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

chore(i18n): refresh de translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-06 09:07:25 +00:00
parent 721f4001d3
commit 8f06ecfd2c
15 changed files with 2183 additions and 2149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/de/channels/line.md
View File

@ -1,32 +1,32 @@
---
read_when:
- Sie möchten OpenClaw mit LINE verbinden
- Sie müssen LINE-Webhook und Zugangsdaten einrichten
- Einrichtung von LINE-Webhook und Zugangsdaten erforderlich
- Sie möchten LINE-spezifische Nachrichtenoptionen
summary: 'LINE Messaging API Plugin: Einrichtung, Konfiguration und Nutzung'
summary: Einrichtung, Konfiguration und Nutzung des LINE Messaging API-Plugins
title: ZEILE
x-i18n:
generated_at: "2026-05-02T20:41:58Z"
generated_at: "2026-05-06T09:03:09Z"
model: gpt-5.5
provider: openai
source_hash: 7a42afc437140185415347f66a8c0b8eaf7d623a6cc08aedf274121e89cdc3b7
source_hash: d9d2880bd27e11b72b51ad8a1e8c9e9d41adb51622edf890554594b90d24cd8d
source_path: channels/line.md
workflow: 16
---
LINE verbindet sich über die LINE Messaging API mit OpenClaw. Das Plugin läuft als Webhook-Empfänger auf dem Gateway und verwendet Ihr Channel-Zugriffstoken + Channel-Secret für die Authentifizierung.
LINE verbindet sich über die LINE Messaging API mit OpenClaw. Das Plugin läuft als Webhook-Empfänger auf dem Gateway und verwendet Ihr Channel Access Token + Channel Secret für die Authentifizierung.
Status: herunterladbares Plugin. Direktnachrichten, Gruppenchats, Medien, Standorte, Flex-Nachrichten, Template-Nachrichten und Schnellantworten werden unterstützt. Reaktionen und Threads werden nicht unterstützt.
Status: herunterladbares Plugin. Direktnachrichten, Gruppenchats, Medien, Standorte, Flex-Nachrichten, Vorlagennachrichten und Schnellantworten werden unterstützt. Reaktionen und Threads werden nicht unterstützt.
## Installieren
## Installation
Installieren Sie LINE, bevor Sie den Channel konfigurieren:
Installieren Sie LINE, bevor Sie den Kanal konfigurieren:
```bash
openclaw plugins install @openclaw/line
```
Lokaler Checkout (wenn aus einem Git-Repo ausgeführt):
Lokaler Checkout (bei Ausführung aus einem Git-Repository):
```bash
openclaw plugins install ./path/to/local/line-plugin
@ -34,10 +34,10 @@ openclaw plugins install ./path/to/local/line-plugin
## Einrichtung
1. Erstellen Sie ein LINE Developers-Konto und öffnen Sie die Console:
1. Erstellen Sie ein LINE Developers-Konto und öffnen Sie die Konsole:
[https://developers.line.biz/console/](https://developers.line.biz/console/)
2. Erstellen (oder wählen) Sie einen Provider und fügen Sie einen **Messaging API**-Channel hinzu.
3. Kopieren Sie das **Channel access token** und das **Channel secret** aus den Channel-Einstellungen.
2. Erstellen (oder wählen) Sie einen Provider und fügen Sie einen **Messaging API**-Kanal hinzu.
3. Kopieren Sie das **Channel access token** und das **Channel secret** aus den Kanaleinstellungen.
4. Aktivieren Sie **Use webhook** in den Messaging API-Einstellungen.
5. Setzen Sie die Webhook-URL auf Ihren Gateway-Endpunkt (HTTPS erforderlich):
@ -45,16 +45,14 @@ openclaw plugins install ./path/to/local/line-plugin
https://gateway-host/line/webhook
```
Das Gateway antwortet auf die Webhook-Verifizierung (GET) und eingehende Ereignisse (POST) von LINE.
Wenn Sie einen benutzerdefinierten Pfad benötigen, setzen Sie `channels.line.webhookPath` oder
`channels.line.accounts.<id>.webhookPath` und aktualisieren Sie die URL entsprechend.
Das Gateway beantwortet die Webhook-Verifizierung (GET) und eingehende Ereignisse (POST) von LINE. Wenn Sie einen benutzerdefinierten Pfad benötigen, setzen Sie `channels.line.webhookPath` oder `channels.line.accounts.<id>.webhookPath` und aktualisieren Sie die URL entsprechend.
Sicherheitshinweis:
- Die LINE-Signaturverifizierung hängt vom Body ab (HMAC über den unverarbeiteten Body), daher wendet OpenClaw vor der Verifizierung strenge Body-Limits vor der Authentifizierung und ein Timeout an.
- OpenClaw verarbeitet Webhook-Ereignisse aus den verifizierten unverarbeiteten Request-Bytes. Durch vorgelagerte Middleware transformierte `req.body`-Werte werden zur Sicherheit der Signaturintegrität ignoriert.
- Die Signaturverifizierung von LINE hängt vom Body ab (HMAC über den Roh-Body), daher wendet OpenClaw vor der Verifizierung strikte Body-Limits vor der Authentifizierung und ein Timeout an.
- OpenClaw verarbeitet Webhook-Ereignisse aus den verifizierten Roh-Request-Bytes. Von vorgelagerter Middleware transformierte `req.body`-Werte werden zur Sicherheit der Signaturintegrität ignoriert.
## Konfigurieren
## Konfiguration
Minimale Konfiguration:
@ -71,6 +69,22 @@ Minimale Konfiguration:
}
```
Konfiguration für öffentliche Direktnachrichten:
```json5
{
channels: {
line: {
enabled: true,
channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
channelSecret: "LINE_CHANNEL_SECRET",
dmPolicy: "open",
allowFrom: ["*"],
},
},
}
```
Umgebungsvariablen (nur Standardkonto):
- `LINE_CHANNEL_ACCESS_TOKEN`
@ -111,8 +125,7 @@ Mehrere Konten:
## Zugriffskontrolle
Direktnachrichten verwenden standardmäßig Pairing. Unbekannte Absender erhalten einen Pairing-Code und ihre
Nachrichten werden ignoriert, bis sie genehmigt wurden.
Direktnachrichten verwenden standardmäßig Pairing. Unbekannte Absender erhalten einen Pairing-Code, und ihre Nachrichten werden ignoriert, bis sie genehmigt wurden.
```bash
openclaw pairing list line
@ -122,13 +135,13 @@ openclaw pairing approve line <CODE>
Allowlisten und Richtlinien:
- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled`
- `channels.line.allowFrom`: allowgelistete LINE-Benutzer-IDs für DMs
- `channels.line.allowFrom`: allowlistete LINE-Benutzer-IDs für Direktnachrichten; `dmPolicy: "open"` erfordert `["*"]`
- `channels.line.groupPolicy`: `allowlist | open | disabled`
- `channels.line.groupAllowFrom`: allowgelistete LINE-Benutzer-IDs für Gruppen
- Überschreibungen pro Gruppe: `channels.line.groups.<groupId>.allowFrom`
- `channels.line.groupAllowFrom`: allowlistete LINE-Benutzer-IDs für Gruppen
- Gruppenbezogene Überschreibungen: `channels.line.groups.<groupId>.allowFrom`
- Laufzeithinweis: Wenn `channels.line` vollständig fehlt, fällt die Laufzeit für Gruppenprüfungen auf `groupPolicy="allowlist"` zurück (auch wenn `channels.defaults.groupPolicy` gesetzt ist).
LINE-IDs unterscheiden Groß- und Kleinschreibung. Gültige IDs sehen so aus:
Bei LINE-IDs wird zwischen Groß- und Kleinschreibung unterschieden. Gültige IDs sehen so aus:
- Benutzer: `U` + 32 Hex-Zeichen
- Gruppe: `C` + 32 Hex-Zeichen
@ -136,15 +149,15 @@ LINE-IDs unterscheiden Groß- und Kleinschreibung. Gültige IDs sehen so aus:
## Nachrichtenverhalten
- Text wird bei 5000 Zeichen in Blöcke aufgeteilt.
- Markdown-Formatierung wird entfernt; Codeblöcke und Tabellen werden nach Möglichkeit in Flex-Karten umgewandelt.
- Streaming-Antworten werden gepuffert; LINE erhält vollständige Blöcke mit einer Ladeanimation, während der Agent arbeitet.
- Mediendownloads werden durch `channels.line.mediaMaxMb` begrenzt (Standard 10).
- Eingehende Medien werden unter `~/.openclaw/media/inbound/` gespeichert, bevor sie an den Agent übergeben werden, entsprechend dem gemeinsamen Medienspeicher, der von anderen gebündelten Channel-Plugins verwendet wird.
- Text wird bei 5000 Zeichen in Teile aufgeteilt.
- Markdown-Formatierung wird entfernt; Codeblöcke und Tabellen werden, wenn möglich, in Flex-Karten umgewandelt.
- Streaming-Antworten werden gepuffert; LINE erhält vollständige Teile mit einer Ladeanimation, während der Agent arbeitet.
- Mediendownloads werden durch `channels.line.mediaMaxMb` begrenzt (Standard: 10).
- Eingehende Medien werden unter `~/.openclaw/media/inbound/` gespeichert, bevor sie an den Agent übergeben werden. Dies entspricht dem gemeinsamen Medienspeicher, der von anderen gebündelten Kanal-Plugins verwendet wird.
## Channel-Daten (Rich Messages)
## Kanaldaten (Rich Messages)
Verwenden Sie `channelData.line`, um Schnellantworten, Standorte, Flex-Karten oder Template-Nachrichten zu senden.
Verwenden Sie `channelData.line`, um Schnellantworten, Standorte, Flex-Karten oder Vorlagennachrichten zu senden.
```json5
{
@ -177,7 +190,7 @@ Verwenden Sie `channelData.line`, um Schnellantworten, Standorte, Flex-Karten od
}
```
Das LINE-Plugin liefert außerdem einen `/card`-Befehl für Flex-Nachrichten-Voreinstellungen mit:
Das LINE-Plugin liefert außerdem einen `/card`-Befehl für Flex-Nachrichten-Presets mit:
```
/card info "Welcome" "Thanks for joining!"
@ -188,32 +201,32 @@ Das LINE-Plugin liefert außerdem einen `/card`-Befehl für Flex-Nachrichten-Vor
LINE unterstützt ACP-Konversationsbindungen (Agent Communication Protocol):
- `/acp spawn <agent> --bind here` bindet den aktuellen LINE-Chat an eine ACP-Sitzung, ohne einen untergeordneten Thread zu erstellen.
- Konfigurierte ACP-Bindungen und aktive konversationsgebundene ACP-Sitzungen funktionieren auf LINE wie in anderen Konversations-Channels.
- Konfigurierte ACP-Bindungen und aktive konversationsgebundene ACP-Sitzungen funktionieren in LINE wie in anderen Konversationskanälen.
Weitere Informationen finden Sie unter [ACP-Agenten](/de/tools/acp-agents).
Details finden Sie unter [ACP-Agenten](/de/tools/acp-agents).
## Ausgehende Medien
Das LINE-Plugin unterstützt das Senden von Bildern, Videos und Audiodateien über das Nachrichten-Tool des Agents. Medien werden über den LINE-spezifischen Zustellpfad mit passender Vorschau- und Tracking-Behandlung gesendet:
Das LINE-Plugin unterstützt das Senden von Bildern, Videos und Audiodateien über das Nachrichten-Tool des Agents. Medien werden über den LINE-spezifischen Zustellpfad mit entsprechender Vorschau- und Tracking-Verarbeitung gesendet:
- **Bilder**: werden als LINE-Bildnachrichten mit automatischer Vorschaugenerierung gesendet.
- **Videos**: werden mit expliziter Vorschau- und Content-Type-Behandlung gesendet.
- **Videos**: werden mit expliziter Vorschau- und Content-Type-Verarbeitung gesendet.
- **Audio**: wird als LINE-Audionachrichten gesendet.
URLs für ausgehende Medien müssen öffentliche HTTPS-URLs sein. OpenClaw validiert den Ziel-Hostnamen, bevor die URL an LINE übergeben wird, und lehnt local loopback-, link-local- und private Netzwerkziele ab.
Generische Mediensendungen fallen auf die vorhandene Nur-Bild-Route zurück, wenn kein LINE-spezifischer Pfad verfügbar ist.
Generische Mediensendungen fallen auf die vorhandene reine Bildroute zurück, wenn kein LINE-spezifischer Pfad verfügbar ist.
## Fehlerbehebung
- **Webhook-Verifizierung schlägt fehl:** Stellen Sie sicher, dass die Webhook-URL HTTPS verwendet und das `channelSecret` mit der LINE-Konsole übereinstimmt.
- **Keine eingehenden Ereignisse:** Bestätigen Sie, dass der Webhook-Pfad mit `channels.line.webhookPath` übereinstimmt und dass das Gateway von LINE erreichbar ist.
- **Mediendownload-Fehler:** Erhöhen Sie `channels.line.mediaMaxMb`, wenn Medien das Standardlimit überschreiten.
- **Webhook-Verifizierung schlägt fehl:** Stellen Sie sicher, dass die Webhook-URL HTTPS verwendet und `channelSecret` mit der LINE-Konsole übereinstimmt.
- **Keine eingehenden Ereignisse:** Bestätigen Sie, dass der Webhook-Pfad `channels.line.webhookPath` entspricht und dass das Gateway von LINE erreichbar ist.
- **Fehler beim Mediendownload:** Erhöhen Sie `channels.line.mediaMaxMb`, wenn Medien das Standardlimit überschreiten.
## Verwandte Themen
- [Channels-Übersicht](/de/channels) — alle unterstützten Channels
- [Kanalübersicht](/de/channels) — alle unterstützten Kanäle
- [Pairing](/de/channels/pairing) — DM-Authentifizierung und Pairing-Ablauf
- [Gruppen](/de/channels/groups) — Gruppenchat-Verhalten und Mention-Gating
- [Channel-Routing](/de/channels/channel-routing) — Sitzungsrouting für Nachrichten
- [Kanalrouting](/de/channels/channel-routing) — Sitzungsrouting für Nachrichten
- [Sicherheit](/de/gateway/security) — Zugriffsmodell und Härtung

388
docs/de/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- Sie müssen verstehen, warum ein CI-Job ausgeführt wurde oder nicht
- Sie debuggen eine fehlgeschlagene GitHub-Actions-Prüfung
- Sie koordinieren einen Release-Validierungslauf oder eine erneute Ausführung
- Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht
- Sie debuggen eine fehlgeschlagene GitHub Actions-Prüfung
- Sie koordinieren einen Release-Validierungslauf oder dessen Wiederholung
- Sie ändern den ClawSweeper-Dispatch oder die Weiterleitung von GitHub-Aktivitäten
summary: CI-Auftragsgraph, Bereichs-Gates, Release-Umbrellas und lokale Befehlsäquivalente
summary: CI-Job-Graph, Bereichsprüfungen, Release-Sammelprüfungen und lokale Befehlsäquivalente
title: CI-Pipeline
x-i18n:
generated_at: "2026-05-05T06:16:27Z"
generated_at: "2026-05-06T09:03:23Z"
model: gpt-5.5
provider: openai
source_hash: 31fe6704e18f9efc519a1a73fc3aa8ae3909d6a27553874eb477e73979a94af2
source_hash: 189f717fac369d6374102612308c73705f19eca9baca81b24f052dbd5357e15f
source_path: ci.md
workflow: 16
---
OpenClaw CI läuft bei jedem Push auf `main` und bei jedem Pull Request. Der `preflight`-Job klassifiziert den Diff und schaltet teure Lanes ab, wenn sich nur nicht verwandte Bereiche geändert haben. Manuelle `workflow_dispatch`-Läufe umgehen Smart Scoping absichtlich und fächern für Release-Kandidaten und breite Validierung den vollständigen Graphen auf. Android-Lanes bleiben über `include_android` optional. Release-exklusive Plugin-Abdeckung liegt im separaten [`Plugin Prerelease`](#plugin-prerelease)-Workflow und läuft nur über [`Full Release Validation`](#full-release-validation) oder einen expliziten manuellen Dispatch.
OpenClaw-CI läuft bei jedem Push auf `main` und bei jedem Pull Request. Der `preflight`-Job klassifiziert den Diff und deaktiviert teure Lanes, wenn sich nur nicht zugehörige Bereiche geändert haben. Manuelle `workflow_dispatch`-Läufe umgehen bewusst das intelligente Scoping und fächern für Release-Kandidaten und breite Validierung den vollständigen Graphen auf. Android-Lanes bleiben über `include_android` optional. Release-spezifische Plugin-Abdeckung befindet sich im separaten Workflow [`Plugin-Vorabversion`](#plugin-prerelease) und läuft nur aus [`Vollständige Release-Validierung`](#full-release-validation) heraus oder durch einen expliziten manuellen Dispatch.
## Pipeline-Übersicht
| Job | Zweck | Wann er läuft |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Extensions und erstellt das CI-Manifest | Immer bei Nicht-Entwurfs-Pushes und PRs |
| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Entwurfs-Pushes und PRs |
| `security-dependency-audit` | Abhängigkeitsfreier Audit des Produktions-Lockfiles gegen npm-Advisories | Immer bei Nicht-Entwurfs-Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheitsjobs | Immer bei Nicht-Entwurfs-Pushes und PRs |
| `check-dependencies` | Reiner Produktions-Knip-Durchlauf für Abhängigkeiten plus Allowlist-Guard für ungenutzte Dateien | Node-relevante Änderungen |
| `build-artifacts` | Erstellt `dist/`, Control UI, Prüfungen gebauter Artefakte und wiederverwendbare nachgelagerte Artefakte | Node-relevante Änderungen |
| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie Bundled-/Plugin-Contract-/Protocol-Prüfungen | 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-, Bundled-, Contract- und Extension-Lanes | Node-relevante Änderungen |
| `check` | Geshardetes Äquivalent zum lokalen Haupt-Gate: Produktions-Typen, Lint, Guards, Testtypen und Strict-Smoke | Node-relevante Änderungen |
| `check-additional` | Architektur, geshardete Boundary-/Prompt-Drift, Extension-Guards, Paketgrenze und Gateway-Watch | Node-relevante Änderungen |
| `build-smoke` | Smoke-Tests für gebaute CLI und Startup-Memory-Smoke | Node-relevante Änderungen |
| `checks` | Verifier für gebaute Artefakt-Channel-Tests | Node-relevante Änderungen |
| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases |
| `check-docs` | Docs-Formatierung, Lint und Broken-Link-Prüfungen | Docs geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Für Python-Skills relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus Regressionen für gemeinsame Runtime-Import-Spezifizierer | Windows-relevante Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsamen gebauten Artefakten | macOS-relevante Änderungen |
| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen |
| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Android-relevante Änderungen |
| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Erfolg der Main-CI oder manueller Dispatch |
| `openclaw-performance` | Tägliche/bedarfsgesteuerte Kova-Runtime-Performance-Berichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplant und manueller Dispatch |
| Job | Zweck | Wann er läuft |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Erweiterungen und erstellt das CI-Manifest | Immer bei Nicht-Draft-Pushes und PRs |
| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Draft-Pushes und PRs |
| `security-dependency-audit` | Dependency-freier Audit des Produktions-Lockfiles gegen npm-Advisories | Immer bei Nicht-Draft-Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheitsjobs | Immer bei Nicht-Draft-Pushes und PRs |
| `check-dependencies` | Reiner Produktions-Knip-Dependency-Durchlauf 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-Contract-/Protokollprüfungen | Node-relevante Änderungen |
| `checks-fast-contracts-channels` | Gesplittete Channel-Contract-Prüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen |
| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, gebündelte, Contract- und Erweiterungs-Lanes | Node-relevante Änderungen |
| `check` | Gesplittetes Äquivalent des lokalen Haupt-Gates: Produktionstypen, Lint, Guards, Testtypen und strikter Smoke-Test | Node-relevante Änderungen |
| `check-additional` | Architektur, gesplitteter Boundary-/Prompt-Drift, Erweiterungs-Guards, Package-Boundary und Gateway Watch | Node-relevante Änderungen |
| `build-smoke` | Smoke-Tests für gebaute CLI und Startup-Memory-Smoke | Node-relevante Änderungen |
| `checks` | Verifier 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` | Docs-Formatierung, Lint und Broken-Link-Prüfungen | Docs geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus Regressionen bei gemeinsamen Runtime-Import-Spezifizierern | 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 | Erfolgreiche Haupt-CI oder manueller Dispatch |
| `openclaw-performance` | Tägliche/bedarfsbasierte Kova-Runtime-Performance-Berichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplanter und manueller Dispatch |
## Fail-Fast-Reihenfolge
1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die `docs-scope`- und `changed-scope`-Logik 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` überlappt sich mit den schnellen Linux-Lanes, damit nachgelagerte 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 ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch der neueste Lauf für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, damit sie normale Shard-Fehler weiterhin melden, sich aber nicht mehr einreihen, nachdem der gesamte Workflow bereits ersetzt wurde. Der automatische CI-Concurrency-Schlüssel ist versioniert (`CI-v7-*`), damit ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann. Manuelle Full-Suite-Läufe verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab.
GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf denselben PR- oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch der neueste Lauf für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, damit sie normale Shard-Fehler weiterhin melden, aber nicht mehr eingereiht werden, nachdem der gesamte Workflow bereits ersetzt wurde. Der automatische CI-Concurrency-Schlüssel ist versioniert (`CI-v7-*`), sodass ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann. Manuelle Full-Suite-Läufe verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab.
## Scope und Routing
Die Scope-Logik liegt in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Changed-Scope-Erkennung und lässt das Preflight-Manifest so agieren, als hätte sich jeder gescopte Bereich geändert.
Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Changed-Scope-Erkennung und lässt das Preflight-Manifest so handeln, als hätte sich jeder gescopte Bereich geändert.
- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen beschränkt.
- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und enge Plugin-Contract-Helper-/Test-Routing-Änderungen** verwenden einen schnellen Node-only-Manifest-Pfad: `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 Routing- oder Helper-Oberflächen begrenzt ist, die die schnelle Aufgabe direkt ausführt.
- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helper, Paketmanager-Konfiguration und die CI-Workflow-Oberflächen beschränkt, die diese Lane ausführen; nicht verwandte Source-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes.
- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen gescopet.
- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und enge Plugin-Contract-Helper-/Test-Routing-Änderungen** verwenden einen schnellen Node-only-Manifestpfad: `preflight`, Sicherheit und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Contracts, vollständige Core-Shards, gebündelte 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 ausübt.
- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helper, Package-Manager-Konfiguration und die CI-Workflow-Oberflächen gescopet, die diese Lane ausführen; nicht zugehörige Quell-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes.
Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Contracts laufen als drei gewichtete Shards, Core-Unit-Fast-/Support-Lanes laufen separat, Core-Runtime-Infrastruktur ist zwischen State- und Process-/Config-Shards aufgeteilt, Auto-Reply läuft als ausbalancierte Worker (wobei der Reply-Subtree in Agent-Runner-, Dispatch- und Commands-/State-Routing-Shards aufgeteilt ist), und Agentic-Gateway-/Server-Konfigurationen sind über Chat-/Auth-/Model-/HTTP-Plugin-/Runtime-/Startup-Lanes aufgeteilt, 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; die Boundary-Guard-Liste ist über vier Matrix-Shards gestreift, wobei jeder ausgewählte unabhängige Guards parallel ausführt und Timings pro Prüfung ausgibt, einschließlich `pnpm prompt:snapshots:check`, damit Prompt-Drift im Codex-Runtime-Happy-Path an den PR gebunden ist, der ihn verursacht hat. Gateway-Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden.
Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Contracts laufen als drei gewichtete Shards, schnelle/supportbezogene Core-Unit-Lanes laufen separat, Core-Runtime-Infrastruktur ist zwischen State- und Process-/Config-Shards aufgeteilt, Auto-Reply läuft als ausbalancierte Worker (wobei der Reply-Subtree in Agent-Runner-, Dispatch- und Commands-/State-Routing-Shards aufgeteilt ist), und agentische Gateway-/Server-Konfigurationen sind über Chat-/Auth-/Model-/HTTP-Plugin-/Runtime-/Startup-Lanes aufgeteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Media- 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 vollständige Konfiguration von einem gefilterten Shard unterscheiden kann. `check-additional` hält Package-Boundary-Compile-/Canary-Arbeit zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; die Boundary-Guard-Liste ist über vier Matrix-Shards gestreift, wobei jeder ausgewählte unabhängige Guards parallel ausführt und Timings pro Prüfung ausgibt, einschließlich `pnpm prompt:snapshots:check`, damit Prompt-Drift im Codex-Runtime-Happy-Path an den PR gebunden ist, der ihn verursacht hat. Gateway Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden.
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 weiterhin mit den SMS-/Call-Log-`BuildConfig`-Flags, vermeidet aber bei jedem Android-relevanten Push einen doppelten Debug-APK-Paketierungsjob.
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, vermeidet aber bei jedem Android-relevanten Push einen doppelten Debug-APK-Packaging-Job.
Der `check-dependencies`-Shard führt `pnpm deadcode:dependencies` (einen reinen Produktions-Knip-Durchlauf für Abhängigkeiten, 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, nicht geprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Package-Bridge-Oberflächen erhalten bleiben, die Knip statisch nicht auflösen kann.
Der `check-dependencies`-Shard führt `pnpm deadcode:dependencies` (einen reinen Produktions-Knip-Dependency-Durchlauf, der an die neueste Knip-Version gepinnt ist, wobei pnpm's Mindest-Release-Alter für die `dlx`-Installation deaktiviert ist) und `pnpm deadcode:unused-files` aus, das Knips Produktionsfunde ungenutzter Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Unused-File-Guard schlägt fehl, wenn ein PR eine neue, nicht geprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Package-Bridge-Oberflächen erhalten bleiben, die Knip nicht statisch auflösen kann.
## Weiterleitung von ClawSweeper-Aktivität
## 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 aus `CLAWSWEEPER_APP_PRIVATE_KEY` ein GitHub-App-Token und dispatcht dann kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`.
Der Workflow hat vier Lanes:
- `clawsweeper_item` für exakte Issue- und Pull-Request-Review-Anfragen;
- `clawsweeper_item` für genaue Review-Anfragen zu Issues und Pull Requests;
- `clawsweeper_comment` für explizite ClawSweeper-Befehle in Issue-Kommentaren;
- `clawsweeper_commit_review` für Review-Anfragen auf Commit-Ebene bei `main`-Pushes;
- `github_activity` für allgemeine GitHub-Aktivität, die der ClawSweeper-Agent inspizieren kann.
- `github_activity` für allgemeine GitHub-Aktivität, die der ClawSweeper-Agent prüfen kann.
Die `github_activity`-Lane leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Akteur, Repository, Item-Nummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet 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 sendet.
Die `github_activity`-Lane leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Akteur, Repository, Item-Nummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet bewusst die Weiterleitung des vollständigen Webhook-Bodys. Der empfangende Workflow in `openclaw/clawsweeper` ist `.github/workflows/github-activity.yml`, der das normalisierte Ereignis an den OpenClaw-Gateway-Hook für den ClawSweeper-Agent postet.
Allgemeine Aktivität ist Beobachtung, keine standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann in `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder betrieblich nützlich ist. Routinemäßige Öffnungen, Bearbeitungen, Bot-Rauschen, doppelte Webhook-Störungen und normaler Review-Traffic sollten zu `NO_REPLY` führen.
Allgemeine Aktivität ist Beobachtung, nicht standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann in `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder betrieblich nützlich ist. Routinemäßiges Öffnen, Bearbeitungen, Bot-Fluktuation, doppelte Webhook-Geräusche 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-Texte, 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 die normale CI aus, erzwingen aber jede nicht auf Android beschränkte Lane: Linux-Node-Shards, gebündelte Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Dokumentationsprüfungen, Python-Skills, Windows, macOS und Control-UI-i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; der vollständige Release-Umbrella aktiviert Android, indem er `include_android=true` übergibt. 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 `Plugin Prerelease`-Workflow mit aktivierter Release-Validation-Gate auslöst.
Manuelle CI-Ausführungen verwenden denselben Job-Graphen wie normale CI, 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, Docs-Prüfungen, Python-Skills, Windows, macOS und Control-UI-i18n. Eigenständige manuelle CI-Ausführungen 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 Workflow `Plugin Prerelease` mit aktiviertem Release-Validation-Gate auslöst.
Manuelle Läufe verwenden eine eindeutige Nebenläufigkeitsgruppe, 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` ermöglicht 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 Ausführungen verwenden eine eindeutige Concurrency-Gruppe, damit eine vollständige Release-Candidate-Suite nicht durch eine andere Push- oder PR-Ausführung auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` erlaubt 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.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -98,15 +98,15 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Runner
| Runner | Jobs |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, schnelle Sicherheitsjobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Vertrags-/gebündelte Prüfungen, geshardete Channel-Vertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregate, Node-Test-Aggregatprüfer, 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 kommen kann |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, leichtere 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-empfindlich genug, dass 8 vCPU mehr kosteten, als sie einsparten); Install-Smoke-Docker-Builds (die Warteschlangenzeit mit 32 vCPU 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-/Bundled-Prüfungen, geshardete Channel-Contract-Prüfungen, `check`-Shards außer Lint, `check-additional`-Aggregate, Node-Test-Aggregatverifizierer, Docs-Prüfungen, Python-Skills, workflow-sanity, labeler, auto-response; install-smoke-Preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Queue 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, gebündelte Plugin-Test-Shards, `check-additional`-Shards, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (CPU-sensibel genug, dass 8 vCPU mehr kosteten, als sie einsparten); install-smoke-Docker-Builds (32-vCPU-Queue-Zeit kostete mehr, als sie einsparten) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
## Lokale Entsprechungen
@ -135,9 +135,9 @@ 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-Leistung
`OpenClaw Performance` ist der Performance-Workflow für Produkt und Runtime. Er läuft täglich auf `main` und kann manuell ausgelöst werden:
`OpenClaw Performance` ist der Produkt-/Runtime-Performance-Workflow. Er läuft täglich auf `main` und kann manuell ausgelöst werden:
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@ -145,30 +145,30 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
```
Manueller Dispatch benchmarked normalerweise den Workflow-Ref. Setzen Sie `target_ref`, um ein Release-Tag oder einen anderen Branch mit der aktuellen Workflow-Implementierung zu benchmarken. Veröffentlichte Berichtspfade und Latest-Zeiger werden nach dem getesteten Ref geschlüsselt, und jede `index.md` erfasst den getesteten Ref/SHA, Workflow-Ref/SHA, Kova-Ref, Profil, Lane-Auth-Modus, Modell, Wiederholungsanzahl und Szenariofilter.
Ein manueller Dispatch benchmarked normalerweise den Workflow-Ref. Setzen Sie `target_ref`, um ein Release-Tag oder einen anderen Branch mit der aktuellen Workflow-Implementierung zu benchmarken. Veröffentlichte Berichtspfade und Latest-Pointer werden nach dem getesteten Ref geschlüsselt, und jede `index.md` zeichnet den getesteten Ref/SHA, Workflow-Ref/SHA, Kova-Ref, Profil, Lane-Auth-Modus, Modell, Wiederholungsanzahl und Szenariofilter auf.
Der Workflow installiert OCM aus einem gepinnten Release und Kova aus `openclaw/Kova` mit der gepinnten Eingabe `kova_ref` und führt dann drei Lanes aus:
- `mock-provider`: Kova-Diagnoseszenarien gegen eine lokal gebaute Runtime mit deterministischer gefälschter OpenAI-kompatibler Authentifizierung.
- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Hotspots beim Start, Gateway und Agent-Turn.
- `mock-provider`: Kova-Diagnoseszenarien gegen eine Runtime aus lokalem Build mit deterministischer gefälschter OpenAI-kompatibler Authentifizierung.
- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Startup-, Gateway- und Agent-Turn-Hotspots.
- `live-gpt54`: ein echter OpenAI-`openai/gpt-5.4`-Agent-Turn, der übersprungen wird, wenn `OPENAI_API_KEY` nicht verfügbar ist.
Die Mock-Provider-Lane führt nach dem Kova-Durchlauf auch OpenClaw-native Quell-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 Quell-Probes liegt unter `source/index.md` im Berichtsbundle, mit Roh-JSON daneben.
Die mock-provider-Lane führt nach dem Kova-Durchlauf außerdem OpenClaw-native Source-Probes aus: Gateway-Boot-Timing und Speicher über Standard-, Hook- und 50-Plugin-Startup-Fälle hinweg; wiederholte Mock-OpenAI-`channel-chat-baseline`-Hello-Loops; und CLI-Startup-Befehle gegen das gestartete Gateway. Die Markdown-Zusammenfassung der Source-Probe liegt unter `source/index.md` im Berichtsbundle, mit Roh-JSON daneben.
Jede Lane lädt GitHub-Artefakte hoch. Wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist, committet der Workflow außerdem `report.json`, `report.md`, Bundles, `index.md` und Quell-Probe-Artefakte nach `openclaw/clawgrit-reports` unter `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Der aktuelle Zeiger des getesteten Refs wird als `openclaw-performance/<tested-ref>/latest-<lane>.json` geschrieben.
Jede Lane lädt GitHub-Artefakte hoch. Wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist, committet der Workflow außerdem `report.json`, `report.md`, Bundles, `index.md` und Source-Probe-Artefakte nach `openclaw/clawgrit-reports` unter `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Der aktuelle Pointer für den getesteten Ref wird als `openclaw-performance/<tested-ref>/latest-<lane>.json` geschrieben.
## Vollständige Release-Validierung
`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, ein Tag oder einen vollständigen Commit-SHA, löst den manuellen `CI`-Workflow mit diesem Ziel aus, löst `Plugin Prerelease` für nur im Release benötigte Plugin-/Paket-/Statik-/Docker-Nachweise aus und löst `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, paketübergreifende Cross-OS-Prüfungen, QA-Lab-Parität, Matrix- und Telegram-Lanes aus. Stabile/Standardläufe belassen umfassende Live-/E2E- und Docker-Release-Pfad-Abdeckung hinter `run_release_soak=true`; `release_profile=full` erzwingt diese Soak-Abdeckung, damit breite Advisory-Validierung breit bleibt. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus den Release-Prüfungen aus. Nach der Veröffentlichung übergeben Sie `npm_telegram_package_spec`, um dieselbe Telegram-Paket-Lane gegen das veröffentlichte npm-Paket erneut auszuführen.
`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, löst den manuellen Workflow `CI` mit diesem Ziel aus, löst `Plugin Prerelease` für nur releasebezogene Plugin-/Package-/statische/Docker-Nachweise aus und löst `OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Cross-OS-Package-Prüfungen, QA-Lab-Parität, Matrix- und Telegram-Lanes aus. Stabile/standardmäßige Ausführungen halten erschöpfende Live-/E2E- und Docker-Release-Path-Abdeckung hinter `run_release_soak=true`; `release_profile=full` erzwingt diese Soak-Abdeckung, damit breite Advisory-Validierung breit bleibt. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus den Release-Prüfungen aus. Übergeben Sie nach der Veröffentlichung `npm_telegram_package_spec`, um dieselbe Telegram-Package-Lane gegen das veröffentlichte npm-Package 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.
Stage-Matrix, exakten Workflow-Job-Namen, Profilunterschiede, Artefakte und
gezielten Rerun-Handles.
`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`,
löst `Plugin NPM Release` für alle veröffentlichbaren Plugin-Pakete aus, löst
löst `Plugin NPM Release` für alle veröffentlichbaren Plugin-Packages aus, löst
`Plugin ClawHub Release` für denselben Release-SHA aus und löst erst dann
`OpenClaw NPM Release` mit der gespeicherten `preflight_run_id` aus.
@ -180,7 +180,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Für den Nachweis eines gepinnten Commits auf einem schnell fortschreitenden Branch verwenden Sie den Helper statt
Für gepinnten Commit-Nachweis auf einem schnelllebigen Branch verwenden Sie den Helper statt
`gh workflow run ... --ref main -f ref=<sha>`:
```bash
@ -189,36 +189,36 @@ pnpm ci:full-release --sha <full-sha>
GitHub-Workflow-Dispatch-Refs müssen Branches oder Tags sein, keine rohen Commit-SHAs. Der
Helper pusht einen temporären Branch `release-ci/<sha>-...` am Ziel-SHA,
löst `Full Release Validation` von diesem gepinnten Ref aus, verifiziert, dass jedes untergeordnete
Workflow-`headSha` dem Ziel entspricht, und löscht den temporären Branch, wenn der
Lauf abgeschlossen ist. Der Umbrella-Verifizierer schlägt außerdem fehl, wenn ein untergeordneter Workflow mit einem
anderen SHA lief.
löst `Full Release Validation` von diesem gepinnten Ref aus, verifiziert, dass jeder untergeordnete
Workflow-`headSha` dem Ziel entspricht, und löscht den temporären Branch, wenn die
Ausführung abgeschlossen ist. Der Umbrella-Verifizierer schlägt außerdem fehl, wenn ein untergeordneter Workflow mit einem
anderen SHA ausgeführt wurde.
`release_profile` steuert die an Release-Prüfungen übergebene Live-/Provider-Breite. Die
`release_profile` steuert die Live-/Provider-Breite, die an Release-Prüfungen übergeben wird. Die
manuellen Release-Workflows verwenden standardmäßig `stable`; verwenden Sie `full` nur, wenn Sie
bewusst die breite informative Provider-/Medienmatrix wünschen. `run_release_soak`
absichtlich die breite, beratende Provider-/Medienmatrix möchten. `run_release_soak`
steuert, ob stabile/standardmäßige Release-Prüfungen den umfassenden Live-/E2E- und
Docker-Release-Pfad-Soak ausführen; `full` erzwingt den Soak.
Docker-Dauertest für den Release-Pfad ausführen; `full` erzwingt den Dauertest.
- `minimum` behält die schnellsten release-kritischen OpenAI-/Core-Lanes.
- `stable` fügt den stabilen Provider-/Backend-Satz hinzu.
- `full` führt die breite informative Provider-/Medienmatrix aus.
- `minimum` behält die schnellsten OpenAI-/Core-Release-kritischen Lanes bei.
- `stable` fügt das stabile Provider-/Backend-Set hinzu.
- `full` führt die breite, beratende Provider-/Medienmatrix aus.
Der Umbrella zeichnet die ausgelösten untergeordneten Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Ergebnisse der untergeordneten Runs erneut und hängt Tabellen der langsamsten Jobs für jeden untergeordneten Run an. Wenn ein untergeordneter Workflow erneut ausgeführt wird und grün wird, führen Sie nur den übergeordneten Verifier-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren.
Der Umbrella zeichnet die IDs der ausgelösten untergeordneten Runs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Ergebnisse der untergeordneten Runs erneut und hängt Tabellen der langsamsten Jobs für jeden untergeordneten Run an. Wenn ein untergeordneter Workflow erneut ausgeführt wird und grün wird, führen Sie nur den übergeordneten Verifier-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren.
Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release Candidate, `ci` nur für das normale untergeordnete vollständige CI, `plugin-prerelease` nur für das untergeordnete Plugin-Prerelease, `release-checks` für jedes untergeordnete Release, oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` im Umbrella. Dadurch bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einem gezielten Fix begrenzt. Für eine fehlgeschlagene Cross-OS-Lane kombinieren Sie `rerun_group=cross-os` mit `cross_os_suite_filter`, zum Beispiel `windows/packaged-upgrade`; lange Cross-OS-Befehle geben Heartbeat-Zeilen aus, und packaged-upgrade-Zusammenfassungen enthalten Timings pro Phase. QA-Release-Check-Lanes sind informativ, daher warnen reine QA-Fehler, blockieren den Release-Check-Verifier aber nicht.
Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release-Kandidaten, `ci` nur für das normale untergeordnete Full-CI, `plugin-prerelease` nur für das untergeordnete Plugin-Prerelease, `release-checks` für jedes untergeordnete Release, oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` auf dem Umbrella. Dadurch bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einem fokussierten Fix begrenzt. Für eine einzelne fehlgeschlagene Cross-OS-Lane kombinieren Sie `rerun_group=cross-os` mit `cross_os_suite_filter`, zum Beispiel `windows/packaged-upgrade`; lange Cross-OS-Befehle geben Heartbeat-Zeilen aus, und Packaged-Upgrade-Zusammenfassungen enthalten Timings pro Phase. QA-Release-Check-Lanes sind beratend, daher warnen reine QA-Fehler, blockieren den Release-Check-Verifier aber nicht.
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die ausgewählte Ref einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann an Cross-OS-Prüfungen und Package Acceptance sowie an den Live-/E2E-Release-Pfad-Docker-Workflow, wenn Soak-Abdeckung ausgeführt wird. Dadurch bleiben die Paket-Bytes über Release-Boxen hinweg konsistent und dasselbe Candidate-Paket wird nicht in mehreren untergeordneten Jobs neu gepackt.
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die ausgewählte Ref einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann an Cross-OS-Prüfungen und Package Acceptance sowie an den Live-/E2E-Docker-Workflow für den Release-Pfad, wenn die Dauertest-Abdeckung läuft. Dadurch bleiben die Paketbytes über Release-Boxen hinweg konsistent, und derselbe Kandidat muss nicht in mehreren untergeordneten Jobs neu gepackt werden.
Doppelte `Full Release Validation`-Runs für `ref=main` und `rerun_group=all`
ersetzen den älteren Umbrella. Der übergeordnete Monitor bricht jeden untergeordneten Workflow ab, den
er bereits ausgelöst hat, wenn der übergeordnete abgebrochen wird, sodass eine neuere main-Validierung
nicht hinter einem veralteten zweistündigen Release-Check-Run wartet. Release-Branch-/Tag-
Validierung und gezielte Rerun-Gruppen behalten `cancel-in-progress: false` bei.
er bereits ausgelöst hat, wenn der übergeordnete Run abgebrochen wird, sodass neuere Main-Validierung
nicht hinter einem veralteten zweistündigen Release-Check-Run warten muss. Release-Branch-/Tag-
Validierung und fokussierte Rerun-Gruppen behalten `cancel-in-progress: false` bei.
## Live- und E2E-Shards
Das untergeordnete Release-Live-/E2E behält die 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:
Das untergeordnete Release-Live-/E2E 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:
- `native-live-src-agents`
- `native-live-src-gateway-core`
@ -234,29 +234,29 @@ Das untergeordnete Release-Live-/E2E behält die breite native `pnpm test:live`-
Dadurch bleibt dieselbe Dateiabdeckung erhalten, während langsame Live-Provider-Fehler leichter erneut ausgeführt und diagnostiziert werden können. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle einmalige Reruns gültig.
Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut vom Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medienjobs prüfen die Binärdateien vor dem Setup nur noch. Lassen Sie Docker-gestützte Live-Suiten auf normalen Blacksmith-Runnern; Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten.
Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut vom Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medienjobs prüfen vor dem Setup nur die Binärdateien. Lassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern; Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten.
Docker-gestützte Live-Modell-/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:<sha>` pro ausgewähltem Commit. Der Live-Release-Workflow baut und veröffentlicht dieses Image einmal, dann laufen die Docker-Live-Modell-, Provider-geshardeten Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards tragen explizite Time-out-Grenzen auf Skriptebene unterhalb des Workflow-Job-Time-outs, sodass ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit mit doppelten Image-Builds.
Docker-gestützte Live-Modell-/Backend-Shards verwenden pro ausgewähltem Commit ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:<sha>`. Der Live-Release-Workflow baut und pusht dieses Image einmal, danach laufen die Docker-Live-Modell-, Provider-geshardeten Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards tragen explizite Timeout-Obergrenzen auf Skriptebene unterhalb des Workflow-Job-Timeouts, damit ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit mit doppelten Image-Builds.
## Paketakzeptanz
## Package Acceptance
Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Sie unterscheidet sich von normalem CI: Normales CI validiert den Quellbaum, während Package Acceptance ein einzelnes Tarball über denselben Docker-E2E-Harness validiert, den Benutzer nach der Installation oder einem Update ausüben.
Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Es unterscheidet sich von normalem CI: Normales 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 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-Schrittzusammenfassung aus.
2. `docker_acceptance` ruft `openclaw-live-and-e2e-checks-reusable.yml` mit `ref=workflow_ref` und `package_artifact_name=package-under-test` auf. Der wiederverwendbare Workflow lädt dieses Artefakt herunter, validiert das Tarball-Inventar, bereitet bei Bedarf Paket-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 Paketauflösung, Docker-Akzeptanz oder die optionale Telegram-Lane fehlgeschlagen sind.
1. `resolve_package` checkt `workflow_ref` aus, löst einen Paketkandidaten auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Ref, Paket-Ref, Version, SHA-256 und Profil in der GitHub-Schrittzusammenfassung aus.
2. `docker_acceptance` ruft `openclaw-live-and-e2e-checks-reusable.yml` mit `ref=workflow_ref` und `package_artifact_name=package-under-test` auf. Der wiederverwendbare Workflow lädt dieses Artefakt herunter, validiert 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 gemeinsame Images einmal vor und fächert diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten auf.
3. `package_telegram` ruft optional `NPM Telegram Beta E2E` auf. Es läuft, wenn `telegram_mode` nicht `none` ist, und installiert dasselbe Artefakt `package-under-test`, wenn Package Acceptance eines aufgelöst hat; ein eigenständiger Telegram-Dispatch kann weiterhin eine veröffentlichte npm-Spezifikation installieren.
4. `summary` lässt den Workflow fehlschlagen, wenn Paketauflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist.
### Candidate-Quellen
### Kandidatenquellen
- `source=npm` akzeptiert nur `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für veröffentlichte Prerelease-/Stable-Akzeptanz.
- `source=ref` packt einen vertrauenswürdigen Branch, Tag oder vollständigen Commit-SHA aus `package_ref`. Der Resolver holt OpenClaw-Branches/-Tags, verifiziert, dass der ausgewählte Commit aus der Branch-Historie des Repositorys oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten 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 die Acceptance veröffentlichter Prerelease-/Stable-Versionen.
- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, verifiziert, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten in einem detached Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`.
- `source=url` lädt ein HTTPS-`.tgz` herunter; `package_sha256` ist erforderlich.
- `source=artifact` lädt ein `.tgz` aus `artifact_run_id` und `artifact_name` herunter; `package_sha256` ist optional, sollte aber für extern geteilte Artefakte angegeben werden.
- `source=artifact` lädt ein `.tgz` von `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 Quell-Commit, der gepackt wird, wenn `source=ref` gilt. Dadurch kann der aktuelle Test-Harness ältere vertrauenswürdige Quell-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
@ -266,25 +266,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, sodass die Validierung veröffentlichter Pakete nicht von der Live-Verfügbarkeit von ClawHub abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der 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 Richtlinie für Update- und Plugin-Tests, einschließlich lokaler Befehle,
Docker-Lanes, Package Acceptance-Eingaben, Release-Standards und Fehlertriage,
Docker-Lanes, Package-Acceptance-Eingaben, Release-Standards und Fehlertriage,
finden Sie unter [Updates und Plugins testen](/de/help/testing-updates-plugins).
Release-Prüfungen rufen Package Acceptance mit `source=artifact`, dem vorbereiteten Release-Paketartefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` und `telegram_mode=mock-openai` auf. Dadurch bleiben Paketmigration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Reparatur konfigurierter Plugin-Installationen, 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-Prüfungen decken weiterhin OS-spezifisches Onboarding, Installer- und Plattformverhalten ab; die Produktvalidierung für Paket/Update sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert im blockierenden Release-Pfad pro Run eine veröffentlichte Paketbaseline. 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. Full Release Validation mit `run_release_soak=true` oder `release_profile=full` setzt `published_upgrade_survivor_baselines='last-stable-4 2026.4.23 2026.5.2 2026.4.15'` und `published_upgrade_survivor_scenarios=reported-issues`, um auf die vier neuesten stabilen npm-Releases plus festgelegte Grenz-Releases für Plugin-Kompatibilität und issue-förmige Fixtures für Feishu-Konfiguration, beibehaltene Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeitswurzeln zu erweitern. Multi-Baseline-Auswahlen von published-upgrade survivor werden nach Baseline in separate gezielte Docker-Runner-Jobs geshardet. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn die Frage umfassende Bereinigung veröffentlichter Updates ist, nicht normale Full-Release-CI-Breite. Lokale aggregierte Runs können exakte Paketspezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` eine einzelne Lane wie `openclaw@2026.4.15` beibehalten oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenariomatrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebauten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft `/healthz`, `/readyz` sowie den RPC-Status nach dem Start des Gateway. Die frischen Windows-Packaged- und Installer-Lanes prüfen außerdem, dass ein installiertes Paket ein Browser-Control-Override von einem rohen absoluten Windows-Pfad importieren kann. Der OpenAI-Cross-OS-Agent-Turn-Smoke verwendet standardmäßig `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn gesetzt, andernfalls `openai/gpt-5.4`, sodass der Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleibt und GPT-4.x-Standards vermieden werden.
Release-Prüfungen rufen Package Acceptance mit `source=artifact`, dem vorbereiteten Release-Paketartefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` und `telegram_mode=mock-openai` auf. Dadurch bleiben Paketmigration, Update, Cleanup veralteter Plugin-Abhängigkeiten, Reparatur konfigurierter Plugin-Installationen, Offline-Plugin, Plugin-Update und Telegram-Nachweis auf demselben aufgelösten Paket-Tarball. Setzen Sie `package_acceptance_package_spec` in Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Paket statt gegen das aus dem SHA gebaute Artefakt auszuführen. Cross-OS-Release-Prüfungen decken weiterhin OS-spezifisches Onboarding, Installer- und Plattformverhalten ab; Produktvalidierung für Paket/Update sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert im blockierenden Release-Pfad pro Run eine veröffentlichte Paketbaseline. In Package Acceptance ist das aufgelöste Tarball `package-under-test` immer der Kandidat, und `published_upgrade_survivor_baseline` wählt die veröffentlichte Fallback-Baseline aus, standardmäßig `openclaw@latest`; Befehle zum erneuten Ausführen fehlgeschlagener Lanes behalten diese Baseline bei. Full Release Validation mit `run_release_soak=true` oder `release_profile=full` setzt `published_upgrade_survivor_baselines='last-stable-4 2026.4.23 2026.5.2 2026.4.15'` und `published_upgrade_survivor_scenarios=reported-issues`, um auf die vier neuesten stabilen npm-Releases plus gepinnte Plugin-Kompatibilitätsgrenz-Releases und issue-förmige Fixtures für Feishu-Konfiguration, beibehaltene Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeitswurzeln zu erweitern. Published-Upgrade-Survivor-Auswahlen mit mehreren Baselines werden nach Baseline in separate gezielte Docker-Runner-Jobs geshardet. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn es um umfassendes Cleanup veröffentlichter Updates geht, nicht um normale Full-Release-CI-Breite. Lokale aggregierte Runs können exakte Paketspezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, 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 Start des Gateway. Die Windows-Packaged- und Installer-Fresh-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 der Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleibt und GPT-4.x-Standards vermieden werden.
### Legacy-Kompatibilitätsfenster
Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, können den Kompatibilitätspfad verwenden:
- bekannte private QA-Einträge in `dist/postinstall-inventory.json` können auf Dateien verweisen, die im Tarball ausgelassen wurden;
- `doctor-switch` kann den Unterfall für die Persistenz von `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht bereitstellt;
- `update-channel-switch` kann fehlende `pnpm.patchedDependencies` aus dem aus dem Tarball abgeleiteten gefälschten Git-Fixture entfernen und fehlende persistierte `update.channel` protokollieren;
- Plugin-Smokes können Legacy-Speicherorte für Installationsdatensätze lesen oder fehlende Marketplace-Installationsdatensatz-Persistenz akzeptieren;
- `plugin-update` kann die Migration von Konfigurationsmetadaten 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 ausgelassen wurden;
- `doctor-switch` darf den Unterfall zur Persistenz von `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht verfügbar macht;
- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus dem vom Tarball abgeleiteten gefälschten Git-Fixture entfernen und fehlendes persistiertes `update.channel` protokollieren;
- Plugin-Smokes dürfen Legacy-Install-Record-Orte lesen oder fehlende Marketplace-Install-Record-Persistenz akzeptieren;
- `plugin-update` darf die Migration von Konfigurationsmetadaten zulassen, während weiterhin erforderlich ist, dass Install-Record- und No-Reinstall-Verhalten unverändert bleiben.
Das veröffentlichte Paket `2026.4.26` kann auch bei lokalen Build-Metadaten-Stempeldateien warnen, die bereits ausgeliefert wurden. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder übersprungen zu werden.
Das veröffentlichte Paket `2026.4.26` kann auch für lokale Build-Metadaten-Stempeldateien warnen, die bereits ausgeliefert wurden. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder übersprungen zu werden.
### Beispiele
@ -327,151 +327,151 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Wenn Sie einen fehlgeschlagenen Package-Acceptance-Lauf debuggen, beginnen Sie mit der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie dann den untergeordneten Lauf `docker_acceptance` und dessen Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Protokolle, 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.
Wenn Sie einen fehlgeschlagenen Package-Acceptance-Lauf debuggen, beginnen Sie bei der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und seine Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasen-Timings und 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.
## Install-Smoke
## Installations-Smoke
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 Paket/Manifest gebündelter Plugins oder Core-Plugin-/Channel-/Gateway-/Plugin-SDK-Oberflächen berühren, welche die Docker-Smoke-Jobs ausführen. Reine Quelländerungen an gebündelten Plugins, reine Teständerungen und reine Dokuänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den CLI-Smoke für `agents delete shared-workspace` aus, führt den Container-Gateway-Network-E2E aus, verifiziert ein Build-Argument für gebündelte Erweiterungen und führt das begrenzte Docker-Profil für gebündelte Plugins unter einem aggregierten Befehls-Timeout von 240 Sekunden aus (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-Prüfungen und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet install-smoke ein GHCR-Root-Dockerfile-Smoke-Image für den Ziel-SHA vor oder verwendet eines wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und den schnellen Docker-E2E für gebündelte Plugins 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-/Paket-Oberflächen berühren, Änderungen an gebündelten Plugin-Paketen/-Manifesten oder Core-Plugin-/Channel-/Gateway-/Plugin-SDK-Oberflächen, die von den Docker-Smoke-Jobs ausgeübt werden. Reine Quelländerungen an gebündelten Plugins, reine Teständerungen und reine Dokumentationsänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den CLI-Smoke für das Löschen von Agents in gemeinsam genutzten Workspaces aus, führt den Container-Gateway-Netzwerk-E2E aus, verifiziert ein Build-Argument für gebündelte Erweiterungen und führt das begrenzte Docker-Profil für gebündelte Plugins unter einem aggregierten Befehls-Timeout von 240 Sekunden aus (jeder Docker-Lauf eines Szenarios wird separat begrenzt).
- **Vollständiger Pfad** behält QR-Paketinstallation und Installer-Docker-/Update-Abdeckung für nächtliche geplante Läufe, manuelle Dispatches, Workflow-Call-Release-Prüfungen und Pull Requests bei, die wirklich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet Install-Smoke ein Root-Dockerfile-Smoke-Image für die Ziel-SHA in GHCR vor oder verwendet es wieder. Danach laufen QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und der schnelle Docker-E2E für gebündelte Plugins als separate Jobs, damit Installer-Arbeit nicht hinter den Root-Image-Smokes warten muss.
`main`-Pushes (einschließlich Merge-Commits) erzwingen den vollständigen Pfad nicht; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke bei und überlässt den vollständigen Install-Smoke der nächtlichen oder Release-Validierung.
Der langsame Bun-Global-Install-Smoke für Image-Provider wird separat durch `run_bun_global_install_smoke` gesteuert. Er läuft nach nächtlichem Zeitplan und aus dem Release-Checks-Workflow, und manuelle Dispatches von `Install Smoke` können ihn aktivieren, aber Pull Requests und `main`-Pushes tun das nicht. QR- und Installer-Docker-Tests behalten ihre eigenen install-fokussierten Dockerfiles.
Der langsame Bun-Global-Install-Image-Provider-Smoke wird separat über `run_bun_global_install_smoke` gesteuert. Er läuft im nächtlichen Zeitplan und aus dem Release-Checks-Workflow; manuelle `Install Smoke`-Dispatches können ihn aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installationsfokussierten Dockerfiles.
## Lokaler Docker-E2E
`pnpm test:docker:all` baut ein gemeinsames Live-Test-Image vorab, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsame Images aus `scripts/e2e/Dockerfile`:
`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:
- einen einfachen Node-/Git-Runner für Installer-/Update-/Plugin-Abhängigkeits-Lanes;
- ein funktionales Image, das denselben Tarball für normale Funktionalitäts-Lanes in `/app` installiert.
- einen schlanken Node/Git-Runner für Installer-/Update-/Plugin-Abhängigkeits-Lanes;
- ein funktionales Image, das denselben Tarball für normale Funktions-Lanes in `/app` installiert.
Docker-Lane-Definitionen liegen in `scripts/lib/docker-e2e-scenarios.mjs`, die Planner-Logik liegt 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.
### Anpassbare Parameter
### Einstellbare Optionen
| Variable | Standard | Zweck |
| -------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Slot-Anzahl des Provider-sensitiven Tail-Pools. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit für parallele Live-Lanes, damit Provider nicht drosseln. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit für parallele npm-Install-Lanes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit für parallele Multi-Service-Lanes. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Staffelung zwischen Lane-Starts, um Docker-Daemon-Erstellungsstürme zu vermeiden; setzen Sie `0` für keine Staffelung. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden strengere Grenzen. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Slot-Anzahl des Provider-sensitiven Tail-Pools. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Obergrenze für gleichzeitige Live-Lanes, damit Provider nicht drosseln. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Obergrenze für gleichzeitige npm-Install-Lanes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Obergrenze für gleichzeitige Multi-Service-Lanes. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Versatz zwischen Lane-Starts, um Docker-Daemon-Create-Stürme zu vermeiden; `0` deaktiviert den Versatz. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden engere Grenzen. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Kommagetrennte Liste exakter Lanes; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Durch Kommas getrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. |
Eine Lane, die schwerer ist als ihre effektive Grenze, kann weiterhin aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale aggregierte Ausführung prüft Docker vorab, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für eine längste-zuerst-Reihenfolge und stoppt standardmäßig nach dem ersten Fehler die Einplanung neuer gepoolter Lanes.
Eine Lane, die schwerer als ihre effektive Obergrenze ist, kann dennoch aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale Aggregation prüft Docker vorab, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für eine Longest-First-Reihenfolge und plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein.
### Wiederverwendbarer Live-/E2E-Workflow
Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welches Paket, welche Image-Art, welches Live-Image, welche Lane und welche Credential-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 aus dem aktuellen Lauf herunter oder lädt ein Paketartefakt aus `package_artifact_run_id` herunter; validiert das Tarball-Inventar; baut und pusht paket-digest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan Lanes mit installiertem Paket benötigt; und verwendet angegebene Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paket-Digest-Images wieder, statt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch erneut versucht, damit ein blockierter Registry-/Cache-Stream schnell wiederholt 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 Credential-Abdeckung erforderlich ist. `scripts/docker-e2e.mjs` wandelt diesen Plan dann in GitHub-Ausgaben und Zusammenfassungen um. Er 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 paket-digest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan Lanes mit installiertem Paket benötigt; und verwendet bereitgestellte Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paket-Digest-Images wieder, statt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch erneut versucht, damit ein hängender Registry-/Cache-Stream schnell neu gestartet wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen.
### Release-Pfad-Chunks
Release-Docker-Abdeckung läuft in kleineren, in Chunks aufgeteilten Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Chunk nur die Image-Art pullt, die er benötigt, und mehrere Lanes über denselben gewichteten Scheduler ausführt:
Release-Docker-Abdeckung läuft in kleineren Chunk-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:
- `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-Chunks 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-Aliasse. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Alias zum erneuten Ausführen für beide Provider-Installer-Lanes.
OpenWebUI wird in `plugins-runtime-services` integriert, wenn vollständige Release-Pfad-Abdeckung es anfordert, und behält nur für OpenWebUI-only-Dispatches einen eigenständigen Chunk `openwebui`. Update-Lanes für gebündelte Channels wiederholen bei vorübergehenden npm-Netzwerkfehlern einmal.
OpenWebUI wird in `plugins-runtime-services` integriert, wenn vollständige Release-Pfad-Abdeckung dies anfordert, und behält nur für reine OpenWebUI-Dispatches einen eigenständigen Chunk `openwebui`. Update-Lanes für gebündelte Channels versuchen bei transienten npm-Netzwerkfehlern einmal erneut.
Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Protokollen, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Rerun-Befehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus statt die Chunk-Jobs, wodurch 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 für diesen Rerun lokal. 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 Chunk lädt `.artifacts/docker-tests/` mit Lane-Logs, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Befehlen zum erneuten Ausführen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus, statt die Chunk-Jobs zu verwenden. Dadurch bleibt das 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 lokal für diesen erneuten Lauf. Generierte GitHub-Befehle zum erneuten Ausführen pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, sofern diese Werte vorhanden sind, damit eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
Der geplante Live-/E2E-Workflow führt täglich die vollständige Release-Pfad-Docker-Suite aus.
Der geplante Live-/E2E-Workflow führt die vollständige Release-Pfad-Docker-Suite täglich aus.
## Plugin-Prerelease
`Plugin Prerelease` ist aufwendigere 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 balanciert Tests gebündelter Plugins über acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap aus, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der reine Release-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.
`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 Tests gebündelter Plugins auf acht Extension-Worker; diese Extension-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap aus, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der nur für Releases vorgesehene Docker-Prerelease-Pfad bündelt gezielte Docker-Lanes in kleinen Gruppen, um nicht Dutzende Runner für ein- bis dreiminütige Jobs zu reservieren.
## QA Lab
QA Lab hat dedizierte CI-Lanes außerhalb des hauptsächlichen smart-gescopten Workflows. Agentic Parity ist unter den breiten QA- und Release-Harnesses verschachtelt, kein eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parity Teil eines breiten Validierungslaufs sein soll.
QA Lab hat dedizierte CI-Lanes außerhalb des wichtigsten Smart-Scoped-Workflows. Agentische Parität ist unter den breiten QA- und Release-Harnesses verschachtelt und kein eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität zusammen mit einem breiten Validierungslauf laufen soll.
- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Parity-Lane, die Live-Matrix-Lane sowie die Live-Telegram- und Live-Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases.
- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Paritäts-Lane, die Live-Matrix-Lane sowie die Live-Telegram- und Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases.
Release-Prüfungen führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Channel-Vertrag von Live-Modell-Latenz und normalem Start von Provider-Plugins isoliert ist. Das Live-Transport-Gateway deaktiviert Speichersuche, weil QA-Parity das Speicherverhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Live-Model-, Native-Provider- und Docker-Provider-Suites abgedeckt.
Release-Prüfungen führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Channel-Vertrag von Live-Modelllatenz und normalem Start von Provider-Plugins isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, weil QA-Parität 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`; ein manueller Dispatch mit `matrix_profile=all` shardet die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`.
Matrix verwendet `--profile fast` für geplante und Release-Gates und fügt `--fail-fast` nur hinzu, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standardwert und die manuelle Workflow-Eingabe bleiben `all`; ein manueller Dispatch mit `matrix_profile=all` shardet die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`.
`OpenClaw Release Checks` führt auch die release-kritischen QA-Lab-Lanes vor der Release-Freigabe aus; sein QA-Parity-Gate führt die Candidate- und Baseline-Packs als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Berichtsjob für den finalen Parity-Vergleich 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-Packs als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Report-Job für den abschließenden Paritätsvergleich herunter.
Bei normalen PRs folgen Sie den bereichsbezogenen CI-/Prüfnachweisen, statt Parität als erforderlichen Status zu behandeln.
Für normale PRs folgen Sie scoped CI-/Check-Nachweisen, statt Parität als erforderlichen Status zu behandeln.
## CodeQL
Der `CodeQL`-Workflow ist bewusst ein enger Sicherheitsscan im ersten Durchlauf, kein vollständiger Repository-Sweep. Tägliche, manuelle und Guard-Ausführungen für nicht als Entwurf markierte Pull Requests scannen Actions-Workflow-Code sowie die JavaScript-/TypeScript-Bereiche mit dem höchsten Risiko mit hochverlässlichen Sicherheitsabfragen, gefiltert auf hohe/kritische `security-severity`.
Der `CodeQL`-Workflow ist bewusst ein schmaler Sicherheits-Scanner für den ersten Durchlauf, nicht der vollständige Repository-Sweep. Tägliche, manuelle und Guard-Läufe für nicht als Entwurf markierte Pull Requests scannen Actions-Workflow-Code sowie die risikoreichsten JavaScript-/TypeScript-Flächen mit Sicherheitsabfragen 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 führt dieselbe hochverlässliche Sicherheitsmatrix wie der geplante Workflow aus. Android- und macOS-CodeQL bleiben außerhalb der PR-Standards.
Der Pull-Request-Guard bleibt leichtgewichtig: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src` und führt dieselbe Sicherheitsmatrix hoher Konfidenz wie der geplante Workflow aus. Android- und macOS-CodeQL bleiben außerhalb der PR-Standards.
### Sicherheitskategorien
| Kategorie | Bereich |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `/codeql-security-high/core-auth-secrets` | Auth, Geheimnisse, Sandbox, Cron und Gateway-Basis |
| `/codeql-security-high/channel-runtime-boundary` | Core-Channel-Implementierungsverträge plus Channel-Plugin-Runtime, Gateway, Plugin SDK, Geheimnisse, Audit-Berührungspunkte |
| `/codeql-security-high/network-ssrf-boundary` | Core-SSRF, IP-Parsing, Network-Guard, Web-Fetch und SSRF-Policy-Bereiche des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfsfunktionen für Prozessausführung, ausgehende Zustellung und Gates für Agent-Toolausführung |
| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Package-Manager-Installation, Source-Loading und Vertrauensbereiche des Plugin-SDK-Package-Vertrags |
| Kategorie | Fläche |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Gateway-Baseline |
| `/codeql-security-high/channel-runtime-boundary` | Core-Channel-Implementierungsverträge plus Channel-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte |
| `/codeql-security-high/network-ssrf-boundary` | Core-SSRF, IP-Parsing, Netzwerkschutz, Web-Fetch und SSRF-Policy-Flächen des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfen zur Prozessausführung, ausgehende Zustellung und Gates für Agent-Tool-Ausführung |
| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Paketmanager-Installation, Source-Loading und Trust-Flächen des Plugin-SDK-Paketvertrags |
### Plattformspezifische Sicherheits-Shards
- `CodeQL Android Critical Security` — geplanter Android-Sicherheits-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, den 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 Ergebnisse aus Dependency-Builds aus dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standards, weil der macOS-Build die Laufzeit dominiert, selbst wenn er sauber ist.
- `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 Dependency-Build-Ergebnisse aus dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standards, weil der macOS-Build selbst bei sauberem Lauf die Laufzeit dominiert.
### Critical-Quality-Kategorien
`CodeQL Critical Quality` ist der passende Nicht-Sicherheits-Shard. Er führt nur JavaScript-/TypeScript-Qualitätsabfragen mit Fehler-Schweregrad und ohne Sicherheitsbezug über enge, hochwertige Bereiche auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist bewusst kleiner als das geplante Profil: Nicht-Entwurfs-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-/Toolausführung und Antwort-Dispatch-Code, Config-Schema-/Migrations-/IO-Code, Auth-/Geheimnis-/Sandbox-/Sicherheitscode, Core-Channel und gebündelte Channel-Plugin-Runtime, Gateway-Protokoll/Servermethode, Memory-Runtime/SDK-Verknüpfung, MCP/Prozess/ausgehende Zustellung, Provider-Runtime/Modellkatalog, Sitzungsdiagnose/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK/Package-Vertrag oder Änderungen an der Plugin-SDK-Antwort-Runtime aus. Änderungen an CodeQL-Config und Quality-Workflow führen alle zwölf PR-Quality-Shards aus.
`CodeQL Critical Quality` ist der passende Nicht-Sicherheits-Shard. Er führt nur JavaScript-/TypeScript-Qualitätsabfragen mit Fehler-Schweregrad und ohne Sicherheitsbezug über schmale, hochwertige Flächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist bewusst kleiner als das geplante Profil: Nicht als Entwurf markierte PRs führen nur die passenden Shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` und `plugin-sdk-reply-runtime` für Änderungen an Agent-Befehl-/Modell-/Tool-Ausführung und Reply-Dispatch-Code, Config-Schema-/Migrations-/IO-Code, Auth-/Secrets-/Sandbox-/Sicherheitscode, Core-Channel- und gebündelter Channel-Plugin-Runtime, Gateway-Protokoll-/Server-Methoden, Memory-Runtime-/SDK-Glue, MCP-/Prozess-/ausgehender Zustellung, Provider-Runtime-/Modellkatalog, Session-Diagnose-/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Paketvertrag oder Plugin-SDK-Reply-Runtime aus. Änderungen an CodeQL-Config und Quality-Workflow führen alle zwölf PR-Quality-Shards aus.
Manueller Dispatch akzeptiert:
Manuelle Dispatches akzeptieren:
```
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 Lehr-/Iterations-Hooks, um einen Quality-Shard isoliert auszuführen.
Die schmalen Profile sind Lehr-/Iterations-Hooks, um einen Quality-Shard isoliert auszuführen.
| Kategorie | Bereich |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Auth, Geheimnisse, Sandbox, Cron und Code der Gateway-Sicherheitsgrenze |
| `/codeql-critical-quality/config-boundary` | Config-Schema-, Migrations-, Normalisierungs- und IO-Verträge |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemata und Servermethodenverträge |
| `/codeql-critical-quality/channel-runtime-boundary` | Core-Channel- und gebündelte Channel-Plugin-Implementierungsverträge |
| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie Runtime-Verträge der ACP-Control-Plane |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Hilfsfunktionen zur Prozessüberwachung und Verträge für ausgehende Zustellung |
| `/codeql-critical-quality/memory-runtime-boundary` | Memory-Host-SDK, Memory-Runtime-Fassaden, Memory-Plugin-SDK-Aliasse, Verknüpfung zur Memory-Runtime-Aktivierung und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Antwortwarteschlange, Sitzungszustellungswarteschlangen, Hilfsfunktionen für ausgehende Sitzungsbindung/-zustellung, Diagnoseereignis-/Log-Bundle-Bereiche und Session-Doctor-CLI-Verträge |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Eingehender Antwort-Dispatch des Plugin SDK, Hilfsfunktionen für Antwort-Payload/Chunking/Runtime, Channel-Antwortoptionen, Zustellungswarteschlangen und Hilfsfunktionen für Sitzungs-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Auth und -Discovery, Provider-Runtime-Registrierung, Provider-Standards/-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` | Core-Web-Fetch/Search, 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öffentlichter package-seitiger Plugin-SDK-Quellcode und Hilfsfunktionen für Plugin-Package-Verträge |
| Kategorie | Fläche |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Code an der Gateway-Sicherheitsgrenze |
| `/codeql-critical-quality/config-boundary` | Config-Schema, 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` | Core-Channel- und gebündelte Channel-Plugin-Implementierungsverträge |
| `/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, Prozessüberwachungs-Hilfen und Verträge für ausgehende Zustellung |
| `/codeql-critical-quality/memory-runtime-boundary` | Memory-Host-SDK, Memory-Runtime-Fassaden, Memory-Plugin-SDK-Aliasse, Memory-Runtime-Aktivierungs-Glue und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Reply-Warteschlangen-Interna, Session-Zustellungswarteschlangen, Hilfen für ausgehende Session-Bindung/-Zustellung, Diagnoseereignis-/Log-Bundle-Flächen und Session-Doctor-CLI-Verträge |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Inbound-Reply-Dispatch des Plugin SDK, Reply-Payload-/Chunking-/Runtime-Hilfen, Channel-Reply-Optionen, Zustellungswarteschlangen und Hilfen für Session-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Authentifizierung und -Erkennung, Provider-Runtime-Registrierung, Provider-Standards/-Kataloge und Web-/Search-/Fetch-/Embedding-Registries |
| `/codeql-critical-quality/ui-control-plane` | Control-UI-Bootstrap, lokale Persistenz, Gateway-Control-Flows und Task-Control-Plane-Runtime-Verträge |
| `/codeql-critical-quality/web-media-runtime-boundary` | Core-Web-Fetch/-Search, Medien-IO, Medienverständnis, Bildgenerierung und Mediengenerierungs-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 paket seitiger Plugin-SDK-Quellcode und Hilfen für Plugin-Paketverträge |
Quality bleibt von Security getrennt, damit Quality-Funde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Sicherheitssignal zu verdecken. Die CodeQL-Erweiterung für Swift, Python und gebündelte Plugins sollte erst wieder als bereichsbezogene oder geshardete Folgearbeit hinzugefügt werden, nachdem die engen Profile stabile Laufzeit und stabile Signale haben.
Quality bleibt von Security getrennt, damit Quality-Ergebnisse geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Security-Signal zu verschleiern. Swift-, Python- und gebündelte-Plugin-CodeQL-Erweiterungen sollten erst wieder als scoped oder in Shards aufgeteilte Folgearbeit hinzugefügt werden, nachdem die schmalen Profile stabile Laufzeit und stabile Signale haben.
## Wartungs-Workflows
### Docs Agent
Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur, um vorhandene Docs an kürzlich gelandete Änderungen anzupassen. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, und 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 vom vorherigen nicht übersprungenen Docs-Agent-Quell-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle Änderungen auf main seit dem letzten Docs-Durchlauf abdecken kann.
Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungslane, um vorhandene Docs mit kürzlich gelandeten Änderungen abzugleichen. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, und ein manueller Dispatch kann ihn direkt ausführen. 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 vom 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.
### Test Performance Agent
Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher Nicht-Bot-Push-CI-Lauf auf `main` kann ihn auslösen, aber er wird übersprungen, wenn an diesem UTC-Tag bereits ein anderer Workflow-Run-Aufruf lief oder läuft. Manueller Dispatch umgeht dieses tägliche Aktivitäts-Gate. Die Spur erstellt einen gruppierten Vitest-Performance-Bericht für die vollständige Suite, lässt Codex nur kleine, Coverage-erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt den vollständigen Suite-Bericht danach erneut aus und weist Änderungen zurück, die die Baseline-Anzahl bestandener Tests reduzieren. Wenn die Baseline fehlgeschlagene Tests enthält, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agent muss bestehen, bevor etwas committet wird. Wenn `main` vor dem Bot-Push voranschreitet, rebasiert die Spur den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; widersprüchliche veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitsausrichtung wie der Docs Agent beibehalten kann.
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äts-Gate. Die Lane erstellt einen gruppierten Vitest-Performance-Bericht der vollständigen Suite, lässt Codex nur kleine, Coverage-erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt dann den vollständigen Suite-Bericht erneut aus und weist Änderungen zurück, die die Baseline-Anzahl bestandener Tests reduzieren. Wenn die Baseline fehlgeschlagene Tests hat, darf Codex nur offensichtliche Fehler beheben, und der vollständige Suite-Bericht nach dem Agent muss bestanden sein, bevor etwas committet wird. Wenn `main` vor dem Bot-Push weiterläuft, rebased die Lane den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; konfliktbehaftete veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-sudo-Sicherheitshaltung wie der Docs Agent beibehalten kann.
### Doppelte PRs nach dem Merge
### Doppelte PRs nach Merge
Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow zur Duplikatbereinigung nach dem Landen. Er ist standardmäßig ein Dry-Run und schließt nur explizit aufgelistete PRs, wenn `apply=true` gesetzt ist. Bevor GitHub mutiert wird, 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 doppelter PRs nach dem Landen. Standardmäßig läuft er als Dry-Run und schließt nur ausdrücklich aufgeführte PRs, wenn `apply=true` gesetzt ist. Bevor er GitHub verändert, prüft er, dass der gelandete PR gemergt ist und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat.
```bash
gh workflow run duplicate-after-merge.yml \
@ -482,35 +482,35 @@ gh workflow run duplicate-after-merge.yml \
## Lokale Check-Gates und Changed-Routing
Die lokale Changed-Lane-Logik befindet sich in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite CI-Plattformbereich:
Die lokale Changed-Lane-Logik liegt in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite CI-Plattform-Scope:
- Core-Produktionsänderungen führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/Guards aus;
- reine Core-Teständerungen führen nur Core-Test-Typecheck plus Core-Lint aus;
- Extension-Produktionsänderungen führen Extension-Prod- und Extension-Test-Typecheck plus Extension-Lint aus;
- reine Extension-Teständerungen führen Extension-Test-Typecheck plus Extension-Lint aus;
- öffentliche Plugin-SDK- oder Plugin-Contract-Änderungen erweitern auf Extension-Typecheck, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit);
- reine Release-Metadaten-Versions-Bumps führen gezielte Versions-/Config-/Root-Dependency-Checks aus;
- unbekannte Root-/Config-Änderungen schlagen sicherheitshalber auf alle Check-Lanes aus.
- Core-Produktionsänderungen führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/-Guards aus;
- reine Core-Test-Änderungen führen nur Core-Test-Typecheck plus Core-Lint aus;
- Plugin-Produktionsänderungen führen Plugin-Prod- und Plugin-Test-Typecheck plus Plugin-Lint aus;
- reine Plugin-Test-Änderungen führen Plugin-Test-Typecheck plus Plugin-Lint aus;
- öffentliche Plugin-SDK- oder Plugin-Vertragsänderungen erweitern auf Plugin-Typecheck, weil Plugins von diesen Core-Verträgen abhängen (Vitest-Plugin-Sweeps bleiben explizite Testarbeit);
- reine Release-Metadaten-Versionsbumps führen gezielte Versions-/Config-/Root-Dependency-Checks aus;
- unbekannte Root-/Config-Änderungen fallen sicherheitshalber auf alle Check-Lanes zurück.
Das lokale Changed-Test-Routing befindet sich in `scripts/test-projects.test-support.mjs` und ist bewusst günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Quelländerungen bevorzugen explizite Zuordnungen, dann Geschwistertests und Import-Graph-Dependents. Die gemeinsame Zustellungs-Config für Gruppenräume ist eine der expliziten Zuordnungen: Änderungen an der für Gruppen sichtbaren Antwort-Config, am Quell-Antwort-Zustellmodus oder am Message-Tool-System-Prompt laufen durch die Core-Antworttests plus Discord- und Slack-Zustellungsregressionen, sodass eine geänderte gemeinsame Voreinstellung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung so harness-weit ist, dass das günstige zugeordnete Set 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-Delivery-Config ist eines der expliziten Mappings: Änderungen an der für die Gruppe sichtbaren Reply-Config, am Source-Reply-Zustellungsmodus oder am Message-Tool-Systemprompt werden durch die Core-Reply-Tests plus Discord- und Slack-Zustellungsregressionen geroutet, sodass eine gemeinsame Standardänderung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung so harness-weit ist, dass die günstige gemappte Menge kein vertrauenswürdiger Proxy ist.
## Testbox-Validierung
Führen Sie Testbox aus dem Repo-Root aus und bevorzugen Sie für umfassende Nachweise eine frisch vorgewärmte Box. Bevor Sie ein langsames Gate auf einer Box ausführen, die wiederverwendet wurde, abgelaufen ist oder gerade eine unerwartet große Synchronisierung gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` in der Box aus.
Führen Sie Testbox vom Repo-Root aus und bevorzugen Sie für breite Nachweise eine frisch aufgewärmte Box. Bevor Sie ein langsames Gate auf einer Box ausführen, die wiederverwendet wurde, abgelaufen ist oder gerade einen unerwartet großen Sync gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` innerhalb der Box aus.
Der Sanity-Check schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 nachverfolgte Löschungen anzeigt. Das bedeutet normalerweise, dass der Remote-Synchronisierungszustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie eine frische vor, statt den Produkt-Testfehler zu debuggen. Für absichtliche PRs mit vielen Löschungen setzen Sie `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` für diesen Sanity-Lauf.
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-Sync-Zustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie eine frische auf, statt den Produkttestfehler zu debuggen. Setzen Sie für absichtliche PRs mit vielen Löschungen `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` für diesen Sanity-Lauf.
`pnpm testbox:run` beendet außerdem einen lokalen Blacksmith-CLI-Aufruf, der länger als fünf Minuten ohne Ausgabe nach der Synchronisierung in der Synchronisierungsphase bleibt. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diese Schutzprüfung zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs.
`pnpm testbox:run` beendet außerdem eine lokale Blacksmith-CLI-Invocation, die länger als fünf Minuten ohne Ausgabe nach dem Sync in der Sync-Phase bleibt. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diesen Schutz zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs.
Crabbox ist der repo-eigene Remote-Box-Wrapper für Linux-Nachweise von Maintainern. Verwenden Sie ihn, wenn ein Check für einen lokalen Edit-Loop zu breit ist, wenn CI-Parität wichtig ist oder wenn der Nachweis Secrets, Docker, Paket-Lanes, wiederverwendbare Boxen oder Remote-Logs benötigt. Das normale OpenClaw-Backend ist `blacksmith-testbox`; eigene AWS-/Hetzner-Kapazität ist ein Fallback bei Blacksmith-Ausfällen, Kontingentproblemen oder ausdrücklich gewünschtem Testen auf eigener Kapazität.
Crabbox ist der repo-eigene Remote-Box-Wrapper für Maintainer-Linux-Nachweise. Verwenden Sie ihn, wenn ein Check für eine lokale Edit-Schleife zu breit ist, wenn CI-Parität wichtig ist oder wenn der Nachweis Secrets, Docker, Package-Lanes, wiederverwendbare Boxen oder Remote-Logs benötigt. Das normale OpenClaw-Backend ist `blacksmith-testbox`; eigene AWS-/Hetzner-Kapazität ist ein Fallback für Blacksmith-Ausfälle, Quotenprobleme oder ausdrücklich gewünschte Tests auf eigener Kapazität.
Prüfen Sie den Wrapper vor dem ersten Lauf aus dem Repo-Root:
Prüfen Sie vor einem ersten Lauf den Wrapper vom Repo-Root aus:
```bash
pnpm crabbox:run -- --help | sed -n '1,120p'
```
Der Repo-Wrapper verweigert ein veraltetes Crabbox-Binary, das `blacksmith-testbox` nicht ausweist. Übergeben Sie den Provider explizit, auch wenn `.crabbox.yaml` Defaults für die eigene Cloud enthält.
Der Repo-Wrapper verweigert eine veraltete Crabbox-Binary, die `blacksmith-testbox` nicht ausweist. Übergeben Sie den Provider explizit, auch wenn `.crabbox.yaml` Defaults für die eigene Cloud enthält.
Changed-Gate:
@ -557,7 +557,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
```
Lesen Sie die abschließende JSON-Zusammenfassung. Die nützlichen Felder sind `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` und `totalMs`. Einmalige Blacksmith-gestützte Crabbox-Läufe sollten die Testbox automatisch stoppen; wenn ein Lauf unterbrochen wurde oder die Bereinigung unklar ist, prüfen Sie die laufenden Boxen und stoppen Sie nur die Boxen, die Sie erstellt haben:
Lesen Sie die abschließende JSON-Zusammenfassung. Die nützlichen Felder sind `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` und `totalMs`. Einmalige Blacksmith-gestützte Crabbox-Läufe sollten die Testbox automatisch stoppen; wenn ein Lauf unterbrochen wird oder die Bereinigung unklar ist, prüfen Sie laufende Boxen und stoppen Sie nur die Boxen, die Sie erstellt haben:
```bash
blacksmith testbox list
@ -579,7 +579,7 @@ blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_id>
```
Eskalieren Sie nur dann auf eigene Crabbox-Kapazität, wenn Blacksmith ausgefallen ist, durch Kontingente begrenzt ist, die benötigte Umgebung fehlt oder eigene Kapazität ausdrücklich das Ziel ist:
Eskalieren Sie nur dann auf eigene Crabbox-Kapazität, wenn Blacksmith ausgefallen, durch Quoten begrenzt oder die benötigte Umgebung nicht verfügbar ist, oder wenn eigene Kapazität ausdrücklich das Ziel ist:
```bash
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
@ -588,9 +588,9 @@ pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` besitzt die Defaults für Provider, Synchronisierung und GitHub-Actions-Hydrierung für eigene Cloud-Lanes. Sie schließt lokales `.git` aus, damit der hydrierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, statt maintainer-lokale Remotes und Object Stores zu synchronisieren, und sie schließt lokale Laufzeit-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` besitzt Checkout, Node-/pnpm-Einrichtung, `origin/main`-Fetch und die nicht geheime Umgebungsübergabe für eigene Cloud-Befehle mit `crabbox run --id <cbx_id>`.
`.crabbox.yaml` besitzt die Defaults für Provider, Sync und die GitHub Actions-Hydrierung für eigene Cloud-Lanes. Sie schließt lokales `.git` aus, damit der hydrierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, statt maintainer-lokale Remotes und Object Stores zu synchronisieren, und sie schließt lokale Runtime-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` besitzt Checkout, Node-/pnpm-Setup, `origin/main`-Fetch und die nicht geheime Umgebungsübergabe für eigene Cloud-Befehle mit `crabbox run --id <cbx_id>`.
## Verwandt
- [Installationsübersicht](/de/install)
- [Entwicklungs-Channels](/de/install/development-channels)
- [Entwicklungskanäle](/de/install/development-channels)

40
docs/de/cli/dns.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Sie möchten Weitbereichserkennung (DNS-SD) über Tailscale + CoreDNS via Tailscale
- You’re setting up split DNS for a custom discovery domain (example: openclaw.internal)
summary: CLI-Referenz für `openclaw dns` (Hilfsprogramme für die Weitbereichserkennung)
- Sie möchten bereichsübergreifende Erkennung (DNS-SD) über Tailscale + CoreDNS nutzen
- You're setting up split DNS for a custom discovery domain (example: openclaw.internal)
summary: CLI-Referenz für `openclaw dns` (Hilfsfunktionen für die Weitbereichserkennung)
title: DNS
x-i18n:
generated_at: "2026-04-24T06:31:11Z"
model: gpt-5.4
generated_at: "2026-05-06T09:02:53Z"
model: gpt-5.5
provider: openai
source_hash: 99dcf7c8c76833784a2b712b02f9e40c6c0548c37c9743a89b9d650fe503d385
source_hash: 460bdcbaa2c0c0fc1a4f5bdd76b904d8ac35195a25324c66421abfdc2044bb07
source_path: cli/dns.md
workflow: 15
workflow: 16
---
# `openclaw dns`
DNS-Hilfsprogramme für die Weitbereichserkennung (Tailscale + CoreDNS). Derzeit auf macOS + Homebrew CoreDNS fokussiert.
DNS-Helfer für Wide-Area-Erkennung (Tailscale + CoreDNS). Derzeit auf macOS + Homebrew CoreDNS ausgerichtet.
Verwandt:
- Gateway-Erkennung: [Discovery](/de/gateway/discovery)
- Konfiguration der Weitbereichserkennung: [Configuration](/de/gateway/configuration)
- Gateway-Erkennung: [Erkennung](/de/gateway/discovery)
- Wide-Area-Erkennungskonfiguration: [Konfiguration](/de/gateway/configuration)
## Einrichtung
@ -36,25 +36,25 @@ CoreDNS-Einrichtung für Unicast-DNS-SD-Erkennung planen oder anwenden.
Optionen:
- `--domain <domain>`: Domain für die Weitbereichserkennung (zum Beispiel `openclaw.internal`)
- `--domain <domain>`: Wide-Area-Erkennungsdomain (zum Beispiel `openclaw.internal`)
- `--apply`: CoreDNS-Konfiguration installieren oder aktualisieren und den Dienst neu starten (erfordert sudo; nur macOS)
Was angezeigt wird:
Angezeigte Informationen:
- aufgelöste Discovery-Domain
- Zone-File-Pfad
- aufgelöste Erkennungsdomain
- Zone-Dateipfad
- aktuelle Tailnet-IPs
- empfohlene `openclaw.json`-Discovery-Konfiguration
- die festzulegenden Tailscale-Split-DNS-Nameserver-/Domain-Werte
- empfohlene `openclaw.json`-Erkennungskonfiguration
- die festzulegenden Tailscale-Split-DNS-Nameserver-/Domainwerte
Hinweise:
- Ohne `--apply` ist der Befehl nur ein Planungshilfsmittel und gibt die empfohlene Einrichtung aus.
- Wenn `--domain` weggelassen wird, verwendet OpenClaw `discovery.wideArea.domain` aus der Konfiguration.
- Ohne `--apply` dient der Befehl nur als Planungshilfe und gibt die empfohlene Einrichtung aus.
- Wenn `--domain` ausgelassen wird, verwendet OpenClaw `discovery.wideArea.domain` aus der Konfiguration.
- `--apply` unterstützt derzeit nur macOS und erwartet Homebrew CoreDNS.
- `--apply` bootstrapped bei Bedarf das Zone-File, stellt sicher, dass die CoreDNS-Import-Stanza vorhanden ist, und startet den `coredns`-Brew-Service neu.
- `--apply` initialisiert bei Bedarf die Zone-Datei, stellt sicher, dass die CoreDNS-Import-Anweisung vorhanden ist, und startet den Brew-Dienst `coredns` neu.
## Verwandt
- [CLI-Referenz](/de/cli)
- [Discovery](/de/gateway/discovery)
- [Erkennung](/de/gateway/discovery)

28
docs/de/cli/health.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Sie möchten schnell die Integrität des laufenden Gateway prüfen
summary: CLI-Referenz für `openclaw health` (Gateway-Integritäts-Snapshot über RPC)
title: Integrität
- Sie möchten schnell den Zustand des laufenden Gateway prüfen
summary: CLI-Referenz für `openclaw health` (Gateway-Zustandssnapshot über RPC)
title: Systemzustand
x-i18n:
generated_at: "2026-04-24T06:31:27Z"
model: gpt-5.4
generated_at: "2026-05-06T09:02:56Z"
model: gpt-5.5
provider: openai
source_hash: bf5f5b9c3ec5c08090134764966d2657241ed0ebbd28a9dc7fafde0b8c7216d6
source_hash: 443684af04efce2c54a6679e13b0bff0a5c1869f85d60fae0e853aed0a362226
source_path: cli/health.md
workflow: 15
workflow: 16
---
# `openclaw health`
Rufen Sie die Integrität des laufenden Gateway ab.
Ruft den Integritätsstatus vom laufenden Gateway ab.
Optionen:
- `--json`: maschinenlesbare Ausgabe
- `--timeout <ms>`: Verbindungs-Timeout in Millisekunden (Standard `10000`)
- `--timeout <ms>`: Verbindungszeitlimit in Millisekunden (Standard `10000`)
- `--verbose`: ausführliche Protokollierung
- `--debug`: Alias für `--verbose`
@ -37,12 +37,12 @@ Hinweise:
- Standardmäßig fragt `openclaw health` das laufende Gateway nach seinem Integritäts-Snapshot. Wenn das
Gateway bereits einen aktuellen zwischengespeicherten Snapshot hat, kann es diese zwischengespeicherte Payload zurückgeben und
die Aktualisierung im Hintergrund durchführen.
- `--verbose` erzwingt eine Live-Prüfung, gibt Gateway-Verbindungsdetails aus und erweitert die
menschenlesbare Ausgabe auf alle konfigurierten Konten und Agenten.
im Hintergrund aktualisieren.
- `--verbose` erzwingt eine Live-Prüfung, gibt Details zur Gateway-Verbindung aus und erweitert die
menschenlesbare Ausgabe über alle konfigurierten Konten und Agenten hinweg.
- Die Ausgabe enthält Session Stores pro Agent, wenn mehrere Agenten konfiguriert sind.
## Verwandt
## Verwandte Themen
- [CLI-Referenz](/de/cli)
- [Gateway-Integrität](/de/gateway/health)
- [Gateway-Integritätsstatus](/de/gateway/health)

106
docs/de/cli/infer.md
View File

@ -1,23 +1,23 @@
---
read_when:
- Hinzufügen oder Ändern von `openclaw infer`-Befehlen
- Stabile Automatisierung von Fähigkeiten ohne grafische Oberfläche entwerfen
- Stabile Headless-Capability-Automatisierung entwerfen
summary: Inferenzorientierte CLI für Provider-gestützte Modell-, Bild-, Audio-, TTS-, Video-, Web- und Embedding-Workflows
title: Inferenz-CLI
x-i18n:
generated_at: "2026-05-02T06:29:38Z"
generated_at: "2026-05-06T09:03:09Z"
model: gpt-5.5
provider: openai
source_hash: 04f8b4aeb70e960835612eedcc0a22202957803ca4e5eeb3f1e107e8c736e458
source_hash: 232bf8165ff74b19aaf84431519d9f9f99f20831420b73935f73ffd9412bd04a
source_path: cli/infer.md
workflow: 16
---
`openclaw infer` ist die kanonische Headless-Oberfläche für Inferenz-Workflows mit Provider-Unterstützung.
`openclaw infer` ist die maßgebliche Headless-Oberfläche für Provider-gestützte Inferenz-Workflows.
Es stellt absichtlich Capability-Familien bereit, nicht rohe Gateway-RPC-Namen und nicht rohe Agent-Tool-IDs.
Es stellt bewusst Funktionsfamilien bereit, nicht rohe Gateway-RPC-Namen und nicht rohe Agent-Tool-IDs.
## infer in einen Skill umwandeln
## infer in ein Skill umwandeln
Kopieren Sie dies und fügen Sie es in einen Agent ein:
@ -26,14 +26,14 @@ Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my comm
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.
```
Ein guter infer-basierter Skill sollte:
Ein gutes infer-basiertes Skill sollte:
- gängige Benutzerabsichten dem richtigen infer-Unterbefehl zuordnen
- häufige Benutzerabsichten dem richtigen infer-Unterbefehl zuordnen
- einige kanonische infer-Beispiele für die abgedeckten Workflows enthalten
- in Beispielen und Vorschlägen `openclaw infer ...` bevorzugen
- vermeiden, die gesamte infer-Oberfläche im Skill-Text erneut zu dokumentieren
Typischer Umfang eines infer-fokussierten Skills:
Typische Abdeckung für infer-fokussierte Skills:
- `openclaw infer model run`
- `openclaw infer image generate`
@ -44,17 +44,20 @@ Typischer Umfang eines infer-fokussierten Skills:
## Warum infer verwenden
`openclaw infer` bietet eine einheitliche CLI für Inferenzaufgaben mit Provider-Unterstützung innerhalb von OpenClaw.
`openclaw infer` stellt eine einheitliche CLI für Provider-gestützte Inferenzaufgaben innerhalb von OpenClaw bereit.
Vorteile:
- Nutzen Sie die bereits in OpenClaw konfigurierten Provider und Modelle, statt einmalige Wrapper für jedes Backend zu verdrahten.
- Halten Sie Workflows für Modell-, Bild-, Audiotranskriptions-, TTS-, Video-, Web- und Embedding-Aufgaben unter einem Befehlsbaum.
- Verwenden Sie eine stabile `--json`-Ausgabeform für Skripte, Automatisierung und agentengesteuerte Workflows.
- Bevorzugen Sie eine OpenClaw-eigene Oberfläche, wenn die Aufgabe im Kern „Inferenz ausführen“ ist.
- Verwenden Sie die bereits in OpenClaw konfigurierten Provider und Modelle, anstatt einmalige Wrapper für jedes Backend zu verdrahten.
- Halten Sie Modell-, Bild-, Audiotranskriptions-, TTS-, Video-, Web- und Embedding-Workflows unter einem Befehlsbaum.
- Verwenden Sie eine stabile `--json`-Ausgabeform für Skripte, Automatisierung und Agent-gesteuerte Workflows.
- Bevorzugen Sie eine native OpenClaw-Oberfläche, wenn die Aufgabe im Kern „Inferenz ausführen“ ist.
- Verwenden Sie für die meisten infer-Befehle den normalen lokalen Pfad, ohne den Gateway zu benötigen.
Für End-to-End-Provider-Prüfungen sollten Sie `openclaw infer ...` bevorzugen, sobald Low-Level-Provider-Tests grün sind. Es übt die ausgelieferte CLI, das Laden der Konfiguration, die Standard-Agent-Auflösung, die Aktivierung gebündelter Plugins und die gemeinsame Capability-Laufzeit aus, bevor die Provider-Anfrage gestellt wird.
Für End-to-End-Provider-Prüfungen bevorzugen Sie `openclaw infer ...`, sobald untergeordnete
Provider-Tests erfolgreich sind. Es prüft die ausgelieferte CLI, das Laden der Konfiguration,
die Auflösung des Standard-Agent, die Aktivierung gebündelter Plugins und die gemeinsame Capability-
Laufzeitumgebung, bevor die Provider-Anfrage gestellt wird.
## Befehlsbaum
@ -109,13 +112,13 @@ Für End-to-End-Provider-Prüfungen sollten Sie `openclaw infer ...` bevorzugen,
## Häufige Aufgaben
Diese Tabelle ordnet gängige Inferenzaufgaben dem entsprechenden infer-Befehl zu.
Diese Tabelle ordnet häufige Inferenzaufgaben dem entsprechenden infer-Befehl zu.
| Aufgabe | Befehl | Hinweise |
| Aufgabe | Befehl | Hinweise |
| ---------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Einen Text-/Modell-Prompt ausführen | `openclaw infer model run --prompt "..." --json` | Verwendet standardmäßig den normalen lokalen Pfad |
| Einen Modell-Prompt für Bilder ausführen | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | Wiederholen Sie `--file` für mehrere Bildeingaben |
| Ein Bild generieren | `openclaw infer image generate --prompt "..." --json` | Verwenden Sie `image edit`, wenn Sie von einer vorhandenen Datei starten |
| Einen Modell-Prompt mit Bildern ausführen | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | Wiederholen Sie `--file` für mehrere Bildeingaben |
| Ein Bild generieren | `openclaw infer image generate --prompt "..." --json` | Verwenden Sie `image edit`, wenn Sie mit einer bestehenden Datei beginnen |
| Eine Bilddatei beschreiben | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` muss ein bildfähiges `<provider/model>` sein |
| Audio transkribieren | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` muss `<provider/model>` sein |
| Sprache synthetisieren | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` ist Gateway-orientiert |
@ -131,19 +134,19 @@ Diese Tabelle ordnet gängige Inferenzaufgaben dem entsprechenden infer-Befehl z
- Verwenden Sie `--json`, wenn die Ausgabe von einem anderen Befehl oder Skript verarbeitet wird.
- Verwenden Sie `--provider` oder `--model provider/model`, wenn ein bestimmtes Backend erforderlich ist.
- Für `image describe`, `audio transcribe` und `video describe` muss `--model` die Form `<provider/model>` verwenden.
- Bei `image describe` führt ein explizites `--model` dieses Provider/Modell direkt aus. Das Modell muss im Modellkatalog oder in der Provider-Konfiguration bildfähig sein. `codex/<model>` führt einen begrenzten Bildverständnis-Turn über den Codex-App-Server aus; `openai-codex/<model>` verwendet den OpenAI-Codex-OAuth-Provider-Pfad.
- Für `image describe` führt ein explizites `--model` dieses Provider/Modell direkt aus. Das Modell muss im Modellkatalog oder in der Provider-Konfiguration bildfähig sein. `codex/<model>` führt einen begrenzten Codex-App-Server-Turn zum Bildverständnis aus; `openai-codex/<model>` verwendet den OpenAI Codex-OAuth-Provider-Pfad.
- Zustandslose Ausführungsbefehle verwenden standardmäßig lokal.
- Gateway-verwaltete Zustandsbefehle verwenden standardmäßig den Gateway.
- Der normale lokale Pfad erfordert nicht, dass der Gateway läuft.
- Lokales `model run` ist eine schlanke einmalige Provider-Vervollständigung. Es löst das konfigurierte Agent-Modell und die Authentifizierung auf, startet aber keinen Chat-Agent-Turn, lädt keine Tools und öffnet keine gebündelten MCP-Server.
- Lokales `model run` ist ein schlanker einmaliger Provider-Completion-Aufruf. Er löst das konfigurierte Agent-Modell und die Authentifizierung auf, startet aber keinen Chat-Agent-Turn, lädt keine Tools und öffnet keine gebündelten MCP-Server.
- `model run --file` akzeptiert Bilddateien, erkennt deren MIME-Typ und sendet sie mit dem angegebenen Prompt an das ausgewählte Modell. Wiederholen Sie `--file` für mehrere Bilder.
- `model run --file` lehnt Nicht-Bildeingaben ab. Verwenden Sie `infer audio transcribe` für Audiodateien und `infer video describe` für Videodateien.
- `model run --gateway` übt Gateway-Routing, gespeicherte Authentifizierung, Provider-Auswahl und die eingebettete Laufzeit aus, läuft aber weiterhin als roher Modell-Probe: Es sendet den angegebenen Prompt und alle Bildanhänge ohne vorheriges Sitzungstranskript, Bootstrap-/AGENTS-Kontext, Context-Engine-Assembly, Tools oder gebündelte MCP-Server.
- `model run --gateway --model <provider/model>` erfordert vertrauenswürdige Operator-Gateway-Anmeldedaten, da die Anfrage den Gateway auffordert, eine einmalige Provider/Modell-Überschreibung auszuführen.
- `model run --gateway` prüft Gateway-Routing, gespeicherte Authentifizierung, Provider-Auswahl und die eingebettete Laufzeitumgebung, läuft aber weiterhin als roher Modell-Probe: Es sendet den angegebenen Prompt und alle Bildanhänge ohne vorheriges Sitzungstranskript, Bootstrap-/AGENTS-Kontext, Context-Engine-Assembly, Tools oder gebündelte MCP-Server.
- `model run --gateway --model <provider/model>` erfordert eine vertrauenswürdige Operator-Gateway-Anmeldeinformation, da die Anfrage den Gateway auffordert, eine einmalige Provider/Modell-Überschreibung auszuführen.
## Modell
Verwenden Sie `model` für Provider-gestützte Textinferenz und Modell-/Provider-Inspektion.
Verwenden Sie `model` für Provider-gestützte Textinferenz und die Prüfung von Modell/Provider.
```bash
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
@ -153,7 +156,8 @@ openclaw infer model providers --json
openclaw infer model inspect --name gpt-5.5 --json
```
Verwenden Sie vollständige `<provider/model>`-Referenzen, um einen bestimmten Provider per Smoke-Test zu prüfen, ohne den Gateway zu starten oder die vollständige Agent-Tool-Oberfläche zu laden:
Verwenden Sie vollständige `<provider/model>`-Referenzen, um einen bestimmten Provider zu smoke-testen, ohne
den Gateway zu starten oder die vollständige Agent-Tool-Oberfläche zu laden:
```bash
openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json
@ -167,14 +171,15 @@ openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe
Hinweise:
- Lokales `model run` ist der engste CLI-Smoke-Test für Provider-/Modell-/Auth-Gesundheit, weil es nur den angegebenen Prompt an das ausgewählte Modell sendet.
- Lokales `model run` ist der engste CLI-Smoke für den Zustand von Provider/Modell/Auth, weil es bei Nicht-Codex-Providern nur den angegebenen Prompt an das ausgewählte Modell sendet.
- Lokale `openai-codex/*`-Probes sind die schmale Ausnahme: OpenClaw fügt eine minimale Systemanweisung hinzu, damit der Codex-Responses-Transport sein erforderliches Feld `instructions` befüllen kann, ohne vollständigen Agent-Kontext, Tools, Memory oder Sitzungstranskript hinzuzufügen.
- Lokales `model run --file` behält diesen schlanken Pfad bei und hängt Bildinhalte direkt an die einzelne Benutzernachricht an. Gängige Bilddateien wie PNG, JPEG und WebP funktionieren, wenn ihr MIME-Typ als `image/*` erkannt wird; nicht unterstützte oder nicht erkannte Dateien schlagen fehl, bevor der Provider aufgerufen wird.
- `model run --file` ist am besten geeignet, wenn Sie das ausgewählte multimodale Textmodell direkt testen möchten. Verwenden Sie `infer image describe`, wenn Sie OpenClaws Provider-Auswahl für Bildverständnis und das Standard-Routing für Bildmodelle verwenden möchten.
- `model run --file` eignet sich am besten, wenn Sie das ausgewählte multimodale Textmodell direkt testen möchten. Verwenden Sie `infer image describe`, wenn Sie die Bildverständnis-Provider-Auswahl von OpenClaw und das standardmäßige Bildmodell-Routing verwenden möchten.
- Das ausgewählte Modell muss Bildeingaben unterstützen; reine Textmodelle können die Anfrage auf Provider-Ebene ablehnen.
- `model run --prompt` muss Text enthalten, der nicht nur aus Leerraum besteht; leere Prompts werden abgelehnt, bevor lokale Provider oder der Gateway aufgerufen werden.
- Lokales `model run` wird mit einem Nicht-Null-Exitcode beendet, wenn der Provider keine Textausgabe zurückgibt, sodass nicht erreichbare lokale Provider und leere Vervollständigungen nicht wie erfolgreiche Probes aussehen.
- Verwenden Sie `model run --gateway`, wenn Sie Gateway-Routing, Agent-Runtime-Setup oder Gateway-verwalteten Provider-Zustand testen müssen, während die Modelleingabe roh bleibt. Verwenden Sie `openclaw agent` oder Chat-Oberflächen, wenn Sie den vollständigen Agent-Kontext, Tools, Speicher und Sitzungstranskript möchten.
- `model auth login`, `model auth logout` und `model auth status` verwalten gespeicherten Provider-Authentifizierungszustand.
- Lokales `model run` beendet sich mit einem von null verschiedenen Exit-Code, wenn der Provider keine Textausgabe zurückgibt, sodass nicht erreichbare lokale Provider und leere Completions nicht wie erfolgreiche Probes aussehen.
- Verwenden Sie `model run --gateway`, wenn Sie Gateway-Routing, Agent-Laufzeit-Setup oder Gateway-verwalteten Provider-Zustand testen müssen, während die Modelleingabe roh bleibt. Verwenden Sie `openclaw agent` oder Chat-Oberflächen, wenn Sie den vollständigen Agent-Kontext, Tools, Memory und das Sitzungstranskript wünschen.
- `model auth login`, `model auth logout` und `model auth status` verwalten den gespeicherten Provider-Auth-Zustand.
## Bild
@ -196,11 +201,18 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --p
Hinweise:
- Verwenden Sie `image edit`, wenn Sie von vorhandenen Eingabedateien starten.
- Verwenden Sie `--size`, `--aspect-ratio` oder `--resolution` mit `image edit` für Provider/Modelle, die Geometriehinweise bei Referenzbild-Bearbeitungen unterstützen.
- Verwenden Sie `--output-format png --background transparent` mit `--model openai/gpt-image-1.5` für OpenAI-PNG-Ausgaben mit transparentem Hintergrund; `--openai-background` bleibt als OpenAI-spezifischer Alias verfügbar. Provider, die keine Hintergrundunterstützung deklarieren, melden den Hinweis als ignorierte Überschreibung.
- Verwenden Sie `image providers --json`, um zu prüfen, welche gebündelten Bild-Provider auffindbar, konfiguriert und ausgewählt sind und welche Generierungs-/Bearbeitungs-Capabilities jeder Provider bereitstellt.
- Verwenden Sie `image generate --model <provider/model> --json` als engsten Live-CLI-Smoke-Test für Änderungen an der Bildgenerierung. Beispiel:
- Verwenden Sie `image edit`, wenn Sie mit vorhandenen Eingabedateien starten.
- Verwenden Sie `--size`, `--aspect-ratio` oder `--resolution` mit `image edit` für
Provider/Modelle, die Geometriehinweise bei Bearbeitungen von Referenzbildern unterstützen.
- Verwenden Sie `--output-format png --background transparent` mit
`--model openai/gpt-image-1.5` für OpenAI-PNG-Ausgaben mit transparentem Hintergrund;
`--openai-background` bleibt als OpenAI-spezifischer Alias verfügbar. Provider,
die keine Hintergrundunterstützung deklarieren, melden den Hinweis als ignorierte Überschreibung.
- Verwenden Sie `image providers --json`, um zu prüfen, welche gebündelten Bild-Provider
auffindbar, konfiguriert und ausgewählt sind und welche Generierungs-/Bearbeitungsfunktionen
jeder Provider bereitstellt.
- Verwenden Sie `image generate --model <provider/model> --json` als den schmalsten Live-
CLI-Smoke-Test für Änderungen an der Bildgenerierung. Beispiel:
```bash
openclaw infer image providers --json
@ -215,14 +227,14 @@ Hinweise:
Ausgabepfade. Wenn `--output` gesetzt ist, kann die finale Erweiterung dem
vom Provider zurückgegebenen MIME-Typ folgen.
- Verwenden Sie für `image describe` und `image describe-many` `--prompt`, um dem Vision-Modell eine aufgabenspezifische Anweisung wie OCR, Vergleich, UI-Inspektion oder knappe Bildbeschriftung zu geben.
- Verwenden Sie `--timeout-ms` bei langsamen lokalen Vision-Modellen oder Kaltstarts von Ollama.
- Verwenden Sie für `image describe` und `image describe-many` `--prompt`, um dem Vision-Modell eine aufgabenspezifische Anweisung wie OCR, Vergleich, UI-Prüfung oder knappe Beschriftung zu geben.
- Verwenden Sie `--timeout-ms` bei langsamen lokalen Vision-Modellen oder kalten Ollama-Starts.
- Für `image describe` muss `--model` ein bildfähiges `<provider/model>` sein.
- Für lokale Ollama-Vision-Modelle laden Sie zuerst das Modell herunter und setzen Sie `OLLAMA_API_KEY` auf einen beliebigen Platzhalterwert, zum Beispiel `ollama-local`. Siehe [Ollama](/de/providers/ollama#vision-and-image-description).
## Audio
Verwenden Sie `audio` für die Dateitranskription.
Verwenden Sie `audio` für Dateitranskription.
```bash
openclaw infer audio transcribe --file ./memo.m4a --json
@ -232,7 +244,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
Hinweise:
- `audio transcribe` ist für die Dateitranskription vorgesehen, nicht für Echtzeit-Sitzungsverwaltung.
- `audio transcribe` ist für Dateitranskription gedacht, nicht für Realtime-Sitzungsverwaltung.
- `--model` muss `<provider/model>` sein.
## TTS
@ -264,12 +276,12 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js
Hinweise:
- `video generate` akzeptiert `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` und `--timeout-ms` und leitet sie an die Laufzeit für Videogenerierung weiter.
- `video generate` akzeptiert `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` und `--timeout-ms` und leitet sie an die Video-Generierungs-Runtime weiter.
- `--model` muss für `video describe` `<provider/model>` sein.
## Web
Verwenden Sie `web` für Such- und Abruf-Workflows.
Verwenden Sie `web` für Such- und Fetch-Workflows.
```bash
openclaw infer web search --query "OpenClaw docs" --json
@ -284,7 +296,7 @@ Hinweise:
## Embedding
Verwenden Sie `embedding` für die Vektorerstellung und die Prüfung von Embedding-Providern.
Verwenden Sie `embedding` für Vektorerstellung und Prüfung von Embedding-Providern.
```bash
openclaw infer embedding create --text "friendly lobster" --json
@ -294,7 +306,7 @@ openclaw infer embedding providers --json
## JSON-Ausgabe
Infer-Befehle normalisieren die JSON-Ausgabe unter einer gemeinsamen Hülle:
Infer-Befehle normalisieren JSON-Ausgaben unter einer gemeinsamen Hülle:
```json
{
@ -319,9 +331,9 @@ Felder auf oberster Ebene sind stabil:
- `outputs`
- `error`
Für Befehle, die Medien generieren, enthält `outputs` Dateien, die von OpenClaw geschrieben wurden. Verwenden Sie
`path`, `mimeType`, `size` und alle medienspezifischen Abmessungen in diesem Array
für Automatisierung, statt menschenlesbare stdout-Ausgaben zu parsen.
Für Befehle zur Mediengenerierung enthält `outputs` Dateien, die von OpenClaw geschrieben wurden. Verwenden Sie
für Automatisierung `path`, `mimeType`, `size` und alle medienspezifischen Dimensionen in diesem Array,
anstatt menschenlesbares stdout zu parsen.
## Häufige Fallstricke
@ -345,7 +357,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
- `openclaw capability ...` ist ein Alias für `openclaw infer ...`.
## Verwandte Themen
## Verwandt
- [CLI-Referenz](/de/cli)
- [Modelle](/de/concepts/models)

174
docs/de/cli/plugins.md
View File

@ -1,33 +1,33 @@
---
read_when:
- Sie möchten Gateway-Plugins oder kompatible Bundles installieren oder verwalten
- Sie möchten Ladefehler von Plugins debuggen
- Sie möchten Plugin-Ladefehler debuggen
sidebarTitle: Plugins
summary: CLI-Referenz für `openclaw plugins` (auflisten, installieren, Marketplace, deinstallieren, aktivieren/deaktivieren, Diagnose)
summary: CLI-Referenz für `openclaw plugins` (auflisten, installieren, Marketplace, deinstallieren, aktivieren/deaktivieren, doctor)
title: Plugins
x-i18n:
generated_at: "2026-05-05T01:44:20Z"
generated_at: "2026-05-06T09:03:02Z"
model: gpt-5.5
provider: openai
source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a
source_hash: e584092c6cdaf87681aef2ed106c299e3bab0552305b669c66b05deb61bf25ce
source_path: cli/plugins.md
workflow: 16
---
Verwalten Sie Gateway-Plugins, Hook-Packs und kompatible Bundles.
Plugins, Hook-Packs und kompatible Bundles für das Gateway verwalten.
<CardGroup cols={2}>
<Card title="Plugin-System" href="/de/tools/plugin">
Leitfaden für Endbenutzer zum Installieren, Aktivieren und Beheben von Problemen mit Plugins.
</Card>
<Card title="Plugins verwalten" href="/de/plugins/manage-plugins">
Kurze Beispiele für Installation, Auflisten, Aktualisieren, Deinstallieren und Veröffentlichen.
Kurze Beispiele für Installation, Auflisten, Aktualisierung, Deinstallation und Veröffentlichung.
</Card>
<Card title="Plugin-Bundles" href="/de/plugins/bundles">
Kompatibilitätsmodell für Bundles.
</Card>
<Card title="Plugin-Manifest" href="/de/plugins/manifest">
Manifest-Felder und Konfigurationsschema.
Manifestfelder und Konfigurationsschema.
</Card>
<Card title="Sicherheit" href="/de/gateway/security">
Sicherheitshärtung für Plugin-Installationen.
@ -62,14 +62,14 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Führen Sie für die Untersuchung langsamer Installations-, Inspektions-, Deinstallations- oder Registry-Refresh-Vorgänge den Befehl mit `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` aus. Der Trace schreibt Phasenzeiten nach stderr und hält JSON-Ausgaben parsebar. Siehe [Debugging](/de/help/debugging#plugin-lifecycle-trace).
Für die Untersuchung langsamer Installations-, Inspektions-, Deinstallations- oder Registry-Aktualisierungsvorgänge führen Sie den Befehl mit `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` aus. Der Trace schreibt Phasen-Timings nach stderr und hält die JSON-Ausgabe parsebar. Siehe [Debugging](/de/help/debugging#plugin-lifecycle-trace).
<Note>
Gebündelte Plugins werden mit OpenClaw ausgeliefert. Einige sind standardmäßig aktiviert, zum Beispiel gebündelte Modell-Provider, gebündelte Sprach-Provider und das gebündelte Browser-Plugin; andere erfordern `plugins enable`.
Gebündelte Plugins werden mit OpenClaw ausgeliefert. Einige sind standardmäßig aktiviert (zum Beispiel gebündelte Modell-Provider, gebündelte Speech-Provider und das gebündelte Browser-Plugin); andere erfordern `plugins enable`.
Native OpenClaw-Plugins müssen `openclaw.plugin.json` mit einem Inline-JSON-Schema (`configSchema`, auch wenn leer) ausliefern. Kompatible Bundles verwenden stattdessen ihre eigenen Bundle-Manifeste.
Native OpenClaw-Plugins müssen `openclaw.plugin.json` mit einem Inline-JSON-Schema (`configSchema`, auch wenn es leer ist) ausliefern. Kompatible Bundles verwenden stattdessen ihre eigenen Bundle-Manifeste.
`plugins list` zeigt `Format: openclaw` oder `Format: bundle`. Ausführliche Listen-/Info-Ausgaben zeigen außerdem den Bundle-Subtyp (`codex`, `claude` oder `cursor`) sowie erkannte Bundle-Fähigkeiten.
`plugins list` zeigt `Format: openclaw` oder `Format: bundle`. Ausführliche list/info-Ausgaben zeigen außerdem den Bundle-Untertyp (`codex`, `claude` oder `cursor`) sowie erkannte Bundle-Fähigkeiten.
</Note>
### Installieren
@ -79,6 +79,7 @@ openclaw plugins search "calendar" # search ClawHub plugins
openclaw plugins install <package> # npm by default
openclaw plugins install clawhub:<package> # ClawHub only
openclaw plugins install npm:<package> # npm only
openclaw plugins install npm-pack:<path.tgz> # local npm pack through npm install semantics
openclaw plugins install git:github.com/<owner>/<repo> # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force # overwrite existing install
@ -91,62 +92,64 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
Reine Paketnamen werden während der Launch-Umstellung standardmäßig von npm installiert. Verwenden Sie `clawhub:<package>` für ClawHub. Behandeln Sie Plugin-Installationen wie das Ausführen von Code. Bevorzugen Sie gepinnte Versionen.
Bloße Paketnamen werden während der Launch-Umstellung standardmäßig aus npm installiert. Verwenden Sie `clawhub:<package>` für ClawHub. Behandeln Sie Plugin-Installationen wie das Ausführen von Code. Bevorzugen Sie gepinnte Versionen.
</Warning>
`plugins search` fragt ClawHub nach installierbaren Plugin-Paketen ab und gibt installationsbereite Paketnamen aus. Es durchsucht Code-Plugin- und Bundle-Plugin-Pakete, nicht Skills. Verwenden Sie `openclaw skills search` für ClawHub-Skills.
<Note>
ClawHub ist die primäre Oberfläche für Verteilung und Auffindbarkeit der meisten Plugins. Npm bleibt ein unterstützter Fallback und direkter Installationspfad. OpenClaw-eigene `@openclaw/*`-Plugin-Pakete werden wieder auf npm veröffentlicht; die aktuelle Liste finden Sie auf [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) oder im [Plugin-Inventar](/de/plugins/plugin-inventory). Stabile Installationen verwenden `latest`. Installationen und Updates aus dem Beta-Kanal bevorzugen den npm-`beta`-dist-tag, wenn dieses Tag verfügbar ist, und fallen dann auf `latest` zurück.
ClawHub ist die primäre Distributions- und Auffindbarkeitsoberfläche für die meisten Plugins. Npm bleibt ein unterstützter Fallback und direkter Installationspfad. OpenClaw-eigene `@openclaw/*`-Plugin-Pakete werden wieder auf npm veröffentlicht; die aktuelle Liste finden Sie auf [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) oder im [Plugin-Inventar](/de/plugins/plugin-inventory). Stabile Installationen verwenden `latest`. Installationen und Aktualisierungen im Beta-Channel bevorzugen den npm-`beta`-Dist-Tag, wenn dieser Tag verfügbar ist, und fallen dann auf `latest` zurück.
</Note>
<AccordionGroup>
<Accordion title="Konfigurations-Includes und Reparatur ungültiger Konfiguration">
Wenn Ihr Abschnitt `plugins` durch ein einzeiliges `$include` gesichert ist, schreiben `plugins install/update/enable/disable/uninstall` in diese eingebundene Datei durch und lassen `openclaw.json` unverändert. Root-Includes, Include-Arrays und Includes mit benachbarten Überschreibungen schlagen geschlossen fehl, statt abgeflacht zu werden. Siehe [Konfigurations-Includes](/de/gateway/configuration) für die unterstützten Formen.
<Accordion title="Konfigurations-Includes und Reparatur ungültiger Konfigurationen">
Wenn Ihr `plugins`-Abschnitt durch ein einzeiliges `$include` gestützt wird, schreiben `plugins install/update/enable/disable/uninstall` in diese eingebundene Datei durch und lassen `openclaw.json` unverändert. Root-Includes, Include-Arrays und Includes mit überschreibenden Geschwistern schlagen geschlossen fehl, statt abgeflacht zu werden. Siehe [Config includes](/de/gateway/configuration) für die unterstützten Formen.
Wenn die Konfiguration während der Installation ungültig ist, schlägt `plugins install` normalerweise geschlossen fehl und weist Sie an, zuerst `openclaw doctor --fix` auszuführen. Beim Gateway-Start und beim Hot Reload schlägt eine ungültige Plugin-Konfiguration wie jede andere ungültige Konfiguration geschlossen fehl; `openclaw doctor --fix` kann den ungültigen Plugin-Eintrag quarantänisieren. Die einzige dokumentierte Ausnahme zur Installationszeit ist ein enger Wiederherstellungspfad für gebündelte Plugins, die sich ausdrücklich für `openclaw.install.allowInvalidConfigRecovery` entscheiden.
Wenn die Konfiguration während der Installation ungültig ist, schlägt `plugins install` normalerweise geschlossen fehl und weist Sie an, zuerst `openclaw doctor --fix` auszuführen. Während des Gateway-Starts und Hot Reload schlägt eine ungültige Plugin-Konfiguration wie jede andere ungültige Konfiguration geschlossen fehl; `openclaw doctor --fix` kann den ungültigen Plugin-Eintrag isolieren. Die einzige dokumentierte Ausnahme zur Installationszeit ist ein enger Wiederherstellungspfad für gebündelte Plugins, die sich explizit für `openclaw.install.allowInvalidConfigRecovery` entscheiden.
</Accordion>
<Accordion title="--force und Neuinstallation gegenüber Update">
`--force` verwendet das vorhandene Installationsziel wieder und überschreibt ein bereits installiertes Plugin oder Hook-Pack direkt. Verwenden Sie es, wenn Sie absichtlich dieselbe ID aus einem neuen lokalen Pfad, Archiv, ClawHub-Paket oder npm-Artefakt neu installieren. Für routinemäßige Upgrades eines bereits nachverfolgten npm-Plugins bevorzugen Sie `openclaw plugins update <id-or-npm-spec>`.
<Accordion title="--force und Neuinstallation gegenüber Aktualisierung">
`--force` verwendet das vorhandene Installationsziel wieder und überschreibt ein bereits installiertes Plugin oder Hook-Pack direkt. Verwenden Sie es, wenn Sie dieselbe id absichtlich von einem neuen lokalen Pfad, Archiv, ClawHub-Paket oder npm-Artefakt neu installieren. Für routinemäßige Upgrades eines bereits nachverfolgten npm-Plugins bevorzugen Sie `openclaw plugins update <id-or-npm-spec>`.
Wenn Sie `plugins install` für eine bereits installierte Plugin-ID ausführen, hält OpenClaw an und verweist Sie für ein normales Upgrade auf `plugins update <id-or-npm-spec>` oder auf `plugins install <package> --force`, wenn Sie die aktuelle Installation wirklich aus einer anderen Quelle überschreiben möchten.
Wenn Sie `plugins install` für eine bereits installierte Plugin-id ausführen, stoppt OpenClaw und verweist Sie für ein normales Upgrade auf `plugins update <id-or-npm-spec>` oder auf `plugins install <package> --force`, wenn Sie die aktuelle Installation wirklich aus einer anderen Quelle überschreiben möchten.
</Accordion>
<Accordion title="Geltungsbereich von --pin">
`--pin` gilt nur für npm-Installationen. Es wird bei `git:`-Installationen nicht unterstützt; verwenden Sie eine explizite Git-Ref wie `git:github.com/acme/plugin@v1.2.3`, wenn Sie eine gepinnte Quelle möchten. Es wird mit `--marketplace` nicht unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation speichern.
`--pin` gilt nur für npm-Installationen. Es wird bei `git:`-Installationen nicht unterstützt; verwenden Sie eine explizite Git-Ref wie `git:github.com/acme/plugin@v1.2.3`, wenn Sie eine gepinnte Quelle wünschen. Es wird bei `--marketplace` nicht unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation speichern.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` ist eine Notfalloption für False Positives im integrierten Scanner für gefährlichen Code. Sie erlaubt, dass die Installation fortgesetzt wird, auch wenn der integrierte Scanner `critical`-Befunde meldet, umgeht aber **keine** Policy-Sperren von Plugin-`before_install`-Hooks und umgeht **keine** Scan-Fehlschläge.
`--dangerously-force-unsafe-install` ist eine Notfalloption für False Positives im integrierten Scanner für gefährlichen Code. Sie erlaubt, dass die Installation fortgesetzt wird, auch wenn der integrierte Scanner `critical`-Funde meldet, aber sie umgeht **nicht** Policy-Blockaden durch Plugin-`before_install`-Hooks und umgeht **nicht** Scan-Fehler.
Dieses CLI-Flag gilt für Plugin-Installations-/Update-Flows. Gateway-gestützte Skill-Abhängigkeitsinstallationen verwenden die passende Request-Überschreibung `dangerouslyForceUnsafeInstall`, während `openclaw skills install` ein separater ClawHub-Skill-Download-/Installations-Flow bleibt.
Dieses CLI-Flag gilt für Plugin-Installations- und Aktualisierungsabläufe. Gateway-gestützte Skill-Abhängigkeitsinstallationen verwenden die entsprechende `dangerouslyForceUnsafeInstall`-Request-Überschreibung, während `openclaw skills install` ein separater ClawHub-Skill-Download-/Installationsablauf bleibt.
Wenn ein von Ihnen auf ClawHub veröffentlichtes Plugin durch einen Registry-Scan blockiert wird, verwenden Sie die Publisher-Schritte in [ClawHub](/de/tools/clawhub).
</Accordion>
<Accordion title="Hook-Packs und npm-Spezifikationen">
`plugins install` ist auch die Installationsoberfläche für Hook-Packs, die `openclaw.hooks` in `package.json` bereitstellen. Verwenden Sie `openclaw hooks` für gefilterte Hook-Sichtbarkeit und Aktivierung einzelner Hooks, nicht für Paketinstallationen.
`plugins install` ist auch die Installationsoberfläche für Hook-Packs, die `openclaw.hooks` in `package.json` bereitstellen. Verwenden Sie `openclaw hooks` für gefilterte Hook-Sichtbarkeit und Aktivierung pro Hook, nicht für Paketinstallation.
Npm-Spezifikationen sind **nur Registry** (Paketname + optionale **exakte Version** oder **dist-tag**). Git-/URL-/Datei-Spezifikationen und Semver-Bereiche werden abgelehnt. Abhängigkeitsinstallationen laufen aus Sicherheitsgründen projektlokal mit `--ignore-scripts`, selbst wenn Ihre Shell globale npm-Installationseinstellungen hat.
Npm-Spezifikationen sind **nur Registry** (Paketname plus optionale **exakte Version** oder **Dist-Tag**). Git-/URL-/Datei-Spezifikationen und Semver-Bereiche werden abgelehnt. Abhängigkeitsinstallationen laufen zur Sicherheit projektlokal mit `--ignore-scripts`, selbst wenn Ihre Shell globale npm-Installationseinstellungen hat.
Verwenden Sie `npm:<package>`, wenn Sie die npm-Auflösung explizit machen möchten. Reine Paketspezifikationen werden während der Launch-Umstellung ebenfalls direkt von npm installiert.
Verwenden Sie `npm:<package>`, wenn Sie die npm-Auflösung explizit machen möchten. Bloße Paketspezifikationen werden während der Launch-Umstellung ebenfalls direkt aus npm installiert.
Reine Spezifikationen und `@latest` bleiben auf dem stabilen Track. Datumsstempel-Korrekturversionen von OpenClaw wie `2026.5.3-1` sind für diese Prüfung stabile Releases. Wenn npm eines davon zu einem Prerelease auflöst, hält OpenClaw an und fordert Sie auf, explizit mit einem Prerelease-Tag wie `@beta`/`@rc` oder einer exakten Prerelease-Version wie `@1.2.3-beta.4` zuzustimmen.
Bloße Spezifikationen und `@latest` bleiben auf dem stabilen Track. OpenClaw-datumsgeprägte Korrekturversionen wie `2026.5.3-1` sind für diese Prüfung stabile Releases. Wenn npm eine dieser Varianten zu einem Prerelease auflöst, stoppt OpenClaw und fordert Sie auf, sich explizit mit einem Prerelease-Tag wie `@beta`/`@rc` oder einer exakten Prerelease-Version wie `@1.2.3-beta.4` anzumelden.
Wenn eine reine Installationsspezifikation mit einer offiziellen Plugin-ID übereinstimmt, zum Beispiel `diffs`, installiert OpenClaw den Katalogeintrag direkt. Um ein npm-Paket mit demselben Namen zu installieren, verwenden Sie eine explizite bereichsbezogene Spezifikation, zum Beispiel `@scope/diffs`.
Wenn eine bloße Installationsspezifikation mit einer offiziellen Plugin-id übereinstimmt (zum Beispiel `diffs`), installiert OpenClaw den Katalogeintrag direkt. Um ein npm-Paket mit demselben Namen zu installieren, verwenden Sie eine explizite Scoped-Spezifikation (zum Beispiel `@scope/diffs`).
</Accordion>
<Accordion title="Git-Repositorys">
Verwenden Sie `git:<repo>`, um direkt aus einem Git-Repository zu installieren. Unterstützte Formen umfassen `git:github.com/owner/repo`, `git:owner/repo`, vollständige `https://`-, `ssh://`-, `git://`-, `file://`- und `git@host:owner/repo.git`-Clone-URLs. Fügen Sie `@<ref>` oder `#<ref>` hinzu, um vor der Installation einen Branch, ein Tag oder einen Commit auszuchecken.
Verwenden Sie `git:<repo>`, um direkt aus einem Git-Repository zu installieren. Unterstützte Formen umfassen `git:github.com/owner/repo`, `git:owner/repo`, vollständige `https://`-, `ssh://`-, `git://`-, `file://`- und `git@host:owner/repo.git`-Clone-URLs. Fügen Sie `@<ref>` oder `#<ref>` hinzu, um vor der Installation einen Branch, Tag oder Commit auszuchecken.
Git-Installationen klonen in ein temporäres Verzeichnis, checken die angeforderte Ref aus, wenn vorhanden, und verwenden dann den normalen Plugin-Verzeichnis-Installer. Das bedeutet, dass Manifest-Validierung, Scans auf gefährlichen Code, Package-Manager-Installationsarbeit und Installationsdatensätze sich wie bei npm-Installationen verhalten. Aufgezeichnete Git-Installationen enthalten die Quell-URL/-Ref plus den aufgelösten Commit, damit `openclaw plugins update` die Quelle später erneut auflösen kann.
Git-Installationen klonen in ein temporäres Verzeichnis, checken die angeforderte Ref aus, falls vorhanden, und verwenden dann den normalen Installer für Plugin-Verzeichnisse. Das bedeutet, dass Manifestvalidierung, Scannen auf gefährlichen Code, Paketmanager-Installationsarbeit und Installationsdatensätze sich wie npm-Installationen verhalten. Aufgezeichnete Git-Installationen enthalten die Quell-URL/Ref sowie den aufgelösten Commit, damit `openclaw plugins update` die Quelle später erneut auflösen kann.
Verwenden Sie nach der Installation aus Git `openclaw plugins inspect <id> --runtime --json`, um Laufzeitregistrierungen wie Gateway-Methoden und CLI-Befehle zu prüfen. Wenn das Plugin mit `api.registerCli` eine CLI-Root registriert hat, führen Sie diesen Befehl direkt über die OpenClaw-Root-CLI aus, zum Beispiel `openclaw demo-plugin ping`.
Nach der Installation aus Git verwenden Sie `openclaw plugins inspect <id> --runtime --json`, um Runtime-Registrierungen wie Gateway-Methoden und CLI-Befehle zu prüfen. Wenn das Plugin mit `api.registerCli` eine CLI-Root registriert hat, führen Sie diesen Befehl direkt über die OpenClaw-Root-CLI aus, zum Beispiel `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="Archive">
Unterstützte Archive: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Native OpenClaw-Plugin-Archive müssen ein gültiges `openclaw.plugin.json` im extrahierten Plugin-Root enthalten; Archive, die nur `package.json` enthalten, werden abgelehnt, bevor OpenClaw Installationsdatensätze schreibt.
Verwenden Sie `npm-pack:<path.tgz>`, wenn die Datei ein npm-pack-Tarball ist und Sie denselben verwalteten npm-Root-Installationspfad testen möchten, der von Registry-Installationen verwendet wird, einschließlich `package-lock.json`-Verifizierung, Scannen gehobener Abhängigkeiten und npm-Installationsdatensätzen. Einfache Archivpfade werden weiterhin als lokale Archive unter dem Plugin-Erweiterungs-Root installiert.
Claude-Marketplace-Installationen werden ebenfalls unterstützt.
</Accordion>
@ -159,20 +162,20 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
Reine npm-sichere Plugin-Spezifikationen werden während der Launch-Umstellung standardmäßig von npm installiert:
Bloße npm-sichere Plugin-Spezifikationen werden während der Launch-Umstellung standardmäßig aus npm installiert:
```bash
openclaw plugins install openclaw-codex-app-server
```
Verwenden Sie `npm:`, um die Nur-npm-Auflösung explizit zu machen:
Verwenden Sie `npm:`, um eine reine npm-Auflösung explizit zu machen:
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw prüft die beworbene Plugin-API-/Mindest-Gateway-Kompatibilität vor der Installation. Wenn die ausgewählte ClawHub-Version ein ClawPack-Artefakt veröffentlicht, lädt OpenClaw das versionierte npm-pack-`.tgz` herunter, prüft den ClawHub-Digest-Header und den Artefakt-Digest und installiert es dann über den normalen Archivpfad. Ältere ClawHub-Versionen ohne ClawPack-Metadaten werden weiterhin über den alten Pfad zur Paketarchivprüfung installiert. Aufgezeichnete Installationen behalten ihre ClawHub-Quellmetadaten, Artefaktart, npm-Integrität, npm-Shasum, Tarball-Namen und ClawPack-Digest-Fakten für spätere Updates.
OpenClaw prüft die beworbene Plugin-API-/Mindest-Gateway-Kompatibilität vor der Installation. Wenn die ausgewählte ClawHub-Version ein ClawPack-Artefakt veröffentlicht, lädt OpenClaw das versionierte npm-pack-`.tgz` herunter, verifiziert den ClawHub-Digest-Header und den Artefakt-Digest und installiert es dann über den normalen Archivpfad. Ältere ClawHub-Versionen ohne ClawPack-Metadaten werden weiterhin über den Legacy-Paketarchiv-Verifizierungspfad installiert. Aufgezeichnete Installationen behalten ihre ClawHub-Quellmetadaten, Artefaktart, npm-Integrität, npm-shasum, Tarball-Namen und ClawPack-Digest-Fakten für spätere Aktualisierungen.
Unversionierte ClawHub-Installationen behalten eine unversionierte aufgezeichnete Spezifikation, damit `openclaw plugins update` neueren ClawHub-Releases folgen kann; explizite Versions- oder Tag-Selektoren wie `clawhub:pkg@1.2.3` und `clawhub:pkg@beta` bleiben an diesen Selektor gepinnt.
#### Marketplace-Kurzform
@ -194,16 +197,16 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="Marketplace-Quellen">
- ein Claude-Name eines bekannten Marketplace aus `~/.claude/plugins/known_marketplaces.json`
- ein lokaler Marketplace-Stammordner oder `marketplace.json`-Pfad
- eine GitHub-Repository-Kurzform wie `owner/repo`
- eine GitHub-Repository-URL wie `https://github.com/owner/repo`
<Tab title="Marketplace sources">
- ein Claude-Name für bekannte Marketplaces aus `~/.claude/plugins/known_marketplaces.json`
- ein lokaler Marketplace-Root oder ein `marketplace.json`-Pfad
- ein GitHub-Repo-Kürzel wie `owner/repo`
- eine GitHub-Repo-URL wie `https://github.com/owner/repo`
- eine Git-URL
</Tab>
<Tab title="Regeln für Remote-Marketplaces">
Für Remote-Marketplaces, die von GitHub oder Git geladen werden, müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repositorys bleiben. OpenClaw akzeptiert relative Pfadquellen aus diesem Repository und weist HTTP(S)-, absolute Pfad-, Git-, GitHub- und andere Nicht-Pfad-Plugin-Quellen aus Remote-Manifesten zurück.
<Tab title="Remote marketplace rules">
Bei Remote-Marketplaces, die aus GitHub oder Git geladen werden, müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repos bleiben. OpenClaw akzeptiert relative Pfadquellen aus diesem Repo und lehnt HTTP(S)-, absolute Pfad-, Git-, GitHub- und andere Nicht-Pfad-Plugin-Quellen aus Remote-Manifesten ab.
</Tab>
</Tabs>
@ -215,7 +218,7 @@ Für lokale Pfade und Archive erkennt OpenClaw automatisch:
- Cursor-kompatible Bundles (`.cursor-plugin/plugin.json`)
<Note>
Kompatible Bundles werden im normalen Plugin-Stammverzeichnis installiert und nehmen am selben Ablauf für Auflisten/Info/Aktivieren/Deaktivieren teil. Derzeit werden Bundle-Skills, Claude-Befehls-Skills, Claude-Standardwerte aus `settings.json`, Claude-Standardwerte aus `.lsp.json` / per Manifest deklarierte `lspServers`, Cursor-Befehls-Skills und kompatible Codex-Hook-Verzeichnisse unterstützt; andere erkannte Bundle-Fähigkeiten werden in Diagnosen/Info angezeigt, sind aber noch nicht in die Laufzeitausführung eingebunden.
Kompatible Bundles werden im normalen Plugin-Root installiert und nehmen am selben List-/Info-/Aktivieren-/Deaktivieren-Ablauf teil. Heute werden Bundle-Skills, Claude-Befehls-Skills, Claude-`settings.json`-Defaults, Claude-`.lsp.json`-/im Manifest deklarierte `lspServers`-Defaults, Cursor-Befehls-Skills und kompatible Codex-Hook-Verzeichnisse unterstützt; andere erkannte Bundle-Fähigkeiten werden in Diagnose/Info angezeigt, sind aber noch nicht in die Runtime-Ausführung eingebunden.
</Note>
### Auflisten
@ -237,53 +240,54 @@ openclaw plugins search <query> --json
Von der Tabellenansicht zu Detailzeilen pro Plugin mit Metadaten zu Quelle/Ursprung/Version/Aktivierung wechseln.
</ParamField>
<ParamField path="--json" type="boolean">
Maschinenlesbarer Bestand plus Registrierungsdiagnosen und Installationsstatus der Paketabhängigkeiten.
Maschinenlesbares Inventar plus Registry-Diagnosen und Installationsstatus von Paketabhängigkeiten.
</ParamField>
<Note>
`plugins list` liest zuerst die persistierte lokale Plugin-Registry, mit einem nur aus Manifesten abgeleiteten Fallback, wenn die Registry fehlt oder ungültig ist. Das ist nützlich, um zu prüfen, ob ein Plugin installiert, aktiviert und für die Planung eines Kaltstarts sichtbar ist, aber es ist keine Live-Laufzeitprüfung eines bereits laufenden Gateway-Prozesses. Nachdem Sie Plugin-Code, Aktivierung, Hook-Richtlinie oder `plugins.load.paths` geändert haben, starten Sie den Gateway neu, der den Kanal bereitstellt, bevor Sie erwarten, dass neuer `register(api)`-Code oder Hooks ausgeführt werden. Prüfen Sie bei Remote-/Container-Bereitstellungen, dass Sie den tatsächlichen `openclaw gateway run`-Kindprozess neu starten, nicht nur einen Wrapper-Prozess.
`plugins list` liest zuerst die dauerhaft gespeicherte lokale Plugin-Registry, mit einem nur aus Manifesten abgeleiteten Fallback, wenn die Registry fehlt oder ungültig ist. Das ist nützlich, um zu prüfen, ob ein Plugin installiert, aktiviert und für die Kaltstartplanung sichtbar ist, aber es ist keine Live-Runtime-Prüfung eines bereits laufenden Gateway-Prozesses. Nachdem Sie Plugin-Code, Aktivierung, Hook-Richtlinie oder `plugins.load.paths` geändert haben, starten Sie das Gateway neu, das den Kanal bedient, bevor Sie erwarten, dass neuer `register(api)`-Code oder Hooks ausgeführt werden. Prüfen Sie bei Remote-/Container-Deployments, dass Sie den tatsächlichen `openclaw gateway run`-Kindprozess neu starten, nicht nur einen Wrapper-Prozess.
`plugins list --json` enthält für jedes Plugin den `dependencyStatus` aus `package.json`
`dependencies` und `optionalDependencies`. OpenClaw prüft, ob diese Paketnamen
entlang des normalen Node-`node_modules`-Suchpfads des Plugins vorhanden sind; es
importiert keinen Plugin-Laufzeitcode, führt keinen Paketmanager aus und repariert
fehlende Abhängigkeiten nicht.
entlang des normalen Node-`node_modules`-Lookup-Pfads des Plugins vorhanden sind; es
importiert keinen Plugin-Runtime-Code, führt keinen Paketmanager aus und repariert
keine fehlenden Abhängigkeiten.
</Note>
`plugins search` ist eine Remote-ClawHub-Katalogsuche. Sie prüft keinen lokalen
Zustand, ändert keine Konfiguration, installiert keine Pakete und lädt keinen
Plugin-Laufzeitcode. Suchergebnisse enthalten den ClawHub-Paketnamen, die Familie,
Plugin-Runtime-Code. Suchergebnisse enthalten den ClawHub-Paketnamen, die Familie,
den Kanal, die Version, die Zusammenfassung und einen Installationshinweis wie
`openclaw plugins install clawhub:<package>`.
Für Arbeiten an gebündelten Plugins innerhalb eines paketierten Docker-Images binden Sie das Plugin-Quellverzeichnis per Bind-Mount über den passenden paketierten Quellpfad ein, zum Beispiel
`/app/extensions/synology-chat`. OpenClaw erkennt dieses eingehängte Quell-Overlay
vor `/app/dist/extensions/synology-chat`; ein einfach kopiertes Quellverzeichnis
bleibt inaktiv, sodass normale paketierte Installationen weiterhin die kompilierte Distribution verwenden.
Für Arbeiten an gebündelten Plugins innerhalb eines paketierten Docker-Images mounten Sie das Plugin-
Quellverzeichnis per Bind-Mount über den passenden paketierten Quellpfad, etwa
`/app/extensions/synology-chat`. OpenClaw erkennt dieses gemountete Quell-
Overlay vor `/app/dist/extensions/synology-chat`; ein einfach kopiertes Quell-
verzeichnis bleibt inaktiv, sodass normale paketierte Installationen weiterhin das kompilierte dist verwenden.
Für die Laufzeit-Hook-Fehlersuche:
Für Runtime-Hook-Debugging:
- `openclaw plugins inspect <id> --runtime --json` zeigt registrierte Hooks und Diagnosen aus einem Inspektionsdurchlauf mit geladenem Modul. Die Laufzeitinspektion installiert niemals Abhängigkeiten; verwenden Sie `openclaw doctor --fix`, um veralteten Abhängigkeitszustand zu bereinigen oder fehlende herunterladbare Plugins wiederherzustellen, auf die in der Konfiguration verwiesen wird.
- `openclaw gateway status --deep --require-rpc` bestätigt den erreichbaren Gateway, Dienst-/Prozesshinweise, den Konfigurationspfad und die RPC-Funktionsfähigkeit.
- `openclaw plugins inspect <id> --runtime --json` zeigt registrierte Hooks und Diagnosen aus einem Inspektionsdurchlauf mit geladenem Modul. Runtime-Inspektion installiert niemals Abhängigkeiten; verwenden Sie `openclaw doctor --fix`, um alten Abhängigkeitszustand zu bereinigen oder fehlende herunterladbare Plugins wiederherzustellen, die von der Konfiguration referenziert werden.
- `openclaw gateway status --deep --require-rpc` bestätigt das erreichbare Gateway, Dienst-/Prozesshinweise, Konfigurationspfad und RPC-Zustand.
- Nicht gebündelte Konversations-Hooks (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) erfordern `plugins.entries.<id>.hooks.allowConversationAccess=true`.
Verwenden Sie `--link`, um das Kopieren eines lokalen Verzeichnisses zu vermeiden (fügt zu `plugins.load.paths` hinzu):
Verwenden Sie `--link`, um das Kopieren eines lokalen Verzeichnisses zu vermeiden (fügt es zu `plugins.load.paths` hinzu):
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` wird mit `--link` nicht unterstützt, weil verlinkte Installationen den Quellpfad wiederverwenden, statt über ein verwaltetes Installationsziel zu kopieren.
`--force` wird mit `--link` nicht unterstützt, weil verlinkte Installationen den Quellpfad wiederverwenden, anstatt über ein verwaltetes Installationsziel zu kopieren.
Verwenden Sie `--pin` bei npm-Installationen, um die aufgelöste exakte Spezifikation (`name@version`) im verwalteten Plugin-Index zu speichern, während das Standardverhalten unfixiert bleibt.
Verwenden Sie `--pin` bei npm-Installationen, um die aufgelöste exakte Spezifikation (`name@version`) im verwalteten Plugin-Index zu speichern, während das Standardverhalten ungepinnt bleibt.
</Note>
### Plugin-Index
Plugin-Installationsmetadaten sind maschinenverwalteter Zustand, keine Benutzerkonfiguration. Installationen und Aktualisierungen schreiben sie unter `plugins/installs.json` in das aktive OpenClaw-Zustandsverzeichnis. Die oberste `installRecords`-Map ist die dauerhafte Quelle für Installationsmetadaten, einschließlich Einträgen für beschädigte oder fehlende Plugin-Manifeste. Das `plugins`-Array ist der aus Manifesten abgeleitete Kalt-Registry-Cache. Die Datei enthält eine Nicht-bearbeiten-Warnung und wird von `openclaw plugins update`, Deinstallation, Diagnosen und der kalten Plugin-Registry verwendet.
Plugin-Installationsmetadaten sind maschinenverwalteter Zustand, keine Benutzerkonfiguration. Installationen und Updates schreiben sie in `plugins/installs.json` unter dem aktiven OpenClaw-Zustandsverzeichnis. Die `installRecords`-Map auf oberster Ebene ist die dauerhafte Quelle der Installationsmetadaten, einschließlich Datensätzen für defekte oder fehlende Plugin-Manifeste. Das `plugins`-Array ist der aus Manifesten abgeleitete Kaltstart-Registry-Cache. Die Datei enthält eine Warnung, sie nicht zu bearbeiten, und wird von `openclaw plugins update`, Deinstallation, Diagnosen und der kalten Plugin-Registry verwendet.
Wenn OpenClaw ausgelieferte Legacy-`plugins.installs`-Einträge in der Konfiguration sieht, verschiebt es sie in den Plugin-Index und entfernt den Konfigurationsschlüssel; wenn einer der Schreibvorgänge fehlschlägt, bleiben die Konfigurationseinträge erhalten, damit die Installationsmetadaten nicht verloren gehen.
Wenn OpenClaw ausgelieferte alte `plugins.installs`-Datensätze in der Konfiguration sieht, verschiebt es sie in den Plugin-Index und entfernt den Konfigurationsschlüssel; wenn einer der Schreibvorgänge fehlschlägt, bleiben die Konfigurationsdatensätze erhalten, damit die Installationsmetadaten nicht verloren gehen.
### Deinstallieren
@ -293,7 +297,7 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` entfernt Plugin-Einträge aus `plugins.entries`, dem persistierten Plugin-Index, den Plugin-Erlaubnis-/Sperrlisten-Einträgen und, sofern zutreffend, verlinkten `plugins.load.paths`-Einträgen. Sofern `--keep-files` nicht gesetzt ist, entfernt die Deinstallation auch das nachverfolgte verwaltete Installationsverzeichnis, wenn es innerhalb des Plugin-Erweiterungsstammverzeichnisses von OpenClaw liegt. Bei Active-Memory-Plugins wird der Speicher-Slot auf `memory-core` zurückgesetzt.
`uninstall` entfernt Plugin-Datensätze aus `plugins.entries`, dem dauerhaft gespeicherten Plugin-Index, Plugin-Allow-/Denylist-Einträgen und verlinkten `plugins.load.paths`-Einträgen, sofern zutreffend. Sofern `--keep-files` nicht gesetzt ist, entfernt die Deinstallation außerdem das nachverfolgte verwaltete Installationsverzeichnis, wenn es sich innerhalb des OpenClaw-Plugin-Erweiterungsroots befindet. Bei Active-Memory-Plugins wird der Memory-Slot auf `memory-core` zurückgesetzt.
<Note>
`--keep-config` wird als veralteter Alias für `--keep-files` unterstützt.
@ -309,29 +313,29 @@ openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Aktualisierungen gelten für nachverfolgte Plugin-Installationen im verwalteten Plugin-Index und für nachverfolgte Hook-Pack-Installationen in `hooks.internal.installs`.
Updates gelten für nachverfolgte Plugin-Installationen im verwalteten Plugin-Index und nachverfolgte Hook-Pack-Installationen in `hooks.internal.installs`.
<AccordionGroup>
<Accordion title="Plugin-ID gegenüber npm-Spezifikation auflösen">
Wenn Sie eine Plugin-ID übergeben, verwendet OpenClaw die für dieses Plugin aufgezeichnete Installationsspezifikation erneut. Das bedeutet, dass zuvor gespeicherte Dist-Tags wie `@beta` und exakt fixierte Versionen bei späteren `update <id>`-Läufen weiterverwendet werden.
<Accordion title="Resolving plugin id vs npm spec">
Wenn Sie eine Plugin-ID übergeben, verwendet OpenClaw die aufgezeichnete Installationsspezifikation für dieses Plugin erneut. Das bedeutet, dass zuvor gespeicherte dist-tags wie `@beta` und exakt gepinnte Versionen bei späteren `update <id>`-Ausführungen weiterverwendet werden.
Bei npm-Installationen können Sie auch eine explizite npm-Paketspezifikation mit einem Dist-Tag oder einer exakten Version übergeben. OpenClaw löst diesen Paketnamen zurück auf den nachverfolgten Plugin-Eintrag auf, aktualisiert dieses installierte Plugin und zeichnet die neue npm-Spezifikation für zukünftige ID-basierte Aktualisierungen auf.
Bei npm-Installationen können Sie auch eine explizite npm-Paketspezifikation mit einem dist-tag oder einer exakten Version übergeben. OpenClaw löst diesen Paketnamen zurück auf den nachverfolgten Plugin-Datensatz auf, aktualisiert dieses installierte Plugin und zeichnet die neue npm-Spezifikation für zukünftige ID-basierte Updates auf.
Wenn Sie den npm-Paketnamen ohne Version oder Tag übergeben, wird er ebenfalls zurück auf den nachverfolgten Plugin-Eintrag aufgelöst. Verwenden Sie dies, wenn ein Plugin auf eine exakte Version fixiert war und Sie es wieder auf die Standard-Release-Linie der Registry zurückführen möchten.
Das Übergeben des npm-Paketnamens ohne Version oder Tag löst ebenfalls zurück auf den nachverfolgten Plugin-Datensatz auf. Verwenden Sie dies, wenn ein Plugin auf eine exakte Version gepinnt war und Sie es zurück auf die Standard-Release-Linie der Registry verschieben möchten.
</Accordion>
<Accordion title="Aktualisierungen im Beta-Kanal">
`openclaw plugins update` verwendet die nachverfolgte Plugin-Spezifikation erneut, sofern Sie keine neue Spezifikation übergeben. `openclaw update` kennt zusätzlich den aktiven OpenClaw-Aktualisierungskanal: Im Beta-Kanal versuchen npm- und ClawHub-Plugin-Einträge der Standardlinie zuerst `@beta` und fallen dann auf die aufgezeichnete Standard-/Latest-Spezifikation zurück, wenn keine Plugin-Beta-Version existiert. Exakte Versionen und explizite Tags bleiben an diesen Selektor gebunden.
<Accordion title="Beta channel updates">
`openclaw plugins update` verwendet die nachverfolgte Plugin-Spezifikation erneut, sofern Sie keine neue Spezifikation übergeben. `openclaw update` kennt zusätzlich den aktiven OpenClaw-Update-Kanal: Auf dem Beta-Kanal versuchen npm- und ClawHub-Plugin-Datensätze der Standardlinie zuerst `@beta` und fallen dann auf die aufgezeichnete default/latest-Spezifikation zurück, falls kein Plugin-Beta-Release existiert. Exakte Versionen und explizite Tags bleiben an diesen Selektor gepinnt.
</Accordion>
<Accordion title="Versionsprüfungen und Integritätsabweichungen">
Vor einer Live-npm-Aktualisierung prüft OpenClaw die installierte Paketversion gegen die Metadaten der npm-Registry. Wenn die installierte Version und die aufgezeichnete Artefaktidentität bereits mit dem aufgelösten Ziel übereinstimmen, wird die Aktualisierung übersprungen, ohne herunterzuladen, neu zu installieren oder `openclaw.json` neu zu schreiben.
<Accordion title="Version checks and integrity drift">
Vor einem Live-npm-Update prüft OpenClaw die installierte Paketversion gegen die Metadaten der npm-Registry. Wenn die installierte Version und die aufgezeichnete Artefaktidentität bereits dem aufgelösten Ziel entsprechen, wird das Update übersprungen, ohne herunterzuladen, neu zu installieren oder `openclaw.json` neu zu schreiben.
Wenn ein gespeicherter Integritäts-Hash existiert und sich der Hash des abgerufenen Artefakts ändert, behandelt OpenClaw dies als npm-Artefaktabweichung. Der interaktive Befehl `openclaw plugins update` gibt die erwarteten und tatsächlichen Hashes aus und bittet um Bestätigung, bevor er fortfährt. Nicht interaktive Aktualisierungshelfer schlagen geschlossen fehl, sofern der Aufrufer keine explizite Fortsetzungsrichtlinie bereitstellt.
Wenn ein gespeicherter Integritäts-Hash existiert und sich der Hash des abgerufenen Artefakts ändert, behandelt OpenClaw dies als npm-Artefaktdrift. Der interaktive Befehl `openclaw plugins update` gibt die erwarteten und tatsächlichen Hashes aus und fragt vor dem Fortfahren nach Bestätigung. Nicht interaktive Update-Helfer schlagen geschlossen fehl, sofern der Aufrufer keine explizite Fortsetzungsrichtlinie bereitstellt.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install bei Aktualisierung">
`--dangerously-force-unsafe-install` ist auch bei `plugins update` als Notfall-Override für falsch positive Treffer des integrierten Gefährlicher-Code-Scans während Plugin-Aktualisierungen verfügbar. Es umgeht weiterhin keine Plugin-`before_install`-Richtlinienblockaden oder Blockaden durch Scan-Fehler und gilt nur für Plugin-Aktualisierungen, nicht für Hook-Pack-Aktualisierungen.
<Accordion title="--dangerously-force-unsafe-install on update">
`--dangerously-force-unsafe-install` ist auch bei `plugins update` als Notfall-Override für False Positives des eingebauten Dangerous-Code-Scans während Plugin-Updates verfügbar. Es umgeht weiterhin keine Plugin-`before_install`-Richtlinienblockaden oder Blockaden durch Scan-Fehler und gilt nur für Plugin-Updates, nicht für Hook-Pack-Updates.
</Accordion>
</AccordionGroup>
@ -343,13 +347,13 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Inspect zeigt Identität, Ladestatus, Quelle, Manifestfähigkeiten, Richtlinien-Flags, Diagnosen, Installationsmetadaten, Bundle-Fähigkeiten und jede erkannte MCP- oder LSP-Server-Unterstützung an, ohne standardmäßig Plugin-Laufzeit zu importieren. Fügen Sie `--runtime` hinzu, um das Plugin-Modul zu laden und registrierte Hooks, Tools, Befehle, Dienste, Gateway-Methoden und HTTP-Routen einzuschließen. Die Laufzeitinspektion meldet fehlende Plugin-Abhängigkeiten direkt; Installationen und Reparaturen bleiben in `openclaw plugins install`, `openclaw plugins update` und `openclaw doctor --fix`.
Inspect zeigt Identität, Ladestatus, Quelle, Manifest-Fähigkeiten, Richtlinien-Flags, Diagnosen, Installationsmetadaten, Bundle-Fähigkeiten und erkannte MCP- oder LSP-Server-Unterstützung, ohne standardmäßig Plugin-Runtime zu importieren. Fügen Sie `--runtime` hinzu, um das Plugin-Modul zu laden und registrierte Hooks, Tools, Befehle, Dienste, Gateway-Methoden und HTTP-Routen einzuschließen. Runtime-Inspektion meldet fehlende Plugin-Abhängigkeiten direkt; Installationen und Reparaturen bleiben in `openclaw plugins install`, `openclaw plugins update` und `openclaw doctor --fix`.
Plugin-eigene CLI-Befehle werden als Stamm-`openclaw`-Befehlsgruppen installiert. Nachdem `inspect --runtime` einen Befehl unter `cliCommands` anzeigt, führen Sie ihn als `openclaw <command> ...` aus; zum Beispiel kann ein Plugin, das `demo-git` registriert, mit `openclaw demo-git ping` geprüft werden.
Plugin-eigene CLI-Befehle werden als Root-`openclaw`-Befehlsgruppen installiert. Nachdem `inspect --runtime` einen Befehl unter `cliCommands` zeigt, führen Sie ihn als `openclaw <command> ...` aus; beispielsweise kann ein Plugin, das `demo-git` registriert, mit `openclaw demo-git ping` geprüft werden.
Jedes Plugin wird danach klassifiziert, was es tatsächlich zur Laufzeit registriert:
Jedes Plugin wird danach klassifiziert, was es tatsächlich zur Runtime registriert:
- **plain-capability** — ein Fähigkeitstyp (z. B. ein reines Provider-Plugin)
- **plain-capability** — ein Fähigkeitstyp (z. B. ein Provider-only-Plugin)
- **hybrid-capability** — mehrere Fähigkeitstypen (z. B. Text + Sprache + Bilder)
- **hook-only** — nur Hooks, keine Fähigkeiten oder Oberflächen
- **non-capability** — Tools/Befehle/Dienste, aber keine Fähigkeiten
@ -357,7 +361,7 @@ Jedes Plugin wird danach klassifiziert, was es tatsächlich zur Laufzeit registr
Weitere Informationen zum Fähigkeitsmodell finden Sie unter [Plugin-Formen](/de/plugins/architecture#plugin-shapes).
<Note>
Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der für Skripting und Audits geeignet ist. `inspect --all` rendert eine flottenweite Tabelle mit Spalten für Form, Fähigkeitsarten, Kompatibilitätshinweise, Bundle-Fähigkeiten und Hook-Zusammenfassung. `info` ist ein Alias für `inspect`.
Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der sich für Scripting und Audits eignet. `inspect --all` rendert eine flottenweite Tabelle mit Spalten für Form, Fähigkeitstypen, Kompatibilitätshinweise, Bundle-Fähigkeiten und Hook-Zusammenfassung. `info` ist ein Alias für `inspect`.
</Note>
### Doctor
@ -366,11 +370,11 @@ Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der für Skripting u
openclaw plugins doctor
```
`doctor` meldet Plugin-Ladefehler, Manifest-/Erkennungsdiagnosen und Kompatibilitätshinweise. Wenn alles sauber ist, gibt es `No plugin issues detected.` aus.
`doctor` meldet Plugin-Ladefehler, Manifest-/Discovery-Diagnosen und Kompatibilitätshinweise. Wenn alles sauber ist, gibt es `No plugin issues detected.` aus
Wenn ein konfiguriertes Plugin auf dem Datenträger vorhanden ist, aber durch die Pfadsicherheitsprüfungen des Loaders blockiert wird, behält die Konfigurationsvalidierung den Plugin-Eintrag bei und meldet ihn als `present but blocked`. Beheben Sie die vorhergehende Diagnose zum blockierten Plugin, etwa Pfadeigentum oder weltweit beschreibbare Berechtigungen, statt die Konfiguration `plugins.entries.<id>` oder `plugins.allow` zu entfernen.
Wenn ein konfiguriertes Plugin auf der Festplatte vorhanden ist, aber durch die Pfadsicherheitsprüfungen des Loaders blockiert wird, behält die Konfigurationsvalidierung den Plugin-Eintrag bei und meldet ihn als `present but blocked`. Beheben Sie die vorherige Diagnose für blockierte Plugins, etwa Pfadbesitz oder weltbeschreibbare Berechtigungen, anstatt die Konfiguration `plugins.entries.<id>` oder `plugins.allow` zu entfernen.
Bei Modulform-Fehlern wie fehlenden `register`/`activate`-Exporten führen Sie den Befehl erneut mit `OPENCLAW_PLUGIN_LOAD_DEBUG=1` aus, um eine kompakte Zusammenfassung der Exportform in die Diagnoseausgabe aufzunehmen.
Bei Modulform-Fehlern wie fehlenden `register`-/`activate`-Exports führen Sie den Befehl erneut mit `OPENCLAW_PLUGIN_LOAD_DEBUG=1` aus, um eine kompakte Exportform-Zusammenfassung in die Diagnoseausgabe aufzunehmen.
### Registry
@ -380,14 +384,14 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
Die lokale Plugin-Registry ist das persistierte Kaltlesemodell von OpenClaw für installierte Plugin-Identität, Aktivierung, Quellenmetadaten und Beitragsverantwortung. Normaler Start, Provider-Besitzerauflösung, Klassifizierung der Kanaleinrichtung und Plugin-Bestand können sie lesen, ohne Plugin-Laufzeitmodule zu importieren.
Die lokale Plugin-Registry ist das persistierte Cold-Read-Modell von OpenClaw für die Identität installierter Plugins, deren Aktivierung, Quellmetadaten und Contribution-Ownership. Normaler Start, Provider-Owner-Lookup, Klassifizierung der Kanal-Einrichtung und Plugin-Inventar können sie lesen, ohne Plugin-Laufzeitmodule zu importieren.
Verwenden Sie `plugins registry`, um zu prüfen, ob die persistierte Registry vorhanden, aktuell oder veraltet ist. Verwenden Sie `--refresh`, um sie aus dem persistierten Plugin-Index, der Konfigurationsrichtlinie und den Manifest-/Paketmetadaten neu aufzubauen. Dies ist ein Reparaturpfad, kein Pfad zur Laufzeitaktivierung.
`openclaw doctor --fix` repariert außerdem verwaltete npm-Abweichungen im Umfeld der Registry: Wenn ein verwaistes oder wiederhergestelltes `@openclaw/*`-Paket unter dem verwalteten Plugin-npm-Root ein gebündeltes Plugin überschattet, entfernt doctor dieses veraltete Paket und baut die Registry neu auf, sodass der Start gegen das gebündelte Manifest validiert.
`openclaw doctor --fix` repariert außerdem registry-nahe managed npm-Abweichungen: Wenn ein verwaistes oder wiederhergestelltes `@openclaw/*`-Paket unter der managed Plugin-npm-Wurzel ein gebündeltes Plugin überdeckt, entfernt doctor dieses veraltete Paket und baut die Registry neu auf, damit der Start gegen das gebündelte Manifest validiert.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` ist ein veralteter Notfall-Kompatibilitätsschalter für Lesefehler der Registry. Bevorzugen Sie `plugins registry --refresh` oder `openclaw doctor --fix`; der Umgebungs-Fallback ist nur für die Notfallwiederherstellung beim Start vorgesehen, während die Migration ausgerollt wird.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` ist ein veralteter Break-Glass-Kompatibilitätsschalter für Registry-Lesefehler. Bevorzugen Sie `plugins registry --refresh` oder `openclaw doctor --fix`; der Env-Fallback ist nur für die Notfallwiederherstellung beim Start gedacht, während die Migration ausgerollt wird.
</Warning>
### Marktplatz
@ -397,9 +401,9 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Der Marktplatz-Listenbefehl akzeptiert einen lokalen Marktplatzpfad, einen `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL. `--json` gibt die aufgelöste Quellbezeichnung sowie das geparste Marktplatzmanifest und die Plugin-Einträge aus.
Die Marketplace-Liste akzeptiert einen lokalen Marketplace-Pfad, einen `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL. `--json` gibt das aufgelöste Quellenlabel sowie das geparste Marketplace-Manifest und die Plugin-Einträge aus.
## Zugehörige Themen
## Verwandte Themen
- [Plugins erstellen](/de/plugins/building-plugins)
- [CLI-Referenz](/de/cli)

245
docs/de/concepts/model-providers.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Sie benötigen eine Referenz zur Modelleinrichtung nach Provider
- Sie benötigen eine nach Providern gegliederte Referenz zur Modelleinrichtung
- Sie möchten Beispielkonfigurationen oder CLI-Onboarding-Befehle für Modell-Provider
sidebarTitle: Model providers
summary: Übersicht über Modell-Provider mit Beispielkonfigurationen + CLI-Abläufen
summary: Überblick über Modell-Provider mit Beispielkonfigurationen + CLI-Abläufen
title: Modell-Provider
x-i18n:
generated_at: "2026-05-06T06:44:16Z"
generated_at: "2026-05-06T09:03:10Z"
model: gpt-5.5
provider: openai
source_hash: 304f20e10cbcd4465b7b843e398452b1b93a19cfaefd9f4d4edc213d7e003542
source_hash: 8375caf4bacbb360e57637801d06a9d7898b36d440b82885d993b8248cd4daff
source_path: concepts/model-providers.md
workflow: 16
---
@ -19,94 +19,94 @@ Referenz für **LLM-/Modell-Provider** (nicht Chat-Kanäle wie WhatsApp/Telegram
## Kurzregeln
<AccordionGroup>
<Accordion title="Modell-Refs und CLI-Hilfen">
- Modell-Refs verwenden `provider/model` (Beispiel: `opencode/claude-opus-4-6`).
- `agents.defaults.models` dient als Allowlist, wenn es gesetzt ist.
- CLI-Hilfen: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` legen Standardwerte auf Provider-Ebene fest; `models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` überschreiben sie pro Modell.
<Accordion title="Model refs and CLI helpers">
- Modellreferenzen verwenden `provider/model` (Beispiel: `opencode/claude-opus-4-6`).
- `agents.defaults.models` fungiert als Allowlist, wenn es gesetzt ist.
- CLI-Helfer: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` setzen Defaults auf Provider-Ebene; `models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` überschreiben sie pro Modell.
- Fallback-Regeln, Cooldown-Probes und Persistenz von Sitzungsüberschreibungen: [Modell-Failover](/de/concepts/model-failover).
</Accordion>
<Accordion title="Das Hinzufügen von Provider-Authentifizierung ändert Ihr primäres Modell nicht">
`openclaw configure` behält ein vorhandenes `agents.defaults.model.primary` bei, wenn Sie einen Provider hinzufügen oder erneut authentifizieren. Provider-Plugins können in ihrem Auth-Konfigurationspatch weiterhin ein empfohlenes Standardmodell zurückgeben, aber configure behandelt dies als „dieses Modell verfügbar machen“, wenn bereits ein primäres Modell existiert, nicht als „das aktuelle primäre Modell ersetzen“.
<Accordion title="Adding provider auth does not change your primary model">
`openclaw configure` behält ein vorhandenes `agents.defaults.model.primary` bei, wenn Sie einen Provider hinzufügen oder erneut authentifizieren. Provider-Plugins können in ihrem Auth-Konfigurationspatch weiterhin ein empfohlenes Default-Modell zurückgeben, aber configure behandelt dies als „dieses Modell verfügbar machen“, wenn bereits ein primäres Modell existiert, nicht als „das aktuelle primäre Modell ersetzen“.
Um das Standardmodell absichtlich zu wechseln, verwenden Sie `openclaw models set <provider/model>` oder `openclaw models auth login --provider <id> --set-default`.
Um das Default-Modell absichtlich zu wechseln, verwenden Sie `openclaw models set <provider/model>` oder `openclaw models auth login --provider <id> --set-default`.
</Accordion>
<Accordion title="OpenAI-Provider-/Runtime-Aufteilung">
OpenAI-Family-Routen sind präfixspezifisch:
<Accordion title="OpenAI provider/runtime split">
Routen der OpenAI-Familie sind präfixspezifisch:
- `openai/<model>` plus `agents.defaults.agentRuntime.id: "codex"` verwendet das native Codex-App-Server-Harness. Dies ist die übliche Einrichtung für ChatGPT-/Codex-Abonnements.
- `openai/<model>` plus `agents.defaults.agentRuntime.id: "codex"` verwendet den nativen Codex App-Server-Harness. Dies ist die übliche Einrichtung für ChatGPT-/Codex-Abonnements.
- `openai-codex/<model>` verwendet Codex OAuth in PI.
- `openai/<model>` ohne Codex-Runtime-Überschreibung verwendet den direkten OpenAI-API-Key-Provider in PI.
- `openai/<model>` ohne Codex-Runtime-Override verwendet den direkten OpenAI-API-Schlüssel-Provider in PI.
Siehe [OpenAI](/de/providers/openai) und [Codex-Harness](/de/plugins/codex-harness). Wenn die Provider-/Runtime-Aufteilung verwirrend ist, lesen Sie zuerst [Agent-Runtimes](/de/concepts/agent-runtimes).
Siehe [OpenAI](/de/providers/openai) und [Codex-Harness](/de/plugins/codex-harness). Wenn die Trennung zwischen Provider und Runtime verwirrend ist, lesen Sie zuerst [Agent-Runtimes](/de/concepts/agent-runtimes).
Das automatische Aktivieren von Plugins folgt derselben Grenze: `openai-codex/<model>` gehört zum OpenAI-Plugin, während das Codex-Plugin durch `agentRuntime.id: "codex"` oder Legacy-Refs `codex/<model>` aktiviert wird.
Die automatische Aktivierung von Plugins folgt derselben Grenze: `openai-codex/<model>` gehört zum OpenAI-Plugin, während das Codex-Plugin durch `agentRuntime.id: "codex"` oder ältere `codex/<model>`-Referenzen aktiviert wird.
GPT-5.5 ist über das native Codex-App-Server-Harness verfügbar, wenn `agentRuntime.id: "codex"` gesetzt ist, über `openai-codex/gpt-5.5` in PI für Codex OAuth und über `openai/gpt-5.5` in PI für direkten API-Key-Traffic, wenn Ihr Konto dies bereitstellt.
GPT-5.5 ist über den nativen Codex App-Server-Harness verfügbar, wenn `agentRuntime.id: "codex"` gesetzt ist, über `openai-codex/gpt-5.5` in PI für Codex OAuth und über `openai/gpt-5.5` in PI für direkten API-Schlüssel-Traffic, wenn Ihr Konto dies bereitstellt.
</Accordion>
<Accordion title="CLI-Runtimes">
CLI-Runtimes verwenden dieselbe Aufteilung: Wählen Sie kanonische Modell-Refs wie `anthropic/claude-*`, `google/gemini-*` oder `openai/gpt-*` und setzen Sie dann `agents.defaults.agentRuntime.id` auf `claude-cli`, `google-gemini-cli` oder `codex-cli`, wenn Sie ein lokales CLI-Backend verwenden möchten.
<Accordion title="CLI runtimes">
CLI-Runtimes verwenden dieselbe Trennung: Wählen Sie kanonische Modellreferenzen wie `anthropic/claude-*`, `google/gemini-*` oder `openai/gpt-*` und setzen Sie dann `agents.defaults.agentRuntime.id` auf `claude-cli`, `google-gemini-cli` oder `codex-cli`, wenn Sie ein lokales CLI-Backend verwenden möchten.
Legacy-Refs `claude-cli/*`, `google-gemini-cli/*` und `codex-cli/*` werden zurück zu kanonischen Provider-Refs migriert, wobei die Runtime separat gespeichert wird.
Ältere `claude-cli/*`-, `google-gemini-cli/*`- und `codex-cli/*`-Referenzen werden wieder zu kanonischen Provider-Referenzen migriert, wobei die Runtime separat gespeichert wird.
</Accordion>
</AccordionGroup>
## Plugin-eigenes Provider-Verhalten
Die meiste providerspezifische Logik lebt in Provider-Plugins (`registerProvider(...)`), während OpenClaw die generische Inferenzschleife beibehält. Plugins besitzen Onboarding, Modellkataloge, Auth-Env-Var-Mapping, Transport-/Konfigurationsnormalisierung, Tool-Schema-Bereinigung, Failover-Klassifizierung, OAuth-Aktualisierung, Nutzungsberichte, Denk-/Reasoning-Profile und mehr.
Die meiste Provider-spezifische Logik befindet sich in Provider-Plugins (`registerProvider(...)`), während OpenClaw die generische Inferenzschleife beibehält. Plugins besitzen Onboarding, Modellkataloge, Auth-Umgebungsvariablen-Mapping, Transport-/Konfigurationsnormalisierung, Tool-Schema-Bereinigung, Failover-Klassifizierung, OAuth-Aktualisierung, Nutzungsberichte, Denk-/Reasoning-Profile und mehr.
Die vollständige Liste der Provider-SDK-Hooks und Beispiele für gebündelte Plugins finden Sie unter [Provider-Plugins](/de/plugins/sdk-provider-plugins). Ein Provider, der einen vollständig benutzerdefinierten Request-Executor benötigt, ist eine separate, tiefergehende Erweiterungsoberfläche.
Die vollständige Liste der Provider-SDK-Hooks und Beispiele für gebündelte Plugins finden Sie unter [Provider-Plugins](/de/plugins/sdk-provider-plugins). Ein Provider, der einen vollständig benutzerdefinierten Request-Executor benötigt, ist eine separate, tiefere Erweiterungsfläche.
<Note>
Provider-eigenes Runner-Verhalten lebt in expliziten Provider-Hooks wie Replay-Policy, Tool-Schema-Normalisierung, Stream-Wrapping sowie Transport-/Request-Hilfen. Die statische Legacy-Tasche `ProviderPlugin.capabilities` dient nur der Kompatibilität und wird von gemeinsamer Runner-Logik nicht mehr gelesen.
Provider-eigenes Runner-Verhalten lebt auf expliziten Provider-Hooks wie Replay-Policy, Tool-Schema-Normalisierung, Stream-Wrapping und Transport-/Request-Helfern. Der ältere statische `ProviderPlugin.capabilities`-Bag dient nur der Kompatibilität und wird von gemeinsamer Runner-Logik nicht mehr gelesen.
</Note>
## API-Key-Rotation
## API-Schlüsselrotation
<AccordionGroup>
<Accordion title="Key-Quellen und Priorität">
Konfigurieren Sie mehrere Keys über:
<Accordion title="Key sources and priority">
Konfigurieren Sie mehrere Schlüssel über:
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (einzelne Live-Überschreibung, höchste Priorität)
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (einzelner Live-Override, höchste Priorität)
- `<PROVIDER>_API_KEYS` (durch Kommas oder Semikolons getrennte Liste)
- `<PROVIDER>_API_KEY` (primärer Key)
- `<PROVIDER>_API_KEY` (primärer Schlüssel)
- `<PROVIDER>_API_KEY_*` (nummerierte Liste, z. B. `<PROVIDER>_API_KEY_1`)
Für Google-Provider wird `GOOGLE_API_KEY` ebenfalls als Fallback einbezogen. Die Auswahlreihenfolge der Keys bewahrt die Priorität und dedupliziert Werte.
Für Google-Provider wird `GOOGLE_API_KEY` ebenfalls als Fallback einbezogen. Die Reihenfolge der Schlüsselauswahl bewahrt die Priorität und dedupliziert Werte.
</Accordion>
<Accordion title="Wann Rotation greift">
- Requests werden nur bei Rate-Limit-Antworten mit dem nächsten Key erneut versucht (zum Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` oder periodische Nutzungslimit-Meldungen).
- Fehler, die keine Rate Limits sind, schlagen sofort fehl; es wird keine Key-Rotation versucht.
- Wenn alle Kandidaten-Keys fehlschlagen, wird der endgültige Fehler aus dem letzten Versuch zurückgegeben.
<Accordion title="When rotation kicks in">
- Requests werden nur bei Rate-Limit-Antworten mit dem nächsten Schlüssel wiederholt (zum Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` oder regelmäßige Nutzungslimitmeldungen).
- Fehler, die keine Rate-Limits sind, schlagen sofort fehl; es wird keine Schlüsselrotation versucht.
- Wenn alle Kandidatenschlüssel fehlschlagen, wird der finale Fehler aus dem letzten Versuch zurückgegeben.
</Accordion>
</AccordionGroup>
## Eingebaute Provider (pi-ai-Katalog)
## Integrierte Provider (pi-ai-Katalog)
OpenClaw wird mit dem pi-ai-Katalog ausgeliefert. Diese Provider benötigen **keine** `models.providers`-Konfiguration; setzen Sie einfach Auth und wählen Sie ein Modell aus.
OpenClaw wird mit dem pi-ai-Katalog ausgeliefert. Diese Provider benötigen **keine** `models.providers`-Konfiguration; setzen Sie einfach Authentifizierung und wählen Sie ein Modell.
### OpenAI
- Provider: `openai`
- Auth: `OPENAI_API_KEY`
- Optionale Rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2` plus `OPENCLAW_LIVE_OPENAI_KEY` (einzelne Überschreibung)
- Authentifizierung: `OPENAI_API_KEY`
- Optionale Rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (einzelner Override)
- Beispielmodelle: `openai/gpt-5.5`, `openai/gpt-5.4-mini`
- Prüfen Sie die Konto-/Modellverfügbarkeit mit `openclaw models list --provider openai`, wenn sich eine bestimmte Installation oder ein API-Key anders verhält.
- Prüfen Sie Konto-/Modellverfügbarkeit mit `openclaw models list --provider openai`, wenn eine bestimmte Installation oder ein API-Schlüssel sich anders verhält.
- CLI: `openclaw onboard --auth-choice openai-api-key`
- Der Standardtransport ist `auto` (WebSocket zuerst, SSE-Fallback)
- Überschreibung pro Modell über `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`)
- OpenAI-Responses-WebSocket-Warm-up ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`)
- Der Default-Transport ist `auto` (WebSocket zuerst, SSE-Fallback)
- Pro Modell über `agents.defaults.models["openai/<model>"].params.transport` überschreiben (`"sse"`, `"websocket"` oder `"auto"`)
- OpenAI Responses WebSocket-Warm-up ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`)
- OpenAI-Prioritätsverarbeitung kann über `agents.defaults.models["openai/<model>"].params.serviceTier` aktiviert werden
- `/fast` und `params.fastMode` mappen direkte `openai/*`-Responses-Requests auf `service_tier=priority` auf `api.openai.com`
- Verwenden Sie `params.serviceTier`, wenn Sie statt des gemeinsamen `/fast`-Toggles eine explizite Stufe wünschen
- Verborgene OpenClaw-Attributions-Header (`originator`, `version`, `User-Agent`) gelten nur für nativen OpenAI-Traffic zu `api.openai.com`, nicht für generische OpenAI-kompatible Proxys
- Native OpenAI-Routen behalten außerdem Responses `store`, Prompt-Cache-Hinweise und OpenAI-Reasoning-kompatibles Payload-Shaping bei; Proxy-Routen tun dies nicht
- Verwenden Sie `params.serviceTier`, wenn Sie statt des gemeinsamen `/fast`-Toggles eine explizite Stufe möchten
- Verborgene OpenClaw-Attributionsheader (`originator`, `version`, `User-Agent`) gelten nur für nativen OpenAI-Traffic zu `api.openai.com`, nicht für generische OpenAI-kompatible Proxys
- Native OpenAI-Routen behalten außerdem Responses `store`, Prompt-Cache-Hinweise und OpenAI-Reasoning-Kompatibilitäts-Payload-Formung bei; Proxy-Routen tun dies nicht
- `openai/gpt-5.3-codex-spark` wird in OpenClaw absichtlich unterdrückt, weil Live-OpenAI-API-Requests es ablehnen und der aktuelle Codex-Katalog es nicht bereitstellt
```json5
@ -118,15 +118,15 @@ OpenClaw wird mit dem pi-ai-Katalog ausgeliefert. Diese Provider benötigen **ke
### Anthropic
- Provider: `anthropic`
- Auth: `ANTHROPIC_API_KEY`
- Optionale Rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2` plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (einzelne Überschreibung)
- Authentifizierung: `ANTHROPIC_API_KEY`
- Optionale Rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (einzelner Override)
- Beispielmodell: `anthropic/claude-opus-4-6`
- CLI: `openclaw onboard --auth-choice apiKey`
- Direkte öffentliche Anthropic-Requests unterstützen den gemeinsamen `/fast`-Toggle und `params.fastMode`, einschließlich API-Key- und OAuth-authentifiziertem Traffic, der an `api.anthropic.com` gesendet wird; OpenClaw mappt dies auf Anthropic `service_tier` (`auto` vs. `standard_only`)
- Die bevorzugte Claude-CLI-Konfiguration hält die Modell-Ref kanonisch und wählt das CLI-Backend separat aus: `anthropic/claude-opus-4-7` mit `agents.defaults.agentRuntime.id: "claude-cli"`. Legacy-Refs `claude-cli/claude-opus-4-7` funktionieren aus Kompatibilitätsgründen weiterhin.
- Direkte öffentliche Anthropic-Requests unterstützen den gemeinsamen `/fast`-Toggle und `params.fastMode`, einschließlich API-Schlüssel- und OAuth-authentifiziertem Traffic an `api.anthropic.com`; OpenClaw mappt dies auf Anthropic `service_tier` (`auto` vs. `standard_only`)
- Die bevorzugte Claude-CLI-Konfiguration behält die Modellreferenz kanonisch und wählt das CLI-Backend separat: `anthropic/claude-opus-4-7` mit `agents.defaults.agentRuntime.id: "claude-cli"`. Ältere `claude-cli/claude-opus-4-7`-Referenzen funktionieren aus Kompatibilitätsgründen weiterhin.
<Note>
Anthropic-Mitarbeitende haben uns mitgeteilt, dass die Claude-CLI-Nutzung im OpenClaw-Stil wieder erlaubt ist, daher behandelt OpenClaw die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als sanktioniert, sofern Anthropic keine neue Richtlinie veröffentlicht. Anthropic-Setup-Token bleiben als unterstützter OpenClaw-Token-Pfad verfügbar, aber OpenClaw bevorzugt jetzt die Wiederverwendung der Claude CLI und `claude -p`, wenn verfügbar.
Anthropic-Mitarbeitende haben uns mitgeteilt, dass die Claude-CLI-Nutzung im OpenClaw-Stil wieder erlaubt ist. Daher behandelt OpenClaw die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als genehmigt, sofern Anthropic keine neue Richtlinie veröffentlicht. Anthropic-Setup-Token bleiben als unterstützter OpenClaw-Token-Pfad verfügbar, aber OpenClaw bevorzugt nun die Wiederverwendung der Claude CLI und `claude -p`, wenn verfügbar.
</Note>
```json5
@ -138,22 +138,23 @@ Anthropic-Mitarbeitende haben uns mitgeteilt, dass die Claude-CLI-Nutzung im Ope
### OpenAI Codex OAuth
- Provider: `openai-codex`
- Auth: OAuth (ChatGPT)
- PI-Modell-Ref: `openai-codex/gpt-5.5`
- Native Codex-App-Server-Harness-Ref: `openai/gpt-5.5` mit `agents.defaults.agentRuntime.id: "codex"`
- Dokumentation zum nativen Codex-App-Server-Harness: [Codex-Harness](/de/plugins/codex-harness)
- Legacy-Modell-Refs: `codex/gpt-*`
- Plugin-Grenze: `openai-codex/*` lädt das OpenAI-Plugin; das native Codex-App-Server-Plugin wird nur durch die Codex-Harness-Runtime oder Legacy-Refs `codex/*` ausgewählt.
- Authentifizierung: OAuth (ChatGPT)
- PI-Modellreferenz: `openai-codex/gpt-5.5`
- Native Codex App-Server-Harness-Referenz: `openai/gpt-5.5` mit `agents.defaults.agentRuntime.id: "codex"`
- Dokumentation zum nativen Codex App-Server-Harness: [Codex-Harness](/de/plugins/codex-harness)
- Ältere Modellreferenzen: `codex/gpt-*`
- Plugin-Grenze: `openai-codex/*` lädt das OpenAI-Plugin; das native Codex App-Server-Plugin wird nur durch die Codex-Harness-Runtime oder ältere `codex/*`-Referenzen ausgewählt.
- CLI: `openclaw onboard --auth-choice openai-codex` oder `openclaw models auth login --provider openai-codex`
- Der Standardtransport ist `auto` (WebSocket zuerst, SSE-Fallback)
- Überschreibung pro PI-Modell über `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`)
- Der Default-Transport ist `auto` (WebSocket zuerst, SSE-Fallback)
- Pro PI-Modell über `agents.defaults.models["openai-codex/<model>"].params.transport` überschreiben (`"sse"`, `"websocket"` oder `"auto"`)
- `params.serviceTier` wird auch bei nativen Codex-Responses-Requests weitergeleitet (`chatgpt.com/backend-api`)
- Verborgene OpenClaw-Attributions-Header (`originator`, `version`, `User-Agent`) werden nur bei nativem Codex-Traffic zu `chatgpt.com/backend-api` angehängt, nicht bei generischen OpenAI-kompatiblen Proxys
- Teilt denselben `/fast`-Toggle und dieselbe `params.fastMode`-Konfiguration wie direktes `openai/*`; OpenClaw mappt dies auf `service_tier=priority`
- `openai-codex/gpt-5.5` verwendet den nativen Codex-Katalogwert `contextWindow = 400000` und die Standard-Runtime `contextTokens = 272000`; überschreiben Sie die Runtime-Obergrenze mit `models.providers.openai-codex.models[].contextTokens`
- Verborgene OpenClaw-Attributionsheader (`originator`, `version`, `User-Agent`) werden nur bei nativem Codex-Traffic zu `chatgpt.com/backend-api` angehängt, nicht bei generischen OpenAI-kompatiblen Proxys
- Teilt dieselbe `/fast`-Toggle- und `params.fastMode`-Konfiguration wie direktes `openai/*`; OpenClaw mappt dies auf `service_tier=priority`
- `openai-codex/gpt-5.5` verwendet den nativen `contextWindow = 400000` des Codex-Katalogs und die Default-Runtime `contextTokens = 272000`; überschreiben Sie die Runtime-Obergrenze mit `models.providers.openai-codex.models[].contextTokens`
- Richtlinienhinweis: OpenAI Codex OAuth wird ausdrücklich für externe Tools/Workflows wie OpenClaw unterstützt.
- Für die übliche Route mit Abonnement plus nativer Codex-Runtime melden Sie sich mit `openai-codex`-Auth an, konfigurieren aber `openai/gpt-5.5` plus `agents.defaults.agentRuntime.id: "codex"`.
- Verwenden Sie `openai-codex/gpt-5.5` nur, wenn Sie die Codex-OAuth-/Abonnementroute über PI möchten; verwenden Sie `openai/gpt-5.5` ohne Codex-Runtime-Überschreibung, wenn Ihre API-Key-Einrichtung und Ihr lokaler Katalog die öffentliche API-Route bereitstellen.
- Für die gängige Route aus Abonnement plus nativer Codex-Runtime melden Sie sich mit `openai-codex`-Authentifizierung an, konfigurieren aber `openai/gpt-5.5` plus `agents.defaults.agentRuntime.id: "codex"`.
- Verwenden Sie `openai-codex/gpt-5.5` nur, wenn Sie die Codex-OAuth-/Abonnementroute über PI möchten; verwenden Sie `openai/gpt-5.5` ohne Codex-Runtime-Override, wenn Ihre API-Schlüssel-Einrichtung und Ihr lokaler Katalog die öffentliche API-Route bereitstellen.
- Ältere `openai-codex/gpt-5.1*`-, `openai-codex/gpt-5.2*`- und `openai-codex/gpt-5.3*`-Referenzen werden unterdrückt, weil ChatGPT-/Codex-OAuth-Konten sie ablehnen; verwenden Sie stattdessen `openai-codex/gpt-5.5` oder die native Codex-Runtime-Route.
```json5
{
@ -182,20 +183,20 @@ Anthropic-Mitarbeitende haben uns mitgeteilt, dass die Claude-CLI-Nutzung im Ope
### Weitere gehostete Optionen im Abonnementstil
<CardGroup cols={3}>
<Card title="GLM-Modelle" href="/de/providers/glm">
<Card title="GLM models" href="/de/providers/glm">
Z.AI Coding Plan oder allgemeine API-Endpunkte.
</Card>
<Card title="MiniMax" href="/de/providers/minimax">
MiniMax Coding Plan OAuth oder API-Key-Zugriff.
MiniMax Coding Plan OAuth oder Zugriff per API-Schlüssel.
</Card>
<Card title="Qwen Cloud" href="/de/providers/qwen">
Qwen-Cloud-Provider-Oberfläche plus Alibaba DashScope und Endpunkt-Mapping für Coding Plan.
Qwen Cloud-Provider-Oberfläche plus Alibaba DashScope und Endpunkt-Mapping für den Coding Plan.
</Card>
</CardGroup>
### OpenCode
- Auth: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`)
- Authentifizierung: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`)
- Zen-Runtime-Provider: `opencode`
- Go-Runtime-Provider: `opencode-go`
- Beispielmodelle: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.6`
@ -207,25 +208,25 @@ Anthropic-Mitarbeitende haben uns mitgeteilt, dass die Claude-CLI-Nutzung im Ope
}
```
### Google Gemini (API-Key)
### Google Gemini (API-Schlüssel)
- Provider: `google`
- Authentifizierung: `GEMINI_API_KEY`
- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` als Fallback und `OPENCLAW_LIVE_GEMINI_KEY` (einzelne Überschreibung)
- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY`-Fallback und `OPENCLAW_LIVE_GEMINI_KEY` (einzelne Überschreibung)
- Beispielmodelle: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
- Kompatibilität: Legacy-OpenClaw-Konfiguration mit `google/gemini-3.1-flash-preview` wird zu `google/gemini-3-flash-preview` normalisiert
- Kompatibilität: Legacy-OpenClaw-Konfigurationen mit `google/gemini-3.1-flash-preview` werden zu `google/gemini-3-flash-preview` normalisiert
- Alias: `google/gemini-3.1-pro` wird akzeptiert und zu Googles Live-Gemini-API-ID `google/gemini-3.1-pro-preview` normalisiert
- CLI: `openclaw onboard --auth-choice gemini-api-key`
- Denken: `/think adaptive` verwendet Googles dynamisches Denken. Gemini 3/3.1 lassen ein festes `thinkingLevel` weg; Gemini 2.5 sendet `thinkingBudget: -1`.
- Direkte Gemini-Ausführungen akzeptieren außerdem `agents.defaults.models["google/<model>"].params.cachedContent` (oder das Legacy-Format `cached_content`), um einen provider-nativen `cachedContents/...`-Handle weiterzuleiten; Gemini-Cachetreffer erscheinen als OpenClaw `cacheRead`
- Denken: `/think adaptive` verwendet dynamisches Denken von Google. Gemini 3/3.1 lassen ein festes `thinkingLevel` weg; Gemini 2.5 sendet `thinkingBudget: -1`.
- Direkte Gemini-Ausführungen akzeptieren außerdem `agents.defaults.models["google/<model>"].params.cachedContent` (oder das Legacy-`cached_content`), um ein provider-natives `cachedContents/...`-Handle weiterzuleiten; Gemini-Cache-Treffer erscheinen als OpenClaw-`cacheRead`
### Google Vertex und Gemini CLI
- Provider: `google-vertex`, `google-gemini-cli`
- Authentifizierung: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Flow
- Authentifizierung: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Ablauf
<Warning>
Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Benutzer haben nach der Verwendung von Drittanbieter-Clients Einschränkungen für Google-Konten gemeldet. Prüfen Sie die Google-Bedingungen und verwenden Sie ein unkritisches Konto, wenn Sie fortfahren möchten.
Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Benutzer haben nach der Verwendung von Drittanbieter-Clients von Einschränkungen für Google-Konten berichtet. Prüfen Sie die Google-Bedingungen und verwenden Sie ein nicht kritisches Konto, wenn Sie fortfahren möchten.
</Warning>
Gemini-CLI-OAuth wird als Teil des gebündelten `google`-Plugins ausgeliefert.
@ -255,7 +256,7 @@ Gemini-CLI-OAuth wird als Teil des gebündelten `google`-Plugins ausgeliefert.
openclaw models auth login --provider google-gemini-cli --set-default
```
Standardmodell: `google-gemini-cli/gemini-3-flash-preview`. Sie fügen **keine** Client-ID und kein Secret in `openclaw.json` ein. Der CLI-Anmeldeflow speichert Token in Auth-Profilen auf dem Gateway-Host.
Standardmodell: `google-gemini-cli/gemini-3-flash-preview`. Sie fügen **keine** Client-ID und kein Secret in `openclaw.json` ein. Der CLI-Anmeldeablauf speichert Tokens in Authentifizierungsprofilen auf dem Gateway-Host.
</Step>
<Step title="Projekt festlegen (falls erforderlich)">
@ -263,7 +264,7 @@ Gemini-CLI-OAuth wird als Teil des gebündelten `google`-Plugins ausgeliefert.
</Step>
</Steps>
Gemini-CLI-JSON-Antworten werden aus `response` geparst; die Nutzung fällt auf `stats` zurück, wobei `stats.cached` in OpenClaw `cacheRead` normalisiert wird.
Gemini-CLI-JSON-Antworten werden aus `response` geparst; die Nutzung fällt auf `stats` zurück, wobei `stats.cached` zu OpenClaw-`cacheRead` normalisiert wird.
### Z.AI (GLM)
@ -271,8 +272,8 @@ Gemini-CLI-JSON-Antworten werden aus `response` geparst; die Nutzung fällt auf
- Authentifizierung: `ZAI_API_KEY`
- Beispielmodell: `zai/glm-5.1`
- CLI: `openclaw onboard --auth-choice zai-api-key`
- Aliase: `z.ai/*` und `z-ai/*` werden zu `zai/*` normalisiert
- `zai-api-key` erkennt automatisch den passenden Z.AI-Endpunkt; `zai-coding-global`, `zai-coding-cn`, `zai-global` und `zai-cn` erzwingen eine bestimmte Oberfläche
- Aliasse: `z.ai/*` und `z-ai/*` werden zu `zai/*` normalisiert
- `zai-api-key` erkennt den passenden Z.AI-Endpunkt automatisch; `zai-coding-global`, `zai-coding-cn`, `zai-global` und `zai-cn` erzwingen eine bestimmte Oberfläche
### Vercel AI Gateway
@ -288,14 +289,14 @@ Gemini-CLI-JSON-Antworten werden aus `response` geparst; die Nutzung fällt auf
- Beispielmodell: `kilocode/kilo/auto`
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
- Basis-URL: `https://api.kilo.ai/api/gateway/`
- Der statische Fallback-Katalog liefert `kilocode/kilo/auto` mit; die Live-Erkennung über `https://api.kilo.ai/api/gateway/models` kann den Laufzeitkatalog weiter erweitern.
- Das exakte Upstream-Routing hinter `kilocode/kilo/auto` gehört Kilo Gateway und ist nicht fest in OpenClaw codiert.
- Der statische Fallback-Katalog liefert `kilocode/kilo/auto`; die Live-Erkennung über `https://api.kilo.ai/api/gateway/models` kann den Laufzeitkatalog weiter erweitern.
- Das exakte Upstream-Routing hinter `kilocode/kilo/auto` liegt bei Kilo Gateway und ist nicht fest in OpenClaw codiert.
Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails.
Einrichtungsdetails finden Sie unter [/providers/kilocode](/de/providers/kilocode).
### Weitere gebündelte Provider-Plugins
| Provider | ID | Auth-Env | Beispielmodell |
| Provider | ID | Authentifizierungs-Env | Beispielmodell |
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
@ -326,16 +327,16 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails.
<AccordionGroup>
<Accordion title="OpenRouter">
Wendet seine App-Attribution-Header und Anthropic-`cache_control`-Marker nur auf verifizierten `openrouter.ai`-Routen an. DeepSeek-, Moonshot- und ZAI-Refs sind für von OpenRouter verwaltetes Prompt-Caching mit Cache-TTL geeignet, erhalten aber keine Anthropic-Cache-Marker. Als proxyartiger OpenAI-kompatibler Pfad überspringt er ausschließlich native OpenAI-Formung (`serviceTier`, Responses `store`, Prompt-Cache-Hinweise, OpenAI-Reasoning-Kompatibilität). Gemini-gestützte Refs behalten nur die proxy-Gemini-Bereinigung der Thought-Signaturen bei.
Wendet seine App-Attribution-Header und Anthropic-`cache_control`-Marker nur auf verifizierten `openrouter.ai`-Routen an. DeepSeek-, Moonshot- und ZAI-Refs sind für das von OpenRouter verwaltete Prompt-Caching Cache-TTL-berechtigt, erhalten aber keine Anthropic-Cache-Marker. Als proxyartiger OpenAI-kompatibler Pfad überspringt er nur für native OpenAI geltende Anpassungen (`serviceTier`, Responses `store`, Prompt-Cache-Hinweise, OpenAI-Reasoning-Kompatibilität). Gemini-gestützte Refs behalten nur die Proxy-Gemini-Bereinigung von Gedankensignaturen bei.
</Accordion>
<Accordion title="Kilo Gateway">
Gemini-gestützte Refs folgen demselben proxy-Gemini-Bereinigungspfad; `kilocode/kilo/auto` und andere Refs ohne Unterstützung für Proxy-Reasoning überspringen die Proxy-Reasoning-Injektion.
Gemini-gestützte Refs folgen demselben Proxy-Gemini-Bereinigungspfad; `kilocode/kilo/auto` und andere Refs ohne Proxy-Reasoning-Unterstützung überspringen die Proxy-Reasoning-Injektion.
</Accordion>
<Accordion title="MiniMax">
Das API-Key-Onboarding schreibt explizite reine Textdefinitionen für M2.7-Chatmodelle; Bildverständnis verbleibt beim Plugin-eigenen Medien-Provider `MiniMax-VL-01`.
API-Schlüssel-Onboarding schreibt explizite text-only M2.7-Chatmodelldefinitionen; Bildverständnis bleibt beim Plugin-eigenen `MiniMax-VL-01`-Medien-Provider.
</Accordion>
<Accordion title="NVIDIA">
Modell-IDs verwenden einen Namespace `nvidia/<vendor>/<model>` (zum Beispiel `nvidia/nvidia/nemotron-...` neben `nvidia/moonshotai/kimi-k2.5`); Auswahllisten bewahren die wörtliche Zusammensetzung `<provider>/<model-id>`, während der an die API gesendete kanonische Schlüssel einfach präfigiert bleibt.
Modell-IDs verwenden einen `nvidia/<vendor>/<model>`-Namensraum (zum Beispiel `nvidia/nvidia/nemotron-...` neben `nvidia/moonshotai/kimi-k2.5`); Auswahloberflächen bewahren die wörtliche Zusammensetzung `<provider>/<model-id>`, während der an die API gesendete kanonische Schlüssel einfach präfixiert bleibt.
</Accordion>
<Accordion title="xAI">
Verwendet den xAI-Responses-Pfad. `grok-4.3` ist das gebündelte Standard-Chatmodell. `/fast` oder `params.fastMode: true` schreibt `grok-3`, `grok-3-mini`, `grok-4` und `grok-4-0709` auf ihre `*-fast`-Varianten um. `tool_stream` ist standardmäßig aktiviert; deaktivieren Sie es über `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
@ -347,11 +348,11 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails.
## Provider über `models.providers` (benutzerdefinierte/Basis-URL)
Verwenden Sie `models.providers` (oder `models.json`), um **benutzerdefinierte** Provider oder OpenAI-/Anthropic-kompatible Proxys hinzuzufügen.
Verwenden Sie `models.providers` (oder `models.json`), um **benutzerdefinierte** Provider oder OpenAI/Anthropic-kompatible Proxys hinzuzufügen.
Viele der unten aufgeführten gebündelten Provider-Plugins veröffentlichen bereits einen Standardkatalog. Verwenden Sie explizite `models.providers.<id>`-Einträge nur, wenn Sie die Standard-Basis-URL, Header oder Modellliste überschreiben möchten.
Gateway-Modellfähigkeitsprüfungen lesen auch explizite `models.providers.<id>.models[]`-Metadaten. Wenn ein benutzerdefiniertes oder Proxy-Modell Bilder akzeptiert, setzen Sie für dieses Modell `input: ["text", "image"]`, damit WebChat- und Node-Ursprungs-Anhangspfade Bilder als native Modelleingaben anstelle reiner Text-Medien-Refs übergeben.
Gateway-Modellfähigkeitsprüfungen lesen außerdem explizite `models.providers.<id>.models[]`-Metadaten. Wenn ein benutzerdefiniertes oder Proxy-Modell Bilder akzeptiert, setzen Sie `input: ["text", "image"]` für dieses Modell, damit WebChat- und Node-Ursprungs-Anhangspfade Bilder als native Modelleingaben statt als reine Text-Medien-Refs übergeben.
### Moonshot AI (Kimi)
@ -395,7 +396,7 @@ Kimi-K2-Modell-IDs:
### Kimi-Coding
Kimi Coding verwendet den Anthropic-kompatiblen Endpoint von Moonshot AI:
Kimi Coding verwendet den Anthropic-kompatiblen Endpunkt von Moonshot AI:
- Provider: `kimi`
- Authentifizierung: `KIMI_API_KEY`
@ -410,7 +411,7 @@ Kimi Coding verwendet den Anthropic-kompatiblen Endpoint von Moonshot AI:
}
```
Legacy `kimi/k2p5` bleibt als Kompatibilitätsmodell-ID akzeptiert.
Legacy `kimi/k2p5` wird weiterhin als Kompatibilitätsmodell-ID akzeptiert.
### Volcano Engine (Doubao)
@ -431,10 +432,10 @@ Volcano Engine (火山引擎) bietet Zugriff auf Doubao und andere Modelle in Ch
Onboarding verwendet standardmäßig die Coding-Oberfläche, aber der allgemeine `volcengine/*`-Katalog wird gleichzeitig registriert.
In den Modellauswahlen für Onboarding/Konfiguration bevorzugt die Volcengine-Authentifizierungsauswahl sowohl `volcengine/*`- als auch `volcengine-plan/*`-Zeilen. Wenn diese Modelle noch nicht geladen sind, fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere Provider-bezogene Auswahl anzuzeigen.
In Modell-Auswahlfeldern beim Onboarding/Konfigurieren bevorzugt die Volcengine-Authentifizierungsoption sowohl `volcengine/*`- als auch `volcengine-plan/*`-Zeilen. Wenn diese Modelle noch nicht geladen sind, fällt OpenClaw auf den ungefilterten Katalog zurück, anstatt ein leeres Provider-spezifisches Auswahlfeld anzuzeigen.
<Tabs>
<Tab title="Standardmodelle">
<Tab title="Standard models">
- `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8)
- `volcengine/doubao-seed-code-preview-251028`
- `volcengine/kimi-k2-5-260127` (Kimi K2.5)
@ -442,7 +443,7 @@ In den Modellauswahlen für Onboarding/Konfiguration bevorzugt die Volcengine-Au
- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
</Tab>
<Tab title="Coding-Modelle (volcengine-plan)">
<Tab title="Coding models (volcengine-plan)">
- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
- `volcengine-plan/kimi-k2.5`
@ -471,16 +472,16 @@ BytePlus ARK bietet internationalen Benutzern Zugriff auf dieselben Modelle wie
Onboarding verwendet standardmäßig die Coding-Oberfläche, aber der allgemeine `byteplus/*`-Katalog wird gleichzeitig registriert.
In den Modellauswahlen für Onboarding/Konfiguration bevorzugt die BytePlus-Authentifizierungsauswahl sowohl `byteplus/*`- als auch `byteplus-plan/*`-Zeilen. Wenn diese Modelle noch nicht geladen sind, fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere Provider-bezogene Auswahl anzuzeigen.
In Modell-Auswahlfeldern beim Onboarding/Konfigurieren bevorzugt die BytePlus-Authentifizierungsoption sowohl `byteplus/*`- als auch `byteplus-plan/*`-Zeilen. Wenn diese Modelle noch nicht geladen sind, fällt OpenClaw auf den ungefilterten Katalog zurück, anstatt ein leeres Provider-spezifisches Auswahlfeld anzuzeigen.
<Tabs>
<Tab title="Standardmodelle">
<Tab title="Standard models">
- `byteplus/seed-1-8-251228` (Seed 1.8)
- `byteplus/kimi-k2-5-260127` (Kimi K2.5)
- `byteplus/glm-4-7-251222` (GLM 4.7)
</Tab>
<Tab title="Coding-Modelle (byteplus-plan)">
<Tab title="Coding models (byteplus-plan)">
- `byteplus-plan/ark-code-latest`
- `byteplus-plan/doubao-seed-code`
- `byteplus-plan/kimi-k2.5`
@ -492,7 +493,7 @@ In den Modellauswahlen für Onboarding/Konfiguration bevorzugt die BytePlus-Auth
### Synthetic
Synthetic stellt Anthropic-kompatible Modelle hinter dem `synthetic`-Provider bereit:
Synthetic stellt Anthropic-kompatible Modelle hinter dem Provider `synthetic` bereit:
- Provider: `synthetic`
- Authentifizierung: `SYNTHETIC_API_KEY`
@ -520,15 +521,15 @@ Synthetic stellt Anthropic-kompatible Modelle hinter dem `synthetic`-Provider be
### MiniMax
MiniMax wird über `models.providers` konfiguriert, weil es benutzerdefinierte Endpunkte verwendet:
MiniMax wird über `models.providers` konfiguriert, da es benutzerdefinierte Endpunkte verwendet:
- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth`
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
- MiniMax API key (Global): `--auth-choice minimax-global-api`
- MiniMax API key (CN): `--auth-choice minimax-cn-api`
- MiniMax API-Schlüssel (Global): `--auth-choice minimax-global-api`
- MiniMax API-Schlüssel (CN): `--auth-choice minimax-cn-api`
- Authentifizierung: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal`
Weitere Informationen zur Einrichtung, zu Modelloptionen und zu Konfigurations-Snippets finden Sie unter [/providers/minimax](/de/providers/minimax).
Setup-Details, Modelloptionen und Konfigurationsausschnitte finden Sie unter [/providers/minimax](/de/providers/minimax).
<Note>
Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw Thinking standardmäßig, sofern Sie es nicht ausdrücklich festlegen, und `/fast on` schreibt `MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um.
@ -536,10 +537,10 @@ Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw Th
Plugin-eigene Aufteilung der Fähigkeiten:
- Text-/Chat-Defaults bleiben auf `minimax/MiniMax-M2.7`
- Bilderzeugung ist `minimax/image-01` oder `minimax-portal/image-01`
- Text-/Chat-Standards bleiben auf `minimax/MiniMax-M2.7`
- Bildgenerierung ist `minimax/image-01` oder `minimax-portal/image-01`
- Bildverständnis ist Plugin-eigenes `MiniMax-VL-01` auf beiden MiniMax-Authentifizierungspfaden
- Websuche bleibt auf Provider-ID `minimax`
- Websuche bleibt auf der Provider-ID `minimax`
### LM Studio
@ -559,7 +560,7 @@ Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der von `http://local
}
```
OpenClaw verwendet LM Studios natives `/api/v1/models` und `/api/v1/models/load` für Discovery und automatisches Laden, standardmäßig mit `/v1/chat/completions` für Inferenz. Wenn Sie möchten, dass LM Studio JIT-Laden, TTL und automatisches Entfernen den Modelllebenszyklus übernehmen, setzen Sie `models.providers.lmstudio.params.preload: false`. Informationen zur Einrichtung und Fehlerbehebung finden Sie unter [/providers/lmstudio](/de/providers/lmstudio).
OpenClaw verwendet die nativen LM Studio-Endpunkte `/api/v1/models` und `/api/v1/models/load` für Discovery + automatisches Laden, standardmäßig mit `/v1/chat/completions` für Inferenz. Wenn Sie möchten, dass LM Studio JIT-Laden, TTL und automatische Verdrängung für den Modelllebenszyklus übernimmt, setzen Sie `models.providers.lmstudio.params.preload: false`. Setup und Fehlerbehebung finden Sie unter [/providers/lmstudio](/de/providers/lmstudio).
### Ollama
@ -583,7 +584,7 @@ ollama pull llama3.3
}
```
Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie es mit `OLLAMA_API_KEY` aktivieren, und das gebündelte Provider-Plugin fügt Ollama direkt zu `openclaw onboard` und zur Modellauswahl hinzu. Informationen zu Onboarding, Cloud-/Lokalmodus und benutzerdefinierter Konfiguration finden Sie unter [/providers/ollama](/de/providers/ollama).
Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie es mit `OLLAMA_API_KEY` aktivieren, und das gebündelte Provider-Plugin fügt Ollama direkt zu `openclaw onboard` und der Modellauswahl hinzu. Onboarding, Cloud-/lokaler Modus und benutzerdefinierte Konfiguration finden Sie unter [/providers/ollama](/de/providers/ollama).
### vLLM
@ -593,7 +594,7 @@ vLLM wird als gebündeltes Provider-Plugin für lokale/selbst gehostete OpenAI-k
- Authentifizierung: Optional (hängt von Ihrem Server ab)
- Standard-Basis-URL: `http://127.0.0.1:8000/v1`
So aktivieren Sie lokale Auto-Discovery (jeder Wert funktioniert, wenn Ihr Server keine Authentifizierung erzwingt):
Um lokale Auto-Discovery zu aktivieren (jeder Wert funktioniert, wenn Ihr Server keine Authentifizierung erzwingt):
```bash
export VLLM_API_KEY="vllm-local"
@ -609,7 +610,7 @@ Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der von `/v1/models`
}
```
Details finden Sie unter [/providers/vllm](/de/providers/vllm).
Weitere Details finden Sie unter [/providers/vllm](/de/providers/vllm).
### SGLang
@ -619,7 +620,7 @@ SGLang wird als gebündeltes Provider-Plugin für schnelle selbst gehostete Open
- Authentifizierung: Optional (hängt von Ihrem Server ab)
- Standard-Basis-URL: `http://127.0.0.1:30000/v1`
So aktivieren Sie lokale Auto-Discovery (jeder Wert funktioniert, wenn Ihr Server keine Authentifizierung erzwingt):
Um lokale Auto-Discovery zu aktivieren (jeder Wert funktioniert, wenn Ihr Server keine Authentifizierung erzwingt):
```bash
export SGLANG_API_KEY="sglang-local"
@ -635,7 +636,7 @@ Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der von `/v1/models`
}
```
Details finden Sie unter [/providers/sglang](/de/providers/sglang).
Weitere Details finden Sie unter [/providers/sglang](/de/providers/sglang).
### Lokale Proxys (LM Studio, vLLM, LiteLLM usw.)
@ -674,7 +675,7 @@ Beispiel (OpenAI-kompatibel):
```
<AccordionGroup>
<Accordion title="Optionale Standardfelder">
<Accordion title="Default optional fields">
Für benutzerdefinierte Provider sind `reasoning`, `input`, `cost`, `contextWindow` und `maxTokens` optional. Wenn sie weggelassen werden, verwendet OpenClaw standardmäßig:
- `reasoning: false`
@ -686,16 +687,16 @@ Beispiel (OpenAI-kompatibel):
Empfohlen: Legen Sie explizite Werte fest, die zu den Limits Ihres Proxys/Modells passen.
</Accordion>
<Accordion title="Regeln für die Proxy-Routenformung">
- Für `api: "openai-completions"` auf nicht nativen Endpunkten (jede nicht leere `baseUrl`, deren Host nicht `api.openai.com` ist) erzwingt OpenClaw `compat.supportsDeveloperRole: false`, um Provider-400-Fehler wegen nicht unterstützter `developer`-Rollen zu vermeiden.
- Proxy-artige OpenAI-kompatible Routen überspringen außerdem natives, nur OpenAI-spezifisches Request-Shaping: kein `service_tier`, kein Responses-`store`, kein Completions-`store`, keine Prompt-Cache-Hinweise, kein OpenAI-Reasoning-Kompatibilitäts-Payload-Shaping und keine versteckten OpenClaw-Zuordnungs-Header.
- Für OpenAI-kompatible Completions-Proxys, die herstellerspezifische Felder benötigen, setzen Sie `agents.defaults.models["provider/model"].params.extra_body` (oder `extraBody`), um zusätzliches JSON in den ausgehenden Request-Body einzufügen.
- Für vLLM-Chat-Template-Steuerungen setzen Sie `agents.defaults.models["provider/model"].params.chat_template_kwargs`. Das gebündelte vLLM-Plugin sendet automatisch `enable_thinking: false` und `force_nonempty_content: true` für `vllm/nemotron-3-*`, wenn das Session-Thinking-Level deaktiviert ist.
- Für langsame lokale Modelle oder Remote-LAN-/Tailnet-Hosts setzen Sie `models.providers.<id>.timeoutSeconds`. Dadurch wird die HTTP-Request-Verarbeitung des Provider-Modells erweitert, einschließlich Verbindungsaufbau, Headern, Body-Streaming und dem gesamten abgesicherten Fetch-Abbruch, ohne das gesamte Agent-Runtime-Timeout zu erhöhen.
- HTTP-Aufrufe an Modell-Provider erlauben Surge-, Clash- und sing-box-Fake-IP-DNS-Antworten in `198.18.0.0/15` und `fc00::/7` nur für den konfigurierten Provider-`baseUrl`-Hostnamen. Andere private, loopback-, link-local- und Metadatenziele erfordern weiterhin eine explizite Aktivierung mit `models.providers.<id>.request.allowPrivateNetwork: true`.
- Wenn `baseUrl` leer ist oder weggelassen wird, behält OpenClaw das standardmäßige OpenAI-Verhalten bei (das zu `api.openai.com` auflöst).
<Accordion title="Proxy-route shaping rules">
- Für `api: "openai-completions"` auf nicht nativen Endpunkten (jede nicht leere `baseUrl`, deren Host nicht `api.openai.com` ist) erzwingt OpenClaw `compat.supportsDeveloperRole: false`, um Provider-400-Fehler für nicht unterstützte `developer`-Rollen zu vermeiden.
- Proxy-artige OpenAI-kompatible Routen überspringen außerdem nur für natives OpenAI geltende Request-Anpassungen: kein `service_tier`, kein Responses-`store`, kein Completions-`store`, keine Prompt-Cache-Hinweise, keine OpenAI-Reasoning-Kompatibilitäts-Payload-Anpassung und keine verborgenen OpenClaw-Attributions-Header.
- Für OpenAI-kompatible Completions-Proxys, die anbieterspezifische Felder benötigen, setzen Sie `agents.defaults.models["provider/model"].params.extra_body` (oder `extraBody`), um zusätzliches JSON in den ausgehenden Request-Body zu mergen.
- Für vLLM-Chat-Template-Steuerungen setzen Sie `agents.defaults.models["provider/model"].params.chat_template_kwargs`. Das gebündelte vLLM-Plugin sendet automatisch `enable_thinking: false` und `force_nonempty_content: true` für `vllm/nemotron-3-*`, wenn die Thinking-Stufe der Sitzung deaktiviert ist.
- Für langsame lokale Modelle oder entfernte LAN-/Tailnet-Hosts setzen Sie `models.providers.<id>.timeoutSeconds`. Dies erweitert die HTTP-Request-Verarbeitung des Provider-Modells, einschließlich Verbindung, Headern, Body-Streaming und dem gesamten abgesicherten Fetch-Abbruch, ohne das Laufzeit-Timeout des gesamten Agenten zu erhöhen.
- HTTP-Aufrufe des Modell-Providers erlauben Surge-, Clash- und sing-box-Fake-IP-DNS-Antworten in `198.18.0.0/15` und `fc00::/7` nur für den konfigurierten `baseUrl`-Hostnamen des Providers. Andere private, loopback-, link-local- und Metadaten-Ziele erfordern weiterhin eine explizite Aktivierung mit `models.providers.<id>.request.allowPrivateNetwork: true`.
- Wenn `baseUrl` leer ist oder weggelassen wird, behält OpenClaw das Standardverhalten von OpenAI bei (das zu `api.openai.com` auflöst).
- Aus Sicherheitsgründen wird ein explizites `compat.supportsDeveloperRole: true` auf nicht nativen `openai-completions`-Endpunkten weiterhin überschrieben.
- Für `api: "anthropic-messages"` auf nicht direkten Endpunkten (jeder Provider außer dem kanonischen `anthropic` oder eine benutzerdefinierte `models.providers.anthropic.baseUrl`, deren Host kein öffentlicher `api.anthropic.com`-Endpunkt ist) unterdrückt OpenClaw implizite Anthropic-Beta-Header wie `claude-code-20250219`, `interleaved-thinking-2025-05-14` und OAuth-Marker, damit benutzerdefinierte Anthropic-kompatible Proxys nicht unterstützte Beta-Flags nicht ablehnen. Setzen Sie `models.providers.<id>.headers["anthropic-beta"]` explizit, wenn Ihr Proxy bestimmte Beta-Features benötigt.
- Für `api: "anthropic-messages"` auf nicht direkten Endpunkten (jeder Provider außer dem kanonischen `anthropic` oder eine benutzerdefinierte `models.providers.anthropic.baseUrl`, deren Host kein öffentlicher `api.anthropic.com`-Endpunkt ist) unterdrückt OpenClaw implizite Anthropic-Beta-Header wie `claude-code-20250219`, `interleaved-thinking-2025-05-14` und OAuth-Marker, damit benutzerdefinierte Anthropic-kompatible Proxys nicht unterstützte Beta-Flags nicht ablehnen. Setzen Sie `models.providers.<id>.headers["anthropic-beta"]` explizit, wenn Ihr Proxy bestimmte Beta-Funktionen benötigt.
</Accordion>
</AccordionGroup>
@ -715,4 +716,4 @@ Siehe auch: [Konfiguration](/de/gateway/configuration) für vollständige Konfig
- [Konfigurationsreferenz](/de/gateway/config-agents#agent-defaults) - Modellkonfigurationsschlüssel
- [Modell-Failover](/de/concepts/model-failover) - Fallback-Ketten und Wiederholungsverhalten
- [Modelle](/de/concepts/models) - Modellkonfiguration und Aliasse
- [Provider](/de/providers) - Einrichtungshandbücher pro Provider
- [Provider](/de/providers) - Setup-Leitfäden pro Provider

90
docs/de/install/ansible.md
View File

@ -1,44 +1,42 @@
---
read_when:
- Sie möchten eine automatisierte Serverbereitstellung mit Sicherheitshärtung
- Sie benötigen eine durch eine Firewall isolierte Einrichtung mit VPN-Zugriff
- Sie stellen auf entfernten Debian/Ubuntu-Servern bereit
- Sie benötigen eine durch eine Firewall isolierte Umgebung mit VPN-Zugriff
- Sie stellen auf entfernten Debian-/Ubuntu-Servern bereit
summary: Automatisierte, gehärtete OpenClaw-Installation mit Ansible, Tailscale-VPN und Firewall-Isolierung
title: Ansible
x-i18n:
generated_at: "2026-05-02T06:37:19Z"
generated_at: "2026-05-06T09:03:04Z"
model: gpt-5.5
provider: openai
source_hash: 789763c82483f4eec0963f4dccb06f2daa22d470a5e69e275f38c70a00a10ba4
source_hash: a7424e766619096f50fa0c83aa4e85e46adba11515b1871e58cf2406b7c8f815
source_path: install/ansible.md
workflow: 16
---
# Ansible-Installation
Stellen Sie OpenClaw mit **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** auf Produktionsservern bereit -- einem automatisierten Installer mit Security-first-Architektur.
Stellen Sie OpenClaw mit **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)** auf Produktionsservern bereit -- einem automatisierten Installer mit einer Architektur, die Sicherheit priorisiert.
<Info>
Das Repository [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) ist die maßgebliche Quelle für das Ansible-Deployment. Diese Seite bietet einen kurzen Überblick.
Das Repository [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) ist die maßgebliche Quelle für die Ansible-Bereitstellung. Diese Seite bietet einen kurzen Überblick.
</Info>
## Voraussetzungen
| Anforderung | Details |
| ----------- | --------------------------------------------------------- |
| **OS** | Debian 11+ oder Ubuntu 20.04+ |
| **Zugriff** | Root- oder sudo-Berechtigungen |
| **Netzwerk** | Internetverbindung für die Paketinstallation |
| **Ansible** | 2.14+ (wird automatisch vom Schnellstart-Skript installiert) |
| Anforderung | Details |
| ----------------- | ---------------------------------------------------------------- |
| **Betriebssystem** | Debian 11+ oder Ubuntu 20.04+ |
| **Zugriff** | Root- oder sudo-Berechtigungen |
| **Netzwerk** | Internetverbindung für die Paketinstallation |
| **Ansible** | 2.14+ (wird vom Schnellstart-Skript automatisch installiert) |
## Was Sie erhalten
- **Firewall-first-Sicherheit** -- UFW + Docker-Isolation (nur SSH + Tailscale erreichbar)
- **Tailscale-VPN** -- sicherer Remote-Zugriff, ohne Dienste öffentlich offenzulegen
- **Firewall-zuerst-Sicherheit** -- UFW + Docker-Isolation (nur SSH + Tailscale zugänglich)
- **Tailscale-VPN** -- sicherer Remote-Zugriff, ohne Dienste öffentlich bereitzustellen
- **Docker** -- isolierte Sandbox-Container, Bindings nur an localhost
- **Defense in Depth** -- 4-schichtige Sicherheitsarchitektur
- **Systemd-Integration** -- automatischer Start beim Booten mit Hardening
- **Ein-Befehl-Setup** -- vollständiges Deployment in wenigen Minuten
- **Defense in depth** -- 4-Schichten-Sicherheitsarchitektur
- **Systemd-Integration** -- automatischer Start beim Booten mit Härtung
- **Einrichtung mit einem Befehl** -- vollständige Bereitstellung in wenigen Minuten
## Schnellstart
@ -53,16 +51,16 @@ curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/inst
Das Ansible-Playbook installiert und konfiguriert:
1. **Tailscale** -- Mesh-VPN für sicheren Remote-Zugriff
2. **UFW-Firewall** -- nur SSH- + Tailscale-Ports
3. **Docker CE + Compose V2** -- für das standardmäßige Agent-Sandbox-Backend
4. **Node.js 24 + pnpm** -- Runtime-Abhängigkeiten (Node 22 LTS, derzeit `22.14+`, bleibt unterstützt)
2. **UFW-Firewall** -- nur SSH- und Tailscale-Ports
3. **Docker CE + Compose V2** -- für das Standard-Backend der Agent-Sandbox
4. **Node.js 24 + pnpm** -- Laufzeitabhängigkeiten (Node 22 LTS, derzeit `22.14+`, bleibt unterstützt)
5. **OpenClaw** -- hostbasiert, nicht containerisiert
6. **Systemd-Dienst** -- automatischer Start mit Security Hardening
6. **Systemd-Dienst** -- automatischer Start mit Sicherheitshärtung
<Note>
Das Gateway läuft direkt auf dem Host (nicht in Docker). Agent-Sandboxing ist
optional; dieses Playbook installiert Docker, weil es das standardmäßige Sandbox-
Backend ist. Weitere Details und andere Backends finden Sie unter [Sandboxing](/de/gateway/sandboxing).
Der Gateway läuft direkt auf dem Host (nicht in Docker). Agent-Sandboxing ist
optional; dieses Playbook installiert Docker, weil es das Standard-Sandbox-
Backend ist. Siehe [Sandboxing](/de/gateway/sandboxing) für Details und andere Backends.
</Note>
## Einrichtung nach der Installation
@ -73,8 +71,8 @@ Backend ist. Weitere Details und andere Backends finden Sie unter [Sandboxing](/
sudo -i -u openclaw
```
</Step>
<Step title="Onboarding-Assistent ausführen">
Das Post-Installationsskript führt Sie durch die Konfiguration der OpenClaw-Einstellungen.
<Step title="Onboarding-Assistenten ausführen">
Das Post-Installations-Skript führt Sie durch die Konfiguration der OpenClaw-Einstellungen.
</Step>
<Step title="Messaging-Provider verbinden">
Melden Sie sich bei WhatsApp, Telegram, Discord oder Signal an:
@ -112,12 +110,12 @@ openclaw channels login
## Sicherheitsarchitektur
Das Deployment verwendet ein 4-schichtiges Defense-in-Depth-Modell:
Die Bereitstellung verwendet ein 4-Schichten-Verteidigungsmodell:
1. **Firewall (UFW)** -- nur SSH (22) + Tailscale (41641/udp) sind öffentlich exponiert
2. **VPN (Tailscale)** -- Gateway ist nur über das VPN-Mesh erreichbar
3. **Docker-Isolation** -- die DOCKER-USER-iptables-Chain verhindert externe Port-Exposition
4. **Systemd-Hardening** -- NoNewPrivileges, PrivateTmp, unprivilegierter Benutzer
1. **Firewall (UFW)** -- nur SSH (22) + Tailscale (41641/udp) sind öffentlich erreichbar
2. **VPN (Tailscale)** -- Gateway nur über das VPN-Mesh erreichbar
3. **Docker-Isolation** -- DOCKER-USER-iptables-Chain verhindert externe Portfreigaben
4. **Systemd-Härtung** -- NoNewPrivileges, PrivateTmp, unprivilegierter Benutzer
So überprüfen Sie Ihre externe Angriffsfläche:
@ -125,13 +123,13 @@ So überprüfen Sie Ihre externe Angriffsfläche:
nmap -p- YOUR_SERVER_IP
```
Nur Port 22 (SSH) sollte geöffnet sein. Alle anderen Dienste (Gateway, Docker) sind gesperrt.
Nur Port 22 (SSH) sollte offen sein. Alle anderen Dienste (Gateway, Docker) sind gesperrt.
Docker wird für Agent-Sandboxen (isolierte Tool-Ausführung) installiert, nicht zum Ausführen des Gateway selbst. Informationen zur Sandbox-Konfiguration finden Sie unter [Multi-Agent Sandbox and Tools](/de/tools/multi-agent-sandbox-tools).
Docker wird für Agent-Sandboxes (isolierte Tool-Ausführung) installiert, nicht zum Ausführen des Gateways selbst. Siehe [Multi-Agent Sandbox und Tools](/de/tools/multi-agent-sandbox-tools) für die Sandbox-Konfiguration.
## Manuelle Installation
Wenn Sie manuelle Kontrolle der Automatisierung vorziehen:
Wenn Sie manuelle Kontrolle gegenüber der Automatisierung bevorzugen:
<Steps>
<Step title="Voraussetzungen installieren">
@ -155,7 +153,7 @@ Wenn Sie manuelle Kontrolle der Automatisierung vorziehen:
./run-playbook.sh
```
Alternativ können Sie es direkt ausführen und anschließend das Setup-Skript manuell ausführen:
Alternativ können Sie es direkt ausführen und anschließend das Einrichtungsskript manuell ausführen:
```bash
ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/openclaw-setup.sh
@ -166,7 +164,7 @@ Wenn Sie manuelle Kontrolle der Automatisierung vorziehen:
## Aktualisierung
Der Ansible-Installer richtet OpenClaw für manuelle Updates ein. Den Standard-Update-Ablauf finden Sie unter [Aktualisierung](/de/install/updating).
Der Ansible-Installer richtet OpenClaw für manuelle Updates ein. Siehe [Aktualisierung](/de/install/updating) für den Standard-Update-Ablauf.
So führen Sie das Ansible-Playbook erneut aus (zum Beispiel für Konfigurationsänderungen):
@ -181,9 +179,9 @@ Dies ist idempotent und kann sicher mehrfach ausgeführt werden.
<AccordionGroup>
<Accordion title="Firewall blockiert meine Verbindung">
- Stellen Sie sicher, dass Sie zuerst über das Tailscale-VPN zugreifen können
- Stellen Sie sicher, dass Sie zuerst Zugriff über das Tailscale-VPN haben
- SSH-Zugriff (Port 22) ist immer erlaubt
- Das Gateway ist absichtlich nur über Tailscale erreichbar
- Der Gateway ist konstruktionsbedingt nur über Tailscale erreichbar
</Accordion>
<Accordion title="Dienst startet nicht">
@ -201,7 +199,7 @@ Dies ist idempotent und kann sicher mehrfach ausgeführt werden.
```
</Accordion>
<Accordion title="Docker-Sandbox-Probleme">
<Accordion title="Probleme mit der Docker-Sandbox">
```bash
# Verify Docker is running
sudo systemctl status docker
@ -217,7 +215,7 @@ Dies ist idempotent und kann sicher mehrfach ausgeführt werden.
```
</Accordion>
<Accordion title="Provider-Login schlägt fehl">
<Accordion title="Provider-Anmeldung schlägt fehl">
Stellen Sie sicher, dass Sie als Benutzer `openclaw` ausführen:
```bash
sudo -i -u openclaw
@ -228,7 +226,7 @@ Dies ist idempotent und kann sicher mehrfach ausgeführt werden.
## Erweiterte Konfiguration
Ausführliche Informationen zur Sicherheitsarchitektur und Fehlerbehebung finden Sie im Repository openclaw-ansible:
Ausführliche Informationen zur Sicherheitsarchitektur und Fehlerbehebung finden Sie im openclaw-ansible-Repository:
- [Sicherheitsarchitektur](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
- [Technische Details](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
@ -236,7 +234,7 @@ Ausführliche Informationen zur Sicherheitsarchitektur und Fehlerbehebung finden
## Verwandte Themen
- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) -- vollständiger Deployment-Leitfaden
- [Docker](/de/install/docker) -- containerisiertes Gateway-Setup
- [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) -- vollständiger Bereitstellungsleitfaden
- [Docker](/de/install/docker) -- containerisierte Gateway-Einrichtung
- [Sandboxing](/de/gateway/sandboxing) -- Agent-Sandbox-Konfiguration
- [Multi-Agent Sandbox and Tools](/de/tools/multi-agent-sandbox-tools) -- Isolation pro Agent
- [Multi-Agent Sandbox und Tools](/de/tools/multi-agent-sandbox-tools) -- Isolation pro Agent

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

File diff suppressed because it is too large Load Diff

121
docs/de/plugins/dependency-resolution.md
View File

@ -1,50 +1,50 @@
---
read_when:
- Sie debuggen Installationen von Plugin-Paketen
- Sie ändern das Startverhalten von Plugins, Doctor oder das Installationsverhalten des Paketmanagers
- Sie verwalten paketierte OpenClaw-Installationen oder gebündelte Plugin-Manifeste
- Sie debuggen Plugin-Paketinstallationen
- Sie ändern das Plugin-Startverhalten, Doctor-Verhalten oder Installationsverhalten des Paketmanagers
- Sie pflegen paketierte OpenClaw-Installationen oder gebündelte Plugin-Manifeste
sidebarTitle: Dependencies
summary: Wie OpenClaw Plugin-Pakete installiert und Plugin-Abhängigkeiten auflöst
title: Auflösung von Plugin-Abhängigkeiten
x-i18n:
generated_at: "2026-05-06T06:57:34Z"
generated_at: "2026-05-06T09:03:43Z"
model: gpt-5.5
provider: openai
source_hash: 4ef307fb034d397a5e2e991254fb881046c73a4e6d860073b90f2b4e0667edc2
source_hash: e06f1fdc34c8392cbf0e399484fd59af11b9b7d73c5c7e68b3617a7cfd433a36
source_path: plugins/dependency-resolution.md
workflow: 16
---
# Plugin-Abhängigkeitsauflösung
OpenClaw hält die Arbeit an Plugin-Abhängigkeiten auf die Installations-/Update-Zeit beschränkt. Das Laden zur Laufzeit
OpenClaw erledigt die Arbeit an Plugin-Abhängigkeiten zur Installations-/Aktualisierungszeit. Das Laden zur Laufzeit
führt keine Paketmanager aus, repariert keine Abhängigkeitsbäume und verändert nicht das OpenClaw-
Paketverzeichnis.
## Aufteilung der Verantwortlichkeiten
## Verantwortungsaufteilung
Plugin-Pakete besitzen ihren Abhängigkeitsgraphen:
- Laufzeitabhängigkeiten befinden sich in den Plugin-Paket-`dependencies` oder
`optionalDependencies`
- SDK-/Core-Importe sind Peer- oder von OpenClaw bereitgestellte Importe
- lokale Entwicklungs-Plugins bringen ihre eigenen, bereits installierten Abhängigkeiten mit
- npm- und git-Plugins werden in OpenClaw-eigene Paket-Roots installiert
- Laufzeitabhängigkeiten befinden sich in den `dependencies` oder
`optionalDependencies` des Plugin-Pakets
- SDK-/Core-Imports sind Peer- oder von OpenClaw bereitgestellte Imports
- lokale Entwicklungs-Plugins bringen ihre eigenen bereits installierten Abhängigkeiten mit
- npm- und Git-Plugins werden in OpenClaw-eigene Paket-Roots installiert
OpenClaw besitzt nur den Plugin-Lebenszyklus:
- die Plugin-Quelle erkennen
- das Paket installieren oder aktualisieren, wenn dies ausdrücklich angefordert wird
- die Installationsmetadaten aufzeichnen
- den Plugin-Einstiegspunkt laden
- mit einem umsetzbaren Fehler fehlschlagen, wenn Abhängigkeiten fehlen
- Plugin-Quelle ermitteln
- Paket installieren oder aktualisieren, wenn dies explizit angefordert wird
- Installationsmetadaten aufzeichnen
- Plugin-Einstiegspunkt laden
- mit einem handlungsorientierten Fehler fehlschlagen, wenn Abhängigkeiten fehlen
## Installations-Roots
OpenClaw verwendet stabile Roots pro Quelle:
- npm-Pakete werden unter `~/.openclaw/npm` installiert
- git-Pakete werden unter `~/.openclaw/git` geklont
- Git-Pakete werden unter `~/.openclaw/git` geklont
- lokale/Pfad-/Archiv-Installationen werden ohne Abhängigkeitsreparatur kopiert oder referenziert
npm-Installationen laufen im npm-Root mit:
@ -53,29 +53,53 @@ npm-Installationen laufen im npm-Root mit:
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
```
npm kann transitive Abhängigkeiten neben dem Plugin-Paket nach `~/.openclaw/npm/node_modules` hoisten. OpenClaw scannt den verwalteten npm-Root, bevor es der Installation vertraut, und verwendet npm, um npm-verwaltete Pakete während der Deinstallation zu entfernen, sodass gehoistete Laufzeitabhängigkeiten innerhalb der verwalteten Bereinigungsgrenze bleiben.
`openclaw plugins install npm-pack:<path.tgz>` verwendet denselben verwalteten npm-Root
für einen lokalen npm-pack-Tarball. OpenClaw liest die npm-Metadaten des Tarballs, fügt ihn
dem verwalteten Root als kopierte `file:`-Abhängigkeit hinzu, führt die normale npm-Installation aus
und prüft anschließend die installierten Lockfile-Metadaten, bevor dem Plugin vertraut wird.
Dies ist für Paketakzeptanz- und Release-Candidate-Nachweise gedacht, bei denen ein
lokales Pack-Artefakt sich wie das Registry-Artefakt verhalten soll, das es simuliert.
Plugins, die `openclaw/plugin-sdk/*` importieren, deklarieren `openclaw` als Peer-Abhängigkeit. OpenClaw lässt npm keine separate Registry-Kopie des Host-Pakets in den verwalteten Root installieren, weil veraltete Host-Pakete die npm-Peer-Auflösung bei späteren Plugin-Installationen beeinflussen können. Stattdessen setzt OpenClaw, nachdem npm den gemeinsam genutzten Root während Installation, Update oder Deinstallation verändert hat, Plugin-lokale `node_modules/openclaw`-Links für installierte Pakete erneut durch, die den Host-Peer deklarieren.
npm kann transitive Abhängigkeiten nach `~/.openclaw/npm/node_modules` neben
das Plugin-Paket hoisten. OpenClaw scannt den verwalteten npm-Root, bevor der
Installation vertraut wird, und verwendet npm, um npm-verwaltete Pakete während der Deinstallation zu entfernen, sodass gehoistete
Laufzeitabhängigkeiten innerhalb der verwalteten Bereinigungsgrenze bleiben.
git-Installationen klonen oder aktualisieren das Repository und führen dann aus:
Plugins, die `openclaw/plugin-sdk/*` importieren, deklarieren `openclaw` als Peer-
Abhängigkeit. OpenClaw lässt npm keine separate Registry-Kopie des
Host-Pakets in den verwalteten Root installieren, weil veraltete Host-Pakete die npm-
Peer-Auflösung bei späteren Plugin-Installationen beeinflussen können. Stattdessen stellt OpenClaw, nachdem npm
den gemeinsamen Root während Installation, Aktualisierung oder Deinstallation verändert hat, erneut
Plugin-lokale `node_modules/openclaw`-Links für installierte Pakete her, die
den Host-Peer deklarieren.
Git-Installationen klonen oder aktualisieren das Repository und führen dann aus:
```bash
npm install --omit=dev --ignore-scripts --no-audit --no-fund
```
Das installierte Plugin wird dann aus diesem Paketverzeichnis geladen, sodass paketlokale und übergeordnete `node_modules`-Auflösung genauso funktioniert wie bei einem normalen Node-Paket.
Das installierte Plugin wird dann aus diesem Paketverzeichnis geladen, sodass die paketlokale
und übergeordnete `node_modules`-Auflösung genauso funktioniert wie bei einem normalen
Node-Paket.
## Lokale Plugins
Lokale Plugins werden als von Entwicklern kontrollierte Verzeichnisse behandelt. OpenClaw führt für sie weder `npm install`, `pnpm install` noch Abhängigkeitsreparaturen aus. Wenn ein lokales Plugin Abhängigkeiten hat, installieren Sie diese in diesem Plugin, bevor Sie es laden.
Lokale Plugins werden als entwicklerkontrollierte Verzeichnisse behandelt. OpenClaw führt für sie kein
`npm install`, `pnpm install` und keine Abhängigkeitsreparatur aus. Wenn ein lokales
Plugin Abhängigkeiten hat, installieren Sie diese in diesem Plugin, bevor Sie es laden.
Lokale TypeScript-Plugins von Drittanbietern können den Notfallpfad über Jiti verwenden. Paketierte JavaScript-Plugins und gebündelte interne Plugins werden über natives import/require statt über Jiti geladen.
Lokale TypeScript-Plugins von Drittanbietern können den Notfall-Jiti-Pfad verwenden. Paketierte
JavaScript-Plugins und gebündelte interne Plugins werden über natives
import/require statt über Jiti geladen.
## Start und Neuladen
Gateway-Start und Konfigurations-Neuladen installieren niemals Plugin-Abhängigkeiten. Sie lesen die Plugin-Installationsdatensätze, berechnen den Einstiegspunkt und laden ihn.
Gateway-Start und Konfigurations-Reload installieren niemals Plugin-Abhängigkeiten. Sie lesen
die Plugin-Installationsdatensätze, berechnen den Einstiegspunkt und laden ihn.
Wenn zur Laufzeit eine Abhängigkeit fehlt, schlägt das Laden des Plugins fehl, und der Fehler sollte den Betreiber auf eine explizite Behebung hinweisen:
Wenn zur Laufzeit eine Abhängigkeit fehlt, kann das Plugin nicht geladen werden, und der Fehler
sollte den Betreiber auf eine explizite Korrektur hinweisen:
```bash
openclaw plugins update <id>
@ -83,26 +107,45 @@ openclaw plugins install <source>
openclaw doctor --fix
```
`doctor --fix` kann von OpenClaw erzeugten Legacy-Abhängigkeitszustand bereinigen und herunterladbare Plugins wiederherstellen, die in den lokalen Installationsdatensätzen fehlen, wenn die Konfiguration auf sie verweist. Doctor repariert keine Abhängigkeiten für ein bereits installiertes lokales Plugin.
`doctor --fix` kann alten von OpenClaw generierten Abhängigkeitszustand bereinigen und
herunterladbare Plugins wiederherstellen, die in den lokalen Installationsdatensätzen fehlen, wenn die Konfiguration
auf sie verweist. Doctor repariert keine Abhängigkeiten für ein bereits installiertes
lokales Plugin.
## Gebündelte Plugins
Leichtgewichtige und für den Core kritische gebündelte Plugins werden als Teil von OpenClaw ausgeliefert. Sie sollten entweder keinen schweren Laufzeit-Abhängigkeitsbaum haben oder in ein herunterladbares Paket auf ClawHub/npm verschoben werden.
Leichtgewichtige und core-kritische gebündelte Plugins werden als Teil von OpenClaw ausgeliefert.
Sie sollten entweder keinen schweren Laufzeit-Abhängigkeitsbaum haben oder in ein
herunterladbares Paket auf ClawHub/npm ausgelagert werden.
Die aktuelle generierte Liste der Plugins, die im Core-Paket ausgeliefert, extern installiert oder nur als Quellcode behalten werden, finden Sie unter [Plugin-Bestand](/de/plugins/plugin-inventory).
Die aktuelle generierte Liste der Plugins, die im Core-Paket ausgeliefert,
extern installiert oder nur als Quellcode behalten werden, finden Sie im [Plugin-Bestand](/de/plugins/plugin-inventory).
Manifestdateien gebündelter Plugins dürfen kein Dependency-Staging anfordern. Große oder optionale Plugin-Funktionalität sollte als normales Plugin paketiert und über denselben npm-/git-/ClawHub-Pfad wie Drittanbieter-Plugins installiert werden.
Gebündelte Plugin-Manifeste dürfen kein Abhängigkeits-Staging anfordern. Große oder optionale
Plugin-Funktionalität sollte als normales Plugin paketiert und über
denselben npm-/Git-/ClawHub-Pfad wie Drittanbieter-Plugins installiert werden.
In Quell-Checkouts behandelt OpenClaw das Repository als pnpm-Monorepo. Nach `pnpm install` werden gebündelte Plugins aus `extensions/<id>` geladen, sodass paketlokale Workspace-Abhängigkeiten verfügbar sind und Änderungen direkt übernommen werden. Entwicklung in Quell-Checkouts ist ausschließlich pnpm-basiert; ein einfaches `npm install` im Repository-Root ist kein unterstützter Weg, um Abhängigkeiten gebündelter Plugins vorzubereiten.
In Quell-Checkouts behandelt OpenClaw das Repository als pnpm-Monorepo. Nach
`pnpm install` werden gebündelte Plugins aus `extensions/<id>` geladen, sodass paketlokale
Workspace-Abhängigkeiten verfügbar sind und Änderungen direkt übernommen werden. Die Entwicklung in Quell-
Checkouts ist ausschließlich pnpm-basiert; ein einfaches `npm install` im Repository-Root ist
keine unterstützte Methode, um gebündelte Plugin-Abhängigkeiten vorzubereiten.
| Installationsform | Speicherort des gebündelten Plugins | Eigentümer der Abhängigkeiten |
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw` | Gebauter Laufzeitbaum innerhalb des Pakets | OpenClaw-Paket und explizite Plugin-Installations-/Update-/Doctor-Flows |
| Git-Checkout plus `pnpm install` | `extensions/<id>`-Workspace-Pakete | Der pnpm-Workspace, einschließlich der eigenen Abhängigkeiten jedes Plugin-Pakets |
| `openclaw plugins install ...` | Verwalteter npm-/git-/ClawHub-Plugin-Root | Der Plugin-Installations-/Update-Flow |
| Installationsform | Speicherort des gebündelten Plugins | Eigentümer der Abhängigkeiten |
| --------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw` | Gebauter Laufzeitbaum im Paket | OpenClaw-Paket und explizite Plugin-Installations-/Aktualisierungs-/Doctor-Abläufe |
| Git-Checkout plus `pnpm install` | `extensions/<id>`-Workspace-Pakete | Der pnpm-Workspace, einschließlich der eigenen Abhängigkeiten jedes Plugin-Pakets |
| `openclaw plugins install ...` | Verwalteter npm-/Git-/ClawHub-Plugin-Root | Der Plugin-Installations-/Aktualisierungsablauf |
## Legacy-Bereinigung
## Bereinigung von Altlasten
Ältere OpenClaw-Versionen erzeugten Roots für Abhängigkeiten gebündelter Plugins beim Start oder während der Doctor-Reparatur. Die aktuelle Doctor-Bereinigung entfernt diese veralteten Verzeichnisse und Symlinks, wenn `--fix` verwendet wird, einschließlich alter `plugin-runtime-deps`-Roots, globaler Node-Präfix-Paket-Symlinks, die auf entfernte `plugin-runtime-deps`-Ziele zeigen, `.openclaw-runtime-deps*`-Manifeste, erzeugter Plugin-`node_modules`, Installations-Staging-Verzeichnisse und paketlokaler pnpm-Stores. Paketierte Postinstall-Schritte entfernen außerdem diese globalen Symlinks, bevor die Legacy-Ziel-Roots entfernt werden, damit Upgrades keine hängenden ESM-Paketimporte zurücklassen.
Ältere OpenClaw-Versionen erzeugten Roots für Abhängigkeiten gebündelter Plugins beim Start oder
während der Doctor-Reparatur. Die aktuelle Doctor-Bereinigung entfernt diese veralteten Verzeichnisse und
Symlinks, wenn `--fix` verwendet wird, einschließlich alter `plugin-runtime-deps`-Roots, globaler
Node-Präfix-Paketsymlinks, die auf bereinigte `plugin-runtime-deps`-Ziele zeigen,
`.openclaw-runtime-deps*`-Manifeste, generierte Plugin-`node_modules`, Installations-
Staging-Verzeichnisse und paketlokale pnpm-Stores. Paketiertes Postinstall entfernt außerdem
diese globalen Symlinks, bevor die alten Ziel-Roots bereinigt werden, damit Upgrades
keine verwaisten ESM-Paketimporte hinterlassen.
Diese Pfade sind nur Legacy-Reste. Neue Installationen sollten sie nicht erstellen.
Diese Pfade sind ausschließlich alte Überreste. Neue Installationen sollten sie nicht erzeugen.

956
docs/de/plugins/google-meet.md
View File

File diff suppressed because it is too large Load Diff

328
docs/de/plugins/voice-call.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Sie möchten von OpenClaw aus einen ausgehenden Sprachanruf tätigen
- Sie konfigurieren oder entwickeln das Sprachanruf-Plugin
- Sie benötigen Echtzeit-Sprachfunktionen oder Streaming-Transkription für Telefonie
- Sie möchten einen ausgehenden Sprachanruf über OpenClaw tätigen
- Sie konfigurieren oder entwickeln das Plugin für Sprachanrufe
- Sie benötigen Echtzeit-Sprachkommunikation oder Streaming-Transkription für Telefonie
sidebarTitle: Voice call
summary: Tätigen Sie ausgehende Sprachanrufe und nehmen Sie eingehende Sprachanrufe über Twilio, Telnyx oder Plivo an, mit optionaler Echtzeit-Sprachübertragung und Streaming-Transkription
title: Sprachanruf-Plugin
x-i18n:
generated_at: "2026-05-06T06:59:30Z"
generated_at: "2026-05-06T09:04:05Z"
model: gpt-5.5
provider: openai
source_hash: cc608883e8f36cdd2075c3a8c7ab002d89d0616e119f488437bd18c995f066f9
source_hash: aba168696481ef0cc3c55ac8fd8be4382cb36889a12ed6d881fe6b29a2b0a54c
source_path: plugins/voice-call.md
workflow: 16
---
Sprachanrufe für OpenClaw über ein Plugin. Unterstützt ausgehende Benachrichtigungen,
mehrteilige Gespräche, Full-Duplex-Echtzeit-Sprache, Streaming-
Voice calls für OpenClaw über ein Plugin. Unterstützt ausgehende Benachrichtigungen,
Multi-Turn-Konversationen, Full-Duplex-Echtzeit-Sprache, Streaming-
Transkription und eingehende Anrufe mit Allowlist-Richtlinien.
**Aktuelle Provider:** `twilio` (Programmable Voice + Media Streams),
@ -24,22 +24,22 @@ Transkription und eingehende Anrufe mit Allowlist-Richtlinien.
speech), `mock` (Entwicklung/kein Netzwerk).
<Note>
Das Voice Call Plugin läuft **innerhalb des Gateway-Prozesses**. Wenn Sie ein
Remote-Gateway verwenden, installieren und konfigurieren Sie das Plugin auf dem Computer, auf dem
Das Voice Call-Plugin läuft **innerhalb des Gateway-Prozesses**. Wenn Sie ein
Remote-Gateway verwenden, installieren und konfigurieren Sie das Plugin auf dem Rechner, auf dem
das Gateway läuft, und starten Sie anschließend das Gateway neu, um es zu laden.
</Note>
## Schnellstart
<Steps>
<Step title="Plugin installieren">
<Step title="Install the plugin">
<Tabs>
<Tab title="Aus npm">
<Tab title="From npm">
```bash
openclaw plugins install @openclaw/voice-call
```
</Tab>
<Tab title="Aus einem lokalen Ordner (Entwicklung)">
<Tab title="From a local folder (dev)">
```bash
PLUGIN_SRC=./path/to/local/voice-call-plugin
openclaw plugins install "$PLUGIN_SRC"
@ -48,36 +48,36 @@ das Gateway läuft, und starten Sie anschließend das Gateway neu, um es zu lade
</Tab>
</Tabs>
Verwenden Sie das bloße Paket, um dem aktuellen offiziellen Release-Tag zu folgen. Pinnen Sie eine
exakte Version nur dann, wenn Sie eine reproduzierbare Installation benötigen.
Verwenden Sie das Paket ohne Versionsangabe, um dem aktuellen offiziellen Release-Tag zu folgen. Pinnen Sie eine
exakte Version nur, wenn Sie eine reproduzierbare Installation benötigen.
Starten Sie danach das Gateway neu, damit das Plugin geladen wird.
Starten Sie anschließend das Gateway neu, damit das Plugin geladen wird.
</Step>
<Step title="Provider und Webhook konfigurieren">
Legen Sie die Konfiguration unter `plugins.entries.voice-call.config` fest (die vollständige Form finden Sie
<Step title="Configure provider and webhook">
Legen Sie die Konfiguration unter `plugins.entries.voice-call.config` fest (die vollständige Struktur finden Sie
unten unter [Konfiguration](#configuration)). Mindestens erforderlich sind:
`provider`, Provider-Zugangsdaten, `fromNumber` und eine öffentlich
erreichbare Webhook-URL.
</Step>
<Step title="Einrichtung überprüfen">
<Step title="Verify setup">
```bash
openclaw voicecall setup
```
Die Standardausgabe ist in Chatprotokollen und Terminals lesbar. Sie prüft,
ob das Plugin aktiviert ist, Provider-Zugangsdaten vorhanden sind, der Webhook erreichbar ist und
Die Standardausgabe ist in Chatprotokollen und Terminals gut lesbar. Sie prüft,
ob das Plugin aktiviert ist, ob Provider-Zugangsdaten vorhanden sind, ob der Webhook erreichbar ist und ob
nur ein Audiomodus (`streaming` oder `realtime`) aktiv ist. Verwenden Sie
`--json` für Skripte.
</Step>
<Step title="Smoke-Test">
<Step title="Smoke test">
```bash
openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"
```
Beide sind standardmäßig Probeläufe. Fügen Sie `--yes` hinzu, um tatsächlich einen kurzen
Beides sind standardmäßig Trockenläufe. Fügen Sie `--yes` hinzu, um tatsächlich einen kurzen
ausgehenden Benachrichtigungsanruf zu platzieren:
```bash
@ -88,21 +88,21 @@ das Gateway läuft, und starten Sie anschließend das Gateway neu, um es zu lade
</Steps>
<Warning>
Für Twilio, Telnyx und Plivo muss die Einrichtung zu einer **öffentlichen Webhook-URL** führen.
Für Twilio, Telnyx und Plivo muss die Einrichtung zu einer **öffentlichen Webhook-URL** auflösen.
Wenn `publicUrl`, die Tunnel-URL, die Tailscale-URL oder der Serve-Fallback
auf Loopback oder privaten Netzwerkadressraum aufgelöst wird, schlägt die Einrichtung fehl, statt
auf loopback oder privaten Netzwerkadressraum auflöst, schlägt die Einrichtung fehl, statt
einen Provider zu starten, der keine Carrier-Webhooks empfangen kann.
</Warning>
## Konfiguration
Wenn `enabled: true` gesetzt ist, dem ausgewählten Provider aber Zugangsdaten fehlen,
protokolliert der Gateway-Start eine Warnung über eine unvollständige Einrichtung mit den fehlenden Schlüsseln und
protokolliert der Gateway-Start eine Warnung über die unvollständige Einrichtung mit den fehlenden Schlüsseln und
überspringt den Start der Runtime. Befehle, RPC-Aufrufe und Agent-Tools geben bei Verwendung weiterhin
die exakt fehlende Provider-Konfiguration zurück.
<Note>
Zugangsdaten für Voice Call akzeptieren SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` und `plugins.entries.voice-call.config.tts.providers.*.apiKey` werden über die standardmäßige SecretRef-Oberfläche aufgelöst; siehe [SecretRef-Zugangsdatenoberfläche](/de/reference/secretref-credential-surface).
Voice-call-Zugangsdaten akzeptieren SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` und `plugins.entries.voice-call.config.tts.providers.*.apiKey` werden über die standardmäßige SecretRef-Oberfläche aufgelöst; siehe [SecretRef-Zugangsdatenoberfläche](/de/reference/secretref-credential-surface).
</Note>
```json5
@ -175,28 +175,28 @@ Zugangsdaten für Voice Call akzeptieren SecretRefs. `plugins.entries.voice-call
```
<AccordionGroup>
<Accordion title="Provider-Erreichbarkeit und Sicherheitshinweise">
<Accordion title="Provider exposure and security notes">
- Twilio, Telnyx und Plivo benötigen alle eine **öffentlich erreichbare** Webhook-URL.
- `mock` ist ein lokaler Entwicklungs-Provider (keine Netzwerkaufrufe).
- Telnyx erfordert `telnyx.publicKey` (oder `TELNYX_PUBLIC_KEY`), sofern `skipSignatureVerification` nicht true ist.
- Telnyx benötigt `telnyx.publicKey` (oder `TELNYX_PUBLIC_KEY`), sofern `skipSignatureVerification` nicht true ist.
- `skipSignatureVerification` ist nur für lokale Tests vorgesehen.
- Legen Sie im kostenlosen ngrok-Tarif `publicUrl` auf die exakte ngrok-URL fest; Signaturprüfung wird immer erzwungen.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` erlaubt Twilio-Webhooks mit ungültigen Signaturen **nur**, wenn `tunnel.provider="ngrok"` ist und `serve.bind` Loopback ist (lokaler ngrok-Agent). Nur für lokale Entwicklung.
- URLs im kostenlosen ngrok-Tarif können sich ändern oder ein Interstitial-Verhalten hinzufügen; wenn `publicUrl` abweicht, schlagen Twilio-Signaturen fehl. Produktion: Bevorzugen Sie eine stabile Domain oder einen Tailscale-Funnel.
- Setzen Sie bei der kostenlosen ngrok-Stufe `publicUrl` auf die exakte ngrok-URL; Signaturprüfung wird immer erzwungen.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` erlaubt Twilio-Webhooks mit ungültigen Signaturen **nur**, wenn `tunnel.provider="ngrok"` ist und `serve.bind` loopback ist (lokaler ngrok-Agent). Nur für lokale Entwicklung.
- URLs der kostenlosen ngrok-Stufe können sich ändern oder Zwischenseiten hinzufügen; wenn `publicUrl` abweicht, schlagen Twilio-Signaturen fehl. Produktion: bevorzugen Sie eine stabile Domain oder einen Tailscale-Funnel.
</Accordion>
<Accordion title="Limits für Streaming-Verbindungen">
<Accordion title="Streaming connection caps">
- `streaming.preStartTimeoutMs` schließt Sockets, die nie einen gültigen `start`-Frame senden.
- `streaming.maxPendingConnections` begrenzt die Gesamtzahl nicht authentifizierter Pre-Start-Sockets.
- `streaming.maxPendingConnectionsPerIp` begrenzt nicht authentifizierte Pre-Start-Sockets pro Quell-IP.
- `streaming.maxConnections` begrenzt die Gesamtzahl geöffneter Media-Stream-Sockets (ausstehend + aktiv).
- `streaming.maxConnections` begrenzt die Gesamtzahl offener Media-Stream-Sockets (ausstehend + aktiv).
</Accordion>
<Accordion title="Migrationen alter Konfigurationen">
Ältere Konfigurationen mit `provider: "log"`, `twilio.from` oder alten
`streaming.*` OpenAI-Schlüsseln werden durch `openclaw doctor --fix` umgeschrieben.
Der Runtime-Fallback akzeptiert die alten Voice-Call-Schlüssel vorerst weiterhin, aber
der Umschreibpfad ist `openclaw doctor --fix` und der Kompatibilitäts-Shim ist
<Accordion title="Legacy config migrations">
Ältere Konfigurationen, die `provider: "log"`, `twilio.from` oder ältere
`streaming.*` OpenAI-Schlüssel verwenden, werden von `openclaw doctor --fix` umgeschrieben.
Der Runtime-Fallback akzeptiert die alten voice-call-Schlüssel vorerst noch, aber
der Umschreibpfad ist `openclaw doctor --fix`, und der Kompatibilitäts-Shim ist
temporär.
Automatisch migrierte Streaming-Schlüssel:
@ -212,16 +212,16 @@ Zugangsdaten für Voice Call akzeptieren SecretRefs. `plugins.entries.voice-call
## Sitzungsbereich
Standardmäßig verwendet Voice Call `sessionScope: "per-phone"`, sodass wiederholte Anrufe vom
gleichen Anrufer den Gesprächsspeicher behalten. Setzen Sie `sessionScope: "per-call"`, wenn
jeder Carrier-Anruf mit frischem Kontext beginnen soll, zum Beispiel bei Rezeption,
Buchung, IVR oder Google Meet Bridge-Abläufen, bei denen dieselbe Telefonnummer
Standardmäßig verwendet Voice Call `sessionScope: "per-phone"`, sodass wiederholte Anrufe desselben
Anrufers den Gesprächsspeicher beibehalten. Setzen Sie `sessionScope: "per-call"`, wenn
jeder Carrier-Anruf mit frischem Kontext starten soll, zum Beispiel bei Empfangs-,
Buchungs-, IVR- oder Google Meet-Bridge-Abläufen, bei denen dieselbe Telefonnummer
verschiedene Meetings darstellen kann.
## Echtzeit-Sprachgespräche
## Echtzeit-Sprachkonversationen
`realtime` wählt einen Full-Duplex-Echtzeit-Sprach-Provider für Live-Anruf-
Audio aus. Dies ist getrennt von `streaming`, das Audio nur an
Audio aus. Es ist getrennt von `streaming`, das Audio nur an
Echtzeit-Transkriptions-Provider weiterleitet.
<Warning>
@ -235,37 +235,37 @@ Aktuelles Runtime-Verhalten:
- `realtime.provider` ist optional. Wenn nicht gesetzt, verwendet Voice Call den ersten registrierten Echtzeit-Sprach-Provider.
- Gebündelte Echtzeit-Sprach-Provider: Google Gemini Live (`google`) und OpenAI (`openai`), registriert durch ihre Provider-Plugins.
- Provider-eigene Rohkonfiguration befindet sich unter `realtime.providers.<providerId>`.
- Voice Call stellt standardmäßig das gemeinsame Echtzeit-Tool `openclaw_agent_consult` bereit. Das Echtzeitmodell kann es aufrufen, wenn der Anrufer tieferes Reasoning, aktuelle Informationen oder normale OpenClaw-Tools anfordert.
- `realtime.consultPolicy` fügt optional Hinweise dazu hinzu, wann das Echtzeitmodell `openclaw_agent_consult` aufrufen soll.
- `realtime.agentContext.enabled` ist standardmäßig deaktiviert. Wenn aktiviert, injiziert Voice Call bei der Sitzungseinrichtung eine begrenzte Agent-Identität, eine System-Prompt-Überschreibung und eine ausgewählte Workspace-Datei-Kapsel in die Anweisungen des Echtzeit-Providers.
- `realtime.fastContext.enabled` ist standardmäßig deaktiviert. Wenn aktiviert, durchsucht Voice Call zuerst indizierten Speicher-/Sitzungskontext nach der Consult-Frage und gibt diese Ausschnitte innerhalb von `realtime.fastContext.timeoutMs` an das Echtzeitmodell zurück, bevor nur dann auf den vollständigen Consult-Agent zurückgefallen wird, wenn `realtime.fastContext.fallbackToConsult` true ist.
- Wenn `realtime.provider` auf einen nicht registrierten Provider zeigt oder überhaupt kein Echtzeit-Sprach-Provider registriert ist, protokolliert Voice Call eine Warnung und überspringt Echtzeitmedien, statt das gesamte Plugin fehlschlagen zu lassen.
- Consult-Sitzungsschlüssel verwenden die gespeicherte Anrufsitzung wieder, wenn verfügbar, und fallen dann auf das konfigurierte `sessionScope` zurück (`per-phone` standardmäßig oder `per-call` für isolierte Anrufe).
- Voice Call stellt standardmäßig das gemeinsame `openclaw_agent_consult`-Echtzeit-Tool bereit. Das Echtzeitmodell kann es aufrufen, wenn der Anrufer nach tiefergehender Argumentation, aktuellen Informationen oder normalen OpenClaw-Tools fragt.
- `realtime.consultPolicy` fügt optional Hinweise hinzu, wann das Echtzeitmodell `openclaw_agent_consult` aufrufen soll.
- `realtime.agentContext.enabled` ist standardmäßig deaktiviert. Wenn aktiviert, injiziert Voice Call eine begrenzte Agent-Identität, eine System-Prompt-Überschreibung und eine ausgewählte Workspace-Dateikapsel bei der Sitzungseinrichtung in die Anweisungen des Echtzeit-Providers.
- `realtime.fastContext.enabled` ist standardmäßig deaktiviert. Wenn aktiviert, durchsucht Voice Call zuerst indexierten Speicher/Sitzungskontext nach der Consult-Frage und gibt diese Ausschnitte innerhalb von `realtime.fastContext.timeoutMs` an das Echtzeitmodell zurück, bevor nur dann auf den vollständigen Consult-Agent zurückgefallen wird, wenn `realtime.fastContext.fallbackToConsult` true ist.
- Wenn `realtime.provider` auf einen nicht registrierten Provider verweist oder überhaupt kein Echtzeit-Sprach-Provider registriert ist, protokolliert Voice Call eine Warnung und überspringt Echtzeitmedien, statt das gesamte Plugin fehlschlagen zu lassen.
- Consult-Sitzungsschlüssel verwenden die gespeicherte Anrufsitzung erneut, sofern verfügbar, und fallen dann auf den konfigurierten `sessionScope` zurück (`per-phone` standardmäßig oder `per-call` für isolierte Anrufe).
### Tool-Richtlinie
`realtime.toolPolicy` steuert den Consult-Lauf:
| Richtlinie | Verhalten |
| Richtlinie | Verhalten |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | Stellt das Consult-Tool bereit und beschränkt den regulären Agent auf `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` und `memory_get`. |
| `owner` | Stellt das Consult-Tool bereit und erlaubt dem regulären Agent die normale Agent-Tool-Richtlinie. |
| `safe-read-only` | Stellt das Consult-Tool bereit und begrenzt den regulären Agent auf `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` und `memory_get`. |
| `owner` | Stellt das Consult-Tool bereit und lässt den regulären Agent die normale Agent-Tool-Richtlinie verwenden. |
| `none` | Stellt das Consult-Tool nicht bereit. Benutzerdefinierte `realtime.tools` werden weiterhin an den Echtzeit-Provider durchgereicht. |
`realtime.consultPolicy` steuert nur die Anweisungen des Echtzeitmodells:
`realtime.consultPolicy` steuert nur die Anweisungen für das Echtzeitmodell:
| Richtlinie | Anleitung |
| Richtlinie | Anleitung |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `auto` | Behalten Sie den Standard-Prompt bei und lassen Sie den Provider entscheiden, wann das Consult-Tool aufgerufen wird. |
| `substantive` | Beantwortet einfache gesprächsverbindende Passagen direkt und konsultiert vor Fakten, Speicher, Tools oder Kontext. |
| `always` | Konsultiert vor jeder substantiellen Antwort. |
| `substantive` | Beantworten Sie einfache konversationelle Überleitungen direkt und konsultieren Sie vor Fakten, Speicher, Tools oder Kontext. |
| `always` | Konsultieren Sie vor jeder substanziellen Antwort. |
### Agent-Sprachkontext
Aktivieren Sie `realtime.agentContext`, wenn die Sprachbrücke wie der
konfigurierte OpenClaw-Agent klingen soll, ohne bei gewöhnlichen Turns einen vollständigen Agent-Consult-Roundtrip
zu bezahlen. Die Kontextkapsel wird einmal hinzugefügt, wenn die Echtzeitsitzung
erstellt wird, sodass sie keine Latenz pro Turn hinzufügt. Aufrufe von
konfigurierte OpenClaw-Agent klingen soll, ohne bei gewöhnlichen Gesprächsrunden einen vollständigen Agent-Consult-Roundtrip zu bezahlen.
Die Kontextkapsel wird einmal hinzugefügt, wenn die Echtzeitsitzung
erstellt wird, sodass keine Latenz pro Gesprächsrunde entsteht. Aufrufe von
`openclaw_agent_consult` führen weiterhin den vollständigen OpenClaw-Agent aus und sollten
für Tool-Arbeit, aktuelle Informationen, Speicherabfragen oder Workspace-Zustand verwendet werden.
@ -297,7 +297,7 @@ für Tool-Arbeit, aktuelle Informationen, Speicherabfragen oder Workspace-Zustan
}
```
### Echtzeit-Provider-Beispiele
### Beispiele für Realtime-Provider
<Tabs>
<Tab title="Google Gemini Live">
@ -306,7 +306,7 @@ für Tool-Arbeit, aktuelle Informationen, Speicherabfragen oder Workspace-Zustan
`gemini-2.5-flash-native-audio-preview-12-2025`; Stimme `Kore`.
`sessionResumption` und `contextWindowCompression` sind standardmäßig für längere,
wiederverbindbare Anrufe aktiviert. Verwenden Sie `silenceDurationMs`, `startSensitivity` und
`endSensitivity`, um schnelleres Turn-Taking bei Telefonie-Audio abzustimmen.
`endSensitivity`, um schnellere Sprecherwechsel bei Telefonie-Audio abzustimmen.
```json5
{
@ -365,23 +365,22 @@ für Tool-Arbeit, aktuelle Informationen, Speicherabfragen oder Workspace-Zustan
</Tab>
</Tabs>
Weitere Provider-spezifische Echtzeit-Sprachoptionen finden Sie unter
[Google-Provider](/de/providers/google) und
Weitere Provider-spezifische Realtime-Sprachoptionen finden Sie unter [Google-Provider](/de/providers/google) und
[OpenAI-Provider](/de/providers/openai).
## Streaming-Transkription
`streaming` wählt einen Echtzeit-Transkriptions-Provider für Live-Anrufaudio aus.
`streaming` wählt einen Realtime-Transkriptions-Provider für Live-Anruf-Audio aus.
Aktuelles Laufzeitverhalten:
- `streaming.provider` ist optional. Wenn nicht gesetzt, verwendet Voice Call den ersten registrierten Echtzeit-Transkriptions-Provider.
- Gebündelte Echtzeit-Transkriptions-Provider: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) und xAI (`xai`), registriert durch ihre Provider-Plugins.
- `streaming.provider` ist optional. Wenn nicht festgelegt, verwendet Voice Call den ersten registrierten Realtime-Transkriptions-Provider.
- Gebündelte Realtime-Transkriptions-Provider: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) und xAI (`xai`), registriert durch ihre Provider-Plugins.
- Provider-eigene Rohkonfiguration befindet sich unter `streaming.providers.<providerId>`.
- Nachdem Twilio eine akzeptierte Stream-`start`-Nachricht gesendet hat, registriert Voice Call den Stream sofort, stellt eingehende Medien über den Transkriptions-Provider in die Warteschlange, während der Provider die Verbindung herstellt, und startet die anfängliche Begrüßung erst, wenn die Echtzeit-Transkription bereit ist.
- Wenn `streaming.provider` auf einen nicht registrierten Provider verweist oder keiner registriert ist, protokolliert Voice Call eine Warnung und überspringt Media-Streaming, statt das gesamte Plugin fehlschlagen zu lassen.
- Nachdem Twilio eine akzeptierte Stream-`start`-Nachricht sendet, registriert Voice Call den Stream sofort, reiht eingehende Medien über den Transkriptions-Provider ein, während der Provider die Verbindung herstellt, und startet die erste Begrüßung erst, nachdem die Realtime-Transkription bereit ist.
- Wenn `streaming.provider` auf einen nicht registrierten Provider verweist oder keiner registriert ist, protokolliert Voice Call eine Warnung und überspringt Media-Streaming, anstatt das gesamte Plugin fehlschlagen zu lassen.
### Streaming-Provider-Beispiele
### Beispiele für Streaming-Provider
<Tabs>
<Tab title="OpenAI">
@ -451,8 +450,8 @@ Aktuelles Laufzeitverhalten:
## TTS für Anrufe
Voice Call verwendet die zentrale `messages.tts`-Konfiguration für Streaming-
Sprache bei Anrufen. Sie können sie in der Plugin-Konfiguration mit
Voice Call verwendet die zentrale `messages.tts`-Konfiguration für gestreamte
Sprachausgabe bei Anrufen. Sie können sie in der Plugin-Konfiguration mit
**derselben Struktur** überschreiben — sie wird per Deep-Merge mit `messages.tts` zusammengeführt.
```json5
@ -470,17 +469,17 @@ Sprache bei Anrufen. Sie können sie in der Plugin-Konfiguration mit
```
<Warning>
**Microsoft-Sprachausgabe wird für Sprachanrufe ignoriert.** Telefonie-Audio benötigt PCM;
**Microsoft Speech wird für Sprachanrufe ignoriert.** Telefonie-Audio benötigt PCM;
der aktuelle Microsoft-Transport stellt keine Telefonie-PCM-Ausgabe bereit.
</Warning>
Verhaltenshinweise:
Hinweise zum Verhalten:
- Legacy-`tts.<provider>`-Schlüssel innerhalb der Plugin-Konfiguration (`openai`, `elevenlabs`, `microsoft`, `edge`) werden durch `openclaw doctor --fix` repariert; festgeschriebene Konfiguration sollte `tts.providers.<provider>` verwenden.
- Legacy-`tts.<provider>`-Schlüssel innerhalb der Plugin-Konfiguration (`openai`, `elevenlabs`, `microsoft`, `edge`) werden durch `openclaw doctor --fix` repariert; committete Konfiguration sollte `tts.providers.<provider>` verwenden.
- Zentrales TTS wird verwendet, wenn Twilio-Media-Streaming aktiviert ist; andernfalls fallen Anrufe auf Provider-native Stimmen zurück.
- Wenn bereits ein Twilio-Mediastream aktiv ist, fällt Voice Call nicht auf TwiML `<Say>` zurück. Wenn Telefonie-TTS in diesem Zustand nicht verfügbar ist, schlägt die Wiedergabeanforderung fehl, statt zwei Wiedergabepfade zu mischen.
- Wenn Telefonie-TTS auf einen sekundären Provider zurückfällt, protokolliert Voice Call zur Fehlerbehebung eine Warnung mit der Provider-Kette (`from`, `to`, `attempts`).
- Wenn Twilio-Barge-in oder Stream-Abbau die ausstehende TTS-Warteschlange leert, werden eingereihte Wiedergabeanforderungen abgeschlossen, statt Anrufer beim Warten auf den Abschluss der Wiedergabe hängen zu lassen.
- Wenn bereits ein Twilio-Media-Stream aktiv ist, fällt Voice Call nicht auf TwiML `<Say>` zurück. Wenn Telefonie-TTS in diesem Zustand nicht verfügbar ist, schlägt die Wiedergabeanforderung fehl, anstatt zwei Wiedergabepfade zu mischen.
- Wenn Telefonie-TTS auf einen sekundären Provider zurückfällt, protokolliert Voice Call zur Fehlersuche eine Warnung mit der Provider-Kette (`from`, `to`, `attempts`).
- Wenn Twilio-Barge-in oder Stream-Abbau die ausstehende TTS-Warteschlange leert, werden eingereihte Wiedergabeanforderungen abgeschlossen, anstatt Anrufer hängen zu lassen, die auf den Abschluss der Wiedergabe warten.
### TTS-Beispiele
@ -549,7 +548,7 @@ Verhaltenshinweise:
## Eingehende Anrufe
Die Standardrichtlinie für eingehende Anrufe ist `disabled`. Um eingehende Anrufe zu aktivieren, setzen Sie:
Die Eingangsrichtlinie ist standardmäßig `disabled`. Um eingehende Anrufe zu aktivieren, setzen Sie:
```json5
{
@ -560,29 +559,29 @@ Die Standardrichtlinie für eingehende Anrufe ist `disabled`. Um eingehende Anru
```
<Warning>
`inboundPolicy: "allowlist"` ist eine Anrufer-ID-Prüfung mit geringer Vertrauenssicherheit. Das
Plugin normalisiert den vom Provider gelieferten `From`-Wert und vergleicht ihn mit
`allowFrom`. Webhook-Verifizierung authentifiziert die Provider-Zustellung und
Payload-Integrität, beweist aber **nicht** die Inhaberschaft der PSTN-/VoIP-Anrufernummer.
`inboundPolicy: "allowlist"` ist eine Anrufer-ID-Prüfung mit geringer Vertrauenswürdigkeit. Das
Plugin normalisiert den vom Provider bereitgestellten `From`-Wert und vergleicht ihn mit
`allowFrom`. Die Webhook-Verifizierung authentifiziert die Provider-Zustellung und
Payload-Integrität, beweist jedoch **nicht** die Inhaberschaft der PSTN-/VoIP-Anrufernummer.
Behandeln Sie `allowFrom` als Anrufer-ID-Filterung, nicht als starke Anruferidentität.
</Warning>
Automatische Antworten verwenden das Agent-System. Stimmen Sie sie mit `responseModel`,
`responseSystemPrompt` und `responseTimeoutMs` ab.
### Rufnummernspezifisches Routing
### Routing pro Nummer
Verwenden Sie `numbers`, wenn ein Voice Call-Plugin Anrufe für mehrere Telefonnummern
empfängt und jede Nummer sich wie eine andere Leitung verhalten soll. Beispielsweise kann eine
Verwenden Sie `numbers`, wenn ein Voice-Call-Plugin Anrufe für mehrere Telefonnummern
empfängt und sich jede Nummer wie eine andere Leitung verhalten soll. Beispielsweise kann eine
Nummer einen lockeren persönlichen Assistenten verwenden, während eine andere eine geschäftliche
Persona, einen anderen Antwort-Agent und eine andere TTS-Stimme verwendet.
Routen werden aus der vom Provider gelieferten gewählten `To`-Nummer ausgewählt. Schlüssel müssen
Routen werden anhand der vom Provider bereitgestellten gewählten `To`-Nummer ausgewählt. Schlüssel müssen
E.164-Nummern sein. Wenn ein Anruf eingeht, löst Voice Call die passende Route einmal auf,
speichert die passende Route im Anrufdatensatz und verwendet diese effektive Konfiguration
für die Begrüßung, den klassischen automatischen Antwortpfad, den Echtzeit-Consult-Pfad und die TTS-
Wiedergabe wieder. Wenn keine Route passt, wird die globale Voice Call-Konfiguration verwendet.
Ausgehende Anrufe verwenden `numbers` nicht; übergeben Sie beim Einleiten des Anrufs das ausgehende Ziel, die Nachricht und
speichert die zugeordnete Route im Anrufdatensatz und verwendet diese effektive Konfiguration
für die Begrüßung, den klassischen Auto-Response-Pfad, den Realtime-Consult-Pfad und die TTS-
Wiedergabe erneut. Wenn keine Route passt, wird die globale Voice-Call-Konfiguration verwendet.
Ausgehende Anrufe verwenden `numbers` nicht; übergeben Sie beim Starten des Anrufs das ausgehende Ziel, die Nachricht und
die Sitzung explizit.
Routenüberschreibungen unterstützen derzeit:
@ -594,8 +593,8 @@ Routenüberschreibungen unterstützen derzeit:
- `responseSystemPrompt`
- `responseTimeoutMs`
Der Routenwert `tts` wird per Deep-Merge über die globale Voice Call-`tts`-Konfiguration gelegt, sodass
Sie in der Regel nur die Provider-Stimme überschreiben können:
Der `tts`-Routenwert wird per Deep-Merge über die globale Voice-Call-`tts`-Konfiguration zusammengeführt, sodass
Sie in der Regel nur die Provider-Stimme überschreiben müssen:
```json5
{
@ -633,35 +632,35 @@ den System-Prompt an:
Voice Call extrahiert Sprachtext defensiv:
- Ignoriert Payloads, die als Reasoning-/Fehlerinhalte markiert sind.
- Parst direktes JSON, eingezäuntes JSON oder inline gesetzte `"spoken"`-Schlüssel.
- Fällt auf Klartext zurück und entfernt wahrscheinliche Planungs-/Meta-Einleitungsabsätze.
- Parst direktes JSON, eingezäuntes JSON oder Inline-`"spoken"`-Schlüssel.
- Fällt auf Klartext zurück und entfernt wahrscheinliche einleitende Planungs-/Meta-Absätze.
Dadurch bleibt die gesprochene Wiedergabe auf anruferseitigen Text fokussiert und verhindert,
dass Planungstext in Audio gelangt.
Dadurch bleibt die gesprochene Wiedergabe auf anruferorientierten Text fokussiert und
es wird vermieden, dass Planungstext in Audio gelangt.
### Startverhalten von Konversationen
### Verhalten beim Gesprächsstart
Bei ausgehenden `conversation`-Anrufen ist die Behandlung der ersten Nachricht an den Live-
Wiedergabestatus gebunden:
Wiedergabestatus gekoppelt:
- Barge-in-Warteschlangenleerung und automatische Antwort werden nur unterdrückt, während die anfängliche Begrüßung aktiv gesprochen wird.
- Wenn die anfängliche Wiedergabe fehlschlägt, kehrt der Anruf zu `listening` zurück und die anfängliche Nachricht bleibt für einen erneuten Versuch in der Warteschlange.
- Die anfängliche Wiedergabe für Twilio-Streaming startet beim Stream-Verbindungsaufbau ohne zusätzliche Verzögerung.
- Barge-in bricht aktive Wiedergabe ab und leert eingereihte, aber noch nicht wiedergegebene Twilio-TTS-Einträge. Geleerte Einträge werden als übersprungen aufgelöst, sodass nachgelagerte Antwortlogik fortfahren kann, ohne auf Audio zu warten, das nie abgespielt wird.
- Echtzeit-Sprachkonversationen verwenden den eigenen Eröffnungs-Turn des Echtzeit-Streams. Voice Call sendet für diese anfängliche Nachricht **kein** Legacy-`<Say>`-TwiML-Update, sodass ausgehende `<Connect><Stream>`-Sitzungen verbunden bleiben.
- Das Leeren der Barge-in-Warteschlange und die automatische Antwort werden nur unterdrückt, während die erste Begrüßung aktiv gesprochen wird.
- Wenn die erste Wiedergabe fehlschlägt, kehrt der Anruf zu `listening` zurück und die erste Nachricht bleibt für einen erneuten Versuch eingereiht.
- Die erste Wiedergabe für Twilio-Streaming startet beim Verbinden des Streams ohne zusätzliche Verzögerung.
- Barge-in bricht die aktive Wiedergabe ab und leert eingereihte, aber noch nicht abgespielte Twilio-TTS-Einträge. Geleerte Einträge werden als übersprungen aufgelöst, sodass nachfolgende Antwortlogik fortgesetzt werden kann, ohne auf Audio zu warten, das nie abgespielt wird.
- Realtime-Sprachkonversationen verwenden den eigenen Eröffnungszug des Realtime-Streams. Voice Call sendet für diese erste Nachricht **kein** Legacy-`<Say>`-TwiML-Update, sodass ausgehende `<Connect><Stream>`-Sitzungen verbunden bleiben.
### Karenzzeit bei Twilio-Stream-Trennung
Wenn ein Twilio-Mediastream getrennt wird, wartet Voice Call **2000 ms**, bevor
Wenn ein Twilio-Media-Stream getrennt wird, wartet Voice Call **2000 ms**, bevor
der Anruf automatisch beendet wird:
- Wenn sich der Stream innerhalb dieses Zeitfensters erneut verbindet, wird das automatische Beenden abgebrochen.
- Wenn sich nach der Karenzzeit kein Stream erneut registriert, wird der Anruf beendet, um hängengebliebene aktive Anrufe zu verhindern.
- Wenn der Stream innerhalb dieses Fensters erneut verbunden wird, wird das automatische Beenden abgebrochen.
- Wenn sich nach der Karenzzeit kein Stream erneut registriert, wird der Anruf beendet, um hängende aktive Anrufe zu verhindern.
## Reaper für veraltete Anrufe
Verwenden Sie `staleCallReaperSeconds`, um Anrufe zu beenden, die nie einen abschließenden
Webhook erhalten (z. B. Notify-Mode-Anrufe, die nie abgeschlossen werden). Der Standardwert
Verwenden Sie `staleCallReaperSeconds`, um Anrufe zu beenden, die nie einen terminalen
Webhook erhalten (zum Beispiel Notify-Mode-Anrufe, die nie abgeschlossen werden). Der Standardwert
ist `0` (deaktiviert).
Empfohlene Bereiche:
@ -686,15 +685,15 @@ Empfohlene Bereiche:
## Webhook-Sicherheit
Wenn sich ein Proxy oder Tunnel vor dem Gateway befindet, rekonstruiert das Plugin
Wenn ein Proxy oder Tunnel vor dem Gateway sitzt, rekonstruiert das Plugin
die öffentliche URL für die Signaturprüfung. Diese Optionen steuern, welchen
weitergeleiteten Headern vertraut wird:
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
Zulässige Hosts aus Weiterleitungs-Headern.
Zulassungsliste für Hosts aus Weiterleitungs-Headern.
</ParamField>
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
Weitergeleiteten Headern ohne Allowlist vertrauen.
Weitergeleiteten Headern ohne Zulassungsliste vertrauen.
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
Weitergeleiteten Headern nur vertrauen, wenn die Remote-IP der Anfrage mit der Liste übereinstimmt.
@ -702,12 +701,12 @@ weitergeleiteten Headern vertraut wird:
Zusätzliche Schutzmaßnahmen:
- Webhook-**Replay-Schutz** ist für Twilio und Plivo aktiviert. Erneut gesendete gültige Webhook-Anfragen werden bestätigt, aber für Seiteneffekte übersprungen.
- Twilio-Konversationsdurchläufe enthalten ein Token pro Durchlauf in `<Gather>`-Callbacks, sodass veraltete oder erneut gesendete Sprach-Callbacks keinen neueren ausstehenden Transkriptdurchlauf erfüllen können.
- Nicht authentifizierte Webhook-Anfragen werden vor dem Lesen des Bodys abgelehnt, wenn die vom Provider benötigten Signatur-Header fehlen.
- Der Voice-Call-Webhook verwendet das gemeinsame Pre-Auth-Body-Profil (64 KB / 5 Sekunden) plus eine pro-IP-Begrenzung laufender Anfragen vor der Signaturprüfung.
- Webhook-**Replay-Schutz** ist für Twilio und Plivo aktiviert. Wiederholte gültige Webhook-Anfragen werden bestätigt, aber für Nebeneffekte übersprungen.
- Twilio-Konversationsdurchläufe enthalten ein durchlaufspezifisches Token in `<Gather>`-Callbacks, sodass veraltete/wiederholte Sprach-Callbacks keinen neueren ausstehenden Transkriptdurchlauf erfüllen können.
- Nicht authentifizierte Webhook-Anfragen werden vor dem Lesen des Bodys abgelehnt, wenn die erforderlichen Signatur-Header des Providers fehlen.
- Der Voice-Call-Webhook verwendet das gemeinsame Pre-Auth-Body-Profil (64 KB / 5 Sekunden) plus eine In-Flight-Begrenzung pro IP vor der Signaturprüfung.
Beispiel mit stabilem öffentlichen Host:
Beispiel mit einem stabilen öffentlichen Host:
```json5
{
@ -741,15 +740,15 @@ openclaw voicecall latency # summarize turn latency from lo
openclaw voicecall expose --mode funnel
```
Wenn das Gateway bereits ausgeführt wird, delegieren operative `voicecall`-Befehle
an die vom Gateway verwaltete Voice-Call-Laufzeit, damit die CLI keinen zweiten
Webhook-Server bindet. Wenn kein Gateway erreichbar ist, fallen die Befehle auf eine
eigenständige CLI-Laufzeit zurück.
Wenn das Gateway bereits läuft, delegieren operative `voicecall`-Befehle
an die Gateway-eigene Voice-Call-Laufzeit, damit die CLI keinen zweiten
Webhook-Server bindet. Wenn kein Gateway erreichbar ist, fallen die Befehle auf
eine eigenständige CLI-Laufzeit zurück.
`latency` liest `calls.jsonl` aus dem Standardspeicherpfad für Voice Call.
`latency` liest `calls.jsonl` aus dem standardmäßigen Voice-Call-Speicherpfad.
Verwenden Sie `--file <path>`, um auf ein anderes Protokoll zu verweisen, und `--last <n>`, um die
Analyse auf die letzten N Datensätze zu begrenzen (Standard 200). Die Ausgabe enthält p50/p90/p99
für Durchlauflatenz und Listen-Wait-Zeiten.
Analyse auf die letzten N Datensätze zu begrenzen (Standard: 200). Die Ausgabe enthält p50/p90/p99
für Durchlauflatenz und Wartezeiten beim Zuhören.
## Agent-Tool
@ -764,7 +763,7 @@ Tool-Name: `voice_call`.
| `end_call` | `callId` |
| `get_status` | `callId` |
Dieses Repo liefert eine passende Skill-Dokumentation unter `skills/voice-call/SKILL.md`.
Dieses Repository liefert ein passendes Skill-Dokument unter `skills/voice-call/SKILL.md`.
## Gateway-RPC
@ -778,12 +777,12 @@ Dieses Repo liefert eine passende Skill-Dokumentation unter `skills/voice-call/S
| `voicecall.status` | `callId` |
`dtmfSequence` ist nur mit `mode: "conversation"` gültig. Aufrufe im Notify-Modus
sollten `voicecall.dtmf` verwenden, nachdem der Anruf existiert, wenn sie Ziffern
nach dem Verbindungsaufbau benötigen.
sollten `voicecall.dtmf` verwenden, nachdem der Aufruf existiert, wenn sie Ziffern nach dem Verbindungsaufbau
benötigen.
## Problembehandlung
## Fehlerbehebung
### Einrichtung schlägt bei der Webhook-Erreichbarkeit fehl
### Einrichtung schlägt bei Webhook-Erreichbarkeit fehl
Führen Sie die Einrichtung aus derselben Umgebung aus, in der auch das Gateway läuft:
@ -793,15 +792,15 @@ openclaw voicecall setup --json
```
Für `twilio`, `telnyx` und `plivo` muss `webhook-exposure` grün sein. Eine
konfigurierte `publicUrl` schlägt weiterhin fehl, wenn sie auf lokalen oder privaten Netzwerkraum
zeigt, weil der Carrier diese Adressen nicht zurückrufen kann. Verwenden Sie nicht
konfigurierte `publicUrl` schlägt trotzdem fehl, wenn sie auf lokalen oder privaten Netzwerkraum
zeigt, weil der Netzbetreiber diese Adressen nicht zurückrufen kann. Verwenden Sie nicht
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
`192.168.x`, `169.254.x`, `fc00::/7` oder `fd00::/8` als `publicUrl`.
Ausgehende Twilio-Aufrufe im Notify-Modus senden ihr anfängliches `<Say>`-TwiML direkt in
der Create-Call-Anfrage, sodass die erste gesprochene Nachricht nicht davon abhängt, dass Twilio
Webhook-TwiML abruft. Ein öffentlicher Webhook ist weiterhin für Status-Callbacks,
Konversationsanrufe, Pre-Connect-DTMF, Echtzeitstreams und Anrufsteuerung nach dem Verbindungsaufbau
Konversationsaufrufe, Pre-Connect-DTMF, Echtzeit-Streams und Call-Control nach dem Verbindungsaufbau
erforderlich.
Verwenden Sie einen öffentlichen Freigabepfad:
@ -835,19 +834,19 @@ openclaw voicecall smoke
### Provider-Anmeldedaten schlagen fehl
Prüfen Sie den ausgewählten Provider und die erforderlichen Anmeldedatenfelder:
Prüfen Sie den ausgewählten Provider und die erforderlichen Felder für Anmeldedaten:
- Twilio: `twilio.accountSid`, `twilio.authToken` und `fromNumber` oder
- Twilio: `twilio.accountSid`, `twilio.authToken` und `fromNumber`, oder
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` und `TWILIO_FROM_NUMBER`.
- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` und
`fromNumber`.
- Plivo: `plivo.authId`, `plivo.authToken` und `fromNumber`.
Anmeldedaten müssen auf dem Gateway-Host vorhanden sein. Das Bearbeiten eines lokalen Shell-Profils wirkt sich
nicht auf ein bereits laufendes Gateway aus, bis es neu gestartet wird oder seine
erst auf ein bereits laufendes Gateway aus, wenn es neu startet oder seine
Umgebung neu lädt.
### Anrufe starten, aber Provider-Webhooks kommen nicht an
### Aufrufe starten, aber Provider-Webhooks kommen nicht an
Bestätigen Sie, dass die Provider-Konsole auf die exakte öffentliche Webhook-URL zeigt:
@ -855,7 +854,7 @@ Bestätigen Sie, dass die Provider-Konsole auf die exakte öffentliche Webhook-U
https://voice.example.com/voice/webhook
```
Prüfen Sie dann den Laufzeitstatus:
Prüfen Sie dann den Laufzeitzustand:
```bash
openclaw voicecall status --call-id <id>
@ -868,10 +867,10 @@ Häufige Ursachen:
- `publicUrl` zeigt auf einen anderen Pfad als `serve.path`.
- Die Tunnel-URL hat sich geändert, nachdem das Gateway gestartet wurde.
- Ein Proxy leitet die Anfrage weiter, entfernt oder überschreibt aber Host-/Proto-Header.
- Firewall oder DNS routen den öffentlichen Hostnamen an einen anderen Ort als das Gateway.
- Das Gateway wurde ohne aktiviertes Voice-Call-Plugin neu gestartet.
- Firewall oder DNS leiten den öffentlichen Hostnamen an einen anderen Ort als das Gateway.
- Das Gateway wurde neu gestartet, ohne dass das Voice-Call-Plugin aktiviert war.
Wenn ein Reverse Proxy oder Tunnel vor dem Gateway steht, setzen Sie
Wenn ein Reverse Proxy oder Tunnel vor dem Gateway sitzt, setzen Sie
`webhookSecurity.allowedHosts` auf den öffentlichen Hostnamen oder verwenden Sie
`webhookSecurity.trustedProxyIPs` für eine bekannte Proxy-Adresse. Verwenden Sie
`webhookSecurity.trustForwardingHeaders` nur, wenn die Proxy-Grenze unter
@ -879,68 +878,69 @@ Ihrer Kontrolle steht.
### Signaturprüfung schlägt fehl
Provider-Signaturen werden gegen die öffentliche URL geprüft, die OpenClaw aus
der eingehenden Anfrage rekonstruiert. Wenn Signaturen fehlschlagen:
Provider-Signaturen werden gegen die öffentliche URL geprüft, die OpenClaw
aus der eingehenden Anfrage rekonstruiert. Wenn Signaturen fehlschlagen:
- Bestätigen Sie, dass die Provider-Webhook-URL exakt mit `publicUrl` übereinstimmt, einschließlich
Schema, Host und Pfad.
- Aktualisieren Sie bei ngrok-URLs im Free-Tier `publicUrl`, wenn sich der Tunnel-Hostname ändert.
- Aktualisieren Sie bei kostenlosen ngrok-URLs `publicUrl`, wenn sich der Tunnel-Hostname ändert.
- Stellen Sie sicher, dass der Proxy die ursprünglichen Host- und Proto-Header beibehält, oder konfigurieren Sie
`webhookSecurity.allowedHosts`.
- Aktivieren Sie `skipSignatureVerification` nicht außerhalb lokaler Tests.
### Google-Meet-Twilio-Beitritte schlagen fehl
### Google Meet-Twilio-Beitritte schlagen fehl
Google Meet verwendet dieses Plugin für Twilio-Einwahlbeitritte. Überprüfen Sie zuerst Voice Call:
Google Meet verwendet dieses Plugin für Twilio-Einwahlbeitritte. Prüfen Sie zuerst Voice Call:
```bash
openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"
```
Überprüfen Sie dann den Google-Meet-Transport ausdrücklich:
Prüfen Sie dann den Google Meet-Transport ausdrücklich:
```bash
openclaw googlemeet setup --transport twilio
```
Wenn Voice Call grün ist, der Meet-Teilnehmer aber nie beitritt, prüfen Sie die Meet-
Einwahlnummer, PIN und `--dtmf-sequence`. Der Telefonanruf kann fehlerfrei sein, während
das Meeting eine falsche DTMF-Sequenz ablehnt oder ignoriert.
Einwahlnummer, die PIN und `--dtmf-sequence`. Der Telefonanruf kann fehlerfrei sein, während
die Besprechung eine falsche DTMF-Sequenz ablehnt oder ignoriert.
Google Meet übergibt die Meet-DTMF-Sequenz und den Einführungstext an `voicecall.start`.
Bei Twilio-Anrufen stellt Voice Call zuerst das DTMF-TwiML bereit, leitet zurück an den
Webhook und öffnet dann den Echtzeit-Medienstream, sodass die gespeicherte Einführung erzeugt wird,
nachdem der Telefonteilnehmer dem Meeting beigetreten ist.
Google Meet startet den Twilio-Telefonabschnitt über `voicecall.start` mit einer
Pre-Connect-DTMF-Sequenz. Aus der PIN abgeleitete Sequenzen enthalten das
`voiceCall.dtmfDelayMs` des Google Meet-Plugins als führende Twilio-Warteziffern. Der Standardwert beträgt 12 Sekunden,
weil Meet-Einwahlansagen verspätet eintreffen können. Voice Call leitet dann zurück zur
Echtzeitverarbeitung, bevor die Begrüßung angefordert wird.
Verwenden Sie `openclaw logs --follow` für die Live-Phasenablaufverfolgung. Ein fehlerfreier Twilio-Meet-
Verwenden Sie `openclaw logs --follow` für die Live-Phasenverfolgung. Ein fehlerfreier Twilio-Meet-
Beitritt protokolliert diese Reihenfolge:
- Google Meet delegiert den Twilio-Beitritt an Voice Call.
- Voice Call speichert Pre-Connect-DTMF-TwiML.
- Das anfängliche Twilio-TwiML wird verbraucht und vor der Echtzeitverarbeitung bereitgestellt.
- Voice Call stellt Echtzeit-TwiML für den Twilio-Anruf bereit.
- Die Echtzeit-Bridge startet mit der anfänglichen Begrüßung in der Warteschlange.
- Twilio-Anfangs-TwiML wird verbraucht und vor der Echtzeitverarbeitung bereitgestellt.
- Voice Call stellt Echtzeit-TwiML für den Twilio-Aufruf bereit.
- Google Meet fordert die Begrüßung mit `voicecall.speak` nach der Post-DTMF-Verzögerung an.
`openclaw voicecall tail` zeigt weiterhin persistierte Anrufdatensätze; es ist nützlich für
Anrufstatus und Transkripte, aber nicht jeder Webhook-/Echtzeitübergang erscheint
dort.
### Echtzeitanruf hat keine Sprache
### Echtzeitaufruf hat keine Sprache
Bestätigen Sie, dass nur ein Audiomodus aktiviert ist. `realtime.enabled` und
`streaming.enabled` können nicht beide `true` sein.
`streaming.enabled` können nicht beide true sein.
Prüfen Sie bei Echtzeit-Twilio-Anrufen außerdem:
Prüfen Sie für Echtzeit-Twilio-Aufrufe außerdem:
- Ein Echtzeit-Provider-Plugin ist geladen und registriert.
- `realtime.provider` ist nicht gesetzt oder benennt einen registrierten Provider.
- Der Provider-API-Schlüssel ist für den Gateway-Prozess verfügbar.
- `openclaw logs --follow` zeigt, dass Echtzeit-TwiML bereitgestellt wurde, die Echtzeit-Bridge
gestartet ist und die anfängliche Begrüßung in die Warteschlange gestellt wurde.
- `openclaw logs --follow` zeigt, dass Echtzeit-TwiML bereitgestellt, die Echtzeit-Bridge
gestartet und die anfängliche Begrüßung in die Warteschlange gestellt wurde.
## Verwandte Themen
## Verwandt
- [Sprechmodus](/de/nodes/talk)
- [Text-zu-Sprache](/de/tools/tts)
- [Voice Wake](/de/nodes/voicewake)
- [Text-to-speech](/de/tools/tts)
- [Sprachaktivierung](/de/nodes/voicewake)

465
docs/de/providers/openai.md
View File

@ -2,102 +2,83 @@
read_when:
- Sie möchten OpenAI-Modelle in OpenClaw verwenden
- Sie möchten die Codex-Abonnementauthentifizierung statt API-Schlüsseln verwenden
- Sie benötigen ein strengeres Ausführungsverhalten für GPT-5-Agenten
- Sie benötigen ein strikteres Ausführungsverhalten für GPT-5-Agenten
summary: OpenAI über API-Schlüssel oder ein Codex-Abonnement in OpenClaw verwenden
title: OpenAI
x-i18n:
generated_at: "2026-05-03T06:43:36Z"
generated_at: "2026-05-06T09:04:23Z"
model: gpt-5.5
provider: openai
source_hash: cdffcdf53d9b17a19450c2ce47103db116e54a71a8dd432d981f5ece81cc38b3
source_hash: b5606cafb8dfec888b922874202aa0fdcad8cbd4fec1a1e15a9074ad14bc5486
source_path: providers/openai.md
workflow: 16
---
OpenAI stellt Entwickler-APIs für GPT-Modelle bereit, und Codex ist auch als
Coding-Agent in ChatGPT-Tarifen über OpenAIs Codex-Clients verfügbar. OpenClaw hält diese
Oberflächen getrennt, damit die Konfiguration vorhersehbar bleibt.
OpenAI stellt Entwickler-APIs für GPT-Modelle bereit, und Codex ist über OpenAIs Codex-Clients auch als Coding-Agent für ChatGPT-Tarife verfügbar. OpenClaw hält diese Oberflächen getrennt, damit die Konfiguration vorhersehbar bleibt.
OpenClaw unterstützt drei Routen der OpenAI-Familie. Die meisten ChatGPT-/Codex-Abonnenten,
die Codex-Verhalten wünschen, sollten die native Codex-App-Server-Runtime verwenden. Das
Modellpräfix wählt den Provider-/Modellnamen aus; eine separate Runtime-Einstellung wählt aus,
wer den eingebetteten Agent-Loop ausführt:
OpenClaw unterstützt drei Routen aus der OpenAI-Familie. Die meisten ChatGPT/Codex-Abonnenten, die Codex-Verhalten wünschen, sollten die native Codex-App-Server-Laufzeit verwenden. Das Modellpräfix wählt den Provider-/Modellnamen aus; eine separate Laufzeiteinstellung legt fest, wer den eingebetteten Agent-Loop ausführt:
- **API-Schlüssel** - direkter OpenAI-Platform-Zugriff mit nutzungsbasierter Abrechnung (`openai/*`-Modelle)
- **Codex-Abonnement mit nativer Codex-Runtime** - ChatGPT-/Codex-Anmeldung plus Ausführung über den Codex-App-Server (`openai/*`-Modelle plus `agents.defaults.agentRuntime.id: "codex"`)
- **Codex-Abonnement über PI** - ChatGPT-/Codex-Anmeldung mit dem normalen OpenClaw-PI-Runner (`openai-codex/*`-Modelle)
- **API-Schlüssel** - direkter OpenAI Platform-Zugriff mit nutzungsbasierter Abrechnung (`openai/*`-Modelle)
- **Codex-Abonnement mit nativer Codex-Laufzeit** - ChatGPT/Codex-Anmeldung plus Codex-App-Server-Ausführung (`openai/*`-Modelle plus `agents.defaults.agentRuntime.id: "codex"`)
- **Codex-Abonnement über PI** - ChatGPT/Codex-Anmeldung mit dem normalen OpenClaw-PI-Runner (`openai-codex/*`-Modelle)
OpenAI unterstützt ausdrücklich die Nutzung von Abonnement-OAuth in externen Tools und Workflows wie OpenClaw.
OpenAI unterstützt OAuth-Nutzung per Abonnement in externen Tools und Workflows wie OpenClaw ausdrücklich.
Provider, Modell, Runtime und Kanal sind getrennte Ebenen. Wenn diese Bezeichnungen
durcheinandergeraten, lesen Sie [Agent-Runtimes](/de/concepts/agent-runtimes), bevor
Sie die Konfiguration ändern.
Provider, Modell, Laufzeit und Kanal sind getrennte Ebenen. Wenn diese Bezeichnungen vermischt werden, lesen Sie [Agent-Laufzeiten](/de/concepts/agent-runtimes), bevor Sie die Konfiguration ändern.
## Schnelle Auswahl
## Schnellauswahl
| Ziel | Verwenden | Hinweise |
| ---------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
| ChatGPT-/Codex-Abonnement mit nativer Codex-Runtime | `openai/gpt-5.5` plus `agentRuntime.id: "codex"` | Empfohlene Codex-Einrichtung für die meisten Benutzer. Melden Sie sich mit `openai-codex`-Auth an. |
| Direkte API-Schlüssel-Abrechnung | `openai/gpt-5.5` | Setzen Sie `OPENAI_API_KEY` oder führen Sie das OpenAI-API-Schlüssel-Onboarding aus. |
| ChatGPT-/Codex-Abonnement-Auth über PI | `openai-codex/gpt-5.5` | Nur verwenden, wenn Sie bewusst den normalen PI-Runner wünschen. |
| Bilderzeugung oder -bearbeitung | `openai/gpt-image-2` | Funktioniert entweder mit `OPENAI_API_KEY` oder OpenAI-Codex-OAuth. |
| Bilder mit transparentem Hintergrund | `openai/gpt-image-1.5` | Verwenden Sie `outputFormat=png` oder `webp` und `openai.background=transparent`. |
| Ziel | Verwenden | Hinweise |
| ---------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
| ChatGPT/Codex-Abonnement mit nativer Codex-Laufzeit | `openai/gpt-5.5` plus `agentRuntime.id: "codex"` | Empfohlene Codex-Einrichtung für die meisten Benutzer. Mit `openai-codex`-Auth anmelden. |
| Direkte API-Schlüssel-Abrechnung | `openai/gpt-5.5` | Setzen Sie `OPENAI_API_KEY` oder führen Sie das OpenAI-API-Schlüssel-Onboarding aus. |
| ChatGPT/Codex-Abonnement-Auth über PI | `openai-codex/gpt-5.5` | Nur verwenden, wenn Sie ausdrücklich den normalen PI-Runner möchten. |
| Bilderzeugung oder -bearbeitung | `openai/gpt-image-2` | Funktioniert entweder mit `OPENAI_API_KEY` oder OpenAI Codex OAuth. |
| Bilder mit transparentem Hintergrund | `openai/gpt-image-1.5` | Verwenden Sie `outputFormat=png` oder `webp` und `openai.background=transparent`. |
## Namensübersicht
## Namenszuordnung
Die Namen sind ähnlich, aber nicht austauschbar:
Die Namen ähneln sich, sind aber nicht austauschbar:
| Name, den Sie sehen | Ebene | Bedeutung |
| ----------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | Provider-Präfix | Direkte OpenAI-Platform-API-Route. |
| `openai-codex` | Provider-Präfix | OpenAI-Codex-OAuth-/Abonnement-Route über den normalen OpenClaw-PI-Runner. |
| `codex` Plugin | Plugin | Gebündeltes OpenClaw-Plugin, das die native Codex-App-Server-Runtime und `/codex`-Chat-Steuerungen bereitstellt. |
| `agentRuntime.id: codex` | Agent-Runtime | Erzwingt das native Codex-App-Server-Harness für eingebettete Turns. |
| `/codex ...` | Chat-Befehlssatz | Codex-App-Server-Threads aus einer Unterhaltung binden/steuern. |
| `runtime: "acp", agentId: "codex"` | ACP-Sitzungsroute | Expliziter Fallback-Pfad, der Codex über ACP/acpx ausführt. |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | Provider-Präfix | Direkte OpenAI Platform-API-Route. |
| `openai-codex` | Provider-Präfix | OpenAI Codex OAuth-/Abonnement-Route über den normalen OpenClaw-PI-Runner. |
| `codex` plugin | Plugin | Gebündeltes OpenClaw-Plugin, das die native Codex-App-Server-Laufzeit und `/codex`-Chatsteuerungen bereitstellt. |
| `agentRuntime.id: codex` | Agent-Laufzeit | Erzwingt das native Codex-App-Server-Harness für eingebettete Turns. |
| `/codex ...` | Chatbefehlssatz | Codex-App-Server-Threads aus einer Unterhaltung binden/steuern. |
| `runtime: "acp", agentId: "codex"` | ACP-Sitzungsroute | Expliziter Fallback-Pfad, der Codex über ACP/acpx ausführt. |
Das bedeutet, dass eine Konfiguration absichtlich sowohl `openai-codex/*` als auch das
`codex` Plugin enthalten kann. Das ist gültig, wenn Sie Codex-OAuth über PI wünschen und außerdem
native `/codex`-Chat-Steuerungen verfügbar haben möchten. `openclaw doctor` warnt vor dieser
Kombination, damit Sie bestätigen können, dass sie beabsichtigt ist; es schreibt sie nicht um.
Das bedeutet, dass eine Konfiguration absichtlich sowohl `openai-codex/*` als auch das `codex`-Plugin enthalten kann. Das ist gültig, wenn Sie Codex OAuth über PI verwenden möchten und außerdem native `/codex`-Chatsteuerungen verfügbar haben möchten. `openclaw doctor` warnt vor dieser Kombination, damit Sie bestätigen können, dass sie beabsichtigt ist; es schreibt sie nicht um.
<Note>
GPT-5.5 ist sowohl über direkten OpenAI-Platform-API-Schlüssel-Zugriff als auch über
Abonnement-/OAuth-Routen verfügbar. Für ChatGPT-/Codex-Abonnement plus native Codex-
Ausführung verwenden Sie `openai/gpt-5.5` mit `agentRuntime.id: "codex"`. Verwenden Sie
`openai-codex/gpt-5.5` nur für Codex-OAuth über PI oder `openai/gpt-5.5`
ohne Codex-Runtime-Override für direkten `OPENAI_API_KEY`-Datenverkehr.
GPT-5.5 ist sowohl über direkten OpenAI Platform-API-Schlüssel-Zugriff als auch über Abonnement-/OAuth-Routen verfügbar. Für ChatGPT/Codex-Abonnement plus native Codex-Ausführung verwenden Sie `openai/gpt-5.5` mit `agentRuntime.id: "codex"`. Verwenden Sie `openai-codex/gpt-5.5` nur für Codex OAuth über PI oder `openai/gpt-5.5` ohne Codex-Laufzeitüberschreibung für direkten `OPENAI_API_KEY`-Traffic.
</Note>
<Note>
Das Aktivieren des OpenAI-Plugins oder die Auswahl eines `openai-codex/*`-Modells aktiviert nicht
das gebündelte Codex-App-Server-Plugin. OpenClaw aktiviert dieses Plugin nur,
wenn Sie das native Codex-Harness ausdrücklich mit
`agentRuntime.id: "codex"` auswählen oder eine ältere `codex/*`-Modellreferenz verwenden.
Wenn das gebündelte `codex` Plugin aktiviert ist, `openai-codex/*` aber weiterhin
über PI aufgelöst wird, warnt `openclaw doctor` und lässt die Route unverändert.
Das Aktivieren des OpenAI-Plugins oder die Auswahl eines `openai-codex/*`-Modells aktiviert nicht das gebündelte Codex-App-Server-Plugin. OpenClaw aktiviert dieses Plugin nur, wenn Sie das native Codex-Harness ausdrücklich mit `agentRuntime.id: "codex"` auswählen oder eine ältere `codex/*`-Modellreferenz verwenden.
Wenn das gebündelte `codex`-Plugin aktiviert ist, `openai-codex/*` aber weiterhin über PI aufgelöst wird, warnt `openclaw doctor` und lässt die Route unverändert.
</Note>
## OpenClaw-Funktionsabdeckung
| OpenAI-Fähigkeit | OpenClaw-Oberfläche | Status |
| ------------------------- | -------------------------------------------------------- | ------------------------------------------------------ |
| Chat / Responses | `openai/<model>` Modell-Provider | Ja |
| Codex-Abonnementmodelle | `openai-codex/<model>` mit `openai-codex` OAuth | Ja |
| Codex-App-Server-Harness | `openai/<model>` mit `agentRuntime.id: codex` | Ja |
| Serverseitige Websuche | Natives OpenAI-Responses-Tool | Ja, wenn die Websuche aktiviert und kein Provider festgelegt ist |
| Bilder | `image_generate` | Ja |
| Videos | `video_generate` | Ja |
| Text-to-Speech | `messages.tts.provider: "openai"` / `tts` | Ja |
| Batch-Speech-to-Text | `tools.media.audio` / Medienverständnis | Ja |
| Streaming-Speech-to-Text | Voice Call `streaming.provider: "openai"` | Ja |
| Echtzeit-Sprache | Voice Call `realtime.provider: "openai"` / Control UI Talk | Ja |
| Embeddings | Memory-Embedding-Provider | Ja |
| OpenAI-Fähigkeit | OpenClaw-Oberfläche | Status |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| Chat / Responses | `openai/<model>`-Modell-Provider | Ja |
| Codex-Abonnementmodelle | `openai-codex/<model>` mit `openai-codex` OAuth | Ja |
| Codex-App-Server-Harness | `openai/<model>` mit `agentRuntime.id: codex` | Ja |
| Serverseitige Websuche | Natives OpenAI Responses-Tool | Ja, wenn Websuche aktiviert ist und kein Provider festgelegt ist |
| Bilder | `image_generate` | Ja |
| Videos | `video_generate` | Ja |
| Text-to-Speech | `messages.tts.provider: "openai"` / `tts` | Ja |
| Batch-Speech-to-Text | `tools.media.audio` / Medienverständnis | Ja |
| Streaming-Speech-to-Text | Voice Call `streaming.provider: "openai"` | Ja |
| Echtzeit-Stimme | Voice Call `realtime.provider: "openai"` / Control UI Talk | Ja |
| Embeddings | Speicher-Embedding-Provider | Ja |
## Memory-Embeddings
## Speicher-Embeddings
OpenClaw kann OpenAI oder einen OpenAI-kompatiblen Embedding-Endpunkt für
`memory_search`-Indexierung und Abfrage-Embeddings verwenden:
OpenClaw kann OpenAI oder einen OpenAI-kompatiblen Embedding-Endpunkt für `memory_search`-Indexierung und Abfrage-Embeddings verwenden:
```json5
{
@ -112,11 +93,7 @@ OpenClaw kann OpenAI oder einen OpenAI-kompatiblen Embedding-Endpunkt für
}
```
Für OpenAI-kompatible Endpunkte, die asymmetrische Embedding-Labels erfordern, setzen Sie
`queryInputType` und `documentInputType` unter `memorySearch`. OpenClaw leitet
diese als Provider-spezifische `input_type`-Anfragefelder weiter: Abfrage-Embeddings verwenden
`queryInputType`; indexierte Memory-Chunks und Batch-Indexierung verwenden
`documentInputType`. Das vollständige Beispiel finden Sie in der [Memory-Konfigurationsreferenz](/de/reference/memory-config#provider-specific-config).
Für OpenAI-kompatible Endpunkte, die asymmetrische Embedding-Labels erfordern, setzen Sie `queryInputType` und `documentInputType` unter `memorySearch`. OpenClaw leitet diese als Provider-spezifische `input_type`-Request-Felder weiter: Abfrage-Embeddings verwenden `queryInputType`; indexierte Speicher-Chunks und Batch-Indexierung verwenden `documentInputType`. Das vollständige Beispiel finden Sie in der [Referenz zur Speicherkonfiguration](/de/reference/memory-config#provider-specific-config).
## Erste Schritte
@ -124,11 +101,11 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
<Tabs>
<Tab title="API-Schlüssel (OpenAI Platform)">
**Am besten geeignet für:** direkten API-Zugriff und nutzungsbasierte Abrechnung.
**Am besten für:** direkten API-Zugriff und nutzungsbasierte Abrechnung.
<Steps>
<Step title="Ihren API-Schlüssel abrufen">
Erstellen oder kopieren Sie einen API-Schlüssel aus dem [OpenAI-Platform-Dashboard](https://platform.openai.com/api-keys).
<Step title="API-Schlüssel abrufen">
Erstellen oder kopieren Sie einen API-Schlüssel aus dem [OpenAI Platform-Dashboard](https://platform.openai.com/api-keys).
</Step>
<Step title="Onboarding ausführen">
```bash
@ -150,17 +127,14 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
### Routenzusammenfassung
| Modellreferenz | Runtime-Konfiguration | Route | Auth |
| Modellreferenz | Laufzeitkonfiguration | Route | Auth |
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
| `openai/gpt-5.5` | weggelassen / `agentRuntime.id: "pi"` | Direkte OpenAI-Platform-API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | weggelassen / `agentRuntime.id: "pi"` | Direkte OpenAI-Platform-API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex-App-Server-Harness | Codex-App-Server |
| `openai/gpt-5.5` | weggelassen / `agentRuntime.id: "pi"` | Direkte OpenAI Platform-API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | weggelassen / `agentRuntime.id: "pi"` | Direkte OpenAI Platform-API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex-App-Server-Harness | Codex-App-Server |
<Note>
`openai/*` ist die direkte OpenAI-API-Schlüssel-Route, sofern Sie nicht ausdrücklich
das Codex-App-Server-Harness erzwingen. Verwenden Sie `openai-codex/*` für Codex-OAuth über
den standardmäßigen PI-Runner oder verwenden Sie `openai/gpt-5.5` mit
`agentRuntime.id: "codex"` für native Codex-App-Server-Ausführung.
`openai/*` ist die direkte OpenAI-API-Schlüssel-Route, sofern Sie nicht ausdrücklich das Codex-App-Server-Harness erzwingen. Verwenden Sie `openai-codex/*` für Codex OAuth über den Standard-PI-Runner oder `openai/gpt-5.5` mit `agentRuntime.id: "codex"` für native Codex-App-Server-Ausführung.
</Note>
### Konfigurationsbeispiel
@ -173,16 +147,16 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
```
<Warning>
OpenClaw stellt `openai/gpt-5.3-codex-spark` **nicht** bereit. Live-OpenAI-API-Anfragen lehnen dieses Modell ab, und der aktuelle Codex-Katalog stellt es ebenfalls nicht bereit.
OpenClaw stellt `openai/gpt-5.3-codex-spark` **nicht** bereit. Live-OpenAI-API-Requests lehnen dieses Modell ab, und der aktuelle Codex-Katalog stellt es ebenfalls nicht bereit.
</Warning>
</Tab>
<Tab title="Codex-Abonnement">
**Am besten geeignet für:** die Nutzung Ihres ChatGPT-/Codex-Abonnements mit nativer Codex-App-Server-Ausführung anstelle eines separaten API-Schlüssels. Codex Cloud erfordert eine ChatGPT-Anmeldung.
**Am besten für:** die Nutzung Ihres ChatGPT/Codex-Abonnements mit nativer Codex-App-Server-Ausführung anstelle eines separaten API-Schlüssels. Codex Cloud erfordert eine ChatGPT-Anmeldung.
<Steps>
<Step title="Codex-OAuth ausführen">
<Step title="Codex OAuth ausführen">
```bash
openclaw onboard --auth-choice openai-codex
```
@ -193,13 +167,13 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
openclaw models auth login --provider openai-codex
```
Für Headless- oder Callback-feindliche Setups fügen Sie `--device-code` hinzu, um sich mit einem ChatGPT-Device-Code-Flow statt über den localhost-Browser-Callback anzumelden:
Für headless oder Callback-unfreundliche Setups fügen Sie `--device-code` hinzu, um sich mit einem ChatGPT-Gerätecode-Flow statt mit dem localhost-Browser-Callback anzumelden:
```bash
openclaw models auth login --provider openai-codex --device-code
```
</Step>
<Step title="Die native Codex-Runtime verwenden">
<Step title="Native Codex-Laufzeit verwenden">
```bash
openclaw config set plugins.entries.codex '{"enabled":true}' --strict-json --merge
openclaw config set agents.defaults.model.primary openai/gpt-5.5
@ -211,26 +185,29 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
openclaw models list --provider openai-codex
```
Nachdem der Gateway läuft, senden Sie `/codex status` oder `/codex models`
im Chat, um die native App-Server-Runtime zu prüfen.
Nachdem das Gateway ausgeführt wird, senden Sie `/codex status` oder `/codex models` im Chat, um die native App-Server-Laufzeit zu prüfen.
</Step>
</Steps>
### Routenzusammenfassung
| Modellreferenz | Runtime-Konfiguration | Route | Auth |
| Modellreferenz | Laufzeitkonfiguration | Route | Auth |
|-----------|----------------|-------|------|
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Natives Codex-App-Server-Harness | Codex-Anmeldung oder ausgewähltes `openai-codex`-Profil |
| `openai-codex/gpt-5.5` | weggelassen / `runtime: "pi"` | ChatGPT-/Codex-OAuth über PI | Codex-Anmeldung |
| `openai-codex/gpt-5.4-mini` | weggelassen / `runtime: "pi"` | ChatGPT-/Codex-OAuth über PI | Codex-Anmeldung |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | Weiterhin PI, sofern nicht ein Plugin ausdrücklich `openai-codex` beansprucht | Codex-Anmeldung |
| `openai-codex/gpt-5.5` | weggelassen / `runtime: "pi"` | ChatGPT/Codex OAuth über PI | Codex-Anmeldung |
| `openai-codex/gpt-5.4-mini` | weggelassen / `runtime: "pi"` | ChatGPT/Codex OAuth über PI | Codex-Anmeldung |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | Weiterhin PI, sofern kein Plugin ausdrücklich `openai-codex` beansprucht | Codex-Anmeldung |
<Warning>
Konfigurieren Sie keine älteren `openai-codex/gpt-5.1*`-, `openai-codex/gpt-5.2*`- oder `openai-codex/gpt-5.3*`-Modellreferenzen. ChatGPT/Codex-OAuth-Konten lehnen diese Modelle inzwischen ab. Verwenden Sie `openai-codex/gpt-5.5` für die PI-OAuth-Route oder `openai/gpt-5.5` mit `agentRuntime.id: "codex"` für native Codex-Laufzeitausführung.
</Warning>
<Note>
Verwenden Sie weiterhin die Provider-ID `openai-codex` für Authentifizierungs-/Profilbefehle. Das
Verwenden Sie für Auth-/Profilbefehle weiterhin die Provider-ID `openai-codex`. Das
Modellpräfix `openai-codex/*` ist außerdem die explizite PI-Route für Codex OAuth.
Es wählt das gebündelte Codex-App-Server-Harness nicht aus und aktiviert es nicht automatisch. Für
die übliche Einrichtung mit Abonnement und nativer Laufzeit melden Sie sich mit
`openai-codex` an, behalten aber die Modellreferenz `openai/gpt-5.5` bei und setzen
Es wählt den gebündelten Codex-App-Server-Harness weder aus noch aktiviert es ihn automatisch. Für
die übliche Einrichtung mit Abonnement plus nativer Runtime melden Sie sich mit
`openai-codex` an, behalten Sie jedoch die Modellreferenz `openai/gpt-5.5` bei und setzen Sie
`agentRuntime.id: "codex"`.
</Note>
@ -249,39 +226,39 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
```
Um Codex OAuth stattdessen auf dem normalen PI-Runner zu belassen, verwenden Sie
`openai-codex/gpt-5.5` und lassen Sie die Codex-Laufzeitüberschreibung weg.
`openai-codex/gpt-5.5` und lassen Sie die Codex-Runtime-Überschreibung weg.
<Note>
Das Onboarding importiert kein OAuth-Material mehr aus `~/.codex`. Melden Sie sich mit Browser-OAuth (Standard) oder dem oben beschriebenen Gerätecode-Ablauf an — OpenClaw verwaltet die daraus resultierenden Anmeldedaten in seinem eigenen Agent-Auth-Speicher.
Onboarding importiert kein OAuth-Material mehr aus `~/.codex`. Melden Sie sich mit Browser-OAuth (Standard) oder dem oben beschriebenen Device-Code-Flow an — OpenClaw verwaltet die daraus entstehenden Anmeldedaten in seinem eigenen Agent-Auth-Speicher.
</Note>
### Statusanzeige
Chat `/status` zeigt, welche Modelllaufzeit für die aktuelle Sitzung aktiv ist.
Das Standard-PI-Harness wird als `Runtime: OpenClaw Pi Default` angezeigt. Wenn das
Chat `/status` zeigt, welche Modell-Runtime für die aktuelle Sitzung aktiv ist.
Der Standard-PI-Harness erscheint als `Runtime: OpenClaw Pi Default`. Wenn der
gebündelte Codex-App-Server-Harness ausgewählt ist, zeigt `/status`
`Runtime: OpenAI Codex`. Bestehende Sitzungen behalten ihre aufgezeichnete Harness-ID, verwenden Sie daher
`/new` oder `/reset`, nachdem Sie `agentRuntime` geändert haben, wenn `/status` eine neue PI/Codex-Auswahl
widerspiegeln soll.
`Runtime: OpenAI Codex`. Bestehende Sitzungen behalten ihre aufgezeichnete Harness-ID, verwenden Sie also
`/new` oder `/reset`, nachdem Sie `agentRuntime` geändert haben, wenn `/status`
eine neue PI-/Codex-Auswahl anzeigen soll.
### Doctor-Warnung
Wenn das gebündelte `codex`-Plugin aktiviert ist, während eine `openai-codex/*`-Route
ausgewählt ist, warnt `openclaw doctor`, dass das Modell weiterhin über PI aufgelöst wird.
Lassen Sie die Konfiguration nur unverändert, wenn diese PI-Route mit Abonnementauthentifizierung
Lassen Sie die Konfiguration nur dann unverändert, wenn diese PI-Route für Abonnement-Auth
beabsichtigt ist. Wechseln Sie zu `openai/<model>` plus `agentRuntime.id: "codex"`, wenn
Sie native Codex-App-Server-Ausführung möchten.
Sie native Codex-App-Server-Ausführung wünschen.
### Obergrenze für das Kontextfenster
### Kontextfenster-Obergrenze
OpenClaw behandelt Modellmetadaten und die Laufzeit-Obergrenze für den Kontext als getrennte Werte.
OpenClaw behandelt Modellmetadaten und die Runtime-Kontextobergrenze als getrennte Werte.
Für `openai-codex/gpt-5.5` über Codex OAuth:
- Native `contextWindow`: `1000000`
- Standardmäßige Laufzeit-Obergrenze `contextTokens`: `272000`
- Standardmäßige Runtime-Obergrenze `contextTokens`: `272000`
Die kleinere Standard-Obergrenze bietet in der Praxis bessere Latenz- und Qualitätsmerkmale. Überschreiben Sie sie mit `contextTokens`:
Die kleinere Standardobergrenze bietet in der Praxis bessere Latenz- und Qualitätseigenschaften. Überschreiben Sie sie mit `contextTokens`:
```json5
{
@ -296,13 +273,13 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
```
<Note>
Verwenden Sie `contextWindow`, um native Modellmetadaten zu deklarieren. Verwenden Sie `contextTokens`, um das Laufzeit-Kontextbudget zu begrenzen.
Verwenden Sie `contextWindow`, um native Modellmetadaten zu deklarieren. Verwenden Sie `contextTokens`, um das Runtime-Kontextbudget zu begrenzen.
</Note>
### Katalogwiederherstellung
OpenClaw verwendet vorgelagerte Codex-Katalogmetadaten für `gpt-5.5`, wenn sie
vorhanden sind. Wenn die Live-Codex-Erkennung die Zeile `openai-codex/gpt-5.5` auslässt, während
OpenClaw verwendet Upstream-Codex-Katalogmetadaten für `gpt-5.5`, wenn sie
vorhanden sind. Wenn die Live-Codex-Erkennung die Zeile `openai-codex/gpt-5.5` auslässt, obwohl
das Konto authentifiziert ist, synthetisiert OpenClaw diese OAuth-Modellzeile, damit
Cron-, Sub-Agent- und konfigurierte Standardmodell-Läufe nicht mit
`Unknown model` fehlschlagen.
@ -310,41 +287,41 @@ Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritte
</Tab>
</Tabs>
## Native Codex-App-Server-Authentifizierung
## Native Codex-App-Server-Auth
Das native Codex-App-Server-Harness verwendet `openai/*`-Modellreferenzen plus
`agentRuntime.id: "codex"`, aber seine Authentifizierung bleibt kontobasiert. OpenClaw
wählt die Authentifizierung in dieser Reihenfolge aus:
Der native Codex-App-Server-Harness verwendet `openai/*`-Modellreferenzen plus
`agentRuntime.id: "codex"`, seine Authentifizierung bleibt jedoch kontobasiert. OpenClaw
wählt Auth in dieser Reihenfolge aus:
1. Ein explizites OpenClaw-Auth-Profil `openai-codex`, das an den Agent gebunden ist.
2. Das vorhandene Konto des App-Servers, z. B. eine lokale Codex CLI-ChatGPT-Anmeldung.
3. Nur für lokale stdio-App-Server-Starts: `CODEX_API_KEY`, dann
2. Das vorhandene Konto des App-Servers, etwa eine lokale Codex-CLI-ChatGPT-Anmeldung.
3. Nur für lokale Stdio-App-Server-Starts: `CODEX_API_KEY`, dann
`OPENAI_API_KEY`, wenn der App-Server kein Konto meldet und weiterhin
OpenAI-Authentifizierung benötigt.
OpenAI-Auth benötigt.
Das bedeutet, dass eine lokale ChatGPT-/Codex-Abonnementanmeldung nicht ersetzt wird, nur
Das bedeutet, dass eine lokale ChatGPT-/Codex-Abonnement-Anmeldung nicht ersetzt wird, nur
weil der Gateway-Prozess auch `OPENAI_API_KEY` für direkte OpenAI-Modelle
oder Embeddings hat. Der Env-API-Schlüssel-Fallback ist nur der lokale stdio-Pfad ohne Konto; er
oder Embeddings hat. Der Env-API-Key-Fallback gilt nur für den lokalen Stdio-Pfad ohne Konto; er
wird nicht an WebSocket-App-Server-Verbindungen gesendet. Wenn ein Codex-Profil im Abonnementstil
ausgewählt ist, hält OpenClaw außerdem `CODEX_API_KEY` und `OPENAI_API_KEY`
aus dem gestarteten stdio-App-Server-Kindprozess heraus und sendet die ausgewählten Anmeldedaten
über den Login-RPC des App-Servers.
aus dem erzeugten Stdio-App-Server-Child heraus und sendet die ausgewählten Anmeldedaten
über den App-Server-Login-RPC.
## Bilderzeugung
Das gebündelte `openai`-Plugin registriert Bilderzeugung über das Tool `image_generate`.
Es unterstützt sowohl Bilderzeugung mit OpenAI-API-Schlüssel als auch Codex-OAuth-Bilderzeugung
Es unterstützt sowohl OpenAI-API-Key-Bilderzeugung als auch Codex-OAuth-Bilderzeugung
über dieselbe Modellreferenz `openai/gpt-image-2`.
| Fähigkeit | OpenAI-API-Schlüssel | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| Modellreferenz | `openai/gpt-image-2` | `openai/gpt-image-2` |
| Authentifizierung | `OPENAI_API_KEY` | OpenAI Codex OAuth-Anmeldung |
| Transport | OpenAI Images API | Codex Responses-Backend |
| Max. Bilder pro Anfrage | 4 | 4 |
| Bearbeitungsmodus | Aktiviert (bis zu 5 Referenzbilder) | Aktiviert (bis zu 5 Referenzbilder) |
| Größenüberschreibungen | Unterstützt, einschließlich 2K-/4K-Größen | Unterstützt, einschließlich 2K-/4K-Größen |
| Seitenverhältnis / Auflösung | Nicht an OpenAI Images API weitergeleitet | Wird bei sicherer Möglichkeit einer unterstützten Größe zugeordnet |
| Fähigkeit | OpenAI-API-Key | Codex OAuth |
| ------------------------ | --------------------------------- | ------------------------------------ |
| Modellreferenz | `openai/gpt-image-2` | `openai/gpt-image-2` |
| Auth | `OPENAI_API_KEY` | OpenAI-Codex-OAuth-Anmeldung |
| Transport | OpenAI Images API | Codex Responses-Backend |
| Maximale Bilder pro Anfrage | 4 | 4 |
| Bearbeitungsmodus | Aktiviert (bis zu 5 Referenzbilder) | Aktiviert (bis zu 5 Referenzbilder) |
| Größenüberschreibungen | Unterstützt, einschließlich 2K-/4K-Größen | Unterstützt, einschließlich 2K-/4K-Größen |
| Seitenverhältnis / Auflösung | Nicht an OpenAI Images API weitergeleitet | Wird, sofern sicher, einer unterstützten Größe zugeordnet |
```json5
{
@ -360,21 +337,21 @@ Es unterstützt sowohl Bilderzeugung mit OpenAI-API-Schlüssel als auch Codex-OA
Siehe [Bilderzeugung](/de/tools/image-generation) für gemeinsame Tool-Parameter, Provider-Auswahl und Failover-Verhalten.
</Note>
`gpt-image-2` ist der Standard für OpenAI-Text-zu-Bild-Erzeugung und Bildbearbeitung.
`gpt-image-1.5`, `gpt-image-1` und `gpt-image-1-mini` bleiben als explizite
Modellüberschreibungen verwendbar. Verwenden Sie `openai/gpt-image-1.5` für PNG-/WebP-Ausgabe
mit transparentem Hintergrund; die aktuelle `gpt-image-2`-API weist
`background: "transparent"` zurück.
`gpt-image-2` ist der Standard sowohl für OpenAI-Text-zu-Bild-Erzeugung als auch für Bildbearbeitung.
`gpt-image-1.5`, `gpt-image-1` und `gpt-image-1-mini` bleiben als
explizite Modellüberschreibungen nutzbar. Verwenden Sie `openai/gpt-image-1.5` für PNG-/WebP-Ausgabe
mit transparentem Hintergrund; die aktuelle `gpt-image-2`-API lehnt
`background: "transparent"` ab.
Für eine Anfrage mit transparentem Hintergrund sollten Agents `image_generate` mit
`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` oder `"webp"` und
`background: "transparent"` aufrufen; die ältere Provider-Option `openai.background` wird
weiterhin akzeptiert. OpenClaw schützt außerdem die öffentlichen OpenAI- und
OpenAI-Codex-OAuth-Routen, indem transparente Standardanfragen an `openai/gpt-image-2`
zu `gpt-image-1.5` umgeschrieben werden; Azure- und benutzerdefinierte OpenAI-kompatible Endpunkte behalten
OpenAI-Codex-OAuth-Routen, indem standardmäßige transparente `openai/gpt-image-2`-Anfragen
zu `gpt-image-1.5` umgeschrieben werden; Azure und benutzerdefinierte OpenAI-kompatible Endpunkte behalten
ihre konfigurierten Deployment-/Modellnamen.
Dieselbe Einstellung ist für Headless-CLI-Läufe verfügbar:
Dieselbe Einstellung wird für Headless-CLI-Läufe verfügbar gemacht:
```bash
openclaw infer image generate \
@ -389,25 +366,25 @@ Verwenden Sie dieselben Flags `--output-format` und `--background` mit
`openclaw infer image edit`, wenn Sie von einer Eingabedatei ausgehen.
`--openai-background` bleibt als OpenAI-spezifischer Alias verfügbar.
Behalten Sie für Codex-OAuth-Installationen dieselbe Referenz `openai/gpt-image-2` bei. Wenn ein
Für Codex-OAuth-Installationen behalten Sie dieselbe Referenz `openai/gpt-image-2` bei. Wenn ein
OAuth-Profil `openai-codex` konfiguriert ist, löst OpenClaw dieses gespeicherte OAuth-
Zugriffstoken auf und sendet Bildanfragen über das Codex Responses-Backend. Es
versucht für diese Anfrage nicht zuerst `OPENAI_API_KEY` und fällt nicht stillschweigend auf einen API-Schlüssel
zurück. Konfigurieren Sie `models.providers.openai` explizit mit einem API-Schlüssel,
versucht nicht zuerst `OPENAI_API_KEY` und fällt für diese Anfrage auch nicht stillschweigend auf einen API-Key
zurück. Konfigurieren Sie `models.providers.openai` explizit mit einem API-Key,
einer benutzerdefinierten Basis-URL oder einem Azure-Endpunkt, wenn Sie stattdessen die direkte OpenAI Images API-
Route verwenden möchten.
Wenn sich dieser benutzerdefinierte Bildendpunkt in einem vertrauenswürdigen LAN/einer privaten Adresse befindet, setzen Sie außerdem
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw blockiert
private/interne OpenAI-kompatible Bildendpunkte, sofern diese explizite Zustimmung nicht
Wenn dieser benutzerdefinierte Bildendpunkt in einem vertrauenswürdigen LAN/privaten Adressbereich liegt, setzen Sie außerdem
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw hält
private/interne OpenAI-kompatible Bildendpunkte blockiert, sofern diese Opt-in-Option nicht
vorhanden ist.
Erzeugen:
Generieren:
```
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
```
Transparentes PNG erzeugen:
Ein transparentes PNG generieren:
```
/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
@ -423,13 +400,13 @@ Bearbeiten:
Das gebündelte `openai`-Plugin registriert Videoerzeugung über das Tool `video_generate`.
| Fähigkeit | Wert |
| ---------------- | --------------------------------------------------------------------------------- |
| Standardmodell | `openai/sora-2` |
| Modi | Text-zu-Video, Bild-zu-Video, Einzelvideo-Bearbeitung |
| Referenzeingaben | 1 Bild oder 1 Video |
| Größenüberschreibungen | Unterstützt |
| Weitere Überschreibungen | `aspectRatio`, `resolution`, `audio`, `watermark` werden mit einer Tool-Warnung ignoriert |
| Fähigkeit | Wert |
| --------------- | --------------------------------------------------------------------------------- |
| Standardmodell | `openai/sora-2` |
| Modi | Text-zu-Video, Bild-zu-Video, Einzelvideo-Bearbeitung |
| Referenzeingaben | 1 Bild oder 1 Video |
| Größenüberschreibungen | Unterstützt |
| Weitere Überschreibungen | `aspectRatio`, `resolution`, `audio`, `watermark` werden mit einer Tool-Warnung ignoriert |
```json5
{
@ -447,17 +424,17 @@ Siehe [Videoerzeugung](/de/tools/video-generation) für gemeinsame Tool-Paramete
## GPT-5-Prompt-Beitrag
OpenClaw fügt einen gemeinsamen GPT-5-Prompt-Beitrag für Läufe der GPT-5-Familie über Provider hinweg hinzu. Er wird anhand der Modell-ID angewendet, sodass `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` und andere kompatible GPT-5-Referenzen dieselbe Überlagerung erhalten. Ältere GPT-4.x-Modelle nicht.
OpenClaw fügt einen gemeinsamen GPT-5-Prompt-Beitrag für Läufe der GPT-5-Familie über Provider hinweg hinzu. Er wird anhand der Modell-ID angewendet, sodass `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` und andere kompatible GPT-5-Referenzen dasselbe Overlay erhalten. Ältere GPT-4.x-Modelle erhalten es nicht.
Das gebündelte native Codex-Harness verwendet dasselbe GPT-5-Verhalten und dieselbe Heartbeat-Überlagerung über Entwickleranweisungen des Codex-App-Servers, sodass `openai/gpt-5.x`-Sitzungen, die über `agentRuntime.id: "codex"` erzwungen werden, dieselbe Follow-through- und proaktive Heartbeat-Anleitung behalten, auch wenn Codex den Rest des Harness-Prompts besitzt.
Der gebündelte native Codex-Harness verwendet dasselbe GPT-5-Verhalten und Heartbeat-Overlay über Codex-App-Server-Developer-Instruktionen, sodass `openai/gpt-5.x`-Sitzungen, die über `agentRuntime.id: "codex"` erzwungen werden, dieselbe Follow-through- und proaktive Heartbeat-Anleitung behalten, obwohl Codex den Rest des Harness-Prompts besitzt.
Der GPT-5-Beitrag fügt einen getaggten Verhaltensvertrag für Persona-Persistenz, Ausführungssicherheit, Tool-Disziplin, Ausgabeform, Abschlussprüfungen und Verifizierung hinzu. Kanalspezifisches Antwort- und Silent-Message-Verhalten bleibt im gemeinsamen OpenClaw-Systemprompt und in der ausgehenden Zustellrichtlinie. Die GPT-5-Anleitung ist für passende Modelle immer aktiviert. Die Ebene für freundlichen Interaktionsstil ist separat und konfigurierbar.
Der GPT-5-Beitrag fügt einen getaggten Verhaltensvertrag für Persona-Persistenz, Ausführungssicherheit, Tool-Disziplin, Ausgabeform, Abschlussprüfungen und Verifikation hinzu. Kanalspezifisches Antwort- und Silent-Message-Verhalten verbleibt im gemeinsamen OpenClaw-Systemprompt und in der Richtlinie für ausgehende Zustellung. Die GPT-5-Anleitung ist für passende Modelle immer aktiviert. Die Ebene für den freundlichen Interaktionsstil ist separat und konfigurierbar.
| Wert | Wirkung |
| ---------------------- | ------------------------------------------- |
| `"friendly"` (Standard) | Ebene für freundlichen Interaktionsstil aktivieren |
| `"on"` | Alias für `"friendly"` |
| `"off"` | Nur die freundliche Stilebene deaktivieren |
| Wert | Effekt |
| ---------------------- | -------------------------------------------------- |
| `"friendly"` (Standard) | Freundliche Interaktionsstil-Ebene aktivieren |
| `"on"` | Alias für `"friendly"` |
| `"off"` | Nur die freundliche Stil-Ebene deaktivieren |
<Tabs>
<Tab title="Konfiguration">
@ -481,11 +458,11 @@ Der GPT-5-Beitrag fügt einen getaggten Verhaltensvertrag für Persona-Persisten
</Tabs>
<Tip>
Bei der Laufzeit wird Groß-/Kleinschreibung für Werte nicht beachtet, daher deaktivieren sowohl `"Off"` als auch `"off"` die freundliche Stilebene.
Werte sind zur Laufzeit nicht groß-/kleinschreibungssensitiv, daher deaktivieren sowohl `"Off"` als auch `"off"` die freundliche Stil-Ebene.
</Tip>
<Note>
Das veraltete `plugins.entries.openai.config.personality` wird weiterhin als Kompatibilitäts-Fallback gelesen, wenn die gemeinsame Einstellung `agents.defaults.promptOverlays.gpt5.personality` nicht gesetzt ist.
Das Legacy-`plugins.entries.openai.config.personality` wird weiterhin als Kompatibilitäts-Fallback gelesen, wenn die gemeinsame Einstellung `agents.defaults.promptOverlays.gpt5.personality` nicht gesetzt ist.
</Note>
## Stimme und Sprache
@ -500,14 +477,14 @@ Das veraltete `plugins.entries.openai.config.personality` wird weiterhin als Kom
| Stimme | `messages.tts.providers.openai.voice` | `coral` |
| Geschwindigkeit | `messages.tts.providers.openai.speed` | (nicht gesetzt) |
| Anweisungen | `messages.tts.providers.openai.instructions` | (nicht gesetzt, nur `gpt-4o-mini-tts`) |
| Format | `messages.tts.providers.openai.responseFormat` | `opus` für Sprachnachrichten, `mp3` für Dateien |
| Format | `messages.tts.providers.openai.responseFormat` | `opus` für Sprachnotizen, `mp3` für Dateien |
| API-Schlüssel | `messages.tts.providers.openai.apiKey` | Fällt auf `OPENAI_API_KEY` zurück |
| Basis-URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
| Zusätzlicher Body | `messages.tts.providers.openai.extraBody` / `extra_body` | (nicht gesetzt) |
Verfügbare Modelle: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Verfügbare Stimmen: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
`extraBody` wird nach den von OpenClaw generierten Feldern in das Anfrage-JSON für `/audio/speech` zusammengeführt. Verwenden Sie es daher für OpenAI-kompatible Endpunkte, die zusätzliche Schlüssel wie `lang` erfordern. Prototypschlüssel werden ignoriert.
`extraBody` wird nach den von OpenClaw generierten Feldern in das JSON der `/audio/speech`-Anfrage zusammengeführt. Verwenden Sie es daher für OpenAI-kompatible Endpunkte, die zusätzliche Schlüssel wie `lang` benötigen. Prototype-Schlüssel werden ignoriert.
```json5
{
@ -532,13 +509,13 @@ Das veraltete `plugins.entries.openai.config.personality` wird weiterhin als Kom
OpenClaws Transkriptionsoberfläche für Medienverständnis.
- Standardmodell: `gpt-4o-transcribe`
- Endpunkt: OpenAI REST `/v1/audio/transcriptions`
- Endpunkt: OpenAI-REST `/v1/audio/transcriptions`
- Eingabepfad: Multipart-Audiodatei-Upload
- Unterstützt von OpenClaw überall dort, wo die Transkription eingehender Audiodaten
`tools.media.audio` verwendet, einschließlich Discord-Sprachkanalsegmenten und Kanal-
Audioanhängen
- Unterstützt von OpenClaw überall dort, wo eingehende Audiotranskription
`tools.media.audio` verwendet, einschließlich Discord-Sprachkanal-Segmenten und
Audioanhängen in Channels
So erzwingen Sie OpenAI für die Transkription eingehender Audiodaten:
Um OpenAI für eingehende Audiotranskription zu erzwingen:
```json5
{
@ -559,30 +536,31 @@ Das veraltete `plugins.entries.openai.config.personality` wird weiterhin als Kom
```
Sprach- und Prompt-Hinweise werden an OpenAI weitergeleitet, wenn sie von der
gemeinsamen Audiomedien-Konfiguration oder der Transkriptionsanfrage pro Aufruf bereitgestellt werden.
gemeinsamen Audiomedienkonfiguration oder der Transkriptionsanfrage pro Aufruf
bereitgestellt werden.
</Accordion>
<Accordion title="Echtzeittranskription">
Das gebündelte `openai`-Plugin registriert Echtzeittranskription für das Voice Call-Plugin.
<Accordion title="Realtime-Transkription">
Das gebündelte `openai`-Plugin registriert Realtime-Transkription für das Voice Call-Plugin.
| Einstellung | Konfigurationspfad | Standard |
|---------|------------|---------|
| Modell | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| Sprache | `...openai.language` | (nicht gesetzt) |
| Prompt | `...openai.prompt` | (nicht gesetzt) |
| Stilledauer | `...openai.silenceDurationMs` | `800` |
| Dauer der Stille | `...openai.silenceDurationMs` | `800` |
| VAD-Schwellenwert | `...openai.vadThreshold` | `0.5` |
| API-Schlüssel | `...openai.apiKey` | Fällt auf `OPENAI_API_KEY` zurück |
<Note>
Verwendet eine WebSocket-Verbindung zu `wss://api.openai.com/v1/realtime` mit G.711 u-law (`g711_ulaw` / `audio/pcmu`)-Audio. Dieser Streaming-Provider ist für den Echtzeittranskriptionspfad von Voice Call vorgesehen; Discord-Sprachfunktionen zeichnen derzeit kurze Segmente auf und verwenden stattdessen den Batch-Transkriptionspfad `tools.media.audio`.
Verwendet eine WebSocket-Verbindung zu `wss://api.openai.com/v1/realtime` mit G.711 u-law (`g711_ulaw` / `audio/pcmu`)-Audio. Dieser Streaming-Provider ist für den Realtime-Transkriptionspfad von Voice Call vorgesehen; Discord-Voice zeichnet derzeit kurze Segmente auf und verwendet stattdessen den Batch-Transkriptionspfad `tools.media.audio`.
</Note>
</Accordion>
<Accordion title="Echtzeitstimme">
Das gebündelte `openai`-Plugin registriert Echtzeitstimme für das Voice Call-Plugin.
<Accordion title="Realtime-Sprache">
Das gebündelte `openai`-Plugin registriert Realtime-Sprache für das Voice Call-Plugin.
| Einstellung | Konfigurationspfad | Standard |
|---------|------------|---------|
@ -590,21 +568,21 @@ Das veraltete `plugins.entries.openai.config.personality` wird weiterhin als Kom
| Stimme | `...openai.voice` | `alloy` |
| Temperatur | `...openai.temperature` | `0.8` |
| VAD-Schwellenwert | `...openai.vadThreshold` | `0.5` |
| Stilledauer | `...openai.silenceDurationMs` | `500` |
| Dauer der Stille | `...openai.silenceDurationMs` | `500` |
| API-Schlüssel | `...openai.apiKey` | Fällt auf `OPENAI_API_KEY` zurück |
<Note>
Unterstützt Azure OpenAI über die Konfigurationsschlüssel `azureEndpoint` und `azureDeployment` für Backend-Echtzeit-Bridges. Unterstützt bidirektionale Tool-Aufrufe. Verwendet das Audioformat G.711 u-law.
Unterstützt Azure OpenAI über die Konfigurationsschlüssel `azureEndpoint` und `azureDeployment` für Backend-Realtime-Bridges. Unterstützt bidirektionale Tool-Aufrufe. Verwendet das Audioformat G.711 u-law.
</Note>
<Note>
Control UI Talk verwendet OpenAI-Browser-Echtzeitsitzungen mit einem vom Gateway geprägten
kurzlebigen Client-Geheimnis und einem direkten Browser-WebRTC-SDP-Austausch gegen die
OpenAI Realtime API. Live-Verifizierung durch Maintainer ist verfügbar mit
Control UI Talk verwendet OpenAI-Browser-Realtime-Sitzungen mit einem vom Gateway geprägten
kurzlebigen Client-Secret und einem direkten Browser-WebRTC-SDP-Austausch mit der
OpenAI Realtime API. Maintainer-Live-Verifizierung ist verfügbar mit
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
der OpenAI-Teil prägt ein Client-Geheimnis in Node, generiert ein Browser-SDP-Angebot
mit gefälschten Mikrofonmedien, postet es an OpenAI und wendet die SDP-Antwort an,
ohne Geheimnisse zu protokollieren.
der OpenAI-Abschnitt prägt ein Client-Secret in Node, generiert ein Browser-SDP-Angebot
mit gefälschten Mikrofonmedien, sendet es an OpenAI und wendet die SDP-Antwort an,
ohne Secrets zu protokollieren.
</Note>
</Accordion>
@ -612,29 +590,29 @@ Das veraltete `plugins.entries.openai.config.personality` wird weiterhin als Kom
## Azure OpenAI-Endpunkte
Der gebündelte `openai`-Provider kann durch Überschreiben der Basis-URL eine Azure OpenAI-Ressource
für die Bildgenerierung ansteuern. Im Bildgenerierungspfad erkennt OpenClaw
Azure-Hostnamen in `models.providers.openai.baseUrl` und wechselt automatisch
zur Anfrageform von Azure.
Der gebündelte `openai`-Provider kann für die Bildgenerierung eine Azure OpenAI-Ressource
ansteuern, indem die Basis-URL überschrieben wird. Im Bildgenerierungspfad erkennt OpenClaw
Azure-Hostnamen in `models.providers.openai.baseUrl` und wechselt automatisch zur
Anfrageform von Azure.
<Note>
Echtzeitstimme verwendet einen separaten Konfigurationspfad
Realtime-Sprache verwendet einen separaten Konfigurationspfad
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
und wird von `models.providers.openai.baseUrl` nicht beeinflusst. Siehe das Accordion **Echtzeitstimme**
unter [Stimme und Sprache](#voice-and-speech) für die Azure-
und wird von `models.providers.openai.baseUrl` nicht beeinflusst. Siehe das Akkordeon **Realtime-
Sprache** unter [Sprache und Sprachausgabe](#voice-and-speech) für die zugehörigen Azure-
Einstellungen.
</Note>
Verwenden Sie Azure OpenAI, wenn:
- Sie bereits ein Azure OpenAI-Abonnement, Kontingent oder eine Unternehmensvereinbarung haben
- Sie bereits ein Azure OpenAI-Abonnement, ein Kontingent oder eine Unternehmensvereinbarung haben
- Sie regionale Datenresidenz oder Compliance-Kontrollen benötigen, die Azure bereitstellt
- Sie Datenverkehr innerhalb eines bestehenden Azure-Mandanten halten möchten
- Sie den Datenverkehr innerhalb einer vorhandenen Azure-Tenancy halten möchten
### Konfiguration
Für Azure-Bildgenerierung über den gebündelten `openai`-Provider richten Sie
`models.providers.openai.baseUrl` auf Ihre Azure-Ressource und setzen `apiKey` auf
`models.providers.openai.baseUrl` auf Ihre Azure-Ressource und setzen Sie `apiKey` auf
den Azure OpenAI-Schlüssel (nicht auf einen OpenAI Platform-Schlüssel):
```json5
@ -650,29 +628,28 @@ den Azure OpenAI-Schlüssel (nicht auf einen OpenAI Platform-Schlüssel):
}
```
OpenClaw erkennt diese Azure-Hostsuffixe für die Azure-Bildgenerierungs-
Route:
OpenClaw erkennt diese Azure-Host-Suffixe für die Azure-Bildgenerierungsroute:
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
Bei Bildgenerierungsanfragen auf einem erkannten Azure-Host führt OpenClaw Folgendes aus:
Bei Bildgenerierungsanfragen an einen erkannten Azure-Host führt OpenClaw Folgendes aus:
- Sendet den Header `api-key` anstelle von `Authorization: Bearer`
- Verwendet deploymentspezifische Pfade (`/openai/deployments/{deployment}/...`)
- Verwendet deploymentbezogene Pfade (`/openai/deployments/{deployment}/...`)
- Hängt `?api-version=...` an jede Anfrage an
- Verwendet ein Standard-Anfragetimeout von 600 s für Azure-Bildgenerierungsaufrufe.
- Verwendet ein Standard-Anfrage-Timeout von 600 Sekunden für Azure-Bildgenerierungsaufrufe.
`timeoutMs`-Werte pro Aufruf überschreiben diesen Standard weiterhin.
Andere Basis-URLs (öffentliches OpenAI, OpenAI-kompatible Proxys) behalten die standardmäßige
OpenAI-Anfrageform für Bilder bei.
Andere Basis-URLs (öffentliches OpenAI, OpenAI-kompatible Proxys) behalten die Standardform
für OpenAI-Bildanfragen bei.
<Note>
Azure-Routing für den Bildgenerierungspfad des `openai`-Providers erfordert
OpenClaw 2026.4.22 oder höher. Frühere Versionen behandeln jede benutzerdefinierte
OpenClaw 2026.4.22 oder neuer. Frühere Versionen behandeln jede benutzerdefinierte
`openai.baseUrl` wie den öffentlichen OpenAI-Endpunkt und schlagen bei Azure-
Bildbereitstellungen fehl.
Bild-Deployments fehl.
</Note>
### API-Version
@ -707,28 +684,28 @@ den gebündelten `openai`-Provider geroutet werden.
Azure-Bildgenerierung ist derzeit nur in einer Teilmenge von Regionen verfügbar
(zum Beispiel `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
`uaenorth`). Prüfen Sie die aktuelle Regionsliste von Microsoft, bevor Sie ein
Deployment erstellen, und bestätigen Sie, dass das spezifische Modell in Ihrer Region angeboten wird.
Deployment erstellen, und bestätigen Sie, dass das konkrete Modell in Ihrer Region angeboten wird.
### Parameterunterschiede
Azure OpenAI und öffentliches OpenAI akzeptieren nicht immer dieselben Bildparameter.
Azure kann Optionen ablehnen, die öffentliches OpenAI zulässt (zum Beispiel bestimmte
`background`-Werte bei `gpt-image-2`), oder sie nur für bestimmte Modellversionen
bereitstellen. Diese Unterschiede stammen von Azure und dem zugrunde liegenden Modell, nicht
von OpenClaw. Wenn eine Azure-Anfrage mit einem Validierungsfehler fehlschlägt, prüfen Sie den
Parametersatz, der von Ihrem spezifischen Deployment und Ihrer API-Version im
Azure kann Optionen ablehnen, die öffentliches OpenAI erlaubt (zum Beispiel bestimmte
`background`-Werte bei `gpt-image-2`), oder sie nur für bestimmte Modellversionen bereitstellen.
Diese Unterschiede stammen von Azure und dem zugrunde liegenden Modell, nicht von
OpenClaw. Wenn eine Azure-Anfrage mit einem Validierungsfehler fehlschlägt, prüfen Sie den
Parametersatz, der von Ihrem konkreten Deployment und Ihrer API-Version im
Azure-Portal unterstützt wird.
<Note>
Azure OpenAI verwendet natives Transport- und Kompatibilitätsverhalten, erhält aber nicht
die versteckten Attributionsheader von OpenClaw — siehe das Accordion **Native vs. OpenAI-kompatible
Azure OpenAI verwendet nativen Transport und Compat-Verhalten, erhält aber nicht
OpenClaws versteckte Attribution-Header — siehe das Akkordeon **Native vs. OpenAI-kompatible
Routen** unter [Erweiterte Konfiguration](#advanced-configuration).
Für Chat- oder Responses-Datenverkehr auf Azure (über die Bildgenerierung hinaus) verwenden Sie den
Für Chat- oder Responses-Datenverkehr auf Azure (über Bildgenerierung hinaus) verwenden Sie den
Onboarding-Ablauf oder eine dedizierte Azure-Provider-Konfiguration — `openai.baseUrl` allein
übernimmt nicht die Azure-API-/Auth-Form. Ein separater
übernimmt nicht die Azure-API/Auth-Form. Ein separater
`azure-openai-responses/*`-Provider existiert; siehe
das Server-seitige Compaction-Accordion unten.
das Server-seitige Compaction-Akkordeon unten.
</Note>
## Erweiterte Konfiguration
@ -739,13 +716,13 @@ das Server-seitige Compaction-Accordion unten.
Im Modus `"auto"` führt OpenClaw Folgendes aus:
- Wiederholt einen frühen WebSocket-Fehler einmal, bevor auf SSE zurückgefallen wird
- Markiert WebSocket nach einem Fehler für ca. 60 Sekunden als beeinträchtigt und verwendet während der Abkühlphase SSE
- Fügt stabile Sitzungs- und Turn-Identitätsheader für Wiederholungen und erneute Verbindungen an
- Markiert WebSocket nach einem Fehler für etwa 60 Sekunden als beeinträchtigt und verwendet während der Abkühlphase SSE
- Hängt stabile Sitzungs- und Turn-Identitätsheader für Wiederholungen und Wiederverbindungen an
- Normalisiert Nutzungszähler (`input_tokens` / `prompt_tokens`) über Transportvarianten hinweg
| Wert | Verhalten |
|-------|----------|
| `"auto"` (Standard) | Zuerst WebSocket, SSE-Fallback |
| `"auto"` (Standard) | WebSocket zuerst, SSE-Fallback |
| `"sse"` | Nur SSE erzwingen |
| `"websocket"` | Nur WebSocket erzwingen |
@ -772,8 +749,8 @@ das Server-seitige Compaction-Accordion unten.
</Accordion>
<Accordion title="WebSocket-Aufwärmung">
OpenClaw aktiviert WebSocket-Aufwärmung standardmäßig für `openai/*` und `openai-codex/*`, um die Latenz des ersten Turns zu reduzieren.
<Accordion title="WebSocket-Warm-up">
OpenClaw aktiviert WebSocket-Warm-up standardmäßig für `openai/*` und `openai-codex/*`, um die Latenz der ersten Antwort zu reduzieren.
```json5
// Disable warm-up
@ -798,7 +775,7 @@ das Server-seitige Compaction-Accordion unten.
- **Chat/UI:** `/fast status|on|off`
- **Konfiguration:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
Wenn aktiviert, ordnet OpenClaw den Schnellmodus der OpenAI-Prioritätsverarbeitung zu (`service_tier = "priority"`). Bestehende `service_tier`-Werte bleiben erhalten, und der Schnellmodus schreibt `reasoning` oder `text.verbosity` nicht um.
Wenn aktiviert, ordnet OpenClaw den Schnellmodus der OpenAI-Prioritätsverarbeitung (`service_tier = "priority"`) zu. Vorhandene `service_tier`-Werte bleiben erhalten, und der Schnellmodus schreibt weder `reasoning` noch `text.verbosity` um.
```json5
{
@ -813,13 +790,13 @@ das Server-seitige Compaction-Accordion unten.
```
<Note>
Sitzungsüberschreibungen haben Vorrang vor der Konfiguration. Das Löschen der Sitzungsüberschreibung in der Sessions-UI setzt die Sitzung auf den konfigurierten Standard zurück.
Sitzungsüberschreibungen haben Vorrang vor der Konfiguration. Wenn Sie die Sitzungsüberschreibung in der Sessions UI löschen, kehrt die Sitzung zum konfigurierten Standard zurück.
</Note>
</Accordion>
<Accordion title="Prioritätsverarbeitung (service_tier)">
Die OpenAI-API stellt Prioritätsverarbeitung über `service_tier` bereit. Legen Sie sie in OpenClaw pro Modell fest:
Die API von OpenAI stellt Prioritätsverarbeitung über `service_tier` bereit. Legen Sie sie in OpenClaw pro Modell fest:
```json5
{
@ -836,7 +813,7 @@ das Server-seitige Compaction-Accordion unten.
Unterstützte Werte: `auto`, `default`, `flex`, `priority`.
<Warning>
`serviceTier` wird nur an native OpenAI-Endpunkte (`api.openai.com`) und native Codex-Endpunkte (`chatgpt.com/backend-api`) weitergeleitet. Wenn Sie einen der beiden Provider über einen Proxy routen, lässt OpenClaw `service_tier` unverändert.
`serviceTier` wird nur an native OpenAI-Endpunkte (`api.openai.com`) und native Codex-Endpunkte (`chatgpt.com/backend-api`) weitergeleitet. Wenn Sie einen der Provider über einen Proxy leiten, lässt OpenClaw `service_tier` unverändert.
</Warning>
</Accordion>
@ -846,7 +823,7 @@ das Server-seitige Compaction-Accordion unten.
- Erzwingt `store: true` (außer die Modellkompatibilität setzt `supportsStore: false`)
- Fügt `context_management: [{ type: "compaction", compact_threshold: ... }]` ein
- Standardwert für `compact_threshold`: 70% von `contextWindow` (oder `80000`, wenn nicht verfügbar)
- Standard-`compact_threshold`: 70 % von `contextWindow` (oder `80000`, wenn nicht verfügbar)
Dies gilt für den integrierten Pi-Harness-Pfad und für OpenAI-Provider-Hooks, die von eingebetteten Ausführungen verwendet werden. Der native Codex-App-Server-Harness verwaltet seinen eigenen Kontext über Codex und wird separat mit `agents.defaults.agentRuntime.id` konfiguriert.
@ -904,12 +881,12 @@ das Server-seitige Compaction-Accordion unten.
</Tabs>
<Note>
`responsesServerCompaction` steuert nur das Einfügen von `context_management`. Direkte OpenAI-Responses-Modelle erzwingen weiterhin `store: true`, außer die Kompatibilität setzt `supportsStore: false`.
`responsesServerCompaction` steuert nur die Einfügung von `context_management`. Direkte OpenAI-Responses-Modelle erzwingen weiterhin `store: true`, außer die Kompatibilität setzt `supportsStore: false`.
</Note>
</Accordion>
<Accordion title="Strikter agentischer GPT-Modus">
<Accordion title="Strict-agentic-GPT-Modus">
Für Ausführungen der GPT-5-Familie auf `openai/*` kann OpenClaw einen strengeren eingebetteten Ausführungsvertrag verwenden:
```json5
@ -925,8 +902,8 @@ das Server-seitige Compaction-Accordion unten.
Mit `strict-agentic`:
- Behandelt OpenClaw eine reine Planungsrunde nicht mehr als erfolgreichen Fortschritt, wenn eine Tool-Aktion verfügbar ist
- Wiederholt OpenClaw die Runde mit einer Aufforderung zum sofortigen Handeln
- Aktiviert OpenClaw `update_plan` automatisch für umfangreiche Arbeiten
- Zeigt OpenClaw einen expliziten blockierten Zustand an, wenn das Modell weiterhin plant, ohne zu handeln
- Aktiviert OpenClaw bei umfangreicher Arbeit automatisch `update_plan`
- Zeigt OpenClaw einen expliziten blockierten Zustand an, wenn das Modell weiter plant, ohne zu handeln
<Note>
Nur auf Ausführungen der OpenAI- und Codex-GPT-5-Familie beschränkt. Andere Provider und ältere Modellfamilien behalten das Standardverhalten bei.
@ -934,41 +911,41 @@ das Server-seitige Compaction-Accordion unten.
</Accordion>
<Accordion title="Native im Vergleich zu OpenAI-kompatiblen Routen">
<Accordion title="Native vs. OpenAI-kompatible Routen">
OpenClaw behandelt direkte OpenAI-, Codex- und Azure-OpenAI-Endpunkte anders als generische OpenAI-kompatible `/v1`-Proxys:
**Native Routen** (`openai/*`, Azure OpenAI):
- Behalten `reasoning: { effort: "none" }` nur für Modelle bei, die den OpenAI-Aufwand `none` unterstützen
- Behalten `reasoning: { effort: "none" }` nur für Modelle bei, die den OpenAI-`none`-Aufwand unterstützen
- Lassen deaktiviertes Reasoning für Modelle oder Proxys weg, die `reasoning.effort: "none"` ablehnen
- Setzen Tool-Schemas standardmäßig auf den strikten Modus
- Hängen versteckte Attributions-Header nur auf verifizierten nativen Hosts an
- Behalten OpenAI-spezifische Anfrageformung (`service_tier`, `store`, Reasoning-Kompatibilität, Prompt-Cache-Hinweise) bei
- Hängen versteckte Zuordnungs-Header nur bei verifizierten nativen Hosts an
- Behalten OpenAI-spezifische Anfrageformung bei (`service_tier`, `store`, Reasoning-Kompatibilität, Prompt-Cache-Hinweise)
**Proxy-/kompatible Routen:**
- Verwenden lockeres Kompatibilitätsverhalten
- Entfernen Completions-`store` aus nicht-nativen `openai-completions`-Payloads
- Verwenden lockereres Kompatibilitätsverhalten
- Entfernen Completions-`store` aus nicht nativen `openai-completions`-Payloads
- Akzeptieren erweitertes `params.extra_body`/`params.extraBody`-Pass-through-JSON für OpenAI-kompatible Completions-Proxys
- Akzeptieren `params.chat_template_kwargs` für OpenAI-kompatible Completions-Proxys wie vLLM
- Erzwingen keine strikten Tool-Schemas oder nur nativen Routen vorbehaltene Header
- Erzwingen keine strikten Tool-Schemas oder nur nativen Routen vorbehaltenen Header
Azure OpenAI verwendet nativen Transport und Kompatibilitätsverhalten, erhält jedoch keine versteckten Attributions-Header.
Azure OpenAI verwendet nativen Transport und Kompatibilitätsverhalten, erhält aber keine versteckten Zuordnungs-Header.
</Accordion>
</AccordionGroup>
## Verwandt
## Verwandte Themen
<CardGroup cols={2}>
<Card title="Modellauswahl" href="/de/concepts/model-providers" icon="layers">
Auswahl von Providern, Modellreferenzen und Failover-Verhalten.
</Card>
<Card title="Bildgenerierung" href="/de/tools/image-generation" icon="image">
Gemeinsame Bild-Tool-Parameter und Providerauswahl.
Gemeinsame Bild-Tool-Parameter und Provider-Auswahl.
</Card>
<Card title="Videogenerierung" href="/de/tools/video-generation" icon="video">
Gemeinsame Video-Tool-Parameter und Providerauswahl.
Gemeinsame Video-Tool-Parameter und Provider-Auswahl.
</Card>
<Card title="OAuth und Authentifizierung" href="/de/gateway/authentication" icon="key">
Authentifizierungsdetails und Regeln zur Wiederverwendung von Anmeldedaten.
Authentifizierungsdetails und Regeln zur Wiederverwendung von Zugangsdaten.
</Card>
</CardGroup>

42
docs/de/tools/brave-search.md
View File

@ -1,26 +1,24 @@
---
read_when:
- Sie möchten Brave Search für web_search verwenden
- Sie benötigen einen BRAVE_API_KEY oder Details zum Plan
- Sie benötigen einen BRAVE_API_KEY oder Plandetails
summary: Einrichtung der Brave Search API für web_search
title: Brave-Suche
x-i18n:
generated_at: "2026-05-02T21:03:36Z"
generated_at: "2026-05-06T09:04:25Z"
model: gpt-5.5
provider: openai
source_hash: b1ecb9e3e5475bb26f4058311429b558f49cdd1df907a622f93f297ac6569d65
source_hash: d2bff7589ddb54d002853898c6fc37e613fd32b0fa69cb0d712d5955973efb39
source_path: tools/brave-search.md
workflow: 16
---
# Brave Search API
OpenClaw unterstützt die Brave Search API als `web_search`-Provider.
## API-Schlüssel erhalten
## API-Schlüssel abrufen
1. Erstellen Sie ein Brave Search API-Konto unter [https://brave.com/search/api/](https://brave.com/search/api/)
2. Wählen Sie im Dashboard den **Search**-Tarif aus und generieren Sie einen API-Schlüssel.
2. Wählen Sie im Dashboard den **Search**-Plan aus und generieren Sie einen API-Schlüssel.
3. Speichern Sie den Schlüssel in der Konfiguration oder setzen Sie `BRAVE_API_KEY` in der Gateway-Umgebung.
## Konfigurationsbeispiel
@ -52,18 +50,18 @@ OpenClaw unterstützt die Brave Search API als `web_search`-Provider.
}
```
Provider-spezifische Brave-Sucheinstellungen liegen jetzt unter `plugins.entries.brave.config.webSearch.*`.
Das Legacy-`tools.web.search.apiKey` wird weiterhin über die Kompatibilitätsschicht geladen, ist aber nicht mehr der kanonische Konfigurationspfad.
Brave-spezifische Sucheinstellungen des Providers befinden sich jetzt unter `plugins.entries.brave.config.webSearch.*`.
Das veraltete `tools.web.search.apiKey` wird weiterhin über den Kompatibilitäts-Shim geladen, ist aber nicht mehr der kanonische Konfigurationspfad.
`webSearch.mode` steuert den Brave-Transport:
- `web` (Standard): normale Brave-Websuche mit Titeln, URLs und Snippets
- `llm-context`: Brave LLM Context API mit vorab extrahierten Text-Chunks und Quellen für Grounding
- `llm-context`: Brave LLM Context API mit vorab extrahierten Textabschnitten und Quellen für Grounding
`webSearch.baseUrl` kann Brave-Anfragen an einen vertrauenswürdigen Brave-kompatiblen Proxy
oder ein Gateway leiten. OpenClaw hängt `/res/v1/web/search` oder `/res/v1/llm/context` an
die konfigurierte Basis-URL an und behält die Basis-URL im Cache-Schlüssel bei. Öffentliche
Endpunkte müssen `https://` verwenden; `http://` wird nur für vertrauenswürdige local loopback-
Endpunkte müssen `https://` verwenden; `http://` wird nur für vertrauenswürdige Loopback-
oder Private-Network-Proxy-Hosts akzeptiert.
## Tool-Parameter
@ -73,11 +71,11 @@ Suchanfrage.
</ParamField>
<ParamField path="count" type="number" default="5">
Anzahl der zurückzugebenden Ergebnisse (1-10).
Anzahl der zurückzugebenden Ergebnisse (1–10).
</ParamField>
<ParamField path="country" type="string">
ISO-Ländercode mit 2 Buchstaben (z. B. `US`, `DE`).
2-stelliger ISO-Ländercode (z. B. `US`, `DE`).
</ParamField>
<ParamField path="language" type="string">
@ -93,7 +91,7 @@ ISO-Sprachcode für UI-Elemente.
</ParamField>
<ParamField path="freshness" type="'day' | 'week' | 'month' | 'year'">
Zeitfilter - `day` entspricht 24 Stunden.
Zeitfilter — `day` entspricht 24 Stunden.
</ParamField>
<ParamField path="date_after" type="string">
@ -130,19 +128,19 @@ await web_search({
## Hinweise
- OpenClaw verwendet den Brave-**Search**-Tarif. Wenn Sie ein Legacy-Abonnement haben (z. B. den ursprünglichen Free-Tarif mit 2.000 Abfragen/Monat), bleibt es gültig, enthält aber keine neueren Funktionen wie LLM Context oder höhere Ratenlimits.
- Jeder Brave-Tarif enthält **\$5/Monat kostenloses Guthaben** (erneuernd). Der Search-Tarif kostet \$5 pro 1.000 Anfragen, sodass das Guthaben 1.000 Abfragen/Monat abdeckt. Legen Sie Ihr Nutzungslimit im Brave-Dashboard fest, um unerwartete Kosten zu vermeiden. Aktuelle Tarife finden Sie im [Brave API-Portal](https://brave.com/search/api/).
- Der Search-Tarif enthält den LLM Context-Endpunkt und Rechte für KI-Inferenz. Das Speichern von Ergebnissen zum Trainieren oder Abstimmen von Modellen erfordert einen Tarif mit ausdrücklichen Speicherrechten. Siehe die Brave-[Nutzungsbedingungen](https://api-dashboard.search.brave.com/terms-of-service).
- Der Modus `llm-context` gibt Grounding-Quelleneinträge statt der normalen Websuche-Snippet-Struktur zurück.
- Der Modus `llm-context` unterstützt `freshness` und begrenzte Bereiche mit `date_after` + `date_before`. Er unterstützt `ui_lang` nicht; `date_before` ohne `date_after` wird abgelehnt, weil Brave für benutzerdefinierte Aktualitätsbereiche sowohl Start- als auch Enddatum verlangt.
- OpenClaw verwendet den Brave-**Search**-Plan. Wenn Sie ein älteres Abonnement haben (z. B. den ursprünglichen kostenlosen Plan mit 2.000 Abfragen/Monat), bleibt es gültig, enthält aber keine neueren Funktionen wie LLM Context oder höhere Ratenlimits.
- Jeder Brave-Plan enthält **\$5/Monat kostenloses Guthaben** (erneuernd). Der Search-Plan kostet \$5 pro 1.000 Anfragen, sodass das Guthaben 1.000 Abfragen/Monat abdeckt. Legen Sie im Brave-Dashboard Ihr Nutzungslimit fest, um unerwartete Kosten zu vermeiden. Aktuelle Pläne finden Sie im [Brave API-Portal](https://brave.com/search/api/).
- Der Search-Plan enthält den LLM Context-Endpunkt und Rechte für KI-Inferenz. Das Speichern von Ergebnissen zum Trainieren oder Optimieren von Modellen erfordert einen Plan mit ausdrücklichen Speicherrechten. Siehe die Brave-[Nutzungsbedingungen](https://api-dashboard.search.brave.com/terms-of-service).
- Der Modus `llm-context` gibt geerdete Quelleneinträge statt der normalen Snippet-Struktur der Websuche zurück.
- Der Modus `llm-context` unterstützt `freshness` und begrenzte Bereiche mit `date_after` + `date_before`. Er unterstützt `ui_lang` nicht; `date_before` ohne `date_after` wird abgelehnt, da Brave für benutzerdefinierte Freshness-Bereiche sowohl Start- als auch Enddatum verlangt.
- `ui_lang` muss ein Regions-Subtag wie `en-US` enthalten.
- Ergebnisse werden standardmäßig 15 Minuten lang zwischengespeichert (konfigurierbar über `cacheTtlMinutes`).
- Benutzerdefinierte `webSearch.baseUrl`-Werte werden in die Brave-Cache-Identität einbezogen, sodass
Proxy-spezifische Antworten nicht kollidieren.
- Aktivieren Sie das Diagnose-Flag `brave.http`, um beim Troubleshooting Brave-Anfrage-URLs/Abfrageparameter, Antwortstatus/-Timing und Search-Cache-Hit/Miss/Write-Ereignisse zu protokollieren. Das Flag protokolliert niemals den API-Schlüssel oder Antworttexte, Suchanfragen können jedoch sensibel sein.
proxy-spezifische Antworten nicht kollidieren.
- Aktivieren Sie das Diagnose-Flag `brave.http`, um bei der Fehlerbehebung Brave-Anfrage-URLs/Abfrageparameter, Antwortstatus/-Timing sowie Treffer/Fehlschläge/Schreibereignisse des Such-Caches zu protokollieren. Das Flag protokolliert niemals den API-Schlüssel oder Antwortkörper, Suchanfragen können jedoch sensibel sein.
## Verwandte Themen
- [Websuche-Übersicht](/de/tools/web) -- alle Provider und automatische Erkennung
- [Web Search-Übersicht](/de/tools/web) -- alle Provider und automatische Erkennung
- [Perplexity Search](/de/tools/perplexity-search) -- strukturierte Ergebnisse mit Domain-Filterung
- [Exa Search](/de/tools/exa-search) -- neuronale Suche mit Inhaltsextraktion

468
docs/de/tools/plugin.md
View File

@ -7,27 +7,27 @@ sidebarTitle: Install and Configure
summary: OpenClaw-Plugins installieren, konfigurieren und verwalten
title: Plugins
x-i18n:
generated_at: "2026-05-06T07:07:11Z"
generated_at: "2026-05-06T09:04:54Z"
model: gpt-5.5
provider: openai
source_hash: 118c856507965f496d87edc1fef8cb67d36c7ef62acc84d5ad130ffd3a3f5568
source_hash: 0d68ad3cbd040d3f973d219cf273a792f11df382f6c4ccbf80c07acb0d26c658
source_path: tools/plugin.md
workflow: 16
---
Plugins erweitern OpenClaw um neue Funktionen: Kanäle, Modell-Provider,
Agent-Harnesses, Werkzeuge, Skills, Sprache, Echtzeittranskription, Echtzeit-
Voice, Medienverständnis, Bildgenerierung, Videogenerierung, Web-Abruf, Websuche
und mehr. Einige Plugins sind **Kern-Plugins** (mit OpenClaw ausgeliefert), andere
sind **extern**. Die meisten externen Plugins werden über
[ClawHub](/de/tools/clawhub) veröffentlicht und entdeckt. Npm bleibt für direkte Installationen und für eine
temporäre Gruppe von OpenClaw-eigenen Plugin-Paketen unterstützt, während diese
Migration abgeschlossen wird.
Agent-Harnesses, Werkzeuge, Skills, Sprache, Echtzeit-Transkription,
Echtzeit-Sprache, Medienverständnis, Bildgenerierung, Videogenerierung,
Web-Abruf, Websuche und mehr. Einige Plugins sind **core** (werden mit
OpenClaw ausgeliefert), andere sind **extern**. Die meisten externen Plugins
werden über [ClawHub](/de/tools/clawhub) veröffentlicht und gefunden. Npm bleibt
für Direktinstallationen und für eine temporäre Reihe OpenClaw-eigener
Plugin-Pakete unterstützt, solange diese Migration abgeschlossen wird.
## Schnellstart
Beispiele zum Kopieren und Einfügen für Installation, Auflisten, Deinstallation,
Aktualisierung und Veröffentlichung finden Sie unter
Beispiele zum Kopieren und Einfügen für Installation, Auflisten,
Deinstallation, Aktualisierung und Veröffentlichung finden Sie unter
[Plugins verwalten](/de/plugins/manage-plugins).
<Steps>
@ -47,6 +47,7 @@ Aktualisierung und Veröffentlichung finden Sie unter
# From npm
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz
# From git
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
@ -68,12 +69,13 @@ Aktualisierung und Veröffentlichung finden Sie unter
</Step>
<Step title="Chat-native Verwaltung">
In einem laufenden Gateway lösen nur für Owner verfügbare `/plugins enable` und `/plugins disable`
den Konfigurations-Neulader des Gateway aus. Das Gateway lädt Plugin-Laufzeitoberflächen
im Prozess neu, und neue Agent-Turns bauen ihre Werkzeugliste aus der
aktualisierten Registry neu auf. `/plugins install` ändert Plugin-Quellcode, daher fordert das
Gateway stattdessen einen Neustart an, anstatt vorzutäuschen, der aktuelle Prozess könne
bereits importierte Module sicher neu laden.
In einem laufenden Gateway lösen die nur für Besitzer verfügbaren Befehle
`/plugins enable` und `/plugins disable` den Gateway-Konfigurations-Reloader
aus. Das Gateway lädt Plugin-Runtime-Oberflächen im Prozess neu, und neue
Agent-Durchläufe bauen ihre Werkzeugliste aus der aktualisierten Registry
neu auf. `/plugins install` ändert Plugin-Quellcode, daher fordert das
Gateway stattdessen einen Neustart an, anstatt so zu tun, als könne der
aktuelle Prozess bereits importierte Module sicher neu laden.
</Step>
@ -85,9 +87,10 @@ Aktualisierung und Veröffentlichung finden Sie unter
openclaw <plugin-command> --help
```
Verwenden Sie `--runtime`, wenn Sie registrierte Werkzeuge, Dienste, Gateway-
Methoden, Hooks oder Plugin-eigene CLI-Befehle nachweisen müssen. Einfaches
`inspect` ist eine kalte Manifest-/Registry-Prüfung und vermeidet absichtlich den Import der Plugin-Laufzeit.
Verwenden Sie `--runtime`, wenn Sie registrierte Werkzeuge, Dienste,
Gateway-Methoden, Hooks oder Plugin-eigene CLI-Befehle nachweisen müssen.
Einfaches `inspect` ist eine kalte Manifest-/Registry-Prüfung und vermeidet
absichtlich den Import der Plugin-Runtime.
</Step>
</Steps>
@ -100,119 +103,139 @@ Wenn Sie chat-native Steuerung bevorzugen, aktivieren Sie `commands.plugins: tru
/plugin enable <plugin-id>
```
Der Installationspfad verwendet denselben Resolver wie die CLI: lokaler Pfad/Archiv, explizites
`clawhub:<pkg>`, explizites `npm:<pkg>`, explizites `git:<repo>` oder eine einfache Paket-
Spezifikation über npm.
Der Installationspfad verwendet denselben Resolver wie die CLI: lokaler
Pfad/Archiv, explizites `clawhub:<pkg>`, explizites `npm:<pkg>`, explizites
`npm-pack:<path.tgz>`, explizites `git:<repo>` oder eine einfache
Paketspezifikation über npm.
Wenn die Konfiguration ungültig ist, schlägt die Installation normalerweise geschlossen fehl und verweist Sie auf
`openclaw doctor --fix`. Die einzige Wiederherstellungsausnahme ist ein enger Neuinstallationspfad
für gebündelte Plugins, die sich für
`openclaw.install.allowInvalidConfigRecovery` anmelden.
Während des Gateway-Starts schlägt ungültige Plugin-Konfiguration geschlossen fehl wie jede andere ungültige
Konfiguration. Führen Sie `openclaw doctor --fix` aus, um die fehlerhafte Plugin-Konfiguration zu quarantänisieren, indem
der betreffende Plugin-Eintrag deaktiviert und dessen ungültiger Konfigurations-Payload entfernt wird; das normale
Konfigurations-Backup behält die vorherigen Werte.
Wenn eine Kanalkonfiguration auf ein Plugin verweist, das nicht mehr auffindbar ist, dieselbe
veraltete Plugin-ID aber in der Plugin-Konfiguration oder in Installationsdatensätzen verbleibt, protokolliert der Gateway-Start
Warnungen und überspringt diesen Kanal, anstatt jeden anderen Kanal zu blockieren.
Führen Sie `openclaw doctor --fix` aus, um die veralteten Kanal-/Plugin-Einträge zu entfernen; unbekannte
Kanalschlüssel ohne Hinweise auf veraltete Plugins schlagen weiterhin bei der Validierung fehl, damit Tippfehler
sichtbar bleiben.
Wenn `plugins.enabled: false` gesetzt ist, werden veraltete Plugin-Verweise als inaktiv behandelt:
Der Gateway-Start überspringt Plugin-Erkennung/-Laden, und `openclaw doctor` behält
die deaktivierte Plugin-Konfiguration bei, anstatt sie automatisch zu entfernen. Aktivieren Sie Plugins erneut, bevor
Sie die doctor-Bereinigung ausführen, wenn veraltete Plugin-IDs entfernt werden sollen.
Wenn die Konfiguration ungültig ist, schlägt die Installation normalerweise
geschlossen fehl und verweist Sie auf `openclaw doctor --fix`. Die einzige
Wiederherstellungsausnahme ist ein enger Neuinstallationspfad für gebündelte
Plugins, die sich für `openclaw.install.allowInvalidConfigRecovery` entscheiden.
Während des Gateway-Starts schlägt eine ungültige Plugin-Konfiguration wie jede
andere ungültige Konfiguration geschlossen fehl. Führen Sie
`openclaw doctor --fix` aus, um die fehlerhafte Plugin-Konfiguration zu
isolieren, indem dieser Plugin-Eintrag deaktiviert und seine ungültige
Konfigurationsnutzlast entfernt wird; das normale Konfigurations-Backup behält
die vorherigen Werte.
Wenn eine Kanalkonfiguration auf ein Plugin verweist, das nicht mehr auffindbar
ist, aber dieselbe veraltete Plugin-ID weiterhin in der Plugin-Konfiguration
oder in Installationsdatensätzen vorhanden ist, protokolliert der Gateway-Start
Warnungen und überspringt diesen Kanal, anstatt alle anderen Kanäle zu
blockieren. Führen Sie `openclaw doctor --fix` aus, um die veralteten
Kanal-/Plugin-Einträge zu entfernen; unbekannte Kanalschlüssel ohne Hinweise
auf veraltete Plugins schlagen weiterhin bei der Validierung fehl, damit
Tippfehler sichtbar bleiben.
Wenn `plugins.enabled: false` gesetzt ist, werden veraltete Plugin-Verweise als
inert behandelt: Der Gateway-Start überspringt Plugin-Erkennungs-/Ladearbeiten,
und `openclaw doctor` bewahrt die deaktivierte Plugin-Konfiguration, anstatt
sie automatisch zu entfernen. Aktivieren Sie Plugins wieder, bevor Sie die
doctor-Bereinigung ausführen, wenn veraltete Plugin-IDs entfernt werden sollen.
Die Installation von Plugin-Abhängigkeiten erfolgt nur während expliziter Installations-/Update- oder
doctor-Reparaturabläufe. Gateway-Start, Konfigurationsneuladen und Laufzeitinspektion führen
keine Paketmanager aus und reparieren keine Abhängigkeitsbäume. Lokale Plugins müssen ihre
Abhängigkeiten bereits installiert haben, während npm-, git- und ClawHub-Plugins
unter den von OpenClaw verwalteten Plugin-Roots installiert werden. npm-Abhängigkeiten können
innerhalb des von OpenClaw verwalteten npm-Roots gehoistet werden; Install/Update durchsucht diesen verwalteten Root vor
der Vertrauensentscheidung, und Uninstall entfernt npm-verwaltete Pakete über npm. Externe Plugins
und benutzerdefinierte Ladepfade müssen weiterhin über `openclaw plugins install` installiert werden.
Verwenden Sie `openclaw plugins list --json`, um den statischen `dependencyStatus` für jedes
sichtbare Plugin zu sehen, ohne Laufzeitcode zu importieren oder Abhängigkeiten zu reparieren.
Siehe [Plugin-Abhängigkeitsauflösung](/de/plugins/dependency-resolution) für den
Die Installation von Plugin-Abhängigkeiten erfolgt nur während expliziter
Installations-/Aktualisierungs- oder doctor-Reparaturabläufe. Gateway-Start,
Konfigurations-Reload und Runtime-Inspektion führen keine Paketmanager aus und
reparieren keine Abhängigkeitsbäume. Bei lokalen Plugins müssen die
Abhängigkeiten bereits installiert sein, während npm-, git- und ClawHub-Plugins
unter den verwalteten Plugin-Roots von OpenClaw installiert werden.
npm-Abhängigkeiten können innerhalb des verwalteten npm-Roots von OpenClaw
gehoistet werden; Installieren/Aktualisieren scannt diesen verwalteten Root vor
dem Vertrauen, und Deinstallieren entfernt npm-verwaltete Pakete über npm.
Externe Plugins und benutzerdefinierte Ladepfade müssen weiterhin über
`openclaw plugins install` installiert werden. Verwenden Sie
`openclaw plugins list --json`, um den statischen `dependencyStatus` für jedes
sichtbare Plugin anzuzeigen, ohne Runtime-Code zu importieren oder
Abhängigkeiten zu reparieren. Siehe
[Auflösung von Plugin-Abhängigkeiten](/de/plugins/dependency-resolution) für den
Installationszeit-Lebenszyklus.
### Blockierte Plugin-Pfad-Ownership
### Blockierte Plugin-Pfad-Eigentümerschaft
Wenn die Plugin-Diagnose
Wenn Plugin-Diagnosen
`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
meldet und die Konfigurationsvalidierung mit `plugin present but blocked` folgt, hat OpenClaw
Plugin-Dateien gefunden, die einem anderen Unix-Benutzer gehören als dem Prozess, der sie lädt.
Behalten Sie die Plugin-Konfiguration bei; beheben Sie die Dateisystem-Ownership oder führen Sie
OpenClaw als denselben Benutzer aus, dem das State-Verzeichnis gehört.
melden und daraufhin die Konfigurationsvalidierung mit `plugin present but blocked`
folgt, hat OpenClaw Plugin-Dateien gefunden, deren Eigentümer ein anderer
Unix-Benutzer ist als der Prozess, der sie lädt. Lassen Sie die
Plugin-Konfiguration bestehen; korrigieren Sie die Dateisystem-Eigentümerschaft
oder führen Sie OpenClaw als denselben Benutzer aus, dem das Zustandsverzeichnis
gehört.
Bei Docker-Installationen läuft das offizielle Image als `node` (uid `1000`), daher sollten die
hostseitig bind-gemounteten OpenClaw-Konfigurations- und Workspace-Verzeichnisse normalerweise
uid `1000` gehören:
Bei Docker-Installationen läuft das offizielle Image als `node` (uid `1000`),
daher sollten die per Bind-Mount vom Host eingebundenen OpenClaw-Konfigurations-
und Arbeitsbereichsverzeichnisse normalerweise uid `1000` gehören:
```bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
```
Wenn Sie OpenClaw absichtlich als root ausführen, reparieren Sie stattdessen den verwalteten Plugin-Root auf
root-Ownership:
Wenn Sie OpenClaw absichtlich als root ausführen, reparieren Sie stattdessen
den verwalteten Plugin-Root auf root-Eigentümerschaft:
```bash
sudo chown -R root:root /path/to/openclaw-config/npm
```
Nachdem Sie die Ownership behoben haben, führen Sie erneut `openclaw doctor --fix` oder
`openclaw plugins registry --refresh` aus, damit die persistierte Plugin-Registry zu
den reparierten Dateien passt.
Nach der Korrektur der Eigentümerschaft führen Sie erneut
`openclaw doctor --fix` oder `openclaw plugins registry --refresh` aus, damit
die persistierte Plugin-Registry zu den reparierten Dateien passt.
Bei npm-Installationen werden veränderliche Selektoren wie `latest` oder ein dist-tag
vor der Installation aufgelöst und anschließend auf die exakt verifizierte Version im von OpenClaw
verwalteten npm-Root gepinnt. Nachdem npm abgeschlossen ist, verifiziert OpenClaw, dass der installierte
`package-lock.json`-Eintrag weiterhin der aufgelösten Version und Integrität entspricht. Wenn
npm andere Paketmetadaten schreibt, schlägt die Installation fehl und das verwaltete Paket
wird zurückgerollt, anstatt ein anderes Plugin-Artefakt zu akzeptieren.
Bei npm-Installationen werden veränderliche Selektoren wie `latest` oder ein
dist-tag vor der Installation aufgelöst und dann im verwalteten npm-Root von
OpenClaw an die exakt verifizierte Version gepinnt. Nachdem npm abgeschlossen
ist, verifiziert OpenClaw, dass der installierte `package-lock.json`-Eintrag
weiterhin der aufgelösten Version und Integrität entspricht. Wenn npm andere
Paketmetadaten schreibt, schlägt die Installation fehl und das verwaltete Paket
wird zurückgesetzt, anstatt ein anderes Plugin-Artefakt zu akzeptieren.
Quell-Checkouts sind pnpm-Workspaces. Wenn Sie OpenClaw klonen, um an gebündelten
Plugins zu arbeiten, führen Sie `pnpm install` aus; OpenClaw lädt gebündelte Plugins dann aus
`extensions/<id>`, sodass Änderungen und paketlokale Abhängigkeiten direkt verwendet werden.
Einfache npm-Root-Installationen sind für paketiertes OpenClaw vorgesehen, nicht für die Entwicklung mit
Quell-Checkouts.
Quell-Checkouts sind pnpm-Workspaces. Wenn Sie OpenClaw klonen, um an
gebündelten Plugins zu arbeiten, führen Sie `pnpm install` aus; OpenClaw lädt
gebündelte Plugins dann aus `extensions/<id>`, sodass Änderungen und
paketlokale Abhängigkeiten direkt verwendet werden. Einfache npm-Root-
Installationen sind für paketiertes OpenClaw gedacht, nicht für die Entwicklung
in Quell-Checkouts.
## Plugin-Typen
OpenClaw erkennt zwei Plugin-Formate:
| Format | Funktionsweise | Beispiele |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Nativ** | `openclaw.plugin.json` + Laufzeitmodul; wird im Prozess ausgeführt | Offizielle Plugins, Community-npm-Pakete |
| Format | Funktionsweise | Beispiele |
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + Runtime-Modul; wird im Prozess ausgeführt | Offizielle Plugins, Community-npm-Pakete |
| **Bundle** | Codex-/Claude-/Cursor-kompatibles Layout; wird auf OpenClaw-Funktionen abgebildet | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Beide erscheinen unter `openclaw plugins list`. Details zu Bundles finden Sie unter [Plugin Bundles](/de/plugins/bundles).
Beide erscheinen unter `openclaw plugins list`. Details zu Bundles finden Sie unter [Plugin-Bundles](/de/plugins/bundles).
Wenn Sie ein natives Plugin schreiben, beginnen Sie mit [Plugins erstellen](/de/plugins/building-plugins)
und der [Plugin SDK Overview](/de/plugins/sdk-overview).
und der [Plugin-SDK-Übersicht](/de/plugins/sdk-overview).
## Paket-Einstiegspunkte
Native Plugin-npm-Pakete müssen `openclaw.extensions` in `package.json` deklarieren.
Jeder Eintrag muss innerhalb des Paketverzeichnisses bleiben und auf eine lesbare
Laufzeitdatei auflösen oder auf eine TypeScript-Quelldatei mit einem abgeleiteten gebauten JavaScript-
Peer wie `src/index.ts` zu `dist/index.js`.
Paketierte Installationen müssen diese JavaScript-Laufzeitausgabe mitliefern. Der TypeScript-
Quellfallback ist für Quell-Checkouts und lokale Entwicklungspfade vorgesehen, nicht für
npm-Pakete, die in OpenClaws verwalteten Plugin-Root installiert werden.
Native Plugin-npm-Pakete müssen `openclaw.extensions` in `package.json`
deklarieren. Jeder Eintrag muss innerhalb des Paketverzeichnisses bleiben und
zu einer lesbaren Runtime-Datei auflösen oder zu einer TypeScript-Quelldatei
mit einem abgeleiteten gebauten JavaScript-Gegenstück wie `src/index.ts` zu
`dist/index.js`.
Paketierte Installationen müssen diese JavaScript-Runtime-Ausgabe mitliefern.
Der TypeScript-Quell-Fallback ist für Quell-Checkouts und lokale
Entwicklungspfade gedacht, nicht für npm-Pakete, die in OpenClaws verwalteten
Plugin-Root installiert werden.
Wenn eine Warnung für verwaltete Pakete sagt, dass sie `requires compiled runtime output for
TypeScript entry ...`, wurde das Paket ohne die JavaScript-Dateien veröffentlicht, die
OpenClaw zur Laufzeit benötigt. Das ist ein Problem der Plugin-Paketierung, kein lokales Konfigurations-
problem. Aktualisieren oder installieren Sie das Plugin erneut, nachdem der Publisher kompiliertes
JavaScript erneut veröffentlicht hat, oder deaktivieren/deinstallieren Sie dieses Plugin, bis ein behobenes Paket verfügbar ist.
Wenn eine Warnung zu verwalteten Paketen meldet, dass es
`requires compiled runtime output for TypeScript entry ...`, wurde das Paket
ohne die JavaScript-Dateien veröffentlicht, die OpenClaw zur Laufzeit benötigt.
Das ist ein Plugin-Paketierungsproblem, kein lokales Konfigurationsproblem.
Aktualisieren oder installieren Sie das Plugin neu, nachdem der Publisher
kompiliertes JavaScript erneut veröffentlicht hat, oder deaktivieren/
deinstallieren Sie dieses Plugin, bis ein korrigiertes Paket verfügbar ist.
Verwenden Sie `openclaw.runtimeExtensions`, wenn veröffentlichte Laufzeitdateien nicht unter denselben
Pfaden liegen wie die Quelleinträge. Wenn vorhanden, muss `runtimeExtensions` genau
einen Eintrag für jeden `extensions`-Eintrag enthalten. Nicht übereinstimmende Listen lassen Installation und
Plugin-Erkennung fehlschlagen, anstatt stillschweigend auf Quellpfade zurückzufallen. Wenn Sie außerdem
`openclaw.setupEntry` veröffentlichen, verwenden Sie `openclaw.runtimeSetupEntry` für dessen gebauten
JavaScript-Peer; diese Datei ist erforderlich, wenn sie deklariert wird.
Verwenden Sie `openclaw.runtimeExtensions`, wenn veröffentlichte
Runtime-Dateien nicht an denselben Pfaden wie die Quelleinträge liegen. Wenn
vorhanden, muss `runtimeExtensions` genau einen Eintrag für jeden
`extensions`-Eintrag enthalten. Nicht übereinstimmende Listen lassen
Installation und Plugin-Erkennung fehlschlagen, anstatt stillschweigend auf
Quellpfade zurückzufallen. Wenn Sie außerdem `openclaw.setupEntry`
veröffentlichen, verwenden Sie `openclaw.runtimeSetupEntry` für dessen gebautes
JavaScript-Gegenstück; diese Datei ist erforderlich, wenn sie deklariert wird.
```json
{
@ -228,17 +251,19 @@ JavaScript-Peer; diese Datei ist erforderlich, wenn sie deklariert wird.
### OpenClaw-eigene npm-Pakete während der Migration
ClawHub ist der primäre Distributionspfad für die meisten Plugins. Aktuelle paketierte
OpenClaw-Releases bündeln bereits viele offizielle Plugins, daher benötigen diese in normalen Setups
keine separaten npm-Installationen. Bis jedes OpenClaw-eigene Plugin
zu ClawHub migriert ist, liefert OpenClaw weiterhin einige `@openclaw/*`-Plugin-Pakete auf
npm für ältere/benutzerdefinierte Installationen und direkte npm-Workflows aus.
ClawHub ist der primäre Distributionspfad für die meisten Plugins. Aktuelle
paketierte OpenClaw-Releases bündeln bereits viele offizielle Plugins, sodass
diese in normalen Setups keine separaten npm-Installationen benötigen. Bis
jedes OpenClaw-eigene Plugin zu ClawHub migriert ist, liefert OpenClaw weiterhin
einige `@openclaw/*`-Plugin-Pakete auf npm für ältere/benutzerdefinierte
Installationen und direkte npm-Workflows aus.
Wenn npm ein `@openclaw/*`-Plugin-Paket als deprecated meldet, stammt diese Paketversion
aus einer älteren externen Paketreihe. Verwenden Sie das gebündelte Plugin aus
dem aktuellen OpenClaw oder einem lokalen Checkout, bis ein neueres npm-Paket veröffentlicht wird.
Wenn npm ein `@openclaw/*`-Plugin-Paket als veraltet meldet, stammt diese
Paketversion aus einer älteren externen Paketreihe. Verwenden Sie das
gebündelte Plugin aus dem aktuellen OpenClaw oder einen lokalen Checkout, bis
ein neueres npm-Paket veröffentlicht ist.
| Plugin | Paket | Dokumentation |
| Plugin | Paket | Dokumentation |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/de/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/de/channels/discord) |
@ -254,7 +279,7 @@ dem aktuellen OpenClaw oder einem lokalen Checkout, bis ein neueres npm-Paket ve
| Zalo | `@openclaw/zalo` | [Zalo](/de/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/de/plugins/zalouser) |
### Kern (mit OpenClaw ausgeliefert)
### Core (wird mit OpenClaw ausgeliefert)
<AccordionGroup>
<Accordion title="Modell-Provider (standardmäßig aktiviert)">
@ -267,10 +292,10 @@ dem aktuellen OpenClaw oder einem lokalen Checkout, bis ein neueres npm-Paket ve
<Accordion title="Memory-Plugins">
- `memory-core` - gebündelte Memory-Suche (Standard über `plugins.slots.memory`)
- `memory-lancedb` - LanceDB-gestütztes Langzeitgedächtnis mit automatischem Recall/Capture (setzen Sie `plugins.slots.memory = "memory-lancedb"`)
- `memory-lancedb` - LanceDB-gestütztes Langzeitgedächtnis mit automatischem Abruf/Erfassen (setzen Sie `plugins.slots.memory = "memory-lancedb"`)
Siehe [Memory LanceDB](/de/plugins/memory-lancedb) für OpenAI-kompatible
Embedding-Einrichtung, Ollama-Beispiele, Abrufgrenzen und Fehlerbehebung.
Siehe [Memory LanceDB](/de/plugins/memory-lancedb) für die OpenAI-kompatible
Einrichtung von Embeddings, Ollama-Beispiele, Abruflimits und Fehlerbehebung.
</Accordion>
@ -278,8 +303,8 @@ dem aktuellen OpenClaw oder einem lokalen Checkout, bis ein neueres npm-Paket ve
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="Andere">
- `browser` - gebündeltes Browser-Plugin für das Browser-Tool, die `openclaw browser` CLI, die `browser.request`-Gateway-Methode, die Browser-Laufzeitumgebung und den standardmäßigen Browser-Steuerungsdienst (standardmäßig aktiviert; vor dem Ersetzen deaktivieren)
<Accordion title="Sonstige">
- `browser` - gebündeltes Browser-Plugin für das Browser-Tool, die `openclaw browser` CLI, die `browser.request` Gateway-Methode, die Browser-Laufzeitumgebung und den standardmäßigen Browser-Steuerungsdienst (standardmäßig aktiviert; deaktivieren Sie es, bevor Sie es ersetzen)
- `copilot-proxy` - VS Code Copilot Proxy-Bridge (standardmäßig deaktiviert)
</Accordion>
@ -308,42 +333,42 @@ Suchen Sie nach Plugins von Drittanbietern? Siehe [Community-Plugins](/de/plugin
| `enabled` | Hauptschalter (Standard: `true`) |
| `allow` | Plugin-Allowlist (optional) |
| `bundledDiscovery` | Erkennungsmodus für gebündelte Plugins (standardmäßig `allowlist`) |
| `deny` | Plugin-Denylist (optional; deny hat Vorrang) |
| `deny` | Plugin-Denylist (optional; Deny hat Vorrang) |
| `load.paths` | Zusätzliche Plugin-Dateien/-Verzeichnisse |
| `slots` | Exklusive Slot-Selektoren (z. B. `memory`, `contextEngine`) |
| `entries.\<id\>` | Pro-Plugin-Schalter + Konfiguration |
| `entries.\<id\>` | Plugin-spezifische Schalter + Konfiguration |
`plugins.allow` ist exklusiv. Wenn die Liste nicht leer ist, können nur aufgeführte Plugins geladen werden
`plugins.allow` ist exklusiv. Wenn es nicht leer ist, können nur aufgelistete Plugins geladen
oder Tools bereitstellen, selbst wenn `tools.allow` `"*"` oder einen bestimmten Plugin-eigenen
Tool-Namen enthält. Wenn eine Tool-Allowlist auf Plugin-Tools verweist, fügen Sie die besitzenden Plugin-IDs
Tool-Namen enthält. Wenn eine Tool-Allowlist auf Plugin-Tools verweist, fügen Sie die IDs der besitzenden Plugins
zu `plugins.allow` hinzu oder entfernen Sie `plugins.allow`; `openclaw doctor` warnt vor dieser
Struktur.
Form.
`plugins.bundledDiscovery` ist bei neuen Konfigurationen standardmäßig `"allowlist"`, sodass ein
restriktives `plugins.allow`-Inventar auch ausgelassene gebündelte Provider-Plugins blockiert,
einschließlich der Laufzeit-Erkennung von Web-Such-Providern. Doctor versieht ältere
einschließlich der Erkennung von Laufzeit-Websuche-Providern. Doctor versieht ältere
restriktive Allowlist-Konfigurationen während der Migration mit `"compat"`, damit Upgrades das
bisherige Verhalten gebündelter Provider beibehalten, bis der Operator sich für den strengeren Modus entscheidet.
bisherige Verhalten gebündelter Provider beibehalten, bis der Betreiber den strengeren Modus aktiviert.
Ein leeres `plugins.allow` wird weiterhin als nicht gesetzt/offen behandelt.
Konfigurationsänderungen über `/plugins enable` oder `/plugins disable` lösen ein
Plugin-Neuladen im laufenden Gateway-Prozess aus. Neue Agent-Turns erstellen ihre Tool-Liste aus
der aktualisierten Plugin-Registry neu. Quellcodeändernde Vorgänge wie Installieren,
Aktualisieren und Deinstallieren starten den Gateway-Prozess weiterhin neu, da bereits importierte
Plugin-Module nicht sicher im laufenden Prozess ersetzt werden können.
prozessinternes Neuladen der Gateway-Plugins aus. Neue Agent-Turns bauen ihre Tool-Liste aus
der aktualisierten Plugin-Registrierung neu auf. Quelländernde Vorgänge wie Installation,
Aktualisierung und Deinstallation starten den Gateway-Prozess weiterhin neu, da bereits importierte
Plugin-Module nicht sicher direkt ersetzt werden können.
`openclaw plugins list` ist ein lokaler Snapshot der Plugin-Registry/Konfiguration. Ein dort
`enabled` Plugin bedeutet, dass die persistierte Registry und die aktuelle Konfiguration dem
Plugin die Teilnahme erlauben. Es beweist nicht, dass ein bereits laufendes Remote-Gateway
neu geladen oder mit demselben Plugin-Code neu gestartet wurde. Senden Sie bei VPS-/Container-Setups
mit Wrapper-Prozessen Neustarts oder neu ladeauslösende Schreibvorgänge an den tatsächlichen
`openclaw plugins list` ist ein lokaler Snapshot von Plugin-Registrierung/Konfiguration. Ein dort
`enabled` Plugin bedeutet, dass die persistierte Registrierung und die aktuelle Konfiguration dem
Plugin die Teilnahme erlauben. Es beweist nicht, dass ein bereits laufendes entferntes Gateway
neu geladen oder mit demselben Plugin-Code neu gestartet wurde. In VPS-/Container-Setups
mit Wrapper-Prozessen senden Sie Neustarts oder neu ladende Schreibvorgänge an den tatsächlichen
`openclaw gateway run`-Prozess, oder verwenden Sie `openclaw gateway restart` gegen das
laufende Gateway, wenn das Neuladen einen Fehler meldet.
<Accordion title="Plugin-Zustände: deaktiviert vs. fehlend vs. ungültig">
- **Deaktiviert**: Plugin existiert, aber Aktivierungsregeln haben es ausgeschaltet. Die Konfiguration bleibt erhalten.
- **Fehlend**: Konfiguration verweist auf eine Plugin-ID, die bei der Erkennung nicht gefunden wurde.
- **Ungültig**: Plugin existiert, aber seine Konfiguration entspricht nicht dem deklarierten Schema. Der Gateway-Start überspringt nur dieses Plugin; `openclaw doctor --fix` kann den ungültigen Eintrag quarantänisieren, indem es ihn deaktiviert und seine Konfigurationsnutzlast entfernt.
- **Deaktiviert**: Das Plugin existiert, wurde aber durch Aktivierungsregeln abgeschaltet. Die Konfiguration bleibt erhalten.
- **Fehlend**: Die Konfiguration verweist auf eine Plugin-ID, die bei der Erkennung nicht gefunden wurde.
- **Ungültig**: Das Plugin existiert, aber seine Konfiguration entspricht nicht dem deklarierten Schema. Der Gateway-Start überspringt nur dieses Plugin; `openclaw doctor --fix` kann den ungültigen Eintrag quarantänisieren, indem er ihn deaktiviert und seine Konfigurationsnutzlast entfernt.
</Accordion>
@ -354,8 +379,8 @@ OpenClaw sucht in dieser Reihenfolge nach Plugins (erster Treffer gewinnt):
<Steps>
<Step title="Konfigurationspfade">
`plugins.load.paths` - explizite Datei- oder Verzeichnispfade. Pfade, die zurück
auf OpenClaws eigene verpackte gebündelte Plugin-Verzeichnisse zeigen, werden ignoriert;
führen Sie `openclaw doctor --fix` aus, um diese veralteten Aliase zu entfernen.
auf OpenClaws eigene paketierte gebündelte Plugin-Verzeichnisse zeigen, werden ignoriert;
führen Sie `openclaw doctor --fix` aus, um diese veralteten Aliasse zu entfernen.
</Step>
<Step title="Workspace-Plugins">
@ -376,55 +401,55 @@ Paketierte Installationen und Docker-Images lösen gebündelte Plugins normalerw
kompilierten `dist/extensions`-Baum auf. Wenn ein Quellverzeichnis eines gebündelten Plugins
über den passenden paketierten Quellpfad bind-gemountet wird, zum Beispiel
`/app/extensions/synology-chat`, behandelt OpenClaw dieses gemountete Quellverzeichnis
als gebündeltes Source-Overlay und erkennt es vor dem paketierten
`/app/dist/extensions/synology-chat`-Bundle. Dadurch funktionieren Maintainer-Container-Schleifen,
ohne jedes gebündelte Plugin zurück auf TypeScript-Quellcode umzustellen.
als gebündeltes Quell-Overlay und erkennt es vor dem paketierten
`/app/dist/extensions/synology-chat`-Bundle. Dadurch funktionieren Maintainer-Container-Loops,
ohne jedes gebündelte Plugin zurück auf TypeScript-Quellen umzustellen.
Setzen Sie `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, um paketierte Dist-Bundles zu erzwingen,
selbst wenn Source-Overlay-Mounts vorhanden sind.
auch wenn Quell-Overlay-Mounts vorhanden sind.
### Aktivierungsregeln
- `plugins.enabled: false` deaktiviert alle Plugins und überspringt Plugin-Erkennungs-/Ladearbeit
- `plugins.deny` hat immer Vorrang vor allow
- `plugins.deny` hat immer Vorrang vor Allow
- `plugins.entries.\<id\>.enabled: false` deaktiviert dieses Plugin
- Plugins aus dem Workspace-Ursprung sind **standardmäßig deaktiviert** (müssen explizit aktiviert werden)
- Gebündelte Plugins folgen dem eingebauten standardmäßig aktivierten Set, sofern nicht überschrieben
- Plugins aus dem Workspace sind **standardmäßig deaktiviert** (müssen explizit aktiviert werden)
- Gebündelte Plugins folgen dem eingebauten Standard-aktiviert-Satz, sofern nicht überschrieben
- Exklusive Slots können das ausgewählte Plugin für diesen Slot zwangsaktivieren
- Einige gebündelte Opt-in-Plugins werden automatisch aktiviert, wenn die Konfiguration eine
Plugin-eigene Oberfläche benennt, etwa eine Provider-Modellreferenz, Channel-Konfiguration oder Harness-
Plugin-eigene Oberfläche nennt, etwa eine Provider-Modellreferenz, Channel-Konfiguration oder Harness-
Laufzeitumgebung
- Veraltete Plugin-Konfiguration bleibt erhalten, während `plugins.enabled: false` aktiv ist;
aktivieren Sie Plugins erneut, bevor Sie die Doctor-Bereinigung ausführen, wenn Sie veraltete IDs entfernt haben möchten
- OpenAI-Familien-Codex-Routen behalten getrennte Plugin-Grenzen:
aktivieren Sie Plugins erneut, bevor Sie die Doctor-Bereinigung ausführen, wenn Sie veraltete IDs entfernen möchten
- OpenAI-Family-Codex-Routen behalten separate Plugin-Grenzen bei:
`openai-codex/*` gehört zum OpenAI-Plugin, während das gebündelte Codex-
App-Server-Plugin durch `agentRuntime.id: "codex"` oder ältere
App-Server-Plugin durch `agentRuntime.id: "codex"` oder Legacy-
`codex/*`-Modellreferenzen ausgewählt wird
## Fehlerbehebung bei Laufzeit-Hooks
Wenn ein Plugin in `plugins list` angezeigt wird, aber `register(api)`-Seiteneffekte oder Hooks
Wenn ein Plugin in `plugins list` erscheint, aber `register(api)`-Seiteneffekte oder Hooks
im Live-Chat-Verkehr nicht ausgeführt werden, prüfen Sie zuerst Folgendes:
- Führen Sie `openclaw gateway status --deep --require-rpc` aus und bestätigen Sie, dass die aktive
Gateway-URL, das Profil, der Konfigurationspfad und der Prozess diejenigen sind, die Sie bearbeiten.
- Starten Sie das Live-Gateway nach Plugin-Installations-/Konfigurations-/Codeänderungen neu. In Wrapper-
- Starten Sie das Live-Gateway nach Änderungen an Plugin-Installation/-Konfiguration/-Code neu. In Wrapper-
Containern kann PID 1 nur ein Supervisor sein; starten Sie den untergeordneten
`openclaw gateway run`-Prozess neu oder signalisieren Sie ihn.
- Verwenden Sie `openclaw plugins inspect <id> --runtime --json`, um Hook-Registrierungen und
Diagnosen zu bestätigen. Nicht gebündelte Conversation-Hooks wie `llm_input`,
Diagnosen zu bestätigen. Nicht gebündelte Konversations-Hooks wie `llm_input`,
`llm_output`, `before_agent_finalize` und `agent_end` benötigen
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
- Für Modellwechsel bevorzugen Sie `before_model_resolve`. Es läuft vor der Modell-
Auflösung für Agent-Turns; `llm_output` läuft erst, nachdem ein Modellversuch
Assistant-Ausgabe erzeugt hat.
- Für den Nachweis des effektiven Sitzungsmodells verwenden Sie `openclaw sessions` oder die
Gateway-Sitzungs-/Statusoberflächen und starten Sie beim Debuggen von Provider-Nutzlasten das
- Verwenden Sie als Nachweis des effektiven Sitzungsmodells `openclaw sessions` oder die
Gateway-Sitzungs-/Statusoberflächen und starten Sie beim Debuggen von Provider-Payloads das
Gateway mit `--raw-stream --raw-stream-path <path>`.
### Langsame Einrichtung von Plugin-Tools
Wenn Agent-Turns beim Vorbereiten von Tools zu stocken scheinen, aktivieren Sie Trace-Logging und
prüfen Sie auf Timing-Zeilen der Plugin-Tool-Factory:
Wenn Agent-Turns beim Vorbereiten von Tools zu stocken scheinen, aktivieren Sie Trace-Protokollierung und
prüfen Sie auf Timing-Zeilen der Plugin-Tool-Factories:
```bash
openclaw config set logging.level trace
@ -437,15 +462,15 @@ Suchen Sie nach:
[trace:plugin-tools] factory timings ...
```
Die Zusammenfassung listet die gesamte Factory-Zeit und die langsamsten Plugin-Tool-Factorys auf,
Die Zusammenfassung listet die gesamte Factory-Zeit und die langsamsten Plugin-Tool-Factories auf,
einschließlich Plugin-ID, deklarierter Tool-Namen, Ergebnisform und ob das Tool
optional ist. Langsame Zeilen werden zu Warnungen hochgestuft, wenn eine einzelne Factory
mindestens 1 s benötigt oder die gesamte Vorbereitung der Plugin-Tool-Factory mindestens 5 s dauert.
mindestens 1 s benötigt oder die gesamte Vorbereitung der Plugin-Tool-Factories mindestens 5 s dauert.
OpenClaw cached erfolgreiche Plugin-Tool-Factory-Ergebnisse für wiederholte Auflösungen
OpenClaw cached erfolgreiche Ergebnisse von Plugin-Tool-Factories für wiederholte Auflösungen
mit demselben effektiven Anfragekontext. Der Cache-Schlüssel enthält die effektive
Laufzeitkonfiguration, den Workspace, Agent-/Sitzungs-IDs, Sandbox-Richtlinie, Browser-Einstellungen,
Delivery-Kontext, Requester-Identität und Ownership-Zustand, sodass Factorys, die
Laufzeitkonfiguration, Workspace, Agent-/Sitzungs-IDs, Sandbox-Policy, Browser-Einstellungen,
Bereitstellungskontext, Requester-Identität und Ownership-Zustand, sodass Factories, die
von diesen vertrauenswürdigen Feldern abhängen, erneut ausgeführt werden, wenn sich der Kontext ändert.
Wenn ein Plugin das Timing dominiert, prüfen Sie seine Laufzeitregistrierungen:
@ -456,7 +481,7 @@ openclaw plugins inspect <plugin-id> --runtime --json
Aktualisieren, reinstallieren oder deaktivieren Sie dann dieses Plugin. Plugin-Autoren sollten
teures Laden von Abhängigkeiten hinter den Tool-Ausführungspfad verschieben, statt es
innerhalb der Tool-Factory zu tun.
innerhalb der Tool-Factory zu erledigen.
### Doppelte Channel- oder Tool-Ownership
@ -468,33 +493,32 @@ Symptome:
Diese bedeuten, dass mehr als ein aktiviertes Plugin versucht, denselben Channel,
Setup-Flow oder Tool-Namen zu besitzen. Die häufigste Ursache ist ein externes Channel-Plugin,
das neben einem gebündelten Plugin installiert ist, das nun dieselbe Channel-ID bereitstellt.
das neben einem gebündelten Plugin installiert ist, das jetzt dieselbe Channel-ID bereitstellt.
Debug-Schritte:
- Führen Sie `openclaw plugins list --enabled --verbose` aus, um jedes aktivierte Plugin
und seinen Ursprung zu sehen.
und seine Herkunft zu sehen.
- Führen Sie `openclaw plugins inspect <id> --runtime --json` für jedes verdächtige Plugin aus und
vergleichen Sie `channels`, `channelConfigs`, `tools` und Diagnosen.
- Führen Sie `openclaw plugins registry --refresh` nach dem Installieren oder Entfernen von
- Führen Sie `openclaw plugins registry --refresh` nach der Installation oder Entfernung von
Plugin-Paketen aus, damit persistierte Metadaten die aktuelle Installation widerspiegeln.
- Starten Sie das Gateway nach Installations-, Registry- oder Konfigurationsänderungen neu.
- Starten Sie das Gateway nach Installations-, Registrierungs- oder Konfigurationsänderungen neu.
Behebungsoptionen:
- Wenn ein Plugin absichtlich ein anderes für dieselbe Channel-ID ersetzt, sollte das
bevorzugte Plugin `channelConfigs.<channel-id>.preferOver` mit der
niedriger priorisierten Plugin-ID deklarieren. Siehe [/plugins/manifest#replacing-another-channel-plugin](/de/plugins/manifest#replacing-another-channel-plugin).
bevorzugte Plugin `channelConfigs.<channel-id>.preferOver` mit der Plugin-ID niedrigerer Priorität deklarieren. Siehe [/plugins/manifest#replacing-another-channel-plugin](/de/plugins/manifest#replacing-another-channel-plugin).
- Wenn das Duplikat versehentlich ist, deaktivieren Sie eine Seite mit
`plugins.entries.<plugin-id>.enabled: false` oder entfernen Sie die veraltete Plugin-
Installation.
- Wenn Sie beide Plugins explizit aktiviert haben, behält OpenClaw diese Anfrage bei und
meldet den Konflikt. Wählen Sie einen Besitzer für den Channel oder benennen Sie Plugin-eigene
meldet den Konflikt. Wählen Sie einen Owner für den Channel oder benennen Sie Plugin-eigene
Tools um, damit die Laufzeitoberfläche eindeutig ist.
## Plugin-Slots (exklusive Kategorien)
Einige Kategorien sind exklusiv (nur eine gleichzeitig aktiv):
Einige Kategorien sind exklusiv (jeweils nur eine aktiv):
```json5
{
@ -507,10 +531,10 @@ Einige Kategorien sind exklusiv (nur eine gleichzeitig aktiv):
}
```
| Slot | Was er steuert | Standard |
| --------------- | -------------------- | ------------------- |
| `memory` | Active-Memory-Plugin | `memory-core` |
| `contextEngine` | Aktive Kontext-Engine | `legacy` (eingebaut) |
| Slot | Was er steuert | Standard |
| --------------- | ----------------------- | ------------------- |
| `memory` | Active Memory Plugin | `memory-core` |
| `contextEngine` | Aktive Context Engine | `legacy` (eingebaut) |
## CLI-Referenz
@ -562,31 +586,33 @@ openclaw plugins disable <id>
Gebündelte Plugins werden mit OpenClaw ausgeliefert. Viele sind standardmäßig aktiviert (zum Beispiel gebündelte Modell-Provider, gebündelte Speech-Provider und das gebündelte Browser-Plugin). Andere gebündelte Plugins benötigen weiterhin `openclaw plugins enable <id>`.
`--force` überschreibt ein vorhandenes installiertes Plugin oder Hook-Pack direkt. Verwenden Sie `openclaw plugins update <id-or-npm-spec>` für routinemäßige Upgrades nachverfolgter npm-Plugins. Es wird nicht mit `--link` unterstützt, da dabei der Quellpfad wiederverwendet wird, statt über ein verwaltetes Installationsziel zu kopieren.
`--force` überschreibt ein vorhandenes installiertes Plugin oder Hook-Pack direkt. Verwenden Sie `openclaw plugins update <id-or-npm-spec>` für routinemäßige Upgrades nachverfolgter npm-Plugins. Die Option wird nicht mit `--link` unterstützt, da dabei der Quellpfad wiederverwendet wird, statt ein verwaltetes Installationsziel zu überschreiben.
Wenn `plugins.allow` bereits gesetzt ist, fügt `openclaw plugins install` die installierte Plugin-ID dieser Allowlist hinzu, bevor es sie aktiviert. Wenn dieselbe Plugin-ID in `plugins.deny` vorhanden ist, entfernt die Installation diesen veralteten Deny-Eintrag, sodass die explizite Installation nach einem Neustart sofort geladen werden kann.
Wenn `plugins.allow` bereits gesetzt ist, fügt `openclaw plugins install` die installierte Plugin-ID dieser Allowlist hinzu, bevor es sie aktiviert. Wenn dieselbe Plugin-ID in `plugins.deny` vorhanden ist, entfernt die Installation diesen veralteten Deny-Eintrag, damit die explizite Installation nach einem Neustart sofort ladbar ist.
OpenClaw verwaltet eine persistierte lokale Plugin-Registry als Cold-Read-Modell für Plugin-Bestand, Besitz von Beiträgen und Startplanung. Installations-, Update-, Deinstallations-, Aktivierungs- und Deaktivierungsabläufe aktualisieren diese Registry, nachdem sie den Plugin-Status geändert haben. Dieselbe Datei `plugins/installs.json` enthält dauerhafte Installationsmetadaten in `installRecords` auf oberster Ebene und wiederaufbaubare Manifestmetadaten in `plugins`. Wenn die Registry fehlt, veraltet oder ungültig ist, baut `openclaw plugins registry --refresh` ihre Manifestansicht aus Installationsdatensätzen, Konfigurationsrichtlinien und Manifest-/Paketmetadaten neu auf, ohne Plugin-Runtime-Module zu laden. `openclaw plugins update <id-or-npm-spec>` gilt für nachverfolgte Installationen. Wenn eine npm-Paketspezifikation mit einem Dist-Tag oder einer exakten Version übergeben wird, wird der Paketname zurück zum nachverfolgten Plugin-Datensatz aufgelöst und die neue Spezifikation für künftige Updates gespeichert. Wenn der Paketname ohne Version übergeben wird, wird eine exakt gepinnte Installation zurück auf die Standard-Release-Linie der Registry verschoben. Wenn das installierte npm-Plugin bereits der aufgelösten Version und der gespeicherten Artefaktidentität entspricht, überspringt OpenClaw das Update, ohne herunterzuladen, neu zu installieren oder die Konfiguration neu zu schreiben. Wenn `openclaw update` im Beta-Kanal ausgeführt wird, versuchen Standardlinien-npm- und ClawHub-Plugin-Datensätze zuerst `@beta` und fallen auf standard/latest zurück, wenn kein Plugin-Beta-Release existiert. Exakte Versionen und explizite Tags bleiben gepinnt.
OpenClaw hält eine persistierte lokale Plugin-Registry als Cold-Read-Modell für Plugin-Inventar, Beitragszuordnung und Startplanung vor. Installations-, Update-, Deinstallations-, Aktivierungs- und Deaktivierungsabläufe aktualisieren diese Registry, nachdem sie den Plugin-Zustand geändert haben. Dieselbe Datei `plugins/installs.json` hält dauerhafte Installationsmetadaten in `installRecords` auf oberster Ebene und neu aufbaubare Manifestmetadaten in `plugins`. Wenn die Registry fehlt, veraltet oder ungültig ist, baut `openclaw plugins registry --refresh` ihre Manifestansicht aus Installationsdatensätzen, Konfigurationsrichtlinien und Manifest-/Paketmetadaten neu auf, ohne Plugin-Runtime-Module zu laden.
`openclaw plugins update <id-or-npm-spec>` gilt für nachverfolgte Installationen. Wenn Sie eine npm-Paketspezifikation mit Dist-Tag oder exakter Version übergeben, wird der Paketname zurück auf den nachverfolgten Plugin-Datensatz aufgelöst und die neue Spezifikation für zukünftige Updates gespeichert. Wenn Sie den Paketnamen ohne Version übergeben, wird eine exakt gepinnte Installation zurück auf die Standard-Release-Linie der Registry verschoben. Wenn das installierte npm-Plugin bereits der aufgelösten Version und der gespeicherten Artefaktidentität entspricht, überspringt OpenClaw das Update ohne Download, Neuinstallation oder Umschreiben der Konfiguration.
Wenn `openclaw update` im Beta-Kanal ausgeführt wird, versuchen npm- und ClawHub-Plugin-Datensätze der Standardlinie zuerst `@beta` und fallen auf default/latest zurück, wenn keine Plugin-Beta-Version existiert. Exakte Versionen und explizite Tags bleiben gepinnt.
`--pin` ist nur für npm. Es wird nicht mit `--marketplace` unterstützt, da Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation persistieren.
`--pin` ist nur für npm. Es wird nicht mit `--marketplace` unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation persistieren.
`--dangerously-force-unsafe-install` ist eine Notfallüberschreibung für False Positives des integrierten Scanners für gefährlichen Code. Damit können Plugin-Installationen und Plugin-Updates trotz integrierter `critical`-Befunde fortgesetzt werden, aber Plugin-`before_install`-Richtlinienblöcke oder Blockierungen wegen Scan-Fehlern werden weiterhin nicht umgangen. Installationsscans ignorieren übliche Testdateien und -verzeichnisse wie `tests/`, `__tests__/`, `*.test.*` und `*.spec.*`, um das Blockieren paketierter Test-Mocks zu vermeiden; deklarierte Plugin-Runtime-Einstiegspunkte werden weiterhin gescannt, selbst wenn sie einen dieser Namen verwenden.
`--dangerously-force-unsafe-install` ist eine Break-Glass-Übersteuerung für False Positives des integrierten Dangerous-Code-Scanners. Sie erlaubt Plugin-Installationen und Plugin-Updates trotz integrierter `critical`-Funde fortzufahren, umgeht aber weiterhin keine Plugin-`before_install`-Richtlinienblockaden oder Blockaden durch Scan-Fehler. Installations-Scans ignorieren gängige Testdateien und Verzeichnisse wie `tests/`, `__tests__/`, `*.test.*` und `*.spec.*`, um paketierte Test-Mocks nicht zu blockieren; deklarierte Plugin-Runtime-Einstiegspunkte werden weiterhin gescannt, selbst wenn sie einen dieser Namen verwenden.
Dieses CLI-Flag gilt nur für Plugin-Installations-/Update-Abläufe. Gateway-gestützte Installationen von Skill-Abhängigkeiten verwenden stattdessen die entsprechende `dangerouslyForceUnsafeInstall`-Anfrageüberschreibung, während `openclaw skills install` der separate ClawHub-Ablauf zum Herunterladen/Installieren von Skills bleibt.
Dieses CLI-Flag gilt nur für Plugin-Installations-/Update-Abläufe. Gateway-gestützte Skill-Abhängigkeitsinstallationen verwenden stattdessen die entsprechende `dangerouslyForceUnsafeInstall`-Anfrageübersteuerung, während `openclaw skills install` der separate ClawHub-Skill-Download-/Installationsablauf bleibt.
Wenn ein von Ihnen auf ClawHub veröffentlichtes Plugin durch einen Scan ausgeblendet oder blockiert wird, öffnen Sie das ClawHub-Dashboard oder führen Sie `clawhub package rescan <name>` aus, um ClawHub zu bitten, es erneut zu prüfen. `--dangerously-force-unsafe-install` wirkt sich nur auf Installationen auf Ihrem eigenen Rechner aus; es fordert ClawHub nicht auf, das Plugin erneut zu scannen oder ein blockiertes Release öffentlich zu machen.
Wenn ein von Ihnen auf ClawHub veröffentlichtes Plugin durch einen Scan ausgeblendet oder blockiert wird, öffnen Sie das ClawHub-Dashboard oder führen Sie `clawhub package rescan <name>` aus, um ClawHub zu bitten, es erneut zu prüfen. `--dangerously-force-unsafe-install` wirkt sich nur auf Installationen auf Ihrem eigenen Computer aus; es fordert ClawHub nicht auf, das Plugin erneut zu scannen oder eine blockierte Veröffentlichung öffentlich zu machen.
Kompatible Bundles nehmen am selben Ablauf für Plugin-Listen, -Inspektion, -Aktivierung und -Deaktivierung teil. Die aktuelle Runtime-Unterstützung umfasst Bundle-Skills, Claude-Command-Skills, Claude-`settings.json`-Defaults, Claude-`.lsp.json`- und im Manifest deklarierte `lspServers`-Defaults, Cursor-Command-Skills und kompatible Codex-Hook-Verzeichnisse.
Kompatible Bundles nehmen am selben Plugin-Ablauf für Auflisten/Prüfen/Aktivieren/Deaktivieren teil. Die aktuelle Runtime-Unterstützung umfasst Bundle-Skills, Claude-Command-Skills, Claude-`settings.json`-Standardeinstellungen, Claude-`.lsp.json`- und manifestdeklarierte `lspServers`-Standardeinstellungen, Cursor-Command-Skills und kompatible Codex-Hook-Verzeichnisse.
`openclaw plugins inspect <id>` meldet außerdem erkannte Bundle-Fähigkeiten sowie unterstützte oder nicht unterstützte MCP- und LSP-Servereinträge für Bundle-gestützte Plugins.
Marketplace-Quellen können ein bekannter Claude-Marketplace-Name aus `~/.claude/plugins/known_marketplaces.json`, ein lokaler Marketplace-Root oder `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repository-URL oder eine Git-URL sein. Bei Remote-Marketplaces müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repositorys bleiben und ausschließlich relative Pfadquellen verwenden.
Marketplace-Quellen können ein bekannter Claude-Marketplace-Name aus `~/.claude/plugins/known_marketplaces.json`, ein lokaler Marketplace-Root oder `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL sein. Für Remote-Marketplaces müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repos bleiben und ausschließlich relative Pfadquellen verwenden.
Vollständige Details finden Sie in der [`openclaw plugins`-CLI-Referenz](/de/cli/plugins).
Vollständige Details finden Sie in der [CLI-Referenz zu `openclaw plugins`](/de/cli/plugins).
## Plugin-API-Überblick
## Überblick über die Plugin-API
Native Plugins exportieren ein Entry-Objekt, das `register(api)` bereitstellt. Ältere Plugins verwenden möglicherweise weiterhin `activate(api)` als Legacy-Alias, neue Plugins sollten jedoch `register` verwenden.
Native Plugins exportieren ein Entry-Objekt, das `register(api)` bereitstellt. Ältere Plugins verwenden möglicherweise noch `activate(api)` als Legacy-Alias, neue Plugins sollten jedoch `register` verwenden.
```typescript
export default definePluginEntry({
@ -606,60 +632,60 @@ export default definePluginEntry({
});
```
OpenClaw lädt das Entry-Objekt und ruft während der Plugin-Aktivierung `register(api)` auf. Der Loader fällt für ältere Plugins weiterhin auf `activate(api)` zurück, aber gebündelte Plugins und neue externe Plugins sollten `register` als öffentlichen Vertrag betrachten.
OpenClaw lädt das Entry-Objekt und ruft während der Plugin-Aktivierung `register(api)` auf. Der Loader fällt für ältere Plugins weiterhin auf `activate(api)` zurück, aber gebündelte Plugins und neue externe Plugins sollten `register` als öffentlichen Vertrag behandeln.
`api.registrationMode` teilt einem Plugin mit, warum sein Entry geladen wird:
| Modus | Bedeutung |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Runtime-Aktivierung. Registrieren Sie Tools, Hooks, Dienste, Befehle, Routen und andere aktive Seiteneffekte. |
| `discovery` | Schreibgeschützte Fähigkeitserkennung. Registrieren Sie Provider und Metadaten; vertrauenswürdiger Plugin-Entry-Code kann geladen werden, aber aktive Seiteneffekte sollten übersprungen werden. |
| Modus | Bedeutung |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Runtime-Aktivierung. Registriert Tools, Hooks, Services, Befehle, Routen und andere Live-Nebeneffekte. |
| `discovery` | Schreibgeschützte Fähigkeitserkennung. Registriert Provider und Metadaten; vertrauenswürdiger Plugin-Entry-Code kann geladen werden, Live-Nebeneffekte jedoch überspringen. |
| `setup-only` | Laden von Channel-Setup-Metadaten über einen leichtgewichtigen Setup-Entry. |
| `setup-runtime` | Channel-Setup-Laden, das auch den Runtime-Entry benötigt. |
| `cli-metadata` | Nur Erfassung von CLI-Befehlsmetadaten. |
| `setup-runtime` | Channel-Setup-Laden, das zusätzlich den Runtime-Entry benötigt. |
| `cli-metadata` | Nur Sammlung von CLI-Befehlsmetadaten. |
Plugin-Entries, die Sockets, Datenbanken, Hintergrund-Worker oder langlebige Clients öffnen, sollten diese Seiteneffekte mit `api.registrationMode === "full"` absichern. Discovery-Ladevorgänge werden getrennt von Aktivierungsladevorgängen gecacht und ersetzen die laufende Gateway-Registry nicht. Discovery ist nicht aktivierend, aber nicht importfrei: OpenClaw kann den vertrauenswürdigen Plugin-Entry oder das Channel-Plugin-Modul auswerten, um den Snapshot zu erstellen. Halten Sie Module auf oberster Ebene leichtgewichtig und frei von Seiteneffekten, und verschieben Sie Netzwerkclients, Subprozesse, Listener, Credential-Lesevorgänge und Dienststarts hinter Full-Runtime-Pfade.
Plugin-Entries, die Sockets, Datenbanken, Hintergrund-Worker oder langlebige Clients öffnen, sollten diese Nebeneffekte mit `api.registrationMode === "full"` absichern. Discovery-Ladevorgänge werden getrennt von Aktivierungsladevorgängen gecacht und ersetzen nicht die laufende Gateway-Registry. Discovery ist nicht aktivierend, aber nicht importfrei: OpenClaw kann den vertrauenswürdigen Plugin-Entry oder das Channel-Plugin-Modul auswerten, um den Snapshot zu erstellen. Halten Sie Module auf oberster Ebene leichtgewichtig und frei von Nebeneffekten, und verschieben Sie Netzwerk-Clients, Subprozesse, Listener, Credential-Lesevorgänge und Service-Start hinter Full-Runtime-Pfade.
Gängige Registrierungsmethoden:
| Methode | Was registriert wird |
| --------------------------------------- | --------------------------------- |
| `registerProvider` | Modell-Provider (LLM) |
| `registerChannel` | Chat-Channel |
| `registerTool` | Agent-Tool |
| `registerHook` / `on(...)` | Lifecycle-Hooks |
| `registerSpeechProvider` | Text-to-Speech / STT |
| `registerRealtimeTranscriptionProvider` | Streaming-STT |
| `registerRealtimeVoiceProvider` | Duplex-Echtzeitstimme |
| `registerMediaUnderstandingProvider` | Bild-/Audioanalyse |
| `registerImageGenerationProvider` | Bilderzeugung |
| `registerMusicGenerationProvider` | Musikerzeugung |
| `registerVideoGenerationProvider` | Videoerzeugung |
| `registerWebFetchProvider` | Web-Fetch-/Scrape-Provider |
| `registerWebSearchProvider` | Websuche |
| `registerHttpRoute` | HTTP-Endpunkt |
| `registerCommand` / `registerCli` | CLI-Befehle |
| `registerContextEngine` | Kontext-Engine |
| `registerService` | Hintergrunddienst |
| Methode | Was sie registriert |
| --------------------------------------- | ----------------------------- |
| `registerProvider` | Modell-Provider (LLM) |
| `registerChannel` | Chat-Channel |
| `registerTool` | Agent-Tool |
| `registerHook` / `on(...)` | Lifecycle-Hooks |
| `registerSpeechProvider` | Text-to-Speech / STT |
| `registerRealtimeTranscriptionProvider` | Streaming-STT |
| `registerRealtimeVoiceProvider` | Duplex-Echtzeitstimme |
| `registerMediaUnderstandingProvider` | Bild-/Audioanalyse |
| `registerImageGenerationProvider` | Bilderzeugung |
| `registerMusicGenerationProvider` | Musikerzeugung |
| `registerVideoGenerationProvider` | Videoerzeugung |
| `registerWebFetchProvider` | Web-Fetch-/Scrape-Provider |
| `registerWebSearchProvider` | Websuche |
| `registerHttpRoute` | HTTP-Endpunkt |
| `registerCommand` / `registerCli` | CLI-Befehle |
| `registerContextEngine` | Kontext-Engine |
| `registerService` | Hintergrund-Service |
Guard-Verhalten für typisierte Lifecycle-Hooks:
Hook-Guard-Verhalten für typisierte Lifecycle-Hooks:
- `before_tool_call`: `{ block: true }` ist terminal; Handler mit niedrigerer Priorität werden übersprungen.
- `before_tool_call`: `{ block: false }` ist ein No-op und hebt einen früheren Block nicht auf.
- `before_tool_call`: `{ block: false }` ist ein No-op und hebt keine frühere Blockierung auf.
- `before_install`: `{ block: true }` ist terminal; Handler mit niedrigerer Priorität werden übersprungen.
- `before_install`: `{ block: false }` ist ein No-op und hebt einen früheren Block nicht auf.
- `before_install`: `{ block: false }` ist ein No-op und hebt keine frühere Blockierung auf.
- `message_sending`: `{ cancel: true }` ist terminal; Handler mit niedrigerer Priorität werden übersprungen.
- `message_sending`: `{ cancel: false }` ist ein No-op und hebt ein früheres Cancel nicht auf.
- `message_sending`: `{ cancel: false }` ist ein No-op und hebt keinen früheren Abbruch auf.
Der native Codex-App-Server leitet native Codex-Tool-Ereignisse zurück in diese Hook-Oberfläche. Plugins können native Codex-Tools über `before_tool_call` blockieren, Ergebnisse über `after_tool_call` beobachten und an Codex-`PermissionRequest`-Freigaben teilnehmen. Die Bridge schreibt native Codex-Tool-Argumente noch nicht um. Die genaue Grenze der Codex-Runtime-Unterstützung befindet sich im [Codex-harness-v1-Supportvertrag](/de/plugins/codex-harness#v1-support-contract).
Native Codex-App-Server führen Codex-native Tool-Events über eine Bridge zurück in diese Hook-Oberfläche. Plugins können native Codex-Tools über `before_tool_call` blockieren, Ergebnisse über `after_tool_call` beobachten und an Codex-`PermissionRequest`-Genehmigungen teilnehmen. Die Bridge schreibt Codex-native Tool-Argumente noch nicht um. Die genaue Grenze der Codex-Runtime-Unterstützung ist im [Support-Vertrag für Codex-Harness v1](/de/plugins/codex-harness#v1-support-contract) festgelegt.
Das vollständige Verhalten typisierter Hooks finden Sie in der [SDK-Übersicht](/de/plugins/sdk-overview#hook-decision-semantics).
Das vollständige typisierte Hook-Verhalten finden Sie in der [SDK-Übersicht](/de/plugins/sdk-overview#hook-decision-semantics).
## Verwandt
## Verwandte
- [Plugins erstellen](/de/plugins/building-plugins) - erstellen Sie Ihr eigenes Plugin
- [Plugin-Bundles](/de/plugins/bundles) - Bundle-Kompatibilität mit Codex/Claude/Cursor
- [Plugins erstellen](/de/plugins/building-plugins) - eigenes Plugin erstellen
- [Plugin-Bundles](/de/plugins/bundles) - Bundle-Kompatibilität für Codex/Claude/Cursor
- [Plugin-Manifest](/de/plugins/manifest) - Manifest-Schema
- [Tools registrieren](/de/plugins/building-plugins#registering-agent-tools) - Agent-Tools in einem Plugin hinzufügen
- [Plugin-Interna](/de/plugins/architecture) - Fähigkeitsmodell und Lade-Pipeline
- [Plugin-Interna](/de/plugins/architecture) - Fähigkeitsmodell und Ladepipeline
- [Community-Plugins](/de/plugins/community) - Einträge von Drittanbietern