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

chore(i18n): refresh de translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-09 01:33:43 +00:00
parent a0d596177d
commit 9d98cbf608
21 changed files with 4101 additions and 4425 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

430
docs/de/channels/discord.md
View File

@ -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.
<CardGroup cols={3}>
<Card title="Kopplung" icon="link" href="/de/channels/pairing">
@ -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**).
<Steps>
<Step title="Discord-Anwendung und Bot erstellen">
<Step title="Eine Discord-Anwendung und einen Bot erstellen">
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)
</Step>
<Step title="Bot-Token kopieren">
<Step title="Ihren Bot-Token kopieren">
Scrollen Sie auf der Seite **Bot** wieder nach oben und klicken Sie auf **Reset Token**.
<Note>
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“.
</Note>
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.
</Step>
<Step title="Einladungs-URL erzeugen und den Bot zu Ihrem Server hinzufügen">
<Step title="Eine Einladungs-URL erzeugen und den Bot zu Ihrem Server hinzufügen">
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.
</Step>
@ -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.
</Step>
<Step title="DMs von Servermitgliedern erlauben">
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.
</Step>
<Step title="Bot-Token sicher setzen (nicht im Chat senden)">
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.
<Step title="Ihren Bot-Token sicher setzen (nicht im Chat 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.
</Step>
<Step title="OpenClaw konfigurieren und koppeln">
<Tabs>
<Tab title="Fragen Sie Ihren Agenten">
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.
<Tab title="Ihren Agenten fragen">
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 `<user_id>` und der Server ID `<server_id>` ab.“
> „Ich habe meinen Discord-Bot-Token bereits in der Konfiguration gesetzt. Bitte schließe die Discord-Einrichtung mit der User ID `<user_id>` und der Server ID `<server_id>` ab.“
</Tab>
<Tab title="CLI / config">
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=...
</Step>
<Step title="Erste DM-Kopplung genehmigen">
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.
<Tabs>
<Tab title="Fragen Sie Ihren Agenten">
<Tab title="Ihren Agenten fragen">
Senden Sie den Kopplungscode auf Ihrem bestehenden Kanal an Ihren Agenten:
> „Genehmige diesen Discord-Kopplungscode: `<CODE>`“
@ -174,27 +174,27 @@ openclaw pairing approve discord <CODE>
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.
</Step>
</Steps>
<Note>
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.
</Note>
## 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.
<Steps>
<Step title="Ihren Server zur Guild-Allowlist hinzufügen">
Dadurch kann Ihr Agent in jedem Kanal auf Ihrem Server antworten, nicht nur in DMs.
<Step title="Ihren Server zur Server-Allowlist hinzufügen">
Dadurch kann Ihr Agent in jedem Kanal Ihres Servers antworten, nicht nur in DMs.
<Tabs>
<Tab title="Fragen Sie Ihren Agenten">
> „Füge meine Discord Server ID `<server_id>` zur Guild-Allowlist hinzu“
<Tab title="Ihren Agenten fragen">
> „Füge meine Discord Server ID `<server_id>` zur Server-Allowlist hinzu“
</Tab>
<Tab title="Konfiguration">
@ -219,15 +219,15 @@ Sobald DMs funktionieren, können Sie Ihren Discord-Server als vollständigen Wo
</Step>
<Step title="Antworten ohne @mention erlauben">
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.
<Step title="Antworten ohne @Erwähnung erlauben">
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.
<Tabs>
<Tab title="Fragen Sie Ihren Agenten">
> „Erlaube meinem Agenten, auf diesem Server zu antworten, ohne per @ erwähnt werden zu müssen“
<Tab title="Ihren Agenten fragen">
> „Erlaube meinem Agenten, auf diesem Server zu antworten, ohne dass er mit @ erwähnt werden muss“
</Tab>
<Tab title="Konfiguration">
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
</Step>
<Step title="Speicher in Guild-Kanälen planen">
Standardmäßig wird der Langzeitspeicher (`MEMORY.md`) nur in DM-Sitzungen geladen. Guild-Kanäle laden `MEMORY.md` nicht automatisch.
<Step title="Speichernutzung in Serverkanälen planen">
Standardmäßig wird Langzeitspeicher (`MEMORY.md`) nur in DM-Sitzungen geladen. In Serverkanälen wird `MEMORY.md` nicht automatisch geladen.
<Tabs>
<Tab title="Fragen Sie Ihren Agenten">
> „Wenn ich in Discord-Kanälen Fragen stelle, verwende memory_search oder memory_get, wenn du langfristigen Kontext aus MEMORY.md brauchst.“
<Tab title="Ihren Agenten fragen">
> „Wenn ich in Discord-Kanälen Fragen stelle, verwende memory_search oder memory_get, wenn du Langzeitkontext aus MEMORY.md benötigst.“
</Tab>
<Tab title="Manuell">
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.
</Tab>
</Tabs>
</Step>
</Steps>
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:<agentId>:discord:channel:<channelId>`).
- 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:<agentId>:discord:channel:<channelId>`).
- Gruppen-DMs werden standardmäßig ignoriert (`channels.discord.dm.groupEnabled=false`).
- Native Slash-Befehle laufen in isolierten Befehlssitzungen (`agent:<agentId>:discord:slash:<userId>`), während weiterhin `CommandTargetSessionKey` an die geroutete Konversationssitzung übergeben wird.
- Native Slash-Befehle laufen in isolierten Befehlssitzungen (`agent:<agentId>:discord:slash:<userId>`), 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:<forumId>`), 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:<forumId>`), 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:<forumId> \
@ -295,11 +295,11 @@ openclaw message thread create --channel discord --target channel:<forumId> \
--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:<threadId>`).
Forum-Parents akzeptieren keine Discord-Komponenten. Wenn Sie Komponenten benötigen, senden Sie an den Thread selbst (`channel:<threadId>`).
## 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://<filename>`)
- `file`-Blöcke müssen auf eine Anhangsreferenz zeigen (`attachment://<filename>`)
- 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>`
- `<@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.
</Tab>
<Tab title="Guild-Richtlinie">
Die Behandlung von Guilds wird durch `channels.discord.groupPolicy` gesteuert:
<Tab title="Serverrichtlinie">
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.
</Tab>
<Tab title="Erwähnungen und Gruppen-DMs">
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:
</Tab>
</Tabs>
### 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
</Accordion>
<Accordion title="Privilegierte Intents">
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.
</Accordion>
<Accordion title="OAuth-Scopes und Basisberechtigungen">
<Accordion title="OAuth-Scopes und grundlegende Berechtigungen">
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.
</Accordion>
@ -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:
<AccordionGroup>
<Accordion title="Antwort-Tags und native Antworten">
Discord unterstützt Antwort-Tags in der Agent-Ausgabe:
Discord unterstützt Antwort-Tags in der Agentenausgabe:
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
@ -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.
</Accordion>
<Accordion title="Live-Stream-Vorschau">
OpenClaw kann Entwurfsantworten streamen, indem eine temporäre Nachricht gesendet und während des Eintreffens von Text bearbeitet wird.
<Accordion title="Vorschau für Live-Streaming">
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:
</Accordion>
<Accordion title="Verlauf, Kontext und Thread-Verhalten">
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["<user_id>"].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.
</Accordion>
<Accordion title="Thread-gebundene Sitzungen für Subagents">
Discord kann einen Thread an ein Sitzungsziel binden, sodass Folgebotschaften in diesem Thread weiterhin an dieselbe Sitzung geleitet werden (einschließlich Subagent-Sitzungen).
<Accordion title="Thread-gebundene Sitzungen für Subagenten">
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 <target>` bindet aktuellen/neuen Thread an ein Subagent-/Sitzungsziel
- `/focus <target>` 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 <duration|off>` prüft/aktualisiert das automatische Lösen der Fokusbindung bei Inaktivität
- `/session max-age <duration|off>` prüft/aktualisiert das feste maximale Alter für fokussierte Bindungen
- `/session idle <duration|off>` prüft/aktualisiert das automatische Lösen des Fokus bei Inaktivität für fokussierte Bindungen
- `/session max-age <duration|off>` 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).
</Accordion>
<Accordion title="Persistente ACP-Kanal-Bindungen">
Für stabile „always-on“-ACP-Workspaces konfigurieren Sie ACP-Bindungen auf oberster Ebene mit Typisierung, die auf Discord-Konversationen zielen.
<Accordion title="Persistente ACP-Kanalbindungen">
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.
</Accordion>
<Accordion title="Reaktionsbenachrichtigungen">
Reaktionsbenachrichtigungsmodus pro Guild:
<Accordion title="Benachrichtigungen für Reaktionen">
Modus für Reaktionsbenachrichtigungen pro Server:
- `off`
- `own` (Standard)
- `all`
- `allowlist` (verwendet `guilds.<id>.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.
</Accordion>
@ -797,19 +797,19 @@ Standardmäßige Einstellungen für Slash-Befehle:
- `channels.discord.accounts.<accountId>.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.
</Accordion>
<Accordion title="Konfigurationsschreibvorgänge">
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:
</Accordion>
<Accordion title="Gateway-Proxy">
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:
</Accordion>
<Accordion title="PluralKit-Unterstützung">
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:<memberId>` verwenden
- Allowlists können `pk:<memberId>` 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`
</Accordion>
<Accordion title="Presence-Konfiguration">
Presence-Updates werden angewendet, wenn Sie ein Status- oder Aktivitätsfeld setzen oder Auto Presence aktivieren.
<Accordion title="Präsenzkonfiguration">
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}`)
</Accordion>
<Accordion title="Genehmigungen in Discord">
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)
</Accordion>
</AccordionGroup>
## 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.<id>.ui.components.accentColor`.
- `channels.discord.ui.components.accentColor` setzt die Akzentfarbe, die von Discord-Komponentencontainern verwendet wird (hex).
- Pro Konto mit `channels.discord.accounts.<id>.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
<AccordionGroup>
<Accordion title="Nicht erlaubte Intents verwendet oder Bot sieht keine Guild-Nachrichten">
<Accordion title="Nicht erlaubte Intents verwendet oder Bot sieht keine Servernachrichten">
- 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
</Accordion>
<Accordion title="Guild-Nachrichten werden unerwartet blockiert">
<Accordion title="Servernachrichten unerwartet blockiert">
- `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
</Accordion>
<Accordion title="Require mention false, aber weiterhin blockiert">
<Accordion title="requireMention false, aber trotzdem blockiert">
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
</Accordion>
<Accordion title="Lang laufende Handler laufen ab oder erzeugen doppelte Antworten">
<Accordion title="Lang laufende Handler haben Timeouts oder doppelte Antworten">
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.<accountId>.eventQueue.listenerTimeout`
- mehrere Konten: `channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`
Schalter für Worker-Lauf-Timeout:
Regler für Worker-Laufzeit-Timeout:
- Einzelkonto: `channels.discord.inboundWorker.runTimeoutMs`
- Mehrere Konten: `channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs`
- mehrere Konten: `channels.discord.accounts.<accountId>.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.
</Accordion>
<Accordion title="Abweichungen bei der Berechtigungsprüfung">
<Accordion title="Abweichungen bei Berechtigungs-Audits">
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.
</Accordion>
<Accordion title="DM- und Kopplungsprobleme">
<Accordion title="Probleme mit DM und Kopplung">
- 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
</Accordion>
@ -1214,15 +1216,15 @@ openclaw logs --follow
</Accordion>
<Accordion title="Voice-STT-Ausfälle mit DecryptionFailed(...)">
<Accordion title="Voice-STT-Aussetzer mit DecryptionFailed(...)">
- 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)
</Accordion>
</AccordionGroup>
@ -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

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

