diff --git a/docs/de/channels/matrix.md b/docs/de/channels/matrix.md index 34920ae8c..78e0f94f7 100644 --- a/docs/de/channels/matrix.md +++ b/docs/de/channels/matrix.md @@ -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"`. `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-.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__HOMESERVER` - `MATRIX__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-`, 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..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 "" @@ -517,25 +518,25 @@ Ausführliche Details zur Geräteverifizierung: openclaw matrix verify device "" --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 ` ü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 ` ü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 ` hinzu, wenn du gezielt ein benanntes Matrix-Konto ansprechen möchtest. +Füge `--account ` 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//__//`. -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 ` hinzu, wenn du gezielt ein benanntes Matrix-Konto ansprechen möchtest. +Füge `--account ` 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..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..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..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 ``` -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 allow-once`, `/approve allow-always` oder `/approve deny`. +Genehmiger können auf diese Nachricht reagieren oder die Fallback-Slash-Befehle verwenden: `/approve allow-once`, `/approve allow-always` oder `/approve 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..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..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..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 ` für CLI-Befehle, die auf impliziter Kontoauswahl basieren. +Wenn du mehrere benannte Konten konfigurierst, setze `defaultAccount` oder übergib `--account ` für CLI-Befehle, die auf impliziter Kontoauswahl beruhen. Übergib `--account ` 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..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..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..account`: beschränkt einen geerbten Raumeintrag in Setups mit mehreren Konten auf ein bestimmtes Matrix-Konto. -- `groups..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..account`: beschränkt einen geerbten Raumeintrag in Multi-Account-Setups auf ein bestimmtes Matrix-Konto. +- `groups..allowBots`: raumbezogener Override für Absender aus konfigurierten Bots (`true` oder `"mentions"`). - `groups..users`: absenderbezogene Allowlist pro Raum. -- `groups..tools`: Überschreibungen zum Zulassen/Ablehnen von Tools pro Raum. -- `groups..autoReply`: Überschreibung des Erwähnungsgatings auf Raumebene. `true` deaktiviert Erwähnungsanforderungen für diesen Raum; `false` erzwingt sie wieder. -- `groups..skills`: optionaler Skills-Filter auf Raumebene. -- `groups..systemPrompt`: optionales Snippet für den System Prompt auf Raumebene. -- `rooms`: veralteter Alias für `groups`. +- `groups..tools`: raumbezogene Tool-Allow-/Deny-Overrides. +- `groups..autoReply`: raumbezogener Override für Erwähnungs-Gating. `true` deaktiviert Erwähnungspflichten für diesen Raum; `false` erzwingt sie wieder. +- `groups..skills`: optionaler raumbezogener Skills-Filter. +- `groups..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 diff --git a/docs/de/concepts/system-prompt.md b/docs/de/concepts/system-prompt.md index 0f4018873..961dd6032 100644 --- a/docs/de/concepts/system-prompt.md +++ b/docs/de/concepts/system-prompt.md @@ -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 ``` -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). diff --git a/docs/de/gateway/configuration-reference.md b/docs/de/gateway/configuration-reference.md index 4e93d8918..aa2e1e94e 100644 --- a/docs/de/gateway/configuration-reference.md +++ b/docs/de/gateway/configuration-reference.md @@ -1,43 +1,43 @@ --- read_when: - - Sie benötigen die genaue feldbezogene Konfigurationssemantik oder Standardwerte - - Sie validieren Kanal-, Modell-, Gateway- oder Tool-Konfigurationsblöcke -summary: Gateway-Konfigurationsreferenz für zentrale OpenClaw-Schlüssel, Standardwerte und Links zu dedizierten Subsystemreferenzen + - Sie benötigen genaue feldbezogene Konfigurationssemantik oder Standardwerte + - Sie validieren Konfigurationsblöcke für Kanal, Modell, Gateway oder Tool +summary: Gateway-Konfigurationsreferenz für zentrale OpenClaw-Schlüssel, Standardwerte und Links zu dedizierten Subsystem-Referenzen title: Konfigurationsreferenz x-i18n: - generated_at: "2026-04-15T14:40:32Z" + generated_at: "2026-04-15T19:41:36Z" model: gpt-5.4 provider: openai - source_hash: 7a4da3b41d0304389bd6359aac1185c231e529781b607656ab352f8a8104bdba + source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d source_path: gateway/configuration-reference.md workflow: 15 --- # Konfigurationsreferenz -Zentrale Konfigurationsreferenz für `~/.openclaw/openclaw.json`. Eine aufgabenorientierte Übersicht finden Sie unter [Configuration](/de/gateway/configuration). +Zentrale Konfigurationsreferenz für `~/.openclaw/openclaw.json`. Eine aufgabenorientierte Übersicht finden Sie unter [Konfiguration](/de/gateway/configuration). -Diese Seite behandelt die wichtigsten OpenClaw-Konfigurationsoberflächen und verlinkt weiterführend, wenn ein Subsystem eine eigene ausführlichere Referenz hat. Sie versucht **nicht**, jeden kanal-/Plugin-eigenen Befehlskatalog oder jede tiefgehende Speicher-/QMD-Einstellung auf einer einzigen Seite einzubetten. +Diese Seite behandelt die wichtigsten OpenClaw-Konfigurationsoberflächen und verweist nach außen, wenn ein Subsystem eine eigene, ausführlichere Referenz hat. Sie versucht **nicht**, jeden kanal-/Plugin-eigenen Befehlskatalog oder jede tiefgehende Speicher-/QMD-Einstellung auf einer einzigen Seite einzubetten. -Code-Quelle: +Code-Wahrheit: -- `openclaw config schema` gibt das aktive JSON Schema aus, das für Validierung und Control UI verwendet wird, wobei verfügbare Metadaten aus gebündelten Plugins/Kanälen zusammengeführt werden -- `config.schema.lookup` gibt einen einzelnen pfadbezogenen Schemaknoten für Drill-down-Werkzeuge zurück +- `openclaw config schema` gibt das Live-JSON-Schema aus, das für Validierung und Control UI verwendet wird, wobei gebündelte/Plugin-/Kanal-Metadaten zusammengeführt werden, wenn sie verfügbar sind +- `config.schema.lookup` gibt einen einzelnen pfadbezogenen Schemaknoten für Drilldown-Tools zurück - `pnpm config:docs:check` / `pnpm config:docs:gen` validieren den Hash der Konfigurationsdokumentations-Baseline gegen die aktuelle Schemaoberfläche Dedizierte ausführliche Referenzen: -- [Memory-Konfigurationsreferenz](/de/reference/memory-config) für `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` und Dreaming-Konfiguration unter `plugins.entries.memory-core.config.dreaming` -- [Slash Commands](/de/tools/slash-commands) für den aktuellen integrierten + gebündelten Befehlskatalog -- zugehörige Kanal-/Plugin-Seiten für kanalspezifische Befehlsoberflächen +- [Speicherkonfigurationsreferenz](/de/reference/memory-config) für `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` und Dreaming-Konfiguration unter `plugins.entries.memory-core.config.dreaming` +- [Slash-Befehle](/de/tools/slash-commands) für den aktuellen integrierten + gebündelten Befehlskatalog +- Eigentümerseiten von Kanal/Plugin für kanalspezifische Befehlsoberflächen -Das Konfigurationsformat ist **JSON5** (Kommentare + nachgestellte Kommas sind erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden. +Das Konfigurationsformat ist **JSON5** (Kommentare + nachgestellte Kommata sind erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden. --- ## Kanäle -Jeder Kanal startet automatisch, wenn sein Konfigurationsabschnitt vorhanden ist (außer bei `enabled: false`). +Jeder Kanal startet automatisch, wenn sein Konfigurationsabschnitt vorhanden ist (außer `enabled: false`). ### DM- und Gruppenzugriff @@ -46,25 +46,25 @@ Alle Kanäle unterstützen DM-Richtlinien und Gruppenrichtlinien: | DM-Richtlinie | Verhalten | | ------------------- | -------------------------------------------------------------- | | `pairing` (Standard) | Unbekannte Absender erhalten einen einmaligen Pairing-Code; der Eigentümer muss zustimmen | -| `allowlist` | Nur Absender in `allowFrom` (oder gepaartem Allow-Store) | +| `allowlist` | Nur Absender in `allowFrom` (oder gepaartem Zulassungsspeicher) | | `open` | Alle eingehenden DMs zulassen (erfordert `allowFrom: ["*"]`) | | `disabled` | Alle eingehenden DMs ignorieren | | Gruppenrichtlinie | Verhalten | | --------------------- | ----------------------------------------------------- | -| `allowlist` (Standard) | Nur Gruppen, die der konfigurierten Allowlist entsprechen | -| `open` | Gruppen-Allowlists umgehen (Mention-Gating gilt weiterhin) | -| `disabled` | Alle Gruppen-/Raumnachrichten blockieren | +| `allowlist` (Standard) | Nur Gruppen, die der konfigurierten Zulassungsliste entsprechen | +| `open` | Gruppen-Zulassungslisten umgehen (Erwähnungs-Gating gilt weiterhin) | +| `disabled` | Alle Gruppen-/Raumnachrichten blockieren | -`channels.defaults.groupPolicy` legt den Standard fest, wenn die `groupPolicy` eines Anbieters nicht gesetzt ist. +`channels.defaults.groupPolicy` setzt den Standard, wenn die `groupPolicy` eines Providers nicht gesetzt ist. Pairing-Codes laufen nach 1 Stunde ab. Ausstehende DM-Pairing-Anfragen sind auf **3 pro Kanal** begrenzt. -Wenn ein Anbieterblock vollständig fehlt (`channels.` nicht vorhanden), fällt die Laufzeit-Gruppenrichtlinie auf `allowlist` zurück (fail-closed) und es wird beim Start eine Warnung ausgegeben. +Wenn ein Provider-Block vollständig fehlt (`channels.` fehlt), fällt die Laufzeit-Gruppenrichtlinie auf `allowlist` zurück (fail-closed) und gibt beim Start eine Warnung aus. ### Kanal-Modellüberschreibungen -Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu binden. Werte akzeptieren `provider/model` oder konfigurierte Modellaliase. Das Kanal-Mapping wird angewendet, wenn eine Sitzung noch keine Modellüberschreibung hat (zum Beispiel über `/model` gesetzt). +Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu binden. Werte akzeptieren `provider/model` oder konfigurierte Modell-Aliase. Die Kanalzuordnung wird angewendet, wenn eine Sitzung nicht bereits eine Modellüberschreibung hat (zum Beispiel durch `/model` gesetzt). ```json5 { @@ -85,9 +85,9 @@ Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu } ``` -### Kanalstandards und Heartbeat +### Kanal-Standardwerte und Heartbeat -Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heartbeat-Verhalten über Anbieter hinweg: +Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heartbeat-Verhalten über Provider hinweg: ```json5 { @@ -105,15 +105,15 @@ Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heart } ``` -- `channels.defaults.groupPolicy`: Fallback-Gruppenrichtlinie, wenn auf Anbieterebene keine `groupPolicy` gesetzt ist. -- `channels.defaults.contextVisibility`: Standardmodus für die Sichtbarkeit ergänzender Kontexte für alle Kanäle. Werte: `all` (Standard, schließt allen zitierten/Thread-/Verlaufs-Kontext ein), `allowlist` (schließt nur Kontext von Absendern auf der Allowlist ein), `allowlist_quote` (wie allowlist, behält aber expliziten Zitat-/Antwort-Kontext bei). Überschreibung pro Kanal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: Gesunde Kanalstatus in der Heartbeat-Ausgabe einschließen. -- `channels.defaults.heartbeat.showAlerts`: Beeinträchtigte/fehlerhafte Status in der Heartbeat-Ausgabe einschließen. +- `channels.defaults.groupPolicy`: Fallback-Gruppenrichtlinie, wenn die providerbezogene `groupPolicy` nicht gesetzt ist. +- `channels.defaults.contextVisibility`: Standardmodus für die Sichtbarkeit ergänzenden Kontexts für alle Kanäle. Werte: `all` (Standard, gesamten zitierten/Thread-/Verlaufs-Kontext einbeziehen), `allowlist` (nur Kontext von zugelassenen Absendern einbeziehen), `allowlist_quote` (wie allowlist, aber expliziten Zitat-/Antwort-Kontext beibehalten). Überschreibung pro Kanal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: Gesunde Kanalstatus in die Heartbeat-Ausgabe einbeziehen. +- `channels.defaults.heartbeat.showAlerts`: Beeinträchtigte/Fehler-Status in die Heartbeat-Ausgabe einbeziehen. - `channels.defaults.heartbeat.useIndicator`: Kompakte Heartbeat-Ausgabe im Indikatorstil rendern. ### WhatsApp -WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automatisch, wenn eine verknüpfte Sitzung vorhanden ist. +WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet automatisch, wenn eine verknüpfte Sitzung existiert. ```json5 { @@ -124,7 +124,7 @@ WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automa textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // blaue Häkchen (false im Selbstchat-Modus) groups: { "*": { requireMention: true }, }, @@ -165,8 +165,8 @@ WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automa ``` - Ausgehende Befehle verwenden standardmäßig das Konto `default`, falls vorhanden; andernfalls die erste konfigurierte Konto-ID (sortiert). -- Das optionale `channels.whatsapp.defaultAccount` überschreibt diese Fallback-Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. -- Das Legacy-Authentifizierungsverzeichnis für ein einzelnes Baileys-Konto wird von `openclaw doctor` nach `whatsapp/default` migriert. +- Optional überschreibt `channels.whatsapp.defaultAccount` diese Fallback-Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. +- Das alte Single-Account-Baileys-Authentifizierungsverzeichnis wird durch `openclaw doctor` nach `whatsapp/default` migriert. - Überschreibungen pro Konto: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -226,12 +226,12 @@ WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automa ``` - Bot-Token: `channels.telegram.botToken` oder `channels.telegram.tokenFile` (nur reguläre Datei; Symlinks werden abgelehnt), mit `TELEGRAM_BOT_TOKEN` als Fallback für das Standardkonto. -- Das optionale `channels.telegram.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- Optional überschreibt `channels.telegram.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. - In Multi-Account-Setups (2+ Konto-IDs) setzen Sie einen expliziten Standard (`channels.telegram.defaultAccount` oder `channels.telegram.accounts.default`), um Fallback-Routing zu vermeiden; `openclaw doctor` warnt, wenn dies fehlt oder ungültig ist. -- `configWrites: false` blockiert von Telegram initiierte Konfigurationsschreibvorgänge (Supergroup-ID-Migrationen, `/config set|unset`). -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` konfigurieren persistente ACP-Bindungen für Foren-Themen (verwenden Sie das kanonische `chatId:topic:topicId` in `match.peer.id`). Die Feldsemantik ist gemeinsam in [ACP Agents](/de/tools/acp-agents#channel-specific-settings) definiert. +- `configWrites: false` blockiert durch Telegram initiierte Konfigurationsschreibvorgänge (Supergroup-ID-Migrationen, `/config set|unset`). +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` konfigurieren persistente ACP-Bindungen für Forum-Themen (verwenden Sie das kanonische `chatId:topic:topicId` in `match.peer.id`). Die Feldsemantik ist gemeinsam beschrieben unter [ACP-Agents](/de/tools/acp-agents#channel-specific-settings). - Telegram-Stream-Vorschauen verwenden `sendMessage` + `editMessageText` (funktioniert in Direkt- und Gruppenchats). -- Retry-Richtlinie: siehe [Retry policy](/de/concepts/retry). +- Retry-Richtlinie: siehe [Retry-Richtlinie](/de/concepts/retry). ### Discord @@ -297,7 +297,7 @@ WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automa enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // Opt-in für sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,33 +334,33 @@ WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automa ``` - Token: `channels.discord.token`, mit `DISCORD_BOT_TOKEN` als Fallback für das Standardkonto. -- Direkte ausgehende Aufrufe, die ein explizites Discord-`token` angeben, verwenden dieses Token für den Aufruf; Einstellungen für Konto-Retry/Richtlinien stammen weiterhin aus dem ausgewählten Konto im aktiven Laufzeit-Snapshot. -- Das optionale `channels.discord.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- Direkte ausgehende Aufrufe, die ein explizites Discord-`token` bereitstellen, verwenden dieses Token für den Aufruf; Konto-Retry-/Richtlinieneinstellungen stammen weiterhin vom ausgewählten Konto im aktiven Laufzeit-Snapshot. +- Optional überschreibt `channels.discord.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. - Verwenden Sie `user:` (DM) oder `channel:` (Guild-Kanal) als Zustellziele; reine numerische IDs werden abgelehnt. - Guild-Slugs sind kleingeschrieben, wobei Leerzeichen durch `-` ersetzt werden; Kanalschlüssel verwenden den Slug-Namen (ohne `#`). Bevorzugen Sie Guild-IDs. - Von Bots verfasste Nachrichten werden standardmäßig ignoriert. `allowBots: true` aktiviert sie; verwenden Sie `allowBots: "mentions"`, um nur Bot-Nachrichten zu akzeptieren, die den Bot erwähnen (eigene Nachrichten werden weiterhin gefiltert). - `channels.discord.guilds..ignoreOtherMentions` (und Kanal-Überschreibungen) verwirft Nachrichten, die einen anderen Benutzer oder eine andere Rolle erwähnen, aber nicht den Bot (ausgenommen @everyone/@here). -- `maxLinesPerMessage` (Standard 17) teilt lange Nachrichten auch dann auf, wenn sie unter 2000 Zeichen bleiben. +- `maxLinesPerMessage` (Standard 17) teilt lange Nachrichten auf, auch wenn sie unter 2000 Zeichen liegen. - `channels.discord.threadBindings` steuert an Discord-Threads gebundenes Routing: - `enabled`: Discord-Überschreibung für an Threads gebundene Sitzungsfunktionen (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` und gebundene Zustellung/Routing) - - `idleHours`: Discord-Überschreibung für automatisches Entfokussieren bei Inaktivität in Stunden (`0` deaktiviert) - - `maxAgeHours`: Discord-Überschreibung für das harte Maximalalter in Stunden (`0` deaktiviert) - - `spawnSubagentSessions`: Opt-in-Schalter für automatische Thread-Erstellung/-Bindung durch `sessions_spawn({ thread: true })` -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` konfigurieren persistente ACP-Bindungen für Kanäle und Threads (verwenden Sie die Kanal-/Thread-ID in `match.peer.id`). Die Feldsemantik ist gemeinsam in [ACP Agents](/de/tools/acp-agents#channel-specific-settings) definiert. + - `idleHours`: Discord-Überschreibung für automatisches Entfokussieren nach Inaktivität in Stunden (`0` deaktiviert) + - `maxAgeHours`: Discord-Überschreibung für hartes Maximalalter in Stunden (`0` deaktiviert) + - `spawnSubagentSessions`: Opt-in-Schalter für automatische Thread-Erstellung/-Bindung bei `sessions_spawn({ thread: true })` +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` konfigurieren persistente ACP-Bindungen für Kanäle und Threads (verwenden Sie die Kanal-/Thread-ID in `match.peer.id`). Die Feldsemantik ist gemeinsam beschrieben unter [ACP-Agents](/de/tools/acp-agents#channel-specific-settings). - `channels.discord.ui.components.accentColor` setzt die Akzentfarbe für Discord-Komponenten-v2-Container. -- `channels.discord.voice` aktiviert Gespräche in Discord-Sprachkanälen sowie optionale automatische Beitritte + TTS-Überschreibungen. +- `channels.discord.voice` aktiviert Discord-Sprachkanal-Unterhaltungen und optionale Auto-Join- + TTS-Überschreibungen. - `channels.discord.voice.daveEncryption` und `channels.discord.voice.decryptionFailureTolerance` werden an die DAVE-Optionen von `@discordjs/voice` durchgereicht (`true` bzw. `24` standardmäßig). -- OpenClaw versucht zusätzlich, die Sprachübertragung wiederherzustellen, indem es nach wiederholten Entschlüsselungsfehlern eine Sprachsitzung verlässt und ihr erneut beitritt. -- `channels.discord.streaming` ist der kanonische Schlüssel für den Stream-Modus. Das Legacy-`streamMode` und boolesche `streaming`-Werte werden automatisch migriert. -- `channels.discord.autoPresence` bildet die Laufzeitverfügbarkeit auf die Bot-Präsenz ab (healthy => online, degraded => idle, exhausted => dnd) und erlaubt optionale Überschreibungen des Statustexts. -- `channels.discord.dangerouslyAllowNameMatching` aktiviert die Abgleichung über veränderliche Namen/Tags erneut (Break-Glass-Kompatibilitätsmodus). -- `channels.discord.execApprovals`: Discord-native Zustellung von Exec-Freigaben und Autorisierung von Freigebenden. - - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Freigaben aktiviert, wenn Freigebende aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. - - `approvers`: Discord-Benutzer-IDs, die Exec-Anfragen freigeben dürfen. Fällt auf `commands.ownerAllowFrom` zurück, wenn weggelassen. - - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Freigaben für alle Agenten weiterzuleiten. - - `sessionFilter`: optionale Muster für Sitzungsschlüssel (Teilstring oder Regex). - - `target`: wohin Freigabeaufforderungen gesendet werden. `"dm"` (Standard) sendet an DMs der Freigebenden, `"channel"` sendet an den Ursprungskanal, `"both"` sendet an beide. Wenn das Ziel `"channel"` einschließt, sind Buttons nur für aufgelöste Freigebende nutzbar. - - `cleanupAfterResolve`: wenn `true`, werden Freigabe-DMs nach Freigabe, Ablehnung oder Zeitüberschreitung gelöscht. +- OpenClaw versucht zusätzlich, den Sprachempfang wiederherzustellen, indem nach wiederholten Entschlüsselungsfehlern eine Sprachsitzung verlassen und erneut beigetreten wird. +- `channels.discord.streaming` ist der kanonische Schlüssel für den Stream-Modus. Veraltete Werte für `streamMode` und boolesches `streaming` werden automatisch migriert. +- `channels.discord.autoPresence` ordnet die Laufzeitverfügbarkeit dem Bot-Status zu (healthy => online, degraded => idle, exhausted => dnd) und erlaubt optionale Überschreibungen für den Statustext. +- `channels.discord.dangerouslyAllowNameMatching` aktiviert veränderliches Namens-/Tag-Matching erneut (Break-Glass-Kompatibilitätsmodus). +- `channels.discord.execApprovals`: Discord-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern. + - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmiger aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. + - `approvers`: Discord-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Fällt auf `commands.ownerAllowFrom` zurück, wenn nicht angegeben. + - `agentFilter`: optionale Zulassungsliste für Agenten-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. + - `sessionFilter`: optionale Muster für Sitzungsschlüssel (Teilzeichenfolge oder Regex). + - `target`: wohin Genehmigungsaufforderungen gesendet werden. `"dm"` (Standard) sendet an DMs der Genehmiger, `"channel"` sendet in den Ursprungskanal, `"both"` sendet an beide. Wenn das Ziel `"channel"` enthält, sind Schaltflächen nur für aufgelöste Genehmiger verwendbar. + - `cleanupAfterResolve`: wenn `true`, werden Genehmigungs-DMs nach Genehmigung, Ablehnung oder Timeout gelöscht. **Modi für Reaktionsbenachrichtigungen:** `off` (keine), `own` (Nachrichten des Bots, Standard), `all` (alle Nachrichten), `allowlist` (aus `guilds..users` für alle Nachrichten). @@ -394,10 +394,10 @@ WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automa ``` - Service-Account-JSON: inline (`serviceAccount`) oder dateibasiert (`serviceAccountFile`). -- SecretRef für den Service Account wird ebenfalls unterstützt (`serviceAccountRef`). -- Umgebungsvariablen-Fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` oder `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- SecretRef für den Service-Account wird ebenfalls unterstützt (`serviceAccountRef`). +- Umgebungs-Fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` oder `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Verwenden Sie `spaces/` oder `users/` als Zustellziele. -- `channels.googlechat.dangerouslyAllowNameMatching` aktiviert die Abgleichung über veränderliche E-Mail-Principals erneut (Break-Glass-Kompatibilitätsmodus). +- `channels.googlechat.dangerouslyAllowNameMatching` aktiviert veränderliches E-Mail-Principal-Matching erneut (Break-Glass-Kompatibilitätsmodus). ### Slack @@ -464,29 +464,34 @@ WhatsApp läuft über den Web-Kanal des Gateway (Baileys Web). Er startet automa } ``` -- **Socket-Modus** erfordert sowohl `botToken` als auch `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` als Umgebungsvariablen-Fallback für das Standardkonto). -- **HTTP-Modus** erfordert `botToken` plus `signingSecret` (auf Root-Ebene oder pro Konto). -- `botToken`, `appToken`, `signingSecret` und `userToken` akzeptieren Klartext-Strings oder SecretRef-Objekte. -- Slack-Konto-Snapshots stellen pro Anmeldedaten Quelle-/Statusfelder bereit, etwa `botTokenSource`, `botTokenStatus`, `appTokenStatus` und im HTTP-Modus `signingSecretStatus`. `configured_unavailable` bedeutet, dass das Konto über SecretRef konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den Secret-Wert jedoch nicht auflösen konnte. -- `configWrites: false` blockiert von Slack initiierte Konfigurationsschreibvorgänge. -- Das optionale `channels.slack.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. -- `channels.slack.streaming.mode` ist der kanonische Schlüssel für den Slack-Stream-Modus. `channels.slack.streaming.nativeTransport` steuert den nativen Streaming-Transport von Slack. Legacy-`streamMode`, boolesche `streaming`- und `nativeStreaming`-Werte werden automatisch migriert. +- **Socket-Modus** erfordert sowohl `botToken` als auch `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` für den Env-Fallback des Standardkontos). +- **HTTP-Modus** erfordert `botToken` plus `signingSecret` (am Root oder pro Konto). +- `botToken`, `appToken`, `signingSecret` und `userToken` akzeptieren Klartext- + Strings oder SecretRef-Objekte. +- Slack-Konto-Snapshots stellen pro Zugangsdatenquelle/-status Felder wie + `botTokenSource`, `botTokenStatus`, `appTokenStatus` und im HTTP-Modus + `signingSecretStatus` bereit. `configured_unavailable` bedeutet, dass das Konto + über SecretRef konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den + Secret-Wert aber nicht auflösen konnte. +- `configWrites: false` blockiert durch Slack initiierte Konfigurationsschreibvorgänge. +- Optional überschreibt `channels.slack.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- `channels.slack.streaming.mode` ist der kanonische Schlüssel für den Slack-Stream-Modus. `channels.slack.streaming.nativeTransport` steuert den nativen Streaming-Transport von Slack. Veraltete Werte für `streamMode`, boolesches `streaming` und `nativeStreaming` werden automatisch migriert. - Verwenden Sie `user:` (DM) oder `channel:` als Zustellziele. **Modi für Reaktionsbenachrichtigungen:** `off`, `own` (Standard), `all`, `allowlist` (aus `reactionAllowlist`). -**Thread-Sitzungsisolierung:** `thread.historyScope` ist pro Thread (Standard) oder über den Kanal geteilt. `thread.inheritParent` kopiert das übergeordnete Kanal-Transkript in neue Threads. +**Thread-Sitzungsisolierung:** `thread.historyScope` ist pro Thread (Standard) oder kanalweit gemeinsam. `thread.inheritParent` kopiert das Elternkanal-Transkript in neue Threads. -- Native Slack-Streams sowie der Slack-Assistentenstil-Status „is typing...“ für Threads erfordern ein Antwort-Thread-Ziel. DMs auf oberster Ebene bleiben standardmäßig außerhalb von Threads, daher verwenden sie stattdessen `typingReaction` oder normale Zustellung statt einer Thread-Vorschau. -- `typingReaction` fügt der eingehenden Slack-Nachricht während der Ausführung einer Antwort vorübergehend eine Reaktion hinzu und entfernt sie nach Abschluss wieder. Verwenden Sie einen Slack-Emoji-Shortcode wie `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: Slack-native Zustellung von Exec-Freigaben und Autorisierung von Freigebenden. Gleiches Schema wie bei Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack-Benutzer-IDs), `agentFilter`, `sessionFilter` und `target` (`"dm"`, `"channel"` oder `"both"`). +- Slack-native Streams plus der Slack-assistentenartige Thread-Status „is typing...“ erfordern ein Antwort-Thread-Ziel. DMs auf oberster Ebene bleiben standardmäßig außerhalb von Threads, daher verwenden sie `typingReaction` oder normale Zustellung statt der Thread-artigen Vorschau. +- `typingReaction` fügt der eingehenden Slack-Nachricht temporär eine Reaktion hinzu, während eine Antwort läuft, und entfernt sie nach Abschluss. Verwenden Sie einen Slack-Emoji-Shortcode wie `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: Slack-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern. Gleiches Schema wie bei Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack-Benutzer-IDs), `agentFilter`, `sessionFilter` und `target` (`"dm"`, `"channel"` oder `"both"`). -| Aktionsgruppe | Standard | Hinweise | -| ------------- | -------- | ------------------------ | +| Aktionsgruppe | Standard | Hinweise | +| ------------- | -------- | ----------------------- | | reactions | aktiviert | Reagieren + Reaktionen auflisten | | messages | aktiviert | Lesen/senden/bearbeiten/löschen | | pins | aktiviert | Anheften/lösen/auflisten | -| memberInfo | aktiviert | Mitgliedsinformationen | +| memberInfo | aktiviert | Mitgliedsinformationen | | emojiList | aktiviert | Benutzerdefinierte Emoji-Liste | ### Mattermost @@ -521,18 +526,24 @@ Mattermost wird als Plugin ausgeliefert: `openclaw plugins install @openclaw/mat } ``` -Chat-Modi: `oncall` (antwortet auf @-Erwähnung, Standard), `onmessage` (jede Nachricht), `onchar` (Nachrichten, die mit einem Trigger-Präfix beginnen). +Chat-Modi: `oncall` (antwortet bei @-Erwähnung, Standard), `onmessage` (jede Nachricht), `onchar` (Nachrichten, die mit einem Trigger-Präfix beginnen). Wenn native Mattermost-Befehle aktiviert sind: - `commands.callbackPath` muss ein Pfad sein (zum Beispiel `/api/channels/mattermost/command`), keine vollständige URL. -- `commands.callbackUrl` muss auf den Gateway-Endpunkt von OpenClaw aufgelöst werden und vom Mattermost-Server aus erreichbar sein. -- Native Slash-Callbacks werden mit den pro Befehl vergebenen Tokens authentifiziert, die Mattermost bei der Registrierung des Slash-Befehls zurückgibt. Wenn die Registrierung fehlschlägt oder keine Befehle aktiviert sind, lehnt OpenClaw Callbacks mit `Unauthorized: invalid command token.` ab. -- Für private/Tailnet-/interne Callback-Hosts muss Mattermost unter Umständen `ServiceSettings.AllowedUntrustedInternalConnections` so konfigurieren, dass der Callback-Host/-Domain enthalten ist. Verwenden Sie Host-/Domain-Werte, keine vollständigen URLs. -- `channels.mattermost.configWrites`: von Mattermost initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. -- `channels.mattermost.requireMention`: `@mention` vor Antworten in Kanälen verlangen. -- `channels.mattermost.groups..requireMention`: kanalbezogene Überschreibung für Mention-Gating (`"*"` als Standard). -- Das optionale `channels.mattermost.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- `commands.callbackUrl` muss auf den OpenClaw-Gateway-Endpunkt auflösen und vom Mattermost-Server aus erreichbar sein. +- Native Slash-Callbacks werden mit den pro Befehl zurückgegebenen Tokens + authentifiziert, die Mattermost bei der Registrierung von Slash-Befehlen + zurückgibt. Wenn die Registrierung fehlschlägt oder keine Befehle aktiviert + werden, lehnt OpenClaw Callbacks mit + `Unauthorized: invalid command token.` ab. +- Für private/tailnet/interne Callback-Hosts kann Mattermost verlangen, dass + `ServiceSettings.AllowedUntrustedInternalConnections` den Callback-Host bzw. die Domain enthält. + Verwenden Sie Host-/Domain-Werte, keine vollständigen URLs. +- `channels.mattermost.configWrites`: durch Mattermost initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- `channels.mattermost.requireMention`: `@mention` verlangen, bevor in Kanälen geantwortet wird. +- `channels.mattermost.groups..requireMention`: Überschreibung des Erwähnungs-Gatings pro Kanal (`"*"` für Standard). +- Optional überschreibt `channels.mattermost.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. ### Signal @@ -555,9 +566,9 @@ Wenn native Mattermost-Befehle aktiviert sind: **Modi für Reaktionsbenachrichtigungen:** `off`, `own` (Standard), `all`, `allowlist` (aus `reactionAllowlist`). -- `channels.signal.account`: bindet den Kanalstart an eine bestimmte Signal-Kontoidentität. -- `channels.signal.configWrites`: erlaubt oder verweigert von Signal initiierte Konfigurationsschreibvorgänge. -- Das optionale `channels.signal.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- `channels.signal.account`: Kanalstart an eine bestimmte Signal-Kontoidentität binden. +- `channels.signal.configWrites`: durch Signal initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- Optional überschreibt `channels.signal.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. ### BlueBubbles @@ -569,21 +580,21 @@ BlueBubbles ist der empfohlene iMessage-Pfad (Plugin-gestützt, konfiguriert unt bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, Gruppensteuerung und erweiterte Aktionen: + // serverUrl, password, webhookPath, Gruppensteuerungen und erweiterte Aktionen: // siehe /channels/bluebubbles }, }, } ``` -- Hier abgedeckte zentrale Schlüsselpfade: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Das optionale `channels.bluebubbles.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` können BlueBubbles-Konversationen an persistente ACP-Sitzungen binden. Verwenden Sie einen BlueBubbles-Handle oder Ziel-String (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP Agents](/de/tools/acp-agents#channel-specific-settings). +- Hier behandelte zentrale Schlüsselpfade: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Optional überschreibt `channels.bluebubbles.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` können BlueBubbles-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie einen BlueBubbles-Handle oder Ziel-String (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP-Agents](/de/tools/acp-agents#channel-specific-settings). - Die vollständige BlueBubbles-Kanalkonfiguration ist unter [BlueBubbles](/de/channels/bluebubbles) dokumentiert. ### iMessage -OpenClaw startet `imsg rpc` (JSON-RPC über stdio). Kein Daemon oder Port erforderlich. +OpenClaw startet `imsg rpc` (JSON-RPC über stdio). Kein Daemon und kein Port erforderlich. ```json5 { @@ -607,15 +618,15 @@ OpenClaw startet `imsg rpc` (JSON-RPC über stdio). Kein Daemon oder Port erford } ``` -- Das optionale `channels.imessage.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- Optional überschreibt `channels.imessage.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. - Erfordert Vollzugriff auf die Messages-Datenbank. -- Bevorzugen Sie Ziele vom Typ `chat_id:`. Verwenden Sie `imsg chats --limit 20`, um Chats aufzulisten. +- Bevorzugen Sie `chat_id:`-Ziele. Verwenden Sie `imsg chats --limit 20`, um Chats aufzulisten. - `cliPath` kann auf einen SSH-Wrapper zeigen; setzen Sie `remoteHost` (`host` oder `user@host`) für das Abrufen von Anhängen per SCP. -- `attachmentRoots` und `remoteAttachmentRoots` beschränken Pfade eingehender Anhänge (Standard: `/Users/*/Library/Messages/Attachments`). -- SCP verwendet strikte Host-Key-Prüfung, stellen Sie daher sicher, dass der Host-Key des Relay-Hosts bereits in `~/.ssh/known_hosts` vorhanden ist. -- `channels.imessage.configWrites`: erlaubt oder verweigert von iMessage initiierte Konfigurationsschreibvorgänge. -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` können iMessage-Konversationen an persistente ACP-Sitzungen binden. Verwenden Sie einen normalisierten Handle oder ein explizites Chat-Ziel (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP Agents](/de/tools/acp-agents#channel-specific-settings). +- `attachmentRoots` und `remoteAttachmentRoots` beschränken eingehende Anhangspfade (Standard: `/Users/*/Library/Messages/Attachments`). +- SCP verwendet strikte Host-Key-Prüfung, daher muss der Host-Key des Relay-Hosts bereits in `~/.ssh/known_hosts` vorhanden sein. +- `channels.imessage.configWrites`: durch iMessage initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` können iMessage-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie einen normalisierten Handle oder ein explizites Chat-Ziel (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP-Agents](/de/tools/acp-agents#channel-specific-settings). @@ -659,20 +670,20 @@ Matrix ist erweiterungsgestützt und wird unter `channels.matrix` konfiguriert. ``` - Token-Authentifizierung verwendet `accessToken`; Passwort-Authentifizierung verwendet `userId` + `password`. -- `channels.matrix.proxy` leitet Matrix-HTTP-Datenverkehr über einen expliziten HTTP(S)-Proxy. Benannte Konten können dies mit `channels.matrix.accounts..proxy` überschreiben. +- `channels.matrix.proxy` leitet Matrix-HTTP-Verkehr über einen expliziten HTTP(S)-Proxy. Benannte Konten können dies mit `channels.matrix.accounts..proxy` überschreiben. - `channels.matrix.network.dangerouslyAllowPrivateNetwork` erlaubt private/interne Homeserver. `proxy` und dieses Netzwerk-Opt-in sind unabhängige Steuerungen. - `channels.matrix.defaultAccount` wählt das bevorzugte Konto in Multi-Account-Setups aus. - `channels.matrix.autoJoin` ist standardmäßig `off`, daher werden eingeladene Räume und neue DM-artige Einladungen ignoriert, bis Sie `autoJoin: "allowlist"` mit `autoJoinAllowlist` oder `autoJoin: "always"` setzen. -- `channels.matrix.execApprovals`: Matrix-native Zustellung von Exec-Freigaben und Autorisierung von Freigebenden. - - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Freigaben aktiviert, wenn Freigebende aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. - - `approvers`: Matrix-Benutzer-IDs (z. B. `@owner:example.org`), die Exec-Anfragen freigeben dürfen. - - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Freigaben für alle Agenten weiterzuleiten. - - `sessionFilter`: optionale Muster für Sitzungsschlüssel (Teilstring oder Regex). - - `target`: wohin Freigabeaufforderungen gesendet werden. `"dm"` (Standard), `"channel"` (Ursprungsraum) oder `"both"`. +- `channels.matrix.execApprovals`: Matrix-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern. + - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmiger aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. + - `approvers`: Matrix-Benutzer-IDs (z. B. `@owner:example.org`), die Exec-Anfragen genehmigen dürfen. + - `agentFilter`: optionale Zulassungsliste für Agenten-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. + - `sessionFilter`: optionale Muster für Sitzungsschlüssel (Teilzeichenfolge oder Regex). + - `target`: wohin Genehmigungsaufforderungen gesendet werden. `"dm"` (Standard), `"channel"` (Ursprungsraum) oder `"both"`. - Überschreibungen pro Konto: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` steuert, wie Matrix-DMs zu Sitzungen gruppiert werden: `per-user` (Standard) teilt nach geroutetem Peer, während `per-room` jeden DM-Raum isoliert. -- Matrix-Statusprüfungen und Live-Verzeichnissuchen verwenden dieselbe Proxy-Richtlinie wie der Laufzeitverkehr. -- Die vollständige Matrix-Konfiguration, Targeting-Regeln und Setup-Beispiele sind unter [Matrix](/de/channels/matrix) dokumentiert. +- `channels.matrix.dm.sessionScope` steuert, wie Matrix-DMs in Sitzungen gruppiert werden: `per-user` (Standard) wird nach geroutetem Peer geteilt, während `per-room` jeden DM-Raum isoliert. +- Matrix-Statusprobes und Live-Verzeichnisabfragen verwenden dieselbe Proxy-Richtlinie wie Laufzeitverkehr. +- Die vollständige Matrix-Konfiguration, Zielregeln und Setup-Beispiele sind unter [Matrix](/de/channels/matrix) dokumentiert. ### Microsoft Teams @@ -684,14 +695,14 @@ Microsoft Teams ist erweiterungsgestützt und wird unter `channels.msteams` konf msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, Webhook, Team-/Kanalrichtlinien: + // appId, appPassword, tenantId, webhook, Team-/Kanalrichtlinien: // siehe /channels/msteams }, }, } ``` -- Hier abgedeckte zentrale Schlüsselpfade: `channels.msteams`, `channels.msteams.configWrites`. +- Hier behandelte zentrale Schlüsselpfade: `channels.msteams`, `channels.msteams.configWrites`. - Die vollständige Teams-Konfiguration (Anmeldedaten, Webhook, DM-/Gruppenrichtlinie, Überschreibungen pro Team/pro Kanal) ist unter [Microsoft Teams](/de/channels/msteams) dokumentiert. ### IRC @@ -717,13 +728,13 @@ IRC ist erweiterungsgestützt und wird unter `channels.irc` konfiguriert. } ``` -- Hier abgedeckte zentrale Schlüsselpfade: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Das optionale `channels.irc.defaultAccount` überschreibt die Standardkontenauswahl, wenn es mit einer konfigurierten Konto-ID übereinstimmt. -- Die vollständige IRC-Kanalkonfiguration (Host/Port/TLS/Kanäle/Allowlists/Mention-Gating) ist unter [IRC](/de/channels/irc) dokumentiert. +- Hier behandelte zentrale Schlüsselpfade: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Optional überschreibt `channels.irc.defaultAccount` die Standardkontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- Die vollständige IRC-Kanalkonfiguration (Host/Port/TLS/Kanäle/Zulassungslisten/Erwähnungs-Gating) ist unter [IRC](/de/channels/irc) dokumentiert. ### Multi-Account (alle Kanäle) -Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener `accountId`): +Mehrere Konten pro Kanal ausführen (jedes mit eigener `accountId`): ```json5 { @@ -745,27 +756,27 @@ Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener `accountId`): ``` - `default` wird verwendet, wenn `accountId` weggelassen wird (CLI + Routing). -- Umgebungsvariablen-Tokens gelten nur für das **Standard**konto. +- Env-Tokens gelten nur für das **Standard**konto. - Basis-Kanaleinstellungen gelten für alle Konten, sofern sie nicht pro Konto überschrieben werden. - Verwenden Sie `bindings[].match.accountId`, um jedes Konto an einen anderen Agenten zu routen. -- Wenn Sie ein Nicht-Standardkonto über `openclaw channels add` (oder Kanal-Onboarding) hinzufügen, während Sie noch eine Top-Level-Kanalkonfiguration für ein Einzelkonto verwenden, hebt OpenClaw zunächst die kontobezogenen Top-Level-Werte des Einzelkontos in die Konto-Map des Kanals hoch, damit das ursprüngliche Konto weiterhin funktioniert. Die meisten Kanäle verschieben sie nach `channels..accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. -- Vorhandene reine Kanal-Bindungen (ohne `accountId`) passen weiterhin zum Standardkonto; kontobezogene Bindungen bleiben optional. -- `openclaw doctor --fix` repariert auch gemischte Formen, indem es kontobezogene Top-Level-Werte des Einzelkontos in das für diesen Kanal ausgewählte hochgestufte Konto verschiebt. Die meisten Kanäle verwenden `accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. +- Wenn Sie über `openclaw channels add` (oder Kanal-Onboarding) ein Nicht-Standardkonto hinzufügen, während Sie sich noch in einer Single-Account-Top-Level-Kanalkonfiguration befinden, überführt OpenClaw zunächst kontobezogene Top-Level-Single-Account-Werte in die Konto-Map des Kanals, damit das ursprüngliche Konto weiter funktioniert. Die meisten Kanäle verschieben sie nach `channels..accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. +- Bestehende kanalbezogene Bindungen (ohne `accountId`) passen weiterhin auf das Standardkonto; kontobezogene Bindungen bleiben optional. +- `openclaw doctor --fix` repariert auch gemischte Formen, indem kontobezogene Top-Level-Single-Account-Werte in das für diesen Kanal ausgewählte überführte Konto verschoben werden. Die meisten Kanäle verwenden `accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. -### Andere Erweiterungskanäle +### Weitere Erweiterungskanäle -Viele Erweiterungskanäle werden als `channels.` konfiguriert und auf ihren jeweiligen dedizierten Kanalseiten dokumentiert (zum Beispiel Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat und Twitch). -Siehe den vollständigen Kanalindex: [Channels](/de/channels). +Viele Erweiterungskanäle werden als `channels.` konfiguriert und auf ihren dedizierten Kanalseiten dokumentiert (zum Beispiel Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat und Twitch). +Siehe den vollständigen Kanalindex: [Kanäle](/de/channels). -### Mention-Gating in Gruppenchats +### Erwähnungs-Gating in Gruppenchats -Gruppennachrichten erfordern standardmäßig eine **Erwähnung erforderlich** (Metadaten-Erwähnung oder sichere Regex-Muster). Gilt für WhatsApp-, Telegram-, Discord-, Google Chat- und iMessage-Gruppenchats. +Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erwähnung oder sichere Regex-Muster). Gilt für WhatsApp-, Telegram-, Discord-, Google Chat- und iMessage-Gruppenchats. **Erwähnungstypen:** -- **Metadaten-Erwähnungen**: Native @-Erwähnungen der Plattform. Im WhatsApp-Selbstchatmodus ignoriert. +- **Metadaten-Erwähnungen**: Native Plattform-@-Erwähnungen. Werden im WhatsApp-Selbstchat-Modus ignoriert. - **Textmuster**: Sichere Regex-Muster in `agents.list[].groupChat.mentionPatterns`. Ungültige Muster und unsichere verschachtelte Wiederholungen werden ignoriert. -- Mention-Gating wird nur erzwungen, wenn eine Erkennung möglich ist (native Erwähnungen oder mindestens ein Muster). +- Erwähnungs-Gating wird nur erzwungen, wenn Erkennung möglich ist (native Erwähnungen oder mindestens ein Muster). ```json5 { @@ -778,7 +789,7 @@ Gruppennachrichten erfordern standardmäßig eine **Erwähnung erforderlich** (M } ``` -`messages.groupChat.historyLimit` setzt den globalen Standard. Kanäle können mit `channels..historyLimit` (oder pro Konto) überschreiben. Setzen Sie `0`, um dies zu deaktivieren. +`messages.groupChat.historyLimit` setzt den globalen Standard. Kanäle können dies mit `channels..historyLimit` (oder pro Konto) überschreiben. Setzen Sie `0`, um es zu deaktivieren. #### DM-Verlaufslimits @@ -795,13 +806,13 @@ Gruppennachrichten erfordern standardmäßig eine **Erwähnung erforderlich** (M } ``` -Auflösung: Überschreibung pro DM → Anbieterstandard → kein Limit (alles wird beibehalten). +Auflösung: Überschreibung pro DM → Provider-Standard → kein Limit (alles wird beibehalten). Unterstützt: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Selbstchatmodus +#### Selbstchat-Modus -Nehmen Sie Ihre eigene Nummer in `allowFrom` auf, um den Selbstchatmodus zu aktivieren (ignoriert native @-Erwähnungen, reagiert nur auf Textmuster): +Fügen Sie Ihre eigene Nummer zu `allowFrom` hinzu, um den Selbstchat-Modus zu aktivieren (ignoriert native @-Erwähnungen, antwortet nur auf Textmuster): ```json5 { @@ -822,13 +833,13 @@ Nehmen Sie Ihre eigene Nummer in `allowFrom` auf, um den Selbstchatmodus zu akti } ``` -### Befehle (Behandlung von Chat-Befehlen) +### Befehle (Chat-Befehlshandhabung) ```json5 { commands: { native: "auto", // native Befehle registrieren, wenn unterstützt - nativeSkills: "auto", // native Skill-Befehle registrieren, wenn unterstützt + nativeSkills: "auto", // native Skills-Befehle registrieren, wenn unterstützt text: true, // /commands in Chat-Nachrichten parsen bash: false, // ! erlauben (Alias: /bash) bashForegroundMs: 2000, @@ -836,7 +847,7 @@ Nehmen Sie Ihre eigene Nummer in `allowFrom` auf, um den Selbstchatmodus zu akti mcp: false, // /mcp erlauben plugins: false, // /plugins erlauben debug: false, // /debug erlauben - restart: true, // /restart + Gateway-Neustart-Werkzeug erlauben + restart: true, // /restart + Gateway-Neustart-Tool erlauben ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -851,38 +862,38 @@ Nehmen Sie Ihre eigene Nummer in `allowFrom` auf, um den Selbstchatmodus zu akti -- Dieser Block konfiguriert Befehlsoberflächen. Den aktuellen integrierten + gebündelten Befehlskatalog finden Sie unter [Slash Commands](/de/tools/slash-commands). -- Diese Seite ist eine **Referenz für Konfigurationsschlüssel**, nicht der vollständige Befehlskatalog. Kanal-/Plugin-eigene Befehle wie QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` und Talk `/voice` sind auf ihren Kanal-/Plugin-Seiten sowie unter [Slash Commands](/de/tools/slash-commands) dokumentiert. -- Textbefehle müssen **eigenständige** Nachrichten mit vorangestelltem `/` sein. +- Dieser Block konfiguriert Befehlsoberflächen. Den aktuellen integrierten + gebündelten Befehlskatalog finden Sie unter [Slash-Befehle](/de/tools/slash-commands). +- Diese Seite ist eine **Konfigurationsschlüssel-Referenz**, nicht der vollständige Befehlskatalog. Kanal-/Plugin-eigene Befehle wie QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, Speicher `/dreaming`, phone-control `/phone` und Talk `/voice` sind auf ihren Kanal-/Plugin-Seiten sowie unter [Slash-Befehle](/de/tools/slash-commands) dokumentiert. +- Textbefehle müssen **eigenständige** Nachrichten sein, die mit `/` beginnen. - `native: "auto"` aktiviert native Befehle für Discord/Telegram und lässt Slack deaktiviert. - `nativeSkills: "auto"` aktiviert native Skills-Befehle für Discord/Telegram und lässt Slack deaktiviert. - Überschreibung pro Kanal: `channels.discord.commands.native` (bool oder `"auto"`). `false` löscht zuvor registrierte Befehle. - Überschreiben Sie die Registrierung nativer Skills pro Kanal mit `channels..commands.nativeSkills`. - `channels.telegram.customCommands` fügt zusätzliche Telegram-Bot-Menüeinträge hinzu. - `bash: true` aktiviert `! ` für die Host-Shell. Erfordert `tools.elevated.enabled` und einen Absender in `tools.elevated.allowFrom.`. -- `config: true` aktiviert `/config` (liest/schreibt `openclaw.json`). Für Gateway-`chat.send`-Clients erfordern persistente Schreibvorgänge über `/config set|unset` zusätzlich `operator.admin`; schreibgeschütztes `/config show` bleibt für normale Operator-Clients mit Schreibbereich verfügbar. +- `config: true` aktiviert `/config` (liest/schreibt `openclaw.json`). Für Gateway-`chat.send`-Clients erfordern persistente Schreibvorgänge mit `/config set|unset` zusätzlich `operator.admin`; schreibgeschütztes `/config show` bleibt für normale Operator-Clients mit Schreibbereich verfügbar. - `mcp: true` aktiviert `/mcp` für von OpenClaw verwaltete MCP-Serverkonfiguration unter `mcp.servers`. -- `plugins: true` aktiviert `/plugins` für Plugin-Erkennung, -Installation sowie Steuerung von Aktivierung/Deaktivierung. +- `plugins: true` aktiviert `/plugins` für Plugin-Erkennung sowie Installations- und Aktivierungs-/Deaktivierungssteuerungen. - `channels..configWrites` steuert Konfigurationsänderungen pro Kanal (Standard: true). -- Für Multi-Account-Kanäle steuert `channels..accounts..configWrites` ebenfalls Schreibvorgänge, die dieses Konto betreffen (zum Beispiel `/allowlist --config --account ` oder `/config set channels..accounts....`). -- `restart: false` deaktiviert `/restart` und Aktionen des Gateway-Neustart-Werkzeugs. Standard: `true`. -- `ownerAllowFrom` ist die explizite Eigentümer-Allowlist für nur für Eigentümer bestimmte Befehle/Werkzeuge. Sie ist von `allowFrom` getrennt. +- Für Multi-Account-Kanäle steuert `channels..accounts..configWrites` auch Schreibvorgänge, die auf dieses Konto zielen (zum Beispiel `/allowlist --config --account ` oder `/config set channels..accounts....`). +- `restart: false` deaktiviert `/restart` und Aktionen des Gateway-Neustart-Tools. Standard: `true`. +- `ownerAllowFrom` ist die explizite Eigentümer-Zulassungsliste für nur für Eigentümer verfügbare Befehle/Tools. Sie ist von `allowFrom` getrennt. - `ownerDisplay: "hash"` hasht Eigentümer-IDs im System-Prompt. Setzen Sie `ownerDisplaySecret`, um das Hashing zu steuern. -- `allowFrom` ist anbieterbezogen. Wenn gesetzt, ist es die **einzige** Autorisierungsquelle (Kanal-Allowlists/Pairing und `useAccessGroups` werden ignoriert). -- `useAccessGroups: false` erlaubt es Befehlen, Richtlinien von Zugriffsgruppen zu umgehen, wenn `allowFrom` nicht gesetzt ist. +- `allowFrom` ist providerbezogen. Wenn gesetzt, ist dies die **einzige** Autorisierungsquelle (Kanal-Zulassungslisten/Pairing und `useAccessGroups` werden ignoriert). +- `useAccessGroups: false` erlaubt Befehlen, Zugriffsguppenrichtlinien zu umgehen, wenn `allowFrom` nicht gesetzt ist. - Zuordnung der Befehlsdokumentation: - - integrierter + gebündelter Katalog: [Slash Commands](/de/tools/slash-commands) - - kanalspezifische Befehlsoberflächen: [Channels](/de/channels) + - integrierter + gebündelter Katalog: [Slash-Befehle](/de/tools/slash-commands) + - kanalspezifische Befehlsoberflächen: [Kanäle](/de/channels) - QQ-Bot-Befehle: [QQ Bot](/de/channels/qqbot) - Pairing-Befehle: [Pairing](/de/channels/pairing) - LINE-Kartenbefehl: [LINE](/de/channels/line) - - Memory-Dreaming: [Dreaming](/de/concepts/dreaming) + - Speicher-Dreaming: [Dreaming](/de/concepts/dreaming) --- -## Agent-Standards +## Agenten-Standardwerte ### `agents.defaults.workspace` @@ -896,7 +907,7 @@ Standard: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Optionales Repository-Root, das in der Runtime-Zeile des System-Prompts angezeigt wird. Wenn nicht gesetzt, erkennt OpenClaw es automatisch, indem es vom Workspace aus nach oben traversiert. +Optionales Repository-Root, das in der Runtime-Zeile des System-Prompts angezeigt wird. Wenn nicht gesetzt, erkennt OpenClaw es automatisch, indem vom Workspace aus nach oben gegangen wird. ```json5 { @@ -906,7 +917,7 @@ Optionales Repository-Root, das in der Runtime-Zeile des System-Prompts angezeig ### `agents.defaults.skills` -Optionale Standard-Allowlist für Skills bei Agenten, die +Optionale Standard-Zulassungsliste für Skills für Agenten, die `agents.list[].skills` nicht setzen. ```json5 @@ -914,18 +925,19 @@ Optionale Standard-Allowlist für Skills bei Agenten, die agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // erbt github, weather - { id: "docs", skills: ["docs-search"] }, // ersetzt Standards + { id: "writer" }, // übernimmt github, weather + { id: "docs", skills: ["docs-search"] }, // ersetzt Standardwerte { id: "locked-down", skills: [] }, // keine Skills ], }, } ``` -- Lassen Sie `agents.defaults.skills` weg, um standardmäßig uneingeschränkte Skills zuzulassen. -- Lassen Sie `agents.list[].skills` weg, um die Standards zu erben. +- Lassen Sie `agents.defaults.skills` weg, um standardmäßig uneingeschränkte Skills zu verwenden. +- Lassen Sie `agents.list[].skills` weg, um die Standardwerte zu übernehmen. - Setzen Sie `agents.list[].skills: []` für keine Skills. -- Eine nicht leere Liste in `agents.list[].skills` ist die endgültige Menge für diesen Agenten; sie wird nicht mit Standards zusammengeführt. +- Eine nicht leere Liste in `agents.list[].skills` ist die endgültige Menge für diesen Agenten; sie + wird nicht mit den Standardwerten zusammengeführt. ### `agents.defaults.skipBootstrap` @@ -939,9 +951,9 @@ Deaktiviert die automatische Erstellung von Workspace-Bootstrap-Dateien (`AGENTS ### `agents.defaults.contextInjection` -Steuert, wann Workspace-Bootstrap-Dateien in den System-Prompt injiziert werden. Standard: `"always"`. +Steuert, wann Workspace-Bootstrap-Dateien in den System-Prompt eingefügt werden. Standard: `"always"`. -- `"continuation-skip"`: Sichere Fortsetzungsturns (nach einer abgeschlossenen Assistant-Antwort) überspringen die erneute Injektion des Workspace-Bootstraps, wodurch die Prompt-Größe reduziert wird. Heartbeat-Läufe und Wiederholungen nach Compaction bauen den Kontext weiterhin neu auf. +- `"continuation-skip"`: Sichere Fortsetzungs-Turns (nach einer abgeschlossenen Assistant-Antwort) überspringen das erneute Einfügen des Workspace-Bootstraps, wodurch die Prompt-Größe reduziert wird. Heartbeat-Läufe und Wiederholungen nach Compaction bauen den Kontext weiterhin neu auf. ```json5 { @@ -951,7 +963,7 @@ Steuert, wann Workspace-Bootstrap-Dateien in den System-Prompt injiziert werden. ### `agents.defaults.bootstrapMaxChars` -Maximale Zeichenanzahl pro Workspace-Bootstrap-Datei vor der Kürzung. Standard: `20000`. +Maximale Zeichenanzahl pro Workspace-Bootstrap-Datei vor dem Abschneiden. Standard: `20000`. ```json5 { @@ -961,7 +973,7 @@ Maximale Zeichenanzahl pro Workspace-Bootstrap-Datei vor der Kürzung. Standard: ### `agents.defaults.bootstrapTotalMaxChars` -Maximale Gesamtzahl injizierter Zeichen über alle Workspace-Bootstrap-Dateien hinweg. Standard: `150000`. +Maximale Gesamtzahl an eingefügten Zeichen über alle Workspace-Bootstrap-Dateien hinweg. Standard: `150000`. ```json5 { @@ -971,12 +983,12 @@ Maximale Gesamtzahl injizierter Zeichen über alle Workspace-Bootstrap-Dateien h ### `agents.defaults.bootstrapPromptTruncationWarning` -Steuert den für Agenten sichtbaren Warntext, wenn Bootstrap-Kontext gekürzt wird. +Steuert den für Agenten sichtbaren Warntext, wenn Bootstrap-Kontext abgeschnitten wird. Standard: `"once"`. -- `"off"`: Niemals Warntext in den System-Prompt injizieren. -- `"once"`: Warnung einmal pro eindeutiger Kürzungssignatur injizieren (empfohlen). -- `"always"`: Warnung bei jedem Lauf injizieren, wenn eine Kürzung vorliegt. +- `"off"`: Niemals Warntext in den System-Prompt einfügen. +- `"once"`: Warnung einmal pro eindeutiger Abschneide-Signatur einfügen (empfohlen). +- `"always"`: Warnung bei jedem Lauf einfügen, wenn eine Abschneidung vorliegt. ```json5 { @@ -984,13 +996,148 @@ Standard: `"once"`. } ``` +### Zuordnung der Kontextbudget-Verantwortlichkeit + +OpenClaw hat mehrere umfangreiche Prompt-/Kontextbudgets, und diese sind +bewusst nach Subsystem aufgeteilt, statt alle über einen generischen +Schalter zu führen. + +- `agents.defaults.bootstrapMaxChars` / + `agents.defaults.bootstrapTotalMaxChars`: + normales Einfügen des Workspace-Bootstraps. +- `agents.defaults.startupContext.*`: + einmaliges Startprelude für `/new` und `/reset`, einschließlich aktueller täglicher + `memory/*.md`-Dateien. +- `skills.limits.*`: + die kompakte Skills-Liste, die in den System-Prompt eingefügt wird. +- `agents.defaults.contextLimits.*`: + begrenzte Laufzeit-Auszüge und eingefügte, laufzeiteigene Blöcke. +- `memory.qmd.limits.*`: + Größe von Snippets und Einfügungen für indizierte Speicher-Suche. + +Verwenden Sie die passende Überschreibung pro Agent nur dann, wenn ein Agent ein anderes +Budget benötigt: + +- `agents.list[].skillsLimits.maxSkillsPromptChars` +- `agents.list[].contextLimits.*` + +#### `agents.defaults.startupContext` + +Steuert das Prelude des ersten Turns, das bei einfachen `/new`- und `/reset`- +Läufen eingefügt wird. + +```json5 +{ + agents: { + defaults: { + startupContext: { + enabled: true, + applyOn: ["new", "reset"], + dailyMemoryDays: 2, + maxFileBytes: 16384, + maxFileChars: 1200, + maxTotalChars: 2800, + }, + }, + }, +} +``` + +#### `agents.defaults.contextLimits` + +Gemeinsame Standardwerte für begrenzte Laufzeit-Kontextoberflächen. + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + memoryGetDefaultLines: 120, + toolResultMaxChars: 16000, + postCompactionMaxChars: 1800, + }, + }, + }, +} +``` + +- `memoryGetMaxChars`: Standardobergrenze für `memory_get`-Auszüge, bevor Abschneide- + Metadaten und Fortsetzungshinweis hinzugefügt werden. +- `memoryGetDefaultLines`: Standard-Line-Fenster für `memory_get`, wenn `lines` + weggelassen wird. +- `toolResultMaxChars`: Live-Obergrenze für Tool-Ergebnisse, die für persistierte Ergebnisse und + Overflow-Wiederherstellung verwendet wird. +- `postCompactionMaxChars`: Obergrenze für AGENTS.md-Auszüge, die während der Aktualisierungseinfügung nach Compaction verwendet wird. + +#### `agents.list[].contextLimits` + +Überschreibung pro Agent für die gemeinsamen `contextLimits`-Schalter. Weggelassene Felder übernehmen +Werte aus `agents.defaults.contextLimits`. + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + toolResultMaxChars: 16000, + }, + }, + list: [ + { + id: "tiny-local", + contextLimits: { + memoryGetMaxChars: 6000, + toolResultMaxChars: 8000, + }, + }, + ], + }, +} +``` + +#### `skills.limits.maxSkillsPromptChars` + +Globale Obergrenze für die kompakte Skills-Liste, die in den System-Prompt eingefügt wird. Dies +beeinflusst nicht das bedarfsweise Lesen von `SKILL.md`-Dateien. + +```json5 +{ + skills: { + limits: { + maxSkillsPromptChars: 18000, + }, + }, +} +``` + +#### `agents.list[].skillsLimits.maxSkillsPromptChars` + +Überschreibung pro Agent für das Skills-Prompt-Budget. + +```json5 +{ + agents: { + list: [ + { + id: "tiny-local", + skillsLimits: { + maxSkillsPromptChars: 6000, + }, + }, + ], + }, +} +``` + ### `agents.defaults.imageMaxDimensionPx` -Maximale Pixelgröße der längsten Bildseite in Bildblöcken von Transcript/Werkzeugen vor Anbieteraufrufen. +Maximale Pixelgröße für die längste Bildseite in Transkript-/Tool-Bildblöcken vor Provider-Aufrufen. Standard: `1200`. -Niedrigere Werte reduzieren in der Regel die Nutzung von Vision-Tokens und die Größe des Request-Payloads bei screenshotlastigen Läufen. -Höhere Werte bewahren mehr visuelle Details. +Niedrigere Werte reduzieren in der Regel die Nutzung von Vision-Tokens und die Größe der Request-Payload bei screenshotlastigen Läufen. +Höhere Werte erhalten mehr visuelle Details. ```json5 { @@ -1000,7 +1147,7 @@ Höhere Werte bewahren mehr visuelle Details. ### `agents.defaults.userTimezone` -Zeitzone für den Kontext des System-Prompts (nicht für Nachrichten-Zeitstempel). Fällt auf die Host-Zeitzone zurück. +Zeitzone für den Kontext des System-Prompts (nicht für Nachrichten-Zeitstempel). Fällt auf die Zeitzone des Hosts zurück. ```json5 { @@ -1048,7 +1195,7 @@ Zeitformat im System-Prompt. Standard: `auto` (OS-Präferenz). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // globaler Standard für Anbieterparameter + params: { cacheRetention: "long" }, // globale Standard-Provider-Parameter embeddedHarness: { runtime: "auto", // auto | pi | registrierte Harness-ID, z. B. codex fallback: "pi", // pi | none @@ -1071,44 +1218,45 @@ Zeitformat im System-Prompt. Standard: `auto` (OS-Präferenz). - Die String-Form setzt nur das primäre Modell. - Die Objekt-Form setzt das primäre Modell plus geordnete Failover-Modelle. - `imageModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird vom `image`-Werkzeugpfad als Vision-Modellkonfiguration verwendet. - - Wird außerdem als Fallback-Routing verwendet, wenn das ausgewählte/Standardmodell keine Bildeingaben akzeptieren kann. + - Wird vom `image`-Tool-Pfad als Vision-Modellkonfiguration verwendet. + - Wird auch als Fallback-Routing verwendet, wenn das ausgewählte/Standardmodell keine Bildeingabe akzeptieren kann. - `imageGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird von der gemeinsamen Fähigkeit zur Bildgenerierung und jeder zukünftigen Werkzeug-/Plugin-Oberfläche verwendet, die Bilder generiert. + - Wird von der gemeinsamen Bildgenerierungsfunktion und jeder zukünftigen Tool-/Plugin-Oberfläche verwendet, die Bilder generiert. - Typische Werte: `google/gemini-3.1-flash-image-preview` für native Gemini-Bildgenerierung, `fal/fal-ai/flux/dev` für fal oder `openai/gpt-image-1` für OpenAI Images. - - Wenn Sie direkt einen Anbieter/ein Modell auswählen, konfigurieren Sie auch die passende Anbieter-Authentifizierung bzw. den API-Schlüssel dazu (zum Beispiel `GEMINI_API_KEY` oder `GOOGLE_API_KEY` für `google/*`, `OPENAI_API_KEY` für `openai/*`, `FAL_KEY` für `fal/*`). - - Wenn nicht gesetzt, kann `image_generate` trotzdem einen authentifizierungsbasierten Anbieterstandard ableiten. Es versucht zuerst den aktuellen Standardanbieter und dann die übrigen registrierten Anbieter für Bildgenerierung in der Reihenfolge der Anbieter-IDs. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel dazu (zum Beispiel `GEMINI_API_KEY` oder `GOOGLE_API_KEY` für `google/*`, `OPENAI_API_KEY` für `openai/*`, `FAL_KEY` für `fal/*`). + - Wenn nicht gesetzt, kann `image_generate` dennoch einen authentifizierungsbasierten Standard-Provider ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die übrigen registrierten Bildgenerierungs-Provider in der Reihenfolge der Provider-IDs. - `musicGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird von der gemeinsamen Fähigkeit zur Musikgenerierung und dem integrierten Werkzeug `music_generate` verwendet. + - Wird von der gemeinsamen Musikgenerierungsfunktion und vom integrierten Tool `music_generate` verwendet. - Typische Werte: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` oder `minimax/music-2.5+`. - - Wenn nicht gesetzt, kann `music_generate` trotzdem einen authentifizierungsbasierten Anbieterstandard ableiten. Es versucht zuerst den aktuellen Standardanbieter und dann die übrigen registrierten Anbieter für Musikgenerierung in der Reihenfolge der Anbieter-IDs. - - Wenn Sie direkt einen Anbieter/ein Modell auswählen, konfigurieren Sie auch die passende Anbieter-Authentifizierung bzw. den API-Schlüssel dazu. + - Wenn nicht gesetzt, kann `music_generate` dennoch einen authentifizierungsbasierten Standard-Provider ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die übrigen registrierten Musikgenerierungs-Provider in der Reihenfolge der Provider-IDs. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel dazu. - `videoGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird von der gemeinsamen Fähigkeit zur Videogenerierung und dem integrierten Werkzeug `video_generate` verwendet. + - Wird von der gemeinsamen Videogenerierungsfunktion und vom integrierten Tool `video_generate` verwendet. - Typische Werte: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` oder `qwen/wan2.7-r2v`. - - Wenn nicht gesetzt, kann `video_generate` trotzdem einen authentifizierungsbasierten Anbieterstandard ableiten. Es versucht zuerst den aktuellen Standardanbieter und dann die übrigen registrierten Anbieter für Videogenerierung in der Reihenfolge der Anbieter-IDs. - - Wenn Sie direkt einen Anbieter/ein Modell auswählen, konfigurieren Sie auch die passende Anbieter-Authentifizierung bzw. den API-Schlüssel dazu. - - Der gebündelte Qwen-Anbieter für Videogenerierung unterstützt bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer sowie anbieterbezogene Optionen für `size`, `aspectRatio`, `resolution`, `audio` und `watermark`. + - Wenn nicht gesetzt, kann `video_generate` dennoch einen authentifizierungsbasierten Standard-Provider ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die übrigen registrierten Videogenerierungs-Provider in der Reihenfolge der Provider-IDs. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel dazu. + - Der gebündelte Qwen-Provider für Videogenerierung unterstützt bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer sowie Provider-Optionen auf Ebene des Providers für `size`, `aspectRatio`, `resolution`, `audio` und `watermark`. - `pdfModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird vom `pdf`-Werkzeug für das Modell-Routing verwendet. - - Wenn nicht gesetzt, greift das PDF-Werkzeug auf `imageModel` zurück und dann auf das aufgelöste Sitzungs-/Standardmodell. -- `pdfMaxBytesMb`: Standard-PDF-Größenlimit für das `pdf`-Werkzeug, wenn `maxBytesMb` zur Aufrufzeit nicht übergeben wird. -- `pdfMaxPages`: Standardmaximum an Seiten, das im Extraktions-Fallback-Modus des `pdf`-Werkzeugs berücksichtigt wird. + - Wird vom `pdf`-Tool für das Modell-Routing verwendet. + - Wenn nicht gesetzt, fällt das PDF-Tool auf `imageModel` und dann auf das aufgelöste Sitzungs-/Standardmodell zurück. +- `pdfMaxBytesMb`: Standard-PDF-Größenlimit für das `pdf`-Tool, wenn `maxBytesMb` nicht beim Aufruf übergeben wird. +- `pdfMaxPages`: standardmäßige maximale Seitenzahl, die im Extraktions-Fallback-Modus des `pdf`-Tools berücksichtigt wird. - `verboseDefault`: Standard-Verbose-Stufe für Agenten. Werte: `"off"`, `"on"`, `"full"`. Standard: `"off"`. -- `elevatedDefault`: Standardstufe für erweiterte Ausgabe bei Agenten. Werte: `"off"`, `"on"`, `"ask"`, `"full"`. Standard: `"on"`. -- `model.primary`: Format `provider/model` (z. B. `openai/gpt-5.4`). Wenn Sie den Anbieter weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige Übereinstimmung eines konfigurierten Anbieters für genau diese Modell-ID und greift erst dann auf den konfigurierten Standardanbieter zurück (veraltetes Kompatibilitätsverhalten, daher bevorzugen Sie explizit `provider/model`). Wenn dieser Anbieter das konfigurierte Standardmodell nicht mehr bereitstellt, greift OpenClaw auf das erste konfigurierte Anbieter-/Modellpaar zurück, statt einen veralteten entfernten Anbieterstandard anzuzeigen. -- `models`: der konfigurierte Modellkatalog und die Allowlist für `/model`. Jeder Eintrag kann `alias` (Kurzform) und `params` (anbieterspezifisch, zum Beispiel `temperature`, `maxTokens`, `cacheRetention`, `context1m`) enthalten. -- `params`: globale Standardanbieterparameter, die auf alle Modelle angewendet werden. Setzen Sie sie unter `agents.defaults.params` (z. B. `{ cacheRetention: "long" }`). -- Merge-Priorität von `params` (Konfiguration): `agents.defaults.params` (globale Basis) wird durch `agents.defaults.models["provider/model"].params` (pro Modell) überschrieben, anschließend überschreibt `agents.list[].params` (passende Agent-ID) schlüsselweise. Details finden Sie unter [Prompt Caching](/de/reference/prompt-caching). -- `embeddedHarness`: Standardrichtlinie für die Low-Level-Laufzeit eingebetteter Agenten. Verwenden Sie `runtime: "auto"`, damit registrierte Plugin-Harnesses unterstützte Modelle übernehmen können, `runtime: "pi"` zum Erzwingen des integrierten Pi-Harnesses oder eine registrierte Harness-ID wie `runtime: "codex"`. Setzen Sie `fallback: "none"`, um den automatischen Pi-Fallback zu deaktivieren. -- Konfigurationsschreiber, die diese Felder ändern (zum Beispiel `/models set`, `/models set-image` und Befehle zum Hinzufügen/Entfernen von Fallbacks), speichern die kanonische Objektform und erhalten vorhandene Fallback-Listen, wenn möglich. -- `maxConcurrent`: maximale Anzahl paralleler Agent-Läufe über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4. +- `elevatedDefault`: Standardstufe für erhöhte Ausgabe bei Agenten. Werte: `"off"`, `"on"`, `"ask"`, `"full"`. Standard: `"on"`. +- `model.primary`: Format `provider/model` (z. B. `openai/gpt-5.4`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige configured-provider-Übereinstimmung für genau diese Modell-ID und fällt erst danach auf den konfigurierten Standard-Provider zurück (veraltetes Kompatibilitätsverhalten, daher bevorzugt explizit `provider/model`). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr anbietet, fällt OpenClaw auf das erste konfigurierte Provider-/Modellpaar zurück, statt einen veralteten entfernten Provider-Standard anzuzeigen. +- `models`: der konfigurierte Modellkatalog und die Zulassungsliste für `/model`. Jeder Eintrag kann `alias` (Kurzform) und `params` (providerspezifisch, zum Beispiel `temperature`, `maxTokens`, `cacheRetention`, `context1m`) enthalten. +- `params`: globale Standard-Provider-Parameter, die auf alle Modelle angewendet werden. Gesetzt unter `agents.defaults.params` (z. B. `{ cacheRetention: "long" }`). +- Merge-Priorität von `params` (Konfiguration): `agents.defaults.params` (globale Basis) wird durch `agents.defaults.models["provider/model"].params` (pro Modell) überschrieben, dann überschreibt `agents.list[].params` (passende Agent-ID) nach Schlüssel. Details finden Sie unter [Prompt Caching](/de/reference/prompt-caching). +- `embeddedHarness`: Standardrichtlinie für die Low-Level-Laufzeit eingebetteter Agenten. Verwenden Sie `runtime: "auto"`, damit registrierte Plugin-Harnesses unterstützte Modelle übernehmen können, `runtime: "pi"`, um das integrierte PI-Harness zu erzwingen, oder eine registrierte Harness-ID wie `runtime: "codex"`. Setzen Sie `fallback: "none"`, um den automatischen PI-Fallback zu deaktivieren. +- Konfigurationsschreiber, die diese Felder ändern (zum Beispiel `/models set`, `/models set-image` und Befehle zum Hinzufügen/Entfernen von Fallbacks), speichern die kanonische Objektform und erhalten vorhandene Fallback-Listen nach Möglichkeit. +- `maxConcurrent`: maximale Anzahl paralleler Agentenläufe über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` steuert, welcher Low-Level-Executor eingebettete Agent-Turns ausführt. +`embeddedHarness` steuert, welcher Low-Level-Executor eingebettete Agenten-Turns ausführt. Die meisten Deployments sollten den Standard `{ runtime: "auto", fallback: "pi" }` beibehalten. -Verwenden Sie dies, wenn ein vertrauenswürdiges Plugin ein natives Harness bereitstellt, wie etwa das gebündelte Codex-App-Server-Harness. +Verwenden Sie dies, wenn ein vertrauenswürdiges Plugin ein natives Harness bereitstellt, wie etwa das gebündelte +Codex-App-Server-Harness. ```json5 { @@ -1125,33 +1273,33 @@ Verwenden Sie dies, wenn ein vertrauenswürdiges Plugin ein natives Harness bere ``` - `runtime`: `"auto"`, `"pi"` oder eine registrierte Plugin-Harness-ID. Das gebündelte Codex-Plugin registriert `codex`. -- `fallback`: `"pi"` oder `"none"`. `"pi"` behält das integrierte Pi-Harness als Kompatibilitäts-Fallback bei. `"none"` sorgt dafür, dass eine fehlende oder nicht unterstützte Plugin-Harness-Auswahl fehlschlägt, statt stillschweigend Pi zu verwenden. -- Umgebungsvariablen-Überschreibungen: `OPENCLAW_AGENT_RUNTIME=` überschreibt `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` deaktiviert den Pi-Fallback für diesen Prozess. +- `fallback`: `"pi"` oder `"none"`. `"pi"` behält das integrierte PI-Harness als Kompatibilitäts-Fallback bei. `"none"` führt dazu, dass eine fehlende oder nicht unterstützte Auswahl eines Plugin-Harness fehlschlägt, statt stillschweigend PI zu verwenden. +- Umgebungsüberschreibungen: `OPENCLAW_AGENT_RUNTIME=` überschreibt `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` deaktiviert den PI-Fallback für diesen Prozess. - Für reine Codex-Deployments setzen Sie `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` und `embeddedHarness.fallback: "none"`. -- Dies steuert nur das eingebettete Chat-Harness. Mediengenerierung, Vision, PDF, Musik, Video und TTS verwenden weiterhin ihre Anbieter-/Modelleinstellungen. +- Dies steuert nur das eingebettete Chat-Harness. Mediengenerierung, Vision, PDF, Musik, Video und TTS verwenden weiterhin ihre Provider-/Modelleinstellungen. **Integrierte Alias-Kurzformen** (gelten nur, wenn das Modell in `agents.defaults.models` enthalten ist): -| Alias | Modell | -| ------------------- | ------------------------------------- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | +| Alias | Modell | +| ------------------- | -------------------------------------- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.4` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | Ihre konfigurierten Aliase haben immer Vorrang vor den Standardwerten. -Z.AI-GLM-4.x-Modelle aktivieren automatisch den Denkmodus, sofern Sie nicht `--thinking off` setzen oder `agents.defaults.models["zai/"].params.thinking` selbst definieren. -Z.AI-Modelle aktivieren standardmäßig `tool_stream` für Tool-Call-Streaming. Setzen Sie `agents.defaults.models["zai/"].params.tool_stream` auf `false`, um dies zu deaktivieren. +Bei Z.AI-GLM-4.x-Modellen wird Thinking automatisch aktiviert, sofern Sie nicht `--thinking off` setzen oder `agents.defaults.models["zai/"].params.thinking` selbst definieren. +Z.AI-Modelle aktivieren standardmäßig `tool_stream` für Tool-Call-Streaming. Setzen Sie `agents.defaults.models["zai/"].params.tool_stream` auf `false`, um es zu deaktivieren. Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive` Thinking, wenn keine explizite Thinking-Stufe gesetzt ist. ### `agents.defaults.cliBackends` -Optionale CLI-Backends für reine Text-Fallback-Läufe (ohne Tool-Calls). Nützlich als Backup, wenn API-Anbieter ausfallen. +Optionale CLI-Backends für reine Text-Fallback-Läufe (ohne Tool-Calls). Nützlich als Reserve, wenn API-Provider ausfallen. ```json5 { @@ -1179,13 +1327,13 @@ Optionale CLI-Backends für reine Text-Fallback-Läufe (ohne Tool-Calls). Nützl } ``` -- CLI-Backends sind textorientiert; Werkzeuge sind immer deaktiviert. +- CLI-Backends sind textorientiert; Tools sind immer deaktiviert. - Sitzungen werden unterstützt, wenn `sessionArg` gesetzt ist. -- Bild-Durchreichung wird unterstützt, wenn `imageArg` Dateipfade akzeptiert. +- Bilddurchreichung wird unterstützt, wenn `imageArg` Dateipfade akzeptiert. ### `agents.defaults.systemPromptOverride` -Ersetzt den gesamten von OpenClaw zusammengesetzten System-Prompt durch einen festen String. Setzen Sie ihn auf Standardebene (`agents.defaults.systemPromptOverride`) oder pro Agent (`agents.list[].systemPromptOverride`). Werte pro Agent haben Vorrang; ein leerer oder nur aus Leerraum bestehender Wert wird ignoriert. Nützlich für kontrollierte Prompt-Experimente. +Ersetzt den vollständig von OpenClaw zusammengesetzten System-Prompt durch einen festen String. Setzbar auf Standardebene (`agents.defaults.systemPromptOverride`) oder pro Agent (`agents.list[].systemPromptOverride`). Werte pro Agent haben Vorrang; ein leerer oder nur aus Leerraum bestehender Wert wird ignoriert. Nützlich für kontrollierte Prompt-Experimente. ```json5 { @@ -1209,9 +1357,9 @@ Periodische Heartbeat-Läufe. every: "30m", // 0m deaktiviert model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // Standard: true; false lässt den Heartbeat-Abschnitt aus dem System-Prompt weg + includeSystemPromptSection: true, // Standard: true; false lässt den Heartbeat-Abschnitt im System-Prompt weg lightContext: false, // Standard: false; true behält nur HEARTBEAT.md aus den Workspace-Bootstrap-Dateien - isolatedSession: false, // Standard: false; true führt jeden Heartbeat in einer neuen Sitzung aus (ohne Gesprächsverlauf) + isolatedSession: false, // Standard: false; true führt jeden Heartbeat in einer neuen Sitzung aus (kein Gesprächsverlauf) session: "main", to: "+15555550123", directPolicy: "allow", // allow (Standard) | block @@ -1226,15 +1374,15 @@ Periodische Heartbeat-Läufe. } ``` -- `every`: Dauer-String (ms/s/m/h). Standard: `30m` (API-Key-Authentifizierung) oder `1h` (OAuth-Authentifizierung). Setzen Sie `0m`, um dies zu deaktivieren. -- `includeSystemPromptSection`: wenn false, wird der Heartbeat-Abschnitt aus dem System-Prompt weggelassen und die Injektion von `HEARTBEAT.md` in den Bootstrap-Kontext übersprungen. Standard: `true`. -- `suppressToolErrorWarnings`: wenn true, werden Warn-Payloads für Tool-Fehler während Heartbeat-Läufen unterdrückt. -- `timeoutSeconds`: maximal zulässige Zeit in Sekunden für einen Heartbeat-Agent-Turn, bevor er abgebrochen wird. Wenn nicht gesetzt, wird `agents.defaults.timeoutSeconds` verwendet. +- `every`: Dauer-String (ms/s/m/h). Standard: `30m` (API-Key-Authentifizierung) oder `1h` (OAuth-Authentifizierung). Auf `0m` setzen, um zu deaktivieren. +- `includeSystemPromptSection`: wenn false, lässt den Heartbeat-Abschnitt im System-Prompt weg und überspringt das Einfügen von `HEARTBEAT.md` in den Bootstrap-Kontext. Standard: `true`. +- `suppressToolErrorWarnings`: wenn true, unterdrückt Tool-Fehlerwarn-Payloads während Heartbeat-Läufen. +- `timeoutSeconds`: maximal erlaubte Zeit in Sekunden für einen Heartbeat-Agenten-Turn, bevor er abgebrochen wird. Wenn nicht gesetzt, wird `agents.defaults.timeoutSeconds` verwendet. - `directPolicy`: Richtlinie für direkte/DM-Zustellung. `allow` (Standard) erlaubt direkte Zielzustellung. `block` unterdrückt direkte Zielzustellung und gibt `reason=dm-blocked` aus. -- `lightContext`: wenn true, verwenden Heartbeat-Läufe einen leichtgewichtigen Bootstrap-Kontext und behalten nur `HEARTBEAT.md` aus den Workspace-Bootstrap-Dateien. -- `isolatedSession`: wenn true, wird jeder Heartbeat in einer neuen Sitzung ohne vorherigen Gesprächsverlauf ausgeführt. Gleiches Isolationsmuster wie bei Cron `sessionTarget: "isolated"`. Reduziert die Token-Kosten pro Heartbeat von ca. 100K auf ca. 2–5K Tokens. +- `lightContext`: wenn true, verwenden Heartbeat-Läufe einen leichtgewichtigen Bootstrap-Kontext und behalten aus den Workspace-Bootstrap-Dateien nur `HEARTBEAT.md`. +- `isolatedSession`: wenn true, wird jeder Heartbeat in einer frischen Sitzung ohne vorherigen Gesprächsverlauf ausgeführt. Dasselbe Isolationsmuster wie bei Cron `sessionTarget: "isolated"`. Reduziert die Token-Kosten pro Heartbeat von ~100K auf ~2-5K Tokens. - Pro Agent: setzen Sie `agents.list[].heartbeat`. Wenn irgendein Agent `heartbeat` definiert, führen **nur diese Agenten** Heartbeats aus. -- Heartbeats führen vollständige Agent-Turns aus — kürzere Intervalle verbrauchen mehr Tokens. +- Heartbeats führen vollständige Agenten-Turns aus — kürzere Intervalle verbrauchen mehr Tokens. ### `agents.defaults.compaction` @@ -1248,15 +1396,15 @@ Periodische Heartbeat-Läufe. timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // verwendet, wenn identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] deaktiviert die erneute Injektion + identifierInstructions: "Bewahren Sie Deployment-IDs, Ticket-IDs und Host:Port-Paare exakt auf.", // verwendet, wenn identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] deaktiviert erneutes Einfügen model: "openrouter/anthropic/claude-sonnet-4-6", // optionale nur für Compaction geltende Modellüberschreibung - notifyUser: true, // sendet eine kurze Mitteilung, wenn Compaction beginnt (Standard: false) + notifyUser: true, // kurze Mitteilung an den Benutzer senden, wenn Compaction beginnt (Standard: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "Sitzung nähert sich der Compaction. Speichern Sie jetzt dauerhafte Erinnerungen.", + prompt: "Schreiben Sie alle bleibenden Notizen in memory/YYYY-MM-DD.md; antworten Sie mit dem exakten stillen Token NO_REPLY, wenn nichts gespeichert werden muss.", }, }, }, @@ -1264,19 +1412,19 @@ Periodische Heartbeat-Läufe. } ``` -- `mode`: `default` oder `safeguard` (stückweise Zusammenfassung für lange Verläufe). Siehe [Compaction](/de/concepts/compaction). -- `provider`: ID eines registrierten Compaction-Provider-Plugins. Wenn gesetzt, wird `summarize()` des Providers anstelle der integrierten LLM-Zusammenfassung aufgerufen. Fällt bei Fehlern auf die integrierte Variante zurück. Das Setzen eines Providers erzwingt `mode: "safeguard"`. Siehe [Compaction](/de/concepts/compaction). -- `timeoutSeconds`: maximale Anzahl von Sekunden, die für einen einzelnen Compaction-Vorgang erlaubt ist, bevor OpenClaw ihn abbricht. Standard: `900`. -- `identifierPolicy`: `strict` (Standard), `off` oder `custom`. `strict` stellt der Compaction-Zusammenfassung integrierte Hinweise zum Beibehalten opaker Bezeichner voran. -- `identifierInstructions`: optionaler benutzerdefinierter Text zur Beibehaltung von Bezeichnern, der verwendet wird, wenn `identifierPolicy=custom`. -- `postCompactionSections`: optionale Abschnittsnamen (H2/H3) aus `AGENTS.md`, die nach der Compaction erneut injiziert werden. Standard ist `["Session Startup", "Red Lines"]`; setzen Sie `[]`, um die erneute Injektion zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften `Every Session`/`Safety` zusätzlich als Legacy-Fallback akzeptiert. +- `mode`: `default` oder `safeguard` (zusammenfassende Chunk-Verarbeitung für lange Verläufe). Siehe [Compaction](/de/concepts/compaction). +- `provider`: ID eines registrierten Compaction-Provider-Plugins. Wenn gesetzt, wird statt der integrierten LLM-Zusammenfassung `summarize()` des Providers aufgerufen. Bei Fehlern wird auf die integrierte Variante zurückgefallen. Das Setzen eines Providers erzwingt `mode: "safeguard"`. Siehe [Compaction](/de/concepts/compaction). +- `timeoutSeconds`: maximal zulässige Sekunden für eine einzelne Compaction-Operation, bevor OpenClaw sie abbricht. Standard: `900`. +- `identifierPolicy`: `strict` (Standard), `off` oder `custom`. `strict` stellt der Compaction-Zusammenfassung integrierte Hinweise zur Beibehaltung opaker Bezeichner voran. +- `identifierInstructions`: optionaler benutzerdefinierter Text zur Beibehaltung von Bezeichnern, verwendet wenn `identifierPolicy=custom`. +- `postCompactionSections`: optionale AGENTS.md-H2/H3-Abschnittsnamen, die nach der Compaction erneut eingefügt werden. Standard ist `["Session Startup", "Red Lines"]`; setzen Sie `[]`, um das erneute Einfügen zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften `Every Session`/`Safety` ebenfalls als Legacy-Fallback akzeptiert. - `model`: optionale Überschreibung `provider/model-id` nur für die Compaction-Zusammenfassung. Verwenden Sie dies, wenn die Hauptsitzung ein Modell beibehalten soll, Compaction-Zusammenfassungen aber auf einem anderen Modell laufen sollen; wenn nicht gesetzt, verwendet Compaction das primäre Modell der Sitzung. -- `notifyUser`: wenn `true`, sendet beim Start der Compaction eine kurze Mitteilung an den Benutzer (zum Beispiel „Compacting context...“). Standardmäßig deaktiviert, damit Compaction still bleibt. +- `notifyUser`: wenn `true`, sendet beim Beginn der Compaction eine kurze Mitteilung an den Benutzer (zum Beispiel „Kontext wird kompaktiert...“). Standardmäßig deaktiviert, damit Compaction still bleibt. - `memoryFlush`: stiller agentischer Turn vor automatischer Compaction, um dauerhafte Erinnerungen zu speichern. Wird übersprungen, wenn der Workspace schreibgeschützt ist. ### `agents.defaults.contextPruning` -Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor er an das LLM gesendet wird. Ändert **nicht** den Sitzungsverlauf auf der Festplatte. +Beschneidet **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor er an das LLM gesendet wird. Ändert **nicht** den Sitzungsverlauf auf der Festplatte. ```json5 { @@ -1290,7 +1438,7 @@ Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor er an das LLM hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Inhalt alter Tool-Ergebnisse gelöscht]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1298,11 +1446,11 @@ Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor er an das LLM } ``` - + -- `mode: "cache-ttl"` aktiviert Pruning-Durchläufe. -- `ttl` steuert, wie oft Pruning erneut ausgeführt werden kann (nach dem letzten Cache-Touch). -- Pruning kürzt zuerst übergroße Tool-Ergebnisse weich und löscht bei Bedarf danach ältere Tool-Ergebnisse hart. +- `mode: "cache-ttl"` aktiviert Beschneidungsdurchläufe. +- `ttl` steuert, wie oft die Beschneidung erneut laufen darf (nach dem letzten Cache-Touch). +- Die Beschneidung kürzt zuerst übergroße Tool-Ergebnisse weich und löscht bei Bedarf danach ältere Tool-Ergebnisse hart. **Soft-Trim** behält Anfang + Ende bei und fügt in der Mitte `...` ein. @@ -1311,12 +1459,12 @@ Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor er an das LLM Hinweise: - Bildblöcke werden niemals gekürzt/gelöscht. -- Verhältnisse basieren auf Zeichen (ungefähr), nicht auf exakten Token-Anzahlen. -- Wenn weniger als `keepLastAssistants` Assistant-Nachrichten vorhanden sind, wird Pruning übersprungen. +- Verhältnisse basieren auf Zeichen (annähernd), nicht auf exakten Token-Anzahlen. +- Wenn weniger als `keepLastAssistants` Assistant-Nachrichten vorhanden sind, wird die Beschneidung übersprungen. -Siehe [Session Pruning](/de/concepts/session-pruning) für Details zum Verhalten. +Details zum Verhalten finden Sie unter [Session Pruning](/de/concepts/session-pruning). ### Block-Streaming @@ -1334,11 +1482,11 @@ Siehe [Session Pruning](/de/concepts/session-pruning) für Details zum Verhalten } ``` -- Nicht-Telegram-Kanäle erfordern explizit `*.blockStreaming: true`, um Block-Antworten zu aktivieren. +- Nicht-Telegram-Kanäle erfordern explizit `*.blockStreaming: true`, um Blockantworten zu aktivieren. - Kanalüberschreibungen: `channels..blockStreamingCoalesce` (und Varianten pro Konto). Signal/Slack/Discord/Google Chat verwenden standardmäßig `minChars: 1500`. -- `humanDelay`: zufällige Pause zwischen Block-Antworten. `natural` = 800–2500 ms. Überschreibung pro Agent: `agents.list[].humanDelay`. +- `humanDelay`: zufällige Pause zwischen Blockantworten. `natural` = 800–2500 ms. Überschreibung pro Agent: `agents.list[].humanDelay`. -Siehe [Streaming](/de/concepts/streaming) für Verhalten und Details zur Aufteilung. +Details zu Verhalten + Chunking finden Sie unter [Streaming](/de/concepts/streaming). ### Tippindikatoren @@ -1362,7 +1510,7 @@ Siehe [Typing Indicators](/de/concepts/typing-indicators). ### `agents.defaults.sandbox` -Optionale Sandbox-Ausführung für den eingebetteten Agenten. Den vollständigen Leitfaden finden Sie unter [Sandboxing](/de/gateway/sandboxing). +Optionale Sandboxing für den eingebetteten Agenten. Die vollständige Anleitung finden Sie unter [Sandboxing](/de/gateway/sandboxing). ```json5 { @@ -1470,39 +1618,39 @@ Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstell **SSH-Backend-Konfiguration:** -- `target`: SSH-Ziel im Format `user@host[:port]` +- `target`: SSH-Ziel in der Form `user@host[:port]` - `command`: SSH-Client-Befehl (Standard: `ssh`) -- `workspaceRoot`: absolutes Remote-Root, das für Workspaces pro Scope verwendet wird +- `workspaceRoot`: absoluter Remote-Root, der für Workspaces pro Scope verwendet wird - `identityFile` / `certificateFile` / `knownHostsFile`: vorhandene lokale Dateien, die an OpenSSH übergeben werden - `identityData` / `certificateData` / `knownHostsData`: Inline-Inhalte oder SecretRefs, die OpenClaw zur Laufzeit in temporäre Dateien materialisiert - `strictHostKeyChecking` / `updateHostKeys`: OpenSSH-Schalter für die Host-Key-Richtlinie -**SSH-Authentifizierungspriorität:** +**Priorität der SSH-Authentifizierung:** - `identityData` hat Vorrang vor `identityFile` - `certificateData` hat Vorrang vor `certificateFile` - `knownHostsData` hat Vorrang vor `knownHostsFile` -- SecretRef-gestützte `*Data`-Werte werden aus dem aktiven Secrets-Laufzeit-Snapshot aufgelöst, bevor die Sandbox-Sitzung startet +- SecretRef-gestützte `*Data`-Werte werden aus dem aktiven Laufzeit-Snapshot der Secrets aufgelöst, bevor die Sandbox-Sitzung startet **Verhalten des SSH-Backends:** - initialisiert den Remote-Workspace einmal nach Erstellung oder Neuerstellung - behält danach den Remote-SSH-Workspace als kanonisch bei -- leitet `exec`, Dateitools und Medienpfade über SSH -- synchronisiert Remote-Änderungen nicht automatisch zurück zum Host +- leitet `exec`, Datei-Tools und Medienpfade über SSH +- synchronisiert Remote-Änderungen nicht automatisch zurück auf den Host - unterstützt keine Sandbox-Browser-Container **Workspace-Zugriff:** - `none`: Workspace pro Scope unter `~/.openclaw/sandboxes` -- `ro`: Sandbox-Workspace unter `/workspace`, Agent-Workspace schreibgeschützt unter `/agent` eingehängt -- `rw`: Agent-Workspace unter `/workspace` mit Lese-/Schreibzugriff eingehängt +- `ro`: Sandbox-Workspace unter `/workspace`, Agenten-Workspace schreibgeschützt unter `/agent` eingehängt +- `rw`: Agenten-Workspace unter `/workspace` mit Lese-/Schreibzugriff eingehängt **Scope:** - `session`: Container + Workspace pro Sitzung - `agent`: ein Container + Workspace pro Agent (Standard) -- `shared`: gemeinsamer Container und gemeinsamer Workspace (keine sitzungsübergreifende Isolation) +- `shared`: geteilter Container und Workspace (keine sitzungsübergreifende Isolation) **OpenShell-Plugin-Konfiguration:** @@ -1532,13 +1680,13 @@ Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstell **OpenShell-Modus:** -- `mirror`: initialisiert Remote vor `exec` aus lokal, synchronisiert nach `exec` zurück; der lokale Workspace bleibt kanonisch -- `remote`: initialisiert Remote einmal bei der Erstellung der Sandbox, danach bleibt der Remote-Workspace kanonisch +- `mirror`: initialisiert Remote vor `exec` aus lokalem Stand, synchronisiert nach `exec` zurück; der lokale Workspace bleibt kanonisch +- `remote`: initialisiert Remote einmal, wenn die Sandbox erstellt wird, und behält dann den Remote-Workspace als kanonisch bei -Im Modus `remote` werden Host-lokale Bearbeitungen, die außerhalb von OpenClaw vorgenommen werden, nach dem Initialisierungsschritt nicht automatisch in die Sandbox synchronisiert. -Der Transport erfolgt per SSH in die OpenShell-Sandbox, aber das Plugin verwaltet den Sandbox-Lebenszyklus und die optionale Mirror-Synchronisierung. +Im Modus `remote` werden hostlokale Änderungen, die außerhalb von OpenClaw vorgenommen wurden, nach dem Initialisierungsschritt nicht automatisch in die Sandbox synchronisiert. +Der Transport erfolgt per SSH in die OpenShell-Sandbox, aber das Plugin besitzt den Lebenszyklus der Sandbox und optional die Spiegel-Synchronisierung. -**`setupCommand`** wird einmal nach der Erstellung des Containers ausgeführt (über `sh -lc`). Benötigt ausgehenden Netzwerkzugriff, beschreibbares Root-Dateisystem und Root-Benutzer. +**`setupCommand`** wird einmal nach der Container-Erstellung ausgeführt (über `sh -lc`). Benötigt Netzwerk-Egress, beschreibbares Root-Dateisystem und Root-Benutzer. **Container verwenden standardmäßig `network: "none"`** — setzen Sie es auf `"bridge"` (oder ein benutzerdefiniertes Bridge-Netzwerk), wenn der Agent ausgehenden Zugriff benötigt. `"host"` ist blockiert. `"container:"` ist standardmäßig blockiert, außer Sie setzen explizit @@ -1546,18 +1694,18 @@ Der Transport erfolgt per SSH in die OpenShell-Sandbox, aber das Plugin verwalte **Eingehende Anhänge** werden in `media/inbound/*` im aktiven Workspace bereitgestellt. -**`docker.binds`** bindet zusätzliche Host-Verzeichnisse ein; globale und agentbezogene Bindings werden zusammengeführt. +**`docker.binds`** bindet zusätzliche Host-Verzeichnisse ein; globale und agentbezogene Binds werden zusammengeführt. -**Sandbox-Browser** (`sandbox.browser.enabled`): Chromium + CDP in einem Container. Die noVNC-URL wird in den System-Prompt injiziert. Erfordert kein `browser.enabled` in `openclaw.json`. -noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung, und OpenClaw gibt eine URL mit kurzlebigem Token aus (anstatt das Passwort in der geteilten URL offenzulegen). +**Sandbox-Browser** (`sandbox.browser.enabled`): Chromium + CDP in einem Container. Die noVNC-URL wird in den System-Prompt eingefügt. Erfordert nicht `browser.enabled` in `openclaw.json`. +Der noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung, und OpenClaw gibt eine URL mit kurzlebigem Token aus (statt das Passwort in der gemeinsam genutzten URL offenzulegen). -- `allowHostControl: false` (Standard) blockiert, dass Sandbox-Sitzungen auf den Browser des Hosts zielen. -- `network` ist standardmäßig `openclaw-sandbox-browser` (dediziertes Bridge-Netzwerk). Setzen Sie es nur dann auf `bridge`, wenn Sie ausdrücklich globale Bridge-Konnektivität wünschen. -- `cdpSourceRange` beschränkt optional eingehenden CDP-Zugriff am Container-Rand auf einen CIDR-Bereich (zum Beispiel `172.21.0.1/32`). +- `allowHostControl: false` (Standard) blockiert, dass Sandbox-Sitzungen den Host-Browser ansteuern. +- `network` hat standardmäßig den Wert `openclaw-sandbox-browser` (dediziertes Bridge-Netzwerk). Setzen Sie es nur dann auf `bridge`, wenn Sie ausdrücklich globale Bridge-Konnektivität möchten. +- `cdpSourceRange` beschränkt optional den CDP-Eingang am Container-Rand auf einen CIDR-Bereich (zum Beispiel `172.21.0.1/32`). - `sandbox.browser.binds` bindet zusätzliche Host-Verzeichnisse nur in den Sandbox-Browser-Container ein. Wenn gesetzt (einschließlich `[]`), ersetzt es `docker.binds` für den Browser-Container. -- Start-Standards sind in `scripts/sandbox-browser-entrypoint.sh` definiert und auf Container-Hosts abgestimmt: +- Start-Standardwerte sind in `scripts/sandbox-browser-entrypoint.sh` definiert und für Container-Hosts abgestimmt: - `--remote-debugging-address=127.0.0.1` - - `--remote-debugging-port=` + - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` @@ -1573,11 +1721,17 @@ noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung, und Ope - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions` (standardmäßig aktiviert) - - `--disable-3d-apis`, `--disable-software-rasterizer` und `--disable-gpu` sind standardmäßig aktiviert und können mit `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` deaktiviert werden, wenn WebGL-/3D-Nutzung dies erfordert. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` aktiviert Erweiterungen erneut, wenn Ihr Workflow davon abhängt. - - `--renderer-process-limit=2` kann mit `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` geändert werden; setzen Sie `0`, um das Standard-Prozesslimit von Chromium zu verwenden. - - zusätzlich `--no-sandbox` und `--disable-setuid-sandbox`, wenn `noSandbox` aktiviert ist. - - Diese Standardwerte sind die Basis des Container-Images; verwenden Sie ein benutzerdefiniertes Browser-Image mit eigenem Entrypoint, um die Container-Standards zu ändern. + - `--disable-3d-apis`, `--disable-software-rasterizer` und `--disable-gpu` sind + standardmäßig aktiviert und können mit + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` deaktiviert werden, wenn WebGL-/3D-Nutzung dies erfordert. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` aktiviert Erweiterungen wieder, wenn Ihr Workflow + davon abhängt. + - `--renderer-process-limit=2` kann mit + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` geändert werden; setzen Sie `0`, um den + Standardprozessgrenzwert von Chromium zu verwenden. + - plus `--no-sandbox` und `--disable-setuid-sandbox`, wenn `noSandbox` aktiviert ist. + - Die Standardwerte sind die Basis des Container-Images; verwenden Sie ein benutzerdefiniertes Browser-Image mit einem benutzerdefinierten + Entrypoint, um die Container-Standardwerte zu ändern. @@ -1603,11 +1757,11 @@ scripts/sandbox-browser-setup.sh # optionales Browser-Image workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // oder { primary, fallbacks } - thinkingDefault: "high", // Überschreibung der Standard-Thinking-Stufe pro Agent - reasoningDefault: "on", // Überschreibung der Standard-Sichtbarkeit von Reasoning pro Agent - fastModeDefault: false, // Überschreibung des Standard-Fast-Mode pro Agent + thinkingDefault: "high", // Überschreibung der Thinking-Stufe pro Agent + reasoningDefault: "on", // Überschreibung der Sichtbarkeit von Reasoning pro Agent + fastModeDefault: false, // Überschreibung des Fast-Modus pro Agent embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // überschreibt passende defaults.models-Parameter schlüsselweise + params: { cacheRetention: "none" }, // überschreibt passende defaults.models-Parameter nach Schlüssel skills: ["docs-search"], // ersetzt agents.defaults.skills, wenn gesetzt identity: { name: "Samantha", @@ -1639,27 +1793,27 @@ scripts/sandbox-browser-setup.sh # optionales Browser-Image } ``` -- `id`: stabile Agent-ID (erforderlich). -- `default`: wenn mehrere gesetzt sind, gewinnt der erste (es wird eine Warnung protokolliert). Wenn keiner gesetzt ist, ist der erste Listeneintrag der Standard. -- `model`: Die String-Form überschreibt nur `primary`; die Objektform `{ primary, fallbacks }` überschreibt beide (`[]` deaktiviert globale Fallbacks). Cron-Jobs, die nur `primary` überschreiben, erben weiterhin Standard-Fallbacks, sofern Sie nicht `fallbacks: []` setzen. -- `params`: Stream-Parameter pro Agent, zusammengeführt über dem ausgewählten Modelleintrag in `agents.defaults.models`. Verwenden Sie dies für agentenspezifische Überschreibungen wie `cacheRetention`, `temperature` oder `maxTokens`, ohne den gesamten Modellkatalog zu duplizieren. -- `skills`: optionale Skill-Allowlist pro Agent. Wenn weggelassen, erbt der Agent `agents.defaults.skills`, falls gesetzt; eine explizite Liste ersetzt Standards statt sie zusammenzuführen, und `[]` bedeutet keine Skills. +- `id`: stabile Agenten-ID (erforderlich). +- `default`: wenn mehrere gesetzt sind, gewinnt der erste (Warnung wird protokolliert). Wenn keiner gesetzt ist, ist der erste Listeneintrag der Standard. +- `model`: Die String-Form überschreibt nur `primary`; die Objektform `{ primary, fallbacks }` überschreibt beide (`[]` deaktiviert globale Fallbacks). Cron-Jobs, die nur `primary` überschreiben, übernehmen weiterhin Standard-Fallbacks, sofern Sie nicht `fallbacks: []` setzen. +- `params`: Stream-Parameter pro Agent, die über den ausgewählten Modelleintrag in `agents.defaults.models` zusammengeführt werden. Verwenden Sie dies für agentenspezifische Überschreibungen wie `cacheRetention`, `temperature` oder `maxTokens`, ohne den gesamten Modellkatalog zu duplizieren. +- `skills`: optionale Skills-Zulassungsliste pro Agent. Wenn weggelassen, übernimmt der Agent `agents.defaults.skills`, falls gesetzt; eine explizite Liste ersetzt die Standardwerte statt sie zusammenzuführen, und `[]` bedeutet keine Skills. - `thinkingDefault`: optionale Standard-Thinking-Stufe pro Agent (`off | minimal | low | medium | high | xhigh | adaptive`). Überschreibt `agents.defaults.thinkingDefault` für diesen Agenten, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist. -- `reasoningDefault`: optionale Standardsichtbarkeit von Reasoning pro Agent (`on | off | stream`). Gilt, wenn keine Reasoning-Überschreibung pro Nachricht oder Sitzung gesetzt ist. -- `fastModeDefault`: optionale Standardeinstellung pro Agent für den Fast Mode (`true | false`). Gilt, wenn keine Fast-Mode-Überschreibung pro Nachricht oder Sitzung gesetzt ist. -- `embeddedHarness`: optionale Überschreibung der Low-Level-Harness-Richtlinie pro Agent. Verwenden Sie `{ runtime: "codex", fallback: "none" }`, um einen Agenten auf Codex-only festzulegen, während andere Agenten den Standard-Pi-Fallback beibehalten. -- `runtime`: optionaler Runtime-Deskriptor pro Agent. Verwenden Sie `type: "acp"` mit `runtime.acp`-Standards (`agent`, `backend`, `mode`, `cwd`), wenn der Agent standardmäßig ACP-Harness-Sitzungen verwenden soll. -- `identity.avatar`: workspace-relativer Pfad, `http(s)`-URL oder `data:`-URI. +- `reasoningDefault`: optionale Standardvorgabe pro Agent für die Sichtbarkeit von Reasoning (`on | off | stream`). Gilt, wenn keine Überschreibung für Reasoning pro Nachricht oder Sitzung gesetzt ist. +- `fastModeDefault`: optionale Standardvorgabe pro Agent für den Fast-Modus (`true | false`). Gilt, wenn keine Überschreibung des Fast-Modus pro Nachricht oder Sitzung gesetzt ist. +- `embeddedHarness`: optionale Überschreibung der Low-Level-Harness-Richtlinie pro Agent. Verwenden Sie `{ runtime: "codex", fallback: "none" }`, um einen Agenten nur mit Codex zu betreiben, während andere Agenten den Standard-PI-Fallback beibehalten. +- `runtime`: optionaler Laufzeit-Deskriptor pro Agent. Verwenden Sie `type: "acp"` mit `runtime.acp`-Standardwerten (`agent`, `backend`, `mode`, `cwd`), wenn der Agent standardmäßig ACP-Harness-Sitzungen verwenden soll. +- `identity.avatar`: pfad relativ zum Workspace, `http(s)`-URL oder `data:`-URI. - `identity` leitet Standardwerte ab: `ackReaction` aus `emoji`, `mentionPatterns` aus `name`/`emoji`. -- `subagents.allowAgents`: Allowlist von Agent-IDs für `sessions_spawn` (`["*"]` = beliebig; Standard: nur derselbe Agent). -- Sandbox-Vererbungsschutz: Wenn die anfragende Sitzung in einer Sandbox läuft, lehnt `sessions_spawn` Ziele ab, die unsandboxed ausgeführt würden. +- `subagents.allowAgents`: Zulassungsliste von Agenten-IDs für `sessions_spawn` (`["*"]` = beliebig; Standard: nur derselbe Agent). +- Vererbungs-Schutz für Sandbox: Wenn die anfordernde Sitzung in einer Sandbox läuft, lehnt `sessions_spawn` Ziele ab, die unsandboxed laufen würden. - `subagents.requireAgentId`: wenn true, blockiert `sessions_spawn`-Aufrufe ohne `agentId` (erzwingt explizite Profilauswahl; Standard: false). --- ## Multi-Agent-Routing -Führen Sie mehrere isolierte Agenten innerhalb eines Gateway aus. Siehe [Multi-Agent](/de/concepts/multi-agent). +Führen Sie mehrere isolierte Agenten innerhalb eines Gateways aus. Siehe [Multi-Agent](/de/concepts/multi-agent). ```json5 { @@ -1678,9 +1832,9 @@ Führen Sie mehrere isolierte Agenten innerhalb eines Gateway aus. Siehe [Multi- ### Felder für Binding-Matches -- `type` (optional): `route` für normales Routing (fehlender Typ bedeutet standardmäßig `route`), `acp` für persistente ACP-Konversationsbindungen. +- `type` (optional): `route` für normales Routing (fehlender Typ verwendet standardmäßig route), `acp` für persistente ACP-Unterhaltungs-Bindungen. - `match.channel` (erforderlich) -- `match.accountId` (optional; `*` = beliebiges Konto; weggelassen = Standardkonto) +- `match.accountId` (optional; `*` = jedes Konto; weggelassen = Standardkonto) - `match.peer` (optional; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (optional; kanalspezifisch) - `acp` (optional; nur für `type: "acp"`): `{ mode, label, cwd, backend }` @@ -1690,17 +1844,17 @@ Führen Sie mehrere isolierte Agenten innerhalb eines Gateway aus. Siehe [Multi- 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (exakt, ohne peer/guild/team) +4. `match.accountId` (exakt, ohne Peer/Guild/Team) 5. `match.accountId: "*"` (kanalweit) 6. Standard-Agent -Innerhalb jeder Ebene gewinnt der erste passende Eintrag in `bindings`. +Innerhalb jeder Stufe gewinnt der erste passende `bindings`-Eintrag. -Bei Einträgen vom Typ `type: "acp"` löst OpenClaw anhand der exakten Konversationsidentität auf (`match.channel` + Konto + `match.peer.id`) und verwendet nicht die obige Reihenfolge der Route-Binding-Ebenen. +Bei Einträgen mit `type: "acp"` löst OpenClaw nach exakter Unterhaltungsidentität auf (`match.channel` + Konto + `match.peer.id`) und verwendet nicht die obige Stufenreihenfolge der Route-Bindings. ### Zugriffsprofile pro Agent - + ```json5 { @@ -1718,7 +1872,7 @@ Bei Einträgen vom Typ `type: "acp"` löst OpenClaw anhand der exakten Konversat - + ```json5 { @@ -1827,14 +1981,14 @@ Details zur Priorität finden Sie unter [Multi-Agent Sandbox & Tools](/de/tools/ rotateBytes: "10mb", resetArchiveRetention: "30d", // Dauer oder false maxDiskBytes: "500mb", // optionales hartes Budget - highWaterBytes: "400mb", // optionales Ziel für Bereinigung + highWaterBytes: "400mb", // optionales Bereinigungsziel }, threadBindings: { enabled: true, - idleHours: 24, // Standard für automatisches Entfokussieren bei Inaktivität in Stunden (`0` deaktiviert) + idleHours: 24, // Standard für automatisches Entfokussieren nach Inaktivität in Stunden (`0` deaktiviert) maxAgeHours: 0, // Standard für hartes Maximalalter in Stunden (`0` deaktiviert) }, - mainKey: "main", // Legacy (die Runtime verwendet immer "main") + mainKey: "main", // Legacy (Laufzeit verwendet immer "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1846,35 +2000,35 @@ Details zur Priorität finden Sie unter [Multi-Agent Sandbox & Tools](/de/tools/ -- **`scope`**: grundlegende Strategie zur Sitzungsgruppierung für Gruppenchats. - - `per-sender` (Standard): Jeder Absender erhält eine isolierte Sitzung innerhalb eines Kanal-Kontexts. - - `global`: Alle Teilnehmer in einem Kanal-Kontext teilen sich eine einzige Sitzung (nur verwenden, wenn gemeinsamer Kontext beabsichtigt ist). +- **`scope`**: grundlegende Gruppierungsstrategie für Sitzungen in Gruppenchats. + - `per-sender` (Standard): Jeder Absender erhält innerhalb eines Kanalkontexts eine isolierte Sitzung. + - `global`: Alle Teilnehmer in einem Kanalkontext teilen sich eine einzige Sitzung (nur verwenden, wenn geteilter Kontext beabsichtigt ist). - **`dmScope`**: wie DMs gruppiert werden. - `main`: Alle DMs teilen sich die Hauptsitzung. - - `per-peer`: Isolation nach Absender-ID kanalübergreifend. - - `per-channel-peer`: Isolation pro Kanal + Absender (empfohlen für Multi-User-Inboxes). - - `per-account-channel-peer`: Isolation pro Konto + Kanal + Absender (empfohlen für Multi-Account). -- **`identityLinks`**: ordnet kanonische IDs an anbieterpräfixierte Peers zu, um sitzungsübergreifendes Teilen zwischen Kanälen zu ermöglichen. -- **`reset`**: primäre Reset-Richtlinie. `daily` setzt bei `atHour` in lokaler Zeit zurück; `idle` setzt nach `idleMinutes` zurück. Wenn beides konfiguriert ist, gilt jeweils das zuerst ablaufende. + - `per-peer`: Isolierung nach Absender-ID kanalübergreifend. + - `per-channel-peer`: Isolierung pro Kanal + Absender (empfohlen für Multi-User-Posteingänge). + - `per-account-channel-peer`: Isolierung pro Konto + Kanal + Absender (empfohlen für Multi-Account). +- **`identityLinks`**: ordnet kanonische IDs providerpräfigierten Peers zu, um kanalübergreifendes Teilen von Sitzungen zu ermöglichen. +- **`reset`**: primäre Reset-Richtlinie. `daily` setzt um `atHour` lokaler Zeit zurück; `idle` setzt nach `idleMinutes` zurück. Wenn beide konfiguriert sind, gilt der zuerst ablaufende Wert. - **`resetByType`**: Überschreibungen pro Typ (`direct`, `group`, `thread`). Legacy-`dm` wird als Alias für `direct` akzeptiert. -- **`parentForkMaxTokens`**: maximal erlaubte `totalTokens` der übergeordneten Sitzung beim Erstellen einer geforkten Thread-Sitzung (Standard `100000`). - - Wenn die `totalTokens` der übergeordneten Sitzung über diesem Wert liegen, startet OpenClaw eine neue Thread-Sitzung, statt den Verlauf des übergeordneten Transkripts zu erben. - - Setzen Sie `0`, um diesen Schutz zu deaktivieren und Parent-Forking immer zu erlauben. -- **`mainKey`**: Legacy-Feld. Die Runtime verwendet für den Hauptbucket direkter Chats immer `"main"`. -- **`agentToAgent.maxPingPongTurns`**: maximale Anzahl von Antwort-Turns zwischen Agenten bei Agent-zu-Agent-Austausch (Integer, Bereich: `0`–`5`). `0` deaktiviert Ping-Pong-Verkettung. -- **`sendPolicy`**: Match anhand von `channel`, `chatType` (`direct|group|channel`, mit Legacy-Alias `dm`), `keyPrefix` oder `rawKeyPrefix`. Das erste Deny gewinnt. -- **`maintenance`**: Steuerung für Bereinigung + Aufbewahrung des Sitzungsspeichers. - - `mode`: `warn` gibt nur Warnungen aus; `enforce` wendet die Bereinigung an. +- **`parentForkMaxTokens`**: maximal erlaubte `totalTokens` der Elternsitzung beim Erstellen einer geforkten Thread-Sitzung (Standard `100000`). + - Wenn `totalTokens` der Elternsitzung über diesem Wert liegt, startet OpenClaw eine neue Thread-Sitzung, anstatt den Verlauf der Elternsitzung zu übernehmen. + - Setzen Sie `0`, um diese Schutzfunktion zu deaktivieren und Parent-Forking immer zu erlauben. +- **`mainKey`**: Legacy-Feld. Die Laufzeit verwendet immer `"main"` für den Haupt-Bucket direkter Chats. +- **`agentToAgent.maxPingPongTurns`**: maximale Anzahl von Antwort-Zurück-Turns zwischen Agenten bei Agent-zu-Agent-Austausch (Ganzzahl, Bereich: `0`–`5`). `0` deaktiviert Ping-Pong-Verkettung. +- **`sendPolicy`**: Match nach `channel`, `chatType` (`direct|group|channel`, mit Legacy-Alias `dm`), `keyPrefix` oder `rawKeyPrefix`. Die erste Verweigerung gewinnt. +- **`maintenance`**: Bereinigung + Aufbewahrungssteuerung für den Sitzungsspeicher. + - `mode`: `warn` gibt nur Warnungen aus; `enforce` wendet Bereinigung an. - `pruneAfter`: Altersgrenze für veraltete Einträge (Standard `30d`). - - `maxEntries`: maximale Anzahl von Einträgen in `sessions.json` (Standard `500`). + - `maxEntries`: maximale Anzahl an Einträgen in `sessions.json` (Standard `500`). - `rotateBytes`: rotiert `sessions.json`, wenn diese Größe überschritten wird (Standard `10mb`). - - `resetArchiveRetention`: Aufbewahrung für Transkriptarchive `*.reset.`. Standardmäßig `pruneAfter`; setzen Sie `false`, um dies zu deaktivieren. - - `maxDiskBytes`: optionales Speicherbudget für das Sitzungsverzeichnis. Im Modus `warn` werden Warnungen protokolliert; im Modus `enforce` werden zuerst die ältesten Artefakte/Sitzungen entfernt. - - `highWaterBytes`: optionales Ziel nach der Budgetbereinigung. Standardmäßig `80%` von `maxDiskBytes`. + - `resetArchiveRetention`: Aufbewahrung für `*.reset.`-Transkriptarchive. Standardmäßig `pruneAfter`; setzen Sie `false`, um zu deaktivieren. + - `maxDiskBytes`: optionales Festplattenbudget für das Sitzungsverzeichnis. Im Modus `warn` werden Warnungen protokolliert; im Modus `enforce` werden zuerst die ältesten Artefakte/Sitzungen entfernt. + - `highWaterBytes`: optionales Ziel nach Budgetbereinigung. Standardmäßig `80%` von `maxDiskBytes`. - **`threadBindings`**: globale Standardwerte für an Threads gebundene Sitzungsfunktionen. - - `enabled`: globaler Standardschalter (Anbieter können überschreiben; Discord verwendet `channels.discord.threadBindings.enabled`) - - `idleHours`: Standard für automatisches Entfokussieren bei Inaktivität in Stunden (`0` deaktiviert; Anbieter können überschreiben) - - `maxAgeHours`: Standard für hartes Maximalalter in Stunden (`0` deaktiviert; Anbieter können überschreiben) + - `enabled`: zentraler Standardschalter (Provider können überschreiben; Discord verwendet `channels.discord.threadBindings.enabled`) + - `idleHours`: Standard für automatisches Entfokussieren nach Inaktivität in Stunden (`0` deaktiviert; Provider können überschreiben) + - `maxAgeHours`: Standard für hartes Maximalalter in Stunden (`0` deaktiviert; Provider können überschreiben) @@ -1914,34 +2068,34 @@ Details zur Priorität finden Sie unter [Multi-Agent Sandbox & Tools](/de/tools/ Überschreibungen pro Kanal/Konto: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Auflösung (höchste Spezifität gewinnt): Konto → Kanal → global. `""` deaktiviert und stoppt die Kaskade. `"auto"` leitet `[{identity.name}]` ab. +Auflösung (das Spezifischste gewinnt): Konto → Kanal → global. `""` deaktiviert und stoppt die Kaskade. `"auto"` leitet `[{identity.name}]` ab. **Template-Variablen:** -| Variable | Beschreibung | Beispiel | -| ----------------- | --------------------- | --------------------------- | -| `{model}` | Kurzer Modellname | `claude-opus-4-6` | +| Variable | Beschreibung | Beispiel | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | Kurzer Modellname | `claude-opus-4-6` | | `{modelFull}` | Vollständiger Modellbezeichner | `anthropic/claude-opus-4-6` | -| `{provider}` | Anbietername | `anthropic` | -| `{thinkingLevel}` | Aktuelle Thinking-Stufe | `high`, `low`, `off` | -| `{identity.name}` | Name der Agentenidentität | (wie bei `"auto"`) | +| `{provider}` | Provider-Name | `anthropic` | +| `{thinkingLevel}` | Aktuelle Thinking-Stufe | `high`, `low`, `off` | +| `{identity.name}` | Name der Agentenidentität | (gleich wie `"auto"`) | -Variablen sind nicht case-sensitiv. `{think}` ist ein Alias für `{thinkingLevel}`. +Variablen sind nicht case-sensitive. `{think}` ist ein Alias für `{thinkingLevel}`. ### Bestätigungsreaktion -- Standardmäßig das `identity.emoji` des aktiven Agenten, andernfalls `"👀"`. Setzen Sie `""`, um dies zu deaktivieren. +- Standardmäßig die `identity.emoji` des aktiven Agenten, andernfalls `"👀"`. Setzen Sie `""`, um zu deaktivieren. - Überschreibungen pro Kanal: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Auflösungsreihenfolge: Konto → Kanal → `messages.ackReaction` → Identity-Fallback. -- Geltungsbereich: `group-mentions` (Standard), `group-all`, `direct`, `all`. +- Reihenfolge der Auflösung: Konto → Kanal → `messages.ackReaction` → Identity-Fallback. +- Scope: `group-mentions` (Standard), `group-all`, `direct`, `all`. - `removeAckAfterReply`: entfernt die Bestätigungsreaktion nach der Antwort auf Slack, Discord und Telegram. -- `messages.statusReactions.enabled`: aktiviert Lifecycle-Statusreaktionen auf Slack, Discord und Telegram. - Bei Slack und Discord bleiben Statusreaktionen aktiviert, wenn Bestätigungsreaktionen aktiv sind und der Wert nicht gesetzt ist. - Bei Telegram setzen Sie ihn explizit auf `true`, um Lifecycle-Statusreaktionen zu aktivieren. +- `messages.statusReactions.enabled`: aktiviert Lebenszyklus-Statusreaktionen auf Slack, Discord und Telegram. + Auf Slack und Discord bleiben Statusreaktionen aktiv, wenn der Wert nicht gesetzt ist und Bestätigungsreaktionen aktiv sind. + Auf Telegram setzen Sie ihn explizit auf `true`, um Lebenszyklus-Statusreaktionen zu aktivieren. ### Inbound-Debounce -Bündelt schnelle reine Textnachrichten vom selben Absender zu einem einzelnen Agent-Turn. Medien/Anhänge werden sofort geleert. Steuerbefehle umgehen Debouncing. +Bündelt schnelle reine Textnachrichten desselben Absenders zu einem einzigen Agenten-Turn. Medien/Anhänge flushen sofort. Steuerbefehle umgehen Debouncing. ### TTS (Text-to-Speech) @@ -1984,12 +2138,12 @@ Bündelt schnelle reine Textnachrichten vom selben Absender zu einem einzelnen A } ``` -- `auto` steuert den Standardmodus für Auto-TTS: `off`, `always`, `inbound` oder `tagged`. `/tts on|off` kann lokale Einstellungen überschreiben, und `/tts status` zeigt den effektiven Zustand an. +- `auto` steuert den Standardmodus für automatisches TTS: `off`, `always`, `inbound` oder `tagged`. `/tts on|off` kann lokale Präferenzen überschreiben, und `/tts status` zeigt den effektiven Zustand an. - `summaryModel` überschreibt `agents.defaults.model.primary` für die automatische Zusammenfassung. - `modelOverrides` ist standardmäßig aktiviert; `modelOverrides.allowProvider` ist standardmäßig `false` (Opt-in). -- API-Schlüssel greifen auf `ELEVENLABS_API_KEY`/`XI_API_KEY` und `OPENAI_API_KEY` zurück. +- API-Schlüssel fallen auf `ELEVENLABS_API_KEY`/`XI_API_KEY` und `OPENAI_API_KEY` zurück. - `openai.baseUrl` überschreibt den OpenAI-TTS-Endpunkt. Die Auflösungsreihenfolge ist Konfiguration, dann `OPENAI_TTS_BASE_URL`, dann `https://api.openai.com/v1`. -- Wenn `openai.baseUrl` auf einen Nicht-OpenAI-Endpunkt zeigt, behandelt OpenClaw ihn als OpenAI-kompatiblen TTS-Server und lockert die Validierung von Modell/Stimme. +- Wenn `openai.baseUrl` auf einen Nicht-OpenAI-Endpunkt zeigt, behandelt OpenClaw ihn als OpenAI-kompatiblen TTS-Server und lockert die Modell-/Stimmenvalidierung. --- @@ -2019,13 +2173,13 @@ Standardwerte für den Talk-Modus (macOS/iOS/Android). } ``` -- `talk.provider` muss einem Schlüssel in `talk.providers` entsprechen, wenn mehrere Talk-Anbieter konfiguriert sind. -- Legacy-flache Talk-Schlüssel (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) dienen nur der Kompatibilität und werden automatisch nach `talk.providers.` migriert. -- Für Voice-IDs wird auf `ELEVENLABS_VOICE_ID` oder `SAG_VOICE_ID` zurückgegriffen. +- `talk.provider` muss einem Schlüssel in `talk.providers` entsprechen, wenn mehrere Talk-Provider konfiguriert sind. +- Veraltete flache Talk-Schlüssel (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) dienen nur der Kompatibilität und werden automatisch nach `talk.providers.` migriert. +- Voice-IDs fallen auf `ELEVENLABS_VOICE_ID` oder `SAG_VOICE_ID` zurück. - `providers.*.apiKey` akzeptiert Klartext-Strings oder SecretRef-Objekte. - Der Fallback `ELEVENLABS_API_KEY` gilt nur, wenn kein Talk-API-Schlüssel konfiguriert ist. -- `providers.*.voiceAliases` erlaubt es Talk-Direktiven, benutzerfreundliche Namen zu verwenden. -- `silenceTimeoutMs` steuert, wie lange der Talk-Modus nach Stille des Benutzers wartet, bevor das Transkript gesendet wird. Wenn nicht gesetzt, bleibt das plattformspezifische Standard-Pausenfenster erhalten (`700 ms unter macOS und Android, 900 ms unter iOS`). +- `providers.*.voiceAliases` ermöglicht es Talk-Direktiven, freundliche Namen zu verwenden. +- `silenceTimeoutMs` steuert, wie lange der Talk-Modus nach der Stille des Benutzers wartet, bevor das Transkript gesendet wird. Wenn nicht gesetzt, bleibt das plattformspezifische Standard-Pausenfenster bestehen (`700 ms auf macOS und Android, 900 ms auf iOS`). --- @@ -2033,37 +2187,37 @@ Standardwerte für den Talk-Modus (macOS/iOS/Android). ### Tool-Profile -`tools.profile` legt eine Basis-Allowlist vor `tools.allow`/`tools.deny` fest: +`tools.profile` setzt eine Basis-Zulassungsliste vor `tools.allow`/`tools.deny`: -Lokales Onboarding setzt neue lokale Konfigurationen standardmäßig auf `tools.profile: "coding"`, wenn kein Wert gesetzt ist (bestehende explizite Profile bleiben erhalten). +Lokales Onboarding setzt für neue lokale Konfigurationen standardmäßig `tools.profile: "coding"`, wenn nichts gesetzt ist (bestehende explizite Profile bleiben erhalten). | Profil | Enthält | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | nur `session_status` | +| `minimal` | nur `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Keine Einschränkung (wie nicht gesetzt) | +| `full` | Keine Einschränkung (wie nicht gesetzt) | ### Tool-Gruppen -| Gruppe | Tools | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` wird als Alias für `exec` akzeptiert) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Gruppe | Tools | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` wird als Alias für `exec` akzeptiert) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Alle integrierten Tools (Provider-Plugins ausgeschlossen) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Alle integrierten Tools (ohne Provider-Plugins) | ### `tools.allow` / `tools.deny` -Globale Richtlinie zum Erlauben/Verweigern von Tools (Deny gewinnt). Groß-/Kleinschreibung wird ignoriert, `*`-Wildcards werden unterstützt. Wird auch angewendet, wenn die Docker-Sandbox deaktiviert ist. +Globale Richtlinie zum Erlauben/Verweigern von Tools (Verweigerung gewinnt). Nicht case-sensitive, unterstützt `*`-Wildcards. Wird auch angewendet, wenn die Docker-Sandbox deaktiviert ist. ```json5 { @@ -2073,7 +2227,7 @@ Globale Richtlinie zum Erlauben/Verweigern von Tools (Deny gewinnt). Groß-/Klei ### `tools.byProvider` -Schränkt Tools für bestimmte Anbieter oder Modelle weiter ein. Reihenfolge: Basisprofil → Anbieterprofil → allow/deny. +Schränkt Tools für bestimmte Provider oder Modelle weiter ein. Reihenfolge: Basisprofil → Provider-Profil → allow/deny. ```json5 { @@ -2089,7 +2243,7 @@ Schränkt Tools für bestimmte Anbieter oder Modelle weiter ein. Reihenfolge: Ba ### `tools.elevated` -Steuert erweiterten `exec`-Zugriff außerhalb der Sandbox: +Steuert erhöhten `exec`-Zugriff außerhalb der Sandbox: ```json5 { @@ -2106,8 +2260,8 @@ Steuert erweiterten `exec`-Zugriff außerhalb der Sandbox: ``` - Die Überschreibung pro Agent (`agents.list[].tools.elevated`) kann nur weiter einschränken. -- `/elevated on|off|ask|full` speichert den Zustand pro Sitzung; Inline-Direktiven gelten nur für eine einzelne Nachricht. -- Erweitertes `exec` umgeht die Sandbox und verwendet den konfigurierten Escape-Pfad (`gateway` standardmäßig oder `node`, wenn das `exec`-Ziel `node` ist). +- `/elevated on|off|ask|full` speichert den Zustand pro Sitzung; Inline-Direktiven gelten für eine einzelne Nachricht. +- Erhöhtes `exec` umgeht Sandboxing und verwendet den konfigurierten Escape-Pfad (`gateway` standardmäßig oder `node`, wenn das `exec`-Ziel `node` ist). ### `tools.exec` @@ -2131,8 +2285,8 @@ Steuert erweiterten `exec`-Zugriff außerhalb der Sandbox: ### `tools.loopDetection` -Sicherheitsprüfungen für Tool-Schleifen sind standardmäßig **deaktiviert**. Setzen Sie `enabled: true`, um die Erkennung zu aktivieren. -Einstellungen können global unter `tools.loopDetection` definiert und pro Agent unter `agents.list[].tools.loopDetection` überschrieben werden. +Sicherheitsprüfungen für Tool-Schleifen sind **standardmäßig deaktiviert**. Setzen Sie `enabled: true`, um die Erkennung zu aktivieren. +Einstellungen können global in `tools.loopDetection` definiert und pro Agent unter `agents.list[].tools.loopDetection` überschrieben werden. ```json5 { @@ -2153,10 +2307,10 @@ Einstellungen können global unter `tools.loopDetection` definiert und pro Agent } ``` -- `historySize`: maximale Tool-Call-Historie, die für die Schleifenanalyse behalten wird. -- `warningThreshold`: Schwellenwert für Warnungen bei sich wiederholenden Mustern ohne Fortschritt. -- `criticalThreshold`: höherer Wiederholungsschwellenwert zum Blockieren kritischer Schleifen. -- `globalCircuitBreakerThreshold`: harte Stoppschwelle für jeden Lauf ohne Fortschritt. +- `historySize`: maximale Tool-Call-Historie, die für die Schleifenanalyse beibehalten wird. +- `warningThreshold`: Schwellwert für Warnungen bei sich wiederholenden Mustern ohne Fortschritt. +- `criticalThreshold`: höherer Wiederholungsschwellwert zum Blockieren kritischer Schleifen. +- `globalCircuitBreakerThreshold`: harter Stoppschwellwert für jeden Lauf ohne Fortschritt. - `detectors.genericRepeat`: warnt bei wiederholten Aufrufen desselben Tools mit denselben Argumenten. - `detectors.knownPollNoProgress`: warnt/blockiert bei bekannten Poll-Tools (`process.poll`, `command_status` usw.). - `detectors.pingPong`: warnt/blockiert bei alternierenden Paarmustern ohne Fortschritt. @@ -2202,7 +2356,7 @@ Konfiguriert das Verständnis eingehender Medien (Bild/Audio/Video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // Opt-in: fertige asynchrone Musik/Videos direkt an den Kanal senden + directSend: false, // Opt-in: abgeschlossene asynchrone Musik-/Videos direkt an den Kanal senden }, audio: { enabled: true, @@ -2228,28 +2382,30 @@ Konfiguriert das Verständnis eingehender Medien (Bild/Audio/Video): -**Anbietereintrag** (`type: "provider"` oder weggelassen): +**Provider-Eintrag** (`type: "provider"` oder weggelassen): -- `provider`: ID des API-Anbieters (`openai`, `anthropic`, `google`/`gemini`, `groq` usw.) +- `provider`: API-Provider-ID (`openai`, `anthropic`, `google`/`gemini`, `groq` usw.) - `model`: Überschreibung der Modell-ID -- `profile` / `preferredProfile`: Auswahl des Profils aus `auth-profiles.json` +- `profile` / `preferredProfile`: Auswahl des `auth-profiles.json`-Profils **CLI-Eintrag** (`type: "cli"`): -- `command`: auszuführende Datei -- `args`: templatebasierte Argumente (unterstützt `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` usw.) +- `command`: auszuführendes Programm +- `args`: Template-Argumente (unterstützt `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` usw.) **Gemeinsame Felder:** -- `capabilities`: optionale Liste (`image`, `audio`, `video`). Standardwerte: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `capabilities`: optionale Liste (`image`, `audio`, `video`). Standardwerte: `openai`/`anthropic`/`minimax` → Bild, `google` → Bild+Audio+Video, `groq` → Audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: Überschreibungen pro Eintrag. -- Bei Fehlern wird auf den nächsten Eintrag zurückgegriffen. +- Bei Fehlern wird auf den nächsten Eintrag zurückgefallen. -Die Anbieter-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.json` → Umgebungsvariablen → `models.providers.*.apiKey`. +Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.json` → Umgebungsvariablen → `models.providers.*.apiKey`. **Felder für asynchrone Fertigstellung:** -- `asyncCompletion.directSend`: wenn `true`, versuchen abgeschlossene asynchrone Aufgaben von `music_generate` und `video_generate` zuerst die direkte Kanalzustellung. Standard: `false` (Legacy-Pfad über Requester-Sitzungs-Weckung/Modellzustellung). +- `asyncCompletion.directSend`: wenn `true`, versuchen abgeschlossene asynchrone Tasks von `music_generate` + und `video_generate` zuerst die direkte Kanalzustellung. Standard: `false` + (Legacy-Pfad über Anforderer-Sitzungs-Wakeup/Modellzustellung). @@ -2268,9 +2424,9 @@ Die Anbieter-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.jso ### `tools.sessions` -Steuert, welche Sitzungen mit den Sitzungstools (`sessions_list`, `sessions_history`, `sessions_send`) adressiert werden können. +Steuert, welche Sitzungen von den Sitzungs-Tools (`sessions_list`, `sessions_history`, `sessions_send`) adressiert werden können. -Standard: `tree` (aktuelle Sitzung + von ihr erzeugte Sitzungen, etwa Subagenten). +Standard: `tree` (aktuelle Sitzung + von ihr gestartete Sitzungen, wie z. B. Unteragenten). ```json5 { @@ -2286,14 +2442,14 @@ Standard: `tree` (aktuelle Sitzung + von ihr erzeugte Sitzungen, etwa Subagenten Hinweise: - `self`: nur der aktuelle Sitzungsschlüssel. -- `tree`: aktuelle Sitzung + von der aktuellen Sitzung erzeugte Sitzungen (Subagenten). -- `agent`: jede Sitzung, die zur aktuellen Agent-ID gehört (kann auch andere Benutzer einschließen, wenn Sie Sitzungen pro Absender unter derselben Agent-ID ausführen). -- `all`: jede Sitzung. Kanalübergreifendes Targeting erfordert weiterhin `tools.agentToAgent`. -- Sandbox-Klammerung: Wenn die aktuelle Sitzung in einer Sandbox läuft und `agents.defaults.sandbox.sessionToolsVisibility="spawned"` gesetzt ist, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"` ist. +- `tree`: aktuelle Sitzung + von der aktuellen Sitzung gestartete Sitzungen (Unteragenten). +- `agent`: jede Sitzung, die zur aktuellen Agenten-ID gehört (kann auch andere Benutzer einschließen, wenn Sie Sitzungen pro Absender unter derselben Agenten-ID ausführen). +- `all`: jede Sitzung. Agentenübergreifendes Adressieren erfordert weiterhin `tools.agentToAgent`. +- Sandbox-Begrenzung: Wenn die aktuelle Sitzung in einer Sandbox läuft und `agents.defaults.sandbox.sessionToolsVisibility="spawned"` ist, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"` ist. ### `tools.sessions_spawn` -Steuert die Unterstützung von Inline-Anhängen für `sessions_spawn`. +Steuert die Unterstützung für Inline-Anhänge bei `sessions_spawn`. ```json5 { @@ -2301,10 +2457,10 @@ Steuert die Unterstützung von Inline-Anhängen für `sessions_spawn`. sessions_spawn: { attachments: { enabled: false, // Opt-in: auf true setzen, um Inline-Dateianhänge zu erlauben - maxTotalBytes: 5242880, // insgesamt 5 MB über alle Dateien + maxTotalBytes: 5242880, // 5 MB insgesamt über alle Dateien maxFiles: 50, maxFileBytes: 1048576, // 1 MB pro Datei - retainOnSessionKeep: false, // Anhänge behalten, wenn cleanup="keep" + retainOnSessionKeep: false, // Anhänge beibehalten, wenn cleanup="keep" }, }, }, @@ -2313,16 +2469,16 @@ Steuert die Unterstützung von Inline-Anhängen für `sessions_spawn`. Hinweise: -- Anhänge werden nur für `runtime: "subagent"` unterstützt. Die ACP-Runtime lehnt sie ab. +- Anhänge werden nur für `runtime: "subagent"` unterstützt. Die ACP-Laufzeit lehnt sie ab. - Dateien werden im Child-Workspace unter `.openclaw/attachments//` mit einer `.manifest.json` materialisiert. -- Der Inhalt von Anhängen wird automatisch aus der persistenten Transkriptspeicherung entfernt. -- Base64-Eingaben werden mit strikter Alphabet-/Padding-Prüfung und einer Größenprüfung vor dem Dekodieren validiert. +- Anhangsinhalte werden automatisch aus der Transkriptpersistenz redigiert. +- Base64-Eingaben werden mit strenger Alphabet-/Padding-Prüfung und einer Größenprüfung vor dem Dekodieren validiert. - Dateiberechtigungen sind `0700` für Verzeichnisse und `0600` für Dateien. -- Die Bereinigung folgt der Richtlinie `cleanup`: `delete` entfernt Anhänge immer; `keep` behält sie nur, wenn `retainOnSessionKeep: true` gesetzt ist. +- Die Bereinigung folgt der Richtlinie `cleanup`: `delete` entfernt Anhänge immer; `keep` behält sie nur bei, wenn `retainOnSessionKeep: true`. ### `tools.experimental` -Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, sofern keine Regel zur automatischen Aktivierung für strikt agentisches GPT-5 greift. +Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, außer wenn eine Auto-Aktivierungsregel für streng agentische GPT-5 greift. ```json5 { @@ -2336,9 +2492,9 @@ Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, sofern keine Hinweise: -- `planTool`: aktiviert das strukturierte Tool `update_plan` zur Nachverfolgung nichttrivialer mehrstufiger Arbeit. -- Standard: `false`, sofern nicht `agents.defaults.embeddedPi.executionContract` (oder eine Überschreibung pro Agent) für einen Lauf mit OpenAI oder OpenAI Codex der GPT-5-Familie auf `"strict-agentic"` gesetzt ist. Setzen Sie `true`, um das Tool auch außerhalb dieses Bereichs zu erzwingen, oder `false`, um es selbst für strikt agentische GPT-5-Läufe deaktiviert zu lassen. -- Wenn aktiviert, fügt der System-Prompt auch Nutzungshinweise hinzu, sodass das Modell es nur für umfangreichere Arbeit verwendet und höchstens einen Schritt als `in_progress` hält. +- `planTool`: aktiviert das strukturierte Tool `update_plan` für die Verfolgung nicht-trivialer mehrstufiger Arbeit. +- Standard: `false`, außer wenn `agents.defaults.embeddedPi.executionContract` (oder eine Überschreibung pro Agent) für einen OpenAI- oder OpenAI-Codex-GPT-5-Family-Lauf auf `"strict-agentic"` gesetzt ist. Setzen Sie `true`, um das Tool auch außerhalb dieses Bereichs zu erzwingen, oder `false`, um es selbst für streng agentische GPT-5-Läufe deaktiviert zu halten. +- Wenn aktiviert, fügt der System-Prompt außerdem Nutzungshinweise hinzu, damit das Modell es nur für wesentliche Arbeit verwendet und höchstens einen Schritt `in_progress` hält. ### `agents.defaults.subagents` @@ -2358,16 +2514,16 @@ Hinweise: } ``` -- `model`: Standardmodell für erzeugte Subagenten. Wenn nicht gesetzt, erben Subagenten das Modell des Aufrufers. -- `allowAgents`: Standard-Allowlist der Ziel-Agent-IDs für `sessions_spawn`, wenn der anfragende Agent nicht selbst `subagents.allowAgents` setzt (`["*"]` = beliebig; Standard: nur derselbe Agent). +- `model`: Standardmodell für gestartete Unteragenten. Wenn nicht gesetzt, übernehmen Unteragenten das Modell des Aufrufers. +- `allowAgents`: Standard-Zulassungsliste der Ziel-Agenten-IDs für `sessions_spawn`, wenn der anfordernde Agent keine eigene `subagents.allowAgents` setzt (`["*"]` = beliebig; Standard: nur derselbe Agent). - `runTimeoutSeconds`: Standard-Timeout (Sekunden) für `sessions_spawn`, wenn der Tool-Aufruf `runTimeoutSeconds` weglässt. `0` bedeutet kein Timeout. -- Tool-Richtlinie pro Subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Tool-Richtlinie pro Unteragent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Benutzerdefinierte Anbieter und Base-URLs +## Benutzerdefinierte Provider und Base-URLs -OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte Anbieter über `models.providers` in der Konfiguration oder `~/.openclaw/agents//agent/models.json` hinzu. +OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte Provider über `models.providers` in der Konfiguration oder `~/.openclaw/agents//agent/models.json` hinzu. ```json5 { @@ -2397,49 +2553,49 @@ OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte ``` - Verwenden Sie `authHeader: true` + `headers` für benutzerdefinierte Authentifizierungsanforderungen. -- Überschreiben Sie das Root der Agent-Konfiguration mit `OPENCLAW_AGENT_DIR` (oder `PI_CODING_AGENT_DIR`, einem Legacy-Alias für Umgebungsvariablen). -- Merge-Priorität für übereinstimmende Anbieter-IDs: +- Überschreiben Sie das Root der Agentenkonfiguration mit `OPENCLAW_AGENT_DIR` (oder `PI_CODING_AGENT_DIR`, ein Legacy-Alias für Umgebungsvariablen). +- Merge-Priorität für übereinstimmende Provider-IDs: - Nicht leere `baseUrl`-Werte aus `models.json` des Agenten haben Vorrang. - - Nicht leere `apiKey`-Werte des Agenten haben nur dann Vorrang, wenn dieser Anbieter im aktuellen Kontext von Konfiguration/Auth-Profil nicht über SecretRef verwaltet wird. - - SecretRef-verwaltete `apiKey`-Werte des Anbieters werden aus Quellenmarkierungen aktualisiert (`ENV_VAR_NAME` für env-Referenzen, `secretref-managed` für file-/exec-Referenzen), statt aufgelöste Secrets zu persistieren. - - SecretRef-verwaltete Header-Werte des Anbieters werden aus Quellenmarkierungen aktualisiert (`secretref-env:ENV_VAR_NAME` für env-Referenzen, `secretref-managed` für file-/exec-Referenzen). - - Leere oder fehlende `apiKey`-/`baseUrl`-Werte des Agenten greifen auf `models.providers` in der Konfiguration zurück. - - Übereinstimmende `contextWindow`-/`maxTokens`-Werte des Modells verwenden den höheren Wert zwischen expliziter Konfiguration und impliziten Katalogwerten. - - Übereinstimmende `contextTokens` behalten ein explizites Laufzeitlimit bei, wenn vorhanden; verwenden Sie dies, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern. + - Nicht leere `apiKey`-Werte des Agenten haben nur dann Vorrang, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profil-Kontext nicht von SecretRef verwaltet wird. + - Von SecretRef verwaltete Provider-`apiKey`-Werte werden aus Quellmarkern aktualisiert (`ENV_VAR_NAME` für Env-Referenzen, `secretref-managed` für Datei-/Exec-Referenzen), statt aufgelöste Secrets zu persistieren. + - Von SecretRef verwaltete Provider-Header-Werte werden aus Quellmarkern aktualisiert (`secretref-env:ENV_VAR_NAME` für Env-Referenzen, `secretref-managed` für Datei-/Exec-Referenzen). + - Leere oder fehlende `apiKey`/`baseUrl` des Agenten fallen auf `models.providers` in der Konfiguration zurück. + - Übereinstimmende `contextWindow`/`maxTokens` eines Modells verwenden den höheren Wert zwischen expliziter Konfiguration und impliziten Katalogwerten. + - Übereinstimmende `contextTokens` eines Modells behalten ein explizites Laufzeitlimit bei, wenn vorhanden; verwenden Sie dies, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern. - Verwenden Sie `models.mode: "replace"`, wenn die Konfiguration `models.json` vollständig neu schreiben soll. - - Die Persistenz von Markierungen ist quellenautoritativ: Markierungen werden aus dem aktiven Quellkonfigurations-Snapshot (vor der Auflösung) geschrieben, nicht aus aufgelösten Secret-Werten der Laufzeit. + - Marker-Persistenz ist quellenautoritativ: Marker werden aus dem aktiven Snapshot der Quellkonfiguration (vor der Auflösung) geschrieben, nicht aus aufgelösten Laufzeit-Secret-Werten. -### Details zu Anbieterfeldern +### Details zu Provider-Feldern -- `models.mode`: Verhalten des Anbieter-Katalogs (`merge` oder `replace`). -- `models.providers`: benutzerdefinierte Anbieterzuordnung, indiziert nach Anbieter-ID. +- `models.mode`: Verhalten des Provider-Katalogs (`merge` oder `replace`). +- `models.providers`: benutzerdefinierte Provider-Map, indiziert nach Provider-ID. - `models.providers.*.api`: Request-Adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` usw.). -- `models.providers.*.apiKey`: Anbieter-Anmeldedaten (bevorzugt SecretRef/env-Substitution verwenden). +- `models.providers.*.apiKey`: Provider-Zugangsdaten (bevorzugt mit SecretRef/Env-Substitution). - `models.providers.*.auth`: Authentifizierungsstrategie (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: für Ollama + `openai-completions` `options.num_ctx` in Requests injizieren (Standard: `true`). -- `models.providers.*.authHeader`: erzwingt bei Bedarf die Übertragung von Anmeldedaten im Header `Authorization`. +- `models.providers.*.injectNumCtxForOpenAICompat`: für Ollama + `openai-completions` `options.num_ctx` in Requests einfügen (Standard: `true`). +- `models.providers.*.authHeader`: erzwingt bei Bedarf die Übertragung der Zugangsdaten im `Authorization`-Header. - `models.providers.*.baseUrl`: Base-URL der Upstream-API. -- `models.providers.*.headers`: zusätzliche statische Header für Proxy-/Mandanten-Routing. -- `models.providers.*.request`: Transport-Überschreibungen für HTTP-Requests von Modellanbietern. - - `request.headers`: zusätzliche Header (werden mit den Standardwerten des Anbieters zusammengeführt). Werte akzeptieren SecretRef. - - `request.auth`: Überschreibung der Authentifizierungsstrategie. Modi: `"provider-default"` (integrierte Auth des Anbieters verwenden), `"authorization-bearer"` (mit `token`), `"header"` (mit `headerName`, `value`, optional `prefix`). - - `request.proxy`: Überschreibung des HTTP-Proxys. Modi: `"env-proxy"` (Umgebungsvariablen `HTTP_PROXY`/`HTTPS_PROXY` verwenden), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren ein optionales Unterobjekt `tls`. +- `models.providers.*.headers`: zusätzliche statische Header für Proxy-/Tenant-Routing. +- `models.providers.*.request`: Transport-Überschreibungen für HTTP-Requests von Modell-Providern. + - `request.headers`: zusätzliche Header (mit Provider-Standardwerten zusammengeführt). Werte akzeptieren SecretRef. + - `request.auth`: Überschreibung der Authentifizierungsstrategie. Modi: `"provider-default"` (integrierte Authentifizierung des Providers verwenden), `"authorization-bearer"` (mit `token`), `"header"` (mit `headerName`, `value`, optional `prefix`). + - `request.proxy`: Überschreibung des HTTP-Proxys. Modi: `"env-proxy"` (verwendet `HTTP_PROXY`/`HTTPS_PROXY`-Umgebungsvariablen), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren optional ein `tls`-Unterobjekt. - `request.tls`: TLS-Überschreibung für direkte Verbindungen. Felder: `ca`, `cert`, `key`, `passphrase` (alle akzeptieren SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: wenn `true`, erlaubt HTTPS zu `baseUrl`, wenn DNS auf private, CGNAT- oder ähnliche Bereiche auflöst, über die HTTP-Fetch-Schutzlogik des Anbieters (Opt-in für Operatoren bei vertrauenswürdigen selbstgehosteten OpenAI-kompatiblen Endpunkten). WebSocket verwendet dieselbe `request` für Header/TLS, aber nicht diese SSRF-Schutzlogik für Fetch. Standard `false`. -- `models.providers.*.models`: explizite Modellsatzeinträge des Anbieters. -- `models.providers.*.models.*.contextWindow`: Metadaten des nativen Modell-Kontextfensters. + - `request.allowPrivateNetwork`: wenn `true`, HTTPS zu `baseUrl` erlauben, wenn DNS zu privaten, CGNAT- oder ähnlichen Bereichen auflöst, über die HTTP-Fetch-Schutzfunktion des Providers (Opt-in des Operators für vertrauenswürdige selbstgehostete OpenAI-kompatible Endpunkte). WebSocket verwendet denselben `request` für Header/TLS, aber nicht dieses Fetch-SSRF-Gate. Standard `false`. +- `models.providers.*.models`: explizite Modellkatalogeinträge des Providers. +- `models.providers.*.models.*.contextWindow`: native Metadaten zum Kontextfenster des Modells. - `models.providers.*.models.*.contextTokens`: optionales Laufzeitlimit für den Kontext. Verwenden Sie dies, wenn Sie ein kleineres effektives Kontextbudget als das native `contextWindow` des Modells möchten. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: optionaler Kompatibilitätshinweis. Für `api: "openai-completions"` mit einer nicht leeren, nicht nativen `baseUrl` (Host nicht `api.openai.com`) erzwingt OpenClaw dies zur Laufzeit auf `false`. Leere/weggelassene `baseUrl` behält das Standardverhalten von OpenAI bei. -- `models.providers.*.models.*.compat.requiresStringContent`: optionaler Kompatibilitätshinweis für OpenAI-kompatible Chat-Endpunkte, die nur Strings unterstützen. Wenn `true`, flacht OpenClaw reine Text-Arrays in `messages[].content` vor dem Senden des Requests zu einfachen Strings ab. -- `plugins.entries.amazon-bedrock.config.discovery`: Root für Bedrock-Einstellungen zur automatischen Erkennung. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: optionaler Kompatibilitätshinweis. Für `api: "openai-completions"` mit einer nicht leeren, nicht nativen `baseUrl` (Host nicht `api.openai.com`) erzwingt OpenClaw zur Laufzeit `false`. Eine leere/weggelassene `baseUrl` behält das Standardverhalten von OpenAI bei. +- `models.providers.*.models.*.compat.requiresStringContent`: optionaler Kompatibilitätshinweis für reine String-OpenAI-kompatible Chat-Endpunkte. Wenn `true`, flacht OpenClaw reine Text-Arrays in `messages[].content` vor dem Senden des Requests zu einfachen Strings ab. +- `plugins.entries.amazon-bedrock.config.discovery`: Root der Bedrock-Einstellungen für automatische Erkennung. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: implizite Erkennung ein-/ausschalten. - `plugins.entries.amazon-bedrock.config.discovery.region`: AWS-Region für die Erkennung. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optionaler Filter nach Anbieter-ID für gezielte Erkennung. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optionaler Filter nach Provider-ID für gezielte Erkennung. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: Polling-Intervall für die Aktualisierung der Erkennung. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: Fallback-Kontextfenster für erkannte Modelle. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: Fallback für maximale Ausgabetokens erkannter Modelle. -### Anbieterbeispiele +### Provider-Beispiele @@ -2475,7 +2631,7 @@ OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte } ``` -Verwenden Sie `cerebras/zai-glm-4.7` für Cerebras; `zai/glm-4.7` für direktes Z.AI. +Verwenden Sie `cerebras/zai-glm-4.7` für Cerebras; `zai/glm-4.7` für Z.AI direkt. @@ -2492,7 +2648,7 @@ Verwenden Sie `cerebras/zai-glm-4.7` für Cerebras; `zai/glm-4.7` für direktes } ``` -Setzen Sie `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`). Verwenden Sie `opencode/...`-Referenzen für den Zen-Katalog oder `opencode-go/...`-Referenzen für den Go-Katalog. Kurzform: `openclaw onboard --auth-choice opencode-zen` oder `openclaw onboard --auth-choice opencode-go`. +Setzen Sie `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`). Verwenden Sie Referenzen mit `opencode/...` für den Zen-Katalog oder mit `opencode-go/...` für den Go-Katalog. Kurzform: `openclaw onboard --auth-choice opencode-zen` oder `openclaw onboard --auth-choice opencode-go`. @@ -2509,11 +2665,11 @@ Setzen Sie `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`). Verwenden Sie `open } ``` -Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Aliase akzeptiert. Kurzform: `openclaw onboard --auth-choice zai-api-key`. +Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` sind akzeptierte Aliase. Kurzform: `openclaw onboard --auth-choice zai-api-key`. - Allgemeiner Endpunkt: `https://api.z.ai/api/paas/v4` - Coding-Endpunkt (Standard): `https://api.z.ai/api/coding/paas/v4` -- Für den allgemeinen Endpunkt definieren Sie einen benutzerdefinierten Anbieter mit Überschreibung der Base-URL. +- Für den allgemeinen Endpunkt definieren Sie einen benutzerdefinierten Provider mit Überschreibung der Base-URL. @@ -2554,7 +2710,9 @@ Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Aliase akzeptiert. Ku Für den China-Endpunkt: `baseUrl: "https://api.moonshot.cn/v1"` oder `openclaw onboard --auth-choice moonshot-api-key-cn`. -Native Moonshot-Endpunkte melden Streaming-Nutzungskompatibilität auf dem gemeinsamen Transport `openai-completions`, und OpenClaw richtet sich dabei nach den Fähigkeiten des Endpunkts statt allein nach der integrierten Anbieter-ID. +Native Moonshot-Endpunkte geben Streaming-Nutzungskompatibilität für den gemeinsamen +Transport `openai-completions` an, und OpenClaw richtet sich dabei nach den Fähigkeiten des Endpunkts +statt nur nach der integrierten Provider-ID. @@ -2572,7 +2730,7 @@ Native Moonshot-Endpunkte melden Streaming-Nutzungskompatibilität auf dem gemei } ``` -Anthropic-kompatibel, integrierter Anbieter. Kurzform: `openclaw onboard --auth-choice kimi-code-api-key`. +Anthropic-kompatibler integrierter Provider. Kurzform: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2611,7 +2769,7 @@ Anthropic-kompatibel, integrierter Anbieter. Kurzform: `openclaw onboard --auth- } ``` -Die Base-URL sollte `/v1` weglassen (der Anthropic-Client hängt sie an). Kurzform: `openclaw onboard --auth-choice synthetic-api-key`. +Die Base-URL sollte `/v1` weglassen (der Anthropic-Client hängt es an). Kurzform: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2654,14 +2812,17 @@ Die Base-URL sollte `/v1` weglassen (der Anthropic-Client hängt sie an). Kurzfo Setzen Sie `MINIMAX_API_KEY`. Kurzformen: `openclaw onboard --auth-choice minimax-global-api` oder `openclaw onboard --auth-choice minimax-cn-api`. -Der Modellkatalog ist standardmäßig auf nur M2.7 gesetzt. -Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw MiniMax-Thinking standardmäßig, sofern Sie `thinking` nicht explizit selbst setzen. `/fast on` oder `params.fastMode: true` schreibt `MiniMax-M2.7` zu `MiniMax-M2.7-highspeed` um. +Der Modellkatalog verwendet standardmäßig nur M2.7. +Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw standardmäßig MiniMax-Thinking, +sofern Sie `thinking` nicht explizit selbst setzen. `/fast on` oder +`params.fastMode: true` schreibt `MiniMax-M2.7` auf +`MiniMax-M2.7-highspeed` um. -Siehe [Local Models](/de/gateway/local-models). Kurz gesagt: Führen Sie ein großes lokales Modell über die LM Studio Responses API auf leistungsfähiger Hardware aus; behalten Sie gehostete Modelle zusammengeführt als Fallback. +Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein großes lokales Modell über die LM Studio Responses API auf leistungsstarker Hardware aus; behalten Sie gehostete Modelle für Fallbacks zusammengeführt. @@ -2692,10 +2853,12 @@ Siehe [Local Models](/de/gateway/local-models). Kurz gesagt: Führen Sie ein gro } ``` -- `allowBundled`: optionale Allowlist nur für gebündelte Skills (verwaltete/Workspace-Skills bleiben unberührt). +- `allowBundled`: optionale Zulassungsliste nur für gebündelte Skills (verwaltete/Workspace-Skills sind nicht betroffen). - `load.extraDirs`: zusätzliche gemeinsame Skill-Roots (niedrigste Priorität). -- `install.preferBrew`: wenn true, werden Homebrew-Installer bevorzugt, wenn `brew` verfügbar ist, bevor auf andere Installer-Arten zurückgegriffen wird. -- `install.nodeManager`: Präferenz für Node-Installer bei Spezifikationen aus `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `install.preferBrew`: wenn true, werden Homebrew-Installer bevorzugt, wenn `brew` + verfügbar ist, bevor auf andere Installer-Arten zurückgefallen wird. +- `install.nodeManager`: Präferenz für Node-Installer bei `metadata.openclaw.install`- + Spezifikationen (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` deaktiviert einen Skill, selbst wenn er gebündelt/installiert ist. - `entries..apiKey`: Komfortfeld für Skills, die eine primäre Umgebungsvariable deklarieren (Klartext-String oder SecretRef-Objekt). @@ -2728,37 +2891,37 @@ Siehe [Local Models](/de/gateway/local-models). Kurz gesagt: Führen Sie ein gro - Geladen aus `~/.openclaw/extensions`, `/.openclaw/extensions` sowie `plugins.load.paths`. - Die Erkennung akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles im Standardlayout. - **Konfigurationsänderungen erfordern einen Gateway-Neustart.** -- `allow`: optionale Allowlist (nur aufgeführte Plugins werden geladen). `deny` gewinnt. +- `allow`: optionale Zulassungsliste (nur aufgeführte Plugins werden geladen). `deny` gewinnt. - `plugins.entries..apiKey`: Komfortfeld für API-Schlüssel auf Plugin-Ebene (wenn vom Plugin unterstützt). -- `plugins.entries..env`: Plugin-spezifische Zuordnung von Umgebungsvariablen. -- `plugins.entries..hooks.allowPromptInjection`: wenn `false`, blockiert der Core `before_prompt_build` und ignoriert promptverändernde Felder aus Legacy-`before_agent_start`, während Legacy-`modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte Hook-Verzeichnisse aus Bundles. -- `plugins.entries..subagent.allowModelOverride`: vertraut diesem Plugin explizit, pro Lauf Überschreibungen von `provider` und `model` für Hintergrund-Subagent-Läufe anzufordern. -- `plugins.entries..subagent.allowedModels`: optionale Allowlist kanonischer Ziele vom Typ `provider/model` für vertrauenswürdige Subagent-Überschreibungen. Verwenden Sie `"*"`, nur wenn Sie bewusst jedes Modell erlauben möchten. -- `plugins.entries..config`: plugindefiniertes Konfigurationsobjekt (validiert durch das native OpenClaw-Plugin-Schema, sofern verfügbar). -- `plugins.entries.firecrawl.config.webFetch`: Firecrawl-Einstellungen für den Web-Fetch-Anbieter. - - `apiKey`: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt zurück auf `plugins.entries.firecrawl.config.webSearch.apiKey`, Legacy-`tools.web.fetch.firecrawl.apiKey` oder die Umgebungsvariable `FIRECRAWL_API_KEY`. - - `baseUrl`: Firecrawl-API-Base-URL (Standard: `https://api.firecrawl.dev`). +- `plugins.entries..env`: pluginbezogene Env-Variablen-Map. +- `plugins.entries..hooks.allowPromptInjection`: wenn `false`, blockiert der Kern `before_prompt_build` und ignoriert promptmutierende Felder aus Legacy-`before_agent_start`, während Legacy-`modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte hook-Verzeichnisse aus Bundles. +- `plugins.entries..subagent.allowModelOverride`: diesem Plugin ausdrücklich vertrauen, damit es pro Lauf Überschreibungen von `provider` und `model` für Hintergrund-Unteragenten anfordern darf. +- `plugins.entries..subagent.allowedModels`: optionale Zulassungsliste kanonischer Ziele im Format `provider/model` für vertrauenswürdige Überschreibungen von Unteragenten. Verwenden Sie `"*"` nur, wenn Sie absichtlich jedes Modell zulassen möchten. +- `plugins.entries..config`: Plugin-definiertes Konfigurationsobjekt (validiert durch das native OpenClaw-Plugin-Schema, sofern verfügbar). +- `plugins.entries.firecrawl.config.webFetch`: Einstellungen des Firecrawl-Web-Fetch-Providers. + - `apiKey`: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt zurück auf `plugins.entries.firecrawl.config.webSearch.apiKey`, Legacy-`tools.web.fetch.firecrawl.apiKey` oder die Env-Variable `FIRECRAWL_API_KEY`. + - `baseUrl`: Base-URL der Firecrawl-API (Standard: `https://api.firecrawl.dev`). - `onlyMainContent`: nur den Hauptinhalt von Seiten extrahieren (Standard: `true`). - `maxAgeMs`: maximales Cache-Alter in Millisekunden (Standard: `172800000` / 2 Tage). - `timeoutSeconds`: Timeout für Scrape-Requests in Sekunden (Standard: `60`). - `plugins.entries.xai.config.xSearch`: Einstellungen für xAI X Search (Grok-Websuche). - - `enabled`: den Anbieter X Search aktivieren. + - `enabled`: den X-Search-Provider aktivieren. - `model`: für die Suche zu verwendendes Grok-Modell (z. B. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: Einstellungen für Memory-Dreaming. Phasen und Schwellenwerte finden Sie unter [Dreaming](/de/concepts/dreaming). - - `enabled`: globaler Dreaming-Schalter (Standard `false`). - - `frequency`: Cron-Takt für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`). - - Phasenrichtlinie und Schwellenwerte sind Implementierungsdetails (keine benutzerseitigen Konfigurationsschlüssel). -- Die vollständige Memory-Konfiguration befindet sich in [Memory configuration reference](/de/reference/memory-config): +- `plugins.entries.memory-core.config.dreaming`: Einstellungen für Speicher-Dreaming. Phasen und Schwellwerte finden Sie unter [Dreaming](/de/concepts/dreaming). + - `enabled`: zentraler Schalter für Dreaming (Standard `false`). + - `frequency`: Cron-Kadenz für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`). + - Phasenrichtlinie und Schwellwerte sind Implementierungsdetails (keine benutzerseitigen Konfigurationsschlüssel). +- Die vollständige Speicherkonfiguration finden Sie unter [Speicherkonfigurationsreferenz](/de/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standards aus `settings.json` beisteuern; OpenClaw wendet diese als bereinigte Agent-Einstellungen an, nicht als rohe OpenClaw-Konfigurations-Patches. -- `plugins.slots.memory`: aktive ID des Memory-Plugins auswählen oder `"none"`, um Memory-Plugins zu deaktivieren. -- `plugins.slots.contextEngine`: aktive ID des Context-Engine-Plugins auswählen; standardmäßig `"legacy"`, sofern Sie keine andere Engine installieren und auswählen. -- `plugins.installs`: CLI-verwaltete Installationsmetadaten, die von `openclaw plugins update` verwendet werden. - - Umfasst `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. +- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standardwerte aus `settings.json` beitragen; OpenClaw wendet diese als bereinigte Agenteneinstellungen an, nicht als rohe OpenClaw-Konfigurations-Patches. +- `plugins.slots.memory`: aktive Memory-Plugin-ID auswählen oder `"none"` zum Deaktivieren von Speicher-Plugins. +- `plugins.slots.contextEngine`: aktive Context-Engine-Plugin-ID auswählen; standardmäßig `"legacy"`, sofern Sie keine andere Engine installieren und auswählen. +- `plugins.installs`: von der CLI verwaltete Installationsmetadaten, die von `openclaw plugins update` verwendet werden. + - Enthält `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - Behandeln Sie `plugins.installs.*` als verwalteten Zustand; bevorzugen Sie CLI-Befehle gegenüber manuellen Änderungen. Siehe [Plugins](/de/tools/plugin). @@ -2802,21 +2965,27 @@ Siehe [Plugins](/de/tools/plugin). ``` - `evaluateEnabled: false` deaktiviert `act:evaluate` und `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist deaktiviert, wenn nicht gesetzt, daher bleibt Browser-Navigation standardmäßig strikt. -- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` nur dann, wenn Sie Browser-Navigation in privaten Netzwerken bewusst vertrauen. -- Im strikten Modus unterliegen entfernte CDP-Profilendpunkte (`profiles.*.cdpUrl`) bei Erreichbarkeits-/Erkennungsprüfungen derselben Blockierung für private Netzwerke. -- `ssrfPolicy.allowPrivateNetwork` wird weiterhin als Legacy-Alias unterstützt. -- Im strikten Modus verwenden Sie `ssrfPolicy.hostnameAllowlist` und `ssrfPolicy.allowedHostnames` für explizite Ausnahmen. -- Remote-Profile sind nur zum Anhängen geeignet (Start/Stopp/Reset deaktiviert). +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist deaktiviert, wenn nicht gesetzt, sodass Browser-Navigation standardmäßig streng bleibt. +- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` nur, wenn Sie Navigation des Browsers in private Netzwerke ausdrücklich vertrauen. +- Im strengen Modus unterliegen Remote-CDP-Profilendpunkte (`profiles.*.cdpUrl`) bei Erreichbarkeits-/Erkennungsprüfungen derselben Sperre für private Netzwerke. +- `ssrfPolicy.allowPrivateNetwork` bleibt als Legacy-Alias unterstützt. +- Verwenden Sie im strengen Modus `ssrfPolicy.hostnameAllowlist` und `ssrfPolicy.allowedHostnames` für explizite Ausnahmen. +- Remote-Profile sind nur zum Anhängen verfügbar (Start/Stopp/Reset deaktiviert). - `profiles.*.cdpUrl` akzeptiert `http://`, `https://`, `ws://` und `wss://`. - Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` erkennen soll; verwenden Sie WS(S), wenn Ihr Anbieter Ihnen eine direkte DevTools-WebSocket-URL liefert. -- `existing-session`-Profile sind nur hostseitig verfügbar und verwenden Chrome MCP anstelle von CDP. -- `existing-session`-Profile können `userDataDir` setzen, um ein bestimmtes Profil eines Chromium-basierten Browsers wie Brave oder Edge anzusprechen. -- `existing-session`-Profile behalten die aktuellen Routenbeschränkungen von Chrome MCP bei: snapshot-/ref-basierte Aktionen statt CSS-Selektor-Targeting, Hooks zum Hochladen einzelner Dateien, keine Überschreibungen für Dialog-Timeouts, kein `wait --load networkidle` sowie kein `responsebody`, kein PDF-Export, keine Download-Abfangung und keine Batch-Aktionen. -- Lokal verwaltete `openclaw`-Profile weisen `cdpPort` und `cdpUrl` automatisch zu; setzen Sie `cdpUrl` nur explizit für Remote-CDP. -- Reihenfolge der automatischen Erkennung: Standardbrowser, wenn Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Control-Service: nur loopback (Port aus `gateway.port` abgeleitet, Standard `18791`). -- `extraArgs` hängt zusätzliche Start-Flags an den lokalen Chromium-Start an (zum Beispiel `--disable-gpu`, Fenstergrößen oder Debug-Flags). + Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` erkennen soll; verwenden Sie WS(S), + wenn Ihr Provider Ihnen eine direkte DevTools-WebSocket-URL gibt. +- `existing-session`-Profile sind nur für den Host und verwenden Chrome MCP statt CDP. +- `existing-session`-Profile können `userDataDir` setzen, um ein bestimmtes + Chromium-basiertes Browserprofil wie Brave oder Edge anzusteuern. +- Für `existing-session`-Profile gelten weiterhin die aktuellen Routenbeschränkungen von Chrome MCP: + snapshot-/ref-basierte Aktionen statt CSS-Selector-Targeting, Hooks für das Hochladen einzelner Dateien, keine Überschreibungen für Dialog-Timeouts, kein `wait --load networkidle` und kein + `responsebody`, PDF-Export, Download-Abfangen oder Batch-Aktionen. +- Lokal verwaltete `openclaw`-Profile weisen `cdpPort` und `cdpUrl` automatisch zu; setzen Sie + `cdpUrl` nur explizit für Remote-CDP. +- Reihenfolge der Auto-Erkennung: Standardbrowser, wenn Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Control-Service: nur loopback (Port wird aus `gateway.port` abgeleitet, Standard `18791`). +- `extraArgs` hängt zusätzliche Start-Flags an den lokalen Chromium-Start an (zum Beispiel + `--disable-gpu`, Fenstergröße oder Debug-Flags). --- @@ -2828,13 +2997,13 @@ Siehe [Plugins](/de/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // Emoji, kurzer Text, Bild-URL oder data-URI + avatar: "CB", // Emoji, Kurztext, Bild-URL oder data-URI }, }, } ``` -- `seamColor`: Akzentfarbe für die UI-Chrome der nativen App (Talk-Mode-Blasentönung usw.). +- `seamColor`: Akzentfarbe für natives App-UI-Chrome (Färbung der Talk-Mode-Blase usw.). - `assistant`: Überschreibung der Identität in der Control UI. Fällt auf die aktive Agentenidentität zurück. --- @@ -2869,9 +3038,9 @@ Siehe [Plugins](/de/tools/plugin). basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // gefährlich: absolute externe http(s)-Embed-URLs erlauben + // allowExternalEmbedUrls: false, // gefährlich: absolute externe http(s)-Embed-URLs zulassen // allowedOrigins: ["https://control.example.com"], // erforderlich für nicht-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // gefährlicher Fallback-Modus für Host-Header-Origin + // dangerouslyAllowHostHeaderOriginFallback: false, // gefährlicher Host-Header-Origin-Fallback-Modus // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2885,9 +3054,9 @@ Siehe [Plugins](/de/tools/plugin). // Optional. Standard false. allowRealIpFallback: false, tools: { - // Zusätzliche HTTP-Denys für /tools/invoke + // Zusätzliche HTTP-Verweigerungen für /tools/invoke deny: ["browser"], - // Tools aus der Standard-HTTP-Deny-Liste entfernen + // Tools aus der Standardliste der HTTP-Verweigerungen entfernen allow: ["gateway"], }, push: { @@ -2904,43 +3073,45 @@ Siehe [Plugins](/de/tools/plugin). -- `mode`: `local` (Gateway ausführen) oder `remote` (mit Remote-Gateway verbinden). Das Gateway verweigert den Start, wenn es nicht auf `local` gesetzt ist. -- `port`: einzelner multiplexter Port für WS + HTTP. Priorität: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local` (Gateway ausführen) oder `remote` (mit Remote-Gateway verbinden). Das Gateway verweigert den Start, sofern nicht `local`. +- `port`: einzelner multiplexierter Port für WS + HTTP. Priorität: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (Standard), `lan` (`0.0.0.0`), `tailnet` (nur Tailscale-IP) oder `custom`. - **Legacy-Bind-Aliase**: Verwenden Sie Bind-Modus-Werte in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), nicht Host-Aliase (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Docker-Hinweis**: Der standardmäßige `loopback`-Bind lauscht innerhalb des Containers auf `127.0.0.1`. Bei Docker-Bridge-Networking (`-p 18789:18789`) kommt der Datenverkehr auf `eth0` an, sodass das Gateway nicht erreichbar ist. Verwenden Sie `--network host` oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), damit auf allen Interfaces gelauscht wird. -- **Auth**: Standardmäßig erforderlich. Nicht-Loopback-Binds erfordern Gateway-Authentifizierung. Praktisch bedeutet das ein gemeinsames Token/Passwort oder einen identitätsbewussten Reverse-Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token. -- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- sowie Service-Installations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und `mode` nicht gesetzt ist. +- **Docker-Hinweis**: Der Standard-Bind `loopback` lauscht im Container auf `127.0.0.1`. Bei Docker-Bridge-Netzwerk (`-p 18789:18789`) kommt der Datenverkehr auf `eth0` an, daher ist das Gateway nicht erreichbar. Verwenden Sie `--network host` oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), um auf allen Interfaces zu lauschen. +- **Authentifizierung**: standardmäßig erforderlich. Nicht-Loopback-Binds erfordern Gateway-Authentifizierung. Praktisch bedeutet das ein gemeinsames Token/Passwort oder einen identitätsbewussten Reverse Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token. +- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- sowie Service-Installations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und der Modus nicht gesetzt ist. - `gateway.auth.mode: "none"`: expliziter Modus ohne Authentifizierung. Nur für vertrauenswürdige lokale loopback-Setups verwenden; dies wird absichtlich nicht in Onboarding-Prompts angeboten. -- `gateway.auth.mode: "trusted-proxy"`: delegiert die Authentifizierung an einen identitätsbewussten Reverse-Proxy und vertraut Identitäts-Headern aus `gateway.trustedProxies` (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet eine **nicht-loopback** Proxy-Quelle; Loopback-Reverse-Proxys auf demselben Host erfüllen die Anforderungen für trusted-proxy auth nicht. -- `gateway.auth.allowTailscale`: wenn `true`, können Identitäts-Header von Tailscale Serve die Authentifizierung für Control UI/WebSocket erfüllen (verifiziert über `tailscale whois`). HTTP-API-Endpunkte verwenden **nicht** diese Tailscale-Header-Authentifizierung; sie folgen stattdessen dem normalen HTTP-Auth-Modus des Gateway. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Standardmäßig `true`, wenn `tailscale.mode = "serve"` gesetzt ist. -- `gateway.auth.rateLimit`: optionaler Limiter für fehlgeschlagene Authentifizierungen. Gilt pro Client-IP und pro Auth-Bereich (Shared Secret und Device-Token werden unabhängig verfolgt). Geblockte Versuche geben `429` + `Retry-After` zurück. - - Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, clientIp}` vor dem Schreiben des Fehlers serialisiert. Gleichzeitige ungültige Versuche vom selben Client können den Limiter daher schon beim zweiten Request auslösen, statt dass beide als einfache Mismatches durchrutschen. - - `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie `false`, wenn auch Localhost-Datenverkehr bewusst dem Rate-Limit unterliegen soll (für Test-Setups oder strikte Proxy-Deployments). -- WebSocket-Authentifizierungsversuche mit Browser-Origin werden immer gedrosselt, wobei die Loopback-Ausnahme deaktiviert ist (Defense-in-Depth gegen browserbasiertes Brute-Force auf Localhost). -- Auf loopback werden diese browserbasierten Sperren pro normalisiertem `Origin`-Wert isoliert, sodass wiederholte Fehlschläge von einem Localhost-Origin nicht automatisch einen anderen Origin aussperren. -- `tailscale.mode`: `serve` (nur tailnet, loopback-Bind) oder `funnel` (öffentlich, Auth erforderlich). -- `controlUi.allowedOrigins`: explizite Browser-Origin-Allowlist für Gateway-WebSocket-Verbindungen. Erforderlich, wenn Browser-Clients von nicht-loopback Origins erwartet werden. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Host-Header-Origin-Fallback für Deployments aktiviert, die sich bewusst auf Host-Header-Origin-Richtlinien verlassen. -- `remote.transport`: `ssh` (Standard) oder `direct` (ws/wss). Bei `direct` muss `remote.url` `ws://` oder `wss://` sein. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: clientseitige Break-Glass-Überschreibung, die Klartext-`ws://` zu vertrauenswürdigen IPs in privaten Netzwerken erlaubt; standardmäßig bleibt Klartext auf loopback beschränkt. -- `gateway.remote.token` / `.password` sind Anmeldedatenfelder für Remote-Clients. Sie konfigurieren die Gateway-Authentifizierung nicht von selbst. -- `gateway.push.apns.relay.baseUrl`: Basis-HTTPS-URL für das externe APNs-Relay, das offizielle/TestFlight-iOS-Builds verwenden, nachdem sie Relay-gestützte Registrierungen an das Gateway veröffentlicht haben. Diese URL muss mit der in den iOS-Build kompilierten Relay-URL übereinstimmen. -- `gateway.push.apns.relay.timeoutMs`: Sendetimeout vom Gateway zum Relay in Millisekunden. Standardmäßig `10000`. -- Relay-gestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die gekoppelte iOS-App ruft `gateway.identity.get` ab, schließt diese Identität in die Relay-Registrierung ein und leitet dem Gateway eine registrierungsbezogene Sendeberechtigung weiter. Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: temporäre env-Überschreibungen für die obige Relay-Konfiguration. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für Entwicklung gedachter Escape Hatch für loopback-HTTP-Relay-URLs. Produktions-Relay-URLs sollten bei HTTPS bleiben. +- `gateway.auth.mode: "trusted-proxy"`: Authentifizierung an einen identitätsbewussten Reverse Proxy delegieren und Identitäts-Headern von `gateway.trustedProxies` vertrauen (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet eine **nicht-loopback**-Proxy-Quelle; Reverse Proxies auf demselben Host über loopback erfüllen die trusted-proxy-Authentifizierung nicht. +- `gateway.auth.allowTailscale`: wenn `true`, können Tailscale-Serve-Identitäts-Header die Authentifizierung für Control UI/WebSocket erfüllen (verifiziert über `tailscale whois`). HTTP-API-Endpunkte verwenden **nicht** diese Tailscale-Header-Authentifizierung; sie folgen stattdessen dem normalen HTTP-Authentifizierungsmodus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Standardmäßig `true`, wenn `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: optionaler Limiter für fehlgeschlagene Authentifizierungen. Gilt pro Client-IP und pro Authentifizierungs-Scope (gemeinsames Secret und Device-Token werden getrennt verfolgt). Geblockte Versuche geben `429` + `Retry-After` zurück. + - Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dieselbe `{scope, clientIp}` vor dem Schreiben des Fehlers serialisiert. Gleichzeitige schlechte Versuche desselben Clients können den Limiter daher beim zweiten Request auslösen, statt dass beide als einfache Mismatches durchrutschen. + - `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie `false`, wenn Sie localhost-Datenverkehr absichtlich ebenfalls ratenbegrenzen möchten (für Test-Setups oder strikte Proxy-Deployments). +- WS-Authentifizierungsversuche aus dem Browser-Origin werden immer mit deaktivierter Loopback-Ausnahme gedrosselt (Defense-in-Depth gegen browserbasierte Brute-Force-Angriffe auf localhost). +- Auf loopback werden diese browserbasierten Sperren pro normalisiertem `Origin`- + Wert isoliert, sodass wiederholte Fehler von einem localhost-Origin nicht automatisch + einen anderen Origin aussperren. +- `tailscale.mode`: `serve` (nur tailnet, loopback-Bind) oder `funnel` (öffentlich, erfordert Authentifizierung). +- `controlUi.allowedOrigins`: explizite Browser-Origin-Zulassungsliste für Gateway-WebSocket-Verbindungen. Erforderlich, wenn Browser-Clients von Nicht-Loopback-Origin erwartet werden. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Host-Header-Origin-Fallback für Deployments aktiviert, die absichtlich auf Host-Header-Origin-Richtlinien setzen. +- `remote.transport`: `ssh` (Standard) oder `direct` (ws/wss). Für `direct` muss `remote.url` `ws://` oder `wss://` sein. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: clientseitige Break-Glass-Überschreibung, die Klartext-`ws://` zu vertrauenswürdigen privaten Netzwerk-IP-Adressen erlaubt; Standard bleibt loopback-only für Klartext. +- `gateway.remote.token` / `.password` sind Zugangsdatenfelder für den Remote-Client. Sie konfigurieren die Gateway-Authentifizierung nicht selbst. +- `gateway.push.apns.relay.baseUrl`: Basis-HTTPS-URL für das externe APNs-Relay, das von offiziellen/TestFlight-iOS-Builds verwendet wird, nachdem diese Relay-gestützte Registrierungen an das Gateway veröffentlicht haben. Diese URL muss mit der in den iOS-Build einkompilierten Relay-URL übereinstimmen. +- `gateway.push.apns.relay.timeoutMs`: Timeout in Millisekunden für das Senden vom Gateway an das Relay. Standardmäßig `10000`. +- Relay-gestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die gekoppelte iOS-App ruft `gateway.identity.get` ab, schließt diese Identität in die Relay-Registrierung ein und leitet dem Gateway ein registrierungsspezifisches Senderecht weiter. Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: temporäre Env-Überschreibungen für die obige Relay-Konfiguration. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für Entwicklung gedachte Escape-Hatch für loopback-HTTP-Relay-URLs. Produktions-Relay-URLs sollten HTTPS verwenden. - `gateway.channelHealthCheckMinutes`: Intervall des Kanal-Gesundheitsmonitors in Minuten. Setzen Sie `0`, um Neustarts durch den Gesundheitsmonitor global zu deaktivieren. Standard: `5`. -- `gateway.channelStaleEventThresholdMinutes`: Schwellenwert für veraltete Sockets in Minuten. Halten Sie diesen Wert größer oder gleich `gateway.channelHealthCheckMinutes`. Standard: `30`. -- `gateway.channelMaxRestartsPerHour`: maximale Anzahl von Neustarts durch den Gesundheitsmonitor pro Kanal/Konto innerhalb einer gleitenden Stunde. Standard: `10`. -- `channels..healthMonitor.enabled`: kanalbezogenes Opt-out für Neustarts durch den Gesundheitsmonitor, während der globale Monitor aktiviert bleibt. +- `gateway.channelStaleEventThresholdMinutes`: Schwellwert für veraltete Sockets in Minuten. Halten Sie diesen Wert größer oder gleich `gateway.channelHealthCheckMinutes`. Standard: `30`. +- `gateway.channelMaxRestartsPerHour`: maximale Anzahl von Neustarts pro Kanal/Konto durch den Gesundheitsmonitor in einer gleitenden Stunde. Standard: `10`. +- `channels..healthMonitor.enabled`: Opt-out pro Kanal für Neustarts durch den Gesundheitsmonitor, während der globale Monitor aktiviert bleibt. - `channels..accounts..healthMonitor.enabled`: Überschreibung pro Konto für Multi-Account-Kanäle. Wenn gesetzt, hat sie Vorrang vor der Überschreibung auf Kanalebene. -- Lokale Gateway-Aufrufpfade können `gateway.remote.*` nur dann als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist. -- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht auflösbar sind, schlägt die Auflösung fail-closed fehl (kein Maskieren durch Remote-Fallback). -- `trustedProxies`: IPs von Reverse-Proxys, die TLS terminieren oder Header mit weitergeleiteter Client-Identität injizieren. Listen Sie nur Proxys auf, die Sie kontrollieren. Loopback-Einträge bleiben für Setups mit Proxy auf demselben Host/lokaler Erkennung gültig (zum Beispiel Tailscale Serve oder ein lokaler Reverse-Proxy), machen Loopback-Requests aber **nicht** für `gateway.auth.mode: "trusted-proxy"` geeignet. +- Lokale Gateway-Aufrufpfade können `gateway.remote.*` nur als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist. +- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht aufgelöst ist, schlägt die Auflösung fail-closed fehl (kein Remote-Fallback zur Maskierung). +- `trustedProxies`: IPs von Reverse Proxies, die TLS terminieren oder Header des weitergeleiteten Clients injizieren. Listen Sie nur Proxies auf, die Sie kontrollieren. Loopback-Einträge sind weiterhin gültig für Setups mit Proxy auf demselben Host/lokaler Erkennung (zum Beispiel Tailscale Serve oder ein lokaler Reverse Proxy), machen loopback-Requests aber **nicht** für `gateway.auth.mode: "trusted-proxy"` zulässig. - `allowRealIpFallback`: wenn `true`, akzeptiert das Gateway `X-Real-IP`, wenn `X-Forwarded-For` fehlt. Standard `false` für fail-closed-Verhalten. -- `gateway.tools.deny`: zusätzliche Tool-Namen, die für HTTP `POST /tools/invoke` blockiert werden (erweitert die Standard-Deny-Liste). -- `gateway.tools.allow`: entfernt Tool-Namen aus der Standard-HTTP-Deny-Liste. +- `gateway.tools.deny`: zusätzliche Tool-Namen, die für HTTP `POST /tools/invoke` blockiert werden (erweitert die Standardliste der Verweigerungen). +- `gateway.tools.allow`: entfernt Tool-Namen aus der Standardliste der HTTP-Verweigerungen. @@ -2952,14 +3123,14 @@ Siehe [Plugins](/de/tools/plugin). - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Leere Allowlists werden als nicht gesetzt behandelt; verwenden Sie `gateway.http.endpoints.responses.files.allowUrl=false` - und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um das Abrufen per URL zu deaktivieren. -- Optionaler Härtungs-Header für Responses: - - `gateway.http.securityHeaders.strictTransportSecurity` (nur für HTTPS-Origins setzen, die Sie kontrollieren; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Leere Zulassungslisten werden wie nicht gesetzt behandelt; verwenden Sie `gateway.http.endpoints.responses.files.allowUrl=false` + und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um das Abrufen von URLs zu deaktivieren. +- Optionaler Härtungs-Header für Antworten: + - `gateway.http.securityHeaders.strictTransportSecurity` (nur für von Ihnen kontrollierte HTTPS-Origins setzen; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolation mehrerer Instanzen +### Multi-Instance-Isolation -Führen Sie mehrere Gateways auf einem Host mit eindeutigen Ports und State-Verzeichnissen aus: +Mehrere Gateways auf einem Host mit eindeutigen Ports und Zustandsverzeichnissen ausführen: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2967,9 +3138,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Praktische Flags: `--dev` (verwendet `~/.openclaw-dev` + Port `19001`), `--profile ` (verwendet `~/.openclaw-`). +Komfortflags: `--dev` (verwendet `~/.openclaw-dev` + Port `19001`), `--profile ` (verwendet `~/.openclaw-`). -Siehe [Multiple Gateways](/de/gateway/multiple-gateways). +Siehe [Mehrere Gateways](/de/gateway/multiple-gateways). ### `gateway.tls` @@ -2988,10 +3159,10 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways). ``` - `enabled`: aktiviert TLS-Terminierung am Gateway-Listener (HTTPS/WSS) (Standard: `false`). -- `autoGenerate`: generiert automatisch ein lokales selbstsigniertes Zertifikat-/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokale/dev-Nutzung. +- `autoGenerate`: erzeugt automatisch ein lokales selbstsigniertes Zertifikat-/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokal/dev. - `certPath`: Dateisystempfad zur TLS-Zertifikatsdatei. -- `keyPath`: Dateisystempfad zur privaten TLS-Schlüsseldatei; mit eingeschränkten Berechtigungen schützen. -- `caPath`: optionaler Pfad zu einem CA-Bundle für Client-Verifikation oder benutzerdefinierte Vertrauensketteten. +- `keyPath`: Dateisystempfad zum privaten TLS-Schlüssel; Zugriffsrechte einschränken. +- `caPath`: optionaler Pfad zu einem CA-Bundle für Client-Verifizierung oder benutzerdefinierte Vertrauenskette. ### `gateway.reload` @@ -3009,10 +3180,10 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways). - `mode`: steuert, wie Konfigurationsänderungen zur Laufzeit angewendet werden. - `"off"`: Live-Änderungen ignorieren; Änderungen erfordern einen expliziten Neustart. - - `"restart"`: bei Konfigurationsänderungen immer den Gateway-Prozess neu starten. + - `"restart"`: Gateway-Prozess bei Konfigurationsänderung immer neu starten. - `"hot"`: Änderungen im Prozess anwenden, ohne neu zu starten. - - `"hybrid"` (Standard): zuerst Hot Reload versuchen; bei Bedarf auf Neustart zurückfallen. -- `debounceMs`: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nicht negativer Integer). + - `"hybrid"` (Standard): zuerst Hot-Reload versuchen; falls erforderlich auf Neustart zurückfallen. +- `debounceMs`: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nichtnegative Ganzzahl). - `deferralTimeoutMs`: maximale Wartezeit in ms auf laufende Operationen, bevor ein Neustart erzwungen wird (Standard: `300000` = 5 Minuten). --- @@ -3040,7 +3211,7 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways). wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "Von: {{messages[0].from}}\nBetreff: {{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3050,8 +3221,8 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways). } ``` -Auth: `Authorization: Bearer ` oder `x-openclaw-token: `. -Hook-Tokens in Query-Strings werden abgelehnt. +Authentifizierung: `Authorization: Bearer ` oder `x-openclaw-token: `. +Hook-Tokens in der Query-String werden abgelehnt. Hinweise zu Validierung und Sicherheit: @@ -3064,7 +3235,7 @@ Hinweise zu Validierung und Sicherheit: - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` aus dem Request-Payload wird nur akzeptiert, wenn `hooks.allowRequestSessionKey=true` gesetzt ist (Standard: `false`). + - `sessionKey` aus dem Request-Payload wird nur akzeptiert, wenn `hooks.allowRequestSessionKey=true` (Standard: `false`). - `POST /hooks/` → aufgelöst über `hooks.mappings` @@ -3075,12 +3246,12 @@ Hinweise zu Validierung und Sicherheit: - `transform` kann auf ein JS-/TS-Modul zeigen, das eine Hook-Aktion zurückgibt. - `transform.module` muss ein relativer Pfad sein und innerhalb von `hooks.transformsDir` bleiben (absolute Pfade und Traversal werden abgelehnt). - `agentId` routet an einen bestimmten Agenten; unbekannte IDs fallen auf den Standard zurück. -- `allowedAgentIds`: schränkt explizites Routing ein (`*` oder weggelassen = alle erlauben, `[]` = alle verweigern). -- `defaultSessionKey`: optionaler fester Sitzungsschlüssel für Hook-Agent-Läufe ohne explizites `sessionKey`. +- `allowedAgentIds`: beschränkt explizites Routing (`*` oder weggelassen = alle erlauben, `[]` = alle verweigern). +- `defaultSessionKey`: optionaler fester Sitzungsschlüssel für Hook-Agent-Läufe ohne expliziten `sessionKey`. - `allowRequestSessionKey`: erlaubt Aufrufern von `/hooks/agent`, `sessionKey` zu setzen (Standard: `false`). -- `allowedSessionKeyPrefixes`: optionale Präfix-Allowlist für explizite `sessionKey`-Werte (Request + Mapping), z. B. `["hook:"]`. +- `allowedSessionKeyPrefixes`: optionale Präfix-Zulassungsliste für explizite `sessionKey`-Werte (Request + Mapping), z. B. `["hook:"]`. - `deliver: true` sendet die endgültige Antwort an einen Kanal; `channel` ist standardmäßig `last`. -- `model` überschreibt das LLM für diesen Hook-Lauf (muss erlaubt sein, wenn der Modellkatalog gesetzt ist). +- `model` überschreibt das LLM für diesen Hook-Lauf (muss erlaubt sein, wenn ein Modellkatalog gesetzt ist). @@ -3127,19 +3298,19 @@ Hinweise zu Validierung und Sicherheit: - Stellt vom Agenten bearbeitbares HTML/CSS/JS und A2UI über HTTP unter dem Gateway-Port bereit: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Nur lokal: behalten Sie `gateway.bind: "loopback"` (Standard) bei. -- Nicht-Loopback-Binds: Canvas-Routen erfordern Gateway-Authentifizierung (Token/Passwort/trusted-proxy), genau wie andere HTTP-Oberflächen des Gateway. -- Node-WebViews senden typischerweise keine Auth-Header; nachdem ein Node gekoppelt und verbunden ist, veröffentlicht das Gateway nodebezogene Capability-URLs für den Zugriff auf Canvas/A2UI. -- Capability-URLs sind an die aktive Node-WS-Sitzung gebunden und laufen schnell ab. Es wird kein IP-basierter Fallback verwendet. -- Injiziert den Live-Reload-Client in ausgeliefertes HTML. -- Erstellt automatisch eine Starter-`index.html`, wenn das Verzeichnis leer ist. -- Stellt A2UI außerdem unter `/__openclaw__/a2ui/` bereit. +- Nur lokal: `gateway.bind: "loopback"` beibehalten (Standard). +- Bei Nicht-Loopback-Binds erfordern Canvas-Routen Gateway-Authentifizierung (Token/Passwort/trusted-proxy), genauso wie andere HTTP-Oberflächen des Gateways. +- Node-WebViews senden typischerweise keine Authentifizierungs-Header; nachdem ein Node gekoppelt und verbunden ist, veröffentlicht das Gateway nodebezogene Capability-URLs für den Zugriff auf Canvas/A2UI. +- Capability-URLs sind an die aktive Node-WS-Sitzung gebunden und laufen schnell ab. IP-basierter Fallback wird nicht verwendet. +- Injiziert einen Live-Reload-Client in bereitgestelltes HTML. +- Erstellt automatisch eine Starter-`index.html`, wenn leer. +- Stellt A2UI auch unter `/__openclaw__/a2ui/` bereit. - Änderungen erfordern einen Gateway-Neustart. -- Deaktivieren Sie Live Reload bei großen Verzeichnissen oder `EMFILE`-Fehlern. +- Deaktivieren Sie Live-Reload bei großen Verzeichnissen oder `EMFILE`-Fehlern. --- -## Discovery +## Erkennung ### mDNS (Bonjour) @@ -3155,9 +3326,9 @@ Hinweise zu Validierung und Sicherheit: - `minimal` (Standard): `cliPath` + `sshPort` aus TXT-Records weglassen. - `full`: `cliPath` + `sshPort` einschließen. -- Der Hostname ist standardmäßig `openclaw`. Überschreiben Sie ihn mit `OPENCLAW_MDNS_HOSTNAME`. +- Der Hostname ist standardmäßig `openclaw`. Überschreiben mit `OPENCLAW_MDNS_HOSTNAME`. -### Wide-area (DNS-SD) +### Wide-Area (DNS-SD) ```json5 { @@ -3167,7 +3338,7 @@ Hinweise zu Validierung und Sicherheit: } ``` -Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für netzwerkübergreifende Erkennung kombinieren Sie dies mit einem DNS-Server (CoreDNS empfohlen) + Tailscale Split DNS. +Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für netzwerkübergreifende Erkennung mit einem DNS-Server (CoreDNS empfohlen) + Tailscale Split DNS kombinieren. Setup: `openclaw dns setup --apply`. @@ -3175,7 +3346,7 @@ Setup: `openclaw dns setup --apply`. ## Umgebung -### `env` (Inline-Umgebungsvariablen) +### `env` (inline Env-Variablen) ```json5 { @@ -3192,14 +3363,14 @@ Setup: `openclaw dns setup --apply`. } ``` -- Inline-Umgebungsvariablen werden nur angewendet, wenn die Prozessumgebung den Schlüssel nicht enthält. -- `.env`-Dateien: CWD `.env` + `~/.openclaw/.env` (keine von beiden überschreibt vorhandene Variablen). +- Inline-Env-Variablen werden nur angewendet, wenn die Prozessumgebung den Schlüssel nicht enthält. +- `.env`-Dateien: CWD `.env` + `~/.openclaw/.env` (keine davon überschreibt bestehende Variablen). - `shellEnv`: importiert fehlende erwartete Schlüssel aus Ihrem Login-Shell-Profil. -- Die vollständige Prioritätsreihenfolge finden Sie unter [Environment](/de/help/environment). +- Vollständige Priorität siehe [Umgebung](/de/help/environment). -### Substitution von Umgebungsvariablen +### Env-Variablen-Substitution -Referenzieren Sie Umgebungsvariablen in jeder Konfigurationszeichenfolge mit `${VAR_NAME}`: +Referenzieren Sie Env-Variablen in jedem Konfigurations-String mit `${VAR_NAME}`: ```json5 { @@ -3209,9 +3380,9 @@ Referenzieren Sie Umgebungsvariablen in jeder Konfigurationszeichenfolge mit `${ } ``` -- Es werden nur Großbuchstabennamen im Muster `[A-Z_][A-Z0-9_]*` abgeglichen. -- Fehlende/leere Variablen verursachen beim Laden der Konfiguration einen Fehler. -- Mit `$${VAR}` escapen Sie ein wörtliches `${VAR}`. +- Es werden nur Großbuchstabennamen erkannt: `[A-Z_][A-Z0-9_]*`. +- Fehlende/leere Variablen werfen beim Laden der Konfiguration einen Fehler. +- Mit `$${VAR}` escapen, um ein wörtliches `${VAR}` zu erhalten. - Funktioniert mit `$include`. --- @@ -3222,7 +3393,7 @@ SecretRefs sind additiv: Klartextwerte funktionieren weiterhin. ### `SecretRef` -Verwenden Sie genau eine Objektform: +Verwenden Sie eine Objektform: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3231,15 +3402,15 @@ Verwenden Sie genau eine Objektform: Validierung: - Muster für `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- Muster für `source: "env"` bei `id`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` `id`: absoluter JSON-Zeiger (zum Beispiel `"/providers/openai/apiKey"`) -- Muster für `source: "exec"` bei `id`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- Muster für `source: "env"` id: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"` id: absoluter JSON-Pointer (zum Beispiel `"/providers/openai/apiKey"`) +- Muster für `source: "exec"` id: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` - `source: "exec"`-IDs dürfen keine slashgetrennten Pfadsegmente `.` oder `..` enthalten (zum Beispiel wird `a/../b` abgelehnt) -### Unterstützte Oberfläche für Anmeldedaten +### Unterstützte Credential-Oberfläche - Kanonische Matrix: [SecretRef Credential Surface](/de/reference/secretref-credential-surface) -- `secrets apply` zielt auf unterstützte Pfade für Anmeldedaten in `openclaw.json`. +- `secrets apply` zielt auf unterstützte Credential-Pfade in `openclaw.json`. - Refs in `auth-profiles.json` sind in Laufzeitauflösung und Audit-Abdeckung enthalten. ### Konfiguration der Secret-Provider @@ -3272,17 +3443,17 @@ Validierung: Hinweise: -- Der `file`-Provider unterstützt `mode: "json"` und `mode: "singleValue"` (`id` muss im Modus `singleValue` `"value"` sein). +- Der `file`-Provider unterstützt `mode: "json"` und `mode: "singleValue"` (`id` muss im Modus singleValue `"value"` sein). - Der `exec`-Provider erfordert einen absoluten `command`-Pfad und verwendet Protokoll-Payloads auf stdin/stdout. -- Standardmäßig werden Symlink-Befehlspfade abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zu erlauben, während der aufgelöste Zielpfad weiterhin validiert wird. -- Wenn `trustedDirs` konfiguriert ist, gilt die Prüfung auf vertrauenswürdige Verzeichnisse für den aufgelösten Zielpfad. -- Die Child-Umgebung von `exec` ist standardmäßig minimal; geben Sie benötigte Variablen explizit mit `passEnv` weiter. -- SecretRefs werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst; Request-Pfade lesen danach nur noch aus diesem Snapshot. -- Beim Aktivieren wird Active-Surface-Filtering angewendet: nicht aufgelöste Refs auf aktiven Oberflächen führen zu fehlschlagendem Startup/Reload, während inaktive Oberflächen mit Diagnosen übersprungen werden. +- Standardmäßig werden symbolische Linkpfade für Befehle abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zuzulassen und dabei den aufgelösten Zielpfad zu validieren. +- Wenn `trustedDirs` konfiguriert ist, gilt die Trusted-Dir-Prüfung für den aufgelösten Zielpfad. +- Die Child-Umgebung von `exec` ist standardmäßig minimal; übergeben Sie benötigte Variablen explizit mit `passEnv`. +- SecretRefs werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst; Request-Pfade lesen anschließend nur noch aus diesem Snapshot. +- Während der Aktivierung gilt aktive-Oberflächen-Filterung: Nicht aufgelöste Refs auf aktiven Oberflächen lassen Start/Reload fehlschlagen, während inaktive Oberflächen mit Diagnosen übersprungen werden. --- -## Speicherung der Authentifizierung +## Auth-Speicher ```json5 { @@ -3301,12 +3472,12 @@ Hinweise: ``` - Profile pro Agent werden unter `/auth-profiles.json` gespeichert. -- `auth-profiles.json` unterstützt Refs auf Wertebene (`keyRef` für `api_key`, `tokenRef` für `token`) für statische Anmeldedatenmodi. -- OAuth-Modus-Profile (`auth.profiles..mode = "oauth"`) unterstützen keine SecretRef-gestützten Anmeldedaten in Auth-Profilen. -- Statische Laufzeit-Anmeldedaten stammen aus aufgelösten In-Memory-Snapshots; Legacy-statische Einträge in `auth.json` werden beim Auffinden bereinigt. -- Legacy-OAuth-Importe kommen aus `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` unterstützt Refs auf Wertebene (`keyRef` für `api_key`, `tokenRef` für `token`) für statische Credential-Modi. +- Profile im OAuth-Modus (`auth.profiles..mode = "oauth"`) unterstützen keine SecretRef-gestützten Credentials in Auth-Profilen. +- Statische Laufzeit-Credentials stammen aus aufgelösten In-Memory-Snapshots; Legacy-statische Einträge in `auth.json` werden bereinigt, wenn sie entdeckt werden. +- Legacy-OAuth-Importe aus `~/.openclaw/credentials/oauth.json`. - Siehe [OAuth](/de/concepts/oauth). -- Secrets-Laufzeitverhalten sowie Werkzeuge `audit/configure/apply`: [Secrets Management](/de/gateway/secrets). +- Laufzeitverhalten von Secrets und Tooling für `audit/configure/apply`: [Secrets Management](/de/gateway/secrets). ### `auth.cooldowns` @@ -3328,15 +3499,20 @@ Hinweise: } ``` -- `billingBackoffHours`: Basis-Backoff in Stunden, wenn ein Profil wegen echter Abrechnungs-/unzureichender-Credits-Fehler fehlschlägt (Standard: `5`). Expliziter Abrechnungstext kann trotzdem hier landen, selbst bei `401`-/`403`-Antworten, anbieterbezogene Textmatcher bleiben aber auf den Anbieter beschränkt, zu dem sie gehören (zum Beispiel OpenRouter `Key limit exceeded`). Retry-fähige `402`-Nachrichten zu Nutzungsfenstern oder Ausgabenlimits für Organisationen/Workspaces bleiben stattdessen im Pfad `rate_limit`. -- `billingBackoffHoursByProvider`: optionale anbieterspezifische Überschreibungen für Billing-Backoff in Stunden. -- `billingMaxHours`: Obergrenze in Stunden für das exponentielle Wachstum des Billing-Backoff (Standard: `24`). -- `authPermanentBackoffMinutes`: Basis-Backoff in Minuten für Fehler vom Typ `auth_permanent` mit hoher Sicherheit (Standard: `10`). -- `authPermanentMaxMinutes`: Obergrenze in Minuten für das Wachstum des `auth_permanent`-Backoff (Standard: `60`). +- `billingBackoffHours`: Basis-Backoff in Stunden, wenn ein Profil aufgrund echter + Billing-/ungenügender-Credits-Fehler fehlschlägt (Standard: `5`). Expliziter Billing-Text kann + hier auch bei `401`-/`403`-Antworten landen, aber providerbezogene Text- + Matcher bleiben auf den Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter + `Key limit exceeded`). Wiederholbare `402`-Nutzungsfenster- oder + Spend-Limit-Meldungen für Organisation/Workspace bleiben stattdessen im Pfad `rate_limit`. +- `billingBackoffHoursByProvider`: optionale providerbezogene Überschreibungen für Billing-Backoff in Stunden. +- `billingMaxHours`: Obergrenze in Stunden für exponentielles Wachstum des Billing-Backoff (Standard: `24`). +- `authPermanentBackoffMinutes`: Basis-Backoff in Minuten für hochzuverlässige `auth_permanent`-Fehler (Standard: `10`). +- `authPermanentMaxMinutes`: Obergrenze in Minuten für Wachstum des `auth_permanent`-Backoff (Standard: `60`). - `failureWindowHours`: gleitendes Fenster in Stunden, das für Backoff-Zähler verwendet wird (Standard: `24`). -- `overloadedProfileRotations`: maximale Anzahl von Rotationen von Auth-Profilen desselben Anbieters bei Überlastungsfehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Formen von Anbieterüberlastung wie `ModelNotReadyException` landen hier. -- `overloadedBackoffMs`: feste Verzögerung vor einem erneuten Versuch einer Profilrotation bei überlastetem Anbieter/Profil (Standard: `0`). -- `rateLimitedProfileRotations`: maximale Anzahl von Rotationen von Auth-Profilen desselben Anbieters bei Rate-Limit-Fehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Rate-Limit-Bucket umfasst auch anbieterspezifische Texte wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`. +- `overloadedProfileRotations`: maximale Rotationen von Auth-Profilen desselben Providers bei Überlastungsfehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Provider-busy-Formen wie `ModelNotReadyException` landen hier. +- `overloadedBackoffMs`: feste Verzögerung vor erneutem Versuch einer Rotation eines überlasteten Providers/Profils (Standard: `0`). +- `rateLimitedProfileRotations`: maximale Rotationen von Auth-Profilen desselben Providers bei Rate-Limit-Fehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Rate-Limit-Bucket umfasst providergeprägte Texte wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`. --- @@ -3358,7 +3534,7 @@ Hinweise: - Standard-Logdatei: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Setzen Sie `logging.file` für einen stabilen Pfad. - `consoleLevel` wird bei `--verbose` auf `debug` erhöht. -- `maxFileBytes`: maximale Größe der Logdatei in Bytes, bevor Schreibvorgänge unterdrückt werden (positiver Integer; Standard: `524288000` = 500 MB). Verwenden Sie für Produktions-Deployments externe Logrotation. +- `maxFileBytes`: maximale Logdateigröße in Byte, bevor Schreibvorgänge unterdrückt werden (positive Ganzzahl; Standard: `524288000` = 500 MB). Verwenden Sie für Produktions-Deployments externe Logrotation. --- @@ -3395,20 +3571,20 @@ Hinweise: } ``` -- `enabled`: globaler Schalter für die Ausgabe von Instrumentierung (Standard: `true`). -- `flags`: Array aus Flag-Strings zum Aktivieren gezielter Logausgaben (unterstützt Wildcards wie `"telegram.*"` oder `"*"`). -- `stuckSessionWarnMs`: Altersschwelle in ms für die Ausgabe von Warnungen zu festhängenden Sitzungen, solange eine Sitzung im Verarbeitungszustand bleibt. +- `enabled`: zentraler Schalter für die Ausgabe von Instrumentierung (Standard: `true`). +- `flags`: Array von Flag-Strings zur Aktivierung gezielter Log-Ausgabe (unterstützt Wildcards wie `"telegram.*"` oder `"*"`). +- `stuckSessionWarnMs`: Altersschwelle in ms für die Ausgabe von Warnungen zu hängenden Sitzungen, solange eine Sitzung im Verarbeitungszustand bleibt. - `otel.enabled`: aktiviert die OpenTelemetry-Exportpipeline (Standard: `false`). - `otel.endpoint`: Collector-URL für den OTel-Export. - `otel.protocol`: `"http/protobuf"` (Standard) oder `"grpc"`. - `otel.headers`: zusätzliche HTTP-/gRPC-Metadaten-Header, die mit OTel-Export-Requests gesendet werden. -- `otel.serviceName`: Dienstname für Ressourcenattribute. -- `otel.traces` / `otel.metrics` / `otel.logs`: aktiviert den Export von Traces, Metriken oder Logs. -- `otel.sampleRate`: Sampling-Rate für Traces `0`–`1`. +- `otel.serviceName`: Service-Name für Ressourcenattribute. +- `otel.traces` / `otel.metrics` / `otel.logs`: Export von Traces, Metriken oder Logs aktivieren. +- `otel.sampleRate`: Trace-Sampling-Rate `0`–`1`. - `otel.flushIntervalMs`: periodisches Flush-Intervall für Telemetrie in ms. -- `cacheTrace.enabled`: protokolliert Cache-Trace-Snapshots für eingebettete Läufe (Standard: `false`). +- `cacheTrace.enabled`: Cache-Trace-Snapshots für eingebettete Läufe protokollieren (Standard: `false`). - `cacheTrace.filePath`: Ausgabepfad für Cache-Trace-JSONL (Standard: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: steuern, was in der Cache-Trace-Ausgabe enthalten ist (alle standardmäßig: `true`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: steuern, was in die Cache-Trace-Ausgabe aufgenommen wird (alle standardmäßig: `true`). --- @@ -3431,11 +3607,11 @@ Hinweise: ``` - `channel`: Release-Kanal für npm-/Git-Installationen — `"stable"`, `"beta"` oder `"dev"`. -- `checkOnStart`: beim Start des Gateway nach npm-Updates suchen (Standard: `true`). +- `checkOnStart`: beim Start des Gateways auf npm-Updates prüfen (Standard: `true`). - `auto.enabled`: Hintergrund-Auto-Update für Paketinstallationen aktivieren (Standard: `false`). -- `auto.stableDelayHours`: minimale Verzögerung in Stunden vor automatischer Anwendung im Stable-Kanal (Standard: `6`; max: `168`). -- `auto.stableJitterHours`: zusätzliches Rollout-Streuungsfenster in Stunden für den Stable-Kanal (Standard: `12`; max: `168`). -- `auto.betaCheckIntervalHours`: wie oft Prüfungen für den Beta-Kanal in Stunden laufen (Standard: `1`; max: `24`). +- `auto.stableDelayHours`: Mindestverzögerung in Stunden vor automatischer Anwendung auf dem Stable-Kanal (Standard: `6`; max: `168`). +- `auto.stableJitterHours`: zusätzliches Verteilungsfenster in Stunden für Rollouts auf dem Stable-Kanal (Standard: `12`; max: `168`). +- `auto.betaCheckIntervalHours`: wie oft Prüfungen auf dem Beta-Kanal in Stunden laufen (Standard: `1`; max: `24`). --- @@ -3469,21 +3645,21 @@ Hinweise: ``` - `enabled`: globales ACP-Feature-Gate (Standard: `false`). -- `dispatch.enabled`: unabhängiges Gate für die Turn-Dispatch von ACP-Sitzungen (Standard: `true`). Setzen Sie `false`, um ACP-Befehle verfügbar zu halten, aber die Ausführung zu blockieren. -- `backend`: Standard-ID des ACP-Runtime-Backends (muss einem registrierten ACP-Runtime-Plugin entsprechen). -- `defaultAgent`: Fallback-Ziel-Agent-ID für ACP, wenn Spawns kein explizites Ziel angeben. -- `allowedAgents`: Allowlist von Agent-IDs, die für ACP-Runtime-Sitzungen erlaubt sind; leer bedeutet keine zusätzliche Einschränkung. +- `dispatch.enabled`: unabhängiges Gate für das Dispatching von ACP-Sitzungs-Turns (Standard: `true`). Setzen Sie `false`, um ACP-Befehle verfügbar zu halten, aber die Ausführung zu blockieren. +- `backend`: Standard-ID des ACP-Laufzeit-Backends (muss einem registrierten ACP-Laufzeit-Plugin entsprechen). +- `defaultAgent`: Fallback-Ziel-Agenten-ID für ACP, wenn Spawns kein explizites Ziel angeben. +- `allowedAgents`: Zulassungsliste von Agenten-IDs, die für ACP-Laufzeit-Sitzungen erlaubt sind; leer bedeutet keine zusätzliche Einschränkung. - `maxConcurrentSessions`: maximale Anzahl gleichzeitig aktiver ACP-Sitzungen. - `stream.coalesceIdleMs`: Idle-Flush-Fenster in ms für gestreamten Text. -- `stream.maxChunkChars`: maximale Chunk-Größe vor dem Aufteilen der gestreamten Blockprojektion. +- `stream.maxChunkChars`: maximale Chunk-Größe, bevor die Projektion gestreamter Blöcke aufgeteilt wird. - `stream.repeatSuppression`: unterdrückt wiederholte Status-/Tool-Zeilen pro Turn (Standard: `true`). - `stream.deliveryMode`: `"live"` streamt inkrementell; `"final_only"` puffert bis zu terminalen Turn-Ereignissen. - `stream.hiddenBoundarySeparator`: Trennzeichen vor sichtbarem Text nach verborgenen Tool-Ereignissen (Standard: `"paragraph"`). -- `stream.maxOutputChars`: maximale Anzahl projizierter Assistant-Ausgabezeichen pro ACP-Turn. -- `stream.maxSessionUpdateChars`: maximale Anzahl Zeichen für projizierte ACP-Status-/Update-Zeilen. +- `stream.maxOutputChars`: maximale Anzahl von Zeichen der Assistant-Ausgabe, die pro ACP-Turn projiziert werden. +- `stream.maxSessionUpdateChars`: maximale Anzahl von Zeichen für projizierte ACP-Status-/Update-Zeilen. - `stream.tagVisibility`: Zuordnung von Tag-Namen zu booleschen Sichtbarkeitsüberschreibungen für gestreamte Ereignisse. - `runtime.ttlMinutes`: Idle-TTL in Minuten für ACP-Sitzungs-Worker, bevor sie für die Bereinigung infrage kommen. -- `runtime.installCommand`: optionaler Installationsbefehl, der beim Bootstrap einer ACP-Runtime-Umgebung ausgeführt wird. +- `runtime.installCommand`: optionaler Installationsbefehl, der beim Bootstrap einer ACP-Laufzeitumgebung ausgeführt wird. --- @@ -3500,16 +3676,16 @@ Hinweise: ``` - `cli.banner.taglineMode` steuert den Stil des Banner-Slogans: - - `"random"` (Standard): rotierende lustige/saisonale Slogans. + - `"random"` (Standard): rotierende witzige/saisonale Slogans. - `"default"`: fester neutraler Slogan (`All your chats, one OpenClaw.`). - `"off"`: kein Slogantext (Banner-Titel/Version werden weiterhin angezeigt). -- Um das gesamte Banner auszublenden (nicht nur Slogans), setzen Sie die Umgebungsvariable `OPENCLAW_HIDE_BANNER=1`. +- Um das gesamte Banner auszublenden (nicht nur die Slogans), setzen Sie die Env-Variable `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Von CLI-geführten Setup-Abläufen (`onboard`, `configure`, `doctor`) geschriebene Metadaten: +Metadaten, die von CLI-gestützten Setup-Abläufen geschrieben werden (`onboard`, `configure`, `doctor`): ```json5 { @@ -3527,7 +3703,7 @@ Von CLI-geführten Setup-Abläufen (`onboard`, `configure`, `doctor`) geschriebe ## Identität -Siehe `agents.list`-Identitätsfelder unter [Agent-Standards](#agent-defaults). +Siehe Identitätsfelder in `agents.list` unter [Agenten-Standardwerte](#agent-defaults). --- @@ -3566,17 +3742,17 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über webhookToken: "replace-with-dedicated-token", // optionales Bearer-Token für ausgehende Webhook-Authentifizierung sessionRetention: "24h", // Dauer-String oder false runLog: { - maxBytes: "2mb", // Standard 2_000_000 Bytes + maxBytes: "2mb", // Standard 2_000_000 Byte keepLines: 2000, // Standard 2000 }, }, } ``` -- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Run-Sitzungen aufbewahrt werden, bevor sie aus `sessions.json` entfernt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; setzen Sie `false`, um dies zu deaktivieren. -- `runLog.maxBytes`: maximale Größe pro Run-Log-Datei (`cron/runs/.jsonl`) vor der Bereinigung. Standard: `2_000_000` Bytes. +- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Run-Sitzungen aufbewahrt werden, bevor sie aus `sessions.json` bereinigt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; setzen Sie `false`, um zu deaktivieren. +- `runLog.maxBytes`: maximale Größe pro Run-Log-Datei (`cron/runs/.jsonl`) vor der Bereinigung. Standard: `2_000_000` Byte. - `runLog.keepLines`: neueste Zeilen, die beibehalten werden, wenn die Bereinigung des Run-Logs ausgelöst wird. Standard: `2000`. -- `webhookToken`: Bearer-Token, das für die POST-Zustellung an Cron-Webhooks verwendet wird (`delivery.mode = "webhook"`); wenn nicht gesetzt, wird kein Auth-Header gesendet. +- `webhookToken`: Bearer-Token, das für die POST-Zustellung von Cron-Webhooks (`delivery.mode = "webhook"`) verwendet wird; wenn weggelassen, wird kein Authentifizierungs-Header gesendet. - `webhook`: veraltete Legacy-Fallback-Webhook-URL (http/https), die nur für gespeicherte Jobs verwendet wird, die noch `notify: true` haben. ### `cron.retry` @@ -3593,9 +3769,9 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über } ``` -- `maxAttempts`: maximale Anzahl von Wiederholungsversuchen für One-Shot-Jobs bei transienten Fehlern (Standard: `3`; Bereich: `0`–`10`). +- `maxAttempts`: maximale Wiederholungen für One-Shot-Jobs bei transienten Fehlern (Standard: `3`; Bereich: `0`–`10`). - `backoffMs`: Array von Backoff-Verzögerungen in ms für jeden Wiederholungsversuch (Standard: `[30000, 60000, 300000]`; 1–10 Einträge). -- `retryOn`: Fehlertypen, die Wiederholungen auslösen — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Weglassen, um alle transienten Typen zu wiederholen. +- `retryOn`: Fehlertypen, die Wiederholungen auslösen — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Weglassen, um alle transienten Typen erneut zu versuchen. Gilt nur für One-Shot-Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fehlerbehandlung. @@ -3615,11 +3791,11 @@ Gilt nur für One-Shot-Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fe } ``` -- `enabled`: Fehlermeldungen für Cron-Jobs aktivieren (Standard: `false`). -- `after`: aufeinanderfolgende Fehler, bevor eine Meldung ausgelöst wird (positiver Integer, min: `1`). -- `cooldownMs`: minimale Millisekunden zwischen wiederholten Meldungen für denselben Job (nicht negativer Integer). -- `mode`: Zustellmodus — `"announce"` sendet per Kanalnachricht; `"webhook"` postet an den konfigurierten Webhook. -- `accountId`: optionale Konto- oder Kanal-ID, um die Zustellung der Meldung zu begrenzen. +- `enabled`: Fehlerwarnungen für Cron-Jobs aktivieren (Standard: `false`). +- `after`: aufeinanderfolgende Fehler, bevor eine Warnung ausgelöst wird (positive Ganzzahl, min: `1`). +- `cooldownMs`: minimale Millisekunden zwischen wiederholten Warnungen für denselben Job (nichtnegative Ganzzahl). +- `mode`: Zustellmodus — `"announce"` sendet über eine Kanalnachricht; `"webhook"` postet an den konfigurierten Webhook. +- `accountId`: optionale Konto- oder Kanal-ID, um die Zustellung der Warnung einzugrenzen. ### `cron.failureDestination` @@ -3636,16 +3812,16 @@ Gilt nur für One-Shot-Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fe } ``` -- Standardziel für Fehlermeldungen von Cron-Jobs über alle Jobs hinweg. +- Standardziel für Cron-Fehlerbenachrichtigungen über alle Jobs hinweg. - `mode`: `"announce"` oder `"webhook"`; standardmäßig `"announce"`, wenn genügend Zieldaten vorhanden sind. -- `channel`: Kanalüberschreibung für announce-Zustellung. `"last"` verwendet den zuletzt bekannten Zustellkanal wieder. +- `channel`: Kanalüberschreibung für die Zustellung per announce. `"last"` verwendet den zuletzt bekannten Zustellkanal erneut. - `to`: explizites announce-Ziel oder Webhook-URL. Für den Webhook-Modus erforderlich. - `accountId`: optionale Kontoüberschreibung für die Zustellung. - `delivery.failureDestination` pro Job überschreibt diesen globalen Standard. -- Wenn weder global noch pro Job ein Fehlerziel gesetzt ist, greifen Jobs, die bereits per `announce` zustellen, bei Fehlern auf dieses primäre announce-Ziel zurück. -- `delivery.failureDestination` wird nur für Jobs mit `sessionTarget="isolated"` unterstützt, es sei denn, der primäre `delivery.mode` des Jobs ist `"webhook"`. +- Wenn weder global noch pro Job ein Fehlerziel gesetzt ist, fallen Jobs, die bereits über `announce` zustellen, im Fehlerfall auf dieses primäre announce-Ziel zurück. +- `delivery.failureDestination` wird nur für Jobs mit `sessionTarget="isolated"` unterstützt, sofern der primäre `delivery.mode` des Jobs nicht `"webhook"` ist. -Siehe [Cron Jobs](/de/automation/cron-jobs). Isolierte Cron-Ausführungen werden als [background tasks](/de/automation/tasks) verfolgt. +Siehe [Cron-Jobs](/de/automation/cron-jobs). Isolierte Cron-Ausführungen werden als [Hintergrundaufgaben](/de/automation/tasks) verfolgt. --- @@ -3656,8 +3832,8 @@ Template-Platzhalter, die in `tools.media.models[].args` erweitert werden: | Variable | Beschreibung | | ------------------ | ----------------------------------------------- | | `{{Body}}` | Vollständiger eingehender Nachrichtentext | -| `{{RawBody}}` | Roher Nachrichtentext (ohne Verlaufs-/Absender-Wrapper) | -| `{{BodyStripped}}` | Nachrichtentext mit entfernten Gruppenerwähnungen | +| `{{RawBody}}` | Rohtext (ohne Verlauf-/Absender-Wrapper) | +| `{{BodyStripped}}` | Text mit entfernten Gruppenerwähnungen | | `{{From}}` | Absenderkennung | | `{{To}}` | Zielkennung | | `{{MessageSid}}` | Kanal-Nachrichten-ID | @@ -3665,22 +3841,22 @@ Template-Platzhalter, die in `tools.media.models[].args` erweitert werden: | `{{IsNewSession}}` | `"true"`, wenn eine neue Sitzung erstellt wurde | | `{{MediaUrl}}` | Pseudo-URL eingehender Medien | | `{{MediaPath}}` | Lokaler Medienpfad | -| `{{MediaType}}` | Medientyp (image/audio/document/…) | +| `{{MediaType}}` | Medientyp (Bild/Audio/Dokument/…) | | `{{Transcript}}` | Audio-Transkript | | `{{Prompt}}` | Aufgelöster Medien-Prompt für CLI-Einträge | -| `{{MaxChars}}` | Aufgelöste maximale Ausgabelänge in Zeichen für CLI-Einträge | +| `{{MaxChars}}` | Aufgelöste maximale Ausgabenzeichen für CLI-Einträge | | `{{ChatType}}` | `"direct"` oder `"group"` | | `{{GroupSubject}}` | Gruppenbetreff (best effort) | -| `{{GroupMembers}}` | Vorschau auf Gruppenmitglieder (best effort) | +| `{{GroupMembers}}` | Vorschau der Gruppenmitglieder (best effort) | | `{{SenderName}}` | Anzeigename des Absenders (best effort) | | `{{SenderE164}}` | Telefonnummer des Absenders (best effort) | -| `{{Provider}}` | Anbieterhinweis (whatsapp, telegram, discord usw.) | +| `{{Provider}}` | Provider-Hinweis (whatsapp, telegram, discord usw.) | --- ## Konfigurations-Includes (`$include`) -Teilen Sie die Konfiguration in mehrere Dateien auf: +Konfiguration in mehrere Dateien aufteilen: ```json5 // ~/.openclaw/openclaw.json @@ -3695,13 +3871,13 @@ Teilen Sie die Konfiguration in mehrere Dateien auf: **Merge-Verhalten:** -- Einzelne Datei: ersetzt das enthaltende Objekt. -- Array von Dateien: wird in Reihenfolge tief zusammengeführt (spätere überschreiben frühere). -- Benachbarte Schlüssel: werden nach den Includes zusammengeführt (überschreiben inkludierte Werte). +- Einzelne Datei: ersetzt das umgebende Objekt. +- Array von Dateien: wird in Reihenfolge deep-merged (spätere überschreiben frühere). +- Geschwisterschlüssel: werden nach Includes zusammengeführt (überschreiben inkludierte Werte). - Verschachtelte Includes: bis zu 10 Ebenen tief. -- Pfade: werden relativ zur inkludierenden Datei aufgelöst, müssen aber innerhalb des Konfigurationsverzeichnisses der obersten Ebene bleiben (`dirname` von `openclaw.json`). Absolute Formen/`../` sind nur erlaubt, wenn sie sich dennoch innerhalb dieser Grenze auflösen. +- Pfade: werden relativ zur inkludierenden Datei aufgelöst, müssen aber innerhalb des Top-Level-Konfigurationsverzeichnisses bleiben (`dirname` von `openclaw.json`). Absolute Formen/`../` sind nur erlaubt, wenn sie weiterhin innerhalb dieser Grenze aufgelöst werden. - Fehler: klare Meldungen für fehlende Dateien, Parse-Fehler und zirkuläre Includes. --- -_Verwandt: [Configuration](/de/gateway/configuration) · [Configuration Examples](/de/gateway/configuration-examples) · [Doctor](/de/gateway/doctor)_ +_Verwandt: [Konfiguration](/de/gateway/configuration) · [Konfigurationsbeispiele](/de/gateway/configuration-examples) · [Doctor](/de/gateway/doctor)_ diff --git a/docs/de/plugins/sdk-channel-plugins.md b/docs/de/plugins/sdk-channel-plugins.md index 6a2e03065..b11c04c69 100644 --- a/docs/de/plugins/sdk-channel-plugins.md +++ b/docs/de/plugins/sdk-channel-plugins.md @@ -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. - 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. ## 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..accounts..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..accounts..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 - 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): ```json package.json @@ -286,7 +285,7 @@ Die älteren Hilfsfunktionen `resolveMentionGating*` bleiben auf - 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 }); ``` - - Statt Low-Level-Adapter-Interfaces manuell zu implementieren, übergeben Sie + + 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. - + 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. - + 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. + 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 ``` - 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. - + 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 -- /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). @@ -560,11 +565,11 @@ Schreiben Sie colocated Tests in `src/channel.test.ts`: └── runtime.ts # Runtime-Store (falls erforderlich) ``` -## Erweiterte Themen +## Fortgeschrittene Themen - Feste, accountbezogene oder benutzerdefinierte Antwortmodi + Feste, konto-spezifische oder benutzerdefinierte Antwortmodi describeMessageTool und Action-Erkennung @@ -578,15 +583,15 @@ Schreiben Sie colocated Tests in `src/channel.test.ts`: -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. ## 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 diff --git a/docs/de/plugins/sdk-entrypoints.md b/docs/de/plugins/sdk-entrypoints.md index 40c686336..ddeef2217 100644 --- a/docs/de/plugins/sdk-entrypoints.md +++ b/docs/de/plugins/sdk-entrypoints.md @@ -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. - **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. ## `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 `, 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 diff --git a/docs/de/plugins/sdk-runtime.md b/docs/de/plugins/sdk-runtime.md index ec84683e1..57444f756 100644 --- a/docs/de/plugins/sdk-runtime.md +++ b/docs/de/plugins/sdk-runtime.md @@ -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. - **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. ```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({ ``` - 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..subagent.allowModelOverride: true` in der Konfiguration. Nicht vertrauenswürdige Plugins können weiterhin Subagents ausführen, aber Überschreibungsanfragen werden abgelehnt. ### `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). - `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. ### `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("my-plugin runtime not initialized"); +const store = createPluginRuntimeStore({ + 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` | Pluginspezifische Konfiguration aus `plugins.entries..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` | Plugin-spezifische Konfiguration aus `plugins.entries..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 diff --git a/docs/de/plugins/sdk-setup.md b/docs/de/plugins/sdk-setup.md index f2ac2b193..1993b51b0 100644 --- a/docs/de/plugins/sdk-setup.md +++ b/docs/de/plugins/sdk-setup.md @@ -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. - **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). -## 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.` -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.`-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. - 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. -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..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..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 ``` - 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. ## 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 diff --git a/docs/de/plugins/sdk-testing.md b/docs/de/plugins/sdk-testing.md index 9e012a7b4..f25f0f32e 100644 --- a/docs/de/plugins/sdk-testing.md +++ b/docs/de/plugins/sdk-testing.md @@ -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. - **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). -## 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("test runtime not set"); +const store = createPluginRuntimeStore({ + 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/` 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/` 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 -- /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 -- /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 diff --git a/docs/de/reference/token-use.md b/docs/de/reference/token-use.md index 5a1076f53..7479c0134 100644 --- a/docs/de/reference/token-use.md +++ b/docs/de/reference/token-use.md @@ -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..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.