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-15 19:55:37 +00:00
parent 33a137e83f
commit db04fca532
9 changed files with 1730 additions and 1495 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

481
docs/de/channels/matrix.md
View File

@ -2,25 +2,25 @@
read_when:
- Matrix in OpenClaw einrichten
- Matrix-E2EE und Verifizierung konfigurieren
summary: Status des Matrix-Supports, Einrichtung und Konfigurationsbeispiele
summary: Matrix-Unterstützungsstatus, Einrichtung und Konfigurationsbeispiele
title: Matrix
x-i18n:
generated_at: "2026-04-15T06:21:25Z"
generated_at: "2026-04-15T19:41:41Z"
model: gpt-5.4
provider: openai
source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8
source_hash: bd730bb9d0c8a548ee48b20931b3222e9aa1e6e95f1390b0c236645e03f3576d
source_path: channels/matrix.md
workflow: 15
---
# Matrix
Matrix ist ein gebündeltes Kanal-Plugin für OpenClaw.
Es verwendet das offizielle `matrix-js-sdk` und unterstützt Direktnachrichten, Räume, Threads, Medien, Reaktionen, Umfragen, Standort und E2EE.
Matrix ist ein gebündeltes Channel-Plugin für OpenClaw.
Es verwendet das offizielle `matrix-js-sdk` und unterstützt DMs, Räume, Threads, Medien, Reaktionen, Umfragen, Standort und E2EE.
## Gebündeltes Plugin
Matrix wird in aktuellen OpenClaw-Releases als gebündeltes Plugin mitgeliefert, daher
Matrix wird in aktuellen OpenClaw-Releases als gebündeltes Plugin ausgeliefert, daher
benötigen normale paketierte Builds keine separate Installation.
Wenn du einen älteren Build oder eine benutzerdefinierte Installation verwendest, die Matrix ausschließt, installiere
@ -43,14 +43,14 @@ Siehe [Plugins](/de/tools/plugin) für Plugin-Verhalten und Installationsregeln.
## Einrichtung
1. Stelle sicher, dass das Matrix-Plugin verfügbar ist.
- Aktuelle paketierte OpenClaw-Releases enthalten es bereits.
- Ältere/benutzerdefinierte Installationen können es mit den obigen Befehlen manuell hinzufügen.
- Aktuelle paketierte OpenClaw-Releases enthalten es bereits gebündelt.
- Ältere/benutzerdefinierte Installationen können es manuell mit den obigen Befehlen hinzufügen.
2. Erstelle ein Matrix-Konto auf deinem Homeserver.
3. Konfiguriere `channels.matrix` mit entweder:
- `homeserver` + `accessToken`, oder
- `homeserver` + `userId` + `password`.
4. Starte das Gateway neu.
5. Starte eine Direktnachricht mit dem Bot oder lade ihn in einen Raum ein.
5. Starte eine DM mit dem Bot oder lade ihn in einen Raum ein.
- Neue Matrix-Einladungen funktionieren nur, wenn `channels.matrix.autoJoin` sie zulässt.
Interaktive Einrichtungswege:
@ -64,24 +64,24 @@ Der Matrix-Assistent fragt nach:
- Homeserver-URL
- Authentifizierungsmethode: Access Token oder Passwort
- Benutzer-ID (nur Passwort-Authentifizierung)
- optionalem Gerätenamen
- Benutzer-ID (nur bei Passwort-Authentifizierung)
- optionaler Gerätename
- ob E2EE aktiviert werden soll
- ob Raumzugriff und automatisches Beitreten bei Einladungen konfiguriert werden sollen
- ob Raumzugriff und automatisches Beitreten zu Einladungen konfiguriert werden sollen
Wichtige Verhaltensweisen des Assistenten:
- Wenn Matrix-Authentifizierungs-Umgebungsvariablen bereits vorhanden sind und für dieses Konto noch keine Authentifizierung in der Konfiguration gespeichert ist, bietet der Assistent eine Umgebungsvariablen-Verknüpfung an, damit die Authentifizierung in Umgebungsvariablen bleiben kann.
- Kontonamen werden zur Konto-ID normalisiert. Zum Beispiel wird aus `Ops Bot` `ops-bot`.
- Einträge in der DM-Allowlist akzeptieren `@user:server` direkt; Anzeigenamen funktionieren nur, wenn die Live-Verzeichnissuche genau eine Übereinstimmung findet.
- Einträge in der Raum-Allowlist akzeptieren Raum-IDs und Aliasse direkt. Bevorzuge `!room:server` oder `#alias:server`; nicht aufgelöste Namen werden zur Laufzeit von der Allowlist-Auflösung ignoriert.
- Im Allowlist-Modus für automatisches Beitreten bei Einladungen nur stabile Einladungsziele verwenden: `!roomId:server`, `#alias:server` oder `*`. Einfache Raumnamen werden abgelehnt.
- Wenn Matrix-Auth-Umgebungsvariablen bereits vorhanden sind und für dieses Konto noch keine Authentifizierung in der Konfiguration gespeichert ist, bietet der Assistent eine Umgebungsvariablen-Verknüpfung an, um die Authentifizierung in Umgebungsvariablen zu belassen.
- Kontonamen werden zur Konto-ID normalisiert. Zum Beispiel wird `Ops Bot` zu `ops-bot`.
- DM-Allowlist-Einträge akzeptieren `@user:server` direkt; Anzeigenamen funktionieren nur, wenn die Live-Verzeichnissuche genau einen Treffer findet.
- Raum-Allowlist-Einträge akzeptieren Raum-IDs und Aliase direkt. Bevorzuge `!room:server` oder `#alias:server`; nicht aufgelöste Namen werden zur Laufzeit von der Allowlist-Auflösung ignoriert.
- Im Allowlist-Modus für automatisches Beitreten zu Einladungen nur stabile Einladungsziele verwenden: `!roomId:server`, `#alias:server` oder `*`. Einfache Raumnamen werden abgelehnt.
- Um Raumnamen vor dem Speichern aufzulösen, verwende `openclaw channels resolve --channel matrix "Project Room"`.
<Warning>
`channels.matrix.autoJoin` ist standardmäßig auf `off` gesetzt.
Wenn du es nicht setzt, tritt der Bot eingeladenen Räumen oder neuen DM-artigen Einladungen nicht bei, daher erscheint er nicht in neuen Gruppen oder eingeladenen DMs, außer du trittst zuerst manuell bei.
Wenn du es nicht setzt, tritt der Bot eingeladenen Räumen oder neuen DM-ähnlichen Einladungen nicht bei und erscheint daher nicht in neuen Gruppen oder eingeladenen DMs, es sei denn, du trittst zuerst manuell bei.
Setze `autoJoin: "allowlist"` zusammen mit `autoJoinAllowlist`, um einzuschränken, welche Einladungen akzeptiert werden, oder setze `autoJoin: "always"`, wenn er jeder Einladung beitreten soll.
@ -133,7 +133,7 @@ Minimale tokenbasierte Einrichtung:
}
```
Passwortbasierte Einrichtung (Token wird nach der Anmeldung zwischengespeichert):
Passwortbasierte Einrichtung (Token wird nach dem Login zwischengespeichert):
```json5
{
@ -151,9 +151,9 @@ Passwortbasierte Einrichtung (Token wird nach der Anmeldung zwischengespeichert)
Matrix speichert zwischengespeicherte Anmeldedaten in `~/.openclaw/credentials/matrix/`.
Das Standardkonto verwendet `credentials.json`; benannte Konten verwenden `credentials-<account>.json`.
Wenn dort zwischengespeicherte Anmeldedaten vorhanden sind, behandelt OpenClaw Matrix für Einrichtung, Doctor und Kanalstatus-Erkennung als konfiguriert, auch wenn die aktuelle Authentifizierung nicht direkt in der Konfiguration gesetzt ist.
Wenn dort zwischengespeicherte Anmeldedaten vorhanden sind, behandelt OpenClaw Matrix für Setup, doctor und Channel-Status-Erkennung als konfiguriert, auch wenn die aktuelle Authentifizierung nicht direkt in der Konfiguration gesetzt ist.
Entsprechende Umgebungsvariablen (werden verwendet, wenn der Konfigurationsschlüssel nicht gesetzt ist):
Äquivalente Umgebungsvariablen (werden verwendet, wenn der Konfigurationsschlüssel nicht gesetzt ist):
- `MATRIX_HOMESERVER`
- `MATRIX_ACCESS_TOKEN`
@ -162,7 +162,7 @@ Entsprechende Umgebungsvariablen (werden verwendet, wenn der Konfigurationsschl
- `MATRIX_DEVICE_ID`
- `MATRIX_DEVICE_NAME`
Für Nicht-Standardkonten verwende kontobezogene Umgebungsvariablen:
Für Nicht-Standardkonten verwende kontoabhängige Umgebungsvariablen:
- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
@ -181,10 +181,10 @@ Für die normalisierte Konto-ID `ops-bot` verwende:
- `MATRIX_OPS_X2D_BOT_HOMESERVER`
- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN`
Matrix maskiert Satzzeichen in Konto-IDs, damit kontobezogene Umgebungsvariablen kollisionsfrei bleiben.
Zum Beispiel wird `-` zu `_X2D_`, sodass `ops-prod` auf `MATRIX_OPS_X2D_PROD_*` abgebildet wird.
Matrix maskiert Satzzeichen in Konto-IDs, damit kontoabhängige Umgebungsvariablen kollisionsfrei bleiben.
Zum Beispiel wird `-` zu `_X2D_`, daher wird `ops-prod` zu `MATRIX_OPS_X2D_PROD_*`.
Der interaktive Assistent bietet die Umgebungsvariablen-Verknüpfung nur an, wenn diese Authentifizierungs-Umgebungsvariablen bereits vorhanden sind und für das ausgewählte Konto noch keine Matrix-Authentifizierung in der Konfiguration gespeichert ist.
Der interaktive Assistent bietet die Umgebungsvariablen-Verknüpfung nur an, wenn diese Auth-Umgebungsvariablen bereits vorhanden sind und für das ausgewählte Konto noch keine Matrix-Authentifizierung in der Konfiguration gespeichert ist.
## Konfigurationsbeispiel
@ -223,17 +223,18 @@ Dies ist eine praktische Basiskonfiguration mit DM-Pairing, Raum-Allowlist und a
}
```
`autoJoin` gilt für alle Matrix-Einladungen, einschließlich DM-artiger Einladungen. OpenClaw kann einen eingeladenen
Raum zum Zeitpunkt der Einladung nicht zuverlässig als DM oder Gruppe klassifizieren, daher laufen alle Einladungen zuerst über `autoJoin`.
`dm.policy` gilt, nachdem der Bot beigetreten ist und der Raum als DM klassifiziert wurde.
`autoJoin` gilt für alle Matrix-Einladungen, einschließlich DM-ähnlicher Einladungen. OpenClaw kann einen
eingeladenen Raum zum Zeitpunkt der Einladung nicht zuverlässig als DM oder Gruppe
klassifizieren, daher laufen alle Einladungen zuerst über `autoJoin`.
`dm.policy` wird angewendet, nachdem der Bot beigetreten ist und der Raum als DM klassifiziert wurde.
## Streaming-Vorschauen
Reply-Streaming für Matrix ist optional.
Setze `channels.matrix.streaming` auf `"partial"`, wenn OpenClaw eine einzelne Live-Vorschau
der Antwort senden, diese Vorschau während der Textgenerierung durch das Modell direkt bearbeiten und sie dann
abschließen soll, sobald die Antwort fertig ist:
Setze `channels.matrix.streaming` auf `"partial"`, wenn OpenClaw eine einzelne Live-Vorschau-Antwort senden,
diese Vorschau während der Textgenerierung durch das Modell an Ort und Stelle bearbeiten und sie dann abschließen soll, wenn die
Antwort fertig ist:
```json5
{
@ -246,37 +247,37 @@ abschließen soll, sobald die Antwort fertig ist:
```
- `streaming: "off"` ist die Standardeinstellung. OpenClaw wartet auf die endgültige Antwort und sendet sie einmal.
- `streaming: "partial"` erstellt eine bearbeitbare Vorschau-Nachricht für den aktuellen Assistant-Block unter Verwendung normaler Matrix-Textnachrichten. Dadurch bleibt das ältere Benachrichtigungsverhalten von Matrix mit Vorschau zuerst erhalten, sodass Standard-Clients möglicherweise beim ersten gestreamten Vorschautext statt beim fertigen Block benachrichtigen.
- `streaming: "quiet"` erstellt eine bearbeitbare stille Vorschau-Mitteilung für den aktuellen Assistant-Block. Verwende dies nur, wenn du zusätzlich Empfänger-Push-Regeln für abgeschlossene Vorschau-Bearbeitungen konfigurierst.
- `blockStreaming: true` aktiviert separate Matrix-Fortschrittsnachrichten. Wenn Vorschau-Streaming aktiviert ist, behält Matrix den Live-Entwurf für den aktuellen Block bei und belässt abgeschlossene Blöcke als separate Nachrichten.
- Wenn Vorschau-Streaming aktiviert ist und `blockStreaming` deaktiviert ist, bearbeitet Matrix den Live-Entwurf direkt und schließt dasselbe Ereignis ab, wenn der Block oder Turn beendet ist.
- Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Ereignis passt, beendet OpenClaw das Vorschau-Streaming und greift auf normale endgültige Zustellung zurück.
- `streaming: "partial"` erstellt eine bearbeitbare Vorschau-Nachricht für den aktuellen Assistentenblock mit normalen Matrix-Textnachrichten. Dadurch bleibt das ältere benachrichtigungsorientierte Vorschau-zuerst-Verhalten von Matrix erhalten, sodass Standard-Clients möglicherweise beim ersten gestreamten Vorschautext statt beim fertigen Block benachrichtigen.
- `streaming: "quiet"` erstellt einen bearbeitbaren unauffälligen Vorschauhinweis für den aktuellen Assistentenblock. Verwende dies nur, wenn du zusätzlich Push-Regeln für Empfänger für abgeschlossene Vorschau-Bearbeitungen konfigurierst.
- `blockStreaming: true` aktiviert separate Matrix-Fortschrittsnachrichten. Wenn Vorschau-Streaming aktiviert ist, behält Matrix den Live-Entwurf für den aktuellen Block bei und lässt abgeschlossene Blöcke als separate Nachrichten bestehen.
- Wenn Vorschau-Streaming aktiviert und `blockStreaming` deaktiviert ist, bearbeitet Matrix den Live-Entwurf an Ort und Stelle und schließt dasselbe Ereignis ab, wenn der Block oder Turn endet.
- Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Ereignis passt, beendet OpenClaw das Vorschau-Streaming und fällt auf normale endgültige Zustellung zurück.
- Medienantworten senden Anhänge weiterhin normal. Wenn eine veraltete Vorschau nicht mehr sicher wiederverwendet werden kann, entfernt OpenClaw sie vor dem Senden der endgültigen Medienantwort.
- Vorschau-Bearbeitungen verursachen zusätzliche Matrix-API-Aufrufe. Lasse Streaming deaktiviert, wenn du das konservativste Verhalten bei Ratenbegrenzungen möchtest.
- Vorschau-Bearbeitungen verursachen zusätzliche Matrix-API-Aufrufe. Lasse Streaming deaktiviert, wenn du das konservativste Rate-Limit-Verhalten möchtest.
`blockStreaming` aktiviert Entwurfsvorschauen nicht von selbst.
Verwende `streaming: "partial"` oder `streaming: "quiet"` für Vorschau-Bearbeitungen; füge dann `blockStreaming: true` nur hinzu, wenn abgeschlossene Assistant-Blöcke zusätzlich als separate Fortschrittsnachrichten sichtbar bleiben sollen.
Verwende `streaming: "partial"` oder `streaming: "quiet"` für Vorschau-Bearbeitungen; füge dann `blockStreaming: true` nur hinzu, wenn du außerdem möchtest, dass abgeschlossene Assistentenblöcke als separate Fortschrittsnachrichten sichtbar bleiben.
Wenn du Standard-Matrix-Benachrichtigungen ohne benutzerdefinierte Push-Regeln benötigst, verwende `streaming: "partial"` für Vorschau-zuerst-Verhalten oder lasse `streaming` für reine Endzustellung deaktiviert. Mit `streaming: "off"`:
Wenn du Matrix-Standardbenachrichtigungen ohne benutzerdefinierte Push-Regeln benötigst, verwende `streaming: "partial"` für Vorschau-zuerst-Verhalten oder lasse `streaming` deaktiviert, um nur endgültige Zustellung zu erhalten. Mit `streaming: "off"`:
- `blockStreaming: true` sendet jeden abgeschlossenen Block als normale benachrichtigende Matrix-Nachricht.
- `blockStreaming: false` sendet nur die endgültige abgeschlossene Antwort als normale benachrichtigende Matrix-Nachricht.
### Selbst gehostete Push-Regeln für stille abgeschlossene Vorschauen
### Selbstgehostete Push-Regeln für unauffällige abgeschlossene Vorschauen
Wenn du deine eigene Matrix-Infrastruktur betreibst und stille Vorschauen erst dann benachrichtigen sollen, wenn ein Block oder die
Wenn du deine eigene Matrix-Infrastruktur betreibst und unauffällige Vorschauen nur dann benachrichtigen sollen, wenn ein Block oder eine
endgültige Antwort abgeschlossen ist, setze `streaming: "quiet"` und füge eine benutzerspezifische Push-Regel für abgeschlossene Vorschau-Bearbeitungen hinzu.
Dies ist normalerweise eine Einrichtung pro Empfängerbenutzer, keine globale Konfigurationsänderung am Homeserver:
Dies ist normalerweise eine Einrichtung pro Empfängerbenutzer, keine globale Konfigurationsänderung des Homeservers:
Kurzübersicht vor dem Start:
Kurzübersicht, bevor du beginnst:
- Empfängerbenutzer = die Person, die die Benachrichtigung erhalten soll
- Bot-Benutzer = das OpenClaw-Matrix-Konto, das die Antwort sendet
- verwende für die folgenden API-Aufrufe das Access Token des Empfängerbenutzers
- gleiche `sender` in der Push-Regel mit der vollständigen MXID des Bot-Benutzers ab
1. Konfiguriere OpenClaw für stille Vorschauen:
1. Konfiguriere OpenClaw so, dass unauffällige Vorschauen verwendet werden:
```json5
{
@ -288,13 +289,13 @@ Kurzübersicht vor dem Start:
}
```
2. Stelle sicher, dass das Empfängerkonto bereits normale Matrix-Push-Benachrichtigungen erhält. Regeln für stille Vorschauen
2. Stelle sicher, dass das Empfängerkonto bereits normale Matrix-Push-Benachrichtigungen erhält. Regeln für unauffällige Vorschauen
funktionieren nur, wenn dieser Benutzer bereits funktionierende Pusher/Geräte hat.
3. Besorge das Access Token des Empfängerbenutzers.
3. Hole das Access Token des Empfängerbenutzers.
- Verwende das Token des empfangenden Benutzers, nicht das Token des Bots.
- Ein vorhandenes Client-Sitzungstoken wiederzuverwenden ist normalerweise am einfachsten.
- Wenn du ein neues Token erstellen musst, kannst du dich über die standardmäßige Matrix Client-Server-API anmelden:
- Die Wiederverwendung eines vorhandenen Client-Sitzungstokens ist normalerweise am einfachsten.
- Wenn du ein neues Token erzeugen musst, kannst du dich über die Standard-Matrix-Client-Server-API anmelden:
```bash
curl -sS -X POST \
@ -310,7 +311,7 @@ curl -sS -X POST \
}'
```
4. Prüfe, ob das Empfängerkonto bereits Pusher hat:
4. Verifiziere, dass das Empfängerkonto bereits Pusher hat:
```bash
curl -sS \
@ -318,10 +319,10 @@ curl -sS \
"https://matrix.example.org/_matrix/client/v3/pushers"
```
Wenn dies keine aktiven Pusher/Geräte zurückgibt, behebe zuerst die normalen Matrix-Benachrichtigungen, bevor du die
unten stehende OpenClaw-Regel hinzufügst.
Wenn dies keine aktiven Pusher/Geräte zurückgibt, behebe zuerst normale Matrix-Benachrichtigungen, bevor du die
untenstehende OpenClaw-Regel hinzufügst.
OpenClaw markiert abgeschlossene textbasierte Vorschau-Bearbeitungen mit:
OpenClaw markiert abgeschlossene Vorschau-Bearbeitungen nur mit Text mit:
```json
{
@ -361,23 +362,23 @@ curl -sS -X PUT \
Ersetze diese Werte, bevor du den Befehl ausführst:
- `https://matrix.example.org`: deine Homeserver-Basis-URL
- `https://matrix.example.org`: die Basis-URL deines Homeservers
- `$USER_ACCESS_TOKEN`: das Access Token des empfangenden Benutzers
- `openclaw-finalized-preview-botname`: eine für diesen Bot bei diesem empfangenden Benutzer eindeutige Regel-ID
- `openclaw-finalized-preview-botname`: eine Regel-ID, die für diesen Bot bei diesem empfangenden Benutzer eindeutig ist
- `@bot:example.org`: die MXID deines OpenClaw-Matrix-Bots, nicht die MXID des empfangenden Benutzers
Wichtig für Setups mit mehreren Bots:
- Push-Regeln werden über `ruleId` identifiziert. Wenn `PUT` erneut mit derselben Regel-ID ausgeführt wird, wird genau diese Regel aktualisiert.
- Wenn ein empfangender Benutzer für mehrere OpenClaw-Matrix-Bot-Konten Benachrichtigungen erhalten soll, erstelle eine Regel pro Bot mit jeweils einer eindeutigen Regel-ID für jede `sender`-Übereinstimmung.
- Push-Regeln werden über `ruleId` referenziert. Ein erneutes `PUT` mit derselben Regel-ID aktualisiert diese eine Regel.
- Wenn ein empfangender Benutzer für mehrere OpenClaw-Matrix-Bot-Konten benachrichtigt werden soll, erstelle eine Regel pro Bot mit einer eindeutigen Regel-ID für jede `sender`-Übereinstimmung.
- Ein einfaches Muster ist `openclaw-finalized-preview-<botname>`, zum Beispiel `openclaw-finalized-preview-ops` oder `openclaw-finalized-preview-support`.
Die Regel wird anhand des Ereignis-Absenders ausgewertet:
Die Regel wird gegen den Ereignisabsender ausgewertet:
- authentifiziere dich mit dem Token des empfangenden Benutzers
- gleiche `sender` mit der MXID des OpenClaw-Bots ab
6. Prüfe, ob die Regel vorhanden ist:
6. Verifiziere, dass die Regel existiert:
```bash
curl -sS \
@ -385,8 +386,8 @@ curl -sS \
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
```
7. Teste eine gestreamte Antwort. Im stillen Modus sollte der Raum eine stille Entwurfs-Vorschau anzeigen, und die endgültige
direkte Bearbeitung sollte benachrichtigen, sobald der Block oder Turn abgeschlossen ist.
7. Teste eine gestreamte Antwort. Im leisen Modus sollte der Raum eine leise Entwurfsvorschau anzeigen und die endgültige
Bearbeitung an Ort und Stelle sollte benachrichtigen, sobald der Block oder Turn abgeschlossen ist.
Wenn du die Regel später entfernen musst, lösche dieselbe Regel-ID mit dem Token des empfangenden Benutzers:
@ -398,9 +399,9 @@ curl -sS -X DELETE \
Hinweise:
- Erstelle die Regel mit dem Access Token des empfangenden Benutzers, nicht mit dem des Bots.
- Neue benutzerdefinierte `override`-Regeln werden vor den standardmäßigen Unterdrückungsregeln eingefügt, daher ist kein zusätzlicher Ordnungsparameter erforderlich.
- Dies betrifft nur reine Text-Vorschau-Bearbeitungen, die OpenClaw sicher direkt abschließen kann. Medien-Fallbacks und Fallbacks für veraltete Vorschauen verwenden weiterhin die normale Matrix-Zustellung.
- Erstelle die Regel mit dem Access Token des empfangenden Benutzers, nicht mit dem Token des Bots.
- Neue benutzerdefinierte `override`-Regeln werden vor den standardmäßigen Unterdrückungsregeln eingefügt, daher ist kein zusätzlicher Reihenfolgeparameter erforderlich.
- Dies betrifft nur Vorschau-Bearbeitungen nur mit Text, die OpenClaw sicher an Ort und Stelle abschließen kann. Medien-Fallbacks und Fallbacks für veraltete Vorschauen verwenden weiterhin die normale Matrix-Zustellung.
- Wenn `GET /_matrix/client/v3/pushers` keine Pusher anzeigt, hat der Benutzer für dieses Konto/Gerät noch keine funktionierende Matrix-Push-Zustellung.
#### Synapse
@ -409,14 +410,14 @@ Für Synapse reicht die obige Einrichtung normalerweise bereits aus:
- Es ist keine spezielle Änderung an `homeserver.yaml` für abgeschlossene OpenClaw-Vorschau-Benachrichtigungen erforderlich.
- Wenn deine Synapse-Bereitstellung bereits normale Matrix-Push-Benachrichtigungen sendet, sind das Benutzertoken und der obige `pushrules`-Aufruf der wichtigste Einrichtungsschritt.
- Wenn du Synapse hinter einem Reverse Proxy oder mit Workern betreibst, stelle sicher, dass `/_matrix/client/.../pushrules/` Synapse korrekt erreicht.
- Wenn du Synapse-Worker verwendest, stelle sicher, dass die Pusher fehlerfrei laufen. Die Push-Zustellung wird vom Hauptprozess oder von `synapse.app.pusher` / konfigurierten Pusher-Workern übernommen.
- Wenn du Synapse hinter einem Reverse-Proxy oder mit Workern betreibst, stelle sicher, dass `/_matrix/client/.../pushrules/` Synapse korrekt erreicht.
- Wenn du Synapse-Worker betreibst, stelle sicher, dass die Pusher fehlerfrei arbeiten. Die Push-Zustellung wird vom Hauptprozess oder von `synapse.app.pusher` / konfigurierten Pusher-Workern übernommen.
#### Tuwunel
Für Tuwunel verwende denselben Einrichtungsablauf und denselben `push-rule`-API-Aufruf wie oben gezeigt:
Für Tuwunel verwende denselben Einrichtungsablauf und denselben oben gezeigten `pushrules`-API-Aufruf:
- Für den Marker der abgeschlossenen Vorschau selbst ist keine Tuwunel-spezifische Konfiguration erforderlich.
- Für die Markierung der abgeschlossenen Vorschau selbst ist keine Tuwunel-spezifische Konfiguration erforderlich.
- Wenn normale Matrix-Benachrichtigungen für diesen Benutzer bereits funktionieren, sind das Benutzertoken und der obige `pushrules`-Aufruf der wichtigste Einrichtungsschritt.
- Wenn Benachrichtigungen zu verschwinden scheinen, während der Benutzer auf einem anderen Gerät aktiv ist, prüfe, ob `suppress_push_when_active` aktiviert ist. Tuwunel hat diese Option in Tuwunel 1.4.2 am 12. September 2025 hinzugefügt, und sie kann Pushes an andere Geräte absichtlich unterdrücken, während ein Gerät aktiv ist.
@ -424,7 +425,7 @@ Für Tuwunel verwende denselben Einrichtungsablauf und denselben `push-rule`-API
Standardmäßig werden Matrix-Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten ignoriert.
Verwende `allowBots`, wenn du absichtlich Matrix-Verkehr zwischen Agents erlauben möchtest:
Verwende `allowBots`, wenn du absichtlich Matrix-Verkehr zwischen Agents möchtest:
```json5
{
@ -442,16 +443,16 @@ Verwende `allowBots`, wenn du absichtlich Matrix-Verkehr zwischen Agents erlaube
```
- `allowBots: true` akzeptiert Nachrichten von anderen konfigurierten Matrix-Bot-Konten in erlaubten Räumen und DMs.
- `allowBots: "mentions"` akzeptiert diese Nachrichten in Räumen nur dann, wenn dieser Bot darin sichtbar erwähnt wird. DMs sind weiterhin erlaubt.
- `allowBots: "mentions"` akzeptiert diese Nachrichten in Räumen nur dann, wenn sie diesen Bot sichtbar erwähnen. DMs sind weiterhin erlaubt.
- `groups.<room>.allowBots` überschreibt die Einstellung auf Kontoebene für einen einzelnen Raum.
- OpenClaw ignoriert weiterhin Nachrichten von derselben Matrix-Benutzer-ID, um Selbstantwort-Schleifen zu vermeiden.
- Matrix stellt hier kein natives Bot-Flag bereit; OpenClaw behandelt „von Bot verfasst“ als „von einem anderen konfigurierten Matrix-Konto auf diesem OpenClaw-Gateway gesendet“.
- OpenClaw ignoriert weiterhin Nachrichten von derselben Matrix-Benutzer-ID, um Schleifen durch Selbstantworten zu vermeiden.
- Matrix bietet hier kein natives Bot-Flag; OpenClaw behandelt „von Bots verfasst“ als „von einem anderen konfigurierten Matrix-Konto auf diesem OpenClaw-Gateway gesendet“.
Verwende strikte Raum-Allowlists und Erwähnungsanforderungen, wenn du Bot-zu-Bot-Verkehr in gemeinsam genutzten Räumen aktivierst.
Verwende strikte Raum-Allowlists und Erwähnungspflichten, wenn du Bot-zu-Bot-Verkehr in gemeinsam genutzten Räumen aktivierst.
## Verschlüsselung und Verifizierung
In verschlüsselten (E2EE-)Räumen verwenden ausgehende Bildereignisse `thumbnail_file`, sodass Bildvorschauen zusammen mit dem vollständigen Anhang verschlüsselt werden. Unverschlüsselte Räume verwenden weiterhin einfaches `thumbnail_url`. Es ist keine Konfiguration erforderlich — das Plugin erkennt den E2EE-Status automatisch.
In verschlüsselten (E2EE-)Räumen verwenden ausgehende Bildereignisse `thumbnail_file`, sodass Bildvorschauen zusammen mit dem vollständigen Anhang verschlüsselt werden. Unverschlüsselte Räume verwenden weiterhin einfaches `thumbnail_url`. Keine Konfiguration erforderlich — das Plugin erkennt den E2EE-Status automatisch.
Verschlüsselung aktivieren:
@ -475,13 +476,13 @@ Verifizierungsstatus prüfen:
openclaw matrix verify status
```
Ausführlicher Status (vollständige Diagnose):
Ausführlicher Status (vollständige Diagnosen):
```bash
openclaw matrix verify status --verbose
```
Den gespeicherten Recovery Key in maschinenlesbarer Ausgabe einschließen:
Den gespeicherten Wiederherstellungsschlüssel in maschinenlesbarer Ausgabe einbeziehen:
```bash
openclaw matrix verify status --include-recovery-key --json
@ -493,19 +494,19 @@ Cross-Signing- und Verifizierungsstatus initialisieren:
openclaw matrix verify bootstrap
```
Ausführliche Bootstrap-Diagnose:
Ausführliche Bootstrap-Diagnosen:
```bash
openclaw matrix verify bootstrap --verbose
```
Vor dem Bootstrap eine neue Cross-Signing-Identität erzwingen:
Vor dem Bootstrap ein vollständiges Zurücksetzen der Cross-Signing-Identität erzwingen:
```bash
openclaw matrix verify bootstrap --force-reset-cross-signing
```
Dieses Gerät mit einem Recovery Key verifizieren:
Dieses Gerät mit einem Wiederherstellungsschlüssel verifizieren:
```bash
openclaw matrix verify device "<your-recovery-key>"
@ -517,25 +518,25 @@ Ausführliche Details zur Geräteverifizierung:
openclaw matrix verify device "<your-recovery-key>" --verbose
```
Zustand des Raumschlüssel-Backups prüfen:
Integrität des Raumschlüssel-Backups prüfen:
```bash
openclaw matrix verify backup status
```
Ausführliche Diagnose zum Zustand des Backups:
Ausführliche Diagnosen zur Backup-Integrität:
```bash
openclaw matrix verify backup status --verbose
```
Raumschlüssel aus einem Server-Backup wiederherstellen:
Raumschlüssel aus dem Server-Backup wiederherstellen:
```bash
openclaw matrix verify backup restore
```
Ausführliche Diagnose zur Wiederherstellung:
Ausführliche Diagnosen zur Wiederherstellung:
```bash
openclaw matrix verify backup restore --verbose
@ -549,12 +550,12 @@ zukünftige Kaltstarts den neuen Backup-Schlüssel laden können:
openclaw matrix verify backup reset --yes
```
Alle `verify`-Befehle sind standardmäßig kompakt (einschließlich stiller interner SDK-Protokollierung) und zeigen nur mit `--verbose` detaillierte Diagnosen an.
Verwende `--json` für vollständige maschinenlesbare Ausgabe bei der Skripterstellung.
Alle `verify`-Befehle sind standardmäßig knapp gehalten (einschließlich stiller interner SDK-Protokollierung) und zeigen ausführliche Diagnosen nur mit `--verbose`.
Verwende `--json` für vollständige maschinenlesbare Ausgabe in Skripten.
In Setups mit mehreren Konten verwenden Matrix-CLI-Befehle implizit das standardmäßige Matrix-Konto, sofern du nicht `--account <id>` übergibst.
Wenn du mehrere benannte Konten konfigurierst, setze zuerst `channels.matrix.defaultAccount`, andernfalls werden diese impliziten CLI-Operationen angehalten und verlangen, dass du ein Konto explizit auswählst.
Verwende `--account`, wenn Verifizierungs- oder Geräteoperationen gezielt auf ein benanntes Konto angewendet werden sollen:
In Multi-Account-Setups verwenden Matrix-CLI-Befehle implizit das Matrix-Standardkonto, sofern du nicht `--account <id>` übergibst.
Wenn du mehrere benannte Konten konfigurierst, setze zuerst `channels.matrix.defaultAccount`, sonst werden diese impliziten CLI-Operationen angehalten und fordern dich auf, ein Konto explizit auszuwählen.
Verwende `--account`, wann immer Verifizierungs- oder Geräteoperationen ausdrücklich auf ein benanntes Konto zielen sollen:
```bash
openclaw matrix verify status --account assistant
@ -562,18 +563,18 @@ openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
```
Wenn Verschlüsselung für ein benanntes Konto deaktiviert oder nicht verfügbar ist, zeigen Matrix-Warnungen und Verifizierungsfehler auf den Konfigurationsschlüssel dieses Kontos, zum Beispiel `channels.matrix.accounts.assistant.encryption`.
Wenn Verschlüsselung für ein benanntes Konto deaktiviert oder nicht verfügbar ist, verweisen Matrix-Warnungen und Verifizierungsfehler auf den Konfigurationsschlüssel dieses Kontos, zum Beispiel `channels.matrix.accounts.assistant.encryption`.
### Was „verifiziert“ bedeutet
OpenClaw behandelt dieses Matrix-Gerät nur dann als verifiziert, wenn es durch deine eigene Cross-Signing-Identität verifiziert wurde.
In der Praxis zeigt `openclaw matrix verify status --verbose` drei Vertrauenssignale an:
- `Locally trusted`: Dieses Gerät wird nur vom aktuellen Client als vertrauenswürdig eingestuft
- `Locally trusted`: Dieses Gerät ist nur durch den aktuellen Client als vertrauenswürdig markiert
- `Cross-signing verified`: Das SDK meldet das Gerät als durch Cross-Signing verifiziert
- `Signed by owner`: Das Gerät ist mit deinem eigenen Self-Signing-Schlüssel signiert
`Verified by owner` wird nur dann zu `yes`, wenn Cross-Signing-Verifizierung oder Signierung durch den Eigentümer vorhanden ist.
`Verified by owner` wird nur dann zu `yes`, wenn Cross-Signing-Verifizierung oder Owner-Signing vorhanden ist.
Lokales Vertrauen allein reicht nicht aus, damit OpenClaw das Gerät als vollständig verifiziert behandelt.
### Was Bootstrap macht
@ -581,24 +582,23 @@ Lokales Vertrauen allein reicht nicht aus, damit OpenClaw das Gerät als vollst
`openclaw matrix verify bootstrap` ist der Reparatur- und Einrichtungsbefehl für verschlüsselte Matrix-Konten.
Er führt der Reihe nach Folgendes aus:
- initialisiert Secret Storage und verwendet nach Möglichkeit einen vorhandenen Recovery Key erneut
- initialisiert den Secret Storage und verwendet nach Möglichkeit einen vorhandenen Wiederherstellungsschlüssel erneut
- initialisiert Cross-Signing und lädt fehlende öffentliche Cross-Signing-Schlüssel hoch
- versucht, das aktuelle Gerät zu markieren und per Cross-Signing zu signieren
- erstellt ein neues serverseitiges Raumschlüssel-Backup, falls noch keines vorhanden ist
- erstellt ein neues serverseitiges Raumschlüssel-Backup, falls noch keines existiert
Wenn der Homeserver interaktive Authentifizierung zum Hochladen von Cross-Signing-Schlüsseln verlangt, versucht OpenClaw das Hochladen zuerst ohne Authentifizierung, dann mit `m.login.dummy` und anschließend mit `m.login.password`, wenn `channels.matrix.password` konfiguriert ist.
Verwende `--force-reset-cross-signing` nur, wenn du die aktuelle Cross-Signing-Identität absichtlich verwerfen und eine neue erstellen möchtest.
Verwende `--force-reset-cross-signing` nur, wenn du absichtlich die aktuelle Cross-Signing-Identität verwerfen und eine neue erstellen möchtest.
Wenn du das aktuelle Raumschlüssel-Backup absichtlich verwerfen und eine neue
Backup-Basis für zukünftige Nachrichten erstellen möchtest, verwende `openclaw matrix verify backup reset --yes`.
Tu dies nur, wenn du akzeptierst, dass nicht wiederherstellbarer alter verschlüsselter Verlauf
nicht verfügbar bleibt und dass OpenClaw den Secret Storage möglicherweise neu erstellt, wenn das aktuelle Backup-Geheimnis
nicht sicher geladen werden kann.
Wenn du absichtlich das aktuelle Raumschlüssel-Backup verwerfen und eine neue
Backup-Basis für zukünftige Nachrichten starten möchtest, verwende `openclaw matrix verify backup reset --yes`.
Tue dies nur, wenn du akzeptierst, dass nicht wiederherstellbarer alter verschlüsselter Verlauf
weiterhin nicht verfügbar bleibt und dass OpenClaw den Secret Storage möglicherweise neu erstellt, wenn das aktuelle Backup-Secret nicht sicher geladen werden kann.
### Neue Backup-Basis
Wenn du die Funktion für zukünftige verschlüsselte Nachrichten erhalten und den Verlust nicht wiederherstellbaren alten Verlaufs akzeptieren möchtest, führe diese Befehle in dieser Reihenfolge aus:
Wenn du sicherstellen möchtest, dass zukünftige verschlüsselte Nachrichten weiterhin funktionieren, und akzeptierst, nicht wiederherstellbaren alten Verlauf zu verlieren, führe diese Befehle in dieser Reihenfolge aus:
```bash
openclaw matrix verify backup reset --yes
@ -606,24 +606,25 @@ openclaw matrix verify backup status --verbose
openclaw matrix verify status
```
Füge zu jedem Befehl `--account <id>` hinzu, wenn du gezielt ein benanntes Matrix-Konto ansprechen möchtest.
Füge `--account <id>` zu jedem Befehl hinzu, wenn du explizit ein benanntes Matrix-Konto ansprechen möchtest.
### Verhalten beim Start
### Startverhalten
Wenn `encryption: true` gesetzt ist, verwendet Matrix standardmäßig `startupVerification` mit dem Wert `"if-unverified"`.
Beim Start fordert Matrix, wenn dieses Gerät noch nicht verifiziert ist, die Selbstverifizierung in einem anderen Matrix-Client an,
überspringt doppelte Anfragen, solange bereits eine aussteht, und wendet vor einem erneuten Versuch nach Neustarts eine lokale Abkühlzeit an.
Fehlgeschlagene Anfrageversuche werden standardmäßig früher erneut versucht als erfolgreich erstellte Anfragen.
Beim Start fordert Matrix, falls dieses Gerät noch nicht verifiziert ist, in einem anderen Matrix-Client zur Selbstverifizierung auf,
überspringt doppelte Anforderungen, solange bereits eine aussteht, und verwendet vor einem erneuten Versuch nach Neustarts eine lokale Abklingzeit.
Fehlgeschlagene Anforderungsversuche werden standardmäßig früher erneut versucht als eine erfolgreiche Erstellung der Anforderung.
Setze `startupVerification: "off"`, um automatische Anfragen beim Start zu deaktivieren, oder passe `startupVerificationCooldownHours`
an, wenn du ein kürzeres oder längeres Wiederholungsfenster möchtest.
Beim Start wird außerdem automatisch ein konservativer Crypto-Bootstrap-Durchlauf ausgeführt.
Dieser Durchlauf versucht zuerst, den aktuellen Secret Storage und die aktuelle Cross-Signing-Identität wiederzuverwenden, und vermeidet ein Zurücksetzen von Cross-Signing, es sei denn, du führst explizit einen Bootstrap-Reparaturablauf aus.
Dieser Durchlauf versucht zuerst, den aktuellen Secret Storage und die aktuelle Cross-Signing-Identität wiederzuverwenden, und vermeidet ein Zurücksetzen von Cross-Signing, sofern du nicht ausdrücklich einen Bootstrap-Reparaturablauf ausführst.
Wenn beim Start ein defekter Bootstrap-Zustand gefunden wird und `channels.matrix.password` konfiguriert ist, kann OpenClaw einen strengeren Reparaturpfad versuchen.
Wenn beim Start dennoch ein fehlerhafter Bootstrap-Status erkannt wird, kann OpenClaw einen abgesicherten Reparaturpfad versuchen, selbst wenn `channels.matrix.password` nicht konfiguriert ist.
Wenn der Homeserver für diese Reparatur passwortbasierte UIA verlangt, protokolliert OpenClaw eine Warnung und hält den Start weiterhin nicht fatal, anstatt den Bot abzubrechen.
Wenn das aktuelle Gerät bereits vom Eigentümer signiert ist, bewahrt OpenClaw diese Identität, anstatt sie automatisch zurückzusetzen.
Siehe [Matrix migration](/de/install/migrating-matrix) für den vollständigen Upgrade-Ablauf, Einschränkungen, Recovery-Befehle und häufige Migrationsmeldungen.
Siehe [Matrix migration](/de/install/migrating-matrix) für den vollständigen Upgrade-Ablauf, Grenzen, Wiederherstellungsbefehle und häufige Migrationsmeldungen.
### Verifizierungshinweise
@ -631,46 +632,46 @@ Matrix veröffentlicht Hinweise zum Lebenszyklus der Verifizierung direkt im str
Dazu gehören:
- Hinweise zu Verifizierungsanfragen
- Hinweise darauf, dass die Verifizierung bereit ist (mit explizitem Hinweis „Per Emoji verifizieren“)
- Hinweise zur Verifizierungsbereitschaft (mit ausdrücklichem Hinweis „Per Emoji verifizieren“)
- Hinweise zum Start und Abschluss der Verifizierung
- SAS-Details (Emoji und Dezimalwerte), wenn verfügbar
- SAS-Details (Emoji und Dezimalzahl), wenn verfügbar
Eingehende Verifizierungsanfragen von einem anderen Matrix-Client werden von OpenClaw nachverfolgt und automatisch akzeptiert.
Bei Selbstverifizierungsabläufen startet OpenClaw außerdem automatisch den SAS-Ablauf, sobald die Emoji-Verifizierung verfügbar wird, und bestätigt die eigene Seite.
Bei Verifizierungsanfragen von einem anderen Matrix-Benutzer/Gerät akzeptiert OpenClaw die Anfrage automatisch und wartet dann darauf, dass der SAS-Ablauf normal fortgesetzt wird.
Du musst die Emoji- oder dezimalen SAS-Werte in deinem Matrix-Client weiterhin vergleichen und dort „Sie stimmen überein“ bestätigen, um die Verifizierung abzuschließen.
Eingehende Verifizierungsanfragen von einem anderen Matrix-Client werden von OpenClaw nachverfolgt und automatisch angenommen.
Bei Selbstverifizierungsabläufen startet OpenClaw den SAS-Ablauf auch automatisch, sobald die Emoji-Verifizierung verfügbar wird, und bestätigt die eigene Seite.
Bei Verifizierungsanfragen von einem anderen Matrix-Benutzer/-Gerät nimmt OpenClaw die Anfrage automatisch an und wartet dann darauf, dass der SAS-Ablauf normal fortgesetzt wird.
Du musst die Emoji- oder dezimale SAS dennoch in deinem Matrix-Client vergleichen und dort „Sie stimmen überein“ bestätigen, um die Verifizierung abzuschließen.
OpenClaw akzeptiert selbst initiierte doppelte Abläufe nicht blind automatisch. Beim Start wird das Erstellen einer neuen Anfrage übersprungen, wenn bereits eine Selbstverifizierungsanfrage aussteht.
OpenClaw akzeptiert selbst initiierte doppelte Abläufe nicht blind automatisch. Beim Start wird keine neue Anfrage erstellt, wenn bereits eine Selbstverifizierungsanfrage aussteht.
Hinweise des Verifizierungsprotokolls/Systems werden nicht an die Agent-Chat-Pipeline weitergeleitet und erzeugen daher kein `NO_REPLY`.
Hinweise zum Verifizierungsprotokoll/System werden nicht an die Agent-Chat-Pipeline weitergeleitet und erzeugen daher kein `NO_REPLY`.
### Gerätehygiene
Alte von OpenClaw verwaltete Matrix-Geräte können sich im Konto ansammeln und die Vertrauensbewertung in verschlüsselten Räumen schwerer nachvollziehbar machen.
Alte, von OpenClaw verwaltete Matrix-Geräte können sich im Konto ansammeln und das Vertrauen in verschlüsselten Räumen schwerer nachvollziehbar machen.
Liste sie auf mit:
```bash
openclaw matrix devices list
```
Entferne veraltete von OpenClaw verwaltete Geräte mit:
Entferne veraltete, von OpenClaw verwaltete Geräte mit:
```bash
openclaw matrix devices prune-stale
```
### Krypto-Speicher
### Crypto-Store
Matrix-E2EE verwendet den offiziellen Rust-Kryptopfad von `matrix-js-sdk` in Node, mit `fake-indexeddb` als IndexedDB-Shim. Der Kryptozustand wird in einer Snapshot-Datei (`crypto-idb-snapshot.json`) gespeichert und beim Start wiederhergestellt. Die Snapshot-Datei ist sensibler Laufzeitzustand und wird mit restriktiven Dateiberechtigungen gespeichert.
Matrix-E2EE verwendet den offiziellen Rust-Crypto-Pfad von `matrix-js-sdk` in Node, mit `fake-indexeddb` als IndexedDB-Shim. Der Crypto-Status wird in einer Snapshot-Datei (`crypto-idb-snapshot.json`) gespeichert und beim Start wiederhergestellt. Die Snapshot-Datei ist sensibler Laufzeitstatus und wird mit restriktiven Dateiberechtigungen gespeichert.
Der verschlüsselte Laufzeitzustand befindet sich unter kontospezifischen, benutzerspezifischen Token-Hash-Wurzeln in
Verschlüsselter Laufzeitstatus liegt unter roots pro Konto und Benutzer mit Token-Hash in
`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/`.
Dieses Verzeichnis enthält den Sync-Speicher (`bot-storage.json`), den Krypto-Speicher (`crypto/`),
die Recovery-Key-Datei (`recovery-key.json`), den IndexedDB-Snapshot (`crypto-idb-snapshot.json`),
Thread-Bindungen (`thread-bindings.json`) und den Startverifizierungszustand (`startup-verification.json`).
Dieses Verzeichnis enthält den Sync-Store (`bot-storage.json`), den Crypto-Store (`crypto/`),
die Wiederherstellungsschlüssel-Datei (`recovery-key.json`), den IndexedDB-Snapshot (`crypto-idb-snapshot.json`),
Thread-Bindings (`thread-bindings.json`) und den Status der Startverifizierung (`startup-verification.json`).
Wenn sich das Token ändert, die Kontoidentität aber gleich bleibt, verwendet OpenClaw die beste vorhandene
Wurzel für dieses Tupel aus Konto/Homeserver/Benutzer erneut, sodass der bisherige Sync-Zustand, Krypto-Zustand, Thread-Bindungen
und Startverifizierungszustand weiterhin sichtbar bleiben.
Root für dieses Konto-/Homeserver-/Benutzer-Tupel wieder, sodass vorheriger Sync-Status, Crypto-Status, Thread-Bindings
und Startverifizierungsstatus sichtbar bleiben.
## Profilverwaltung
@ -681,37 +682,37 @@ openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```
Füge `--account <id>` hinzu, wenn du gezielt ein benanntes Matrix-Konto ansprechen möchtest.
Füge `--account <id>` hinzu, wenn du explizit ein benanntes Matrix-Konto ansprechen möchtest.
Matrix akzeptiert `mxc://`-Avatar-URLs direkt. Wenn du eine `http://`- oder `https://`-Avatar-URL übergibst, lädt OpenClaw sie zuerst zu Matrix hoch und speichert die aufgelöste `mxc://`-URL zurück in `channels.matrix.avatarUrl` (oder in die ausgewählte Kontoüberschreibung).
Matrix akzeptiert `mxc://`-Avatar-URLs direkt. Wenn du eine `http://`- oder `https://`-Avatar-URL übergibst, lädt OpenClaw sie zuerst zu Matrix hoch und speichert die aufgelöste `mxc://`-URL zurück in `channels.matrix.avatarUrl` (oder in den ausgewählten Konto-Override).
## Threads
Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für Sendevorgänge von Message-Tools.
Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für Sendungen über Message-Tools.
- `dm.sessionScope: "per-user"` (Standard) hält das Routing von Matrix-DMs absenderbezogen, sodass mehrere DM-Räume eine Sitzung gemeinsam nutzen können, wenn sie zum selben Gegenüber aufgelöst werden.
- `dm.sessionScope: "per-room"` isoliert jeden Matrix-DM-Raum in seinen eigenen Sitzungsschlüssel, verwendet aber weiterhin normale DM-Authentifizierung und Allowlist-Prüfungen.
- Explizite Matrix-Konversationsbindungen haben weiterhin Vorrang vor `dm.sessionScope`, sodass gebundene Räume und Threads ihre gewählte Zielsitzung beibehalten.
- `threadReplies: "off"` hält Antworten auf oberster Ebene und belässt eingehende Thread-Nachrichten in der übergeordneten Sitzung.
- `dm.sessionScope: "per-user"` (Standard) hält das DM-Routing in Matrix absenderspezifisch, sodass mehrere DM-Räume eine Sitzung gemeinsam nutzen können, wenn sie zum selben Peer aufgelöst werden.
- `dm.sessionScope: "per-room"` isoliert jeden Matrix-DM-Raum in seinen eigenen Sitzungsschlüssel und verwendet dabei weiterhin normale DM-Authentifizierungs- und Allowlist-Prüfungen.
- Explizite Matrix-Konversations-Bindings haben weiterhin Vorrang vor `dm.sessionScope`, sodass gebundene Räume und Threads ihre gewählte Zielsitzung beibehalten.
- `threadReplies: "off"` hält Antworten auf der obersten Ebene und behält eingehende Thread-Nachrichten in der übergeordneten Sitzung.
- `threadReplies: "inbound"` antwortet innerhalb eines Threads nur dann, wenn die eingehende Nachricht bereits in diesem Thread war.
- `threadReplies: "always"` hält Raumantworten in einem Thread mit Wurzel in der auslösenden Nachricht und leitet diese Konversation ab der ersten auslösenden Nachricht über die passende threadspezifische Sitzung.
- `dm.threadReplies` überschreibt die Einstellung der obersten Ebene nur für DMs. Du kannst zum Beispiel Raum-Threads isoliert halten und DMs flach belassen.
- `threadReplies: "always"` hält Raumantworten in einem Thread mit der auslösenden Nachricht als Wurzel und leitet diese Konversation ab der ersten auslösenden Nachricht über die passende threadbezogene Sitzung.
- `dm.threadReplies` überschreibt die Einstellung auf oberster Ebene nur für DMs. So kannst du zum Beispiel Raum-Threads isoliert halten und DMs flach halten.
- Eingehende Thread-Nachrichten enthalten die Thread-Wurzel-Nachricht als zusätzlichen Agent-Kontext.
- Sendevorgänge von Message-Tools übernehmen automatisch den aktuellen Matrix-Thread, wenn das Ziel derselbe Raum oder dasselbe DM-Benutzerziel ist, es sei denn, eine explizite `threadId` wird angegeben.
- Dieselbe sitzungsbezogene Wiederverwendung eines DM-Benutzerziels greift nur, wenn die aktuellen Sitzungsmetadaten dasselbe DM-Gegenüber auf demselben Matrix-Konto belegen; andernfalls greift OpenClaw auf normales benutzerbezogenes Routing zurück.
- Wenn OpenClaw erkennt, dass ein Matrix-DM-Raum mit einem anderen DM-Raum in derselben gemeinsamen Matrix-DM-Sitzung kollidiert, veröffentlicht es einmalig ein `m.notice` in diesem Raum mit dem `/focus`-Ausweg, wenn Thread-Bindungen aktiviert sind und dem Hinweis `dm.sessionScope`.
- Laufzeit-Thread-Bindungen werden für Matrix unterstützt. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` und threadgebundenes `/acp spawn` funktionieren in Matrix-Räumen und DMs.
- `/focus` auf oberster Ebene in einem Matrix-Raum/DM erstellt einen neuen Matrix-Thread und bindet ihn an die Zielsitzung, wenn `threadBindings.spawnSubagentSessions=true`.
- Wenn `/focus` oder `/acp spawn --thread here` innerhalb eines vorhandenen Matrix-Threads ausgeführt wird, bindet es stattdessen diesen aktuellen Thread.
- Sendungen über Message-Tools übernehmen den aktuellen Matrix-Thread automatisch, wenn das Ziel derselbe Raum oder dasselbe DM-Benutzerziel ist, sofern kein explizites `threadId` angegeben wird.
- Die Wiederverwendung desselben sitzungsbezogenen DM-Benutzerziels greift nur, wenn die Metadaten der aktuellen Sitzung denselben DM-Peer im selben Matrix-Konto nachweisen; andernfalls fällt OpenClaw auf normales benutzerbezogenes Routing zurück.
- Wenn OpenClaw erkennt, dass ein Matrix-DM-Raum mit einem anderen DM-Raum in derselben gemeinsamen Matrix-DM-Sitzung kollidiert, veröffentlicht es in diesem Raum einmalig ein `m.notice` mit dem `/focus`-Ausweg, wenn Thread-Bindings aktiviert sind, sowie dem Hinweis `dm.sessionScope`.
- Laufzeit-Thread-Bindings werden für Matrix unterstützt. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` und threadgebundenes `/acp spawn` funktionieren in Matrix-Räumen und DMs.
- `/focus` auf oberster Ebene in Matrix-Räumen/DMs erstellt einen neuen Matrix-Thread und bindet ihn an die Zielsitzung, wenn `threadBindings.spawnSubagentSessions=true`.
- Wenn `/focus` oder `/acp spawn --thread here` innerhalb eines vorhandenen Matrix-Threads ausgeführt wird, bindet dies stattdessen diesen aktuellen Thread.
## ACP-Konversationsbindungen
## ACP-Konversations-Bindings
Matrix-Räume, DMs und vorhandene Matrix-Threads können in dauerhafte ACP-Arbeitsbereiche umgewandelt werden, ohne die Chat-Oberfläche zu ändern.
Schneller Operator-Ablauf:
- Führe `/acp spawn codex --bind here` innerhalb der Matrix-DM, des Raums oder des vorhandenen Threads aus, den du weiterverwenden möchtest.
- In einer Matrix-DM oder einem Raum auf oberster Ebene bleibt die aktuelle DM bzw. der aktuelle Raum die Chat-Oberfläche und zukünftige Nachrichten werden an die erzeugte ACP-Sitzung geleitet.
- In einer Matrix-DM oder einem Matrix-Raum auf oberster Ebene bleibt die aktuelle DM/der aktuelle Raum die Chat-Oberfläche, und zukünftige Nachrichten werden an die erzeugte ACP-Sitzung weitergeleitet.
- Innerhalb eines vorhandenen Matrix-Threads bindet `--bind here` diesen aktuellen Thread an Ort und Stelle.
- `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung an Ort und Stelle zurück.
- `/acp close` schließt die ACP-Sitzung und entfernt die Bindung.
@ -721,9 +722,9 @@ Hinweise:
- `--bind here` erstellt keinen untergeordneten Matrix-Thread.
- `threadBindings.spawnAcpSessions` ist nur für `/acp spawn --thread auto|here` erforderlich, wenn OpenClaw einen untergeordneten Matrix-Thread erstellen oder binden muss.
### Konfiguration von Thread-Bindungen
### Thread-Binding-Konfiguration
Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterstützt außerdem kanalbezogene Überschreibungen:
Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterstützt außerdem kanalbezogene Overrides:
- `threadBindings.enabled`
- `threadBindings.idleHours`
@ -733,33 +734,33 @@ Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterst
Threadgebundene Spawn-Flags für Matrix sind optional:
- Setze `threadBindings.spawnSubagentSessions: true`, um zu erlauben, dass `/focus` auf oberster Ebene neue Matrix-Threads erstellt und bindet.
- Setze `threadBindings.spawnAcpSessions: true`, um zu erlauben, dass `/acp spawn --thread auto|here` ACP-Sitzungen an Matrix-Threads bindet.
- Setze `threadBindings.spawnSubagentSessions: true`, um zuzulassen, dass `/focus` auf oberster Ebene neue Matrix-Threads erstellt und bindet.
- Setze `threadBindings.spawnAcpSessions: true`, um zuzulassen, dass `/acp spawn --thread auto|here` ACP-Sitzungen an Matrix-Threads bindet.
## Reaktionen
Matrix unterstützt ausgehende Reaktionsaktionen, eingehende Reaktionsbenachrichtigungen und eingehende Bestätigungsreaktionen.
- Ausgehende Reaktions-Tools werden durch `channels["matrix"].actions.reactions` gesteuert.
- `react` fügt eine Reaktion zu einem bestimmten Matrix-Ereignis hinzu.
- Tooling für ausgehende Reaktionen wird durch `channels["matrix"].actions.reactions` gesteuert.
- `react` fügt einem bestimmten Matrix-Ereignis eine Reaktion hinzu.
- `reactions` listet die aktuelle Reaktionszusammenfassung für ein bestimmtes Matrix-Ereignis auf.
- `emoji=""` entfernt die eigenen Reaktionen des Bot-Kontos auf dieses Ereignis.
- `remove: true` entfernt nur die angegebene Emoji-Reaktion des Bot-Kontos.
- `emoji=""` entfernt die eigenen Reaktionen des Bot-Kontos auf diesem Ereignis.
- `remove: true` entfernt nur die angegebene Emoji-Reaktion vom Bot-Konto.
Der Geltungsbereich von Bestätigungsreaktionen wird in dieser Reihenfolge aufgelöst:
Der Geltungsbereich für Bestätigungsreaktionen wird in dieser Reihenfolge aufgelöst:
- `channels["matrix"].accounts.<accountId>.ackReaction`
- `channels["matrix"].ackReaction`
- `messages.ackReaction`
- Emoji-Fallback der Agent-Identität
Der Geltungsbereich der Bestätigungsreaktion wird in dieser Reihenfolge aufgelöst:
Der Geltungsbereich von Bestätigungsreaktionen wird in dieser Reihenfolge aufgelöst:
- `channels["matrix"].accounts.<accountId>.ackReactionScope`
- `channels["matrix"].ackReactionScope`
- `messages.ackReactionScope`
Der Modus für Reaktionsbenachrichtigungen wird in dieser Reihenfolge aufgelöst:
Der Benachrichtigungsmodus für Reaktionen wird in dieser Reihenfolge aufgelöst:
- `channels["matrix"].accounts.<accountId>.reactionNotifications`
- `channels["matrix"].reactionNotifications`
@ -767,28 +768,28 @@ Der Modus für Reaktionsbenachrichtigungen wird in dieser Reihenfolge aufgelöst
Verhalten:
- `reactionNotifications: "own"` leitet hinzugefügte `m.reaction`-Ereignisse weiter, wenn sie auf von Bots verfasste Matrix-Nachrichten zielen.
- `reactionNotifications: "off"` deaktiviert Reaktionssystemereignisse.
- Das Entfernen von Reaktionen wird nicht in Systemereignisse umgewandelt, weil Matrix diese als Redactions und nicht als eigenständige `m.reaction`-Entfernungen darstellt.
- `reactionNotifications: "own"` leitet hinzugefügte `m.reaction`-Ereignisse weiter, wenn sie sich auf vom Bot verfasste Matrix-Nachrichten beziehen.
- `reactionNotifications: "off"` deaktiviert Reaktions-Systemereignisse.
- Das Entfernen von Reaktionen wird nicht zu Systemereignissen synthetisiert, da Matrix diese als Redaktionen und nicht als eigenständige Entfernungen von `m.reaction` darstellt.
## Verlaufskontext
## Verlaufs-Kontext
- `channels.matrix.historyLimit` steuert, wie viele aktuelle Raumnachrichten als `InboundHistory` einbezogen werden, wenn eine Matrix-Raumnachricht den Agent auslöst. Fällt auf `messages.groupChat.historyLimit` zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setze `0`, um dies zu deaktivieren.
- Der Verlauf von Matrix-Räumen gilt nur für Räume. DMs verwenden weiterhin den normalen Sitzungsverlauf.
- Der Verlauf von Matrix-Räumen ist nur raumbezogen. DMs verwenden weiterhin den normalen Sitzungsverlauf.
- Der Verlauf von Matrix-Räumen ist nur für ausstehende Nachrichten: OpenClaw puffert Raumnachrichten, die noch keine Antwort ausgelöst haben, und erstellt dann einen Snapshot dieses Fensters, wenn eine Erwähnung oder ein anderer Auslöser eintrifft.
- Die aktuelle Auslösernachricht wird nicht in `InboundHistory` aufgenommen; sie bleibt für diesen Turn im Hauptteil der eingehenden Nachricht.
- Wiederholungen desselben Matrix-Ereignisses verwenden den ursprünglichen Verlaufs-Snapshot wieder, anstatt zu neueren Raumnachrichten weiterzuwandern.
- Die aktuelle auslösende Nachricht ist nicht in `InboundHistory` enthalten; sie bleibt für diesen Turn im Hauptteil der eingehenden Nachricht.
- Wiederholungsversuche desselben Matrix-Ereignisses verwenden den ursprünglichen Verlaufs-Snapshot wieder, anstatt auf neuere Raumnachrichten weiterzudriften.
## Kontextsichtigkeit
## Kontextsichtbarkeit
Matrix unterstützt die gemeinsame Steuerung `contextVisibility` für ergänzenden Raumkontext wie abgerufenen Antworttext, Thread-Wurzeln und ausstehenden Verlauf.
- `contextVisibility: "all"` ist die Standardeinstellung. Ergänzender Kontext bleibt wie empfangen erhalten.
- `contextVisibility: "allowlist"` filtert ergänzenden Kontext auf Absender, die durch die aktiven Allowlist-Prüfungen für Raum/Benutzer erlaubt sind.
- `contextVisibility: "allowlist_quote"` verhält sich wie `allowlist`, behält aber dennoch ein explizites zitiertes Reply bei.
- `contextVisibility: "all"` ist der Standard. Ergänzender Kontext bleibt wie empfangen erhalten.
- `contextVisibility: "allowlist"` filtert ergänzenden Kontext auf Absender, die durch die aktiven Raum-/Benutzer-Allowlist-Prüfungen zugelassen sind.
- `contextVisibility: "allowlist_quote"` verhält sich wie `allowlist`, behält aber dennoch eine explizit zitierte Antwort bei.
Diese Einstellung beeinflusst die Sichtbarkeit des ergänzenden Kontexts, nicht, ob die eingehende Nachricht selbst eine Antwort auslösen darf.
Die Autorisierung des Auslösers stammt weiterhin aus `groupPolicy`, `groups`, `groupAllowFrom` und den Einstellungen für DM-Richtlinien.
Diese Einstellung beeinflusst die Sichtbarkeit ergänzenden Kontexts, nicht ob die eingehende Nachricht selbst eine Antwort auslösen kann.
Die Autorisierung von Auslösern kommt weiterhin von `groupPolicy`, `groups`, `groupAllowFrom` und den DM-Richtlinieneinstellungen.
## DM- und Raumrichtlinie
@ -813,7 +814,7 @@ Die Autorisierung des Auslösers stammt weiterhin aus `groupPolicy`, `groups`, `
}
```
Siehe [Groups](/de/channels/groups) für Verhalten bei Erwähnungsgating und Allowlists.
Siehe [Groups](/de/channels/groups) für Erwähnungs-Gating und Allowlist-Verhalten.
Pairing-Beispiel für Matrix-DMs:
@ -822,13 +823,13 @@ openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```
Wenn ein nicht genehmigter Matrix-Benutzer dir vor der Freigabe weiterhin Nachrichten sendet, verwendet OpenClaw denselben ausstehenden Pairing-Code erneut und kann nach einer kurzen Abkühlzeit erneut eine Erinnerungsantwort senden, anstatt einen neuen Code zu erzeugen.
Wenn ein nicht genehmigter Matrix-Benutzer dich vor der Genehmigung weiter anschreibt, verwendet OpenClaw denselben ausstehenden Pairing-Code erneut und kann nach einer kurzen Abklingzeit erneut eine Erinnerung senden, statt einen neuen Code zu erzeugen.
Siehe [Pairing](/de/channels/pairing) für den gemeinsamen DM-Pairing-Ablauf und das Speicherlayout.
## Reparatur direkter Räume
Wenn der Direktnachrichtenstatus nicht mehr synchron ist, kann OpenClaw veraltete `m.direct`-Zuordnungen haben, die auf alte Einzelräume statt auf die aktuelle DM zeigen. Prüfe die aktuelle Zuordnung für ein Gegenüber mit:
Wenn der Status von Direktnachrichten nicht synchron ist, kann OpenClaw veraltete `m.direct`-Zuordnungen haben, die auf alte Einzelräume statt auf die aktive DM zeigen. Prüfe die aktuelle Zuordnung für einen Peer mit:
```bash
openclaw matrix direct inspect --user-id @alice:example.org
@ -843,15 +844,15 @@ openclaw matrix direct repair --user-id @alice:example.org
Der Reparaturablauf:
- bevorzugt eine strikte 1:1-DM, die bereits in `m.direct` zugeordnet ist
- greift andernfalls auf eine aktuell beigetretene strikte 1:1-DM mit diesem Benutzer zurück
- erstellt einen neuen Direkt-Raum und schreibt `m.direct` neu, wenn keine funktionsfähige DM existiert
- fällt auf eine aktuell beigetretene strikte 1:1-DM mit diesem Benutzer zurück
- erstellt einen neuen Direkt-Raum und schreibt `m.direct` neu, wenn keine gesunde DM existiert
Der Reparaturablauf löscht alte Räume nicht automatisch. Er wählt nur die funktionsfähige DM aus und aktualisiert die Zuordnung, sodass neue Matrix-Sendevorgänge, Verifizierungshinweise und andere Direktnachrichtenabläufe wieder den richtigen Raum ansteuern.
Der Reparaturablauf löscht alte Räume nicht automatisch. Er wählt nur die gesunde DM aus und aktualisiert die Zuordnung, damit neue Matrix-Sendungen, Verifizierungshinweise und andere Direktnachrichtenabläufe wieder den richtigen Raum ansprechen.
## Exec-Genehmigungen
Matrix kann als nativer Genehmigungs-Client für ein Matrix-Konto fungieren. Die nativen
Routing-Regler für DMs/Kanäle befinden sich weiterhin unter der Konfiguration für Exec-Genehmigungen:
DM-/Channel-Routing-Schalter befinden sich weiterhin unter der Exec-Genehmigungskonfiguration:
- `channels.matrix.execApprovals.enabled`
- `channels.matrix.execApprovals.approvers` (optional; fällt auf `channels.matrix.dm.allowFrom` zurück)
@ -859,38 +860,38 @@ Routing-Regler für DMs/Kanäle befinden sich weiterhin unter der Konfiguration
- `channels.matrix.execApprovals.agentFilter`
- `channels.matrix.execApprovals.sessionFilter`
Genehmigende Personen müssen Matrix-Benutzer-IDs wie `@owner:example.org` sein. Matrix aktiviert native Genehmigungen automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und mindestens eine genehmigende Person aufgelöst werden kann. Exec-Genehmigungen verwenden zuerst `execApprovals.approvers` und können auf `channels.matrix.dm.allowFrom` zurückfallen. Plugin-Genehmigungen autorisieren über `channels.matrix.dm.allowFrom`. Setze `enabled: false`, um Matrix explizit als nativen Genehmigungs-Client zu deaktivieren. Genehmigungsanfragen fallen andernfalls auf andere konfigurierte Genehmigungswege oder die Fallback-Richtlinie für Genehmigungen zurück.
Genehmiger müssen Matrix-Benutzer-IDs wie `@owner:example.org` sein. Matrix aktiviert native Genehmigungen automatisch, wenn `enabled` nicht gesetzt ist oder `"auto"` lautet und mindestens ein Genehmiger aufgelöst werden kann. Exec-Genehmigungen verwenden zuerst `execApprovals.approvers` und können auf `channels.matrix.dm.allowFrom` zurückfallen. Plugin-Genehmigungen autorisieren über `channels.matrix.dm.allowFrom`. Setze `enabled: false`, um Matrix ausdrücklich als nativen Genehmigungs-Client zu deaktivieren. Andernfalls fallen Genehmigungsanfragen auf andere konfigurierte Genehmigungsrouten oder die Genehmigungs-Fallback-Richtlinie zurück.
Das native Matrix-Routing unterstützt beide Genehmigungsarten:
Matrix-native Weiterleitung unterstützt beide Genehmigungsarten:
- `channels.matrix.execApprovals.*` steuert den nativen DM-/Kanal-Fanout-Modus für Matrix-Genehmigungsaufforderungen.
- Exec-Genehmigungen verwenden die Menge genehmigender Personen aus `execApprovals.approvers` oder `channels.matrix.dm.allowFrom`.
- `channels.matrix.execApprovals.*` steuert den nativen DM-/Channel-Fanout-Modus für Matrix-Genehmigungsaufforderungen.
- Exec-Genehmigungen verwenden die Menge der Exec-Genehmiger aus `execApprovals.approvers` oder `channels.matrix.dm.allowFrom`.
- Plugin-Genehmigungen verwenden die DM-Allowlist von Matrix aus `channels.matrix.dm.allowFrom`.
- Matrix-Reaktionskürzel und Nachrichtenaktualisierungen gelten sowohl für Exec- als auch für Plugin-Genehmigungen.
Zustellungsregeln:
Zustellregeln:
- `target: "dm"` sendet Genehmigungsaufforderungen an DMs der genehmigenden Personen
- `target: "dm"` sendet Genehmigungsaufforderungen an Genehmiger-DMs
- `target: "channel"` sendet die Aufforderung zurück an den auslösenden Matrix-Raum oder die auslösende DM
- `target: "both"` sendet an DMs der genehmigenden Personen und an den auslösenden Matrix-Raum oder die auslösende DM
- `target: "both"` sendet an Genehmiger-DMs und an den auslösenden Matrix-Raum oder die auslösende DM
Matrix-Genehmigungsaufforderungen setzen Reaktionskürzel auf der primären Genehmigungsnachricht:
Matrix-Genehmigungsaufforderungen initialisieren Reaktionskürzel auf der primären Genehmigungsnachricht:
- `✅` = einmal erlauben
- `❌` = ablehnen
- `♾️` = immer erlauben, wenn diese Entscheidung durch die effektive Exec-Richtlinie erlaubt ist
- `♾️` = immer erlauben, wenn diese Entscheidung durch die effektive Exec-Richtlinie zulässig ist
Genehmigende Personen können auf diese Nachricht reagieren oder die Fallback-Slash-Befehle verwenden: `/approve <id> allow-once`, `/approve <id> allow-always` oder `/approve <id> deny`.
Genehmiger können auf diese Nachricht reagieren oder die Fallback-Slash-Befehle verwenden: `/approve <id> allow-once`, `/approve <id> allow-always` oder `/approve <id> deny`.
Nur aufgelöste genehmigende Personen können genehmigen oder ablehnen. Bei Exec-Genehmigungen enthält die Kanalzustellung den Befehlstext, aktiviere also `channel` oder `both` nur in vertrauenswürdigen Räumen.
Nur aufgelöste Genehmiger können genehmigen oder ablehnen. Bei Exec-Genehmigungen enthält die Channel-Zustellung den Befehlstext, daher solltest du `channel` oder `both` nur in vertrauenswürdigen Räumen aktivieren.
Kontobezogene Überschreibung:
Kontoabhängiger Override:
- `channels.matrix.accounts.<account>.execApprovals`
Verwandte Dokumentation: [Exec approvals](/de/tools/exec-approvals)
## Mehrere Konten
## Multi-Account
```json5
{
@ -921,21 +922,21 @@ Verwandte Dokumentation: [Exec approvals](/de/tools/exec-approvals)
```
Werte auf oberster Ebene unter `channels.matrix` dienen als Standardwerte für benannte Konten, sofern ein Konto sie nicht überschreibt.
Du kannst geerbte Raumeinträge mit `groups.<room>.account` auf ein bestimmtes Matrix-Konto beschränken.
Einträge ohne `account` bleiben für alle Matrix-Konten gemeinsam, und Einträge mit `account: "default"` funktionieren weiterhin, wenn das Standardkonto direkt auf oberster Ebene unter `channels.matrix.*` konfiguriert ist.
Teilweise gemeinsam genutzte Authentifizierungs-Standardwerte erzeugen für sich genommen kein separates implizites Standardkonto. OpenClaw synthetisiert das oberste Konto `default` nur dann, wenn dieses Standardkonto aktuelle Authentifizierung hat (`homeserver` plus `accessToken` oder `homeserver` plus `userId` und `password`); benannte Konten können weiterhin auffindbar bleiben, wenn `homeserver` plus `userId` später durch zwischengespeicherte Anmeldedaten zur Authentifizierung ausreichen.
Wenn Matrix bereits genau ein benanntes Konto hat oder `defaultAccount` auf einen vorhandenen Schlüssel eines benannten Kontos verweist, bewahrt die Reparatur-/Einrichtungs-Hochstufung von Einzelkonto zu Mehrkonten dieses Konto, anstatt einen neuen `accounts.default`-Eintrag zu erstellen. Nur Matrix-Authentifizierungs-/Bootstrap-Schlüssel werden in dieses hochgestufte Konto verschoben; gemeinsam genutzte Zustellungsrichtlinien-Schlüssel bleiben auf oberster Ebene.
Setze `defaultAccount`, wenn OpenClaw für implizites Routing, Probing und CLI-Operationen ein benanntes Matrix-Konto bevorzugen soll.
Du kannst geerbte Raumeinträge mit `groups.<room>.account` auf ein einzelnes Matrix-Konto begrenzen.
Einträge ohne `account` bleiben über alle Matrix-Konten hinweg gemeinsam genutzt, und Einträge mit `account: "default"` funktionieren weiterhin, wenn das Standardkonto direkt auf oberster Ebene unter `channels.matrix.*` konfiguriert ist.
Partielle gemeinsame Auth-Standardwerte erzeugen für sich genommen kein separates implizites Standardkonto. OpenClaw synthetisiert das Standardkonto auf oberster Ebene `default` nur dann, wenn dieses Standardkonto aktuelle Auth-Daten hat (`homeserver` plus `accessToken` oder `homeserver` plus `userId` und `password`); benannte Konten können weiterhin über `homeserver` plus `userId` erkennbar bleiben, wenn zwischengespeicherte Anmeldedaten die Authentifizierung später erfüllen.
Wenn Matrix bereits genau ein benanntes Konto hat oder `defaultAccount` auf einen vorhandenen benannten Kontoschlüssel zeigt, bewahrt die Reparatur-/Einrichtungs-Hochstufung von Einzelkonto zu Multi-Account dieses Konto, anstatt einen neuen `accounts.default`-Eintrag zu erstellen. Nur Matrix-Authentifizierungs-/Bootstrap-Schlüssel werden in dieses hochgestufte Konto verschoben; gemeinsame Zustellungsrichtlinien-Schlüssel bleiben auf oberster Ebene.
Setze `defaultAccount`, wenn OpenClaw ein benanntes Matrix-Konto für implizites Routing, Sondierung und CLI-Operationen bevorzugen soll.
Wenn mehrere Matrix-Konten konfiguriert sind und eine Konto-ID `default` ist, verwendet OpenClaw dieses Konto implizit, auch wenn `defaultAccount` nicht gesetzt ist.
Wenn du mehrere benannte Konten konfigurierst, setze `defaultAccount` oder übergib `--account <id>` für CLI-Befehle, die auf impliziter Kontoauswahl basieren.
Wenn du mehrere benannte Konten konfigurierst, setze `defaultAccount` oder übergib `--account <id>` für CLI-Befehle, die auf impliziter Kontoauswahl beruhen.
Übergib `--account <id>` an `openclaw matrix verify ...` und `openclaw matrix devices ...`, wenn du diese implizite Auswahl für einen einzelnen Befehl überschreiben möchtest.
Siehe [Configuration reference](/de/gateway/configuration-reference#multi-account-all-channels) für das gemeinsame Muster für mehrere Konten.
Siehe [Configuration reference](/de/gateway/configuration-reference#multi-account-all-channels) für das gemeinsame Multi-Account-Muster.
## Private/LAN-Homeserver
Standardmäßig blockiert OpenClaw private/interne Matrix-Homeserver zum Schutz vor SSRF, sofern du
nicht explizit pro Konto zustimmst.
Standardmäßig blockiert OpenClaw private/interne Matrix-Homeserver zum SSRF-Schutz, sofern du
nicht explizit pro Konto optierst.
Wenn dein Homeserver auf localhost, einer LAN-/Tailscale-IP oder einem internen Hostnamen läuft, aktiviere
`network.dangerouslyAllowPrivateNetwork` für dieses Matrix-Konto:
@ -964,10 +965,10 @@ openclaw matrix account add \
--access-token syt_ops_xxx
```
Diese Zustimmung erlaubt nur vertrauenswürdige private/interne Ziele. Öffentliche Homeserver im Klartext wie
Dieses Opt-in erlaubt nur vertrauenswürdige private/interne Ziele. Öffentliche unverschlüsselte Homeserver wie
`http://matrix.example.org:8008` bleiben blockiert. Bevorzuge nach Möglichkeit `https://`.
## Matrix-Datenverkehr über einen Proxy leiten
## Matrix-Verkehr über einen Proxy leiten
Wenn deine Matrix-Bereitstellung einen expliziten ausgehenden HTTP(S)-Proxy benötigt, setze `channels.matrix.proxy`:
@ -984,11 +985,11 @@ Wenn deine Matrix-Bereitstellung einen expliziten ausgehenden HTTP(S)-Proxy ben
```
Benannte Konten können den Standardwert auf oberster Ebene mit `channels.matrix.accounts.<id>.proxy` überschreiben.
OpenClaw verwendet dieselbe Proxy-Einstellung für Matrix-Laufzeitdatenverkehr und Prüfungen des Kontostatus.
OpenClaw verwendet dieselbe Proxy-Einstellung für Laufzeit-Matrix-Verkehr und Konto-Status-Sondierungen.
## Zielauflösung
Matrix akzeptiert überall dort diese Zielformen, wo OpenClaw nach einem Raum- oder Benutzerziel fragt:
Matrix akzeptiert diese Zielformen überall dort, wo OpenClaw nach einem Raum- oder Benutzerziel fragt:
- Benutzer: `@user:server`, `user:@user:server` oder `matrix:user:@user:server`
- Räume: `!room:server`, `room:!room:server` oder `matrix:room:!room:server`
@ -997,72 +998,72 @@ Matrix akzeptiert überall dort diese Zielformen, wo OpenClaw nach einem Raum- o
Die Live-Verzeichnissuche verwendet das angemeldete Matrix-Konto:
- Benutzersuchen fragen das Matrix-Benutzerverzeichnis auf diesem Homeserver ab.
- Raumsuchen akzeptieren explizite Raum-IDs und Aliasse direkt und greifen dann auf die Suche in beigetretenen Raumnamen für dieses Konto zurück.
- Die Suche nach Namen beigetretener Räume erfolgt nach bestem Bemühen. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird er bei der Laufzeit-Auflösung von Allowlists ignoriert.
- Raumsuchen akzeptieren explizite Raum-IDs und Aliasse direkt und fallen dann auf die Suche nach beigetretenen Raumnamen für dieses Konto zurück.
- Die Suche nach Namen beigetretener Räume erfolgt nach bestem Bemühen. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird er bei der Laufzeit-Allowlist-Auflösung ignoriert.
## Konfigurationsreferenz
- `enabled`: den Kanal aktivieren oder deaktivieren.
- `enabled`: den Channel aktivieren oder deaktivieren.
- `name`: optionales Label für das Konto.
- `defaultAccount`: bevorzugte Konto-ID, wenn mehrere Matrix-Konten konfiguriert sind.
- `homeserver`: Homeserver-URL, zum Beispiel `https://matrix.example.org`.
- `network.dangerouslyAllowPrivateNetwork`: diesem Matrix-Konto erlauben, sich mit privaten/internen Homeservern zu verbinden. Aktiviere dies, wenn der Homeserver zu `localhost`, einer LAN-/Tailscale-IP oder einem internen Host wie `matrix-synapse` aufgelöst wird.
- `proxy`: optionale HTTP(S)-Proxy-URL für Matrix-Datenverkehr. Benannte Konten können den Standardwert auf oberster Ebene mit ihrem eigenen `proxy` überschreiben.
- `network.dangerouslyAllowPrivateNetwork`: erlaubt diesem Matrix-Konto, sich mit privaten/internen Homeservern zu verbinden. Aktiviere dies, wenn der Homeserver zu `localhost`, einer LAN-/Tailscale-IP oder einem internen Host wie `matrix-synapse` aufgelöst wird.
- `proxy`: optionale HTTP(S)-Proxy-URL für Matrix-Verkehr. Benannte Konten können den Standardwert auf oberster Ebene mit ihrem eigenen `proxy` überschreiben.
- `userId`: vollständige Matrix-Benutzer-ID, zum Beispiel `@bot:example.org`.
- `accessToken`: Access Token für tokenbasierte Authentifizierung. Klartextwerte und SecretRef-Werte werden für `channels.matrix.accessToken` und `channels.matrix.accounts.<id>.accessToken` über env-/file-/exec-Provider unterstützt. Siehe [Secrets Management](/de/gateway/secrets).
- `password`: Passwort für passwortbasierte Anmeldung. Klartextwerte und SecretRef-Werte werden unterstützt.
- `deviceId`: explizite Matrix-Geräte-ID.
- `deviceName`: Anzeigename des Geräts für die Passwortanmeldung.
- `avatarUrl`: gespeicherte Self-Avatar-URL für Profilsynchronisierung und Aktualisierungen über `profile set`.
- `initialSyncLimit`: maximale Anzahl an Ereignissen, die während der Startsynchronisierung abgerufen werden.
- `deviceName`: Anzeigename des Geräts für Passwort-Login.
- `avatarUrl`: gespeicherte Selbst-Avatar-URL für Profilsynchronisierung und `profile set`-Aktualisierungen.
- `initialSyncLimit`: maximale Anzahl von Ereignissen, die während der Start-Synchronisierung abgerufen werden.
- `encryption`: E2EE aktivieren.
- `allowlistOnly`: wenn `true`, wird die Raumrichtlinie `open` auf `allowlist` hochgestuft und alle aktiven DM-Richtlinien außer `disabled` (einschließlich `pairing` und `open`) werden auf `allowlist` erzwungen. Hat keinen Einfluss auf `disabled`-Richtlinien.
- `allowBots`: Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten zulassen (`true` oder `"mentions"`).
- `allowlistOnly`: wenn `true`, wird die Raumrichtlinie `open` auf `allowlist` hochgestuft und alle aktiven DM-Richtlinien außer `disabled` (einschließlich `pairing` und `open`) werden zu `allowlist` gezwungen. Wirkt sich nicht auf `disabled`-Richtlinien aus.
- `allowBots`: Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten erlauben (`true` oder `"mentions"`).
- `groupPolicy`: `open`, `allowlist` oder `disabled`.
- `contextVisibility`: Sichtbarkeitsmodus für ergänzenden Raumkontext (`all`, `allowlist`, `allowlist_quote`).
- `groupAllowFrom`: Allowlist von Benutzer-IDs für Raumdatenverkehr. Einträge sollten vollständige Matrix-Benutzer-IDs sein; nicht aufgelöste Namen werden zur Laufzeit ignoriert.
- `historyLimit`: maximale Anzahl an Raumnachrichten, die als Verlaufskontext für Gruppen einbezogen werden. Fällt auf `messages.groupChat.historyLimit` zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setze `0`, um dies zu deaktivieren.
- `groupAllowFrom`: Allowlist von Benutzer-IDs für Raumverkehr. Einträge sollten vollständige Matrix-Benutzer-IDs sein; nicht aufgelöste Namen werden zur Laufzeit ignoriert.
- `historyLimit`: maximale Anzahl von Raumnachrichten, die als Gruppenverlaufs-Kontext einbezogen werden. Fällt auf `messages.groupChat.historyLimit` zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setze `0`, um dies zu deaktivieren.
- `replyToMode`: `off`, `first`, `all` oder `batched`.
- `markdown`: optionale Markdown-Rendering-Konfiguration für ausgehenden Matrix-Text.
- `streaming`: `off` (Standard), `"partial"`, `"quiet"`, `true` oder `false`. `"partial"` und `true` aktivieren Vorschau-zuerst-Entwurfsaktualisierungen mit normalen Matrix-Textnachrichten. `"quiet"` verwendet nicht benachrichtigende Vorschau-Hinweise für selbstgehostete Push-Regel-Setups. `false` ist gleichbedeutend mit `"off"`.
- `blockStreaming`: `true` aktiviert separate Fortschrittsnachrichten für abgeschlossene Assistant-Blöcke, während das Streaming von Entwurfsvorschauen aktiv ist.
- `streaming`: `off` (Standard), `"partial"`, `"quiet"`, `true` oder `false`. `"partial"` und `true` aktivieren Vorschau-zuerst-Entwurfsaktualisierungen mit normalen Matrix-Textnachrichten. `"quiet"` verwendet nicht benachrichtigende Vorschauhinweise für selbstgehostete Push-Regel-Setups. `false` entspricht `"off"`.
- `blockStreaming`: `true` aktiviert separate Fortschrittsnachrichten für abgeschlossene Assistentenblöcke, während Entwurfsvorschau-Streaming aktiv ist.
- `threadReplies`: `off`, `inbound` oder `always`.
- `threadBindings`: kanalbezogene Überschreibungen für threadgebundenes Sitzungsrouting und dessen Lebenszyklus.
- `startupVerification`: automatischer Modus für Selbstverifizierungsanfragen beim Start (`if-unverified`, `off`).
- `startupVerificationCooldownHours`: Abkühlzeit vor dem erneuten Versuch automatischer Selbstverifizierungsanfragen beim Start.
- `textChunkLimit`: Chunk-Größe für ausgehende Nachrichten in Zeichen (gilt, wenn `chunkMode` auf `length` gesetzt ist).
- `chunkMode`: `length` teilt Nachrichten nach Zeichenanzahl; `newline` teilt an Zeilengrenzen.
- `responsePrefix`: optionale Zeichenfolge, die allen ausgehenden Antworten für diesen Kanal vorangestellt wird.
- `ackReaction`: optionale Überschreibung der Bestätigungsreaktion für diesen Kanal/dieses Konto.
- `ackReactionScope`: optionale Überschreibung des Geltungsbereichs der Bestätigungsreaktion (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
- `threadBindings`: kanalbezogene Overrides für threadgebundenes Sitzungsrouting und Lebenszyklus.
- `startupVerification`: Modus für automatische Selbstverifizierungsanforderungen beim Start (`if-unverified`, `off`).
- `startupVerificationCooldownHours`: Abklingzeit vor einem erneuten Versuch automatischer Start-Verifizierungsanforderungen.
- `textChunkLimit`: Größe ausgehender Nachrichten-Chunks in Zeichen (gilt, wenn `chunkMode` `length` ist).
- `chunkMode`: `length` teilt Nachrichten nach Zeichenzahl; `newline` teilt an Zeilengrenzen.
- `responsePrefix`: optionale Zeichenfolge, die allen ausgehenden Antworten für diesen Channel vorangestellt wird.
- `ackReaction`: optionaler Override für Bestätigungsreaktionen für diesen Channel/dieses Konto.
- `ackReactionScope`: optionaler Override für den Geltungsbereich von Bestätigungsreaktionen (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
- `reactionNotifications`: Modus für eingehende Reaktionsbenachrichtigungen (`own`, `off`).
- `mediaMaxMb`: Obergrenze für Mediengröße in MB für ausgehende Sendungen und eingehende Medienverarbeitung.
- `autoJoin`: Richtlinie für automatisches Beitreten bei Einladungen (`always`, `allowlist`, `off`). Standard: `off`. Gilt für alle Matrix-Einladungen, einschließlich DM-artiger Einladungen.
- `autoJoinAllowlist`: Räume/Aliasse, die erlaubt sind, wenn `autoJoin` auf `allowlist` gesetzt ist. Alias-Einträge werden während der Einladungsverarbeitung in Raum-IDs aufgelöst; OpenClaw vertraut nicht auf Alias-Zustände, die vom eingeladenen Raum behauptet werden.
- `mediaMaxMb`: Größenlimit für Medien in MB für ausgehende Sendungen und eingehende Medienverarbeitung.
- `autoJoin`: Richtlinie für automatisches Beitreten zu Einladungen (`always`, `allowlist`, `off`). Standard: `off`. Gilt für alle Matrix-Einladungen, einschließlich DM-ähnlicher Einladungen.
- `autoJoinAllowlist`: Räume/Aliasse, die erlaubt sind, wenn `autoJoin` auf `allowlist` gesetzt ist. Alias-Einträge werden während der Einladungsverarbeitung zu Raum-IDs aufgelöst; OpenClaw vertraut keinem Alias-Status, den der eingeladene Raum behauptet.
- `dm`: DM-Richtlinienblock (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`).
- `dm.policy`: steuert den DM-Zugriff, nachdem OpenClaw dem Raum beigetreten ist und ihn als DM klassifiziert hat. Dies ändert nicht, ob einer Einladung automatisch beigetreten wird.
- `dm.allowFrom`: Einträge sollten vollständige Matrix-Benutzer-IDs sein, außer du hast sie bereits über eine Live-Verzeichnissuche aufgelöst.
- `dm.sessionScope`: `per-user` (Standard) oder `per-room`. Verwende `per-room`, wenn jeder Matrix-DM-Raum einen getrennten Kontext behalten soll, auch wenn das Gegenüber gleich ist.
- `dm.threadReplies`: Überschreibung der Thread-Richtlinie nur für DMs (`off`, `inbound`, `always`). Überschreibt die Einstellung `threadReplies` auf oberster Ebene sowohl für die Platzierung von Antworten als auch für die Sitzungsisolation in DMs.
- `dm.policy`: steuert den DM-Zugriff, nachdem OpenClaw dem Raum beigetreten ist und ihn als DM klassifiziert hat. Ändert nicht, ob einer Einladung automatisch beigetreten wird.
- `dm.allowFrom`: Einträge sollten vollständige Matrix-Benutzer-IDs sein, es sei denn, du hast sie bereits über die Live-Verzeichnissuche aufgelöst.
- `dm.sessionScope`: `per-user` (Standard) oder `per-room`. Verwende `per-room`, wenn du möchtest, dass jeder Matrix-DM-Raum einen getrennten Kontext behält, selbst wenn der Peer derselbe ist.
- `dm.threadReplies`: DM-spezifischer Override für Thread-Richtlinien (`off`, `inbound`, `always`). Überschreibt die Einstellung `threadReplies` auf oberster Ebene sowohl für die Platzierung von Antworten als auch für die Sitzungsisolierung in DMs.
- `execApprovals`: Matrix-native Zustellung von Exec-Genehmigungen (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
- `execApprovals.approvers`: Matrix-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Optional, wenn `dm.allowFrom` die genehmigenden Personen bereits identifiziert.
- `execApprovals.approvers`: Matrix-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Optional, wenn `dm.allowFrom` die Genehmiger bereits identifiziert.
- `execApprovals.target`: `dm | channel | both` (Standard: `dm`).
- `accounts`: benannte kontobezogene Überschreibungen. Werte auf oberster Ebene unter `channels.matrix` dienen als Standardwerte für diese Einträge.
- `groups`: richtlinienbezogene Zuordnung pro Raum. Bevorzuge Raum-IDs oder Aliasse; nicht aufgelöste Raumnamen werden zur Laufzeit ignoriert. Sitzungs-/Gruppenidentität verwendet nach der Auflösung die stabile Raum-ID.
- `groups.<room>.account`: beschränkt einen geerbten Raumeintrag in Setups mit mehreren Konten auf ein bestimmtes Matrix-Konto.
- `groups.<room>.allowBots`: Überschreibung auf Raumebene für von konfigurierten Bots gesendete Nachrichten (`true` oder `"mentions"`).
- `accounts`: benannte kontoabhängige Overrides. Werte auf oberster Ebene unter `channels.matrix` dienen als Standardwerte für diese Einträge.
- `groups`: raumbezogene Richtlinienzuordnung. Bevorzuge Raum-IDs oder Aliasse; nicht aufgelöste Raumnamen werden zur Laufzeit ignoriert. Sitzungs-/Gruppenidentität verwendet nach der Auflösung die stabile Raum-ID.
- `groups.<room>.account`: beschränkt einen geerbten Raumeintrag in Multi-Account-Setups auf ein bestimmtes Matrix-Konto.
- `groups.<room>.allowBots`: raumbezogener Override für Absender aus konfigurierten Bots (`true` oder `"mentions"`).
- `groups.<room>.users`: absenderbezogene Allowlist pro Raum.
- `groups.<room>.tools`: Überschreibungen zum Zulassen/Ablehnen von Tools pro Raum.
- `groups.<room>.autoReply`: Überschreibung des Erwähnungsgatings auf Raumebene. `true` deaktiviert Erwähnungsanforderungen für diesen Raum; `false` erzwingt sie wieder.
- `groups.<room>.skills`: optionaler Skills-Filter auf Raumebene.
- `groups.<room>.systemPrompt`: optionales Snippet für den System Prompt auf Raumebene.
- `rooms`: veralteter Alias für `groups`.
- `groups.<room>.tools`: raumbezogene Tool-Allow-/Deny-Overrides.
- `groups.<room>.autoReply`: raumbezogener Override für Erwähnungs-Gating. `true` deaktiviert Erwähnungspflichten für diesen Raum; `false` erzwingt sie wieder.
- `groups.<room>.skills`: optionaler raumbezogener Skills-Filter.
- `groups.<room>.systemPrompt`: optionaler raumbezogener System-Prompt-Ausschnitt.
- `rooms`: Legacy-Alias für `groups`.
- `actions`: Tool-Gating pro Aktion (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
## Verwandt
- [Channels Overview](/de/channels) — alle unterstützten Kanäle
- [Channels Overview](/de/channels) — alle unterstützten Channels
- [Pairing](/de/channels/pairing) — DM-Authentifizierung und Pairing-Ablauf
- [Groups](/de/channels/groups) — Verhalten in Gruppenchats und Erwähnungsgating
- [Groups](/de/channels/groups) — Verhalten in Gruppenchats und Erwähnungs-Gating
- [Channel Routing](/de/channels/channel-routing) — Sitzungsrouting für Nachrichten
- [Security](/de/gateway/security) — Zugriffsmodell und Härtung

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

@ -1,106 +1,101 @@
---
read_when:
- Bearbeiten von Systemprompt-Text, Tool-Liste oder Zeit-/Heartbeat-Abschnitten
- Bearbeiten von Systemaufforderungstext, Werkzeugliste oder Zeit-/Heartbeat-Abschnitten
- Ändern des Workspace-Bootstraps oder des Verhaltens bei der Skills-Injektion
summary: Was der OpenClaw-Systemprompt enthält und wie er zusammengesetzt wird
title: Systemprompt
summary: Was die OpenClaw-Systemaufforderung enthält und wie sie zusammengestellt wird
title: Systemaufforderung
x-i18n:
generated_at: "2026-04-12T06:16:42Z"
generated_at: "2026-04-15T19:41:36Z"
model: gpt-5.4
provider: openai
source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
source_path: concepts/system-prompt.md
workflow: 15
---
# Systemprompt
# Systemaufforderung
OpenClaw erstellt für jeden Agentenlauf einen benutzerdefinierten Systemprompt. Der Prompt ist **OpenClaw-eigen** und verwendet nicht den Standardprompt von pi-coding-agent.
OpenClaw erstellt für jeden Agentenlauf eine benutzerdefinierte Systemaufforderung. Die Aufforderung wird **von OpenClaw verwaltet** und verwendet nicht die Standardaufforderung von pi-coding-agent.
Der Prompt wird von OpenClaw zusammengestellt und in jeden Agentenlauf injiziert.
Die Aufforderung wird von OpenClaw zusammengestellt und in jeden Agentenlauf eingefügt.
Provider-Plugins können cachefähige Prompt-Hinweise beisteuern, ohne den
vollständigen OpenClaw-eigenen Prompt zu ersetzen. Die Provider-Laufzeit kann:
Provider-Plugins können cache-fähige Prompt-Hinweise beisteuern, ohne die
vollständige von OpenClaw verwaltete Aufforderung zu ersetzen. Die Provider-Laufzeit kann:
- eine kleine Menge benannter Kernabschnitte ersetzen (`interaction_style`,
`tool_call_style`, `execution_bias`)
- ein **stabiles Präfix** oberhalb der Prompt-Cache-Grenze injizieren
- ein **dynamisches Suffix** unterhalb der Prompt-Cache-Grenze injizieren
- ein **stabiles Präfix** oberhalb der Prompt-Cache-Grenze einfügen
- ein **dynamisches Suffix** unterhalb der Prompt-Cache-Grenze einfügen
Verwende provider-eigene Beiträge für modellspezifische Abstimmung nach
Modellfamilie. Behalte die ältere Prompt-Mutation per
`before_prompt_build` für Kompatibilität oder wirklich globale
Prompt-Änderungen bei, nicht für normales Provider-Verhalten.
Verwenden Sie provider-eigene Beiträge für modellfamilien-spezifische Abstimmung. Behalten Sie die veraltete
`before_prompt_build`-Prompt-Mutation für Kompatibilität oder wirklich globale Prompt-Änderungen bei,
nicht für normales Provider-Verhalten.
## Struktur
Der Prompt ist absichtlich kompakt und verwendet feste Abschnitte:
Die Aufforderung ist bewusst kompakt und verwendet feste Abschnitte:
- **Tooling**: Erinnerung an die strukturierte Tool-Quelle der Wahrheit sowie Hinweise zur Tool-Nutzung zur Laufzeit.
- **Safety**: kurze Guardrail-Erinnerung, um machtsuchendes Verhalten oder das Umgehen von Aufsicht zu vermeiden.
- **Skills** (wenn verfügbar): erklärt dem Modell, wie Skill-Anweisungen bei Bedarf geladen werden.
- **OpenClaw Self-Update**: wie die Konfiguration sicher mit
`config.schema.lookup` geprüft, mit `config.patch` gepatcht, die vollständige
Konfiguration mit `config.apply` ersetzt und `update.run` nur auf
ausdrücklichen Benutzerwunsch ausgeführt wird. Das nur für Owner verfügbare
`gateway`-Tool verweigert außerdem das Umschreiben von
`tools.exec.ask` / `tools.exec.security`, einschließlich älterer
`tools.bash.*`-Aliase, die auf diese geschützten Exec-Pfade normalisiert werden.
- **Tooling**: Erinnerung an die Quelle der Wahrheit für strukturierte Tools plus Laufzeithinweise zur Tool-Nutzung.
- **Safety**: kurze Guardrail-Erinnerung, um machtsuchendes Verhalten oder die Umgehung von Aufsicht zu vermeiden.
- **Skills** (wenn verfügbar): erklärt dem Modell, wie es Skill-Anweisungen bei Bedarf lädt.
- **OpenClaw Self-Update**: wie Konfiguration sicher mit
`config.schema.lookup` geprüft, Konfiguration mit `config.patch` gepatcht, die vollständige
Konfiguration mit `config.apply` ersetzt und `update.run` nur auf ausdrückliche
Benutzeranfrage ausgeführt wird. Das ausschließlich für Eigentümer verfügbare `gateway`-Tool verweigert auch das Umschreiben von
`tools.exec.ask` / `tools.exec.security`, einschließlich veralteter `tools.bash.*`-
Aliasse, die zu diesen geschützten Exec-Pfaden normalisiert werden.
- **Workspace**: Arbeitsverzeichnis (`agents.defaults.workspace`).
- **Documentation**: lokaler Pfad zur OpenClaw-Dokumentation (Repository oder npm-Paket) und wann sie gelesen werden sollte.
- **Workspace Files (injected)**: zeigt an, dass Bootstrap-Dateien unten eingefügt sind.
- **Sandbox** (wenn aktiviert): zeigt eine sandboxed Laufzeit, Sandbox-Pfade und ob erhöhtes `exec` verfügbar ist.
- **Sandbox** (wenn aktiviert): zeigt die sandboxed Laufzeit, Sandbox-Pfade und ob erhöhte Exec-Rechte verfügbar sind.
- **Current Date & Time**: benutzerlokale Zeit, Zeitzone und Zeitformat.
- **Reply Tags**: optionale Reply-Tag-Syntax für unterstützte Provider.
- **Heartbeats**: Heartbeat-Prompt und Bestätigungsverhalten, wenn Heartbeats für den Standardagenten aktiviert sind.
- **Runtime**: Host, Betriebssystem, Node, Modell, Repo-Root (wenn erkannt), Thinking-Level (eine Zeile).
- **Reasoning**: aktuelle Sichtbarkeitsebene + Hinweis auf den Schalter `/reasoning`.
- **Heartbeats**: Heartbeat-Aufforderung und Bestätigungsverhalten, wenn Heartbeats für den Standardagenten aktiviert sind.
- **Runtime**: Host, Betriebssystem, Node, Modell, Repository-Wurzel (wenn erkannt), Denkstufe (eine Zeile).
- **Reasoning**: aktuelle Sichtbarkeitsstufe + Hinweis auf Umschaltung mit /reasoning.
Der Abschnitt Tooling enthält außerdem Laufzeithinweise für lang laufende Arbeit:
- verwende `cron` für spätere Nachverfolgung (`check back later`, Erinnerungen, wiederkehrende Arbeit)
statt `exec`-Sleep-Schleifen, `yieldMs`-Verzögerungstricks oder wiederholtem
`process`-Polling
- verwende `exec` / `process` nur für Befehle, die jetzt starten und im
- verwenden Sie Cron für spätere Nachverfolgung (`check back later`, Erinnerungen, wiederkehrende Arbeit)
statt `exec`-Sleep-Schleifen, `yieldMs`-Verzögerungstricks oder wiederholtem `process`-
Polling
- verwenden Sie `exec` / `process` nur für Befehle, die jetzt starten und im
Hintergrund weiterlaufen
- wenn automatisches Aufwecken bei Abschluss aktiviert ist, starte den Befehl
einmal und verlasse dich auf den pushbasierten Aufweckpfad, wenn er Ausgabe
erzeugt oder fehlschlägt
- verwende `process` für Logs, Status, Eingaben oder Eingriffe, wenn du einen
laufenden Befehl prüfen musst
- wenn die Aufgabe größer ist, bevorzuge `sessions_spawn`; der Abschluss von
Sub-Agenten ist pushbasiert und wird dem Anfragenden automatisch angekündigt
- frage nicht in einer Schleife `subagents list` / `sessions_list` ab, nur um
auf den Abschluss zu warten
- wenn automatisches Abschluss-Aufwecken aktiviert ist, starten Sie den Befehl einmal und verlassen Sie sich auf
den push-basierten Aufweckpfad, wenn er Ausgabe erzeugt oder fehlschlägt
- verwenden Sie `process` für Protokolle, Status, Eingaben oder Eingriffe, wenn Sie
einen laufenden Befehl prüfen müssen
- wenn die Aufgabe größer ist, bevorzugen Sie `sessions_spawn`; der Abschluss von Sub-Agenten ist
push-basiert und wird automatisch an den Anfragenden zurückgemeldet
- pollen Sie `subagents list` / `sessions_list` nicht in einer Schleife, nur um auf
den Abschluss zu warten
Wenn das experimentelle Tool `update_plan` aktiviert ist, weist Tooling das
Modell außerdem an, es nur für nicht triviale mehrstufige Arbeit zu verwenden,
genau einen Schritt als `in_progress` zu halten und nicht nach jedem Update den
gesamten Plan zu wiederholen.
Modell außerdem an, es nur für nicht triviale mehrstufige Arbeit zu verwenden, genau einen
Schritt mit `in_progress` beizubehalten und nicht nach jeder Aktualisierung den gesamten Plan zu wiederholen.
Safety-Guardrails im Systemprompt sind beratend. Sie lenken das Modellverhalten, setzen aber keine Richtlinien durch. Verwende Tool-Richtlinien, Exec-Genehmigungen, Sandboxing und Channel-Allowlists für harte Durchsetzung; Operatoren können diese absichtlich deaktivieren.
Safety-Guardrails in der Systemaufforderung sind hinweisend. Sie leiten das Modellverhalten an, erzwingen aber keine Richtlinie. Verwenden Sie Tool-Richtlinien, Exec-Genehmigungen, Sandboxing und Kanal-Allowlists für harte Durchsetzung; Betreiber können diese absichtlich deaktivieren.
Auf Channels mit nativen Genehmigungskarten/-schaltflächen weist der Laufzeitprompt den
Agenten jetzt an, sich zuerst auf diese native Genehmigungs-UI zu verlassen. Er
sollte einen manuellen Befehl `/approve` nur dann einfügen, wenn das
Tool-Ergebnis angibt, dass Chat-Genehmigungen nicht verfügbar sind oder eine
Auf Kanälen mit nativen Genehmigungskarten/-schaltflächen weist die Laufzeitaufforderung den
Agenten jetzt an, sich zuerst auf diese native Genehmigungs-UI zu verlassen. Sie sollte nur einen manuellen
`/approve`-Befehl enthalten, wenn das Tool-Ergebnis angibt, dass Chat-Genehmigungen nicht verfügbar sind oder
manuelle Genehmigung der einzige Weg ist.
## Prompt-Modi
OpenClaw kann kleinere Systemprompts für Sub-Agenten rendern. Die Laufzeit setzt
für jeden Lauf einen `promptMode` (keine benutzerseitige Konfiguration):
OpenClaw kann kleinere Systemaufforderungen für Sub-Agenten rendern. Die Laufzeit setzt für jeden Lauf einen
`promptMode` (keine benutzerseitige Konfiguration):
- `full` (Standard): enthält alle obigen Abschnitte.
- `minimal`: wird für Sub-Agenten verwendet; lässt **Skills**, **Memory Recall**, **OpenClaw
Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**,
**Messaging**, **Silent Replies** und **Heartbeats** weg. Tooling, **Safety**,
Workspace, Sandbox, Current Date & Time (wenn bekannt), Runtime und injizierter
Workspace, Sandbox, Current Date & Time (wenn bekannt), Runtime und eingefügter
Kontext bleiben verfügbar.
- `none`: gibt nur die grundlegende Identitätszeile zurück.
- `none`: gibt nur die Zeile mit der Basisidentität zurück.
Wenn `promptMode=minimal` gilt, werden zusätzlich injizierte Prompts als **Subagent
Context** statt als **Group Chat Context** bezeichnet.
Wenn `promptMode=minimal`, werden zusätzlich eingefügte Prompts als **Subagent
Context** statt als **Group Chat Context** beschriftet.
## Workspace-Bootstrap-Injektion
@ -113,52 +108,50 @@ Bootstrap-Dateien werden gekürzt und unter **Project Context** angehängt, dami
- `USER.md`
- `HEARTBEAT.md`
- `BOOTSTRAP.md` (nur in brandneuen Workspaces)
- `MEMORY.md`, wenn vorhanden, andernfalls `memory.md` als Fallback in Kleinschreibung
- `MEMORY.md`, wenn vorhanden, andernfalls `memory.md` als Fallback in Kleinbuchstaben
Alle diese Dateien werden bei jedem Turn **in das Kontextfenster injiziert**, sofern
keine dateispezifische Bedingung greift. `HEARTBEAT.md` wird bei normalen Läufen
weggelassen, wenn Heartbeats für den Standardagenten deaktiviert sind oder
`agents.defaults.heartbeat.includeSystemPromptSection` false ist. Halte injizierte
Dateien knapp – insbesondere `MEMORY.md`, das mit der Zeit wachsen und zu
unerwartet hoher Kontextnutzung sowie häufigerer Kompaktierung führen kann.
Alle diese Dateien werden bei jeder Runde **in das Kontextfenster eingefügt**, sofern
keine dateispezifische Sperre gilt. `HEARTBEAT.md` wird bei normalen Läufen weggelassen, wenn
Heartbeats für den Standardagenten deaktiviert sind oder
`agents.defaults.heartbeat.includeSystemPromptSection` false ist. Halten Sie eingefügte
Dateien kurz — insbesondere `MEMORY.md`, das mit der Zeit wachsen und zu
unerwartet hoher Kontextnutzung und häufigerer Compaction führen kann.
> **Hinweis:** Tägliche Dateien `memory/*.md` sind **kein** Teil des normalen Bootstrap-
> Project Context. Bei normalen Turns wird auf sie bei Bedarf über die Tools
> `memory_search` und `memory_get` zugegriffen, sodass sie nicht gegen das
> Kontextfenster zählen, sofern das Modell sie nicht explizit liest. Bloße
> Turns mit `/new` und `/reset` sind die Ausnahme: Die Laufzeit kann aktuelle
> tägliche Memory-Dateien als einmaligen Startup-Kontextblock für diesen ersten Turn
> voranstellen.
> **Hinweis:** Tägliche Dateien in `memory/*.md` sind **nicht** Teil des normalen Bootstrap-
> Project Context. Bei gewöhnlichen Runden werden sie bei Bedarf über die
> Tools `memory_search` und `memory_get` abgerufen, sodass sie nicht gegen das
> Kontextfenster zählen, es sei denn, das Modell liest sie ausdrücklich. Reine `/new`- und
> `/reset`-Runden sind die Ausnahme: Die Laufzeit kann aktuelle tägliche Speicherinhalte
> als einmaligen Startup-Kontextblock für diese erste Runde voranstellen.
Große Dateien werden mit einem Marker gekürzt. Die maximale Größe pro Datei wird durch
`agents.defaults.bootstrapMaxChars` gesteuert (Standard: 20000). Der insgesamt
injizierte Bootstrap-Inhalt über alle Dateien hinweg ist durch
`agents.defaults.bootstrapTotalMaxChars` begrenzt
(Standard: 150000). Fehlende Dateien injizieren einen kurzen Marker für fehlende Dateien. Wenn Kürzung
auftritt, kann OpenClaw einen Warnblock in Project Context injizieren; dies wird mit
`agents.defaults.bootstrapPromptTruncationWarning` gesteuert (`off`, `once`, `always`;
Große Dateien werden mit einer Markierung gekürzt. Die maximale Größe pro Datei wird durch
`agents.defaults.bootstrapMaxChars` gesteuert (Standard: 20000). Der insgesamt eingefügte Bootstrap-
Inhalt über alle Dateien hinweg ist durch `agents.defaults.bootstrapTotalMaxChars`
begrenzt (Standard: 150000). Fehlende Dateien fügen eine kurze Markierung für fehlende Dateien ein. Wenn eine Kürzung
auftritt, kann OpenClaw einen Warnblock in Project Context einfügen; dies wird gesteuert durch
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
Standard: `once`).
Sub-Agent-Sitzungen injizieren nur `AGENTS.md` und `TOOLS.md` (andere Bootstrap-Dateien
werden herausgefiltert, um den Sub-Agent-Kontext klein zu halten).
Sub-Agenten-Sitzungen fügen nur `AGENTS.md` und `TOOLS.md` ein (andere Bootstrap-Dateien
werden herausgefiltert, um den Sub-Agenten-Kontext klein zu halten).
Interne Hooks können diesen Schritt über `agent:bootstrap` abfangen, um die
injizierten Bootstrap-Dateien zu verändern oder zu ersetzen (zum Beispiel `SOUL.md` durch eine alternative Persona auszutauschen).
Interne Hooks können diesen Schritt über `agent:bootstrap` abfangen, um
die eingefügten Bootstrap-Dateien zu verändern oder zu ersetzen (zum Beispiel `SOUL.md` gegen eine alternative Persona auszutauschen).
Wenn du den Agenten weniger generisch klingen lassen möchtest, beginne mit dem
Wenn Sie möchten, dass der Agent weniger generisch klingt, beginnen Sie mit dem
[SOUL.md Personality Guide](/de/concepts/soul).
Um zu prüfen, wie viel jede injizierte Datei beiträgt (roh vs. injiziert, Kürzung sowie Tool-Schema-Overhead), verwende `/context list` oder `/context detail`. Siehe [Context](/de/concepts/context).
Um zu prüfen, wie viel jede eingefügte Datei beiträgt (roh vs. eingefügt, Kürzung, plus Tool-Schema-Overhead), verwenden Sie `/context list` oder `/context detail`. Siehe [Context](/de/concepts/context).
## Zeitverarbeitung
## Zeitbehandlung
Der Systemprompt enthält einen eigenen Abschnitt **Current Date & Time**, wenn die
Benutzerzeitzone bekannt ist. Um den Prompt cache-stabil zu halten, enthält er
jetzt nur noch die **Zeitzone** (keine dynamische Uhrzeit und kein Zeitformat).
Die Systemaufforderung enthält einen eigenen Abschnitt **Current Date & Time**, wenn die
Benutzerzeitzone bekannt ist. Um den Prompt cache-stabil zu halten, enthält sie jetzt nur noch die
**Zeitzone** (keine dynamische Uhrzeit oder Zeitformat).
Verwende `session_status`, wenn der Agent die aktuelle Zeit benötigt; die
Statuskarte enthält eine Zeitstempelzeile. Dasselbe Tool kann optional auch ein
modellspezifisches Override pro Sitzung setzen (`model=default` entfernt es).
Verwenden Sie `session_status`, wenn der Agent die aktuelle Uhrzeit benötigt; die Statuskarte
enthält eine Zeitstempelzeile. Dasselbe Tool kann optional eine Modellüberschreibung pro Sitzung
setzen (`model=default` löscht sie).
Konfiguration mit:
@ -169,14 +162,14 @@ Siehe [Date & Time](/de/date-time) für vollständige Verhaltensdetails.
## Skills
Wenn geeignete Skills vorhanden sind, injiziert OpenClaw eine kompakte **Liste verfügbarer Skills**
(`formatSkillsForPrompt`), die für jeden Skill den **Dateipfad** enthält. Der
Prompt weist das Modell an, `read` zu verwenden, um die SKILL.md am aufgeführten
Ort zu laden (Workspace, verwaltet oder gebündelt). Wenn keine geeigneten Skills
vorhanden sind, wird der Abschnitt Skills weggelassen.
Wenn infrage kommende Skills vorhanden sind, fügt OpenClaw eine kompakte **Liste verfügbarer Skills**
(`formatSkillsForPrompt`) ein, die für jeden Skill den **Dateipfad** enthält. Die
Aufforderung weist das Modell an, `read` zu verwenden, um die SKILL.md am angegebenen
Ort zu laden (Workspace, verwaltet oder gebündelt). Wenn keine infrage kommenden Skills vorhanden sind, wird der
Skills-Abschnitt weggelassen.
Zur Eignung gehören Skill-Metadaten-Bedingungen, Prüfungen der Laufzeitumgebung/-konfiguration
sowie die effektive Skill-Allowlist des Agenten, wenn `agents.defaults.skills` oder
Die Eignung umfasst Skill-Metadaten-Sperren, Laufzeitumgebungs-/Konfigurationsprüfungen
und die effektive Agenten-Skill-Allowlist, wenn `agents.defaults.skills` oder
`agents.list[].skills` konfiguriert ist.
```
@ -189,13 +182,26 @@ sowie die effektive Skill-Allowlist des Agenten, wenn `agents.defaults.skills` o
</available_skills>
```
So bleibt der Basisprompt klein und ermöglicht dennoch eine gezielte Skill-Nutzung.
Dadurch bleibt die Basisprompt klein und ermöglicht trotzdem gezielte Skill-Nutzung.
Das Budget für die Skills-Liste gehört dem Skills-Subsystem:
- Globaler Standard: `skills.limits.maxSkillsPromptChars`
- Überschreibung pro Agent: `agents.list[].skillsLimits.maxSkillsPromptChars`
Generische begrenzte Laufzeitauszüge verwenden eine andere Oberfläche:
- `agents.defaults.contextLimits.*`
- `agents.list[].contextLimits.*`
Diese Trennung hält die Größenbemessung für Skills getrennt von der Größenbemessung für Laufzeit-Lesen/Injektion,
wie etwa `memory_get`, Live-Tool-Ergebnissen und Aktualisierungen von AGENTS.md nach Compaction.
## Dokumentation
Wenn verfügbar, enthält der Systemprompt einen Abschnitt **Documentation**, der auf das
lokale OpenClaw-Dokumentationsverzeichnis verweist (entweder `docs/` im Repo-Workspace oder die gebündelte npm-
Paketdokumentation) und außerdem den öffentlichen Spiegel, das Quell-Repository, die
Community auf Discord sowie ClawHub ([https://clawhub.ai](https://clawhub.ai)) zur Entdeckung von Skills nennt. Der Prompt weist das Modell an, zuerst die lokale Dokumentation
für OpenClaw-Verhalten, Befehle, Konfiguration oder Architektur zu konsultieren und
nach Möglichkeit selbst `openclaw status` auszuführen (den Benutzer nur zu fragen, wenn kein Zugriff besteht).
Wenn verfügbar, enthält die Systemaufforderung einen Abschnitt **Documentation**, der auf das
lokale OpenClaw-Dokumentationsverzeichnis verweist (entweder `docs/` im Repository-Workspace oder die gebündelte npm-
Paketdokumentation) und außerdem den öffentlichen Mirror, das Quell-Repository, die Community-Discord und
ClawHub ([https://clawhub.ai](https://clawhub.ai)) zur Skills-Entdeckung erwähnt. Die Aufforderung weist das Modell an, zuerst lokale Dokumentation zu konsultieren
für OpenClaw-Verhalten, Befehle, Konfiguration oder Architektur, und
`openclaw status` nach Möglichkeit selbst auszuführen (den Benutzer nur zu fragen, wenn kein Zugriff besteht).

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

File diff suppressed because it is too large Load Diff

219
docs/de/plugins/sdk-channel-plugins.md
View File

@ -4,49 +4,48 @@ read_when:
- Sie möchten OpenClaw mit einer Messaging-Plattform verbinden.
- Sie müssen die Adapter-Oberfläche von ChannelPlugin verstehen.
sidebarTitle: Channel Plugins
summary: Schritt-für-Schritt-Anleitung zum Erstellen eines Messaging-Channel-Plugins für OpenClaw
summary: Schritt-für-Schritt-Anleitung zum Erstellen eines Messaging-Channel-Plugin für OpenClaw
title: Erstellen von Channel-Plugins
x-i18n:
generated_at: "2026-04-15T06:21:28Z"
generated_at: "2026-04-15T19:41:39Z"
model: gpt-5.4
provider: openai
source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
source_path: plugins/sdk-channel-plugins.md
workflow: 15
---
# Erstellen von Channel-Plugins
Diese Anleitung führt Sie durch das Erstellen eines Channel-Plugins, das OpenClaw mit einer Messaging-Plattform verbindet. Am Ende haben Sie einen funktionierenden Channel mit DM-Sicherheit, Pairing, Antwort-Threading und ausgehender Nachrichtenübermittlung.
Diese Anleitung führt Sie durch das Erstellen eines Channel-Plugin, das OpenClaw mit einer Messaging-Plattform verbindet. Am Ende haben Sie einen funktionierenden Channel mit DM-Sicherheit, Pairing, Antwort-Threading und ausgehenden Nachrichten.
<Info>
Wenn Sie bisher noch kein OpenClaw-Plugin erstellt haben, lesen Sie zuerst
[Erste Schritte](/de/plugins/building-plugins) für die grundlegende
Paketstruktur und die Manifest-Einrichtung.
Wenn Sie noch nie zuvor ein OpenClaw-Plugin erstellt haben, lesen Sie zuerst
[Erste Schritte](/de/plugins/building-plugins) für die grundlegende Paketstruktur
und die Manifest-Einrichtung.
</Info>
## So funktionieren Channel-Plugins
Channel-Plugins benötigen keine eigenen Send/Edit/React-Tools. OpenClaw behält ein
gemeinsam genutztes `message`-Tool im Core. Ihr Plugin ist zuständig für:
Channel-Plugins benötigen keine eigenen Senden-/Bearbeiten-/Reagieren-Tools. OpenClaw verwaltet ein gemeinsames `message`-Tool im Core. Ihr Plugin ist verantwortlich für:
- **Konfiguration** — Account-Auflösung und Einrichtungsassistent
- **Konfiguration** — Kontenauflösung und Einrichtungsassistent
- **Sicherheit** — DM-Richtlinie und Zulassungslisten
- **Pairing** — DM-Genehmigungsablauf
- **Sitzungsgrammatik** — wie anbieterspezifische Konversations-IDs auf Basis-Chats, Thread-IDs und Parent-Fallbacks abgebildet werden
- **Ausgehend** — Senden von Text, Medien und Umfragen an die Plattform
- **Threading** — wie Antworten in Threads organisiert werden
Der Core ist zuständig für das gemeinsam genutzte Message-Tool, die Prompt-Verdrahtung, die äußere Sitzungs-Schlüsselstruktur, generische `:thread:`-Buchführung und Dispatch.
Der Core verwaltet das gemeinsame Message-Tool, die Prompt-Verdrahtung, die äußere Sitzungs-Schlüsselstruktur, generisches `:thread:`-Bookkeeping und die Verteilung.
Wenn Ihr Channel `message`-Tool-Parameter hinzufügt, die Medienquellen transportieren, stellen Sie diese Parameternamen über `describeMessageTool(...).mediaSourceParams` bereit. Der Core verwendet diese explizite Liste für die Normalisierung von Sandbox-Pfaden und die Richtlinie für ausgehenden Medienzugriff, sodass Plugins keine Shared-Core-Sonderfälle für anbieterspezifische Avatar-, Anhangs- oder Titelbild-Parameter benötigen.
Geben Sie vorzugsweise eine aktionsbezogene Zuordnung zurück, etwa
`{ "set-profile": ["avatarUrl", "avatarPath"] }`, damit nicht zusammenhängende Aktionen nicht die Medienargumente einer anderen Aktion übernehmen. Ein flaches Array funktioniert weiterhin für Parameter, die absichtlich über alle bereitgestellten Aktionen hinweg gemeinsam genutzt werden.
Wenn Ihr Channel Message-Tool-Parameter hinzufügt, die Medienquellen transportieren, stellen Sie diese Parameternamen über `describeMessageTool(...).mediaSourceParams` bereit. Der Core verwendet diese explizite Liste für die Sandbox-Pfad-Normalisierung und die Richtlinie für ausgehenden Medienzugriff, sodass Plugins keine Shared-Core-Sonderfälle für anbieterspezifische Avatar-, Anhangs- oder Titelbild-Parameter benötigen.
Bevorzugen Sie die Rückgabe einer aktionsbezogenen Map wie
`{ "set-profile": ["avatarUrl", "avatarPath"] }`, damit nicht verwandte Aktionen nicht die Medienargumente einer anderen Aktion übernehmen. Ein flaches Array funktioniert weiterhin für Parameter, die absichtlich über alle bereitgestellten Aktionen hinweg gemeinsam genutzt werden.
Wenn Ihre Plattform zusätzlichen Geltungsbereich in Konversations-IDs speichert, belassen Sie diese Analyse im Plugin mit `messaging.resolveSessionConversation(...)`. Dies ist der kanonische Hook, um `rawId` auf die Basis-Konversations-ID, eine optionale Thread-ID, eine explizite `baseConversationId` und beliebige `parentConversationCandidates` abzubilden.
Wenn Sie `parentConversationCandidates` zurückgeben, halten Sie sie in der Reihenfolge vom spezifischsten Parent bis zur breitesten/Basis-Konversation.
Wenn Ihre Plattform zusätzlichen Geltungsbereich innerhalb von Konversations-IDs speichert, behalten Sie dieses Parsing im Plugin mit `messaging.resolveSessionConversation(...)`. Das ist der kanonische Hook für das Mapping von `rawId` auf die Basis-Konversations-ID, optionale Thread-ID, explizite `baseConversationId` und beliebige `parentConversationCandidates`.
Wenn Sie `parentConversationCandidates` zurückgeben, halten Sie sie in der Reihenfolge vom engsten Parent bis zur breitesten/Basis-Konversation.
Gebündelte Plugins, die dieselbe Analyse benötigen, bevor die Channel-Registry startet, können außerdem eine Top-Level-Datei `session-key-api.ts` mit einem passenden Export `resolveSessionConversation(...)` bereitstellen. Der Core verwendet diese Bootstrap-sichere Oberfläche nur dann, wenn die Runtime-Plugin-Registry noch nicht verfügbar ist.
Gebündelte Plugins, die dasselbe Parsing benötigen, bevor die Channel-Registry startet, können außerdem eine Datei `session-key-api.ts` auf oberster Ebene mit einem passenden Export `resolveSessionConversation(...)` bereitstellen. Der Core verwendet diese bootstrap-sichere Oberfläche nur dann, wenn die Runtime-Plugin-Registry noch nicht verfügbar ist.
`messaging.resolveParentConversationCandidates(...)` bleibt als Legacy-Kompatibilitäts-Fallback verfügbar, wenn ein Plugin nur Parent-Fallbacks zusätzlich zur generischen/rohen ID benötigt. Wenn beide Hooks vorhanden sind, verwendet der Core zuerst `resolveSessionConversation(...).parentConversationCandidates` und greift nur auf `resolveParentConversationCandidates(...)` zurück, wenn der kanonische Hook diese auslässt.
@ -54,37 +53,37 @@ Gebündelte Plugins, die dieselbe Analyse benötigen, bevor die Channel-Registry
Die meisten Channel-Plugins benötigen keinen Genehmigungs-spezifischen Code.
- Der Core ist zuständig für `/approve` im selben Chat, gemeinsam genutzte Payloads für Genehmigungs-Buttons und generische Fallback-Zustellung.
- Bevorzugen Sie ein einzelnes `approvalCapability`-Objekt auf dem Channel-Plugin, wenn der Channel Genehmigungs-spezifisches Verhalten benötigt.
- `ChannelPlugin.approvals` wurde entfernt. Legen Sie Fakten zu Genehmigungszustellung/nativer Unterstützung/Rendering/Auth in `approvalCapability` ab.
- `plugin.auth` dient nur für Login/Logout; der Core liest aus diesem Objekt keine Genehmigungs-Auth-Hooks mehr.
- `approvalCapability.authorizeActorAction` und `approvalCapability.getActionAvailabilityState` sind die kanonische Schnittstelle für Genehmigungs-Auth.
- Verwenden Sie `approvalCapability.getActionAvailabilityState` für die Verfügbarkeit von Genehmigungs-Auth bei Genehmigungen im selben Chat.
- Wenn Ihr Channel native Exec-Genehmigungen bereitstellt, verwenden Sie `approvalCapability.getExecInitiatingSurfaceState` für den Zustand der auslösenden Oberfläche/des nativen Clients, wenn dieser sich von der Genehmigungs-Auth im selben Chat unterscheidet. Der Core verwendet diesen exec-spezifischen Hook, um zwischen `enabled` und `disabled` zu unterscheiden, zu entscheiden, ob der auslösende Channel native Exec-Genehmigungen unterstützt, und den Channel in Hinweisen für native Client-Fallbacks einzubeziehen. `createApproverRestrictedNativeApprovalCapability(...)` füllt dies für den häufigen Fall aus.
- Der Core verwaltet `/approve` im selben Chat, gemeinsame Payloads für Genehmigungs-Schaltflächen und generische Fallback-Zustellung.
- Bevorzugen Sie ein einzelnes `approvalCapability`-Objekt im Channel-Plugin, wenn der Channel Genehmigungs-spezifisches Verhalten benötigt.
- `ChannelPlugin.approvals` wurde entfernt. Legen Sie Fakten zu Genehmigungszustellung/nativem Rendering/Auth unter `approvalCapability` ab.
- `plugin.auth` ist nur für Login/Logout; der Core liest aus diesem Objekt keine Auth-Hooks für Genehmigungen mehr.
- `approvalCapability.authorizeActorAction` und `approvalCapability.getActionAvailabilityState` sind die kanonische Nahtstelle für Genehmigungs-Auth.
- Verwenden Sie `approvalCapability.getActionAvailabilityState` für die Verfügbarkeit der Genehmigungs-Auth im selben Chat.
- Wenn Ihr Channel native Exec-Genehmigungen bereitstellt, verwenden Sie `approvalCapability.getExecInitiatingSurfaceState` für den Status der auslösenden Oberfläche/des nativen Clients, wenn dieser sich von der Genehmigungs-Auth im selben Chat unterscheidet. Der Core verwendet diesen Exec-spezifischen Hook, um zwischen `enabled` und `disabled` zu unterscheiden, zu entscheiden, ob der auslösende Channel native Exec-Genehmigungen unterstützt, und den Channel in die Fallback-Hinweise für native Clients aufzunehmen. `createApproverRestrictedNativeApprovalCapability(...)` füllt dies für den häufigen Fall aus.
- Verwenden Sie `outbound.shouldSuppressLocalPayloadPrompt` oder `outbound.beforeDeliverPayload` für Channel-spezifisches Payload-Lifecycle-Verhalten, etwa das Ausblenden doppelter lokaler Genehmigungs-Prompts oder das Senden von Tippindikatoren vor der Zustellung.
- Verwenden Sie `approvalCapability.delivery` nur für natives Genehmigungs-Routing oder die Unterdrückung von Fallbacks.
- Verwenden Sie `approvalCapability.nativeRuntime` für Channel-eigene Fakten zu nativen Genehmigungen. Halten Sie diese auf Hot-Path-Channel-Entrypoints lazy mit `createLazyChannelApprovalNativeRuntimeAdapter(...)`, das Ihr Runtime-Modul bei Bedarf importieren kann, während der Core dennoch den Genehmigungs-Lifecycle zusammenstellen kann.
- Verwenden Sie `approvalCapability.render` nur dann, wenn ein Channel wirklich benutzerdefinierte Genehmigungs-Payloads statt des gemeinsam genutzten Renderers benötigt.
- Verwenden Sie `approvalCapability.describeExecApprovalSetup`, wenn der Channel in der Antwort für den deaktivierten Pfad die genauen Konfigurationsschalter erläutern soll, die zum Aktivieren nativer Exec-Genehmigungen erforderlich sind. Der Hook erhält `{ channel, channelLabel, accountId }`; Channels mit benannten Accounts sollten accountbezogene Pfade wie `channels.<channel>.accounts.<id>.execApprovals.*` statt Top-Level-Standards rendern.
- Wenn ein Channel aus vorhandener Konfiguration stabile owner-ähnliche DM-Identitäten ableiten kann, verwenden Sie `createResolvedApproverActionAuthAdapter` aus `openclaw/plugin-sdk/approval-runtime`, um `/approve` im selben Chat einzuschränken, ohne Genehmigungs-spezifische Core-Logik hinzuzufügen.
- Wenn ein Channel native Genehmigungszustellung benötigt, halten Sie den Channel-Code auf Zielnormalisierung plus Fakten zu Transport/Präsentation fokussiert. Verwenden Sie `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` und `createApproverRestrictedNativeApprovalCapability` aus `openclaw/plugin-sdk/approval-runtime`. Legen Sie die Channel-spezifischen Fakten hinter `approvalCapability.nativeRuntime`, idealerweise über `createChannelApprovalNativeRuntimeAdapter(...)` oder `createLazyChannelApprovalNativeRuntimeAdapter(...)`, damit der Core den Handler zusammensetzen und Request-Filterung, Routing, Deduplizierung, Ablauf, Gateway-Abonnement und Hinweise zu anderweitiger Weiterleitung übernehmen kann. `nativeRuntime` ist in einige kleinere Schnittstellen aufgeteilt:
- `availability` — ob der Account konfiguriert ist und ob eine Anfrage behandelt werden sollte
- `presentation` — Abbildung des gemeinsam genutzten View-Models für Genehmigungen auf ausstehende/aufgelöste/abgelaufene native Payloads oder endgültige Aktionen
- `transport` — Vorbereitung von Zielen sowie Senden/Aktualisieren/Löschen nativer Genehmigungsnachrichten
- `interactions` — optionale Hooks zum Binden/Lösen/Löschen von Aktionen für native Buttons oder Reaktionen
- Verwenden Sie `approvalCapability.nativeRuntime` für Channel-eigene Fakten zu nativen Genehmigungen. Halten Sie dies auf heißen Channel-Einstiegspunkten lazy mit `createLazyChannelApprovalNativeRuntimeAdapter(...)`, das Ihr Runtime-Modul bei Bedarf importieren kann, während der Core weiterhin den Genehmigungs-Lifecycle zusammenstellen kann.
- Verwenden Sie `approvalCapability.render` nur, wenn ein Channel wirklich benutzerdefinierte Genehmigungs-Payloads statt des gemeinsamen Renderers benötigt.
- Verwenden Sie `approvalCapability.describeExecApprovalSetup`, wenn der Channel in der Antwort auf den deaktivierten Pfad die genauen Konfigurationsschalter erläutern soll, die zum Aktivieren nativer Exec-Genehmigungen erforderlich sind. Der Hook erhält `{ channel, channelLabel, accountId }`; Channels mit benannten Konten sollten konto-spezifische Pfade wie `channels.<channel>.accounts.<id>.execApprovals.*` anstelle von Standardwerten auf oberster Ebene rendern.
- Wenn ein Channel stabile DM-Identitäten mit owner-ähnlichem Charakter aus der vorhandenen Konfiguration ableiten kann, verwenden Sie `createResolvedApproverActionAuthAdapter` aus `openclaw/plugin-sdk/approval-runtime`, um `/approve` im selben Chat einzuschränken, ohne Genehmigungs-spezifische Core-Logik hinzuzufügen.
- Wenn ein Channel native Genehmigungszustellung benötigt, halten Sie den Channel-Code auf Ziel-Normalisierung plus Transport-/Präsentationsfakten fokussiert. Verwenden Sie `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` und `createApproverRestrictedNativeApprovalCapability` aus `openclaw/plugin-sdk/approval-runtime`. Legen Sie die Channel-spezifischen Fakten hinter `approvalCapability.nativeRuntime`, idealerweise über `createChannelApprovalNativeRuntimeAdapter(...)` oder `createLazyChannelApprovalNativeRuntimeAdapter(...)`, sodass der Core den Handler zusammenstellen und Anforderungsfilterung, Routing, Deduplizierung, Ablauf, Gateway-Abonnement und Hinweise auf anderweitiges Routing verwalten kann. `nativeRuntime` ist in einige kleinere Nahtstellen aufgeteilt:
- `availability` — ob das Konto konfiguriert ist und ob eine Anforderung verarbeitet werden soll
- `presentation` — das gemeinsame Genehmigungs-View-Model in ausstehende/aufgelöste/abgelaufene native Payloads oder abschließende Aktionen abbilden
- `transport` — Ziele vorbereiten sowie native Genehmigungsnachrichten senden/aktualisieren/löschen
- `interactions` — optionale Hooks zum Binden/Entbinden/Löschen von Aktionen für native Schaltflächen oder Reaktionen
- `observe` — optionale Hooks für Zustellungsdiagnostik
- Wenn der Channel Runtime-eigene Objekte wie einen Client, Token, eine Bolt-App oder einen Webhook-Empfänger benötigt, registrieren Sie diese über `openclaw/plugin-sdk/channel-runtime-context`. Die generische Runtime-Context-Registry ermöglicht dem Core, fähigkeitsgesteuerte Handler aus dem Startzustand des Channels zu bootstrappen, ohne Genehmigungs-spezifischen Wrapper-Klebstoff hinzuzufügen.
- Greifen Sie nur dann zu den Low-Level-Funktionen `createChannelApprovalHandler` oder `createChannelNativeApprovalRuntime`, wenn die fähigkeitsgesteuerte Schnittstelle noch nicht aussagekräftig genug ist.
- Native Genehmigungs-Channels müssen sowohl `accountId` als auch `approvalKind` durch diese Hilfsfunktionen leiten. `accountId` hält die Multi-Account-Genehmigungsrichtlinie auf den richtigen Bot-Account begrenzt, und `approvalKind` stellt Exec- vs. Plugin-Genehmigungsverhalten dem Channel zur Verfügung, ohne fest codierte Verzweigungen im Core.
- Der Core ist jetzt auch für Hinweise zur erneuten Weiterleitung von Genehmigungen zuständig. Channel-Plugins sollten daher keine eigenen Follow-up-Nachrichten wie „Genehmigung ging an DMs / einen anderen Channel“ aus `createChannelNativeApprovalRuntime` senden; stattdessen sollten sie präzises Routing für Ursprung + Approver-DM über die gemeinsam genutzten Hilfsfunktionen für Genehmigungs-Fähigkeiten bereitstellen und den Core die tatsächlichen Zustellungen aggregieren lassen, bevor irgendein Hinweis in den auslösenden Chat gepostet wird.
- Behalten Sie die Art der zugestellten Genehmigungs-ID Ende-zu-Ende bei. Native Clients sollten Exec- vs. Plugin-Genehmigungsrouting nicht anhand Channel-lokalen Zustands erraten oder umschreiben.
- Verschiedene Arten von Genehmigungen können absichtlich unterschiedliche native Oberflächen bereitstellen.
- Wenn der Channel Runtime-eigene Objekte wie einen Client, Token, eine Bolt-App oder einen Webhook-Empfänger benötigt, registrieren Sie sie über `openclaw/plugin-sdk/channel-runtime-context`. Die generische Runtime-Context-Registry erlaubt es dem Core, fähigkeitsgesteuerte Handler aus dem Startzustand des Channels zu bootstrappen, ohne Genehmigungs-spezifischen Wrapper-Kleber hinzuzufügen.
- Greifen Sie nur dann zu den Low-Level-Funktionen `createChannelApprovalHandler` oder `createChannelNativeApprovalRuntime`, wenn die fähigkeitsgesteuerte Nahtstelle noch nicht ausdrucksstark genug ist.
- Native Genehmigungs-Channels müssen sowohl `accountId` als auch `approvalKind` durch diese Hilfsfunktionen routen. `accountId` hält die Multi-Account-Genehmigungsrichtlinie auf das richtige Bot-Konto beschränkt, und `approvalKind` hält das Verhalten für Exec- vs. Plugin-Genehmigungen für den Channel verfügbar, ohne fest codierte Verzweigungen im Core.
- Der Core verwaltet jetzt auch Hinweise zur Umleitung von Genehmigungen. Channel-Plugins sollten keine eigenen Folge-Nachrichten wie „Genehmigung ging an DMs / einen anderen Channel“ aus `createChannelNativeApprovalRuntime` senden; stattdessen sollten sie korrektes Ursprungs- und Approver-DM-Routing über die gemeinsamen Hilfsfunktionen für Genehmigungsfähigkeiten bereitstellen und den Core tatsächliche Zustellungen aggregieren lassen, bevor ein Hinweis zurück in den auslösenden Chat gesendet wird.
- Behalten Sie die Art der zugestellten Genehmigungs-ID durchgängig bei. Native Clients sollten Exec- vs. Plugin-Genehmigungsrouting nicht anhand Channel-lokalen Zustands erraten oder umschreiben.
- Unterschiedliche Genehmigungsarten können absichtlich unterschiedliche native Oberflächen bereitstellen.
Aktuelle gebündelte Beispiele:
- Slack hält natives Genehmigungsrouting sowohl für Exec- als auch für Plugin-IDs verfügbar.
- Matrix behält dasselbe native DM-/Channel-Routing und dieselbe Reaktions-UX für Exec- und Plugin-Genehmigungen bei, während sich Auth weiterhin je nach Genehmigungsart unterscheiden kann.
- Matrix behält dasselbe native DM-/Channel-Routing und dieselbe Reaktions-UX für Exec- und Plugin-Genehmigungen bei, während Auth je nach Genehmigungsart trotzdem unterschiedlich sein darf.
- `createApproverRestrictedNativeApprovalAdapter` existiert weiterhin als Kompatibilitäts-Wrapper, aber neuer Code sollte den Capability-Builder bevorzugen und `approvalCapability` im Plugin bereitstellen.
Für Hot-Path-Channel-Entrypoints sollten Sie die schmaleren Runtime-Unterpfade bevorzugen, wenn Sie nur einen Teil dieser Familie benötigen:
Für heiße Channel-Einstiegspunkte bevorzugen Sie die schmaleren Runtime-Subpaths, wenn Sie nur einen Teil dieser Familie benötigen:
- `openclaw/plugin-sdk/approval-auth-runtime`
- `openclaw/plugin-sdk/approval-client-runtime`
@ -96,38 +95,36 @@ Für Hot-Path-Channel-Entrypoints sollten Sie die schmaleren Runtime-Unterpfade
- `openclaw/plugin-sdk/approval-reply-runtime`
- `openclaw/plugin-sdk/channel-runtime-context`
Ebenso sollten Sie `openclaw/plugin-sdk/setup-runtime`,
Bevorzugen Sie ebenso `openclaw/plugin-sdk/setup-runtime`,
`openclaw/plugin-sdk/setup-adapter-runtime`,
`openclaw/plugin-sdk/reply-runtime`,
`openclaw/plugin-sdk/reply-dispatch-runtime`,
`openclaw/plugin-sdk/reply-reference` und
`openclaw/plugin-sdk/reply-chunking` bevorzugen, wenn Sie die breitere übergreifende Oberfläche nicht benötigen.
`openclaw/plugin-sdk/reply-chunking`, wenn Sie die breitere übergreifende Oberfläche nicht benötigen.
Speziell für das Setup gilt:
Speziell für das Setup:
- `openclaw/plugin-sdk/setup-runtime` deckt die Runtime-sicheren Setup-Hilfen ab:
import-sichere Setup-Patch-Adapter (`createPatchedAccountSetupAdapter`,
- `openclaw/plugin-sdk/setup-runtime` umfasst die runtime-sicheren Setup-Hilfsfunktionen:
importsichere Setup-Patch-Adapter (`createPatchedAccountSetupAdapter`,
`createEnvPatchedAccountSetupAdapter`,
`createSetupInputPresenceValidator`), Ausgabe von Lookup-Hinweisen,
`promptResolvedAllowFrom`, `splitSetupEntries` und die delegierten
Setup-Proxy-Builder
- `openclaw/plugin-sdk/setup-adapter-runtime` ist die schmale env-bewusste Adapter-Schnittstelle
für `createEnvPatchedAccountSetupAdapter`
- `openclaw/plugin-sdk/channel-setup` deckt die Setup-Builder für optionale Installationen
plus einige Setup-sichere Primitive ab:
- `openclaw/plugin-sdk/setup-adapter-runtime` ist die schmale env-bewusste Adapter-Nahtstelle für `createEnvPatchedAccountSetupAdapter`
- `openclaw/plugin-sdk/channel-setup` umfasst die Builder für optionales Setup bei Installation plus einige setup-sichere Primitive:
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
Wenn Ihr Channel env-gesteuertes Setup oder Auth unterstützt und generische Startup-/Konfigurationsabläufe diese Env-Namen vor dem Laden der Runtime kennen sollen, deklarieren Sie sie im Plugin-Manifest mit `channelEnvVars`. Behalten Sie Runtime-`envVars` des Channels oder lokale Konstanten nur für operatorseitigen Text.
Wenn Ihr Channel env-gesteuertes Setup oder Auth unterstützt und generische Start-/Konfigurationsabläufe diese env-Namen vor dem Laden der Runtime kennen sollen, deklarieren Sie sie im Plugin-Manifest mit `channelEnvVars`. Behalten Sie Channel-Runtime-`envVars` oder lokale Konstanten nur für operatorseitige Texte bei.
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` und
`splitSetupEntries`
- verwenden Sie die breitere Schnittstelle `openclaw/plugin-sdk/setup` nur dann, wenn Sie auch die schwergewichtigeren gemeinsam genutzten Setup-/Konfigurationshilfen benötigen, wie etwa
- verwenden Sie die breitere Nahtstelle `openclaw/plugin-sdk/setup` nur dann, wenn Sie auch die schwergewichtigeren gemeinsamen Setup-/Konfigurationshilfen benötigen, etwa
`moveSingleAccountChannelSectionToDefaultAccount(...)`
Wenn Ihr Channel in Setup-Oberflächen nur „installieren Sie zuerst dieses Plugin“ anzeigen möchte, bevorzugen Sie `createOptionalChannelSetupSurface(...)`. Der generierte Adapter/Assistent schlägt bei Konfigurationsschreibvorgängen und Finalisierung sicher fehl und verwendet dieselbe Meldung „Installation erforderlich“ für Validierung, Finalisierung und Text mit Docs-Link erneut.
Wenn Ihr Channel in Setup-Oberflächen nur „Dieses Plugin zuerst installieren“ bewerben möchte, bevorzugen Sie `createOptionalChannelSetupSurface(...)`. Der generierte Adapter/Assistent schlägt bei Konfigurationsschreibvorgängen und Finalisierung geschlossen fehl und verwendet dieselbe Meldung zur erforderlichen Installation über Validierung, Finalisierung und Docs-Link-Text hinweg wieder.
Für andere Hot-Path-Channel-Pfade sollten Sie schmale Hilfsfunktionen gegenüber breiteren Legacy-Oberflächen bevorzugen:
Für andere heiße Channel-Pfade bevorzugen Sie die schmalen Hilfsfunktionen gegenüber breiteren Legacy-Oberflächen:
- `openclaw/plugin-sdk/account-core`,
`openclaw/plugin-sdk/account-id`,
@ -135,45 +132,46 @@ Für andere Hot-Path-Channel-Pfade sollten Sie schmale Hilfsfunktionen gegenübe
`openclaw/plugin-sdk/account-helpers` für Multi-Account-Konfiguration und
Default-Account-Fallback
- `openclaw/plugin-sdk/inbound-envelope` und
`openclaw/plugin-sdk/inbound-reply-dispatch` für das Routing/die Envelope eingehender Nachrichten und
Record-and-Dispatch-Verdrahtung
- `openclaw/plugin-sdk/messaging-targets` für Zielanalyse/-abgleich
`openclaw/plugin-sdk/inbound-reply-dispatch` für eingehendes Routing/Umschlagformat und
Wiring für Aufzeichnen und Verteilen
- `openclaw/plugin-sdk/messaging-targets` für Ziel-Parsing/-Matching
- `openclaw/plugin-sdk/outbound-media` und
`openclaw/plugin-sdk/outbound-runtime` für Medienladen plus ausgehende
Identitäts-/Sende-Delegates
- `openclaw/plugin-sdk/thread-bindings-runtime` für den Lifecycle von Thread-Bindings
und die Adapter-Registrierung
- `openclaw/plugin-sdk/agent-media-payload` nur dann, wenn weiterhin ein Legacy-Layout
für Agent-/Medien-Payload-Felder erforderlich ist
- `openclaw/plugin-sdk/telegram-command-config` für die Normalisierung benutzerdefinierter Telegram-Befehle,
Duplikat-/Konfliktvalidierung und einen fallback-stabilen Vertrag für die Befehlskonfiguration
und Adapter-Registrierung
- `openclaw/plugin-sdk/agent-media-payload` nur dann, wenn weiterhin ein Legacy-Agent-/Medien-
Payload-Feldlayout erforderlich ist
- `openclaw/plugin-sdk/telegram-command-config` für Telegram-Benutzerdefinierte-Befehls-
Normalisierung, Validierung von Duplikaten/Konflikten und einen fallback-stabilen
Command-Konfigurationsvertrag
Channels nur mit Auth können normalerweise beim Standardpfad bleiben: Der Core verarbeitet Genehmigungen, und das Plugin stellt nur Outbound-/Auth-Fähigkeiten bereit. Native Genehmigungs-Channels wie Matrix, Slack, Telegram und benutzerdefinierte Chat-Transporte sollten die gemeinsam genutzten nativen Hilfsfunktionen verwenden, statt ihren eigenen Genehmigungs-Lifecycle zu implementieren.
Auth-only-Channels können in der Regel beim Standardpfad aufhören: Der Core verwaltet Genehmigungen, und das Plugin stellt nur Outbound-/Auth-Fähigkeiten bereit. Native Genehmigungs-Channels wie Matrix, Slack, Telegram und benutzerdefinierte Chat-Transporte sollten die gemeinsamen nativen Hilfsfunktionen verwenden, anstatt ihren eigenen Genehmigungs-Lifecycle zu implementieren.
## Richtlinie für eingehende Erwähnungen
Halten Sie die Verarbeitung eingehender Erwähnungen in zwei Schichten getrennt:
Halten Sie die Verarbeitung eingehender Erwähnungen in zwei Ebenen getrennt:
- plugin-eigene Evidenzerfassung
- gemeinsam genutzte Richtlinienauswertung
- Plugin-eigene Faktenermittlung
- gemeinsame Richtlinienauswertung
Verwenden Sie `openclaw/plugin-sdk/channel-inbound` für die gemeinsam genutzte Schicht.
Verwenden Sie `openclaw/plugin-sdk/channel-inbound` für die gemeinsame Ebene.
Gut geeignet für plugin-lokale Logik:
Gut geeignet für Plugin-lokale Logik:
- Erkennung von Antworten an den Bot
- Erkennung von Antworten auf den Bot
- Erkennung von Zitaten des Bots
- Prüfungen zur Thread-Beteiligung
- Ausschlüsse von Service-/Systemnachrichten
- plattformnative Caches, die benötigt werden, um die Beteiligung des Bots nachzuweisen
Gut geeignet für die gemeinsam genutzte Hilfsfunktion:
Gut geeignet für die gemeinsame Hilfsfunktion:
- `requireMention`
- explizites Erwähnungsergebnis
- Zulassungsliste für implizite Erwähnungen
- Command-Bypass
- endgültige Skip-Entscheidung
- endgültige Entscheidung zum Überspringen
Bevorzugter Ablauf:
@ -218,7 +216,7 @@ const decision = resolveInboundMentionDecision({
if (decision.shouldSkip) return;
```
`api.runtime.channel.mentions` stellt dieselben gemeinsam genutzten Hilfsfunktionen für Erwähnungen für gebündelte Channel-Plugins bereit, die bereits von Runtime-Injection abhängen:
`api.runtime.channel.mentions` stellt dieselben gemeinsamen Hilfsfunktionen für Erwähnungen für gebündelte Channel-Plugins bereit, die bereits von Runtime-Injection abhängen:
- `buildMentionRegexes`
- `matchesMentionPatterns`
@ -227,16 +225,17 @@ if (decision.shouldSkip) return;
- `resolveInboundMentionDecision`
Die älteren Hilfsfunktionen `resolveMentionGating*` bleiben auf
`openclaw/plugin-sdk/channel-inbound` nur als Kompatibilitätsexporte erhalten. Neuer Code sollte `resolveInboundMentionDecision({ facts, policy })` verwenden.
`openclaw/plugin-sdk/channel-inbound` nur als Kompatibilitäts-Exporte erhalten. Neuer Code sollte `resolveInboundMentionDecision({ facts, policy })` verwenden.
## Schritt-für-Schritt-Anleitung
<Steps>
<a id="step-1-package-and-manifest"></a>
<Step title="Paket und Manifest">
Erstellen Sie die Standarddateien des Plugins. Das Feld `channel` in `package.json`
macht dies zu einem Channel-Plugin. Die vollständige Oberfläche der Paketmetadaten
finden Sie unter [Plugin-Setup und Konfiguration](/de/plugins/sdk-setup#openclaw-channel):
Erstellen Sie die Standard-Plugin-Dateien. Das Feld `channel` in `package.json`
macht dies zu einem Channel-Plugin. Die vollständige Oberfläche für
Paketmetadaten finden Sie unter
[Plugin-Setup und Konfiguration](/de/plugins/sdk-setup#openclaw-channel):
<CodeGroup>
```json package.json
@ -286,7 +285,7 @@ Die älteren Hilfsfunktionen `resolveMentionGating*` bleiben auf
</Step>
<Step title="Das Channel-Plugin-Objekt erstellen">
Das Interface `ChannelPlugin` hat viele optionale Adapter-Oberflächen. Beginnen Sie mit
Die Schnittstelle `ChannelPlugin` hat viele optionale Adapter-Oberflächen. Beginnen Sie mit
dem Minimum — `id` und `setup` — und fügen Sie nach Bedarf Adapter hinzu.
Erstellen Sie `src/channel.ts`:
@ -382,24 +381,24 @@ Die älteren Hilfsfunktionen `resolveMentionGating*` bleiben auf
});
```
<Accordion title="Was `createChatChannelPlugin` für Sie erledigt">
Statt Low-Level-Adapter-Interfaces manuell zu implementieren, übergeben Sie
<Accordion title="Was createChatChannelPlugin für Sie übernimmt">
Statt Low-Level-Adapter-Schnittstellen manuell zu implementieren, übergeben Sie
deklarative Optionen, und der Builder setzt sie zusammen:
| Option | Was verdrahtet wird |
| --- | --- |
| `security.dm` | Bereichsbezogener DM-Sicherheits-Resolver aus Konfigurationsfeldern |
| `security.dm` | Scoped-DM-Sicherheits-Resolver aus Konfigurationsfeldern |
| `pairing.text` | Textbasierter DM-Pairing-Ablauf mit Codeaustausch |
| `threading` | Reply-to-Modus-Resolver (fest, accountbezogen oder benutzerdefiniert) |
| `threading` | Resolver für Reply-to-Modus (fest, konto-spezifisch oder benutzerdefiniert) |
| `outbound.attachedResults` | Sendefunktionen, die Ergebnis-Metadaten zurückgeben (Nachrichten-IDs) |
Sie können statt der deklarativen Optionen auch rohe Adapter-Objekte übergeben,
wenn Sie die vollständige Kontrolle benötigen.
wenn Sie vollständige Kontrolle benötigen.
</Accordion>
</Step>
<Step title="Den Entry-Point verdrahten">
<Step title="Den Einstiegspunkt verdrahten">
Erstellen Sie `index.ts`:
```typescript index.ts
@ -437,18 +436,19 @@ Die älteren Hilfsfunktionen `resolveMentionGating*` bleiben auf
Legen Sie Channel-eigene CLI-Deskriptoren in `registerCliMetadata(...)` ab, damit OpenClaw
sie in der Root-Hilfe anzeigen kann, ohne die vollständige Channel-Runtime zu aktivieren,
während normale vollständige Ladevorgänge dieselben Deskriptoren weiterhin für die echte
Befehlsregistrierung übernehmen. Behalten Sie `registerFull(...)` für reine Runtime-Arbeit.
während normale vollständige Ladevorgänge dieselben Deskriptoren weiterhin für die echte Command-
Registrierung übernehmen. Behalten Sie `registerFull(...)` für reine Runtime-Arbeiten.
Wenn `registerFull(...)` Gateway-RPC-Methoden registriert, verwenden Sie ein
pluginspezifisches Präfix. Core-Admin-Namespaces (`config.*`,
Plugin-spezifisches Präfix. Core-Admin-Namespaces (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) bleiben reserviert und werden immer
zu `operator.admin` aufgelöst.
`defineChannelPluginEntry` übernimmt die Aufteilung des Registrierungsmodus automatisch. Alle
Optionen finden Sie unter [Entry-Points](/de/plugins/sdk-entrypoints#definechannelpluginentry).
`defineChannelPluginEntry` übernimmt die Aufteilung nach Registrierungsmodus automatisch. Siehe
[Einstiegspunkte](/de/plugins/sdk-entrypoints#definechannelpluginentry) für alle
Optionen.
</Step>
<Step title="Einen Setup-Entry hinzufügen">
<Step title="Einen Setup-Eintrag hinzufügen">
Erstellen Sie `setup-entry.ts` für leichtgewichtiges Laden während des Onboardings:
```typescript setup-entry.ts
@ -458,16 +458,21 @@ Die älteren Hilfsfunktionen `resolveMentionGating*` bleiben auf
export default defineSetupPluginEntry(acmeChatPlugin);
```
OpenClaw lädt diesen statt des vollständigen Entry-Points, wenn der Channel deaktiviert
oder nicht konfiguriert ist. So wird verhindert, dass während Setup-Abläufen schwergewichtiger Runtime-Code geladen wird.
OpenClaw lädt dies anstelle des vollständigen Einstiegspunkts, wenn der Channel deaktiviert
oder nicht konfiguriert ist. Dadurch wird vermieden, während Setup-Abläufen schweren Runtime-Code zu laden.
Details finden Sie unter [Setup und Konfiguration](/de/plugins/sdk-setup#setup-entry).
Gebündelte Workspace-Channels, die setup-sichere Exporte in Sidecar-
Module aufteilen, können `defineBundledChannelSetupEntry(...)` aus
`openclaw/plugin-sdk/channel-entry-contract` verwenden, wenn sie zusätzlich einen
expliziten Runtime-Setter zur Setup-Zeit benötigen.
</Step>
<Step title="Eingehende Nachrichten verarbeiten">
Ihr Plugin muss Nachrichten von der Plattform empfangen und an
OpenClaw weiterleiten. Das typische Muster ist ein Webhook, der die Anfrage überprüft und
sie über den Inbound-Handler Ihres Channels weiterleitet:
OpenClaw weiterleiten. Das typische Muster ist ein Webhook, der die Anfrage verifiziert und
sie über den Inbound-Handler Ihres Channels verteilt:
```typescript
registerFull(api) {
@ -491,15 +496,15 @@ Die älteren Hilfsfunktionen `resolveMentionGating*` bleiben auf
```
<Note>
Die Verarbeitung eingehender Nachrichten ist channelspezifisch. Jedes Channel-Plugin besitzt
seine eigene Inbound-Pipeline. Sehen Sie sich gebündelte Channel-Plugins
(zum Beispiel das Plugin-Paket für Microsoft Teams oder Google Chat) für reale Muster an.
Die Verarbeitung eingehender Nachrichten ist Channel-spezifisch. Jedes Channel-Plugin besitzt
seine eigene Inbound-Pipeline. Schauen Sie sich gebündelte Channel-Plugins an
(zum Beispiel das Microsoft Teams- oder Google Chat-Plugin-Paket) für echte Muster.
</Note>
</Step>
<a id="step-6-test"></a>
<Step title="Testen">
<Step title="Test">
Schreiben Sie colocated Tests in `src/channel.test.ts`:
```typescript src/channel.test.ts
@ -538,7 +543,7 @@ Schreiben Sie colocated Tests in `src/channel.test.ts`:
pnpm test -- <bundled-plugin-root>/acme-chat/
```
Für gemeinsam genutzte Test-Hilfsfunktionen siehe [Testing](/de/plugins/sdk-testing).
Für gemeinsame Test-Hilfsfunktionen siehe [Testing](/de/plugins/sdk-testing).
</Step>
</Steps>
@ -560,11 +565,11 @@ Schreiben Sie colocated Tests in `src/channel.test.ts`:
└── runtime.ts # Runtime-Store (falls erforderlich)
```
## Erweiterte Themen
## Fortgeschrittene Themen
<CardGroup cols={2}>
<Card title="Threading-Optionen" icon="git-branch" href="/de/plugins/sdk-entrypoints#registration-mode">
Feste, accountbezogene oder benutzerdefinierte Antwortmodi
Feste, konto-spezifische oder benutzerdefinierte Antwortmodi
</Card>
<Card title="Integration des Message-Tools" icon="puzzle" href="/de/plugins/architecture#channel-plugins-and-the-shared-message-tool">
describeMessageTool und Action-Erkennung
@ -578,15 +583,15 @@ Schreiben Sie colocated Tests in `src/channel.test.ts`:
</CardGroup>
<Note>
Einige gebündelte Helper-Schnittstellen existieren weiterhin für die Pflege gebündelter Plugins und
Kompatibilität. Sie sind nicht das empfohlene Muster für neue Channel-Plugins;
bevorzugen Sie die generischen Unterpfade channel/setup/reply/runtime aus der gemeinsamen SDK-
Oberfläche, es sei denn, Sie pflegen diese gebündelte Plugin-Familie direkt.
Einige gebündelte Helper-Nahtstellen existieren weiterhin für die Wartung und
Kompatibilität gebündelter Plugins. Sie sind nicht das empfohlene Muster für neue Channel-Plugins;
bevorzugen Sie die generischen Channel-/Setup-/Reply-/Runtime-Subpaths aus der gemeinsamen SDK-
Oberfläche, es sei denn, Sie warten direkt diese gebündelte Plugin-Familie.
</Note>
## Nächste Schritte
- [Provider-Plugins](/de/plugins/sdk-provider-plugins) — wenn Ihr Plugin auch Modelle bereitstellt
- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Importreferenz für Unterpfade
- [SDK-Testing](/de/plugins/sdk-testing) — Test-Utilities und Vertragstests
- [Plugin-Manifest](/de/plugins/manifest) — vollständiges Manifestschema
- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Referenz für Subpath-Importe
- [SDK Testing](/de/plugins/sdk-testing) — Test-Utilities und Vertragstests
- [Plugin-Manifest](/de/plugins/manifest) — vollständiges Manifest-Schema

160
docs/de/plugins/sdk-entrypoints.md
View File

@ -1,28 +1,27 @@
---
read_when:
- Sie benötigen die genaue Typsignatur von definePluginEntry oder defineChannelPluginEntry
- Sie möchten den Registrierungsmodus verstehen (vollständig vs. Setup vs. CLI-Metadaten)
- Sie schlagen Optionen für Einstiegspunkte nach
- Sie benötigen die genaue Typsignatur von definePluginEntry oder defineChannelPluginEntry.
- Sie möchten den Registrierungsmodus verstehen (vollständig vs. Einrichtung vs. CLI-Metadaten).
- Sie schlagen Einstiegspunktoptionen nach.
sidebarTitle: Entry Points
summary: Referenz für definePluginEntry, defineChannelPluginEntry und defineSetupPluginEntry
title: Plugin-Einstiegspunkte
x-i18n:
generated_at: "2026-04-05T12:51:09Z"
generated_at: "2026-04-15T19:41:40Z"
model: gpt-5.4
provider: openai
source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f
source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4
source_path: plugins/sdk-entrypoints.md
workflow: 15
---
# Plugin-Einstiegspunkte
Jedes Plugin exportiert ein Standard-Einstiegsobjekt. Das SDK bietet drei Hilfsfunktionen
zu seiner Erstellung.
Jedes Plugin exportiert ein Standard-Einstiegsobjekt. Das SDK bietet drei Hilfsfunktionen, um diese zu erstellen.
<Tip>
**Suchen Sie nach einer Schritt-für-Schritt-Anleitung?** Unter [Channel Plugins](/plugins/sdk-channel-plugins)
oder [Provider Plugins](/plugins/sdk-provider-plugins) finden Sie Anleitungen mit einzelnen Schritten.
**Suchen Sie nach einer Schritt-für-Schritt-Anleitung?** Siehe [Kanal-Plugins](/de/plugins/sdk-channel-plugins)
oder [Provider-Plugins](/de/plugins/sdk-provider-plugins) für Schritt-für-Schritt-Anleitungen.
</Tip>
## `definePluginEntry`
@ -50,28 +49,27 @@ export default definePluginEntry({
});
```
| Feld | Typ | Erforderlich | Standard |
| Feld | Typ | Erforderlich | Standardwert |
| -------------- | ---------------------------------------------------------------- | ------------ | ------------------- |
| `id` | `string` | Ja | — |
| `name` | `string` | Ja | — |
| `description` | `string` | Ja | — |
| `kind` | `string` | Nein | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Nein | Schema für leeres Objekt |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Nein | Leeres Objektschema |
| `register` | `(api: OpenClawPluginApi) => void` | Ja | — |
- `id` muss mit Ihrem `openclaw.plugin.json`-Manifest übereinstimmen.
- `kind` ist für exklusive Slots: `"memory"` oder `"context-engine"`.
- `kind` ist für exklusive Slots gedacht: `"memory"` oder `"context-engine"`.
- `configSchema` kann eine Funktion zur verzögerten Auswertung sein.
- OpenClaw löst dieses Schema beim ersten Zugriff auf und memoisiert es, sodass aufwendige Schema-
Builder nur einmal ausgeführt werden.
- OpenClaw löst dieses Schema beim ersten Zugriff auf und memoisiert es, sodass aufwendige Schema-Builder nur einmal ausgeführt werden.
## `defineChannelPluginEntry`
**Import:** `openclaw/plugin-sdk/channel-core`
Kapselt `definePluginEntry` mit kanalspezifischer Verdrahtung. Ruft automatisch
`api.registerChannel({ plugin })` auf, stellt eine optionale CLI-Metadaten-Nahtstelle
für die Root-Hilfe bereit und steuert `registerFull` über den Registrierungsmodus.
Umschließt `definePluginEntry` mit kanalspezifischer Verdrahtung. Ruft automatisch
`api.registerChannel({ plugin })` auf, stellt einen optionalen CLI-Metadaten-Einstiegspunkt
für die Root-Hilfe bereit und steuert `registerFull` anhand des Registrierungsmodus.
```typescript
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
@ -91,35 +89,36 @@ export default defineChannelPluginEntry({
});
```
| Feld | Typ | Erforderlich | Standard |
| Feld | Typ | Erforderlich | Standardwert |
| --------------------- | ---------------------------------------------------------------- | ------------ | ------------------- |
| `id` | `string` | Ja | — |
| `name` | `string` | Ja | — |
| `description` | `string` | Ja | — |
| `plugin` | `ChannelPlugin` | Ja | — |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Nein | Schema für leeres Objekt |
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Nein | Leeres Objektschema |
| `setRuntime` | `(runtime: PluginRuntime) => void` | Nein | — |
| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Nein | — |
| `registerFull` | `(api: OpenClawPluginApi) => void` | Nein | — |
- `setRuntime` wird während der Registrierung aufgerufen, damit Sie die Runtime-Referenz speichern können
(typischerweise über `createPluginRuntimeStore`). Während der Erfassung von CLI-Metadaten
wird dies übersprungen.
- `setRuntime` wird bei der Registrierung aufgerufen, damit Sie die Runtime-Referenz speichern können
(typischerweise über `createPluginRuntimeStore`). Beim Erfassen von CLI-Metadaten
wird es übersprungen.
- `registerCliMetadata` wird sowohl bei `api.registrationMode === "cli-metadata"`
als auch bei `api.registrationMode === "full"` ausgeführt.
Verwenden Sie dies als maßgeblichen Ort für dem Kanal gehörende CLI-Deskriptoren, damit die Root-Hilfe
nicht aktivierend bleibt, während die normale Registrierung von CLI-Befehlen mit vollständigen Plugin-Ladevorgängen
kompatibel bleibt.
- `registerFull` wird nur ausgeführt, wenn `api.registrationMode === "full"` gilt. Es wird
beim reinen Setup-Laden übersprungen.
Verwenden Sie es als die kanonische Stelle für kanal-eigene CLI-Deskriptoren, damit die Root-Hilfe
nicht aktivierend bleibt, während die normale CLI-Befehlsregistrierung mit
vollständigen Plugin-Ladevorgängen kompatibel bleibt.
- `registerFull` wird nur ausgeführt, wenn `api.registrationMode === "full"` ist. Bei
reinen Setup-Ladevorgängen wird es übersprungen.
- Wie bei `definePluginEntry` kann `configSchema` eine Lazy-Factory sein, und OpenClaw
memoisiert das aufgelöste Schema beim ersten Zugriff.
- Für Root-CLI-Befehle, die dem Plugin gehören, bevorzugen Sie `api.registerCli(..., { descriptors: [...] })`,
wenn der Befehl lazy-loaded bleiben soll, ohne aus dem Root-CLI-Parsebaum zu verschwinden.
Bei Channel-Plugins sollten diese Deskriptoren bevorzugt aus `registerCliMetadata(...)`
registriert werden, und `registerFull(...)` sollte sich auf reine Laufzeitarbeit konzentrieren.
- Wenn `registerFull(...)` auch Gateway-RPC-Methoden registriert, behalten Sie diese unter einem
pluginspezifischen Präfix. Reservierte Kern-Admin-Namespaces (`config.*`,
- Für Plugin-eigene Root-CLI-Befehle sollten Sie `api.registerCli(..., { descriptors: [...] })`
bevorzugen, wenn der Befehl lazy-loaded bleiben soll, ohne aus dem
Root-CLI-Parse-Baum zu verschwinden. Bei Kanal-Plugins sollten Sie diese Deskriptoren
vorzugsweise aus `registerCliMetadata(...)` registrieren und `registerFull(...)` auf
Arbeiten beschränken, die nur zur Laufzeit nötig sind.
- Wenn `registerFull(...)` auch Gateway-RPC-Methoden registriert, halten Sie diese unter einem
pluginspezifischen Präfix. Reservierte Core-Admin-Namespaces (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) werden immer zu
`operator.admin` umgewandelt.
@ -136,33 +135,58 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
export default defineSetupPluginEntry(myChannelPlugin);
```
OpenClaw lädt dies anstelle des vollständigen Einstiegspunkts, wenn ein Kanal deaktiviert,
nicht konfiguriert ist oder wenn verzögertes Laden aktiviert ist. Unter
[Setup and Config](/plugins/sdk-setup#setup-entry) finden Sie Informationen dazu, wann das wichtig ist.
OpenClaw lädt dies anstelle des vollständigen Einstiegs, wenn ein Kanal deaktiviert,
nicht konfiguriert ist oder wenn verzögertes Laden aktiviert ist. Siehe
[Setup und Konfiguration](/de/plugins/sdk-setup#setup-entry), wann dies wichtig ist.
In der Praxis kombinieren Sie `defineSetupPluginEntry(...)` mit den schmalen Setup-Hilfsfamilien:
- `openclaw/plugin-sdk/setup-runtime` für laufzeitsichere Setup-Hilfen wie
import-sichere Setup-Patch-Adapter, Ausgabe von Lookup-Hinweisen,
- `openclaw/plugin-sdk/setup-runtime` für runtime-sichere Setup-Helfer wie
importsichere Setup-Patch-Adapter, Ausgabe von Lookup-Hinweisen,
`promptResolvedAllowFrom`, `splitSetupEntries` und delegierte Setup-Proxys
- `openclaw/plugin-sdk/channel-setup` für optionale Installations-Setup-Oberflächen
- `openclaw/plugin-sdk/setup-tools` für Setup-/Installations-CLI-/Archiv-/Dokumentationshilfen
- `openclaw/plugin-sdk/setup-tools` für Setup-/Installations-CLI-/Archiv-/Dokumentations-Helfer
Behalten Sie schwere SDKs, CLI-Registrierung und langlebige Laufzeitdienste im vollständigen
Einstiegspunkt.
Behalten Sie schwere SDKs, CLI-Registrierung und langlebige Runtime-Dienste im vollständigen
Einstieg.
Gebündelte Workspace-Kanäle, die Setup- und Runtime-Oberflächen aufteilen, können stattdessen
`defineBundledChannelSetupEntry(...)` aus
`openclaw/plugin-sdk/channel-entry-contract` verwenden. Dieser Vertrag ermöglicht es dem
Setup-Einstieg, setupsichere Plugin-/Secret-Exporte beizubehalten und gleichzeitig einen
Runtime-Setter bereitzustellen:
```typescript
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
export default defineBundledChannelSetupEntry({
importMetaUrl: import.meta.url,
plugin: {
specifier: "./channel-plugin-api.js",
exportName: "myChannelPlugin",
},
runtime: {
specifier: "./runtime-api.js",
exportName: "setMyChannelRuntime",
},
});
```
Verwenden Sie diesen gebündelten Vertrag nur dann, wenn Setup-Flows wirklich einen leichtgewichtigen Runtime-Setter
benötigen, bevor der vollständige Kanaleinstieg geladen wird.
## Registrierungsmodus
`api.registrationMode` zeigt Ihrem Plugin, wie es geladen wurde:
`api.registrationMode` teilt Ihrem Plugin mit, wie es geladen wurde:
| Modus | Wann | Was registriert werden soll |
| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------------- |
| `"full"` | Normaler Gateway-Start | Alles |
| `"setup-only"` | Deaktivierter/nicht konfigurierter Kanal | Nur Kanalregistrierung |
| `"setup-runtime"` | Setup-Ablauf mit verfügbarer Runtime | Kanalregistrierung plus nur die schlanke Runtime, die vor dem Laden des vollständigen Einstiegspunkts benötigt wird |
| `"cli-metadata"` | Root-Hilfe / Erfassung von CLI-Metadaten | Nur CLI-Deskriptoren |
| Modus | Wann | Was registriert werden soll |
| ----------------- | --------------------------------- | -------------------------------------------------------------------------------------------- |
| `"full"` | Normaler Gateway-Start | Alles |
| `"setup-only"` | Deaktivierter/nicht konfigurierter Kanal | Nur Kanalregistrierung |
| `"setup-runtime"` | Setup-Flow mit verfügbarer Runtime | Kanalregistrierung plus nur die leichtgewichtige Runtime, die vor dem Laden des vollständigen Einstiegs benötigt wird |
| `"cli-metadata"` | Root-Hilfe / Erfassung von CLI-Metadaten | Nur CLI-Deskriptoren |
`defineChannelPluginEntry` übernimmt diese Aufteilung automatisch. Wenn Sie
`defineChannelPluginEntry` behandelt diese Aufteilung automatisch. Wenn Sie
`definePluginEntry` direkt für einen Kanal verwenden, prüfen Sie den Modus selbst:
```typescript
@ -175,24 +199,24 @@ register(api) {
api.registerChannel({ plugin: myPlugin });
if (api.registrationMode !== "full") return;
// Schwere Registrierungen nur für die Laufzeit
// Schwere Registrierungen nur zur Laufzeit
api.registerService(/* ... */);
}
```
Behandeln Sie `"setup-runtime"` als das Fenster, in dem reine Setup-Startoberflächen
vorhanden sein müssen, ohne die vollständige gebündelte Kanal-Runtime erneut zu betreten. Geeignet sind
Behandeln Sie `"setup-runtime"` als das Zeitfenster, in dem Setup-only-Startoberflächen
vorhanden sein müssen, ohne die vollständige gebündelte Kanal-Runtime erneut zu betreten. Geeignete Anwendungsfälle sind
Kanalregistrierung, setupsichere HTTP-Routen, setupsichere Gateway-Methoden und
delegierte Setup-Hilfen. Schwere Hintergrunddienste, CLI-Registrierer und
delegierte Setup-Helfer. Schwere Hintergrunddienste, CLI-Registrare und
Provider-/Client-SDK-Bootstraps gehören weiterhin in `"full"`.
Speziell für CLI-Registrierer gilt:
Speziell für CLI-Registrare gilt:
- verwenden Sie `descriptors`, wenn der Registrierer einen oder mehrere Root-Befehle besitzt und Sie
möchten, dass OpenClaw das echte CLI-Modul beim ersten Aufruf lazy lädt
- stellen Sie sicher, dass diese Deskriptoren jeden Top-Level-Befehlsstamm abdecken, der vom
Registrierer bereitgestellt wird
- verwenden Sie `commands` allein nur für eager-kompatible Pfade
- verwenden Sie `descriptors`, wenn der Registrar einen oder mehrere Root-Befehle besitzt und Sie
möchten, dass OpenClaw das eigentliche CLI-Modul beim ersten Aufruf lazy-loaded
- stellen Sie sicher, dass diese Deskriptoren jeden Top-Level-Befehls-Root abdecken, der vom
Registrar bereitgestellt wird
- verwenden Sie nur `commands` für eager Kompatibilitätspfade
## Plugin-Formen
@ -200,17 +224,17 @@ OpenClaw klassifiziert geladene Plugins nach ihrem Registrierungsverhalten:
| Form | Beschreibung |
| ------------------- | ------------------------------------------------- |
| **plain-capability** | Ein Funktionstyp (z. B. nur Provider) |
| **hybrid-capability** | Mehrere Funktionstypen (z. B. Provider + Speech) |
| **hook-only** | Nur Hooks, keine Funktionen |
| **non-capability** | Tools/Befehle/Dienste, aber keine Funktionen |
| **plain-capability** | Ein Fähigkeitstyp (z. B. nur Provider) |
| **hybrid-capability** | Mehrere Fähigkeitstypen (z. B. Provider + Sprache) |
| **hook-only** | Nur Hooks, keine Fähigkeiten |
| **non-capability** | Tools/Befehle/Dienste, aber keine Fähigkeiten |
Verwenden Sie `openclaw plugins inspect <id>`, um die Form eines Plugins anzuzeigen.
## Verwandt
- [SDK-Überblick](/plugins/sdk-overview) — Registrierungs-API und Subpfad-Referenz
- [Runtime-Hilfen](/plugins/sdk-runtime) — `api.runtime` und `createPluginRuntimeStore`
- [Setup und Konfiguration](/plugins/sdk-setup) — Manifest, Setup-Einstiegspunkt, verzögertes Laden
- [Channel Plugins](/plugins/sdk-channel-plugins) — das `ChannelPlugin`-Objekt erstellen
- [Provider Plugins](/plugins/sdk-provider-plugins) — Provider-Registrierung und Hooks
- [SDK-Überblick](/de/plugins/sdk-overview) — Registrierungs-API und Subpath-Referenz
- [Runtime-Helfer](/de/plugins/sdk-runtime) — `api.runtime` und `createPluginRuntimeStore`
- [Setup und Konfiguration](/de/plugins/sdk-setup) — Manifest, Setup-Einstieg, verzögertes Laden
- [Kanal-Plugins](/de/plugins/sdk-channel-plugins) — Erstellen des `ChannelPlugin`-Objekts
- [Provider-Plugins](/de/plugins/sdk-provider-plugins) — Provider-Registrierung und Hooks

118
docs/de/plugins/sdk-runtime.md
View File

@ -1,29 +1,28 @@
---
read_when:
- Sie müssen Core-Hilfsfunktionen aus einem Plugin aufrufen (TTS, STT, Bildgenerierung, Websuche, Subagent)
- Sie müssen Core-Helfer aus einem Plugin aufrufen (TTS, STT, Bildgenerierung, Websuche, Subagent)
- Sie möchten verstehen, was `api.runtime` bereitstellt
- Sie greifen aus Plugin-Code auf Konfigurations-, Agenten- oder Medien-Hilfsfunktionen zu
- Sie greifen aus Plugin-Code auf Konfigurations-, Agent- oder Medien-Helfer zu
sidebarTitle: Runtime Helpers
summary: api.runtime -- die injizierten Laufzeit-Hilfsfunktionen, die Plugins zur Verfügung stehen
title: Plugin-Laufzeit-Hilfsfunktionen
summary: api.runtime -- die injizierten Runtime-Helfer, die Plugins zur Verfügung stehen
title: Plugin-Runtime-Helfer
x-i18n:
generated_at: "2026-04-11T02:46:50Z"
generated_at: "2026-04-15T19:41:34Z"
model: gpt-5.4
provider: openai
source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be
source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8
source_path: plugins/sdk-runtime.md
workflow: 15
---
# Plugin-Laufzeit-Hilfsfunktionen
# Plugin-Runtime-Helfer
Referenz für das `api.runtime`-Objekt, das jedem Plugin bei der
Registrierung injiziert wird. Verwenden Sie diese Hilfsfunktionen, anstatt Host-Interna direkt zu importieren.
Referenz für das `api.runtime`-Objekt, das bei der Registrierung in jedes Plugin injiziert wird. Verwenden Sie diese Helfer, anstatt Host-Interna direkt zu importieren.
<Tip>
**Suchen Sie eine Schritt-für-Schritt-Anleitung?** Unter [Kanal-Plugins](/de/plugins/sdk-channel-plugins)
oder [Provider-Plugins](/de/plugins/sdk-provider-plugins) finden Sie Anleitungen
mit diesen Hilfsfunktionen im Kontext.
**Suchen Sie nach einer Schritt-für-Schritt-Anleitung?** Siehe [Channel-Plugins](/de/plugins/sdk-channel-plugins)
oder [Provider-Plugins](/de/plugins/sdk-provider-plugins) für Schritt-für-Schritt-Anleitungen,
die diese Helfer im Kontext zeigen.
</Tip>
```typescript
@ -32,32 +31,32 @@ register(api) {
}
```
## Laufzeit-Namespaces
## Runtime-Namespaces
### `api.runtime.agent`
Agentenidentität, Verzeichnisse und Sitzungsverwaltung.
Agent-Identität, Verzeichnisse und Sitzungsverwaltung.
```typescript
// Arbeitsverzeichnis des Agenten auflösen
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
// Agenten-Workspace auflösen
// Agent-Workspace auflösen
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
// Agentenidentität abrufen
// Agent-Identität abrufen
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
// Standard-Thinking-Stufe abrufen
// Standard-Thinkinglevel abrufen
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);
// Agenten-Zeitlimit abrufen
// Agent-Timeout abrufen
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
// Sicherstellen, dass der Workspace existiert
await api.runtime.agent.ensureAgentWorkspace(cfg);
// Einen eingebetteten Agentenzug ausführen
// Einen eingebetteten Agent-Durchlauf ausführen
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
const result = await api.runtime.agent.runEmbeddedAgent({
sessionId: "my-plugin:task-1",
@ -69,13 +68,11 @@ const result = await api.runtime.agent.runEmbeddedAgent({
});
```
`runEmbeddedAgent(...)` ist die neutrale Hilfsfunktion zum Starten eines normalen OpenClaw-
Agentenzugs aus Plugin-Code. Sie verwendet dieselbe Auflösung von Provider/Modell und
dieselbe Auswahl des Agent-Harness wie kanalgetriggerte Antworten.
`runEmbeddedAgent(...)` ist der neutrale Helfer zum Starten eines normalen OpenClaw-Agent-Durchlaufs aus Plugin-Code. Er verwendet dieselbe Provider-/Modellauflösung und dieselbe Agent-Harness-Auswahl wie kanalgetriggerte Antworten.
`runEmbeddedPiAgent(...)` bleibt als Kompatibilitätsalias bestehen.
`runEmbeddedPiAgent(...)` bleibt als Kompatibilitätsalias erhalten.
**Hilfsfunktionen für den Sitzungsspeicher** befinden sich unter `api.runtime.agent.session`:
**Sitzungsspeicher-Helfer** befinden sich unter `api.runtime.agent.session`:
```typescript
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
@ -107,7 +104,7 @@ const { runId } = await api.runtime.subagent.run({
deliver: false,
});
// Auf den Abschluss warten
// Auf Abschluss warten
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });
// Sitzungsnachrichten lesen
@ -123,15 +120,14 @@ await api.runtime.subagent.deleteSession({
```
<Warning>
Modellüberschreibungen (`provider`/`model`) erfordern ein Opt-in des Operators über
Modellüberschreibungen (`provider`/`model`) erfordern eine ausdrückliche Freigabe durch den Operator über
`plugins.entries.<id>.subagent.allowModelOverride: true` in der Konfiguration.
Nicht vertrauenswürdige Plugins können weiterhin Subagents ausführen, aber Überschreibungsanfragen werden abgelehnt.
</Warning>
### `api.runtime.taskFlow`
Eine Task-Flow-Laufzeit an einen vorhandenen OpenClaw-Sitzungsschlüssel oder einen vertrauenswürdigen Tool-
Kontext binden und dann Task Flows erstellen und verwalten, ohne bei jedem Aufruf einen Owner zu übergeben.
Eine TaskFlow-Runtime an einen vorhandenen OpenClaw-Sitzungsschlüssel oder einen vertrauenswürdigen Tool-Kontext binden und dann TaskFlows erstellen und verwalten, ohne bei jedem Aufruf einen Eigentümer zu übergeben.
```typescript
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
@ -158,9 +154,7 @@ const waiting = taskFlow.setWaiting({
});
```
Verwenden Sie `bindSession({ sessionKey, requesterOrigin })`, wenn Sie bereits einen
vertrauenswürdigen OpenClaw-Sitzungsschlüssel aus Ihrer eigenen Bindungsschicht haben. Binden Sie nicht aus roher
Benutzereingabe.
Verwenden Sie `bindSession({ sessionKey, requesterOrigin })`, wenn Sie bereits einen vertrauenswürdigen OpenClaw-Sitzungsschlüssel aus Ihrer eigenen Bindungsschicht haben. Binden Sie nicht aus rohen Benutzereingaben.
### `api.runtime.tts`
@ -186,8 +180,7 @@ const voices = await api.runtime.tts.listVoices({
});
```
Verwendet die Core-Konfiguration `messages.tts` und die Providerauswahl. Gibt einen PCM-Audio-
Puffer + Samplerate zurück.
Verwendet die Core-Konfiguration `messages.tts` und die Providerauswahl. Gibt einen PCM-Audiopuffer plus Abtastrate zurück.
### `api.runtime.mediaUnderstanding`
@ -205,7 +198,7 @@ const image = await api.runtime.mediaUnderstanding.describeImageFile({
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
filePath: "/tmp/inbound-audio.ogg",
cfg: api.config,
mime: "audio/ogg", // optional, wenn MIME nicht abgeleitet werden kann
mime: "audio/ogg", // optional, wenn der MIME-Typ nicht abgeleitet werden kann
});
// Ein Video beschreiben
@ -221,11 +214,11 @@ const result = await api.runtime.mediaUnderstanding.runFile({
});
```
Gibt `{ text: undefined }` zurück, wenn keine Ausgabe erzeugt wird (z. B. bei übersprungener Eingabe).
Gibt `{ text: undefined }` zurück, wenn keine Ausgabe erzeugt wird (z. B. bei übersprungenen Eingaben).
<Info>
`api.runtime.stt.transcribeAudioFile(...)` bleibt als Kompatibilitätsalias
für `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` bestehen.
`api.runtime.stt.transcribeAudioFile(...)` bleibt als Kompatibilitätsalias für
`api.runtime.mediaUnderstanding.transcribeAudioFile(...)` erhalten.
</Info>
### `api.runtime.imageGeneration`
@ -256,7 +249,7 @@ const result = await api.runtime.webSearch.search({
### `api.runtime.media`
Low-Level-Medien-Hilfsfunktionen.
Low-Level-Medienwerkzeuge.
```typescript
const webMedia = await api.runtime.media.loadWebMedia(url);
@ -278,7 +271,7 @@ await api.runtime.config.writeConfigFile(cfg);
### `api.runtime.system`
Hilfsfunktionen auf Systemebene.
Dienstprogramme auf Systemebene.
```typescript
await api.runtime.system.enqueueSystemEvent(event);
@ -302,7 +295,7 @@ api.runtime.events.onSessionTranscriptUpdate((update) => {
### `api.runtime.logging`
Logging.
Protokollierung.
```typescript
const verbose = api.runtime.logging.shouldLogVerbose();
@ -311,7 +304,7 @@ const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" },
### `api.runtime.modelAuth`
Auflösung von Modell- und Provider-Auth.
Auflösung der Authentifizierung für Modell und Provider.
```typescript
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
@ -323,7 +316,7 @@ const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
### `api.runtime.state`
Auflösung des State-Verzeichnisses.
Auflösung des Statusverzeichnisses.
```typescript
const stateDir = api.runtime.state.resolveStateDir();
@ -331,7 +324,7 @@ const stateDir = api.runtime.state.resolveStateDir();
### `api.runtime.tools`
Factories und CLI für Memory-Tools.
Active Memory-Toolfabriken und CLI.
```typescript
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
@ -341,10 +334,9 @@ api.runtime.tools.registerMemoryCli(/* ... */);
### `api.runtime.channel`
Kanalspezifische Laufzeit-Hilfsfunktionen (verfügbar, wenn ein Kanal-Plugin geladen ist).
Kanalspezifische Runtime-Helfer (verfügbar, wenn ein Channel-Plugin geladen ist).
`api.runtime.channel.mentions` ist die gemeinsame Oberfläche für die Mention-Richtlinie bei eingehenden Nachrichten für
gebündelte Kanal-Plugins, die Laufzeitinjektion verwenden:
`api.runtime.channel.mentions` ist die gemeinsame Oberfläche für die Erwähnungsrichtlinie bei eingehenden Nachrichten für gebündelte Channel-Plugins, die Runtime-Injektion verwenden:
```typescript
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
@ -371,7 +363,7 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
});
```
Verfügbare Mention-Hilfsfunktionen:
Verfügbare Erwähnungshelfer:
- `buildMentionRegexes`
- `matchesMentionPatterns`
@ -379,20 +371,20 @@ Verfügbare Mention-Hilfsfunktionen:
- `implicitMentionKindWhen`
- `resolveInboundMentionDecision`
`api.runtime.channel.mentions` stellt absichtlich nicht die älteren
Kompatibilitäts-Hilfsfunktionen `resolveMentionGating*` bereit. Bevorzugen Sie den normalisierten
Pfad `{ facts, policy }`.
`api.runtime.channel.mentions` stellt die älteren Kompatibilitätshelfer `resolveMentionGating*` absichtlich nicht bereit. Bevorzugen Sie den normalisierten Pfad `{ facts, policy }`.
## Laufzeitreferenzen speichern
## Runtime-Referenzen speichern
Verwenden Sie `createPluginRuntimeStore`, um die Laufzeitreferenz für die Nutzung außerhalb
des `register`-Callbacks zu speichern:
Verwenden Sie `createPluginRuntimeStore`, um die Runtime-Referenz zur Verwendung außerhalb des Callbacks `register` zu speichern:
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
const store = createPluginRuntimeStore<PluginRuntime>("my-plugin runtime not initialized");
const store = createPluginRuntimeStore<PluginRuntime>({
pluginId: "my-plugin",
errorMessage: "my-plugin runtime not initialized",
});
// In Ihrem Einstiegspunkt
export default defineChannelPluginEntry({
@ -405,7 +397,7 @@ export default defineChannelPluginEntry({
// In anderen Dateien
export function getRuntime() {
return store.getRuntime(); // wirft einen Fehler, wenn nicht initialisiert
return store.getRuntime(); // löst einen Fehler aus, wenn nicht initialisiert
}
export function tryGetRuntime() {
@ -413,22 +405,24 @@ export function tryGetRuntime() {
}
```
Bevorzugen Sie `pluginId` für die Identität des Runtime-Store. Die Low-Level-Form `key` ist für ungewöhnliche Fälle gedacht, in denen ein Plugin absichtlich mehr als einen Runtime-Slot benötigt.
## Andere Top-Level-Felder in `api`
Zusätzlich zu `api.runtime` stellt das API-Objekt außerdem Folgendes bereit:
Zusätzlich zu `api.runtime` stellt das API-Objekt auch Folgendes bereit:
| Feld | Typ | Beschreibung |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Plugin-ID |
| `api.name` | `string` | Anzeigename des Plugins |
| `api.config` | `OpenClawConfig` | Aktueller Konfigurations-Snapshot (aktiver In-Memory-Laufzeit-Snapshot, wenn verfügbar) |
| `api.pluginConfig` | `Record<string, unknown>` | Pluginspezifische Konfiguration aus `plugins.entries.<id>.config` |
| `api.logger` | `PluginLogger` | Bereichsspezifischer Logger (`debug`, `info`, `warn`, `error`) |
| `api.config` | `OpenClawConfig` | Aktueller Konfigurations-Snapshot (aktiver In-Memory-Runtime-Snapshot, wenn verfügbar) |
| `api.pluginConfig` | `Record<string, unknown>` | Plugin-spezifische Konfiguration aus `plugins.entries.<id>.config` |
| `api.logger` | `PluginLogger` | Bereichsbezogener Logger (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Aktueller Lademodus; `"setup-runtime"` ist das leichtgewichtige Startup-/Setup-Fenster vor dem vollständigen Entry |
| `api.resolvePath(input)` | `(string) => string` | Einen Pfad relativ zum Plugin-Root auflösen |
## Verwandt
- [SDK Overview](/de/plugins/sdk-overview) -- Referenz für Subpaths
- [SDK Entry Points](/de/plugins/sdk-entrypoints) -- Optionen für `definePluginEntry`
- [Plugin Internals](/de/plugins/architecture) -- Fähigkeitsmodell und Registry
- [SDK-Überblick](/de/plugins/sdk-overview) -- Subpath-Referenz
- [SDK-Einstiegspunkte](/de/plugins/sdk-entrypoints) -- Optionen für `definePluginEntry`
- [Plugin-Interna](/de/plugins/architecture) -- Fähigkeitsmodell und Registry

340
docs/de/plugins/sdk-setup.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Sie fügen einem Plugin einen Setup-Assistenten hinzu
- Sie müssen den Unterschied zwischen setup-entry.ts und index.ts verstehen
- Sie definieren Plugin-Konfigurationsschemas oder openclaw-Metadaten in package.json
- Du fügst einem Plugin einen Einrichtungsassistenten hinzu.
- Du musst `setup-entry.ts` im Vergleich zu `index.ts` verstehen.
- Du definierst Plugin-Konfigurationsschemata oder `package.json`-`openclaw`-Metadaten.
sidebarTitle: Setup and Config
summary: Setup-Assistenten, setup-entry.ts, Konfigurationsschemas und package.json-Metadaten
title: Plugin-Setup und Konfiguration
summary: Einrichtungsassistenten, setup-entry.ts, Konfigurationsschemata und package.json-Metadaten
title: Plugin-Einrichtung und -Konfiguration
x-i18n:
generated_at: "2026-04-06T03:10:48Z"
generated_at: "2026-04-15T19:42:33Z"
model: gpt-5.4
provider: openai
source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9
source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b
source_path: plugins/sdk-setup.md
workflow: 15
---
# Plugin-Setup und Konfiguration
# Plugin-Einrichtung und -Konfiguration
Referenz für Plugin-Paketierung (`package.json`-Metadaten), Manifeste
(`openclaw.plugin.json`), Setup-Einträge und Konfigurationsschemas.
(`openclaw.plugin.json`), Setup-Einstiegspunkte und Konfigurationsschemata.
<Tip>
**Suchen Sie nach einer Schritt-für-Schritt-Anleitung?** Die How-to-Anleitungen behandeln Paketierung im Kontext:
[Kanal-Plugins](/de/plugins/sdk-channel-plugins#step-1-package-and-manifest) und
[Provider-Plugins](/de/plugins/sdk-provider-plugins#step-1-package-and-manifest).
**Suchst du nach einer Schritt-für-Schritt-Anleitung?** Die How-to-Guides behandeln die Paketierung im Kontext:
[Channel Plugins](/de/plugins/sdk-channel-plugins#step-1-package-and-manifest) und
[Provider Plugins](/de/plugins/sdk-provider-plugins#step-1-package-and-manifest).
</Tip>
## Paketmetadaten
## Paket-Metadaten
Ihre `package.json` benötigt ein Feld `openclaw`, das dem Plugin-System mitteilt, was
Ihr Plugin bereitstellt:
Deine `package.json` benötigt ein `openclaw`-Feld, das dem Plugin-System mitteilt,
was dein Plugin bereitstellt:
**Kanal-Plugin:**
@ -50,7 +50,7 @@ Ihr Plugin bereitstellt:
}
```
**Provider-Plugin / ClawHub-Veröffentlichungsbaseline:**
**Provider Plugin / ClawHub-Veröffentlichungsbasis:**
```json openclaw-clawhub-package.json
{
@ -71,47 +71,47 @@ Ihr Plugin bereitstellt:
}
```
Wenn Sie das Plugin extern auf ClawHub veröffentlichen, sind diese Felder `compat` und `build`
erforderlich. Die kanonischen Snippets für die Veröffentlichung finden Sie in
Wenn du das Plugin extern auf ClawHub veröffentlichst, sind diese `compat`- und `build`-
Felder erforderlich. Die kanonischen Veröffentlichungs-Snippets befinden sich in
`docs/snippets/plugin-publish/`.
### `openclaw`-Felder
| Feld | Typ | Beschreibung |
| ------------ | ---------- | -------------------------------------------------------------------------------------------------------- |
| `extensions` | `string[]` | Einstiegspunktdateien (relativ zum Paketstamm) |
| `setupEntry` | `string` | Leichtgewichtiger Einstiegspunkt nur für Setup (optional) |
| `channel` | `object` | Metadaten des Kanalkatalogs für Setup, Picker, Quickstart- und Statusoberflächen |
| `providers` | `string[]` | Provider-IDs, die von diesem Plugin registriert werden |
| Feld | Typ | Beschreibung |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |
| `extensions` | `string[]` | Einstiegspunktdateien (relativ zum Paketstamm) |
| `setupEntry` | `string` | Leichtgewichtiger, nur für das Setup verwendeter Einstiegspunkt (optional) |
| `channel` | `object` | Kanal-Katalogmetadaten für Setup-, Auswahl-, Schnellstart- und Status-Oberflächen |
| `providers` | `string[]` | Provider-IDs, die von diesem Plugin registriert werden |
| `install` | `object` | Installationshinweise: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` |
| `startup` | `object` | Flags für das Startverhalten |
| `startup` | `object` | Flags für das Startverhalten |
### `openclaw.channel`
`openclaw.channel` sind kostengünstige Paketmetadaten für Kanalerkennung und Setup-
Oberflächen, bevor die Laufzeit geladen wird.
`openclaw.channel` sind kostengünstige Paket-Metadaten für die Kanalerkennung und
Setup-Oberflächen, bevor die Laufzeit geladen wird.
| Feld | Typ | Bedeutung |
| -------------------------------------- | ---------- | -------------------------------------------------------------------------------- |
| `id` | `string` | Kanonische Kanal-ID. |
| `label` | `string` | Primäre Kanalbezeichnung. |
| `selectionLabel` | `string` | Bezeichnung für Picker/Setup, wenn sie sich von `label` unterscheiden soll. |
| `detailLabel` | `string` | Sekundäre Detailbezeichnung für umfangreichere Kanalkataloge und Statusoberflächen. |
| `docsPath` | `string` | Docs-Pfad für Setup- und Auswahllinks. |
| `docsLabel` | `string` | Überschreibungsbezeichnung für Docs-Links, wenn sie sich von der Kanal-ID unterscheiden soll. |
| `blurb` | `string` | Kurze Beschreibung für Onboarding/Katalog. |
| `order` | `number` | Sortierreihenfolge in Kanalkatalogen. |
| `aliases` | `string[]` | Zusätzliche Lookup-Aliasse für die Kanalauswahl. |
| `preferOver` | `string[]` | Plugin-/Kanal-IDs mit niedrigerer Priorität, die dieser Kanal übertreffen soll. |
| `systemImage` | `string` | Optionaler Symbol-/Systembildname für Kanal-UI-Kataloge. |
| `selectionDocsPrefix` | `string` | Präfixtext vor Docs-Links in Auswahloberflächen. |
| `selectionDocsOmitLabel` | `boolean` | Zeigt den Docs-Pfad direkt anstelle eines beschrifteten Docs-Links im Auswahltext. |
| `selectionExtras` | `string[]` | Zusätzliche kurze Zeichenfolgen, die im Auswahltext angehängt werden. |
| `markdownCapable` | `boolean` | Markiert den Kanal als markdownfähig für Entscheidungen zur ausgehenden Formatierung. |
| `exposure` | `object` | Steuerung der Kanalsichtbarkeit für Setup, konfigurierte Listen und Docs-Oberflächen. |
| `quickstartAllowFrom` | `boolean` | Meldet diesen Kanal für den standardmäßigen Quickstart-`allowFrom`-Setup-Ablauf an. |
| `forceAccountBinding` | `boolean` | Erzwingt explizites Account-Binding, selbst wenn nur ein Konto existiert. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | Bevorzugt Session-Lookup beim Auflösen von Ankündigungszielen für diesen Kanal. |
| Feld | Typ | Bedeutung |
| -------------------------------------- | ---------- | ------------------------------------------------------------------------------ |
| `id` | `string` | Kanonische Kanal-ID. |
| `label` | `string` | Primäre Kanalbezeichnung. |
| `selectionLabel` | `string` | Bezeichnung für Auswahl/Setup, wenn sie sich von `label` unterscheiden soll. |
| `detailLabel` | `string` | Sekundäre Detailbezeichnung für umfangreichere Kanalkataloge und Statusansichten. |
| `docsPath` | `string` | Dokumentationspfad für Setup- und Auswahllinks. |
| `docsLabel` | `string` | Überschriebene Bezeichnung für Dokumentationslinks, wenn sie sich von der Kanal-ID unterscheiden soll. |
| `blurb` | `string` | Kurze Beschreibung für Onboarding/Katalog. |
| `order` | `number` | Sortierreihenfolge in Kanalkatalogen. |
| `aliases` | `string[]` | Zusätzliche Suchaliase für die Kanalauswahl. |
| `preferOver` | `string[]` | IDs von Plugins/Kanälen mit niedrigerer Priorität, die von diesem Kanal übertroffen werden sollen. |
| `systemImage` | `string` | Optionaler Symbol-/Systembildname für Kanal-UI-Kataloge. |
| `selectionDocsPrefix` | `string` | Präfixtext vor Dokumentationslinks in Auswahloberflächen. |
| `selectionDocsOmitLabel` | `boolean` | Zeigt den Dokumentationspfad direkt anstelle eines beschrifteten Dokumentationslinks im Auswahltext an. |
| `selectionExtras` | `string[]` | Zusätzliche kurze Zeichenfolgen, die im Auswahltext angehängt werden. |
| `markdownCapable` | `boolean` | Kennzeichnet den Kanal als Markdown-fähig für Entscheidungen zur ausgehenden Formatierung. |
| `exposure` | `object` | Sichtbarkeitssteuerung des Kanals für Setup-, konfigurierte Listen- und Dokumentationsoberflächen. |
| `quickstartAllowFrom` | `boolean` | Nimmt diesen Kanal in den standardmäßigen Schnellstart-`allowFrom`-Setup-Ablauf auf. |
| `forceAccountBinding` | `boolean` | Erzwingt explizite Kontobindung, selbst wenn nur ein Konto vorhanden ist. |
| `preferSessionLookupForAnnounceTarget` | `boolean` | Bevorzugt die Sitzungssuche beim Auflösen von Ankündigungszielen für diesen Kanal. |
Beispiel:
@ -145,37 +145,37 @@ Beispiel:
`exposure` unterstützt:
- `configured`: schließt den Kanal in Oberflächen für konfigurierte/statusartige Listen ein
- `setup`: schließt den Kanal in interaktive Setup-/Konfigurations-Picker ein
- `docs`: markiert den Kanal als öffentlich sichtbar in Docs-/Navigationsoberflächen
- `configured`: nimmt den Kanal in konfigurierte/statusartige Listenoberflächen auf
- `setup`: nimmt den Kanal in interaktive Setup-/Konfigurationsauswahlen auf
- `docs`: markiert den Kanal als öffentlich sichtbar in Dokumentations-/Navigationsoberflächen
`showConfigured` und `showInSetup` werden weiterhin als veraltete Aliasse unterstützt. Bevorzugen Sie
`showConfigured` und `showInSetup` werden weiterhin als Legacy-Aliase unterstützt. Bevorzuge
`exposure`.
### `openclaw.install`
`openclaw.install` sind Paketmetadaten, keine Manifestmetadaten.
`openclaw.install` sind Paket-Metadaten, keine Manifest-Metadaten.
| Feld | Typ | Bedeutung |
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
| `npmSpec` | `string` | Kanonische npm-Spezifikation für Installations-/Aktualisierungsabläufe. |
| `localPath` | `string` | Lokaler Entwicklungs- oder gebündelter Installationspfad. |
| `defaultChoice` | `"npm"` \| `"local"` | Bevorzugte Installationsquelle, wenn beide verfügbar sind. |
| `minHostVersion` | `string` | Mindestunterstützte OpenClaw-Version in der Form `>=x.y.z`. |
| `allowInvalidConfigRecovery` | `boolean` | Ermöglicht Reinstallationsabläufen für gebündelte Plugins die Wiederherstellung nach bestimmten veralteten Konfigurationsfehlern. |
| Feld | Typ | Bedeutung |
| ---------------------------- | -------------------- | ------------------------------------------------------------------------------- |
| `npmSpec` | `string` | Kanonische npm-Spezifikation für Installations-/Update-Abläufe. |
| `localPath` | `string` | Lokaler Entwicklungs- oder gebündelter Installationspfad. |
| `defaultChoice` | `"npm"` \| `"local"` | Bevorzugte Installationsquelle, wenn beide verfügbar sind. |
| `minHostVersion` | `string` | Minimal unterstützte OpenClaw-Version im Format `>=x.y.z`. |
| `allowInvalidConfigRecovery` | `boolean` | Ermöglicht es Neuinstallationsabläufen gebündelter Plugins, sich von bestimmten Fehlern mit veralteter Konfiguration zu erholen. |
Wenn `minHostVersion` gesetzt ist, erzwingen sowohl Installation als auch das Laden der Manifest-
Registry diese. Ältere Hosts überspringen das Plugin; ungültige Versionszeichenfolgen werden abgelehnt.
Wenn `minHostVersion` gesetzt ist, erzwingen sowohl die Installation als auch das Laden der Manifest-Registry
diese Angabe. Ältere Hosts überspringen das Plugin; ungültige Versionszeichenfolgen werden abgelehnt.
`allowInvalidConfigRecovery` ist keine allgemeine Umgehung für fehlerhafte Konfigurationen. Es ist
nur für eng gefasste Wiederherstellung gebündelter Plugins gedacht, damit Reinstallation/Setup bekannte Upgrade-
Überbleibsel wie einen fehlenden Pfad zu einem gebündelten Plugin oder einen veralteten Eintrag `channels.<id>`
für dasselbe Plugin reparieren können. Wenn die Konfiguration aus anderen Gründen fehlerhaft ist,
schlägt die Installation weiterhin fehlgeschlossen fehl und weist den Operator an, `openclaw doctor --fix` auszuführen.
nur für die gezielte Wiederherstellung gebündelter Plugins gedacht, damit Neuinstallation/Setup bekannte
Upgrade-Überbleibsel reparieren können, wie einen fehlenden gebündelten Plugin-Pfad oder einen veralteten
`channels.<id>`-Eintrag für genau dieses Plugin. Wenn die Konfiguration aus anderen Gründen fehlerhaft ist,
schlägt die Installation weiterhin sicher fehl und weist den Operator an, `openclaw doctor --fix` auszuführen.
### Verzögertes vollständiges Laden
### Aufgeschobenes vollständiges Laden
Kanal-Plugins können sich mit Folgendem für verzögertes Laden anmelden:
Kanal-Plugins können sich mit Folgendem für aufgeschobenes Laden entscheiden:
```json
{
@ -189,26 +189,26 @@ Kanal-Plugins können sich mit Folgendem für verzögertes Laden anmelden:
}
```
Wenn dies aktiviert ist, lädt OpenClaw in der Startphase vor `listen`
nur `setupEntry`, selbst für bereits konfigurierte Kanäle. Der vollständige Einstiegspunkt wird geladen, nachdem das
Gateway mit dem Lauschen begonnen hat.
Wenn dies aktiviert ist, lädt OpenClaw in der Startphase vor `listen` nur `setupEntry`,
selbst für bereits konfigurierte Kanäle. Der vollständige Einstiegspunkt wird geladen, nachdem das
Gateway begonnen hat zu lauschen.
<Warning>
Aktivieren Sie verzögertes Laden nur dann, wenn Ihr `setupEntry` alles registriert, was das
Gateway benötigt, bevor es mit dem Lauschen beginnt (Kanalregistrierung, HTTP-Routen,
Gateway-Methoden). Wenn der vollständige Einstiegspunkt erforderliche Startfähigkeiten besitzt, behalten Sie
das Standardverhalten bei.
Aktiviere aufgeschobenes Laden nur, wenn dein `setupEntry` alles registriert, was das
Gateway benötigt, bevor es beginnt zu lauschen (Kanalregistrierung, HTTP-Routen,
Gateway-Methoden). Wenn der vollständige Einstiegspunkt erforderliche Startfähigkeiten besitzt,
behalte das Standardverhalten bei.
</Warning>
Wenn Ihr Setup-/Voll-Einstiegspunkt Gateway-RPC-Methoden registriert, behalten Sie sie auf einem
plugin-spezifischen Präfix. Reservierte Admin-Namespaces des Kerns (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) bleiben im Besitz des Kerns und werden immer zu
`operator.admin` aufgelöst.
Wenn dein Setup-/vollständiger Einstiegspunkt Gateway-RPC-Methoden registriert, halte sie auf einem
Plugin-spezifischen Präfix. Reservierte Core-Admin-Namespaces (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) bleiben im Besitz des Core und werden immer
zu `operator.admin` aufgelöst.
## Plugin-Manifest
Jedes native Plugin muss ein `openclaw.plugin.json` im Paketstamm mitliefern.
OpenClaw verwendet dies, um Konfiguration zu validieren, ohne Plugin-Code auszuführen.
Jedes native Plugin muss im Paketstamm ein `openclaw.plugin.json` enthalten.
OpenClaw verwendet dies, um die Konfiguration zu validieren, ohne Plugin-Code auszuführen.
```json
{
@ -228,7 +228,7 @@ OpenClaw verwendet dies, um Konfiguration zu validieren, ohne Plugin-Code auszuf
}
```
Für Kanal-Plugins fügen Sie `kind` und `channels` hinzu:
Für Kanal-Plugins füge `kind` und `channels` hinzu:
```json
{
@ -243,7 +243,7 @@ Für Kanal-Plugins fügen Sie `kind` und `channels` hinzu:
}
```
Selbst Plugins ohne Konfiguration müssen ein Schema mitliefern. Ein leeres Schema ist gültig:
Selbst Plugins ohne Konfiguration müssen ein Schema enthalten. Ein leeres Schema ist gültig:
```json
{
@ -255,24 +255,24 @@ Selbst Plugins ohne Konfiguration müssen ein Schema mitliefern. Ein leeres Sche
}
```
Die vollständige Schemareferenz finden Sie unter [Plugin Manifest](/de/plugins/manifest).
Siehe [Plugin Manifest](/de/plugins/manifest) für die vollständige Schemareferenz.
## ClawHub-Veröffentlichung
Für Plugin-Pakete verwenden Sie den paketspezifischen ClawHub-Befehl:
Verwende für Plugin-Pakete den paket-spezifischen ClawHub-Befehl:
```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
Der veraltete Alias für die Veröffentlichung nur von Skills ist für Skills gedacht. Plugin-Pakete sollten
Der ältere, nur auf Skills bezogene Veröffentlichungsalias ist für Skills. Plugin-Pakete sollten
immer `clawhub package publish` verwenden.
## Setup-Eintrag
## Setup-Einstiegspunkt
Die Datei `setup-entry.ts` ist eine leichtgewichtige Alternative zu `index.ts`, die
OpenClaw lädt, wenn es nur Setup-Oberflächen benötigt (Onboarding, Konfigurationsreparatur,
OpenClaw lädt, wenn nur Setup-Oberflächen benötigt werden (Onboarding, Konfigurationsreparatur,
Inspektion deaktivierter Kanäle).
```typescript
@ -283,75 +283,82 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
Dadurch wird vermieden, während Setup-Abläufen schweren Laufzeitcode zu laden (Kryptobibliotheken, CLI-Registrierungen,
Hintergrunddienste).
Dadurch wird vermieden, schwere Laufzeitkomponenten (Kryptobibliotheken, CLI-Registrierungen,
Hintergrunddienste) während Setup-Abläufen zu laden.
**Wann OpenClaw `setupEntry` statt des vollständigen Einstiegspunkts verwendet:**
Gebündelte Workspace-Kanäle, die setup-sichere Exporte in Sidecar-Modulen behalten, können
`defineBundledChannelSetupEntry(...)` aus
`openclaw/plugin-sdk/channel-entry-contract` anstelle von
`defineSetupPluginEntry(...)` verwenden. Dieser gebündelte Vertrag unterstützt auch einen optionalen
`runtime`-Export, damit die Laufzeitverdrahtung zur Setup-Zeit leichtgewichtig und explizit bleiben kann.
**Wann OpenClaw `setupEntry` anstelle des vollständigen Einstiegspunkts verwendet:**
- Der Kanal ist deaktiviert, benötigt aber Setup-/Onboarding-Oberflächen
- Der Kanal ist aktiviert, aber nicht konfiguriert
- Verzögertes Laden ist aktiviert (`deferConfiguredChannelFullLoadUntilAfterListen`)
- Aufgeschobenes Laden ist aktiviert (`deferConfiguredChannelFullLoadUntilAfterListen`)
**Was `setupEntry` registrieren muss:**
- Das Kanal-Plugin-Objekt (über `defineSetupPluginEntry`)
- Alle HTTP-Routen, die vor dem Gateway-`listen` erforderlich sind
- Alle HTTP-Routen, die vor dem Lauschen des Gateways erforderlich sind
- Alle Gateway-Methoden, die beim Start benötigt werden
Diese Gateway-Methoden beim Start sollten weiterhin reservierte Admin-
Namespaces des Kerns wie `config.*` oder `update.*` vermeiden.
Diese Gateway-Methoden für den Start sollten weiterhin reservierte Core-Admin-
Namespaces wie `config.*` oder `update.*` vermeiden.
**Was `setupEntry` NICHT enthalten sollte:**
- CLI-Registrierungen
- Hintergrunddienste
- Schwere Laufzeitimporte (Krypto, SDKs)
- Schwere Laufzeitimporte (Kryptografie, SDKs)
- Gateway-Methoden, die erst nach dem Start benötigt werden
### Enge Importe von Setup-Hilfen
### Schmale Importe für Setup-Hilfsfunktionen
Für heiße Pfade nur für Setup bevorzugen Sie die engen Helper-Seams für Setup gegenüber der breiteren
übergeordneten `plugin-sdk/setup`-Oberfläche, wenn Sie nur einen Teil der Setup-Oberfläche benötigen:
Für reine Setup-Hotpaths solltest du die schmalen Hilfsseams für das Setup dem breiteren
`plugin-sdk/setup`-Umbrella vorziehen, wenn du nur einen Teil der Setup-Oberfläche benötigst:
| Importpfad | Verwenden Sie ihn für | Wichtige Exporte |
| --------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | laufzeitsichere Setup-Hilfen, die in `setupEntry` / beim verzögerten Kanalstart verfügbar bleiben | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | umgebungsbewusste Account-Setup-Adapter | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | CLI-/Archiv-/Docs-Hilfen für Setup/Installation | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| Importpfad | Verwende ihn für | Wichtige Exporte |
| --------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | Laufzeit-Hilfsfunktionen zur Setup-Zeit, die in `setupEntry` / beim aufgeschobenen Kanalstart verfügbar bleiben | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | umgebungsbewusste Account-Setup-Adapter | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | CLI-/Archiv-/Dokumentations-Hilfsfunktionen für Setup/Installation | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
Verwenden Sie die breitere Naht `plugin-sdk/setup`, wenn Sie die vollständige gemeinsame Setup-
Werkzeugkiste möchten, einschließlich Hilfen für Konfigurations-Patches wie
Verwende den breiteren `plugin-sdk/setup`-Seam, wenn du die vollständige gemeinsame Setup-
Werkzeugkiste haben möchtest, einschließlich Hilfsfunktionen zum Patchen der Konfiguration wie
`moveSingleAccountChannelSectionToDefaultAccount(...)`.
Die Setup-Patch-Adapter bleiben beim Import für den Hot Path sicher. Ihr gebündeltes
Lookup der Vertragsoberfläche für Single-Account-Promotion ist lazy, sodass das Importieren von
`plugin-sdk/setup-runtime` die Discovery der gebündelten Vertragsoberfläche nicht eager lädt, bevor der Adapter tatsächlich verwendet wird.
Die Setup-Patch-Adapter bleiben beim Import hotpath-sicher. Ihr gebündeltes Nachschlagen der
Vertragsoberfläche für die Promotion eines Einzelkontos erfolgt lazy, sodass der Import von
`plugin-sdk/setup-runtime` die Erkennung gebündelter Vertragsoberflächen nicht vorzeitig lädt,
bevor der Adapter tatsächlich verwendet wird.
### Kanal-eigene Single-Account-Promotion
### Kanal-eigene Einzelkonto-Promotion
Wenn ein Kanal von einer Top-Level-Konfiguration für ein einzelnes Konto auf
`channels.<id>.accounts.*` aktualisiert wird, verschiebt das standardmäßige gemeinsame Verhalten die
hochgestuften kontobezogenen Werte nach `accounts.default`.
Wenn ein Kanal von einer Konfiguration auf oberster Ebene für ein Einzelkonto auf
`channels.<id>.accounts.*` umstellt, verschiebt das standardmäßige gemeinsame Verhalten die
promoteten konto-spezifischen Werte in `accounts.default`.
Gebündelte Kanäle können diese Promotion über ihre Setup-
Vertragsoberfläche eingrenzen oder überschreiben:
Gebündelte Kanäle können diese Promotion über ihre Setup-Vertragsoberfläche eingrenzen oder
überschreiben:
- `singleAccountKeysToMove`: zusätzliche Top-Level-Schlüssel, die in das
hochgestufte Konto verschoben werden sollen
- `singleAccountKeysToMove`: zusätzliche Schlüssel auf oberster Ebene, die in das
promotete Konto verschoben werden sollen
- `namedAccountPromotionKeys`: wenn bereits benannte Konten existieren, werden nur diese
Schlüssel in das hochgestufte Konto verschoben; gemeinsame Richtlinien-/Zustellungsschlüssel bleiben im
Kanalstamm
- `resolveSingleAccountPromotionTarget(...)`: wählt aus, welches vorhandene Konto
hochgestufte Werte erhält
Schlüssel in das promotete Konto verschoben; gemeinsame Richtlinien-/Zustellungsschlüssel
bleiben auf der Kanalwurzelebene
- `resolveSingleAccountPromotionTarget(...)`: wählt aus, welches vorhandene Konto die
promoteten Werte erhält
Matrix ist das aktuelle gebündelte Beispiel. Wenn genau ein benanntes Matrix-Konto
bereits existiert oder wenn `defaultAccount` auf einen vorhandenen nichtkanonischen Schlüssel
wie `Ops` zeigt, bewahrt die Promotion dieses Konto, statt einen neuen Eintrag
`accounts.default` zu erzeugen.
Matrix ist das aktuelle gebündelte Beispiel. Wenn bereits genau ein benanntes Matrix-Konto
existiert oder wenn `defaultAccount` auf einen vorhandenen nicht-kanonischen Schlüssel wie
`Ops` zeigt, bewahrt die Promotion dieses Konto, anstatt einen neuen Eintrag
`accounts.default` zu erstellen.
## Konfigurationsschema
Die Plugin-Konfiguration wird gegen das JSON-Schema in Ihrem Manifest validiert. Benutzer
Die Plugin-Konfiguration wird gegen das JSON-Schema in deinem Manifest validiert. Benutzer
konfigurieren Plugins über:
```json5
@ -368,9 +375,9 @@ konfigurieren Plugins über:
}
```
Ihr Plugin erhält diese Konfiguration während der Registrierung als `api.pluginConfig`.
Dein Plugin erhält diese Konfiguration während der Registrierung als `api.pluginConfig`.
Für kanalspezifische Konfiguration verwenden Sie stattdessen den Kanal-Konfigurationsabschnitt:
Verwende für kanal-spezifische Konfiguration stattdessen den Kanal-Konfigurationsabschnitt:
```json5
{
@ -383,10 +390,10 @@ Für kanalspezifische Konfiguration verwenden Sie stattdessen den Kanal-Konfigur
}
```
### Kanal-Konfigurationsschemas erstellen
### Kanal-Konfigurationsschemata erstellen
Verwenden Sie `buildChannelConfigSchema` aus `openclaw/plugin-sdk/core`, um ein
Zod-Schema in den Wrapper `ChannelConfigSchema` zu konvertieren, den OpenClaw validiert:
Verwende `buildChannelConfigSchema` aus `openclaw/plugin-sdk/core`, um ein
Zod-Schema in den `ChannelConfigSchema`-Wrapper umzuwandeln, den OpenClaw validiert:
```typescript
import { z } from "zod";
@ -402,10 +409,10 @@ const accountSchema = z.object({
const configSchema = buildChannelConfigSchema(accountSchema);
```
## Setup-Assistenten
## Einrichtungsassistenten
Kanal-Plugins können interaktive Setup-Assistenten für `openclaw onboard` bereitstellen.
Der Assistent ist ein Objekt `ChannelSetupWizard` auf dem `ChannelPlugin`:
Kanal-Plugins können interaktive Einrichtungsassistenten für `openclaw onboard` bereitstellen.
Der Assistent ist ein `ChannelSetupWizard`-Objekt auf dem `ChannelPlugin`:
```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
@ -440,20 +447,21 @@ const setupWizard: ChannelSetupWizard = {
Der Typ `ChannelSetupWizard` unterstützt `credentials`, `textInputs`,
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` und mehr.
Vollständige Beispiele finden Sie in gebündelten Plugin-Paketen (zum Beispiel im Discord-Plugin `src/channel.setup.ts`).
Siehe die gebündelten Plugin-Pakete (zum Beispiel das Discord-Plugin `src/channel.setup.ts`) für
vollständige Beispiele.
Für Abfragen der DM-Allowlist, die nur den Standardablauf
`note -> prompt -> parse -> merge -> patch` benötigen, bevorzugen Sie die gemeinsamen Setup-
Hilfen aus `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`,
Für DM-Allowlist-Abfragen, die nur den Standardablauf
`note -> prompt -> parse -> merge -> patch` benötigen, solltest du die gemeinsamen Setup-
Hilfsfunktionen aus `openclaw/plugin-sdk/setup` bevorzugen: `createPromptParsedAllowFromForAccount(...)`,
`createTopLevelChannelParsedAllowFromPrompt(...)` und
`createNestedChannelParsedAllowFromPrompt(...)`.
Für Statusblöcke des Kanal-Setups, die sich nur durch Bezeichnungen, Werte und optionale
zusätzliche Zeilen unterscheiden, bevorzugen Sie `createStandardChannelSetupStatus(...)` aus
`openclaw/plugin-sdk/setup`, statt in jedem Plugin dasselbe `status`-Objekt
von Hand zu erstellen.
Für Kanal-Setup-Statusblöcke, die sich nur in Bezeichnungen, Bewertungen und optionalen
zusätzlichen Zeilen unterscheiden, solltest du `createStandardChannelSetupStatus(...)` aus
`openclaw/plugin-sdk/setup` bevorzugen, anstatt in jedem Plugin dasselbe `status`-Objekt
von Hand zu bauen.
Für optionale Setup-Oberflächen, die nur in bestimmten Kontexten erscheinen sollen, verwenden Sie
Für optionale Setup-Oberflächen, die nur in bestimmten Kontexten erscheinen sollen, verwende
`createOptionalChannelSetupSurface` aus `openclaw/plugin-sdk/channel-setup`:
```typescript
@ -468,52 +476,52 @@ const setupSurface = createOptionalChannelSetupSurface({
// Returns { setupAdapter, setupWizard }
```
`plugin-sdk/channel-setup` exportiert auch die Low-Level-Builder
`plugin-sdk/channel-setup` stellt außerdem die Low-Level-Builder
`createOptionalChannelSetupAdapter(...)` und
`createOptionalChannelSetupWizard(...)`, wenn Sie nur eine Hälfte
dieser Oberfläche für optionale Installation benötigen.
`createOptionalChannelSetupWizard(...)` bereit, wenn du nur eine Hälfte
dieser optionalen Installationsoberfläche benötigst.
Der erzeugte optionale Adapter/Assistent schlägt bei echten Konfigurationsschreibvorgängen fehlgeschlossen fehl. Er
verwendet eine einzige Meldung „Installation erforderlich“ über `validateInput`,
`applyAccountConfig` und `finalize` hinweg wieder und hängt einen Docs-Link an, wenn `docsPath`
Der generierte optionale Adapter/Assistent schlägt bei echten Konfigurationsschreibvorgängen sicher fehl. Sie
verwenden dieselbe Meldung „Installation erforderlich“ in `validateInput`,
`applyAccountConfig` und `finalize` wieder und hängen einen Dokumentationslink an, wenn `docsPath`
gesetzt ist.
Für binär gestützte Setup-UIs bevorzugen Sie die gemeinsamen delegierten Hilfen, statt
denselben Binär-/Status-Klebstoff in jeden Kanal zu kopieren:
Für binärgestützte Setup-UIs solltest du die gemeinsamen delegierten Hilfsfunktionen bevorzugen,
anstatt dieselbe Binär-/Status-Logik in jeden Kanal zu kopieren:
- `createDetectedBinaryStatus(...)` für Statusblöcke, die sich nur nach Bezeichnungen,
Hinweisen, Werten und Binärerkennung unterscheiden
Hinweisen, Bewertungen und Binärerkennung unterscheiden
- `createCliPathTextInput(...)` für pfadgestützte Texteingaben
- `createDelegatedSetupWizardStatusResolvers(...)`,
`createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` und
`createDelegatedResolveConfigured(...)`, wenn `setupEntry` lazy an einen
schwereren vollständigen Assistenten weiterleiten muss
- `createDelegatedTextInputShouldPrompt(...)`, wenn `setupEntry` nur die Entscheidung
`textInputs[*].shouldPrompt` delegieren muss
`createDelegatedResolveConfigured(...)`, wenn `setupEntry` lazy an
einen schwergewichtigeren vollständigen Assistenten weiterleiten muss
- `createDelegatedTextInputShouldPrompt(...)`, wenn `setupEntry` nur eine
`textInputs[*].shouldPrompt`-Entscheidung delegieren muss
## Veröffentlichen und installieren
**Externe Plugins:** auf [ClawHub](/de/tools/clawhub) oder npm veröffentlichen, dann installieren:
**Externe Plugins:** Veröffentliche sie auf [ClawHub](/de/tools/clawhub) oder npm und installiere sie dann:
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
OpenClaw versucht zuerst ClawHub und fällt automatisch auf npm zurück. Sie können ClawHub auch
OpenClaw versucht zuerst ClawHub und greift automatisch auf npm zurück. Du kannst ClawHub auch
explizit erzwingen:
```bash
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # nur ClawHub
```
Es gibt keine passende Überschreibung `npm:`. Verwenden Sie die normale npm-Paketspezifikation, wenn Sie
nach dem ClawHub-Fallback den npm-Pfad wünschen:
Es gibt kein entsprechendes `npm:`-Override. Verwende die normale npm-Paketspezifikation, wenn du
nach dem ClawHub-Fallback den npm-Pfad verwenden möchtest:
```bash
openclaw plugins install @myorg/openclaw-my-plugin
```
**Plugins im Repository:** Platzieren Sie sie unter dem Workspace-Baum für gebündelte Plugins, dann werden sie beim Build automatisch
**Plugins im Repository:** Lege sie unter dem gebündelten Plugin-Workspace-Baum ab; dann werden sie beim Build automatisch
erkannt.
**Benutzer können installieren:**
@ -523,13 +531,13 @@ openclaw plugins install <package-name>
```
<Info>
Für Installationen aus npm führt `openclaw plugins install`
`npm install --ignore-scripts` aus (keine Lifecycle-Skripte). Halten Sie die Abhängigkeits-
Bäume von Plugins bei reinem JS/TS und vermeiden Sie Pakete, die `postinstall`-Builds erfordern.
Für Installationen aus npm-Quellen führt `openclaw plugins install`
`npm install --ignore-scripts` aus (keine Lifecycle-Skripte). Halte die Abhängigkeitsbäume von Plugins
rein in JS/TS und vermeide Pakete, die `postinstall`-Builds erfordern.
</Info>
## Verwandt
- [SDK Entry Points](/de/plugins/sdk-entrypoints) -- `definePluginEntry` und `defineChannelPluginEntry`
- [Plugin Manifest](/de/plugins/manifest) -- vollständige Manifest-Schemareferenz
- [Building Plugins](/de/plugins/building-plugins) -- Schritt-für-Schritt-Anleitung für den Einstieg
- [Plugin Manifest](/de/plugins/manifest) -- vollständige Referenz des Manifestschemas
- [Building Plugins](/de/plugins/building-plugins) -- Schritt-für-Schritt-Einstiegsanleitung

106
docs/de/plugins/sdk-testing.md
View File

@ -1,36 +1,36 @@
---
read_when:
- Sie schreiben Tests für ein Plugin
- Sie benötigen Testhilfen aus dem Plugin SDK
- Sie möchten Vertragstests für gebündelte Plugins verstehen
- Sie schreiben Tests für ein Plugin.
- Sie benötigen Testhilfsprogramme aus dem Plugin SDK.
- Sie möchten Vertragstests für gebündelte Plugins verstehen.
sidebarTitle: Testing
summary: Testhilfen und Muster für OpenClaw-Plugins
summary: Testhilfsprogramme und Muster für OpenClaw-Plugins
title: Plugin-Tests
x-i18n:
generated_at: "2026-04-05T12:51:55Z"
generated_at: "2026-04-15T19:41:34Z"
model: gpt-5.4
provider: openai
source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe
source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09
source_path: plugins/sdk-testing.md
workflow: 15
---
# Plugin-Tests
Referenz für Testhilfen, Muster und Lint-Durchsetzung für OpenClaw-
Referenz für Testhilfsprogramme, Muster und Lint-Durchsetzung für OpenClaw-
Plugins.
<Tip>
**Sie suchen nach Testbeispielen?** Die Schritt-für-Schritt-Leitfäden enthalten ausgearbeitete Testbeispiele:
[Kanal-Plugin-Tests](/plugins/sdk-channel-plugins#step-6-test) und
[Provider-Plugin-Tests](/plugins/sdk-provider-plugins#step-6-test).
**Suchen Sie nach Testbeispielen?** Die Schritt-für-Schritt-Anleitungen enthalten ausgearbeitete Testbeispiele:
[Tests für Channel-Plugins](/de/plugins/sdk-channel-plugins#step-6-test) und
[Tests für Provider-Plugins](/de/plugins/sdk-provider-plugins#step-6-test).
</Tip>
## Testhilfen
## Testhilfsprogramme
**Import:** `openclaw/plugin-sdk/testing`
Der Testing-Subpfad exportiert eine gezielte Menge von Hilfsfunktionen für Plugin-Autorinnen und -Autoren:
Der Testing-Subpath exportiert einen eingeschränkten Satz von Hilfsfunktionen für Plugin-Autorinnen und -Autoren:
```typescript
import {
@ -42,15 +42,15 @@ import {
### Verfügbare Exporte
| Export | Zweck |
| -------------------------------------- | ------------------------------------------------------- |
| Export | Zweck |
| -------------------------------------- | ------------------------------------------------------ |
| `installCommonResolveTargetErrorCases` | Gemeinsame Testfälle für die Fehlerbehandlung bei der Zielauflösung |
| `shouldAckReaction` | Prüfen, ob ein Kanal eine Ack-Reaktion hinzufügen sollte |
| `removeAckReactionAfterReply` | Ack-Reaktion nach der Zustellung einer Antwort entfernen |
| `shouldAckReaction` | Prüfen, ob ein Channel eine Ack-Reaktion hinzufügen sollte |
| `removeAckReactionAfterReply` | Ack-Reaktion nach der Zustellung der Antwort entfernen |
### Typen
Der Testing-Subpfad exportiert auch Typen erneut, die in Testdateien nützlich sind:
Der Testing-Subpath exportiert außerdem Typen erneut, die in Testdateien nützlich sind:
```typescript
import type {
@ -65,8 +65,7 @@ import type {
## Zielauflösung testen
Verwenden Sie `installCommonResolveTargetErrorCases`, um Standardfehlerfälle für
die Zielauflösung von Kanälen hinzuzufügen:
Verwenden Sie `installCommonResolveTargetErrorCases`, um Standardfehlerfälle für die Channel-Zielauflösung hinzuzufügen:
```typescript
import { describe } from "vitest";
@ -75,13 +74,13 @@ import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testin
describe("my-channel target resolution", () => {
installCommonResolveTargetErrorCases({
resolveTarget: ({ to, mode, allowFrom }) => {
// Zielauflösungslogik Ihres Kanals
// Your channel's target resolution logic
return myChannelResolveTarget({ to, mode, allowFrom });
},
implicitAllowFrom: ["user1", "user2"],
});
// Kanalspezifische Testfälle hinzufügen
// Add channel-specific test cases
it("should resolve @username targets", () => {
// ...
});
@ -90,7 +89,7 @@ describe("my-channel target resolution", () => {
## Testmuster
### Unit-Tests für ein Kanal-Plugin
### Unit-Tests für ein Channel-Plugin
```typescript
import { describe, it, expect, vi } from "vitest";
@ -120,7 +119,7 @@ describe("my-channel plugin", () => {
const inspection = myPlugin.setup.inspectAccount(cfg, undefined);
expect(inspection.configured).toBe(true);
expect(inspection.tokenStatus).toBe("available");
// Kein Token-Wert wird offengelegt
// No token value exposed
expect(inspection).not.toHaveProperty("token");
});
});
@ -135,7 +134,7 @@ describe("my-provider plugin", () => {
it("should resolve dynamic models", () => {
const model = myProvider.resolveDynamicModel({
modelId: "custom-model-v2",
// ... Kontext
// ... context
});
expect(model.id).toBe("custom-model-v2");
@ -146,7 +145,7 @@ describe("my-provider plugin", () => {
it("should return catalog when API key is available", async () => {
const result = await myProvider.catalog.run({
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
// ... Kontext
// ... context
});
expect(result?.provider?.models).toHaveLength(2);
@ -156,49 +155,52 @@ describe("my-provider plugin", () => {
### Die Plugin-Laufzeit mocken
Für Code, der `createPluginRuntimeStore` verwendet, sollten Sie die Laufzeit in Tests mocken:
Für Code, der `createPluginRuntimeStore` verwendet, mocken Sie die Laufzeit in Tests:
```typescript
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
const store = createPluginRuntimeStore<PluginRuntime>("test runtime not set");
const store = createPluginRuntimeStore<PluginRuntime>({
pluginId: "test-plugin",
errorMessage: "test runtime not set",
});
// Im Test-Setup
// In test setup
const mockRuntime = {
agent: {
resolveAgentDir: vi.fn().mockReturnValue("/tmp/agent"),
// ... weitere Mocks
// ... other mocks
},
config: {
loadConfig: vi.fn(),
writeConfigFile: vi.fn(),
},
// ... weitere Namespaces
// ... other namespaces
} as unknown as PluginRuntime;
store.setRuntime(mockRuntime);
// Nach den Tests
// After tests
store.clearRuntime();
```
### Mit instanzspezifischen Stubs testen
Bevorzugen Sie instanzspezifische Stubs gegenüber Prototyp-Mutation:
Bevorzugen Sie instanzspezifische Stubs statt Prototyp-Mutation:
```typescript
// Bevorzugt: instanzspezifischer Stub
// Preferred: per-instance stub
const client = new MyChannelClient();
client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
// Vermeiden: Prototyp-Mutation
// Avoid: prototype mutation
// MyChannelClient.prototype.sendMessage = vi.fn();
```
## Vertragstests (Plugins im Repository)
Gebündelte Plugins haben Vertragstests, die die Besitzerschaft der Registrierung verifizieren:
Gebündelte Plugins haben Vertragstests, die die Besitzverhältnisse bei der Registrierung überprüfen:
```bash
pnpm test -- src/plugins/contracts/
@ -207,7 +209,7 @@ pnpm test -- src/plugins/contracts/
Diese Tests prüfen:
- Welche Plugins welche Provider registrieren
- Welche Plugins welche Speech-Provider registrieren
- Welche Plugins welche Sprach-Provider registrieren
- Korrektheit der Registrierungsform
- Einhaltung des Laufzeitvertrags
@ -229,42 +231,42 @@ pnpm test -- src/plugins/contracts/runtime.contract.test.ts
## Lint-Durchsetzung (Plugins im Repository)
Drei Regeln werden durch `pnpm check` für Plugins im Repository erzwungen:
Drei Regeln werden durch `pnpm check` für Plugins im Repository durchgesetzt:
1. **Keine monolithischen Root-Imports** -- Das Root-Barrel `openclaw/plugin-sdk` wird abgelehnt
2. **Keine direkten `src/`-Imports** -- Plugins dürfen `../../src/` nicht direkt importieren
3. **Keine Selbstimporte** -- Plugins dürfen ihren eigenen Subpfad `plugin-sdk/<name>` nicht importieren
1. **Keine monolithischen Root-Importe** -- die Root-Barrel-Datei `openclaw/plugin-sdk` wird abgelehnt
2. **Keine direkten `src/`-Importe** -- Plugins dürfen `../../src/` nicht direkt importieren
3. **Keine Selbstimporte** -- Plugins dürfen nicht ihren eigenen Subpath `plugin-sdk/<name>` importieren
Externe Plugins unterliegen diesen Lint-Regeln nicht, aber es wird empfohlen,
denselben Mustern zu folgen.
Externe Plugins unterliegen diesen Lint-Regeln nicht, aber es wird empfohlen, dieselben
Muster zu befolgen.
## Testkonfiguration
OpenClaw verwendet Vitest mit V8-Coverage-Schwellenwerten. Für Plugin-Tests:
```bash
# Alle Tests ausführen
# Run all tests
pnpm test
# Tests für ein bestimmtes Plugin ausführen
# Run specific plugin tests
pnpm test -- <bundled-plugin-root>/my-channel/src/channel.test.ts
# Mit einem Filter für einen bestimmten Testnamen ausführen
# Run with a specific test name filter
pnpm test -- <bundled-plugin-root>/my-channel/ -t "resolves account"
# Mit Coverage ausführen
# Run with coverage
pnpm test:coverage
```
Wenn lokale Läufe zu Speicherdruck führen:
Wenn lokale Ausführungen zu Speicherdruck führen:
```bash
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
```
## Verwandt
## Verwandte Themen
- [SDK-Überblick](/plugins/sdk-overview) -- Importkonventionen
- [SDK-Kanal-Plugins](/plugins/sdk-channel-plugins) -- Schnittstelle für Kanal-Plugins
- [SDK-Provider-Plugins](/plugins/sdk-provider-plugins) -- Hooks für Provider-Plugins
- [Plugins erstellen](/plugins/building-plugins) -- Einstiegsleitfaden
- [SDK Overview](/de/plugins/sdk-overview) -- Importkonventionen
- [SDK Channel Plugins](/de/plugins/sdk-channel-plugins) -- Channel-Plugin-Schnittstelle
- [SDK Provider Plugins](/de/plugins/sdk-provider-plugins) -- Provider-Plugin-Hooks
- [Building Plugins](/de/plugins/building-plugins) -- Leitfaden für den Einstieg

137
docs/de/reference/token-use.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Erklärung von Token-Nutzung, Kosten oder Kontextfenstern
- Debuggen von Kontextwachstum oder Kompaktierungsverhalten
summary: Wie OpenClaw Prompt-Kontext erstellt und Token-Nutzung + Kosten meldet
- Kontextwachstum oder Compaction-Verhalten debuggen
summary: Wie OpenClaw Prompt-Kontext erstellt und Token-Nutzung sowie Kosten meldet
title: Token-Nutzung und Kosten
x-i18n:
generated_at: "2026-04-12T06:16:41Z"
generated_at: "2026-04-15T19:41:57Z"
model: gpt-5.4
provider: openai
source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb
source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5
source_path: reference/token-use.md
workflow: 15
---
@ -16,16 +16,19 @@ x-i18n:
# Token-Nutzung und Kosten
OpenClaw erfasst **Token**, nicht Zeichen. Token sind modellspezifisch, aber die meisten
Modelle im OpenAI-Stil haben im Durchschnitt etwa 4 Zeichen pro Token bei englischem Text.
OpenAI-ähnlichen Modelle haben im Durchschnitt etwa 4 Zeichen pro Token für englischen Text.
## Wie der System-Prompt erstellt wird
OpenClaw setzt bei jedem Lauf seinen eigenen System-Prompt zusammen. Er enthält:
OpenClaw setzt seinen eigenen System-Prompt bei jeder Ausführung zusammen. Er enthält:
- Tool-Liste + kurze Beschreibungen
- Skills-Liste (nur Metadaten; Anweisungen werden bei Bedarf mit `read` geladen)
- Skills-Liste (nur Metadaten; Anweisungen werden bei Bedarf mit `read` geladen).
Der kompakte Skills-Block ist durch `skills.limits.maxSkillsPromptChars`
begrenzt, mit optionaler agentenspezifischer Überschreibung unter
`agents.list[].skillsLimits.maxSkillsPromptChars`.
- Anweisungen zur Selbstaktualisierung
- Workspace- + Bootstrap-Dateien (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, wenn neu, sowie `MEMORY.md`, wenn vorhanden, oder `memory.md` als Fallback in Kleinbuchstaben). Große Dateien werden durch `agents.defaults.bootstrapMaxChars` abgeschnitten (Standard: 20000), und die gesamte Bootstrap-Injektion ist durch `agents.defaults.bootstrapTotalMaxChars` begrenzt (Standard: 150000). Tägliche Dateien in `memory/*.md` sind nicht Teil des normalen Bootstrap-Prompts; sie bleiben bei normalen Turns bedarfsbasiert über Speicher-Tools verfügbar, aber bei reinem `/new` und `/reset` kann ein einmaliger Startkontext-Block mit aktuellem täglichem Speicher für diesen ersten Turn vorangestellt werden. Dieses Startpräliminarium wird durch `agents.defaults.startupContext` gesteuert.
- Workspace- und Bootstrap-Dateien (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, wenn neu, sowie `MEMORY.md`, wenn vorhanden, oder `memory.md` als Fallback in Kleinbuchstaben). Große Dateien werden durch `agents.defaults.bootstrapMaxChars` abgeschnitten (Standard: 12000), und die gesamte Bootstrap-Injektion ist durch `agents.defaults.bootstrapTotalMaxChars` begrenzt (Standard: 60000). Tägliche Dateien in `memory/*.md` sind nicht Teil des normalen Bootstrap-Prompts; sie bleiben in normalen Turns bei Bedarf über Memory-Tools verfügbar, aber ein einfaches `/new` und `/reset` kann für den ersten Turn einen einmaligen Startup-Kontextblock mit aktuellem täglichem Memory voranstellen. Dieses Startup-Präludium wird durch `agents.defaults.startupContext` gesteuert.
- Zeit (UTC + Benutzerzeitzone)
- Antwort-Tags + Heartbeat-Verhalten
- Laufzeitmetadaten (Host/OS/Modell/Thinking)
@ -37,88 +40,104 @@ Die vollständige Aufschlüsselung finden Sie unter [System Prompt](/de/concepts
Alles, was das Modell erhält, zählt zum Kontextlimit:
- System-Prompt (alle oben aufgeführten Abschnitte)
- Gesprächsverlauf (Benutzer- + Assistenten-Nachrichten)
- Gesprächsverlauf (Benutzer- und Assistentennachrichten)
- Tool-Aufrufe und Tool-Ergebnisse
- Anhänge/Transkripte (Bilder, Audio, Dateien)
- Kompaktierungszusammenfassungen und Artefakte des Beschneidens
- Provider-Wrapper oder Safety-Header (nicht sichtbar, aber dennoch mitgezählt)
- Compaction-Zusammenfassungen und Pruning-Artefakte
- Provider-Wrapper oder Sicherheits-Header (nicht sichtbar, werden aber trotzdem mitgezählt)
Bei Bildern skaliert OpenClaw Bild-Payloads aus Transkripten/Tools vor Provider-Aufrufen herunter.
Verwenden Sie `agents.defaults.imageMaxDimensionPx` (Standard: `1200`), um dies anzupassen:
Einige laufzeitintensive Bereiche haben eigene explizite Begrenzungen:
- Niedrigere Werte reduzieren in der Regel die Vision-Token-Nutzung und die Payload-Größe.
- `agents.defaults.contextLimits.memoryGetMaxChars`
- `agents.defaults.contextLimits.memoryGetDefaultLines`
- `agents.defaults.contextLimits.toolResultMaxChars`
- `agents.defaults.contextLimits.postCompactionMaxChars`
Agentenspezifische Überschreibungen befinden sich unter `agents.list[].contextLimits`. Diese Regler sind
für begrenzte Laufzeitauszüge und injizierte laufzeiteigene Blöcke gedacht. Sie sind
getrennt von Bootstrap-Limits, Startup-Kontext-Limits und Skills-Prompt-
Limits.
Bei Bildern skaliert OpenClaw Transkript-/Tool-Bild-Payloads vor Provider-Aufrufen herunter.
Verwenden Sie `agents.defaults.imageMaxDimensionPx` (Standard: `1200`), um dies abzustimmen:
- Niedrigere Werte reduzieren normalerweise die Vision-Token-Nutzung und die Payload-Größe.
- Höhere Werte bewahren mehr visuelle Details für OCR-/UI-lastige Screenshots.
Für eine praktische Aufschlüsselung (pro injizierter Datei, Tools, Skills und System-Prompt-Größe) verwenden Sie `/context list` oder `/context detail`. Siehe [Context](/de/concepts/context).
Für eine praktische Aufschlüsselung (pro injizierter Datei, Tools, Skills und Größe des System-Prompts) verwenden Sie `/context list` oder `/context detail`. Siehe [Context](/de/concepts/context).
## So sehen Sie die aktuelle Token-Nutzung
Verwenden Sie diese Befehle im Chat:
- `/status` → **statuskarte mit vielen Emojis** mit dem Sitzungsmodell, der Kontextnutzung,
den Eingabe-/Ausgabe-Token der letzten Antwort und den **geschätzten Kosten** (nur API-Schlüssel).
- `/usage off|tokens|full` → hängt an jede Antwort eine **Nutzungsfußzeile pro Antwort** an.
- Wird pro Sitzung beibehalten (gespeichert als `responseUsage`).
den Input-/Output-Token der letzten Antwort und den **geschätzten Kosten** (nur API-Schlüssel).
- `/usage off|tokens|full` → hängt an jede Antwort eine **Nutzungs-Fußzeile pro Antwort** an.
- Bleibt pro Sitzung bestehen (gespeichert als `responseUsage`).
- OAuth-Authentifizierung **blendet Kosten aus** (nur Token).
- `/usage cost` → zeigt eine lokale Kostenzusammenfassung aus OpenClaw-Sitzungsprotokollen an.
Weitere Oberflächen:
- **TUI/Web TUI:** `/status` + `/usage` werden unterstützt.
- **TUI/Web TUI:** `/status` und `/usage` werden unterstützt.
- **CLI:** `openclaw status --usage` und `openclaw channels list` zeigen
normalisierte Provider-Quota-Fenster (`X% left`, keine Kosten pro Antwort).
normalisierte Provider-Quotenfenster an (`X% left`, nicht Kosten pro Antwort).
Aktuelle Provider mit Nutzungsfenster: Anthropic, GitHub Copilot, Gemini CLI,
OpenAI Codex, MiniMax, Xiaomi und z.ai.
Nutzungsoberflächen normalisieren vor der Anzeige gängige feldnative Aliase von Providern.
Für OpenAI-Familie-Responses-Datenverkehr umfasst das sowohl `input_tokens` /
Nutzungsoberflächen normalisieren vor der Anzeige gängige providernative Feldaliase.
Für OpenAI-Family-Responses-Traffic umfasst dies sowohl `input_tokens` /
`output_tokens` als auch `prompt_tokens` / `completion_tokens`, sodass transportspezifische
Feldnamen `/status`, `/usage` oder Sitzungszusammenfassungen nicht verändern.
Auch die JSON-Nutzung von Gemini CLI wird normalisiert: Der Antworttext stammt aus `response`, und
Feldnamen `/status`, `/usage` oder Sitzungszusammenfassungen nicht ändern.
Auch die JSON-Nutzung von Gemini CLI wird normalisiert: Antworttext kommt aus `response`, und
`stats.cached` wird auf `cacheRead` abgebildet, wobei `stats.input_tokens - stats.cached`
verwendet wird, wenn die CLI kein explizites Feld `stats.input` ausgibt.
Für nativen OpenAI-Familie-Responses-Datenverkehr werden WebSocket-/SSE-Nutzungsaliase
auf die gleiche Weise normalisiert, und Summen greifen auf normalisierte Eingabe + Ausgabe zurück, wenn
verwendet wird, wenn die CLI kein explizites Feld `stats.input` bereitstellt.
Für nativen OpenAI-Family-Responses-Traffic werden WebSocket-/SSE-Nutzungsaliase
auf dieselbe Weise normalisiert, und Summen greifen auf normalisierte Input- + Output-Werte zurück, wenn
`total_tokens` fehlt oder `0` ist.
Wenn der aktuelle Sitzungssnapshot spärlich ist, können `/status` und `session_status`
auch Token-/Cache-Zähler und die aktive Laufzeit-Modellbezeichnung aus dem zuletzt verwendeten Transkript-Nutzungsprotokoll wiederherstellen. Bereits vorhandene Live-Werte ungleich null haben weiterhin Vorrang vor Transkript-Fallback-Werten, und größere promptorientierte
Wenn der aktuelle Sitzungssnapshot nur spärlich ist, können `/status` und `session_status`
außerdem Token-/Cache-Zähler und das aktive Laufzeitmodell-Label aus dem
aktuellsten Nutzungsprotokoll des Transkripts wiederherstellen. Vorhandene von null verschiedene Live-Werte
haben weiterhin Vorrang vor Transkript-Fallback-Werten, und größere promptorientierte
Transkript-Summen können gewinnen, wenn gespeicherte Summen fehlen oder kleiner sind.
Die Nutzungsautorisierung für Provider-Quota-Fenster stammt, sofern verfügbar, aus providerspezifischen Hooks; andernfalls greift OpenClaw auf passende OAuth-/API-Schlüssel-Anmeldedaten aus Auth-Profilen, Umgebungsvariablen oder der Konfiguration zurück.
Die Nutzungsauthentifizierung für Provider-Quotenfenster stammt aus providerspezifischen Hooks, wenn
verfügbar; andernfalls greift OpenClaw auf passende OAuth-/API-Key-Zugangsdaten
aus Auth-Profilen, der Umgebung oder der Konfiguration zurück.
## Kostenschätzung (wenn angezeigt)
Kosten werden anhand Ihrer Modell-Preis-Konfiguration geschätzt:
Die Kosten werden anhand Ihrer Modellpreis-Konfiguration geschätzt:
```
models.providers.<provider>.models[].cost
```
Dies sind **USD pro 1 Mio. Token** für `input`, `output`, `cacheRead` und
`cacheWrite`. Wenn Preisdaten fehlen, zeigt OpenClaw nur Token an. OAuth-Token
zeigen niemals Dollar-Kosten an.
`cacheWrite`. Wenn die Preisangaben fehlen, zeigt OpenClaw nur Token an. OAuth-Token
zeigen niemals Dollarkosten an.
## Auswirkungen von Cache-TTL und Beschneidung
## Auswirkungen von Cache-TTL und Pruning
Provider-Prompt-Caching gilt nur innerhalb des Cache-TTL-Fensters. OpenClaw kann
optional **Cache-TTL-Beschneidung** ausführen: Es beschneidet die Sitzung, sobald die Cache-TTL
optional **Cache-TTL-Pruning** ausführen: Es beschneidet die Sitzung, sobald die Cache-TTL
abgelaufen ist, und setzt dann das Cache-Fenster zurück, sodass nachfolgende Anfragen den
frisch gecachten Kontext erneut verwenden können, anstatt den gesamten Verlauf neu zu cachen. Dadurch bleiben die
Cache-Schreibkosten niedriger, wenn eine Sitzung länger als die TTL inaktiv bleibt.
frisch gecachten Kontext wiederverwenden können, anstatt den vollständigen Verlauf erneut zu cachen.
Dadurch bleiben die Cache-Schreibkosten niedriger, wenn eine Sitzung nach Ablauf der TTL untätig wird.
Konfigurieren Sie dies in der [Gateway-Konfiguration](/de/gateway/configuration) und lesen Sie die
Konfigurieren Sie dies in [Gateway configuration](/de/gateway/configuration) und lesen Sie die
Verhaltensdetails unter [Session pruning](/de/concepts/session-pruning).
Heartbeat kann den Cache über Leerlaufphasen hinweg **warm** halten. Wenn Ihre Modell-Cache-TTL
`1h` beträgt, kann das Setzen des Heartbeat-Intervalls knapp darunter (z. B. `55m`) verhindern,
dass der gesamte Prompt erneut gecacht werden muss, was Cache-Schreibkosten reduziert.
Heartbeat kann den Cache über Leerlaufphasen hinweg **warm** halten. Wenn die Cache-TTL
Ihres Modells `1h` beträgt, kann das Setzen des Heartbeat-Intervalls knapp darunter (z. B. `55m`)
verhindern, dass der vollständige Prompt erneut gecacht werden muss, wodurch sich Cache-Schreibkosten verringern.
In Multi-Agent-Setups können Sie eine gemeinsame Modellkonfiguration beibehalten und das Cache-Verhalten
In Multi-Agent-Setups können Sie eine gemeinsam genutzte Modellkonfiguration beibehalten und das Cache-Verhalten
pro Agent mit `agents.list[].params.cacheRetention` abstimmen.
Eine vollständige Anleitung zu allen Stellschrauben finden Sie unter [Prompt Caching](/de/reference/prompt-caching).
Eine vollständige Anleitung zu allen Reglern finden Sie unter [Prompt Caching](/de/reference/prompt-caching).
Bei der Preisgestaltung der Anthropic API sind Cache-Lesevorgänge deutlich günstiger als Eingabe-Token,
während Cache-Schreibvorgänge mit einem höheren Multiplikator berechnet werden. Die aktuellen Tarife und TTL-Multiplikatoren finden Sie in der Anthropic-Dokumentation zur Prompt-Caching-Preisgestaltung:
Bei den Anthropic-API-Preisen sind Cache-Lesevorgänge deutlich günstiger als Input-
Token, während Cache-Schreibvorgänge mit einem höheren Multiplikator abgerechnet werden. Die aktuellen Preise und TTL-Multiplikatoren finden Sie in der Anthropic-Dokumentation zur Preisgestaltung für Prompt-Caching:
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
### Beispiel: 1h-Cache mit Heartbeat warm halten
@ -136,7 +155,7 @@ agents:
every: "55m"
```
### Beispiel: gemischter Datenverkehr mit Cache-Strategie pro Agent
### Beispiel: gemischter Traffic mit agentenspezifischer Cache-Strategie
```yaml
agents:
@ -146,24 +165,24 @@ agents:
models:
"anthropic/claude-opus-4-6":
params:
cacheRetention: "long" # Standardbasis für die meisten Agents
cacheRetention: "long" # default baseline for most agents
list:
- id: "research"
default: true
heartbeat:
every: "55m" # langen Cache für tiefe Sitzungen warm halten
every: "55m" # keep long cache warm for deep sessions
- id: "alerts"
params:
cacheRetention: "none" # Cache-Schreibvorgänge für burstartige Benachrichtigungen vermeiden
cacheRetention: "none" # avoid cache writes for bursty notifications
```
`agents.list[].params` wird über die `params` des ausgewählten Modells zusammengeführt, sodass Sie
nur `cacheRetention` überschreiben und andere Modellstandards unverändert erben können.
`agents.list[].params` wird über `params` des ausgewählten Modells zusammengeführt, sodass Sie
nur `cacheRetention` überschreiben und andere Modellstandards unverändert übernehmen können.
### Beispiel: Anthropic-1M-Kontext-Beta-Header aktivieren
Das 1M-Kontextfenster von Anthropic ist derzeit per Beta-Gating geschützt. OpenClaw kann den
erforderlichen Wert für `anthropic-beta` einfügen, wenn Sie `context1m` bei unterstützten Opus-
Das 1M-Kontextfenster von Anthropic ist derzeit beta-gesteuert. OpenClaw kann den
erforderlichen Wert für `anthropic-beta` injizieren, wenn Sie `context1m` bei unterstützten Opus-
oder Sonnet-Modellen aktivieren.
```yaml
@ -175,22 +194,22 @@ agents:
context1m: true
```
Dies wird auf den Beta-Header `context-1m-2025-08-07` von Anthropic abgebildet.
Dies wird dem Beta-Header `context-1m-2025-08-07` von Anthropic zugeordnet.
Dies gilt nur, wenn `context1m: true` für diesen Modelleintrag gesetzt ist.
Voraussetzung: Die Anmeldedaten müssen für die Nutzung von Langkontext berechtigt sein. Ist dies nicht der Fall,
Voraussetzung: Die Zugangsdaten müssen für die Nutzung mit langem Kontext berechtigt sein. Andernfalls
antwortet Anthropic für diese Anfrage mit einem providerseitigen Rate-Limit-Fehler.
Wenn Sie Anthropic mit OAuth-/Abonnement-Token (`sk-ant-oat-*`) authentifizieren,
überspringt OpenClaw den Beta-Header `context-1m-*`, da Anthropic diese Kombination derzeit
Wenn Sie Anthropic mit OAuth-/Subscription-Token (`sk-ant-oat-*`) authentifizieren,
überspringt OpenClaw den Beta-Header `context-1m-*`, weil Anthropic diese Kombination derzeit
mit HTTP 401 ablehnt.
## Tipps zur Reduzierung von Token-Druck
## Tipps zur Reduzierung des Token-Drucks
- Verwenden Sie `/compact`, um lange Sitzungen zusammenzufassen.
- Kürzen Sie große Tool-Ausgaben in Ihren Workflows.
- Senken Sie `agents.defaults.imageMaxDimensionPx` bei screenshotlastigen Sitzungen.
- Reduzieren Sie `agents.defaults.imageMaxDimensionPx` für screenshotlastige Sitzungen.
- Halten Sie Skill-Beschreibungen kurz (die Skills-Liste wird in den Prompt injiziert).
- Bevorzugen Sie kleinere Modelle für ausführliche, explorative Arbeit.