File diff suppressed because it is too large Load Diff

188
docs/de/concepts/agent-loop.md
View File

@ -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

152
docs/de/concepts/dreaming.md
View File

@ -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/<phase>/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/<phase>/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)

167
docs/de/concepts/memory.md
View File

@ -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`).
<Tip>
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.
</Tip>
## 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.
<Info>
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.
</Info>
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
<CardGroup cols={3}>
<Card title="Integriert (Standard)" icon="database" href="/de/concepts/memory-builtin">
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.
</Card>
<Card title="QMD" icon="search" href="/de/concepts/memory-qmd">
Lokaler Sidecar mit Reranking, Query-Erweiterung und der Möglichkeit,
@ -99,7 +103,7 @@ Verzeichnisse außerhalb des Workspace zu indizieren.
</Card>
<Card title="Honcho" icon="brain" href="/de/concepts/memory-honcho">
KI-nativer sitzungsübergreifender Speicher mit Benutzermodellierung,
semantischer Suche und Multi-Agent-Bewusstsein. Plugin-Installation.
semantischer Suche und Multi-Agent-Unterstützung. Plugin-Installation.
</Card>
</CardGroup>
@ -107,60 +111,99 @@ semantischer Suche und Multi-Agent-Bewusstsein. Plugin-Installation.
<CardGroup cols={1}>
<Card title="Memory Wiki" icon="book" href="/de/plugins/memory-wiki">
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.
</Card>
</CardGroup>
## 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.
<Tip>
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.
</Tip>
## 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

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

@ -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 <provider/model>`.
- 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.<id>`, 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.<id>`, 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_<PROVIDER>_KEY` (einzelne Live-Überschreibung, höchste Priorität)
- `<PROVIDER>_API_KEYS` (durch Komma oder Semikolon getrennte Liste)
- `<PROVIDER>_API_KEYS` (komma- oder semikolongetrennte Liste)
- `<PROVIDER>_API_KEY` (primärer Schlüssel)
- `<PROVIDER>_API_KEY_*` (nummerierte Liste, z. B. `<PROVIDER>_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/<model>"].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/<model>"].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/<model>"].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/<model>"].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/<model>"].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/<model>"].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/<model>"].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/<model>"].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.<id>` 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.<id>` 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

