diff --git a/docs/de/channels/discord.md b/docs/de/channels/discord.md index 5df4f2070..c0fb2d0aa 100644 --- a/docs/de/channels/discord.md +++ b/docs/de/channels/discord.md @@ -1,20 +1,20 @@ --- read_when: - - Arbeiten an Discord-Kanalfunktionen -summary: Status, Funktionen und Konfiguration der Discord-Bot-Unterstützung + - Arbeiten an Funktionen des Discord-Kanals +summary: Supportstatus, Funktionen und Konfiguration für Discord-Bots title: Discord x-i18n: - generated_at: "2026-04-06T03:08:00Z" + generated_at: "2026-04-09T01:29:47Z" model: gpt-5.4 provider: openai - source_hash: 54af2176a1b4fa1681e3f07494def0c652a2730165058848000e71a59e2a9d08 + source_hash: 3cd2886fad941ae2129e681911309539e9a65a2352b777b538d7f4686a68f73f source_path: channels/discord.md workflow: 15 --- # Discord (Bot API) -Status: bereit für DMs und Guild-Kanäle über das offizielle Discord-Gateway. +Status: bereit für DMs und Serverkanäle über das offizielle Discord-Gateway. @@ -33,7 +33,7 @@ Status: bereit für DMs und Guild-Kanäle über das offizielle Discord-Gateway. Sie müssen eine neue Anwendung mit einem Bot erstellen, den Bot zu Ihrem Server hinzufügen und ihn mit OpenClaw koppeln. Wir empfehlen, Ihren Bot zu Ihrem eigenen privaten Server hinzuzufügen. Wenn Sie noch keinen haben, [erstellen Sie zuerst einen](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (wählen Sie **Create My Own > For me and my friends**). - + Gehen Sie zum [Discord Developer Portal](https://discord.com/developers/applications) und klicken Sie auf **New Application**. Geben Sie ihr einen Namen wie „OpenClaw“. Klicken Sie in der Seitenleiste auf **Bot**. Setzen Sie den **Username** auf den Namen, den Ihr OpenClaw-Agent tragen soll. @@ -44,23 +44,23 @@ Sie müssen eine neue Anwendung mit einem Bot erstellen, den Bot zu Ihrem Server Bleiben Sie auf der Seite **Bot**, scrollen Sie nach unten zu **Privileged Gateway Intents** und aktivieren Sie: - **Message Content Intent** (erforderlich) - - **Server Members Intent** (empfohlen; erforderlich für Rollen-Allowlisten und Abgleich von Namen zu IDs) - - **Presence Intent** (optional; nur für Presence-Updates erforderlich) + - **Server Members Intent** (empfohlen; erforderlich für Rollen-Allowlists und Name-zu-ID-Abgleich) + - **Presence Intent** (optional; nur für Präsenzaktualisierungen erforderlich) - + Scrollen Sie auf der Seite **Bot** wieder nach oben und klicken Sie auf **Reset Token**. - Trotz des Namens wird dadurch Ihr erstes Token erzeugt — es wird nichts „zurückgesetzt“. + Trotz des Namens wird dadurch Ihr erster Token erzeugt — es wird nichts „zurückgesetzt“. - Kopieren Sie das Token und speichern Sie es an einem sicheren Ort. Das ist Ihr **Bot Token**, und Sie werden es gleich benötigen. + Kopieren Sie den Token und speichern Sie ihn irgendwo. Dies ist Ihr **Bot Token**, und Sie werden ihn gleich benötigen. - + Klicken Sie in der Seitenleiste auf **OAuth2**. Sie erzeugen eine Einladungs-URL mit den richtigen Berechtigungen, um den Bot zu Ihrem Server hinzuzufügen. Scrollen Sie nach unten zu **OAuth2 URL Generator** und aktivieren Sie: @@ -68,7 +68,7 @@ Sie müssen eine neue Anwendung mit einem Bot erstellen, den Bot zu Ihrem Server - `bot` - `applications.commands` - Darunter erscheint ein Abschnitt **Bot Permissions**. Aktivieren Sie: + Darunter wird ein Abschnitt **Bot Permissions** angezeigt. Aktivieren Sie: - View Channels - Send Messages @@ -77,7 +77,7 @@ Sie müssen eine neue Anwendung mit einem Bot erstellen, den Bot zu Ihrem Server - Attach Files - Add Reactions (optional) - Kopieren Sie die unten erzeugte URL, fügen Sie sie in Ihren Browser ein, wählen Sie Ihren Server aus und klicken Sie auf **Continue**, um die Verbindung herzustellen. Sie sollten Ihren Bot nun auf dem Discord-Server sehen. + Kopieren Sie die unten erzeugte URL, fügen Sie sie in Ihren Browser ein, wählen Sie Ihren Server aus und klicken Sie auf **Continue**, um die Verbindung herzustellen. Sie sollten Ihren Bot jetzt auf dem Discord-Server sehen. @@ -85,22 +85,22 @@ Sie müssen eine neue Anwendung mit einem Bot erstellen, den Bot zu Ihrem Server Zurück in der Discord-App müssen Sie den Developer Mode aktivieren, damit Sie interne IDs kopieren können. 1. Klicken Sie auf **User Settings** (Zahnradsymbol neben Ihrem Avatar) → **Advanced** → aktivieren Sie **Developer Mode** - 2. Klicken Sie in der Seitenleiste mit der rechten Maustaste auf Ihr **Server-Symbol** → **Copy Server ID** - 3. Klicken Sie mit der rechten Maustaste auf Ihren **eigenen Avatar** → **Copy User ID** + 2. Rechtsklick auf Ihr **Serversymbol** in der Seitenleiste → **Copy Server ID** + 3. Rechtsklick auf Ihren **eigenen Avatar** → **Copy User ID** - Speichern Sie Ihre **Server ID** und **User ID** zusammen mit Ihrem Bot Token — im nächsten Schritt senden Sie alle drei an OpenClaw. + Speichern Sie Ihre **Server ID** und **User ID** zusammen mit Ihrem Bot Token — Sie senden alle drei im nächsten Schritt an OpenClaw. - Damit die Kopplung funktioniert, muss Discord Ihrem Bot erlauben, Ihnen eine DM zu senden. Klicken Sie mit der rechten Maustaste auf Ihr **Server-Symbol** → **Privacy Settings** → aktivieren Sie **Direct Messages**. + Damit die Kopplung funktioniert, muss Discord zulassen, dass Ihr Bot Ihnen eine DM senden darf. Rechtsklick auf Ihr **Serversymbol** → **Privacy Settings** → aktivieren Sie **Direct Messages**. - Dadurch können Servermitglieder (einschließlich Bots) Ihnen DMs senden. Lassen Sie dies aktiviert, wenn Sie Discord-DMs mit OpenClaw verwenden möchten. Wenn Sie nur Guild-Kanäle verwenden möchten, können Sie DMs nach der Kopplung deaktivieren. + Dadurch können Servermitglieder (einschließlich Bots) Ihnen DMs senden. Lassen Sie dies aktiviert, wenn Sie Discord-DMs mit OpenClaw verwenden möchten. Wenn Sie nur Serverkanäle verwenden möchten, können Sie DMs nach der Kopplung deaktivieren. - - Ihr Discord-Bot-Token ist ein Geheimnis (wie ein Passwort). Setzen Sie es auf dem Rechner, auf dem OpenClaw läuft, bevor Sie Ihrem Agenten Nachrichten senden. + + Ihr Discord-Bot-Token ist ein Geheimnis (wie ein Passwort). Setzen Sie ihn auf dem Rechner, auf dem OpenClaw ausgeführt wird, bevor Sie Ihrem Agenten schreiben. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -110,20 +110,20 @@ openclaw config set channels.discord.enabled true --strict-json openclaw gateway ``` - Wenn OpenClaw bereits als Hintergrunddienst läuft, starten Sie es über die OpenClaw Mac app oder durch Stoppen und erneutes Starten des Prozesses `openclaw gateway run` neu. + Wenn OpenClaw bereits als Hintergrunddienst läuft, starten Sie ihn über die OpenClaw-Mac-App neu oder indem Sie den Prozess `openclaw gateway run` stoppen und erneut starten. - - Chatten Sie mit Ihrem OpenClaw-Agenten auf einem bereits vorhandenen Kanal (z. B. Telegram) und teilen Sie ihm dies mit. Wenn Discord Ihr erster Kanal ist, verwenden Sie stattdessen den Tab CLI / config. + + Chatten Sie mit Ihrem OpenClaw-Agenten auf einem bestehenden Kanal (z. B. Telegram) und teilen Sie es ihm mit. Wenn Discord Ihr erster Kanal ist, verwenden Sie stattdessen die Registerkarte CLI / config. - > „Ich habe mein Discord-Bot-Token bereits in der Konfiguration gesetzt. Bitte schließe die Discord-Einrichtung mit der User ID `` und der Server ID `` ab.“ + > „Ich habe meinen Discord-Bot-Token bereits in der Konfiguration gesetzt. Bitte schließe die Discord-Einrichtung mit der User ID `` und der Server ID `` ab.“ - Wenn Sie eine dateibasierte Konfiguration bevorzugen, setzen Sie Folgendes: + Wenn Sie dateibasierte Konfiguration bevorzugen, setzen Sie Folgendes: ```json5 { @@ -154,10 +154,10 @@ DISCORD_BOT_TOKEN=... - Warten Sie, bis das Gateway läuft, und senden Sie dann Ihrem Bot eine DM in Discord. Er antwortet mit einem Kopplungscode. + Warten Sie, bis das Gateway läuft, und senden Sie Ihrem Bot dann eine DM in Discord. Er antwortet mit einem Kopplungscode. - + Senden Sie den Kopplungscode auf Ihrem bestehenden Kanal an Ihren Agenten: > „Genehmige diesen Discord-Kopplungscode: ``“ @@ -174,27 +174,27 @@ openclaw pairing approve discord Kopplungscodes laufen nach 1 Stunde ab. - Sie sollten nun per DM mit Ihrem Agenten in Discord chatten können. + Sie sollten jetzt per DM in Discord mit Ihrem Agenten chatten können. -Die Token-Auflösung ist kontobewusst. Tokenwerte in der Konfiguration haben Vorrang vor dem Env-Fallback. `DISCORD_BOT_TOKEN` wird nur für das Standardkonto verwendet. -Für erweiterte ausgehende Aufrufe (message-Tool/Kanalaktionen) wird ein explizites aufrufbezogenes `token` für diesen Aufruf verwendet. Dies gilt für Sende- sowie Lese-/Probe-artige Aktionen (zum Beispiel read/search/fetch/thread/pins/permissions). Kontorichtlinie- und Wiederholungseinstellungen stammen weiterhin aus dem ausgewählten Konto im aktiven Runtime-Snapshot. +Die Token-Auflösung ist kontobewusst. Token-Werte aus der Konfiguration haben Vorrang vor dem Env-Fallback. `DISCORD_BOT_TOKEN` wird nur für das Standardkonto verwendet. +Für erweiterte ausgehende Aufrufe (message-Tool/Kanalaktionen) wird ein expliziter aufrufbezogener `token` für diesen Aufruf verwendet. Dies gilt für Sende- sowie Lese-/Probe-Aktionen (zum Beispiel read/search/fetch/thread/pins/permissions). Kontorichtlinien und Wiederholungseinstellungen stammen weiterhin aus dem ausgewählten Konto im aktiven Runtime-Snapshot. -## Empfohlen: Einen Guild-Workspace einrichten +## Empfohlen: Einen Server-Workspace einrichten -Sobald DMs funktionieren, können Sie Ihren Discord-Server als vollständigen Workspace einrichten, in dem jeder Kanal seine eigene Agentensitzung mit eigenem Kontext erhält. Das wird für private Server empfohlen, auf denen nur Sie und Ihr Bot sind. +Sobald DMs funktionieren, können Sie Ihren Discord-Server als vollständigen Workspace einrichten, in dem jeder Kanal eine eigene Agentensitzung mit eigenem Kontext erhält. Das wird für private Server empfohlen, auf denen nur Sie und Ihr Bot sind. - - Dadurch kann Ihr Agent in jedem Kanal auf Ihrem Server antworten, nicht nur in DMs. + + Dadurch kann Ihr Agent in jedem Kanal Ihres Servers antworten, nicht nur in DMs. - - > „Füge meine Discord Server ID `` zur Guild-Allowlist hinzu“ + + > „Füge meine Discord Server ID `` zur Server-Allowlist hinzu“ @@ -219,15 +219,15 @@ Sobald DMs funktionieren, können Sie Ihren Discord-Server als vollständigen Wo - - Standardmäßig antwortet Ihr Agent in Guild-Kanälen nur, wenn er per @ erwähnt wird. Für einen privaten Server möchten Sie wahrscheinlich, dass er auf jede Nachricht antwortet. + + Standardmäßig antwortet Ihr Agent in Serverkanälen nur, wenn er mit @ erwähnt wird. Für einen privaten Server möchten Sie wahrscheinlich, dass er auf jede Nachricht antwortet. - - > „Erlaube meinem Agenten, auf diesem Server zu antworten, ohne per @ erwähnt werden zu müssen“ + + > „Erlaube meinem Agenten, auf diesem Server zu antworten, ohne dass er mit @ erwähnt werden muss“ - Setzen Sie `requireMention: false` in Ihrer Guild-Konfiguration: + Setzen Sie `requireMention: false` in Ihrer Serverkonfiguration: ```json5 { @@ -248,40 +248,40 @@ Sobald DMs funktionieren, können Sie Ihren Discord-Server als vollständigen Wo - - Standardmäßig wird der Langzeitspeicher (`MEMORY.md`) nur in DM-Sitzungen geladen. Guild-Kanäle laden `MEMORY.md` nicht automatisch. + + Standardmäßig wird Langzeitspeicher (`MEMORY.md`) nur in DM-Sitzungen geladen. In Serverkanälen wird `MEMORY.md` nicht automatisch geladen. - - > „Wenn ich in Discord-Kanälen Fragen stelle, verwende memory_search oder memory_get, wenn du langfristigen Kontext aus MEMORY.md brauchst.“ + + > „Wenn ich in Discord-Kanälen Fragen stelle, verwende memory_search oder memory_get, wenn du Langzeitkontext aus MEMORY.md benötigst.“ - Wenn Sie gemeinsamen Kontext in jedem Kanal benötigen, legen Sie die stabilen Anweisungen in `AGENTS.md` oder `USER.md` ab (sie werden in jede Sitzung injiziert). Behalten Sie Langzeitnotizen in `MEMORY.md` und greifen Sie bei Bedarf mit Speicher-Tools darauf zu. + Wenn Sie in jedem Kanal gemeinsamen Kontext benötigen, legen Sie die stabilen Anweisungen in `AGENTS.md` oder `USER.md` ab (sie werden in jede Sitzung injiziert). Behalten Sie Langzeitnotizen in `MEMORY.md` und greifen Sie bei Bedarf mit Speicher-Tools darauf zu. -Erstellen Sie nun einige Kanäle auf Ihrem Discord-Server und beginnen Sie mit dem Chatten. Ihr Agent kann den Kanalnamen sehen, und jeder Kanal erhält seine eigene isolierte Sitzung — so können Sie `#coding`, `#home`, `#research` oder alles einrichten, was zu Ihrem Workflow passt. +Erstellen Sie nun einige Kanäle auf Ihrem Discord-Server und beginnen Sie zu chatten. Ihr Agent kann den Kanalnamen sehen, und jeder Kanal erhält seine eigene isolierte Sitzung — so können Sie `#coding`, `#home`, `#research` oder was auch immer zu Ihrem Workflow passt einrichten. -## Runtime-Modell +## Laufzeitmodell - Das Gateway besitzt die Discord-Verbindung. -- Antwort-Routing ist deterministisch: Eingehende Discord-Nachrichten werden an Discord zurückbeantwortet. -- Standardmäßig (`session.dmScope=main`) teilen direkte Chats die Hauptsitzung des Agenten (`agent:main:main`). -- Guild-Kanäle sind isolierte Sitzungsschlüssel (`agent::discord:channel:`). +- Die Antwortweiterleitung ist deterministisch: Eingehende Discord-Antworten gehen zurück an Discord. +- Standardmäßig (`session.dmScope=main`) teilen sich Direktchats die Hauptsitzung des Agenten (`agent:main:main`). +- Serverkanäle sind isolierte Sitzungsschlüssel (`agent::discord:channel:`). - Gruppen-DMs werden standardmäßig ignoriert (`channels.discord.dm.groupEnabled=false`). -- Native Slash-Befehle laufen in isolierten Befehlssitzungen (`agent::discord:slash:`), während weiterhin `CommandTargetSessionKey` an die geroutete Konversationssitzung übergeben wird. +- Native Slash-Befehle laufen in isolierten Befehlssitzungen (`agent::discord:slash:`), führen aber weiterhin `CommandTargetSessionKey` zur weitergeleiteten Konversationssitzung mit. -## Forum-Kanäle +## Forumskanäle Discord-Forum- und Medienkanäle akzeptieren nur Thread-Beiträge. OpenClaw unterstützt zwei Möglichkeiten, sie zu erstellen: -- Senden Sie eine Nachricht an das Forum-Elternelement (`channel:`), um automatisch einen Thread zu erstellen. Der Thread-Titel verwendet die erste nicht leere Zeile Ihrer Nachricht. -- Verwenden Sie `openclaw message thread create`, um direkt einen Thread zu erstellen. Übergeben Sie für Forum-Kanäle kein `--message-id`. +- Senden Sie eine Nachricht an das Forum-Parent (`channel:`), um automatisch einen Thread zu erstellen. Der Thread-Titel verwendet die erste nicht leere Zeile Ihrer Nachricht. +- Verwenden Sie `openclaw message thread create`, um direkt einen Thread zu erstellen. Übergeben Sie für Forumskanäle nicht `--message-id`. -Beispiel: An das Forum-Elternelement senden, um einen Thread zu erstellen +Beispiel: An das Forum-Parent senden, um einen Thread zu erstellen ```bash openclaw message send --channel discord --target channel: \ @@ -295,11 +295,11 @@ openclaw message thread create --channel discord --target channel: \ --thread-name "Topic title" --message "Body of the post" ``` -Forum-Elternelemente akzeptieren keine Discord-Komponenten. Wenn Sie Komponenten benötigen, senden Sie an den Thread selbst (`channel:`). +Forum-Parents akzeptieren keine Discord-Komponenten. Wenn Sie Komponenten benötigen, senden Sie an den Thread selbst (`channel:`). ## Interaktive Komponenten -OpenClaw unterstützt Discord-Komponenten-v2-Container für Agentennachrichten. Verwenden Sie das message-Tool mit einer `components`-Payload. Interaktionsergebnisse werden als normale eingehende Nachrichten an den Agenten zurückgeleitet und folgen den bestehenden Discord-Einstellungen für `replyToMode`. +OpenClaw unterstützt Discord-Komponenten-v2-Container für Agentennachrichten. Verwenden Sie das message-Tool mit einer `components`-Payload. Interaktionsergebnisse werden als normale eingehende Nachrichten zurück an den Agenten geleitet und folgen den vorhandenen Discord-Einstellungen für `replyToMode`. Unterstützte Blöcke: @@ -307,23 +307,23 @@ Unterstützte Blöcke: - Aktionszeilen erlauben bis zu 5 Buttons oder ein einzelnes Auswahlmenü - Auswahltypen: `string`, `user`, `role`, `mentionable`, `channel` -Standardmäßig sind Komponenten einmalig nutzbar. Setzen Sie `components.reusable=true`, um Buttons, Auswahlen und Formulare mehrfach verwendbar zu machen, bis sie ablaufen. +Standardmäßig sind Komponenten nur einmal verwendbar. Setzen Sie `components.reusable=true`, um Buttons, Auswahlen und Formulare mehrfach verwendbar zu machen, bis sie ablaufen. Um einzuschränken, wer auf einen Button klicken kann, setzen Sie `allowedUsers` auf diesem Button (Discord-Benutzer-IDs, Tags oder `*`). Wenn dies konfiguriert ist, erhalten nicht passende Benutzer eine ephemere Ablehnung. -Die Slash-Befehle `/model` und `/models` öffnen eine interaktive Modellauswahl mit Dropdowns für Provider und Modell sowie einem Schritt zum Absenden. Die Antwort der Auswahl ist ephemer, und nur der aufrufende Benutzer kann sie verwenden. +Die Slash-Befehle `/model` und `/models` öffnen einen interaktiven Modellauswähler mit Dropdowns für Provider und Modell sowie einem Schritt zum Absenden. Die Antwort des Auswählers ist ephemer, und nur der aufrufende Benutzer kann sie verwenden. Dateianhänge: -- `file`-Blöcke müssen auf eine Attachment-Referenz zeigen (`attachment://`) +- `file`-Blöcke müssen auf eine Anhangsreferenz zeigen (`attachment://`) - Stellen Sie den Anhang über `media`/`path`/`filePath` bereit (einzelne Datei); verwenden Sie `media-gallery` für mehrere Dateien -- Verwenden Sie `filename`, um den Upload-Namen zu überschreiben, wenn er mit der Attachment-Referenz übereinstimmen soll +- Verwenden Sie `filename`, um den Upload-Namen zu überschreiben, wenn er mit der Anhangsreferenz übereinstimmen soll Modale Formulare: - Fügen Sie `components.modal` mit bis zu 5 Feldern hinzu - Feldtypen: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` -- OpenClaw fügt automatisch einen Auslöser-Button hinzu +- OpenClaw fügt automatisch einen Auslöse-Button hinzu Beispiel: @@ -398,32 +398,32 @@ Beispiel: - Benannte Konten erben `channels.discord.allowFrom`, wenn ihr eigenes `allowFrom` nicht gesetzt ist. - Benannte Konten erben nicht `channels.discord.accounts.default.allowFrom`. - DM-Zielformat für die Zustellung: + DM-Zielformat für Zustellung: - `user:` - `<@id>`-Erwähnung - Reine numerische IDs sind mehrdeutig und werden abgelehnt, sofern kein expliziter Benutzer-/Kanal-Zieltyp angegeben ist. + Reine numerische IDs sind mehrdeutig und werden abgelehnt, sofern nicht explizit eine Art von Benutzer-/Kanalziel angegeben wird. - - Die Behandlung von Guilds wird durch `channels.discord.groupPolicy` gesteuert: + + Die Serverbehandlung wird durch `channels.discord.groupPolicy` gesteuert: - `open` - `allowlist` - `disabled` - Sichere Baseline, wenn `channels.discord` vorhanden ist, ist `allowlist`. + Die sichere Baseline, wenn `channels.discord` vorhanden ist, ist `allowlist`. Verhalten von `allowlist`: - - Die Guild muss `channels.discord.guilds` entsprechen (`id` bevorzugt, Slug akzeptiert) - - optionale Sender-Allowlisten: `users` (stabile IDs empfohlen) und `roles` (nur Rollen-IDs); wenn eines von beiden konfiguriert ist, sind Sender erlaubt, wenn sie `users` ODER `roles` entsprechen - - direktes Matching nach Name/Tag ist standardmäßig deaktiviert; aktivieren Sie `channels.discord.dangerouslyAllowNameMatching: true` nur als Break-Glass-Kompatibilitätsmodus - - Namen/Tags werden für `users` unterstützt, aber IDs sind sicherer; `openclaw security audit` warnt, wenn Name-/Tag-Einträge verwendet werden - - wenn für eine Guild `channels` konfiguriert ist, werden nicht aufgeführte Kanäle verweigert - - wenn eine Guild keinen `channels`-Block hat, sind alle Kanäle in dieser allowlisteten Guild erlaubt + - Der Server muss mit `channels.discord.guilds` übereinstimmen (`id` bevorzugt, Slug akzeptiert) + - optionale Absender-Allowlists: `users` (stabile IDs empfohlen) und `roles` (nur Rollen-IDs); wenn eines davon konfiguriert ist, sind Absender erlaubt, wenn sie mit `users` ODER `roles` übereinstimmen + - direkter Abgleich nach Name/Tag ist standardmäßig deaktiviert; aktivieren Sie `channels.discord.dangerouslyAllowNameMatching: true` nur als Notfall-Kompatibilitätsmodus + - Namen/Tags werden für `users` unterstützt, aber IDs sind sicherer; `openclaw security audit` warnt, wenn Namens-/Tag-Einträge verwendet werden + - wenn für einen Server `channels` konfiguriert ist, werden nicht aufgeführte Kanäle abgelehnt + - wenn ein Server keinen `channels`-Block hat, sind alle Kanäle in diesem erlaubten Server zugelassen Beispiel: @@ -449,21 +449,21 @@ Beispiel: } ``` - Wenn Sie nur `DISCORD_BOT_TOKEN` setzen und keinen `channels.discord`-Block erstellen, ist das Runtime-Fallback `groupPolicy="allowlist"` (mit einer Warnung in den Logs), auch wenn `channels.defaults.groupPolicy` auf `open` steht. + Wenn Sie nur `DISCORD_BOT_TOKEN` setzen und keinen `channels.discord`-Block erstellen, ist das Laufzeit-Fallback `groupPolicy="allowlist"` (mit einer Warnung in den Logs), selbst wenn `channels.defaults.groupPolicy` auf `open` gesetzt ist. - Guild-Nachrichten sind standardmäßig an Erwähnungen gebunden. + Nachrichten in Servern sind standardmäßig durch Erwähnungen geschützt. - Die Erkennung von Erwähnungen umfasst: + Die Erwähnungserkennung umfasst: - explizite Bot-Erwähnung - konfigurierte Erwähnungsmuster (`agents.list[].groupChat.mentionPatterns`, Fallback `messages.groupChat.mentionPatterns`) - implizites Antwort-an-Bot-Verhalten in unterstützten Fällen - `requireMention` wird pro Guild/Kanal konfiguriert (`channels.discord.guilds...`). - `ignoreOtherMentions` verwirft optional Nachrichten, die einen anderen Benutzer/eine andere Rolle erwähnen, aber nicht den Bot (ausgenommen @everyone/@here). + `requireMention` wird pro Server/Kanal konfiguriert (`channels.discord.guilds...`). + `ignoreOtherMentions` verwirft optional Nachrichten, die einen anderen Benutzer/eine andere Rolle, aber nicht den Bot erwähnen (ausgenommen @everyone/@here). Gruppen-DMs: @@ -473,9 +473,9 @@ Beispiel: -### Rollenbasiertes Agent-Routing +### Rollenbasiertes Agenten-Routing -Verwenden Sie `bindings[].match.roles`, um Discord-Guild-Mitglieder anhand der Rollen-ID an unterschiedliche Agenten zu routen. Rollenbasierte Bindings akzeptieren nur Rollen-IDs und werden nach Peer- oder Parent-Peer-Bindings und vor reinen Guild-Bindings ausgewertet. Wenn ein Binding zusätzlich andere Match-Felder setzt (zum Beispiel `peer` + `guildId` + `roles`), müssen alle konfigurierten Felder übereinstimmen. +Verwenden Sie `bindings[].match.roles`, um Discord-Servermitglieder anhand ihrer Rollen-ID an unterschiedliche Agenten weiterzuleiten. Rollenbasierte Bindings akzeptieren nur Rollen-IDs und werden nach Peer- oder Parent-Peer-Bindings und vor rein serverbasierten Bindings ausgewertet. Wenn ein Binding auch andere Match-Felder setzt (zum Beispiel `peer` + `guildId` + `roles`), müssen alle konfigurierten Felder übereinstimmen. ```json5 { @@ -511,21 +511,21 @@ Verwenden Sie `bindings[].match.roles`, um Discord-Guild-Mitglieder anhand der R - Aktivieren Sie unter **Bot -> Privileged Gateway Intents**: + Aktivieren Sie in **Bot -> Privileged Gateway Intents**: - Message Content Intent - Server Members Intent (empfohlen) - Presence Intent ist optional und nur erforderlich, wenn Sie Presence-Updates empfangen möchten. Das Setzen der Bot-Presence (`setPresence`) erfordert nicht, dass Presence-Updates für Mitglieder aktiviert sind. + Presence Intent ist optional und nur erforderlich, wenn Sie Präsenzaktualisierungen empfangen möchten. Das Setzen der Bot-Präsenz (`setPresence`) erfordert nicht, dass Präsenzaktualisierungen für Mitglieder aktiviert sind. - + OAuth-URL-Generator: - Scopes: `bot`, `applications.commands` - Typische Basisberechtigungen: + Typische grundlegende Berechtigungen: - View Channels - Send Messages @@ -534,7 +534,7 @@ Verwenden Sie `bindings[].match.roles`, um Discord-Guild-Mitglieder anhand der R - Attach Files - Add Reactions (optional) - Vermeiden Sie `Administrator`, sofern nicht ausdrücklich erforderlich. + Vermeiden Sie `Administrator`, sofern es nicht ausdrücklich benötigt wird. @@ -552,15 +552,15 @@ Verwenden Sie `bindings[].match.roles`, um Discord-Guild-Mitglieder anhand der R ## Native Befehle und Befehlsauthentifizierung -- `commands.native` hat standardmäßig den Wert `"auto"` und ist für Discord aktiviert. +- `commands.native` ist standardmäßig `"auto"` und für Discord aktiviert. - Kanalbezogene Überschreibung: `channels.discord.commands.native`. - `commands.native=false` löscht explizit zuvor registrierte native Discord-Befehle. -- Die Authentifizierung nativer Befehle verwendet dieselben Discord-Allowlisten/-Richtlinien wie die normale Nachrichtenverarbeitung. +- Die Authentifizierung nativer Befehle verwendet dieselben Discord-Allowlists/-Richtlinien wie die normale Nachrichtenverarbeitung. - Befehle können in der Discord-Benutzeroberfläche weiterhin für Benutzer sichtbar sein, die nicht autorisiert sind; die Ausführung erzwingt dennoch die OpenClaw-Authentifizierung und gibt „nicht autorisiert“ zurück. Siehe [Slash commands](/de/tools/slash-commands) für Befehlskatalog und Verhalten. -Standardmäßige Einstellungen für Slash-Befehle: +Standard-Slash-Befehlseinstellungen: - `ephemeral: true` @@ -568,7 +568,7 @@ Standardmäßige Einstellungen für Slash-Befehle: - Discord unterstützt Antwort-Tags in der Agent-Ausgabe: + Discord unterstützt Antwort-Tags in der Agentenausgabe: - `[[reply_to_current]]` - `[[reply_to:]]` @@ -580,26 +580,26 @@ Standardmäßige Einstellungen für Slash-Befehle: - `all` - `batched` - Hinweis: `off` deaktiviert implizites Antwort-Threading. Explizite Tags `[[reply_to_*]]` werden weiterhin beachtet. + Hinweis: `off` deaktiviert implizites Reply-Threading. Explizite `[[reply_to_*]]`-Tags werden weiterhin berücksichtigt. `first` hängt die implizite native Antwortreferenz immer an die erste ausgehende Discord-Nachricht des Turns an. - `batched` hängt Discords implizite native Antwortreferenz nur an, wenn der - eingehende Turn ein entprellter Stapel mehrerer Nachrichten war. Das ist nützlich, - wenn Sie native Antworten hauptsächlich für mehrdeutige, stoßweise Chats möchten, - nicht für jeden einzelnen Nachrichtenturn. + `batched` hängt Disords implizite native Antwortreferenz nur dann an, wenn der + eingehende Turn ein entprelltes Batch aus mehreren Nachrichten war. Das ist nützlich, + wenn Sie native Antworten hauptsächlich für mehrdeutige, stoßweise Chats möchten, nicht für + jeden einzelnen Turn mit nur einer Nachricht. - Nachrichten-IDs werden im Kontext/Verlauf sichtbar gemacht, sodass Agenten bestimmte Nachrichten adressieren können. + Nachrichten-IDs werden im Kontext/Verlauf offengelegt, sodass Agenten gezielt bestimmte Nachrichten adressieren können. - - OpenClaw kann Entwurfsantworten streamen, indem eine temporäre Nachricht gesendet und während des Eintreffens von Text bearbeitet wird. + + OpenClaw kann Antwortentwürfe streamen, indem eine temporäre Nachricht gesendet und beim Eintreffen von Text bearbeitet wird. - - `channels.discord.streaming` steuert das Vorschau-Streaming (`off` | `partial` | `block` | `progress`, Standard: `off`). - - Der Standard bleibt `off`, weil Discord-Vorschau-Bearbeitungen schnell an Rate Limits stoßen können, besonders wenn mehrere Bots oder Gateways dasselbe Konto oder denselben Guild-Traffic nutzen. - - `progress` wird aus Gründen der kanalübergreifenden Konsistenz akzeptiert und in Discord auf `partial` abgebildet. + - `channels.discord.streaming` steuert Vorschau-Streaming (`off` | `partial` | `block` | `progress`, Standard: `off`). + - Der Standard bleibt `off`, weil Discord-Vorschau-Bearbeitungen schnell an Ratenlimits stoßen können, insbesondere wenn mehrere Bots oder Gateways dasselbe Konto oder denselben Serververkehr teilen. + - `progress` wird zur kanalübergreifenden Konsistenz akzeptiert und in Discord auf `partial` abgebildet. - `channels.discord.streamMode` ist ein veralteter Alias und wird automatisch migriert. - - `partial` bearbeitet eine einzelne Vorschaunachricht, während Tokens eintreffen. - - `block` sendet Entwurfsblöcke in Chunk-Größe (verwenden Sie `draftChunk`, um Größe und Umbruchpunkte anzupassen). + - `partial` bearbeitet eine einzelne Vorschau-Nachricht, wenn Tokens eintreffen. + - `block` sendet Entwurfsblöcke in Chunk-Größe (verwenden Sie `draftChunk`, um Größe und Trennpunkte abzustimmen). Beispiel: @@ -630,7 +630,7 @@ Standardmäßige Einstellungen für Slash-Befehle: } ``` - Vorschau-Streaming ist nur für Text; Medienantworten fallen auf normale Zustellung zurück. + Vorschau-Streaming ist nur für Text verfügbar; Medienantworten fallen auf normale Zustellung zurück. Hinweis: Vorschau-Streaming ist vom Block-Streaming getrennt. Wenn Block-Streaming für Discord explizit aktiviert ist, überspringt OpenClaw den Vorschau-Stream, um doppeltes Streaming zu vermeiden. @@ -638,39 +638,39 @@ Standardmäßige Einstellungen für Slash-Befehle: - Guild-Verlaufskontext: + Verlaufskontext in Servern: - `channels.discord.historyLimit` Standard `20` - Fallback: `messages.groupChat.historyLimit` - `0` deaktiviert - Steuerung des DM-Verlaufs: + Steuerelemente für DM-Verlauf: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` Thread-Verhalten: - - Discord-Threads werden als Kanalsitzungen geroutet - - übergeordnete Thread-Metadaten können für Parent-Session-Verknüpfungen genutzt werden - - Thread-Konfiguration erbt die Konfiguration des übergeordneten Kanals, sofern kein threadspezifischer Eintrag existiert + - Discord-Threads werden als Kanalsitzungen weitergeleitet + - Parent-Thread-Metadaten können für eine Verknüpfung zur übergeordneten Sitzung verwendet werden + - Thread-Konfiguration erbt die Konfiguration des Parent-Kanals, sofern kein threadspezifischer Eintrag vorhanden ist Kanalthemen werden als **nicht vertrauenswürdiger** Kontext injiziert (nicht als System-Prompt). - Antwort- und Zitierte-Nachricht-Kontext bleibt derzeit wie empfangen erhalten. - Discord-Allowlisten steuern in erster Linie, wer den Agenten auslösen kann, nicht eine vollständige Redaktionsgrenze für ergänzenden Kontext. + Antwort- und Kontext aus zitierten Nachrichten bleibt derzeit wie empfangen erhalten. + Discord-Allowlists steuern in erster Linie, wer den Agenten auslösen kann, und sind keine vollständige Redaktionsgrenze für ergänzenden Kontext. - - Discord kann einen Thread an ein Sitzungsziel binden, sodass Folgebotschaften in diesem Thread weiterhin an dieselbe Sitzung geleitet werden (einschließlich Subagent-Sitzungen). + + Discord kann einen Thread an ein Sitzungsziel binden, sodass nachfolgende Nachrichten in diesem Thread weiterhin an dieselbe Sitzung weitergeleitet werden (einschließlich Subagent-Sitzungen). Befehle: - - `/focus ` bindet aktuellen/neuen Thread an ein Subagent-/Sitzungsziel + - `/focus ` bindet den aktuellen/neuen Thread an ein Subagent-/Sitzungsziel - `/unfocus` entfernt die aktuelle Thread-Bindung - `/agents` zeigt aktive Läufe und den Bindungsstatus - - `/session idle ` prüft/aktualisiert das automatische Lösen der Fokusbindung bei Inaktivität - - `/session max-age ` prüft/aktualisiert das feste maximale Alter für fokussierte Bindungen + - `/session idle ` prüft/aktualisiert das automatische Lösen des Fokus bei Inaktivität für fokussierte Bindungen + - `/session max-age ` prüft/aktualisiert das harte Maximalalter für fokussierte Bindungen Konfiguration: @@ -700,16 +700,16 @@ Standardmäßige Einstellungen für Slash-Befehle: - `session.threadBindings.*` setzt globale Standardwerte. - `channels.discord.threadBindings.*` überschreibt das Discord-Verhalten. - - `spawnSubagentSessions` muss auf true gesetzt sein, um Threads für `sessions_spawn({ thread: true })` automatisch zu erstellen/zu binden. - - `spawnAcpSessions` muss auf true gesetzt sein, um Threads für ACP (`/acp spawn ... --thread ...` oder `sessions_spawn({ runtime: "acp", thread: true })`) automatisch zu erstellen/zu binden. - - Wenn Thread-Bindings für ein Konto deaktiviert sind, sind `/focus` und verwandte Thread-Binding-Operationen nicht verfügbar. + - `spawnSubagentSessions` muss `true` sein, damit Threads für `sessions_spawn({ thread: true })` automatisch erstellt/gebunden werden. + - `spawnAcpSessions` muss `true` sein, damit Threads für ACP automatisch erstellt/gebunden werden (`/acp spawn ... --thread ...` oder `sessions_spawn({ runtime: "acp", thread: true })`). + - Wenn Thread-Bindungen für ein Konto deaktiviert sind, sind `/focus` und verwandte Operationen für Thread-Bindungen nicht verfügbar. Siehe [Sub-agents](/de/tools/subagents), [ACP Agents](/de/tools/acp-agents) und [Configuration Reference](/de/gateway/configuration-reference). - - Für stabile „always-on“-ACP-Workspaces konfigurieren Sie ACP-Bindungen auf oberster Ebene mit Typisierung, die auf Discord-Konversationen zielen. + + Für stabile „always-on“-ACP-Workspaces konfigurieren Sie ACP-Bindungen mit Typ auf oberster Ebene, die auf Discord-Konversationen zielen. Konfigurationspfad: @@ -765,27 +765,27 @@ Standardmäßige Einstellungen für Slash-Befehle: Hinweise: - - `/acp spawn codex --bind here` bindet den aktuellen Discord-Kanal oder Thread direkt und hält zukünftige Nachrichten weiterhin an dieselbe ACP-Sitzung geroutet. - - Das kann weiterhin bedeuten: „eine frische Codex-ACP-Sitzung starten“, aber es erstellt nicht von selbst einen neuen Discord-Thread. Der bestehende Kanal bleibt die Chat-Oberfläche. - - Codex kann weiterhin in seinem eigenen `cwd` oder Backend-Workspace auf der Festplatte laufen. Dieser Workspace ist Runtime-Zustand, kein Discord-Thread. - - Thread-Nachrichten können die ACP-Bindung des übergeordneten Kanals erben. - - In einem gebundenen Kanal oder Thread setzen `/new` und `/reset` dieselbe ACP-Sitzung direkt zurück. - - Temporäre Thread-Bindings funktionieren weiterhin und können die Zielauflösung überschreiben, solange sie aktiv sind. - - `spawnAcpSessions` ist nur erforderlich, wenn OpenClaw einen Child-Thread über `--thread auto|here` erstellen/binden muss. Es ist nicht erforderlich für `/acp spawn ... --bind here` im aktuellen Kanal. + - `/acp spawn codex --bind here` bindet den aktuellen Discord-Kanal oder Thread direkt vor Ort und hält zukünftige Nachrichten an dieselbe ACP-Sitzung gebunden. + - Das kann weiterhin bedeuten: „Eine frische Codex-ACP-Sitzung starten“, aber es wird dadurch nicht von selbst ein neuer Discord-Thread erstellt. Der bestehende Kanal bleibt die Chat-Oberfläche. + - Codex kann weiterhin in seinem eigenen `cwd` oder Backend-Workspace auf dem Datenträger laufen. Dieser Workspace ist Laufzeitzustand, kein Discord-Thread. + - Thread-Nachrichten können die ACP-Bindung des Parent-Kanals erben. + - In einem gebundenen Kanal oder Thread setzen `/new` und `/reset` dieselbe ACP-Sitzung direkt vor Ort zurück. + - Temporäre Thread-Bindungen funktionieren weiterhin und können die Zielauflösung überschreiben, solange sie aktiv sind. + - `spawnAcpSessions` ist nur erforderlich, wenn OpenClaw einen untergeordneten Thread über `--thread auto|here` erstellen/binden muss. Es ist nicht erforderlich für `/acp spawn ... --bind here` im aktuellen Kanal. - Siehe [ACP Agents](/de/tools/acp-agents) für Details zum Binding-Verhalten. + Siehe [ACP Agents](/de/tools/acp-agents) für Details zum Bindungsverhalten. - - Reaktionsbenachrichtigungsmodus pro Guild: + + Modus für Reaktionsbenachrichtigungen pro Server: - `off` - `own` (Standard) - `all` - `allowlist` (verwendet `guilds..users`) - Reaktionsereignisse werden in Systemereignisse umgewandelt und an die geroutete Discord-Sitzung angehängt. + Reaktionsereignisse werden in Systemereignisse umgewandelt und an die weitergeleitete Discord-Sitzung angehängt. @@ -797,19 +797,19 @@ Standardmäßige Einstellungen für Slash-Befehle: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - Fallback auf Agentenidentitäts-Emoji (`agents.list[].identity.emoji`, sonst "👀") + - Emoji-Fallback der Agentenidentität (`agents.list[].identity.emoji`, sonst "👀") Hinweise: - - Discord akzeptiert Unicode-Emoji oder benutzerdefinierte Emoji-Namen. + - Discord akzeptiert Unicode-Emojis oder benutzerdefinierte Emoji-Namen. - Verwenden Sie `""`, um die Reaktion für einen Kanal oder ein Konto zu deaktivieren. - Durch den Kanal initiierte Konfigurationsschreibvorgänge sind standardmäßig aktiviert. + Durch Kanäle initiierte Konfigurationsschreibvorgänge sind standardmäßig aktiviert. - Dies betrifft `/config set|unset`-Abläufe (wenn Befehlsfunktionen aktiviert sind). + Dies betrifft Abläufe für `/config set|unset` (wenn Befehlsfunktionen aktiviert sind). Deaktivieren: @@ -826,7 +826,7 @@ Standardmäßige Einstellungen für Slash-Befehle: - Leiten Sie Discord-Gateway-WebSocket-Traffic und Startup-REST-Lookups (Anwendungs-ID + Allowlist-Auflösung) über einen HTTP(S)-Proxy mit `channels.discord.proxy`. + Leiten Sie WebSocket-Datenverkehr des Discord-Gateways und REST-Abfragen beim Start (Anwendungs-ID + Allowlist-Auflösung) mit `channels.discord.proxy` über einen HTTP(S)-Proxy. ```json5 { @@ -857,7 +857,7 @@ Standardmäßige Einstellungen für Slash-Befehle: - Aktivieren Sie die PluralKit-Auflösung, um proxied messages der Identität von Systemmitgliedern zuzuordnen: + Aktivieren Sie die PluralKit-Auflösung, um weitergeleitete Nachrichten auf die Identität eines Systemmitglieds abzubilden: ```json5 { @@ -865,7 +865,7 @@ Standardmäßige Einstellungen für Slash-Befehle: discord: { pluralkit: { enabled: true, - token: "pk_live_...", // optional; erforderlich für private Systeme + token: "pk_live_...", // optional; für private Systeme erforderlich }, }, }, @@ -874,15 +874,15 @@ Standardmäßige Einstellungen für Slash-Befehle: Hinweise: - - Allowlisten können `pk:` verwenden + - Allowlists können `pk:` verwenden - Anzeigenamen von Mitgliedern werden nur dann nach Name/Slug abgeglichen, wenn `channels.discord.dangerouslyAllowNameMatching: true` gesetzt ist - - Lookups verwenden die ursprüngliche Nachrichten-ID und sind zeitfensterbegrenzt - - wenn der Lookup fehlschlägt, werden proxied messages als Bot-Nachrichten behandelt und verworfen, sofern nicht `allowBots=true` gesetzt ist + - Abfragen verwenden die ursprüngliche Nachrichten-ID und sind auf ein Zeitfenster begrenzt + - wenn die Abfrage fehlschlägt, werden weitergeleitete Nachrichten als Bot-Nachrichten behandelt und verworfen, sofern nicht `allowBots=true` - - Presence-Updates werden angewendet, wenn Sie ein Status- oder Aktivitätsfeld setzen oder Auto Presence aktivieren. + + Präsenzaktualisierungen werden angewendet, wenn Sie ein Status- oder Aktivitätsfeld setzen oder automatische Präsenz aktivieren. Beispiel nur für Status: @@ -896,7 +896,7 @@ Standardmäßige Einstellungen für Slash-Befehle: } ``` - Aktivitätsbeispiel (Custom Status ist der Standard-Aktivitätstyp): + Aktivitätsbeispiel (benutzerdefinierter Status ist der Standard-Aktivitätstyp): ```json5 { @@ -929,10 +929,10 @@ Standardmäßige Einstellungen für Slash-Befehle: - 1: Streaming (erfordert `activityUrl`) - 2: Listening - 3: Watching - - 4: Custom (verwendet den Aktivitätstext als Statuszustand; Emoji ist optional) + - 4: Custom (verwendet den Aktivitätstext als Statusstatus; Emoji ist optional) - 5: Competing - Beispiel für Auto Presence (Runtime-Gesundheitssignal): + Beispiel für automatische Präsenz (Signal für Laufzeitzustand): ```json5 { @@ -949,72 +949,74 @@ Standardmäßige Einstellungen für Slash-Befehle: } ``` - Auto Presence ordnet die Runtime-Verfügbarkeit dem Discord-Status zu: healthy => online, degraded oder unknown => idle, exhausted oder unavailable => dnd. Optionale Textüberschreibungen: + Die automatische Präsenz ordnet die Laufzeitverfügbarkeit dem Discord-Status zu: healthy => online, degraded oder unknown => idle, exhausted oder unavailable => dnd. Optionale Textüberschreibungen: - `autoPresence.healthyText` - `autoPresence.degradedText` - - `autoPresence.exhaustedText` (unterstützt den Platzhalter `{reason}`) + - `autoPresence.exhaustedText` (unterstützt Platzhalter `{reason}`) - Discord unterstützt button-basierte Genehmigungsverarbeitung in DMs und kann Genehmigungsaufforderungen optional im ursprünglichen Kanal veröffentlichen. + Discord unterstützt Genehmigungsabläufe auf Button-Basis in DMs und kann optional Genehmigungsaufforderungen im auslösenden Kanal veröffentlichen. Konfigurationspfad: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (optional; verwendet nach Möglichkeit `commands.ownerAllowFrom` als Fallback) + - `channels.discord.execApprovals.approvers` (optional; fällt nach Möglichkeit auf `commands.ownerAllowFrom` zurück) - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, Standard: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord aktiviert native Exec-Genehmigungen automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und mindestens ein Genehmigender aufgelöst werden kann, entweder aus `execApprovals.approvers` oder aus `commands.ownerAllowFrom`. Discord leitet Exec-Genehmigende nicht aus kanalbezogenem `allowFrom`, veraltetem `dm.allowFrom` oder Direct-Message-`defaultTo` ab. Setzen Sie `enabled: false`, um Discord explizit als nativen Genehmigungs-Client zu deaktivieren. + Discord aktiviert native Exec-Genehmigungen automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und mindestens ein Genehmiger aufgelöst werden kann, entweder aus `execApprovals.approvers` oder aus `commands.ownerAllowFrom`. Discord leitet Exec-Genehmiger nicht aus kanalbezogenem `allowFrom`, veraltetem `dm.allowFrom` oder direktem `defaultTo` für Direktnachrichten ab. Setzen Sie `enabled: false`, um Discord explizit als nativen Genehmigungs-Client zu deaktivieren. - Wenn `target` den Wert `channel` oder `both` hat, ist die Genehmigungsaufforderung im Kanal sichtbar. Nur aufgelöste Genehmigende können die Buttons verwenden; andere Benutzer erhalten eine ephemere Ablehnung. Genehmigungsaufforderungen enthalten den Befehlstext, daher sollten Sie die Zustellung im Kanal nur in vertrauenswürdigen Kanälen aktivieren. Wenn die Kanal-ID nicht aus dem Sitzungsschlüssel abgeleitet werden kann, fällt OpenClaw auf DM-Zustellung zurück. + Wenn `target` den Wert `channel` oder `both` hat, ist die Genehmigungsaufforderung im Kanal sichtbar. Nur aufgelöste Genehmiger können die Buttons verwenden; andere Benutzer erhalten eine ephemere Ablehnung. Genehmigungsaufforderungen enthalten den Befehlstext, daher sollten Sie die Zustellung im Kanal nur in vertrauenswürdigen Kanälen aktivieren. Wenn die Kanal-ID nicht aus dem Sitzungsschlüssel abgeleitet werden kann, verwendet OpenClaw stattdessen die Zustellung per DM. - Discord rendert auch die gemeinsamen Genehmigungs-Buttons, die von anderen Chat-Kanälen verwendet werden. Der native Discord-Adapter ergänzt hauptsächlich DM-Routing für Genehmigende und Kanal-Fanout. + Discord rendert auch die gemeinsamen Genehmigungsbuttons, die von anderen Chat-Kanälen verwendet werden. Der native Discord-Adapter fügt hauptsächlich das DM-Routing für Genehmiger und die Verteilung an Kanäle hinzu. Wenn diese Buttons vorhanden sind, sind sie die primäre UX für Genehmigungen; OpenClaw - sollte einen manuellen `/approve`-Befehl nur dann einfügen, wenn das Tool-Ergebnis angibt, - dass Chat-Genehmigungen nicht verfügbar sind oder die manuelle Genehmigung der einzige Weg ist. + sollte einen manuellen `/approve`-Befehl nur dann einschließen, wenn das Tool-Ergebnis angibt, + dass Chat-Genehmigungen nicht verfügbar sind oder nur eine manuelle Genehmigung möglich ist. - Die Gateway-Authentifizierung für diesen Handler verwendet denselben gemeinsamen Vertrag zur Auflösung von Anmeldedaten wie andere Gateway-Clients: + Die Gateway-Authentifizierung für diesen Handler verwendet denselben gemeinsamen Vertrag zur Anmeldedatenauflösung wie andere Gateway-Clients: - - env-first local auth (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` dann `gateway.auth.*`) - - im lokalen Modus kann `gateway.remote.*` nur dann als Fallback verwendet werden, wenn `gateway.auth.*` nicht gesetzt ist; konfigurierte, aber nicht aufgelöste lokale SecretRefs schlagen fail-closed fehl - - Unterstützung des Remote-Modus über `gateway.remote.*`, wenn anwendbar - - URL-Überschreibungen sind override-sicher: CLI-Überschreibungen verwenden keine impliziten Anmeldedaten erneut, und Env-Überschreibungen verwenden nur Env-Anmeldedaten + - env-first-lokale Authentifizierung (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` dann `gateway.auth.*`) + - im lokalen Modus kann `gateway.remote.*` nur dann als Fallback verwendet werden, wenn `gateway.auth.*` nicht gesetzt ist; konfigurierte, aber nicht aufgelöste lokale SecretRefs schlagen geschlossen fehl + - Unterstützung für den Remote-Modus über `gateway.remote.*`, wenn zutreffend + - URL-Überschreibungen sind Override-sicher: CLI-Überschreibungen verwenden keine impliziten Anmeldedaten wieder, und Env-Überschreibungen verwenden nur Env-Anmeldedaten Verhalten bei der Genehmigungsauflösung: - - IDs mit dem Präfix `plugin:` werden über `plugin.approval.resolve` aufgelöst. + - Mit `plugin:` präfixierte IDs werden über `plugin.approval.resolve` aufgelöst. - Andere IDs werden über `exec.approval.resolve` aufgelöst. - - Discord führt hier keinen zusätzlichen Exec-zu-Plugin-Fallback-Schritt aus; das ID-Präfix - entscheidet, welche Gateway-Methode aufgerufen wird. + - Discord führt hier keinen zusätzlichen Exec-zu-Plugin-Fallback durch; das + ID-Präfix entscheidet, welche Gateway-Methode aufgerufen wird. Exec-Genehmigungen laufen standardmäßig nach 30 Minuten ab. Wenn Genehmigungen mit - unbekannten Genehmigungs-IDs fehlschlagen, überprüfen Sie die Auflösung der Genehmigenden, - die Aktivierung der Funktion und dass die zugestellte Genehmigungs-ID-Art zur ausstehenden Anfrage passt. + unbekannten Genehmigungs-IDs fehlschlagen, prüfen Sie die Auflösung der Genehmiger, die Aktivierung der Funktion und + ob die zugestellte Art der Genehmigungs-ID zur ausstehenden Anfrage passt. Zugehörige Dokumentation: [Exec approvals](/de/tools/exec-approvals) -## Tools und Action-Gates +## Tools und Action Gates -Discord-Nachrichtenaktionen umfassen Messaging, Kanalverwaltung, Moderation, Presence und Metadatenaktionen. +Discord-Nachrichtenaktionen umfassen Messaging, Kanaladministration, Moderation, Präsenz und Metadatenaktionen. Zentrale Beispiele: - Messaging: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply` - Reaktionen: `react`, `reactions`, `emojiList` - Moderation: `timeout`, `kick`, `ban` -- Presence: `setPresence` +- Präsenz: `setPresence` -Action-Gates befinden sich unter `channels.discord.actions.*`. +Die Aktion `event-create` akzeptiert einen optionalen Parameter `image` (URL oder lokaler Dateipfad), um das Titelbild des geplanten Ereignisses festzulegen. + +Action Gates befinden sich unter `channels.discord.actions.*`. Standardverhalten der Gates: -| Action-Gruppe | Standard | +| Action group | Standard | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | aktiviert | | roles | deaktiviert | @@ -1023,10 +1025,10 @@ Standardverhalten der Gates: ## Components v2 UI -OpenClaw verwendet Discord components v2 für Exec-Genehmigungen und kontextübergreifende Markierungen. Discord-Nachrichtenaktionen können auch `components` für benutzerdefinierte UI akzeptieren (fortgeschritten; erfordert das Erstellen einer Komponenten-Payload über das Discord-Tool), während veraltete `embeds` weiterhin verfügbar, aber nicht empfohlen sind. +OpenClaw verwendet Discord components v2 für Exec-Genehmigungen und kanalübergreifende Markierungen. Discord-Nachrichtenaktionen können auch `components` für benutzerdefinierte UI akzeptieren (fortgeschritten; erfordert das Erstellen einer Komponenten-Payload über das Discord-Tool), während veraltete `embeds` weiterhin verfügbar sind, aber nicht empfohlen werden. -- `channels.discord.ui.components.accentColor` setzt die Akzentfarbe, die für Discord-Komponentencontainer verwendet wird (Hex). -- Pro Konto setzen mit `channels.discord.accounts..ui.components.accentColor`. +- `channels.discord.ui.components.accentColor` setzt die Akzentfarbe, die von Discord-Komponentencontainern verwendet wird (hex). +- Pro Konto mit `channels.discord.accounts..ui.components.accentColor` setzen. - `embeds` werden ignoriert, wenn components v2 vorhanden sind. Beispiel: @@ -1047,15 +1049,15 @@ Beispiel: ## Sprachkanäle -OpenClaw kann Discord-Sprachkanälen für Echtzeit- und fortlaufende Gespräche beitreten. Dies ist getrennt von Anhängen mit Sprachnachrichten. +OpenClaw kann Discord-Sprachkanälen für Echtzeitgespräche mit kontinuierlicher Interaktion beitreten. Dies ist von Anhängen mit Sprachnachrichten getrennt. Anforderungen: - Aktivieren Sie native Befehle (`commands.native` oder `channels.discord.commands.native`). - Konfigurieren Sie `channels.discord.voice`. -- Der Bot benötigt Connect- und Speak-Berechtigungen im Ziel-Sprachkanal. +- Der Bot benötigt die Berechtigungen Connect + Speak im Ziel-Sprachkanal. -Verwenden Sie den nur für Discord verfügbaren nativen Befehl `/vc join|leave|status`, um Sitzungen zu steuern. Der Befehl verwendet den Standard-Agenten des Kontos und folgt denselben Allowlist- und Group-Policy-Regeln wie andere Discord-Befehle. +Verwenden Sie den nur für Discord verfügbaren nativen Befehl `/vc join|leave|status`, um Sitzungen zu steuern. Der Befehl verwendet den Standard-Agenten des Kontos und folgt denselben Allowlist- und Gruppenrichtlinienregeln wie andere Discord-Befehle. Beispiel für automatischen Beitritt: @@ -1085,23 +1087,23 @@ Beispiel für automatischen Beitritt: Hinweise: -- `voice.tts` überschreibt `messages.tts` nur für die Sprachwiedergabe. -- Voice-Transcript-Turns leiten den Owner-Status aus Discord-`allowFrom` (oder `dm.allowFrom`) ab; Sprecher ohne Owner-Status können nicht auf owner-only Tools zugreifen (zum Beispiel `gateway` und `cron`). -- Voice ist standardmäßig aktiviert; setzen Sie `channels.discord.voice.enabled=false`, um es zu deaktivieren. +- `voice.tts` überschreibt `messages.tts` nur für die Sprachausgabe. +- Sprach-Transkript-Turns leiten den Eigentümerstatus aus Discord `allowFrom` (oder `dm.allowFrom`) ab; Sprecher ohne Eigentümerstatus können nicht auf Tools zugreifen, die nur Eigentümern vorbehalten sind (zum Beispiel `gateway` und `cron`). +- Voice ist standardmäßig aktiviert; setzen Sie `channels.discord.voice.enabled=false`, um sie zu deaktivieren. - `voice.daveEncryption` und `voice.decryptionFailureTolerance` werden an die Join-Optionen von `@discordjs/voice` durchgereicht. -- Die Standardwerte von `@discordjs/voice` sind `daveEncryption=true` und `decryptionFailureTolerance=24`, wenn nichts gesetzt ist. -- OpenClaw überwacht außerdem Entschlüsselungsfehler beim Empfang und stellt automatisch wieder her, indem der Sprachkanal nach wiederholten Fehlern in einem kurzen Zeitfenster verlassen und erneut betreten wird. -- Wenn Empfangsprotokolle wiederholt `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` anzeigen, kann dies der Upstream-Fehler von `@discordjs/voice` beim Empfang sein, der in [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) verfolgt wird. +- Die Standardwerte von `@discordjs/voice` sind `daveEncryption=true` und `decryptionFailureTolerance=24`, wenn sie nicht gesetzt sind. +- OpenClaw überwacht außerdem Entschlüsselungsfehler beim Empfang und stellt sich nach wiederholten Fehlern in einem kurzen Zeitfenster automatisch wieder her, indem der Sprachkanal verlassen und erneut betreten wird. +- Wenn Empfangslogs wiederholt `DecryptionFailed(UnencryptedWhenPassthroughDisabled)` anzeigen, könnte dies der Upstream-Receive-Bug von `@discordjs/voice` sein, der in [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) verfolgt wird. ## Sprachnachrichten -Discord-Sprachnachrichten zeigen eine Wellenformvorschau an und erfordern OGG/Opus-Audio plus Metadaten. OpenClaw erzeugt die Wellenform automatisch, benötigt dafür aber `ffmpeg` und `ffprobe`, die auf dem Gateway-Host verfügbar sein müssen, um Audiodateien zu prüfen und zu konvertieren. +Discord-Sprachnachrichten zeigen eine Wellenformvorschau an und erfordern OGG/Opus-Audio plus Metadaten. OpenClaw erzeugt die Wellenform automatisch, benötigt aber `ffmpeg` und `ffprobe`, die auf dem Gateway-Host verfügbar sein müssen, um Audiodateien zu prüfen und zu konvertieren. Anforderungen und Einschränkungen: - Geben Sie einen **lokalen Dateipfad** an (URLs werden abgelehnt). -- Lassen Sie Textinhalt weg (Discord erlaubt nicht Text + Sprachnachricht in derselben Payload). -- Jedes Audioformat wird akzeptiert; OpenClaw konvertiert bei Bedarf zu OGG/Opus. +- Lassen Sie Textinhalte weg (Discord erlaubt nicht Text + Sprachnachricht in derselben Payload). +- Jedes Audioformat wird akzeptiert; OpenClaw konvertiert bei Bedarf in OGG/Opus. Beispiel: @@ -1112,19 +1114,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Fehlerbehebung - + - Message Content Intent aktivieren - - Server Members Intent aktivieren, wenn Sie von Benutzer-/Mitgliedsauflösung abhängig sind + - Server Members Intent aktivieren, wenn Sie von Benutzer-/Mitgliederauflösung abhängen - Gateway nach Änderung der Intents neu starten - + - `groupPolicy` prüfen - - Guild-Allowlist unter `channels.discord.guilds` prüfen - - wenn die Guild-`channels`-Map existiert, sind nur aufgeführte Kanäle erlaubt + - Server-Allowlist unter `channels.discord.guilds` prüfen + - wenn eine `channels`-Zuordnung für den Server existiert, sind nur aufgelistete Kanäle erlaubt - Verhalten von `requireMention` und Erwähnungsmustern prüfen Nützliche Prüfungen: @@ -1137,16 +1139,16 @@ openclaw logs --follow - + Häufige Ursachen: - - `groupPolicy="allowlist"` ohne passende Guild-/Kanal-Allowlist + - `groupPolicy="allowlist"` ohne passende Server-/Kanal-Allowlist - `requireMention` an der falschen Stelle konfiguriert (muss unter `channels.discord.guilds` oder im Kanaleintrag stehen) - - Sender durch Guild-/Kanal-`users`-Allowlist blockiert + - Absender durch Server-/Kanal-`users`-Allowlist blockiert - + Typische Logs: @@ -1154,15 +1156,15 @@ openclaw logs --follow - `Slow listener detected ...` - `discord inbound worker timed out after ...` - Schalter für Listener-Budget: + Regler für Listener-Budget: - Einzelkonto: `channels.discord.eventQueue.listenerTimeout` - - Mehrere Konten: `channels.discord.accounts..eventQueue.listenerTimeout` + - mehrere Konten: `channels.discord.accounts..eventQueue.listenerTimeout` - Schalter für Worker-Lauf-Timeout: + Regler für Worker-Laufzeit-Timeout: - Einzelkonto: `channels.discord.inboundWorker.runTimeoutMs` - - Mehrere Konten: `channels.discord.accounts..inboundWorker.runTimeoutMs` + - mehrere Konten: `channels.discord.accounts..inboundWorker.runTimeoutMs` - Standard: `1800000` (30 Minuten); setzen Sie `0`, um zu deaktivieren Empfohlene Baseline: @@ -1186,23 +1188,23 @@ openclaw logs --follow } ``` - Verwenden Sie `eventQueue.listenerTimeout` für langsames Listener-Setup und `inboundWorker.runTimeoutMs` - nur dann, wenn Sie ein separates Sicherheitsventil für in der Warteschlange stehende Agent-Turns möchten. + Verwenden Sie `eventQueue.listenerTimeout` für langsame Listener-Einrichtung und `inboundWorker.runTimeoutMs` + nur dann, wenn Sie ein separates Sicherheitsventil für in die Warteschlange gestellte Agenten-Turns möchten. - + Berechtigungsprüfungen von `channels status --probe` funktionieren nur für numerische Kanal-IDs. - Wenn Sie Slug-Schlüssel verwenden, kann das Runtime-Matching weiterhin funktionieren, aber Probe kann die Berechtigungen nicht vollständig überprüfen. + Wenn Sie Slug-Schlüssel verwenden, kann das Runtime-Matching weiterhin funktionieren, aber die Probe kann die Berechtigungen nicht vollständig überprüfen. - + - DM deaktiviert: `channels.discord.dm.enabled=false` - DM-Richtlinie deaktiviert: `channels.discord.dmPolicy="disabled"` (veraltet: `channels.discord.dm.policy`) - - wartet auf Genehmigung der Kopplung im Modus `pairing` + - im Modus `pairing` wird auf Genehmigung der Kopplung gewartet @@ -1214,15 +1216,15 @@ openclaw logs --follow - + - - halten Sie OpenClaw aktuell (`openclaw update`), damit die Discord-Wiederherstellungslogik für Voice-Empfang vorhanden ist + - halten Sie OpenClaw aktuell (`openclaw update`), damit die Wiederherstellungslogik für den Empfang von Discord-Voice vorhanden ist - bestätigen Sie `channels.discord.voice.daveEncryption=true` (Standard) - beginnen Sie mit `channels.discord.voice.decryptionFailureTolerance=24` (Upstream-Standard) und passen Sie nur bei Bedarf an - - überwachen Sie Logs auf: + - beobachten Sie die Logs auf: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - wenn Fehler nach automatischem erneuten Beitritt weiter auftreten, sammeln Sie Logs und vergleichen Sie sie mit [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) + - wenn die Fehler nach automatischem erneuten Beitritt weiterhin auftreten, sammeln Sie Logs und vergleichen Sie sie mit [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) @@ -1239,22 +1241,22 @@ Signalstarke Discord-Felder: - Richtlinie: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` - Befehl: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` - Ereigniswarteschlange: `eventQueue.listenerTimeout` (Listener-Budget), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` -- Inbound-Worker: `inboundWorker.runTimeoutMs` +- Eingangs-Worker: `inboundWorker.runTimeoutMs` - Antwort/Verlauf: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - Zustellung: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` - Streaming: `streaming` (veralteter Alias: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` - Medien/Wiederholung: `mediaMaxMb`, `retry` - `mediaMaxMb` begrenzt ausgehende Discord-Uploads (Standard: `100MB`) - Aktionen: `actions.*` -- Presence: `activity`, `status`, `activityType`, `activityUrl` +- Präsenz: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` - Funktionen: `threadBindings`, oberstes `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` ## Sicherheit und Betrieb -- Behandeln Sie Bot-Tokens als Geheimnisse (`DISCORD_BOT_TOKEN` bevorzugt in überwachten Umgebungen). +- Behandeln Sie Bot-Tokens als Geheimnisse (`DISCORD_BOT_TOKEN` wird in überwachten Umgebungen bevorzugt). - Gewähren Sie Discord-Berechtigungen mit minimalen Rechten. -- Wenn der Bereitstellungs-/Statuszustand von Befehlen veraltet ist, starten Sie das Gateway neu und prüfen Sie erneut mit `openclaw channels status --probe`. +- Wenn der Befehlsbereitstellungs-/Statuszustand veraltet ist, starten Sie das Gateway neu und prüfen Sie mit `openclaw channels status --probe` erneut. ## Verwandt diff --git a/docs/de/channels/matrix.md b/docs/de/channels/matrix.md index e2da1cdbb..079ca4b56 100644 --- a/docs/de/channels/matrix.md +++ b/docs/de/channels/matrix.md @@ -1,30 +1,30 @@ --- read_when: - - Einrichten von Matrix in OpenClaw - - Konfigurieren von Matrix-E2EE und Verifizierung -summary: Matrix-Supportstatus, Einrichtung und Konfigurationsbeispiele + - Matrix in OpenClaw einrichten + - Matrix-E2EE und Verifizierung konfigurieren +summary: Status des Matrix-Supports, Einrichtung und Konfigurationsbeispiele title: Matrix x-i18n: - generated_at: "2026-04-08T02:16:54Z" + generated_at: "2026-04-09T01:29:59Z" model: gpt-5.4 provider: openai - source_hash: ec926df79a41fa296d63f0ec7219d0f32e075628d76df9ea490e93e4c5030f83 + source_hash: 28fc13c7620c1152200315ae69c94205da6de3180c53c814dd8ce03b5cb1758f source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix ist das gebündelte Matrix-Kanal-Plugin für OpenClaw. +Matrix ist ein gebündeltes Kanal-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 ausgeliefert, daher benötigen normale -paketierte Builds keine separate Installation. +Matrix wird in aktuellen OpenClaw-Releases als gebündeltes Plugin mitgeliefert, daher +benötigen normale paketierte Builds keine separate Installation. -Wenn Sie eine ältere Version oder eine benutzerdefinierte Installation verwenden, die Matrix ausschließt, installieren Sie -es manuell: +Wenn Sie eine ältere Build-Version oder eine benutzerdefinierte Installation verwenden, die Matrix ausschließt, installieren +Sie es manuell: Von npm installieren: @@ -32,19 +32,19 @@ Von npm installieren: openclaw plugins install @openclaw/matrix ``` -Von einem lokalen Checkout installieren: +Aus einem lokalen Checkout installieren: ```bash openclaw plugins install ./path/to/local/matrix-plugin ``` -Siehe [Plugins](/de/tools/plugin) für das Plugin-Verhalten und die Installationsregeln. +Siehe [Plugins](/de/tools/plugin) für Plugin-Verhalten und Installationsregeln. ## Einrichtung 1. Stellen Sie sicher, dass das Matrix-Plugin verfügbar ist. - - Aktuelle paketierte OpenClaw-Releases enthalten es bereits. - - Ältere/benutzerdefinierte Installationen können es manuell mit den obigen Befehlen hinzufügen. + - Aktuelle paketierte OpenClaw-Releases enthalten es bereits gebündelt. + - Ältere/benutzerdefinierte Installationen können es mit den obigen Befehlen manuell hinzufügen. 2. Erstellen Sie ein Matrix-Konto auf Ihrem Homeserver. 3. Konfigurieren Sie `channels.matrix` mit entweder: - `homeserver` + `accessToken`, oder @@ -60,39 +60,35 @@ openclaw channels add openclaw configure --section channels ``` -Wonach der Matrix-Assistent tatsächlich fragt: +Der Matrix-Assistent fragt nach: - Homeserver-URL -- Authentifizierungsmethode: Zugriffstoken oder Passwort -- Benutzer-ID nur, wenn Sie Passwortauthentifizierung auswählen -- optionaler Gerätename +- Authentifizierungsmethode: Access-Token oder Passwort +- Benutzer-ID (nur bei Passwort-Authentifizierung) +- optionalem Gerätenamen - ob E2EE aktiviert werden soll -- ob der Matrix-Raumzugriff jetzt konfiguriert werden soll -- ob der automatische Beitritt zu Matrix-Einladungen jetzt konfiguriert werden soll -- wenn der automatische Beitritt zu Einladungen aktiviert ist, ob er `allowlist`, `always` oder `off` sein soll +- ob Raumzugriff und automatischer Beitritt bei Einladungen konfiguriert werden sollen -Wichtiges Verhalten des Assistenten: +Wichtige Verhaltensweisen des Assistenten: -- Wenn für das ausgewählte Konto bereits Matrix-Auth-Umgebungsvariablen 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 Einrichtung die Authentifizierung in Umgebungsvariablen behalten kann, anstatt Geheimnisse in die Konfiguration zu kopieren. -- Wenn Sie interaktiv ein weiteres Matrix-Konto hinzufügen, wird der eingegebene Kontoname in die Konto-ID normalisiert, die in Konfiguration und Umgebungsvariablen verwendet wird. Beispielsweise wird aus `Ops Bot` `ops-bot`. -- Abfragen für DM-Zulassungslisten akzeptieren sofort vollständige `@user:server`-Werte. Anzeigenamen funktionieren nur, wenn die Live-Verzeichnissuche genau einen Treffer findet; andernfalls fordert der Assistent Sie auf, es mit einer vollständigen Matrix-ID erneut zu versuchen. -- Abfragen für Raum-Zulassungslisten akzeptieren Raum-IDs und Aliase direkt. Sie können auch Namen beigetretener Räume live auflösen, aber nicht aufgelöste Namen werden bei der Einrichtung nur wie eingegeben beibehalten und später von der Laufzeitauflösung der Zulassungsliste ignoriert. Bevorzugen Sie `!room:server` oder `#alias:server`. -- Der Assistent zeigt jetzt vor dem Schritt zum automatischen Beitritt bei Einladungen eine ausdrückliche Warnung an, da `channels.matrix.autoJoin` standardmäßig auf `off` steht; Agents treten eingeladenen Räumen oder neuen Einladungen im DM-Stil nicht bei, wenn Sie dies nicht festlegen. -- Im Zulassungslistenmodus für automatischen Beitritt bei Einladungen verwenden Sie nur stabile Einladungsziele: `!roomId:server`, `#alias:server` oder `*`. Einfache Raumnamen werden abgelehnt. -- Die Laufzeitidentität von Raum/Sitzung verwendet die stabile Matrix-Raum-ID. Im Raum deklarierte Aliase werden nur als Suchparameter verwendet, nicht als langfristiger Sitzungsschlüssel oder stabile Gruppenidentität. +- 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, damit die Authentifizierung in Umgebungsvariablen bleibt. +- Kontonamen werden zur Konto-ID normalisiert. Zum Beispiel wird `Ops Bot` zu `ops-bot`. +- DM-Allowlist-Einträge akzeptieren direkt `@user:server`; Anzeigenamen funktionieren nur, wenn die Live-Verzeichnissuche genau einen Treffer findet. +- Raum-Allowlist-Einträge akzeptieren direkt Raum-IDs und Aliasse. Bevorzugen Sie `!room:server` oder `#alias:server`; nicht aufgelöste Namen werden zur Laufzeit bei der Allowlist-Auflösung ignoriert. +- Im Allowlist-Modus für automatischen Beitritt bei Einladungen verwenden Sie nur stabile Einladungsziele: `!roomId:server`, `#alias:server` oder `*`. Einfache Raumnamen werden abgelehnt. - Um Raumnamen vor dem Speichern aufzulösen, verwenden Sie `openclaw channels resolve --channel matrix "Project Room"`. -`channels.matrix.autoJoin` ist standardmäßig `off`. +`channels.matrix.autoJoin` ist standardmäßig auf `off` gesetzt. -Wenn Sie es nicht setzen, tritt der Bot eingeladenen Räumen oder neuen Einladungen im DM-Stil nicht bei, sodass er nicht in neuen Gruppen oder eingeladenen DMs erscheint, sofern Sie nicht zuerst manuell beitreten. +Wenn Sie es nicht setzen, tritt der Bot eingeladenen Räumen oder neuen DM-artigen Einladungen nicht bei, sodass er in neuen Gruppen oder eingeladenen DMs nicht erscheint, sofern Sie nicht zuerst manuell beitreten. Setzen Sie `autoJoin: "allowlist"` zusammen mit `autoJoinAllowlist`, um einzuschränken, welche Einladungen akzeptiert werden, oder setzen Sie `autoJoin: "always"`, wenn er jeder Einladung beitreten soll. Im Modus `allowlist` akzeptiert `autoJoinAllowlist` nur `!roomId:server`, `#alias:server` oder `*`. -Beispiel für eine Zulassungsliste: +Allowlist-Beispiel: ```json5 { @@ -155,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, betrachtet OpenClaw Matrix für Einrichtung, Doctor und die Erkennung des Kanalstatus 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 Einrichtung, Doctor und Kanalstatus-Erkennung als konfiguriert, auch wenn die aktuelle Authentifizierung nicht direkt in der Konfiguration gesetzt ist. -Äquivalente Umgebungsvariablen (werden verwendet, wenn der Konfigurationsschlüssel nicht gesetzt ist): +Entsprechende Umgebungsvariablen (werden verwendet, wenn der Konfigurationsschlüssel nicht gesetzt ist): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -166,7 +162,7 @@ Wenn dort zwischengespeicherte Anmeldedaten vorhanden sind, betrachtet OpenClaw - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Für Nicht-Standardkonten verwenden Sie kontospezifische Umgebungsvariablen: +Für Nicht-Standardkonten verwenden Sie kontobezogene Umgebungsvariablen: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -175,7 +171,7 @@ Für Nicht-Standardkonten verwenden Sie kontospezifische Umgebungsvariablen: - `MATRIX__DEVICE_ID` - `MATRIX__DEVICE_NAME` -Beispiel für Konto `ops`: +Beispiel für das Konto `ops`: - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` @@ -192,7 +188,7 @@ Der interaktive Assistent bietet die Umgebungsvariablen-Verknüpfung nur an, wen ## Konfigurationsbeispiel -Dies ist eine praktische Basiskonfiguration mit DM-Pairing, Raum-Zulassungsliste und aktiviertem E2EE: +Dies ist eine praktische Basiskonfiguration mit DM-Pairing, Raum-Allowlist und aktivierter E2EE: ```json5 { @@ -227,20 +223,18 @@ Dies ist eine praktische Basiskonfiguration mit DM-Pairing, Raum-Zulassungsliste } ``` -`autoJoin` gilt allgemein für Matrix-Einladungen, nicht nur für Raum-/Gruppeneinladungen. -Dazu gehören auch neue Einladungen im DM-Stil. Zum Zeitpunkt der Einladung weiß OpenClaw nicht zuverlässig, ob der -eingeladene Raum letztlich als DM oder als Gruppe behandelt wird, daher durchlaufen alle Einladungen zuerst dieselbe -`autoJoin`-Entscheidung. `dm.policy` gilt weiterhin, nachdem der Bot dem Raum beigetreten ist und der Raum -als DM klassifiziert wurde, sodass `autoJoin` das Beitrittsverhalten steuert, während `dm.policy` das Antwort-/Zugriffs- -verhalten steuert. +`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 werden alle Einladungen zuerst durch `autoJoin` +gefiltert. `dm.policy` gilt, nachdem der Bot beigetreten ist und der Raum als DM klassifiziert wurde. ## Streaming-Vorschauen -Antwort-Streaming in Matrix ist Opt-in. +Reply-Streaming in Matrix ist optional. -Setzen Sie `channels.matrix.streaming` auf `"partial"`, wenn OpenClaw eine einzelne Live-Vorschau- -Antwort senden, diese Vorschau während der Textgenerierung durch das Modell direkt bearbeiten und sie -abschließend finalisieren soll, sobald die Antwort fertig ist: +Setzen Sie `channels.matrix.streaming` auf `"partial"`, wenn OpenClaw eine einzelne Live-Vorschau +senden, diese Vorschau während der Textgenerierung durch das Modell direkt bearbeiten und sie +abschließen soll, wenn die Antwort fertig ist: ```json5 { @@ -252,35 +246,34 @@ abschließend finalisieren soll, sobald die Antwort fertig ist: } ``` -- `streaming: "off"` ist die Standardeinstellung. OpenClaw wartet auf die endgültige Antwort und sendet sie einmalig. -- `streaming: "partial"` erstellt eine bearbeitbare Vorschau-Nachricht für den aktuellen Assistant-Block unter Verwendung normaler Matrix-Textnachrichten. Dadurch bleibt das bisherige Benachrichtigungsverhalten von Matrix mit Vorschau zuerst erhalten, sodass Standard-Clients möglicherweise auf den ersten gestreamten Vorschautext statt auf den fertigen Block benachrichtigen. -- `streaming: "quiet"` erstellt einen bearbeitbaren stillen Vorschauhinweis für den aktuellen Assistant-Block. Verwenden Sie dies nur, wenn Sie zusätzlich Empfänger-Push-Regeln für finalisierte Vorschau-Bearbeitungen konfigurieren. -- `blockStreaming: true` aktiviert separate Matrix-Fortschrittsnachrichten. Wenn Vorschau-Streaming aktiviert ist, behält Matrix den Live-Entwurf für den aktuellen Block bei und bewahrt abgeschlossene Blöcke als separate Nachrichten. -- Wenn Vorschau-Streaming aktiviert ist und `blockStreaming` deaktiviert ist, bearbeitet Matrix den Live-Entwurf direkt und finalisiert dasselbe Ereignis, wenn der Block oder Zug beendet ist. -- Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Ereignis passt, beendet OpenClaw das Vorschau-Streaming und greift auf die normale endgültige Zustellung zurück. -- Medienantworten senden Anhänge weiterhin normal. Wenn eine veraltete Vorschau nicht mehr sicher wiederverwendet werden kann, redigiert OpenClaw sie, bevor die endgültige Medienantwort gesendet wird. +- `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 mit normalen Matrix-Textnachrichten. Dadurch bleibt das ältere Matrix-Verhalten „Vorschau zuerst“ für Benachrichtigungen 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. Verwenden Sie dies nur, wenn Sie zusätzlich Push-Regeln für Empfänger für abgeschlossene Vorschau-Bearbeitungen konfigurieren. +- `blockStreaming: true` aktiviert separate Matrix-Fortschrittsnachrichten. Wenn Vorschau-Streaming aktiviert ist, behält Matrix den Live-Entwurf für den aktuellen Block bei und erhält abgeschlossene Blöcke als separate Nachrichten. +- Wenn Vorschau-Streaming aktiviert ist und `blockStreaming` deaktiviert ist, bearbeitet Matrix den Live-Entwurf direkt und finalisiert dasselbe Ereignis, wenn der Block oder Turn abgeschlossen ist. +- Wenn die Vorschau nicht mehr in ein einzelnes Matrix-Ereignis passt, stoppt 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, redigiert OpenClaw sie vor dem Senden der endgültigen Medienantwort. - Vorschau-Bearbeitungen verursachen zusätzliche Matrix-API-Aufrufe. Lassen Sie Streaming deaktiviert, wenn Sie das konservativste Rate-Limit-Verhalten wünschen. `blockStreaming` aktiviert Entwurfsvorschauen nicht von selbst. -Verwenden Sie `streaming: "partial"` oder `streaming: "quiet"` für Vorschau-Bearbeitungen; fügen Sie dann `blockStreaming: true` nur hinzu, wenn auch abgeschlossene Assistant-Blöcke als separate Fortschrittsnachrichten sichtbar bleiben sollen. +Verwenden Sie `streaming: "partial"` oder `streaming: "quiet"` für Vorschau-Bearbeitungen; fügen Sie dann `blockStreaming: true` nur hinzu, wenn abgeschlossene Assistant-Blöcke zusätzlich als separate Fortschrittsnachrichten sichtbar bleiben sollen. -Wenn Sie Matrix-Standardbenachrichtigungen ohne benutzerdefinierte Push-Regeln benötigen, verwenden Sie `streaming: "partial"` für Vorschau-zuerst-Verhalten oder lassen Sie `streaming` für nur endgültige Zustellung deaktiviert. Mit `streaming: "off"`: +Wenn Sie Standard-Matrix-Benachrichtigungen ohne benutzerdefinierte Push-Regeln benötigen, verwenden Sie `streaming: "partial"` für Verhalten „Vorschau zuerst“ oder lassen `streaming` für reine endgültige Zustellung deaktiviert. Mit `streaming: "off"`: -- `blockStreaming: true` sendet jeden fertigen Block als normale benachrichtigende Matrix-Nachricht. -- `blockStreaming: false` sendet nur die endgültige vollständige Antwort als normale benachrichtigende Matrix-Nachricht. +- `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. ### Selbstgehostete Push-Regeln für stille finalisierte Vorschauen -Wenn Sie Ihre eigene Matrix-Infrastruktur betreiben und stille Vorschauen nur benachrichtigen sollen, wenn ein Block oder -eine endgültige Antwort fertig ist, setzen Sie `streaming: "quiet"` und fügen Sie eine benutzerspezifische Push-Regel für finalisierte Vorschau-Bearbeitungen hinzu. +Wenn Sie Ihre eigene Matrix-Infrastruktur betreiben und möchten, dass stille Vorschauen nur benachrichtigen, wenn ein Block oder die endgültige Antwort abgeschlossen ist, setzen Sie `streaming: "quiet"` und fügen Sie eine benutzerspezifische Push-Regel für finalisierte Vorschau-Bearbeitungen hinzu. -Dies ist in der Regel eine Empfänger-Benutzereinrichtung, keine globale Homeserver-Konfigurationsänderung: +Dies ist normalerweise eine Empfänger-Benutzerkonfiguration, keine globale Homeserver-Konfigurationsänderung: Kurzübersicht, bevor Sie beginnen: - Empfängerbenutzer = die Person, die die Benachrichtigung erhalten soll - Bot-Benutzer = das OpenClaw-Matrix-Konto, das die Antwort sendet -- verwenden Sie für die folgenden API-Aufrufe das Zugriffstoken des Empfängerbenutzers +- verwenden Sie für die folgenden API-Aufrufe das Access-Token des Empfängerbenutzers - gleichen Sie `sender` in der Push-Regel mit der vollständigen MXID des Bot-Benutzers ab 1. Konfigurieren Sie OpenClaw für stille Vorschauen: @@ -298,10 +291,10 @@ Kurzübersicht, bevor Sie beginnen: 2. Stellen Sie sicher, dass das Empfängerkonto bereits normale Matrix-Push-Benachrichtigungen erhält. Regeln für stille Vorschauen funktionieren nur, wenn dieser Benutzer bereits funktionierende Pusher/Geräte hat. -3. Beschaffen Sie das Zugriffstoken des Empfängerbenutzers. +3. Ermitteln Sie das Access-Token des Empfängerbenutzers. - Verwenden Sie das Token des empfangenden Benutzers, nicht das Token des Bots. - - Ein vorhandenes Client-Sitzungstoken wiederzuverwenden ist normalerweise am einfachsten. - - Wenn Sie ein neues Token ausstellen müssen, können Sie sich über die standardmäßige Matrix-Client-Server-API anmelden: + - Die Wiederverwendung eines vorhandenen Client-Sitzungstokens ist normalerweise am einfachsten. + - Wenn Sie ein neues Token erzeugen müssen, können Sie sich über die Standard-Client-Server-API von Matrix anmelden: ```bash curl -sS -X POST \ @@ -317,7 +310,7 @@ curl -sS -X POST \ }' ``` -4. Verifizieren Sie, dass das Empfängerkonto bereits Pusher hat: +4. Prüfen Sie, ob das Empfängerkonto bereits Pusher hat: ```bash curl -sS \ @@ -325,10 +318,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Wenn dies keine aktiven Pusher/Geräte zurückgibt, beheben Sie zuerst die normalen Matrix-Benachrichtigungen, bevor Sie die +Wenn dies keine aktiven Pusher/Geräte zurückgibt, beheben Sie zuerst normale Matrix-Benachrichtigungen, bevor Sie die unten stehende OpenClaw-Regel hinzufügen. -OpenClaw kennzeichnet finalisierte Bearbeitungen von Nur-Text-Vorschauen mit: +OpenClaw markiert finalisierte reine Text-Vorschau-Bearbeitungen mit: ```json { @@ -369,22 +362,22 @@ curl -sS -X PUT \ Ersetzen Sie diese Werte, bevor Sie den Befehl ausführen: - `https://matrix.example.org`: Ihre Homeserver-Basis-URL -- `$USER_ACCESS_TOKEN`: das Zugriffstoken des empfangenden Benutzers -- `openclaw-finalized-preview-botname`: eine für diesen Bot und diesen empfangenden Benutzer eindeutige Regel-ID -- `@bot:example.org`: Ihre OpenClaw-Matrix-Bot-MXID, nicht die MXID des empfangenden Benutzers +- `$USER_ACCESS_TOKEN`: das Access-Token des empfangenden Benutzers +- `openclaw-finalized-preview-botname`: eine Regel-ID, die für diesen Bot für diesen empfangenden Benutzer eindeutig ist +- `@bot:example.org`: die MXID Ihres OpenClaw-Matrix-Bots, nicht die MXID des empfangenden Benutzers Wichtig für Setups mit mehreren Bots: -- Push-Regeln werden über `ruleId` identifiziert. Wenn Sie `PUT` erneut gegen dieselbe Regel-ID ausführen, wird diese eine Regel aktualisiert. -- Wenn ein empfangender Benutzer für mehrere OpenClaw-Matrix-Bot-Konten benachrichtigt werden soll, erstellen Sie pro Bot eine Regel mit einer eindeutigen Regel-ID für jede Sender-Übereinstimmung. +- Push-Regeln sind durch `ruleId` gekennzeichnet. Wenn `PUT` erneut mit derselben Regel-ID ausgeführt wird, wird diese eine Regel aktualisiert. +- Wenn ein empfangender Benutzer Benachrichtigungen für mehrere OpenClaw-Matrix-Botkonten erhalten soll, erstellen Sie eine Regel pro Bot mit einer eindeutigen Regel-ID für jede `sender`-Übereinstimmung. - Ein einfaches Muster ist `openclaw-finalized-preview-`, etwa `openclaw-finalized-preview-ops` oder `openclaw-finalized-preview-support`. Die Regel wird gegen den Ereignisabsender ausgewertet: - authentifizieren Sie sich mit dem Token des empfangenden Benutzers -- gleichen Sie `sender` mit der OpenClaw-Bot-MXID ab +- gleichen Sie `sender` mit der MXID des OpenClaw-Bots ab -6. Verifizieren Sie, dass die Regel vorhanden ist: +6. Prüfen Sie, ob die Regel vorhanden ist: ```bash curl -sS \ @@ -392,8 +385,8 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Testen Sie eine gestreamte Antwort. Im stillen Modus sollte der Raum eine stille Entwurfsvorschau anzeigen, und die endgültige - direkte Bearbeitung sollte benachrichtigen, sobald der Block oder Zug abgeschlossen ist. +7. Testen Sie eine gestreamte Antwort. Im stillen Modus sollte der Raum eine stille Entwurfs-Vorschau anzeigen, und die endgültige + Bearbeitung direkt an Ort und Stelle sollte benachrichtigen, sobald der Block oder Turn abgeschlossen ist. Wenn Sie die Regel später entfernen müssen, löschen Sie dieselbe Regel-ID mit dem Token des empfangenden Benutzers: @@ -405,37 +398,33 @@ curl -sS -X DELETE \ Hinweise: -- Erstellen Sie die Regel mit dem Zugriffstoken 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 Ordnungsparameter erforderlich. -- Dies betrifft nur Bearbeitungen von Nur-Text-Vorschauen, die OpenClaw sicher direkt finalisieren kann. Medien-Fallbacks und Fallbacks bei veralteten Vorschauen verwenden weiterhin die normale Matrix-Zustellung. +- Erstellen Sie die Regel mit dem Access-Token des empfangenden Benutzers, nicht mit dem des Bots. +- Neue benutzerdefinierte `override`-Regeln werden vor standardmäßigen Unterdrückungsregeln eingefügt, daher ist kein zusätzlicher Ordnungsparameter erforderlich. +- Dies betrifft nur reine Text-Vorschau-Bearbeitungen, die OpenClaw sicher direkt finalisieren kann. Medien-Fallbacks und Fallbacks für veraltete Vorschauen verwenden weiterhin 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 -Für Synapse reicht die obige Einrichtung normalerweise bereits aus: +Für Synapse reicht die oben beschriebene Einrichtung normalerweise bereits aus: -- Für finalisierte OpenClaw-Vorschau-Benachrichtigungen ist keine spezielle Änderung in `homeserver.yaml` erforderlich. -- Wenn Ihre Synapse-Bereitstellung bereits normale Matrix-Push-Benachrichtigungen sendet, ist der wichtigste Einrichtungsschritt das obige Benutzer-Token plus der Aufruf von `pushrules`. -- Wenn Sie Synapse hinter einem Reverse-Proxy oder Workern betreiben, stellen Sie sicher, dass `/_matrix/client/.../pushrules/` Synapse korrekt erreicht. +- Es ist keine spezielle Änderung an `homeserver.yaml` für finalisierte OpenClaw-Vorschau-Benachrichtigungen erforderlich. +- Wenn Ihre Synapse-Bereitstellung bereits normale Matrix-Push-Benachrichtigungen sendet, ist das Benutzer-Token plus der obige `pushrules`-Aufruf der wichtigste Einrichtungsschritt. +- Wenn Sie Synapse hinter einem Reverse-Proxy oder mit Workern betreiben, stellen Sie sicher, dass `/_matrix/client/.../pushrules/` Synapse korrekt erreicht. - Wenn Sie Synapse-Worker betreiben, stellen Sie sicher, dass Pusher fehlerfrei arbeiten. Die Push-Zustellung wird vom Hauptprozess oder von `synapse.app.pusher` / konfigurierten Pusher-Workern verarbeitet. #### Tuwunel -Für Tuwunel verwenden Sie denselben Einrichtungsablauf und denselben oben gezeigten API-Aufruf für Push-Regeln: +Für Tuwunel verwenden Sie denselben Einrichtungsablauf und denselben oben gezeigten Push-Regel-API-Aufruf: -- Für die Kennzeichnung finalisierter Vorschauen selbst ist keine Tuwunel-spezifische Konfiguration erforderlich. -- Wenn normale Matrix-Benachrichtigungen für diesen Benutzer bereits funktionieren, ist der wichtigste Einrichtungsschritt das obige Benutzer-Token plus der Aufruf von `pushrules`. -- Wenn Benachrichtigungen zu verschwinden scheinen, während der Benutzer auf einem anderen Gerät aktiv ist, prüfen Sie, 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. +- Für die Markierung der finalisierten Vorschau selbst ist keine Tuwunel-spezifische Konfiguration erforderlich. +- Wenn normale Matrix-Benachrichtigungen für diesen Benutzer bereits funktionieren, ist das Benutzer-Token plus der obige `pushrules`-Aufruf der wichtigste Einrichtungsschritt. +- Wenn Benachrichtigungen scheinbar verschwinden, während der Benutzer auf einem anderen Gerät aktiv ist, prüfen Sie, 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. -## Verschlüsselung und Verifizierung +## Bot-zu-Bot-Räume -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. +Standardmäßig werden Matrix-Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten ignoriert. -### Bot-zu-Bot-Räume - -Standardmäßig werden Matrix-Nachrichten anderer konfigurierter OpenClaw-Matrix-Konten ignoriert. - -Verwenden Sie `allowBots`, wenn Sie absichtlich Matrix-Datenverkehr zwischen Agents wünschen: +Verwenden Sie `allowBots`, wenn Sie absichtlich Matrix-Verkehr zwischen Agenten möchten: ```json5 { @@ -452,13 +441,17 @@ Verwenden Sie `allowBots`, wenn Sie absichtlich Matrix-Datenverkehr zwischen Age } ``` -- `allowBots: true` akzeptiert Nachrichten anderer konfigurierter Matrix-Bot-Konten in zulässigen Räumen und DMs. -- `allowBots: "mentions"` akzeptiert diese Nachrichten in Räumen nur dann, wenn sie diesen Bot sichtbar erwähnen. DMs sind weiterhin erlaubt. +- `allowBots: true` akzeptiert Nachrichten von anderen konfigurierten Matrix-Botkonten in zugelassenen Räumen und DMs. +- `allowBots: "mentions"` akzeptiert diese Nachrichten in Räumen nur, wenn dieser Bot darin sichtbar erwähnt wird. DMs sind weiterhin zulässig. - `groups..allowBots` überschreibt die Einstellung auf Kontoebene für einen Raum. -- OpenClaw ignoriert weiterhin Nachrichten derselben Matrix-Benutzer-ID, um Selbstantwort-Schleifen zu vermeiden. -- Matrix stellt hier kein natives Bot-Flag bereit; OpenClaw behandelt „von einem Bot verfasst“ als „von einem anderen konfigurierten Matrix-Konto auf diesem OpenClaw-Gateway gesendet“. +- 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“. -Verwenden Sie strikte Raum-Zulassungslisten und Erwähnungsanforderungen, wenn Sie Bot-zu-Bot-Datenverkehr in gemeinsam genutzten Räumen aktivieren. +Verwenden Sie strikte Raum-Allowlists und Erwähnungspflichten, wenn Sie Bot-zu-Bot-Verkehr in gemeinsam genutzten Räumen aktivieren. + +## 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. Verschlüsselung aktivieren: @@ -488,33 +481,31 @@ Ausführlicher Status (vollständige Diagnose): openclaw matrix verify status --verbose ``` -Den gespeicherten Wiederherstellungsschlüssel in maschinenlesbarer Ausgabe einbeziehen: +Den gespeicherten Recovery-Key in maschinenlesbarer Ausgabe einschließen: ```bash openclaw matrix verify status --include-recovery-key --json ``` -Cross-Signing- und Verifizierungsstatus bootstrapen: +Cross-Signing- und Verifizierungsstatus initialisieren: ```bash openclaw matrix verify bootstrap ``` -Unterstützung für mehrere Konten: Verwenden Sie `channels.matrix.accounts` mit kontoabhängigen Anmeldedaten und optionalem `name`. Das gemeinsame Muster finden Sie unter [Konfigurationsreferenz](/de/gateway/configuration-reference#multi-account-all-channels). - Ausführliche Bootstrap-Diagnose: ```bash openclaw matrix verify bootstrap --verbose ``` -Ein Zurücksetzen auf eine frische Cross-Signing-Identität vor dem Bootstrap erzwingen: +Vor dem Bootstrap explizit eine neue Cross-Signing-Identität erzwingen: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -Dieses Gerät mit einem Wiederherstellungsschlüssel verifizieren: +Dieses Gerät mit einem Recovery-Key verifizieren: ```bash openclaw matrix verify device "" @@ -526,19 +517,19 @@ Ausführliche Details zur Geräteverifizierung: openclaw matrix verify device "" --verbose ``` -Integrität der Raumschlüssel-Sicherung prüfen: +Zustand des Raumschlüssel-Backups prüfen: ```bash openclaw matrix verify backup status ``` -Ausführliche Diagnose zur Integrität der Sicherung: +Ausführliche Diagnose zum Backup-Zustand: ```bash openclaw matrix verify backup status --verbose ``` -Raumschlüssel aus der Server-Sicherung wiederherstellen: +Raumschlüssel aus dem Server-Backup wiederherstellen: ```bash openclaw matrix verify backup restore @@ -550,20 +541,20 @@ Ausführliche Diagnose zur Wiederherstellung: openclaw matrix verify backup restore --verbose ``` -Löschen Sie die aktuelle Server-Sicherung und erstellen Sie eine neue Sicherungsbasislinie. Wenn der gespeicherte -Sicherungsschlüssel nicht sauber geladen werden kann, kann dieses Zurücksetzen auch den geheimen Speicher neu erstellen, sodass -zukünftige Kaltstarts den neuen Sicherungsschlüssel laden können: +Das aktuelle Server-Backup löschen und eine neue Backup-Basis erstellen. Wenn der gespeicherte +Backup-Schlüssel nicht sauber geladen werden kann, kann dieses Zurücksetzen auch den Secret Storage neu erstellen, damit +zukünftige Kaltstarts den neuen Backup-Schlüssel laden können: ```bash openclaw matrix verify backup reset --yes ``` -Alle `verify`-Befehle sind standardmäßig kompakt (einschließlich stiller interner SDK-Protokollierung) und zeigen detaillierte Diagnose nur mit `--verbose`. -Verwenden Sie `--json` für vollständige maschinenlesbare Ausgabe bei der Skripterstellung. +Alle `verify`-Befehle sind standardmäßig kompakt (einschließlich ruhiger interner SDK-Protokollierung) und zeigen detaillierte Diagnosen nur mit `--verbose`. +Verwenden Sie `--json` für vollständige maschinenlesbare Ausgabe beim Skripting. In Setups mit mehreren Konten verwenden Matrix-CLI-Befehle das implizite Matrix-Standardkonto, sofern Sie nicht `--account ` übergeben. -Wenn Sie mehrere benannte Konten konfigurieren, setzen Sie zuerst `channels.matrix.defaultAccount`, andernfalls werden diese impliziten CLI-Operationen angehalten und fordern Sie auf, explizit ein Konto auszuwählen. -Verwenden Sie `--account` immer dann, wenn Verifizierungs- oder Geräteoperationen explizit ein benanntes Konto ansprechen sollen: +Wenn Sie mehrere benannte Konten konfigurieren, setzen Sie zuerst `channels.matrix.defaultAccount`, sonst stoppen diese impliziten CLI-Operationen und fordern Sie auf, ein Konto explizit auszuwählen. +Verwenden Sie `--account` immer dann, wenn Verifizierungs- oder Geräteoperationen explizit ein benanntes Konto betreffen sollen: ```bash openclaw matrix verify status --account assistant @@ -575,39 +566,39 @@ Wenn die Verschlüsselung für ein benanntes Konto deaktiviert oder nicht verfü ### Was „verifiziert“ bedeutet -OpenClaw behandelt dieses Matrix-Gerät nur dann als verifiziert, wenn es durch Ihre eigene Cross-Signing-Identität verifiziert ist. -In der Praxis macht `openclaw matrix verify status --verbose` drei Vertrauenssignale sichtbar: +OpenClaw behandelt dieses Matrix-Gerät nur dann als verifiziert, wenn es von Ihrer eigenen Cross-Signing-Identität verifiziert wurde. +In der Praxis stellt `openclaw matrix verify status --verbose` drei Vertrauenssignale bereit: -- `Locally trusted`: Dieses Gerät wird nur vom aktuellen Client als vertrauenswürdig eingestuft -- `Cross-signing verified`: Das SDK meldet das Gerät als durch Cross-Signing verifiziert +- `Locally trusted`: Dieses Gerät wird nur vom aktuellen Client als vertrauenswürdig behandelt +- `Cross-signing verified`: Das SDK meldet das Gerät als per Cross-Signing verifiziert - `Signed by owner`: Das Gerät ist mit Ihrem eigenen Self-Signing-Schlüssel signiert -`Verified by owner` wird nur dann zu `yes`, wenn Cross-Signing-Verifizierung oder Eigentümer-Signierung 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 `openclaw matrix verify bootstrap` ist der Reparatur- und Einrichtungsbefehl für verschlüsselte Matrix-Konten. -Er führt der Reihe nach Folgendes aus: +Er führt in dieser Reihenfolge alle folgenden Schritte aus: -- bootstrapt den geheimen Speicher und verwendet nach Möglichkeit einen vorhandenen Wiederherstellungsschlüssel wieder -- bootstrapt Cross-Signing und lädt fehlende öffentliche Cross-Signing-Schlüssel hoch +- initialisiert Secret Storage und verwendet nach Möglichkeit einen vorhandenen Recovery-Key wieder +- 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 eine neue serverseitige Raumschlüssel-Sicherung, falls noch keine existiert +- 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`, dann mit `m.login.password`, wenn `channels.matrix.password` konfiguriert ist. +Wenn der Homeserver interaktive Authentifizierung zum Hochladen von Cross-Signing-Schlüsseln verlangt, versucht OpenClaw den Upload zuerst ohne Authentifizierung, dann mit `m.login.dummy`, dann mit `m.login.password`, wenn `channels.matrix.password` konfiguriert ist. -Verwenden Sie `--force-reset-cross-signing` nur, wenn Sie absichtlich die aktuelle Cross-Signing-Identität verwerfen und eine neue erstellen möchten. +Verwenden Sie `--force-reset-cross-signing` nur, wenn Sie die aktuelle Cross-Signing-Identität absichtlich verwerfen und eine neue erstellen möchten. -Wenn Sie absichtlich die aktuelle Raumschlüssel-Sicherung verwerfen und eine neue -Sicherungsbasislinie für zukünftige Nachrichten starten möchten, verwenden Sie `openclaw matrix verify backup reset --yes`. +Wenn Sie das aktuelle Raumschlüssel-Backup absichtlich verwerfen und eine neue +Backup-Basis für zukünftige Nachrichten starten möchten, verwenden Sie `openclaw matrix verify backup reset --yes`. Tun Sie dies nur, wenn Sie akzeptieren, dass nicht wiederherstellbarer alter verschlüsselter Verlauf -nicht verfügbar bleibt und OpenClaw den geheimen Speicher möglicherweise neu erstellt, wenn das aktuelle Sicherungs- -geheimnis nicht sicher geladen werden kann. +nicht verfügbar bleibt und OpenClaw den Secret Storage möglicherweise neu erstellt, wenn das aktuelle Backup- +Geheimnis nicht sicher geladen werden kann. -### Frische Sicherungsbasislinie +### Neue Backup-Basis -Wenn Sie möchten, dass zukünftige verschlüsselte Nachrichten weiterhin funktionieren, und akzeptieren, dass nicht wiederherstellbarer alter Verlauf verloren geht, führen Sie diese Befehle in dieser Reihenfolge aus: +Wenn Sie zukünftige verschlüsselte Nachrichten funktionsfähig halten und den Verlust nicht wiederherstellbarer alter Chronik akzeptieren möchten, führen Sie diese Befehle in der angegebenen Reihenfolge aus: ```bash openclaw matrix verify backup reset --yes @@ -615,96 +606,43 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Fügen Sie zu jedem Befehl `--account ` hinzu, wenn Sie explizit ein benanntes Matrix-Konto ansprechen möchten. +Fügen Sie jedem Befehl `--account ` hinzu, wenn Sie explizit ein benanntes Matrix-Konto ansprechen möchten. -### Startverhalten +### Verhalten beim Start -Wenn `encryption: true` gesetzt ist, verwendet Matrix standardmäßig `startupVerification` mit dem Wert `"if-unverified"`. -Beim Start fordert Matrix, falls dieses Gerät noch nicht verifiziert ist, in einem anderen Matrix-Client eine Selbstverifizierung an, -überspringt doppelte Anfragen, solange bereits eine aussteht, und wendet vor erneuten Versuchen nach Neustarts eine lokale Abkühlzeit an. -Fehlgeschlagene Anforderungsversuche werden standardmäßig früher erneut versucht als erfolgreiche Erstellungen von Anforderungen. -Setzen Sie `startupVerification: "off"`, um automatische Anfragen beim Start zu deaktivieren, oder passen Sie `startupVerificationCooldownHours` +Wenn `encryption: true` gesetzt ist, verwendet Matrix standardmäßig `startupVerification` = `"if-unverified"`. +Beim Start fordert Matrix, falls 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. +Setzen Sie `startupVerification: "off"`, um automatische Startanfragen zu deaktivieren, oder passen Sie `startupVerificationCooldownHours` an, wenn Sie ein kürzeres oder längeres Wiederholungsfenster wünschen. Beim Start wird außerdem automatisch ein konservativer Crypto-Bootstrap-Durchlauf ausgeführt. -Dieser Durchlauf versucht zuerst, den aktuellen geheimen Speicher und die aktuelle Cross-Signing-Identität wiederzuverwenden, und vermeidet das Zurücksetzen von Cross-Signing, sofern Sie nicht einen expliziten Bootstrap-Reparaturablauf ausführen. +Dieser Durchlauf versucht zuerst, den aktuellen Secret Storage und die aktuelle Cross-Signing-Identität wiederzuverwenden, und vermeidet das Zurücksetzen von Cross-Signing, sofern Sie nicht explizit einen Bootstrap-Reparaturablauf ausführen. -Wenn beim Start ein fehlerhafter Bootstrap-Zustand gefunden wird und `channels.matrix.password` konfiguriert ist, kann OpenClaw einen strengeren Reparaturpfad versuchen. -Wenn das aktuelle Gerät bereits vom Eigentümer signiert ist, bewahrt OpenClaw diese Identität, anstatt sie automatisch zurückzusetzen. +Wenn beim Start ein defekter Bootstrap-Zustand gefunden wird und `channels.matrix.password` konfiguriert ist, kann OpenClaw einen strengeren Reparaturpfad versuchen. +Wenn das aktuelle Gerät bereits vom Besitzer signiert ist, bewahrt OpenClaw diese Identität, statt sie automatisch zurückzusetzen. -Upgrade vom vorherigen öffentlichen Matrix-Plugin: +Siehe [Matrix migration](/de/install/migrating-matrix) für den vollständigen Upgrade-Ablauf, Einschränkungen, Wiederherstellungsbefehle und häufige Migrationsmeldungen. -- OpenClaw verwendet nach Möglichkeit automatisch dasselbe Matrix-Konto, dasselbe Zugriffstoken und dieselbe Geräteidentität wieder. -- Bevor umsetzbare Matrix-Migrationsänderungen ausgeführt werden, erstellt oder verwendet OpenClaw einen Wiederherstellungs-Snapshot unter `~/Backups/openclaw-migrations/`. -- Wenn Sie mehrere Matrix-Konten verwenden, setzen Sie `channels.matrix.defaultAccount`, bevor Sie vom alten Flat-Store-Layout aktualisieren, damit OpenClaw weiß, welches Konto diesen gemeinsam genutzten Legacy-Status erhalten soll. -- Wenn das vorherige Plugin lokal einen Entschlüsselungsschlüssel für Matrix-Raumschlüssel-Sicherungen gespeichert hat, importiert der Start oder `openclaw doctor --fix` ihn automatisch in den neuen Wiederherstellungsschlüssel-Ablauf. -- Wenn sich das Matrix-Zugriffstoken geändert hat, nachdem die Migration vorbereitet wurde, durchsucht der Start jetzt benachbarte token-hash-Speicherwurzeln nach ausstehendem Legacy-Wiederherstellungsstatus, bevor die automatische Sicherungswiederherstellung aufgegeben wird. -- Wenn sich das Matrix-Zugriffstoken später für dasselbe Konto, denselben Homeserver und denselben Benutzer ändert, bevorzugt OpenClaw jetzt die Wiederverwendung der vollständigsten vorhandenen token-hash-Speicherwurzel, anstatt mit einem leeren Matrix-Statusverzeichnis zu beginnen. -- Beim nächsten Gateway-Start werden gesicherte Raumschlüssel automatisch in den neuen Crypto-Speicher wiederhergestellt. -- Wenn das alte Plugin nur lokale Raumschlüssel hatte, die nie gesichert wurden, warnt OpenClaw deutlich. Diese Schlüssel können nicht automatisch aus dem vorherigen Rust-Crypto-Speicher exportiert werden, daher kann ein Teil des alten verschlüsselten Verlaufs bis zur manuellen Wiederherstellung nicht verfügbar bleiben. -- Siehe [Matrix-Migration](/de/install/migrating-matrix) für den vollständigen Upgrade-Ablauf, Einschränkungen, Wiederherstellungsbefehle und häufige Migrationsmeldungen. +### Verifizierungsmitteilungen -Der verschlüsselte Laufzeitstatus ist unter konto-, benutzer- und token-hash-spezifischen Wurzeln organisiert in -`~/.openclaw/matrix/accounts//__//`. -Dieses Verzeichnis enthält den Sync-Speicher (`bot-storage.json`), den Crypto-Speicher (`crypto/`), -die Wiederherstellungsschlüsseldatei (`recovery-key.json`), den IndexedDB-Snapshot (`crypto-idb-snapshot.json`), -Thread-Bindings (`thread-bindings.json`) und den Status der Startverifizierung (`startup-verification.json`), -wenn diese Funktionen verwendet werden. -Wenn sich das Token ändert, die Kontoidentität aber gleich bleibt, verwendet OpenClaw die beste vorhandene -Wurzel für dieses Konto/Homeserver/Benutzer-Tupel wieder, damit vorheriger Sync-Status, Crypto-Status, Thread-Bindings -und Startverifizierungsstatus sichtbar bleiben. - -### Node-Crypto-Speichermodell - -Matrix-E2EE in diesem Plugin verwendet den offiziellen Rust-Crypto-Pfad von `matrix-js-sdk` in Node. -Dieser Pfad erwartet IndexedDB-gestützte Persistenz, wenn der Crypto-Status Neustarts überdauern soll. - -OpenClaw stellt dies derzeit in Node bereit, indem es: - -- `fake-indexeddb` als den vom SDK erwarteten IndexedDB-API-Shim verwendet -- die Inhalte der Rust-Crypto-IndexedDB aus `crypto-idb-snapshot.json` vor `initRustCrypto` wiederherstellt -- die aktualisierten IndexedDB-Inhalte nach der Initialisierung und während der Laufzeit zurück in `crypto-idb-snapshot.json` persistiert -- die Snapshot-Wiederherstellung und Persistierung gegenüber `crypto-idb-snapshot.json` mit einer beratenden Dateisperre serialisiert, damit Laufzeitpersistenz des Gateways und CLI-Wartung nicht um dieselbe Snapshot-Datei konkurrieren - -Dies ist Kompatibilitäts-/Speicher-Infrastruktur, keine benutzerdefinierte Crypto-Implementierung. -Die Snapshot-Datei ist sensibler Laufzeitstatus und wird mit restriktiven Dateiberechtigungen gespeichert. -Unter dem Sicherheitsmodell von OpenClaw befinden sich der Gateway-Host und das lokale OpenClaw-Statusverzeichnis bereits innerhalb der vertrauenswürdigen Betreibergrenze, daher ist dies primär ein operatives Haltbarkeitsproblem und keine separate Remote-Vertrauensgrenze. - -Geplante Verbesserung: - -- SecretRef-Unterstützung für persistentes Matrix-Schlüsselmaterial hinzufügen, damit Wiederherstellungsschlüssel und verwandte Speicher-Verschlüsselungsgeheimnisse aus OpenClaw-Geheimnisanbietern statt nur aus lokalen Dateien bezogen werden können - -## Profilverwaltung - -Aktualisieren Sie das Matrix-Selbstprofil für das ausgewählte Konto mit: - -```bash -openclaw matrix profile set --name "OpenClaw Assistant" -openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png -``` - -Fügen Sie `--account ` hinzu, wenn Sie explizit ein benanntes Matrix-Konto ansprechen möchten. - -Matrix akzeptiert `mxc://`-Avatar-URLs direkt. Wenn Sie eine `http://`- oder `https://`-Avatar-URL übergeben, lädt OpenClaw sie zuerst zu Matrix hoch und speichert die aufgelöste `mxc://`-URL zurück in `channels.matrix.avatarUrl` (oder die ausgewählte Kontoüberschreibung). - -## Automatische Verifizierungshinweise - -Matrix veröffentlicht jetzt Hinweise zum Verifizierungslebenszyklus direkt als `m.notice`-Nachrichten im strikten DM-Verifizierungsraum. +Matrix veröffentlicht Mitteilungen zum Verifizierungslebenszyklus direkt in den strikten DM-Verifizierungsraum als `m.notice`-Nachrichten. Dazu gehören: -- Hinweise auf Verifizierungsanfragen -- Hinweise auf Verifizierungsbereitschaft (mit expliziter Anleitung „Per Emoji verifizieren“) -- Hinweise auf Verifizierungsstart und -abschluss -- SAS-Details (Emoji und Dezimalwerte), sofern verfügbar +- Mitteilungen zu Verifizierungsanfragen +- Mitteilungen „Verifizierung bereit“ (mit explizitem Hinweis „Per Emoji verifizieren“) +- Mitteilungen über Beginn und Abschluss der Verifizierung +- SAS-Details (Emoji und Dezimalzahlen), wenn verfügbar Eingehende Verifizierungsanfragen von einem anderen Matrix-Client werden von OpenClaw nachverfolgt und automatisch akzeptiert. -Bei Selbstverifizierungsabläufen startet OpenClaw den SAS-Ablauf auch automatisch, sobald Emoji-Verifizierung verfügbar wird, und bestätigt seine eigene Seite. -Bei Verifizierungsanfragen von einem anderen Matrix-Benutzer/Gerät akzeptiert OpenClaw die Anfrage automatisch und wartet dann, bis der SAS-Ablauf normal fortgesetzt wird. +Für Selbstverifizierungsabläufe startet OpenClaw außerdem den SAS-Ablauf automatisch, sobald Emoji-Verifizierung verfügbar ist, und bestätigt seine eigene Seite. +Bei Verifizierungsanfragen von einem anderen Matrix-Benutzer/Gerät akzeptiert OpenClaw die Anfrage automatisch und wartet dann, bis der SAS-Ablauf normal weitergeht. Sie müssen weiterhin die Emoji- oder Dezimal-SAS in Ihrem Matrix-Client vergleichen und dort „Sie stimmen überein“ bestätigen, um die Verifizierung abzuschließen. -OpenClaw akzeptiert selbstinitiierte doppelte Abläufe nicht blind automatisch. Beim Start wird keine neue Anfrage erstellt, 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. -Verifizierungs-/Protokoll-/Systemhinweise werden nicht an die Agent-Chat-Pipeline weitergeleitet und erzeugen daher kein `NO_REPLY`. +Mitteilungen des Verifizierungsprotokolls/Systems werden nicht an die Agent-Chat-Pipeline weitergeleitet, daher erzeugen sie kein `NO_REPLY`. ### Gerätehygiene @@ -721,56 +659,60 @@ Entfernen Sie veraltete von OpenClaw verwaltete Geräte mit: openclaw matrix devices prune-stale ``` -### Reparatur direkter Räume +### Crypto-Store -Wenn der Direktnachrichtenstatus nicht mehr synchron ist, kann OpenClaw veraltete `m.direct`-Zuordnungen haben, die auf alte Einzelräume statt auf die aktive DM zeigen. Überprüfen Sie die aktuelle Zuordnung für einen Peer mit: +Matrix E2EE verwendet in Node den offiziellen `matrix-js-sdk`-Rust-Crypto-Pfad, mit `fake-indexeddb` als IndexedDB-Shim. Der Crypto-Zustand wird in eine Snapshot-Datei (`crypto-idb-snapshot.json`) persistiert und beim Start wiederhergestellt. Die Snapshot-Datei ist sensibler Laufzeitzustand und wird mit restriktiven Dateiberechtigungen gespeichert. + +Verschlüsselter Laufzeitzustand liegt unter konto-, benutzer- und tokenhashbezogenen Wurzeln in +`~/.openclaw/matrix/accounts//__//`. +Dieses Verzeichnis enthält den Sync-Store (`bot-storage.json`), den Crypto-Store (`crypto/`), +die Recovery-Key-Datei (`recovery-key.json`), den IndexedDB-Snapshot (`crypto-idb-snapshot.json`), +Thread-Bindings (`thread-bindings.json`) und den Start-Verifizierungsstatus (`startup-verification.json`). +Wenn sich das Token ändert, die Kontenidentität aber gleich bleibt, verwendet OpenClaw für dieses +Konto/Homeserver/Benutzer-Tupel die am besten geeignete vorhandene Wurzel wieder, sodass früherer Sync-Zustand, Crypto-Zustand, Thread-Bindings +und Start-Verifizierungsstatus weiter verfügbar bleiben. + +## Profilverwaltung + +Aktualisieren Sie das Matrix-Selbstprofil für das ausgewählte Konto mit: ```bash -openclaw matrix direct inspect --user-id @alice:example.org +openclaw matrix profile set --name "OpenClaw Assistant" +openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Reparieren Sie sie mit: +Fügen Sie `--account ` hinzu, wenn Sie explizit ein benanntes Matrix-Konto ansprechen möchten. -```bash -openclaw matrix direct repair --user-id @alice:example.org -``` - -Die Reparatur hält die Matrix-spezifische Logik innerhalb des Plugins: - -- sie bevorzugt eine strikte 1:1-DM, die bereits in `m.direct` zugeordnet ist -- andernfalls greift sie auf jede aktuell beigetretene strikte 1:1-DM mit diesem Benutzer zurück -- wenn keine fehlerfreie DM existiert, erstellt sie einen neuen direkten Raum und schreibt `m.direct` so um, dass er auf diesen zeigt - -Der Reparaturablauf löscht alte Räume nicht automatisch. Er wählt nur die fehlerfreie DM aus und aktualisiert die Zuordnung, damit neue Matrix-Sendungen, Verifizierungshinweise und andere Direktnachrichtenabläufe wieder den richtigen Raum ansprechen. +Matrix akzeptiert `mxc://`-Avatar-URLs direkt. Wenn Sie eine `http://`- oder `https://`-Avatar-URL übergeben, 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). ## Threads -Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für Sendungen durch Message-Tools. +Matrix unterstützt native Matrix-Threads sowohl für automatische Antworten als auch für Sendevorgänge mit Message-Tools. -- `dm.sessionScope: "per-user"` (Standard) hält das Matrix-DM-Routing absenderbezogen, sodass mehrere DM-Räume eine Sitzung teilen können, wenn sie demselben Peer zugeordnet werden. -- `dm.sessionScope: "per-room"` isoliert jeden Matrix-DM-Raum in seinen eigenen Sitzungsschlüssel und verwendet dabei weiterhin normale DM-Authentifizierungs- und Zulassungslistenprüfungen. -- Explizite Matrix-Konversationsbindungen haben weiterhin Vorrang vor `dm.sessionScope`, sodass gebundene Räume und Threads ihr gewähltes Zielsitzung beibehalten. -- `threadReplies: "off"` hält Antworten auf oberster Ebene und hält eingehende gethreadete Nachrichten in der übergeordneten Sitzung. -- `threadReplies: "inbound"` antwortet in einem Thread nur dann innerhalb dieses Threads, wenn die eingehende Nachricht bereits in diesem Thread war. -- `threadReplies: "always"` hält Raumantworten in einem Thread, der an der auslösenden Nachricht verankert ist, und leitet diese Konversation ab der ersten auslösenden Nachricht durch die passende threadbezogene Sitzung. -- `dm.threadReplies` überschreibt die Einstellung auf oberster Ebene nur für DMs. So können Sie zum Beispiel Raum-Threads isoliert halten und DMs flach lassen. -- Eingehende gethreadete Nachrichten enthalten die Thread-Root-Nachricht als zusätzlichen Agent-Kontext. -- Sendungen durch Message-Tools übernehmen jetzt automatisch den aktuellen Matrix-Thread, wenn das Ziel derselbe Raum oder dasselbe DM-Benutzerziel ist, es sei denn, es wird explizit eine `threadId` angegeben. -- Die Wiederverwendung desselben DM-Benutzerziels in derselben Sitzung greift nur, wenn die aktuellen Sitzungsmetadaten denselben DM-Peer 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 auf derselben gemeinsamen Matrix-DM-Sitzung kollidiert, veröffentlicht es in diesem Raum einen einmaligen `m.notice` mit der `/focus`-Ausweichmöglichkeit, wenn Thread-Bindings aktiviert sind, sowie dem Hinweis auf `dm.sessionScope`. -- Laufzeit-Thread-Bindings werden für Matrix unterstützt. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` und threadgebundenes `/acp spawn` funktionieren jetzt 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`. -- Das Ausführen von `/focus` oder `/acp spawn --thread here` innerhalb eines vorhandenen Matrix-Threads bindet stattdessen diesen aktuellen Thread. +- `dm.sessionScope: "per-user"` (Standard) hält das DM-Routing in Matrix auf Absenderebene, sodass mehrere DM-Räume eine Sitzung teilen können, wenn sie zum selben Peer aufgelöst werden. +- `dm.sessionScope: "per-room"` isoliert jeden Matrix-DM-Raum in seinen eigenen Sitzungsschlüssel, verwendet aber weiterhin normale DM-Authentifizierungs- 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 eingehende Thread-Nachrichten in der Sitzung des übergeordneten Elements. +- `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, der in der auslösenden Nachricht verwurzelt ist, und leitet diese Konversation ab der ersten auslösenden Nachricht durch die passende threadbezogene Sitzung. +- `dm.threadReplies` überschreibt die Einstellung auf oberster Ebene nur für DMs. Sie können beispielsweise Raum-Threads isoliert halten und DMs flach belassen. +- Eingehende Thread-Nachrichten enthalten die Thread-Root-Nachricht als zusätzlichen Agent-Kontext. +- Message-Tool-Sendevorgänge übernehmen automatisch den aktuellen Matrix-Thread, wenn das Ziel derselbe Raum oder dasselbe DM-Benutzerziel ist, sofern kein explizites `threadId` angegeben wird. +- Die Wiederverwendung desselben DM-Benutzerziels in derselben Sitzung greift nur, wenn die aktuelle Sitzungsmetadaten 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 geteilten Matrix-DM-Sitzung kollidiert, veröffentlicht es in diesem Raum einmalig ein `m.notice` mit dem Ausweg `/focus`, wenn Thread-Bindings aktiviert sind und der Hinweis `dm.sessionScope` gilt. +- 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. +- Ein `/focus` auf oberster Ebene in 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 bestehenden Matrix-Threads ausgeführt wird, wird stattdessen dieser aktuelle Thread gebunden. ## ACP-Konversationsbindungen -Matrix-Räume, DMs und vorhandene Matrix-Threads können in dauerhafte ACP-Arbeitsbereiche verwandelt werden, ohne die Chat-Oberfläche zu ändern. +Matrix-Räume, DMs und bestehende Matrix-Threads können in dauerhafte ACP-Workspaces umgewandelt werden, ohne die Chat-Oberfläche zu ändern. Schneller Operator-Ablauf: -- Führen Sie `/acp spawn codex --bind here` innerhalb der Matrix-DM, des Raums oder des vorhandenen Threads aus, den Sie weiterverwenden möchten. +- Führen Sie `/acp spawn codex --bind here` innerhalb der Matrix-DM, des Raums oder des bestehenden Threads aus, den Sie weiterverwenden möchten. - 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. -- Innerhalb eines vorhandenen Matrix-Threads bindet `--bind here` diesen aktuellen Thread direkt. +- Innerhalb eines bestehenden Matrix-Threads bindet `--bind here` diesen aktuellen Thread direkt. - `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung direkt zurück. - `/acp close` schließt die ACP-Sitzung und entfernt die Bindung. @@ -781,7 +723,7 @@ Hinweise: ### Thread-Binding-Konfiguration -Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterstützt außerdem kanalbezogene Überschreibungen: +Matrix übernimmt globale Standardwerte von `session.threadBindings` und unterstützt außerdem kanalbezogene Überschreibungen: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -789,27 +731,27 @@ Matrix übernimmt globale Standardwerte aus `session.threadBindings` und unterst - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Threadgebundene Spawn-Flags für Matrix sind Opt-in: +Threadgebundene Spawn-Flags für Matrix sind optional: -- Setzen Sie `threadBindings.spawnSubagentSessions: true`, um zuzulassen, dass `/focus` auf oberster Ebene neue Matrix-Threads erstellt und bindet. -- Setzen Sie `threadBindings.spawnAcpSessions: true`, um zuzulassen, dass `/acp spawn --thread auto|here` ACP-Sitzungen an Matrix-Threads bindet. +- Setzen Sie `threadBindings.spawnSubagentSessions: true`, damit `/focus` auf oberster Ebene neue Matrix-Threads erstellen und binden darf. +- Setzen Sie `threadBindings.spawnAcpSessions: true`, damit `/acp spawn --thread auto|here` ACP-Sitzungen an Matrix-Threads binden darf. ## Reaktionen Matrix unterstützt ausgehende Reaktionsaktionen, eingehende Reaktionsbenachrichtigungen und eingehende Bestätigungsreaktionen. -- Werkzeuge für ausgehende Reaktionen werden durch `channels["matrix"].actions.reactions` gesteuert. +- Ausgehende Reaktions-Tooling 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 diesem Ereignis. -- `remove: true` entfernt nur die angegebene Emoji-Reaktion vom Bot-Konto. +- `emoji=""` entfernt die eigenen Reaktionen des Bot-Kontos auf dieses Ereignis. +- `remove: true` entfernt nur die angegebene Emoji-Reaktion des Bot-Kontos. Der Geltungsbereich von Bestätigungsreaktionen wird in dieser Standardreihenfolge von OpenClaw aufgelöst: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- Agent-Identity-Emoji-Fallback +- Emoji-Fallback der Agent-Identität Der Geltungsbereich von Bestätigungsreaktionen wird in dieser Reihenfolge aufgelöst: @@ -823,33 +765,32 @@ Der Modus für Reaktionsbenachrichtigungen wird in dieser Reihenfolge aufgelöst - `channels["matrix"].reactionNotifications` - Standard: `own` -Aktuelles Verhalten: +Verhalten: -- `reactionNotifications: "own"` leitet hinzugefügte `m.reaction`-Ereignisse weiter, wenn sie auf vom Bot verfasste Matrix-Nachrichten abzielen. -- `reactionNotifications: "off"` deaktiviert Reaktionssystemereignisse. -- Das Entfernen von Reaktionen wird weiterhin nicht in Systemereignisse umgewandelt, da Matrix diese als Redaktionen und nicht als eigenständige `m.reaction`-Entfernungen darstellt. +- `reactionNotifications: "own"` leitet hinzugefügte `m.reaction`-Ereignisse weiter, wenn sie auf vom Bot verfasste Matrix-Nachrichten zielen. +- `reactionNotifications: "off"` deaktiviert Reaktions-Systemereignisse. +- Das Entfernen von Reaktionen wird nicht in Systemereignisse synthetisiert, da Matrix diese als Redactions und nicht als eigenständige `m.reaction`-Entfernungen darstellt. -## Verlaufs-Kontext +## Verlaufskontext -- `channels.matrix.historyLimit` steuert, wie viele aktuelle Raumnachrichten als `InboundHistory` einbezogen werden, wenn eine Matrix-Raumnachricht den Agent auslöst. -- Es greift auf `messages.groupChat.historyLimit` zurück. Wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`, sodass erwähnungsgesteuerte Raumnachrichten nicht gepuffert werden. Setzen Sie `0`, um zu deaktivieren. -- Der Matrix-Raumverlauf ist nur raumbezogen. DMs verwenden weiterhin den normalen Sitzungsverlauf. -- Der Matrix-Raumverlauf 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` einbezogen; sie verbleibt für diesen Zug im Haupttext der eingehenden Nachricht. -- Wiederholungen desselben Matrix-Ereignisses verwenden den ursprünglichen Verlaufs-Snapshot erneut, anstatt zu neueren Raumnachrichten weiterzuwandern. +- `channels.matrix.historyLimit` steuert, wie viele aktuelle Raumnachrichten als `InboundHistory` einbezogen werden, wenn eine Matrix-Raumnachricht den Agenten auslöst. Fällt zurück auf `messages.groupChat.historyLimit`; wenn beides nicht gesetzt ist, ist der effektive Standardwert `0`. Setzen Sie `0`, um dies zu deaktivieren. +- Matrix-Raumverlauf ist nur raumbezogen. DMs verwenden weiterhin den normalen Sitzungsverlauf. +- Matrix-Raumverlauf 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ösende Nachricht ist nicht in `InboundHistory` enthalten; sie bleibt im Haupt-Inbound-Text für diesen Turn. +- Wiederholungen desselben Matrix-Ereignisses verwenden den ursprünglichen Verlaufs-Snapshot erneut, statt sich auf neuere Raumnachrichten vorzuschieben. ## Kontextsichtigkeit 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 wird wie empfangen beibehalten. -- `contextVisibility: "allowlist"` filtert ergänzenden Kontext nach Absendern, die durch die aktiven Raum-/Benutzer-Zulassungslistenprüfungen erlaubt sind. -- `contextVisibility: "allowlist_quote"` verhält sich wie `allowlist`, behält aber weiterhin eine explizit zitierte Antwort bei. +- `contextVisibility: "all"` ist die Standardeinstellung. Ergänzender Kontext bleibt unverändert 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 zusätzlich genau eine explizit zitierte Antwort bei. -Diese Einstellung betrifft die Sichtbarkeit ergänzenden Kontexts, nicht die Frage, ob die eingehende Nachricht selbst eine Antwort auslösen kann. -Die Berechtigung zum Auslösen stammt weiterhin aus `groupPolicy`, `groups`, `groupAllowFrom` und den DM-Richtlinieneinstellungen. +Diese Einstellung beeinflusst die Sichtbarkeit des ergänzenden Kontexts, nicht die Frage, ob die eingehende Nachricht selbst eine Antwort auslösen kann. +Die Autorisierung für Auslöser stammt weiterhin aus `groupPolicy`, `groups`, `groupAllowFrom` und den DM-Richtlinieneinstellungen. -## Beispiel für DM- und Raumrichtlinien +## DM- und Raumrichtlinie ```json5 { @@ -872,38 +813,60 @@ Die Berechtigung zum Auslösen stammt weiterhin aus `groupPolicy`, `groups`, `gr } ``` -Siehe [Groups](/de/channels/groups) für Verhalten bei Erwähnungsgating und Zulassungslisten. +Siehe [Groups](/de/channels/groups) für Erwähnungs-Gating und Allowlist-Verhalten. -Beispiel für Pairing in Matrix-DMs: +Pairing-Beispiel für Matrix-DMs: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Wenn ein nicht genehmigter Matrix-Benutzer Sie vor der Genehmigung weiterhin anschreibt, verwendet OpenClaw denselben ausstehenden Pairing-Code wieder und kann nach einer kurzen Abkühlzeit erneut eine Erinnerungsantwort senden, anstatt einen neuen Code zu erzeugen. +Wenn ein nicht genehmigter Matrix-Benutzer Ihnen vor der Genehmigung weiterhin Nachrichten sendet, verwendet OpenClaw denselben ausstehenden Pairing-Code erneut und sendet nach einer kurzen Abkühlzeit möglicherweise erneut eine Erinnerungsantwort, 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 erhalten, die auf alte Einzelräume statt auf die aktive DM zeigen. Prüfen Sie die aktuelle Zuordnung für einen Peer mit: + +```bash +openclaw matrix direct inspect --user-id @alice:example.org +``` + +Reparieren Sie sie mit: + +```bash +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 gesunde DM existiert + +Der Reparaturablauf löscht alte Räume nicht automatisch. Er wählt nur die gesunde DM aus und aktualisiert die Zuordnung, damit neue Matrix-Sendevorgänge, Verifizierungsmitteilungen und andere Direktnachrichtenabläufe wieder den richtigen Raum ansprechen. + ## Exec-Genehmigungen -Matrix kann als nativer Genehmigungsclient für ein Matrix-Konto dienen. Die nativen -DM-/Kanal-Routing-Regler befinden sich weiterhin unter der Exec-Genehmigungskonfiguration: +Matrix kann für ein Matrix-Konto als nativer Genehmigungsclient fungieren. Die nativen +DM-/Kanal-Routing-Regler liegen weiterhin unter der Exec-Genehmigungskonfiguration: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (optional; greift auf `channels.matrix.dm.allowFrom` zurück) +- `channels.matrix.execApprovals.approvers` (optional; fällt zurück auf `channels.matrix.dm.allowFrom`) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, Standard: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Genehmiger müssen Matrix-Benutzer-IDs wie `@owner:example.org` sein. Matrix aktiviert native Genehmigungen automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und mindestens ein Genehmiger aufgelöst werden kann. Exec-Genehmigungen verwenden zuerst `execApprovals.approvers` und können auf `channels.matrix.dm.allowFrom` zurückgreifen. Plugin-Genehmigungen autorisieren über `channels.matrix.dm.allowFrom`. Setzen Sie `enabled: false`, um Matrix explizit als nativen Genehmigungsclient zu deaktivieren. Genehmigungsanfragen greifen andernfalls auf andere konfigurierte Genehmigungsrouten 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 oder `"auto"` ist 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`. Setzen Sie `enabled: false`, um Matrix explizit als nativen Genehmigungsclient zu deaktivieren. Andernfalls fallen Genehmigungsanfragen auf andere konfigurierte Genehmigungswege oder die Fallback-Richtlinie für Genehmigungen zurück. -Das native Matrix-Routing unterstützt jetzt beide Genehmigungsarten: +Das native Matrix-Routing unterstützt beide Arten von Genehmigungen: - `channels.matrix.execApprovals.*` steuert den nativen DM-/Kanal-Fanout-Modus für Matrix-Genehmigungsaufforderungen. -- Exec-Genehmigungen verwenden die Genehmigermenge für Exec aus `execApprovals.approvers` oder `channels.matrix.dm.allowFrom`. -- Plugin-Genehmigungen verwenden die Matrix-DM-Zulassungsliste aus `channels.matrix.dm.allowFrom`. -- Matrix-Reaktionskürzel und Nachrichtenaktualisierungen gelten für Exec- und Plugin-Genehmigungen. +- Exec-Genehmigungen verwenden die Menge der Exec-Genehmiger aus `execApprovals.approvers` oder `channels.matrix.dm.allowFrom`. +- Plugin-Genehmigungen verwenden die Matrix-DM-Allowlist aus `channels.matrix.dm.allowFrom`. +- Matrix-Reaktionskürzel und Nachrichtenaktualisierungen gelten sowohl für Exec- als auch für Plugin-Genehmigungen. Zustellregeln: @@ -911,25 +874,23 @@ Zustellregeln: - `target: "channel"` sendet die Aufforderung zurück an den ursprünglichen Matrix-Raum oder die ursprüngliche DM - `target: "both"` sendet an Genehmiger-DMs und an den ursprünglichen Matrix-Raum oder die ursprüngliche DM -Matrix-Genehmigungsaufforderungen initialisieren Reaktionskürzel auf der primären Genehmigungsnachricht: +Matrix-Genehmigungsaufforderungen setzen Reaktionskürzel auf der primären Genehmigungsnachricht: -- `✅` = einmal erlauben +- `✅` = einmal zulassen - `❌` = ablehnen -- `♾️` = immer erlauben, wenn diese Entscheidung durch die effektive Exec-Richtlinie zulässig ist +- `♾️` = immer zulassen, wenn diese Entscheidung durch die effektive Exec-Richtlinie erlaubt ist 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 Genehmiger können genehmigen oder ablehnen. Bei Exec-Genehmigungen enthält die Kanalzustellung den Befehlstext, daher sollten `channel` oder `both` nur in vertrauenswürdigen Räumen aktiviert werden. +Nur aufgelöste Genehmiger können zulassen oder ablehnen. Bei Exec-Genehmigungen enthält die Kanalzustellung den Befehlstext, daher sollten Sie `channel` oder `both` nur in vertrauenswürdigen Räumen aktivieren. -Matrix-Genehmigungsaufforderungen verwenden den gemeinsamen Kern-Genehmigungsplaner erneut. Die Matrix-spezifische native Oberfläche verarbeitet Raum-/DM-Routing, Reaktionen sowie das Senden/Aktualisieren/Löschen von Nachrichten für Exec- und Plugin-Genehmigungen. - -Kontoabhängige Überschreibung: +Überschreibung pro Konto: - `channels.matrix.accounts..execApprovals` -Verwandte Dokumentation: [Exec-Genehmigungen](/de/tools/exec-approvals) +Verwandte Dokumentation: [Exec approvals](/de/tools/exec-approvals) -## Beispiel für mehrere Konten +## Mehrere Konten ```json5 { @@ -959,19 +920,21 @@ Verwandte Dokumentation: [Exec-Genehmigungen](/de/tools/exec-approvals) } ``` -Werte auf oberster Ebene in `channels.matrix` fungieren als Standardwerte für benannte Konten, sofern ein Konto sie nicht überschreibt. -Sie können geerbte Raumeinträge mit `groups..account` (oder dem Legacy-Schlüssel `rooms..account`) auf ein 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. -Partielle gemeinsam genutzte Auth-Standardwerte erzeugen für sich genommen kein separates implizites Standardkonto. OpenClaw synthetisiert das oberste `default`-Konto nur dann, wenn dieses Standardkonto frische Authentifizierung 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-Promotion von Einzelkonto zu Mehrkonto dieses Konto, anstatt einen neuen `accounts.default`-Eintrag zu erstellen. Nur Matrix-Auth-/Bootstrap-Schlüssel werden in dieses hochgestufte Konto verschoben; gemeinsam genutzte Richtlinienschlüssel für die Zustellung bleiben auf oberster Ebene. -Setzen Sie `defaultAccount`, wenn OpenClaw ein benanntes Matrix-Konto für implizites Routing, Sondierungen und CLI-Operationen bevorzugen soll. +Werte auf oberster Ebene unter `channels.matrix` dienen als Standardwerte für benannte Konten, sofern ein Konto sie nicht überschreibt. +Sie können geerbte Raumeinträge mit `groups..account` auf ein Matrix-Konto beschränken. +Einträge ohne `account` bleiben über alle Matrix-Konten hinweg gemeinsam, und Einträge mit `account: "default"` funktionieren weiterhin, wenn das Standardkonto direkt auf oberster Ebene unter `channels.matrix.*` konfiguriert ist. +Teilweise gemeinsame Auth-Standardwerte erzeugen für sich allein kein separates implizites Standardkonto. OpenClaw synthetisiert das Standardkonto der obersten Ebene `default` nur dann, wenn dieses Standardkonto frische Authentifizierungsdaten hat (`homeserver` plus `accessToken` oder `homeserver` plus `userId` und `password`); benannte Konten können dennoch durch `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-Promotion von Einzelkonto zu Mehrkonten dieses Konto, statt einen neuen `accounts.default`-Eintrag zu erstellen. Nur Matrix-Auth-/Bootstrap-Schlüssel werden in dieses hochgestufte Konto verschoben; gemeinsame Schlüssel für Zustellrichtlinien bleiben auf oberster Ebene. +Setzen Sie `defaultAccount`, wenn OpenClaw ein benanntes Matrix-Konto für implizites Routing, Probing und CLI-Operationen bevorzugen soll. Wenn Sie mehrere benannte Konten konfigurieren, setzen Sie `defaultAccount` oder übergeben Sie `--account ` für CLI-Befehle, die auf impliziter Kontoauswahl beruhen. -Übergeben Sie `--account ` an `openclaw matrix verify ...` und `openclaw matrix devices ...`, wenn Sie diese implizite Auswahl für einen Befehl überschreiben möchten. +Übergeben Sie `--account ` an `openclaw matrix verify ...` und `openclaw matrix devices ...`, wenn Sie diese implizite Auswahl für einen einzelnen Befehl überschreiben möchten. + +Siehe [Configuration reference](/de/gateway/configuration-reference#multi-account-all-channels) für das gemeinsame Muster für mehrere Konten. ## Private/LAN-Homeserver -Standardmäßig blockiert OpenClaw private/interne Matrix-Homeserver zum Schutz vor SSRF, sofern Sie -nicht pro Konto explizit optieren. +Standardmäßig blockiert OpenClaw private/interne Matrix-Homeserver aus SSRF-Schutzgründen, sofern Sie +nicht pro Konto ausdrücklich optieren. Wenn Ihr Homeserver auf localhost, einer LAN-/Tailscale-IP oder einem internen Hostnamen läuft, aktivieren Sie `network.dangerouslyAllowPrivateNetwork` für dieses Matrix-Konto: @@ -990,7 +953,7 @@ Wenn Ihr Homeserver auf localhost, einer LAN-/Tailscale-IP oder einem internen H } ``` -Beispiel für die CLI-Einrichtung: +CLI-Einrichtungsbeispiel: ```bash openclaw matrix account add \ @@ -1001,9 +964,9 @@ openclaw matrix account add \ ``` Dieses Opt-in erlaubt nur vertrauenswürdige private/interne Ziele. Öffentliche unverschlüsselte Homeserver wie -`http://matrix.example.org:8008` bleiben blockiert. Bevorzugen Sie wann immer möglich `https://`. +`http://matrix.example.org:8008` bleiben blockiert. Bevorzugen Sie nach Möglichkeit `https://`. -## Proxying von Matrix-Datenverkehr +## Matrix-Verkehr über Proxy leiten Wenn Ihre Matrix-Bereitstellung einen expliziten ausgehenden HTTP(S)-Proxy benötigt, setzen Sie `channels.matrix.proxy`: @@ -1019,22 +982,22 @@ Wenn Ihre 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 den Matrix-Laufzeitverkehr und für Sondierungen des Kontostatus. +Benannte Konten können den Standardwert der obersten Ebene mit `channels.matrix.accounts..proxy` überschreiben. +OpenClaw verwendet dieselbe Proxy-Einstellung für laufenden Matrix-Verkehr und Statusprüfungen von Konten. ## Zielauflösung -Matrix akzeptiert diese Zielformen überall dort, wo OpenClaw nach einem Raum- oder Benutzerziel fragt: +Matrix akzeptiert diese Zielformen überall dort, wo OpenClaw Sie 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` -- Aliase: `#alias:server`, `channel:#alias:server` oder `matrix:channel:#alias:server` +- Aliasse: `#alias:server`, `channel:#alias:server` oder `matrix:channel:#alias:server` Die Live-Verzeichnissuche verwendet das angemeldete Matrix-Konto: -- Benutzersuchen fragen das Matrix-Benutzerverzeichnis auf diesem Homeserver ab. -- Raumsuchen akzeptieren explizite Raum-IDs und Aliase direkt und greifen dann auf die Suche nach Namen beigetretener Räume für dieses Konto zurück. -- Die Suche nach Namen beigetretener Räume ist Best-Effort. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird er bei der Laufzeitauflösung der Zulassungsliste ignoriert. +- Benutzerabfragen durchsuchen das Matrix-Benutzerverzeichnis auf diesem Homeserver. +- Raumabfragen akzeptieren explizite Raum-IDs und Aliasse direkt und fallen dann auf die Suche in beigetretenen Raumnamen für dieses Konto zurück. +- Die Suche nach Namen beigetretener Räume erfolgt best effort. Wenn ein Raumname nicht zu einer ID oder einem Alias aufgelöst werden kann, wird er bei der Laufzeit-Allowlist-Auflösung ignoriert. ## Konfigurationsreferenz @@ -1042,64 +1005,63 @@ Die Live-Verzeichnissuche verwendet das angemeldete Matrix-Konto: - `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. Aktivieren Sie dies, wenn der Homeserver auf `localhost`, eine LAN-/Tailscale-IP oder einen 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`: diesem Matrix-Konto erlauben, sich mit privaten/internen Homeservern zu verbinden. Aktivieren Sie 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 der obersten Ebene mit ihrem eigenen `proxy` überschreiben. - `userId`: vollständige Matrix-Benutzer-ID, zum Beispiel `@bot:example.org`. -- `accessToken`: Zugriffstoken für tokenbasierte Authentifizierung. Klartextwerte und SecretRef-Werte werden für `channels.matrix.accessToken` und `channels.matrix.accounts..accessToken` über env/file/exec-Anbieter unterstützt. Siehe [Secrets Management](/de/gateway/secrets). +- `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-Anbieter 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 Passwortanmeldung. -- `avatarUrl`: gespeicherte Selbst-Avatar-URL für Profilsynchronisierung und `set-profile`-Aktualisierungen. -- `initialSyncLimit`: Ereignislimit für den Start-Sync. +- `deviceName`: Gerätename für die Anzeige bei Passwort-Anmeldung. +- `avatarUrl`: gespeicherte Selbst-Avatar-URL für Profilsynchronisierung und `profile set`-Aktualisierungen. +- `initialSyncLimit`: maximale Anzahl an Ereignissen, die während der Start-Synchronisierung abgerufen werden. - `encryption`: E2EE aktivieren. -- `allowlistOnly`: Verhalten nur mit Zulassungsliste für DMs und Räume erzwingen. -- `allowBots`: Nachrichten anderer konfigurierter 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 auf `allowlist` gesetzt. `disabled`-Richtlinien sind davon nicht betroffen. +- `allowBots`: Nachrichten von anderen konfigurierten OpenClaw-Matrix-Konten zulassen (`true` oder `"mentions"`). - `groupPolicy`: `open`, `allowlist` oder `disabled`. - `contextVisibility`: Sichtbarkeitsmodus für ergänzenden Raumkontext (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: Zulassungsliste von Benutzer-IDs für Raumverkehr. -- `groupAllowFrom`-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. Greift auf `messages.groupChat.historyLimit` zurück; wenn beide nicht gesetzt sind, ist der effektive Standardwert `0`. Setzen Sie `0`, um 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 an Raumnachrichten, die als Gruppenverlaufs-Kontext einbezogen werden. Fällt zurück auf `messages.groupChat.historyLimit`; wenn beides nicht gesetzt ist, ist der effektive Standardwert `0`. Setzen Sie `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 Vorschauhinweise für selbstgehostete Push-Regel-Setups. -- `blockStreaming`: `true` aktiviert separate Fortschrittsnachrichten für abgeschlossene Assistant-Blöcke, während Entwurfsvorschau-Streaming 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 Vorschau-Mitteilungen für selbstgehostete Push-Regel-Setups. `false` ist gleichbedeutend mit `"off"`. +- `blockStreaming`: `true` aktiviert separate Fortschrittsnachrichten für abgeschlossene Assistant-Blöcke, während Entwurfs-Vorschau-Streaming aktiv ist. - `threadReplies`: `off`, `inbound` oder `always`. - `threadBindings`: kanalbezogene Überschreibungen für threadgebundenes Sitzungsrouting und Lebenszyklus. -- `startupVerification`: automatischer Selbstverifizierungs-Anfragemodus beim Start (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: Abkühlzeit vor einem erneuten Versuch automatischer Startverifizierungsanfragen. -- `textChunkLimit`: Chunk-Größe für ausgehende Nachrichten. -- `chunkMode`: `length` oder `newline`. -- `responsePrefix`: optionales Nachrichtenpräfix für ausgehende Antworten. +- `startupVerification`: Modus für automatische Selbstverifizierungsanfrage beim Start (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: Abkühlzeit vor einem erneuten Versuch automatischer Start-Verifizierungsanfragen. +- `textChunkLimit`: Größe ausgehender Nachrichten-Chunks in Zeichen (gilt, wenn `chunkMode` `length` 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`). - `reactionNotifications`: Modus für eingehende Reaktionsbenachrichtigungen (`own`, `off`). -- `mediaMaxMb`: Mediengrößenlimit in MB für Matrix-Medienverarbeitung. Es gilt für ausgehende Sendungen und eingehende Medienverarbeitung. -- `autoJoin`: Richtlinie für automatischen Beitritt bei Einladungen (`always`, `allowlist`, `off`). Standard: `off`. Dies gilt allgemein für Matrix-Einladungen, einschließlich Einladungen im DM-Stil, nicht nur für Raum-/Gruppeneinladungen. OpenClaw trifft diese Entscheidung zum Zeitpunkt der Einladung, bevor zuverlässig klassifiziert werden kann, ob der beigetretene Raum eine DM oder eine Gruppe ist. -- `autoJoinAllowlist`: Räume/Aliase, die erlaubt sind, wenn `autoJoin` den Wert `allowlist` hat. Alias-Einträge werden während der Behandlung der Einladung in Raum-IDs aufgelöst; OpenClaw vertraut nicht auf den vom eingeladenen Raum behaupteten Alias-Status. +- `mediaMaxMb`: Mediengrößenlimit in MB für ausgehende Sendungen und eingehende Medienverarbeitung. +- `autoJoin`: Richtlinie für automatischen Beitritt 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 bei der Einladungsverarbeitung zu Raum-IDs aufgelöst; OpenClaw vertraut nicht auf 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. Es ändert nicht, ob einer Einladung automatisch beigetreten wird. -- `dm.allowFrom`-Einträge sollten vollständige Matrix-Benutzer-IDs sein, es sei denn, Sie haben sie bereits über eine Live-Verzeichnissuche aufgelöst. +- `dm.allowFrom`: Einträge sollten vollständige Matrix-Benutzer-IDs sein, sofern Sie sie nicht bereits per Live-Verzeichnissuche aufgelöst haben. - `dm.sessionScope`: `per-user` (Standard) oder `per-room`. Verwenden Sie `per-room`, wenn jeder Matrix-DM-Raum einen separaten Kontext behalten soll, selbst wenn der Peer derselbe ist. -- `dm.threadReplies`: DM-spezifische Überschreibung der Thread-Richtlinie (`off`, `inbound`, `always`). Sie überschreibt die Einstellung `threadReplies` auf oberster Ebene sowohl für die Platzierung von Antworten als auch für die Sitzungsisolierung in DMs. +- `dm.threadReplies`: DM-spezifische Überschreibung der Thread-Richtlinie (`off`, `inbound`, `always`). Sie überschreibt die Einstellung `threadReplies` auf oberster Ebene sowohl für die Antwortplatzierung als auch für die Sitzungsisolation 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 Genehmiger bereits identifiziert. - `execApprovals.target`: `dm | channel | both` (Standard: `dm`). -- `accounts`: benannte kontoabhängige Überschreibungen. Werte auf oberster Ebene in `channels.matrix` fungieren als Standardwerte für diese Einträge. -- `groups`: richtlinienbezogene Zuordnung pro Raum. Bevorzugen Sie Raum-IDs oder Aliase; nicht aufgelöste Raumnamen werden zur Laufzeit ignoriert. Die Sitzungs-/Gruppenidentität verwendet nach der Auflösung die stabile Raum-ID, während menschenlesbare Labels weiterhin von Raumnamen stammen. -- `groups..account`: einen geerbten Raumeintrag in Setups mit mehreren Konten auf ein bestimmtes Matrix-Konto beschränken. -- `groups..allowBots`: Überschreibung auf Raumebene für Absender aus konfigurierten Bot-Konten (`true` oder `"mentions"`). -- `groups..users`: absenderbezogene Zulassungsliste pro Raum. -- `groups..tools`: raumbezogene Tool-Allow/Deny-Überschreibungen. -- `groups..autoReply`: Überschreibung des Erwähnungsgatings auf Raumebene. `true` deaktiviert Erwähnungsanforderungen für diesen Raum; `false` erzwingt sie wieder. +- `accounts`: benannte kontoabhängige Überschreibungen. Werte der obersten Ebene unter `channels.matrix` dienen für diese Einträge als Standardwerte. +- `groups`: raumbezogene Richtlinienzuordnung. Bevorzugen Sie 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`: einen geerbten Raumeintrag in Mehrkonten-Setups auf ein bestimmtes Matrix-Konto beschränken. +- `groups..allowBots`: Überschreibung auf Raumebene für Absender aus konfigurierten Botkonten (`true` oder `"mentions"`). +- `groups..users`: absenderspezifische Allowlist pro Raum. +- `groups..tools`: raumbezogene Tool-Zulassen/Ablehnen-Überschreibungen. +- `groups..autoReply`: Überschreibung der Erwähnungssteuerung auf Raumebene. `true` deaktiviert Erwähnungspflichten für diesen Raum; `false` erzwingt sie wieder. - `groups..skills`: optionaler Skill-Filter auf Raumebene. -- `groups..systemPrompt`: optionales systemPrompt-Snippet auf Raumebene. -- `rooms`: Legacy-Alias für `groups`. +- `groups..systemPrompt`: optionales Snippet für den System-Prompt auf Raumebene. +- `rooms`: veralteter 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 - [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ähnungssteuerung - [Channel Routing](/de/channels/channel-routing) — Sitzungsrouting für Nachrichten - [Security](/de/gateway/security) — Zugriffsmodell und Härtung diff --git a/docs/de/concepts/agent-loop.md b/docs/de/concepts/agent-loop.md index bfe43efa3..a1b43aa31 100644 --- a/docs/de/concepts/agent-loop.md +++ b/docs/de/concepts/agent-loop.md @@ -1,175 +1,177 @@ --- read_when: - - Sie benötigen eine genaue Schritt-für-Schritt-Erklärung der Agent-Schleife oder der Lebenszyklusereignisse -summary: Lebenszyklus der Agent-Schleife, Streams und Wait-Semantik -title: Agent Loop + - Sie benötigen eine genaue Schritt-für-Schritt-Erklärung der Agentenschleife oder der Lebenszyklusereignisse +summary: Lebenszyklus der Agentenschleife, Streams und Warte-Semantik +title: Agentenschleife x-i18n: - generated_at: "2026-04-05T12:39:43Z" + generated_at: "2026-04-09T01:28:00Z" model: gpt-5.4 provider: openai - source_hash: 8e562e63c494881e9c345efcb93c5f972d69aaec61445afc3d4ad026b2d26883 + source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1 source_path: concepts/agent-loop.md workflow: 15 --- -# Agent Loop (OpenClaw) +# Agentenschleife (OpenClaw) -Eine agentische Schleife ist der vollständige „echte“ Lauf eines Agent: Eingang → Kontextzusammenstellung → Modellinferenz → -Tool-Ausführung → Streaming-Antworten → Persistenz. Es ist der maßgebliche Pfad, der eine Nachricht +Eine agentische Schleife ist der vollständige „echte“ Lauf eines Agenten: Eingabe → Kontextzusammenstellung → Modellinferenz → +Werkzeugausführung → gestreamte Antworten → Persistenz. Es ist der maßgebliche Pfad, der eine Nachricht in Aktionen und eine endgültige Antwort umwandelt und dabei den Sitzungszustand konsistent hält. -In OpenClaw ist eine Schleife ein einzelner, serialisierter Lauf pro Sitzung, der Lebenszyklus- und Stream-Ereignisse -ausgibt, während das Modell nachdenkt, Tools aufruft und Ausgabe streamt. Dieses Dokument erklärt, wie diese -authentische Schleife Ende-zu-Ende verdrahtet ist. +In OpenClaw ist eine Schleife ein einzelner, serialisierter Lauf pro Sitzung, der Lebenszyklus- und Stream-Ereignisse ausgibt, +während das Modell nachdenkt, Werkzeuge aufruft und Ausgaben streamt. Dieses Dokument erklärt, wie diese authentische Schleife Ende-zu-Ende +verdrahtet ist. ## Einstiegspunkte -- Gateway-RPC: `agent` und `agent.wait`. +- Gateway RPC: `agent` und `agent.wait`. - CLI: Befehl `agent`. -## Funktionsweise (allgemein) +## Funktionsweise (Überblick) -1. Die RPC `agent` validiert Parameter, löst die Sitzung auf (sessionKey/sessionId), persistiert Sitzungsmetadaten und gibt sofort `{ runId, acceptedAt }` zurück. -2. `agentCommand` führt den Agent aus: - - löst Modell- + Thinking-/Verbose-Standards auf +1. RPC `agent` validiert Parameter, löst die Sitzung auf (`sessionKey`/`sessionId`), persistiert Sitzungsmetadaten und gibt sofort `{ runId, acceptedAt }` zurück. +2. `agentCommand` führt den Agenten aus: + - löst Modell- sowie Thinking-/Verbose-Standards auf - lädt den Skills-Snapshot - ruft `runEmbeddedPiAgent` auf (Laufzeit von pi-agent-core) - - gibt **Lebenszyklus-Ende/Fehler** aus, wenn die eingebettete Schleife kein entsprechendes Ereignis ausgibt + - gibt **Lebenszyklus-Ende/Fehler** aus, wenn die eingebettete Schleife keines davon ausgibt 3. `runEmbeddedPiAgent`: - - serialisiert Läufe über Warteschlangen pro Sitzung und global - - löst Modell + Auth-Profil auf und erstellt die Pi-Sitzung - - abonniert Pi-Ereignisse und streamt Assistant-/Tool-Deltas + - serialisiert Läufe über sitzungsbezogene und globale Queues + - löst Modell- und Auth-Profil auf und erstellt die Pi-Sitzung + - abonniert Pi-Ereignisse und streamt Assistant-/Werkzeug-Deltas - erzwingt ein Timeout -> bricht den Lauf bei Überschreitung ab - - gibt Nutzlasten + Nutzungsmetadaten zurück + - gibt Nutzlasten und Nutzungsmetadaten zurück 4. `subscribeEmbeddedPiSession` überbrückt pi-agent-core-Ereignisse zum OpenClaw-`agent`-Stream: - - Tool-Ereignisse => `stream: "tool"` + - Werkzeugereignisse => `stream: "tool"` - Assistant-Deltas => `stream: "assistant"` - Lebenszyklusereignisse => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` verwendet `waitForAgentRun`: - wartet auf **Lebenszyklus-Ende/Fehler** für `runId` - gibt `{ status: ok|error|timeout, startedAt, endedAt, error? }` zurück -## Warteschlangen + Parallelität +## Queueing + Nebenläufigkeit -- Läufe werden pro Sitzungsschlüssel serialisiert (Sitzungs-Lane) und optional über eine globale Lane. -- Dies verhindert Tool-/Sitzungs-Rennen und hält den Sitzungsverlauf konsistent. -- Messaging-Kanäle können Warteschlangenmodi wählen (collect/steer/followup), die dieses Lane-System speisen. - Siehe [Command Queue](/concepts/queue). +- Läufe werden pro Sitzungsschlüssel (Sitzungs-Lane) und optional über eine globale Lane serialisiert. +- Dies verhindert Wettlaufsituationen bei Werkzeugen/Sitzungen und hält den Sitzungsverlauf konsistent. +- Messaging-Kanäle können Queue-Modi auswählen (collect/steer/followup), die in dieses Lane-System einspeisen. + Siehe [Befehlswarteschlange](/de/concepts/queue). -## Vorbereitung von Sitzung + Workspace +## Sitzungs- und Workspace-Vorbereitung -- Der Workspace wird aufgelöst und erstellt; sandboxed Läufe können zu einem Sandbox-Workspace-Stamm umgeleitet werden. -- Skills werden geladen (oder aus einem Snapshot wiederverwendet) und in env und Prompt injiziert. -- Bootstrap-/Kontextdateien werden aufgelöst und in den Bericht zum System-Prompt injiziert. +- Der Workspace wird aufgelöst und erstellt; sandboxed Läufe können auf ein Sandbox-Workspace-Stammverzeichnis umgeleitet werden. +- Skills werden geladen (oder aus einem Snapshot wiederverwendet) und in Umgebungsvariablen und Prompt injiziert. +- Bootstrap-/Kontextdateien werden aufgelöst und in den Bericht des System-Prompts injiziert. - Eine Schreibsperre für die Sitzung wird erworben; `SessionManager` wird geöffnet und vor dem Streaming vorbereitet. ## Prompt-Zusammenstellung + System-Prompt -- Der System-Prompt wird aus dem Basis-Prompt von OpenClaw, dem Skills-Prompt, dem Bootstrap-Kontext und Überschreibungen pro Lauf aufgebaut. -- Modellspezifische Limits und Reserve-Token für Compaction werden erzwungen. -- Siehe [System prompt](/concepts/system-prompt), um zu sehen, was das Modell sieht. +- Der System-Prompt wird aus dem Basisprompt von OpenClaw, dem Skills-Prompt, dem Bootstrap-Kontext und laufspezifischen Überschreibungen aufgebaut. +- Modellspezifische Limits und für Kompaktierung reservierte Tokens werden erzwungen. +- Unter [System-Prompt](/de/concepts/system-prompt) sehen Sie, was das Modell sieht. -## Hook-Punkte (an denen Sie eingreifen können) +## Hook-Punkte (wo Sie eingreifen können) OpenClaw hat zwei Hook-Systeme: - **Interne Hooks** (Gateway-Hooks): ereignisgesteuerte Skripte für Befehle und Lebenszyklusereignisse. -- **Plugin-Hooks**: Erweiterungspunkte innerhalb des Agent-/Tool-Lebenszyklus und der Gateway-Pipeline. +- **Plugin-Hooks**: Erweiterungspunkte innerhalb des Agenten-/Werkzeug-Lebenszyklus und der Gateway-Pipeline. ### Interne Hooks (Gateway-Hooks) -- **`agent:bootstrap`**: läuft beim Erstellen von Bootstrap-Dateien, bevor der System-Prompt finalisiert wird. - Verwenden Sie dies, um Bootstrap-Kontextdateien hinzuzufügen/zu entfernen. -- **Befehls-Hooks**: `/new`, `/reset`, `/stop` und andere Befehlsereignisse (siehe Hooks-Dokumentation). +- **`agent:bootstrap`**: wird ausgeführt, während Bootstrap-Dateien erstellt werden, bevor der System-Prompt finalisiert wird. + Verwenden Sie dies, um Bootstrap-Kontextdateien hinzuzufügen oder zu entfernen. +- **Befehls-Hooks**: `/new`, `/reset`, `/stop` und andere Befehlsereignisse (siehe Hook-Dokumentation). -Siehe [Hooks](/automation/hooks) für Einrichtung und Beispiele. +Unter [Hooks](/de/automation/hooks) finden Sie Einrichtung und Beispiele. -### Plugin-Hooks (Lebenszyklus von Agent + Gateway) +### Plugin-Hooks (Agenten- und Gateway-Lebenszyklus) -Diese laufen innerhalb der Agent-Schleife oder Gateway-Pipeline: +Diese werden innerhalb der Agentenschleife oder der Gateway-Pipeline ausgeführt: -- **`before_model_resolve`**: läuft vor der Sitzung (ohne `messages`), um Provider/Modell deterministisch vor der Modellauflösung zu überschreiben. -- **`before_prompt_build`**: läuft nach dem Laden der Sitzung (mit `messages`), um `prependContext`, `systemPrompt`, `prependSystemContext` oder `appendSystemContext` vor dem Übermitteln des Prompt einzufügen. Verwenden Sie `prependContext` für dynamischen Text pro Durchlauf und die System-Kontext-Felder für stabile Anleitung, die im Bereich des System-Prompt liegen sollte. -- **`before_agent_start`**: veralteter Kompatibilitäts-Hook, der in beiden Phasen laufen kann; bevorzugen Sie die expliziten Hooks oben. -- **`before_agent_reply`**: läuft nach Inline-Aktionen und vor dem LLM-Aufruf und erlaubt es einem Plugin, den Durchlauf zu übernehmen und eine synthetische Antwort zurückzugeben oder den Durchlauf vollständig stummzuschalten. -- **`agent_end`**: prüft die endgültige Nachrichtenliste und Metadaten des Laufs nach dem Abschluss. -- **`before_compaction` / `after_compaction`**: beobachten oder annotieren Compaction-Zyklen. -- **`before_tool_call` / `after_tool_call`**: fangen Tool-Parameter/-Ergebnisse ab. -- **`before_install`**: prüft integrierte Scan-Ergebnisse und kann Installationen von Skills oder Plugins optional blockieren. -- **`tool_result_persist`**: transformiert Tool-Ergebnisse synchron, bevor sie in das Sitzungs-Transkript geschrieben werden. -- **`message_received` / `message_sending` / `message_sent`**: Hooks für eingehende + ausgehende Nachrichten. +- **`before_model_resolve`**: wird vor der Sitzung ausgeführt (ohne `messages`), um Provider/Modell vor der Modellauflösung deterministisch zu überschreiben. +- **`before_prompt_build`**: wird nach dem Laden der Sitzung ausgeführt (mit `messages`), um `prependContext`, `systemPrompt`, `prependSystemContext` oder `appendSystemContext` vor dem Senden des Prompts einzuschleusen. Verwenden Sie `prependContext` für dynamischen Text pro Turn und die Systemkontext-Felder für stabile Hinweise, die im Bereich des System-Prompts liegen sollen. +- **`before_agent_start`**: Legacy-Kompatibilitätshook, der in beiden Phasen ausgeführt werden kann; bevorzugen Sie die expliziten Hooks oben. +- **`before_agent_reply`**: wird nach Inline-Aktionen und vor dem LLM-Aufruf ausgeführt und ermöglicht es einem Plugin, den Turn zu übernehmen und eine synthetische Antwort zurückzugeben oder den Turn vollständig stummzuschalten. +- **`agent_end`**: inspiziert die endgültige Nachrichtenliste und Metadaten des Laufs nach Abschluss. +- **`before_compaction` / `after_compaction`**: beobachten oder annotieren Kompaktierungszyklen. +- **`before_tool_call` / `after_tool_call`**: fangen Werkzeugparameter/-ergebnisse ab. +- **`before_install`**: inspiziert integrierte Scan-Ergebnisse und kann Skill- oder Plugin-Installationen optional blockieren. +- **`tool_result_persist`**: transformiert Werkzeugergebnisse synchron, bevor sie in das Sitzungsprotokoll geschrieben werden. +- **`message_received` / `message_sending` / `message_sent`**: Hooks für eingehende und ausgehende Nachrichten. - **`session_start` / `session_end`**: Grenzen des Sitzungslebenszyklus. -- **`gateway_start` / `gateway_stop`**: Lebenszyklusereignisse des Gateway. +- **`gateway_start` / `gateway_stop`**: Gateway-Lebenszyklusereignisse. -Entscheidungsregeln für Hooks bei ausgehenden/Tool-Guards: +Entscheidungsregeln für ausgehende/Werkzeug-Schutzmechanismen bei Hooks: -- `before_tool_call`: `{ block: true }` ist terminal und stoppt Handler mit niedrigerer Priorität. -- `before_tool_call`: `{ block: false }` ist ein No-op und hebt eine frühere Blockierung nicht auf. -- `before_install`: `{ block: true }` ist terminal und stoppt Handler mit niedrigerer Priorität. -- `before_install`: `{ block: false }` ist ein No-op und hebt eine frühere Blockierung nicht auf. -- `message_sending`: `{ cancel: true }` ist terminal und stoppt Handler mit niedrigerer Priorität. -- `message_sending`: `{ cancel: false }` ist ein No-op und hebt einen früheren Abbruch nicht auf. +- `before_tool_call`: `{ block: true }` ist final und stoppt Handler mit niedrigerer Priorität. +- `before_tool_call`: `{ block: false }` ist eine No-Op und hebt eine vorherige Blockierung nicht auf. +- `before_install`: `{ block: true }` ist final und stoppt Handler mit niedrigerer Priorität. +- `before_install`: `{ block: false }` ist eine No-Op und hebt eine vorherige Blockierung nicht auf. +- `message_sending`: `{ cancel: true }` ist final und stoppt Handler mit niedrigerer Priorität. +- `message_sending`: `{ cancel: false }` ist eine No-Op und hebt einen vorherigen Abbruch nicht auf. -Siehe [Plugin hooks](/plugins/architecture#provider-runtime-hooks) für die Hook-API und Registrierungsdetails. +Unter [Plugin-Hooks](/de/plugins/architecture#provider-runtime-hooks) finden Sie die Hook-API sowie Details zur Registrierung. ## Streaming + partielle Antworten -- Assistant-Deltas werden aus pi-agent-core gestreamt und als `assistant`-Ereignisse ausgegeben. +- Assistant-Deltas werden von pi-agent-core gestreamt und als `assistant`-Ereignisse ausgegeben. - Block-Streaming kann partielle Antworten entweder bei `text_end` oder `message_end` ausgeben. -- Reasoning-Streaming kann als separater Stream oder als Block-Antworten ausgegeben werden. -- Siehe [Streaming](/concepts/streaming) für Chunking und das Verhalten von Block-Antworten. +- Reasoning-Streaming kann als separater Stream oder als Blockantworten ausgegeben werden. +- Unter [Streaming](/de/concepts/streaming) finden Sie Informationen zum Chunking und zum Verhalten von Blockantworten. -## Tool-Ausführung + Messaging-Tools +## Werkzeugausführung + Messaging-Werkzeuge -- Tool-Start-/Update-/Ende-Ereignisse werden im `tool`-Stream ausgegeben. -- Tool-Ergebnisse werden vor dem Protokollieren/Ausgeben hinsichtlich Größe und Bildnutzlasten bereinigt. -- Sendungen von Messaging-Tools werden verfolgt, um doppelte Bestätigungen des Assistant zu unterdrücken. +- Ereignisse für Start/Aktualisierung/Ende von Werkzeugen werden im `tool`-Stream ausgegeben. +- Werkzeugergebnisse werden vor dem Protokollieren/Ausgeben in Bezug auf Größe und Bildnutzlasten bereinigt. +- Sendevorgänge von Messaging-Werkzeugen werden verfolgt, um doppelte Bestätigungen durch den Assistant zu unterdrücken. ## Antwortformung + Unterdrückung -- Endgültige Nutzlasten werden zusammengesetzt aus: +- Endgültige Nutzlasten werden zusammengestellt aus: - Assistant-Text (und optional Reasoning) - - Inline-Tool-Zusammenfassungen (wenn verbose + erlaubt) - - Assistant-Fehlertext, wenn das Modell einen Fehler erzeugt -- Das exakte Silent-Token `NO_REPLY` / `no_reply` wird aus ausgehenden + - Inline-Werkzeugzusammenfassungen (wenn verbose + erlaubt) + - Assistant-Fehlertext bei Modellfehlern +- Das exakte stumme Token `NO_REPLY` / `no_reply` wird aus ausgehenden Nutzlasten herausgefiltert. -- Duplikate von Messaging-Tools werden aus der endgültigen Nutzlastliste entfernt. -- Wenn keine darstellbaren Nutzlasten übrig bleiben und ein Tool einen Fehler erzeugt hat, wird eine Fallback-Tool-Fehlerantwort ausgegeben - (es sei denn, ein Messaging-Tool hat bereits eine für den Benutzer sichtbare Antwort gesendet). +- Duplikate von Messaging-Werkzeugen werden aus der endgültigen Nutzlastliste entfernt. +- Wenn keine darstellbaren Nutzlasten verbleiben und ein Werkzeug einen Fehler erzeugt hat, wird + eine Fallback-Antwort für Werkzeugfehler ausgegeben + (es sei denn, ein Messaging-Werkzeug hat bereits eine für Benutzer sichtbare Antwort gesendet). -## Compaction + Wiederholungen +## Kompaktierung + Wiederholungen -- Auto-Compaction gibt `compaction`-Stream-Ereignisse aus und kann eine Wiederholung auslösen. -- Bei einer Wiederholung werden In-Memory-Puffer und Tool-Zusammenfassungen zurückgesetzt, um doppelte Ausgabe zu vermeiden. -- Siehe [Compaction](/concepts/compaction) für die Compaction-Pipeline. +- Die automatische Kompaktierung gibt `compaction`-Stream-Ereignisse aus und kann eine Wiederholung auslösen. +- Bei einer Wiederholung werden In-Memory-Puffer und Werkzeugzusammenfassungen zurückgesetzt, um doppelte Ausgaben zu vermeiden. +- Unter [Kompaktierung](/de/concepts/compaction) finden Sie die Kompaktierungs-Pipeline. ## Ereignis-Streams (heute) - `lifecycle`: ausgegeben von `subscribeEmbeddedPiSession` (und als Fallback von `agentCommand`) -- `assistant`: gestreamte Deltas aus pi-agent-core -- `tool`: gestreamte Tool-Ereignisse aus pi-agent-core +- `assistant`: gestreamte Deltas von pi-agent-core +- `tool`: gestreamte Werkzeugereignisse von pi-agent-core -## Behandlung von Chat-Kanälen +## Handhabung von Chat-Kanälen - Assistant-Deltas werden in Chat-`delta`-Nachrichten gepuffert. - Ein Chat-`final` wird bei **Lebenszyklus-Ende/Fehler** ausgegeben. ## Timeouts -- Standard von `agent.wait`: 30 s (nur das Warten). Der Parameter `timeoutMs` überschreibt dies. -- Agent-Laufzeit: Standard von `agents.defaults.timeoutSeconds` ist 172800 s (48 Stunden); erzwungen im Abbruch-Timer von `runEmbeddedPiAgent`. +- Standard für `agent.wait`: 30 s (nur das Warten). Der Parameter `timeoutMs` überschreibt dies. +- Agentenlaufzeit: Standard für `agents.defaults.timeoutSeconds` ist 172800 s (48 Stunden); erzwungen im Abort-Timer von `runEmbeddedPiAgent`. +- LLM-Leerlauf-Timeout: `agents.defaults.llm.idleTimeoutSeconds` bricht eine Modellanfrage ab, wenn vor Ablauf des Leerlauffensters keine Antwort-Chunks eintreffen. Legen Sie es explizit für langsame lokale Modelle oder Reasoning-/Werkzeugaufruf-Provider fest; setzen Sie es auf 0, um es zu deaktivieren. Wenn es nicht gesetzt ist, verwendet OpenClaw `agents.defaults.timeoutSeconds`, falls konfiguriert, andernfalls 60 s. Durch Cron ausgelöste Läufe ohne explizites LLM- oder Agenten-Timeout deaktivieren den Leerlauf-Wächter und verlassen sich auf das äußere Cron-Timeout. -## Wo Dinge frühzeitig enden können +## Wo Dinge vorzeitig enden können -- Agent-Timeout (Abbruch) -- AbortSignal (Abbrechen) +- Agenten-Timeout (Abbruch) +- AbortSignal (Abbruch) - Gateway-Trennung oder RPC-Timeout -- `agent.wait`-Timeout (nur Warten, stoppt den Agent nicht) +- `agent.wait`-Timeout (nur Warten, stoppt den Agenten nicht) ## Verwandt -- [Tools](/tools) — verfügbare Agent-Tools -- [Hooks](/automation/hooks) — ereignisgesteuerte Skripte, die durch Lebenszyklusereignisse des Agent ausgelöst werden -- [Compaction](/concepts/compaction) — wie lange Konversationen zusammengefasst werden -- [Exec Approvals](/tools/exec-approvals) — Genehmigungs-Gates für Shell-Befehle -- [Thinking](/tools/thinking) — Konfiguration der Thinking-/Reasoning-Stufe +- [Werkzeuge](/de/tools) — verfügbare Agentenwerkzeuge +- [Hooks](/de/automation/hooks) — ereignisgesteuerte Skripte, die durch Agenten-Lebenszyklusereignisse ausgelöst werden +- [Kompaktierung](/de/concepts/compaction) — wie lange Unterhaltungen zusammengefasst werden +- [Exec-Genehmigungen](/de/tools/exec-approvals) — Genehmigungsschranken für Shell-Befehle +- [Thinking](/de/tools/thinking) — Konfiguration der Thinking-/Reasoning-Stufe diff --git a/docs/de/concepts/dreaming.md b/docs/de/concepts/dreaming.md index 55fd96a04..240118720 100644 --- a/docs/de/concepts/dreaming.md +++ b/docs/de/concepts/dreaming.md @@ -1,68 +1,68 @@ --- read_when: - - Sie möchten, dass die Erinnerungs-Promotion automatisch ausgeführt wird - - Sie möchten verstehen, was jede Dreaming-Phase bewirkt + - Sie möchten, dass die Speicherpromotion automatisch ausgeführt wird + - Sie möchten verstehen, was jede Träumphase bewirkt - Sie möchten die Konsolidierung abstimmen, ohne `MEMORY.md` zu überladen -summary: Hintergrund-Konsolidierung von Erinnerungen mit Light-, Deep- und REM-Phasen sowie einem Dream Diary -title: Dreaming (experimentell) +summary: Hintergrundkonsolidierung von Speicherinhalten mit Light-, Deep- und REM-Phasen sowie einem Traumtagebuch +title: Träumen (experimentell) x-i18n: - generated_at: "2026-04-06T06:21:04Z" + generated_at: "2026-04-09T01:27:43Z" model: gpt-5.4 provider: openai - source_hash: 36c4b1e70801d662090dc8ce20608c2f141c23cd7ce53c54e3dcf332c801fd4e + source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef source_path: concepts/dreaming.md workflow: 15 --- -# Dreaming (experimentell) +# Träumen (experimentell) -Dreaming ist das Hintergrundsystem zur Konsolidierung von Erinnerungen in `memory-core`. -Es hilft OpenClaw dabei, starke kurzfristige Signale in dauerhafte Erinnerungen zu überführen, -während der Prozess nachvollziehbar und überprüfbar bleibt. +Träumen ist das Hintergrundsystem zur Konsolidierung von Speicherinhalten in `memory-core`. +Es hilft OpenClaw dabei, starke kurzfristige Signale in dauerhafte Speicherinhalte zu überführen, während +der Prozess nachvollziehbar und überprüfbar bleibt. -Dreaming ist **optional** und standardmäßig deaktiviert. +Träumen ist **optional** und standardmäßig deaktiviert. -## Was Dreaming schreibt +## Was Träumen schreibt -Dreaming verwaltet zwei Arten von Ausgaben: +Träumen verwaltet zwei Arten von Ausgaben: -- **Maschinenzustand** in `memory/.dreams/` (Recall-Speicher, Phasensignale, Ingestion-Checkpoints, Sperren). -- **Menschenlesbare Ausgabe** in `DREAMS.md` (oder vorhandenem `dreams.md`) und optionalen Phasenberichtdateien unter `memory/dreaming//YYYY-MM-DD.md`. +- **Maschinenzustand** in `memory/.dreams/` (Recall-Speicher, Phasensignale, Ingestion-Prüfpunkte, Sperren). +- **Menschenlesbare Ausgabe** in `DREAMS.md` (oder vorhandener `dreams.md`) und optionalen Phasenberichtdateien unter `memory/dreaming//YYYY-MM-DD.md`. Die langfristige Promotion schreibt weiterhin nur in `MEMORY.md`. ## Phasenmodell -Dreaming verwendet drei kooperative Phasen: +Träumen verwendet drei kooperative Phasen: -| Phase | Zweck | Dauerhafter Schreibvorgang | -| ----- | ------------------------------------------------ | -------------------------- | -| Light | Aktuelles kurzfristiges Material sortieren und vorbereiten | Nein | -| Deep | Dauerhafte Kandidaten bewerten und promovieren | Ja (`MEMORY.md`) | +| Phase | Zweck | Dauerhafter Schreibvorgang | +| ----- | ----------------------------------------- | -------------------------- | +| Light | Jüngstes kurzfristiges Material sortieren und vorbereiten | Nein | +| Deep | Dauerhafte Kandidaten bewerten und befördern | Ja (`MEMORY.md`) | | REM | Über Themen und wiederkehrende Ideen reflektieren | Nein | -Diese Phasen sind interne Implementierungsdetails, keine separaten, vom Benutzer konfigurierbaren +Diese Phasen sind interne Implementierungsdetails, keine separat vom Benutzer konfigurierbaren „Modi“. ### Light-Phase -Die Light-Phase erfasst aktuelle tägliche Erinnerungssignale und Recall-Traces, entfernt Duplikate +Die Light-Phase erfasst aktuelle tägliche Speichersignale und Recall-Traces, dedupliziert sie und bereitet Kandidatenzeilen vor. -- Liest aus dem kurzfristigen Recall-Zustand und aktuellen täglichen Erinnerungsdateien. +- Liest aus kurzfristigem Recall-Zustand, aktuellen täglichen Speicherdateien und redigierten Sitzungsabschriften, sofern verfügbar. - Schreibt einen verwalteten Block `## Light Sleep`, wenn der Speicher Inline-Ausgabe enthält. -- Erfasst Verstärkungssignale für ein späteres Deep-Ranking. +- Zeichnet Verstärkungssignale für die spätere Deep-Rangfolge auf. - Schreibt niemals in `MEMORY.md`. ### Deep-Phase -Die Deep-Phase entscheidet, was zu einer langfristigen Erinnerung wird. +Die Deep-Phase entscheidet, was zu langfristigem Speicher wird. -- Bewertet Kandidaten anhand gewichteter Scores und Schwellenwert-Gates. -- Erfordert das Bestehen von `minScore`, `minRecallCount` und `minUniqueQueries`. -- Hydriert Snippets vor dem Schreiben aus aktiven Tagesdateien erneut, sodass veraltete/gelöschte Snippets übersprungen werden. -- Hängt promovierte Einträge an `MEMORY.md` an. -- Schreibt eine Zusammenfassung `## Deep Sleep` in `DREAMS.md` und optional `memory/dreaming/deep/YYYY-MM-DD.md`. +- Ordnet Kandidaten mithilfe gewichteter Bewertung und Schwellenwert-Gates ein. +- Erfordert, dass `minScore`, `minRecallCount` und `minUniqueQueries` erfüllt werden. +- Stellt Snippets vor dem Schreiben aus aktiven täglichen Dateien wieder her, sodass veraltete oder gelöschte Snippets übersprungen werden. +- Hängt beförderte Einträge an `MEMORY.md` an. +- Schreibt eine Zusammenfassung `## Deep Sleep` in `DREAMS.md` und schreibt optional `memory/dreaming/deep/YYYY-MM-DD.md`. ### REM-Phase @@ -70,39 +70,59 @@ Die REM-Phase extrahiert Muster und reflektierende Signale. - Erstellt Themen- und Reflexionszusammenfassungen aus aktuellen kurzfristigen Traces. - Schreibt einen verwalteten Block `## REM Sleep`, wenn der Speicher Inline-Ausgabe enthält. -- Erfasst REM-Verstärkungssignale, die vom Deep-Ranking verwendet werden. +- Zeichnet REM-Verstärkungssignale auf, die von der Deep-Rangfolge verwendet werden. - Schreibt niemals in `MEMORY.md`. -## Dream Diary +## Aufnahme von Sitzungsabschriften -Dreaming führt außerdem ein erzählerisches **Dream Diary** in `DREAMS.md`. -Sobald nach jeder Phase genügend Material vorhanden ist, führt `memory-core` im Hintergrund -best-effort einen Subagent-Durchlauf aus (mit dem Standard-Laufzeitmodell) und hängt einen kurzen Tagebucheintrag an. +Träumen kann redigierte Sitzungsabschriften in den Träum-Korpus aufnehmen. Wenn +Abschriften verfügbar sind, werden sie zusammen mit täglichen +Speichersignalen und Recall-Traces in die Light-Phase eingespeist. Persönliche und sensible Inhalte werden vor der Aufnahme redigiert. -Dieses Tagebuch ist zum Lesen durch Menschen in der Dreams-UI gedacht, nicht als Quelle für Promotion. +## Traumtagebuch -## Deep-Ranking-Signale +Träumen führt außerdem ein erzählerisches **Traumtagebuch** in `DREAMS.md`. +Nachdem jede Phase genügend Material hat, führt `memory-core` im Hintergrund nach bestem Bemühen einen +Subagenten-Durchlauf aus (unter Verwendung des Standard-Laufzeitmodells) und hängt einen kurzen Tagebucheintrag an. -Das Deep-Ranking verwendet sechs gewichtete Basissignale plus Phasenverstärkung: +Dieses Tagebuch ist für menschliches Lesen in der Dreams-Benutzeroberfläche gedacht, nicht als Promotionsquelle. -| Signal | Gewicht | Beschreibung | -| ------------------- | ------- | ----------------------------------------------- | -| Häufigkeit | 0.24 | Wie viele kurzfristige Signale der Eintrag angesammelt hat | -| Relevanz | 0.30 | Durchschnittliche Abrufqualität für den Eintrag | -| Anfragevielfalt | 0.15 | Unterschiedliche Anfrage-/Tageskontexte, in denen er auftauchte | -| Aktualität | 0.15 | Zeitabklingender Frische-Score | -| Konsolidierung | 0.10 | Stärke des Wiederauftretens über mehrere Tage | -| Konzeptuelle Dichte | 0.06 | Dichte von Konzept-Tags aus Snippet/Pfad | +Es gibt außerdem einen fundierten historischen Backfill-Pfad für Prüf- und Wiederherstellungsarbeiten: -Treffer aus der Light- und REM-Phase fügen einen kleinen, zeitabklingenden Boost aus +- `memory rem-harness --path ... --grounded` zeigt eine Vorschau der fundierten Tagebuchausgabe aus historischen Notizen `YYYY-MM-DD.md`. +- `memory rem-backfill --path ...` schreibt reversible fundierte Tagebucheinträge in `DREAMS.md`. +- `memory rem-backfill --path ... --stage-short-term` stellt fundierte dauerhafte Kandidaten in denselben kurzfristigen Evidenzspeicher ein, den die normale Deep-Phase bereits verwendet. +- `memory rem-backfill --rollback` und `--rollback-short-term` entfernen diese bereitgestellten Backfill-Artefakte, ohne normale Tagebucheinträge oder aktiven kurzfristigen Recall zu berühren. + +Die Control UI bietet denselben Tagebuch-Backfill-/Zurücksetzen-Ablauf, damit Sie +Ergebnisse in der Dreams-Ansicht prüfen können, bevor Sie entscheiden, ob die fundierten Kandidaten +eine Promotion verdienen. Die Ansicht zeigt außerdem einen separaten fundierten Pfad, damit Sie sehen können, +welche bereitgestellten kurzfristigen Einträge aus historischem Replay stammen, welche beförderten +Elemente fundiert ausgelöst wurden, und fundiert-only bereitgestellte Einträge löschen können, ohne +den normalen aktiven kurzfristigen Zustand zu berühren. + +## Deep-Rangfolgesignale + +Die Deep-Rangfolge verwendet sechs gewichtete Basissignale plus Phasenverstärkung: + +| Signal | Gewicht | Beschreibung | +| ------------------- | ------- | ------------------------------------------------ | +| Häufigkeit | 0.24 | Wie viele kurzfristige Signale der Eintrag gesammelt hat | +| Relevanz | 0.30 | Durchschnittliche Abrufqualität für den Eintrag | +| Abfragevielfalt | 0.15 | Unterschiedliche Abfrage-/Tageskontexte, in denen er erschien | +| Aktualität | 0.15 | Zeitlich abklingender Frischewert | +| Konsolidierung | 0.10 | Stärke des Wiederauftretens über mehrere Tage | +| Konzeptionelle Dichte | 0.06 | Dichte der Konzept-Tags aus Snippet/Pfad | + +Treffer aus der Light- und REM-Phase fügen einen kleinen, mit der Aktualität abklingenden Boost aus `memory/.dreams/phase-signals.json` hinzu. -## Zeitplanung +## Planung -Wenn aktiviert, verwaltet `memory-core` automatisch einen Cron-Job für einen vollständigen Dreaming-Durchlauf. -Jeder Durchlauf führt die Phasen in dieser Reihenfolge aus: light -> REM -> deep. +Wenn aktiviert, verwaltet `memory-core` automatisch einen Cron-Job für einen vollständigen +Träum-Durchlauf. Jeder Durchlauf führt die Phasen der Reihe nach aus: light -> REM -> deep. -Standardverhalten für die Ausführungsfrequenz: +Standardverhalten für die Taktung: | Einstellung | Standard | | -------------------- | ----------- | @@ -110,7 +130,7 @@ Standardverhalten für die Ausführungsfrequenz: ## Schnellstart -Dreaming aktivieren: +Träumen aktivieren: ```json { @@ -128,7 +148,7 @@ Dreaming aktivieren: } ``` -Dreaming mit einer benutzerdefinierten Durchlauf-Frequenz aktivieren: +Träumen mit benutzerdefinierter Durchlauf-Taktung aktivieren: ```json { @@ -168,17 +188,17 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -Die manuelle Ausführung von `memory promote` verwendet standardmäßig die Schwellenwerte der Deep-Phase, sofern sie +Die manuelle Verwendung von `memory promote` nutzt standardmäßig die Schwellenwerte der Deep-Phase, sofern diese nicht mit CLI-Flags überschrieben werden. -Erklären, warum ein bestimmter Kandidat promoviert würde oder nicht: +Erklären, warum ein bestimmter Kandidat befördert würde oder nicht: ```bash openclaw memory promote-explain "router vlan" openclaw memory promote-explain "router vlan" --json ``` -REM-Reflexionen, Kandidatenwahrheiten und Deep-Promotion-Ausgaben in der Vorschau anzeigen, ohne +REM-Reflexionen, Kandidatenwahrheiten und die Ausgabe der Deep-Promotion als Vorschau anzeigen, ohne etwas zu schreiben: ```bash @@ -198,21 +218,23 @@ Alle Einstellungen befinden sich unter `plugins.entries.memory-core.config.dream Phasenrichtlinie, Schwellenwerte und Speicherverhalten sind interne Implementierungsdetails (keine benutzerseitige Konfiguration). -Die vollständige Schlüsselliste finden Sie unter [Referenz zur Memory-Konfiguration](/de/reference/memory-config#dreaming-experimental). +Siehe [Referenz zur Speicherkonfiguration](/de/reference/memory-config#dreaming-experimental) +für die vollständige Liste der Schlüssel. -## Dreams-UI +## Dreams-Benutzeroberfläche Wenn aktiviert, zeigt der Gateway-Tab **Dreams** Folgendes an: -- aktueller Aktivierungsstatus von Dreaming -- Status auf Phasenebene und Vorhandensein verwalteter Durchläufe -- Anzahl kurzfristiger, langfristiger und heute promovierter Erinnerungen +- aktuellen Aktivierungsstatus von Träumen +- Status auf Phasenebene und Vorhandensein des verwalteten Durchlaufs +- Anzahlen für kurzfristige, fundierte, Signal- und heute beförderte Einträge - Zeitpunkt des nächsten geplanten Durchlaufs -- einen aufklappbaren Dream-Diary-Reader, der auf `doctor.memory.dreamDiary` basiert +- einen separaten fundierten Szenenpfad für bereitgestellte historische Replay-Einträge +- einen aufklappbaren Traumtagebuch-Leser auf Basis von `doctor.memory.dreamDiary` ## Verwandt -- [Memory](/de/concepts/memory) -- [Memory Search](/de/concepts/memory-search) +- [Speicher](/de/concepts/memory) +- [Speichersuche](/de/concepts/memory-search) - [memory CLI](/cli/memory) -- [Referenz zur Memory-Konfiguration](/de/reference/memory-config) +- [Referenz zur Speicherkonfiguration](/de/reference/memory-config) diff --git a/docs/de/concepts/memory.md b/docs/de/concepts/memory.md index 2783d1432..61406fbbb 100644 --- a/docs/de/concepts/memory.md +++ b/docs/de/concepts/memory.md @@ -1,59 +1,63 @@ --- read_when: - - Sie möchten verstehen, wie Speicher funktioniert + - Sie möchten verstehen, wie der Speicher funktioniert - Sie möchten wissen, welche Speicherdateien geschrieben werden -summary: Wie OpenClaw sich Dinge sitzungsübergreifend merkt +summary: Wie OpenClaw Dinge sitzungsübergreifend behält title: Überblick über den Speicher x-i18n: - generated_at: "2026-04-08T06:01:19Z" + generated_at: "2026-04-09T01:27:46Z" model: gpt-5.4 provider: openai - source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af + source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059 source_path: concepts/memory.md workflow: 15 --- # Überblick über den Speicher -OpenClaw merkt sich Dinge, indem **einfache Markdown-Dateien** im Workspace -Ihres Agenten geschrieben werden. Das Modell „erinnert“ sich nur an das, was -auf der Festplatte gespeichert wird – es gibt keinen versteckten Zustand. +OpenClaw merkt sich Dinge, indem es **einfache Markdown-Dateien** im Workspace +Ihres Agenten schreibt. Das Modell „erinnert“ sich nur an das, was auf der +Festplatte gespeichert wird – es gibt keinen verborgenen Zustand. ## So funktioniert es -Ihr Agent hat drei speicherbezogene Dateien: +Ihr Agent verfügt über drei speicherbezogene Dateien: -- **`MEMORY.md`** -- Langzeitspeicher. Dauerhafte Fakten, Präferenzen und +- **`MEMORY.md`** – Langzeitspeicher. Dauerhafte Fakten, Präferenzen und Entscheidungen. Wird zu Beginn jeder DM-Sitzung geladen. -- **`memory/YYYY-MM-DD.md`** -- tägliche Notizen. Laufender Kontext und +- **`memory/YYYY-MM-DD.md`** – tägliche Notizen. Laufender Kontext und Beobachtungen. Die Notizen von heute und gestern werden automatisch geladen. -- **`DREAMS.md`** (experimentell, optional) -- Dream Diary und Zusammenfassungen - von Dreaming-Durchläufen zur menschlichen Überprüfung. +- **`DREAMS.md`** (experimentell, optional) – Traumtagebuch und + Zusammenfassungen der Dreaming-Durchläufe zur menschlichen Überprüfung, + einschließlich fundierter historischer Backfill-Einträge. Diese Dateien befinden sich im Agent-Workspace (standardmäßig `~/.openclaw/workspace`). -Wenn Sie möchten, dass sich Ihr Agent etwas merkt, bitten Sie ihn einfach darum: „Merke dir, dass ich -TypeScript bevorzuge.“ Er schreibt es in die passende Datei. +Wenn Sie möchten, dass sich Ihr Agent etwas merkt, sagen Sie es ihm einfach: +„Merke dir, dass ich TypeScript bevorzuge.“ Er schreibt es in die passende +Datei. ## Speicher-Tools -Der Agent verfügt über zwei Tools für die Arbeit mit Speicher: +Der Agent hat zwei Tools für die Arbeit mit Speicher: -- **`memory_search`** -- findet relevante Notizen mithilfe semantischer Suche, +- **`memory_search`** – findet relevante Notizen mithilfe semantischer Suche, auch wenn die Formulierung vom Original abweicht. -- **`memory_get`** -- liest eine bestimmte Speicherdatei oder einen +- **`memory_get`** – liest eine bestimmte Speicherdatei oder einen Zeilenbereich. -Beide Tools werden vom aktiven Speicher-Plugin bereitgestellt (standardmäßig: `memory-core`). +Beide Tools werden vom aktiven Speicher-Plugin bereitgestellt +(Standard: `memory-core`). -## Begleit-Plugin Memory Wiki +## Begleit-Plugin „Memory Wiki“ Wenn sich dauerhafter Speicher eher wie eine gepflegte Wissensdatenbank als -nur wie rohe Notizen verhalten soll, verwenden Sie das gebündelte Plugin `memory-wiki`. +nur wie rohe Notizen verhalten soll, verwenden Sie das gebündelte Plugin +`memory-wiki`. -`memory-wiki` kompiliert dauerhaftes Wissen in einen Wiki-Tresor mit: +`memory-wiki` kompiliert dauerhaftes Wissen in einen Wiki-Vault mit: - deterministischer Seitenstruktur - strukturierten Aussagen und Belegen @@ -63,35 +67,35 @@ nur wie rohe Notizen verhalten soll, verwenden Sie das gebündelte Plugin `memor - wiki-nativen Tools wie `wiki_search`, `wiki_get`, `wiki_apply` und `wiki_lint` Es ersetzt nicht das aktive Speicher-Plugin. Das aktive Speicher-Plugin ist -weiterhin für Abruf, Promotion und Dreaming zuständig. `memory-wiki` ergänzt es -um eine wissensbezogene Ebene mit Herkunftsnachweisen. +weiterhin für Abruf, Promotion und Dreaming zuständig. `memory-wiki` fügt +daneben eine wissensreiche Ebene mit Herkunftsnachweisen hinzu. Siehe [Memory Wiki](/de/plugins/memory-wiki). ## Speichersuche -Wenn ein Embedding-Anbieter konfiguriert ist, verwendet `memory_search` eine +Wenn ein Embedding-Provider konfiguriert ist, verwendet `memory_search` eine **hybride Suche** – eine Kombination aus Vektorähnlichkeit (semantische Bedeutung) und Schlüsselwortabgleich (exakte Begriffe wie IDs und Codesymbole). -Das funktioniert sofort, sobald Sie einen API-Schlüssel für einen unterstützten -Anbieter haben. +Das funktioniert sofort, sobald Sie einen API-Schlüssel für einen +unterstützten Provider haben. -OpenClaw erkennt Ihren Embedding-Anbieter automatisch anhand verfügbarer API-Schlüssel. Wenn Sie -einen OpenAI-, Gemini-, Voyage- oder Mistral-Schlüssel konfiguriert haben, ist -die Speichersuche automatisch aktiviert. +OpenClaw erkennt Ihren Embedding-Provider automatisch anhand verfügbarer +API-Schlüssel. Wenn Sie einen konfigurierten Schlüssel für OpenAI, Gemini, +Voyage oder Mistral haben, wird die Speichersuche automatisch aktiviert. -Ausführliche Informationen zur Funktionsweise der Suche, zu -Optimierungsoptionen und zur Einrichtung von Anbietern finden Sie unter +Einzelheiten dazu, wie die Suche funktioniert, zu Abstimmungsoptionen und zur +Provider-Einrichtung finden Sie unter [Memory Search](/de/concepts/memory-search). ## Speicher-Backends -SQLite-basiert. Funktioniert sofort mit Schlüsselwortsuche, Vektorähnlichkeit und -hybrider Suche. Keine zusätzlichen Abhängigkeiten. +SQLite-basiert. Funktioniert sofort mit Schlüsselwortsuche, Vektorähnlichkeit +und hybrider Suche. Keine zusätzlichen Abhängigkeiten. Lokaler Sidecar mit Reranking, Query-Erweiterung und der Möglichkeit, @@ -99,7 +103,7 @@ Verzeichnisse außerhalb des Workspace zu indizieren. KI-nativer sitzungsübergreifender Speicher mit Benutzermodellierung, -semantischer Suche und Multi-Agent-Bewusstsein. Plugin-Installation. +semantischer Suche und Multi-Agent-Unterstützung. Plugin-Installation. @@ -107,60 +111,99 @@ semantischer Suche und Multi-Agent-Bewusstsein. Plugin-Installation. -Kompiliert dauerhaften Speicher in einen Wiki-Tresor mit Herkunftsnachweisen, -Dashboards, Bridge-Modus und Obsidian-freundlichen Workflows. +Kompiliert dauerhaften Speicher in einen herkunftsreichen Wiki-Vault mit +Aussagen, Dashboards, Bridge-Modus und Obsidian-freundlichen Workflows. ## Automatische Speicherleerung Bevor [Kompaktierung](/de/concepts/compaction) Ihre Unterhaltung zusammenfasst, -führt OpenClaw einen stillen Turn aus, der den Agenten daran erinnert, wichtigen -Kontext in Speicherdateien zu sichern. Dies ist standardmäßig aktiviert – Sie -müssen nichts konfigurieren. +führt OpenClaw einen stillen Turn aus, der den Agenten daran erinnert, +wichtigen Kontext in Speicherdateien zu speichern. Dies ist standardmäßig +aktiviert – Sie müssen nichts konfigurieren. -Die Speicherleerung verhindert Kontextverlust während der Kompaktierung. Wenn Ihr Agent wichtige -Fakten in der Unterhaltung hat, die noch nicht in eine Datei geschrieben wurden, -werden sie automatisch gespeichert, bevor die Zusammenfassung erfolgt. +Die Speicherleerung verhindert Kontextverlust während der Kompaktierung. Wenn +Ihr Agent wichtige Fakten in der Unterhaltung hat, die noch nicht in eine Datei +geschrieben wurden, werden sie automatisch gespeichert, bevor die +Zusammenfassung erfolgt. ## Dreaming (experimentell) Dreaming ist ein optionaler Hintergrunddurchlauf zur Konsolidierung von -Speicher. Dabei werden kurzfristige Signale gesammelt, Kandidaten bewertet und -nur qualifizierte Elemente in den Langzeitspeicher (`MEMORY.md`) übernommen. +Speicher. Es sammelt kurzfristige Signale, bewertet Kandidaten und überführt nur +qualifizierte Elemente in den Langzeitspeicher (`MEMORY.md`). -Es soll dafür sorgen, dass der Langzeitspeicher ein starkes Signal-Rausch-Verhältnis behält: +Es wurde entwickelt, um den Langzeitspeicher signalstark zu halten: - **Opt-in**: standardmäßig deaktiviert. - **Geplant**: wenn aktiviert, verwaltet `memory-core` automatisch einen wiederkehrenden Cron-Job für einen vollständigen Dreaming-Durchlauf. -- **Schwellenwertbasiert**: Übernahmen müssen Grenzwerte für Bewertung, - Abruffrequenz und Query-Diversität erfüllen. +- **Schwellenwertbasiert**: Promotions müssen Gates für Punktzahl, + Abruffrequenz und Abfragevielfalt bestehen. - **Überprüfbar**: Phasenzusammenfassungen und Tagebucheinträge werden zur menschlichen Überprüfung in `DREAMS.md` geschrieben. -Informationen zum Phasenverhalten, zu Bewertungssignalen und Details zum Dream Diary finden Sie unter -[Dreaming (experimental)](/de/concepts/dreaming). +Details zum Phasenverhalten, zu Bewertungssignalen und zum Traumtagebuch finden +Sie unter [Dreaming (experimental)](/de/concepts/dreaming). + +## Fundiertes Backfill und Live-Promotion + +Das Dreaming-System hat jetzt zwei eng verwandte Überprüfungspfade: + +- **Live Dreaming** arbeitet mit dem kurzfristigen Dreaming-Speicher unter + `memory/.dreams/` und wird von der normalen tiefen Phase verwendet, wenn + entschieden wird, was in `MEMORY.md` übernommen werden kann. +- **Fundiertes Backfill** liest historische Notizen aus + `memory/YYYY-MM-DD.md` als eigenständige Tagesdateien und schreibt + strukturierten Überprüfungsausgabe in `DREAMS.md`. + +Fundiertes Backfill ist nützlich, wenn Sie ältere Notizen erneut durchlaufen und +prüfen möchten, was das System für dauerhaft hält, ohne `MEMORY.md` manuell zu +bearbeiten. + +Wenn Sie Folgendes verwenden: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +werden die fundierten dauerhaften Kandidaten nicht direkt übernommen. Sie werden +in denselben kurzfristigen Dreaming-Speicher eingestuft, den die normale tiefe +Phase bereits verwendet. Das bedeutet: + +- `DREAMS.md` bleibt die Oberfläche für die menschliche Überprüfung. +- der kurzfristige Speicher bleibt die maschinenseitige Oberfläche für das Ranking. +- `MEMORY.md` wird weiterhin nur durch tiefe Promotion geschrieben. + +Wenn Sie entscheiden, dass die Wiederholung nicht nützlich war, können Sie die +bereitgestellten Artefakte entfernen, ohne gewöhnliche Tagebucheinträge oder den +normalen Abrufstatus zu berühren: + +```bash +openclaw memory rem-backfill --rollback +openclaw memory rem-backfill --rollback-short-term +``` ## CLI ```bash -openclaw memory status # Check index status and provider -openclaw memory search "query" # Search from the command line -openclaw memory index --force # Rebuild the index +openclaw memory status # Indexstatus und Provider prüfen +openclaw memory search "query" # Über die Befehlszeile suchen +openclaw memory index --force # Den Index neu erstellen ``` ## Weiterführende Informationen -- [Builtin Memory Engine](/de/concepts/memory-builtin) -- standardmäßiges SQLite-Backend -- [QMD Memory Engine](/de/concepts/memory-qmd) -- fortgeschrittener lokaler Sidecar -- [Honcho Memory](/de/concepts/memory-honcho) -- KI-nativer sitzungsübergreifender Speicher -- [Memory Wiki](/de/plugins/memory-wiki) -- kompilierter Wissens-Tresor und wiki-native Tools -- [Memory Search](/de/concepts/memory-search) -- Suchpipeline, Anbieter und - Optimierung -- [Dreaming (experimental)](/de/concepts/dreaming) -- Hintergrund-Promotion - von kurzfristigem Abruf in den Langzeitspeicher -- [Referenz zur Speicherkonfiguration](/de/reference/memory-config) -- alle Konfigurationsoptionen -- [Kompaktierung](/de/concepts/compaction) -- wie Kompaktierung mit Speicher interagiert +- [Builtin Memory Engine](/de/concepts/memory-builtin) – Standard-Backend mit SQLite +- [QMD Memory Engine](/de/concepts/memory-qmd) – erweiterter lokaler Sidecar +- [Honcho Memory](/de/concepts/memory-honcho) – KI-nativer sitzungsübergreifender Speicher +- [Memory Wiki](/de/plugins/memory-wiki) – kompilierter Wissens-Vault und wiki-native Tools +- [Memory Search](/de/concepts/memory-search) – Suchpipeline, Provider und + Abstimmung +- [Dreaming (experimental)](/de/concepts/dreaming) – Hintergrund-Promotion + vom kurzfristigen Abruf in den Langzeitspeicher +- [Referenz zur Speicherkonfiguration](/de/reference/memory-config) – alle Konfigurationsoptionen +- [Kompaktierung](/de/concepts/compaction) – wie Kompaktierung mit Speicher interagiert diff --git a/docs/de/concepts/model-providers.md b/docs/de/concepts/model-providers.md index 267f67834..890ef72c2 100644 --- a/docs/de/concepts/model-providers.md +++ b/docs/de/concepts/model-providers.md @@ -1,40 +1,42 @@ --- read_when: - - Sie benötigen eine Referenz zur Modelleinrichtung für einzelne Anbieter + - Sie benötigen eine Referenz zur Modelleinrichtung nach Anbieter - Sie möchten Beispielkonfigurationen oder CLI-Onboarding-Befehle für Modellanbieter -summary: Übersicht über Modellanbieter mit Beispielkonfigurationen und CLI-Abläufen +summary: Überblick über Modellanbieter mit Beispielkonfigurationen und CLI-Abläufen title: Modellanbieter x-i18n: - generated_at: "2026-04-08T06:03:09Z" + generated_at: "2026-04-09T01:29:26Z" model: gpt-5.4 provider: openai - source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9 + source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b source_path: concepts/model-providers.md workflow: 15 --- # Modellanbieter -Diese Seite behandelt **LLM-/Modellanbieter** (keine Chat-Kanäle wie WhatsApp/Telegram). +Diese Seite behandelt **LLM-/Modellanbieter** (nicht Chat-Kanäle wie WhatsApp/Telegram). Regeln zur Modellauswahl finden Sie unter [/concepts/models](/de/concepts/models). -## Schnellregeln +## Kurzregeln - Modellreferenzen verwenden `provider/model` (Beispiel: `opencode/claude-opus-4-6`). - Wenn Sie `agents.defaults.models` festlegen, wird es zur Allowlist. - CLI-Helfer: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Fallback-Laufzeitregeln, Cooldown-Prüfungen und die Persistenz von Sitzungsüberschreibungen sind in [/concepts/model-failover](/de/concepts/model-failover) dokumentiert. +- Fallback-Laufzeitregeln, Cooldown-Prüfungen und die Persistenz von Sitzungsüberschreibungen + sind in [/concepts/model-failover](/de/concepts/model-failover) + dokumentiert. - `models.providers.*.models[].contextWindow` sind native Modellmetadaten; `models.providers.*.models[].contextTokens` ist die effektive Laufzeitgrenze. - Anbieter-Plugins können Modellkataloge über `registerProvider({ catalog })` einfügen; OpenClaw führt diese Ausgabe in `models.providers` zusammen, bevor `models.json` geschrieben wird. -- Anbieter-Manifeste können `providerAuthEnvVars` deklarieren, sodass generische - umgebungsvariablenbasierte Auth-Prüfungen die Plugin-Laufzeit nicht laden - müssen. Die verbleibende Core-Umgebungsvariablenzuordnung ist jetzt nur noch - für Nicht-Plugin-/Core-Anbieter und einige generische Vorrangfälle da, etwa - Anthropic-Onboarding mit API-Schlüssel zuerst. -- Anbieter-Plugins können auch das Laufzeitverhalten des Anbieters über +- Anbieter-Manifeste können `providerAuthEnvVars` und + `providerAuthAliases` deklarieren, sodass generische authentifizierungsbasierte Umgebungsvariablen-Prüfungen und Anbietervarianten + keine Plugin-Laufzeit laden müssen. Die verbleibende Kern-Zuordnung von Umgebungsvariablen ist jetzt + nur noch für Nicht-Plugin-/Kern-Anbieter und einige generische Prioritätsfälle gedacht, + wie z. B. Anthropic-Onboarding mit API-Schlüssel zuerst. +- Anbieter-Plugins können auch das Laufzeitverhalten von Anbietern übernehmen über `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -51,144 +53,218 @@ Regeln zur Modellauswahl finden Sie unter [/concepts/models](/de/concepts/models `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot` und - `onModelSelected` steuern. -- Hinweis: Laufzeit-`capabilities` des Anbieters sind gemeinsame Runner-Metadaten (Anbieterfamilie, Besonderheiten bei Transkripten/Tools, Transport-/Cache-Hinweise). Sie sind nicht dasselbe wie das [öffentliche Fähigkeitsmodell](/de/plugins/architecture#public-capability-model), + `onModelSelected`. +- Hinweis: Laufzeit-`capabilities` des Anbieters sind gemeinsame Runner-Metadaten (Anbieter- + Familie, Eigenheiten bei Transkripten/Tooling, Transport-/Cache-Hinweise). Sie sind nicht + identisch mit dem [öffentlichen Fähigkeitsmodell](/de/plugins/architecture#public-capability-model), das beschreibt, was ein Plugin registriert (Textinferenz, Sprache usw.). ## Plugin-eigenes Anbieterverhalten -Anbieter-Plugins können jetzt den Großteil der anbieterspezifischen Logik -übernehmen, während OpenClaw die generische Inferenzschleife beibehält. +Anbieter-Plugins können jetzt den Großteil der anbieterbezogenen Logik übernehmen, während OpenClaw +die generische Inferenzschleife beibehält. Typische Aufteilung: -- `auth[].run` / `auth[].runNonInteractive`: Der Anbieter übernimmt Onboarding-/Login-Abläufe für `openclaw onboard`, `openclaw models auth` und Headless-Einrichtung -- `wizard.setup` / `wizard.modelPicker`: Der Anbieter übernimmt Beschriftungen für Auth-Auswahl, Legacy-Aliasse, Hinweise zur Onboarding-Allowlist und Einrichtungseinträge in Onboarding-/Modellauswahlen -- `catalog`: Der Anbieter erscheint in `models.providers` -- `normalizeModelId`: Der Anbieter normalisiert Legacy-/Vorschau-Modell-IDs vor +- `auth[].run` / `auth[].runNonInteractive`: Anbieter besitzt Onboarding-/Login- + Abläufe für `openclaw onboard`, `openclaw models auth` und kopflose Einrichtung +- `wizard.setup` / `wizard.modelPicker`: Anbieter besitzt Beschriftungen für Authentifizierungsoptionen, + Legacy-Aliase, Hinweise zur Allowlist beim Onboarding und Einträge zur Einrichtung in Onboarding-/Modellauswahlen +- `catalog`: Anbieter erscheint in `models.providers` +- `normalizeModelId`: Anbieter normalisiert Legacy-/Vorschau-Modell-IDs vor Lookup oder Kanonisierung -- `normalizeTransport`: Der Anbieter normalisiert `api` / `baseUrl` der - Transportfamilie vor der generischen Modellerstellung; OpenClaw prüft zuerst - den passenden Anbieter, dann andere hook-fähige Anbieter-Plugins, bis eines - den Transport tatsächlich ändert -- `normalizeConfig`: Der Anbieter normalisiert die Konfiguration - `models.providers.`, bevor die Laufzeit sie verwendet; OpenClaw prüft - zuerst den passenden Anbieter, dann andere hook-fähige Anbieter-Plugins, bis - eines die Konfiguration tatsächlich ändert. Wenn kein Anbieter-Hook die - Konfiguration umschreibt, normalisieren gebündelte Google-Familien-Helfer - weiterhin unterstützte Google-Anbietereinträge. -- `applyNativeStreamingUsageCompat`: Der Anbieter wendet endpointgesteuerte native Streaming-Usage-Kompatibilitätsanpassungen für Konfigurationsanbieter an -- `resolveConfigApiKey`: Der Anbieter löst umgebungsmarkierungsbasierte Auth für Konfigurationsanbieter auf, ohne das vollständige Laufzeit-Auth laden zu müssen. `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Umgebungsmarkierungs-Resolver, obwohl die Bedrock-Laufzeit-Auth die Standardkette des AWS SDK verwendet. -- `resolveSyntheticAuth`: Der Anbieter kann lokale/self-hosted oder andere - konfigurationsgestützte Auth-Verfügbarkeit bereitstellen, ohne Klartext-Geheimnisse zu speichern -- `shouldDeferSyntheticProfileAuth`: Der Anbieter kann gespeicherte synthetische Profilplatzhalter als nachrangig gegenüber umgebungs-/konfigurationsgestützter Auth markieren -- `resolveDynamicModel`: Der Anbieter akzeptiert Modell-IDs, die noch nicht im - lokalen statischen Katalog vorhanden sind -- `prepareDynamicModel`: Der Anbieter benötigt eine Metadatenaktualisierung, - bevor die dynamische Auflösung erneut versucht wird -- `normalizeResolvedModel`: Der Anbieter benötigt Umschreibungen für Transport - oder Basis-URL -- `contributeResolvedModelCompat`: Der Anbieter steuert Kompatibilitätsflags für seine Anbietermodelle bei, selbst wenn sie über einen anderen kompatiblen Transport ankommen -- `capabilities`: Der Anbieter veröffentlicht Besonderheiten bei Transkripten/Tools/Anbieterfamilien -- `normalizeToolSchemas`: Der Anbieter bereinigt Toolschemas, bevor der eingebettete Runner sie sieht -- `inspectToolSchemas`: Der Anbieter gibt transportspezifische Schemawarnungen nach der Normalisierung aus -- `resolveReasoningOutputMode`: Der Anbieter wählt native gegenüber getaggten Reasoning-Ausgabeverträgen -- `prepareExtraParams`: Der Anbieter legt pro-Modell-Anfrageparameter standardmäßig fest oder normalisiert sie -- `createStreamFn`: Der Anbieter ersetzt den normalen Stream-Pfad durch einen vollständig benutzerdefinierten Transport -- `wrapStreamFn`: Der Anbieter wendet Wrapper für Anfrageheader/-body/Modellkompatibilität an -- `resolveTransportTurnState`: Der Anbieter liefert native Transportheader - oder Metadaten pro Zug -- `resolveWebSocketSessionPolicy`: Der Anbieter liefert native WebSocket-Sitzungsheader oder eine Sitzungs-Cooldown-Richtlinie -- `createEmbeddingProvider`: Der Anbieter besitzt das Verhalten für Memory-Embeddings, wenn es besser zum Anbieter-Plugin als zur Core-Embedding-Switchboard gehört -- `formatApiKey`: Der Anbieter formatiert gespeicherte Auth-Profile in den zur Laufzeit erwarteten `apiKey`-String des Transports -- `refreshOAuth`: Der Anbieter übernimmt OAuth-Aktualisierung, wenn die gemeinsamen `pi-ai`-Refresher nicht ausreichen -- `buildAuthDoctorHint`: Der Anbieter hängt Reparaturhinweise an, wenn die OAuth-Aktualisierung fehlschlägt -- `matchesContextOverflowError`: Der Anbieter erkennt anbieterspezifische Fehler bei Kontextfensterüberläufen, die generische Heuristiken übersehen würden -- `classifyFailoverReason`: Der Anbieter ordnet anbieterspezifische rohe Transport-/API-Fehler Failover-Gründen wie Ratenlimit oder Überlastung zu -- `isCacheTtlEligible`: Der Anbieter entscheidet, welche Upstream-Modell-IDs Prompt-Cache-TTL unterstützen -- `buildMissingAuthMessage`: Der Anbieter ersetzt den generischen Fehler des Auth-Speichers durch einen anbieterspezifischen Wiederherstellungshinweis -- `suppressBuiltInModel`: Der Anbieter blendet veraltete Upstream-Zeilen aus und kann für direkte Auflösungsfehler einen anbieterdefinierten Fehler zurückgeben -- `augmentModelCatalog`: Der Anbieter hängt nach Erkennung und Konfigurationszusammenführung synthetische/abschließende Katalogzeilen an -- `isBinaryThinking`: Der Anbieter besitzt die binäre Ein/Aus-Thinking-UX -- `supportsXHighThinking`: Der Anbieter aktiviert `xhigh` für ausgewählte Modelle -- `resolveDefaultThinkingLevel`: Der Anbieter besitzt die standardmäßige `/think`-Richtlinie für eine Modellfamilie -- `applyConfigDefaults`: Der Anbieter wendet anbieterspezifische globale Standardwerte während der Konfigurationsmaterialisierung anhand von Auth-Modus, Umgebung oder Modellfamilie an -- `isModernModelRef`: Der Anbieter besitzt die Zuordnung bevorzugter Modelle für live/smoke -- `prepareRuntimeAuth`: Der Anbieter wandelt konfigurierte Anmeldedaten in ein kurzlebiges Laufzeittoken um -- `resolveUsageAuth`: Der Anbieter löst Nutzungs-/Kontingent-Anmeldedaten für `/usage` und verwandte Status-/Berichtsoberflächen auf -- `fetchUsageSnapshot`: Der Anbieter übernimmt Abruf/Parsing des Nutzungsendpunkts, während der Core weiterhin die Zusammenfassungs-Hülle und Formatierung übernimmt -- `onModelSelected`: Der Anbieter führt Seiteneffekte nach der Modellauswahl aus, etwa Telemetrie oder anbieterdefinierte Sitzungsbuchhaltung +- `normalizeTransport`: Anbieter normalisiert `api` / `baseUrl` der Transportfamilie + vor der generischen Modellzusammenstellung; OpenClaw prüft zuerst den passenden Anbieter, + dann andere Hook-fähige Anbieter-Plugins, bis eines den + Transport tatsächlich ändert +- `normalizeConfig`: Anbieter normalisiert die Konfiguration `models.providers.`, bevor + die Laufzeit sie verwendet; OpenClaw prüft zuerst den passenden Anbieter, dann andere + Hook-fähige Anbieter-Plugins, bis eines die Konfiguration tatsächlich ändert. Falls kein + Anbieter-Hook die Konfiguration umschreibt, normalisieren gebündelte Google-Familien-Helfer weiterhin + unterstützte Google-Anbietereinträge. +- `applyNativeStreamingUsageCompat`: Anbieter wendet endpoint-gesteuerte Kompatibilitätsumschreibungen für native Streaming-Nutzung auf Konfigurationsanbieter an +- `resolveConfigApiKey`: Anbieter löst umgebungsmarkierte Authentifizierung für Konfigurationsanbieter auf, + ohne das vollständige Laufzeit-Authentifizierungsmodul laden zu müssen. `amazon-bedrock` hat hier ebenfalls einen + eingebauten AWS-Resolver für Umgebungsmarker, obwohl die Bedrock-Laufzeit-Authentifizierung + die AWS-SDK-Standardkette verwendet. +- `resolveSyntheticAuth`: Anbieter kann lokale/selbst gehostete oder andere + konfigurationsgestützte Authentifizierungsverfügbarkeit verfügbar machen, ohne Klartext-Geheimnisse + zu persistieren +- `shouldDeferSyntheticProfileAuth`: Anbieter kann gespeicherte synthetische Profil- + Platzhalter als niedrigere Priorität als umgebungs-/konfigurationsgestützte Authentifizierung markieren +- `resolveDynamicModel`: Anbieter akzeptiert Modell-IDs, die noch nicht im lokalen + statischen Katalog vorhanden sind +- `prepareDynamicModel`: Anbieter benötigt eine Metadatenaktualisierung, bevor die dynamische + Auflösung erneut versucht wird +- `normalizeResolvedModel`: Anbieter benötigt Umschreibungen für Transport oder Basis-URL +- `contributeResolvedModelCompat`: Anbieter steuert Kompatibilitäts-Flags für seine + Herstellermodelle bei, selbst wenn sie über einen anderen kompatiblen Transport ankommen +- `capabilities`: Anbieter veröffentlicht Eigenheiten bei Transkripten/Tooling/Anbieterfamilie +- `normalizeToolSchemas`: Anbieter bereinigt Tool-Schemas, bevor der eingebettete + Runner sie sieht +- `inspectToolSchemas`: Anbieter stellt transportspezifische Schemawarnungen + nach der Normalisierung bereit +- `resolveReasoningOutputMode`: Anbieter wählt native oder markierte + Contracts für Reasoning-Ausgaben +- `prepareExtraParams`: Anbieter setzt Standardwerte für anfragespezifische Parameter pro Modell oder normalisiert sie +- `createStreamFn`: Anbieter ersetzt den normalen Stream-Pfad durch einen vollständig + benutzerdefinierten Transport +- `wrapStreamFn`: Anbieter wendet Kompatibilitäts-Wrapper für Anforderungsheader/-body/-modell an +- `resolveTransportTurnState`: Anbieter liefert native Transport- + Header oder Metadaten pro Turn +- `resolveWebSocketSessionPolicy`: Anbieter liefert native WebSocket-Sitzungs- + Header oder Cooldown-Richtlinien für Sitzungen +- `createEmbeddingProvider`: Anbieter besitzt das Verhalten für Speicher-Embeddings, wenn es + beim Anbieter-Plugin statt im Kern-Switchboard für Embeddings liegen soll +- `formatApiKey`: Anbieter formatiert gespeicherte Authentifizierungsprofile in den Laufzeit- + String `apiKey`, der vom Transport erwartet wird +- `refreshOAuth`: Anbieter besitzt die OAuth-Aktualisierung, wenn die gemeinsamen `pi-ai`- + Refresher nicht ausreichen +- `buildAuthDoctorHint`: Anbieter ergänzt Reparaturanweisungen, wenn die OAuth-Aktualisierung + fehlschlägt +- `matchesContextOverflowError`: Anbieter erkennt anbieterspezifische + Fehler bei Überschreitungen des Kontextfensters, die generische Heuristiken übersehen würden +- `classifyFailoverReason`: Anbieter ordnet anbieterspezifische rohe Transport-/API- + Fehler Failover-Gründen wie Ratenbegrenzung oder Überlastung zu +- `isCacheTtlEligible`: Anbieter entscheidet, welche Upstream-Modell-IDs Prompt-Cache-TTL unterstützen +- `buildMissingAuthMessage`: Anbieter ersetzt den generischen Fehler des Authentifizierungsspeichers + durch einen anbieterspezifischen Wiederherstellungshinweis +- `suppressBuiltInModel`: Anbieter blendet veraltete Upstream-Zeilen aus und kann einen + herstellereigenen Fehler bei direkten Auflösungsfehlern zurückgeben +- `augmentModelCatalog`: Anbieter hängt synthetische/finale Katalogzeilen nach + Discovery und Konfigurationszusammenführung an +- `isBinaryThinking`: Anbieter besitzt die binäre Ein/Aus-Denken-UX +- `supportsXHighThinking`: Anbieter aktiviert `xhigh` für ausgewählte Modelle +- `resolveDefaultThinkingLevel`: Anbieter besitzt die Standardrichtlinie von `/think` für eine + Modellfamilie +- `applyConfigDefaults`: Anbieter wendet anbieterspezifische globale Standardwerte + während der Materialisierung der Konfiguration basierend auf Authentifizierungsmodus, Umgebung oder Modellfamilie an +- `isModernModelRef`: Anbieter besitzt die Zuordnung bevorzugter Modelle für Live-/Smoke-Tests +- `prepareRuntimeAuth`: Anbieter wandelt eine konfigurierte Berechtigung in ein kurzlebiges + Laufzeit-Token um +- `resolveUsageAuth`: Anbieter löst Anmeldedaten für Nutzung/Kontingente für `/usage` + und zugehörige Status-/Berichtsoberflächen auf +- `fetchUsageSnapshot`: Anbieter besitzt das Abrufen/Parsen des Nutzungsendpunkts, während + der Kern weiterhin die Zusammenfassungs-Hülle und Formatierung übernimmt +- `onModelSelected`: Anbieter führt Seiteneffekte nach der Modellauswahl aus, z. B. + Telemetrie oder anbietereigene Sitzungsbuchhaltung Aktuelle gebündelte Beispiele: -- `anthropic`: Claude-4.6-Vorwärtskompatibilitäts-Fallback, Auth-Reparaturhinweise, Abruf des Nutzungsendpunkts, Cache-TTL-/Anbieterfamilien-Metadaten und auth-bewusste globale Konfigurationsstandards -- `amazon-bedrock`: anbieterdefinierte Erkennung von Kontextüberlauf und Klassifizierung von Failover-Gründen für Bedrock-spezifische Throttle-/Not-ready-Fehler sowie die gemeinsame Replay-Familie `anthropic-by-model` für Claude-spezifische Replay-Richtlinienwächter auf Anthropic-Datenverkehr -- `anthropic-vertex`: Claude-spezifische Replay-Richtlinienwächter für Anthropic-Messages-Datenverkehr -- `openrouter`: Durchreichen von Modell-IDs, Anfrage-Wrapper, Hinweise zu Anbieterfähigkeiten, Bereinigung von Gemini-Thought-Signatures bei Proxy-Gemini-Datenverkehr, Proxy-Reasoning-Injektion über die Stream-Familie `openrouter-thinking`, Weiterleitung von Routing-Metadaten und Cache-TTL-Richtlinie -- `github-copilot`: Onboarding/Gerätelogin, Vorwärtskompatibilitäts-Fallback für Modelle, Claude-Thinking-Transkripthinweise, Laufzeit-Token-Austausch und Abruf des Nutzungsendpunkts -- `openai`: GPT-5.4-Vorwärtskompatibilitäts-Fallback, direkte OpenAI-Transportnormalisierung, Codex-bewusste Missing-Auth-Hinweise, Spark-Unterdrückung, synthetische OpenAI-/Codex-Katalogzeilen, Thinking-/Live-Modell-Richtlinie, Alias-Normalisierung von Usage-Token (`input` / `output` und `prompt` / `completion`-Familien), die gemeinsame Stream-Familie `openai-responses-defaults` für native OpenAI-/Codex-Wrapper, Anbieterfamilien-Metadaten, gebündelte Registrierung des Bildgenerierungsanbieters für `gpt-image-1` und gebündelte Registrierung des Videogenerierungsanbieters für `sora-2` -- `google` und `google-gemini-cli`: Gemini-3.1-Vorwärtskompatibilitäts-Fallback, native Gemini-Replay-Validierung, Bereinigung von Bootstrap-Replays, getaggter Reasoning-Ausgabemodus, Modern-Model-Matching, gebündelte Registrierung des Bildgenerierungsanbieters für Gemini-Image-Preview-Modelle und gebündelte Registrierung des Videogenerierungsanbieters für Veo-Modelle; Gemini CLI OAuth besitzt außerdem die Formatierung von Auth-Profil-Token, Parsing von Usage-Token und Abruf des Kontingentendpunkts für Nutzungsoberflächen +- `anthropic`: Claude-4.6-Vorwärtskompatibilitäts-Fallback, Hinweise zur Authentifizierungsreparatur, Abruf des + Nutzungsendpunkts, Cache-TTL-/Anbieterfamilien-Metadaten und auth-aware globale + Konfigurationsstandardwerte +- `amazon-bedrock`: anbieterbezogene Erkennung von Kontextüberläufen und Failover- + Klassifizierung für Bedrock-spezifische Fehler bei Drosselung/Nicht-Bereitschaft sowie + die gemeinsame Replay-Familie `anthropic-by-model` für Claude-spezifische Replay-Richtlinien- + Schutzmaßnahmen auf Anthropic-Datenverkehr +- `anthropic-vertex`: Claude-spezifische Replay-Richtlinien-Schutzmaßnahmen auf Anthropic-Message- + Datenverkehr +- `openrouter`: Durchreichen von Modell-IDs, Anforderungs-Wrapper, Hinweise zu Anbieterfunktionen, + Bereinigung von Gemini-Thinking-Signaturen bei proxybasiertem Gemini-Datenverkehr, + Proxy-Reasoning-Injektion über die Stream-Familie `openrouter-thinking`, Weiterleitung + von Routing-Metadaten und Cache-TTL-Richtlinie +- `github-copilot`: Onboarding/Geräte-Login, Vorwärtskompatibilitäts-Fallback für Modelle, + Hinweise zu Claude-Thinking-Transkripten, Austausch von Laufzeit-Token und Abruf des Nutzungsendpunkts +- `openai`: GPT-5.4-Vorwärtskompatibilitäts-Fallback, direkte OpenAI-Transport- + Normalisierung, Codex-spezifische Hinweise bei fehlender Authentifizierung, Spark-Unterdrückung, synthetische + OpenAI-/Codex-Katalogzeilen, Thinking-/Live-Modell-Richtlinie, Normalisierung von Aliasen für Nutzungstoken + (`input` / `output` und `prompt` / `completion`-Familien), die + gemeinsame Stream-Familie `openai-responses-defaults` für native OpenAI-/Codex- + Wrapper, Anbieterfamilien-Metadaten, gebündelte Registrierung von Bildgenerierungsanbietern + für `gpt-image-1` und gebündelte Registrierung von Videogenerierungsanbietern + für `sora-2` +- `google` und `google-gemini-cli`: Gemini-3.1-Vorwärtskompatibilitäts-Fallback, + native Gemini-Replay-Validierung, Bereinigung von Bootstrap-Replays, markierter + Modus für Reasoning-Ausgaben, Modern-Model-Matching, gebündelte Registrierung von Bildgenerierungs- + Anbietern für Gemini-Image-Preview-Modelle und gebündelte + Registrierung von Videogenerierungsanbietern für Veo-Modelle; Gemini-CLI-OAuth übernimmt außerdem + die Tokenformatierung für Authentifizierungsprofile, das Parsen von Nutzungstoken und das Abrufen des Kontingentendpunkts + für Nutzungsoberflächen - `moonshot`: gemeinsamer Transport, plugin-eigene Normalisierung von Thinking-Payloads -- `kilocode`: gemeinsamer Transport, plugin-eigene Anfrageheader, Normalisierung von Reasoning-Payloads, Bereinigung von Proxy-Gemini-Thought-Signatures und Cache-TTL-Richtlinie -- `zai`: GLM-5-Vorwärtskompatibilitäts-Fallback, Standardwerte für `tool_stream`, Cache-TTL-Richtlinie, Richtlinie für binäres Thinking/live-Modelle sowie Usage-Auth und Abruf von Kontingenten; unbekannte `glm-5*`-IDs werden aus der gebündelten Vorlage `glm-4.7` synthetisiert -- `xai`: native Normalisierung des Responses-Transports, Umschreibungen des Alias `/fast` für schnelle Grok-Varianten, Standard-`tool_stream`, xAI-spezifische Bereinigung von Toolschemas / Reasoning-Payloads und gebündelte Registrierung des Videogenerierungsanbieters für `grok-imagine-video` +- `kilocode`: gemeinsamer Transport, plugin-eigene Anforderungsheader, Normalisierung von Reasoning-Payloads, + Bereinigung von Proxy-Gemini-Thinking-Signaturen und Cache-TTL- + Richtlinie +- `zai`: GLM-5-Vorwärtskompatibilitäts-Fallback, Standardwerte für `tool_stream`, Cache-TTL- + Richtlinie, binäre Thinking-/Live-Modell-Richtlinie und Nutzungsauthentifizierung + Kontingentabruf; + unbekannte `glm-5*`-IDs werden aus der gebündelten Vorlage `glm-4.7` synthetisiert +- `xai`: native Responses-Transportnormalisierung, Umschreibungen von `/fast`-Aliasen für + schnelle Grok-Varianten, standardmäßiges `tool_stream`, xAI-spezifische Bereinigung von Tool-Schemas / + Reasoning-Payloads und gebündelte Registrierung von Videogenerierungsanbietern + für `grok-imagine-video` - `mistral`: plugin-eigene Fähigkeitsmetadaten -- `opencode` und `opencode-go`: plugin-eigene Fähigkeitsmetadaten sowie Bereinigung von Proxy-Gemini-Thought-Signatures -- `alibaba`: plugin-eigener Videogenerierungskatalog für direkte Wan-Modellreferenzen wie `alibaba/wan2.6-t2v` -- `byteplus`: plugin-eigene Kataloge sowie gebündelte Registrierung des Videogenerierungsanbieters für Seedance-Text-zu-Video-/Bild-zu-Video-Modelle -- `fal`: gebündelte Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter-Registrierung des Bildgenerierungsanbieters für FLUX-Bildmodelle sowie gebündelte Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter-Videomodelle +- `opencode` und `opencode-go`: plugin-eigene Fähigkeitsmetadaten plus + Bereinigung von Proxy-Gemini-Thinking-Signaturen +- `alibaba`: plugin-eigener Videogenerierungskatalog für direkte Wan-Modellreferenzen + wie `alibaba/wan2.6-t2v` +- `byteplus`: plugin-eigene Kataloge plus gebündelte Registrierung von Videogenerierungsanbietern + für Seedance-Text-zu-Video-/Bild-zu-Video-Modelle +- `fal`: gebündelte Registrierung von Videogenerierungsanbietern für gehostete Drittanbieter- + Registrierung von Bildgenerierungsanbietern für FLUX-Bildmodelle plus gebündelte + Registrierung von Videogenerierungsanbietern für gehostete Drittanbieter-Videomodelle - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` und `volcengine`: nur plugin-eigene Kataloge -- `qwen`: plugin-eigene Kataloge für Textmodelle sowie gemeinsame Registrierungen von Media-Understanding- und Videogenerierungsanbietern für seine multimodalen Oberflächen; Qwen-Videogenerierung verwendet die Standard-DashScope-Videoendpunkte mit gebündelten Wan-Modellen wie `wan2.6-t2v` und `wan2.7-r2v` -- `runway`: plugin-eigene Registrierung des Videogenerierungsanbieters für native aufgabenbasierte Runway-Modelle wie `gen4.5` -- `minimax`: plugin-eigene Kataloge, gebündelte Registrierung des Videogenerierungsanbieters für Hailuo-Videomodelle, gebündelte Registrierung des Bildgenerierungsanbieters für `image-01`, hybride Auswahl von Anthropic-/OpenAI-Replay-Richtlinien sowie Usage-Auth-/Snapshot-Logik -- `together`: plugin-eigene Kataloge sowie gebündelte Registrierung des Videogenerierungsanbieters für Wan-Videomodelle -- `xiaomi`: plugin-eigene Kataloge sowie Usage-Auth-/Snapshot-Logik +- `qwen`: plugin-eigene Kataloge für Textmodelle plus gemeinsame + Registrierungen von Anbietern für Media Understanding und Videogenerierung für seine + multimodalen Oberflächen; die Qwen-Videogenerierung verwendet die Standard-DashScope-Video- + Endpunkte mit gebündelten Wan-Modellen wie `wan2.6-t2v` und `wan2.7-r2v` +- `runway`: plugin-eigene Registrierung von Videogenerierungsanbietern für native + taskbasierte Runway-Modelle wie `gen4.5` +- `minimax`: plugin-eigene Kataloge, gebündelte Registrierung von Videogenerierungsanbietern + für Hailuo-Videomodelle, gebündelte Registrierung von Bildgenerierungsanbietern + für `image-01`, hybride Auswahl der Anthropic-/OpenAI-Replay-Richtlinie sowie Logik für Nutzungsauthentifizierung/Snapshots +- `together`: plugin-eigene Kataloge plus gebündelte Registrierung von Videogenerierungsanbietern + für Wan-Videomodelle +- `xiaomi`: plugin-eigene Kataloge plus Logik für Nutzungsauthentifizierung/Snapshots Das gebündelte Plugin `openai` besitzt jetzt beide Anbieter-IDs: `openai` und `openai-codex`. -Damit sind Anbieter abgedeckt, die noch in die normalen Transporte von OpenClaw passen. Ein Anbieter, der einen vollständig benutzerdefinierten Anfrage-Executor benötigt, ist eine separate, tiefere Erweiterungsoberfläche. +Das deckt Anbieter ab, die noch in die normalen Transporte von OpenClaw passen. Ein Anbieter, +der einen vollständig benutzerdefinierten Request-Executor benötigt, ist eine separate, tiefere Erweiterungsoberfläche. -## API-Schlüsselrotation +## Rotation von API-Schlüsseln -- Unterstützt generische Anbieterrotation für ausgewählte Anbieter. +- Unterstützt generische Anbieterrrotation für ausgewählte Anbieter. - Konfigurieren Sie mehrere Schlüssel über: - `OPENCLAW_LIVE__KEY` (einzelne Live-Überschreibung, höchste Priorität) - - `_API_KEYS` (durch Komma oder Semikolon getrennte Liste) + - `_API_KEYS` (komma- oder semikolongetrennte Liste) - `_API_KEY` (primärer Schlüssel) - `_API_KEY_*` (nummerierte Liste, z. B. `_API_KEY_1`) -- Für Google-Anbieter wird `GOOGLE_API_KEY` zusätzlich als Fallback einbezogen. -- Die Reihenfolge der Schlüsselauswahl bewahrt die Priorität und dedupliziert Werte. -- Anfragen werden nur bei Antworten mit Ratenlimit mit dem nächsten Schlüssel wiederholt (zum Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Für Google-Anbieter ist `GOOGLE_API_KEY` zusätzlich als Fallback enthalten. +- Die Reihenfolge der Schlüsselauswahl bewahrt die Priorität und entfernt doppelte Werte. +- Anfragen werden nur bei Antworten mit Ratenbegrenzung mit dem nächsten Schlüssel erneut versucht (zum + Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` oder periodische Usage-Limit-Meldungen). -- Fehler ohne Ratenlimit schlagen sofort fehl; es wird keine Schlüsselrotation versucht. + `workers_ai ... quota limit exceeded` oder periodische Meldungen zur Nutzungsbegrenzung). +- Fehler ohne Ratenbegrenzung schlagen sofort fehl; es wird keine Schlüsselrotation versucht. - Wenn alle Kandidatenschlüssel fehlschlagen, wird der letzte Fehler des letzten Versuchs zurückgegeben. ## Integrierte Anbieter (pi-ai-Katalog) -OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **keine** -`models.providers`-Konfiguration; legen Sie einfach Auth fest und wählen Sie ein Modell aus. +OpenClaw wird mit dem pi-ai-Katalog ausgeliefert. Diese Anbieter erfordern **keine** +Konfiguration in `models.providers`; setzen Sie einfach die Authentifizierung und wählen Sie ein Modell aus. ### OpenAI - Anbieter: `openai` -- Auth: `OPENAI_API_KEY` +- Authentifizierung: `OPENAI_API_KEY` - Optionale Rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2` sowie `OPENCLAW_LIVE_OPENAI_KEY` (einzelne Überschreibung) - Beispielmodelle: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Der Standardtransport ist `auto` (zuerst WebSocket, dann SSE als Fallback) -- Pro Modell überschreiben über `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) -- OpenAI-Responses-WebSocket-Aufwärmen ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`) -- OpenAI-Prioritätsverarbeitung kann über `agents.defaults.models["openai/"].params.serviceTier` aktiviert werden -- `/fast` und `params.fastMode` ordnen direkte `openai/*`-Responses-Anfragen auf `api.openai.com` `service_tier=priority` zu -- Verwenden Sie `params.serviceTier`, wenn Sie einen expliziten Tier statt des gemeinsamen `/fast`-Schalters möchten -- Versteckte OpenClaw-Zuordnungsheader (`originator`, `version`, - `User-Agent`) werden nur auf nativem OpenAI-Datenverkehr zu `api.openai.com` angewendet, nicht auf generischen OpenAI-kompatiblen Proxys -- Native OpenAI-Routen behalten auch Responses-`store`, Prompt-Cache-Hinweise und OpenAI-Reasoning-Kompatibilitäts-Payload-Shaping bei; Proxy-Routen nicht -- `openai/gpt-5.3-codex-spark` wird in OpenClaw absichtlich unterdrückt, weil die Live-OpenAI-API es ablehnt; Spark wird als nur für Codex behandelt +- Standardtransport ist `auto` (WebSocket zuerst, SSE als Fallback) +- Überschreibung pro Modell über `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) +- Das Aufwärmen von OpenAI-Responses-WebSocket ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`) +- Prioritätsverarbeitung von OpenAI kann über `agents.defaults.models["openai/"].params.serviceTier` aktiviert werden +- `/fast` und `params.fastMode` ordnen direkte `openai/*`-Responses-Anfragen `service_tier=priority` auf `api.openai.com` zu +- Verwenden Sie `params.serviceTier`, wenn Sie eine explizite Stufe statt des gemeinsamen Schalters `/fast` möchten +- Versteckte OpenClaw-Attributionsheader (`originator`, `version`, + `User-Agent`) gelten nur für nativen OpenAI-Datenverkehr an `api.openai.com`, nicht + für generische OpenAI-kompatible Proxys +- Native OpenAI-Routen behalten außerdem Responses-`store`, Prompt-Cache-Hinweise und + OpenAI-Reasoning-kompatible Payload-Aufbereitung bei; Proxy-Routen nicht +- `openai/gpt-5.3-codex-spark` wird in OpenClaw absichtlich unterdrückt, weil die Live-OpenAI-API es ablehnt; Spark wird nur als Codex behandelt ```json5 { @@ -199,13 +275,13 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### Anthropic - Anbieter: `anthropic` -- Auth: `ANTHROPIC_API_KEY` +- Authentifizierung: `ANTHROPIC_API_KEY` - Optionale Rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2` sowie `OPENCLAW_LIVE_ANTHROPIC_KEY` (einzelne Überschreibung) - Beispielmodell: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Direkte öffentliche Anthropic-Anfragen unterstützen den gemeinsamen `/fast`-Schalter und `params.fastMode`, einschließlich per API-Schlüssel und OAuth authentifiziertem Datenverkehr an `api.anthropic.com`; OpenClaw ordnet dies Anthropic-`service_tier` zu (`auto` vs `standard_only`) -- Anthropic-Hinweis: Anthropic-Mitarbeiter haben uns mitgeteilt, dass OpenClaw-artige Claude-CLI-Nutzung wieder erlaubt ist, daher behandelt OpenClaw die Wiederverwendung von Claude CLI und die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. -- Anthropic-Setup-Token bleibt als unterstützter OpenClaw-Tokenpfad verfügbar, aber OpenClaw bevorzugt jetzt, wenn verfügbar, die Wiederverwendung von Claude CLI und `claude -p`. +- Direkte öffentliche Anthropic-Anfragen unterstützen den gemeinsamen Schalter `/fast` und `params.fastMode`, einschließlich mit API-Schlüssel und OAuth authentifiziertem Datenverkehr an `api.anthropic.com`; OpenClaw ordnet dies Anthropic-`service_tier` zu (`auto` vs `standard_only`) +- Anthropic-Hinweis: Anthropic-Mitarbeiter haben uns mitgeteilt, dass die Nutzung im Stil von OpenClaw Claude CLI wieder erlaubt ist, daher behandelt OpenClaw die Wiederverwendung von Claude CLI und die Nutzung von `claude -p` als für diese Integration zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. +- Das Anthropic-Setup-Token bleibt als unterstützter OpenClaw-Tokenpfad verfügbar, aber OpenClaw bevorzugt jetzt die Wiederverwendung von Claude CLI und `claude -p`, wenn verfügbar. ```json5 { @@ -216,19 +292,19 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### OpenAI Code (Codex) - Anbieter: `openai-codex` -- Auth: OAuth (ChatGPT) +- Authentifizierung: OAuth (ChatGPT) - Beispielmodell: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` oder `openclaw models auth login --provider openai-codex` -- Der Standardtransport ist `auto` (zuerst WebSocket, dann SSE als Fallback) -- Pro Modell überschreiben über `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) -- `params.serviceTier` wird auch bei nativen Codex-Responses-Anfragen (`chatgpt.com/backend-api`) weitergeleitet -- Versteckte OpenClaw-Zuordnungsheader (`originator`, `version`, - `User-Agent`) werden nur auf nativem Codex-Datenverkehr zu - `chatgpt.com/backend-api` angehängt, nicht auf generischen OpenAI-kompatiblen Proxys +- Standardtransport ist `auto` (WebSocket zuerst, SSE als Fallback) +- Überschreibung pro Modell über `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) +- `params.serviceTier` wird auch bei nativen Codex-Responses-Anfragen weitergegeben (`chatgpt.com/backend-api`) +- Versteckte OpenClaw-Attributionsheader (`originator`, `version`, + `User-Agent`) werden nur bei nativem Codex-Datenverkehr an + `chatgpt.com/backend-api` angehängt, nicht bei generischen OpenAI-kompatiblen Proxys - Verwendet denselben `/fast`-Schalter und dieselbe `params.fastMode`-Konfiguration wie direktes `openai/*`; OpenClaw ordnet dies `service_tier=priority` zu - `openai-codex/gpt-5.3-codex-spark` bleibt verfügbar, wenn der Codex-OAuth-Katalog es bereitstellt; abhängig von Berechtigungen -- `openai-codex/gpt-5.4` behält natives `contextWindow = 1050000` und ein Standard-Laufzeit-`contextTokens = 272000`; überschreiben Sie die Laufzeitgrenze mit `models.providers.openai-codex.models[].contextTokens` -- Richtlinienhinweis: OpenAI-Codex-OAuth wird explizit für externe Tools/Workflows wie OpenClaw unterstützt. +- `openai-codex/gpt-5.4` behält nativ `contextWindow = 1050000` und standardmäßig zur Laufzeit `contextTokens = 272000`; überschreiben Sie die Laufzeitgrenze mit `models.providers.openai-codex.models[].contextTokens` +- Richtlinienhinweis: OpenAI-Codex-OAuth wird ausdrücklich für externe Tools/Workflows wie OpenClaw unterstützt. ```json5 { @@ -248,15 +324,15 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k } ``` -### Andere abonnementsbasierte gehostete Optionen +### Andere gehostete Optionen im Abonnementstil -- [Qwen Cloud](/de/providers/qwen): Qwen-Cloud-Anbieteroberfläche sowie Alibaba-DashScope- und Coding-Plan-Endpunktzuordnung -- [MiniMax](/de/providers/minimax): MiniMax-Coding-Plan-OAuth- oder API-Schlüsselzugriff -- [GLM Models](/de/providers/glm): Z.AI-Coding-Plan oder allgemeine API-Endpunkte +- [Qwen Cloud](/de/providers/qwen): Qwen-Cloud-Anbieteroberfläche plus Endpoint-Zuordnung für Alibaba DashScope und Coding Plan +- [MiniMax](/de/providers/minimax): MiniMax-Coding-Plan-Zugriff per OAuth oder API-Schlüssel +- [GLM Models](/de/providers/glm): Z.AI Coding Plan oder allgemeine API-Endpunkte ### OpenCode -- Auth: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`) +- Authentifizierung: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`) - Zen-Laufzeitanbieter: `opencode` - Go-Laufzeitanbieter: `opencode-go` - Beispielmodelle: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` @@ -271,80 +347,88 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### Google Gemini (API-Schlüssel) - Anbieter: `google` -- Auth: `GEMINI_API_KEY` -- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` als Fallback sowie `OPENCLAW_LIVE_GEMINI_KEY` (einzelne Überschreibung) +- Authentifizierung: `GEMINI_API_KEY` +- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` als Fallback und `OPENCLAW_LIVE_GEMINI_KEY` (einzelne Überschreibung) - Beispielmodelle: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Kompatibilität: Legacy-OpenClaw-Konfiguration mit `google/gemini-3.1-flash-preview` wird zu `google/gemini-3-flash-preview` normalisiert - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Direkte Gemini-Läufe akzeptieren außerdem `agents.defaults.models["google/"].params.cachedContent` - (oder das Legacy-`cached_content`), um einen anbieterinternen - `cachedContents/...`-Handle weiterzuleiten; Gemini-Cache-Treffer erscheinen als OpenClaw-`cacheRead` +- Direkte Gemini-Ausführungen akzeptieren außerdem `agents.defaults.models["google/"].params.cachedContent` + (oder das Legacy-`cached_content`), um ein anbieter- + natives Handle `cachedContents/...` weiterzuleiten; Gemini-Cache-Treffer erscheinen als OpenClaw-`cacheRead` ### Google Vertex und Gemini CLI - Anbieter: `google-vertex`, `google-gemini-cli` -- Auth: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Ablauf -- Vorsicht: Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Nutzer haben von Einschränkungen ihres Google-Kontos nach der Nutzung von Drittanbieter-Clients berichtet. Prüfen Sie die Google-Nutzungsbedingungen und verwenden Sie ein nicht kritisches Konto, wenn Sie sich dafür entscheiden. -- Gemini-CLI-OAuth wird als Teil des gebündelten `google`-Plugins ausgeliefert. +- Authentifizierung: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Ablauf +- Achtung: Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Nutzer haben von Einschränkungen ihres Google-Kontos nach der Verwendung von Drittanbieter-Clients berichtet. Prüfen Sie die Google-Bedingungen und verwenden Sie bei Bedarf ein nicht kritisches Konto. +- Gemini-CLI-OAuth wird als Teil des gebündelten Plugins `google` ausgeliefert. - Installieren Sie zuerst Gemini CLI: - `brew install gemini-cli` - oder `npm install -g @google/gemini-cli` - Aktivieren: `openclaw plugins enable google` - Login: `openclaw models auth login --provider google-gemini-cli --set-default` - Standardmodell: `google-gemini-cli/gemini-3-flash-preview` - - Hinweis: Sie fügen **keine** Client-ID oder kein Secret in `openclaw.json` ein. Der CLI-Login-Ablauf speichert Tokens in Auth-Profilen auf dem Gateway-Host. + - Hinweis: Sie fügen **keine** Client-ID oder kein Secret in `openclaw.json` ein. Der CLI-Login-Ablauf speichert + Tokens in Authentifizierungsprofilen auf dem Gateway-Host. - Wenn Anfragen nach dem Login fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder `GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host. - - Gemini-CLI-JSON-Antworten werden aus `response` geparst; die Nutzung fällt auf - `stats` zurück, wobei `stats.cached` zu OpenClaw-`cacheRead` normalisiert wird. + - JSON-Antworten von Gemini CLI werden aus `response` geparst; die Nutzung fällt auf + `stats` zurück, wobei `stats.cached` in OpenClaw-`cacheRead` normalisiert wird. ### Z.AI (GLM) - Anbieter: `zai` -- Auth: `ZAI_API_KEY` +- Authentifizierung: `ZAI_API_KEY` - Beispielmodell: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - - Aliasse: `z.ai/*` und `z-ai/*` werden zu `zai/*` normalisiert + - Aliase: `z.ai/*` und `z-ai/*` werden zu `zai/*` normalisiert - `zai-api-key` erkennt den passenden Z.AI-Endpunkt automatisch; `zai-coding-global`, `zai-coding-cn`, `zai-global` und `zai-cn` erzwingen eine bestimmte Oberfläche ### Vercel AI Gateway - Anbieter: `vercel-ai-gateway` -- Auth: `AI_GATEWAY_API_KEY` +- Authentifizierung: `AI_GATEWAY_API_KEY` - Beispielmodell: `vercel-ai-gateway/anthropic/claude-opus-4.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway - Anbieter: `kilocode` -- Auth: `KILOCODE_API_KEY` +- Authentifizierung: `KILOCODE_API_KEY` - Beispielmodell: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - Basis-URL: `https://api.kilo.ai/api/gateway/` -- Der statische Fallback-Katalog enthält `kilocode/kilo/auto`; die Live-Erkennung unter - `https://api.kilo.ai/api/gateway/models` kann den Laufzeitkatalog weiter - erweitern. -- Das genaue Upstream-Routing hinter `kilocode/kilo/auto` gehört zu Kilo Gateway - und ist nicht in OpenClaw fest codiert. +- Der statische Fallback-Katalog enthält `kilocode/kilo/auto`; die Live- + Discovery unter `https://api.kilo.ai/api/gateway/models` kann den Laufzeit- + Katalog weiter erweitern. +- Das genaue Upstream-Routing hinter `kilocode/kilo/auto` wird von Kilo Gateway verwaltet + und ist nicht fest in OpenClaw kodiert. -Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails. +Einzelheiten zur Einrichtung finden Sie unter [/providers/kilocode](/de/providers/kilocode). ### Andere gebündelte Anbieter-Plugins - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Beispielmodell: `openrouter/auto` -- OpenClaw wendet die dokumentierten App-Zuordnungsheader von OpenRouter nur an, wenn die Anfrage tatsächlich an `openrouter.ai` geht -- OpenRouter-spezifische Anthropic-`cache_control`-Marker werden entsprechend nur für verifizierte OpenRouter-Routen aktiviert, nicht für beliebige Proxy-URLs -- OpenRouter bleibt auf dem proxyartigen OpenAI-kompatiblen Pfad, daher wird natives nur-OpenAI-Request-Shaping (`serviceTier`, Responses-`store`, - Prompt-Cache-Hinweise, OpenAI-Reasoning-Kompatibilitäts-Payloads) nicht weitergeleitet -- Gemini-gestützte OpenRouter-Referenzen behalten nur die Bereinigung von Proxy-Gemini-Thought-Signatures; native Gemini-Replay-Validierung und Bootstrap-Umschreibungen bleiben deaktiviert +- OpenClaw wendet die dokumentierten App-Attributionsheader von OpenRouter nur an, wenn + die Anfrage tatsächlich `openrouter.ai` als Ziel hat +- OpenRouter-spezifische Anthropic-`cache_control`-Marker werden ebenfalls nur auf + verifizierten OpenRouter-Routen angewendet, nicht auf beliebigen Proxy-URLs +- OpenRouter bleibt auf dem proxyartigen OpenAI-kompatiblen Pfad, daher wird native + nur-OpenAI-Request-Aufbereitung (`serviceTier`, Responses-`store`, + Prompt-Cache-Hinweise, OpenAI-reasoning-kompatible Payloads) nicht weitergeleitet +- Gemini-basierte OpenRouter-Referenzen behalten nur die Bereinigung der Proxy-Gemini- + Thinking-Signatur bei; native Gemini-Replay-Validierung und Bootstrap-Umschreibungen bleiben deaktiviert - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Beispielmodell: `kilocode/kilo/auto` -- Gemini-gestützte Kilo-Referenzen behalten denselben Bereinigungspfad für Proxy-Gemini-Thought-Signatures; `kilocode/kilo/auto` und andere Hinweise auf nicht unterstütztes Proxy-Reasoning überspringen die Proxy-Reasoning-Injektion +- Gemini-basierte Kilo-Referenzen behalten denselben Bereinigungspfad für Proxy-Gemini-Thinking- + Signaturen; `kilocode/kilo/auto` und andere Hinweise ohne Unterstützung für Proxy-Reasoning + überspringen die Injektion von Proxy-Reasoning - MiniMax: `minimax` (API-Schlüssel) und `minimax-portal` (OAuth) -- Auth: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal` +- Authentifizierung: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal` - Beispielmodell: `minimax/MiniMax-M2.7` oder `minimax-portal/MiniMax-M2.7` -- MiniMax-Onboarding-/API-Schlüssel-Einrichtung schreibt explizite M2.7-Modell-Definitionen mit - `input: ["text", "image"]`; der gebündelte Anbieterkatalog hält die Chat-Referenzen text-only, bis diese Anbieterkonfiguration materialisiert wird +- MiniMax-Onboarding/Einrichtung mit API-Schlüssel schreibt explizite M2.7-Modelldefinitionen mit + `input: ["text", "image"]`; der gebündelte Anbieterkatalog hält die Chat-Referenzen + als nur Text, bis diese Anbieterkonfiguration materialisiert wird - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Beispielmodell: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` oder `KIMICODE_API_KEY`) @@ -386,22 +470,23 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Beispielmodell für Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Siehe [Hugging Face (Inference)](/de/providers/huggingface). -## Anbieter über `models.providers` (benutzerdefinierte/Basis-URL) +## Anbieter über `models.providers` (benutzerdefiniert/Basis-URL) Verwenden Sie `models.providers` (oder `models.json`), um **benutzerdefinierte** Anbieter oder OpenAI-/Anthropic-kompatible Proxys hinzuzufügen. -Viele der gebündelten Anbieter-Plugins unten veröffentlichen bereits einen Standardkatalog. -Verwenden Sie explizite Einträge `models.providers.` nur dann, wenn Sie die +Viele der unten aufgeführten gebündelten Anbieter-Plugins veröffentlichen bereits einen Standardkatalog. +Verwenden Sie explizite Einträge in `models.providers.` nur dann, wenn Sie die Standard-Basis-URL, Header oder Modellliste überschreiben möchten. ### Moonshot AI (Kimi) -Moonshot wird als gebündeltes Anbieter-Plugin ausgeliefert. Verwenden Sie -standardmäßig den integrierten Anbieter und fügen Sie nur dann einen expliziten Eintrag `models.providers.moonshot` hinzu, wenn Sie die Basis-URL oder Modellmetadaten überschreiben müssen: +Moonshot wird als gebündeltes Anbieter-Plugin ausgeliefert. Verwenden Sie standardmäßig den integrierten Anbieter +und fügen Sie nur dann einen expliziten Eintrag `models.providers.moonshot` hinzu, wenn Sie +die Basis-URL oder Modellmetadaten überschreiben müssen: - Anbieter: `moonshot` -- Auth: `MOONSHOT_API_KEY` +- Authentifizierung: `MOONSHOT_API_KEY` - Beispielmodell: `moonshot/kimi-k2.5` - CLI: `openclaw onboard --auth-choice moonshot-api-key` oder `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -440,7 +525,7 @@ Kimi-K2-Modell-IDs: Kimi Coding verwendet den Anthropic-kompatiblen Endpunkt von Moonshot AI: - Anbieter: `kimi` -- Auth: `KIMI_API_KEY` +- Authentifizierung: `KIMI_API_KEY` - Beispielmodell: `kimi/kimi-code` ```json5 @@ -452,14 +537,14 @@ Kimi Coding verwendet den Anthropic-kompatiblen Endpunkt von Moonshot AI: } ``` -Legacy-`kimi/k2p5` bleibt als Kompatibilitätsmodell-ID akzeptiert. +Das Legacy-`kimi/k2p5` bleibt als kompatible Modell-ID weiterhin akzeptiert. ### Volcano Engine (Doubao) Volcano Engine (火山引擎) bietet in China Zugriff auf Doubao und andere Modelle. - Anbieter: `volcengine` (Coding: `volcengine-plan`) -- Auth: `VOLCANO_ENGINE_API_KEY` +- Authentifizierung: `VOLCANO_ENGINE_API_KEY` - Beispielmodell: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -471,9 +556,13 @@ Volcano Engine (火山引擎) bietet in China Zugriff auf Doubao und andere Mode } ``` -Onboarding verwendet standardmäßig die Coding-Oberfläche, aber der allgemeine `volcengine/*`-Katalog wird gleichzeitig registriert. +Beim Onboarding wird standardmäßig die Coding-Oberfläche verwendet, aber der allgemeine Katalog `volcengine/*` +wird gleichzeitig registriert. -In Onboarding-/Modellauswahllisten für die Modellkonfiguration bevorzugt die Volcengine-Auth-Auswahl sowohl Zeilen mit `volcengine/*` als auch mit `volcengine-plan/*`. Wenn diese Modelle noch nicht geladen sind, fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere anbieterbezogene Auswahl anzuzeigen. +In Onboarding-/Modellauswahlen für die Konfiguration bevorzugt die Volcengine-Authentifizierungsoption sowohl +Zeilen `volcengine/*` als auch `volcengine-plan/*`. Wenn diese Modelle noch nicht geladen sind, +fällt OpenClaw auf den ungefilterten Katalog zurück, anstatt eine leere +anbieterspezifische Auswahl anzuzeigen. Verfügbare Modelle: @@ -496,7 +585,7 @@ Coding-Modelle (`volcengine-plan`): BytePlus ARK bietet internationalen Nutzern Zugriff auf dieselben Modelle wie Volcano Engine. - Anbieter: `byteplus` (Coding: `byteplus-plan`) -- Auth: `BYTEPLUS_API_KEY` +- Authentifizierung: `BYTEPLUS_API_KEY` - Beispielmodell: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -508,9 +597,13 @@ BytePlus ARK bietet internationalen Nutzern Zugriff auf dieselben Modelle wie Vo } ``` -Onboarding verwendet standardmäßig die Coding-Oberfläche, aber der allgemeine `byteplus/*`-Katalog wird gleichzeitig registriert. +Beim Onboarding wird standardmäßig die Coding-Oberfläche verwendet, aber der allgemeine Katalog `byteplus/*` +wird gleichzeitig registriert. -In Onboarding-/Modellauswahllisten für die Modellkonfiguration bevorzugt die BytePlus-Auth-Auswahl sowohl Zeilen mit `byteplus/*` als auch mit `byteplus-plan/*`. Wenn diese Modelle noch nicht geladen sind, fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere anbieterbezogene Auswahl anzuzeigen. +In Onboarding-/Modellauswahlen für die Konfiguration bevorzugt die BytePlus-Authentifizierungsoption sowohl +Zeilen `byteplus/*` als auch `byteplus-plan/*`. Wenn diese Modelle noch nicht geladen sind, +fällt OpenClaw auf den ungefilterten Katalog zurück, anstatt eine leere +anbieterspezifische Auswahl anzuzeigen. Verfügbare Modelle: @@ -531,7 +624,7 @@ Coding-Modelle (`byteplus-plan`): Synthetic stellt Anthropic-kompatible Modelle hinter dem Anbieter `synthetic` bereit: - Anbieter: `synthetic` -- Auth: `SYNTHETIC_API_KEY` +- Authentifizierung: `SYNTHETIC_API_KEY` - Beispielmodell: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` @@ -556,25 +649,26 @@ Synthetic stellt Anthropic-kompatible Modelle hinter dem Anbieter `synthetic` be ### MiniMax -MiniMax wird über `models.providers` konfiguriert, da es benutzerdefinierte Endpunkte verwendet: +MiniMax wird über `models.providers` konfiguriert, weil es benutzerdefinierte Endpunkte verwendet: -- MiniMax OAuth (global): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax-API-Schlüssel (global): `--auth-choice minimax-global-api` -- MiniMax-API-Schlüssel (CN): `--auth-choice minimax-cn-api` -- Auth: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder +- MiniMax API-Schlüssel (Global): `--auth-choice minimax-global-api` +- MiniMax API-Schlüssel (CN): `--auth-choice minimax-cn-api` +- Authentifizierung: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal` -Siehe [/providers/minimax](/de/providers/minimax) für Einrichtungsdetails, Modelloptionen und Konfigurationsausschnitte. +Einzelheiten zur Einrichtung, Modelloptionen und Konfigurationsbeispiele finden Sie unter [/providers/minimax](/de/providers/minimax). -Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw Thinking standardmäßig, sofern Sie es nicht explizit festlegen, und `/fast on` schreibt +Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw Thinking standardmäßig, +es sei denn, Sie setzen es explizit, und `/fast on` schreibt `MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um. -Aufteilung der plugin-eigenen Fähigkeiten: +Plugin-eigene Aufteilung der Fähigkeiten: - Standardwerte für Text/Chat bleiben auf `minimax/MiniMax-M2.7` - Bildgenerierung ist `minimax/image-01` oder `minimax-portal/image-01` -- Bildverständnis ist plugin-eigenes `MiniMax-VL-01` auf beiden MiniMax-Auth-Pfaden +- Bildverständnis ist plugin-eigenes `MiniMax-VL-01` auf beiden MiniMax-Authentifizierungspfaden - Websuche bleibt auf Anbieter-ID `minimax` ### Ollama @@ -582,12 +676,12 @@ Aufteilung der plugin-eigenen Fähigkeiten: Ollama wird als gebündeltes Anbieter-Plugin ausgeliefert und verwendet die native API von Ollama: - Anbieter: `ollama` -- Auth: Nicht erforderlich (lokaler Server) +- Authentifizierung: Keine erforderlich (lokaler Server) - Beispielmodell: `ollama/llama3.3` - Installation: [https://ollama.com/download](https://ollama.com/download) ```bash -# Install Ollama, then pull a model: +# Installieren Sie Ollama und ziehen Sie dann ein Modell: ollama pull llama3.3 ``` @@ -599,27 +693,27 @@ ollama pull llama3.3 } ``` -Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie mit -`OLLAMA_API_KEY` optieren, und das gebündelte Anbieter-Plugin fügt Ollama direkt zu +Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie sich mit +`OLLAMA_API_KEY` dafür anmelden, und das gebündelte Anbieter-Plugin fügt Ollama direkt zu `openclaw onboard` und der Modellauswahl hinzu. Siehe [/providers/ollama](/de/providers/ollama) für Onboarding, Cloud-/lokalen Modus und benutzerdefinierte Konfiguration. ### vLLM -vLLM wird als gebündeltes Anbieter-Plugin für lokale/self-hosted OpenAI-kompatible +vLLM wird als gebündeltes Anbieter-Plugin für lokale/selbst gehostete OpenAI-kompatible Server ausgeliefert: - Anbieter: `vllm` -- Auth: Optional (abhängig von Ihrem Server) +- Authentifizierung: Optional (abhängig von Ihrem Server) - Standard-Basis-URL: `http://127.0.0.1:8000/v1` -So aktivieren Sie lokale Auto-Erkennung (jeder Wert funktioniert, wenn Ihr Server keine Auth erzwingt): +Um sich lokal für die automatische Erkennung anzumelden (jeder Wert funktioniert, wenn Ihr Server keine Authentifizierung erzwingt): ```bash export VLLM_API_KEY="vllm-local" ``` -Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): +Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): ```json5 { @@ -629,24 +723,25 @@ Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1 } ``` -Siehe [/providers/vllm](/de/providers/vllm) für Details. +Einzelheiten finden Sie unter [/providers/vllm](/de/providers/vllm). ### SGLang -SGLang wird als gebündeltes Anbieter-Plugin für schnelle self-hosted +SGLang wird als gebündeltes Anbieter-Plugin für schnelle selbst gehostete OpenAI-kompatible Server ausgeliefert: - Anbieter: `sglang` -- Auth: Optional (abhängig von Ihrem Server) +- Authentifizierung: Optional (abhängig von Ihrem Server) - Standard-Basis-URL: `http://127.0.0.1:30000/v1` -So aktivieren Sie lokale Auto-Erkennung (jeder Wert funktioniert, wenn Ihr Server keine Auth erzwingt): +Um sich lokal für die automatische Erkennung anzumelden (jeder Wert funktioniert, wenn Ihr Server keine +Authentifizierung erzwingt): ```bash export SGLANG_API_KEY="sglang-local" ``` -Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): +Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): ```json5 { @@ -656,7 +751,7 @@ Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1 } ``` -Siehe [/providers/sglang](/de/providers/sglang) für Details. +Einzelheiten finden Sie unter [/providers/sglang](/de/providers/sglang). ### Lokale Proxys (LM Studio, vLLM, LiteLLM usw.) @@ -702,10 +797,13 @@ Hinweise: - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Empfohlen: Legen Sie explizite Werte fest, die zu den Grenzen Ihres Proxys/Modells passen. +- Empfohlen: Setzen Sie explizite Werte, die zu den Grenzen Ihres Proxys/Modells passen. - Für `api: "openai-completions"` auf nicht nativen Endpunkten (jede nicht leere `baseUrl`, deren Host nicht `api.openai.com` ist), erzwingt OpenClaw `compat.supportsDeveloperRole: false`, um Provider-400-Fehler für nicht unterstützte `developer`-Rollen zu vermeiden. -- Proxyartige OpenAI-kompatible Routen überspringen ebenfalls natives nur-OpenAI-Request-Shaping: kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise, kein OpenAI-Reasoning-Kompatibilitäts-Payload-Shaping und keine versteckten OpenClaw-Zuordnungsheader. -- Wenn `baseUrl` leer ist oder fehlt, behält OpenClaw das Standard-OpenAI-Verhalten bei (das zu `api.openai.com` aufgelöst wird). +- Proxyartige OpenAI-kompatible Routen überspringen außerdem native nur-OpenAI-Request- + Aufbereitung: kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise, keine + OpenAI-reasoning-kompatible Payload-Aufbereitung und keine versteckten OpenClaw-Attributions- + Header. +- Wenn `baseUrl` leer ist oder weggelassen wird, behält OpenClaw das Standard-OpenAI-Verhalten bei (das zu `api.openai.com` aufgelöst wird). - Aus Sicherheitsgründen wird ein explizites `compat.supportsDeveloperRole: true` auf nicht nativen `openai-completions`-Endpunkten weiterhin überschrieben. ## CLI-Beispiele @@ -720,7 +818,7 @@ Siehe auch: [/gateway/configuration](/de/gateway/configuration) für vollständi ## Verwandt -- [Models](/de/concepts/models) — Modellkonfiguration und Aliasse +- [Models](/de/concepts/models) — Modellkonfiguration und Aliase - [Model Failover](/de/concepts/model-failover) — Fallback-Ketten und Wiederholungsverhalten -- [Configuration Reference](/de/gateway/configuration-reference#agent-defaults) — Modellkonfigurationsschlüssel +- [Configuration Reference](/de/gateway/configuration-reference#agent-defaults) — Konfigurationsschlüssel für Modelle - [Providers](/de/providers) — Einrichtungsanleitungen pro Anbieter diff --git a/docs/de/concepts/qa-e2e-automation.md b/docs/de/concepts/qa-e2e-automation.md index e81ead5a6..03178590e 100644 --- a/docs/de/concepts/qa-e2e-automation.md +++ b/docs/de/concepts/qa-e2e-automation.md @@ -1,51 +1,52 @@ --- read_when: - Erweitern von qa-lab oder qa-channel - - Hinzufügen repo-gestützter QA-Szenarien + - Hinzufügen von repo-gestützten QA-Szenarien - Erstellen realitätsnäherer QA-Automatisierung rund um das Gateway-Dashboard -summary: Private QA-Automatisierungsform für qa-lab, qa-channel, Seed-Szenarien und Protokollberichte -title: QA E2E-Automatisierung +summary: Form der privaten QA-Automatisierung für qa-lab, qa-channel, vordefinierte Szenarien und Protokollberichte +title: QA-E2E-Automatisierung x-i18n: - generated_at: "2026-04-08T06:00:59Z" + generated_at: "2026-04-09T01:27:40Z" model: gpt-5.4 provider: openai - source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99 + source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# QA E2E-Automatisierung +# QA-E2E-Automatisierung -Der private QA-Stack soll OpenClaw auf realistischere, kanalähnliche Weise -testen, als es ein einzelner Unit-Test kann. +Der private QA-Stack soll OpenClaw auf realistischere, +kanalähnliche Weise prüfen, als es ein einzelner Unit-Test kann. Aktuelle Bestandteile: -- `extensions/qa-channel`: synthetischer Nachrichtenkanal mit Oberflächen für DMs, Kanäle, Threads, - Reaktionen, Bearbeitungen und Löschungen. +- `extensions/qa-channel`: synthetischer Nachrichtenkanal mit DM-, Kanal-, Thread-, + Reaktions-, Bearbeitungs- und Löschoberflächen. - `extensions/qa-lab`: Debugger-UI und QA-Bus zum Beobachten des Transkripts, - Einspielen eingehender Nachrichten und Exportieren eines Markdown-Berichts. + Einspeisen eingehender Nachrichten und Exportieren eines Markdown-Berichts. - `qa/`: repo-gestützte Seed-Assets für die Startaufgabe und grundlegende QA- Szenarien. -Der aktuelle QA-Operator-Workflow ist eine QA-Site mit zwei Bereichen: +Der aktuelle QA-Operator-Ablauf ist eine QA-Site mit zwei Bereichen: - Links: Gateway-Dashboard (Control UI) mit dem Agenten. -- Rechts: QA Lab, das das Slack-ähnliche Transkript und den Szenarioplan anzeigt. +- Rechts: QA Lab mit dem Slack-ähnlichen Transkript und dem Szenarioplan. -Führe es aus mit: +Starten Sie es mit: ```bash pnpm qa:lab:up ``` -Dadurch wird die QA-Site gebaut, der Docker-gestützte Gateway-Lane gestartet und die -QA-Lab-Seite bereitgestellt, auf der ein Operator oder eine Automatisierungsschleife dem Agenten eine QA- -Mission geben, echtes Kanalverhalten beobachten und aufzeichnen kann, was funktioniert hat, fehlgeschlagen ist oder -blockiert geblieben ist. +Dadurch wird die QA-Site gebaut, die Docker-gestützte Gateway-Lane gestartet und +die QA-Lab-Seite bereitgestellt, auf der ein Operator oder eine +Automatisierungsschleife dem Agenten eine QA-Mission geben, echtes +Kanalverhalten beobachten und festhalten kann, was funktioniert hat, +fehlgeschlagen ist oder blockiert blieb. -Für schnellere Iterationen an der QA-Lab-UI, ohne das Docker-Image jedes Mal neu zu bauen, -starte den Stack mit einem per Bind-Mount eingebundenen QA-Lab-Bundle: +Für schnellere Iteration an der QA-Lab-UI, ohne das Docker-Image jedes Mal neu +zu bauen, starten Sie den Stack mit einem bind-gemounteten QA-Lab-Bundle: ```bash pnpm openclaw qa docker-build-image @@ -54,9 +55,10 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` hält die Docker-Services auf einem vorab gebauten Image und bind-mountet -`extensions/qa-lab/web/dist` in den Container `qa-lab`. `qa:lab:watch` -baut dieses Bundle bei Änderungen neu, und der Browser lädt automatisch neu, wenn sich der Asset-Hash von QA Lab ändert. +`qa:lab:up:fast` hält die Docker-Services auf einem vorab gebauten Image und +bind-mountet `extensions/qa-lab/web/dist` in den `qa-lab`-Container. `qa:lab:watch` +baut dieses Bundle bei Änderungen neu, und der Browser lädt automatisch neu, +wenn sich der Asset-Hash von QA Lab ändert. ## Repo-gestützte Seeds @@ -65,14 +67,15 @@ Seed-Assets liegen in `qa/`: - `qa/scenarios/index.md` - `qa/scenarios/*.md` -Diese liegen absichtlich in git, damit der QA-Plan sowohl für Menschen als auch für den -Agenten sichtbar ist. Die grundlegende Liste sollte breit genug bleiben, um Folgendes abzudecken: +Diese liegen bewusst in Git, damit der QA-Plan sowohl für Menschen als auch für +den Agenten sichtbar ist. Die Basisliste sollte breit genug bleiben, um +Folgendes abzudecken: - DM- und Kanal-Chat - Thread-Verhalten - Lebenszyklus von Nachrichtenaktionen - Cron-Callbacks -- Memory Recall +- Speicherabruf - Modellwechsel - Übergabe an Subagenten - Lesen des Repos und Lesen der Dokumentation @@ -80,16 +83,81 @@ Agenten sichtbar ist. Die grundlegende Liste sollte breit genug bleiben, um Folg ## Berichterstellung -`qa-lab` exportiert einen Markdown-Protokollbericht aus der beobachteten Bus-Zeitleiste. +`qa-lab` exportiert einen Markdown-Protokollbericht aus der beobachteten +Bus-Zeitleiste. Der Bericht sollte Folgendes beantworten: - Was funktioniert hat - Was fehlgeschlagen ist -- Was blockiert geblieben ist -- Welche Folgeszenarien sich hinzuzufügen lohnen +- Was blockiert blieb +- Welche Folge-Szenarien sich hinzuzufügen lohnen + +Für Charakter- und Stilprüfungen führen Sie dasselbe Szenario über mehrere Live-Modell- +Refs aus und schreiben einen bewerteten Markdown-Bericht: + +```bash +pnpm openclaw qa character-eval \ + --model openai/gpt-5.4,thinking=xhigh \ + --model openai/gpt-5.2,thinking=xhigh \ + --model openai/gpt-5,thinking=xhigh \ + --model anthropic/claude-opus-4-6,thinking=high \ + --model anthropic/claude-sonnet-4-6,thinking=high \ + --model zai/glm-5.1,thinking=high \ + --model moonshot/kimi-k2.5,thinking=high \ + --model google/gemini-3.1-pro-preview,thinking=high \ + --judge-model openai/gpt-5.4,thinking=xhigh,fast \ + --judge-model anthropic/claude-opus-4-6,thinking=high \ + --blind-judge-models \ + --concurrency 16 \ + --judge-concurrency 16 +``` + +Der Befehl führt lokale QA-Gateway-Kindprozesse aus, nicht Docker. Character-eval- +Szenarien sollten die Persona über `SOUL.md` festlegen und dann gewöhnliche +Benutzer-Turns ausführen, etwa Chat, Hilfe zum Workspace und kleine +Dateiaufgaben. Dem Kandidatenmodell sollte nicht mitgeteilt werden, dass es +bewertet wird. Der Befehl bewahrt jedes vollständige Transkript auf, erfasst +grundlegende Laufstatistiken und bittet dann die Bewertungsmodelle im schnellen +Modus mit `xhigh`-Reasoning, die Läufe nach Natürlichkeit, Vibe und Humor zu +bewerten. +Verwenden Sie `--blind-judge-models`, wenn Sie Provider vergleichen: Der Prompt +für die Bewertungsmodelle erhält weiterhin jedes Transkript und jeden +Laufstatus, aber Kandidaten-Refs werden durch neutrale Bezeichnungen wie +`candidate-01` ersetzt; der Bericht ordnet die Ranglisten nach dem Parsen wieder +den echten Refs zu. +Kandidatenläufe verwenden standardmäßig `high` Thinking, mit `xhigh` für +OpenAI-Modelle, die dies unterstützen. Überschreiben Sie einen bestimmten +Kandidaten inline mit +`--model provider/model,thinking=`. `--thinking ` setzt weiterhin +einen globalen Fallback, und die ältere Form +`--model-thinking ` wird aus Kompatibilitätsgründen +beibehalten. +OpenAI-Kandidaten-Refs verwenden standardmäßig den schnellen Modus, damit +Prioritätsverarbeitung genutzt wird, sofern der Provider dies unterstützt. +Fügen Sie inline `,fast`, `,no-fast` oder `,fast=false` hinzu, wenn ein einzelner +Kandidat oder ein Bewertungsmodell eine Überschreibung benötigt. Übergeben Sie +`--fast` nur, wenn Sie den schnellen Modus für jedes Kandidatenmodell erzwingen +möchten. Dauer von Kandidaten- und Bewertungsmodellläufen wird zur +Benchmark-Analyse im Bericht erfasst, aber die Prompts für die +Bewertungsmodelle weisen ausdrücklich an, nicht nach Geschwindigkeit zu +bewerten. +Kandidaten- und Bewertungsmodellläufe verwenden beide standardmäßig eine +Parallelität von 16. Senken Sie `--concurrency` oder `--judge-concurrency`, +wenn Provider-Limits oder Druck auf das lokale Gateway einen Lauf zu unruhig +machen. +Wenn kein Kandidaten-`--model` übergeben wird, verwendet character-eval +standardmäßig +`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, +`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, +`moonshot/kimi-k2.5` und +`google/gemini-3.1-pro-preview`, wenn kein `--model` übergeben wird. +Wenn kein `--judge-model` übergeben wird, verwenden die Bewertungsmodelle +standardmäßig +`openai/gpt-5.4,thinking=xhigh,fast` und +`anthropic/claude-opus-4-6,thinking=high`. ## Verwandte Dokumentation -- [Testing](/de/help/testing) +- [Tests](/de/help/testing) - [QA Channel](/de/channels/qa-channel) - [Dashboard](/web/dashboard) diff --git a/docs/de/gateway/cli-backends.md b/docs/de/gateway/cli-backends.md index a70d3c758..4e8e137e2 100644 --- a/docs/de/gateway/cli-backends.md +++ b/docs/de/gateway/cli-backends.md @@ -1,38 +1,38 @@ --- read_when: - - Sie möchten einen zuverlässigen Fallback, wenn API-Provider ausfallen - - Sie verwenden Codex CLI oder andere lokale AI-CLIs und möchten sie wiederverwenden - - Sie möchten die MCP-loopback-Bridge für den Tool-Zugriff von CLI-Backends verstehen -summary: 'CLI-Backends: lokaler AI-CLI-Fallback mit optionaler MCP-Tool-Bridge' + - Sie möchten einen zuverlässigen Fallback, wenn API-Anbieter ausfallen + - Sie verwenden Codex CLI oder andere lokale KI-CLIs und möchten sie wiederverwenden + - Sie möchten die MCP-Loopback-Bridge für den Tool-Zugriff von CLI-Backends verstehen +summary: 'CLI-Backends: lokaler KI-CLI-Fallback mit optionaler MCP-Tool-Bridge' title: CLI-Backends x-i18n: - generated_at: "2026-04-08T02:14:35Z" + generated_at: "2026-04-09T01:27:51Z" model: gpt-5.4 provider: openai - source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414 + source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20 source_path: gateway/cli-backends.md workflow: 15 --- # CLI-Backends (Fallback-Laufzeit) -OpenClaw kann **lokale AI-CLIs** als **reinen Text-Fallback** ausführen, wenn API-Provider nicht verfügbar sind, -Rate-Limits greifen oder sich vorübergehend fehlerhaft verhalten. Das ist bewusst konservativ gehalten: +OpenClaw kann **lokale KI-CLIs** als **reinen Text-Fallback** ausführen, wenn API-Anbieter ausfallen, +ratenbegrenzt sind oder sich vorübergehend fehlerhaft verhalten. Das ist bewusst konservativ ausgelegt: -- **OpenClaw-Tools werden nicht direkt injiziert**, aber Backends mit `bundleMcp: true` - können Gateway-Tools über eine loopback-MCP-Bridge erhalten. +- **OpenClaw-Tools werden nicht direkt eingebunden**, aber Backends mit `bundleMcp: true` + können Gateway-Tools über eine Loopback-MCP-Bridge erhalten. - **JSONL-Streaming** für CLIs, die es unterstützen. -- **Sitzungen werden unterstützt** (damit Folge-Turns kohärent bleiben). +- **Sitzungen werden unterstützt** (damit zusammenhängende Folge-Turns kohärent bleiben). - **Bilder können durchgereicht werden**, wenn die CLI Bildpfade akzeptiert. -Das ist als **Sicherheitsnetz** und nicht als primärer Pfad gedacht. Verwenden Sie es, wenn Sie -Textantworten möchten, die „immer funktionieren“, ohne auf externe APIs angewiesen zu sein. +Dies ist als **Sicherheitsnetz** und nicht als primärer Pfad gedacht. Verwenden Sie es, wenn Sie +zuverlässige Textantworten möchten, ohne von externen APIs abhängig zu sein. -Wenn Sie stattdessen eine vollständige Harness-Laufzeit mit ACP-Sitzungssteuerung, Hintergrundaufgaben, -Thread-/Konversationsbindung und persistenten externen Coding-Sitzungen möchten, verwenden Sie -[ACP Agents](/de/tools/acp-agents). CLI-Backends sind nicht ACP. +Wenn Sie eine vollständige Harness-Laufzeit mit ACP-Sitzungssteuerung, Hintergrundaufgaben, +Thread-/Unterhaltungs-Bindung und persistenten externen Coding-Sitzungen möchten, verwenden Sie +stattdessen [ACP Agents](/de/tools/acp-agents). CLI-Backends sind kein ACP. -## Einsteigerfreundlicher Schnellstart +## Schnellstart für Einsteiger Sie können Codex CLI **ohne Konfiguration** verwenden (das gebündelte OpenAI-Plugin registriert ein Standard-Backend): @@ -41,7 +41,7 @@ registriert ein Standard-Backend): openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Wenn Ihr Gateway unter launchd/systemd läuft und PATH minimal ist, fügen Sie nur den +Wenn Ihr Gateway unter launchd/systemd läuft und `PATH` minimal ist, fügen Sie nur den Befehlspfad hinzu: ```json5 @@ -58,9 +58,9 @@ Befehlspfad hinzu: } ``` -Das ist alles. Keine Schlüssel, keine zusätzliche Auth-Konfiguration über die CLI selbst hinaus erforderlich. +Das ist alles. Keine Schlüssel, keine zusätzliche Authentifizierungskonfiguration außer der CLI selbst erforderlich. -Wenn Sie ein gebündeltes CLI-Backend als **primären Nachrichten-Provider** auf einem +Wenn Sie ein gebündeltes CLI-Backend als **primären Nachrichtenanbieter** auf einem Gateway-Host verwenden, lädt OpenClaw jetzt automatisch das zugehörige gebündelte Plugin, wenn Ihre Konfiguration dieses Backend explizit in einer Modellreferenz oder unter `agents.defaults.cliBackends` referenziert. @@ -89,7 +89,7 @@ Fügen Sie Ihrer Fallback-Liste ein CLI-Backend hinzu, damit es nur ausgeführt Hinweise: - Wenn Sie `agents.defaults.models` (Allowlist) verwenden, müssen Sie dort auch Ihre CLI-Backend-Modelle einschließen. -- Wenn der primäre Provider fehlschlägt (Auth, Rate-Limits, Timeouts), versucht OpenClaw +- Wenn der primäre Anbieter fehlschlägt (Authentifizierung, Ratenbegrenzungen, Timeouts), versucht OpenClaw als Nächstes das CLI-Backend. ## Konfigurationsübersicht @@ -100,8 +100,8 @@ Alle CLI-Backends befinden sich unter: agents.defaults.cliBackends ``` -Jeder Eintrag ist mit einer **Provider-ID** verschlüsselt (z. B. `codex-cli`, `my-cli`). -Die Provider-ID wird zur linken Seite Ihrer Modellreferenz: +Jeder Eintrag wird durch eine **Anbieter-ID** identifiziert (z. B. `codex-cli`, `my-cli`). +Die Anbieter-ID wird zur linken Seite Ihrer Modellreferenz: ``` / @@ -131,6 +131,9 @@ Die Provider-ID wird zur linken Seite Ihrer Modellreferenz: sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", + // CLIs im Codex-Stil können stattdessen auf eine Prompt-Datei verweisen: + // systemPromptFileConfigArg: "-c", + // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -142,39 +145,45 @@ Die Provider-ID wird zur linken Seite Ihrer Modellreferenz: } ``` -## Funktionsweise +## So funktioniert es -1. **Wählt ein Backend aus** anhand des Provider-Präfixes (`codex-cli/...`). +1. **Wählt ein Backend aus** basierend auf dem Anbieterpräfix (`codex-cli/...`). 2. **Erstellt einen System-Prompt** mit demselben OpenClaw-Prompt und Workspace-Kontext. -3. **Führt die CLI** mit einer Sitzungs-ID aus (falls unterstützt), damit der Verlauf konsistent bleibt. +3. **Führt die CLI aus** mit einer Sitzungs-ID (falls unterstützt), damit der Verlauf konsistent bleibt. 4. **Parst die Ausgabe** (JSON oder Klartext) und gibt den endgültigen Text zurück. -5. **Persistiert Sitzungs-IDs** pro Backend, damit Folgeanfragen dieselbe CLI-Sitzung wiederverwenden. +5. **Speichert Sitzungs-IDs** pro Backend, damit Folgeanfragen dieselbe CLI-Sitzung wiederverwenden. -Das gebündelte Anthropic-`claude-cli`-Backend wird wieder unterstützt. Mitarbeiter von Anthropic +Das gebündelte Anthropic-`claude-cli`-Backend wird wieder unterstützt. Mitarbeitende von Anthropic haben uns mitgeteilt, dass die Nutzung von Claude CLI im OpenClaw-Stil wieder erlaubt ist, daher behandelt OpenClaw -die Nutzung von `claude -p` für diese Integration als genehmigt, solange Anthropic +die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. +Das gebündelte OpenAI-`codex-cli`-Backend übergibt den System-Prompt von OpenClaw über +Codex' `model_instructions_file`-Konfigurationsüberschreibung (`-c +model_instructions_file="..."`). Codex bietet kein Flag im Claude-Stil wie +`--append-system-prompt`, daher schreibt OpenClaw den zusammengesetzten Prompt für jede neue Codex-CLI-Sitzung in eine +temporäre Datei. + ## Sitzungen - Wenn die CLI Sitzungen unterstützt, setzen Sie `sessionArg` (z. B. `--session-id`) oder - `sessionArgs` (Platzhalter `{sessionId}`), wenn die ID in mehrere Flags - eingefügt werden muss. + `sessionArgs` (Platzhalter `{sessionId}`), wenn die ID in + mehrere Flags eingefügt werden muss. - Wenn die CLI einen **Resume-Subcommand** mit anderen Flags verwendet, setzen Sie `resumeArgs` (ersetzt `args` beim Fortsetzen) und optional `resumeOutput` (für nicht-JSON-Resumes). - `sessionMode`: - - `always`: sendet immer eine Sitzungs-ID (neue UUID, wenn keine gespeichert ist). - - `existing`: sendet eine Sitzungs-ID nur, wenn zuvor eine gespeichert wurde. + - `always`: sendet immer eine Sitzungs-ID (neue UUID, falls keine gespeichert ist). + - `existing`: sendet nur dann eine Sitzungs-ID, wenn bereits eine gespeichert wurde. - `none`: sendet niemals eine Sitzungs-ID. Hinweise zur Serialisierung: - `serialize: true` hält Ausführungen auf derselben Lane geordnet. -- Die meisten CLIs serialisieren auf einer Provider-Lane. -- OpenClaw verwirft die Wiederverwendung gespeicherter CLI-Sitzungen, wenn sich der Auth-Status des Backends ändert, einschließlich erneuter Anmeldung, Token-Rotation oder geänderter Auth-Profil-Credentials. +- Die meisten CLIs serialisieren auf einer Anbieter-Lane. +- OpenClaw verwirft die Wiederverwendung gespeicherter CLI-Sitzungen, wenn sich der Authentifizierungsstatus des Backends ändert, einschließlich erneutem Login, Token-Rotation oder geänderten Anmeldedaten eines Authentifizierungsprofils. ## Bilder (Durchreichung) @@ -187,17 +196,17 @@ imageMode: "repeat" OpenClaw schreibt Base64-Bilder in temporäre Dateien. Wenn `imageArg` gesetzt ist, werden diese Pfade als CLI-Argumente übergeben. Wenn `imageArg` fehlt, hängt OpenClaw die -Dateipfade an den Prompt an (Pfadinjektion), was für CLIs ausreicht, die lokale +Dateipfade an den Prompt an (Path Injection), was für CLIs ausreicht, die lokale Dateien automatisch aus einfachen Pfaden laden. -## Ein- / Ausgaben +## Eingaben / Ausgaben - `output: "json"` (Standard) versucht, JSON zu parsen und Text + Sitzungs-ID zu extrahieren. -- Für Gemini CLI-JSON-Ausgabe liest OpenClaw den Antworttext aus `response` und - die Nutzung aus `stats`, wenn `usage` fehlt oder leer ist. -- `output: "jsonl"` parst JSONL-Streams (zum Beispiel Codex CLI `--json`) und extrahiert die finale Agentennachricht sowie Sitzungs- - Kennungen, wenn vorhanden. -- `output: "text"` behandelt stdout als endgültige Antwort. +- Für die JSON-Ausgabe von Gemini CLI liest OpenClaw Antworttext aus `response` und + Nutzung aus `stats`, wenn `usage` fehlt oder leer ist. +- `output: "jsonl"` parst JSONL-Streams (zum Beispiel Codex CLI `--json`) und extrahiert die endgültige Agentennachricht sowie Sitzungs- + kennungen, sofern vorhanden. +- `output: "text"` behandelt stdout als die endgültige Antwort. Eingabemodi: @@ -205,9 +214,9 @@ Eingabemodi: - `input: "stdin"` sendet den Prompt über stdin. - Wenn der Prompt sehr lang ist und `maxPromptArgChars` gesetzt ist, wird stdin verwendet. -## Standardwerte (plugin-eigen) +## Standards (plugin-eigen) -Das gebündelte OpenAI-Plugin registriert außerdem einen Standard für `codex-cli`: +Das gebündelte OpenAI-Plugin registriert auch einen Standard für `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -218,7 +227,7 @@ Das gebündelte OpenAI-Plugin registriert außerdem einen Standard für `codex-c - `imageArg: "--image"` - `sessionMode: "existing"` -Das gebündelte Google-Plugin registriert außerdem einen Standard für `google-gemini-cli`: +Das gebündelte Google-Plugin registriert auch einen Standard für `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -235,57 +244,57 @@ Voraussetzung: Die lokale Gemini CLI muss installiert und als Hinweise zu Gemini-CLI-JSON: -- Der Antworttext wird aus dem JSON-Feld `response` gelesen. -- Die Nutzung fällt auf `stats` zurück, wenn `usage` fehlt oder leer ist. +- Antworttext wird aus dem JSON-Feld `response` gelesen. +- Nutzung greift auf `stats` zurück, wenn `usage` fehlt oder leer ist. - `stats.cached` wird in OpenClaw-`cacheRead` normalisiert. -- Wenn `stats.input` fehlt, leitet OpenClaw Eingabetokens aus +- Wenn `stats.input` fehlt, leitet OpenClaw Eingabe-Token aus `stats.input_tokens - stats.cached` ab. -Nur bei Bedarf überschreiben (häufig: absoluter `command`-Pfad). +Überschreiben Sie dies nur bei Bedarf (häufig: absoluter `command`-Pfad). -## Plugin-eigene Standardwerte +## Plugin-eigene Standards -CLI-Backend-Standards sind jetzt Teil der Plugin-Oberfläche: +Standardwerte für CLI-Backends sind jetzt Teil der Plugin-Oberfläche: - Plugins registrieren sie mit `api.registerCliBackend(...)`. -- Die Backend-`id` wird zum Provider-Präfix in Modellreferenzen. -- Benutzerkonfiguration unter `agents.defaults.cliBackends.` überschreibt weiterhin den Plugin-Standard. +- Die Backend-`id` wird zum Anbieterpräfix in Modellreferenzen. +- Benutzerkonfiguration in `agents.defaults.cliBackends.` überschreibt weiterhin den Plugin-Standard. - Backend-spezifische Konfigurationsbereinigung bleibt über den optionalen Hook `normalizeConfig` plugin-eigen. ## Bundle-MCP-Overlays -CLI-Backends erhalten **keine** OpenClaw-Tool-Aufrufe direkt, aber ein Backend kann -sich mit `bundleMcp: true` für ein generiertes MCP-Konfigurations-Overlay anmelden. +CLI-Backends erhalten **keine** direkten OpenClaw-Tool-Aufrufe, aber ein Backend kann +sich mit `bundleMcp: true` für ein generiertes MCP-Konfigurations-Overlay entscheiden. Aktuelles gebündeltes Verhalten: - `claude-cli`: generierte strikte MCP-Konfigurationsdatei -- `codex-cli`: Inline-Konfigurations-Overrides für `mcp_servers` +- `codex-cli`: Inline-Konfigurationsüberschreibungen für `mcp_servers` - `google-gemini-cli`: generierte Gemini-Systemeinstellungsdatei Wenn Bundle MCP aktiviert ist, führt OpenClaw Folgendes aus: -- Es startet einen loopback-HTTP-MCP-Server, der Gateway-Tools für den CLI-Prozess bereitstellt. -- Es authentifiziert die Bridge mit einem sitzungsspezifischen Token (`OPENCLAW_MCP_TOKEN`). -- Es begrenzt den Tool-Zugriff auf den aktuellen Sitzungs-, Konto- und Kanal-Kontext. -- Es lädt aktivierte Bundle-MCP-Server für den aktuellen Workspace. -- Es führt sie mit jeder vorhandenen Backend-MCP-Konfigurations-/Einstellungsstruktur zusammen. -- Es schreibt die Startkonfiguration unter Verwendung des Backend-eigenen Integrationsmodus aus der besitzenden Erweiterung um. +- startet einen Loopback-HTTP-MCP-Server, der Gateway-Tools für den CLI-Prozess bereitstellt +- authentifiziert die Bridge mit einem sitzungsbezogenen Token (`OPENCLAW_MCP_TOKEN`) +- begrenzt den Tool-Zugriff auf die aktuelle Sitzung, das aktuelle Konto und den Kanal-Kontext +- lädt aktivierte Bundle-MCP-Server für den aktuellen Workspace +- führt sie mit einer vorhandenen MCP-Konfigurations-/Einstellungsstruktur des Backends zusammen +- schreibt die Startkonfiguration unter Verwendung des backend-eigenen Integrationsmodus aus der zugehörigen Erweiterung um -Wenn keine MCP-Server aktiviert sind, injiziert OpenClaw dennoch eine strikte Konfiguration, wenn sich ein -Backend für Bundle MCP anmeldet, damit Hintergrundläufe isoliert bleiben. +Wenn keine MCP-Server aktiviert sind, injiziert OpenClaw dennoch eine strikte Konfiguration, wenn ein +Backend sich für Bundle MCP entscheidet, damit Hintergrundausführungen isoliert bleiben. ## Einschränkungen -- **Keine direkten OpenClaw-Tool-Aufrufe.** OpenClaw injiziert keine Tool-Aufrufe in - das CLI-Backend-Protokoll. Backends sehen Gateway-Tools nur, wenn sie sich für - `bundleMcp: true` anmelden. -- **Streaming ist backend-spezifisch.** Einige Backends streamen JSONL; andere puffern +- **Keine direkten OpenClaw-Tool-Aufrufe.** OpenClaw bindet Tool-Aufrufe nicht direkt in + das CLI-Backend-Protokoll ein. Backends sehen Gateway-Tools nur dann, wenn sie sich für + `bundleMcp: true` entscheiden. +- **Streaming ist backend-spezifisch.** Manche Backends streamen JSONL, andere puffern bis zum Beenden. - **Strukturierte Ausgaben** hängen vom JSON-Format der CLI ab. - **Codex-CLI-Sitzungen** werden über Textausgabe fortgesetzt (kein JSONL), was weniger - strukturiert ist als der anfängliche `--json`-Lauf. OpenClaw-Sitzungen funktionieren weiterhin + strukturiert ist als der anfängliche `--json`-Lauf. OpenClaw-Sitzungen funktionieren dennoch normal. ## Fehlerbehebung diff --git a/docs/de/gateway/configuration-reference.md b/docs/de/gateway/configuration-reference.md index 1b7de8d0f..1e8709da5 100644 --- a/docs/de/gateway/configuration-reference.md +++ b/docs/de/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - Sie benötigen genaue feldspezifische Konfigurationssemantik oder Standardwerte + - 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 Subsystem-Referenzen +summary: Referenz zur Gateway-Konfiguration für zentrale OpenClaw-Schlüssel, Standardwerte und Links zu dedizierten Referenzen für Subsysteme title: Konfigurationsreferenz x-i18n: - generated_at: "2026-04-08T06:06:53Z" + generated_at: "2026-04-09T01:33:42Z" model: gpt-5.4 provider: openai - source_hash: 2f9ab34fb56897a77cb038d95bea21e8530d8f0402b66d1ee97c73822a1e8fd4 + source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c source_path: gateway/configuration-reference.md workflow: 15 --- # Konfigurationsreferenz -Referenz der Kernkonfiguration für `~/.openclaw/openclaw.json`. Eine aufgabenorientierte Übersicht finden Sie unter [Konfiguration](/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-Konfigurationsflächen und verweist weiter, wenn ein Subsystem eine eigene ausführlichere Referenz hat. Sie versucht **nicht**, jeden kanal-/plugin-eigenen Befehlskatalog oder jeden tiefen Speicher-/QMD-Schalter auf einer Seite einzubetten. +Diese Seite behandelt die wichtigsten OpenClaw-Konfigurationsoberflächen und verlinkt weiter, wenn ein Subsystem eine eigene, detailliertere Referenz hat. Sie versucht **nicht**, jeden kanal-/plugin-eigenen Befehlskatalog oder jede tiefgehende Speicher-/QMD-Einstellung auf einer Seite einzubetten. -Code-Wahrheit: +Code-Referenz: -- `openclaw config schema` gibt das Live-JSON-Schema aus, das für Validierung und Control UI verwendet wird, mit zusammengeführten gebündelten/plugin-/kanalbezogenen Metadaten, sofern verfügbar -- `config.schema.lookup` gibt einen pfadbezogenen einzelnen Schemaknoten für Drill-down-Tools zurück -- `pnpm config:docs:check` / `pnpm config:docs:gen` validieren den Hash der Konfigurationsdokumentations-Basislinie gegen die aktuelle Schemaoberfläche +- `openclaw config schema` gibt das live verwendete JSON-Schema aus, das für Validierung und Control UI genutzt wird, mit zusammengeführten Metadaten aus gebündelten/plugins/channels, wenn verfügbar +- `config.schema.lookup` gibt einen pfadbezogenen Schema-Knoten 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 Detailreferenzen: +Dedizierte detaillierte Referenzen: -- [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 -- seiten der zuständigen Kanäle/plugins für kanalspezifische Befehlsflächen +- [Referenz zur Speicherkonfiguration](/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 +- Seiten des jeweiligen Channels/Plugins für kanalspezifische Befehlsoberflächen -Das Konfigurationsformat ist **JSON5** (Kommentare + abschließende Kommas erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden. +Das Konfigurationsformat ist **JSON5** (Kommentare + nachgestellte Kommas erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden. --- -## Kanäle +## Channels -Jeder Kanal startet automatisch, wenn sein Konfigurationsabschnitt vorhanden ist (außer `enabled: false`). +Jeder Channel startet automatisch, wenn sein Konfigurationsabschnitt vorhanden ist (außer bei `enabled: false`). ### DM- und Gruppenzugriff -Alle Kanäle unterstützen DM-Richtlinien und Gruppenrichtlinien: +Alle Channels unterstützen DM-Richtlinien und Gruppenrichtlinien: -| DM-Richtlinie | Verhalten | -| ------------------ | -------------------------------------------------------------- | -| `pairing` (Standard) | Unbekannte Sender erhalten einen einmaligen Pairing-Code; Eigentümer muss genehmigen | -| `allowlist` | Nur Sender in `allowFrom` (oder gekoppeltem Erlaubnisspeicher) | -| `open` | Alle eingehenden DMs erlauben (erfordert `allowFrom: ["*"]`) | -| `disabled` | Alle eingehenden DMs ignorieren | +| DM-Richtlinie | Verhalten | +| ------------------- | -------------------------------------------------------------- | +| `pairing` (Standard) | Unbekannte Absender erhalten einen einmaligen Pairing-Code; der Eigentümer muss zustimmen | +| `allowlist` | Nur Absender in `allowFrom` (oder im gepaarten Allow-Store) | +| `open` | Alle eingehenden DMs zulassen (erfordert `allowFrom: ["*"]`) | +| `disabled` | Alle eingehenden DMs ignorieren | -| Gruppenrichtlinie | Verhalten | -| -------------------- | ---------------------------------------------------- | -| `allowlist` (Standard) | Nur Gruppen, die der konfigurierten Erlaubnisliste entsprechen | -| `open` | Gruppen-Erlaubnislisten umgehen (Mention-Gating gilt weiterhin) | -| `disabled` | Alle Gruppen-/Raumnachrichten blockieren | +| Gruppenrichtlinie | Verhalten | +| --------------------- | ----------------------------------------------------- | +| `allowlist` (Standard) | Nur Gruppen, die der konfigurierten Allowlist entsprechen | +| `open` | Gruppen-Allowlists umgehen (Mention-Gating gilt weiterhin) | +| `disabled` | Alle Gruppen-/Raumnachrichten blockieren | -`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 Provider-Block vollständig fehlt (`channels.` nicht vorhanden), fällt die Gruppenrichtlinie zur Laufzeit auf `allowlist` zurück (fail-closed) und gibt beim Start eine Warnung aus. +`channels.defaults.groupPolicy` setzt den Standard, wenn `groupPolicy` eines Providers nicht gesetzt ist. +Pairing-Codes laufen nach 1 Stunde ab. Ausstehende DM-Pairing-Anfragen sind auf **3 pro Channel** begrenzt. +Wenn ein Provider-Block vollständig fehlt (`channels.` fehlt), fällt die Gruppenrichtlinie zur Laufzeit auf `allowlist` zurück (fail-closed) und es wird beim Start gewarnt. -### Kanal-Modell-Überschreibungen +### Channel-Modellüberschreibungen -Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu binden. Werte akzeptieren `provider/model` oder konfigurierte Modell-Aliasse. Das Kanal-Mapping wird angewendet, wenn eine Sitzung nicht bereits eine Modell-Überschreibung hat (zum Beispiel gesetzt über `/model`). +Verwenden Sie `channels.modelByChannel`, um bestimmte Channel-IDs an ein Modell zu binden. Werte akzeptieren `provider/model` oder konfigurierte Modellaliase. Das Channel-Mapping wird angewendet, wenn eine Sitzung noch keine Modellüberschreibung hat (zum Beispiel durch `/model` gesetzt). ```json5 { @@ -85,7 +85,7 @@ Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu } ``` -### Kanal-Standardeinstellungen und Heartbeat +### Channel-Standards und Heartbeat Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heartbeat-Verhalten über Provider hinweg: @@ -105,15 +105,15 @@ Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heart } ``` -- `channels.defaults.groupPolicy`: Fallback-Gruppenrichtlinie, wenn eine providerbezogene `groupPolicy` nicht gesetzt ist. -- `channels.defaults.contextVisibility`: Standardmodus für die Sichtbarkeit ergänzenden Kontexts für alle Kanäle. Werte: `all` (Standard, schließt allen zitierten/Thread-/Verlaufs-Kontext ein), `allowlist` (schließt nur Kontext von Sendern aus der Erlaubnisliste ein), `allowlist_quote` (wie allowlist, behält aber expliziten Zitat-/Antwort-Kontext bei). Kanalbezogene Überschreibung: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: gesunde Kanalstatus in der Heartbeat-Ausgabe einschließen. -- `channels.defaults.heartbeat.showAlerts`: degradierte/Fehler-Status in der Heartbeat-Ausgabe einschließen. -- `channels.defaults.heartbeat.useIndicator`: kompakte indikatorartige Heartbeat-Ausgabe rendern. +- `channels.defaults.groupPolicy`: Fallback-Gruppenrichtlinie, wenn `groupPolicy` auf Providerebene nicht gesetzt ist. +- `channels.defaults.contextVisibility`: Standardmodus für zusätzliche Kontextsichtigkeit für alle Channels. Werte: `all` (Standard, gesamten zitierten/Thread-/Verlaufs-Kontext einbeziehen), `allowlist` (nur Kontext von Absendern auf der Allowlist einbeziehen), `allowlist_quote` (wie allowlist, aber expliziten Zitat-/Antwort-Kontext beibehalten). Überschreibung pro Channel: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: gesunde Channel-Status in die Heartbeat-Ausgabe aufnehmen. +- `channels.defaults.heartbeat.showAlerts`: degradierte/Fehler-Status in die Heartbeat-Ausgabe aufnehmen. +- `channels.defaults.heartbeat.useIndicator`: kompakte Heartbeat-Ausgabe im Indikatorstil rendern. ### WhatsApp -WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet automatisch, wenn eine verknüpfte Sitzung vorhanden ist. +WhatsApp läuft über den Web-Channel des Gateways (Baileys Web). Er startet automatisch, wenn eine verknüpfte Sitzung vorhanden ist. ```json5 { @@ -124,7 +124,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blaue Häkchen (false im Selbstchat-Modus) + sendReadReceipts: true, // blaue Häkchen (false im Self-Chat-Modus) groups: { "*": { requireMention: true }, }, @@ -165,9 +165,9 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom ``` - Ausgehende Befehle verwenden standardmäßig das Konto `default`, falls vorhanden; andernfalls die erste konfigurierte Konto-ID (sortiert). -- Optional überschreibt `channels.whatsapp.defaultAccount` diese Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. -- Das alte Single-Account-Baileys-Authentifizierungsverzeichnis wird von `openclaw doctor` nach `whatsapp/default` migriert. -- Pro-Konto-Überschreibungen: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Optional überschreibt `channels.whatsapp.defaultAccount` diese Fallback-Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- Das alte Baileys-Auth-Verzeichnis für Einzelkonten wird von `openclaw doctor` nach `whatsapp/default` migriert. +- Überschreibungen pro Konto: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -185,24 +185,24 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Antworten kurz halten.", + systemPrompt: "Keep answers brief.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Beim Thema bleiben.", + systemPrompt: "Stay on topic.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git-Backup" }, - { command: "generate", description: "Ein Bild erstellen" }, + { command: "backup", description: "Git backup" }, + { command: "generate", description: "Create an image" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (Standard: off; explizit aktivieren, um Ratenlimits bei Vorschau-Bearbeitungen zu vermeiden) + streaming: "partial", // off | partial | block | progress (Standard: off; explizit aktivieren, um Ratenlimits für Vorschau-Bearbeitungen zu vermeiden) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -226,12 +226,12 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom ``` - 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. -- Optional überschreibt `channels.telegram.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. -- In Multi-Account-Setups (2+ Konto-IDs) sollten Sie einen expliziten Standard setzen (`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 ausgelöste Konfigurationsschreibvorgänge (Supergruppen-ID-Migrationen, `/config set|unset`). -- Top-Level-`bindings[]`-Einträge mit `type: "acp"` konfigurieren persistente ACP-Bindings für Forenthemen (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). +- Optional überschreibt `channels.telegram.defaultAccount` die Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- In Setups mit mehreren Konten (2+ Konto-IDs) setzen Sie ein explizites Standardkonto (`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-Bindings für Forenthemen (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) dokumentiert. - Telegram-Stream-Vorschauen verwenden `sendMessage` + `editMessageText` (funktioniert in Direkt- und Gruppenchats). -- Wiederholungsrichtlinie: siehe [Wiederholungsrichtlinie](/de/concepts/retry). +- Retry-Richtlinie: siehe [Retry-Richtlinie](/de/concepts/retry). ### Discord @@ -278,7 +278,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Nur kurze Antworten.", + systemPrompt: "Short answers only.", }, }, }, @@ -286,7 +286,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress wird auf Discord auf partial abgebildet) + streaming: "off", // off | partial | block | progress (progress wird auf Discord zu partial abgebildet) maxLinesPerMessage: 17, ui: { components: { @@ -334,33 +334,33 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom ``` - Token: `channels.discord.token`, mit `DISCORD_BOT_TOKEN` als Fallback für das Standardkonto. -- Direkte ausgehende Aufrufe mit explizitem Discord-`token` verwenden dieses Token für den Aufruf; Konto-Wiederholungs-/Richtlinieneinstellungen stammen weiterhin aus dem ausgewählten Konto im aktiven Laufzeit-Snapshot. -- Optional überschreibt `channels.discord.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. -- Verwenden Sie `user:` (DM) oder `channel:` (Guild-Kanal) für Zustellungsziele; bloße numerische IDs werden abgelehnt. -- Guild-Slugs sind kleingeschrieben, Leerzeichen werden durch `-` ersetzt; Kanalschlüssel verwenden den slugifizierten Namen (ohne `#`). Bevorzugen Sie Guild-IDs. +- Direkte ausgehende Aufrufe, die ein explizites Discord-`token` angeben, verwenden dieses Token für den Aufruf; Retry-/Richtlinieneinstellungen des Kontos kommen weiterhin vom gewählten Konto im aktiven Laufzeit-Snapshot. +- Optional überschreibt `channels.discord.defaultAccount` die Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- Verwenden Sie `user:` (DM) oder `channel:` (Guild-Channel) für Zustellungsziele; reine numerische IDs werden abgelehnt. +- Guild-Slugs sind kleingeschrieben, Leerzeichen werden durch `-` ersetzt; Channel-Schlüssel verwenden den geslugten 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 Rolle erwähnen, aber nicht den Bot (ausgenommen @everyone/@here). -- `maxLinesPerMessage` (Standard 17) teilt hohe Nachrichten auch dann auf, wenn sie unter 2000 Zeichen liegen. -- `channels.discord.threadBindings` steuert threadgebundenes Discord-Routing: - - `enabled`: Discord-Überschreibung für threadgebundene Sitzungsfunktionen (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` sowie gebundene Zustellung/Routing) - - `idleHours`: Discord-Überschreibung für automatische Defokussierung bei Inaktivität in Stunden (`0` deaktiviert) - - `maxAgeHours`: Discord-Überschreibung für maximales Alter in Stunden (`0` deaktiviert) - - `spawnSubagentSessions`: Opt-in-Schalter für automatische Thread-Erstellung/-Bindung durch `sessions_spawn({ thread: true })` -- Top-Level-`bindings[]`-Einträge mit `type: "acp"` konfigurieren persistente ACP-Bindings für Kanäle und Threads (verwenden Sie 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 Discord-Sprachkanal-Gespräche und optionale automatische Teilnahme + TTS-Überschreibungen. -- `channels.discord.voice.daveEncryption` und `channels.discord.voice.decryptionFailureTolerance` werden an `@discordjs/voice`-DAVE-Optionen durchgereicht (`true` bzw. `24` standardmäßig). -- OpenClaw versucht zusätzlich, den Sprach-Empfang wiederherzustellen, indem nach wiederholten Entschlüsselungsfehlern eine Sprachsitzung verlassen und erneut betreten wird. -- `channels.discord.streaming` ist der kanonische Schlüssel für den Stream-Modus. Das alte `streamMode` und boolesche `streaming`-Werte werden automatisch migriert. -- `channels.discord.autoPresence` ordnet die Laufzeitverfügbarkeit der Bot-Präsenz zu (healthy => online, degraded => idle, exhausted => dnd) und erlaubt optionale Überschreibungen des Status-Texts. +- `channels.discord.guilds..ignoreOtherMentions` (und Channel-Überschreibungen) verwirft Nachrichten, die einen anderen Benutzer oder eine Rolle erwähnen, aber nicht den Bot (ohne @everyone/@here). +- `maxLinesPerMessage` (Standard 17) teilt hohe Nachrichten selbst dann auf, wenn sie unter 2000 Zeichen liegen. +- `channels.discord.threadBindings` steuert Discord-Thread-gebundenes Routing: + - `enabled`: Discord-Überschreibung für threadgebundene Sitzungsfunktionen (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` und gebundene Zustellung/Routing) + - `idleHours`: Discord-Überschreibung für automatisches Defokussieren bei Inaktivität in Stunden (`0` deaktiviert) + - `maxAgeHours`: Discord-Überschreibung für harte maximale Laufzeit in Stunden (`0` deaktiviert) + - `spawnSubagentSessions`: Opt-in-Schalter für automatische Thread-Erstellung/-Bindung bei `sessions_spawn({ thread: true })` +- Top-Level-Einträge in `bindings[]` mit `type: "acp"` konfigurieren persistente ACP-Bindings für Channels und Threads (verwenden Sie die Channel-/Thread-ID in `match.peer.id`). Die Feldsemantik ist gemeinsam in [ACP Agents](/de/tools/acp-agents#channel-specific-settings) dokumentiert. +- `channels.discord.ui.components.accentColor` setzt die Akzentfarbe für Discord-Components-v2-Container. +- `channels.discord.voice` aktiviert Discord-Sprachkanal-Konversationen und optionale Auto-Join- + TTS-Überschreibungen. +- `channels.discord.voice.daveEncryption` und `channels.discord.voice.decryptionFailureTolerance` werden an die DAVE-Optionen von `@discordjs/voice` durchgereicht (standardmäßig `true` und `24`). +- OpenClaw versucht zusätzlich, die Sprachübertragung wiederherzustellen, indem nach wiederholten Entschlüsselungsfehlern eine Sprachsitzung verlassen und erneut betreten wird. +- `channels.discord.streaming` ist der kanonische Schlüssel für den Stream-Modus. Die alten Werte `streamMode` und boolesches `streaming` werden automatisch migriert. +- `channels.discord.autoPresence` ordnet die Laufzeitverfügbarkeit der Bot-Präsenz zu (healthy => online, degraded => idle, exhausted => dnd) und erlaubt optionale Überschreibungen für den Statustext. - `channels.discord.dangerouslyAllowNameMatching` aktiviert veränderbares 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 weggelassen. - - `agentFilter`: optionale Erlaubnisliste für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. - - `sessionFilter`: optionale Sitzungsschlüssel-Muster (Teilzeichenfolge oder Regex). - - `target`: wohin Genehmigungsaufforderungen gesendet werden. `"dm"` (Standard) sendet an DMs der Genehmiger, `"channel"` sendet an den Ursprungskanal, `"both"` sendet an beide. Wenn `target` `"channel"` enthält, sind Schaltflächen nur für aufgelöste Genehmiger nutzbar. - - `cleanupAfterResolve`: wenn `true`, löscht Genehmigungs-DMs nach Genehmigung, Ablehnung oder Timeout. +- `channels.discord.execApprovals`: Discord-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigenden. + - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmigende 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 gesetzt. + - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. + - `sessionFilter`: optionale Muster für Sitzungsschlüssel (Teilstring oder Regex). + - `target`: wohin Genehmigungsaufforderungen gesendet werden. `"dm"` (Standard) sendet in die DMs der Genehmigenden, `"channel"` sendet in den Ursprungskanal, `"both"` sendet an beide. Wenn das Ziel `"channel"` einschließt, sind Buttons nur für aufgelöste Genehmigende nutzbar. + - `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). @@ -393,11 +393,11 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom } ``` -- Service-Account-JSON: inline (`serviceAccount`) oder dateibasiert (`serviceAccountFile`). -- Service-Account-SecretRef wird ebenfalls unterstützt (`serviceAccountRef`). -- Env-Fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` oder `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- JSON des Servicekontos: inline (`serviceAccount`) oder dateibasiert (`serviceAccountFile`). +- SecretRef für das Servicekonto wird ebenfalls unterstützt (`serviceAccountRef`). +- Umgebungs-Fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` oder `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Verwenden Sie `spaces/` oder `users/` für Zustellungsziele. -- `channels.googlechat.dangerouslyAllowNameMatching` aktiviert veränderbares E-Mail-Prinzipal-Matching erneut (Break-Glass-Kompatibilitätsmodus). +- `channels.googlechat.dangerouslyAllowNameMatching` aktiviert veränderbares Matching von E-Mail-Principals erneut (Break-Glass-Kompatibilitätsmodus). ### Slack @@ -419,7 +419,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Nur kurze Antworten.", + systemPrompt: "Short answers only.", }, }, historyLimit: 50, @@ -449,7 +449,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // Slack-native Streaming-API verwenden, wenn mode=partial + nativeTransport: true, // Slack-nativen Streaming-API verwenden, wenn mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,35 +464,30 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet autom } ``` -- **Socket-Modus** erfordert sowohl `botToken` als auch `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` als Env-Fallback für das Standardkonto). +- **Socket Mode** erfordert sowohl `botToken` als auch `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` als Umgebungs-Fallback für das Standardkonto). - **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-Anmeldedaten Quell-/Statusfelder 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 jedoch nicht auflösen konnte. -- `configWrites: false` blockiert von Slack ausgelöste Konfigurationsschreibvorgänge. -- Optional überschreibt `channels.slack.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. -- `channels.slack.streaming.mode` ist der kanonische Slack-Stream-Modus-Schlüssel. `channels.slack.streaming.nativeTransport` steuert Slacks nativen Streaming-Transport. Das alte `streamMode`, boolesche `streaming`- und `nativeStreaming`-Werte werden automatisch migriert. +- `botToken`, `appToken`, `signingSecret` und `userToken` akzeptieren Klartextzeichenfolgen 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 geheimen Wert jedoch nicht auflösen konnte. +- `configWrites: false` blockiert von Slack initiierte Konfigurationsschreibvorgänge. +- Optional überschreibt `channels.slack.defaultAccount` die Standardkontenauswahl, 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 Slacks nativen Streaming-Transport. Alte Werte `streamMode`, boolesches `streaming` und `nativeStreaming` werden automatisch migriert. - Verwenden Sie `user:` (DM) oder `channel:` für Zustellungsziele. **Modi für Reaktionsbenachrichtigungen:** `off`, `own` (Standard), `all`, `allowlist` (aus `reactionAllowlist`). -**Thread-Sitzungsisolierung:** `thread.historyScope` ist pro Thread (Standard) oder kanalweit geteilt. `thread.inheritParent` kopiert das Transkript des Elternkanals in neue Threads. +**Thread-Sitzungsisolierung:** `thread.historyScope` ist pro Thread (Standard) oder über den Channel geteilt. `thread.inheritParent` kopiert das Transkript des übergeordneten Channels in neue Threads. -- Slack-natives Streaming plus der Slack-assistant-artige Thread-Status „is typing...“ erfordern ein Antwort-Thread-Ziel. DMs auf oberster Ebene bleiben standardmäßig ohne Thread, daher verwenden sie `typingReaction` oder normale Zustellung statt der Thread-artigen Vorschau. -- `typingReaction` fügt der eingehenden Slack-Nachricht während einer laufenden Antwort vorübergehend eine Reaktion hinzu und entfernt sie nach Abschluss. Verwenden Sie einen Slack-Emoji-Kurznamen 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"`). +- Slack-natives Streaming plus der Slack-assistant-artige 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-Vorschau. +- `typingReaction` fügt der eingehenden Slack-Nachricht während der Antwortausführung temporär eine Reaktion hinzu 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 Genehmigenden. 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 | -| emojiList | aktiviert | Benutzerdefinierte Emoji-Liste | +| messages | aktiviert | Lesen/senden/bearbeiten/löschen | +| pins | aktiviert | Anheften/lösen/auflisten | +| memberInfo | aktiviert | Mitgliedsinformationen | +| emojiList | aktiviert | Liste benutzerdefinierter Emojis | ### Mattermost @@ -526,23 +521,19 @@ Mattermost wird als Plugin ausgeliefert: `openclaw plugins install @openclaw/mat } ``` -Chat-Modi: `oncall` (antwortet bei @-Erwähnung, Standard), `onmessage` (jede Nachricht), `onchar` (Nachrichten, die mit Trigger-Präfix beginnen). +Chat-Modi: `oncall` (bei @-Erwähnung antworten, Standard), `onmessage` (jede Nachricht), `onchar` (Nachrichten, die mit einem Trigger-Präfix beginnen). -Wenn native Mattermost-Befehle aktiviert sind: +Wenn Mattermost-native Befehle aktiviert sind: - `commands.callbackPath` muss ein Pfad sein (zum Beispiel `/api/channels/mattermost/command`), keine vollständige URL. -- `commands.callbackUrl` muss auf den OpenClaw-Gateway-Endpunkt auflösen und vom Mattermost-Server erreichbar sein. -- Native Slash-Callbacks werden mit den pro-Befehl-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/die Domain enthält. +- `commands.callbackUrl` muss zum OpenClaw-Gateway-Endpunkt aufgelöst werden und vom Mattermost-Server erreichbar sein. +- Native Slash-Callbacks werden mit den pro Befehl von Mattermost bei der Registrierung zurückgegebenen Tokens authentifiziert. Wenn die Registrierung fehlschlägt oder keine Befehle aktiviert sind, weist OpenClaw Callbacks mit `Unauthorized: invalid command token.` zurück. +- Für private/tailnet/interne Callback-Hosts kann Mattermost verlangen, dass `ServiceSettings.AllowedUntrustedInternalConnections` den Callback-Host/-Domain enthält. Verwenden Sie Host-/Domain-Werte, keine vollständigen URLs. -- `channels.mattermost.configWrites`: von Mattermost ausgelöste Konfigurationsschreibvorgänge erlauben oder verweigern. -- `channels.mattermost.requireMention`: `@mention` vor Antworten in Kanälen verlangen. -- `channels.mattermost.groups..requireMention`: kanalbezogene Überschreibung des Mention-Gatings (`"*"` für Standard). -- Optional überschreibt `channels.mattermost.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- `channels.mattermost.configWrites`: Mattermost-initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- `channels.mattermost.requireMention`: `@mention` vor einer Antwort in Channels verlangen. +- `channels.mattermost.groups..requireMention`: Überschreibung des Mention-Gatings pro Channel (`"*"` für Standard). +- Optional überschreibt `channels.mattermost.defaultAccount` die Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. ### Signal @@ -565,13 +556,13 @@ Wenn native Mattermost-Befehle aktiviert sind: **Modi für Reaktionsbenachrichtigungen:** `off`, `own` (Standard), `all`, `allowlist` (aus `reactionAllowlist`). -- `channels.signal.account`: Kanalstart an eine bestimmte Signal-Kontoidentität anheften. -- `channels.signal.configWrites`: von Signal ausgelöste Konfigurationsschreibvorgänge erlauben oder verweigern. -- Optional überschreibt `channels.signal.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- `channels.signal.account`: bindet den Channel-Start an eine bestimmte Signal-Kontoidentität. +- `channels.signal.configWrites`: von Signal initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- Optional überschreibt `channels.signal.defaultAccount` die Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. ### BlueBubbles -BlueBubbles ist der empfohlene iMessage-Pfad (pluginbasiert, konfiguriert unter `channels.bluebubbles`). +BlueBubbles ist der empfohlene iMessage-Pfad (plugin-gestützt, konfiguriert unter `channels.bluebubbles`). ```json5 { @@ -579,17 +570,17 @@ BlueBubbles ist der empfohlene iMessage-Pfad (pluginbasiert, konfiguriert unter bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, Gruppenkontrollen und erweiterte Aktionen: + // serverUrl, password, webhookPath, group controls und erweiterte actions: // siehe /channels/bluebubbles }, }, } ``` -- Hier behandelte Kern-Schlüsselpfade: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Optional überschreibt `channels.bluebubbles.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. -- Top-Level-`bindings[]`-Einträge 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). -- Die vollständige BlueBubbles-Kanalkonfiguration ist dokumentiert unter [BlueBubbles](/de/channels/bluebubbles). +- Hier abgedeckte zentrale Schlüsselpfade: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Optional überschreibt `channels.bluebubbles.defaultAccount` die Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- Top-Level-Einträge in `bindings[]` mit `type: "acp"` können BlueBubbles-Konversationen an persistente ACP-Sitzungen binden. Verwenden Sie ein BlueBubbles-Handle oder einen Zielstring (`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-Channel-Konfiguration ist in [BlueBubbles](/de/channels/bluebubbles) dokumentiert. ### iMessage @@ -617,15 +608,15 @@ OpenClaw startet `imsg rpc` (JSON-RPC über stdio). Kein Daemon oder Port erford } ``` -- Optional überschreibt `channels.imessage.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- Optional überschreibt `channels.imessage.defaultAccount` die Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. - Erfordert Vollzugriff auf die Messages-Datenbank. -- 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 den SCP-Abruf von Anhängen. -- `attachmentRoots` und `remoteAttachmentRoots` begrenzen eingehende Anhangspfade (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` existiert. -- `channels.imessage.configWrites`: von iMessage ausgelöste Konfigurationsschreibvorgänge erlauben oder verweigern. -- Top-Level-`bindings[]`-Einträge 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). +- Bevorzugen Sie Ziele im Format `chat_id:`. 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 eingehende Anhangspfade (Standard: `/Users/*/Library/Messages/Attachments`). +- SCP verwendet strikte Host-Key-Prüfung, daher stellen Sie sicher, dass der Schlüssel des Relay-Hosts bereits in `~/.ssh/known_hosts` vorhanden ist. +- `channels.imessage.configWrites`: von iMessage initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- Top-Level-Einträge in `bindings[]` mit `type: "acp"` können iMessage-Konversationen an persistente ACP-Sitzungen binden. Verwenden Sie ein normalisiertes 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). @@ -638,7 +629,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix ist extension-basiert und wird unter `channels.matrix` konfiguriert. +Matrix ist extension-gestützt und wird unter `channels.matrix` konfiguriert. ```json5 { @@ -669,24 +660,24 @@ Matrix ist extension-basiert 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 in Multi-Account-Setups das bevorzugte Konto aus. +- `channels.matrix.defaultAccount` wählt in Multi-Account-Setups das bevorzugte Konto. - `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-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. +- `channels.matrix.execApprovals`: Matrix-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigenden. + - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmigende 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 Erlaubnisliste für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. - - `sessionFilter`: optionale Sitzungsschlüssel-Muster (Teilzeichenfolge oder Regex). + - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. + - `sessionFilter`: optionale Muster für Sitzungsschlüssel (Teilstring oder Regex). - `target`: wohin Genehmigungsaufforderungen gesendet werden. `"dm"` (Standard), `"channel"` (Ursprungsraum) oder `"both"`. - - Pro-Konto-Überschreibungen: `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-Verzeichnisabfragen verwenden dieselbe Proxy-Richtlinie wie der Laufzeitverkehr. -- Vollständige Matrix-Konfiguration, Zielregeln und Setup-Beispiele sind dokumentiert unter [Matrix](/de/channels/matrix). + - Überschreibungen pro Konto: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` steuert, wie Matrix-DMs in Sitzungen gruppiert werden: `per-user` (Standard) teilt nach geroutetem Peer, während `per-room` jeden DM-Raum isoliert. +- Matrix-Statusprobes und Live-Verzeichnisabfragen verwenden dieselbe Proxy-Richtlinie wie der Laufzeitverkehr. +- Die vollständige Matrix-Konfiguration, Zielregeln und Setup-Beispiele sind in [Matrix](/de/channels/matrix) dokumentiert. ### Microsoft Teams -Microsoft Teams ist extension-basiert und wird unter `channels.msteams` konfiguriert. +Microsoft Teams ist extension-gestützt und wird unter `channels.msteams` konfiguriert. ```json5 { @@ -694,19 +685,19 @@ Microsoft Teams ist extension-basiert und wird unter `channels.msteams` konfigur msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, Team-/Kanalrichtlinien: + // appId, appPassword, tenantId, webhook, Team-/Channel-Richtlinien: // siehe /channels/msteams }, }, } ``` -- Hier behandelte Kern-Schlüsselpfade: `channels.msteams`, `channels.msteams.configWrites`. -- Die vollständige Teams-Konfiguration (Anmeldedaten, Webhook, DM-/Gruppenrichtlinie, Überschreibungen pro Team/pro Kanal) ist dokumentiert unter [Microsoft Teams](/de/channels/msteams). +- Hier abgedeckte zentrale Schlüsselpfade: `channels.msteams`, `channels.msteams.configWrites`. +- Die vollständige Teams-Konfiguration (Anmeldedaten, Webhook, DM-/Gruppenrichtlinie, Überschreibungen pro Team/pro Channel) ist in [Microsoft Teams](/de/channels/msteams) dokumentiert. ### IRC -IRC ist extension-basiert und wird unter `channels.irc` konfiguriert. +IRC ist extension-gestützt und wird unter `channels.irc` konfiguriert. ```json5 { @@ -727,13 +718,13 @@ IRC ist extension-basiert und wird unter `channels.irc` konfiguriert. } ``` -- Hier behandelte Kern-Schlüsselpfade: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Optional überschreibt `channels.irc.defaultAccount` die Standard-Kontoauswahl, wenn es einer konfigurierten Konto-ID entspricht. -- Die vollständige IRC-Kanalkonfiguration (Host/Port/TLS/Kanäle/Erlaubnislisten/Mention-Gating) ist dokumentiert unter [IRC](/de/channels/irc). +- Hier abgedeckte zentrale Schlüsselpfade: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Optional überschreibt `channels.irc.defaultAccount` die Standardkontenauswahl, wenn es einer konfigurierten Konto-ID entspricht. +- Die vollständige IRC-Channel-Konfiguration (Host/Port/TLS/Channels/Allowlists/Mention-Gating) ist in [IRC](/de/channels/irc) dokumentiert. -### Multi-Account (alle Kanäle) +### Mehrere Konten (alle Channels) -Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener `accountId`): +Führen Sie mehrere Konten pro Channel aus (jeweils mit eigener `accountId`): ```json5 { @@ -741,11 +732,11 @@ Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener `accountId`): telegram: { accounts: { default: { - name: "Primärer Bot", + name: "Primary bot", botToken: "123456:ABC...", }, alerts: { - name: "Alerts-Bot", + name: "Alerts bot", botToken: "987654:XYZ...", }, }, @@ -755,17 +746,17 @@ Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener `accountId`): ``` - `default` wird verwendet, wenn `accountId` weggelassen wird (CLI + Routing). -- Env-Tokens gelten nur für das **Standard**-Konto. -- Basis-Kanaleinstellungen gelten für alle Konten, sofern sie nicht pro Konto überschrieben werden. +- Umgebungs-Token gelten nur für das **Standardkonto**. +- Basiseinstellungen des Channels gelten für alle Konten, sofern nicht pro Konto überschrieben. - Verwenden Sie `bindings[].match.accountId`, um jedes Konto an einen anderen Agenten zu routen. -- Wenn Sie ein nicht-standardmäßiges Konto über `openclaw channels add` (oder Kanal-Onboarding) hinzufügen, während Sie noch eine kanalbezogene Single-Account-Konfiguration auf oberster Ebene haben, verschiebt OpenClaw zunächst kontoabhängige Werte der Top-Level-Single-Account-Konfiguration in die Kanal-Kontomap, sodass 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 reine Kanal-Bindings (ohne `accountId`) passen weiterhin zum Standardkonto; kontoabhängige Bindings bleiben optional. -- `openclaw doctor --fix` repariert auch gemischte Formen, indem kontoabhängige Top-Level-Single-Account-Werte in das für diesen Kanal gewählte beförderte Konto verschoben werden. Die meisten Kanäle verwenden `accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. +- Wenn Sie ein Nicht-Standardkonto über `openclaw channels add` (oder Channel-Onboarding) hinzufügen, während Sie noch eine Top-Level-Channel-Konfiguration für ein Einzelkonto haben, überführt OpenClaw zuerst die kontobezogenen Top-Level-Werte mit Einzelkonto in die Konto-Map des Channels, damit das ursprüngliche Konto weiter funktioniert. Die meisten Channels verschieben sie nach `channels..accounts.default`; Matrix kann stattdessen ein bestehendes passendes benanntes/Standardziel beibehalten. +- Bestehende nur-kanalbezogene Bindings (ohne `accountId`) passen weiterhin auf das Standardkonto; kontobezogene Bindings bleiben optional. +- `openclaw doctor --fix` repariert auch gemischte Formen, indem kontobezogene Top-Level-Werte mit Einzelkonto in das für diesen Channel gewählte hochgestufte Konto verschoben werden. Die meisten Channels verwenden `accounts.default`; Matrix kann stattdessen ein bestehendes passendes benanntes/Standardziel beibehalten. -### Andere Extension-Kanäle +### Andere Extension-Channels -Viele Extension-Kanäle werden als `channels.` konfiguriert und in ihren jeweiligen Kanal-Seiten dokumentiert (zum Beispiel Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat und Twitch). -Siehe den vollständigen Kanalindex: [Kanäle](/de/channels). +Viele Extension-Channels werden als `channels.` konfiguriert und in ihren dedizierten Channel-Seiten dokumentiert (zum Beispiel Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat und Twitch). +Siehe den vollständigen Channel-Index: [Channels](/de/channels). ### Mention-Gating in Gruppenchats @@ -773,8 +764,8 @@ Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erw **Erwähnungstypen:** -- **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. +- **Metadaten-Erwähnungen**: native @-Erwähnungen der Plattform. Im WhatsApp-Self-Chat-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 Erkennung möglich ist (native Erwähnungen oder mindestens ein Muster). ```json5 @@ -788,7 +779,7 @@ Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erw } ``` -`messages.groupChat.historyLimit` setzt den globalen Standard. Kanäle können mit `channels..historyLimit` (oder pro Konto) überschreiben. Setzen Sie `0`, um zu deaktivieren. +`messages.groupChat.historyLimit` setzt den globalen Standard. Channels können ihn mit `channels..historyLimit` (oder pro Konto) überschreiben. Setzen Sie `0`, um ihn zu deaktivieren. #### DM-Verlaufslimits @@ -805,13 +796,13 @@ Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erw } ``` -Auflösung: Überschreibung pro DM → Provider-Standard → kein Limit (alles wird beibehalten). +Auflösung: Überschreibung pro DM → Provider-Standard → kein Limit (alles bleibt erhalten). Unterstützt: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Selbstchat-Modus +#### Self-Chat-Modus -Fügen Sie Ihre eigene Nummer in `allowFrom` ein, um den Selbstchat-Modus zu aktivieren (ignoriert native @-Erwähnungen, antwortet nur auf Textmuster): +Fügen Sie Ihre eigene Nummer zu `allowFrom` hinzu, um den Self-Chat-Modus zu aktivieren (ignoriert native @-Erwähnungen, antwortet nur auf Textmuster): ```json5 { @@ -832,7 +823,7 @@ Fügen Sie Ihre eigene Nummer in `allowFrom` ein, um den Selbstchat-Modus zu akt } ``` -### Befehle (Behandlung von Chat-Befehlen) +### Commands (Verarbeitung von Chat-Befehlen) ```json5 { @@ -861,38 +852,38 @@ Fügen Sie Ihre eigene Nummer in `allowFrom` ein, um den Selbstchat-Modus zu akt -- Dieser Block konfiguriert Befehlsflä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`, memory `/dreaming`, phone-control `/phone` und Talk `/voice` sind in ihren Kanal-/plugin-Seiten sowie unter [Slash-Befehle](/de/tools/slash-commands) dokumentiert. +- 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 in ihren Channel-/Plugin-Seiten sowie unter [Slash Commands](/de/tools/slash-commands) dokumentiert. - Textbefehle müssen eigenständige Nachrichten mit führendem `/` sein. -- `native: "auto"` aktiviert native Befehle für Discord/Telegram, lässt Slack deaktiviert. -- `nativeSkills: "auto"` aktiviert native Skill-Befehle für Discord/Telegram, lässt Slack deaktiviert. -- Pro Kanal überschreiben: `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`. +- `native: "auto"` schaltet native Befehle für Discord/Telegram ein, lässt Slack aus. +- `nativeSkills: "auto"` schaltet native Skill-Befehle für Discord/Telegram ein, lässt Slack aus. +- Überschreibung pro Channel: `channels.discord.commands.native` (boolesch oder `"auto"`). `false` löscht zuvor registrierte Befehle. +- Überschreiben Sie die Registrierung nativer Skills pro Channel 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 den Sender in `tools.elevated.allowFrom.`. -- `config: true` aktiviert `/config` (liest/schreibt `openclaw.json`). Für Gateway-`chat.send`-Clients erfordern persistente `/config set|unset`-Schreibvorgänge außerdem `operator.admin`; schreibgeschütztes `/config show` bleibt für normale Operator-Clients mit Schreibbereich verfügbar. +- `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 `chat.send`-Clients des Gateways erfordern persistente Schreibvorgänge via `/config set|unset` zusätzlich `operator.admin`; nur lesendes `/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 und Aktivieren/Deaktivieren. -- `channels..configWrites` steuert Konfigurationsänderungen pro Kanal (Standard: true). -- Bei Multi-Account-Kanälen steuert `channels..accounts..configWrites` auch Schreibvorgänge, die dieses Konto betreffen (zum Beispiel `/allowlist --config --account ` oder `/config set channels..accounts....`). +- `plugins: true` aktiviert `/plugins` für Plugin-Erkennung, Installation und Steuerung von Aktivierung/Deaktivierung. +- `channels..configWrites` steuert Konfigurationsänderungen pro Channel (Standard: true). +- Für Multi-Account-Channels 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 Gateway-Neustart-Tool-Aktionen. Standard: `true`. -- `ownerAllowFrom` ist die explizite Eigentümer-Erlaubnisliste für eigentümerexklusive Befehle/Tools. Sie ist getrennt von `allowFrom`. -- `ownerDisplay: "hash"` hasht Eigentümer-IDs im Systemprompt. Setzen Sie `ownerDisplaySecret`, um das Hashing zu steuern. -- `allowFrom` ist pro Provider. Wenn gesetzt, ist es die **einzige** Autorisierungsquelle (Kanal-Erlaubnislisten/Pairing und `useAccessGroups` werden ignoriert). -- `useAccessGroups: false` erlaubt Befehlen, Access-Group-Richtlinien zu umgehen, wenn `allowFrom` nicht gesetzt ist. +- `ownerAllowFrom` ist die explizite Eigentümer-Allowlist für eigentümerexklusive 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 pro Provider. Wenn gesetzt, ist es die **einzige** Autorisierungsquelle (Channel-Allowlists/Pairing und `useAccessGroups` werden ignoriert). +- `useAccessGroups: false` erlaubt Befehlen, Richtlinien von Zugriffsgruppen zu umgehen, wenn `allowFrom` nicht gesetzt ist. - Zuordnung der Befehlsdokumentation: - - integrierter + gebündelter Katalog: [Slash-Befehle](/de/tools/slash-commands) - - kanalspezifische Befehlsflächen: [Kanäle](/de/channels) - - QQ Bot-Befehle: [QQ Bot](/de/channels/qqbot) + - integrierter + gebündelter Katalog: [Slash Commands](/de/tools/slash-commands) + - kanalspezifische Befehlsoberflächen: [Channels](/de/channels) + - QQ-Bot-Befehle: [QQ Bot](/de/channels/qqbot) - Pairing-Befehle: [Pairing](/de/channels/pairing) - - LINE-Kartenbefehl: [LINE](/de/channels/line) + - LINE-Card-Befehl: [LINE](/de/channels/line) - Memory-Dreaming: [Dreaming](/de/concepts/dreaming) --- -## Agent-Standardeinstellungen +## Agent-Standards ### `agents.defaults.workspace` @@ -906,7 +897,7 @@ Standard: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Optionales Repository-Root, das in der Runtime-Zeile des Systemprompts angezeigt wird. Wenn nicht gesetzt, erkennt OpenClaw es automatisch, indem es vom Workspace aus nach oben läuft. +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 läuft. ```json5 { @@ -916,8 +907,7 @@ Optionales Repository-Root, das in der Runtime-Zeile des Systemprompts angezeigt ### `agents.defaults.skills` -Optionale Standard-Erlaubnisliste für Skills für Agenten, die -`agents.list[].skills` nicht setzen. +Optionale Standard-Allowlist für Skills für Agenten, die `agents.list[].skills` nicht setzen. ```json5 { @@ -932,10 +922,10 @@ Optionale Standard-Erlaubnisliste für Skills für Agenten, die } ``` -- Lassen Sie `agents.defaults.skills` weg, um standardmäßig uneingeschränkte Skills zuzulassen. +- Lassen Sie `agents.defaults.skills` weg, um standardmäßig uneingeschränkte Skills zu erlauben. - Lassen Sie `agents.list[].skills` weg, um die Standards zu erben. -- Setzen Sie `agents.list[].skills: []`, um keine Skills zuzulassen. -- Eine nicht-leere Liste in `agents.list[].skills` ist die endgültige Menge für diesen Agenten; sie wird nicht mit Standards zusammengeführt. +- Setzen Sie `agents.list[].skills: []`, um keine Skills zu erlauben. +- Eine nichtleere Liste in `agents.list[].skills` ist die endgültige Menge für diesen Agenten; sie wird nicht mit den Standards zusammengeführt. ### `agents.defaults.skipBootstrap` @@ -949,9 +939,9 @@ Deaktiviert die automatische Erstellung von Workspace-Bootstrap-Dateien (`AGENTS ### `agents.defaults.contextInjection` -Steuert, wann Workspace-Bootstrap-Dateien in den Systemprompt injiziert werden. Standard: `"always"`. +Steuert, wann Workspace-Bootstrap-Dateien in den System-Prompt injiziert werden. Standard: `"always"`. -- `"continuation-skip"`: Sichere Fortsetzungs-Turns (nach einer abgeschlossenen Assistentenantwort) überspringen die erneute Injektion des Workspace-Bootstraps und reduzieren so die Prompt-Größe. Heartbeat-Läufe und Wiederholungen nach Kompaktierung bauen den Kontext weiterhin neu auf. +- `"continuation-skip"`: sichere Fortsetzungsturns (nach einer abgeschlossenen Assistentenantwort) überspringen die erneute Injektion von Workspace-Bootstrap, wodurch die Prompt-Größe reduziert wird. Heartbeat-Läufe und Wiederholungen nach Kompaktierung bauen den Kontext weiterhin neu auf. ```json5 { @@ -961,7 +951,7 @@ Steuert, wann Workspace-Bootstrap-Dateien in den Systemprompt injiziert werden. ### `agents.defaults.bootstrapMaxChars` -Maximale Zeichen pro Workspace-Bootstrap-Datei vor Abschneidung. Standard: `20000`. +Maximale Zeichenanzahl pro Workspace-Bootstrap-Datei vor dem Abschneiden. Standard: `20000`. ```json5 { @@ -971,7 +961,7 @@ Maximale Zeichen pro Workspace-Bootstrap-Datei vor Abschneidung. Standard: `2000 ### `agents.defaults.bootstrapTotalMaxChars` -Maximale Gesamtzahl an injizierten Zeichen über alle Workspace-Bootstrap-Dateien. Standard: `150000`. +Maximale Gesamtanzahl von Zeichen, die über alle Workspace-Bootstrap-Dateien injiziert werden. Standard: `150000`. ```json5 { @@ -981,12 +971,12 @@ Maximale Gesamtzahl an injizierten Zeichen über alle Workspace-Bootstrap-Dateie ### `agents.defaults.bootstrapPromptTruncationWarning` -Steuert den für Agenten sichtbaren Warntext, wenn Bootstrap-Kontext abgeschnitten wird. +Steuert den für Agenten sichtbaren Warntext, wenn der Bootstrap-Kontext abgeschnitten wird. Standard: `"once"`. -- `"off"`: niemals Warntext in den Systemprompt injizieren. -- `"once"`: Warnung einmal pro eindeutiger Abschneidesignatur injizieren (empfohlen). -- `"always"`: Warnung bei jedem Lauf injizieren, wenn Abschneidung vorliegt. +- `"off"`: niemals Warntext in den System-Prompt injizieren. +- `"once"`: Warnung einmal pro eindeutiger Abschneidungssignatur injizieren (empfohlen). +- `"always"`: Warnung bei jedem Lauf injizieren, wenn eine Abschneidung vorliegt. ```json5 { @@ -999,8 +989,8 @@ Standard: `"once"`. Maximale Pixelgröße der längsten Bildseite in Transkript-/Tool-Bildblöcken vor Provider-Aufrufen. Standard: `1200`. -Niedrigere Werte reduzieren meist den Verbrauch von Vision-Tokens und die Größe der Request-Payload bei screenshotlastigen Läufen. -Höhere Werte erhalten mehr visuelle Details. +Kleinere Werte reduzieren in der Regel die Nutzung von Vision-Tokens und die Größe der Request-Payload bei screenshotlastigen Läufen. +Größere Werte erhalten mehr visuelle Details. ```json5 { @@ -1010,7 +1000,7 @@ Höhere Werte erhalten mehr visuelle Details. ### `agents.defaults.userTimezone` -Zeitzone für den Systemprompt-Kontext (nicht Nachrichtentimestamps). Fällt auf die Host-Zeitzone zurück. +Zeitzone für den Kontext des System-Prompts (nicht für Zeitstempel von Nachrichten). Fällt auf die Zeitzone des Hosts zurück. ```json5 { @@ -1020,7 +1010,7 @@ Zeitzone für den Systemprompt-Kontext (nicht Nachrichtentimestamps). Fällt auf ### `agents.defaults.timeFormat` -Zeitformat im Systemprompt. Standard: `auto` (OS-Präferenz). +Zeitformat im System-Prompt. Standard: `auto` (OS-Einstellung). ```json5 { @@ -1073,43 +1063,43 @@ Zeitformat im Systemprompt. Standard: `auto` (OS-Präferenz). } ``` -- `model`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - 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 }`). +- `model`: akzeptiert entweder eine Zeichenfolge (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). + - Die Zeichenfolgenform setzt nur das primäre Modell. + - Die Objektform setzt das primäre Modell plus geordnete Failover-Modelle. +- `imageModel`: akzeptiert entweder eine Zeichenfolge (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - 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 auch als Fallback-Routing verwendet, wenn das gewählte/Standardmodell keine Bildeingaben akzeptieren kann. +- `imageGenerationModel`: akzeptiert entweder eine Zeichenfolge (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - Wird von der gemeinsamen Bildgenerierungsfunktion und jeder zukünftigen Tool-/Plugin-Oberfläche verwendet, die Bilder erzeugt. - 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 Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key 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 weggelassen, kann `image_generate` trotzdem einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider, dann die verbleibenden registrierten Bildgenerierungs-Provider in Provider-ID-Reihenfolge. -- `musicGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird von der gemeinsamen Musikgenerierungsfunktion und dem integrierten `music_generate`-Tool verwendet. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key (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 Provider-Standard ableiten. Es versucht zuerst den aktuellen Standardprovider, dann die übrigen registrierten Bildgenerierungsprovider in Provider-ID-Reihenfolge. +- `musicGenerationModel`: akzeptiert entweder eine Zeichenfolge (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). + - Wird von der gemeinsamen Musikgenerierungsfunktion und dem integrierten Tool `music_generate` verwendet. - Typische Werte: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` oder `minimax/music-2.5+`. - - Wenn weggelassen, kann `music_generate` trotzdem einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider, dann die verbleibenden registrierten Musikgenerierungs-Provider in Provider-ID-Reihenfolge. - - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key dazu. -- `videoGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird von der gemeinsamen Videogenerierungsfunktion und dem integrierten `video_generate`-Tool verwendet. + - Wenn nicht gesetzt, kann `music_generate` trotzdem einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standardprovider, dann die übrigen registrierten Musikgenerierungsprovider in Provider-ID-Reihenfolge. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key. +- `videoGenerationModel`: akzeptiert entweder eine Zeichenfolge (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). + - Wird von der gemeinsamen Videogenerierungsfunktion und dem 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 weggelassen, kann `video_generate` trotzdem einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider, dann die verbleibenden registrierten Videogenerierungs-Provider in Provider-ID-Reihenfolge. - - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key dazu. - - Der gebündelte Qwen-Videogenerierungs-Provider unterstützt derzeit bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer sowie providerbezogene Optionen `size`, `aspectRatio`, `resolution`, `audio` und `watermark`. -- `pdfModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird vom `pdf`-Tool für Modell-Routing verwendet. - - Wenn weggelassen, fällt das PDF-Tool auf `imageModel`, 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`: Standardhöchstzahl von Seiten, die im Extraktions-Fallback-Modus des `pdf`-Tools berücksichtigt werden. -- `verboseDefault`: Standard-Verbose-Stufe für Agenten. Werte: `"off"`, `"on"`, `"full"`. Standard: `"off"`. + - Wenn nicht gesetzt, kann `video_generate` trotzdem einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standardprovider, dann die übrigen registrierten Videogenerierungsprovider in Provider-ID-Reihenfolge. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung/API-Key. + - Der gebündelte Qwen-Provider für Videogenerierung unterstützt bis zu 1 Ausgabenvideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer und Provider-Optionen auf Ebene von `size`, `aspectRatio`, `resolution`, `audio` und `watermark`. +- `pdfModel`: akzeptiert entweder eine Zeichenfolge (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). + - Wird vom `pdf`-Tool für das Modellrouting verwendet. + - Wenn nicht gesetzt, fällt das PDF-Tool auf `imageModel` und anschließend auf das aufgelöste Sitzungs-/Standardmodell zurück. +- `pdfMaxBytesMb`: Standardgrenze für die PDF-Größe des `pdf`-Tools, wenn `maxBytesMb` beim Aufruf nicht übergeben wird. +- `pdfMaxPages`: standardmäßige maximale Seitenzahl, die der Extraktions-Fallback-Modus im `pdf`-Tool berücksichtigt. +- `verboseDefault`: Standard-Verbose-Level für Agenten. Werte: `"off"`, `"on"`, `"full"`. Standard: `"off"`. - `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 einen eindeutigen Match eines konfigurierten Providers für genau diese Modell-ID und fällt erst dann auf den konfigurierten Standard-Provider zurück (veraltetes Kompatibilitätsverhalten, daher bevorzugen Sie explizit `provider/model`). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr anbietet, fällt OpenClaw auf das erste konfigurierte Provider-/Modell zurück, statt einen veralteten entfernten Provider-Standard anzuzeigen. -- `models`: der konfigurierte Modellkatalog und die Erlaubnisliste für `/model`. Jeder Eintrag kann `alias` (Kurzform) und `params` (providerspezifisch, z. B. `temperature`, `maxTokens`, `cacheRetention`, `context1m`) enthalten. -- `params`: globale Standard-Provider-Parameter, die auf alle Modelle angewendet werden. Setzen unter `agents.defaults.params` (z. B. `{ cacheRetention: "long" }`). -- `params`-Merge-Priorität (Konfiguration): `agents.defaults.params` (globale Basis) wird überschrieben durch `agents.defaults.models["provider/model"].params` (pro Modell), dann überschreibt `agents.list[].params` (passende Agent-ID) pro Schlüssel. Siehe [Prompt Caching](/de/reference/prompt-caching) für Details. -- 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 bestehende Fallback-Listen nach Möglichkeit. -- `maxConcurrent`: maximale parallele Agent-Läufe über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4. +- `model.primary`: Format `provider/model` (z. B. `openai/gpt-5.4`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann einen eindeutigen Match eines konfigurierten Providers für genau diese Modell-ID und fällt erst dann auf den konfigurierten Standardprovider zurück (veraltetes Kompatibilitätsverhalten, daher `provider/model` bevorzugen). 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 Allowlist für `/model`. Jeder Eintrag kann `alias` (Abkürzung) und `params` (providerspezifisch, z. B. `temperature`, `maxTokens`, `cacheRetention`, `context1m`) enthalten. +- `params`: globale Standard-Provider-Parameter, die auf alle Modelle angewendet werden. Setzen Sie sie unter `agents.defaults.params` (z. B. `{ cacheRetention: "long" }`). +- Merge-Priorität für `params` (Konfiguration): `agents.defaults.params` (globale Basis) wird von `agents.defaults.models["provider/model"].params` (pro Modell) überschrieben, dann überschreibt `agents.list[].params` (passende Agent-ID) nach Schlüssel. Siehe [Prompt Caching](/de/reference/prompt-caching) für Details. +- Konfigurationsschreiber, die diese Felder ändern (zum Beispiel `/models set`, `/models set-image` und Fallback-add/remove-Befehle), speichern die kanonische Objektform und erhalten bestehende Fallback-Listen nach Möglichkeit. +- `maxConcurrent`: maximale Zahl paralleler Agentenläufe über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4. -**Integrierte Alias-Kurzformen** (gelten nur, wenn das Modell in `agents.defaults.models` steht): +**Integrierte Alias-Kurzformen** (gelten nur, wenn das Modell in `agents.defaults.models` enthalten ist): | Alias | Modell | | ------------------- | -------------------------------------- | @@ -1122,15 +1112,15 @@ Zeitformat im Systemprompt. Standard: `auto` (OS-Präferenz). | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ihre konfigurierten Aliasse haben immer Vorrang vor Standards. +Ihre konfigurierten Aliase haben immer Vorrang vor den Standardwerten. -Z.AI-GLM-4.x-Modelle aktivieren den Thinking-Modus automatisch, sofern Sie nicht `--thinking off` setzen oder `agents.defaults.models["zai/"].params.thinking` selbst definieren. -Z.AI-Modelle aktivieren `tool_stream` standardmäßig für Tool-Call-Streaming. Setzen Sie `agents.defaults.models["zai/"].params.tool_stream` auf `false`, um dies zu deaktivieren. -Anthropic Claude 4.6-Modelle verwenden standardmäßig `adaptive` Thinking, wenn keine explizite Thinking-Stufe gesetzt ist. +Z.AI-GLM-4.x-Modelle aktivieren den Thinking-Modus automatisch, es sei denn, Sie setzen `--thinking off` oder definieren `agents.defaults.models["zai/"].params.thinking` selbst. +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. +Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive` Thinking, wenn kein explizites Thinking-Level gesetzt ist. ### `agents.defaults.cliBackends` -Optionale CLI-Backends für Text-only-Fallback-Läufe (keine Tool-Aufrufe). Nützlich als Reserve, wenn API-Provider ausfallen. +Optionale CLI-Backends für Text-only-Fallback-Läufe (ohne Tool-Aufrufe). Nützlich als Backup, wenn API-Provider ausfallen. ```json5 { @@ -1160,7 +1150,21 @@ Optionale CLI-Backends für Text-only-Fallback-Läufe (keine Tool-Aufrufe). Nüt - CLI-Backends sind textorientiert; Tools sind immer deaktiviert. - Sitzungen werden unterstützt, wenn `sessionArg` gesetzt ist. -- Bild-Durchleitung wird unterstützt, wenn `imageArg` Dateipfade akzeptiert. +- Bilddurchleitung wird unterstützt, wenn `imageArg` Dateipfade akzeptiert. + +### `agents.defaults.systemPromptOverride` + +Ersetzt den vollständig von OpenClaw zusammengesetzten System-Prompt durch eine feste Zeichenfolge. Kann auf Standardebene (`agents.defaults.systemPromptOverride`) oder pro Agent (`agents.list[].systemPromptOverride`) gesetzt werden. Werte pro Agent haben Vorrang; ein leerer oder nur aus Leerraum bestehender Wert wird ignoriert. Nützlich für kontrollierte Prompt-Experimente. + +```json5 +{ + agents: { + defaults: { + systemPromptOverride: "You are a helpful assistant.", + }, + }, +} +``` ### `agents.defaults.heartbeat` @@ -1174,13 +1178,14 @@ 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 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 frischen Sitzung aus (kein Gesprächsverlauf) session: "main", to: "+15555550123", directPolicy: "allow", // allow (Standard) | block target: "none", // Standard: none | Optionen: last | whatsapp | telegram | discord | ... - prompt: "Lese HEARTBEAT.md, falls vorhanden...", + prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1189,12 +1194,13 @@ Periodische Heartbeat-Läufe. } ``` -- `every`: Dauer-String (ms/s/m/h). Standard: `30m` (API-Key-Authentifizierung) oder `1h` (OAuth-Authentifizierung). Setzen Sie `0m`, um zu deaktivieren. -- `suppressToolErrorWarnings`: wenn true, werden Tool-Fehlerwarn-Payloads während Heartbeat-Läufen unterdrückt. -- `directPolicy`: Richtlinie für direkte/DM-Zustellung. `allow` (Standard) erlaubt direkte Zielzustellung. `block` unterdrückt direkte Zielzustellung und erzeugt `reason=dm-blocked`. -- `lightContext`: wenn true, verwenden Heartbeat-Läufe leichten Bootstrap-Kontext und behalten aus den Workspace-Bootstrap-Dateien nur `HEARTBEAT.md`. -- `isolatedSession`: wenn true, läuft jeder Heartbeat in einer frischen Sitzung ohne vorherigen Gesprächsverlauf. Gleiches 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 ein Agent `heartbeat` definiert, führen **nur diese Agenten** Heartbeats aus. +- `every`: Dauerzeichenfolge (ms/s/m/h). Standard: `30m` (API-Key-Authentifizierung) oder `1h` (OAuth-Authentifizierung). Setzen Sie `0m`, um zu deaktivieren. +- `includeSystemPromptSection`: wenn false, lässt den Heartbeat-Abschnitt im System-Prompt weg und überspringt die Injektion von `HEARTBEAT.md` in den Bootstrap-Kontext. Standard: `true`. +- `suppressToolErrorWarnings`: wenn true, unterdrückt Warn-Payloads für Tool-Fehler während Heartbeat-Läufen. +- `directPolicy`: Richtlinie für direkte/DM-Zustellung. `allow` (Standard) erlaubt Zustellung an Direktziele. `block` unterdrückt Zustellung an Direktziele 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, läuft jeder Heartbeat in einer frischen Sitzung ohne vorherigen Gesprächsverlauf. Gleiches Isolationsmuster wie bei Cron `sessionTarget: "isolated"`. Reduziert die Token-Kosten pro Heartbeat von etwa 100K auf etwa 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. ### `agents.defaults.compaction` @@ -1205,19 +1211,19 @@ Periodische Heartbeat-Läufe. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // ID eines registrierten Compaction-Provider-Plugins (optional) + provider: "my-provider", // ID eines registrierten Provider-Plugins für Kompaktierung (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Deployment-IDs, Ticket-IDs und Host:Port-Paare exakt beibehalten.", // verwendet bei identifierPolicy=custom + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // verwendet, wenn identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] deaktiviert Re-Injektion - model: "openrouter/anthropic/claude-sonnet-4-6", // optionale modellbezogene Überschreibung nur für Compaction - notifyUser: true, // kurze Benachrichtigung senden, wenn die Compaction startet (Standard: false) + model: "openrouter/anthropic/claude-sonnet-4-6", // optionale nur-für-Kompaktierung-Modellüberschreibung + notifyUser: true, // kurze Benachrichtigung senden, wenn die Kompaktierung beginnt (Standard: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Sitzung nähert sich der Compaction. Dauerhafte Erinnerungen jetzt speichern.", - prompt: "Schreibe bleibende Notizen nach memory/YYYY-MM-DD.md; antworte mit dem exakten stillen Token NO_REPLY, wenn nichts zu speichern ist.", + 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.", }, }, }, @@ -1225,19 +1231,19 @@ Periodische Heartbeat-Läufe. } ``` -- `mode`: `default` oder `safeguard` (chunkweise Zusammenfassung für lange Verläufe). Siehe [Compaction](/de/concepts/compaction). -- `provider`: ID eines registrierten Compaction-Provider-Plugins. Wenn gesetzt, wird `summarize()` des Providers statt der integrierten LLM-Zusammenfassung aufgerufen. Bei Fehlern wird auf die integrierte Methode zurückgefallen. Das Setzen eines Providers erzwingt `mode: "safeguard"`. Siehe [Compaction](/de/concepts/compaction). -- `timeoutSeconds`: maximale Anzahl von Sekunden für eine einzelne Compaction-Operation, bevor OpenClaw sie abbricht. Standard: `900`. -- `identifierPolicy`: `strict` (Standard), `off` oder `custom`. `strict` stellt bei der Compaction-Zusammenfassung integrierte Hinweise zur Beibehaltung opaker Kennungen voran. -- `identifierInstructions`: optionaler benutzerdefinierter Text zur Beibehaltung von Kennungen, verwendet bei `identifierPolicy=custom`. -- `postCompactionSections`: optionale H2/H3-Abschnittsnamen aus AGENTS.md, die nach der Compaction erneut injiziert werden. Standard ist `["Session Startup", "Red Lines"]`; setzen Sie `[]`, um die Re-Injektion zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften `Every Session`/`Safety` auch als Legacy-Fallback akzeptiert. -- `model`: optionale Überschreibung `provider/model-id` nur für die Compaction-Zusammenfassung. Verwenden Sie dies, wenn die Hauptsitzung ein Modell behalten soll, Compaction-Zusammenfassungen aber auf einem anderen laufen sollen; wenn nicht gesetzt, verwendet Compaction das primäre Modell der Sitzung. -- `notifyUser`: wenn `true`, wird dem Benutzer beim Start der Compaction eine kurze Mitteilung gesendet (zum Beispiel „Kontext wird kompaktiert...“). Standardmäßig deaktiviert, um Compaction still zu halten. -- `memoryFlush`: stiller agentischer Turn vor automatischer Compaction, um dauerhafte Erinnerungen zu speichern. Wird übersprungen, wenn der Workspace schreibgeschützt ist. +- `mode`: `default` oder `safeguard` (chunkweise Zusammenfassung für lange Verläufe). Siehe [Kompaktierung](/de/concepts/compaction). +- `provider`: ID eines registrierten Provider-Plugins für Kompaktierung. Wenn gesetzt, wird statt der integrierten LLM-Zusammenfassung die `summarize()`-Funktion des Providers aufgerufen. Fällt bei Fehlern auf die integrierte Variante zurück. Das Setzen eines Providers erzwingt `mode: "safeguard"`. Siehe [Kompaktierung](/de/concepts/compaction). +- `timeoutSeconds`: maximale Sekundenanzahl, die für einen einzelnen Kompaktierungsvorgang erlaubt ist, bevor OpenClaw ihn abbricht. Standard: `900`. +- `identifierPolicy`: `strict` (Standard), `off` oder `custom`. `strict` stellt bei der Kompaktierungszusammenfassung integrierte Hinweise zur Beibehaltung opaker Bezeichner voran. +- `identifierInstructions`: optionaler benutzerdefinierter Text zur Beibehaltung von Bezeichnern, der verwendet wird, wenn `identifierPolicy=custom`. +- `postCompactionSections`: optionale Abschnittsnamen auf H2/H3-Ebene aus AGENTS.md, die nach der Kompaktierung erneut injiziert werden. Standardmäßig `["Session Startup", "Red Lines"]`; setzen Sie `[]`, um die Re-Injektion zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften `Every Session`/`Safety` auch als Legacy-Fallback akzeptiert. +- `model`: optionale Überschreibung `provider/model-id` nur für die Kompaktierungszusammenfassung. Verwenden Sie dies, wenn die Hauptsitzung ein Modell behalten soll, Kompaktierungszusammenfassungen aber auf einem anderen Modell laufen sollen; wenn nicht gesetzt, verwendet die Kompaktierung das primäre Modell der Sitzung. +- `notifyUser`: wenn `true`, sendet eine kurze Benachrichtigung an den Benutzer, wenn die Kompaktierung beginnt (zum Beispiel „Compacting context...“). Standardmäßig deaktiviert, damit die Kompaktierung lautlos bleibt. +- `memoryFlush`: lautloser agentischer Turn vor der automatischen Kompaktierung, um dauerhafte Erinnerungen zu speichern. Wird übersprungen, wenn der Workspace schreibgeschützt ist. ### `agents.defaults.contextPruning` -Beschneidet **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor sie an das LLM gesendet werden. Ändert **nicht** den Sitzungsverlauf auf der Festplatte. +Schneidet **alte Tool-Ergebnisse** vor dem Senden an das LLM aus dem In-Memory-Kontext heraus. Ändert **nicht** den Sitzungsverlauf auf der Festplatte. ```json5 { @@ -1251,7 +1257,7 @@ Beschneidet **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor sie an das hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Inhalt altes Tool-Ergebnis gelöscht]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1259,25 +1265,25 @@ Beschneidet **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor sie an das } ``` - + -- `mode: "cache-ttl"` aktiviert Beschneidungsläufe. -- `ttl` steuert, wie oft die Beschneidung erneut laufen darf (nach der letzten Cache-Berührung). -- Die Beschneidung beschneidet zuerst übergroße Tool-Ergebnisse sanft und löscht bei Bedarf danach ältere Tool-Ergebnisse vollständig. +- `mode: "cache-ttl"` aktiviert Bereinigungsläufe. +- `ttl` steuert, wie oft die Bereinigung erneut ausgeführt werden kann (nach der letzten Cache-Berührung). +- Die Bereinigung kürzt zunächst übergroße Tool-Ergebnisse weich und löscht dann bei Bedarf ältere Tool-Ergebnisse vollständig. -**Sanftes Beschneiden** behält Anfang + Ende bei und fügt in der Mitte `...` ein. +**Soft-Trim** behält Anfang + Ende und fügt in der Mitte `...` ein. -**Hartes Löschen** ersetzt das gesamte Tool-Ergebnis durch den Platzhalter. +**Hard-Clear** ersetzt das gesamte Tool-Ergebnis durch den Platzhalter. Hinweise: -- Bildblöcke werden niemals beschnitten/gelöscht. -- Verhältnisse basieren auf Zeichen (ungefähr), nicht auf exakten Token-Zahlen. -- Wenn weniger als `keepLastAssistants` Assistentennachrichten vorhanden sind, wird die Beschneidung übersprungen. +- Bildblöcke werden niemals gekürzt/gelöscht. +- Verhältnisse sind zeichenbasiert (ungefähr), keine exakten Token-Anzahlen. +- Wenn weniger als `keepLastAssistants` Assistentennachrichten existieren, wird die Bereinigung übersprungen. -Siehe [Sitzungsbeschneidung](/de/concepts/session-pruning) für Verhaltensdetails. +Details zum Verhalten finden Sie unter [Sitzungsbereinigung](/de/concepts/session-pruning). ### Block-Streaming @@ -1295,13 +1301,13 @@ Siehe [Sitzungsbeschneidung](/de/concepts/session-pruning) für Verhaltensdetail } ``` -- Nicht-Telegram-Kanäle erfordern explizit `*.blockStreaming: true`, um Block-Antworten 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. Pro-Agent-Überschreibung: `agents.list[].humanDelay`. +- Nicht-Telegram-Channels erfordern explizit `*.blockStreaming: true`, um Block-Antworten zu aktivieren. +- Überschreibungen pro Channel: `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`. -Siehe [Streaming](/de/concepts/streaming) für Verhaltens- und Chunking-Details. +Siehe [Streaming](/de/concepts/streaming) für Verhalten + Chunking-Details. -### Tipppindikatoren +### Tippindikatoren ```json5 { @@ -1314,16 +1320,16 @@ Siehe [Streaming](/de/concepts/streaming) für Verhaltens- und Chunking-Details. } ``` -- Standards: `instant` für Direktchats/Erwähnungen, `message` für Gruppenchats ohne Erwähnung. -- Pro-Sitzungs-Überschreibungen: `session.typingMode`, `session.typingIntervalSeconds`. +- Standardwerte: `instant` für Direktchats/Erwähnungen, `message` für nicht erwähnte Gruppenchats. +- Überschreibungen pro Sitzung: `session.typingMode`, `session.typingIntervalSeconds`. -Siehe [Tipppindikatoren](/de/concepts/typing-indicators). +Siehe [Tippindikatoren](/de/concepts/typing-indicators). ### `agents.defaults.sandbox` -Optionales Sandboxing für den eingebetteten Agenten. Siehe [Sandboxing](/de/gateway/sandboxing) für die vollständige Anleitung. +Optionale Sandboxing-Funktion für den eingebetteten Agenten. Den vollständigen Leitfaden finden Sie unter [Sandboxing](/de/gateway/sandboxing). ```json5 { @@ -1369,7 +1375,7 @@ Optionales Sandboxing für den eingebetteten Agenten. Siehe [Sandboxing](/de/gat identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / Inline-Inhalte werden ebenfalls unterstützt: + // SecretRefs / Inline-Inhalte ebenfalls unterstützt: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1423,47 +1429,47 @@ Optionales Sandboxing für den eingebetteten Agenten. Siehe [Sandboxing](/de/gat **Backend:** - `docker`: lokale Docker-Laufzeit (Standard) -- `ssh`: generische SSH-basierte Remote-Laufzeit +- `ssh`: generische SSH-gestützte Remote-Laufzeit - `openshell`: OpenShell-Laufzeit -Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstellungen nach -`plugins.entries.openshell.config` verschoben. +Wenn `backend: "openshell"` gewählt ist, verschieben sich laufzeitspezifische Einstellungen nach +`plugins.entries.openshell.config`. -**SSH-Backend-Konfiguration:** +**Konfiguration des SSH-Backends:** -- `target`: SSH-Ziel in Form `user@host[:port]` +- `target`: SSH-Ziel im Format `user@host[:port]` - `command`: SSH-Client-Befehl (Standard: `ssh`) -- `workspaceRoot`: absolutes Remote-Root, das für Workspaces pro Scope verwendet wird +- `workspaceRoot`: absolutes Remote-Root für Workspaces pro Scope - `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 Host-Key-Richtlinien +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH-Regler für die Host-Key-Richtlinie -**SSH-Authentifizierungs-Priorität:** +**SSH-Authentifizierungspriorität:** - `identityData` hat Vorrang vor `identityFile` - `certificateData` hat Vorrang vor `certificateFile` - `knownHostsData` hat Vorrang vor `knownHostsFile` -- SecretRef-basierte `*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 Snapshot der Secrets-Laufzeit aufgelöst, bevor die Sandbox-Sitzung startet -**SSH-Backend-Verhalten:** +**Verhalten des SSH-Backends:** - initialisiert den Remote-Workspace einmal nach Erstellen oder Neuerstellen - behält danach den Remote-SSH-Workspace als kanonisch bei -- leitet `exec`, Datei-Tools und Medienpfade über SSH -- synchronisiert Remote-Änderungen nicht automatisch zurück zum Host -- unterstützt keine Sandbox-Browser-Container +- leitet `exec`, Dateitools und Medienpfade über SSH +- synchronisiert Remote-Änderungen nicht automatisch zurück auf den Host +- unterstützt keine browserbasierten Sandbox-Container **Workspace-Zugriff:** - `none`: Workspace pro Scope unter `~/.openclaw/sandboxes` -- `ro`: Sandbox-Workspace unter `/workspace`, Agent-Workspace schreibgeschützt unter `/agent` eingebunden -- `rw`: Agent-Workspace mit Lese-/Schreibzugriff unter `/workspace` eingebunden +- `ro`: Sandbox-Workspace unter `/workspace`, Agent-Workspace schreibgeschützt unter `/agent` eingehängt +- `rw`: Agent-Workspace lesend/schreibend unter `/workspace` eingehängt **Scope:** - `session`: Container + Workspace pro Sitzung - `agent`: ein Container + Workspace pro Agent (Standard) -- `shared`: gemeinsamer Container und gemeinsamer Workspace (keine sitzungsübergreifende Isolierung) +- `shared`: gemeinsam genutzter Container und Workspace (keine sitzungsübergreifende Isolation) **OpenShell-Plugin-Konfiguration:** @@ -1494,31 +1500,31 @@ Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstell **OpenShell-Modus:** - `mirror`: Remote vor `exec` aus lokalem Stand initialisieren, nach `exec` zurücksynchronisieren; lokaler Workspace bleibt kanonisch -- `remote`: Remote einmal beim Erstellen der Sandbox initialisieren, danach bleibt der Remote-Workspace kanonisch +- `remote`: Remote einmal initialisieren, wenn die Sandbox erstellt wird, dann den Remote-Workspace als kanonisch beibehalten -Im `remote`-Modus werden hostlokale Änderungen, die außerhalb von OpenClaw vorgenommen werden, nach dem Initialisierungsschritt nicht automatisch in die Sandbox synchronisiert. +Im Modus `remote` werden hostlokale Bearbeitungen außerhalb von OpenClaw 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 die optionale Mirror-Synchronisierung. -**`setupCommand`** läuft einmal nach dem Erstellen des Containers (über `sh -lc`). Benötigt ausgehenden Netzwerkzugriff, beschreibbares Root und Root-Benutzer. +**`setupCommand`** läuft einmal nach dem Erstellen des Containers (via `sh -lc`). Benötigt Netzwerk-Egress, beschreibbares Root und Root-Benutzer. -**Container verwenden standardmäßig `network: "none"`** — setzen Sie `"bridge"` (oder ein benutzerdefiniertes Bridge-Netzwerk), wenn der Agent ausgehenden Zugriff benötigt. -`"host"` ist blockiert. `"container:"` ist standardmäßig blockiert, sofern Sie nicht explizit -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` setzen (Break-Glass). +**Container verwenden standardmäßig `network: "none"`** — setzen Sie dies auf `"bridge"` (oder ein benutzerdefiniertes Bridge-Netzwerk), wenn der Agent ausgehenden Zugriff benötigt. +`"host"` wird blockiert. `"container:"` wird standardmäßig blockiert, es sei denn, Sie setzen explizit +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (Break-Glass). -**Eingehende Anhänge** werden in `media/inbound/*` im aktiven Workspace abgelegt. +**Eingehende Anhänge** werden in `media/inbound/*` im aktiven Workspace bereitgestellt. -**`docker.binds`** bindet zusätzliche Host-Verzeichnisse ein; globale und pro-Agent-Binds werden zusammengeführt. +**`docker.binds`** hängt zusätzliche Host-Verzeichnisse ein; globale und pro Agent definierte Binds werden zusammengeführt. -**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP in einem Container. Die noVNC-URL wird in den Systemprompt injiziert. Erfordert kein `browser.enabled` in `openclaw.json`. -noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung, und OpenClaw erzeugt eine kurzlebige Token-URL (anstatt das Passwort in der geteilten URL offenzulegen). +**Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP in einem Container. Die noVNC-URL wird in den System-Prompt injiziert. Benötigt kein `browser.enabled` in `openclaw.json`. +noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung und OpenClaw gibt eine URL mit kurzlebigem Token aus (statt das Passwort in der geteilten URL offenzulegen). -- `allowHostControl: false` (Standard) blockiert, dass sandboxierte Sitzungen den Host-Browser ansteuern. -- `network` ist standardmäßig `openclaw-sandbox-browser` (dediziertes Bridge-Netzwerk). Setzen Sie `bridge` nur, wenn Sie ausdrücklich globale Bridge-Konnektivität wünschen. -- `cdpSourceRange` kann den CDP-Zugang am Containerrand optional auf einen CIDR-Bereich beschränken (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 für Container-Hosts abgestimmt: +- `allowHostControl: false` (Standard) blockiert, dass sandboxed Sitzungen auf den Host-Browser 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` kann eingehenden CDP-Verkehr am Container-Rand optional auf einen CIDR-Bereich beschränken (zum Beispiel `172.21.0.1/32`). +- `sandbox.browser.binds` hängt 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-Standardeinstellungen 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` @@ -1534,21 +1540,15 @@ 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 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 das - Standard-Prozesslimit von Chromium zu verwenden. + - `--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 die Nutzung von WebGL/3D 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 das Standard-Prozesslimit von Chromium zu verwenden. - plus `--no-sandbox` und `--disable-setuid-sandbox`, wenn `noSandbox` aktiviert ist. - - Standards sind die Basis des Container-Images; verwenden Sie ein benutzerdefiniertes Browser-Image mit einem benutzerdefinierten - Entry-Point, um Container-Standards zu ändern. + - Die Standardwerte sind die Baseline des Container-Images; verwenden Sie ein benutzerdefiniertes Browser-Image mit benutzerdefiniertem Entry-Point, um Container-Standardeinstellungen zu ändern. -Browser-Sandboxing und `sandbox.docker.binds` sind derzeit nur für Docker verfügbar. +Browser-Sandboxing und `sandbox.docker.binds` sind nur für Docker verfügbar. Images bauen: @@ -1557,7 +1557,7 @@ scripts/sandbox-setup.sh # Haupt-Sandbox-Image scripts/sandbox-browser-setup.sh # optionales Browser-Image ``` -### `agents.list` (agentbezogene Überschreibungen) +### `agents.list` (Überschreibungen pro Agent) ```json5 { @@ -1566,18 +1566,18 @@ scripts/sandbox-browser-setup.sh # optionales Browser-Image { id: "main", default: true, - name: "Hauptagent", + name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // oder { primary, fallbacks } - thinkingDefault: "high", // agentbezogene Überschreibung der Thinking-Stufe - reasoningDefault: "on", // agentbezogene Überschreibung der Sichtbarkeit von Reasoning - fastModeDefault: false, // agentbezogene Überschreibung des Schnellmodus - params: { cacheRetention: "none" }, // überschreibt passende defaults.models-Parameter pro Schlüssel + thinkingDefault: "high", // Überschreibung des Thinking-Levels pro Agent + reasoningDefault: "on", // Überschreibung der Sichtbarkeit von Reasoning pro Agent + fastModeDefault: false, // Überschreibung des schnellen Modus pro Agent + params: { cacheRetention: "none" }, // überschreibt passende defaults.models-Parameter nach Schlüssel skills: ["docs-search"], // ersetzt agents.defaults.skills, wenn gesetzt identity: { name: "Samantha", - theme: "hilfreiches Faultier", + theme: "helpful sloth", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1606,25 +1606,25 @@ scripts/sandbox-browser-setup.sh # optionales Browser-Image ``` - `id`: stabile Agent-ID (erforderlich). -- `default`: wenn mehrere gesetzt sind, gewinnt der erste (Warnung wird protokolliert). Wenn keiner gesetzt ist, ist der erste Listeneintrag der Standard. -- `model`: String-Form überschreibt nur `primary`; Objekt-Form `{ primary, fallbacks }` überschreibt beides (`[]` deaktiviert globale Fallbacks). Cron-Jobs, die nur `primary` überschreiben, erben weiterhin Standard-Fallbacks, sofern Sie nicht `fallbacks: []` setzen. -- `params`: agentbezogene Stream-Parameter, 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 agentbezogene Skill-Erlaubnisliste. Wenn weggelassen, erbt der Agent `agents.defaults.skills`, falls gesetzt; eine explizite Liste ersetzt Standards statt sie zusammenzuführen, und `[]` bedeutet keine Skills. -- `thinkingDefault`: optionale agentbezogene Standard-Thinking-Stufe (`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 agentbezogene Standardsichtbarkeit für Reasoning (`on | off | stream`). Gilt, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist. -- `fastModeDefault`: optionale agentbezogene Standardeinstellung für den Schnellmodus (`true | false`). Gilt, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist. -- `runtime`: optionaler agentbezogener Laufzeitdeskriptor. 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. -- `identity` leitet Standards ab: `ackReaction` aus `emoji`, `mentionPatterns` aus `name`/`emoji`. -- `subagents.allowAgents`: Erlaubnisliste von Agent-IDs für `sessions_spawn` (`["*"]` = beliebig; Standard: nur derselbe Agent). -- Schutz vor Sandbox-Vererbung: Wenn die anfragende Sitzung sandboxiert ist, lehnt `sessions_spawn` Ziele ab, die unsandboxiert laufen würden. -- `subagents.requireAgentId`: wenn true, blockiert `sessions_spawn` Aufrufe ohne `agentId` (erzwingt explizite Profilauswahl; Standard: false). +- `default`: wenn mehrere gesetzt sind, gewinnt der erste (mit Warnung im Log). Wenn keiner gesetzt ist, wird der erste Listeneintrag Standard. +- `model`: Die Zeichenfolgenform überschreibt nur `primary`; die Objektform `{ primary, fallbacks }` überschreibt beides (`[]` deaktiviert globale Fallbacks). Cron-Jobs, die nur `primary` überschreiben, erben weiterhin Standard-Fallbacks, sofern Sie nicht `fallbacks: []` setzen. +- `params`: Stream-Parameter pro Agent, die über den ausgewählten Modelleintrag in `agents.defaults.models` gemerged werden. 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`, sofern gesetzt; eine explizite Liste ersetzt die Standards statt sie zusammenzuführen, und `[]` bedeutet keine Skills. +- `thinkingDefault`: optionales standardmäßiges Thinking-Level 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 standardmäßige Sichtbarkeit von Reasoning pro Agent (`on | off | stream`). Gilt, wenn keine Überschreibung von Reasoning pro Nachricht oder Sitzung gesetzt ist. +- `fastModeDefault`: optionaler Standard pro Agent für den schnellen Modus (`true | false`). Gilt, wenn keine Überschreibung des schnellen Modus pro Nachricht oder Sitzung gesetzt ist. +- `runtime`: optionaler Laufzeitdeskriptor pro Agent. Verwenden Sie `type: "acp"` mit Standardwerten aus `runtime.acp` (`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` von `emoji`, `mentionPatterns` von `name`/`emoji`. +- `subagents.allowAgents`: Allowlist von Agent-IDs für `sessions_spawn` (`["*"]` = beliebig; Standard: nur derselbe Agent). +- Guardrail für Sandbox-Vererbung: wenn die anfragende Sitzung sandboxed ist, 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 Gateways aus. Siehe [Multi-Agent](/de/concepts/multi-agent). +Führen Sie mehrere isolierte Agenten in einem Gateway aus. Siehe [Multi-Agent](/de/concepts/multi-agent). ```json5 { @@ -1643,7 +1643,7 @@ Führen Sie mehrere isolierte Agenten innerhalb eines Gateways aus. Siehe [Multi ### Binding-Match-Felder -- `type` (optional): `route` für normales Routing (fehlender Typ entspricht route), `acp` für persistente ACP-Konversations-Bindings. +- `type` (optional): `route` für normales Routing (fehlender Typ bedeutet standardmäßig route), `acp` für persistente ACP-Konversations-Bindings. - `match.channel` (erforderlich) - `match.accountId` (optional; `*` = beliebiges Konto; weggelassen = Standardkonto) - `match.peer` (optional; `{ kind: direct|group|channel, id }`) @@ -1656,16 +1656,16 @@ Führen Sie mehrere isolierte Agenten innerhalb eines Gateways aus. Siehe [Multi 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (exakt, ohne peer/guild/team) -5. `match.accountId: "*"` (kanalweit) -6. Standardagent +5. `match.accountId: "*"` (channelweit) +6. Standard-Agent -Innerhalb jeder Stufe gewinnt der erste passende `bindings`-Eintrag. +Innerhalb jeder Stufe gewinnt der erste passende Eintrag in `bindings`. -Für `type: "acp"`-Einträge löst OpenClaw über die exakte Konversationsidentität auf (`match.channel` + Konto + `match.peer.id`) und verwendet nicht die obige Stufenreihenfolge für Route-Bindings. +Für Einträge mit `type: "acp"` löst OpenClaw nach exakter Konversationsidentität auf (`match.channel` + Konto + `match.peer.id`) und verwendet nicht die obige Stufenreihenfolge für Route-Bindings. ### Zugriffsprofile pro Agent - + ```json5 { @@ -1758,7 +1758,7 @@ Für `type: "acp"`-Einträge löst OpenClaw über die exakte Konversationsidenti -Siehe [Multi-Agent-Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für Prioritätsdetails. +Details zur Priorität finden Sie unter [Multi-Agent Sandbox & Tools](/de/tools/multi-agent-sandbox-tools). --- @@ -1784,7 +1784,7 @@ Siehe [Multi-Agent-Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für Pr }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // über diesem Token-Count keinen Eltern-Thread-Fork (0 deaktiviert) + parentForkMaxTokens: 100000, // Überspringt das Forken vom Parent-Thread oberhalb dieser Token-Anzahl (0 deaktiviert) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1792,14 +1792,14 @@ Siehe [Multi-Agent-Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für Pr rotateBytes: "10mb", resetArchiveRetention: "30d", // Dauer oder false maxDiskBytes: "500mb", // optionales hartes Budget - highWaterBytes: "400mb", // optionales Ziel nach Bereinigung + highWaterBytes: "400mb", // optionales Bereinigungsziel }, threadBindings: { enabled: true, - idleHours: 24, // Standard für automatische Defokussierung bei Inaktivität in Stunden (`0` deaktiviert) - maxAgeHours: 0, // Standard für maximales Alter in Stunden (`0` deaktiviert) + idleHours: 24, // standardmäßiges automatisches Defokussieren bei Inaktivität in Stunden (`0` deaktiviert) + maxAgeHours: 0, // standardmäßige harte Maximaldauer in Stunden (`0` deaktiviert) }, - mainKey: "main", // Legacy (Laufzeit verwendet immer "main") + mainKey: "main", // legacy (Laufzeit verwendet immer "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1811,35 +1811,35 @@ Siehe [Multi-Agent-Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für Pr -- **`scope`**: Basisstrategie für die Gruppierung von Sitzungen in Gruppenchats. - - `per-sender` (Standard): jeder Sender erhält innerhalb eines Kanalkontexts eine isolierte Sitzung. - - `global`: alle Teilnehmer in einem Kanalkontext teilen sich eine gemeinsame Sitzung (nur verwenden, wenn gemeinsamer Kontext beabsichtigt ist). +- **`scope`**: Basisstrategie für die Sitzungsgruppierung in Gruppenchats. + - `per-sender` (Standard): jeder Absender erhält innerhalb eines Channel-Kontexts eine isolierte Sitzung. + - `global`: alle Teilnehmer in einem Channel-Kontext teilen sich eine einzelne Sitzung (nur verwenden, wenn gemeinsam genutzter Kontext beabsichtigt ist). - **`dmScope`**: wie DMs gruppiert werden. - - `main`: alle DMs teilen die Hauptsitzung. - - `per-peer`: isoliert nach Sender-ID über Kanäle hinweg. - - `per-channel-peer`: isoliert pro Kanal + Sender (empfohlen für Multi-User-Posteingänge). - - `per-account-channel-peer`: isoliert pro Konto + Kanal + Sender (empfohlen für Multi-Account). -- **`identityLinks`**: Zuordnung kanonischer IDs zu providerpräfixierten Peers für kanalübergreifendes Teilen von Sitzungen. -- **`reset`**: primäre Reset-Richtlinie. `daily` setzt bei `atHour` lokaler Zeit zurück; `idle` setzt nach `idleMinutes` zurück. Wenn beide konfiguriert sind, gilt diejenige, die zuerst abläuft. -- **`resetByType`**: Überschreibungen pro Typ (`direct`, `group`, `thread`). Das alte `dm` wird als Alias für `direct` akzeptiert. -- **`parentForkMaxTokens`**: maximal erlaubte `totalTokens` der Elternsitzung beim Erstellen einer geforkten Thread-Sitzung (Standard `100000`). - - Wenn die `totalTokens` des Elternteils über diesem Wert liegen, startet OpenClaw eine frische Thread-Sitzung, statt den Gesprächsverlauf des Elternteils zu erben. - - Setzen Sie `0`, um diese Schutzfunktion zu deaktivieren und immer Eltern-Forks zu erlauben. -- **`mainKey`**: Legacy-Feld. Die Laufzeit verwendet jetzt immer `"main"` für den Haupt-Bucket im Direktchat. -- **`agentToAgent.maxPingPongTurns`**: maximale Anzahl von Antwort-Rückantwort-Turns zwischen Agenten bei Agent-zu-Agent-Austausch (Ganzzahl, Bereich: `0`–`5`). `0` deaktiviert Ping-Pong-Ketten. -- **`sendPolicy`**: Match nach `channel`, `chatType` (`direct|group|channel`, mit altem Alias `dm`), `keyPrefix` oder `rawKeyPrefix`. Erste Ablehnung gewinnt. + - `main`: alle DMs teilen sich die Hauptsitzung. + - `per-peer`: Isolation nach Absender-ID über Channels hinweg. + - `per-channel-peer`: Isolation pro Channel + Absender (empfohlen für Multi-User-Posteingänge). + - `per-account-channel-peer`: Isolation pro Konto + Channel + Absender (empfohlen für mehrere Konten). +- **`identityLinks`**: Zuordnung kanonischer IDs zu providerpräfixierten Peers für sitzungsübergreifendes Teilen über Channels hinweg. +- **`reset`**: primäre Reset-Richtlinie. `daily` setzt bei `atHour` in lokaler Zeit zurück; `idle` setzt nach `idleMinutes` zurück. Wenn beides konfiguriert ist, gewinnt das, was zuerst ausläuft. +- **`resetByType`**: Überschreibungen pro Typ (`direct`, `group`, `thread`). Legacy `dm` wird als Alias für `direct` akzeptiert. +- **`parentForkMaxTokens`**: maximale `totalTokens` der Elternsitzung beim Erstellen einer geforkten Thread-Sitzung (Standard `100000`). + - Wenn `totalTokens` des Parents über diesem Wert liegt, startet OpenClaw stattdessen eine frische Thread-Sitzung, anstatt den Verlauf des Parent-Transkripts zu erben. + - Setzen Sie `0`, um diesen Schutz zu deaktivieren und Parent-Forking immer zu erlauben. +- **`mainKey`**: Legacy-Feld. Die Laufzeit verwendet immer `"main"` für den Haupt-Bucket für Direktchats. +- **`agentToAgent.maxPingPongTurns`**: maximale Anzahl von Antwort-Rück-Turns zwischen Agenten während 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`. Das erste deny gewinnt. - **`maintenance`**: Bereinigung + Aufbewahrungssteuerung für den Sitzungs-Store. - - `mode`: `warn` gibt nur Warnungen aus; `enforce` wendet Bereinigung an. + - `mode`: `warn` gibt nur Warnungen aus; `enforce` führt Bereinigung aus. - `pruneAfter`: Altersgrenze für veraltete Einträge (Standard `30d`). - `maxEntries`: maximale Anzahl von Einträgen in `sessions.json` (Standard `500`). - - `rotateBytes`: rotiert `sessions.json`, wenn es diese Größe überschreitet (Standard `10mb`). - - `resetArchiveRetention`: Aufbewahrung für `*.reset.`-Transkriptarchive. Standardmäßig gleich `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 der Budget-Bereinigung. Standardmäßig `80%` von `maxDiskBytes`. -- **`threadBindings`**: globale Standards für threadgebundene Sitzungsfunktionen. - - `enabled`: globaler Standard-Schalter (Provider können überschreiben; Discord verwendet `channels.discord.threadBindings.enabled`) - - `idleHours`: Standard für automatische Defokussierung bei Inaktivität in Stunden (`0` deaktiviert; Provider können überschreiben) - - `maxAgeHours`: Standard für maximales Alter in Stunden (`0` deaktiviert; Provider können überschreiben) + - `rotateBytes`: rotiert `sessions.json`, wenn diese Größe überschritten wird (Standard `10mb`). + - `resetArchiveRetention`: Aufbewahrung für Transkriptarchive `*.reset.`. Standardmäßig gleich `pruneAfter`; setzen Sie `false`, um zu deaktivieren. + - `maxDiskBytes`: optionales Plattenbudget für das Sitzungsverzeichnis. Im Modus `warn` werden Warnungen protokolliert; im Modus `enforce` werden zuerst die ältesten Artefakte/Sitzungen entfernt. + - `highWaterBytes`: optionales Ziel nach Budget-Bereinigung. Standardmäßig `80%` von `maxDiskBytes`. +- **`threadBindings`**: globale Standardwerte für threadgebundene Sitzungsfunktionen. + - `enabled`: globaler Standardschalter (Provider können überschreiben; Discord verwendet `channels.discord.threadBindings.enabled`) + - `idleHours`: standardmäßiges automatisches Defokussieren bei Inaktivität in Stunden (`0` deaktiviert; Provider können überschreiben) + - `maxAgeHours`: standardmäßige harte Maximaldauer in Stunden (`0` deaktiviert; Provider können überschreiben) @@ -1875,38 +1875,38 @@ Siehe [Multi-Agent-Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für Pr } ``` -### Antwort-Präfix +### Antwortpräfix -Überschreibungen pro Kanal/Konto: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Überschreibungen pro Channel/Konto: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Auflösung (spezifischstes gewinnt): Konto → Kanal → global. `""` deaktiviert und stoppt die Kaskade. `"auto"` leitet `[{identity.name}]` ab. +Auflösung (am spezifischsten gewinnt): Konto → Channel → global. `""` deaktiviert und stoppt die Kaskade. `"auto"` leitet `[{identity.name}]` ab. **Vorlagenvariablen:** | Variable | Beschreibung | Beispiel | | ----------------- | --------------------- | --------------------------- | -| `{model}` | Kurzer Modellname | `claude-opus-4-6` | -| `{modelFull}` | Vollständige Modellkennung | `anthropic/claude-opus-4-6` | -| `{provider}` | Provider-Name | `anthropic` | -| `{thinkingLevel}` | Aktuelle Thinking-Stufe | `high`, `low`, `off` | +| `{model}` | kurzer Modellname | `claude-opus-4-6` | +| `{modelFull}` | vollständiger Modellbezeichner | `anthropic/claude-opus-4-6` | +| `{provider}` | Providername | `anthropic` | +| `{thinkingLevel}` | aktuelles Thinking-Level | `high`, `low`, `off` | | `{identity.name}` | Name der Agentenidentität | (gleich wie `"auto"`) | Variablen sind nicht case-sensitiv. `{think}` ist ein Alias für `{thinkingLevel}`. -### Bestätigungsreaktion +### Empfangsbestätigungs-Reaktion -- Standardmäßig das `identity.emoji` des aktiven Agenten, sonst `"👀"`. Setzen Sie `""`, um zu deaktivieren. -- Überschreibungen pro Kanal: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Reihenfolge der Auflösung: Konto → Kanal → `messages.ackReaction` → Identity-Fallback. +- Standard ist `identity.emoji` des aktiven Agenten, andernfalls `"👀"`. Setzen Sie `""`, um zu deaktivieren. +- Überschreibungen pro Channel: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Auflösungsreihenfolge: Konto → Channel → `messages.ackReaction` → Identity-Fallback. - Scope: `group-mentions` (Standard), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: entfernt die Bestätigung 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. - Bei Telegram müssen Sie es explizit auf `true` setzen, um Lifecycle-Statusreaktionen zu aktivieren. +- `removeAckAfterReply`: entfernt die Empfangsbestätigung nach der Antwort in Slack, Discord und Telegram. +- `messages.statusReactions.enabled`: aktiviert Lifecycle-Statusreaktionen in Slack, Discord und Telegram. + In Slack und Discord bleiben Statusreaktionen bei nicht gesetztem Wert aktiviert, wenn Empfangsbestätigungsreaktionen aktiv sind. + In Telegram muss es explizit auf `true` gesetzt werden, um Lifecycle-Statusreaktionen zu aktivieren. -### Entprellung eingehender Nachrichten +### Eingehendes Debouncing -Bündelt schnelle reine Textnachrichten desselben Senders zu einem einzigen Agent-Turn. Medien/Anhänge leeren sofort. Steuerbefehle umgehen die Entprellung. +Bündelt schnelle textbasierte Nachrichten desselben Absenders zu einem einzigen Agenten-Turn. Medien/Anhänge werden sofort geleert. Kontrollbefehle umgehen das Debouncing. ### TTS (Text-to-Speech) @@ -1949,7 +1949,7 @@ Bündelt schnelle reine Textnachrichten desselben Senders zu einem einzigen Agen } ``` -- `auto` steuert den Standard-Auto-TTS-Modus: `off`, `always`, `inbound` oder `tagged`. `/tts on|off` kann lokale Präferenzen überschreiben, und `/tts status` zeigt den effektiven Zustand. +- `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. - `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-Keys fallen auf `ELEVENLABS_API_KEY`/`XI_API_KEY` und `OPENAI_API_KEY` zurück. @@ -1984,13 +1984,13 @@ Standardeinstellungen für den Talk-Modus (macOS/iOS/Android). } ``` -- `talk.provider` muss bei mehreren konfigurierten Talk-Providern einem Schlüssel in `talk.providers` entsprechen. -- Alte flache Talk-Schlüssel (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) sind nur noch kompatibilitätsbedingt vorhanden 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. +- `talk.provider` muss einem Schlüssel in `talk.providers` entsprechen, wenn mehrere Talk-Provider konfiguriert sind. +- Legacy-Talk-Schlüssel in flacher Form (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) dienen nur der Kompatibilität und werden automatisch nach `talk.providers.` migriert. +- Stimmen-IDs fallen auf `ELEVENLABS_VOICE_ID` oder `SAG_VOICE_ID` zurück. +- `providers.*.apiKey` akzeptiert Klartextzeichenfolgen oder SecretRef-Objekte. - Der Fallback `ELEVENLABS_API_KEY` gilt nur, wenn kein Talk-API-Key konfiguriert ist. -- `providers.*.voiceAliases` ermöglicht Talk-Anweisungen die Verwendung freundlicher Namen. -- `silenceTimeoutMs` steuert, wie lange der Talk-Modus nach Benutzerstille wartet, bevor das Transkript gesendet wird. Nicht gesetzt behält das plattformspezifische Standard-Pausenfenster bei (`700 ms auf macOS und Android, 900 ms auf iOS`). +- `providers.*.voiceAliases` erlaubt es Talk-Anweisungen, benutzerfreundliche Namen zu verwenden. +- `silenceTimeoutMs` steuert, wie lange der Talk-Modus nach Benutzerschweigen 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`). --- @@ -1998,9 +1998,9 @@ Standardeinstellungen für den Talk-Modus (macOS/iOS/Android). ### Tool-Profile -`tools.profile` setzt eine Basis-Erlaubnisliste vor `tools.allow`/`tools.deny`: +`tools.profile` setzt eine Basis-Allowlist vor `tools.allow`/`tools.deny`: -Lokales Onboarding setzt für neue lokale Konfigurationen standardmäßig `tools.profile: "coding"`, wenn nicht gesetzt (bestehende explizite Profile bleiben erhalten). +Lokales Onboarding setzt neue lokale Konfigurationen standardmäßig auf `tools.profile: "coding"`, wenn nicht gesetzt (bestehende explizite Profile bleiben erhalten). | Profil | Enthält | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | @@ -2013,7 +2013,7 @@ Lokales Onboarding setzt für neue lokale Konfigurationen standardmäßig `tools | Gruppe | Tools | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` wird als Alias für `exec` akzeptiert) | +| `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` | @@ -2024,11 +2024,11 @@ Lokales Onboarding setzt für neue lokale Konfigurationen standardmäßig `tools | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Alle integrierten Tools (ohne Provider-Plugins) | +| `group:openclaw` | Alle integrierten Tools (schließt Provider-Plugins aus) | ### `tools.allow` / `tools.deny` -Globale Tool-Erlauben-/Ablehnen-Richtlinie (Ablehnen gewinnt). Groß-/Kleinschreibung wird ignoriert, `*`-Wildcards werden unterstützt. Gilt auch, wenn die Docker-Sandbox deaktiviert ist. +Globale Allow-/Deny-Richtlinie für Tools (deny gewinnt). Nicht case-sensitiv, unterstützt `*`-Wildcards. Gilt auch dann, wenn die Docker-Sandbox deaktiviert ist. ```json5 { @@ -2070,9 +2070,9 @@ Steuert erhöhten Exec-Zugriff außerhalb der Sandbox: } ``` -- Die Pro-Agent-Überschreibung (`agents.list[].tools.elevated`) kann nur weiter einschränken. -- `/elevated on|off|ask|full` speichert den Zustand pro Sitzung; Inline-Anweisungen 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). +- 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. +- Erhöhtes `exec` umgeht das Sandboxing und verwendet den konfigurierten Escape-Pfad (`gateway` standardmäßig oder `node`, wenn das Exec-Ziel `node` ist). ### `tools.exec` @@ -2096,7 +2096,7 @@ Steuert erhöhten 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. +Sicherheitsprüfungen gegen 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 @@ -2118,10 +2118,10 @@ Einstellungen können global in `tools.loopDetection` definiert und pro Agent un } ``` -- `historySize`: maximale Tool-Call-Historie, die für Schleifenanalyse beibehalten wird. -- `warningThreshold`: Schwellenwert für Warnungen bei wiederholten Mustern ohne Fortschritt. +- `historySize`: maximale Historie von Tool-Aufrufen, die für die Schleifenanalyse aufbewahrt 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. +- `globalCircuitBreakerThreshold`: harte Stopp-Schwelle 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. @@ -2167,7 +2167,7 @@ Konfiguriert das Verständnis eingehender Medien (Bild/Audio/Video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // Opt-in: fertige asynchrone Musik-/Videos direkt in den Kanal senden + directSend: false, // Opt-in: fertige asynchrone Musik/Videos direkt in den Channel senden }, audio: { enabled: true, @@ -2193,30 +2193,30 @@ Konfiguriert das Verständnis eingehender Medien (Bild/Audio/Video): -**Provider-Eintrag** (`type: "provider"` oder weggelassen): +**Providereintrag** (`type: "provider"` oder weggelassen): -- `provider`: API-Provider-ID (`openai`, `anthropic`, `google`/`gemini`, `groq` usw.) +- `provider`: ID des API-Providers (`openai`, `anthropic`, `google`/`gemini`, `groq` usw.) - `model`: Überschreibung der Modell-ID -- `profile` / `preferredProfile`: Auswahl des Profils in `auth-profiles.json` +- `profile` / `preferredProfile`: Profilauswahl für `auth-profiles.json` **CLI-Eintrag** (`type: "cli"`): -- `command`: auszuführende ausführbare Datei -- `args`: vorlagenbasierte Argumente (unterstützt `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` usw.) +- `command`: auszuführende Binärdatei +- `args`: templatisierte Argumente (unterstützt `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` usw.) **Gemeinsame Felder:** -- `capabilities`: optionale Liste (`image`, `audio`, `video`). Standards: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `capabilities`: optionale Liste (`image`, `audio`, `video`). Standard: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: Überschreibungen pro Eintrag. - Bei Fehlern wird auf den nächsten Eintrag zurückgefallen. -Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.json` → Env-Variablen → `models.providers.*.apiKey`. +Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.json` → Umgebungsvariablen → `models.providers.*.apiKey`. **Felder für asynchronen Abschluss:** - `asyncCompletion.directSend`: wenn `true`, versuchen abgeschlossene asynchrone `music_generate`- - und `video_generate`-Aufgaben zuerst direkte Kanalzustellung. Standard: `false` - (altes Pfadmodell mit Anfragender-Sitzung-Wake/Modell-Zustellung). + und `video_generate`-Tasks zuerst eine direkte Zustellung an den Channel. Standard: `false` + (alter Anforderer-Sitzungs-Wakeup-/Modellzustellungspfad). @@ -2235,7 +2235,7 @@ Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.jso ### `tools.sessions` -Steuert, welche Sitzungen von den Sitzungstools (`sessions_list`, `sessions_history`, `sessions_send`) angesprochen werden können. +Steuert, auf welche Sitzungen die Sitzungstools zielen können (`sessions_list`, `sessions_history`, `sessions_send`). Standard: `tree` (aktuelle Sitzung + von ihr gestartete Sitzungen, etwa Subagenten). @@ -2254,13 +2254,13 @@ Hinweise: - `self`: nur der aktuelle Sitzungsschlüssel. - `tree`: aktuelle Sitzung + von der aktuellen Sitzung gestartete Sitzungen (Subagenten). -- `agent`: jede Sitzung, die zur aktuellen Agent-ID gehört (kann andere Benutzer einschließen, wenn Sie Sender-pro-Sitzung unter derselben Agent-ID ausführen). -- `all`: jede Sitzung. Agentübergreifendes Targeting erfordert weiterhin `tools.agentToAgent`. -- Sandbox-Klammerung: Wenn die aktuelle Sitzung sandboxiert ist und `agents.defaults.sandbox.sessionToolsVisibility="spawned"` gilt, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"` ist. +- `agent`: jede Sitzung, die zur aktuellen Agent-ID gehört (kann andere Benutzer einschließen, wenn Sie Sitzungen pro Absender unter derselben Agent-ID ausführen). +- `all`: jede Sitzung. Sitzungsübergreifendes Targeting zwischen Agenten erfordert weiterhin `tools.agentToAgent`. +- Sandbox-Klammer: wenn die aktuelle Sitzung sandboxed ist und `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Steuert die Unterstützung von Inline-Anhängen für `sessions_spawn`. +Steuert Inline-Anhangsunterstützung für `sessions_spawn`. ```json5 { @@ -2283,13 +2283,13 @@ Hinweise: - Anhänge werden nur für `runtime: "subagent"` unterstützt. 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 Transkriptpersistenz redigiert. -- Base64-Eingaben werden mit strikten Alphabet-/Padding-Prüfungen und einer Vorab-Größenprüfung vor dem Dekodieren validiert. +- Base64-Eingaben werden mit strenger Prüfung von Alphabet/Padding und einem Größenschutz vor dem Decodieren validiert. - Dateiberechtigungen sind `0700` für Verzeichnisse und `0600` für Dateien. -- Die Bereinigung folgt der `cleanup`-Richtlinie: `delete` entfernt Anhänge immer; `keep` behält sie nur, wenn `retainOnSessionKeep: true`. +- Die Bereinigung folgt der Richtlinie `cleanup`: `delete` entfernt Anhänge immer; `keep` behält sie nur, wenn `retainOnSessionKeep: true`. ### `tools.experimental` -Experimentelle integrierte Tool-Flags. Standardmäßig aus, außer wenn eine laufzeitspezifische Auto-Aktivierungsregel greift. +Experimentelle integrierte Tool-Flags. Standardmäßig aus, sofern keine laufzeitspezifische Auto-Aktivierungsregel greift. ```json5 { @@ -2303,9 +2303,9 @@ Experimentelle integrierte Tool-Flags. Standardmäßig aus, außer wenn eine lau Hinweise: -- `planTool`: aktiviert das strukturierte `update_plan`-Tool für das Tracking nicht-trivialer mehrstufiger Arbeit. -- Standard: `false` für Nicht-OpenAI-Provider. OpenAI- und OpenAI-Codex-Läufe aktivieren es automatisch, wenn nicht gesetzt; setzen Sie `false`, um diese automatische Aktivierung zu deaktivieren. -- Wenn aktiviert, fügt der Systemprompt auch Nutzungshinweise hinzu, sodass das Modell es nur für substanzielle Arbeit verwendet und höchstens einen Schritt `in_progress` hält. +- `planTool`: aktiviert das strukturierte Tool `update_plan` zur Nachverfolgung nichttrivialer mehrstufiger Arbeit. +- Standard: `false` für Nicht-OpenAI-Provider. OpenAI- und OpenAI-Codex-Läufe aktivieren es automatisch, wenn nicht gesetzt; setzen Sie `false`, um diese Auto-Aktivierung zu deaktivieren. +- Wenn aktiviert, fügt der System-Prompt auch Nutzungshinweise hinzu, damit das Modell es nur für substanzielle Arbeit verwendet und höchstens einen Schritt `in_progress` hält. ### `agents.defaults.subagents` @@ -2325,14 +2325,14 @@ Hinweise: } ``` -- `model`: Standardmodell für gestartete Sub-Agenten. Wenn weggelassen, erben Sub-Agenten das Modell des Aufrufers. -- `allowAgents`: Standard-Erlaubnisliste für Ziel-Agent-IDs für `sessions_spawn`, wenn der anfragende Agent keine eigene `subagents.allowAgents` setzt (`["*"]` = beliebig; Standard: nur derselbe Agent). +- `model`: Standardmodell für gestartete Subagenten. Wenn nicht gesetzt, erben Subagenten das Modell des Aufrufers. +- `allowAgents`: Standard-Allowlist von Ziel-Agent-IDs für `sessions_spawn`, wenn der anfragende Agent nicht seine 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`. --- -## Benutzerdefinierte Provider und Basis-URLs +## Benutzerdefinierte Provider und Base-URLs OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte Provider über `models.providers` in der Konfiguration oder `~/.openclaw/agents//agent/models.json` hinzu. @@ -2364,48 +2364,48 @@ OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte ``` - Verwenden Sie `authHeader: true` + `headers` für benutzerdefinierte Authentifizierungsanforderungen. -- Überschreiben Sie das Root der Agentenkonfiguration mit `OPENCLAW_AGENT_DIR` (oder `PI_CODING_AGENT_DIR`, ein alter Alias für Umgebungsvariablen). +- Überschreiben Sie das Root für die Agentenkonfiguration mit `OPENCLAW_AGENT_DIR` (oder `PI_CODING_AGENT_DIR`, ein veralteter Alias für Umgebungsvariablen). - Merge-Priorität für passende Provider-IDs: - - Nicht-leere `baseUrl`-Werte in agentbezogenem `models.json` gewinnen. - - Nicht-leere agentbezogene `apiKey`-Werte gewinnen nur dann, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profile-Kontext nicht durch SecretRef verwaltet wird. - - SecretRef-verwaltete Provider-`apiKey`-Werte werden aus Quellmarkern aktualisiert (`ENV_VAR_NAME` für Env-Refs, `secretref-managed` für Datei-/Exec-Refs), statt aufgelöste Secrets zu persistieren. - - SecretRef-verwaltete Provider-Header-Werte werden aus Quellmarkern aktualisiert (`secretref-env:ENV_VAR_NAME` für Env-Refs, `secretref-managed` für Datei-/Exec-Refs). - - Leere oder fehlende agentbezogene `apiKey`/`baseUrl` fallen auf `models.providers` in der Konfiguration zurück. - - Passende Modell-`contextWindow`/`maxTokens` verwenden den höheren Wert zwischen expliziter Konfiguration und impliziten Katalogwerten. - - Passende Modell-`contextTokens` behalten eine explizite Laufzeitobergrenze bei, wenn vorhanden; verwenden Sie es, um den effektiven Kontext zu begrenzen, ohne die nativen Modellmetadaten zu ändern. + - Nichtleere `baseUrl`-Werte in `models.json` des Agenten haben Vorrang. + - Nichtleere `apiKey`-Werte des Agenten haben nur dann Vorrang, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profile-Kontext nicht über SecretRef verwaltet wird. + - SecretRef-verwaltete Provider-`apiKey`-Werte werden aus Quellmarkern aktualisiert (`ENV_VAR_NAME` für env-Refs, `secretref-managed` für file-/exec-Refs), statt aufgelöste Secrets zu persistieren. + - SecretRef-verwaltete Provider-Headerwerte werden aus Quellmarkern aktualisiert (`secretref-env:ENV_VAR_NAME` für env-Refs, `secretref-managed` für file-/exec-Refs). + - Leere oder fehlende `apiKey`-/`baseUrl`-Werte des Agenten fallen auf `models.providers` in der Konfiguration zurück. + - Passende `contextWindow`/`maxTokens` eines Modells verwenden den höheren Wert aus expliziter Konfiguration und impliziten Katalogwerten. + - Passende `contextTokens` eines Modells behalten eine explizite Laufzeitgrenze bei, wenn vorhanden; verwenden Sie sie, um das effektive Kontextbudget zu begrenzen, ohne native Modellmetadaten zu ändern. - Verwenden Sie `models.mode: "replace"`, wenn die Konfiguration `models.json` vollständig neu schreiben soll. - - Marker-Persistenz ist quellautoritativer Natur: Marker werden aus dem aktiven Quellkonfigurations-Snapshot (vor der Auflösung) geschrieben, nicht aus aufgelösten Laufzeit-Secret-Werten. + - 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 Provider-Feldern - `models.mode`: Verhalten des Provider-Katalogs (`merge` oder `replace`). -- `models.providers`: benutzerdefinierte Provider-Map, indiziert nach Provider-ID. +- `models.providers`: benutzerdefinierte Provider-Map, verschlüsselt nach Provider-ID. - `models.providers.*.api`: Request-Adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` usw.). -- `models.providers.*.apiKey`: Provider-Anmeldedaten (bevorzugt mit SecretRef/Env-Substitution). +- `models.providers.*.apiKey`: Provider-Anmeldedaten (SecretRef/env-Ersetzung bevorzugen). - `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`: Transport der Anmeldedaten im `Authorization`-Header erzwingen, wenn erforderlich. -- `models.providers.*.baseUrl`: Basis-URL der Upstream-API. +- `models.providers.*.injectNumCtxForOpenAICompat`: fügt für Ollama + `openai-completions` `options.num_ctx` in Requests ein (Standard: `true`). +- `models.providers.*.authHeader`: erzwingt bei Bedarf die Übertragung von Anmeldedaten im `Authorization`-Header. +- `models.providers.*.baseUrl`: Base-URL der Upstream-API. - `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-Standards zusammengeführt). Werte akzeptieren SecretRef. - - `request.auth`: Überschreibung der Authentifizierungsstrategie. Modi: `"provider-default"` (eingebaute Auth des Providers verwenden), `"authorization-bearer"` (mit `token`), `"header"` (mit `headerName`, `value`, optional `prefix`). - - `request.proxy`: Überschreibung des HTTP-Proxys. Modi: `"env-proxy"` (verwendet Env-Variablen `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren optional ein `tls`-Unterobjekt. - - `request.tls`: TLS-Überschreibung für Direktverbindungen. Felder: `ca`, `cert`, `key`, `passphrase` (alle akzeptieren SecretRef), `serverName`, `insecureSkipVerify`. -- `models.providers.*.models`: explizite Provider-Modellkatalogeinträge. -- `models.providers.*.models.*.contextWindow`: native Modell-Metadaten für das Kontextfenster. -- `models.providers.*.models.*.contextTokens`: optionale Laufzeit-Kontextobergrenze. Verwenden Sie dies, wenn Sie ein kleineres effektives Kontextbudget als das native `contextWindow` des Modells wünschen. -- `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 Standard-OpenAI-Verhalten. -- `models.providers.*.models.*.compat.requiresStringContent`: optionaler Kompatibilitätshinweis für rein stringbasierte OpenAI-kompatible Chat-Endpunkte. Wenn `true`, glättet OpenClaw reine Text-Arrays in `messages[].content` zu Klartext-Strings, bevor der Request gesendet wird. +- `models.providers.*.request`: Transportüberschreibungen für HTTP-Requests von Modell-Providern. + - `request.headers`: zusätzliche Header (gemerged mit den Standardwerten des Providers). 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"` (Umgebungsvariablen `HTTP_PROXY`/`HTTPS_PROXY` verwenden), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren optional ein TLS-Subobjekt. + - `request.tls`: TLS-Überschreibung für direkte Verbindungen. Felder: `ca`, `cert`, `key`, `passphrase` (alle akzeptieren SecretRef), `serverName`, `insecureSkipVerify`. +- `models.providers.*.models`: explizite Katalogeinträge für Providermodelle. +- `models.providers.*.models.*.contextWindow`: Metadaten zum nativen Kontextfenster des Modells. +- `models.providers.*.models.*.contextTokens`: optionale Laufzeitgrenze für den Kontext. Verwenden Sie dies, wenn Sie ein kleineres effektives Kontextbudget als das native `contextWindow` des Modells wünschen. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: optionaler Kompatibilitätshinweis. Für `api: "openai-completions"` mit einer nichtleeren, nichtnativen `baseUrl` (Host nicht `api.openai.com`) erzwingt OpenClaw dies zur Laufzeit auf `false`. Leere/weggelassene `baseUrl` behält das Standardverhalten von OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: optionaler Kompatibilitätshinweis für OpenAI-kompatible Chat-Endpunkte, die nur Zeichenfolgen akzeptieren. Wenn `true`, reduziert OpenClaw reine Text-Arrays in `messages[].content` vor dem Senden auf einfache Zeichenfolgen. - `plugins.entries.amazon-bedrock.config.discovery`: Root der Bedrock-Auto-Discovery-Einstellungen. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: implizite Discovery ein-/ausschalten. - `plugins.entries.amazon-bedrock.config.discovery.region`: AWS-Region für Discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optionaler Provider-ID-Filter für gezielte Discovery. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optionaler Filter nach Provider-ID für gezielte Discovery. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: Polling-Intervall für Discovery-Aktualisierung. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: Fallback-Kontextfenster für entdeckte Modelle. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: Fallback für maximale Ausgabetokens bei entdeckten Modellen. -### Provider-Beispiele +### Beispiele für Provider @@ -2441,7 +2441,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 Z.AI direkt. +Verwenden Sie `cerebras/zai-glm-4.7` für Cerebras; `zai/glm-4.7` für direktes Z.AI. @@ -2458,7 +2458,7 @@ Verwenden Sie `cerebras/zai-glm-4.7` für Cerebras; `zai/glm-4.7` für Z.AI dire } ``` -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 vom Typ `opencode/...` für den Zen-Katalog oder `opencode-go/...` für den Go-Katalog. Kurzform: `openclaw onboard --auth-choice opencode-zen` oder `openclaw onboard --auth-choice opencode-go`. @@ -2475,11 +2475,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 Alias akzeptiert. Kurzform: `openclaw onboard --auth-choice zai-api-key`. +Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Aliase akzeptiert. 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 Provider mit Überschreibung der Basis-URL. +- Für den allgemeinen Endpunkt definieren Sie einen benutzerdefinierten Provider mit überschreibender Base-URL. @@ -2520,9 +2520,7 @@ Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Alias akzeptiert. Kur 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 -`openai-completions`-Transport, und OpenClaw koppelt dies nun an Endpunkt- -Fähigkeiten statt nur an die eingebaute Provider-ID. +Native Moonshot-Endpunkte werben Streaming-Nutzungskompatibilität auf dem gemeinsamen Transport `openai-completions` an, und OpenClaw richtet sich dabei nach Endpunktfunktionen statt nur nach der integrierten Provider-ID. @@ -2579,7 +2577,7 @@ Anthropic-kompatibel, integrierter Provider. Kurzform: `openclaw onboard --auth- } ``` -Die Basis-URL sollte `/v1` auslassen (der Anthropic-Client fügt es an). Kurzform: `openclaw onboard --auth-choice synthetic-api-key`. +Die Base-URL sollte `/v1` weglassen (der Anthropic-Client hängt sie an). Kurzform: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2622,17 +2620,14 @@ Die Basis-URL sollte `/v1` auslassen (der Anthropic-Client fügt es an). Kurzfor Setzen Sie `MINIMAX_API_KEY`. Kurzformen: `openclaw onboard --auth-choice minimax-global-api` oder `openclaw onboard --auth-choice minimax-cn-api`. -Der Modellkatalog verwendet jetzt standardmäßig nur noch M2.7. -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` zu `MiniMax-M2.7-highspeed` um. -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. +Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie auf leistungsfähiger Hardware ein großes lokales Modell über die Responses API von LM Studio aus; behalten Sie gehostete Modelle für den Fallback zusammengeführt. @@ -2653,7 +2648,7 @@ Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein g }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // oder Klartext-String + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // oder Klartextzeichenfolge env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2663,14 +2658,12 @@ Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein g } ``` -- `allowBundled`: optionale Erlaubnisliste nur für gebündelte Skills (verwaltete/Workspace-Skills bleiben unberührt). +- `allowBundled`: optionale Allowlist nur für gebündelte Skills (verwaltete/Workspace-Skills sind davon nicht betroffen). - `load.extraDirs`: zusätzliche gemeinsame Skill-Roots (niedrigste Priorität). -- `install.preferBrew`: wenn true, Homebrew-Installer bevorzugen, sofern `brew` - verfügbar ist, bevor auf andere Installer-Typen zurückgefallen wird. -- `install.nodeManager`: bevorzugter Node-Installer für `metadata.openclaw.install`- - Spezifikationen (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` deaktiviert einen Skill, auch wenn er gebündelt/installiert ist. -- `entries..apiKey`: Komfortfeld für Skills, die eine primäre Env-Variable deklarieren (Klartext-String oder SecretRef-Objekt). +- `install.preferBrew`: wenn true, werden Homebrew-Installer bevorzugt, sofern `brew` verfügbar ist, bevor auf andere Installer-Arten zurückgefallen wird. +- `install.nodeManager`: bevorzugter Node-Installer für `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 (Klartextzeichenfolge oder SecretRef-Objekt). --- @@ -2699,40 +2692,40 @@ Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein g ``` - Geladen aus `~/.openclaw/extensions`, `/.openclaw/extensions` sowie `plugins.load.paths`. -- Discovery akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles mit Standard-Layout. +- Discovery akzeptiert native OpenClaw-Plugins plus kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles mit Standardlayout. - **Konfigurationsänderungen erfordern einen Gateway-Neustart.** -- `allow`: optionale Erlaubnisliste (nur gelistete Plugins werden geladen). `deny` gewinnt. -- `plugins.entries..apiKey`: Komfortfeld für Plugin-API-Key auf Plugin-Ebene (wenn vom Plugin unterstützt). -- `plugins.entries..env`: pluginbezogene Env-Variablenzuordnung. -- `plugins.entries..hooks.allowPromptInjection`: wenn `false`, blockiert der Kern `before_prompt_build` und ignoriert prompt-mutierende Felder aus altem `before_agent_start`, während altes `modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte hook-Verzeichnisse aus Bundles. -- `plugins.entries..subagent.allowModelOverride`: diesem Plugin explizit vertrauen, pro Lauf `provider`- und `model`-Überschreibungen für Hintergrund-Subagent-Läufe anzufordern. -- `plugins.entries..subagent.allowedModels`: optionale Erlaubnisliste kanonischer `provider/model`-Ziele für vertrauenswürdige Subagent-Überschreibungen. Verwenden Sie `"*"` nur, wenn Sie absichtlich jedes Modell zulassen möchten. -- `plugins.entries..config`: plugindefiniertes Konfigurationsobjekt (validiert gegen natives OpenClaw-Plugin-Schema, sofern verfügbar). -- `plugins.entries.firecrawl.config.webFetch`: Firecrawl-Einstellungen für den Web-Fetch-Provider. - - `apiKey`: Firecrawl-API-Key (akzeptiert SecretRef). Fällt auf `plugins.entries.firecrawl.config.webSearch.apiKey`, altes `tools.web.fetch.firecrawl.apiKey` oder Env-Variable `FIRECRAWL_API_KEY` zurück. - - `baseUrl`: Basis-URL der Firecrawl-API (Standard: `https://api.firecrawl.dev`). - - `onlyMainContent`: nur den Hauptinhalt von Seiten extrahieren (Standard: `true`). +- `allow`: optionale Allowlist (nur aufgelistete Plugins werden geladen). `deny` gewinnt. +- `plugins.entries..apiKey`: Plugin-spezifisches Komfortfeld für API-Keys (wenn vom Plugin unterstützt). +- `plugins.entries..env`: pluginspezifische Map von Umgebungsvariablen. +- `plugins.entries..hooks.allowPromptInjection`: wenn `false`, blockiert der Kern `before_prompt_build` und ignoriert prompt-mutierende Felder aus dem alten `before_agent_start`, während die alten Felder `modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte Hook-Verzeichnisse aus Bundles. +- `plugins.entries..subagent.allowModelOverride`: diesem Plugin explizit vertrauen, damit es bei Hintergrundläufen von Subagenten Überschreibungen pro Lauf für `provider` und `model` anfordern darf. +- `plugins.entries..subagent.allowedModels`: optionale Allowlist kanonischer Ziele vom Typ `provider/model` für vertrauenswürdige Überschreibungen von Subagenten. Verwenden Sie `"*"` nur, wenn Sie absichtlich jedes Modell zulassen möchten. +- `plugins.entries..config`: Plugin-definiertes Konfigurationsobjekt (validiert gegen das native OpenClaw-Plugin-Schema, sofern verfügbar). +- `plugins.entries.firecrawl.config.webFetch`: Einstellungen für Firecrawl als Web-Fetch-Provider. + - `apiKey`: Firecrawl-API-Key (akzeptiert SecretRef). Fällt auf `plugins.entries.firecrawl.config.webSearch.apiKey`, das alte `tools.web.fetch.firecrawl.apiKey` oder die Umgebungsvariable `FIRECRAWL_API_KEY` zurück. + - `baseUrl`: Firecrawl-API-Base-URL (Standard: `https://api.firecrawl.dev`). + - `onlyMainContent`: nur den Hauptinhalt aus Seiten extrahieren (Standard: `true`). - `maxAgeMs`: maximales Cache-Alter in Millisekunden (Standard: `172800000` / 2 Tage). - - `timeoutSeconds`: Timeout für Scrape-Anfragen in Sekunden (Standard: `60`). + - `timeoutSeconds`: Timeout des Scrape-Requests in Sekunden (Standard: `60`). - `plugins.entries.xai.config.xSearch`: Einstellungen für xAI X Search (Grok-Websuche). - `enabled`: X Search-Provider aktivieren. - - `model`: Grok-Modell, das für die Suche verwendet wird (z. B. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: Einstellungen für Memory-Dreaming (experimentell). Siehe [Dreaming](/de/concepts/dreaming) für Phasen und Schwellenwerte. - - `enabled`: globaler Dreaming-Schalter (Standard `false`). - - `frequency`: Cron-Takt für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`). + - `model`: zu verwendendes Grok-Modell für die Suche (z. B. `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: Einstellungen für Memory Dreaming (experimentell). Phasen und Schwellenwerte finden Sie unter [Dreaming](/de/concepts/dreaming). + - `enabled`: globaler Schalter für Dreaming (Standard `false`). + - `frequency`: Cron-Taktung für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`). - Phasenrichtlinie und Schwellenwerte sind Implementierungsdetails (keine benutzerseitigen Konfigurationsschlüssel). -- Die vollständige Speicherkonfiguration befindet sich in [Speicherkonfigurationsreferenz](/de/reference/memory-config): +- Die vollständige Speicherkonfiguration befindet sich in [Referenz zur Speicherkonfiguration](/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`: wählen Sie die aktive Memory-Plugin-ID oder `"none"`, um Memory-Plugins zu deaktivieren. -- `plugins.slots.contextEngine`: wählen Sie die aktive Context-Engine-Plugin-ID; Standard ist `"legacy"`, sofern Sie keine andere Engine installieren und auswählen. +- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standards aus `settings.json` beisteuern; OpenClaw wendet diese als bereinigte Agenteneinstellungen an, nicht als rohe Patches für die OpenClaw-Konfiguration. +- `plugins.slots.memory`: aktive Memory-Plugin-ID wählen oder `"none"`, um Memory-Plugins zu deaktivieren. +- `plugins.slots.contextEngine`: aktive Plugin-ID für die Context Engine wä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 statt manueller Bearbeitungen. + - Umfasst `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. + - Behandeln Sie `plugins.installs.*` als verwalteten Zustand; verwenden Sie vorzugsweise CLI-Befehle statt manueller Bearbeitung. Siehe [Plugins](/de/tools/plugin). @@ -2747,7 +2740,7 @@ Siehe [Plugins](/de/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // Standard im Trusted-Network-Modell + dangerouslyAllowPrivateNetwork: true, // Standardmodell für vertrauenswürdige Netzwerke // allowPrivateNetwork: true, // alter Alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2775,37 +2768,17 @@ Siehe [Plugins](/de/tools/plugin). ``` - `evaluateEnabled: false` deaktiviert `act:evaluate` und `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist standardmäßig `true`, wenn nicht gesetzt (Trusted-Network-Modell). -- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` für strikte öffentliche Browser-Navigation. -- Im strikten Modus unterliegen Remote-CDP-Profil-Endpunkte (`profiles.*.cdpUrl`) während Erreichbarkeits-/Discovery-Prüfungen derselben Blockierung privater Netzwerke. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist standardmäßig `true`, wenn nicht gesetzt (Modell für vertrauenswürdige Netzwerke). +- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` für strikte Browser-Navigation nur zu öffentlichen Zielen. +- Im strikten Modus unterliegen Endpunkte von Remote-CDP-Profilen (`profiles.*.cdpUrl`) denselben Sperren für private Netzwerke bei Erreichbarkeits-/Discovery-Prüfungen. - `ssrfPolicy.allowPrivateNetwork` wird weiterhin als alter Alias unterstützt. - Im strikten Modus verwenden Sie `ssrfPolicy.hostnameAllowlist` und `ssrfPolicy.allowedHostnames` für explizite Ausnahmen. -- Remote-Profile sind nur zum Anhängen (Start/Stop/Reset deaktiviert). +- Remote-Profile sind nur zum Anhängen gedacht (Start/Stopp/Reset deaktiviert). - `profiles.*.cdpUrl` akzeptiert `http://`, `https://`, `ws://` und `wss://`. - Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` entdecken soll; verwenden Sie WS(S), - wenn Ihr Provider eine direkte DevTools-WebSocket-URL bereitstellt. -- `existing-session`-Profile sind hostgebunden und verwenden Chrome MCP statt CDP. -- `existing-session`-Profile können `userDataDir` setzen, um ein bestimmtes - Chromium-basiertes Browser-Profil wie Brave oder Edge anzusprechen. -- `existing-session`-Profile behalten die aktuellen Grenzen der Chrome-MCP-Route bei: - snapshot-/ref-basierte Aktionen statt CSS-Selektor-Zielsteuerung, Hooks für Einzeldatei-Uploads, - keine Dialog-Timeout-Überschreibungen, kein `wait --load networkidle` und kein - `responsebody`, PDF-Export, Download-Interception oder 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, falls Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Steuerdienst: nur loopback (Port abgeleitet aus `gateway.port`, Standard `18791`). -- `extraArgs` fügt dem lokalen Chromium-Start zusätzliche Flags hinzu (zum Beispiel - `--disable-gpu`, Fenstergrößen oder Debug-Flags). - ---- - -## UI - -```json5 -{ - ui: { - seamColor: "#FF4500", - assistant: { - name: "OpenClaw", - avatar: "CB", // Emoji, kurzer \ No newline at end of file + Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` entdecken soll; verwenden Sie WS(S), wenn Ihr Provider eine direkte DevTools-WebSocket-URL liefert. +- Profile vom Typ `existing-session` sind nur für den Host und verwenden Chrome MCP statt CDP. +- Profile vom Typ `existing-session` können `userDataDir` setzen, um auf ein bestimmtes Chromium-basiertes Browserprofil wie Brave oder Edge zu zielen. +- Profile vom Typ `existing-session` behalten die aktuellen Einschränkungen der Chrome-MCP-Route: + snapshot-/ref-basierte Aktionen statt CSS-Selektor-Targeting, Hooks für den Upload einer einzelnen Datei, keine Überschreibungen von Dialog-Timeouts, kein `wait --load networkidle` sowie kein `responsebody`, PDF-Export, Download-Interception oder 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 → \ No newline at end of file diff --git a/docs/de/gateway/doctor.md b/docs/de/gateway/doctor.md index 7e28a2f8f..b749d6aea 100644 --- a/docs/de/gateway/doctor.md +++ b/docs/de/gateway/doctor.md @@ -1,14 +1,14 @@ --- read_when: - - Hinzufügen oder Ändern von Doctor-Migrationen - - Einführung von inkompatiblen Konfigurationsänderungen -summary: 'Doctor-Befehl: Zustandsprüfungen, Konfigurationsmigrationen und Reparaturschritte' + - Sie fügen Doctor-Migrationen hinzu oder ändern sie + - Sie führen nicht abwärtskompatible Konfigurationsänderungen ein +summary: 'Doctor-Befehl: Integritätsprüfungen, Konfigurationsmigrationen und Reparaturschritte' title: Doctor x-i18n: - generated_at: "2026-04-08T02:15:50Z" + generated_at: "2026-04-09T01:29:19Z" model: gpt-5.4 provider: openai - source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6 + source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce source_path: gateway/doctor.md workflow: 15 --- @@ -16,7 +16,7 @@ x-i18n: # Doctor `openclaw doctor` ist das Reparatur- und Migrationstool für OpenClaw. Es behebt veraltete -Konfigurationen/Zustände, prüft den Zustand und bietet umsetzbare Reparaturschritte. +Konfigurationen/Zustände, prüft die Integrität und bietet umsetzbare Reparaturschritte. ## Schnellstart @@ -30,13 +30,13 @@ openclaw doctor openclaw doctor --yes ``` -Akzeptiert Standardwerte ohne Rückfrage (einschließlich Neustart-/Dienst-/Sandbox-Reparaturschritten, wenn zutreffend). +Akzeptiert Standardwerte ohne Rückfrage (einschließlich Neustart-/Service-/Sandbox-Reparaturschritten, falls zutreffend). ```bash openclaw doctor --repair ``` -Wendet empfohlene Reparaturen ohne Rückfrage an (Reparaturen + Neustarts, wenn sicher). +Wendet empfohlene Reparaturen ohne Rückfrage an (Reparaturen + Neustarts, wo sicher). ```bash openclaw doctor --repair --force @@ -48,14 +48,14 @@ Wendet auch aggressive Reparaturen an (überschreibt benutzerdefinierte Supervis openclaw doctor --non-interactive ``` -Wird ohne Rückfragen ausgeführt und wendet nur sichere Migrationen an (Konfigurationsnormalisierung + Zustandsverschiebungen auf dem Datenträger). Überspringt Neustart-/Dienst-/Sandbox-Aktionen, die menschliche Bestätigung erfordern. -Migrationen von Altzuständen werden bei Erkennung automatisch ausgeführt. +Wird ohne Rückfragen ausgeführt und wendet nur sichere Migrationen an (Konfigurationsnormalisierung + Verschieben von On-Disk-Zuständen). Überspringt Neustart-/Service-/Sandbox-Aktionen, die eine menschliche Bestätigung erfordern. +Legacy-Zustandsmigrationen werden bei Erkennung automatisch ausgeführt. ```bash openclaw doctor --deep ``` -Prüft Systemdienste auf zusätzliche Gateway-Installationen (launchd/systemd/schtasks). +Durchsucht Systemdienste nach zusätzlichen Gateway-Installationen (launchd/systemd/schtasks). Wenn Sie Änderungen vor dem Schreiben prüfen möchten, öffnen Sie zuerst die Konfigurationsdatei: @@ -65,72 +65,104 @@ cat ~/.openclaw/openclaw.json ## Was es tut (Zusammenfassung) -- Optionales Pre-Flight-Update für Git-Installationen (nur interaktiv). -- Frischeprüfung des UI-Protokolls (baut die Control UI neu, wenn das Protokollschema neuer ist). -- Zustandsprüfung + Neustartabfrage. -- Skills-Statusübersicht (geeignet/fehlend/blockiert) und Plugin-Status. -- Konfigurationsnormalisierung für Altwerte. -- Migration der Talk-Konfiguration von den alten flachen `talk.*`-Feldern in `talk.provider` + `talk.providers.`. +- Optionale Vorab-Aktualisierung für Git-Installationen (nur interaktiv). +- Prüfung der Aktualität des UI-Protokolls (erstellt die Control UI neu, wenn das Protokollschema neuer ist). +- Integritätsprüfung + Neustartaufforderung. +- Skills-Statuszusammenfassung (geeignet/fehlend/blockiert) und Plugin-Status. +- Konfigurationsnormalisierung für Legacy-Werte. +- Migration der Talk-Konfiguration von alten flachen `talk.*`-Feldern nach `talk.provider` + `talk.providers.`. - Browser-Migrationsprüfungen für alte Chrome-Erweiterungskonfigurationen und Chrome-MCP-Bereitschaft. -- OpenCode-Anbieter-Override-Warnungen (`models.providers.opencode` / `models.providers.opencode-go`). -- Codex-OAuth-Shadowing-Warnungen (`models.providers.openai-codex`). +- Warnungen zu OpenCode-Provider-Overrides (`models.providers.opencode` / `models.providers.opencode-go`). +- Warnungen zu Codex-OAuth-Überschattung (`models.providers.openai-codex`). - Prüfung der OAuth-TLS-Voraussetzungen für OpenAI-Codex-OAuth-Profile. -- Migration von Altzuständen auf dem Datenträger (Sitzungen/Agent-Verzeichnis/WhatsApp-Authentifizierung). -- Migration veralteter Vertragsschlüssel in Plugin-Manifests (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Legacy-Migration von On-Disk-Zuständen (Sitzungen/Agent-Verzeichnis/WhatsApp-Authentifizierung). +- Migration von Legacy-Schlüsseln für Plugin-Manifestverträge (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - Migration des Legacy-Cron-Speichers (`jobId`, `schedule.cron`, Delivery-/Payload-Felder auf oberster Ebene, Payload-`provider`, einfache Fallback-Jobs für Webhooks mit `notify: true`). -- Überprüfung von Sitzungs-Sperrdateien und Bereinigung veralteter Sperren. -- Integritäts- und Berechtigungsprüfungen des Zustands (Sitzungen, Transkripte, Zustandsverzeichnis). -- Berechtigungsprüfungen der Konfigurationsdatei (`chmod 600`) bei lokaler Ausführung. -- Zustand der Modellauthentifizierung: prüft OAuth-Ablauf, kann ablaufende Tokens aktualisieren und meldet Cooldown-/Deaktivierungszustände von Auth-Profilen. +- Prüfung von Sitzungs-Sperrdateien und Bereinigung veralteter Sperren. +- Prüfungen auf Zustandsintegrität und Berechtigungen (Sitzungen, Abschriften, Zustandsverzeichnis). +- Prüfungen der Konfigurationsdateiberechtigungen (`chmod 600`) bei lokaler Ausführung. +- Integrität der Modell-Authentifizierung: prüft OAuth-Ablauf, kann ablaufende Tokens aktualisieren und meldet Abklingzeiten/deaktivierte Zustände von Auth-Profilen. - Erkennung zusätzlicher Workspace-Verzeichnisse (`~/openclaw`). -- Reparatur des Sandbox-Images, wenn Sandboxing aktiviert ist. -- Migration alter Dienste und Erkennung zusätzlicher Gateways. -- Migration alter Matrix-Kanalzustände (im Modus `--fix` / `--repair`). -- Prüfungen der Gateway-Laufzeit (Dienst installiert, aber nicht ausgeführt; zwischengespeichertes launchd-Label). -- Kanalstatuswarnungen (vom laufenden Gateway abgefragt). +- Reparatur von Sandbox-Images, wenn Sandboxing aktiviert ist. +- Legacy-Servicemigration und Erkennung zusätzlicher Gateways. +- Migration von Legacy-Zuständen für den Matrix-Kanal (im Modus `--fix` / `--repair`). +- Laufzeitprüfungen des Gateways (Dienst installiert, aber nicht aktiv; zwischengespeichertes launchd-Label). +- Warnungen zum Kanalstatus (vom laufenden Gateway geprüft). - Audit der Supervisor-Konfiguration (launchd/systemd/schtasks) mit optionaler Reparatur. -- Best-Practice-Prüfungen für die Gateway-Laufzeit (Node vs. Bun, Pfade von Versionsmanagern). -- Diagnose von Gateway-Portkollisionen (Standard `18789`). -- Sicherheitswarnungen für offene DM-Richtlinien. -- Prüfungen der Gateway-Authentifizierung für den lokalen Token-Modus (bietet Tokenerzeugung an, wenn keine Tokenquelle vorhanden ist; überschreibt keine Token-SecretRef-Konfigurationen). -- Prüfung von systemd linger unter Linux. +- Prüfungen bewährter Laufzeitpraktiken für das Gateway (Node vs Bun, Pfade von Versionsmanagern). +- Diagnose von Gateway-Portkonflikten (Standard `18789`). +- Sicherheitswarnungen bei offenen DM-Richtlinien. +- Prüfungen der Gateway-Authentifizierung für den lokalen Token-Modus (bietet Tokenerzeugung an, wenn keine Tokenquelle vorhanden ist; überschreibt keine SecretRef-Token-Konfigurationen). +- Prüfung von `systemd linger` unter Linux. - Prüfung der Dateigröße von Workspace-Bootstrap-Dateien (Warnungen bei Abschneidung/nahe am Limit für Kontextdateien). -- Prüfung des Status der Shell-Vervollständigung sowie automatische Installation/Aktualisierung. -- Berechtigkeitsprüfung für den Embedding-Anbieter der Memory-Suche (lokales Modell, Remote-API-Schlüssel oder QMD-Binärdatei). -- Prüfungen der Quellinstallation (pnpm-Workspace-Abweichung, fehlende UI-Assets, fehlende tsx-Binärdatei). +- Prüfung des Shell-Completion-Status und automatische Installation/Aktualisierung. +- Bereitschaftsprüfung für den Embedding-Provider der Speichersuche (lokales Modell, API-Schlüssel für Remote-Anbieter oder QMD-Binary). +- Prüfungen für Source-Installationen (Nichtübereinstimmung des pnpm-Workspaces, fehlende UI-Assets, fehlende `tsx`-Binärdatei). - Schreibt aktualisierte Konfiguration + Wizard-Metadaten. +## Dreams-UI-Backfill und -Zurücksetzen + +Die Dreams-Ansicht der Control UI enthält die Aktionen **Backfill**, **Reset** und **Clear Grounded** +für den fundierten Träumen-Workflow. Diese Aktionen verwenden Gateway-RPC-Methoden +im Doctor-Stil, sind aber **nicht** Teil der CLI-Reparatur-/Migrationsfunktion von `openclaw doctor`. + +Was sie tun: + +- **Backfill** durchsucht historische `memory/YYYY-MM-DD.md`-Dateien im aktiven + Workspace, führt den fundierten REM-Tagebuchdurchlauf aus und schreibt reversible Backfill-Einträge in `DREAMS.md`. +- **Reset** entfernt nur die markierten Backfill-Tagebucheinträge aus `DREAMS.md`. +- **Clear Grounded** entfernt nur bereitgestellte, ausschließlich fundierte kurzfristige Einträge, die + aus historischem Replay stammen und noch keine Unterstützung durch aktiven Recall oder tägliche + Einträge gesammelt haben. + +Was sie für sich genommen **nicht** tun: + +- sie bearbeiten nicht `MEMORY.md` +- sie führen keine vollständigen Doctor-Migrationen aus +- sie stellen fundierte Kandidaten nicht automatisch in den aktiven kurzfristigen + Promotionsspeicher ein, es sei denn, Sie führen zuerst ausdrücklich den vorbereitenden CLI-Pfad aus + +Wenn Sie möchten, dass fundiertes historisches Replay den normalen Deep-Promotionspfad +beeinflusst, verwenden Sie stattdessen den CLI-Ablauf: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +Dadurch werden fundierte dauerhafte Kandidaten in den kurzfristigen Träumen-Speicher eingestellt, während +`DREAMS.md` als Prüfoberfläche erhalten bleibt. + ## Detailliertes Verhalten und Begründung -### 0) Optionales Update (Git-Installationen) +### 0) Optionale Aktualisierung (Git-Installationen) Wenn dies ein Git-Checkout ist und Doctor interaktiv ausgeführt wird, bietet es an, -vor dem Ausführen von Doctor zu aktualisieren (Fetch/Rebase/Build). +vor der Ausführung von Doctor zu aktualisieren (fetch/rebase/build). ### 1) Konfigurationsnormalisierung -Wenn die Konfiguration veraltete Wertformen enthält (zum Beispiel `messages.ackReaction` -ohne kanalspezifische Überschreibung), normalisiert Doctor sie in das aktuelle +Wenn die Konfiguration alte Werteformen enthält (zum Beispiel `messages.ackReaction` +ohne kanalspezifisches Override), normalisiert Doctor sie auf das aktuelle Schema. Dazu gehören auch alte flache Talk-Felder. Die aktuelle öffentliche Talk-Konfiguration ist `talk.provider` + `talk.providers.`. Doctor schreibt alte Formen von `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` in die Anbieterzuordnung um. +`talk.apiKey` in die Provider-Map um. -### 2) Migrationen veralteter Konfigurationsschlüssel +### 2) Migrationen von Legacy-Konfigurationsschlüsseln -Wenn die Konfiguration veraltete Schlüssel enthält, verweigern andere Befehle die Ausführung -und fordern Sie auf, `openclaw doctor` auszuführen. +Wenn die Konfiguration veraltete Schlüssel enthält, verweigern andere Befehle die Ausführung und fordern +Sie auf, `openclaw doctor` auszuführen. Doctor wird: -- Erklären, welche veralteten Schlüssel gefunden wurden. +- Erklären, welche Legacy-Schlüssel gefunden wurden. - Die angewendete Migration anzeigen. - `~/.openclaw/openclaw.json` mit dem aktualisierten Schema neu schreiben. -Das Gateway führt Doctor-Migrationen auch beim Start automatisch aus, wenn es ein -veraltetes Konfigurationsformat erkennt, sodass veraltete Konfigurationen ohne manuelles Eingreifen repariert werden. +Das Gateway führt Doctor-Migrationen beim Start ebenfalls automatisch aus, wenn es ein +altes Konfigurationsformat erkennt, sodass veraltete Konfigurationen ohne manuelles Eingreifen repariert werden. Migrationen des Cron-Job-Speichers werden von `openclaw doctor --fix` verarbeitet. Aktuelle Migrationen: @@ -140,9 +172,9 @@ Aktuelle Migrationen: - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` -- `routing.bindings` → `bindings` auf oberster Ebene +- `routing.bindings` → oberstes `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` -- veraltete `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` +- altes `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` - `routing.transcribeAudio` → `tools.media.audio.models` - `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.` @@ -155,7 +187,7 @@ Aktuelle Migrationen: - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Bei Kanälen mit benannten `accounts`, aber verbliebenen Kanalwerten auf oberster Ebene für ein Einzelkonto, werden diese kontobezogenen Werte in das für diesen Kanal ausgewählte hochgestufte Konto verschoben (`accounts.default` für die meisten Kanäle; Matrix kann ein vorhandenes passendes benanntes/Standardziel beibehalten) +- Bei Kanälen mit benannten `accounts`, aber verbliebenen einkonto-spezifischen Kanalwerten auf oberster Ebene, diese kontobezogenen Werte in das für diesen Kanal ausgewählte hochgestufte Konto verschieben (`accounts.default` für die meisten Kanäle; Matrix kann ein vorhandenes passendes benanntes/Standardziel beibehalten) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` @@ -166,103 +198,105 @@ Aktuelle Migrationen: Doctor-Warnungen enthalten auch Hinweise zu Standardkonten für Mehrkonten-Kanäle: -- Wenn zwei oder mehr Einträge in `channels..accounts` konfiguriert sind, ohne `channels..defaultAccount` oder `accounts.default`, warnt Doctor, dass Fallback-Routing ein unerwartetes Konto auswählen kann. +- Wenn zwei oder mehr `channels..accounts`-Einträge konfiguriert sind, ohne `channels..defaultAccount` oder `accounts.default`, warnt Doctor davor, dass Fallback-Routing ein unerwartetes Konto auswählen kann. - Wenn `channels..defaultAccount` auf eine unbekannte Konto-ID gesetzt ist, warnt Doctor und listet die konfigurierten Konto-IDs auf. -### 2b) OpenCode-Anbieter-Overrides +### 2b) OpenCode-Provider-Overrides Wenn Sie `models.providers.opencode`, `opencode-zen` oder `opencode-go` -manuell hinzugefügt haben, überschreibt das den integrierten OpenCode-Katalog aus `@mariozechner/pi-ai`. -Dadurch können Modelle auf die falsche API gezwungen oder Kosten auf null gesetzt werden. Doctor warnt, damit Sie die Überschreibung entfernen und Routing + Kosten pro Modell wiederherstellen können. +manuell hinzugefügt haben, überschreibt dies den integrierten OpenCode-Katalog aus `@mariozechner/pi-ai`. +Das kann Modelle auf die falsche API zwingen oder Kosten auf null setzen. Doctor warnt Sie, damit Sie +das Override entfernen und das API-Routing plus die Kosten pro Modell wiederherstellen können. ### 2c) Browser-Migration und Chrome-MCP-Bereitschaft Wenn Ihre Browser-Konfiguration noch auf den entfernten Pfad der Chrome-Erweiterung verweist, normalisiert Doctor -sie auf das aktuelle hostlokale Chrome-MCP-Anbindungsmodell: +sie auf das aktuelle host-lokale Chrome-MCP-Attach-Modell: - `browser.profiles.*.driver: "extension"` wird zu `"existing-session"` - `browser.relayBindHost` wird entfernt -Doctor prüft außerdem den hostlokalen Chrome-MCP-Pfad, wenn Sie `defaultProfile: -"user"` oder ein konfiguriertes Profil `existing-session` verwenden: +Doctor prüft außerdem den host-lokalen Chrome-MCP-Pfad, wenn Sie `defaultProfile: +"user"` oder ein konfiguriertes `existing-session`-Profil verwenden: - prüft, ob Google Chrome auf demselben Host für Standardprofile mit automatischer Verbindung installiert ist - prüft die erkannte Chrome-Version und warnt, wenn sie unter Chrome 144 liegt -- erinnert daran, Remote-Debugging auf der Browser-Inspektionsseite zu aktivieren (zum +- erinnert daran, Remote-Debugging auf der Browser-Inspect-Seite zu aktivieren (zum Beispiel `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` oder `edge://inspect/#remote-debugging`) -Doctor kann die browserseitige Einstellung nicht für Sie aktivieren. Hostlokales Chrome MCP +Doctor kann die Chrome-seitige Einstellung nicht für Sie aktivieren. Host-lokales Chrome MCP erfordert weiterhin: -- einen Chromium-basierten Browser 144+ auf dem Gateway-/Node-Host -- einen lokal laufenden Browser +- einen Chromium-basierten Browser 144+ auf dem Gateway-/Knoten-Host +- den lokal laufenden Browser - aktiviertes Remote-Debugging in diesem Browser -- das Bestätigen der ersten Zustimmungsabfrage zum Anbinden im Browser +- die Bestätigung der ersten Attach-Zustimmungsaufforderung im Browser -Die Bereitschaft bezieht sich hier nur auf lokale Voraussetzungen für das Anbinden. Existing-session behält +Bereitschaft bezieht sich hier nur auf lokale Voraussetzungen für das Attach. Existing-session behält die aktuellen Routenbeschränkungen von Chrome MCP bei; erweiterte Routen wie `responsebody`, PDF- -Export, Download-Interception und Stapelaktionen erfordern weiterhin einen verwalteten -Browser oder ein rohes CDP-Profil. +Export, Download-Interception und Batch-Aktionen erfordern weiterhin einen verwalteten +Browser oder ein Roh-CDP-Profil. Diese Prüfung gilt **nicht** für Docker-, Sandbox-, Remote-Browser- oder andere -Headless-Abläufe. Diese verwenden weiterhin rohes CDP. +headless Abläufe. Diese verwenden weiterhin Roh-CDP. ### 2d) OAuth-TLS-Voraussetzungen Wenn ein OpenAI-Codex-OAuth-Profil konfiguriert ist, prüft Doctor den OpenAI- -Autorisierungsendpunkt, um zu verifizieren, dass der lokale Node/OpenSSL-TLS-Stack die Zertifikatskette -validieren kann. Wenn die Prüfung mit einem Zertifikatsfehler fehlschlägt (zum +Autorisierungsendpunkt, um zu verifizieren, dass der lokale Node-/OpenSSL-TLS-Stack die +Zertifikatskette validieren kann. Wenn die Prüfung mit einem Zertifikatsfehler fehlschlägt (zum Beispiel `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, abgelaufenes Zertifikat oder selbstsigniertes Zertifikat), -gibt Doctor plattformspezifische Hinweise zur Behebung aus. Auf macOS mit einem Homebrew-Node ist die -Behebung normalerweise `brew postinstall ca-certificates`. Mit `--deep` wird die Prüfung auch dann ausgeführt, -wenn das Gateway gesund ist. +gibt Doctor plattformspezifische Lösungshinweise aus. Auf macOS mit einem Homebrew-Node ist die +Lösung meist `brew postinstall ca-certificates`. Mit `--deep` wird die Prüfung auch dann ausgeführt, +wenn das Gateway in Ordnung ist. -### 2c) Codex-OAuth-Anbieter-Overrides +### 2c) Codex-OAuth-Provider-Overrides Wenn Sie zuvor alte OpenAI-Transporteinstellungen unter -`models.providers.openai-codex` hinzugefügt haben, können diese den integrierten Pfad des Codex-OAuth- -Anbieters verdecken, den neuere Releases automatisch verwenden. Doctor warnt, wenn es diese -alten Transporteinstellungen zusammen mit Codex OAuth sieht, damit Sie die veraltete -Transportüberschreibung entfernen oder umschreiben und das integrierte Routing-/Fallback-Verhalten +`models.providers.openai-codex` hinzugefügt haben, können diese den integrierten Codex-OAuth- +Provider-Pfad überschatten, den neuere Releases automatisch verwenden. Doctor warnt, wenn diese +alten Transporteinstellungen zusammen mit Codex OAuth gefunden werden, damit Sie das veraltete +Transport-Override entfernen oder umschreiben und das integrierte Routing-/Fallback-Verhalten wiederherstellen können. Benutzerdefinierte Proxys und reine Header-Overrides werden weiterhin unterstützt und lösen diese Warnung nicht aus. -### 3) Migrationen von Altzuständen (Datenträgerlayout) +### 3) Legacy-Zustandsmigrationen (Datenträgerlayout) Doctor kann ältere Layouts auf dem Datenträger in die aktuelle Struktur migrieren: -- Sitzungsspeicher + Transkripte: +- Sitzungsspeicher + Abschriften: - von `~/.openclaw/sessions/` nach `~/.openclaw/agents//sessions/` - Agent-Verzeichnis: - von `~/.openclaw/agent/` nach `~/.openclaw/agents//agent/` - WhatsApp-Authentifizierungszustand (Baileys): - - aus altem `~/.openclaw/credentials/*.json` (außer `oauth.json`) + - von altem `~/.openclaw/credentials/*.json` (außer `oauth.json`) - nach `~/.openclaw/credentials/whatsapp//...` (Standard-Konto-ID: `default`) Diese Migrationen erfolgen nach bestem Bemühen und sind idempotent; Doctor gibt Warnungen aus, wenn -es alte Ordner als Backups zurücklässt. Das Gateway/die CLI migriert die alten Sitzungen + das Agent-Verzeichnis -beim Start ebenfalls automatisch, sodass Verlauf/Auth/Modelle ohne manuellen Doctor-Lauf im -pfad pro Agent landen. Die WhatsApp-Authentifizierung wird bewusst nur über `openclaw doctor` migriert. Die Normalisierung von Talk-Anbieter/Anbieterzuordnung -vergleicht jetzt nach struktureller Gleichheit, sodass Unterschiede nur in der Schlüsselreihenfolge keine -wiederholten, wirkungslosen Änderungen durch `doctor --fix` mehr auslösen. +Legacy-Ordner als Sicherungen zurückbleiben. Gateway/CLI migrieren außerdem die alten +Sitzungen + das Agent-Verzeichnis beim Start automatisch, sodass Verlauf/Auth/Modelle ohne +manuelle Doctor-Ausführung im pfad pro Agent landen. Die WhatsApp-Authentifizierung wird absichtlich nur +über `openclaw doctor` migriert. Die Normalisierung von Talk-Provider/Provider-Map vergleicht nun +nach struktureller Gleichheit, sodass Unterschiede nur in der Schlüsselreihenfolge keine +wiederholten No-op-Änderungen von `doctor --fix` mehr auslösen. -### 3a) Migrationen alter Plugin-Manifests +### 3a) Legacy-Migrationen von Plugin-Manifesten -Doctor scannt alle installierten Plugin-Manifeste auf veraltete Capability-Schlüssel -auf oberster Ebene (`speechProviders`, `realtimeTranscriptionProviders`, +Doctor durchsucht alle installierten Plugin-Manifeste nach veralteten Capability- +Schlüsseln auf oberster Ebene (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Wenn sie gefunden werden, bietet es an, sie in das Objekt `contracts` -zu verschieben und die Manifestdatei direkt neu zu schreiben. Diese Migration ist idempotent; +zu verschieben und die Manifestdatei direkt zu überschreiben. Diese Migration ist idempotent; wenn der Schlüssel `contracts` bereits dieselben Werte enthält, wird der alte Schlüssel entfernt, ohne die Daten zu duplizieren. -### 3b) Migrationen des Legacy-Cron-Speichers +### 3b) Legacy-Migrationen des Cron-Speichers Doctor prüft auch den Cron-Job-Speicher (`~/.openclaw/cron/jobs.json` standardmäßig, -oder `cron.store`, wenn überschrieben) auf alte Jobformen, die der Scheduler aus Kompatibilitätsgründen -weiterhin akzeptiert. +oder `cron.store`, wenn überschrieben) auf alte Job-Formen, die der Scheduler aus +Kompatibilitätsgründen weiterhin akzeptiert. Aktuelle Bereinigungen für Cron umfassen: @@ -277,141 +311,146 @@ Doctor migriert Jobs mit `notify: true` nur dann automatisch, wenn dies ohne Verhaltensänderung möglich ist. Wenn ein Job den alten Notify-Fallback mit einem vorhandenen Nicht-Webhook-Delivery-Modus kombiniert, warnt Doctor und überlässt diesen Job der manuellen Prüfung. -### 3c) Bereinigung von Sitzungssperren +### 3c) Bereinigung von Sitzungs-Sperren -Doctor scannt jedes Sitzungverzeichnis jedes Agenten nach veralteten Schreib-Sperrdateien — Dateien, die +Doctor durchsucht jedes Sitzungsverzeichnis eines Agenten nach veralteten Schreib-Sperrdateien — Dateien, die zurückbleiben, wenn eine Sitzung abnormal beendet wurde. Für jede gefundene Sperrdatei meldet es: -den Pfad, die PID, ob die PID noch aktiv ist, das Alter der Sperre und ob sie als -veraltet gilt (tote PID oder älter als 30 Minuten). Im Modus `--fix` / `--repair` -entfernt es veraltete Sperrdateien automatisch; andernfalls gibt es einen Hinweis aus und -weist Sie an, den Befehl mit `--fix` erneut auszuführen. +den Pfad, die PID, ob die PID noch aktiv ist, das Alter der Sperre und ob sie +als veraltet gilt (tote PID oder älter als 30 Minuten). Im Modus `--fix` / `--repair` +entfernt es veraltete Sperrdateien automatisch; andernfalls wird ein Hinweis ausgegeben und +angewiesen, den Befehl mit `--fix` erneut auszuführen. -### 4) Integritätsprüfungen des Zustands (Sitzungspersistenz, Routing und Sicherheit) +### 4) Prüfungen der Zustandsintegrität (Sitzungspersistenz, Routing und Sicherheit) -Das Zustandsverzeichnis ist der operative Hirnstamm. Wenn es verschwindet, verlieren Sie -Sitzungen, Anmeldedaten, Protokolle und Konfigurationen (es sei denn, Sie haben anderswo Backups). +Das Zustandsverzeichnis ist das operative Stammhirn. Wenn es verschwindet, verlieren Sie +Sitzungen, Anmeldedaten, Logs und Konfigurationen (außer Sie haben anderswo Sicherungen). Doctor prüft: -- **Zustandsverzeichnis fehlt**: warnt vor katastrophalem Zustandsverlust, fragt nach, ob - das Verzeichnis neu erstellt werden soll, und erinnert Sie daran, dass fehlende Daten nicht wiederhergestellt werden können. +- **Fehlendes Zustandsverzeichnis**: warnt vor katastrophalem Zustandsverlust, fordert zur Neuerstellung + des Verzeichnisses auf und erinnert daran, dass fehlende Daten nicht wiederhergestellt werden können. - **Berechtigungen des Zustandsverzeichnisses**: prüft Schreibbarkeit; bietet an, Berechtigungen zu reparieren - (und gibt einen `chown`-Hinweis aus, wenn ein Eigentümer-/Gruppenmismatch erkannt wird). -- **macOS-Zustandsverzeichnis in Cloud-Sync**: warnt, wenn der Zustand unter iCloud Drive + (und gibt einen `chown`-Hinweis aus, wenn eine Nichtübereinstimmung bei Eigentümer/Gruppe erkannt wird). +- **Cloud-synchronisiertes Zustandsverzeichnis unter macOS**: warnt, wenn sich der Zustand unter iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) oder - `~/Library/CloudStorage/...` aufgelöst wird, weil Sync-basierte Pfade langsamere I/O - und Sperr-/Synchronisationsrennen verursachen können. -- **Linux-Zustandsverzeichnis auf SD oder eMMC**: warnt, wenn der Zustand auf eine `mmcblk*`- - Mount-Quelle aufgelöst wird, weil zufällige I/O auf SD- oder eMMC-Basis langsamer sein und bei - Sitzungs- und Credential-Schreibvorgängen schneller verschleißen kann. -- **Sitzungsverzeichnisse fehlen**: `sessions/` und das Sitzungs-Speicherverzeichnis sind - erforderlich, um den Verlauf zu speichern und `ENOENT`-Abstürze zu vermeiden. -- **Transkript-Mismatch**: warnt, wenn bei aktuellen Sitzungseinträgen - Transkriptdateien fehlen. -- **Hauptsitzung „1-zeiliges JSONL“**: meldet, wenn das Haupttranskript nur eine - Zeile hat (der Verlauf sammelt sich nicht an). -- **Mehrere Zustandsverzeichnisse**: warnt, wenn mehrere `~/.openclaw`-Ordner über - Home-Verzeichnisse hinweg vorhanden sind oder wenn `OPENCLAW_STATE_DIR` auf etwas anderes zeigt (der Verlauf kann + `~/Library/CloudStorage/...` befindet, da synchronisierte Pfade langsamere I/O- + Vorgänge und Sperr-/Synchronisierungsrennen verursachen können. +- **SD- oder eMMC-Zustandsverzeichnis unter Linux**: warnt, wenn sich der Zustand auf einer `mmcblk*`- + Mount-Quelle befindet, da zufällige I/O auf SD- oder eMMC-Medien langsamer sein und + bei Sitzungs- und Credential-Schreibvorgängen schneller verschleißen kann. +- **Fehlende Sitzungsverzeichnisse**: `sessions/` und das Sitzungsverzeichnis sind + erforderlich, um Verlauf zu speichern und `ENOENT`-Abstürze zu vermeiden. +- **Nichtübereinstimmung von Abschriften**: warnt, wenn bei aktuellen Sitzungseinträgen + Abschriftdateien fehlen. +- **Hauptsitzung „1-zeiliges JSONL“**: markiert, wenn die Hauptabschrift nur eine Zeile hat + (Verlauf sammelt sich nicht an). +- **Mehrere Zustandsverzeichnisse**: warnt, wenn mehrere `~/.openclaw`-Ordner in + Home-Verzeichnissen vorhanden sind oder wenn `OPENCLAW_STATE_DIR` auf einen anderen Ort zeigt (der Verlauf kann sich zwischen Installationen aufteilen). -- **Erinnerung an den Remote-Modus**: wenn `gateway.mode=remote`, erinnert Doctor Sie daran, - es auf dem Remote-Host auszuführen (dort liegt der Zustand). +- **Erinnerung an den Remote-Modus**: wenn `gateway.mode=remote`, erinnert Doctor daran, den Befehl + auf dem Remote-Host auszuführen (dort liegt der Zustand). - **Berechtigungen der Konfigurationsdatei**: warnt, wenn `~/.openclaw/openclaw.json` - für Gruppe/Welt lesbar ist, und bietet an, sie auf `600` zu verschärfen. + für Gruppe/Welt lesbar ist, und bietet an, auf `600` zu verschärfen. -### 5) Zustand der Modellauthentifizierung (OAuth-Ablauf) +### 5) Integrität der Modell-Authentifizierung (OAuth-Ablauf) -Doctor prüft OAuth-Profile im Auth-Speicher, warnt, wenn Tokens bald -ablaufen/abgelaufen sind, und kann sie aktualisieren, wenn dies sicher ist. Wenn das Anthropic- +Doctor prüft OAuth-Profile im Auth-Speicher, warnt bei +ablaufenden/abgelaufenen Tokens und kann sie aktualisieren, wenn das sicher ist. Wenn das Anthropic- OAuth-/Token-Profil veraltet ist, schlägt es einen Anthropic-API-Schlüssel oder den Anthropic-Setup-Token-Pfad vor. Aufforderungen zur Aktualisierung erscheinen nur bei interaktiver Ausführung (TTY); `--non-interactive` überspringt Aktualisierungsversuche. -Doctor meldet auch Auth-Profile, die vorübergehend nicht nutzbar sind aufgrund von: +Wenn eine OAuth-Aktualisierung dauerhaft fehlschlägt (zum Beispiel `refresh_token_reused`, +`invalid_grant` oder ein Provider mitteilt, dass Sie sich erneut anmelden müssen), meldet Doctor, +dass eine erneute Authentifizierung erforderlich ist, und gibt den exakten Befehl +`openclaw models auth login --provider ...` aus, der auszuführen ist. -- kurzen Cooldowns (Ratenbegrenzungen/Timeouts/Auth-Fehler) +Doctor meldet auch Auth-Profile, die vorübergehend nicht verwendbar sind aufgrund von: + +- kurzen Abklingzeiten (Ratenbegrenzungen/Timeouts/Auth-Fehler) - längeren Deaktivierungen (Abrechnungs-/Guthabenfehler) -### 6) Modellvalidierung für Hooks +### 6) Validierung des Hooks-Modells -Wenn `hooks.gmail.model` gesetzt ist, validiert Doctor die Modellreferenz gegen den -Katalog und die Allowlist und warnt, wenn sie nicht aufgelöst wird oder nicht erlaubt ist. +Wenn `hooks.gmail.model` gesetzt ist, validiert Doctor den Modellverweis gegen den +Katalog und die Allowlist und warnt, wenn er nicht aufgelöst werden kann oder nicht erlaubt ist. -### 7) Reparatur des Sandbox-Images +### 7) Reparatur von Sandbox-Images -Wenn Sandboxing aktiviert ist, prüft Doctor Docker-Images und bietet an, sie zu bauen oder -auf alte Namen zu wechseln, wenn das aktuelle Image fehlt. +Wenn Sandboxing aktiviert ist, prüft Doctor Docker-Images und bietet an, sie zu erstellen oder +zu alten Namen zu wechseln, falls das aktuelle Image fehlt. ### 7b) Laufzeitabhängigkeiten gebündelter Plugins -Doctor verifiziert, dass Laufzeitabhängigkeiten gebündelter Plugins (zum Beispiel die +Doctor prüft, ob Laufzeitabhängigkeiten gebündelter Plugins (zum Beispiel die Laufzeitpakete des Discord-Plugins) im OpenClaw-Installationsstamm vorhanden sind. Wenn welche fehlen, meldet Doctor die Pakete und installiert sie im Modus `openclaw doctor --fix` / `openclaw doctor --repair`. -### 8) Migrationen von Gateway-Diensten und Hinweise zur Bereinigung +### 8) Migrationen von Gateway-Diensten und Bereinigungshinweise Doctor erkennt alte Gateway-Dienste (launchd/systemd/schtasks) und bietet an, sie zu entfernen und den OpenClaw-Dienst mit dem aktuellen Gateway-Port zu installieren. -Es kann außerdem nach zusätzlichen Gateway-ähnlichen Diensten suchen und Hinweise zur Bereinigung ausgeben. -Profilbenannte OpenClaw-Gateway-Dienste gelten als erstklassig und werden nicht als „zusätzlich“ -markiert. +Es kann auch nach zusätzlichen gatewayähnlichen Diensten suchen und Bereinigungshinweise ausgeben. +Profilbenannte OpenClaw-Gateway-Dienste gelten als erstklassig und werden nicht +als „zusätzlich“ markiert. -### 8b) Matrix-Migration beim Start +### 8b) Startup-Matrix-Migration -Wenn für ein Matrix-Kanalkonto eine ausstehende oder umsetzbare Migration von Altzuständen vorliegt, +Wenn für ein Matrix-Kanalkonto eine ausstehende oder durchführbare Legacy-Zustandsmigration vorliegt, erstellt Doctor (im Modus `--fix` / `--repair`) einen Snapshot vor der Migration und -führt dann die Migrationsschritte nach bestem Bemühen aus: Migration des alten Matrix-Zustands und Vorbereitung des alten +führt dann die Migrationsschritte nach bestem Bemühen aus: Legacy-Migration des Matrix-Zustands und Vorbereitung des alten verschlüsselten Zustands. Beide Schritte sind nicht fatal; Fehler werden protokolliert und -der Start wird fortgesetzt. Im Nur-Lese-Modus (`openclaw doctor` ohne `--fix`) wird diese Prüfung +der Start wird fortgesetzt. Im Nur-Lesen-Modus (`openclaw doctor` ohne `--fix`) wird diese Prüfung vollständig übersprungen. ### 9) Sicherheitswarnungen -Doctor gibt Warnungen aus, wenn ein Anbieter für DMs ohne Allowlist offen ist oder -wenn eine Richtlinie auf gefährliche Weise konfiguriert ist. +Doctor gibt Warnungen aus, wenn ein Provider für DMs ohne Allowlist offen ist oder +wenn eine Richtlinie gefährlich konfiguriert ist. ### 10) systemd linger (Linux) -Wenn er als systemd-Benutzerdienst läuft, stellt Doctor sicher, dass Linger aktiviert ist, damit das +Wenn die Ausführung als systemd-Benutzerdienst erfolgt, stellt Doctor sicher, dass Linger aktiviert ist, damit das Gateway nach dem Abmelden aktiv bleibt. ### 11) Workspace-Status (Skills, Plugins und alte Verzeichnisse) Doctor gibt eine Zusammenfassung des Workspace-Zustands für den Standard-Agenten aus: -- **Skills-Status**: zählt geeignete, an Anforderungen scheiternde und durch Allowlists blockierte Skills. +- **Skills-Status**: Anzahl geeigneter, Anforderungen-fehlen- und Allowlist-blockierter Skills. - **Alte Workspace-Verzeichnisse**: warnt, wenn `~/openclaw` oder andere alte Workspace-Verzeichnisse neben dem aktuellen Workspace vorhanden sind. - **Plugin-Status**: zählt geladene/deaktivierte/fehlerhafte Plugins; listet Plugin-IDs für alle - Fehler auf; meldet Capabilitys gebündelter Plugins. + Fehler auf; meldet Fähigkeiten gebündelter Plugins. - **Plugin-Kompatibilitätswarnungen**: markiert Plugins mit Kompatibilitätsproblemen mit der aktuellen Laufzeit. -- **Plugin-Diagnosen**: zeigt beim Laden entstandene Warnungen oder Fehler an, die von der - Plugin-Registry ausgegeben wurden. +- **Plugin-Diagnosen**: zeigt beim Laden ausgegebene Warnungen oder Fehler aus der + Plugin-Registry an. -### 11b) Größe von Bootstrap-Dateien +### 11b) Größe der Bootstrap-Datei Doctor prüft, ob Bootstrap-Dateien des Workspace (zum Beispiel `AGENTS.md`, -`CLAUDE.md` oder andere injizierte Kontextdateien) nahe am konfigurierten -Zeichenbudget liegen oder es überschreiten. Es meldet pro Datei rohe vs. injizierte Zeichenzahlen, -den Prozentsatz der Abschneidung, die Ursache der Abschneidung (`max/file` oder `max/total`) und die insgesamt injizierten +`CLAUDE.md` oder andere injizierte Kontextdateien) nahe am oder über dem konfigurierten +Zeichenbudget liegen. Es meldet pro Datei rohe vs. injizierte Zeichenzahlen, den Abschneidungs- +Prozentsatz, die Ursache der Abschneidung (`max/file` oder `max/total`) und die gesamte Zahl injizierter Zeichen als Anteil am Gesamtbudget. Wenn Dateien abgeschnitten werden oder nahe am -Limit liegen, gibt Doctor Tipps zur Abstimmung von `agents.defaults.bootstrapMaxChars` +Limit liegen, gibt Doctor Tipps zur Anpassung von `agents.defaults.bootstrapMaxChars` und `agents.defaults.bootstrapTotalMaxChars`. -### 11c) Shell-Vervollständigung +### 11c) Shell-Completion -Doctor prüft, ob die Tab-Vervollständigung für die aktuelle Shell -(zsh, bash, fish oder PowerShell) installiert ist: +Doctor prüft, ob Tab-Completion für die aktuelle Shell installiert ist +(zsh, bash, fish oder PowerShell): -- Wenn das Shell-Profil ein langsames dynamisches Vervollständigungsmuster verwendet +- Wenn das Shell-Profil ein langsames Muster für dynamische Completion verwendet (`source <(openclaw completion ...)`), aktualisiert Doctor es auf die schnellere Variante mit zwischengespeicherter Datei. -- Wenn die Vervollständigung im Profil konfiguriert ist, aber die Cache-Datei fehlt, - erzeugt Doctor den Cache automatisch neu. -- Wenn überhaupt keine Vervollständigung konfiguriert ist, fordert Doctor zur Installation auf - (nur im interaktiven Modus; mit `--non-interactive` übersprungen). +- Wenn Completion im Profil konfiguriert ist, aber die Cache-Datei fehlt, + regeneriert Doctor den Cache automatisch. +- Wenn überhaupt keine Completion konfiguriert ist, fordert Doctor zur Installation auf + (nur im interaktiven Modus; übersprungen mit `--non-interactive`). Führen Sie `openclaw completion --write-state` aus, um den Cache manuell neu zu erzeugen. @@ -419,91 +458,91 @@ Führen Sie `openclaw completion --write-state` aus, um den Cache manuell neu zu Doctor prüft die Bereitschaft der lokalen Gateway-Token-Authentifizierung. -- Wenn der Token-Modus einen Token benötigt und keine Tokenquelle vorhanden ist, bietet Doctor an, einen zu generieren. -- Wenn `gateway.auth.token` durch SecretRef verwaltet wird, aber nicht verfügbar ist, warnt Doctor und überschreibt ihn nicht mit Klartext. -- `openclaw doctor --generate-gateway-token` erzwingt die Generierung nur dann, wenn kein Token-SecretRef konfiguriert ist. +- Wenn der Token-Modus einen Token benötigt und keine Tokenquelle vorhanden ist, bietet Doctor an, einen zu erzeugen. +- Wenn `gateway.auth.token` per SecretRef verwaltet wird, aber nicht verfügbar ist, warnt Doctor und überschreibt ihn nicht mit Klartext. +- `openclaw doctor --generate-gateway-token` erzwingt eine Erzeugung nur dann, wenn kein Token-SecretRef konfiguriert ist. -### 12b) SecretRef-bewusste Reparaturen im Nur-Lese-Modus +### 12b) SecretRef-bewusste Reparaturen im Nur-Lesen-Modus -Einige Reparaturabläufe müssen konfigurierte Anmeldedaten prüfen, ohne das Fail-Fast-Verhalten der Laufzeit zu schwächen. +Einige Reparaturabläufe müssen konfigurierte Anmeldedaten prüfen, ohne das Laufzeitverhalten beim schnellen Fehlschlagen abzuschwächen. -- `openclaw doctor --fix` verwendet jetzt dasselbe SecretRef-Zusammenfassungsmodell im Nur-Lese-Modus wie Befehle der Statusfamilie für gezielte Konfigurationsreparaturen. -- Beispiel: Die Reparatur von Telegram-`allowFrom` / `groupAllowFrom` mit `@username` versucht, wenn verfügbar, konfigurierte Bot-Anmeldedaten zu verwenden. -- Wenn das Telegram-Bot-Token über SecretRef konfiguriert ist, aber im aktuellen Befehlsablauf nicht verfügbar ist, meldet Doctor, dass die Anmeldedaten konfiguriert, aber nicht verfügbar sind, und überspringt die automatische Auflösung, statt abzustürzen oder das Token fälschlich als fehlend zu melden. +- `openclaw doctor --fix` verwendet jetzt dasselbe schreibgeschützte SecretRef-Zusammenfassungsmodell wie Befehle der Statusfamilie für gezielte Konfigurationsreparaturen. +- Beispiel: Die Reparatur von Telegram-`allowFrom` / `groupAllowFrom` mit `@username` versucht, konfigurierte Bot-Anmeldedaten zu verwenden, wenn verfügbar. +- Wenn der Telegram-Bot-Token per SecretRef konfiguriert ist, aber im aktuellen Befehlsablauf nicht verfügbar ist, meldet Doctor, dass die Anmeldedaten konfiguriert, aber nicht verfügbar sind, und überspringt die automatische Auflösung, anstatt abzustürzen oder den Token fälschlich als fehlend zu melden. -### 13) Zustandsprüfung des Gateways + Neustart +### 13) Integritätsprüfung des Gateways + Neustart -Doctor führt eine Zustandsprüfung durch und bietet an, das Gateway neu zu starten, wenn es +Doctor führt eine Integritätsprüfung aus und bietet an, das Gateway neu zu starten, wenn es ungesund wirkt. -### 13b) Bereitschaft der Memory-Suche +### 13b) Bereitschaft der Speichersuche -Doctor prüft, ob der konfigurierte Embedding-Anbieter der Memory-Suche für den -Standard-Agenten bereit ist. Das Verhalten hängt vom konfigurierten Backend und Anbieter ab: +Doctor prüft, ob der konfigurierte Embedding-Provider der Speichersuche für den +Standard-Agenten bereit ist. Das Verhalten hängt vom konfigurierten Backend und Provider ab: -- **QMD-Backend**: prüft, ob die Binärdatei `qmd` verfügbar und startbar ist. - Wenn nicht, werden Hinweise zur Behebung ausgegeben, einschließlich des npm-Pakets und einer manuellen Option für den Binärpfad. -- **Expliziter lokaler Anbieter**: prüft auf eine lokale Modelldatei oder eine erkannte - Remote-/herunterladbare Modell-URL. Wenn sie fehlt, wird vorgeschlagen, zu einem Remote-Anbieter zu wechseln. -- **Expliziter Remote-Anbieter** (`openai`, `voyage` usw.): verifiziert, dass ein API-Schlüssel - in der Umgebung oder im Auth-Speicher vorhanden ist. Gibt umsetzbare Hinweise aus, wenn er fehlt. -- **Automatischer Anbieter**: prüft zuerst die Verfügbarkeit lokaler Modelle und versucht dann jeden Remote- - Anbieter in der Reihenfolge der automatischen Auswahl. +- **QMD-Backend**: prüft, ob die `qmd`-Binärdatei verfügbar und startbar ist. + Wenn nicht, werden Lösungshinweise ausgegeben, einschließlich des npm-Pakets und einer manuellen Binärpfadoption. +- **Expliziter lokaler Provider**: prüft auf eine lokale Modelldatei oder eine erkannte + Remote-/herunterladbare Modell-URL. Wenn sie fehlt, wird vorgeschlagen, zu einem Remote-Provider zu wechseln. +- **Expliziter Remote-Provider** (`openai`, `voyage` usw.): prüft, ob ein API-Schlüssel + in der Umgebung oder im Auth-Speicher vorhanden ist. Gibt umsetzbare Lösungshinweise aus, wenn er fehlt. +- **Auto-Provider**: prüft zuerst die Verfügbarkeit lokaler Modelle und versucht dann jeden Remote- + Provider in der Auto-Auswahlreihenfolge. -Wenn ein Gateway-Prüfergebnis verfügbar ist (das Gateway war zum Zeitpunkt der -Prüfung gesund), gleicht Doctor dessen Ergebnis mit der in der CLI sichtbaren Konfiguration ab und vermerkt -jede Abweichung. +Wenn ein Ergebnis einer Gateway-Prüfung verfügbar ist (das Gateway war zum Zeitpunkt der +Prüfung in Ordnung), vergleicht Doctor das Ergebnis mit der in der CLI sichtbaren Konfiguration und weist +auf etwaige Abweichungen hin. -Verwenden Sie `openclaw memory status --deep`, um die Embedding-Bereitschaft zur Laufzeit zu verifizieren. +Verwenden Sie `openclaw memory status --deep`, um die Embedding-Bereitschaft zur Laufzeit zu prüfen. -### 14) Kanalstatuswarnungen +### 14) Warnungen zum Kanalstatus -Wenn das Gateway gesund ist, führt Doctor eine Abfrage des Kanalstatus aus und meldet -Warnungen mit vorgeschlagenen Behebungen. +Wenn das Gateway in Ordnung ist, führt Doctor eine Prüfung des Kanalstatus aus und meldet +Warnungen mit vorgeschlagenen Lösungen. ### 15) Audit der Supervisor-Konfiguration + Reparatur Doctor prüft die installierte Supervisor-Konfiguration (launchd/systemd/schtasks) auf -fehlende oder veraltete Standardwerte (z. B. network-online-Abhängigkeiten und -Neustartverzögerung bei systemd). Wenn es eine Abweichung findet, empfiehlt es ein Update und kann -die Dienstdatei/Aufgabe mit den aktuellen Standardwerten neu schreiben. +fehlende oder veraltete Standardwerte (z. B. systemd-Abhängigkeiten von network-online und +Neustartverzögerung). Wenn es eine Nichtübereinstimmung findet, empfiehlt es eine Aktualisierung und kann +die Dienstdatei/Aufgabe auf die aktuellen Standardwerte umschreiben. Hinweise: -- `openclaw doctor` fragt vor dem Neuschreiben der Supervisor-Konfiguration nach. -- `openclaw doctor --yes` akzeptiert die Standard-Reparaturabfragen. -- `openclaw doctor --repair` wendet empfohlene Behebungen ohne Rückfrage an. +- `openclaw doctor` fragt vor dem Umschreiben der Supervisor-Konfiguration nach. +- `openclaw doctor --yes` akzeptiert die Standard-Reparaturaufforderungen. +- `openclaw doctor --repair` wendet empfohlene Korrekturen ohne Rückfragen an. - `openclaw doctor --repair --force` überschreibt benutzerdefinierte Supervisor-Konfigurationen. -- Wenn die Token-Authentifizierung ein Token erfordert und `gateway.auth.token` durch SecretRef verwaltet wird, validiert die Installation/Reparatur des Doctor-Dienstes den SecretRef, persistiert aber keine aufgelösten Klartext-Tokenwerte in die Umgebungsmetadaten des Supervisor-Dienstes. -- Wenn die Token-Authentifizierung ein Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst ist, blockiert Doctor den Installations-/Reparaturpfad mit umsetzbaren Hinweisen. -- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, blockiert Doctor Installation/Reparatur, bis der Modus explizit gesetzt wird. -- Für Linux-User-systemd-Units umfassen Token-Drift-Prüfungen von Doctor jetzt sowohl Quellen aus `Environment=` als auch aus `EnvironmentFile=`, wenn Dienst-Auth-Metadaten verglichen werden. -- Sie können jederzeit eine vollständige Neuschreibung mit `openclaw gateway install --force` erzwingen. +- Wenn die Token-Authentifizierung einen Token erfordert und `gateway.auth.token` per SecretRef verwaltet wird, validiert die Dienstinstallation/-reparatur von Doctor den SecretRef, speichert aber keine aufgelösten Klartext-Tokenwerte in den Umgebungsmetadaten des Supervisor-Dienstes. +- Wenn die Token-Authentifizierung einen Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst werden kann, blockiert Doctor den Installations-/Reparaturpfad mit umsetzbaren Hinweisen. +- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, blockiert Doctor Installation/Reparatur, bis der Modus explizit gesetzt ist. +- Für Linux-User-systemd-Units umfassen Doctor-Prüfungen auf Token-Abweichungen jetzt sowohl `Environment=`- als auch `EnvironmentFile=`-Quellen beim Vergleich der Dienst-Auth-Metadaten. +- Sie können jederzeit ein vollständiges Umschreiben mit `openclaw gateway install --force` erzwingen. -### 16) Gateway-Laufzeit + Portdiagnosen +### 16) Gateway-Laufzeit + Portdiagnose -Doctor prüft die Laufzeit des Dienstes (PID, letzter Exit-Status) und warnt, wenn der -Dienst installiert, aber tatsächlich nicht ausgeführt wird. Es prüft auch auf Portkollisionen +Doctor prüft die Dienstlaufzeit (PID, letzter Exit-Status) und warnt, wenn der +Dienst installiert, aber nicht tatsächlich aktiv ist. Es prüft außerdem auf Portkonflikte am Gateway-Port (Standard `18789`) und meldet wahrscheinliche Ursachen (Gateway läuft bereits, SSH-Tunnel). -### 17) Best Practices für die Gateway-Laufzeit +### 17) Bewährte Laufzeitpraktiken für das Gateway -Doctor warnt, wenn der Gateway-Dienst auf Bun oder einem Node-Pfad mit Versionsmanager +Doctor warnt, wenn der Gateway-Dienst auf Bun oder einem versionsverwalteten Node-Pfad (`nvm`, `fnm`, `volta`, `asdf` usw.) läuft. WhatsApp- und Telegram-Kanäle erfordern Node, -und Pfade von Versionsmanagern können nach Upgrades brechen, weil der Dienst Ihre Shell-Initialisierung nicht -lädt. Doctor bietet an, zu einer System-Node-Installation zu migrieren, wenn +und Pfade von Versionsmanagern können nach Upgrades Probleme verursachen, weil der Dienst Ihre Shell-Initialisierung nicht +lädt. Doctor bietet an, auf eine System-Node-Installation zu migrieren, wenn verfügbar (Homebrew/apt/choco). ### 18) Konfigurationsschreiben + Wizard-Metadaten -Doctor persistiert alle Konfigurationsänderungen und versieht die -Wizard-Metadaten mit einem Zeitstempel, um den Doctor-Lauf aufzuzeichnen. +Doctor speichert alle Konfigurationsänderungen und setzt Wizard-Metadaten, um die +Doctor-Ausführung zu protokollieren. -### 19) Workspace-Tipps (Backup + Memory-System) +### 19) Workspace-Tipps (Sicherung + Speichersystem) -Doctor schlägt ein Workspace-Memory-System vor, wenn keines vorhanden ist, und gibt einen Backup-Hinweis aus, +Doctor schlägt ein Workspace-Speichersystem vor, wenn keines vorhanden ist, und gibt einen Sicherungshinweis aus, wenn der Workspace noch nicht unter Git steht. Siehe [/concepts/agent-workspace](/de/concepts/agent-workspace) für eine vollständige Anleitung zur -Workspace-Struktur und Git-Backups (empfohlen: privates GitHub oder GitLab). +Workspace-Struktur und Git-Sicherung (empfohlen: privates GitHub oder GitLab). diff --git a/docs/de/help/testing.md b/docs/de/help/testing.md index 4bf8c8cca..567064c4a 100644 --- a/docs/de/help/testing.md +++ b/docs/de/help/testing.md @@ -1,123 +1,120 @@ --- read_when: - - Beim lokalen Ausführen von Tests oder in CI - - Beim Hinzufügen von Regressionstests für Modell-/Provider-Fehler - - Beim Debuggen von Gateway- und Agent-Verhalten -summary: 'Test-Kit: Unit-/E2E-/Live-Suiten, Docker-Runner und was jeder Test abdeckt' + - Tests lokal oder in CI ausführen + - Regressionen für Modell-/Provider-Fehler hinzufügen + - Gateway- und Agent-Verhalten debuggen +summary: 'Test-Kit: Unit-/E2E-/Live-Suiten, Docker-Runner und was die einzelnen Tests abdecken' title: Tests x-i18n: - generated_at: "2026-04-08T02:17:53Z" + generated_at: "2026-04-09T01:30:33Z" model: gpt-5.4 provider: openai - source_hash: ace2c19bfc350780475f4348264a4b55be2b4ccbb26f0d33b4a6af34510943b5 + source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b source_path: help/testing.md workflow: 15 --- # Tests -OpenClaw hat drei Vitest-Suiten (Unit/Integration, E2E, Live) und eine kleine Gruppe von Docker-Runnern. +OpenClaw hat drei Vitest-Suiten (Unit/Integration, E2E, Live) und eine kleine Anzahl von Docker-Runnern. -Diese Dokumentation ist ein Leitfaden dazu, **wie wir testen**: +Dieses Dokument ist ein Leitfaden dazu, „wie wir testen“: - Was jede Suite abdeckt (und was sie bewusst _nicht_ abdeckt) -- Welche Befehle für gängige Workflows ausgeführt werden sollten (lokal, vor dem Push, Debugging) +- Welche Befehle Sie für häufige Workflows ausführen sollten (lokal, vor dem Push, Debugging) - Wie Live-Tests Anmeldedaten erkennen und Modelle/Provider auswählen -- Wie Regressionstests für reale Modell-/Provider-Probleme hinzugefügt werden +- Wie Sie Regressionen für reale Modell-/Provider-Probleme hinzufügen ## Schnellstart An den meisten Tagen: -- Vollständiges Gate (vor einem Push erwartet): `pnpm build && pnpm check && pnpm test` -- Schnellere vollständige lokale Ausführung auf einem leistungsfähigen Rechner: `pnpm test:max` +- Vollständiges Gate (vor dem Push erwartet): `pnpm build && pnpm check && pnpm test` +- Schnellere lokale Ausführung der vollständigen Suite auf einem leistungsfähigen Rechner: `pnpm test:max` - Direkte Vitest-Watch-Schleife: `pnpm test:watch` -- Direktes Targeting einzelner Dateien routet jetzt auch Extension-/Kanalpfade: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Direktes File-Targeting leitet jetzt auch Erweiterungs-/Kanalpfade weiter: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Docker-gestützte QA-Site: `pnpm qa:lab:up` -Wenn Sie Tests ändern oder zusätzliche Sicherheit möchten: +Wenn Sie Tests anfassen oder zusätzliche Sicherheit möchten: - Coverage-Gate: `pnpm test:coverage` - E2E-Suite: `pnpm test:e2e` -Beim Debuggen realer Provider/Modelle (erfordert echte Zugangsdaten): +Beim Debuggen echter Provider/Modelle (erfordert echte Anmeldedaten): -- Live-Suite (Modelle + Gateway-Tool-/Bild-Probes): `pnpm test:live` -- Eine einzelne Live-Datei leise ausführen: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-Suite (Modelle + Gateway-Tool-/Bild-Sonden): `pnpm test:live` +- Eine einzelne Live-Datei ruhig ausführen: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Tipp: Wenn Sie nur einen fehlschlagenden Fall brauchen, grenzen Sie Live-Tests bevorzugt über die unten beschriebenen Allowlist-Umgebungsvariablen ein. +Tipp: Wenn Sie nur einen fehlschlagenden Fall benötigen, grenzen Sie Live-Tests vorzugsweise über die unten beschriebenen Allowlist-Umgebungsvariablen ein. ## Test-Suiten (was wo läuft) -Betrachten Sie die Suiten als „zunehmend realistisch“ (und zunehmend anfällig/kostenintensiv): +Betrachten Sie die Suiten als „zunehmend realistisch“ (und zunehmend anfällig/kostspielig): ### Unit / Integration (Standard) - Befehl: `pnpm test` -- Konfiguration: zehn sequenzielle Shard-Läufe (`vitest.full-*.config.ts`) über die vorhandenen scoped Vitest-Projekte -- Dateien: Core-/Unit-Inventare unter `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` und die per `vitest.unit.config.ts` freigegebenen `ui`-Node-Tests +- Konfiguration: zehn sequentielle Shard-Läufe (`vitest.full-*.config.ts`) über die vorhandenen abgegrenzten Vitest-Projekte +- Dateien: Kern-/Unit-Inventare unter `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` und die freigegebenen `ui`-Node-Tests, die von `vitest.unit.config.ts` abgedeckt werden - Umfang: - Reine Unit-Tests - In-Process-Integrationstests (Gateway-Authentifizierung, Routing, Tooling, Parsing, Konfiguration) - - Deterministische Regressionstests für bekannte Fehler + - Deterministische Regressionen für bekannte Fehler - Erwartungen: - Läuft in CI - Keine echten Schlüssel erforderlich - Sollte schnell und stabil sein - Hinweis zu Projekten: - - Nicht gezieltes `pnpm test` führt jetzt elf kleinere Shard-Konfigurationen aus (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) statt eines einzigen riesigen nativen Root-Project-Prozesses. Das senkt den Spitzen-RSS auf ausgelasteten Rechnern und verhindert, dass auto-reply-/Extension-Arbeit andere Suiten ausbremst. - - `pnpm test --watch` verwendet weiterhin den nativen Root-`vitest.config.ts`-Projektgraphen, weil eine Watch-Schleife über mehrere Shards nicht praktikabel ist. - - `pnpm test`, `pnpm test:watch` und `pnpm test:perf:imports` routen explizite Datei-/Verzeichnisziele zuerst durch scoped Lanes, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die vollen Startup-Kosten des Root-Projekts zahlen muss. - - `pnpm test:changed` erweitert geänderte Git-Pfade in dieselben scoped Lanes, wenn der Diff nur routbare Quell-/Testdateien berührt; Änderungen an Konfiguration/Setup fallen weiterhin auf die breitere Wiederholung des Root-Projekts zurück. - - Ausgewählte `plugin-sdk`- und `commands`-Tests werden ebenfalls durch dedizierte leichte Lanes geroutet, die `test/setup-openclaw-runtime.ts` überspringen; zustandsbehaftete/laufzeitintensive Dateien bleiben auf den bestehenden Lanes. - - Ausgewählte `plugin-sdk`- und `commands`-Hilfsquelldateien mappen Läufe im Changed-Modus ebenfalls auf explizite benachbarte Tests in diesen leichten Lanes, sodass Änderungen an Helfern nicht die gesamte schwere Suite für dieses Verzeichnis neu starten. - - `auto-reply` hat jetzt drei dedizierte Buckets: Core-Helfer auf oberster Ebene, Integrations-Tests `reply.*` auf oberster Ebene und den Unterbaum `src/auto-reply/reply/**`. Dadurch bleibt die schwerste Reply-Harness-Arbeit von den günstigen Status-/Chunk-/Token-Tests getrennt. + - Nicht gezieltes `pnpm test` führt jetzt elf kleinere Shard-Konfigurationen aus (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) statt eines riesigen nativen Root-Project-Prozesses. Das reduziert den Spitzen-RSS auf ausgelasteten Maschinen und verhindert, dass `auto-reply`-/Erweiterungsarbeit nicht verwandte Suiten ausbremst. + - `pnpm test --watch` verwendet weiterhin den nativen Root-`vitest.config.ts`-Projektgraphen, weil eine Multi-Shard-Watch-Schleife nicht praktikabel ist. + - `pnpm test`, `pnpm test:watch` und `pnpm test:perf:imports` leiten explizite Datei-/Verzeichnisziele zuerst durch abgegrenzte Lanes, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die vollständige Startlast des Root-Projekts zahlen muss. + - `pnpm test:changed` erweitert geänderte Git-Pfade in dieselben abgegrenzten Lanes, wenn der Diff nur routbare Source-/Test-Dateien berührt; Konfigurations-/Setup-Änderungen fallen weiterhin auf die breite erneute Ausführung des Root-Projekts zurück. + - Ausgewählte `plugin-sdk`- und `commands`-Tests werden ebenfalls durch dedizierte leichte Lanes geleitet, die `test/setup-openclaw-runtime.ts` überspringen; zustandsbehaftete/runtime-schwere Dateien bleiben auf den vorhandenen Lanes. + - Ausgewählte `plugin-sdk`- und `commands`-Hilfsquelldateien ordnen Läufe im Changed-Modus ebenfalls expliziten Nachbartests in diesen leichten Lanes zu, sodass Hilfsänderungen nicht die vollständige schwere Suite für dieses Verzeichnis erneut ausführen. + - `auto-reply` hat jetzt drei dedizierte Buckets: Top-Level-Kernhilfen, Top-Level-`reply.*`-Integrationstests und den Teilbaum `src/auto-reply/reply/**`. Dadurch bleibt die schwerste Reply-Harness-Arbeit von den günstigen Status-/Chunk-/Token-Tests getrennt. - Hinweis zum eingebetteten Runner: - - Wenn Sie Eingaben zur Message-Tool-Erkennung oder den Laufzeitkontext der Kompaktierung ändern, - halten Sie beide Abdeckungsebenen intakt. - - Fügen Sie gezielte Helfer-Regressionen für reine Routing-/Normalisierungsgrenzen hinzu. - - Halten Sie außerdem die Integrationssuiten des eingebetteten Runners funktionsfähig: + - Wenn Sie Eingaben zur Message-Tool-Erkennung oder den Runtime-Kontext der Kompaktierung ändern, erhalten Sie beide Ebenen der Abdeckung. + - Fügen Sie fokussierte Hilfsregressionen für reine Routing-/Normalisierungsgrenzen hinzu. + - Halten Sie außerdem die eingebetteten Runner-Integrationssuiten intakt: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` und `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Diese Suiten prüfen, dass scoped IDs und Kompaktierungsverhalten weiterhin - durch die realen Pfade `run.ts` / `compact.ts` fließen; reine Helfer-Tests - sind kein ausreichender Ersatz für diese Integrationspfade. + - Diese Suiten prüfen, dass abgegrenzte IDs und das Kompaktierungsverhalten weiterhin durch die echten `run.ts`-/`compact.ts`-Pfade fließen; reine Hilfstests sind kein ausreichender Ersatz für diese Integrationspfade. - Hinweis zum Pool: - Die Basis-Vitest-Konfiguration verwendet jetzt standardmäßig `threads`. - - Die gemeinsame Vitest-Konfiguration fixiert außerdem `isolate: false` und verwendet den nicht isolierten Runner über Root-Projekte, E2E- und Live-Konfigurationen hinweg. - - Die Root-UI-Lane behält ihr `jsdom`-Setup und ihren Optimizer, läuft jetzt aber ebenfalls auf dem gemeinsamen nicht isolierten Runner. + - Die gemeinsame Vitest-Konfiguration setzt außerdem `isolate: false` fest und verwendet den nicht isolierten Runner über die Root-Projekte sowie die E2E- und Live-Konfigurationen hinweg. + - Die Root-UI-Lane behält ihr `jsdom`-Setup und ihren Optimizer bei, läuft jetzt aber ebenfalls auf dem gemeinsamen nicht isolierten Runner. - Jeder `pnpm test`-Shard erbt dieselben Standardwerte `threads` + `isolate: false` aus der gemeinsamen Vitest-Konfiguration. - - Der gemeinsame Launcher `scripts/run-vitest.mjs` fügt standardmäßig jetzt auch `--no-maglev` für Vitest-Kind-Node-Prozesse hinzu, um V8-Kompilieraufwand bei großen lokalen Läufen zu reduzieren. Setzen Sie `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, wenn Sie gegen das Standardverhalten von V8 vergleichen müssen. + - Der gemeinsame Launcher `scripts/run-vitest.mjs` fügt jetzt standardmäßig auch `--no-maglev` für Node-Unterprozesse von Vitest hinzu, um V8-Kompilierungs-Churn bei großen lokalen Läufen zu reduzieren. Setzen Sie `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, wenn Sie mit dem Standardverhalten von V8 vergleichen müssen. - Hinweis zur schnellen lokalen Iteration: - - `pnpm test:changed` routet durch scoped Lanes, wenn sich die geänderten Pfade sauber auf eine kleinere Suite abbilden lassen. - - `pnpm test:max` und `pnpm test:changed:max` behalten dasselbe Routing-Verhalten bei, nur mit höherem Worker-Limit. - - Die automatische Skalierung lokaler Worker ist jetzt bewusst konservativ und reduziert sich auch dann, wenn die Host-Load-Average bereits hoch ist, sodass mehrere gleichzeitige Vitest-Läufe standardmäßig weniger Schaden anrichten. - - Die Basis-Vitest-Konfiguration markiert die Projekte/Konfigurationsdateien als `forceRerunTriggers`, damit Wiederholungen im Changed-Modus korrekt bleiben, wenn sich die Test-Verdrahtung ändert. - - Die Konfiguration lässt `OPENCLAW_VITEST_FS_MODULE_CACHE` auf unterstützten Hosts aktiviert; setzen Sie `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, wenn Sie einen expliziten Cache-Pfad für direktes Profiling möchten. + - `pnpm test:changed` leitet durch abgegrenzte Lanes, wenn sich die geänderten Pfade sauber einer kleineren Suite zuordnen lassen. + - `pnpm test:max` und `pnpm test:changed:max` behalten dasselbe Routing-Verhalten bei, nur mit höherer Worker-Obergrenze. + - Die automatische lokale Worker-Skalierung ist jetzt absichtlich konservativ und fährt auch zurück, wenn die Last des Hosts bereits hoch ist, sodass mehrere gleichzeitige Vitest-Läufe standardmäßig weniger Schaden anrichten. + - Die Basis-Vitest-Konfiguration markiert Projekte/Konfigurationsdateien als `forceRerunTriggers`, damit Wiederholungsläufe im Changed-Modus korrekt bleiben, wenn sich die Testverkabelung ändert. + - Die Konfiguration lässt `OPENCLAW_VITEST_FS_MODULE_CACHE` auf unterstützten Hosts aktiviert; setzen Sie `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, wenn Sie einen expliziten Cache-Speicherort für direktes Profiling möchten. - Hinweis zum Performance-Debugging: - - `pnpm test:perf:imports` aktiviert Importdauer-Berichte von Vitest plus Ausgabe zur Import-Aufschlüsselung. - - `pnpm test:perf:imports:changed` beschränkt dieselbe Profiling-Ansicht auf Dateien, die seit `origin/main` geändert wurden. -- `pnpm test:perf:changed:bench -- --ref ` vergleicht das geroutete `test:changed` für diesen festgeschriebenen Diff mit dem nativen Root-Project-Pfad und gibt Laufzeit plus macOS-Max-RSS aus. -- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen nicht festgeschriebenen Baum, indem die Liste geänderter Dateien durch `scripts/test-projects.mjs` und die Root-Vitest-Konfiguration geroutet wird. - - `pnpm test:perf:profile:main` schreibt ein CPU-Profil des Hauptthreads für Vitest-/Vite-Startup- und Transform-Overhead. - - `pnpm test:perf:profile:runner` schreibt Runner-CPU- und Heap-Profile für die Unit-Suite bei deaktivierter Datei-Parallelität. + - `pnpm test:perf:imports` aktiviert die Importdauer-Berichterstattung von Vitest sowie die Ausgabe der Import-Aufschlüsselung. + - `pnpm test:perf:imports:changed` grenzt dieselbe Profiling-Ansicht auf Dateien ein, die seit `origin/main` geändert wurden. +- `pnpm test:perf:changed:bench -- --ref ` vergleicht geroutetes `test:changed` mit dem nativen Root-Project-Pfad für diesen bestätigten Diff und gibt Wandzeit plus macOS-Max-RSS aus. +- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen schmutzigen Baum, indem die Liste geänderter Dateien über `scripts/test-projects.mjs` und die Root-Vitest-Konfiguration geleitet wird. + - `pnpm test:perf:profile:main` schreibt ein CPU-Profil des Hauptthreads für den Vitest/Vite-Start und den Transform-Overhead. + - `pnpm test:perf:profile:runner` schreibt CPU- und Heap-Profile des Runners für die Unit-Suite bei deaktivierter Dateiparallelität. ### E2E (Gateway-Smoke) - Befehl: `pnpm test:e2e` - Konfiguration: `vitest.e2e.config.ts` - Dateien: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Laufzeit-Standards: - - Verwendet Vitest `threads` mit `isolate: false`, passend zum Rest des Repositories. +- Standardwerte zur Laufzeit: + - Verwendet Vitest-`threads` mit `isolate: false`, passend zum Rest des Repos. - Verwendet adaptive Worker (CI: bis zu 2, lokal: standardmäßig 1). - - Läuft standardmäßig im Silent-Modus, um Console-I/O-Overhead zu reduzieren. -- Nützliche Overrides: - - `OPENCLAW_E2E_WORKERS=`, um die Worker-Anzahl zu erzwingen (maximal 16). - - `OPENCLAW_E2E_VERBOSE=1`, um ausführliche Console-Ausgabe wieder zu aktivieren. + - Läuft standardmäßig im stillen Modus, um den Konsolen-I/O-Overhead zu verringern. +- Nützliche Überschreibungen: + - `OPENCLAW_E2E_WORKERS=`, um die Worker-Anzahl zu erzwingen (begrenzt auf 16). + - `OPENCLAW_E2E_VERBOSE=1`, um ausführliche Konsolenausgabe wieder zu aktivieren. - Umfang: - - End-to-End-Verhalten von Gateway-Instanzen mit mehreren Instanzen - - WebSocket-/HTTP-Oberflächen, Node-Pairing und aufwendigere Netzwerkpfade + - End-to-End-Verhalten mit mehreren Gateway-Instanzen + - WebSocket-/HTTP-Oberflächen, Node-Pairing und umfangreicheres Networking - Erwartungen: - Läuft in CI (wenn in der Pipeline aktiviert) - Keine echten Schlüssel erforderlich @@ -128,132 +125,134 @@ Betrachten Sie die Suiten als „zunehmend realistisch“ (und zunehmend anfäll - Befehl: `pnpm test:e2e:openshell` - Datei: `test/openshell-sandbox.e2e.test.ts` - Umfang: - - Startet ein isoliertes OpenShell-Gateway auf dem Host über Docker - - Erstellt eine Sandbox aus einer temporären lokalen Dockerfile - - Testet OpenClaws OpenShell-Backend über echtes `sandbox ssh-config` + SSH-exec - - Prüft remote-kanonisches Dateisystemverhalten über die Sandbox-FS-Bridge + - Startet über Docker ein isoliertes OpenShell-Gateway auf dem Host + - Erstellt aus einem temporären lokalen Dockerfile eine Sandbox + - Testet das OpenShell-Backend von OpenClaw über echtes `sandbox ssh-config` + SSH-Exec + - Verifiziert Remote-Canonical-Dateisystemverhalten über die Sandbox-FS-Bridge - Erwartungen: - - Nur opt-in; nicht Teil des Standardlaufs `pnpm test:e2e` - - Erfordert eine lokale `openshell`-CLI plus einen funktionierenden Docker-Daemon + - Nur Opt-in; nicht Teil des standardmäßigen `pnpm test:e2e`-Laufs + - Erfordert eine lokale `openshell`-CLI sowie einen funktionierenden Docker-Daemon - Verwendet isoliertes `HOME` / `XDG_CONFIG_HOME` und zerstört anschließend Test-Gateway und Sandbox -- Nützliche Overrides: +- Nützliche Überschreibungen: - `OPENCLAW_E2E_OPENSHELL=1`, um den Test zu aktivieren, wenn die breitere E2E-Suite manuell ausgeführt wird - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, um auf ein nicht standardmäßiges CLI-Binary oder Wrapper-Skript zu verweisen + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, um auf eine nicht standardmäßige CLI-Binärdatei oder ein Wrapper-Skript zu zeigen -### Live (reale Provider + reale Modelle) +### Live (echte Provider + echte Modelle) - Befehl: `pnpm test:live` - Konfiguration: `vitest.live.config.ts` - Dateien: `src/**/*.live.test.ts` - Standard: **aktiviert** durch `pnpm test:live` (setzt `OPENCLAW_LIVE_TEST=1`) - Umfang: - - „Funktioniert dieser Provider/dieses Modell _heute_ tatsächlich mit echten Zugangsdaten?“ - - Erkennt Provider-Formatänderungen, Eigenheiten beim Tool-Calling, Authentifizierungsprobleme und Rate-Limit-Verhalten + - „Funktioniert dieser Provider/dieses Modell _heute_ tatsächlich mit echten Anmeldedaten?“ + - Erkennt Provider-Formatänderungen, Tool-Calling-Besonderheiten, Auth-Probleme und Rate-Limit-Verhalten - Erwartungen: - - Bewusst nicht CI-stabil (reale Netzwerke, reale Provider-Richtlinien, Quoten, Ausfälle) - - Kostet Geld / verbraucht Rate Limits - - Bevorzugt eingegrenzte Teilmengen statt „alles“ -- Live-Läufe laden `~/.profile`, um fehlende API-Schlüssel aufzunehmen. -- Standardmäßig isolieren Live-Läufe trotzdem `HOME` und kopieren Konfigurations-/Authentifizierungsmaterial in ein temporäres Test-Home, damit Unit-Fixtures Ihr echtes `~/.openclaw` nicht verändern können. + - Von Natur aus nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Quoten, Ausfälle) + - Kostet Geld / verbraucht Rate-Limits + - Führen Sie vorzugsweise eingegrenzte Teilmengen statt „alles“ aus +- Live-Läufe sourcen `~/.profile`, um fehlende API-Schlüssel zu übernehmen. +- Standardmäßig isolieren Live-Läufe weiterhin `HOME` und kopieren Konfigurations-/Auth-Material in ein temporäres Test-Home, sodass Unit-Fixtures Ihr echtes `~/.openclaw` nicht verändern können. - Setzen Sie `OPENCLAW_LIVE_USE_REAL_HOME=1` nur dann, wenn Live-Tests absichtlich Ihr echtes Home-Verzeichnis verwenden sollen. -- `pnpm test:live` verwendet jetzt standardmäßig einen leiseren Modus: Der `[live] ...`-Fortschritt bleibt sichtbar, die zusätzliche `~/.profile`-Meldung wird jedoch unterdrückt und Gateway-Bootstrap-Logs/Bonjour-Rauschen werden stummgeschaltet. Setzen Sie `OPENCLAW_LIVE_TEST_QUIET=0`, wenn Sie die vollständigen Start-Logs wieder sehen möchten. -- Rotation von API-Schlüsseln (provider-spezifisch): Setzen Sie `*_API_KEYS` im Komma-/Semikolon-Format oder `*_API_KEY_1`, `*_API_KEY_2` (zum Beispiel `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oder pro Live-Override `OPENCLAW_LIVE_*_KEY`; Tests wiederholen bei Rate-Limit-Antworten. -- Fortschritts-/Heartbeat-Ausgabe: - - Live-Suiten geben jetzt Fortschrittszeilen nach stderr aus, damit lange Provider-Aufrufe sichtbar aktiv bleiben, auch wenn die Console-Erfassung von Vitest still ist. - - `vitest.live.config.ts` deaktiviert die Console-Abfangung von Vitest, sodass Fortschrittszeilen von Provider/Gateway während Live-Läufen sofort gestreamt werden. - - Steuern Sie Heartbeats für direkte Modelle mit `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Steuern Sie Heartbeats für Gateway/Probe mit `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- `pnpm test:live` verwendet jetzt standardmäßig einen ruhigeren Modus: Der Fortschritt `[live] ...` bleibt erhalten, aber der zusätzliche Hinweis zu `~/.profile` wird unterdrückt und Gateway-Bootstrap-Logs/Bonjour-Chatter werden stummgeschaltet. Setzen Sie `OPENCLAW_LIVE_TEST_QUIET=0`, wenn Sie die vollständigen Startlogs wieder sehen möchten. +- Rotation von API-Schlüsseln (providerspezifisch): Setzen Sie `*_API_KEYS` im Komma-/Semikolonformat oder `*_API_KEY_1`, `*_API_KEY_2` (zum Beispiel `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oder eine per-Live-Überschreibung über `OPENCLAW_LIVE_*_KEY`; Tests versuchen bei Rate-Limit-Antworten erneut. +- Ausgabe von Fortschritt/Heartbeat: + - Live-Suiten geben jetzt Fortschrittszeilen nach stderr aus, sodass lange Provider-Aufrufe sichtbar aktiv sind, selbst wenn die Konsolenerfassung von Vitest ruhig ist. + - `vitest.live.config.ts` deaktiviert die Konsoleninterzeption von Vitest, sodass Provider-/Gateway-Fortschrittszeilen während Live-Läufen sofort gestreamt werden. + - Stimmen Sie Heartbeats für direkte Modelle mit `OPENCLAW_LIVE_HEARTBEAT_MS` ab. + - Stimmen Sie Heartbeats für Gateway/Sonden mit `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` ab. -## Welche Suite sollte ich ausführen? +## Welche Suite soll ich ausführen? -Verwenden Sie diese Entscheidungshilfe: +Verwenden Sie diese Entscheidungstabelle: - Logik/Tests bearbeiten: `pnpm test` ausführen (und `pnpm test:coverage`, wenn Sie viel geändert haben) -- Gateway-Netzwerk / WS-Protokoll / Pairing anfassen: zusätzlich `pnpm test:e2e` -- „Mein Bot ist down“ / provider-spezifische Ausfälle / Tool-Calling debuggen: ein eingegrenztes `pnpm test:live` ausführen +- Gateway-Networking / WS-Protokoll / Pairing anfassen: `pnpm test:e2e` hinzufügen +- „Mein Bot ist down“ / providerspezifische Fehler / Tool-Calling debuggen: ein eingegrenztes `pnpm test:live` ausführen ## Live: Android-Node-Fähigkeiten-Sweep - Test: `src/gateway/android-node.capabilities.live.test.ts` - Skript: `pnpm android:test:integration` -- Ziel: **jeden aktuell beworbenen Befehl** eines verbundenen Android-Nodes aufrufen und das Vertragsverhalten des Befehls prüfen. +- Ziel: **jeden aktuell angekündigten Befehl** eines verbundenen Android-Nodes aufrufen und das Vertragsverhalten des Befehls bestätigen. - Umfang: - - Vorausgesetztes/manuelles Setup (die Suite installiert/startet/pairt die App nicht). - - Gateway-Validierung `node.invoke` pro Befehl für den ausgewählten Android-Node. + - Voraussetzungen/manuelles Setup sind erforderlich (die Suite installiert/startet/pairt die App nicht). + - Gateway-Validierung `node.invoke` für jeden Befehl des ausgewählten Android-Nodes. - Erforderliches Vorab-Setup: - - Android-App bereits mit dem Gateway verbunden und gepairt. + - Android-App bereits verbunden und mit dem Gateway gepairt. - App im Vordergrund halten. - - Berechtigungen/Aufzeichnungseinwilligung für Fähigkeiten erteilen, die erfolgreich sein sollen. -- Optionale Target-Overrides: + - Berechtigungen/Aufnahmezustimmung für Fähigkeiten erteilen, die erfolgreich sein sollen. +- Optionale Zielüberschreibungen: - `OPENCLAW_ANDROID_NODE_ID` oder `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Vollständige Details zur Android-Einrichtung: [Android App](/de/platforms/android) +- Vollständige Android-Setup-Details: [Android App](/de/platforms/android) ## Live: Modell-Smoke (Profilschlüssel) -Live-Tests sind in zwei Ebenen aufgeteilt, damit Fehler isoliert werden können: +Live-Tests sind in zwei Ebenen aufgeteilt, damit wir Fehler isolieren können: -- „Direktes Modell“ sagt uns, ob der Provider/das Modell mit dem angegebenen Schlüssel überhaupt antworten kann. -- „Gateway-Smoke“ sagt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Modell funktioniert (Sitzungen, Verlauf, Tools, Sandbox-Richtlinie usw.). +- „Direct model“ zeigt uns, ob der Provider/das Modell mit dem gegebenen Schlüssel überhaupt antworten kann. +- „Gateway smoke“ zeigt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Modell funktioniert (Sitzungen, Verlauf, Tools, Sandbox-Richtlinie usw.). -### Ebene 1: Direkte Modell-Completion (ohne Gateway) +### Ebene 1: Direkte Modellvervollständigung (ohne Gateway) - Test: `src/agents/models.profiles.live.test.ts` - Ziel: - Erkannte Modelle aufzählen - - `getApiKeyForModel` verwenden, um Modelle auszuwählen, für die Sie Zugangsdaten haben - - Eine kleine Completion pro Modell ausführen (und gezielte Regressionen, wenn nötig) + - Mit `getApiKeyForModel` Modelle auswählen, für die Sie Anmeldedaten haben + - Eine kleine Vervollständigung pro Modell ausführen (und gezielte Regressionen, wenn nötig) - Aktivierung: - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) -- Setzen Sie `OPENCLAW_LIVE_MODELS=modern` (oder `all`, Alias für modern), um diese Suite tatsächlich auszuführen; andernfalls wird sie übersprungen, damit `pnpm test:live` auf Gateway-Smoke fokussiert bleibt +- Setzen Sie `OPENCLAW_LIVE_MODELS=modern` (oder `all`, Alias für modern), damit diese Suite tatsächlich läuft; andernfalls wird sie übersprungen, damit `pnpm test:live` auf Gateway-Smoke fokussiert bleibt - Modellauswahl: - `OPENCLAW_LIVE_MODELS=modern`, um die moderne Allowlist auszuführen (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` ist ein Alias für die moderne Allowlist - oder `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (Komma-Allowlist) + - Moderne/All-Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setzen Sie `OPENCLAW_LIVE_MAX_MODELS=0` für einen vollständigen modernen Sweep oder einen positiven Wert für eine kleinere Obergrenze. - Providerauswahl: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (Komma-Allowlist) -- Herkunft der Schlüssel: - - Standardmäßig: Profilspeicher und Env-Fallbacks - - Setzen Sie `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um **nur** den Profilspeicher zu erzwingen -- Warum das existiert: +- Woher die Schlüssel kommen: + - Standardmäßig: Profile-Store und Env-Fallbacks + - Setzen Sie `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um **nur** den Profile-Store zu erzwingen +- Warum es das gibt: - Trennt „Provider-API ist kaputt / Schlüssel ist ungültig“ von „Gateway-Agent-Pipeline ist kaputt“ - - Enthält kleine, isolierte Regressionen (Beispiel: OpenAI-Responses/Codex-Responses-Reasoning-Replay + Tool-Call-Flows) + - Enthält kleine, isolierte Regressionen (Beispiel: OpenAI Responses/Codex-Responses-Reasoning-Replay + Tool-Call-Flows) -### Ebene 2: Gateway + Dev-Agent-Smoke (was „@openclaw“ tatsächlich macht) +### Ebene 2: Gateway + Dev-Agent-Smoke (was „@openclaw“ tatsächlich tut) - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Ziel: - Ein In-Process-Gateway starten - - Eine Sitzung `agent:dev:*` erstellen/patchen (Modell-Override pro Lauf) - - Über Modelle mit Schlüsseln iterieren und prüfen: + - Eine `agent:dev:*`-Sitzung erstellen/patchen (Modellüberschreibung pro Lauf) + - Modelle mit Schlüsseln durchlaufen und Folgendes bestätigen: - „sinnvolle“ Antwort (ohne Tools) - - ein echter Tool-Aufruf funktioniert (`read`-Probe) - - optionale zusätzliche Tool-Probes funktionieren (`exec+read`-Probe) - - OpenAI-Regressionspfade (nur Tool-Call → Follow-up) funktionieren weiter -- Details zu den Probes (damit Fehler schnell erklärt werden können): - - `read`-Probe: Der Test schreibt eine Nonce-Datei in den Workspace und fordert den Agenten auf, sie mit `read` zu lesen und die Nonce zurückzugeben. - - `exec+read`-Probe: Der Test fordert den Agenten auf, per `exec` eine Nonce in eine temporäre Datei zu schreiben und sie dann mit `read` zurückzulesen. - - Bild-Probe: Der Test hängt eine generierte PNG-Datei an (Katze + randomisierter Code) und erwartet, dass das Modell `cat ` zurückgibt. + - ein echter Tool-Aufruf funktioniert (Read-Sonde) + - optionale zusätzliche Tool-Sonden funktionieren (Exec+Read-Sonde) + - OpenAI-Regressionspfade (nur Tool-Call → Follow-up) funktionieren weiterhin +- Details zu den Sonden (damit Sie Fehler schnell erklären können): + - `read`-Sonde: Der Test schreibt eine Nonce-Datei in den Workspace und fordert den Agenten auf, sie mit `read` zu lesen und die Nonce zurückzugeben. + - `exec+read`-Sonde: Der Test fordert den Agenten auf, per `exec` eine Nonce in eine temporäre Datei zu schreiben und sie anschließend per `read` zurückzulesen. + - Bildsonde: Der Test hängt ein generiertes PNG an (Katze + zufälliger Code) und erwartet, dass das Modell `cat ` zurückgibt. - Implementierungsreferenz: `src/gateway/gateway-models.profiles.live.test.ts` und `src/gateway/live-image-probe.ts`. - Aktivierung: - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) - Modellauswahl: - Standard: moderne Allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` ist ein Alias für die moderne Allowlist - - Oder `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (oder Komma-Liste) setzen, um einzugrenzen -- Providerauswahl (vermeidet „OpenRouter alles“): + - Oder `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` setzen (oder Kommaliste), um einzugrenzen + - Moderne/All-Gateway-Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setzen Sie `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` für einen vollständigen modernen Sweep oder einen positiven Wert für eine kleinere Obergrenze. +- Providerauswahl (vermeiden Sie „alles von OpenRouter“): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (Komma-Allowlist) -- Tool- + Bild-Probes sind in diesem Live-Test immer aktiv: - - `read`-Probe + `exec+read`-Probe (Tool-Stresstest) - - Bild-Probe läuft, wenn das Modell Unterstützung für Bildeingabe meldet - - Ablauf (hohe Ebene): - - Test generiert eine winzige PNG mit „CAT“ + Zufallscode (`src/gateway/live-image-probe.ts`) - - Sendet sie über `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway parst Anhänge in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Eingebetteter Agent leitet eine multimodale Benutzernachricht an das Modell weiter - - Prüfung: Antwort enthält `cat` + den Code (OCR-Toleranz: kleinere Fehler sind erlaubt) +- Tool- und Bildsonden sind in diesem Live-Test immer aktiv: + - `read`-Sonde + `exec+read`-Sonde (Tool-Stresstest) + - Bildsonde läuft, wenn das Modell Unterstützung für Bildeingaben ankündigt + - Ablauf (auf hoher Ebene): + - Der Test erzeugt ein kleines PNG mit „CAT“ + zufälligem Code (`src/gateway/live-image-probe.ts`) + - Sendet es per `agent` `attachments: [{ mimeType: "image/png", content: "" }]` + - Das Gateway parst Anhänge in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Der eingebettete Agent leitet eine multimodale Benutzernachricht an das Modell weiter + - Assertion: Die Antwort enthält `cat` + den Code (OCR-Toleranz: kleine Fehler sind erlaubt) -Tipp: Um zu sehen, was Sie auf Ihrem Rechner testen können (und die exakten IDs `provider/model`), führen Sie aus: +Tipp: Um zu sehen, was Sie auf Ihrer Maschine testen können (und die genauen `provider/model`-IDs), führen Sie Folgendes aus: ```bash openclaw models list @@ -264,22 +263,22 @@ openclaw models list --json - Test: `src/gateway/gateway-cli-backend.live.test.ts` - Ziel: die Gateway+Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne Ihre Standardkonfiguration anzufassen. -- Standards für backend-spezifischen Smoke liegen zusammen mit der `cli-backend.ts`-Definition der besitzenden Extension. +- Backend-spezifische Smoke-Standardwerte liegen mit der Definition `cli-backend.ts` der besitzenden Erweiterung vor. - Aktivierung: - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Standardwerte: - Standard-Provider/-Modell: `claude-cli/claude-sonnet-4-6` - - Befehls-/Arg-/Bildverhalten stammt aus den Metadaten des besitzenden CLI-Backend-Plugins. -- Overrides (optional): + - Befehl/Argumente/Bildverhalten stammen aus den Metadaten des besitzenden CLI-Backend-Plugins. +- Überschreibungen (optional): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, um einen echten Bildanhang zu senden (Pfade werden in den Prompt eingefügt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, um Bilddateipfade als CLI-Argumente statt per Prompt-Injektion zu übergeben. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, um Bilddateipfade statt per Prompt-Injektion als CLI-Argumente zu übergeben. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oder `"list"`), um zu steuern, wie Bildargumente übergeben werden, wenn `IMAGE_ARG` gesetzt ist. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, um eine zweite Runde zu senden und den Resume-Flow zu validieren. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, um die standardmäßige Kontinuitätsprobe derselben Sitzung beim Wechsel Claude Sonnet -> Opus zu deaktivieren (auf `1` setzen, um sie zu erzwingen, wenn das gewählte Modell ein Wechselziel unterstützt). + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, um einen zweiten Turn zu senden und den Resume-Flow zu validieren. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, um die standardmäßige Kontinuitätssonde Claude Sonnet -> Opus innerhalb derselben Sitzung zu deaktivieren (setzen Sie `1`, um sie zu erzwingen, wenn das ausgewählte Modell ein Wechselziel unterstützt). Beispiel: @@ -306,19 +305,19 @@ pnpm test:docker:live-cli-backend:gemini Hinweise: - Der Docker-Runner befindet sich unter `scripts/test-live-cli-backend-docker.sh`. -- Er führt den Live-CLI-Backend-Smoke innerhalb des Repo-Docker-Images als nicht-root Benutzer `node` aus. -- Er löst CLI-Smoke-Metadaten aus der besitzenden Extension auf und installiert dann das passende Linux-CLI-Paket (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`) in ein gecachtes beschreibbares Präfix unter `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (Standard: `~/.cache/openclaw/docker-cli-tools`). -- Der Live-CLI-Backend-Smoke testet jetzt denselben End-to-End-Flow für Claude, Codex und Gemini: Text-Runde, Bildklassifizierungsrunde, dann MCP-Tool-Aufruf `cron`, geprüft über die Gateway-CLI. -- Claudes Standard-Smoke patcht außerdem die Sitzung von Sonnet auf Opus und prüft, dass sich die fortgesetzte Sitzung weiterhin eine frühere Notiz merkt. +- Er führt den Live-CLI-Backend-Smoke innerhalb des Repo-Docker-Images als Nicht-Root-Benutzer `node` aus. +- Er löst CLI-Smoke-Metadaten aus der besitzenden Erweiterung auf und installiert anschließend das passende Linux-CLI-Paket (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`) in ein zwischengespeichertes beschreibbares Präfix unter `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (Standard: `~/.cache/openclaw/docker-cli-tools`). +- Der Live-CLI-Backend-Smoke testet jetzt denselben End-to-End-Flow für Claude, Codex und Gemini: Text-Turn, Bildklassifizierungs-Turn und anschließend ein MCP-`cron`-Tool-Call, der über die Gateway-CLI verifiziert wird. +- Der standardmäßige Claude-Smoke patcht außerdem die Sitzung von Sonnet auf Opus und verifiziert, dass die fortgesetzte Sitzung sich weiterhin an eine frühere Notiz erinnert. ## Live: ACP-Bind-Smoke (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Ziel: den realen ACP-Konversations-Bind-Flow mit einem Live-ACP-Agenten validieren: +- Ziel: den echten ACP-Conversational-Bind-Flow mit einem Live-ACP-Agenten validieren: - `/acp spawn --bind here` senden - - eine synthetische Nachrichtenkanal-Konversation direkt binden - - ein normales Follow-up in genau derselben Konversation senden - - prüfen, dass das Follow-up im gebundenen ACP-Sitzungstranskript landet + - eine synthetische Message-Channel-Konversation direkt binden + - auf derselben Konversation ein normales Follow-up senden + - verifizieren, dass das Follow-up im gebundenen ACP-Sitzungstranskript landet - Aktivierung: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` @@ -327,15 +326,15 @@ Hinweise: - ACP-Agent für direktes `pnpm test:live ...`: `claude` - Synthetischer Kanal: Slack-DM-ähnlicher Konversationskontext - ACP-Backend: `acpx` -- Overrides: +- Überschreibungen: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Hinweise: - - Diese Lane verwendet die Gateway-Oberfläche `chat.send` mit admin-only Feldern für synthetische Ursprungspfade, damit Tests Nachrichtenkanal-Kontext anhängen können, ohne vorzugeben, extern zuzustellen. - - Wenn `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nicht gesetzt ist, verwendet der Test das eingebaute Agent-Registry des eingebetteten `acpx`-Plugins für den ausgewählten ACP-Harness-Agenten. + - Diese Lane verwendet die Gateway-Oberfläche `chat.send` mit nur für Administratoren bestimmten synthetischen Feldern der Ausgangsroute, damit Tests Message-Channel-Kontext anhängen können, ohne vorzugeben, extern zuzustellen. + - Wenn `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nicht gesetzt ist, verwendet der Test die integrierte Agent-Registry des eingebetteten `acpx`-Plugins für den ausgewählten ACP-Harness-Agenten. Beispiel: @@ -364,12 +363,12 @@ Docker-Hinweise: - Der Docker-Runner befindet sich unter `scripts/test-live-acp-bind-docker.sh`. - Standardmäßig führt er den ACP-Bind-Smoke nacheinander gegen alle unterstützten Live-CLI-Agenten aus: `claude`, `codex`, dann `gemini`. - Verwenden Sie `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oder `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, um die Matrix einzugrenzen. -- Er lädt `~/.profile`, stellt das passende CLI-Authentifizierungsmaterial in den Container bereit, installiert `acpx` in ein beschreibbares npm-Präfix und installiert dann die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`), falls sie fehlt. -- Innerhalb von Docker setzt der Runner `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, damit `acpx` Provider-Umgebungsvariablen aus dem geladenen Profil für die untergeordnete Harness-CLI verfügbar hält. +- Er sourct `~/.profile`, stellt das passende CLI-Auth-Material in den Container bereit, installiert `acpx` in ein beschreibbares npm-Präfix und installiert dann die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`), falls sie fehlt. +- Innerhalb von Docker setzt der Runner `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, damit `acpx` die Provider-Umgebungsvariablen aus dem gesourcten Profil für die untergeordnete Harness-CLI verfügbar hält. ### Empfohlene Live-Rezepte -Schmale, explizite Allowlists sind am schnellsten und am wenigsten fehleranfällig: +Schmale, explizite Allowlists sind am schnellsten und am wenigsten störanfällig: - Einzelnes Modell, direkt (ohne Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` @@ -380,31 +379,31 @@ Schmale, explizite Allowlists sind am schnellsten und am wenigsten fehleranfäll - Tool-Calling über mehrere Provider hinweg: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Fokus auf Google (Gemini-API-Schlüssel + Antigravity): +- Google-Fokus (Gemini-API-Schlüssel + Antigravity): - Gemini (API-Schlüssel): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Hinweise: - `google/...` verwendet die Gemini-API (API-Schlüssel). -- `google-antigravity/...` verwendet die Antigravity-OAuth-Bridge (Cloud-Code-Assist-ähnlicher Agent-Endpunkt). -- `google-gemini-cli/...` verwendet die lokale Gemini-CLI auf Ihrem Rechner (separate Authentifizierung + Tooling-Eigenheiten). +- `google-antigravity/...` verwendet die Antigravity-OAuth-Bridge (agentenendpunkt im Stil von Cloud Code Assist). +- `google-gemini-cli/...` verwendet die lokale Gemini-CLI auf Ihrem Rechner (separate Auth + Tooling-Besonderheiten). - Gemini-API vs. Gemini-CLI: - - API: OpenClaw ruft Googles gehostete Gemini-API über HTTP auf (API-Schlüssel / Profil-Authentifizierung); das ist in der Regel das, was Nutzer mit „Gemini“ meinen. - - CLI: OpenClaw führt lokal ein `gemini`-Binary aus; es hat eine eigene Authentifizierung und kann sich anders verhalten (Streaming/Tool-Support/Versionsabweichungen). + - API: OpenClaw ruft die gehostete Gemini-API von Google über HTTP auf (API-Schlüssel / Profil-Auth); das ist meist gemeint, wenn Nutzer von „Gemini“ sprechen. + - CLI: OpenClaw ruft eine lokale `gemini`-Binärdatei per Shell auf; sie hat ihre eigene Auth und kann sich anders verhalten (Streaming/Tool-Support/Versionsabweichung). ## Live: Modellmatrix (was wir abdecken) -Es gibt keine feste „CI-Modellliste“ (Live ist opt-in), aber dies sind die **empfohlenen** Modelle, die regelmäßig auf einem Entwicklerrechner mit Schlüsseln abgedeckt werden sollten. +Es gibt keine feste „CI-Modellliste“ (Live ist Opt-in), aber dies sind die **empfohlenen** Modelle, die auf einem Entwicklungsrechner mit Schlüsseln regelmäßig abgedeckt werden sollten. -### Moderner Smoke-Satz (Tool-Calling + Bild) +### Modernes Smoke-Set (Tool-Calling + Bild) -Das ist der Lauf für die „gängigen Modelle“, der funktionsfähig bleiben soll: +Dies ist der Lauf für die „üblichen Modelle“, den wir funktionsfähig halten wollen: - OpenAI (nicht Codex): `openai/gpt-5.4` (optional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (oder `anthropic/claude-sonnet-4-6`) -- Google (Gemini-API): `google/gemini-3.1-pro-preview` und `google/gemini-3-flash-preview` (ältere Gemini-2.x-Modelle vermeiden) +- Google (Gemini API): `google/gemini-3.1-pro-preview` und `google/gemini-3-flash-preview` (ältere Gemini-2.x-Modelle vermeiden) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` und `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` @@ -425,41 +424,41 @@ Wählen Sie mindestens eines pro Provider-Familie: Optionale zusätzliche Abdeckung (nice to have): - xAI: `xai/grok-4` (oder die neueste verfügbare Version) -- Mistral: `mistral/`… (wählen Sie ein aktiviertes Modell mit „tools“-Fähigkeit) +- Mistral: `mistral/`… (wählen Sie ein „tools“-fähiges Modell, das Sie aktiviert haben) - Cerebras: `cerebras/`… (wenn Sie Zugriff haben) - LM Studio: `lmstudio/`… (lokal; Tool-Calling hängt vom API-Modus ab) ### Vision: Bild senden (Anhang → multimodale Nachricht) -Nehmen Sie mindestens ein bildfähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` auf (Claude/Gemini/OpenAI-Varianten mit Vision-Unterstützung usw.), um die Bild-Probe auszuführen. +Nehmen Sie mindestens ein bildfähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` auf (Claude-/Gemini-/OpenAI-Varianten mit Vision-Unterstützung usw.), um die Bildsonde zu testen. ### Aggregatoren / alternative Gateways -Wenn Sie Schlüssel aktiviert haben, unterstützen wir auch Tests über: +Wenn Sie aktivierte Schlüssel haben, unterstützen wir auch Tests über Folgendes: -- OpenRouter: `openrouter/...` (Hunderte Modelle; verwenden Sie `openclaw models scan`, um Kandidaten mit Tool- + Bild-Fähigkeit zu finden) -- OpenCode: `opencode/...` für Zen und `opencode-go/...` für Go (Authentifizierung über `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (Hunderte Modelle; verwenden Sie `openclaw models scan`, um geeignete Kandidaten mit Tool- und Bildunterstützung zu finden) +- OpenCode: `opencode/...` für Zen und `opencode-go/...` für Go (Auth über `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Weitere Provider, die Sie in die Live-Matrix aufnehmen können (wenn Sie Zugangsdaten/Konfiguration haben): +Weitere Provider, die Sie in die Live-Matrix aufnehmen können (wenn Sie Anmeldedaten/Konfiguration haben): - Integriert: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` - Über `models.providers` (benutzerdefinierte Endpunkte): `minimax` (Cloud/API) sowie jeder OpenAI-/Anthropic-kompatible Proxy (LM Studio, vLLM, LiteLLM usw.) -Tipp: Versuchen Sie nicht, „alle Modelle“ in der Dokumentation fest zu codieren. Die maßgebliche Liste ist alles, was `discoverModels(...)` auf Ihrem Rechner zurückgibt + alle verfügbaren Schlüssel. +Tipp: Versuchen Sie nicht, „alle Modelle“ in der Dokumentation fest zu codieren. Die maßgebliche Liste ist das, was `discoverModels(...)` auf Ihrer Maschine zurückgibt + die verfügbaren Schlüssel. -## Zugangsdaten (niemals committen) +## Anmeldedaten (niemals committen) -Live-Tests finden Zugangsdaten genauso wie die CLI. Praktische Konsequenzen: +Live-Tests erkennen Anmeldedaten auf dieselbe Weise wie die CLI. Praktische Auswirkungen: - Wenn die CLI funktioniert, sollten Live-Tests dieselben Schlüssel finden. -- Wenn ein Live-Test „keine Zugangsdaten“ meldet, debuggen Sie genauso, wie Sie `openclaw models list` / Modellauswahl debuggen würden. +- Wenn ein Live-Test „keine Anmeldedaten“ meldet, debuggen Sie auf dieselbe Weise wie bei `openclaw models list` / Modellauswahl. -- Authentifizierungsprofile pro Agent: `~/.openclaw/agents//agent/auth-profiles.json` (das bedeutet in den Live-Tests „Profilschlüssel“) +- Auth-Profile pro Agent: `~/.openclaw/agents//agent/auth-profiles.json` (das ist die Bedeutung von „Profilschlüsseln“ in den Live-Tests) - Konfiguration: `~/.openclaw/openclaw.json` (oder `OPENCLAW_CONFIG_PATH`) -- Veraltetes State-Verzeichnis: `~/.openclaw/credentials/` (wird bei lokalen Live-Homes in das vorbereitete Test-Home kopiert, wenn vorhanden, ist aber nicht der Hauptspeicher für Profilschlüssel) -- Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, pro Agent die `auth-profiles.json`-Dateien, veraltete `credentials/` und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; vorbereitete Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfad-Overrides für `agents.*.workspace` / `agentDir` werden entfernt, damit Probes nicht in Ihrem echten Host-Workspace landen. +- Legacy-State-Verzeichnis: `~/.openclaw/credentials/` (wird, wenn vorhanden, in das bereitgestellte Live-Home kopiert, ist aber nicht der Hauptspeicher für Profilschlüssel) +- Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, `auth-profiles.json`-Dateien pro Agent, Legacy-`credentials/` und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; bereitgestellte Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfadüberschreibungen `agents.*.workspace` / `agentDir` werden entfernt, damit Sonden nicht in Ihrem echten Host-Workspace laufen. -Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrer `~/.profile` exportiert), führen Sie lokale Tests nach `source ~/.profile` aus oder verwenden Sie die Docker-Runner unten (diese können `~/.profile` in den Container mounten). +Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrem `~/.profile` exportiert), führen Sie lokale Tests nach `source ~/.profile` aus oder verwenden Sie die Docker-Runner unten (sie können `~/.profile` in den Container mounten). ## Deepgram live (Audiotranskription) @@ -470,14 +469,14 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrer `~/.profile - Test: `src/agents/byteplus.live.test.ts` - Aktivierung: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Optionales Modell-Override: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Optionale Modellüberschreibung: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## ComfyUI-Workflow-Medien live - Test: `extensions/comfy/comfy.live.test.ts` - Aktivierung: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Umfang: - - Testet die gebündelten comfy-Pfade für Bild, Video und `music_generate` + - Testet die gebündelten Pfade für Bild, Video und `music_generate` von comfy - Überspringt jede Fähigkeit, sofern `models.providers.comfy.` nicht konfiguriert ist - Nützlich nach Änderungen an comfy-Workflow-Übermittlung, Polling, Downloads oder Plugin-Registrierung @@ -487,24 +486,24 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrer `~/.profile - Befehl: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Umfang: - - Zählt jedes registrierte Provider-Plugin für Bildgenerierung auf - - Lädt fehlende Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`), bevor Probes ausgeführt werden - - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Authentifizierungsprofilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Zugangsdaten nicht maskieren - - Überspringt Provider ohne nutzbare Authentifizierung/Profil/Modell + - Zählt jedes registrierte Plugin für Bildgenerierungs-Provider auf + - Lädt vor der Sonde fehlende Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Überspringt Provider ohne nutzbare Auth/Profil/Modell - Führt die Standardvarianten der Bildgenerierung über die gemeinsame Runtime-Fähigkeit aus: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Derzeit abgedeckte gebündelte Provider: +- Aktuell abgedeckte gebündelte Provider: - `openai` - `google` - Optionale Eingrenzung: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Optionales Authentifizierungsverhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung aus dem Profilspeicher zu erzwingen und nur-env-Overrides zu ignorieren +- Optionales Auth-Verhalten: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profil-Store zu erzwingen und reine Env-Überschreibungen zu ignorieren ## Musikgenerierung live @@ -512,11 +511,11 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrer `~/.profile - Aktivierung: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Umfang: - - Testet den gemeinsamen gebündelten Provider-Pfad für Musikgenerierung + - Testet den gemeinsam gebündelten Pfad für Musikgenerierungs-Provider - Deckt derzeit Google und MiniMax ab - - Lädt Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`), bevor Probes ausgeführt werden - - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Authentifizierungsprofilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Zugangsdaten nicht maskieren - - Überspringt Provider ohne nutzbare Authentifizierung/Profil/Modell + - Lädt vor der Sonde Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Überspringt Provider ohne nutzbare Auth/Profil/Modell - Führt beide deklarierten Runtime-Modi aus, sofern verfügbar: - `generate` mit Eingabe nur per Prompt - `edit`, wenn der Provider `capabilities.edit.enabled` deklariert @@ -527,8 +526,8 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrer `~/.profile - Optionale Eingrenzung: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Optionales Authentifizierungsverhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung aus dem Profilspeicher zu erzwingen und nur-env-Overrides zu ignorieren +- Optionales Auth-Verhalten: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profil-Store zu erzwingen und reine Env-Überschreibungen zu ignorieren ## Videogenerierung live @@ -536,39 +535,39 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrer `~/.profile - Aktivierung: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Umfang: - - Testet den gemeinsamen gebündelten Provider-Pfad für Videogenerierung - - Lädt Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`), bevor Probes ausgeführt werden - - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Authentifizierungsprofilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Zugangsdaten nicht maskieren - - Überspringt Provider ohne nutzbare Authentifizierung/Profil/Modell + - Testet den gemeinsam gebündelten Pfad für Videogenerierungs-Provider + - Lädt vor der Sonde Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, sodass veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Überspringt Provider ohne nutzbare Auth/Profil/Modell - Führt beide deklarierten Runtime-Modi aus, sofern verfügbar: - `generate` mit Eingabe nur per Prompt - - `imageToVideo`, wenn der Provider `capabilities.imageToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep Puffer-gestützte lokale Bildeingabe akzeptiert - - `videoToVideo`, wenn der Provider `capabilities.videoToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep Puffer-gestützte lokale Videoeingabe akzeptiert + - `imageToVideo`, wenn der Provider `capabilities.imageToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep lokale Bild-Eingaben auf Buffer-Basis akzeptiert + - `videoToVideo`, wenn der Provider `capabilities.videoToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep lokale Video-Eingaben auf Buffer-Basis akzeptiert - Aktuell deklarierte, aber im gemeinsamen Sweep übersprungene `imageToVideo`-Provider: - - `vydra`, weil das gebündelte `veo3` nur Text unterstützt und das gebündelte `kling` eine entfernte Bild-URL erfordert + - `vydra`, weil gebündeltes `veo3` nur Text unterstützt und gebündeltes `kling` eine Remote-Bild-URL erfordert - Provider-spezifische Vydra-Abdeckung: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - diese Datei führt `veo3` Text-zu-Video plus eine `kling`-Lane aus, die standardmäßig eine Fixture mit entfernter Bild-URL verwendet + - diese Datei führt `veo3` für Text-zu-Video sowie eine `kling`-Lane aus, die standardmäßig eine Fixture mit Remote-Bild-URL verwendet - Aktuelle `videoToVideo`-Live-Abdeckung: - nur `runway`, wenn das ausgewählte Modell `runway/gen4_aleph` ist - Aktuell deklarierte, aber im gemeinsamen Sweep übersprungene `videoToVideo`-Provider: - - `alibaba`, `qwen`, `xai`, weil diese Pfade derzeit entfernte Referenz-URLs `http(s)` / MP4 erfordern - - `google`, weil die aktuelle gemeinsame Gemini-/Veo-Lane lokale puffergestützte Eingabe verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird - - `openai`, weil die aktuelle gemeinsame Lane keine Garantien für org-spezifischen Zugriff auf Video-Inpaint/Remix hat + - `alibaba`, `qwen`, `xai`, weil diese Pfade derzeit Remote-Referenz-URLs `http(s)` / MP4 erfordern + - `google`, weil die aktuelle gemeinsame Gemini/Veo-Lane lokale bufferbasierte Eingaben verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird + - `openai`, weil der aktuellen gemeinsamen Lane keine garantierten organisationsspezifischen Zugriffe auf Video-Inpaint/Remix vorliegen - Optionale Eingrenzung: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- Optionales Authentifizierungsverhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Authentifizierung aus dem Profilspeicher zu erzwingen und nur-env-Overrides zu ignorieren +- Optionales Auth-Verhalten: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profil-Store zu erzwingen und reine Env-Überschreibungen zu ignorieren ## Media-Live-Harness - Befehl: `pnpm test:live:media` - Zweck: - - Führt die gemeinsamen Live-Suiten für Bild, Musik und Video über einen repo-nativen Entry-Point aus + - Führt die gemeinsamen Live-Suiten für Bild, Musik und Video über einen repo-nativen Einstiegspunkt aus - Lädt fehlende Provider-Umgebungsvariablen automatisch aus `~/.profile` - - Grenzt standardmäßig jede Suite automatisch auf Provider ein, die aktuell nutzbare Authentifizierung haben - - Verwendet `scripts/test-live.mjs` wieder, sodass Heartbeat- und Quiet-Mode-Verhalten konsistent bleiben + - Grenzt standardmäßig jede Suite automatisch auf Provider ein, für die derzeit nutzbare Auth vorhanden ist + - Verwendet `scripts/test-live.mjs` erneut, sodass Heartbeat- und Quiet-Mode-Verhalten konsistent bleiben - Beispiele: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -577,20 +576,20 @@ Wenn Sie sich auf Env-Schlüssel verlassen möchten (z. B. aus Ihrer `~/.profile ## Docker-Runner (optionale „funktioniert unter Linux“-Prüfungen) -Diese Docker-Runner teilen sich in zwei Gruppen: +Diese Docker-Runner teilen sich in zwei Kategorien: -- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur ihre jeweilige Live-Datei für Profilschlüssel im Repo-Docker-Image aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`), mounten dabei Ihr lokales Konfigurationsverzeichnis und Ihren Workspace (und laden `~/.profile`, falls gemountet). Die passenden lokalen Entry-Points sind `test:live:models-profiles` und `test:live:gateway-profiles`. -- Docker-Live-Runner verwenden standardmäßig ein kleineres Smoke-Limit, damit ein vollständiger Docker-Sweep praktikabel bleibt: +- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur die jeweils passende Live-Datei für Profilschlüssel innerhalb des Repo-Docker-Images aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`), mounten dabei Ihr lokales Konfigurationsverzeichnis und Ihren Workspace (und sourcen `~/.profile`, falls gemountet). Die passenden lokalen Einstiegspunkte sind `test:live:models-profiles` und `test:live:gateway-profiles`. +- Docker-Live-Runner verwenden standardmäßig eine kleinere Smoke-Obergrenze, damit ein vollständiger Docker-Sweep praktikabel bleibt: `test:docker:live-models` verwendet standardmäßig `OPENCLAW_LIVE_MAX_MODELS=12`, und `test:docker:live-gateway` verwendet standardmäßig `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` und `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Überschreiben Sie diese Env-Variablen, wenn Sie ausdrücklich den größeren vollständigen Scan möchten. -- `test:docker:all` baut das Live-Docker-Image einmal über `test:docker:live-build` und verwendet es dann für die beiden Docker-Lanes für Live erneut. -- Container-Smoke-Runner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` und `test:docker:plugins` starten einen oder mehrere echte Container und prüfen Integrationspfade höherer Ebene. +- `test:docker:all` baut das Live-Docker-Image einmal über `test:docker:live-build` und verwendet es dann für die beiden Docker-Live-Lanes erneut. +- Container-Smoke-Runner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` und `test:docker:plugins` starten einen oder mehrere echte Container und verifizieren Integrationspfade auf höherer Ebene. -Die Docker-Runner für Live-Modelle mounten außerdem nur die benötigten CLI-Auth-Homes (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit externe CLI-OAuth Tokens aktualisieren kann, ohne den Auth-Store auf dem Host zu verändern: +Die Docker-Runner für Live-Modelle mounten außerdem nur die benötigten CLI-Auth-Homes (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit OAuth externer CLI-Tools Tokens aktualisieren kann, ohne den Auth-Store des Hosts zu verändern: - Direkte Modelle: `pnpm test:docker:live-models` (Skript: `scripts/test-live-models-docker.sh`) - ACP-Bind-Smoke: `pnpm test:docker:live-acp-bind` (Skript: `scripts/test-live-acp-bind-docker.sh`) @@ -598,103 +597,101 @@ Die Docker-Runner für Live-Modelle mounten außerdem nur die benötigten CLI-Au - Gateway + Dev-Agent: `pnpm test:docker:live-gateway` (Skript: `scripts/test-live-gateway-models-docker.sh`) - Open-WebUI-Live-Smoke: `pnpm test:docker:openwebui` (Skript: `scripts/e2e/openwebui-docker.sh`) - Onboarding-Assistent (TTY, vollständiges Scaffolding): `pnpm test:docker:onboard` (Skript: `scripts/e2e/onboard-docker.sh`) -- Gateway-Netzwerk (zwei Container, WS-Auth + Health): `pnpm test:docker:gateway-network` (Skript: `scripts/e2e/gateway-network-docker.sh`) -- MCP-Kanal-Bridge (vorbereiteter Gateway + stdio-Bridge + roher Claude-Benachrichtigungsframe-Smoke): `pnpm test:docker:mcp-channels` (Skript: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (Installations-Smoke + Alias `/plugin` + Claude-Bundle-Neustart-Semantik): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) +- Gateway-Networking (zwei Container, WS-Auth + Health): `pnpm test:docker:gateway-network` (Skript: `scripts/e2e/gateway-network-docker.sh`) +- MCP-Kanal-Bridge (mit Seeds versehenes Gateway + stdio-Bridge + roher Claude-Benachrichtigungs-Frame-Smoke): `pnpm test:docker:mcp-channels` (Skript: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (Installations-Smoke + `/plugin`-Alias + Neustartsemantik des Claude-Bundles): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) -Die Docker-Runner für Live-Modelle mounten außerdem den aktuellen Checkout schreibgeschützt und -stellen ihn in einem temporären Arbeitsverzeichnis innerhalb des Containers bereit. Dadurch bleibt das Runtime- -Image schlank, während Vitest weiterhin gegen Ihren exakten lokalen Quellstand/Ihre Konfiguration läuft. -Der Bereitstellungsschritt überspringt große lokale Caches und App-Build-Ausgaben wie -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` und app-lokale `.build`- oder -Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht minutenlang -maschinenabhängige Artefakte kopieren. -Sie setzen außerdem `OPENCLAW_SKIP_CHANNELS=1`, damit Gateway-Live-Probes im Container -keine echten Kanal-Worker für Telegram/Discord/etc. starten. -`test:docker:live-models` führt weiterhin `pnpm test:live` aus; geben Sie daher -auch `OPENCLAW_LIVE_GATEWAY_*` weiter, wenn Sie Gateway-Live-Abdeckung in dieser Docker-Lane -eingrenzen oder ausschließen möchten. -`test:docker:openwebui` ist ein Kompatibilitäts-Smoke auf höherer Ebene: Es startet einen -OpenClaw-Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, -startet einen fest angepinnten Open-WebUI-Container gegen dieses Gateway, meldet sich über -Open WebUI an, prüft, dass `/api/models` `openclaw/default` bereitstellt, und sendet dann eine +Die Docker-Runner für Live-Modelle mounten den aktuellen Checkout außerdem schreibgeschützt und stellen ihn in ein temporäres Workdir innerhalb des Containers bereit. Dadurch bleibt das Runtime-Image schlank, während Vitest trotzdem gegen Ihren exakten lokalen Source-/Config-Stand ausgeführt wird. +Der Bereitstellungsschritt überspringt große lokale Caches und Build-Ausgaben von Apps wie +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` sowie app-lokale `.build`- oder +Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht Minuten damit verbringen, +maschinenspezifische Artefakte zu kopieren. +Außerdem setzen sie `OPENCLAW_SKIP_CHANNELS=1`, sodass Live-Sonden des Gateways keine +echten Kanal-Worker für Telegram/Discord/etc. innerhalb des Containers starten. +`test:docker:live-models` führt weiterhin `pnpm test:live` aus, daher müssen Sie +`OPENCLAW_LIVE_GATEWAY_*` ebenfalls durchreichen, wenn Sie die Gateway-Live-Abdeckung +in dieser Docker-Lane eingrenzen oder ausschließen möchten. +`test:docker:openwebui` ist ein höherstufiger Kompatibilitäts-Smoke: Er startet einen +Gateway-Container von OpenClaw mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, +startet einen angehefteten Open-WebUI-Container gegen dieses Gateway, meldet sich über +Open WebUI an, verifiziert, dass `/api/models` `openclaw/default` bereitstellt, und sendet dann eine echte Chat-Anfrage über den Proxy `/api/chat/completions` von Open WebUI. -Der erste Lauf kann merklich langsamer sein, weil Docker möglicherweise erst das -Open-WebUI-Image ziehen muss und Open WebUI sein eigenes Cold-Start-Setup abschließen muss. +Der erste Lauf kann merklich langsamer sein, weil Docker möglicherweise das +Open-WebUI-Image laden muss und Open WebUI möglicherweise den eigenen Kaltstart abschließen muss. Diese Lane erwartet einen nutzbaren Live-Modellschlüssel, und `OPENCLAW_PROFILE_FILE` -(`~/.profile` standardmäßig) ist der primäre Weg, ihn in Docker-Läufen bereitzustellen. -Erfolgreiche Läufe geben eine kleine JSON-Payload aus wie `{ "ok": true, "model": -"openclaw/default", ... }`. -`test:docker:mcp-channels` ist bewusst deterministisch und benötigt kein -echtes Telegram-, Discord- oder iMessage-Konto. Es startet einen vorbereiteten Gateway- -Container, startet einen zweiten Container, der `openclaw mcp serve` ausführt, und -prüft dann geroutete Konversationserkennung, Transkript-Lesezugriffe, Anhangsmetadaten, -das Verhalten der Live-Event-Queue, ausgehendes Send-Routing sowie Claude-ähnliche Kanal- + -Berechtigungsbenachrichtigungen über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung -untersucht die rohen stdio-MCP-Frames direkt, sodass der Smoke validiert, was die -Bridge tatsächlich ausgibt, und nicht nur das, was ein bestimmtes Client-SDK zufällig sichtbar macht. +(standardmäßig `~/.profile`) ist der primäre Weg, ihn in Docker-Läufen bereitzustellen. +Erfolgreiche Läufe geben eine kleine JSON-Nutzlast wie `{ "ok": true, "model": +"openclaw/default", ... }` aus. +`test:docker:mcp-channels` ist absichtlich deterministisch und benötigt kein +echtes Telegram-, Discord- oder iMessage-Konto. Es startet einen Gateway-Container +mit Seeds, startet einen zweiten Container, der `openclaw mcp serve` erzeugt, und +verifiziert dann geroutete Konversationserkennung, Transkriptlesungen, Metadaten zu Anhängen, +Verhalten der Live-Event-Warteschlange, Routing ausgehender Sendungen sowie Benachrichtigungen +im Claude-Stil für Kanal + Berechtigungen über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung +untersucht die rohen stdio-MCP-Frames direkt, sodass der Smoke prüft, was die +Bridge tatsächlich ausgibt, und nicht nur, was ein bestimmtes Client-SDK zufällig sichtbar macht. Manueller ACP-Smoke für Plain-Language-Threads (nicht CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Behalten Sie dieses Skript für Regressions-/Debugging-Workflows bei. Es könnte für die Validierung des ACP-Thread-Routings erneut gebraucht werden, also nicht löschen. +- Behalten Sie dieses Skript für Regression-/Debug-Workflows. Es kann erneut für die Validierung des ACP-Thread-Routings benötigt werden, daher nicht löschen. Nützliche Env-Variablen: - `OPENCLAW_CONFIG_DIR=...` (Standard: `~/.openclaw`), gemountet nach `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (Standard: `~/.openclaw/workspace`), gemountet nach `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`), gemountet nach `/home/node/.profile` und vor dem Ausführen der Tests geladen -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`), gemountet nach `/home/node/.npm-global` für gecachte CLI-Installationen innerhalb von Docker -- Externe CLI-Auth-Verzeichnisse/-Dateien unter `$HOME` werden schreibgeschützt unter `/host-auth...` gemountet und dann vor dem Start der Tests nach `/home/node/...` kopiert +- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`), gemountet nach `/home/node/.profile` und vor dem Ausführen der Tests gesourct +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`), gemountet nach `/home/node/.npm-global` für zwischengespeicherte CLI-Installationen innerhalb von Docker +- Externe CLI-Auth-Verzeichnisse/-Dateien unter `$HOME` werden schreibgeschützt unter `/host-auth...` gemountet und dann vor Teststart nach `/home/node/...` kopiert - Standardverzeichnisse: `.minimax` - Standarddateien: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Eingegrenzte Provider-Läufe mounten nur die benötigten Verzeichnisse/Dateien, abgeleitet aus `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Manuell überschreiben mit `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oder einer Komma-Liste wie `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Eingegrenzte Provider-Läufe mounten nur die benötigten Verzeichnisse/Dateien, die aus `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` abgeleitet werden + - Manuelle Überschreibung mit `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oder einer Kommaliste wie `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, um den Lauf einzugrenzen - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, um Provider im Container zu filtern -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Zugangsdaten aus dem Profilspeicher kommen (nicht aus Env) +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Anmeldedaten aus dem Profil-Store kommen (nicht aus Env) - `OPENCLAW_OPENWEBUI_MODEL=...`, um das vom Gateway für den Open-WebUI-Smoke bereitgestellte Modell auszuwählen -- `OPENCLAW_OPENWEBUI_PROMPT=...`, um den für den Open-WebUI-Smoke verwendeten Nonce-Prüf-Prompt zu überschreiben -- `OPENWEBUI_IMAGE=...`, um den angepinnten Open-WebUI-Image-Tag zu überschreiben +- `OPENCLAW_OPENWEBUI_PROMPT=...`, um den Prompt zur Nonce-Prüfung zu überschreiben, der vom Open-WebUI-Smoke verwendet wird +- `OPENWEBUI_IMAGE=...`, um den angehefteten Open-WebUI-Image-Tag zu überschreiben ## Dokumentations-Sanity -Führen Sie nach Dokumentationsänderungen Dokumentationsprüfungen aus: `pnpm check:docs`. -Führen Sie die vollständige Mintlify-Anchor-Validierung aus, wenn Sie auch In-Page-Heading-Prüfungen brauchen: `pnpm docs:check-links:anchors`. +Führen Sie nach Änderungen an der Dokumentation die Doku-Prüfungen aus: `pnpm check:docs`. +Führen Sie eine vollständige Mintlify-Anchor-Validierung aus, wenn Sie auch In-Page-Heading-Prüfungen benötigen: `pnpm docs:check-links:anchors`. ## Offline-Regression (CI-sicher) -Dies sind Regressionen für die „reale Pipeline“ ohne reale Provider: +Dies sind Regressionen mit „realer Pipeline“ ohne echte Provider: -- Gateway-Tool-Calling (Mock-OpenAI, echtes Gateway + Agent-Schleife): `src/gateway/gateway.test.ts` (Fall: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Gateway-Assistent (WS `wizard.start`/`wizard.next`, schreibt Konfiguration + Auth erzwungen): `src/gateway/gateway.test.ts` (Fall: "runs wizard over ws and writes auth token config") +- Gateway-Tool-Calling (mocked OpenAI, echtes Gateway + Agent-Schleife): `src/gateway/gateway.test.ts` (Fall: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway-Assistent (WS `wizard.start`/`wizard.next`, schreibt Konfiguration + erzwungene Auth): `src/gateway/gateway.test.ts` (Fall: "runs wizard over ws and writes auth token config") -## Evals zur Agent-Zuverlässigkeit (Skills) +## Evaluierungen der Agent-Zuverlässigkeit (Skills) -Wir haben bereits einige CI-sichere Tests, die sich wie „Evals zur Agent-Zuverlässigkeit“ verhalten: +Wir haben bereits einige CI-sichere Tests, die sich wie „Evaluierungen der Agent-Zuverlässigkeit“ verhalten: -- Mock-Tool-Calling durch das reale Gateway + die Agent-Schleife (`src/gateway/gateway.test.ts`). -- End-to-End-Assistenten-Flows, die Sitzungsverdrahtung und Konfigurationseffekte validieren (`src/gateway/gateway.test.ts`). +- Mock-Tool-Calling durch die echte Gateway + Agent-Schleife (`src/gateway/gateway.test.ts`). +- End-to-End-Assistenten-Flows, die Sitzungsverkabelung und Konfigurationseffekte validieren (`src/gateway/gateway.test.ts`). Was für Skills noch fehlt (siehe [Skills](/de/tools/skills)): -- **Entscheidungsverhalten:** Wenn Skills im Prompt aufgeführt sind, wählt der Agent dann den richtigen Skill (oder vermeidet irrelevante)? -- **Konformität:** Liest der Agent `SKILL.md` vor der Nutzung und befolgt erforderliche Schritte/Argumente? -- **Workflow-Verträge:** Mehrere Runden umfassende Szenarien, die Tool-Reihenfolge, Übernahme des Sitzungsverlaufs und Sandbox-Grenzen prüfen. +- **Entscheidungsfindung:** Wenn Skills im Prompt aufgeführt sind, wählt der Agent dann den richtigen Skill aus (oder vermeidet irrelevante)? +- **Compliance:** Liest der Agent vor der Verwendung `SKILL.md` und befolgt die erforderlichen Schritte/Argumente? +- **Workflow-Verträge:** Multi-Turn-Szenarien, die Tool-Reihenfolge, Mitnahme des Sitzungsverlaufs und Sandbox-Grenzen bestätigen. -Zukünftige Evals sollten zuerst deterministisch bleiben: +Zukünftige Evaluierungen sollten zuerst deterministisch bleiben: -- Ein Szenario-Runner mit Mock-Providern, um Tool-Aufrufe + Reihenfolge, Skill-Datei-Lesevorgänge und Sitzungsverdrahtung zu prüfen. -- Eine kleine Suite mit auf Skills fokussierten Szenarien (verwenden vs. vermeiden, Gating, Prompt-Injektion). -- Optionale Live-Evals (opt-in, env-gesteuert) erst, nachdem die CI-sichere Suite vorhanden ist. +- Ein Szenario-Runner mit Mock-Providern, um Tool-Aufrufe + Reihenfolge, Skill-Datei-Lesungen und Sitzungsverkabelung zu prüfen. +- Eine kleine Suite skillfokussierter Szenarien (verwenden vs. vermeiden, Gating, Prompt Injection). +- Optionale Live-Evaluierungen (Opt-in, per Env geregelt) erst, nachdem die CI-sichere Suite vorhanden ist. -## Vertragstests (Plugin- und Kanal-Shape) +## Vertragstests (Plugin- und Kanalform) -Vertragstests prüfen, dass jedes registrierte Plugin und jeder registrierte Kanal seinem -Schnittstellenvertrag entspricht. Sie iterieren über alle entdeckten Plugins und führen eine Suite aus -Form- und Verhaltensprüfungen aus. Die Standard-Unit-Lane `pnpm test` -überspringt diese gemeinsamen Nahtstellen- und Smoke-Dateien absichtlich; führen Sie die Vertragsbefehle explizit -aus, wenn Sie gemeinsame Kanal- oder Provider-Oberflächen ändern. +Vertragstests verifizieren, dass jedes registrierte Plugin und jeder Kanal seinem +Schnittstellenvertrag entspricht. Sie iterieren über alle erkannten Plugins und führen eine Suite aus +Form- und Verhaltensprüfungen aus. Die standardmäßige Unit-Lane `pnpm test` +überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien absichtlich; führen Sie die Vertragsbefehle +explizit aus, wenn Sie gemeinsame Kanal- oder Provider-Oberflächen ändern. ### Befehle @@ -704,55 +701,55 @@ aus, wenn Sie gemeinsame Kanal- oder Provider-Oberflächen ändern. ### Kanalverträge -Zu finden in `src/channels/plugins/contracts/*.contract.test.ts`: +Befinden sich in `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Grundlegende Plugin-Form (id, name, capabilities) -- **setup** - Vertrag des Setup-Assistenten -- **session-binding** - Verhalten bei Sitzungsbindung +- **plugin** - Grundform des Plugins (ID, Name, Fähigkeiten) +- **setup** - Vertragsform des Setup-Assistenten +- **session-binding** - Verhalten der Sitzungsbindung - **outbound-payload** - Struktur der Nachrichten-Payload - **inbound** - Verarbeitung eingehender Nachrichten -- **actions** - Kanal-Aktions-Handler -- **threading** - Behandlung von Thread-IDs -- **directory** - API für Verzeichnis/Roster -- **group-policy** - Durchsetzung von Gruppenrichtlinien +- **actions** - Handler für Kanalaktionen +- **threading** - Verarbeitung von Thread-IDs +- **directory** - Verzeichnis-/Roster-API +- **group-policy** - Durchsetzung der Gruppenrichtlinie -### Provider-Status-Verträge +### Provider-Statusverträge -Zu finden in `src/plugins/contracts/*.contract.test.ts`. +Befinden sich in `src/plugins/contracts/*.contract.test.ts`. -- **status** - Kanal-Status-Probes +- **status** - Statussonden für Kanäle - **registry** - Form der Plugin-Registry ### Provider-Verträge -Zu finden in `src/plugins/contracts/*.contract.test.ts`: +Befinden sich in `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Vertrag des Authentifizierungsflusses -- **auth-choice** - Authentifizierungswahl/-auswahl +- **auth** - Vertragsform des Auth-Flows +- **auth-choice** - Auth-Auswahl/Auswahlprozess - **catalog** - API des Modellkatalogs -- **discovery** - Plugin-Erkennung -- **loader** - Plugin-Laden -- **runtime** - Provider-Laufzeit +- **discovery** - Erkennung von Plugins +- **loader** - Laden von Plugins +- **runtime** - Provider-Runtime - **shape** - Plugin-Form/Schnittstelle - **wizard** - Setup-Assistent ### Wann ausführen -- Nach Änderungen an `plugin-sdk`-Exports oder Subpaths +- Nach Änderungen an `plugin-sdk`-Exports oder Subpfaden - Nach dem Hinzufügen oder Ändern eines Kanal- oder Provider-Plugins -- Nach dem Refactoring von Plugin-Registrierung oder -Erkennung +- Nach Refactorings der Plugin-Registrierung oder -Erkennung Vertragstests laufen in CI und erfordern keine echten API-Schlüssel. -## Regressionen hinzufügen (Hinweise) +## Regressionen hinzufügen (Leitlinien) -Wenn Sie ein in Live entdecktes Provider-/Modellproblem beheben: +Wenn Sie ein Provider-/Modellproblem beheben, das in Live entdeckt wurde: -- Fügen Sie nach Möglichkeit eine CI-sichere Regression hinzu (Mock-/Stub-Provider oder exakte Erfassung der Request-Shape-Transformation) -- Wenn das Problem inhärent nur live auftritt (Rate Limits, Authentifizierungsrichtlinien), halten Sie den Live-Test schmal und opt-in über Env-Variablen -- Zielen Sie bevorzugt auf die kleinste Ebene, die den Fehler erkennt: - - Bug bei Provider-Request-Konvertierung/-Replay → Test für direkte Modelle - - Bug in Gateway-Sitzung/Verlauf/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test -- Guardrail für SecretRef-Traversal: - - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet pro SecretRef-Klasse genau ein Beispielziel aus den Registry-Metadaten ab (`listSecretTargetRegistryEntries()`) und prüft dann, dass Traversal-Segment-Exec-IDs abgelehnt werden. - - Wenn Sie in `src/secrets/target-registry-data.ts` eine neue SecretRef-Zielfamilie mit `includeInPlan` hinzufügen, aktualisieren Sie `classifyTargetClass` in diesem Test. Der Test schlägt absichtlich bei nicht klassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden. +- Fügen Sie wenn möglich eine CI-sichere Regression hinzu (Mock/Stub des Providers oder Erfassen der exakten Transformation der Request-Form) +- Wenn das Problem von Natur aus nur live auftritt (Rate-Limits, Auth-Richtlinien), halten Sie den Live-Test schmal und aktivieren Sie ihn nur opt-in über Env-Variablen +- Zielen Sie vorzugsweise auf die kleinste Ebene, die den Fehler erkennt: + - Fehler bei Provider-Request-Konvertierung/-Replay → direkter Modelltest + - Fehler in Gateway-Sitzung/Verlauf/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test +- Schutzregel für SecretRef-Traversal: + - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet aus den Registry-Metadaten pro SecretRef-Klasse ein Beispielziel ab (`listSecretTargetRegistryEntries()`) und bestätigt dann, dass Traversal-Segment-Exec-IDs abgelehnt werden. + - Wenn Sie in `src/secrets/target-registry-data.ts` eine neue SecretRef-Zielfamilie `includeInPlan` hinzufügen, aktualisieren Sie `classifyTargetClass` in diesem Test. Der Test schlägt absichtlich bei nicht klassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden. diff --git a/docs/de/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md b/docs/de/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md deleted file mode 100644 index 29c6cdd88..000000000 --- a/docs/de/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md +++ /dev/null @@ -1,578 +0,0 @@ ---- -date: 2026-04-05T00:00:00Z -status: active -title: 'Refactor: plugin-sdk schrittweise zu einem echten Workspace-Paket machen' -type: refactor -x-i18n: - generated_at: "2026-04-07T06:16:24Z" - model: gpt-5.4 - provider: openai - source_hash: ea1ca41846363c506a0db6dbca746e840d7c71ca82bbfc5277af9e2ae7f6b070 - source_path: plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md - workflow: 15 ---- - -# Refactor: plugin-sdk schrittweise zu einem echten Workspace-Paket machen - -## Überblick - -Dieser Plan führt unter -`packages/plugin-sdk` ein echtes Workspace-Paket für das plugin-sdk ein und verwendet es, um für eine kleine erste Welle von Erweiterungen paketgrenzen mit Compiler-Durchsetzung zu aktivieren. Das Ziel ist, dass unzulässige relative -Importe unter normalem `tsc` für eine ausgewählte Gruppe gebündelter Provider- -Erweiterungen fehlschlagen, ohne eine repo-weite Migration oder eine riesige Merge-Konflikt- -Oberfläche zu erzwingen. - -Der zentrale inkrementelle Schritt besteht darin, zwei Modi eine Zeit lang parallel auszuführen: - -| Modus | Importform | Wer es verwendet | Durchsetzung | -| ----------- | ------------------------ | ------------------------------------ | -------------------------------------------- | -| Legacy-Modus | `openclaw/plugin-sdk/*` | alle bestehenden nicht aktivierten Erweiterungen | aktuelles permissives Verhalten bleibt bestehen | -| Opt-in-Modus | `@openclaw/plugin-sdk/*` | nur Erweiterungen der ersten Welle | paketlokales `rootDir` + Projekt-Referenzen | - -## Problemrahmen - -Das aktuelle Repo exportiert eine große öffentliche plugin-sdk-Oberfläche, ist aber kein echtes -Workspace-Paket. Stattdessen gilt: - -- `tsconfig.json` im Root mappt `openclaw/plugin-sdk/*` direkt auf - `src/plugin-sdk/*.ts` -- Erweiterungen, die nicht für das vorherige Experiment aktiviert wurden, teilen weiterhin dieses - globale Source-Alias-Verhalten -- Das Hinzufügen von `rootDir` funktioniert nur dann, wenn erlaubte SDK-Importe nicht mehr in rohe - Repo-Quellen aufgelöst werden - -Das bedeutet, dass das Repo die gewünschte Grenzrichtlinie beschreiben kann, TypeScript -sie aber für die meisten Erweiterungen nicht sauber durchsetzt. - -Gewünscht ist ein inkrementeller Pfad, der: - -- `plugin-sdk` real macht -- das SDK in Richtung eines Workspace-Pakets namens `@openclaw/plugin-sdk` bewegt -- im ersten PR nur etwa 10 Erweiterungen ändert -- den Rest des Erweiterungsbaums bis zur späteren Bereinigung im alten Schema belässt -- den Workflow mit `tsconfig.plugin-sdk.dts.json` + durch postinstall generierten Deklarationen als primären Mechanismus für den Rollout der ersten Welle vermeidet - -## Anforderungszuordnung - -- R1. Unter `packages/` ein echtes Workspace-Paket für das Plugin SDK erstellen. -- R2. Das neue Paket `@openclaw/plugin-sdk` nennen. -- R3. Dem neuen SDK-Paket ein eigenes `package.json` und `tsconfig.json` geben. -- R4. Während des Migrationsfensters Legacy-Importe `openclaw/plugin-sdk/*` für nicht aktivierte - Erweiterungen funktionsfähig halten. -- R5. Im ersten PR nur eine kleine erste Welle von Erweiterungen aktivieren. -- R6. Die Erweiterungen der ersten Welle müssen für relative Importe, die ihren - Paket-Root verlassen, fail-closed sein. -- R7. Die Erweiterungen der ersten Welle müssen das SDK über eine Paket- - Abhängigkeit und eine TS-Projekt-Referenz konsumieren, nicht über `paths`-Aliasse im Root. -- R8. Der Plan muss einen repo-weiten verpflichtenden postinstall-Generierungsschritt für die Editor-Korrektheit vermeiden. -- R9. Der Rollout der ersten Welle muss als moderater PR überprüfbar und mergbar sein, - nicht als repo-weites Refactoring mit mehr als 300 Dateien. - -## Bereichsgrenzen - -- Keine vollständige Migration aller gebündelten Erweiterungen im ersten PR. -- Keine Anforderung, `src/plugin-sdk` im ersten PR zu löschen. -- Keine Anforderung, jeden Root-Build- oder Testpfad sofort auf das neue Paket umzuleiten. -- Kein Versuch, VS Code-Squiggles für jede nicht aktivierte Erweiterung zu erzwingen. -- Keine breite Lint-Bereinigung für den Rest des Erweiterungsbaums. -- Keine großen Änderungen des Laufzeitverhaltens jenseits von Importauflösung, Paketbesitz - und Grenzdurchsetzung für die aktivierten Erweiterungen. - -## Kontext und Recherche - -### Relevanter Code und Muster - -- `pnpm-workspace.yaml` enthält bereits `packages/*` und `extensions/*`, daher passt ein - neues Workspace-Paket unter `packages/plugin-sdk` in das bestehende Repo- - Layout. -- Bestehende Workspace-Pakete wie `packages/memory-host-sdk/package.json` - und `packages/plugin-package-contract/package.json` verwenden bereits paketlokale - `exports`-Maps mit Wurzeln in `src/*.ts`. -- `package.json` im Root veröffentlicht die SDK-Oberfläche derzeit über `./plugin-sdk` - und `./plugin-sdk/*`-Exporte, die von `dist/plugin-sdk/*.js` und - `dist/plugin-sdk/*.d.ts` unterstützt werden. -- `src/plugin-sdk/entrypoints.ts` und `scripts/lib/plugin-sdk-entrypoints.json` - fungieren bereits als kanonisches Entry-Point-Inventar für die SDK-Oberfläche. -- `tsconfig.json` im Root mappt derzeit: - - `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts` - - `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts` -- Das vorherige Grenzexperiment hat gezeigt, dass paketlokales `rootDir` für - unzulässige relative Importe nur dann funktioniert, nachdem erlaubte SDK-Importe nicht mehr in rohe - Quellen außerhalb des Erweiterungspakets aufgelöst werden. - -### Satz von Erweiterungen der ersten Welle - -Dieser Plan geht davon aus, dass die erste Welle die providerlastige Gruppe ist, die am wenigsten -wahrscheinlich komplexe Sonderfälle der Channel-Laufzeit mit sich bringt: - -- `extensions/anthropic` -- `extensions/exa` -- `extensions/firecrawl` -- `extensions/groq` -- `extensions/mistral` -- `extensions/openai` -- `extensions/perplexity` -- `extensions/tavily` -- `extensions/together` -- `extensions/xai` - -### Inventar der SDK-Oberfläche für die erste Welle - -Die Erweiterungen der ersten Welle importieren derzeit eine handhabbare Teilmenge von SDK-Subpfaden. -Das anfängliche Paket `@openclaw/plugin-sdk` muss nur diese abdecken: - -- `agent-runtime` -- `cli-runtime` -- `config-runtime` -- `core` -- `image-generation` -- `media-runtime` -- `media-understanding` -- `plugin-entry` -- `plugin-runtime` -- `provider-auth` -- `provider-auth-api-key` -- `provider-auth-login` -- `provider-auth-runtime` -- `provider-catalog-shared` -- `provider-entry` -- `provider-http` -- `provider-model-shared` -- `provider-onboard` -- `provider-stream-family` -- `provider-stream-shared` -- `provider-tools` -- `provider-usage` -- `provider-web-fetch` -- `provider-web-search` -- `realtime-transcription` -- `realtime-voice` -- `runtime-env` -- `secret-input` -- `security-runtime` -- `speech` -- `testing` - -### Institutionelle Erkenntnisse - -- In diesem Worktree waren keine relevanten `docs/solutions/`-Einträge vorhanden. - -### Externe Referenzen - -- Für diesen Plan war keine externe Recherche nötig. Das Repo enthält bereits die - relevanten Muster für Workspace-Pakete und SDK-Exporte. - -## Wichtige technische Entscheidungen - -- `@openclaw/plugin-sdk` als neues Workspace-Paket einführen und gleichzeitig die - Legacy-Oberfläche `openclaw/plugin-sdk/*` während der Migration aktiv halten. - Begründung: Dadurch kann ein Satz von Erweiterungen der ersten Welle auf echte Paket- - Auflösung umsteigen, ohne dass alle Erweiterungen und alle Build-Pfade im Root - gleichzeitig geändert werden müssen. - -- Eine dedizierte Basis-Konfiguration für Opt-in-Grenzen wie - `extensions/tsconfig.package-boundary.base.json` verwenden, anstatt die - bestehende Erweiterungsbasis für alle zu ersetzen. - Begründung: Das Repo muss während der Migration gleichzeitig Legacy- und Opt-in- - Modi für Erweiterungen unterstützen. - -- TS-Projekt-Referenzen von den Erweiterungen der ersten Welle auf - `packages/plugin-sdk/tsconfig.json` verwenden und - `disableSourceOfProjectReferenceRedirect` für den Opt-in-Grenzmodus setzen. - Begründung: So erhält `tsc` einen echten Paketgraphen und gleichzeitig werden Editor- und - Compiler-Fallbacks auf rohe Source-Traversierung entmutigt. - -- `@openclaw/plugin-sdk` in der ersten Welle privat halten. - Begründung: Das unmittelbare Ziel ist interne Grenzdurchsetzung und Migrations- - Sicherheit, nicht die Veröffentlichung eines zweiten externen SDK-Vertrags, bevor die Oberfläche - stabil ist. - -- In der ersten Implementierung nur die SDK-Subpfade der ersten Welle verschieben und - für den Rest Kompatibilitäts-Brücken beibehalten. - Begründung: Alle 315 `src/plugin-sdk/*.ts`-Dateien in einem PR physisch zu verschieben, ist - genau die Merge-Konflikt-Oberfläche, die dieser Plan vermeiden will. - -- Sich für die erste Welle nicht auf `scripts/postinstall-bundled-plugins.mjs` verlassen, um SDK- - Deklarationen zu bauen. - Begründung: Explizite Build-/Referenz-Flows sind leichter nachvollziehbar und machen das - Repo-Verhalten besser vorhersagbar. - -## Offene Fragen - -### Während der Planung geklärt - -- Welche Erweiterungen sollen in der ersten Welle sein? - Verwenden Sie die 10 oben aufgeführten Provider-/Web-Search-Erweiterungen, weil sie strukturell stärker - isoliert sind als die schwereren Channel-Pakete. - -- Soll der erste PR den gesamten Erweiterungsbaum ersetzen? - Nein. Der erste PR sollte zwei Modi parallel unterstützen und nur die - erste Welle aktivieren. - -- Soll die erste Welle einen postinstall-Deklarations-Build erfordern? - Nein. Der Paket-/Referenzgraph sollte explizit sein, und CI sollte den - relevanten paketlokalen Typecheck bewusst ausführen. - -### Für die Implementierung zurückgestellt - -- Ob das Paket der ersten Welle allein über Projekt-Referenzen direkt auf paketlokale `src/*.ts` - zeigen kann oder ob für das Paket `@openclaw/plugin-sdk` - dennoch ein kleiner Schritt zur Deklarationserzeugung erforderlich ist. - Das ist eine der Implementierung gehörende Frage zur Validierung des TS-Graphen. - -- Ob das Root-Paket `openclaw` Subpfade des SDK der ersten Welle sofort auf - Ausgaben aus `packages/plugin-sdk` proxien sollte oder weiterhin generierte - Kompatibilitäts-Shims unter `src/plugin-sdk` verwenden sollte. - Das ist ein Kompatibilitäts- und Build-Shape-Detail, das vom minimalen - Implementierungspfad abhängt, der CI grün hält. - -## Technisches Design auf hoher Ebene - -> Dies veranschaulicht den beabsichtigten Ansatz und ist richtungsweisende Orientierung für das Review, keine Implementierungsspezifikation. Der implementierende Agent sollte dies als Kontext behandeln, nicht als Code zur Reproduktion. - -```mermaid -flowchart TB - subgraph Legacy["Legacy-Erweiterungen (unverändert)"] - L1["extensions/*\nopenclaw/plugin-sdk/*"] - L2["root tsconfig paths"] - L1 --> L2 - L2 --> L3["src/plugin-sdk/*"] - end - - subgraph OptIn["Erweiterungen der ersten Welle"] - O1["10 aktivierte Erweiterungen"] - O2["extensions/tsconfig.package-boundary.base.json"] - O3["rootDir = '.'\nProjekt-Referenz"] - O4["@openclaw/plugin-sdk"] - O1 --> O2 - O2 --> O3 - O3 --> O4 - end - - subgraph SDK["Neues Workspace-Paket"] - P1["packages/plugin-sdk/package.json"] - P2["packages/plugin-sdk/tsconfig.json"] - P3["packages/plugin-sdk/src/.ts"] - P1 --> P2 - P2 --> P3 - end - - O4 --> SDK -``` - -## Implementierungseinheiten - -- [ ] **Einheit 1: Das echte Workspace-Paket `@openclaw/plugin-sdk` einführen** - -**Ziel:** Ein echtes Workspace-Paket für das SDK erstellen, das die -Oberfläche der ersten Welle von Subpfaden besitzen kann, ohne eine repo-weite Migration zu erzwingen. - -**Anforderungen:** R1, R2, R3, R8, R9 - -**Abhängigkeiten:** Keine - -**Dateien:** - -- Erstellen: `packages/plugin-sdk/package.json` -- Erstellen: `packages/plugin-sdk/tsconfig.json` -- Erstellen: `packages/plugin-sdk/src/index.ts` -- Erstellen: `packages/plugin-sdk/src/*.ts` für die SDK-Subpfade der ersten Welle -- Ändern: `pnpm-workspace.yaml` nur falls Anpassungen an Paket-Globs nötig sind -- Ändern: `package.json` -- Ändern: `src/plugin-sdk/entrypoints.ts` -- Ändern: `scripts/lib/plugin-sdk-entrypoints.json` -- Test: `src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts` - -**Ansatz:** - -- Ein neues Workspace-Paket namens `@openclaw/plugin-sdk` hinzufügen. -- Mit nur den SDK-Subpfaden der ersten Welle beginnen, nicht mit dem gesamten Baum aus 315 Dateien. -- Wenn das direkte Verschieben eines Entry-Points der ersten Welle einen zu großen Diff erzeugen würde, kann der - erste PR diesen Subpfad zunächst als dünnen Paket-Wrapper in `packages/plugin-sdk/src` einführen - und dann in einem Folge-PR für diesen Subpfad-Cluster die Quelle der Wahrheit auf das Paket umstellen. -- Die vorhandene Entry-Point-Inventar-Mechanik wiederverwenden, damit die Paketoberfläche der ersten Welle - an einer kanonischen Stelle deklariert ist. -- Die Exporte des Root-Pakets für Legacy-Benutzer aktiv halten, während das Workspace- - Paket zum neuen Opt-in-Vertrag wird. - -**Zu befolgende Muster:** - -- `packages/memory-host-sdk/package.json` -- `packages/plugin-package-contract/package.json` -- `src/plugin-sdk/entrypoints.ts` - -**Testszenarien:** - -- Happy Path: Das Workspace-Paket exportiert jeden im - Plan aufgeführten Subpfad der ersten Welle, und kein erforderlicher Export der ersten Welle fehlt. -- Sonderfall: Metadaten zu Paket-Exporten bleiben stabil, wenn die Liste der Einträge der ersten Welle - neu generiert oder mit dem kanonischen Inventar verglichen wird. -- Integration: Legacy-SDK-Exporte des Root-Pakets bleiben nach Einführung des neuen Workspace-Pakets erhalten. - -**Verifizierung:** - -- Das Repo enthält ein gültiges Workspace-Paket `@openclaw/plugin-sdk` mit einer - stabilen Export-Map der ersten Welle und ohne Regression der Legacy-Exporte im Root- - `package.json`. - -- [ ] **Einheit 2: Einen Opt-in-TS-Grenzmodus für paketdurchgesetzte Erweiterungen hinzufügen** - -**Ziel:** Den TS-Konfigurationsmodus definieren, den aktivierte Erweiterungen verwenden, -während das bestehende TS-Verhalten für Erweiterungen für alle anderen unverändert bleibt. - -**Anforderungen:** R4, R6, R7, R8, R9 - -**Abhängigkeiten:** Einheit 1 - -**Dateien:** - -- Erstellen: `extensions/tsconfig.package-boundary.base.json` -- Erstellen: `tsconfig.boundary-optin.json` -- Ändern: `extensions/xai/tsconfig.json` -- Ändern: `extensions/openai/tsconfig.json` -- Ändern: `extensions/anthropic/tsconfig.json` -- Ändern: `extensions/mistral/tsconfig.json` -- Ändern: `extensions/groq/tsconfig.json` -- Ändern: `extensions/together/tsconfig.json` -- Ändern: `extensions/perplexity/tsconfig.json` -- Ändern: `extensions/tavily/tsconfig.json` -- Ändern: `extensions/exa/tsconfig.json` -- Ändern: `extensions/firecrawl/tsconfig.json` -- Test: `src/plugins/contracts/extension-package-project-boundaries.test.ts` -- Test: `test/extension-package-tsc-boundary.test.ts` - -**Ansatz:** - -- `extensions/tsconfig.base.json` für Legacy-Erweiterungen beibehalten. -- Eine neue Opt-in-Basiskonfiguration hinzufügen, die: - - `rootDir: "."` setzt - - auf `packages/plugin-sdk` referenziert - - `composite` aktiviert - - die Source-Umleitung von Projekt-Referenzen deaktiviert, wenn nötig -- Eine dedizierte Lösungskonfiguration für den Typecheck-Graphen der ersten Welle hinzufügen, anstatt - im selben PR das TS-Projekt des gesamten Repos umzugestalten. - -**Ausführungshinweis:** Beginnen Sie mit einem fehlschlagenden paketlokalen Canary-Typecheck für eine -aktivierte Erweiterung, bevor Sie das Muster auf alle 10 anwenden. - -**Zu befolgende Muster:** - -- Bestehendes Muster paketlokaler `tsconfig.json` für Erweiterungen aus der vorherigen - Grenzarbeit -- Workspace-Paket-Muster aus `packages/memory-host-sdk` - -**Testszenarien:** - -- Happy Path: Jede aktivierte Erweiterung typecheckt erfolgreich über die - TS-Konfiguration mit Paketgrenzen. -- Fehlerpfad: Ein Canary-relative-Import aus `../../src/cli/acp-cli.ts` schlägt - für eine aktivierte Erweiterung mit `TS6059` fehl. -- Integration: Nicht aktivierte Erweiterungen bleiben unangetastet und müssen nicht an der neuen Lösungskonfiguration teilnehmen. - -**Verifizierung:** - -- Es gibt einen dedizierten Typecheck-Graphen für die 10 aktivierten Erweiterungen, und unzulässige - relative Importe aus einer davon schlagen unter normalem `tsc` fehl. - -- [ ] **Einheit 3: Die Erweiterungen der ersten Welle auf `@openclaw/plugin-sdk` migrieren** - -**Ziel:** Die Erweiterungen der ersten Welle so ändern, dass sie das echte SDK-Paket -über Abhängigkeitsmetadaten, Projekt-Referenzen und Importen per Paketname konsumieren. - -**Anforderungen:** R5, R6, R7, R9 - -**Abhängigkeiten:** Einheit 2 - -**Dateien:** - -- Ändern: `extensions/anthropic/package.json` -- Ändern: `extensions/exa/package.json` -- Ändern: `extensions/firecrawl/package.json` -- Ändern: `extensions/groq/package.json` -- Ändern: `extensions/mistral/package.json` -- Ändern: `extensions/openai/package.json` -- Ändern: `extensions/perplexity/package.json` -- Ändern: `extensions/tavily/package.json` -- Ändern: `extensions/together/package.json` -- Ändern: `extensions/xai/package.json` -- Ändern: Produktions- und Testimporte unter jedem der 10 Erweiterungs-Roots, die derzeit auf - `openclaw/plugin-sdk/*` verweisen - -**Ansatz:** - -- `@openclaw/plugin-sdk: workspace:*` zu den `devDependencies` der Erweiterungen der ersten Welle hinzufügen. -- `openclaw/plugin-sdk/*`-Importe in diesen Paketen durch - `@openclaw/plugin-sdk/*` ersetzen. -- Erweiterungsinterne lokale Importe auf lokalen Barrels wie `./api.ts` und - `./runtime-api.ts` belassen. -- Nicht aktivierte Erweiterungen in diesem PR nicht ändern. - -**Zu befolgende Muster:** - -- Bestehende lokale Import-Barrels von Erweiterungen (`api.ts`, `runtime-api.ts`) -- Form von Paketabhängigkeiten, die von anderen `@openclaw/*`-Workspace-Paketen verwendet wird - -**Testszenarien:** - -- Happy Path: Jede migrierte Erweiterung registriert/lädt sich nach dem Umschreiben der Importe - weiterhin über ihre bestehenden Plugin-Tests. -- Sonderfall: Rein testbezogene SDK-Importe im aktivierten Satz von Erweiterungen werden weiterhin korrekt - über das neue Paket aufgelöst. -- Integration: Migrierte Erweiterungen benötigen für den Typecheck nicht die - Legacy-Root-Alias-Pfade `openclaw/plugin-sdk/*`. - -**Verifizierung:** - -- Die Erweiterungen der ersten Welle bauen und testen gegen `@openclaw/plugin-sdk`, - ohne den Legacy-Root-SDK-Alias-Pfad zu benötigen. - -- [ ] **Einheit 4: Legacy-Kompatibilität erhalten, während die Migration nur teilweise erfolgt** - -**Ziel:** Den Rest des Repos funktionsfähig halten, während das SDK während der Migration sowohl in Legacy- -als auch in neuer Paketform existiert. - -**Anforderungen:** R4, R8, R9 - -**Abhängigkeiten:** Einheiten 1-3 - -**Dateien:** - -- Ändern: `src/plugin-sdk/*.ts` für Kompatibilitäts-Shims der ersten Welle nach Bedarf -- Ändern: `package.json` -- Ändern: Build- oder Export-Verkabelung, die SDK-Artefakte zusammenstellt -- Test: `src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts` -- Test: `src/plugins/contracts/plugin-sdk-index.bundle.test.ts` - -**Ansatz:** - -- `openclaw/plugin-sdk/*` im Root als Kompatibilitätsoberfläche für Legacy- - Erweiterungen und für externe Nutzer, die noch nicht migrieren, beibehalten. -- Entweder generierte Shims oder Root-Export-Proxy-Verkabelung für die - Subpfade der ersten Welle verwenden, die nach `packages/plugin-sdk` verschoben wurden. -- In dieser Phase nicht versuchen, die SDK-Oberfläche im Root außer Betrieb zu nehmen. - -**Zu befolgende Muster:** - -- Bestehende Erzeugung von SDK-Exporten im Root über `src/plugin-sdk/entrypoints.ts` -- Bestehende Export-Kompatibilität des Pakets im Root in `package.json` - -**Testszenarien:** - -- Happy Path: Ein Legacy-Root-SDK-Import wird für eine nicht aktivierte - Erweiterung weiterhin aufgelöst, nachdem das neue Paket existiert. -- Sonderfall: Ein Subpfad der ersten Welle funktioniert während des Migrationsfensters sowohl über die - Legacy-Root-Oberfläche als auch über die neue Paketoberfläche. -- Integration: Vertrags-Tests für den SDK-Index/das Bundle sehen weiterhin eine kohärente - öffentliche Oberfläche. - -**Verifizierung:** - -- Das Repo unterstützt sowohl Legacy- als auch Opt-in-Modi für die Nutzung des SDK, ohne - unveränderte Erweiterungen zu beschädigen. - -- [ ] **Einheit 5: Abgegrenzte Durchsetzung hinzufügen und den Migrationsvertrag dokumentieren** - -**Ziel:** CI und Contributor-Guidance einführen, die das neue Verhalten für die -erste Welle durchsetzen, ohne so zu tun, als wäre der gesamte Erweiterungsbaum migriert. - -**Anforderungen:** R5, R6, R8, R9 - -**Abhängigkeiten:** Einheiten 1-4 - -**Dateien:** - -- Ändern: `package.json` -- Ändern: CI-Workflow-Dateien, die den Typecheck der Opt-in-Grenzen ausführen sollen -- Ändern: `AGENTS.md` -- Ändern: `docs/plugins/sdk-overview.md` -- Ändern: `docs/plugins/sdk-entrypoints.md` -- Ändern: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` - -**Ansatz:** - -- Ein explizites Gate für die erste Welle hinzufügen, etwa einen dedizierten `tsc -b`-Lauf der Lösung für - `packages/plugin-sdk` plus die 10 aktivierten Erweiterungen. -- Dokumentieren, dass das Repo nun sowohl Legacy- als auch Opt-in-Modi für Erweiterungen unterstützt, - und dass neue Arbeiten an Erweiterungsgrenzen den neuen Paketpfad bevorzugen sollten. -- Die Regel für die nächste Migrationswelle festhalten, damit spätere PRs weitere Erweiterungen hinzufügen können, - ohne die Architektur erneut auszudiskutieren. - -**Zu befolgende Muster:** - -- Bestehende Vertrags-Tests unter `src/plugins/contracts/` -- Bestehende Doku-Updates, die gestufte Migrationen erklären - -**Testszenarien:** - -- Happy Path: Das neue Typecheck-Gate der ersten Welle besteht für das Workspace-Paket - und die aktivierten Erweiterungen. -- Fehlerpfad: Das Einführen eines neuen unzulässigen relativen Imports in einer aktivierten - Erweiterung lässt das abgegrenzte Typecheck-Gate fehlschlagen. -- Integration: CI verlangt noch nicht von nicht aktivierten Erweiterungen, den neuen - Paketgrenzen-Modus zu erfüllen. - -**Verifizierung:** - -- Der Durchsetzungspfad für die erste Welle ist dokumentiert, getestet und ausführbar, ohne - den gesamten Erweiterungsbaum zur Migration zu zwingen. - -## Systemweite Auswirkungen - -- **Interaktionsgraph:** Diese Arbeit betrifft die Quelle der Wahrheit des SDK, Root-Paket- - Exporte, Paketmetadaten von Erweiterungen, das Layout des TS-Graphen und die CI-Verifizierung. -- **Fehlerfortpflanzung:** Der wichtigste beabsichtigte Fehlermodus werden Compile-Zeit-TS- - Fehler (`TS6059`) in aktivierten Erweiterungen anstelle von Fehlern, die nur durch benutzerdefinierte Skripte erkannt werden. -- **Risiken im Zustandslebenszyklus:** Die Dual-Oberflächen-Migration führt das Risiko von Drift zwischen - Root-Kompatibilitätsexporten und dem neuen Workspace-Paket ein. -- **Parität der API-Oberfläche:** Subpfade der ersten Welle müssen während der - Übergangsphase semantisch identisch bleiben – sowohl über `openclaw/plugin-sdk/*` als auch über - `@openclaw/plugin-sdk/*`. -- **Integrationsabdeckung:** Unit-Tests reichen nicht aus; abgegrenzte Paketgraph- - Typechecks sind erforderlich, um die Grenze zu beweisen. -- **Unveränderte Invarianten:** Nicht aktivierte Erweiterungen behalten in PR 1 ihr aktuelles Verhalten - bei. Dieser Plan beansprucht keine repo-weite Durchsetzung von Importgrenzen. - -## Risiken und Abhängigkeiten - -| Risiko | Gegenmaßnahme | -| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| Das Paket der ersten Welle wird weiterhin in rohe Quellen aufgelöst und `rootDir` schlägt nicht tatsächlich fail-closed fehl | Den ersten Implementierungsschritt zu einer Paket-Referenz-Canary auf einer aktivierten Erweiterung machen, bevor auf die gesamte Gruppe erweitert wird | -| Durch das Verschieben von zu viel SDK-Source auf einmal entsteht erneut das ursprüngliche Merge-Konflikt-Problem | Im ersten PR nur die Subpfade der ersten Welle verschieben und Kompatibilitäts-Brücken im Root beibehalten | -| Legacy- und neue SDK-Oberflächen driften semantisch auseinander | Ein einziges Entry-Point-Inventar beibehalten, Kompatibilitäts-Vertrags-Tests hinzufügen und die Dual-Oberflächen-Parität explizit machen | -| Build-/Testpfade des Root-Repos beginnen versehentlich, auf unkontrollierte Weise vom neuen Paket abzuhängen | Eine dedizierte Opt-in-Lösungskonfiguration verwenden und Änderungen an der repo-weiten TS-Topologie aus dem ersten PR heraushalten | - -## Phasenweise Auslieferung - -### Phase 1 - -- `@openclaw/plugin-sdk` einführen -- Die Subpfad-Oberfläche der ersten Welle definieren -- Nachweisen, dass eine aktivierte Erweiterung über `rootDir` fail-closed fehlschlagen kann - -### Phase 2 - -- Die 10 Erweiterungen der ersten Welle aktivieren -- Root-Kompatibilität für alle anderen beibehalten - -### Phase 3 - -- In späteren PRs weitere Erweiterungen hinzufügen -- Mehr SDK-Subpfade in das Workspace-Paket verschieben -- Root-Kompatibilität erst außer Betrieb nehmen, nachdem die Menge der Legacy-Erweiterungen verschwunden ist - -## Dokumentations- / Betriebshinweise - -- Der erste PR sollte sich ausdrücklich als Dual-Modus-Migration beschreiben, nicht als - Abschluss der repo-weiten Durchsetzung. -- Die Migrationsanleitung sollte es späteren PRs leicht machen, weitere Erweiterungen hinzuzufügen, - indem dasselbe Muster aus Paket/Abhängigkeit/Referenz befolgt wird. - -## Quellen und Referenzen - -- Vorheriger Plan: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` -- Workspace-Konfiguration: `pnpm-workspace.yaml` -- Bestehendes Inventar von SDK-Entry-Points: `src/plugin-sdk/entrypoints.ts` -- Bestehende SDK-Exporte im Root: `package.json` -- Bestehende Muster für Workspace-Pakete: - - `packages/memory-host-sdk/package.json` - - `packages/plugin-package-contract/package.json` diff --git a/docs/de/plugins/architecture.md b/docs/de/plugins/architecture.md index 3d6b11bce..2015f38e3 100644 --- a/docs/de/plugins/architecture.md +++ b/docs/de/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - Erstellen oder Debuggen nativer OpenClaw-Plugins - - Das Fähigkeitsmodell von Plugins oder Eigentumsgrenzen verstehen - - An der Plugin-Ladepipeline oder Registry arbeiten - - Provider-Laufzeit-Hooks oder Kanal-Plugins implementieren + - Sie erstellen oder debuggen native OpenClaw-Plugins + - Sie möchten das Plugin-Fähigkeitsmodell oder Ownership-Grenzen verstehen + - Sie arbeiten an der Plugin-Ladepipeline oder Registry + - Sie implementieren Provider-Laufzeit-Hooks oder Kanal-Plugins sidebarTitle: Internals -summary: 'Plugin-Interna: Fähigkeitsmodell, Eigentümerschaft, Verträge, Ladepipeline und Laufzeit-Hilfsfunktionen' +summary: 'Plugin-Interna: Fähigkeitsmodell, Ownership, Verträge, Ladepipeline und Laufzeit-Helfer' title: Plugin-Interna x-i18n: - generated_at: "2026-04-08T02:20:33Z" + generated_at: "2026-04-09T01:31:44Z" model: gpt-5.4 provider: openai - source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 + source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 source_path: plugins/architecture.md workflow: 15 --- @@ -19,12 +19,12 @@ x-i18n: # Plugin-Interna - Dies ist die **ausführliche Architekturreferenz**. Praktische Anleitungen finden Sie unter: - - [Plugins installieren und verwenden](/de/tools/plugin) — Benutzerhandbuch + Dies ist die **Referenz für die tiefgehende Architektur**. Praktische Anleitungen finden Sie hier: + - [Plugins installieren und verwenden](/de/tools/plugin) — Benutzerleitfaden - [Erste Schritte](/de/plugins/building-plugins) — erstes Plugin-Tutorial - [Kanal-Plugins](/de/plugins/sdk-channel-plugins) — einen Messaging-Kanal erstellen - - [Provider-Plugins](/de/plugins/sdk-provider-plugins) — einen Modell-Provider erstellen - - [SDK-Überblick](/de/plugins/sdk-overview) — Import-Map und Registrierungs-API + - [Provider-Plugins](/de/plugins/sdk-provider-plugins) — einen Modellanbieter erstellen + - [SDK-Überblick](/de/plugins/sdk-overview) — Importzuordnung und Registrierungs-API Diese Seite behandelt die interne Architektur des OpenClaw-Plugin-Systems. @@ -34,47 +34,47 @@ Diese Seite behandelt die interne Architektur des OpenClaw-Plugin-Systems. Fähigkeiten sind das öffentliche Modell für **native Plugins** innerhalb von OpenClaw. Jedes native OpenClaw-Plugin registriert sich für einen oder mehrere Fähigkeitstypen: -| Fähigkeit | Registrierungsmethode | Beispiel-Plugins | -| --------------------- | ----------------------------------------------- | ----------------------------------- | -| Textinferenz | `api.registerProvider(...)` | `openai`, `anthropic` | -| CLI-Inferenz-Backend | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Sprache | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Echtzeit-Transkription | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Echtzeit-Stimme | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Medienverständnis | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Bildgenerierung | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Musikgenerierung | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Videogenerierung | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Web-Abruf | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Websuche | `api.registerWebSearchProvider(...)` | `google` | -| Kanal / Messaging | `api.registerChannel(...)` | `msteams`, `matrix` | +| Fähigkeit | Registrierungsmethode | Beispiel-Plugins | +| ---------------------- | ------------------------------------------------ | ------------------------------------ | +| Textinferenz | `api.registerProvider(...)` | `openai`, `anthropic` | +| CLI-Inferenz-Backend | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Sprache | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Echtzeit-Transkription | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Echtzeit-Sprache | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Medienverständnis | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Bildgenerierung | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Musikgenerierung | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Videogenerierung | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Web-Abruf | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Websuche | `api.registerWebSearchProvider(...)` | `google` | +| Kanal / Messaging | `api.registerChannel(...)` | `msteams`, `matrix` | Ein Plugin, das null Fähigkeiten registriert, aber Hooks, Tools oder -Dienste bereitstellt, ist ein **Legacy-Hook-only**-Plugin. Dieses Muster wird weiterhin vollständig unterstützt. +Services bereitstellt, ist ein **Legacy-Hook-only**-Plugin. Dieses Muster wird weiterhin vollständig unterstützt. ### Haltung zur externen Kompatibilität -Das Fähigkeitsmodell ist im Core angekommen und wird heute von gebündelten/nativen Plugins -verwendet, aber die Kompatibilität für externe Plugins braucht weiterhin einen strengeren Maßstab als „es wird +Das Fähigkeitsmodell ist im Kernsystem eingeführt und wird heute von gebündelten/nativen Plugins +verwendet, aber für die Kompatibilität externer Plugins braucht es weiterhin eine strengere Messlatte als „es ist exportiert, also ist es eingefroren“. Aktuelle Richtlinien: -- **bestehende externe Plugins:** Hook-basierte Integrationen funktionsfähig halten; behandeln Sie +- **bestehende externe Plugins:** halten Sie hook-basierte Integrationen funktionsfähig; behandeln Sie dies als Kompatibilitäts-Basislinie -- **neue gebündelte/native Plugins:** explizite Fähigkeitsregistrierung gegenüber - herstellerspezifischen Eingriffen oder neuen Hook-only-Designs bevorzugen -- **externe Plugins, die Fähigkeitsregistrierung übernehmen:** erlaubt, aber die - fähigkeitsspezifischen Hilfsoberflächen als in Entwicklung betrachten, sofern die Dokumentation einen +- **neue gebündelte/native Plugins:** bevorzugen Sie explizite Fähigkeitsregistrierung statt + anbieterspezifischer Eingriffe oder neuer Hook-only-Designs +- **externe Plugins, die Fähigkeitsregistrierung übernehmen:** erlaubt, aber behandeln Sie + fähigkeitsspezifische Helferoberflächen als weiterentwickelbar, sofern die Dokumentation einen Vertrag nicht ausdrücklich als stabil kennzeichnet Praktische Regel: -- APIs zur Fähigkeitsregistrierung sind die beabsichtigte Richtung -- Legacy-Hooks bleiben während - des Übergangs der sicherste Weg ohne Breaking Changes für externe Plugins -- exportierte Hilfs-Subpaths sind nicht alle gleich; bevorzugen Sie den eng dokumentierten - Vertrag, nicht zufällige Hilfsexporte +- APIs zur Fähigkeitsregistrierung sind die vorgesehene Richtung +- Legacy-Hooks bleiben während des + Übergangs der sicherste Weg ohne Inkompatibilitäten für externe Plugins +- exportierte Helper-Subpaths sind nicht alle gleich; bevorzugen Sie den schmalen dokumentierten + Vertrag, nicht beiläufig exportierte Helfer ### Plugin-Formen @@ -84,39 +84,39 @@ Registrierungsverhaltens in eine Form (nicht nur anhand statischer Metadaten): - **plain-capability** -- registriert genau einen Fähigkeitstyp (zum Beispiel ein reines Provider-Plugin wie `mistral`) - **hybrid-capability** -- registriert mehrere Fähigkeitstypen (zum Beispiel - besitzt `openai` Textinferenz, Sprache, Medienverständnis und Bild- + `openai` besitzt Textinferenz, Sprache, Medienverständnis und Bild- generierung) - **hook-only** -- registriert nur Hooks (typisiert oder benutzerdefiniert), keine Fähigkeiten, - Tools, Befehle oder Dienste -- **non-capability** -- registriert Tools, Befehle, Dienste oder Routen, aber keine + Tools, Befehle oder Services +- **non-capability** -- registriert Tools, Befehle, Services oder Routen, aber keine Fähigkeiten -Verwenden Sie `openclaw plugins inspect `, um die Form und Aufschlüsselung der Fähigkeiten -eines Plugins anzuzeigen. Details finden Sie in der [CLI-Referenz](/cli/plugins#inspect). +Verwenden Sie `openclaw plugins inspect `, um die Form und die Aufschlüsselung der +Fähigkeiten eines Plugins anzuzeigen. Details finden Sie in der [CLI-Referenz](/cli/plugins#inspect). ### Legacy-Hooks Der Hook `before_agent_start` bleibt als Kompatibilitätspfad für -Hook-only-Plugins unterstützt. Reale ältere Plugins sind weiterhin davon abhängig. +Hook-only-Plugins unterstützt. Bestehende Plugins aus der Praxis hängen weiterhin davon ab. Ausrichtung: - funktionsfähig halten -- als veraltet dokumentieren -- `before_model_resolve` für Arbeit an Modell-/Provider-Overrides bevorzugen -- `before_prompt_build` für Prompt-Mutationen bevorzugen -- erst entfernen, wenn die reale Nutzung zurückgeht und Fixture-Abdeckung Migrationssicherheit beweist +- als Legacy dokumentieren +- `before_model_resolve` für Arbeiten an Modell-/Provider-Überschreibungen bevorzugen +- `before_prompt_build` für Arbeiten an Prompt-Mutationen bevorzugen +- erst entfernen, wenn die reale Nutzung sinkt und die Abdeckung durch Fixtures eine sichere Migration belegt ### Kompatibilitätssignale Wenn Sie `openclaw doctor` oder `openclaw plugins inspect ` ausführen, sehen Sie möglicherweise -eine dieser Kennzeichnungen: +eines dieser Labels: -| Signal | Bedeutung | -| -------------------------- | ----------------------------------------------------------- | +| Signal | Bedeutung | +| -------------------------- | ---------------------------------------------------------- | | **config valid** | Konfiguration wird korrekt geparst und Plugins werden aufgelöst | | **compatibility advisory** | Plugin verwendet ein unterstütztes, aber älteres Muster (z. B. `hook-only`) | -| **legacy warning** | Plugin verwendet `before_agent_start`, das veraltet ist | +| **legacy warning** | Plugin verwendet `before_agent_start`, das veraltet ist | | **hard error** | Konfiguration ist ungültig oder Plugin konnte nicht geladen werden | Weder `hook-only` noch `before_agent_start` machen Ihr Plugin heute kaputt -- @@ -125,62 +125,62 @@ Signale erscheinen auch in `openclaw status --all` und `openclaw plugins doctor` ## Architekturüberblick -Das Plugin-System von OpenClaw hat vier Schichten: +Das Plugin-System von OpenClaw hat vier Ebenen: 1. **Manifest + Discovery** - OpenClaw findet Kandidaten-Plugins aus konfigurierten Pfaden, Workspace-Wurzeln, - globalen Erweiterungswurzeln und gebündelten Erweiterungen. Discovery liest zuerst native + OpenClaw findet potenzielle Plugins aus konfigurierten Pfaden, Workspace-Wurzeln, + globalen Extension-Wurzeln und gebündelten Extensions. Discovery liest zuerst native `openclaw.plugin.json`-Manifeste sowie unterstützte Bundle-Manifeste. 2. **Aktivierung + Validierung** - Der Core entscheidet, ob ein entdecktes Plugin aktiviert, deaktiviert, blockiert oder - für einen exklusiven Slot wie Memory ausgewählt ist. + Der Kern entscheidet, ob ein entdecktes Plugin aktiviert, deaktiviert, blockiert oder + für einen exklusiven Slot wie Speicher ausgewählt wird. 3. **Laufzeitladen** - Native OpenClaw-Plugins werden im Prozess über jiti geladen und registrieren + Native OpenClaw-Plugins werden über jiti im Prozess geladen und registrieren Fähigkeiten in einer zentralen Registry. Kompatible Bundles werden in Registry-Einträge normalisiert, ohne Laufzeitcode zu importieren. -4. **Nutzung der Oberflächen** +4. **Oberflächennutzung** Der Rest von OpenClaw liest die Registry, um Tools, Kanäle, Provider- - Einrichtung, Hooks, HTTP-Routen, CLI-Befehle und Dienste bereitzustellen. + Einrichtung, Hooks, HTTP-Routen, CLI-Befehle und Services bereitzustellen. -Speziell für die Plugin-CLI ist die Discovery von Root-Befehlen in zwei Phasen aufgeteilt: +Speziell für die Plugin-CLI ist die Erkennung von Root-Befehlen in zwei Phasen aufgeteilt: -- Parse-Time-Metadaten stammen aus `registerCli(..., { descriptors: [...] })` -- das eigentliche Plugin-CLI-Modul kann lazy bleiben und sich beim ersten Aufruf registrieren +- Parse-Zeit-Metadaten kommen aus `registerCli(..., { descriptors: [...] })` +- das eigentliche Plugin-CLI-Modul kann lazy bleiben und sich erst beim ersten Aufruf registrieren -Dadurch bleibt plugin-eigener CLI-Code im Plugin, während OpenClaw dennoch +Dadurch bleibt die dem Plugin gehörende CLI im Plugin, während OpenClaw dennoch Root-Befehlsnamen vor dem Parsen reservieren kann. Die wichtige Designgrenze: -- Discovery + Konfigurationsvalidierung sollten aus **Manifest-/Schema-Metadaten** +- Discovery + Konfigurationsvalidierung sollten anhand von **Manifest-/Schema-Metadaten** funktionieren, ohne Plugin-Code auszuführen -- natives Laufzeitverhalten stammt aus dem Pfad `register(api)` des Plugin-Moduls +- natives Laufzeitverhalten kommt aus dem Pfad `register(api)` des Plugin-Moduls -Diese Aufteilung ermöglicht es OpenClaw, Konfigurationen zu validieren, fehlende/deaktivierte Plugins zu erklären und -UI-/Schema-Hinweise aufzubauen, bevor die vollständige Laufzeit aktiv ist. +Diese Trennung ermöglicht OpenClaw, Konfigurationen zu validieren, fehlende/deaktivierte Plugins +zu erklären und UI-/Schema-Hinweise zu erzeugen, bevor die vollständige Laufzeit aktiv ist. -### Kanal-Plugins und das gemeinsame Message-Tool +### Kanal-Plugins und das gemeinsame `message`-Tool Kanal-Plugins müssen für normale Chat-Aktionen kein separates Tool zum Senden/Bearbeiten/Reagieren registrieren. -OpenClaw hält ein gemeinsames `message`-Tool im Core, und +OpenClaw behält ein gemeinsames `message`-Tool im Kern, und Kanal-Plugins besitzen die kanalspezifische Discovery und Ausführung dahinter. Die aktuelle Grenze ist: -- der Core besitzt den gemeinsamen Tool-Host `message`, Prompt-Verdrahtung, Sitzungs-/Thread- +- der Kern besitzt den gemeinsamen `message`-Tool-Host, Prompt-Verdrahtung, Sitzungs-/Thread- Buchführung und Ausführungs-Dispatch -- Kanal-Plugins besitzen scoped Action-Discovery, Fähigkeits-Discovery und alle - kanalspezifischen Schemafragmente -- Kanal-Plugins besitzen die providerspezifische Sitzungs-Gesprächsgrammatik, also - wie Gesprächs-IDs Thread-IDs codieren oder von Elterngesprächen erben -- Kanal-Plugins führen die finale Aktion über ihren Action-Adapter aus +- Kanal-Plugins besitzen Scoped-Action-Discovery, Fähigkeits-Discovery und beliebige + kanalspezifische Schemafragmente +- Kanal-Plugins besitzen anbieterspezifische Sitzungs-/Unterhaltungsgrammatik, etwa + wie Unterhaltungs-IDs Thread-IDs kodieren oder von Elternunterhaltungen erben +- Kanal-Plugins führen die endgültige Aktion über ihren Action-Adapter aus Für Kanal-Plugins ist die SDK-Oberfläche `ChannelMessageActionAdapter.describeMessageTool(...)`. Dieser einheitliche Discovery- -Aufruf ermöglicht es einem Plugin, seine sichtbaren Aktionen, Fähigkeiten und Schema- -Beiträge zusammen zurückzugeben, damit diese Teile nicht auseinanderlaufen. +Aufruf erlaubt es einem Plugin, seine sichtbaren Aktionen, Fähigkeiten und Schema- +Beiträge zusammen zurückzugeben, damit diese Teile nicht auseinanderdriften. -Der Core übergibt den Laufzeit-Scope an diesen Discovery-Schritt. Wichtige Felder sind: +Der Kern übergibt den Laufzeitkontext in diesen Discovery-Schritt. Wichtige Felder sind: - `accountId` - `currentChannelId` @@ -191,123 +191,123 @@ Der Core übergibt den Laufzeit-Scope an diesen Discovery-Schritt. Wichtige Feld - `agentId` - vertrauenswürdige eingehende `requesterSenderId` -Das ist wichtig für kontextsensitive Plugins. Ein Kanal kann -Message-Aktionen basierend auf dem aktiven Konto, dem aktuellen Raum/Thread/Nachricht oder der -vertrauenswürdigen Identität des Anfragenden ausblenden oder anzeigen, ohne kanalspezifische Verzweigungen -im Core-Tool `message` hart zu codieren. +Das ist für kontextsensitive Plugins wichtig. Ein Kanal kann +Nachrichtenaktionen abhängig vom aktiven Konto, dem aktuellen Raum/Thread/der aktuellen Nachricht oder +der vertrauenswürdigen Anforderer-Identität ein- oder ausblenden, ohne +kanalspezifische Verzweigungen im Kern-`message`-Tool fest zu verdrahten. -Deshalb bleiben Änderungen am Embedded-Runner-Routing Plugin-Arbeit: Der Runner ist -dafür verantwortlich, die aktuelle Chat-/Sitzungsidentität an die Plugin- -Discovery-Grenze weiterzugeben, damit das gemeinsame Tool `message` die richtige -kanaleigene Oberfläche für den aktuellen Zug bereitstellt. +Deshalb sind Änderungen am Embedded-Runner-Routing weiterhin Plugin-Arbeit: Der Runner ist +dafür verantwortlich, die aktuelle Chat-/Sitzungsidentität in die Plugin- +Discovery-Grenze weiterzuleiten, damit das gemeinsame `message`-Tool die richtige, dem Kanal gehörende +Oberfläche für den aktuellen Turn bereitstellt. -Für kanaleigene Ausführungs-Hilfsfunktionen sollten gebündelte Plugins die Ausführungs- -Laufzeit in ihren eigenen Erweiterungsmodulen halten. Der Core besitzt nicht mehr die -Laufzeiten für Discord-, Slack-, Telegram- oder WhatsApp-Message-Aktionen unter `src/agents/tools`. +Für kanaleigene Ausführungshelfer sollten gebündelte Plugins die Ausführungs- +Laufzeit innerhalb ihrer eigenen Extension-Module behalten. Der Kern besitzt nicht mehr die Laufzeiten +für Discord-, Slack-, Telegram- oder WhatsApp-Nachrichtenaktionen unter `src/agents/tools`. Wir veröffentlichen keine separaten `plugin-sdk/*-action-runtime`-Subpaths, und gebündelte Plugins sollten ihren eigenen lokalen Laufzeitcode direkt aus ihren -erweiterungseigenen Modulen importieren. +Extension-eigenen Modulen importieren. -Dieselbe Grenze gilt allgemein für providerbenannte SDK-Seams: Der Core sollte +Dieselbe Grenze gilt allgemein für providerbenannte SDK-Seams: Der Kern sollte keine kanalspezifischen Convenience-Barrels für Slack, Discord, Signal, -WhatsApp oder ähnliche Erweiterungen importieren. Wenn der Core ein Verhalten braucht, dann entweder über das -eigene `api.ts`- / `runtime-api.ts`-Barrel des gebündelten Plugins konsumieren oder den Bedarf -in eine schmale generische Fähigkeit im gemeinsamen SDK überführen. +WhatsApp oder ähnliche Extensions importieren. Wenn der Kern ein Verhalten benötigt, dann entweder +über das eigene Barrel `api.ts` / `runtime-api.ts` des gebündelten Plugins oder durch Anheben +dieses Bedarfs in eine schmale generische Fähigkeit im gemeinsamen SDK. Speziell für Umfragen gibt es zwei Ausführungspfade: -- `outbound.sendPoll` ist die gemeinsame Basis für Kanäle, die zum allgemeinen +- `outbound.sendPoll` ist die gemeinsame Basis für Kanäle, die zum gemeinsamen Umfragemodell passen - `actions.handleAction("poll")` ist der bevorzugte Pfad für kanalspezifische Umfragesemantik oder zusätzliche Umfrageparameter -Der Core verschiebt das gemeinsame Umfrage-Parsing nun auf den Zeitpunkt nach dem Ablehnen -des Actions durch den Plugin-Dispatch für Umfragen, sodass plugin-eigene Umfrage-Handler +Der Kern verschiebt das gemeinsame Umfrage-Parsing jetzt so lange, bis der +Plugin-Umfrage-Dispatch die Aktion ablehnt, damit plugin-eigene Umfrage-Handler kanalspezifische Umfragefelder akzeptieren können, ohne zuerst vom generischen Umfrage-Parser blockiert zu werden. Die vollständige Startsequenz finden Sie unter [Ladepipeline](#load-pipeline). -## Modell für Fähigkeitseigentum +## Ownership-Modell für Fähigkeiten -OpenClaw behandelt ein natives Plugin als Eigentumsgrenze für ein **Unternehmen** oder ein -**Feature**, nicht als Sammelsurium nicht zusammenhängender Integrationen. +OpenClaw behandelt ein natives Plugin als Ownership-Grenze für ein **Unternehmen** oder ein +**Feature**, nicht als Sammelsurium unabhängiger Integrationen. Das bedeutet: -- ein Unternehmens-Plugin sollte normalerweise alle OpenClaw-bezogenen +- ein Unternehmens-Plugin sollte normalerweise alle OpenClaw-seitigen Oberflächen dieses Unternehmens besitzen -- ein Feature-Plugin sollte normalerweise die vollständige Oberfläche des eingeführten Features besitzen -- Kanäle sollten gemeinsame Core-Fähigkeiten nutzen, statt Provider-Verhalten ad hoc neu zu implementieren +- ein Feature-Plugin sollte normalerweise die gesamte von ihm eingeführte Feature-Oberfläche besitzen +- Kanäle sollten gemeinsame Kernfähigkeiten konsumieren, statt Provider-Verhalten ad hoc + neu zu implementieren Beispiele: -- das gebündelte Plugin `openai` besitzt OpenAI-Modell-Provider-Verhalten und OpenAI- - Verhalten für Sprache + Echtzeit-Stimme + Medienverständnis + Bildgenerierung -- das gebündelte Plugin `elevenlabs` besitzt ElevenLabs-Sprachverhalten -- das gebündelte Plugin `microsoft` besitzt Microsoft-Sprachverhalten -- das gebündelte Plugin `google` besitzt Google-Modell-Provider-Verhalten sowie Google- +- das gebündelte Plugin `openai` besitzt das OpenAI-Modellprovider-Verhalten und OpenAI- + Verhalten für Sprache + Echtzeit-Sprache + Medienverständnis + Bildgenerierung +- das gebündelte Plugin `elevenlabs` besitzt das ElevenLabs-Sprachverhalten +- das gebündelte Plugin `microsoft` besitzt das Microsoft-Sprachverhalten +- das gebündelte Plugin `google` besitzt das Google-Modellprovider-Verhalten sowie Google- Verhalten für Medienverständnis + Bildgenerierung + Websuche -- das gebündelte Plugin `firecrawl` besitzt Firecrawl-Web-Abrufverhalten +- das gebündelte Plugin `firecrawl` besitzt das Firecrawl-Web-Abruf-Verhalten - die gebündelten Plugins `minimax`, `mistral`, `moonshot` und `zai` besitzen ihre Backends für Medienverständnis -- das gebündelte Plugin `qwen` besitzt Qwen-Textprovider-Verhalten sowie - Verhalten für Medienverständnis und Videogenerierung - das Plugin `voice-call` ist ein Feature-Plugin: Es besitzt Anruftransport, Tools, - CLI, Routen und Twilio-Media-Stream-Bridge, nutzt aber gemeinsame Sprach- sowie Echtzeit- - Transkriptions- und Echtzeit-Stimmfähigkeiten, statt Hersteller-Plugins direkt + CLI, Routen und Twilio-Medienstrom-Bridging, nutzt aber gemeinsame Sprach- sowie + Echtzeit-Transkriptions- und Echtzeit-Sprach-Fähigkeiten, statt Anbieter-Plugins direkt zu importieren -Der beabsichtigte Endzustand ist: +Der angestrebte Endzustand ist: -- OpenAI lebt in einem Plugin, selbst wenn es Textmodelle, Sprache, Bilder und +- OpenAI lebt in einem Plugin, auch wenn es Textmodelle, Sprache, Bilder und künftig Video umfasst -- ein anderer Anbieter kann dasselbe für seine eigene Oberfläche tun -- Kanäle interessiert nicht, welches Anbieter-Plugin den Provider besitzt; sie nutzen den vom Core offengelegten gemeinsamen Fähigkeitsvertrag +- ein anderer Anbieter kann dasselbe für seinen eigenen Oberflächenbereich tun +- Kanäle ist es egal, welches Anbieter-Plugin den Provider besitzt; sie konsumieren den + gemeinsamen Fähigkeitsvertrag, den der Kern bereitstellt -Das ist die entscheidende Unterscheidung: +Das ist die zentrale Unterscheidung: -- **plugin** = Eigentumsgrenze -- **capability** = Core-Vertrag, den mehrere Plugins implementieren oder nutzen können +- **Plugin** = Ownership-Grenze +- **Fähigkeit** = Kernvertrag, den mehrere Plugins implementieren oder konsumieren können -Wenn OpenClaw also einen neuen Bereich wie Video hinzufügt, lautet die erste Frage nicht -„welcher Provider sollte Videoverarbeitung hart codieren?“ Die erste Frage ist: -„wie lautet der Core-Vertrag für die Videofähigkeit?“ Sobald dieser Vertrag existiert, -können Anbieter-Plugins sich dafür registrieren, und Kanal-/Feature-Plugins können ihn nutzen. +Wenn OpenClaw also eine neue Domäne wie Video hinzufügt, ist die erste Frage nicht +„welcher Provider sollte die Videoverarbeitung fest einkodieren?“ Die erste Frage lautet „wie sieht +der Kernvertrag für die Videofähigkeit aus?“ Sobald dieser Vertrag existiert, können sich Anbieter- +Plugins dagegen registrieren und Kanal-/Feature-Plugins ihn konsumieren. -Wenn die Fähigkeit noch nicht existiert, ist der richtige Schritt normalerweise: +Wenn die Fähigkeit noch nicht existiert, ist der richtige Weg in der Regel: -1. die fehlende Fähigkeit im Core definieren +1. die fehlende Fähigkeit im Kern definieren 2. sie typisiert über die Plugin-API/Laufzeit verfügbar machen -3. Kanäle/Features an diese Fähigkeit anbinden -4. Anbieter-Plugins ihre Implementierungen registrieren lassen +3. Kanäle/Features gegen diese Fähigkeit verdrahten +4. Anbieter-Plugins Implementierungen registrieren lassen -Dadurch bleibt Eigentum explizit, während vermieden wird, dass Core-Verhalten von einem -einzigen Anbieter oder einem einmaligen pluginspezifischen Codepfad abhängt. +So bleibt Ownership explizit, ohne Kernverhalten zu schaffen, das von +einem einzelnen Anbieter oder einem einmaligen plugin-spezifischen Codepfad abhängt. -### Fähigkeitsschichtung +### Schichtung von Fähigkeiten -Verwenden Sie dieses mentale Modell, wenn Sie entscheiden, wohin Code gehört: +Verwenden Sie dieses mentale Modell, um zu entscheiden, wohin Code gehört: -- **Core-Fähigkeitsschicht**: gemeinsame Orchestrierung, Richtlinien, Fallback, Konfigurations- - Merge-Regeln, Auslieferungssemantik und typisierte Verträge +- **Kern-Fähigkeitsschicht**: gemeinsame Orchestrierung, Richtlinien, Fallback, Konfigurations- + Merge-Regeln, Bereitstellungssemantik und typisierte Verträge - **Anbieter-Plugin-Schicht**: anbieterspezifische APIs, Authentifizierung, Modellkataloge, Sprach- - synthese, Bildgenerierung, künftige Video-Backends, Usage-Endpunkte -- **Kanal-/Feature-Plugin-Schicht**: Slack-/Discord-/voice-call-/usw.-Integration, - die Core-Fähigkeiten nutzt und sie auf einer Oberfläche präsentiert + synthese, Bildgenerierung, zukünftige Video-Backends, Nutzungsendpunkte +- **Kanal-/Feature-Plugin-Schicht**: Slack/Discord/voice-call/etc.-Integration, + die Kernfähigkeiten konsumiert und auf einer Oberfläche präsentiert Zum Beispiel folgt TTS dieser Form: -- der Core besitzt TTS-Richtlinie zur Antwortzeit, Fallback-Reihenfolge, Präferenzen und Kanalauslieferung -- `openai`, `elevenlabs` und `microsoft` besitzen Synthese-Implementierungen -- `voice-call` nutzt die Laufzeit-Hilfsfunktion für Telephony-TTS +- der Kern besitzt TTS-Richtlinien zur Antwortzeit, Fallback-Reihenfolge, Präferenzen und Kanalzustellung +- `openai`, `elevenlabs` und `microsoft` besitzen Syntheseimplementierungen +- `voice-call` konsumiert den Laufzeithelfer für Telefonie-TTS -Dasselbe Muster sollte für künftige Fähigkeiten bevorzugt werden. +Dasselbe Muster sollte für zukünftige Fähigkeiten bevorzugt werden. ### Beispiel für ein Unternehmens-Plugin mit mehreren Fähigkeiten Ein Unternehmens-Plugin sollte sich von außen kohärent anfühlen. Wenn OpenClaw gemeinsame -Verträge für Modelle, Sprache, Echtzeit-Transkription, Echtzeit-Stimme, Medien- +Verträge für Modelle, Sprache, Echtzeit-Transkription, Echtzeit-Sprache, Medien- verständnis, Bildgenerierung, Videogenerierung, Web-Abruf und Websuche hat, kann ein Anbieter alle seine Oberflächen an einer Stelle besitzen: @@ -363,62 +363,63 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Wichtig sind nicht die exakten Hilfsnamen. Wichtig ist die Form: +Entscheidend sind nicht die exakten Helper-Namen. Entscheidend ist die Form: - ein Plugin besitzt die Anbieteroberfläche -- der Core besitzt weiterhin die Fähigkeitsverträge -- Kanäle und Feature-Plugins nutzen `api.runtime.*`-Hilfsfunktionen, keinen Anbietercode -- Vertragstests können prüfen, dass das Plugin die Fähigkeiten registriert hat, die - es zu besitzen beansprucht +- der Kern besitzt weiterhin die Fähigkeitsverträge +- Kanäle und Feature-Plugins konsumieren `api.runtime.*`-Helfer, nicht Anbieter-Code +- Vertragstests können prüfen, dass das Plugin die Fähigkeiten registriert hat, die es + laut eigener Angabe besitzt ### Fähigkeitsbeispiel: Videoverständnis OpenClaw behandelt Bild-/Audio-/Videoverständnis bereits als eine gemeinsame -Fähigkeit. Dasselbe Eigentumsmodell gilt dort: +Fähigkeit. Dasselbe Ownership-Modell gilt auch hier: -1. der Core definiert den Vertrag für Medienverständnis -2. Anbieter-Plugins registrieren `describeImage`, `transcribeAudio` und - `describeVideo`, je nach Anwendbarkeit -3. Kanal- und Feature-Plugins nutzen das gemeinsame Core-Verhalten, statt direkt an Anbietercode anzubinden +1. der Kern definiert den Vertrag für Medienverständnis +2. Anbieter-Plugins registrieren je nach Bedarf `describeImage`, `transcribeAudio` und + `describeVideo` +3. Kanal- und Feature-Plugins konsumieren das gemeinsame Kernverhalten, statt + direkt mit Anbieter-Code verdrahtet zu sein -Dadurch wird vermieden, dass die Videoannahmen eines Providers in den Core eingebrannt werden. Das Plugin besitzt -die Anbieteroberfläche; der Core besitzt den Fähigkeitsvertrag und das Fallback-Verhalten. +Dadurch wird vermieden, die Video-Annahmen eines einzelnen Providers in den Kern einzubacken. Das Plugin besitzt +die Anbieteroberfläche; der Kern besitzt den Fähigkeitsvertrag und das Fallback-Verhalten. -Videogenerierung verwendet bereits dieselbe Abfolge: Der Core besitzt den typisierten -Fähigkeitsvertrag und die Laufzeit-Hilfsfunktion, und Anbieter-Plugins registrieren -`api.registerVideoGenerationProvider(...)`-Implementierungen dafür. +Die Videogenerierung folgt bereits derselben Sequenz: Der Kern besitzt den typisierten +Fähigkeitsvertrag und den Laufzeithelfer, und Anbieter-Plugins registrieren +`api.registerVideoGenerationProvider(...)`-Implementierungen dagegen. -Brauchen Sie eine konkrete Rollout-Checkliste? Siehe +Sie brauchen eine konkrete Checkliste für die Einführung? Siehe [Capability Cookbook](/de/plugins/architecture). ## Verträge und Durchsetzung -Die Oberfläche der Plugin-API ist bewusst typisiert und in -`OpenClawPluginApi` zentralisiert. Dieser Vertrag definiert die unterstützten Registrierungsstellen und -die Laufzeit-Hilfsfunktionen, auf die sich ein Plugin verlassen darf. +Die Oberfläche der Plugin-API ist absichtlich typisiert und in +`OpenClawPluginApi` zentralisiert. Dieser Vertrag definiert die unterstützten Registrierungspunkte und +die Laufzeit-Helfer, auf die sich ein Plugin verlassen darf. Warum das wichtig ist: -- Plugin-Autoren erhalten einen stabilen internen Standard -- der Core kann doppelte Eigentümerschaft ablehnen, etwa wenn zwei Plugins dieselbe +- Plugin-Autorinnen und -Autoren erhalten einen stabilen internen Standard +- der Kern kann doppelte Ownership ablehnen, etwa wenn zwei Plugins dieselbe Provider-ID registrieren -- der Start kann umsetzbare Diagnosen für fehlerhafte Registrierungen anzeigen -- Vertragstests können Eigentümerschaft gebündelter Plugins durchsetzen und stilles Drift verhindern +- beim Start können verwertbare Diagnosen für fehlerhafte Registrierungen ausgegeben werden +- Vertragstests können die Ownership gebündelter Plugins durchsetzen und stilles Driften verhindern Es gibt zwei Ebenen der Durchsetzung: 1. **Durchsetzung bei der Laufzeitregistrierung** - Die Plugin-Registry validiert Registrierungen, während Plugins geladen werden. Beispiele: - doppelte Provider-IDs, doppelte Sprach-Provider-IDs und fehlerhafte - Registrierungen erzeugen Plugin-Diagnosen statt undefinierten Verhaltens. + Die Plugin-Registry validiert Registrierungen während Plugins geladen werden. Beispiele: + doppelte Provider-IDs, doppelte Speech-Provider-IDs und fehlerhafte + Registrierungen erzeugen Plugin-Diagnosen statt undefiniertem Verhalten. 2. **Vertragstests** Gebündelte Plugins werden in Vertrag-Registries während Testläufen erfasst, damit - OpenClaw Eigentümerschaft explizit prüfen kann. Heute wird dies für Modell- - Provider, Sprach-Provider, Websuch-Provider und Eigentümerschaft gebündelter Registrierungen verwendet. + OpenClaw Ownership explizit prüfen kann. Heute wird dies für Modell- + provider, Speech-Provider, Websuch-Provider und die Ownership gebündelter Registrierungen verwendet. -Der praktische Effekt ist, dass OpenClaw im Voraus weiß, welches Plugin welche -Oberfläche besitzt. Dadurch können Core und Kanäle nahtlos zusammenspielen, weil Eigentum -deklariert, typisiert und testbar statt implizit ist. +Der praktische Effekt ist, dass OpenClaw von Anfang an weiß, welches Plugin welche +Oberfläche besitzt. Dadurch können Kern und Kanäle nahtlos zusammenspielen, weil Ownership +deklariert, typisiert und testbar ist statt implizit. ### Was in einen Vertrag gehört @@ -427,101 +428,101 @@ Gute Plugin-Verträge sind: - typisiert - klein - fähigkeitsspezifisch -- im Besitz des Core -- für mehrere Plugins wiederverwendbar -- für Kanäle/Features ohne Anbieterwissen nutzbar +- im Besitz des Kerns +- von mehreren Plugins wiederverwendbar +- von Kanälen/Features ohne Anbieterwissen konsumierbar Schlechte Plugin-Verträge sind: -- anbieterspezifische Richtlinien, die im Core versteckt sind -- einmalige Plugin-Fluchtwege, die die Registry umgehen -- Kanalcode, der direkt in eine Anbieterimplementierung greift -- ad hoc Laufzeitobjekte, die nicht Teil von `OpenClawPluginApi` oder +- im Kern versteckte anbieterspezifische Richtlinien +- einmalige Plugin-Escape-Hatches, die die Registry umgehen +- Kanal-Code, der direkt in eine Anbieterimplementierung greift +- ad hoc erzeugte Laufzeitobjekte, die nicht Teil von `OpenClawPluginApi` oder `api.runtime` sind -Im Zweifel die Abstraktionsebene anheben: zuerst die Fähigkeit definieren, dann -Plugins daran andocken lassen. +Wenn Sie unsicher sind, heben Sie die Abstraktionsebene an: Definieren Sie zuerst die Fähigkeit und +lassen Sie dann Plugins daran andocken. ## Ausführungsmodell Native OpenClaw-Plugins laufen **im Prozess** mit dem Gateway. Sie sind nicht -sandboxed. Ein geladenes natives Plugin hat dieselbe Vertrauensgrenze auf Prozessebene wie -Core-Code. +sandboxed. Ein geladenes natives Plugin hat dieselbe Vertrauen-Grenze auf Prozessebene wie +Kerncode. Auswirkungen: -- ein natives Plugin kann Tools, Netzwerk-Handler, Hooks und Dienste registrieren -- ein Fehler in einem nativen Plugin kann das Gateway abstürzen lassen oder destabilisieren -- ein bösartiges natives Plugin entspricht beliebiger Codeausführung innerhalb des - OpenClaw-Prozesses +- ein natives Plugin kann Tools, Netzwerk-Handler, Hooks und Services registrieren +- ein Fehler in einem nativen Plugin kann das Gateway zum Absturz bringen oder destabilisieren +- ein bösartiges natives Plugin ist gleichbedeutend mit beliebiger Codeausführung innerhalb + des OpenClaw-Prozesses -Kompatible Bundles sind standardmäßig sicherer, weil OpenClaw sie derzeit als -Metadaten-/Content-Pakete behandelt. In aktuellen Releases bedeutet das meist +Kompatible Bundles sind standardmäßig sicherer, weil OpenClaw sie derzeit +als Metadaten-/Content-Pakete behandelt. In aktuellen Releases bedeutet das meist gebündelte Skills. Verwenden Sie Allowlists und explizite Installations-/Ladepfade für nicht gebündelte Plugins. Behandeln Sie -Workspace-Plugins als Entwicklungscode, nicht als Produktionsstandard. +Workspace-Plugins als Entwicklungszeit-Code, nicht als Produktionsstandard. -Bei Namen gebündelter Workspace-Pakete sollte die Plugin-ID im npm- +Bei gebündelten Workspace-Paketnamen sollte die Plugin-ID im npm- Namen verankert bleiben: standardmäßig `@openclaw/` oder ein genehmigtes typisiertes Suffix wie `-provider`, `-plugin`, `-speech`, `-sandbox` oder `-media-understanding`, wenn -das Paket absichtlich eine schmalere Plugin-Rolle exponiert. +das Paket absichtlich eine engere Plugin-Rolle bereitstellt. -Wichtiger Hinweis zum Vertrauen: +Wichtiger Vertrauenshinweis: -- `plugins.allow` vertraut **Plugin-IDs**, nicht der Herkunft des Quellcodes. +- `plugins.allow` vertraut **Plugin-IDs**, nicht der Herkunft der Quelle. - Ein Workspace-Plugin mit derselben ID wie ein gebündeltes Plugin überschattet - absichtlich die gebündelte Kopie, wenn dieses Workspace-Plugin aktiviert/auf der Allowlist ist. + absichtlich die gebündelte Kopie, wenn dieses Workspace-Plugin aktiviert/allowlisted ist. - Das ist normal und nützlich für lokale Entwicklung, Patch-Tests und Hotfixes. ## Exportgrenze -OpenClaw exportiert Fähigkeiten, nicht bequeme Implementierungsdetails. +OpenClaw exportiert Fähigkeiten, keine Implementierungs-Convenience. -Halten Sie die Fähigkeitsregistrierung öffentlich. Straffen Sie nichtvertragliche Hilfsexporte: +Halten Sie Fähigkeitsregistrierungen öffentlich. Reduzieren Sie nicht-vertragliche Helper-Exporte: -- gebündelte pluginspezifische Hilfs-Subpaths -- Laufzeit-Subpaths, die nicht als öffentliche API gedacht sind -- anbieterspezifische Convenience-Hilfsfunktionen -- Setup-/Onboarding-Hilfsfunktionen, die Implementierungsdetails sind +- gebündelte plugin-spezifische Helper-Subpaths +- Laufzeit-Plumbing-Subpaths, die nicht als öffentliche API gedacht sind +- anbieterspezifische Convenience-Helper +- Setup-/Onboarding-Helfer, die Implementierungsdetails sind -Einige Hilfs-Subpaths gebündelter Plugins verbleiben aus Kompatibilitäts- und Wartungsgründen -weiterhin in der generierten SDK-Export-Map. Aktuelle Beispiele sind +Einige Helper-Subpaths gebündelter Plugins verbleiben aus Kompatibilitäts- und Wartungsgründen +weiterhin in der generierten SDK-Exportzuordnung. Aktuelle Beispiele sind `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` und mehrere `plugin-sdk/matrix*`-Seams. Behandeln Sie diese als -reservierte Exporte von Implementierungsdetails, nicht als empfohlenes SDK-Muster für -neue Plugins von Drittanbietern. +reservierte Exporte für Implementierungsdetails, nicht als empfohlenes SDK-Muster für +neue Drittanbieter-Plugins. ## Ladepipeline -Beim Start macht OpenClaw ungefähr Folgendes: +Beim Start macht OpenClaw grob Folgendes: -1. Kandidaten-Plugin-Wurzeln entdecken +1. potenzielle Plugin-Wurzeln entdecken 2. native oder kompatible Bundle-Manifeste und Paketmetadaten lesen 3. unsichere Kandidaten ablehnen 4. Plugin-Konfiguration normalisieren (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. für jeden Kandidaten die Aktivierung entscheiden -6. aktivierte native Module über jiti laden -7. native Hooks `register(api)` (oder `activate(api)` — ein älterer Alias) aufrufen und Registrierungen in der Plugin-Registry sammeln -8. die Registry CLI-/Laufzeitoberflächen bereitstellen +5. Aktivierung für jeden Kandidaten entscheiden +6. aktivierte native Module per jiti laden +7. native Hooks `register(api)` (oder `activate(api)` — ein Legacy-Alias) aufrufen und Registrierungen in die Plugin-Registry einsammeln +8. die Registry für Befehle/Laufzeitoberflächen bereitstellen -`activate` ist ein älterer Alias für `register` — der Loader löst die jeweils vorhandene Variante auf (`def.register ?? def.activate`) und ruft sie an derselben Stelle auf. Alle gebündelten Plugins verwenden `register`; für neue Plugins `register` bevorzugen. +`activate` ist ein Legacy-Alias für `register` — der Loader löst auf, was vorhanden ist (`def.register ?? def.activate`), und ruft es an derselben Stelle auf. Alle gebündelten Plugins verwenden `register`; bevorzugen Sie `register` für neue Plugins. -Die Sicherheitsprüfungen finden **vor** der Laufzeitausführung statt. Kandidaten werden blockiert, -wenn der Entry aus der Plugin-Wurzel herausführt, der Pfad weltbeschreibbar ist oder die Eigentümerschaft -des Pfads bei nicht gebündelten Plugins verdächtig aussieht. +Die Sicherheitsprüfungen erfolgen **vor** der Laufzeitausführung. Kandidaten werden blockiert, +wenn der Einstiegspunkt die Plugin-Wurzel verlässt, der Pfad weltweit beschreibbar ist oder die Pfad- +Ownership bei nicht gebündelten Plugins verdächtig aussieht. -### Manifest-First-Verhalten +### Manifest-first-Verhalten -Das Manifest ist die Quelle der Wahrheit für die Control Plane. OpenClaw verwendet es, um: +Das Manifest ist die Quelle der Wahrheit auf der Control-Plane. OpenClaw verwendet es, um: - das Plugin zu identifizieren -- deklarierte Kanäle/Skills/Konfigurationsschema oder Bundle-Fähigkeiten zu erkennen +- deklarierte Kanäle/Skills/Konfigurationsschema oder Bundle-Fähigkeiten zu entdecken - `plugins.entries..config` zu validieren -- Labels/Platzhalter der Control UI anzureichern +- Labels/Platzhalter in der Control UI zu ergänzen - Installations-/Katalogmetadaten anzuzeigen Für native Plugins ist das Laufzeitmodul der Data-Plane-Teil. Es registriert @@ -532,13 +533,13 @@ tatsächliches Verhalten wie Hooks, Tools, Befehle oder Provider-Flows. OpenClaw hält kurze In-Process-Caches für: - Discovery-Ergebnisse -- Manifest-Registry-Daten +- Daten der Manifest-Registry - geladene Plugin-Registries -Diese Caches reduzieren burstige Starts und den Overhead wiederholter Befehle. Es ist sinnvoll, -sie als kurzlebige Performance-Caches und nicht als Persistenz zu betrachten. +Diese Caches reduzieren burstartige Starts und den Overhead wiederholter Befehle. Man kann sie +als kurzlebige Performance-Caches betrachten, nicht als Persistenz. -Hinweis zur Performance: +Leistungshinweis: - Setzen Sie `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` oder `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, um diese Caches zu deaktivieren. @@ -547,37 +548,37 @@ Hinweis zur Performance: ## Registry-Modell -Geladene Plugins mutieren nicht direkt zufällige globale Objekte des Core. Sie registrieren sich in einer +Geladene Plugins verändern nicht direkt beliebige globale Kernzustände. Sie registrieren sich in einer zentralen Plugin-Registry. Die Registry verfolgt: - Plugin-Einträge (Identität, Quelle, Herkunft, Status, Diagnosen) - Tools -- ältere Hooks und typisierte Hooks +- Legacy-Hooks und typisierte Hooks - Kanäle - Provider - Gateway-RPC-Handler - HTTP-Routen - CLI-Registrare -- Hintergrunddienste +- Hintergrund-Services - plugin-eigene Befehle -Core-Features lesen dann aus dieser Registry, statt direkt mit Plugin-Modulen zu sprechen. -Das hält das Laden einseitig: +Kern-Features lesen dann aus dieser Registry, statt direkt mit Plugin-Modulen +zu sprechen. Dadurch bleibt das Laden eindirektional: - Plugin-Modul -> Registry-Registrierung -- Core-Laufzeit -> Registry-Konsum +- Kern-Laufzeit -> Registry-Konsum -Diese Trennung ist wichtig für die Wartbarkeit. Sie bedeutet, dass die meisten Core-Oberflächen -nur einen Integrationspunkt brauchen: „die Registry lesen“, nicht „jedes Plugin-Modul gesondert behandeln“. +Diese Trennung ist für die Wartbarkeit wichtig. Sie bedeutet, dass die meisten Kernoberflächen nur +einen Integrationspunkt brauchen: „Registry lesen“, nicht „jedes Plugin-Modul gesondert behandeln“. -## Callbacks für Gesprächsbindungen +## Callbacks für Konversationsbindung -Plugins, die ein Gespräch binden, können reagieren, wenn eine Genehmigung aufgelöst wird. +Plugins, die eine Konversation binden, können reagieren, wenn eine Genehmigung entschieden wurde. -Verwenden Sie `api.onConversationBindingResolved(...)`, um nach Genehmigung oder Ablehnung einer -Bindungsanfrage einen Callback zu erhalten: +Verwenden Sie `api.onConversationBindingResolved(...)`, um einen Callback zu erhalten, nachdem eine Bindungs- +anfrage genehmigt oder abgelehnt wurde: ```ts export default { @@ -602,21 +603,22 @@ Felder der Callback-Nutzlast: - `status`: `"approved"` oder `"denied"` - `decision`: `"allow-once"`, `"allow-always"` oder `"deny"` - `binding`: die aufgelöste Bindung für genehmigte Anfragen -- `request`: die ursprüngliche Anfragezusammenfassung, Detach-Hinweis, Sender-ID und - Gesprächsmetadaten +- `request`: die ursprüngliche Anforderungszusammenfassung, Detach-Hinweis, Sender-ID und + Konversationsmetadaten -Dieser Callback dient nur zur Benachrichtigung. Er ändert nicht, wer ein Gespräch binden darf, -und er läuft, nachdem die Core-Behandlung der Genehmigung abgeschlossen ist. +Dieser Callback dient nur zur Benachrichtigung. Er ändert nicht, wer eine +Konversation binden darf, und läuft erst, nachdem die Kernbehandlung der Genehmigung abgeschlossen ist. ## Provider-Laufzeit-Hooks Provider-Plugins haben jetzt zwei Ebenen: -- Manifest-Metadaten: `providerAuthEnvVars` für kostengünstige env-basierte Provider-Auth-Suche - vor dem Laden der Laufzeit, `channelEnvVars` für kostengünstige env-/Setup-Suche für Kanäle - vor dem Laden der Laufzeit sowie `providerAuthChoices` für kostengünstige Labels bei Onboarding/Auth-Auswahl - und CLI-Flag-Metadaten vor dem Laden der Laufzeit -- Hooks zur Konfigurationszeit: `catalog` / älteres `discovery` plus `applyConfigDefaults` +- Manifest-Metadaten: `providerAuthEnvVars` für günstige Provider- + Env-Auth-Erkennung vor dem Laden der Laufzeit, `providerAuthAliases` für Provider-Varianten, die sich + Auth teilen, `channelEnvVars` für günstige Kanal-Env-/Setup-Erkennung vor dem + Laden der Laufzeit sowie `providerAuthChoices` für günstige Labels bei Onboarding/Auth-Auswahl und + CLI-Flag-Metadaten vor dem Laden der Laufzeit +- Hooks zur Konfigurationszeit: `catalog` / Legacy-`discovery` sowie `applyConfigDefaults` - Laufzeit-Hooks: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -637,83 +639,86 @@ Provider-Plugins haben jetzt zwei Ebenen: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw besitzt weiterhin die generische Agent-Schleife, das Failover, die Transkriptbehandlung und -die Tool-Richtlinien. Diese Hooks sind die Erweiterungsoberfläche für providerspezifisches Verhalten, ohne -einen vollständig benutzerdefinierten Inferenz-Transport zu benötigen. +OpenClaw besitzt weiterhin die generische Agent-Schleife, den Failover, die Verarbeitung von Transkripten und +Tool-Richtlinien. Diese Hooks sind die Erweiterungsoberfläche für anbieterspezifisches Verhalten, ohne +einen vollständig benutzerdefinierten Inferenztransport zu benötigen. -Verwenden Sie Manifest-`providerAuthEnvVars`, wenn der Provider env-basierte Zugangsdaten hat, -die generische Auth-/Status-/Model-Picker-Pfade sehen sollen, ohne die Plugin-Laufzeit zu laden. -Verwenden Sie Manifest-`providerAuthChoices`, wenn Oberflächen für Onboarding/Auth-Auswahl in der CLI -die Choice-ID, Gruppenlabels und einfache -Auth-Verdrahtung per einzelner Flag des Providers kennen sollen, ohne die Provider-Laufzeit zu laden. Behalten Sie Provider-Laufzeit- -`envVars` für operatorseitige Hinweise wie Onboarding-Labels oder Variablen für die Einrichtung von OAuth- -Client-ID/Client-Secret bei. +Verwenden Sie das Manifest `providerAuthEnvVars`, wenn der Provider env-basierte +Anmeldedaten hat, die generische Auth-/Status-/Modell-Picker-Pfade sehen sollen, ohne die Plugin-Laufzeit +zu laden. Verwenden Sie Manifest-`providerAuthAliases`, wenn eine Provider-ID die Env-Variablen, +Auth-Profile, konfigurationsgestützte Auth und die API-Key-Onboarding-Wahl einer anderen Provider-ID +wiederverwenden soll. Verwenden Sie Manifest-`providerAuthChoices`, wenn CLI-Oberflächen +für Onboarding/Auth-Auswahl die Choice-ID des Providers, Gruppenlabels und einfache +Auth-Verdrahtung per Einzelflag kennen sollen, ohne die Provider-Laufzeit zu laden. Behalten Sie in der Provider-Laufzeit +`envVars` für operatorseitige Hinweise wie Onboarding-Labels oder +Setup-Variablen für OAuth-Client-ID/Client-Secret. -Verwenden Sie Manifest-`channelEnvVars`, wenn ein Kanal env-gesteuerte Authentifizierung oder Einrichtung hat, -die generischer Shell-env-Fallback, Prüfungen von Konfiguration/Status oder Setup-Abfragen sehen sollen, -ohne die Kanallaufzeit zu laden. +Verwenden Sie Manifest-`channelEnvVars`, wenn ein Kanal env-gesteuerte Auth oder Einrichtung hat, +die generischer Shell-Env-Fallback, Konfigurations-/Statusprüfungen oder Setup-Prompts sehen sollen, +ohne die Kanal-Laufzeit zu laden. ### Hook-Reihenfolge und Verwendung Für Modell-/Provider-Plugins ruft OpenClaw Hooks ungefähr in dieser Reihenfolge auf. -Die Spalte „Verwendung“ ist die schnelle Entscheidungshilfe. +Die Spalte „Wann verwenden“ ist die schnelle Entscheidungshilfe. -| # | Hook | Was er tut | Verwendung | -| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Veröffentlicht Provider-Konfiguration in `models.providers` während der Generierung von `models.json` | Der Provider besitzt einen Katalog oder Standardwerte für `baseUrl` | -| 2 | `applyConfigDefaults` | Wendet provider-eigene globale Konfigurationsstandards während der Konfigurationsmaterialisierung an | Standards hängen von Auth-Modus, Umgebung oder der Semantik der Modellfamilie des Providers ab | -| -- | _(built-in model lookup)_ | OpenClaw versucht zuerst den normalen Registry-/Katalogpfad | _(kein Plugin-Hook)_ | -| 3 | `normalizeModelId` | Normalisiert ältere oder Preview-Modell-ID-Aliasse vor dem Lookup | Der Provider besitzt Alias-Bereinigung vor der kanonischen Modellauflösung | -| 4 | `normalizeTransport` | Normalisiert `api` / `baseUrl` der Provider-Familie vor der generischen Modellassemblierung | Der Provider besitzt Transport-Bereinigung für benutzerdefinierte Provider-IDs in derselben Transportfamilie | -| 5 | `normalizeConfig` | Normalisiert `models.providers.` vor Laufzeit-/Provider-Auflösung | Der Provider benötigt Konfigurationsbereinigung, die beim Plugin liegen sollte; gebündelte Hilfsfunktionen der Google-Familie stützen außerdem unterstützte Google-Konfigurationseinträge ab | -| 6 | `applyNativeStreamingUsageCompat` | Wendet native Umschreibungen für Streaming-Usage-Kompatibilität auf Konfigurations-Provider an | Der Provider benötigt endpointgesteuerte Korrekturen an nativen Streaming-Usage-Metadaten | -| 7 | `resolveConfigApiKey` | Löst env-marker-Authentifizierung für Konfigurations-Provider vor dem Laden der Laufzeit-Auth auf | Der Provider besitzt eigene API-Key-Auflösung über env-marker; `amazon-bedrock` hat hier ebenfalls einen eingebauten AWS-env-marker-Resolver | -| 8 | `resolveSyntheticAuth` | Macht lokale/self-hosted oder konfigurationsgestützte Auth sichtbar, ohne Klartext zu persistieren | Der Provider kann mit einem synthetischen/lokalen Zugangsdaten-Marker arbeiten | -| 9 | `resolveExternalAuthProfiles` | Legt provider-eigene externe Auth-Profile darüber; Standard-`persistence` ist `runtime-only` für CLI-/app-eigene Zugangsdaten | Der Provider verwendet externe Auth-Zugangsdaten wieder, ohne kopierte Refresh-Tokens zu persistieren | -| 10 | `shouldDeferSyntheticProfileAuth` | Ordnet gespeicherte Platzhalterprofile für synthetische Profile hinter env-/konfigurationsgestützter Auth ein | Der Provider speichert synthetische Platzhalterprofile, die nicht Vorrang haben sollten | -| 11 | `resolveDynamicModel` | Synchroner Fallback für provider-eigene Modell-IDs, die noch nicht in der lokalen Registry sind | Der Provider akzeptiert beliebige Upstream-Modell-IDs | -| 12 | `prepareDynamicModel` | Asynchrones Warm-up, dann läuft `resolveDynamicModel` erneut | Der Provider benötigt Netzwerkmetadaten, bevor unbekannte IDs aufgelöst werden können | -| 13 | `normalizeResolvedModel` | Letzte Umschreibung, bevor der Embedded-Runner das aufgelöste Modell verwendet | Der Provider benötigt Transport-Umschreibungen, verwendet aber weiterhin einen Core-Transport | -| 14 | `contributeResolvedModelCompat` | Liefert Kompatibilitäts-Flags für Anbietermodelle hinter einem anderen kompatiblen Transport | Der Provider erkennt seine eigenen Modelle auf Proxy-Transporten, ohne den Provider zu übernehmen | -| 15 | `capabilities` | Provider-eigene Transkript-/Tooling-Metadaten, die von geteilter Core-Logik genutzt werden | Der Provider benötigt Eigenheiten von Transkript/Provider-Familie | -| 16 | `normalizeToolSchemas` | Normalisiert Tool-Schemas, bevor der Embedded-Runner sie sieht | Der Provider benötigt schema-bezogene Bereinigung für die Transportfamilie | -| 17 | `inspectToolSchemas` | Macht provider-eigene Schema-Diagnosen nach der Normalisierung sichtbar | Der Provider möchte Keyword-Warnungen anzeigen, ohne dem Core providerspezifische Regeln beizubringen | -| 18 | `resolveReasoningOutputMode` | Wählt nativen oder getaggten Vertrag für den Reasoning-Output | Der Provider benötigt getaggten Reasoning-/Final-Output statt nativer Felder | -| 19 | `prepareExtraParams` | Normalisierung von Anfrageparametern vor generischen Stream-Option-Wrappern | Der Provider benötigt Standard-Anfrageparameter oder providerspezifische Bereinigung pro Provider | -| 20 | `createStreamFn` | Ersetzt den normalen Stream-Pfad vollständig durch einen benutzerdefinierten Transport | Der Provider benötigt ein benutzerdefiniertes Wire-Protokoll, nicht nur einen Wrapper | -| 21 | `wrapStreamFn` | Stream-Wrapper, nachdem generische Wrapper angewendet wurden | Der Provider benötigt Wrapper für Anfrage-Header/Body/Modell-Kompatibilität ohne benutzerdefinierten Transport | -| 22 | `resolveTransportTurnState` | Hängt native Header oder Metadaten pro Zug an den Transport | Der Provider möchte, dass generische Transporte provider-native Zug-Identität senden | -| 23 | `resolveWebSocketSessionPolicy` | Hängt native WebSocket-Header oder Session-Cooldown-Richtlinien an | Der Provider möchte, dass generische WS-Transporte Session-Header oder Fallback-Richtlinien anpassen | -| 24 | `formatApiKey` | Auth-Profil-Formatter: gespeichertes Profil wird zur Laufzeit-Zeichenfolge `apiKey` | Der Provider speichert zusätzliche Auth-Metadaten und benötigt eine benutzerdefinierte Laufzeit-Tokenform | -| 25 | `refreshOAuth` | OAuth-Refresh-Override für benutzerdefinierte Refresh-Endpunkte oder Richtlinien bei Refresh-Fehlern | Der Provider passt nicht zu den gemeinsamen `pi-ai`-Refreshern | -| 26 | `buildAuthDoctorHint` | Reparaturhinweis, der angehängt wird, wenn OAuth-Refresh fehlschlägt | Der Provider benötigt provider-eigene Hinweise zur Reparatur der Auth nach Refresh-Fehler | -| 27 | `matchesContextOverflowError` | Provider-eigener Matcher für Überläufe des Kontextfensters | Der Provider hat rohe Überlauffehler, die generische Heuristiken übersehen würden | -| 28 | `classifyFailoverReason` | Provider-eigene Klassifikation von Failover-Gründen | Der Provider kann rohe API-/Transportfehler auf Rate-Limit/Überlastung/usw. abbilden | -| 29 | `isCacheTtlEligible` | Prompt-Cache-Richtlinie für Proxy-/Backhaul-Provider | Der Provider benötigt proxiespezifisches Cache-TTL-Gating | -| 30 | `buildMissingAuthMessage` | Ersatz für die generische Recovery-Nachricht bei fehlender Auth | Der Provider benötigt einen providerspezifischen Hinweis zur Wiederherstellung bei fehlender Auth | +| # | Hook | Was er macht | Wann verwenden | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Provider-Konfiguration bei der Generierung von `models.json` in `models.providers` veröffentlichen | Der Provider besitzt einen Katalog oder Standardwerte für `baseUrl` | +| 2 | `applyConfigDefaults` | plugin-eigene globale Konfigurationsstandards während der Konfigurationsmaterialisierung anwenden | Standardwerte hängen von Auth-Modus, Env oder der Semantik der Provider-Modellfamilie ab | +| -- | _(integrierte Modellsuche)_ | OpenClaw versucht zuerst den normalen Registry-/Katalog-Pfad | _(kein Plugin-Hook)_ | +| 3 | `normalizeModelId` | Legacy- oder Preview-Aliase für Modell-IDs vor der Suche normalisieren | Der Provider besitzt Alias-Bereinigung vor der kanonischen Modellauflösung | +| 4 | `normalizeTransport` | Provider-Familien-`api` / `baseUrl` vor generischer Modellzusammenstellung normalisieren | Der Provider besitzt Transport-Bereinigung für benutzerdefinierte Provider-IDs in derselben Transportfamilie | +| 5 | `normalizeConfig` | `models.providers.` vor Laufzeit-/Provider-Auflösung normalisieren | Der Provider benötigt Konfigurationsbereinigung, die beim Plugin leben sollte; gebündelte Google-Familien-Helper fangen auch unterstützte Google-Konfigurationseinträge ab | +| 6 | `applyNativeStreamingUsageCompat` | Native Streaming-Usage-Kompatibilitäts-Umschreibungen auf Konfigurationsprovider anwenden | Der Provider benötigt endpunktgesteuerte Korrekturen für native Streaming-Usage-Metadaten | +| 7 | `resolveConfigApiKey` | Env-Marker-Auth für Konfigurationsprovider vor dem Laden der Laufzeit-Auth auflösen | Der Provider besitzt eine plugin-eigene Auflösung von Env-Marker-API-Keys; `amazon-bedrock` hat hier ebenfalls einen eingebauten AWS-Env-Marker-Resolver | +| 8 | `resolveSyntheticAuth` | lokale/self-hosted oder konfigurationsgestützte Auth anzeigen, ohne Klartext zu persistieren | Der Provider kann mit einem synthetischen/lokalen Credential-Marker arbeiten | +| 9 | `resolveExternalAuthProfiles` | plugin-eigene externe Auth-Profile überlagern; Standard-`persistence` ist `runtime-only` für CLI-/app-eigene Credentials | Der Provider verwendet externe Auth-Credentials wieder, ohne kopierte Refresh-Tokens zu persistieren | +| 10 | `shouldDeferSyntheticProfileAuth` | gespeicherte synthetische Profil-Platzhalter hinter env-/konfigurationsgestützter Auth zurückstufen | Der Provider speichert synthetische Platzhalterprofile, die keine Priorität haben sollten | +| 11 | `resolveDynamicModel` | synchroner Fallback für plugin-eigene Modell-IDs, die noch nicht in der lokalen Registry sind | Der Provider akzeptiert beliebige Upstream-Modell-IDs | +| 12 | `prepareDynamicModel` | asynchrones Warm-up, dann läuft `resolveDynamicModel` erneut | Der Provider benötigt Netzwerkmetadaten, bevor unbekannte IDs aufgelöst werden können | +| 13 | `normalizeResolvedModel` | endgültige Umschreibung, bevor der Embedded-Runner das aufgelöste Modell verwendet | Der Provider benötigt Transport-Umschreibungen, verwendet aber weiterhin einen Kerntransport | +| 14 | `contributeResolvedModelCompat` | Kompatibilitätsflags für Anbietermodelle hinter einem anderen kompatiblen Transport beisteuern | Der Provider erkennt seine eigenen Modelle auf Proxy-Transporten, ohne den Provider zu übernehmen | +| 15 | `capabilities` | plugin-eigene Transkript-/Tooling-Metadaten, die von gemeinsamer Kernlogik verwendet werden | Der Provider benötigt Besonderheiten für Transkripte/Provider-Familien | +| 16 | `normalizeToolSchemas` | Tool-Schemas normalisieren, bevor der Embedded-Runner sie sieht | Der Provider benötigt schemaseitige Bereinigung für eine Transportfamilie | +| 17 | `inspectToolSchemas` | plugin-eigene Schema-Diagnosen nach der Normalisierung ausgeben | Der Provider möchte Keyword-Warnungen ausgeben, ohne dem Kern anbieterspezifische Regeln beizubringen | +| 18 | `resolveReasoningOutputMode` | nativen versus getaggten Vertrag für Reasoning-Ausgaben auswählen | Der Provider benötigt getaggtes Reasoning/finale Ausgabe statt nativer Felder | +| 19 | `prepareExtraParams` | Normalisierung von Anfrageparametern vor generischen Stream-Option-Wrappern | Der Provider benötigt Standard-Anfrageparameter oder anbieterspezifische Parameterbereinigung | +| 20 | `createStreamFn` | normalen Stream-Pfad vollständig durch einen benutzerdefinierten Transport ersetzen | Der Provider benötigt ein benutzerdefiniertes Wire-Protokoll, nicht nur einen Wrapper | +| 21 | `wrapStreamFn` | Stream-Wrapper, nachdem generische Wrapper angewendet wurden | Der Provider benötigt Wrapper für Anfrageheader/Body/Modell-Kompatibilität ohne benutzerdefinierten Transport | +| 22 | `resolveTransportTurnState` | native turnbezogene Transport-Header oder -Metadaten anhängen | Der Provider möchte, dass generische Transporte die providereigene Turn-Identität senden | +| 23 | `resolveWebSocketSessionPolicy` | native WebSocket-Header oder Richtlinien zur Session-Abkühlung anhängen | Der Provider möchte, dass generische WS-Transporte Session-Header oder Fallback-Richtlinien abstimmen | +| 24 | `formatApiKey` | Auth-Profil-Formatierer: gespeichertes Profil wird zur Laufzeit-Zeichenfolge `apiKey` | Der Provider speichert zusätzliche Auth-Metadaten und benötigt eine benutzerdefinierte Laufzeit-Tokenform | +| 25 | `refreshOAuth` | OAuth-Refresh-Override für benutzerdefinierte Refresh-Endpunkte oder Richtlinien bei Refresh-Fehlschlägen | Der Provider passt nicht zu den gemeinsamen `pi-ai`-Refreshern | +| 26 | `buildAuthDoctorHint` | Reparaturhinweis, der angehängt wird, wenn OAuth-Refresh fehlschlägt | Der Provider benötigt plugin-eigene Hinweise zur Auth-Reparatur nach einem Refresh-Fehler | +| 27 | `matchesContextOverflowError` | plugin-eigener Matcher für Überläufe des Kontextfensters | Der Provider hat rohe Overflow-Fehler, die generische Heuristiken übersehen würden | +| 28 | `classifyFailoverReason` | plugin-eigene Klassifizierung des Failover-Grunds | Der Provider kann rohe API-/Transportfehler auf Ratenbegrenzung/Überlast/etc. abbilden | +| 29 | `isCacheTtlEligible` | Richtlinie für Prompt-Cache bei Proxy-/Backhaul-Providern | Der Provider benötigt proxy-spezifisches Cache-TTL-Gating | +| 30 | `buildMissingAuthMessage` | Ersatz für die generische Wiederherstellungsnachricht bei fehlender Auth | Der Provider benötigt einen provider-spezifischen Hinweis zur Wiederherstellung fehlender Auth | | 31 | `suppressBuiltInModel` | Unterdrückung veralteter Upstream-Modelle plus optionaler benutzerseitiger Fehlerhinweis | Der Provider muss veraltete Upstream-Zeilen ausblenden oder durch einen Anbieterhinweis ersetzen | -| 32 | `augmentModelCatalog` | Synthetische/finale Katalogzeilen, die nach der Discovery angehängt werden | Der Provider benötigt synthetische Zeilen für Forward-Compatibility in `models list` und Pickern | -| 33 | `isBinaryThinking` | Ein/Aus-Toggle für Reasoning bei Providern mit binärem Thinking | Der Provider bietet nur binäres Thinking an/aus an | -| 34 | `supportsXHighThinking` | Unterstützung für `xhigh`-Reasoning bei ausgewählten Modellen | Der Provider möchte `xhigh` nur für eine Teilmenge von Modellen | -| 35 | `resolveDefaultThinkingLevel` | Standard-`/think`-Level für eine bestimmte Modellfamilie | Der Provider besitzt die Standard-`/think`-Richtlinie für eine Modellfamilie | -| 36 | `isModernModelRef` | Matcher für moderne Modelle für Live-Profilfilter und Smoke-Auswahl | Der Provider besitzt das Matching bevorzugter Live-/Smoke-Modelle | -| 37 | `prepareRuntimeAuth` | Tauscht konfigurierte Zugangsdaten direkt vor der Inferenz in den eigentlichen Laufzeit-Token/-Schlüssel um | Der Provider benötigt einen Tokenaustausch oder kurzlebige Anfrage-Zugangsdaten | -| 38 | `resolveUsageAuth` | Löst Usage-/Billing-Zugangsdaten für `/usage` und verwandte Statusoberflächen auf | Der Provider benötigt benutzerdefiniertes Parsing von Usage-/Quota-Tokens oder andere Usage-Zugangsdaten | -| 39 | `fetchUsageSnapshot` | Ruft providerspezifische Usage-/Quota-Snapshots ab und normalisiert sie, nachdem die Auth aufgelöst wurde | Der Provider benötigt einen providerspezifischen Usage-Endpunkt oder Payload-Parser | -| 40 | `createEmbeddingProvider` | Baut einen provider-eigenen Embedding-Adapter für Memory/Suche | Verhalten für Memory-Embeddings gehört in das Provider-Plugin | -| 41 | `buildReplayPolicy` | Gibt eine Replay-Richtlinie zurück, die die Transkriptbehandlung für den Provider steuert | Der Provider benötigt eine benutzerdefinierte Transkript-Richtlinie (z. B. Entfernen von Thinking-Blöcken) | -| 42 | `sanitizeReplayHistory` | Schreibt den Replay-Verlauf nach der generischen Bereinigung des Transkripts um | Der Provider benötigt providerspezifische Replay-Umschreibungen über gemeinsame Kompaktierungs-Hilfsfunktionen hinaus | -| 43 | `validateReplayTurns` | Finale Validierung oder Umformung der Replay-Züge vor dem Embedded-Runner | Der Provider-Transport benötigt strengere Zugvalidierung nach generischer Bereinigung | -| 44 | `onModelSelected` | Führt provider-eigene Side Effects nach der Modellauswahl aus | Der Provider benötigt Telemetrie oder provider-eigenen Zustand, wenn ein Modell aktiv wird | +| 32 | `augmentModelCatalog` | synthetische/endgültige Katalogzeilen, die nach Discovery angehängt werden | Der Provider benötigt synthetische Vorwärtskompatibilitäts-Zeilen in `models list` und Pickern | +| 33 | `isBinaryThinking` | Ein/Aus-Reasoning-Umschaltung für Anbieter mit binärem Thinking | Der Provider bietet nur binäres Thinking an/aus an | +| 34 | `supportsXHighThinking` | `xhigh`-Reasoning-Unterstützung für ausgewählte Modelle | Der Provider möchte `xhigh` nur für eine Teilmenge von Modellen | +| 35 | `resolveDefaultThinkingLevel` | Standard-`/think`-Level für eine bestimmte Modellfamilie | Der Provider besitzt die Standard-`/think`-Richtlinie für eine Modellfamilie | +| 36 | `isModernModelRef` | Matcher für moderne Modelle für Live-Profil-Filter und Smoke-Auswahl | Der Provider besitzt das Matching bevorzugter Modelle für Live/Smoke | +| 37 | `prepareRuntimeAuth` | konfiguriertes Credential direkt vor der Inferenz in das tatsächliche Laufzeit-Token/den Schlüssel umtauschen | Der Provider benötigt einen Tokenaustausch oder kurzlebige Anfrage-Credentials | +| 38 | `resolveUsageAuth` | Credentials für Nutzung/Abrechnung für `/usage` und verwandte Statusoberflächen auflösen | Der Provider benötigt benutzerdefinierte Tokenanalyse für Nutzung/Quota oder andere Usage-Credentials | +| 39 | `fetchUsageSnapshot` | provider-spezifische Nutzung-/Quota-Snapshots abrufen und normalisieren, nachdem Auth aufgelöst wurde | Der Provider benötigt einen provider-spezifischen Usage-Endpunkt oder Payload-Parser | +| 40 | `createEmbeddingProvider` | plugin-eigenen Embedding-Adapter für Speicher/Suche bauen | Verhalten für Memory-Embeddings gehört zum Provider-Plugin | +| 41 | `buildReplayPolicy` | eine Replay-Richtlinie zurückgeben, die den Umgang des Providers mit Transkripten steuert | Der Provider benötigt eine benutzerdefinierte Transkript-Richtlinie (zum Beispiel Entfernen von Thinking-Blöcken) | +| 42 | `sanitizeReplayHistory` | Replay-Verlauf nach generischer Transkript-Bereinigung umschreiben | Der Provider benötigt provider-spezifische Replay-Umschreibungen über gemeinsame Kompaktion-Helper hinaus | +| 43 | `validateReplayTurns` | endgültige Validierung oder Umformung von Replay-Turns vor dem Embedded-Runner | Der Provider-Transport benötigt strengere Turn-Validierung nach generischer Bereinigung | +| 44 | `onModelSelected` | plugin-eigene Nebeneffekte nach Auswahl des Modells ausführen | Der Provider benötigt Telemetrie oder provider-eigenen Zustand, wenn ein Modell aktiv wird | `normalizeModelId`, `normalizeTransport` und `normalizeConfig` prüfen zuerst das -passende Provider-Plugin und fallen dann auf andere hook-fähige Provider-Plugins -zurück, bis eines die Modell-ID oder den Transport/die Konfiguration tatsächlich ändert. Dadurch bleiben -Alias-/Kompatibilitäts-Shims für Provider funktionsfähig, ohne dass der Aufrufer wissen muss, welches -gebündelte Plugin die Umschreibung besitzt. Wenn kein Provider-Hook einen unterstützten -Konfigurationseintrag der Google-Familie umschreibt, greift weiterhin die gebündelte Google-Konfigurationsnormalisierung für diese Kompatibilitätsbereinigung. +zugeordnete Provider-Plugin und greifen dann auf andere hook-fähige Provider-Plugins zurück, +bis eines tatsächlich die Modell-ID oder den Transport/die Konfiguration ändert. Das hält +Alias-/Kompatibilitäts-Provider-Shims funktionsfähig, ohne vom Aufrufer zu verlangen zu wissen, +welches gebündelte Plugin die Umschreibung besitzt. Wenn kein Provider-Hook einen unterstützten +Google-Familien-Konfigurationseintrag umschreibt, greift weiterhin der gebündelte Google-Konfigurations- +Normalizer für diese Kompatibilitätsbereinigung. -Wenn der Provider ein vollständig benutzerdefiniertes Wire-Protokoll oder einen benutzerdefinierten Anfrage- +Wenn der Provider ein vollständig benutzerdefiniertes Wire-Protokoll oder einen benutzerdefinierten Request- Executor benötigt, ist das eine andere Klasse von Erweiterung. Diese Hooks sind für Provider-Verhalten gedacht, das weiterhin auf der normalen Inferenzschleife von OpenClaw läuft. @@ -771,121 +776,120 @@ api.registerProvider({ }); ``` -### Eingebaute Beispiele +### Integrierte Beispiele - Anthropic verwendet `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` und `wrapStreamFn`, weil es Vorwärtskompatibilität für Claude 4.6, - Hinweise zur Provider-Familie, Richtlinien zur Reparatur der Auth, - Integration des Usage-Endpunkts, - Eignung für Prompt-Cache, auth-bewusste Konfigurationsstandards, Standard-/adaptive - Thinking-Richtlinien für Claude und Anthropic-spezifische Stream-Formung für + Hinweise zur Provider-Familie, Anleitungen zur Auth-Reparatur, Integration von + Nutzungsendpunkten, Prompt-Cache-Eignung, auth-bewusste Konfigurationsstandards, die + Standard-/adaptive Thinking-Richtlinie für Claude sowie Anthropic-spezifisches Stream-Shaping für Beta-Header, `/fast` / `serviceTier` und `context1m` besitzt. -- Anthropic-spezifische Stream-Hilfsfunktionen für Claude bleiben vorerst in der eigenen - öffentlichen Seam `api.ts` / `contract-api.ts` des gebündelten Plugins. Diese Paketoberfläche +- Die Claude-spezifischen Stream-Helper von Anthropic verbleiben vorerst in der eigenen + öffentlichen Naht `api.ts` / `contract-api.ts` des gebündelten Plugins. Diese Paketoberfläche exportiert `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` und die - niedrigstufigen Builder für Anthropic-Wrapper, statt das generische SDK um die - Beta-Header-Regeln eines einzelnen Providers zu erweitern. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` sowie die Low-Level- + Anthropic-Wrapper-Builder, statt das generische SDK um die Beta-Header-Regeln eines + einzelnen Providers zu erweitern. - OpenAI verwendet `resolveDynamicModel`, `normalizeResolvedModel` und `capabilities` sowie `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` und `isModernModelRef`, weil es Vorwärtskompatibilität für GPT-5.4, die direkte OpenAI- Normalisierung `openai-completions` -> `openai-responses`, Codex-bewusste Auth- - Hinweise, Spark-Unterdrückung, synthetische OpenAI-Katalogzeilen und GPT-5-Thinking-/ + Hinweise, Spark-Unterdrückung, synthetische OpenAI-Listenzeilen und GPT-5-Thinking-/ Live-Modell-Richtlinien besitzt; die Stream-Familie `openai-responses-defaults` besitzt die - gemeinsamen nativen OpenAI-Responses-Wrapper für Attribution-Header, - `/fast`/`serviceTier`, Text-Verbosity, native Codex-Websuche, - Reasoning-kompatible Payload-Formung und Kontextverwaltung für Responses. + gemeinsamen nativen OpenAI-Responses-Wrapper für Zuordnungsheader, + `/fast`/`serviceTier`, Textausführlichkeit, native Codex-Websuche, + Reasoning-kompatibles Payload-Shaping und Responses-Kontextverwaltung. - OpenRouter verwendet `catalog` sowie `resolveDynamicModel` und `prepareDynamicModel`, weil der Provider ein Pass-through ist und neue - Modell-IDs anzeigen kann, bevor der statische Katalog von OpenClaw aktualisiert wird; außerdem verwendet es + Modell-IDs verfügbar machen kann, bevor der statische Katalog von OpenClaw aktualisiert wird; außerdem nutzt es `capabilities`, `wrapStreamFn` und `isCacheTtlEligible`, um - providerspezifische Anfrage-Header, Routing-Metadaten, Reasoning-Patches und - Prompt-Cache-Richtlinien aus dem Core herauszuhalten. Seine Replay-Richtlinie stammt aus der + provider-spezifische Request-Header, Routing-Metadaten, Reasoning-Patches und + Prompt-Cache-Richtlinien aus dem Kern herauszuhalten. Seine Replay-Richtlinie stammt aus der Familie `passthrough-gemini`, während die Stream-Familie `openrouter-thinking` - das Injizieren von Proxy-Reasoning und das Überspringen nicht unterstützter Modelle bzw. von `auto` besitzt. + Proxy-Reasoning-Injection und das Überspringen nicht unterstützter Modelle bzw. von `auto` besitzt. - GitHub Copilot verwendet `catalog`, `auth`, `resolveDynamicModel` und - `capabilities` sowie `prepareRuntimeAuth` und `fetchUsageSnapshot`, - weil es geräteeigenen Login des Providers, Fallback-Verhalten für Modelle, Claude-Transkript- - Eigenheiten, einen Austausch GitHub-Token -> Copilot-Token und einen provider-eigenen - Usage-Endpunkt benötigt. + `capabilities` sowie `prepareRuntimeAuth` und `fetchUsageSnapshot`, weil es + provider-eigenes Device-Login, Modell-Fallback-Verhalten, Besonderheiten bei Claude-Transkripten, + einen GitHub-Token -> Copilot-Token-Austausch und einen provider-eigenen Nutzungsendpunkt benötigt. - OpenAI Codex verwendet `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` und `augmentModelCatalog` sowie `prepareExtraParams`, `resolveUsageAuth` und `fetchUsageSnapshot`, weil es - weiterhin auf Core-OpenAI-Transporten läuft, aber seine Transport-/`baseUrl`- - Normalisierung, OAuth-Refresh-Fallback-Richtlinien, Standard-Transportwahl, - synthetische Codex-Katalogzeilen und ChatGPT-Usage-Endpunkt-Integration besitzt; es + weiterhin auf Kern-OpenAI-Transporten läuft, aber seine Transport-/`baseUrl`- + Normalisierung, Richtlinien zum OAuth-Refresh-Fallback, die Standardwahl des Transports, + synthetische Codex-Katalogzeilen und die Integration des ChatGPT-Nutzungsendpunkts besitzt; es teilt sich dieselbe Stream-Familie `openai-responses-defaults` wie direktes OpenAI. - Google AI Studio und Gemini CLI OAuth verwenden `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` und `isModernModelRef`, weil die - Replay-Familie `google-gemini` Vorwärtskompatibilitäts-Fallback für Gemini 3.1, - native Replay-Validierung für Gemini, Bereinigung von Bootstrap-Replays, einen getaggten - Reasoning-Output-Modus und Matching moderner Modelle besitzt, während die - Stream-Familie `google-thinking` die Normalisierung von Thinking-Payloads für Gemini besitzt; + Replay-Familie `google-gemini` den Vorwärtskompatibilitäts-Fallback für Gemini 3.1, + native Gemini-Replay-Validierung, Bootstrap-Replay-Säuberung, den getaggten + Reasoning-Ausgabemodus und das Matching moderner Modelle besitzt, während die + Stream-Familie `google-thinking` die Normalisierung von Gemini-Thinking-Payloads besitzt; Gemini CLI OAuth verwendet außerdem `formatApiKey`, `resolveUsageAuth` und - `fetchUsageSnapshot` für Token-Formatierung, Token-Parsing und Verdrahtung - des Quota-Endpunkts. + `fetchUsageSnapshot` für Token-Formatierung, Token-Parsing und + Verdrahtung des Quota-Endpunkts. - Anthropic Vertex verwendet `buildReplayPolicy` über die - Replay-Familie `anthropic-by-model`, sodass Claude-spezifische Replay-Bereinigung - auf Claude-IDs beschränkt bleibt statt auf jeden `anthropic-messages`-Transport. + Replay-Familie `anthropic-by-model`, damit Claude-spezifische Replay-Bereinigung + auf Claude-IDs beschränkt bleibt statt auf jeden Transport `anthropic-messages`. - Amazon Bedrock verwendet `buildReplayPolicy`, `matchesContextOverflowError`, `classifyFailoverReason` und `resolveDefaultThinkingLevel`, weil es - Bedrock-spezifische Klassifikation von Throttle-/Not-Ready-/Kontextüberlauf-Fehlern - für Anthropic-on-Bedrock-Verkehr besitzt; seine Replay-Richtlinie teilt weiterhin denselben - nur-auf-Claude-bezogenen Guard `anthropic-by-model`. + Bedrock-spezifische Klassifizierung von Throttle-/Not-ready-/Context-Overflow-Fehlern + für Anthropic-auf-Bedrock-Datenverkehr besitzt; seine Replay-Richtlinie teilt sich weiterhin denselben + nur-für-Claude-Schutz `anthropic-by-model`. - OpenRouter, Kilocode, Opencode und Opencode Go verwenden `buildReplayPolicy` über die Replay-Familie `passthrough-gemini`, weil sie Gemini- - Modelle über OpenAI-kompatible Transporte proxen und eine Bereinigung von Gemini- - Thought-Signaturen benötigen, aber keine native Gemini-Replay-Validierung oder - Bootstrap-Umschreibungen. + Modelle über OpenAI-kompatible Transporte proxien und eine Bereinigung von Gemini- + Thought-Signatures ohne native Gemini-Replay-Validierung oder + Bootstrap-Umschreibungen benötigen. - MiniMax verwendet `buildReplayPolicy` über die - Replay-Familie `hybrid-anthropic-openai`, weil ein Provider sowohl - Anthropic-Message- als auch OpenAI-kompatible Semantik besitzt; es hält das - Entfernen von Thinking-Blöcken nur für Claude auf der Anthropic-Seite bei, während es den Reasoning- - Output-Modus wieder auf nativ zurücksetzt, und die Stream-Familie `minimax-fast-mode` besitzt - Umschreibungen von Fast-Mode-Modellen auf dem gemeinsamen Stream-Pfad. -- Moonshot verwendet `catalog` sowie `wrapStreamFn`, weil es weiterhin den - gemeinsamen OpenAI-Transport nutzt, aber provider-eigene Normalisierung von Thinking-Payloads benötigt; die - Stream-Familie `moonshot-thinking` bildet Konfiguration plus `/think`-Status auf ihre - native binäre Thinking-Payload ab. + Replay-Familie `hybrid-anthropic-openai`, weil ein Provider sowohl Semantik + für Anthropic-Nachrichten als auch OpenAI-Kompatibilität besitzt; Claude-spezifisches + Entfernen von Thinking-Blöcken bleibt auf der Anthropic-Seite, während der + Reasoning-Ausgabemodus zurück auf nativ gesetzt wird, und die Stream-Familie `minimax-fast-mode` + besitzt Umschreibungen für den Fast-Modus auf dem gemeinsamen Stream-Pfad. +- Moonshot verwendet `catalog` sowie `wrapStreamFn`, weil es weiterhin den gemeinsamen + OpenAI-Transport nutzt, aber provider-eigene Normalisierung von Thinking-Payloads benötigt; die + Stream-Familie `moonshot-thinking` ordnet Konfiguration plus `/think`-Zustand seiner + nativen binären Thinking-Payload zu. - Kilocode verwendet `catalog`, `capabilities`, `wrapStreamFn` und - `isCacheTtlEligible`, weil es provider-eigene Anfrage-Header, - Normalisierung von Reasoning-Payloads, Hinweise zu Gemini-Transkripten und Anthropic- - Cache-TTL-Gating benötigt; die Stream-Familie `kilocode-thinking` hält Kilo-Thinking- - Injektion auf dem gemeinsamen Proxy-Stream-Pfad, während `kilo/auto` und - andere Proxy-Modell-IDs übersprungen werden, die keine expliziten Reasoning-Payloads unterstützen. + `isCacheTtlEligible`, weil es provider-eigene Request-Header, + Normalisierung von Reasoning-Payloads, Hinweise für Gemini-Transkripte und Anthropic- + Cache-TTL-Gating benötigt; die Stream-Familie `kilocode-thinking` hält die Kilo- + Thinking-Injektion auf dem gemeinsamen Proxy-Stream-Pfad, während `kilo/auto` und + andere Proxy-Modell-IDs, die keine expliziten Reasoning-Payloads unterstützen, ausgelassen werden. - Z.AI verwendet `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` und `fetchUsageSnapshot`, weil es Fallbacks für GLM-5, - Standardwerte für `tool_stream`, binäre Thinking-UX, Matching moderner Modelle und sowohl - Usage-Auth als auch Abruf von Quoten besitzt; die Stream-Familie `tool-stream-default-on` hält - den standardmäßig aktivierten Wrapper `tool_stream` aus handgeschriebenem Glue pro Provider heraus. + `resolveUsageAuth` und `fetchUsageSnapshot`, weil es GLM-5-Fallback, + Standardwerte für `tool_stream`, binäre Thinking-UX, Matching moderner Modelle sowie + sowohl Usage-Auth als auch Quota-Abruf besitzt; die Stream-Familie `tool-stream-default-on` + hält den standardmäßig aktivierten `tool_stream`-Wrapper aus handgeschriebenem + Glue-Code pro Provider heraus. - xAI verwendet `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` und `isModernModelRef`, - weil es Normalisierung für nativen xAI-Responses-Transport, Umschreibungen von - Aliasen für Grok Fast-Mode, Standard-`tool_stream`, Bereinigung für Strict-Tool / Reasoning-Payload, - Wiederverwendung von Fallback-Auth für plugin-eigene Tools, Vorwärtskompatibilität bei der Auflösung von Grok- - Modellen und provider-eigene Kompatibilitätspatches wie xAI-Tool-Schema- + weil es die Normalisierung des nativen xAI-Responses-Transports, Umschreibungen von Grok- + Fast-Mode-Aliassen, Standardwerte für `tool_stream`, Bereinigung für strikte Tools / Reasoning-Payloads, + Wiederverwendung von Fallback-Auth für plugin-eigene Tools, Vorwärtskompatibilitäts- + Auflösung von Grok-Modellen und provider-eigene Kompatibilitätspatches wie xAI-Tool-Schema- Profil, nicht unterstützte Schema-Keywords, natives `web_search` und HTML-Entity- - Decoding von Tool-Call-Argumenten besitzt. + Dekodierung für Tool-Call-Argumente besitzt. - Mistral, OpenCode Zen und OpenCode Go verwenden nur `capabilities`, um - Eigenheiten von Transkript/Tooling aus dem Core herauszuhalten. -- Nur-Katalog-Provider unter den gebündelten Providern wie `byteplus`, `cloudflare-ai-gateway`, + Besonderheiten bei Transkripten/Tooling aus dem Kern herauszuhalten. +- Nur-Katalog-gebündelte Provider wie `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` und `volcengine` verwenden nur `catalog`. -- Qwen verwendet `catalog` für seinen Text-Provider sowie gemeinsame Registrierungen für Medienverständnis und - Videogenerierung für seine multimodalen Oberflächen. -- MiniMax und Xiaomi verwenden `catalog` plus Usage-Hooks, weil ihr `/usage`- - Verhalten plugin-eigen ist, obwohl die Inferenz weiterhin über gemeinsame Transporte läuft. +- Qwen verwendet `catalog` für seinen Textprovider sowie gemeinsame Registrierungen für + Medienverständnis und Videogenerierung für seine multimodalen Oberflächen. +- MiniMax und Xiaomi verwenden `catalog` sowie Usage-Hooks, weil ihr `/usage`- + Verhalten plugin-eigen ist, obwohl die Inferenz weiterhin über die gemeinsamen Transporte läuft. -## Laufzeit-Hilfsfunktionen +## Laufzeit-Helfer -Plugins können über `api.runtime` auf ausgewählte Core-Hilfsfunktionen zugreifen. Für TTS: +Plugins können über `api.runtime` auf ausgewählte Kern-Helper zugreifen. Für TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -906,14 +910,14 @@ const voices = await api.runtime.tts.listVoices({ Hinweise: -- `textToSpeech` gibt die normale Core-TTS-Ausgabe-Payload für Datei-/Sprachnotiz-Oberflächen zurück. -- Verwendet die Core-Konfiguration `messages.tts` und Providerauswahl. -- Gibt PCM-Audiopuffer + Sample-Rate zurück. Plugins müssen für Provider neu sampeln/kodieren. -- `listVoices` ist pro Provider optional. Verwenden Sie es für provider-eigene Voice-Picker oder Setup-Flows. -- Stimmauflistungen können reichere Metadaten wie Locale, Geschlecht und Personality-Tags für providerbewusste Picker enthalten. -- OpenAI und ElevenLabs unterstützen heute Telephony. Microsoft nicht. +- `textToSpeech` gibt die normale Kern-TTS-Ausgabe-Nutzlast für Datei-/Voice-Note-Oberflächen zurück. +- Verwendet die Kernkonfiguration `messages.tts` und Provider-Auswahl. +- Gibt PCM-Audiopuffer + Samplerate zurück. Plugins müssen für Provider neu sampeln/kodieren. +- `listVoices` ist pro Provider optional. Verwenden Sie es für anbietereigene Sprach-Auswahllisten oder Setup-Flows. +- Sprachlisten können reichere Metadaten wie Gebietsschema, Geschlecht und Persönlichkeits-Tags für providerbewusste Picker enthalten. +- OpenAI und ElevenLabs unterstützen heute Telefonie. Microsoft nicht. -Plugins können auch Sprach-Provider über `api.registerSpeechProvider(...)` registrieren. +Plugins können auch Speech-Provider über `api.registerSpeechProvider(...)` registrieren. ```ts api.registerSpeechProvider({ @@ -933,15 +937,15 @@ api.registerSpeechProvider({ Hinweise: -- Behalten Sie TTS-Richtlinie, Fallback und Antwortzustellung im Core. -- Verwenden Sie Sprach-Provider für anbietereigene Synthese. -- Ältere Microsoft-Eingaben `edge` werden auf die Provider-ID `microsoft` normalisiert. -- Das bevorzugte Eigentumsmodell ist unternehmensorientiert: Ein Anbieter-Plugin kann +- Behalten Sie TTS-Richtlinien, Fallback und Antwortzustellung im Kern. +- Verwenden Sie Speech-Provider für anbietereigene Syntheseimplementierungen. +- Legacy-Microsoft-`edge`-Eingabe wird auf die Provider-ID `microsoft` normalisiert. +- Das bevorzugte Ownership-Modell ist unternehmensorientiert: Ein Anbieter-Plugin kann Text-, Sprach-, Bild- und künftige Medien-Provider besitzen, wenn OpenClaw diese Fähigkeitsverträge hinzufügt. Für Bild-/Audio-/Videoverständnis registrieren Plugins einen typisierten -Provider für Medienverständnis statt einer generischen Schlüssel/Wert-Tasche: +Provider für Medienverständnis statt eines generischen Schlüssel/Wert-Sacks: ```ts api.registerMediaUnderstandingProvider({ @@ -955,16 +959,16 @@ api.registerMediaUnderstandingProvider({ Hinweise: -- Behalten Sie Orchestrierung, Fallback, Konfiguration und Kanalverdrahtung im Core. +- Behalten Sie Orchestrierung, Fallback, Konfiguration und Kanalverdrahtung im Kern. - Behalten Sie Anbieterverhalten im Provider-Plugin. -- Additive Erweiterung sollte typisiert bleiben: neue optionale Methoden, neue optionale +- Additive Erweiterungen sollten typisiert bleiben: neue optionale Methoden, neue optionale Ergebnisfelder, neue optionale Fähigkeiten. -- Videogenerierung folgt bereits demselben Muster: - - der Core besitzt den Fähigkeitsvertrag und die Laufzeit-Hilfsfunktion +- Die Videogenerierung folgt bereits demselben Muster: + - der Kern besitzt den Fähigkeitsvertrag und den Laufzeithelfer - Anbieter-Plugins registrieren `api.registerVideoGenerationProvider(...)` - - Feature-/Kanal-Plugins verwenden `api.runtime.videoGeneration.*` + - Feature-/Kanal-Plugins konsumieren `api.runtime.videoGeneration.*` -Für Laufzeit-Hilfsfunktionen des Medienverständnisses können Plugins Folgendes aufrufen: +Für Laufzeit-Helfer des Medienverständnisses können Plugins Folgendes aufrufen: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -995,9 +999,9 @@ Hinweise: - `api.runtime.mediaUnderstanding.*` ist die bevorzugte gemeinsame Oberfläche für Bild-/Audio-/Videoverständnis. -- Verwendet die Audio-Konfiguration des Core für Medienverständnis (`tools.media.audio`) und die Provider-Fallback-Reihenfolge. +- Verwendet die Audio-Konfiguration des Kern-Medienverständnisses (`tools.media.audio`) und die Provider-Fallback-Reihenfolge. - Gibt `{ text: undefined }` zurück, wenn keine Transkriptionsausgabe erzeugt wird (zum Beispiel bei übersprungenen/nicht unterstützten Eingaben). -- `api.runtime.stt.transcribeAudioFile(...)` bleibt als Kompatibilitäts-Alias erhalten. +- `api.runtime.stt.transcribeAudioFile(...)` bleibt als Kompatibilitäts-Alias bestehen. Plugins können auch Hintergrundläufe von Subagents über `api.runtime.subagent` starten: @@ -1015,11 +1019,11 @@ Hinweise: - `provider` und `model` sind optionale Überschreibungen pro Lauf, keine persistenten Sitzungsänderungen. - OpenClaw berücksichtigt diese Override-Felder nur für vertrauenswürdige Aufrufer. -- Für plugin-eigene Fallback-Läufe müssen Betreiber mit `plugins.entries..subagent.allowModelOverride: true` zustimmen. -- Verwenden Sie `plugins.entries..subagent.allowedModels`, um vertrauenswürdige Plugins auf bestimmte kanonische Ziele `provider/model` zu beschränken, oder `"*"`, um explizit jedes Ziel zuzulassen. -- Läufe von Subagents aus nicht vertrauenswürdigen Plugins funktionieren weiterhin, aber Override-Anfragen werden abgelehnt, statt still auf Fallback zurückzufallen. +- Für plugin-eigene Fallback-Läufe müssen Operatoren mit `plugins.entries..subagent.allowModelOverride: true` zustimmen. +- Verwenden Sie `plugins.entries..subagent.allowedModels`, um vertrauenswürdige Plugins auf bestimmte kanonische Ziele `provider/model` zu beschränken, oder `"*"`, um explizit jedes Ziel zu erlauben. +- Läufe von Subagents durch nicht vertrauenswürdige Plugins funktionieren weiterhin, aber Override-Anfragen werden abgelehnt, statt stillschweigend zurückzufallen. -Für Websuche können Plugins die gemeinsame Laufzeit-Hilfsfunktion nutzen, statt +Für die Websuche können Plugins den gemeinsamen Laufzeit-Helfer konsumieren, statt in die Verdrahtung des Agent-Tools zu greifen: ```ts @@ -1041,9 +1045,9 @@ Plugins können Websuch-Provider auch über Hinweise: -- Behalten Sie Providerauswahl, Auflösung von Zugangsdaten und gemeinsame Anfrage-Semantik im Core. +- Behalten Sie Provider-Auswahl, Auflösung von Credentials und gemeinsame Request-Semantik im Kern. - Verwenden Sie Websuch-Provider für anbieterspezifische Suchtransporte. -- `api.runtime.webSearch.*` ist die bevorzugte gemeinsame Oberfläche für Feature-/Kanal-Plugins, die Suchverhalten benötigen, ohne vom Wrapper des Agent-Tools abhängig zu sein. +- `api.runtime.webSearch.*` ist die bevorzugte gemeinsame Oberfläche für Feature-/Kanal-Plugins, die Suchverhalten benötigen, ohne von dem Agent-Tool-Wrapper abhängig zu sein. ### `api.runtime.imageGeneration` @@ -1058,8 +1062,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: Erzeugt ein Bild mit der konfigurierten Provider-Kette für Bildgenerierung. -- `listProviders(...)`: Listet verfügbare Provider für Bildgenerierung und ihre Fähigkeiten auf. +- `generate(...)`: ein Bild mit der konfigurierten Kette von Bildgenerierungs-Providern erzeugen. +- `listProviders(...)`: verfügbare Bildgenerierungs-Provider und ihre Fähigkeiten auflisten. ## Gateway-HTTP-Routen @@ -1080,35 +1084,35 @@ api.registerHttpRoute({ Routenfelder: -- `path`: Routenpfad unter dem HTTP-Server des Gateway. -- `auth`: erforderlich. Verwenden Sie `"gateway"`, um normale Gateway-Auth zu verlangen, oder `"plugin"` für plugin-verwaltete Auth/Webhook-Verifikation. +- `path`: Routenpfad unter dem Gateway-HTTP-Server. +- `auth`: erforderlich. Verwenden Sie `"gateway"`, um normale Gateway-Auth zu verlangen, oder `"plugin"` für pluginverwaltete Auth/Webhook-Verifikation. - `match`: optional. `"exact"` (Standard) oder `"prefix"`. -- `replaceExisting`: optional. Erlaubt demselben Plugin, seine eigene vorhandene Routenregistrierung zu ersetzen. +- `replaceExisting`: optional. Erlaubt demselben Plugin, seine eigene bestehende Routenregistrierung zu ersetzen. - `handler`: gibt `true` zurück, wenn die Route die Anfrage verarbeitet hat. Hinweise: -- `api.registerHttpHandler(...)` wurde entfernt und führt zu einem Plugin-Ladefehler. Verwenden Sie stattdessen `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` wurde entfernt und führt zu einem Fehler beim Laden des Plugins. Verwenden Sie stattdessen `api.registerHttpRoute(...)`. - Plugin-Routen müssen `auth` explizit deklarieren. -- Exakte Konflikte bei `path + match` werden abgelehnt, es sei denn `replaceExisting: true`, und ein Plugin kann die Route eines anderen Plugins nicht ersetzen. -- Überlappende Routen mit unterschiedlichen `auth`-Ebenen werden abgelehnt. Halten Sie Fallthrough-Ketten von `exact`/`prefix` nur auf derselben Auth-Ebene. -- Routen mit `auth: "plugin"` erhalten **nicht** automatisch Runtime-Scopes des Operators. Sie sind für plugin-verwaltete Webhooks/Signaturverifikation gedacht, nicht für privilegierte Gateway-Hilfsaufrufe. -- Routen mit `auth: "gateway"` laufen innerhalb eines Runtime-Scopes für Gateway-Anfragen, aber dieser Scope ist bewusst konservativ: - - Bearer-Auth mit gemeinsamem Secret (`gateway.auth.mode = "token"` / `"password"`) hält Runtime-Scopes für Plugin-Routen auf `operator.write` fest, auch wenn der Aufrufer `x-openclaw-scopes` sendet - - vertrauenswürdige HTTP-Modi mit Identität (zum Beispiel `trusted-proxy` oder `gateway.auth.mode = "none"` an einem privaten Ingress) berücksichtigen `x-openclaw-scopes` nur, wenn der Header explizit vorhanden ist - - wenn `x-openclaw-scopes` bei solchen Plugin-Routen mit Identität fehlt, fällt der Runtime-Scope auf `operator.write` zurück -- Praktische Regel: Gehen Sie nicht davon aus, dass eine Plugin-Route mit Gateway-Auth implizit eine Admin-Oberfläche ist. Wenn Ihre Route Verhalten nur für Admins benötigt, verlangen Sie einen Auth-Modus mit Identität und dokumentieren Sie den expliziten Header-Vertrag `x-openclaw-scopes`. +- Exakte Konflikte von `path + match` werden abgelehnt, außer `replaceExisting: true` ist gesetzt, und ein Plugin kann keine Route eines anderen Plugins ersetzen. +- Überlappende Routen mit unterschiedlichen `auth`-Leveln werden abgelehnt. Halten Sie `exact`-/`prefix`-Fallthrough-Ketten nur auf derselben Auth-Stufe. +- Routen mit `auth: "plugin"` erhalten nicht automatisch Runtime-Scopes des Operators. Sie sind für pluginverwaltete Webhooks/Signaturprüfung gedacht, nicht für privilegierte Gateway-Helper-Aufrufe. +- Routen mit `auth: "gateway"` laufen innerhalb eines Gateway-Request-Runtime-Scopes, aber dieser Scope ist bewusst konservativ: + - Bearer-Auth mit Shared Secret (`gateway.auth.mode = "token"` / `"password"`) hält die Runtime-Scopes von Plugin-Routen auf `operator.write` fest, selbst wenn der Aufrufer `x-openclaw-scopes` sendet + - vertrauenswürdige HTTP-Modi mit identitätstragenden Daten (zum Beispiel `trusted-proxy` oder `gateway.auth.mode = "none"` an einem privaten Ingress) beachten `x-openclaw-scopes` nur, wenn der Header ausdrücklich vorhanden ist + - wenn `x-openclaw-scopes` bei solchen identitätstragenden Plugin-Routenanfragen fehlt, fällt der Runtime-Scope auf `operator.write` zurück +- Praktische Regel: Gehen Sie nicht davon aus, dass eine Gateway-authentifizierte Plugin-Route implizit eine Admin-Oberfläche ist. Wenn Ihre Route rein administratives Verhalten braucht, verlangen Sie einen identitätstragenden Auth-Modus und dokumentieren Sie den expliziten Vertragsumfang des Headers `x-openclaw-scopes`. -## Importpfade des Plugin-SDK +## Importpfade des Plugin SDK Verwenden Sie SDK-Subpaths statt des monolithischen Imports `openclaw/plugin-sdk`, -wenn Sie Plugins verfassen: +wenn Sie Plugins erstellen: -- `openclaw/plugin-sdk/plugin-entry` für Primitive zur Plugin-Registrierung. +- `openclaw/plugin-sdk/plugin-entry` für Plugin-Registrierungsprimitive. - `openclaw/plugin-sdk/core` für den generischen gemeinsamen pluginseitigen Vertrag. - `openclaw/plugin-sdk/config-schema` für den Export des Zod-Schemas der Wurzel `openclaw.json` (`OpenClawSchema`). -- Stabile Kanalprimitive wie `openclaw/plugin-sdk/channel-setup`, +- Stabile Kanal-Primitive wie `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1120,15 +1124,15 @@ wenn Sie Plugins verfassen: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` und - `openclaw/plugin-sdk/webhook-ingress` für gemeinsame Verdrahtung von Setup/Auth/Antwort/Webhook. - `channel-inbound` ist das gemeinsame Zuhause für Debounce, Mention-Matching, - Hilfsfunktionen für Mention-Richtlinien eingehender Nachrichten, Envelope-Formatierung und Hilfsfunktionen - für den Kontext eingehender Envelopes. - `channel-setup` ist die schmale Setup-Seam für optionale Installation. + `openclaw/plugin-sdk/webhook-ingress` für gemeinsame Setup-/Auth-/Antwort-/Webhook- + Verdrahtung. `channel-inbound` ist die gemeinsame Heimat für Debounce, Mention-Matching, + Helper für Inbound-Mention-Richtlinien, Envelope-Formatierung und + Kontext-Helper für Inbound-Envelopes. + `channel-setup` ist die schmale optionale Setup-Naht. `setup-runtime` ist die laufzeitsichere Setup-Oberfläche, die von `setupEntry` / - verzögertem Start verwendet wird, einschließlich import-sicherer Patch-Adapter für das Setup. - `setup-adapter-runtime` ist die env-bewusste Adapter-Seam für Konto-Setup. - `setup-tools` ist die kleine Seam für Hilfsfunktionen zu CLI/Archiven/Dokumentation (`formatCliCommand`, + verzögertem Start verwendet wird, einschließlich der importsicheren Setup-Patch-Adapter. + `setup-adapter-runtime` ist die env-bewusste Naht für Account-Setup-Adapter. + `setup-tools` ist die kleine Naht für CLI-/Archiv-/Dokumentations-Helfer (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Domänen-Subpaths wie `openclaw/plugin-sdk/channel-config-helpers`, @@ -1149,131 +1153,136 @@ wenn Sie Plugins verfassen: `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` und - `openclaw/plugin-sdk/directory-runtime` für gemeinsame Hilfsfunktionen für Laufzeit/Konfiguration. - `telegram-command-config` ist die schmale öffentliche Seam für Normalisierung/Validierung benutzerdefinierter Telegram- - Befehle und bleibt verfügbar, selbst wenn die gebündelte Telegram-Vertragsoberfläche vorübergehend nicht verfügbar ist. - `text-runtime` ist die gemeinsame Seam für Text/Markdown/Logging, einschließlich - Entfernen für Assistenten sichtbaren Texts, Hilfsfunktionen für Rendering/Chunking von Markdown, Hilfsfunktionen - für Redaction, Hilfsfunktionen für Direktiven-Tags und Safe-Text-Utilities. -- Genehmigungsspezifische Kanal-Seams sollten einen einzelnen Vertrag `approvalCapability` - auf dem Plugin bevorzugen. Der Core liest dann Auth, Zustellung, Rendering, - natives Routing und lazy native Handler-Verhalten für Genehmigungen über diese eine Fähigkeit, - statt Genehmigungsverhalten in nicht zusammenhängende Plugin-Felder zu mischen. -- `openclaw/plugin-sdk/channel-runtime` ist veraltet und bleibt nur als - Kompatibilitäts-Shim für ältere Plugins erhalten. Neuer Code sollte stattdessen die schmaleren - generischen Primitive importieren, und im Repo sollte kein neuer Import des - Shims hinzugefügt werden. -- Interne Bestandteile gebündelter Erweiterungen bleiben privat. Externe Plugins sollten nur - `openclaw/plugin-sdk/*`-Subpaths verwenden. OpenClaw-Core-/Test-Code kann die öffentlichen - Repo-Entry-Points unter einer Plugin-Paketwurzel verwenden, etwa `index.js`, `api.js`, + `openclaw/plugin-sdk/directory-runtime` für gemeinsame Laufzeit-/Konfigurations-Helfer. + `telegram-command-config` ist die schmale öffentliche Naht für Normalisierung/Validierung von benutzerdefinierten Telegram- + Befehlen und bleibt verfügbar, selbst wenn die Vertragsoberfläche des gebündelten + Telegram vorübergehend nicht verfügbar ist. + `text-runtime` ist die gemeinsame Naht für Text/Markdown/Logging, einschließlich + Entfernen von für Assistenten sichtbarem Text, Helpern für Markdown-Rendering/Chunking, Redaktions- + Helpern, Helpern für Richtlinien-Tags und Safe-Text-Utilities. +- Kanalspezifische Approval-Seams sollten bevorzugt einen einzigen `approvalCapability`- + Vertrag auf dem Plugin verwenden. Der Kern liest dann Auth, Bereitstellung, Rendering, + natives Routing und lazy natives Handler-Verhalten für Approvals über diese eine Fähigkeit, + statt Approval-Verhalten in unabhängige Plugin-Felder zu mischen. +- `openclaw/plugin-sdk/channel-runtime` ist veraltet und verbleibt nur als + Kompatibilitäts-Shim für ältere Plugins. Neuer Code sollte stattdessen die schmaleren + generischen Primitive importieren, und Repo-Code sollte keine neuen Importe dieses + Shims hinzufügen. +- Interne Elemente gebündelter Extensions bleiben privat. Externe Plugins sollten nur + `openclaw/plugin-sdk/*`-Subpaths verwenden. OpenClaw-Kern-/Test-Code kann die + öffentlichen Repo-Einstiegspunkte unter einer Plugin-Paketwurzel wie `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js` und eng begrenzte Dateien wie - `login-qr-api.js`. Importieren Sie niemals `src/*` eines Plugin-Pakets aus dem Core oder aus - einer anderen Erweiterung. -- Aufteilung der Repo-Entry-Points: - `/api.js` ist das Helper-/Types-Barrel, - `/runtime-api.js` ist das reine Laufzeit-Barrel, - `/index.js` ist der Entry des gebündelten Plugins - und `/setup-entry.js` ist der Setup-Entry des Plugins. + `login-qr-api.js` verwenden. Importieren Sie niemals `src/*` eines Plugin-Pakets aus dem Kern oder aus + einer anderen Extension. +- Aufteilung der Repo-Einstiegspunkte: + `/api.js` ist das Barrel für Helfer/Typen, + `/runtime-api.js` ist das nur-Laufzeit-Barrel, + `/index.js` ist der Einstieg des gebündelten Plugins, + und `/setup-entry.js` ist der Einstieg des Setup-Plugins. - Aktuelle Beispiele für gebündelte Provider: - - Anthropic verwendet `api.js` / `contract-api.js` für Claude-Stream-Hilfsfunktionen wie - `wrapAnthropicProviderStream`, Hilfsfunktionen für Beta-Header und Parsing von `service_tier`. - - OpenAI verwendet `api.js` für Provider-Builder, Hilfsfunktionen für Standardmodelle und Builder für Echtzeit-Provider. - - OpenRouter verwendet `api.js` für seinen Provider-Builder sowie Hilfsfunktionen für Onboarding/Konfiguration, - während `register.runtime.js` weiterhin generische - `plugin-sdk/provider-stream`-Hilfsfunktionen für repo-lokale Verwendung re-exportieren kann. -- Öffentlich zugängliche Entry-Points, die über Fassaden geladen werden, bevorzugen den aktiven Laufzeit-Snapshot der Konfiguration, - wenn ein solcher existiert, und fallen andernfalls auf die auf dem Datenträger aufgelöste Konfigurationsdatei zurück, wenn - OpenClaw noch keinen Laufzeit-Snapshot bereitstellt. + - Anthropic verwendet `api.js` / `contract-api.js` für Claude-Stream-Helper wie + `wrapAnthropicProviderStream`, Helper für Beta-Header und Parsing von `service_tier`. + - OpenAI verwendet `api.js` für Provider-Builder, Helper für Standardmodelle und + Builder für Realtime-Provider. + - OpenRouter verwendet `api.js` für seinen Provider-Builder sowie Onboarding-/Konfigurations- + Helper, während `register.runtime.js` weiterhin generische + `plugin-sdk/provider-stream`-Helper für die repo-lokale Nutzung re-exportieren kann. +- Über Fassade geladene öffentliche Einstiegspunkte bevorzugen den aktiven Laufzeit- + Konfigurations-Snapshot, wenn einer existiert, und fallen andernfalls auf die auf der Platte aufgelöste Konfigurationsdatei zurück, + wenn OpenClaw noch keinen Laufzeit-Snapshot bereitstellt. - Generische gemeinsame Primitive bleiben der bevorzugte öffentliche SDK-Vertrag. Ein kleiner - reservierter Kompatibilitätssatz gebündelter, kanalgebrandeter Helper-Seams existiert weiterhin. - Behandeln Sie diese als Seams für Wartung/Kompatibilität gebündelter Plugins, nicht als neue Importziele für Dritte; neue kanalübergreifende Verträge sollten weiterhin auf generischen `plugin-sdk/*`-Subpaths oder den plugin-lokalen Barrels `api.js` / + reservierter Kompatibilitätssatz gebündelter, kanalmarkierter Helper-Seams existiert weiterhin. + Behandeln Sie diese als Seams für gebündelte Wartung/Kompatibilität, nicht als neue + Importziele für Drittanbieter; neue kanalübergreifende Verträge sollten weiterhin auf + generischen `plugin-sdk/*`-Subpaths oder den plugin-lokalen Barrels `api.js` / `runtime-api.js` landen. -Hinweis zur Kompatibilität: +Kompatibilitätshinweis: - Vermeiden Sie für neuen Code das Root-Barrel `openclaw/plugin-sdk`. -- Bevorzugen Sie zuerst die schmalen stabilen Primitive. Die neueren Setup-/Pairing-/Reply-/ - Feedback-/Contract-/Inbound-/Threading-/Command-/Secret-Input-/Webhook-/Infra-/ - Allowlist-/Status-/Message-Tool-Subpaths sind der beabsichtigte Vertrag für neue - Arbeit an gebündelten und externen Plugins. - Parsen/Matching von Zielen gehört zu `openclaw/plugin-sdk/channel-targets`. - Gates für Message-Aktionen und Hilfsfunktionen für Reaktions-Message-IDs gehören zu +- Bevorzugen Sie zuerst die schmalen stabilen Primitive. Die neueren Subpaths für setup/pairing/reply/ + feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool sind der vorgesehene Vertrag für neue + gebündelte und externe Plugin-Arbeit. + Target-Parsing/-Matching gehört auf `openclaw/plugin-sdk/channel-targets`. + Gates für Message-Actions und Helper für Reaktions-Message-IDs gehören auf `openclaw/plugin-sdk/channel-actions`. -- Erweiterungsspezifische Helper-Barrels gebündelter Erweiterungen sind standardmäßig nicht stabil. Wenn ein - Helper nur von einer gebündelten Erweiterung benötigt wird, halten Sie ihn hinter der lokalen - Seam `api.js` oder `runtime-api.js` dieser Erweiterung, statt ihn in +- Extensionspezifische Helper-Barrels gebündelter Plugins sind standardmäßig nicht stabil. Wenn ein + Helper nur von einer gebündelten Extension benötigt wird, behalten Sie ihn hinter der + lokalen Naht `api.js` oder `runtime-api.js` der Extension, statt ihn nach `openclaw/plugin-sdk/` zu befördern. -- Neue gemeinsame Helper-Seams sollten generisch sein, nicht kanalgebrandet. Gemeinsames Parsen - von Zielen gehört zu `openclaw/plugin-sdk/channel-targets`; kanalspezifische - Interna bleiben hinter der lokalen Seam `api.js` oder `runtime-api.js` des besitzenden Plugins. +- Neue gemeinsame Helper-Seams sollten generisch sein, nicht kanalmarkiert. Gemeinsames Target- + Parsing gehört auf `openclaw/plugin-sdk/channel-targets`; kanalspezifische + Interna bleiben hinter dem lokalen `api.js` oder `runtime-api.js` des besitzenden Plugins. - Fähigkeitsspezifische Subpaths wie `image-generation`, - `media-understanding` und `speech` existieren, weil gebündelte/native Plugins sie heute nutzen. - Ihre Existenz bedeutet nicht automatisch, dass jede exportierte Hilfsfunktion ein + `media-understanding` und `speech` existieren, weil gebündelte/native Plugins sie + heute verwenden. Ihre Existenz bedeutet für sich genommen nicht, dass jeder exportierte Helper ein langfristig eingefrorener externer Vertrag ist. -## Schemas für Message-Tools +## Schemas für das Message-Tool -Plugins sollten kanalspezifische Schema-Beiträge in `describeMessageTool(...)` -besitzen. Behalten Sie providerspezifische Felder im Plugin, nicht im gemeinsamen Core. +Plugins sollten kanalspezifische Schema-Beiträge für `describeMessageTool(...)` +besitzen. Behalten Sie providerspezifische Felder im Plugin, nicht im gemeinsamen Kern. -Für gemeinsame portable Schemafragmente verwenden Sie die generischen Hilfsfunktionen, die über +Für gemeinsame portable Schemafragmente verwenden Sie die generischen Helper, die über `openclaw/plugin-sdk/channel-actions` exportiert werden: -- `createMessageToolButtonsSchema()` für Payloads im Stil von Button-Rastern -- `createMessageToolCardSchema()` für strukturierte Card-Payloads +- `createMessageToolButtonsSchema()` für Payloads im Stil von Schaltflächengittern +- `createMessageToolCardSchema()` für strukturierte Karten-Payloads -Wenn eine Schemaform nur für einen Provider sinnvoll ist, definieren Sie sie in den -eigenen Quellen dieses Plugins, statt sie in das gemeinsame SDK zu befördern. +Wenn eine Schemaform nur für einen Provider sinnvoll ist, definieren Sie sie im +eigenen Quellcode dieses Plugins, statt sie in das gemeinsame SDK zu befördern. ## Auflösung von Kanalzielen -Kanal-Plugins sollten kanalspezifische Zielsemantik besitzen. Halten Sie den gemeinsamen +Kanal-Plugins sollten die kanalspezifische Zielsemantik besitzen. Halten Sie den gemeinsamen Outbound-Host generisch und verwenden Sie die Oberfläche des Messaging-Adapters für Provider-Regeln: - `messaging.inferTargetChatType({ to })` entscheidet, ob ein normalisiertes Ziel - vor dem Directory-Lookup als `direct`, `group` oder `channel` behandelt werden soll. -- `messaging.targetResolver.looksLikeId(raw, normalized)` teilt dem Core mit, ob eine - Eingabe direkt zur ID-artigen Auflösung springen soll statt zur Directory-Suche. + vor der Verzeichnissuche als `direct`, `group` oder `channel` behandelt werden soll. +- `messaging.targetResolver.looksLikeId(raw, normalized)` teilt dem Kern mit, ob eine + Eingabe direkt in die Auflösung einer ID-ähnlichen Form übergehen soll, statt in die Verzeichnissuche. - `messaging.targetResolver.resolveTarget(...)` ist der Plugin-Fallback, wenn - der Core nach der Normalisierung oder nach einem Directory-Fehlschlag eine letzte provider-eigene Auflösung benötigt. + der Kern nach der Normalisierung oder nach einem Verzeichnis-Fehlschlag eine endgültige + providereigene Auflösung benötigt. - `messaging.resolveOutboundSessionRoute(...)` besitzt die providerspezifische Konstruktion der Sitzungsroute, sobald ein Ziel aufgelöst ist. Empfohlene Aufteilung: -- Verwenden Sie `inferTargetChatType` für Kategorieentscheidungen, die vor - der Suche nach Peers/Gruppen erfolgen sollten. +- Verwenden Sie `inferTargetChatType` für Kategorientscheidungen, die vor + der Suche nach Peers/Gruppen stattfinden sollten. - Verwenden Sie `looksLikeId` für Prüfungen wie „dies als explizite/native Ziel-ID behandeln“. -- Verwenden Sie `resolveTarget` für provider-eigenen Normalisierungs-Fallback, nicht für - breit angelegte Directory-Suche. -- Halten Sie provider-native IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum-IDs - in `target`-Werten oder providerspezifischen Parametern, nicht in generischen SDK-Feldern. +- Verwenden Sie `resolveTarget` für provider-spezifischen Normalisierungs-Fallback, nicht für + umfangreiche Verzeichnissuche. +- Behalten Sie native Provider-IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum-IDs + innerhalb von `target`-Werten oder providerspezifischen Parametern, nicht in generischen SDK-Feldern. -## Konfigurationsgestützte Directories +## Konfigurationsgestützte Verzeichnisse -Plugins, die Directory-Einträge aus der Konfiguration ableiten, sollten diese Logik im -Plugin behalten und die gemeinsamen Hilfsfunktionen aus +Plugins, die Verzeichniseinträge aus der Konfiguration ableiten, sollten diese Logik im +Plugin behalten und die gemeinsamen Helper aus `openclaw/plugin-sdk/directory-runtime` wiederverwenden. -Verwenden Sie dies, wenn ein Kanal konfigurationsgestützte Peers/Gruppen benötigt, etwa: +Verwenden Sie dies, wenn ein Kanal konfigurationsgestützte Peers/Gruppen benötigt, wie etwa: - Allowlist-gesteuerte DM-Peers -- konfigurierte Kanal-/Gruppen-Zuordnungen -- kontoabhängige statische Directory-Fallbacks +- konfigurierte Kanal-/Gruppenzuordnungen +- kontobezogene statische Verzeichnis-Fallbacks -Die gemeinsamen Hilfsfunktionen in `directory-runtime` behandeln nur generische Operationen: +Die gemeinsamen Helper in `directory-runtime` behandeln nur generische Operationen: - Query-Filterung - Anwenden von Limits -- Hilfsfunktionen für Deduplizierung/Normalisierung +- Helfer für Deduplizierung/Normalisierung - Erstellen von `ChannelDirectoryEntry[]` Kanalspezifische Kontoinspektion und ID-Normalisierung sollten in der -Plugin-Implementierung bleiben. +Plugin-Implementierung verbleiben. ## Provider-Kataloge -Provider-Plugins können Modellkataloge für Inferenz definieren mit +Provider-Plugins können Modellkataloge für die Inferenz definieren mit `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` gibt dieselbe Form zurück, die OpenClaw in @@ -1285,54 +1294,57 @@ Provider-Plugins können Modellkataloge für Inferenz definieren mit Verwenden Sie `catalog`, wenn das Plugin providerspezifische Modell-IDs, Standardwerte für `baseUrl` oder auth-gesteuerte Modellmetadaten besitzt. -`catalog.order` steuert, wann der Katalog eines Plugins relativ zu den eingebauten impliziten Providern von OpenClaw zusammengeführt wird: +`catalog.order` steuert, wann der Katalog eines Plugins relativ zu den +integrierten impliziten Providern von OpenClaw zusammengeführt wird: - `simple`: einfache API-Key- oder env-gesteuerte Provider -- `profile`: Provider, die erscheinen, wenn Auth-Profile existieren +- `profile`: Provider, die erscheinen, wenn Auth-Profile vorhanden sind - `paired`: Provider, die mehrere zusammengehörige Provider-Einträge synthetisieren - `late`: letzter Durchlauf, nach anderen impliziten Providern -Spätere Provider gewinnen bei Schlüsselkollisionen, sodass Plugins absichtlich einen eingebauten Provider- -Eintrag mit derselben Provider-ID überschreiben können. +Spätere Provider gewinnen bei Schlüsselkollisionen, sodass Plugins absichtlich einen +integrierten Provider-Eintrag mit derselben Provider-ID überschreiben können. Kompatibilität: -- `discovery` funktioniert weiterhin als älterer Alias +- `discovery` funktioniert weiterhin als Legacy-Alias - wenn sowohl `catalog` als auch `discovery` registriert sind, verwendet OpenClaw `catalog` -## Read-only-Kanalinspektion +## Schreibgeschützte Kanalinspektion -Wenn Ihr Plugin einen Kanal registriert, sollten Sie -`plugin.config.inspectAccount(cfg, accountId)` parallel zu `resolveAccount(...)` implementieren. +Wenn Ihr Plugin einen Kanal registriert, bevorzugen Sie die Implementierung von +`plugin.config.inspectAccount(cfg, accountId)` zusammen mit `resolveAccount(...)`. Warum: -- `resolveAccount(...)` ist der Laufzeitpfad. Er darf davon ausgehen, dass Zugangsdaten +- `resolveAccount(...)` ist der Laufzeitpfad. Es darf davon ausgehen, dass Credentials vollständig materialisiert sind, und bei fehlenden erforderlichen Secrets schnell fehlschlagen. -- Read-only-Befehlspfade wie `openclaw status`, `openclaw status --all`, +- Schreibgeschützte Befehlspfade wie `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` und Doctor-/Konfigurations- - Reparaturflüsse sollten Laufzeit-Zugangsdaten nicht materialisieren müssen, nur um Konfiguration zu beschreiben. + Reparaturabläufe sollten keine Laufzeit-Credentials materialisieren müssen, nur um + Konfiguration zu beschreiben. -Empfohlenes Verhalten für `inspectAccount(...)`: +Empfohlenes Verhalten von `inspectAccount(...)`: -- Nur beschreibenden Kontostatus zurückgeben. +- Nur beschreibenden Kontozustand zurückgeben. - `enabled` und `configured` beibehalten. -- Felder zu Quelle/Status von Zugangsdaten einbeziehen, wenn relevant, etwa: +- Felder zu Credential-Quelle/-Status einschließen, wenn relevant, z. B.: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Sie müssen keine rohen Tokenwerte zurückgeben, nur um Read-only- - Verfügbarkeit zu melden. `tokenStatus: "available"` (und das passende Quellfeld) reicht für Statusbefehle aus. -- Verwenden Sie `configured_unavailable`, wenn Zugangsdaten über SecretRef konfiguriert sind, aber - im aktuellen Befehlspfad nicht verfügbar sind. +- Sie müssen keine rohen Tokenwerte zurückgeben, nur um schreibgeschützte + Verfügbarkeit zu melden. Die Rückgabe von `tokenStatus: "available"` (und dem zugehörigen + Quellenfeld) reicht für statusartige Befehle aus. +- Verwenden Sie `configured_unavailable`, wenn ein Credential über SecretRef konfiguriert ist, im + aktuellen Befehlspfad aber nicht verfügbar ist. -Dadurch können Read-only-Befehle „konfiguriert, aber in diesem Befehlspfad nicht verfügbar“ melden, -statt abzustürzen oder das Konto fälschlich als nicht konfiguriert zu melden. +Dadurch können schreibgeschützte Befehle „konfiguriert, aber in diesem Befehlspfad nicht verfügbar“ +melden, statt abzustürzen oder das Konto fälschlich als nicht konfiguriert zu melden. -## Package-Packs +## Paket-Packs -Ein Plugin-Verzeichnis kann eine `package.json` mit `openclaw.extensions` enthalten: +Ein Plugin-Verzeichnis kann ein `package.json` mit `openclaw.extensions` enthalten: ```json { @@ -1344,64 +1356,66 @@ Ein Plugin-Verzeichnis kann eine `package.json` mit `openclaw.extensions` enthal } ``` -Jeder Eintrag wird zu einem Plugin. Wenn das Pack mehrere Erweiterungen auflistet, wird die Plugin-ID zu -`name/`. +Jeder Eintrag wird zu einem Plugin. Wenn das Pack mehrere Extensions auflistet, wird die Plugin-ID +zu `name/`. Wenn Ihr Plugin npm-Abhängigkeiten importiert, installieren Sie sie in diesem Verzeichnis, damit `node_modules` verfügbar ist (`npm install` / `pnpm install`). Sicherheitsleitplanke: Jeder Eintrag in `openclaw.extensions` muss nach der Auflösung von Symlinks innerhalb des Plugin- -Verzeichnisses bleiben. Einträge, die aus dem Paketverzeichnis herausführen, werden +Verzeichnisses bleiben. Einträge, die das Paketverzeichnis verlassen, werden abgelehnt. Sicherheitshinweis: `openclaw plugins install` installiert Plugin-Abhängigkeiten mit `npm install --omit=dev --ignore-scripts` (keine Lifecycle-Skripte, keine Dev-Abhängigkeiten zur Laufzeit). Halten Sie Plugin-Abhängigkeits- -bäume „reines JS/TS“ und vermeiden Sie Pakete, die `postinstall`-Builds erfordern. +Bäume „reines JS/TS“ und vermeiden Sie Pakete, die `postinstall`-Builds benötigen. -Optional: `openclaw.setupEntry` kann auf ein leichtgewichtiges, nur für Setup bestimmtes Modul verweisen. +Optional: `openclaw.setupEntry` kann auf ein leichtgewichtiges Nur-Setup-Modul verweisen. Wenn OpenClaw Setup-Oberflächen für ein deaktiviertes Kanal-Plugin benötigt oder wenn ein Kanal-Plugin aktiviert, aber noch nicht konfiguriert ist, lädt es `setupEntry` -statt des vollständigen Plugin-Entries. Dadurch bleiben Start und Setup leichter, -wenn Ihr Haupteintrag zusätzlich Tools, Hooks oder anderen reinen Laufzeit- +statt des vollständigen Plugin-Einstiegs. Das hält Start und Einrichtung leichter, +wenn Ihr Haupteinstieg außerdem Tools, Hooks oder anderen rein laufzeitbezogenen Code verdrahtet. Optional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -kann ein Kanal-Plugin in denselben `setupEntry`-Pfad während der Pre-Listen-Startphase des Gateway aufnehmen, auch wenn der Kanal bereits konfiguriert ist. +kann ein Kanal-Plugin während der Phase vor `listen` beim Gateway-Start ebenfalls in denselben `setupEntry`- +Pfad opt-in versetzen, selbst wenn der Kanal bereits konfiguriert ist. -Verwenden Sie dies nur, wenn `setupEntry` die Startoberfläche, die vor dem Lauschen -des Gateway existieren muss, vollständig abdeckt. In der Praxis bedeutet das, dass der -Setup-Entry jede kanaleigene Fähigkeit registrieren muss, von der der Start abhängt, z. B.: +Verwenden Sie dies nur, wenn `setupEntry` die Startoberfläche vollständig abdeckt, die +existieren muss, bevor das Gateway zu lauschen beginnt. In der Praxis bedeutet das, dass der +Setup-Einstieg jede kanaleigene Fähigkeit registrieren muss, von der der Start abhängt, wie z. B.: - die Kanalregistrierung selbst -- alle HTTP-Routen, die verfügbar sein müssen, bevor das Gateway mit dem Lauschen beginnt -- alle Gateway-Methoden, Tools oder Dienste, die in diesem Zeitfenster existieren müssen +- beliebige HTTP-Routen, die verfügbar sein müssen, bevor das Gateway zu lauschen beginnt +- beliebige Gateway-Methoden, Tools oder Services, die in diesem Zeitraum vorhanden sein müssen -Wenn Ihr vollständiger Entry weiterhin eine erforderliche Startfähigkeit besitzt, aktivieren Sie -dieses Flag nicht. Behalten Sie für das Plugin das Standardverhalten bei und lassen Sie OpenClaw beim Start den -vollständigen Entry laden. +Wenn Ihr vollständiger Einstieg noch eine erforderliche Startfähigkeit besitzt, aktivieren Sie +dieses Flag nicht. Behalten Sie das Standardverhalten bei und lassen Sie OpenClaw den +vollständigen Einstieg während des Starts laden. -Gebündelte Kanäle können außerdem Hilfsfunktionen mit reiner Setup-Vertragsoberfläche veröffentlichen, die der Core -abfragen kann, bevor die vollständige Kanallaufzeit geladen ist. Die aktuelle Setup- -Promotion-Oberfläche ist: +Gebündelte Kanäle können auch nur-Setup-Helfer für Vertragsoberflächen veröffentlichen, die der Kern +abfragen kann, bevor die vollständige Kanal-Laufzeit geladen ist. Die aktuelle Oberfläche +für Setup-Promotion ist: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Der Core verwendet diese Oberfläche, wenn er eine ältere Einzelkonto-Kanal- -Konfiguration in `channels..accounts.*` hochstufen muss, ohne den vollständigen Plugin-Entry zu laden. +Der Kern nutzt diese Oberfläche, wenn er eine Legacy-Einzelkonto-Kanal- +Konfiguration in `channels..accounts.*` überführen muss, ohne den vollständigen Plugin-Einstieg zu laden. Matrix ist das aktuelle gebündelte Beispiel: Es verschiebt nur Auth-/Bootstrap-Schlüssel in ein -benanntes hochgestuftes Konto, wenn bereits benannte Konten existieren, und es kann ein -konfiguriertes nicht-kanonisches Standardkonto beibehalten, statt immer +benanntes hochgestuftes Konto, wenn bereits benannte Konten existieren, und es kann +einen konfigurierten nicht-kanonischen Standard-Kontoschlüssel beibehalten, statt immer `accounts.default` zu erstellen. -Diese Setup-Patch-Adapter halten die Discovery der gebündelten Vertragsoberfläche lazy. Die Importzeit bleibt gering; -die Promotion-Oberfläche wird nur bei der ersten Verwendung geladen, statt beim Modulimport den Start des gebündelten Kanals erneut zu betreten. +Diese Setup-Patch-Adapter halten die Discovery gebündelter Vertragsoberflächen lazy. Die Importzeit +bleibt gering; die Promotionsoberfläche wird nur bei der ersten Verwendung geladen, statt beim Modulimport +erneut den Start gebündelter Kanäle zu betreten. -Wenn diese Startoberflächen Gateway-RPC-Methoden enthalten, halten Sie sie auf einem -pluginspezifischen Präfix. Core-Admin-Namespaces (`config.*`, +Wenn diese Startoberflächen Gateway-RPC-Methoden enthalten, behalten Sie sie auf einem +plugin-spezifischen Präfix. Kern-Admin-Namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) bleiben reserviert und werden immer -zu `operator.admin` aufgelöst, selbst wenn ein Plugin einen schmaleren Scope anfordert. +nach `operator.admin` aufgelöst, selbst wenn ein Plugin einen schmaleren Scope anfordert. Beispiel: @@ -1418,10 +1432,10 @@ Beispiel: } ``` -### Kanal-Katalogmetadaten +### Katalogmetadaten für Kanäle Kanal-Plugins können Setup-/Discovery-Metadaten über `openclaw.channel` und -Installationshinweise über `openclaw.install` bekannt machen. Dadurch bleibt der Core-Katalog frei von Daten. +Installationshinweise über `openclaw.install` bekanntgeben. Dadurch bleiben die Katalogdaten des Kerns datenfrei. Beispiel: @@ -1452,38 +1466,38 @@ Beispiel: Nützliche Felder in `openclaw.channel` über das Minimalbeispiel hinaus: - `detailLabel`: sekundäres Label für reichhaltigere Katalog-/Statusoberflächen -- `docsLabel`: überschreibt den Linktext für den Doku-Link -- `preferOver`: Plugin-/Kanal-IDs niedrigerer Priorität, die dieser Katalogeintrag übertreffen soll -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: Copy-Steuerung für Auswahloberflächen -- `markdownCapable`: markiert den Kanal für Entscheidungen zur Outbound-Formatierung als markdownfähig +- `docsLabel`: Linktext für den Dokumentationslink überschreiben +- `preferOver`: Plugin-/Kanal-IDs niedrigerer Priorität, die dieser Katalogeintrag übertreffen sollte +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: Steuerung von Texten auf Auswahloberflächen +- `markdownCapable`: markiert den Kanal für Entscheidungen zur Outbound-Formatierung als Markdown-fähig - `exposure.configured`: blendet den Kanal aus Oberflächen mit konfigurierten Kanälen aus, wenn auf `false` gesetzt -- `exposure.setup`: blendet den Kanal aus interaktiven Setup-/Konfigurations-Pickern aus, wenn auf `false` gesetzt -- `exposure.docs`: markiert den Kanal für Dokumentationsnavigationsoberflächen als intern/privat -- `showConfigured` / `showInSetup`: ältere Aliasse werden aus Kompatibilitätsgründen weiterhin akzeptiert; `exposure` bevorzugen -- `quickstartAllowFrom`: nimmt den Kanal in den Standard-Quickstart-Flow `allowFrom` auf -- `forceAccountBinding`: verlangt explizite Kontobindung, selbst wenn nur ein Konto existiert -- `preferSessionLookupForAnnounceTarget`: bevorzugt Sitzungs-Lookup bei der Auflösung von Ankündigungszielen +- `exposure.setup`: blendet den Kanal aus interaktiven Setup-/Configure-Pickern aus, wenn auf `false` gesetzt +- `exposure.docs`: markiert den Kanal für Dokumentations-Navigationsoberflächen als intern/privat +- `showConfigured` / `showInSetup`: Legacy-Aliase werden aus Kompatibilitätsgründen weiterhin akzeptiert; bevorzugen Sie `exposure` +- `quickstartAllowFrom`: nimmt den Kanal in den Standard-Quickstart-Ablauf `allowFrom` auf +- `forceAccountBinding`: explizite Kontobindung erzwingen, selbst wenn nur ein Konto existiert +- `preferSessionLookupForAnnounceTarget`: Sitzungs-Lookup bei der Auflösung von Ankündigungszielen bevorzugen -OpenClaw kann auch **externe Kanal-Kataloge** zusammenführen (zum Beispiel einen MPM- -Registry-Export). Legen Sie eine JSON-Datei an einer der folgenden Stellen ab: +OpenClaw kann auch **externe Kanalkataloge** zusammenführen (zum Beispiel einen Export aus einer MPM- +Registry). Legen Sie eine JSON-Datei an einem der folgenden Orte ab: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -Oder zeigen Sie `OPENCLAW_PLUGIN_CATALOG_PATHS` (oder `OPENCLAW_MPM_CATALOG_PATHS`) auf +Oder setzen Sie `OPENCLAW_PLUGIN_CATALOG_PATHS` (oder `OPENCLAW_MPM_CATALOG_PATHS`) auf eine oder mehrere JSON-Dateien (durch Komma/Semikolon/`PATH` getrennt). Jede Datei sollte -`{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }` enthalten. Der Parser akzeptiert außerdem `"packages"` oder `"plugins"` als ältere Aliasse für den Schlüssel `"entries"`. +`{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }` enthalten. Der Parser akzeptiert auch `"packages"` oder `"plugins"` als Legacy-Aliase für den Schlüssel `"entries"`. -## Plugins für Context Engines +## Context-Engine-Plugins -Plugins für Context Engines besitzen die Orchestrierung des Sitzungs- -kontexts für Ingest, Assemblierung und Kompaktierung. Registrieren Sie sie in Ihrem Plugin mit +Context-Engine-Plugins besitzen die Orchestrierung des Sitzungs-Kontexts für Ingest, Zusammenstellung +und Kompaktierung. Registrieren Sie sie aus Ihrem Plugin mit `api.registerContextEngine(id, factory)` und wählen Sie dann die aktive Engine mit `plugins.slots.contextEngine`. Verwenden Sie dies, wenn Ihr Plugin die Standard- -Kontextpipeline ersetzen oder erweitern muss, statt nur Memory-Suche oder Hooks hinzuzufügen. +Context-Pipeline ersetzen oder erweitern muss, statt nur Memory Search oder Hooks hinzuzufügen. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1511,8 +1525,8 @@ export default function (api) { } ``` -Wenn Ihre Engine den Kompaktierungsalgorithmus **nicht** besitzt, halten Sie `compact()` -implementiert und delegieren Sie explizit: +Wenn Ihre Engine den Kompaktierungsalgorithmus **nicht** besitzt, implementieren Sie `compact()` +trotzdem und delegieren Sie ihn explizit: ```ts import { @@ -1549,45 +1563,44 @@ export default function (api) { ## Eine neue Fähigkeit hinzufügen -Wenn ein Plugin Verhalten benötigt, das nicht zur aktuellen API passt, umgehen Sie -das Plugin-System nicht mit einem privaten Eingriff. Fügen Sie die fehlende Fähigkeit hinzu. +Wenn ein Plugin Verhalten benötigt, das nicht in die aktuelle API passt, umgehen Sie +das Plugin-System nicht mit einem privaten Reach-in. Fügen Sie die fehlende Fähigkeit hinzu. Empfohlene Reihenfolge: -1. den Core-Vertrag definieren - Entscheiden Sie, welches gemeinsame Verhalten der Core besitzen sollte: Richtlinie, Fallback, Konfigurations- - Merge, Lebenszyklus, kanalorientierte Semantik und Form der Laufzeit-Hilfsfunktion. -2. typisierte Plugin-Registrierungs-/Laufzeitoberflächen hinzufügen +1. den Kernvertrag definieren + Entscheiden Sie, welches gemeinsame Verhalten der Kern besitzen soll: Richtlinie, Fallback, Konfigurations-Merge, + Lebenszyklus, kanalorientierte Semantik und Form des Laufzeit-Helfers. +2. typisierte Oberflächen für Plugin-Registrierung/Laufzeit hinzufügen Erweitern Sie `OpenClawPluginApi` und/oder `api.runtime` um die kleinste nützliche typisierte Fähigkeitsoberfläche. -3. Core + Kanal-/Feature-Konsumenten verdrahten - Kanäle und Feature-Plugins sollten die neue Fähigkeit über den Core nutzen, - nicht durch direktes Importieren einer Anbieterimplementierung. +3. Kern + Kanal-/Feature-Konsumenten verdrahten + Kanäle und Feature-Plugins sollten die neue Fähigkeit über den Kern konsumieren, + nicht durch direkten Import einer Anbieterimplementierung. 4. Anbieterimplementierungen registrieren - Anbieter-Plugins registrieren dann ihre Backends für diese Fähigkeit. + Anbieter-Plugins registrieren dann ihre Backends gegen die Fähigkeit. 5. Vertragsabdeckung hinzufügen - Fügen Sie Tests hinzu, damit Eigentum und Form der Registrierung über die Zeit explizit bleiben. + Fügen Sie Tests hinzu, damit Ownership und Registrierungsform im Laufe der Zeit explizit bleiben. -So bleibt OpenClaw meinungsstark, ohne an die Sichtweise eines -einzigen Providers hart gebunden zu werden. Siehe das [Capability Cookbook](/de/plugins/architecture) -für eine konkrete Dateicheckliste und ein ausgearbeitetes Beispiel. +So bleibt OpenClaw meinungsstark, ohne an die Sichtweise eines einzelnen +Providers hart gekoppelt zu werden. Eine konkrete Dateicheckliste und ein ausgearbeitetes Beispiel finden Sie im [Capability Cookbook](/de/plugins/architecture). ### Checkliste für Fähigkeiten -Wenn Sie eine neue Fähigkeit hinzufügen, sollte die Implementierung normalerweise -diese Oberflächen gemeinsam berühren: +Wenn Sie eine neue Fähigkeit hinzufügen, sollte die Implementierung in der Regel diese +Oberflächen gemeinsam berühren: -- Core-Vertragstypen in `src//types.ts` -- Core-Runner/Laufzeit-Hilfsfunktion in `src//runtime.ts` +- Kernvertragstypen in `src//types.ts` +- Kern-Runner/Laufzeit-Helper in `src//runtime.ts` - Plugin-API-Registrierungsoberfläche in `src/plugins/types.ts` - Verdrahtung der Plugin-Registry in `src/plugins/registry.ts` -- Laufzeit-Exposition von Plugins in `src/plugins/runtime/*`, wenn Feature-/Kanal- - Plugins sie nutzen müssen -- Capture-/Test-Hilfsfunktionen in `src/test-utils/plugin-registration.ts` -- Assertions zu Eigentum/Verträgen in `src/plugins/contracts/registry.ts` +- Bereitstellung der Plugin-Laufzeit in `src/plugins/runtime/*`, wenn Feature-/Kanal- + Plugins sie konsumieren müssen +- Capture-/Test-Helper in `src/test-utils/plugin-registration.ts` +- Ownership-/Vertragsprüfungen in `src/plugins/contracts/registry.ts` - Operator-/Plugin-Dokumentation in `docs/` -Wenn eine dieser Oberflächen fehlt, ist das normalerweise ein Zeichen dafür, dass die Fähigkeit +Wenn eine dieser Oberflächen fehlt, ist das in der Regel ein Zeichen dafür, dass die Fähigkeit noch nicht vollständig integriert ist. ### Vorlage für Fähigkeiten @@ -1624,9 +1637,9 @@ Muster für Vertragstests: expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Damit bleibt die Regel einfach: +Das hält die Regel einfach: -- der Core besitzt den Fähigkeitsvertrag + die Orchestrierung +- der Kern besitzt den Fähigkeitsvertrag + die Orchestrierung - Anbieter-Plugins besitzen Anbieterimplementierungen -- Feature-/Kanal-Plugins nutzen Laufzeit-Hilfsfunktionen -- Vertragstests halten Eigentum explizit +- Feature-/Kanal-Plugins konsumieren Laufzeit-Helfer +- Vertragstests halten Ownership explizit diff --git a/docs/de/plugins/manifest.md b/docs/de/plugins/manifest.md index bc926603e..56f3b26d6 100644 --- a/docs/de/plugins/manifest.md +++ b/docs/de/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - Sie erstellen ein OpenClaw-Plugin - - Sie müssen ein Plugin-Konfigurationsschema ausliefern oder Plugin-Validierungsfehler debuggen + - Sie müssen ein Plugin-Konfigurationsschema bereitstellen oder Fehler bei der Plugin-Validierung debuggen summary: Anforderungen an Plugin-Manifest + JSON-Schema (strikte Konfigurationsvalidierung) title: Plugin-Manifest x-i18n: - generated_at: "2026-04-07T06:17:35Z" + generated_at: "2026-04-09T01:29:53Z" model: gpt-5.4 provider: openai - source_hash: 22d41b9f8748b1b1b066ee856be4a8f41e88b9a8bc073d74fc79d2bb0982f01a + source_hash: 9a7ee4b621a801d2a8f32f8976b0e1d9433c7810eb360aca466031fc0ffb286a source_path: plugins/manifest.md workflow: 15 --- @@ -17,7 +17,7 @@ x-i18n: Diese Seite gilt nur für das **native OpenClaw-Plugin-Manifest**. -Kompatible Bundle-Layouts finden Sie unter [Plugin bundles](/de/plugins/bundles). +Kompatible Bundle-Layouts finden Sie unter [Plugin-Bundles](/de/plugins/bundles). Kompatible Bundle-Formate verwenden andere Manifestdateien: @@ -27,23 +27,24 @@ Kompatible Bundle-Formate verwenden andere Manifestdateien: - Cursor-Bundle: `.cursor-plugin/plugin.json` OpenClaw erkennt diese Bundle-Layouts ebenfalls automatisch, sie werden jedoch nicht -gegen das hier beschriebene Schema für `openclaw.plugin.json` validiert. +gegen das hier beschriebene Schema von `openclaw.plugin.json` validiert. -Für kompatible Bundles liest OpenClaw derzeit Bundle-Metadaten plus deklarierte -Skill-Stammverzeichnisse, Claude-Befehlsstammverzeichnisse, Standardwerte aus `settings.json` von Claude-Bundles, -Standardwerte für Claude-Bundle-LSPs und unterstützte Hook-Pakete, wenn das Layout den -Laufzeiterwartungen von OpenClaw entspricht. +Für kompatible Bundles liest OpenClaw derzeit Bundle-Metadaten sowie deklarierte +Skill-Stammverzeichnisse, Claude-Befehlsstammverzeichnisse, Standardwerte aus +`settings.json` für Claude-Bundles, Standardwerte für Claude-Bundle-LSPs +und unterstützte Hook-Packs, wenn das Layout den Laufzeiterwartungen von +OpenClaw entspricht. -Jedes native OpenClaw-Plugin **muss** im -**Plugin-Stammverzeichnis** eine Datei `openclaw.plugin.json` ausliefern. OpenClaw verwendet dieses Manifest, um die Konfiguration zu validieren, -**ohne Plugin-Code auszuführen**. Fehlende oder ungültige Manifeste werden als +Jedes native OpenClaw-Plugin **muss** eine Datei `openclaw.plugin.json` im +**Plugin-Stammverzeichnis** bereitstellen. OpenClaw verwendet dieses Manifest, um die Konfiguration +**ohne Ausführung von Plugin-Code** zu validieren. Fehlende oder ungültige Manifeste werden als Plugin-Fehler behandelt und blockieren die Konfigurationsvalidierung. Den vollständigen Leitfaden zum Plugin-System finden Sie unter: [Plugins](/de/tools/plugin). Zum nativen Fähigkeitsmodell und den aktuellen Hinweisen zur externen Kompatibilität: [Fähigkeitsmodell](/de/plugins/architecture#public-capability-model). -## Was diese Datei macht +## Wozu diese Datei dient `openclaw.plugin.json` sind die Metadaten, die OpenClaw liest, bevor Ihr Plugin-Code geladen wird. @@ -54,19 +55,20 @@ Verwenden Sie sie für: - Konfigurationsvalidierung - Auth- und Onboarding-Metadaten, die verfügbar sein sollen, ohne die Plugin- Laufzeit zu starten -- Alias- und Autoaktivierungs-Metadaten, die aufgelöst werden sollen, bevor die Plugin-Laufzeit geladen wird -- Kurzmetadaten zur Besitzerschaft von Modellfamilien, die das +- Alias- und Autoaktivierungs-Metadaten, die aufgelöst werden sollen, bevor die + Plugin-Laufzeit geladen wird +- Kurzform-Metadaten zur Modellfamilien-Zugehörigkeit, die das Plugin vor dem Laden der Laufzeit automatisch aktivieren sollen -- statische Snapshots der Fähigkeitsbesitzerschaft, die für gebündelte Kompatibilitätsverkabelung und +- statische Snapshots zur Fähigkeitszuordnung, die für gebündelte Kompatibilitätsverdrahtung und Vertragsabdeckung verwendet werden -- kanalspezifische Konfigurationsmetadaten, die vor dem Laden der Laufzeit in Katalog- und Validierungs- - Oberflächen zusammengeführt werden sollen +- kanalspezifische Konfigurationsmetadaten, die in Katalog- und Validierungsoberflächen + zusammengeführt werden sollen, ohne die Laufzeit zu laden - Hinweise für die Konfigurations-UI Verwenden Sie sie nicht für: - Registrierung von Laufzeitverhalten -- Deklaration von Code-Entrypoints +- Deklaration von Code-Einstiegspunkten - npm-Installationsmetadaten Diese gehören in Ihren Plugin-Code und in `package.json`. @@ -90,7 +92,7 @@ Diese gehören in Ihren Plugin-Code und in `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "OpenRouter-Provider-Plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -100,6 +102,9 @@ Diese gehören in Ihren Plugin-Code und in `package.json`. "providerAuthEnvVars": { "openrouter": ["OPENROUTER_API_KEY"] }, + "providerAuthAliases": { + "openrouter-coding": "openrouter" + }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, @@ -108,19 +113,19 @@ Diese gehören in Ihren Plugin-Code und in `package.json`. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "OpenRouter-API-Schlüssel", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "OpenRouter-API-Schlüssel", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "API-Schlüssel", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -139,63 +144,64 @@ Diese gehören in Ihren Plugin-Code und in `package.json`. ## Referenz der Felder auf oberster Ebene -| Feld | Erforderlich | Typ | Bedeutung | -| ----------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Ja | `string` | Kanonische Plugin-ID. Dies ist die ID, die in `plugins.entries.` verwendet wird. | -| `configSchema` | Ja | `object` | Inline-JSON-Schema für die Konfiguration dieses Plugins. | -| `enabledByDefault` | Nein | `true` | Markiert ein gebündeltes Plugin als standardmäßig aktiviert. Lassen Sie es weg oder setzen Sie einen beliebigen Wert ungleich `true`, damit das Plugin standardmäßig deaktiviert bleibt. | -| `legacyPluginIds` | Nein | `string[]` | Legacy-IDs, die auf diese kanonische Plugin-ID normalisiert werden. | -| `autoEnableWhenConfiguredProviders` | Nein | `string[]` | Anbieter-IDs, die dieses Plugin automatisch aktivieren sollen, wenn Auth, Konfiguration oder Modellreferenzen sie erwähnen. | -| `kind` | Nein | `"memory"` \| `"context-engine"` | Deklariert eine exklusive Plugin-Art, die von `plugins.slots.*` verwendet wird. | -| `channels` | Nein | `string[]` | Kanal-IDs, die diesem Plugin gehören. Werden für Discovery und Konfigurationsvalidierung verwendet. | -| `providers` | Nein | `string[]` | Anbieter-IDs, die diesem Plugin gehören. | -| `modelSupport` | Nein | `object` | Manifest-eigene Kurzmetadaten zu Modellfamilien, die verwendet werden, um das Plugin vor der Laufzeit automatisch zu laden. | -| `cliBackends` | Nein | `string[]` | IDs von CLI-Inferenz-Backends, die diesem Plugin gehören. Werden zur automatischen Aktivierung beim Start anhand expliziter Konfigurationsreferenzen verwendet. | -| `providerAuthEnvVars` | Nein | `Record` | Günstige Anbieter-Auth-Env-Metadaten, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. | -| `channelEnvVars` | Nein | `Record` | Günstige Kanal-Env-Metadaten, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. Verwenden Sie dies für env-gesteuerte Kanaleinrichtung oder Auth-Oberflächen, die generische Start-/Konfigurationshilfen sehen sollen. | -| `providerAuthChoices` | Nein | `object[]` | Günstige Metadaten zu Auth-Auswahlen für Onboarding-Auswahlen, bevorzugte Anbieterauflösung und einfache CLI-Flag-Verdrahtung. | -| `contracts` | Nein | `object` | Statischer gebündelter Fähigkeitssnapshot für Sprache, Echtzeittranskription, Echtzeitstimme, Medienverständnis, Bildgenerierung, Musikgenerierung, Videogenerierung, Web-Abruf, Websuche und Tool-Besitzerschaft. | -| `channelConfigs` | Nein | `Record` | Manifest-eigene Kanal-Konfigurationsmetadaten, die in Discovery- und Validierungsoberflächen zusammengeführt werden, bevor die Laufzeit geladen wird. | -| `skills` | Nein | `string[]` | Skill-Verzeichnisse, die relativ zum Plugin-Stammverzeichnis geladen werden. | -| `name` | Nein | `string` | Menschenlesbarer Plugin-Name. | -| `description` | Nein | `string` | Kurze Zusammenfassung, die in Plugin-Oberflächen angezeigt wird. | -| `version` | Nein | `string` | Informative Plugin-Version. | -| `uiHints` | Nein | `Record` | UI-Beschriftungen, Platzhalter und Sensitivitätshinweise für Konfigurationsfelder. | +| Feld | Erforderlich | Typ | Bedeutung | +| ----------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Ja | `string` | Kanonische Plugin-ID. Dies ist die ID, die in `plugins.entries.` verwendet wird. | +| `configSchema` | Ja | `object` | Inline-JSON-Schema für die Konfiguration dieses Plugins. | +| `enabledByDefault` | Nein | `true` | Kennzeichnet ein gebündeltes Plugin als standardmäßig aktiviert. Lassen Sie das Feld weg oder setzen Sie einen beliebigen Wert ungleich `true`, damit das Plugin standardmäßig deaktiviert bleibt. | +| `legacyPluginIds` | Nein | `string[]` | Legacy-IDs, die auf diese kanonische Plugin-ID normalisiert werden. | +| `autoEnableWhenConfiguredProviders` | Nein | `string[]` | Provider-IDs, die dieses Plugin automatisch aktivieren sollen, wenn Auth, Konfiguration oder Modellreferenzen sie erwähnen. | +| `kind` | Nein | `"memory"` \| `"context-engine"` | Deklariert eine exklusive Plugin-Art, die von `plugins.slots.*` verwendet wird. | +| `channels` | Nein | `string[]` | Kanal-IDs, die diesem Plugin gehören. Wird für Erkennung und Konfigurationsvalidierung verwendet. | +| `providers` | Nein | `string[]` | Provider-IDs, die diesem Plugin gehören. | +| `modelSupport` | Nein | `object` | Manifest-eigene Kurzform-Metadaten zu Modellfamilien, mit denen das Plugin vor der Laufzeit automatisch geladen wird. | +| `cliBackends` | Nein | `string[]` | IDs von CLI-Inferenz-Backends, die diesem Plugin gehören. Wird für die automatische Aktivierung beim Start aus expliziten Konfigurationsreferenzen verwendet. | +| `providerAuthEnvVars` | Nein | `Record` | Leichtgewichtige Metadaten zu Provider-Auth-Umgebungsvariablen, die OpenClaw ohne Laden von Plugin-Code prüfen kann. | +| `providerAuthAliases` | Nein | `Record` | Provider-IDs, die für die Auth-Suche eine andere Provider-ID wiederverwenden sollen, zum Beispiel ein Coding-Provider, der denselben API-Schlüssel und dieselben Auth-Profile wie der Basis-Provider teilt. | +| `channelEnvVars` | Nein | `Record` | Leichtgewichtige Kanal-Metadaten zu Umgebungsvariablen, die OpenClaw ohne Laden von Plugin-Code prüfen kann. Verwenden Sie dies für umgebungsvariablengesteuerte Kanaleinrichtung oder Auth-Oberflächen, die generische Start-/Konfigurationshilfen sehen sollen. | +| `providerAuthChoices` | Nein | `object[]` | Leichtgewichtige Metadaten zu Auth-Auswahlen für Onboarding-Auswahlfelder, die Auflösung bevorzugter Provider und einfache Verdrahtung von CLI-Flags. | +| `contracts` | Nein | `object` | Statischer Snapshot gebündelter Fähigkeiten für Sprach-, Echtzeit-Transkriptions-, Echtzeit-Sprach-, Medienverständnis-, Bildgenerierungs-, Musikgenerierungs-, Videogenerierungs-, Web-Fetch-, Web-Such- und Werkzeug-Zuständigkeit. | +| `channelConfigs` | Nein | `Record` | Manifest-eigene Kanal-Konfigurationsmetadaten, die in Erkennungs- und Validierungsoberflächen zusammengeführt werden, bevor die Laufzeit geladen wird. | +| `skills` | Nein | `string[]` | Skill-Verzeichnisse, die relativ zum Plugin-Stammverzeichnis geladen werden sollen. | +| `name` | Nein | `string` | Menschenlesbarer Plugin-Name. | +| `description` | Nein | `string` | Kurze Zusammenfassung, die in Plugin-Oberflächen angezeigt wird. | +| `version` | Nein | `string` | Informative Plugin-Version. | +| `uiHints` | Nein | `Record` | UI-Beschriftungen, Platzhalter und Hinweise zur Sensitivität für Konfigurationsfelder. | -## Referenz für `providerAuthChoices` +## Referenz zu `providerAuthChoices` Jeder Eintrag in `providerAuthChoices` beschreibt eine Onboarding- oder Auth-Auswahl. -OpenClaw liest dies, bevor die Anbieter-Laufzeit geladen wird. +OpenClaw liest diese, bevor die Provider-Laufzeit geladen wird. -| Feld | Erforderlich | Typ | Bedeutung | -| --------------------- | ------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| `provider` | Ja | `string` | Anbieter-ID, zu der diese Auswahl gehört. | -| `method` | Ja | `string` | ID der Auth-Methode, an die weitergeleitet wird. | -| `choiceId` | Ja | `string` | Stabile Auth-Auswahl-ID, die von Onboarding- und CLI-Abläufen verwendet wird. | -| `choiceLabel` | Nein | `string` | Benutzerseitige Bezeichnung. Wenn weggelassen, greift OpenClaw auf `choiceId` zurück. | -| `choiceHint` | Nein | `string` | Kurzer Hilfetext für die Auswahl. | -| `assistantPriority` | Nein | `number` | Niedrigere Werte werden in assistentengesteuerten interaktiven Auswahlen früher sortiert. | -| `assistantVisibility` | Nein | `"visible"` \| `"manual-only"` | Blendet die Auswahl in Assistenten-Auswahlen aus, erlaubt aber weiterhin die manuelle CLI-Auswahl. | -| `deprecatedChoiceIds` | Nein | `string[]` | Legacy-Auswahl-IDs, die Benutzer auf diese Ersatzauswahl umleiten sollen. | -| `groupId` | Nein | `string` | Optionale Gruppen-ID zum Gruppieren verwandter Auswahlen. | -| `groupLabel` | Nein | `string` | Benutzerseitige Bezeichnung für diese Gruppe. | -| `groupHint` | Nein | `string` | Kurzer Hilfetext für die Gruppe. | -| `optionKey` | Nein | `string` | Interner Optionsschlüssel für einfache Auth-Abläufe mit einem einzelnen Flag. | -| `cliFlag` | Nein | `string` | Name des CLI-Flags, z. B. `--openrouter-api-key`. | -| `cliOption` | Nein | `string` | Vollständige Form der CLI-Option, z. B. `--openrouter-api-key `. | -| `cliDescription` | Nein | `string` | Beschreibung, die in der CLI-Hilfe verwendet wird. | -| `onboardingScopes` | Nein | `Array<"text-inference" \| "image-generation">` | In welchen Onboarding-Oberflächen diese Auswahl erscheinen soll. Wenn weggelassen, ist der Standard `["text-inference"]`. | +| Feld | Erforderlich | Typ | Bedeutung | +| --------------------- | ------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | Ja | `string` | Provider-ID, zu der diese Auswahl gehört. | +| `method` | Ja | `string` | ID der Auth-Methode, an die weitergeleitet wird. | +| `choiceId` | Ja | `string` | Stabile ID der Auth-Auswahl, die von Onboarding- und CLI-Abläufen verwendet wird. | +| `choiceLabel` | Nein | `string` | Benutzerseitige Beschriftung. Wenn weggelassen, greift OpenClaw auf `choiceId` zurück. | +| `choiceHint` | Nein | `string` | Kurzer Hilfetext für das Auswahlfeld. | +| `assistantPriority` | Nein | `number` | Kleinere Werte werden in assistantgesteuerten interaktiven Auswahlfeldern früher sortiert. | +| `assistantVisibility` | Nein | `"visible"` \| `"manual-only"` | Blendet die Auswahl in Assistant-Auswahlfeldern aus, erlaubt aber weiterhin die manuelle Auswahl per CLI. | +| `deprecatedChoiceIds` | Nein | `string[]` | Legacy-IDs für Auswahlen, die Benutzer auf diese Ersatz-Auswahl umleiten sollen. | +| `groupId` | Nein | `string` | Optionale Gruppen-ID zum Gruppieren verwandter Auswahlen. | +| `groupLabel` | Nein | `string` | Benutzerseitige Beschriftung für diese Gruppe. | +| `groupHint` | Nein | `string` | Kurzer Hilfetext für die Gruppe. | +| `optionKey` | Nein | `string` | Interner Optionsschlüssel für einfache Auth-Abläufe mit nur einem Flag. | +| `cliFlag` | Nein | `string` | Name des CLI-Flags, etwa `--openrouter-api-key`. | +| `cliOption` | Nein | `string` | Vollständige Form der CLI-Option, etwa `--openrouter-api-key `. | +| `cliDescription` | Nein | `string` | Beschreibung, die in der CLI-Hilfe verwendet wird. | +| `onboardingScopes` | Nein | `Array<"text-inference" \| "image-generation">` | In welchen Onboarding-Oberflächen diese Auswahl erscheinen soll. Wenn weggelassen, lautet der Standard `["text-inference"]`. | -## Referenz für `uiHints` +## Referenz zu `uiHints` -`uiHints` ist eine Zuordnung von Konfigurationsfeldnamen zu kleinen Render-Hinweisen. +`uiHints` ist eine Zuordnung von Namen von Konfigurationsfeldern zu kleinen Darstellungs-Hinweisen. ```json { "uiHints": { "apiKey": { - "label": "API key", - "help": "Used for OpenRouter requests", + "label": "API-Schlüssel", + "help": "Wird für OpenRouter-Anfragen verwendet", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -205,18 +211,18 @@ OpenClaw liest dies, bevor die Anbieter-Laufzeit geladen wird. Jeder Feldhinweis kann Folgendes enthalten: -| Feld | Typ | Bedeutung | -| ------------- | ---------- | ------------------------------------------- | -| `label` | `string` | Benutzerseitige Feldbezeichnung. | -| `help` | `string` | Kurzer Hilfetext. | -| `tags` | `string[]` | Optionale UI-Tags. | -| `advanced` | `boolean` | Markiert das Feld als erweitert. | -| `sensitive` | `boolean` | Markiert das Feld als geheim oder sensibel. | -| `placeholder` | `string` | Platzhaltertext für Formulareingaben. | +| Feld | Typ | Bedeutung | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Benutzerseitige Feldbeschriftung. | +| `help` | `string` | Kurzer Hilfetext. | +| `tags` | `string[]` | Optionale UI-Tags. | +| `advanced` | `boolean` | Kennzeichnet das Feld als erweitert. | +| `sensitive` | `boolean` | Kennzeichnet das Feld als geheim oder sensibel. | +| `placeholder` | `string` | Platzhaltertext für Formulareingaben. | -## Referenz für `contracts` +## Referenz zu `contracts` -Verwenden Sie `contracts` nur für statische Metadaten zur Fähigkeitsbesitzerschaft, die OpenClaw +Verwenden Sie `contracts` nur für statische Metadaten zur Fähigkeitszuordnung, die OpenClaw lesen kann, ohne die Plugin-Laufzeit zu importieren. ```json @@ -239,20 +245,20 @@ Jede Liste ist optional: | Feld | Typ | Bedeutung | | -------------------------------- | ---------- | -------------------------------------------------------------- | -| `speechProviders` | `string[]` | IDs von Sprachanbietern, die diesem Plugin gehören. | -| `realtimeTranscriptionProviders` | `string[]` | IDs von Echtzeit-Transkriptionsanbietern, die diesem Plugin gehören. | -| `realtimeVoiceProviders` | `string[]` | IDs von Echtzeit-Stimmanbietern, die diesem Plugin gehören. | -| `mediaUnderstandingProviders` | `string[]` | IDs von Medienverständnis-Anbietern, die diesem Plugin gehören. | -| `imageGenerationProviders` | `string[]` | IDs von Bildgenerierungsanbietern, die diesem Plugin gehören. | -| `videoGenerationProviders` | `string[]` | IDs von Videogenerierungsanbietern, die diesem Plugin gehören. | -| `webFetchProviders` | `string[]` | IDs von Web-Abruf-Anbietern, die diesem Plugin gehören. | -| `webSearchProviders` | `string[]` | IDs von Websuchanbietern, die diesem Plugin gehören. | -| `tools` | `string[]` | Namen von Agent-Tools, die diesem Plugin für gebündelte Vertragsprüfungen gehören. | +| `speechProviders` | `string[]` | IDs von Sprach-Providern, die diesem Plugin gehören. | +| `realtimeTranscriptionProviders` | `string[]` | IDs von Echtzeit-Transkriptions-Providern, die diesem Plugin gehören. | +| `realtimeVoiceProviders` | `string[]` | IDs von Echtzeit-Sprach-Providern, die diesem Plugin gehören. | +| `mediaUnderstandingProviders` | `string[]` | IDs von Providern für Medienverständnis, die diesem Plugin gehören. | +| `imageGenerationProviders` | `string[]` | IDs von Bildgenerierungs-Providern, die diesem Plugin gehören. | +| `videoGenerationProviders` | `string[]` | IDs von Videogenerierungs-Providern, die diesem Plugin gehören. | +| `webFetchProviders` | `string[]` | IDs von Web-Fetch-Providern, die diesem Plugin gehören. | +| `webSearchProviders` | `string[]` | IDs von Web-Such-Providern, die diesem Plugin gehören. | +| `tools` | `string[]` | Namen von Agentenwerkzeugen, die diesem Plugin für Prüfungen gebündelter Verträge gehören. | -## Referenz für `channelConfigs` +## Referenz zu `channelConfigs` -Verwenden Sie `channelConfigs`, wenn ein Kanal-Plugin günstige Konfigurationsmetadaten benötigt, bevor -die Laufzeit geladen wird. +Verwenden Sie `channelConfigs`, wenn ein Kanal-Plugin vor dem Laden der +Laufzeit leichtgewichtige Konfigurationsmetadaten benötigt. ```json { @@ -267,12 +273,12 @@ die Laufzeit geladen wird. }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "Homeserver-URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Verbindung zum Matrix-Homeserver", "preferOver": ["matrix-legacy"] } } @@ -281,17 +287,17 @@ die Laufzeit geladen wird. Jeder Kanaleintrag kann Folgendes enthalten: -| Feld | Typ | Bedeutung | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | +| Feld | Typ | Bedeutung | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | | `schema` | `object` | JSON-Schema für `channels.`. Für jeden deklarierten Kanal-Konfigurationseintrag erforderlich. | -| `uiHints` | `Record` | Optionale UI-Beschriftungen/Platzhalter/Sensitivitätshinweise für diesen Kanal-Konfigurationsabschnitt. | -| `label` | `string` | Kanalbezeichnung, die in Auswahl- und Prüfoberflächen zusammengeführt wird, wenn Laufzeitmetadaten noch nicht bereit sind. | -| `description` | `string` | Kurze Kanalbeschreibung für Prüf- und Katalogoberflächen. | -| `preferOver` | `string[]` | Legacy- oder Plugins mit niedrigerer Priorität, die dieser Kanal in Auswahloberflächen übertreffen soll. | +| `uiHints` | `Record` | Optionale UI-Beschriftungen/Platzhalter/Hinweise zur Sensitivität für diesen Kanal-Konfigurationsabschnitt. | +| `label` | `string` | Kanalbeschriftung, die in Auswahl- und Prüfoberflächen zusammengeführt wird, wenn Laufzeitmetadaten noch nicht bereit sind. | +| `description` | `string` | Kurze Kanalbeschreibung für Prüf- und Katalogoberflächen. | +| `preferOver` | `string[]` | Legacy- oder Plugin-IDs mit niedrigerer Priorität, die dieser Kanal in Auswahloberflächen übertreffen soll. | -## Referenz für `modelSupport` +## Referenz zu `modelSupport` -Verwenden Sie `modelSupport`, wenn OpenClaw Ihr Anbieter-Plugin aus +Verwenden Sie `modelSupport`, wenn OpenClaw Ihr Provider-Plugin aus Kurzform-Modell-IDs wie `gpt-5.4` oder `claude-sonnet-4.6` ableiten soll, bevor die Plugin-Laufzeit geladen wird. @@ -304,75 +310,76 @@ geladen wird. } ``` -OpenClaw verwendet diese Reihenfolge: +OpenClaw wendet folgende Rangfolge an: -- explizite `provider/model`-Referenzen verwenden die Manifest-Metadaten des besitzenden `providers` +- explizite Referenzen `provider/model` verwenden die Manifest-Metadaten des zuständigen `providers` - `modelPatterns` haben Vorrang vor `modelPrefixes` -- wenn ein nicht gebündeltes Plugin und ein gebündeltes Plugin beide passen, gewinnt das nicht gebündelte +- wenn sowohl ein nicht gebündeltes Plugin als auch ein gebündeltes Plugin passen, gewinnt das nicht gebündelte Plugin -- verbleibende Mehrdeutigkeit wird ignoriert, bis der Benutzer oder die Konfiguration einen Anbieter angibt +- verbleibende Mehrdeutigkeit wird ignoriert, bis der Benutzer oder die Konfiguration einen Provider angibt Felder: | Feld | Typ | Bedeutung | | --------------- | ---------- | ------------------------------------------------------------------------------ | | `modelPrefixes` | `string[]` | Präfixe, die mit `startsWith` gegen Kurzform-Modell-IDs abgeglichen werden. | -| `modelPatterns` | `string[]` | Regex-Quellen, die nach dem Entfernen von Profilsuffixen gegen Kurzform-Modell-IDs abgeglichen werden. | +| `modelPatterns` | `string[]` | Regex-Quellen, die nach dem Entfernen des Profilsuffixes gegen Kurzform-Modell-IDs abgeglichen werden. | Legacy-Fähigkeitsschlüssel auf oberster Ebene sind veraltet. Verwenden Sie `openclaw doctor --fix`, um `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` und `webSearchProviders` unter `contracts` zu -verschieben; das normale Laden von Manifesten behandelt diese Felder auf oberster Ebene nicht mehr als -Fähigkeitsbesitzerschaft. +verschieben; das normale Laden des Manifests behandelt diese Felder auf oberster Ebene nicht mehr als +Zuständigkeit für Fähigkeiten. -## Manifest im Vergleich zu package.json +## Manifest versus package.json Die beiden Dateien erfüllen unterschiedliche Aufgaben: -| Datei | Verwenden Sie sie für | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Discovery, Konfigurationsvalidierung, Metadaten zu Auth-Auswahlen und UI-Hinweise, die vorhanden sein müssen, bevor Plugin-Code ausgeführt wird | -| `package.json` | npm-Metadaten, Abhängigkeitsinstallation und den Block `openclaw`, der für Entrypoints, Installations-Gating, Einrichtung oder Katalogmetadaten verwendet wird | +| Datei | Verwenden Sie sie für | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.plugin.json` | Erkennung, Konfigurationsvalidierung, Metadaten zu Auth-Auswahlen und UI-Hinweise, die vorhanden sein müssen, bevor Plugin-Code ausgeführt wird | +| `package.json` | npm-Metadaten, Abhängigkeitsinstallation und den Block `openclaw`, der für Einstiegspunkte, Installationssteuerung, Einrichtung oder Katalogmetadaten verwendet wird | -Wenn Sie unsicher sind, wohin ein Metadatenelement gehört, verwenden Sie diese Regel: +Wenn Sie nicht sicher sind, wohin ein Metadatum gehört, verwenden Sie diese Regel: - wenn OpenClaw es kennen muss, bevor Plugin-Code geladen wird, gehört es in `openclaw.plugin.json` -- wenn es um Packaging, Eingabedateien oder das Installationsverhalten von npm geht, gehört es in `package.json` +- wenn es um Packaging, Einstiegsdateien oder das npm-Installationsverhalten geht, gehört es in `package.json` -### package.json-Felder, die die Discovery beeinflussen +### `package.json`-Felder, die die Erkennung beeinflussen -Einige Plugin-Metadaten vor der Laufzeit befinden sich absichtlich in `package.json` unter dem +Einige Plugin-Metadaten vor der Laufzeit liegen absichtlich in `package.json` im Block `openclaw` statt in `openclaw.plugin.json`. Wichtige Beispiele: | Feld | Bedeutung | | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Deklariert native Plugin-Entrypoints. | -| `openclaw.setupEntry` | Leichtgewichtiger Entrypoint nur für die Einrichtung, der beim Onboarding und beim verzögerten Kanalstart verwendet wird. | -| `openclaw.channel` | Günstige Kanal-Katalogmetadaten wie Bezeichnungen, Dokumentationspfade, Aliasse und Auswahltexte. | -| `openclaw.channel.configuredState` | Leichtgewichtige Metadaten für die Prüfung des konfigurierten Zustands, die ohne Laden der vollständigen Kanal-Laufzeit beantworten können: "Existiert bereits eine rein env-basierte Einrichtung?" | -| `openclaw.channel.persistedAuthState` | Leichtgewichtige Metadaten für die Prüfung des persistierten Auth-Zustands, die ohne Laden der vollständigen Kanal-Laufzeit beantworten können: "Ist bereits etwas angemeldet?" | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Installations-/Aktualisierungshinweise für gebündelte und extern veröffentlichte Plugins. | -| `openclaw.install.defaultChoice` | Bevorzugter Installationspfad, wenn mehrere Installationsquellen verfügbar sind. | -| `openclaw.install.minHostVersion` | Minimale unterstützte OpenClaw-Host-Version, mit einer semver-Untergrenze wie `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Erlaubt einen engen Wiederherstellungspfad für die Neuinstallation gebündelter Plugins, wenn die Konfiguration ungültig ist. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Erlaubt das Laden von Kanaloberflächen nur für die Einrichtung vor dem vollständigen Kanal-Plugin während des Starts. | +| `openclaw.extensions` | Deklariert native Plugin-Einstiegspunkte. | +| `openclaw.setupEntry` | Leichtgewichtiger Einstiegspunkt nur für die Einrichtung, der während Onboarding und verzögertem Kanalstart verwendet wird. | +| `openclaw.channel` | Leichtgewichtige Metadaten zum Kanalkatalog wie Beschriftungen, Dokumentationspfade, Aliase und Auswahltexte. | +| `openclaw.channel.configuredState` | Leichtgewichtige Metadaten für den Prüfer des konfigurierten Zustands, der beantworten kann: „Gibt es bereits eine rein umgebungsvariablenbasierte Einrichtung?“ ohne die vollständige Kanallaufzeit zu laden. | +| `openclaw.channel.persistedAuthState` | Leichtgewichtige Metadaten für den Prüfer des persistenten Auth-Zustands, der beantworten kann: „Ist bereits irgendetwas angemeldet?“ ohne die vollständige Kanallaufzeit zu laden. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Hinweise zur Installation/Aktualisierung für gebündelte und extern veröffentlichte Plugins. | +| `openclaw.install.defaultChoice` | Bevorzugter Installationspfad, wenn mehrere Installationsquellen verfügbar sind. | +| `openclaw.install.minHostVersion` | Mindestunterstützte OpenClaw-Hostversion mit einer Semver-Untergrenze wie `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Erlaubt einen eng begrenzten Wiederherstellungspfad bei Neuinstallation gebündelter Plugins, wenn die Konfiguration ungültig ist. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Ermöglicht das Laden von Kanaloberflächen nur für die Einrichtung vor dem vollständigen Kanal-Plugin beim Start. | -`openclaw.install.minHostVersion` wird während der Installation und beim Laden des -Manifest-Registers erzwungen. Ungültige Werte werden abgelehnt; neuere, aber gültige Werte überspringen das +`openclaw.install.minHostVersion` wird während der Installation und beim Laden der +Manifest-Registry erzwungen. Ungültige Werte werden abgelehnt; neuere, aber gültige Werte überspringen das Plugin auf älteren Hosts. -`openclaw.install.allowInvalidConfigRecovery` ist absichtlich eng gefasst. Es +`openclaw.install.allowInvalidConfigRecovery` ist absichtlich eng begrenzt. Es macht nicht beliebige defekte Konfigurationen installierbar. Derzeit erlaubt es nur Installationsabläufen, -sich von bestimmten veralteten Upgrade-Fehlern bei gebündelten Plugins zu erholen, etwa einem -fehlenden gebündelten Plugin-Pfad oder einem veralteten `channels.`-Eintrag für dasselbe -gebündelte Plugin. Nicht zusammenhängende Konfigurationsfehler blockieren die Installation weiterhin und schicken Betreiber zu +sich von bestimmten veralteten Upgrade-Fehlern gebündelter Plugins zu erholen, etwa bei einem +fehlenden gebündelten Plugin-Pfad oder einem veralteten Eintrag `channels.` für dasselbe +gebündelte Plugin. Nicht zusammenhängende Konfigurationsfehler blockieren die Installation weiterhin und verweisen Betreiber an `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` ist Paketmetadaten für ein kleines Prüfermodul: +`openclaw.channel.persistedAuthState` ist Package-Metadaten für ein kleines +Prüfmodul: ```json { @@ -388,13 +395,13 @@ gebündelte Plugin. Nicht zusammenhängende Konfigurationsfehler blockieren die } ``` -Verwenden Sie es, wenn Einrichtung, Doctor oder Abläufe zum konfigurierten Zustand vor dem Laden des vollständigen -Kanal-Plugins eine günstige Ja/Nein-Auth-Sondierung benötigen. Der Ziel-Export sollte eine kleine -Funktion sein, die nur persistierten Zustand liest; leiten Sie ihn nicht über die vollständige -Kanal-Laufzeit-Barrel-Datei. +Verwenden Sie dies, wenn Einrichtung, Doctor oder Abläufe zum konfigurierten Zustand +eine leichte Ja/Nein-Auth-Prüfung benötigen, bevor das vollständige Kanal-Plugin geladen wird. Das Zielexport +sollte eine kleine Funktion sein, die nur den persistenten Zustand liest; leiten Sie sie nicht über die vollständige +Barrel-Datei der Kanallaufzeit. -`openclaw.channel.configuredState` folgt derselben Form für günstige rein env-basierte -Prüfungen des konfigurierten Zustands: +`openclaw.channel.configuredState` hat dieselbe Struktur für leichtgewichtige Prüfungen des +konfigurierten Zustands nur über Umgebungsvariablen: ```json { @@ -410,62 +417,65 @@ Prüfungen des konfigurierten Zustands: } ``` -Verwenden Sie es, wenn ein Kanal den konfigurierten Zustand aus env oder anderen kleinen -Nicht-Laufzeit-Eingaben beantworten kann. Wenn die Prüfung vollständige Konfigurationsauflösung oder die echte -Kanal-Laufzeit benötigt, behalten Sie diese Logik stattdessen im Hook `config.hasConfiguredState` +Verwenden Sie dies, wenn ein Kanal den konfigurierten Zustand aus Umgebungsvariablen oder anderen kleinen +Nicht-Laufzeit-Eingaben bestimmen kann. Wenn die Prüfung eine vollständige Konfigurationsauflösung oder die echte +Kanallaufzeit benötigt, belassen Sie diese Logik stattdessen im Hook `config.hasConfiguredState` des Plugins. -## Anforderungen an JSON Schema +## JSON-Schema-Anforderungen -- **Jedes Plugin muss ein JSON-Schema ausliefern**, auch wenn es keine Konfiguration akzeptiert. +- **Jedes Plugin muss ein JSON-Schema bereitstellen**, auch wenn es keine Konfiguration akzeptiert. - Ein leeres Schema ist zulässig (zum Beispiel `{ "type": "object", "additionalProperties": false }`). -- Schemas werden beim Lesen/Schreiben der Konfiguration validiert, nicht zur Laufzeit. +- Schemata werden beim Lesen/Schreiben der Konfiguration validiert, nicht zur Laufzeit. ## Validierungsverhalten -- Unbekannte `channels.*`-Schlüssel sind **Fehler**, es sei denn, die Kanal-ID wird durch +- Unbekannte Schlüssel unter `channels.*` sind **Fehler**, es sei denn, die Kanal-ID wird durch ein Plugin-Manifest deklariert. - `plugins.entries.`, `plugins.allow`, `plugins.deny` und `plugins.slots.*` - müssen sich auf **auffindbare** Plugin-IDs beziehen. Unbekannte IDs sind **Fehler**. + müssen auf **erkennbare** Plugin-IDs verweisen. Unbekannte IDs sind **Fehler**. - Wenn ein Plugin installiert ist, aber ein defektes oder fehlendes Manifest oder Schema hat, schlägt die Validierung fehl und Doctor meldet den Plugin-Fehler. - Wenn eine Plugin-Konfiguration vorhanden ist, das Plugin aber **deaktiviert** ist, bleibt die Konfiguration erhalten und - in Doctor + Protokollen wird eine **Warnung** angezeigt. + es wird in Doctor und in den Logs eine **Warnung** angezeigt. -Das vollständige Schema für `plugins.*` finden Sie unter [Configuration reference](/de/gateway/configuration). +Unter [Konfigurationsreferenz](/de/gateway/configuration) finden Sie das vollständige Schema für `plugins.*`. ## Hinweise - Das Manifest ist **für native OpenClaw-Plugins erforderlich**, einschließlich lokaler Dateisystem-Ladevorgänge. -- Die Laufzeit lädt das Plugin-Modul weiterhin separat; das Manifest dient nur der - Discovery + Validierung. -- Native Manifeste werden mit JSON5 geparst, daher sind Kommentare, nachgestellte Kommata und - unquotierte Schlüssel zulässig, solange der endgültige Wert weiterhin ein Objekt ist. +- Die Laufzeit lädt das Plugin-Modul weiterhin separat; das Manifest dient nur zur + Erkennung und Validierung. +- Native Manifeste werden mit JSON5 geparst, daher sind Kommentare, nachgestellte Kommas und + nicht in Anführungszeichen gesetzte Schlüssel zulässig, solange der endgültige Wert weiterhin ein Objekt ist. - Nur dokumentierte Manifestfelder werden vom Manifest-Loader gelesen. Vermeiden Sie es, hier benutzerdefinierte Schlüssel auf oberster Ebene hinzuzufügen. -- `providerAuthEnvVars` ist der günstige Metadatenpfad für Auth-Sondierungen, Env-Marker- - Validierung und ähnliche Anbieter-Auth-Oberflächen, die die Plugin- - Laufzeit nicht starten sollten, nur um Env-Namen zu prüfen. -- `channelEnvVars` ist der günstige Metadatenpfad für Shell-Env-Fallbacks, Einrichtungs- - Eingabeaufforderungen und ähnliche Kanaloberflächen, die die Plugin-Laufzeit nicht starten sollten, - nur um Env-Namen zu prüfen. -- `providerAuthChoices` ist der günstige Metadatenpfad für Auth-Auswahl-Picker, - Auflösung von `--auth-choice`, Zuordnung bevorzugter Anbieter und einfache Onboarding- - Registrierung von CLI-Flags, bevor die Anbieter-Laufzeit geladen wird. Für Laufzeit-Wizard- - Metadaten, die Anbieter-Code benötigen, siehe - [Provider runtime hooks](/de/plugins/architecture#provider-runtime-hooks). +- `providerAuthEnvVars` ist der leichtgewichtige Metadatenpfad für Auth-Prüfungen, Validierung von + Umgebungsvariablen-Markern und ähnliche Oberflächen für Provider-Auth, die die Plugin- + Laufzeit nicht nur zum Prüfen von Umgebungsvariablennamen starten sollten. +- `providerAuthAliases` erlaubt es Provider-Varianten, die Auth- + Umgebungsvariablen, Auth-Profile, konfigurationsgestützte Auth und die Onboarding-Auswahl für API-Schlüssel + eines anderen Providers wiederzuverwenden, ohne diese Beziehung im Core fest zu codieren. +- `channelEnvVars` ist der leichtgewichtige Metadatenpfad für Shell-Umgebungsvariablen-Fallbacks, Einrichtungs- + Prompts und ähnliche Kanaloberflächen, die die Plugin-Laufzeit nicht + nur zum Prüfen von Umgebungsvariablennamen starten sollten. +- `providerAuthChoices` ist der leichtgewichtige Metadatenpfad für Auswahlfelder zu Auth-Auswahlen, + die Auflösung von `--auth-choice`, die Zuordnung bevorzugter Provider und die einfache Registrierung von + CLI-Flags für Onboarding, bevor die Provider-Laufzeit geladen wird. Für Metadaten des Laufzeitassistenten, + die Provider-Code erfordern, siehe + [Provider-Laufzeit-Hooks](/de/plugins/architecture#provider-runtime-hooks). - Exklusive Plugin-Arten werden über `plugins.slots.*` ausgewählt. - - `kind: "memory"` wird von `plugins.slots.memory` ausgewählt. - - `kind: "context-engine"` wird von `plugins.slots.contextEngine` + - `kind: "memory"` wird durch `plugins.slots.memory` ausgewählt. + - `kind: "context-engine"` wird durch `plugins.slots.contextEngine` ausgewählt (Standard: integriertes `legacy`). - `channels`, `providers`, `cliBackends` und `skills` können weggelassen werden, wenn ein Plugin sie nicht benötigt. -- Wenn Ihr Plugin von nativen Modulen abhängt, dokumentieren Sie die Build-Schritte und alle - Anforderungen an die Paketmanager-Zulassungsliste (zum Beispiel pnpm `allow-build-scripts` +- Wenn Ihr Plugin von nativen Modulen abhängt, dokumentieren Sie die Build-Schritte und etwaige + Anforderungen an die Package-Manager-Allowlist (zum Beispiel pnpm `allow-build-scripts` - `pnpm rebuild `). ## Verwandt -- [Building Plugins](/de/plugins/building-plugins) — Erste Schritte mit Plugins -- [Plugin Architecture](/de/plugins/architecture) — interne Architektur -- [SDK Overview](/de/plugins/sdk-overview) — Referenz zum Plugin SDK +- [Plugins erstellen](/de/plugins/building-plugins) — erste Schritte mit Plugins +- [Plugin-Architektur](/de/plugins/architecture) — interne Architektur +- [SDK-Überblick](/de/plugins/sdk-overview) — Referenz zum Plugin-SDK diff --git a/docs/de/plugins/sdk-migration.md b/docs/de/plugins/sdk-migration.md index 9380dc694..5e2975155 100644 --- a/docs/de/plugins/sdk-migration.md +++ b/docs/de/plugins/sdk-migration.md @@ -1,130 +1,129 @@ --- read_when: - - Die Warnung OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED wird angezeigt - - Die Warnung OPENCLAW_EXTENSION_API_DEPRECATED wird angezeigt - - Ein Plugin wird auf die moderne Plugin-Architektur aktualisiert - - Ein externes OpenClaw-Plugin wird verwaltet + - Sie sehen die Warnung `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` + - Sie sehen die Warnung `OPENCLAW_EXTENSION_API_DEPRECATED` + - Sie aktualisieren ein Plugin auf die moderne Plugin-Architektur + - Sie pflegen ein externes OpenClaw-Plugin sidebarTitle: Migrate to SDK -summary: Von der Legacy-Abwärtskompatibilitätsschicht zum modernen Plugin SDK migrieren -title: Migration des Plugin SDK +summary: Von der alten Abwärtskompatibilitätsschicht auf das moderne Plugin SDK migrieren +title: Plugin-SDK-Migration x-i18n: - generated_at: "2026-04-08T02:17:33Z" + generated_at: "2026-04-09T01:31:04Z" model: gpt-5.4 provider: openai - source_hash: 155a8b14bc345319c8516ebdb8a0ccdea2c5f7fa07dad343442996daee21ecad + source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07 source_path: plugins/sdk-migration.md workflow: 15 --- -# Migration des Plugin SDK +# Plugin-SDK-Migration OpenClaw ist von einer breiten Abwärtskompatibilitätsschicht zu einer modernen Plugin- -Architektur mit fokussierten, dokumentierten Imports übergegangen. Wenn dein Plugin vor -der neuen Architektur erstellt wurde, hilft dir diese Anleitung bei der Migration. +Architektur mit fokussierten, dokumentierten Imports übergegangen. Wenn Ihr Plugin vor +der neuen Architektur erstellt wurde, hilft Ihnen diese Anleitung bei der Migration. ## Was sich ändert Das alte Plugin-System stellte zwei weit offene Oberflächen bereit, über die Plugins -alles importieren konnten, was sie über einen einzigen Einstiegspunkt benötigten: +alles importieren konnten, was sie von einem einzigen Einstiegspunkt aus benötigten: - **`openclaw/plugin-sdk/compat`** — ein einzelner Import, der Dutzende von - Hilfsfunktionen re-exportierte. Er wurde eingeführt, damit ältere hookbasierte Plugins weiter funktionieren, - während die neue Plugin-Architektur aufgebaut wurde. + Hilfsfunktionen re-exportierte. Er wurde eingeführt, damit ältere hookbasierte Plugins weiter funktionierten, während die + neue Plugin-Architektur aufgebaut wurde. - **`openclaw/extension-api`** — eine Brücke, die Plugins direkten Zugriff auf hostseitige Hilfsfunktionen wie den eingebetteten Agent-Runner gab. Beide Oberflächen sind jetzt **veraltet**. Sie funktionieren zur Laufzeit weiterhin, aber neue Plugins dürfen sie nicht verwenden, und bestehende Plugins sollten migrieren, bevor die nächste -Major-Version sie entfernt. +Hauptversion sie entfernt. - Die Abwärtskompatibilitätsschicht wird in einer zukünftigen Major-Version entfernt. - Plugins, die weiterhin von diesen Oberflächen importieren, werden dann nicht mehr funktionieren. + Die Abwärtskompatibilitätsschicht wird in einer zukünftigen Hauptversion entfernt. + Plugins, die weiterhin aus diesen Oberflächen importieren, werden dann nicht mehr funktionieren. ## Warum sich das geändert hat Der alte Ansatz verursachte Probleme: -- **Langsamer Start** — der Import einer Hilfsfunktion lud Dutzende nicht zusammenhängender Module -- **Zirkuläre Abhängigkeiten** — breite Re-Exports machten es einfach, Importzyklen zu erzeugen +- **Langsamer Start** — das Importieren einer Hilfsfunktion lud Dutzende nicht zusammenhängender Module +- **Zirkuläre Abhängigkeiten** — breite Re-Exports machten es leicht, Importzyklen zu erzeugen - **Unklare API-Oberfläche** — es gab keine Möglichkeit zu erkennen, welche Exporte stabil und welche intern waren Das moderne Plugin SDK behebt das: Jeder Importpfad (`openclaw/plugin-sdk/\`) ist ein kleines, in sich geschlossenes Modul mit einem klaren Zweck und dokumentiertem Vertrag. -Legacy-Provider-Convenience-Seams für gebündelte Kanäle sind ebenfalls verschwunden. Imports +Alte Convenience-Seams für Provider in gebündelten Kanälen entfallen ebenfalls. Imports wie `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -kanalmarkierte Helper-Seams und -`openclaw/plugin-sdk/telegram-core` waren private Monorepo-Abkürzungen, keine -stabilen Plugin-Verträge. Verwende stattdessen schmale generische SDK-Subpaths. Innerhalb des -gebündelten Plugin-Workspace sollten provider-eigene Hilfsfunktionen im jeweiligen -`api.ts` oder `runtime-api.ts` des Plugins bleiben. +kanalmarkenspezifische Helper-Seams und +`openclaw/plugin-sdk/telegram-core` waren private Mono-Repo-Abkürzungen, keine +stabilen Plugin-Verträge. Verwenden Sie stattdessen schmale generische SDK-Unterpfade. Innerhalb des +gebündelten Plugin-Workspaces sollten provider-eigene Hilfsfunktionen im eigenen +`api.ts` oder `runtime-api.ts` dieses Plugins bleiben. Aktuelle Beispiele für gebündelte Provider: -- Anthropic behält Claude-spezifische Stream-Hilfsfunktionen in seinem eigenen `api.ts` / - `contract-api.ts`-Seam -- OpenAI behält Provider-Builder, Default-Model-Hilfsfunktionen und Realtime-Provider- - Builder in seinem eigenen `api.ts` -- OpenRouter behält Provider-Builder sowie Onboarding-/Konfigurationshilfsfunktionen in seinem eigenen +- Anthropic hält Claude-spezifische Stream-Hilfsfunktionen in seiner eigenen `api.ts` / + `contract-api.ts`-Naht +- OpenAI hält Provider-Builder, Standardmodell-Hilfsfunktionen und Realtime-Provider- + Builder in seiner eigenen `api.ts` +- OpenRouter hält Provider-Builder und Onboarding-/Konfigurationshilfsfunktionen in seiner eigenen `api.ts` -## So migrierst du +## Migration - - Freigabefähige Kanal-Plugins stellen natives Freigabeverhalten jetzt über - `approvalCapability.nativeRuntime` plus das gemeinsame Runtime-Context-Registry bereit. + + Approval-fähige Kanal-Plugins stellen natives Approval-Verhalten jetzt über + `approvalCapability.nativeRuntime` plus die gemeinsame Runtime-Context-Registry bereit. Wichtige Änderungen: - - Ersetze `approvalCapability.handler.loadRuntime(...)` durch + - Ersetzen Sie `approvalCapability.handler.loadRuntime(...)` durch `approvalCapability.nativeRuntime` - - Verschiebe Freigabe-spezifische Auth/Delivery von der Legacy-Verkabelung - `plugin.auth` / `plugin.approvals` auf `approvalCapability` + - Verschieben Sie Approval-spezifische Auth-/Delivery-Logik von der alten Verkabelung `plugin.auth` / + `plugin.approvals` auf `approvalCapability` - `ChannelPlugin.approvals` wurde aus dem öffentlichen Vertrag für Kanal-Plugins - entfernt; verschiebe Delivery-/native-/render-Felder auf `approvalCapability` - - `plugin.auth` bleibt nur für Kanal-Login-/Logout-Abläufe bestehen; Freigabe-Auth- - Hooks dort werden vom Core nicht mehr gelesen - - Registriere kanal-eigene Runtime-Objekte wie Clients, Tokens oder Bolt- + entfernt; verschieben Sie Delivery-/Native-/Render-Felder auf `approvalCapability` + - `plugin.auth` bleibt nur für Login-/Logout-Abläufe von Kanälen; Approval- + Auth-Hooks dort werden vom Core nicht mehr gelesen + - Registrieren Sie kanal-eigene Runtime-Objekte wie Clients, Tokens oder Bolt- Apps über `openclaw/plugin-sdk/channel-runtime-context` - - Sende keine plugin-eigenen Reroute-Hinweise aus nativen Freigabe-Handlern; - der Core übernimmt jetzt Routed-Elsewhere-Hinweise aus tatsächlichen Delivery-Ergebnissen - - Wenn `channelRuntime` an `createChannelManager(...)` übergeben wird, stelle eine - echte `createPluginRuntime().channel`-Oberfläche bereit. Partielle Stubs werden abgelehnt. + - Senden Sie aus nativen Approval-Handlern keine plugin-eigenen Umleitungs-Hinweise; + Core verwaltet Hinweise „anderswo zugestellt“ jetzt anhand der tatsächlichen Delivery-Ergebnisse + - Wenn Sie `channelRuntime` an `createChannelManager(...)` übergeben, stellen Sie eine + echte `createPluginRuntime().channel`-Oberfläche bereit. Teilweise Stubs werden abgelehnt. - Siehe `/plugins/sdk-channel-plugins` für das aktuelle Layout der - Freigabe-Capability. + Siehe `/plugins/sdk-channel-plugins` für das aktuelle Layout der Approval-Capabilities. - Wenn dein Plugin `openclaw/plugin-sdk/windows-spawn` verwendet, - schlagen nicht aufgelöste Windows-Wrapper vom Typ `.cmd`/`.bat` jetzt fail-closed fehl, sofern nicht - ausdrücklich `allowShellFallback: true` übergeben wird. + Wenn Ihr Plugin `openclaw/plugin-sdk/windows-spawn` verwendet, + schlagen nicht aufgelöste Windows-Wrapper vom Typ `.cmd`/`.bat` jetzt standardmäßig fehl, es sei denn, Sie übergeben explizit + `allowShellFallback: true`. ```typescript - // Before + // Vorher const program = applyWindowsSpawnProgramPolicy({ candidate }); - // After + // Nachher const program = applyWindowsSpawnProgramPolicy({ candidate, - // Only set this for trusted compatibility callers that intentionally - // accept shell-mediated fallback. + // Nur für vertrauenswürdige Kompatibilitätsaufrufer setzen, die + // bewusst einen Shell-vermittelten Fallback akzeptieren. allowShellFallback: true, }); ``` - Wenn dein Aufrufer nicht absichtlich auf Shell-Fallback angewiesen ist, setze - `allowShellFallback` nicht und behandle stattdessen den ausgelösten Fehler. + Wenn Ihr Aufrufer nicht bewusst auf einen Shell-Fallback angewiesen ist, setzen Sie + `allowShellFallback` nicht und behandeln Sie stattdessen den ausgelösten Fehler. - Durchsuche dein Plugin nach Imports von einer der beiden veralteten Oberflächen: + Durchsuchen Sie Ihr Plugin nach Imports aus einer der beiden veralteten Oberflächen: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -134,35 +133,35 @@ Aktuelle Beispiele für gebündelte Provider: - Jeder Export der alten Oberfläche entspricht einem bestimmten modernen Importpfad: + Jeder Export aus der alten Oberfläche entspricht einem bestimmten modernen Importpfad: ```typescript - // Before (deprecated backwards-compatibility layer) + // Vorher (veraltete Abwärtskompatibilitätsschicht) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // After (modern focused imports) + // Nachher (moderne fokussierte Imports) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Für hostseitige Hilfsfunktionen verwende die injizierte Plugin-Runtime, statt direkt + Verwenden Sie für hostseitige Hilfsfunktionen die injizierte Plugin-Runtime, anstatt direkt zu importieren: ```typescript - // Before (deprecated extension-api bridge) + // Vorher (veraltete extension-api-Brücke) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // After (injected runtime) + // Nachher (injizierte Runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Dasselbe Muster gilt für andere Legacy-Brücken-Hilfsfunktionen: + Dasselbe Muster gilt für andere alte Bridge-Hilfsfunktionen: | Alter Import | Modernes Äquivalent | | --- | --- | @@ -172,11 +171,11 @@ Aktuelle Beispiele für gebündelte Provider: | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | Sitzungsspeicher-Hilfsfunktionen | `api.runtime.agent.session.*` | + | Hilfsfunktionen für den Sitzungsspeicher | `api.runtime.agent.session.*` | - + ```bash pnpm build pnpm test -- my-plugin/ @@ -184,174 +183,177 @@ Aktuelle Beispiele für gebündelte Provider: -## Referenz für Importpfade +## Referenz der Importpfade | Importpfad | Zweck | Wichtige Exporte | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Kanonische Plugin-Einstiegshilfe | `definePluginEntry` | - | `plugin-sdk/core` | Legacy-Überdach-Re-Export für Kanal-Entry-Definitionen/Builder | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Kanonische Hilfsfunktion für Plugin-Einstiegspunkte | `definePluginEntry` | + | `plugin-sdk/core` | Alter Sammel-Re-Export für Definitionen/Builder von Kanaleinstiegspunkten | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Export des Root-Konfigurationsschemas | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Einstiegshilfe für Single-Provider | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Fokussierte Kanal-Entry-Definitionen und Builder | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Gemeinsame Hilfsfunktionen für den Setup-Wizard | Allowlist-Prompts, Builder für Setup-Status | - | `plugin-sdk/setup-runtime` | Runtime-Hilfsfunktionen zur Setup-Zeit | Importsichere Setup-Patch-Adapter, Hilfsfunktionen für Lookup-Notizen, `promptResolvedAllowFrom`, `splitSetupEntries`, delegierte Setup-Proxys | + | `plugin-sdk/provider-entry` | Hilfsfunktion für Single-Provider-Einstiegspunkte | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Fokussierte Definitionen und Builder für Kanaleinstiegspunkte | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Gemeinsame Hilfsfunktionen für Setup-Assistenten | Allowlist-Prompts, Builder für Setup-Status | + | `plugin-sdk/setup-runtime` | Laufzeit-Hilfsfunktionen zur Setup-Zeit | Importsichere Setup-Patch-Adapter, Lookup-Note-Hilfsfunktionen, `promptResolvedAllowFrom`, `splitSetupEntries`, delegierte Setup-Proxys | | `plugin-sdk/setup-adapter-runtime` | Hilfsfunktionen für Setup-Adapter | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Hilfsfunktionen für Setup-Tooling | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Hilfsfunktionen für mehrere Accounts | Hilfsfunktionen für Account-Liste/Konfiguration/Aktions-Gates | - | `plugin-sdk/account-id` | Hilfsfunktionen für Account-IDs | `DEFAULT_ACCOUNT_ID`, Normalisierung von Account-IDs | - | `plugin-sdk/account-resolution` | Hilfsfunktionen für Account-Lookups | Hilfsfunktionen für Account-Lookup + Default-Fallback | - | `plugin-sdk/account-helpers` | Schmale Account-Hilfsfunktionen | Hilfsfunktionen für Account-Liste/Account-Aktionen | - | `plugin-sdk/channel-setup` | Adapter für den Setup-Wizard | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Primitive für DM-Pairing | `createChannelPairingController` | + | `plugin-sdk/setup-tools` | Hilfsfunktionen für Setup-Tools | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Hilfsfunktionen für Mehrkonten | Hilfsfunktionen für Kontoliste/Konfiguration/Action-Gates | + | `plugin-sdk/account-id` | Hilfsfunktionen für Konto-IDs | `DEFAULT_ACCOUNT_ID`, Normalisierung von Konto-IDs | + | `plugin-sdk/account-resolution` | Hilfsfunktionen für Konto-Lookups | Hilfsfunktionen für Konto-Lookup + Standard-Fallback | + | `plugin-sdk/account-helpers` | Schmale Kontohilfsfunktionen | Hilfsfunktionen für Kontoliste/Kontoaktionen | + | `plugin-sdk/channel-setup` | Adapter für Setup-Assistenten | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard` sowie `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/channel-pairing` | Grundbausteine für DM-Pairing | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | Verkabelung für Antwortpräfix + Tippen | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Fabriken für Konfigurationsadapter | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Builder für Konfigurationsschemas | Typen für Kanal-Konfigurationsschemas | + | `plugin-sdk/channel-config-schema` | Builder für Konfigurationsschemata | Typen für Kanal-Konfigurationsschemata | | `plugin-sdk/telegram-command-config` | Hilfsfunktionen für Telegram-Befehlskonfiguration | Normalisierung von Befehlsnamen, Kürzen von Beschreibungen, Validierung von Duplikaten/Konflikten | | `plugin-sdk/channel-policy` | Auflösung von Gruppen-/DM-Richtlinien | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Statusverfolgung für Accounts | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Hilfsfunktionen für eingehende Umschläge | Gemeinsame Hilfsfunktionen für Route- + Umschlag-Builder | - | `plugin-sdk/inbound-reply-dispatch` | Hilfsfunktionen für eingehende Antworten | Gemeinsame Hilfsfunktionen für record-and-dispatch | - | `plugin-sdk/messaging-targets` | Parsing von Messaging-Zielen | Hilfsfunktionen für Ziel-Parsing/-Matching | + | `plugin-sdk/channel-lifecycle` | Verfolgung des Kontostatus | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Hilfsfunktionen für eingehende Umschläge | Gemeinsame Hilfsfunktionen für Routen- und Umschlag-Builder | + | `plugin-sdk/inbound-reply-dispatch` | Hilfsfunktionen für eingehende Antworten | Gemeinsame Hilfsfunktionen zum Aufzeichnen und Verteilen | + | `plugin-sdk/messaging-targets` | Parsen von Nachrichtenzielen | Hilfsfunktionen zum Parsen/Abgleichen von Zielen | | `plugin-sdk/outbound-media` | Hilfsfunktionen für ausgehende Medien | Gemeinsames Laden ausgehender Medien | - | `plugin-sdk/outbound-runtime` | Hilfsfunktionen für ausgehende Runtime | Hilfsfunktionen für ausgehende Identität/Send-Delegates | - | `plugin-sdk/thread-bindings-runtime` | Hilfsfunktionen für Thread-Bindings | Hilfsfunktionen für Thread-Binding-Lebenszyklus und -Adapter | - | `plugin-sdk/agent-media-payload` | Legacy-Hilfsfunktionen für Medien-Nutzlasten | Builder für Agent-Medien-Nutzlasten für Legacy-Feldlayouts | - | `plugin-sdk/channel-runtime` | Veralteter Kompatibilitäts-Shim | Nur Legacy-Hilfsfunktionen für Kanal-Runtime | + | `plugin-sdk/outbound-runtime` | Laufzeit-Hilfsfunktionen für ausgehende Vorgänge | Hilfsfunktionen für ausgehende Identität/Sende-Delegierung | + | `plugin-sdk/thread-bindings-runtime` | Hilfsfunktionen für Thread-Bindings | Hilfsfunktionen für Lifecycle und Adapter von Thread-Bindings | + | `plugin-sdk/agent-media-payload` | Alte Hilfsfunktionen für Medien-Payloads | Builder für Agent-Medien-Payloads für alte Feldlayouts | + | `plugin-sdk/channel-runtime` | Veraltetes Kompatibilitäts-Shim | Nur alte Kanal-Laufzeitdienstprogramme | | `plugin-sdk/channel-send-result` | Typen für Sendeergebnisse | Typen für Antwortergebnisse | | `plugin-sdk/runtime-store` | Persistenter Plugin-Speicher | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Breite Runtime-Hilfsfunktionen | Hilfsfunktionen für Runtime/Logging/Backup/Plugin-Install | - | `plugin-sdk/runtime-env` | Schmale Hilfsfunktionen für Runtime-Umgebung | Logger/Runtime-Umgebung, Timeout-, Retry- und Backoff-Hilfsfunktionen | - | `plugin-sdk/plugin-runtime` | Gemeinsame Plugin-Runtime-Hilfsfunktionen | Hilfsfunktionen für Plugin-Befehle/Hooks/HTTP/interaktive Abläufe | + | `plugin-sdk/runtime` | Breite Laufzeit-Hilfsfunktionen | Hilfsfunktionen für Runtime/Logging/Backup/Plugin-Installation | + | `plugin-sdk/runtime-env` | Schmale Hilfsfunktionen für Laufzeitumgebungen | Logger-/Laufzeitumgebungs-, Timeout-, Retry- und Backoff-Hilfsfunktionen | + | `plugin-sdk/plugin-runtime` | Gemeinsame Plugin-Laufzeit-Hilfsfunktionen | Hilfsfunktionen für Plugin-Befehle/Hooks/HTTP/interaktive Abläufe | | `plugin-sdk/hook-runtime` | Hilfsfunktionen für Hook-Pipelines | Gemeinsame Hilfsfunktionen für Webhook-/interne Hook-Pipelines | | `plugin-sdk/lazy-runtime` | Hilfsfunktionen für Lazy Runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Hilfsfunktionen für Prozesse | Gemeinsame Exec-Hilfsfunktionen | - | `plugin-sdk/cli-runtime` | Hilfsfunktionen für CLI-Runtime | Hilfsfunktionen für Befehlsformatierung, Waits, Versionen | - | `plugin-sdk/gateway-runtime` | Gateway-Hilfsfunktionen | Hilfsfunktionen für Gateway-Client und Channel-Status-Patches | - | `plugin-sdk/config-runtime` | Konfigurationshilfen | Hilfsfunktionen zum Laden/Schreiben von Konfiguration | + | `plugin-sdk/cli-runtime` | Hilfsfunktionen für CLI-Laufzeiten | Befehlsformatierung, Wartevorgänge, Versionshilfsfunktionen | + | `plugin-sdk/gateway-runtime` | Hilfsfunktionen für Gateways | Gateway-Client- und Patch-Hilfsfunktionen für Kanalstatus | + | `plugin-sdk/config-runtime` | Hilfsfunktionen für Konfigurationen | Hilfsfunktionen zum Laden/Schreiben von Konfigurationen | | `plugin-sdk/telegram-command-config` | Hilfsfunktionen für Telegram-Befehle | Fallback-stabile Hilfsfunktionen zur Telegram-Befehlsvalidierung, wenn die gebündelte Telegram-Vertragsoberfläche nicht verfügbar ist | - | `plugin-sdk/approval-runtime` | Hilfsfunktionen für Freigabe-Prompts | Nutzlasten für Exec-/Plugin-Freigaben, Hilfsfunktionen für Freigabe-Capability/-Profil, natives Freigabe-Routing/-Runtime | - | `plugin-sdk/approval-auth-runtime` | Hilfsfunktionen für Freigabe-Auth | Auflösung von Approvern, Auth für Aktionen im selben Chat | - | `plugin-sdk/approval-client-runtime` | Hilfsfunktionen für Freigabe-Clients | Hilfsfunktionen für natives Exec-Freigabeprofil/-Filter | - | `plugin-sdk/approval-delivery-runtime` | Hilfsfunktionen für Freigabe-Delivery | Adapter für native Freigabe-Capability/-Delivery | - | `plugin-sdk/approval-gateway-runtime` | Hilfsfunktionen für Freigabe-Gateway | Gemeinsame Hilfsfunktion für die Auflösung von Freigabe-Gateways | - | `plugin-sdk/approval-handler-adapter-runtime` | Hilfsfunktionen für Freigabe-Adapter | Leichtgewichtige Hilfsfunktionen zum Laden nativer Freigabe-Adapter für heiße Kanal-Entrypoints | - | `plugin-sdk/approval-handler-runtime` | Hilfsfunktionen für Freigabe-Handler | Breitere Runtime-Hilfsfunktionen für Freigabe-Handler; bevorzuge die schmaleren Adapter-/Gateway-Seams, wenn sie ausreichen | - | `plugin-sdk/approval-native-runtime` | Hilfsfunktionen für Freigabe-Ziele | Hilfsfunktionen für native Bindings von Freigabe-Zielen/Accounts | - | `plugin-sdk/approval-reply-runtime` | Hilfsfunktionen für Freigabe-Antworten | Hilfsfunktionen für Antwortnutzlasten bei Exec-/Plugin-Freigaben | + | `plugin-sdk/approval-runtime` | Hilfsfunktionen für Approval-Prompts | Payloads für Exec-/Plugin-Approval, Hilfsfunktionen für Approval-Capabilities/-Profile, native Approval-Routing-/Runtime-Hilfsfunktionen | + | `plugin-sdk/approval-auth-runtime` | Hilfsfunktionen für Approval-Authentifizierung | Approver-Auflösung, Authentifizierung von Aktionen im selben Chat | + | `plugin-sdk/approval-client-runtime` | Hilfsfunktionen für Approval-Clients | Hilfsfunktionen für native Exec-Approval-Profile/-Filter | + | `plugin-sdk/approval-delivery-runtime` | Hilfsfunktionen für Approval-Delivery | Adapter für native Approval-Capabilities/-Delivery | + | `plugin-sdk/approval-gateway-runtime` | Hilfsfunktionen für Approval-Gateways | Gemeinsame Hilfsfunktion für die Auflösung von Approval-Gateways | + | `plugin-sdk/approval-handler-adapter-runtime` | Hilfsfunktionen für Approval-Adapter | Leichtgewichtige Hilfsfunktionen zum Laden nativer Approval-Adapter für heiße Kanaleinstiegspunkte | + | `plugin-sdk/approval-handler-runtime` | Hilfsfunktionen für Approval-Handler | Breitere Laufzeit-Hilfsfunktionen für Approval-Handler; bevorzugen Sie die schmaleren Adapter-/Gateway-Seams, wenn diese ausreichen | + | `plugin-sdk/approval-native-runtime` | Hilfsfunktionen für Approval-Ziele | Hilfsfunktionen für native Approval-Ziel-/Kontobindungen | + | `plugin-sdk/approval-reply-runtime` | Hilfsfunktionen für Approval-Antworten | Hilfsfunktionen für Antwort-Payloads bei Exec-/Plugin-Approval | | `plugin-sdk/channel-runtime-context` | Hilfsfunktionen für Kanal-Runtime-Context | Generische Hilfsfunktionen zum Registrieren/Abrufen/Beobachten von Kanal-Runtime-Contexts | - | `plugin-sdk/security-runtime` | Hilfsfunktionen für Sicherheit | Gemeinsame Hilfsfunktionen für Vertrauen, DM-Gating, externe Inhalte und Secret-Erfassung | - | `plugin-sdk/ssrf-policy` | Hilfsfunktionen für SSRF-Richtlinien | Hilfsfunktionen für Host-Allowlist und Private-Network-Richtlinien | - | `plugin-sdk/ssrf-runtime` | Hilfsfunktionen für SSRF-Runtime | Pinned-Dispatcher, Guarded Fetch, SSRF-Richtlinienhilfen | + | `plugin-sdk/security-runtime` | Hilfsfunktionen für Sicherheit | Gemeinsame Hilfsfunktionen für Trust, DM-Gating, externe Inhalte und Secret-Erfassung | + | `plugin-sdk/ssrf-policy` | Hilfsfunktionen für SSRF-Richtlinien | Hilfsfunktionen für Host-Allowlist- und Private-Network-Richtlinien | + | `plugin-sdk/ssrf-runtime` | Laufzeit-Hilfsfunktionen für SSRF | Hilfsfunktionen für Pinned Dispatcher, Guarded Fetch und SSRF-Richtlinien | | `plugin-sdk/collection-runtime` | Hilfsfunktionen für begrenzte Caches | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Hilfsfunktionen für Diagnostic-Gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/diagnostic-runtime` | Hilfsfunktionen für Diagnose-Gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | | `plugin-sdk/error-runtime` | Hilfsfunktionen für Fehlerformatierung | `formatUncaughtError`, `isApprovalNotFoundError`, Hilfsfunktionen für Fehlergraphen | | `plugin-sdk/fetch-runtime` | Hilfsfunktionen für gewrapptes Fetch/Proxy | `resolveFetch`, Proxy-Hilfsfunktionen | | `plugin-sdk/host-runtime` | Hilfsfunktionen für Host-Normalisierung | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Retry-Hilfsfunktionen | `RetryConfig`, `retryAsync`, Richtlinien-Runner | - | `plugin-sdk/allow-from` | Formatierung von Zulassungslisten | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Mapping von Eingaben für Zulassungslisten | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Hilfsfunktionen für Befehls-Gating und Befehlsoberflächen | `resolveControlCommandGate`, Hilfsfunktionen für Sender-Autorisierung, Hilfsfunktionen für Befehlsregistry | - | `plugin-sdk/secret-input` | Parsing von Secret-Eingaben | Hilfsfunktionen für Secret-Eingaben | - | `plugin-sdk/webhook-ingress` | Hilfsfunktionen für Webhook-Anfragen | Hilfsfunktionen für Webhook-Ziele | - | `plugin-sdk/webhook-request-guards` | Hilfsfunktionen für Guarding von Webhook-Bodies | Hilfsfunktionen zum Lesen/Begrenzen von Request-Bodies | - | `plugin-sdk/reply-runtime` | Gemeinsame Runtime für Antworten | Inbound-Dispatch, Heartbeat, Antwortplanung, Chunking | - | `plugin-sdk/reply-dispatch-runtime` | Schmale Hilfsfunktionen für Reply-Dispatch | Hilfsfunktionen für Finalize + Provider-Dispatch | + | `plugin-sdk/retry-runtime` | Hilfsfunktionen für Wiederholungen | `RetryConfig`, `retryAsync`, Richtlinien-Runner | + | `plugin-sdk/allow-from` | Formatierung von Allowlists | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Mapping von Allowlist-Eingaben | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Command-Gating- und Command-Surface-Hilfsfunktionen | `resolveControlCommandGate`, Hilfsfunktionen für Senderautorisierung, Hilfsfunktionen für Befehlsregistrierung | + | `plugin-sdk/command-status` | Renderer für Befehlsstatus/-hilfe | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Parsen geheimer Eingaben | Hilfsfunktionen für geheime Eingaben | + | `plugin-sdk/webhook-ingress` | Hilfsfunktionen für Webhook-Anfragen | Dienstprogramme für Webhook-Ziele | + | `plugin-sdk/webhook-request-guards` | Hilfsfunktionen für Webhook-Body-Guards | Hilfsfunktionen zum Lesen/Begrenzen von Request-Bodys | + | `plugin-sdk/reply-runtime` | Gemeinsame Antwort-Laufzeit | Eingehende Verteilung, Heartbeat, Antwortplanung, Chunking | + | `plugin-sdk/reply-dispatch-runtime` | Schmale Hilfsfunktionen für Antwortverteilung | Hilfsfunktionen für Finalisierung + Provider-Verteilung | | `plugin-sdk/reply-history` | Hilfsfunktionen für Antwortverlauf | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | Planung von Antwortreferenzen | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Hilfsfunktionen für Antwort-Chunks | Hilfsfunktionen für Text-/Markdown-Chunking | | `plugin-sdk/session-store-runtime` | Hilfsfunktionen für Sitzungsspeicher | Hilfsfunktionen für Speicherpfade + updated-at | - | `plugin-sdk/state-paths` | Hilfsfunktionen für Statuspfade | Hilfsfunktionen für Status- und OAuth-Verzeichnisse | + | `plugin-sdk/state-paths` | Hilfsfunktionen für Zustandspfade | Hilfsfunktionen für Zustands- und OAuth-Verzeichnisse | | `plugin-sdk/routing` | Hilfsfunktionen für Routing/Sitzungsschlüssel | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, Hilfsfunktionen zur Normalisierung von Sitzungsschlüsseln | - | `plugin-sdk/status-helpers` | Hilfsfunktionen für Kanalstatus | Builder für Kanal-/Account-Statuszusammenfassungen, Defaults für Runtime-Status, Hilfsfunktionen für Issue-Metadaten | + | `plugin-sdk/status-helpers` | Hilfsfunktionen für Kanalstatus | Builder für Zusammenfassungen von Kanal-/Kontostatus, Laufzeitzustandsstandards, Hilfsfunktionen für Issue-Metadaten | | `plugin-sdk/target-resolver-runtime` | Hilfsfunktionen für Zielauflösung | Gemeinsame Hilfsfunktionen für Zielauflösung | - | `plugin-sdk/string-normalization-runtime` | Hilfsfunktionen für String-Normalisierung | Hilfsfunktionen zur Slug-/String-Normalisierung | - | `plugin-sdk/request-url` | Hilfsfunktionen für Request-URLs | String-URLs aus request-artigen Eingaben extrahieren | - | `plugin-sdk/run-command` | Hilfsfunktionen für zeitgesteuerte Befehle | Zeitgesteuerter Befehls-Runner mit normalisiertem stdout/stderr | - | `plugin-sdk/param-readers` | Param-Reader | Gemeinsame Param-Reader für Tool/CLI | - | `plugin-sdk/tool-send` | Extraktion für Tool-Send | Kanonische Send-Zielfelder aus Tool-Argumenten extrahieren | - | `plugin-sdk/temp-path` | Hilfsfunktionen für temporäre Pfade | Gemeinsame Hilfsfunktionen für Temp-Download-Pfade | - | `plugin-sdk/logging-core` | Logging-Hilfsfunktionen | Subsystem-Logger und Hilfsfunktionen zur Redaction | - | `plugin-sdk/markdown-table-runtime` | Hilfsfunktionen für Markdown-Tabellen | Hilfsfunktionen für den Modus von Markdown-Tabellen | - | `plugin-sdk/reply-payload` | Typen für Nachrichtenantworten | Typen für Antwortnutzlasten | - | `plugin-sdk/provider-setup` | Kuratierte Hilfsfunktionen für das Setup lokaler/self-hosted Provider | Hilfsfunktionen für Discovery/Konfiguration self-hosted Provider | - | `plugin-sdk/self-hosted-provider-setup` | Fokussierte Hilfsfunktionen für OpenAI-kompatible self-hosted Provider-Setups | Dieselben Hilfsfunktionen für Discovery/Konfiguration self-hosted Provider | - | `plugin-sdk/provider-auth-runtime` | Laufzeit-Hilfsfunktionen für Provider-Auth | Hilfsfunktionen zur Laufzeitauflösung von API-Keys | - | `plugin-sdk/provider-auth-api-key` | Hilfsfunktionen für API-Key-Setups von Providern | Hilfsfunktionen für API-Key-Onboarding/Profilschreiben | + | `plugin-sdk/string-normalization-runtime` | Hilfsfunktionen für String-Normalisierung | Hilfsfunktionen für Slug-/String-Normalisierung | + | `plugin-sdk/request-url` | Hilfsfunktionen für Request-URLs | String-URLs aus requestähnlichen Eingaben extrahieren | + | `plugin-sdk/run-command` | Hilfsfunktionen für zeitgesteuerte Befehle | Runner für zeitgesteuerte Befehle mit normalisiertem stdout/stderr | + | `plugin-sdk/param-readers` | Param-Reader | Gemeinsame Param-Reader für Tools/CLI | + | `plugin-sdk/tool-payload` | Extraktion von Tool-Payloads | Normalisierte Payloads aus Tool-Ergebnisobjekten extrahieren | + | `plugin-sdk/tool-send` | Extraktion von Tool-Sendewerten | Kanonische Sendefelder aus Tool-Argumenten extrahieren | + | `plugin-sdk/temp-path` | Hilfsfunktionen für temporäre Pfade | Gemeinsame Hilfsfunktionen für temporäre Download-Pfade | + | `plugin-sdk/logging-core` | Logging-Hilfsfunktionen | Subsystem-Logger und Redaktionshilfsfunktionen | + | `plugin-sdk/markdown-table-runtime` | Hilfsfunktionen für Markdown-Tabellen | Hilfsfunktionen für Modi von Markdown-Tabellen | + | `plugin-sdk/reply-payload` | Nachrichtenantworttypen | Antwort-Payload-Typen | + | `plugin-sdk/provider-setup` | Kuratierte Hilfsfunktionen zum Setup lokaler/self-hosted Provider | Hilfsfunktionen für Discovery/Konfiguration self-hosted Provider | + | `plugin-sdk/self-hosted-provider-setup` | Fokussierte Hilfsfunktionen zum Setup OpenAI-kompatibler self-hosted Provider | Dieselben Hilfsfunktionen für Discovery/Konfiguration self-hosted Provider | + | `plugin-sdk/provider-auth-runtime` | Hilfsfunktionen für Provider-Runtime-Authentifizierung | Hilfsfunktionen zur Auflösung von API-Schlüsseln zur Laufzeit | + | `plugin-sdk/provider-auth-api-key` | Hilfsfunktionen zum Setup von Provider-API-Schlüsseln | Hilfsfunktionen für API-Key-Onboarding/Profile-Schreiben | | `plugin-sdk/provider-auth-result` | Hilfsfunktionen für Provider-Auth-Ergebnisse | Standard-Builder für OAuth-Auth-Ergebnisse | - | `plugin-sdk/provider-auth-login` | Hilfsfunktionen für interaktiven Provider-Login | Gemeinsame Hilfsfunktionen für interaktiven Login | - | `plugin-sdk/provider-env-vars` | Hilfsfunktionen für Provider-Umgebungsvariablen | Hilfsfunktionen für Lookup von Umgebungsvariablen für Provider-Auth | - | `plugin-sdk/provider-model-shared` | Gemeinsame Hilfsfunktionen für Provider-Modelle/Replay | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Builder für Replay-Richtlinien, Provider-Endpunkt-Hilfen und Hilfsfunktionen zur Normalisierung von Modell-IDs | + | `plugin-sdk/provider-auth-login` | Interaktive Hilfsfunktionen für Provider-Login | Gemeinsame Hilfsfunktionen für interaktives Login | + | `plugin-sdk/provider-env-vars` | Hilfsfunktionen für Provider-Umgebungsvariablen | Hilfsfunktionen zum Lookup von Provider-Auth-Umgebungsvariablen | + | `plugin-sdk/provider-model-shared` | Gemeinsame Hilfsfunktionen für Provider-Modelle/-Replay | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Builder für Replay-Richtlinien, Hilfsfunktionen für Provider-Endpunkte und Hilfsfunktionen zur Modell-ID-Normalisierung | | `plugin-sdk/provider-catalog-shared` | Gemeinsame Hilfsfunktionen für Provider-Kataloge | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-onboard` | Patches für Provider-Onboarding | Hilfsfunktionen für Onboarding-Konfiguration | - | `plugin-sdk/provider-http` | Hilfsfunktionen für Provider-HTTP | Generische Hilfsfunktionen für Provider-HTTP/Endpunkt-Capabilities | + | `plugin-sdk/provider-http` | Hilfsfunktionen für Provider-HTTP | Generische Hilfsfunktionen für Provider-HTTP/Endpoint-Capabilities | | `plugin-sdk/provider-web-fetch` | Hilfsfunktionen für Provider-Web-Fetch | Hilfsfunktionen für Registrierung/Cache von Web-Fetch-Providern | - | `plugin-sdk/provider-web-search-contract` | Hilfsfunktionen für Verträge der Provider-Websuche | Schmale Hilfsfunktionen für Verträge von Websuche-Konfiguration/Zugangsdaten wie `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` und scoped Setter/Getter für Zugangsdaten | - | `plugin-sdk/provider-web-search` | Hilfsfunktionen für Provider-Websuche | Hilfsfunktionen für Registrierung/Cache/Runtime von Websuche-Providern | - | `plugin-sdk/provider-tools` | Hilfsfunktionen für Provider-Tool-/Schema-Kompatibilität | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini-Schema-Bereinigung + Diagnostics und xAI-Kompatibilitätshilfen wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-web-search-config-contract` | Hilfsfunktionen für Provider-Websearch-Konfiguration | Schmale Hilfsfunktionen für Websearch-Konfiguration/Anmeldedaten für Provider, die keine Plugin-Aktivierungsverkabelung benötigen | + | `plugin-sdk/provider-web-search-contract` | Hilfsfunktionen für Provider-Websearch-Verträge | Schmale Hilfsfunktionen für Verträge zu Websearch-Konfiguration/Anmeldedaten wie `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` und bereichsbezogene Setter/Getter für Anmeldedaten | + | `plugin-sdk/provider-web-search` | Hilfsfunktionen für Provider-Websearch | Hilfsfunktionen für Registrierung/Cache/Laufzeit von Websearch-Providern | + | `plugin-sdk/provider-tools` | Hilfsfunktionen für Provider-Tool-/Schema-Kompatibilität | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini-Schema-Bereinigung + Diagnosen sowie xAI-Kompatibilitätshilfen wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | Hilfsfunktionen für Provider-Nutzung | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` und andere Hilfsfunktionen für Provider-Nutzung | - | `plugin-sdk/provider-stream` | Hilfsfunktionen für Wrapper von Provider-Streams | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Typen für Stream-Wrapper und gemeinsame Wrapper-Hilfen für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-stream` | Hilfsfunktionen für Provider-Stream-Wrapper | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Typen für Stream-Wrapper und gemeinsame Wrapper-Hilfsfunktionen für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | | `plugin-sdk/keyed-async-queue` | Geordnete Async-Queue | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Gemeinsame Medienhilfsfunktionen | Hilfsfunktionen für Abrufen/Transformieren/Speichern von Medien plus Builder für Medien-Nutzlasten | - | `plugin-sdk/media-generation-runtime` | Gemeinsame Hilfsfunktionen für Mediengenerierung | Gemeinsame Hilfsfunktionen für Failover, Kandidatenauswahl und Meldungen bei fehlenden Modellen für Bild-/Video-/Musikgenerierung | - | `plugin-sdk/media-understanding` | Hilfsfunktionen für Media Understanding | Typen für Media-Understanding-Provider plus providerseitige Exporte für Bild-/Audio-Hilfsfunktionen | - | `plugin-sdk/text-runtime` | Gemeinsame Texthilfsfunktionen | Entfernen Assistant-sichtbaren Texts, Rendern/Chunking/Tabellen für Markdown, Hilfsfunktionen für Redaction, Direktiv-Tags, Safe-Text-Utilities und verwandte Hilfsfunktionen für Text/Logging | + | `plugin-sdk/media-runtime` | Gemeinsame Medien-Hilfsfunktionen | Hilfsfunktionen für Abruf/Transformation/Speicherung von Medien sowie Builder für Medien-Payloads | + | `plugin-sdk/media-generation-runtime` | Gemeinsame Hilfsfunktionen für Mediengenerierung | Gemeinsame Hilfsfunktionen für Failover, Kandidatenauswahl und Hinweise bei fehlenden Modellen für Bild-/Video-/Musikgenerierung | + | `plugin-sdk/media-understanding` | Hilfsfunktionen für Medienverständnis | Typen für Media-Understanding-Provider plus providerseitige Exporte für Bild-/Audio-Hilfsfunktionen | + | `plugin-sdk/text-runtime` | Gemeinsame Text-Hilfsfunktionen | Entfernen von für Assistenten sichtbarem Text, Hilfsfunktionen für Markdown-Rendering/Chunking/Tabellen, Redaktionshilfsfunktionen, Hilfsfunktionen für Directive-Tags, Safe-Text-Dienstprogramme und verwandte Hilfsfunktionen für Text/Logging | | `plugin-sdk/text-chunking` | Hilfsfunktionen für Text-Chunking | Hilfsfunktion für Chunking ausgehender Texte | - | `plugin-sdk/speech` | Hilfsfunktionen für Sprache | Typen für Speech-Provider plus providerseitige Hilfsfunktionen für Direktiven, Registry und Validierung | - | `plugin-sdk/speech-core` | Gemeinsamer Speech-Core | Typen für Speech-Provider, Registry, Direktiven, Normalisierung | + | `plugin-sdk/speech` | Hilfsfunktionen für Sprachausgabe | Typen für Speech-Provider plus providerseitige Hilfsfunktionen für Direktiven, Registry und Validierung | + | `plugin-sdk/speech-core` | Gemeinsamer Kern für Sprachausgabe | Typen für Speech-Provider, Registry, Direktiven, Normalisierung | | `plugin-sdk/realtime-transcription` | Hilfsfunktionen für Echtzeit-Transkription | Provider-Typen und Registry-Hilfsfunktionen | - | `plugin-sdk/realtime-voice` | Hilfsfunktionen für Echtzeit-Sprache | Provider-Typen und Registry-Hilfsfunktionen | - | `plugin-sdk/image-generation-core` | Gemeinsamer Core für Bildgenerierung | Typen, Failover, Auth und Registry-Hilfsfunktionen für Bildgenerierung | - | `plugin-sdk/music-generation` | Hilfsfunktionen für Musikgenerierung | Typen für Musikgenerierungs-Provider/-Anfrage/-Ergebnis | - | `plugin-sdk/music-generation-core` | Gemeinsamer Core für Musikgenerierung | Typen für Musikgenerierung, Hilfsfunktionen für Failover, Provider-Lookup und Modell-Ref-Parsing | - | `plugin-sdk/video-generation` | Hilfsfunktionen für Videogenerierung | Typen für Videogenerierungs-Provider/-Anfrage/-Ergebnis | - | `plugin-sdk/video-generation-core` | Gemeinsamer Core für Videogenerierung | Typen für Videogenerierung, Hilfsfunktionen für Failover, Provider-Lookup und Modell-Ref-Parsing | - | `plugin-sdk/interactive-runtime` | Hilfsfunktionen für interaktive Antworten | Normalisierung/Reduktion interaktiver Antwortnutzlasten | - | `plugin-sdk/channel-config-primitives` | Primitive für Kanal-Konfiguration | Schmale Primitive für Kanal-Konfigurationsschemas | - | `plugin-sdk/channel-config-writes` | Hilfsfunktionen für Schreibvorgänge in Kanal-Konfiguration | Hilfsfunktionen für Autorisierung von Schreibvorgängen in Kanal-Konfiguration | - | `plugin-sdk/channel-plugin-common` | Gemeinsames Kanal-Prelude | Exporte des gemeinsamen Kanal-Plugin-Preludes | + | `plugin-sdk/realtime-voice` | Hilfsfunktionen für Echtzeit-Stimme | Provider-Typen und Registry-Hilfsfunktionen | + | `plugin-sdk/image-generation-core` | Gemeinsamer Kern für Bildgenerierung | Typen, Failover-, Auth- und Registry-Hilfsfunktionen für Bildgenerierung | + | `plugin-sdk/music-generation` | Hilfsfunktionen für Musikgenerierung | Typen für Music-Generation-Provider/Requests/Ergebnisse | + | `plugin-sdk/music-generation-core` | Gemeinsamer Kern für Musikgenerierung | Typen für Musikgenerierung, Failover-Hilfsfunktionen, Provider-Lookup und Parsing von Modellreferenzen | + | `plugin-sdk/video-generation` | Hilfsfunktionen für Videogenerierung | Typen für Video-Generation-Provider/Requests/Ergebnisse | + | `plugin-sdk/video-generation-core` | Gemeinsamer Kern für Videogenerierung | Typen für Videogenerierung, Failover-Hilfsfunktionen, Provider-Lookup und Parsing von Modellreferenzen | + | `plugin-sdk/interactive-runtime` | Hilfsfunktionen für interaktive Antworten | Normalisierung/Reduktion von Payloads interaktiver Antworten | + | `plugin-sdk/channel-config-primitives` | Grundbausteine für Kanal-Konfiguration | Schmale Grundbausteine für Kanal-Konfigurationsschemata | + | `plugin-sdk/channel-config-writes` | Hilfsfunktionen für Kanal-Konfigurationsschreibvorgänge | Hilfsfunktionen zur Autorisierung von Kanal-Konfigurationsschreibvorgängen | + | `plugin-sdk/channel-plugin-common` | Gemeinsames Kanal-Präludium | Gemeinsame Exporte des Kanal-Plugin-Präludiums | | `plugin-sdk/channel-status` | Hilfsfunktionen für Kanalstatus | Gemeinsame Hilfsfunktionen für Snapshots/Zusammenfassungen des Kanalstatus | - | `plugin-sdk/allowlist-config-edit` | Hilfsfunktionen für Allowlist-Konfiguration | Hilfsfunktionen zum Bearbeiten/Lesen von Allowlist-Konfiguration | + | `plugin-sdk/allowlist-config-edit` | Hilfsfunktionen für Allowlist-Konfigurationen | Hilfsfunktionen zum Bearbeiten/Lesen von Allowlist-Konfigurationen | | `plugin-sdk/group-access` | Hilfsfunktionen für Gruppenzugriff | Gemeinsame Hilfsfunktionen für Entscheidungen zum Gruppenzugriff | | `plugin-sdk/direct-dm` | Hilfsfunktionen für direkte DMs | Gemeinsame Hilfsfunktionen für Auth/Guards bei direkten DMs | | `plugin-sdk/extension-shared` | Gemeinsame Hilfsfunktionen für Erweiterungen | Primitive für passive Kanäle/Status und Ambient-Proxy-Hilfsfunktionen | - | `plugin-sdk/webhook-targets` | Hilfsfunktionen für Webhook-Ziele | Hilfsfunktionen für Registry und Route-Install von Webhook-Zielen | - | `plugin-sdk/webhook-path` | Hilfsfunktionen für Webhook-Pfade | Hilfsfunktionen zur Normalisierung von Webhook-Pfaden | - | `plugin-sdk/web-media` | Gemeinsame Web-Medienhilfsfunktionen | Hilfsfunktionen zum Laden entfernter/lokaler Medien | - | `plugin-sdk/zod` | Zod-Re-Export | Re-exportiertes `zod` für Nutzer des Plugin SDK | - | `plugin-sdk/memory-core` | Gebündelte memory-core-Hilfsfunktionen | Oberfläche für Hilfsfunktionen zu Memory-Manager/Konfiguration/Datei/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Runtime-Fassade für Memory-Engine | Runtime-Fassade für Memory-Index/-Suche | - | `plugin-sdk/memory-core-host-engine-foundation` | Foundation-Engine für Memory-Host | Exporte der Foundation-Engine für Memory-Host | - | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding-Engine für Memory-Host | Exporte der Embedding-Engine für Memory-Host | - | `plugin-sdk/memory-core-host-engine-qmd` | QMD-Engine für Memory-Host | Exporte der QMD-Engine für Memory-Host | - | `plugin-sdk/memory-core-host-engine-storage` | Storage-Engine für Memory-Host | Exporte der Storage-Engine für Memory-Host | - | `plugin-sdk/memory-core-host-multimodal` | Multimodale Hilfsfunktionen für Memory-Host | Multimodale Hilfsfunktionen für Memory-Host | - | `plugin-sdk/memory-core-host-query` | Query-Hilfsfunktionen für Memory-Host | Query-Hilfsfunktionen für Memory-Host | - | `plugin-sdk/memory-core-host-secret` | Secret-Hilfsfunktionen für Memory-Host | Secret-Hilfsfunktionen für Memory-Host | - | `plugin-sdk/memory-core-host-events` | Hilfsfunktionen für Event-Journal des Memory-Hosts | Hilfsfunktionen für Event-Journal des Memory-Hosts | - | `plugin-sdk/memory-core-host-status` | Status-Hilfsfunktionen für Memory-Host | Status-Hilfsfunktionen für Memory-Host | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI-Runtime für Memory-Host | CLI-Runtime-Hilfsfunktionen für Memory-Host | - | `plugin-sdk/memory-core-host-runtime-core` | Core-Runtime für Memory-Host | Core-Runtime-Hilfsfunktionen für Memory-Host | - | `plugin-sdk/memory-core-host-runtime-files` | Datei-/Runtime-Hilfsfunktionen für Memory-Host | Datei-/Runtime-Hilfsfunktionen für Memory-Host | - | `plugin-sdk/memory-host-core` | Alias für Core-Runtime des Memory-Hosts | Anbieterneutraler Alias für Core-Runtime-Hilfsfunktionen des Memory-Hosts | - | `plugin-sdk/memory-host-events` | Alias für Event-Journal des Memory-Hosts | Anbieterneutraler Alias für Hilfsfunktionen des Event-Journals des Memory-Hosts | - | `plugin-sdk/memory-host-files` | Alias für Datei-/Runtime des Memory-Hosts | Anbieterneutraler Alias für Datei-/Runtime-Hilfsfunktionen des Memory-Hosts | - | `plugin-sdk/memory-host-markdown` | Hilfsfunktionen für verwaltetes Markdown | Gemeinsame Hilfsfunktionen für verwaltetes Markdown für memory-nahe Plugins | - | `plugin-sdk/memory-host-search` | Fassade für aktive Memory-Suche | Lazy Runtime-Fassade für Search-Manager der aktiven Memory-Suche | - | `plugin-sdk/memory-host-status` | Alias für Status des Memory-Hosts | Anbieterneutraler Alias für Status-Hilfsfunktionen des Memory-Hosts | - | `plugin-sdk/memory-lancedb` | Gebündelte memory-lancedb-Hilfsfunktionen | Oberfläche für memory-lancedb-Hilfsfunktionen | - | `plugin-sdk/testing` | Test-Utilities | Testhilfen und Mocks | + | `plugin-sdk/webhook-targets` | Hilfsfunktionen für Webhook-Ziele | Registry für Webhook-Ziele und Hilfsfunktionen für die Routeninstallation | + | `plugin-sdk/webhook-path` | Hilfsfunktionen für Webhook-Pfade | Hilfsfunktionen für die Normalisierung von Webhook-Pfaden | + | `plugin-sdk/web-media` | Gemeinsame Hilfsfunktionen für Webmedien | Hilfsfunktionen zum Laden entfernter/lokaler Medien | + | `plugin-sdk/zod` | Zod-Re-Export | Re-exportiertes `zod` für Plugin-SDK-Konsumenten | + | `plugin-sdk/memory-core` | Gebündelte Hilfsfunktionen für memory-core | Hilfsoberfläche für Speicherverwaltung/Konfiguration/Dateien/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Laufzeit-Fassade für die Speicher-Engine | Laufzeit-Fassade für Speicherindex/Suche | + | `plugin-sdk/memory-core-host-engine-foundation` | Host-Foundation-Engine für Speicher | Exporte der Host-Foundation-Engine für Speicher | + | `plugin-sdk/memory-core-host-engine-embeddings` | Host-Embedding-Engine für Speicher | Exporte der Host-Embedding-Engine für Speicher | + | `plugin-sdk/memory-core-host-engine-qmd` | Host-QMD-Engine für Speicher | Exporte der Host-QMD-Engine für Speicher | + | `plugin-sdk/memory-core-host-engine-storage` | Host-Storage-Engine für Speicher | Exporte der Host-Storage-Engine für Speicher | + | `plugin-sdk/memory-core-host-multimodal` | Hilfsfunktionen für multimodalen Speicher-Host | Hilfsfunktionen für multimodalen Speicher-Host | + | `plugin-sdk/memory-core-host-query` | Hilfsfunktionen für Speicher-Host-Abfragen | Hilfsfunktionen für Speicher-Host-Abfragen | + | `plugin-sdk/memory-core-host-secret` | Hilfsfunktionen für Speicher-Host-Secrets | Hilfsfunktionen für Speicher-Host-Secrets | + | `plugin-sdk/memory-core-host-events` | Hilfsfunktionen für Ereignisjournale des Speicher-Hosts | Hilfsfunktionen für Ereignisjournale des Speicher-Hosts | + | `plugin-sdk/memory-core-host-status` | Hilfsfunktionen für Speicher-Host-Status | Hilfsfunktionen für Speicher-Host-Status | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI-Laufzeit des Speicher-Hosts | CLI-Laufzeit-Hilfsfunktionen des Speicher-Hosts | + | `plugin-sdk/memory-core-host-runtime-core` | Kernlaufzeit des Speicher-Hosts | Kernlaufzeit-Hilfsfunktionen des Speicher-Hosts | + | `plugin-sdk/memory-core-host-runtime-files` | Datei-/Laufzeit-Hilfsfunktionen des Speicher-Hosts | Datei-/Laufzeit-Hilfsfunktionen des Speicher-Hosts | + | `plugin-sdk/memory-host-core` | Alias für Kernlaufzeit des Speicher-Hosts | Anbieterneutraler Alias für Kernlaufzeit-Hilfsfunktionen des Speicher-Hosts | + | `plugin-sdk/memory-host-events` | Alias für Ereignisjournale des Speicher-Hosts | Anbieterneutraler Alias für Hilfsfunktionen für Ereignisjournale des Speicher-Hosts | + | `plugin-sdk/memory-host-files` | Alias für Datei-/Laufzeit des Speicher-Hosts | Anbieterneutraler Alias für Datei-/Laufzeit-Hilfsfunktionen des Speicher-Hosts | + | `plugin-sdk/memory-host-markdown` | Hilfsfunktionen für verwaltetes Markdown | Gemeinsame Hilfsfunktionen für verwaltetes Markdown für speichernahe Plugins | + | `plugin-sdk/memory-host-search` | Fassade für aktive Speichersuche | Lazy Runtime-Fassade des Search-Managers für aktiven Speicher | + | `plugin-sdk/memory-host-status` | Alias für Speicher-Host-Status | Anbieterneutraler Alias für Hilfsfunktionen für Speicher-Host-Status | + | `plugin-sdk/memory-lancedb` | Gebündelte Hilfsfunktionen für memory-lancedb | Hilfsoberfläche für memory-lancedb | + | `plugin-sdk/testing` | Testdienstprogramme | Testhilfsfunktionen und Mocks | -Diese Tabelle ist absichtlich auf die häufige Migrations-Teilmenge beschränkt, nicht auf die vollständige SDK- -Oberfläche. Die vollständige Liste der über 200 Einstiegspunkte befindet sich in +Diese Tabelle ist absichtlich nur die gängige Migrations-Teilmenge und nicht die vollständige SDK- +Oberfläche. Die vollständige Liste mit mehr als 200 Einstiegspunkten befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`. -Diese Liste enthält weiterhin einige Hilfs-Seams für gebündelte Plugins wie +Diese Liste enthält weiterhin einige Helper-Seams für gebündelte Plugins wie `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` und `plugin-sdk/matrix*`. Diese bleiben für -die Wartung gebündelter Plugins und aus Kompatibilitätsgründen exportiert, werden aber absichtlich -aus der häufigen Migrationstabelle ausgelassen und sind kein empfohlenes Ziel für +`plugin-sdk/zalo-setup` und `plugin-sdk/matrix*`. Diese werden für +die Pflege gebündelter Plugins und aus Kompatibilitätsgründen weiterhin exportiert, sind aber +absichtlich nicht in der gängigen Migrationstabelle enthalten und nicht das empfohlene Ziel für neuen Plugin-Code. Dieselbe Regel gilt für andere Familien gebündelter Hilfsfunktionen wie: @@ -360,7 +362,7 @@ Dieselbe Regel gilt für andere Familien gebündelter Hilfsfunktionen wie: - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- gebündelte Hilfs-/Plugin-Oberflächen wie `plugin-sdk/googlechat`, +- gebündelte Helper-/Plugin-Oberflächen wie `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -369,39 +371,39 @@ Dieselbe Regel gilt für andere Familien gebündelter Hilfsfunktionen wie: `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` und `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` stellt derzeit die schmale Token-Hilfsoberfläche -`DEFAULT_COPILOT_API_BASE_URL`, +`plugin-sdk/github-copilot-token` stellt derzeit die schmale +Token-Hilfsoberfläche `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` und `resolveCopilotApiToken` bereit. -Verwende den schmalsten Import, der zur Aufgabe passt. Wenn du keinen Export finden kannst, -prüfe die Quelle unter `src/plugin-sdk/` oder frage auf Discord nach. +Verwenden Sie den schmalsten Import, der zur Aufgabe passt. Wenn Sie keinen Export finden können, +prüfen Sie den Quellcode unter `src/plugin-sdk/` oder fragen Sie in Discord. ## Zeitplan für die Entfernung -| Wann | Was passiert | -| ---------------------- | ----------------------------------------------------------------------- | -| **Jetzt** | Veraltete Oberflächen geben Laufzeitwarnungen aus | -| **Nächste Major-Version** | Veraltete Oberflächen werden entfernt; Plugins, die sie noch verwenden, schlagen fehl | +| Wann | Was passiert | +| --- | --- | +| **Jetzt** | Veraltete Oberflächen geben Laufzeitwarnungen aus | +| **Nächste Hauptversion** | Veraltete Oberflächen werden entfernt; Plugins, die sie noch verwenden, schlagen fehl | -Alle Core-Plugins wurden bereits migriert. Externe Plugins sollten vor der -nächsten Major-Version migrieren. +Alle Core-Plugins wurden bereits migriert. Externe Plugins sollten vor der nächsten Hauptversion +migrieren. ## Warnungen vorübergehend unterdrücken -Setze diese Umgebungsvariablen, während du an der Migration arbeitest: +Setzen Sie diese Umgebungsvariablen, während Sie an der Migration arbeiten: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Dies ist ein temporärer Escape Hatch, keine dauerhafte Lösung. +Dies ist ein vorübergehender Ausweg, keine dauerhafte Lösung. ## Verwandt -- [Erste Schritte](/de/plugins/building-plugins) — dein erstes Plugin erstellen -- [SDK Overview](/de/plugins/sdk-overview) — vollständige Referenz für Subpath-Imports -- [Channel Plugins](/de/plugins/sdk-channel-plugins) — Kanal-Plugins erstellen -- [Provider Plugins](/de/plugins/sdk-provider-plugins) — Provider-Plugins erstellen -- [Plugin Internals](/de/plugins/architecture) — Architektur-Deep-Dive -- [Plugin Manifest](/de/plugins/manifest) — Referenz für das Manifest-Schema +- [Erste Schritte](/de/plugins/building-plugins) — Ihr erstes Plugin erstellen +- [SDK-Übersicht](/de/plugins/sdk-overview) — vollständige Referenz zu Unterpfad-Imports +- [Kanal-Plugins](/de/plugins/sdk-channel-plugins) — Kanal-Plugins erstellen +- [Provider-Plugins](/de/plugins/sdk-provider-plugins) — Provider-Plugins erstellen +- [Plugin-Interna](/de/plugins/architecture) — tiefer Einblick in die Architektur +- [Plugin-Manifest](/de/plugins/manifest) — Referenz zum Manifest-Schema diff --git a/docs/de/plugins/sdk-overview.md b/docs/de/plugins/sdk-overview.md index 1eb7b3cfd..69b832d0a 100644 --- a/docs/de/plugins/sdk-overview.md +++ b/docs/de/plugins/sdk-overview.md @@ -1,362 +1,365 @@ --- read_when: - - Sie müssen wissen, aus welchem SDK-Unterpfad Sie importieren sollen - - Sie möchten eine Referenz für alle Registrierungsmethoden in OpenClawPluginApi - - Sie schlagen einen bestimmten SDK-Export nach + - Sie müssen wissen, aus welchem SDK-Subpath Sie importieren sollen + - Sie möchten eine Referenz für alle Registrierungsmethoden auf OpenClawPluginApi + - Sie suchen einen bestimmten SDK-Export nach sidebarTitle: SDK Overview -summary: Import-Map, Referenz der Registrierungs-API und SDK-Architektur -title: Überblick über das Plugin SDK +summary: Referenz zur Import-Zuordnung, Registrierungs-API und SDK-Architektur +title: Plugin SDK Überblick x-i18n: - generated_at: "2026-04-08T02:18:25Z" + generated_at: "2026-04-09T01:31:37Z" model: gpt-5.4 provider: openai - source_hash: c5a41bd82d165dfbb7fbd6e4528cf322e9133a51efe55fa8518a7a0a626d9d30 + source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381 source_path: plugins/sdk-overview.md workflow: 15 --- -# Überblick über das Plugin SDK +# Plugin SDK Überblick -Das Plugin SDK ist der typisierte Vertrag zwischen Plugins und dem Core. Diese Seite ist die -Referenz für **was importiert werden soll** und **was Sie registrieren können**. +Das Plugin SDK ist der typisierte Vertrag zwischen Plugins und dem Kern. Diese Seite ist die +Referenz für **was importiert werden soll** und **was registriert werden kann**. - **Suchen Sie nach einer How-to-Anleitung?** - - Ihr erstes Plugin? Beginnen Sie mit [Erste Schritte](/de/plugins/building-plugins) + **Suchen Sie eine Schritt-für-Schritt-Anleitung?** + - Erstes Plugin? Beginnen Sie mit [Getting Started](/de/plugins/building-plugins) - Channel-Plugin? Siehe [Channel Plugins](/de/plugins/sdk-channel-plugins) - - Provider-Plugin? Siehe [Provider Plugins](/de/plugins/sdk-provider-plugins) + - Anbieter-Plugin? Siehe [Provider Plugins](/de/plugins/sdk-provider-plugins) ## Importkonvention -Importieren Sie immer aus einem spezifischen Unterpfad: +Importieren Sie immer aus einem bestimmten Subpath: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Jeder Unterpfad ist ein kleines, in sich abgeschlossenes Modul. Das hält den Start schnell und -verhindert Probleme mit zirkulären Abhängigkeiten. Für channelspezifische Entry-/Build-Helper +Jeder Subpath ist ein kleines, in sich geschlossenes Modul. Das hält den Start schnell und +verhindert Probleme mit zirkulären Abhängigkeiten. Für Channel-spezifische Entry-/Build-Helfer bevorzugen Sie `openclaw/plugin-sdk/channel-core`; verwenden Sie `openclaw/plugin-sdk/core` für -die breitere Dachoberfläche und gemeinsame Helper wie +die breitere Dachoberfläche und gemeinsame Hilfsfunktionen wie `buildChannelConfigSchema`. -Fügen Sie keine nach Providern benannten Convenience-Seams hinzu und hängen Sie nicht von ihnen ab, wie +Fügen Sie keine nach Anbietern benannten Convenience-Seams hinzu und hängen Sie nicht von solchen ab, wie `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` oder -channelgebrandete Helper-Seams. Gebündelte Plugins sollten generische -SDK-Unterpfade innerhalb ihrer eigenen `api.ts`- oder `runtime-api.ts`-Barrels zusammensetzen, und der Core +Channel-markenspezifischen Helper-Seams. Gebündelte Plugins sollten generische +SDK-Subpaths in ihren eigenen `api.ts`- oder `runtime-api.ts`-Barrels zusammensetzen, und der Kern sollte entweder diese pluginlokalen Barrels verwenden oder einen schmalen generischen SDK- -Vertrag hinzufügen, wenn der Bedarf wirklich channelübergreifend ist. +Vertrag hinzufügen, wenn der Bedarf wirklich kanalübergreifend ist. -Die generierte Export-Map enthält weiterhin eine kleine Menge an Helper- -Seams für gebündelte Plugins wie `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Die generierte Export-Zuordnung enthält weiterhin eine kleine Menge gebündelter Plugin-Helper- +Seams wie `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` und `plugin-sdk/matrix*`. Diese -Unterpfade existieren nur für Wartung und Kompatibilität gebündelter Plugins; sie werden -absichtlich aus der unten stehenden allgemeinen Tabelle weggelassen und sind nicht der empfohlene +Subpaths existieren nur für die Wartung und Kompatibilität gebündelter Plugins; sie werden +absichtlich aus der allgemeinen Tabelle unten ausgelassen und sind nicht der empfohlene Importpfad für neue Drittanbieter-Plugins. -## Unterpfad-Referenz +## Subpath-Referenz -Die am häufigsten verwendeten Unterpfade, nach Zweck gruppiert. Die generierte vollständige Liste von -mehr als 200 Unterpfaden befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`. +Die am häufigsten verwendeten Subpaths, nach Zweck gruppiert. Die generierte vollständige Liste mit +mehr als 200 Subpaths befindet sich in `scripts/lib/plugin-sdk-entrypoints.json`. -Reservierte Helper-Unterpfade für gebündelte Plugins erscheinen weiterhin in dieser generierten Liste. -Behandeln Sie diese als Implementierungsdetail-/Kompatibilitätsoberflächen, sofern eine Dokumentationsseite -nicht ausdrücklich einen davon als öffentlich empfiehlt. +Reservierte gebündelte Plugin-Helper-Subpaths erscheinen weiterhin in dieser generierten Liste. +Behandeln Sie diese als Implementierungsdetail-/Kompatibilitätsoberflächen, sofern nicht eine Dokumentationsseite +sie ausdrücklich als öffentlich hervorhebt. ### Plugin-Einstiegspunkt -| Subpath | Key exports | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| Subpath | Wichtige Exporte | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - - | Subpath | Key exports | + + | Subpath | Wichtige Exporte | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Root-`openclaw.json`-Zod-Schema-Export (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Zod-Schema-Export für das Root-`openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard` sowie `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Gemeinsame Helper für Setup-Wizards, Allowlist-Prompts und Setup-Status-Builder | + | `plugin-sdk/setup` | Gemeinsame Hilfsfunktionen für Einrichtungsassistenten, Allowlist-Aufforderungen, Builder für Einrichtungsstatus | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helper für Multi-Account-Konfiguration/Aktions-Gates und Fallbacks für Standardkonten | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, Helper zur Normalisierung von Account-IDs | - | `plugin-sdk/account-resolution` | Account-Lookup- und Standard-Fallback-Helper | - | `plugin-sdk/account-helpers` | Schmale Helper für Account-Listen/Account-Aktionen | + | `plugin-sdk/account-core` | Hilfsfunktionen für Mehrkonten-Konfiguration/Aktions-Gating, Hilfen für Standardkonto-Fallback | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, Hilfsfunktionen zur Normalisierung von Konto-IDs | + | `plugin-sdk/account-resolution` | Kontosuche + Hilfen für Standard-Fallback | + | `plugin-sdk/account-helpers` | Schmale Hilfsfunktionen für Kontolisten/Kontoaktionen | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Channel-Konfigurationsschematypen | - | `plugin-sdk/telegram-command-config` | Helper zur Normalisierung/Validierung benutzerdefinierter Telegram-Befehle mit Fallback für gebündelte Verträge | + | `plugin-sdk/channel-config-schema` | Typen für Channel-Konfigurationsschemata | + | `plugin-sdk/telegram-command-config` | Hilfsfunktionen zur Normalisierung/Validierung benutzerdefinierter Telegram-Befehle mit Fallback für gebündelte Verträge | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Gemeinsame Helper für eingehende Routen und Envelope-Builder | - | `plugin-sdk/inbound-reply-dispatch` | Gemeinsame Helper zum Erfassen und Dispatchen eingehender Nachrichten | - | `plugin-sdk/messaging-targets` | Helper zum Parsen/Abgleichen von Zielen | - | `plugin-sdk/outbound-media` | Gemeinsame Helper zum Laden ausgehender Medien | - | `plugin-sdk/outbound-runtime` | Helper für ausgehende Identität/Sende-Delegates | - | `plugin-sdk/thread-bindings-runtime` | Lifecycle- und Adapter-Helper für Thread-Bindings | - | `plugin-sdk/agent-media-payload` | Legacy-Builder für Agent-Media-Payloads | - | `plugin-sdk/conversation-runtime` | Helper für Konversations-/Thread-Bindings, Pairing und konfigurierte Bindings | - | `plugin-sdk/runtime-config-snapshot` | Helper für Runtime-Konfigurations-Snapshots | - | `plugin-sdk/runtime-group-policy` | Helper zur Auflösung von Runtime-Gruppenrichtlinien | - | `plugin-sdk/channel-status` | Gemeinsame Helper für Snapshots/Zusammenfassungen des Channel-Status | - | `plugin-sdk/channel-config-primitives` | Schmale Primitive für Channel-Konfigurationsschemas | - | `plugin-sdk/channel-config-writes` | Helper zur Autorisierung von Channel-Konfigurationsschreibvorgängen | + | `plugin-sdk/inbound-envelope` | Gemeinsame Hilfsfunktionen für eingehende Routen und Envelope-Builder | + | `plugin-sdk/inbound-reply-dispatch` | Gemeinsame Hilfsfunktionen zum Aufzeichnen und Verteilen eingehender Nachrichten | + | `plugin-sdk/messaging-targets` | Hilfsfunktionen zum Parsen/Abgleichen von Zielen | + | `plugin-sdk/outbound-media` | Gemeinsame Hilfsfunktionen zum Laden ausgehender Medien | + | `plugin-sdk/outbound-runtime` | Hilfsfunktionen für ausgehende Identitäten/Sende-Delegates | + | `plugin-sdk/thread-bindings-runtime` | Hilfsfunktionen für Lebenszyklus und Adapter von Thread-Bindungen | + | `plugin-sdk/agent-media-payload` | Legacy-Builder für Agent-Medien-Payloads | + | `plugin-sdk/conversation-runtime` | Hilfsfunktionen für Konversations-/Thread-Bindung, Pairing und konfigurierte Bindungen | + | `plugin-sdk/runtime-config-snapshot` | Hilfsfunktion für Laufzeit-Konfigurations-Snapshots | + | `plugin-sdk/runtime-group-policy` | Hilfsfunktionen zur Auflösung von Laufzeit-Gruppenrichtlinien | + | `plugin-sdk/channel-status` | Gemeinsame Hilfsfunktionen für Snapshots/Zusammenfassungen des Channel-Status | + | `plugin-sdk/channel-config-primitives` | Schmale Primitive für Channel-Konfigurationsschemata | + | `plugin-sdk/channel-config-writes` | Hilfsfunktionen zur Autorisierung von Channel-Konfigurationsschreibvorgängen | | `plugin-sdk/channel-plugin-common` | Gemeinsame Prelude-Exporte für Channel-Plugins | - | `plugin-sdk/allowlist-config-edit` | Helper zum Lesen/Bearbeiten der Allowlist-Konfiguration | - | `plugin-sdk/group-access` | Gemeinsame Helper für Gruppen-Zugriffsentscheidungen | - | `plugin-sdk/direct-dm` | Gemeinsame Helper für direkte-DM-Auth/Guards | - | `plugin-sdk/interactive-runtime` | Helper zur Normalisierung/Reduktion interaktiver Antwort-Payloads | - | `plugin-sdk/channel-inbound` | Helper für Inbound-Debounce, Mention-Matching, Mention-Policy und Envelopes | - | `plugin-sdk/channel-send-result` | Antwort-Ergebnistypen | + | `plugin-sdk/allowlist-config-edit` | Hilfsfunktionen zum Bearbeiten/Lesen der Allowlist-Konfiguration | + | `plugin-sdk/group-access` | Gemeinsame Hilfsfunktionen für Entscheidungen über Gruppenzugriff | + | `plugin-sdk/direct-dm` | Gemeinsame Hilfsfunktionen für Auth/Schutz bei Direktnachrichten | + | `plugin-sdk/interactive-runtime` | Hilfsfunktionen zur Normalisierung/Reduktion interaktiver Antwort-Payloads | + | `plugin-sdk/channel-inbound` | Hilfsfunktionen für eingehendes Debouncing, Mention-Abgleich, Mention-Richtlinien und Envelopes | + | `plugin-sdk/channel-send-result` | Typen für Antwortergebnisse | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | - | `plugin-sdk/channel-targets` | Helper zum Parsen/Abgleichen von Zielen | - | `plugin-sdk/channel-contract` | Channel-Vertragstypen | - | `plugin-sdk/channel-feedback` | Feedback-/Reaktions-Verdrahtung | - | `plugin-sdk/channel-secret-runtime` | Schmale Helper für Secret-Verträge wie `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` und Secret-Zieltypen | + | `plugin-sdk/channel-targets` | Hilfsfunktionen zum Parsen/Abgleichen von Zielen | + | `plugin-sdk/channel-contract` | Typen für Channel-Verträge | + | `plugin-sdk/channel-feedback` | Verdrahtung für Feedback/Reaktionen | + | `plugin-sdk/channel-secret-runtime` | Schmale Hilfsfunktionen für Secret-Verträge wie `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` sowie Secret-Zieltypen | - - | Subpath | Key exports | + + | Subpath | Wichtige Exporte | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Kuratierte Setup-Helper für lokale/selbstgehostete Provider | - | `plugin-sdk/self-hosted-provider-setup` | Fokussierte Setup-Helper für OpenAI-kompatible selbstgehostete Provider | - | `plugin-sdk/cli-backend` | Standardwerte für CLI-Backends + Watchdog-Konstanten | - | `plugin-sdk/provider-auth-runtime` | Helper für die Auflösung von Runtime-API-Schlüsseln für Provider-Plugins | - | `plugin-sdk/provider-auth-api-key` | Onboarding-/Profile-Write-Helper für API-Schlüssel wie `upsertApiKeyProfile` | + | `plugin-sdk/provider-setup` | Kuratierte Hilfsfunktionen für die Einrichtung lokaler/selbst gehosteter Anbieter | + | `plugin-sdk/self-hosted-provider-setup` | Fokussierte Hilfsfunktionen für die Einrichtung selbst gehosteter OpenAI-kompatibler Anbieter | + | `plugin-sdk/cli-backend` | CLI-Backend-Standardwerte + Watchdog-Konstanten | + | `plugin-sdk/provider-auth-runtime` | Hilfsfunktionen zur Laufzeit-Auflösung von API-Schlüsseln für Anbieter-Plugins | + | `plugin-sdk/provider-auth-api-key` | Hilfsfunktionen für API-Schlüssel-Onboarding/Profilschreibvorgänge wie `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | Standard-Builder für OAuth-Authentifizierungsergebnisse | - | `plugin-sdk/provider-auth-login` | Gemeinsame interaktive Login-Helper für Provider-Plugins | - | `plugin-sdk/provider-env-vars` | Helper zum Lookup von Umgebungsvariablen für Provider-Auth | + | `plugin-sdk/provider-auth-login` | Gemeinsame interaktive Login-Hilfsfunktionen für Anbieter-Plugins | + | `plugin-sdk/provider-env-vars` | Hilfsfunktionen zur Suche von Auth-Umgebungsvariablen für Anbieter | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Replay-Policy-Builder, Provider-Endpoint-Helper und Helper zur Normalisierung von Modell-IDs wie `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, gemeinsame Builder für Replay-Richtlinien, Hilfsfunktionen für Anbieter-Endpunkte und Hilfsfunktionen zur Modell-ID-Normalisierung wie `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Generische Helper für Provider-HTTP/Endpoint-Fähigkeiten | - | `plugin-sdk/provider-web-fetch-contract` | Schmale Helper für Web-Fetch-Konfigurations-/Auswahlverträge wie `enablePluginInConfig` und `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helper für Registrierung/Cache von Web-Fetch-Providern | - | `plugin-sdk/provider-web-search-contract` | Schmale Helper für Web-Search-Konfigurations-/Credential-Verträge wie `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` und Scoped-Setter/Getter für Credentials | - | `plugin-sdk/provider-web-search` | Helper für Registrierung/Cache/Runtime von Web-Search-Providern | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini-Schema-Bereinigung + Diagnostik sowie xAI-Kompatibilitäts-Helper wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Generische Hilfsfunktionen für HTTP-/Endpoint-Fähigkeiten von Anbietern | + | `plugin-sdk/provider-web-fetch-contract` | Schmale Hilfsfunktionen für Web-Fetch-Konfigurations-/Auswahlverträge wie `enablePluginInConfig` und `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Hilfsfunktionen für Registrierung/Cache von Web-Fetch-Anbietern | + | `plugin-sdk/provider-web-search-config-contract` | Schmale Hilfsfunktionen für Websuche-Konfiguration/Berechtigungen für Anbieter, die keine Plugin-Aktivierungsverdrahtung benötigen | + | `plugin-sdk/provider-web-search-contract` | Schmale Hilfsfunktionen für Websuche-Konfigurations-/Berechtigungsverträge wie `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` und bereichsspezifische Setter/Getter für Berechtigungen | + | `plugin-sdk/provider-web-search` | Hilfsfunktionen für Registrierung/Cache/Laufzeit von Websuche-Anbietern | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Bereinigung + Diagnose für Gemini-Schemas und xAI-Kompatibilitätshelfer wie `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` und Ähnliches | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Stream-Wrapper-Typen und gemeinsame Wrapper-Helper für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Helper zum Patchen von Onboarding-Konfigurationen | - | `plugin-sdk/global-singleton` | Prozesslokale Singleton-/Map-/Cache-Helper | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, Stream-Wrapper-Typen und gemeinsame Wrapper-Helfer für Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Hilfsfunktionen zum Patchen der Onboarding-Konfiguration | + | `plugin-sdk/global-singleton` | Hilfsfunktionen für prozesslokale Singletons/Maps/Caches | - - | Subpath | Key exports | + + | Subpath | Wichtige Exporte | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, Helper für Befehlsregistrierung und Sender-Autorisierung | - | `plugin-sdk/approval-auth-runtime` | Approver-Auflösung und Helper für Same-Chat-Action-Auth | - | `plugin-sdk/approval-client-runtime` | Native Helper für Exec-Approval-Profile/-Filter | - | `plugin-sdk/approval-delivery-runtime` | Native Adapter für Approval-Fähigkeiten/Zustellung | - | `plugin-sdk/approval-gateway-runtime` | Gemeinsamer Helper zur Auflösung des Approval-Gateways | - | `plugin-sdk/approval-handler-adapter-runtime` | Leichtgewichtige Lade-Helper für native Approval-Adapter für Hot-Channel-Entrypoints | - | `plugin-sdk/approval-handler-runtime` | Breitere Runtime-Helper für Approval-Handler; bevorzugen Sie die schmaleren Adapter-/Gateway-Seams, wenn sie ausreichen | - | `plugin-sdk/approval-native-runtime` | Native Helper für Approval-Ziele und Account-Bindings | - | `plugin-sdk/approval-reply-runtime` | Helper für Antwort-Payloads zu Exec-/Plugin-Approvals | - | `plugin-sdk/command-auth-native` | Native Command-Auth und native Session-Target-Helper | - | `plugin-sdk/command-detection` | Gemeinsame Helper zur Befehlserkennung | - | `plugin-sdk/command-surface` | Helper zur Normalisierung von Befehls-Bodies und Befehlsoberflächen | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, Hilfsfunktionen für Befehlsregister, Hilfsfunktionen für Absenderautorisierung | + | `plugin-sdk/command-status` | Builder für Befehls-/Hilfemeldungen wie `buildCommandsMessagePaginated` und `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Hilfsfunktionen für Auflöser von Genehmigern und gleiche-Chat-Aktionsauthentifizierung | + | `plugin-sdk/approval-client-runtime` | Hilfsfunktionen für Profile/Filter der nativen Ausführungsfreigabe | + | `plugin-sdk/approval-delivery-runtime` | Adapter für native Genehmigungsfunktionen/-auslieferung | + | `plugin-sdk/approval-gateway-runtime` | Gemeinsame Hilfsfunktion zur Auflösung des Genehmigungs-Gateways | + | `plugin-sdk/approval-handler-adapter-runtime` | Leichtgewichtige Hilfsfunktionen zum Laden nativer Genehmigungsadapter für schnelle Channel-Einstiegspunkte | + | `plugin-sdk/approval-handler-runtime` | Breitere Laufzeit-Hilfsfunktionen für Genehmigungshandler; bevorzugen Sie die schmaleren Adapter-/Gateway-Seams, wenn sie ausreichen | + | `plugin-sdk/approval-native-runtime` | Hilfsfunktionen für native Genehmigungsziele und Konto-Bindungen | + | `plugin-sdk/approval-reply-runtime` | Hilfsfunktionen für Antwort-Payloads von Exec-/Plugin-Genehmigungen | + | `plugin-sdk/command-auth-native` | Native Befehlsauthentifizierung + Hilfsfunktionen für native Sitzungsziele | + | `plugin-sdk/command-detection` | Gemeinsame Hilfsfunktionen zur Befehlserkennung | + | `plugin-sdk/command-surface` | Hilfsfunktionen zur Normalisierung von Befehlsinhalten und Befehlsoberflächen | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Schmale Collection-Helper für Secret-Verträge von Channel-/Plugin-Secret-Oberflächen | - | `plugin-sdk/secret-ref-runtime` | Schmale `coerceSecretRef`- und SecretRef-Typing-Helper für Secret-Vertrags-/Konfigurations-Parsing | - | `plugin-sdk/security-runtime` | Gemeinsame Helper für Vertrauen, DM-Gating, externe Inhalte und Secret-Sammlung | - | `plugin-sdk/ssrf-policy` | Helper für Host-Allowlists und SSRF-Richtlinien für private Netzwerke | - | `plugin-sdk/ssrf-runtime` | Helper für Pinned-Dispatcher, SSRF-geschütztes Fetch und SSRF-Richtlinien | - | `plugin-sdk/secret-input` | Helper zum Parsen geheimer Eingaben | - | `plugin-sdk/webhook-ingress` | Helper für Webhook-Requests/-Ziele | - | `plugin-sdk/webhook-request-guards` | Helper für Größe/Timeout des Request-Bodys | + | `plugin-sdk/channel-secret-runtime` | Schmale Hilfsfunktionen zur Sammlung von Secret-Verträgen für Secret-Oberflächen von Channels/Plugins | + | `plugin-sdk/secret-ref-runtime` | Schmale Hilfsfunktionen für `coerceSecretRef` und SecretRef-Typisierung für Secret-Vertrags-/Konfigurations-Parsing | + | `plugin-sdk/security-runtime` | Gemeinsame Hilfsfunktionen für Vertrauen, DM-Gating, externe Inhalte und Secret-Sammlung | + | `plugin-sdk/ssrf-policy` | Hilfsfunktionen für Host-Allowlist und SSRF-Richtlinien für private Netzwerke | + | `plugin-sdk/ssrf-runtime` | Hilfsfunktionen für angeheftete Dispatcher, SSRF-geschütztes Fetch und SSRF-Richtlinien | + | `plugin-sdk/secret-input` | Hilfsfunktionen zum Parsen von Secret-Eingaben | + | `plugin-sdk/webhook-ingress` | Hilfsfunktionen für Webhook-Anfragen/-Ziele | + | `plugin-sdk/webhook-request-guards` | Hilfsfunktionen für Größe/Timeout von Request-Bodys | - - | Subpath | Key exports | + + | Subpath | Wichtige Exporte | | --- | --- | - | `plugin-sdk/runtime` | Breite Helper für Runtime/Logging/Backups/Plugin-Installation | - | `plugin-sdk/runtime-env` | Schmale Helper für Runtime-Umgebung, Logger, Timeout, Retry und Backoff | - | `plugin-sdk/channel-runtime-context` | Generische Helper für Registrierung und Lookup von Channel-Runtime-Kontexten | + | `plugin-sdk/runtime` | Breite Hilfsfunktionen für Laufzeit/Logging/Backups/Plugin-Installation | + | `plugin-sdk/runtime-env` | Schmale Hilfsfunktionen für Laufzeitumgebung, Logger, Timeout, Retry und Backoff | + | `plugin-sdk/channel-runtime-context` | Generische Hilfsfunktionen für Registrierung und Lookup von Channel-Laufzeitkontexten | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Gemeinsame Helper für Plugin-Befehle/Hooks/HTTP/Interaktivität | - | `plugin-sdk/hook-runtime` | Gemeinsame Helper für Webhook-/interne Hook-Pipelines | - | `plugin-sdk/lazy-runtime` | Helper für Lazy-Runtime-Importe/-Bindings wie `createLazyRuntimeModule`, `createLazyRuntimeMethod` und `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helper für Prozessausführung | - | `plugin-sdk/cli-runtime` | Helper für CLI-Formatierung, Warten und Version | - | `plugin-sdk/gateway-runtime` | Gateway-Client- und Helper zum Patchen des Channel-Status | - | `plugin-sdk/config-runtime` | Helper zum Laden/Schreiben von Konfigurationen | + | `plugin-sdk/plugin-runtime` | Gemeinsame Hilfsfunktionen für Plugin-Befehle/Hooks/HTTP/Interaktivität | + | `plugin-sdk/hook-runtime` | Gemeinsame Hilfsfunktionen für Webhook-/interne Hook-Pipelines | + | `plugin-sdk/lazy-runtime` | Hilfsfunktionen für lazy Laufzeitimporte/-bindungen wie `createLazyRuntimeModule`, `createLazyRuntimeMethod` und `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Hilfsfunktionen für Prozessausführung | + | `plugin-sdk/cli-runtime` | Hilfsfunktionen für CLI-Formatierung, Warten und Version | + | `plugin-sdk/gateway-runtime` | Hilfsfunktionen für Gateway-Client und Channel-Status-Patches | + | `plugin-sdk/config-runtime` | Hilfsfunktionen zum Laden/Schreiben von Konfiguration | | `plugin-sdk/telegram-command-config` | Normalisierung von Telegram-Befehlsnamen/-beschreibungen und Prüfungen auf Duplikate/Konflikte, auch wenn die gebündelte Telegram-Vertragsoberfläche nicht verfügbar ist | - | `plugin-sdk/approval-runtime` | Helper für Exec-/Plugin-Approvals, Approval-Capability-Builder, Auth-/Profil-Helper und native Routing-/Runtime-Helper | - | `plugin-sdk/reply-runtime` | Gemeinsame Inbound-/Reply-Runtime-Helper, Chunking, Dispatch, Heartbeat und Reply-Planer | - | `plugin-sdk/reply-dispatch-runtime` | Schmale Helper für Antwort-Dispatch/-Finalisierung | - | `plugin-sdk/reply-history` | Gemeinsame Helper für Reply-Historie in kurzen Fenstern wie `buildHistoryContext`, `recordPendingHistoryEntry` und `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/approval-runtime` | Hilfsfunktionen für Exec-/Plugin-Genehmigungen, Builder für Genehmigungsfähigkeiten, Hilfsfunktionen für Auth/Profile sowie native Routing-/Laufzeit-Helfer | + | `plugin-sdk/reply-runtime` | Gemeinsame Laufzeit-Hilfsfunktionen für eingehende Nachrichten/Antworten, Chunking, Dispatch, Heartbeat, Antwortplanung | + | `plugin-sdk/reply-dispatch-runtime` | Schmale Hilfsfunktionen für Dispatch/Abschluss von Antworten | + | `plugin-sdk/reply-history` | Gemeinsame Hilfsfunktionen für den Antwortverlauf in kurzen Fenstern wie `buildHistoryContext`, `recordPendingHistoryEntry` und `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Schmale Helper für Text-/Markdown-Chunking | - | `plugin-sdk/session-store-runtime` | Helper für Pfade und `updated-at` im Session-Store | - | `plugin-sdk/state-paths` | Helper für Pfade zu State-/OAuth-Verzeichnissen | - | `plugin-sdk/routing` | Helper für Route-/Session-Key-/Account-Bindings wie `resolveAgentRoute`, `buildAgentSessionKey` und `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Gemeinsame Helper für Zusammenfassungen des Channel-/Account-Status, Runtime-State-Standards und Metadaten zu Problemen | - | `plugin-sdk/target-resolver-runtime` | Gemeinsame Helper für Target-Resolver | - | `plugin-sdk/string-normalization-runtime` | Helper zur Slug-/String-Normalisierung | - | `plugin-sdk/request-url` | String-URLs aus Fetch-/Request-ähnlichen Eingaben extrahieren | - | `plugin-sdk/run-command` | Zeitgesteuerter Befehls-Runner mit normalisierten stdout-/stderr-Ergebnissen | - | `plugin-sdk/param-readers` | Allgemeine Tool-/CLI-Parameterleser | - | `plugin-sdk/tool-send` | Kanonische Send-Zielfelder aus Tool-Argumenten extrahieren | - | `plugin-sdk/temp-path` | Gemeinsame Helper für temporäre Download-Pfade | - | `plugin-sdk/logging-core` | Helper für Subsystem-Logger und Redaction | - | `plugin-sdk/markdown-table-runtime` | Helper für Markdown-Tabellenmodi | - | `plugin-sdk/json-store` | Kleine Helper zum Lesen/Schreiben von JSON-State | - | `plugin-sdk/file-lock` | Reentrante File-Lock-Helper | - | `plugin-sdk/persistent-dedupe` | Helper für diskgestützten Dedupe-Cache | - | `plugin-sdk/acp-runtime` | Helper für ACP-Runtime/Session und Reply-Dispatch | - | `plugin-sdk/agent-config-primitives` | Schmale Primitive für Agent-Runtime-Konfigurationsschemas | - | `plugin-sdk/boolean-param` | Leser für lockere Boolesche Parameter | - | `plugin-sdk/dangerous-name-runtime` | Helper zur Auflösung von Dangerous-Name-Matching | - | `plugin-sdk/device-bootstrap` | Helper für Device-Bootstrap und Pairing-Token | - | `plugin-sdk/extension-shared` | Gemeinsame Primitive für passive Channels, Status und Ambient-Proxy-Helper | - | `plugin-sdk/models-provider-runtime` | Helper für `/models`-Befehle/Provider-Antworten | - | `plugin-sdk/skill-commands-runtime` | Helper zum Auflisten von Skill-Befehlen | - | `plugin-sdk/native-command-registry` | Helper zum Registrieren/Bauen/Serialisieren nativer Befehle | - | `plugin-sdk/provider-zai-endpoint` | Helper zur Erkennung von Z.AI-Endpoints | - | `plugin-sdk/infra-runtime` | Helper für Systemereignisse/Heartbeat | - | `plugin-sdk/collection-runtime` | Kleine Helper für begrenzte Caches | - | `plugin-sdk/diagnostic-runtime` | Helper für Diagnose-Flags und -Ereignisse | - | `plugin-sdk/error-runtime` | Helper für Fehlergraphen, Formatierung, gemeinsame Fehlerklassifikation, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helper für Wrapped Fetch, Proxy und Pinned-Lookup | - | `plugin-sdk/host-runtime` | Helper zur Normalisierung von Hostnamen und SCP-Hosts | - | `plugin-sdk/retry-runtime` | Helper für Retry-Konfiguration und Retry-Runner | - | `plugin-sdk/agent-runtime` | Helper für Agent-Verzeichnis/Identität/Workspace | - | `plugin-sdk/directory-runtime` | Konfigurationsgestützte Verzeichnisabfrage/-Deduplizierung | + | `plugin-sdk/reply-chunking` | Schmale Hilfsfunktionen für Text-/Markdown-Chunking | + | `plugin-sdk/session-store-runtime` | Hilfsfunktionen für Pfade des Session-Stores und `updated-at` | + | `plugin-sdk/state-paths` | Hilfsfunktionen für State-/OAuth-Verzeichnispfade | + | `plugin-sdk/routing` | Hilfsfunktionen für Route/Session-Key/Konto-Bindung wie `resolveAgentRoute`, `buildAgentSessionKey` und `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Gemeinsame Hilfsfunktionen für Zusammenfassungen des Channel-/Kontostatus, Standardwerte für Laufzeitzustände und Metadaten von Problemen | + | `plugin-sdk/target-resolver-runtime` | Gemeinsame Hilfsfunktionen für Zielauflöser | + | `plugin-sdk/string-normalization-runtime` | Hilfsfunktionen zur Slug-/String-Normalisierung | + | `plugin-sdk/request-url` | Extrahieren von String-URLs aus fetch-/request-ähnlichen Eingaben | + | `plugin-sdk/run-command` | Zeitgesteuerter Befehlsrunner mit normalisierten stdout-/stderr-Ergebnissen | + | `plugin-sdk/param-readers` | Gemeinsame Leser für Tool-/CLI-Parameter | + | `plugin-sdk/tool-payload` | Extrahieren normalisierter Payloads aus Tool-Ergebnisobjekten | + | `plugin-sdk/tool-send` | Extrahieren kanonischer Sendefelder aus Tool-Argumenten | + | `plugin-sdk/temp-path` | Gemeinsame Hilfsfunktionen für temporäre Download-Pfade | + | `plugin-sdk/logging-core` | Hilfsfunktionen für Subsystem-Logger und Redaction | + | `plugin-sdk/markdown-table-runtime` | Hilfsfunktionen für Modi von Markdown-Tabellen | + | `plugin-sdk/json-store` | Kleine Hilfsfunktionen zum Lesen/Schreiben von JSON-Status | + | `plugin-sdk/file-lock` | Reentrant-Hilfsfunktionen für Dateisperren | + | `plugin-sdk/persistent-dedupe` | Hilfsfunktionen für festplattenbasierten Dedupe-Cache | + | `plugin-sdk/acp-runtime` | Hilfsfunktionen für ACP-Laufzeit/Sitzungen und Reply-Dispatch | + | `plugin-sdk/agent-config-primitives` | Schmale Primitive für Agent-Laufzeit-Konfigurationsschemata | + | `plugin-sdk/boolean-param` | Nachsichtiger Leser für boolesche Parameter | + | `plugin-sdk/dangerous-name-runtime` | Hilfsfunktionen zur Auflösung von Treffern bei gefährlichen Namen | + | `plugin-sdk/device-bootstrap` | Hilfsfunktionen für Device-Bootstrap und Pairing-Token | + | `plugin-sdk/extension-shared` | Gemeinsame Primitive für passive Channels, Status und Ambient-Proxy-Helfer | + | `plugin-sdk/models-provider-runtime` | Hilfsfunktionen für Antworten von `/models`-Befehlen/Anbietern | + | `plugin-sdk/skill-commands-runtime` | Hilfsfunktionen zum Auflisten von Skill-Befehlen | + | `plugin-sdk/native-command-registry` | Hilfsfunktionen für Register/Build/Serialisierung nativer Befehle | + | `plugin-sdk/provider-zai-endpoint` | Hilfsfunktionen zur Erkennung von Z.AI-Endpunkten | + | `plugin-sdk/infra-runtime` | Hilfsfunktionen für Systemereignisse/Heartbeat | + | `plugin-sdk/collection-runtime` | Kleine Hilfsfunktionen für begrenzte Caches | + | `plugin-sdk/diagnostic-runtime` | Hilfsfunktionen für Diagnose-Flags und -Ereignisse | + | `plugin-sdk/error-runtime` | Fehlergraph, Formatierung, gemeinsame Hilfsfunktionen zur Fehlerklassifizierung, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Hilfsfunktionen für umhülltes Fetch, Proxy und angeheftetes Lookup | + | `plugin-sdk/host-runtime` | Hilfsfunktionen zur Normalisierung von Hostnamen und SCP-Hosts | + | `plugin-sdk/retry-runtime` | Hilfsfunktionen für Retry-Konfiguration und Retry-Runner | + | `plugin-sdk/agent-runtime` | Hilfsfunktionen für Agent-Verzeichnis/Identität/Workspace | + | `plugin-sdk/directory-runtime` | Konfigurationsgestützte Verzeichnisabfrage/Deduplizierung | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - | Subpath | Key exports | + + | Subpath | Wichtige Exporte | | --- | --- | - | `plugin-sdk/media-runtime` | Gemeinsame Helper für Fetch/Transformation/Speicherung von Medien sowie Builder für Medien-Payloads | - | `plugin-sdk/media-generation-runtime` | Gemeinsame Helper für Media-Generation-Failover, Kandidatenauswahl und Meldungen zu fehlenden Modellen | - | `plugin-sdk/media-understanding` | Provider-Typen für Media Understanding sowie providerseitige Exporte für Bild-/Audio-Helper | - | `plugin-sdk/text-runtime` | Gemeinsame Text-/Markdown-/Logging-Helper wie das Entfernen von für Assistenten sichtbarem Text, Markdown-Render-/Chunking-/Tabellen-Helper, Redaction-Helper, Directive-Tag-Helper und Safe-Text-Utilities | - | `plugin-sdk/text-chunking` | Helper für Chunking ausgehenden Texts | - | `plugin-sdk/speech` | Typen für Sprachprovider sowie providerseitige Helper für Directive, Registry und Validierung | - | `plugin-sdk/speech-core` | Gemeinsame Typen für Sprachprovider, Registry, Directive und Normalisierungs-Helper | - | `plugin-sdk/realtime-transcription` | Typen für Realtime-Transkriptionsprovider und Registry-Helper | - | `plugin-sdk/realtime-voice` | Typen für Realtime-Voice-Provider und Registry-Helper | - | `plugin-sdk/image-generation` | Provider-Typen für Bildgenerierung | - | `plugin-sdk/image-generation-core` | Gemeinsame Typen, Failover-, Auth- und Registry-Helper für Bildgenerierung | - | `plugin-sdk/music-generation` | Typen für Music-Generation-Provider/Requests/Ergebnisse | - | `plugin-sdk/music-generation-core` | Gemeinsame Typen, Failover-Helper, Provider-Lookup und Modellref-Parsing für Music Generation | - | `plugin-sdk/video-generation` | Typen für Video-Generation-Provider/Requests/Ergebnisse | - | `plugin-sdk/video-generation-core` | Gemeinsame Typen, Failover-Helper, Provider-Lookup und Modellref-Parsing für Video Generation | - | `plugin-sdk/webhook-targets` | Registry für Webhook-Ziele und Helper zur Routeninstallation | - | `plugin-sdk/webhook-path` | Helper zur Normalisierung von Webhook-Pfaden | - | `plugin-sdk/web-media` | Gemeinsame Helper zum Laden entfernter/lokaler Medien | - | `plugin-sdk/zod` | Re-exportiertes `zod` für Plugin-SDK-Konsumenten | + | `plugin-sdk/media-runtime` | Gemeinsame Hilfsfunktionen zum Abrufen/Transformieren/Speichern von Medien plus Builder für Medien-Payloads | + | `plugin-sdk/media-generation-runtime` | Gemeinsame Hilfsfunktionen für Failover bei Mediengenerierung, Kandidatenauswahl und Meldungen bei fehlenden Modellen | + | `plugin-sdk/media-understanding` | Typen für Media-Understanding-Anbieter plus anbieterseitige Exporte von Bild-/Audio-Hilfsfunktionen | + | `plugin-sdk/text-runtime` | Gemeinsame Hilfsfunktionen für Text/Markdown/Logging wie das Entfernen von für Assistenten sichtbarem Text, Hilfen zum Rendern/Chunking von Markdown/Tabellen, Redaction-Helfer, Directive-Tag-Helfer und Safe-Text-Dienstprogramme | + | `plugin-sdk/text-chunking` | Hilfsfunktion für ausgehendes Text-Chunking | + | `plugin-sdk/speech` | Typen für Speech-Anbieter plus anbieterseitige Hilfsfunktionen für Direktiven, Register und Validierung | + | `plugin-sdk/speech-core` | Gemeinsame Typen für Speech-Anbieter, Register-, Direktiven- und Normalisierungshilfen | + | `plugin-sdk/realtime-transcription` | Typen für Realtime-Transcription-Anbieter und Register-Hilfen | + | `plugin-sdk/realtime-voice` | Typen für Realtime-Voice-Anbieter und Register-Hilfen | + | `plugin-sdk/image-generation` | Typen für Bildgenerierungsanbieter | + | `plugin-sdk/image-generation-core` | Gemeinsame Typen und Hilfsfunktionen für Bildgenerierung, Failover, Auth und Register | + | `plugin-sdk/music-generation` | Typen für Anbieter/Anfragen/Ergebnisse bei Musikgenerierung | + | `plugin-sdk/music-generation-core` | Gemeinsame Typen und Hilfsfunktionen für Musikgenerierung, Failover, Anbieter-Lookup und Parsing von Modellreferenzen | + | `plugin-sdk/video-generation` | Typen für Anbieter/Anfragen/Ergebnisse bei Videogenerierung | + | `plugin-sdk/video-generation-core` | Gemeinsame Typen und Hilfsfunktionen für Videogenerierung, Failover, Anbieter-Lookup und Parsing von Modellreferenzen | + | `plugin-sdk/webhook-targets` | Register für Webhook-Ziele und Hilfsfunktionen zur Routeninstallation | + | `plugin-sdk/webhook-path` | Hilfsfunktionen zur Normalisierung von Webhook-Pfaden | + | `plugin-sdk/web-media` | Gemeinsame Hilfsfunktionen zum Laden entfernter/lokaler Medien | + | `plugin-sdk/zod` | Re-exportiertes `zod` für Plugin-SDK-Nutzer | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - | Subpath | Key exports | + + | Subpath | Wichtige Exporte | | --- | --- | - | `plugin-sdk/memory-core` | Helper-Oberfläche des gebündelten memory-core für Manager-/Konfigurations-/Datei-/CLI-Helper | - | `plugin-sdk/memory-core-engine-runtime` | Runtime-Fassade für Memory-Index/Search | + | `plugin-sdk/memory-core` | Gebündelte Hilfsoberfläche von memory-core für Manager-/Konfigurations-/Datei-/CLI-Hilfsfunktionen | + | `plugin-sdk/memory-core-engine-runtime` | Laufzeit-Fassade für Memory-Index/Suche | | `plugin-sdk/memory-core-host-engine-foundation` | Exporte der Foundation-Engine des Memory-Hosts | | `plugin-sdk/memory-core-host-engine-embeddings` | Exporte der Embedding-Engine des Memory-Hosts | | `plugin-sdk/memory-core-host-engine-qmd` | Exporte der QMD-Engine des Memory-Hosts | | `plugin-sdk/memory-core-host-engine-storage` | Exporte der Storage-Engine des Memory-Hosts | - | `plugin-sdk/memory-core-host-multimodal` | Multimodale Helper des Memory-Hosts | - | `plugin-sdk/memory-core-host-query` | Query-Helper des Memory-Hosts | - | `plugin-sdk/memory-core-host-secret` | Secret-Helper des Memory-Hosts | - | `plugin-sdk/memory-core-host-events` | Helper für das Event-Journal des Memory-Hosts | - | `plugin-sdk/memory-core-host-status` | Status-Helper des Memory-Hosts | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI-Runtime-Helper des Memory-Hosts | - | `plugin-sdk/memory-core-host-runtime-core` | Core-Runtime-Helper des Memory-Hosts | - | `plugin-sdk/memory-core-host-runtime-files` | Datei-/Runtime-Helper des Memory-Hosts | - | `plugin-sdk/memory-host-core` | Herstellerneutraler Alias für Core-Runtime-Helper des Memory-Hosts | - | `plugin-sdk/memory-host-events` | Herstellerneutraler Alias für Helper für das Event-Journal des Memory-Hosts | - | `plugin-sdk/memory-host-files` | Herstellerneutraler Alias für Datei-/Runtime-Helper des Memory-Hosts | - | `plugin-sdk/memory-host-markdown` | Gemeinsame Helper für verwaltetes Markdown für Memory-nahe Plugins | - | `plugin-sdk/memory-host-search` | Aktive Runtime-Fassade für Memory für den Zugriff auf Search-Manager | - | `plugin-sdk/memory-host-status` | Herstellerneutraler Alias für Status-Helper des Memory-Hosts | - | `plugin-sdk/memory-lancedb` | Helper-Oberfläche des gebündelten memory-lancedb | + | `plugin-sdk/memory-core-host-multimodal` | Multimodale Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-core-host-query` | Query-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-core-host-secret` | Secret-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-core-host-events` | Hilfsfunktionen für Event-Journale des Memory-Hosts | + | `plugin-sdk/memory-core-host-status` | Status-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI-Laufzeit-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-core-host-runtime-core` | Kern-Laufzeit-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-core-host-runtime-files` | Datei-/Laufzeit-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-host-core` | Herstellerneutraler Alias für Kern-Laufzeit-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-host-events` | Herstellerneutraler Alias für Event-Journal-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-host-files` | Herstellerneutraler Alias für Datei-/Laufzeit-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-host-markdown` | Gemeinsame Hilfsfunktionen für verwaltetes Markdown für Memory-nahe Plugins | + | `plugin-sdk/memory-host-search` | Aktive Memory-Laufzeit-Fassade für den Zugriff auf Search-Manager | + | `plugin-sdk/memory-host-status` | Herstellerneutraler Alias für Status-Hilfsfunktionen des Memory-Hosts | + | `plugin-sdk/memory-lancedb` | Gebündelte Hilfsoberfläche von memory-lancedb | - - | Family | Current subpaths | Intended use | + + | Familie | Aktuelle Subpaths | Verwendungszweck | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Support-Helper für das gebündelte Browser-Plugin (`browser-support` bleibt das Kompatibilitäts-Barrel) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Helper-/Runtime-Oberfläche des gebündelten Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Helper-/Runtime-Oberfläche des gebündelten LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Helper-Oberfläche des gebündelten IRC | - | Channelspezifische Helper | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Gebündelte Kompatibilitäts-/Helper-Seams für Channels | - | Auth-/pluginspezifische Helper | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Gebündelte Feature-/Plugin-Helper-Seams; `plugin-sdk/github-copilot-token` exportiert derzeit `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` und `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Unterstützende Hilfsfunktionen für das gebündelte Browser-Plugin (`browser-support` bleibt das Kompatibilitäts-Barrel) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Gebündelte Matrix-Helper-/Laufzeitoberfläche | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Gebündelte LINE-Helper-/Laufzeitoberfläche | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Gebündelte IRC-Helper-Oberfläche | + | Channel-spezifische Hilfsfunktionen | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Gebündelte Channel-Kompatibilitäts-/Helper-Seams | + | Auth-/plugin-spezifische Hilfsfunktionen | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Gebündelte Funktions-/Plugin-Helper-Seams; `plugin-sdk/github-copilot-token` exportiert derzeit `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` und `resolveCopilotApiToken` | ## Registrierungs-API -Der Callback `register(api)` erhält ein `OpenClawPluginApi`-Objekt mit diesen +Der Callback `register(api)` erhält ein Objekt `OpenClawPluginApi` mit diesen Methoden: -### Registrierung von Fähigkeiten +### Fähigkeitsregistrierung -| Method | What it registers | -| ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | Textinferenz (LLM) | -| `api.registerCliBackend(...)` | Lokales CLI-Inferenz-Backend | -| `api.registerChannel(...)` | Nachrichten-Channel | -| `api.registerSpeechProvider(...)` | Text-to-Speech / STT-Synthese | +| Methode | Was registriert wird | +| ------------------------------------------------ | ------------------------------- | +| `api.registerProvider(...)` | Textinferenz (LLM) | +| `api.registerCliBackend(...)` | Lokales CLI-Inferenz-Backend | +| `api.registerChannel(...)` | Messaging-Kanal | +| `api.registerSpeechProvider(...)` | Text-to-Speech / STT-Synthese | | `api.registerRealtimeTranscriptionProvider(...)` | Streaming-Realtime-Transkription | -| `api.registerRealtimeVoiceProvider(...)` | Duplex-Realtime-Voice-Sitzungen | -| `api.registerMediaUnderstandingProvider(...)` | Bild-/Audio-/Videoanalyse | -| `api.registerImageGenerationProvider(...)` | Bildgenerierung | -| `api.registerMusicGenerationProvider(...)` | Musikgenerierung | -| `api.registerVideoGenerationProvider(...)` | Videogenerierung | -| `api.registerWebFetchProvider(...)` | Web-Fetch-/Scrape-Provider | -| `api.registerWebSearchProvider(...)` | Websuche | +| `api.registerRealtimeVoiceProvider(...)` | Duplex-Realtime-Sprachsitzungen | +| `api.registerMediaUnderstandingProvider(...)` | Bild-/Audio-/Videoanalyse | +| `api.registerImageGenerationProvider(...)` | Bildgenerierung | +| `api.registerMusicGenerationProvider(...)` | Musikgenerierung | +| `api.registerVideoGenerationProvider(...)` | Videogenerierung | +| `api.registerWebFetchProvider(...)` | Web-Fetch-/Scrape-Anbieter | +| `api.registerWebSearchProvider(...)` | Websuche | ### Tools und Befehle -| Method | What it registers | +| Methode | Was registriert wird | | ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Agent-Tool (erforderlich oder `{ optional: true }`) | | `api.registerCommand(def)` | Benutzerdefinierter Befehl (umgeht das LLM) | ### Infrastruktur -| Method | What it registers | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Event-Hook | -| `api.registerHttpRoute(params)` | Gateway-HTTP-Endpoint | -| `api.registerGatewayMethod(name, handler)` | Gateway-RPC-Methode | -| `api.registerCli(registrar, opts?)` | CLI-Unterbefehl | -| `api.registerService(service)` | Hintergrunddienst | -| `api.registerInteractiveHandler(registration)` | Interaktiver Handler | -| `api.registerMemoryPromptSupplement(builder)` | Additiver promptnaher Memory-Abschnitt | -| `api.registerMemoryCorpusSupplement(adapter)` | Additiver Memory-Such-/Lese-Korpus | +| Methode | Was registriert wird | +| ---------------------------------------------- | ----------------------------------- | +| `api.registerHook(events, handler, opts?)` | Event-Hook | +| `api.registerHttpRoute(params)` | Gateway-HTTP-Endpunkt | +| `api.registerGatewayMethod(name, handler)` | Gateway-RPC-Methode | +| `api.registerCli(registrar, opts?)` | CLI-Unterbefehl | +| `api.registerService(service)` | Hintergrunddienst | +| `api.registerInteractiveHandler(registration)` | Interaktiver Handler | +| `api.registerMemoryPromptSupplement(builder)` | Additiver promptnaher Memory-Abschnitt | +| `api.registerMemoryCorpusSupplement(adapter)` | Additiver Such-/Lese-Korpus für Memory | -Reservierte Core-Admin-Namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) bleiben immer `operator.admin`, auch wenn ein Plugin versucht, einer -Gateway-Methode einen engeren Scope zuzuweisen. Bevorzugen Sie pluginspezifische Präfixe für +Reservierte Admin-Namespaces des Kerns (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) bleiben immer `operator.admin`, auch wenn ein Plugin versucht, einen +engeren Scope für Gateway-Methoden zuzuweisen. Bevorzugen Sie plugin-spezifische Präfixe für plugin-eigene Methoden. -### Metadaten zur CLI-Registrierung +### CLI-Registrierungsmetadaten `api.registerCli(registrar, opts?)` akzeptiert zwei Arten von Metadaten auf oberster Ebene: - `commands`: explizite Befehlswurzeln, die dem Registrar gehören -- `descriptors`: Parse-Time-Befehlsdeskriptoren für Root-CLI-Hilfe, - Routing und Lazy-CLI-Registrierung von Plugins +- `descriptors`: Parse-Zeit-Befehlsdeskriptoren für Root-CLI-Hilfe, + Routing und lazy CLI-Registrierung von Plugins -Wenn Sie möchten, dass ein Plugin-Befehl im normalen Root-CLI-Pfad lazy geladen bleibt, -stellen Sie `descriptors` bereit, die jede oberste Befehlswurzel abdecken, die durch diesen -Registrar verfügbar gemacht wird. +Wenn ein Plugin-Befehl im normalen Root-CLI-Pfad lazy geladen bleiben soll, +geben Sie `descriptors` an, die jede Befehlswurzel auf oberster Ebene abdecken, die von diesem +Registrar bereitgestellt wird. ```typescript api.registerCli( @@ -378,130 +381,132 @@ api.registerCli( Verwenden Sie `commands` allein nur dann, wenn Sie keine lazy Root-CLI-Registrierung benötigen. Dieser eager-Kompatibilitätspfad wird weiterhin unterstützt, installiert jedoch keine -deskriptorbasierten Platzhalter für parsezeitiges Lazy Loading. +deskriptorbasierten Platzhalter für lazy Laden zur Parse-Zeit. ### Registrierung von CLI-Backends -`api.registerCliBackend(...)` erlaubt es einem Plugin, die Standardkonfiguration für ein lokales -AI-CLI-Backend wie `codex-cli` zu besitzen. +`api.registerCliBackend(...)` ermöglicht es einem Plugin, die Standardkonfiguration für ein lokales +KI-CLI-Backend wie `codex-cli` zu besitzen. -- Die `id` des Backends wird zum Provider-Präfix in Modellreferenzen wie `codex-cli/gpt-5`. +- Die `id` des Backends wird zum Anbieterpräfix in Modellreferenzen wie `codex-cli/gpt-5`. - Die `config` des Backends verwendet dieselbe Form wie `agents.defaults.cliBackends.`. -- Benutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt `agents.defaults.cliBackends.` über dem +- Nutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt `agents.defaults.cliBackends.` über dem Plugin-Standard zusammen, bevor die CLI ausgeführt wird. -- Verwenden Sie `normalizeConfig`, wenn ein Backend nach dem Zusammenführen Kompatibilitäts-Umschreibungen benötigt - (zum Beispiel zur Normalisierung alter Flag-Formen). +- Verwenden Sie `normalizeConfig`, wenn ein Backend nach dem Zusammenführen Kompatibilitätsumschreibungen + benötigt (zum Beispiel zur Normalisierung alter Flag-Formen). ### Exklusive Slots -| Method | What it registers | -| ------------------------------------------ | ------------------------------------- | -| `api.registerContextEngine(id, factory)` | Kontext-Engine (jeweils nur eine aktiv) | -| `api.registerMemoryCapability(capability)` | Vereinheitlichte Memory-Fähigkeit | -| `api.registerMemoryPromptSection(builder)` | Builder für Memory-Prompt-Abschnitte | -| `api.registerMemoryFlushPlan(resolver)` | Resolver für Memory-Flush-Pläne | -| `api.registerMemoryRuntime(runtime)` | Memory-Runtime-Adapter | +| Methode | Was registriert wird | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Kontext-Engine (jeweils nur eine aktiv). Der Callback `assemble()` erhält `availableTools` und `citationsMode`, damit die Engine Prompt-Ergänzungen anpassen kann. | +| `api.registerMemoryCapability(capability)` | Einheitliche Memory-Fähigkeit | +| `api.registerMemoryPromptSection(builder)` | Builder für Memory-Prompt-Abschnitte | +| `api.registerMemoryFlushPlan(resolver)` | Resolver für Memory-Flush-Pläne | +| `api.registerMemoryRuntime(runtime)` | Laufzeitadapter für Memory | ### Memory-Embedding-Adapter -| Method | What it registers | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Memory-Embedding-Adapter für das aktive Plugin | +| Methode | Was registriert wird | +| ---------------------------------------------- | ------------------------------------------------ | +| `api.registerMemoryEmbeddingProvider(adapter)` | Memory-Embedding-Adapter für das aktive Plugin | - `registerMemoryCapability` ist die bevorzugte exklusive API für Memory-Plugins. -- `registerMemoryCapability` kann auch `publicArtifacts.listArtifacts(...)` - bereitstellen, damit Begleit-Plugins exportierte Memory-Artefakte über - `openclaw/plugin-sdk/memory-host-core` verwenden können, statt in das private - Layout eines bestimmten Memory-Plugins zu greifen. +- `registerMemoryCapability` kann auch `publicArtifacts.listArtifacts(...)` bereitstellen, + sodass Begleit-Plugins exportierte Memory-Artefakte über + `openclaw/plugin-sdk/memory-host-core` nutzen können, anstatt in ein bestimmtes + privates Layout eines Memory-Plugins zu greifen. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` und `registerMemoryRuntime` sind Legacy-kompatible exklusive APIs für Memory-Plugins. -- `registerMemoryEmbeddingProvider` erlaubt dem aktiven Memory-Plugin, einen - oder mehrere Embedding-Adapter-IDs zu registrieren (zum Beispiel `openai`, `gemini` oder eine benutzerdefinierte plugindefinierte ID). -- Benutzerkonfigurationen wie `agents.defaults.memorySearch.provider` und - `agents.defaults.memorySearch.fallback` werden gegen diese registrierten +- `registerMemoryEmbeddingProvider` erlaubt es dem aktiven Memory-Plugin, einen + oder mehrere Embedding-Adapter-IDs zu registrieren (zum Beispiel `openai`, `gemini` oder eine benutzerdefinierte plugin-definierte ID). +- Nutzerkonfiguration wie `agents.defaults.memorySearch.provider` und + `agents.defaults.memorySearch.fallback` wird gegen diese registrierten Adapter-IDs aufgelöst. -### Ereignisse und Lifecycle +### Ereignisse und Lebenszyklus -| Method | What it does | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Typisierter Lifecycle-Hook | -| `api.onConversationBindingResolved(handler)` | Callback für Konversations-Binding | +| Methode | Was sie tut | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Typisierter Lebenszyklus-Hook | +| `api.onConversationBindingResolved(handler)` | Callback für aufgelöste Konversationsbindung | ### Entscheidungssemantik von Hooks -- `before_tool_call`: Die Rückgabe von `{ block: true }` ist final. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen. -- `before_tool_call`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `block`), nicht als Override. -- `before_install`: Die Rückgabe von `{ block: true }` ist final. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen. -- `before_install`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `block`), nicht als Override. -- `reply_dispatch`: Die Rückgabe von `{ handled: true, ... }` ist final. Sobald ein Handler den Dispatch beansprucht, werden Handler mit niedrigerer Priorität und der Standardpfad für den Modell-Dispatch übersprungen. -- `message_sending`: Die Rückgabe von `{ cancel: true }` ist final. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen. -- `message_sending`: Die Rückgabe von `{ cancel: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `cancel`), nicht als Override. +- `before_tool_call`: Die Rückgabe von `{ block: true }` ist endgültig. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen. +- `before_tool_call`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `block`), nicht als Überschreibung. +- `before_install`: Die Rückgabe von `{ block: true }` ist endgültig. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen. +- `before_install`: Die Rückgabe von `{ block: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `block`), nicht als Überschreibung. +- `reply_dispatch`: Die Rückgabe von `{ handled: true, ... }` ist endgültig. Sobald ein Handler den Dispatch beansprucht, werden Handler mit niedrigerer Priorität und der Standardpfad für den Modelldispatch übersprungen. +- `message_sending`: Die Rückgabe von `{ cancel: true }` ist endgültig. Sobald ein Handler dies setzt, werden Handler mit niedrigerer Priorität übersprungen. +- `message_sending`: Die Rückgabe von `{ cancel: false }` wird als keine Entscheidung behandelt (wie das Weglassen von `cancel`), nicht als Überschreibung. -### Felder des API-Objekts +### API-Objektfelder -| Field | Type | Description | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Plugin-ID | -| `api.name` | `string` | Anzeigename | -| `api.version` | `string?` | Plugin-Version (optional) | -| `api.description` | `string?` | Plugin-Beschreibung (optional) | -| `api.source` | `string` | Plugin-Quellpfad | -| `api.rootDir` | `string?` | Plugin-Root-Verzeichnis (optional) | -| `api.config` | `OpenClawConfig` | Aktueller Konfigurations-Snapshot (aktive In-Memory-Runtime-Snapshot, wenn verfügbar) | -| `api.pluginConfig` | `Record` | Pluginspezifische Konfiguration aus `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Runtime-Helper](/de/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Scoped Logger (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Aktueller Lademodus; `"setup-runtime"` ist das leichtgewichtige Fenster vor dem vollständigen Entry für Start/Setup | -| `api.resolvePath(input)` | `(string) => string` | Pfad relativ zum Plugin-Root auflösen | +| Feld | Typ | Beschreibung | +| ------------------------ | -------------------------- | --------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Plugin-ID | +| `api.name` | `string` | Anzeigename | +| `api.version` | `string?` | Plugin-Version (optional) | +| `api.description` | `string?` | Plugin-Beschreibung (optional) | +| `api.source` | `string` | Quellpfad des Plugins | +| `api.rootDir` | `string?` | Root-Verzeichnis des Plugins (optional) | +| `api.config` | `OpenClawConfig` | Aktueller Konfigurations-Snapshot (aktiver In-Memory-Laufzeit-Snapshot, wenn verfügbar) | +| `api.pluginConfig` | `Record` | Plugin-spezifische Konfiguration aus `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Laufzeit-Hilfsfunktionen](/de/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Bereichsgebundener Logger (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Aktueller Lademodus; `"setup-runtime"` ist das leichtgewichtige Start-/Einrichtungsfenster vor dem vollständigen Entry | +| `api.resolvePath(input)` | `(string) => string` | Löst einen Pfad relativ zur Plugin-Wurzel auf | -## Interne Modulkonvention +## Konvention für interne Module Verwenden Sie innerhalb Ihres Plugins lokale Barrel-Dateien für interne Importe: ``` my-plugin/ api.ts # Öffentliche Exporte für externe Konsumenten - runtime-api.ts # Interne Runtime-Exporte + runtime-api.ts # Nur interne Laufzeit-Exporte index.ts # Plugin-Einstiegspunkt - setup-entry.ts # Leichtgewichtiger setup-only-Einstiegspunkt (optional) + setup-entry.ts # Leichtgewichtiger nur-für-Setup-Einstiegspunkt (optional) ``` - Importieren Sie Ihr eigenes Plugin in Produktionscode niemals über `openclaw/plugin-sdk/`. - Leiten Sie interne Importe über `./api.ts` oder + Importieren Sie Ihr eigenes Plugin niemals über `openclaw/plugin-sdk/` + aus Produktionscode. Leiten Sie interne Importe über `./api.ts` oder `./runtime-api.ts`. Der SDK-Pfad ist nur der externe Vertrag. -Facadengeladene öffentliche Oberflächen gebündelter Plugins (`api.ts`, `runtime-api.ts`, +Öffentliche Oberflächen gebündelter Plugins mit geladener Fassade (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` und ähnliche öffentliche Entry-Dateien) bevorzugen jetzt den -aktiven Runtime-Konfigurations-Snapshot, wenn OpenClaw bereits läuft. Wenn noch kein Runtime- -Snapshot existiert, greifen sie auf die auf der Festplatte aufgelöste Konfigurationsdatei zurück. +aktiven Laufzeit-Konfigurations-Snapshot, wenn OpenClaw bereits läuft. Falls noch kein Laufzeit- +Snapshot existiert, greifen sie auf die auf dem Datenträger aufgelöste Konfigurationsdatei zurück. -Provider-Plugins können auch ein schmales pluginlokales Vertrags-Barrel bereitstellen, wenn ein -Helper absichtlich providerspezifisch ist und noch nicht in einen generischen SDK-Unterpfad gehört. Aktuelles gebündeltes Beispiel: Der Anthropic-Provider hält seine Claude- -Stream-Helper in seiner eigenen öffentlichen `api.ts`-/`contract-api.ts`-Seam, statt Anthropic-Beta-Header und `service_tier`-Logik in einen generischen -`plugin-sdk/*`-Vertrag zu überführen. +Anbieter-Plugins können auch ein schmales pluginlokales Vertrags-Barrel bereitstellen, wenn ein +Helper absichtlich anbieterspezifisch ist und noch nicht in einen generischen SDK- +Subpath gehört. Aktuelles gebündeltes Beispiel: Der Anthropic-Anbieter behält seine Claude- +Stream-Helfer in seinem eigenen öffentlichen `api.ts`- / `contract-api.ts`-Seam, anstatt +Anthropic-Beta-Header- und `service_tier`-Logik in einen generischen +`plugin-sdk/*`-Vertrag zu übernehmen. Weitere aktuelle gebündelte Beispiele: -- `@openclaw/openai-provider`: `api.ts` exportiert Provider-Builder, - Standardmodell-Helper und Realtime-Provider-Builder -- `@openclaw/openrouter-provider`: `api.ts` exportiert den Provider-Builder sowie - Helper für Onboarding/Konfiguration +- `@openclaw/openai-provider`: `api.ts` exportiert Anbieter-Builder, + Hilfsfunktionen für Standardmodelle und Builder für Realtime-Anbieter +- `@openclaw/openrouter-provider`: `api.ts` exportiert den Anbieter-Builder sowie + Hilfsfunktionen für Onboarding/Konfiguration - Produktionscode von Extensions sollte außerdem Importe von `openclaw/plugin-sdk/` - vermeiden. Wenn ein Helper wirklich gemeinsam genutzt wird, überführen Sie ihn in einen neutralen SDK-Unterpfad + Produktionscode von Erweiterungen sollte außerdem Importe von `openclaw/plugin-sdk/` + vermeiden. Wenn eine Hilfsfunktion wirklich gemeinsam genutzt wird, heben Sie sie in einen neutralen SDK-Subpath wie `openclaw/plugin-sdk/speech`, `.../provider-model-shared` oder eine andere - fähigkeitsorientierte Oberfläche, statt zwei Plugins miteinander zu koppeln. + fähigkeitsorientierte Oberfläche an, anstatt zwei Plugins miteinander zu koppeln. -## Zugehörig +## Verwandt -- [Einstiegspunkte](/de/plugins/sdk-entrypoints) — Optionen für `definePluginEntry` und `defineChannelPluginEntry` -- [Runtime-Helper](/de/plugins/sdk-runtime) — vollständige Referenz des Namespace `api.runtime` -- [Setup und Konfiguration](/de/plugins/sdk-setup) — Paketierung, Manifeste, Konfigurationsschemas -- [Testing](/de/plugins/sdk-testing) — Test-Utilities und Lint-Regeln -- [SDK-Migration](/de/plugins/sdk-migration) — Migration von veralteten Oberflächen -- [Plugin-Interna](/de/plugins/architecture) — detaillierte Architektur und Fähigkeitsmodell +- [Entry Points](/de/plugins/sdk-entrypoints) — Optionen für `definePluginEntry` und `defineChannelPluginEntry` +- [Runtime Helpers](/de/plugins/sdk-runtime) — vollständige Referenz für den Namespace `api.runtime` +- [Setup and Config](/de/plugins/sdk-setup) — Paketierung, Manifeste, Konfigurationsschemata +- [Testing](/de/plugins/sdk-testing) — Testdienstprogramme und Lint-Regeln +- [SDK Migration](/de/plugins/sdk-migration) — Migration von veralteten Oberflächen +- [Plugin Internals](/de/plugins/architecture) — tiefergehende Architektur und Fähigkeitsmodell diff --git a/docs/de/plugins/sdk-provider-plugins.md b/docs/de/plugins/sdk-provider-plugins.md index 8087fbabb..4dd0f2f65 100644 --- a/docs/de/plugins/sdk-provider-plugins.md +++ b/docs/de/plugins/sdk-provider-plugins.md @@ -1,33 +1,33 @@ --- read_when: - Sie erstellen ein neues Modell-Provider-Plugin - - Sie möchten OpenClaw einen OpenAI-kompatiblen Proxy oder ein benutzerdefiniertes LLM hinzufügen - - Sie müssen Provider-Auth, Kataloge und Laufzeit-Hooks verstehen + - Sie möchten einen OpenAI-kompatiblen Proxy oder ein benutzerdefiniertes LLM zu OpenClaw hinzufügen + - Sie müssen Provider-Authentifizierung, Kataloge und Laufzeit-Hooks verstehen sidebarTitle: Provider Plugins summary: Schritt-für-Schritt-Anleitung zum Erstellen eines Modell-Provider-Plugins für OpenClaw title: Provider-Plugins erstellen x-i18n: - generated_at: "2026-04-07T06:19:03Z" + generated_at: "2026-04-09T01:31:16Z" model: gpt-5.4 provider: openai - source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990 + source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # Provider-Plugins erstellen -Diese Anleitung führt Sie durch das Erstellen eines Provider-Plugins, das OpenClaw einen Modell-Provider -(LLM) hinzufügt. Am Ende verfügen Sie über einen Provider mit Modellkatalog, -API-Key-Auth und dynamischer Modellauflösung. +Diese Anleitung führt Sie durch das Erstellen eines Provider-Plugins, das einen Modell-Provider +(LLM) zu OpenClaw hinzufügt. Am Ende verfügen Sie über einen Provider mit Modellkatalog, +API-Schlüssel-Authentifizierung und dynamischer Modellauflösung. - Wenn Sie bisher noch kein OpenClaw-Plugin erstellt haben, lesen Sie zuerst - [Erste Schritte](/de/plugins/building-plugins) für die grundlegende Paket- - Struktur und die Manifest-Einrichtung. + Wenn Sie noch nie zuvor ein OpenClaw-Plugin erstellt haben, lesen Sie zuerst + [Getting Started](/de/plugins/building-plugins), um sich mit der grundlegenden Paketstruktur + und der Manifest-Einrichtung vertraut zu machen. -## Walkthrough +## Anleitung @@ -65,6 +65,9 @@ API-Key-Auth und dynamischer Modellauflösung. "providerAuthEnvVars": { "acme-ai": ["ACME_AI_API_KEY"] }, + "providerAuthAliases": { + "acme-ai-coding": "acme-ai" + }, "providerAuthChoices": [ { "provider": "acme-ai", @@ -87,9 +90,10 @@ API-Key-Auth und dynamischer Modellauflösung. Das Manifest deklariert `providerAuthEnvVars`, damit OpenClaw - Anmeldedaten erkennen kann, ohne die Laufzeit Ihres Plugins zu laden. `modelSupport` ist optional - und ermöglicht OpenClaw, Ihr Provider-Plugin anhand von Kurzform-Modell-IDs - wie `acme-large` automatisch zu laden, bevor Laufzeit-Hooks existieren. Wenn Sie den + Anmeldedaten erkennen kann, ohne die Laufzeit Ihres Plugins zu laden. Fügen Sie `providerAuthAliases` + hinzu, wenn eine Provider-Variante die Authentifizierung einer anderen Provider-ID wiederverwenden soll. `modelSupport` + ist optional und ermöglicht es OpenClaw, Ihr Provider-Plugin automatisch aus Kurzform- + Modell-IDs wie `acme-large` zu laden, bevor Laufzeit-Hooks existieren. Wenn Sie den Provider auf ClawHub veröffentlichen, sind diese Felder `openclaw.compat` und `openclaw.build` in `package.json` erforderlich. @@ -167,13 +171,13 @@ API-Key-Auth und dynamischer Modellauflösung. }); ``` - Das ist ein funktionierender Provider. Benutzer können jetzt - `openclaw onboard --acme-ai-api-key ` ausführen und - `acme-ai/acme-large` als ihr Modell auswählen. + Das ist ein funktionierender Provider. Benutzer können nun + `openclaw onboard --acme-ai-api-key ` verwenden und + `acme-ai/acme-large` als Modell auswählen. - Für gebündelte Provider, die nur einen einzelnen Text-Provider mit API-Key- - Auth plus eine einzelne kataloggestützte Laufzeit registrieren, bevorzugen Sie den engeren - Helper `defineSingleProviderPluginEntry(...)`: + Für gebündelte Provider, die nur einen Text-Provider mit API-Key- + Authentifizierung plus eine einzelne kataloggestützte Laufzeit registrieren, sollten Sie bevorzugt + den schmaleren Helper `defineSingleProviderPluginEntry(...)` verwenden: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -208,20 +212,20 @@ API-Key-Auth und dynamischer Modellauflösung. }); ``` - Wenn Ihr Auth-Flow während des Onboardings zusätzlich `models.providers.*`, Aliase und - das Standardmodell des Agenten patchen muss, verwenden Sie die Preset-Helper aus - `openclaw/plugin-sdk/provider-onboard`. Die engsten Helper sind + Wenn Ihr Authentifizierungsablauf während des Onboardings außerdem + `models.providers.*`, Aliasse und das Standardmodell des Agenten anpassen muss, verwenden Sie die Preset-Helper aus + `openclaw/plugin-sdk/provider-onboard`. Die schmalsten Helper sind `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` und `createModelCatalogPresetAppliers(...)`. - Wenn der native Endpunkt eines Providers gestreamte Usage-Blöcke auf dem - normalen Transport `openai-completions` unterstützt, bevorzugen Sie die gemeinsam genutzten Katalog-Helper in - `openclaw/plugin-sdk/provider-catalog-shared`, statt Provider-ID-Prüfungen - hart zu codieren. `supportsNativeStreamingUsageCompat(...)` und - `applyProviderNativeStreamingUsageCompat(...)` erkennen Unterstützung anhand der - Endpoint-Capability-Map, sodass auch native Moonshot-/DashScope-artige Endpunkte - aktiviert werden, selbst wenn ein Plugin eine benutzerdefinierte Provider-ID verwendet. + Wenn ein nativer Endpunkt eines Providers gestreamte Nutzungsblöcke auf dem + normalen Transport `openai-completions` unterstützt, verwenden Sie bevorzugt die gemeinsamen Katalog-Helper in + `openclaw/plugin-sdk/provider-catalog-shared`, anstatt Prüfungen auf Provider-IDs hart zu codieren. + `supportsNativeStreamingUsageCompat(...)` und + `applyProviderNativeStreamingUsageCompat(...)` erkennen die Unterstützung anhand der + Endpunkt-Fähigkeitszuordnung, sodass native Moonshot-/DashScope-artige Endpunkte weiterhin + opt-in können, selbst wenn ein Plugin eine benutzerdefinierte Provider-ID verwendet. @@ -248,17 +252,17 @@ API-Key-Auth und dynamischer Modellauflösung. }); ``` - Wenn die Auflösung einen Netzwerkaufruf erfordert, verwenden Sie `prepareDynamicModel` für asynchrones - Aufwärmen — `resolveDynamicModel` wird nach dessen Abschluss erneut ausgeführt. + Wenn für die Auflösung ein Netzwerkaufruf erforderlich ist, verwenden Sie `prepareDynamicModel` für asynchrones + Aufwärmen — `resolveDynamicModel` wird nach Abschluss erneut ausgeführt. Die meisten Provider benötigen nur `catalog` + `resolveDynamicModel`. Fügen Sie Hooks - schrittweise hinzu, je nach Anforderungen Ihres Providers. + schrittweise hinzu, wenn Ihr Provider sie benötigt. - Gemeinsam genutzte Helper-Builder decken jetzt die häufigsten Familien für Replay und Tool-Kompatibilität - ab, sodass Plugins normalerweise nicht jeden Hook einzeln verdrahten müssen: + Gemeinsame Helper-Builder decken jetzt die häufigsten Familien für Replay/Tool-Kompatibilität + ab, sodass Plugins normalerweise nicht jeden Hook einzeln manuell verdrahten müssen: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -278,15 +282,15 @@ API-Key-Auth und dynamischer Modellauflösung. }); ``` - Derzeit verfügbare Replay-Familien: + Heute verfügbare Replay-Familien: - | Family | Was eingebunden wird | + | Family | Was sie verdrahtet | | --- | --- | - | `openai-compatible` | Gemeinsam genutzte Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transporte, einschließlich Bereinigung von Tool-Call-IDs, Korrekturen für Assistant-first-Reihenfolge und generischer Gemini-Turn-Validierung dort, wo der Transport sie benötigt | - | `anthropic-by-model` | Claude-bewusste Replay-Richtlinie, gewählt nach `modelId`, sodass Transporte für Anthropic-Nachrichten nur dann Claude-spezifische Bereinigung von Thinking-Blöcken erhalten, wenn das aufgelöste Modell tatsächlich eine Claude-ID ist | - | `google-gemini` | Native Gemini-Replay-Richtlinie plus Bootstrap-Replay-Bereinigung und getaggter Reasoning-Output-Modus | - | `passthrough-gemini` | Bereinigung von Gemini-Thought-Signatures für Gemini-Modelle, die über OpenAI-kompatible Proxy-Transporte laufen; aktiviert keine native Gemini-Replay-Validierung oder Bootstrap-Umschreibungen | - | `hybrid-anthropic-openai` | Hybride Richtlinie für Provider, die in einem Plugin Oberflächen für Anthropic-Nachrichten und OpenAI-kompatible Modelle mischen; das optionale Verwerfen von Thinking-Blöcken nur für Claude bleibt auf die Anthropic-Seite beschränkt | + | `openai-compatible` | Gemeinsame Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transporte, einschließlich Bereinigung von Tool-Call-IDs, Korrekturen der Assistant-First-Reihenfolge und generischer Gemini-Turn-Validierung, wo der Transport sie benötigt | + | `anthropic-by-model` | Claude-bewusste Replay-Richtlinie, ausgewählt über `modelId`, sodass Transports vom Typ Anthropic Messages nur dann Claude-spezifische Bereinigung von Thinking-Blöcken erhalten, wenn das aufgelöste Modell tatsächlich eine Claude-ID ist | + | `google-gemini` | Native Gemini-Replay-Richtlinie plus Bootstrap-Replay-Bereinigung und Modus für getaggte Reasoning-Ausgabe | + | `passthrough-gemini` | Bereinigung der Gemini-Thought-Signatur für Gemini-Modelle, die über OpenAI-kompatible Proxy-Transporte laufen; aktiviert keine native Gemini-Replay-Validierung oder Bootstrap-Umschreibungen | + | `hybrid-anthropic-openai` | Hybride Richtlinie für Provider, die Anthropic-Message- und OpenAI-kompatible Modelloberflächen in einem Plugin kombinieren; optionales Entfernen von Claude-only-Thinking-Blöcken bleibt auf die Anthropic-Seite beschränkt | Reale gebündelte Beispiele: @@ -296,16 +300,16 @@ API-Key-Auth und dynamischer Modellauflösung. - `minimax`: `hybrid-anthropic-openai` - `moonshot`, `ollama`, `xai` und `zai`: `openai-compatible` - Derzeit verfügbare Stream-Familien: + Heute verfügbare Stream-Familien: - | Family | Was eingebunden wird | + | Family | Was sie verdrahtet | | --- | --- | - | `google-thinking` | Normalisierung von Gemini-Thinking-Payloads auf dem gemeinsam genutzten Stream-Pfad | - | `kilocode-thinking` | Kilo-Reasoning-Wrapper auf dem gemeinsam genutzten Proxy-Stream-Pfad, wobei `kilo/auto` und nicht unterstützte Proxy-Reasoning-IDs injiziertes Thinking überspringen | - | `moonshot-thinking` | Zuordnung von nativen Moonshot-Thinking-Payloads im Binärformat aus Konfiguration + `/think`-Level | - | `minimax-fast-mode` | Umschreibung von MiniMax-Fast-Mode-Modellen auf dem gemeinsam genutzten Stream-Pfad | - | `openai-responses-defaults` | Gemeinsam genutzte native OpenAI-/Codex-Responses-Wrapper: Attribution-Header, `/fast`/`serviceTier`, Text-Verbosity, native Codex-Web-Suche, Payload-Shaping für Reasoning-Kompatibilität und Kontextverwaltung für Responses | - | `openrouter-thinking` | OpenRouter-Reasoning-Wrapper für Proxy-Routen, wobei Überspringen bei nicht unterstützten Modellen/`auto` zentral behandelt wird | + | `google-thinking` | Normalisierung der Gemini-Thinking-Payload auf dem gemeinsamen Stream-Pfad | + | `kilocode-thinking` | Kilo-Reasoning-Wrapper auf dem gemeinsamen Proxy-Stream-Pfad, wobei `kilo/auto` und nicht unterstützte Proxy-Reasoning-IDs das injizierte Thinking überspringen | + | `moonshot-thinking` | Abbildung der nativen binären Thinking-Payload von Moonshot aus Konfiguration + `/think`-Level | + | `minimax-fast-mode` | Umschreiben von MiniMax-Fast-Mode-Modellen auf dem gemeinsamen Stream-Pfad | + | `openai-responses-defaults` | Gemeinsame Wrapper für native OpenAI/Codex Responses: Attributions-Header, `/fast`/`serviceTier`, Text-Verbosity, native Codex-Websuche, kompatible Payload-Gestaltung für Reasoning und Kontextverwaltung für Responses | + | `openrouter-thinking` | OpenRouter-Reasoning-Wrapper für Proxy-Routen, wobei übersprungene nicht unterstützte Modelle/`auto` zentral behandelt werden | | `tool-stream-default-on` | Standardmäßig aktivierter `tool_stream`-Wrapper für Provider wie Z.AI, die Tool-Streaming wünschen, sofern es nicht explizit deaktiviert wird | Reale gebündelte Beispiele: @@ -318,74 +322,75 @@ API-Key-Auth und dynamischer Modellauflösung. - `openrouter`: `openrouter-thinking` - `zai`: `tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` exportiert außerdem das Enum für Replay-Familien - plus die gemeinsam genutzten Helper, aus denen diese Familien aufgebaut sind. Häufige öffentliche - Exporte sind: + `openclaw/plugin-sdk/provider-model-shared` exportiert außerdem die Replay-Family- + Enum sowie die gemeinsamen Helper, aus denen diese Familien aufgebaut sind. Häufige öffentliche + Exporte umfassen: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - gemeinsam genutzte Replay-Builder wie `buildOpenAICompatibleReplayPolicy(...)`, + - gemeinsame Replay-Builder wie `buildOpenAICompatibleReplayPolicy(...)`, `buildAnthropicReplayPolicyForModel(...)`, `buildGoogleGeminiReplayPolicy(...)` und `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - Gemini-Replay-Helper wie `sanitizeGoogleGeminiReplayHistory(...)` und `resolveTaggedReasoningOutputMode()` - - Endpoint-/Modell-Helper wie `resolveProviderEndpoint(...)`, + - Endpunkt-/Modell-Helper wie `resolveProviderEndpoint(...)`, `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` und `normalizeNativeXaiModelId(...)` `openclaw/plugin-sdk/provider-stream` stellt sowohl den Family-Builder als - auch die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Häufige öffentliche Exporte - sind: + auch die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Häufige öffentliche + Exporte umfassen: - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` - `composeProviderStreamWrappers(...)` - - gemeinsam genutzte OpenAI-/Codex-Wrapper wie + - gemeinsame OpenAI-/Codex-Wrapper wie `createOpenAIAttributionHeadersWrapper(...)`, `createOpenAIFastModeWrapper(...)`, `createOpenAIServiceTierWrapper(...)`, `createOpenAIResponsesContextManagementWrapper(...)` und `createCodexNativeWebSearchWrapper(...)` - - gemeinsam genutzte Proxy-/Provider-Wrapper wie `createOpenRouterWrapper(...)`, + - gemeinsame Proxy-/Provider-Wrapper wie `createOpenRouterWrapper(...)`, `createToolStreamWrapper(...)` und `createMinimaxFastModeWrapper(...)` - Einige Stream-Helper bleiben absichtlich providerlokal. Aktuelles gebündeltes + Einige Stream-Helper bleiben absichtlich Provider-lokal. Aktuelles gebündeltes Beispiel: `@openclaw/anthropic-provider` exportiert `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` und die - Low-Level-Builder für Anthropic-Wrapper über seinen öffentlichen Seam `api.ts` / + Low-Level-Builder für Anthropic-Wrapper über die öffentliche Abgrenzung `api.ts` / `contract-api.ts`. Diese Helper bleiben Anthropic-spezifisch, weil - sie auch die Behandlung von Claude-OAuth-Betas und `context1m`-Gating kodieren. + sie außerdem Claude-OAuth-Beta-Handling und `context1m`-Gating codieren. - Andere gebündelte Provider halten transportspezifische Wrapper ebenfalls lokal, wenn - das Verhalten nicht sauber familienübergreifend geteilt wird. Aktuelles Beispiel: das - gebündelte xAI-Plugin hält das native Shaping von xAI-Responses in seinem eigenen - `wrapStreamFn`, einschließlich Umschreibungen von `/fast`-Aliasen, standardmäßigem `tool_stream`, - Bereinigung nicht unterstützter Strict-Tools und Entfernung von xAI-spezifischen Reasoning-Payloads. + Andere gebündelte Provider behalten ebenfalls transport-spezifische Wrapper lokal, wenn + das Verhalten nicht sauber zwischen Familien geteilt werden kann. Aktuelles Beispiel: Das + gebündelte xAI-Plugin hält die native Gestaltung von xAI Responses in seinem eigenen + `wrapStreamFn`, einschließlich Umschreiben von `/fast`-Aliasen, standardmäßigem `tool_stream`, + Bereinigung nicht unterstützter strikter Tools und Entfernen + xAI-spezifischer Reasoning-Payloads. - `openclaw/plugin-sdk/provider-tools` stellt derzeit eine gemeinsam genutzte - Tool-Schema-Familie plus gemeinsam genutzte Schema-/Kompatibilitäts-Helper bereit: + `openclaw/plugin-sdk/provider-tools` stellt derzeit eine gemeinsame + Tool-Schema-Familie plus gemeinsame Schema-/Kompatibilitäts-Helper bereit: - - `ProviderToolCompatFamily` dokumentiert das heute gemeinsam genutzte Family-Inventar. - - `buildProviderToolCompatFamilyHooks("gemini")` verdrahtet die Bereinigung von Gemini-Schemata - + Diagnosen für Provider, die Gemini-sichere Tool-Schemata benötigen. + - `ProviderToolCompatFamily` dokumentiert heute das gemeinsame Family-Inventar. + - `buildProviderToolCompatFamilyHooks("gemini")` verdrahtet die Bereinigung und + Diagnose von Gemini-Schemata für Provider, die Gemini-sichere Tool-Schemata benötigen. - `normalizeGeminiToolSchemas(...)` und `inspectGeminiToolSchemas(...)` - sind die zugrunde liegenden öffentlichen Gemini-Schema-Helper. - - `resolveXaiModelCompatPatch()` gibt den gebündelten xAI-Kompatibilitäts-Patch zurück: + sind die zugrunde liegenden öffentlichen Helper für Gemini-Schemata. + - `resolveXaiModelCompatPatch()` gibt den gebündelten xAI-Kompatibilitätspatch zurück: `toolSchemaProfile: "xai"`, nicht unterstützte Schema-Schlüsselwörter, native - `web_search`-Unterstützung und HTML-Entity-Dekodierung für Argumente von Tool-Calls. - - `applyXaiModelCompat(model)` wendet denselben xAI-Kompatibilitäts-Patch auf ein + Unterstützung für `web_search` und Decodierung von Tool-Call-Argumenten mit HTML-Entities. + - `applyXaiModelCompat(model)` wendet denselben xAI-Kompatibilitätspatch auf ein aufgelöstes Modell an, bevor es den Runner erreicht. Reales gebündeltes Beispiel: Das xAI-Plugin verwendet `normalizeResolvedModel` plus - `contributeResolvedModelCompat`, um diese Kompatibilitäts-Metadaten dem Provider zuzuordnen, - anstatt xAI-Regeln im Core hart zu codieren. + `contributeResolvedModelCompat`, damit diese Kompatibilitätsmetadaten dem + Provider zugeordnet bleiben, anstatt xAI-Regeln hart im Core zu codieren. - Dasselbe Paket-Root-Muster unterstützt auch andere gebündelte Provider: + Dasselbe Muster am Paket-Root unterstützt auch andere gebündelte Provider: - `@openclaw/openai-provider`: `api.ts` exportiert Provider-Builder, - Helper für Standardmodelle und Builder für Realtime-Provider + Standardmodell-Helper und Builder für Realtime-Provider - `@openclaw/openrouter-provider`: `api.ts` exportiert den Provider-Builder plus Onboarding-/Konfigurations-Helper @@ -422,8 +427,8 @@ API-Key-Auth und dynamischer Modellauflösung. }, ``` - - Für Provider, die native Request-/Session-Header oder Metadaten auf + + Für Provider, die native Request-/Sitzungs-Header oder Metadaten auf generischen HTTP- oder WebSocket-Transporten benötigen: ```typescript @@ -444,8 +449,8 @@ API-Key-Auth und dynamischer Modellauflösung. }), ``` - - Für Provider, die Usage-/Abrechnungsdaten bereitstellen: + + Für Provider, die Nutzungs-/Abrechnungsdaten bereitstellen: ```typescript resolveUsageAuth: async (ctx) => { @@ -462,80 +467,80 @@ API-Key-Auth und dynamischer Modellauflösung. OpenClaw ruft Hooks in dieser Reihenfolge auf. Die meisten Provider verwenden nur 2-3: - | # | Hook | Wann verwenden | + | # | Hook | Wann er verwendet wird | | --- | --- | --- | - | 1 | `catalog` | Modellkatalog oder Standardwerte für baseUrl | - | 2 | `applyConfigDefaults` | Providereigene globale Standardwerte während der Materialisierung der Konfiguration | - | 3 | `normalizeModelId` | Bereinigung von Legacy-/Preview-Modell-ID-Aliasen vor dem Lookup | - | 4 | `normalizeTransport` | Bereinigung von `api` / `baseUrl` für Provider-Familien vor der generischen Modellzusammenstellung | + | 1 | `catalog` | Modellkatalog oder Standardwerte für Base-URL | + | 2 | `applyConfigDefaults` | Provider-eigene globale Standardwerte während der Materialisierung der Konfiguration | + | 3 | `normalizeModelId` | Bereinigung veralteter/Vorschau-Aliasse von Modell-IDs vor der Suche | + | 4 | `normalizeTransport` | Bereinigung von `api` / `baseUrl` für die Provider-Familie vor der generischen Modellerstellung | | 5 | `normalizeConfig` | `models.providers.`-Konfiguration normalisieren | | 6 | `applyNativeStreamingUsageCompat` | Native Streaming-Usage-Kompatibilitäts-Umschreibungen für Konfigurations-Provider | - | 7 | `resolveConfigApiKey` | Providereigene Auflösung von Auth über Env-Marker | - | 8 | `resolveSyntheticAuth` | Synthetische Auth aus lokalem/self-hosted oder konfigurationsgestütztem Kontext | - | 9 | `shouldDeferSyntheticProfileAuth` | Platzhalter synthetischer gespeicherter Profile hinter Env-/Konfigurations-Auth niedriger priorisieren | + | 7 | `resolveConfigApiKey` | Provider-eigene Auflösung von Env-Marker-Authentifizierung | + | 8 | `resolveSyntheticAuth` | Synthetische Authentifizierung lokal/selbst gehostet oder konfigurationsgestützt | + | 9 | `shouldDeferSyntheticProfileAuth` | Platziert synthetische Platzhalter für gespeicherte Profile hinter Env-/Konfigurations-Authentifizierung | | 10 | `resolveDynamicModel` | Beliebige Upstream-Modell-IDs akzeptieren | | 11 | `prepareDynamicModel` | Asynchrones Abrufen von Metadaten vor der Auflösung | - | 12 | `normalizeResolvedModel` | Transport-Umschreibungen vor dem Runner | + | 12 | `normalizeResolvedModel` | Umschreibungen des Transports vor dem Runner | Hinweise zum Laufzeit-Fallback: - - `normalizeConfig` prüft zuerst den passenden Provider und dann andere - hookfähige Provider-Plugins, bis eines die Konfiguration tatsächlich ändert. - Wenn kein Provider-Hook einen unterstützten Google-Family-Konfigurationseintrag umschreibt, wird weiterhin - der gebündelte Google-Konfigurations-Normalizer angewendet. + - `normalizeConfig` prüft zuerst den passenden Provider, dann andere + Hook-fähige Provider-Plugins, bis eines die Konfiguration tatsächlich ändert. + Wenn kein Provider-Hook einen unterstützten Google-Family-Konfigurationseintrag umschreibt, + wird weiterhin der gebündelte Google-Konfigurations-Normalisierer angewendet. - `resolveConfigApiKey` verwendet den Provider-Hook, wenn er bereitgestellt wird. Der gebündelte - Pfad `amazon-bedrock` hat hier zusätzlich einen integrierten AWS-Env-Marker-Resolver, - obwohl Bedrock-Laufzeit-Auth selbst weiterhin die Standardkette des AWS-SDK verwendet. - | 13 | `contributeResolvedModelCompat` | Kompatibilitäts-Flags für Vendor-Modelle hinter einem anderen kompatiblen Transport | - | 14 | `capabilities` | Legacy-Bag mit statischen Fähigkeiten; nur zur Kompatibilität | - | 15 | `normalizeToolSchemas` | Providereigene Bereinigung von Tool-Schemata vor der Registrierung | - | 16 | `inspectToolSchemas` | Providereigene Diagnosen für Tool-Schemata | - | 17 | `resolveReasoningOutputMode` | Vertrag für getaggten vs. nativen Reasoning-Output | + Pfad `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, + auch wenn Bedrock-Laufzeit-Authentifizierung selbst weiterhin die Standardkette des AWS SDK verwendet. + | 13 | `contributeResolvedModelCompat` | Kompatibilitäts-Flags für Anbietermodelle hinter einem anderen kompatiblen Transport | + | 14 | `capabilities` | Veralteter statischer Capability-Bag; nur zur Kompatibilität | + | 15 | `normalizeToolSchemas` | Provider-eigene Bereinigung von Tool-Schemata vor der Registrierung | + | 16 | `inspectToolSchemas` | Provider-eigene Diagnose für Tool-Schemata | + | 17 | `resolveReasoningOutputMode` | Vertrag für getaggte vs. native Reasoning-Ausgabe | | 18 | `prepareExtraParams` | Standard-Request-Parameter | | 19 | `createStreamFn` | Vollständig benutzerdefinierter StreamFn-Transport | | 20 | `wrapStreamFn` | Benutzerdefinierte Header-/Body-Wrapper auf dem normalen Stream-Pfad | | 21 | `resolveTransportTurnState` | Native Header/Metadaten pro Turn | - | 22 | `resolveWebSocketSessionPolicy` | Native WS-Session-Header/Cool-down | + | 22 | `resolveWebSocketSessionPolicy` | Native WS-Sitzungs-Header/Cool-down | | 23 | `formatApiKey` | Benutzerdefinierte Form von Laufzeit-Tokens | - | 24 | `refreshOAuth` | Benutzerdefinierter OAuth-Refresh | - | 25 | `buildAuthDoctorHint` | Hinweise zur Reparatur von Auth | - | 26 | `matchesContextOverflowError` | Providereigene Erkennung von Überläufen | - | 27 | `classifyFailoverReason` | Providereigene Klassifizierung von Ratenlimit/Überlastung | + | 24 | `refreshOAuth` | Benutzerdefiniertes OAuth-Refresh | + | 25 | `buildAuthDoctorHint` | Hinweise zur Reparatur der Authentifizierung | + | 26 | `matchesContextOverflowError` | Provider-eigene Erkennung von Kontextüberlauf | + | 27 | `classifyFailoverReason` | Provider-eigene Klassifizierung von Ratenlimit-/Überlastgründen | | 28 | `isCacheTtlEligible` | TTL-Gating für Prompt-Cache | - | 29 | `buildMissingAuthMessage` | Benutzerdefinierter Hinweis bei fehlender Auth | + | 29 | `buildMissingAuthMessage` | Benutzerdefinierter Hinweis bei fehlender Authentifizierung | | 30 | `suppressBuiltInModel` | Veraltete Upstream-Zeilen ausblenden | | 31 | `augmentModelCatalog` | Synthetische Zeilen für Vorwärtskompatibilität | | 32 | `isBinaryThinking` | Binäres Thinking an/aus | | 33 | `supportsXHighThinking` | Unterstützung für `xhigh`-Reasoning | | 34 | `resolveDefaultThinkingLevel` | Standardrichtlinie für `/think` | - | 35 | `isModernModelRef` | Abgleich für Live-/Smoke-Modelle | + | 35 | `isModernModelRef` | Live-/Smoke-Matching von Modellen | | 36 | `prepareRuntimeAuth` | Token-Austausch vor der Inferenz | - | 37 | `resolveUsageAuth` | Benutzerdefiniertes Parsen von Usage-Anmeldedaten | - | 38 | `fetchUsageSnapshot` | Benutzerdefinierter Usage-Endpunkt | - | 39 | `createEmbeddingProvider` | Providereigener Embedding-Adapter für Memory/Search | - | 40 | `buildReplayPolicy` | Benutzerdefinierte Replay-/Kompaktierungsrichtlinie für Transkripte | - | 41 | `sanitizeReplayHistory` | Providerspezifische Replay-Umschreibungen nach generischer Bereinigung | + | 37 | `resolveUsageAuth` | Benutzerdefiniertes Parsen von Nutzungsanmeldedaten | + | 38 | `fetchUsageSnapshot` | Benutzerdefinierter Nutzungsendpunkt | + | 39 | `createEmbeddingProvider` | Provider-eigener Embedding-Adapter für Speicher/Suche | + | 40 | `buildReplayPolicy` | Benutzerdefinierte Richtlinie für Transcript-Replay/-Kompaktierung | + | 41 | `sanitizeReplayHistory` | Provider-spezifische Replay-Umschreibungen nach generischer Bereinigung | | 42 | `validateReplayTurns` | Strikte Validierung von Replay-Turns vor dem eingebetteten Runner | - | 43 | `onModelSelected` | Callback nach Auswahl (z. B. Telemetrie) | + | 43 | `onModelSelected` | Callback nach der Auswahl (z. B. Telemetrie) | Hinweis zum Prompt-Tuning: - - `resolveSystemPromptContribution` ermöglicht einem Provider, cachebewusste - System-Prompt-Hinweise für eine Modellfamilie einzuschleusen. Bevorzugen Sie dies statt + - `resolveSystemPromptContribution` erlaubt es einem Provider, cache-bewusste + System-Prompt-Hinweise für eine Modelfamilie zu injizieren. Verwenden Sie dies bevorzugt gegenüber `before_prompt_build`, wenn das Verhalten zu einer Provider-/Modellfamilie gehört und die stabile/dynamische Cache-Aufteilung erhalten bleiben soll. - Detaillierte Beschreibungen und praxisnahe Beispiele finden Sie unter - [Interna: Provider-Laufzeit-Hooks](/de/plugins/architecture#provider-runtime-hooks). + Ausführliche Beschreibungen und Praxisbeispiele finden Sie unter + [Internals: Provider Runtime Hooks](/de/plugins/architecture#provider-runtime-hooks). - Ein Provider-Plugin kann zusätzlich zu Text-Inferenz auch Speech, Realtime-Transkription, Realtime- - Voice, Medienverständnis, Bildgenerierung, Videogenerierung, Web-Fetch - und Web-Suche registrieren: + Ein Provider-Plugin kann zusätzlich zu Textinferenz Sprachsynthese, Echtzeittranskription, + Echtzeitstimme, Medienverständnis, Bildgenerierung, Videogenerierung, Web-Abruf + und Websuche registrieren: ```typescript register(api) { @@ -643,20 +648,20 @@ API-Key-Auth und dynamischer Modellauflösung. } ``` - OpenClaw klassifiziert dies als **Hybrid-Capability**-Plugin. Dies ist das + OpenClaw klassifiziert dies als Plugin mit **hybrid-capability**. Dies ist das empfohlene Muster für Unternehmens-Plugins (ein Plugin pro Anbieter). Siehe - [Interna: Eigentum an Fähigkeiten](/de/plugins/architecture#capability-ownership-model). + [Internals: Capability Ownership](/de/plugins/architecture#capability-ownership-model). - Für Videogenerierung bevorzugen Sie die oben gezeigte modusb ewusste Form der Fähigkeiten: + Für Videogenerierung bevorzugen Sie die oben gezeigte, modusbewusste Fähigkeitsform: `generate`, `imageToVideo` und `videoToVideo`. Flache aggregierte Felder wie - `maxInputImages`, `maxInputVideos` und `maxDurationSeconds` reichen nicht aus, - um die Unterstützung von Transformationsmodi oder deaktivierte Modi sauber zu bewerben. + `maxInputImages`, `maxInputVideos` und `maxDurationSeconds` reichen + nicht aus, um Unterstützung für Transformationsmodi oder deaktivierte Modi sauber anzugeben. Provider für Musikgenerierung sollten demselben Muster folgen: - `generate` für promptbasierte Generierung und `edit` für referenzbildbasierte + `generate` für reine Prompt-basierte Generierung und `edit` für referenzbildbasierte Generierung. Flache aggregierte Felder wie `maxInputImages`, - `supportsLyrics` und `supportsFormat` reichen nicht aus, um Edit- - Unterstützung zu bewerben; explizite Blöcke `generate` / `edit` sind der erwartete Vertrag. + `supportsLyrics` und `supportsFormat` reichen nicht aus, um Unterstützung für + Bearbeitung anzugeben; explizite Blöcke `generate` / `edit` sind der erwartete Vertrag. @@ -697,14 +702,14 @@ API-Key-Auth und dynamischer Modellauflösung. ## Auf ClawHub veröffentlichen -Provider-Plugins werden genauso veröffentlicht wie jedes andere externe Code-Plugin: +Provider-Plugins werden auf dieselbe Weise veröffentlicht wie jedes andere externe Code-Plugin: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Verwenden Sie hier nicht den veralteten Alias zum Veröffentlichen nur für Skills; Plugin-Pakete sollten +Verwenden Sie hier nicht den veralteten skill-only-Publish-Alias; Plugin-Pakete sollten `clawhub package publish` verwenden. ## Dateistruktur @@ -712,28 +717,28 @@ Verwenden Sie hier nicht den veralteten Alias zum Veröffentlichen nur für Skil ``` /acme-ai/ ├── package.json # openclaw.providers-Metadaten -├── openclaw.plugin.json # Manifest mit providerAuthEnvVars +├── openclaw.plugin.json # Manifest mit Provider-Authentifizierungsmetadaten ├── index.ts # definePluginEntry + registerProvider └── src/ ├── provider.test.ts # Tests - └── usage.ts # Usage-Endpunkt (optional) + └── usage.ts # Nutzungsendpunkt (optional) ``` -## Referenz für Katalogreihenfolge +## Referenz zur Katalogreihenfolge -`catalog.order` steuert, wann Ihr Katalog relativ zu eingebauten +`catalog.order` steuert, wann Ihr Katalog im Verhältnis zu eingebauten Providern zusammengeführt wird: -| Order | Wann | Anwendungsfall | -| --------- | ------------- | --------------------------------------------- | -| `simple` | Erster Durchlauf | Einfache Provider mit API-Key | -| `profile` | Nach simple | Provider, die von Auth-Profilen abhängen | -| `paired` | Nach profile | Mehrere zusammengehörige Einträge synthetisieren | -| `late` | Letzter Durchlauf | Bestehende Provider überschreiben (gewinnt bei Kollision) | +| Order | Wann | Anwendungsfall | +| --------- | ------------- | ---------------------------------------------- | +| `simple` | Erster Durchlauf | Einfache Provider mit API-Schlüssel | +| `profile` | Nach simple | Provider, die von Authentifizierungsprofilen abhängen | +| `paired` | Nach profile | Mehrere verwandte Einträge synthetisieren | +| `late` | Letzter Durchlauf | Vorhandene Provider überschreiben (gewinnt bei Kollision) | ## Nächste Schritte -- [Channel Plugins](/de/plugins/sdk-channel-plugins) — wenn Ihr Plugin auch einen Channel bereitstellt +- [Channel Plugins](/de/plugins/sdk-channel-plugins) — wenn Ihr Plugin auch einen Kanal bereitstellt - [SDK Runtime](/de/plugins/sdk-runtime) — `api.runtime`-Helper (TTS, Suche, Subagent) -- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Referenz für Subpfad-Importe -- [Plugin-Interna](/de/plugins/architecture#provider-runtime-hooks) — Hook-Details und gebündelte Beispiele +- [SDK Overview](/de/plugins/sdk-overview) — vollständige Referenz für Subpath-Importe +- [Plugin Internals](/de/plugins/architecture#provider-runtime-hooks) — Hook-Details und gebündelte Beispiele diff --git a/docs/de/providers/google.md b/docs/de/providers/google.md index 30749176b..6e2b2a8f5 100644 --- a/docs/de/providers/google.md +++ b/docs/de/providers/google.md @@ -1,14 +1,14 @@ --- read_when: - Sie möchten Google-Gemini-Modelle mit OpenClaw verwenden - - Sie benötigen den Auth-Flow für API-Schlüssel oder OAuth + - Sie benötigen den Auth-Ablauf mit API-Schlüssel oder OAuth summary: Einrichtung von Google Gemini (API-Schlüssel + OAuth, Bildgenerierung, Medienverständnis, Websuche) title: Google (Gemini) x-i18n: - generated_at: "2026-04-08T02:17:34Z" + generated_at: "2026-04-09T01:30:26Z" model: gpt-5.4 provider: openai - source_hash: e9e558f5ce35c853e0240350be9a1890460c5f7f7fd30b05813a656497dee516 + source_hash: fad2ff68987301bd86145fa6e10de8c7b38d5bd5dbcd13db9c883f7f5b9a4e01 source_path: providers/google.md workflow: 15 --- @@ -19,20 +19,20 @@ Das Google-Plugin bietet Zugriff auf Gemini-Modelle über Google AI Studio sowie Bildgenerierung, Medienverständnis (Bild/Audio/Video) und Websuche über Gemini Grounding. -- Anbieter: `google` +- Provider: `google` - Auth: `GEMINI_API_KEY` oder `GOOGLE_API_KEY` - API: Google Gemini API -- Alternativer Anbieter: `google-gemini-cli` (OAuth) +- Alternativer Provider: `google-gemini-cli` (OAuth) ## Schnellstart -1. API-Schlüssel festlegen: +1. Setzen Sie den API-Schlüssel: ```bash openclaw onboard --auth-choice gemini-api-key ``` -2. Ein Standardmodell festlegen: +2. Legen Sie ein Standardmodell fest: ```json5 { @@ -55,13 +55,13 @@ openclaw onboard --non-interactive \ ## OAuth (Gemini CLI) -Ein alternativer Anbieter `google-gemini-cli` verwendet PKCE-OAuth statt eines API- -Schlüssels. Dies ist eine inoffizielle Integration; einige Nutzer berichten von Konto- -einschränkungen. Verwendung auf eigenes Risiko. +Ein alternativer Provider `google-gemini-cli` verwendet PKCE-OAuth statt eines API- +Schlüssels. Dies ist eine inoffizielle Integration; einige Benutzer berichten von +Kontoeinschränkungen. Die Nutzung erfolgt auf eigenes Risiko. - Standardmodell: `google-gemini-cli/gemini-3-flash-preview` - Alias: `gemini-cli` -- Installationsvoraussetzung: lokale Gemini CLI als `gemini` verfügbar +- Installationsvoraussetzung: lokale Gemini CLI, verfügbar als `gemini` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` - Anmeldung: @@ -77,46 +77,49 @@ Umgebungsvariablen: (Oder die Varianten `GEMINI_CLI_*`.) -Wenn Gemini-CLI-OAuth-Anfragen nach der Anmeldung fehlschlagen, setzen Sie +Wenn OAuth-Anfragen der Gemini CLI nach der Anmeldung fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder `GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host und versuchen Sie es erneut. -Wenn die Anmeldung fehlschlägt, bevor der Browser-Flow startet, stellen Sie sicher, dass der lokale Befehl `gemini` -installiert und auf `PATH` verfügbar ist. OpenClaw unterstützt sowohl Homebrew-Installationen +Wenn die Anmeldung fehlschlägt, bevor der Browser-Ablauf startet, stellen Sie sicher, dass der lokale Befehl `gemini` +installiert ist und sich auf `PATH` befindet. OpenClaw unterstützt sowohl Homebrew-Installationen als auch globale npm-Installationen, einschließlich gängiger Windows-/npm-Layouts. -Hinweise zur JSON-Nutzung von Gemini CLI: +Hinweise zur JSON-Nutzung der Gemini CLI: -- Antworttext stammt aus dem JSON-Feld `response` der CLI. -- Die Nutzung fällt auf `stats` zurück, wenn die CLI `usage` leer lässt. -- `stats.cached` wird zu OpenClaw-`cacheRead` normalisiert. -- Wenn `stats.input` fehlt, leitet OpenClaw die Eingabetokens aus +- Der Antworttext stammt aus dem JSON-Feld `response` der CLI. +- Die Nutzung greift auf `stats` zurück, wenn die CLI `usage` leer lässt. +- `stats.cached` wird in OpenClaw-`cacheRead` normalisiert. +- Wenn `stats.input` fehlt, leitet OpenClaw die Eingabe-Token aus `stats.input_tokens - stats.cached` ab. ## Fähigkeiten -| Fähigkeit | Unterstützt | -| ---------------------- | ---------------- | -| Chat Completions | Ja | -| Bildgenerierung | Ja | -| Musikgenerierung | Ja | -| Bildverständnis | Ja | -| Audiotranskription | Ja | -| Videoverständnis | Ja | -| Websuche (Grounding) | Ja | -| Thinking/Reasoning | Ja (Gemini 3.1+) | +| Fähigkeit | Unterstützt | +| ---------------------- | ----------------- | +| Chat-Completions | Ja | +| Bildgenerierung | Ja | +| Musikgenerierung | Ja | +| Bildverständnis | Ja | +| Audio-Transkription | Ja | +| Videoverständnis | Ja | +| Websuche (Grounding) | Ja | +| Thinking/Reasoning | Ja (Gemini 3.1+) | +| Gemma 4-Modelle | Ja | -## Direkte Wiederverwendung des Gemini-Cache +Gemma 4-Modelle (zum Beispiel `gemma-4-26b-a4b-it`) unterstützen den Thinking-Modus. OpenClaw schreibt `thinkingBudget` für Gemma 4 in ein unterstütztes Google-`thinkingLevel` um. Wenn Thinking auf `off` gesetzt wird, bleibt Thinking deaktiviert, statt auf `MINIMAL` abgebildet zu werden. -Bei direkten Gemini-API-Ausführungen (`api: "google-generative-ai"`) reicht OpenClaw jetzt -einen konfigurierten `cachedContent`-Handle an Gemini-Anfragen durch. +## Direkte Wiederverwendung des Gemini-Caches -- Konfigurieren Sie pro Modell oder globalen Parametern entweder - `cachedContent` oder das Legacy-`cached_content` +Für direkte Gemini-API-Läufe (`api: "google-generative-ai"`) gibt OpenClaw jetzt +einen konfigurierten `cachedContent`-Handle an Gemini-Anfragen weiter. + +- Konfigurieren Sie pro Modell oder global Parameter mit entweder + `cachedContent` oder dem Legacy-Wert `cached_content` - Wenn beide vorhanden sind, hat `cachedContent` Vorrang - Beispielwert: `cachedContents/prebuilt-context` -- Die Nutzung bei Gemini-Cache-Treffern wird in OpenClaw als `cacheRead` aus - Upstream-`cachedContentTokenCount` normalisiert +- Die Nutzung bei Gemini-Cache-Treffern wird in OpenClaw-`cacheRead` aus + `cachedContentTokenCount` des Upstreams normalisiert Beispiel: @@ -138,19 +141,19 @@ Beispiel: ## Bildgenerierung -Der gebündelte Bildgenerierungsanbieter `google` verwendet standardmäßig +Der gebündelte Provider `google` für Bildgenerierung verwendet standardmäßig `google/gemini-3.1-flash-image-preview`. -- Unterstützt außerdem `google/gemini-3-pro-image-preview` -- Generieren: bis zu 4 Bilder pro Anfrage +- Unterstützt auch `google/gemini-3-pro-image-preview` +- Generierung: bis zu 4 Bilder pro Anfrage - Bearbeitungsmodus: aktiviert, bis zu 5 Eingabebilder - Geometriesteuerungen: `size`, `aspectRatio` und `resolution` -Der OAuth-only-Anbieter `google-gemini-cli` ist eine separate Oberfläche +Der nur per OAuth nutzbare Provider `google-gemini-cli` ist eine separate Oberfläche für Textinferenz. Bildgenerierung, Medienverständnis und Gemini Grounding bleiben auf -der Anbieter-ID `google`. +der Provider-ID `google`. -So verwenden Sie Google als Standardanbieter für Bilder: +So verwenden Sie Google als Standardprovider für Bilder: ```json5 { @@ -164,20 +167,20 @@ So verwenden Sie Google als Standardanbieter für Bilder: } ``` -Unter [Image Generation](/de/tools/image-generation) finden Sie die gemeinsam genutzten Tool- -Parameter, die Anbieterauswahl und das Failover-Verhalten. +Unter [Bildgenerierung](/de/tools/image-generation) finden Sie die gemeinsamen Werkzeug- +Parameter, die Providerauswahl und das Failover-Verhalten. ## Videogenerierung -Das gebündelte Plugin `google` registriert auch Videogenerierung über das gemeinsame -Tool `video_generate`. +Das gebündelte Plugin `google` registriert außerdem Videogenerierung über das gemeinsame +Werkzeug `video_generate`. - Standard-Videomodell: `google/veo-3.1-fast-generate-preview` -- Modi: Text-zu-Video, Bild-zu-Video und Abläufe mit einzelner Video-Referenz +- Modi: Text-zu-Video-, Bild-zu-Video- und Referenzabläufe mit einem einzelnen Video - Unterstützt `aspectRatio`, `resolution` und `audio` - Aktuelle Begrenzung der Dauer: **4 bis 8 Sekunden** -So verwenden Sie Google als Standardanbieter für Videos: +So verwenden Sie Google als Standardprovider für Videos: ```json5 { @@ -191,22 +194,22 @@ So verwenden Sie Google als Standardanbieter für Videos: } ``` -Unter [Video Generation](/de/tools/video-generation) finden Sie die gemeinsam genutzten Tool- -Parameter, die Anbieterauswahl und das Failover-Verhalten. +Unter [Videogenerierung](/de/tools/video-generation) finden Sie die gemeinsamen Werkzeug- +Parameter, die Providerauswahl und das Failover-Verhalten. ## Musikgenerierung -Das gebündelte Plugin `google` registriert auch Musikgenerierung über das gemeinsame -Tool `music_generate`. +Das gebündelte Plugin `google` registriert außerdem Musikgenerierung über das gemeinsame +Werkzeug `music_generate`. - Standard-Musikmodell: `google/lyria-3-clip-preview` -- Unterstützt außerdem `google/lyria-3-pro-preview` +- Unterstützt auch `google/lyria-3-pro-preview` - Prompt-Steuerungen: `lyrics` und `instrumental` - Ausgabeformat: standardmäßig `mp3`, zusätzlich `wav` bei `google/lyria-3-pro-preview` - Referenzeingaben: bis zu 10 Bilder -- Sitzungsgebundene Ausführungen werden über den gemeinsamen Task-/Status-Ablauf entkoppelt, einschließlich `action: "status"` +- Sitzungsbasierte Läufe werden über den gemeinsamen Aufgaben-/Statusablauf abgekoppelt, einschließlich `action: "status"` -So verwenden Sie Google als Standardanbieter für Musik: +So verwenden Sie Google als Standardprovider für Musik: ```json5 { @@ -220,11 +223,11 @@ So verwenden Sie Google als Standardanbieter für Musik: } ``` -Unter [Music Generation](/de/tools/music-generation) finden Sie die gemeinsam genutzten Tool- -Parameter, die Anbieterauswahl und das Failover-Verhalten. +Unter [Musikgenerierung](/de/tools/music-generation) finden Sie die gemeinsamen Werkzeug- +Parameter, die Providerauswahl und das Failover-Verhalten. ## Hinweis zur Umgebung -Wenn das Gateway als Daemon läuft (launchd/systemd), stellen Sie sicher, dass `GEMINI_API_KEY` -für diesen Prozess verfügbar ist (zum Beispiel in `~/.openclaw/.env` oder über +Wenn das Gateway als Daemon (launchd/systemd) läuft, stellen Sie sicher, dass `GEMINI_API_KEY` +diesem Prozess zur Verfügung steht (zum Beispiel in `~/.openclaw/.env` oder über `env.shellEnv`). diff --git a/docs/de/providers/inferrs.md b/docs/de/providers/inferrs.md index 7ce197dee..1a9d3f45d 100644 --- a/docs/de/providers/inferrs.md +++ b/docs/de/providers/inferrs.md @@ -1,15 +1,15 @@ --- read_when: - - OpenClaw soll gegen einen lokalen inferrs-Server ausgeführt werden - - Gemma oder ein anderes Modell wird über inferrs bereitgestellt - - Die exakten OpenClaw-Kompatibilitäts-Flags für inferrs werden benötigt + - Sie möchten OpenClaw gegen einen lokalen inferrs-Server ausführen + - Sie stellen Gemma oder ein anderes Modell über inferrs bereit + - Sie benötigen die genauen OpenClaw-Kompatibilitäts-Flags für inferrs summary: OpenClaw über inferrs ausführen (OpenAI-kompatibler lokaler Server) title: inferrs x-i18n: - generated_at: "2026-04-08T02:17:50Z" + generated_at: "2026-04-09T01:30:16Z" model: gpt-5.4 provider: openai - source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6 + source_hash: 03b9d5a9935c75fd369068bacb7807a5308cd0bd74303b664227fb664c3a2098 source_path: providers/inferrs.md workflow: 15 --- @@ -20,30 +20,30 @@ x-i18n: OpenAI-kompatiblen `/v1`-API bereitstellen. OpenClaw funktioniert mit `inferrs` über den generischen Pfad `openai-completions`. -`inferrs` sollte derzeit am besten als benutzerdefiniertes self-hosted +`inferrs` sollte derzeit am besten als benutzerdefiniertes selbstgehostetes OpenAI-kompatibles Backend behandelt werden, nicht als dediziertes OpenClaw-Provider-Plugin. ## Schnellstart -1. `inferrs` mit einem Modell starten. +1. Starten Sie `inferrs` mit einem Modell. Beispiel: ```bash -inferrs serve gg-hf-gg/gemma-4-E2B-it \ +inferrs serve google/gemma-4-E2B-it \ --host 127.0.0.1 \ --port 8080 \ --device metal ``` -2. Prüfen, ob der Server erreichbar ist. +2. Verifizieren Sie, dass der Server erreichbar ist. ```bash curl http://127.0.0.1:8080/health curl http://127.0.0.1:8080/v1/models ``` -3. Einen expliziten OpenClaw-Provider-Eintrag hinzufügen und das Standardmodell darauf verweisen lassen. +3. Fügen Sie einen expliziten OpenClaw-Provider-Eintrag hinzu und verweisen Sie Ihr Standardmodell darauf. ## Vollständiges Konfigurationsbeispiel @@ -53,9 +53,9 @@ Dieses Beispiel verwendet Gemma 4 auf einem lokalen `inferrs`-Server. { agents: { defaults: { - model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" }, + model: { primary: "inferrs/google/gemma-4-E2B-it" }, models: { - "inferrs/gg-hf-gg/gemma-4-E2B-it": { + "inferrs/google/gemma-4-E2B-it": { alias: "Gemma 4 (inferrs)", }, }, @@ -70,7 +70,7 @@ Dieses Beispiel verwendet Gemma 4 auf einem lokalen `inferrs`-Server. api: "openai-completions", models: [ { - id: "gg-hf-gg/gemma-4-E2B-it", + id: "google/gemma-4-E2B-it", name: "Gemma 4 E2B (inferrs)", reasoning: false, input: ["text"], @@ -90,16 +90,16 @@ Dieses Beispiel verwendet Gemma 4 auf einem lokalen `inferrs`-Server. ## Warum `requiresStringContent` wichtig ist -Einige Chat-Completions-Routen von `inferrs` akzeptieren nur String- -`messages[].content` und keine strukturierten Content-Part-Arrays. +Einige `inferrs`-Chat-Completions-Routen akzeptieren nur String-Werte in +`messages[].content`, nicht strukturierte Inhalts-Arrays mit Content-Parts. -Wenn OpenClaw-Läufe mit einem Fehler wie diesem fehlschlagen: +Wenn OpenClaw-Ausführungen mit einem Fehler wie diesem fehlschlagen: ```text messages[1].content: invalid type: sequence, expected a string ``` -setze: +setzen Sie: ```json5 compat: { @@ -107,16 +107,15 @@ compat: { } ``` -OpenClaw reduziert dann reine Text-Content-Parts vor dem Senden der -Anfrage auf einfache Strings. +OpenClaw reduziert dann reine Text-Content-Parts vor dem Senden der Anfrage auf einfache Strings. -## Vorbehalt zu Gemma und Tool-Schema +## Gemma- und Tool-Schema-Einschränkung -Einige aktuelle Kombinationen aus `inferrs` + Gemma akzeptieren kleine direkte -`/v1/chat/completions`-Anfragen, schlagen aber bei vollständigen OpenClaw-Agent-Runtime- -Turns weiterhin fehl. +Einige aktuelle Kombinationen aus `inferrs` und Gemma akzeptieren kleine direkte +`/v1/chat/completions`-Anfragen, schlagen aber trotzdem bei vollständigen OpenClaw-Agent-Runtime- +Turns fehl. -Wenn das passiert, versuche zuerst Folgendes: +Wenn das passiert, versuchen Sie zuerst Folgendes: ```json5 compat: { @@ -125,56 +124,55 @@ compat: { } ``` -Dadurch wird die Tool-Schema-Oberfläche von OpenClaw für das Modell deaktiviert und der Prompt- -Druck auf strengeren lokalen Backends kann reduziert werden. +Dadurch wird die Tool-Schema-Oberfläche von OpenClaw für das Modell deaktiviert und der Prompt-Druck +auf strengeren lokalen Backends kann reduziert werden. -Wenn winzige direkte Anfragen weiterhin funktionieren, normale OpenClaw-Agent-Turns aber in `inferrs` -weiterhin abstürzen, liegt das verbleibende Problem normalerweise eher am Verhalten des Upstream- -Modells/Servers als an der Transportschicht von OpenClaw. +Wenn sehr kleine direkte Anfragen weiterhin funktionieren, normale OpenClaw-Agent-Turns aber in +`inferrs` weiterhin abstürzen, liegt das verbleibende Problem normalerweise eher am Upstream-Verhalten von Modell/Server als an der Transportebene von OpenClaw. ## Manueller Smoke-Test -Nach der Konfiguration beide Ebenen testen: +Sobald alles konfiguriert ist, testen Sie beide Ebenen: ```bash curl http://127.0.0.1:8080/v1/chat/completions \ -H 'content-type: application/json' \ - -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' + -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' openclaw infer model run \ - --model inferrs/gg-hf-gg/gemma-4-E2B-it \ + --model inferrs/google/gemma-4-E2B-it \ --prompt "What is 2 + 2? Reply with one short sentence." \ --json ``` -Wenn der erste Befehl funktioniert, der zweite aber fehlschlägt, verwende die Hinweise -zur Fehlerbehebung unten. +Wenn der erste Befehl funktioniert, der zweite aber fehlschlägt, verwenden Sie die unten stehenden +Hinweise zur Fehlerbehebung. ## Fehlerbehebung - `curl /v1/models` schlägt fehl: `inferrs` läuft nicht, ist nicht erreichbar oder nicht an den erwarteten Host/Port gebunden. -- `messages[].content ... expected a string`: setze +- `messages[].content ... expected a string`: setzen Sie `compat.requiresStringContent: true`. - Direkte kleine `/v1/chat/completions`-Aufrufe funktionieren, aber `openclaw infer model run` - schlägt fehl: versuche `compat.supportsTools: false`. -- OpenClaw bekommt keine Schemafehler mehr, aber `inferrs` stürzt bei größeren - Agent-Turns weiterhin ab: behandle dies als Einschränkung von Upstream-`inferrs` oder des Modells und reduziere - den Prompt-Druck oder wechsle Backend/Modell lokal. + schlägt fehl: versuchen Sie `compat.supportsTools: false`. +- OpenClaw erhält keine Schemafehler mehr, aber `inferrs` stürzt bei größeren + Agent-Turns weiterhin ab: behandeln Sie es als Upstream-Einschränkung von `inferrs` oder des Modells und reduzieren Sie + den Prompt-Druck oder wechseln Sie Backend/Modell. -## Proxy-ähnliches Verhalten +## Proxy-artiges Verhalten -`inferrs` wird als proxyähnliches OpenAI-kompatibles `/v1`-Backend behandelt, nicht als +`inferrs` wird als proxy-artiges OpenAI-kompatibles `/v1`-Backend behandelt, nicht als nativer OpenAI-Endpunkt. -- natives request shaping nur für OpenAI gilt hier nicht -- kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise und kein - OpenAI-Reasoning-Compat-Payload-Shaping -- versteckte OpenClaw-Attribution-Header (`originator`, `version`, `User-Agent`) - werden bei benutzerdefinierten `inferrs`-Base-URLs nicht injiziert +- nur für natives OpenAI vorgesehene Anfrageformung gilt hier nicht +- kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise und keine + OpenAI-Reasoning-Kompatibilitäts-Payload-Formung +- versteckte OpenClaw-Attributions-Header (`originator`, `version`, `User-Agent`) + werden bei benutzerdefinierten `inferrs`-Basis-URLs nicht eingefügt ## Siehe auch -- [Lokale Modelle](/de/gateway/local-models) -- [Gateway-Fehlerbehebung](/de/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) -- [Modell-Provider](/de/concepts/model-providers) +- [Local models](/de/gateway/local-models) +- [Gateway troubleshooting](/de/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) +- [Model providers](/de/concepts/model-providers) diff --git a/docs/de/providers/ollama.md b/docs/de/providers/ollama.md index 6ef9c12cb..bcb5776f8 100644 --- a/docs/de/providers/ollama.md +++ b/docs/de/providers/ollama.md @@ -1,24 +1,24 @@ --- read_when: - - OpenClaw soll mit Cloud- oder lokalen Modellen über Ollama ausgeführt werden - - Anleitung für Einrichtung und Konfiguration von Ollama wird benötigt + - Sie möchten OpenClaw mit Cloud- oder lokalen Modellen über Ollama ausführen + - Sie benötigen Anleitungen zur Einrichtung und Konfiguration von Ollama summary: OpenClaw mit Ollama ausführen (Cloud- und lokale Modelle) title: Ollama x-i18n: - generated_at: "2026-04-08T02:18:26Z" + generated_at: "2026-04-09T01:30:50Z" model: gpt-5.4 provider: openai - source_hash: 222ec68f7d4bb29cc7796559ddef1d5059f5159e7a51e2baa3a271ddb3abb716 + source_hash: d3295a7c879d3636a2ffdec05aea6e670e54a990ef52bd9b0cae253bc24aa3f7 source_path: providers/ollama.md workflow: 15 --- # Ollama -Ollama ist eine lokale LLM-Runtime, mit der sich Open-Source-Modelle einfach auf deinem Rechner ausführen lassen. OpenClaw integriert sich mit der nativen API von Ollama (`/api/chat`), unterstützt Streaming und Tool-Aufrufe und kann lokale Ollama-Modelle automatisch erkennen, wenn du dies mit `OLLAMA_API_KEY` (oder einem Auth-Profil) aktivierst und keinen expliziten Eintrag `models.providers.ollama` definierst. +Ollama ist eine lokale LLM-Laufzeitumgebung, mit der sich Open-Source-Modelle einfach auf Ihrem Rechner ausführen lassen. OpenClaw integriert sich mit der nativen API von Ollama (`/api/chat`), unterstützt Streaming und Tool Calling und kann lokale Ollama-Modelle automatisch erkennen, wenn Sie sich mit `OLLAMA_API_KEY` (oder einem Auth-Profil) dafür entscheiden und keinen expliziten Eintrag `models.providers.ollama` definieren. -**Remote-Ollama-Benutzer**: Verwende die OpenAI-kompatible URL `/v1` (`http://host:11434/v1`) nicht mit OpenClaw. Dadurch funktionieren Tool-Aufrufe nicht mehr korrekt, und Modelle können rohes Tool-JSON als Klartext ausgeben. Verwende stattdessen die native Ollama-API-URL: `baseUrl: "http://host:11434"` (ohne `/v1`). +**Remote-Ollama-Benutzer**: Verwenden Sie nicht die OpenAI-kompatible URL `/v1` (`http://host:11434/v1`) mit OpenClaw. Dadurch wird Tool Calling unterbrochen und Modelle können rohes Tool-JSON als Klartext ausgeben. Verwenden Sie stattdessen die native Ollama-API-URL: `baseUrl: "http://host:11434"` (ohne `/v1`). ## Schnellstart @@ -31,13 +31,13 @@ Der schnellste Weg, Ollama einzurichten, ist über das Onboarding: openclaw onboard ``` -Wähle **Ollama** aus der Provider-Liste. Das Onboarding wird: +Wählen Sie **Ollama** aus der Provider-Liste. Das Onboarding wird: -1. Nach der Ollama-Base-URL fragen, unter der deine Instanz erreichbar ist (Standard `http://127.0.0.1:11434`). -2. Zwischen **Cloud + Local** (Cloud-Modelle und lokale Modelle) oder **Local** (nur lokale Modelle) wählen lassen. -3. Einen Browser-Anmeldefluss öffnen, wenn du **Cloud + Local** auswählst und nicht bei ollama.com angemeldet bist. -4. Verfügbare Modelle erkennen und Standards vorschlagen. -5. Das ausgewählte Modell automatisch pullen, wenn es lokal nicht verfügbar ist. +1. nach der Ollama-Basis-URL fragen, unter der Ihre Instanz erreichbar ist (Standard: `http://127.0.0.1:11434`). +2. Ihnen die Wahl zwischen **Cloud + Local** (Cloud-Modelle und lokale Modelle) oder **Local** (nur lokale Modelle) geben. +3. einen Browser-Anmeldefluss öffnen, wenn Sie **Cloud + Local** wählen und nicht bei ollama.com angemeldet sind. +4. verfügbare Modelle erkennen und Standardwerte vorschlagen. +5. das ausgewählte Modell automatisch pullen, wenn es lokal nicht verfügbar ist. Der nicht interaktive Modus wird ebenfalls unterstützt: @@ -47,7 +47,7 @@ openclaw onboard --non-interactive \ --accept-risk ``` -Optional kann eine benutzerdefinierte Base-URL oder ein Modell angegeben werden: +Optional können Sie eine benutzerdefinierte Basis-URL oder ein Modell angeben: ```bash openclaw onboard --non-interactive \ @@ -59,9 +59,9 @@ openclaw onboard --non-interactive \ ### Manuelle Einrichtung -1. Ollama installieren: [https://ollama.com/download](https://ollama.com/download) +1. Installieren Sie Ollama: [https://ollama.com/download](https://ollama.com/download) -2. Ein lokales Modell pullen, wenn du lokale Inferenz verwenden möchtest: +2. Pullen Sie ein lokales Modell, wenn Sie lokale Inferenz verwenden möchten: ```bash ollama pull gemma4 @@ -71,13 +71,13 @@ ollama pull gpt-oss:20b ollama pull llama3.3 ``` -3. Wenn du auch Cloud-Modelle möchtest, melde dich an: +3. Wenn Sie auch Cloud-Modelle möchten, melden Sie sich an: ```bash ollama signin ``` -4. Das Onboarding ausführen und `Ollama` wählen: +4. Führen Sie das Onboarding aus und wählen Sie `Ollama`: ```bash openclaw onboard @@ -92,13 +92,13 @@ OpenClaw schlägt derzeit vor: - lokaler Standard: `gemma4` - Cloud-Standards: `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud` -5. Wenn du die manuelle Einrichtung bevorzugst, aktiviere Ollama direkt für OpenClaw (jeder Wert funktioniert; Ollama benötigt keinen echten Schlüssel): +5. Wenn Sie die manuelle Einrichtung bevorzugen, aktivieren Sie Ollama direkt für OpenClaw (jeder Wert funktioniert; Ollama erfordert keinen echten Schlüssel): ```bash # Umgebungsvariable setzen export OLLAMA_API_KEY="ollama-local" -# Oder in deiner Konfigurationsdatei konfigurieren +# Oder in Ihrer Konfigurationsdatei konfigurieren openclaw config set models.providers.ollama.apiKey "ollama-local" ``` @@ -109,7 +109,7 @@ openclaw models list openclaw models set ollama/gemma4 ``` -7. Oder den Standard in der Konfiguration festlegen: +7. Oder den Standardwert in der Konfiguration setzen: ```json5 { @@ -123,38 +123,39 @@ openclaw models set ollama/gemma4 ## Modellerkennung (impliziter Provider) -Wenn du `OLLAMA_API_KEY` (oder ein Auth-Profil) setzt und **nicht** `models.providers.ollama` definierst, erkennt OpenClaw Modelle von der lokalen Ollama-Instanz unter `http://127.0.0.1:11434`: +Wenn Sie `OLLAMA_API_KEY` (oder ein Auth-Profil) setzen und **keinen** `models.providers.ollama` definieren, erkennt OpenClaw Modelle von der lokalen Ollama-Instanz unter `http://127.0.0.1:11434`: - Fragt `/api/tags` ab -- Verwendet best-effort-`/api/show`-Lookups, um `contextWindow` zu lesen, wenn verfügbar -- Markiert `reasoning` mit einer Heuristik anhand des Modellnamens (`r1`, `reasoning`, `think`) -- Setzt `maxTokens` auf das Standard-Max-Token-Limit von Ollama, das von OpenClaw verwendet wird +- Verwendet best-effort-`/api/show`-Abfragen, um `contextWindow` zu lesen und Fähigkeiten (einschließlich Vision) zu erkennen, wenn verfügbar +- Modelle mit einer durch `/api/show` gemeldeten Fähigkeit `vision` werden als bildfähig markiert (`input: ["text", "image"]`), sodass OpenClaw Bilder für diese Modelle automatisch in den Prompt einfügt +- Markiert `reasoning` mit einer Modellnamen-Heuristik (`r1`, `reasoning`, `think`) +- Setzt `maxTokens` auf das von OpenClaw verwendete Standard-Max-Token-Limit für Ollama - Setzt alle Kosten auf `0` -Dadurch werden manuelle Modelleinträge vermieden, während der Katalog mit der lokalen Ollama-Instanz abgestimmt bleibt. +Dadurch vermeiden Sie manuelle Modelleinträge und halten den Katalog gleichzeitig an die lokale Ollama-Instanz angepasst. -So siehst du, welche Modelle verfügbar sind: +Um zu sehen, welche Modelle verfügbar sind: ```bash ollama list openclaw models list ``` -Um ein neues Modell hinzuzufügen, pulle es einfach mit Ollama: +Um ein neues Modell hinzuzufügen, pullen Sie es einfach mit Ollama: ```bash ollama pull mistral ``` -Das neue Modell wird automatisch erkannt und kann verwendet werden. +Das neue Modell wird automatisch erkannt und ist zur Verwendung verfügbar. -Wenn du `models.providers.ollama` explizit setzt, wird die automatische Erkennung übersprungen, und du musst Modelle manuell definieren (siehe unten). +Wenn Sie `models.providers.ollama` explizit setzen, wird die automatische Erkennung übersprungen und Sie müssen Modelle manuell definieren (siehe unten). ## Konfiguration -### Grundeinrichtung (implizite Erkennung) +### Grundlegende Einrichtung (implizite Erkennung) -Der einfachste Weg, Ollama zu aktivieren, ist per Umgebungsvariable: +Der einfachste Weg, Ollama zu aktivieren, ist über eine Umgebungsvariable: ```bash export OLLAMA_API_KEY="ollama-local" @@ -162,11 +163,11 @@ export OLLAMA_API_KEY="ollama-local" ### Explizite Einrichtung (manuelle Modelle) -Verwende eine explizite Konfiguration, wenn: +Verwenden Sie eine explizite Konfiguration, wenn: - Ollama auf einem anderen Host/Port läuft. -- Du bestimmte Kontextfenster oder Modelllisten erzwingen möchtest. -- Du vollständig manuelle Modelldefinitionen möchtest. +- Sie bestimmte Kontextfenster oder Modelllisten erzwingen möchten. +- Sie vollständig manuelle Modelldefinitionen möchten. ```json5 { @@ -193,9 +194,9 @@ Verwende eine explizite Konfiguration, wenn: } ``` -Wenn `OLLAMA_API_KEY` gesetzt ist, kannst du `apiKey` im Provider-Eintrag weglassen, und OpenClaw füllt ihn für Verfügbarkeitsprüfungen aus. +Wenn `OLLAMA_API_KEY` gesetzt ist, können Sie `apiKey` im Provider-Eintrag weglassen und OpenClaw füllt ihn für Verfügbarkeitsprüfungen aus. -### Benutzerdefinierte Base-URL (explizite Konfiguration) +### Benutzerdefinierte Basis-URL (explizite Konfiguration) Wenn Ollama auf einem anderen Host oder Port läuft (explizite Konfiguration deaktiviert die automatische Erkennung, daher Modelle manuell definieren): @@ -205,8 +206,8 @@ Wenn Ollama auf einem anderen Host oder Port läuft (explizite Konfiguration dea providers: { ollama: { apiKey: "ollama-local", - baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL - api: "ollama", // Set explicitly to guarantee native tool-calling behavior + baseUrl: "http://ollama-host:11434", // Kein /v1 - native Ollama-API-URL verwenden + api: "ollama", // Explizit setzen, um natives Tool-Calling-Verhalten sicherzustellen }, }, }, @@ -214,12 +215,12 @@ Wenn Ollama auf einem anderen Host oder Port läuft (explizite Konfiguration dea ``` -Füge der URL kein `/v1` hinzu. Der Pfad `/v1` verwendet den OpenAI-kompatiblen Modus, in dem Tool-Aufrufe nicht zuverlässig funktionieren. Verwende die Basis-URL von Ollama ohne Pfadsuffix. +Fügen Sie der URL kein `/v1` hinzu. Der Pfad `/v1` verwendet den OpenAI-kompatiblen Modus, in dem Tool Calling nicht zuverlässig ist. Verwenden Sie die Basis-Ollama-URL ohne Pfadsuffix. ### Modellauswahl -Sobald die Konfiguration eingerichtet ist, sind alle deine Ollama-Modelle verfügbar: +Sobald alles konfiguriert ist, sind alle Ihre Ollama-Modelle verfügbar: ```json5 { @@ -236,24 +237,24 @@ Sobald die Konfiguration eingerichtet ist, sind alle deine Ollama-Modelle verfü ## Cloud-Modelle -Cloud-Modelle ermöglichen es dir, in der Cloud gehostete Modelle (zum Beispiel `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`) zusammen mit deinen lokalen Modellen auszuführen. +Mit Cloud-Modellen können Sie Cloud-gehostete Modelle (zum Beispiel `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`) neben Ihren lokalen Modellen ausführen. -Um Cloud-Modelle zu verwenden, wähle während der Einrichtung den Modus **Cloud + Local**. Der Wizard prüft, ob du angemeldet bist, und öffnet bei Bedarf einen Browser-Anmeldefluss. Wenn die Authentifizierung nicht verifiziert werden kann, fällt der Wizard auf Standardwerte für lokale Modelle zurück. +Um Cloud-Modelle zu verwenden, wählen Sie während der Einrichtung den Modus **Cloud + Local**. Der Assistent prüft, ob Sie angemeldet sind, und öffnet bei Bedarf einen Browser-Anmeldefluss. Wenn die Authentifizierung nicht verifiziert werden kann, greift der Assistent auf Standardwerte für lokale Modelle zurück. -Du kannst dich auch direkt unter [ollama.com/signin](https://ollama.com/signin) anmelden. +Sie können sich auch direkt unter [ollama.com/signin](https://ollama.com/signin) anmelden. ## Ollama Web Search -OpenClaw unterstützt auch **Ollama Web Search** als gebündelten `web_search`- -Provider. +OpenClaw unterstützt außerdem **Ollama Web Search** als gebündelten Provider für +`web_search`. -- Verwendet deinen konfigurierten Ollama-Host (`models.providers.ollama.baseUrl`, wenn +- Es verwendet Ihren konfigurierten Ollama-Host (`models.providers.ollama.baseUrl`, wenn gesetzt, andernfalls `http://127.0.0.1:11434`). -- Benötigt keinen Schlüssel. -- Erfordert, dass Ollama läuft und du mit `ollama signin` angemeldet bist. +- Es benötigt keinen Schlüssel. +- Es erfordert, dass Ollama läuft und Sie mit `ollama signin` angemeldet sind. -Wähle **Ollama Web Search** während `openclaw onboard` oder -`openclaw configure --section web`, oder setze: +Wählen Sie **Ollama Web Search** während `openclaw onboard` oder +`openclaw configure --section web`, oder setzen Sie: ```json5 { @@ -267,7 +268,7 @@ Wähle **Ollama Web Search** während `openclaw onboard` oder } ``` -Die vollständigen Details zu Einrichtung und Verhalten findest du unter [Ollama Web Search](/de/tools/ollama-search). +Die vollständigen Details zu Einrichtung und Verhalten finden Sie unter [Ollama Web Search](/de/tools/ollama-search). ## Erweitert @@ -285,15 +286,15 @@ Ollama ist kostenlos und läuft lokal, daher sind alle Modellkosten auf $0 geset ### Streaming-Konfiguration -Die Ollama-Integration von OpenClaw verwendet standardmäßig die **native Ollama-API** (`/api/chat`), die Streaming und Tool-Aufrufe gleichzeitig vollständig unterstützt. Es ist keine besondere Konfiguration erforderlich. +Die Ollama-Integration von OpenClaw verwendet standardmäßig die **native Ollama-API** (`/api/chat`), die Streaming und Tool Calling gleichzeitig vollständig unterstützt. Es ist keine besondere Konfiguration erforderlich. -#### Legacy OpenAI-Compatible Mode +#### Veralteter OpenAI-kompatibler Modus -**Tool-Aufrufe sind im OpenAI-kompatiblen Modus nicht zuverlässig.** Verwende diesen Modus nur, wenn du das OpenAI-Format für einen Proxy benötigst und nicht auf natives Tool-Calling-Verhalten angewiesen bist. +**Tool Calling ist im OpenAI-kompatiblen Modus nicht zuverlässig.** Verwenden Sie diesen Modus nur, wenn Sie ein OpenAI-Format für einen Proxy benötigen und nicht von nativem Tool-Calling-Verhalten abhängig sind. -Wenn du stattdessen den OpenAI-kompatiblen Endpunkt verwenden musst (z. B. hinter einem Proxy, der nur das OpenAI-Format unterstützt), setze explizit `api: "openai-completions"`: +Wenn Sie stattdessen den OpenAI-kompatiblen Endpunkt verwenden müssen (z. B. hinter einem Proxy, der nur OpenAI-Format unterstützt), setzen Sie `api: "openai-completions"` explizit: ```json5 { @@ -302,7 +303,7 @@ Wenn du stattdessen den OpenAI-kompatiblen Endpunkt verwenden musst (z. B. hinte ollama: { baseUrl: "http://ollama-host:11434/v1", api: "openai-completions", - injectNumCtxForOpenAICompat: true, // default: true + injectNumCtxForOpenAICompat: true, // Standard: true apiKey: "ollama-local", models: [...] } @@ -311,9 +312,9 @@ Wenn du stattdessen den OpenAI-kompatiblen Endpunkt verwenden musst (z. B. hinte } ``` -Dieser Modus unterstützt möglicherweise Streaming + Tool-Aufrufe nicht gleichzeitig. Möglicherweise musst du Streaming mit `params: { streaming: false }` in der Modellkonfiguration deaktivieren. +Dieser Modus unterstützt Streaming und Tool Calling möglicherweise nicht gleichzeitig. Eventuell müssen Sie Streaming mit `params: { streaming: false }` in der Modellkonfiguration deaktivieren. -Wenn `api: "openai-completions"` mit Ollama verwendet wird, injiziert OpenClaw standardmäßig `options.num_ctx`, damit Ollama nicht stillschweigend auf ein Kontextfenster von 4096 zurückfällt. Wenn dein Proxy/Upstream unbekannte `options`-Felder ablehnt, deaktiviere dieses Verhalten: +Wenn `api: "openai-completions"` mit Ollama verwendet wird, fügt OpenClaw standardmäßig `options.num_ctx` ein, damit Ollama nicht stillschweigend auf ein Kontextfenster von 4096 zurückfällt. Wenn Ihr Proxy/Upstream unbekannte `options`-Felder ablehnt, deaktivieren Sie dieses Verhalten: ```json5 { @@ -333,13 +334,13 @@ Wenn `api: "openai-completions"` mit Ollama verwendet wird, injiziert OpenClaw s ### Kontextfenster -Für automatisch erkannte Modelle verwendet OpenClaw das von Ollama gemeldete Kontextfenster, wenn verfügbar, andernfalls das von OpenClaw verwendete Standard-Kontextfenster für Ollama. Du kannst `contextWindow` und `maxTokens` in der expliziten Provider-Konfiguration überschreiben. +Für automatisch erkannte Modelle verwendet OpenClaw das von Ollama gemeldete Kontextfenster, wenn verfügbar, andernfalls fällt es auf das von OpenClaw verwendete Standard-Kontextfenster für Ollama zurück. Sie können `contextWindow` und `maxTokens` in der expliziten Provider-Konfiguration überschreiben. ## Fehlerbehebung ### Ollama wird nicht erkannt -Stelle sicher, dass Ollama läuft, dass du `OLLAMA_API_KEY` (oder ein Auth-Profil) gesetzt hast und dass du **keinen** expliziten Eintrag `models.providers.ollama` definiert hast: +Stellen Sie sicher, dass Ollama läuft, dass Sie `OLLAMA_API_KEY` (oder ein Auth-Profil) gesetzt haben und dass Sie **keinen** expliziten Eintrag `models.providers.ollama` definiert haben: ```bash ollama serve @@ -353,34 +354,34 @@ curl http://localhost:11434/api/tags ### Keine Modelle verfügbar -Wenn dein Modell nicht aufgelistet ist, musst du entweder: +Wenn Ihr Modell nicht aufgeführt wird, dann entweder: -- das Modell lokal pullen oder -- das Modell explizit in `models.providers.ollama` definieren. +- pullen Sie das Modell lokal, oder +- definieren Sie das Modell explizit in `models.providers.ollama`. -So fügst du Modelle hinzu: +Um Modelle hinzuzufügen: ```bash -ollama list # See what's installed +ollama list # Anzeigen, was installiert ist ollama pull gemma4 ollama pull gpt-oss:20b -ollama pull llama3.3 # Or another model +ollama pull llama3.3 # Oder ein anderes Modell ``` ### Verbindung abgelehnt -Prüfe, ob Ollama auf dem richtigen Port läuft: +Prüfen Sie, ob Ollama auf dem richtigen Port läuft: ```bash -# Check if Ollama is running +# Prüfen, ob Ollama läuft ps aux | grep ollama -# Or restart Ollama +# Oder Ollama neu starten ollama serve ``` ## Siehe auch -- [Modell-Provider](/de/concepts/model-providers) - Überblick über alle Provider -- [Modellauswahl](/de/concepts/models) - So wählst du Modelle aus -- [Konfiguration](/de/gateway/configuration) - Vollständige Konfigurationsreferenz +- [Model Providers](/de/concepts/model-providers) - Überblick über alle Provider +- [Model Selection](/de/concepts/models) - So wählen Sie Modelle aus +- [Configuration](/de/gateway/configuration) - Vollständige Konfigurationsreferenz diff --git a/docs/de/providers/qwen.md b/docs/de/providers/qwen.md index 2b47d359d..38b2e816a 100644 --- a/docs/de/providers/qwen.md +++ b/docs/de/providers/qwen.md @@ -2,13 +2,13 @@ read_when: - Sie möchten Qwen mit OpenClaw verwenden - Sie haben zuvor Qwen OAuth verwendet -summary: Qwen Cloud über den gebündelten Provider `qwen` von OpenClaw verwenden +summary: Qwen Cloud über den gebündelten Qwen-Provider von OpenClaw verwenden title: Qwen x-i18n: - generated_at: "2026-04-06T03:11:33Z" + generated_at: "2026-04-09T01:30:57Z" model: gpt-5.4 provider: openai - source_hash: f175793693ab6a4c3f1f4d42040e673c15faf7603a500757423e9e06977c989d + source_hash: 4786df2cb6ec1ab29d191d012c61dcb0e5468bf0f8561fbbb50eed741efad325 source_path: providers/qwen.md workflow: 15 --- @@ -17,9 +17,9 @@ x-i18n: -**Qwen OAuth wurde entfernt.** Die OAuth-Integration der kostenlosen Stufe -(`qwen-portal`), die `portal.qwen.ai`-Endpunkte verwendete, ist nicht mehr verfügbar. -Hintergrundinformationen finden Sie in [Issue #49557](https://github.com/openclaw/openclaw/issues/49557). +**Qwen OAuth wurde entfernt.** Die Free-Tier-OAuth-Integration +(`qwen-portal`), die Endpunkte von `portal.qwen.ai` verwendete, ist nicht mehr verfügbar. +Hintergrundinformationen finden Sie unter [Issue #49557](https://github.com/openclaw/openclaw/issues/49557). @@ -27,16 +27,16 @@ Hintergrundinformationen finden Sie in [Issue #49557](https://github.com/opencla OpenClaw behandelt Qwen jetzt als erstklassigen gebündelten Provider mit der kanonischen ID `qwen`. Der gebündelte Provider zielt auf die Endpunkte von Qwen Cloud / Alibaba DashScope und -Coding Plan und hält ältere `modelstudio`-IDs weiterhin als +Coding Plan und hält Legacy-IDs von `modelstudio` als Kompatibilitätsalias funktionsfähig. - Provider: `qwen` -- Bevorzugte Env-Variable: `QWEN_API_KEY` -- Ebenfalls aus Kompatibilitätsgründen akzeptiert: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` +- Bevorzugte Umgebungsvariable: `QWEN_API_KEY` +- Aus Kompatibilitätsgründen ebenfalls akzeptiert: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` - API-Stil: OpenAI-kompatibel -Wenn Sie `qwen3.6-plus` verwenden möchten, bevorzugen Sie den Endpunkt **Standard (Pay-as-you-go)**. -Die Unterstützung im Coding Plan kann hinter dem öffentlichen Katalog zurückbleiben. +Wenn Sie `qwen3.6-plus` verwenden möchten, bevorzugen Sie den Endpunkt **Standard (pay-as-you-go)**. +Die Unterstützung für Coding Plan kann dem öffentlichen Katalog hinterherhinken. ```bash # Globaler Coding-Plan-Endpunkt @@ -45,16 +45,16 @@ openclaw onboard --auth-choice qwen-api-key # Chinesischer Coding-Plan-Endpunkt openclaw onboard --auth-choice qwen-api-key-cn -# Globaler Standard-Endpunkt (Pay-as-you-go) +# Globaler Standard-Endpunkt (pay-as-you-go) openclaw onboard --auth-choice qwen-standard-api-key -# Chinesischer Standard-Endpunkt (Pay-as-you-go) +# Chinesischer Standard-Endpunkt (pay-as-you-go) openclaw onboard --auth-choice qwen-standard-api-key-cn ``` -Ältere `modelstudio-*`-`auth-choice`-IDs und Modellreferenzen vom Typ `modelstudio/...` funktionieren weiterhin -als Kompatibilitätsalias, neue Einrichtungsabläufe sollten jedoch die kanonischen -`qwen-*`-`auth-choice`-IDs und Modellreferenzen vom Typ `qwen/...` bevorzugen. +Legacy-Auth-Choice-IDs vom Typ `modelstudio-*` und Modellreferenzen vom Typ `modelstudio/...` funktionieren weiterhin +als Kompatibilitätsalias, aber neue Einrichtungsabläufe sollten die kanonischen +Auth-Choice-IDs `qwen-*` und Modellreferenzen `qwen/...` bevorzugen. Legen Sie nach dem Onboarding ein Standardmodell fest: @@ -70,22 +70,22 @@ Legen Sie nach dem Onboarding ein Standardmodell fest: ## Plantypen und Endpunkte -| Plan | Region | Auth choice | Endpunkt | -| -------------------------- | ------ | -------------------------- | ----------------------------------------------- | -| Standard (Pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | -| Standard (Pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | -| Coding Plan (Abonnement) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | -| Coding Plan (Abonnement) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | +| Plan | Region | Auth-Auswahl | Endpunkt | +| -------------------------- | ------ | -------------------------- | ------------------------------------------------ | +| Standard (pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | +| Standard (pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | +| Coding Plan (Abonnement) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | +| Coding Plan (Abonnement) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | -Der Provider wählt den Endpunkt anhand Ihrer `auth-choice` automatisch aus. Kanonische +Der Provider wählt den Endpunkt automatisch basierend auf Ihrer Auth-Auswahl. Kanonische Auswahlen verwenden die Familie `qwen-*`; `modelstudio-*` bleibt nur für Kompatibilität erhalten. Sie können dies mit einer benutzerdefinierten `baseUrl` in der Konfiguration überschreiben. -Native Model-Studio-Endpunkte signalisieren Streaming-Nutzungskompatibilität auf dem -gemeinsamen Transport `openai-completions`. OpenClaw leitet dies jetzt aus den Fähigkeiten des Endpunkts ab, +Native Model-Studio-Endpunkte geben Streaming-Nutzungskompatibilität auf dem +gemeinsamen Transport `openai-completions` an. OpenClaw koppelt das jetzt an die Endpunktfähigkeiten, sodass DashScope-kompatible benutzerdefinierte Provider-IDs, die auf dieselben nativen Hosts zeigen, -dasselbe Verhalten für Streaming-Nutzung übernehmen, statt -speziell die integrierte Provider-ID `qwen` zu erfordern. +dasselbe Verhalten für Streaming-Nutzung erben, statt +die integrierte Provider-ID `qwen` ausdrücklich zu erfordern. ## API-Schlüssel abrufen @@ -94,25 +94,27 @@ speziell die integrierte Provider-ID `qwen` zu erfordern. ## Integrierter Katalog -OpenClaw enthält derzeit diesen gebündelten Qwen-Katalog: +OpenClaw liefert derzeit diesen gebündelten Qwen-Katalog mit. Der konfigurierte Katalog ist +endpunktbewusst: Konfigurationen für Coding Plan lassen Modelle aus, von denen nur bekannt ist, dass sie auf +dem Standard-Endpunkt funktionieren. -| Modellreferenz | Eingabe | Kontext | Hinweise | -| --------------------------- | ----------- | --------- | -------------------------------------------------- | -| `qwen/qwen3.5-plus` | Text, Bild | 1,000,000 | Standardmodell | -| `qwen/qwen3.6-plus` | Text, Bild | 1,000,000 | Bevorzugen Sie Standard-Endpunkte, wenn Sie dieses Modell benötigen | -| `qwen/qwen3-max-2026-01-23` | Text | 262,144 | Qwen-Max-Linie | -| `qwen/qwen3-coder-next` | Text | 262,144 | Coding | -| `qwen/qwen3-coder-plus` | Text | 1,000,000 | Coding | -| `qwen/MiniMax-M2.5` | Text | 1,000,000 | Reasoning aktiviert | -| `qwen/glm-5` | Text | 202,752 | GLM | -| `qwen/glm-4.7` | Text | 202,752 | GLM | -| `qwen/kimi-k2.5` | Text, Bild | 262,144 | Moonshot AI über Alibaba | +| Modellreferenz | Eingabe | Kontext | Hinweise | +| --------------------------- | ------------ | --------- | -------------------------------------------------- | +| `qwen/qwen3.5-plus` | Text, Bild | 1,000,000 | Standardmodell | +| `qwen/qwen3.6-plus` | Text, Bild | 1,000,000 | Bei Bedarf dieses Modells Standard-Endpunkte bevorzugen | +| `qwen/qwen3-max-2026-01-23` | Text | 262,144 | Qwen-Max-Linie | +| `qwen/qwen3-coder-next` | Text | 262,144 | Coding | +| `qwen/qwen3-coder-plus` | Text | 1,000,000 | Coding | +| `qwen/MiniMax-M2.5` | Text | 1,000,000 | Reasoning aktiviert | +| `qwen/glm-5` | Text | 202,752 | GLM | +| `qwen/glm-4.7` | Text | 202,752 | GLM | +| `qwen/kimi-k2.5` | Text, Bild | 262,144 | Moonshot AI über Alibaba | -Die Verfügbarkeit kann weiterhin je nach Endpunkt und Abrechnungsplan variieren, selbst wenn ein Modell +Die Verfügbarkeit kann weiterhin je nach Endpunkt und Abrechnungsplan variieren, auch wenn ein Modell im gebündelten Katalog vorhanden ist. -Kompatibilität mit nativer Streaming-Nutzung gilt sowohl für die Coding-Plan-Hosts als auch für -die Standard-DashScope-kompatiblen Hosts: +Die native Streaming-Nutzungskompatibilität gilt sowohl für die Coding-Plan-Hosts als auch für die +Standard-DashScope-kompatiblen Hosts: - `https://coding.dashscope.aliyuncs.com/v1` - `https://coding-intl.dashscope.aliyuncs.com/v1` @@ -121,30 +123,30 @@ die Standard-DashScope-kompatiblen Hosts: ## Verfügbarkeit von Qwen 3.6 Plus -`qwen3.6-plus` ist auf den Standard-Endpunkten (Pay-as-you-go) von Model Studio +`qwen3.6-plus` ist auf den Standard-Endpunkten (pay-as-you-go) von Model Studio verfügbar: - China: `dashscope.aliyuncs.com/compatible-mode/v1` - Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1` Wenn die Coding-Plan-Endpunkte für -`qwen3.6-plus` einen Fehler vom Typ „unsupported model“ zurückgeben, wechseln Sie zu Standard (Pay-as-you-go) anstelle des -Endpunkts/Schlüsselpaares des Coding Plan. +`qwen3.6-plus` den Fehler „unsupported model“ zurückgeben, wechseln Sie zu Standard (pay-as-you-go) statt zum +Endpunkt-/Schlüsselpaar von Coding Plan. -## Capability-Plan +## Fähigkeitsplan -Die Erweiterung `qwen` wird als das anbieterseitige Zuhause für die vollständige Qwen- +Die Erweiterung `qwen` wird als Anbieter-Heimat für die vollständige Qwen- Cloud-Oberfläche positioniert, nicht nur für Coding-/Textmodelle. -- Text-/Chatmodelle: jetzt gebündelt -- Tool-Calling, strukturierte Ausgabe, Thinking: werden vom OpenAI-kompatiblen Transport geerbt +- Text-/Chat-Modelle: jetzt gebündelt +- Tool-Aufrufe, strukturierte Ausgabe, Thinking: vom OpenAI-kompatiblen Transport geerbt - Bildgenerierung: auf der Ebene des Provider-Plugins geplant - Bild-/Videoverständnis: jetzt auf dem Standard-Endpunkt gebündelt - Sprache/Audio: auf der Ebene des Provider-Plugins geplant -- Memory-Embeddings/Reranking: über die Embedding-Adapter-Oberfläche geplant -- Videogenerierung: jetzt über die gemeinsame Videogenerierungs-Capability gebündelt +- Memory-Embeddings/Reranking: über die Adapteroberfläche für Embeddings geplant +- Videogenerierung: jetzt über die gemeinsame Fähigkeit zur Videogenerierung gebündelt -## Multimodale Add-ons +## Multimodale Zusätze Die Erweiterung `qwen` stellt jetzt außerdem Folgendes bereit: @@ -163,13 +165,13 @@ Coding-Plan-Endpunkte. - Chinesische Standard-`baseUrl`: `https://dashscope.aliyuncs.com/compatible-mode/v1` Für die Videogenerierung ordnet OpenClaw die konfigurierte Qwen-Region dem passenden -DashScope-AIGC-Host zu, bevor der Job gesendet wird: +DashScope-AIGC-Host zu, bevor der Auftrag gesendet wird: - Global/International: `https://dashscope-intl.aliyuncs.com` - China: `https://dashscope.aliyuncs.com` -Das bedeutet, dass eine normale `models.providers.qwen.baseUrl`, die entweder auf die -Hosts von Coding Plan oder Standard Qwen verweist, die Videogenerierung weiterhin auf dem korrekten +Das bedeutet, dass eine normale `models.providers.qwen.baseUrl`, die auf einen der +Coding-Plan- oder Standard-Qwen-Hosts zeigt, die Videogenerierung weiterhin auf dem korrekten regionalen DashScope-Videoendpunkt hält. Legen Sie für die Videogenerierung explizit ein Standardmodell fest: @@ -191,15 +193,15 @@ Aktuelle Grenzen der gebündelten Qwen-Videogenerierung: - Bis zu **4** Eingabevideos - Bis zu **10 Sekunden** Dauer - Unterstützt `size`, `aspectRatio`, `resolution`, `audio` und `watermark` -- Der Referenzbild-/Referenzvideo-Modus erfordert derzeit **entfernte http(s)-URLs**. Lokale - Dateipfade werden vorab abgelehnt, da der DashScope-Videoendpunkt keine - hochgeladenen lokalen Buffer für diese Referenzen akzeptiert. +- Der Referenzbild-/Videomodus erfordert derzeit **entfernte http(s)-URLs**. Lokale + Dateipfade werden vorab abgelehnt, da der DashScope-Videoendpunkt keine hochgeladenen lokalen Puffer + für diese Referenzen akzeptiert. -Siehe [Videogenerierung](/tools/video-generation) für die gemeinsamen Tool- -Parameter, Providerauswahl und das Failover-Verhalten. +Unter [Videogenerierung](/de/tools/video-generation) finden Sie die gemeinsamen Werkzeug- +Parameter, die Providerauswahl und das Failover-Verhalten. ## Hinweis zur Umgebung -Wenn das Gateway als Daemon läuft (launchd/systemd), stellen Sie sicher, dass `QWEN_API_KEY` -für diesen Prozess verfügbar ist (zum Beispiel in `~/.openclaw/.env` oder über +Wenn das Gateway als Daemon (launchd/systemd) läuft, stellen Sie sicher, dass `QWEN_API_KEY` +diesem Prozess zur Verfügung steht (zum Beispiel in `~/.openclaw/.env` oder über `env.shellEnv`).