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

chore(i18n): refresh de translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 09:02:57 +00:00
parent ddf26b79d5
commit c2294e9e77
28 changed files with 5093 additions and 5002 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
docs/de/automation/hooks.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Sie möchten ereignisgesteuerte Automatisierung für /new, /reset, /stop und Agent-Lifecycle-Ereignisse.
- Sie möchten ereignisgesteuerte Automatisierung für `/new`, `/reset`, `/stop` und Agent-Lebenszyklusereignisse.
- Sie möchten Hooks erstellen, installieren oder debuggen.
summary: 'Hooks: ereignisgesteuerte Automatisierung für Befehle und Lifecycle-Ereignisse'
summary: 'Hooks: ereignisgesteuerte Automatisierung für Befehle und Lebenszyklusereignisse'
title: Hooks
x-i18n:
generated_at: "2026-04-24T06:26:23Z"
generated_at: "2026-04-24T08:57:06Z"
model: gpt-5.4
provider: openai
source_hash: 9e24d5a95748151059e34f8c9ff9910dbcd7a32e7cadb44d1fa25352ef3a09a6
source_hash: 4e6246f25272208d9a9ff2f186bcd3a463c78ea24b833f0259174d0f7f0cbea6
source_path: automation/hooks.md
workflow: 15
---
Hooks sind kleine Skripte, die ausgeführt werden, wenn innerhalb des Gateway etwas passiert. Sie können aus Verzeichnissen erkannt und mit `openclaw hooks` geprüft werden. Das Gateway lädt interne Hooks erst, nachdem Sie Hooks aktiviert oder mindestens einen Hook-Eintrag, ein Hook-Paket, einen Legacy-Handler oder ein zusätzliches Hook-Verzeichnis konfiguriert haben.
Hooks sind kleine Skripte, die ausgeführt werden, wenn innerhalb des Gateway etwas passiert. Sie können aus Verzeichnissen erkannt und mit `openclaw hooks` geprüft werden. Das Gateway lädt interne Hooks erst, nachdem Sie Hooks aktiviert oder mindestens einen Hook-Eintrag, ein Hook-Pack, einen Legacy-Handler oder ein zusätzliches Hook-Verzeichnis konfiguriert haben.
Es gibt zwei Arten von Hooks in OpenClaw:
- **Interne Hooks** (diese Seite): werden innerhalb des Gateway ausgeführt, wenn Agent-Ereignisse ausgelöst werden, etwa `/new`, `/reset`, `/stop` oder Lifecycle-Ereignisse.
- **Webhooks**: externe HTTP-Endpunkte, mit denen andere Systeme Arbeit in OpenClaw auslösen können. Siehe [Webhooks](/de/automation/cron-jobs#webhooks).
- **Interne Hooks** (diese Seite): werden innerhalb des Gateway ausgeführt, wenn Agent-Ereignisse ausgelöst werden, etwa `/new`, `/reset`, `/stop` oder Lebenszyklusereignisse.
- **Webhooks**: externe HTTP-Endpunkte, über die andere Systeme Arbeit in OpenClaw auslösen können. Siehe [Webhooks](/de/automation/cron-jobs#webhooks).
Hooks können auch in Plugins gebündelt sein. `openclaw hooks list` zeigt sowohl eigenständige Hooks als auch von Plugins verwaltete Hooks an.
@ -48,12 +48,12 @@ openclaw hooks info session-memory
| `command` | Beliebiges Befehlsereignis (allgemeiner Listener) |
| `session:compact:before` | Bevor Compaction den Verlauf zusammenfasst |
| `session:compact:after` | Nachdem Compaction abgeschlossen ist |
| `session:patch` | Wenn Sitzungseigenschaften geändert werden |
| `session:patch` | Wenn Session-Eigenschaften geändert werden |
| `agent:bootstrap` | Bevor Workspace-Bootstrap-Dateien eingefügt werden |
| `gateway:startup` | Nachdem Channels gestartet wurden und Hooks geladen sind |
| `message:received` | Eingehende Nachricht aus einem beliebigen Channel |
| `gateway:startup` | Nachdem Kanäle gestartet und Hooks geladen wurden |
| `message:received` | Eingehende Nachricht aus einem beliebigen Kanal |
| `message:transcribed` | Nachdem die Audiotranskription abgeschlossen ist |
| `message:preprocessed` | Nachdem die gesamte Medien- und Link-Verarbeitung abgeschlossen ist |
| `message:preprocessed` | Nachdem die gesamte Medien- und Linkverarbeitung abgeschlossen ist |
| `message:sent` | Ausgehende Nachricht zugestellt |
## Hooks schreiben
@ -62,13 +62,13 @@ openclaw hooks info session-memory
Jeder Hook ist ein Verzeichnis mit zwei Dateien:
```text
```
my-hook/
├── HOOK.md # Metadaten + Dokumentation
└── handler.ts # Handler-Implementierung
```
### Format von HOOK.md
### `HOOK.md`-Format
```markdown
---
@ -78,9 +78,9 @@ metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# My Hook
# Mein Hook
Ausführliche Dokumentation kommt hier hin.
Detaillierte Dokumentation kommt hier hin.
```
**Metadatenfelder** (`metadata.openclaw`):
@ -92,7 +92,7 @@ Ausführliche Dokumentation kommt hier hin.
| `export` | Zu verwendender benannter Export (Standard ist `"default"`) |
| `os` | Erforderliche Plattformen (z. B. `["darwin", "linux"]`) |
| `requires` | Erforderliche `bins`, `anyBins`, `env` oder `config`-Pfade |
| `always` | Eignungsprüfungen umgehen (Boolean) |
| `always` | Eignungsprüfungen umgehen (boolean) |
| `install` | Installationsmethoden |
### Handler-Implementierung
@ -113,7 +113,7 @@ const handler = async (event) => {
export default handler;
```
Jedes Ereignis enthält: `type`, `action`, `sessionKey`, `timestamp`, `messages` (zum Senden an den Benutzer per push ergänzen) und `context` (ereignisspezifische Daten).
Jedes Ereignis enthält: `type`, `action`, `sessionKey`, `timestamp`, `messages` (per `push`, um an den Nutzer zu senden) und `context` (ereignisspezifische Daten). Hook-Kontexte von Agent- und Tool-Plugins können außerdem `trace` enthalten, einen schreibgeschützten W3C-kompatiblen Diagnose-Trace-Kontext, den Plugins zur OTEL-Korrelation in strukturierte Logs weitergeben können.
### Wichtige Punkte zum Ereigniskontext
@ -125,7 +125,7 @@ Jedes Ereignis enthält: `type`, `action`, `sessionKey`, `timestamp`, `messages`
**Nachrichtenereignisse** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
**Nachrichtenereignisse** (`message:preprocessed`): `context.bodyForAgent` (final angereicherter Inhalt), `context.from`, `context.channelId`.
**Nachrichtenereignisse** (`message:preprocessed`): `context.bodyForAgent` (endgültiger angereicherter Inhalt), `context.from`, `context.channelId`.
**Bootstrap-Ereignisse** (`agent:bootstrap`): `context.bootstrapFiles` (veränderbares Array), `context.agentId`.
@ -135,34 +135,34 @@ Jedes Ereignis enthält: `type`, `action`, `sessionKey`, `timestamp`, `messages`
## Hook-Erkennung
Hooks werden aus diesen Verzeichnissen erkannt, in aufsteigender Reihenfolge der Überschreibungspriorität:
Hooks werden aus diesen Verzeichnissen erkannt, in Reihenfolge zunehmender Override-Priorität:
1. **Gebündelte Hooks**: werden mit OpenClaw ausgeliefert
2. **Plugin-Hooks**: Hooks, die in installierten Plugins gebündelt sind
3. **Verwaltete Hooks**: `~/.openclaw/hooks/` (benutzerinstalliert, über Workspaces hinweg gemeinsam genutzt). Zusätzliche Verzeichnisse aus `hooks.internal.load.extraDirs` haben dieselbe Priorität.
3. **Verwaltete Hooks**: `~/.openclaw/hooks/` (vom Nutzer installiert, gemeinsam für alle Workspaces). Zusätzliche Verzeichnisse aus `hooks.internal.load.extraDirs` haben dieselbe Priorität.
4. **Workspace-Hooks**: `<workspace>/hooks/` (pro Agent, standardmäßig deaktiviert, bis sie ausdrücklich aktiviert werden)
Workspace-Hooks können neue Hook-Namen hinzufügen, aber gebündelte, verwaltete oder von Plugins bereitgestellte Hooks mit demselben Namen nicht überschreiben.
Workspace-Hooks können neue Hook-Namen hinzufügen, aber keine gebündelten, verwalteten oder von Plugins bereitgestellten Hooks mit demselben Namen überschreiben.
Das Gateway überspringt die Erkennung interner Hooks beim Start, bis interne Hooks konfiguriert sind. Aktivieren Sie einen gebündelten oder verwalteten Hook mit `openclaw hooks enable <name>`, installieren Sie ein Hook-Paket oder setzen Sie `hooks.internal.enabled=true`, um dies zu aktivieren. Wenn Sie einen benannten Hook aktivieren, lädt das Gateway nur den Handler dieses Hooks; `hooks.internal.enabled=true`, zusätzliche Hook-Verzeichnisse und Legacy-Handler aktivieren die umfassende Erkennung.
Das Gateway überspringt die Erkennung interner Hooks beim Start, bis interne Hooks konfiguriert sind. Aktivieren Sie einen gebündelten oder verwalteten Hook mit `openclaw hooks enable <name>`, installieren Sie ein Hook-Pack oder setzen Sie `hooks.internal.enabled=true`, um dies zu aktivieren. Wenn Sie einen benannten Hook aktivieren, lädt das Gateway nur den Handler dieses Hooks; `hooks.internal.enabled=true`, zusätzliche Hook-Verzeichnisse und Legacy-Handler aktivieren eine breite Erkennung.
### Hook-Pakete
### Hook-Packs
Hook-Pakete sind npm-Pakete, die Hooks über `openclaw.hooks` in `package.json` exportieren. Installation mit:
Hook-Packs sind npm-Pakete, die Hooks über `openclaw.hooks` in `package.json` exportieren. Installation mit:
```bash
openclaw plugins install <path-or-spec>
```
Npm-Spezifikationen sind nur für die Registry zulässig (Paketname + optionale exakte Version oder dist-tag). Git-/URL-/Datei-Spezifikationen und semver-Bereiche werden abgelehnt.
Npm-Spezifikationen sind nur für Registries zulässig (Paketname plus optionale exakte Version oder dist-tag). Git-/URL-/Datei-Spezifikationen und semver-Bereiche werden abgelehnt.
## Gebündelte Hooks
| Hook | Ereignisse | Was er tut |
| Hook | Ereignisse | Was er macht |
| --------------------- | ------------------------------ | ---------------------------------------------------- |
| session-memory | `command:new`, `command:reset` | Speichert Sitzungskontext in `<workspace>/memory/` |
| session-memory | `command:new`, `command:reset` | Speichert Session-Kontext unter `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | Fügt zusätzliche Bootstrap-Dateien aus Glob-Mustern ein |
| command-logger | `command` | Protokolliert alle Befehle in `~/.openclaw/logs/commands.log` |
| command-logger | `command` | Protokolliert alle Befehle nach `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | Führt `BOOT.md` aus, wenn das Gateway startet |
Beliebigen gebündelten Hook aktivieren:
@ -173,13 +173,13 @@ openclaw hooks enable <hook-name>
<a id="session-memory"></a>
### Details zu session-memory
### Details zu `session-memory`
Extrahiert die letzten 15 Benutzer-/Assistant-Nachrichten, erzeugt per LLM einen beschreibenden Dateinamen-Slug und speichert ihn unter `<workspace>/memory/YYYY-MM-DD-slug.md`. Erfordert, dass `workspace.dir` konfiguriert ist.
Extrahiert die letzten 15 Nutzer-/Assistant-Nachrichten, erzeugt per LLM einen beschreibenden Dateinamen-Slug und speichert unter `<workspace>/memory/YYYY-MM-DD-slug.md`. Erfordert, dass `workspace.dir` konfiguriert ist.
<a id="bootstrap-extra-files"></a>
### Konfiguration von bootstrap-extra-files
### Konfiguration für `bootstrap-extra-files`
```json
{
@ -200,21 +200,21 @@ Pfade werden relativ zum Workspace aufgelöst. Es werden nur erkannte Bootstrap-
<a id="command-logger"></a>
### Details zu command-logger
### Details zu `command-logger`
Protokolliert jeden Slash-Befehl in `~/.openclaw/logs/commands.log`.
Protokolliert jeden Slash-Befehl nach `~/.openclaw/logs/commands.log`.
<a id="boot-md"></a>
### Details zu boot-md
### Details zu `boot-md`
Führt `BOOT.md` aus dem aktiven Workspace aus, wenn das Gateway startet.
## Plugin-Hooks
Plugins können Hooks über das Plugin SDK registrieren, um eine tiefere Integration zu ermöglichen: Tool-Aufrufe abfangen, Prompts ändern, den Nachrichtenfluss steuern und mehr. Das Plugin SDK stellt 28 Hooks bereit, die Modellauflösung, Agent-Lifecycle, Nachrichtenfluss, Tool-Ausführung, Subagent-Koordination und Gateway-Lifecycle abdecken.
Plugins können Hooks über das Plugin SDK registrieren, um eine tiefere Integration zu ermöglichen: Tool-Aufrufe abfangen, Prompts ändern, den Nachrichtenfluss steuern und mehr. Das Plugin SDK stellt 28 Hooks bereit, die Modellauflösung, Agent-Lebenszyklus, Nachrichtenfluss, Tool-Ausführung, Subagent-Koordination und Gateway-Lebenszyklus abdecken.
Die vollständige Referenz für Plugin-Hooks einschließlich `before_tool_call`, `before_agent_reply`, `before_install` und aller weiteren Plugin-Hooks finden Sie unter [Plugin Architecture](/de/plugins/architecture-internals#provider-runtime-hooks).
Die vollständige Referenz der Plugin-Hooks einschließlich `before_tool_call`, `before_agent_reply`, `before_install` und aller anderen Plugin-Hooks finden Sie unter [Plugin Architecture](/de/plugins/architecture-internals#provider-runtime-hooks).
## Konfiguration
@ -264,7 +264,7 @@ Zusätzliche Hook-Verzeichnisse:
```
<Note>
Das Legacy-Konfigurationsformat `hooks.internal.handlers` als Array wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, neue Hooks sollten jedoch das erkennungsgestützte System verwenden.
Das Legacy-Konfigurationsformat `hooks.internal.handlers` als Array wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, neue Hooks sollten jedoch das erkennungsbasierte System verwenden.
</Note>
## CLI-Referenz
@ -286,10 +286,10 @@ openclaw hooks disable <hook-name>
## Best Practices
- **Handler schnell halten.** Hooks werden während der Befehlsverarbeitung ausgeführt. Starten Sie aufwendige Arbeit im Fire-and-forget-Stil mit `void processInBackground(event)`.
- **Fehler robust behandeln.** Umschließen Sie riskante Operationen mit try/catch; werfen Sie keine Fehler, damit andere Handler weiterlaufen können.
- **Ereignisse früh filtern.** Kehren Sie sofort zurück, wenn Ereignistyp oder Aktion nicht relevant sind.
- **Spezifische Ereignisschlüssel verwenden.** Bevorzugen Sie `"events": ["command:new"]` gegenüber `"events": ["command"]`, um den Overhead zu reduzieren.
- **Handler schnell halten.** Hooks laufen während der Befehlsverarbeitung. Starten Sie aufwendige Arbeit per Fire-and-forget mit `void processInBackground(event)`.
- **Fehler sauber behandeln.** Kapseln Sie riskante Operationen in try/catch; werfen Sie keine Fehler, damit andere Handler weiterlaufen können.
- **Ereignisse früh filtern.** Geben Sie sofort zurück, wenn Ereignistyp/-aktion nicht relevant ist.
- **Spezifische Ereignisschlüssel verwenden.** Bevorzugen Sie `"events": ["command:new"]` gegenüber `"events": ["command"]`, um Overhead zu reduzieren.
## Fehlerbehebung
@ -310,7 +310,7 @@ openclaw hooks list
openclaw hooks info my-hook
```
Prüfen Sie auf fehlende Binärdateien (PATH), Umgebungsvariablen, Konfigurationswerte oder OS-Kompatibilität.
Prüfen Sie auf fehlende Binärdateien (PATH), Umgebungsvariablen, Konfigurationswerte oder Betriebssystemkompatibilität.
### Hook wird nicht ausgeführt
@ -322,5 +322,5 @@ Prüfen Sie auf fehlende Binärdateien (PATH), Umgebungsvariablen, Konfiguration
- [CLI-Referenz: hooks](/de/cli/hooks)
- [Webhooks](/de/automation/cron-jobs#webhooks)
- [Plugin Architecture](/de/plugins/architecture-internals#provider-runtime-hooks) — vollständige Referenz für Plugin-Hooks
- [Plugin Architecture](/de/plugins/architecture-internals#provider-runtime-hooks) — vollständige Referenz der Plugin-Hooks
- [Konfiguration](/de/gateway/configuration-reference#hooks)

162
docs/de/ci.md
View File

@ -1,57 +1,57 @@
---
read_when:
- Sie müssen verstehen, warum ein CI-Job ausgeführt wurde oder nicht ausgeführt wurde
- Sie debuggen fehlschlagende GitHub-Actions-Checks
- Sie müssen verstehen, warum ein CI-Job ausgeführt wurde oder nicht.
- Sie debuggen fehlgeschlagene GitHub-Actions-Prüfungen.
summary: CI-Job-Graph, Scope-Gates und lokale Befehlsäquivalente
title: CI-Pipeline
x-i18n:
generated_at: "2026-04-24T06:30:05Z"
generated_at: "2026-04-24T08:57:07Z"
model: gpt-5.4
provider: openai
source_hash: 8e24efec145ff144b007e248ef0f9c56287619eb9af204d45d49984909a6136b
source_hash: 489ac05725a316b25f56f7f754d6a8652abbd60481fbe6e692572b81581fe405
source_path: ci.md
workflow: 15
---
Die CI läuft bei jedem Push nach `main` und bei jedem Pull Request. Sie verwendet intelligentes Scoping, um teure Jobs zu überspringen, wenn sich nur nicht zusammenhängende Bereiche geändert haben.
Die CI läuft bei jedem Push auf `main` und bei jedem Pull Request. Sie verwendet intelligentes Scoping, um teure Jobs zu überspringen, wenn sich nur nicht zusammenhängende Bereiche geändert haben.
QA Lab hat dedizierte CI-Lanes außerhalb des smart gescopten Haupt-Workflows. Der
QA Lab hat dedizierte CI-Lanes außerhalb des Haupt-Workflows mit intelligentem Scoping. Der
Workflow `Parity gate` läuft bei passenden PR-Änderungen und bei manuellem Dispatch; er
baut die private QA-Laufzeit und vergleicht die agentischen Packs für Mock GPT-5.4 und Opus 4.6.
baut die private QA-Laufzeitumgebung und vergleicht die agentischen Packs für Mock GPT-5.4 und Opus 4.6.
Der Workflow `QA-Lab - All Lanes` läuft nachts auf `main` und bei
manuellem Dispatch; er fächert das Mock-Parity-Gate, die Live-Matrix-Lane und die Live-
Telegram-Lane als parallele Jobs auf. Die Live-Jobs verwenden die Umgebung
`qa-live-shared`, und die Telegram-Lane verwendet Convex-Leases. `OpenClaw Release
Checks` führt dieselben QA-Lab-Lanes ebenfalls vor der Release-Freigabe aus.
Checks` führt vor der Release-Freigabe ebenfalls dieselben QA-Lab-Lanes aus.
Der Workflow `Duplicate PRs After Merge` ist ein manueller Maintainer-Workflow für
das Bereinigen von Duplikaten nach dem Landen. Er verwendet standardmäßig Dry-Run und schließt
nur ausdrücklich aufgeführte PRs, wenn `apply=true`. Bevor GitHub geändert wird,
prüft er, dass der gelandete PR gemergt ist und dass jeder Duplikat-PR entweder ein gemeinsames referenziertes Issue
oder überlappende geänderte Hunks hat.
die Bereinigung von Duplikaten nach dem Merge. Standardmäßig läuft er als Dry Run und schließt nur explizit
aufgelistete PRs, wenn `apply=true` gesetzt ist. Bevor GitHub verändert wird,
prüft er, dass der gelandete PR gemergt ist und dass jedes Duplikat entweder ein gemeinsames referenziertes Issue
oder überlappende geänderte Hunk-Bereiche hat.
Der Workflow `Docs Agent` ist eine ereignisgesteuerte Codex-Wartungslane, um
bestehende Dokumentation an kürzlich gelandete Änderungen anzupassen. Er hat keinen reinen Zeitplan:
Ein erfolgreicher CI-Lauf eines nicht von Bots stammenden Pushs auf `main` kann ihn auslösen,
und manueller Dispatch kann ihn direkt ausführen. Aufrufe über Workflow-Run werden übersprungen, wenn
`main` bereits weitergelaufen ist oder wenn in der letzten Stunde bereits 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 Änderungen auf `main` abdecken kann.
bestehende Docs an kürzlich gelandete Änderungen angepasst zu halten. Er hat keinen reinen Zeitplan:
Ein erfolgreicher nicht von einem Bot stammender Push-CI-Lauf auf `main` kann ihn auslösen, und manueller Dispatch kann
ihn direkt ausführen. Aufrufe per Workflow-Run werden übersprungen, wenn `main` inzwischen weitergezogen ist oder wenn
im letzten Stunde bereits 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 Änderungen auf `main` seit dem
letzten Docs-Durchlauf abdecken kann.
Der Workflow `Test Performance Agent` ist eine ereignisgesteuerte Codex-Wartungslane
für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher CI-Lauf eines nicht von Bots stammenden Pushs auf
`main` kann ihn auslösen, aber er wird übersprungen, wenn an diesem UTC-Tag bereits ein anderer Aufruf per Workflow-Run
gelaufen ist oder läuft. Manueller Dispatch umgeht diese tägliche Aktivitätsschranke.
Die Lane erstellt einen gruppierten Vitest-Leistungsbericht für die vollständige Suite, erlaubt Codex
nur kleine testleistungsbezogene Korrekturen mit Erhalt der Abdeckung statt umfangreicher Refactorings,
führt dann den Bericht für die vollständige Suite erneut aus und weist Änderungen zurück, die
die Anzahl der erfolgreich laufenden Baseline-Tests verringern. Wenn die Baseline fehlschlagende Tests hat, darf
Codex nur offensichtliche Fehler beheben, und der vollständige Suite-Bericht nach dem Agenten muss erfolgreich sein, bevor
irgendetwas committet wird. Wenn `main` weiterläuft, bevor der Bot-Push landet, rebased
die Lane den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut;
veraltete widersprüchliche Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-
Aktion dieselbe Drop-Sudo-Sicherheitsposition wie der Docs Agent beibehalten kann.
für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher nicht von einem Bot stammender Push-CI-Lauf auf
`main` kann ihn auslösen, aber er wird übersprungen, wenn an diesem UTC-Tag bereits ein anderer
workflow-run-Aufruf gelaufen ist oder gerade läuft. Manueller Dispatch umgeht diese tägliche
Aktivitätsprüfung. Die Lane erstellt einen gruppierten Vitest-Performancebericht für die vollständige Test-Suite, lässt Codex
nur kleine testleistungsbezogene Korrekturen vornehmen, die die Abdeckung erhalten, statt umfassender
Refactorings, führt dann den vollständigen Bericht erneut aus und lehnt Änderungen ab, die
die Zahl der bestandenen Baseline-Tests verringern. Wenn die Baseline fehlschlagende Tests hat,
darf Codex nur offensichtliche Fehler beheben, und der vollständige Bericht nach dem Agenten muss bestehen, bevor
irgendetwas committet wird. Wenn `main` weitergeht, bevor der Bot-Push landet, rebaset 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-Sicherheitsposition wie der Docs Agent beibehalten kann.
```bash
gh workflow run duplicate-after-merge.yml \
@ -60,86 +60,86 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Job-Überblick
## Job-Übersicht
| Job | Zweck | Wann er läuft |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
| `preflight` | Nur-Doku-Änderungen, geänderte Scopes, geänderte Extensions erkennen und das CI-Manifest bauen | 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` | Audit der produktionsrelevanten Lockfile ohne Abhängigkeiten 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 |
| `build-artifacts` | `dist/`, Control UI, Prüfungen gebauter Artefakte und wiederverwendbare nachgelagerte Artefakte bauen | Bei Node-relevanten Änderungen |
| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie Bundled-/Plugin-Contract-/Protokoll-Prüfungen | Bei Node-relevanten Änderungen |
| `checks-fast-contracts-channels` | Geshardete Kanal-Contract-Prüfungen mit stabilem aggregiertem Prüfergebnis | Bei Node-relevanten Änderungen |
| `checks-node-extensions` | Vollständige Test-Shards gebündelter Plugins über die gesamte Extension-Suite | Bei Node-relevanten Änderungen |
| `checks-node-core-test` | Core-Node-Test-Shards, ohne Kanal-, Bundled-, Contract- und Extension-Lanes | Bei Node-relevanten Änderungen |
| `extension-fast` | Fokussierte Tests nur für die geänderten gebündelten Plugins | Pull Requests mit Extension-Änderungen |
| `check` | Geshardetes Äquivalent des lokalen Haupt-Gates: Prod-Typen, Lint, Guards, Test-Typen und strikter Smoke | Bei Node-relevanten Änderungen |
| `check-additional` | Architektur-, Boundary-, Extension-Surface-Guards, Package-Boundary und Gateway-Watch-Shards | Bei Node-relevanten Änderungen |
| `build-smoke` | Smoke-Tests für gebaute CLI und Speicher-Smoke beim Start | Bei Node-relevanten Änderungen |
| `checks` | Verifier für Kanaltests mit gebauten Artefakten plus nur bei Pushes Node-22-Kompatibilität | Bei Node-relevanten Änderungen |
| `check-docs` | Doku-Formatierung, Lint und Broken-Link-Prüfungen | Wenn Doku geändert wurde |
| 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 als Draft markierten Pushes und PRs |
| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei nicht als Draft markierten Pushes und PRs |
| `security-dependency-audit` | Audit der produktionsrelevanten Lockfile ohne Abhängigkeiten gegen npm-Advisories | Immer bei nicht als Draft markierten Pushes und PRs |
| `security-fast` | Erforderliche Aggregation für die schnellen Sicherheitsjobs | Immer bei nicht als Draft markierten Pushes und PRs |
| `build-artifacts` | Baut `dist/`, Control UI, Prüfungen für gebaute Artefakte und wiederverwendbare Downstream-Artefakte | Bei Node-relevanten Änderungen |
| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie bundled/plugin-contract/protocol-Prüfungen | Bei Node-relevanten Änderungen |
| `checks-fast-contracts-channels` | Gesplittete Channel-Contract-Prüfungen mit einem stabilen aggregierten Prüfergebnis | Bei Node-relevanten Änderungen |
| `checks-node-extensions` | Vollständige Test-Shards für gebündelte Plugins über die gesamte Erweiterungssuite | Bei Node-relevanten Änderungen |
| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, bundled-, contract- und extension-Lanes | Bei Node-relevanten Änderungen |
| `extension-fast` | Fokussierte Tests nur für die geänderten gebündelten Plugins | Pull Requests mit Erweiterungsänderungen |
| `check` | Gesplittetes Äquivalent zum lokalen Haupt-Gate: Prod-Typen, Lint, Guards, Test-Typen und strikter Smoke-Test | Bei Node-relevanten Änderungen |
| `check-additional` | Architektur-, Boundary-, Erweiterungsflächen-Guards, Package-Boundary- und Gateway-Watch-Shards | Bei Node-relevanten Änderungen |
| `build-smoke` | Smoke-Tests für gebaute CLI und Startup-Memory-Smoke | Bei Node-relevanten Änderungen |
| `checks` | Verifier für gebaute-Artefakt-Channel-Tests plus nur für Pushes Node-22-Kompatibilität | Bei Node-relevanten Änderungen |
| `check-docs` | Docs-Formatierung, Lint und Prüfungen auf defekte Links | Wenn Docs geändert wurden |
| `skills-python` | Ruff + pytest für Python-basierte Skills | Bei Python-Skills-relevanten Änderungen |
| `checks-windows` | Windows-spezifische Test-Lanes | Bei Windows-relevanten Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam genutzten gebauten Artefakten | Bei macOS-relevanten Änderungen |
| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | Bei macOS-relevanten Änderungen |
| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Bei Android-relevanten Änderungen |
| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | CI-Erfolg auf Main oder manueller Dispatch |
| `checks-windows` | Windows-spezifische Test-Lanes | Bei Windows-relevanten Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam genutzten gebauten Artefakten | Bei macOS-relevanten Änderungen |
| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | Bei macOS-relevanten Änderungen |
| `android` | Android-Unit-Tests für beide Varianten plus ein Debug-APK-Build | Bei Android-relevanten Änderungen |
| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Erfolg der Main-CI oder manueller Dispatch |
## Fail-Fast-Reihenfolge
Die Jobs sind so angeordnet, dass günstige Prüfungen fehlschlagen, bevor teure laufen:
Jobs sind so angeordnet, dass günstige Prüfungen fehlschlagen, bevor teure ausgeführt werden:
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 mit den schnellen Linux-Lanes, sodass nachgelagerte Konsumenten starten können, sobald der gemeinsame Build bereit ist.
4. Schwerere Plattform- und Laufzeit-Lanes fächern sich danach auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, das nur für PRs laufende `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`.
3. `build-artifacts` überlappt mit den schnellen Linux-Lanes, sodass nachgelagerte Verbraucher starten können, sobald der gemeinsame Build bereit ist.
4. Danach fächern sich die schwereren Plattform- und Laufzeit-Lanes auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, das nur für PRs laufende `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`.
Die Scope-Logik lebt in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt.
Änderungen am CI-Workflow validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber nicht von sich aus Windows-, Android- oder macOS-Native-Builds; diese Plattform-Lanes bleiben auf Änderungen an plattformspezifischem Quellcode beschränkt.
Windows-Node-Prüfungen sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm/pnpm/UI-Runner-Helfer, Package-Manager-Konfiguration und die CI-Workflow-Oberflächen begrenzt, die diese Lane ausführen; nicht zusammenhängende Source-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes, damit sie keinen Windows-Worker mit 16 vCPUs für Abdeckung reservieren, die bereits durch die normalen Test-Shards ausgeübt wird.
Der separate Workflow `install-smoke` verwendet dasselbe Scope-Skript über seinen eigenen `preflight`-Job wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke` auf. Pull Requests führen den schnellen Pfad für Docker-/Package-Oberflächen, Package-/Manifest-Änderungen gebündelter Plugins und Core-Plugin-/Kanal-/Gateway-/Plugin-SDK-Oberflächen aus, die von den Docker-Smoke-Jobs verwendet werden. Reine Source-Ä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 das Container-Gateway-Network-E2E aus, verifiziert ein Build-Arg einer gebündelten Extension und führt das begrenzte Docker-Profil für gebündelte Plugins unter einem Befehls-Timeout von 120 Sekunden aus. Der vollständige Pfad behält QR-Package-Install sowie Installer-Docker-/Update-Abdeckung für nächtliche geplante Läufe, manuelle Dispatches, Release-Prüfungen per Workflow-Call und Pull Requests bei, die tatsächlich Installer-/Package-/Docker-Oberflächen berühren. Pushes nach `main`, einschließlich Merge-Commits, erzwingen nicht den vollständigen Pfad; wenn die Logik des Changed-Scope 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 Smoke für globalen Bun-Install des Image-Providers wird separat durch `run_bun_global_install_smoke` gegatet; er läuft im nächtlichen Zeitplan und aus dem Workflow für Release-Checks, und manuelle `install-smoke`-Dispatches können ihn optional einschließen, aber Pull Requests und Pushes nach `main` führen ihn nicht aus. QR- und Installer-Docker-Tests behalten ihre eigenen installfokussierten Dockerfiles. Lokal baut `test:docker:all` ein gemeinsames Live-Test-Image und ein gemeinsames Built-App-Image aus `scripts/e2e/Dockerfile` vor und führt dann die Live-/E2E-Smoke-Lanes parallel mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus; stimmen Sie die standardmäßige Parallelität des Main-Pools von 8 mit `OPENCLAW_DOCKER_ALL_PARALLELISM` und die standardmäßige Parallelität des provider-sensitiven Tail-Pools von 8 mit `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` ab. Das lokale Aggregat plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, und jede Lane hat ein Timeout von 120 Minuten, überschreibbar mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Der wiederverwendbare Live-/E2E-Workflow spiegelt das Muster gemeinsamer Images, indem er vor der Docker-Matrix ein SHA-getaggtes GHCR-Docker-E2E-Image baut und pusht und dann die Matrix mit `OPENCLAW_SKIP_DOCKER_BUILD=1` ausführt. Der geplante Live-/E2E-Workflow führt täglich die vollständige Docker-Suite des Release-Pfads aus. Die vollständige Matrix für Updates/Kanäle gebündelter Plugins bleibt manuell bzw. Full-Suite, weil sie wiederholte echte npm-Update- und Doctor-Repair-Durchläufe ausführt.
Die Scope-Logik liegt in `scripts/ci-changed-scope.mjs` und wird durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt.
Änderungen am CI-Workflow validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber nicht von sich aus Windows-, Android- oder macOS-native Builds; diese Plattform-Lanes bleiben auf Änderungen an Plattformquellen beschränkt.
Windows-Node-Prüfungen sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm/pnpm/UI-Runner-Helfer, Package-Manager-Konfiguration und die CI-Workflow-Oberflächen beschränkt, die diese Lane ausführen; nicht zusammenhängende Source-, Plugin-, install-smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes, damit sie keinen Windows-Worker mit 16 vCPU für Abdeckung reservieren, die bereits durch die normalen Test-Shards ausgeübt wird.
Der separate Workflow `install-smoke` verwendet dasselbe Scope-Skript über seinen eigenen `preflight`-Job wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke`. Pull Requests führen den schnellen Pfad für Docker-/Package-Oberflächen, gebündelte Plugin-Package-/Manifest-Änderungen und Core-Plugin-/Channel-/Gateway-/Plugin-SDK-Oberflächen aus, die von den Docker-Smoke-Jobs abgedeckt werden. Reine Source-Änderungen an gebündelten Plugins, reine Teständerungen und reine Docs-Änderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt das Container-Gateway-Network-E2E aus, verifiziert ein Build-Arg für eine gebündelte Erweiterung und führt das begrenzte Docker-Profil für gebündelte Plugins mit einem Befehls-Timeout von 120 Sekunden aus. Der vollständige Pfad behält Paketinstallation per QR und 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-/Package-/Docker-Oberflächen betreffen. Pushes auf `main`, einschließlich Merge-Commits, erzwingen nicht den vollständigen Pfad; wenn die changed-scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke bei und überlässt den vollständigen Install-Smoke der nächtlichen oder Release-Validierung. Der langsame Smoke für den globalen Bun-Install mit Image-Provider wird separat durch `run_bun_global_install_smoke` gesteuert; er läuft nachts und aus dem Release-Checks-Workflow heraus, und manuelle `install-smoke`-Dispatches können ihn optional einschalten, aber Pull Requests und Pushes auf `main` führen ihn nicht aus. QR- und Installer-Docker-Tests behalten ihre eigenen installationsfokussierten Dockerfiles. Lokal baut `test:docker:all` ein gemeinsames Live-Test-Image und ein gemeinsames Built-App-Image aus `scripts/e2e/Dockerfile` vor und führt dann die Live-/E2E-Smoke-Lanes parallel mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus; stimmen Sie die Standard-Konkurrenz des Haupt-Pools von 8 mit `OPENCLAW_DOCKER_ALL_PARALLELISM` und die Konkurrenz des provider-sensitiven Tail-Pools von 8 mit `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` ab. Standardmäßig werden Lane-Starts um 2 Sekunden versetzt, um lokale Docker-Daemon-Erstellungsstürme zu vermeiden; überschreiben Sie dies mit `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` oder einem anderen Millisekundenwert. Das lokale Aggregat plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, und jede Lane hat ein Timeout von 120 Minuten, das mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` überschrieben werden kann. Der wiederverwendbare Live-/E2E-Workflow spiegelt das Muster gemeinsamer Images, indem er vor der Docker-Matrix ein per SHA getaggtes GHCR-Docker-E2E-Image baut und pusht und dann die Matrix mit `OPENCLAW_SKIP_DOCKER_BUILD=1` ausführt. Der geplante Live-/E2E-Workflow führt täglich die vollständige Docker-Suite des Release-Pfads aus. Die vollständige Matrix für gebündelte Updates/Channels bleibt manuell/vollständig, weil sie wiederholte echte npm-Update- und doctor-repair-Durchläufe ausführt.
Die Logik geänderter Lanes für lokale Läufe lebt in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Gate ist hinsichtlich Architekturgrenzen strenger als das breite CI-Plattform-Scoping: Änderungen an der Core-Produktion führen Core-Prod-Typecheck plus Core-Tests aus, reine Core-Teständerungen führen nur Core-Test-Typecheck/Tests aus, Änderungen an der Extension-Produktion führen Extension-Prod-Typecheck plus Extension-Tests aus, und reine Extension-Teständerungen führen nur Extension-Test-Typecheck/Tests aus. Änderungen am öffentlichen Plugin SDK oder an Plugin-Contracts erweitern auf Extension-Validierung, weil Extensions von diesen Core-Contracts abhängen. Reine Versionssprünge in Release-Metadaten führen gezielte Prüfungen für Version/Konfiguration/Root-Abhängigkeiten aus. Unbekannte Root-/Konfigurationsänderungen schlagen sicherheitshalber auf alle Lanes durch.
Die lokale Logik für geänderte Lanes liegt in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Gate ist bei Architekturgrenzen strenger als das breite CI-Plattform-Scoping: Core-Produktionsänderungen führen Core-Prod-Typecheck plus Core-Tests aus, reine Core-Teständerungen führen nur Core-Test-Typecheck/-Tests aus, Produktionsänderungen an Erweiterungen führen Extension-Prod-Typecheck plus Extension-Tests aus, und reine Extension-Teständerungen führen nur Extension-Test-Typecheck/-Tests aus. Änderungen am öffentlichen Plugin SDK oder am Plugin-Contract erweitern die Validierung auf Erweiterungen, weil Erweiterungen von diesen Core-Contracts abhängen. Versionssprünge nur in Release-Metadaten führen gezielte Prüfungen für Version/Config/Root-Abhängigkeiten aus. Unbekannte Root-/Config-Änderungen schlagen sicherheitshalber auf alle Lanes durch.
Bei Pushes fügt die Matrix `checks` die nur bei Pushes laufende Lane `compat-node22` hinzu. Bei Pull Requests wird diese Lane übersprungen und die Matrix bleibt auf die normalen Test-/Kanal-Lanes fokussiert.
Bei Pushes fügt die `checks`-Matrix die nur für Pushes geltende Lane `compat-node22` hinzu. Bei Pull Requests wird diese Lane übersprungen, und die Matrix bleibt auf die normalen Test-/Channel-Lanes fokussiert.
Die langsamsten Node-Testfamilien werden aufgeteilt oder ausbalanciert, sodass jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Kanal-Contracts laufen als drei gewichtete Shards, Tests für gebündelte Plugins werden über sechs Extension-Worker ausbalanciert, kleine Core-Unit-Lanes werden gepaart, Auto-Reply läuft als drei ausbalancierte Worker statt sechs winziger Worker, und agentische Gateway-/Plugin-Konfigurationen werden über die bestehenden source-only agentischen Node-Jobs verteilt, statt auf gebaute Artefakte zu warten. Umfangreiche Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Catch-all für Plugins. Extension-Shard-Jobs führen Plugin-Konfigurationsgruppen seriell mit einem Vitest-Worker und einem größeren Node-Heap aus, damit importlastige Plugin-Batches kleine CI-Runner nicht überbelegen. Die breite Agents-Lane verwendet den gemeinsamen dateiparallelen Vitest-Scheduler, weil sie eher von Importen/Planung dominiert wird als von einer einzelnen langsamen Testdatei. `runtime-config` läuft mit dem Infra-Core-Runtime-Shard, damit das gemeinsame Runtime-Shard nicht das Tail übernimmt. `check-additional` hält Package-Boundary-Compile-/Canary-Arbeit zusammen und trennt Laufzeit-Topologie-Architektur von Gateway-Watch-Abdeckung; das Boundary-Guard-Shard führt seine kleinen unabhängigen Guards parallel innerhalb eines Jobs aus. Gateway-Watch, Kanaltests und das Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden, behalten ihre alten Check-Namen als leichtgewichtige Verifier-Jobs bei und vermeiden dabei zwei zusätzliche Blacksmith-Worker und eine zweite Queue für Artefakt-Konsumenten.
Die langsamsten Node-Testfamilien werden aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Contracts laufen als drei gewichtete Shards, Tests für gebündelte Plugins werden über sechs Erweiterungs-Worker ausbalanciert, kleine Core-Unit-Lanes werden gepaart, Auto-Reply läuft als drei ausbalancierte Worker statt als sechs winzige Worker, und agentische Gateway-/Plugin-Konfigurationen werden über die bestehenden source-only agentischen Node-Jobs verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-all. Jobs für Erweiterungs-Shards führen Plugin-Konfigurationsgruppen seriell mit einem Vitest-Worker und einem größeren Node-Heap aus, damit importlastige Plugin-Batches kleine CI-Runner nicht überbelegen. Die breite Agents-Lane verwendet den gemeinsamen dateiparallelen Vitest-Scheduler, weil sie von Importen/Planung dominiert wird statt von einer einzelnen langsamen Testdatei. `runtime-config` läuft mit dem Infra-Core-Runtime-Shard, damit der gemeinsame Runtime-Shard nicht das Tail besitzt. `check-additional` hält Package-Boundary-Compile-/Canary-Arbeit zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; der Boundary-Guard-Shard führt seine kleinen unabhängigen Guards innerhalb eines Jobs gleichzeitig aus. Gateway-Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` gleichzeitig, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden, wodurch ihre bisherigen Check-Namen als leichtgewichtige Verifier-Jobs erhalten bleiben, während zwei zusätzliche Blacksmith-Worker und eine zweite Artifact-Consumer-Warteschlange vermieden werden.
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 diesen Flavor dennoch mit den BuildConfig-Flags für SMS/Anrufprotokoll, vermeidet dabei aber einen doppelten Debug-APK-Packaging-Job bei jedem Android-relevanten Push.
`extension-fast` ist nur für PRs vorgesehen, weil Push-Läufe bereits die vollständigen Shards für gebündelte Plugins ausführen. Das hält das Feedback zu geänderten Plugins für Reviews aufrecht, ohne auf `main` einen zusätzlichen Blacksmith-Worker für Abdeckung zu reservieren, die bereits in `checks-node-extensions` vorhanden ist.
Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut dann die Play-Debug-APK. Die Third-Party-Variante hat kein separates Source-Set und kein separates Manifest; ihre Unit-Test-Lane kompiliert diese Variante trotzdem mit den BuildConfig-Flags für SMS/Anrufprotokoll, vermeidet dabei aber bei jedem Android-relevanten Push einen doppelten Packaging-Job für Debug-APKs.
`extension-fast` ist nur für PRs, weil Push-Läufe bereits die vollständigen Shards für gebündelte Plugins ausführen. Das hält Feedback zu geänderten Plugins für Reviews verfügbar, ohne auf `main` einen zusätzlichen Blacksmith-Worker für Abdeckung zu reservieren, die bereits in `checks-node-extensions` vorhanden ist.
GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR oder derselben `main`-Ref landet. Behandeln Sie das als CI-Rauschen, es sei denn, der neueste Lauf für dieselbe Ref schlägt ebenfalls fehl. Aggregierte Shard-Checks verwenden `!cancelled() && always()`, sodass sie weiterhin normale Shard-Fehler melden, aber nicht mehr in die Queue kommen, nachdem der gesamte Workflow bereits ersetzt wurde.
Der CI-Concurrency-Key ist versioniert (`CI-v7-*`), sodass ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann.
GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf derselben PR oder auf derselben `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern der neueste Lauf für dieselbe Ref nicht ebenfalls fehlschlägt. Aggregierte Shard-Checks verwenden `!cancelled() && always()`, damit sie weiterhin normale Shard-Fehler melden, aber nicht erst in die Warteschlange gehen, nachdem der gesamte Workflow bereits ersetzt wurde.
Der CI-Concurrency-Key ist versioniert (`CI-v7-*`), damit ein zombieartiger GitHub-Eintrag in einer alten Warteschlangengruppe neuere Main-Läufe nicht unbegrenzt blockieren kann.
## Runner
| Runner | Jobs |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, schnelle Sicherheitsjobs und Aggregate (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Contract-/Bundled-Prüfungen, geshardete Kanal-Contract-Prüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregate, Aggregate-Verifier für Node-Tests, Doku-Prüfungen, Python-Skills, workflow-sanity, labeler, auto-response; das `install-smoke`-Preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Queue gehen kann |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux-Node-Test-Shards, Test-Shards für gebündelte Plugins, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, das weiterhin so CPU-sensitiv ist, dass 8 vCPU mehr kosten als sparen; `install-smoke`-Docker-Builds, bei denen die Queue-Zeit für 32 vCPU mehr kostete als sie sparte |
| `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 Sicherheitsjobs 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`-Shards und -Aggregate, Node-Test-Aggregat-Verifier, Docs-Prüfungen, Python-Skills, workflow-sanity, labeler, auto-response; install-smoke-preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Warteschlange gehen kann |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux-Node-Test-Shards, Test-Shards für gebündelte Plugins, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, das weiterhin CPU-sensitiv genug ist, dass 8 vCPU mehr kosteten, als sie einsparten; install-smoke-Docker-Builds, bei denen die Warteschlangenzeit für 32 vCPU mehr kostete, 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 Äquivalente
```bash
pnpm changed:lanes # den lokalen Klassifizierer für geänderte Lanes für origin/main...HEAD prüfen
pnpm changed:lanes # den lokalen Klassifikator für geänderte Lanes für origin/main...HEAD prüfen
pnpm check:changed # intelligentes lokales Gate: geänderter Typecheck/Lint/Tests nach Boundary-Lane
pnpm check # schnelles lokales Gate: Produktions-tsgo + geshardetes Lint + parallele schnelle Guards
pnpm check # schnelles lokales Gate: produktionsrelevantes tsgo + geshardetes Lint + parallele schnelle Guards
pnpm check:test-types
pnpm check:timed # dasselbe Gate mit Zeitmessungen pro Phase
pnpm check:timed # dasselbe Gate mit Timing pro Phase
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test # Vitest-Tests
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs # Doku-Format + Lint + Broken Links
pnpm check:docs # Docs-Formatierung + Lint + defekte Links
pnpm build # `dist` bauen, wenn CI-Artefakt-/build-smoke-Lanes relevant sind
node scripts/ci-run-timings.mjs <run-id> # Wall Time, Queue Time und langsamste Jobs zusammenfassen
node scripts/ci-run-timings.mjs <run-id> # Laufzeit, Warteschlangenzeit und langsamste Jobs zusammenfassen
node scripts/ci-run-timings.mjs --recent 10 # aktuelle erfolgreiche Main-CI-Läufe vergleichen
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json

77
docs/de/cli/node.md
View File

@ -1,48 +1,42 @@
---
read_when:
- Den Headless-Node-Host ausführen
- Einen Nicht-macOS-Node für `system.run` pairen
- Einen Nicht-macOS-Node für `system.run` koppeln
summary: CLI-Referenz für `openclaw node` (Headless-Node-Host)
title: Node
x-i18n:
generated_at: "2026-04-24T06:32:01Z"
generated_at: "2026-04-24T08:57:05Z"
model: gpt-5.4
provider: openai
source_hash: 61b16bdd0c52115bc9938a0fc975369159a4e45d743173ab4e65fce8292af51e
source_hash: 9f2bd6d61ee87d36f7691207d03a91c914e6460549256e0cc6ea7bebfa713923
source_path: cli/node.md
workflow: 15
---
# `openclaw node`
Einen **Headless-Node-Host** ausführen, der sich mit dem Gateway-WebSocket verbindet und auf
diesem Rechner `system.run` / `system.which` bereitstellt.
Führen Sie einen **Headless-Node-Host** aus, der sich mit dem Gateway-WebSocket verbindet und auf diesem Rechner `system.run` / `system.which` bereitstellt.
## Warum einen Node-Host verwenden?
Verwenden Sie einen Node-Host, wenn Sie möchten, dass Agenten **Befehle auf anderen Rechnern** in Ihrem
Netzwerk ausführen, ohne dort eine vollständige macOS-Begleit-App zu installieren.
Verwenden Sie einen Node-Host, wenn Sie möchten, dass Agents **Befehle auf anderen Rechnern** in Ihrem Netzwerk ausführen, ohne dort eine vollständige macOS-Companion-App zu installieren.
Häufige Anwendungsfälle:
- Befehle auf entfernten Linux-/Windows-Rechnern ausführen (Build-Server, Lab-Rechner, NAS).
- Die Exec-Ausführung auf dem Gateway **sandboxed** halten, aber genehmigte Ausführungen an andere Hosts delegieren.
- Ein leichtgewichtiges, headless Ausführungsziel für Automatisierung oder CI-Nodes bereitstellen.
- Befehle auf entfernten Linux-/Windows-Rechnern ausführen (Build-Server, Laborrechner, NAS).
- Exec auf dem Gateway **isoliert** halten, aber genehmigte Ausführungen an andere Hosts delegieren.
- Ein leichtgewichtiges, Headless-Ausführungsziel für Automatisierung oder CI-Nodes bereitstellen.
Die Ausführung wird weiterhin durch **Exec-Genehmigungen** und agent-spezifische Allowlists auf dem
Node-Host geschützt, sodass Sie den Befehlszugriff eingegrenzt und explizit halten können.
Die Ausführung wird weiterhin durch **Exec-Freigaben** und Allowlists pro Agent auf dem Node-Host geschützt, sodass Sie den Befehlszugriff begrenzt und explizit halten können.
## Browser-Proxy (ohne Konfiguration)
Node-Hosts kündigen automatisch einen Browser-Proxy an, wenn `browser.enabled` auf dem Node nicht
deaktiviert ist. Dadurch kann der Agent Browser-Automatisierung auf diesem Node ohne zusätzliche Konfiguration verwenden.
Node-Hosts kündigen automatisch einen Browser-Proxy an, wenn `browser.enabled` auf dem Node nicht deaktiviert ist. Dadurch kann der Agent die Browser-Automatisierung auf diesem Node ohne zusätzliche Konfiguration verwenden.
Standardmäßig stellt der Proxy die normale Browser-Profiloberfläche des Nodes bereit. Wenn Sie
`nodeHost.browserProxy.allowProfiles` setzen, wird der Proxy restriktiv:
Nicht per Allowlist zugelassenes Profil-Targeting wird abgelehnt, und Routen zum Erstellen/Löschen
persistenter Profile werden über den Proxy blockiert.
Standardmäßig stellt der Proxy die normale Browser-Profile-Oberfläche des Nodes bereit. Wenn Sie `nodeHost.browserProxy.allowProfiles` festlegen, wird der Proxy restriktiv:
Zugriffe auf nicht allowlistete Profile werden abgelehnt, und Routen zum Erstellen/Löschen persistenter Profile werden über den Proxy blockiert.
Bei Bedarf auf dem Node deaktivieren:
Deaktivieren Sie ihn bei Bedarf auf dem Node:
```json5
{
@ -66,28 +60,27 @@ Optionen:
- `--port <port>`: Gateway-WebSocket-Port (Standard: `18789`)
- `--tls`: TLS für die Gateway-Verbindung verwenden
- `--tls-fingerprint <sha256>`: Erwarteter TLS-Zertifikats-Fingerprint (sha256)
- `--node-id <id>`: Node-ID überschreiben (löscht Pairing-Token)
- `--node-id <id>`: Node-ID überschreiben (setzt Pairing-Token zurück)
- `--display-name <name>`: Anzeigenamen des Nodes überschreiben
## Gateway-Authentifizierung für den Node-Host
`openclaw node run` und `openclaw node install` lösen die Gateway-Authentifizierung aus Konfiguration/Umgebung auf (keine `--token`-/`--password`-Flags bei Node-Befehlen):
`openclaw node run` und `openclaw node install` lösen die Gateway-Authentifizierung aus config/env auf (keine `--token`-/`--password`-Flags bei Node-Befehlen):
- `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` werden zuerst geprüft.
- Dann lokaler Konfigurations-Fallback: `gateway.auth.token` / `gateway.auth.password`.
- Danach lokaler Config-Fallback: `gateway.auth.token` / `gateway.auth.password`.
- Im lokalen Modus übernimmt der Node-Host absichtlich nicht `gateway.remote.token` / `gateway.remote.password`.
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht aufgelöst ist, schlägt die Auflösung der Node-Authentifizierung fail-closed fehl (kein Maskieren durch Remote-Fallback).
- In `gateway.mode=remote` kommen Remote-Client-Felder (`gateway.remote.token` / `gateway.remote.password`) gemäß den Remote-Prioritätsregeln ebenfalls infrage.
- Die Authentifizierungsauflösung des Node-Hosts berücksichtigt nur `OPENCLAW_GATEWAY_*`-Umgebungsvariablen.
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht aufgelöst ist, schlägt die Auflösung der Node-Authentifizierung kontrolliert fehl (kein Remote-Fallback, der dies verdeckt).
- In `gateway.mode=remote` kommen gemäß den Vorrangregeln für Remote auch die Felder des Remote-Clients (`gateway.remote.token` / `gateway.remote.password`) infrage.
- Die Auflösung der Node-Host-Authentifizierung berücksichtigt nur `OPENCLAW_GATEWAY_*`-Umgebungsvariablen.
Für einen Node, der sich mit einem nicht-loopback `ws://`-Gateway in einem vertrauenswürdigen privaten
Netzwerk verbindet, setzen Sie `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`. Ohne dies schlägt der Node-Start fail-closed fehl
und fordert Sie auf, `wss://`, einen SSH-Tunnel oder Tailscale zu verwenden.
`openclaw node install` persistiert dieses Opt-in in den überwachten Node-Service.
Für einen Node, der sich mit einem Nicht-Loopback-`ws://`-Gateway in einem vertrauenswürdigen privaten Netzwerk verbindet, setzen Sie `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`. Ohne diese Einstellung schlägt der Start des Nodes kontrolliert fehl und fordert Sie auf, `wss://`, einen SSH-Tunnel oder Tailscale zu verwenden.
Dies ist ein Prozess-Umgebungs-Opt-in und kein Config-Schlüssel in `openclaw.json`.
`openclaw node install` speichert diese Einstellung im überwachten Node-Service, wenn sie in der Befehlsumgebung von install vorhanden ist.
## Service (Hintergrund)
Installieren Sie einen Headless-Node-Host als Benutzerservice.
Installieren Sie einen Headless-Node-Host als Benutzerdienst.
```bash
openclaw node install --host <gateway-host> --port 18789
@ -99,10 +92,10 @@ Optionen:
- `--port <port>`: Gateway-WebSocket-Port (Standard: `18789`)
- `--tls`: TLS für die Gateway-Verbindung verwenden
- `--tls-fingerprint <sha256>`: Erwarteter TLS-Zertifikats-Fingerprint (sha256)
- `--node-id <id>`: Node-ID überschreiben (löscht Pairing-Token)
- `--node-id <id>`: Node-ID überschreiben (setzt Pairing-Token zurück)
- `--display-name <name>`: Anzeigenamen des Nodes überschreiben
- `--runtime <runtime>`: Service-Laufzeit (`node` oder `bun`)
- `--force`: Neu installieren/überschreiben, falls bereits installiert
- `--force`: Neu installieren/überschreiben, wenn bereits installiert
Den Service verwalten:
@ -120,31 +113,27 @@ Service-Befehle akzeptieren `--json` für maschinenlesbare Ausgabe.
## Pairing
Die erste Verbindung erstellt auf dem Gateway eine ausstehende Geräte-Pairing-Anfrage (`role: node`).
Genehmigen Sie sie mit:
Bestätigen Sie sie mit:
```bash
openclaw devices list
openclaw devices approve <requestId>
```
Wenn der Node das Pairing mit geänderten Authentifizierungsdetails (Rolle/Scopes/öffentlicher Schlüssel) erneut versucht,
wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId` erstellt.
Führen Sie vor der Genehmigung erneut `openclaw devices list` aus.
Wenn der Node das Pairing mit geänderten Authentifizierungsdetails (Rolle/Scopes/öffentlicher Schlüssel) erneut versucht, wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId` erstellt.
Führen Sie vor der Bestätigung erneut `openclaw devices list` aus.
Der Node-Host speichert seine Node-ID, sein Token, seinen Anzeigenamen und die Gateway-Verbindungsinformationen in
`~/.openclaw/node.json`.
Der Node-Host speichert seine Node-ID, sein Token, seinen Anzeigenamen und die Informationen zur Gateway-Verbindung in `~/.openclaw/node.json`.
## Exec-Genehmigungen
## Exec-Freigaben
`system.run` wird durch lokale Exec-Genehmigungen geschützt:
`system.run` wird durch lokale Exec-Freigaben gesteuert:
- `~/.openclaw/exec-approvals.json`
- [Exec-Genehmigungen](/de/tools/exec-approvals)
- [Exec-Freigaben](/de/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>` (vom Gateway aus bearbeiten)
Für genehmigte asynchrone Node-Exec bereitet OpenClaw vor der Aufforderung einen kanonischen `systemRunPlan` vor. Die später genehmigte `system.run`-Weiterleitung verwendet dann diesen gespeicherten
Plan wieder, sodass Änderungen an command-/cwd-/session-Feldern nach Erstellung der Genehmigungsanfrage
abgelehnt werden, anstatt zu ändern, was der Node ausführt.
Für genehmigte asynchrone Node-Ausführung bereitet OpenClaw vor der Aufforderung einen kanonischen `systemRunPlan` vor. Die später genehmigte `system.run`-Weiterleitung verwendet diesen gespeicherten Plan erneut, sodass Änderungen an Feldern für command/cwd/session nach Erstellung der Freigabeanfrage abgelehnt werden, statt zu ändern, was der Node ausführt.
## Verwandt

85
docs/de/cli/onboard.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Sie möchten eine geführte Einrichtung für Gateway, Workspace, Auth, Kanäle und Skills
- Sie möchten eine geführte Einrichtung für Gateway, Workspace, Auth, Channels und Skills.
summary: CLI-Referenz für `openclaw onboard` (interaktives Onboarding)
title: Onboard
title: Onboarding
x-i18n:
generated_at: "2026-04-24T06:32:07Z"
generated_at: "2026-04-24T08:57:06Z"
model: gpt-5.4
provider: openai
source_hash: ab92ff5651b7db18850558cbb47527bf0486f278c8aed0929eaeff0017b6c280
source_hash: c1959ad7014b891230e497a2e0ab494ba316090c81629f25b8147614b694ead5
source_path: cli/onboard.md
workflow: 15
---
# `openclaw onboard`
Interaktives Onboarding für die lokale oder Remote-Gateway-Einrichtung.
Interaktives Onboarding für die lokale oder entfernte Gateway-Einrichtung.
## Verwandte Leitfäden
## Verwandte Anleitungen
- CLI-Onboarding-Hub: [Onboarding (CLI)](/de/start/wizard)
- Onboarding-Übersicht: [Onboarding Overview](/de/start/onboarding-overview)
@ -33,8 +33,10 @@ openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
Für unverschlüsselte `ws://`-Ziele in privaten Netzwerken (nur vertrauenswürdige Netzwerke) setzen Sie
Für Klartext-`ws://`-Ziele in privaten Netzwerken (nur vertrauenswürdige Netzwerke) setzen Sie
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` in der Prozessumgebung des Onboardings.
Es gibt kein `openclaw.json`-Äquivalent für diesen clientseitigen Transport-
Notfallmechanismus.
Nicht-interaktiver benutzerdefinierter Provider:
@ -50,7 +52,7 @@ openclaw onboard --non-interactive \
`--custom-api-key` ist im nicht-interaktiven Modus optional. Wenn es weggelassen wird, prüft das Onboarding `CUSTOM_API_KEY`.
LM Studio unterstützt im nicht-interaktiven Modus auch ein providerspezifisches Schlüssel-Flag:
LM Studio unterstützt im nicht-interaktiven Modus auch ein providerspezifisches Key-Flag:
```bash
openclaw onboard --non-interactive \
@ -71,9 +73,9 @@ openclaw onboard --non-interactive \
--accept-risk
```
`--custom-base-url` hat standardmäßig den Wert `http://127.0.0.1:11434`. `--custom-model-id` ist optional; wenn es weggelassen wird, verwendet das Onboarding die vorgeschlagenen Standardwerte von Ollama. Cloud-Modell-IDs wie `kimi-k2.5:cloud` funktionieren hier ebenfalls.
`--custom-base-url` ist standardmäßig `http://127.0.0.1:11434`. `--custom-model-id` ist optional; wenn es weggelassen wird, verwendet das Onboarding die von Ollama vorgeschlagenen Standardwerte. Cloud-Modell-IDs wie `kimi-k2.5:cloud` funktionieren hier ebenfalls.
Providerschlüssel statt als Klartext als Referenzen speichern:
Provider-Schlüssel als Referenzen statt als Klartext speichern:
```bash
openclaw onboard --non-interactive \
@ -83,25 +85,25 @@ openclaw onboard --non-interactive \
```
Mit `--secret-input-mode ref` schreibt das Onboarding env-gestützte Referenzen statt Klartext-Schlüsselwerten.
Bei Providern mit Auth-Profil-Unterstützung werden dadurch `keyRef`-Einträge geschrieben; bei benutzerdefinierten Providern schreibt dies `models.providers.<id>.apiKey` als env-Referenz (zum Beispiel `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
Bei auth-profile-gestützten Providern schreibt dies `keyRef`-Einträge; bei benutzerdefinierten Providern schreibt es `models.providers.<id>.apiKey` als env-Referenz (zum Beispiel `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
Vertrag für den nicht-interaktiven Modus `ref`:
Vertrag für den nicht-interaktiven `ref`-Modus:
- Setzen Sie die Provider-Umgebungsvariable in der Prozessumgebung des Onboardings (zum Beispiel `OPENAI_API_KEY`).
- Übergeben Sie keine Inline-Schlüssel-Flags (zum Beispiel `--openai-api-key`), es sei denn, diese Umgebungsvariable ist ebenfalls gesetzt.
- Wenn ein Inline-Schlüssel-Flag ohne die erforderliche Umgebungsvariable übergeben wird, schlägt das Onboarding sofort mit Hinweisen fehl.
- Setzen Sie die env-Variable des Providers in der Prozessumgebung des Onboardings (zum Beispiel `OPENAI_API_KEY`).
- Übergeben Sie keine Inline-Key-Flags (zum Beispiel `--openai-api-key`), es sei denn, diese env-Variable ist ebenfalls gesetzt.
- Wenn ein Inline-Key-Flag ohne die erforderliche env-Variable übergeben wird, schlägt das Onboarding sofort mit Hinweisen fehl.
Optionen für Gateway-Token im nicht-interaktiven Modus:
Gateway-Token-Optionen im nicht-interaktiven Modus:
- `--gateway-auth token --gateway-token <token>` speichert ein Klartext-Token.
- `--gateway-auth token --gateway-token-ref-env <name>` speichert `gateway.auth.token` als env-SecretRef.
- `--gateway-token` und `--gateway-token-ref-env` schließen sich gegenseitig aus.
- `--gateway-token-ref-env` erfordert eine nicht leere Umgebungsvariable in der Prozessumgebung des Onboardings.
- Mit `--install-daemon` werden SecretRef-verwaltete Gateway-Tokens validiert, wenn die Token-Authentifizierung ein Token erfordert, aber nicht als aufgelöster Klartext in den Umgebungsmetadaten des Supervisor-Dienstes gespeichert.
- Mit `--install-daemon` schlägt das Onboarding geschlossen fehl und gibt Hinweise zur Behebung, wenn der Token-Modus ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist.
- `--gateway-token-ref-env` erfordert eine nicht leere env-Variable in der Prozessumgebung des Onboardings.
- Mit `--install-daemon` werden, wenn Token-Auth ein Token erfordert, von SecretRef verwaltete Gateway-Token validiert, aber nicht als aufgelöster Klartext in den Umgebungsmetadaten des Supervisor-Dienstes gespeichert.
- Mit `--install-daemon` schlägt das Onboarding fehlgeschlossen mit Hinweisen zur Behebung fehl, wenn der Token-Modus ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist.
- Mit `--install-daemon` blockiert das Onboarding die Installation, bis der Modus explizit gesetzt ist, wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist.
- Lokales Onboarding schreibt `gateway.mode="local"` in die Konfiguration. Wenn in einer späteren Konfigurationsdatei `gateway.mode` fehlt, behandeln Sie das als Konfigurationsschaden oder unvollständige manuelle Bearbeitung, nicht als gültige Abkürzung für den lokalen Modus.
- `--allow-unconfigured` ist ein separater Laufzeit-Escape-Hatch für Gateway. Es bedeutet nicht, dass das Onboarding `gateway.mode` weglassen darf.
- `--allow-unconfigured` ist eine separate Notfalloption für die Gateway-Laufzeit. Das bedeutet nicht, dass das Onboarding `gateway.mode` weglassen darf.
Beispiel:
@ -115,26 +117,26 @@ openclaw onboard --non-interactive \
--accept-risk
```
Nicht-interaktive Prüfung des lokalen Gateway-Zustands:
Integritätsprüfung des lokalen Gateway im nicht-interaktiven Modus:
- Wenn Sie nicht `--skip-health` übergeben, wartet das Onboarding vor erfolgreichem Beenden auf ein erreichbares lokales Gateway.
- Sofern Sie nicht `--skip-health` übergeben, wartet das Onboarding auf ein erreichbares lokales Gateway, bevor es erfolgreich beendet wird.
- `--install-daemon` startet zuerst den verwalteten Gateway-Installationspfad. Ohne diese Option muss bereits ein lokales Gateway laufen, zum Beispiel `openclaw gateway run`.
- Wenn Sie in der Automatisierung nur Konfigurations-/Workspace-/Bootstrap-Schreibvorgänge möchten, verwenden Sie `--skip-health`.
- Unter nativem Windows versucht `--install-daemon` zuerst Geplante Aufgaben und greift auf ein Anmeldeelement im benutzerspezifischen Startup-Ordner zurück, wenn das Erstellen der Aufgabe verweigert wird.
- Unter nativem Windows versucht `--install-daemon` zuerst Scheduled Tasks und fällt auf ein Anmeldeobjekt im Startup-Ordner pro Benutzer zurück, wenn das Erstellen der Aufgabe verweigert wird.
Verhalten des interaktiven Onboardings mit Referenzmodus:
Verhalten des interaktiven Onboardings im Referenzmodus:
- Wählen Sie **Use secret reference**, wenn Sie dazu aufgefordert werden.
- Wählen Sie bei der Aufforderung **Use secret reference**.
- Wählen Sie dann entweder:
- Umgebungsvariable
- Konfigurierter Secret-Provider (`file` oder `exec`)
- Das Onboarding führt vor dem Speichern der Referenz eine schnelle Vorabprüfung durch.
- Das Onboarding führt vor dem Speichern der Referenz eine schnelle Vorabvalidierung durch.
- Wenn die Validierung fehlschlägt, zeigt das Onboarding den Fehler an und lässt Sie es erneut versuchen.
Nicht-interaktive Z.AI-Endpunktauswahl:
Hinweis: `--auth-choice zai-api-key` erkennt jetzt automatisch den besten Z.AI-Endpunkt für Ihren Schlüssel (bevorzugt die allgemeine API mit `zai/glm-5.1`).
Wenn Sie speziell die Endpunkte des GLM Coding Plan möchten, wählen Sie `zai-coding-global` oder `zai-coding-cn`.
Wenn Sie speziell die GLM-Coding-Plan-Endpunkte möchten, wählen Sie `zai-coding-global` oder `zai-coding-cn`.
```bash
# Endpunktauswahl ohne Prompt
@ -156,20 +158,25 @@ openclaw onboard --non-interactive \
--mistral-api-key "$MISTRAL_API_KEY"
```
Hinweise zu den Abläufen:
Hinweise zu den Flows:
- `quickstart`: minimale Abfragen, erzeugt automatisch ein Gateway-Token.
- `manual`: vollständige Abfragen für Port/Bind/Auth (Alias von `advanced`).
- Wenn eine Auth-Auswahl einen bevorzugten Provider impliziert, filtert das Onboarding die Auswahlen für Standardmodell und Allowlist vorab auf diesen Provider. Für Volcengine und BytePlus schließt dies auch die Coding-Plan-Varianten ein (`volcengine-plan/*`, `byteplus-plan/*`).
- Wenn der Filter für bevorzugte Provider noch keine geladenen Modelle ergibt, greift das Onboarding auf den ungefilterten Katalog zurück, statt die Auswahl leer zu lassen.
- Im Schritt zur Websuche können einige Provider providerspezifische Folgeabfragen auslösen:
- **Grok** kann optionales `x_search`-Setup mit demselben `XAI_API_KEY` und einer Modellauswahl für `x_search` anbieten.
- **Kimi** kann nach der Moonshot-API-Region (`api.moonshot.ai` vs. `api.moonshot.cn`) und dem Standard-Websuchmodell von Kimi fragen.
- Verhalten des lokalen Onboardings für den DM-Bereich: [CLI Setup Reference](/de/start/wizard-cli-reference#outputs-and-internals).
- Schnellster erster Chat: `openclaw dashboard` (Control UI, keine Kanaleinrichtung).
- Benutzerdefinierter Provider: Verbinden Sie jeden mit OpenAI oder Anthropic kompatiblen Endpunkt, einschließlich gehosteter Provider, die nicht aufgelistet sind. Verwenden Sie Unknown zur automatischen Erkennung.
- `quickstart`: minimale Eingabeaufforderungen, generiert automatisch ein Gateway-Token.
- `manual`: vollständige Eingabeaufforderungen für Port/Bind/Auth (Alias von `advanced`).
- Wenn eine Auth-Auswahl einen bevorzugten Provider impliziert, filtert das Onboarding die Auswahlfelder für default-model und allowlist vorab auf diesen Provider. Für Volcengine und BytePlus entspricht dies auch den Coding-Plan-Varianten
(`volcengine-plan/*`, `byteplus-plan/*`).
- Wenn der Filter für den bevorzugten Provider noch keine geladenen Modelle ergibt, greift das Onboarding auf den ungefilterten Katalog zurück, statt das Auswahlfeld leer zu lassen.
- Im Schritt zur Websuche können einige Provider providerspezifische
Folgeaufforderungen auslösen:
- **Grok** kann eine optionale `x_search`-Einrichtung mit demselben `XAI_API_KEY`
und einer `x_search`-Modellauswahl anbieten.
- **Kimi** kann nach der Moonshot-API-Region fragen (`api.moonshot.ai` vs
`api.moonshot.cn`) und nach dem Standard-Websuchmodell von Kimi.
- Verhalten des DM-Bereichs beim lokalen Onboarding: [CLI Setup Reference](/de/start/wizard-cli-reference#outputs-and-internals).
- Schnellster Weg zum ersten Chat: `openclaw dashboard` (Control UI, keine Channel-Einrichtung).
- Benutzerdefinierter Provider: Stellen Sie eine Verbindung zu jedem mit OpenAI oder Anthropic kompatiblen Endpunkt her,
einschließlich gehosteter Provider, die nicht aufgelistet sind. Verwenden Sie Unknown zur automatischen Erkennung.
## Häufige Folge-Befehle
## Häufige Folgekommandos
```bash
openclaw configure

121
docs/de/gateway/bonjour.md
View File

@ -1,47 +1,48 @@
---
read_when:
- Probleme mit der Bonjour-Erkennung auf macOS/iOS debuggen
- mDNS-Servicetypen, TXT-Records oder Discovery-UX ändern
summary: Bonjour-/mDNS-Erkennung + Debugging (Gateway-Beacons, Clients und häufige Fehlermodi)
- Fehlerbehebung bei Bonjour-Erkennungsproblemen unter macOS/iOS
- Ändern von mDNS-Servicetypen, TXT-Einträgen oder der Erkennungs-UX
summary: Bonjour/mDNS-Erkennung + Fehlerbehebung (Gateway-Beacons, Clients und häufige Fehlermodi)
title: Bonjour-Erkennung
x-i18n:
generated_at: "2026-04-24T06:36:33Z"
generated_at: "2026-04-24T08:57:05Z"
model: gpt-5.4
provider: openai
source_hash: d5d9099ce178aca1e6e443281133928f886de965245ad0fb02ce91a27aad3989
source_hash: 62961714a0c9880be457c254e1cfc1701020ea51b89f2582757cddc8b3dd2113
source_path: gateway/bonjour.md
workflow: 15
---
# Bonjour-/mDNS-Erkennung
# Bonjour- / mDNS-Erkennung
OpenClaw verwendet Bonjour (mDNS / DNS-SD), um ein aktives Gateway (WebSocket-Endpunkt) zu erkennen.
Multicast-Browsing in `local.` ist nur ein **LAN-Komfortmerkmal**. Für netzwerkübergreifende Erkennung kann
dasselbe Beacon auch über eine konfigurierte Wide-Area-DNS-SD-Domain veröffentlicht werden. Erkennung bleibt
weiterhin Best Effort und ersetzt **nicht** SSH- oder Tailnet-basierte Konnektivität.
OpenClaw verwendet Bonjour (mDNS / DNS‑SD), um ein aktives Gateway (WebSocket-Endpunkt) zu erkennen.
Multicast-Browsing in `local.` ist eine **reine LAN-Komfortfunktion**. Das gebündelte `bonjour`
Plugin ist für die LAN-Ankündigung verantwortlich und standardmäßig aktiviert. Für netzwerkübergreifende Erkennung
kann derselbe Beacon auch über eine konfigurierte Wide-Area-DNS-SD-Domain veröffentlicht werden.
Die Erkennung bleibt weiterhin Best-Effort und **ersetzt weder SSH noch Tailnet-basierte Konnektivität**.
## Wide-Area-Bonjour (Unicast DNS-SD) über Tailscale
## Wide-Area Bonjour (Unicast DNS-SD) über Tailscale
Wenn sich Node und Gateway in unterschiedlichen Netzwerken befinden, überquert Multicast-mDNS diese
Grenze nicht. Sie können dieselbe Discovery-UX beibehalten, indem Sie auf **Unicast DNS-SD**
(„Wide-Area Bonjour“) über Tailscale umstellen.
Wenn sich Node und Gateway in unterschiedlichen Netzwerken befinden, überschreitet Multicast-mDNS
diese Grenze nicht. Sie können dieselbe Erkennungs-UX beibehalten, indem Sie auf **Unicast DNS‑SD**
("Wide‑Area Bonjour") über Tailscale umstellen.
Schritte auf hoher Ebene:
1. Führen Sie einen DNS-Server auf dem Gateway-Host aus (über Tailnet erreichbar).
2. Veröffentlichen Sie DNS-SD-Records für `_openclaw-gw._tcp` unter einer dedizierten Zone
2. Veröffentlichen Sie DNS‑SD-Einträge für `_openclaw-gw._tcp` unter einer dedizierten Zone
(Beispiel: `openclaw.internal.`).
3. Konfigurieren Sie Tailscale **Split DNS**, sodass Ihre gewählte Domain über diesen
3. Konfigurieren Sie Tailscale **Split DNS**, damit Ihre gewählte Domain über diesen
DNS-Server für Clients aufgelöst wird (einschließlich iOS).
OpenClaw unterstützt jede Discovery-Domain; `openclaw.internal.` ist nur ein Beispiel.
iOS-/Android-Nodes browsen sowohl `local.` als auch Ihre konfigurierte Wide-Area-Domain.
OpenClaw unterstützt jede Erkennungsdomain; `openclaw.internal.` ist nur ein Beispiel.
iOS-/Android-Nodes durchsuchen sowohl `local.` als auch Ihre konfigurierte Wide-Area-Domain.
### Gateway-Konfiguration (empfohlen)
```json5
{
gateway: { bind: "tailnet" }, // nur Tailnet (empfohlen)
gateway: { bind: "tailnet" }, // nur tailnet (empfohlen)
discovery: { wideArea: { enabled: true } }, // aktiviert Wide-Area-DNS-SD-Veröffentlichung
}
```
@ -54,10 +55,10 @@ openclaw dns setup --apply
Dadurch wird CoreDNS installiert und so konfiguriert, dass es:
- auf Port 53 nur auf den Tailscale-Schnittstellen des Gateway lauscht
- nur auf Port 53 an den Tailscale-Schnittstellen des Gateway lauscht
- Ihre gewählte Domain (Beispiel: `openclaw.internal.`) aus `~/.openclaw/dns/<domain>.db` bereitstellt
Von einem mit dem Tailnet verbundenen Rechner validieren:
Validieren Sie dies von einem mit dem Tailnet verbundenen Rechner aus:
```bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.
@ -69,24 +70,26 @@ dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
In der Tailscale-Admin-Konsole:
- Fügen Sie einen Nameserver hinzu, der auf die Tailnet-IP des Gateway zeigt (UDP/TCP 53).
- Fügen Sie Split DNS hinzu, sodass Ihre Discovery-Domain diesen Nameserver verwendet.
- Fügen Sie Split DNS hinzu, damit Ihre Erkennungsdomain diesen Nameserver verwendet.
Sobald Clients Tailnet-DNS akzeptieren, können iOS-Nodes und CLI-Discovery
`_openclaw-gw._tcp` in Ihrer Discovery-Domain ohne Multicast browsen.
Sobald Clients Tailnet-DNS akzeptieren, können iOS-Nodes und die CLI-Erkennung
`_openclaw-gw._tcp` in Ihrer Erkennungsdomain ohne Multicast durchsuchen.
### Sicherheit des Gateway-Listeners (empfohlen)
Der Gateway-WS-Port (Standard `18789`) bindet standardmäßig an loopback. Für LAN-/Tailnet-
Zugriff binden Sie explizit und lassen die Authentifizierung aktiviert.
Der Gateway-WS-Port (Standard `18789`) bindet standardmäßig an Loopback. Für LAN-/Tailnet-Zugriff
binden Sie ihn explizit und lassen Sie die Authentifizierung aktiviert.
Für reine Tailnet-Setups:
- Setzen Sie `gateway.bind: "tailnet"` in `~/.openclaw/openclaw.json`.
- Starten Sie das Gateway neu (oder starten Sie die macOS-Menüleisten-App neu).
## Was veröffentlicht
## Was angekündigt wird
Nur das Gateway veröffentlicht `_openclaw-gw._tcp`.
Nur das Gateway kündigt `_openclaw-gw._tcp` an. Die LAN-Multicast-Ankündigung wird
vom gebündelten `bonjour` Plugin bereitgestellt; die Veröffentlichung per Wide-Area-DNS-SD bleibt
dem Gateway vorbehalten.
## Servicetypen
@ -94,33 +97,33 @@ Nur das Gateway veröffentlicht `_openclaw-gw._tcp`.
## TXT-Schlüssel (nicht geheime Hinweise)
Das Gateway veröffentlicht kleine nicht geheime Hinweise, um UI-Abläufe komfortabel zu machen:
Das Gateway kündigt kleine, nicht geheime Hinweise an, um UI-Abläufe komfortabler zu machen:
- `role=gateway`
- `displayName=<friendly name>`
- `displayName=<freundlicher Name>`
- `lanHost=<hostname>.local`
- `gatewayPort=<port>` (Gateway WS + HTTP)
- `gatewayTls=1` (nur wenn TLS aktiviert ist)
- `gatewayTlsSha256=<sha256>` (nur wenn TLS aktiviert ist und ein Fingerabdruck verfügbar ist)
- `canvasPort=<port>` (nur wenn der Canvas-Host aktiviert ist; derzeit identisch mit `gatewayPort`)
- `transport=gateway`
- `tailnetDns=<magicdns>` (optionaler Hinweis, wenn Tailnet verfügbar ist)
- `sshPort=<port>` (nur im mDNS-Vollmodus; Wide-Area-DNS-SD kann ihn weglassen)
- `cliPath=<path>` (nur im mDNS-Vollmodus; Wide-Area-DNS-SD schreibt ihn weiterhin als Hinweis für Remote-Installationen)
- `tailnetDns=<magicdns>` (nur im mDNS-Vollmodus, optionaler Hinweis, wenn Tailnet verfügbar ist)
- `sshPort=<port>` (nur im mDNS-Vollmodus; Wide-Area-DNS-SD kann dies weglassen)
- `cliPath=<path>` (nur im mDNS-Vollmodus; Wide-Area-DNS-SD schreibt dies weiterhin als Hinweis für Remote-Installation)
Sicherheitshinweise:
- Bonjour-/mDNS-TXT-Records sind **nicht authentifiziert**. Clients dürfen TXT nicht als autoritatives Routing behandeln.
- Bonjour-/mDNS-TXT-Einträge sind **nicht authentifiziert**. Clients dürfen TXT nicht als autoritatives Routing behandeln.
- Clients sollten über den aufgelösten Service-Endpunkt routen (SRV + A/AAAA). Behandeln Sie `lanHost`, `tailnetDns`, `gatewayPort` und `gatewayTlsSha256` nur als Hinweise.
- Auch SSH-Auto-Targeting sollte den aufgelösten Service-Host verwenden, nicht nur TXT-Hinweise.
- TLS-Pinning darf niemals zulassen, dass ein veröffentlichtes `gatewayTlsSha256` einen zuvor gespeicherten Pin überschreibt.
- iOS-/Android-Nodes sollten discovery-basierte Direktverbindungen als **nur TLS** behandeln und vor dem Vertrauen in einen erstmaligen Fingerabdruck eine ausdrückliche Benutzerbestätigung verlangen.
- Auch SSH-Auto-Targeting sollte den aufgelösten Service-Host verwenden, nicht Hinweise nur aus TXT.
- TLS-Pinning darf niemals zulassen, dass ein angekündigter `gatewayTlsSha256` einen zuvor gespeicherten Pin überschreibt.
- iOS-/Android-Nodes sollten entdeckungsbasierte Direktverbindungen als **nur TLS** behandeln und vor dem Vertrauen in einen Fingerabdruck beim ersten Mal eine ausdrückliche Benutzerbestätigung verlangen.
## Debugging unter macOS
## Fehlerbehebung unter macOS
Nützliche integrierte Tools:
- Instanzen browsen:
- Instanzen durchsuchen:
```bash
dns-sd -B _openclaw-gw._tcp local.
@ -132,19 +135,19 @@ Nützliche integrierte Tools:
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```
Wenn Browsing funktioniert, das Auflösen aber fehlschlägt, stoßen Sie meist auf eine LAN-Richtlinie oder
ein mDNS-Resolver-Problem.
Wenn das Durchsuchen funktioniert, das Auflösen aber fehlschlägt, stoßen Sie in der Regel auf
eine LAN-Richtlinie oder ein Problem mit dem mDNS-Resolver.
## Debugging in Gateway-Logs
## Fehlerbehebung in Gateway-Logs
Das Gateway schreibt eine rotierende Logdatei (beim Start ausgegeben als
`gateway log file: ...`). Achten Sie auf Zeilen mit `bonjour:`, insbesondere:
`gateway log file: ...`). Achten Sie auf `bonjour:`-Zeilen, insbesondere:
- `bonjour: advertise failed ...`
- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
- `bonjour: watchdog detected non-announced service ...`
## Debugging auf der iOS-Node
## Fehlerbehebung auf iOS-Node
Die iOS-Node verwendet `NWBrowser`, um `_openclaw-gw._tcp` zu erkennen.
@ -153,20 +156,20 @@ So erfassen Sie Logs:
- Einstellungen → Gateway → Erweitert → **Discovery Debug Logs**
- Einstellungen → Gateway → Erweitert → **Discovery Logs** → reproduzieren → **Copy**
Das Log enthält Browser-Zustandsübergänge und Änderungen an der Ergebnismenge.
Das Log enthält Browser-Statusübergänge und Änderungen an der Ergebnismenge.
## Häufige Fehlermodi
- **Bonjour überquert keine Netzwerke**: Verwenden Sie Tailnet oder SSH.
- **Multicast blockiert**: Einige WLAN-Netzwerke deaktivieren mDNS.
- **Ruhezustand / Schnittstellenwechsel**: macOS kann mDNS-Ergebnisse vorübergehend verwerfen; erneut versuchen.
- **Browsing funktioniert, aber Auflösen schlägt fehl**: Halten Sie Rechnernamen einfach (vermeiden Sie Emojis oder
Satzzeichen) und starten Sie dann das Gateway neu. Der Name der Serviceinstanz leitet sich vom
Hostnamen ab, daher können zu komplexe Namen einige Resolver verwirren.
- **Bonjour überschreitet keine Netzwerke**: Verwenden Sie Tailnet oder SSH.
- **Multicast blockiert**: Einige Wi‑Fi-Netzwerke deaktivieren mDNS.
- **Ruhezustand / Schnittstellenwechsel**: macOS kann mDNS-Ergebnisse vorübergehend verwerfen; versuchen Sie es erneut.
- **Durchsuchen funktioniert, aber Auflösen schlägt fehl**: Halten Sie Rechnernamen einfach (vermeiden Sie Emojis oder
Satzzeichen) und starten Sie dann das Gateway neu. Der Name der Serviceinstanz wird vom
Hostnamen abgeleitet, daher können übermäßig komplexe Namen einige Resolver verwirren.
## Escapte Instanznamen (`\032`)
Bonjour/DNS-SD maskiert Bytes in Serviceinstanznamen oft als dezimale `\DDD`-
Bonjour/DNS‑SD maskiert Bytes in Serviceinstanznamen oft als dezimale `\DDD`-
Sequenzen (z. B. werden Leerzeichen zu `\032`).
- Das ist auf Protokollebene normal.
@ -174,13 +177,15 @@ Sequenzen (z. B. werden Leerzeichen zu `\032`).
## Deaktivierung / Konfiguration
- `OPENCLAW_DISABLE_BONJOUR=1` deaktiviert die Veröffentlichung (Legacy: `OPENCLAW_DISABLE_BONJOUR`).
- `openclaw plugins disable bonjour` deaktiviert die LAN-Multicast-Ankündigung, indem das gebündelte Plugin deaktiviert wird.
- `openclaw plugins enable bonjour` stellt das standardmäßige LAN-Erkennungs-Plugin wieder her.
- `OPENCLAW_DISABLE_BONJOUR=1` deaktiviert die LAN-Multicast-Ankündigung, ohne die Plugin-Konfiguration zu ändern; akzeptierte Truthy-Werte sind `1`, `true`, `yes` und `on` (Legacy: `OPENCLAW_DISABLE_BONJOUR`).
- `gateway.bind` in `~/.openclaw/openclaw.json` steuert den Bind-Modus des Gateway.
- `OPENCLAW_SSH_PORT` überschreibt den SSH-Port, wenn `sshPort` veröffentlicht wird (Legacy: `OPENCLAW_SSH_PORT`).
- `OPENCLAW_TAILNET_DNS` veröffentlicht einen MagicDNS-Hinweis in TXT (Legacy: `OPENCLAW_TAILNET_DNS`).
- `OPENCLAW_CLI_PATH` überschreibt den veröffentlichten CLI-Pfad (Legacy: `OPENCLAW_CLI_PATH`).
- `OPENCLAW_SSH_PORT` überschreibt den SSH-Port, wenn `sshPort` angekündigt wird (Legacy: `OPENCLAW_SSH_PORT`).
- `OPENCLAW_TAILNET_DNS` veröffentlicht einen MagicDNS-Hinweis in TXT, wenn der mDNS-Vollmodus aktiviert ist (Legacy: `OPENCLAW_TAILNET_DNS`).
- `OPENCLAW_CLI_PATH` überschreibt den angekündigten CLI-Pfad (Legacy: `OPENCLAW_CLI_PATH`).
## Verwandte Dokumente
## Zugehörige Dokumentation
- Discovery-Richtlinie und Transportauswahl: [Discovery](/de/gateway/discovery)
- Erkennungsrichtlinie und Transportauswahl: [Discovery](/de/gateway/discovery)
- Node-Kopplung + Genehmigungen: [Gateway pairing](/de/gateway/pairing)

530
docs/de/gateway/configuration-reference.md
View File

@ -1,62 +1,62 @@
---
read_when:
- Sie benötigen die exakte Semantik oder Standardwerte der Konfiguration auf Feldebene
- Sie validieren Konfigurationsblöcke für Kanäle, Modelle, Gateway oder Tools
- Sie benötigen exakte feldbezogene Konfigurationssemantik oder Standardwerte
- Sie validieren Konfigurationsblöcke für Channel, Modelle, Gateway oder Tools
summary: Gateway-Konfigurationsreferenz für zentrale OpenClaw-Schlüssel, Standardwerte und Links zu dedizierten Subsystem-Referenzen
title: Konfigurationsreferenz
x-i18n:
generated_at: "2026-04-24T06:37:04Z"
generated_at: "2026-04-24T08:57:03Z"
model: gpt-5.4
provider: openai
source_hash: 6dc3b920ada38951086908713e9347141d8b11faa007df23a90a2532ac6f3bb2
source_hash: dc0d9feea2f2707f267d50ec83aa664ef503db8f9132762345cc80305f8bef73
source_path: gateway/configuration-reference.md
workflow: 15
---
Zentrale Konfigurationsreferenz für `~/.openclaw/openclaw.json`. Für einen aufgabenorientierten Überblick siehe [Konfiguration](/de/gateway/configuration).
Kern-Konfigurationsreferenz für `~/.openclaw/openclaw.json`. Für einen aufgabenorientierten Überblick siehe [Configuration](/de/gateway/configuration).
Diese Seite behandelt die wichtigsten Konfigurationsoberflächen von OpenClaw und verweist weiter, wenn ein Subsystem eine eigene ausführlichere Referenz hat. Sie versucht **nicht**, jeden befehlsbezogenen Katalog von Kanälen/Plugins oder jeden tiefen Regler für Memory/QMD auf einer Seite einzubetten.
Diese Seite behandelt die wichtigsten OpenClaw-Konfigurationsoberflächen und verlinkt weiter, wenn ein Subsystem eine eigene, ausführlichere Referenz hat. Sie versucht **nicht**, jeden Channel-/Plugin-eigenen Befehlskatalog oder jede tiefgehende Speicher-/QMD-Option auf einer Seite inline abzubilden.
Code-Quelle der Wahrheit:
Code-Referenz:
- `openclaw config schema` gibt das Live-JSON-Schema aus, das für Validierung und Control UI verwendet wird, mit eingebundenen Metadaten aus gebündelten Plugins/Kanälen, wenn verfügbar
- `config.schema.lookup` gibt einen schemagebundenen Knoten für einen einzelnen Pfad für Drill-down-Tooling zurück
- `openclaw config schema` gibt das Live-JSON-Schema aus, das für Validierung und die Control UI verwendet wird, wobei gebündelte Plugin-/Channel-Metadaten zusammengeführt werden, wenn verfügbar
- `config.schema.lookup` gibt einen einzelnen pfadbezogenen Schemaknoten für Drill-down-Tools zurück
- `pnpm config:docs:check` / `pnpm config:docs:gen` validieren den Baseline-Hash der Konfigurationsdokumentation gegen die aktuelle Schemaoberfläche
Dedizierte ausführliche Referenzen:
- [Memory-Konfigurationsreferenz](/de/reference/memory-config) für `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` und die Dreaming-Konfiguration unter `plugins.entries.memory-core.config.dreaming`
- [Slash-Befehle](/de/tools/slash-commands) für den aktuellen integrierten + gebündelten Befehlskatalog
- zuständige Kanal-/Plugin-Seiten für kanalspezifische Befehlsoberflächen
- [Memory-Konfigurationsreferenz](/de/reference/memory-config) für `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` und Dreaming-Konfiguration unter `plugins.entries.memory-core.config.dreaming`
- [Slash Commands](/de/tools/slash-commands) für den aktuellen integrierten + gebündelten Befehlskatalog
- zugehörige Channel-/Plugin-Seiten für Channel-spezifische Befehlsoberflächen
Das Konfigurationsformat ist **JSON5** (Kommentare + nachgestellte Kommata erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden.
Das Konfigurationsformat ist **JSON5** (Kommentare + nachgestellte Kommas erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden.
---
## Kanäle
## Channels
Kanalspezifische Konfigurationsschlüssel wurden auf eine eigene Seite verschoben — siehe
[Konfiguration — Kanäle](/de/gateway/config-channels) für `channels.*`,
Die Konfigurationsschlüssel pro Channel wurden auf eine dedizierte Seite verschoben — siehe
[Configuration — channels](/de/gateway/config-channels) für `channels.*`,
einschließlich Slack, Discord, Telegram, WhatsApp, Matrix, iMessage und anderer
gebündelter Kanäle (Authentifizierung, Zugriffskontrolle, mehrere Konten, Erwähnungsbindung).
gebündelter Channels (Authentifizierung, Zugriffskontrolle, Multi-Account, Mention-Gating).
## Agent-Standards, Multi-Agent, Sitzungen und Nachrichten
## Agent-Standardeinstellungen, Multi-Agent, Sitzungen und Nachrichten
Auf eine eigene Seite verschoben — siehe
[Konfiguration — Agenten](/de/gateway/config-agents) für:
Auf eine dedizierte Seite verschoben — siehe
[Configuration — agents](/de/gateway/config-agents) für:
- `agents.defaults.*` (Workspace, Modell, Thinking, Heartbeat, Memory, Medien, Skills, Sandbox)
- `multiAgent.*` (Multi-Agent-Routing und Bindings)
- `agents.defaults.*` (Arbeitsbereich, Modell, Thinking, Heartbeat, Speicher, Medien, Skills, Sandbox)
- `multiAgent.*` (Multi-Agent-Routing und Bindungen)
- `session.*` (Sitzungslebenszyklus, Compaction, Bereinigung)
- `messages.*` (Nachrichtenzustellung, TTS, Markdown-Rendering)
- `talk.*` (Talk-Modus)
- `talk.silenceTimeoutMs`: wenn nicht gesetzt, verwendet Talk das plattformspezifische Standard-Pausenfenster vor dem Senden des Transkripts (`700 ms auf macOS und Android, 900 ms auf iOS`)
- `talk.silenceTimeoutMs`: wenn nicht gesetzt, behält Talk das plattformspezifische Standard-Pausenfenster vor dem Senden des Transkripts bei (`700 ms unter macOS und Android, 900 ms unter iOS`)
## Tools und benutzerdefinierte Provider
Tool-Richtlinien, experimentelle Umschalter, providergestützte Tool-Konfiguration und benutzerdefinierte
Provider-/Basis-URL-Einrichtung wurden auf eine eigene Seite verschoben — siehe
[Konfiguration — Tools und benutzerdefinierte Provider](/de/gateway/config-tools).
Tool-Richtlinien, experimentelle Umschalter, Provider-gestützte Tool-Konfiguration und benutzerdefinierte
Provider- / Base-URL-Einrichtung wurden auf eine dedizierte Seite verschoben — siehe
[Configuration — tools and custom providers](/de/gateway/config-tools).
## Skills
@ -83,14 +83,14 @@ Provider-/Basis-URL-Einrichtung wurden auf eine eigene Seite verschoben — sieh
}
```
- `allowBundled`: optionale Allowlist nur für gebündelte Skills (verwaltete/Workspace-Skills bleiben unberührt).
- `load.extraDirs`: zusätzliche gemeinsam genutzte Skill-Roots (niedrigste Priorität).
- `allowBundled`: optionale Allowlist nur für gebündelte Skills (verwaltete/Arbeitsbereichs-Skills bleiben unberührt).
- `load.extraDirs`: zusätzliche gemeinsame Skill-Wurzelverzeichnisse (niedrigste Priorität).
- `install.preferBrew`: wenn `true`, werden Homebrew-Installer bevorzugt, wenn `brew`
verfügbar ist, bevor auf andere Installer-Arten zurückgegriffen wird.
- `install.nodeManager`: bevorzugter Node-Installer für `metadata.openclaw.install`-
Spezifikationen (`npm` | `pnpm` | `yarn` | `bun`).
- `entries.<skillKey>.enabled: false` deaktiviert einen Skill, selbst wenn er gebündelt/installiert ist.
- `entries.<skillKey>.apiKey`: Komfortfeld für Skills, die eine primäre Env-Variable deklarieren (Klartext-String oder SecretRef-Objekt).
verfügbar ist, bevor auf andere Installer-Typen zurückgegriffen wird.
- `install.nodeManager`: Node-Installer-Präferenz für `metadata.openclaw.install`
specs (`npm` | `pnpm` | `yarn` | `bun`).
- `entries.<skillKey>.enabled: false` deaktiviert einen Skill, auch wenn er gebündelt/installiert ist.
- `entries.<skillKey>.apiKey`: Komfortfeld für Skills, die eine primäre Umgebungsvariable deklarieren (Klartext-String oder SecretRef-Objekt).
---
@ -122,37 +122,37 @@ Provider-/Basis-URL-Einrichtung wurden auf eine eigene Seite verschoben — sieh
- Discovery akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles im Standardlayout.
- **Konfigurationsänderungen erfordern einen Gateway-Neustart.**
- `allow`: optionale Allowlist (nur aufgeführte Plugins werden geladen). `deny` hat Vorrang.
- `plugins.entries.<id>.apiKey`: pluginbezogenes Komfortfeld für API-Keys (wenn vom Plugin unterstützt).
- `plugins.entries.<id>.env`: pluginbezogene Env-Variablen-Map.
- `plugins.entries.<id>.hooks.allowPromptInjection`: wenn `false`, blockiert der Core `before_prompt_build` und ignoriert promptmutierende Felder aus dem veralteten `before_agent_start`, während veraltete `modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte von Bundles bereitgestellte Hook-Verzeichnisse.
- `plugins.entries.<id>.subagent.allowModelOverride`: diesem Plugin ausdrücklich vertrauen, pro Lauf `provider`- und `model`-Überschreibungen für Hintergrund-Sub-Agent-Läufe anzufordern.
- `plugins.entries.<id>.subagent.allowedModels`: optionale Allowlist kanonischer `provider/model`-Ziele für vertrauenswürdige Sub-Agent-Überschreibungen. Verwenden Sie `"*"` nur, wenn Sie absichtlich jedes Modell zulassen möchten.
- `plugins.entries.<id>.apiKey`: Komfortfeld für API-Schlüssel auf Plugin-Ebene (wenn vom Plugin unterstützt).
- `plugins.entries.<id>.env`: Plugin-bezogene Umgebungsvariablenzuordnung.
- `plugins.entries.<id>.hooks.allowPromptInjection`: wenn `false`, blockiert der Kern `before_prompt_build` und ignoriert Prompt-modifizierende Felder aus dem älteren `before_agent_start`, wobei das ältere `modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte Hook-Verzeichnisse aus Bundles.
- `plugins.entries.<id>.subagent.allowModelOverride`: diesem Plugin explizit vertrauen, pro Ausführung `provider`- und `model`-Overrides für Hintergrund-Subagent-Ausführungen anzufordern.
- `plugins.entries.<id>.subagent.allowedModels`: optionale Allowlist kanonischer `provider/model`-Ziele für vertrauenswürdige Subagent-Overrides. Verwenden Sie `"*"`, nur wenn Sie absichtlich jedes Modell zulassen möchten.
- `plugins.entries.<id>.config`: vom Plugin definiertes Konfigurationsobjekt (validiert durch das native OpenClaw-Plugin-Schema, wenn verfügbar).
- `plugins.entries.firecrawl.config.webFetch`: Firecrawl-Web-Fetch-Provider-Einstellungen.
- `apiKey`: Firecrawl-API-Key (akzeptiert SecretRef). Fällt zurück auf `plugins.entries.firecrawl.config.webSearch.apiKey`, veraltetes `tools.web.fetch.firecrawl.apiKey` oder die Env-Variable `FIRECRAWL_API_KEY`.
- `plugins.entries.firecrawl.config.webFetch`: Firecrawl-Einstellungen für den Web-Fetch-Provider.
- `apiKey`: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt zurück auf `plugins.entries.firecrawl.config.webSearch.apiKey`, das ältere `tools.web.fetch.firecrawl.apiKey` oder die Umgebungsvariable `FIRECRAWL_API_KEY`.
- `baseUrl`: Firecrawl-API-Basis-URL (Standard: `https://api.firecrawl.dev`).
- `onlyMainContent`: nur den Hauptinhalt von Seiten extrahieren (Standard: `true`).
- `onlyMainContent`: nur den Hauptinhalt aus Seiten extrahieren (Standard: `true`).
- `maxAgeMs`: maximales Cache-Alter in Millisekunden (Standard: `172800000` / 2 Tage).
- `timeoutSeconds`: Timeout für Scrape-Requests in Sekunden (Standard: `60`).
- `plugins.entries.xai.config.xSearch`: Einstellungen für xAI X Search (Grok-Websuche).
- `timeoutSeconds`: Timeout der Scrape-Anfrage in Sekunden (Standard: `60`).
- `plugins.entries.xai.config.xSearch`: xAI-X-Search-Einstellungen (Grok-Websuche).
- `enabled`: den X-Search-Provider aktivieren.
- `model`: Grok-Modell, das für die Suche verwendet werden soll (z. B. `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: Memory-Dreaming-Einstellungen. Siehe [Dreaming](/de/concepts/dreaming) für Phasen und Schwellenwerte.
- `model`: für die Suche zu verwendendes Grok-Modell (z. B. `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: Einstellungen für Memory Dreaming. Siehe [Dreaming](/de/concepts/dreaming) für Phasen und Schwellenwerte.
- `enabled`: globaler Dreaming-Schalter (Standard `false`).
- `frequency`: Cron-Rhythmus für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`).
- `frequency`: Cron-Taktung für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`).
- Phasenrichtlinien und Schwellenwerte sind Implementierungsdetails (keine benutzerseitigen Konfigurationsschlüssel).
- Die vollständige Memory-Konfiguration befindet sich in der [Memory-Konfigurationsreferenz](/de/reference/memory-config):
- Die vollständige Speicherkonfiguration befindet sich in der [Memory-Konfigurationsreferenz](/de/reference/memory-config):
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standardeinstellungen aus `settings.json` beitragen; OpenClaw wendet diese als bereinigte Agenteneinstellungen an, nicht als rohe OpenClaw-Konfigurations-Patches.
- `plugins.slots.memory`: die aktive Memory-Plugin-ID auswählen oder `"none"`, um Memory-Plugins zu deaktivieren.
- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standardeinstellungen aus `settings.json` beisteuern; OpenClaw wendet diese als bereinigte Agent-Einstellungen an, nicht als rohe OpenClaw-Konfigurations-Patches.
- `plugins.slots.memory`: die aktive Speicher-Plugin-ID auswählen oder `"none"` zum Deaktivieren von Speicher-Plugins.
- `plugins.slots.contextEngine`: die aktive Context-Engine-Plugin-ID auswählen; standardmäßig `"legacy"`, sofern Sie keine andere Engine installieren und auswählen.
- `plugins.installs`: von der CLI verwaltete Installationsmetadaten, die von `openclaw plugins update` verwendet werden.
- `plugins.installs`: CLI-verwaltete Installationsmetadaten, die von `openclaw plugins update` verwendet werden.
- Enthält `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
- Behandeln Sie `plugins.installs.*` als verwalteten Zustand; bevorzugen Sie CLI-Befehle gegenüber manuellen Bearbeitungen.
- Behandeln Sie `plugins.installs.*` als verwalteten Zustand; bevorzugen Sie CLI-Befehle gegenüber manuellen Änderungen.
Siehe [Plugins](/de/tools/plugin).
@ -196,24 +196,25 @@ Siehe [Plugins](/de/tools/plugin).
- `evaluateEnabled: false` deaktiviert `act:evaluate` und `wait --fn`.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist deaktiviert, wenn es nicht gesetzt ist, sodass die Browser-Navigation standardmäßig strikt bleibt.
- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` nur dann, wenn Sie private Netzwerk-Browser-Navigation bewusst vertrauen.
- Im strikten Modus unterliegen Endpoints von Remote-CDP-Profilen (`profiles.*.cdpUrl`) derselben Sperrung privater Netzwerke während Erreichbarkeits-/Discovery-Prüfungen.
- `ssrfPolicy.allowPrivateNetwork` wird weiterhin als veralteter Alias unterstützt.
- Verwenden Sie im strikten Modus `ssrfPolicy.hostnameAllowlist` und `ssrfPolicy.allowedHostnames` für explizite Ausnahmen.
- Remote-Profile sind nur zum Anhängen geeignet (start/stop/reset deaktiviert).
- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` nur dann, wenn Sie der Browser-Navigation in privaten Netzwerken absichtlich vertrauen.
- Im strikten Modus unterliegen entfernte CDP-Profilendpunkte (`profiles.*.cdpUrl`) denselben Sperren privater Netzwerke bei Erreichbarkeits-/Discovery-Prüfungen.
- `ssrfPolicy.allowPrivateNetwork` wird weiterhin als älterer Alias unterstützt.
- Im strikten Modus verwenden Sie `ssrfPolicy.hostnameAllowlist` und `ssrfPolicy.allowedHostnames` für explizite Ausnahmen.
- Entfernte Profile sind nur zum Anhängen vorgesehen (Start/Stopp/Zurücksetzen deaktiviert).
- `profiles.*.cdpUrl` akzeptiert `http://`, `https://`, `ws://` und `wss://`.
Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` entdecken soll; verwenden Sie WS(S),
wenn Ihr Provider Ihnen eine direkte DevTools-WebSocket-URL gibt.
- `existing-session`-Profile verwenden Chrome MCP statt CDP und können auf
dem ausgewählten Host oder über einen verbundenen Browser-Node anhängen.
Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` erkennen soll; verwenden Sie WS(S),
wenn Ihr Provider Ihnen eine direkte DevTools-WebSocket-URL bereitstellt.
- `existing-session`-Profile verwenden Chrome MCP statt CDP und können sich
an den ausgewählten Host oder über einen verbundenen Browser-Node anhängen.
- `existing-session`-Profile können `userDataDir` setzen, um ein bestimmtes
Chromium-basiertes Browser-Profil wie Brave oder Edge anzusprechen.
- `existing-session`-Profile behalten die aktuellen Einschränkungen der Chrome-MCP-Route:
snapshot-/referenzgesteuerte Aktionen statt CSS-Selektor-Targeting, Hooks zum Hochladen einzelner Dateien, keine Dialog-Timeout-Überschreibungen, kein `wait --load networkidle` und kein `responsebody`, kein PDF-Export, keine Download-Interception und keine Batch-Aktionen.
Chromium-basiertes Browserprofil wie Brave oder Edge anzusprechen.
- `existing-session`-Profile behalten die aktuellen Begrenzungen der Chrome-MCP-Route bei:
Snapshot-/Ref-basierte Aktionen statt CSS-Selektor-Targeting, Hooks für Einzeldatei-Uploads, keine Dialog-Timeout-Overrides, kein `wait --load networkidle` und kein
`responsebody`, PDF-Export, Download-Abfangung oder Batch-Aktionen.
- Lokal verwaltete `openclaw`-Profile weisen `cdpPort` und `cdpUrl` automatisch zu; setzen Sie
`cdpUrl` nur explizit für Remote-CDP.
- Reihenfolge der Auto-Erkennung: Standardbrowser, wenn Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary.
- Control-Dienst: nur loopback (Port wird von `gateway.port` abgeleitet, Standard `18791`).
`cdpUrl` nur explizit für entferntes CDP.
- Reihenfolge der automatischen Erkennung: Standardbrowser, falls Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary.
- Control-Service: nur Loopback (Port abgeleitet von `gateway.port`, Standard `18791`).
- `extraArgs` hängt zusätzliche Start-Flags an den lokalen Chromium-Start an (zum Beispiel
`--disable-gpu`, Fenstergröße oder Debug-Flags).
@ -233,8 +234,8 @@ Siehe [Plugins](/de/tools/plugin).
}
```
- `seamColor`: Akzentfarbe für den nativen App-UI-Rahmen (Talk-Mode-Blasentönung usw.).
- `assistant`: Identitätsüberschreibung für die Control UI. Fällt auf die aktive Agentenidentität zurück.
- `seamColor`: Akzentfarbe für das UI-Chrome der nativen App (Talk-Mode-Blasentönung usw.).
- `assistant`: Identitäts-Override für die Control UI. Fällt auf die aktive Agent-Identität zurück.
---
@ -301,66 +302,64 @@ Siehe [Plugins](/de/tools/plugin).
}
```
<Accordion title="Details zu Gateway-Feldern">
<Accordion title="Gateway-Felddetails">
- `mode`: `local` (Gateway ausführen) oder `remote` (mit Remote-Gateway verbinden). Das Gateway verweigert den Start, sofern nicht `local`.
- `port`: einzelner multiplexter Port für WS + HTTP. Vorrang: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `mode`: `local` (Gateway ausführen) oder `remote` (mit entferntem Gateway verbinden). Das Gateway verweigert den Start, außer bei `local`.
- `port`: einzelner multiplexter Port für WS + HTTP. Priorität: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `bind`: `auto`, `loopback` (Standard), `lan` (`0.0.0.0`), `tailnet` (nur Tailscale-IP) oder `custom`.
- **Veraltete Bind-Aliasse**: Verwenden Sie Bind-Modus-Werte in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), nicht Host-Aliasse (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Docker-Hinweis**: Das standardmäßige Bind `loopback` lauscht innerhalb des Containers auf `127.0.0.1`. Bei Docker-Bridge-Netzwerk (`-p 18789:18789`) kommt Datenverkehr auf `eth0` an, sodass das Gateway nicht erreichbar ist. Verwenden Sie `--network host` oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), um auf allen Interfaces zu lauschen.
- **Auth**: Standardmäßig erforderlich. Nicht-Loopback-Binds erfordern Gateway-Authentifizierung. In der Praxis bedeutet das ein gemeinsames Token/Passwort oder einen identitätsbewussten Reverse-Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- sowie Dienstinstallations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und `mode` nicht gesetzt ist.
- `gateway.auth.mode: "none"`: expliziter Modus ohne Authentifizierung. Verwenden Sie dies nur für vertrauenswürdige lokale local loopback-Setups; diese Option wird in Onboarding-Prompts absichtlich nicht angeboten.
- `gateway.auth.mode: "trusted-proxy"`: Authentifizierung an einen identitätsbewussten Reverse-Proxy delegieren und Identitäts-Headern von `gateway.trustedProxies` vertrauen (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet eine **Nicht-Loopback**-Proxyquelle; gleichhostige Loopback-Reverse-Proxys erfüllen trusted-proxy-Auth nicht.
- `gateway.auth.allowTailscale`: wenn `true`, können Identitäts-Header von Tailscale Serve die Authentifizierung für Control UI/WebSocket erfüllen (verifiziert über `tailscale whois`). HTTP-API-Endpoints verwenden diese Tailscale-Header-Auth **nicht**; sie folgen stattdessen dem normalen HTTP-Auth-Modus des Gateway. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Standardmäßig `true`, wenn `tailscale.mode = "serve"`.
- `gateway.auth.rateLimit`: optionaler Limiter für fehlgeschlagene Authentifizierung. Gilt pro Client-IP und pro Auth-Bereich (gemeinsames Secret und Device-Token werden unabhängig verfolgt). Geblockte Versuche geben `429` + `Retry-After` zurück.
- Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für denselben `{scope, clientIp}` vor dem Schreiben des Fehlers serialisiert. Gleichzeitige falsche Versuche desselben Clients können daher den Limiter beim zweiten Request auslösen, statt dass beide als normale Nichtübereinstimmungen durchlaufen.
- `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie es auf `false`, wenn Sie localhost-Datenverkehr absichtlich ebenfalls ratenlimitieren möchten (für Test-Setups oder strikte Proxy-Bereitstellungen).
- Browser-originierte WS-Authentifizierungsversuche werden immer mit deaktivierter Loopback-Ausnahme gedrosselt (Defense-in-Depth gegen browserbasiertes Brute-Force auf localhost).
- Auf loopback sind diese Sperren browser-originierter Versuche pro normalisiertem `Origin`-
Wert isoliert, sodass wiederholte Fehlschläge von einer localhost-Origin nicht automatisch
eine andere Origin sperren.
- `tailscale.mode`: `serve` (nur tailnet, loopback-Bind) oder `funnel` (öffentlich, erfordert Auth).
- `controlUi.allowedOrigins`: explizite Browser-Origin-Allowlist für Gateway-WebSocket-Verbindungen. Erforderlich, wenn Browser-Clients von Nicht-Loopback-Origins erwartet werden.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Host-Header-Origin-Fallback für Bereitstellungen aktiviert, die sich absichtlich auf eine Origin-Richtlinie über den Host-Header verlassen.
- **Ältere Bind-Aliasse**: Verwenden Sie Bind-Modus-Werte in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), keine Host-Aliasse (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Docker-Hinweis**: Das Standard-Binding `loopback` lauscht innerhalb des Containers auf `127.0.0.1`. Bei Docker-Bridge-Networking (`-p 18789:18789`) trifft der Datenverkehr auf `eth0` ein, sodass das Gateway nicht erreichbar ist. Verwenden Sie `--network host`, oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), um auf allen Schnittstellen zu lauschen.
- **Authentifizierung**: Standardmäßig erforderlich. Nicht-Loopback-Bindings erfordern Gateway-Authentifizierung. In der Praxis bedeutet das ein gemeinsames Token/Passwort oder einen identitätsbewussten Reverse-Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- sowie Service-Installations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und kein Modus gesetzt ist.
- `gateway.auth.mode: "none"`: expliziter Modus ohne Authentifizierung. Nur für vertrauenswürdige lokale `local loopback`-Setups verwenden; dies wird in Onboarding-Prompts absichtlich nicht angeboten.
- `gateway.auth.mode: "trusted-proxy"`: Authentifizierung an einen identitätsbewussten Reverse-Proxy delegieren und Identitäts-Header von `gateway.trustedProxies` vertrauen (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet eine **nicht-Loopback**-Proxy-Quelle; Reverse-Proxys auf demselben Host mit Loopback erfüllen `trusted-proxy`-Authentifizierung nicht.
- `gateway.auth.allowTailscale`: wenn `true`, können Tailscale-Serve-Identitäts-Header die Authentifizierung für Control UI/WebSocket erfüllen (verifiziert über `tailscale whois`). HTTP-API-Endpunkte verwenden **nicht** diese Tailscale-Header-Authentifizierung; sie folgen stattdessen dem normalen HTTP-Authentifizierungsmodus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Standard ist `true`, wenn `tailscale.mode = "serve"` gesetzt ist.
- `gateway.auth.rateLimit`: optionaler Begrenzer für fehlgeschlagene Authentifizierungen. Gilt pro Client-IP und pro Authentifizierungsbereich (gemeinsames Geheimnis und Geräte-Token werden getrennt verfolgt). Blockierte Versuche geben `429` + `Retry-After` zurück.
- Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, clientIp}` vor dem Schreiben des Fehlers serialisiert. Gleichzeitige fehlerhafte Versuche desselben Clients können daher beim zweiten Request den Begrenzer auslösen, statt dass beide als einfache Nichtübereinstimmungen durchlaufen.
- `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie es auf `false`, wenn Sie absichtlich möchten, dass auch localhost-Datenverkehr begrenzt wird (für Test-Setups oder strikte Proxy-Bereitstellungen).
- Browserseitige WS-Authentifizierungsversuche werden immer mit deaktivierter Loopback-Ausnahme gedrosselt (Defense-in-Depth gegen browserbasierte Brute-Force-Angriffe auf localhost).
- Bei Loopback werden diese Sperren für browserseitige Ursprünge pro normalisiertem `Origin`-Wert isoliert, sodass wiederholte Fehlversuche von einem localhost-Ursprung nicht automatisch einen anderen Ursprung sperren.
- `tailscale.mode`: `serve` (nur Tailnet, Loopback-Bind) oder `funnel` (öffentlich, erfordert Authentifizierung).
- `controlUi.allowedOrigins`: explizite Browser-Origin-Allowlist für Gateway-WebSocket-Verbindungen. Erforderlich, wenn Browser-Clients von Nicht-Loopback-Originen erwartet werden.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Host-Header-Origin-Fallback für Bereitstellungen aktiviert, die absichtlich auf einer Host-Header-Origin-Richtlinie basieren.
- `remote.transport`: `ssh` (Standard) oder `direct` (ws/wss). Für `direct` muss `remote.url` `ws://` oder `wss://` sein.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: clientseitige Break-Glass-Überschreibung, die unverschlüsseltes `ws://` zu vertrauenswürdigen privaten Netzwerk-IPs erlaubt; Standard bleibt für unverschlüsseltes Protokoll weiterhin nur loopback.
- `gateway.remote.token` / `.password` sind Anmeldedatenfelder des Remote-Clients. Sie konfigurieren für sich genommen keine Gateway-Authentifizierung.
- `gateway.push.apns.relay.baseUrl`: Basis-HTTPS-URL für das externe APNs-Relay, das von offiziellen/TestFlight-iOS-Builds verwendet wird, nachdem diese relaygestützte Registrierungen beim Gateway veröffentlicht haben. Diese URL muss mit der Relay-URL übereinstimmen, die in den iOS-Build einkompiliert wurde.
- `gateway.push.apns.relay.timeoutMs`: Gateway-zu-Relay-Sende-Timeout in Millisekunden. Standardwert ist `10000`.
- Relaygestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die gekoppelte iOS-App ruft `gateway.identity.get` ab, schließt diese Identität in die Relay-Registrierung ein und leitet eine registrierungsbezogene Sendeberechtigung an das Gateway weiter. Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden.
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: temporäre Env-Überschreibungen für die obige Relay-Konfiguration.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für die Entwicklung gedachte Escape-Hatch für loopback-HTTP-Relay-URLs. Produktions-Relay-URLs sollten auf HTTPS bleiben.
- `gateway.channelHealthCheckMinutes`: Intervall des Kanal-Health-Monitors in Minuten. Setzen Sie `0`, um Neustarts durch den Health-Monitor global zu deaktivieren. Standard: `5`.
- `gateway.channelStaleEventThresholdMinutes`: Schwelle für stale sockets in Minuten. Halten Sie diesen Wert größer oder gleich `gateway.channelHealthCheckMinutes`. Standard: `30`.
- `gateway.channelMaxRestartsPerHour`: maximale Anzahl von Neustarts durch den Health-Monitor pro Kanal/Konto innerhalb einer gleitenden Stunde. Standard: `10`.
- `channels.<provider>.healthMonitor.enabled`: kanalbezogener Opt-out für Neustarts durch den Health-Monitor, während der globale Monitor aktiviert bleibt.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: kontobezogene Überschreibung für Kanäle mit mehreren Konten. Wenn gesetzt, hat sie Vorrang vor der Überschreibung auf Kanalebene.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: clientseitige Break-Glass-Override über die Prozessumgebung, die unverschlüsseltes `ws://` zu vertrauenswürdigen privaten Netzwerk-IP-Adressen erlaubt; standardmäßig bleibt unverschlüsselter Verkehr auf Loopback beschränkt. Es gibt kein Äquivalent in `openclaw.json`, und Browser-Konfigurationen für private Netzwerke wie `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` wirken sich nicht auf Gateway-WebSocket-Clients aus.
- `gateway.remote.token` / `.password` sind Anmeldefelder des Remote-Clients. Sie konfigurieren die Gateway-Authentifizierung nicht selbst.
- `gateway.push.apns.relay.baseUrl`: Basis-HTTPS-URL für das externe APNs-Relay, das von offiziellen/TestFlight-iOS-Builds verwendet wird, nachdem sie relay-gestützte Registrierungen an das Gateway veröffentlicht haben. Diese URL muss mit der in den iOS-Build kompilierten Relay-URL übereinstimmen.
- `gateway.push.apns.relay.timeoutMs`: Timeout in Millisekunden für das Senden vom Gateway an das Relay. Standard ist `10000`.
- Relay-gestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die zugehörige iOS-App ruft `gateway.identity.get` ab, schließt diese Identität in die Relay-Registrierung ein und leitet eine registrierungsbezogene Sende-Berechtigung an das Gateway weiter. Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden.
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: temporäre Umgebungsvariablen-Overrides für die obige Relay-Konfiguration.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für die Entwicklung gedachter Escape Hatch für Loopback-HTTP-Relay-URLs. Relay-URLs in Produktion sollten bei HTTPS bleiben.
- `gateway.channelHealthCheckMinutes`: Intervall des Channel-Health-Monitors in Minuten. Setzen Sie `0`, um Health-Monitor-Neustarts global zu deaktivieren. Standard: `5`.
- `gateway.channelStaleEventThresholdMinutes`: Schwellenwert für veraltete Sockets in Minuten. Halten Sie diesen Wert größer oder gleich `gateway.channelHealthCheckMinutes`. Standard: `30`.
- `gateway.channelMaxRestartsPerHour`: maximale Anzahl von Health-Monitor-Neustarts pro Channel/Konto innerhalb einer gleitenden Stunde. Standard: `10`.
- `channels.<provider>.healthMonitor.enabled`: kanalbezogenes Opt-out für Health-Monitor-Neustarts, während der globale Monitor aktiviert bleibt.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: kontobezogenes Override für Multi-Account-Channels. Wenn gesetzt, hat es Vorrang vor dem Override auf Channel-Ebene.
- Lokale Gateway-Aufrufpfade können `gateway.remote.*` nur dann als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist.
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert sind und nicht aufgelöst werden können, schlägt die Auflösung fail-closed fehl (kein Remote-Fallback, das dies verdeckt).
- `trustedProxies`: IPs von Reverse-Proxys, die TLS terminieren oder weitergeleitete Client-Header injizieren. Listen Sie nur Proxys auf, die Sie kontrollieren. Loopback-Einträge sind weiterhin für Setups mit Proxy-Erkennung/gleichem Host gültig (zum Beispiel Tailscale Serve oder ein lokaler Reverse-Proxy), machen Loopback-Requests jedoch **nicht** für `gateway.auth.mode: "trusted-proxy"` zulässig.
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht auflösbar ist, schlägt die Auflösung fail-closed fehl (kein verdeckender Remote-Fallback).
- `trustedProxies`: Reverse-Proxy-IPs, die TLS terminieren oder weitergeleitete Client-Header einfügen. Führen Sie nur Proxys auf, die Sie kontrollieren. Loopback-Einträge sind weiterhin gültig für Setups mit Proxy auf demselben Host/lokaler Erkennung (zum Beispiel Tailscale Serve oder ein lokaler Reverse-Proxy), aber sie machen Loopback-Requests **nicht** für `gateway.auth.mode: "trusted-proxy"` zulässig.
- `allowRealIpFallback`: wenn `true`, akzeptiert das Gateway `X-Real-IP`, wenn `X-Forwarded-For` fehlt. Standard `false` für fail-closed-Verhalten.
- `gateway.tools.deny`: zusätzliche Tool-Namen, die für HTTP `POST /tools/invoke` blockiert werden (erweitert die Standard-Deny-Liste).
- `gateway.tools.allow`: Tool-Namen aus der Standard-HTTP-Deny-Liste entfernen.
- `gateway.tools.deny`: zusätzliche Tool-Namen, die für HTTP `POST /tools/invoke` blockiert werden (erweitert die Standard-Denylist).
- `gateway.tools.allow`: entfernt Tool-Namen aus der Standard-Denylist für HTTP.
</Accordion>
### OpenAI-kompatible Endpoints
### OpenAI-kompatible Endpunkte
- Chat Completions: standardmäßig deaktiviert. Aktivieren mit `gateway.http.endpoints.chatCompletions.enabled: true`.
- Responses API: `gateway.http.endpoints.responses.enabled`.
- Härtung für URL-Eingaben bei Responses:
- Härtung von URL-Eingaben für Responses:
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
Leere Allowlists werden als nicht gesetzt behandelt; verwenden Sie `gateway.http.endpoints.responses.files.allowUrl=false`
und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um das Abrufen per URL zu deaktivieren.
- Optionaler Härtungs-Header für Antworten:
- `gateway.http.securityHeaders.strictTransportSecurity` (nur für HTTPS-Ursprünge setzen, die Sie kontrollieren; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth#tls-termination-and-hsts))
und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um URL-Abruf zu deaktivieren.
- Optionaler Header für Response-Härtung:
- `gateway.http.securityHeaders.strictTransportSecurity` (nur für HTTPS-Originen setzen, die Sie kontrollieren; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth#tls-termination-and-hsts))
### Isolation mehrerer Instanzen
Führen Sie mehrere Gateways auf einem Host mit eindeutigen Ports und State-Dirs aus:
Führen Sie mehrere Gateways auf einem Host mit eindeutigen Ports und Zustandsverzeichnissen aus:
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -368,7 +367,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
Komfort-Flags: `--dev` (verwendet `~/.openclaw-dev` + Port `19001`), `--profile <name>` (verwendet `~/.openclaw-<name>`).
Praktische Flags: `--dev` (verwendet `~/.openclaw-dev` + Port `19001`), `--profile <name>` (verwendet `~/.openclaw-<name>`).
Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
@ -389,10 +388,10 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
```
- `enabled`: aktiviert TLS-Terminierung am Gateway-Listener (HTTPS/WSS) (Standard: `false`).
- `autoGenerate`: erzeugt automatisch ein lokales selbstsigniertes Zertifikats-/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokal/Entwicklung.
- `autoGenerate`: erzeugt automatisch ein lokales selbstsigniertes Zertifikat-/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokale Entwicklungsnutzung.
- `certPath`: Dateisystempfad zur TLS-Zertifikatsdatei.
- `keyPath`: Dateisystempfad zum privaten TLS-Schlüssel; Zugriff sollte auf Berechtigte beschränkt sein.
- `caPath`: optionaler Pfad zu einem CA-Bundle für Client-Validierung oder benutzerdefinierte Trust-Chains.
- `keyPath`: Dateisystempfad zum privaten TLS-Schlüssel; restriktive Berechtigungen beibehalten.
- `caPath`: optionaler CA-Bundle-Pfad für Client-Verifizierung oder benutzerdefinierte Vertrauenskette.
### `gateway.reload`
@ -408,12 +407,12 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
}
```
- `mode`: steuert, wie Konfigurationsbearbeitungen zur Laufzeit angewendet werden.
- `"off"`: Live-Bearbeitungen ignorieren; Änderungen erfordern einen expliziten Neustart.
- `mode`: steuert, wie Konfigurationsänderungen zur Laufzeit angewendet werden.
- `"off"`: Live-Änderungen ignorieren; Änderungen erfordern einen expliziten Neustart.
- `"restart"`: den Gateway-Prozess bei Konfigurationsänderungen immer neu starten.
- `"hot"`: Änderungen im Prozess anwenden, ohne neu zu starten.
- `"hybrid"` (Standard): zuerst Hot-Reload versuchen; bei Bedarf auf Neustart zurückfallen.
- `debounceMs`: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nichtnegative Ganzzahl).
- `"hot"`: Änderungen ohne Neustart direkt im Prozess anwenden.
- `"hybrid"` (Standard): zuerst Hot-Reload versuchen; falls erforderlich auf Neustart zurückfallen.
- `debounceMs`: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nicht-negative Ganzzahl).
- `deferralTimeoutMs`: maximale Wartezeit in ms auf laufende Operationen, bevor ein Neustart erzwungen wird (Standard: `300000` = 5 Minuten).
---
@ -452,46 +451,46 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
```
Auth: `Authorization: Bearer <token>` oder `x-openclaw-token: <token>`.
Hook-Tokens in der Query-String werden abgelehnt.
Hook-Token in der Query-String werden abgelehnt.
Hinweise zu Validierung und Sicherheit:
- `hooks.enabled=true` erfordert ein nicht leeres `hooks.token`.
- `hooks.token` muss sich von `gateway.auth.token` **unterscheiden**; die Wiederverwendung des Gateway-Tokens wird abgelehnt.
- `hooks.enabled=true` erfordert ein nicht-leeres `hooks.token`.
- `hooks.token` muss sich **von** `gateway.auth.token` unterscheiden; die Wiederverwendung des Gateway-Tokens wird abgelehnt.
- `hooks.path` darf nicht `/` sein; verwenden Sie einen dedizierten Unterpfad wie `/hooks`.
- Wenn `hooks.allowRequestSessionKey=true`, schränken Sie `hooks.allowedSessionKeyPrefixes` ein (zum Beispiel `["hook:"]`).
- Wenn `hooks.allowRequestSessionKey=true`, beschränken Sie `hooks.allowedSessionKeyPrefixes` (zum Beispiel `["hook:"]`).
- Wenn ein Mapping oder Preset einen templatisierten `sessionKey` verwendet, setzen Sie `hooks.allowedSessionKeyPrefixes` und `hooks.allowRequestSessionKey=true`. Statische Mapping-Schlüssel erfordern dieses Opt-in nicht.
**Endpoints:**
**Endpunkte:**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- `sessionKey` aus der Request-Payload wird nur akzeptiert, wenn `hooks.allowRequestSessionKey=true` (Standard: `false`).
- `sessionKey` aus dem Request-Payload wird nur akzeptiert, wenn `hooks.allowRequestSessionKey=true` (Standard: `false`).
- `POST /hooks/<name>` → aufgelöst über `hooks.mappings`
- Per Template gerenderte `sessionKey`-Werte aus Mappings werden als extern geliefert behandelt und erfordern ebenfalls `hooks.allowRequestSessionKey=true`.
- Template-gerenderte `sessionKey`-Werte in Mappings werden als extern bereitgestellt behandelt und erfordern ebenfalls `hooks.allowRequestSessionKey=true`.
<Accordion title="Details zu Mappings">
<Accordion title="Mapping-Details">
- `match.path` vergleicht den Unterpfad nach `/hooks` (z. B. `/hooks/gmail` → `gmail`).
- `match.source` vergleicht ein Payload-Feld für generische Pfade.
- Templates wie `{{messages[0].subject}}` lesen aus der Payload.
- `match.path` gleicht den Unterpfad nach `/hooks` ab (z. B. `/hooks/gmail` → `gmail`).
- `match.source` gleicht ein Payload-Feld für generische Pfade ab.
- Templates wie `{{messages[0].subject}}` lesen aus dem Payload.
- `transform` kann auf ein JS-/TS-Modul zeigen, das eine Hook-Aktion zurückgibt.
- `transform.module` muss ein relativer Pfad sein und innerhalb von `hooks.transformsDir` bleiben (absolute Pfade und Traversal werden abgelehnt).
- `agentId` routet an einen bestimmten Agenten; unbekannte IDs fallen auf den Standard zurück.
- `allowedAgentIds`: schränkt explizites Routing ein (`*` oder weggelassen = alle erlauben, `[]` = alle verweigern).
- `defaultSessionKey`: optionaler fester Sitzungsschlüssel für Hook-Agent-Läufe ohne expliziten `sessionKey`.
- `allowRequestSessionKey`: erlaubt Aufrufern von `/hooks/agent` und templategesteuerten Mapping-Sitzungsschlüsseln, `sessionKey` zu setzen (Standard: `false`).
- `agentId` leitet an einen bestimmten Agent weiter; unbekannte IDs fallen auf den Standard zurück.
- `allowedAgentIds`: beschränkt explizites Routing (`*` oder weggelassen = alle erlauben, `[]` = alle verweigern).
- `defaultSessionKey`: optionaler fester Sitzungsschlüssel für Hook-Agent-Ausführungen ohne expliziten `sessionKey`.
- `allowRequestSessionKey`: erlaubt es Aufrufern von `/hooks/agent` und templategesteuerten Mapping-Sitzungsschlüsseln, `sessionKey` zu setzen (Standard: `false`).
- `allowedSessionKeyPrefixes`: optionale Präfix-Allowlist für explizite `sessionKey`-Werte (Request + Mapping), z. B. `["hook:"]`. Sie wird erforderlich, wenn ein Mapping oder Preset einen templatisierten `sessionKey` verwendet.
- `deliver: true` sendet die finale Antwort an einen Kanal; `channel` ist standardmäßig `last`.
- `model` überschreibt das LLM für diesen Hook-Lauf (muss erlaubt sein, wenn ein Modellkatalog gesetzt ist).
- `deliver: true` sendet die endgültige Antwort an einen Channel; `channel` ist standardmäßig `last`.
- `model` überschreibt das LLM für diese Hook-Ausführung (muss erlaubt sein, wenn ein Modellkatalog gesetzt ist).
</Accordion>
### Gmail-Integration
- Das integrierte Gmail-Preset verwendet `sessionKey: "hook:gmail:{{messages[0].id}}"`.
- Wenn Sie dieses Routing pro Nachricht beibehalten, setzen Sie `hooks.allowRequestSessionKey: true` und schränken `hooks.allowedSessionKeyPrefixes` so ein, dass sie zum Gmail-Namespace passen, zum Beispiel `["hook:", "hook:gmail:"]`.
- Wenn Sie `hooks.allowRequestSessionKey: false` benötigen, überschreiben Sie das Preset mit einem statischen `sessionKey` statt mit dem templatisierten Standard.
- Wenn Sie dieses Routing pro Nachricht beibehalten, setzen Sie `hooks.allowRequestSessionKey: true` und beschränken Sie `hooks.allowedSessionKeyPrefixes` so, dass sie zum Gmail-Namespace passen, zum Beispiel `["hook:", "hook:gmail:"]`.
- Wenn Sie `hooks.allowRequestSessionKey: false` benötigen, überschreiben Sie das Preset mit einem statischen `sessionKey` anstelle des templatisierten Standards.
```json5
{
@ -515,7 +514,7 @@ Hinweise zu Validierung und Sicherheit:
```
- Das Gateway startet `gog gmail watch serve` beim Booten automatisch, wenn es konfiguriert ist. Setzen Sie `OPENCLAW_SKIP_GMAIL_WATCHER=1`, um dies zu deaktivieren.
- Führen Sie nicht zusätzlich zu dem Gateway einen separaten `gog gmail watch serve` aus.
- Führen Sie nicht zusätzlich zu dem Gateway ein separates `gog gmail watch serve` aus.
---
@ -531,16 +530,16 @@ Hinweise zu Validierung und Sicherheit:
}
```
- Stellt vom Agenten bearbeitbares HTML/CSS/JS und A2UI über HTTP unter dem Gateway-Port bereit:
- Stellt vom Agent bearbeitbares HTML/CSS/JS und A2UI per HTTP unter dem Gateway-Port bereit:
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- Nur lokal: behalten Sie `gateway.bind: "loopback"` (Standard) bei.
- Nicht-Loopback-Binds: Canvas-Routen erfordern Gateway-Auth (Token/Passwort/trusted-proxy), genauso wie andere HTTP-Oberflächen des Gateway.
- Node-WebViews senden typischerweise keine Auth-Header; nachdem ein Node gekoppelt und verbunden ist, veröffentlicht das Gateway nodebezogene Fähigkeits-URLs für den Zugriff auf Canvas/A2UI.
- Fähigkeits-URLs sind an die aktive Node-WS-Sitzung gebunden und laufen schnell ab. Es wird kein IP-basierter Fallback verwendet.
- Nur lokal: behalten Sie `gateway.bind: "loopback"` bei (Standard).
- Nicht-Loopback-Bindings: Canvas-Routen erfordern Gateway-Authentifizierung (token/password/trusted-proxy), genau wie andere HTTP-Oberflächen des Gateways.
- Node-WebViews senden typischerweise keine Auth-Header; nachdem ein Node gekoppelt und verbunden ist, veröffentlicht das Gateway Node-bezogene Capability-URLs für den Zugriff auf Canvas/A2UI.
- Capability-URLs sind an die aktive WS-Sitzung des Node gebunden und laufen schnell ab. IP-basierter Fallback wird nicht verwendet.
- Injiziert einen Live-Reload-Client in ausgeliefertes HTML.
- Erstellt automatisch eine Starter-`index.html`, wenn leer.
- Stellt A2UI auch unter `/__openclaw__/a2ui/` bereit.
- Erstellt automatisch eine Starter-`index.html`, wenn das Verzeichnis leer ist.
- Stellt A2UI außerdem unter `/__openclaw__/a2ui/` bereit.
- Änderungen erfordern einen Gateway-Neustart.
- Deaktivieren Sie Live-Reload bei großen Verzeichnissen oder `EMFILE`-Fehlern.
@ -562,9 +561,9 @@ Hinweise zu Validierung und Sicherheit:
- `minimal` (Standard): `cliPath` + `sshPort` aus TXT-Records weglassen.
- `full`: `cliPath` + `sshPort` einschließen.
- Der Hostname ist standardmäßig `openclaw`. Überschreiben Sie ihn mit `OPENCLAW_MDNS_HOSTNAME`.
- Hostname ist standardmäßig `openclaw`. Überschreiben mit `OPENCLAW_MDNS_HOSTNAME`.
### Wide-Area (DNS-SD)
### Wide-area (DNS-SD)
```json5
{
@ -574,7 +573,7 @@ Hinweise zu Validierung und Sicherheit:
}
```
Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für netzwerkübergreifende Discovery kombinieren Sie dies mit einem DNS-Server (CoreDNS empfohlen) + Tailscale Split DNS.
Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für netzwerkübergreifende Discovery mit einem DNS-Server (CoreDNS empfohlen) + Tailscale Split DNS kombinieren.
Einrichtung: `openclaw dns setup --apply`.
@ -582,7 +581,7 @@ Einrichtung: `openclaw dns setup --apply`.
## Umgebung
### `env` (Inline-Env-Variablen)
### `env` (inline Umgebungsvariablen)
```json5
{
@ -599,14 +598,14 @@ Einrichtung: `openclaw dns setup --apply`.
}
```
- Inline-Env-Variablen werden nur angewendet, wenn der Prozess-Env der Schlüssel fehlt.
- `.env`-Dateien: `.env` im aktuellen Arbeitsverzeichnis + `~/.openclaw/.env` (keine von beiden überschreibt vorhandene Variablen).
- Inline-Umgebungsvariablen werden nur angewendet, wenn der Prozessumgebung der Schlüssel fehlt.
- `.env`-Dateien: CWD `.env` + `~/.openclaw/.env` (keine von beiden überschreibt vorhandene Variablen).
- `shellEnv`: importiert fehlende erwartete Schlüssel aus Ihrem Login-Shell-Profil.
- Siehe [Umgebung](/de/help/environment) für die vollständige Priorität.
- Vollständige Prioritätsregeln finden Sie unter [Environment](/de/help/environment).
### Env-Variablen-Substitution
### Substitution von Umgebungsvariablen
Referenzieren Sie Env-Variablen in jedem Konfigurations-String mit `${VAR_NAME}`:
Verweisen Sie in beliebigen Konfigurations-Strings mit `${VAR_NAME}` auf Umgebungsvariablen:
```json5
{
@ -616,9 +615,9 @@ Referenzieren Sie Env-Variablen in jedem Konfigurations-String mit `${VAR_NAME}`
}
```
- Es werden nur Großschreibungsnamen passend zu `[A-Z_][A-Z0-9_]*` erkannt.
- Es werden nur Großbuchstabennamen abgeglichen: `[A-Z_][A-Z0-9_]*`.
- Fehlende/leere Variablen werfen beim Laden der Konfiguration einen Fehler.
- Mit `$${VAR}` escapen Sie für ein literales `${VAR}`.
- Mit `$${VAR}` für ein wörtliches `${VAR}` escapen.
- Funktioniert mit `$include`.
---
@ -638,16 +637,16 @@ Verwenden Sie eine Objektform:
Validierung:
- `provider`-Muster: `^[a-z][a-z0-9_-]{0,63}$`
- `source: "env"` id-Muster: `^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` id: absoluter JSON-Pointer (zum Beispiel `"/providers/openai/apiKey"`)
- `source: "exec"` id-Muster: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"`-IDs dürfen keine punktbasierten Slash-getrennten Pfadsegmente `.` oder `..` enthalten (zum Beispiel wird `a/../b` abgelehnt)
- `source: "env"` `id`-Muster: `^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` `id`: absoluter JSON-Pointer (zum Beispiel `"/providers/openai/apiKey"`)
- `source: "exec"` `id`-Muster: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"`-IDs dürfen keine slash-getrennten Pfadsegmente `.` oder `..` enthalten (zum Beispiel wird `a/../b` abgelehnt)
### Unterstützte Credential-Oberfläche
### Unterstützte Anmeldedatenoberfläche
- Kanonische Matrix: [SecretRef Credential Surface](/de/reference/secretref-credential-surface)
- `secrets apply` zielt auf unterstützte Credential-Pfade in `openclaw.json`.
- Refs in `auth-profiles.json` sind in Laufzeitauflösung und Audit-Abdeckung eingeschlossen.
- `auth-profiles.json`-Refs sind in der Laufzeitauflösung und Audit-Abdeckung enthalten.
### Konfiguration von Secret-Providern
@ -679,18 +678,18 @@ Validierung:
Hinweise:
- Der Provider `file` unterstützt `mode: "json"` und `mode: "singleValue"` (`id` muss im Modus singleValue `"value"` sein).
- Pfade von Datei- und Exec-Providern schlagen fail-closed fehl, wenn die Windows-ACL-Prüfung nicht verfügbar ist. Setzen Sie `allowInsecurePath: true` nur für vertrauenswürdige Pfade, die nicht verifiziert werden können.
- Der Provider `exec` erfordert einen absoluten `command`-Pfad und verwendet Protokoll-Payloads über stdin/stdout.
- Standardmäßig werden Symlink-Befehlspfade abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zuzulassen, während der aufgelöste Zielpfad validiert wird.
- Wenn `trustedDirs` konfiguriert ist, gilt die trusted-dir-Prüfung für den aufgelösten Zielpfad.
- Die Child-Umgebung von `exec` ist standardmäßig minimal; übergeben Sie erforderliche Variablen explizit mit `passEnv`.
- SecretRefs werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst; Request-Pfade lesen danach nur noch diesen Snapshot.
- Active-surface filtering gilt während der Aktivierung: nicht auflösbare Refs auf aktiven Oberflächen verhindern Start/Reload, während inaktive Oberflächen mit Diagnosen übersprungen werden.
- Der `file`-Provider unterstützt `mode: "json"` und `mode: "singleValue"` (`id` muss im `singleValue`-Modus `"value"` sein).
- Pfade von File- und Exec-Providern schlagen fail-closed fehl, wenn die Windows-ACL-Verifizierung nicht verfügbar ist. Setzen Sie `allowInsecurePath: true` nur für vertrauenswürdige Pfade, die nicht verifiziert werden können.
- Der `exec`-Provider erfordert einen absoluten `command`-Pfad und verwendet Protokoll-Payloads auf stdin/stdout.
- Standardmäßig werden symbolische Linkpfade für Befehle abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zu erlauben und dabei den aufgelösten Zielpfad zu validieren.
- Wenn `trustedDirs` konfiguriert ist, gilt die Trusted-Dir-Prüfung für den aufgelösten Zielpfad.
- Die Kindumgebung von `exec` ist standardmäßig minimal; übergeben Sie erforderliche Variablen explizit mit `passEnv`.
- SecretRefs werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst, danach lesen Request-Pfade nur noch aus dem Snapshot.
- Die Filterung aktiver Oberflächen gilt während der Aktivierung: Nicht aufgelöste Refs auf aktivierten Oberflächen lassen Start/Reload fehlschlagen, während inaktive Oberflächen mit Diagnosen übersprungen werden.
---
## Speicherung von Authentifizierung
## Auth-Speicher
```json5
{
@ -710,11 +709,11 @@ Hinweise:
- Profile pro Agent werden unter `<agentDir>/auth-profiles.json` gespeichert.
- `auth-profiles.json` unterstützt Refs auf Wertebene (`keyRef` für `api_key`, `tokenRef` für `token`) für statische Credential-Modi.
- OAuth-Modus-Profile (`auth.profiles.<id>.mode = "oauth"`) unterstützen keine SecretRef-gestützten Credentials in Auth-Profilen.
- Statische Runtime-Credentials stammen aus aufgelösten In-Memory-Snapshots; veraltete statische Einträge in `auth.json` werden bereinigt, wenn sie gefunden werden.
- Veraltete OAuth-Importe aus `~/.openclaw/credentials/oauth.json`.
- OAuth-Modus-Profile (`auth.profiles.<id>.mode = "oauth"`) unterstützen keine SecretRef-gestützten Anmeldedaten für Auth-Profile.
- Statische Laufzeit-Anmeldedaten stammen aus aufgelösten In-Memory-Snapshots; ältere statische `auth.json`-Einträge werden bei Erkennung bereinigt.
- Ältere OAuth-Importe aus `~/.openclaw/credentials/oauth.json`.
- Siehe [OAuth](/de/concepts/oauth).
- Runtime-Verhalten für Secrets und Tooling für `audit/configure/apply`: [Secrets Management](/de/gateway/secrets).
- Laufzeitverhalten von Secrets sowie `audit/configure/apply`-Tools: [Secrets Management](/de/gateway/secrets).
### `auth.cooldowns`
@ -736,24 +735,19 @@ Hinweise:
}
```
- `billingBackoffHours`: Basis-Backoff in Stunden, wenn ein Profil aufgrund echter
Abrechnungs-/unzureichender-Guthaben-Fehler fehlschlägt (Standard: `5`). Expliziter Abrechnungstext kann
selbst bei Antworten `401`/`403` hier landen, aber provider-spezifische Text-
Matcher bleiben auf den Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter
`Key limit exceeded`). Wiederholbare HTTP-`402`-Nutzungsfenster- oder
Ausgabenlimit-Nachrichten für Organisation/Workspace bleiben stattdessen im Pfad `rate_limit`.
- `billingBackoffHoursByProvider`: optionale providerbezogene Überschreibungen für Abrechnungs-Backoff-Stunden.
- `billingMaxHours`: Obergrenze in Stunden für exponentielles Wachstum des Abrechnungs-Backoff (Standard: `24`).
- `authPermanentBackoffMinutes`: Basis-Backoff in Minuten für hochsichere Fehler vom Typ `auth_permanent` (Standard: `10`).
- `authPermanentMaxMinutes`: Obergrenze in Minuten für das Wachstum des `auth_permanent`-Backoff (Standard: `60`).
- `failureWindowHours`: gleitendes Fenster in Stunden, das für Backoff-Zähler verwendet wird (Standard: `24`).
- `overloadedProfileRotations`: maximale Anzahl von Auth-Profil-Rotationen desselben Providers bei Überlastungsfehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Provider-Busy-Formen wie `ModelNotReadyException` landen hier.
- `overloadedBackoffMs`: feste Verzögerung vor dem erneuten Versuch einer Provider-/Profilrotation bei Überlastung (Standard: `0`).
- `rateLimitedProfileRotations`: maximale Anzahl von Auth-Profil-Rotationen desselben Providers bei Rate-Limit-Fehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Rate-Limit-Bucket umfasst providergeformten Text wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`.
- `billingBackoffHours`: Basis-Backoff in Stunden, wenn ein Profil aufgrund echter Abrechnungs-/unzureichender-Guthaben-Fehler fehlschlägt (Standard: `5`). Expliziter Abrechnungstext kann auch bei `401`-/`403`-Antworten weiterhin hier landen, aber Provider-spezifische Text-Matcher bleiben auf den Provider beschränkt, zu dem sie gehören (zum Beispiel OpenRouter `Key limit exceeded`). Wiederholbare HTTP-`402`-Nutzungsfenster- oder Ausgabenlimit-Meldungen für Organisation/Workspace bleiben stattdessen im `rate_limit`-Pfad.
- `billingBackoffHoursByProvider`: optionale providerbezogene Overrides für Billing-Backoff in Stunden.
- `billingMaxHours`: Obergrenze in Stunden für exponentielles Wachstum des Billing-Backoff (Standard: `24`).
- `authPermanentBackoffMinutes`: Basis-Backoff in Minuten für `auth_permanent`-Fehler mit hoher Sicherheit (Standard: `10`).
- `authPermanentMaxMinutes`: Obergrenze in Minuten für das Backoff-Wachstum von `auth_permanent` (Standard: `60`).
- `failureWindowHours`: gleitendes Zeitfenster in Stunden, das für Backoff-Zähler verwendet wird (Standard: `24`).
- `overloadedProfileRotations`: maximale Anzahl von Rotationen des Auth-Profils beim selben Provider für Überlastungsfehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Provider-Busy-Formen wie `ModelNotReadyException` fallen hier hinein.
- `overloadedBackoffMs`: feste Verzögerung vor dem erneuten Versuch einer Rotation für einen überlasteten Provider/ein überlastetes Profil (Standard: `0`).
- `rateLimitedProfileRotations`: maximale Anzahl von Rotationen des Auth-Profils beim selben Provider für Rate-Limit-Fehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Rate-Limit-Bucket umfasst providergeprägten Text wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`.
---
## Logging
## Protokollierung
```json5
{
@ -770,12 +764,12 @@ Hinweise:
- Standard-Logdatei: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
- Setzen Sie `logging.file` für einen stabilen Pfad.
- `consoleLevel` wird bei `--verbose` auf `debug` angehoben.
- `maxFileBytes`: maximale Größe der Logdatei in Bytes, bevor Schreibvorgänge unterdrückt werden (positive Ganzzahl; Standard: `524288000` = 500 MB). Verwenden Sie externe Logrotation für Produktionsbereitstellungen.
- `consoleLevel` wird mit `--verbose` auf `debug` erhöht.
- `maxFileBytes`: maximale Größe der Logdatei in Byte, bevor Schreibvorgänge unterdrückt werden (positive Ganzzahl; Standard: `524288000` = 500 MB). Verwenden Sie externe Logrotation für Produktionsbereitstellungen.
---
## Diagnostik
## Diagnose
```json5
{
@ -808,20 +802,20 @@ Hinweise:
}
```
- `enabled`: globaler Schalter für die Ausgabe von Instrumentierung (Standard: `true`).
- `flags`: Array aus Flag-Strings zum Aktivieren gezielter Logausgabe (unterstützt Wildcards wie `"telegram.*"` oder `"*"`).
- `stuckSessionWarnMs`: Altersschwelle in ms, ab der Warnungen für hängende Sitzungen ausgegeben werden, solange eine Sitzung im Verarbeitungsstatus bleibt.
- `otel.enabled`: aktiviert die OpenTelemetry-Export-Pipeline (Standard: `false`).
- `enabled`: globaler Umschalter für die Instrumentierungsausgabe (Standard: `true`).
- `flags`: Array von Flag-Strings zur Aktivierung gezielter Logausgaben (unterstützt Wildcards wie `"telegram.*"` oder `"*"`).
- `stuckSessionWarnMs`: Altersschwelle in ms für die Ausgabe von Warnungen zu hängenden Sitzungen, während eine Sitzung im Verarbeitungszustand bleibt.
- `otel.enabled`: aktiviert die OpenTelemetry-Exportpipeline (Standard: `false`).
- `otel.endpoint`: Collector-URL für den OTel-Export.
- `otel.protocol`: `"http/protobuf"` (Standard) oder `"grpc"`.
- `otel.headers`: zusätzliche HTTP-/gRPC-Metadaten-Header, die mit OTel-Export-Requests gesendet werden.
- `otel.serviceName`: Dienstname für Resource-Attribute.
- `otel.traces` / `otel.metrics` / `otel.logs`: Export von Traces, Metriken oder Logs aktivieren.
- `otel.headers`: zusätzliche HTTP-/gRPC-Metadaten-Header, die mit OTel-Exportanfragen gesendet werden.
- `otel.serviceName`: Dienstname für Ressourcenattribute.
- `otel.traces` / `otel.metrics` / `otel.logs`: aktiviert den Export von Traces, Metriken oder Logs.
- `otel.sampleRate`: Trace-Sampling-Rate `0`–`1`.
- `otel.flushIntervalMs`: Intervall in ms für periodisches Leeren von Telemetrie.
- `cacheTrace.enabled`: Cache-Trace-Snapshots für eingebettete Runs protokollieren (Standard: `false`).
- `otel.flushIntervalMs`: Intervall in ms für das periodische Flushen der Telemetrie.
- `cacheTrace.enabled`: Cache-Trace-Snapshots für eingebettete Ausführungen protokollieren (Standard: `false`).
- `cacheTrace.filePath`: Ausgabepfad für Cache-Trace-JSONL (Standard: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: steuern, was in der Cache-Trace-Ausgabe enthalten ist (alle standardmäßig `true`).
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: steuern, was in die Cache-Trace-Ausgabe aufgenommen wird (alle standardmäßig: `true`).
---
@ -843,12 +837,12 @@ Hinweise:
}
```
- `channel`: Release-Kanal für npm-/git-Installationen — `"stable"`, `"beta"` oder `"dev"`.
- `checkOnStart`: beim Start des Gateway nach npm-Updates suchen (Standard: `true`).
- `channel`: Release-Channel für npm-/git-Installationen — `"stable"`, `"beta"` oder `"dev"`.
- `checkOnStart`: beim Start des Gateways nach npm-Updates suchen (Standard: `true`).
- `auto.enabled`: Hintergrund-Auto-Update für Paketinstallationen aktivieren (Standard: `false`).
- `auto.stableDelayHours`: minimale Verzögerung in Stunden vor dem automatischen Anwenden im Stable-Kanal (Standard: `6`; max: `168`).
- `auto.stableJitterHours`: zusätzliches Rollout-Streuungsfenster für den Stable-Kanal in Stunden (Standard: `12`; max: `168`).
- `auto.betaCheckIntervalHours`: wie oft Prüfungen für den Beta-Kanal in Stunden laufen (Standard: `1`; max: `24`).
- `auto.stableDelayHours`: Mindestverzögerung in Stunden vor der automatischen Anwendung im Stable-Channel (Standard: `6`; Maximalwert: `168`).
- `auto.stableJitterHours`: zusätzliches Verteilungsfenster in Stunden für den Rollout im Stable-Channel (Standard: `12`; Maximalwert: `168`).
- `auto.betaCheckIntervalHours`: wie oft Prüfungen im Beta-Channel in Stunden ausgeführt werden (Standard: `1`; Maximalwert: `24`).
---
@ -882,21 +876,21 @@ Hinweise:
```
- `enabled`: globales ACP-Feature-Gate (Standard: `false`).
- `dispatch.enabled`: unabhängiges Gate für die Turn-Dispatch von ACP-Sitzungen (Standard: `true`). Setzen Sie `false`, um ACP-Befehle verfügbar zu halten, während die Ausführung blockiert wird.
- `backend`: Standard-ID des ACP-Runtime-Backends (muss zu einem registrierten ACP-Runtime-Plugin passen).
- `defaultAgent`: Fallback-Ziel-Agent-ID für ACP-Spawns, wenn keine explizite Zielvorgabe gemacht wird.
- `allowedAgents`: Allowlist von Agent-IDs, die für ACP-Runtime-Sitzungen erlaubt sind; leer bedeutet keine zusätzliche Einschränkung.
- `dispatch.enabled`: unabhängiges Gate für das Dispatching von ACP-Sitzungs-Turns (Standard: `true`). Setzen Sie `false`, um ACP-Befehle verfügbar zu halten, aber die Ausführung zu blockieren.
- `backend`: Standard-ID des ACP-Laufzeit-Backends (muss mit einem registrierten ACP-Runtime-Plugin übereinstimmen).
- `defaultAgent`: Fallback-ID des Ziel-Agenten für ACP, wenn Spawns kein explizites Ziel angeben.
- `allowedAgents`: Allowlist von Agent-IDs, die für ACP-Runtime-Sitzungen erlaubt sind; leer bedeutet keine zusätzliche Beschränkung.
- `maxConcurrentSessions`: maximale Anzahl gleichzeitig aktiver ACP-Sitzungen.
- `stream.coalesceIdleMs`: Leerlauf-Flush-Fenster in ms für gestreamten Text.
- `stream.maxChunkChars`: maximale Chunk-Größe, bevor die Projektion gestreamter Blöcke aufgeteilt wird.
- `stream.repeatSuppression`: wiederholte Status-/Tool-Zeilen pro Turn unterdrücken (Standard: `true`).
- `stream.coalesceIdleMs`: Idle-Flush-Fenster in ms für gestreamten Text.
- `stream.maxChunkChars`: maximale Chunk-Größe vor dem Aufteilen einer gestreamten Blockprojektion.
- `stream.repeatSuppression`: unterdrückt wiederholte Status-/Tool-Zeilen pro Turn (Standard: `true`).
- `stream.deliveryMode`: `"live"` streamt inkrementell; `"final_only"` puffert bis zu terminalen Turn-Ereignissen.
- `stream.hiddenBoundarySeparator`: Trennzeichen vor sichtbarem Text nach versteckten Tool-Ereignissen (Standard: `"paragraph"`).
- `stream.maxOutputChars`: maximale Anzahl an Zeichen der Assistentenausgabe, die pro ACP-Turn projiziert werden.
- `stream.maxSessionUpdateChars`: maximale Anzahl von Zeichen für projizierte ACP-Status-/Update-Zeilen.
- `stream.tagVisibility`: Zuordnung von Tag-Namen zu booleschen Sichtbarkeitsüberschreibungen für gestreamte Ereignisse.
- `runtime.ttlMinutes`: Leerlauf-TTL in Minuten für ACP-Sitzungs-Worker, bevor sie zur Bereinigung infrage kommen.
- `runtime.installCommand`: optionaler Installationsbefehl, der beim Bootstrap einer ACP-Runtime-Umgebung ausgeführt wird.
- `stream.maxOutputChars`: maximale Anzahl projizierter Ausgabenzeichen des Assistenten pro ACP-Turn.
- `stream.maxSessionUpdateChars`: maximale Zeichenzahl für projizierte ACP-Status-/Update-Zeilen.
- `stream.tagVisibility`: Zuordnung von Tag-Namen zu booleschen Sichtbarkeits-Overrides für gestreamte Ereignisse.
- `runtime.ttlMinutes`: Idle-TTL in Minuten für ACP-Sitzungs-Worker, bevor sie für Bereinigung infrage kommen.
- `runtime.installCommand`: optionaler Installationsbefehl, der beim Bootstrap einer ACP-Laufzeitumgebung ausgeführt wird.
---
@ -916,13 +910,13 @@ Hinweise:
- `"random"` (Standard): rotierende lustige/saisonale Slogans.
- `"default"`: fester neutraler Slogan (`All your chats, one OpenClaw.`).
- `"off"`: kein Slogantext (Banner-Titel/Version werden weiterhin angezeigt).
- Um das gesamte Banner auszublenden (nicht nur Slogans), setzen Sie die Env-Variable `OPENCLAW_HIDE_BANNER=1`.
- Um das gesamte Banner auszublenden (nicht nur Slogans), setzen Sie die Umgebungsvariable `OPENCLAW_HIDE_BANNER=1`.
---
## Wizard
Von CLI-geführten Setup-Abläufen (`onboard`, `configure`, `doctor`) geschriebene Metadaten:
Metadaten, die von CLI-gestützten Setup-Abläufen geschrieben werden (`onboard`, `configure`, `doctor`):
```json5
{
@ -940,15 +934,15 @@ Von CLI-geführten Setup-Abläufen (`onboard`, `configure`, `doctor`) geschriebe
## Identität
Siehe Identitätsfelder von `agents.list` unter [Agent-Standards](/de/gateway/config-agents#agent-defaults).
Siehe die Identitätsfelder von `agents.list` unter [Agent defaults](/de/gateway/config-agents#agent-defaults).
---
## Bridge (veraltet, entfernt)
## Bridge (älter, entfernt)
Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über den Gateway-WebSocket. Schlüssel unter `bridge.*` sind nicht mehr Teil des Konfigurationsschemas (die Validierung schlägt fehl, bis sie entfernt werden; `openclaw doctor --fix` kann unbekannte Schlüssel entfernen).
Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über den Gateway-WebSocket. `bridge.*`-Schlüssel sind nicht mehr Teil des Konfigurationsschemas (die Validierung schlägt fehl, bis sie entfernt werden; `openclaw doctor --fix` kann unbekannte Schlüssel entfernen).
<Accordion title="Veraltete Bridge-Konfiguration (historische Referenz)">
<Accordion title="Ältere Bridge-Konfiguration (historische Referenz)">
```json
{
@ -986,11 +980,11 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über
}
```
- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Run-Sitzungen aufbewahrt werden, bevor sie aus `sessions.json` entfernt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; setzen Sie `false`, um dies zu deaktivieren.
- `runLog.maxBytes`: maximale Größe pro Run-Log-Datei (`cron/runs/<jobId>.jsonl`) vor der Bereinigung. Standard: `2_000_000` Bytes.
- `runLog.keepLines`: neueste Zeilen, die bei Auslösung der Run-Log-Bereinigung beibehalten werden. Standard: `2000`.
- `webhookToken`: Bearer-Token, das für die POST-Zustellung von Cron-Webhooks (`delivery.mode = "webhook"`) verwendet wird; wenn weggelassen, wird kein Auth-Header gesendet.
- `webhook`: veraltete Legacy-Fallback-Webhook-URL (http/https), die nur für gespeicherte Jobs verwendet wird, die noch `notify: true` haben.
- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Ausführungssitzungen vor dem Entfernen aus `sessions.json` aufbewahrt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; setzen Sie `false`, um dies zu deaktivieren.
- `runLog.maxBytes`: maximale Größe pro Ausführungs-Logdatei (`cron/runs/<jobId>.jsonl`) vor dem Kürzen. Standard: `2_000_000` Byte.
- `runLog.keepLines`: neueste Zeilen, die beibehalten werden, wenn das Kürzen des Ausführungslogs ausgelöst wird. Standard: `2000`.
- `webhookToken`: Bearer-Token, das für die POST-Zustellung an Cron-Webhooks (`delivery.mode = "webhook"`) verwendet wird; wenn es weggelassen wird, wird kein Auth-Header gesendet.
- `webhook`: veraltete ältere Fallback-Webhook-URL (http/https), die nur für gespeicherte Jobs verwendet wird, die weiterhin `notify: true` haben.
### `cron.retry`
@ -1006,11 +1000,11 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über
}
```
- `maxAttempts`: maximale Wiederholungen für einmalige Jobs bei transienten Fehlern (Standard: `3`; Bereich: `0`–`10`).
- `backoffMs`: Array aus Backoff-Verzögerungen in ms für jeden Wiederholungsversuch (Standard: `[30000, 60000, 300000]`; 1–10 Einträge).
- `retryOn`: Fehlertypen, die Wiederholungen auslösen — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Weglassen, um alle transienten Typen zu wiederholen.
- `maxAttempts`: maximale Anzahl von Wiederholungsversuchen für einmalige Jobs bei temporären Fehlern (Standard: `3`; Bereich: `0`–`10`).
- `backoffMs`: Array von Backoff-Verzögerungen in ms für jeden Wiederholungsversuch (Standard: `[30000, 60000, 300000]`; 1–10 Einträge).
- `retryOn`: Fehlertypen, die Wiederholungsversuche auslösen — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Weglassen, um alle temporären Typen zu wiederholen.
Gilt nur für einmalige Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fehlerbehandlung.
Gilt nur für einmalige Cron-Jobs. Wiederkehrende Jobs verwenden eine getrennte Fehlerbehandlung.
### `cron.failureAlert`
@ -1028,11 +1022,11 @@ Gilt nur für einmalige Cron-Jobs. Wiederkehrende Jobs verwenden eine separate F
}
```
- `enabled`: Failure-Alerts für Cron-Jobs aktivieren (Standard: `false`).
- `after`: aufeinanderfolgende Fehler, bevor ein Alert ausgelöst wird (positive Ganzzahl, min: `1`).
- `cooldownMs`: minimale Millisekunden zwischen wiederholten Alerts für denselben Job (nichtnegative Ganzzahl).
- `mode`: Zustellungsmodus — `"announce"` sendet über eine Kanalnachricht; `"webhook"` postet an den konfigurierten Webhook.
- `accountId`: optionale Konto- oder Kanal-ID zur Eingrenzung der Alert-Zustellung.
- `enabled`: Fehlerwarnungen für Cron-Jobs aktivieren (Standard: `false`).
- `after`: aufeinanderfolgende Fehler, bevor eine Warnung ausgelöst wird (positive Ganzzahl, Min.: `1`).
- `cooldownMs`: minimale Millisekunden zwischen wiederholten Warnungen für denselben Job (nicht-negative Ganzzahl).
- `mode`: Zustellmodus — `"announce"` sendet über eine Channel-Nachricht; `"webhook"` sendet an den konfigurierten Webhook.
- `accountId`: optionale Konto- oder Channel-ID zur Eingrenzung der Warnungszustellung.
### `cron.failureDestination`
@ -1049,51 +1043,51 @@ Gilt nur für einmalige Cron-Jobs. Wiederkehrende Jobs verwenden eine separate F
}
```
- Standardziel für Cron-Fehlerbenachrichtigungen über alle Jobs hinweg.
- Standardziel für Cron-Fehlerbenachrichtigungen für alle Jobs.
- `mode`: `"announce"` oder `"webhook"`; standardmäßig `"announce"`, wenn genügend Zieldaten vorhanden sind.
- `channel`: Kanalüberschreibung für die Zustellung per Announce. `"last"` verwendet den zuletzt bekannten Zustellungskanal erneut.
- `channel`: Channel-Override für die Announce-Zustellung. `"last"` verwendet den zuletzt bekannten Zustell-Channel erneut.
- `to`: explizites Announce-Ziel oder Webhook-URL. Für den Webhook-Modus erforderlich.
- `accountId`: optionale Kontoüberschreibung für die Zustellung.
- `accountId`: optionales Konto-Override für die Zustellung.
- `delivery.failureDestination` pro Job überschreibt diesen globalen Standard.
- Wenn weder global noch pro Job ein Fehlerziel gesetzt ist, fallen Jobs, die bereits über `announce` zustellen, bei Fehlern auf dieses primäre Announce-Ziel zurück.
- `delivery.failureDestination` wird nur für Jobs mit `sessionTarget="isolated"` unterstützt, sofern der primäre `delivery.mode` des Jobs nicht `"webhook"` ist.
- Wenn weder ein globales noch ein jobspezifisches Fehlerziel gesetzt ist, fallen Jobs, die bereits über `announce` zustellen, im Fehlerfall auf dieses primäre Announce-Ziel zurück.
- `delivery.failureDestination` wird nur für Jobs mit `sessionTarget="isolated"` unterstützt, es sei denn, der primäre `delivery.mode` des Jobs ist `"webhook"`.
Siehe [Cron-Jobs](/de/automation/cron-jobs). Isolierte Cron-Ausführungen werden als [Hintergrundaufgaben](/de/automation/tasks) verfolgt.
Siehe [Cron Jobs](/de/automation/cron-jobs). Isolierte Cron-Ausführungen werden als [background tasks](/de/automation/tasks) verfolgt.
---
## Template-Variablen für Medienmodelle
## Vorlagenvariablen für Medienmodelle
Template-Platzhalter, die in `tools.media.models[].args` expandiert werden:
Template-Platzhalter, die in `tools.media.models[].args` erweitert werden:
| Variable | Beschreibung |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | Vollständiger eingehender Nachrichtentext |
| `{{RawBody}}` | Roher Nachrichtentext (ohne Verlaufs-/Absender-Wrapper) |
| `{{RawBody}}` | Roher Nachrichtentext (ohne Verlauf-/Sender-Wrapper) |
| `{{BodyStripped}}` | Nachrichtentext mit entfernten Gruppenerwähnungen |
| `{{From}}` | Absenderkennung |
| `{{From}}` | Senderkennung |
| `{{To}}` | Zielkennung |
| `{{MessageSid}}` | Kanal-Nachrichten-ID |
| `{{MessageSid}}` | Channel-Nachrichten-ID |
| `{{SessionId}}` | Aktuelle Sitzungs-UUID |
| `{{IsNewSession}}` | `"true"`, wenn eine neue Sitzung erstellt wurde |
| `{{MediaUrl}}` | Pseudo-URL der eingehenden Medien |
| `{{MediaUrl}}` | Pseudo-URL eingehender Medien |
| `{{MediaPath}}` | Lokaler Medienpfad |
| `{{MediaType}}` | Medientyp (Bild/Audio/Dokument/…) |
| `{{Transcript}}` | Audio-Transkript |
| `{{Prompt}}` | Aufgelöster Medien-Prompt für CLI-Einträge |
| `{{MaxChars}}` | Aufgelöste maximale Ausgabemenge an Zeichen für CLI-Einträge |
| `{{MaxChars}}` | Aufgelöste maximale Ausgabezeichen für CLI-Einträge |
| `{{ChatType}}` | `"direct"` oder `"group"` |
| `{{GroupSubject}}` | Gruppenbetreff (Best Effort) |
| `{{GroupMembers}}` | Vorschau der Gruppenmitglieder (Best Effort) |
| `{{SenderName}}` | Anzeigename des Absenders (Best Effort) |
| `{{SenderE164}}` | Telefonnummer des Absenders (Best Effort) |
| `{{GroupSubject}}` | Gruppenbetreff (nach bestem Wissen) |
| `{{GroupMembers}}` | Vorschau auf Gruppenmitglieder (nach bestem Wissen) |
| `{{SenderName}}` | Anzeigename des Senders (nach bestem Wissen) |
| `{{SenderE164}}` | Telefonnummer des Senders (nach bestem Wissen) |
| `{{Provider}}` | Provider-Hinweis (whatsapp, telegram, discord usw.) |
---
## Config-Includes (`$include`)
## Konfigurations-Includes (`$include`)
Teilen Sie die Konfiguration in mehrere Dateien auf:
Konfiguration in mehrere Dateien aufteilen:
```json5
// ~/.openclaw/openclaw.json
@ -1108,20 +1102,20 @@ Teilen Sie die Konfiguration in mehrere Dateien auf:
**Merge-Verhalten:**
- Einzelne Datei: ersetzt das umgebende Objekt.
- Array von Dateien: wird in Reihenfolge tief zusammengeführt (spätere überschreiben frühere).
- Einzelne Datei: ersetzt das enthaltende Objekt.
- Array von Dateien: wird der Reihe nach tief zusammengeführt (spätere überschreiben frühere).
- Benachbarte Schlüssel: werden nach den Includes zusammengeführt (überschreiben eingeschlossene Werte).
- Verschachtelte Includes: bis zu 10 Ebenen tief.
- Pfade: werden relativ zur einbindenden Datei aufgelöst, müssen aber innerhalb des Konfigurationsverzeichnisses der obersten Ebene bleiben (`dirname` von `openclaw.json`). Absolute Formen/`../` sind nur erlaubt, wenn sie dennoch innerhalb dieser Grenze aufgelöst werden.
- Von OpenClaw verwaltete Schreibvorgänge, die nur einen einzigen Abschnitt der obersten Ebene ändern, der durch ein Single-File-Include gestützt wird, schreiben in diese eingebundene Datei durch. Zum Beispiel aktualisiert `plugins install` `plugins: { $include: "./plugins.json5" }` in `plugins.json5` und lässt `openclaw.json` unverändert.
- Root-Includes, Include-Arrays und Includes mit benachbarten Überschreibungen sind für von OpenClaw verwaltete Schreibvorgänge schreibgeschützt; solche Schreibvorgänge schlagen fail-closed fehl, statt die Konfiguration abzuflachen.
- Pfade: werden relativ zur einbindenden Datei aufgelöst, müssen aber innerhalb des Konfigurationsverzeichnisses der obersten Ebene bleiben (`dirname` von `openclaw.json`). Absolute Formen und `../` sind nur erlaubt, wenn sie sich weiterhin innerhalb dieser Grenze auflösen.
- OpenClaw-eigene Schreibvorgänge, die nur einen Top-Level-Abschnitt ändern, der durch ein Single-File-Include gestützt wird, schreiben in diese eingebundene Datei zurück. Zum Beispiel aktualisiert `plugins install` `plugins: { $include: "./plugins.json5" }` in `plugins.json5` und lässt `openclaw.json` unverändert.
- Root-Includes, Include-Arrays und Includes mit benachbarten Overrides sind für OpenClaw-eigene Schreibvorgänge schreibgeschützt; diese Schreibvorgänge schlagen fail-closed fehl, statt die Konfiguration zu flatten.
- Fehler: klare Meldungen für fehlende Dateien, Parse-Fehler und zirkuläre Includes.
---
_Verwandt: [Konfiguration](/de/gateway/configuration) · [Konfigurationsbeispiele](/de/gateway/configuration-examples) · [Doctor](/de/gateway/doctor)_
_Verwandt: [Configuration](/de/gateway/configuration) · [Configuration Examples](/de/gateway/configuration-examples) · [Doctor](/de/gateway/doctor)_
## Verwandt
- [Konfiguration](/de/gateway/configuration)
- [Konfigurationsbeispiele](/de/gateway/configuration-examples)
- [Configuration](/de/gateway/configuration)
- [Configuration examples](/de/gateway/configuration-examples)

186
docs/de/gateway/remote.md
View File

@ -1,81 +1,81 @@
---
read_when:
- Remote-Gateway-Setups ausführen oder Fehler beheben
summary: Remote-Zugriff mit SSH-Tunneln (Gateway WS) und Tailnets
title: Remote-Zugriff
summary: Fernzugriff mit SSH-Tunneln (Gateway WS) und Tailnets
title: Fernzugriff
x-i18n:
generated_at: "2026-04-24T06:39:42Z"
generated_at: "2026-04-24T08:57:04Z"
model: gpt-5.4
provider: openai
source_hash: 3753f29d6b3cc3f1a2f749cc0fdfdd60dfde8822f0ec6db0e18e5412de0980da
source_hash: 66eebbe3762134f29f982201d7e79a789624b96042bd931e07d9855710d64bfe
source_path: gateway/remote.md
workflow: 15
---
# Remote-Zugriff (SSH, Tunnel und Tailnets)
# Fernzugriff (SSH, Tunnel und Tailnets)
Dieses Repo unterstützt „remote over SSH“, indem ein einzelnes Gateway (der Master) auf einem dedizierten Host (Desktop/Server) ausgeführt wird und Clients sich damit verbinden.
Dieses Repo unterstützt „remote over SSH“, indem ein einzelnes Gateway (das Master-Gateway) auf einem dedizierten Host (Desktop/Server) läuft und Clients damit verbunden werden.
- Für **Operatoren (Sie / die macOS-App)**: SSH-Tunneling ist der universelle Fallback.
- Für **Nodes (iOS/Android und zukünftige Geräte)**: Verbindung mit dem Gateway-**WebSocket** (LAN/Tailnet oder bei Bedarf per SSH-Tunnel).
- Für **Operatoren (du / die macOS-App)**: SSH-Tunneling ist der universelle Fallback.
- Für **Nodes (iOS/Android und zukünftige Geräte)**: Verbindung zum Gateway-**WebSocket** (**LAN**/Tailnet oder SSH-Tunnel nach Bedarf).
## Die Kernidee
## Die Grundidee
- Der Gateway-WebSocket bindet an **loopback** auf Ihrem konfigurierten Port (standardmäßig `18789`).
- Für Remote-Nutzung leiten Sie diesen Loopback-Port über SSH weiter (oder verwenden ein Tailnet/VPN und benötigen weniger Tunnel).
- Der Gateway-WebSocket bindet an **loopback** auf deinem konfigurierten Port (standardmäßig 18789).
- Für die Remote-Nutzung leitest du diesen loopback-Port per SSH weiter (oder verwendest ein Tailnet/VPN und brauchst weniger Tunnel).
## Häufige VPN-/Tailnet-Setups (wo der Agent lebt)
## Gängige VPN-/Tailnet-Setups (wo der Agent lebt)
Betrachten Sie den **Gateway-Host** als den Ort, „an dem der Agent lebt“. Er besitzt Sitzungen, Auth-Profile, Kanäle und Zustand.
Ihr Laptop/Desktop (und Nodes) verbinden sich mit diesem Host.
Betrachte den **Gateway-Host** als den Ort, „an dem der Agent lebt“. Er besitzt Sitzungen, Auth-Profile, Kanäle und Status.
Dein Laptop/Desktop (und Nodes) verbinden sich mit diesem Host.
### 1) Immer aktives Gateway in Ihrem Tailnet (VPS oder Heimserver)
### 1) Immer aktives Gateway in deinem Tailnet (VPS oder Heimserver)
Führen Sie das Gateway auf einem persistenten Host aus und greifen Sie über **Tailscale** oder SSH darauf zu.
Führe das Gateway auf einem persistenten Host aus und greife über **Tailscale** oder SSH darauf zu.
- **Beste UX:** Behalten Sie `gateway.bind: "loopback"` bei und verwenden Sie **Tailscale Serve** für die Control UI.
- **Fallback:** Behalten Sie Loopback + SSH-Tunnel von jedem Rechner, der Zugriff benötigt.
- **Beste UX:** Behalte `gateway.bind: "loopback"` bei und verwende **Tailscale Serve** für die Control UI.
- **Fallback:** loopback beibehalten + SSH-Tunnel von jedem Rechner, der Zugriff benötigt.
- **Beispiele:** [exe.dev](/de/install/exe-dev) (einfache VM) oder [Hetzner](/de/install/hetzner) (Produktions-VPS).
Das ist ideal, wenn Ihr Laptop oft in den Ruhezustand geht, Sie den Agenten aber permanent aktiv haben möchten.
Das ist ideal, wenn dein Laptop oft im Ruhezustand ist, du den Agent aber immer aktiv haben möchtest.
### 2) Heim-Desktop führt das Gateway aus, Laptop ist die Fernsteuerung
### 2) Heim-Desktop führt das Gateway aus, Laptop dient als Fernsteuerung
Der Laptop führt den Agenten **nicht** aus. Er verbindet sich remote:
Der Laptop führt den Agent **nicht** aus. Er verbindet sich remote:
- Verwenden Sie den Modus **Remote over SSH** der macOS-App (Einstellungen → Allgemein → „OpenClaw runs“).
- Die App öffnet und verwaltet den Tunnel, sodass WebChat + Health Checks „einfach funktionieren“.
- Verwende den Modus **Remote over SSH** der macOS-App (Einstellungen → Allgemein → „OpenClaw läuft“).
- Die App öffnet und verwaltet den Tunnel, sodass WebChat + Zustandsprüfungen „einfach funktionieren“.
Runbook: [macOS remote access](/de/platforms/mac/remote).
Runbook: [macOS-Fernzugriff](/de/platforms/mac/remote).
### 3) Laptop führt das Gateway aus, Remote-Zugriff von anderen Rechnern
### 3) Laptop führt das Gateway aus, Fernzugriff von anderen Rechnern
Behalten Sie das Gateway lokal, aber exponieren Sie es sicher:
Behalte das Gateway lokal, aber stelle es sicher bereit:
- SSH-Tunnel zum Laptop von anderen Rechnern aus, oder
- Tailscale Serve für die Control UI und das Gateway nur auf Loopback halten.
- Tailscale Serve für die Control UI und das Gateway nur auf loopback belassen.
Anleitung: [Tailscale](/de/gateway/tailscale) und [Web overview](/de/web).
Anleitung: [Tailscale](/de/gateway/tailscale) und [Web-Überblick](/de/web).
## Befehlsfluss (was wo läuft)
## Befehlsablauf (was wo läuft)
Ein Gateway-Dienst besitzt Zustand + Kanäle. Nodes sind Peripheriegeräte.
Ein Gateway-Dienst besitzt Status + Kanäle. Nodes sind Peripheriegeräte.
Beispielablauf (Telegram → Node):
Beispielfluss (Telegram → Node):
- Eine Telegram-Nachricht trifft beim **Gateway** ein.
- Das Gateway führt den **Agenten** aus und entscheidet, ob ein Node-Tool aufgerufen werden soll.
- Das Gateway ruft die **Node** über den Gateway-WebSocket auf (`node.*` RPC).
- Die Node liefert das Ergebnis zurück; das Gateway antwortet nach Telegram.
- Das Gateway führt den **Agent** aus und entscheidet, ob ein Node-Tool aufgerufen werden soll.
- Das Gateway ruft den **Node** über den Gateway-WebSocket auf (`node.*`-RPC).
- Der Node gibt das Ergebnis zurück; das Gateway antwortet über Telegram.
Hinweise:
- **Nodes führen den Gateway-Dienst nicht aus.** Pro Host sollte nur ein Gateway laufen, sofern Sie nicht absichtlich isolierte Profile ausführen (siehe [Multiple gateways](/de/gateway/multiple-gateways)).
- Der „Node-Modus“ der macOS-App ist nur ein Node-Client über den Gateway-WebSocket.
- **Nodes führen den Gateway-Dienst nicht aus.** Pro Host sollte nur ein Gateway laufen, außer du betreibst absichtlich isolierte Profile (siehe [Mehrere Gateways](/de/gateway/multiple-gateways)).
- Der „Node-Modus“ der macOS-App ist lediglich ein Node-Client über den Gateway-WebSocket.
## SSH-Tunnel (CLI + Tools)
Erstellen Sie einen lokalen Tunnel zum entfernten Gateway-WS:
Erstelle einen lokalen Tunnel zum entfernten Gateway-WS:
```bash
ssh -N -L 18789:127.0.0.1:18789 user@host
@ -86,13 +86,13 @@ Wenn der Tunnel aktiv ist:
- `openclaw health` und `openclaw status --deep` erreichen jetzt das entfernte Gateway über `ws://127.0.0.1:18789`.
- `openclaw gateway status`, `openclaw gateway health`, `openclaw gateway probe` und `openclaw gateway call` können bei Bedarf ebenfalls die weitergeleitete URL über `--url` ansprechen.
Hinweis: Ersetzen Sie `18789` durch Ihren konfigurierten `gateway.port` (oder `--port`/`OPENCLAW_GATEWAY_PORT`).
Hinweis: Wenn Sie `--url` übergeben, greift die CLI nicht auf Konfigurations- oder Umgebungs-Anmeldedaten zurück.
Geben Sie `--token` oder `--password` ausdrücklich an. Fehlende explizite Anmeldedaten führen zu einem Fehler.
Hinweis: Ersetze `18789` durch deinen konfigurierten `gateway.port` (oder `--port`/`OPENCLAW_GATEWAY_PORT`).
Hinweis: Wenn du `--url` übergibst, greift die CLI nicht auf Konfigurations- oder Umgebungs-Credentials zurück.
Gib `--token` oder `--password` explizit an. Fehlende explizite Credentials führen zu einem Fehler.
## CLI-Remote-Standards
Sie können ein Remote-Ziel persistent speichern, sodass CLI-Befehle es standardmäßig verwenden:
Du kannst ein Remote-Ziel dauerhaft speichern, damit CLI-Befehle es standardmäßig verwenden:
```json5
{
@ -106,69 +106,71 @@ Sie können ein Remote-Ziel persistent speichern, sodass CLI-Befehle es standard
}
```
Wenn das Gateway nur auf Loopback gebunden ist, belassen Sie die URL auf `ws://127.0.0.1:18789` und öffnen Sie zuerst den SSH-Tunnel.
Wenn das Gateway nur auf loopback verfügbar ist, belasse die URL bei `ws://127.0.0.1:18789` und öffne zuerst den SSH-Tunnel.
## Vorrangfolge bei Anmeldedaten
## Credential-Priorität
Die Auflösung der Gateway-Anmeldedaten folgt einem gemeinsamen Vertrag über Call-/Probe-/Status-Pfade und Discord-Exec-Approval-Monitoring hinweg. Node-Host verwendet denselben Basisvertrag mit einer Ausnahme im lokalen Modus (es ignoriert absichtlich `gateway.remote.*`):
Die Auflösung von Gateway-Credentials folgt einem gemeinsamen Vertrag für call/probe/status-Pfade und die Überwachung der Discord-Ausführungsfreigabe. Node-host verwendet denselben Grundvertrag mit einer Ausnahme im lokalen Modus (dort wird `gateway.remote.*` absichtlich ignoriert):
- Explizite Anmeldedaten (`--token`, `--password` oder Tool `gatewayToken`) haben auf Call-Pfaden, die explizite Authentifizierung akzeptieren, immer Vorrang.
- Sicherheit bei URL-Überschreibungen:
- CLI-URL-Überschreibungen (`--url`) verwenden niemals implizite Anmeldedaten aus Konfiguration/Umgebung erneut.
- URL-Überschreibungen per Umgebung (`OPENCLAW_GATEWAY_URL`) dürfen nur Umgebungs-Anmeldedaten verwenden (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`).
- Standardwerte im lokalen Modus:
- Token: `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token` (Remote-Fallback gilt nur, wenn lokaler Eingabewert für Auth-Token nicht gesetzt ist)
- Passwort: `OPENCLAW_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password` (Remote-Fallback gilt nur, wenn lokaler Eingabewert für Auth-Passwort nicht gesetzt ist)
- Standardwerte im Remote-Modus:
- Explizite Credentials (`--token`, `--password` oder Tool-`gatewayToken`) haben bei Call-Pfaden, die explizite Authentifizierung akzeptieren, immer Vorrang.
- Sicherheit bei URL-Overrides:
- CLI-URL-Overrides (`--url`) verwenden niemals implizite Credentials aus Konfiguration/Umgebung erneut.
- URL-Overrides aus Umgebungsvariablen (`OPENCLAW_GATEWAY_URL`) dürfen nur Credentials aus Umgebungsvariablen verwenden (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`).
- Standards im lokalen Modus:
- Token: `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token` (der Remote-Fallback gilt nur, wenn keine lokale Auth-Token-Eingabe gesetzt ist)
- Passwort: `OPENCLAW_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password` (der Remote-Fallback gilt nur, wenn keine lokale Auth-Passwort-Eingabe gesetzt ist)
- Standards im Remote-Modus:
- Token: `gateway.remote.token` -> `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token`
- Passwort: `OPENCLAW_GATEWAY_PASSWORD` -> `gateway.remote.password` -> `gateway.auth.password`
- Ausnahme für Node-Host im lokalen Modus: `gateway.remote.token` / `gateway.remote.password` werden ignoriert.
- Token-Prüfungen für Remote-Probe/Status sind standardmäßig strikt: Sie verwenden nur `gateway.remote.token` (kein lokaler Token-Fallback), wenn der Remote-Modus angesprochen wird.
- Überschreibungen von Gateway-Umgebungswerten verwenden nur `OPENCLAW_GATEWAY_*`.
- Ausnahme für Node-host im lokalen Modus: `gateway.remote.token` / `gateway.remote.password` werden ignoriert.
- Token-Prüfungen für Remote probe/status sind standardmäßig strikt: Sie verwenden nur `gateway.remote.token` (kein lokaler Token-Fallback), wenn der Remote-Modus angesprochen wird.
- Gateway-Umgebungs-Overrides verwenden nur `OPENCLAW_GATEWAY_*`.
## Chat-UI über SSH
WebChat verwendet keinen separaten HTTP-Port mehr. Die SwiftUI-Chat-UI verbindet sich direkt mit dem Gateway-WebSocket.
- Leiten Sie `18789` über SSH weiter (siehe oben) und verbinden Sie Clients dann mit `ws://127.0.0.1:18789`.
- Unter macOS bevorzugen Sie den Modus „Remote over SSH“ der App, der den Tunnel automatisch verwaltet.
- Leite `18789` per SSH weiter (siehe oben) und verbinde dann Clients mit `ws://127.0.0.1:18789`.
- Unter macOS solltest du den Modus „Remote over SSH“ der App bevorzugen, da er den Tunnel automatisch verwaltet.
## macOS-App „Remote over SSH“
Die Menüleisten-App für macOS kann dasselbe Setup Ende zu Ende steuern (Remote-Statusprüfungen, WebChat und Voice-Wake-Weiterleitung).
Die macOS-Menüleisten-App kann dasselbe Setup Ende-zu-Ende steuern (Remote-Statusprüfungen, WebChat und Voice-Wake-Weiterleitung).
Runbook: [macOS remote access](/de/platforms/mac/remote).
Runbook: [macOS-Fernzugriff](/de/platforms/mac/remote).
## Sicherheitsregeln (Remote/VPN)
Kurzfassung: **Behalten Sie das Gateway nur auf Loopback**, es sei denn, Sie sind sicher, dass Sie eine Bindung benötigen.
Kurzfassung: **Belasse das Gateway nur auf loopback**, außer du bist sicher, dass du ein anderes Binding brauchst.
- **Loopback + SSH/Tailscale Serve** ist der sicherste Standard (keine öffentliche Exponierung).
- Klartext-`ws://` ist standardmäßig nur für Loopback vorgesehen. Für vertrauenswürdige private Netzwerke
setzen Sie `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` im Client-Prozess als Break-Glass.
- **Nicht-Loopback-Bindungen** (`lan`/`tailnet`/`custom` oder `auto`, wenn Loopback nicht verfügbar ist) müssen Gateway-Authentifizierung verwenden: Token, Passwort oder einen identitätsbewussten Reverse-Proxy mit `gateway.auth.mode: "trusted-proxy"`.
- `gateway.remote.token` / `.password` sind Anmeldedatenquellen des Clients. Sie konfigurieren den Server selbst **nicht**.
- **Loopback + SSH/Tailscale Serve** ist der sicherste Standard (keine öffentliche Exposition).
- Klartext-`ws://` ist standardmäßig nur für loopback erlaubt. Für vertrauenswürdige private Netzwerke
setze `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` im Client-Prozess als
Break-Glass-Maßnahme. Es gibt kein `openclaw.json`-Äquivalent; dies muss in der
Prozessumgebung des Clients gesetzt werden, der die WebSocket-Verbindung herstellt.
- **Nicht-loopback-Bindings** (`lan`/`tailnet`/`custom` oder `auto`, wenn loopback nicht verfügbar ist) müssen Gateway-Authentifizierung verwenden: Token, Passwort oder einen identitätsbewussten Reverse Proxy mit `gateway.auth.mode: "trusted-proxy"`.
- `gateway.remote.token` / `.password` sind Quellen für Client-Credentials. Sie konfigurieren **nicht** eigenständig die Server-Authentifizierung.
- Lokale Call-Pfade können `gateway.remote.*` nur dann als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist.
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit per SecretRef konfiguriert, aber nicht aufgelöst sind, schlägt die Auflösung fail-closed fehl (kein Remote-Fallback zum Verdecken).
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht aufgelöst werden, schlägt die Auflösung fail-closed fehl (kein verdeckender Remote-Fallback).
- `gateway.remote.tlsFingerprint` pinnt das entfernte TLS-Zertifikat bei Verwendung von `wss://`.
- **Tailscale Serve** kann Datenverkehr für Control UI/WebSocket über Identity-Header authentifizieren,
- **Tailscale Serve** kann Control-UI-/WebSocket-Verkehr über Identitäts-Header authentifizieren,
wenn `gateway.auth.allowTailscale: true`; HTTP-API-Endpunkte verwenden diese
Tailscale-Header-Authentifizierung nicht und folgen stattdessen dem normalen HTTP-
Auth-Modus des Gateway. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Setzen Sie dies auf
`false`, wenn Sie überall Shared-Secret-Authentifizierung möchten.
- Authentifizierung per **Trusted-Proxy** ist nur für identitätsbewusste Proxy-Setups mit Nicht-Loopback gedacht.
Reverse-Proxys auf demselben Host mit Loopback erfüllen `gateway.auth.mode: "trusted-proxy"` nicht.
- Behandeln Sie Browsersteuerung wie Operatorzugriff: nur Tailnet + absichtliches Node Pairing.
Auth-Modus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Setze den Wert auf
`false`, wenn du überall Authentifizierung mit gemeinsamem Geheimnis möchtest.
- Die **trusted-proxy**-Authentifizierung ist nur für nicht-loopback-Setups mit identitätsbewusstem Proxy gedacht.
Reverse Proxies auf demselben Host mit loopback erfüllen `gateway.auth.mode: "trusted-proxy"` nicht.
- Betrachte Browser-Steuerung wie Operator-Zugriff: nur Tailnet + bewusstes Node-Pairing.
Ausführliche Informationen: [Security](/de/gateway/security).
Ausführlich: [Sicherheit](/de/gateway/security).
### macOS: Persistenter SSH-Tunnel über LaunchAgent
### macOS: persistenter SSH-Tunnel per LaunchAgent
Für macOS-Clients, die sich mit einem entfernten Gateway verbinden, verwendet das einfachste persistente Setup einen SSH-Eintrag mit `LocalForward` in der Konfiguration plus einen LaunchAgent, um den Tunnel über Neustarts und Abstürze hinweg aktiv zu halten.
Für macOS-Clients, die sich mit einem entfernten Gateway verbinden, verwendet das einfachste persistente Setup einen SSH-`LocalForward`-Eintrag in der Konfiguration sowie einen LaunchAgent, um den Tunnel über Neustarts und Abstürze hinweg aktiv zu halten.
#### Schritt 1: SSH-Konfiguration hinzufügen
Bearbeiten Sie `~/.ssh/config`:
Bearbeite `~/.ssh/config`:
```ssh
Host remote-gateway
@ -178,7 +180,7 @@ Host remote-gateway
IdentityFile ~/.ssh/id_rsa
```
Ersetzen Sie `<REMOTE_IP>` und `<REMOTE_USER>` durch Ihre Werte.
Ersetze `<REMOTE_IP>` und `<REMOTE_USER>` durch deine Werte.
#### Schritt 2: SSH-Schlüssel kopieren (einmalig)
@ -186,17 +188,17 @@ Ersetzen Sie `<REMOTE_IP>` und `<REMOTE_USER>` durch Ihre Werte.
ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
```
#### Schritt 3: Gateway-Token konfigurieren
#### Schritt 3: das Gateway-Token konfigurieren
Speichern Sie das Token in der Konfiguration, damit es Neustarts überdauert:
Speichere das Token in der Konfiguration, damit es Neustarts überdauert:
```bash
openclaw config set gateway.remote.token "<your-token>"
```
#### Schritt 4: Den LaunchAgent erstellen
#### Schritt 4: den LaunchAgent erstellen
Speichern Sie dies als `~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist`:
Speichere dies als `~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
@ -219,19 +221,19 @@ Speichern Sie dies als `~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist`:
</plist>
```
#### Schritt 5: Den LaunchAgent laden
#### Schritt 5: den LaunchAgent laden
```bash
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist
```
Der Tunnel startet automatisch beim Login, wird nach Abstürzen neu gestartet und hält den weitergeleiteten Port aktiv.
Der Tunnel wird automatisch bei der Anmeldung gestartet, nach einem Absturz neu gestartet und hält den weitergeleiteten Port aktiv.
Hinweis: Wenn Sie einen verbliebenen LaunchAgent `com.openclaw.ssh-tunnel` aus einem älteren Setup haben, entladen und löschen Sie ihn.
Hinweis: Wenn du einen übrig gebliebenen `com.openclaw.ssh-tunnel`-LaunchAgent aus einem älteren Setup hast, entlade und lösche ihn.
#### Fehlerbehebung
Prüfen, ob der Tunnel läuft:
Prüfe, ob der Tunnel läuft:
```bash
ps aux | grep "ssh -N remote-gateway" | grep -v grep
@ -250,15 +252,15 @@ Den Tunnel stoppen:
launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel
```
| Konfigurationseintrag | Was er bewirkt |
| ------------------------------------ | ------------------------------------------------------------ |
| Konfigurationseintrag | Funktion |
| ----------------------------------- | ------------------------------------------------------------ |
| `LocalForward 18789 127.0.0.1:18789` | Leitet den lokalen Port 18789 an den entfernten Port 18789 weiter |
| `ssh -N` | SSH ohne Ausführung entfernter Befehle (nur Portweiterleitung) |
| `KeepAlive` | Startet den Tunnel automatisch neu, wenn er abstürzt |
| `RunAtLoad` | Startet den Tunnel, wenn der LaunchAgent beim Login geladen wird |
| `ssh -N` | SSH ohne Ausführung entfernter Befehle (nur Port-Weiterleitung) |
| `KeepAlive` | Startet den Tunnel automatisch neu, wenn er abstürzt |
| `RunAtLoad` | Startet den Tunnel, wenn der LaunchAgent bei der Anmeldung geladen wird |
## Verwandt
- [Tailscale](/de/gateway/tailscale)
- [Authentication](/de/gateway/authentication)
- [Remote gateway setup](/de/gateway/remote-gateway-readme)
- [Authentifizierung](/de/gateway/authentication)
- [Remote-Gateway-Setup](/de/gateway/remote-gateway-readme)

1006
docs/de/gateway/security/index.md
View File

File diff suppressed because it is too large Load Diff

329
docs/de/gateway/troubleshooting.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Der Fehlerbehebungs-Hub hat Sie für eine tiefergehende Diagnose hierher verwiesen
- Der Hub zur Fehlerbehebung hat Sie für eine eingehendere Diagnose hierher verwiesen.
- Sie benötigen stabile, symptombasierte Runbook-Abschnitte mit exakten Befehlen
summary: Ausführliches Fehlerbehebungs-Runbook für Gateway, Kanäle, Automatisierung, Nodes und Browser
summary: Ausführliches Runbook zur Fehlerbehebung für Gateway, Channels, Automatisierung, Nodes und Browser
title: Fehlerbehebung
x-i18n:
generated_at: "2026-04-24T06:40:32Z"
generated_at: "2026-04-24T08:57:26Z"
model: gpt-5.4
provider: openai
source_hash: 32c4cbbbe8b1cd5eaca34503f4a363d3fa2650e491f83455958eb5725f9d50c5
source_hash: 20066bdab03f05304b3a620fbadc38e4dc74b740da151c58673dcf5196e5f1e1
source_path: gateway/troubleshooting.md
workflow: 15
---
@ -20,7 +20,7 @@ Beginnen Sie bei [/help/troubleshooting](/de/help/troubleshooting), wenn Sie zue
## Befehlsleiter
Führen Sie diese Befehle zuerst in dieser Reihenfolge aus:
Führen Sie zuerst diese Befehle in dieser Reihenfolge aus:
```bash
openclaw status
@ -30,14 +30,13 @@ openclaw doctor
openclaw channels status --probe
```
Erwartete gesunde Signale:
Erwartete Signale für einen fehlerfreien Zustand:
- `openclaw gateway status` zeigt `Runtime: running`, `Connectivity probe: ok` und eine Zeile `Capability: ...`.
- `openclaw doctor` meldet keine blockierenden Konfigurations-/Dienstprobleme.
- `openclaw channels status --probe` zeigt Live-Transportstatus pro Konto und,
wo unterstützt, Probe-/Audit-Ergebnisse wie `works` oder `audit ok`.
- `openclaw doctor` meldet keine blockierenden Config-/Service-Probleme.
- `openclaw channels status --probe` zeigt den Live-Transportstatus pro Account und, wo unterstützt, Probe-/Audit-Ergebnisse wie `works` oder `audit ok`.
## Anthropic 429 zusätzliche Nutzung für langen Kontext erforderlich
## Anthropic 429: zusätzliche Nutzung für langen Kontext erforderlich
Verwenden Sie dies, wenn Logs/Fehler Folgendes enthalten:
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
@ -51,14 +50,14 @@ openclaw config get agents.defaults.models
Achten Sie auf Folgendes:
- Das ausgewählte Anthropic-Opus-/Sonnet-Modell hat `params.context1m: true`.
- Die aktuelle Anthropic-Anmeldedatenquelle ist nicht für Long-Context-Nutzung geeignet.
- Die aktuelle Anthropic-Anmeldeinformation ist nicht für die Nutzung mit langem Kontext geeignet.
- Anfragen schlagen nur bei langen Sitzungen/Modelläufen fehl, die den 1M-Beta-Pfad benötigen.
Lösungsoptionen:
Optionen zur Behebung:
1. Deaktivieren Sie `context1m` für dieses Modell, um auf das normale Kontextfenster zurückzufallen.
2. Verwenden Sie eine Anthropic-Anmeldedatenquelle, die für Long-Context-Anfragen geeignet ist, oder wechseln Sie zu einem Anthropic-API-Schlüssel.
3. Konfigurieren Sie Fallback-Modelle, damit Läufe fortgesetzt werden, wenn Anthropic-Long-Context-Anfragen abgelehnt werden.
1. Deaktivieren Sie `context1m` für dieses Modell, damit auf das normale Kontextfenster zurückgefallen wird.
2. Verwenden Sie eine Anthropic-Anmeldeinformation, die für Anfragen mit langem Kontext geeignet ist, oder wechseln Sie zu einem Anthropic-API-Schlüssel.
3. Konfigurieren Sie Fallback-Modelle, damit Läufe fortgesetzt werden, wenn Anthropic-Anfragen mit langem Kontext abgelehnt werden.
Verwandt:
@ -66,13 +65,13 @@ Verwandt:
- [/reference/token-use](/de/reference/token-use)
- [/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/de/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
## Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agentenläufe schlagen fehl
## Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Läufe schlagen fehl
Verwenden Sie dies, wenn:
- `curl ... /v1/models` funktioniert
- kleine direkte Aufrufe von `/v1/chat/completions` funktionieren
- OpenClaw-Modelläufe nur bei normalen Agenten-Turnussen fehlschlagen
- kleine direkte `/v1/chat/completions`-Aufrufe funktionieren
- OpenClaw-Modelläufe nur bei normalen Agent-Turns fehlschlagen
```bash
curl http://127.0.0.1:1234/v1/models
@ -85,33 +84,22 @@ openclaw logs --follow
Achten Sie auf Folgendes:
- direkte kleine Aufrufe funktionieren, aber OpenClaw-Läufe schlagen nur bei größeren Prompts fehl
- Backend-Fehler darüber, dass `messages[].content` eine Zeichenfolge erwartet
- Backend-Abstürze, die nur bei größeren Prompt-Token-Zahlen oder vollständigen Prompt-
Formen der Agentenlaufzeit auftreten
- direkte kleine Aufrufe sind erfolgreich, aber OpenClaw-Läufe schlagen nur bei größeren Prompts fehl
- Backend-Fehler darüber, dass `messages[].content` einen String erwartet
- Backend-Abstürze, die nur bei größeren Prompt-Token-Zahlen oder vollständigen Agent-Runtime-Prompts auftreten
Häufige Signaturen:
- `messages[...].content: invalid type: sequence, expected a string` → Backend
lehnt strukturierte Chat-Completions-Content-Teile ab. Korrektur: setzen Sie
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
- direkte kleine Requests funktionieren, aber OpenClaw-Agentenläufe schlagen mit Backend-/Modell-
Abstürzen fehl (zum Beispiel Gemma auf einigen `inferrs`-Builds) → Der OpenClaw-Transport ist
wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Prompt-Form der Agentenlaufzeit.
- Fehler werden geringer, nachdem Tools deaktiviert wurden, verschwinden aber nicht → Tool-Schemas waren
Teil des Drucks, aber das verbleibende Problem ist weiterhin Upstream-Kapazität des Modells/Servers oder ein Backend-Bug.
- `messages[...].content: invalid type: sequence, expected a string` → das Backend lehnt strukturierte Chat-Completions-Content-Teile ab. Behebung: Setzen Sie `models.providers.<provider>.models[].compat.requiresStringContent: true`.
- direkte kleine Anfragen sind erfolgreich, aber OpenClaw-Agent-Läufe schlagen mit Backend-/Modellabstürzen fehl (zum Beispiel Gemma auf einigen `inferrs`-Builds) → der OpenClaw-Transport ist wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Prompt-Form der Agent-Runtime.
- Fehler werden geringer, nachdem Tools deaktiviert wurden, verschwinden aber nicht → Tool-Schemas waren Teil der Belastung, aber das verbleibende Problem liegt weiterhin bei der Upstream-Modell-/Server-Kapazität oder einem Backend-Bug.
Lösungsoptionen:
Optionen zur Behebung:
1. Setzen Sie `compat.requiresStringContent: true` für Chat-Completions-Backends, die nur Zeichenfolgen unterstützen.
2. Setzen Sie `compat.supportsTools: false` für Modelle/Backends, die die
Tool-Schema-Oberfläche von OpenClaw nicht zuverlässig verarbeiten können.
3. Reduzieren Sie den Prompt-Druck, wo möglich: kleinerer Workspace-Bootstrap, kürzerer
Sitzungsverlauf, leichteres lokales Modell oder ein Backend mit stärkerer Long-Context-
Unterstützung.
4. Wenn direkte kleine Requests weiterhin funktionieren, OpenClaw-Agenten-Turnusse aber im Backend weiterhin abstürzen,
behandeln Sie dies als Upstream-Einschränkung von Server/Modell und reichen Sie dort
eine Reproduktion mit der akzeptierten Payload-Form ein.
1. Setzen Sie `compat.requiresStringContent: true` für Chat-Completions-Backends, die nur Strings unterstützen.
2. Setzen Sie `compat.supportsTools: false` für Modelle/Backends, die die Tool-Schema-Oberfläche von OpenClaw nicht zuverlässig verarbeiten können.
3. Verringern Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzere Sitzungshistorie, leichteres lokales Modell oder ein Backend mit stärkerer Unterstützung für langen Kontext.
4. Wenn direkte kleine Anfragen weiterhin erfolgreich sind, während OpenClaw-Agent-Turns im Backend weiterhin abstürzen, behandeln Sie dies als Einschränkung des Upstream-Servers/-Modells und melden Sie dort eine Reproduktion mit der akzeptierten Payload-Form.
Verwandt:
@ -121,7 +109,7 @@ Verwandt:
## Keine Antworten
Wenn Kanäle aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinien, bevor Sie irgendetwas neu verbinden.
Wenn Channels aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinien, bevor Sie irgendetwas neu verbinden.
```bash
openclaw status
@ -133,15 +121,15 @@ openclaw logs --follow
Achten Sie auf Folgendes:
- Ausstehendes Pairing für DM-Absender.
- Pairing ausstehend für DM-Absender.
- Erwähnungs-Gating in Gruppen (`requireMention`, `mentionPatterns`).
- Nichtübereinstimmungen in Kanal-/Gruppen-Allowlist.
- Nicht übereinstimmende Channel-/Gruppen-Allowlist-Einträge.
Häufige Signaturen:
- `drop guild message (mention required` → Gruppennachricht wird ignoriert, bis eine Erwähnung erfolgt.
- `pairing request` → Absender benötigt Genehmigung.
- `blocked` / `allowlist` → Absender/Kanal wurde durch Richtlinie gefiltert.
- `pairing request` → der Absender benötigt eine Freigabe.
- `blocked` / `allowlist` → Absender/Channel wurde durch die Richtlinie gefiltert.
Verwandt:
@ -149,9 +137,9 @@ Verwandt:
- [/channels/pairing](/de/channels/pairing)
- [/channels/groups](/de/channels/groups)
## Dashboard-/Control-UI-Konnektivität
## Verbindungsprobleme der Dashboard-/Control-UI
Wenn Dashboard/Control UI keine Verbindung herstellen kann, validieren Sie URL, Auth-Modus und Annahmen zum sicheren Kontext.
Wenn die Dashboard-/Control-UI keine Verbindung herstellt, prüfen Sie URL, Authentifizierungsmodus und Annahmen zum sicheren Kontext.
```bash
openclaw gateway status
@ -164,44 +152,35 @@ openclaw gateway status --json
Achten Sie auf Folgendes:
- Korrekte Probe-URL und Dashboard-URL.
- Nichtübereinstimmung von Auth-Modus/Token zwischen Client und Gateway.
- HTTP-Nutzung, wo Geräteidentität erforderlich ist.
- Nicht übereinstimmender Authentifizierungsmodus/Token zwischen Client und Gateway.
- HTTP-Verwendung dort, wo Geräteidentität erforderlich ist.
Häufige Signaturen:
- `device identity required` → unsicherer Kontext oder fehlende Geräteauthentifizierung.
- `origin not allowed` → Browser-`Origin` ist nicht in `gateway.controlUi.allowedOrigins`
enthalten (oder Sie verbinden sich von einem Browser-Origin ohne Loopback ohne explizite
Allowlist).
- `device nonce required` / `device nonce mismatch` → Client schließt den
challengebasierten Geräteauthentifizierungsablauf nicht ab (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → Client hat die falsche
Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert.
- `AUTH_TOKEN_MISMATCH` mit `canRetryWithDeviceToken=true` → Client kann einen vertrauenswürdigen Retry mit zwischengespeichertem Device-Token durchführen.
- Dieser Retry mit zwischengespeichertem Token verwendet den mit dem gekoppelten
Device-Token gespeicherten Scope-Satz erneut. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihren angeforderten Scope-Satz.
- Außerhalb dieses Retry-Pfads gilt bei Connect-Auth Vorrang für explizites Shared-
Token/Passwort, dann explizites `deviceToken`, dann gespeichertes Device-Token,
dann Bootstrap-Token.
- Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für denselben
`{scope, ip}` serialisiert, bevor der Limiter den Fehler aufzeichnet. Zwei schlechte gleichzeitige Retries vom selben Client können daher beim zweiten Versuch `retry later`
statt zwei einfacher Nichtübereinstimmungen ergeben.
- `too many failed authentication attempts (retry later)` von einem Loopback-Client mit Browser-Origin → wiederholte Fehlschläge von derselben normalisierten `Origin` werden vorübergehend gesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
- wiederholtes `unauthorized` nach diesem Retry → Drift von Shared Token/Device Token; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Device-Token erneut, falls nötig.
- `origin not allowed` → der Browser-`Origin` ist nicht in `gateway.controlUi.allowedOrigins` enthalten (oder Sie verbinden sich von einem Nicht-Loopback-Browser-Origin ohne explizite Allowlist).
- `device nonce required` / `device nonce mismatch` → der Client schließt den challengebasierten Geräteauthentifizierungsablauf nicht ab (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → der Client hat die falsche Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert.
- `AUTH_TOKEN_MISMATCH` mit `canRetryWithDeviceToken=true` → der Client kann einen vertrauenswürdigen erneuten Versuch mit einem zwischengespeicherten Geräte-Token durchführen.
- Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet erneut den zwischengespeicherten Scope-Satz, der zusammen mit dem gepaarten Geräte-Token gespeichert wurde. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihren angeforderten Scope-Satz bei.
- Außerhalb dieses Wiederholungspfads gilt für die Verbindungsauthentifizierung folgende Vorrangreihenfolge: zuerst explizites gemeinsames Token/Passwort, dann explizites `deviceToken`, dann gespeichertes Geräte-Token, dann Bootstrap-Token.
- Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, ip}` serialisiert, bevor der Limiter den Fehlschlag aufzeichnet. Zwei schlechte gleichzeitige Wiederholungsversuche desselben Clients können deshalb beim zweiten Versuch `retry later` anzeigen statt zwei einfacher Nichtübereinstimmungen.
- `too many failed authentication attempts (retry later)` von einem Loopback-Client mit Browser-Origin → wiederholte Fehlschläge desselben normalisierten `Origin` werden vorübergehend gesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
- wiederholtes `unauthorized` nach diesem Wiederholungsversuch → gemeinsames Token/Geräte-Token ist auseinandergeraten; aktualisieren Sie die Token-Config und genehmigen/rotieren Sie das Geräte-Token bei Bedarf erneut.
- `gateway connect failed:` → falsches Host-/Port-/URL-Ziel.
### Schnelle Zuordnung von Auth-Detailcodes
### Kurzübersicht zu Authentifizierungs-Detailcodes
Verwenden Sie `error.details.code` aus der fehlgeschlagenen `connect`-Antwort, um die nächste Aktion auszuwählen:
Verwenden Sie `error.details.code` aus der fehlgeschlagenen `connect`-Antwort, um die nächste Maßnahme auszuwählen:
| Detailcode | Bedeutung | Empfohlene Aktion |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Client hat kein erforderliches Shared Token gesendet. | Token im Client einfügen/setzen und erneut versuchen. Für Dashboard-Pfade: `openclaw config get gateway.auth.token`, dann in die Einstellungen der Control UI einfügen. |
| `AUTH_TOKEN_MISMATCH` | Shared Token stimmte nicht mit dem Gateway-Auth-Token überein. | Wenn `canRetryWithDeviceToken=true`, einen vertrauenswürdigen Retry erlauben. Retries mit zwischengespeichertem Token verwenden gespeicherte genehmigte Scopes erneut; Aufrufer mit explizitem `deviceToken` / `scopes` behalten angeforderte Scopes. Wenn es weiterhin fehlschlägt, führen Sie die [Checkliste zur Wiederherstellung bei Token-Drift](/de/cli/devices#token-drift-recovery-checklist) aus. |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Zwischengespeichertes Token pro Gerät ist veraltet oder widerrufen. | Device-Token mit der [Devices-CLI](/de/cli/devices) rotieren/erneut genehmigen und dann erneut verbinden. |
| `PAIRING_REQUIRED` | Geräteidentität benötigt Genehmigung. Prüfen Sie `error.details.reason` auf `not-paired`, `scope-upgrade`, `role-upgrade` oder `metadata-upgrade` und verwenden Sie `requestId` / `remediationHint`, wenn vorhanden. | Ausstehende Anfrage genehmigen: `openclaw devices list` und dann `openclaw devices approve <requestId>`. Scope-/Rollen-Upgrades verwenden denselben Ablauf, nachdem Sie den angeforderten Zugriff geprüft haben. |
| Detailcode | Bedeutung | Empfohlene Maßnahme |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | Der Client hat kein erforderliches gemeinsames Token gesendet. | Fügen Sie das Token im Client ein bzw. setzen Sie es und versuchen Sie es erneut. Für Dashboard-Pfade: `openclaw config get gateway.auth.token` und dann in die Einstellungen der Control UI einfügen. |
| `AUTH_TOKEN_MISMATCH` | Das gemeinsame Token stimmte nicht mit dem Gateway-Authentifizierungstoken überein. | Wenn `canRetryWithDeviceToken=true`, erlauben Sie einen vertrauenswürdigen erneuten Versuch. Wiederholungsversuche mit zwischengespeichertem Token verwenden erneut die gespeicherten freigegebenen Scopes; Aufrufer mit explizitem `deviceToken` / `scopes` behalten die angeforderten Scopes bei. Wenn es weiterhin fehlschlägt, führen Sie die [Checkliste zur Wiederherstellung bei Token-Drift](/de/cli/devices#token-drift-recovery-checklist) aus. |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Das zwischengespeicherte Token pro Gerät ist veraltet oder widerrufen. | Rotieren bzw. genehmigen Sie das Geräte-Token mit der [devices CLI](/de/cli/devices) erneut und verbinden Sie sich dann erneut. |
| `PAIRING_REQUIRED` | Die Geräteidentität benötigt eine Freigabe. Prüfen Sie `error.details.reason` auf `not-paired`, `scope-upgrade`, `role-upgrade` oder `metadata-upgrade`, und verwenden Sie `requestId` / `remediationHint`, wenn vorhanden. | Genehmigen Sie die ausstehende Anfrage: `openclaw devices list` und dann `openclaw devices approve <requestId>`. Scope-/Rollen-Upgrades verwenden nach Prüfung des angeforderten Zugriffs denselben Ablauf. |
Prüfung der Migration zu Device Auth v2:
Prüfung der Migration auf Geräteauthentifizierung v2:
```bash
openclaw --version
@ -209,7 +188,7 @@ openclaw doctor
openclaw gateway status
```
Wenn Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Client und verifizieren Sie, dass er:
Wenn die Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Client und prüfen Sie, dass er:
1. auf `connect.challenge` wartet
2. die an die Challenge gebundene Payload signiert
@ -217,45 +196,43 @@ Wenn Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Clien
Wenn `openclaw devices rotate` / `revoke` / `remove` unerwartet verweigert wird:
- Sitzungen mit Token gekoppelter Geräte können nur **ihr eigenes** Gerät verwalten, sofern der
Aufrufer nicht zusätzlich `operator.admin` hat
- `openclaw devices rotate --scope ...` kann nur Operator-Scopes anfordern,
die die Sitzung des Aufrufers bereits hält
- Sitzungen mit gepaartem Geräte-Token können nur **ihr eigenes** Gerät verwalten, es sei denn, der Aufrufer hat zusätzlich `operator.admin`
- `openclaw devices rotate --scope ...` kann nur Operator-Scopes anfordern, die die Sitzung des Aufrufers bereits besitzt
Verwandt:
- [/web/control-ui](/de/web/control-ui)
- [/gateway/configuration](/de/gateway/configuration) (Gateway-Auth-Modi)
- [/gateway/configuration](/de/gateway/configuration) (Gateway-Authentifizierungsmodi)
- [/gateway/trusted-proxy-auth](/de/gateway/trusted-proxy-auth)
- [/gateway/remote](/de/gateway/remote)
- [/cli/devices](/de/cli/devices)
## Gateway-Dienst läuft nicht
## Gateway-Service läuft nicht
Verwenden Sie dies, wenn der Dienst installiert ist, der Prozess aber nicht aktiv bleibt.
Verwenden Sie dies, wenn der Service installiert ist, der Prozess aber nicht aktiv bleibt.
```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep # auch systemweite Dienste scannen
openclaw gateway status --deep # auch systemweite Services prüfen
```
Achten Sie auf Folgendes:
- `Runtime: stopped` mit Hinweisen zum Exit.
- Nichtübereinstimmung in der Dienstkonfiguration (`Config (cli)` vs `Config (service)`).
- `Runtime: stopped` mit Hinweisen zum Beenden.
- Nicht übereinstimmende Service-Config (`Config (cli)` vs `Config (service)`).
- Port-/Listener-Konflikte.
- Zusätzliche Installationen von launchd/systemd/schtasks bei Verwendung von `--deep`.
- Zusätzliche launchd-/systemd-/schtasks-Installationen, wenn `--deep` verwendet wird.
- Hinweise zur Bereinigung unter `Other gateway-like services detected (best effort)`.
Häufige Signaturen:
- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → lokaler Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde überschrieben und hat `gateway.mode` verloren. Korrektur: Setzen Sie `gateway.mode="local"` in Ihrer Konfiguration oder führen Sie `openclaw onboard --mode local` / `openclaw setup` erneut aus, um die erwartete Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardpfad der Konfiguration `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bindung ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder, wo konfiguriert, trusted-proxy).
- `another gateway instance is already listening` / `EADDRINUSE` → Portkonflikt.
- `Other gateway-like services detected (best effort)` → veraltete oder parallele launchd/systemd/schtasks-Units existieren. Die meisten Setups sollten ein Gateway pro Rechner beibehalten; wenn Sie mehr als eines benötigen, isolieren Sie Ports + Konfiguration/Zustand/Workspace. Siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host).
- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → der lokale Gateway-Modus ist nicht aktiviert, oder die Config-Datei wurde beschädigt und hat `gateway.mode` verloren. Behebung: Setzen Sie `gateway.mode="local"` in Ihrer Config oder führen Sie `openclaw onboard --mode local` / `openclaw setup` erneut aus, um die erwartete Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardpfad der Config `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder, falls konfiguriert, Trusted Proxy).
- `another gateway instance is already listening` / `EADDRINUSE` → Port-Konflikt.
- `Other gateway-like services detected (best effort)` → veraltete oder parallele launchd-/systemd-/schtasks-Units sind vorhanden. Die meisten Setups sollten ein Gateway pro Rechner beibehalten; wenn Sie tatsächlich mehr als eines benötigen, isolieren Sie Ports sowie Config/State/Workspace. Siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host).
Verwandt:
@ -263,7 +240,7 @@ Verwandt:
- [/gateway/configuration](/de/gateway/configuration)
- [/gateway/doctor](/de/gateway/doctor)
## Gateway hat die zuletzt als gut bekannte Konfiguration wiederhergestellt
## Gateway hat die zuletzt bekannte funktionierende Config wiederhergestellt
Verwenden Sie dies, wenn das Gateway startet, die Logs aber melden, dass `openclaw.json` wiederhergestellt wurde.
@ -279,15 +256,15 @@ Achten Sie auf Folgendes:
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- Eine Datei `openclaw.json.clobbered.*` mit Zeitstempel neben der aktiven Konfiguration
- Ein Systemereignis des Hauptagenten, das mit `Config recovery warning` beginnt
- Eine mit Zeitstempel versehene Datei `openclaw.json.clobbered.*` neben der aktiven Config
- Ein Systemereignis des Haupt-Agents, das mit `Config recovery warning` beginnt
Was passiert ist:
- Die abgelehnte Konfiguration hat bei Start oder Hot Reload die Validierung nicht bestanden.
- Die abgelehnte Config hat bei Start oder Hot-Reload die Validierung nicht bestanden.
- OpenClaw hat die abgelehnte Payload als `.clobbered.*` bewahrt.
- Die aktive Konfiguration wurde aus der zuletzt validierten, als gut bekannten Kopie wiederhergestellt.
- Der nächste Turnus des Hauptagenten wird davor gewarnt, die abgelehnte Konfiguration blind neu zu schreiben.
- Die aktive Config wurde aus der zuletzt validierten, zuletzt bekannten funktionierenden Kopie wiederhergestellt.
- Der nächste Turn des Haupt-Agents wird gewarnt, die abgelehnte Config nicht blind neu zu schreiben.
Prüfen und reparieren:
@ -301,18 +278,18 @@ openclaw doctor
Häufige Signaturen:
- `.clobbered.*` existiert → eine externe direkte Bearbeitung oder ein Start-Lesevorgang wurde wiederhergestellt.
- `.rejected.*` existiert → ein OpenClaw-eigener Schreibvorgang an der Konfiguration ist vor dem Commit an Schema- oder Clobber-Prüfungen gescheitert.
- `Config write rejected:` → der Schreibvorgang wollte erforderliche Struktur entfernen, die Dateigröße stark verkleinern oder ungültige Konfiguration persistieren.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` oder `size-drop-vs-last-good:*` → beim Start wurde die aktuelle Datei als überschrieben behandelt, weil ihr Felder oder Größe im Vergleich zum zuletzt als gut bekannten Backup fehlten.
- `Config last-known-good promotion skipped` → der Kandidat enthielt geschwärzte Secret-Platzhalter wie `***`.
- `.clobbered.*` ist vorhanden → eine externe direkte Bearbeitung oder ein Start-Lesevorgang wurde wiederhergestellt.
- `.rejected.*` ist vorhanden → ein OpenClaw-eigener Schreibvorgang für die Config ist vor dem Commit an Schema- oder Clobber-Prüfungen gescheitert.
- `Config write rejected:` → der Schreibvorgang hätte versucht, die erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder eine ungültige Config zu speichern.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` oder `size-drop-vs-last-good:*` → beim Start wurde die aktuelle Datei als beschädigt behandelt, weil ihr im Vergleich zum zuletzt bekannten funktionierenden Backup Felder oder Größe fehlten.
- `Config last-known-good promotion skipped` → der Kandidat enthielt redigierte Secret-Platzhalter wie `***`.
Lösungsoptionen:
Optionen zur Behebung:
1. Behalten Sie die wiederhergestellte aktive Konfiguration bei, wenn sie korrekt ist.
1. Behalten Sie die wiederhergestellte aktive Config bei, wenn sie korrekt ist.
2. Kopieren Sie nur die beabsichtigten Schlüssel aus `.clobbered.*` oder `.rejected.*` und wenden Sie sie dann mit `openclaw config set` oder `config.patch` an.
3. Führen Sie `openclaw config validate` vor dem Neustart aus.
4. Wenn Sie von Hand bearbeiten, behalten Sie die vollständige JSON5-Konfiguration bei, nicht nur das partielle Objekt, das Sie ändern wollten.
3. Führen Sie vor einem Neustart `openclaw config validate` aus.
4. Wenn Sie von Hand bearbeiten, behalten Sie die vollständige JSON5-Config bei und nicht nur das Teilobjekt, das Sie ändern wollten.
Verwandt:
@ -321,7 +298,7 @@ Verwandt:
- [/cli/config](/de/cli/config)
- [/gateway/doctor](/de/gateway/doctor)
## Warnungen bei Gateway-Probes
## Gateway-Probe-Warnungen
Verwenden Sie dies, wenn `openclaw gateway probe` etwas erreicht, aber trotzdem einen Warnblock ausgibt.
@ -334,15 +311,15 @@ openclaw gateway probe --ssh user@gateway-host
Achten Sie auf Folgendes:
- `warnings[].code` und `primaryTargetId` in der JSON-Ausgabe.
- Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Refs bezieht.
- Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Referenzen bezieht.
Häufige Signaturen:
- `SSH tunnel failed to start; falling back to direct probes.` → SSH-Setup ist fehlgeschlagen, aber der Befehl hat dennoch direkte konfigurierte/Loopback-Ziele versucht.
- `multiple reachable gateways detected` → mehr als ein Ziel hat geantwortet. Das bedeutet meist ein beabsichtigtes Multi-Gateway-Setup oder veraltete/doppelte Listener.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → Verbindung hat funktioniert, aber Detail-RPC ist durch Scope begrenzt; koppeln Sie Geräteidentität oder verwenden Sie Anmeldedaten mit `operator.read`.
- `Capability: pairing-pending` oder `gateway closed (1008): pairing required` → das Gateway hat geantwortet, aber dieser Client benötigt weiterhin Pairing/Genehmigung vor normalem Operatorzugriff.
- nicht aufgelöster SecretRef-Warntext zu `gateway.auth.*` / `gateway.remote.*` → Auth-Material war in diesem Befehlsweg für das fehlgeschlagene Ziel nicht verfügbar.
- `SSH tunnel failed to start; falling back to direct probes.` → das SSH-Setup ist fehlgeschlagen, aber der Befehl hat trotzdem direkte konfigurierte/Loopback-Ziele versucht.
- `multiple reachable gateways detected` → mehr als ein Ziel hat geantwortet. Normalerweise bedeutet das ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → die Verbindung hat funktioniert, aber das Detail-RPC ist durch Scopes eingeschränkt; pairen Sie die Geräteidentität oder verwenden Sie Anmeldeinformationen mit `operator.read`.
- `Capability: pairing-pending` oder `gateway closed (1008): pairing required` → das Gateway hat geantwortet, aber dieser Client benötigt weiterhin Pairing/Freigabe vor normalem Operator-Zugriff.
- nicht aufgelöster `gateway.auth.*`- / `gateway.remote.*`-SecretRef-Warntext → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.
Verwandt:
@ -350,9 +327,9 @@ Verwandt:
- [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host)
- [/gateway/remote](/de/gateway/remote)
## Kanal verbunden, Nachrichten fließen aber nicht
## Channel verbunden, aber Nachrichten fließen nicht
Wenn der Kanalstatus verbunden ist, der Nachrichtenfluss aber tot ist, konzentrieren Sie sich auf Richtlinie, Berechtigungen und kanalspezifische Zustellregeln.
Wenn der Channel-Status verbunden ist, aber kein Nachrichtenfluss stattfindet, konzentrieren Sie sich auf Richtlinien, Berechtigungen und channelspezifische Zustellregeln.
```bash
openclaw channels status --probe
@ -365,14 +342,14 @@ openclaw config get channels
Achten Sie auf Folgendes:
- DM-Richtlinie (`pairing`, `allowlist`, `open`, `disabled`).
- Gruppen-Allowlist und Erwähnungsanforderungen.
- Fehlende API-Berechtigungen/Scopes des Kanals.
- Gruppen-Allowlist und Anforderungen an Erwähnungen.
- Fehlende Channel-API-Berechtigungen/-Scopes.
Häufige Signaturen:
- `mention required` → Nachricht wird durch Gruppen-Erwähnungsrichtlinie ignoriert.
- `pairing` / Traces zu ausstehender Genehmigung → Absender ist nicht genehmigt.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → Problem mit Kanal-Authentifizierung/Berechtigungen.
- `mention required` → Nachricht wird durch die Gruppen-Erwähnungsrichtlinie ignoriert.
- `pairing` / ausstehende Freigabespuren → der Absender ist nicht genehmigt.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → Problem mit Channel-Authentifizierung/Berechtigungen.
Verwandt:
@ -381,9 +358,9 @@ Verwandt:
- [/channels/telegram](/de/channels/telegram)
- [/channels/discord](/de/channels/discord)
## Zustellung von Cron und Heartbeat
## Cron- und Heartbeat-Zustellung
Wenn Cron oder Heartbeat nicht ausgeführt wurde oder nicht zugestellt hat, prüfen Sie zuerst den Zustand des Schedulers und dann das Zustellziel.
Wenn Cron oder Heartbeat nicht ausgeführt wurde oder nicht zugestellt wurde, prüfen Sie zuerst den Scheduler-Status und dann das Zustellziel.
```bash
openclaw cron status
@ -395,19 +372,19 @@ openclaw logs --follow
Achten Sie auf Folgendes:
- Cron aktiviert und nächstes Aufwachen vorhanden.
- Status im Verlauf von Job-Läufen (`ok`, `skipped`, `error`).
- Heartbeat-Überspringgründe (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
- Cron ist aktiviert und der nächste Weckzeitpunkt ist vorhanden.
- Status der Job-Laufhistorie (`ok`, `skipped`, `error`).
- Gründe für übersprungene Heartbeats (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
Häufige Signaturen:
- `cron: scheduler disabled; jobs will not run automatically` → Cron ist deaktiviert.
- `cron: timer tick failed` → Scheduler-Tick fehlgeschlagen; prüfen Sie Datei-/Log-/Laufzeitfehler.
- `heartbeat skipped` mit `reason=quiet-hours` → außerhalb des Fensters aktiver Stunden.
- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` existiert, enthält aber nur leere Zeilen / Markdown-Überschriften, daher überspringt OpenClaw den Modellaufruf.
- `heartbeat skipped` mit `reason=no-tasks-due` → `HEARTBEAT.md` enthält einen `tasks:`-Block, aber bei diesem Tick ist keine der Aufgaben fällig.
- `cron: timer tick failed` → Scheduler-Tick ist fehlgeschlagen; prüfen Sie Datei-/Log-/Runtime-Fehler.
- `heartbeat skipped` mit `reason=quiet-hours` → außerhalb des Zeitfensters für aktive Stunden.
- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` ist vorhanden, enthält aber nur Leerzeilen / Markdown-Header, daher überspringt OpenClaw den Modellaufruf.
- `heartbeat skipped` mit `reason=no-tasks-due` → `HEARTBEAT.md` enthält einen `tasks:`-Block, aber bei diesem Tick ist keine Aufgabe fällig.
- `heartbeat: unknown accountId` → ungültige Account-ID für das Heartbeat-Zustellziel.
- `heartbeat skipped` mit `reason=dm-blocked` → Heartbeat-Ziel wurde zu einem Ziel im Stil einer DM aufgelöst, während `agents.defaults.heartbeat.directPolicy` (oder eine Überschreibung pro Agent) auf `block` gesetzt ist.
- `heartbeat skipped` mit `reason=dm-blocked` → das Heartbeat-Ziel wurde zu einem Ziel im DM-Stil aufgelöst, während `agents.defaults.heartbeat.directPolicy` (oder eine agentbezogene Überschreibung) auf `block` gesetzt ist.
Verwandt:
@ -415,9 +392,9 @@ Verwandt:
- [/automation/cron-jobs](/de/automation/cron-jobs)
- [/gateway/heartbeat](/de/gateway/heartbeat)
## Tool auf gekoppelter Node schlägt fehl
## Tool auf gepaartem Node schlägt fehl
Wenn eine Node gekoppelt ist, Tools aber fehlschlagen, isolieren Sie Vordergrund, Berechtigungen und Genehmigungsstatus.
Wenn ein Node gepaart ist, aber Tools fehlschlagen, isolieren Sie Vordergrundstatus, Berechtigungen und Freigabestatus.
```bash
openclaw nodes status
@ -429,16 +406,16 @@ openclaw status
Achten Sie auf Folgendes:
- Node online mit den erwarteten Fähigkeiten.
- OS-Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
- Exec-Genehmigungen und Zustand der Allowlist.
- Node ist online und hat die erwarteten Capabilities.
- Vom Betriebssystem gewährte Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
- Exec-Freigaben und Allowlist-Status.
Häufige Signaturen:
- `NODE_BACKGROUND_UNAVAILABLE` → Node-App muss im Vordergrund sein.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → fehlende OS-Berechtigung.
- `SYSTEM_RUN_DENIED: approval required` → Exec-Genehmigung ausstehend.
- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl durch Allowlist blockiert.
- `NODE_BACKGROUND_UNAVAILABLE` → die Node-App muss im Vordergrund sein.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → fehlende Betriebssystemberechtigung.
- `SYSTEM_RUN_DENIED: approval required` → Exec-Freigabe steht aus.
- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl wurde durch die Allowlist blockiert.
Verwandt:
@ -448,7 +425,7 @@ Verwandt:
## Browser-Tool schlägt fehl
Verwenden Sie dies, wenn Aktionen des Browser-Tools fehlschlagen, obwohl das Gateway selbst gesund ist.
Verwenden Sie dies, wenn Aktionen des Browser-Tools fehlschlagen, obwohl das Gateway selbst fehlerfrei ist.
```bash
openclaw browser status
@ -461,41 +438,43 @@ openclaw doctor
Achten Sie auf Folgendes:
- Ob `plugins.allow` gesetzt ist und `browser` enthält.
- Gültiger Browserpfad für die ausführbare Datei.
- Gültiger Pfad zur Browser-Executable.
- Erreichbarkeit des CDP-Profils.
- Lokale Chrome-Verfügbarkeit für Profile `existing-session` / `user`.
- Lokale Chrome-Verfügbarkeit für `existing-session`- / `user`-Profile.
Häufige Signaturen:
- `unknown command "browser"` oder `unknown command 'browser'` → das gebündelte Browser-Plugin wird durch `plugins.allow` ausgeschlossen.
- `unknown command "browser"` oder `unknown command 'browser'` → der gebündelte Browser-Plugin ist durch `plugins.allow` ausgeschlossen.
- Browser-Tool fehlt / ist nicht verfügbar, obwohl `browser.enabled=true` → `plugins.allow` schließt `browser` aus, daher wurde das Plugin nie geladen.
- `Failed to start Chrome CDP on port` → Browserprozess konnte nicht gestartet werden.
- `browser.executablePath not found` → konfigurierter Pfad ist ungültig.
- `Failed to start Chrome CDP on port` → der Browser-Prozess konnte nicht gestartet werden.
- `browser.executablePath not found` → der konfigurierte Pfad ist ungültig.
- `browser.cdpUrl must be http(s) or ws(s)` → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema wie `file:` oder `ftp:`.
- `browser.cdpUrl has invalid port` → die konfigurierte CDP-URL hat einen fehlerhaften oder außerhalb des Bereichs liegenden Port.
- `Could not find DevToolsActivePort for chrome` → Chrome-MCP-Existing-Session konnte sich noch nicht an das ausgewählte Browser-Datenverzeichnis anhängen. Öffnen Sie die Browser-Inspect-Seite, aktivieren Sie Remote Debugging, lassen Sie den Browser geöffnet, genehmigen Sie die erste Attach-Abfrage und versuchen Sie es erneut. Wenn kein eingeloggter Zustand erforderlich ist, bevorzugen Sie das verwaltete Profil `openclaw`.
- `No Chrome tabs found for profile="user"` → das Attach-Profil von Chrome MCP hat keine geöffneten lokalen Chrome-Tabs.
- `browser.cdpUrl has invalid port` → die konfigurierte CDP-URL hat einen fehlerhaften oder ungültigen Port.
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session konnte noch keine Verbindung mit dem ausgewählten Browser-Datenverzeichnis herstellen. Öffnen Sie die Browser-Inspektionsseite, aktivieren Sie Remote-Debugging, lassen Sie den Browser geöffnet, bestätigen Sie die erste Verbindungsanfrage und versuchen Sie es dann erneut. Wenn kein angemeldeter Zustand erforderlich ist, bevorzugen Sie das verwaltete Profil `openclaw`.
- `No Chrome tabs found for profile="user"` → das Chrome-MCP-Attach-Profil hat keine offenen lokalen Chrome-Tabs.
- `Remote CDP for profile "<name>" is not reachable` → der konfigurierte Remote-CDP-Endpunkt ist vom Gateway-Host aus nicht erreichbar.
- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → das Attach-Only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber der CDP-WebSocket konnte trotzdem nicht geöffnet werden.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → der aktuellen Gateway-Installation fehlt die Laufzeitabhängigkeit `playwright-core` des gebündelten Browser-Plugins; führen Sie `openclaw doctor --fix` aus und starten Sie dann das Gateway neu. ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, KI-Snapshots, Elementscreenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar.
- `fullPage is not supported for element screenshots` → Screenshot-Anfrage hat `--full-page` mit `--ref` oder `--element` kombiniert.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Screenshot-Aufrufe von Chrome MCP / `existing-session` müssen Seitenerfassung oder ein Snapshot-`--ref` verwenden, nicht CSS-`--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Upload-Hooks in Chrome MCP benötigen Snapshot-Refs, keine CSS-Selektoren.
- `existing-session file uploads currently support one file at a time.` → senden Sie einen Upload pro Aufruf bei Chrome-MCP-Profilen.
- `existing-session dialog handling does not support timeoutMs.` → Dialog-Hooks in Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → das Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber der CDP-WebSocket konnte trotzdem nicht geöffnet werden.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → der aktuellen Gateway-Installation fehlt die gebündelte `playwright-core`-Runtime-Abhängigkeit des Browser-Plugins; führen Sie `openclaw doctor --fix` aus und starten Sie dann das Gateway neu. ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, AI-Snapshots, Elementscreenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar.
- `fullPage is not supported for element screenshots` → die Screenshot-Anfrage hat `--full-page` mit `--ref` oder `--element` kombiniert.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Screenshot-Aufrufe für Chrome MCP / `existing-session` müssen Seitenerfassung oder ein Snapshot-`--ref` verwenden, nicht CSS-`--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Upload-Hooks für Chrome MCP benötigen Snapshot-Refs, keine CSS-Selektoren.
- `existing-session file uploads currently support one file at a time.` → senden Sie bei Chrome-MCP-Profilen einen Upload pro Aufruf.
- `existing-session dialog handling does not support timeoutMs.` → Dialog-Hooks auf Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
- `existing-session type does not support timeoutMs overrides.` → lassen Sie `timeoutMs` für `act:type` auf `profile="user"` / Chrome-MCP-existing-session-Profilen weg oder verwenden Sie ein verwaltetes/CDP-Browserprofil, wenn ein benutzerdefiniertes Timeout erforderlich ist.
- `existing-session evaluate does not support timeoutMs overrides.` → lassen Sie `timeoutMs` für `act:evaluate` auf `profile="user"` / Chrome-MCP-existing-session-Profilen weg oder verwenden Sie ein verwaltetes/CDP-Browserprofil, wenn ein benutzerdefiniertes Timeout erforderlich ist.
- `response body is not supported for existing-session profiles yet.` → `responsebody` erfordert weiterhin einen verwalteten Browser oder ein rohes CDP-Profil.
- veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline auf Attach-Only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile <name>` aus, um die aktive Steuersitzung zu schließen und den Emulationszustand von Playwright/CDP freizugeben, ohne das gesamte Gateway neu zu starten.
- veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline auf Attach-only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile <name>` aus, um die aktive Steuerungssitzung zu schließen und den Emulationszustand von Playwright/CDP freizugeben, ohne das gesamte Gateway neu zu starten.
Verwandt:
- [/tools/browser-linux-troubleshooting](/de/tools/browser-linux-troubleshooting)
- [/tools/browser](/de/tools/browser)
## Wenn nach einem Upgrade plötzlich etwas kaputtging
## Wenn nach einem Upgrade plötzlich etwas kaputt ist
Die meisten Probleme nach einem Upgrade sind Konfigurationsdrift oder jetzt durchgesetzte strengere Standardwerte.
Die meisten Probleme nach einem Upgrade sind Config-Drift oder jetzt erzwungene strengere Standardwerte.
### 1) Verhalten von Auth und URL-Überschreibungen hat sich geändert
### 1) Das Verhalten von Authentifizierung und URL-Überschreibungen hat sich geändert
```bash
openclaw gateway status
@ -504,17 +483,17 @@ openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
```
Was zu prüfen ist:
Was Sie prüfen sollten:
- Wenn `gateway.mode=remote`, können CLI-Aufrufe auf Remote zielen, während Ihr lokaler Dienst in Ordnung ist.
- Explizite `--url`-Aufrufe greifen nicht auf gespeicherte Anmeldedaten zurück.
- Wenn `gateway.mode=remote`, können CLI-Aufrufe auf Remote zielen, während Ihr lokaler Service in Ordnung ist.
- Explizite `--url`-Aufrufe fallen nicht auf gespeicherte Anmeldeinformationen zurück.
Häufige Signaturen:
- `gateway connect failed:` → falsches URL-Ziel.
- `unauthorized` → Endpunkt erreichbar, aber falsche Authentifizierung.
### 2) Guardrails für Bind und Auth sind strenger
### 2) Guardrails für Bind und Authentifizierung sind strenger
```bash
openclaw config get gateway.bind
@ -524,17 +503,17 @@ openclaw gateway status
openclaw logs --follow
```
Was zu prüfen ist:
Was Sie prüfen sollten:
- Nicht-Loopback-Bindungen (`lan`, `tailnet`, `custom`) benötigen einen gültigen Gateway-Authentifizierungspfad: Shared-Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte `trusted-proxy`-Bereitstellung ohne Loopback.
- Nicht-Loopback-Binds (`lan`, `tailnet`, `custom`) benötigen einen gültigen Gateway-Authentifizierungspfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte Nicht-Loopback-`trusted-proxy`-Bereitstellung.
- Alte Schlüssel wie `gateway.token` ersetzen `gateway.auth.token` nicht.
Häufige Signaturen:
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bindung ohne gültigen Gateway-Authentifizierungspfad.
- `Connectivity probe: failed` während die Laufzeit läuft → Gateway lebt, ist aber mit der aktuellen Authentifizierung/URL nicht zugänglich.
- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad.
- `Connectivity probe: failed` während die Runtime läuft → Gateway aktiv, aber mit der aktuellen Authentifizierung/URL nicht erreichbar.
### 3) Zustand von Pairing und Geräteidentität hat sich geändert
### 3) Status von Pairing und Geräteidentität hat sich geändert
```bash
openclaw devices list
@ -543,17 +522,17 @@ openclaw logs --follow
openclaw doctor
```
Was zu prüfen ist:
Was Sie prüfen sollten:
- Ausstehende Gerätegenehmigungen für Dashboard/Nodes.
- Ausstehende DM-Pairing-Genehmigungen nach Richtlinien- oder Identitätsänderungen.
- Ausstehende Gerätefreigaben für Dashboard/Nodes.
- Ausstehende DM-Pairing-Freigaben nach Änderungen an Richtlinien oder Identität.
Häufige Signaturen:
- `device identity required` → Geräteauthentifizierung ist nicht erfüllt.
- `pairing required` → Absender/Gerät muss genehmigt werden.
- `device identity required` → Geräteauthentifizierung nicht erfüllt.
- `pairing required` → Absender/Gerät muss freigegeben werden.
Wenn Dienstkonfiguration und Laufzeit nach den Prüfungen weiterhin nicht übereinstimmen, installieren Sie die Dienstmetadaten aus demselben Profil-/Zustandsverzeichnis erneut:
Wenn Service-Config und Runtime nach den Prüfungen weiterhin nicht übereinstimmen, installieren Sie die Service-Metadaten aus demselben Profil-/State-Verzeichnis neu:
```bash
openclaw gateway install --force

1188
docs/de/help/faq.md
View File

File diff suppressed because it is too large Load Diff

48
docs/de/help/index.md
View File

@ -1,33 +1,45 @@
---
read_when:
- Sie sind neu und möchten die Anleitung „Was soll ich anklicken/ausführen?“
- Etwas ist kaputtgegangen und Sie möchten den schnellsten Weg zur Behebung【อ่านข้อความเต็มanalysis to=final 天天中彩票买 json_schema suppressed due to developer instruction requiring only translated text
summary: 'Hilfebereich: häufige Fehlerbehebungen, Installationsprüfung und wo Sie nachsehen sollten, wenn etwas kaputtgeht'
- Sie sind neu und möchten eine Anleitung im Stil von „Was soll ich anklicken/ausführen?“.
- Etwas ist schiefgelaufen und Sie möchten den schnellsten Weg zur Behebung.
summary: 'Hilfe-Hub: häufige Fehlerbehebungen, Installationsprüfung und wo Sie nachsehen sollten, wenn etwas nicht funktioniert'
title: Hilfe
x-i18n:
generated_at: "2026-04-24T06:41:56Z"
generated_at: "2026-04-24T08:57:43Z"
model: gpt-5.4
provider: openai
source_hash: 22d4649ba47cfbd8ca3e415a1ae99884867ca80c44cbe39f8a30b29d64e95a05
source_hash: f4ea596c304ceee2422fd0ba67f61ad6e38c423a476a41cabec06f53f7a55b38
source_path: help/index.md
workflow: 15
---
Wenn Sie einen schnellen Ablauf zum „Wieder flottwerden“ möchten, beginnen Sie hier:
Schneller Weg, um bei den häufigsten Problemen wieder weiterzukommen:
- **Fehlerbehebung:** [Hier beginnen](/de/help/troubleshooting)
- **Installationsprüfung (Node/npm/PATH):** [Installation](/de/install/node#troubleshooting)
- **Gateway-Probleme:** [Fehlerbehebung für Gateway](/de/gateway/troubleshooting)
- **Logs:** [Logging](/de/logging) und [Gateway-Logging](/de/gateway/logging)
- **Reparaturen:** [Doctor](/de/gateway/doctor)
- [Fehlerbehebung](/de/help/troubleshooting) — entscheidungsbaum nach Symptomen
- [Debugging](/de/help/debugging) — Watch-Modus, rohe Streams, Entwicklungsprofil
- [Installationsprüfung](/de/install/node#troubleshooting) — Prüfungen für Node / npm / PATH
- [Gateway-Fehlerbehebung](/de/gateway/troubleshooting) — Gateway-spezifische Probleme
- [Doctor](/de/gateway/doctor) — automatisierte Reparatur + Diagnosepaket
Wenn Sie nach konzeptionellen Fragen suchen (nicht „etwas ist kaputtgegangen“):
## FAQ
- [FAQ (Konzepte)](/de/help/faq)
- [FAQ](/de/help/faq) — Alltagskonzepte und Betriebsfragen
- [FAQ zum ersten Start](/de/help/faq-first-run) — Installation, Onboarding, Auth, Abonnements, frühe Fehler
- [Modell-FAQ](/de/help/faq-models) — Modellauswahl, Failover, Auth-Profile
## Umgebung und Debugging
## Diagnose
- **Umgebungsvariablen:** [Wo OpenClaw Env-Variablen lädt und ihre Priorität](/de/help/environment)
- **Debugging:** [Watch-Modus, rohe Streams und Dev-Profil](/de/help/debugging)
- **Tests:** [Test-Suites, Live-Tests und Docker-Runner](/de/help/testing)
- **Skripte:** [Hilfsskripte des Repositorys](/de/help/scripts)
- [Umgebungsvariablen](/de/help/environment) — wo OpenClaw env-Variablen lädt und deren Priorität
- [Diagnose-Flags](/de/diagnostics/flags) — Laufzeitdiagnose und ausführliche Modi
- [Node + tsx-Absturz](/de/debug/node-issue) — spezifische Laufzeitabsturzszenarien von Node / tsx
## Tests
- [Tests](/de/help/testing) — Test-Suites und Docker-Runner
- [Live-Tests](/de/help/testing-live) — netzwerkberührende Provider- und CLI-Smokes
## Community und Meta
- [OpenClaw-Lore](/de/start/lore) — die Geschichte
- [Docs-Hubs](/de/start/hubs) — wie diese Dokumentation organisiert ist
- [Docs-Verzeichnis](/de/start/docs-directory) — vollständige Dateizuordnung

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

File diff suppressed because it is too large Load Diff

218
docs/de/help/troubleshooting.md
View File

@ -1,25 +1,23 @@
---
read_when:
- OpenClaw funktioniert nicht und Sie brauchen den schnellsten Weg zur Lösung
- Sie möchten einen Triage-Ablauf, bevor Sie in tiefgehende Runbooks einsteigen
summary: Symptomorientierter Hub zur Fehlerbehebung für OpenClaw
- OpenClaw funktioniert nicht und du brauchst den schnellsten Weg zu einer Lösung
- Du möchtest einen Triage-Ablauf, bevor du in ausführliche Runbooks einsteigst
summary: Hub zur Fehlerbehebung für OpenClaw mit Symptom-orientiertem Einstieg
title: Allgemeine Fehlerbehebung
x-i18n:
generated_at: "2026-04-24T06:42:19Z"
generated_at: "2026-04-24T08:57:52Z"
model: gpt-5.4
provider: openai
source_hash: ce06ddce9de9e5824b4c5e8c182df07b29ce3ff113eb8e29c62aef9a4682e8e9
source_hash: c832c3f7609c56a5461515ed0f693d2255310bf2d3958f69f57c482bcbef97f0
source_path: help/troubleshooting.md
workflow: 15
---
# Fehlerbehebung
Wenn Sie nur 2 Minuten haben, verwenden Sie diese Seite als Triage-Einstieg.
Wenn du nur 2 Minuten hast, nutze diese Seite als Triage-Einstieg.
## Die ersten 60 Sekunden
Führen Sie genau diese Befehlsleiter in dieser Reihenfolge aus:
Führe diese genaue Reihenfolge aus:
```bash
openclaw status
@ -36,42 +34,44 @@ Gute Ausgabe in einer Zeile:
- `openclaw status` → zeigt konfigurierte Kanäle und keine offensichtlichen Auth-Fehler.
- `openclaw status --all` → vollständiger Bericht ist vorhanden und teilbar.
- `openclaw gateway probe` → erwartetes Gateway-Ziel ist erreichbar (`Reachable: yes`). `Capability: ...` zeigt, welche Auth-Stufe der Probe nachweisen konnte, und `Read probe: limited - missing scope: operator.read` bedeutet eingeschränkte Diagnose, nicht einen Verbindungsfehler.
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` und eine plausible Zeile `Capability: ...`. Verwenden Sie `--require-rpc`, wenn Sie zusätzlich einen RPC-Nachweis mit Leseberechtigung brauchen.
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` und eine plausible `Capability: ...`-Zeile. Verwende `--require-rpc`, wenn du zusätzlich einen Nachweis für Read-Scope-RPC brauchst.
- `openclaw doctor` → keine blockierenden Konfigurations-/Dienstfehler.
- `openclaw channels status --probe` → ein erreichbares Gateway liefert Live-Transportstatus pro Account plus Probe-/Audit-Ergebnisse wie `works` oder `audit ok`; wenn das Gateway nicht erreichbar ist, fällt der Befehl auf rein konfigurationsbasierte Zusammenfassungen zurück.
- `openclaw channels status --probe` → ein erreichbares Gateway liefert Live-Transportstatus pro Account
plus Probe-/Audit-Ergebnisse wie `works` oder `audit ok`; wenn das
Gateway nicht erreichbar ist, fällt der Befehl auf reine Konfigurations-Zusammenfassungen zurück.
- `openclaw logs --follow` → stetige Aktivität, keine sich wiederholenden fatalen Fehler.
## Anthropic Long-Context 429
## Anthropic Long Context 429
Wenn Sie Folgendes sehen:
Wenn du Folgendes siehst:
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`,
gehen Sie zu [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/de/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
gehe zu [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/de/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
## Lokales OpenAI-kompatibles Backend funktioniert direkt, aber nicht in OpenClaw
Wenn Ihr lokales oder selbst gehostetes `/v1`-Backend kleine direkte
Wenn dein lokales oder selbst gehostetes `/v1`-Backend kleine direkte
`/v1/chat/completions`-Probes beantwortet, aber bei `openclaw infer model run` oder normalen
Agenten-Turns fehlschlägt:
Agent-Turns fehlschlägt:
1. Wenn der Fehler erwähnt, dass `messages[].content` einen String erwartet, setzen Sie
1. Wenn der Fehler erwähnt, dass `messages[].content` einen String erwartet, setze
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
2. Wenn das Backend weiterhin nur bei OpenClaw-Agenten-Turns fehlschlägt, setzen Sie
`models.providers.<provider>.models[].compat.supportsTools: false` und versuchen Sie es erneut.
2. Wenn das Backend weiterhin nur bei OpenClaw-Agent-Turns fehlschlägt, setze
`models.providers.<provider>.models[].compat.supportsTools: false` und versuche es erneut.
3. Wenn winzige direkte Aufrufe weiterhin funktionieren, aber größere OpenClaw-Prompts das
Backend zum Absturz bringen, behandeln Sie das verbleibende Problem als Einschränkung des Upstream-Modells/Servers und
fahren Sie im tiefgehenden Runbook fort:
Backend zum Absturz bringen, behandle das verbleibende Problem als Upstream-Modell-/Server-Einschränkung und
fahre im ausführlichen Runbook fort:
[/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/de/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
## Plugin-Installation schlägt fehl wegen fehlender openclaw extensions
## Plugin-Installation schlägt mit fehlenden openclaw extensions fehl
Wenn die Installation mit `package.json missing openclaw.extensions` fehlschlägt, verwendet das Plugin-Paket
eine alte Form, die OpenClaw nicht mehr akzeptiert.
Korrektur im Plugin-Paket:
Behebung im Plugin-Paket:
1. Fügen Sie `openclaw.extensions` zu `package.json` hinzu.
2. Verweisen Sie Einträge auf gebaute Laufzeitdateien (normalerweise `./dist/index.js`).
3. Veröffentlichen Sie das Plugin erneut und führen Sie `openclaw plugins install <package>` erneut aus.
1. Füge `openclaw.extensions` zu `package.json` hinzu.
2. Verweise die Einträge auf gebaute Laufzeitdateien (normalerweise `./dist/index.js`).
3. Veröffentliche das Plugin erneut und führe `openclaw plugins install <package>` noch einmal aus.
Beispiel:
@ -85,28 +85,28 @@ Beispiel:
}
```
Referenz: [Plugin architecture](/de/plugins/architecture)
Referenz: [Plugin-Architektur](/de/plugins/architecture)
## Entscheidungsbaum
```mermaid
flowchart TD
A[OpenClaw is not working] --> B{What breaks first}
B --> C[No replies]
B --> D[Dashboard or Control UI will not connect]
B --> E[Gateway will not start or service not running]
B --> F[Channel connects but messages do not flow]
B --> G[Cron or heartbeat did not fire or did not deliver]
B --> H[Node is paired but camera canvas screen exec fails]
B --> I[Browser tool fails]
A[OpenClaw funktioniert nicht] --> B{Was bricht zuerst}
B --> C[Keine Antworten]
B --> D[Dashboard oder Control UI verbindet nicht]
B --> E[Gateway startet nicht oder Dienst läuft nicht]
B --> F[Kanal verbindet sich, aber Nachrichten fließen nicht]
B --> G[Cron oder Heartbeat wurde nicht ausgelöst oder nicht zugestellt]
B --> H[Node ist gekoppelt, aber camera canvas screen exec schlägt fehl]
B --> I[Browser-Tool schlägt fehl]
C --> C1[/No replies section/]
D --> D1[/Control UI section/]
E --> E1[/Gateway section/]
F --> F1[/Channel flow section/]
G --> G1[/Automation section/]
H --> H1[/Node tools section/]
I --> I1[/Browser section/]
C --> C1[/Abschnitt Keine Antworten/]
D --> D1[/Abschnitt Control UI/]
E --> E1[/Abschnitt Gateway/]
F --> F1[/Abschnitt Nachrichtenfluss im Kanal/]
G --> G1[/Abschnitt Automatisierung/]
H --> H1[/Abschnitt Node-Tools/]
I --> I1[/Abschnitt Browser/]
```
<AccordionGroup>
@ -124,16 +124,16 @@ flowchart TD
- `Runtime: running`
- `Connectivity probe: ok`
- `Capability: read-only`, `write-capable` oder `admin-capable`
- Ihr Kanal zeigt verbundenen Transport und, wo unterstützt, `works` oder `audit ok` in `channels status --probe`
- Absender erscheint als genehmigt (oder die DM-Richtlinie ist open/allowlist)
- Dein Kanal zeigt einen verbundenen Transport und, wo unterstützt, `works` oder `audit ok` in `channels status --probe`
- Absender erscheint als genehmigt (oder die DM-Richtlinie ist offen/Allowlist)
Häufige Log-Signaturen:
- `drop guild message (mention required` → Erwähnungs-Gating hat die Nachricht in Discord blockiert.
- `pairing request` → Absender ist nicht genehmigt und wartet auf Genehmigung für DM-Pairing.
- `blocked` / `allowlist` in Kanal-Logs → Absender, Raum oder Gruppe wird gefiltert.
- `drop guild message (mention required` → Mention-Gating hat die Nachricht in Discord blockiert.
- `pairing request` → Absender ist nicht genehmigt und wartet auf DM-Kopplungsfreigabe.
- `blocked` / `allowlist` in den Kanallogs → Absender, Raum oder Gruppe wird gefiltert.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/gateway/troubleshooting#no-replies](/de/gateway/troubleshooting#no-replies)
- [/channels/troubleshooting](/de/channels/troubleshooting)
@ -141,7 +141,7 @@ flowchart TD
</Accordion>
<Accordion title="Dashboard oder Control UI kann keine Verbindung herstellen">
<Accordion title="Dashboard oder Control UI verbindet nicht">
```bash
openclaw status
openclaw gateway status
@ -159,16 +159,22 @@ flowchart TD
Häufige Log-Signaturen:
- `device identity required` → HTTP-/unsicherer Kontext kann Geräte-Auth nicht abschließen.
- `origin not allowed` → Browser-`Origin` ist für das Gateway-Ziel der Control UI nicht erlaubt.
- `AUTH_TOKEN_MISMATCH` mit Retry-Hinweisen (`canRetryWithDeviceToken=true`) → ein vertrauenswürdiger Retry mit Geräte-Token kann automatisch erfolgen.
- Dieser Retry mit gecachtem Token verwendet erneut die gecachte Scope-Menge, die mit dem gepairten Geräte-Token gespeichert wurde. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihre angeforderte Scope-Menge.
- Auf dem asynchronen Tailscale-Serve-Pfad der Control UI werden fehlgeschlagene Versuche für dasselbe `{scope, ip}` serialisiert, bevor der Limiter den Fehlschlag protokolliert, sodass ein zweiter gleichzeitiger fehlerhafter Retry bereits `retry later` anzeigen kann.
- `too many failed authentication attempts (retry later)` von einer localhost-Browser-Origin → wiederholte Fehler von derselben `Origin` werden vorübergehend gesperrt; eine andere localhost-Origin verwendet einen separaten Bucket.
- wiederholtes `unauthorized` nach diesem Retry → falsches Token/Passwort, Auth-Modus-Mismatch oder veraltetes gepairtes Geräte-Token.
- `gateway connect failed:` → UI zielt auf falsche URL/falschen Port oder auf ein nicht erreichbares Gateway.
- `device identity required` → HTTP-/nicht-sicherer Kontext kann Geräteauthentifizierung nicht abschließen.
- `origin not allowed` → Browser-`Origin` ist für das Gateway-Ziel der Control UI nicht erlaubt
- `AUTH_TOKEN_MISMATCH` mit Wiederholungs-Hinweisen (`canRetryWithDeviceToken=true`) → ein vertrauenswürdiger Retry mit Device-Token kann automatisch erfolgen.
- Dieser Retry mit zwischengespeichertem Token verwendet erneut die zwischengespeicherte Scope-Menge, die mit dem gekoppelten
Device-Token gespeichert wurde. Aufrufer mit explizitem `deviceToken` / expliziten `scopes`
behalten stattdessen ihre angeforderte Scope-Menge.
- Im asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe
`{scope, ip}` serialisiert, bevor der Limiter den Fehler erfasst, daher kann ein
zweiter gleichzeitiger fehlerhafter Retry bereits `retry later` anzeigen.
- `too many failed authentication attempts (retry later)` von einem localhost-
Browser-`Origin` → wiederholte Fehlversuche von derselben `Origin` werden vorübergehend
gesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
- wiederholtes `unauthorized` nach diesem Retry → falsches Token/Passwort, nicht passender Auth-Modus oder veraltetes gekoppeltes Device-Token.
- `gateway connect failed:` → UI zielt auf die falsche URL/den falschen Port oder ein nicht erreichbares Gateway.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/de/gateway/troubleshooting#dashboard-control-ui-connectivity)
- [/web/control-ui](/de/web/control-ui)
@ -176,7 +182,7 @@ flowchart TD
</Accordion>
<Accordion title="Gateway startet nicht oder Dienst ist installiert, aber läuft nicht">
<Accordion title="Gateway startet nicht oder Dienst ist installiert, läuft aber nicht">
```bash
openclaw status
openclaw gateway status
@ -194,11 +200,11 @@ flowchart TD
Häufige Log-Signaturen:
- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → Gateway-Modus ist auf remote gesetzt, oder in der Konfigurationsdatei fehlt die Markierung für den lokalen Modus und sie sollte repariert werden.
- `refusing to bind gateway ... without auth` → Bind ohne Loopback ohne gültigen Gateway-Auth-Pfad (Token/Passwort oder, falls konfiguriert, trusted-proxy).
- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → Gateway-Modus ist remote, oder der Konfigurationsdatei fehlt die Kennzeichnung für den lokalen Modus und sie sollte repariert werden.
- `refusing to bind gateway ... without auth` → Nicht-loopback-Binding ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder trusted-proxy, sofern konfiguriert).
- `another gateway instance is already listening` oder `EADDRINUSE` → Port ist bereits belegt.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/gateway/troubleshooting#gateway-service-not-running](/de/gateway/troubleshooting#gateway-service-not-running)
- [/gateway/background-process](/de/gateway/background-process)
@ -217,17 +223,17 @@ flowchart TD
Gute Ausgabe sieht so aus:
- Kanal-Transport ist verbunden.
- Kanaltransport ist verbunden.
- Pairing-/Allowlist-Prüfungen bestehen.
- Erwähnungen werden erkannt, wo erforderlich.
- Mentions werden erkannt, wo sie erforderlich sind.
Häufige Log-Signaturen:
- `mention required` → Erwähnungs-Gating hat die Verarbeitung in einer Gruppe blockiert.
- `mention required` → Mention-Gating in Gruppen hat die Verarbeitung blockiert.
- `pairing` / `pending` → DM-Absender ist noch nicht genehmigt.
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → Problem mit Kanalberechtigungen/Token.
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → Problem mit Kanalberechtigungen oder -Token.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/de/gateway/troubleshooting#channel-connected-messages-not-flowing)
- [/channels/troubleshooting](/de/channels/troubleshooting)
@ -246,7 +252,7 @@ flowchart TD
Gute Ausgabe sieht so aus:
- `cron.status` zeigt aktiviert mit dem nächsten Wake.
- `cron.status` zeigt aktiviert mit einem nächsten Aufweckzeitpunkt.
- `cron runs` zeigt aktuelle `ok`-Einträge.
- Heartbeat ist aktiviert und nicht außerhalb der aktiven Stunden.
@ -254,13 +260,13 @@ flowchart TD
- `cron: scheduler disabled; jobs will not run automatically` → Cron ist deaktiviert.
- `heartbeat skipped` mit `reason=quiet-hours` → außerhalb der konfigurierten aktiven Stunden.
- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` existiert, enthält aber nur leere/header-only Grundstruktur.
- `heartbeat skipped` mit `reason=no-tasks-due` → Task-Modus von `HEARTBEAT.md` ist aktiv, aber keines der Task-Intervalle ist bislang fällig.
- `heartbeat skipped` mit `reason=alerts-disabled` → sämtliche Heartbeat-Sichtbarkeit ist deaktiviert (`showOk`, `showAlerts` und `useIndicator` sind alle aus).
- `requests-in-flight` → Haupt-Lane beschäftigt; Heartbeat-Wake wurde verschoben.
- `unknown accountId` → Ziel-Account für Heartbeat-Zustellung existiert nicht.
- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` existiert, enthält aber nur leere/header-only-Struktur.
- `heartbeat skipped` mit `reason=no-tasks-due` → Der Task-Modus von `HEARTBEAT.md` ist aktiv, aber keines der Task-Intervalle ist bisher fällig.
- `heartbeat skipped` mit `reason=alerts-disabled` → die gesamte Heartbeat-Sichtbarkeit ist deaktiviert (`showOk`, `showAlerts` und `useIndicator` sind alle aus).
- `requests-in-flight` → Hauptpfad ist beschäftigt; Heartbeat-Wakeup wurde verschoben.
- `unknown accountId` → Ziel-Account für die Heartbeat-Zustellung existiert nicht.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/de/gateway/troubleshooting#cron-and-heartbeat-delivery)
- [/automation/cron-jobs#troubleshooting](/de/automation/cron-jobs#troubleshooting)
@ -268,7 +274,7 @@ flowchart TD
</Accordion>
<Accordion title="Node ist gepairt, aber Tool für Kamera/Canvas/Bildschirm/Exec schlägt fehl">
<Accordion title="Node ist gekoppelt, aber Tool schlägt bei camera canvas screen exec fehl">
```bash
openclaw status
openclaw gateway status
@ -279,18 +285,18 @@ flowchart TD
Gute Ausgabe sieht so aus:
- Node ist als verbunden und gepairt für die Rolle `node` aufgeführt.
- Fähigkeit existiert für den Befehl, den Sie aufrufen.
- Berechtigungsstatus ist für das Tool erteilt.
- Node ist als verbunden und für die Rolle `node` gekoppelt aufgeführt.
- Capability existiert für den Befehl, den du aufrufst.
- Berechtigungsstatus ist für das Tool gewährt.
Häufige Log-Signaturen:
- `NODE_BACKGROUND_UNAVAILABLE` → Node-App in den Vordergrund bringen.
- `NODE_BACKGROUND_UNAVAILABLE` → bringe die Node-App in den Vordergrund.
- `*_PERMISSION_REQUIRED` → OS-Berechtigung wurde verweigert/fehlt.
- `SYSTEM_RUN_DENIED: approval required` → Exec-Genehmigung ist ausstehend.
- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl steht nicht auf der Exec-Allowlist.
- `SYSTEM_RUN_DENIED: approval required` → exec-Freigabe steht aus.
- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl steht nicht auf der exec-Allowlist.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/gateway/troubleshooting#node-paired-tool-fails](/de/gateway/troubleshooting#node-paired-tool-fails)
- [/nodes/troubleshooting](/de/nodes/troubleshooting)
@ -298,7 +304,7 @@ flowchart TD
</Accordion>
<Accordion title="Exec fragt plötzlich nach Genehmigung">
<Accordion title="Exec verlangt plötzlich eine Freigabe">
```bash
openclaw config get tools.exec.host
openclaw config get tools.exec.security
@ -306,16 +312,16 @@ flowchart TD
openclaw gateway restart
```
Was hat sich geändert:
Was sich geändert hat:
- Wenn `tools.exec.host` nicht gesetzt ist, lautet der Standard `auto`.
- `host=auto` wird zu `sandbox` aufgelöst, wenn eine Sandbox-Laufzeit aktiv ist, andernfalls zu `gateway`.
- `host=auto` betrifft nur das Routing; das Verhalten „YOLO“ ohne Rückfrage kommt von `security=full` plus `ask=off` auf Gateway/Node.
- Auf `gateway` und `node` lautet der Standard für nicht gesetztes `tools.exec.security` `full`.
- Wenn `tools.exec.host` nicht gesetzt ist, ist der Standardwert `auto`.
- `host=auto` wird zu `sandbox` aufgelöst, wenn eine Sandbox-Laufzeit aktiv ist, sonst zu `gateway`.
- `host=auto` betrifft nur das Routing; das promptfreie „YOLO“-Verhalten ergibt sich aus `security=full` plus `ask=off` auf Gateway/Node.
- Auf `gateway` und `node` ist der Standard für nicht gesetztes `tools.exec.security` `full`.
- Nicht gesetztes `tools.exec.ask` hat standardmäßig den Wert `off`.
- Ergebnis: Wenn Sie Genehmigungen sehen, hat irgendeine hostlokale oder sitzungsbezogene Richtlinie Exec gegenüber den aktuellen Standards verschärft.
- Ergebnis: Wenn du Freigaben siehst, wurde irgendeine host-lokale oder sitzungsspezifische Richtlinie für exec gegenüber den aktuellen Standards verschärft.
Aktuelles Standardverhalten ohne Genehmigungen wiederherstellen:
Aktuelles Standardverhalten ohne Freigabe wiederherstellen:
```bash
openclaw config set tools.exec.host gateway
@ -326,17 +332,17 @@ flowchart TD
Sicherere Alternativen:
- Setzen Sie nur `tools.exec.host=gateway`, wenn Sie lediglich stabiles Host-Routing möchten.
- Verwenden Sie `security=allowlist` mit `ask=on-miss`, wenn Sie Host-Exec möchten, aber bei Allowlist-Fehlschlägen trotzdem prüfen wollen.
- Aktivieren Sie den Sandbox-Modus, wenn `host=auto` wieder zu `sandbox` aufgelöst werden soll.
- Setze nur `tools.exec.host=gateway`, wenn du nur stabiles Host-Routing möchtest.
- Verwende `security=allowlist` mit `ask=on-miss`, wenn du Host-exec möchtest, aber bei Allowlist-Fehlschlägen weiterhin eine Prüfung willst.
- Aktiviere den Sandbox-Modus, wenn du möchtest, dass `host=auto` wieder zu `sandbox` aufgelöst wird.
Häufige Log-Signaturen:
- `Approval required.` → Befehl wartet auf `/approve ...`.
- `SYSTEM_RUN_DENIED: approval required` → Exec-Genehmigung auf dem Node-Host ist ausstehend.
- `exec host=sandbox requires a sandbox runtime for this session` → implizite/explizite Sandbox-Auswahl, aber Sandbox-Modus ist deaktiviert.
- `Approval required.` → der Befehl wartet auf `/approve ...`.
- `SYSTEM_RUN_DENIED: approval required` → die exec-Freigabe für node-host steht aus.
- `exec host=sandbox requires a sandbox runtime for this session` → implizite/explizite Sandbox-Auswahl, aber der Sandbox-Modus ist deaktiviert.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/tools/exec](/de/tools/exec)
- [/tools/exec-approvals](/de/tools/exec-approvals)
@ -362,15 +368,15 @@ flowchart TD
- `unknown command "browser"` oder `unknown command 'browser'` → `plugins.allow` ist gesetzt und enthält `browser` nicht.
- `Failed to start Chrome CDP on port` → Start des lokalen Browsers ist fehlgeschlagen.
- `browser.executablePath not found` → konfigurierter Binärpfad ist falsch.
- `browser.executablePath not found` → der konfigurierte Binärpfad ist falsch.
- `browser.cdpUrl must be http(s) or ws(s)` → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema.
- `browser.cdpUrl has invalid port` → die konfigurierte CDP-URL hat einen ungültigen oder außerhalb des zulässigen Bereichs liegenden Port.
- `No Chrome tabs found for profile="user"` → das Chrome-MCP-Attach-Profil hat keine offenen lokalen Chrome-Tabs.
- `Remote CDP for profile "<name>" is not reachable` → der konfigurierte Remote-CDP-Endpunkt ist von diesem Host nicht erreichbar.
- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → Attach-only-Profil hat kein aktives CDP-Ziel.
- veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline bei Attach-only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile <name>` aus, um die aktive Steuerungssitzung zu schließen und den Emulationsstatus freizugeben, ohne das Gateway neu zu starten.
- `Remote CDP for profile "<name>" is not reachable` → der konfigurierte Remote-CDP-Endpunkt ist von diesem Host aus nicht erreichbar.
- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → das Attach-only-Profil hat kein aktives CDP-Ziel.
- veraltete Overrides für Viewport / Dark Mode / Gebietsschema / Offline-Modus auf Attach-only- oder Remote-CDP-Profilen → führe `openclaw browser stop --browser-profile <name>` aus, um die aktive Steuerungssitzung zu schließen und den Emulationsstatus freizugeben, ohne das Gateway neu zu starten.
Tiefgehende Seiten:
Ausführliche Seiten:
- [/gateway/troubleshooting#browser-tool-fails](/de/gateway/troubleshooting#browser-tool-fails)
- [/tools/browser#missing-browser-command-or-tool](/de/tools/browser#missing-browser-command-or-tool)
@ -384,7 +390,7 @@ flowchart TD
## Verwandt
- [FAQ](/de/help/faq) — häufig gestellte Fragen
- [Gateway Troubleshooting](/de/gateway/troubleshooting) — gatewayspezifische Probleme
- [Doctor](/de/gateway/doctor) — automatisierte Gesundheitsprüfungen und Reparaturen
- [Channel Troubleshooting](/de/channels/troubleshooting) — Probleme mit der Kanalverbindung
- [Automation Troubleshooting](/de/automation/cron-jobs#troubleshooting) — Probleme mit Cron und Heartbeat
- [Gateway-Fehlerbehebung](/de/gateway/troubleshooting) — Gateway-spezifische Probleme
- [Doctor](/de/gateway/doctor) — automatisierte Zustandsprüfungen und Reparaturen
- [Fehlerbehebung für Kanäle](/de/channels/troubleshooting) — Probleme mit der Kanal-Konnektivität
- [Fehlerbehebung für Automatisierung](/de/automation/cron-jobs#troubleshooting) — Probleme mit Cron und Heartbeat

793
docs/de/plugins/architecture-internals.md
View File

File diff suppressed because it is too large Load Diff

505
docs/de/plugins/architecture.md
View File

@ -1,121 +1,125 @@
---
read_when:
- Erstellen oder Debuggen nativer OpenClaw-Plugins
- Verstehen des Plugin-Fähigkeitsmodells oder der Zuständigkeitsgrenzen
- Arbeiten an der Plugin-Lade-Pipeline oder Registry
- Implementieren von Provider-Runtime-Hooks oder Kanal-Plugins
- Native OpenClaw-Plugins erstellen oder debuggen
- Das Fähigkeitsmodell oder die Ownership-Grenzen von Plugins verstehen
- An der Plugin-Lade-Pipeline oder Registry arbeiten
- Runtime-Hooks für Provider oder Channel-Plugins implementieren
sidebarTitle: Internals
summary: 'Plugin-Interna: Fähigkeitsmodell, Zuständigkeit, Verträge, Lade-Pipeline und Runtime-Helper'
summary: 'Plugin-Interna: Fähigkeitsmodell, Ownership, Contracts, Lade-Pipeline und Laufzeithelfer'
title: Plugin-Interna
x-i18n:
generated_at: "2026-04-24T06:48:59Z"
generated_at: "2026-04-24T08:58:14Z"
model: gpt-5.4
provider: openai
source_hash: 344c02f9f0bb19780d262929e665fcaf8093ac08cda30b61af56857368b0b07a
source_hash: d05891966669e599b1aa0165f20f913bfa82c22436356177436fba5d1be31e7b
source_path: plugins/architecture.md
workflow: 15
---
Dies ist die **ausführliche Architekturreferenz** für das Plugin-System von OpenClaw. Für
Dies ist die **umfassende Architekturreferenz** für das OpenClaw-Plugin-System. Für
praktische Anleitungen beginnen Sie mit einer der fokussierten Seiten unten.
<CardGroup cols={2}>
<Card title="Plugins installieren und verwenden" icon="plug" href="/de/tools/plugin">
Leitfaden für Endbenutzer zum Hinzufügen, Aktivieren und Beheben von Problemen mit Plugins.
Endbenutzeranleitung zum Hinzufügen, Aktivieren und Beheben von Problemen mit Plugins.
</Card>
<Card title="Plugins erstellen" icon="rocket" href="/de/plugins/building-plugins">
Tutorial für das erste Plugin mit dem kleinsten funktionsfähigen Manifest.
</Card>
<Card title="Kanal-Plugins" icon="comments" href="/de/plugins/sdk-channel-plugins">
Ein Messaging-Kanal-Plugin erstellen.
<Card title="Channel-Plugins" icon="comments" href="/de/plugins/sdk-channel-plugins">
Erstellen Sie ein Messaging-Channel-Plugin.
</Card>
<Card title="Provider-Plugins" icon="microchip" href="/de/plugins/sdk-provider-plugins">
Ein Modell-Provider-Plugin erstellen.
Erstellen Sie ein Modell-Provider-Plugin.
</Card>
<Card title="SDK-Überblick" icon="book" href="/de/plugins/sdk-overview">
Import-Map und Referenz zur Registrierungs-API.
Referenz für Import-Map und Registrierungs-API.
</Card>
</CardGroup>
## Öffentliches Fähigkeitsmodell
Fähigkeiten sind das öffentliche **native Plugin**-Modell innerhalb von OpenClaw. Jedes
Fähigkeiten sind das öffentliche Modell für **native Plugins** innerhalb von OpenClaw. Jedes
native OpenClaw-Plugin registriert sich für einen oder mehrere Fähigkeitstypen:
| Fähigkeit | Registrierungsmethode | Beispiel-Plugins |
| --------------------- | ------------------------------------------------ | ------------------------------------ |
| Textinferenz | `api.registerProvider(...)` | `openai`, `anthropic` |
| CLI-Inferenz-Backend | `api.registerCliBackend(...)` | `openai`, `anthropic` |
| Sprache | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` |
| Realtime-Transkription | `api.registerRealtimeTranscriptionProvider(...)` | `openai` |
| Realtime-Sprache | `api.registerRealtimeVoiceProvider(...)` | `openai` |
| Medienverständnis | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
| Bilderzeugung | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
| Musikerzeugung | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
| Videoerzeugung | `api.registerVideoGenerationProvider(...)` | `qwen` |
| Web-Fetch | `api.registerWebFetchProvider(...)` | `firecrawl` |
| Web-Suche | `api.registerWebSearchProvider(...)` | `google` |
| Kanal / Messaging | `api.registerChannel(...)` | `msteams`, `matrix` |
| Fähigkeit | Registrierungsmethode | Beispiel-Plugins |
| --------------------- | ----------------------------------------------- | ----------------------------------- |
| Text-Inferenz | `api.registerProvider(...)` | `openai`, `anthropic` |
| CLI-Inferenz-Backend | `api.registerCliBackend(...)` | `openai`, `anthropic` |
| Sprache | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` |
| Echtzeit-Transkription | `api.registerRealtimeTranscriptionProvider(...)` | `openai` |
| Echtzeit-Stimme | `api.registerRealtimeVoiceProvider(...)` | `openai` |
| Medienverständnis | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
| Bildgenerierung | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
| Musikgenerierung | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
| Videogenerierung | `api.registerVideoGenerationProvider(...)` | `qwen` |
| Web-Abruf | `api.registerWebFetchProvider(...)` | `firecrawl` |
| Websuche | `api.registerWebSearchProvider(...)` | `google` |
| Channel / Messaging | `api.registerChannel(...)` | `msteams`, `matrix` |
| Gateway-Erkennung | `api.registerGatewayDiscoveryService(...)` | `bonjour` |
Ein Plugin, das null Fähigkeiten registriert, aber Hooks, Tools oder
Dienste bereitstellt, ist ein **veraltetes hook-only**-Plugin. Dieses Muster wird weiterhin vollständig unterstützt.
Ein Plugin, das null Fähigkeiten registriert, aber Hooks, Tools, Discovery-
Services oder Hintergrunddienste bereitstellt, ist ein **Legacy-hook-only**-Plugin. Dieses Muster
wird weiterhin vollständig unterstützt.
### Haltung zur externen Kompatibilität
Das Fähigkeitsmodell ist im Core gelandet und wird heute von gebündelten/nativen Plugins
verwendet, aber die Kompatibilität externer Plugins braucht weiterhin eine engere Latte als „es ist
verwendet, aber die externe Plugin-Kompatibilität braucht weiterhin eine strengere Messlatte als „es ist
exportiert, also ist es eingefroren“.
| Pluginsituation | Leitlinie |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Bestehende externe Plugins | Hook-basierte Integrationen funktionsfähig halten; das ist die Kompatibilitätsbasis. |
| Neue gebündelte/native Plugins | Explizite Fähigkeitsregistrierung gegenüber anbieterspezifischen Reach-ins oder neuen hook-only-Designs bevorzugen. |
| Externe Plugins mit Fähigkeitsregistrierung | Erlaubt, aber fähigkeitsspezifische Helper-Oberflächen als entwickelnd behandeln, sofern die Doku sie nicht als stabil markiert. |
| Plugin-Situation | Richtlinie |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Bestehende externe Plugins | Hook-basierte Integrationen funktionsfähig halten; das ist die Kompatibilitäts-Baseline. |
| Neue gebündelte/native Plugins | Explizite Fähigkeitsregistrierung gegenüber anbieterspezifischen Zugriffen oder neuen rein hook-basierten Designs bevorzugen. |
| Externe Plugins, die Fähigkeitsregistrierung übernehmen | Erlaubt, aber fähigkeitsspezifische Hilfsoberflächen als weiterentwickelbar behandeln, sofern die Docs sie nicht als stabil markieren. |
Die Fähigkeitsregistrierung ist die beabsichtigte Richtung. Veraltete Hooks bleiben
während des Übergangs der sicherste No-Breakage-Pfad für externe Plugins. Exportierte
Helper-Subpaths sind nicht alle gleich — bevorzugen Sie schmale dokumentierte Verträge gegenüber
zufälligen Helper-Exporten.
Die Fähigkeitsregistrierung ist die beabsichtigte Richtung. Legacy-Hooks bleiben während des
Übergangs der sicherste Weg ohne Breaking Changes für externe Plugins. Exportierte
Hilfs-Subpaths sind nicht alle gleich — bevorzugen Sie enge dokumentierte Contracts statt
zufälliger Hilfsexporte.
### Plugin-Shapes
### Plugin-Formen
OpenClaw klassifiziert jedes geladene Plugin anhand seines tatsächlichen
Registrierungsverhaltens (nicht nur anhand statischer Metadaten) in eine Shape:
Registrierungsverhaltens in eine Form (nicht nur anhand statischer Metadaten):
- **plain-capability**: registriert genau einen Fähigkeitstyp (zum Beispiel ein
reines Provider-Plugin wie `mistral`).
nur-Provider-Plugin wie `mistral`).
- **hybrid-capability**: registriert mehrere Fähigkeitstypen (zum Beispiel
verwaltet `openai` Textinferenz, Sprache, Medienverständnis und Bilderzeugung).
besitzt `openai` Text-Inferenz, Sprache, Medienverständnis und Bild-
generierung).
- **hook-only**: registriert nur Hooks (typisiert oder benutzerdefiniert), keine Fähigkeiten,
Tools, Befehle oder Dienste.
- **non-capability**: registriert Tools, Befehle, Dienste oder Routen, aber keine
Fähigkeiten.
Verwenden Sie `openclaw plugins inspect <id>`, um die Shape und Aufschlüsselung der Fähigkeiten eines Plugins zu sehen. Siehe [CLI-Referenz](/de/cli/plugins#inspect) für Details.
Verwenden Sie `openclaw plugins inspect <id>`, um die Form und die Fähigkeitsaufschlüsselung
eines Plugins zu sehen. Siehe [CLI-Referenz](/de/cli/plugins#inspect) für Details.
### Veraltete Hooks
### Legacy-Hooks
Der Hook `before_agent_start` bleibt als Kompatibilitätspfad für
hook-only-Plugins unterstützt. Veraltete reale Plugins hängen weiterhin davon ab.
rein hook-basierte Plugins unterstützt. Legacy-Plugins aus der Praxis sind weiterhin davon abhängig.
Richtung:
- funktionsfähig halten
- als veraltet dokumentieren
- `before_model_resolve` für Arbeit an Modell-/Provider-Overrides bevorzugen
- `before_prompt_build` für Prompt-Mutation bevorzugen
- erst entfernen, wenn die reale Nutzung zurückgeht und Fixture-Abdeckung die Sicherheit der Migration belegt
- als Legacy dokumentieren
- `before_model_resolve` für Arbeit an Modell-/Provider-Überschreibungen bevorzugen
- `before_prompt_build` für Änderungen an Prompts bevorzugen
- erst entfernen, nachdem die reale Nutzung sinkt und Fixture-Abdeckung die Migrationssicherheit belegt
### Kompatibilitätssignale
Wenn Sie `openclaw doctor` oder `openclaw plugins inspect <id>` ausführen, sehen Sie möglicherweise
eine dieser Bezeichnungen:
eines dieser Labels:
| Signal | Bedeutung |
| -------------------------- | ----------------------------------------------------------- |
| **config valid** | Konfiguration wird korrekt geparst und Plugins werden aufgelöst |
| **compatibility advisory** | Plugin verwendet ein unterstütztes, aber älteres Muster (z. B. `hook-only`) |
| **legacy warning** | Plugin verwendet `before_agent_start`, was veraltet ist |
| **legacy warning** | Plugin verwendet `before_agent_start`, das veraltet ist |
| **hard error** | Konfiguration ist ungültig oder Plugin konnte nicht geladen werden |
Weder `hook-only` noch `before_agent_start` werden Ihr Plugin heute kaputt machen:
@ -127,87 +131,88 @@ Signale erscheinen auch in `openclaw status --all` und `openclaw plugins doctor`
Das Plugin-System von OpenClaw hat vier Schichten:
1. **Manifest + Discovery**
OpenClaw findet Kandidaten-Plugins aus konfigurierten Pfaden, Workspace-Roots,
OpenClaw findet Kandidaten-Plugins in konfigurierten Pfaden, Workspace-Roots,
globalen Plugin-Roots und gebündelten Plugins. Discovery liest zuerst native
`openclaw.plugin.json`-Manifeste sowie unterstützte Bundle-Manifeste.
2. **Aktivierung + Validierung**
Der Core entscheidet, ob ein gefundenes Plugin aktiviert, deaktiviert, blockiert oder
für einen exklusiven Slot wie Memory ausgewählt ist.
3. **Laden zur Laufzeit**
Native OpenClaw-Plugins werden im Prozess über jiti geladen und registrieren
für einen exklusiven Slot wie Speicher ausgewählt ist.
3. **Laufzeitladen**
Native OpenClaw-Plugins werden per jiti im Prozess geladen und registrieren
Fähigkeiten in einer zentralen Registry. Kompatible Bundles werden in
Registry-Einträge normalisiert, ohne Runtime-Code zu importieren.
Registry-Einträge normalisiert, ohne Laufzeitcode zu importieren.
4. **Nutzung der Oberflächen**
Der Rest von OpenClaw liest die Registry, um Tools, Kanäle, Provider-
Der Rest von OpenClaw liest die Registry, um Tools, Channels, Provider-
Setup, Hooks, HTTP-Routen, CLI-Befehle und Dienste bereitzustellen.
Speziell für Plugin-CLI ist die Discovery von Root-Befehlen in zwei Phasen aufgeteilt:
Speziell für die Plugin-CLI ist die Discovery von Root-Befehlen in zwei Phasen aufgeteilt:
- Parse-Time-Metadaten kommen aus `registerCli(..., { descriptors: [...] })`
- das eigentliche Plugin-CLI-Modul kann lazy bleiben und sich erst beim ersten Aufruf registrieren
- Parse-Time-Metadaten stammen aus `registerCli(..., { descriptors: [...] })`
- das echte Plugin-CLI-Modul kann lazy bleiben und sich beim ersten Aufruf registrieren
Dadurch bleibt pluginbezogener CLI-Code im Plugin, während OpenClaw
Root-Befehlsnamen bereits vor dem Parsen reservieren kann.
Dadurch bleibt Plugin-eigener CLI-Code innerhalb des Plugins, während OpenClaw trotzdem
Root-Befehlsnamen vor dem Parsen reservieren kann.
Die wichtige Designgrenze:
- Discovery + Konfigurationsvalidierung sollten aus **Manifest-/Schema-Metadaten**
- Discovery + Konfigurationsvalidierung sollten anhand von **Manifest-/Schema-Metadaten**
funktionieren, ohne Plugin-Code auszuführen
- natives Laufzeitverhalten kommt aus dem Pfad `register(api)` des Plugin-Moduls
Diese Trennung ermöglicht es OpenClaw, Konfiguration zu validieren, fehlende/deaktivierte Plugins zu erklären und
UI-/Schema-Hinweise zu erstellen, bevor die vollständige Runtime aktiv ist.
Diese Trennung ermöglicht es OpenClaw, Konfigurationen zu validieren, fehlende/deaktivierte Plugins
zu erklären und UI-/Schema-Hinweise zu erstellen, bevor die vollständige Laufzeit aktiv ist.
### Aktivierungsplanung
Die Aktivierungsplanung ist Teil der Steuerungsebene. Aufrufer können fragen, welche Plugins
für einen konkreten Befehl, Provider, Kanal, eine Route, ein Agent-Harness oder eine
Fähigkeit relevant sind, bevor breitere Runtime-Registries geladen werden.
Die Aktivierungsplanung ist Teil der Control Plane. Aufrufer können fragen, welche Plugins
für einen konkreten Befehl, Provider, Channel, eine Route, ein Agent-Harness oder eine
Fähigkeit relevant sind, bevor breitere Laufzeit-Registries geladen werden.
Der Planner hält das aktuelle Manifest-Verhalten kompatibel:
Der Planer hält das aktuelle Manifest-Verhalten kompatibel:
- `activation.*`-Felder sind explizite Planner-Hinweise
- `activation.*`-Felder sind explizite Planer-Hinweise
- `providers`, `channels`, `commandAliases`, `setup.providers`,
`contracts.tools` und Hooks bleiben als Fallback für Manifest-Zuständigkeit erhalten
- die reine IDs-API des Planners bleibt für bestehende Aufrufer verfügbar
- die Plan-API meldet Reason-Labels, sodass Diagnosen explizite
Hinweise von Zuständigkeits-Fallback unterscheiden können
`contracts.tools` und Hooks bleiben Fallbacks für Manifest-Ownership
- die ids-only-Planer-API bleibt für bestehende Aufrufer verfügbar
- die Plan-API meldet Begründungslabels, damit die Diagnose explizite
Hinweise von Ownership-Fallback unterscheiden kann
Behandeln Sie `activation` nicht als Lifecycle-Hook oder als Ersatz für
`register(...)`. Es sind Metadaten, die zum Eingrenzen des Ladens verwendet werden. Bevorzugen Sie Zuständigkeitsfelder,
`register(...)`. Es handelt sich um Metadaten, die zum Einschränken des Ladens verwendet werden. Bevorzugen Sie Ownership-Felder,
wenn sie die Beziehung bereits beschreiben; verwenden Sie `activation` nur für zusätzliche
Planner-Hinweise.
Planer-Hinweise.
### Kanal-Plugins und das gemeinsame Message-Tool
### Channel-Plugins und das gemeinsame Nachrichtentool
Kanal-Plugins müssen für normale Chat-Aktionen kein separates Send/Edit/React-Tool registrieren.
OpenClaw behält ein gemeinsames `message`-Tool im Core, und
Kanal-Plugins verwalten die kanalspezifische Discovery und Ausführung dahinter.
Channel-Plugins müssen für normale Chat-Aktionen kein separates Send/Edit/React-Tool
registrieren. OpenClaw behält ein gemeinsames `message`-Tool im Core, und
Channel-Plugins besitzen die channelspezifische Discovery und Ausführung dahinter.
Die aktuelle Grenze ist:
- der Core verwaltet den gemeinsamen Tool-Host `message`, Prompt-Wiring, Sitzungs-/Thread-
Bookkeeping und Execution-Dispatch
- Kanal-Plugins verwalten scoped Action Discovery, Capability Discovery und alle
kanalspezifischen Schemafragmente
- Kanal-Plugins verwalten provider-spezifische Konversationsgrammatik für Sitzungen, also
wie Konversations-IDs Thread-IDs kodieren oder von Parent-Konversationen erben
- Kanal-Plugins führen die finale Aktion über ihren Action-Adapter aus
- der Core besitzt den gemeinsamen `message`-Tool-Host, Prompt-Verkabelung, Session-/Thread-
Buchhaltung und Ausführungs-Dispatch
- Channel-Plugins besitzen die Discovery für bereichsbezogene Aktionen, Fähigkeits-Discovery
und alle channelspezifischen Schemafragmente
- Channel-Plugins besitzen providerspezifische Sitzungs-Konversationsgrammatik, also etwa
wie Konversations-IDs Thread-IDs kodieren oder von Elternkonversationen erben
- Channel-Plugins führen die endgültige Aktion über ihren Action-Adapter aus
Für Kanal-Plugins ist die SDK-Oberfläche
Für Channel-Plugins ist die SDK-Oberfläche
`ChannelMessageActionAdapter.describeMessageTool(...)`. Dieser einheitliche Discovery-
Aufruf erlaubt einem Plugin, sichtbare Aktionen, Fähigkeiten und Schema-
Beiträge zusammen zurückzugeben, sodass diese Teile nicht auseinanderdriften.
Aufruf erlaubt es einem Plugin, seine sichtbaren Aktionen, Fähigkeiten und Schema-
Beiträge zusammen zurückzugeben, damit diese Teile nicht auseinanderdriften.
Wenn ein kanalspezifischer Parameter des Message-Tools eine Medienquelle wie einen
lokalen Pfad oder eine Remote-Medien-URL trägt, sollte das Plugin außerdem
`mediaSourceParams` aus `describeMessageTool(...)` zurückgeben. Der Core verwendet diese explizite
Liste, um Sandbox-Pfadnormalisierung und Hinweise für ausgehenden Medienzugriff anzuwenden,
ohne pluginbezogene Parameternamen hart zu codieren.
Bevorzugen Sie dort aktionsbezogene Maps, nicht eine kanalweite flache Liste, sodass ein
profilbezogener Medienparameter nicht bei nicht verwandten Aktionen wie `send` normalisiert wird.
Wenn ein channelspezifischer message-tool-Parameter eine Medienquelle wie einen
lokalen Pfad oder eine entfernte Medien-URL enthält, sollte das Plugin außerdem
`mediaSourceParams` von `describeMessageTool(...)` zurückgeben. Der Core verwendet diese explizite
Liste, um Sandbox-Pfadnormalisierung und Hinweise für ausgehenden Medienzugriff
anzuwenden, ohne Plugin-eigene Parameternamen hart zu codieren.
Bevorzugen Sie dort aktionsbezogene Maps statt einer kanalweiten flachen Liste, damit ein
nur profilbezogener Medienparameter nicht bei nicht zusammenhängenden Aktionen wie
`send` normalisiert wird.
Der Core übergibt Runtime-Scope in diesen Discovery-Schritt. Wichtige Felder sind:
Der Core übergibt den Laufzeit-Scope an diesen Discovery-Schritt. Wichtige Felder sind unter anderem:
- `accountId`
- `currentChannelId`
@ -218,121 +223,123 @@ Der Core übergibt Runtime-Scope in diesen Discovery-Schritt. Wichtige Felder si
- `agentId`
- vertrauenswürdige eingehende `requesterSenderId`
Das ist für kontextsensitive Plugins wichtig. Ein Kanal kann
Message-Aktionen anhand des aktiven Kontos, des aktuellen Raums/Threads/der aktuellen Nachricht oder der
vertrauenswürdigen Identität des Requesters ein- oder ausblenden, ohne kanalspezifische Zweige im
gemeinsamen Core-Tool `message` hart zu codieren.
Das ist für kontextsensitive Plugins wichtig. Ein Channel kann
Nachrichtenaktionen abhängig vom aktiven Konto, dem aktuellen Raum/Thread/Nachricht oder der
vertrauenswürdigen Identität des Anfragenden ausblenden oder bereitstellen, ohne
channelspezifische Verzweigungen im Core-Tool `message` hart zu codieren.
Deshalb sind Änderungen am Routing des Embedded-Runners weiterhin Plugin-Arbeit: Der Runner ist
dafür verantwortlich, die aktuelle Chat-/Sitzungsidentität in die Plugin-
Discovery-Grenze weiterzuleiten, sodass das gemeinsame Tool `message` die richtige pluginbezogene
Oberfläche für den aktuellen Turn freilegt.
Darum sind Routing-Änderungen im eingebetteten Runner weiterhin Plugin-Arbeit: Der Runner ist
dafür verantwortlich, die aktuelle Chat-/Session-Identität an die Plugin-
Discovery-Grenze weiterzuleiten, damit das gemeinsame Tool `message` die richtige, Channel-eigene
Oberfläche für den aktuellen Turn bereitstellt.
Für kanalbezogene Execution-Helper sollten gebündelte Plugins die Execution-
Runtime in ihren eigenen Erweiterungsmodulen behalten. Der Core verwaltet die Discord-,
Slack-, Telegram- oder WhatsApp-Message-Action-Runtimes unter `src/agents/tools` nicht mehr.
Bei Channel-eigenen Ausführungshelfern sollten gebündelte Plugins die Ausführungs-
Laufzeit innerhalb ihrer eigenen Erweiterungsmodule halten. Der Core besitzt nicht länger die Discord-,
Slack-, Telegram- oder WhatsApp-Nachrichtenaktions-Laufzeiten unter `src/agents/tools`.
Wir veröffentlichen keine separaten Subpaths `plugin-sdk/*-action-runtime`, und gebündelte
Plugins sollten ihren eigenen lokalen Runtime-Code direkt aus ihren
Plugins sollten ihren eigenen lokalen Laufzeitcode direkt aus ihren
erweiterungseigenen Modulen importieren.
Dieselbe Grenze gilt allgemein für providerbenannte SDK-Seams: Der Core sollte
keine kanalspezifischen Convenience-Barrels für Slack, Discord, Signal,
WhatsApp oder ähnliche Erweiterungen importieren. Wenn der Core ein Verhalten benötigt, soll er entweder
das eigene Barrel `api.ts` / `runtime-api.ts` des gebündelten Plugins verwenden oder den Bedarf
in eine schmale generische Fähigkeit im gemeinsamen SDK überführen.
keine channelspezifischen Convenience-Barrels für Slack, Discord, Signal,
WhatsApp oder ähnliche Erweiterungen importieren. Wenn der Core ein Verhalten benötigt,
sollte er entweder das eigene Barrel `api.ts` / `runtime-api.ts` des gebündelten Plugins
verwenden oder den Bedarf in eine schmale generische Fähigkeit im gemeinsam genutzten SDK überführen.
Speziell für Umfragen gibt es zwei Ausführungspfade:
- `outbound.sendPoll` ist die gemeinsame Basis für Kanäle, die zum allgemeinen
- `outbound.sendPoll` ist die gemeinsame Basis für Channels, die zum gemeinsamen
Umfragemodell passen
- `actions.handleAction("poll")` ist der bevorzugte Pfad für kanalspezifische
- `actions.handleAction("poll")` ist der bevorzugte Pfad für channelspezifische
Umfragesemantik oder zusätzliche Umfrageparameter
Der Core verzögert jetzt das gemeinsame Poll-Parsing, bis der pluginbezogene Poll-Dispatch die
Aktion ablehnt, sodass pluginbezogene Poll-Handler kanalspezifische Poll-Felder akzeptieren können,
ohne zuvor vom generischen Poll-Parser blockiert zu werden.
Der Core verschiebt das gemeinsame Parsing von Umfragen jetzt so lange, bis der
plugin-eigene Dispatch für Umfragen die Aktion ablehnt, damit plugin-eigene
Umfrage-Handler channelspezifische Umfragefelder akzeptieren können, ohne zuerst
vom generischen Umfrage-Parser blockiert zu werden.
Siehe [Plugin-Architektur-Interna](/de/plugins/architecture-internals) für die vollständige Startsequenz.
Siehe [Plugin architecture internals](/de/plugins/architecture-internals) für die vollständige Startsequenz.
## Zuständigkeitsmodell für Fähigkeiten
## Modell für Capability-Ownership
OpenClaw behandelt ein natives Plugin als Zuständigkeitsgrenze für ein **Unternehmen** oder ein
OpenClaw behandelt ein natives Plugin als Ownership-Grenze für ein **Unternehmen** oder ein
**Feature**, nicht als Sammelsurium nicht zusammenhängender Integrationen.
Das bedeutet:
- ein Unternehmens-Plugin sollte normalerweise alle OpenClaw-bezogenen
Oberflächen dieses Unternehmens verwalten
- ein Feature-Plugin sollte normalerweise die vollständige Feature-Oberfläche verwalten, die es einführt
- Kanäle sollten gemeinsame Core-Fähigkeiten nutzen, statt Provider-Verhalten
ad hoc neu zu implementieren
Oberflächen dieses Unternehmens besitzen
- ein Feature-Plugin sollte normalerweise die vollständige Feature-Oberfläche
besitzen, die es einführt
- Channels sollten gemeinsame Core-Capabilities nutzen, statt
Provider-Verhalten ad hoc neu zu implementieren
<Accordion title="Beispiele für Zuständigkeitsmuster in gebündelten Plugins">
- **Multi-Capability eines Anbieters**: `openai` verwaltet Textinferenz, Sprache, Realtime-
Sprache, Medienverständnis und Bilderzeugung. `google` verwaltet Text-
Inferenz plus Medienverständnis, Bilderzeugung und Websuche.
`qwen` verwaltet Textinferenz plus Medienverständnis und Videoerzeugung.
- **Single-Capability eines Anbieters**: `elevenlabs` und `microsoft` verwalten Sprache;
`firecrawl` verwaltet Web-Fetch; `minimax` / `mistral` / `moonshot` / `zai` verwalten
<Accordion title="Beispielhafte Ownership-Muster über gebündelte Plugins hinweg">
- **Anbieter mit mehreren Capabilities**: `openai` besitzt Text-Inferenz, Sprache, Echtzeit-
Stimme, Medienverständnis und Bildgenerierung. `google` besitzt Text-
Inferenz plus Medienverständnis, Bildgenerierung und Websuche.
`qwen` besitzt Text-Inferenz plus Medienverständnis und Videogenerierung.
- **Anbieter mit einzelner Capability**: `elevenlabs` und `microsoft` besitzen Sprache;
`firecrawl` besitzt Web-Abruf; `minimax` / `mistral` / `moonshot` / `zai` besitzen
Backends für Medienverständnis.
- **Feature-Plugin**: `voice-call` verwaltet Anruftransport, Tools, CLI, Routen
und Twilio-Medienstream-Bridging, nutzt aber gemeinsame Fähigkeiten für Sprache, Realtime-
Transkription und Realtime-Sprache, statt Provider-Plugins direkt zu importieren.
- **Feature-Plugin**: `voice-call` besitzt Anruftransport, Tools, CLI, Routen
und Twilio-Medienstrom-Bridge, nutzt aber gemeinsame Capabilities für Sprache, Echtzeit-
Transkription und Echtzeit-Stimme, statt Anbieter-Plugins direkt zu importieren.
</Accordion>
Der beabsichtigte Endzustand ist:
Der angestrebte Endzustand ist:
- OpenAI lebt in einem Plugin, auch wenn es Textmodelle, Sprache, Bilder und
künftig Video umfasst
- OpenAI lebt in einem Plugin, selbst wenn es Textmodelle, Sprache, Bilder und
zukünftiges Video umfasst
- ein anderer Anbieter kann dasselbe für seinen eigenen Oberflächenbereich tun
- Kanäle ist es egal, welches Anbieter-Plugin den Provider verwaltet; sie nutzen den
gemeinsamen Fähigkeitsvertrag, den der Core bereitstellt
- Channels ist es egal, welches Anbieter-Plugin den Provider besitzt; sie nutzen den
gemeinsamen Capability-Contract, den der Core bereitstellt
Das ist die zentrale Unterscheidung:
Das ist die entscheidende Unterscheidung:
- **plugin** = Zuständigkeitsgrenze
- **capability** = Core-Vertrag, den mehrere Plugins implementieren oder nutzen können
- **Plugin** = Ownership-Grenze
- **Capability** = Core-Contract, den mehrere Plugins implementieren oder nutzen können
Wenn OpenClaw also einen neuen Bereich wie Video hinzufügt, lautet die erste Frage nicht
„welcher Provider sollte die Videoverarbeitung hart codieren?“ Die erste Frage lautet:
„wie sieht der zentrale Video-Fähigkeitsvertrag aus?“ Sobald dieser Vertrag existiert, können Anbieter-Plugins
sich dafür registrieren und Kanal-/Feature-Plugins ihn nutzen.
Wenn OpenClaw also eine neue Domäne wie Video hinzufügt, lautet die erste Frage nicht
„welcher Provider sollte Videoverarbeitung hart codieren?“ Die erste Frage lautet
„was ist der Core-Capability-Contract für Video?“ Sobald dieser Contract existiert,
können Anbieter-Plugins sich dafür registrieren und Channel-/Feature-Plugins ihn nutzen.
Wenn die Fähigkeit noch nicht existiert, ist normalerweise der richtige Schritt:
Wenn die Capability noch nicht existiert, ist der richtige Schritt normalerweise:
1. die fehlende Fähigkeit im Core definieren
2. sie typisiert über die Plugin-API/Runtime bereitstellen
3. Kanäle/Features gegen diese Fähigkeit verdrahten
1. die fehlende Capability im Core definieren
2. sie typisiert über die Plugin-API/Laufzeit bereitstellen
3. Channels/Features gegen diese Capability verdrahten
4. Anbieter-Plugins Implementierungen registrieren lassen
Dadurch bleiben Zuständigkeiten explizit, während Core-Verhalten vermieden wird, das von einem
einzigen Anbieter oder einem einmaligen pluginspezifischen Codepfad abhängt.
Dadurch bleibt Ownership explizit, während Core-Verhalten vermieden wird, das von einem
einzelnen Anbieter oder einem einmaligen pluginspezifischen Codepfad abhängt.
### Schichtung von Fähigkeiten
### Capability-Schichtung
Verwenden Sie dieses mentale Modell, wenn Sie entscheiden, wohin Code gehört:
Verwenden Sie dieses mentale Modell, wenn Sie entscheiden, wo Code hingehört:
- **Core-Capability-Layer**: gemeinsame Orchestrierung, Richtlinien, Fallback,
Konfigurations-Merge-Regeln, Zustellungssemantik und typisierte Verträge
- **Vendor-Plugin-Layer**: anbieterspezifische APIs, Authentifizierung, Modellkataloge, Sprach-
Synthese, Bilderzeugung, zukünftige Video-Backends, Nutzungsendpunkte
- **Kanal-/Feature-Plugin-Layer**: Slack-/Discord-/voice-call-/etc.-Integration,
die Core-Fähigkeiten nutzt und sie an einer Oberfläche bereitstellt
- **Core-Capability-Schicht**: gemeinsame Orchestrierung, Richtlinien, Fallback,
Regeln zum Zusammenführen von Konfigurationen, Zustellsemantik und typisierte Contracts
- **Anbieter-Plugin-Schicht**: anbieterspezifische APIs, Auth, Modellkataloge, Sprache-
synthese, Bildgenerierung, zukünftige Video-Backends, Nutzungsendpunkte
- **Channel-/Feature-Plugin-Schicht**: Integration von Slack/Discord/voice-call/usw.,
die Core-Capabilities nutzt und sie auf einer Oberfläche darstellt
Zum Beispiel folgt TTS diesem Muster:
TTS folgt zum Beispiel dieser Form:
- der Core verwaltet Antwortzeit-TTS-Richtlinien, Fallback-Reihenfolge, Präferenzen und Kanalzustellung
- `openai`, `elevenlabs` und `microsoft` verwalten die Implementierungen der Synthese
- `voice-call` nutzt den Runtime-Helper für Telephony-TTS
- der Core besitzt TTS-Richtlinien zur Antwortzeit, Fallback-Reihenfolge, Präferenzen und Channel-Zustellung
- `openai`, `elevenlabs` und `microsoft` besitzen Synthese-Implementierungen
- `voice-call` nutzt den Laufzeithelfer für Telephony-TTS
Dasselbe Muster sollte für zukünftige Fähigkeiten bevorzugt werden.
Dasselbe Muster sollte für zukünftige Capabilities bevorzugt werden.
### Beispiel für ein Unternehmens-Plugin mit mehreren Fähigkeiten
### Beispiel für ein Unternehmens-Plugin mit mehreren Capabilities
Ein Unternehmens-Plugin sollte sich von außen kohärent anfühlen. Wenn OpenClaw gemeinsame
Verträge für Modelle, Sprache, Realtime-Transkription, Realtime-Sprache, Medien-
Verständnis, Bilderzeugung, Videoerzeugung, Web-Fetch und Websuche hat,
kann ein Anbieter all seine Oberflächen an einer Stelle verwalten:
Contracts für Modelle, Sprache, Echtzeit-Transkription, Echtzeit-Stimme, Medienverständnis,
Bildgenerierung, Videogenerierung, Web-Abruf und Websuche hat,
kann ein Anbieter alle seine Oberflächen an einer Stelle besitzen:
```ts
import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
@ -347,12 +354,12 @@ const plugin: OpenClawPluginDefinition = {
register(api) {
api.registerProvider({
id: "exampleai",
// auth/model catalog/runtime hooks
// Auth-/Modellkatalog-/Laufzeit-Hooks
});
api.registerSpeechProvider({
id: "exampleai",
// vendor speech config — implement the SpeechProviderPlugin interface directly
// Anbieter-Sprachkonfiguration — das Interface SpeechProviderPlugin direkt implementieren
});
api.registerMediaUnderstandingProvider({
@ -377,7 +384,7 @@ const plugin: OpenClawPluginDefinition = {
api.registerWebSearchProvider(
createPluginBackedWebSearchProvider({
id: "exampleai-search",
// credential + fetch logic
// Credential- + Fetch-Logik
}),
);
},
@ -386,83 +393,85 @@ const plugin: OpenClawPluginDefinition = {
export default plugin;
```
Wichtig ist nicht die genaue Benennung der Helper. Wichtig ist die Form:
Wichtig sind nicht die genauen Namen der Helfer. Entscheidend ist die Form:
- ein Plugin verwaltet die Anbieteroberfläche
- der Core verwaltet weiterhin die Fähigkeitsverträge
- Kanäle und Feature-Plugins nutzen `api.runtime.*`-Helper, nicht Anbietercode
- Vertragstests können sicherstellen, dass das Plugin die Fähigkeiten registriert, für die es Zuständigkeit beansprucht
- ein Plugin besitzt die Anbieteroberfläche
- der Core besitzt weiterhin die Capability-Contracts
- Channels und Feature-Plugins nutzen Helfer aus `api.runtime.*`, nicht Anbietercode
- Contract-Tests können prüfen, dass das Plugin die Capabilities registriert, die es
vorgibt zu besitzen
### Beispiel einer Fähigkeit: Videoverständnis
### Beispiel für eine Capability: Videoverständnis
OpenClaw behandelt Bild-/Audio-/Videoverständnis bereits als eine gemeinsame
Fähigkeit. Dasselbe Zuständigkeitsmodell gilt dort:
Capability. Dasselbe Ownership-Modell gilt auch dort:
1. der Core definiert den Vertrag für Medienverständnis
2. Anbieter-Plugins registrieren `describeImage`, `transcribeAudio` und
`describeVideo`, soweit zutreffend
3. Kanal- und Feature-Plugins nutzen das gemeinsame Core-Verhalten, statt
direkt Anbieter-Code zu verdrahten
1. der Core definiert den Contract für Medienverständnis
2. Anbieter-Plugins registrieren je nach Anwendbarkeit `describeImage`, `transcribeAudio` und
`describeVideo`
3. Channel- und Feature-Plugins nutzen das gemeinsame Core-Verhalten, statt
direkt an Anbietercode zu verdrahten
Dadurch wird vermieden, dass Videoannahmen eines einzelnen Providers im Core fest eingebrannt werden. Das Plugin verwaltet
die Anbieteroberfläche; der Core verwaltet den Fähigkeitsvertrag und das Fallback-Verhalten.
Dadurch werden die Video-Annahmen eines einzelnen Providers nicht in den Core eingebrannt. Das Plugin besitzt
die Anbieteroberfläche; der Core besitzt den Capability-Contract und das Fallback-Verhalten.
Die Videoerzeugung verwendet bereits dieselbe Reihenfolge: Der Core verwaltet den typisierten
Fähigkeitsvertrag und den Runtime-Helper, und Anbieter-Plugins registrieren
Implementierungen von `api.registerVideoGenerationProvider(...)` dagegen.
Videogenerierung verwendet bereits dieselbe Abfolge: Der Core besitzt den typisierten
Capability-Contract und den Laufzeithelfer, und Anbieter-Plugins registrieren
Implementierungen von `api.registerVideoGenerationProvider(...)` dafür.
Benötigen Sie eine konkrete Rollout-Checkliste? Siehe
Benötigen Sie eine konkrete Checkliste für die Einführung? Siehe
[Capability Cookbook](/de/plugins/architecture).
## Verträge und Durchsetzung
## Contracts und Durchsetzung
Die Oberfläche der Plugin-API ist absichtlich typisiert und zentralisiert in
`OpenClawPluginApi`. Dieser Vertrag definiert die unterstützten Registrierungspunkte und
die Runtime-Helper, auf die sich ein Plugin verlassen darf.
Die Plugin-API-Oberfläche ist absichtlich typisiert und in
`OpenClawPluginApi` zentralisiert. Dieser Contract definiert die unterstützten Registrierungspunkte und
die Laufzeithelfer, auf die sich ein Plugin verlassen darf.
Warum das wichtig ist:
- Plugin-Autoren erhalten einen stabilen internen Standard
- der Core kann doppelte Zuständigkeit ablehnen, etwa wenn zwei Plugins dieselbe
- der Core kann doppelte Ownership ablehnen, etwa wenn zwei Plugins dieselbe
Provider-ID registrieren
- der Start kann umsetzbare Diagnosen für fehlerhafte Registrierung liefern
- Vertragstests können die Zuständigkeit gebündelter Plugins erzwingen und stilles Driften verhindern
- beim Start können umsetzbare Diagnosen für fehlerhafte Registrierungen ausgegeben werden
- Contract-Tests können Ownership gebündelter Plugins durchsetzen und stilles Driften verhindern
Es gibt zwei Ebenen der Durchsetzung:
1. **Durchsetzung der Runtime-Registrierung**
Die Plugin-Registry validiert Registrierungen beim Laden der Plugins. Beispiele:
doppelte Provider-IDs, doppelte Sprach-Provider-IDs und fehlerhafte
1. **Durchsetzung bei der Laufzeitregistrierung**
Die Plugin-Registry validiert Registrierungen beim Laden von Plugins. Beispiele:
doppelte Provider-IDs, doppelte Speech-Provider-IDs und fehlerhafte
Registrierungen erzeugen Plugin-Diagnosen statt undefiniertem Verhalten.
2. **Vertragstests**
Gebündelte Plugins werden bei Testläufen in Vertrags-Registries erfasst, sodass
OpenClaw Zuständigkeit explizit prüfen kann. Heute wird dies für Modell-
Provider, Sprach-Provider, Web-Search-Provider und die Zuständigkeit gebündelter Registrierungen verwendet.
2. **Contract-Tests**
Gebündelte Plugins werden während Testläufen in Contract-Registries erfasst, damit
OpenClaw Ownership explizit prüfen kann. Heute wird das für Modell-
Provider, Speech-Provider, Websuch-Provider und Registrierungs-Ownership gebündelter Plugins verwendet.
Der praktische Effekt ist, dass OpenClaw im Voraus weiß, welches Plugin welche
Oberfläche verwaltet. Dadurch können Core und Kanäle nahtlos zusammenspielen, weil Zuständigkeit
deklariert, typisiert und testbar statt implizit ist.
Oberfläche besitzt. Dadurch können der Core und Channels nahtlos zusammenspielen, weil Ownership
deklariert, typisiert und testbar ist statt implizit.
### Was in einen Vertrag gehört
### Was in einen Contract gehört
Gute Plugin-Verträge sind:
Gute Plugin-Contracts sind:
- typisiert
- klein
- fähigkeitsspezifisch
- im Besitz des Cores
- capability-spezifisch
- im Besitz des Core
- von mehreren Plugins wiederverwendbar
- von Kanälen/Features ohne Anbieterwissen nutzbar
- von Channels/Features ohne Anbieterwissen nutzbar
Schlechte Plugin-Verträge sind:
Schlechte Plugin-Contracts sind:
- anbieterspezifische Richtlinien, die im Core versteckt sind
- einmalige Escape-Hatches für Plugins, die die Registry umgehen
- Kanalcode, der direkt in eine Anbieterimplementierung greift
- ad hoc Runtime-Objekte, die nicht Teil von `OpenClawPluginApi` oder
- anbieterspezifische Richtlinien, die im Core verborgen sind
- einmalige pluginspezifische Escape-Hatches, die die Registry umgehen
- Channel-Code, der direkt in eine Anbieterimplementierung greift
- ad hoc Laufzeitobjekte, die nicht Teil von `OpenClawPluginApi` oder
`api.runtime` sind
Wenn Sie unsicher sind, erhöhen Sie die Abstraktionsebene: Definieren Sie zuerst die Fähigkeit und lassen Sie dann Plugins sich daran anschließen.
Im Zweifel: Heben Sie die Abstraktionsebene an. Definieren Sie zuerst die Capability und
lassen Sie dann Plugins daran andocken.
## Ausführungsmodell
@ -470,22 +479,22 @@ Native OpenClaw-Plugins laufen **im Prozess** mit dem Gateway. Sie sind nicht
sandboxed. Ein geladenes natives Plugin hat dieselbe Vertrauensgrenze auf Prozessebene wie
Core-Code.
Implikationen:
Folgen:
- ein natives Plugin kann Tools, Netzwerk-Handler, Hooks und Dienste registrieren
- ein Fehler in einem nativen Plugin kann das Gateway abstürzen lassen oder destabilisieren
- ein bösartiges natives Plugin entspricht willkürlicher Codeausführung innerhalb des
OpenClaw-Prozesses
- ein Fehler in einem nativen Plugin kann das Gateway zum Absturz bringen oder destabilisieren
- ein bösartiges natives Plugin ist gleichbedeutend mit beliebiger Codeausführung innerhalb
des OpenClaw-Prozesses
Kompatible Bundles sind standardmäßig sicherer, weil OpenClaw sie derzeit
als Metadaten-/Content-Pakete behandelt. In aktuellen Releases bedeutet das meist
als Metadaten-/Inhaltspakete behandelt. In aktuellen Releases bedeutet das meist
gebündelte Skills.
Verwenden Sie Allowlists und explizite Installations-/Ladepfade für nicht gebündelte Plugins. Behandeln Sie
Workspace-Plugins als Entwicklungszeit-Code, nicht als Produktionsstandard.
Workspace-Plugins als Code zur Entwicklungszeit, nicht als Standard für die Produktion.
Bei gebündelten Workspace-Paketnamen bleibt die Plugin-ID im npm-
Namen verankert: standardmäßig `@openclaw/<id>` oder ein genehmigter typisierter Suffix wie
Bei gebündelten Workspace-Paketnamen halten Sie die Plugin-ID im npm-
Namen verankert: standardmäßig `@openclaw/<id>` oder ein genehmigtes typisiertes Suffix wie
`-provider`, `-plugin`, `-speech`, `-sandbox` oder `-media-understanding`, wenn
das Paket absichtlich eine engere Plugin-Rolle bereitstellt.
@ -493,39 +502,39 @@ Wichtiger Hinweis zum Vertrauen:
- `plugins.allow` vertraut **Plugin-IDs**, nicht der Herkunft der Quelle.
- Ein Workspace-Plugin mit derselben ID wie ein gebündeltes Plugin überschattet
absichtlich die gebündelte Kopie, wenn dieses Workspace-Plugin aktiviert/allowlistet ist.
absichtlich die gebündelte Kopie, wenn dieses Workspace-Plugin aktiviert/auf der Allowlist steht.
- Das ist normal und nützlich für lokale Entwicklung, Patch-Tests und Hotfixes.
- Vertrauen in gebündelte Plugins wird aus dem Source-Snapshot aufgelöst — dem Manifest und
dem Code auf dem Datenträger zum Ladezeitpunkt — nicht aus Installationsmetadaten. Ein beschädigter
oder ersetzter Installationsdatensatz kann die Vertrauensoberfläche eines gebündelten Plugins
nicht stillschweigend über das hinaus erweitern, was der tatsächliche Quellcode beansprucht.
Code auf Datenträger zur Ladezeit — und nicht aus Installationsmetadaten. Ein beschädigter
oder ersetzter Installationseintrag kann die Vertrauensoberfläche eines gebündelten Plugins nicht stillschweigend
über das hinaus erweitern, was die tatsächliche Quelle beansprucht.
## Export-Grenze
OpenClaw exportiert Fähigkeiten, keine bequemen Implementierungs-Shortcuts.
OpenClaw exportiert Capabilities, keine Bequemlichkeitsimplementierungen.
Halten Sie die Fähigkeitsregistrierung öffentlich. Beschneiden Sie nicht vertragliche Helper-Exporte:
Halten Sie die Registrierung von Capabilities öffentlich. Kürzen Sie nichtvertragliche Helferexporte:
- gebündelte plugin-spezifische Helper-Subpaths
- Runtime-Plumbing-Subpaths, die nicht als öffentliche API gedacht sind
- anbieterspezifische Convenience-Helper
- Setup-/Onboarding-Helper, die Implementierungsdetails sind
- helper-Subpaths speziell für gebündelte Plugins
- Subpaths für Laufzeitverdrahtung, die nicht als öffentliche API gedacht sind
- anbieterspezifische Convenience-Helfer
- Setup-/Onboarding-Helfer, die Implementierungsdetails sind
Einige Helper-Subpaths gebündelter Plugins bleiben aus Kompatibilitäts- und Wartungsgründen für gebündelte Plugins weiterhin in der generierten SDK-Export-Map. Aktuelle Beispiele sind
Einige Hilfs-Subpaths gebündelter Plugins bleiben aus Kompatibilitätsgründen und für die Pflege gebündelter Plugins weiterhin in der generierten SDK-Export-Map erhalten. Aktuelle Beispiele sind
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup` und mehrere `plugin-sdk/matrix*`-Seams. Behandeln Sie diese als
reservierte Exportdetails der Implementierung, nicht als empfohlenes SDK-Muster für
neue Plugins von Drittanbietern.
`plugin-sdk/zalo-setup` und mehrere Seams vom Typ `plugin-sdk/matrix*`. Behandeln Sie diese als
reservierte, implementierungsbezogene Exporte, nicht als empfohlenes SDK-Muster für
neue Drittanbieter-Plugins.
## Interna und Referenz
Für die Lade-Pipeline, das Registry-Modell, Provider-Runtime-Hooks, Gateway-HTTP-
Routen, Message-Tool-Schemas, Auflösung von Kanalzielen, Provider-Kataloge,
Context-Engine-Plugins und die Anleitung zum Hinzufügen einer neuen Fähigkeit siehe
[Plugin-Architektur-Interna](/de/plugins/architecture-internals).
Für die Lade-Pipeline, das Registry-Modell, Runtime-Hooks für Provider, Gateway-HTTP-
Routen, Schemas für Nachrichtentools, Auflösung von Channel-Zielen, Provider-Kataloge,
Context-Engine-Plugins und die Anleitung zum Hinzufügen einer neuen Capability siehe
[Plugin architecture internals](/de/plugins/architecture-internals).
## Verwandt
- [Plugins erstellen](/de/plugins/building-plugins)
- [Plugin-SDK-Einrichtung](/de/plugins/sdk-setup)
- [Plugin-SDK-Setup](/de/plugins/sdk-setup)
- [Plugin-Manifest](/de/plugins/manifest)

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

@ -1,113 +1,73 @@
---
read_when:
- Sie möchten das gebündelte Codex-App-Server-Harness verwenden
- Sie benötigen Codex-Modell-Refs und Konfigurationsbeispiele
- Sie möchten den PI-Fallback für reine Codex-Bereitstellungen deaktivieren
summary: Eingebettete Agenten-Turns von OpenClaw über das gebündelte Codex-App-Server-Harness ausführen
- Sie benötigen Codex-Modellreferenzen und Config-Beispiele
- Sie möchten den Pi-Fallback für reine Codex-Bereitstellungen deaktivieren
summary: OpenClaw-eingebettete Agent-Turns über das gebündelte Codex-App-Server-Harness ausführen
title: Codex-Harness
x-i18n:
generated_at: "2026-04-24T06:49:16Z"
generated_at: "2026-04-24T08:58:50Z"
model: gpt-5.4
provider: openai
source_hash: 095933d2c32df302c312c67fdc266d2f01b552dddb1607d6e4ecc4f3c3326acf
source_hash: c02b1e6cbaaefee858db7ebd7e306261683278ed9375bca6fe74855ca84eabd8
source_path: plugins/codex-harness.md
workflow: 15
---
Das gebündelte Plugin `codex` ermöglicht es OpenClaw, eingebettete Agenten-Turns über den
Codex-App-Server statt über das integrierte PI-Harness auszuführen.
Das gebündelte `codex`-Plugin ermöglicht es OpenClaw, eingebettete Agent-Turns über den Codex-App-Server statt über das integrierte Pi-Harness auszuführen.
Verwenden Sie dies, wenn Codex die Low-Level-Agentensitzung besitzen soll: Modell-
Discovery, natives Thread-Resume, native Compaction und App-Server-Ausführung.
OpenClaw besitzt weiterhin Chat-Kanäle, Sitzungsdateien, Modellauswahl, Tools,
Genehmigungen, Medienzustellung und das sichtbare Spiegel-Transkript.
Verwenden Sie dies, wenn Codex die Agent-Sitzung auf niedriger Ebene steuern soll: Modellerkennung, natives Wiederaufnehmen von Threads, native Compaction und Ausführung im App-Server.
OpenClaw steuert weiterhin Chat-Channels, Sitzungsdateien, Modellauswahl, Tools, Freigaben, Medienzustellung und die sichtbare Spiegelung des Transkripts.
Native Codex-Turns behalten OpenClaw-Plugin-Hooks als öffentliche Kompatibilitätsschicht.
Dabei handelt es sich um In-Process-Hooks von OpenClaw, nicht um `hooks.json`-Befehlshooks von Codex:
Native Codex-Turns behalten OpenClaw-Plugin-Hooks als öffentliche Kompatibilitätsschicht bei.
Dabei handelt es sich um In-Process-Hooks von OpenClaw, nicht um Codex-`hooks.json`-Befehlshooks:
- `before_prompt_build`
- `before_compaction`, `after_compaction`
- `llm_input`, `llm_output`
- `after_tool_call`
- `before_message_write` für gespiegelte Transkriptdatensätze
- `before_message_write` für gespiegelte Transkript-Einträge
- `agent_end`
Gebündelte Plugins können außerdem eine Extension-Factory für den Codex-App-Server registrieren, um
asynchrone Middleware für `tool_result` hinzuzufügen. Diese Middleware läuft für dynamische OpenClaw-Tools,
nachdem OpenClaw das Tool ausgeführt hat und bevor das Ergebnis an Codex zurückgegeben wird. Sie
ist getrennt vom öffentlichen Plugin-Hook `tool_result_persist`, der OpenClaw-eigene
Tool-Ergebnisschreibvorgänge im Transkript transformiert.
Gebündelte Plugins können auch eine Codex-App-Server-Extension-Factory registrieren, um asynchrone `tool_result`-Middleware hinzuzufügen. Diese Middleware läuft für dynamische OpenClaw-Tools, nachdem OpenClaw das Tool ausgeführt hat und bevor das Ergebnis an Codex zurückgegeben wird. Sie ist getrennt vom öffentlichen Plugin-Hook `tool_result_persist`, der OpenClaw-eigene Schreibvorgänge für Tool-Ergebnisse im Transkript transformiert.
Das Harness ist standardmäßig deaktiviert. Neue Konfigurationen sollten OpenAI-Modell-Refs
kanonisch als `openai/gpt-*` beibehalten und explizit
`embeddedHarness.runtime: "codex"` oder `OPENCLAW_AGENT_RUNTIME=codex` erzwingen, wenn sie
native App-Server-Ausführung möchten. Legacy-Modell-Refs `codex/*` wählen das Harness aus Kompatibilitätsgründen weiterhin automatisch aus.
Das Harness ist standardmäßig deaktiviert. Neue Configs sollten OpenAI-Modellreferenzen kanonisch als `openai/gpt-*` beibehalten und explizit `embeddedHarness.runtime: "codex"` oder `OPENCLAW_AGENT_RUNTIME=codex` erzwingen, wenn sie native Ausführung über den App-Server möchten. Veraltete Modellreferenzen `codex/*` wählen das Harness aus Kompatibilitätsgründen weiterhin automatisch aus.
## Das richtige Modellpräfix wählen
Routen der OpenAI-Familie sind präfixspezifisch. Verwenden Sie `openai-codex/*`, wenn Sie
Codex-OAuth über PI möchten; verwenden Sie `openai/*`, wenn Sie direkten OpenAI-API-Zugriff möchten oder
wenn Sie das native Codex-App-Server-Harness erzwingen:
Routen der OpenAI-Familie sind präfixspezifisch. Verwenden Sie `openai-codex/*`, wenn Sie Codex-OAuth über Pi verwenden möchten; verwenden Sie `openai/*`, wenn Sie direkten OpenAI-API-Zugriff möchten oder wenn Sie das native Codex-App-Server-Harness erzwingen:
| Modell-Ref | Laufzeitpfad | Verwenden Sie dies, wenn |
| ----------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- |
| `openai/gpt-5.4` | OpenAI-Provider über OpenClaw/PI-Plumbing | Sie aktuellen direkten OpenAI-Platform-API-Zugriff mit `OPENAI_API_KEY` möchten. |
| `openai-codex/gpt-5.5` | OpenAI-Codex-OAuth über OpenClaw/PI | Sie ChatGPT-/Codex-Abo-Auth mit dem Standard-PI-Runner möchten. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex-App-Server-Harness | Sie native Codex-App-Server-Ausführung für den eingebetteten Agenten-Turn möchten. |
| Modellreferenz | Runtime-Pfad | Verwenden, wenn |
| ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | OpenAI-Provider über OpenClaw/Pi-Plumbing | Sie aktuellen direkten Zugriff auf die OpenAI-Platform-API mit `OPENAI_API_KEY` möchten. |
| `openai-codex/gpt-5.5` | OpenAI-Codex-OAuth über OpenClaw/Pi | Sie ChatGPT-/Codex-Abonnement-Authentifizierung mit dem Standard-Pi-Runner möchten. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex-App-Server-Harness | Sie native Ausführung über den Codex-App-Server für den eingebetteten Agent-Turn möchten. |
GPT-5.5 ist in OpenClaw derzeit nur per Abo/OAuth verfügbar. Verwenden Sie
`openai-codex/gpt-5.5` für PI-OAuth oder `openai/gpt-5.5` mit dem Codex-
App-Server-Harness. Direkter API-Schlüssel-Zugriff für `openai/gpt-5.5` wird unterstützt,
sobald OpenAI GPT-5.5 auf der öffentlichen API freischaltet.
GPT-5.5 ist derzeit in OpenClaw nur mit Abonnement/OAuth verfügbar. Verwenden Sie `openai-codex/gpt-5.5` für Pi-OAuth oder `openai/gpt-5.5` mit dem Codex-App-Server-Harness. Direkter API-Key-Zugriff für `openai/gpt-5.5` wird unterstützt, sobald OpenAI GPT-5.5 in der öffentlichen API aktiviert.
Legacy-Refs `codex/gpt-*` werden weiterhin als Kompatibilitäts-Aliasse akzeptiert. Neue PI-
Codex-OAuth-Konfigurationen sollten `openai-codex/gpt-*` verwenden; neue Konfigurationen für native App-Server-
Harnesses sollten `openai/gpt-*` plus `embeddedHarness.runtime:
"codex"` verwenden.
Veraltete Referenzen `codex/gpt-*` werden weiterhin als Kompatibilitätsaliase akzeptiert. Neue Pi-Codex-OAuth-Configs sollten `openai-codex/gpt-*` verwenden; neue Configs für das native App-Server-Harness sollten `openai/gpt-*` plus `embeddedHarness.runtime: "codex"` verwenden.
`agents.defaults.imageModel` folgt derselben Aufteilung nach Präfix. Verwenden Sie
`openai-codex/gpt-*`, wenn Bildverständnis über den Providerpfad von OpenAI
Codex OAuth laufen soll. Verwenden Sie `codex/gpt-*`, wenn Bildverständnis
über einen begrenzten Codex-App-Server-Turn laufen soll. Das Modell des Codex-App-Servers muss
Unterstützung für Bildeingaben ausweisen; reine Text-Codex-Modelle schlagen fehl, bevor der Media-Turn
beginnt.
`agents.defaults.imageModel` folgt derselben Präfix-Aufteilung. Verwenden Sie `openai-codex/gpt-*`, wenn die Bildverarbeitung über den Provider-Pfad OpenAI Codex OAuth laufen soll. Verwenden Sie `codex/gpt-*`, wenn die Bildverarbeitung über einen begrenzten Codex-App-Server-Turn laufen soll. Das Codex-App-Server-Modell muss Unterstützung für Bildeingaben ankündigen; reine Text-Codex-Modelle schlagen fehl, bevor der Medien-Turn beginnt.
Verwenden Sie `/status`, um das effektive Harness für die aktuelle Sitzung zu bestätigen. Wenn die
Auswahl überraschend ist, aktivieren Sie Debug-Logging für das Subsystem `agents/harness`
und prüfen Sie den strukturierten Datensatz `agent harness selected` des Gateway. Er
enthält die ID des ausgewählten Harness, den Grund der Auswahl, die Laufzeit-/Fallback-Richtlinie und,
im Modus `auto`, das Unterstützungsresultat jedes Plugin-Kandidaten.
Verwenden Sie `/status`, um das effektive Harness für die aktuelle Sitzung zu bestätigen. Wenn die Auswahl überraschend ist, aktivieren Sie Debug-Logging für das Subsystem `agents/harness` und prüfen Sie den strukturierten Datensatz `agent harness selected` des Gateways. Er enthält die ID des ausgewählten Harness, den Grund der Auswahl, die Richtlinie für Runtime/Fallback und im Modus `auto` das Unterstützungsergebnis jedes Plugin-Kandidaten.
Die Auswahl des Harness ist keine Live-Steuerung einer Sitzung. Wenn ein eingebetteter Turn läuft,
zeichnet OpenClaw die ID des ausgewählten Harness für diese Sitzung auf und verwendet sie auch für
spätere Turns in derselben Sitzungs-ID. Ändern Sie die Konfiguration von `embeddedHarness` oder
`OPENCLAW_AGENT_RUNTIME`, wenn zukünftige Sitzungen ein anderes Harness verwenden sollen;
verwenden Sie `/new` oder `/reset`, um eine neue Sitzung zu starten, bevor Sie eine bestehende
Konversation zwischen PI und Codex umschalten. So wird vermieden, dass ein Transkript über zwei
inkompatible native Sitzungssysteme erneut abgespielt wird.
Die Auswahl des Harness ist keine Live-Steuerung für Sitzungen. Wenn ein eingebetteter Turn ausgeführt wird, zeichnet OpenClaw die ID des ausgewählten Harness für diese Sitzung auf und verwendet sie für spätere Turns in derselben Sitzungs-ID weiter. Ändern Sie die Config `embeddedHarness` oder `OPENCLAW_AGENT_RUNTIME`, wenn zukünftige Sitzungen ein anderes Harness verwenden sollen; verwenden Sie `/new` oder `/reset`, um eine neue Sitzung zu starten, bevor Sie eine bestehende Unterhaltung zwischen Pi und Codex umschalten. Dadurch wird vermieden, dass ein Transkript über zwei inkompatible native Sitzungssysteme erneut abgespielt wird.
Legacy-Sitzungen, die vor Harness-Pins erstellt wurden, werden als an PI gepinnt behandelt, sobald sie
Transkriptverlauf haben. Verwenden Sie `/new` oder `/reset`, um diese Konversation nach Änderung der Konfiguration
für Codex zu aktivieren.
Veraltete Sitzungen, die vor Harness-Pins erstellt wurden, werden als an Pi gebunden behandelt, sobald sie einen Transkriptverlauf haben. Verwenden Sie `/new` oder `/reset`, um diese Unterhaltung nach einer Config-Änderung für Codex zu aktivieren.
`/status` zeigt das effektive nicht-PI-Harness neben `Fast`, zum Beispiel
`Fast · codex`. Das Standard-PI-Harness bleibt `Runner: pi (embedded)` und fügt
kein separates Harness-Badge hinzu.
`/status` zeigt das effektive Nicht-Pi-Harness neben `Fast` an, zum Beispiel `Fast · codex`. Das Standard-Pi-Harness bleibt `Runner: pi (embedded)` und fügt kein separates Harness-Badge hinzu.
## Anforderungen
- OpenClaw mit dem verfügbaren gebündelten Plugin `codex`.
- OpenClaw mit verfügbarem gebündeltem `codex`-Plugin.
- Codex-App-Server `0.118.0` oder neuer.
- Für den App-Server-Prozess verfügbare Codex-Auth.
- Codex-Authentifizierung, die für den App-Server-Prozess verfügbar ist.
Das Plugin blockiert ältere oder versionslose Handshakes des App-Servers. So bleibt
OpenClaw auf der Protokolloberfläche, gegen die es getestet wurde.
Das Plugin blockiert ältere oder versionslose Handshakes des App-Servers. Dadurch bleibt OpenClaw auf der Protokolloberfläche, gegen die es getestet wurde.
Für Live- und Docker-Smoke-Tests kommt Auth normalerweise von `OPENAI_API_KEY` sowie
optionalen Codex-CLI-Dateien wie `~/.codex/auth.json` und
`~/.codex/config.toml`. Verwenden Sie dasselbe Auth-Material wie Ihr lokaler Codex-App-Server.
Für Live- und Docker-Smoke-Tests stammt die Authentifizierung normalerweise aus `OPENAI_API_KEY` sowie optionalen Codex-CLI-Dateien wie `~/.codex/auth.json` und `~/.codex/config.toml`. Verwenden Sie dasselbe Auth-Material, das auch Ihr lokaler Codex-App-Server verwendet.
## Minimale Konfiguration
## Minimale Config
Verwenden Sie `openai/gpt-5.5`, aktivieren Sie das gebündelte Plugin und erzwingen Sie das Harness `codex`:
@ -132,7 +92,7 @@ Verwenden Sie `openai/gpt-5.5`, aktivieren Sie das gebündelte Plugin und erzwin
}
```
Wenn Ihre Konfiguration `plugins.allow` verwendet, nehmen Sie dort ebenfalls `codex` auf:
Wenn Ihre Config `plugins.allow` verwendet, schließen Sie dort ebenfalls `codex` ein:
```json5
{
@ -147,15 +107,11 @@ Wenn Ihre Konfiguration `plugins.allow` verwendet, nehmen Sie dort ebenfalls `co
}
```
Legacy-Konfigurationen, die `agents.defaults.model` oder ein Agentenmodell auf
`codex/<model>` setzen, aktivieren das gebündelte Plugin `codex` weiterhin automatisch. Neue Konfigurationen sollten
`openai/<model>` plus den expliziten `embeddedHarness`-Eintrag oben bevorzugen.
Veraltete Configs, die `agents.defaults.model` oder ein Agent-Modell auf `codex/<model>` setzen, aktivieren das gebündelte `codex`-Plugin weiterhin automatisch. Neue Configs sollten `openai/<model>` plus den obigen expliziten Eintrag `embeddedHarness` bevorzugen.
## Codex hinzufügen, ohne andere Modelle zu ersetzen
Behalten Sie `runtime: "auto"` bei, wenn alte `codex/*`-Refs Codex auswählen und
PI für alles andere verwendet werden soll. Für neue Konfigurationen bevorzugen Sie explizites `runtime: "codex"` bei
den Agenten, die das Harness verwenden sollen.
Behalten Sie `runtime: "auto"` bei, wenn veraltete Referenzen `codex/*` Codex auswählen sollen und Pi für alles andere. Für neue Configs bevorzugen Sie explizites `runtime: "codex"` bei den Agents, die das Harness verwenden sollen.
```json5
{
@ -185,16 +141,15 @@ den Agenten, die das Harness verwenden sollen.
}
```
Mit dieser Form:
Bei dieser Struktur gilt:
- `/model gpt` oder `/model openai/gpt-5.5` verwendet für diese Konfiguration das Codex-App-Server-Harness.
- `/model opus` verwendet den Anthropic-Providerpfad.
- Wenn ein Nicht-Codex-Modell ausgewählt ist, bleibt PI das Kompatibilitäts-Harness.
- `/model gpt` oder `/model openai/gpt-5.5` verwendet für diese Config das Codex-App-Server-Harness.
- `/model opus` verwendet den Anthropic-Provider-Pfad.
- Wenn ein Nicht-Codex-Modell ausgewählt ist, bleibt Pi das Kompatibilitätsharness.
## Reine Codex-Bereitstellungen
Deaktivieren Sie den PI-Fallback, wenn Sie nachweisen müssen, dass jeder eingebettete Agenten-Turn das
Codex-Harness verwendet:
Deaktivieren Sie den Pi-Fallback, wenn Sie nachweisen müssen, dass jeder eingebettete Agent-Turn das Codex-Harness verwendet:
```json5
{
@ -218,13 +173,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
openclaw gateway run
```
Wenn der Fallback deaktiviert ist, schlägt OpenClaw früh fehl, wenn das Codex-Plugin deaktiviert ist,
der App-Server zu alt ist oder der App-Server nicht starten kann.
Wenn der Fallback deaktiviert ist, schlägt OpenClaw früh fehl, wenn das Codex-Plugin deaktiviert ist, der App-Server zu alt ist oder der App-Server nicht gestartet werden kann.
## Codex pro Agent
Sie können einen Agenten nur für Codex konfigurieren, während der Standard-Agent die normale
Auto-Auswahl beibehält:
Sie können einen Agent auf reines Codex festlegen, während der Standard-Agent die normale automatische Auswahl beibehält:
```json5
{
@ -255,21 +208,17 @@ Auto-Auswahl beibehält:
}
```
Verwenden Sie normale Sitzungsbefehle, um Agenten und Modelle zu wechseln. `/new` erstellt eine neue
OpenClaw-Sitzung, und das Codex-Harness erstellt oder setzt bei Bedarf seinen Sidecar-App-Server-
Thread fort. `/reset` löscht die OpenClaw-Sitzungsbindung für diesen Thread
und lässt den nächsten Turn das Harness erneut aus der aktuellen Konfiguration auflösen.
Verwenden Sie normale Sitzungsbefehle, um Agents und Modelle zu wechseln. `/new` erstellt eine neue OpenClaw-Sitzung und das Codex-Harness erstellt oder setzt den zugehörigen App-Server-Thread bei Bedarf fort. `/reset` löscht die OpenClaw-Sitzungsbindung für diesen Thread und lässt den nächsten Turn das Harness erneut aus der aktuellen Config auflösen.
## Modell-Discovery
## Modellerkennung
Standardmäßig fragt das Codex-Plugin den App-Server nach verfügbaren Modellen. Wenn
Discovery fehlschlägt oder ein Timeout eintritt, verwendet es einen gebündelten Fallback-Katalog für:
Standardmäßig fragt das Codex-Plugin den App-Server nach verfügbaren Modellen. Wenn die Erkennung fehlschlägt oder in ein Timeout läuft, verwendet es einen gebündelten Fallback-Katalog für:
- GPT-5.5
- GPT-5.4 mini
- GPT-5.2
Sie können Discovery unter `plugins.entries.codex.config.discovery` anpassen:
Sie können die Erkennung unter `plugins.entries.codex.config.discovery` anpassen:
```json5
{
@ -289,8 +238,7 @@ Sie können Discovery unter `plugins.entries.codex.config.discovery` anpassen:
}
```
Deaktivieren Sie Discovery, wenn Sie möchten, dass der Start auf Probes an Codex verzichtet und beim
Fallback-Katalog bleibt:
Deaktivieren Sie die Erkennung, wenn Sie möchten, dass der Start das Prüfen von Codex vermeidet und beim Fallback-Katalog bleibt:
```json5
{
@ -309,7 +257,7 @@ Fallback-Katalog bleibt:
}
```
## Verbindung und Richtlinie des App-Servers
## Verbindung zum App-Server und Richtlinie
Standardmäßig startet das Plugin Codex lokal mit:
@ -319,11 +267,9 @@ codex app-server --listen stdio://
Standardmäßig startet OpenClaw lokale Codex-Harness-Sitzungen im YOLO-Modus:
`approvalPolicy: "never"`, `approvalsReviewer: "user"` und
`sandbox: "danger-full-access"`. Dies ist die vertrauenswürdige lokale Operator-Haltung, die für
autonome Heartbeats verwendet wird: Codex kann Shell- und Netzwerk-Tools verwenden, ohne bei nativen
Genehmigungs-Prompts anzuhalten, die niemand beantworten kann.
`sandbox: "danger-full-access"`. Dies ist die vertrauenswürdige lokale Operator-Haltung, die für autonome Heartbeats verwendet wird: Codex kann Shell- und Netzwerk-Tools verwenden, ohne bei nativen Freigabeaufforderungen anzuhalten, wenn niemand da ist, um sie zu beantworten.
Um die von Guardian überprüften nativen Codex-Genehmigungen zu aktivieren, setzen Sie `appServer.mode:
Um Codex-Freigaben mit Prüfung durch Guardian zu aktivieren, setzen Sie `appServer.mode:
"guardian"`:
```json5
@ -344,11 +290,11 @@ Um die von Guardian überprüften nativen Codex-Genehmigungen zu aktivieren, set
}
```
Guardian ist ein nativer Genehmigungsprüfer von Codex. Wenn Codex anfragt, die Sandbox zu verlassen, außerhalb des Workspace zu schreiben oder Berechtigungen wie Netzwerkzugriff hinzuzufügen, leitet Codex diese Genehmigungsanfrage an einen Reviewer-Subagenten statt an einen menschlichen Prompt weiter. Der Reviewer wendet das Risikoframework von Codex an und genehmigt oder lehnt die konkrete Anfrage ab. Verwenden Sie Guardian, wenn Sie mehr Leitplanken als im YOLO-Modus möchten, aber weiterhin unbeaufsichtigte Agenten Fortschritte machen sollen.
Guardian ist ein nativer Freigabeprüfer von Codex. Wenn Codex darum bittet, die Sandbox zu verlassen, außerhalb des Workspace zu schreiben oder Berechtigungen wie Netzwerkzugriff hinzuzufügen, leitet Codex diese Freigabeanfrage an einen Prüfer-Subagent weiter statt an eine Aufforderung für Menschen. Der Prüfer wendet das Risikokonzept von Codex an und genehmigt oder lehnt die konkrete Anfrage ab. Verwenden Sie Guardian, wenn Sie mehr Guardrails als im YOLO-Modus möchten, aber weiterhin unbeaufsichtigte Agents Fortschritte machen sollen.
Das Preset `guardian` wird erweitert zu `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` und `sandbox: "workspace-write"`. Einzelne Richtlinienfelder überschreiben weiterhin `mode`, sodass fortgeschrittene Bereitstellungen das Preset mit expliziten Entscheidungen mischen können.
Das Preset `guardian` wird erweitert zu `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` und `sandbox: "workspace-write"`. Einzelne Richtlinienfelder überschreiben weiterhin `mode`, sodass fortgeschrittene Bereitstellungen das Preset mit expliziten Entscheidungen kombinieren können.
Verwenden Sie für einen bereits laufenden App-Server WebSocket-Transport:
Für einen bereits laufenden App-Server verwenden Sie WebSocket-Transport:
```json5
{
@ -372,23 +318,22 @@ Verwenden Sie für einen bereits laufenden App-Server WebSocket-Transport:
Unterstützte `appServer`-Felder:
| Feld | Standard | Bedeutung |
| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` startet Codex; `"websocket"` verbindet sich mit `url`. |
| `command` | `"codex"` | Ausführbare Datei für `stdio`-Transport. |
| `args` | `["app-server", "--listen", "stdio://"]` | Argumente für `stdio`-Transport. |
| `url` | nicht gesetzt | WebSocket-App-Server-URL. |
| `authToken` | nicht gesetzt | Bearer-Token für WebSocket-Transport. |
| `headers` | `{}` | Zusätzliche WebSocket-Header. |
| `requestTimeoutMs` | `60000` | Timeout für Control-Plane-Aufrufe an den App-Server. |
| `mode` | `"yolo"` | Preset für YOLO oder von Guardian überprüfte Ausführung. |
| `approvalPolicy` | `"never"` | Native Codex-Genehmigungsrichtlinie, die an Start/Resume/Turn des Threads gesendet wird. |
| `sandbox` | `"danger-full-access"` | Nativer Codex-Sandbox-Modus, der an Start/Resume des Threads gesendet wird. |
| `approvalsReviewer` | `"user"` | Verwenden Sie `"guardian_subagent"`, damit Codex Guardian Prompts prüft. |
| `serviceTier` | nicht gesetzt | Optionale Service-Tier des Codex-App-Servers: `"fast"`, `"flex"` oder `null`. Ungültige Legacy-Werte werden ignoriert. |
| Feld | Standardwert | Bedeutung |
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` startet Codex; `"websocket"` verbindet sich mit `url`. |
| `command` | `"codex"` | Executable für den Stdio-Transport. |
| `args` | `["app-server", "--listen", "stdio://"]` | Argumente für den Stdio-Transport. |
| `url` | nicht gesetzt | WebSocket-App-Server-URL. |
| `authToken` | nicht gesetzt | Bearer-Token für den WebSocket-Transport. |
| `headers` | `{}` | Zusätzliche WebSocket-Header. |
| `requestTimeoutMs` | `60000` | Timeout für Control-Plane-Aufrufe des App-Servers. |
| `mode` | `"yolo"` | Preset für YOLO- oder Guardian-geprüfte Ausführung. |
| `approvalPolicy` | `"never"` | Native Codex-Freigaberichtlinie, die an Start/Fortsetzung/Turn des Threads gesendet wird. |
| `sandbox` | `"danger-full-access"` | Nativer Codex-Sandbox-Modus, der an Start/Fortsetzung des Threads gesendet wird. |
| `approvalsReviewer` | `"user"` | Verwenden Sie `"guardian_subagent"`, damit Codex Guardian Prompts prüfen kann. |
| `serviceTier` | nicht gesetzt | Optionales Service-Tier des Codex-App-Servers: `"fast"`, `"flex"` oder `null`. Ungültige ältere Werte werden ignoriert. |
Die älteren Umgebungsvariablen funktionieren für lokale Tests weiterhin als Fallbacks, wenn
das passende Konfigurationsfeld nicht gesetzt ist:
Die älteren Umgebungsvariablen funktionieren für lokale Tests weiterhin als Fallbacks, wenn das passende Config-Feld nicht gesetzt ist:
- `OPENCLAW_CODEX_APP_SERVER_BIN`
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
@ -396,15 +341,11 @@ das passende Konfigurationsfeld nicht gesetzt ist:
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` wurde entfernt. Verwenden Sie
stattdessen `plugins.entries.codex.config.appServer.mode: "guardian"` oder
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` für einmalige lokale Tests. Konfiguration
wird für wiederholbare Bereitstellungen bevorzugt, weil das Plugin-Verhalten so in derselben
geprüften Datei liegt wie der Rest der Codex-Harness-Einrichtung.
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` wurde entfernt. Verwenden Sie stattdessen `plugins.entries.codex.config.appServer.mode: "guardian"` oder `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` für einmalige lokale Tests. Config wird für reproduzierbare Bereitstellungen bevorzugt, weil dadurch das Verhalten des Plugins in derselben geprüften Datei wie der Rest des Codex-Harness-Setups bleibt.
## Häufige Rezepte
Lokaler Codex mit standardmäßigem `stdio`-Transport:
Lokales Codex mit Standard-Stdio-Transport:
```json5
{
@ -418,7 +359,7 @@ Lokaler Codex mit standardmäßigem `stdio`-Transport:
}
```
Validierung eines Codex-only-Harness, mit deaktiviertem PI-Fallback:
Validierung für reines Codex-Harness mit deaktiviertem Pi-Fallback:
```json5
{
@ -435,7 +376,7 @@ Validierung eines Codex-only-Harness, mit deaktiviertem PI-Fallback:
}
```
Von Guardian überprüfte Codex-Genehmigungen:
Guardian-geprüfte Codex-Freigaben:
```json5
{
@ -480,124 +421,77 @@ Remote-App-Server mit expliziten Headern:
}
```
Das Umschalten von Modellen bleibt von OpenClaw gesteuert. Wenn eine OpenClaw-Sitzung an
einen bestehenden Codex-Thread gebunden ist, sendet der nächste Turn das aktuell ausgewählte
OpenAI-Modell, den Provider, die Genehmigungsrichtlinie, die Sandbox und die Service-Tier erneut an den
App-Server. Beim Wechsel von `openai/gpt-5.5` zu `openai/gpt-5.2` bleibt die
Thread-Bindung erhalten, aber OpenClaw fordert Codex auf, mit dem neu ausgewählten Modell fortzufahren.
Das Umschalten von Modellen bleibt unter der Kontrolle von OpenClaw. Wenn eine OpenClaw-Sitzung an einen bestehenden Codex-Thread angehängt ist, sendet der nächste Turn das aktuell ausgewählte OpenAI-Modell, den Provider, die Freigaberichtlinie, die Sandbox und das Service-Tier erneut an den App-Server. Beim Wechsel von `openai/gpt-5.5` zu `openai/gpt-5.2` bleibt die Thread-Bindung erhalten, aber Codex wird aufgefordert, mit dem neu ausgewählten Modell fortzufahren.
## Codex-Befehl
Das gebündelte Plugin registriert `/codex` als autorisierten Slash-Befehl. Er ist
generisch und funktioniert auf jedem Kanal, der Textbefehle von OpenClaw unterstützt.
Das gebündelte Plugin registriert `/codex` als autorisierten Slash-Befehl. Er ist generisch und funktioniert auf jedem Channel, der Textbefehle von OpenClaw unterstützt.
Häufige Formen:
- `/codex status` zeigt Live-Konnektivität zum App-Server, Modelle, Account, Rate Limits, MCP-Server und Skills.
- `/codex models` listet Live-Modelle des Codex-App-Servers auf.
- `/codex threads [filter]` listet aktuelle Codex-Threads auf.
- `/codex resume <thread-id>` bindet die aktuelle OpenClaw-Sitzung an einen bestehenden Codex-Thread.
- `/codex compact` fordert den Codex-App-Server auf, den gebundenen Thread zu komprimieren.
- `/codex review` startet die native Codex-Prüfung für den gebundenen Thread.
- `/codex account` zeigt Account- und Rate-Limit-Status.
- `/codex mcp` listet den Status der MCP-Server des Codex-App-Servers auf.
- `/codex skills` listet Skills des Codex-App-Servers auf.
- `/codex status` zeigt Live-App-Server-Konnektivität, Modelle, Account, Ratenlimits, MCP-Server und Skills.
- `/codex models` listet die Live-Modelle des Codex-App-Servers auf.
- `/codex threads [filter]` listet die aktuellen Codex-Threads auf.
- `/codex resume <thread-id>` hängt die aktuelle OpenClaw-Sitzung an einen bestehenden Codex-Thread an.
- `/codex compact` fordert den Codex-App-Server auf, den angehängten Thread zu komprimieren.
- `/codex review` startet die native Codex-Prüfung für den angehängten Thread.
- `/codex account` zeigt Account- und Ratenlimit-Status an.
- `/codex mcp` listet den MCP-Server-Status des Codex-App-Servers auf.
- `/codex skills` listet die Skills des Codex-App-Servers auf.
`/codex resume` schreibt dieselbe Sidecar-Bindungsdatei, die das Harness für
normale Turns verwendet. Bei der nächsten Nachricht setzt OpenClaw diesen Codex-Thread fort, übergibt das
aktuell ausgewählte OpenClaw-Modell an den App-Server und lässt die erweiterte Historie
aktiviert.
`/codex resume` schreibt dieselbe Sidecar-Bindungsdatei, die das Harness für normale Turns verwendet. Bei der nächsten Nachricht setzt OpenClaw diesen Codex-Thread fort, übergibt das aktuell ausgewählte OpenClaw-Modell an den App-Server und lässt den erweiterten Verlauf aktiviert.
Die Befehlsoberfläche erfordert Codex-App-Server `0.118.0` oder neuer. Einzelne
Steuermethoden werden als `unsupported by this Codex app-server` gemeldet, wenn ein
zukünftiger oder benutzerdefinierter App-Server diese JSON-RPC-Methode nicht bereitstellt.
Die Befehlsoberfläche erfordert Codex-App-Server `0.118.0` oder neuer. Einzelne Control-Methoden werden als `unsupported by this Codex app-server` gemeldet, wenn ein zukünftiger oder benutzerdefinierter App-Server diese JSON-RPC-Methode nicht bereitstellt.
## Hook-Grenzen
Das Codex-Harness hat drei Hook-Schichten:
Das Codex-Harness hat drei Hook-Ebenen:
| Schicht | Owner | Zweck |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| OpenClaw-Plugin-Hooks | OpenClaw | Produkt-/Plugin-Kompatibilität über PI- und Codex-Harnesses hinweg. |
| Extension-Middleware des Codex-App-Servers | Gebündelte OpenClaw-Plugins | Adapterverhalten pro Turn rund um dynamische OpenClaw-Tools. |
| Native Codex-Hooks | Codex | Low-Level-Codex-Lebenszyklus und native Tool-Richtlinie aus der Codex-Konfiguration. |
| Ebene | Verantwortlich | Zweck |
| ------------------------------------- | ------------------------- | ------------------------------------------------------------------- |
| OpenClaw-Plugin-Hooks | OpenClaw | Produkt-/Plugin-Kompatibilität über Pi- und Codex-Harnesses hinweg. |
| Codex-App-Server-Extension-Middleware | gebündelte OpenClaw-Plugins | Adapterverhalten pro Turn rund um dynamische OpenClaw-Tools. |
| Native Codex-Hooks | Codex | Low-Level-Codex-Lebenszyklus und native Tool-Richtlinie aus der Codex-Config. |
OpenClaw verwendet keine projektweiten oder globalen Codex-`hooks.json`-Dateien, um
Verhalten von OpenClaw-Plugins zu routen. Native Codex-Hooks sind nützlich für von Codex besessene
Operationen wie Shell-Richtlinie, native Prüfung von Tool-Ergebnissen, Stop-Verhalten und
native Compaction-/Modell-Lebenszyklen, aber sie sind nicht die OpenClaw-Plugin-API.
OpenClaw verwendet keine projektweiten oder globalen Codex-`hooks.json`-Dateien, um das Verhalten von OpenClaw-Plugins zu steuern. Native Codex-Hooks sind nützlich für Codex-eigene Operationen wie Shell-Richtlinien, native Prüfung von Tool-Ergebnissen, Stop-Behandlung und nativen Compaction-/Modell-Lebenszyklus, aber sie sind nicht die OpenClaw-Plugin-API.
Für dynamische OpenClaw-Tools führt OpenClaw das Tool aus, nachdem Codex den Aufruf angefordert hat, also
führt OpenClaw das Plugin- und Middleware-Verhalten aus, das ihm im
Harness-Adapter gehört. Für Codex-native Tools besitzt Codex den kanonischen Tool-Datensatz.
OpenClaw kann ausgewählte Ereignisse spiegeln, aber es kann den nativen Codex-
Thread nicht umschreiben, sofern Codex diese Operation nicht über den App-Server oder native Hook-
Callbacks bereitstellt.
Für dynamische OpenClaw-Tools führt OpenClaw das Tool aus, nachdem Codex den Aufruf angefordert hat. Deshalb löst OpenClaw das Plugin- und Middleware-Verhalten aus, das ihm im Harness-Adapter gehört. Für native Codex-Tools besitzt Codex den kanonischen Tool-Eintrag. OpenClaw kann ausgewählte Ereignisse spiegeln, aber den nativen Codex-Thread nicht umschreiben, sofern Codex diese Operation nicht über den App-Server oder native Hook-Callbacks bereitstellt.
Wenn neuere Builds des Codex-App-Servers native Hook-Ereignisse für Compaction und Modell-Lebenszyklus bereitstellen, soll OpenClaw diese Protokollunterstützung versionsgesteuert freischalten und die
Ereignisse dort in den bestehenden Hook-Vertrag von OpenClaw abbilden, wo die Semantik ehrlich ist.
Bis dahin sind die Ereignisse `before_compaction`, `after_compaction`, `llm_input` und
`llm_output` von OpenClaw Beobachtungen auf Adapter-Ebene, keine Byte-für-Byte-Erfassung
der internen Request- oder Compaction-Payloads von Codex.
Wenn neuere Codex-App-Server-Builds Hook-Ereignisse für native Compaction und den Modell-Lebenszyklus bereitstellen, sollte OpenClaw diese Protokollunterstützung versionsabhängig absichern und die Ereignisse dort in den bestehenden OpenClaw-Hook-Vertrag abbilden, wo die Semantik ehrlich ist. Bis dahin sind die Ereignisse `before_compaction`, `after_compaction`, `llm_input` und `llm_output` von OpenClaw Beobachtungen auf Adapterebene und keine Byte-für-Byte-Erfassungen der internen Anfrage- oder Compaction-Payloads von Codex.
Native Codex-`hook/started`- und `hook/completed`-App-Server-Benachrichtigungen werden als Agent-Ereignisse `codex_app_server.hook` für Trajektorie und Debugging projiziert. Sie rufen keine OpenClaw-Plugin-Hooks auf.
## Tools, Medien und Compaction
Das Codex-Harness ändert nur den Low-Level-Ausführer des eingebetteten Agenten.
Das Codex-Harness ändert nur den Low-Level-Executor für eingebettete Agents.
OpenClaw erstellt weiterhin die Tool-Liste und erhält dynamische Tool-Ergebnisse vom
Harness. Text, Bilder, Video, Musik, TTS, Genehmigungen und Ausgaben des Messaging-Tools
laufen weiterhin über den normalen Zustellpfad von OpenClaw.
OpenClaw erstellt weiterhin die Tool-Liste und empfängt dynamische Tool-Ergebnisse vom Harness. Text, Bilder, Video, Musik, TTS, Freigaben und Ausgaben von Messaging-Tools laufen weiterhin über den normalen Zustellpfad von OpenClaw.
Genehmigungsabfragen von Codex-MCP-Tools werden über den Plugin-
Genehmigungsablauf von OpenClaw geroutet, wenn Codex `_meta.codex_approval_kind` als
`"mcp_tool_call"` markiert. Prompts `request_user_input` von Codex werden an den
ursprünglichen Chat zurückgesendet, und die nächste in die Warteschlange gestellte Folge-Nachricht beantwortet diese
native Server-Anfrage, statt als zusätzlicher Kontext gelenkt zu werden. Andere MCP-Abfrageanfragen schlagen weiterhin geschlossen fehl.
Freigabeanforderungen für Codex-MCP-Tools werden über den Plugin-Freigabefluss von OpenClaw geleitet, wenn Codex `_meta.codex_approval_kind` als `"mcp_tool_call"` markiert. Codex-`request_user_input`-Prompts werden an den ursprünglichen Chat zurückgesendet, und die nächste in die Warteschlange gestellte Folgemeldung beantwortet diese native Serveranfrage, statt als zusätzlicher Kontext gelenkt zu werden. Andere MCP-Anforderungen schlagen weiterhin kontrolliert fehl.
Wenn das ausgewählte Modell das Codex-Harness verwendet, wird native Thread-Compaction an den
Codex-App-Server delegiert. OpenClaw behält ein Spiegel-Transkript für Kanalverlauf,
Suche, `/new`, `/reset` und zukünftiges Umschalten von Modell oder Harness. Der
Spiegel enthält den Benutzer-Prompt, den finalen Assistant-Text und leichtgewichtige Codex-
Reasoning- oder Plan-Datensätze, wenn der App-Server sie ausgibt. Heute zeichnet OpenClaw nur Signale zum Start und Abschluss nativer Compaction auf. Es stellt noch keine
menschenlesbare Compaction-Zusammenfassung oder eine auditierbare Liste bereit, welche Einträge Codex nach der Compaction behalten hat.
Wenn das ausgewählte Modell das Codex-Harness verwendet, wird die native Thread-Compaction an den Codex-App-Server delegiert. OpenClaw behält eine Spiegelung des Transkripts für Channel-Verlauf, Suche, `/new`, `/reset` und zukünftiges Umschalten von Modell oder Harness bei. Die Spiegelung enthält den Benutzer-Prompt, den endgültigen Assistant-Text und leichtgewichtige Einträge zu Codex-Reasoning oder -Plänen, wenn der App-Server diese ausgibt. Aktuell zeichnet OpenClaw nur Start- und Abschluss-Signale der nativen Compaction auf. Es stellt noch keine menschenlesbare Compaction-Zusammenfassung oder prüfbare Liste bereit, welche Einträge Codex nach der Compaction behalten hat.
Da Codex den kanonischen nativen Thread besitzt, schreibt `tool_result_persist` derzeit keine Datensätze von Ergebnissen Codex-nativer Tools um. Es gilt nur, wenn
OpenClaw ein Tool-Ergebnis in ein von OpenClaw besessenes Sitzungs-Transkript schreibt.
Da Codex den kanonischen nativen Thread besitzt, schreibt `tool_result_persist` derzeit keine nativen Tool-Ergebniseinträge von Codex um. Es gilt nur, wenn OpenClaw ein OpenClaw-eigenes Tool-Ergebnis in das Sitzungs-Transkript schreibt.
Mediengenerierung erfordert kein PI. Bild, Video, Musik, PDF, TTS und Medien-
Verständnis verwenden weiterhin die passenden Provider-/Modelleinstellungen wie
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` und
`messages.tts`.
Medienerzeugung erfordert kein Pi. Bilderzeugung, Video, Musik, PDF, TTS und Medienverständnis verwenden weiterhin die passenden Provider-/Modelleinstellungen wie `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` und `messages.tts`.
## Fehlerbehebung
**Codex erscheint nicht in `/model`:** Aktivieren Sie `plugins.entries.codex.enabled`,
wählen Sie ein Modell `openai/gpt-*` mit `embeddedHarness.runtime: "codex"` (oder eine
Legacy-Ref `codex/*`) und prüfen Sie, ob `plugins.allow` `codex` ausschließt.
**Codex erscheint nicht in `/model`:** aktivieren Sie `plugins.entries.codex.enabled`, wählen Sie ein Modell `openai/gpt-*` mit `embeddedHarness.runtime: "codex"` (oder eine veraltete Referenz `codex/*`) und prüfen Sie, ob `plugins.allow` `codex` ausschließt.
**OpenClaw verwendet PI statt Codex:** Wenn kein Codex-Harness den Lauf beansprucht,
kann OpenClaw PI als Kompatibilitäts-Backend verwenden. Setzen Sie
`embeddedHarness.runtime: "codex"`, um bei Tests die Auswahl von Codex zu erzwingen, oder
`embeddedHarness.fallback: "none"`, damit fehlgeschlagen wird, wenn kein Plugin-Harness passt. Sobald
der Codex-App-Server ausgewählt ist, werden seine Fehler direkt ohne zusätzliche
Fallback-Konfiguration ausgegeben.
**OpenClaw verwendet Pi statt Codex:** wenn kein Codex-Harness den Lauf beansprucht, kann OpenClaw Pi als Kompatibilitäts-Backend verwenden. Setzen Sie `embeddedHarness.runtime: "codex"`, um die Auswahl von Codex beim Testen zu erzwingen, oder `embeddedHarness.fallback: "none"`, damit ein Fehler auftritt, wenn kein Plugin-Harness passt. Sobald der Codex-App-Server ausgewählt ist, werden seine Fehler direkt angezeigt, ohne zusätzliche Fallback-Config.
**Der App-Server wird abgelehnt:** Aktualisieren Sie Codex, sodass der Handshake des App-Servers
Version `0.118.0` oder neuer meldet.
**Der App-Server wird abgelehnt:** aktualisieren Sie Codex, sodass der Handshake des App-Servers Version `0.118.0` oder neuer meldet.
**Modell-Discovery ist langsam:** Senken Sie `plugins.entries.codex.config.discovery.timeoutMs`
oder deaktivieren Sie Discovery.
**Die Modellerkennung ist langsam:** verringern Sie `plugins.entries.codex.config.discovery.timeoutMs` oder deaktivieren Sie die Erkennung.
**WebSocket-Transport schlägt sofort fehl:** Prüfen Sie `appServer.url`, `authToken`
und dass der Remote-App-Server dieselbe Protokollversion des Codex-App-Servers spricht.
**Der WebSocket-Transport schlägt sofort fehl:** prüfen Sie `appServer.url`, `authToken` und ob der Remote-App-Server dieselbe Protokollversion des Codex-App-Servers spricht.
**Ein Nicht-Codex-Modell verwendet PI:** Das ist zu erwarten, es sei denn, Sie haben
`embeddedHarness.runtime: "codex"` erzwungen (oder eine Legacy-Ref `codex/*` ausgewählt). Reine
`openai/gpt-*`- und andere Provider-Refs bleiben auf ihrem normalen Providerpfad.
**Ein Nicht-Codex-Modell verwendet Pi:** das ist erwartetes Verhalten, sofern Sie nicht `embeddedHarness.runtime: "codex"` erzwungen haben (oder eine veraltete Referenz `codex/*` ausgewählt wurde). Normale Referenzen `openai/gpt-*` und andere Provider-Referenzen bleiben auf ihrem normalen Provider-Pfad.
## Verwandt
- [Agent Harness Plugins](/de/plugins/sdk-agent-harness)
- [Model Providers](/de/concepts/model-providers)
- [Configuration Reference](/de/gateway/configuration-reference)
- [Testing](/de/help/testing-live#live-codex-app-server-harness-smoke)
- [Agent-Harness-Plugins](/de/plugins/sdk-agent-harness)
- [Modell-Provider](/de/concepts/model-providers)
- [Konfigurationsreferenz](/de/gateway/configuration-reference)
- [Tests](/de/help/testing-live#live-codex-app-server-harness-smoke)

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

@ -1,39 +1,39 @@
---
read_when:
- Sie möchten, dass ein OpenClaw-Agent an einem Google-Meet-Anruf teilnimmt
- Sie konfigurieren Chrome, einen Chrome-Node oder Twilio als Google-Meet-Transport
summary: 'Google-Meet-Plugin: explizite Meet-URLs über Chrome oder Twilio beitreten mit Standardwerten für Echtzeitstimme'
- Du möchtest, dass ein OpenClaw-Agent einem Google-Meet-Anruf beitritt
- Du konfigurierst Chrome, Chrome-Node oder Twilio als Google-Meet-Transport
summary: 'Google-Meet-Plugin: explizite Meet-URLs über Chrome oder Twilio mit Realtime-Voice-Standards beitreten'
title: Google-Meet-Plugin
x-i18n:
generated_at: "2026-04-24T06:49:33Z"
generated_at: "2026-04-24T08:58:53Z"
model: gpt-5.4
provider: openai
source_hash: ab439b777e3043cc647a29e8e17b2794d14f48deceaadf8f81a014dd44583e23
source_hash: 8d430a1f2d6ee7fc1d997ef388a2e0d2915a6475480343e7060edac799dfc027
source_path: plugins/google-meet.md
workflow: 15
---
# Google Meet (Plugin)
Unterstützung für Google-Meet-Teilnehmer in OpenClaw.
Google-Meet-Teilnehmerunterstützung für OpenClaw.
Das Plugin ist absichtlich explizit gestaltet:
Das Plugin ist bewusst explizit ausgelegt:
- Es tritt nur einer expliziten `https://meet.google.com/...`-URL bei.
- `realtime`-Stimme ist der Standardmodus.
- Die Echtzeitstimme kann zurück in den vollständigen OpenClaw-Agenten aufrufen, wenn tieferes
Reasoning oder Tools benötigt werden.
- `realtime` voice ist der Standardmodus.
- Realtime voice kann bei Bedarf für tiefergehendes
Reasoning oder Tools in den vollständigen OpenClaw-Agent zurückrufen.
- Die Authentifizierung beginnt mit persönlichem Google OAuth oder einem bereits angemeldeten Chrome-Profil.
- Es gibt keine automatische Einwilligungsankündigung.
- Das standardmäßige Chrome-Audio-Backend ist `BlackHole 2ch`.
- Chrome kann lokal oder auf einem gepaarten Node-Host laufen.
- Chrome kann lokal oder auf einem gekoppelten Node-Host laufen.
- Twilio akzeptiert eine Einwahlnummer plus optionale PIN oder DTMF-Sequenz.
- Der CLI-Befehl ist `googlemeet`; `meet` ist für allgemeinere Agent-
- Der CLI-Befehl lautet `googlemeet`; `meet` ist für allgemeinere Agent-
Telekonferenz-Workflows reserviert.
## Schnellstart
Installieren Sie die lokalen Audio-Abhängigkeiten und stellen Sie sicher, dass der Echtzeit-Provider
Installiere die lokalen Audio-Abhängigkeiten und stelle sicher, dass der Realtime-Provider
OpenAI verwenden kann:
```bash
@ -41,21 +41,21 @@ brew install blackhole-2ch sox
export OPENAI_API_KEY=sk-...
```
`blackhole-2ch` installiert das virtuelle Audiogerät `BlackHole 2ch`. Der Installer von Homebrew
erfordert einen Neustart, bevor macOS das Gerät bereitstellt:
`blackhole-2ch` installiert das virtuelle Audiogerät `BlackHole 2ch`. Der
Installer von Homebrew erfordert einen Neustart, bevor macOS das Gerät bereitstellt:
```bash
sudo reboot
```
Prüfen Sie nach dem Neustart beide Komponenten:
Prüfe nach dem Neustart beide Komponenten:
```bash
system_profiler SPAudioDataType | grep -i BlackHole
command -v rec play
```
Aktivieren Sie das Plugin:
Aktiviere das Plugin:
```json5
{
@ -82,7 +82,7 @@ Einem Meeting beitreten:
openclaw googlemeet join https://meet.google.com/abc-defg-hij
```
Oder einen Agenten über das Tool `google_meet` beitreten lassen:
Oder einen Agent über das Tool `google_meet` beitreten lassen:
```json
{
@ -91,67 +91,67 @@ Oder einen Agenten über das Tool `google_meet` beitreten lassen:
}
```
Chrome tritt als angemeldetes Chrome-Profil bei. Wählen Sie in Meet `BlackHole 2ch` für
den Mikrofon-/Lautsprecherpfad, den OpenClaw verwendet. Für sauberes Duplex-Audio verwenden Sie
separate virtuelle Geräte oder einen Graph im Stil von Loopback; ein einzelnes BlackHole-Gerät reicht
für einen ersten Smoke-Test, kann aber Echo verursachen.
Chrome tritt als das angemeldete Chrome-Profil bei. Wähle in Meet `BlackHole 2ch` für
den Mikrofon-/Lautsprecherpfad, den OpenClaw verwendet. Für sauberes Duplex-Audio verwende
separate virtuelle Geräte oder ein Routing im Loopback-Stil; ein einzelnes BlackHole-Gerät ist
für einen ersten Smoke-Test ausreichend, kann aber Echo erzeugen.
### Lokales Gateway + Parallels Chrome
Sie benötigen **kein** vollständiges OpenClaw Gateway oder einen Modell-API-Schlüssel innerhalb einer macOS-VM,
nur damit die VM Chrome besitzt. Führen Sie Gateway und Agent lokal aus und starten Sie dann einen
Node-Host in der VM. Aktivieren Sie das gebündelte Plugin dort einmal, damit der Node
Du benötigst **kein** vollständiges OpenClaw-Gateway oder keinen Model-API-Key innerhalb einer macOS-VM,
nur damit Chrome in der VM läuft. Führe Gateway und Agent lokal aus und betreibe dann einen
Node-Host in der VM. Aktiviere das gebündelte Plugin einmal in der VM, damit der Node
den Chrome-Befehl ankündigt:
Was läuft wo:
Was wo läuft:
- Gateway-Host: OpenClaw Gateway, Agent-Workspace, Modell-/API-Schlüssel, Realtime-
Provider und die Konfiguration des Google-Meet-Plugins.
- Gateway-Host: OpenClaw Gateway, Agent-Workspace, Model-/API-Keys, Realtime-
Provider und die Google-Meet-Plugin-Konfiguration.
- Parallels-macOS-VM: OpenClaw CLI/Node-Host, Google Chrome, SoX, BlackHole 2ch
und ein bei Google angemeldetes Chrome-Profil.
- In der VM nicht nötig: Gateway-Dienst, Agent-Konfiguration, OpenAI/GPT-Schlüssel oder
Modell-Provider-Setup.
- In der VM nicht erforderlich: Gateway-Dienst, Agent-Konfiguration, OpenAI/GPT-Key oder Model-
Provider-Setup.
Installieren Sie die VM-Abhängigkeiten:
Installiere die VM-Abhängigkeiten:
```bash
brew install blackhole-2ch sox
```
Starten Sie die VM nach der Installation von BlackHole neu, damit macOS `BlackHole 2ch` bereitstellt:
Starte die VM nach der Installation von BlackHole neu, damit macOS `BlackHole 2ch` bereitstellt:
```bash
sudo reboot
```
Prüfen Sie nach dem Neustart, ob die VM das Audiogerät und die SoX-Befehle sehen kann:
Prüfe nach dem Neustart, ob die VM das Audiogerät und die SoX-Befehle sehen kann:
```bash
system_profiler SPAudioDataType | grep -i BlackHole
command -v rec play
```
Installieren oder aktualisieren Sie OpenClaw in der VM und aktivieren Sie dort dann das gebündelte Plugin:
Installiere oder aktualisiere OpenClaw in der VM und aktiviere dann dort das gebündelte Plugin:
```bash
openclaw plugins enable google-meet
```
Starten Sie den Node-Host in der VM:
Starte den Node-Host in der VM:
```bash
openclaw node run --host <gateway-host> --port 18789 --display-name parallels-macos
```
Wenn `<gateway-host>` eine LAN-IP ist und Sie kein TLS verwenden, verweigert der Node die
Klartext-WebSocket-Verbindung, sofern Sie für dieses vertrauenswürdige private Netzwerk nicht explizit zustimmen:
Wenn `<gateway-host>` eine LAN-IP ist und du TLS nicht verwendest, verweigert der Node den
Klartext-WebSocket, sofern du nicht ausdrücklich für dieses vertrauenswürdige private Netzwerk zustimmst:
```bash
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
```
Verwenden Sie dieselbe Umgebungsvariable, wenn Sie den Node als LaunchAgent installieren:
Verwende dieselbe Umgebungsvariable, wenn du den Node als LaunchAgent installierst:
```bash
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -159,20 +159,24 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
openclaw node restart
```
Genehmigen Sie den Node vom Gateway-Host aus:
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` ist Prozessumgebung, keine
`openclaw.json`-Einstellung. `openclaw node install` speichert sie in der LaunchAgent-
Umgebung, wenn sie beim Installationsbefehl vorhanden ist.
Genehmige den Node vom Gateway-Host aus:
```bash
openclaw devices list
openclaw devices approve <requestId>
```
Bestätigen Sie, dass das Gateway den Node sieht und dass er `googlemeet.chrome` ankündigt:
Bestätige, dass das Gateway den Node sieht und dass er `googlemeet.chrome` ankündigt:
```bash
openclaw nodes status
```
Leiten Sie Meet auf diesem Node am Gateway-Host weiter:
Leite Meet auf dem Gateway-Host über diesen Node:
```json5
{
@ -197,71 +201,71 @@ Leiten Sie Meet auf diesem Node am Gateway-Host weiter:
}
```
Treten Sie jetzt wie gewohnt vom Gateway-Host aus bei:
Nun normal vom Gateway-Host aus beitreten:
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij
```
oder bitten Sie den Agenten, das Tool `google_meet` mit `transport: "chrome-node"` zu verwenden.
oder den Agent anweisen, das Tool `google_meet` mit `transport: "chrome-node"` zu verwenden.
Wenn `chromeNode.node` weggelassen wird, wählt OpenClaw nur dann automatisch aus, wenn genau ein
verbundener Node `googlemeet.chrome` ankündigt. Wenn mehrere fähige Nodes
verbunden sind, setzen Sie `chromeNode.node` auf die Node-ID, den Anzeigenamen oder die Remote-IP.
Wenn `chromeNode.node` ausgelassen wird, wählt OpenClaw nur dann automatisch aus, wenn genau ein
verbundener Node `googlemeet.chrome` ankündigt. Wenn mehrere geeignete Nodes
verbunden sind, setze `chromeNode.node` auf die Node-ID, den Anzeigenamen oder die Remote-IP.
Häufige Prüfungen bei Fehlern:
- `No connected Google Meet-capable node`: Starten Sie `openclaw node run` in der VM,
genehmigen Sie das Pairing und stellen Sie sicher, dass `openclaw plugins enable google-meet` in der VM ausgeführt wurde.
Bestätigen Sie außerdem, dass der Gateway-Host den Node-Befehl mit
- `No connected Google Meet-capable node`: Starte `openclaw node run` in der VM,
genehmige das Pairing und stelle sicher, dass `openclaw plugins enable google-meet` in
der VM ausgeführt wurde. Bestätige außerdem, dass der Gateway-Host den Node-Befehl mit
`gateway.nodes.allowCommands: ["googlemeet.chrome"]` erlaubt.
- `BlackHole 2ch audio device not found on the node`: Installieren Sie `blackhole-2ch`
in der VM und starten Sie die VM neu.
- Chrome öffnet sich, kann aber nicht beitreten: Melden Sie sich in Chrome innerhalb der VM an und bestätigen Sie, dass dieses
- `BlackHole 2ch audio device not found on the node`: Installiere `blackhole-2ch`
in der VM und starte die VM neu.
- Chrome öffnet sich, kann aber nicht beitreten: Melde dich in Chrome innerhalb der VM an und bestätige, dass dieses
Profil der Meet-URL manuell beitreten kann.
- Kein Audio: Leiten Sie Mikrofon/Lautsprecher in Meet über den virtuellen Audiopfad,
den OpenClaw verwendet; verwenden Sie separate virtuelle Geräte oder Routing im Stil von Loopback
- Kein Audio: Route in Meet Mikrofon/Lautsprecher über den virtuellen Audiogerätepfad,
den OpenClaw verwendet; verwende separate virtuelle Geräte oder Routing im Loopback-Stil
für sauberes Duplex-Audio.
## Hinweise zur Installation
Der Standardpfad für Chrome Realtime verwendet zwei externe Tools:
Der standardmäßige Chrome-Realtime-Pfad verwendet zwei externe Tools:
- `sox`: Kommandozeilen-Audio-Utility. Das Plugin verwendet dessen Befehle `rec` und `play`
- `sox`: Kommandozeilen-Audio-Tool. Das Plugin verwendet seine Befehle `rec` und `play`
für die standardmäßige 8-kHz-G.711-mu-law-Audiobrücke.
- `blackhole-2ch`: virtueller Audiotreiber für macOS. Er erstellt das Audiogerät `BlackHole 2ch`,
über das Chrome/Meet geroutet werden kann.
über das Chrome/Meet routen kann.
OpenClaw bündelt oder verteilt keines der beiden Pakete weiter. Die Dokumentation fordert Benutzer auf,
sie als Host-Abhängigkeiten über Homebrew zu installieren. SoX ist lizenziert als
`LGPL-2.0-only AND GPL-2.0-only`; BlackHole steht unter GPL-3.0. Wenn Sie einen
Installer oder eine Appliance bauen, die BlackHole mit OpenClaw bündelt, prüfen Sie die
Lizenzbedingungen von BlackHole upstream oder holen Sie sich eine separate Lizenz von Existential Audio.
sie als Host-Abhängigkeiten über Homebrew zu installieren. SoX ist unter
`LGPL-2.0-only AND GPL-2.0-only` lizenziert; BlackHole ist GPL-3.0. Wenn du einen
Installer oder eine Appliance baust, die BlackHole mit OpenClaw bündelt, prüfe die
upstream-Lizenzbedingungen von BlackHole oder hole eine separate Lizenz von Existential Audio ein.
## Transporte
## Transports
### Chrome
Der Chrome-Transport öffnet die Meet-URL in Google Chrome und tritt mit dem angemeldeten
Chrome-Profil bei. Auf macOS prüft das Plugin vor dem Start auf `BlackHole 2ch`.
Wenn konfiguriert, führt es außerdem einen Audio-Bridge-Health-Befehl und einen Startbefehl
aus, bevor Chrome geöffnet wird. Verwenden Sie `chrome`, wenn Chrome/Audio auf dem Gateway-Host laufen;
verwenden Sie `chrome-node`, wenn Chrome/Audio auf einem gepaarten Node wie einer Parallels-
macOS-VM laufen.
Der Chrome-Transport öffnet die Meet-URL in Google Chrome und tritt als das angemeldete
Chrome-Profil bei. Unter macOS prüft das Plugin vor dem Start auf `BlackHole 2ch`.
Falls konfiguriert, führt es außerdem einen Health-Befehl für die Audiobrücke und einen Startbefehl
aus, bevor Chrome geöffnet wird. Verwende `chrome`, wenn Chrome/Audio auf dem Gateway-Host laufen;
verwende `chrome-node`, wenn Chrome/Audio auf einem gekoppelten Node laufen, etwa in einer Parallels-
macOS-VM.
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome
openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node
```
Leiten Sie Chrome-Mikrofon- und Lautsprecheraudio über die lokale OpenClaw-Audio-
Bridge. Wenn `BlackHole 2ch` nicht installiert ist, schlägt der Beitritt mit einem Setup-Fehler
Leite Mikrofon- und Lautsprecheraudio von Chrome über die lokale OpenClaw-Audiobrücke.
Wenn `BlackHole 2ch` nicht installiert ist, schlägt der Beitritt mit einem Setup-Fehler
fehl, statt stillschweigend ohne Audiopfad beizutreten.
### Twilio
Der Twilio-Transport ist ein strikter Wählplan, der an das Voice-Call-Plugin delegiert wird. Er
parst Meet-Seiten nicht nach Telefonnummern.
parst keine Meet-Seiten nach Telefonnummern.
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -270,7 +274,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \
--pin 123456
```
Verwenden Sie `--dtmf-sequence`, wenn das Meeting eine benutzerdefinierte Sequenz benötigt:
Verwende `--dtmf-sequence`, wenn das Meeting eine benutzerdefinierte Sequenz benötigt:
```bash
openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -281,16 +285,16 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \
## OAuth und Preflight
Der Zugriff auf die Google Meet Media API verwendet zuerst einen persönlichen OAuth-Client. Konfigurieren Sie
`oauth.clientId` und optional `oauth.clientSecret`, und führen Sie dann aus:
Der Zugriff auf die Google-Meet-Media-API verwendet zunächst einen persönlichen OAuth-Client. Konfiguriere
`oauth.clientId` und optional `oauth.clientSecret`, und führe dann Folgendes aus:
```bash
openclaw googlemeet auth login --json
```
Der Befehl gibt einen `oauth`-Konfigurationsblock mit einem Refresh-Token aus. Er verwendet PKCE,
einen Localhost-Callback unter `http://localhost:8085/oauth2callback` und einen manuellen
Copy/Paste-Flow mit `--manual`.
einen localhost-Callback auf `http://localhost:8085/oauth2callback` und einen manuellen
Copy/Paste-Ablauf mit `--manual`.
Diese Umgebungsvariablen werden als Fallback akzeptiert:
@ -303,32 +307,33 @@ Diese Umgebungsvariablen werden als Fallback akzeptiert:
- `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` oder `GOOGLE_MEET_DEFAULT_MEETING`
- `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` oder `GOOGLE_MEET_PREVIEW_ACK`
Lösen Sie eine Meet-URL, einen Code oder `spaces/{id}` über `spaces.get` auf:
Löse eine Meet-URL, einen Code oder `spaces/{id}` über `spaces.get` auf:
```bash
openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
```
Führen Sie Preflight vor Medienarbeit aus:
Führe Preflight vor der Medienarbeit aus:
```bash
openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij
```
Setzen Sie `preview.enrollmentAcknowledged: true` erst, nachdem Sie bestätigt haben, dass Ihr Cloud-
Projekt, OAuth-Principal und die Meeting-Teilnehmer im Google Workspace Developer Preview Program für Meet-Media-APIs angemeldet sind.
Setze `preview.enrollmentAcknowledged: true` erst, nachdem du bestätigt hast, dass dein Cloud-
Projekt, OAuth-Prinzipal und Meeting-Teilnehmer im Google Workspace Developer Preview Program
für Meet-Media-APIs registriert sind.
## Konfiguration
Der gemeinsame Chrome-Realtime-Pfad benötigt nur das aktivierte Plugin, BlackHole, SoX
und einen OpenAI-Schlüssel:
Der gängige Chrome-Realtime-Pfad benötigt nur das aktivierte Plugin, BlackHole, SoX
und einen OpenAI-Key:
```bash
brew install blackhole-2ch sox
export OPENAI_API_KEY=sk-...
```
Setzen Sie die Plugin-Konfiguration unter `plugins.entries.google-meet.config`:
Setze die Plugin-Konfiguration unter `plugins.entries.google-meet.config`:
```json5
{
@ -343,20 +348,22 @@ Setzen Sie die Plugin-Konfiguration unter `plugins.entries.google-meet.config`:
}
```
Standards:
Standardwerte:
- `defaultTransport: "chrome"`
- `defaultMode: "realtime"`
- `chromeNode.node`: optionale Node-ID/-Name/-IP für `chrome-node`
- `chromeNode.node`: optionale Node-ID/Name/IP für `chrome-node`
- `chrome.audioBackend: "blackhole-2ch"`
- `chrome.audioInputCommand`: SoX-`rec`-Befehl, der 8-kHz-G.711-mu-law-
Audio nach stdout schreibt
Audio an stdout schreibt
- `chrome.audioOutputCommand`: SoX-`play`-Befehl, der 8-kHz-G.711-mu-law-
Audio von stdin liest
- `realtime.provider: "openai"`
- `realtime.toolPolicy: "safe-read-only"`
- `realtime.instructions`: kurze gesprochene Antworten, mit
`openclaw_agent_consult` für tiefere Antworten
`openclaw_agent_consult` für tiefergehende Antworten
- `realtime.introMessage`: kurze gesprochene Bereitschaftsprüfung, wenn die Realtime-Brücke
verbunden wird; setze sie auf `""`, um lautlos beizutreten
Optionale Overrides:
@ -373,6 +380,7 @@ Optionale Overrides:
},
realtime: {
toolPolicy: "owner",
introMessage: "Say exactly: I'm here.",
},
}
```
@ -405,59 +413,74 @@ Agenten können das Tool `google_meet` verwenden:
}
```
Verwenden Sie `transport: "chrome"`, wenn Chrome auf dem Gateway-Host läuft. Verwenden Sie
`transport: "chrome-node"`, wenn Chrome auf einem gepaarten Node wie einer Parallels-
VM läuft. In beiden Fällen laufen das Realtime-Modell und `openclaw_agent_consult` auf dem
Gateway-Host, sodass Modell-Anmeldedaten dort bleiben.
Verwende `transport: "chrome"`, wenn Chrome auf dem Gateway-Host läuft. Verwende
`transport: "chrome-node"`, wenn Chrome auf einem gekoppelten Node läuft, etwa in einer Parallels-
VM. In beiden Fällen laufen das Realtime-Modell und `openclaw_agent_consult` auf dem
Gateway-Host, sodass die Model-Credentials dort bleiben.
Verwenden Sie `action: "status"`, um aktive Sitzungen aufzulisten oder eine Sitzungs-ID zu prüfen. Verwenden Sie
`action: "leave"`, um eine Sitzung als beendet zu markieren.
Verwende `action: "status"`, um aktive Sitzungen aufzulisten oder eine Sitzungs-ID zu prüfen. Verwende
`action: "speak"` mit `sessionId` und `message`, damit der Realtime-Agent
sofort spricht. Verwende `action: "leave"`, um eine Sitzung als beendet zu markieren.
```json
{
"action": "speak",
"sessionId": "meet_...",
"message": "Say exactly: I'm here and listening."
}
```
## Realtime-Agent-Consult
Der Chrome-Realtime-Modus ist für einen Live-Sprach-Loop optimiert. Der Realtime-Sprach-
Der Chrome-Realtime-Modus ist für eine Live-Sprachschleife optimiert. Der Realtime-Voice-
Provider hört das Meeting-Audio und spricht über die konfigurierte Audiobrücke.
Wenn das Realtime-Modell tieferes Reasoning, aktuelle Informationen oder normale
Wenn das Realtime-Modell tiefergehendes Reasoning, aktuelle Informationen oder normale
OpenClaw-Tools benötigt, kann es `openclaw_agent_consult` aufrufen.
Das Consult-Tool führt im Hintergrund den regulären OpenClaw-Agenten mit aktuellem
Das Consult-Tool führt im Hintergrund den regulären OpenClaw-Agent mit aktuellem
Meeting-Transkriptkontext aus und gibt eine knappe gesprochene Antwort an die Realtime-
Sprachsitzung zurück. Das Sprachmodell kann diese Antwort dann in das Meeting sprechen.
Voice-Sitzung zurück. Das Voice-Modell kann diese Antwort dann in das Meeting zurücksprechen.
`realtime.toolPolicy` steuert den Consult-Lauf:
- `safe-read-only`: das Consult-Tool verfügbar machen und den regulären Agenten auf
- `safe-read-only`: das Consult-Tool verfügbar machen und den regulären Agent auf
`read`, `web_search`, `web_fetch`, `x_search`, `memory_search` und
`memory_get` begrenzen.
- `owner`: das Consult-Tool verfügbar machen und dem regulären Agenten die normale
Tool-Richtlinie des Agenten erlauben.
- `none`: das Consult-Tool dem Realtime-Sprachmodell nicht bereitstellen.
`memory_get` beschränken.
- `owner`: das Consult-Tool verfügbar machen und dem regulären Agent die normale
Tool-Richtlinie des Agent erlauben.
- `none`: das Consult-Tool dem Realtime-Voice-Modell nicht verfügbar machen.
Der Sitzungsschlüssel für Consult ist pro Meet-Sitzung begrenzt, sodass nachfolgende Consult-Aufrufe
während desselben Meetings den vorherigen Consult-Kontext wiederverwenden können.
Der Consult-Sitzungsschlüssel ist pro Meet-Sitzung begrenzt, sodass nachfolgende Consult-Aufrufe
während desselben Meetings vorherigen Consult-Kontext wiederverwenden können.
Um eine gesprochene Bereitschaftsprüfung zu erzwingen, nachdem Chrome dem Anruf vollständig beigetreten ist:
```bash
openclaw googlemeet speak meet_... "Say exactly: I'm here and listening."
```
## Hinweise
Die offizielle Media API von Google Meet ist auf Empfang ausgerichtet, daher erfordert das Sprechen in einen Meet-
Anruf weiterhin einen Teilnehmerpfad. Dieses Plugin hält diese Grenze sichtbar:
Chrome übernimmt Browser-Teilnahme und lokales Audio-Routing; Twilio übernimmt
Die offizielle Media-API von Google Meet ist auf Empfang ausgerichtet, daher benötigt das Sprechen in einen Meet-
Anruf weiterhin einen Teilnehmerpfad. Dieses Plugin macht diese Grenze sichtbar:
Chrome übernimmt die Browser-Teilnahme und das lokale Audio-Routing; Twilio übernimmt
die Teilnahme per Telefoneinwahl.
Der Chrome-Realtime-Modus benötigt entweder:
- `chrome.audioInputCommand` plus `chrome.audioOutputCommand`: OpenClaw besitzt die
Brücke zum Realtime-Modell und leitet 8-kHz-G.711-mu-law-Audio zwischen diesen
Befehlen und dem ausgewählten Realtime-Sprachprovider weiter.
- `chrome.audioBridgeCommand`: Ein externer Bridge-Befehl besitzt den gesamten lokalen
Audiopfad und muss nach dem Starten oder Validieren seines Daemons beendet werden.
Realtime-Model-Brücke und leitet 8-kHz-G.711-mu-law-Audio zwischen diesen
Befehlen und dem ausgewählten Realtime-Voice-Provider weiter.
- `chrome.audioBridgeCommand`: ein externer Brückenbefehl übernimmt den gesamten lokalen
Audiopfad und muss beendet werden, nachdem sein Daemon gestartet oder validiert wurde.
Für sauberes Duplex-Audio leiten Sie Meet-Ausgabe und Meet-Mikrofon über separate
virtuelle Geräte oder einen Graph für virtuelle Geräte im Stil von Loopback. Ein einzelnes gemeinsam genutztes
Für sauberes Duplex-Audio leite Meet-Ausgabe und Meet-Mikrofon über separate
virtuelle Geräte oder ein virtuelles Gerätegraphrouting im Loopback-Stil. Ein einzelnes gemeinsam genutztes
BlackHole-Gerät kann andere Teilnehmer zurück in den Anruf echoen.
`googlemeet leave` stoppt die kommandogepaarten Realtime-Audiobrücken für Chrome-
Sitzungen. Für Twilio-Sitzungen, die über das Voice-Call-Plugin delegiert werden, wird außerdem
der zugrunde liegende Sprach-Anruf aufgelegt.
`googlemeet speak` löst die aktive Realtime-Audiobrücke für eine Chrome-
Sitzung aus. `googlemeet leave` stoppt diese Brücke. Bei Twilio-Sitzungen, die über das Voice-Call-Plugin
delegiert werden, legt `leave` auch den zugrunde liegenden Sprachanruf auf.
## Verwandt

538
docs/de/plugins/manifest.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Sie entwickeln ein OpenClaw-Plugin
- Sie müssen ein Plugin-Konfigurationsschema bereitstellen oder Plugin-Validierungsfehler debuggen
summary: Plugin-Manifest- + JSON-Schema-Anforderungen (strikte Konfigurationsvalidierung)
- Sie erstellen ein OpenClaw-Plugin.
- Sie müssen ein Plugin-Konfigurationsschema bereitstellen oder Plugin-Validierungsfehler debuggen.
summary: Plugin-Manifest + JSON-Schema-Anforderungen (strikte Konfigurationsvalidierung)
title: Plugin-Manifest
x-i18n:
generated_at: "2026-04-24T06:49:39Z"
generated_at: "2026-04-24T08:59:36Z"
model: gpt-5.4
provider: openai
source_hash: d27765f1efc9720bd68c73d3ede796a91e9afec479f89eda531dd14adc708e53
source_hash: e680a978c4f0bc8fec099462a6e08585f39dfd72e0c159ecfe5162586e7d7258
source_path: plugins/manifest.md
workflow: 15
---
@ -20,45 +20,45 @@ Für kompatible Bundle-Layouts siehe [Plugin bundles](/de/plugins/bundles).
Kompatible Bundle-Formate verwenden andere Manifestdateien:
- Codex-Bundle: `.codex-plugin/plugin.json`
- Claude-Bundle: `.claude-plugin/plugin.json` oder das Standard-Layout von Claude-Komponenten
- Claude-Bundle: `.claude-plugin/plugin.json` oder das Standard-Layout für Claude-Komponenten
ohne Manifest
- Cursor-Bundle: `.cursor-plugin/plugin.json`
OpenClaw erkennt diese Bundle-Layouts ebenfalls automatisch, sie werden jedoch nicht
gegen das hier beschriebene Schema `openclaw.plugin.json` validiert.
OpenClaw erkennt diese Bundle-Layouts ebenfalls automatisch, aber sie werden nicht
gegen das hier beschriebene Schema für `openclaw.plugin.json` validiert.
Für kompatible Bundles liest OpenClaw derzeit Bundle-Metadaten plus deklarierte
Skill-Roots, Claude-Command-Roots, Standardwerte aus `settings.json` von Claude-Bundles,
LSP-Standardwerte von Claude-Bundles und unterstützte Hook-Packs, wenn das Layout
den Laufzeiterwartungen von OpenClaw entspricht.
LSP-Standardwerte von Claude-Bundles und unterstützte Hook-Packs, wenn das Layout den
Laufzeiterwartungen von OpenClaw entspricht.
Jedes native OpenClaw-Plugin **muss** eine Datei `openclaw.plugin.json` im
**Plugin-Root** mitliefern. OpenClaw verwendet dieses Manifest, um Konfigurationen zu validieren,
**ohne Plugin-Code auszuführen**. Fehlende oder ungültige Manifeste werden als
**Plugin-Root** bereitstellen. OpenClaw verwendet dieses Manifest, um die Konfiguration
**ohne Ausführung von Plugin-Code** zu validieren. Fehlende oder ungültige Manifeste werden als
Plugin-Fehler behandelt und blockieren die Konfigurationsvalidierung.
Siehe die vollständige Anleitung zum Plugin-System: [Plugins](/de/tools/plugin).
Für das native Fähigkeitsmodell und die aktuelle Anleitung zur externen Kompatibilität:
Für das native Capability-Modell und die aktuelle Anleitung zur externen Kompatibilität:
[Capability model](/de/plugins/architecture#public-capability-model).
## Was diese Datei macht
## Wozu diese Datei dient
`openclaw.plugin.json` sind die Metadaten, die OpenClaw liest, **bevor Ihr
Plugin-Code geladen wird**. Alles darunter muss günstig genug zu prüfen sein, ohne die
`openclaw.plugin.json` sind die Metadaten, die OpenClaw liest, **bevor es Ihren
Plugin-Code lädt**. Alles unten muss günstig genug sein, um es zu prüfen, ohne die
Plugin-Laufzeit zu starten.
**Verwenden Sie sie für:**
- Plugin-Identität, Konfigurationsvalidierung und Hinweise für die Konfigurations-UI
- Metadaten für Authentifizierung, Onboarding und Einrichtung (Alias, automatische Aktivierung, Provider-Umgebungsvariablen, Auth-Auswahl)
- Plugin-Identität, Konfigurationsvalidierung und UI-Hinweise für die Konfiguration
- Metadaten für Auth, Onboarding und Setup (Alias, automatische Aktivierung, Provider-Umgebungsvariablen, Auth-Auswahl)
- Aktivierungshinweise für Oberflächen der Control Plane
- Kurzformen für Besitz von Modellfamilien
- statische Snapshots zum Besitz von Fähigkeiten (`contracts`)
- Kurzform-Ownership für Modellfamilien
- statische Snapshots der Capability-Ownership (`contracts`)
- QA-Runner-Metadaten, die der gemeinsame Host `openclaw qa` prüfen kann
- kanalspezifische Konfigurationsmetadaten, die in Katalog- und Validierungsoberflächen zusammengeführt werden
- channelspezifische Konfigurationsmetadaten, die in Katalog- und Validierungsoberflächen zusammengeführt werden
**Verwenden Sie sie nicht für:** Registrierung von Laufzeitverhalten, Deklaration von
Code-Entry-Points oder npm-Installationsmetadaten. Diese gehören in Ihren Plugin-Code und in `package.json`.
**Verwenden Sie sie nicht für:** Registrierung von Laufzeitverhalten, Deklaration von Code-Einstiegspunkten
oder npm-Installationsmetadaten. Diese gehören in Ihren Plugin-Code und in `package.json`.
## Minimales Beispiel
@ -73,13 +73,13 @@ Code-Entry-Points oder npm-Installationsmetadaten. Diese gehören in Ihren Plugi
}
```
## Umfangreicheres Beispiel
## Umfangreiches Beispiel
```json
{
"id": "openrouter",
"name": "OpenRouter",
"description": "OpenRouter provider plugin",
"description": "OpenRouter-Provider-Plugin",
"version": "1.0.0",
"providers": ["openrouter"],
"modelSupport": {
@ -107,13 +107,13 @@ Code-Entry-Points oder npm-Installationsmetadaten. Diese gehören in Ihren Plugi
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
"choiceLabel": "OpenRouter API-Schlüssel",
"choiceLabel": "OpenRouter-API-Schlüssel",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key <key>",
"cliDescription": "OpenRouter API-Schlüssel",
"cliDescription": "OpenRouter-API-Schlüssel",
"onboardingScopes": ["text-inference"]
}
],
@ -136,69 +136,69 @@ Code-Entry-Points oder npm-Installationsmetadaten. Diese gehören in Ihren Plugi
}
```
## Referenz der Top-Level-Felder
## Referenz der Felder auf oberster Ebene
| Feld | Erforderlich | Typ | Bedeutung |
| ------------------------------------ | ------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Ja | `string` | Kanonische Plugin-ID. Dies ist die ID, die in `plugins.entries.<id>` verwendet wird. |
| `id` | Ja | `string` | Kanonische Plugin-ID. Dies ist die ID, die in `plugins.entries.<id>` verwendet wird. |
| `configSchema` | Ja | `object` | Inline-JSON-Schema für die Konfiguration dieses Plugins. |
| `enabledByDefault` | Nein | `true` | Markiert ein gebündeltes Plugin als standardmäßig aktiviert. Lassen Sie es weg oder setzen Sie einen beliebigen Wert ungleich `true`, um das Plugin standardmäßig deaktiviert zu lassen. |
| `legacyPluginIds` | Nein | `string[]` | Veraltete IDs, die auf diese kanonische Plugin-ID normalisiert werden. |
| `autoEnableWhenConfiguredProviders` | Nein | `string[]` | Provider-IDs, die dieses Plugin automatisch aktivieren sollen, wenn Authentifizierung, Konfiguration oder Modellreferenzen sie erwähnen. |
| `enabledByDefault` | Nein | `true` | Markiert ein gebündeltes Plugin als standardmäßig aktiviert. Lassen Sie das Feld weg oder setzen Sie einen beliebigen Wert ungleich `true`, damit das Plugin standardmäßig deaktiviert bleibt. |
| `legacyPluginIds` | Nein | `string[]` | Legacy-IDs, die auf diese kanonische Plugin-ID normalisiert werden. |
| `autoEnableWhenConfiguredProviders` | Nein | `string[]` | Provider-IDs, die dieses Plugin automatisch aktivieren sollen, wenn Auth, Konfiguration oder Modellreferenzen sie erwähnen. |
| `kind` | Nein | `"memory"` \| `"context-engine"` | Deklariert eine exklusive Plugin-Art, die von `plugins.slots.*` verwendet wird. |
| `channels` | Nein | `string[]` | Kanal-IDs, die diesem Plugin gehören. Werden für Discovery und Konfigurationsvalidierung verwendet. |
| `providers` | Nein | `string[]` | Provider-IDs, die diesem Plugin gehören. |
| `providerDiscoveryEntry` | Nein | `string` | Pfad zu einem schlanken Provider-Discovery-Modul relativ zum Plugin-Root für manifestgebundene Provider-Katalogmetadaten, die ohne Aktivierung der vollständigen Plugin-Laufzeit geladen werden können. |
| `modelSupport` | Nein | `object` | Manifest-eigene Kurzmetadaten zu Modellfamilien, die verwendet werden, um das Plugin vor der Laufzeit automatisch zu laden. |
| `providerEndpoints` | Nein | `object[]` | Manifest-eigene Metadaten zu Endpoint-Host/baseUrl für Provider-Routen, die der Core klassifizieren muss, bevor die Provider-Laufzeit geladen wird. |
| `cliBackends` | Nein | `string[]` | CLI-Inferenz-Backend-IDs, die diesem Plugin gehören. Werden für automatische Aktivierung beim Start aus expliziten Konfigurationsreferenzen verwendet. |
| `syntheticAuthRefs` | Nein | `string[]` | Provider- oder CLI-Backend-Referenzen, deren plugin-eigener Synthetic-Auth-Hook während kalter Modell-Discovery vor dem Laden der Laufzeit geprüft werden soll. |
| `nonSecretAuthMarkers` | Nein | `string[]` | Platzhalterwerte für API-Schlüssel, die gebündelten Plugins gehören und einen nicht geheimen lokalen, OAuth- oder Ambient-Credential-Zustand darstellen. |
| `commandAliases` | Nein | `object[]` | Befehlsnamen, die diesem Plugin gehören und pluginbewusste Konfigurations- und CLI-Diagnosen erzeugen sollen, bevor die Laufzeit geladen wird. |
| `providerAuthEnvVars` | Nein | `Record<string, string[]>` | Günstige Metadaten zu Provider-Auth-Umgebungsvariablen, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. |
| `providerAuthAliases` | Nein | `Record<string, string>` | Provider-IDs, die für die Authentifizierung eine andere Provider-ID wiederverwenden sollen, zum Beispiel ein Coding-Provider, der denselben API-Schlüssel und dieselben Auth-Profile wie der Basis-Provider teilt. |
| `channelEnvVars` | Nein | `Record<string, string[]>` | Günstige Metadaten zu Kanal-Umgebungsvariablen, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. Verwenden Sie dies für env-gesteuerte Kanaleinrichtung oder Auth-Oberflächen, die generische Start-/Konfigurationshelfer sehen sollen. |
| `providerAuthChoices` | Nein | `object[]` | Günstige Metadaten für Auth-Auswahl in Onboarding-Pickern, bevorzugte Provider-Auflösung und einfache CLI-Flag-Verdrahtung. |
| `activation` | Nein | `object` | Günstige Metadaten für den Aktivierungsplaner bei provider-, befehls-, kanal-, routen- und fähigkeitsgetriggertem Laden. Nur Metadaten; das tatsächliche Verhalten gehört weiterhin der Plugin-Laufzeit. |
| `setup` | Nein | `object` | Günstige Setup-/Onboarding-Beschreibungen, die Discovery- und Setup-Oberflächen prüfen können, ohne die Plugin-Laufzeit zu laden. |
| `qaRunners` | Nein | `object[]` | Günstige Beschreibungen für QA-Runner, die vom gemeinsamen Host `openclaw qa` verwendet werden, bevor die Plugin-Laufzeit geladen wird. |
| `contracts` | Nein | `object` | Statischer Snapshot gebündelter Fähigkeiten für externe Auth-Hooks, Sprache, Echtzeit-Transkription, Echtzeit-Stimme, Media Understanding, Bildgenerierung, Musikgenerierung, Videogenerierung, Web-Fetch, Websuche und Tool-Besitz. |
| `mediaUnderstandingProviderMetadata` | Nein | `Record<string, object>` | Günstige Standardwerte für Media Understanding für Provider-IDs, die in `contracts.mediaUnderstandingProviders` deklariert sind. |
| `channelConfigs` | Nein | `Record<string, object>` | Manifest-eigene Metadaten zur Kanalkonfiguration, die in Discovery- und Validierungsoberflächen zusammengeführt werden, bevor die Laufzeit geladen wird. |
| `skills` | Nein | `string[]` | Zu ladende Skill-Verzeichnisse relativ zum Plugin-Root. |
| `name` | Nein | `string` | Menschenlesbarer Plugin-Name. |
| `description` | Nein | `string` | Kurze Zusammenfassung, die in Plugin-Oberflächen angezeigt wird. |
| `version` | Nein | `string` | Informative Plugin-Version. |
| `uiHints` | Nein | `Record<string, object>` | UI-Labels, Platzhalter und Hinweise auf Sensitivität für Konfigurationsfelder. |
| `channels` | Nein | `string[]` | Channel-IDs, die diesem Plugin gehören. Verwendet für Discovery und Konfigurationsvalidierung. |
| `providers` | Nein | `string[]` | Provider-IDs, die diesem Plugin gehören. |
| `providerDiscoveryEntry` | Nein | `string` | Leichtgewichtiger Modulpfad für Provider-Discovery, relativ zum Plugin-Root, für manifestgebundene Provider-Katalogmetadaten, die geladen werden können, ohne die vollständige Plugin-Laufzeit zu aktivieren. |
| `modelSupport` | Nein | `object` | Manifestgebundene Kurzform-Metadaten für Modellfamilien, die verwendet werden, um das Plugin vor der Laufzeit automatisch zu laden. |
| `providerEndpoints` | Nein | `object[]` | Manifestgebundene Metadaten zu Endpoint-Hosts/baseUrl für Provider-Routen, die vom Core klassifiziert werden müssen, bevor die Provider-Laufzeit geladen wird. |
| `cliBackends` | Nein | `string[]` | CLI-Inferenz-Backend-IDs, die diesem Plugin gehören. Verwendet für die automatische Aktivierung beim Start aus expliziten Konfigurationsreferenzen. |
| `syntheticAuthRefs` | Nein | `string[]` | Provider- oder CLI-Backend-Referenzen, deren plugin-eigener synthetischer Auth-Hook während kalter Modellentdeckung vor dem Laden der Laufzeit geprüft werden soll. |
| `nonSecretAuthMarkers` | Nein | `string[]` | Platzhalterwerte für API-Schlüssel, die gebündelten Plugins gehören und einen nicht geheimen lokalen, OAuth- oder Umgebungs-Credential-Zustand darstellen. |
| `commandAliases` | Nein | `object[]` | Befehlsnamen, die diesem Plugin gehören und vor dem Laden der Laufzeit pluginbewusste Konfigurations- und CLI-Diagnosen erzeugen sollen. |
| `providerAuthEnvVars` | Nein | `Record<string, string[]>` | Kostengünstige Metadaten zu Provider-Auth-Umgebungsvariablen, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. |
| `providerAuthAliases` | Nein | `Record<string, string>` | Provider-IDs, die für Auth-Lookup eine andere Provider-ID wiederverwenden sollen, zum Beispiel ein Coding-Provider, der denselben API-Schlüssel und dieselben Auth-Profile wie der Basis-Provider nutzt. |
| `channelEnvVars` | Nein | `Record<string, string[]>` | Kostengünstige Metadaten zu Channel-Umgebungsvariablen, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. Verwenden Sie dies für env-gesteuertes Channel-Setup oder Auth-Oberflächen, die generische Start-/Konfigurationshelfer sehen sollen. |
| `providerAuthChoices` | Nein | `object[]` | Kostengünstige Metadaten für Auth-Auswahlen für Onboarding-Picker, Auflösung bevorzugter Provider und einfache Verdrahtung von CLI-Flags. |
| `activation` | Nein | `object` | Kostengünstige Metadaten des Aktivierungsplaners für provider-, befehls-, channel-, routen- und capability-ausgelöstes Laden. Nur Metadaten; tatsächliches Verhalten bleibt Eigentum der Plugin-Laufzeit. |
| `setup` | Nein | `object` | Kostengünstige Setup-/Onboarding-Deskriptoren, die Discovery- und Setup-Oberflächen prüfen können, ohne die Plugin-Laufzeit zu laden. |
| `qaRunners` | Nein | `object[]` | Kostengünstige QA-Runner-Deskriptoren, die vom gemeinsamen Host `openclaw qa` verwendet werden, bevor die Plugin-Laufzeit geladen wird. |
| `contracts` | Nein | `object` | Statischer Snapshot gebündelter Capabilities für externe Auth-Hooks, Sprache, Echtzeit-Transkription, Echtzeit-Stimme, Medienverständnis, Bildgenerierung, Musikgenerierung, Videogenerierung, Web-Abruf, Websuche und Tool-Ownership. |
| `mediaUnderstandingProviderMetadata` | Nein | `Record<string, object>` | Kostengünstige Standardwerte für Medienverständnis für Provider-IDs, die in `contracts.mediaUnderstandingProviders` deklariert sind. |
| `channelConfigs` | Nein | `Record<string, object>` | Manifestgebundene Channel-Konfigurationsmetadaten, die vor dem Laden der Laufzeit in Discovery- und Validierungsoberflächen zusammengeführt werden. |
| `skills` | Nein | `string[]` | Skill-Verzeichnisse, relativ zum Plugin-Root, die geladen werden sollen. |
| `name` | Nein | `string` | Menschenlesbarer Plugin-Name. |
| `description` | Nein | `string` | Kurze Zusammenfassung, die in Plugin-Oberflächen angezeigt wird. |
| `version` | Nein | `string` | Informative Plugin-Version. |
| `uiHints` | Nein | `Record<string, object>` | UI-Labels, Platzhalter und Sensitivitätshinweise für Konfigurationsfelder. |
## Referenz für `providerAuthChoices`
Jeder Eintrag in `providerAuthChoices` beschreibt eine Onboarding- oder Auth-Auswahl.
Jeder Eintrag in `providerAuthChoices` beschreibt eine einzelne Onboarding- oder Auth-Auswahl.
OpenClaw liest dies, bevor die Provider-Laufzeit geladen wird.
| Feld | Erforderlich | Typ | Bedeutung |
| --------------------- | ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `provider` | Ja | `string` | Provider-ID, zu der diese Auswahl gehört. |
| `method` | Ja | `string` | ID der Auth-Methode, an die weitergeleitet werden soll. |
| `choiceId` | Ja | `string` | Stabile Auth-Choice-ID, die von Onboarding- und CLI-Abläufen verwendet wird. |
| `choiceLabel` | Nein | `string` | Benutzerseitiges Label. Wenn ausgelassen, greift OpenClaw auf `choiceId` zurück. |
| `choiceHint` | Nein | `string` | Kurzer Hilfetext für den Picker. |
| `assistantPriority` | Nein | `number` | Kleinere Werte werden in assistentengesteuerten interaktiven Pickern früher sortiert. |
| `assistantVisibility` | Nein | `"visible"` \| `"manual-only"` | Verbirgt die Auswahl in Assistenten-Pickern, erlaubt aber weiterhin manuelle CLI-Auswahl. |
| `deprecatedChoiceIds` | Nein | `string[]` | Veraltete Choice-IDs, die Benutzer zu dieser Ersatz-Auswahl umleiten sollen. |
| `groupId` | Nein | `string` | Optionale Gruppen-ID zum Gruppieren verwandter Auswahlmöglichkeiten. |
| `groupLabel` | Nein | `string` | Benutzerseitiges Label für diese Gruppe. |
| `groupHint` | Nein | `string` | Kurzer Hilfetext für die Gruppe. |
| `optionKey` | Nein | `string` | Interner Optionsschlüssel für einfache Auth-Abläufe mit einem Flag. |
| `cliFlag` | Nein | `string` | Name des CLI-Flags, z. B. `--openrouter-api-key`. |
| `cliOption` | Nein | `string` | Vollständige Form der CLI-Option, z. B. `--openrouter-api-key <key>`. |
| `cliDescription` | Nein | `string` | Beschreibung, die in der CLI-Hilfe verwendet wird. |
| `onboardingScopes` | Nein | `Array<"text-inference" \| "image-generation">` | In welchen Onboarding-Oberflächen diese Auswahl erscheinen soll. Wenn ausgelassen, ist der Standard `["text-inference"]`. |
| Feld | Erforderlich | Typ | Bedeutung |
| -------------------- | ------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `provider` | Ja | `string` | Provider-ID, zu der diese Auswahl gehört. |
| `method` | Ja | `string` | ID der Auth-Methode, an die weitergeleitet werden soll. |
| `choiceId` | Ja | `string` | Stabile Auth-Auswahl-ID, die von Onboarding- und CLI-Flows verwendet wird. |
| `choiceLabel` | Nein | `string` | Benutzerseitiges Label. Wenn es weggelassen wird, greift OpenClaw auf `choiceId` zurück. |
| `choiceHint` | Nein | `string` | Kurzer Hilfetext für den Picker. |
| `assistantPriority` | Nein | `number` | Niedrigere Werte werden in assistentengesteuerten interaktiven Pickern früher sortiert. |
| `assistantVisibility`| Nein | `"visible"` \| `"manual-only"` | Blendet die Auswahl in Assistenten-Pickern aus, erlaubt aber weiterhin die manuelle Auswahl per CLI. |
| `deprecatedChoiceIds`| Nein | `string[]` | Legacy-Auswahl-IDs, die Benutzer zu dieser Ersatz-Auswahl weiterleiten sollen. |
| `groupId` | Nein | `string` | Optionale Gruppen-ID zum Gruppieren verwandter Auswahlen. |
| `groupLabel` | Nein | `string` | Benutzerseitiges Label für diese Gruppe. |
| `groupHint` | Nein | `string` | Kurzer Hilfetext für die Gruppe. |
| `optionKey` | Nein | `string` | Interner Optionsschlüssel für einfache Auth-Flows mit einem einzelnen Flag. |
| `cliFlag` | Nein | `string` | Name des CLI-Flags, zum Beispiel `--openrouter-api-key`. |
| `cliOption` | Nein | `string` | Vollständige Form der CLI-Option, zum Beispiel `--openrouter-api-key <key>`. |
| `cliDescription` | Nein | `string` | Beschreibung, die in der CLI-Hilfe verwendet wird. |
| `onboardingScopes` | Nein | `Array<"text-inference" \| "image-generation">` | In welchen Onboarding-Oberflächen diese Auswahl erscheinen soll. Wenn weggelassen, ist der Standard `["text-inference"]`. |
## Referenz für `commandAliases`
Verwenden Sie `commandAliases`, wenn ein Plugin einen Laufzeit-Befehlsnamen besitzt, den Benutzer
irrtümlich in `plugins.allow` eintragen oder als Root-CLI-Befehl ausführen möchten. OpenClaw
möglicherweise fälschlich in `plugins.allow` eintragen oder als Root-CLI-Befehl ausführen möchten. OpenClaw
verwendet diese Metadaten für Diagnosen, ohne Laufzeitcode des Plugins zu importieren.
```json
@ -213,30 +213,34 @@ verwendet diese Metadaten für Diagnosen, ohne Laufzeitcode des Plugins zu impor
}
```
| Feld | Erforderlich | Typ | Bedeutung |
| ------------ | ------------ | ----------------- | ----------------------------------------------------------------------- |
| `name` | Ja | `string` | Befehlsname, der diesem Plugin gehört. |
| `kind` | Nein | `"runtime-slash"` | Markiert den Alias als Chat-Slash-Befehl statt als Root-CLI-Befehl. |
| `cliCommand` | Nein | `string` | Verwandter Root-CLI-Befehl, der für CLI-Operationen vorgeschlagen werden soll, falls vorhanden. |
| Feld | Erforderlich | Typ | Bedeutung |
| ------------ | ------------ | ----------------- | -------------------------------------------------------------------------- |
| `name` | Ja | `string` | Befehlsname, der zu diesem Plugin gehört. |
| `kind` | Nein | `"runtime-slash"` | Markiert den Alias als Chat-Slash-Befehl statt als Root-CLI-Befehl. |
| `cliCommand` | Nein | `string` | Zugehöriger Root-CLI-Befehl, der für CLI-Operationen vorgeschlagen werden soll, falls vorhanden. |
## Referenz für `activation`
Verwenden Sie `activation`, wenn das Plugin günstig deklarieren kann, welche Control-Plane-Ereignisse
Verwenden Sie `activation`, wenn das Plugin günstig deklarieren kann, welche Ereignisse der Control Plane
es in einen Aktivierungs-/Ladeplan aufnehmen sollen.
Dieser Block ist Planer-Metadaten, keine Lifecycle-API. Er registriert kein
Laufzeitverhalten, ersetzt nicht `register(...)` und verspricht nicht, dass
Plugin-Code bereits ausgeführt wurde. Der Aktivierungsplaner verwendet diese Felder, um Kandidaten-Plugins einzugrenzen, bevor auf bestehende Manifest-Eigentums-
metadaten wie `providers`, `channels`, `commandAliases`, `setup.providers`,
`contracts.tools` und Hooks zurückgegriffen wird.
Plugin-Code bereits ausgeführt wurde. Der Aktivierungsplaner verwendet diese Felder, um
Kandidaten-Plugins einzugrenzen, bevor er auf bestehende Manifest-Ownership-
Metadaten wie `providers`, `channels`, `commandAliases`, `setup.providers`,
`contracts.tools` und Hooks zurückfällt.
Bevorzugen Sie die engsten Metadaten, die Eigentum bereits beschreiben. Verwenden Sie
`providers`, `channels`, `commandAliases`, Setup-Beschreibungen oder `contracts`,
wenn diese Felder die Beziehung ausdrücken. Verwenden Sie `activation` für zusätzliche Hinweise an den Planer, die nicht durch diese Eigentumsfelder dargestellt werden können.
Bevorzugen Sie die engsten Metadaten, die Ownership bereits beschreiben. Verwenden Sie
`providers`, `channels`, `commandAliases`, Setup-Deskriptoren oder `contracts`,
wenn diese Felder die Beziehung ausdrücken. Verwenden Sie `activation` für zusätzliche Planer-
Hinweise, die sich nicht durch diese Ownership-Felder darstellen lassen.
Dieser Block enthält nur Metadaten. Er registriert kein Laufzeitverhalten und ersetzt nicht
`register(...)`, `setupEntry` oder andere Laufzeit-/Plugin-Entry-Points.
Aktuelle Konsumenten verwenden ihn als Eingrenzungshinweis vor breiterem Plugin-Laden, sodass fehlende Aktivierungsmetadaten in der Regel nur Leistung kosten; sie sollten die Korrektheit nicht verändern, solange veraltete Manifest-Eigentums-Fallbacks noch existieren.
Dieser Block besteht nur aus Metadaten. Er registriert kein Laufzeitverhalten und ersetzt weder
`register(...)`, `setupEntry` noch andere Laufzeit-/Plugin-Einstiegspunkte.
Aktuelle Verbraucher verwenden ihn als Eingrenzungshinweis vor einem breiteren Plugin-Laden, daher
kosten fehlende Aktivierungsmetadaten normalerweise nur Leistung; die Korrektheit sollte sich nicht
ändern, solange die Legacy-Fallbacks für Manifest-Ownership noch existieren.
```json
{
@ -252,34 +256,34 @@ Aktuelle Konsumenten verwenden ihn als Eingrenzungshinweis vor breiterem Plugin-
| Feld | Erforderlich | Typ | Bedeutung |
| ---------------- | ------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `onProviders` | Nein | `string[]` | Provider-IDs, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onCommands` | Nein | `string[]` | Befehls-IDs, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onChannels` | Nein | `string[]` | Kanal-IDs, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onRoutes` | Nein | `string[]` | Route-Arten, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onCapabilities` | Nein | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Breite Fähigkeitshinweise, die für die Aktivierungsplanung der Control Plane verwendet werden. Bevorzugen Sie nach Möglichkeit engere Felder. |
| `onProviders` | Nein | `string[]` | Provider-IDs, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onCommands` | Nein | `string[]` | Befehls-IDs, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onChannels` | Nein | `string[]` | Channel-IDs, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onRoutes` | Nein | `string[]` | Routenarten, die dieses Plugin in Aktivierungs-/Ladepläne aufnehmen sollen. |
| `onCapabilities` | Nein | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Breite Capability-Hinweise, die von der Aktivierungsplanung der Control Plane verwendet werden. Wenn möglich, engere Felder bevorzugen. |
Aktuelle Live-Konsumenten:
Aktuelle Live-Verbraucher:
- CLI-Planung, die durch Befehle ausgelöst wird, greift auf veraltete
- befehlsausgelöste CLI-Planung fällt auf Legacy-
`commandAliases[].cliCommand` oder `commandAliases[].name` zurück
- Setup-/Kanal-Planung, die durch Kanäle ausgelöst wird, greift auf veraltetes Eigentum aus `channels[]`
zurück, wenn explizite Aktivierungsmetadaten für den Kanal fehlen
- Setup-/Laufzeitplanung, die durch Provider ausgelöst wird, greift auf veraltetes
Eigentum aus `providers[]` und `cliBackends[]` auf oberster Ebene zurück, wenn explizite Provider-
- channel-ausgelöste Setup-/Channel-Planung fällt auf Legacy-Ownership über `channels[]`
zurück, wenn explizite Channel-Aktivierungsmetadaten fehlen
- provider-ausgelöste Setup-/Laufzeitplanung fällt auf Legacy-
`providers[]` und Ownership über das Top-Level `cliBackends[]` zurück, wenn explizite Provider-
Aktivierungsmetadaten fehlen
Diagnosen des Planers können explizite Aktivierungshinweise von Fallbacks des Manifest-
Eigentums unterscheiden. Zum Beispiel bedeutet `activation-command-hint`, dass
Planer-Diagnosen können explizite Aktivierungshinweise von Fallbacks für Manifest-
Ownership unterscheiden. Zum Beispiel bedeutet `activation-command-hint`, dass
`activation.onCommands` übereinstimmte, während `manifest-command-alias` bedeutet, dass der
Planer stattdessen Eigentum aus `commandAliases` verwendet hat. Diese Bezeichner sind für
Planer stattdessen Ownership über `commandAliases` verwendet hat. Diese Begründungslabels sind für
Host-Diagnosen und Tests gedacht; Plugin-Autoren sollten weiterhin die Metadaten deklarieren,
die Eigentum am besten beschreiben.
die Ownership am besten beschreiben.
## Referenz für `qaRunners`
Verwenden Sie `qaRunners`, wenn ein Plugin einen oder mehrere Transport-Runner unterhalb des
gemeinsamen Roots `openclaw qa` bereitstellt. Halten Sie diese Metadaten günstig und statisch; die
Plugin-Laufzeit besitzt weiterhin die eigentliche CLI-Registrierung über eine leichte
gemeinsamen Roots `openclaw qa` beiträgt. Halten Sie diese Metadaten günstig und statisch; die Plugin-
Laufzeit besitzt weiterhin die eigentliche CLI-Registrierung über eine leichtgewichtige
Oberfläche `runtime-api.ts`, die `qaRunnerCliRegistrations` exportiert.
```json
@ -287,16 +291,16 @@ Oberfläche `runtime-api.ts`, die `qaRunnerCliRegistrations` exportiert.
"qaRunners": [
{
"commandName": "matrix",
"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
"description": "Die Docker-gestützte Matrix-Live-QA-Lane gegen einen flüchtigen Homeserver ausführen"
}
]
}
```
| Feld | Erforderlich | Typ | Bedeutung |
| ------------- | ------------ | -------- | ------------------------------------------------------------------ |
| `commandName` | Ja | `string` | Unterbefehl, der unter `openclaw qa` eingehängt wird, z. B. `matrix`. |
| `description` | Nein | `string` | Fallback-Hilfetext, der verwendet wird, wenn der gemeinsame Host einen Stub-Befehl benötigt. |
| Feld | Erforderlich | Typ | Bedeutung |
| ------------- | ------------ | -------- | -------------------------------------------------------------------- |
| `commandName` | Ja | `string` | Unterbefehl unterhalb von `openclaw qa`, zum Beispiel `matrix`. |
| `description` | Nein | `string` | Fallback-Hilfetext, wenn der gemeinsame Host einen Stub-Befehl benötigt. |
## Referenz für `setup`
@ -320,41 +324,41 @@ benötigen, bevor die Laufzeit geladen wird.
}
```
`cliBackends` auf oberster Ebene bleibt gültig und beschreibt weiterhin CLI-Inferenz-
Backends. `setup.cliBackends` ist die setup-spezifische Beschreibungsoberfläche für
Control-Plane-/Setup-Abläufe, die rein metadata-basiert bleiben sollen.
Top-Level-`cliBackends` bleibt gültig und beschreibt weiterhin CLI-Inferenz-
Backends. `setup.cliBackends` ist die setupspezifische Deskriptoroberfläche für
Control-Plane-/Setup-Flows, die nur Metadaten bleiben sollen.
Wenn vorhanden, sind `setup.providers` und `setup.cliBackends` die bevorzugte
deskriptorbasierte Lookup-Oberfläche für Setup-Discovery. Wenn der Deskriptor das
Kandidaten-Plugin nur eingrenzt und Setup weiterhin reichere Laufzeit-Hooks zur Setup-Zeit benötigt,
setzen Sie `requiresRuntime: true` und behalten `setup-api` als Fallback-
Ausführungspfad bei.
deskriptorbasierte Lookup-Oberfläche für Setup-Discovery. Wenn der Deskriptor nur
das Kandidaten-Plugin eingrenzt und das Setup dennoch reichhaltigere Laufzeit-Hooks zur Setup-Zeit benötigt,
setzen Sie `requiresRuntime: true` und behalten Sie `setup-api` als
Fallback-Ausführungspfad bei.
Da das Setup-Lookup plugin-eigenen `setup-api`-Code ausführen kann, müssen normalisierte
Da Setup-Lookup plugin-eigenen `setup-api`-Code ausführen kann, müssen normalisierte
Werte in `setup.providers[].id` und `setup.cliBackends[]` über alle
entdeckten Plugins hinweg eindeutig bleiben. Mehrdeutiges Eigentum schlägt fail-closed fehl, statt
gefundenen Plugins hinweg eindeutig bleiben. Mehrdeutige Ownership schlägt sicher geschlossen fehl, statt
einen Gewinner anhand der Discovery-Reihenfolge auszuwählen.
### Referenz für `setup.providers`
| Feld | Erforderlich | Typ | Bedeutung |
| ------------- | ------------ | ---------- | ----------------------------------------------------------------------------------------- |
| `id` | Ja | `string` | Provider-ID, die während Setup oder Onboarding bereitgestellt wird. Halten Sie normalisierte IDs global eindeutig. |
| `authMethods` | Nein | `string[]` | IDs der Setup-/Auth-Methoden, die dieser Provider unterstützt, ohne die vollständige Laufzeit zu laden. |
| `id` | Ja | `string` | Provider-ID, die während Setup oder Onboarding bereitgestellt wird. Normalisierte IDs müssen global eindeutig bleiben. |
| `authMethods` | Nein | `string[]` | Setup-/Auth-Methoden-IDs, die dieser Provider ohne Laden der vollständigen Laufzeit unterstützt. |
| `envVars` | Nein | `string[]` | Umgebungsvariablen, die generische Setup-/Status-Oberflächen prüfen können, bevor die Plugin-Laufzeit geladen wird. |
### `setup`-Felder
| Feld | Erforderlich | Typ | Bedeutung |
| ------------------ | ------------ | ---------- | ------------------------------------------------------------------------------------------------- |
| `providers` | Nein | `object[]` | Setup-Beschreibungen für Provider, die während Setup und Onboarding bereitgestellt werden. |
| `cliBackends` | Nein | `string[]` | Backend-IDs zur Setup-Zeit, die für deskriptorbasiertes Setup-Lookup verwendet werden. Halten Sie normalisierte IDs global eindeutig. |
| `configMigrations` | Nein | `string[]` | IDs von Konfigurationsmigrationen, die der Setup-Oberfläche dieses Plugins gehören. |
| `requiresRuntime` | Nein | `boolean` | Ob Setup nach dem deskriptorbasierten Lookup weiterhin `setup-api`-Ausführung benötigt. |
| Feld | Erforderlich | Typ | Bedeutung |
| ------------------ | ------------ | ---------- | ---------------------------------------------------------------------------------------------------------- |
| `providers` | Nein | `object[]` | Provider-Setup-Deskriptoren, die während Setup und Onboarding bereitgestellt werden. |
| `cliBackends` | Nein | `string[]` | Backend-IDs zur Setup-Zeit, die für deskriptorbasiertes Setup-Lookup verwendet werden. Normalisierte IDs müssen global eindeutig bleiben. |
| `configMigrations` | Nein | `string[]` | IDs für Konfigurationsmigrationen, die der Setup-Oberfläche dieses Plugins gehören. |
| `requiresRuntime` | Nein | `boolean` | Ob das Setup nach dem Deskriptor-Lookup weiterhin die Ausführung von `setup-api` benötigt. |
## Referenz für `uiHints`
`uiHints` ist eine Zuordnung von Namen von Konfigurationsfeldern zu kleinen Rendering-Hinweisen.
`uiHints` ist eine Map von Namen von Konfigurationsfeldern zu kleinen Rendering-Hinweisen.
```json
{
@ -371,18 +375,18 @@ einen Gewinner anhand der Discovery-Reihenfolge auszuwählen.
Jeder Feldhinweis kann Folgendes enthalten:
| Feld | Typ | Bedeutung |
| ------------- | ---------- | ------------------------------------------ |
| `label` | `string` | Benutzerseitiges Feldlabel. |
| `help` | `string` | Kurzer Hilfetext. |
| `tags` | `string[]` | Optionale UI-Tags. |
| `advanced` | `boolean` | Markiert das Feld als erweitert. |
| Feld | Typ | Bedeutung |
| ------------- | ---------- | ----------------------------------------- |
| `label` | `string` | Benutzerseitiges Feldlabel. |
| `help` | `string` | Kurzer Hilfetext. |
| `tags` | `string[]` | Optionale UI-Tags. |
| `advanced` | `boolean` | Markiert das Feld als erweitert. |
| `sensitive` | `boolean` | Markiert das Feld als geheim oder sensibel. |
| `placeholder` | `string` | Platzhaltertext für Formulareingaben. |
| `placeholder` | `string` | Platzhaltertext für Formulareingaben. |
## Referenz für `contracts`
Verwenden Sie `contracts` nur für statische Metadaten zum Besitz von Fähigkeiten, die OpenClaw
Verwenden Sie `contracts` nur für statische Capability-Ownership-Metadaten, die OpenClaw
lesen kann, ohne die Plugin-Laufzeit zu importieren.
```json
@ -406,38 +410,38 @@ lesen kann, ohne die Plugin-Laufzeit zu importieren.
Jede Liste ist optional:
| Feld | Typ | Bedeutung |
| -------------------------------- | ---------- | ------------------------------------------------------------------------- |
| Feld | Typ | Bedeutung |
| -------------------------------- | ---------- | ----------------------------------------------------------------------- |
| `embeddedExtensionFactories` | `string[]` | IDs eingebetteter Laufzeiten, für die ein gebündeltes Plugin Factories registrieren darf. |
| `externalAuthProviders` | `string[]` | Provider-IDs, deren Hook für externe Auth-Profile diesem Plugin gehört. |
| `speechProviders` | `string[]` | Speech-Provider-IDs, die diesem Plugin gehören. |
| `realtimeTranscriptionProviders` | `string[]` | Provider-IDs für Echtzeit-Transkription, die diesem Plugin gehören. |
| `realtimeVoiceProviders` | `string[]` | Provider-IDs für Echtzeit-Stimme, die diesem Plugin gehören. |
| `memoryEmbeddingProviders` | `string[]` | Provider-IDs für Memory Embedding, die diesem Plugin gehören. |
| `mediaUnderstandingProviders` | `string[]` | Media-Understanding-Provider-IDs, die diesem Plugin gehören. |
| `imageGenerationProviders` | `string[]` | Bildgenerierungs-Provider-IDs, die diesem Plugin gehören. |
| `videoGenerationProviders` | `string[]` | Videogenerierungs-Provider-IDs, die diesem Plugin gehören. |
| `webFetchProviders` | `string[]` | Web-Fetch-Provider-IDs, die diesem Plugin gehören. |
| `webSearchProviders` | `string[]` | Websuch-Provider-IDs, die diesem Plugin gehören. |
| `tools` | `string[]` | Namen von Agent-Tools, die diesem Plugin für gebündelte Vertragsprüfungen gehören. |
| `externalAuthProviders` | `string[]` | Provider-IDs, deren externer Auth-Profile-Hook diesem Plugin gehört. |
| `speechProviders` | `string[]` | Speech-Provider-IDs, die diesem Plugin gehören. |
| `realtimeTranscriptionProviders` | `string[]` | Provider-IDs für Echtzeit-Transkription, die diesem Plugin gehören. |
| `realtimeVoiceProviders` | `string[]` | Provider-IDs für Echtzeit-Stimme, die diesem Plugin gehören. |
| `memoryEmbeddingProviders` | `string[]` | Provider-IDs für Memory-Embeddings, die diesem Plugin gehören. |
| `mediaUnderstandingProviders` | `string[]` | Provider-IDs für Medienverständnis, die diesem Plugin gehören. |
| `imageGenerationProviders` | `string[]` | Provider-IDs für Bildgenerierung, die diesem Plugin gehören. |
| `videoGenerationProviders` | `string[]` | Provider-IDs für Videogenerierung, die diesem Plugin gehören. |
| `webFetchProviders` | `string[]` | Provider-IDs für Web-Abruf, die diesem Plugin gehören. |
| `webSearchProviders` | `string[]` | Provider-IDs für Websuche, die diesem Plugin gehören. |
| `tools` | `string[]` | Namen von Agent-Tools, die diesem Plugin für Contract-Prüfungen gebündelter Plugins gehören. |
Provider-Plugins, die `resolveExternalAuthProfiles` implementieren, sollten
`contracts.externalAuthProviders` deklarieren. Plugins ohne diese Deklaration laufen
weiterhin über einen veralteten Kompatibilitäts-Fallback, aber dieser Fallback ist langsamer und
`contracts.externalAuthProviders` deklarieren. Plugins ohne diese Deklaration laufen weiterhin
über einen veralteten Kompatibilitäts-Fallback, aber dieser Fallback ist langsamer und
wird nach dem Migrationsfenster entfernt.
Gebündelte Memory-Embedding-Provider sollten
Gebündelte Provider für Memory-Embeddings sollten
`contracts.memoryEmbeddingProviders` für jede Adapter-ID deklarieren, die sie bereitstellen, einschließlich
integrierter Adapter wie `local`. Eigenständige CLI-Pfade verwenden diesen Manifest-
Vertrag, um nur das besitzende Plugin zu laden, bevor die vollständige Gateway-Laufzeit
Contract, um nur das besitzende Plugin zu laden, bevor die vollständige Gateway-Laufzeit
Provider registriert hat.
## Referenz für `mediaUnderstandingProviderMetadata`
Verwenden Sie `mediaUnderstandingProviderMetadata`, wenn ein Media-Understanding-Provider
Verwenden Sie `mediaUnderstandingProviderMetadata`, wenn ein Provider für Medienverständnis
Standardmodelle, Auto-Auth-Fallback-Priorität oder native Dokumentunterstützung hat, die
generische Core-Helfer benötigen, bevor die Laufzeit geladen wird. Schlüssel müssen außerdem in
`contracts.mediaUnderstandingProviders` deklariert werden.
generische Core-Helfer benötigen, bevor die Laufzeit geladen wird. Schlüssel müssen auch in
`contracts.mediaUnderstandingProviders` deklariert sein.
```json
{
@ -460,19 +464,19 @@ generische Core-Helfer benötigen, bevor die Laufzeit geladen wird. Schlüssel m
}
```
Jeder Providereintrag kann Folgendes enthalten:
Jeder Provider-Eintrag kann Folgendes enthalten:
| Feld | Typ | Bedeutung |
| Feld | Typ | Bedeutung |
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | Medienfähigkeiten, die dieser Provider bereitstellt. |
| `defaultModels` | `Record<string, string>` | Standardwerte von Fähigkeit zu Modell, die verwendet werden, wenn die Konfiguration kein Modell angibt. |
| `autoPriority` | `Record<string, number>` | Kleinere Zahlen werden bei automatischem providerbasiertem Fallback aufgrund von Anmeldedaten früher sortiert. |
| `capabilities` | `("image" \| "audio" \| "video")[]` | Medien-Capabilities, die von diesem Provider bereitgestellt werden. |
| `defaultModels` | `Record<string, string>` | Standardwerte Capability-zu-Modell, die verwendet werden, wenn die Konfiguration kein Modell angibt. |
| `autoPriority` | `Record<string, number>` | Niedrigere Zahlen werden für automatischen Provider-Fallback auf Basis von Credentials früher sortiert. |
| `nativeDocumentInputs` | `"pdf"[]` | Native Dokumenteingaben, die vom Provider unterstützt werden. |
## Referenz für `channelConfigs`
Verwenden Sie `channelConfigs`, wenn ein Kanal-Plugin günstige Konfigurationsmetadaten benötigt,
bevor die Laufzeit geladen wird.
Verwenden Sie `channelConfigs`, wenn ein Channel-Plugin günstige Konfigurationsmetadaten benötigt, bevor
die Laufzeit geladen wird.
```json
{
@ -492,27 +496,27 @@ bevor die Laufzeit geladen wird.
}
},
"label": "Matrix",
"description": "Matrix homeserver connection",
"description": "Verbindung zum Matrix-Homeserver",
"preferOver": ["matrix-legacy"]
}
}
}
```
Jeder Kanaleintrag kann Folgendes enthalten:
Jeder Channel-Eintrag kann Folgendes enthalten:
| Feld | Typ | Bedeutung |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON-Schema für `channels.<id>`. Für jeden deklarierten Eintrag zur Kanalkonfiguration erforderlich. |
| `uiHints` | `Record<string, object>` | Optionale UI-Labels/Platzhalter/Hinweise auf Sensitivität für diesen Abschnitt der Kanalkonfiguration. |
| `label` | `string` | Kanal-Label, das in Picker- und Prüfoberflächen zusammengeführt wird, wenn Laufzeitmetadaten noch nicht bereit sind. |
| `description` | `string` | Kurze Kanalbeschreibung für Prüf- und Katalogoberflächen. |
| `preferOver` | `string[]` | Veraltete oder niedriger priorisierte Plugin-IDs, die dieser Kanal in Auswahloberflächen übertreffen soll. |
| Feld | Typ | Bedeutung |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON-Schema für `channels.<id>`. Für jeden deklarierten Channel-Konfigurationseintrag erforderlich. |
| `uiHints` | `Record<string, object>` | Optionale UI-Labels/Platzhalter/Sensitivitätshinweise für diesen Abschnitt der Channel-Konfiguration. |
| `label` | `string` | Channel-Label, das in Picker- und Inspect-Oberflächen zusammengeführt wird, wenn Laufzeitmetadaten noch nicht bereit sind. |
| `description` | `string` | Kurze Channel-Beschreibung für Inspect- und Katalogoberflächen. |
| `preferOver` | `string[]` | Legacy- oder niedriger priorisierte Plugin-IDs, die dieser Channel in Auswahloberflächen übertreffen soll. |
## Referenz für `modelSupport`
Verwenden Sie `modelSupport`, wenn OpenClaw Ihr Provider-Plugin aus
Kurzformen von Modell-IDs wie `gpt-5.5` oder `claude-sonnet-4.6` ableiten soll, bevor die Plugin-Laufzeit
Kurzform-Modell-IDs wie `gpt-5.5` oder `claude-sonnet-4.6` ableiten soll, bevor die Plugin-Laufzeit
geladen wird.
```json
@ -524,99 +528,103 @@ geladen wird.
}
```
OpenClaw wendet dabei folgende Priorität an:
OpenClaw wendet dabei diese Priorität an:
- explizite Referenzen `provider/model` verwenden die Manifest-Metadaten `providers` des besitzenden Plugins
- explizite Referenzen `provider/model` verwenden die besitzenden Manifest-Metadaten aus `providers`
- `modelPatterns` schlagen `modelPrefixes`
- wenn ein nicht gebündeltes Plugin und ein gebündeltes Plugin beide übereinstimmen, gewinnt das nicht gebündelte Plugin
- wenn sowohl ein nicht gebündeltes Plugin als auch ein gebündeltes Plugin übereinstimmen, gewinnt das nicht gebündelte
Plugin
- verbleibende Mehrdeutigkeit wird ignoriert, bis Benutzer oder Konfiguration einen Provider angeben
Felder:
| Feld | Typ | Bedeutung |
| --------------- | ---------- | ---------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | Präfixe, die per `startsWith` gegen Kurzformen von Modell-IDs abgeglichen werden. |
| `modelPatterns` | `string[]` | Regex-Quellen, die nach Entfernen von Profil-Suffixen gegen Kurzformen von Modell-IDs abgeglichen werden. |
| Feld | Typ | Bedeutung |
| --------------- | ---------- | ------------------------------------------------------------------------------ |
| `modelPrefixes` | `string[]` | Präfixe, die mit `startsWith` gegen Kurzform-Modell-IDs abgeglichen werden. |
| `modelPatterns` | `string[]` | Regex-Quellen, die nach Entfernen von Profilsuffixen gegen Kurzform-Modell-IDs abgeglichen werden. |
Veraltete Fähigkeits-Schlüssel auf oberster Ebene sind deprecated. Verwenden Sie `openclaw doctor --fix`, um
Legacy-Capability-Schlüssel auf oberster Ebene sind veraltet. Verwenden Sie `openclaw doctor --fix`, um
`speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
`webFetchProviders` und `webSearchProviders` unter `contracts` zu verschieben; normales
Manifest-Laden behandelt diese Felder auf oberster Ebene nicht mehr als Besitz von Fähigkeiten.
`webFetchProviders` und `webSearchProviders` unter `contracts` zu verschieben; das normale
Laden von Manifesten behandelt diese Top-Level-Felder nicht mehr als
Capability-Ownership.
## Manifest versus package.json
Die beiden Dateien dienen unterschiedlichen Aufgaben:
Die beiden Dateien erfüllen unterschiedliche Aufgaben:
| Datei | Verwenden Sie sie für |
| Datei | Verwenden Sie sie für |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Discovery, Konfigurationsvalidierung, Metadaten zur Auth-Auswahl und UI-Hinweise, die vorhanden sein müssen, bevor Plugin-Code läuft |
| `package.json` | npm-Metadaten, Installation von Abhängigkeiten und den Block `openclaw`, der für Entry-Points, Installations-Gating, Setup oder Katalogmetadaten verwendet wird |
| `openclaw.plugin.json` | Discovery, Konfigurationsvalidierung, Metadaten für Auth-Auswahl und UI-Hinweise, die vorhanden sein müssen, bevor Plugin-Code läuft |
| `package.json` | npm-Metadaten, Installation von Abhängigkeiten und den Block `openclaw`, der für Einstiegspunkte, Installations-Gating, Setup oder Katalogmetadaten verwendet wird |
Wenn Sie unsicher sind, wo ein Metadatum hingehört, verwenden Sie diese Regel:
Wenn Sie unsicher sind, wohin ein Metadatum gehört, verwenden Sie diese Regel:
- wenn OpenClaw es kennen muss, bevor Plugin-Code geladen wird, gehört es in `openclaw.plugin.json`
- wenn es um Packaging, Entry-Dateien oder npm-Installationsverhalten geht, gehört es in `package.json`
- wenn es um Packaging, Einstiegsdateien oder npm-Installationsverhalten geht, gehört es in `package.json`
### `package.json`-Felder, die Discovery beeinflussen
Einige Metadaten von Plugins vor der Laufzeit liegen absichtlich in `package.json` unter dem
Einige Plugin-Metadaten vor der Laufzeit leben absichtlich in `package.json` unter dem
Block `openclaw` statt in `openclaw.plugin.json`.
Wichtige Beispiele:
| Feld | Bedeutung |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Deklariert native Plugin-Entry-Points. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.runtimeExtensions` | Deklariert gebaute JavaScript-Laufzeit-Entry-Points für installierte Pakete. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.setupEntry` | Leichter Entry-Point nur für Setup, der während Onboarding, verzögertem Kanalstart und schreibgeschützter Discovery von Kanalstatus/SecretRef verwendet wird. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.runtimeSetupEntry` | Deklariert den gebauten JavaScript-Setup-Entry-Point für installierte Pakete. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.channel` | Günstige Metadaten für den Kanalkatalog wie Labels, Doku-Pfade, Aliasse und Auswahltext. |
| `openclaw.channel.configuredState` | Leichte Metadaten für einen Configured-State-Checker, der „existiert bereits eine nur per env konfigurierte Einrichtung?“ beantworten kann, ohne die vollständige Kanal-Laufzeit zu laden. |
| `openclaw.channel.persistedAuthState` | Leichte Metadaten für einen Persisted-Auth-Checker, der „ist bereits irgendetwas eingeloggt?“ beantworten kann, ohne die vollständige Kanal-Laufzeit zu laden. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Installations-/Update-Hinweise für gebündelte und extern veröffentlichte Plugins. |
| `openclaw.install.defaultChoice` | Bevorzugter Installationspfad, wenn mehrere Installationsquellen verfügbar sind. |
| `openclaw.install.minHostVersion` | Minimal unterstützte OpenClaw-Host-Version, mit einem SemVer-Floor wie `>=2026.3.22`. |
| `openclaw.install.expectedIntegrity` | Erwartete npm-dist-Integritätszeichenfolge wie `sha512-...`; Installations- und Update-Abläufe verifizieren das geladene Artefakt dagegen. |
| `openclaw.install.allowInvalidConfigRecovery` | Erlaubt einen engen Wiederherstellungspfad per Neuinstallation gebündelter Plugins, wenn die Konfiguration ungültig ist. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Erlaubt das Laden von Kanaloberflächen nur für Setup vor dem vollständigen Kanal-Plugin während des Starts. |
| Feld | Bedeutung |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Deklariert Einstiegspunkte für native Plugins. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.runtimeExtensions` | Deklariert Einstiegspunkte der gebauten JavaScript-Laufzeit für installierte Pakete. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.setupEntry` | Leichtgewichtiger, nur für Setup vorgesehener Einstiegspunkt, der während Onboarding, verzögertem Channel-Start und schreibgeschützter Discovery von Channel-Status/SecretRef verwendet wird. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.runtimeSetupEntry` | Deklariert den gebauten JavaScript-Setup-Einstiegspunkt für installierte Pakete. Muss innerhalb des Plugin-Paketverzeichnisses bleiben. |
| `openclaw.channel` | Kostengünstige Metadaten für den Channel-Katalog wie Labels, Docs-Pfade, Aliase und Auswahltexte. |
| `openclaw.channel.configuredState` | Leichtgewichtige Metadaten für den Checker des konfigurierten Zustands, die beantworten können: „Existiert env-only-Setup bereits?“ ohne die vollständige Channel-Laufzeit zu laden. |
| `openclaw.channel.persistedAuthState` | Leichtgewichtige Metadaten für den Checker des persistierten Auth-Zustands, die beantworten können: „Ist bereits etwas angemeldet?“ ohne die vollständige Channel-Laufzeit zu laden. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Installations-/Update-Hinweise für gebündelte und extern veröffentlichte Plugins. |
| `openclaw.install.defaultChoice` | Bevorzugter Installationspfad, wenn mehrere Installationsquellen verfügbar sind. |
| `openclaw.install.minHostVersion` | Minimal unterstützte OpenClaw-Host-Version mit einer SemVer-Untergrenze wie `>=2026.3.22`. |
| `openclaw.install.expectedIntegrity` | Erwarteter npm-dist-Integrity-String wie `sha512-...`; Installations- und Update-Flows prüfen das geladene Artefakt dagegen. |
| `openclaw.install.allowInvalidConfigRecovery` | Erlaubt einen engen Neuinstallations-Recovery-Pfad für gebündelte Plugins, wenn die Konfiguration ungültig ist. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Erlaubt das Laden von Channel-Oberflächen nur für Setup vor dem vollständigen Channel-Plugin während des Starts. |
Manifest-Metadaten entscheiden, welche Provider-/Kanal-/Setup-Auswahlen im
Onboarding erscheinen, bevor die Laufzeit geladen wird. `package.json#openclaw.install` teilt
dem Onboarding mit, wie dieses Plugin geladen oder aktiviert werden soll, wenn der Benutzer
eine dieser Auswahlmöglichkeiten trifft. Verschieben Sie Installationshinweise nicht nach `openclaw.plugin.json`.
Manifest-Metadaten entscheiden, welche Provider-/Channel-/Setup-Auswahlen im
Onboarding erscheinen, bevor die Laufzeit geladen wird. `package.json#openclaw.install` sagt
dem Onboarding, wie dieses Plugin geladen oder aktiviert werden soll, wenn der Benutzer eine dieser
Auswahlen trifft. Verschieben Sie keine Installationshinweise in `openclaw.plugin.json`.
`openclaw.install.minHostVersion` wird während der Installation und beim Laden der Manifest-
Registry durchgesetzt. Ungültige Werte werden abgewiesen; neuere, aber gültige Werte überspringen
das Plugin auf älteren Hosts.
Registry erzwungen. Ungültige Werte werden abgelehnt; neuere, aber gültige Werte überspringen das
Plugin auf älteren Hosts.
Exaktes Pinnen von npm-Versionen lebt bereits in `npmSpec`, zum Beispiel
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Kombinieren Sie das mit
`expectedIntegrity`, wenn Update-Abläufe fail-closed fehlschlagen sollen, falls das geladene
npm-Artefakt nicht mehr zur gepinnten Release-Version passt. Interaktives Onboarding
bietet vertrauenswürdige npm-Spezifikationen aus der Registry an, einschließlich einfacher Paketnamen und Dist-Tags.
Wenn `expectedIntegrity` vorhanden ist, erzwingen Installations-/Update-Abläufe dies; wenn es
weggelassen wird, wird die Registry-Auflösung ohne Integritäts-Pin protokolliert.
Exaktes Pinning von npm-Versionen lebt bereits in `npmSpec`, zum Beispiel
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Offizielle externe Katalog-
Einträge sollten exakte Spezifikationen mit `expectedIntegrity` kombinieren, damit Update-Flows
sicher fehlschlagen, wenn das geladene npm-Artefakt nicht mehr zum gepinnten Release passt.
Interaktives Onboarding bietet aus Kompatibilitätsgründen weiterhin vertrauenswürdige npm-Spezifikationen aus der Registry an, einschließlich bloßer
Paketnamen und Dist-Tags. Katalog-Diagnosen können zwischen exakten, gleitenden,
per Integrity gepinnten und Quellen ohne Integrity unterscheiden.
Wenn `expectedIntegrity` vorhanden ist, erzwingen Installations-/Update-Flows dies; wenn es
weggelassen wird, wird die Registry-Auflösung ohne Integrity-Pin protokolliert.
Kanal-Plugins sollten `openclaw.setupEntry` bereitstellen, wenn Status, Kanalliste
Channel-Plugins sollten `openclaw.setupEntry` bereitstellen, wenn Status, Channel-Liste
oder SecretRef-Scans konfigurierte Konten erkennen müssen, ohne die vollständige
Laufzeit zu laden. Der Setup-Entry-Point sollte Kanalmetadaten sowie setupsichere Config-,
Status- und Secrets-Adapter bereitstellen; behalten Sie Netzwerk-Clients, Gateway-Listener und
Transport-Laufzeiten im Entry-Point der Haupterweiterung.
Laufzeit zu laden. Der Setup-Einstiegspunkt sollte Channel-Metadaten sowie setup-sichere Konfigurations-,
Status- und Secrets-Adapter bereitstellen; Netzwerkclients, Gateway-Listener und
Transport-Laufzeiten bleiben im Haupteinstiegspunkt der Erweiterung.
Felder für Laufzeit-Entry-Points überschreiben die Package-Boundary-Prüfungen für Source-
Entry-Point-Felder nicht. Zum Beispiel kann `openclaw.runtimeExtensions` einen ausbrechenden
Pfad in `openclaw.extensions` nicht ladbar machen.
Felder für Laufzeit-Einstiegspunkte überschreiben Package-Boundary-Prüfungen nicht für Source-
Einstiegspunkt-Felder. Zum Beispiel kann `openclaw.runtimeExtensions` einen
ausbrechenden Pfad in `openclaw.extensions` nicht ladbar machen.
`openclaw.install.allowInvalidConfigRecovery` ist absichtlich eng begrenzt. Es
macht nicht beliebige kaputte Konfigurationen installierbar. Heute erlaubt es nur
Installationsabläufen, sich von bestimmten veralteten Upgrade-Fehlern gebündelter Plugins zu erholen, wie einem
fehlenden Pfad zu einem gebündelten Plugin oder einem veralteten `channels.<id>`-Eintrag für dasselbe
gebündelte Plugin. Nicht zusammenhängende Konfigurationsfehler blockieren die Installation weiterhin und schicken Operatoren
`openclaw.install.allowInvalidConfigRecovery` ist absichtlich eng gefasst. Es macht
nicht beliebige kaputte Konfigurationen installierbar. Derzeit erlaubt es Installations-
Flows nur, sich von bestimmten veralteten Upgrade-Fehlern gebündelter Plugins zu erholen, etwa
von einem fehlenden gebündelten Plugin-Pfad oder einem veralteten `channels.<id>`-Eintrag für dasselbe
gebündelte Plugin. Nicht zusammenhängende Konfigurationsfehler blockieren weiterhin die Installation und schicken Operatoren
zu `openclaw doctor --fix`.
`openclaw.channel.persistedAuthState` ist Paketmetadaten für ein kleines Checker-
`openclaw.channel.persistedAuthState` ist Paketmetadaten für ein winziges Checker-
Modul:
```json
@ -633,13 +641,13 @@ Modul:
}
```
Verwenden Sie dies, wenn Setup-, Doctor- oder Configured-State-Abläufe eine günstige Ja/Nein-
Auth-Probe benötigen, bevor das vollständige Kanal-Plugin geladen wird. Das Ziel-Export sollte eine kleine
Funktion sein, die nur persistierten Zustand liest; leiten Sie es nicht über den vollständigen
Barrel der Kanal-Laufzeit.
Verwenden Sie es, wenn Setup-, Doctor- oder configured-state-Flows vor dem Laden des vollständigen
Channel-Plugins eine günstige Ja/Nein-Auth-Prüfung benötigen. Der Ziel-Export sollte eine kleine
Funktion sein, die nur persistierten Zustand liest; leiten Sie ihn nicht durch das vollständige
Runtime-Barrel des Channels.
`openclaw.channel.configuredState` folgt derselben Form für günstige Configured-State-
Prüfungen nur per env:
`openclaw.channel.configuredState` folgt derselben Form für günstige env-only-
Prüfungen des konfigurierten Zustands:
```json
{
@ -655,68 +663,68 @@ Prüfungen nur per env:
}
```
Verwenden Sie dies, wenn ein Kanal den konfigurierten Zustand aus env oder anderen kleinen
Verwenden Sie es, wenn ein Channel den konfigurierten Zustand aus env oder anderen kleinen
Nicht-Laufzeit-Eingaben beantworten kann. Wenn die Prüfung vollständige Konfigurationsauflösung oder die echte
Kanal-Laufzeit benötigt, behalten Sie diese Logik stattdessen im Hook `config.hasConfiguredState` des Plugins.
Channel-Laufzeit benötigt, belassen Sie diese Logik stattdessen im Hook `config.hasConfiguredState` des Plugins.
## Vorrang bei Discovery (doppelte Plugin-IDs)
## Discovery-Priorität (doppelte Plugin-IDs)
OpenClaw erkennt Plugins aus mehreren Roots (gebündelt, global installiert, Workspace, explizit per Konfiguration ausgewählte Pfade). Wenn zwei Funde dieselbe `id` teilen, wird nur das Manifest mit der **höchsten Priorität** beibehalten; Duplikate mit niedrigerer Priorität werden verworfen, statt parallel dazu geladen zu werden.
OpenClaw findet Plugins aus mehreren Roots (gebündelt, globale Installation, Workspace, explizit per Konfiguration ausgewählte Pfade). Wenn zwei Discovery-Ergebnisse dieselbe `id` teilen, wird nur das Manifest mit der **höchsten Priorität** beibehalten; Duplikate mit niedrigerer Priorität werden verworfen, statt daneben geladen zu werden.
Priorität, von hoch nach niedrig:
1. **Per Konfiguration ausgewählt** — ein Pfad, der explizit in `plugins.entries.<id>` fixiert ist
1. **Per Konfiguration ausgewählt** — ein Pfad, der explizit in `plugins.entries.<id>` angeheftet ist
2. **Gebündelt** — Plugins, die mit OpenClaw ausgeliefert werden
3. **Global installiert** — Plugins, die in den globalen OpenClaw-Plugin-Root installiert sind
4. **Workspace** — Plugins, die relativ zum aktuellen Workspace erkannt werden
3. **Globale Installation** — Plugins, die in den globalen OpenClaw-Plugin-Root installiert sind
4. **Workspace** — Plugins, die relativ zum aktuellen Workspace gefunden werden
Auswirkungen:
- Eine geforkte oder veraltete Kopie eines gebündelten Plugins im Workspace überschattet den gebündelten Build nicht.
- Um ein gebündeltes Plugin tatsächlich durch ein lokales zu überschreiben, fixieren Sie es über `plugins.entries.<id>`, damit es durch Priorität gewinnt, statt sich auf Workspace-Discovery zu verlassen.
- Verworfene Duplikate werden protokolliert, sodass Doctor und Startdiagnosen auf die verworfene Kopie hinweisen können.
- Um ein gebündeltes Plugin tatsächlich mit einem lokalen zu überschreiben, heften Sie es über `plugins.entries.<id>` an, damit es über die Priorität gewinnt, statt sich auf Workspace-Discovery zu verlassen.
- Verworfene Duplikate werden protokolliert, damit Doctor- und Startdiagnosen auf die verworfene Kopie hinweisen können.
## Anforderungen an JSON-Schema
## JSON-Schema-Anforderungen
- **Jedes Plugin muss ein JSON-Schema mitliefern**, selbst wenn es keine Konfiguration akzeptiert.
- **Jedes Plugin muss ein JSON-Schema bereitstellen**, auch wenn es keine Konfiguration akzeptiert.
- Ein leeres Schema ist zulässig (zum Beispiel `{ "type": "object", "additionalProperties": false }`).
- Schemata werden beim Lesen/Schreiben der Konfiguration validiert, nicht zur Laufzeit.
## Validierungsverhalten
- Unbekannte Schlüssel in `channels.*` sind **Fehler**, sofern die Kanal-ID nicht von
einem Plugin-Manifest deklariert wird.
- Unbekannte Schlüssel in `channels.*` sind **Fehler**, es sei denn, die Channel-ID wird durch
ein Plugin-Manifest deklariert.
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` und `plugins.slots.*`
müssen auf **erkennbare** Plugin-IDs verweisen. Unbekannte IDs sind **Fehler**.
- Wenn ein Plugin installiert ist, aber ein kaputtes oder fehlendes Manifest oder Schema hat,
müssen auf **auffindbare** Plugin-IDs verweisen. Unbekannte IDs sind **Fehler**.
- Wenn ein Plugin installiert ist, aber ein defektes oder fehlendes Manifest oder Schema hat,
schlägt die Validierung fehl und Doctor meldet den Plugin-Fehler.
- Wenn Plugin-Konfiguration existiert, das Plugin aber **deaktiviert** ist, bleibt die Konfiguration erhalten und
eine **Warnung** wird in Doctor + Logs angezeigt.
in Doctor + Logs wird eine **Warnung** ausgegeben.
Siehe [Configuration reference](/de/gateway/configuration) für das vollständige Schema `plugins.*`.
## Hinweise
- Das Manifest ist **für native OpenClaw-Plugins erforderlich**, einschließlich lokaler Dateisystem-Ladungen. Die Laufzeit lädt das Plugin-Modul weiterhin separat; das Manifest dient nur der Discovery + Validierung.
- Native Manifeste werden mit JSON5 geparst, daher sind Kommentare, nachgestellte Kommata und unquotierte Schlüssel zulässig, solange der endgültige Wert weiterhin ein Objekt ist.
- Das Manifest ist **für native OpenClaw-Plugins erforderlich**, einschließlich lokaler Dateisystem-Ladevorgänge. Die Laufzeit lädt das Plugin-Modul weiterhin separat; das Manifest dient nur für Discovery + Validierung.
- Native Manifeste werden mit JSON5 geparst, daher sind Kommentare, abschließende Kommas und unquotierte Schlüssel zulässig, solange der endgültige Wert weiterhin ein Objekt ist.
- Nur dokumentierte Manifest-Felder werden vom Manifest-Loader gelesen. Vermeiden Sie benutzerdefinierte Top-Level-Schlüssel.
- `channels`, `providers`, `cliBackends` und `skills` können alle weggelassen werden, wenn ein Plugin sie nicht benötigt.
- `providerDiscoveryEntry` muss leichtgewichtig bleiben und sollte keinen breiten Laufzeitcode importieren; verwenden Sie ihn für statische Provider-Katalogmetadaten oder schmale Discovery-Beschreibungen, nicht für Ausführung zur Request-Zeit.
- `providerDiscoveryEntry` muss leichtgewichtig bleiben und sollte keinen breiten Laufzeitcode importieren; verwenden Sie es für statische Provider-Katalogmetadaten oder schmale Discovery-Deskriptoren, nicht für request-time-Ausführung.
- Exklusive Plugin-Arten werden über `plugins.slots.*` ausgewählt: `kind: "memory"` über `plugins.slots.memory`, `kind: "context-engine"` über `plugins.slots.contextEngine` (Standard `legacy`).
- Metadaten zu Umgebungsvariablen (`providerAuthEnvVars`, `channelEnvVars`) sind nur deklarativ. Status-, Audit-, Validierung von Cron-Zustellung und andere schreibgeschützte Oberflächen wenden weiterhin Plugin-Vertrauen und effektive Aktivierungsrichtlinien an, bevor eine Umgebungsvariable als konfiguriert behandelt wird.
- Für Laufzeit-Wizard-Metadaten, die Provider-Code benötigen, siehe [Provider runtime hooks](/de/plugins/architecture-internals#provider-runtime-hooks).
- Metadaten zu Umgebungsvariablen (`providerAuthEnvVars`, `channelEnvVars`) sind nur deklarativ. Status, Audit, Validierung der Cron-Zustellung und andere schreibgeschützte Oberflächen wenden weiterhin Plugin-Vertrauen und effektive Aktivierungsrichtlinien an, bevor eine Umgebungsvariable als konfiguriert behandelt wird.
- Für Metadaten des Laufzeit-Assistenten, die Providercode erfordern, siehe [Provider runtime hooks](/de/plugins/architecture-internals#provider-runtime-hooks).
- Wenn Ihr Plugin von nativen Modulen abhängt, dokumentieren Sie die Build-Schritte und alle Anforderungen an die Allowlist des Paketmanagers (zum Beispiel pnpm `allow-build-scripts` + `pnpm rebuild <package>`).
## Verwandt
<CardGroup cols={3}>
<Card title="Plugins bauen" href="/de/plugins/building-plugins" icon="rocket">
Einstieg in Plugins.
<Card title="Plugins erstellen" href="/de/plugins/building-plugins" icon="rocket">
Erste Schritte mit Plugins.
</Card>
<Card title="Plugin-Architektur" href="/de/plugins/architecture" icon="diagram-project">
Interne Architektur und Fähigkeitsmodell.
Interne Architektur und Capability-Modell.
</Card>
<Card title="SDK-Überblick" href="/de/plugins/sdk-overview" icon="book">
Referenz zum Plugin-SDK und Imports über Unterpfade.
Plugin-SDK-Referenz und Subpath-Importe.
</Card>
</CardGroup>

503
docs/de/plugins/sdk-migration.md
View File

@ -1,77 +1,77 @@
---
read_when:
- Sie sehen die Warnung OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
- Sie sehen die Warnung OPENCLAW_EXTENSION_API_DEPRECATED
- Sie aktualisieren ein Plugin auf die moderne Plugin-Architektur
- Sie betreuen ein externes OpenClaw-Plugin
- Du siehst die Warnung `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED`
- Du siehst die Warnung `OPENCLAW_EXTENSION_API_DEPRECATED`
- Du aktualisierst ein Plugin auf die moderne Plugin-Architektur
- Du pflegst ein externes OpenClaw-Plugin
sidebarTitle: Migrate to SDK
summary: Von der Legacy-Abwärtskompatibilitätsschicht zum modernen Plugin-SDK migrieren
summary: Von der alten Abwärtskompatibilitätsschicht auf das moderne Plugin-SDK migrieren
title: Plugin-SDK-Migration
x-i18n:
generated_at: "2026-04-24T06:50:55Z"
generated_at: "2026-04-24T08:59:58Z"
model: gpt-5.4
provider: openai
source_hash: d1612fbdc0e472a0ba1ae310ceeca9c672afa5a7eba77637b94726ef1fedee87
source_hash: d1461ae8a7de0a802c9deb59f843e7d93d9d73bea22c27d837ca2db8ae9d14b7
source_path: plugins/sdk-migration.md
workflow: 15
---
OpenClaw ist von einer breiten Abwärtskompatibilitätsschicht zu einer modernen Plugin-
Architektur mit fokussierten, dokumentierten Imports übergegangen. Wenn Ihr Plugin vor
der neuen Architektur erstellt wurde, hilft Ihnen dieser Leitfaden bei der Migration.
OpenClaw hat sich von einer breiten Abwärtskompatibilitätsschicht zu einer modernen Plugin-
Architektur mit fokussierten, dokumentierten Imports weiterentwickelt. Wenn dein Plugin vor
der neuen Architektur erstellt wurde, hilft dir diese Anleitung bei der Migration.
## Was sich ändert
Das alte Plugin-System stellte zwei sehr offene Oberflächen bereit, über die Plugins
Das alte Plugin-System stellte zwei sehr offene Flächen bereit, über die Plugins
alles importieren konnten, was sie über einen einzigen Einstiegspunkt benötigten:
- **`openclaw/plugin-sdk/compat`** — ein einzelner Import, der Dutzende von
Hilfsfunktionen erneut exportierte. Er wurde eingeführt, damit ältere hookbasierte Plugins weiter funktionieren, während die
neue Plugin-Architektur aufgebaut wurde.
Helfern re-exportierte. Er wurde eingeführt, damit ältere Hook-basierte Plugins weiter funktionieren,
während die neue Plugin-Architektur aufgebaut wurde.
- **`openclaw/extension-api`** — eine Brücke, die Plugins direkten Zugriff auf
hostseitige Hilfsfunktionen wie den eingebetteten Agenten-Runner gab.
Host-seitige Helfer wie den eingebetteten Agent-Runner gab.
Beide Oberflächen sind jetzt **veraltet**. Sie funktionieren zur Laufzeit noch, aber neue
Plugins dürfen sie nicht mehr verwenden, und bestehende Plugins sollten migrieren, bevor
die nächste Hauptversion sie entfernt.
Beide Flächen sind jetzt **deprecated**. Sie funktionieren zur Laufzeit weiterhin, aber neue
Plugins dürfen sie nicht verwenden, und bestehende Plugins sollten migrieren, bevor die nächste
Major-Release sie entfernt.
OpenClaw entfernt oder interpretiert dokumentiertes Plugin-Verhalten nicht in derselben
Änderung neu, in der ein Ersatz eingeführt wird. Änderungen an brechenden Verträgen müssen zuerst
über einen Kompatibilitätsadapter, Diagnostik, Dokumentation und ein Deprecation-Fenster laufen.
Das gilt für SDK-Imports, Manifest-Felder, Setup-APIs, Hooks und das Verhalten bei der Laufzeitregistrierung.
Änderung neu, in der ein Ersatz eingeführt wird. Breaking-Contract-Änderungen müssen zuerst
über einen Kompatibilitätsadapter, Diagnostik, Dokumentation und ein Deprecation-Zeitfenster laufen.
Das gilt für SDK-Imports, Manifest-Felder, Setup-APIs, Hooks und das Laufzeitverhalten bei der Registrierung.
<Warning>
Die Abwärtskompatibilitätsschicht wird in einer zukünftigen Hauptversion entfernt.
Plugins, die weiterhin aus diesen Oberflächen importieren, werden dann nicht mehr funktionieren.
Die Abwärtskompatibilitätsschicht wird in einer zukünftigen Major-Release entfernt.
Plugins, die weiterhin von diesen Flächen importieren, werden dann nicht mehr funktionieren.
</Warning>
## Warum sich das geändert hat
Der alte Ansatz verursachte Probleme:
- **Langsamer Start** — der Import einer Hilfsfunktion lud Dutzende nicht zusammenhängende Module
- **Zirkuläre Abhängigkeiten** — breite Re-Exports machten es einfach, Import-Zyklen zu erzeugen
- **Unklare API-Oberfläche** — es gab keine Möglichkeit zu erkennen, welche Exporte stabil und welche intern waren
- **Langsamer Start** — beim Import eines Helfers wurden Dutzende nicht zusammenhängende Module geladen
- **Zirkuläre Abhängigkeiten** — breite Re-Exports machten es leicht, Import-Zyklen zu erzeugen
- **Unklare API-Fläche** — es gab keine Möglichkeit zu erkennen, welche Exporte stabil bzw. intern waren
Das moderne Plugin-SDK behebt dies: Jeder Importpfad (`openclaw/plugin-sdk/\<subpath\>`)
ist ein kleines, in sich geschlossenes Modul mit klarem Zweck und dokumentiertem Vertrag.
Das moderne Plugin-SDK behebt das: Jeder Importpfad (`openclaw/plugin-sdk/\<subpath\>`)
ist ein kleines, in sich abgeschlossenes Modul mit klarem Zweck und dokumentiertem Vertrag.
Legacy-Komfort-Schnittstellen für Provider in gebündelten Kanälen sind ebenfalls verschwunden. Imports
Legacy-Provider-Comfort-Seams für gebündelte Kanäle sind ebenfalls entfernt. Imports
wie `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
kanalbezogene Hilfsschnittstellen mit Branding und
`openclaw/plugin-sdk/telegram-core` waren private Monorepo-Abkürzungen, keine
stabilen Plugin-Verträge. Verwenden Sie stattdessen schmale generische SDK-Unterpfade. Innerhalb des
gebündelten Plugin-Workspace bleiben provider-eigene Hilfsfunktionen in der eigenen
kanalgebrandete Helper-Seams und
`openclaw/plugin-sdk/telegram-core` waren private Mono-Repo-Shortcuts, keine
stabilen Plugin-Verträge. Verwende stattdessen schmale generische SDK-Subpaths. Innerhalb des
gebündelten Plugin-Workspace belasse Provider-eigene Helfer in der eigenen
`api.ts` oder `runtime-api.ts` dieses Plugins.
Aktuelle Beispiele gebündelter Provider:
Aktuelle Beispiele für gebündelte Provider:
- Anthropic hält Claude-spezifische Stream-Hilfsfunktionen in seiner eigenen Schnittstelle `api.ts` /
`contract-api.ts`
- OpenAI hält Provider-Builder, Hilfsfunktionen für Standardmodelle und Realtime-Provider-
Builder in seiner eigenen `api.ts`
- OpenRouter hält Provider-Builder sowie Hilfsfunktionen für Onboarding/Konfiguration in seiner eigenen
- Anthropic belässt Claude-spezifische Stream-Helfer in seinem eigenen `api.ts` /
`contract-api.ts`-Seam
- OpenAI belässt Provider-Builder, Default-Model-Helfer und Realtime-Provider-
Builder in seinem eigenen `api.ts`
- OpenRouter belässt Provider-Builder sowie Onboarding-/Konfigurationshelfer in seinem eigenen
`api.ts`
## Kompatibilitätsrichtlinie
@ -79,47 +79,48 @@ Aktuelle Beispiele gebündelter Provider:
Für externe Plugins folgt Kompatibilitätsarbeit dieser Reihenfolge:
1. den neuen Vertrag hinzufügen
2. das alte Verhalten über einen Kompatibilitätsadapter angeschlossen lassen
3. eine Diagnose oder Warnung ausgeben, die den alten Pfad und den Ersatz nennt
2. das alte Verhalten über einen Kompatibilitätsadapter weiterverdrahten
3. eine Diagnose oder Warnung ausgeben, die den alten Pfad und den Ersatz benennt
4. beide Pfade in Tests abdecken
5. die Deprecation und den Migrationspfad dokumentieren
6. erst nach dem angekündigten Migrationsfenster entfernen, normalerweise in einer Hauptversion
6. erst nach dem angekündigten Migrationszeitfenster entfernen, normalerweise in einer Major-Release
Wenn ein Manifest-Feld weiterhin akzeptiert wird, können Plugin-Autoren es weiter verwenden, bis
Dokumentation und Diagnostik etwas anderes sagen. Neuer Code sollte den dokumentierten
Ersatz bevorzugen, aber bestehende Plugins sollten in normalen Minor-Releases nicht kaputtgehen.
die Dokumentation und Diagnostik etwas anderes sagen. Neuer Code sollte den dokumentierten
Ersatz bevorzugen, aber bestehende Plugins sollten in gewöhnlichen Minor-Releases nicht kaputtgehen.
## Wie Sie migrieren
## So migrierst du
<Steps>
<Step title="Approval-native Handler auf Fähigkeitsfakten migrieren">
Approval-fähige Kanal-Plugins stellen natives Genehmigungsverhalten jetzt über
<Step title="Approval-native-Handler auf Capability-Fakten migrieren">
Approval-fähige Kanal-Plugins stellen natives Approval-Verhalten jetzt über
`approvalCapability.nativeRuntime` plus die gemeinsame Runtime-Context-Registry bereit.
Wichtige Änderungen:
- Ersetzen Sie `approvalCapability.handler.loadRuntime(...)` durch
- Ersetze `approvalCapability.handler.loadRuntime(...)` durch
`approvalCapability.nativeRuntime`
- Verschieben Sie approval-spezifische Auth/Zustellung weg von der Legacy-Verdrahtung `plugin.auth` /
`plugin.approvals` und auf `approvalCapability`
- `ChannelPlugin.approvals` wurde aus dem öffentlichen Vertrag für Kanal-Plugins
entfernt; verschieben Sie Zustell-/Native-/Render-Felder auf `approvalCapability`
- `plugin.auth` bleibt nur für Login-/Logout-Abläufe von Kanälen erhalten; Approval-Auth-
Hooks dort werden vom Core nicht mehr gelesen
- Registrieren Sie kanalbezogene Runtime-Objekte wie Clients, Tokens oder Bolt-
- Verschiebe Approval-spezifische Authentifizierung/Zustellung aus der Legacy-
Verdrahtung `plugin.auth` / `plugin.approvals` nach `approvalCapability`
- `ChannelPlugin.approvals` wurde aus dem öffentlichen Channel-Plugin-
Vertrag entfernt; verschiebe Zustellungs-/Native-/Render-Felder nach `approvalCapability`
- `plugin.auth` bleibt nur für Login-/Logout-Flows des Kanals bestehen; Approval-
Auth-Hooks dort werden vom Core nicht mehr gelesen
- Registriere kanal-eigene Runtime-Objekte wie Clients, Tokens oder Bolt-
Apps über `openclaw/plugin-sdk/channel-runtime-context`
- Senden Sie keine plugin-eigenen Umleitungs-Hinweise aus nativen Approval-Handlern;
der Core besitzt jetzt Hinweise vom Typ „routed elsewhere“ aus tatsächlichen Zustellergebnissen
- Wenn Sie `channelRuntime` an `createChannelManager(...)` übergeben, stellen Sie
eine echte `createPluginRuntime().channel`-Oberfläche bereit. Partielle Stubs werden abgelehnt.
- Sende keine Plugin-eigenen Reroute-Hinweise aus nativen Approval-Handlern;
der Core besitzt jetzt Routed-Elsewhere-Hinweise auf Basis tatsächlicher Zustellungsergebnisse
- Wenn du `channelRuntime` an `createChannelManager(...)` übergibst, stelle eine
echte `createPluginRuntime().channel`-Fläche bereit. Partielle Stubs werden abgelehnt.
Siehe `/plugins/sdk-channel-plugins` für das aktuelle Layout der Approval-Fähigkeiten.
Siehe `/plugins/sdk-channel-plugins` für das aktuelle Layout der Approval-Capability.
</Step>
<Step title="Fallback-Verhalten des Windows-Wrappers prüfen">
Wenn Ihr Plugin `openclaw/plugin-sdk/windows-spawn` verwendet, schlagen aufgelöste Windows-
Wrapper `.cmd`/`.bat` jetzt geschlossen fehl, sofern Sie nicht explizit `allowShellFallback: true` übergeben.
<Step title="Fallback-Verhalten des Windows-Wrapper prüfen">
Wenn dein Plugin `openclaw/plugin-sdk/windows-spawn` verwendet,
schlagen nicht aufgelöste Windows-Wrapper `.cmd`/`.bat` jetzt fail-closed fehl, sofern du nicht
ausdrücklich `allowShellFallback: true` übergibst.
```typescript
// Vorher
@ -128,19 +129,19 @@ Ersatz bevorzugen, aber bestehende Plugins sollten in normalen Minor-Releases ni
// Nachher
const program = applyWindowsSpawnProgramPolicy({
candidate,
// Nur für vertrauenswürdige Kompatibilitätsaufrufer setzen, die
// Shell-vermittelten Fallback bewusst akzeptieren.
// Setze dies nur für vertrauenswürdige Kompatibilitäts-Caller, die
// bewusst einen shell-vermittelten Fallback akzeptieren.
allowShellFallback: true,
});
```
Wenn Ihr Aufrufer nicht absichtlich auf Shell-Fallback angewiesen ist, setzen Sie
`allowShellFallback` nicht und behandeln Sie stattdessen den ausgelösten Fehler.
Wenn dein Caller nicht absichtlich auf Shell-Fallback angewiesen ist, setze
`allowShellFallback` nicht und behandle stattdessen den ausgelösten Fehler.
</Step>
<Step title="Veraltete Imports finden">
Durchsuchen Sie Ihr Plugin nach Imports aus einer der beiden veralteten Oberflächen:
<Step title="Deprecated Imports finden">
Durchsuche dein Plugin nach Imports aus einer der beiden deprecated Flächen:
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -150,10 +151,10 @@ Ersatz bevorzugen, aber bestehende Plugins sollten in normalen Minor-Releases ni
</Step>
<Step title="Durch fokussierte Imports ersetzen">
Jeder Export aus der alten Oberfläche wird auf einen bestimmten modernen Importpfad abgebildet:
Jeder Export aus der alten Fläche wird einem spezifischen modernen Importpfad zugeordnet:
```typescript
// Vorher (veraltete Abwärtskompatibilitätsschicht)
// Vorher (deprecated Abwärtskompatibilitätsschicht)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
@ -166,11 +167,10 @@ Ersatz bevorzugen, aber bestehende Plugins sollten in normalen Minor-Releases ni
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
Verwenden Sie für hostseitige Hilfsfunktionen die injizierte Plugin-Runtime statt eines
direkten Imports:
Verwende für Host-seitige Helfer die injizierte Plugin-Runtime, statt direkt zu importieren:
```typescript
// Vorher (veraltete extension-api-Brücke)
// Vorher (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
@ -178,9 +178,9 @@ Ersatz bevorzugen, aber bestehende Plugins sollten in normalen Minor-Releases ni
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
Dasselbe Muster gilt für andere Legacy-Hilfsfunktionen der Brücke:
Dasselbe Muster gilt für andere Legacy-Bridge-Helfer:
| Alter Import | Moderner Ersatz |
| Alter Import | Modernes Äquivalent |
| --- | --- |
| `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
| `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
@ -188,11 +188,11 @@ Ersatz bevorzugen, aber bestehende Plugins sollten in normalen Minor-Releases ni
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
| Hilfsfunktionen für den Session-Store | `api.runtime.agent.session.*` |
| Session-Store-Helfer | `api.runtime.agent.session.*` |
</Step>
<Step title="Bauen und testen">
<Step title="Build und Tests ausführen">
```bash
pnpm build
pnpm test -- my-plugin/
@ -205,183 +205,182 @@ Ersatz bevorzugen, aber bestehende Plugins sollten in normalen Minor-Releases ni
<Accordion title="Tabelle häufiger Importpfade">
| Importpfad | Zweck | Wichtige Exporte |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | Kanonischer Plugin-Entry-Helper | `definePluginEntry` |
| `plugin-sdk/core` | Legacy-Sammel-Re-Export für Kanal-Entry-Definitionen/-Builder | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/plugin-entry` | Kanonischer Hilfsbaustein für Plugin-Einstiegspunkte | `definePluginEntry` |
| `plugin-sdk/core` | Legacy-Umbrella-Re-Export für Kanal-Einstiegsdefinitionen/-Builder | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Export des Root-Konfigurationsschemas | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Single-Provider-Entry-Helper | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Fokussierte Kanal-Entry-Definitionen und -Builder | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Gemeinsame Setup-Assistenten-Helfer | Allowlist-Prompts, Builder für Setup-Status |
| `plugin-sdk/setup-runtime` | Laufzeit-Helfer zur Setup-Zeit | import-sichere Setup-Patch-Adapter, Hilfsfunktionen für Lookup-Notizen, `promptResolvedAllowFrom`, `splitSetupEntries`, delegierte Setup-Proxys |
| `plugin-sdk/setup-adapter-runtime` | Helfer für Setup-Adapter | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Helfer für Setup-Tooling | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helfer für mehrere Accounts | Hilfsfunktionen für Account-Liste/Konfiguration/Aktions-Gates |
| `plugin-sdk/account-id` | Account-ID-Helfer | `DEFAULT_ACCOUNT_ID`, Normalisierung von Account-IDs |
| `plugin-sdk/account-resolution` | Helfer für Account-Lookups | Account-Lookup- und Default-Fallback-Helfer |
| `plugin-sdk/account-helpers` | Schmale Account-Helfer | Hilfsfunktionen für Account-Liste/Account-Aktionen |
| `plugin-sdk/provider-entry` | Hilfsbaustein für Ein-Provider-Einstiegspunkte | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Fokussierte Kanal-Einstiegsdefinitionen und -Builder | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Gemeinsame Hilfsbausteine für Setup-Assistenten | Allowlist-Abfragen, Setup-Status-Builder |
| `plugin-sdk/setup-runtime` | Runtime-Hilfsbausteine für das Setup | import-sichere Setup-Patch-Adapter, Lookup-Note-Hilfsbausteine, `promptResolvedAllowFrom`, `splitSetupEntries`, delegierte Setup-Proxys |
| `plugin-sdk/setup-adapter-runtime` | Hilfsbausteine für Setup-Adapter | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Hilfsbausteine für Setup-Tools | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Hilfsbausteine für mehrere Accounts | Hilfsbausteine für Account-Liste/Konfiguration/Action-Gate |
| `plugin-sdk/account-id` | Hilfsbausteine für Account-IDs | `DEFAULT_ACCOUNT_ID`, Normalisierung von Account-IDs |
| `plugin-sdk/account-resolution` | Hilfsbausteine für Account-Lookup | Hilfsbausteine für Account-Lookup + Default-Fallback |
| `plugin-sdk/account-helpers` | Schmale Account-Hilfsbausteine | Hilfsbausteine für Account-Liste/Account-Aktionen |
| `plugin-sdk/channel-setup` | Adapter für Setup-Assistenten | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitive für DM-Pairing | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Verdrahtung von Antwort-Präfix + Tippen | `createChannelReplyPipeline` |
| `plugin-sdk/channel-reply-pipeline` | Verdrahtung von Antwortpräfix + Tippstatus | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | Fabriken für Konfigurationsadapter | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Builder für Konfigurationsschemata | Typen für Kanal-Konfigurationsschemata |
| `plugin-sdk/telegram-command-config` | Helfer für Telegram-Befehlskonfiguration | Normalisierung von Befehlsnamen, Kürzen von Beschreibungen, Validierung von Duplikaten/Konflikten |
| `plugin-sdk/channel-config-schema` | Builder für Konfigurationsschemata | Typen für Kanal-Konfigurationsschema |
| `plugin-sdk/telegram-command-config` | Hilfsbausteine für Telegram-Befehlskonfiguration | Normalisierung von Befehlsnamen, Kürzen von Beschreibungen, Prüfung auf Duplikate/Konflikte |
| `plugin-sdk/channel-policy` | Auflösung von Gruppen-/DM-Richtlinien | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Helfer für Account-Status und Lebenszyklus von Entwurfs-Streams | `createAccountStatusSink`, Helfer zur Finalisierung von Entwurfs-Vorschauen |
| `plugin-sdk/inbound-envelope` | Helfer für Inbound-Envelope | Gemeinsame Helfer zum Erstellen von Routen + Envelopes |
| `plugin-sdk/inbound-reply-dispatch` | Helfer für eingehende Antworten | Gemeinsame Helfer für Aufzeichnen-und-Dispatch |
| `plugin-sdk/messaging-targets` | Parsen von Messaging-Zielen | Hilfsfunktionen zum Parsen/Abgleichen von Zielen |
| `plugin-sdk/outbound-media` | Helfer für ausgehende Medien | Gemeinsames Laden ausgehender Medien |
| `plugin-sdk/outbound-runtime` | Laufzeit-Helfer für ausgehende Nachrichten | Helfer für ausgehende Identität/Sende-Delegation und Nutzlastplanung |
| `plugin-sdk/thread-bindings-runtime` | Helfer für Thread-Bindings | Helfer für Lebenszyklus und Adapter von Thread-Bindings |
| `plugin-sdk/agent-media-payload` | Legacy-Helfer für Medien-Payloads | Builder für Agent-Medien-Payloads für Legacy-Feldlayouts |
| `plugin-sdk/channel-runtime` | Veralteter Kompatibilitäts-Shim | Nur Legacy-Utilities für Kanal-Laufzeit |
| `plugin-sdk/channel-lifecycle` | Hilfsbausteine für Account-Status und Draft-Stream-Lifecycle | `createAccountStatusSink`, Hilfsbausteine für die Finalisierung von Draft-Previews |
| `plugin-sdk/inbound-envelope` | Hilfsbausteine für Inbound-Envelopes | Gemeinsame Hilfsbausteine für Route + Envelope-Builder |
| `plugin-sdk/inbound-reply-dispatch` | Hilfsbausteine für Inbound-Antworten | Gemeinsame Hilfsbausteine für Record-and-Dispatch |
| `plugin-sdk/messaging-targets` | Parsing von Messaging-Zielen | Hilfsbausteine für Parsing/Abgleich von Zielen |
| `plugin-sdk/outbound-media` | Hilfsbausteine für Outbound-Medien | Gemeinsames Laden von Outbound-Medien |
| `plugin-sdk/outbound-runtime` | Runtime-Hilfsbausteine für Outbound | Hilfsbausteine für Outbound-Identität/Send-Delegate und Payload-Planung |
| `plugin-sdk/thread-bindings-runtime` | Hilfsbausteine für Thread-Bindings | Hilfsbausteine für Lifecycle und Adapter von Thread-Bindings |
| `plugin-sdk/agent-media-payload` | Legacy-Hilfsbausteine für Media-Payloads | Builder für Agent-Media-Payload bei Legacy-Feldlayouts |
| `plugin-sdk/channel-runtime` | Deprecated Kompatibilitäts-Shim | Nur Legacy-Hilfsbausteine für Kanal-Runtime |
| `plugin-sdk/channel-send-result` | Typen für Sendeergebnisse | Typen für Antwortergebnisse |
| `plugin-sdk/runtime-store` | Persistenter Plugin-Speicher | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Breite Laufzeit-Helfer | Helfer für Laufzeit/Logging/Backups/Plugin-Installationen |
| `plugin-sdk/runtime-env` | Schmale Helfer für Laufzeit-Umgebungen | Logger-/Laufzeit-Umgebung, Timeout-, Retry- und Backoff-Helfer |
| `plugin-sdk/plugin-runtime` | Gemeinsame Plugin-Laufzeit-Helfer | Gemeinsame Helfer für Plugin-Befehle/Hooks/HTTP/Interaktivität |
| `plugin-sdk/hook-runtime` | Helfer für Hook-Pipelines | Gemeinsame Helfer für Webhook-/interne Hook-Pipelines |
| `plugin-sdk/lazy-runtime` | Lazy-Runtime-Helfer | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Prozess-Helfer | Gemeinsame Exec-Helfer |
| `plugin-sdk/cli-runtime` | CLI-Laufzeit-Helfer | Befehlsformatierung, Waits, Versions-Helfer |
| `plugin-sdk/gateway-runtime` | Gateway-Helfer | Gateway-Client und Helfer für Patches des Kanalstatus |
| `plugin-sdk/config-runtime` | Konfigurations-Helfer | Helfer zum Laden/Schreiben von Konfiguration |
| `plugin-sdk/telegram-command-config` | Telegram-Befehlshelfer | Fallback-stabile Telegram-Befehlsvalidierungshelfer, wenn die gebündelte Telegram-Vertragsoberfläche nicht verfügbar ist |
| `plugin-sdk/approval-runtime` | Helfer für Genehmigungs-Prompts | Payloads für Exec-/Plugin-Genehmigungen, Helfer für Genehmigungsfähigkeiten/-profile, native Helfer für Routing/Laufzeit von Genehmigungen |
| `plugin-sdk/approval-auth-runtime` | Helfer für Genehmigungs-Auth | Auflösung von Genehmigern, Auth von Aktionen im selben Chat |
| `plugin-sdk/approval-client-runtime` | Helfer für Genehmigungs-Clients | Native Helfer für Profile/Filter von Exec-Genehmigungen |
| `plugin-sdk/approval-delivery-runtime` | Helfer für Genehmigungszustellung | Adapter für native Genehmigungsfähigkeiten/-zustellung |
| `plugin-sdk/approval-gateway-runtime` | Helfer für Genehmigungs-Gateway | Gemeinsamer Helfer zur Auflösung des Genehmigungs-Gateway |
| `plugin-sdk/approval-handler-adapter-runtime` | Helfer für Genehmigungs-Adapter | Leichtgewichtige Lade-Helfer für native Genehmigungsadapter bei hot channel entrypoints |
| `plugin-sdk/approval-handler-runtime` | Helfer für Genehmigungs-Handler | Umfassendere Laufzeit-Helfer für Genehmigungs-Handler; bevorzugen Sie die schmaleren Adapter-/Gateway-Schnittstellen, wenn diese ausreichen |
| `plugin-sdk/approval-native-runtime` | Helfer für Genehmigungsziele | Native Helfer für Ziel-/Account-Bindung von Genehmigungen |
| `plugin-sdk/approval-reply-runtime` | Helfer für Genehmigungsantworten | Helfer für Antwort-Payloads von Exec-/Plugin-Genehmigungen |
| `plugin-sdk/channel-runtime-context` | Helfer für Channel Runtime Context | Generische Helfer zum Registrieren/Abrufen/Beobachten von Channel Runtime Context |
| `plugin-sdk/security-runtime` | Sicherheits-Helfer | Gemeinsame Helfer für Vertrauen, DM-Gating, externe Inhalte und Secret-Sammlung |
| `plugin-sdk/ssrf-policy` | Helfer für SSRF-Richtlinien | Helfer für Host-Allowlist und Richtlinien für private Netzwerke |
| `plugin-sdk/ssrf-runtime` | SSRF-Laufzeit-Helfer | Helfer für pinned dispatcher, guarded fetch und SSRF-Richtlinien |
| `plugin-sdk/collection-runtime` | Helfer für begrenzte Caches | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Helfer für Diagnostic-Gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helfer für Fehlerformatierung | `formatUncaughtError`, `isApprovalNotFoundError`, Helfer für Fehlergraphen |
| `plugin-sdk/fetch-runtime` | Helfer für gewrapptes Fetch/Proxy | `resolveFetch`, Proxy-Helfer |
| `plugin-sdk/host-runtime` | Helfer für Host-Normalisierung | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Retry-Helfer | `RetryConfig`, `retryAsync`, Policy-Runner |
| `plugin-sdk/runtime` | Breite Runtime-Hilfsbausteine | Hilfsbausteine für Runtime/Logging/Backup/Plugin-Installation |
| `plugin-sdk/runtime-env` | Schmale Hilfsbausteine für Runtime-Umgebung | Logger-/Runtime-Umgebung, Timeout-, Retry- und Backoff-Hilfsbausteine |
| `plugin-sdk/plugin-runtime` | Gemeinsame Hilfsbausteine für Plugin-Runtime | Hilfsbausteine für Plugin-Befehle/Hooks/HTTP/interaktive Funktionen |
| `plugin-sdk/hook-runtime` | Hilfsbausteine für Hook-Pipelines | Gemeinsame Hilfsbausteine für Webhook-/interne Hook-Pipelines |
| `plugin-sdk/lazy-runtime` | Hilfsbausteine für Lazy Runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Hilfsbausteine für Prozesse | Gemeinsame Hilfsbausteine für exec |
| `plugin-sdk/cli-runtime` | Hilfsbausteine für CLI-Runtime | Hilfsbausteine für Befehlsformatierung, Waits, Versionshelfer |
| `plugin-sdk/gateway-runtime` | Hilfsbausteine für Gateway | Hilfsbausteine für Gateway-Client und Channel-Status-Patches |
| `plugin-sdk/config-runtime` | Hilfsbausteine für Konfiguration | Hilfsbausteine zum Laden/Schreiben von Konfiguration |
| `plugin-sdk/telegram-command-config` | Hilfsbausteine für Telegram-Befehle | Fallback-stabile Prüfung von Telegram-Befehlen, wenn die gebündelte Telegram-Vertragsfläche nicht verfügbar ist |
| `plugin-sdk/approval-runtime` | Hilfsbausteine für Approval-Prompts | Payload für exec-/Plugin-Approval, Hilfsbausteine für Approval-Capability/-Profil, native Approval-Routing-/Runtime-Hilfsbausteine |
| `plugin-sdk/approval-auth-runtime` | Hilfsbausteine für Approval-Authentifizierung | Auflösung von Approvern, Same-Chat-Action-Auth |
| `plugin-sdk/approval-client-runtime` | Hilfsbausteine für Approval-Clients | Hilfsbausteine für native exec-Approval-Profile/-Filter |
| `plugin-sdk/approval-delivery-runtime` | Hilfsbausteine für Approval-Zustellung | Adapter für native Approval-Capability/-Zustellung |
| `plugin-sdk/approval-gateway-runtime` | Hilfsbausteine für Approval-Gateway | Gemeinsamer Hilfsbaustein zur Auflösung von Approval-Gateway |
| `plugin-sdk/approval-handler-adapter-runtime` | Hilfsbausteine für Approval-Adapter | Leichtgewichtige Hilfsbausteine zum Laden nativer Approval-Adapter für heiße Kanal-Einstiegspunkte |
| `plugin-sdk/approval-handler-runtime` | Hilfsbausteine für Approval-Handler | Umfassendere Runtime-Hilfsbausteine für Approval-Handler; bevorzuge die schmaleren Adapter-/Gateway-Seams, wenn sie ausreichen |
| `plugin-sdk/approval-native-runtime` | Hilfsbausteine für Approval-Ziele | Hilfsbausteine für native Approval-Ziel-/Account-Bindings |
| `plugin-sdk/approval-reply-runtime` | Hilfsbausteine für Approval-Antworten | Hilfsbausteine für Antwort-Payloads bei exec-/Plugin-Approval |
| `plugin-sdk/channel-runtime-context` | Hilfsbausteine für Kanal-Runtime-Context | Generische Hilfsbausteine zum Registrieren/Abrufen/Beobachten von Kanal-Runtime-Context |
| `plugin-sdk/security-runtime` | Hilfsbausteine für Sicherheit | Gemeinsame Hilfsbausteine für Trust, DM-Gating, externe Inhalte und Secret-Erfassung |
| `plugin-sdk/ssrf-policy` | Hilfsbausteine für SSRF-Richtlinien | Hilfsbausteine für Host-Allowlist und Richtlinien für private Netzwerke |
| `plugin-sdk/ssrf-runtime` | Runtime-Hilfsbausteine für SSRF | Hilfsbausteine für Pinned-Dispatcher, geschütztes Fetch, SSRF-Richtlinien |
| `plugin-sdk/collection-runtime` | Hilfsbausteine für begrenzte Caches | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Hilfsbausteine für Diagnostic-Gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Hilfsbausteine für Fehlerformatierung | `formatUncaughtError`, `isApprovalNotFoundError`, Hilfsbausteine für Fehlergraphen |
| `plugin-sdk/fetch-runtime` | Hilfsbausteine für Wrapped Fetch/Proxy | `resolveFetch`, Proxy-Hilfsbausteine |
| `plugin-sdk/host-runtime` | Hilfsbausteine für Host-Normalisierung | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Hilfsbausteine für Retry | `RetryConfig`, `retryAsync`, Policy-Runner |
| `plugin-sdk/allow-from` | Formatierung von Allowlists | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mapping von Allowlist-Eingaben | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Befehls-Gating und Helfer für Befehlsoberflächen | `resolveControlCommandGate`, Helfer für Sender-Autorisierung, Helfer für Befehls-Registry |
| `plugin-sdk/command-status` | Renderer für Befehlsstatus/-hilfe | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Parsen von Secret-Eingaben | Helfer für Secret-Eingaben |
| `plugin-sdk/webhook-ingress` | Helfer für Webhook-Anfragen | Utilities für Webhook-Ziele |
| `plugin-sdk/webhook-request-guards` | Helfer für Guards von Webhook-Bodys | Helfer für das Lesen/Limitieren von Request-Bodys |
| `plugin-sdk/reply-runtime` | Gemeinsame Antwort-Laufzeit | Inbound-Dispatch, Heartbeat, Antwort-Planer, Chunking |
| `plugin-sdk/reply-dispatch-runtime` | Schmale Helfer für Antwort-Dispatch | Helfer für Finalisierung + Provider-Dispatch |
| `plugin-sdk/reply-history` | Helfer für Antwort-Historie | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/allowlist-resolution` | Zuordnung von Allowlist-Eingaben | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Hilfsbausteine für Command-Gating und Command-Surfaces | `resolveControlCommandGate`, Hilfsbausteine für Sender-Autorisierung, Hilfsbausteine für Befehlsregistrierung |
| `plugin-sdk/command-status` | Renderer für Command-Status/Hilfe | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Parsing von Secret-Eingaben | Hilfsbausteine für Secret-Eingaben |
| `plugin-sdk/webhook-ingress` | Hilfsbausteine für Webhook-Requests | Hilfsbausteine für Webhook-Ziele |
| `plugin-sdk/webhook-request-guards` | Hilfsbausteine für Guards von Webhook-Request-Bodies | Hilfsbausteine zum Lesen/Begrenzen von Request-Bodies |
| `plugin-sdk/reply-runtime` | Gemeinsame Antwort-Runtime | Inbound-Dispatch, Heartbeat, Reply-Planer, Chunking |
| `plugin-sdk/reply-dispatch-runtime` | Schmale Hilfsbausteine für Reply-Dispatch | Finalisierung, Provider-Dispatch und Hilfsbausteine für Konversationslabels |
| `plugin-sdk/reply-history` | Hilfsbausteine für Antwortverlauf | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | Planung von Antwortreferenzen | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helfer für Antwort-Chunks | Helfer für Text-/Markdown-Chunking |
| `plugin-sdk/session-store-runtime` | Helfer für Session-Store | Helfer für Store-Pfad + updated-at |
| `plugin-sdk/state-paths` | Helfer für Statuspfade | Helfer für Status- und OAuth-Verzeichnisse |
| `plugin-sdk/routing` | Helfer für Routing-/Session-Keys | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, Helfer zur Normalisierung von Session-Keys |
| `plugin-sdk/status-helpers` | Helfer für Kanalstatus | Builder für Zusammenfassungen von Kanal-/Account-Status, Standardwerte für Laufzeitstatus, Helfer für Issue-Metadaten |
| `plugin-sdk/target-resolver-runtime` | Helfer für Zielauflösung | Gemeinsame Helfer für Zielauflösung |
| `plugin-sdk/string-normalization-runtime` | Helfer für String-Normalisierung | Helfer für Slug-/String-Normalisierung |
| `plugin-sdk/request-url` | Helfer für Request-URLs | String-URLs aus Request-ähnlichen Eingaben extrahieren |
| `plugin-sdk/run-command` | Helfer für zeitgesteuerte Befehle | Runner für zeitgesteuerte Befehle mit normalisiertem stdout/stderr |
| `plugin-sdk/param-readers` | Parameterleser | Gemeinsame Parameterleser für Tools/CLI |
| `plugin-sdk/tool-payload` | Extraktion von Tool-Payloads | Normalisierte Payloads aus Tool-Ergebnisobjekten extrahieren |
| `plugin-sdk/reply-chunking` | Hilfsbausteine für Antwort-Chunking | Hilfsbausteine für Text-/Markdown-Chunking |
| `plugin-sdk/session-store-runtime` | Hilfsbausteine für Session-Store | Hilfsbausteine für Store-Pfad + updated-at |
| `plugin-sdk/state-paths` | Hilfsbausteine für State-Pfade | Hilfsbausteine für State- und OAuth-Verzeichnisse |
| `plugin-sdk/routing` | Hilfsbausteine für Routing/Session-Key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, Hilfsbausteine zur Normalisierung von Session-Keys |
| `plugin-sdk/status-helpers` | Hilfsbausteine für Kanalstatus | Builder für Kanal-/Account-Statuszusammenfassungen, Defaults für Runtime-State, Hilfsbausteine für Issue-Metadaten |
| `plugin-sdk/target-resolver-runtime` | Hilfsbausteine für Zielauflösung | Gemeinsame Hilfsbausteine für Zielauflösung |
| `plugin-sdk/string-normalization-runtime` | Hilfsbausteine für String-Normalisierung | Hilfsbausteine für Slug-/String-Normalisierung |
| `plugin-sdk/request-url` | Hilfsbausteine für Request-URLs | String-URLs aus request-ähnlichen Eingaben extrahieren |
| `plugin-sdk/run-command` | Hilfsbausteine für zeitgesteuerte Befehle | Runner für zeitgesteuerte Befehle mit normalisiertem stdout/stderr |
| `plugin-sdk/param-readers` | Param-Reader | Gemeinsame Param-Reader für Tool/CLI |
| `plugin-sdk/tool-payload` | Extraktion von Tool-Payload | Normalisierte Payloads aus Tool-Ergebnisobjekten extrahieren |
| `plugin-sdk/tool-send` | Extraktion von Tool-Send | Kanonische Send-Zielfelder aus Tool-Argumenten extrahieren |
| `plugin-sdk/temp-path` | Helfer für Temp-Pfade | Gemeinsame Helfer für Temp-Download-Pfade |
| `plugin-sdk/logging-core` | Logging-Helfer | Subsystem-Logger und Redaktions-Helfer |
| `plugin-sdk/markdown-table-runtime` | Helfer für Markdown-Tabellen | Helfer für Markdown-Tabellenmodi |
| `plugin-sdk/reply-payload` | Typen für Nachrichtenantworten | Typen für Antwort-Payloads |
| `plugin-sdk/provider-setup` | Kuratierte Helfer für Setup lokaler/selbst gehosteter Provider | Helfer für Discovery/Konfiguration selbst gehosteter Provider |
| `plugin-sdk/self-hosted-provider-setup` | Fokussierte Helfer für OpenAI-kompatible selbst gehostete Provider | Dieselben Helfer für Discovery/Konfiguration selbst gehosteter Provider |
| `plugin-sdk/provider-auth-runtime` | Laufzeit-Helfer für Provider-Auth | Helfer zur Auflösung von API-Schlüsseln zur Laufzeit |
| `plugin-sdk/provider-auth-api-key` | Helfer für Setup von Provider-API-Schlüsseln | Helfer für API-Key-Onboarding/Profile-Writes |
| `plugin-sdk/provider-auth-result` | Helfer für Provider-Auth-Ergebnisse | Standard-Builder für OAuth-Auth-Ergebnisse |
| `plugin-sdk/provider-auth-login` | Helfer für interaktiven Provider-Login | Gemeinsame Helfer für interaktiven Login |
| `plugin-sdk/provider-selection-runtime` | Helfer für Providerauswahl | Auswahl konfigurierter oder automatischer Provider und Zusammenführen roher Provider-Konfiguration |
| `plugin-sdk/provider-env-vars` | Helfer für Provider-Umgebungsvariablen | Lookup-Helfer für Auth-Umgebungsvariablen von Providern |
| `plugin-sdk/provider-model-shared` | Gemeinsame Helfer für Provider-Modell/Replay | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Builder für Replay-Richtlinien, Helfer für Provider-Endpunkte und Helfer zur Normalisierung von Modell-IDs |
| `plugin-sdk/provider-catalog-shared` | Gemeinsame Helfer für Provider-Kataloge | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patches für Provider-Onboarding | Helfer für Onboarding-Konfiguration |
| `plugin-sdk/provider-http` | Provider-HTTP-Helfer | Generische Helfer für HTTP/Endpunkt-Fähigkeiten von Providern, einschließlich Multipart-Form-Helfern für Audiotranskription |
| `plugin-sdk/provider-web-fetch` | Helfer für Provider-Web-Fetch | Helfer für Registrierung/Cache von Web-Fetch-Providern |
| `plugin-sdk/provider-web-search-config-contract` | Helfer für Web-Search-Konfiguration von Providern | Schmale Helfer für Web-Search-Konfiguration/Anmeldedaten für Provider, die keine Verdrahtung zur Plugin-Aktivierung benötigen |
| `plugin-sdk/provider-web-search-contract` | Helfer für Web-Search-Verträge von Providern | Schmale Helfer für Verträge von Web-Search-Konfiguration/Anmeldedaten wie `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` und bereichsbezogene Setter/Getter für Anmeldedaten |
| `plugin-sdk/provider-web-search` | Helfer für Provider-Web-Search | Helfer für Registrierung/Cache/Laufzeit von Web-Search-Providern |
| `plugin-sdk/provider-tools` | Helfer für Provider-Tool-/Schema-Kompatibilität | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Schema-Bereinigung + Diagnostik für Gemini und xAI-Kompatibilitätshelfer wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helfer für Provider-Nutzung | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` und andere Helfer für Provider-Nutzung |
| `plugin-sdk/provider-stream` | Helfer für Provider-Stream-Wrapper | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Typen für Stream-Wrapper und gemeinsame Wrapper-Helfer für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Helfer für Provider-Transport | Native Helfer für Provider-Transport wie guarded fetch, Transport-Nachrichtentransformationen und beschreibbare Event-Streams für den Transport |
| `plugin-sdk/keyed-async-queue` | Geordnete asynchrone Queue | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Gemeinsame Medien-Helfer | Helfer für Media-Fetch/Transformation/Speicherung sowie Builder für Medien-Payloads |
| `plugin-sdk/media-generation-runtime` | Gemeinsame Helfer für Mediengenerierung | Gemeinsame Helfer für Failover, Kandidatenauswahl und Meldungen bei fehlenden Modellen für Bild-/Video-/Musikgenerierung |
| `plugin-sdk/media-understanding` | Helfer für Medienverständnis | Typen für Provider von Medienverständnis sowie bild-/audio-bezogene Exporte für Provider |
| `plugin-sdk/text-runtime` | Gemeinsame Text-Helfer | Strippen von für Assistenten sichtbarem Text, Helfer für Markdown-Rendern/Chunking/Tabellen, Redaktions-Helfer, Helfer für Directive-Tags, Safe-Text-Utilities und verwandte Text-/Logging-Helfer |
| `plugin-sdk/text-chunking` | Helfer für Text-Chunking | Helfer für Chunking ausgehenden Texts |
| `plugin-sdk/speech` | Speech-Helfer | Typen für Speech-Provider sowie providerseitige Helfer für Direktiven, Registry und Validierung |
| `plugin-sdk/speech-core` | Gemeinsamer Speech-Core | Typen für Speech-Provider, Registry, Direktiven, Normalisierung |
| `plugin-sdk/realtime-transcription` | Helfer für Realtime-Transkription | Typen für Provider, Helfer für Registry und gemeinsamer Helfer für WebSocket-Sitzungen |
| `plugin-sdk/realtime-voice` | Helfer für Realtime-Voice | Typen für Provider, Helfer für Registry/Auflösung und Bridge-Sitzungshelfer |
| `plugin-sdk/image-generation-core` | Gemeinsamer Core für Bildgenerierung | Typen für Bildgenerierung, Failover, Auth und Registry-Helfer |
| `plugin-sdk/music-generation` | Helfer für Musikgenerierung | Typen für Provider/Requests/Ergebnisse der Musikgenerierung |
| `plugin-sdk/music-generation-core` | Gemeinsamer Core für Musikgenerierung | Typen für Musikgenerierung, Failover-Helfer, Provider-Lookup und Parsing von Modell-Refs |
| `plugin-sdk/video-generation` | Helfer für Videogenerierung | Typen für Provider/Requests/Ergebnisse der Videogenerierung |
| `plugin-sdk/video-generation-core` | Gemeinsamer Core für Videogenerierung | Typen für Videogenerierung, Failover-Helfer, Provider-Lookup und Parsing von Modell-Refs |
| `plugin-sdk/interactive-runtime` | Helfer für interaktive Antworten | Normalisierung/Reduktion interaktiver Antwort-Payloads |
| `plugin-sdk/channel-config-primitives` | Primitive für Kanal-Konfiguration | Schmale Primitive für Kanal-Konfigurationsschemata |
| `plugin-sdk/channel-config-writes` | Helfer für Schreibvorgänge in Kanal-Konfigurationen | Helfer für Autorisierung von Schreibvorgängen in Kanal-Konfigurationen |
| `plugin-sdk/channel-plugin-common` | Gemeinsames Kanal-Prelude | Exporte des gemeinsamen Preludes für Kanal-Plugins |
| `plugin-sdk/channel-status` | Helfer für Kanalstatus | Gemeinsame Helfer für Snapshots/Zusammenfassungen des Kanalstatus |
| `plugin-sdk/allowlist-config-edit` | Helfer für Allowlist-Konfiguration | Helfer zum Bearbeiten/Lesen von Allowlist-Konfigurationen |
| `plugin-sdk/group-access` | Helfer für Gruppenzugriff | Gemeinsame Helfer für Entscheidungen zum Gruppenzugriff |
| `plugin-sdk/direct-dm` | Helfer für direkte DMs | Gemeinsame Helfer für Auth/Guards direkter DMs |
| `plugin-sdk/extension-shared` | Gemeinsame Helfer für Extensions | Primitive für passive Kanäle/Status und Ambient-Proxy-Helfer |
| `plugin-sdk/webhook-targets` | Helfer für Webhook-Ziele | Registry für Webhook-Ziele und Helfer zur Installation von Routen |
| `plugin-sdk/webhook-path` | Helfer für Webhook-Pfade | Helfer zur Normalisierung von Webhook-Pfaden |
| `plugin-sdk/web-media` | Gemeinsame Helfer für Web-Medien | Helfer zum Laden von Remote-/lokalen Medien |
| `plugin-sdk/zod` | Re-Export von Zod | Re-exportiertes `zod` für Verbraucher des Plugin-SDK |
| `plugin-sdk/memory-core` | Gebündelte Helfer für memory-core | Helferoberfläche für Memory-Manager/Konfiguration/Dateien/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Laufzeit-Fassade der Memory-Engine | Laufzeit-Fassade für Memory-Index/Suche |
| `plugin-sdk/memory-core-host-engine-foundation` | Foundation-Engine des Memory-Hosts | Exporte der Foundation-Engine des Memory-Hosts |
| `plugin-sdk/memory-core-host-engine-embeddings` | Embedding-Engine des Memory-Hosts | Embedding-Verträge für Memory, Registry-Zugriff, lokaler Provider und generische Batch-/Remote-Helfer; konkrete Remote-Provider liegen in ihren jeweiligen Plugins |
| `plugin-sdk/memory-core-host-engine-qmd` | QMD-Engine des Memory-Hosts | Exporte der QMD-Engine des Memory-Hosts |
| `plugin-sdk/memory-core-host-engine-storage` | Storage-Engine des Memory-Hosts | Exporte der Storage-Engine des Memory-Hosts |
| `plugin-sdk/memory-core-host-multimodal` | Multimodale Helfer des Memory-Hosts | Multimodale Helfer des Memory-Hosts |
| `plugin-sdk/memory-core-host-query` | Query-Helfer des Memory-Hosts | Query-Helfer des Memory-Hosts |
| `plugin-sdk/memory-core-host-secret` | Secret-Helfer des Memory-Hosts | Secret-Helfer des Memory-Hosts |
| `plugin-sdk/memory-core-host-events` | Helfer für Event-Journal des Memory-Hosts | Helfer für Event-Journal des Memory-Hosts |
| `plugin-sdk/memory-core-host-status` | Status-Helfer des Memory-Hosts | Status-Helfer des Memory-Hosts |
| `plugin-sdk/memory-core-host-runtime-cli` | CLI-Laufzeit des Memory-Hosts | CLI-Laufzeit-Helfer des Memory-Hosts |
| `plugin-sdk/memory-core-host-runtime-core` | Core-Laufzeit des Memory-Hosts | Core-Laufzeit-Helfer des Memory-Hosts |
| `plugin-sdk/memory-core-host-runtime-files` | Datei-/Laufzeit-Helfer des Memory-Hosts | Datei-/Laufzeit-Helfer des Memory-Hosts |
| `plugin-sdk/memory-host-core` | Alias für Core-Laufzeit des Memory-Hosts | Herstellerneutraler Alias für Core-Laufzeit-Helfer des Memory-Hosts |
| `plugin-sdk/memory-host-events` | Alias für Event-Journal des Memory-Hosts | Herstellerneutraler Alias für Helfer des Event-Journals des Memory-Hosts |
| `plugin-sdk/memory-host-files` | Alias für Datei-/Laufzeit des Memory-Hosts | Herstellerneutraler Alias für Datei-/Laufzeit-Helfer des Memory-Hosts |
| `plugin-sdk/memory-host-markdown` | Helfer für Managed Markdown | Gemeinsame Helfer für Managed Markdown für speichernahe Plugins |
| `plugin-sdk/memory-host-search` | Fassade für Active Memory Search | Lazy-Laufzeit-Fassade des Search-Managers für Active Memory |
| `plugin-sdk/memory-host-status` | Alias für Status des Memory-Hosts | Herstellerneutraler Alias für Status-Helfer des Memory-Hosts |
| `plugin-sdk/memory-lancedb` | Gebündelte Helfer für memory-lancedb | Helferoberfläche für memory-lancedb |
| `plugin-sdk/testing` | Test-Utilities | Test-Helfer und Mocks |
| `plugin-sdk/temp-path` | Hilfsbausteine für temporäre Pfade | Gemeinsame Hilfsbausteine für Temp-Download-Pfade |
| `plugin-sdk/logging-core` | Hilfsbausteine für Logging | Subsystem-Logger und Hilfsbausteine für Redaction |
| `plugin-sdk/markdown-table-runtime` | Hilfsbausteine für Markdown-Tabellen | Hilfsbausteine für Markdown-Tabellenmodi |
| `plugin-sdk/reply-payload` | Typen für Nachrichtenantworten | Typen für Antwort-Payload |
| `plugin-sdk/provider-setup` | Kuratierte Hilfsbausteine für lokales/selbst gehostetes Provider-Setup | Hilfsbausteine für Discovery/Konfiguration selbst gehosteter Provider |
| `plugin-sdk/self-hosted-provider-setup` | Fokussierte Hilfsbausteine für das Setup selbst gehosteter OpenAI-kompatibler Provider | Dieselben Hilfsbausteine für Discovery/Konfiguration selbst gehosteter Provider |
| `plugin-sdk/provider-auth-runtime` | Runtime-Hilfsbausteine für Provider-Authentifizierung | Hilfsbausteine zur Auflösung von API-Keys zur Laufzeit |
| `plugin-sdk/provider-auth-api-key` | Hilfsbausteine für Setup von Provider-API-Keys | Hilfsbausteine für Onboarding/Profilschreiben von API-Keys |
| `plugin-sdk/provider-auth-result` | Hilfsbausteine für Provider-Authentifizierungsergebnisse | Standard-Builder für OAuth-Authentifizierungsergebnisse |
| `plugin-sdk/provider-auth-login` | Hilfsbausteine für interaktiven Provider-Login | Gemeinsame Hilfsbausteine für interaktiven Login |
| `plugin-sdk/provider-selection-runtime` | Hilfsbausteine für Providerauswahl | Auswahl konfigurierter oder automatischer Provider und Merging roher Provider-Konfiguration |
| `plugin-sdk/provider-env-vars` | Hilfsbausteine für Provider-Umgebungsvariablen | Hilfsbausteine für Lookup von Auth-Umgebungsvariablen von Providern |
| `plugin-sdk/provider-model-shared` | Gemeinsame Hilfsbausteine für Provider-Modell/Replay | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Builder für Replay-Richtlinien, Hilfsbausteine für Provider-Endpunkte und Hilfsbausteine zur Normalisierung von Model-IDs |
| `plugin-sdk/provider-catalog-shared` | Gemeinsame Hilfsbausteine für Provider-Kataloge | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patches für Provider-Onboarding | Hilfsbausteine für Onboarding-Konfiguration |
| `plugin-sdk/provider-http` | Hilfsbausteine für Provider-HTTP | Generische Hilfsbausteine für Provider-HTTP/Endpunkt-Capabilities, einschließlich Hilfsbausteinen für Multipart-Formulare bei Audio-Transkription |
| `plugin-sdk/provider-web-fetch` | Hilfsbausteine für Provider-Web-Fetch | Hilfsbausteine für Registrierung/Cache von Web-Fetch-Providern |
| `plugin-sdk/provider-web-search-config-contract` | Hilfsbausteine für Provider-Web-Search-Konfiguration | Schmale Hilfsbausteine für Web-Search-Konfiguration/Credentials bei Providern, die keine Verdrahtung zur Plugin-Aktivierung benötigen |
| `plugin-sdk/provider-web-search-contract` | Hilfsbausteine für Provider-Web-Search-Verträge | Schmale Hilfsbausteine für Web-Search-Konfigurations-/Credential-Verträge wie `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` und bereichsbezogene Setter/Getter für Credentials |
| `plugin-sdk/provider-web-search` | Hilfsbausteine für Provider-Web-Search | Hilfsbausteine für Registrierung/Cache/Runtime von Web-Search-Providern |
| `plugin-sdk/provider-tools` | Hilfsbausteine für Provider-Tool-/Schema-Kompatibilität | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini-Schema-Bereinigung + Diagnostik und xAI-Kompatibilitätshelfer wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Hilfsbausteine für Provider-Nutzung | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` und andere Hilfsbausteine für Provider-Nutzung |
| `plugin-sdk/provider-stream` | Hilfsbausteine für Provider-Stream-Wrapper | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Typen für Stream-Wrapper und gemeinsame Wrapper-Hilfsbausteine für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Hilfsbausteine für Provider-Transport | Native Hilfsbausteine für Provider-Transport wie geschütztes Fetch, Transformationen von Transportnachrichten und beschreibbare Transport-Event-Streams |
| `plugin-sdk/keyed-async-queue` | Geordnete Async-Queue | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Gemeinsame Hilfsbausteine für Medien | Hilfsbausteine für Medien-Fetch/Transformation/Speicherung plus Builder für Media-Payloads |
| `plugin-sdk/media-generation-runtime` | Gemeinsame Hilfsbausteine für Mediengenerierung | Gemeinsame Hilfsbausteine für Failover, Kandidatenauswahl und Meldungen bei fehlenden Modellen für Bild-/Video-/Musikgenerierung |
| `plugin-sdk/media-understanding` | Hilfsbausteine für Medienverständnis | Typen für Media-Understanding-Provider plus Provider-seitige Exporte von Bild-/Audio-Hilfsbausteinen |
| `plugin-sdk/text-runtime` | Gemeinsame Hilfsbausteine für Text | Entfernen von für Assistenten sichtbarem Text, Hilfsbausteine für Markdown-Rendering/Chunking/Tabellen, Hilfsbausteine für Redaction, Hilfsbausteine für Directive-Tags, Safe-Text-Utilities und verwandte Hilfsbausteine für Text/Logging |
| `plugin-sdk/text-chunking` | Hilfsbausteine für Text-Chunking | Hilfsbaustein für Outbound-Text-Chunking |
| `plugin-sdk/speech` | Hilfsbausteine für Sprache | Typen für Speech-Provider plus Provider-seitige Hilfsbausteine für Directives, Registry und Validierung |
| `plugin-sdk/speech-core` | Gemeinsamer Speech-Core | Typen für Speech-Provider, Registry, Directives, Normalisierung |
| `plugin-sdk/realtime-transcription` | Hilfsbausteine für Realtime-Transkription | Provider-Typen, Registry-Hilfsbausteine und gemeinsamer Hilfsbaustein für WebSocket-Sitzungen |
| `plugin-sdk/realtime-voice` | Hilfsbausteine für Realtime-Voice | Provider-Typen, Hilfsbausteine für Registry/Auflösung und Hilfsbausteine für Bridge-Sitzungen |
| `plugin-sdk/image-generation-core` | Gemeinsamer Core für Bildgenerierung | Typen, Failover-, Auth- und Registry-Hilfsbausteine für Bildgenerierung |
| `plugin-sdk/music-generation` | Hilfsbausteine für Musikgenerierung | Typen für Provider/Requests/Ergebnisse der Musikgenerierung |
| `plugin-sdk/music-generation-core` | Gemeinsamer Core für Musikgenerierung | Typen für Musikgenerierung, Hilfsbausteine für Failover, Provider-Lookup und Parsing von Model-Refs |
| `plugin-sdk/video-generation` | Hilfsbausteine für Videogenerierung | Typen für Provider/Requests/Ergebnisse der Videogenerierung |
| `plugin-sdk/video-generation-core` | Gemeinsamer Core für Videogenerierung | Typen für Videogenerierung, Hilfsbausteine für Failover, Provider-Lookup und Parsing von Model-Refs |
| `plugin-sdk/interactive-runtime` | Hilfsbausteine für interaktive Antworten | Normalisierung/Reduktion von Payloads für interaktive Antworten |
| `plugin-sdk/channel-config-primitives` | Primitive für Kanal-Konfiguration | Schmale Primitive für channel-config-schema |
| `plugin-sdk/channel-config-writes` | Hilfsbausteine für Schreibvorgänge in Kanal-Konfiguration | Hilfsbausteine für Autorisierung von Schreibvorgängen in Kanal-Konfiguration |
| `plugin-sdk/channel-plugin-common` | Gemeinsames Channel-Prelude | Exporte des gemeinsamen Channel-Plugin-Preludes |
| `plugin-sdk/channel-status` | Hilfsbausteine für Kanalstatus | Gemeinsame Hilfsbausteine für Snapshots/Zusammenfassungen des Kanalstatus |
| `plugin-sdk/allowlist-config-edit` | Hilfsbausteine für Allowlist-Konfiguration | Hilfsbausteine zum Bearbeiten/Lesen von Allowlist-Konfiguration |
| `plugin-sdk/group-access` | Hilfsbausteine für Gruppenzugriff | Gemeinsame Hilfsbausteine für Entscheidungen zum Gruppenzugriff |
| `plugin-sdk/direct-dm` | Hilfsbausteine für direkte DMs | Gemeinsame Hilfsbausteine für Auth/Guards direkter DMs |
| `plugin-sdk/extension-shared` | Gemeinsame Hilfsbausteine für Extensions | Primitive Hilfsbausteine für Passive-Channel/Status und Ambient-Proxy |
| `plugin-sdk/webhook-targets` | Hilfsbausteine für Webhook-Ziele | Hilfsbausteine für Webhook-Ziel-Registry und Route-Installation |
| `plugin-sdk/webhook-path` | Hilfsbausteine für Webhook-Pfade | Hilfsbausteine zur Normalisierung von Webhook-Pfaden |
| `plugin-sdk/web-media` | Gemeinsame Hilfsbausteine für Web-Medien | Hilfsbausteine zum Laden entfernter/lokaler Medien |
| `plugin-sdk/zod` | Zod-Re-Export | Re-exportiertes `zod` für Verbraucher des Plugin-SDK |
| `plugin-sdk/memory-core` | Gebündelte Hilfsbausteine für memory-core | Hilfsoberfläche für Speicherverwaltung/Konfiguration/Dateien/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Runtime-Fassade für Memory-Engine | Runtime-Fassade für Speicherindex/Suche |
| `plugin-sdk/memory-core-host-engine-foundation` | Foundation-Engine für Memory-Host | Exporte der Foundation-Engine für Memory-Host |
| `plugin-sdk/memory-core-host-engine-embeddings` | Embedding-Engine für Memory-Host | Embedding-Verträge für Memory, Registry-Zugriff, lokaler Provider und generische Batch-/Remote-Hilfsbausteine; konkrete Remote-Provider leben in ihren jeweiligen Plugins |
| `plugin-sdk/memory-core-host-engine-qmd` | QMD-Engine für Memory-Host | Exporte der QMD-Engine für Memory-Host |
| `plugin-sdk/memory-core-host-engine-storage` | Storage-Engine für Memory-Host | Exporte der Storage-Engine für Memory-Host |
| `plugin-sdk/memory-core-host-multimodal` | Multimodale Hilfsbausteine für Memory-Host | Multimodale Hilfsbausteine für Memory-Host |
| `plugin-sdk/memory-core-host-query` | Query-Hilfsbausteine für Memory-Host | Query-Hilfsbausteine für Memory-Host |
| `plugin-sdk/memory-core-host-secret` | Secret-Hilfsbausteine für Memory-Host | Secret-Hilfsbausteine für Memory-Host |
| `plugin-sdk/memory-core-host-events` | Hilfsbausteine für Event-Journal von Memory-Host | Hilfsbausteine für Event-Journal von Memory-Host |
| `plugin-sdk/memory-core-host-status` | Hilfsbausteine für Status von Memory-Host | Hilfsbausteine für Status von Memory-Host |
| `plugin-sdk/memory-core-host-runtime-cli` | CLI-Runtime für Memory-Host | CLI-Runtime-Hilfsbausteine für Memory-Host |
| `plugin-sdk/memory-core-host-runtime-core` | Core-Runtime für Memory-Host | Core-Runtime-Hilfsbausteine für Memory-Host |
| `plugin-sdk/memory-core-host-runtime-files` | Datei-/Runtime-Hilfsbausteine für Memory-Host | Datei-/Runtime-Hilfsbausteine für Memory-Host |
| `plugin-sdk/memory-host-core` | Alias für Core-Runtime von Memory-Host | Anbieterneutraler Alias für Core-Runtime-Hilfsbausteine von Memory-Host |
| `plugin-sdk/memory-host-events` | Alias für Event-Journal von Memory-Host | Anbieterneutraler Alias für Hilfsbausteine des Event-Journals von Memory-Host |
| `plugin-sdk/memory-host-files` | Alias für Datei-/Runtime von Memory-Host | Anbieterneutraler Alias für Datei-/Runtime-Hilfsbausteine von Memory-Host |
| `plugin-sdk/memory-host-markdown` | Hilfsbausteine für verwaltetes Markdown | Gemeinsame Hilfsbausteine für verwaltetes Markdown in speichernahen Plugins |
| `plugin-sdk/memory-host-search` | Fassade für Active Memory-Suche | Lazy-Runtime-Fassade für Active-Memory-Suchmanager |
| `plugin-sdk/memory-host-status` | Alias für Status von Memory-Host | Anbieterneutraler Alias für Status-Hilfsbausteine von Memory-Host |
| `plugin-sdk/memory-lancedb` | Gebündelte Hilfsbausteine für memory-lancedb | Hilfsoberfläche für memory-lancedb |
| `plugin-sdk/testing` | Test-Utilities | Test-Hilfsbausteine und Mocks |
</Accordion>
Diese Tabelle ist bewusst die häufige Teilmenge für Migrationen, nicht die vollständige SDK-
Oberfläche. Die vollständige Liste mit über 200 Entry-Points befindet sich in
Diese Tabelle ist bewusst das gängige Migrations-Subset und nicht die vollständige SDK-
Fläche. Die vollständige Liste mit mehr als 200 Einstiegspunkten befindet sich in
`scripts/lib/plugin-sdk-entrypoints.json`.
Diese Liste enthält weiterhin einige Helferschnittstellen für gebündelte Plugins wie
Diese Liste enthält weiterhin einige Helper-Seams für gebündelte Plugins wie
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup` und `plugin-sdk/matrix*`. Diese bleiben für die
Wartung gebündelter Plugins und aus Kompatibilitätsgründen exportiert, werden aber absichtlich
aus der häufigen Migrationstabelle weggelassen und sind nicht das empfohlene Ziel für
neuen Plugin-Code.
`plugin-sdk/zalo-setup` und `plugin-sdk/matrix*`. Diese bleiben für die Wartung
gebündelter Plugins und zur Kompatibilität exportiert, sind aber bewusst nicht in der
gängigen Migrationstabelle enthalten und nicht das empfohlene Ziel für neuen Plugin-Code.
Dieselbe Regel gilt für andere Familien gebündelter Hilfsschnittstellen wie:
Dieselbe Regel gilt für andere Familien gebündelter Helfer wie:
- Browser-Unterstützungshelfer: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- Browser-Support-Helfer: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- Matrix: `plugin-sdk/matrix*`
- LINE: `plugin-sdk/line*`
- IRC: `plugin-sdk/irc*`
- gebündelte Helfer-/Plugin-Oberflächen wie `plugin-sdk/googlechat`,
- gebündelte Helper-/Plugin-Flächen wie `plugin-sdk/googlechat`,
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
@ -390,39 +389,39 @@ Dieselbe Regel gilt für andere Familien gebündelter Hilfsschnittstellen wie:
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
`plugin-sdk/thread-ownership` und `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` stellt derzeit die schmale Oberfläche der Token-Helfer
`DEFAULT_COPILOT_API_BASE_URL`,
`plugin-sdk/github-copilot-token` stellt derzeit die schmale
Token-Hilfsoberfläche `DEFAULT_COPILOT_API_BASE_URL`,
`deriveCopilotApiBaseUrlFromToken` und `resolveCopilotApiToken` bereit.
Verwenden Sie den schmalsten Import, der zur Aufgabe passt. Wenn Sie keinen Export finden können,
prüfen Sie die Quelle unter `src/plugin-sdk/` oder fragen Sie in Discord nach.
Verwende den schmalsten Import, der zur Aufgabe passt. Wenn du einen Export nicht finden kannst,
prüfe den Quellcode unter `src/plugin-sdk/` oder frage in Discord nach.
## Zeitplan für die Entfernung
| Wann | Was passiert |
| ---------------------- | ---------------------------------------------------------------------- |
| **Jetzt** | Veraltete Oberflächen geben Laufzeitwarnungen aus |
| **Nächste Hauptversion** | Veraltete Oberflächen werden entfernt; Plugins, die sie noch verwenden, schlagen dann fehl |
| Wann | Was passiert |
| ---------------------- | ----------------------------------------------------------------------- |
| **Jetzt** | Deprecated Flächen geben Laufzeitwarnungen aus |
| **Nächste Major-Release** | Deprecated Flächen werden entfernt; Plugins, die sie noch verwenden, schlagen fehl |
Alle Core-Plugins wurden bereits migriert. Externe Plugins sollten vor der nächsten Hauptversion
migrieren.
Alle Core-Plugins wurden bereits migriert. Externe Plugins sollten vor der nächsten
Major-Release migrieren.
## Warnungen vorübergehend unterdrücken
Setzen Sie diese Umgebungsvariablen, während Sie an der Migration arbeiten:
Setze diese Umgebungsvariablen, während du an der Migration arbeitest:
```bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
Dies ist ein temporärer Escape-Hatch, keine dauerhafte Lösung.
Dies ist ein vorübergehender Escape Hatch, keine dauerhafte Lösung.
## Verwandt
- [Getting Started](/de/plugins/building-plugins) — Ihr erstes Plugin bauen
- [SDK Overview](/de/plugins/sdk-overview) — vollständige Referenz für Subpath-Imports
- [Channel Plugins](/de/plugins/sdk-channel-plugins) — Kanal-Plugins bauen
- [Provider Plugins](/de/plugins/sdk-provider-plugins) — Provider-Plugins bauen
- [Plugin Internals](/de/plugins/architecture) — tiefer Einblick in die Architektur
- [Plugin Manifest](/de/plugins/manifest) — Referenz für das Manifest-Schema
- [Erste Schritte](/de/plugins/building-plugins) — dein erstes Plugin erstellen
- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Referenz für Subpath-Imports
- [Channel-Plugins](/de/plugins/sdk-channel-plugins) — Channel-Plugins erstellen
- [Provider-Plugins](/de/plugins/sdk-provider-plugins) — Provider-Plugins erstellen
- [Plugin-Interna](/de/plugins/architecture) — ausführlicher Architekturüberblick
- [Plugin-Manifest](/de/plugins/manifest) — Referenz zum Manifest-Schema

332
docs/de/plugins/sdk-overview.md
View File

@ -1,34 +1,34 @@
---
read_when:
- Sie müssen wissen, von welchem SDK-Unterpfad importiert werden soll
- Sie möchten eine Referenz für alle Registrierungsmethoden in OpenClawPluginApi
- Sie suchen einen bestimmten SDK-Export
- Sie müssen wissen, aus welchem SDK-Unterpfad importiert werden soll
- Sie möchten eine Referenz für alle Registrierungsmethoden auf OpenClawPluginApi
- Sie schlagen einen bestimmten SDK-Export nach
sidebarTitle: SDK overview
summary: Import-Map, Registrierungs-API-Referenz und SDK-Architektur
title: Überblick über das Plugin SDK
title: Plugin-SDK-Überblick
x-i18n:
generated_at: "2026-04-24T06:50:55Z"
generated_at: "2026-04-24T08:59:54Z"
model: gpt-5.4
provider: openai
source_hash: 7090e13508382a68988f3d345bf12d6f3822c499e01a3affb1fa7a277b22f276
source_hash: 7f4209c245a3d3462c5d5f51ad3c6e4327240ed402fdbac3f01f8a761ba75233
source_path: plugins/sdk-overview.md
workflow: 15
---
Das Plugin SDK ist der typisierte Vertrag zwischen Plugins und Core. Diese Seite ist die
Referenz dafür, **was Sie importieren** und **was Sie registrieren können**.
Das Plugin-SDK ist der typisierte Vertrag zwischen Plugins und dem Kern. Diese Seite ist die
Referenz für **was importiert werden soll** und **was Sie registrieren können**.
<Tip>
Suchen Sie stattdessen einen How-to-Leitfaden?
Suchen Sie stattdessen nach einer Schritt-für-Schritt-Anleitung?
- Erstes Plugin? Beginnen Sie mit [Plugins erstellen](/de/plugins/building-plugins).
- Channel-Plugin? Siehe [Channel-Plugins](/de/plugins/sdk-channel-plugins).
- Provider-Plugin? Siehe [Provider-Plugins](/de/plugins/sdk-provider-plugins).
- Erstes Plugin? Beginnen Sie mit [Building plugins](/de/plugins/building-plugins).
- Channel-Plugin? Siehe [Channel plugins](/de/plugins/sdk-channel-plugins).
- Provider-Plugin? Siehe [Provider plugins](/de/plugins/sdk-provider-plugins).
</Tip>
## Import-Konvention
## Importkonvention
Importieren Sie immer von einem spezifischen Unterpfad:
Importieren Sie immer aus einem spezifischen Unterpfad:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -36,107 +36,135 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Jeder Unterpfad ist ein kleines, in sich geschlossenes Modul. Das hält den Start schnell und
verhindert Probleme mit zirkulären Abhängigkeiten. Für channel-spezifische Entry-/Build-Helfer
bevorzugen Sie `openclaw/plugin-sdk/channel-core`; behalten Sie `openclaw/plugin-sdk/core` für
die breitere Oberflächenebene und gemeinsame Helfer wie
verhindert Probleme mit zirkulären Abhängigkeiten. Für Channel-spezifische Entry-/Build-Helper
bevorzugen Sie `openclaw/plugin-sdk/channel-core`; verwenden Sie `openclaw/plugin-sdk/core` für
die breitere Dachoberfläche und gemeinsame Helper wie
`buildChannelConfigSchema`.
<Warning>
Importieren Sie keine provider- oder channelgebrandeten Convenience-Seams (zum Beispiel
Importieren Sie keine Provider- oder Channel-spezifisch benannten Komfort-Seams (zum Beispiel
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
Gebündelte Plugins kombinieren generische SDK-Unterpfade innerhalb ihrer eigenen lokalen Barrels `api.ts` /
`runtime-api.ts`; Core-Konsumenten sollten entweder diese plugin-lokalen
Barrels verwenden oder einen schmalen generischen SDK-Vertrag hinzufügen, wenn ein Bedarf wirklich
channelübergreifend ist.
Gebündelte Plugins setzen generische SDK-Unterpfade innerhalb ihrer eigenen `api.ts`- /
`runtime-api.ts`-Barrels zusammen; Kern-Consumer sollten entweder diese pluginlokalen
Barrels verwenden oder einen schmalen generischen SDK-Vertrag hinzufügen, wenn der Bedarf
wirklich kanalübergreifend ist.
Ein kleiner Satz von Helfer-Seams für gebündelte Plugins (`plugin-sdk/feishu`,
Eine kleine Menge von Helper-Seams für gebündelte Plugins (`plugin-sdk/feishu`,
`plugin-sdk/zalo`, `plugin-sdk/matrix*` und ähnliche) erscheint weiterhin in der
generierten Export-Map. Sie existieren nur für die Pflege gebündelter Plugins und sind
keine empfohlenen Importpfade für neue Plugins von Drittanbietern.
generierten Export-Map. Sie existieren nur für die Wartung gebündelter Plugins und sind
keine empfohlenen Importpfade für neue Drittanbieter-Plugins.
</Warning>
## Unterpfad-Referenz
Das Plugin SDK wird als Satz schmaler Unterpfade bereitgestellt, die nach Bereichen gruppiert sind (Plugin-
Entry, Channel, Provider, Auth, Runtime, Capability, Memory und reservierte
Helfer für gebündelte Plugins). Den vollständigen Katalog — gruppiert und verlinkt — finden Sie unter
[Plugin SDK-Unterpfade](/de/plugins/sdk-subpaths).
Das Plugin-SDK wird als Menge schmaler Unterpfade bereitgestellt, gruppiert nach Bereich (Plugin-Entry,
Channel, Provider, Auth, Runtime, Capability, Speicher und reservierte Helper für gebündelte
Plugins). Den vollständigen Katalog — gruppiert und verlinkt — finden Sie unter
[Plugin SDK subpaths](/de/plugins/sdk-subpaths).
Die generierte Liste mit mehr als 200 Unterpfaden befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`.
Die generierte Liste von mehr als 200 Unterpfaden befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`.
## Registrierungs-API
Der Callback `register(api)` erhält ein Objekt `OpenClawPluginApi` mit diesen
Der Callback `register(api)` erhält ein `OpenClawPluginApi`-Objekt mit diesen
Methoden:
### Registrierung von Capabilities
### Capability-Registrierung
| Methode | Was sie registriert |
| ------------------------------------------------ | -------------------------------------- |
| `api.registerProvider(...)` | Text-Inferenz (LLM) |
| Methode | Was registriert wird |
| ------------------------------------------------ | --------------------------------------- |
| `api.registerProvider(...)` | Textinferenz (LLM) |
| `api.registerAgentHarness(...)` | Experimenteller Low-Level-Agent-Executor |
| `api.registerCliBackend(...)` | Lokales CLI-Inferenz-Backend |
| `api.registerChannel(...)` | Messaging-Channel |
| `api.registerSpeechProvider(...)` | Text-to-Speech- / STT-Synthese |
| `api.registerRealtimeTranscriptionProvider(...)` | Streaming-Realtime-Transkription |
| `api.registerRealtimeVoiceProvider(...)` | Duplex-Realtime-Voice-Sitzungen |
| `api.registerMediaUnderstandingProvider(...)` | Bild-/Audio-/Videoanalyse |
| `api.registerImageGenerationProvider(...)` | Bildgenerierung |
| `api.registerMusicGenerationProvider(...)` | Musikgenerierung |
| `api.registerVideoGenerationProvider(...)` | Videogenerierung |
| `api.registerWebFetchProvider(...)` | Web-Fetch-/Scrape-Anbieter |
| `api.registerWebSearchProvider(...)` | Websuche |
| `api.registerCliBackend(...)` | Lokales CLI-Inferenz-Backend |
| `api.registerChannel(...)` | Messaging-Channel |
| `api.registerSpeechProvider(...)` | Text-to-Speech- / STT-Synthese |
| `api.registerRealtimeTranscriptionProvider(...)` | Streaming-Echtzeittranskription |
| `api.registerRealtimeVoiceProvider(...)` | Duplex-Echtzeit-Sprachsitzungen |
| `api.registerMediaUnderstandingProvider(...)` | Bild-/Audio-/Videoanalyse |
| `api.registerImageGenerationProvider(...)` | Bildgenerierung |
| `api.registerMusicGenerationProvider(...)` | Musikgenerierung |
| `api.registerVideoGenerationProvider(...)` | Videogenerierung |
| `api.registerWebFetchProvider(...)` | Web-Fetch- / Scrape-Provider |
| `api.registerWebSearchProvider(...)` | Websuche |
### Tools und Befehle
| Methode | Was sie registriert |
| ------------------------------ | ------------------------------------------------ |
| `api.registerTool(tool, opts?)` | Agenten-Tool (erforderlich oder `{ optional: true }`) |
| `api.registerCommand(def)` | Benutzerdefinierter Befehl (umgeht das LLM) |
| Methode | Was registriert wird |
| ----------------------------- | ------------------------------------------------ |
| `api.registerTool(tool, opts?)` | Agent-Tool (erforderlich oder `{ optional: true }`) |
| `api.registerCommand(def)` | Benutzerdefinierter Befehl (umgeht das LLM) |
### Infrastruktur
| Methode | Was sie registriert |
| ----------------------------------------------- | ---------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Event-Hook |
| `api.registerHttpRoute(params)` | Gateway-HTTP-Endpunkt |
| `api.registerGatewayMethod(name, handler)` | Gateway-RPC-Methode |
| `api.registerCli(registrar, opts?)` | CLI-Unterbefehl |
| `api.registerService(service)` | Hintergrunddienst |
| `api.registerInteractiveHandler(registration)` | Interaktiver Handler |
| `api.registerEmbeddedExtensionFactory(factory)` | Eingebettete Pi-Embedded-Runner-Extension-Factory |
| `api.registerMemoryPromptSupplement(builder)` | Additiver promptnaher Abschnitt für Memory |
| `api.registerMemoryCorpusSupplement(adapter)` | Additives Memory-Korpus für Suche/Abruf |
| Methode | Was registriert wird |
| ----------------------------------------------- | ------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Event-Hook |
| `api.registerHttpRoute(params)` | Gateway-HTTP-Endpunkt |
| `api.registerGatewayMethod(name, handler)` | Gateway-RPC-Methode |
| `api.registerGatewayDiscoveryService(service)` | Lokaler Gateway-Discovery-Advertiser |
| `api.registerCli(registrar, opts?)` | CLI-Unterbefehl |
| `api.registerService(service)` | Hintergrunddienst |
| `api.registerInteractiveHandler(registration)` | Interaktiver Handler |
| `api.registerEmbeddedExtensionFactory(factory)` | Pi-Embedded-Runner-Extension-Factory |
| `api.registerMemoryPromptSupplement(builder)` | Additiver speichernaher Prompt-Abschnitt |
| `api.registerMemoryCorpusSupplement(adapter)` | Additiver Korpus für Speicher-Suche/-Lesen |
<Note>
Reservierte Core-Admin-Namespaces (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) bleiben immer `operator.admin`, auch wenn ein Plugin versucht, einer
Gateway-Methode einen engeren Scope zuzuweisen. Bevorzugen Sie plugin-spezifische Präfixe für
`update.*`) bleiben immer `operator.admin`, auch wenn ein Plugin versucht, einen
engeren Gateway-Methoden-Scope zuzuweisen. Bevorzugen Sie plugin-spezifische Präfixe für
plugin-eigene Methoden.
</Note>
<Accordion title="Wann registerEmbeddedExtensionFactory verwendet werden sollte">
Verwenden Sie `api.registerEmbeddedExtensionFactory(...)`, wenn ein Plugin Pi-native
Event-Timings während eingebetteter OpenClaw-Läufe benötigt — zum Beispiel asynchrone Umschreibungen von `tool_result`,
die stattfinden müssen, bevor die endgültige Tool-Ergebnisnachricht ausgegeben wird.
Event-Timings während eingebetteter OpenClaw-Ausführungen benötigt — zum Beispiel asynchrone
Umschreibungen von `tool_result`, die erfolgen müssen, bevor die endgültige
Tool-Ergebnisnachricht ausgegeben wird.
Dies ist heute ein Seam für gebündelte Plugins: Nur gebündelte Plugins dürfen einen registrieren,
Dies ist derzeit ein Seam für gebündelte Plugins: Nur gebündelte Plugins dürfen eines registrieren,
und sie müssen `contracts.embeddedExtensionFactories: ["pi"]` in
`openclaw.plugin.json` deklarieren. Behalten Sie normale OpenClaw-Plugin-Hooks für alles bei,
was diesen niedrigeren Seam nicht benötigt.
`openclaw.plugin.json` deklarieren. Behalten Sie normale OpenClaw-Plugin-Hooks für alles,
was dieses Low-Level-Seam nicht benötigt.
</Accordion>
### Gateway-Discovery-Registrierung
Mit `api.registerGatewayDiscoveryService(...)` kann ein Plugin das aktive
Gateway auf einem lokalen Discovery-Transport wie mDNS/Bonjour ankündigen. OpenClaw ruft den
Service beim Start des Gateway auf, wenn lokale Discovery aktiviert ist, übergibt die
aktuellen Gateway-Ports und nicht geheime TXT-Hinweisdaten und ruft den zurückgegebenen
`stop`-Handler beim Herunterfahren des Gateway auf.
```typescript
api.registerGatewayDiscoveryService({
id: "my-discovery",
async advertise(ctx) {
const handle = await startMyAdvertiser({
gatewayPort: ctx.gatewayPort,
tls: ctx.gatewayTlsEnabled,
displayName: ctx.machineDisplayName,
});
return { stop: () => handle.stop() };
},
});
```
Gateway-Discovery-Plugins dürfen angekündigte TXT-Werte nicht als Secrets oder
Authentifizierung behandeln. Discovery ist ein Routing-Hinweis; Vertrauen bleibt weiterhin Sache
von Gateway-Auth und TLS-Pinning.
### CLI-Registrierungsmetadaten
`api.registerCli(registrar, opts?)` akzeptiert zwei Arten von Metadaten auf oberster Ebene:
- `commands`: explizite Befehls-Roots, die dem Registrar gehören
- `descriptors`: Parse-Time-Befehlsdeskriptoren, die für Root-CLI-Hilfe,
Routing und Lazy-Registrierung von Plugin-CLI verwendet werden
- `commands`: explizite Befehlswurzeln, die dem Registrar gehören
- `descriptors`: Parse-Zeit-Befehlsdeskriptoren, die für Root-CLI-Hilfe,
Routing und verzögerte Plugin-CLI-Registrierung verwendet werden
Wenn ein Plugin-Befehl im normalen Root-CLI-Pfad lazy geladen bleiben soll,
geben Sie `descriptors` an, die jeden Befehls-Root auf oberster Ebene abdecken, der durch diesen
Registrar bereitgestellt wird.
geben Sie `descriptors` an, die jede Befehlswurzel der obersten Ebene abdecken, die dieser
Registrar bereitstellt.
```typescript
api.registerCli(
@ -156,73 +184,73 @@ api.registerCli(
);
```
Verwenden Sie `commands` allein nur dann, wenn Sie keine Lazy-Root-CLI-Registrierung benötigen.
Dieser eager-Kompatibilitätspfad wird weiterhin unterstützt, installiert aber
keine durch Deskriptoren gestützten Platzhalter für parsezeitiges Lazy Loading.
Verwenden Sie `commands` allein nur dann, wenn Sie keine lazy Root-CLI-Registrierung benötigen.
Dieser eager Kompatibilitätspfad wird weiterhin unterstützt, installiert aber keine
deskriptorbasierten Platzhalter für Parse-Zeit-Lazy-Loading.
### Registrierung von CLI-Backends
### CLI-Backend-Registrierung
`api.registerCliBackend(...)` erlaubt es einem Plugin, die Standardkonfiguration für ein lokales
AI-CLI-Backend wie `codex-cli` zu verwalten.
Mit `api.registerCliBackend(...)` kann ein Plugin die Standardkonfiguration für ein lokales
KI-CLI-Backend wie `codex-cli` besitzen.
- Die Backend-`id` wird zum Anbieterpräfix in Modellreferenzen wie `codex-cli/gpt-5`.
- Die Backend-`config` verwendet dieselbe Form wie `agents.defaults.cliBackends.<id>`.
- Benutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt `agents.defaults.cliBackends.<id>` über dem
Plugin-Standard zusammen, bevor die CLI ausgeführt wird.
- Die `id` des Backends wird zum Provider-Präfix in Modell-Referenzen wie `codex-cli/gpt-5`.
- Die `config` des Backends verwendet dieselbe Form wie `agents.defaults.cliBackends.<id>`.
- Die Benutzerkonfiguration hat weiterhin Vorrang. OpenClaw merged `agents.defaults.cliBackends.<id>` über den
Plugin-Standardwert, bevor die CLI ausgeführt wird.
- Verwenden Sie `normalizeConfig`, wenn ein Backend nach dem Merge Kompatibilitäts-Umschreibungen benötigt
(zum Beispiel Normalisierung alter Flag-Formen).
(zum Beispiel zur Normalisierung älterer Flag-Formen).
### Exklusive Slots
| Methode | Was sie registriert |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api.registerContextEngine(id, factory)` | Kontext-Engine (jeweils nur eine aktiv). Der Callback `assemble()` erhält `availableTools` und `citationsMode`, damit die Engine Prompt-Ergänzungen anpassen kann. |
| `api.registerMemoryCapability(capability)` | Einheitliche Memory-Capability |
| `api.registerMemoryPromptSection(builder)` | Builder für Memory-Prompt-Abschnitt |
| `api.registerMemoryFlushPlan(resolver)` | Resolver für Memory-Flush-Plan |
| `api.registerMemoryRuntime(runtime)` | Adapter für Memory-Runtime |
| Methode | Was registriert wird |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Context-Engine (immer nur eine aktiv). Der Callback `assemble()` erhält `availableTools` und `citationsMode`, damit die Engine Prompt-Ergänzungen anpassen kann. |
| `api.registerMemoryCapability(capability)` | Vereinheitlichte Speicher-Capability |
| `api.registerMemoryPromptSection(builder)` | Builder für Speicher-Prompt-Abschnitte |
| `api.registerMemoryFlushPlan(resolver)` | Resolver für Speicher-Flush-Pläne |
| `api.registerMemoryRuntime(runtime)` | Speicher-Runtime-Adapter |
### Memory-Embedding-Adapter
### Speicher-Embedding-Adapter
| Methode | Was sie registriert |
| --------------------------------------------- | ------------------------------------------------ |
| `api.registerMemoryEmbeddingProvider(adapter)` | Memory-Embedding-Adapter für das aktive Plugin |
| Methode | Was registriert wird |
| ---------------------------------------------- | --------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Speicher-Embedding-Adapter für das aktive Plugin |
- `registerMemoryCapability` ist die bevorzugte exklusive Memory-Plugin-API.
- `registerMemoryCapability` kann auch `publicArtifacts.listArtifacts(...)` bereitstellen,
sodass Companion-Plugins exportierte Memory-Artefakte über
`openclaw/plugin-sdk/memory-host-core` konsumieren können, statt in das private Layout
eines bestimmten Memory-Plugins zu greifen.
- `registerMemoryCapability` ist die bevorzugte exklusive API für Speicher-Plugins.
- `registerMemoryCapability` kann außerdem `publicArtifacts.listArtifacts(...)`
bereitstellen, damit Begleit-Plugins exportierte Speicherartefakte über
`openclaw/plugin-sdk/memory-host-core` nutzen können, statt in das private Layout
eines bestimmten Speicher-Plugins zu greifen.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` und
`registerMemoryRuntime` sind exklusive Memory-Plugin-APIs für Legacy-Kompatibilität.
- `registerMemoryEmbeddingProvider` erlaubt es dem aktiven Memory-Plugin, einen
oder mehrere Adapter-IDs für Embeddings zu registrieren (zum Beispiel `openai`, `gemini` oder eine benutzerdefinierte
plugin-definierte ID).
- Benutzerkonfiguration wie `agents.defaults.memorySearch.provider` und
`agents.defaults.memorySearch.fallback` wird gegen diese registrierten
`registerMemoryRuntime` sind ältere, kompatible exklusive APIs für Speicher-Plugins.
- `registerMemoryEmbeddingProvider` erlaubt dem aktiven Speicher-Plugin, einen
oder mehrere Embedding-Adapter-IDs zu registrieren (zum Beispiel `openai`, `gemini` oder eine
benutzerdefinierte, plugindefinierte ID).
- Benutzerkonfigurationen wie `agents.defaults.memorySearch.provider` und
`agents.defaults.memorySearch.fallback` werden gegen diese registrierten
Adapter-IDs aufgelöst.
### Ereignisse und Lebenszyklus
### Events und Lebenszyklus
| Methode | Was sie tut |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Typisierter Lifecycle-Hook |
| `api.onConversationBindingResolved(handler)` | Callback für Konversationsbindung |
| Methode | Was sie tut |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Typisierter Lifecycle-Hook |
| `api.onConversationBindingResolved(handler)` | Callback für Conversation-Binding |
### Semantik von Hook-Entscheidungen
- `before_tool_call`: Rückgabe von `{ block: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
- `before_tool_call`: Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `block`), nicht als Überschreibung.
- `before_install`: Rückgabe von `{ block: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
- `before_install`: Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `block`), nicht als Überschreibung.
- `reply_dispatch`: Rückgabe von `{ handled: true, ... }` ist terminal. Sobald ein Handler die Zustellung beansprucht, werden Handler mit niedrigerer Priorität und der Standardpfad für die Modellzustellung übersprungen.
- `message_sending`: Rückgabe von `{ cancel: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
- `message_sending`: Rückgabe von `{ cancel: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `cancel`), nicht als Überschreibung.
- `message_received`: Verwenden Sie das typisierte Feld `threadId`, wenn Sie eingehendes Thread-/Topic-Routing benötigen. Behalten Sie `metadata` für channel-spezifische Extras.
- `message_sending`: Verwenden Sie typisierte Routing-Felder `replyToId` / `threadId`, bevor Sie auf channel-spezifische `metadata` zurückfallen.
- `gateway_start`: Verwenden Sie `ctx.config`, `ctx.workspaceDir` und `ctx.getCron?.()` für gateway-eigenen Startzustand, statt sich auf interne Hooks `gateway:startup` zu verlassen.
- `before_tool_call`: das Zurückgeben von `{ block: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
- `before_tool_call`: das Zurückgeben von `{ block: false }` wird als keine Entscheidung behandelt (genau wie das Weglassen von `block`), nicht als Override.
- `before_install`: das Zurückgeben von `{ block: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
- `before_install`: das Zurückgeben von `{ block: false }` wird als keine Entscheidung behandelt (genau wie das Weglassen von `block`), nicht als Override.
- `reply_dispatch`: das Zurückgeben von `{ handled: true, ... }` ist terminal. Sobald ein Handler die Zustellung beansprucht, werden Handler mit niedrigerer Priorität und der Standardpfad für die Modellzustellung übersprungen.
- `message_sending`: das Zurückgeben von `{ cancel: true }` ist terminal. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen.
- `message_sending`: das Zurückgeben von `{ cancel: false }` wird als keine Entscheidung behandelt (genau wie das Weglassen von `cancel`), nicht als Override.
- `message_received`: verwenden Sie das typisierte Feld `threadId`, wenn Sie eingehendes Thread-/Themen-Routing benötigen. Behalten Sie `metadata` für Channel-spezifische Extras.
- `message_sending`: verwenden Sie die typisierten Routing-Felder `replyToId` / `threadId`, bevor Sie auf Channel-spezifische `metadata` zurückfallen.
- `gateway_start`: verwenden Sie `ctx.config`, `ctx.workspaceDir` und `ctx.getCron?.()` für gatewayeigenen Startzustand statt sich auf interne `gateway:startup`-Hooks zu verlassen.
### Felder des API-Objekts
### API-Objektfelder
| Feld | Typ | Beschreibung |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
@ -230,14 +258,14 @@ AI-CLI-Backend wie `codex-cli` zu verwalten.
| `api.name` | `string` | Anzeigename |
| `api.version` | `string?` | Plugin-Version (optional) |
| `api.description` | `string?` | Plugin-Beschreibung (optional) |
| `api.source` | `string` | Quellpfad des Plugins |
| `api.rootDir` | `string?` | Root-Verzeichnis des Plugins (optional) |
| `api.config` | `OpenClawConfig` | Aktueller Konfigurationssnapshot (aktiver In-Memory-Runtime-Snapshot, wenn verfügbar) |
| `api.source` | `string` | Plugin-Quellpfad |
| `api.rootDir` | `string?` | Plugin-Wurzelverzeichnis (optional) |
| `api.config` | `OpenClawConfig` | Aktueller Konfigurations-Snapshot (aktive In-Memory-Laufzeitkopie, wenn verfügbar) |
| `api.pluginConfig` | `Record<string, unknown>` | Plugin-spezifische Konfiguration aus `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Runtime-Helfer](/de/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger mit Scope (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Aktueller Lademodus; `"setup-runtime"` ist das schlanke Fenster für Start/Setup vor dem vollständigen Entry |
| `api.resolvePath(input)` | `(string) => string` | Pfad relativ zum Plugin-Root auflösen |
| `api.runtime` | `PluginRuntime` | [Runtime-Helper](/de/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Bereichsbezogener Logger (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Aktueller Lademodus; `"setup-runtime"` ist das leichtgewichtige Fenster vor vollständigem Entry-Start/Setup |
| `api.resolvePath(input)` | `(string) => string` | Pfad relativ zur Plugin-Wurzel auflösen |
## Konvention für interne Module
@ -245,39 +273,39 @@ Verwenden Sie innerhalb Ihres Plugins lokale Barrel-Dateien für interne Importe
```
my-plugin/
api.ts # Öffentliche Exporte für externe Konsumenten
runtime-api.ts # Nur intern verwendete Runtime-Exporte
index.ts # Entry-Point des Plugins
setup-entry.ts # Leichter Setup-only-Entry (optional)
api.ts # Öffentliche Exporte für externe Consumer
runtime-api.ts # Nur interne Runtime-Exporte
index.ts # Plugin-Entry-Point
setup-entry.ts # Leichtgewichtiger Entry nur für Setup (optional)
```
<Warning>
Importieren Sie Ihr eigenes Plugin im Produktionscode niemals über `openclaw/plugin-sdk/<your-plugin>`.
Leiten Sie interne Importe über `./api.ts` oder
Importieren Sie Ihr eigenes Plugin niemals über `openclaw/plugin-sdk/<your-plugin>`
aus Produktionscode. Leiten Sie interne Importe über `./api.ts` oder
`./runtime-api.ts`. Der SDK-Pfad ist nur der externe Vertrag.
</Warning>
Öffentliche Oberflächen von gebündelten Plugins, die über Facades geladen werden (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` und ähnliche öffentliche Entry-Dateien), bevorzugen den
aktiven Runtime-Konfigurationssnapshot, wenn OpenClaw bereits läuft. Falls noch kein Runtime-
Snapshot existiert, greifen sie auf die auf der Festplatte aufgelöste Konfigurationsdatei zurück.
Durch Fassade geladene öffentliche Oberflächen gebündelter Plugins (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` und ähnliche öffentliche Entry-Dateien) bevorzugen den
aktiven Laufzeit-Konfigurations-Snapshot, wenn OpenClaw bereits läuft. Wenn noch kein Laufzeit-
Snapshot existiert, fallen sie auf die aufgelöste Konfigurationsdatei auf der Festplatte zurück.
Provider-Plugins können ein schmales plugin-lokales Contract-Barrel bereitstellen, wenn eine
Helferfunktion absichtlich anbieterspezifisch ist und noch nicht in einen generischen SDK-
Unterpfad gehört. Beispiele für gebündelte Plugins:
Provider-Plugins können ein schmales pluginlokales Vertrags-Barrel bereitstellen, wenn ein
Helper absichtlich providerspezifisch ist und noch nicht in einen generischen SDK-
Unterpfad gehört. Gebündelte Beispiele:
- **Anthropic**: öffentliches Seam `api.ts` / `contract-api.ts` für Claude-
Beta-Header und Stream-Helfer für `service_tier`.
- **Anthropic**: öffentliche `api.ts`- / `contract-api.ts`-Seam für Claude-
Beta-Header und `service_tier`-Streaming-Helper.
- **`@openclaw/openai-provider`**: `api.ts` exportiert Provider-Builder,
Helfer für Standardmodelle und Realtime-Provider-Builder.
Standardmodell-Helper und Echtzeit-Provider-Builder.
- **`@openclaw/openrouter-provider`**: `api.ts` exportiert den Provider-Builder
plus Helfer für Onboarding/Konfiguration.
plus Onboarding-/Konfigurations-Helper.
<Warning>
Produktionscode von Erweiterungen sollte auch Importe über `openclaw/plugin-sdk/<other-plugin>`
vermeiden. Wenn eine Helferfunktion wirklich gemeinsam genutzt wird, heben Sie sie in einen neutralen SDK-Unterpfad
Produktionscode von Extensions sollte auch Importe aus `openclaw/plugin-sdk/<other-plugin>`
vermeiden. Wenn ein Helper wirklich geteilt ist, verschieben Sie ihn in einen neutralen SDK-Unterpfad
wie `openclaw/plugin-sdk/speech`, `.../provider-model-shared` oder eine andere
auf Capabilities ausgerichtete Oberfläche an, statt zwei Plugins miteinander zu koppeln.
capability-orientierte Oberfläche, statt zwei Plugins miteinander zu koppeln.
</Warning>
## Verwandt
@ -287,10 +315,10 @@ Unterpfad gehört. Beispiele für gebündelte Plugins:
Optionen für `definePluginEntry` und `defineChannelPluginEntry`.
</Card>
<Card title="Runtime helpers" icon="gears" href="/de/plugins/sdk-runtime">
Vollständige Referenz für den Namespace `api.runtime`.
Vollständige Referenz des Namespace `api.runtime`.
</Card>
<Card title="Setup and config" icon="sliders" href="/de/plugins/sdk-setup">
Packaging, Manifeste und Konfigurationsschemas.
Packaging, Manifeste und Konfigurationsschemata.
</Card>
<Card title="Testing" icon="vial" href="/de/plugins/sdk-testing">
Test-Utilities und Lint-Regeln.
@ -299,6 +327,6 @@ Unterpfad gehört. Beispiele für gebündelte Plugins:
Migration von veralteten Oberflächen.
</Card>
<Card title="Plugin internals" icon="diagram-project" href="/de/plugins/architecture">
Tiefe Architektur und Capability-Modell.
Vertiefte Architektur und Capability-Modell.
</Card>
</CardGroup>

444
docs/de/plugins/sdk-subpaths.md
View File

@ -1,287 +1,287 @@
---
read_when:
- Den richtigen Unterpfad von plugin-sdk für einen Plugin-Import auswählen
- Unterpfade und Hilfsoberflächen gebündelter Plugins prüfen
summary: 'Katalog der Plugin-SDK-Unterpfade: welche Importe wo liegen, nach Bereichen gruppiert'
title: Plugin-SDK-Unterpfade
- Den richtigen plugin-sdk-Subpfad für einen Plugin-Import auswählen
- Subpfade gebündelter Plugins und Hilfsoberflächen prüfen
summary: 'Plugin-SDK-Subpfad-Katalog: Welche Imports wo liegen, nach Bereichen gruppiert'
title: Plugin-SDK-Subpfade
x-i18n:
generated_at: "2026-04-24T06:51:51Z"
generated_at: "2026-04-24T09:00:06Z"
model: gpt-5.4
provider: openai
source_hash: 753c7202a8a59ae9e420d436c7f3770ea455d810f2af52b716d438b84b8b986e
source_hash: 20b923e392b3ec65cfc958ccc7452b52d82bc372ae57cc9becad74a5085ed71b
source_path: plugins/sdk-subpaths.md
workflow: 15
---
Das Plugin SDK wird als Satz schmaler Unterpfade unter `openclaw/plugin-sdk/` bereitgestellt.
Diese Seite katalogisiert die häufig verwendeten Unterpfade, nach ihrem Zweck gruppiert. Die generierte
vollständige Liste mit mehr als 200 Unterpfaden befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`;
reservierte Hilfs-Unterpfade für gebündelte Plugins erscheinen dort, sind aber ein
Implementierungsdetail, sofern nicht eine Dokumentationsseite sie ausdrücklich hervorhebt.
Das Plugin-SDK wird als Satz enger Subpfade unter `openclaw/plugin-sdk/` bereitgestellt.
Diese Seite katalogisiert die häufig verwendeten Subpfade nach Zweck gruppiert. Die generierte
vollständige Liste mit mehr als 200 Subpfaden liegt in `scripts/lib/plugin-sdk-entrypoints.json`;
reservierte Hilfs-Subpfade für gebündelte Plugins erscheinen dort ebenfalls, sind aber ein
Implementierungsdetail, sofern eine Dokumentationsseite sie nicht ausdrücklich hervorhebt.
Den Leitfaden zum Schreiben von Plugins finden Sie unter [Überblick über das Plugin SDK](/de/plugins/sdk-overview).
Den Leitfaden zum Schreiben von Plugins finden Sie unter [Plugin SDK overview](/de/plugins/sdk-overview).
## Plugin-Entry
## Plugin-Einstieg
| Unterpfad | Wichtige Exporte |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| Subpfad | Wichtige Exporte |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="Channel-Unterpfade">
| Unterpfad | Wichtige Exporte |
<Accordion title="Channel-Subpfade">
| Subpfad | Wichtige Exporte |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Zod-Schema-Export für das Root-`openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/config-schema` | Root-`openclaw.json`-Zod-Schema-Export (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Gemeinsame Helfer für den Setup-Assistenten, Allowlist-Prompts, Builder für Setup-Status |
| `plugin-sdk/setup` | Gemeinsame Hilfsfunktionen für Setup-Assistenten, Allowlist-Prompts, Setup-Status-Builder |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helfer für Multi-Account-Konfiguration/Aktions-Gating, Helfer für Default-Account-Fallback |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, Helfer zur Normalisierung von Account-IDs |
| `plugin-sdk/account-resolution` | Helfer für Account-Lookup + Default-Fallback |
| `plugin-sdk/account-helpers` | Schmale Helfer für Account-Liste/Account-Aktionen |
| `plugin-sdk/account-core` | Hilfsfunktionen für Multi-Account-Config/Aktions-Gates, Hilfsfunktionen für den Fallback auf den Standard-Account |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, Hilfsfunktionen zur Normalisierung von Account-IDs |
| `plugin-sdk/account-resolution` | Hilfsfunktionen für Account-Lookup + Standard-Fallback |
| `plugin-sdk/account-helpers` | Enge Hilfsfunktionen für Account-Listen/Account-Aktionen |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Typen für Channel-Konfigurationsschema |
| `plugin-sdk/telegram-command-config` | Helfer zur Normalisierung/Validierung benutzerdefinierter Telegram-Befehle mit Fallback für gebündelte Verträge |
| `plugin-sdk/command-gating` | Schmale Helfer für Command-Autorisierungs-Gating |
| `plugin-sdk/channel-config-schema` | Typen für das Channel-Config-Schema |
| `plugin-sdk/telegram-command-config` | Hilfsfunktionen zur Normalisierung/Validierung benutzerdefinierter Telegram-Befehle mit Fallback auf den gebündelten Vertrag |
| `plugin-sdk/command-gating` | Enge Hilfsfunktionen für Gates zur Befehlsautorisierung |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, Lifecycle-/Finalisierungshelfer für Draft-Streams |
| `plugin-sdk/inbound-envelope` | Gemeinsame Helfer für eingehende Routen + Envelope-Builder |
| `plugin-sdk/inbound-reply-dispatch` | Gemeinsame Helfer zum Aufzeichnen und Weiterleiten eingehender Nachrichten |
| `plugin-sdk/messaging-targets` | Helfer zum Parsen/Abgleichen von Targets |
| `plugin-sdk/outbound-media` | Gemeinsame Helfer zum Laden ausgehender Medien |
| `plugin-sdk/outbound-runtime` | Helfer für ausgehende Identität, Send-Delegate und Payload-Planung |
| `plugin-sdk/poll-runtime` | Schmale Helfer zur Poll-Normalisierung |
| `plugin-sdk/thread-bindings-runtime` | Helfer für Thread-Binding-Lifecycle und Adapter |
| `plugin-sdk/agent-media-payload` | Legacy-Builder für Agent-Media-Payload |
| `plugin-sdk/conversation-runtime` | Helfer für Konversations-/Thread-Binding, Pairing und konfigurierte Bindings |
| `plugin-sdk/runtime-config-snapshot` | Helfer für Runtime-Konfigurationssnapshot |
| `plugin-sdk/runtime-group-policy` | Helfer zur Auflösung von Group-Policy zur Laufzeit |
| `plugin-sdk/channel-status` | Gemeinsame Helfer für Channel-Status-Snapshot/-Zusammenfassung |
| `plugin-sdk/channel-config-primitives` | Schmale Primitive für Channel-Konfigurationsschema |
| `plugin-sdk/channel-config-writes` | Helfer zur Autorisierung von Schreibvorgängen in Channel-Konfigurationen |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, Hilfsfunktionen für Lifecycle/Abschluss von Entwurfsstreams |
| `plugin-sdk/inbound-envelope` | Gemeinsame Hilfsfunktionen für Inbound-Routing + Envelope-Builder |
| `plugin-sdk/inbound-reply-dispatch` | Gemeinsame Hilfsfunktionen für Inbound-Aufzeichnung und -Dispatch |
| `plugin-sdk/messaging-targets` | Hilfsfunktionen zum Parsen/Abgleichen von Zielen |
| `plugin-sdk/outbound-media` | Gemeinsame Hilfsfunktionen zum Laden ausgehender Medien |
| `plugin-sdk/outbound-runtime` | Hilfsfunktionen für ausgehende Identität, Sendedelegation und Payload-Planung |
| `plugin-sdk/poll-runtime` | Enge Hilfsfunktionen zur Umfrage-Normalisierung |
| `plugin-sdk/thread-bindings-runtime` | Hilfsfunktionen für den Lifecycle und Adapter von Thread-Bindings |
| `plugin-sdk/agent-media-payload` | Veralteter Builder für Agent-Medien-Payload |
| `plugin-sdk/conversation-runtime` | Hilfsfunktionen für Conversation-/Thread-Binding, Pairing und konfiguriertes Binding |
| `plugin-sdk/runtime-config-snapshot` | Hilfsfunktion für Runtime-Config-Snapshots |
| `plugin-sdk/runtime-group-policy` | Hilfsfunktionen zur Auflösung von Runtime-Gruppenrichtlinien |
| `plugin-sdk/channel-status` | Gemeinsame Hilfsfunktionen für Channel-Status-Snapshots/-Zusammenfassungen |
| `plugin-sdk/channel-config-primitives` | Enge Primitive für das Channel-Config-Schema |
| `plugin-sdk/channel-config-writes` | Hilfsfunktionen zur Autorisierung von Channel-Config-Schreibvorgängen |
| `plugin-sdk/channel-plugin-common` | Gemeinsame Prelude-Exporte für Channel-Plugins |
| `plugin-sdk/allowlist-config-edit` | Helfer zum Bearbeiten/Lesen von Allowlist-Konfigurationen |
| `plugin-sdk/group-access` | Gemeinsame Helfer für Entscheidungen zum Gruppenzugriff |
| `plugin-sdk/direct-dm` | Gemeinsame Helfer für direkte DM-Auth/Guards |
| `plugin-sdk/interactive-runtime` | Semantische Nachrichtenpräsentation, Zustellung und Legacy-Helfer für interaktive Antworten. Siehe [Message Presentation](/de/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Kompatibilitäts-Barrel für Inbound-Debounce, Mention-Matching, Mention-Policy-Helfer und Envelope-Helfer |
| `plugin-sdk/channel-inbound-debounce` | Schmale Inbound-Debounce-Helfer |
| `plugin-sdk/channel-mention-gating` | Schmale Helfer für Mention-Policy und Mention-Text ohne die breitere Inbound-Runtime-Oberfläche |
| `plugin-sdk/channel-envelope` | Schmale Helfer zur Formatierung eingehender Envelopes |
| `plugin-sdk/channel-location` | Helfer für Channel-Standortkontext und -Formatierung |
| `plugin-sdk/channel-logging` | Logging-Helfer für Channel bei Inbound-Drops sowie Fehlern bei Typing/Ack |
| `plugin-sdk/allowlist-config-edit` | Hilfsfunktionen zum Bearbeiten/Lesen der Allowlist-Config |
| `plugin-sdk/group-access` | Gemeinsame Hilfsfunktionen für Entscheidungen zum Gruppenzugriff |
| `plugin-sdk/direct-dm` | Gemeinsame Hilfsfunktionen für Authentifizierung/Guards bei direkten DMs |
| `plugin-sdk/interactive-runtime` | Semantische Nachrichtendarstellung, Zustellung und veraltete Hilfsfunktionen für interaktive Antworten. Siehe [Message Presentation](/de/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Kompatibilitäts-Barrel für Inbound-Debounce, Erwähnungsabgleich, Hilfsfunktionen für Erwähnungsrichtlinien und Envelope-Hilfsfunktionen |
| `plugin-sdk/channel-inbound-debounce` | Enge Hilfsfunktionen für Inbound-Debounce |
| `plugin-sdk/channel-mention-gating` | Enge Hilfsfunktionen für Erwähnungsrichtlinien und Erwähnungstext ohne die breitere Inbound-Runtime-Oberfläche |
| `plugin-sdk/channel-envelope` | Enge Hilfsfunktionen für die Formatierung von Inbound-Envelopes |
| `plugin-sdk/channel-location` | Hilfsfunktionen für Kontext und Formatierung von Channel-Standorten |
| `plugin-sdk/channel-logging` | Hilfsfunktionen für Channel-Logging bei verworfenen Inbounds und Fehlern bei Typing/Ack |
| `plugin-sdk/channel-send-result` | Typen für Antwortergebnisse |
| `plugin-sdk/channel-actions` | Helfer für Channel-Nachrichtenaktionen sowie veraltete native Schema-Helfer, die aus Plugin-Kompatibilitätsgründen beibehalten werden |
| `plugin-sdk/channel-targets` | Helfer zum Parsen/Abgleichen von Targets |
| `plugin-sdk/channel-contract` | Typen für Channel-Verträge |
| `plugin-sdk/channel-feedback` | Verdrahtung für Feedback/Reaktionen |
| `plugin-sdk/channel-secret-runtime` | Schmale Secret-Vertragshelfer wie `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` und Typen für Secret-Ziele |
| `plugin-sdk/channel-actions` | Hilfsfunktionen für Channel-Nachrichtenaktionen sowie veraltete native Schema-Hilfsfunktionen, die für die Plugin-Kompatibilität beibehalten werden |
| `plugin-sdk/channel-targets` | Hilfsfunktionen zum Parsen/Abgleichen von Zielen |
| `plugin-sdk/channel-contract` | Channel-Vertragstypen |
| `plugin-sdk/channel-feedback` | Wiring für Feedback/Reaktionen |
| `plugin-sdk/channel-secret-runtime` | Enge Hilfsfunktionen für Secret-Verträge wie `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` und Secret-Zieltypen |
</Accordion>
<Accordion title="Provider-Unterpfade">
| Unterpfad | Wichtige Exporte |
<Accordion title="Provider-Subpfade">
| Subpfad | Wichtige Exporte |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Kuratierte Helfer für die Einrichtung lokaler/selbstgehosteter Anbieter |
| `plugin-sdk/self-hosted-provider-setup` | Fokussierte Einrichtungshelfer für selbstgehostete OpenAI-kompatible Anbieter |
| `plugin-sdk/cli-backend` | Standardwerte für CLI-Backends + Watchdog-Konstanten |
| `plugin-sdk/provider-auth-runtime` | Laufzeit-Helfer zur Auflösung von API-Schlüsseln für Provider-Plugins |
| `plugin-sdk/provider-auth-api-key` | Helfer für API-Key-Onboarding/Profile-Schreiben wie `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Standard-Builder für OAuth-Auth-Ergebnisse |
| `plugin-sdk/provider-auth-login` | Gemeinsame Helfer für interaktiven Login bei Provider-Plugins |
| `plugin-sdk/provider-env-vars` | Lookup-Helfer für Auth-Env-Variablen von Anbietern |
| `plugin-sdk/provider-setup` | Kuratierte Hilfsfunktionen für das Setup lokaler/self-hosted Provider |
| `plugin-sdk/self-hosted-provider-setup` | Fokussierte Hilfsfunktionen für das Setup self-hosted OpenAI-kompatibler Provider |
| `plugin-sdk/cli-backend` | CLI-Backend-Standards + Watchdog-Konstanten |
| `plugin-sdk/provider-auth-runtime` | Hilfsfunktionen zur API-Key-Auflösung zur Laufzeit für Provider-Plugins |
| `plugin-sdk/provider-auth-api-key` | Hilfsfunktionen für API-Key-Onboarding/Profilschreibvorgänge wie `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Standard-Builder für OAuth-Authentifizierungsergebnisse |
| `plugin-sdk/provider-auth-login` | Gemeinsame Hilfsfunktionen für interaktiven Login bei Provider-Plugins |
| `plugin-sdk/provider-env-vars` | Hilfsfunktionen für das Lookup von Provider-Auth-Umgebungsvariablen |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Builder für Replay-Policies, Helfer für Anbieter-Endpunkte und Helfer zur Modell-ID-Normalisierung wie `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Builder für Replay-Richtlinien, Hilfsfunktionen für Provider-Endpunkte und Hilfsfunktionen zur Normalisierung von Modell-IDs wie `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Generische Helfer für HTTP-/Endpunktfähigkeiten von Anbietern, einschließlich Multipart-Form-Helfern für Audio-Transkription |
| `plugin-sdk/provider-web-fetch-contract` | Schmale Helfer für Verträge zu Web-Fetch-Konfiguration/-Auswahl wie `enablePluginInConfig` und `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helfer für Registrierung/Cache von Web-Fetch-Anbietern |
| `plugin-sdk/provider-web-search-config-contract` | Schmale Helfer für Web-Suche-Konfiguration/Anmeldedaten bei Anbietern, die kein Plugin-Enable-Wiring benötigen |
| `plugin-sdk/provider-web-search-contract` | Schmale Helfer für Verträge zu Web-Suche-Konfiguration/Anmeldedaten wie `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` und scoped Setter/Getter für Anmeldedaten |
| `plugin-sdk/provider-web-search` | Helfer für Registrierung/Cache/Runtime von Web-Suche-Anbietern |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Bereinigung + Diagnose von Gemini-Schemas und xAI-Kompatibilitätshelfer wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` und ähnliche |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Typen für Stream-Wrapper und gemeinsame Wrapper-Helfer für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Native Helfer für Provider-Transport wie guarded fetch, Message-Transforms im Transport und beschreibbare Event-Streams im Transport |
| `plugin-sdk/provider-onboard` | Helfer zum Patchen von Onboarding-Konfigurationen |
| `plugin-sdk/global-singleton` | Prozesslokale Helfer für Singleton/Map/Cache |
| `plugin-sdk/group-activation` | Schmale Helfer für Aktivierungsmodus von Gruppen und Parsing von Befehlen |
| `plugin-sdk/provider-http` | Generische Hilfsfunktionen für HTTP/Endpunkt-Capabilities von Providern, einschließlich Hilfsfunktionen für Multipart-Formulare bei Audio-Transkription |
| `plugin-sdk/provider-web-fetch-contract` | Enge Hilfsfunktionen für Web-Fetch-Config-/Auswahlverträge wie `enablePluginInConfig` und `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Hilfsfunktionen für Registrierung/Cache von Web-Fetch-Providern |
| `plugin-sdk/provider-web-search-config-contract` | Enge Hilfsfunktionen für Web-Search-Config/Anmeldeinformationen für Provider, die kein Wiring zur Plugin-Aktivierung benötigen |
| `plugin-sdk/provider-web-search-contract` | Enge Hilfsfunktionen für Web-Search-Config-/Anmeldedatenverträge wie `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` sowie Scoped-Setter/Getter für Anmeldedaten |
| `plugin-sdk/provider-web-search` | Hilfsfunktionen für Registrierung/Cache/Runtime von Web-Search-Providern |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini-Schema-Bereinigung + Diagnosen sowie xAI-Kompatibilitäts-Hilfsfunktionen wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` und Ähnliches |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Stream-Wrapper-Typen und gemeinsame Wrapper-Hilfsfunktionen für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Native Hilfsfunktionen für Provider-Transporte wie geschütztes Fetch, Transformationen von Transportnachrichten und beschreibbare Transport-Ereignisströme |
| `plugin-sdk/provider-onboard` | Hilfsfunktionen für das Patchen der Onboarding-Config |
| `plugin-sdk/global-singleton` | Hilfsfunktionen für prozesslokale Singleton-/Map-/Cache-Strukturen |
| `plugin-sdk/group-activation` | Enge Hilfsfunktionen für Gruppenaktivierungsmodi und Befehlsparsing |
</Accordion>
<Accordion title="Unterpfade für Auth und Sicherheit">
| Unterpfad | Wichtige Exporte |
<Accordion title="Subpfade für Authentifizierung und Sicherheit">
| Subpfad | Wichtige Exporte |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, Helfer für Command-Registry, Helfer für Sender-Autorisierung |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, Hilfsfunktionen für die Befehlsregistrierung, Hilfsfunktionen für die Absenderautorisierung |
| `plugin-sdk/command-status` | Builder für Befehls-/Hilfenachrichten wie `buildCommandsMessagePaginated` und `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Helfer für Auflösung von Approvern und Action-Auth im selben Chat |
| `plugin-sdk/approval-client-runtime` | Helfer für native Exec-Genehmigungsprofile/-Filter |
| `plugin-sdk/approval-delivery-runtime` | Native Adapter für Genehmigungs-Capability/-Zustellung |
| `plugin-sdk/approval-gateway-runtime` | Gemeinsamer Helfer zur Auflösung von Approval-Gateway |
| `plugin-sdk/approval-handler-adapter-runtime` | Leichtgewichtige Helfer zum Laden nativer Approval-Adapter für Hot-Channel-Entry-Points |
| `plugin-sdk/approval-handler-runtime` | Breitere Runtime-Helfer für Approval-Handler; bevorzugen Sie die schmaleren Adapter-/Gateway-Seams, wenn diese ausreichen |
| `plugin-sdk/approval-native-runtime` | Native Helfer für Approval-Target + Account-Binding |
| `plugin-sdk/approval-reply-runtime` | Payload-Helfer für Antworten auf Exec-/Plugin-Genehmigungen |
| `plugin-sdk/reply-dedupe` | Schmale Reset-Helfer für Dedupe eingehender Antworten |
| `plugin-sdk/channel-contract-testing` | Schmale Helfer für Channel-Vertragstests ohne das breite Testing-Barrel |
| `plugin-sdk/command-auth-native` | Native Command-Auth + Helfer für natives Session-Target |
| `plugin-sdk/command-detection` | Gemeinsame Helfer zur Erkennung von Befehlen |
| `plugin-sdk/command-primitives-runtime` | Leichtgewichtige Prädikate für Befehlstext in Hot-Channel-Pfaden |
| `plugin-sdk/command-surface` | Helfer für Normalisierung von Command-Bodys und Command-Surface |
| `plugin-sdk/approval-auth-runtime` | Hilfsfunktionen für die Auflösung von Approvern und Action-Auth im selben Chat |
| `plugin-sdk/approval-client-runtime` | Hilfsfunktionen für native Exec-Freigabeprofile/-Filter |
| `plugin-sdk/approval-delivery-runtime` | Adapter für native Freigabe-Capabilities/-Zustellung |
| `plugin-sdk/approval-gateway-runtime` | Gemeinsame Hilfsfunktion für die Auflösung des Freigabe-Gateways |
| `plugin-sdk/approval-handler-adapter-runtime` | Leichtgewichtige Hilfsfunktionen zum Laden nativer Freigabe-Adapter für Hot-Channel-Entry-Points |
| `plugin-sdk/approval-handler-runtime` | Umfassendere Runtime-Hilfsfunktionen für Freigabe-Handler; bevorzugen Sie die engeren Adapter-/Gateway-Seams, wenn diese ausreichen |
| `plugin-sdk/approval-native-runtime` | Hilfsfunktionen für native Freigabeziele + Account-Bindings |
| `plugin-sdk/approval-reply-runtime` | Hilfsfunktionen für Reply-Payloads bei Exec-/Plugin-Freigaben |
| `plugin-sdk/reply-dedupe` | Enge Hilfsfunktionen zum Zurücksetzen der Deduplizierung eingehender Antworten |
| `plugin-sdk/channel-contract-testing` | Enge Testhilfsfunktionen für Channel-Verträge ohne das breite Testing-Barrel |
| `plugin-sdk/command-auth-native` | Native Hilfsfunktionen für Befehlsauthentifizierung + native Sitzungsziele |
| `plugin-sdk/command-detection` | Gemeinsame Hilfsfunktionen zur Befehlserkennung |
| `plugin-sdk/command-primitives-runtime` | Leichtgewichtige Prädikate für Befehlstext auf Hot-Channel-Pfaden |
| `plugin-sdk/command-surface` | Hilfsfunktionen für die Normalisierung von Befehlsinhalt und Befehlsoberfläche |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Schmale Helfer zur Sammlung von Secret-Verträgen für Secret-Oberflächen von Channel/Plugin |
| `plugin-sdk/secret-ref-runtime` | Schmale Helfer für `coerceSecretRef` und SecretRef-Typisierung für das Parsen von Secret-Verträgen/Konfiguration |
| `plugin-sdk/security-runtime` | Gemeinsame Helfer für Vertrauen, DM-Gating, externe Inhalte und Secret-Sammlung |
| `plugin-sdk/ssrf-policy` | Helfer für Host-Allowlist und SSRF-Richtlinien für private Netzwerke |
| `plugin-sdk/ssrf-dispatcher` | Schmale Hilfen für pinned dispatcher ohne die breite Infra-Runtime-Oberfläche |
| `plugin-sdk/ssrf-runtime` | Pinned dispatcher, SSRF-geschütztes fetch und SSRF-Richtlinien-Helfer |
| `plugin-sdk/secret-input` | Helfer zum Parsen von Secret-Eingaben |
| `plugin-sdk/webhook-ingress` | Helfer für Webhook-Anfragen/-Targets |
| `plugin-sdk/webhook-request-guards` | Helfer für Body-Größe/Timeout von Anfragen |
| `plugin-sdk/channel-secret-runtime` | Enge Hilfsfunktionen für die Sammlung von Secret-Verträgen auf Channel-/Plugin-Secret-Oberflächen |
| `plugin-sdk/secret-ref-runtime` | Enge Hilfsfunktionen für `coerceSecretRef` und SecretRef-Typisierung für das Parsen von Secret-Verträgen/Config |
| `plugin-sdk/security-runtime` | Gemeinsame Hilfsfunktionen für Vertrauen, DM-Gating, externe Inhalte und Secret-Sammlung |
| `plugin-sdk/ssrf-policy` | Hilfsfunktionen für Host-Allowlist und SSRF-Richtlinien für private Netzwerke |
| `plugin-sdk/ssrf-dispatcher` | Enge Hilfsfunktionen für angeheftete Dispatcher ohne die breite Infra-Runtime-Oberfläche |
| `plugin-sdk/ssrf-runtime` | Hilfsfunktionen für angeheftete Dispatcher, SSRF-geschütztes Fetch und SSRF-Richtlinien |
| `plugin-sdk/secret-input` | Hilfsfunktionen zum Parsen von Secret-Eingaben |
| `plugin-sdk/webhook-ingress` | Hilfsfunktionen für Webhook-Anfragen/-Ziele |
| `plugin-sdk/webhook-request-guards` | Hilfsfunktionen für Body-Größe/Timeout bei Anfragen |
</Accordion>
<Accordion title="Unterpfade für Runtime und Speicherung">
| Unterpfad | Wichtige Exporte |
<Accordion title="Subpfade für Runtime und Speicher">
| Subpfad | Wichtige Exporte |
| --- | --- |
| `plugin-sdk/runtime` | Breite Helfer für Runtime/Logging/Backup/Plugin-Installation |
| `plugin-sdk/runtime-env` | Schmale Helfer für Runtime-Env, Logger, Timeout, Retry und Backoff |
| `plugin-sdk/channel-runtime-context` | Generische Helfer für Registrierung und Lookup von Channel-Runtime-Kontext |
| `plugin-sdk/runtime` | Umfassende Hilfsfunktionen für Runtime/Logging/Backups/Plugin-Installation |
| `plugin-sdk/runtime-env` | Enge Hilfsfunktionen für Runtime-Umgebung, Logger, Timeout, Retry und Backoff |
| `plugin-sdk/channel-runtime-context` | Generische Hilfsfunktionen für Registrierung und Lookup des Channel-Runtime-Kontexts |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Gemeinsame Helfer für Plugin-Command/Hook/HTTP/interaktiv |
| `plugin-sdk/hook-runtime` | Gemeinsame Helfer für Pipeline von Webhook/internen Hooks |
| `plugin-sdk/lazy-runtime` | Helfer für Lazy-Import/Binding von Runtime wie `createLazyRuntimeModule`, `createLazyRuntimeMethod` und `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helfer für Prozess-`exec` |
| `plugin-sdk/cli-runtime` | CLI-Helfer für Formatierung, Warten und Version |
| `plugin-sdk/gateway-runtime` | Helfer für Gateway-Client und Channel-Status-Patches |
| `plugin-sdk/config-runtime` | Helfer zum Laden/Schreiben von Konfiguration und Lookup-Helfer für Plugin-Konfiguration |
| `plugin-sdk/telegram-command-config` | Helfer zur Normalisierung von Name/Beschreibung für Telegram-Befehle und zur Prüfung von Duplikaten/Konflikten, auch wenn die gebündelte Telegram-Vertragsoberfläche nicht verfügbar ist |
| `plugin-sdk/text-autolink-runtime` | Erkennung von Autolinks für Dateiverweise ohne das breite Barrel `text-runtime` |
| `plugin-sdk/approval-runtime` | Helfer für Exec-/Plugin-Genehmigungen, Builder für Approval-Capabilities, Auth-/Profil-Helfer, native Routing-/Runtime-Helfer |
| `plugin-sdk/reply-runtime` | Gemeinsame Runtime-Helfer für Inbound/Antwort, Chunking, Dispatch, Heartbeat, Reply-Planer |
| `plugin-sdk/reply-dispatch-runtime` | Schmale Helfer für Dispatch/Finalisierung von Antworten |
| `plugin-sdk/reply-history` | Gemeinsame Helfer für Reply-History in kurzen Fenstern wie `buildHistoryContext`, `recordPendingHistoryEntry` und `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/plugin-runtime` | Gemeinsame Hilfsfunktionen für Plugin-Befehle/-Hooks/-HTTP/-Interaktivität |
| `plugin-sdk/hook-runtime` | Gemeinsame Hilfsfunktionen für Webhook-/interne Hook-Pipelines |
| `plugin-sdk/lazy-runtime` | Hilfsfunktionen für Lazy-Runtime-Import/Binding wie `createLazyRuntimeModule`, `createLazyRuntimeMethod` und `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Hilfsfunktionen für die Ausführung von Prozessen |
| `plugin-sdk/cli-runtime` | Hilfsfunktionen für CLI-Formatierung, Warten und Version |
| `plugin-sdk/gateway-runtime` | Hilfsfunktionen für Gateway-Client und Patches des Channel-Status |
| `plugin-sdk/config-runtime` | Hilfsfunktionen zum Laden/Schreiben von Config und zum Lookup von Plugin-Config |
| `plugin-sdk/telegram-command-config` | Hilfsfunktionen zur Normalisierung von Telegram-Befehlsnamen/-beschreibungen und zu Prüfungen auf Duplikate/Konflikte, auch wenn die gebündelte Telegram-Vertragsoberfläche nicht verfügbar ist |
| `plugin-sdk/text-autolink-runtime` | Erkennung von Autolinks für Dateireferenzen ohne das breite `text-runtime`-Barrel |
| `plugin-sdk/approval-runtime` | Hilfsfunktionen für Exec-/Plugin-Freigaben, Builder für Freigabe-Capabilities, Auth-/Profil-Hilfsfunktionen, natives Routing/Runtime |
| `plugin-sdk/reply-runtime` | Gemeinsame Inbound-/Reply-Runtime-Hilfsfunktionen, Chunking, Dispatch, Heartbeat, Reply-Planer |
| `plugin-sdk/reply-dispatch-runtime` | Enge Hilfsfunktionen für Reply-Dispatch/-Abschluss und Konversationslabels |
| `plugin-sdk/reply-history` | Gemeinsame Hilfsfunktionen für den Antwortverlauf in kurzen Fenstern wie `buildHistoryContext`, `recordPendingHistoryEntry` und `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Schmale Helfer für Text-/Markdown-Chunking |
| `plugin-sdk/session-store-runtime` | Helfer für Pfad und updated-at von Session Store |
| `plugin-sdk/state-paths` | Helfer für Pfade von State/OAuth-Verzeichnissen |
| `plugin-sdk/routing` | Helfer für Route/Sitzungsschlüssel/Account-Binding wie `resolveAgentRoute`, `buildAgentSessionKey` und `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Gemeinsame Helfer für Zusammenfassungen von Channel-/Account-Status, Standardwerte für Runtime-Status und Helfer für Issue-Metadaten |
| `plugin-sdk/target-resolver-runtime` | Gemeinsame Helfer für Target-Resolver |
| `plugin-sdk/string-normalization-runtime` | Helfer zur Normalisierung von Slugs/Strings |
| `plugin-sdk/request-url` | String-URLs aus fetch-/request-ähnlichen Eingaben extrahieren |
| `plugin-sdk/run-command` | Zeitgesteuerter Command-Runner mit normalisierten Ergebnissen für stdout/stderr |
| `plugin-sdk/param-readers` | Gängige Leser für Tool-/CLI-Parameter |
| `plugin-sdk/tool-payload` | Normalisierte Payloads aus Tool-Ergebnisobjekten extrahieren |
| `plugin-sdk/tool-send` | Kanonische Send-Target-Felder aus Tool-Args extrahieren |
| `plugin-sdk/temp-path` | Gemeinsame Helfer für temporäre Download-Pfade |
| `plugin-sdk/logging-core` | Helfer für Subsystem-Logger und Redaction |
| `plugin-sdk/markdown-table-runtime` | Helfer für Modus und Konvertierung von Markdown-Tabellen |
| `plugin-sdk/json-store` | Kleine Helfer zum Lesen/Schreiben von JSON-State |
| `plugin-sdk/file-lock` | Wiedereintrittsfähige File-Lock-Helfer |
| `plugin-sdk/persistent-dedupe` | Helfer für festplattenbasierten Dedupe-Cache |
| `plugin-sdk/acp-runtime` | ACP-Runtime-/Sitzungs- und Reply-Dispatch-Helfer |
| `plugin-sdk/acp-binding-resolve-runtime` | Nur-Lese-Auflösung von ACP-Bindings ohne Imports für Lifecycle-Start |
| `plugin-sdk/agent-config-primitives` | Schmale Primitive für Agenten-Runtime-Konfigurationsschema |
| `plugin-sdk/boolean-param` | Leser für lose Boolean-Parameter |
| `plugin-sdk/dangerous-name-runtime` | Helfer zur Auflösung von Dangerous-Name-Matching |
| `plugin-sdk/device-bootstrap` | Helfer für Device-Bootstrap und Pairing-Token |
| `plugin-sdk/reply-chunking` | Enge Hilfsfunktionen für Text-/Markdown-Chunking |
| `plugin-sdk/session-store-runtime` | Hilfsfunktionen für Pfade des Sitzungsstores + `updated-at` |
| `plugin-sdk/state-paths` | Hilfsfunktionen für Pfade von State-/OAuth-Verzeichnissen |
| `plugin-sdk/routing` | Hilfsfunktionen für Route-/Sitzungsschlüssel-/Account-Bindings wie `resolveAgentRoute`, `buildAgentSessionKey` und `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Gemeinsame Hilfsfunktionen für Zusammenfassungen des Channel-/Account-Status, Runtime-State-Standards und Metadaten zu Problemen |
| `plugin-sdk/target-resolver-runtime` | Gemeinsame Hilfsfunktionen für den Target-Resolver |
| `plugin-sdk/string-normalization-runtime` | Hilfsfunktionen zur Slug-/String-Normalisierung |
| `plugin-sdk/request-url` | String-URLs aus Fetch-/Request-ähnlichen Eingaben extrahieren |
| `plugin-sdk/run-command` | Runner für zeitgesteuerte Befehle mit normalisierten Ergebnissen für stdout/stderr |
| `plugin-sdk/param-readers` | Allgemeine Param-Reader für Tools/CLI |
| `plugin-sdk/tool-payload` | Normalisierte Payloads aus Objekten für Tool-Ergebnisse extrahieren |
| `plugin-sdk/tool-send` | Kanonische Ziel-Felder für Send aus Tool-Argumenten extrahieren |
| `plugin-sdk/temp-path` | Gemeinsame Hilfsfunktionen für Pfade temporärer Downloads |
| `plugin-sdk/logging-core` | Hilfsfunktionen für Subsystem-Logger und Redaction |
| `plugin-sdk/markdown-table-runtime` | Hilfsfunktionen für Markdown-Tabellenmodus und -Konvertierung |
| `plugin-sdk/json-store` | Kleine Hilfsfunktionen zum Lesen/Schreiben von JSON-State |
| `plugin-sdk/file-lock` | Wiederbetretbare Hilfsfunktionen für Dateisperren |
| `plugin-sdk/persistent-dedupe` | Hilfsfunktionen für festplattenbasierten Dedupe-Cache |
| `plugin-sdk/acp-runtime` | Hilfsfunktionen für ACP-Runtime/Sitzung und Reply-Dispatch |
| `plugin-sdk/acp-binding-resolve-runtime` | Schreibgeschützte Auflösung von ACP-Bindings ohne Lifecycle-Startup-Imports |
| `plugin-sdk/agent-config-primitives` | Enge Primitive für das Runtime-Config-Schema des Agents |
| `plugin-sdk/boolean-param` | Lockere Param-Auslesung für Boolean |
| `plugin-sdk/dangerous-name-runtime` | Hilfsfunktionen zur Auflösung von Abgleichen für gefährliche Namen |
| `plugin-sdk/device-bootstrap` | Hilfsfunktionen für Device-Bootstrap und Pairing-Token |
| `plugin-sdk/extension-shared` | Gemeinsame Primitive für passive Channels, Status und Ambient-Proxy-Helfer |
| `plugin-sdk/models-provider-runtime` | Helfer für Antworten von `/models`-Befehl/Anbieter |
| `plugin-sdk/skill-commands-runtime` | Helfer zum Auflisten von Skill-Befehlen |
| `plugin-sdk/native-command-registry` | Helfer für Registry/Build/Serialize nativer Befehle |
| `plugin-sdk/agent-harness` | Experimentelle Oberfläche für vertrauenswürdige Plugins zu Low-Level-Agent-Harnesses: Harness-Typen, Hilfen für Steuerung/Abbruch aktiver Läufe, Hilfen für OpenClaw-Tool-Bridge und Utilities für Versuchsergebnisse |
| `plugin-sdk/provider-zai-endpoint` | Helfer zur Erkennung von Z.A.I-Endpunkten |
| `plugin-sdk/infra-runtime` | Helfer für Systemereignisse/Heartbeat |
| `plugin-sdk/collection-runtime` | Kleine Helfer für begrenzte Caches |
| `plugin-sdk/diagnostic-runtime` | Helfer für Diagnose-Flags und -Ereignisse |
| `plugin-sdk/error-runtime` | Fehlergraph, Formatierung, gemeinsame Helfer zur Fehlerklassifizierung, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helfer für gewrapptes fetch, Proxy und pinned Lookup |
| `plugin-sdk/runtime-fetch` | Dispatcher-bewusstes Runtime-fetch ohne Importe von Proxy/guarded-fetch |
| `plugin-sdk/models-provider-runtime` | Hilfsfunktionen für `/models`-Befehl/Provider-Antworten |
| `plugin-sdk/skill-commands-runtime` | Hilfsfunktionen zum Auflisten von Skill-Befehlen |
| `plugin-sdk/native-command-registry` | Hilfsfunktionen für Registrieren/Erstellen/Serialisieren nativer Befehle |
| `plugin-sdk/agent-harness` | Experimentelle Oberfläche für vertrauenswürdige Plugins für Low-Level-Agent-Harnesses: Harness-Typen, Hilfsfunktionen zum Steuern/Abbrechen aktiver Läufe, OpenClaw-Tool-Bridge-Hilfsfunktionen, Hilfsfunktionen für Tool-Fortschrittsformatierung/-details und Hilfsfunktionen für Versuchsergebnisse |
| `plugin-sdk/provider-zai-endpoint` | Hilfsfunktionen zur Erkennung von Z.AI-Endpunkten |
| `plugin-sdk/infra-runtime` | Hilfsfunktionen für Systemereignisse/Heartbeat |
| `plugin-sdk/collection-runtime` | Kleine Hilfsfunktionen für begrenzte Caches |
| `plugin-sdk/diagnostic-runtime` | Hilfsfunktionen für Diagnose-Flags und -Ereignisse |
| `plugin-sdk/error-runtime` | Hilfsfunktionen für Fehlergraph, Formatierung, gemeinsame Fehlerklassifizierung, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Hilfsfunktionen für umhülltes Fetch, Proxy und angeheftetes Lookup |
| `plugin-sdk/runtime-fetch` | Dispatcher-sensitives Runtime-Fetch ohne Importe für Proxy/geschütztes Fetch |
| `plugin-sdk/response-limit-runtime` | Begrenzter Reader für Response-Bodys ohne die breite Media-Runtime-Oberfläche |
| `plugin-sdk/session-binding-runtime` | Aktueller Zustand der Konversationsbindung ohne Routing für konfigurierte Bindings oder Pairing-Stores |
| `plugin-sdk/session-store-runtime` | Lesehilfen für Session Store ohne breite Imports für Config-Schreibvorgänge/Wartung |
| `plugin-sdk/context-visibility-runtime` | Auflösung der Sichtbarkeit von Kontext und Filterung von ergänzendem Kontext ohne breite Imports für Konfiguration/Sicherheit |
| `plugin-sdk/string-coerce-runtime` | Schmale Helfer zur primitiven Coercion/Normalisierung von Records/Strings ohne Markdown-/Logging-Imports |
| `plugin-sdk/host-runtime` | Helfer zur Normalisierung von Hostname und SCP-Host |
| `plugin-sdk/retry-runtime` | Helfer für Retry-Konfiguration und Retry-Runner |
| `plugin-sdk/agent-runtime` | Helfer für Agent-Verzeichnis/Identität/Workspace |
| `plugin-sdk/directory-runtime` | Konfigurationsgestützte Verzeichnisabfrage/Deduplizierung |
| `plugin-sdk/session-binding-runtime` | Aktueller Konversations-Binding-Status ohne Routing für konfigurierte Bindings oder Pairing-Stores |
| `plugin-sdk/session-store-runtime` | Hilfsfunktionen zum Lesen des Sitzungsstores ohne breite Importe für Config-Schreibvorgänge/Wartung |
| `plugin-sdk/context-visibility-runtime` | Auflösung der Kontextsichtigkeit und Filterung zusätzlichen Kontexts ohne breite Importe für Config/Sicherheit |
| `plugin-sdk/string-coerce-runtime` | Enge Hilfsfunktionen für primitive Records/String-Coercion und Normalisierung ohne Importe für Markdown/Logging |
| `plugin-sdk/host-runtime` | Hilfsfunktionen zur Normalisierung von Hostnamen und SCP-Hosts |
| `plugin-sdk/retry-runtime` | Hilfsfunktionen für Retry-Config und Retry-Runner |
| `plugin-sdk/agent-runtime` | Hilfsfunktionen für Agent-Verzeichnis/Identität/Workspace |
| `plugin-sdk/directory-runtime` | Config-gestützte Verzeichnisabfrage/-Deduplizierung |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Unterpfade für Capability und Testing">
| Unterpfad | Wichtige Exporte |
<Accordion title="Subpfade für Capabilities und Tests">
| Subpfad | Wichtige Exporte |
| --- | --- |
| `plugin-sdk/media-runtime` | Gemeinsame Helfer für Fetch/Transformation/Speicherung von Medien plus Builder für Media-Payload |
| `plugin-sdk/media-store` | Schmale Media-Store-Helfer wie `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | Gemeinsame Helfer für Failover bei Mediengenerierung, Auswahl von Kandidaten und Meldungen bei fehlenden Modellen |
| `plugin-sdk/media-understanding` | Typen für Anbieter von Medienverständnis plus anbieterorientierte Exporte für Bild-/Audio-Helfer |
| `plugin-sdk/text-runtime` | Gemeinsame Helfer für Text/Markdown/Logging wie Entfernen von assitentensichtbarem Text, Helfer für Rendern/Chunking/Tabellen in Markdown, Hilfen für Redaction, Directive-Tag-Helfer und Utilities für sicheren Text |
| `plugin-sdk/text-chunking` | Helfer für Chunking von ausgehendem Text |
| `plugin-sdk/speech` | Typen für Speech-Anbieter plus anbieterorientierte Helfer für Directives, Registry und Validierung |
| `plugin-sdk/speech-core` | Gemeinsame Typen für Speech-Anbieter, Registry-, Directive- und Normalisierungshelfer |
| `plugin-sdk/realtime-transcription` | Typen für Realtime-Transkriptionsanbieter, Registry-Helfer und gemeinsamer WebSocket-Sitzungshelfer |
| `plugin-sdk/realtime-voice` | Typen für Realtime-Voice-Anbieter und Registry-Helfer |
| `plugin-sdk/image-generation` | Typen für Anbieter von Bildgenerierung |
| `plugin-sdk/image-generation-core` | Gemeinsame Typen für Bildgenerierung, Failover, Auth und Registry-Helfer |
| `plugin-sdk/music-generation` | Typen für Anbieter/Anfragen/Ergebnisse der Musikgenerierung |
| `plugin-sdk/music-generation-core` | Gemeinsame Typen für Musikgenerierung, Failover-Helfer, Provider-Lookup und Parsing von Modellreferenzen |
| `plugin-sdk/video-generation` | Typen für Anbieter/Anfragen/Ergebnisse der Videogenerierung |
| `plugin-sdk/video-generation-core` | Gemeinsame Typen für Videogenerierung, Failover-Helfer, Provider-Lookup und Parsing von Modellreferenzen |
| `plugin-sdk/webhook-targets` | Registry für Webhook-Targets und Helfer zum Installieren von Routen |
| `plugin-sdk/webhook-path` | Helfer zur Normalisierung von Webhook-Pfaden |
| `plugin-sdk/web-media` | Gemeinsame Helfer zum Laden entfernter/lokaler Medien |
| `plugin-sdk/zod` | Re-exportiertes `zod` für Konsumenten des Plugin SDK |
| `plugin-sdk/media-runtime` | Gemeinsame Hilfsfunktionen für Media-Fetch/Transformation/Speicherung sowie Builder für Media-Payloads |
| `plugin-sdk/media-store` | Enge Hilfsfunktionen für Media-Store wie `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | Gemeinsame Hilfsfunktionen für Failover bei Media-Generierung, Kandidatenauswahl und Meldungen bei fehlenden Modellen |
| `plugin-sdk/media-understanding` | Providertypen für Medienverständnis sowie providerseitige Hilfs-Exporte für Bild/Audio |
| `plugin-sdk/text-runtime` | Gemeinsame Hilfsfunktionen für Text/Markdown/Logging wie das Entfernen von für Assistants sichtbarem Text, Hilfsfunktionen für Markdown-Rendering/-Chunking/-Tabellen, Hilfsfunktionen für Redaction, Hilfsfunktionen für Directive-Tags und Hilfsfunktionen für sicheren Text |
| `plugin-sdk/text-chunking` | Hilfsfunktion für das Chunking ausgehenden Texts |
| `plugin-sdk/speech` | Speech-Providertypen sowie providerseitige Hilfsfunktionen für Directive, Registry und Validierung |
| `plugin-sdk/speech-core` | Gemeinsame Hilfsfunktionen für Speech-Providertypen, Registry, Directive und Normalisierung |
| `plugin-sdk/realtime-transcription` | Providertypen für Echtzeit-Transkription, Hilfsfunktionen für Registries und gemeinsame WebSocket-Sitzungshilfsfunktion |
| `plugin-sdk/realtime-voice` | Providertypen für Echtzeit-Stimme und Hilfsfunktionen für Registries |
| `plugin-sdk/image-generation` | Providertypen für Bildgenerierung |
| `plugin-sdk/image-generation-core` | Gemeinsame Hilfsfunktionen für Typen, Failover, Auth und Registry bei Bildgenerierung |
| `plugin-sdk/music-generation` | Provider-/Anfrage-/Ergebnistypen für Musikgenerierung |
| `plugin-sdk/music-generation-core` | Gemeinsame Hilfsfunktionen für Typen, Failover, Provider-Lookup und Modellreferenz-Parsen bei Musikgenerierung |
| `plugin-sdk/video-generation` | Provider-/Anfrage-/Ergebnistypen für Videogenerierung |
| `plugin-sdk/video-generation-core` | Gemeinsame Hilfsfunktionen für Typen, Failover, Provider-Lookup und Modellreferenz-Parsen bei Videogenerierung |
| `plugin-sdk/webhook-targets` | Hilfsfunktionen für Webhook-Ziel-Registry und Routeninstallation |
| `plugin-sdk/webhook-path` | Hilfsfunktionen zur Normalisierung von Webhook-Pfaden |
| `plugin-sdk/web-media` | Gemeinsame Hilfsfunktionen zum Laden entfernter/lokaler Medien |
| `plugin-sdk/zod` | Re-exportiertes `zod` für Verbraucher des Plugin-SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Memory-Unterpfade">
| Unterpfad | Wichtige Exporte |
<Accordion title="Memory-Subpfade">
| Subpfad | Wichtige Exporte |
| --- | --- |
| `plugin-sdk/memory-core` | Gebündelte Hilfsoberfläche für memory-core für Manager-/Konfigurations-/Datei-/CLI-Helfer |
| `plugin-sdk/memory-core-engine-runtime` | Runtime-Fassade für Memory-Index/Suche |
| `plugin-sdk/memory-core-host-engine-foundation` | Exporte der Foundation-Engine für den Memory-Host |
| `plugin-sdk/memory-core-host-engine-embeddings` | Embedding-Verträge für den Memory-Host, Zugriff auf die Registry, lokaler Anbieter und generische Batch-/Remote-Helfer |
| `plugin-sdk/memory-core-host-engine-qmd` | Exporte der QMD-Engine für den Memory-Host |
| `plugin-sdk/memory-core-host-engine-storage` | Exporte der Storage-Engine für den Memory-Host |
| `plugin-sdk/memory-core-host-multimodal` | Multimodale Helfer für den Memory-Host |
| `plugin-sdk/memory-core-host-query` | Query-Helfer für den Memory-Host |
| `plugin-sdk/memory-core-host-secret` | Secret-Helfer für den Memory-Host |
| `plugin-sdk/memory-core-host-events` | Helfer für das Ereignisjournal des Memory-Host |
| `plugin-sdk/memory-core-host-status` | Status-Helfer für den Memory-Host |
| `plugin-sdk/memory-core-host-runtime-cli` | CLI-Runtime-Helfer für den Memory-Host |
| `plugin-sdk/memory-core-host-runtime-core` | Core-Runtime-Helfer für den Memory-Host |
| `plugin-sdk/memory-core-host-runtime-files` | Datei-/Runtime-Helfer für den Memory-Host |
| `plugin-sdk/memory-host-core` | Anbieterneutraler Alias für Core-Runtime-Helfer des Memory-Host |
| `plugin-sdk/memory-host-events` | Anbieterneutraler Alias für Helfer des Ereignisjournals des Memory-Host |
| `plugin-sdk/memory-host-files` | Anbieterneutraler Alias für Datei-/Runtime-Helfer des Memory-Host |
| `plugin-sdk/memory-host-markdown` | Gemeinsame Managed-Markdown-Helfer für memory-nahe Plugins |
| `plugin-sdk/memory-host-search` | Runtime-Fassade des Active Memory für Zugriff auf den Search-Manager |
| `plugin-sdk/memory-host-status` | Anbieterneutraler Alias für Status-Helfer des Memory-Host |
| `plugin-sdk/memory-lancedb` | Gebündelte Hilfsoberfläche für memory-lancedb |
| `plugin-sdk/memory-core` | Gebündelte Hilfsoberfläche von memory-core für Hilfsfunktionen zu Manager/Config/Datei/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Runtime-Fassade für Speicherindex/Suche |
| `plugin-sdk/memory-core-host-engine-foundation` | Exporte der Foundation-Engine des Memory-Hosts |
| `plugin-sdk/memory-core-host-engine-embeddings` | Embedding-Verträge des Memory-Hosts, Registry-Zugriff, lokaler Provider sowie generische Hilfsfunktionen für Batch/Remote |
| `plugin-sdk/memory-core-host-engine-qmd` | Exporte der QMD-Engine des Memory-Hosts |
| `plugin-sdk/memory-core-host-engine-storage` | Exporte der Storage-Engine des Memory-Hosts |
| `plugin-sdk/memory-core-host-multimodal` | Multimodale Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-core-host-query` | Query-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-core-host-secret` | Secret-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-core-host-events` | Hilfsfunktionen für das Ereignisjournal des Memory-Hosts |
| `plugin-sdk/memory-core-host-status` | Status-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-core-host-runtime-cli` | CLI-Runtime-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-core-host-runtime-core` | Core-Runtime-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-core-host-runtime-files` | Datei-/Runtime-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-host-core` | Anbieterneutraler Alias für Core-Runtime-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-host-events` | Anbieterneutraler Alias für Hilfsfunktionen für das Ereignisjournal des Memory-Hosts |
| `plugin-sdk/memory-host-files` | Anbieterneutraler Alias für Datei-/Runtime-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-host-markdown` | Gemeinsame Hilfsfunktionen für verwaltetes Markdown für Memory-nahe Plugins |
| `plugin-sdk/memory-host-search` | Active Memory Runtime-Fassade für den Zugriff auf Search-Manager |
| `plugin-sdk/memory-host-status` | Anbieterneutraler Alias für Status-Hilfsfunktionen des Memory-Hosts |
| `plugin-sdk/memory-lancedb` | Gebündelte Hilfsoberfläche von memory-lancedb |
</Accordion>
<Accordion title="Reservierte Unterpfade für gebündelte Helfer">
| Familie | Aktuelle Unterpfade | Vorgesehene Verwendung |
<Accordion title="Reservierte Subpfade für gebündelte Hilfsfunktionen">
| Familie | Aktuelle Subpfade | Vorgesehene Verwendung |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helfer zur Unterstützung des gebündelten Browser-Plugins (`browser-support` bleibt das Kompatibilitäts-Barrel) |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Hilfsfunktionen zur Unterstützung des gebündelten Browser-Plugins (`browser-support` bleibt das Kompatibilitäts-Barrel) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Gebündelte Hilfs-/Runtime-Oberfläche für Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Gebündelte Hilfs-/Runtime-Oberfläche für LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Gebündelte Hilfsoberfläche für IRC |
| Channel-spezifische Helfer | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Kompatibilitäts-/Helfer-Seams für gebündelte Channels |
| Auth-/plugin-spezifische Helfer | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Helfer-Seams für gebündelte Features/Plugins; `plugin-sdk/github-copilot-token` exportiert derzeit `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` und `resolveCopilotApiToken` |
| Channel-spezifische Hilfsfunktionen | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Gebündelte Kompatibilitäts-/Hilfs-Seams für Channels |
| Auth-/plugin-spezifische Hilfsfunktionen | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Gebündelte Feature-/Plugin-Hilfs-Seams; `plugin-sdk/github-copilot-token` exportiert derzeit `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` und `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## Verwandt
- [Überblick über das Plugin SDK](/de/plugins/sdk-overview)
- [Plugin-SDK-Setup](/de/plugins/sdk-setup)
- [Plugin SDK overview](/de/plugins/sdk-overview)
- [Plugin SDK setup](/de/plugins/sdk-setup)
- [Plugins erstellen](/de/plugins/building-plugins)

234
docs/de/providers/google.md
View File

@ -1,20 +1,20 @@
---
read_when:
- Sie möchten Google-Gemini-Modelle mit OpenClaw verwenden.
- Sie benötigen den Authentifizierungsablauf mit API key oder OAuth.
summary: Google-Gemini-Einrichtung (API key + OAuth, Bildgenerierung, Medienverarbeitung, TTS, Web-Suche)
- Sie benötigen den Auth-Flow mit API-Key oder OAuth.
summary: Google-Gemini-Einrichtung (API-Key + OAuth, Bildgenerierung, Medienverständnis, TTS, Websuche)
title: Google (Gemini)
x-i18n:
generated_at: "2026-04-24T06:54:06Z"
generated_at: "2026-04-24T09:00:43Z"
model: gpt-5.4
provider: openai
source_hash: b43d7171f56ecdfb49a25256783433e64f99a02760b3bc6f0e1055195f556f5d
source_hash: 7e66c9dd637e26976659d04b9b7e2452e6881945dab6011970f9e1c5e4a9a685
source_path: providers/google.md
workflow: 15
---
Das Google-Plugin stellt Zugriff auf Gemini-Modelle über Google AI Studio bereit sowie
Bildgenerierung, Medienverarbeitung (Bild/Audio/Video), Text-to-Speech und Web-Suche über
Das Google-Plugin bietet Zugriff auf Gemini-Modelle über Google AI Studio sowie
Bildgenerierung, Medienverständnis (Bild/Audio/Video), Text-to-Speech und Websuche über
Gemini Grounding.
- Provider: `google`
@ -24,10 +24,10 @@ Gemini Grounding.
## Erste Schritte
Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrichtungs-Schritten.
Wählen Sie Ihre bevorzugte Auth-Methode und folgen Sie den Einrichtungsschritten.
<Tabs>
<Tab title="API key">
<Tab title="API-Key">
**Am besten geeignet für:** standardmäßigen Gemini-API-Zugriff über Google AI Studio.
<Steps>
@ -36,7 +36,7 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich
openclaw onboard --auth-choice gemini-api-key
```
Oder den Schlüssel direkt übergeben:
Oder den Key direkt übergeben:
```bash
openclaw onboard --non-interactive \
@ -45,7 +45,7 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich
--gemini-api-key "$GEMINI_API_KEY"
```
</Step>
<Step title="Ein Standardmodell setzen">
<Step title="Ein Standardmodell festlegen">
```json5
{
agents: {
@ -56,7 +56,7 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich
}
```
</Step>
<Step title="Verifizieren, dass das Modell verfügbar ist">
<Step title="Prüfen, ob das Modell verfügbar ist">
```bash
openclaw models list --provider google
```
@ -64,22 +64,22 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich
</Steps>
<Tip>
Die Umgebungsvariablen `GEMINI_API_KEY` und `GOOGLE_API_KEY` werden beide akzeptiert. Verwenden Sie diejenige, die Sie bereits konfiguriert haben.
Die Umgebungsvariablen `GEMINI_API_KEY` und `GOOGLE_API_KEY` werden beide akzeptiert. Verwenden Sie die, die Sie bereits konfiguriert haben.
</Tip>
</Tab>
<Tab title="Gemini CLI (OAuth)">
**Am besten geeignet für:** Wiederverwendung eines bestehenden Gemini-CLI-Logins über PKCE OAuth statt eines separaten API-Schlüssels.
**Am besten geeignet für:** die Wiederverwendung einer bestehenden Gemini-CLI-Anmeldung per PKCE-OAuth statt eines separaten API-Keys.
<Warning>
Der Provider `google-gemini-cli` ist eine inoffizielle Integration. Einige Benutzer
berichten von Kontobeschränkungen bei der Nutzung von OAuth auf diese Weise. Nutzung auf eigenes Risiko.
Der Provider `google-gemini-cli` ist eine inoffizielle Integration. Einige Nutzer
berichten bei dieser OAuth-Nutzung über Kontoeinschränkungen. Verwendung auf eigenes Risiko.
</Warning>
<Steps>
<Step title="Die Gemini CLI installieren">
Der lokale Befehl `gemini` muss in `PATH` verfügbar sein.
Der lokale Befehl `gemini` muss auf `PATH` verfügbar sein.
```bash
# Homebrew
@ -92,12 +92,12 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich
OpenClaw unterstützt sowohl Homebrew-Installationen als auch globale npm-Installationen, einschließlich
gängiger Windows-/npm-Layouts.
</Step>
<Step title="Über OAuth anmelden">
<Step title="Per OAuth anmelden">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
</Step>
<Step title="Verifizieren, dass das Modell verfügbar ist">
<Step title="Prüfen, ob das Modell verfügbar ist">
```bash
openclaw models list --provider google-gemini-cli
```
@ -115,60 +115,61 @@ Wählen Sie Ihre bevorzugte Authentifizierungsmethode und folgen Sie den Einrich
(Oder die Varianten `GEMINI_CLI_*`.)
<Note>
Wenn Gemini-CLI-OAuth-Requests nach dem Login fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder
Falls Gemini-CLI-OAuth-Anfragen nach der Anmeldung fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder
`GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host und versuchen Sie es erneut.
</Note>
<Note>
Wenn der Login fehlschlägt, bevor der Browser-Flow startet, stellen Sie sicher, dass der lokale Befehl `gemini`
installiert ist und in `PATH` liegt.
Falls die Anmeldung fehlschlägt, bevor der Browser-Flow startet, stellen Sie sicher, dass der lokale Befehl `gemini`
installiert und auf `PATH` ist.
</Note>
Der reine OAuth-Provider `google-gemini-cli` ist eine separate Oberfläche für Text-Inferenz.
Bildgenerierung, Medienverarbeitung und Gemini Grounding bleiben auf
Der nur auf OAuth basierende Provider `google-gemini-cli` ist eine separate Oberfläche
für Textinferenz. Bildgenerierung, Medienverständnis und Gemini Grounding verbleiben auf
der Provider-ID `google`.
</Tab>
</Tabs>
## Fähigkeiten
## Funktionen
| Fähigkeit | Unterstützt |
| ---------------------- | -------------------------------- |
| Chat Completions | Ja |
| Bildgenerierung | Ja |
| Musikgenerierung | Ja |
| Text-to-speech | Ja |
| Bildverarbeitung | Ja |
| Audio-Transkription | Ja |
| Videoverarbeitung | Ja |
| Web-Suche (Grounding) | Ja |
| Thinking/Reasoning | Ja (Gemini 2.5+ / Gemini 3+) |
| Gemma-4-Modelle | Ja |
| Funktion | Unterstützt |
| ---------------------- | ------------------------------ |
| Chat-Completions | Ja |
| Bildgenerierung | Ja |
| Musikgenerierung | Ja |
| Text-to-Speech | Ja |
| Realtime-Sprache | Ja (Google Live API) |
| Bildverständnis | Ja |
| Audiotranskription | Ja |
| Videoverständnis | Ja |
| Websuche (Grounding) | Ja |
| Thinking/Reasoning | Ja (Gemini 2.5+ / Gemini 3+) |
| Gemma-4-Modelle | Ja |
<Tip>
Gemini-3-Modelle verwenden `thinkingLevel` statt `thinkingBudget`. OpenClaw mappt
Reasoning-Steuerungen für Gemini 3, Gemini 3.1 und Alias `gemini-*-latest` auf
`thinkingLevel`, damit Standardläufe/Läufe mit geringer Latenz keine deaktivierten
Werte für `thinkingBudget` senden.
Gemini-3-Modelle verwenden `thinkingLevel` statt `thinkingBudget`. OpenClaw bildet
Reasoning-Steuerungen für Gemini 3, Gemini 3.1 und den Alias `gemini-*-latest`
auf `thinkingLevel` ab, damit Standard-/Low-Latency-Läufe keine deaktivierten
`thinkingBudget`-Werte senden.
Gemma-4-Modelle (zum Beispiel `gemma-4-26b-a4b-it`) unterstützen Thinking-Modus. OpenClaw
schreibt `thinkingBudget` auf ein unterstütztes Google-`thinkingLevel` für Gemma 4 um.
Wenn Thinking auf `off` gesetzt ist, bleibt Thinking deaktiviert, statt auf
`MINIMAL` gemappt zu werden.
Gemma-4-Modelle (zum Beispiel `gemma-4-26b-a4b-it`) unterstützen den Thinking-Modus. OpenClaw
schreibt `thinkingBudget` für Gemma 4 in ein unterstütztes Google-`thinkingLevel` um.
Wenn Thinking auf `off` gesetzt wird, bleibt Thinking deaktiviert, statt auf
`MINIMAL` abgebildet zu werden.
</Tip>
## Bildgenerierung
Der gebündelte `google`-Provider für Bildgenerierung verwendet standardmäßig
Der gebündelte Provider `google` für Bildgenerierung verwendet standardmäßig
`google/gemini-3.1-flash-image-preview`.
- Unterstützt auch `google/gemini-3-pro-image-preview`
- Generieren: bis zu 4 Bilder pro Request
- Generieren: bis zu 4 Bilder pro Anfrage
- Edit-Modus: aktiviert, bis zu 5 Eingabebilder
- Geometrie-Steuerungen: `size`, `aspectRatio` und `resolution`
- Geometriesteuerungen: `size`, `aspectRatio` und `resolution`
Um Google als Standard-Provider für Bilder zu verwenden:
So verwenden Sie Google als Standardprovider für Bilder:
```json5
{
@ -183,20 +184,20 @@ Um Google als Standard-Provider für Bilder zu verwenden:
```
<Note>
Siehe [Image Generation](/de/tools/image-generation) für gemeinsame Tool-Parameter, Provider-Auswahl und Failover-Verhalten.
Siehe [Bildgenerierung](/de/tools/image-generation) für gemeinsame Tool-Parameter, Providerauswahl und Failover-Verhalten.
</Note>
## Videogenerierung
Das gebündelte `google`-Plugin registriert auch Videogenerierung über das gemeinsame
Das gebündelte `google`-Plugin registriert außerdem Videogenerierung über das gemeinsame
Tool `video_generate`.
- Standard-Videomodell: `google/veo-3.1-fast-generate-preview`
- Modi: Text-zu-Video, Bild-zu-Video und Flows mit einzelner Video-Referenz
- Modi: Text-zu-Video, Bild-zu-Video und Flows mit einzelner Videoreferenz
- Unterstützt `aspectRatio`, `resolution` und `audio`
- Aktuelle Dauerbegrenzung: **4 bis 8 Sekunden**
- Aktuelle Begrenzung der Dauer: **4 bis 8 Sekunden**
Um Google als Standard-Provider für Video zu verwenden:
So verwenden Sie Google als Standardprovider für Videos:
```json5
{
@ -211,22 +212,22 @@ Um Google als Standard-Provider für Video zu verwenden:
```
<Note>
Siehe [Video Generation](/de/tools/video-generation) für gemeinsame Tool-Parameter, Provider-Auswahl und Failover-Verhalten.
Siehe [Videogenerierung](/de/tools/video-generation) für gemeinsame Tool-Parameter, Providerauswahl und Failover-Verhalten.
</Note>
## Musikgenerierung
Das gebündelte `google`-Plugin registriert auch Musikgenerierung über das gemeinsame
Das gebündelte `google`-Plugin registriert außerdem Musikgenerierung über das gemeinsame
Tool `music_generate`.
- Standard-Musikmodell: `google/lyria-3-clip-preview`
- Unterstützt auch `google/lyria-3-pro-preview`
- Prompt-Steuerungen: `lyrics` und `instrumental`
- Ausgabeformat: standardmäßig `mp3`, zusätzlich `wav` bei `google/lyria-3-pro-preview`
- Referenz-Inputs: bis zu 10 Bilder
- Sitzungsgebundene Läufe werden über den gemeinsamen Task-/Status-Flow entkoppelt, einschließlich `action: "status"`
- Ausgabeformat: standardmäßig `mp3`, zusätzlich `wav` auf `google/lyria-3-pro-preview`
- Referenzeingaben: bis zu 10 Bilder
- Session-gestützte Läufe werden über den gemeinsamen Task-/Status-Flow entkoppelt, einschließlich `action: "status"`
Um Google als Standard-Provider für Musik zu verwenden:
So verwenden Sie Google als Standardprovider für Musik:
```json5
{
@ -241,20 +242,20 @@ Um Google als Standard-Provider für Musik zu verwenden:
```
<Note>
Siehe [Music Generation](/de/tools/music-generation) für gemeinsame Tool-Parameter, Provider-Auswahl und Failover-Verhalten.
Siehe [Musikgenerierung](/de/tools/music-generation) für gemeinsame Tool-Parameter, Providerauswahl und Failover-Verhalten.
</Note>
## Text-to-Speech
Der gebündelte Sprach-Provider `google` verwendet den Gemini-API-TTS-Pfad mit
Der gebündelte Sprachprovider `google` verwendet den TTS-Pfad der Gemini API mit
`gemini-3.1-flash-tts-preview`.
- Standardstimme: `Kore`
- Auth: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` oder `GOOGLE_API_KEY`
- Ausgabe: WAV für reguläre TTS-Anhänge, PCM für Talk/Telefonie
- Native Sprachnachrichten-Ausgabe: wird auf diesem Gemini-API-Pfad nicht unterstützt, weil die API PCM statt Opus zurückgibt
- Native Voice-Note-Ausgabe: auf diesem Gemini-API-Pfad nicht unterstützt, da die API PCM statt Opus zurückgibt
Um Google als Standard-TTS-Provider zu verwenden:
So verwenden Sie Google als Standardprovider für TTS:
```json5
{
@ -273,9 +274,9 @@ Um Google als Standard-TTS-Provider zu verwenden:
}
```
Gemini-API-TTS akzeptiert expressive Audio-Tags in eckigen Klammern im Text, etwa
`[whispers]` oder `[laughs]`. Um Tags aus der sichtbaren Chat-Antwort herauszuhalten, während
sie trotzdem an TTS gesendet werden, setzen Sie sie in einen Block `[[tts:text]]...[[/tts:text]]`:
Gemini-API-TTS akzeptiert ausdrucksstarke Audio-Tags in eckigen Klammern im Text, etwa
`[whispers]` oder `[laughs]`. Um Tags aus der sichtbaren Chat-Antwort herauszuhalten und
sie dennoch an TTS zu senden, platzieren Sie sie in einem Block `[[tts:text]]...[[/tts:text]]`:
```text
Hier ist der saubere Antworttext.
@ -284,23 +285,80 @@ Hier ist der saubere Antworttext.
```
<Note>
Ein API-Schlüssel aus der Google Cloud Console, der auf die Gemini API beschränkt ist, ist für diesen
Ein in der Google Cloud Console auf die Gemini API beschränkter API-Key ist für diesen
Provider gültig. Dies ist nicht der separate Pfad der Cloud Text-to-Speech API.
</Note>
## Realtime-Sprache
Das gebündelte `google`-Plugin registriert einen Realtime-Sprachprovider, der auf der
Gemini Live API basiert, für Backend-Audiobridges wie Voice Call und Google Meet.
| Einstellung | Konfigurationspfad | Standard |
| ---------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Modell | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| Stimme | `...google.voice` | `Kore` |
| Temperature | `...google.temperature` | (nicht gesetzt) |
| VAD-Startempfindlichkeit | `...google.startSensitivity` | (nicht gesetzt) |
| VAD-Endempfindlichkeit | `...google.endSensitivity` | (nicht gesetzt) |
| Stilledauer | `...google.silenceDurationMs` | (nicht gesetzt) |
| API-Key | `...google.apiKey` | Fällt zurück auf `models.providers.google.apiKey`, `GEMINI_API_KEY` oder `GOOGLE_API_KEY` |
Beispielkonfiguration für Realtime in Voice Call:
```json5
{
plugins: {
entries: {
"voice-call": {
enabled: true,
config: {
realtime: {
enabled: true,
provider: "google",
providers: {
google: {
model: "gemini-2.5-flash-native-audio-preview-12-2025",
voice: "Kore",
},
},
},
},
},
},
},
}
```
<Note>
Die Google Live API verwendet bidirektionales Audio und Function Calling über einen WebSocket.
OpenClaw passt Audio von Telefonie-/Meet-Bridges an Geminis PCM-Live-API-Stream an und
behält Tool-Aufrufe auf dem gemeinsamen Vertrag für Realtime-Sprache. Lassen Sie `temperature`
ungesetzt, sofern Sie keine Änderungen beim Sampling benötigen; OpenClaw lässt nicht positive Werte weg,
weil Google Live für `temperature: 0` Transkripte ohne Audio zurückgeben kann.
Die Transkription der Gemini API ist ohne `languageCodes` aktiviert; das aktuelle Google-
SDK lehnt Sprachcode-Hinweise auf diesem API-Pfad ab.
</Note>
<Note>
Talk-Browsersitzungen in der Control UI erfordern weiterhin einen Realtime-Sprachprovider mit einer
Browser-WebRTC-Sitzungsimplementierung. Heute ist das OpenAI Realtime; der
Google-Provider ist für Backend-Realtime-Bridges gedacht.
</Note>
## Erweiterte Konfiguration
<AccordionGroup>
<Accordion title="Direkte Wiederverwendung des Gemini-Cache">
Für direkte Gemini-API-Läufe (`api: "google-generative-ai"`) übergibt OpenClaw
einen konfigurierten Handle `cachedContent` an Gemini-Requests.
ein konfiguriertes `cachedContent`-Handle an Gemini-Anfragen.
- Konfigurieren Sie pro Modell oder global mit entweder
`cachedContent` oder dem alten `cached_content`
- Wenn beide vorhanden sind, gewinnt `cachedContent`
- Konfigurieren Sie modellbezogene oder globale Parameter entweder mit
`cachedContent` oder dem Legacy-Wert `cached_content`
- Wenn beide vorhanden sind, hat `cachedContent` Vorrang
- Beispielwert: `cachedContents/prebuilt-context`
- Gemini-Cache-Hit-Nutzung wird in OpenClaw `cacheRead` normalisiert aus
upstream `cachedContentTokenCount`
- Die Gemini-Cache-Treffernutzung wird in OpenClaw als `cacheRead` aus
dem Upstream-Wert `cachedContentTokenCount` normalisiert
```json5
{
@ -320,19 +378,19 @@ Provider gültig. Dies ist nicht der separate Pfad der Cloud Text-to-Speech API.
</Accordion>
<Accordion title="Hinweise zur JSON-Nutzung von Gemini CLI">
Wenn der OAuth-Provider `google-gemini-cli` verwendet wird, normalisiert OpenClaw
<Accordion title="Hinweise zur JSON-Nutzung der Gemini CLI">
Bei Verwendung des OAuth-Providers `google-gemini-cli` normalisiert OpenClaw
die JSON-Ausgabe der CLI wie folgt:
- Antworttext kommt aus dem JSON-Feld `response` der CLI.
- Nutzung fällt auf `stats` zurück, wenn die CLI `usage` leer lässt.
- `stats.cached` wird in OpenClaw `cacheRead` normalisiert.
- Wenn `stats.input` fehlt, leitet OpenClaw Input-Tokens aus
- Der Antworttext stammt aus dem JSON-Feld `response` der CLI.
- Die Nutzungsdaten fallen auf `stats` zurück, wenn die CLI `usage` leer lässt.
- `stats.cached` wird in OpenClaw zu `cacheRead` normalisiert.
- Wenn `stats.input` fehlt, leitet OpenClaw die Eingabetokens aus
`stats.input_tokens - stats.cached` ab.
</Accordion>
<Accordion title="Umgebung und Daemon-Setup">
<Accordion title="Umgebungs- und Daemon-Einrichtung">
Wenn das Gateway als Daemon läuft (launchd/systemd), stellen Sie sicher, dass `GEMINI_API_KEY`
diesem Prozess zur Verfügung steht (zum Beispiel in `~/.openclaw/.env` oder über
`env.shellEnv`).
@ -342,16 +400,16 @@ Provider gültig. Dies ist nicht der separate Pfad der Cloud Text-to-Speech API.
## Verwandt
<CardGroup cols={2}>
<Card title="Model selection" href="/de/concepts/model-providers" icon="layers">
Provider, Modell-Referenzen und Failover-Verhalten auswählen.
<Card title="Modellauswahl" href="/de/concepts/model-providers" icon="layers">
Auswahl von Providern, Modell-Referenzen und Failover-Verhalten.
</Card>
<Card title="Image generation" href="/de/tools/image-generation" icon="image">
Gemeinsame Parameter des Bild-Tools und Provider-Auswahl.
<Card title="Bildgenerierung" href="/de/tools/image-generation" icon="image">
Gemeinsame Parameter des Bild-Tools und Providerauswahl.
</Card>
<Card title="Video generation" href="/de/tools/video-generation" icon="video">
Gemeinsame Parameter des Video-Tools und Provider-Auswahl.
<Card title="Videogenerierung" href="/de/tools/video-generation" icon="video">
Gemeinsame Parameter des Video-Tools und Providerauswahl.
</Card>
<Card title="Music generation" href="/de/tools/music-generation" icon="music">
Gemeinsame Parameter des Musik-Tools und Provider-Auswahl.
<Card title="Musikgenerierung" href="/de/tools/music-generation" icon="music">
Gemeinsame Parameter des Musik-Tools und Providerauswahl.
</Card>
</CardGroup>

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

@ -1,207 +1,210 @@
---
read_when:
- Suche nach Definitionen der öffentlichen Release-Kanäle.
- Suche nach Versionsbenennung und Taktung.
summary: Öffentliche Release-Kanäle, Versionsbenennung und Taktung
- Suche nach öffentlichen Definitionen der Release-Channels
- Suche nach Versionsbenennung und Taktung
summary: Öffentliche Release-Channels, Versionsbenennung und Taktung
title: Release-Richtlinie
x-i18n:
generated_at: "2026-04-24T06:57:20Z"
generated_at: "2026-04-24T09:00:43Z"
model: gpt-5.4
provider: openai
source_hash: 32c6d904e21f6d4150cf061ae27594bc2364f0927c48388362b16d8bf97491dc
source_hash: 2cba6cd02c6fb2380abd8d46e10567af2f96c7c6e45236689d69289348b829ce
source_path: reference/RELEASING.md
workflow: 15
---
OpenClaw hat drei öffentliche Release-Kanäle:
OpenClaw hat drei öffentliche Release-Lanes:
- stable: getaggte Releases, die standardmäßig auf npm `beta` veröffentlichen oder bei ausdrücklicher Anforderung auf npm `latest`
- stable: getaggte Releases, die standardmäßig auf npm `beta` veröffentlichen oder bei expliziter Anforderung auf npm `latest`
- beta: Prerelease-Tags, die auf npm `beta` veröffentlichen
- dev: der bewegliche Head von `main`
- dev: der fortlaufende Head von `main`
## Versionsbenennung
- Version für Stable-Releases: `YYYY.M.D`
- Stable-Release-Version: `YYYY.M.D`
- Git-Tag: `vYYYY.M.D`
- Version für Stable-Korrektur-Releases: `YYYY.M.D-N`
- Stable-Korrektur-Release-Version: `YYYY.M.D-N`
- Git-Tag: `vYYYY.M.D-N`
- Version für Beta-Prereleases: `YYYY.M.D-beta.N`
- Beta-Prerelease-Version: `YYYY.M.D-beta.N`
- Git-Tag: `vYYYY.M.D-beta.N`
- Monat oder Tag nicht mit führenden Nullen auffüllen
- `latest` bedeutet das aktuell hochgestufte stabile npm-Release
- `beta` bedeutet das aktuelle Installationsziel für Beta
- Stable- und Stable-Korrektur-Releases veröffentlichen standardmäßig auf npm `beta`; Release-Operatoren können explizit `latest` ansteuern oder später einen geprüften Beta-Build hochstufen
- `latest` bedeutet das aktuell promotete stabile npm-Release
- `beta` bedeutet das aktuelle Beta-Installationsziel
- Stable- und Stable-Korrektur-Releases veröffentlichen standardmäßig auf npm `beta`; Release-Operatoren können explizit `latest` als Ziel setzen oder später einen geprüften Beta-Build promoten
- Jedes stabile OpenClaw-Release liefert das npm-Paket und die macOS-App gemeinsam aus;
Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paketpfad, während
Build/Signierung/Notarisierung der Mac-App für Stable reserviert bleibt, sofern nicht ausdrücklich angefordert
Build/Signieren/Notarisieren der Mac-App Stable vorbehalten ist, sofern nicht ausdrücklich anders angefordert
## Release-Taktung
- Releases gehen zuerst über Beta
- Releases laufen beta-first
- Stable folgt erst, nachdem die neueste Beta validiert wurde
- Maintainer schneiden Releases normalerweise aus einem Branch `release/YYYY.M.D`, der
aus dem aktuellen `main` erstellt wird, damit Release-Validierung und Fixes neue
von `main` erstellt wird, damit Release-Validierung und Fixes neue
Entwicklung auf `main` nicht blockieren
- Wenn ein Beta-Tag bereits gepusht oder veröffentlicht wurde und einen Fix braucht, schneiden
Maintainer das nächste Tag `-beta.N`, statt das alte Beta-Tag zu löschen oder neu zu erstellen
- Detaillierter Release-Prozess, Freigaben, Zugangsdaten und Recovery-Hinweise sind
- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und einen Fix benötigt, schneiden Maintainer
das nächste Tag `-beta.N`, statt das alte Beta-Tag zu löschen oder neu zu erstellen
- Detaillierte Release-Prozedur, Genehmigungen, Anmeldedaten und Recovery-Hinweise sind
nur für Maintainer bestimmt
## Release-Preflight
- Führen Sie `pnpm check:test-types` vor dem Release-Preflight aus, damit Test-TypeScript
- Führen Sie vor dem Release-Preflight `pnpm check:test-types` aus, damit Test-TypeScript
auch außerhalb des schnelleren lokalen Gates `pnpm check` abgedeckt bleibt
- Führen Sie `pnpm check:architecture` vor dem Release-Preflight aus, damit die umfassenderen Import-
Cycle- und Architekturgrenzenprüfungen auch außerhalb des schnelleren lokalen Gates grün sind
- Führen Sie `pnpm build && pnpm ui:build` vor `pnpm release:check` aus, damit die erwarteten
Release-Artefakte `dist/*` und das Bundle der Control UI für den Schritt zur
Pack-Validierung vorhanden sind
- Führen Sie `pnpm release:check` vor jedem getaggten Release aus
- Release-Checks laufen jetzt in einem separaten manuellen Workflow:
- Führen Sie vor dem Release-Preflight `pnpm check:architecture` aus, damit die umfassenderen Import-
Zyklus- und Architekturgrenzen-Prüfungen auch außerhalb des schnelleren lokalen Gates grün sind
- Führen Sie vor `pnpm release:check` `pnpm build && pnpm ui:build` aus, damit die erwarteten
`dist/*`-Release-Artefakte und das Bundle der Control UI für den Pack-
Validierungsschritt vorhanden sind
- Führen Sie vor jedem getaggten Release `pnpm release:check` aus
- Release-Prüfungen laufen jetzt in einem separaten manuellen Workflow:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` führt vor der Release-Freigabe außerdem das QA-Lab-Mock-Parity-Gate sowie die Live-
QA-Lanes für Matrix und Telegram aus. Die Live-Lanes verwenden die
Umgebung `qa-live-shared`; Telegram verwendet zusätzlich Convex-CI-Credential-Leases.
- Cross-OS-Installations- und Upgrade-Validierung zur Laufzeit wird aus dem
- `OpenClaw Release Checks` führt vor der Release-Freigabe auch das QA-Lab-Mock-Parity-Gate sowie die Live-
QA-Lanes für Matrix und Telegram aus. Die Live-Lanes verwenden die Umgebung
`qa-live-shared`; Telegram verwendet außerdem Convex-CI-Credential-Leases.
- Laufzeitvalidierung für Installation und Upgrade über mehrere Betriebssysteme hinweg wird aus dem
privaten Caller-Workflow
`openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`
angestoßen, der den wiederverwendbaren öffentlichen Workflow
ausgelöst, der den wiederverwendbaren öffentlichen Workflow
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
aufruft
- Diese Aufteilung ist beabsichtigt: Halten Sie den echten npm-Release-Pfad kurz,
deterministisch und artefaktfokussiert, während langsamere Live-Checks in ihrer
eigenen Lane bleiben, damit sie die Veröffentlichung weder verzögern noch blockieren
- Release-Checks müssen vom Workflow-Ref `main` oder von einem
Workflow-Ref `release/YYYY.M.D` aus ausgelöst werden, damit Workflow-Logik und Secrets
kontrolliert bleiben
- Diese Aufteilung ist beabsichtigt: Der echte npm-Release-Pfad soll kurz,
deterministisch und artefaktfokussiert bleiben, während langsamere Live-Prüfungen in ihrer
eigenen Lane bleiben, damit sie die Veröffentlichung nicht verzögern oder blockieren
- Release-Prüfungen müssen aus der Workflow-Ref von `main` oder aus einer
Workflow-Ref `release/YYYY.M.D` ausgelöst werden, damit Workflow-Logik und Secrets kontrolliert bleiben
- Dieser Workflow akzeptiert entweder ein bestehendes Release-Tag oder den aktuellen vollständigen
40-stelligen Commit-SHA des Workflow-Branch
- Im Commit-SHA-Modus akzeptiert er nur den aktuellen HEAD des Workflow-Branch; verwenden Sie
für ältere Release-Commits ein Release-Tag
- Der Validierungs-Preflight von `OpenClaw NPM Release` akzeptiert ebenfalls den aktuellen
vollständigen 40-stelligen Commit-SHA des Workflow-Branch, ohne dass ein gepushtes Tag erforderlich ist
- Dieser SHA-Pfad ist nur zur Validierung und kann nicht in eine echte Veröffentlichung hochgestuft werden
- Im SHA-Modus synthetisiert der Workflow `v<package.json version>` nur für die
Prüfung der Paketmetadaten; echte Veröffentlichung erfordert weiterhin ein echtes Release-Tag
- Beide Workflows halten den echten Veröffentlichungs- und Hochstufungspfad auf GitHub-gehosteten
40-stelligen Workflow-Branch-Commit-SHA
- Im Commit-SHA-Modus akzeptiert er nur den aktuellen HEAD des Workflow-Branch; verwenden Sie ein
Release-Tag für ältere Release-Commits
- Das nur zur Validierung dienende Preflight von `OpenClaw NPM Release` akzeptiert ebenfalls den aktuellen
vollständigen 40-stelligen Workflow-Branch-Commit-SHA, ohne ein gepushtes Tag zu erfordern
- Dieser SHA-Pfad dient nur der Validierung und kann nicht zu einer echten Veröffentlichung promotet werden
- Im SHA-Modus erzeugt der Workflow `v<package.json version>` nur für die Prüfung der
Paketmetadaten synthetisch; für die echte Veröffentlichung ist weiterhin ein echtes Release-Tag erforderlich
- Beide Workflows behalten den echten Veröffentlichungs- und Promotion-Pfad auf GitHub-gehosteten
Runnern, während der nicht mutierende Validierungspfad die größeren
Blacksmith-Linux-Runner verwenden kann
- Dieser Workflow führt
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
mit den Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus
- Der npm-Release-Preflight wartet nicht mehr auf die separate Lane der Release-Checks
- Das npm-Release-Preflight wartet nicht mehr auf die separate Lane für Release-Prüfungen
- Führen Sie vor der Freigabe
`RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
aus (oder das passende Beta-/Korrektur-Tag)
- Führen Sie nach der npm-Veröffentlichung
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
aus (oder die passende Beta-/Korrektur-Version), um den veröffentlichten Registry-
Installationspfad in einem frischen temporären Präfix zu verifizieren
- Führen Sie nach einer Beta-Veröffentlichung `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N pnpm test:docker:npm-telegram-live`
aus, um Onboarding mit installiertem Paket, Telegram-Setup und echtes Telegram-E2E
gegen das veröffentlichte npm-Paket zu verifizieren.
Installationspfad in einem frischen temporären Prefix zu verifizieren
- Führen Sie nach einer Beta-Veröffentlichung `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
aus, um Onboarding des installierten Pakets, Telegram-Einrichtung und echtes Telegram-E2E
gegen das veröffentlichte npm-Paket mit dem gemeinsam genutzten geleasten Telegram-Credential-
Pool zu verifizieren. Lokale einmalige Maintainer-Ausführungen können die Convex-Variablen weglassen
und die drei Credentials aus den Umgebungsvariablen `OPENCLAW_QA_TELEGRAM_*` direkt übergeben.
- Maintainer können dieselbe Prüfung nach der Veröffentlichung auch über GitHub Actions mit dem
manuellen Workflow `NPM Telegram Beta E2E` ausführen. Er ist absichtlich nur manuell und läuft
nicht bei jedem Merge.
- Die Release-Automatisierung für Maintainer verwendet jetzt Preflight-then-Promote:
- echte npm-Veröffentlichung muss einen erfolgreichen npm-`preflight_run_id` bestanden haben
- die echte npm-Veröffentlichung muss vom selben Branch `main` oder
`release/YYYY.M.D` gestartet werden wie der erfolgreiche Preflight-Lauf
- stabile npm-Releases verwenden standardmäßig `beta`
- ein stabiles npm-Release kann über Workflow-Input explizit `latest` ansteuern
- tokenbasierte Mutation von npm-Dist-Tags liegt nun in
- eine echte npm-Veröffentlichung muss einen erfolgreichen npm-`preflight_run_id` bestehen
- die echte npm-Veröffentlichung muss aus demselben Branch `main` oder
`release/YYYY.M.D` ausgelöst werden wie der erfolgreiche Preflight-Run
- stabile npm-Releases zielen standardmäßig auf `beta`
- stabile npm-Veröffentlichungen können per Workflow-Eingabe explizit `latest` als Ziel setzen
- tokenbasierte Mutation von npm-dist-tags liegt jetzt in
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
aus Sicherheitsgründen, weil `npm dist-tag add` weiterhin `NPM_TOKEN` benötigt, während das
öffentliche Repo OIDC-only-Publishing beibehält
öffentliche Repo nur OIDC-basierte Veröffentlichung beibehält
- öffentliches `macOS Release` dient nur der Validierung
- echter privater Mac-Publish muss erfolgreiche private Mac-
`preflight_run_id` und `validate_run_id` bestanden haben
- die echten Publish-Pfade stufen vorbereitete Artefakte hoch, statt sie erneut
- eine echte private Mac-Veröffentlichung muss erfolgreiches privates Mac-
`preflight_run_id` und `validate_run_id` bestehen
- die echten Veröffentlichungspfade promoten vorbereitete Artefakte, statt sie erneut
zu bauen
- Für Stable-Korrektur-Releases wie `YYYY.M.D-N` prüft der Post-Publish-Verifier
zusätzlich denselben Temp-Prefix-Upgrade-Pfad von `YYYY.M.D` nach `YYYY.M.D-N`,
damit Release-Korrekturen nicht stillschweigend ältere globale Installationen auf
der Payload der Basis-Stable-Version belassen
- npm-Release-Preflight schlägt fail-closed fehl, sofern das Tarball nicht sowohl
`dist/control-ui/index.html` als auch einen nicht leeren Payload unter `dist/control-ui/assets/` enthält,
damit wir nicht noch einmal ein leeres Browser-Dashboard ausliefern
- Die Verifikation nach der Veröffentlichung prüft außerdem, dass die veröffentlichte Registry-Installation
nicht leere Runtime-Abhängigkeiten gebündelter Plugins unter dem Root-Layout `dist/*`
enthält. Ein Release mit fehlenden oder leeren Abhängigkeits-Payloads für gebündelte Plugins
besteht den Postpublish-Verifier nicht und kann nicht
zu `latest` hochgestuft werden.
- `pnpm test:install:smoke` erzwingt außerdem das Budget für `unpackedSize` des npm-Packages auf
dem Kandidaten-Tarball des Updates, sodass das Installer-E2E versehentliche Vergrößerung des Packs
vor dem Release-Pfad abfängt
- Wenn die Release-Arbeit CI-Planung, Zeitmanifeste für Extensions oder Testmatrizen für
Extensions berührt hat, regenerieren und prüfen Sie die dem Planner gehörenden
Outputs der Workflow-Matrix `checks-node-extensions` aus `.github/workflows/ci.yml`
vor der Freigabe, damit die Release Notes kein veraltetes CI-Layout beschreiben
- Die Bereitschaft für stabile macOS-Releases umfasst auch die Oberflächen des Updaters:
- das GitHub-Release muss am Ende die verpackten Dateien `.zip`, `.dmg` und `.dSYM.zip` enthalten
- `appcast.xml` auf `main` muss nach der Veröffentlichung auf die neue stabile ZIP verweisen
- die verpackte App muss eine nicht-debug Bundle-ID, eine nicht leere Sparkle-Feed-
URL und eine `CFBundleVersion` beibehalten, die mindestens dem kanonischen Sparkle-Build-Floor
für diese Release-Version entspricht
- Bei Stable-Korrektur-Releases wie `YYYY.M.D-N` prüft der Verifier nach der Veröffentlichung
zusätzlich denselben Upgrade-Pfad mit temporärem Prefix von `YYYY.M.D` auf `YYYY.M.D-N`,
damit Release-Korrekturen nicht unbemerkt ältere globale Installationen auf dem
Stable-Basis-Payload belassen
- Das npm-Release-Preflight schlägt fail-closed fehl, wenn das Tarball nicht sowohl
`dist/control-ui/index.html` als auch eine nicht leere Payload unter `dist/control-ui/assets/` enthält,
damit wir nicht erneut ein leeres Browser-Dashboard ausliefern
- Die Verifikation nach der Veröffentlichung prüft außerdem, dass die veröffentlichte Registry-
Installation nicht leere Runtime-Abhängigkeiten gebündelter Plugins unter dem Root-
Layout `dist/*` enthält. Ein Release, das mit fehlenden oder leeren
Payloads für Abhängigkeiten gebündelter Plugins ausgeliefert wird, lässt den Postpublish-Verifier fehlschlagen und kann nicht zu `latest` promotet werden.
- `pnpm test:install:smoke` erzwingt außerdem das `unpackedSize`-Budget des npm-Packs auf
dem Kandidaten-Tarball für das Update, damit das Installer-E2E versehentliche Pack-Aufblähung
vor dem Release-Veröffentlichungspfad erkennt
- Wenn die Release-Arbeit CI-Planung, Timing-Manifeste für Extensions oder
Testmatrizen für Extensions berührt hat, regenerieren und prüfen Sie vor der Freigabe die planner-eigenen
Workflow-Matrix-Ausgaben `checks-node-extensions` aus `.github/workflows/ci.yml`,
damit Release-Notes kein veraltetes CI-Layout beschreiben
- Die Bereitschaft für ein stabiles macOS-Release umfasst auch die Updater-Oberflächen:
- das GitHub-Release muss am Ende die paketierten `.zip`, `.dmg` und `.dSYM.zip` enthalten
- `appcast.xml` auf `main` muss nach der Veröffentlichung auf die neue stabile ZIP zeigen
- die paketierte App muss eine nicht zu Debug gehörende Bundle-ID, eine nicht leere Sparkle-Feed-
URL und eine `CFBundleVersion` mindestens auf dem kanonischen Sparkle-Build-Floor
für diese Release-Version beibehalten
## Inputs für den NPM-Workflow
## NPM-Workflow-Eingaben
`OpenClaw NPM Release` akzeptiert diese operatorgesteuerten Inputs:
`OpenClaw NPM Release` akzeptiert diese operatorgesteuerten Eingaben:
- `tag`: erforderliches Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder
`v2026.4.2-beta.1`; wenn `preflight_only=true`, kann es auch der aktuelle
vollständige 40-stellige Commit-SHA des Workflow-Branch für validierungs-
only-Preflight sein
`v2026.4.2-beta.1`; wenn `preflight_only=true`, darf es auch der aktuelle
vollständige 40-stellige Commit-SHA des Workflow-Branch für ein nur validierendes Preflight sein
- `preflight_only`: `true` nur für Validierung/Build/Paket, `false` für den
echten Publish-Pfad
- `preflight_run_id`: auf dem echten Publish-Pfad erforderlich, damit der Workflow das
vorbereitete Tarball aus dem erfolgreichen Preflight-Lauf wiederverwendet
- `npm_dist_tag`: npm-Ziel-Tag für den Publish-Pfad; Standard ist `beta`
echten Veröffentlichungspfad
- `preflight_run_id`: im echten Veröffentlichungspfad erforderlich, damit der Workflow
das vorbereitete Tarball aus dem erfolgreichen Preflight-Run wiederverwendet
- `npm_dist_tag`: npm-Ziel-Tag für den Veröffentlichungspfad; Standard ist `beta`
`OpenClaw Release Checks` akzeptiert diese operatorgesteuerten Inputs:
`OpenClaw Release Checks` akzeptiert diese operatorgesteuerten Eingaben:
- `ref`: bestehendes Release-Tag oder der aktuelle vollständige 40-stellige Commit-
SHA von `main`, der validiert werden soll, wenn der Workflow von `main` aus ausgelöst wird; von einem
Release-Branch aus verwenden Sie ein bestehendes Release-Tag oder den aktuellen vollständigen 40-stelligen Commit-SHA des Release-Branch
- `ref`: bestehendes Release-Tag oder der aktuelle vollständige 40-stellige `main`-Commit-
SHA, der validiert werden soll, wenn er von `main` aus ausgelöst wird; von einem
Release-Branch aus verwenden Sie ein bestehendes Release-Tag oder den aktuellen vollständigen
40-stelligen Commit-SHA des Release-Branch
Regeln:
- Stable- und Korrektur-Tags dürfen auf `beta` oder `latest` veröffentlichen
- Stable- und Korrektur-Tags dürfen entweder auf `beta` oder `latest` veröffentlichen
- Beta-Prerelease-Tags dürfen nur auf `beta` veröffentlichen
- Für `OpenClaw NPM Release` ist vollständige Commit-SHA-Eingabe nur erlaubt, wenn
- Für `OpenClaw NPM Release` ist die Eingabe eines vollständigen Commit-SHA nur zulässig, wenn
`preflight_only=true`
- `OpenClaw Release Checks` dient immer nur der Validierung und akzeptiert ebenfalls den
aktuellen Commit-SHA des Workflow-Branch
- Der Commit-SHA-Modus für Release-Checks erfordert außerdem den aktuellen HEAD des Workflow-Branch
- Der echte Publish-Pfad muss dasselbe `npm_dist_tag` verwenden wie im Preflight;
- Im Commit-SHA-Modus erfordern Release-Prüfungen außerdem den aktuellen HEAD des Workflow-Branch
- Der echte Veröffentlichungspfad muss denselben `npm_dist_tag` verwenden, der auch während des Preflight verwendet wurde;
der Workflow prüft diese Metadaten, bevor die Veröffentlichung fortgesetzt wird
## Sequenz für stabile npm-Releases
## Ablauf eines stabilen npm-Releases
Beim Schneiden eines stabilen npm-Releases:
1. Führen Sie `OpenClaw NPM Release` mit `preflight_only=true` aus
- Bevor ein Tag existiert, können Sie den aktuellen vollständigen Commit-SHA des Workflow-Branch
für einen Dry-Run zur Validierung des Preflight-Workflows verwenden
2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-First-Ablauf oder `latest` nur,
wenn Sie absichtlich direkt ein stabiles Release veröffentlichen möchten
- Bevor ein Tag existiert, können Sie den aktuellen vollständigen Commit des Workflow-Branch
SHA für einen nur validierenden Trockenlauf des Preflight-Workflows verwenden
2. Wählen Sie `npm_dist_tag=beta` für den normalen beta-first-Ablauf oder `latest` nur dann,
wenn Sie absichtlich eine direkte stabile Veröffentlichung möchten
3. Führen Sie `OpenClaw Release Checks` separat mit demselben Tag oder dem
vollständigen aktuellen Commit-SHA des Workflow-Branch aus, wenn Sie Live-Abdeckung für Prompt-Cache,
QA-Lab-Parität, Matrix und Telegram möchten
vollständigen aktuellen Commit-SHA des Workflow-Branch aus, wenn Sie Live-Prompt-Cache,
QA-Lab-Parity, Matrix- und Telegram-Abdeckung möchten
- Dies ist absichtlich getrennt, damit Live-Abdeckung verfügbar bleibt, ohne
langlaufende oder fragile Checks wieder mit dem Publish-Workflow zu koppeln
lang laufende oder instabile Prüfungen erneut an den Veröffentlichungsworkflow zu koppeln
4. Speichern Sie die erfolgreiche `preflight_run_id`
5. Führen Sie `OpenClaw NPM Release` erneut mit `preflight_only=false`, demselben
`tag`, demselben `npm_dist_tag` und der gespeicherten `preflight_run_id` aus
6. Wenn das Release auf `beta` gelandet ist, verwenden Sie den privaten
Workflow `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
um diese stabile Version von `beta` nach `latest` hochzustufen
um diese stabile Version von `beta` nach `latest` zu promoten
7. Wenn das Release absichtlich direkt auf `latest` veröffentlicht wurde und `beta`
derselben Stable-Version sofort folgen soll, verwenden Sie denselben privaten
Workflow, um beide Dist-Tags auf die Stable-Version zu setzen, oder lassen Sie
die geplante Self-Healing-Synchronisierung `beta` später verschieben
unmittelbar demselben Stable-Build folgen soll, verwenden Sie denselben privaten
Workflow, um beide dist-tags auf die stabile Version zu zeigen, oder lassen Sie später die
geplante Self-Healing-Synchronisierung `beta` verschieben
Die Dist-Tag-Mutation liegt aus Sicherheitsgründen im privaten Repo, weil sie weiterhin
`NPM_TOKEN` benötigt, während das öffentliche Repo OIDC-only-Publishing beibehält.
Die Mutation von dist-tags liegt aus Sicherheitsgründen im privaten Repo, weil sie weiterhin
`NPM_TOKEN` erfordert, während das öffentliche Repo nur OIDC-basierte Veröffentlichung beibehält.
Damit bleiben sowohl der direkte Publish-Pfad als auch der Beta-First-Hochstufungspfad
Damit bleiben sowohl der direkte Veröffentlichungspfad als auch der beta-first-Promotionspfad
dokumentiert und für Operatoren sichtbar.
## Öffentliche Referenzen

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

@ -1,51 +1,51 @@
---
read_when:
- Tests ausführen oder beheben
summary: Wie man Tests lokal ausführt (Vitest) und wann Force-/Coverage-Modi verwendet werden sollten
- Tests ausführen oder korrigieren
summary: Wie Sie Tests lokal ausführen (Vitest) und wann Sie Force-/Coverage-Modi verwenden sollten
title: Tests
x-i18n:
generated_at: "2026-04-24T06:59:14Z"
generated_at: "2026-04-24T09:00:54Z"
model: gpt-5.4
provider: openai
source_hash: df4ad5808ddbc06c704c9bcf9f780b06f9be94ac213ed22e79d880dedcaa6d3b
source_hash: 26cdb5fe005e738ddd00b183e91ccebe08c709bd64eed377d573a37b76e3a3bf
source_path: reference/test.md
workflow: 15
---
- Vollständiges Testing-Kit (Suites, Live, Docker): [Testing](/de/help/testing)
- Vollständiges Test-Kit (Suites, Live, Docker): [Testing](/de/help/testing)
- `pnpm test:force`: Beendet jeden hängen gebliebenen Gateway-Prozess, der den Standard-Control-Port belegt, und führt dann die vollständige Vitest-Suite mit einem isolierten Gateway-Port aus, sodass Server-Tests nicht mit einer laufenden Instanz kollidieren. Verwenden Sie dies, wenn ein vorheriger Gateway-Lauf Port 18789 belegt zurückgelassen hat.
- `pnpm test:coverage`: Führt die Unit-Suite mit V8-Coverage aus (über `vitest.unit.config.ts`). Dies ist ein Gate für Unit-Coverage geladener Dateien, nicht Whole-Repo-All-File-Coverage. Die Schwellenwerte sind 70 % für Lines/Functions/Statements und 55 % für Branches. Da `coverage.all` auf false gesetzt ist, misst das Gate Dateien, die von der Unit-Coverage-Suite geladen wurden, statt jede Quell-Datei aus aufgesplitteten Lanes als nicht abgedeckt zu behandeln.
- `pnpm test:coverage:changed`: Führt Unit-Coverage nur für seit `origin/main` geänderte Dateien aus.
- `pnpm test:changed`: Erweitert geänderte Git-Pfade zu bereichsbezogenen Vitest-Lanes, wenn der Diff nur routbare Quell-/Testdateien betrifft. Änderungen an Konfiguration/Setup fallen weiterhin auf den nativen Root-Projects-Run zurück, damit Änderungen an der Verkabelung bei Bedarf breit erneut ausgeführt werden.
- `pnpm changed:lanes`: Zeigt die Architektur-Lanes an, die durch den Diff gegenüber `origin/main` ausgelöst werden.
- `pnpm check:changed`: Führt das intelligente Changed-Gate für den Diff gegenüber `origin/main` aus. Es führt Core-Arbeit mit Core-Test-Lanes aus, Extension-Arbeit mit Extension-Test-Lanes, test-only-Arbeit nur mit Test-Typecheck/Tests, erweitert Änderungen am öffentlichen Plugin SDK oder am Plugin-Vertrag auf einen Extension-Validierungsdurchlauf und hält release-metadatenbezogene Versions-Bumps auf gezielte Prüfungen für Version/Konfiguration/Root-Abhängigkeiten beschränkt.
- `pnpm test`: Leitet explizite Datei-/Verzeichnisziele über bereichsbezogene Vitest-Lanes. Läufe ohne Ziel verwenden feste Shard-Gruppen und erweitern sich zu Leaf-Konfigurationen für lokale parallele Ausführung; die Extension-Gruppe erweitert sich immer zu den Shard-Konfigurationen pro Extension statt zu einem riesigen Root-Project-Prozess.
- Vollständige Läufe und Läufe mit Extension-Shards aktualisieren lokale Zeitdaten in `.artifacts/vitest-shard-timings.json`; spätere Läufe verwenden diese Zeiten, um langsame und schnelle Shards auszugleichen. Setzen Sie `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, um das lokale Timing-Artefakt zu ignorieren.
- Ausgewählte Testdateien in `plugin-sdk` und `commands` werden jetzt über dedizierte leichte Lanes geroutet, die nur `test/setup.ts` beibehalten; runtime-schwere Fälle bleiben auf ihren bestehenden Lanes.
- Ausgewählte Hilfs-Quelldateien in `plugin-sdk` und `commands` ordnen `pnpm test:changed` nun ebenfalls expliziten benachbarten Tests in diesen leichten Lanes zu, sodass kleine Änderungen an Hilfsfunktionen vermeiden, die schweren runtime-gestützten Suites erneut auszuführen.
- `auto-reply` ist jetzt ebenfalls in drei dedizierte Konfigurationen aufgeteilt (`core`, `top-level`, `reply`), sodass das Reply-Harness nicht die leichteren Top-Level-Status-/Token-/Helper-Tests dominiert.
- Die Basis-Vitest-Konfiguration verwendet jetzt standardmäßig `pool: "threads"` und `isolate: false`, wobei der gemeinsame nicht isolierte Runner über die Repo-Konfigurationen hinweg aktiviert ist.
- `pnpm test:force`: Beendet alle verbliebenen Gateway-Prozesse, die den Standard-Control-Port belegen, und führt dann die vollständige Vitest-Suite mit einem isolierten Gateway-Port aus, damit Server-Tests nicht mit einer laufenden Instanz kollidieren. Verwenden Sie dies, wenn ein vorheriger Gateway-Lauf Port 18789 belegt hinterlassen hat.
- `pnpm test:coverage`: Führt die Unit-Suite mit V8-Coverage aus (über `vitest.unit.config.ts`). Dies ist eine Coverage-Prüfung für geladene Unit-Dateien, nicht eine repositoryweite All-File-Coverage. Die Schwellenwerte sind 70 % für Zeilen/Funktionen/Statements und 55 % für Branches. Da `coverage.all` auf `false` steht, misst die Prüfung Dateien, die von der Unit-Coverage-Suite geladen wurden, statt jede Quelldatei aus aufgeteilten Lanes als nicht abgedeckt zu behandeln.
- `pnpm test:coverage:changed`: Führt Unit-Coverage nur für Dateien aus, die sich seit `origin/main` geändert haben.
- `pnpm test:changed`: Erweitert geänderte Git-Pfade in abgegrenzte Vitest-Lanes, wenn der Diff nur routbare Quell-/Testdateien berührt. Änderungen an Konfiguration/Setup fallen weiterhin auf den nativen Root-Projects-Lauf zurück, sodass Verdrahtungsänderungen bei Bedarf breit erneut ausgeführt werden.
- `pnpm changed:lanes`: Zeigt die architektonischen Lanes, die durch den Diff gegen `origin/main` ausgelöst werden.
- `pnpm check:changed`: Führt die intelligente Changed-Prüfung für den Diff gegen `origin/main` aus. Es führt Core-Arbeit mit Core-Test-Lanes aus, Extension-Arbeit mit Extension-Test-Lanes, reine Test-Arbeit nur mit Test-Typecheck/Tests, erweitert Änderungen am öffentlichen Plugin-SDK oder an Plugin-Verträgen auf einen Extension-Validierungsdurchlauf und hält rein release-metadatenbezogene Versionsanhebungen bei gezielten Prüfungen für Version/Konfiguration/Root-Abhängigkeiten.
- `pnpm test`: Leitet explizite Datei-/Verzeichnisziele über abgegrenzte Vitest-Lanes. Läufe ohne Ziel verwenden feste Shard-Gruppen und erweitern auf Leaf-Konfigurationen für lokale parallele Ausführung; die Extension-Gruppe wird immer zu den Shard-Konfigurationen pro Extension erweitert statt zu einem riesigen Root-Project-Prozess.
- Vollständige Läufe und Extension-Shard-Läufe aktualisieren lokale Timing-Daten in `.artifacts/vitest-shard-timings.json`; spätere Läufe verwenden diese Timings, um langsame und schnelle Shards auszubalancieren. Setzen Sie `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, um das lokale Timing-Artefakt zu ignorieren.
- Ausgewählte Testdateien in `plugin-sdk` und `commands` werden jetzt über dedizierte leichte Lanes geleitet, die nur `test/setup.ts` beibehalten, während laufzeitintensive Fälle auf ihren bestehenden Lanes bleiben.
- Ausgewählte Helper-Quelldateien in `plugin-sdk` und `commands` ordnen `pnpm test:changed` ebenfalls expliziten benachbarten Tests in diesen leichten Lanes zu, sodass kleine Helper-Änderungen nicht die erneute Ausführung schwerer laufzeitgestützter Suites auslösen.
- `auto-reply` ist jetzt ebenfalls in drei dedizierte Konfigurationen aufgeteilt (`core`, `top-level`, `reply`), damit das Reply-Harness nicht die leichteren Top-Level-Tests für Status/Token/Helper dominiert.
- Die Basis-Vitest-Konfiguration verwendet jetzt standardmäßig `pool: "threads"` und `isolate: false`, wobei der gemeinsam genutzte nicht isolierte Runner in den Repo-Konfigurationen aktiviert ist.
- `pnpm test:channels` führt `vitest.channels.config.ts` aus.
- `pnpm test:extensions` und `pnpm test extensions` führen alle Extension-/Plugin-Shards aus. Schwere Kanal-Plugins, das Browser-Plugin und OpenAI laufen als dedizierte Shards; andere Plugin-Gruppen bleiben gebündelt. Verwenden Sie `pnpm test extensions/<id>` für die Lane eines einzelnen gebündelten Plugins.
- `pnpm test:perf:imports`: Aktiviert Reporting für Vitest-Importdauer + Importaufschlüsselung, verwendet aber weiterhin bereichsbezogenes Lane-Routing für explizite Datei-/Verzeichnisziele.
- `pnpm test:perf:imports:changed`: Dasselbe Import-Profiling, aber nur für seit `origin/main` geänderte Dateien.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarkt den gerouteten Changed-Mode-Pfad gegen den nativen Root-Project-Run für denselben committeten Git-Diff.
- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen Worktree-Änderungssatz, ohne vorher zu committen.
- `pnpm test:perf:profile:main`: Schreibt ein CPU-Profil für den Vitest-Main-Thread (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: Schreibt CPU- + Heap-Profile für den Unit-Runner (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: Führt jede Vitest-Leaf-Konfiguration der Full-Suite seriell aus und schreibt gruppierte Laufzeitdaten plus JSON-/Log-Artefakte pro Konfiguration. Der Test Performance Agent verwendet dies als Baseline, bevor er versucht, langsame Tests zu beheben.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: Vergleicht gruppierte Berichte nach einer performanceorientierten Änderung.
- Gateway-Integration: Opt-in über `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` oder `pnpm test:gateway`.
- `pnpm test:e2e`: Führt End-to-End-Smoke-Tests für das Gateway aus (Multi-Instance WS/HTTP/Node-Pairing). Verwendet standardmäßig `threads` + `isolate: false` mit adaptiven Workern in `vitest.e2e.config.ts`; anpassbar mit `OPENCLAW_E2E_WORKERS=<n>` und `OPENCLAW_E2E_VERBOSE=1` für ausführliche Logs.
- `pnpm test:live`: Führt Provider-Live-Tests aus (minimax/zai). Erfordert API-Schlüssel und `LIVE=1` (oder providerspezifisch `*_LIVE_TEST=1`), damit sie nicht übersprungen werden.
- `pnpm test:docker:all`: Baut das gemeinsame Image für Live-Tests und das Docker-E2E-Image einmal, führt dann die Docker-Smoke-Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus, standardmäßig mit Parallelität 8. Stimmen Sie den Haupt-Pool mit `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` und den providersensiblen Tail-Pool mit `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` ab; beide sind standardmäßig 8. Der Runner plant nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, außer wenn `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` gesetzt ist, und jede Lane hat ein Timeout von 120 Minuten, überschreibbar mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Logs pro Lane werden unter `.artifacts/docker-tests/<run-id>/` geschrieben.
- `pnpm test:docker:openwebui`: Startet Dockerisiertes OpenClaw + Open WebUI, meldet sich über Open WebUI an, prüft `/api/models` und führt dann einen echten proxied Chat über `/api/chat/completions` aus. Erfordert einen nutzbaren Live-Modell-Schlüssel (zum Beispiel OpenAI in `~/.profile`), zieht ein externes Open-WebUI-Image und ist nicht darauf ausgelegt, so CI-stabil wie die normalen Unit-/E2E-Suites zu sein.
- `pnpm test:docker:mcp-channels`: Startet einen vorbereiteten Gateway-Container und einen zweiten Client-Container, der `openclaw mcp serve` startet, und verifiziert dann Discovery gerouteter Unterhaltungen, Lesen von Transkripten, Anhangsmetadaten, Verhalten der Live-Event-Queue, Routing ausgehender Sendungen und Claude-artige Kanal- + Berechtigungsbenachrichtigungen über die echte stdio-Bridge. Die Claude-Benachrichtigungs-Assertion liest die rohen stdio-MCP-Frames direkt, sodass der Smoke das widerspiegelt, was die Bridge tatsächlich ausgibt.
- `pnpm test:extensions` und `pnpm test extensions` führen alle Extension-/Plugin-Shards aus. Schwere Channel-Plugins, das Browser-Plugin und OpenAI laufen als dedizierte Shards; andere Plugin-Gruppen bleiben gebündelt. Verwenden Sie `pnpm test extensions/<id>` für die Lane eines einzelnen gebündelten Plugins.
- `pnpm test:perf:imports`: Aktiviert Vitest-Berichte zu Importdauer und Importaufschlüsselung und verwendet weiterhin abgegrenztes Lane-Routing für explizite Datei-/Verzeichnisziele.
- `pnpm test:perf:imports:changed`: Dasselbe Import-Profiling, aber nur für Dateien, die sich seit `origin/main` geändert haben.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarkt den gerouteten Changed-Modus-Pfad gegen den nativen Root-Projects-Lauf für denselben eingecheckten Git-Diff.
- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen Worktree-Änderungssatz, ohne zuerst zu committen.
- `pnpm test:perf:profile:main`: Schreibt ein CPU-Profil für den Vitest-Hauptthread (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: Schreibt CPU- und Heap-Profile für den Unit-Runner (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: Führt jede Leaf-Konfiguration der vollständigen Vitest-Suite seriell aus und schreibt gruppierte Laufzeitdaten plus JSON-/Log-Artefakte pro Konfiguration. Der Test Performance Agent verwendet dies als Baseline, bevor er versucht, langsame Tests zu beheben.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: Vergleicht gruppierte Berichte nach einer leistungsorientierten Änderung.
- Gateway-Integration: per Opt-in mit `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` oder `pnpm test:gateway`.
- `pnpm test:e2e`: Führt Gateway-End-to-End-Smoke-Tests aus (Multi-Instance-WS/HTTP/Node-Pairing). Standardmäßig mit `threads` + `isolate: false` und adaptiven Workern in `vitest.e2e.config.ts`; abstimmbar mit `OPENCLAW_E2E_WORKERS=<n>`, und setzen Sie `OPENCLAW_E2E_VERBOSE=1` für ausführliche Logs.
- `pnpm test:live`: Führt Provider-Live-Tests aus (minimax/zai). Benötigt API-Keys und `LIVE=1` (oder provider-spezifisch `*_LIVE_TEST=1`), um das Überspringen aufzuheben.
- `pnpm test:docker:all`: Baut das gemeinsame Live-Test-Image und das Docker-E2E-Image einmal und führt dann die Docker-Smoke-Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` standardmäßig mit einer Nebenläufigkeit von 8 aus. Stimmen Sie den Haupt-Pool mit `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` und den provider-sensitiven Tail-Pool mit `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` ab; beide haben standardmäßig den Wert 8. Lane-Starts werden standardmäßig um 2 Sekunden versetzt, um lokale Docker-Daemon-Erstellungsstürme zu vermeiden; überschreiben Sie dies mit `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Der Runner plant nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein, sofern nicht `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` gesetzt ist, und jede Lane hat ein Timeout von 120 Minuten, das mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` überschrieben werden kann. Logs pro Lane werden unter `.artifacts/docker-tests/<run-id>/` geschrieben.
- `pnpm test:docker:openwebui`: Startet Dockerisiertes OpenClaw + Open WebUI, meldet sich über Open WebUI an, prüft `/api/models` und führt dann einen echten proxied Chat über `/api/chat/completions` aus. Erfordert einen nutzbaren Live-Modell-Key (zum Beispiel OpenAI in `~/.profile`), zieht ein externes Open-WebUI-Image und ist nicht dafür gedacht, so CI-stabil zu sein wie die normalen Unit-/E2E-Suites.
- `pnpm test:docker:mcp-channels`: Startet einen vorbefüllten Gateway-Container und einen zweiten Client-Container, der `openclaw mcp serve` startet, und prüft dann die geroutete Conversation-Erkennung, Transcript-Lesevorgänge, Attachment-Metadaten, Verhalten der Live-Event-Queue, Outbound-Send-Routing sowie Channel- und Berechtigungsbenachrichtigungen im Claude-Stil über die echte stdio-Bridge. Die Claude-Benachrichtigungs-Assertion liest die rohen stdio-MCP-Frames direkt, sodass der Smoke das widerspiegelt, was die Bridge tatsächlich ausgibt.
## Lokales PR-Gate
## Lokale PR-Prüfung
Für lokale PR-Land-/Gate-Prüfungen führen Sie aus:
Führen Sie für lokale PR-Land-/Gate-Prüfungen Folgendes aus:
- `pnpm check:changed`
- `pnpm check`
@ -54,27 +54,27 @@ Für lokale PR-Land-/Gate-Prüfungen führen Sie aus:
- `pnpm test`
- `pnpm check:docs`
Wenn `pnpm test` auf einem stark belasteten Host flaky ist, führen Sie es einmal erneut aus, bevor Sie es als Regression behandeln, und isolieren Sie dann mit `pnpm test <path/to/test>`. Für Hosts mit wenig Arbeitsspeicher verwenden Sie:
Wenn `pnpm test` auf einem stark ausgelasteten Host flakey ist, führen Sie es einmal erneut aus, bevor Sie es als Regression behandeln, und isolieren Sie es dann mit `pnpm test <path/to/test>`. Verwenden Sie für Hosts mit wenig Speicher:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Benchmark für Modelllatenz (lokale Schlüssel)
## Modell-Latenz-Benchmark (lokale Keys)
Skript: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
Verwendung:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Optionale Env-Variablen: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Standard-Prompt: “Reply with a single word: ok. No punctuation or extra text.”
- Optionale env-Variablen: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Standard-Prompt: „Reply with a single word: ok. No punctuation or extra text.“
Letzter Lauf (2025-12-31, 20 Läufe):
- minimax median 1279ms (min 1114, max 2431)
- opus median 2454ms (min 1224, max 3170)
## Benchmark für CLI-Startzeit
## CLI-Startup-Benchmark
Skript: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -95,41 +95,41 @@ Verwendung:
- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
- `pnpm tsx scripts/bench-cli-startup.ts --json`
Presets:
Vorgaben:
- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: beide Presets
- `all`: beide Vorgaben
Die Ausgabe enthält `sampleCount`, Durchschnitt, p50, p95, min/max, Verteilung von Exit-Code/Signal und Zusammenfassungen des maximalen RSS für jeden Befehl. Optionale `--cpu-prof-dir` / `--heap-prof-dir` schreiben V8-Profile pro Lauf, sodass Timing und Profilerfassung dasselbe Harness verwenden.
Die Ausgabe enthält `sampleCount`, avg, p50, p95, min/max, Verteilung von Exit-Code/Signal und Zusammenfassungen des maximalen RSS für jeden Befehl. Optionales `--cpu-prof-dir` / `--heap-prof-dir` schreibt V8-Profile pro Lauf, sodass Timing und Profilerfassung dasselbe Harness verwenden.
Konventionen für gespeicherte Ausgaben:
- `pnpm test:startup:bench:smoke` schreibt das gezielte Smoke-Artefakt nach `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` schreibt das Full-Suite-Artefakt nach `.artifacts/cli-startup-bench-all.json` mit `runs=5` und `warmup=1`
- `pnpm test:startup:bench:update` aktualisiert die eingecheckte Baseline-Fixture unter `test/fixtures/cli-startup-bench.json` mit `runs=5` und `warmup=1`
- `pnpm test:startup:bench:save` schreibt das Artefakt der vollständigen Suite nach `.artifacts/cli-startup-bench-all.json` mit `runs=5` und `warmup=1`
- `pnpm test:startup:bench:update` aktualisiert das eingecheckte Baseline-Fixture unter `test/fixtures/cli-startup-bench.json` mit `runs=5` und `warmup=1`
Eingecheckte Fixture:
Eingechecktes Fixture:
- `test/fixtures/cli-startup-bench.json`
- Aktualisieren mit `pnpm test:startup:bench:update`
- Aktuelle Ergebnisse mit der Fixture vergleichen mit `pnpm test:startup:bench:check`
- Aktuelle Ergebnisse mit dem Fixture vergleichen mit `pnpm test:startup:bench:check`
## Onboarding E2E (Docker)
## Onboarding-E2E (Docker)
Docker ist optional; dies wird nur für containerisierte Onboarding-Smoke-Tests benötigt.
Vollständiger Cold-Start-Ablauf in einem sauberen Linux-Container:
Vollständiger Cold-Start-Flow in einem sauberen Linux-Container:
```bash
scripts/e2e/onboard-docker.sh
```
Dieses Skript steuert den interaktiven Assistenten über ein Pseudo-TTY, prüft Konfigurations-/Workspace-/Sitzungsdateien, startet dann das Gateway und führt `openclaw health` aus.
Dieses Skript steuert den interaktiven Wizard über ein Pseudo-TTY, prüft Konfigurations-/Workspace-/Session-Dateien, startet dann das Gateway und führt `openclaw health` aus.
## QR-Import-Smoke (Docker)
## Smoke für QR-Import (Docker)
Stellt sicher, dass der gepflegte QR-Runtime-Helfer unter den unterstützten Docker-Node-Laufzeiten lädt (Node 24 Standard, Node 22 kompatibel):
Stellt sicher, dass der gepflegte QR-Laufzeit-Helper unter den unterstützten Docker-Node-Laufzeiten geladen wird (Node 24 standardmäßig, Node 22 kompatibel):
```bash
pnpm test:docker:qr

341
docs/de/tools/browser.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Agentengesteuerte Browser-Automatisierung hinzufügen.
- Debuggen, warum OpenClaw Ihr eigenes Chrome stört
- Browsereinstellungen + Lifecycle in der macOS-App implementieren.
summary: Integrierter Browser-Control-Service + Action-Befehle
title: Browser (OpenClaw-verwaltet)
- Hinzufügen von agentgesteuerter Browser-Automatisierung
- Debuggen, warum openclaw Ihren eigenen Chrome beeinträchtigt
- Implementierung von Browser-Einstellungen + Lebenszyklus in der macOS-App
summary: Integrierter Browser-Control-Service + Aktionsbefehle
title: Browser (von OpenClaw verwaltet)
x-i18n:
generated_at: "2026-04-24T07:01:59Z"
generated_at: "2026-04-24T09:01:20Z"
model: gpt-5.4
provider: openai
source_hash: 2fb0fc0b6235fa8a0324b754e247e015d5ca19d114d324d565ed4a19f9313f7e
source_hash: 80805676213ef5195093163874a848955b3c25364b20045a8d759d03ac088e14
source_path: tools/browser.md
workflow: 15
---
@ -18,21 +18,21 @@ OpenClaw kann ein **dediziertes Chrome-/Brave-/Edge-/Chromium-Profil** ausführe
Es ist von Ihrem persönlichen Browser isoliert und wird über einen kleinen lokalen
Control-Service innerhalb des Gateway verwaltet (nur loopback).
Einfach erklärt:
Ansicht für Einsteiger:
- Stellen Sie es sich als **separaten Browser nur für den Agenten** vor.
- Das Profil `openclaw` berührt **nicht** Ihr persönliches Browser-Profil.
- Der Agent kann **Tabs öffnen, Seiten lesen, klicken und tippen** in einer sicheren Spur.
- Das eingebaute Profil `user` hängt sich über Chrome MCP an Ihre echte eingeloggte Chrome-Sitzung an.
- Betrachten Sie es als einen **separaten Browser nur für den Agenten**.
- Das Profil `openclaw` greift **nicht** auf Ihr persönliches Browser-Profil zu.
- Der Agent kann in einer sicheren Spur **Tabs öffnen, Seiten lesen, klicken und tippen**.
- Das integrierte Profil `user` bindet über Chrome MCP an Ihre echte angemeldete Chrome-Sitzung an.
## Was Sie bekommen
## Was Sie erhalten
- Ein separates Browser-Profil namens **openclaw** (standardmäßig mit orangem Akzent).
- Deterministische Tab-Steuerung (auflisten/öffnen/fokussieren/schließen).
- Agent-Aktionen (klicken/tippen/ziehen/auswählen), Snapshots, Screenshots, PDFs.
- Optionale Unterstützung für mehrere Profile (`openclaw`, `work`, `remote`, ...).
- Optionale Unterstützung mehrerer Profile (`openclaw`, `work`, `remote`, ...).
Dieser Browser ist **nicht** Ihr Daily Driver. Er ist eine sichere, isolierte Oberfläche für
Dieser Browser ist **nicht** Ihr täglicher Hauptbrowser. Er ist eine sichere, isolierte Oberfläche für
Agent-Automatisierung und Verifikation.
## Schnellstart
@ -48,7 +48,7 @@ Wenn Sie „Browser disabled“ erhalten, aktivieren Sie ihn in der Konfiguratio
Gateway neu.
Wenn `openclaw browser` vollständig fehlt oder der Agent sagt, dass das Browser-Tool
nicht verfügbar ist, springen Sie zu [Missing browser command or tool](/de/tools/browser#missing-browser-command-or-tool).
nicht verfügbar ist, springen Sie zu [Fehlender Browser-Befehl oder fehlendes Tool](/de/tools/browser#missing-browser-command-or-tool).
## Plugin-Steuerung
@ -66,9 +66,9 @@ Das Standard-Tool `browser` ist ein gebündeltes Plugin. Deaktivieren Sie es, um
}
```
Standardeinstellungen benötigen sowohl `plugins.entries.browser.enabled` **als auch** `browser.enabled=true`. Wenn Sie nur das Plugin deaktivieren, verschwinden `openclaw browser` CLI, die Gateway-Methode `browser.request`, das Agent-Tool und der Control-Service als Einheit; Ihre `browser.*`-Konfiguration bleibt für einen Ersatz intakt.
Die Standardwerte benötigen sowohl `plugins.entries.browser.enabled` **als auch** `browser.enabled=true`. Wenn Sie nur das Plugin deaktivieren, werden die CLI `openclaw browser`, die Gateway-Methode `browser.request`, das Agent-Tool und der Control-Service als Einheit entfernt; Ihre `browser.*`-Konfiguration bleibt für einen Ersatz erhalten.
Änderungen an der Browser-Konfiguration erfordern einen Neustart des Gateway, damit das Plugin seinen Service neu registrieren kann.
Änderungen an der Browser-Konfiguration erfordern einen Gateway-Neustart, damit das Plugin seinen Service erneut registrieren kann.
## Fehlender Browser-Befehl oder fehlendes Tool
@ -82,40 +82,40 @@ Wenn `openclaw browser` nach einem Upgrade unbekannt ist, `browser.request` fehl
}
```
`browser.enabled=true`, `plugins.entries.browser.enabled=true` und `tools.alsoAllow: ["browser"]` ersetzen die Mitgliedschaft in der Allowlist nicht — die Allowlist steuert das Laden von Plugins, und die Tool-Richtlinie greift erst nach dem Laden. Das vollständige Entfernen von `plugins.allow` stellt ebenfalls das Standardverhalten wieder her.
`browser.enabled=true`, `plugins.entries.browser.enabled=true` und `tools.alsoAllow: ["browser"]` ersetzen die Allowlist-Mitgliedschaft nicht — die Allowlist steuert das Laden von Plugins, und die Tool-Richtlinie greift erst nach dem Laden. Das vollständige Entfernen von `plugins.allow` stellt ebenfalls den Standard wieder her.
## Profile: `openclaw` vs `user`
- `openclaw`: verwalteter, isolierter Browser (keine Extension erforderlich).
- `user`: eingebautes Chrome-MCP-Attach-Profil für Ihre **echte eingeloggte Chrome**-
- `openclaw`: verwalteter, isolierter Browser (keine Erweiterung erforderlich).
- `user`: integriertes Chrome-MCP-Anbindungsprofil für Ihre **echte angemeldete Chrome-**
Sitzung.
Für Browser-Tool-Aufrufe des Agenten:
- Standard: den isolierten Browser `openclaw` verwenden.
- `profile="user"` bevorzugen, wenn bestehende eingeloggte Sitzungen wichtig sind und der Benutzer
am Rechner sitzt, um auf ein mögliches Attach-Prompt zu klicken/zuzustimmen.
- `profile` ist die explizite Überschreibung, wenn Sie einen bestimmten Browser-Modus möchten.
- Standard: Verwenden Sie den isolierten Browser `openclaw`.
- Bevorzugen Sie `profile="user"`, wenn bestehende angemeldete Sitzungen wichtig sind und der Benutzer
am Computer sitzt, um eine eventuelle Anbindungsabfrage zu klicken/zu bestätigen.
- `profile` ist der explizite Override, wenn Sie einen bestimmten Browser-Modus möchten.
Setzen Sie `browser.defaultProfile: "openclaw"`, wenn Sie den verwalteten Modus standardmäßig möchten.
Setzen Sie `browser.defaultProfile: "openclaw"`, wenn Sie den verwalteten Modus standardmäßig verwenden möchten.
## Konfiguration
Browser-Einstellungen liegen in `~/.openclaw/openclaw.json`.
Die Browser-Einstellungen befinden sich in `~/.openclaw/openclaw.json`.
```json5
{
browser: {
enabled: true, // Standard: true
ssrfPolicy: {
// dangerouslyAllowPrivateNetwork: true, // nur bewusst für vertrauenswürdigen Zugriff auf private Netzwerke aktivieren
// dangerouslyAllowPrivateNetwork: true, // nur für vertrauenswürdigen Zugriff auf private Netzwerke aktivieren
// allowPrivateNetwork: true, // Legacy-Alias
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
// cdpUrl: "http://127.0.0.1:18792", // alte Single-Profile-Überschreibung
// cdpUrl: "http://127.0.0.1:18792", // Legacy-Override für ein einzelnes Profil
remoteCdpTimeoutMs: 1500, // Remote-CDP-HTTP-Timeout (ms)
remoteCdpHandshakeTimeoutMs: 3000, // Remote-CDP-WebSocket-Handshake-Timeout (ms)
remoteCdpHandshakeTimeoutMs: 3000, // Timeout für Remote-CDP-WebSocket-Handshake (ms)
defaultProfile: "openclaw",
color: "#FF4500",
headless: false,
@ -146,29 +146,29 @@ Browser-Einstellungen liegen in `~/.openclaw/openclaw.json`.
<Accordion title="Ports und Erreichbarkeit">
- Der Control-Service bindet an loopback auf einem Port, der aus `gateway.port` abgeleitet wird (Standard `18791` = gateway + 2). Wenn `gateway.port` oder `OPENCLAW_GATEWAY_PORT` überschrieben wird, verschieben sich die abgeleiteten Ports derselben Familie entsprechend.
- Lokale `openclaw`-Profile weisen `cdpPort`/`cdpUrl` automatisch zu; setzen Sie diese nur für Remote-CDP. `cdpUrl` verwendet standardmäßig den verwalteten lokalen CDP-Port, wenn nicht gesetzt.
- `remoteCdpTimeoutMs` gilt für HTTP-Erreichbarkeitsprüfungen bei Remote-CDP (nicht-loopback); `remoteCdpHandshakeTimeoutMs` gilt für WebSocket-Handshakes bei Remote-CDP.
- Der Control-Service bindet an loopback auf einem Port, der von `gateway.port` abgeleitet wird (Standard `18791` = Gateway + 2). Wenn `gateway.port` oder `OPENCLAW_GATEWAY_PORT` überschrieben wird, verschieben sich die abgeleiteten Ports in derselben Familie.
- Lokale `openclaw`-Profile weisen `cdpPort`/`cdpUrl` automatisch zu; setzen Sie diese nur für Remote-CDP. `cdpUrl` verwendet standardmäßig den verwalteten lokalen CDP-Port, wenn er nicht gesetzt ist.
- `remoteCdpTimeoutMs` gilt für HTTP-Erreichbarkeitsprüfungen von Remote-CDP (nicht-loopback); `remoteCdpHandshakeTimeoutMs` gilt für WebSocket-Handshakes von Remote-CDP.
</Accordion>
<Accordion title="SSRF-Richtlinie">
- Browser-Navigation und Öffnen von Tabs werden vor der Navigation durch SSRF-Gates geschützt und anschließend best-effort erneut anhand der finalen `http(s)`-URL geprüft.
- Im strikten SSRF-Modus werden auch Discovery von Remote-CDP-Endpunkten und Probes auf `/json/version` (`cdpUrl`) geprüft.
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` ist standardmäßig deaktiviert; aktivieren Sie es nur, wenn Browser-Zugriff auf private Netzwerke bewusst als vertrauenswürdig gilt.
- `browser.ssrfPolicy.allowPrivateNetwork` bleibt als Legacy-Alias unterstützt.
- Browser-Navigation und Open-Tab werden vor der Navigation durch SSRF geschützt und danach nach bestem Bemühen erneut gegen die endgültige `http(s)`-URL geprüft.
- Im strikten SSRF-Modus werden auch Remote-CDP-Endpunkterkennung und `/json/version`-Abfragen (`cdpUrl`) geprüft.
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` ist standardmäßig deaktiviert; aktivieren Sie es nur, wenn Browser-Zugriff auf private Netzwerke absichtlich vertrauenswürdig ist.
- `browser.ssrfPolicy.allowPrivateNetwork` wird weiterhin als Legacy-Alias unterstützt.
</Accordion>
<Accordion title="Profilverhalten">
- `attachOnly: true` bedeutet, niemals einen lokalen Browser zu starten; nur anhängen, wenn bereits einer läuft.
- `color` (Top-Level und pro Profil) färbt die Browser-UI ein, damit Sie sehen können, welches Profil aktiv ist.
- Standardprofil ist `openclaw` (verwaltete Standalone-Variante). Verwenden Sie `defaultProfile: "user"`, um standardmäßig den eingeloggten Benutzer-Browser zu verwenden.
- Reihenfolge der Auto-Erkennung: Standardbrowser des Systems, wenn Chromium-basiert; andernfalls Chrome → Brave → Edge → Chromium → Chrome Canary.
- `driver: "existing-session"` verwendet Chrome DevTools MCP statt rohem CDP. Setzen Sie für diesen Treiber kein `cdpUrl`.
- Setzen Sie `browser.profiles.<name>.userDataDir`, wenn ein Profil mit `existing-session` an ein nicht standardmäßiges Chromium-Benutzerprofil (Brave, Edge usw.) angehängt werden soll.
- `attachOnly: true` bedeutet, dass niemals ein lokaler Browser gestartet wird; es wird nur angebunden, wenn bereits einer läuft.
- `color` (auf oberster Ebene und pro Profil) färbt die Browser-Oberfläche ein, sodass Sie sehen können, welches Profil aktiv ist.
- Das Standardprofil ist `openclaw` (verwalteter eigenständiger Browser). Verwenden Sie `defaultProfile: "user"`, um sich standardmäßig für den angemeldeten Benutzerbrowser zu entscheiden.
- Reihenfolge für Auto-Erkennung: Standardbrowser des Systems, wenn Chromium-basiert; andernfalls Chrome → Brave → Edge → Chromium → Chrome Canary.
- `driver: "existing-session"` verwendet Chrome DevTools MCP statt rohem CDP. Setzen Sie für diesen Treiber nicht `cdpUrl`.
- Setzen Sie `browser.profiles.<name>.userDataDir`, wenn ein existing-session-Profil an ein nicht standardmäßiges Chromium-Benutzerprofil (Brave, Edge usw.) angebunden werden soll.
</Accordion>
@ -176,7 +176,7 @@ Browser-Einstellungen liegen in `~/.openclaw/openclaw.json`.
## Brave verwenden (oder einen anderen Chromium-basierten Browser)
Wenn Ihr **Standardbrowser des Systems** Chromium-basiert ist (Chrome/Brave/Edge/etc),
Wenn Ihr **Standardbrowser des Systems** Chromium-basiert ist (Chrome/Brave/Edge/etc.),
verwendet OpenClaw ihn automatisch. Setzen Sie `browser.executablePath`, um die
Auto-Erkennung zu überschreiben:
@ -184,7 +184,7 @@ Auto-Erkennung zu überschreiben:
openclaw config set browser.executablePath "/usr/bin/google-chrome"
```
Oder setzen Sie es in der Konfiguration, je Plattform:
Oder setzen Sie es in der Konfiguration, je nach Plattform:
<Tabs>
<Tab title="macOS">
@ -219,40 +219,40 @@ Oder setzen Sie es in der Konfiguration, je Plattform:
## Lokale vs. Remote-Steuerung
- **Lokale Steuerung (Standard):** Das Gateway startet den loopback-Control-Service und kann einen lokalen Browser starten.
- **Remote-Steuerung (Node-Host):** Führen Sie einen Node-Host auf der Maschine aus, die den Browser hat; das Gateway proxyt Browser-Aktionen dorthin.
- **Remote-Steuerung (Node-Host):** Führen Sie einen Node-Host auf der Maschine aus, auf der sich der Browser befindet; das Gateway leitet Browser-Aktionen per Proxy dorthin weiter.
- **Remote-CDP:** Setzen Sie `browser.profiles.<name>.cdpUrl` (oder `browser.cdpUrl`), um
sich an einen entfernten Chromium-basierten Browser anzuhängen. In diesem Fall startet OpenClaw keinen lokalen Browser.
eine Verbindung zu einem Remote-Chromium-basierten Browser herzustellen. In diesem Fall startet OpenClaw keinen lokalen Browser.
Das Verhalten beim Stoppen unterscheidet sich je nach Profilmodus:
Das Stop-Verhalten unterscheidet sich je nach Profilmodus:
- lokal verwaltete Profile: `openclaw browser stop` stoppt den Browser-Prozess, den
OpenClaw gestartet hat
- Attach-only- und Remote-CDP-Profile: `openclaw browser stop` schließt die aktive
Control-Sitzung und gibt Emulations-Overrides von Playwright/CDP frei (Viewport,
Farbschema, Locale, Zeitzone, Offline-Modus und ähnlichen Zustand), auch
Control-Sitzung und hebt Playwright-/CDP-Emulations-Overrides auf (Viewport,
Farbschema, Gebietsschema, Zeitzone, Offline-Modus und ähnlicher Status), auch
wenn kein Browser-Prozess von OpenClaw gestartet wurde
Remote-CDP-URLs können Auth enthalten:
- Query-Tokens (z. B. `https://provider.example?token=<token>`)
- HTTP Basic auth (z. B. `https://user:pass@provider.example`)
- Query-Token (z. B. `https://provider.example?token=<token>`)
- HTTP-Basic-Auth (z. B. `https://user:pass@provider.example`)
OpenClaw behält die Auth bei Aufrufen von Endpunkten `/json/*` und bei der Verbindung
zum CDP-WebSocket bei. Bevorzugen Sie Umgebungsvariablen oder Secrets-Manager für
Tokens, statt sie in Konfigurationsdateien zu committen.
OpenClaw bewahrt die Auth beim Aufruf von `/json/*`-Endpunkten und beim Verbinden
mit dem CDP-WebSocket. Bevorzugen Sie Umgebungsvariablen oder Secret-Manager für
Token, statt sie in Konfigurationsdateien zu committen.
## Browser-Proxy für Nodes (Zero-Config-Standard)
## Node-Browser-Proxy (standardmäßig ohne Konfiguration)
Wenn Sie einen **Node-Host** auf der Maschine ausführen, die Ihren Browser hat, kann OpenClaw
Browser-Tool-Aufrufe ohne zusätzliche Browser-Konfiguration automatisch an diesen Node routen.
Wenn Sie einen **Node-Host** auf der Maschine ausführen, auf der sich Ihr Browser befindet, kann OpenClaw
Browser-Tool-Aufrufe automatisch an diesen Node weiterleiten, ohne zusätzliche Browser-Konfiguration.
Dies ist der Standardpfad für Remote-Gateways.
Hinweise:
- Der Node-Host stellt seinen lokalen Browser-Control-Server über einen **Proxy-Befehl** bereit.
- Profile kommen aus der eigenen `browser.profiles`-Konfiguration des Node (wie lokal).
- `nodeHost.browserProxy.allowProfiles` ist optional. Lassen Sie es leer für das alte/Standardverhalten: Alle konfigurierten Profile bleiben über den Proxy erreichbar, einschließlich Routen zum Erstellen/Löschen von Profilen.
- Wenn Sie `nodeHost.browserProxy.allowProfiles` setzen, behandelt OpenClaw dies als Least-Privilege-Grenze: Nur Profile auf der Allowlist können angesprochen werden, und dauerhafte Routen zum Erstellen/Löschen von Profilen werden auf der Proxy-Oberfläche blockiert.
- Profile stammen aus der eigenen `browser.profiles`-Konfiguration des Node (wie lokal).
- `nodeHost.browserProxy.allowProfiles` ist optional. Lassen Sie es leer für das Legacy-/Standardverhalten: Alle konfigurierten Profile bleiben über den Proxy erreichbar, einschließlich Routen zum Erstellen/Löschen von Profilen.
- Wenn Sie `nodeHost.browserProxy.allowProfiles` setzen, behandelt OpenClaw dies als Least-Privilege-Grenze: Nur Profile in der Allowlist können angesprochen werden, und Routen zum Erstellen/Löschen persistenter Profile werden auf der Proxy-Oberfläche blockiert.
- Deaktivieren Sie es, wenn Sie es nicht möchten:
- Auf dem Node: `nodeHost.browserProxy.enabled=false`
- Auf dem Gateway: `gateway.nodes.browser.mode="off"`
@ -261,7 +261,7 @@ Hinweise:
[Browserless](https://browserless.io) ist ein gehosteter Chromium-Service, der
CDP-Verbindungs-URLs über HTTPS und WebSocket bereitstellt. OpenClaw kann beide Formen verwenden, aber
für ein Remote-Browserprofil ist die einfachste Option die direkte WebSocket-URL
für ein Remote-Browser-Profil ist die einfachste Option die direkte WebSocket-URL
aus der Verbindungsdokumentation von Browserless.
Beispiel:
@ -287,30 +287,30 @@ Hinweise:
- Ersetzen Sie `<BROWSERLESS_API_KEY>` durch Ihr echtes Browserless-Token.
- Wählen Sie den Regionsendpunkt, der zu Ihrem Browserless-Konto passt (siehe deren Dokumentation).
- Wenn Browserless Ihnen eine HTTPS-Base-URL gibt, können Sie sie entweder zu
- Wenn Browserless Ihnen eine HTTPS-Basis-URL gibt, können Sie sie entweder in
`wss://` für eine direkte CDP-Verbindung umwandeln oder die HTTPS-URL beibehalten und OpenClaw
`/json/version` erkennen lassen.
## Direkte WebSocket-CDP-Provider
## Direkte WebSocket-CDP-Anbieter
Einige gehostete Browser-Dienste stellen einen **direkten WebSocket**-Endpunkt bereit statt
der standardmäßigen HTTP-basierten CDP-Discovery (`/json/version`). OpenClaw akzeptiert drei
CDP-URL-Formen und wählt die richtige Verbindungsstrategie automatisch:
Einige gehostete Browser-Services stellen einen **direkten WebSocket**-Endpunkt statt
der standardmäßigen HTTP-basierten CDP-Erkennung (`/json/version`) bereit. OpenClaw akzeptiert drei
Formen von CDP-URLs und wählt automatisch die richtige Verbindungsstrategie:
- **HTTP(S)-Discovery** — `http://host[:port]` oder `https://host[:port]`.
- **HTTP(S)-Erkennung** — `http://host[:port]` oder `https://host[:port]`.
OpenClaw ruft `/json/version` auf, um die WebSocket-Debugger-URL zu erkennen, und
verbindet sich dann. Kein WebSocket-Fallback.
- **Direkte WebSocket-Endpunkte** — `ws://host[:port]/devtools/<kind>/<id>` oder
`wss://...` mit einem Pfad `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
OpenClaw verbindet sich direkt über einen WebSocket-Handshake und überspringt
OpenClaw verbindet sich direkt per WebSocket-Handshake und überspringt
`/json/version` vollständig.
- **Bare WebSocket roots** — `ws://host[:port]` oder `wss://host[:port]` ohne
- **Bloße WebSocket-Roots** — `ws://host[:port]` oder `wss://host[:port]` ohne
`/devtools/...`-Pfad (z. B. [Browserless](https://browserless.io),
[Browserbase](https://www.browserbase.com)). OpenClaw versucht zuerst HTTP-
Discovery über `/json/version` (normalisiert das Schema zu `http`/`https`);
wenn die Discovery ein `webSocketDebuggerUrl` zurückgibt, wird diese verwendet, andernfalls fällt OpenClaw
auf einen direkten WebSocket-Handshake am nackten Root zurück. Dadurch kann ein
nacktes `ws://`, das auf lokales Chrome zeigt, trotzdem verbinden, da Chrome WebSocket-Upgrades nur auf dem spezifischen Pfad pro Ziel aus
[Browserbase](https://www.browserbase.com)). OpenClaw versucht zuerst eine HTTP-
`/json/version`-Erkennung (wobei das Schema auf `http`/`https` normalisiert wird);
wenn die Erkennung eine `webSocketDebuggerUrl` zurückgibt, wird diese verwendet, andernfalls greift OpenClaw
auf einen direkten WebSocket-Handshake an der bloßen Root zurück. Dadurch kann ein
bloßes `ws://`, das auf einen lokalen Chrome zeigt, weiterhin verbinden, da Chrome WebSocket-Upgrades nur auf dem spezifischen Pfad pro Ziel aus
`/json/version` akzeptiert.
### Browserbase
@ -338,78 +338,77 @@ Proxies.
Hinweise:
- [Registrieren](https://www.browserbase.com/sign-up) und Ihren **API Key**
aus dem [Overview-Dashboard](https://www.browserbase.com/overview) kopieren.
- Ersetzen Sie `<BROWSERBASE_API_KEY>` durch Ihren echten Browserbase-API-Key.
- Browserbase erstellt beim WebSocket-Connect automatisch eine Browser-Sitzung, daher ist
kein manueller Schritt zum Erstellen einer Sitzung erforderlich.
- Das kostenlose Tier erlaubt eine gleichzeitige Sitzung und eine Browser-Stunde pro Monat.
Siehe [pricing](https://www.browserbase.com/pricing) für Limits kostenpflichtiger Pläne.
- [Registrieren Sie sich](https://www.browserbase.com/sign-up) und kopieren Sie Ihren **API Key**
aus dem [Overview-Dashboard](https://www.browserbase.com/overview).
- Ersetzen Sie `<BROWSERBASE_API_KEY>` durch Ihren echten Browserbase-API-Schlüssel.
- Browserbase erstellt beim WebSocket-Verbindungsaufbau automatisch eine Browser-Session, daher ist
kein manueller Schritt zur Session-Erstellung erforderlich.
- Die kostenlose Stufe erlaubt eine gleichzeitige Session und eine Browser-Stunde pro Monat.
Siehe [Preise](https://www.browserbase.com/pricing) für Limits der kostenpflichtigen Tarife.
- Siehe die [Browserbase-Dokumentation](https://docs.browserbase.com) für die vollständige API-
Referenz, SDK-Anleitungen und Integrationsbeispiele.
## Sicherheit
Wichtige Grundideen:
Wichtige Ideen:
- Browser-Steuerung ist nur über loopback erreichbar; der Zugriff läuft über die Authentifizierung des Gateway oder über Node-Pairing.
- Browser-Steuerung ist nur über loopback erreichbar; der Zugriff läuft über die Authentifizierung des Gateway oder Node-Pairing.
- Die eigenständige loopback-Browser-HTTP-API verwendet **nur Shared-Secret-Authentifizierung**:
Gateway-Token-Bearer-Auth, `x-openclaw-password` oder HTTP Basic Auth mit dem
Gateway-Token-Bearer-Authentifizierung, `x-openclaw-password` oder HTTP-Basic-Auth mit dem
konfigurierten Gateway-Passwort.
- Tailscale-Serve-Identitäts-Header und `gateway.auth.mode: "trusted-proxy"` authentifizieren
diese eigenständige loopback-Browser-API **nicht**.
- Tailscale-Serve-Identitäts-Header und `gateway.auth.mode: "trusted-proxy"` authentifizieren diese eigenständige loopback-Browser-API **nicht**.
- Wenn Browser-Steuerung aktiviert ist und keine Shared-Secret-Authentifizierung konfiguriert ist, erzeugt OpenClaw
beim Start automatisch `gateway.auth.token` und persistiert es in der Konfiguration.
beim Start automatisch `gateway.auth.token` und speichert es in der Konfiguration.
- OpenClaw erzeugt dieses Token **nicht** automatisch, wenn `gateway.auth.mode` bereits
`password`, `none` oder `trusted-proxy` ist.
- Halten Sie das Gateway und alle Node-Hosts in einem privaten Netzwerk (Tailscale); vermeiden Sie öffentliche Exposition.
- Behandeln Sie Remote-CDP-URLs/-Tokens als Secrets; bevorzugen Sie Env-Variablen oder einen Secrets-Manager.
- Halten Sie das Gateway und alle Node-Hosts in einem privaten Netzwerk (Tailscale); vermeiden Sie öffentliche Exponierung.
- Behandeln Sie Remote-CDP-URLs/-Tokens als Geheimnisse; bevorzugen Sie Env-Variablen oder einen Secret-Manager.
Tipps für Remote-CDP:
Tipps zu Remote-CDP:
- Bevorzugen Sie verschlüsselte Endpunkte (HTTPS oder WSS) und nach Möglichkeit kurzlebige Tokens.
- Vermeiden Sie es, langlebige Tokens direkt in Konfigurationsdateien einzubetten.
## Profile (mehrere Browser)
## Profile (Multi-Browser)
OpenClaw unterstützt mehrere benannte Profile (Routing-Konfigurationen). Profile können sein:
- **openclaw-managed**: eine dedizierte Chromium-basierte Browser-Instanz mit eigenem User-Data-Directory + CDP-Port
- **remote**: eine explizite CDP-URL (Chromium-basierter Browser, der anderswo läuft)
- **existing session**: Ihr bestehendes Chrome-Profil über Chrome DevTools MCP Auto-Connect
- **von OpenClaw verwaltet**: eine dedizierte Chromium-basierte Browser-Instanz mit eigenem User-Data-Verzeichnis + CDP-Port
- **remote**: eine explizite CDP-URL (Chromium-basierter Browser läuft anderswo)
- **bestehende Session**: Ihr bestehendes Chrome-Profil über automatisches Verbinden mit Chrome DevTools MCP
Standards:
Standardwerte:
- Das Profil `openclaw` wird automatisch erstellt, falls es fehlt.
- Das Profil `user` ist eingebaut für das Anhängen an eine bestehende Sitzung über Chrome MCP.
- Existing-Session-Profile sind jenseits von `user` Opt-in; erstellen Sie sie mit `--driver existing-session`.
- Das Profil `openclaw` wird automatisch erstellt, wenn es fehlt.
- Das Profil `user` ist für die Anbindung bestehender Sessions über Chrome MCP integriert.
- Existing-session-Profile sind zusätzlich zu `user` Opt-in; erstellen Sie sie mit `--driver existing-session`.
- Lokale CDP-Ports werden standardmäßig aus **18800–18899** zugewiesen.
- Beim Löschen eines Profils wird sein lokales Datenverzeichnis in den Papierkorb verschoben.
- Das Löschen eines Profils verschiebt sein lokales Datenverzeichnis in den Papierkorb.
Alle Control-Endpunkte akzeptieren `?profile=<name>`; die CLI verwendet `--browser-profile`.
## Existing-session über Chrome DevTools MCP
OpenClaw kann sich auch über den
offiziellen Chrome DevTools MCP-Server an ein laufendes Chromium-basiertes Browser-Profil anhängen. Dadurch werden die in diesem Browser-Profil bereits
offenen Tabs und Login-Zustände wiederverwendet.
OpenClaw kann auch an ein laufendes Chromium-basiertes Browser-Profil über den
offiziellen Chrome-DevTools-MCP-Server anbinden. Dadurch werden die Tabs und der Login-Status
wiederverwendet, die bereits in diesem Browser-Profil geöffnet sind.
Offizieller Hintergrund und Referenzen zur Einrichtung:
Offizielle Hintergründe und Setup-Referenzen:
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
Eingebautes Profil:
Integriertes Profil:
- `user`
Optional: Erstellen Sie Ihr eigenes benutzerdefiniertes Existing-Session-Profil, wenn Sie einen
Optional: Erstellen Sie Ihr eigenes benutzerdefiniertes Existing-session-Profil, wenn Sie einen
anderen Namen, eine andere Farbe oder ein anderes Browser-Datenverzeichnis möchten.
Standardverhalten:
- Das eingebaute Profil `user` verwendet Chrome-MCP-Auto-Connect, das auf das
lokale Standardprofil von Google Chrome zielt.
- Das integrierte Profil `user` verwendet automatisches Verbinden per Chrome MCP und zielt auf das
lokale Standardprofil von Google Chrome.
Verwenden Sie `userDataDir` für Brave, Edge, Chromium oder ein nicht standardmäßiges Chrome-Profil:
@ -430,17 +429,17 @@ Verwenden Sie `userDataDir` für Brave, Edge, Chromium oder ein nicht standardm
Dann im passenden Browser:
1. Öffnen Sie die Inspect-Seite dieses Browsers für Remote-Debugging.
1. Öffnen Sie die Inspektionsseite dieses Browsers für Remote-Debugging.
2. Aktivieren Sie Remote-Debugging.
3. Lassen Sie den Browser laufen und bestätigen Sie das Verbindungs-Prompt, wenn OpenClaw sich anhängt.
3. Lassen Sie den Browser weiterlaufen und genehmigen Sie die Verbindungsabfrage, wenn OpenClaw anbindet.
Häufige Inspect-Seiten:
Häufige Inspektionsseiten:
- Chrome: `chrome://inspect/#remote-debugging`
- Brave: `brave://inspect/#remote-debugging`
- Edge: `edge://inspect/#remote-debugging`
Live-Attach-Smoke-Test:
Live-Anbindungs-Smoke-Test:
```bash
openclaw browser --browser-profile user start
@ -457,54 +456,54 @@ So sieht Erfolg aus:
- `tabs` listet Ihre bereits geöffneten Browser-Tabs auf
- `snapshot` gibt Refs aus dem ausgewählten Live-Tab zurück
Was Sie prüfen sollten, wenn das Anhängen nicht funktioniert:
Was Sie prüfen sollten, wenn die Anbindung nicht funktioniert:
- der Zielbrowser auf Chromium-Basis ist Version `144+`
- Remote-Debugging ist auf der Inspect-Seite dieses Browsers aktiviert
- der Browser hat das Attach-Consent-Prompt angezeigt und Sie haben es bestätigt
- `openclaw doctor` migriert alte browserbasierte Konfigurationen und prüft, ob
Chrome lokal für Standardprofile mit Auto-Connect installiert ist, aber es kann
- der Zielbrowser auf Chromium-Basis hat Version `144+`
- Remote-Debugging ist auf der Inspektionsseite dieses Browsers aktiviert
- der Browser hat die Anbindungs-Zustimmungsabfrage angezeigt und Sie haben sie bestätigt
- `openclaw doctor` migriert alte Browser-Konfigurationen auf Basis von Erweiterungen und prüft, dass
Chrome lokal für Standardprofile mit Auto-Connect installiert ist, kann aber
browserseitiges Remote-Debugging nicht für Sie aktivieren
Verwendung durch Agents:
Verwendung durch Agenten:
- Verwenden Sie `profile="user"`, wenn Sie den eingeloggten Browser-Zustand des Benutzers benötigen.
- Wenn Sie ein benutzerdefiniertes Existing-Session-Profil verwenden, übergeben Sie diesen expliziten Profilnamen.
- Wählen Sie diesen Modus nur, wenn der Benutzer am Rechner sitzt, um das Attach-
Prompt zu bestätigen.
- Verwenden Sie `profile="user"`, wenn Sie den angemeldeten Browser-Status des Benutzers benötigen.
- Wenn Sie ein benutzerdefiniertes Existing-session-Profil verwenden, geben Sie diesen expliziten Profilnamen an.
- Wählen Sie diesen Modus nur, wenn der Benutzer am Computer sitzt, um die Anbindungs-
abfrage zu genehmigen.
- das Gateway oder der Node-Host kann `npx chrome-devtools-mcp@latest --autoConnect` starten
Hinweise:
- Dieser Pfad ist riskanter als das isolierte Profil `openclaw`, weil er
innerhalb Ihrer eingeloggten Browser-Sitzung handeln kann.
- OpenClaw startet den Browser für diesen Treiber nicht; es hängt sich nur an.
- OpenClaw verwendet hier den offiziellen Flow `--autoConnect` von Chrome DevTools MCP. Wenn
`userDataDir` gesetzt ist, wird es weitergereicht, um dieses User-Data-Directory anzusteuern.
- Existing-session kann sich auf dem ausgewählten Host oder über einen verbundenen
Browser-Node anhängen. Wenn Chrome anderswo läuft und kein Browser-Node verbunden ist, verwenden Sie
stattdessen Remote-CDP oder einen Node-Host.
- Dieser Pfad ist riskanter als das isolierte Profil `openclaw`, da er
innerhalb Ihrer angemeldeten Browser-Session handeln kann.
- OpenClaw startet den Browser für diesen Treiber nicht; es bindet nur an.
- OpenClaw verwendet hier den offiziellen Chrome DevTools MCP-`--autoConnect`-Flow. Wenn
`userDataDir` gesetzt ist, wird es durchgereicht, um auf dieses User-Data-Verzeichnis zu zielen.
- Existing-session kann auf dem ausgewählten Host oder über einen verbundenen
Browser-Node anbinden. Wenn Chrome anderswo läuft und kein Browser-Node verbunden ist, verwenden Sie stattdessen
Remote-CDP oder einen Node-Host.
<Accordion title="Einschränkungen der Existing-Session-Funktion">
<Accordion title="Einschränkungen der Existing-session-Funktion">
Im Vergleich zum verwalteten Profil `openclaw` sind Existing-Session-Treiber stärker eingeschränkt:
Im Vergleich zum verwalteten Profil `openclaw` sind Existing-session-Treiber stärker eingeschränkt:
- **Screenshots** — Seitenaufnahmen und Elementaufnahmen mit `--ref` funktionieren; CSS-`--element`-Selektoren nicht. `--full-page` kann nicht mit `--ref` oder `--element` kombiniert werden. Für Seiten- oder ref-basierte Element-Screenshots ist Playwright nicht erforderlich.
- **Aktionen** — `click`, `type`, `hover`, `scrollIntoView`, `drag` und `select` erfordern Snapshot-Refs (keine CSS-Selektoren). `click` unterstützt nur die linke Maustaste. `type` unterstützt `slowly=true` nicht; verwenden Sie `fill` oder `press`. `press` unterstützt `delayMs` nicht. `hover`, `scrollIntoView`, `drag`, `select`, `fill` und `evaluate` unterstützen keine Timeouts pro Aufruf. `select` akzeptiert einen einzelnen Wert.
- **Wait / upload / dialog** — `wait --url` unterstützt exakte, Substring- und Glob-Muster; `wait --load networkidle` wird nicht unterstützt. Upload-Hooks erfordern `ref` oder `inputRef`, jeweils nur eine Datei, kein CSS-`element`. Dialog-Hooks unterstützen keine Überschreibung des Timeouts.
- **Screenshots** — Seitenerfassungen und Elementerfassungen mit `--ref` funktionieren; CSS-`--element`-Selektoren jedoch nicht. `--full-page` kann nicht mit `--ref` oder `--element` kombiniert werden. Playwright ist für seiten- oder ref-basierte Element-Screenshots nicht erforderlich.
- **Aktionen** — `click`, `type`, `hover`, `scrollIntoView`, `drag` und `select` erfordern Snapshot-Refs (keine CSS-Selektoren). `click` unterstützt nur die linke Maustaste. `type` unterstützt `slowly=true` nicht; verwenden Sie `fill` oder `press`. `press` unterstützt `delayMs` nicht. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` und `evaluate` unterstützen keine Timeouts pro Aufruf. `select` akzeptiert einen einzelnen Wert.
- **Warten / Upload / Dialog** — `wait --url` unterstützt exakte, Teilstring- und Glob-Muster; `wait --load networkidle` wird nicht unterstützt. Upload-Hooks erfordern `ref` oder `inputRef`, jeweils eine Datei, kein CSS-`element`. Dialog-Hooks unterstützen keine Timeout-Overrides.
- **Nur verwaltete Features** — Batch-Aktionen, PDF-Export, Download-Interception und `responsebody` erfordern weiterhin den verwalteten Browser-Pfad.
</Accordion>
## Isolationsgarantien
- **Dediziertes User-Data-Directory**: berührt niemals Ihr persönliches Browser-Profil.
- **Dediziertes User-Data-Verzeichnis**: greift niemals auf Ihr persönliches Browser-Profil zu.
- **Dedizierte Ports**: vermeidet `9222`, um Kollisionen mit Entwicklungs-Workflows zu verhindern.
- **Deterministische Tab-Steuerung**: Tabs werden per `targetId` angesprochen, nicht per „letzter Tab“.
- **Deterministische Tab-Steuerung**: Zielsteuerung von Tabs über `targetId`, nicht über „letzter Tab“.
## Browser-Auswahl
Wenn lokal gestartet wird, wählt OpenClaw den ersten verfügbaren Browser:
Beim lokalen Start wählt OpenClaw den ersten verfügbaren Browser:
1. Chrome
2. Brave
@ -522,35 +521,35 @@ Plattformen:
## Control API (optional)
Für Skripting und Debugging stellt das Gateway eine kleine **nur loopback erreichbare HTTP-
Control-API** plus eine passende `openclaw browser`-CLI bereit (Snapshots, Refs, Wait-
Power-ups, JSON-Ausgabe, Debug-Workflows). Siehe
[Browser control API](/de/tools/browser-control) für die vollständige Referenz.
Für Skripting und Debugging stellt das Gateway eine kleine **nur über loopback erreichbare HTTP-
Control-API** sowie eine passende CLI `openclaw browser` bereit (Snapshots, Refs, Wait-
Erweiterungen, JSON-Ausgabe, Debug-Workflows). Siehe
[Browser Control API](/de/tools/browser-control) für die vollständige Referenz.
## Fehlerbehebung
Für Linux-spezifische Probleme (insbesondere Snap-Chromium) siehe
[Browser troubleshooting](/de/tools/browser-linux-troubleshooting).
Für Linux-spezifische Probleme (insbesondere Snap Chromium) siehe
[Browser-Fehlerbehebung](/de/tools/browser-linux-troubleshooting).
Für Setups mit WSL2-Gateway + Windows-Chrome auf getrennten Hosts siehe
[WSL2 + Windows + remote Chrome CDP troubleshooting](/de/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
Für Split-Host-Setups mit WSL2-Gateway + Windows-Chrome siehe
[Fehlerbehebung für WSL2 + Windows + Remote Chrome CDP](/de/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
### CDP-Startfehler vs. SSRF-Block bei Navigation
### CDP-Startfehler vs. Navigations-SSRF-Block
Dies sind unterschiedliche Fehlerklassen und sie zeigen auf unterschiedliche Codepfade.
Dies sind unterschiedliche Fehlerklassen und sie verweisen auf unterschiedliche Codepfade.
- **CDP-Start- oder Bereitschaftsfehler** bedeutet, dass OpenClaw nicht bestätigen kann, dass die Browser-Control-Plane funktionsfähig ist.
- **Navigation-SSRF-Block** bedeutet, dass die Browser-Control-Plane funktionsfähig ist, aber ein Seitenziel durch die Richtlinie abgelehnt wird.
- **CDP-Start- oder Bereitschaftsfehler** bedeutet, dass OpenClaw nicht bestätigen kann, dass die Browser-Control-Ebene funktionsfähig ist.
- **Navigations-SSRF-Block** bedeutet, dass die Browser-Control-Ebene funktionsfähig ist, aber ein Ziel für die Seitennavigation von der Richtlinie abgelehnt wird.
Häufige Beispiele:
- CDP-Start- oder Bereitschaftsfehler:
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
- Navigation-SSRF-Block:
- `open`, `navigate`, Snapshot- oder Tab-Öffnungs-Flows schlagen mit einem Browser-/Netzwerk-Richtlinienfehler fehl, während `start` und `tabs` weiterhin funktionieren
- Navigations-SSRF-Block:
- `open`, `navigate`, Snapshot- oder Tab-Öffnungs-Flows schlagen mit einem Browser-/Netzwerkrichtlinienfehler fehl, während `start` und `tabs` weiterhin funktionieren
Verwenden Sie diese minimale Sequenz, um die beiden zu unterscheiden:
Verwenden Sie diese minimale Sequenz, um die beiden Fälle zu unterscheiden:
```bash
openclaw browser --browser-profile openclaw start
@ -561,21 +560,21 @@ openclaw browser --browser-profile openclaw open https://example.com
So lesen Sie die Ergebnisse:
- Wenn `start` mit `not reachable after start` fehlschlägt, beheben Sie zuerst die CDP-Bereitschaft.
- Wenn `start` erfolgreich ist, aber `tabs` fehlschlägt, ist die Control-Plane weiterhin ungesund. Behandeln Sie das als CDP-Erreichbarkeitsproblem, nicht als Problem der Seitennavigation.
- Wenn `start` und `tabs` erfolgreich sind, aber `open` oder `navigate` fehlschlägt, ist die Browser-Control-Plane aktiv und der Fehler liegt in der Navigationsrichtlinie oder im Seitenziel.
- Wenn `start`, `tabs` und `open` alle erfolgreich sind, ist der grundlegende Pfad der verwalteten Browser-Steuerung gesund.
- Wenn `start` erfolgreich ist, aber `tabs` fehlschlägt, ist die Control-Ebene weiterhin nicht funktionsfähig. Behandeln Sie dies als Problem mit der CDP-Erreichbarkeit, nicht als Problem der Seitennavigation.
- Wenn `start` und `tabs` erfolgreich sind, aber `open` oder `navigate` fehlschlägt, ist die Browser-Control-Ebene aktiv und der Fehler liegt in der Navigationsrichtlinie oder an der Zielseite.
- Wenn `start`, `tabs` und `open` alle erfolgreich sind, ist der grundlegende Pfad für die verwaltete Browser-Steuerung funktionsfähig.
Wichtige Verhaltensdetails:
- Die Browser-Konfiguration verwendet standardmäßig ein fail-closed-SSRF-Richtlinienobjekt, selbst wenn Sie `browser.ssrfPolicy` nicht konfigurieren.
- Für das lokal über loopback verwaltete Profil `openclaw` überspringen CDP-Health-Checks absichtlich die SSRF-Erreichbarkeitsprüfung des Browsers für die eigene lokale Control-Plane von OpenClaw.
- Navigationsschutz ist separat. Ein erfolgreiches Ergebnis bei `start` oder `tabs` bedeutet nicht, dass ein späteres Ziel für `open` oder `navigate` erlaubt ist.
- Die Browser-Konfiguration verwendet standardmäßig ein fail-closed-SSRF-Richtlinienobjekt, auch wenn Sie `browser.ssrfPolicy` nicht konfigurieren.
- Für das lokal verwaltete loopback-Profil `openclaw` überspringen CDP-Health-Checks absichtlich die Durchsetzung der Browser-SSRF-Erreichbarkeit für die eigene lokale Control-Ebene von OpenClaw.
- Navigationsschutz ist separat. Ein erfolgreiches Ergebnis von `start` oder `tabs` bedeutet nicht, dass ein späteres Ziel für `open` oder `navigate` erlaubt ist.
Sicherheitshinweise:
Sicherheitsempfehlung:
- Schwächen Sie die Browser-SSRF-Richtlinie nicht standardmäßig ab.
- Bevorzugen Sie enge Host-Ausnahmen wie `hostnameAllowlist` oder `allowedHostnames` statt breiten Zugriff auf private Netzwerke.
- Verwenden Sie `dangerouslyAllowPrivateNetwork: true` nur in bewusst vertrauenswürdigen Umgebungen, in denen Browser-Zugriff auf private Netzwerke erforderlich und geprüft ist.
- Lockern Sie die Browser-SSRF-Richtlinie standardmäßig **nicht**.
- Bevorzugen Sie enge Host-Ausnahmen wie `hostnameAllowlist` oder `allowedHostnames` gegenüber breit gefasstem Zugriff auf private Netzwerke.
- Verwenden Sie `dangerouslyAllowPrivateNetwork: true` nur in absichtlich vertrauenswürdigen Umgebungen, in denen Browser-Zugriff auf private Netzwerke erforderlich und geprüft ist.
## Agent-Tools + wie die Steuerung funktioniert
@ -586,16 +585,16 @@ Der Agent erhält **ein Tool** für Browser-Automatisierung:
Zuordnung:
- `browser snapshot` gibt einen stabilen UI-Baum zurück (AI oder ARIA).
- `browser act` verwendet die Snapshot-`ref`-IDs zum Klicken/Tippen/Ziehen/Auswählen.
- `browser act` verwendet die `ref`-IDs aus dem Snapshot zum Klicken/Tippen/Ziehen/Auswählen.
- `browser screenshot` erfasst Pixel (ganze Seite oder Element).
- `browser` akzeptiert:
- `profile`, um ein benanntes Browser-Profil zu wählen (openclaw, chrome oder remote CDP).
- `target` (`sandbox` | `host` | `node`), um auszuwählen, wo der Browser lebt.
- In sandboxed Sitzungen erfordert `target: "host"` `agents.defaults.sandbox.browser.allowHostControl=true`.
- Wenn `target` weggelassen wird: sandboxed Sitzungen verwenden standardmäßig `sandbox`, nicht-sandboxed Sitzungen standardmäßig `host`.
- Wenn ein browserfähiger Node verbunden ist, kann das Tool automatisch dorthin routen, außer Sie pinnen `target="host"` oder `target="node"`.
- `profile`, um ein benanntes Browser-Profil auszuwählen (openclaw, chrome oder Remote-CDP).
- `target` (`sandbox` | `host` | `node`), um auszuwählen, wo der Browser läuft.
- In sandboxed Sessions erfordert `target: "host"` `agents.defaults.sandbox.browser.allowHostControl=true`.
- Wenn `target` weggelassen wird: sandboxed Sessions verwenden standardmäßig `sandbox`, Nicht-Sandbox-Sessions standardmäßig `host`.
- Wenn ein browserfähiger Node verbunden ist, kann das Tool automatisch dorthin geroutet werden, sofern Sie nicht `target="host"` oder `target="node"` festlegen.
Dadurch bleibt der Agent deterministisch und vermeidet fragile Selektoren.
Dies hält den Agenten deterministisch und vermeidet fragile Selektoren.
## Verwandt

118
docs/de/tools/capability-cookbook.md
View File

@ -1,56 +1,57 @@
---
read_when:
- Eine neue Core-Capability und Oberfläche zur Plugin-Registrierung hinzufügen
- Hinzufügen einer neuen Core-Fähigkeit und Plugin-Registrierungsoberfläche
- Entscheiden, ob Code in den Core, ein Vendor-Plugin oder ein Feature-Plugin gehört
- Einen neuen Runtime-Helper für Kanäle oder Tools verdrahten
- Einrichten eines neuen Laufzeit-Helfers für Kanäle oder Tools
sidebarTitle: Adding Capabilities
summary: Leitfaden für Mitwirkende zum Hinzufügen einer neuen gemeinsamen Capability zum OpenClaw-Plugin-System
title: Capabilities hinzufügen (Leitfaden für Mitwirkende)
summary: Leitfaden für Beitragende zum Hinzufügen einer neuen gemeinsamen Fähigkeit zum OpenClaw-Plugin-System
title: Fähigkeiten hinzufügen (Leitfaden für Beitragende)
x-i18n:
generated_at: "2026-04-24T07:02:04Z"
generated_at: "2026-04-24T09:01:29Z"
model: gpt-5.4
provider: openai
source_hash: f1e3251b9150c9744d967e91f531dfce01435b13aea3a17088ccd54f2145d14f
source_hash: 864506dd3f61aa64e7c997c9d9e05ce0ad70c80a26a734d4f83b2e80331be4ab
source_path: tools/capability-cookbook.md
workflow: 15
---
<Info>
Dies ist ein **Leitfaden für Mitwirkende** für OpenClaw-Core-Entwickler. Wenn Sie
ein externes Plugin erstellen, siehe stattdessen [Plugins erstellen](/de/plugins/building-plugins).
Dies ist ein **Leitfaden für Beitragende** für OpenClaw-Core-Entwickler. Wenn Sie
ein externes Plugin erstellen, lesen Sie stattdessen [Plugins erstellen](/de/plugins/building-plugins).
</Info>
Verwenden Sie dies, wenn OpenClaw einen neuen Bereich benötigt, etwa Bildgenerierung, Video-
generierung oder einen zukünftigen, von Vendoren gestützten Funktionsbereich.
Verwenden Sie dies, wenn OpenClaw einen neuen Bereich wie Bildgenerierung, Video-
generierung oder einen zukünftigen von einem Anbieter unterstützten Funktionsbereich benötigt.
Die Regel:
- Plugin = Eigentumsgrenze
- Capability = gemeinsamer Core-Vertrag
- Plugin = Besitzgrenze
- Fähigkeit = gemeinsamer Core-Vertrag
Das bedeutet, Sie sollten nicht damit beginnen, einen Vendor direkt in einen Kanal oder ein
Tool zu verdrahten. Beginnen Sie damit, die Capability zu definieren.
Das bedeutet, dass Sie nicht damit beginnen sollten, einen Anbieter direkt in einen Kanal oder ein
Tool einzubinden. Beginnen Sie mit der Definition der Fähigkeit.
## Wann eine Capability erstellt werden sollte
## Wann eine Fähigkeit erstellt werden sollte
Erstellen Sie eine neue Capability, wenn all dies zutrifft:
Erstellen Sie eine neue Fähigkeit, wenn all dies zutrifft:
1. mehr als ein Vendor könnte sie plausibel implementieren
2. Kanäle, Tools oder Feature-Plugins sollten sie konsumieren, ohne sich für
den Vendor zu interessieren
3. der Core muss Fallback, Richtlinie, Konfiguration oder Zustellungsverhalten besitzen
1. Mehr als ein Anbieter könnte sie plausibel implementieren
2. Kanäle, Tools oder Feature-Plugins sollten sie verwenden können, ohne sich um
den Anbieter zu kümmern
3. Der Core muss Fallback, Richtlinien, Konfiguration oder Zustellungsverhalten besitzen
Wenn die Arbeit nur vendorspezifisch ist und noch kein gemeinsamer Vertrag existiert, stoppen Sie und definieren Sie zuerst den Vertrag.
Wenn die Arbeit nur anbieterbezogen ist und noch kein gemeinsamer Vertrag existiert, stoppen Sie und definieren
Sie zuerst den Vertrag.
## Die Standardsequenz
## Die Standardreihenfolge
1. Den typisierten Core-Vertrag definieren.
2. Plugin-Registrierung für diesen Vertrag hinzufügen.
3. Einen gemeinsamen Runtime-Helper hinzufügen.
4. Ein echtes Vendor-Plugin als Beweis verdrahten.
5. Feature-/Kanal-Consumer auf den Runtime-Helper umstellen.
6. Vertragstests hinzufügen.
7. Die operatorseitige Konfiguration und das Eigentumsmodell dokumentieren.
3. Einen gemeinsamen Laufzeit-Helfer hinzufügen.
4. Ein echtes Anbieter-Plugin als Nachweis einbinden.
5. Feature-/Kanal-Consumer auf den Laufzeit-Helfer umstellen.
6. Contract-Tests hinzufügen.
7. Die operatorseitige Konfiguration und das Besitzmodell dokumentieren.
## Was wohin gehört
@ -59,24 +60,43 @@ Core:
- Request-/Response-Typen
- Provider-Registry + Auflösung
- Fallback-Verhalten
- Konfigurationsschema plus weitergereichte Dokumentationsmetadaten `title` / `description` auf verschachtelten Objekt-, Wildcard-, Array-Element- und Kompositionsknoten
- Runtime-Helper-Oberfläche
- Konfigurationsschema plus weitergegebene `title`- / `description`-Dokumentationsmetadaten auf verschachtelten Objekt-, Wildcard-, Array-Item- und Kompositionsknoten
- Oberfläche des Laufzeit-Helfers
Vendor-Plugin:
Anbieter-Plugin:
- Vendor-API-Aufrufe
- Vendor-spezifische Authentifizierungsbehandlung
- Vendor-spezifische Request-Normalisierung
- Registrierung der Capability-Implementierung
- Anbieter-API-Aufrufe
- Anbieter-Auth-Handling
- anbieterbezogene Request-Normalisierung
- Registrierung der Fähigkeitsimplementierung
Feature-/Kanal-Plugin:
- ruft `api.runtime.*` oder den passenden Helper `plugin-sdk/*-runtime` auf
- ruft niemals direkt eine Vendor-Implementierung auf
- ruft `api.runtime.*` oder den passenden Helfer `plugin-sdk/*-runtime` auf
- ruft niemals direkt eine Anbieterimplementierung auf
## Provider- und Harness-Seams
Verwenden Sie Provider-Hooks, wenn das Verhalten zum Vertrag des Modell-Providers
gehört und nicht zur generischen Agent-Schleife. Beispiele sind anbieterbezogene Request-
Parameter nach der Auswahl des Transports, Präferenz für Auth-Profile, Prompt-Overlays und
das Routing des nachgelagerten Fallbacks nach Modell-/Profil-Failover.
Verwenden Sie Agent-Harness-Hooks, wenn das Verhalten zur Laufzeit gehört, die
einen Turn ausführt. Harnesses können erfolgreiche, aber unbrauchbare Versuchsergebnisse klassifizieren,
etwa leere, nur aus Reasoning bestehende oder nur planende Antworten, damit die äußere
Modell-Fallback-Richtlinie über den Retry entscheiden kann.
Halten Sie beide Seams schmal:
- der Core besitzt die Retry-/Fallback-Richtlinie
- Provider-Plugins besitzen anbieterbezogene Hinweise für Request/Auth/Routing
- Harness-Plugins besitzen die laufzeitspezifische Klassifizierung von Versuchen
- Plugins von Drittanbietern geben Hinweise zurück, keine direkten Mutationen des Core-Zustands
## Dateicheckliste
Für eine neue Capability werden Sie voraussichtlich diese Bereiche anfassen:
Für eine neue Fähigkeit werden voraussichtlich diese Bereiche berührt:
- `src/<capability>/types.ts`
- `src/<capability>/...registry/runtime.ts`
@ -93,33 +113,33 @@ Für eine neue Capability werden Sie voraussichtlich diese Bereiche anfassen:
## Beispiel: Bildgenerierung
Bildgenerierung folgt der Standardform:
Bildgenerierung folgt der Standardschablone:
1. Der Core definiert `ImageGenerationProvider`
2. Der Core stellt `registerImageGenerationProvider(...)` bereit
3. Der Core stellt `runtime.imageGeneration.generate(...)` bereit
4. Die Plugins `openai`, `google`, `fal` und `minimax` registrieren von Vendoren gestützte Implementierungen
5. Zukünftige Vendoren können denselben Vertrag registrieren, ohne Kanäle/Tools zu ändern
4. Die Plugins `openai`, `google`, `fal` und `minimax` registrieren anbieterunterstützte Implementierungen
5. Zukünftige Anbieter können denselben Vertrag registrieren, ohne Kanäle/Tools zu ändern
Der Konfigurationsschlüssel ist von der Routing-Logik für Bildanalyse getrennt:
Der Konfigurationsschlüssel ist von Vision-Analysis-Routing getrennt:
- `agents.defaults.imageModel` = Bilder analysieren
- `agents.defaults.imageGenerationModel` = Bilder generieren
Halten Sie diese getrennt, damit Fallback und Richtlinie explizit bleiben.
Halten Sie diese getrennt, damit Fallback und Richtlinien explizit bleiben.
## Checkliste für Reviews
Bevor Sie eine neue Capability ausliefern, prüfen Sie:
Verifizieren Sie vor dem Ausliefern einer neuen Fähigkeit:
- Kein Kanal/Tool importiert Vendor-Code direkt
- Der Runtime-Helper ist der gemeinsame Pfad
- Mindestens ein Vertragstest bestätigt gebündeltes Eigentum
- Kein Kanal/Tool importiert Anbieter-Code direkt
- Der Laufzeit-Helfer ist der gemeinsame Pfad
- Mindestens ein Contract-Test stellt gebündelten Besitz sicher
- Die Konfigurationsdokumentation benennt den neuen Modell-/Konfigurationsschlüssel
- Die Plugin-Dokumentation erklärt die Eigentumsgrenze
- Die Plugin-Dokumentation erklärt die Besitzgrenze
Wenn ein PR die Capability-Schicht überspringt und Vendor-Verhalten fest in einen
Kanal/ein Tool codiert, schicken Sie ihn zurück und definieren Sie zuerst den Vertrag.
Wenn ein PR die Fähigkeitsebene überspringt und Anbieter-Verhalten direkt in einen
Kanal/ein Tool hartcodiert, schicken Sie ihn zurück und definieren Sie zuerst den Vertrag.
## Verwandt

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

@ -1,24 +1,24 @@
---
read_when:
- Plugins installieren oder konfigurieren
- Discovery- und Lade-Regeln für Plugins verstehen
- Plugin-Erkennung und Laderegeln verstehen
- Mit Codex-/Claude-kompatiblen Plugin-Bundles arbeiten
sidebarTitle: Install and Configure
summary: OpenClaw-Plugins installieren, konfigurieren und verwalten
title: Plugins
x-i18n:
generated_at: "2026-04-24T07:05:09Z"
generated_at: "2026-04-24T09:01:36Z"
model: gpt-5.4
provider: openai
source_hash: a93114ddb312552f4c321b6e318f3e19810cf5059dd0c68fde93da41936566b8
source_hash: 83ab1218d6677ad518a4991ca546d55eed9648e1fa92b76b7433ecd5df569e28
source_path: tools/plugin.md
workflow: 15
---
Plugins erweitern OpenClaw um neue Fähigkeiten: Kanäle, Modell-Provider,
Tools, Skills, Speech, Realtime-Transkription, Realtime-Voice,
Medienverständnis, Bildgenerierung, Videogenerierung, Web-Fetch, Web-
Search und mehr. Einige Plugins sind **core** (mit OpenClaw ausgeliefert), andere
Plugins erweitern OpenClaw um neue Capabilities: Channels, Modell-Provider,
Agent-Harnesses, Tools, Skills, Speech, Echtzeit-Transkription, Echtzeit-Stimme,
Medienverständnis, Bildgenerierung, Videogenerierung, Web-Fetch, Web-Search
und mehr. Einige Plugins sind **core** (mit OpenClaw ausgeliefert), andere
sind **extern** (von der Community auf npm veröffentlicht).
## Schnellstart
@ -47,12 +47,12 @@ sind **extern** (von der Community auf npm veröffentlicht).
openclaw gateway restart
```
Konfigurieren Sie anschließend unter `plugins.entries.\<id\>.config` in Ihrer Konfigurationsdatei.
Konfigurieren Sie es dann unter `plugins.entries.\<id\>.config` in Ihrer Config-Datei.
</Step>
</Steps>
Wenn Sie chat-native Steuerung bevorzugen, aktivieren Sie `commands.plugins: true` und verwenden Sie:
Wenn Sie chatnative Steuerung bevorzugen, aktivieren Sie `commands.plugins: true` und verwenden Sie:
```text
/plugin install clawhub:@openclaw/voice-call
@ -61,46 +61,45 @@ Wenn Sie chat-native Steuerung bevorzugen, aktivieren Sie `commands.plugins: tru
```
Der Installationspfad verwendet denselben Resolver wie die CLI: lokaler Pfad/Archiv, explizites
`clawhub:<pkg>` oder nackte Paketspezifikation (zuerst ClawHub, dann npm-Fallback).
`clawhub:<pkg>` oder bloße Paketspezifikation (zuerst ClawHub, dann npm-Fallback).
Wenn die Konfiguration ungültig ist, schlägt die Installation normalerweise geschlossen fehl und verweist Sie auf
`openclaw doctor --fix`. Die einzige Ausnahme zur Wiederherstellung ist ein schmaler Pfad zum Neuinstallieren gebündelter Plugins
für Plugins, die sich für
Wenn die Config ungültig ist, schlägt die Installation normalerweise kontrolliert fehl und verweist Sie auf
`openclaw doctor --fix`. Die einzige Wiederherstellungsausnahme ist ein enger Neuinstallationspfad
für gebündelte Plugins, der für Plugins gilt, die sich für
`openclaw.install.allowInvalidConfigRecovery` anmelden.
Paketierte OpenClaw-Installationen installieren den Laufzeit-Abhängigkeitsbaum nicht im Voraus für jedes gebündelte Plugin.
Wenn ein gebündeltes, OpenClaw-eigenes Plugin über
Plugin-Konfiguration, alte Kanal-Konfiguration oder ein standardmäßig aktiviertes Manifest aktiv ist, repariert der Start
nur die vom Plugin deklarierten Laufzeit-Abhängigkeiten, bevor es importiert wird.
Externe Plugins und benutzerdefinierte Ladepfade müssen weiterhin über
Paketierte OpenClaw-Installationen installieren den gesamten Runtime-Abhängigkeitsbaum jedes gebündelten Plugins nicht vorab. Wenn ein gebündeltes OpenClaw-eigenes Plugin durch
die Plugin-Config, veraltete Channel-Config oder ein standardmäßig aktiviertes Manifest aktiv ist,
repariert der Start nur die deklarierten Runtime-Abhängigkeiten dieses Plugins, bevor es importiert wird.
Externe Plugins und benutzerdefinierte Ladepfade müssen weiterhin mit
`openclaw plugins install` installiert werden.
## Plugin-Typen
OpenClaw erkennt zwei Plugin-Formate:
| Format | Funktionsweise | Beispiele |
| Format | Funktionsweise | Beispiele |
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + Laufzeitmodul; wird im Prozess ausgeführt | Offizielle Plugins, Community-npm-Pakete |
| **Bundle** | Codex-/Claude-/Cursor-kompatibles Layout; auf OpenClaw-Funktionen abgebildet | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + Runtime-Modul; wird im Prozess ausgeführt | Offizielle Plugins, npm-Pakete der Community |
| **Bundle** | Codex-/Claude-/Cursor-kompatibles Layout; auf OpenClaw-Features abgebildet | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
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 [Building Plugins](/de/plugins/building-plugins)
und [Plugin SDK Overview](/de/plugins/sdk-overview).
und der [Plugin SDK Overview](/de/plugins/sdk-overview).
## Offizielle Plugins
### Installierbar (npm)
| Plugin | Paket | Dokumentation |
| --------------- | --------------------- | -------------------------------------- |
| Matrix | `@openclaw/matrix` | [Matrix](/de/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/de/channels/msteams) |
| Nostr | `@openclaw/nostr` | [Nostr](/de/channels/nostr) |
| Voice Call | `@openclaw/voice-call`| [Voice Call](/de/plugins/voice-call) |
| Zalo | `@openclaw/zalo` | [Zalo](/de/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/de/plugins/zalouser) |
| Plugin | Paket | Dokumentation |
| --------------- | --------------------- | ------------------------------------- |
| Matrix | `@openclaw/matrix` | [Matrix](/de/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/de/channels/msteams) |
| Nostr | `@openclaw/nostr` | [Nostr](/de/channels/nostr) |
| Voice Call | `@openclaw/voice-call` | [Voice Call](/de/plugins/voice-call) |
| Zalo | `@openclaw/zalo` | [Zalo](/de/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/de/plugins/zalouser) |
### Core (mit OpenClaw ausgeliefert)
@ -115,7 +114,7 @@ und [Plugin SDK Overview](/de/plugins/sdk-overview).
<Accordion title="Memory-Plugins">
- `memory-core` — gebündelte Memory-Suche (Standard über `plugins.slots.memory`)
- `memory-lancedb` — On-Demand-Installation für Langzeitspeicher mit automatischem Recall/Capture (setzen Sie `plugins.slots.memory = "memory-lancedb"`)
- `memory-lancedb` — Long-Term Memory mit Install-on-Demand und automatischem Recall/Capture (setzen Sie `plugins.slots.memory = "memory-lancedb"`)
</Accordion>
<Accordion title="Speech-Provider (standardmäßig aktiviert)">
@ -123,8 +122,8 @@ und [Plugin SDK Overview](/de/plugins/sdk-overview).
</Accordion>
<Accordion title="Sonstiges">
- `browser` — gebündeltes Browser-Plugin für das Browser-Tool, `openclaw browser` CLI, die Gateway-Methode `browser.request`, Browser-Laufzeit und den Standarddienst zur Browser-Steuerung (standardmäßig aktiviert; vor dem Ersetzen deaktivieren)
- `copilot-proxy` — Bridge für VS Code Copilot Proxy (standardmäßig deaktiviert)
- `browser` — gebündeltes Browser-Plugin für das Browser-Tool, die CLI `openclaw browser`, die Gateway-Methode `browser.request`, die Browser-Runtime und den Standarddienst zur Browser-Steuerung (standardmäßig aktiviert; vor dem Ersetzen deaktivieren)
- `copilot-proxy` — VS Code Copilot Proxy Bridge (standardmäßig deaktiviert)
</Accordion>
</AccordionGroup>
@ -146,31 +145,30 @@ Suchen Sie nach Plugins von Drittanbietern? Siehe [Community Plugins](/de/plugin
}
```
| Feld | Beschreibung |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Master-Schalter (Standard: `true`) |
| `allow` | Plugin-Allowlist (optional) |
| `deny` | Plugin-Denylist (optional; deny hat Vorrang) |
| `load.paths` | Zusätzliche Plugin-Dateien/-Verzeichnisse |
| Feld | Beschreibung |
| ---------------- | -------------------------------------------------------- |
| `enabled` | Hauptschalter (Standard: `true`) |
| `allow` | Allowlist für Plugins (optional) |
| `deny` | Denylist für Plugins (optional; deny gewinnt) |
| `load.paths` | Zusätzliche Plugin-Dateien/-Verzeichnisse |
| `slots` | Exklusive Slot-Selektoren (z. B. `memory`, `contextEngine`) |
| `entries.\<id\>` | Pluginspezifische Schalter + Konfiguration |
| `entries.\<id\>` | Plugin-spezifische Schalter + Config |
Änderungen an der Konfiguration **erfordern einen Gateway-Neustart**. Wenn das Gateway mit Konfigurations-
Watch + In-Process-Neustart läuft (der Standardpfad von `openclaw gateway`), wird dieser
Neustart normalerweise kurz nach dem Schreiben der Konfiguration automatisch durchgeführt.
Änderungen an der Config **erfordern einen Neustart des Gateway**. Wenn das Gateway mit Config-Watch + In-Process-Neustart ausgeführt wird (der Standardpfad `openclaw gateway`),
wird dieser Neustart normalerweise automatisch kurz nach dem Schreiben der Config durchgeführt.
<Accordion title="Plugin-Zustände: deaktiviert vs. fehlend vs. ungültig">
- **Deaktiviert**: Plugin existiert, wurde aber durch Aktivierungsregeln ausgeschaltet. Die Konfiguration bleibt erhalten.
- **Fehlend**: Die Konfiguration verweist auf eine Plugin-ID, die durch Discovery nicht gefunden wurde.
- **Ungültig**: Plugin existiert, aber seine Konfiguration entspricht nicht dem deklarierten Schema.
- **Deaktiviert**: Das Plugin existiert, aber Aktivierungsregeln haben es ausgeschaltet. Die Config bleibt erhalten.
- **Fehlend**: Die Config verweist auf eine Plugin-ID, die bei der Erkennung nicht gefunden wurde.
- **Ungültig**: Das Plugin existiert, aber seine Config stimmt nicht mit dem deklarierten Schema überein.
</Accordion>
## Discovery und Priorität
## Erkennung und Vorrang
OpenClaw durchsucht Plugins in dieser Reihenfolge (erster Treffer gewinnt):
<Steps>
<Step title="Konfigurationspfade">
<Step title="Config-Pfade">
`plugins.load.paths` — explizite Datei- oder Verzeichnispfade.
</Step>
@ -191,38 +189,37 @@ OpenClaw durchsucht Plugins in dieser Reihenfolge (erster Treffer gewinnt):
### Aktivierungsregeln
- `plugins.enabled: false` deaktiviert alle Plugins
- `plugins.deny` hat immer Vorrang vor allow
- `plugins.deny` gewinnt immer gegenüber allow
- `plugins.entries.\<id\>.enabled: false` deaktiviert dieses Plugin
- Plugins aus dem Workspace sind **standardmäßig deaktiviert** (müssen explizit aktiviert werden)
- Gebündelte Plugins folgen der integrierten Menge von standardmäßig aktivierten Plugins, sofern nicht überschrieben
- Exklusive Slots können das für diesen Slot ausgewählte Plugin zwangsaktivieren
- Einige gebündelte Opt-in-Plugins werden automatisch aktiviert, wenn die Konfiguration eine
plugin-eigene Oberfläche benennt, etwa eine Provider-Modell-Ref, Kanal-Konfiguration oder Harness-
Laufzeit
- Codex-Routen der OpenAI-Familie behalten separate Plugin-Grenzen:
- Plugins aus dem Workspace-Ursprung sind **standardmäßig deaktiviert** (müssen explizit aktiviert werden)
- Gebündelte Plugins folgen der eingebauten standardmäßig aktivierten Menge, sofern sie nicht überschrieben wird
- Exklusive Slots können das für diesen Slot ausgewählte Plugin zwangsweise aktivieren
- Einige gebündelte Opt-in-Plugins werden automatisch aktiviert, wenn die Config eine plugin-eigene Oberfläche benennt,
zum Beispiel eine Modellreferenz eines Providers, eine Channel-Config oder eine Harness-Runtime
- OpenAI-Family-Codex-Routen behalten getrennte Plugin-Grenzen:
`openai-codex/*` gehört zum OpenAI-Plugin, während das gebündelte Codex-
App-Server-Plugin über `embeddedHarness.runtime: "codex"` oder Legacy-
Modell-Refs `codex/*` ausgewählt wird
App-Server-Plugin durch `embeddedHarness.runtime: "codex"` oder veraltete
Modellreferenzen `codex/*` ausgewählt wird
## Plugin-Slots (exklusive Kategorien)
Einige Kategorien sind exklusiv (jeweils nur eine aktive gleichzeitig):
Einige Kategorien sind exklusiv (jeweils nur eine aktiv):
```json5
{
plugins: {
slots: {
memory: "memory-core", // oder "none", um es zu deaktivieren
memory: "memory-core", // oder "none" zum Deaktivieren
contextEngine: "legacy", // oder eine Plugin-ID
},
},
}
```
| Slot | Wodurch er gesteuert wird | Standard |
| --------------- | ------------------------- | -------------------- |
| `memory` | Aktives Memory-Plugin | `memory-core` |
| `contextEngine` | Aktive Kontext-Engine | `legacy` (integriert) |
| Slot | Steuert was | Standard |
| --------------- | ------------------------ | ------------------- |
| `memory` | Active Memory Plugin | `memory-core` |
| `contextEngine` | Aktive Context Engine | `legacy` (integriert) |
## CLI-Referenz
@ -231,25 +228,25 @@ openclaw plugins list # kompaktes Inventar
openclaw plugins list --enabled # nur geladene Plugins
openclaw plugins list --verbose # Detailzeilen pro Plugin
openclaw plugins list --json # maschinenlesbares Inventar
openclaw plugins inspect <id> # tiefe Details
openclaw plugins inspect <id> # ausführliche Details
openclaw plugins inspect <id> --json # maschinenlesbar
openclaw plugins inspect --all # Tabelle für die gesamte Flotte
openclaw plugins info <id> # Alias für inspect
openclaw plugins doctor # Diagnostik
openclaw plugins doctor # Diagnosen
openclaw plugins install <package> # installieren (zuerst ClawHub, dann npm)
openclaw plugins install clawhub:<pkg> # nur aus ClawHub installieren
openclaw plugins install <spec> --force # vorhandene Installation überschreiben
openclaw plugins install <path> # von lokalem Pfad installieren
openclaw plugins install -l <path> # linken (nicht kopieren) für Entwicklung
openclaw plugins install <spec> --force # bestehende Installation überschreiben
openclaw plugins install <path> # aus lokalem Pfad installieren
openclaw plugins install -l <path> # verlinken (ohne Kopie) für Entwicklung
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin # exakte aufgelöste npm-Spezifikation speichern
openclaw plugins install <spec> --pin # exakt aufgelöste npm-Spezifikation speichern
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # ein Plugin aktualisieren
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all # alle aktualisieren
openclaw plugins uninstall <id> # Konfigurations-/Installationsdatensätze entfernen
openclaw plugins uninstall <id> # Config-/Installationsdatensätze entfernen
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
@ -258,58 +255,57 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Gebündelte Plugins werden mit OpenClaw ausgeliefert. Viele davon sind standardmäßig aktiviert (zum Beispiel
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
`--force` überschreibt ein vorhandenes installiertes Plugin oder Hook-Pack direkt vor Ort. Verwenden Sie
`openclaw plugins update <id-or-npm-spec>` für routinemäßige Upgrades nachverfolgter npm-
Plugins. Es wird nicht zusammen mit `--link` unterstützt, da dort der Quellpfad weiterverwendet wird,
statt ihn über ein verwaltetes Installationsziel zu kopieren.
Plugins. Es wird mit `--link` nicht unterstützt, da dabei der Quellpfad wiederverwendet wird,
anstatt über ein verwaltetes Installationsziel zu kopieren.
Wenn `plugins.allow` bereits gesetzt ist, fügt `openclaw plugins install` die
installierte Plugin-ID dieser Allowlist hinzu, bevor es das Plugin aktiviert, sodass Installationen
nach dem Neustart sofort ladbar sind.
installierte Plugin-ID dieser Allowlist hinzu, bevor sie aktiviert wird, sodass Installationen
sofort nach dem Neustart ladbar sind.
`openclaw plugins update <id-or-npm-spec>` gilt für nachverfolgte Installationen. Übergibt man
eine npm-Paketspezifikation mit Dist-Tag oder exakter Version, wird der Paketname zurück
auf den nachverfolgten Plugin-Datensatz aufgelöst und die neue Spezifikation für zukünftige Updates gespeichert.
Wenn nur der Paketname ohne Version übergeben wird, wird eine exakt gepinnte Installation wieder auf
die Standard-Release-Linie des Registry zurückgestellt. Wenn das installierte npm-Plugin bereits
zur aufgelösten Version und zur gespeicherten Artefakt-Identität passt, überspringt OpenClaw das Update,
ohne herunterzuladen, neu zu installieren oder Konfiguration neu zu schreiben.
`openclaw plugins update <id-or-npm-spec>` gilt für nachverfolgte Installationen. Die Übergabe
einer npm-Paketspezifikation mit Dist-Tag oder exakter Version löst den Paketnamen
zurück auf den nachverfolgten Plugin-Datensatz auf und speichert die neue Spezifikation für künftige Updates.
Die Übergabe des Paketnamens ohne Version verschiebt eine exakt angeheftete Installation wieder zurück auf
die Standard-Release-Linie der Registry. Wenn das installierte npm-Plugin bereits mit der aufgelösten Version
und der gespeicherten Artefaktidentität übereinstimmt, überspringt OpenClaw das Update,
ohne herunterzuladen, neu zu installieren oder die Config neu zu schreiben.
`--pin` gilt nur für npm. Es wird nicht zusammen mit `--marketplace` unterstützt, da
Marketplace-Installationen Metadaten der Marketplace-Quelle statt einer npm-Spezifikation speichern.
`--pin` gilt nur für npm. Es wird mit `--marketplace` nicht unterstützt, weil
Marketplace-Installationen Metadaten zur Marketplace-Quelle statt einer npm-Spezifikation speichern.
`--dangerously-force-unsafe-install` ist eine Break-Glass-Überschreibung für Fehlalarme
des integrierten Scanners für gefährlichen Code. Damit können Plugin-Installationen
und Plugin-Updates trotz integrierter `critical`-Befunde fortgesetzt werden, es
umgeht aber weiterhin weder `before_install`-Richtlinien von Plugins noch Blockierung durch Scan-Fehler.
`--dangerously-force-unsafe-install` ist eine Break-Glass-Überschreibung für False Positives des integrierten Scanners für gefährlichen Code. Damit können Plugin-Installationen
und Plugin-Updates trotz integrierter `critical`-Findings fortgesetzt werden, aber
es umgeht weiterhin keine Plugin-`before_install`-Richtlinienblöcke oder die Blockierung bei Scan-Fehlschlägen.
Dieses CLI-Flag gilt nur für Abläufe zum Installieren/Aktualisieren von Plugins. Gateway-gestützte Skill-
Abhängigkeitsinstallationen verwenden stattdessen die passende Request-Überschreibung `dangerouslyForceUnsafeInstall`, während `openclaw skills install` weiterhin 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 Installationen von Skill-Abhängigkeiten verwenden stattdessen die passende Request-Überschreibung `dangerouslyForceUnsafeInstall`, während `openclaw skills install` der separate Download-/Installationsablauf für ClawHub-Skills bleibt.
Kompatible Bundles nehmen am selben Ablauf für plugin list/inspect/enable/disable teil.
Die aktuelle Laufzeitunterstützung umfasst Bundle-Skills, Claude command-skills,
Claude-Standards aus `settings.json`, Claude `.lsp.json` und in Manifests deklarierte
`lspServers`-Standards, Cursor command-skills und kompatible Codex-Hook-Verzeichnisse.
Kompatible Bundles nehmen am selben Ablauf für `list`/`inspect`/`enable`/`disable`
von Plugins teil. Die aktuelle Runtime-Unterstützung umfasst Bundle-Skills, Claude-Command-Skills,
Claude-`settings.json`-Standards, Claude-`.lsp.json` und manifestdeklarierte
Standardwerte für `lspServers`, 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-Server-Einträge für bundlegestützte Plugins.
`openclaw plugins inspect <id>` meldet außerdem erkannte Bundle-Capabilities sowie
unterstützte oder nicht unterstützte MCP- und LSP-Server-Einträge für Bundle-gestützte Plugins.
Marketplace-Quellen können ein bekannter Claude-Marketplace-Name aus
`~/.claude/plugins/known_marketplaces.json`, eine lokale Marketplace-Wurzel oder ein
Pfad zu `marketplace.json`, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-
`~/.claude/plugins/known_marketplaces.json`, ein lokaler Marketplace-Root oder
`marketplace.json`-Pfad, eine GitHub-Kurzschreibweise wie `owner/repo`, eine GitHub-Repo-
URL oder eine Git-URL sein. Bei Remote-Marketplaces müssen Plugin-Einträge innerhalb des
geklonten Marketplace-Repositorys bleiben und dürfen nur relative Pfadquellen verwenden.
geklonten Marketplace-Repos bleiben und dürfen nur relative Pfadquellen verwenden.
Vollständige Details finden Sie in der [`openclaw plugins` CLI reference](/de/cli/plugins).
Vollständige Details finden Sie in der [CLI-Referenz zu `openclaw plugins`](/de/cli/plugins).
## Überblick über die Plugin-API
Native Plugins exportieren ein Entry-Objekt, das `register(api)` bereitstellt. Ältere
Plugins können noch `activate(api)` als Legacy-Alias verwenden, aber neue Plugins sollten
Plugins können weiterhin `activate(api)` als veralteten Alias verwenden, aber neue Plugins sollten
`register` verwenden.
```typescript
@ -330,48 +326,48 @@ export default definePluginEntry({
});
```
OpenClaw lädt das Entry-Objekt und ruft `register(api)` während der Plugin-
OpenClaw lädt das Entry-Objekt und ruft `register(api)` bei der Plugin-
Aktivierung 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 den öffentlichen Vertrag behandeln.
aber gebündelte Plugins und neue externe Plugins sollten `register` als öffentlichen Vertrag behandeln.
Häufige Registrierungs-Methoden:
Häufige Registrierungsmethoden:
| Methode | Was registriert wird |
| --------------------------------------- | ---------------------------- |
| `registerProvider` | Modell-Provider (LLM) |
| `registerChannel` | Chat-Kanal |
| `registerTool` | Agenten-Tool |
| `registerHook` / `on(...)` | Lifecycle-Hooks |
| `registerSpeechProvider` | Text-to-Speech / STT |
| `registerRealtimeTranscriptionProvider` | Streaming-STT |
| `registerRealtimeVoiceProvider` | Duplex-Realtime-Voice |
| `registerMediaUnderstandingProvider` | Bild-/Audioanalyse |
| `registerImageGenerationProvider` | Bildgenerierung |
| `registerMusicGenerationProvider` | Musikgenerierung |
| `registerVideoGenerationProvider` | Videogenerierung |
| `registerWebFetchProvider` | Web-Fetch-/Scrape-Provider |
| `registerWebSearchProvider` | Websuche |
| `registerHttpRoute` | HTTP-Endpunkt |
| `registerCommand` / `registerCli` | CLI-Befehle |
| `registerContextEngine` | Kontext-Engine |
| `registerService` | Hintergrunddienst |
| 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` | Bildgenerierung |
| `registerMusicGenerationProvider` | Musikgenerierung |
| `registerVideoGenerationProvider` | Videogenerierung |
| `registerWebFetchProvider` | Web-Fetch-/Scrape-Provider |
| `registerWebSearchProvider` | Web-Search |
| `registerHttpRoute` | HTTP-Endpunkt |
| `registerCommand` / `registerCli` | CLI-Befehle |
| `registerContextEngine` | Context Engine |
| `registerService` | Hintergrunddienst |
Verhalten von Hook-Guards 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_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.
- `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.
- `before_tool_call`: `{ block: true }` ist final; Handler mit niedrigerer Priorität werden übersprungen.
- `before_tool_call`: `{ block: false }` hat keine Wirkung und hebt einen früheren Block nicht auf.
- `before_install`: `{ block: true }` ist final; Handler mit niedrigerer Priorität werden übersprungen.
- `before_install`: `{ block: false }` hat keine Wirkung und hebt einen früheren Block nicht auf.
- `message_sending`: `{ cancel: true }` ist final; Handler mit niedrigerer Priorität werden übersprungen.
- `message_sending`: `{ cancel: false }` hat keine Wirkung und hebt ein früheres Cancel nicht auf.
Für das vollständige Verhalten typisierter Hooks siehe [SDK Overview](/de/plugins/sdk-overview#hook-decision-semantics).
Das vollständige Verhalten typisierter Hooks finden Sie unter [SDK Overview](/de/plugins/sdk-overview#hook-decision-semantics).
## Verwandt
- [Building Plugins](/de/plugins/building-plugins) — Ihr eigenes Plugin erstellen
- [Plugin Bundles](/de/plugins/bundles) — Kompatibilität mit Codex-/Claude-/Cursor-Bundles
- [Plugin Manifest](/de/plugins/manifest) — Manifest-Schema
- [Registering Tools](/de/plugins/building-plugins#registering-agent-tools) — Agenten-Tools in einem Plugin hinzufügen
- [Plugin Internals](/de/plugins/architecture) — Fähigkeitsmodell und Lade-Pipeline
- [Community Plugins](/de/plugins/community) — Listings von Drittanbietern
- [Registering Tools](/de/plugins/building-plugins#registering-agent-tools) — Agent-Tools in einem Plugin hinzufügen
- [Plugin Internals](/de/plugins/architecture) — Capability-Modell und Ladepipeline
- [Community Plugins](/de/plugins/community) — Auflistungen von Drittanbietern

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

@ -1,14 +1,14 @@
---
read_when:
- Sie möchten das Gateway über einen Browser bedienen.
- Sie möchten Tailnet-Zugriff ohne SSH-Tunnel.
summary: Browserbasierte Control-UI für das Gateway (Chat, Nodes, Konfiguration)
- Sie möchten das Gateway über einen Browser bedienen
- Sie möchten Tailnet-Zugriff ohne SSH-Tunnel
summary: Browserbasierte Control UI für das Gateway (Chat, Nodes, Konfiguration)
title: Control UI
x-i18n:
generated_at: "2026-04-24T07:07:19Z"
generated_at: "2026-04-24T09:01:33Z"
model: gpt-5.4
provider: openai
source_hash: 2ad0d0cef7d842eddf665ba50f37403df258b17d4c072d22a30d1bc3830dc467
source_hash: c84a74e20d6c8829168025830ff4ec8f650f10f72fcaed7c8d2f5d92ab98d616
source_path: web/control-ui.md
workflow: 15
---
@ -16,7 +16,7 @@ x-i18n:
Die Control UI ist eine kleine **Vite + Lit** Single-Page-App, die vom Gateway bereitgestellt wird:
- Standard: `http://<host>:18789/`
- optionales Präfix: Setzen Sie `gateway.controlUi.basePath` (z. B. `/openclaw`)
- optionales Präfix: `gateway.controlUi.basePath` setzen (z. B. `/openclaw`)
Sie spricht **direkt mit dem Gateway-WebSocket** auf demselben Port.
@ -26,28 +26,28 @@ Wenn das Gateway auf demselben Computer läuft, öffnen Sie:
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (oder [http://localhost:18789/](http://localhost:18789/))
Wenn die Seite nicht geladen wird, starten Sie zuerst das Gateway: `openclaw gateway`.
Wenn die Seite nicht geladen werden kann, starten Sie zuerst das Gateway: `openclaw gateway`.
Auth wird beim WebSocket-Handshake bereitgestellt über:
Die Authentifizierung wird während des WebSocket-Handshakes bereitgestellt über:
- `connect.params.auth.token`
- `connect.params.auth.password`
- Tailscale-Serve-Identitäts-Header, wenn `gateway.auth.allowTailscale: true`
- Trusted-Proxy-Identitäts-Header, wenn `gateway.auth.mode: "trusted-proxy"`
Das Einstellungsfenster im Dashboard speichert ein Token für die aktuelle Browser-Tab-Sitzung
und die ausgewählte Gateway-URL; Passwörter werden nicht persistiert. Das Onboarding
erzeugt beim ersten Connect in der Regel ein Gateway-Token für Shared-Secret-Auth, aber Passwort-
Auth funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist.
Das Einstellungsfenster des Dashboards speichert ein Token für die aktuelle Browser-Tab-Sitzung
und die ausgewählte Gateway-URL; Passwörter werden nicht dauerhaft gespeichert. Beim Onboarding
wird normalerweise beim ersten Verbinden ein Gateway-Token für die Authentifizierung mit gemeinsamem Geheimnis erzeugt,
aber Passwort-Authentifizierung funktioniert ebenfalls, wenn `gateway.auth.mode` `"password"` ist.
## Device-Pairing (erste Verbindung)
## Gerätepaarung (erste Verbindung)
Wenn Sie sich mit einem neuen Browser oder Gerät mit der Control UI verbinden, verlangt das Gateway
eine **einmalige Pairing-Freigabe** — selbst wenn Sie sich im selben Tailnet
mit `gateway.auth.allowTailscale: true` befinden. Das ist eine Sicherheitsmaßnahme, um
unautorisierten Zugriff zu verhindern.
Wenn Sie sich von einem neuen Browser oder Gerät mit der Control UI verbinden, verlangt das Gateway
eine **einmalige Genehmigung zur Paarung** — selbst wenn Sie sich im selben Tailnet
mit `gateway.auth.allowTailscale: true` befinden. Dies ist eine Sicherheitsmaßnahme, um
unbefugten Zugriff zu verhindern.
**Was Sie sehen:** „disconnected (1008): pairing required“
**Was Sie sehen werden:** "disconnected (1008): pairing required"
**So genehmigen Sie das Gerät:**
@ -59,141 +59,144 @@ openclaw devices list
openclaw devices approve <requestId>
```
Wenn der Browser Pairing mit geänderten Auth-Details (Rolle/Scopes/Public
Key) erneut versucht, wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId`
Wenn der Browser die Paarung mit geänderten Authentifizierungsdetails wiederholt (Rolle/Scopes/öffentlicher
Schlüssel), wird die vorherige ausstehende Anfrage ersetzt und eine neue `requestId`
erstellt. Führen Sie vor der Genehmigung erneut `openclaw devices list` aus.
Wenn der Browser bereits gepairt ist und Sie ihn von Lesezugriff auf
Schreib-/Admin-Zugriff ändern, wird dies als Freigabe-Upgrade behandelt, nicht als stiller
Reconnect. OpenClaw hält die alte Freigabe aktiv, blockiert den erweiterten Reconnect
und fordert Sie auf, das neue Scope-Set explizit zu genehmigen.
Wenn der Browser bereits gekoppelt ist und Sie ihn von Lesezugriff auf
Schreib-/Admin-Zugriff umstellen, wird dies als Genehmigungs-Upgrade behandelt, nicht als stilles
Neuverbinden. OpenClaw hält die alte Genehmigung aktiv, blockiert das breiter gefasste Reconnect
und fordert Sie auf, den neuen Satz an Scopes explizit zu genehmigen.
Nach der Genehmigung wird das Gerät gespeichert und benötigt keine erneute Freigabe, es sei denn,
Sie widerrufen sie mit `openclaw devices revoke --device <id> --role <role>`. Siehe
Nach der Genehmigung wird das Gerät gespeichert und erfordert keine erneute Genehmigung mehr,
es sei denn, Sie widerrufen es mit `openclaw devices revoke --device <id> --role <role>`. Siehe
[Devices CLI](/de/cli/devices) für Token-Rotation und Widerruf.
**Hinweise:**
- Direkte lokale loopback-Browser-Verbindungen (`127.0.0.1` / `localhost`) werden
- Direkte lokale `local loopback`-Browserverbindungen (`127.0.0.1` / `localhost`) werden
automatisch genehmigt.
- Browser-Verbindungen über Tailnet und LAN erfordern weiterhin eine explizite Freigabe, selbst wenn
- Browserverbindungen über Tailnet und LAN erfordern weiterhin eine explizite Genehmigung, selbst wenn
sie vom selben Rechner stammen.
- Jedes Browser-Profil erzeugt eine eindeutige Geräte-ID, daher erfordert ein Browserwechsel oder
das Löschen von Browserdaten ein erneutes Pairing.
- Jedes Browserprofil erzeugt eine eindeutige Geräte-ID, daher erfordern Browserwechsel oder
das Löschen von Browserdaten eine erneute Paarung.
## Persönliche Identität (browserlokal)
Die Control UI unterstützt eine persönliche Identität pro Browser (Anzeigename und
Avatar), die zur Zuschreibung an ausgehende Nachrichten in gemeinsam genutzten Sitzungen angehängt wird. Sie
liegt im Browser-Speicher, ist auf das aktuelle Browser-Profil beschränkt und wird nicht
mit anderen Geräten synchronisiert oder serverseitig persistiert, abgesehen von den normalen Transkript-
Metadaten zur Autorschaft von Nachrichten, die Sie tatsächlich senden. Das Löschen von Site-Daten oder
ein Browserwechsel setzt sie auf leer zurück.
Avatar), die ausgehenden Nachrichten zur Zuordnung in gemeinsam genutzten Sitzungen beigefügt wird. Sie
liegt im Browser-Speicher, ist auf das aktuelle Browserprofil beschränkt und wird weder
mit anderen Geräten synchronisiert noch serverseitig dauerhaft gespeichert — abgesehen von den normalen
Urheberschaftsmetadaten im Transkript für Nachrichten, die Sie tatsächlich senden. Das Löschen von Websitedaten oder
der Wechsel des Browsers setzt sie auf leer zurück.
## Runtime-Konfigurationsendpunkt
## Laufzeit-Konfigurationsendpunkt
Die Control UI ruft ihre Runtime-Einstellungen von
`/__openclaw/control-ui-config.json` ab. Dieser Endpunkt wird durch dieselbe
Gateway-Auth wie der übrige HTTP-Surface geschützt: Nicht authentifizierte Browser können
Die Control UI lädt ihre Laufzeiteinstellungen von
`/__openclaw/control-ui-config.json`. Dieser Endpunkt wird durch dieselbe
Gateway-Authentifizierung geschützt wie die übrige HTTP-Oberfläche: nicht authentifizierte Browser können
ihn nicht abrufen, und ein erfolgreicher Abruf erfordert entweder ein bereits gültiges Gateway-
Token/Passwort, Tailscale-Serve-Identität oder eine Trusted-Proxy-Identität.
Token/Passwort, eine Tailscale-Serve-Identität oder eine Trusted-Proxy-Identität.
## Sprachunterstützung
Die Control UI kann sich beim ersten Laden anhand des Browser-Gebietsschemas lokalisieren.
Um dies später zu überschreiben, öffnen Sie **Overview -> Gateway Access -> Language**. Der
Locale-Picker befindet sich in der Karte Gateway Access, nicht unter Appearance.
Die Control UI kann sich beim ersten Laden anhand des Gebietsschemas Ihres Browsers lokalisieren.
Um dies später zu überschreiben, öffnen Sie **Overview -> Gateway Access -> Language**. Die
Auswahl für das Gebietsschema befindet sich in der Karte Gateway Access, nicht unter Appearance.
- Unterstützte Locales: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
- Nicht-englische Übersetzungen werden lazy im Browser geladen.
- Das ausgewählte Locale wird im Browser-Speicher gespeichert und bei künftigen Besuchen wiederverwendet.
- Unterstützte Gebietsschemata: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
- Nicht-englische Übersetzungen werden im Browser lazy geladen.
- Das ausgewählte Gebietsschema wird im Browser-Speicher gespeichert und bei zukünftigen Besuchen wiederverwendet.
- Fehlende Übersetzungsschlüssel fallen auf Englisch zurück.
## Was sie heute kann
- Mit dem Modell über Gateway-WS chatten (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
- Direkt aus dem Browser über WebRTC mit OpenAI Realtime sprechen. Das Gateway
erstellt mit `talk.realtime.session` ein kurzlebiges Realtime-Client-Secret; der
- Direkt aus dem Browser per WebRTC mit OpenAI Realtime sprechen. Das Gateway
prägt mit `talk.realtime.session` ein kurzlebiges Realtime-Client-Secret; der
Browser sendet Mikrofon-Audio direkt an OpenAI und leitet
`openclaw_agent_consult`-Tool-Calls über `chat.send` zurück an das größer
konfigurierte OpenClaw-Modell.
- Tool-Calls + Live-Tool-Output-Karten im Chat streamen (Agent-Events)
- Channels: Status, QR-Login und Konfiguration pro Channel für eingebaute sowie gebündelte/externe Plugin-Channels (`channels.status`, `web.login.*`, `config.patch`)
- Instanzen: Presence-Liste + Refresh (`system-presence`)
- Sessions: Liste + Überschreibungen pro Sitzung für Modell/Thinking/Fast/Verbose/Trace/Reasoning (`sessions.list`, `sessions.patch`)
- Dreams: Dreaming-Status, Umschalter zum Aktivieren/Deaktivieren und Reader für das Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- Cron-Jobs: auflisten/hinzufügen/bearbeiten/ausführen/aktivieren/deaktivieren + Run-Historie (`cron.*`)
Tool-Aufrufe `openclaw_agent_consult` über `chat.send` an das größere
konfigurierte OpenClaw-Modell zurück.
- Tool-Aufrufe + Live-Karten zur Tool-Ausgabe im Chat streamen (Agent-Ereignisse)
- Channels: integrierte sowie gebündelte/externe Plugin-Channel-Status, QR-Login und Channel-spezifische Konfiguration (`channels.status`, `web.login.*`, `config.patch`)
- Instanzen: Präsenzliste + Aktualisierung (`system-presence`)
- Sitzungen: Liste + modell-/thinking-/fast-/verbose-/trace-/reasoning-Overrides pro Sitzung (`sessions.list`, `sessions.patch`)
- Dreams: Dreaming-Status, Umschalter zum Aktivieren/Deaktivieren und Dream-Diary-Leser (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- Cron-Jobs: auflisten/hinzufügen/bearbeiten/ausführen/aktivieren/deaktivieren + Ausführungsverlauf (`cron.*`)
- Skills: Status, aktivieren/deaktivieren, installieren, API-Key-Updates (`skills.*`)
- Nodes: Liste + Caps (`node.list`)
- Exec-Freigaben: Allowlists für Gateway oder Node bearbeiten + Ask-Richtlinie für `exec host=gateway/node` (`exec.approvals.*`)
- Nodes: Liste + Fähigkeiten (`node.list`)
- Exec-Genehmigungen: Allowlists für Gateway oder Node bearbeiten + Ask-Richtlinie für `exec host=gateway/node` (`exec.approvals.*`)
- Konfiguration: `~/.openclaw/openclaw.json` anzeigen/bearbeiten (`config.get`, `config.set`)
- Konfiguration: anwenden + mit Validierung neu starten (`config.apply`) und die zuletzt aktive Sitzung aufwecken
- Konfigurationsschreibvorgänge enthalten einen Base-Hash-Guard, um konkurrierende Änderungen nicht zu überschreiben
- Konfigurationsschreibvorgänge (`config.set`/`config.apply`/`config.patch`) führen außerdem vor dem Schreiben einen Preflight für aktive SecretRef-Auflösung für Refs in der übermittelten Konfigurations-Payload durch; nicht aufgelöste aktive übermittelte Refs werden vor dem Schreiben abgelehnt
- Schreibvorgänge auf der Konfiguration enthalten einen Base-Hash-Schutz, um gleichzeitige Bearbeitungen nicht zu überschreiben
- Schreibvorgänge auf der Konfiguration (`config.set`/`config.apply`/`config.patch`) führen außerdem im Vorfeld die Auflösung aktiver SecretRefs für Refs im eingereichten Konfigurations-Payload durch; nicht aufgelöste aktive eingereichte Refs werden vor dem Schreiben abgelehnt
- Konfigurationsschema + Formular-Rendering (`config.schema` / `config.schema.lookup`,
einschließlich Feld `title` / `description`, passender UI-Hinweise, Zusammenfassungen unmittelbarer Child-Elemente, Docs-Metadaten auf verschachtelten Objekt-/Wildcard-/Array-/Composition-Knoten
sowie Plugin- + Channel-Schemata, wenn verfügbar); der Raw-JSON-Editor ist
einschließlich `title` / `description` pro Feld, passender UI-Hinweise, unmittelbarer
Zusammenfassungen untergeordneter Elemente, Dokumentationsmetadaten auf verschachtelten Objekt-/Wildcard-/Array-/Kompositionsknoten
sowie Plugin- + Channel-Schemata, wenn verfügbar); ein roher JSON-Editor ist
nur verfügbar, wenn der Snapshot einen sicheren Raw-Roundtrip hat
- Wenn ein Snapshot keinen sicheren Raw-Roundtrip durchführen kann, erzwingt die Control UI den Formularmodus und deaktiviert den Raw-Modus für diesen Snapshot
- „Reset to saved“ im Raw-JSON-Editor erhält die roh verfasste Form (Formatierung, Kommentare, `$include`-Layout), anstatt einen flach gerenderten Snapshot neu zu rendern, sodass externe Änderungen ein Reset überleben, wenn der Snapshot sicher round-trippen kann
- Strukturierte SecretRef-Objektwerte werden in Textfeldern des Formulars schreibgeschützt gerendert, um versehentliche Beschädigung durch Umwandlung von Objekt zu String zu verhindern
- Debug: Snapshots von Status/Health/Models + Event-Log + manuelle RPC-Calls (`status`, `health`, `models.list`)
- Wenn ein Snapshot keinen sicheren Raw-Roundtrip zulässt, erzwingt die Control UI den Formularmodus und deaktiviert den Raw-Modus für diesen Snapshot
- „Auf Gespeichertes zurücksetzen“ im Raw-JSON-Editor erhält die roh verfasste Form (Formatierung, Kommentare, `$include`-Layout), statt einen geflatteten Snapshot neu zu rendern, sodass externe Änderungen ein Zurücksetzen überstehen, wenn der Snapshot sicher round-trip-fähig ist
- Strukturierte SecretRef-Objektwerte werden in Formular-Textfeldern schreibgeschützt dargestellt, um versehentliche Beschädigung durch Umwandlung von Objekt zu String zu verhindern
- Debug: Snapshots von Status/Health/Modellen + Ereignisprotokoll + manuelle RPC-Aufrufe (`status`, `health`, `models.list`)
- Logs: Live-Tail der Gateway-Dateilogs mit Filter/Export (`logs.tail`)
- Update: Paket-/Git-Update ausführen + neu starten (`update.run`) mit Neustartbericht
- Update: ein Paket-/Git-Update + Neustart ausführen (`update.run`) mit einem Neustartbericht
Hinweise zum Cron-Jobs-Panel:
- Für isolierte Jobs verwendet die Zustellung standardmäßig eine angekündigte Zusammenfassung. Sie können auf none umstellen, wenn Sie nur interne Runs möchten.
- Bei isolierten Jobs ist die Zustellung standardmäßig auf eine Announce-Zusammenfassung gesetzt. Sie können zu none wechseln, wenn Sie nur interne Ausführungen möchten.
- Felder für Channel/Ziel erscheinen, wenn announce ausgewählt ist.
- Der Webhook-Modus verwendet `delivery.mode = "webhook"` mit `delivery.to`, gesetzt auf eine gültige HTTP(S)-Webhook-URL.
- Für Jobs der Main-Session sind die Zustellmodi webhook und none verfügbar.
- Der Webhook-Modus verwendet `delivery.mode = "webhook"` mit `delivery.to`, das auf eine gültige HTTP(S)-Webhook-URL gesetzt ist.
- Für Jobs der Hauptsitzung sind die Zustellmodi webhook und none verfügbar.
- Erweiterte Bearbeitungssteuerungen umfassen delete-after-run, clear agent override, exakte/gestaffelte Cron-Optionen,
Agent-Modell-/Thinking-Überschreibungen und Best-Effort-Zustellungs-Umschalter.
- Formularvalidierung erfolgt inline mit Fehlern auf Feldebene; ungültige Werte deaktivieren die Save-Schaltfläche, bis sie korrigiert sind.
- Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn es fehlt, wird der Webhook ohne Auth-Header gesendet.
- Veralteter Fallback: gespeicherte Legacy-Jobs mit `notify: true` können bis zur Migration weiterhin `cron.webhook` verwenden.
Overrides für Agent-Modell/Thinking und Best-Effort-Zustellungsumschalter.
- Formularvalidierung erfolgt inline mit Fehlern auf Feldebene; ungültige Werte deaktivieren die Schaltfläche zum Speichern, bis sie korrigiert sind.
- Setzen Sie `cron.webhookToken`, um ein dediziertes Bearer-Token zu senden; wenn es weggelassen wird, wird der Webhook ohne Auth-Header gesendet.
- Veralteter Fallback: gespeicherte ältere Jobs mit `notify: true` können weiterhin `cron.webhook` verwenden, bis sie migriert werden.
## Chat-Verhalten
- `chat.send` ist **nicht blockierend**: Es bestätigt sofort mit `{ runId, status: "started" }`, und die Antwort wird über `chat`-Events gestreamt.
- Erneutes Senden mit demselben `idempotencyKey` gibt während des Laufs `{ status: "in_flight" }` zurück und nach Abschluss `{ status: "ok" }`.
- Antworten von `chat.history` sind für UI-Sicherheit größenbegrenzt. Wenn Transkript-Einträge zu groß sind, kann das Gateway lange Textfelder kürzen, schwere Metadatenblöcke weglassen und übergroße Nachrichten durch einen Platzhalter ersetzen (`[chat.history omitted: message too large]`).
- Von Assistant erzeugte Bilder werden als verwaltete Medienreferenzen persistiert und über authentifizierte Gateway-Media-URLs zurückgeliefert, sodass Reloads nicht davon abhängen, dass rohe Base64-Bild-Payloads in der Chat-History-Antwort verbleiben.
- `chat.history` entfernt außerdem reine Anzeige-Inline-Direktiv-Tags aus sichtbarem Assistant-Text (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), XML-Payloads von Tool-Calls im Klartext (einschließlich `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` und abgeschnittener Tool-Call-Blöcke) sowie geleakte ASCII-/Vollbreiten-Model-Control-Tokens und lässt Assistant-Einträge aus, deren gesamter sichtbarer Text nur aus dem exakten Silent-Token `NO_REPLY` / `no_reply` besteht.
- `chat.inject` hängt dem Sitzungs-Transkript eine Assistant-Notiz an und sendet ein `chat`-Event für reine UI-Updates (kein Agent-Run, keine Channel-Zustellung).
- Die Modell- und Thinking-Picker im Chat-Header patchen die aktive Sitzung sofort über `sessions.patch`; sie sind persistente Sitzungsüberschreibungen, keine Send-Optionen nur für einen Turn.
- Der Talk-Modus verwendet den registrierten Realtime-Voice-Provider. Konfigurieren Sie OpenAI mit
`talk.provider: "openai"` plus `talk.providers.openai.apiKey`, oder verwenden Sie die
Realtime-Provider-Konfiguration von Voice Call wieder. Der Browser erhält niemals den normalen
OpenAI-API-Key; er erhält nur das flüchtige Realtime-Client-Secret. Der Prompt der
Realtime-Sitzung wird vom Gateway zusammengestellt; `talk.realtime.session`
akzeptiert keine vom Aufrufer bereitgestellten Überschreibungen für Instructions.
- `chat.send` ist **nicht blockierend**: Es bestätigt sofort mit `{ runId, status: "started" }`, und die Antwort wird über `chat`-Ereignisse gestreamt.
- Erneutes Senden mit demselben `idempotencyKey` gibt während der Ausführung `{ status: "in_flight" }` und nach Abschluss `{ status: "ok" }` zurück.
- Antworten von `chat.history` sind aus Sicherheitsgründen für die UI größenbegrenzt. Wenn Einträge im Transkript zu groß sind, kann das Gateway lange Textfelder kürzen, schwere Metadatenblöcke weglassen und übergroße Nachrichten durch einen Platzhalter ersetzen (`[chat.history omitted: message too large]`).
- Vom Assistenten erzeugte Bilder werden als verwaltete Medienreferenzen gespeichert und über authentifizierte Gateway-Medien-URLs wieder bereitgestellt, sodass Reloads nicht davon abhängen, dass rohe Base64-Bild-Payloads in der Antwort von `chat.history` erhalten bleiben.
- `chat.history` entfernt außerdem nur für die Anzeige bestimmte Inline-Direktiv-Tags aus sichtbarem Assistententext (zum Beispiel `[[reply_to_*]]` und `[[audio_as_voice]]`), XML-Payloads von Tool-Aufrufen im Klartext (einschließlich `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` und gekürzten Tool-Call-Blöcken) sowie durchgesickerte ASCII-/Vollbreiten-Kontrolltoken des Modells und lässt Assistenteneinträge weg, deren gesamter sichtbarer Text nur aus dem exakten stillen Token `NO_REPLY` / `no_reply` besteht.
- `chat.inject` hängt dem Sitzungs-Transkript eine Assistentennotiz an und sendet ein `chat`-Ereignis für UI-only-Aktualisierungen (keine Agent-Ausführung, keine Channel-Zustellung).
- Die Auswahlfelder für Modell und Thinking im Chat-Header patchen die aktive Sitzung sofort über `sessions.patch`; es sind persistente Sitzungs-Overrides, keine Optionen nur für einen Turn.
- Der Talk-Modus verwendet einen registrierten Realtime-Voice-Provider, der browserbasierte
WebRTC-Sitzungen unterstützt. Konfigurieren Sie OpenAI mit `talk.provider: "openai"` plus
`talk.providers.openai.apiKey`, oder verwenden Sie die Konfiguration des Realtime-Providers von Voice Call wieder.
Der Browser erhält niemals den normalen OpenAI-API-Key; er erhält
nur das ephemere Realtime-Client-Secret. Google Live Realtime Voice wird
für backendseitige Voice-Call- und Google-Meet-Bridges unterstützt, aber noch nicht für diesen browserbasierten
WebRTC-Pfad. Der Prompt der Realtime-Sitzung wird vom Gateway zusammengestellt;
`talk.realtime.session` akzeptiert keine vom Aufrufer bereitgestellten Instruction-Overrides.
- Im Chat-Composer ist das Talk-Steuerelement die Wellen-Schaltfläche neben der
Mikrofon-Diktier-Schaltfläche. Wenn Talk startet, zeigt die Statuszeile des Composer
`Connecting Talk...`, dann `Talk live`, solange Audio verbunden ist, oder
`Asking OpenClaw...`, während ein Realtime-Tool-Call das konfigurierte
Diktier-Mikrofon-Schaltfläche. Wenn Talk startet, zeigt die Statuszeile des Composers
`Connecting Talk...`, dann `Talk live`, während Audio verbunden ist, oder
`Asking OpenClaw...`, während ein Realtime-Tool-Aufruf das konfigurierte
größere Modell über `chat.send` konsultiert.
- Stop:
- Stoppen:
- Klicken Sie auf **Stop** (ruft `chat.abort` auf)
- Während ein Run aktiv ist, werden normale Follow-ups in die Queue gestellt. Klicken Sie bei einer wartenden Nachricht auf **Steer**, um dieses Follow-up in den laufenden Turn zu injizieren.
- Geben Sie `/stop` ein (oder eigenständige Abbruch-Phrasen wie `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), um out-of-band abzubrechen
- `chat.abort` unterstützt `{ sessionKey }` (ohne `runId`), um alle aktiven Runs dieser Sitzung abzubrechen
- Beibehaltung von Abbruch-Teilergebnissen:
- Wenn ein Run abgebrochen wird, kann partieller Assistant-Text weiterhin in der UI angezeigt werden
- Das Gateway persistiert partiellen Assistant-Text aus einem Abbruch in die Transkript-Historie, wenn gepufferte Ausgabe vorhanden ist
- Persistierte Einträge enthalten Abbruch-Metadaten, sodass Transkript-Consumer Abbruch-Teilergebnisse von normal abgeschlossener Ausgabe unterscheiden können
- Während eine Ausführung aktiv ist, werden normale Follow-ups in die Warteschlange gestellt. Klicken Sie bei einer wartenden Nachricht auf **Steer**, um dieses Follow-up in den laufenden Turn einzuspeisen.
- Geben Sie `/stop` ein (oder eigenständige Abbruchphrasen wie `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), um außerhalb des regulären Pfads abzubrechen
- `chat.abort` unterstützt `{ sessionKey }` (ohne `runId`), um alle aktiven Ausführungen für diese Sitzung abzubrechen
- Beibehaltung von Teilinhalten beim Abbruch:
- Wenn eine Ausführung abgebrochen wird, kann partieller Assistententext weiterhin in der UI angezeigt werden
- Das Gateway speichert partiellen Assistententext aus abgebrochenen Ausführungen im Transkriptverlauf, wenn gepufferte Ausgabe vorhanden ist
- Gespeicherte Einträge enthalten Abbruchmetadaten, damit Consumer des Transkripts Teilausgaben nach Abbruch von normal abgeschlossener Ausgabe unterscheiden können
## Gehostete Embeds
## Gehostete Einbettungen
Assistant-Nachrichten können gehostete Webinhalte inline mit dem Shortcode `[embed ...]`
rendern. Die Sandbox-Richtlinie für iframes wird gesteuert durch
Assistentennachrichten können gehostete Webinhalte inline mit dem Shortcode `[embed ...]`
rendern. Die Iframe-Sandbox-Richtlinie wird gesteuert durch
`gateway.controlUi.embedSandbox`:
- `strict`: deaktiviert die Ausführung von Skripten innerhalb gehosteter Embeds
- `scripts`: erlaubt interaktive Embeds bei beibehaltener Origin-Isolation; dies ist
der Standard und reicht normalerweise für in sich geschlossene Browser-Spiele/Widgets
- `trusted`: fügt `allow-same-origin` zusätzlich zu `allow-scripts` für Same-Site-
Dokumente hinzu, die absichtlich stärkere Privilegien benötigen
- `strict`: deaktiviert die Ausführung von Skripten innerhalb gehosteter Einbettungen
- `scripts`: erlaubt interaktive Einbettungen bei beibehaltener Origin-Isolation; dies ist
der Standard und reicht normalerweise für in sich geschlossene Browser-Spiele/Widgets aus
- `trusted`: fügt `allow-same-origin` zusätzlich zu `allow-scripts` für gleichseitige
Dokumente hinzu, die absichtlich stärkere Berechtigungen benötigen
Beispiel:
@ -208,10 +211,10 @@ Beispiel:
```
Verwenden Sie `trusted` nur, wenn das eingebettete Dokument tatsächlich Same-Origin-
Verhalten benötigt. Für die meisten von Agents erzeugten Spiele und interaktiven Canvases ist `scripts`
Verhalten benötigt. Für die meisten vom Agent erzeugten Spiele und interaktiven Canvases ist `scripts`
die sicherere Wahl.
Absolute externe `http(s)`-Embed-URLs bleiben standardmäßig blockiert. Wenn Sie
Absolute externe `http(s)`-Einbettungs-URLs bleiben standardmäßig blockiert. Wenn Sie
absichtlich möchten, dass `[embed url="https://..."]` Seiten von Drittanbietern lädt, setzen Sie
`gateway.controlUi.allowExternalEmbedUrls: true`.
@ -219,7 +222,7 @@ absichtlich möchten, dass `[embed url="https://..."]` Seiten von Drittanbietern
### Integriertes Tailscale Serve (bevorzugt)
Behalten Sie das Gateway auf loopback und lassen Sie Tailscale Serve es per HTTPS proxyen:
Behalten Sie das Gateway auf Loopback und lassen Sie Tailscale Serve es mit HTTPS proxyen:
```bash
openclaw gateway --tailscale serve
@ -229,52 +232,52 @@ openclaw gateway --tailscale serve
- `https://<magicdns>/` (oder Ihr konfiguriertes `gateway.controlUi.basePath`)
Standardmäßig können sich Control-UI-/WebSocket-Serve-Requests über Tailscale-Identitäts-Header
Standardmäßig können sich Anfragen an Control UI/WebSocket über Tailscale-Identitäts-Header
(`tailscale-user-login`) authentifizieren, wenn `gateway.auth.allowTailscale` `true` ist. OpenClaw
verifiziert die Identität, indem es die Adresse `x-forwarded-for` mit
`tailscale whois` auflöst und mit dem Header abgleicht, und akzeptiert diese nur, wenn die
Request loopback mit Tailscales `x-forwarded-*`-Headern erreicht. Setzen Sie
`gateway.auth.allowTailscale: false`, wenn Sie selbst für Serve-Traffic explizite Shared-Secret-
Zugangsdaten verlangen möchten. Verwenden Sie dann `gateway.auth.mode: "token"` oder
`tailscale whois` auflöst und sie mit dem Header abgleicht, und akzeptiert diese nur, wenn die
Anfrage Loopback mit Tailscales `x-forwarded-*`-Headern erreicht. Setzen Sie
`gateway.auth.allowTailscale: false`, wenn Sie selbst für Serve-Datenverkehr explizite Anmeldedaten mit gemeinsamem Geheimnis
erzwingen möchten. Verwenden Sie dann `gateway.auth.mode: "token"` oder
`"password"`.
Für diesen asynchronen Serve-Identitätspfad werden fehlgeschlagene Auth-Versuche für dieselbe Client-IP
und denselben Auth-Scope vor Rate-Limit-Schreibvorgängen serialisiert. Gleichzeitige fehlerhafte Retries
aus demselben Browser können daher bei der zweiten Request `retry later` anzeigen
statt zweier normaler Mismatches, die parallel gegeneinander laufen.
Tokenlose Serve-Auth setzt voraus, dass dem Gateway-Host vertraut wird. Wenn auf diesem Host
nicht vertrauenswürdiger lokaler Code laufen könnte, verlangen Sie Token-/Passwort-Auth.
Für diesen asynchronen Serve-Identitätspfad werden fehlgeschlagene Authentifizierungsversuche für dieselbe Client-IP
und denselben Authentifizierungsbereich vor dem Schreiben des Rate-Limits serialisiert. Gleichzeitige fehlerhafte Wiederholungsversuche
aus demselben Browser können daher beim zweiten Request `retry later` anzeigen
statt zwei einfache Nichtübereinstimmungen parallel durchrennen zu lassen.
Tokenlose Serve-Authentifizierung setzt voraus, dass dem Gateway-Host vertraut wird. Wenn auf diesem Host
nicht vertrauenswürdiger lokaler Code laufen kann, verlangen Sie Token-/Passwort-Authentifizierung.
### An Tailnet + Token binden
### An Tailnet binden + Token
```bash
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
```
Öffnen Sie dann:
Dann öffnen Sie:
- `http://<tailscale-ip>:18789/` (oder Ihr konfiguriertes `gateway.controlUi.basePath`)
Fügen Sie das passende Shared Secret in die UI-Einstellungen ein (gesendet als
Fügen Sie das passende gemeinsame Geheimnis in die UI-Einstellungen ein (gesendet als
`connect.params.auth.token` oder `connect.params.auth.password`).
## Unsicheres HTTP
Wenn Sie das Dashboard über reines HTTP öffnen (`http://<lan-ip>` oder `http://<tailscale-ip>`),
Wenn Sie das Dashboard über unverschlüsseltes HTTP öffnen (`http://<lan-ip>` oder `http://<tailscale-ip>`),
läuft der Browser in einem **nicht sicheren Kontext** und blockiert WebCrypto. Standardmäßig
**blockiert** OpenClaw Control-UI-Verbindungen ohne Geräteidentität.
**blockiert** OpenClaw Verbindungen der Control UI ohne Geräteidentität.
Dokumentierte Ausnahmen:
- nur für localhost: Kompatibilität mit unsicherem HTTP über `gateway.controlUi.allowInsecureAuth=true`
- erfolgreiche Operator-Control-UI-Auth über `gateway.auth.mode: "trusted-proxy"`
- localhost-only-Kompatibilität für unsicheres HTTP mit `gateway.controlUi.allowInsecureAuth=true`
- erfolgreiche operatorseitige Control-UI-Authentifizierung über `gateway.auth.mode: "trusted-proxy"`
- Break-Glass `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
**Empfohlene Lösung:** Verwenden Sie HTTPS (Tailscale Serve) oder öffnen Sie die UI lokal:
**Empfohlene Lösung:** HTTPS verwenden (Tailscale Serve) oder die UI lokal öffnen:
- `https://<magicdns>/` (Serve)
- `http://127.0.0.1:18789/` (auf dem Gateway-Host)
**Verhalten des Toggles für unsichere Auth:**
**Verhalten des Umschalters für unsichere Authentifizierung:**
```json5
{
@ -286,14 +289,14 @@ Dokumentierte Ausnahmen:
}
```
`allowInsecureAuth` ist nur ein lokaler Kompatibilitäts-Toggle:
`allowInsecureAuth` ist nur ein lokaler Kompatibilitäts-Umschalter:
- Es erlaubt localhost-Control-UI-Sitzungen, in
- Er erlaubt localhost-Control-UI-Sitzungen, in
nicht sicheren HTTP-Kontexten ohne Geräteidentität fortzufahren.
- Es umgeht keine Pairing-Prüfungen.
- Es lockert nicht die Anforderungen an die Geräteidentität für entfernte (nicht localhost) Verbindungen.
- Er umgeht keine Paarungsprüfungen.
- Er lockert keine Anforderungen an die Geräteidentität für entfernte (nicht localhost) Verbindungen.
**Nur als Break-Glass:**
**Nur für Break-Glass:**
```json5
{
@ -305,68 +308,68 @@ Dokumentierte Ausnahmen:
}
```
`dangerouslyDisableDeviceAuth` deaktiviert die Prüfungen der Geräteidentität für die Control UI und ist eine
schwerwiegende Sicherheitsverschlechterung. Nehmen Sie die Änderung nach einer Notfallnutzung schnell zurück.
`dangerouslyDisableDeviceAuth` deaktiviert die Prüfungen der Geräteidentität in der Control UI und ist ein
schwerwiegendes Sicherheits-Downgrade. Machen Sie dies nach einer Notfallverwendung schnell rückgängig.
Hinweis zu Trusted Proxy:
Hinweis zu trusted-proxy:
- erfolgreiche Trusted-Proxy-Auth kann **Operator**-Control-UI-Sitzungen ohne
- erfolgreiche trusted-proxy-Authentifizierung kann **operator**-Sitzungen der Control UI ohne
Geräteidentität zulassen
- dies gilt **nicht** für Control-UI-Sitzungen mit Node-Rolle
- Same-Host-loopback-Reverse-Proxies erfüllen Trusted-Proxy-Auth weiterhin nicht; siehe
- dies gilt **nicht** für Sitzungen der Control UI mit Node-Rolle
- Reverse-Proxys auf demselben Host über Loopback erfüllen weiterhin keine trusted-proxy-Authentifizierung; siehe
[Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)
Siehe [Tailscale](/de/gateway/tailscale) für Hinweise zur HTTPS-Einrichtung.
## Content Security Policy
Die Control UI wird mit einer strikten `img-src`-Richtlinie ausgeliefert: Nur Assets mit **same-origin** und `data:`-URLs sind erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgelehnt und lösen keine Netzwerkabrufe aus.
Die Control UI wird mit einer strengen `img-src`-Richtlinie ausgeliefert: Nur Assets mit **gleichem Ursprung** und `data:`-URLs sind erlaubt. Entfernte `http(s)`- und protokollrelative Bild-URLs werden vom Browser abgelehnt und lösen keine Netzwerkabrufe aus.
Was das praktisch bedeutet:
Was das in der Praxis bedeutet:
- Avatare und Bilder, die unter relativen Pfaden ausgeliefert werden (zum Beispiel `/avatars/<id>`), werden weiterhin gerendert.
- Inline-URLs `data:image/...` werden weiterhin gerendert (nützlich für In-Protocol-Payloads).
- Entfernte Avatar-URLs aus Channel-Metadaten werden von den Avatar-Helpern der Control UI entfernt und durch das eingebaute Logo/Badge ersetzt, sodass ein kompromittierter oder bösartiger Channel keine beliebigen entfernten Bildabrufe aus dem Browser eines Operators erzwingen kann.
- Inline-`data:image/...`-URLs werden weiterhin gerendert (nützlich für Payloads innerhalb des Protokolls).
- Entfernte Avatar-URLs, die durch Channel-Metadaten ausgegeben werden, werden in den Avatar-Helpern der Control UI entfernt und durch das integrierte Logo/Badge ersetzt, sodass ein kompromittierter oder bösartiger Channel keine beliebigen entfernten Bildabrufe vom Browser eines Operators erzwingen kann.
Sie müssen nichts ändern, um dieses Verhalten zu erhalten — es ist immer aktiv und nicht konfigurierbar.
## Auth für Avatar-Route
## Authentifizierung der Avatar-Route
Wenn Gateway-Auth konfiguriert ist, erfordert der Avatar-Endpunkt der Control UI dasselbe Gateway-Token wie der Rest der API:
Wenn Gateway-Authentifizierung konfiguriert ist, erfordert der Avatar-Endpunkt der Control UI dasselbe Gateway-Token wie der Rest der API:
- `GET /avatar/<agentId>` gibt das Avatar-Bild nur an authentifizierte Aufrufer zurück. `GET /avatar/<agentId>?meta=1` gibt die Avatar-Metadaten unter derselben Regel zurück.
- Nicht authentifizierte Requests an beide Routen werden abgelehnt (entsprechend der benachbarten Assistant-Media-Route). Dadurch wird verhindert, dass die Avatar-Route Agent-Identität auf Hosts preisgibt, die sonst geschützt sind.
- Die Control UI leitet beim Abrufen von Avataren selbst das Gateway-Token als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, sodass das Bild in Dashboards weiterhin gerendert wird.
- Nicht authentifizierte Anfragen an beide Routen werden abgelehnt (entsprechend der benachbarten Route für Assistant-Medien). Das verhindert, dass die Avatar-Route die Agent-Identität auf Hosts offenlegt, die ansonsten geschützt sind.
- Die Control UI selbst leitet beim Abrufen von Avataren das Gateway-Token als Bearer-Header weiter und verwendet authentifizierte Blob-URLs, sodass das Bild weiterhin in Dashboards gerendert wird.
Wenn Sie Gateway-Auth deaktivieren (nicht empfohlen auf gemeinsam genutzten Hosts), wird auch die Avatar-Route nicht authentifiziert, im Einklang mit dem Rest des Gateway.
Wenn Sie die Gateway-Authentifizierung deaktivieren (nicht empfohlen auf gemeinsam genutzten Hosts), wird auch die Avatar-Route unauthentifiziert, entsprechend dem Rest des Gateway.
## Die UI bauen
## Erstellen der UI
Das Gateway liefert statische Dateien aus `dist/control-ui` aus. Bauen Sie sie mit:
Das Gateway liefert statische Dateien aus `dist/control-ui` aus. Erstellen Sie sie mit:
```bash
pnpm ui:build
```
Optionaler absoluter Base-Pfad (wenn Sie feste Asset-URLs möchten):
Optionale absolute Base (wenn Sie feste Asset-URLs möchten):
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```
Für lokale Entwicklung (separater Dev-Server):
Für lokale Entwicklung (separater Entwicklungsserver):
```bash
pnpm ui:dev
```
Zeigen Sie dann die UI auf Ihre Gateway-WS-URL (z. B. `ws://127.0.0.1:18789`).
Richten Sie die UI dann auf Ihre Gateway-WS-URL aus (z. B. `ws://127.0.0.1:18789`).
## Debugging/Tests: Dev-Server + entferntes Gateway
Die Control UI besteht aus statischen Dateien; das WebSocket-Ziel ist konfigurierbar und kann
sich vom HTTP-Origin unterscheiden. Das ist praktisch, wenn Sie den Vite-Dev-Server
lokal ausführen möchten, das Gateway aber anderswo läuft.
sich vom HTTP-Ursprung unterscheiden. Das ist praktisch, wenn Sie den Vite-Dev-Server lokal möchten,
das Gateway aber anderswo läuft.
1. Starten Sie den UI-Dev-Server: `pnpm ui:dev`
2. Öffnen Sie eine URL wie:
@ -375,7 +378,7 @@ lokal ausführen möchten, das Gateway aber anderswo läuft.
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
```
Optionale einmalige Auth (falls erforderlich):
Optionale einmalige Authentifizierung (falls nötig):
```text
http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>
@ -384,19 +387,18 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
Hinweise:
- `gatewayUrl` wird nach dem Laden in `localStorage` gespeichert und aus der URL entfernt.
- `token` sollte wann immer möglich über das URL-Fragment (`#token=...`) übergeben werden. Fragmente werden nicht an den Server gesendet, wodurch Leaks in Request-Logs und über Referer vermieden werden. Legacy-Query-Parameter `?token=` werden aus Kompatibilitätsgründen weiterhin einmal importiert, aber nur als Fallback, und sofort nach dem Bootstrap entfernt.
- `token` sollte wann immer möglich über das URL-Fragment (`#token=...`) übergeben werden. Fragmente werden nicht an den Server gesendet, wodurch Leaks in Request-Logs und Referer vermieden werden. Ältere Query-Parameter `?token=` werden aus Kompatibilitätsgründen weiterhin einmalig importiert, aber nur als Fallback, und sofort nach dem Bootstrap entfernt.
- `password` wird nur im Speicher gehalten.
- Wenn `gatewayUrl` gesetzt ist, fällt die UI nicht auf Zugangsdaten aus Konfiguration oder Umgebung zurück.
Geben Sie `token` (oder `password`) explizit an. Fehlende explizite Zugangsdaten sind ein Fehler.
- Verwenden Sie `wss://`, wenn sich das Gateway hinter TLS befindet (Tailscale Serve, HTTPS-Proxy usw.).
- `gatewayUrl` wird nur in einem Top-Level-Fenster akzeptiert (nicht eingebettet), um Clickjacking zu verhindern.
- Nicht-loopback-Control-UI-Deployments müssen `gateway.controlUi.allowedOrigins`
- Wenn `gatewayUrl` gesetzt ist, fällt die UI nicht auf Konfiguration oder Umgebungs-Credentials zurück.
Geben Sie `token` (oder `password`) explizit an. Fehlende explizite Anmeldedaten sind ein Fehler.
- Verwenden Sie `wss://`, wenn das Gateway hinter TLS liegt (Tailscale Serve, HTTPS-Proxy usw.).
- `gatewayUrl` wird nur in einem Top-Level-Fenster (nicht eingebettet) akzeptiert, um Clickjacking zu verhindern.
- Bereitstellungen der Control UI ohne Loopback müssen `gateway.controlUi.allowedOrigins`
explizit setzen (vollständige Origins). Das gilt auch für entfernte Dev-Setups.
- Verwenden Sie `gateway.controlUi.allowedOrigins: ["*"]` nur für streng kontrollierte
lokale Tests. Es bedeutet, jeden Browser-Origin zu erlauben, nicht „mit welchem Host ich auch
gerade arbeite“.
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert den
Host-Header-Origin-Fallback-Modus, aber das ist ein gefährlicher Sicherheitsmodus.
lokale Tests. Das bedeutet, jeden Browser-Origin zu erlauben, nicht „den gerade verwendeten Host abzugleichen“.
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` aktiviert
den Modus für Host-Header-Origin-Fallback, ist aber ein gefährlicher Sicherheitsmodus.
Beispiel:
@ -416,5 +418,5 @@ Details zur Einrichtung des Fernzugriffs: [Remote access](/de/gateway/remote).
- [Dashboard](/de/web/dashboard) — Gateway-Dashboard
- [WebChat](/de/web/webchat) — browserbasierte Chat-Oberfläche
- [TUI](/de/web/tui) — Terminal User Interface
- [TUI](/de/web/tui) — terminalbasierte Benutzeroberfläche
- [Health Checks](/de/gateway/health) — Gateway-Health-Monitoring