128
docs/de/concepts/qa-e2e-automation.md
View File

@ -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=<level>`. `--thinking <level>` setzt weiterhin
einen globalen Fallback, und die ältere Form
`--model-thinking <provider/model=level>` 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)

147
docs/de/gateway/cli-backends.md
View File

@ -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:
```
<provider>/<model>
@ -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.
<Note>
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.
</Note>
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.<id>` überschreibt weiterhin den Plugin-Standard.
- Die Backend-`id` wird zum Anbieterpräfix in Modellreferenzen.
- Benutzerkonfiguration in `agents.defaults.cliBackends.<id>` ü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

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

File diff suppressed because it is too large Load Diff

465
docs/de/gateway/doctor.md
View File

@ -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.<provider>`.
- 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.<provider>`.
- 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.<provider>`. 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.<provider>`
- altes `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -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.<channel>.accounts` konfiguriert sind, ohne `channels.<channel>.defaultAccount` oder `accounts.default`, warnt Doctor, dass Fallback-Routing ein unerwartetes Konto auswählen kann.
- Wenn zwei oder mehr `channels.<channel>.accounts`-Einträge konfiguriert sind, ohne `channels.<channel>.defaultAccount` oder `accounts.default`, warnt Doctor davor, dass Fallback-Routing ein unerwartetes Konto auswählen kann.
- Wenn `channels.<channel>.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/<agentId>/sessions/`
- Agent-Verzeichnis:
- von `~/.openclaw/agent/` nach `~/.openclaw/agents/<agentId>/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/<accountId>/...` (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).

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

@ -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 <git-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 <git-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=<n>`, 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=<n>`, 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 <CODE>` 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 <CODE>` 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: "<base64>" }]`
- 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: "<base64>" }]`
- 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 <agent> --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@<version>'`
- 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/<agentId>/agent/auth-profiles.json` (das bedeutet in den Live-Tests „Profilschlüssel“)
- Auth-Profile pro Agent: `~/.openclaw/agents/<agentId>/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.<capability>` 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 <discord-channel-id> ...`
- 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.

578
docs/de/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md
View File

@ -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/<first-wave-subpaths>.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`

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

File diff suppressed because it is too large Load Diff

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

@ -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 <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.<id>` verwendet wird. |
| `configSchema` | Ja | `object` | Inline-JSON-Schema für die Konfiguration dieses Plugins. |
| `enabledByDefault` | Nein | `true` | Markiert ein gebündeltes Plugin als standardmäßig aktiviert. Lassen Sie es weg oder setzen Sie einen beliebigen Wert ungleich `true`, 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<string, string[]>` | Günstige Anbieter-Auth-Env-Metadaten, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. |
| `channelEnvVars` | Nein | `Record<string, string[]>` | 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<string, object>` | 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<string, object>` | 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.<id>` 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<string, string[]>` | Leichtgewichtige Metadaten zu Provider-Auth-Umgebungsvariablen, die OpenClaw ohne Laden von Plugin-Code prüfen kann. |
| `providerAuthAliases` | Nein | `Record<string, string>` | 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<string, string[]>` | 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<string, object>` | 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<string, object>` | 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 <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 <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.<id>`. Für jeden deklarierten Kanal-Konfigurationseintrag erforderlich. |
| `uiHints` | `Record<string, object>` | 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<string, object>` | 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.<id>`-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.<id>` 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.<id>`, `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 <package>`).
## 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

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

@ -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.
<Warning>
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.
</Warning>
## 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/\<subpath\>`)
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
<Steps>
<Step title="Approval-native-Handler auf Capability-Fakten migrieren">
Freigabefähige Kanal-Plugins stellen natives Freigabeverhalten jetzt über
`approvalCapability.nativeRuntime` plus das gemeinsame Runtime-Context-Registry bereit.
<Step title="Native Approval-Handler auf Capability-Fakten migrieren">
Approval-fähige Kanal-Plugins stellen natives Approval-Verhalten jetzt über
`approvalCapability.nativeRuntime` plus die gemeinsame Runtime-Context-Registry bereit.
Wichtige Änderungen:
- 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.
</Step>
<Step title="Fallback-Verhalten des Windows-Wrappers prüfen">
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.
</Step>
<Step title="Veraltete Imports finden">
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:
</Step>
<Step title="Durch fokussierte Imports ersetzen">
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.*` |
</Step>
<Step title="Build und Tests">
<Step title="Erstellen und testen">
```bash
pnpm build
pnpm test -- my-plugin/
@ -184,174 +183,177 @@ Aktuelle Beispiele für gebündelte Provider:
</Step>
</Steps>
## Referenz für Importpfade
## Referenz der Importpfade
<Accordion title="Tabelle häufiger 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 |
</Accordion>
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

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

@ -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**.
<Tip>
**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)
</Tip>
## 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` |
<AccordionGroup>
<Accordion title="Channel-Unterpfade">
| Subpath | Key exports |
<Accordion title="Channel-Subpaths">
| 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 |
</Accordion>
<Accordion title="Provider-Unterpfade">
| Subpath | Key exports |
<Accordion title="Anbieter-Subpaths">
| 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 |
</Accordion>
<Accordion title="Auth- und Sicherheits-Unterpfade">
| Subpath | Key exports |
<Accordion title="Auth- und Sicherheits-Subpaths">
| 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 |
</Accordion>
<Accordion title="Runtime- und Speicher-Unterpfade">
| Subpath | Key exports |
<Accordion title="Laufzeit- und Speicher-Subpaths">
| 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` |
</Accordion>
<Accordion title="Unterpfade für Fähigkeiten und Tests">
| Subpath | Key exports |
<Accordion title="Fähigkeits- und Test-Subpaths">
| 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` |
</Accordion>
<Accordion title="Memory-Unterpfade">
| Subpath | Key exports |
<Accordion title="Memory-Subpaths">
| 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 |
</Accordion>
<Accordion title="Reservierte Unterpfade für gebündelte Helper">
| Family | Current subpaths | Intended use |
<Accordion title="Reservierte gebündelte Helper-Subpaths">
| 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` |
</Accordion>
</AccordionGroup>
## 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.<id>`.
- Benutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt `agents.defaults.cliBackends.<id>` über dem
- Nutzerkonfiguration hat weiterhin Vorrang. OpenClaw führt `agents.defaults.cliBackends.<id>` ü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<string, unknown>` | Pluginspezifische Konfiguration aus `plugins.entries.<id>.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<string, unknown>` | Plugin-spezifische Konfiguration aus `plugins.entries.<id>.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)
```
<Warning>
Importieren Sie Ihr eigenes Plugin in Produktionscode niemals über `openclaw/plugin-sdk/<your-plugin>`.
Leiten Sie interne Importe über `./api.ts` oder
Importieren Sie Ihr eigenes Plugin niemals über `openclaw/plugin-sdk/<your-plugin>`
aus Produktionscode. Leiten Sie interne Importe über `./api.ts` oder
`./runtime-api.ts`. Der SDK-Pfad ist nur der externe Vertrag.
</Warning>
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
<Warning>
Produktionscode von Extensions sollte außerdem Importe von `openclaw/plugin-sdk/<other-plugin>`
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/<other-plugin>`
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.
</Warning>
## 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

299
docs/de/plugins/sdk-provider-plugins.md
View File

@ -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.
<Info>
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.
</Info>
## Walkthrough
## Anleitung
<Steps>
<a id="step-1-package-and-manifest"></a>
@ -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.
</CodeGroup>
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 <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 <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.
</Step>
@ -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.
</Step>
<Step title="Laufzeit-Hooks hinzufügen (bei Bedarf)">
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.
},
```
</Tab>
<Tab title="Native Transportidentität">
Für Provider, die native Request-/Session-Header oder Metadaten auf
<Tab title="Native Transport-Identität">
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.
}),
```
</Tab>
<Tab title="Usage und Abrechnung">
Für Provider, die Usage-/Abrechnungsdaten bereitstellen:
<Tab title="Nutzung und Abrechnung">
Für Provider, die Nutzungs-/Abrechnungsdaten bereitstellen:
```typescript
resolveUsageAuth: async (ctx) => {
@ -462,80 +467,80 @@ API-Key-Auth und dynamischer Modellauflösung.
<Accordion title="Alle verfügbaren Provider-Hooks">
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.<id>`-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).
</Accordion>
</Step>
<Step title="Zusätzliche Fähigkeiten hinzufügen (optional)">
<a id="step-5-add-extra-capabilities"></a>
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.
</Step>
@ -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
```
<bundled-plugin-root>/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

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

@ -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`).

96
docs/de/providers/inferrs.md
View File

@ -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)

145
docs/de/providers/ollama.md
View File

@ -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.
<Warning>
**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`).
</Warning>
## 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
```
<Warning>
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.
</Warning>
### 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
<Warning>
**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.
</Warning>
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

126
docs/de/providers/qwen.md
View File

@ -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:
<Warning>
**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).
</Warning>
@ -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`).