From cdd5c2463fddfa7a2a6561923a1cca0862a3d2fd Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 11 Apr 2026 15:23:46 +0000 Subject: [PATCH] chore(i18n): refresh de translations --- docs/de/gateway/configuration-reference.md | 1276 ++++++++--------- .../gpt54-codex-agentic-parity-maintainers.md | 174 +++ docs/de/help/gpt54-codex-agentic-parity.md | 229 +++ docs/de/plugins/architecture.md | 1195 +++++++-------- docs/de/plugins/manifest.md | 438 +++--- docs/de/reference/rich-output-protocol.md | 60 + docs/de/tools/video-generation.md | 312 ++-- 7 files changed, 2114 insertions(+), 1570 deletions(-) create mode 100644 docs/de/help/gpt54-codex-agentic-parity-maintainers.md create mode 100644 docs/de/help/gpt54-codex-agentic-parity.md create mode 100644 docs/de/reference/rich-output-protocol.md diff --git a/docs/de/gateway/configuration-reference.md b/docs/de/gateway/configuration-reference.md index 1e8daaa30..947e5da49 100644 --- a/docs/de/gateway/configuration-reference.md +++ b/docs/de/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - Sie benötigen die exakte feldbezogene Konfigurationssemantik oder Standardwerte. - - Sie validieren Kanal-, Modell-, Gateway- oder Tool-Konfigurationsblöcke. -summary: Gateway-Konfigurationsreferenz für zentrale OpenClaw-Schlüssel, Standardwerte und Links zu dedizierten Subsystem-Referenzen + - Sie benötigen genaue feldbezogene Konfigurationssemantik oder Standardwerte + - Sie validieren Kanal-, Modell-, Gateway- oder Tool-Konfigurationsblöcke +summary: Gateway-Konfigurationsreferenz für zentrale OpenClaw-Schlüssel, Standardwerte und Links zu dedizierten Subsystemreferenzen title: Konfigurationsreferenz x-i18n: - generated_at: "2026-04-11T02:44:17Z" + generated_at: "2026-04-11T15:15:58Z" model: gpt-5.4 provider: openai - source_hash: 32acb82e756e4740d13ef12277842081f4c90df7b67850c34f8a76701fcd37d0 + source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,19 +17,19 @@ x-i18n: Zentrale Konfigurationsreferenz für `~/.openclaw/openclaw.json`. Eine aufgabenorientierte Übersicht finden Sie unter [Konfiguration](/de/gateway/configuration). -Diese Seite behandelt die wichtigsten OpenClaw-Konfigurationsoberflächen und verweist weiter, wenn ein Subsystem eine eigene ausführlichere Referenz hat. Sie versucht **nicht**, jeden kanal-/plugin-eigenen Befehlskatalog oder jede tiefgehende Speicher-/QMD-Einstellung auf einer Seite einzubetten. +Diese Seite behandelt die wichtigsten OpenClaw-Konfigurationsbereiche und verweist weiter, wenn ein Subsystem eine eigene, ausführlichere Referenz hat. Sie versucht **nicht**, jeden kanal-/plugin-eigenen Befehlskatalog oder jede tiefe Speicher-/QMD-Einstellung auf einer einzigen Seite inline aufzuführen. -Code-Referenz: +Code-Quelle der Wahrheit: -- `openclaw config schema` gibt das Live-JSON-Schema aus, das für die Validierung und die Control UI verwendet wird, wobei Metadaten aus gebündelten Plugins/Kanälen zusammengeführt werden, wenn verfügbar -- `config.schema.lookup` gibt einen einzelnen pfadbezogenen Schemaknoten für Drill-down-Tools zurück +- `openclaw config schema` gibt das Live-JSON-Schema aus, das für die Validierung und die Control UI verwendet wird, wobei gebündelte Plugin-/Kanal-Metadaten zusammengeführt werden, wenn verfügbar +- `config.schema.lookup` gibt einen einzelnen pfadbezogenen Schemaknoten für Drilldown-Tools zurück - `pnpm config:docs:check` / `pnpm config:docs:gen` validieren den Baseline-Hash der Konfigurationsdokumentation gegen die aktuelle Schemaoberfläche -Dedizierte ausführliche Referenzen: +Dedizierte Detailreferenzen: - [Speicherkonfigurationsreferenz](/de/reference/memory-config) für `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` und Dreaming-Konfiguration unter `plugins.entries.memory-core.config.dreaming` - [Slash-Befehle](/de/tools/slash-commands) für den aktuellen integrierten + gebündelten Befehlskatalog -- zuständige Kanal-/Plugin-Seiten für kanalspezifische Befehlsoberflächen +- Seiten des jeweiligen Kanal-/Plugin-Eigentümers für kanalspezifische Befehlsoberflächen Das Konfigurationsformat ist **JSON5** (Kommentare + nachgestellte Kommas erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden. @@ -43,28 +43,28 @@ Jeder Kanal startet automatisch, wenn sein Konfigurationsabschnitt vorhanden ist Alle Kanäle unterstützen DM-Richtlinien und Gruppenrichtlinien: -| DM-Richtlinie | Verhalten | -| -------------------- | -------------------------------------------------------------- | +| DM-Richtlinie | Verhalten | +| ------------------- | -------------------------------------------------------------- | | `pairing` (Standard) | Unbekannte Absender erhalten einen einmaligen Pairing-Code; der Eigentümer muss zustimmen | -| `allowlist` | Nur Absender in `allowFrom` (oder im gepaarten Allow-Store) | -| `open` | Alle eingehenden DMs zulassen (erfordert `allowFrom: ["*"]`) | -| `disabled` | Alle eingehenden DMs ignorieren | +| `allowlist` | Nur Absender in `allowFrom` (oder gepaarter Allow-Store) | +| `open` | Alle eingehenden DMs zulassen (erfordert `allowFrom: ["*"]`) | +| `disabled` | Alle eingehenden DMs ignorieren | -| Gruppenrichtlinie | Verhalten | -| ---------------------- | ----------------------------------------------------- | +| Gruppenrichtlinie | Verhalten | +| --------------------- | ------------------------------------------------------ | | `allowlist` (Standard) | Nur Gruppen, die der konfigurierten Allowlist entsprechen | -| `open` | Gruppen-Allowlists umgehen (Mention-Gating gilt weiterhin) | -| `disabled` | Alle Gruppen-/Raumnachrichten blockieren | +| `open` | Gruppen-Allowlists umgehen (Mention-Gating gilt weiterhin) | +| `disabled` | Alle Gruppen-/Raumnachrichten blockieren | -`channels.defaults.groupPolicy` setzt den Standardwert, wenn die `groupPolicy` eines Providers nicht gesetzt ist. +`channels.defaults.groupPolicy` legt den Standard fest, wenn `groupPolicy` eines Providers nicht gesetzt ist. Pairing-Codes laufen nach 1 Stunde ab. Ausstehende DM-Pairing-Anfragen sind auf **3 pro Kanal** begrenzt. -Wenn ein Provider-Block vollständig fehlt (`channels.` nicht vorhanden), fällt die Gruppenrichtlinie zur Laufzeit auf `allowlist` zurück (Fail-Closed) und erzeugt beim Start eine Warnung. +Fehlt ein Provider-Block vollständig (`channels.` nicht vorhanden), fällt die Laufzeit-Gruppenrichtlinie auf `allowlist` zurück (fail-closed) und es wird eine Startwarnung ausgegeben. ### Kanal-Modellüberschreibungen -Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu binden. Werte akzeptieren `provider/model` oder konfigurierte Modell-Aliase. Die Kanalzuordnung wird angewendet, wenn eine Sitzung noch keine Modellüberschreibung hat (zum Beispiel durch `/model` gesetzt). +Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu binden. Werte akzeptieren `provider/model` oder konfigurierte Modell-Aliasse. Die Kanalzuordnung wird angewendet, wenn eine Sitzung noch keine Modellüberschreibung hat (zum Beispiel durch `/model` gesetzt). ```json5 { @@ -85,9 +85,9 @@ Verwenden Sie `channels.modelByChannel`, um bestimmte Kanal-IDs an ein Modell zu } ``` -### Kanalstandards und Heartbeat +### Kanal-Standards und Heartbeat -Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heartbeat-Verhalten über Provider hinweg: +Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heartbeat-Verhalten über alle Provider hinweg: ```json5 { @@ -105,15 +105,15 @@ Verwenden Sie `channels.defaults` für gemeinsames Gruppenrichtlinien- und Heart } ``` -- `channels.defaults.groupPolicy`: Fallback-Gruppenrichtlinie, wenn eine providerbezogene `groupPolicy` nicht gesetzt ist. -- `channels.defaults.contextVisibility`: Standardmodus für die Sichtbarkeit ergänzenden Kontexts für alle Kanäle. Werte: `all` (Standard, schließt allen zitierten/Thread-/Verlaufs-Kontext ein), `allowlist` (schließt nur Kontext von Absendern auf der Allowlist ein), `allowlist_quote` (wie allowlist, behält aber expliziten Zitat-/Antwort-Kontext bei). Überschreibung pro Kanal: `channels..contextVisibility`. +- `channels.defaults.groupPolicy`: Fallback-Gruppenrichtlinie, wenn eine Provider-spezifische `groupPolicy` nicht gesetzt ist. +- `channels.defaults.contextVisibility`: Standardmodus für die Sichtbarkeit ergänzenden Kontexts für alle Kanäle. Werte: `all` (Standard, allen zitierten/Thread-/Verlaufs-Kontext einschließen), `allowlist` (nur Kontext von zugelassenen Absendern einschließen), `allowlist_quote` (wie allowlist, aber expliziten Zitat-/Antwortkontext beibehalten). Kanalbezogene Überschreibung: `channels..contextVisibility`. - `channels.defaults.heartbeat.showOk`: Gesunde Kanalstatus in die Heartbeat-Ausgabe aufnehmen. -- `channels.defaults.heartbeat.showAlerts`: Beeinträchtigte/Fehlerstatus in die Heartbeat-Ausgabe aufnehmen. -- `channels.defaults.heartbeat.useIndicator`: Kompakte Heartbeat-Ausgabe im Stil eines Indikators rendern. +- `channels.defaults.heartbeat.showAlerts`: Degradierte/Fehlerstatus in die Heartbeat-Ausgabe aufnehmen. +- `channels.defaults.heartbeat.useIndicator`: Kompakte Heartbeat-Ausgabe im Indikatorstil rendern. ### WhatsApp -WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet automatisch, wenn eine verknüpfte Sitzung vorhanden ist. +WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Er startet automatisch, wenn eine verknüpfte Sitzung vorhanden ist. ```json5 { @@ -124,7 +124,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // blaue Häkchen (false im Selbstchat-Modus) groups: { "*": { requireMention: true }, }, @@ -146,7 +146,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom } ``` - + ```json5 { @@ -164,10 +164,10 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom } ``` -- Ausgehende Befehle verwenden standardmäßig das Konto `default`, wenn es vorhanden ist; andernfalls die erste konfigurierte Konto-ID (sortiert). -- Optional überschreibt `channels.whatsapp.defaultAccount` diese Fallback-Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. -- Das Legacy-Baileys-Authentifizierungsverzeichnis für Einzelkonten wird von `openclaw doctor` nach `whatsapp/default` migriert. -- Überschreibungen pro Konto: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Ausgehende Befehle verwenden standardmäßig das Konto `default`, falls vorhanden; andernfalls die erste konfigurierte Konto-ID (sortiert). +- Optional überschreibt `channels.whatsapp.defaultAccount` diese Fallback-Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- Das Legacy-Baileys-Authentifizierungsverzeichnis für ein einzelnes Konto wird von `openclaw doctor` nach `whatsapp/default` migriert. +- Pro-Konto-Überschreibungen: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -226,12 +226,12 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom ``` - Bot-Token: `channels.telegram.botToken` oder `channels.telegram.tokenFile` (nur reguläre Datei; Symlinks werden abgelehnt), mit `TELEGRAM_BOT_TOKEN` als Fallback für das Standardkonto. -- Optional überschreibt `channels.telegram.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. -- In Multi-Konto-Setups (2+ Konto-IDs) setzen Sie explizit ein Standardkonto (`channels.telegram.defaultAccount` oder `channels.telegram.accounts.default`), um Fallback-Routing zu vermeiden; `openclaw doctor` warnt, wenn dies fehlt oder ungültig ist. -- `configWrites: false` blockiert von Telegram initiierte Konfigurationsschreibvorgänge (Supergruppen-ID-Migrationen, `/config set|unset`). -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` konfigurieren persistente ACP-Bindings für Forenthemen (verwenden Sie das kanonische `chatId:topic:topicId` in `match.peer.id`). Die Feldsemantik ist gemeinsam in [ACP-Agenten](/de/tools/acp-agents#channel-specific-settings) beschrieben. +- Optional überschreibt `channels.telegram.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- In Multi-Konto-Setups (2+ Konto-IDs) sollten Sie einen expliziten Standard setzen (`channels.telegram.defaultAccount` oder `channels.telegram.accounts.default`), um Fallback-Routing zu vermeiden; `openclaw doctor` warnt, wenn dies fehlt oder ungültig ist. +- `configWrites: false` blockiert von Telegram initiierte Konfigurationsschreibvorgänge (Supergroup-ID-Migrationen, `/config set|unset`). +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` konfigurieren persistente ACP-Bindungen für Forenthemen (verwenden Sie das kanonische `chatId:topic:topicId` in `match.peer.id`). Die Feldsemantik wird gemeinsam unter [ACP Agents](/de/tools/acp-agents#channel-specific-settings) beschrieben. - Telegram-Stream-Vorschauen verwenden `sendMessage` + `editMessageText` (funktioniert in Direkt- und Gruppenchats). -- Wiederholungsrichtlinie: siehe [Wiederholungsrichtlinie](/de/concepts/retry). +- Retry-Richtlinie: siehe [Retry-Richtlinie](/de/concepts/retry). ### Discord @@ -297,7 +297,7 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // Opt-in für sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,33 +334,33 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom ``` - Token: `channels.discord.token`, mit `DISCORD_BOT_TOKEN` als Fallback für das Standardkonto. -- Direkte ausgehende Aufrufe, die ein explizites Discord-`token` bereitstellen, verwenden dieses Token für den Aufruf; Wiederholungs-/Richtlinieneinstellungen des Kontos stammen weiterhin aus dem ausgewählten Konto im aktiven Laufzeit-Snapshot. -- Optional überschreibt `channels.discord.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. -- Verwenden Sie `user:` (DM) oder `channel:` (Guild-Kanal) als Zustellziele; numerische IDs ohne Präfix werden abgelehnt. -- Guild-Slugs sind klein geschrieben, wobei Leerzeichen durch `-` ersetzt werden; Kanalschlüssel verwenden den Slug-Namen (ohne `#`). Bevorzugen Sie Guild-IDs. +- Direkte ausgehende Aufrufe, die ein explizites Discord-`token` bereitstellen, verwenden dieses Token für den Aufruf; Konto-Retry-/Richtlinieneinstellungen kommen weiterhin vom ausgewählten Konto im aktiven Laufzeit-Snapshot. +- Optional überschreibt `channels.discord.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- Verwenden Sie `user:` (DM) oder `channel:` (Guild-Kanal) für Zustellziele; reine numerische IDs werden abgelehnt. +- Guild-Slugs sind kleingeschrieben, wobei Leerzeichen durch `-` ersetzt werden; Kanalschlüssel verwenden den Slug-Namen (ohne `#`). Bevorzugen Sie Guild-IDs. - Von Bots verfasste Nachrichten werden standardmäßig ignoriert. `allowBots: true` aktiviert sie; verwenden Sie `allowBots: "mentions"`, um nur Bot-Nachrichten zu akzeptieren, die den Bot erwähnen (eigene Nachrichten werden weiterhin gefiltert). -- `channels.discord.guilds..ignoreOtherMentions` (und Kanalüberschreibungen) verwirft Nachrichten, die einen anderen Benutzer oder eine andere Rolle erwähnen, aber nicht den Bot (ausgenommen @everyone/@here). +- `channels.discord.guilds..ignoreOtherMentions` (und Kanal-Überschreibungen) verwirft Nachrichten, die einen anderen Nutzer oder eine andere Rolle erwähnen, aber nicht den Bot (ausgenommen @everyone/@here). - `maxLinesPerMessage` (Standard 17) teilt hohe Nachrichten auf, selbst wenn sie unter 2000 Zeichen liegen. -- `channels.discord.threadBindings` steuert das an Discord-Threads gebundene Routing: - - `enabled`: Discord-Überschreibung für an Threads gebundene Sitzungsfunktionen (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` sowie gebundene Zustellung/Weiterleitung) - - `idleHours`: Discord-Überschreibung für automatisches Aufheben des Fokus bei Inaktivität in Stunden (`0` deaktiviert) - - `maxAgeHours`: Discord-Überschreibung für das harte Maximalalter in Stunden (`0` deaktiviert) +- `channels.discord.threadBindings` steuert an Discord-Threads gebundenes Routing: + - `enabled`: Discord-Überschreibung für an Threads gebundene Sitzungsfunktionen (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` sowie gebundene Zustellung/gebundenes Routing) + - `idleHours`: Discord-Überschreibung für automatisches Entfokussieren bei Inaktivität in Stunden (`0` deaktiviert) + - `maxAgeHours`: Discord-Überschreibung für das harte maximale Alter in Stunden (`0` deaktiviert) - `spawnSubagentSessions`: Opt-in-Schalter für die automatische Thread-Erstellung/-Bindung durch `sessions_spawn({ thread: true })` -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` konfigurieren persistente ACP-Bindings für Kanäle und Threads (verwenden Sie die Kanal-/Thread-ID in `match.peer.id`). Die Feldsemantik ist gemeinsam in [ACP-Agenten](/de/tools/acp-agents#channel-specific-settings) beschrieben. -- `channels.discord.ui.components.accentColor` setzt die Akzentfarbe für Discord Components v2-Container. -- `channels.discord.voice` aktiviert Unterhaltungen in Discord-Sprachkanälen sowie optionale Auto-Join- und TTS-Überschreibungen. -- `channels.discord.voice.daveEncryption` und `channels.discord.voice.decryptionFailureTolerance` werden an die DAVE-Optionen von `@discordjs/voice` durchgereicht (standardmäßig `true` und `24`). -- OpenClaw versucht zusätzlich, den Sprach-Empfang wiederherzustellen, indem nach wiederholten Entschlüsselungsfehlern eine Sprachsitzung verlassen und erneut beigetreten wird. -- `channels.discord.streaming` ist der kanonische Schlüssel für den Stream-Modus. Legacy-`streamMode`- und boolesche `streaming`-Werte werden automatisch migriert. -- `channels.discord.autoPresence` ordnet die Laufzeitverfügbarkeit der Bot-Präsenz zu (healthy => online, degraded => idle, exhausted => dnd) und ermöglicht optionale Überschreibungen des Statustexts. -- `channels.discord.dangerouslyAllowNameMatching` aktiviert abgleichbare Namen/Tags mit veränderlichem Wert erneut (Break-Glass-Kompatibilitätsmodus). -- `channels.discord.execApprovals`: Discord-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern. - - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmiger aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. - - `approvers`: Discord-Benutzer-IDs, die Exec-Anfragen genehmigen dürfen. Fällt auf `commands.ownerAllowFrom` zurück, wenn nicht angegeben. - - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. - - `sessionFilter`: optionale Sitzungsschlüsselmuster (Teilstring oder Regex). - - `target`: wohin Genehmigungsaufforderungen gesendet werden. `"dm"` (Standard) sendet an DMs der Genehmiger, `"channel"` sendet an den Ursprungskanal, `"both"` sendet an beide. Wenn das Ziel `"channel"` enthält, sind Schaltflächen nur für aufgelöste Genehmiger nutzbar. - - `cleanupAfterResolve`: wenn `true`, werden Genehmigungs-DMs nach Genehmigung, Ablehnung oder Zeitüberschreitung gelöscht. +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` konfigurieren persistente ACP-Bindungen für Kanäle und Threads (verwenden Sie die Kanal-/Thread-ID in `match.peer.id`). Die Feldsemantik wird gemeinsam unter [ACP Agents](/de/tools/acp-agents#channel-specific-settings) beschrieben. +- `channels.discord.ui.components.accentColor` legt die Akzentfarbe für Discord-Components-v2-Container fest. +- `channels.discord.voice` aktiviert Gespräche in Discord-Sprachkanälen sowie optionale automatische Beitritte und TTS-Überschreibungen. +- `channels.discord.voice.daveEncryption` und `channels.discord.voice.decryptionFailureTolerance` werden an die DAVE-Optionen von `@discordjs/voice` durchgereicht (standardmäßig `true` bzw. `24`). +- OpenClaw versucht zusätzlich, den Sprach-Empfang wiederherzustellen, indem es nach wiederholten Entschlüsselungsfehlern eine Sprachsitzung verlässt und erneut beitritt. +- `channels.discord.streaming` ist der kanonische Schlüssel für den Stream-Modus. Veraltete Werte für `streamMode` und boolesches `streaming` werden automatisch migriert. +- `channels.discord.autoPresence` ordnet die Laufzeitverfügbarkeit dem Bot-Status zu (healthy => online, degraded => idle, exhausted => dnd) und erlaubt optionale Überschreibungen des Statustexts. +- `channels.discord.dangerouslyAllowNameMatching` aktiviert veränderliches Namens-/Tag-Matching erneut (Break-Glass-Kompatibilitätsmodus). +- `channels.discord.execApprovals`: Discord-native Übermittlung von Exec-Genehmigungen und Autorisierung von Genehmigenden. + - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmigende aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. + - `approvers`: Discord-Nutzer-IDs, die Exec-Anfragen genehmigen dürfen. Fällt auf `commands.ownerAllowFrom` zurück, wenn nicht angegeben. + - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Genehmigungen für alle Agents weiterzuleiten. + - `sessionFilter`: optionale Sitzungs-Schlüsselmuster (Teilzeichenfolge oder Regex). + - `target`: wohin Genehmigungsabfragen gesendet werden. `"dm"` (Standard) sendet an die DMs der Genehmigenden, `"channel"` sendet in den Ursprungskanal, `"both"` sendet an beide. Wenn `target` `"channel"` enthält, sind Buttons nur für aufgelöste Genehmigende nutzbar. + - `cleanupAfterResolve`: wenn `true`, werden Genehmigungs-DMs nach Genehmigung, Ablehnung oder Timeout gelöscht. **Modi für Reaktionsbenachrichtigungen:** `off` (keine), `own` (Nachrichten des Bots, Standard), `all` (alle Nachrichten), `allowlist` (aus `guilds..users` für alle Nachrichten). @@ -395,9 +395,9 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom - Service-Account-JSON: inline (`serviceAccount`) oder dateibasiert (`serviceAccountFile`). - Service-Account-SecretRef wird ebenfalls unterstützt (`serviceAccountRef`). -- Env-Fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` oder `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Verwenden Sie `spaces/` oder `users/` als Zustellziele. -- `channels.googlechat.dangerouslyAllowNameMatching` aktiviert den Abgleich veränderlicher E-Mail-Principals erneut (Break-Glass-Kompatibilitätsmodus). +- Umgebungs-Fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` oder `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Verwenden Sie `spaces/` oder `users/` für Zustellziele. +- `channels.googlechat.dangerouslyAllowNameMatching` aktiviert veränderliches Matching von E-Mail-Principals erneut (Break-Glass-Kompatibilitätsmodus). ### Slack @@ -464,34 +464,34 @@ WhatsApp läuft über den Web-Kanal des Gateways (Baileys Web). Es startet autom } ``` -- **Socket-Modus** erfordert sowohl `botToken` als auch `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` als Env-Fallback für das Standardkonto). +- **Socket-Modus** erfordert sowohl `botToken` als auch `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` als Umgebungs-Fallback für das Standardkonto). - **HTTP-Modus** erfordert `botToken` plus `signingSecret` (auf Root-Ebene oder pro Konto). -- `botToken`, `appToken`, `signingSecret` und `userToken` akzeptieren Klartext-Strings oder SecretRef-Objekte. -- Slack-Konto-Snapshots stellen pro Anmeldedaten Quelle-/Status-Felder bereit, zum Beispiel `botTokenSource`, `botTokenStatus`, `appTokenStatus` und im HTTP-Modus `signingSecretStatus`. `configured_unavailable` bedeutet, dass das Konto über SecretRef konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den Secret-Wert jedoch nicht auflösen konnte. +- `botToken`, `appToken`, `signingSecret` und `userToken` akzeptieren Klartextzeichenfolgen oder SecretRef-Objekte. +- Slack-Konto-Snapshots stellen quellen-/statusbezogene Felder pro Zugangsdaten bereit, wie `botTokenSource`, `botTokenStatus`, `appTokenStatus` und im HTTP-Modus `signingSecretStatus`. `configured_unavailable` bedeutet, dass das Konto über SecretRef konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den Secret-Wert aber nicht auflösen konnte. - `configWrites: false` blockiert von Slack initiierte Konfigurationsschreibvorgänge. -- Optional überschreibt `channels.slack.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. -- `channels.slack.streaming.mode` ist der kanonische Schlüssel für den Slack-Stream-Modus. `channels.slack.streaming.nativeTransport` steuert Slacks nativen Streaming-Transport. Legacy-`streamMode`, boolesche `streaming`- und `nativeStreaming`-Werte werden automatisch migriert. -- Verwenden Sie `user:` (DM) oder `channel:` als Zustellziele. +- Optional überschreibt `channels.slack.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- `channels.slack.streaming.mode` ist der kanonische Schlüssel für den Slack-Stream-Modus. `channels.slack.streaming.nativeTransport` steuert Slacks nativen Streaming-Transport. Veraltete Werte für `streamMode`, boolesches `streaming` und `nativeStreaming` werden automatisch migriert. +- Verwenden Sie `user:` (DM) oder `channel:` für Zustellziele. **Modi für Reaktionsbenachrichtigungen:** `off`, `own` (Standard), `all`, `allowlist` (aus `reactionAllowlist`). -**Thread-Sitzungsisolierung:** `thread.historyScope` ist pro Thread (Standard) oder über den Kanal geteilt. `thread.inheritParent` kopiert das Transkript des übergeordneten Kanals in neue Threads. +**Thread-Sitzungsisolierung:** `thread.historyScope` ist pro Thread (Standard) oder kanalübergreifend gemeinsam. `thread.inheritParent` kopiert das übergeordnete Kanal-Transkript in neue Threads. -- Slack natives Streaming plus der Slack-Assistentenstil-Thread-Status „is typing...“ erfordern ein Antwort-Thread-Ziel. Top-Level-DMs bleiben standardmäßig außerhalb von Threads, daher verwenden sie stattdessen `typingReaction` oder die normale Zustellung anstelle der Vorschau im Thread-Stil. -- `typingReaction` fügt der eingehenden Slack-Nachricht vorübergehend eine Reaktion hinzu, während eine Antwort ausgeführt wird, und entfernt sie nach Abschluss wieder. Verwenden Sie einen Slack-Emoji-Shortcode wie `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: Slack-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern. Dasselbe Schema wie bei Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack-Benutzer-IDs), `agentFilter`, `sessionFilter` und `target` (`"dm"`, `"channel"` oder `"both"`). +- Slack-Native-Streaming plus der Slack-assistentenartige Thread-Status „is typing...“ erfordern ein Antwort-Thread-Ziel. Top-Level-DMs bleiben standardmäßig außerhalb von Threads, daher verwenden sie stattdessen `typingReaction` oder normale Zustellung statt der Thread-Vorschau. +- `typingReaction` fügt der eingehenden Slack-Nachricht temporär eine Reaktion hinzu, während eine Antwort läuft, und entfernt sie nach Abschluss wieder. Verwenden Sie einen Slack-Emoji-Shortcode wie `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: Slack-native Übermittlung von Exec-Genehmigungen und Autorisierung von Genehmigenden. Gleiches Schema wie bei Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack-Nutzer-IDs), `agentFilter`, `sessionFilter` und `target` (`"dm"`, `"channel"` oder `"both"`). -| Aktionsgruppe | Standard | Hinweise | -| ------------- | -------- | ------------------------ | +| Aktionsgruppe | Standard | Hinweise | +| ------------- | -------- | ------------------------- | | reactions | aktiviert | Reagieren + Reaktionen auflisten | -| messages | aktiviert | Lesen/senden/bearbeiten/löschen | -| pins | aktiviert | Anheften/lösen/auflisten | -| memberInfo | aktiviert | Mitgliederinformationen | -| emojiList | aktiviert | Benutzerdefinierte Emoji-Liste | +| messages | aktiviert | Lesen/Senden/Bearbeiten/Löschen | +| pins | aktiviert | Anheften/Lösen/Auflisten | +| memberInfo | aktiviert | Mitgliedsinformationen | +| emojiList | aktiviert | Liste benutzerdefinierter Emojis | ### Mattermost -Mattermost wird als Plugin ausgeliefert: `openclaw plugins install @openclaw/mattermost`. +Mattermost wird als Plugin bereitgestellt: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -511,7 +511,7 @@ Mattermost wird als Plugin ausgeliefert: `openclaw plugins install @openclaw/mat native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // Optional explizite URL für Reverse-Proxy-/öffentliche Bereitstellungen callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,18 +521,18 @@ Mattermost wird als Plugin ausgeliefert: `openclaw plugins install @openclaw/mat } ``` -Chat-Modi: `oncall` (antwortet bei @-Erwähnung, Standard), `onmessage` (jede Nachricht), `onchar` (Nachrichten, die mit einem Trigger-Präfix beginnen). +Chat-Modi: `oncall` (bei @-Erwähnung antworten, Standard), `onmessage` (jede Nachricht), `onchar` (Nachrichten, die mit dem Auslöserpräfix beginnen). Wenn native Mattermost-Befehle aktiviert sind: - `commands.callbackPath` muss ein Pfad sein (zum Beispiel `/api/channels/mattermost/command`), keine vollständige URL. -- `commands.callbackUrl` muss auf den OpenClaw-Gateway-Endpunkt aufgelöst werden und vom Mattermost-Server aus erreichbar sein. -- Native Slash-Callbacks werden mit den tokens pro Befehl authentifiziert, die von Mattermost bei der Registrierung von Slash-Befehlen zurückgegeben werden. Wenn die Registrierung fehlschlägt oder keine Befehle aktiviert sind, lehnt OpenClaw Callbacks mit `Unauthorized: invalid command token.` ab. -- Für private/Tailnet-/interne Callback-Hosts kann Mattermost verlangen, dass `ServiceSettings.AllowedUntrustedInternalConnections` den Callback-Host bzw. die Domain enthält. Verwenden Sie Host-/Domain-Werte, keine vollständigen URLs. -- `channels.mattermost.configWrites`: Mattermost-initiierte Konfigurationsschreibvorgänge zulassen oder ablehnen. -- `channels.mattermost.requireMention`: `@mention` verlangen, bevor in Kanälen geantwortet wird. +- `commands.callbackUrl` muss auf den OpenClaw-Gateway-Endpunkt zeigen und vom Mattermost-Server erreichbar sein. +- Native Slash-Callbacks werden mit den pro Befehl gültigen Tokens authentifiziert, die Mattermost bei der Registrierung von Slash-Befehlen zurückgibt. Wenn die Registrierung fehlschlägt oder keine Befehle aktiviert werden, lehnt OpenClaw Callbacks mit `Unauthorized: invalid command token.` ab. +- Für private/Tailnet/interne Callback-Hosts kann Mattermost verlangen, dass `ServiceSettings.AllowedUntrustedInternalConnections` den Callback-Host bzw. die Callback-Domain enthält. Verwenden Sie Host-/Domain-Werte, keine vollständigen URLs. +- `channels.mattermost.configWrites`: Mattermost-initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- `channels.mattermost.requireMention`: `@mention` vor der Antwort in Kanälen verlangen. - `channels.mattermost.groups..requireMention`: kanalbezogene Überschreibung für Mention-Gating (`"*"` für Standard). -- Optional überschreibt `channels.mattermost.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. +- Optional überschreibt `channels.mattermost.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. ### Signal @@ -541,7 +541,7 @@ Wenn native Mattermost-Befehle aktiviert sind: channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // optionale Kontobindung dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -556,12 +556,12 @@ Wenn native Mattermost-Befehle aktiviert sind: **Modi für Reaktionsbenachrichtigungen:** `off`, `own` (Standard), `all`, `allowlist` (aus `reactionAllowlist`). - `channels.signal.account`: bindet den Kanalstart an eine bestimmte Signal-Kontoidentität. -- `channels.signal.configWrites`: von Signal initiierte Konfigurationsschreibvorgänge zulassen oder ablehnen. -- Optional überschreibt `channels.signal.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. +- `channels.signal.configWrites`: von Signal initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- Optional überschreibt `channels.signal.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. ### BlueBubbles -BlueBubbles ist der empfohlene iMessage-Pfad (plugin-basiert, konfiguriert unter `channels.bluebubbles`). +BlueBubbles ist der empfohlene iMessage-Pfad (plugin-gestützt, konfiguriert unter `channels.bluebubbles`). ```json5 { @@ -569,21 +569,21 @@ BlueBubbles ist der empfohlene iMessage-Pfad (plugin-basiert, konfiguriert unter bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, Gruppensteuerung und erweiterte Aktionen: - // siehe /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` -- Hier abgedeckte zentrale Schlüsselpfade: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Optional überschreibt `channels.bluebubbles.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` können BlueBubbles-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie einen BlueBubbles-Handle oder Ziel-String (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP-Agenten](/de/tools/acp-agents#channel-specific-settings). +- Hier behandelte zentrale Schlüsselpfade: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Optional überschreibt `channels.bluebubbles.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` können BlueBubbles-Konversationen an persistente ACP-Sitzungen binden. Verwenden Sie einen BlueBubbles-Handle oder Ziel-String (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP Agents](/de/tools/acp-agents#channel-specific-settings). - Die vollständige BlueBubbles-Kanalkonfiguration ist unter [BlueBubbles](/de/channels/bluebubbles) dokumentiert. ### iMessage -OpenClaw startet `imsg rpc` (`JSON-RPC` über stdio). Kein Daemon oder Port erforderlich. +OpenClaw startet `imsg rpc` (JSON-RPC über stdio). Kein Daemon oder Port erforderlich. ```json5 { @@ -607,15 +607,15 @@ OpenClaw startet `imsg rpc` (`JSON-RPC` über stdio). Kein Daemon oder Port erfo } ``` -- Optional überschreibt `channels.imessage.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. +- Optional überschreibt `channels.imessage.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. - Erfordert Vollzugriff auf die Messages-Datenbank. -- Bevorzugen Sie `chat_id:`-Ziele. Verwenden Sie `imsg chats --limit 20`, um Chats aufzulisten. -- `cliPath` kann auf einen SSH-Wrapper verweisen; setzen Sie `remoteHost` (`host` oder `user@host`) für das Abrufen von Anhängen per SCP. -- `attachmentRoots` und `remoteAttachmentRoots` beschränken eingehende Anhangspfade (Standard: `/Users/*/Library/Messages/Attachments`). -- SCP verwendet strikte Host-Key-Prüfung, stellen Sie daher sicher, dass der Relay-Host-Key bereits in `~/.ssh/known_hosts` vorhanden ist. -- `channels.imessage.configWrites`: von iMessage initiierte Konfigurationsschreibvorgänge zulassen oder ablehnen. -- Top-Level-Einträge in `bindings[]` mit `type: "acp"` können iMessage-Unterhaltungen an persistente ACP-Sitzungen binden. Verwenden Sie einen normalisierten Handle oder ein explizites Chat-Ziel (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP-Agenten](/de/tools/acp-agents#channel-specific-settings). +- Bevorzugen Sie Ziele im Format `chat_id:`. Verwenden Sie `imsg chats --limit 20`, um Chats aufzulisten. +- `cliPath` kann auf einen SSH-Wrapper zeigen; setzen Sie `remoteHost` (`host` oder `user@host`) für das Abrufen von Anhängen per SCP. +- `attachmentRoots` und `remoteAttachmentRoots` beschränken Pfade eingehender Anhänge (Standard: `/Users/*/Library/Messages/Attachments`). +- SCP verwendet strikte Host-Key-Prüfung, stellen Sie also sicher, dass der Schlüssel des Relay-Hosts bereits in `~/.ssh/known_hosts` vorhanden ist. +- `channels.imessage.configWrites`: von iMessage initiierte Konfigurationsschreibvorgänge erlauben oder verweigern. +- Top-Level-`bindings[]`-Einträge mit `type: "acp"` können iMessage-Konversationen an persistente ACP-Sitzungen binden. Verwenden Sie einen normalisierten Handle oder ein explizites Chat-Ziel (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) in `match.peer.id`. Gemeinsame Feldsemantik: [ACP Agents](/de/tools/acp-agents#channel-specific-settings). @@ -628,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix ist extension-basiert und wird unter `channels.matrix` konfiguriert. +Matrix wird durch eine Erweiterung bereitgestellt und unter `channels.matrix` konfiguriert. ```json5 { @@ -659,24 +659,24 @@ Matrix ist extension-basiert und wird unter `channels.matrix` konfiguriert. ``` - Token-Authentifizierung verwendet `accessToken`; Passwort-Authentifizierung verwendet `userId` + `password`. -- `channels.matrix.proxy` leitet Matrix-HTTP-Datenverkehr über einen expliziten HTTP(S)-Proxy. Benannte Konten können ihn mit `channels.matrix.accounts..proxy` überschreiben. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` erlaubt private/interne Homeserver. `proxy` und dieses Netzwerk-Opt-in sind voneinander unabhängige Einstellungen. +- `channels.matrix.proxy` leitet Matrix-HTTP-Datenverkehr über einen expliziten HTTP(S)-Proxy. Benannte Konten können dies mit `channels.matrix.accounts..proxy` überschreiben. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` erlaubt private/interne Homeserver. `proxy` und diese Netzwerk-Opt-in-Einstellung sind unabhängige Steuerungen. - `channels.matrix.defaultAccount` wählt in Multi-Konto-Setups das bevorzugte Konto aus. -- `channels.matrix.autoJoin` ist standardmäßig `off`, daher werden eingeladene Räume und neue DM-artige Einladungen ignoriert, bis Sie `autoJoin: "allowlist"` mit `autoJoinAllowlist` oder `autoJoin: "always"` setzen. -- `channels.matrix.execApprovals`: Matrix-native Zustellung von Exec-Genehmigungen und Autorisierung von Genehmigern. - - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmiger aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. - - `approvers`: Matrix-Benutzer-IDs (z. B. `@owner:example.org`), die Exec-Anfragen genehmigen dürfen. - - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Genehmigungen für alle Agenten weiterzuleiten. - - `sessionFilter`: optionale Sitzungsschlüsselmuster (Teilstring oder Regex). - - `target`: wohin Genehmigungsaufforderungen gesendet werden. `"dm"` (Standard), `"channel"` (Ursprungsraum) oder `"both"`. - - Überschreibungen pro Konto: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` steuert, wie Matrix-DMs in Sitzungen gruppiert werden: `per-user` (Standard) teilt nach weitergeleitetem Peer, während `per-room` jeden DM-Raum isoliert. -- Matrix-Statusprüfungen und Live-Verzeichnisabfragen verwenden dieselbe Proxy-Richtlinie wie der Laufzeitverkehr. +- `channels.matrix.autoJoin` ist standardmäßig `off`, daher werden Einladungen in Räume und neue DM-artige Einladungen ignoriert, bis Sie `autoJoin: "allowlist"` mit `autoJoinAllowlist` oder `autoJoin: "always"` setzen. +- `channels.matrix.execApprovals`: Matrix-native Übermittlung von Exec-Genehmigungen und Autorisierung von Genehmigenden. + - `enabled`: `true`, `false` oder `"auto"` (Standard). Im Auto-Modus werden Exec-Genehmigungen aktiviert, wenn Genehmigende aus `approvers` oder `commands.ownerAllowFrom` aufgelöst werden können. + - `approvers`: Matrix-Nutzer-IDs (z. B. `@owner:example.org`), die Exec-Anfragen genehmigen dürfen. + - `agentFilter`: optionale Allowlist für Agent-IDs. Weglassen, um Genehmigungen für alle Agents weiterzuleiten. + - `sessionFilter`: optionale Sitzungs-Schlüsselmuster (Teilzeichenfolge oder Regex). + - `target`: wohin Genehmigungsabfragen gesendet werden. `"dm"` (Standard), `"channel"` (Ursprungsraum) oder `"both"`. + - Pro-Konto-Überschreibungen: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` steuert, wie Matrix-DMs in Sitzungen gruppiert werden: `per-user` (Standard) wird nach geroutetem Peer geteilt, während `per-room` jeden DM-Raum isoliert. +- Matrix-Status-Probes und Live-Verzeichnisabfragen verwenden dieselbe Proxy-Richtlinie wie der Laufzeitdatenverkehr. - Die vollständige Matrix-Konfiguration, Zielregeln und Einrichtungsbeispiele sind unter [Matrix](/de/channels/matrix) dokumentiert. ### Microsoft Teams -Microsoft Teams ist extension-basiert und wird unter `channels.msteams` konfiguriert. +Microsoft Teams wird durch eine Erweiterung bereitgestellt und unter `channels.msteams` konfiguriert. ```json5 { @@ -684,19 +684,19 @@ Microsoft Teams ist extension-basiert und wird unter `channels.msteams` konfigur msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, Team-/Kanalrichtlinien: - // siehe /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` -- Hier abgedeckte zentrale Schlüsselpfade: `channels.msteams`, `channels.msteams.configWrites`. -- Die vollständige Teams-Konfiguration (Anmeldedaten, Webhook, DM-/Gruppenrichtlinie, Überschreibungen pro Team/pro Kanal) ist unter [Microsoft Teams](/de/channels/msteams) dokumentiert. +- Hier behandelte zentrale Schlüsselpfade: `channels.msteams`, `channels.msteams.configWrites`. +- Die vollständige Teams-Konfiguration (Anmeldedaten, Webhook, DM-/Gruppenrichtlinie, team-/kanalbezogene Überschreibungen) ist unter [Microsoft Teams](/de/channels/msteams) dokumentiert. ### IRC -IRC ist extension-basiert und wird unter `channels.irc` konfiguriert. +IRC wird durch eine Erweiterung bereitgestellt und unter `channels.irc` konfiguriert. ```json5 { @@ -717,11 +717,11 @@ IRC ist extension-basiert und wird unter `channels.irc` konfiguriert. } ``` -- Hier abgedeckte zentrale Schlüsselpfade: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Optional überschreibt `channels.irc.defaultAccount` die Auswahl des Standardkontos, wenn es einer konfigurierten Konto-ID entspricht. +- Hier behandelte zentrale Schlüsselpfade: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Optional überschreibt `channels.irc.defaultAccount` die Auswahl des Standardkontos, wenn es mit einer konfigurierten Konto-ID übereinstimmt. - Die vollständige IRC-Kanalkonfiguration (Host/Port/TLS/Kanäle/Allowlists/Mention-Gating) ist unter [IRC](/de/channels/irc) dokumentiert. -### Multi-Konto (alle Kanäle) +### Mehrere Konten (alle Kanäle) Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener `accountId`): @@ -744,28 +744,28 @@ Führen Sie mehrere Konten pro Kanal aus (jedes mit eigener `accountId`): } ``` -- `default` wird verwendet, wenn `accountId` ausgelassen wird (CLI + Routing). -- Env-Tokens gelten nur für das **Standard**konto. +- `default` wird verwendet, wenn `accountId` weggelassen wird (CLI + Routing). +- Umgebungs-Token gelten nur für das **default**-Konto. - Basis-Kanaleinstellungen gelten für alle Konten, sofern sie nicht pro Konto überschrieben werden. -- Verwenden Sie `bindings[].match.accountId`, um jedes Konto an einen anderen Agenten weiterzuleiten. -- Wenn Sie über `openclaw channels add` (oder das Kanal-Onboarding) ein Nicht-Standardkonto hinzufügen, während Sie sich noch in einer Top-Level-Kanalkonfiguration für ein Einzelkonto befinden, verschiebt OpenClaw zunächst kontobezogene Top-Level-Einzelkontowerte in die Kontozuordnung des Kanals, damit das ursprüngliche Konto weiter funktioniert. Die meisten Kanäle verschieben sie nach `channels..accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. -- Bestehende kanalbezogene Bindings (ohne `accountId`) bleiben dem Standardkonto zugeordnet; kontobezogene Bindings bleiben optional. -- `openclaw doctor --fix` repariert auch gemischte Formen, indem kontobezogene Top-Level-Einzelkontowerte in das für diesen Kanal ausgewählte hochgestufte Konto verschoben werden. Die meisten Kanäle verwenden `accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. +- Verwenden Sie `bindings[].match.accountId`, um jedes Konto an einen anderen Agent zu routen. +- Wenn Sie über `openclaw channels add` (oder Kanal-Onboarding) ein Nicht-Standardkonto hinzufügen, während Sie sich noch in einer Top-Level-Kanalkonfiguration für ein einzelnes Konto befinden, verschiebt OpenClaw zunächst kontoabhängige Top-Level-Einzelkonto-Werte in die Kontozuordnung des Kanals, damit das ursprüngliche Konto weiter funktioniert. Die meisten Kanäle verschieben sie nach `channels..accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. +- Bestehende kanalbezogene Bindungen (ohne `accountId`) passen weiterhin auf das Standardkonto; kontobezogene Bindungen bleiben optional. +- `openclaw doctor --fix` repariert auch gemischte Formen, indem kontoabhängige Top-Level-Einzelkonto-Werte in das für diesen Kanal gewählte hochgestufte Konto verschoben werden. Die meisten Kanäle verwenden `accounts.default`; Matrix kann stattdessen ein vorhandenes passendes benanntes/Standardziel beibehalten. -### Andere extension-basierte Kanäle +### Andere Erweiterungskanäle -Viele extension-basierte Kanäle werden als `channels.` konfiguriert und auf ihren dedizierten Kanalseiten dokumentiert (zum Beispiel Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat und Twitch). -Siehe den vollständigen Kanalindex: [Kanäle](/de/channels). +Viele Erweiterungskanäle werden als `channels.` konfiguriert und auf ihren dedizierten Kanalseiten dokumentiert (zum Beispiel Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat und Twitch). +Den vollständigen Kanalindex finden Sie unter: [Kanäle](/de/channels). ### Mention-Gating in Gruppenchats -Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erwähnung oder sichere Regex-Muster). Gilt für WhatsApp-, Telegram-, Discord-, Google Chat- und iMessage-Gruppenchats. +Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erwähnung oder sichere Regex-Muster). Gilt für WhatsApp, Telegram, Discord, Google Chat und iMessage-Gruppenchats. -**Erwähnungstypen:** +**Mention-Typen:** -- **Metadaten-Erwähnungen**: Native Plattform-@-Erwähnungen. Im WhatsApp-Self-Chat-Modus ignoriert. +- **Metadaten-Erwähnungen**: Native @-Erwähnungen der Plattform. Im WhatsApp-Selbstchat-Modus ignoriert. - **Textmuster**: Sichere Regex-Muster in `agents.list[].groupChat.mentionPatterns`. Ungültige Muster und unsichere verschachtelte Wiederholungen werden ignoriert. -- Mention-Gating wird nur erzwungen, wenn Erkennung möglich ist (native Erwähnungen oder mindestens ein Muster). +- Mention-Gating wird nur erzwungen, wenn eine Erkennung möglich ist (native Erwähnungen oder mindestens ein Muster). ```json5 { @@ -778,9 +778,9 @@ Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erw } ``` -`messages.groupChat.historyLimit` setzt den globalen Standardwert. Kanäle können ihn mit `channels..historyLimit` (oder pro Konto) überschreiben. Setzen Sie `0`, um ihn zu deaktivieren. +`messages.groupChat.historyLimit` legt den globalen Standard fest. Kanäle können dies mit `channels..historyLimit` (oder pro Konto) überschreiben. Setzen Sie `0`, um es zu deaktivieren. -#### DM-Verlaufslimits +#### DM-Verlaufsgrenzen ```json5 { @@ -795,13 +795,13 @@ Gruppennachrichten erfordern standardmäßig **eine Erwähnung** (Metadaten-Erw } ``` -Auflösung: Überschreibung pro DM → Provider-Standard → kein Limit (alles wird beibehalten). +Auflösung: DM-spezifische Überschreibung → Provider-Standard → keine Begrenzung (alles bleibt erhalten). Unterstützt: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Self-Chat-Modus +#### Selbstchat-Modus -Fügen Sie Ihre eigene Nummer zu `allowFrom` hinzu, um den Self-Chat-Modus zu aktivieren (ignoriert native @-Erwähnungen, antwortet nur auf Textmuster): +Fügen Sie Ihre eigene Nummer zu `allowFrom` hinzu, um den Selbstchat-Modus zu aktivieren (ignoriert native @-Erwähnungen, reagiert nur auf Textmuster): ```json5 { @@ -827,16 +827,16 @@ Fügen Sie Ihre eigene Nummer zu `allowFrom` hinzu, um den Self-Chat-Modus zu ak ```json5 { commands: { - native: "auto", // native Befehle registrieren, wenn unterstützt - nativeSkills: "auto", // native Skill-Befehle registrieren, wenn unterstützt - text: true, // /commands in Chat-Nachrichten parsen - bash: false, // ! zulassen (Alias: /bash) + native: "auto", // native commands when supported register + nativeSkills: "auto", // native skill commands when supported register + text: true, // /commands in chat messages parsen + bash: false, // ! erlauben (Alias: /bash) bashForegroundMs: 2000, - config: false, // /config zulassen - mcp: false, // /mcp zulassen - plugins: false, // /plugins zulassen - debug: false, // /debug zulassen - restart: true, // /restart + Gateway-Neustart-Tool zulassen + config: false, // /config erlauben + mcp: false, // /mcp erlauben + plugins: false, // /plugins erlauben + debug: false, // /debug erlauben + restart: true, // /restart + Gateway-Neustart-Tool erlauben ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -852,37 +852,37 @@ Fügen Sie Ihre eigene Nummer zu `allowFrom` hinzu, um den Self-Chat-Modus zu ak - Dieser Block konfiguriert Befehlsoberflächen. Den aktuellen integrierten + gebündelten Befehlskatalog finden Sie unter [Slash-Befehle](/de/tools/slash-commands). -- Diese Seite ist eine **Konfigurationsschlüssel-Referenz**, nicht der vollständige Befehlskatalog. Kanal-/plugin-eigene Befehle wie QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` und Talk `/voice` sind auf ihren Kanal-/Plugin-Seiten sowie unter [Slash-Befehle](/de/tools/slash-commands) dokumentiert. -- Textbefehle müssen **eigenständige** Nachrichten mit führendem `/` sein. +- Diese Seite ist eine **Referenz für Konfigurationsschlüssel**, nicht der vollständige Befehlskatalog. Kanal-/plugin-eigene Befehle wie QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` und Talk `/voice` sind auf ihren Kanal-/Plugin-Seiten sowie unter [Slash-Befehle](/de/tools/slash-commands) dokumentiert. +- Textbefehle müssen **eigenständige** Nachrichten sein, die mit `/` beginnen. - `native: "auto"` aktiviert native Befehle für Discord/Telegram und lässt Slack deaktiviert. -- `nativeSkills: "auto"` aktiviert native Skill-Befehle für Discord/Telegram und lässt Slack deaktiviert. -- Überschreibung pro Kanal: `channels.discord.commands.native` (bool oder `"auto"`). `false` löscht zuvor registrierte Befehle. +- `nativeSkills: "auto"` aktiviert native Skills-Befehle für Discord/Telegram und lässt Slack deaktiviert. +- Pro Kanal überschreiben mit: `channels.discord.commands.native` (bool oder `"auto"`). `false` entfernt zuvor registrierte Befehle. - Überschreiben Sie die Registrierung nativer Skills pro Kanal mit `channels..commands.nativeSkills`. - `channels.telegram.customCommands` fügt zusätzliche Telegram-Bot-Menüeinträge hinzu. -- `bash: true` aktiviert `! ` für die Host-Shell. Erfordert `tools.elevated.enabled` und einen Absender in `tools.elevated.allowFrom.`. -- `config: true` aktiviert `/config` (liest/schreibt `openclaw.json`). Für Gateway-`chat.send`-Clients erfordern persistente Schreibvorgänge über `/config set|unset` zusätzlich `operator.admin`; schreibgeschütztes `/config show` bleibt für normale Operator-Clients mit Schreibbereich verfügbar. +- `bash: true` aktiviert `! ` für die Host-Shell. Erfordert `tools.elevated.enabled` und dass sich der Absender in `tools.elevated.allowFrom.` befindet. +- `config: true` aktiviert `/config` (liest/schreibt `openclaw.json`). Für Gateway-`chat.send`-Clients erfordern persistente Schreibvorgänge mit `/config set|unset` außerdem `operator.admin`; das schreibgeschützte `/config show` bleibt für normale Operator-Clients mit Schreibbereich verfügbar. - `mcp: true` aktiviert `/mcp` für von OpenClaw verwaltete MCP-Serverkonfiguration unter `mcp.servers`. -- `plugins: true` aktiviert `/plugins` für Plugin-Erkennung, Installation sowie Aktivierungs-/Deaktivierungssteuerung. +- `plugins: true` aktiviert `/plugins` für Plugin-Erkennung, Installation sowie Steuerelemente zum Aktivieren/Deaktivieren. - `channels..configWrites` steuert Konfigurationsänderungen pro Kanal (Standard: true). -- Für Multi-Konto-Kanäle steuert `channels..accounts..configWrites` auch Schreibvorgänge, die dieses Konto betreffen (zum Beispiel `/allowlist --config --account ` oder `/config set channels..accounts....`). -- `restart: false` deaktiviert `/restart` und Aktionen des Gateway-Neustart-Tools. Standard: `true`. -- `ownerAllowFrom` ist die explizite Owner-Allowlist für nur für den Eigentümer bestimmte Befehle/Tools. Sie ist von `allowFrom` getrennt. +- Für Multi-Konto-Kanäle steuert `channels..accounts..configWrites` auch Schreibvorgänge, die auf dieses Konto zielen (zum Beispiel `/allowlist --config --account ` oder `/config set channels..accounts....`). +- `restart: false` deaktiviert `/restart` und Gateway-Neustart-Tool-Aktionen. Standard: `true`. +- `ownerAllowFrom` ist die explizite Eigentümer-Allowlist für nur für Eigentümer bestimmte Befehle/Tools. Sie ist von `allowFrom` getrennt. - `ownerDisplay: "hash"` hasht Eigentümer-IDs im System-Prompt. Setzen Sie `ownerDisplaySecret`, um das Hashing zu steuern. -- `allowFrom` ist providerbezogen. Wenn gesetzt, ist es die **einzige** Autorisierungsquelle (Kanal-Allowlists/Pairing und `useAccessGroups` werden ignoriert). -- `useAccessGroups: false` erlaubt Befehlen, Access-Group-Richtlinien zu umgehen, wenn `allowFrom` nicht gesetzt ist. +- `allowFrom` ist pro Provider. Wenn gesetzt, ist es die **einzige** Autorisierungsquelle (Kanal-Allowlists/Pairing und `useAccessGroups` werden ignoriert). +- `useAccessGroups: false` erlaubt Befehlen, Zugriffsgruppenrichtlinien zu umgehen, wenn `allowFrom` nicht gesetzt ist. - Zuordnung der Befehlsdokumentation: - integrierter + gebündelter Katalog: [Slash-Befehle](/de/tools/slash-commands) - kanalspezifische Befehlsoberflächen: [Kanäle](/de/channels) - QQ-Bot-Befehle: [QQ Bot](/de/channels/qqbot) - Pairing-Befehle: [Pairing](/de/channels/pairing) - LINE-Card-Befehl: [LINE](/de/channels/line) - - memory dreaming: [Dreaming](/de/concepts/dreaming) + - Memory-Dreaming: [Dreaming](/de/concepts/dreaming) --- -## Agent-Standardwerte +## Agent-Standards ### `agents.defaults.workspace` @@ -896,7 +896,7 @@ Standard: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Optionales Repository-Root, das in der Runtime-Zeile des System-Prompts angezeigt wird. Wenn nicht gesetzt, erkennt OpenClaw es automatisch, indem es vom Workspace aus nach oben traversiert. +Optionales Repository-Root, das in der Runtime-Zeile des System-Prompts angezeigt wird. Wenn nicht gesetzt, erkennt OpenClaw es automatisch, indem es vom Workspace aus nach oben läuft. ```json5 { @@ -906,7 +906,7 @@ Optionales Repository-Root, das in der Runtime-Zeile des System-Prompts angezeig ### `agents.defaults.skills` -Optionale Standard-Skill-Allowlist für Agenten, die `agents.list[].skills` nicht setzen. +Optionale Standard-Allowlist für Skills für Agents, die `agents.list[].skills` nicht setzen. ```json5 { @@ -914,17 +914,17 @@ Optionale Standard-Skill-Allowlist für Agenten, die `agents.list[].skills` nich defaults: { skills: ["github", "weather"] }, list: [ { id: "writer" }, // erbt github, weather - { id: "docs", skills: ["docs-search"] }, // ersetzt Standardwerte + { id: "docs", skills: ["docs-search"] }, // ersetzt Standards { id: "locked-down", skills: [] }, // keine Skills ], }, } ``` -- Lassen Sie `agents.defaults.skills` weg, um standardmäßig uneingeschränkte Skills zu erlauben. -- Lassen Sie `agents.list[].skills` weg, um die Standardwerte zu erben. +- Lassen Sie `agents.defaults.skills` weg, um standardmäßig uneingeschränkte Skills zuzulassen. +- Lassen Sie `agents.list[].skills` weg, um die Standards zu erben. - Setzen Sie `agents.list[].skills: []` für keine Skills. -- Eine nicht leere Liste in `agents.list[].skills` ist die endgültige Menge für diesen Agenten; sie wird nicht mit Standardwerten zusammengeführt. +- Eine nicht leere Liste in `agents.list[].skills` ist die endgültige Menge für diesen Agent; sie wird nicht mit den Standards zusammengeführt. ### `agents.defaults.skipBootstrap` @@ -940,7 +940,7 @@ Deaktiviert die automatische Erstellung von Workspace-Bootstrap-Dateien (`AGENTS Steuert, wann Workspace-Bootstrap-Dateien in den System-Prompt eingefügt werden. Standard: `"always"`. -- `"continuation-skip"`: Sichere Fortsetzungs-Turns (nach einer abgeschlossenen Assistant-Antwort) überspringen das erneute Einfügen des Workspace-Bootstraps und verringern so die Prompt-Größe. Heartbeat-Läufe und Wiederholungen nach Kompaktierung bauen den Kontext weiterhin neu auf. +- `"continuation-skip"`: Sichere Fortsetzungs-Turns (nach einer abgeschlossenen Assistant-Antwort) überspringen das erneute Einfügen des Workspace-Bootstraps und reduzieren so die Prompt-Größe. Heartbeat-Läufe und Wiederholungen nach Kompaktierung bauen den Kontext weiterhin neu auf. ```json5 { @@ -950,7 +950,7 @@ Steuert, wann Workspace-Bootstrap-Dateien in den System-Prompt eingefügt werden ### `agents.defaults.bootstrapMaxChars` -Maximale Zeichenanzahl pro Workspace-Bootstrap-Datei vor der Kürzung. Standard: `20000`. +Maximale Zeichenanzahl pro Workspace-Bootstrap-Datei vor dem Abschneiden. Standard: `20000`. ```json5 { @@ -960,7 +960,7 @@ Maximale Zeichenanzahl pro Workspace-Bootstrap-Datei vor der Kürzung. Standard: ### `agents.defaults.bootstrapTotalMaxChars` -Maximale Gesamtzeichenanzahl, die über alle Workspace-Bootstrap-Dateien hinweg eingefügt wird. Standard: `150000`. +Maximale Gesamtzahl an eingefügten Zeichen über alle Workspace-Bootstrap-Dateien hinweg. Standard: `150000`. ```json5 { @@ -970,12 +970,12 @@ Maximale Gesamtzeichenanzahl, die über alle Workspace-Bootstrap-Dateien hinweg ### `agents.defaults.bootstrapPromptTruncationWarning` -Steuert den für Agenten sichtbaren Warntext, wenn Bootstrap-Kontext gekürzt wird. +Steuert den für Agents sichtbaren Warntext, wenn Bootstrap-Kontext abgeschnitten wird. Standard: `"once"`. -- `"off"`: Niemals Warntext in den System-Prompt einfügen. -- `"once"`: Warnung einmal pro eindeutiger Kürzungssignatur einfügen (empfohlen). -- `"always"`: Warnung bei jedem Lauf einfügen, wenn eine Kürzung vorliegt. +- `"off"`: Warntext niemals in den System-Prompt einfügen. +- `"once"`: Warnung einmal pro eindeutiger Abschneidesignatur einfügen (empfohlen). +- `"always"`: Warnung bei jedem Lauf einfügen, wenn Abschneidung vorhanden ist. ```json5 { @@ -985,10 +985,10 @@ Standard: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Maximale Pixelgröße für die längste Bildseite in Transkript-/Tool-Bildblöcken vor Provider-Aufrufen. +Maximale Pixelgröße der längsten Bildseite in Transcript-/Tool-Bildblöcken vor Provider-Aufrufen. Standard: `1200`. -Niedrigere Werte reduzieren in der Regel die Vision-Token-Nutzung und die Größe des Anfrage-Payloads bei screenshotlastigen Läufen. +Niedrigere Werte reduzieren in der Regel den Vision-Token-Verbrauch und die Größe der Anfrage-Payload bei screenshotlastigen Läufen. Höhere Werte erhalten mehr visuelle Details. ```json5 @@ -999,7 +999,7 @@ Höhere Werte erhalten mehr visuelle Details. ### `agents.defaults.userTimezone` -Zeitzone für den Kontext des System-Prompts (nicht für Nachrichtenzeitstempel). Fällt auf die Zeitzone des Hosts zurück. +Zeitzone für den Kontext im System-Prompt (nicht für Nachrichten-Zeitstempel). Fällt auf die Zeitzone des Hosts zurück. ```json5 { @@ -1009,7 +1009,7 @@ Zeitzone für den Kontext des System-Prompts (nicht für Nachrichtenzeitstempel) ### `agents.defaults.timeFormat` -Zeitformat im System-Prompt. Standard: `auto` (OS-Präferenz). +Zeitformat im System-Prompt. Standard: `auto` (OS-Einstellung). ```json5 { @@ -1070,44 +1070,44 @@ Zeitformat im System-Prompt. Standard: `auto` (OS-Präferenz). - Die String-Form setzt nur das primäre Modell. - Die Objekt-Form setzt das primäre Modell plus geordnete Failover-Modelle. - `imageModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird vom `image`-Toolpfad als Vision-Modellkonfiguration verwendet. - - Wird auch als Fallback-Routing verwendet, wenn das ausgewählte/Standardmodell keine Bildeingaben akzeptieren kann. + - Wird vom Tool-Pfad `image` als dessen Vision-Modellkonfiguration verwendet. + - Wird außerdem als Fallback-Routing verwendet, wenn das ausgewählte/standardmäßige Modell keine Bildeingaben akzeptieren kann. - `imageGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - Wird von der gemeinsamen Bildgenerierungsfunktion und jeder zukünftigen Tool-/Plugin-Oberfläche verwendet, die Bilder erzeugt. - Typische Werte: `google/gemini-3.1-flash-image-preview` für native Gemini-Bildgenerierung, `fal/fal-ai/flux/dev` für fal oder `openai/gpt-image-1` für OpenAI Images. - - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel (zum Beispiel `GEMINI_API_KEY` oder `GOOGLE_API_KEY` für `google/*`, `OPENAI_API_KEY` für `openai/*`, `FAL_KEY` für `fal/*`). - - Wenn nicht gesetzt, kann `image_generate` trotzdem einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die verbleibenden registrierten Bildgenerierungs-Provider in der Reihenfolge ihrer Provider-IDs. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel dazu (zum Beispiel `GEMINI_API_KEY` oder `GOOGLE_API_KEY` für `google/*`, `OPENAI_API_KEY` für `openai/*`, `FAL_KEY` für `fal/*`). + - Wenn nicht gesetzt, kann `image_generate` dennoch einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die übrigen registrierten Bildgenerierungs-Provider in Provider-ID-Reihenfolge. - `musicGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - Wird von der gemeinsamen Musikgenerierungsfunktion und dem integrierten Tool `music_generate` verwendet. - Typische Werte: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` oder `minimax/music-2.5+`. - - Wenn nicht gesetzt, kann `music_generate` trotzdem einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die verbleibenden registrierten Musikgenerierungs-Provider in der Reihenfolge ihrer Provider-IDs. - - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel. + - Wenn nicht gesetzt, kann `music_generate` dennoch einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die übrigen registrierten Musikgenerierungs-Provider in Provider-ID-Reihenfolge. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel dazu. - `videoGenerationModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - Wird von der gemeinsamen Videogenerierungsfunktion und dem integrierten Tool `video_generate` verwendet. - Typische Werte: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` oder `qwen/wan2.7-r2v`. - - Wenn nicht gesetzt, kann `video_generate` trotzdem einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die verbleibenden registrierten Videogenerierungs-Provider in der Reihenfolge ihrer Provider-IDs. - - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel. - - Der gebündelte Qwen-Videogenerierungs-Provider unterstützt bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingabevideos, 10 Sekunden Dauer sowie providerbezogene Optionen `size`, `aspectRatio`, `resolution`, `audio` und `watermark`. + - Wenn nicht gesetzt, kann `video_generate` dennoch einen authentifizierungsbasierten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die übrigen registrierten Videogenerierungs-Provider in Provider-ID-Reihenfolge. + - Wenn Sie direkt einen Provider/ein Modell auswählen, konfigurieren Sie auch die passende Provider-Authentifizierung bzw. den API-Schlüssel dazu. + - Der gebündelte Qwen-Videogenerierungs-Provider unterstützt bis zu 1 Ausgabevideo, 1 Eingabebild, 4 Eingangsvideos, 10 Sekunden Dauer sowie Provider-spezifische Optionen für `size`, `aspectRatio`, `resolution`, `audio` und `watermark`. - `pdfModel`: akzeptiert entweder einen String (`"provider/model"`) oder ein Objekt (`{ primary, fallbacks }`). - - Wird vom `pdf`-Tool für das Modell-Routing verwendet. + - Wird vom Tool `pdf` für das Modell-Routing verwendet. - Wenn nicht gesetzt, fällt das PDF-Tool auf `imageModel` und danach auf das aufgelöste Sitzungs-/Standardmodell zurück. -- `pdfMaxBytesMb`: Standard-PDF-Größenlimit für das `pdf`-Tool, wenn `maxBytesMb` nicht beim Aufruf übergeben wird. -- `pdfMaxPages`: Standard-Maximalanzahl an Seiten, die im Extraktions-Fallback-Modus des `pdf`-Tools berücksichtigt werden. -- `verboseDefault`: Standard-Verbose-Stufe für Agenten. Werte: `"off"`, `"on"`, `"full"`. Standard: `"off"`. -- `elevatedDefault`: Standardstufe für erhöhte Ausgabe bei Agenten. Werte: `"off"`, `"on"`, `"ask"`, `"full"`. Standard: `"on"`. -- `model.primary`: Format `provider/model` (z. B. `openai/gpt-5.4`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige Übereinstimmung eines konfigurierten Providers für genau diese Modell-ID und greift erst danach auf den konfigurierten Standard-Provider zurück (veraltetes Kompatibilitätsverhalten, daher möglichst explizit `provider/model` verwenden). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr anbietet, fällt OpenClaw auf das erste konfigurierte Provider-/Modellpaar zurück, anstatt einen veralteten entfernten Provider-Standard anzuzeigen. +- `pdfMaxBytesMb`: Standardgrößenlimit für PDFs im Tool `pdf`, wenn `maxBytesMb` beim Aufruf nicht übergeben wird. +- `pdfMaxPages`: Standardmaximalzahl von Seiten, die im Extraktions-Fallback-Modus des Tools `pdf` berücksichtigt werden. +- `verboseDefault`: Standard-Verbose-Level für Agents. Werte: `"off"`, `"on"`, `"full"`. Standard: `"off"`. +- `elevatedDefault`: Standard-Level für erhöhte Ausgabe für Agents. Werte: `"off"`, `"on"`, `"ask"`, `"full"`. Standard: `"on"`. +- `model.primary`: Format `provider/model` (z. B. `openai/gpt-5.4`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann einen eindeutigen configured-provider-Treffer für genau diese Modell-ID und fällt erst danach auf den konfigurierten Standard-Provider zurück (veraltetes Kompatibilitätsverhalten, daher bevorzugen Sie explizit `provider/model`). Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw auf das erste konfigurierte Provider-/Modellpaar zurück, statt einen veralteten Standard eines entfernten Providers anzuzeigen. - `models`: der konfigurierte Modellkatalog und die Allowlist für `/model`. Jeder Eintrag kann `alias` (Kurzform) und `params` (providerspezifisch, zum Beispiel `temperature`, `maxTokens`, `cacheRetention`, `context1m`) enthalten. - `params`: globale Standard-Provider-Parameter, die auf alle Modelle angewendet werden. Setzen Sie sie unter `agents.defaults.params` (z. B. `{ cacheRetention: "long" }`). -- Zusammenführungsreihenfolge von `params` (Konfiguration): `agents.defaults.params` (globale Basis) wird von `agents.defaults.models["provider/model"].params` (pro Modell) überschrieben, danach überschreibt `agents.list[].params` (mit passender Agent-ID) schlüsselweise. Details finden Sie unter [Prompt Caching](/de/reference/prompt-caching). -- `embeddedHarness`: Standardrichtlinie für die eingebettete Agent-Laufzeit auf niedriger Ebene. Verwenden Sie `runtime: "auto"`, damit registrierte Plugin-Harnesses unterstützte Modelle übernehmen können, `runtime: "pi"` zum Erzwingen des integrierten PI-Harnesses oder eine registrierte Harness-ID wie `runtime: "codex"`. Setzen Sie `fallback: "none"`, um den automatischen PI-Fallback zu deaktivieren. -- Konfigurationsschreiber, die diese Felder ändern (zum Beispiel `/models set`, `/models set-image` und Befehle zum Hinzufügen/Entfernen von Fallbacks), speichern die kanonische Objektform und erhalten vorhandene Fallback-Listen nach Möglichkeit. +- Merge-Priorität von `params` (Konfiguration): `agents.defaults.params` (globale Basis) wird durch `agents.defaults.models["provider/model"].params` (pro Modell) überschrieben, danach überschreibt `agents.list[].params` (passende Agent-ID) schlüsselweise. Details finden Sie unter [Prompt Caching](/de/reference/prompt-caching). +- `embeddedHarness`: standardmäßige Low-Level-Laufzeitrichtlinie für eingebettete Agents. Verwenden Sie `runtime: "auto"`, damit registrierte Plugin-Harnesses unterstützte Modelle beanspruchen können, `runtime: "pi"` zum Erzwingen des integrierten PI-Harnesses oder eine registrierte Harness-ID wie `runtime: "codex"`. Setzen Sie `fallback: "none"`, um den automatischen PI-Fallback zu deaktivieren. +- Konfigurationsschreiber, die diese Felder ändern (zum Beispiel `/models set`, `/models set-image` und Befehle zum Hinzufügen/Entfernen von Fallbacks), speichern die kanonische Objektform und erhalten vorhandene Fallback-Listen, wenn möglich. - `maxConcurrent`: maximale Anzahl paralleler Agent-Läufe über Sitzungen hinweg (jede Sitzung bleibt weiterhin serialisiert). Standard: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` steuert, welcher Low-Level-Executor eingebettete Agent-Turns ausführt. -Die meisten Deployments sollten den Standard `{ runtime: "auto", fallback: "pi" }` beibehalten. -Verwenden Sie es, wenn ein vertrauenswürdiges Plugin ein natives Harness bereitstellt, wie zum Beispiel das gebündelte Codex-App-Server-Harness. +Die meisten Bereitstellungen sollten den Standard `{ runtime: "auto", fallback: "pi" }` beibehalten. +Verwenden Sie dies, wenn ein vertrauenswürdiges Plugin ein natives Harness bereitstellt, etwa das gebündelte Codex-App-Server-Harness. ```json5 { @@ -1124,10 +1124,10 @@ Verwenden Sie es, wenn ein vertrauenswürdiges Plugin ein natives Harness bereit ``` - `runtime`: `"auto"`, `"pi"` oder eine registrierte Plugin-Harness-ID. Das gebündelte Codex-Plugin registriert `codex`. -- `fallback`: `"pi"` oder `"none"`. `"pi"` behält den integrierten PI-Harness als Kompatibilitäts-Fallback bei. `"none"` führt dazu, dass eine fehlende oder nicht unterstützte Plugin-Harness-Auswahl fehlschlägt, anstatt stillschweigend PI zu verwenden. +- `fallback`: `"pi"` oder `"none"`. `"pi"` behält den integrierten PI-Harness als Kompatibilitäts-Fallback bei. `"none"` führt dazu, dass eine fehlende oder nicht unterstützte Plugin-Harness-Auswahl fehlschlägt, statt stillschweigend PI zu verwenden. - Umgebungsüberschreibungen: `OPENCLAW_AGENT_RUNTIME=` überschreibt `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` deaktiviert den PI-Fallback für diesen Prozess. -- Für reine Codex-Deployments setzen Sie `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` und `embeddedHarness.fallback: "none"`. -- Dies steuert nur das eingebettete Chat-Harness. Mediengenerierung, Vision, PDF, Musik, Video und TTS verwenden weiterhin ihre Provider-/Modelleinstellungen. +- Für reine Codex-Bereitstellungen setzen Sie `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` und `embeddedHarness.fallback: "none"`. +- Dies steuert nur das eingebettete Chat-Harness. Mediengenerierung, Vision, PDF, Musik, Video und TTS verwenden weiterhin ihre Provider-/Modell-Einstellungen. **Integrierte Alias-Kurzformen** (gelten nur, wenn das Modell in `agents.defaults.models` enthalten ist): @@ -1142,15 +1142,15 @@ Verwenden Sie es, wenn ein vertrauenswürdiges Plugin ein natives Harness bereit | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ihre konfigurierten Aliase haben immer Vorrang vor den Standardwerten. +Ihre konfigurierten Aliasse haben immer Vorrang vor den Standardwerten. Z.AI-GLM-4.x-Modelle aktivieren den Thinking-Modus automatisch, sofern Sie nicht `--thinking off` setzen oder `agents.defaults.models["zai/"].params.thinking` selbst definieren. Z.AI-Modelle aktivieren standardmäßig `tool_stream` für Tool-Call-Streaming. Setzen Sie `agents.defaults.models["zai/"].params.tool_stream` auf `false`, um dies zu deaktivieren. -Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive` Thinking, wenn keine explizite Thinking-Stufe gesetzt ist. +Anthropic Claude 4.6-Modelle verwenden standardmäßig `adaptive` thinking, wenn kein explizites Thinking-Level gesetzt ist. ### `agents.defaults.cliBackends` -Optionale CLI-Backends für reine Text-Fallback-Läufe (ohne Tool-Calls). Nützlich als Reserve, wenn API-Provider ausfallen. +Optionale CLI-Backends für reine Text-Fallback-Läufe (ohne Tool-Aufrufe). Nützlich als Backup, wenn API-Provider ausfallen. ```json5 { @@ -1180,11 +1180,11 @@ Optionale CLI-Backends für reine Text-Fallback-Läufe (ohne Tool-Calls). Nützl - CLI-Backends sind textorientiert; Tools sind immer deaktiviert. - Sitzungen werden unterstützt, wenn `sessionArg` gesetzt ist. -- Bilddurchreichung wird unterstützt, wenn `imageArg` Dateipfade akzeptiert. +- Bild-Durchleitung wird unterstützt, wenn `imageArg` Dateipfade akzeptiert. ### `agents.defaults.systemPromptOverride` -Ersetzt den vollständig von OpenClaw zusammengesetzten System-Prompt durch einen festen String. Setzen Sie ihn auf der Standardebene (`agents.defaults.systemPromptOverride`) oder pro Agent (`agents.list[].systemPromptOverride`). Werte pro Agent haben Vorrang; ein leerer oder nur aus Leerzeichen bestehender Wert wird ignoriert. Nützlich für kontrollierte Prompt-Experimente. +Ersetzt den gesamten von OpenClaw zusammengesetzten System-Prompt durch eine feste Zeichenfolge. Auf der Standardebene (`agents.defaults.systemPromptOverride`) oder pro Agent (`agents.list[].systemPromptOverride`) setzen. Werte pro Agent haben Vorrang; ein leerer oder nur aus Leerraum bestehender Wert wird ignoriert. Nützlich für kontrollierte Prompt-Experimente. ```json5 { @@ -1210,7 +1210,7 @@ Periodische Heartbeat-Läufe. includeReasoning: false, includeSystemPromptSection: true, // Standard: true; false lässt den Heartbeat-Abschnitt im System-Prompt weg lightContext: false, // Standard: false; true behält nur HEARTBEAT.md aus den Workspace-Bootstrap-Dateien - isolatedSession: false, // Standard: false; true führt jeden Heartbeat in einer frischen Sitzung aus (kein Gesprächsverlauf) + isolatedSession: false, // Standard: false; true führt jeden Heartbeat in einer neuen Sitzung aus (kein Gesprächsverlauf) session: "main", to: "+15555550123", directPolicy: "allow", // allow (Standard) | block @@ -1225,15 +1225,15 @@ Periodische Heartbeat-Läufe. } ``` -- `every`: Dauer-String (ms/s/m/h). Standard: `30m` (API-Key-Authentifizierung) oder `1h` (OAuth-Authentifizierung). Setzen Sie `0m`, um zu deaktivieren. -- `includeSystemPromptSection`: wenn false, wird der Heartbeat-Abschnitt aus dem System-Prompt weggelassen und das Einfügen von `HEARTBEAT.md` in den Bootstrap-Kontext übersprungen. Standard: `true`. -- `suppressToolErrorWarnings`: wenn true, werden Payloads für Tool-Fehlerwarnungen während Heartbeat-Läufen unterdrückt. -- `timeoutSeconds`: maximal erlaubte Zeit in Sekunden für einen Heartbeat-Agent-Turn, bevor er abgebrochen wird. Nicht setzen, um `agents.defaults.timeoutSeconds` zu verwenden. +- `every`: Dauerzeichenfolge (ms/s/m/h). Standard: `30m` (API-Key-Authentifizierung) oder `1h` (OAuth-Authentifizierung). Auf `0m` setzen, um zu deaktivieren. +- `includeSystemPromptSection`: wenn false, lässt den Heartbeat-Abschnitt im System-Prompt weg und überspringt die Einfügung von `HEARTBEAT.md` in den Bootstrap-Kontext. Standard: `true`. +- `suppressToolErrorWarnings`: wenn true, werden Tool-Fehlerwarn-Payloads während Heartbeat-Läufen unterdrückt. +- `timeoutSeconds`: maximal zulässige Zeit in Sekunden für einen Heartbeat-Agent-Turn, bevor er abgebrochen wird. Nicht setzen, um `agents.defaults.timeoutSeconds` zu verwenden. - `directPolicy`: Richtlinie für direkte/DM-Zustellung. `allow` (Standard) erlaubt die direkte Zielzustellung. `block` unterdrückt die direkte Zielzustellung und erzeugt `reason=dm-blocked`. - `lightContext`: wenn true, verwenden Heartbeat-Läufe einen leichtgewichtigen Bootstrap-Kontext und behalten nur `HEARTBEAT.md` aus den Workspace-Bootstrap-Dateien. -- `isolatedSession`: wenn true, wird jeder Heartbeat in einer frischen Sitzung ohne vorherigen Gesprächsverlauf ausgeführt. Dasselbe Isolationsmuster wie bei Cron `sessionTarget: "isolated"`. Reduziert die Token-Kosten pro Heartbeat von etwa 100K auf etwa 2-5K Tokens. -- Pro Agent: setzen Sie `agents.list[].heartbeat`. Wenn ein beliebiger Agent `heartbeat` definiert, führen **nur diese Agenten** Heartbeats aus. -- Heartbeats führen vollständige Agent-Turns aus — kürzere Intervalle verbrauchen mehr Tokens. +- `isolatedSession`: wenn true, wird jeder Heartbeat in einer neuen Sitzung ohne vorherigen Gesprächsverlauf ausgeführt. Gleiches Isolationsmuster wie bei Cron `sessionTarget: "isolated"`. Reduziert die Token-Kosten pro Heartbeat von etwa 100K auf etwa 2-5K Token. +- Pro Agent: setzen Sie `agents.list[].heartbeat`. Wenn irgendein Agent `heartbeat` definiert, führen **nur diese Agents** Heartbeats aus. +- Heartbeats führen vollständige Agent-Turns aus — kürzere Intervalle verbrauchen mehr Token. ### `agents.defaults.compaction` @@ -1247,15 +1247,15 @@ Periodische Heartbeat-Läufe. timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Bereitstellungs-IDs, Ticket-IDs und Host:Port-Paare exakt beibehalten.", // wird verwendet, wenn identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] deaktiviert erneutes Einfügen + identifierInstructions: "Deployment-IDs, Ticket-IDs und Host:Port-Paare exakt beibehalten.", // wird verwendet, wenn identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] deaktiviert erneute Einfügung model: "openrouter/anthropic/claude-sonnet-4-6", // optionale nur für Compaction geltende Modellüberschreibung - notifyUser: true, // beim Start der Compaction eine kurze Benachrichtigung an den Benutzer senden (Standard: false) + notifyUser: true, // sendet einen kurzen Hinweis, wenn die Compaction beginnt (Standard: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, systemPrompt: "Sitzung nähert sich der Compaction. Dauerhafte Erinnerungen jetzt speichern.", - prompt: "Schreibe alle bleibenden Notizen in memory/YYYY-MM-DD.md; antworte mit dem exakten stillen Token NO_REPLY, wenn nichts zu speichern ist.", + prompt: "Schreiben Sie alle bleibenden Notizen in memory/YYYY-MM-DD.md; antworten Sie mit dem exakten stillen Token NO_REPLY, wenn nichts gespeichert werden soll.", }, }, }, @@ -1264,18 +1264,18 @@ Periodische Heartbeat-Läufe. ``` - `mode`: `default` oder `safeguard` (chunkweise Zusammenfassung für lange Verläufe). Siehe [Compaction](/de/concepts/compaction). -- `provider`: ID eines registrierten Compaction-Provider-Plugins. Wenn gesetzt, wird `summarize()` des Providers anstelle der integrierten LLM-Zusammenfassung aufgerufen. Fällt bei Fehlern auf die integrierte Variante zurück. Das Setzen eines Providers erzwingt `mode: "safeguard"`. Siehe [Compaction](/de/concepts/compaction). +- `provider`: ID eines registrierten Compaction-Provider-Plugins. Wenn gesetzt, wird `summarize()` des Providers anstelle der integrierten LLM-Zusammenfassung aufgerufen. Fällt bei Fehlern auf die integrierte Lösung zurück. Das Setzen eines Providers erzwingt `mode: "safeguard"`. Siehe [Compaction](/de/concepts/compaction). - `timeoutSeconds`: maximal zulässige Sekunden für einen einzelnen Compaction-Vorgang, bevor OpenClaw ihn abbricht. Standard: `900`. -- `identifierPolicy`: `strict` (Standard), `off` oder `custom`. `strict` stellt bei der Compaction-Zusammenfassung eine integrierte Anweisung zum Beibehalten undurchsichtiger Kennungen voran. -- `identifierInstructions`: optionaler benutzerdefinierter Text zur Beibehaltung von Kennungen, verwendet bei `identifierPolicy=custom`. -- `postCompactionSections`: optionale H2/H3-Abschnittsnamen aus AGENTS.md, die nach der Compaction erneut eingefügt werden. Standard ist `["Session Startup", "Red Lines"]`; setzen Sie `[]`, um das erneute Einfügen zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften `Every Session`/`Safety` auch als Legacy-Fallback akzeptiert. +- `identifierPolicy`: `strict` (Standard), `off` oder `custom`. `strict` stellt der Compaction-Zusammenfassung integrierte Anweisungen zum Beibehalten undurchsichtiger Bezeichner voran. +- `identifierInstructions`: optionaler benutzerdefinierter Text zur Beibehaltung von Bezeichnern, verwendet bei `identifierPolicy=custom`. +- `postCompactionSections`: optionale AGENTS.md-H2-/H3-Abschnittsnamen, die nach der Compaction erneut eingefügt werden. Standard ist `["Session Startup", "Red Lines"]`; setzen Sie `[]`, um die erneute Einfügung zu deaktivieren. Wenn nicht gesetzt oder explizit auf dieses Standardpaar gesetzt, werden ältere Überschriften `Every Session`/`Safety` auch als Legacy-Fallback akzeptiert. - `model`: optionale Überschreibung `provider/model-id` nur für die Compaction-Zusammenfassung. Verwenden Sie dies, wenn die Hauptsitzung ein Modell behalten soll, Compaction-Zusammenfassungen aber mit einem anderen Modell laufen sollen; wenn nicht gesetzt, verwendet die Compaction das primäre Modell der Sitzung. -- `notifyUser`: wenn `true`, sendet beim Start der Compaction eine kurze Benachrichtigung an den Benutzer (zum Beispiel „Compacting context...“). Standardmäßig deaktiviert, damit die Compaction still bleibt. -- `memoryFlush`: stiller agentischer Turn vor der automatischen Compaction zum Speichern dauerhafter Erinnerungen. Wird übersprungen, wenn der Workspace schreibgeschützt ist. +- `notifyUser`: wenn `true`, sendet einen kurzen Hinweis an den Benutzer, wenn die Compaction beginnt (zum Beispiel „Kontext wird kompaktiert...“). Standardmäßig deaktiviert, damit die Compaction still bleibt. +- `memoryFlush`: stiller agentischer Turn vor der automatischen Compaction, um dauerhafte Erinnerungen zu speichern. Wird übersprungen, wenn der Workspace schreibgeschützt ist. ### `agents.defaults.contextPruning` -Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor sie an das LLM gesendet werden. Ändert **nicht** den Sitzungsverlauf auf der Festplatte. +Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor dieser an das LLM gesendet wird. Ändert **nicht** den Sitzungsverlauf auf der Festplatte. ```json5 { @@ -1289,7 +1289,7 @@ Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor sie an das LL hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Alter Tool-Ergebnisinhalt entfernt]" }, + hardClear: { enabled: true, placeholder: "[Inhalt alter Tool-Ergebnisse entfernt]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1300,22 +1300,22 @@ Entfernt **alte Tool-Ergebnisse** aus dem In-Memory-Kontext, bevor sie an das LL - `mode: "cache-ttl"` aktiviert Pruning-Durchläufe. -- `ttl` steuert, wie oft Pruning erneut ausgeführt werden kann (nach dem letzten Cache-Touch). -- Beim Pruning werden zuerst übergroße Tool-Ergebnisse weich gekürzt und danach bei Bedarf ältere Tool-Ergebnisse vollständig entfernt. +- `ttl` steuert, wie oft das Pruning erneut ausgeführt werden kann (nach der letzten Cache-Berührung). +- Beim Pruning werden zuerst übergroße Tool-Ergebnisse weich gekürzt und danach bei Bedarf ältere Tool-Ergebnisse hart geleert. -**Soft-Trim** behält Anfang + Ende und fügt in der Mitte `...` ein. +**Soft-Trim** behält Anfang + Ende und fügt `...` in der Mitte ein. **Hard-Clear** ersetzt das gesamte Tool-Ergebnis durch den Platzhalter. Hinweise: -- Bildblöcke werden niemals gekürzt/entfernt. -- Verhältnisse basieren auf Zeichen (näherungsweise), nicht auf exakten Token-Anzahlen. -- Wenn weniger als `keepLastAssistants` Assistant-Nachrichten vorhanden sind, wird Pruning übersprungen. +- Bildblöcke werden niemals gekürzt/geleert. +- Verhältnisse basieren auf Zeichen (ungefähr), nicht auf exakten Token-Anzahlen. +- Wenn weniger als `keepLastAssistants` Assistant-Nachrichten vorhanden sind, wird das Pruning übersprungen. -Siehe [Session Pruning](/de/concepts/session-pruning) für Details zum Verhalten. +Details zum Verhalten finden Sie unter [Session Pruning](/de/concepts/session-pruning). ### Block-Streaming @@ -1327,7 +1327,7 @@ Siehe [Session Pruning](/de/concepts/session-pruning) für Details zum Verhalten blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (minMs/maxMs verwenden) + humanDelay: { mode: "natural" }, // off | natural | custom (verwenden Sie minMs/maxMs) }, }, } @@ -1337,7 +1337,7 @@ Siehe [Session Pruning](/de/concepts/session-pruning) für Details zum Verhalten - Kanalüberschreibungen: `channels..blockStreamingCoalesce` (und Varianten pro Konto). Signal/Slack/Discord/Google Chat verwenden standardmäßig `minChars: 1500`. - `humanDelay`: zufällige Pause zwischen Block-Antworten. `natural` = 800–2500 ms. Überschreibung pro Agent: `agents.list[].humanDelay`. -Siehe [Streaming](/de/concepts/streaming) für Details zu Verhalten + Chunking. +Verhaltens- und Chunking-Details finden Sie unter [Streaming](/de/concepts/streaming). ### Tippindikatoren @@ -1355,13 +1355,13 @@ Siehe [Streaming](/de/concepts/streaming) für Details zu Verhalten + Chunking. - Standardwerte: `instant` für Direktchats/Erwähnungen, `message` für Gruppenchats ohne Erwähnung. - Überschreibungen pro Sitzung: `session.typingMode`, `session.typingIntervalSeconds`. -Siehe [Tippindikatoren](/de/concepts/typing-indicators). +Siehe [Typing Indicators](/de/concepts/typing-indicators). ### `agents.defaults.sandbox` -Optionale Sandboxing-Funktion für den eingebetteten Agenten. Den vollständigen Leitfaden finden Sie unter [Sandboxing](/de/gateway/sandboxing). +Optionale Sandboxing-Funktion für den eingebetteten Agent. Die vollständige Anleitung finden Sie unter [Sandboxing](/de/gateway/sandboxing). ```json5 { @@ -1461,7 +1461,7 @@ Optionale Sandboxing-Funktion für den eingebetteten Agenten. Den vollständigen **Backend:** - `docker`: lokale Docker-Laufzeit (Standard) -- `ssh`: generische SSH-basierte Remote-Laufzeit +- `ssh`: generische SSH-gestützte Remote-Laufzeit - `openshell`: OpenShell-Laufzeit Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstellungen nach @@ -1471,10 +1471,10 @@ Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstell - `target`: SSH-Ziel im Format `user@host[:port]` - `command`: SSH-Client-Befehl (Standard: `ssh`) -- `workspaceRoot`: absoluter Remote-Root, der für Workspaces pro Scope verwendet wird +- `workspaceRoot`: absolutes Remote-Root, das für Workspaces pro Geltungsbereich verwendet wird - `identityFile` / `certificateFile` / `knownHostsFile`: vorhandene lokale Dateien, die an OpenSSH übergeben werden - `identityData` / `certificateData` / `knownHostsData`: Inline-Inhalte oder SecretRefs, die OpenClaw zur Laufzeit in temporäre Dateien materialisiert -- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH-Schalter für die Host-Key-Richtlinie +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH-Einstellungen für die Host-Key-Richtlinie **SSH-Authentifizierungspriorität:** @@ -1485,23 +1485,23 @@ Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstell **Verhalten des SSH-Backends:** -- initialisiert den Remote-Workspace einmal nach Erstellung oder Neuerstellung -- hält danach den Remote-SSH-Workspace als kanonisch -- leitet `exec`, Dateitools und Medienpfade über SSH +- initialisiert den Remote-Workspace einmal nach Erstellen oder Neuerstellen +- behält danach den Remote-SSH-Workspace als kanonisch bei +- leitet `exec`, Datei-Tools und Medienpfade über SSH - synchronisiert Remote-Änderungen nicht automatisch zurück zum Host - unterstützt keine Sandbox-Browser-Container **Workspace-Zugriff:** -- `none`: Sandbox-Workspace pro Scope unter `~/.openclaw/sandboxes` +- `none`: Sandbox-Workspace pro Geltungsbereich unter `~/.openclaw/sandboxes` - `ro`: Sandbox-Workspace unter `/workspace`, Agent-Workspace schreibgeschützt unter `/agent` eingehängt -- `rw`: Agent-Workspace unter `/workspace` mit Lese-/Schreibzugriff eingehängt +- `rw`: Agent-Workspace schreibend/lesend unter `/workspace` eingehängt -**Scope:** +**Geltungsbereich:** - `session`: Container + Workspace pro Sitzung - `agent`: ein Container + Workspace pro Agent (Standard) -- `shared`: gemeinsamer Container und Workspace (keine sitzungsübergreifende Isolation) +- `shared`: gemeinsamer Container und gemeinsamer Workspace (keine sitzungsübergreifende Isolation) **OpenShell-Plugin-Konfiguration:** @@ -1531,30 +1531,30 @@ Wenn `backend: "openshell"` ausgewählt ist, werden laufzeitspezifische Einstell **OpenShell-Modus:** -- `mirror`: initialisiert Remote aus lokal vor `exec`, synchronisiert nach `exec` zurück; der lokale Workspace bleibt kanonisch -- `remote`: initialisiert Remote einmal beim Erstellen der Sandbox und hält danach den Remote-Workspace als kanonisch +- `mirror`: Remote vor `exec` aus lokalem Stand initialisieren, nach `exec` zurücksynchronisieren; der lokale Workspace bleibt kanonisch +- `remote`: Remote einmal beim Erstellen der Sandbox initialisieren, danach bleibt der Remote-Workspace kanonisch -Im Modus `remote` werden host-lokale Änderungen, die außerhalb von OpenClaw vorgenommen werden, nach dem Initialisierungsschritt nicht automatisch in die Sandbox synchronisiert. +Im Modus `remote` werden hostlokale Bearbeitungen außerhalb von OpenClaw nach dem Initialisierungsschritt nicht automatisch in die Sandbox synchronisiert. Der Transport erfolgt per SSH in die OpenShell-Sandbox, aber das Plugin verwaltet den Sandbox-Lebenszyklus und die optionale Mirror-Synchronisierung. -**`setupCommand`** wird einmal nach der Erstellung des Containers ausgeführt (über `sh -lc`). Benötigt ausgehenden Netzwerkzugriff, beschreibbares Root-Dateisystem und Root-Benutzer. +**`setupCommand`** wird einmal nach der Erstellung des Containers ausgeführt (über `sh -lc`). Benötigt ausgehenden Netzwerkzugriff, ein beschreibbares Root-Dateisystem und Root-Benutzer. -**Container verwenden standardmäßig `network: "none"`** — setzen Sie es auf `"bridge"` (oder ein benutzerdefiniertes Bridge-Netzwerk), wenn der Agent ausgehenden Zugriff benötigt. -`"host"` ist blockiert. `"container:"` ist standardmäßig blockiert, es sei denn, Sie setzen explizit -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (Break-Glass). +**Container verwenden standardmäßig `network: "none"`** — setzen Sie auf `"bridge"` (oder ein benutzerdefiniertes Bridge-Netzwerk), wenn der Agent ausgehenden Zugriff benötigt. +`"host"` ist blockiert. `"container:"` ist standardmäßig blockiert, sofern Sie nicht explizit +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` setzen (Break-Glass). **Eingehende Anhänge** werden in `media/inbound/*` im aktiven Workspace bereitgestellt. **`docker.binds`** bindet zusätzliche Host-Verzeichnisse ein; globale und agentbezogene Bindings werden zusammengeführt. **Sandbox-Browser** (`sandbox.browser.enabled`): Chromium + CDP in einem Container. Die noVNC-URL wird in den System-Prompt eingefügt. Erfordert kein `browser.enabled` in `openclaw.json`. -noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung, und OpenClaw gibt eine URL mit kurzlebigem Token aus (anstatt das Passwort in der freigegebenen URL offenzulegen). +Der noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung, und OpenClaw gibt eine URL mit kurzlebigem Token aus (anstatt das Passwort in der gemeinsam genutzten URL offenzulegen). -- `allowHostControl: false` (Standard) blockiert, dass Sandbox-Sitzungen den Browser des Hosts ansprechen. -- `network` ist standardmäßig `openclaw-sandbox-browser` (dediziertes Bridge-Netzwerk). Setzen Sie es nur dann auf `bridge`, wenn Sie ausdrücklich globale Bridge-Konnektivität möchten. -- `cdpSourceRange` beschränkt optional den CDP-Eingang am Container-Rand auf einen CIDR-Bereich (zum Beispiel `172.21.0.1/32`). +- `allowHostControl: false` (Standard) blockiert, dass Sandbox-Sitzungen auf den Host-Browser zielen. +- `network` verwendet standardmäßig `openclaw-sandbox-browser` (dediziertes Bridge-Netzwerk). Setzen Sie es nur dann auf `bridge`, wenn Sie ausdrücklich globale Bridge-Konnektivität möchten. +- `cdpSourceRange` beschränkt optional eingehenden CDP-Zugriff am Container-Rand auf einen CIDR-Bereich (zum Beispiel `172.21.0.1/32`). - `sandbox.browser.binds` bindet zusätzliche Host-Verzeichnisse nur in den Sandbox-Browser-Container ein. Wenn gesetzt (einschließlich `[]`), ersetzt es `docker.binds` für den Browser-Container. -- Start-Standardwerte sind in `scripts/sandbox-browser-entrypoint.sh` definiert und für Container-Hosts abgestimmt: +- Start-Standards sind in `scripts/sandbox-browser-entrypoint.sh` definiert und auf Container-Hosts abgestimmt: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1572,17 +1572,17 @@ noVNC-Beobachterzugriff verwendet standardmäßig VNC-Authentifizierung, und Ope - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions` (standardmäßig aktiviert) - - `--disable-3d-apis`, `--disable-software-rasterizer` und `--disable-gpu` sind standardmäßig aktiviert und können mit `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` deaktiviert werden, falls die Verwendung von WebGL/3D dies erfordert. + - `--disable-3d-apis`, `--disable-software-rasterizer` und `--disable-gpu` sind standardmäßig aktiviert und können mit `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` deaktiviert werden, wenn WebGL-/3D-Nutzung dies erfordert. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` aktiviert Erweiterungen wieder, wenn Ihr Workflow davon abhängt. - - `--renderer-process-limit=2` kann mit `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` geändert werden; setzen Sie `0`, um das Standard-Prozesslimit von Chromium zu verwenden. + - `--renderer-process-limit=2` kann mit `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` geändert werden; setzen Sie `0`, um die Standard-Prozessgrenze von Chromium zu verwenden. - plus `--no-sandbox` und `--disable-setuid-sandbox`, wenn `noSandbox` aktiviert ist. - - Die Standardwerte sind die Basis des Container-Images; verwenden Sie ein benutzerdefiniertes Browser-Image mit benutzerdefiniertem Entrypoint, um die Container-Standardwerte zu ändern. + - Die Standards bilden die Basis des Container-Images; verwenden Sie ein benutzerdefiniertes Browser-Image mit einem benutzerdefinierten Entry-Point, um die Container-Standards zu ändern. Browser-Sandboxing und `sandbox.docker.binds` sind nur für Docker verfügbar. -Images bauen: +Images erstellen: ```bash scripts/sandbox-setup.sh # Haupt-Sandbox-Image @@ -1602,9 +1602,9 @@ scripts/sandbox-browser-setup.sh # optionales Browser-Image workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // oder { primary, fallbacks } - thinkingDefault: "high", // Überschreibung der Standard-Thinking-Stufe pro Agent + thinkingDefault: "high", // Überschreibung des Standard-Thinking-Levels pro Agent reasoningDefault: "on", // Überschreibung der Standard-Sichtbarkeit von Reasoning pro Agent - fastModeDefault: false, // Überschreibung des Standard-Fast-Modus pro Agent + fastModeDefault: false, // Überschreibung des Standard-Schnellmodus pro Agent embeddedHarness: { runtime: "auto", fallback: "pi" }, params: { cacheRetention: "none" }, // überschreibt passende defaults.models-Parameter schlüsselweise skills: ["docs-search"], // ersetzt agents.defaults.skills, wenn gesetzt @@ -1639,26 +1639,26 @@ scripts/sandbox-browser-setup.sh # optionales Browser-Image ``` - `id`: stabile Agent-ID (erforderlich). -- `default`: wenn mehrere gesetzt sind, gewinnt der erste (es wird eine Warnung protokolliert). Wenn keiner gesetzt ist, ist der erste Listeneintrag der Standard. -- `model`: Die String-Form überschreibt nur `primary`; die Objekt-Form `{ primary, fallbacks }` überschreibt beide (`[]` deaktiviert globale Fallbacks). Cron-Jobs, die nur `primary` überschreiben, erben weiterhin die Standard-Fallbacks, es sei denn, Sie setzen `fallbacks: []`. -- `params`: streambezogene Parameter pro Agent, zusammengeführt über dem ausgewählten Modelleintrag in `agents.defaults.models`. Verwenden Sie dies für agentenspezifische Überschreibungen wie `cacheRetention`, `temperature` oder `maxTokens`, ohne den gesamten Modellkatalog zu duplizieren. -- `skills`: optionale Skill-Allowlist pro Agent. Wenn weggelassen, erbt der Agent `agents.defaults.skills`, sofern gesetzt; eine explizite Liste ersetzt die Standardwerte statt sie zusammenzuführen, und `[]` bedeutet keine Skills. -- `thinkingDefault`: optionale Standard-Thinking-Stufe pro Agent (`off | minimal | low | medium | high | xhigh | adaptive`). Überschreibt `agents.defaults.thinkingDefault` für diesen Agenten, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist. -- `reasoningDefault`: optionale Standard-Sichtbarkeit von Reasoning pro Agent (`on | off | stream`). Gilt, wenn keine Überschreibung für Reasoning pro Nachricht oder Sitzung gesetzt ist. -- `fastModeDefault`: optionale Standardeinstellung für den Fast-Modus pro Agent (`true | false`). Gilt, wenn keine Überschreibung des Fast-Modus pro Nachricht oder Sitzung gesetzt ist. -- `embeddedHarness`: optionale Überschreibung der Low-Level-Harness-Richtlinie pro Agent. Verwenden Sie `{ runtime: "codex", fallback: "none" }`, um einen Agenten auf Codex-only zu setzen, während andere Agenten den Standard-PI-Fallback behalten. -- `runtime`: optionaler Laufzeit-Deskriptor pro Agent. Verwenden Sie `type: "acp"` mit den Standardwerten in `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), wenn der Agent standardmäßig ACP-Harness-Sitzungen verwenden soll. -- `identity.avatar`: workspace-relativer Pfad, `http(s)`-URL oder `data:`-URI. +- `default`: wenn mehrere gesetzt sind, gewinnt der erste (Warnung wird protokolliert). Wenn keine gesetzt ist, ist der erste Listeneintrag der Standard. +- `model`: Die String-Form überschreibt nur `primary`; die Objektform `{ primary, fallbacks }` überschreibt beides (`[]` deaktiviert globale Fallbacks). Cron-Jobs, die nur `primary` überschreiben, erben weiterhin die Standard-Fallbacks, sofern Sie nicht `fallbacks: []` setzen. +- `params`: Stream-Parameter pro Agent, die über den ausgewählten Modelleintrag in `agents.defaults.models` gemergt werden. Verwenden Sie dies für agentenspezifische Überschreibungen wie `cacheRetention`, `temperature` oder `maxTokens`, ohne den gesamten Modellkatalog zu duplizieren. +- `skills`: optionale Skill-Allowlist pro Agent. Wenn weggelassen, erbt der Agent `agents.defaults.skills`, sofern gesetzt; eine explizite Liste ersetzt die Standards statt mit ihnen gemergt zu werden, und `[]` bedeutet keine Skills. +- `thinkingDefault`: optionales Standard-Thinking-Level pro Agent (`off | minimal | low | medium | high | xhigh | adaptive`). Überschreibt `agents.defaults.thinkingDefault` für diesen Agent, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist. +- `reasoningDefault`: optionale Standard-Sichtbarkeit von Reasoning pro Agent (`on | off | stream`). Gilt, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist. +- `fastModeDefault`: optionaler Standardwert pro Agent für den Schnellmodus (`true | false`). Gilt, wenn keine Überschreibung pro Nachricht oder Sitzung gesetzt ist. +- `embeddedHarness`: optionale Überschreibung der Low-Level-Harness-Richtlinie pro Agent. Verwenden Sie `{ runtime: "codex", fallback: "none" }`, um einen Agent nur auf Codex zu setzen, während andere Agents den Standard-PI-Fallback beibehalten. +- `runtime`: optionaler Laufzeit-Deskriptor pro Agent. Verwenden Sie `type: "acp"` mit `runtime.acp`-Standards (`agent`, `backend`, `mode`, `cwd`), wenn der Agent standardmäßig ACP-Harness-Sitzungen verwenden soll. +- `identity.avatar`: pfad relativ zum Workspace, `http(s)`-URL oder `data:`-URI. - `identity` leitet Standardwerte ab: `ackReaction` aus `emoji`, `mentionPatterns` aus `name`/`emoji`. - `subagents.allowAgents`: Allowlist von Agent-IDs für `sessions_spawn` (`["*"]` = beliebig; Standard: nur derselbe Agent). -- Sandbox-Vererbungs-Schutz: Wenn die anfragende Sitzung in einer Sandbox läuft, lehnt `sessions_spawn` Ziele ab, die ohne Sandbox laufen würden. -- `subagents.requireAgentId`: wenn true, blockiert `sessions_spawn`-Aufrufe ohne `agentId` (erzwingt explizite Profilauswahl; Standard: false). +- Schutz bei Sandbox-Vererbung: Wenn die anfragende Sitzung in einer Sandbox läuft, lehnt `sessions_spawn` Ziele ab, die unsandboxed laufen würden. +- `subagents.requireAgentId`: wenn true, blockiert `sessions_spawn` Aufrufe ohne `agentId` (erzwingt explizite Profilauswahl; Standard: false). --- ## Multi-Agent-Routing -Führen Sie mehrere isolierte Agenten in einem Gateway aus. Siehe [Multi-Agent](/de/concepts/multi-agent). +Führen Sie mehrere isolierte Agents innerhalb eines Gateways aus. Siehe [Multi-Agent](/de/concepts/multi-agent). ```json5 { @@ -1675,9 +1675,9 @@ Führen Sie mehrere isolierte Agenten in einem Gateway aus. Siehe [Multi-Agent]( } ``` -### Binding-Match-Felder +### Übereinstimmungsfelder für Bindings -- `type` (optional): `route` für normales Routing (fehlender Typ entspricht standardmäßig route), `acp` für persistente ACP-Konversations-Bindings. +- `type` (optional): `route` für normales Routing (fehlender Typ bedeutet standardmäßig route), `acp` für persistente ACP-Konversationsbindungen. - `match.channel` (erforderlich) - `match.accountId` (optional; `*` = beliebiges Konto; weggelassen = Standardkonto) - `match.peer` (optional; `{ kind: direct|group|channel, id }`) @@ -1693,13 +1693,13 @@ Führen Sie mehrere isolierte Agenten in einem Gateway aus. Siehe [Multi-Agent]( 5. `match.accountId: "*"` (kanalweit) 6. Standard-Agent -Innerhalb jeder Ebene gewinnt der erste passende Eintrag in `bindings`. +Innerhalb jeder Ebene gewinnt der erste passende `bindings`-Eintrag. -Für Einträge mit `type: "acp"` löst OpenClaw nach exakter Konversationsidentität auf (`match.channel` + Konto + `match.peer.id`) und verwendet nicht die obige Stufenreihenfolge für Route-Bindings. +Für Einträge vom Typ `type: "acp"` löst OpenClaw nach exakter Konversationsidentität (`match.channel` + Konto + `match.peer.id`) auf und verwendet nicht die obige Reihenfolge der Route-Bindungsebenen. ### Zugriffsprofile pro Agent - + ```json5 { @@ -1792,7 +1792,7 @@ Für Einträge mit `type: "acp"` löst OpenClaw nach exakter Konversationsidenti -Siehe [Multi-Agent Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für Details zur Priorität. +Details zur Priorität finden Sie unter [Multi-Agent Sandbox & Tools](/de/tools/multi-agent-sandbox-tools). --- @@ -1830,10 +1830,10 @@ Siehe [Multi-Agent Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für De }, threadBindings: { enabled: true, - idleHours: 24, // Standard für automatisches Aufheben des Fokus bei Inaktivität in Stunden (`0` deaktiviert) + idleHours: 24, // Standard für automatisches Entfokussieren bei Inaktivität in Stunden (`0` deaktiviert) maxAgeHours: 0, // Standard für hartes Maximalalter in Stunden (`0` deaktiviert) }, - mainKey: "main", // Legacy (die Laufzeit verwendet immer "main") + mainKey: "main", // veraltet (Laufzeit verwendet immer "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1845,35 +1845,35 @@ Siehe [Multi-Agent Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für De -- **`scope`**: grundlegende Strategie zur Sitzungsgruppierung für Gruppenchats. - - `per-sender` (Standard): Jeder Absender erhält innerhalb eines Kanalkontexts eine isolierte Sitzung. +- **`scope`**: grundlegende Gruppierungsstrategie für Sitzungen in Gruppenchats. + - `per-sender` (Standard): Jeder Absender erhält eine isolierte Sitzung innerhalb eines Kanalkontexts. - `global`: Alle Teilnehmer in einem Kanalkontext teilen sich eine einzige Sitzung (nur verwenden, wenn gemeinsamer Kontext beabsichtigt ist). - **`dmScope`**: wie DMs gruppiert werden. - `main`: Alle DMs teilen sich die Hauptsitzung. - - `per-peer`: Isolation nach Absender-ID über Kanäle hinweg. - - `per-channel-peer`: Isolation pro Kanal + Absender (empfohlen für Posteingänge mit mehreren Benutzern). - - `per-account-channel-peer`: Isolation pro Konto + Kanal + Absender (empfohlen für Multi-Konto). + - `per-peer`: Isolierung nach Absender-ID kanalübergreifend. + - `per-channel-peer`: Isolierung pro Kanal + Absender (empfohlen für Mehrbenutzer-Posteingänge). + - `per-account-channel-peer`: Isolierung pro Konto + Kanal + Absender (empfohlen für mehrere Konten). - **`identityLinks`**: ordnet kanonische IDs providerpräfixierten Peers für kanalübergreifende gemeinsame Sitzungen zu. -- **`reset`**: primäre Rücksetzrichtlinie. `daily` setzt zur lokalen Zeit `atHour` zurück; `idle` setzt nach `idleMinutes` zurück. Wenn beide konfiguriert sind, gilt der zuerst ablaufende Wert. +- **`reset`**: primäre Zurücksetzungsrichtlinie. `daily` setzt um `atHour` lokaler Zeit zurück; `idle` setzt nach `idleMinutes` zurück. Wenn beide konfiguriert sind, gewinnt die zuerst ablaufende Regel. - **`resetByType`**: Überschreibungen pro Typ (`direct`, `group`, `thread`). Legacy-`dm` wird als Alias für `direct` akzeptiert. - **`parentForkMaxTokens`**: maximal zulässige `totalTokens` der übergeordneten Sitzung beim Erstellen einer geforkten Thread-Sitzung (Standard `100000`). - - Wenn die `totalTokens` der übergeordneten Sitzung über diesem Wert liegen, startet OpenClaw eine frische Thread-Sitzung, anstatt den Verlauf des übergeordneten Transkripts zu übernehmen. - - Setzen Sie `0`, um diese Schutzfunktion zu deaktivieren und das Forken vom Parent immer zuzulassen. -- **`mainKey`**: Legacy-Feld. Die Laufzeit verwendet für den Haupt-Bucket für Direktchats immer `"main"`. -- **`agentToAgent.maxPingPongTurns`**: maximale Anzahl an Antwort-zurück-Turns zwischen Agenten bei Agent-zu-Agent-Austauschvorgängen (Ganzzahl, Bereich: `0`–`5`). `0` deaktiviert Ping-Pong-Verkettung. -- **`sendPolicy`**: Abgleich nach `channel`, `chatType` (`direct|group|channel`, mit Legacy-Alias `dm`), `keyPrefix` oder `rawKeyPrefix`. Die erste Verweigerung gewinnt. -- **`maintenance`**: Bereinigung + Aufbewahrungssteuerung für den Sitzungsspeicher. + - Wenn `totalTokens` der übergeordneten Sitzung über diesem Wert liegt, startet OpenClaw eine neue Thread-Sitzung, statt den Verlauf der übergeordneten Sitzung zu übernehmen. + - Setzen Sie `0`, um diesen Schutz zu deaktivieren und das Forken aus der übergeordneten Sitzung immer zu erlauben. +- **`mainKey`**: Legacy-Feld. Die Laufzeit verwendet immer `"main"` für den Haupt-Bucket für Direktchats. +- **`agentToAgent.maxPingPongTurns`**: maximale Anzahl von Antwort-Rückantwort-Turns zwischen Agents während Agent-zu-Agent-Austauschvorgängen (Ganzzahl, Bereich: `0`–`5`). `0` deaktiviert Ping-Pong-Verkettung. +- **`sendPolicy`**: Abgleich nach `channel`, `chatType` (`direct|group|channel`, mit Legacy-Alias `dm`), `keyPrefix` oder `rawKeyPrefix`. Die erste Ablehnung gewinnt. +- **`maintenance`**: Bereinigungs- und Aufbewahrungssteuerung für den Sitzungsspeicher. - `mode`: `warn` gibt nur Warnungen aus; `enforce` wendet die Bereinigung an. - `pruneAfter`: Altersgrenze für veraltete Einträge (Standard `30d`). - `maxEntries`: maximale Anzahl an Einträgen in `sessions.json` (Standard `500`). - `rotateBytes`: rotiert `sessions.json`, wenn diese Größe überschritten wird (Standard `10mb`). - - `resetArchiveRetention`: Aufbewahrung für `*.reset.`-Transkriptarchive. Standardmäßig identisch mit `pruneAfter`; setzen Sie `false`, um dies zu deaktivieren. - - `maxDiskBytes`: optionales Speicherbudget für das Sitzungsverzeichnis. Im Modus `warn` werden Warnungen protokolliert; im Modus `enforce` werden zuerst die ältesten Artefakte/Sitzungen entfernt. - - `highWaterBytes`: optionaler Zielwert nach der Budget-Bereinigung. Standardmäßig `80%` von `maxDiskBytes`. + - `resetArchiveRetention`: Aufbewahrung für Transcript-Archive vom Typ `*.reset.`. Standardmäßig `pruneAfter`; setzen Sie `false`, um dies zu deaktivieren. + - `maxDiskBytes`: optionales Festplattenbudget für das Sitzungsverzeichnis. Im Modus `warn` werden Warnungen protokolliert; im Modus `enforce` werden zuerst die ältesten Artefakte/Sitzungen entfernt. + - `highWaterBytes`: optionales Ziel nach Budget-Bereinigung. Standardmäßig `80%` von `maxDiskBytes`. - **`threadBindings`**: globale Standardwerte für an Threads gebundene Sitzungsfunktionen. - - `enabled`: globaler Standardschalter (Provider können überschreiben; Discord verwendet `channels.discord.threadBindings.enabled`) - - `idleHours`: Standardwert für automatisches Aufheben des Fokus bei Inaktivität in Stunden (`0` deaktiviert; Provider können überschreiben) - - `maxAgeHours`: Standardwert für hartes Maximalalter in Stunden (`0` deaktiviert; Provider können überschreiben) + - `enabled`: globaler Standard-Hauptschalter (Provider können ihn überschreiben; Discord verwendet `channels.discord.threadBindings.enabled`) + - `idleHours`: Standard für automatisches Entfokussieren bei Inaktivität in Stunden (`0` deaktiviert; Provider können überschreiben) + - `maxAgeHours`: Standard für das harte Maximalalter in Stunden (`0` deaktiviert; Provider können überschreiben) @@ -1913,34 +1913,34 @@ Siehe [Multi-Agent Sandbox & Tools](/de/tools/multi-agent-sandbox-tools) für De Überschreibungen pro Kanal/Konto: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Auflösung (das Spezifischste gewinnt): Konto → Kanal → global. `""` deaktiviert und stoppt die Kaskade. `"auto"` leitet `[{identity.name}]` ab. +Auflösung (spezifischstes gewinnt): Konto → Kanal → global. `""` deaktiviert und stoppt die Kaskade. `"auto"` leitet `[{identity.name}]` ab. -**Template-Variablen:** +**Vorlagenvariablen:** | Variable | Beschreibung | Beispiel | | ----------------- | --------------------- | --------------------------- | | `{model}` | Kurzer Modellname | `claude-opus-4-6` | | `{modelFull}` | Vollständige Modellkennung | `anthropic/claude-opus-4-6` | -| `{provider}` | Provider-Name | `anthropic` | -| `{thinkingLevel}` | Aktuelle Thinking-Stufe | `high`, `low`, `off` | -| `{identity.name}` | Name der Agent-Identität | (gleich wie `"auto"`) | +| `{provider}` | Providername | `anthropic` | +| `{thinkingLevel}` | Aktuelles Thinking-Level | `high`, `low`, `off` | +| `{identity.name}` | Name der Agent-Identität | (entspricht `"auto"`) | -Variablen sind nicht case-sensitiv. `{think}` ist ein Alias für `{thinkingLevel}`. +Variablen sind nicht groß-/kleinschreibungssensitiv. `{think}` ist ein Alias für `{thinkingLevel}`. -### Bestätigungsreaktion +### Ack-Reaktion -- Standard ist das `identity.emoji` des aktiven Agenten, andernfalls `"👀"`. Setzen Sie `""`, um zu deaktivieren. +- Verwendet standardmäßig `identity.emoji` des aktiven Agent, andernfalls `"👀"`. Setzen Sie `""`, um sie zu deaktivieren. - Überschreibungen pro Kanal: `channels..ackReaction`, `channels..accounts..ackReaction`. - Auflösungsreihenfolge: Konto → Kanal → `messages.ackReaction` → Identity-Fallback. -- Scope: `group-mentions` (Standard), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: entfernt die Bestätigungsreaktion nach der Antwort auf Slack, Discord und Telegram. -- `messages.statusReactions.enabled`: aktiviert Lifecycle-Statusreaktionen auf Slack, Discord und Telegram. - Auf Slack und Discord bleiben Statusreaktionen bei nicht gesetztem Wert aktiviert, wenn Bestätigungsreaktionen aktiv sind. - Auf Telegram setzen Sie dies explizit auf `true`, um Lifecycle-Statusreaktionen zu aktivieren. +- Geltungsbereich: `group-mentions` (Standard), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: entfernt die Ack-Reaktion nach der Antwort auf Slack, Discord und Telegram. +- `messages.statusReactions.enabled`: aktiviert Lebenszyklus-Statusreaktionen auf Slack, Discord und Telegram. + Auf Slack und Discord bleiben Statusreaktionen aktiviert, wenn Ack-Reaktionen aktiv sind und der Wert nicht gesetzt ist. + Auf Telegram setzen Sie ihn explizit auf `true`, um Lebenszyklus-Statusreaktionen zu aktivieren. ### Eingehendes Debounce -Fasst schnelle reine Textnachrichten desselben Absenders zu einem einzelnen Agent-Turn zusammen. Medien/Anhänge werden sofort geleert. Steuerbefehle umgehen das Debouncing. +Fasst schnelle reine Textnachrichten vom selben Absender zu einem einzigen Agent-Turn zusammen. Medien/Anhänge werden sofort geleert. Steuerbefehle umgehen das Debouncing. ### TTS (Text-to-Speech) @@ -1983,12 +1983,12 @@ Fasst schnelle reine Textnachrichten desselben Absenders zu einem einzelnen Agen } ``` -- `auto` steuert den Standardmodus für automatisches TTS: `off`, `always`, `inbound` oder `tagged`. `/tts on|off` kann lokale Einstellungen überschreiben, und `/tts status` zeigt den wirksamen Zustand an. +- `auto` steuert den Standardmodus für automatisches TTS: `off`, `always`, `inbound` oder `tagged`. `/tts on|off` kann lokale Einstellungen überschreiben, und `/tts status` zeigt den effektiven Zustand an. - `summaryModel` überschreibt `agents.defaults.model.primary` für die automatische Zusammenfassung. - `modelOverrides` ist standardmäßig aktiviert; `modelOverrides.allowProvider` ist standardmäßig `false` (Opt-in). -- API-Schlüssel greifen auf `ELEVENLABS_API_KEY`/`XI_API_KEY` und `OPENAI_API_KEY` zurück. -- `openai.baseUrl` überschreibt den OpenAI-TTS-Endpunkt. Auflösungsreihenfolge ist Konfiguration, dann `OPENAI_TTS_BASE_URL`, dann `https://api.openai.com/v1`. -- Wenn `openai.baseUrl` auf einen Nicht-OpenAI-Endpunkt verweist, behandelt OpenClaw ihn als OpenAI-kompatiblen TTS-Server und lockert die Validierung von Modell und Stimme. +- API-Schlüssel fallen auf `ELEVENLABS_API_KEY`/`XI_API_KEY` und `OPENAI_API_KEY` zurück. +- `openai.baseUrl` überschreibt den OpenAI-TTS-Endpunkt. Auflösungsreihenfolge: Konfiguration, dann `OPENAI_TTS_BASE_URL`, dann `https://api.openai.com/v1`. +- Wenn `openai.baseUrl` auf einen Nicht-OpenAI-Endpunkt zeigt, behandelt OpenClaw ihn als OpenAI-kompatiblen TTS-Server und lockert die Validierung von Modell und Stimme. --- @@ -2019,12 +2019,12 @@ Standardwerte für den Talk-Modus (macOS/iOS/Android). ``` - `talk.provider` muss einem Schlüssel in `talk.providers` entsprechen, wenn mehrere Talk-Provider konfiguriert sind. -- Legacy-flache Talk-Schlüssel (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) dienen nur der Kompatibilität und werden automatisch nach `talk.providers.` migriert. +- Veraltete flache Talk-Schlüssel (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) dienen nur der Kompatibilität und werden automatisch nach `talk.providers.` migriert. - Für Voice-IDs wird auf `ELEVENLABS_VOICE_ID` oder `SAG_VOICE_ID` zurückgegriffen. -- `providers.*.apiKey` akzeptiert Klartext-Strings oder SecretRef-Objekte. +- `providers.*.apiKey` akzeptiert Klartextzeichenfolgen oder SecretRef-Objekte. - Der Fallback `ELEVENLABS_API_KEY` gilt nur, wenn kein Talk-API-Schlüssel konfiguriert ist. -- `providers.*.voiceAliases` ermöglicht es Talk-Direktiven, benutzerfreundliche Namen zu verwenden. -- `silenceTimeoutMs` steuert, wie lange der Talk-Modus nach Stille des Benutzers wartet, bevor er das Transkript sendet. Wenn nicht gesetzt, bleibt das plattformspezifische Standard-Pausenfenster erhalten (`700 ms auf macOS und Android, 900 ms auf iOS`). +- `providers.*.voiceAliases` erlaubt Talk-Direktiven die Verwendung freundlicher Namen. +- `silenceTimeoutMs` steuert, wie lange der Talk-Modus nach dem Schweigen des Benutzers wartet, bevor das Transkript gesendet wird. Wenn nicht gesetzt, bleibt das plattformspezifische Standard-Pausenfenster erhalten (`700 ms auf macOS und Android, 900 ms auf iOS`). --- @@ -2036,33 +2036,33 @@ Standardwerte für den Talk-Modus (macOS/iOS/Android). Lokales Onboarding setzt für neue lokale Konfigurationen standardmäßig `tools.profile: "coding"`, wenn nichts gesetzt ist (bestehende explizite Profile bleiben erhalten). -| Profil | Beinhaltet | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | nur `session_status` | +| Profil | Enthält | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | nur `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Keine Einschränkung (wie nicht gesetzt) | +| `full` | Keine Einschränkung (wie nicht gesetzt) | ### Tool-Gruppen -| Gruppe | Tools | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` wird als Alias für `exec` akzeptiert) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Gruppe | Tools | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` wird als Alias für `exec` akzeptiert) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Alle integrierten Tools (Provider-Plugins ausgenommen) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Alle integrierten Tools (ohne Provider-Plugins) | ### `tools.allow` / `tools.deny` -Globale Tool-Allow-/Deny-Richtlinie (Deny gewinnt). Nicht case-sensitiv, unterstützt `*`-Wildcards. Wird auch angewendet, wenn die Docker-Sandbox deaktiviert ist. +Globale Tool-Allow-/Deny-Richtlinie (Deny gewinnt). Ohne Berücksichtigung der Groß-/Kleinschreibung, unterstützt `*`-Wildcards. Wird auch angewendet, wenn die Docker-Sandbox deaktiviert ist. ```json5 { @@ -2105,8 +2105,8 @@ Steuert erhöhten `exec`-Zugriff außerhalb der Sandbox: ``` - Die Überschreibung pro Agent (`agents.list[].tools.elevated`) kann nur weiter einschränken. -- `/elevated on|off|ask|full` speichert den Zustand pro Sitzung; Inline-Direktiven gelten nur für eine einzelne Nachricht. -- Erhöhtes `exec` umgeht Sandboxing und verwendet den konfigurierten Escape-Pfad (`gateway` standardmäßig oder `node`, wenn das `exec`-Ziel `node` ist). +- `/elevated on|off|ask|full` speichert den Status pro Sitzung; Inline-Direktiven gelten nur für eine einzelne Nachricht. +- Erhöhtes `exec` umgeht die Sandbox und verwendet den konfigurierten Escape-Pfad (`gateway` standardmäßig oder `node`, wenn das `exec`-Ziel `node` ist). ### `tools.exec` @@ -2131,7 +2131,7 @@ Steuert erhöhten `exec`-Zugriff außerhalb der Sandbox: ### `tools.loopDetection` Sicherheitsprüfungen für Tool-Schleifen sind standardmäßig **deaktiviert**. Setzen Sie `enabled: true`, um die Erkennung zu aktivieren. -Einstellungen können global in `tools.loopDetection` definiert und pro Agent in `agents.list[].tools.loopDetection` überschrieben werden. +Einstellungen können global unter `tools.loopDetection` definiert und pro Agent unter `agents.list[].tools.loopDetection` überschrieben werden. ```json5 { @@ -2152,8 +2152,8 @@ Einstellungen können global in `tools.loopDetection` definiert und pro Agent in } ``` -- `historySize`: maximale Tool-Call-Historie, die für die Schleifenanalyse gespeichert wird. -- `warningThreshold`: Schwellenwert für Warnungen bei wiederholten Mustern ohne Fortschritt. +- `historySize`: maximaler Verlauf von Tool-Aufrufen, der für die Schleifenanalyse aufbewahrt wird. +- `warningThreshold`: Schwellenwert für Warnungen bei sich wiederholenden Mustern ohne Fortschritt. - `criticalThreshold`: höherer Wiederholungsschwellenwert zum Blockieren kritischer Schleifen. - `globalCircuitBreakerThreshold`: harter Stoppschwellenwert für jeden Lauf ohne Fortschritt. - `detectors.genericRepeat`: warnt bei wiederholten Aufrufen desselben Tools mit denselben Argumenten. @@ -2176,7 +2176,7 @@ Einstellungen können global in `tools.loopDetection` definiert und pro Agent in }, fetch: { enabled: true, - provider: "firecrawl", // optional; für Auto-Erkennung weglassen + provider: "firecrawl", // optional; weglassen für automatische Erkennung maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2201,7 +2201,7 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // Opt-in: fertige asynchrone Musik/Videos direkt an den Kanal senden + directSend: false, // Opt-in: abgeschlossene asynchrone Musik/Videos direkt an den Kanal senden }, audio: { enabled: true, @@ -2225,7 +2225,7 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video): } ``` - + **Provider-Eintrag** (`type: "provider"` oder weggelassen): @@ -2235,8 +2235,8 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video): **CLI-Eintrag** (`type: "cli"`): -- `command`: auszuführende ausführbare Datei -- `args`: templatebasierte Argumente (unterstützt `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` usw.) +- `command`: auszuführende Datei +- `args`: vorlagenbasierte Argumente (unterstützt `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` usw.) **Gemeinsame Felder:** @@ -2244,13 +2244,11 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video): - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: Überschreibungen pro Eintrag. - Bei Fehlern wird auf den nächsten Eintrag zurückgegriffen. -Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.json` → Env-Variablen → `models.providers.*.apiKey`. +Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.json` → Umgebungsvariablen → `models.providers.*.apiKey`. -**Felder für asynchronen Abschluss:** +**Felder für asynchrone Abschlüsse:** -- `asyncCompletion.directSend`: wenn `true`, versuchen abgeschlossene asynchrone `music_generate`- - und `video_generate`-Aufgaben zuerst die direkte Kanalauslieferung. Standard: `false` - (Legacy-Pfad über anfragende Sitzung wecken/Modellzustellung). +- `asyncCompletion.directSend`: wenn `true`, versuchen abgeschlossene asynchrone Aufgaben von `music_generate` und `video_generate` zuerst die direkte Zustellung an den Kanal. Standard: `false` (Legacy-Pfad über anfordernde Sitzung/Aufwecken/Modellzustellung). @@ -2269,9 +2267,9 @@ Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.jso ### `tools.sessions` -Steuert, welche Sitzungen von den Sitzungstools (`sessions_list`, `sessions_history`, `sessions_send`) angesprochen werden können. +Steuert, welche Sitzungen von den Sitzungs-Tools (`sessions_list`, `sessions_history`, `sessions_send`) angesprochen werden können. -Standard: `tree` (aktuelle Sitzung + von ihr gestartete Sitzungen, z. B. Subagenten). +Standard: `tree` (aktuelle Sitzung + von ihr gestartete Sitzungen, wie Subagents). ```json5 { @@ -2287,10 +2285,10 @@ Standard: `tree` (aktuelle Sitzung + von ihr gestartete Sitzungen, z. B. Subagen Hinweise: - `self`: nur der aktuelle Sitzungsschlüssel. -- `tree`: aktuelle Sitzung + von der aktuellen Sitzung gestartete Sitzungen (Subagenten). -- `agent`: jede Sitzung, die zur aktuellen Agent-ID gehört (kann andere Benutzer einschließen, wenn Sie per-sender-Sitzungen unter derselben Agent-ID ausführen). -- `all`: jede Sitzung. Kanalübergreifendes Targeting von Agenten erfordert weiterhin `tools.agentToAgent`. -- Sandbox-Begrenzung: Wenn die aktuelle Sitzung in einer Sandbox läuft und `agents.defaults.sandbox.sessionToolsVisibility="spawned"` ist, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"` gesetzt ist. +- `tree`: aktuelle Sitzung + von der aktuellen Sitzung gestartete Sitzungen (Subagents). +- `agent`: jede Sitzung, die zur aktuellen Agent-ID gehört (kann auch andere Benutzer einschließen, wenn Sie Pro-Absender-Sitzungen unter derselben Agent-ID ausführen). +- `all`: jede Sitzung. Kanalübergreifendes Targeting erfordert weiterhin `tools.agentToAgent`. +- Sandbox-Begrenzung: Wenn die aktuelle Sitzung in einer Sandbox läuft und `agents.defaults.sandbox.sessionToolsVisibility="spawned"` gesetzt ist, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"` gesetzt ist. ### `tools.sessions_spawn` @@ -2302,7 +2300,7 @@ Steuert die Unterstützung für Inline-Anhänge bei `sessions_spawn`. sessions_spawn: { attachments: { enabled: false, // Opt-in: auf true setzen, um Inline-Dateianhänge zu erlauben - maxTotalBytes: 5242880, // 5 MB insgesamt über alle Dateien + maxTotalBytes: 5242880, // insgesamt 5 MB über alle Dateien maxFiles: 50, maxFileBytes: 1048576, // 1 MB pro Datei retainOnSessionKeep: false, // Anhänge beibehalten, wenn cleanup="keep" @@ -2314,16 +2312,16 @@ Steuert die Unterstützung für Inline-Anhänge bei `sessions_spawn`. Hinweise: -- Anhänge werden nur für `runtime: "subagent"` unterstützt. ACP-Laufzeit lehnt sie ab. +- Anhänge werden nur für `runtime: "subagent"` unterstützt. Die ACP-Laufzeit lehnt sie ab. - Dateien werden im Child-Workspace unter `.openclaw/attachments//` mit einer `.manifest.json` materialisiert. -- Der Inhalt von Anhängen wird automatisch aus der Persistenz des Transkripts redigiert. -- Base64-Eingaben werden mit strenger Alphabet-/Padding-Prüfung und einer Größenprüfung vor dem Dekodieren validiert. +- Anhangsinhalte werden automatisch aus der Transcript-Persistenz redigiert. +- Base64-Eingaben werden mit strikten Alphabet-/Padding-Prüfungen und einer Größenprüfung vor dem Decodieren validiert. - Dateiberechtigungen sind `0700` für Verzeichnisse und `0600` für Dateien. -- Die Bereinigung folgt der Richtlinie `cleanup`: `delete` entfernt Anhänge immer; `keep` behält sie nur bei, wenn `retainOnSessionKeep: true`. +- Die Bereinigung folgt der `cleanup`-Richtlinie: `delete` entfernt Anhänge immer; `keep` behält sie nur, wenn `retainOnSessionKeep: true`. ### `tools.experimental` -Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, sofern keine Auto-Aktivierungsregel für strict-agentic GPT-5 greift. +Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, außer wenn eine Regel zur automatischen Aktivierung für streng-agentisches GPT-5 greift. ```json5 { @@ -2337,9 +2335,9 @@ Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, sofern keine Hinweise: -- `planTool`: aktiviert das strukturierte Tool `update_plan` zur Nachverfolgung nichttrivialer mehrstufiger Arbeit. -- Standard: `false`, außer wenn `agents.defaults.embeddedPi.executionContract` (oder eine Überschreibung pro Agent) für einen Lauf mit OpenAI oder OpenAI Codex GPT-5-Familie auf `"strict-agentic"` gesetzt ist. Setzen Sie `true`, um das Tool außerhalb dieses Bereichs zu erzwingen, oder `false`, um es auch bei strict-agentic GPT-5-Läufen deaktiviert zu lassen. -- Wenn aktiviert, fügt der System-Prompt auch Nutzungshinweise hinzu, damit das Modell es nur für wesentliche Arbeit verwendet und höchstens einen Schritt `in_progress` hält. +- `planTool`: aktiviert das strukturierte Tool `update_plan` zur Nachverfolgung nicht-trivialer mehrstufiger Arbeit. +- Standard: `false`, außer wenn `agents.defaults.embeddedPi.executionContract` (oder eine Überschreibung pro Agent) für einen Lauf mit OpenAI- oder OpenAI-Codex-GPT-5-Familie auf `"strict-agentic"` gesetzt ist. Setzen Sie `true`, um das Tool außerhalb dieses Bereichs zu erzwingen, oder `false`, um es selbst bei streng-agentischen GPT-5-Läufen deaktiviert zu lassen. +- Wenn aktiviert, fügt der System-Prompt auch Nutzungshinweise hinzu, damit das Modell es nur für umfangreiche Arbeit verwendet und höchstens einen Schritt als `in_progress` markiert. ### `agents.defaults.subagents` @@ -2359,9 +2357,9 @@ Hinweise: } ``` -- `model`: Standardmodell für gestartete Subagenten. Wenn weggelassen, erben Subagenten das Modell des Aufrufers. -- `allowAgents`: Standard-Allowlist der Ziel-Agent-IDs für `sessions_spawn`, wenn der anfragende Agent keine eigene `subagents.allowAgents` setzt (`["*"]` = beliebig; Standard: nur derselbe Agent). -- `runTimeoutSeconds`: Standard-Timeout (Sekunden) für `sessions_spawn`, wenn der Tool-Aufruf `runTimeoutSeconds` weglässt. `0` bedeutet kein Timeout. +- `model`: Standardmodell für gestartete Sub-Agents. Wenn nicht gesetzt, erben Sub-Agents das Modell des Aufrufers. +- `allowAgents`: Standard-Allowlist der Ziel-Agent-IDs für `sessions_spawn`, wenn der anfordernde Agent keine eigene `subagents.allowAgents` setzt (`["*"]` = beliebig; Standard: nur derselbe Agent). +- `runTimeoutSeconds`: Standard-Timeout (Sekunden) für `sessions_spawn`, wenn der Tool-Aufruf `runTimeoutSeconds` nicht angibt. `0` bedeutet kein Timeout. - Tool-Richtlinie pro Subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -2399,46 +2397,46 @@ OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte - Verwenden Sie `authHeader: true` + `headers` für benutzerdefinierte Authentifizierungsanforderungen. - Überschreiben Sie das Root der Agent-Konfiguration mit `OPENCLAW_AGENT_DIR` (oder `PI_CODING_AGENT_DIR`, einem Legacy-Alias für Umgebungsvariablen). -- Zusammenführungspriorität für übereinstimmende Provider-IDs: - - Nicht leere `baseUrl`-Werte in der Agent-`models.json` haben Vorrang. - - Nicht leere Agent-`apiKey`-Werte haben nur dann Vorrang, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profile-Kontext nicht durch SecretRef verwaltet wird. - - Durch SecretRef verwaltete Provider-`apiKey`-Werte werden aus Quell-Markern aktualisiert (`ENV_VAR_NAME` für Env-Refs, `secretref-managed` für file-/exec-Refs), anstatt aufgelöste Secrets zu persistieren. - - Durch SecretRef verwaltete Header-Werte des Providers werden aus Quell-Markern aktualisiert (`secretref-env:ENV_VAR_NAME` für Env-Refs, `secretref-managed` für file-/exec-Refs). - - Leere oder fehlende Agent-`apiKey`/`baseUrl` greifen auf `models.providers` in der Konfiguration zurück. - - Übereinstimmende Modell-`contextWindow`/`maxTokens` verwenden den höheren Wert zwischen expliziter Konfiguration und impliziten Katalogwerten. - - Übereinstimmende Modell-`contextTokens` behalten ein explizites Laufzeitlimit bei, wenn vorhanden; verwenden Sie dies, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern. +- Merge-Priorität für übereinstimmende Provider-IDs: + - Nicht leere `baseUrl`-Werte aus `models.json` des Agent haben Vorrang. + - Nicht leere `apiKey`-Werte des Agent haben nur dann Vorrang, wenn dieser Provider im aktuellen Kontext von config/auth-profile nicht über SecretRef verwaltet wird. + - Über SecretRef verwaltete Provider-`apiKey`-Werte werden aus Quellmarkierungen aktualisiert (`ENV_VAR_NAME` für Env-Refs, `secretref-managed` für Datei-/Exec-Refs), statt aufgelöste Secrets zu persistieren. + - Über SecretRef verwaltete Provider-Headerwerte werden aus Quellmarkierungen aktualisiert (`secretref-env:ENV_VAR_NAME` für Env-Refs, `secretref-managed` für Datei-/Exec-Refs). + - Leere oder fehlende `apiKey`-/`baseUrl`-Werte des Agent fallen auf `models.providers` in der Konfiguration zurück. + - Für übereinstimmende Modelle verwenden `contextWindow`/`maxTokens` den höheren Wert zwischen expliziter Konfiguration und impliziten Katalogwerten. + - Übereinstimmende `contextTokens` bewahren einen expliziten Laufzeitgrenzwert, wenn vorhanden; verwenden Sie ihn, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern. - Verwenden Sie `models.mode: "replace"`, wenn die Konfiguration `models.json` vollständig neu schreiben soll. - - Die Persistenz von Markern ist quellenautoritativ: Marker werden aus dem aktiven Quell-Konfigurationssnapshot (vor der Auflösung) geschrieben, nicht aus aufgelösten Secret-Werten zur Laufzeit. + - Die Persistenz von Markierungen ist quellenautoritativ: Markierungen werden aus dem aktiven Konfigurations-Snapshot der Quelle (vor der Auflösung) geschrieben, nicht aus aufgelösten Laufzeit-Secret-Werten. ### Details zu Provider-Feldern - `models.mode`: Verhalten des Provider-Katalogs (`merge` oder `replace`). -- `models.providers`: benutzerdefinierte Provider-Zuordnung, verschlüsselt nach Provider-ID. +- `models.providers`: benutzerdefinierte Provider-Zuordnung, indiziert nach Provider-ID. - `models.providers.*.api`: Request-Adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` usw.). -- `models.providers.*.apiKey`: Provider-Anmeldedaten (bevorzugt SecretRef/Env-Substitution). +- `models.providers.*.apiKey`: Provider-Zugangsdaten (bevorzugt über SecretRef/Umgebungsvariablen-Substitution). - `models.providers.*.auth`: Authentifizierungsstrategie (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: für Ollama + `openai-completions`, `options.num_ctx` in Requests einfügen (Standard: `true`). -- `models.providers.*.authHeader`: erzwingt bei Bedarf die Übertragung der Anmeldedaten im Header `Authorization`. +- `models.providers.*.injectNumCtxForOpenAICompat`: für Ollama + `openai-completions`, `options.num_ctx` in Anfragen einfügen (Standard: `true`). +- `models.providers.*.authHeader`: Transport der Zugangsdaten im `Authorization`-Header erzwingen, wenn erforderlich. - `models.providers.*.baseUrl`: Base-URL der Upstream-API. - `models.providers.*.headers`: zusätzliche statische Header für Proxy-/Mandanten-Routing. -- `models.providers.*.request`: Transport-Überschreibungen für HTTP-Requests des Modell-Providers. - - `request.headers`: zusätzliche Header (werden mit den Standardwerten des Providers zusammengeführt). Werte akzeptieren SecretRef. - - `request.auth`: Überschreibung der Authentifizierungsstrategie. Modi: `"provider-default"` (eingebaute Auth des Providers verwenden), `"authorization-bearer"` (mit `token`), `"header"` (mit `headerName`, `value`, optional `prefix`). - - `request.proxy`: Überschreibung des HTTP-Proxys. Modi: `"env-proxy"` (Env-Variablen `HTTP_PROXY`/`HTTPS_PROXY` verwenden), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren ein optionales Unterobjekt `tls`. +- `models.providers.*.request`: Transport-Überschreibungen für HTTP-Anfragen an Modell-Provider. + - `request.headers`: zusätzliche Header (mit Provider-Standards zusammengeführt). Werte akzeptieren SecretRef. + - `request.auth`: Überschreibung der Authentifizierungsstrategie. Modi: `"provider-default"` (integrierte Authentifizierung des Providers verwenden), `"authorization-bearer"` (mit `token`), `"header"` (mit `headerName`, `value`, optional `prefix`). + - `request.proxy`: Überschreibung des HTTP-Proxys. Modi: `"env-proxy"` (Umgebungsvariablen `HTTP_PROXY`/`HTTPS_PROXY` verwenden), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren optional ein `tls`-Unterobjekt. - `request.tls`: TLS-Überschreibung für direkte Verbindungen. Felder: `ca`, `cert`, `key`, `passphrase` (alle akzeptieren SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: wenn `true`, HTTPS zu `baseUrl` zulassen, wenn DNS auf private, CGNAT- oder ähnliche Bereiche auflöst, über den HTTP-Fetch-Guard des Providers (Operator-Opt-in für vertrauenswürdige selbst gehostete OpenAI-kompatible Endpunkte). WebSocket verwendet dasselbe `request` für Header/TLS, aber nicht für dieses SSRF-Fetch-Gate. Standard `false`. -- `models.providers.*.models`: explizite Provider-Modellkatalogeinträge. -- `models.providers.*.models.*.contextWindow`: native Kontextfenster-Metadaten des Modells. -- `models.providers.*.models.*.contextTokens`: optionales Laufzeitlimit für den Kontext. Verwenden Sie dies, wenn Sie ein kleineres effektives Kontextbudget möchten als das native `contextWindow` des Modells. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: optionaler Kompatibilitätshinweis. Für `api: "openai-completions"` mit einer nicht leeren, nicht nativen `baseUrl` (Host nicht `api.openai.com`) erzwingt OpenClaw dies zur Laufzeit auf `false`. Eine leere/fehlende `baseUrl` behält das Standardverhalten von OpenAI bei. -- `models.providers.*.models.*.compat.requiresStringContent`: optionaler Kompatibilitätshinweis für rein stringbasierte OpenAI-kompatible Chat-Endpunkte. Wenn `true`, flatteniert OpenClaw reine Text-Arrays in `messages[].content` vor dem Senden des Requests zu einfachen Strings. -- `plugins.entries.amazon-bedrock.config.discovery`: Root der Bedrock-Auto-Discovery-Einstellungen. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: implizite Discovery ein-/ausschalten. -- `plugins.entries.amazon-bedrock.config.discovery.region`: AWS-Region für Discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optionaler Filter nach Provider-ID für gezielte Discovery. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: Polling-Intervall für die Aktualisierung der Discovery. + - `request.allowPrivateNetwork`: wenn `true`, HTTPS zu `baseUrl` erlauben, wenn DNS auf private, CGNAT- oder ähnliche Bereiche auflöst, über den HTTP-Fetch-Schutz des Providers (Opt-in für Operatoren bei vertrauenswürdigen selbstgehosteten OpenAI-kompatiblen Endpunkten). WebSocket verwendet dieselbe `request` für Header/TLS, aber nicht diesen Fetch-SSRF-Schutz. Standard `false`. +- `models.providers.*.models`: explizite Modellkatalogeinträge des Providers. +- `models.providers.*.models.*.contextWindow`: Metadaten des nativen Modell-Kontextfensters. +- `models.providers.*.models.*.contextTokens`: optionale Laufzeitgrenze für den Kontext. Verwenden Sie dies, wenn Sie ein kleineres effektives Kontextbudget als das native `contextWindow` des Modells wünschen. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: optionaler Kompatibilitätshinweis. Für `api: "openai-completions"` mit einer nicht leeren, nicht nativen `baseUrl` (Host nicht `api.openai.com`) erzwingt OpenClaw zur Laufzeit `false`. Bei leerer/weggelassener `baseUrl` bleibt das Standardverhalten von OpenAI erhalten. +- `models.providers.*.models.*.compat.requiresStringContent`: optionaler Kompatibilitätshinweis für reine String-OpenAI-kompatible Chat-Endpunkte. Wenn `true`, flacht OpenClaw reine Text-Arrays in `messages[].content` vor dem Senden der Anfrage zu einfachen Strings ab. +- `plugins.entries.amazon-bedrock.config.discovery`: Root der Bedrock-Einstellungen für automatische Erkennung. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: implizite Erkennung ein-/ausschalten. +- `plugins.entries.amazon-bedrock.config.discovery.region`: AWS-Region für die Erkennung. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optionaler Provider-ID-Filter für gezielte Erkennung. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: Polling-Intervall für das Aktualisieren der Erkennung. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: Fallback-Kontextfenster für erkannte Modelle. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: Fallback für maximale Ausgabetokens bei erkannten Modellen. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: Fallback für maximale Ausgabetoken bei erkannten Modellen. ### Provider-Beispiele @@ -2510,11 +2508,11 @@ Setzen Sie `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`). Verwenden Sie `open } ``` -Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Aliase akzeptiert. Kurzform: `openclaw onboard --auth-choice zai-api-key`. +Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` sind akzeptierte Aliasse. Kurzform: `openclaw onboard --auth-choice zai-api-key`. - Allgemeiner Endpunkt: `https://api.z.ai/api/paas/v4` - Coding-Endpunkt (Standard): `https://api.z.ai/api/coding/paas/v4` -- Für den allgemeinen Endpunkt definieren Sie einen benutzerdefinierten Provider mit Base-URL-Überschreibung. +- Für den allgemeinen Endpunkt definieren Sie einen benutzerdefinierten Provider mit einer Überschreibung der Base-URL. @@ -2555,9 +2553,7 @@ Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Aliase akzeptiert. Ku Für den China-Endpunkt: `baseUrl: "https://api.moonshot.cn/v1"` oder `openclaw onboard --auth-choice moonshot-api-key-cn`. -Native Moonshot-Endpunkte melden Streaming-Nutzungskompatibilität auf dem gemeinsamen -Transport `openai-completions`, und OpenClaw richtet sich dabei nach den Fähigkeiten des Endpunkts -und nicht allein nach der integrierten Provider-ID. +Native Moonshot-Endpunkte deklarieren Streaming-Nutzungskompatibilität auf dem gemeinsamen Transport `openai-completions`, und OpenClaw richtet sich dabei nach den Endpunktfähigkeiten statt nur nach der integrierten Provider-ID. @@ -2614,7 +2610,7 @@ Anthropic-kompatibel, integrierter Provider. Kurzform: `openclaw onboard --auth- } ``` -Die Base-URL sollte `/v1` weglassen (der Anthropic-Client hängt sie an). Kurzform: `openclaw onboard --auth-choice synthetic-api-key`. +Die Base-URL sollte `/v1` weglassen (der Anthropic-Client hängt es an). Kurzform: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2657,17 +2653,14 @@ Die Base-URL sollte `/v1` weglassen (der Anthropic-Client hängt sie an). Kurzfo Setzen Sie `MINIMAX_API_KEY`. Kurzformen: `openclaw onboard --auth-choice minimax-global-api` oder `openclaw onboard --auth-choice minimax-cn-api`. -Der Modellkatalog enthält standardmäßig nur M2.7. -Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw standardmäßig MiniMax-Thinking, -es sei denn, Sie setzen `thinking` selbst explizit. `/fast on` oder -`params.fastMode: true` schreibt `MiniMax-M2.7` zu -`MiniMax-M2.7-highspeed` um. +Der Modellkatalog verwendet standardmäßig nur M2.7. +Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw standardmäßig MiniMax thinking, sofern Sie `thinking` nicht explizit selbst setzen. `/fast on` oder `params.fastMode: true` schreibt `MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um. -Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein großes lokales Modell über die LM Studio Responses API auf leistungsfähiger Hardware aus; behalten Sie gehostete Modelle zur Absicherung als Fallback zusammengeführt. +Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein großes lokales Modell über die LM Studio Responses API auf leistungsstarker Hardware aus; behalten Sie gehostete Modelle als Fallback im Merge bei. @@ -2688,7 +2681,7 @@ Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein g }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // oder Klartext-String + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // oder Klartextzeichenfolge env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2698,12 +2691,12 @@ Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein g } ``` -- `allowBundled`: optionale Allowlist nur für gebündelte Skills (verwaltete/Workspace-Skills sind davon nicht betroffen). +- `allowBundled`: optionale Allowlist nur für gebündelte Skills (verwaltete/Workspace-Skills bleiben unberührt). - `load.extraDirs`: zusätzliche gemeinsame Skill-Roots (niedrigste Priorität). -- `install.preferBrew`: wenn true, werden bei verfügbarer `brew` zuerst Homebrew-Installer bevorzugt, bevor auf andere Installer-Arten zurückgegriffen wird. -- `install.nodeManager`: bevorzugter Node-Installer für `metadata.openclaw.install`-Spezifikationen (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` deaktiviert einen Skill, auch wenn er gebündelt/installiert ist. -- `entries..apiKey`: Komfortfeld für Skills, die eine primäre Env-Variable deklarieren (Klartext-String oder SecretRef-Objekt). +- `install.preferBrew`: wenn true, Homebrew-Installer bevorzugen, wenn `brew` verfügbar ist, bevor auf andere Installer-Arten zurückgegriffen wird. +- `install.nodeManager`: Präferenz für Node-Installer bei Spezifikationen in `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` deaktiviert einen Skill, selbst wenn er gebündelt/installiert ist. +- `entries..apiKey`: Komfortfeld für Skills, die eine primäre Umgebungsvariable deklarieren (Klartextzeichenfolge oder SecretRef-Objekt). --- @@ -2732,40 +2725,40 @@ Siehe [Lokale Modelle](/de/gateway/local-models). Kurz gesagt: Führen Sie ein g ``` - Geladen aus `~/.openclaw/extensions`, `/.openclaw/extensions` sowie `plugins.load.paths`. -- Discovery akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles im Standardlayout. +- Die Erkennung akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich Claude-Bundles im Standardlayout ohne Manifest. - **Konfigurationsänderungen erfordern einen Gateway-Neustart.** - `allow`: optionale Allowlist (nur aufgeführte Plugins werden geladen). `deny` hat Vorrang. - `plugins.entries..apiKey`: Komfortfeld für API-Schlüssel auf Plugin-Ebene (wenn vom Plugin unterstützt). -- `plugins.entries..env`: pluginbezogene Env-Variablen-Zuordnung. -- `plugins.entries..hooks.allowPromptInjection`: wenn `false`, blockiert der Core `before_prompt_build` und ignoriert promptverändernde Felder aus Legacy-`before_agent_start`, während Legacy-`modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte von Bundles bereitgestellte Hook-Verzeichnisse. -- `plugins.entries..subagent.allowModelOverride`: diesem Plugin explizit vertrauen, pro Lauf Überschreibungen für `provider` und `model` bei Hintergrund-Subagent-Läufen anzufordern. -- `plugins.entries..subagent.allowedModels`: optionale Allowlist kanonischer `provider/model`-Ziele für vertrauenswürdige Subagent-Überschreibungen. Verwenden Sie `"*"` nur, wenn Sie absichtlich jedes Modell zulassen möchten. -- `plugins.entries..config`: plugindefiniertes Konfigurationsobjekt (validiert durch das native OpenClaw-Plugin-Schema, sofern verfügbar). +- `plugins.entries..env`: Plugin-spezifische Zuordnung von Umgebungsvariablen. +- `plugins.entries..hooks.allowPromptInjection`: wenn `false`, blockiert der Core `before_prompt_build` und ignoriert promptmutierende Felder aus Legacy-`before_agent_start`, während Legacy-`modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte von Bundles bereitgestellte Hook-Verzeichnisse. +- `plugins.entries..subagent.allowModelOverride`: diesem Plugin explizit vertrauen, pro Lauf `provider`- und `model`-Überschreibungen für Hintergrund-Subagent-Läufe anzufordern. +- `plugins.entries..subagent.allowedModels`: optionale Allowlist kanonischer Ziele im Format `provider/model` für vertrauenswürdige Subagent-Überschreibungen. Verwenden Sie `"*"`, nur wenn Sie absichtlich jedes Modell zulassen möchten. +- `plugins.entries..config`: plugindefiniertes Konfigurationsobjekt (validiert durch das native OpenClaw-Plugin-Schema, wenn verfügbar). - `plugins.entries.firecrawl.config.webFetch`: Firecrawl-Einstellungen für den Web-Fetch-Provider. - - `apiKey`: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt zurück auf `plugins.entries.firecrawl.config.webSearch.apiKey`, Legacy-`tools.web.fetch.firecrawl.apiKey` oder die Env-Variable `FIRECRAWL_API_KEY`. + - `apiKey`: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt auf `plugins.entries.firecrawl.config.webSearch.apiKey`, Legacy-`tools.web.fetch.firecrawl.apiKey` oder die Umgebungsvariable `FIRECRAWL_API_KEY` zurück. - `baseUrl`: Firecrawl-API-Base-URL (Standard: `https://api.firecrawl.dev`). - `onlyMainContent`: nur den Hauptinhalt von Seiten extrahieren (Standard: `true`). - `maxAgeMs`: maximales Cache-Alter in Millisekunden (Standard: `172800000` / 2 Tage). - `timeoutSeconds`: Timeout für Scrape-Anfragen in Sekunden (Standard: `60`). - `plugins.entries.xai.config.xSearch`: Einstellungen für xAI X Search (Grok-Websuche). - `enabled`: den X-Search-Provider aktivieren. - - `model`: zu verwendendes Grok-Modell für die Suche (z. B. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: Einstellungen für memory dreaming (experimentell). Siehe [Dreaming](/de/concepts/dreaming) für Phasen und Schwellenwerte. + - `model`: Grok-Modell, das für die Suche verwendet werden soll (z. B. `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: Einstellungen für Memory-Dreaming (experimentell). Phasen und Schwellenwerte finden Sie unter [Dreaming](/de/concepts/dreaming). - `enabled`: globaler Dreaming-Schalter (Standard `false`). - `frequency`: Cron-Taktung für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`). - Phasenrichtlinie und Schwellenwerte sind Implementierungsdetails (keine benutzerseitigen Konfigurationsschlüssel). -- Die vollständige Speicherkonfiguration befindet sich in der [Speicherkonfigurationsreferenz](/de/reference/memory-config): +- Die vollständige Memory-Konfiguration befindet sich in der [Speicherkonfigurationsreferenz](/de/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standardwerte aus `settings.json` beisteuern; OpenClaw wendet diese als bereinigte Agenteinstellungen an, nicht als rohe OpenClaw-Konfigurations-Patches. -- `plugins.slots.memory`: aktive Memory-Plugin-ID auswählen oder `"none"` zum Deaktivieren von Memory-Plugins. -- `plugins.slots.contextEngine`: aktive Context-Engine-Plugin-ID auswählen; standardmäßig `"legacy"`, sofern Sie keine andere Engine installieren und auswählen. -- `plugins.installs`: von der CLI verwaltete Installationsmetadaten, verwendet von `openclaw plugins update`. +- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standards aus `settings.json` beisteuern; OpenClaw wendet diese als bereinigte Agent-Einstellungen an, nicht als rohe OpenClaw-Konfigurations-Patches. +- `plugins.slots.memory`: aktive Memory-Plugin-ID auswählen oder `"none"`, um Memory-Plugins zu deaktivieren. +- `plugins.slots.contextEngine`: aktive Context-Engine-Plugin-ID auswählen; Standard ist `"legacy"`, sofern Sie keine andere Engine installieren und auswählen. +- `plugins.installs`: von der CLI verwaltete Installationsmetadaten, die von `openclaw plugins update` verwendet werden. - Enthält `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Behandeln Sie `plugins.installs.*` als verwalteten Zustand; bevorzugen Sie CLI-Befehle statt manueller Bearbeitung. + - Behandeln Sie `plugins.installs.*` als verwalteten Zustand; bevorzugen Sie CLI-Befehle gegenüber manuellen Änderungen. Siehe [Plugins](/de/tools/plugin). @@ -2808,28 +2801,21 @@ Siehe [Plugins](/de/tools/plugin). ``` - `evaluateEnabled: false` deaktiviert `act:evaluate` und `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist deaktiviert, wenn es nicht gesetzt ist, daher bleibt Browser-Navigation standardmäßig strikt. -- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` nur, wenn Sie Browser-Navigation in private Netzwerke bewusst vertrauen. -- Im strikten Modus unterliegen Remote-CDP-Profilendpunkte (`profiles.*.cdpUrl`) bei Erreichbarkeits-/Discovery-Prüfungen derselben Sperre für private Netzwerke. -- `ssrfPolicy.allowPrivateNetwork` bleibt als Legacy-Alias unterstützt. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist deaktiviert, wenn es nicht gesetzt ist, sodass Browser-Navigation standardmäßig strikt bleibt. +- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` nur, wenn Sie Browser-Navigation in privaten Netzwerken bewusst vertrauen. +- Im strikten Modus unterliegen entfernte CDP-Profil-Endpunkte (`profiles.*.cdpUrl`) bei Erreichbarkeits-/Erkennungsprüfungen derselben Sperre für private Netzwerke. +- `ssrfPolicy.allowPrivateNetwork` wird weiterhin als Legacy-Alias unterstützt. - Verwenden Sie im strikten Modus `ssrfPolicy.hostnameAllowlist` und `ssrfPolicy.allowedHostnames` für explizite Ausnahmen. -- Remote-Profile sind nur zum Anhängen da (Start/Stop/Reset deaktiviert). +- Remote-Profile sind nur zum Anhängen gedacht (Start/Stopp/Reset deaktiviert). - `profiles.*.cdpUrl` akzeptiert `http://`, `https://`, `ws://` und `wss://`. - Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` erkennen soll; verwenden Sie WS(S), - wenn Ihr Provider Ihnen eine direkte DevTools-WebSocket-URL bereitstellt. -- `existing-session`-Profile sind nur für den Host verfügbar und verwenden Chrome MCP statt CDP. -- `existing-session`-Profile können `userDataDir` setzen, um ein bestimmtes Profil - eines Chromium-basierten Browsers wie Brave oder Edge anzusprechen. -- `existing-session`-Profile behalten die aktuellen Begrenzungen der Chrome-MCP-Route: - snapshot-/ref-basierte Aktionen statt CSS-Selektor-Targeting, Hooks für Datei-Uploads mit einer Datei, - keine Überschreibungen für Dialog-Timeouts, kein `wait --load networkidle`, und kein - `responsebody`, PDF-Export, Download-Interception oder Batch-Aktionen. -- Lokal verwaltete `openclaw`-Profile weisen `cdpPort` und `cdpUrl` automatisch zu; setzen Sie - `cdpUrl` nur explizit für Remote-CDP. -- Reihenfolge der Auto-Erkennung: Standardbrowser, falls Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Steuerdienst: nur loopback (Port abgeleitet von `gateway.port`, Standard `18791`). -- `extraArgs` hängt zusätzliche Start-Flags an den lokalen Chromium-Start an (zum Beispiel - `--disable-gpu`, Fenstergröße oder Debug-Flags). + Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` erkennen soll; verwenden Sie WS(S), wenn Ihr Provider Ihnen eine direkte DevTools-WebSocket-URL bereitstellt. +- Profile vom Typ `existing-session` sind nur auf dem Host verfügbar und verwenden Chrome MCP statt CDP. +- Profile vom Typ `existing-session` können `userDataDir` setzen, um auf ein bestimmtes Chromium-basiertes Browser-Profil wie Brave oder Edge zu zielen. +- Profile vom Typ `existing-session` behalten die aktuellen Routenbeschränkungen von Chrome MCP bei: snapshot-/ref-basierte Aktionen statt CSS-Selektor-Targeting, Hooks für das Hochladen einzelner Dateien, keine Überschreibungen von Dialog-Timeouts, kein `wait --load networkidle` sowie kein `responsebody`, kein PDF-Export, keine Download-Interception und keine Batch-Aktionen. +- Lokal verwaltete `openclaw`-Profile weisen `cdpPort` und `cdpUrl` automatisch zu; setzen Sie `cdpUrl` nur explizit für Remote-CDP. +- Reihenfolge der automatischen Erkennung: Standardbrowser, wenn Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Control-Service: nur loopback (Port von `gateway.port` abgeleitet, Standard `18791`). +- `extraArgs` hängt zusätzliche Start-Flags an den lokalen Chromium-Start an (zum Beispiel `--disable-gpu`, Fenstergröße oder Debug-Flags). --- @@ -2841,14 +2827,14 @@ Siehe [Plugins](/de/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // Emoji, kurzer Text, Bild-URL oder data-URI + avatar: "CB", // Emoji, kurzer Text, Bild-URL oder Data-URI }, }, } ``` -- `seamColor`: Akzentfarbe für das UI-Chrome der nativen App (Talk-Mode-Blasentönung usw.). -- `assistant`: Überschreibung der Identity in der Control UI. Fällt auf die aktive Agent-Identity zurück. +- `seamColor`: Akzentfarbe für native App-UI-Elemente (Talk-Mode-Bubble-Tönung usw.). +- `assistant`: Überschreibung der Identität in der Control UI. Fällt auf die aktive Agent-Identität zurück. --- @@ -2881,8 +2867,10 @@ Siehe [Plugins](/de/tools/plugin). enabled: true, basePath: "/openclaw", // root: "dist/control-ui", + // embedSandbox: "scripts", // strict | scripts | trusted + // allowExternalEmbedUrls: false, // gefährlich: absolute externe http(s)-Embed-URLs erlauben // allowedOrigins: ["https://control.example.com"], // erforderlich für nicht-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // gefährlicher Origin-Fallback-Modus über Host-Header + // dangerouslyAllowHostHeaderOriginFallback: false, // gefährlicher Host-Header-Origin-Fallback-Modus // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2896,7 +2884,7 @@ Siehe [Plugins](/de/tools/plugin). // Optional. Standard false. allowRealIpFallback: false, tools: { - // Zusätzliche HTTP-Denies für /tools/invoke + // Zusätzliche HTTP-Denys für /tools/invoke deny: ["browser"], // Tools aus der Standard-HTTP-Deny-Liste entfernen allow: ["gateway"], @@ -2915,41 +2903,41 @@ Siehe [Plugins](/de/tools/plugin). -- `mode`: `local` (Gateway ausführen) oder `remote` (mit Remote-Gateway verbinden). Das Gateway startet nur bei `local`. -- `port`: einzelner multiplexter Port für WS + HTTP. Priorität: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local` (Gateway ausführen) oder `remote` (mit Remote-Gateway verbinden). Das Gateway verweigert den Start, sofern nicht `local` gesetzt ist. +- `port`: einzelner multiplexierter Port für WS + HTTP. Priorität: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (Standard), `lan` (`0.0.0.0`), `tailnet` (nur Tailscale-IP) oder `custom`. -- **Legacy-Bind-Aliase**: Verwenden Sie Bind-Modus-Werte in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), nicht Host-Aliase (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Docker-Hinweis**: Das Standard-Binding `loopback` lauscht im Container auf `127.0.0.1`. Mit Docker-Bridge-Networking (`-p 18789:18789`) kommt Verkehr auf `eth0` an, sodass das Gateway nicht erreichbar ist. Verwenden Sie `--network host`, oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), um auf allen Interfaces zu lauschen. -- **Auth**: standardmäßig erforderlich. Nicht-Loopback-Bindings erfordern Gateway-Authentifizierung. In der Praxis bedeutet das ein gemeinsames Token/Passwort oder einen identitätsbewussten Reverse-Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token. -- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- und Dienstinstallations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und `mode` nicht gesetzt ist. -- `gateway.auth.mode: "none"`: expliziter Modus ohne Authentifizierung. Nur für vertrauenswürdige lokale local loopback-Setups verwenden; diese Option wird in Onboarding-Prompts absichtlich nicht angeboten. -- `gateway.auth.mode: "trusted-proxy"`: delegiert die Authentifizierung an einen identitätsbewussten Reverse-Proxy und vertraut Identitäts-Headern von `gateway.trustedProxies` (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet eine **nicht-loopback** Proxy-Quelle; Reverse-Proxys auf demselben Host über loopback erfüllen trusted-proxy auth nicht. -- `gateway.auth.allowTailscale`: wenn `true`, können Tailscale-Serve-Identity-Header die Authentifizierung für Control UI/WebSocket erfüllen (verifiziert über `tailscale whois`). HTTP-API-Endpunkte verwenden **nicht** diese Tailscale-Header-Auth; sie folgen stattdessen dem normalen HTTP-Auth-Modus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Standardmäßig `true`, wenn `tailscale.mode = "serve"` gesetzt ist. -- `gateway.auth.rateLimit`: optionaler Begrenzer für fehlgeschlagene Authentifizierung. Gilt pro Client-IP und pro Authentifizierungsbereich (gemeinsam genutztes Secret und Device-Token werden getrennt verfolgt). Blockierte Versuche geben `429` + `Retry-After` zurück. - - Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, clientIp}` vor dem Schreiben des Fehlschlags serialisiert. Gleichzeitige falsche Versuche desselben Clients können daher den Begrenzer bereits bei der zweiten Anfrage auslösen, statt dass beide als normale Fehlanpassungen durchrutschen. - - `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie `false`, wenn Sie absichtlich möchten, dass auch localhost-Verkehr begrenzt wird (für Test-Setups oder strikte Proxy-Deployments). -- Browser-Origin-WS-Authentifizierungsversuche werden immer mit deaktivierter Loopback-Ausnahme gedrosselt (Defense-in-Depth gegen browserbasierte Brute-Force-Angriffe auf localhost). -- Auf loopback sind diese browserbasierten Sperren pro normalisiertem `Origin`-Wert isoliert, sodass wiederholte Fehlschläge von einer localhost-Origin nicht automatisch eine andere Origin aussperren. -- `tailscale.mode`: `serve` (nur Tailnet, loopback-Bind) oder `funnel` (öffentlich, erfordert Auth). -- `controlUi.allowedOrigins`: explizite Browser-Origin-Allowlist für Gateway-WebSocket-Verbindungen. Erforderlich, wenn Browser-Clients von nicht-loopback Origins erwartet werden. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Origin-Fallback über den Host-Header für Deployments aktiviert, die absichtlich auf eine Origin-Richtlinie per Host-Header setzen. +- **Legacy-Bind-Aliasse**: Verwenden Sie Bind-Modus-Werte in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), nicht Host-Aliasse (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Docker-Hinweis**: Der Standard-Bind `loopback` lauscht im Container auf `127.0.0.1`. Bei Docker-Bridge-Netzwerk (`-p 18789:18789`) kommt der Datenverkehr über `eth0` an, daher ist das Gateway nicht erreichbar. Verwenden Sie `--network host`, oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), um auf allen Interfaces zu lauschen. +- **Auth**: standardmäßig erforderlich. Nicht-Loopback-Binds erfordern Gateway-Authentifizierung. In der Praxis bedeutet das ein gemeinsames Token/Passwort oder einen identitätsbewussten Reverse-Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token. +- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- sowie Service-Installations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und `mode` nicht gesetzt ist. +- `gateway.auth.mode: "none"`: expliziter Modus ohne Authentifizierung. Nur für vertrauenswürdige lokale loopback-Setups verwenden; dies wird absichtlich nicht in Onboarding-Prompts angeboten. +- `gateway.auth.mode: "trusted-proxy"`: Authentifizierung an einen identitätsbewussten Reverse-Proxy delegieren und Identitäts-Header von `gateway.trustedProxies` vertrauen (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet eine **nicht-loopback** Proxy-Quelle; gleichartige loopback-Reverse-Proxys erfüllen die trusted-proxy-Authentifizierung nicht. +- `gateway.auth.allowTailscale`: wenn `true`, können Tailscale-Serve-Identitäts-Header die Authentifizierung für Control UI/WebSocket erfüllen (über `tailscale whois` verifiziert). HTTP-API-Endpunkte verwenden diese Tailscale-Header-Authentifizierung **nicht**; sie folgen stattdessen dem normalen HTTP-Auth-Modus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass dem Gateway-Host vertraut wird. Standard ist `true`, wenn `tailscale.mode = "serve"` gesetzt ist. +- `gateway.auth.rateLimit`: optionaler Limiter für fehlgeschlagene Authentifizierungen. Gilt pro Client-IP und pro Auth-Bereich (Shared-Secret und Device-Token werden unabhängig voneinander verfolgt). Blockierte Versuche geben `429` + `Retry-After` zurück. + - Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, clientIp}` vor dem Schreiben des Fehlers serialisiert. Gleichzeitig auftretende fehlerhafte Versuche desselben Clients können daher bereits beim zweiten Request den Limiter auslösen, statt dass beide parallel als normale Fehlanpassungen durchlaufen. + - `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie `false`, wenn Sie absichtlich auch localhost-Datenverkehr ratenbegrenzen möchten (für Test-Setups oder strikte Proxy-Bereitstellungen). +- Browser-originierte WS-Authentifizierungsversuche werden immer mit deaktivierter loopback-Ausnahme gedrosselt (Defense-in-Depth gegen browserbasierte Brute-Force-Angriffe auf localhost). +- Auf loopback werden diese browser-originären Sperren nach normalisiertem `Origin`-Wert isoliert, sodass wiederholte Fehler von einem localhost-Origin nicht automatisch einen anderen Origin sperren. +- `tailscale.mode`: `serve` (nur tailnet, loopback-Bind) oder `funnel` (öffentlich, erfordert Auth). +- `controlUi.allowedOrigins`: explizite Allowlist von Browser-Origin-Werten für Gateway-WebSocket-Verbindungen. Erforderlich, wenn Browser-Clients von Nicht-Loopback-Origins erwartet werden. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Host-Header-Origin-Fallback für Bereitstellungen aktiviert, die absichtlich auf einer Host-Header-Origin-Richtlinie beruhen. - `remote.transport`: `ssh` (Standard) oder `direct` (ws/wss). Für `direct` muss `remote.url` `ws://` oder `wss://` sein. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: clientseitige Break-Glass-Überschreibung, die unverschlüsseltes `ws://` zu vertrauenswürdigen privaten Netzwerk-IPs erlaubt; Standard bleibt unverschlüsselter Verkehr nur für loopback. -- `gateway.remote.token` / `.password` sind Anmeldedatenfelder für Remote-Clients. Sie konfigurieren die Gateway-Authentifizierung nicht selbst. -- `gateway.push.apns.relay.baseUrl`: HTTPS-Basis-URL für das externe APNs-Relay, das von offiziellen/TestFlight-iOS-Builds verwendet wird, nachdem diese relaygestützte Registrierungen an das Gateway veröffentlicht haben. Diese URL muss mit der im iOS-Build einkompilierten Relay-URL übereinstimmen. -- `gateway.push.apns.relay.timeoutMs`: Timeout in Millisekunden für das Senden vom Gateway zum Relay. Standardmäßig `10000`. -- Relaygestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die gekoppelte iOS-App ruft `gateway.identity.get` ab, schließt diese Identität in die Relay-Registrierung ein und leitet eine registrierungsbezogene Sendeberechtigung an das Gateway weiter. Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: temporäre Env-Überschreibungen für die obige Relay-Konfiguration. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für die Entwicklung vorgesehene Escape-Hatch für loopback-HTTP-Relay-URLs. Produktions-Relay-URLs sollten HTTPS verwenden. -- `gateway.channelHealthCheckMinutes`: Intervall des Kanal-Gesundheitsmonitors in Minuten. Setzen Sie `0`, um Neustarts durch den Gesundheitsmonitor global zu deaktivieren. Standard: `5`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: clientseitige Break-Glass-Überschreibung, die Klartext-`ws://` zu vertrauenswürdigen IPs in privaten Netzwerken erlaubt; Standard bleibt loopback-only für Klartext. +- `gateway.remote.token` / `.password` sind Zugangsdatenfelder für den Remote-Client. Sie konfigurieren die Gateway-Authentifizierung nicht selbst. +- `gateway.push.apns.relay.baseUrl`: HTTPS-Basis-URL für das externe APNs-Relay, das von offiziellen/TestFlight-iOS-Builds verwendet wird, nachdem sie relaygestützte Registrierungen an das Gateway veröffentlicht haben. Diese URL muss mit der in den iOS-Build einkompilierten Relay-URL übereinstimmen. +- `gateway.push.apns.relay.timeoutMs`: Timeout in Millisekunden für das Senden vom Gateway an das Relay. Standard ist `10000`. +- Relay-gestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die gekoppelte iOS-App ruft `gateway.identity.get` ab, schließt diese Identität in die Relay-Registrierung ein und leitet eine registrierungsbezogene Sendeberechtigung an das Gateway weiter. Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: temporäre Env-Überschreibungen für die oben genannte Relay-Konfiguration. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für Entwicklung vorgesehener Escape Hatch für loopback-HTTP-Relay-URLs. Produktions-Relay-URLs sollten HTTPS verwenden. +- `gateway.channelHealthCheckMinutes`: Intervall des Kanal-Health-Monitors in Minuten. Setzen Sie `0`, um Neustarts durch den Health-Monitor global zu deaktivieren. Standard: `5`. - `gateway.channelStaleEventThresholdMinutes`: Schwellenwert für veraltete Sockets in Minuten. Halten Sie diesen Wert größer oder gleich `gateway.channelHealthCheckMinutes`. Standard: `30`. -- `gateway.channelMaxRestartsPerHour`: maximale Anzahl von Neustarts durch den Gesundheitsmonitor pro Kanal/Konto innerhalb einer gleitenden Stunde. Standard: `10`. -- `channels..healthMonitor.enabled`: kanalbezogenes Opt-out für Neustarts durch den Gesundheitsmonitor, während der globale Monitor aktiviert bleibt. -- `channels..accounts..healthMonitor.enabled`: Überschreibung pro Konto für Multi-Konto-Kanäle. Wenn gesetzt, hat sie Vorrang vor der kanalbezogenen Überschreibung. +- `gateway.channelMaxRestartsPerHour`: maximale Anzahl von Health-Monitor-Neustarts pro Kanal/Konto in einer rollierenden Stunde. Standard: `10`. +- `channels..healthMonitor.enabled`: kanalbezogenes Opt-out für Neustarts durch den Health-Monitor, während der globale Monitor aktiv bleibt. +- `channels..accounts..healthMonitor.enabled`: kontobezogene Überschreibung für Multi-Konto-Kanäle. Wenn gesetzt, hat sie Vorrang vor der kanalbezogenen Überschreibung. - Lokale Gateway-Aufrufpfade können `gateway.remote.*` nur dann als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist. -- Wenn `gateway.auth.token` / `gateway.auth.password` explizit per SecretRef konfiguriert und nicht auflösbar sind, schlägt die Auflösung fail-closed fehl (kein maskierender Remote-Fallback). -- `trustedProxies`: Reverse-Proxy-IPs, die TLS terminieren oder Header mit weitergeleiteten Client-Informationen einfügen. Führen Sie nur Proxys auf, die Sie kontrollieren. Loopback-Einträge sind weiterhin für Setups mit demselben Host für Proxy-/lokale Erkennung gültig (zum Beispiel Tailscale Serve oder ein lokaler Reverse-Proxy), machen loopback-Anfragen jedoch **nicht** für `gateway.auth.mode: "trusted-proxy"` geeignet. -- `allowRealIpFallback`: wenn `true`, akzeptiert das Gateway `X-Real-IP`, falls `X-Forwarded-For` fehlt. Standard `false` für fail-closed Verhalten. +- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht aufgelöst ist, schlägt die Auflösung fail-closed fehl (kein maskierender Remote-Fallback). +- `trustedProxies`: IPs von Reverse-Proxys, die TLS terminieren oder Header mit weitergeleiteten Client-Informationen einfügen. Listen Sie nur Proxys auf, die Sie kontrollieren. Loopback-Einträge sind weiterhin für Setups mit gleichartigem Proxy/lokaler Erkennung gültig (zum Beispiel Tailscale Serve oder ein lokaler Reverse-Proxy), machen loopback-Anfragen jedoch **nicht** für `gateway.auth.mode: "trusted-proxy"` zulässig. +- `allowRealIpFallback`: wenn `true`, akzeptiert das Gateway `X-Real-IP`, falls `X-Forwarded-For` fehlt. Standard `false` für fail-closed-Verhalten. - `gateway.tools.deny`: zusätzliche Tool-Namen, die für HTTP `POST /tools/invoke` blockiert werden (erweitert die Standard-Deny-Liste). - `gateway.tools.allow`: entfernt Tool-Namen aus der Standard-HTTP-Deny-Liste. @@ -2959,13 +2947,13 @@ Siehe [Plugins](/de/tools/plugin). - Chat Completions: standardmäßig deaktiviert. Aktivieren mit `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Härtung von URL-Eingaben für Responses: +- Härtung für URL-Eingaben bei Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Leere Allowlists werden als nicht gesetzt behandelt; verwenden Sie `gateway.http.endpoints.responses.files.allowUrl=false` - und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um das Abrufen per URL zu deaktivieren. -- Optionaler Header zur Response-Härtung: + und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um URL-Fetching zu deaktivieren. +- Optionaler Header zur Härtung von Antworten: - `gateway.http.securityHeaders.strictTransportSecurity` (nur für HTTPS-Origins setzen, die Sie kontrollieren; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Multi-Instance-Isolation @@ -2999,10 +2987,10 @@ Siehe [Mehrere Gateways](/de/gateway/multiple-gateways). ``` - `enabled`: aktiviert TLS-Terminierung am Gateway-Listener (HTTPS/WSS) (Standard: `false`). -- `autoGenerate`: erzeugt automatisch ein lokales selbstsigniertes Zertifikat/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokale/dev-Verwendung. +- `autoGenerate`: erzeugt automatisch ein lokales selbstsigniertes Zertifikat-/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokale/dev-Nutzung. - `certPath`: Dateisystempfad zur TLS-Zertifikatsdatei. -- `keyPath`: Dateisystempfad zum privaten TLS-Schlüssel; Zugriff per Berechtigungen einschränken. -- `caPath`: optionaler Pfad zu einem CA-Bundle für Client-Verifizierung oder benutzerdefinierte Vertrauenskette. +- `keyPath`: Dateisystempfad zur privaten TLS-Schlüsseldatei; mit eingeschränkten Berechtigungen schützen. +- `caPath`: optionaler Pfad zu einem CA-Bundle für Client-Verifikation oder benutzerdefinierte Vertrauenskette. ### `gateway.reload` @@ -3020,11 +3008,11 @@ Siehe [Mehrere Gateways](/de/gateway/multiple-gateways). - `mode`: steuert, wie Konfigurationsänderungen zur Laufzeit angewendet werden. - `"off"`: Live-Änderungen ignorieren; Änderungen erfordern einen expliziten Neustart. - - `"restart"`: den Gateway-Prozess bei Konfigurationsänderungen immer neu starten. + - `"restart"`: Gateway-Prozess bei Konfigurationsänderung immer neu starten. - `"hot"`: Änderungen im Prozess anwenden, ohne neu zu starten. - - `"hybrid"` (Standard): zuerst Hot-Reload versuchen; bei Bedarf auf Neustart zurückfallen. + - `"hybrid"` (Standard): zuerst Hot-Reload versuchen; falls erforderlich auf Neustart zurückfallen. - `debounceMs`: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nicht negative Ganzzahl). -- `deferralTimeoutMs`: maximale Wartezeit in ms auf laufende Vorgänge, bevor ein Neustart erzwungen wird (Standard: `300000` = 5 Minuten). +- `deferralTimeoutMs`: maximale Wartezeit in ms auf laufende Operationen, bevor ein Neustart erzwungen wird (Standard: `300000` = 5 Minuten). --- @@ -3062,36 +3050,36 @@ Siehe [Mehrere Gateways](/de/gateway/multiple-gateways). ``` Auth: `Authorization: Bearer ` oder `x-openclaw-token: `. -Hook-Tokens im Query-String werden abgelehnt. +Hook-Token in Query-Strings werden abgelehnt. Validierungs- und Sicherheitshinweise: - `hooks.enabled=true` erfordert ein nicht leeres `hooks.token`. - `hooks.token` muss sich von `gateway.auth.token` **unterscheiden**; die Wiederverwendung des Gateway-Tokens wird abgelehnt. - `hooks.path` darf nicht `/` sein; verwenden Sie einen dedizierten Unterpfad wie `/hooks`. -- Wenn `hooks.allowRequestSessionKey=true`, beschränken Sie `hooks.allowedSessionKeyPrefixes` (zum Beispiel `["hook:"]`). +- Wenn `hooks.allowRequestSessionKey=true`, schränken Sie `hooks.allowedSessionKeyPrefixes` ein (zum Beispiel `["hook:"]`). **Endpunkte:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` aus dem Request-Payload wird nur akzeptiert, wenn `hooks.allowRequestSessionKey=true` (Standard: `false`). -- `POST /hooks/` → wird über `hooks.mappings` aufgelöst +- `POST /hooks/` → aufgelöst über `hooks.mappings` -- `match.path` gleicht den Unterpfad nach `/hooks` ab (z. B. `/hooks/gmail` → `gmail`). -- `match.source` gleicht ein Payload-Feld für generische Pfade ab. -- Templates wie `{{messages[0].subject}}` lesen aus dem Payload. +- `match.path` stimmt mit dem Unterpfad nach `/hooks` überein (z. B. `/hooks/gmail` → `gmail`). +- `match.source` stimmt mit einem Payload-Feld für generische Pfade überein. +- Vorlagen wie `{{messages[0].subject}}` lesen aus dem Payload. - `transform` kann auf ein JS-/TS-Modul verweisen, das eine Hook-Aktion zurückgibt. - `transform.module` muss ein relativer Pfad sein und innerhalb von `hooks.transformsDir` bleiben (absolute Pfade und Traversal werden abgelehnt). -- `agentId` leitet an einen bestimmten Agenten weiter; unbekannte IDs fallen auf den Standard zurück. +- `agentId` routet an einen bestimmten Agent; unbekannte IDs fallen auf den Standard zurück. - `allowedAgentIds`: beschränkt explizites Routing (`*` oder weggelassen = alle zulassen, `[]` = alle verweigern). - `defaultSessionKey`: optionaler fester Sitzungsschlüssel für Hook-Agent-Läufe ohne explizites `sessionKey`. - `allowRequestSessionKey`: erlaubt Aufrufern von `/hooks/agent`, `sessionKey` zu setzen (Standard: `false`). - `allowedSessionKeyPrefixes`: optionale Präfix-Allowlist für explizite `sessionKey`-Werte (Request + Mapping), z. B. `["hook:"]`. - `deliver: true` sendet die endgültige Antwort an einen Kanal; `channel` ist standardmäßig `last`. -- `model` überschreibt das LLM für diesen Hook-Lauf (muss erlaubt sein, wenn ein Modellkatalog gesetzt ist). +- `model` überschreibt das LLM für diesen Hook-Lauf (muss zulässig sein, wenn ein Modellkatalog gesetzt ist). @@ -3119,7 +3107,7 @@ Validierungs- und Sicherheitshinweise: ``` - Das Gateway startet `gog gmail watch serve` beim Booten automatisch, wenn es konfiguriert ist. Setzen Sie `OPENCLAW_SKIP_GMAIL_WATCHER=1`, um dies zu deaktivieren. -- Führen Sie nicht zusätzlich zu dem Gateway einen separaten `gog gmail watch serve` aus. +- Führen Sie kein separates `gog gmail watch serve` parallel zum Gateway aus. --- @@ -3135,22 +3123,22 @@ Validierungs- und Sicherheitshinweise: } ``` -- Stellt agentenbearbeitbares HTML/CSS/JS und A2UI über HTTP unter dem Gateway-Port bereit: +- Stellt durch Agents bearbeitbares HTML/CSS/JS und A2UI über HTTP unter dem Gateway-Port bereit: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Nur lokal: Behalten Sie `gateway.bind: "loopback"` bei (Standard). -- Bei Nicht-Loopback-Bindings erfordern Canvas-Routen Gateway-Authentifizierung (Token/Passwort/trusted-proxy), genauso wie andere Gateway-HTTP-Oberflächen. -- Node-WebViews senden typischerweise keine Auth-Header; nachdem ein Node gekoppelt und verbunden ist, bewirbt das Gateway nodebezogene Capability-URLs für den Zugriff auf canvas/A2UI. -- Capability-URLs sind an die aktive Node-WS-Sitzung gebunden und laufen schnell ab. Es wird kein IP-basierter Fallback verwendet. -- Fügt dem ausgelieferten HTML einen Live-Reload-Client hinzu. +- Nur lokal: Behalten Sie `gateway.bind: "loopback"` (Standard) bei. +- Bei Nicht-Loopback-Binds erfordern Canvas-Routen Gateway-Authentifizierung (Token/Passwort/trusted-proxy), genauso wie andere HTTP-Oberflächen des Gateways. +- Node-WebViews senden typischerweise keine Auth-Header; nachdem ein Node gepaart und verbunden ist, kündigt das Gateway nodebezogene Capability-URLs für den Zugriff auf Canvas/A2UI an. +- Capability-URLs sind an die aktive Node-WS-Sitzung gebunden und laufen schnell ab. Ein IP-basierter Fallback wird nicht verwendet. +- Fügt dem ausgelieferten HTML einen Live-Reload-Client ein. - Erstellt automatisch eine Starter-`index.html`, wenn leer. - Stellt A2UI auch unter `/__openclaw__/a2ui/` bereit. - Änderungen erfordern einen Gateway-Neustart. -- Deaktivieren Sie Live-Reload für große Verzeichnisse oder bei `EMFILE`-Fehlern. +- Deaktivieren Sie Live Reload bei großen Verzeichnissen oder `EMFILE`-Fehlern. --- -## Discovery +## Erkennung ### mDNS (Bonjour) @@ -3178,7 +3166,7 @@ Validierungs- und Sicherheitshinweise: } ``` -Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für netzwerkübergreifende Discovery kombinieren Sie dies mit einem DNS-Server (CoreDNS empfohlen) + Tailscale Split DNS. +Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für netzwerkübergreifende Erkennung kombinieren Sie dies mit einem DNS-Server (CoreDNS empfohlen) + Tailscale Split DNS. Einrichtung: `openclaw dns setup --apply`. @@ -3186,7 +3174,7 @@ Einrichtung: `openclaw dns setup --apply`. ## Umgebung -### `env` (inline Env-Variablen) +### `env` (Inline-Umgebungsvariablen) ```json5 { @@ -3203,14 +3191,14 @@ Einrichtung: `openclaw dns setup --apply`. } ``` -- Inline-Env-Variablen werden nur angewendet, wenn der Prozess-Env der Schlüssel fehlt. -- `.env`-Dateien: `.env` im aktuellen Arbeitsverzeichnis + `~/.openclaw/.env` (keine von beiden überschreibt vorhandene Variablen). +- Inline-Umgebungsvariablen werden nur angewendet, wenn die Prozessumgebung den Schlüssel nicht enthält. +- `.env`-Dateien: `.env` im aktuellen Arbeitsverzeichnis + `~/.openclaw/.env` (keine der beiden überschreibt bestehende Variablen). - `shellEnv`: importiert fehlende erwartete Schlüssel aus Ihrem Login-Shell-Profil. -- Siehe [Umgebung](/de/help/environment) für die vollständige Priorität. +- Vollständige Priorität finden Sie unter [Umgebung](/de/help/environment). -### Env-Variablen-Substitution +### Substitution von Umgebungsvariablen -Verweisen Sie in jedem Konfigurationsstring mit `${VAR_NAME}` auf Env-Variablen: +Referenzieren Sie Umgebungsvariablen in jeder Konfigurationszeichenfolge mit `${VAR_NAME}`: ```json5 { @@ -3220,9 +3208,9 @@ Verweisen Sie in jedem Konfigurationsstring mit `${VAR_NAME}` auf Env-Variablen: } ``` -- Es werden nur Großbuchstabennamen passend zu `[A-Z_][A-Z0-9_]*` erkannt. +- Es werden nur großgeschriebene Namen abgeglichen: `[A-Z_][A-Z0-9_]*`. - Fehlende/leere Variablen werfen beim Laden der Konfiguration einen Fehler. -- Mit `$${VAR}` escapen Sie ein literales `${VAR}`. +- Mit `$${VAR}` escapen Sie ein wörtliches `${VAR}`. - Funktioniert mit `$include`. --- @@ -3242,18 +3230,18 @@ Verwenden Sie eine Objektform: Validierung: - `provider`-Muster: `^[a-z][a-z0-9_-]{0,63}$` -- `source: "env"` ID-Muster: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` ID: absoluter JSON-Pointer (z. B. `"/providers/openai/apiKey"`) -- `source: "exec"` ID-Muster: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"`-IDs dürfen keine slashgetrennten Pfadsegmente `.` oder `..` enthalten (z. B. wird `a/../b` abgelehnt) +- `source: "env"`-`id`-Muster: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"`-`id`: absoluter JSON-Pointer (zum Beispiel `"/providers/openai/apiKey"`) +- `source: "exec"`-`id`-Muster: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `source: "exec"`-IDs dürfen keine slashgetrennten Pfadsegmente `.` oder `..` enthalten (zum Beispiel wird `a/../b` abgelehnt) -### Unterstützte Oberfläche für Anmeldedaten +### Unterstützte Zugangsdatenoberfläche - Kanonische Matrix: [SecretRef Credential Surface](/de/reference/secretref-credential-surface) -- `secrets apply` zielt auf unterstützte Pfade für Anmeldedaten in `openclaw.json`. +- `secrets apply` zielt auf unterstützte Zugangsdatenpfade in `openclaw.json`. - `auth-profiles.json`-Refs sind in der Laufzeitauflösung und Audit-Abdeckung enthalten. -### Konfiguration der Secret-Provider +### Konfiguration von Secret-Providern ```json5 { @@ -3283,17 +3271,17 @@ Validierung: Hinweise: -- Der `file`-Provider unterstützt `mode: "json"` und `mode: "singleValue"` (`id` muss im Modus singleValue `"value"` sein). -- Der `exec`-Provider erfordert einen absoluten `command`-Pfad und verwendet Protokoll-Payloads auf stdin/stdout. -- Standardmäßig werden Pfade zu Symlink-Befehlen abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zuzulassen, während der aufgelöste Zielpfad validiert wird. -- Wenn `trustedDirs` konfiguriert ist, gilt die Prüfung vertrauenswürdiger Verzeichnisse für den aufgelösten Zielpfad. +- Der `file`-Provider unterstützt `mode: "json"` und `mode: "singleValue"` (`id` muss im Modus `singleValue` `"value"` sein). +- Der `exec`-Provider erfordert einen absoluten `command`-Pfad und verwendet Protokoll-Payloads über stdin/stdout. +- Standardmäßig werden Befehls-Pfade, die Symlinks sind, abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zu erlauben, während der aufgelöste Zielpfad validiert wird. +- Wenn `trustedDirs` konfiguriert ist, gilt die trusted-dir-Prüfung für den aufgelösten Zielpfad. - Die Child-Umgebung von `exec` ist standardmäßig minimal; übergeben Sie erforderliche Variablen explizit mit `passEnv`. -- SecretRefs werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst; Request-Pfade lesen danach nur noch aus diesem Snapshot. -- Active-Surface-Filtering gilt während der Aktivierung: nicht aufgelöste Refs auf aktivierten Oberflächen lassen Start/Reload fehlschlagen, während inaktive Oberflächen mit Diagnostik übersprungen werden. +- SecretRefs werden bei der Aktivierung in einen In-Memory-Snapshot aufgelöst; Request-Pfade lesen danach nur noch aus dem Snapshot. +- Filtering nach aktiver Oberfläche gilt während der Aktivierung: Nicht aufgelöste Refs auf aktiven Oberflächen führen zu einem fail-closed bei Start/Reload, während inaktive Oberflächen mit Diagnosen übersprungen werden. --- -## Auth-Speicherung +## Auth-Speicher ```json5 { @@ -3312,12 +3300,12 @@ Hinweise: ``` - Profile pro Agent werden unter `/auth-profiles.json` gespeichert. -- `auth-profiles.json` unterstützt refs auf Wertebene (`keyRef` für `api_key`, `tokenRef` für `token`) für statische Anmeldedatenmodi. -- Profile im OAuth-Modus (`auth.profiles..mode = "oauth"`) unterstützen keine SecretRef-gestützten auth-profile-Anmeldedaten. -- Statische Laufzeit-Anmeldedaten stammen aus aufgelösten In-Memory-Snapshots; Legacy-statische Einträge in `auth.json` werden bereinigt, wenn sie entdeckt werden. +- `auth-profiles.json` unterstützt Refs auf Wertebene (`keyRef` für `api_key`, `tokenRef` für `token`) für statische Zugangsdatenmodi. +- Profile im OAuth-Modus (`auth.profiles..mode = "oauth"`) unterstützen keine SecretRef-gestützten Auth-Profile-Zugangsdaten. +- Statische Laufzeit-Zugangsdaten stammen aus aufgelösten In-Memory-Snapshots; veraltete statische Einträge in `auth.json` werden beim Erkennen bereinigt. - Legacy-OAuth-Importe aus `~/.openclaw/credentials/oauth.json`. - Siehe [OAuth](/de/concepts/oauth). -- Verhalten der Secrets-Laufzeit und Tooling für `audit/configure/apply`: [Secrets Management](/de/gateway/secrets). +- Verhalten der Secrets-Laufzeit und Tools für `audit/configure/apply`: [Secrets Management](/de/gateway/secrets). ### `auth.cooldowns` @@ -3339,19 +3327,19 @@ Hinweise: } ``` -- `billingBackoffHours`: Basis-Backoff in Stunden, wenn ein Profil aufgrund echter Abrechnungs-/unzureichender-Guthaben-Fehler fehlschlägt (Standard: `5`). Expliziter Abrechnungstext kann hier auch bei Antworten `401`/`403` landen, providerbezogene Textmatcher bleiben jedoch auf den Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter `Key limit exceeded`). Wiederholbare HTTP-`402`-Nutzungsfenster- oder Ausgabenlimitmeldungen für Organisation/Workspace bleiben stattdessen im Pfad `rate_limit`. -- `billingBackoffHoursByProvider`: optionale providerbezogene Überschreibungen für Billing-Backoff in Stunden. -- `billingMaxHours`: Obergrenze in Stunden für exponentielles Wachstum des Billing-Backoff (Standard: `24`). +- `billingBackoffHours`: Basis-Backoff in Stunden, wenn ein Profil aufgrund echter Abrechnungs-/unzureichender-Guthaben-Fehler fehlschlägt (Standard: `5`). Expliziter Abrechnungstext kann selbst bei `401`-/`403`-Antworten hier landen, aber providerspezifische Text-Matcher bleiben auf den jeweiligen Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter `Key limit exceeded`). Wiederholbare `402`-Nutzungsfenster- oder Organisations-/Workspace-Ausgabenlimit-Meldungen bleiben stattdessen im Pfad `rate_limit`. +- `billingBackoffHoursByProvider`: optionale Überschreibungen der Billing-Backoff-Stunden pro Provider. +- `billingMaxHours`: Obergrenze in Stunden für das exponentielle Anwachsen des Billing-Backoff (Standard: `24`). - `authPermanentBackoffMinutes`: Basis-Backoff in Minuten für High-Confidence-Fehler vom Typ `auth_permanent` (Standard: `10`). -- `authPermanentMaxMinutes`: Obergrenze in Minuten für das Wachstum des Backoff bei `auth_permanent` (Standard: `60`). -- `failureWindowHours`: gleitendes Fenster in Stunden, das für Backoff-Zähler verwendet wird (Standard: `24`). -- `overloadedProfileRotations`: maximale Anzahl an Rotationen von Auth-Profilen desselben Providers bei Überlastungsfehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Formen mit Provider-busy wie `ModelNotReadyException` fallen hierunter. -- `overloadedBackoffMs`: feste Verzögerung vor erneutem Versuch einer überlasteten Provider-/Profilrotation (Standard: `0`). -- `rateLimitedProfileRotations`: maximale Anzahl an Rotationen von Auth-Profilen desselben Providers bei Rate-Limit-Fehlern, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Rate-Limit-Bucket umfasst providergeformte Texte wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`. +- `authPermanentMaxMinutes`: Obergrenze in Minuten für das Anwachsen des `auth_permanent`-Backoff (Standard: `60`). +- `failureWindowHours`: rollierendes Fenster in Stunden, das für Backoff-Zähler verwendet wird (Standard: `24`). +- `overloadedProfileRotations`: maximale Anzahl von Auth-Profile-Rotationen beim selben Provider für Überlastungsfehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Provider-busy-Formen wie `ModelNotReadyException` landen hier. +- `overloadedBackoffMs`: feste Verzögerung vor erneutem Versuch einer Rotation eines überlasteten Provider-/Profils (Standard: `0`). +- `rateLimitedProfileRotations`: maximale Anzahl von Auth-Profile-Rotationen beim selben Provider für Rate-Limit-Fehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Rate-Limit-Bucket umfasst providerförmigen Text wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`. --- -## Protokollierung +## Logging ```json5 { @@ -3368,8 +3356,8 @@ Hinweise: - Standard-Logdatei: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Setzen Sie `logging.file` für einen stabilen Pfad. -- `consoleLevel` wird bei `--verbose` auf `debug` erhöht. -- `maxFileBytes`: maximale Logdateigröße in Bytes, bevor Schreibvorgänge unterdrückt werden (positive Ganzzahl; Standard: `524288000` = 500 MB). Verwenden Sie für Produktions-Deployments externe Logrotation. +- `consoleLevel` wird mit `--verbose` auf `debug` erhöht. +- `maxFileBytes`: maximale Größe der Logdatei in Bytes, bevor Schreibvorgänge unterdrückt werden (positive Ganzzahl; Standard: `524288000` = 500 MB). Verwenden Sie für Produktionsbereitstellungen externe Logrotation. --- @@ -3406,20 +3394,20 @@ Hinweise: } ``` -- `enabled`: globaler Schalter für Instrumentierungsausgabe (Standard: `true`). -- `flags`: Array von Flag-Strings zum Aktivieren gezielter Protokollausgabe (unterstützt Wildcards wie `"telegram.*"` oder `"*"`). -- `stuckSessionWarnMs`: Altersschwellenwert in ms für die Ausgabe von Warnungen zu hängenden Sitzungen, solange eine Sitzung im Verarbeitungszustand bleibt. +- `enabled`: globaler Hauptschalter für Instrumentierungsausgaben (Standard: `true`). +- `flags`: Array von Flag-Strings zum Aktivieren gezielter Log-Ausgaben (unterstützt Wildcards wie `"telegram.*"` oder `"*"`). +- `stuckSessionWarnMs`: Altersschwellenwert in ms für die Ausgabe von Warnungen zu festhängenden Sitzungen, solange eine Sitzung im Verarbeitungsstatus bleibt. - `otel.enabled`: aktiviert die OpenTelemetry-Export-Pipeline (Standard: `false`). - `otel.endpoint`: Collector-URL für den OTel-Export. - `otel.protocol`: `"http/protobuf"` (Standard) oder `"grpc"`. - `otel.headers`: zusätzliche HTTP-/gRPC-Metadaten-Header, die mit OTel-Exportanfragen gesendet werden. -- `otel.serviceName`: Dienstname für Ressourcenattribute. -- `otel.traces` / `otel.metrics` / `otel.logs`: aktiviert den Export von Traces, Metriken oder Logs. +- `otel.serviceName`: Servicename für Ressourcenattribute. +- `otel.traces` / `otel.metrics` / `otel.logs`: aktiviert Trace-, Metrik- oder Log-Export. - `otel.sampleRate`: Trace-Sampling-Rate `0`–`1`. -- `otel.flushIntervalMs`: periodisches Flush-Intervall für Telemetrie in ms. +- `otel.flushIntervalMs`: Intervall in ms für periodisches Flushen von Telemetrie. - `cacheTrace.enabled`: protokolliert Cache-Trace-Snapshots für eingebettete Läufe (Standard: `false`). - `cacheTrace.filePath`: Ausgabepfad für Cache-Trace-JSONL (Standard: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: steuern, was in die Cache-Trace-Ausgabe aufgenommen wird (alle standardmäßig: `true`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: steuern, was in der Cache-Trace-Ausgabe enthalten ist (alle standardmäßig: `true`). --- @@ -3444,9 +3432,9 @@ Hinweise: - `channel`: Release-Kanal für npm-/Git-Installationen — `"stable"`, `"beta"` oder `"dev"`. - `checkOnStart`: beim Start des Gateways auf npm-Updates prüfen (Standard: `true`). - `auto.enabled`: Hintergrund-Auto-Update für Paketinstallationen aktivieren (Standard: `false`). -- `auto.stableDelayHours`: minimale Verzögerung in Stunden vor automatischer Anwendung im Stable-Kanal (Standard: `6`; max: `168`). -- `auto.stableJitterHours`: zusätzliches Rollout-Streuungsfenster in Stunden für den Stable-Kanal (Standard: `12`; max: `168`). -- `auto.betaCheckIntervalHours`: wie oft Prüfungen im Beta-Kanal in Stunden ausgeführt werden (Standard: `1`; max: `24`). +- `auto.stableDelayHours`: minimale Verzögerung in Stunden vor automatischer Anwendung im Stable-Kanal (Standard: `6`; Maximalwert: `168`). +- `auto.stableJitterHours`: zusätzliches Verteilungsfenster in Stunden für den Stable-Kanal-Rollout (Standard: `12`; Maximalwert: `168`). +- `auto.betaCheckIntervalHours`: wie oft Prüfungen im Beta-Kanal in Stunden ausgeführt werden (Standard: `1`; Maximalwert: `24`). --- @@ -3480,20 +3468,20 @@ Hinweise: ``` - `enabled`: globales ACP-Feature-Gate (Standard: `false`). -- `dispatch.enabled`: unabhängiges Gate für die Verteilung von ACP-Sitzungsturns (Standard: `true`). Setzen Sie `false`, um ACP-Befehle verfügbar zu halten, aber die Ausführung zu blockieren. +- `dispatch.enabled`: unabhängiges Gate für die Verteilung von ACP-Sitzungs-Turns (Standard: `true`). Setzen Sie `false`, um ACP-Befehle verfügbar zu halten, aber die Ausführung zu blockieren. - `backend`: Standard-ID des ACP-Laufzeit-Backends (muss einem registrierten ACP-Laufzeit-Plugin entsprechen). - `defaultAgent`: Fallback-Ziel-Agent-ID für ACP, wenn Starts kein explizites Ziel angeben. -- `allowedAgents`: Allowlist von Agent-IDs, die für ACP-Laufzeitsitzungen erlaubt sind; leer bedeutet keine zusätzliche Einschränkung. +- `allowedAgents`: Allowlist von Agent-IDs, die für ACP-Laufzeitsitzungen zulässig sind; leer bedeutet keine zusätzliche Einschränkung. - `maxConcurrentSessions`: maximale Anzahl gleichzeitig aktiver ACP-Sitzungen. - `stream.coalesceIdleMs`: Idle-Flush-Fenster in ms für gestreamten Text. -- `stream.maxChunkChars`: maximale Chunk-Größe vor dem Aufteilen der Projektion gestreamter Blöcke. +- `stream.maxChunkChars`: maximale Chunk-Größe, bevor die Projektion gestreamter Blöcke aufgeteilt wird. - `stream.repeatSuppression`: unterdrückt wiederholte Status-/Tool-Zeilen pro Turn (Standard: `true`). -- `stream.deliveryMode`: `"live"` streamt schrittweise; `"final_only"` puffert bis zu terminalen Turn-Ereignissen. +- `stream.deliveryMode`: `"live"` streamt inkrementell; `"final_only"` puffert bis zu den terminalen Turn-Ereignissen. - `stream.hiddenBoundarySeparator`: Trennzeichen vor sichtbarem Text nach versteckten Tool-Ereignissen (Standard: `"paragraph"`). -- `stream.maxOutputChars`: maximale Anzahl an Assistant-Ausgabezeichen, die pro ACP-Turn projiziert werden. -- `stream.maxSessionUpdateChars`: maximale Zeichenanzahl für projizierte ACP-Status-/Update-Zeilen. +- `stream.maxOutputChars`: maximale Anzahl projizierter Assistant-Ausgabezeichen pro ACP-Turn. +- `stream.maxSessionUpdateChars`: maximale Zeichenzahl für projizierte ACP-Status-/Update-Zeilen. - `stream.tagVisibility`: Zuordnung von Tag-Namen zu booleschen Sichtbarkeitsüberschreibungen für gestreamte Ereignisse. -- `runtime.ttlMinutes`: Idle-TTL in Minuten für ACP-Sitzungs-Worker, bevor sie bereinigt werden können. +- `runtime.ttlMinutes`: Idle-TTL in Minuten für ACP-Sitzungs-Worker, bevor sie für die Bereinigung infrage kommen. - `runtime.installCommand`: optionaler Installationsbefehl, der beim Bootstrap einer ACP-Laufzeitumgebung ausgeführt wird. --- @@ -3510,17 +3498,17 @@ Hinweise: } ``` -- `cli.banner.taglineMode` steuert den Stil der Banner-Tagline: - - `"random"` (Standard): rotierende witzige/saisonale Taglines. - - `"default"`: feste neutrale Tagline (`All your chats, one OpenClaw.`). - - `"off"`: kein Tagline-Text (Banner-Titel/Version werden weiterhin angezeigt). -- Um das gesamte Banner auszublenden (nicht nur Taglines), setzen Sie die Env-Variable `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` steuert den Stil des Banner-Slogans: + - `"random"` (Standard): rotierende lustige/saisonale Slogans. + - `"default"`: fester neutraler Slogan (`All your chats, one OpenClaw.`). + - `"off"`: kein Slogantext (Banner-Titel/Version werden weiterhin angezeigt). +- Um das gesamte Banner auszublenden (nicht nur Slogans), setzen Sie die Umgebungsvariable `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Metadaten, die von geführten CLI-Setup-Abläufen geschrieben werden (`onboard`, `configure`, `doctor`): +Metadaten, die von geführten CLI-Setup-Abläufen (`onboard`, `configure`, `doctor`) geschrieben werden: ```json5 { @@ -3538,13 +3526,13 @@ Metadaten, die von geführten CLI-Setup-Abläufen geschrieben werden (`onboard`, ## Identity -Siehe `agents.list`-Identity-Felder unter [Agent-Standardwerte](#agent-defaults). +Siehe die Identity-Felder in `agents.list` unter [Agent-Standards](#agent-defaults). --- ## Bridge (Legacy, entfernt) -Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über das Gateway-WebSocket. `bridge.*`-Schlüssel sind nicht mehr Teil des Konfigurationsschemas (die Validierung schlägt fehl, bis sie entfernt werden; `openclaw doctor --fix` kann unbekannte Schlüssel entfernen). +Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über das Gateway-WebSocket. Schlüssel unter `bridge.*` sind nicht mehr Teil des Konfigurationsschemas (die Validierung schlägt fehl, bis sie entfernt werden; `openclaw doctor --fix` kann unbekannte Schlüssel entfernen). @@ -3575,19 +3563,19 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über maxConcurrentRuns: 2, webhook: "https://example.invalid/legacy", // veralteter Fallback für gespeicherte Jobs mit notify:true webhookToken: "replace-with-dedicated-token", // optionales Bearer-Token für ausgehende Webhook-Authentifizierung - sessionRetention: "24h", // Dauer-String oder false + sessionRetention: "24h", // Dauerzeichenfolge oder false runLog: { - maxBytes: "2mb", // Standard 2_000_000 Bytes - keepLines: 2000, // Standard 2000 + maxBytes: "2mb", // standardmäßig 2_000_000 Bytes + keepLines: 2000, // standardmäßig 2000 }, }, } ``` -- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Laufsitzungen aufbewahrt werden, bevor sie aus `sessions.json` entfernt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; setzen Sie `false`, um dies zu deaktivieren. -- `runLog.maxBytes`: maximale Größe pro Lauf-Logdatei (`cron/runs/.jsonl`), bevor beschnitten wird. Standard: `2_000_000` Bytes. -- `runLog.keepLines`: neueste Zeilen, die beibehalten werden, wenn das Beschneiden des Lauf-Logs ausgelöst wird. Standard: `2000`. -- `webhookToken`: Bearer-Token, das für die POST-Zustellung an Cron-Webhooks verwendet wird (`delivery.mode = "webhook"`); wenn weggelassen, wird kein Auth-Header gesendet. +- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Run-Sitzungen in `sessions.json` aufbewahrt werden, bevor sie entfernt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; setzen Sie `false`, um dies zu deaktivieren. +- `runLog.maxBytes`: maximale Größe pro Run-Log-Datei (`cron/runs/.jsonl`), bevor sie gekürzt wird. Standard: `2_000_000` Bytes. +- `runLog.keepLines`: neueste Zeilen, die beibehalten werden, wenn die Kürzung des Run-Logs ausgelöst wird. Standard: `2000`. +- `webhookToken`: Bearer-Token, das für die POST-Zustellung an Cron-Webhooks (`delivery.mode = "webhook"`) verwendet wird; wenn nicht gesetzt, wird kein Auth-Header gesendet. - `webhook`: veraltete Legacy-Fallback-Webhook-URL (http/https), die nur für gespeicherte Jobs verwendet wird, die noch `notify: true` haben. ### `cron.retry` @@ -3604,11 +3592,11 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über } ``` -- `maxAttempts`: maximale Anzahl an Wiederholungen für One-Shot-Jobs bei vorübergehenden Fehlern (Standard: `3`; Bereich: `0`–`10`). -- `backoffMs`: Array mit Backoff-Verzögerungen in ms für jeden Wiederholungsversuch (Standard: `[30000, 60000, 300000]`; 1–10 Einträge). -- `retryOn`: Fehlertypen, die Wiederholungen auslösen — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Weglassen, um alle vorübergehenden Typen zu wiederholen. +- `maxAttempts`: maximale Anzahl von Wiederholungen für einmalige Jobs bei transienten Fehlern (Standard: `3`; Bereich: `0`–`10`). +- `backoffMs`: Array von Backoff-Verzögerungen in ms für jeden Wiederholungsversuch (Standard: `[30000, 60000, 300000]`; 1–10 Einträge). +- `retryOn`: Fehlertypen, die Wiederholungen auslösen — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Weglassen, um alle transienten Typen zu wiederholen. -Gilt nur für One-Shot-Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fehlerbehandlung. +Gilt nur für einmalige Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fehlerbehandlung. ### `cron.failureAlert` @@ -3627,10 +3615,10 @@ Gilt nur für One-Shot-Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fe ``` - `enabled`: Fehlerwarnungen für Cron-Jobs aktivieren (Standard: `false`). -- `after`: aufeinanderfolgende Fehler, bevor eine Warnung ausgelöst wird (positive Ganzzahl, min: `1`). +- `after`: aufeinanderfolgende Fehler, bevor eine Warnung ausgelöst wird (positive Ganzzahl, Minimum: `1`). - `cooldownMs`: minimale Millisekunden zwischen wiederholten Warnungen für denselben Job (nicht negative Ganzzahl). -- `mode`: Zustellmodus — `"announce"` sendet über eine Kanalnachricht; `"webhook"` sendet an den konfigurierten Webhook. -- `accountId`: optionale Konto- oder Kanal-ID zur Eingrenzung der Warnungszustellung. +- `mode`: Zustellmodus — `"announce"` sendet über eine Kanalnachricht; `"webhook"` sendet einen POST an den konfigurierten Webhook. +- `accountId`: optionale Konto- oder Kanal-ID zur Eingrenzung der Warnzustellung. ### `cron.failureDestination` @@ -3647,51 +3635,51 @@ Gilt nur für One-Shot-Cron-Jobs. Wiederkehrende Jobs verwenden eine separate Fe } ``` -- Standardziel für Cron-Fehlerbenachrichtigungen für alle Jobs. +- Standardziel für Cron-Fehlerbenachrichtigungen über alle Jobs hinweg. - `mode`: `"announce"` oder `"webhook"`; standardmäßig `"announce"`, wenn genügend Zieldaten vorhanden sind. -- `channel`: Kanalüberschreibung für die Zustellung per announce. `"last"` verwendet den zuletzt bekannten Zustellkanal erneut. -- `to`: explizites announce-Ziel oder Webhook-URL. Für den Webhook-Modus erforderlich. +- `channel`: Kanalüberschreibung für die Zustellung per `announce`. `"last"` verwendet den zuletzt bekannten Zustellkanal erneut. +- `to`: explizites `announce`-Ziel oder Webhook-URL. Für den Webhook-Modus erforderlich. - `accountId`: optionale Kontoüberschreibung für die Zustellung. -- `delivery.failureDestination` pro Job überschreibt diesen globalen Standard. -- Wenn weder global noch pro Job ein Fehlerziel gesetzt ist, greifen Jobs, die bereits über `announce` zustellen, bei Fehlern auf dieses primäre announce-Ziel zurück. +- Pro Job überschreibt `delivery.failureDestination` diesen globalen Standard. +- Wenn weder global noch pro Job ein Fehlerziel gesetzt ist, greifen Jobs, die bereits per `announce` zustellen, im Fehlerfall auf dieses primäre `announce`-Ziel zurück. - `delivery.failureDestination` wird nur für Jobs mit `sessionTarget="isolated"` unterstützt, es sei denn, der primäre `delivery.mode` des Jobs ist `"webhook"`. -Siehe [Cron-Jobs](/de/automation/cron-jobs). Isolierte Cron-Ausführungen werden als [Hintergrundaufgaben](/de/automation/tasks) verfolgt. +Siehe [Cron Jobs](/de/automation/cron-jobs). Isolierte Cron-Ausführungen werden als [Hintergrundaufgaben](/de/automation/tasks) verfolgt. --- -## Template-Variablen für Medienmodelle +## Variablenvorlagen für Medienmodelle -Template-Platzhalter, die in `tools.media.models[].args` erweitert werden: +Vorlagen-Platzhalter, die in `tools.media.models[].args` erweitert werden: -| Variable | Beschreibung | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Vollständiger eingehender Nachrichtentext | -| `{{RawBody}}` | Roher Textkörper (ohne Verlaufs-/Absender-Wrapper) | -| `{{BodyStripped}}` | Textkörper mit entfernten Gruppenerwähnungen | -| `{{From}}` | Absenderkennung | -| `{{To}}` | Zielkennung | -| `{{MessageSid}}` | Kanal-Nachrichten-ID | -| `{{SessionId}}` | Aktuelle Sitzungs-UUID | -| `{{IsNewSession}}` | `"true"`, wenn eine neue Sitzung erstellt wurde | -| `{{MediaUrl}}` | Pseudo-URL eingehender Medien | -| `{{MediaPath}}` | Lokaler Medienpfad | -| `{{MediaType}}` | Medientyp (image/audio/document/…) | -| `{{Transcript}}` | Audio-Transkript | -| `{{Prompt}}` | Aufgelöster Medien-Prompt für CLI-Einträge | +| Variable | Beschreibung | +| ------------------ | ------------------------------------------------ | +| `{{Body}}` | Vollständiger eingehender Nachrichtentext | +| `{{RawBody}}` | Roher Nachrichtentext (ohne Verlauf-/Absender-Wrapper) | +| `{{BodyStripped}}` | Nachrichtentext mit entfernten Gruppenerwähnungen | +| `{{From}}` | Absenderkennung | +| `{{To}}` | Zielkennung | +| `{{MessageSid}}` | Kanal-Nachrichten-ID | +| `{{SessionId}}` | UUID der aktuellen Sitzung | +| `{{IsNewSession}}` | `"true"`, wenn eine neue Sitzung erstellt wurde | +| `{{MediaUrl}}` | Pseudo-URL eingehender Medien | +| `{{MediaPath}}` | Lokaler Medienpfad | +| `{{MediaType}}` | Medientyp (image/audio/document/…) | +| `{{Transcript}}` | Audio-Transkript | +| `{{Prompt}}` | Aufgelöster Medien-Prompt für CLI-Einträge | | `{{MaxChars}}` | Aufgelöste maximale Ausgabezeichen für CLI-Einträge | -| `{{ChatType}}` | `"direct"` oder `"group"` | -| `{{GroupSubject}}` | Gruppenthema (best effort) | -| `{{GroupMembers}}` | Vorschau der Gruppenmitglieder (best effort) | -| `{{SenderName}}` | Angezeigter Absendername (best effort) | -| `{{SenderE164}}` | Telefonnummer des Absenders (best effort) | +| `{{ChatType}}` | `"direct"` oder `"group"` | +| `{{GroupSubject}}` | Gruppenbetreff (best effort) | +| `{{GroupMembers}}` | Vorschau der Gruppenmitglieder (best effort) | +| `{{SenderName}}` | Anzeigename des Absenders (best effort) | +| `{{SenderE164}}` | Telefonnummer des Absenders (best effort) | | `{{Provider}}` | Provider-Hinweis (whatsapp, telegram, discord usw.) | --- ## Konfigurations-Includes (`$include`) -Konfiguration in mehrere Dateien aufteilen: +Teilen Sie die Konfiguration in mehrere Dateien auf: ```json5 // ~/.openclaw/openclaw.json @@ -3707,12 +3695,12 @@ Konfiguration in mehrere Dateien aufteilen: **Merge-Verhalten:** - Einzelne Datei: ersetzt das enthaltende Objekt. -- Array von Dateien: wird der Reihe nach tief zusammengeführt (spätere überschreiben frühere). -- Gleichgeordnete Schlüssel: werden nach den Includes zusammengeführt (überschreiben enthaltene Werte). +- Array von Dateien: wird in Reihenfolge per Deep Merge zusammengeführt (spätere überschreiben frühere). +- Geschwisterschlüssel: werden nach den Includes zusammengeführt (überschreiben eingeschlossene Werte). - Verschachtelte Includes: bis zu 10 Ebenen tief. -- Pfade: werden relativ zur einbindenden Datei aufgelöst, müssen aber innerhalb des Konfigurationsverzeichnisses der obersten Ebene bleiben (`dirname` von `openclaw.json`). Absolute Formen und `../` sind nur erlaubt, wenn sie sich weiterhin innerhalb dieser Grenze auflösen. +- Pfade: werden relativ zur einschließenden Datei aufgelöst, müssen aber innerhalb des Top-Level-Konfigurationsverzeichnisses (`dirname` von `openclaw.json`) bleiben. Absolute/`../`-Formen sind nur erlaubt, wenn sie sich trotzdem innerhalb dieser Grenze auflösen. - Fehler: klare Meldungen für fehlende Dateien, Parse-Fehler und zirkuläre Includes. --- -_Zugehörig: [Konfiguration](/de/gateway/configuration) · [Konfigurationsbeispiele](/de/gateway/configuration-examples) · [Doctor](/de/gateway/doctor)_ +_Verwandt: [Konfiguration](/de/gateway/configuration) · [Konfigurationsbeispiele](/de/gateway/configuration-examples) · [Doctor](/de/gateway/doctor)_ diff --git a/docs/de/help/gpt54-codex-agentic-parity-maintainers.md b/docs/de/help/gpt54-codex-agentic-parity-maintainers.md new file mode 100644 index 000000000..6d5a70516 --- /dev/null +++ b/docs/de/help/gpt54-codex-agentic-parity-maintainers.md @@ -0,0 +1,174 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:49Z" + model: gpt-5.4 + provider: openai + source_hash: 910bcf7668becf182ef48185b43728bf2fa69629d6d50189d47d47b06f807a9e + source_path: help/gpt54-codex-agentic-parity-maintainers.md + workflow: 15 +--- + +# Hinweise für Maintainer zur GPT-5.4 / Codex-Parität + +Diese Notiz erklärt, wie das GPT-5.4 / Codex-Paritätsprogramm als vier Merge-Einheiten geprüft werden kann, ohne die ursprüngliche Architektur mit sechs Verträgen zu verlieren. + +## Merge-Einheiten + +### PR A: strikt-agentische Ausführung + +Verantwortet: + +- `executionContract` +- GPT-5-first Follow-through im selben Turn +- `update_plan` als nicht-terminales Fortschrittstracking +- explizite Blockiert-Zustände statt stiller Stopps nur mit Plan + +Verantwortet nicht: + +- Klassifizierung von Auth-/Runtime-Fehlern +- Wahrhaftigkeit bei Berechtigungen +- Neugestaltung von Replay/Fortsetzung +- Paritäts-Benchmarking + +### PR B: Wahrhaftigkeit der Runtime + +Verantwortet: + +- Korrektheit der Codex OAuth-Scopes +- typisierte Klassifizierung von Provider-/Runtime-Fehlern +- wahrheitsgemäße Verfügbarkeit von `/elevated full` und Blockiert-Gründe + +Verantwortet nicht: + +- Normalisierung von Tool-Schemas +- Replay-/Liveness-Zustand +- Benchmark-Gating + +### PR C: Korrektheit der Ausführung + +Verantwortet: + +- providerseitige OpenAI-/Codex-Tool-Kompatibilität +- parameterfreie strikte Schema-Behandlung +- Sichtbarmachung von Replay-Invalid +- Sichtbarkeit von pausierten, blockierten und aufgegebenen Langzeit-Task-Zuständen + +Verantwortet nicht: + +- selbstgewählte Fortsetzung +- generisches Codex-Dialektverhalten außerhalb von Provider-Hooks +- Benchmark-Gating + +### PR D: Paritäts-Harness + +Verantwortet: + +- erste Welle des GPT-5.4-vs-Opus-4.6-Szenariopakets +- Paritätsdokumentation +- Paritätsbericht und Release-Gate-Mechanik + +Verantwortet nicht: + +- Änderungen des Runtime-Verhaltens außerhalb von QA-lab +- Auth-/Proxy-/DNS-Simulation innerhalb des Harness + +## Rückabbildung auf die ursprünglichen sechs Verträge + +| Ursprünglicher Vertrag | Merge-Einheit | +| ---------------------------------------- | ------------- | +| Korrektheit von Provider-Transport/Auth | PR B | +| Kompatibilität von Tool-Vertrag/Schema | PR C | +| Ausführung im selben Turn | PR A | +| Wahrhaftigkeit bei Berechtigungen | PR B | +| Korrektheit von Replay/Fortsetzung/Liveness | PR C | +| Benchmark-/Release-Gate | PR D | + +## Prüf-Reihenfolge + +1. PR A +2. PR B +3. PR C +4. PR D + +PR D ist die Nachweis-Schicht. Sie sollte nicht der Grund sein, warum PRs zur Runtime-Korrektheit verzögert werden. + +## Worauf zu achten ist + +### PR A + +- GPT-5-Läufe handeln oder scheitern geschlossen, statt bei Kommentaren zu stoppen +- `update_plan` sieht für sich allein nicht mehr wie Fortschritt aus +- das Verhalten bleibt GPT-5-first und auf Embedded-Pi beschränkt + +### PR B + +- Auth-/Proxy-/Runtime-Fehler werden nicht mehr in generische „Modell fehlgeschlagen“-Behandlung zusammengefasst +- `/elevated full` wird nur dann als verfügbar beschrieben, wenn es tatsächlich verfügbar ist +- Blockiert-Gründe sind sowohl für das Modell als auch für die benutzerseitige Runtime sichtbar + +### PR C + +- strikte OpenAI-/Codex-Tool-Registrierung verhält sich vorhersehbar +- parameterfreie Tools scheitern nicht an strikten Schema-Prüfungen +- Replay- und Compaction-Ergebnisse bewahren einen wahrheitsgemäßen Liveness-Zustand + +### PR D + +- das Szenariopaket ist verständlich und reproduzierbar +- das Paket enthält eine mutierende Replay-Sicherheits-Lane, nicht nur schreibgeschützte Abläufe +- Berichte sind für Menschen und Automatisierung lesbar +- Paritätsaussagen sind durch Belege gestützt, nicht anekdotisch + +Erwartete Artefakte aus PR D: + +- `qa-suite-report.md` / `qa-suite-summary.json` für jeden Modelllauf +- `qa-agentic-parity-report.md` mit Aggregat- und szenariobezogenem Vergleich +- `qa-agentic-parity-summary.json` mit einem maschinenlesbaren Urteil + +## Release-Gate + +Keine Parität oder Überlegenheit von GPT-5.4 gegenüber Opus 4.6 behaupten, bis: + +- PR A, PR B und PR C gemergt sind +- PR D das Paritäts-Paket der ersten Welle fehlerfrei ausführt +- Regressions-Suites zur Runtime-Wahrhaftigkeit grün bleiben +- der Paritätsbericht keine Fake-Success-Fälle und keine Regression im Stopp-Verhalten zeigt + +```mermaid +flowchart LR + A["PR A-C gemergt"] --> B["GPT-5.4-Paritäts-Paket ausführen"] + A --> C["Opus-4.6-Paritäts-Paket ausführen"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["qa parity-report"] + E --> F + F --> G["Markdown-Bericht + JSON-Urteil"] + G --> H{"Bestanden?"} + H -- "ja" --> I["Paritätsaussage erlaubt"] + H -- "nein" --> J["Runtime-Fixes / Prüf-Schleife offen halten"] +``` + +Das Paritäts-Harness ist nicht die einzige Belegquelle. Diese Aufteilung in der Prüfung klar beibehalten: + +- PR D verantwortet den szenariobasierten Vergleich GPT-5.4 vs Opus 4.6 +- deterministische Suites aus PR B verantworten weiterhin den Nachweis für Auth/Proxy/DNS und Wahrhaftigkeit bei vollem Zugriff + +## Zuordnung Ziel zu Nachweis + +| Element des Completion-Gates | Hauptverantwortlicher | Prüfartefakt | +| ---------------------------------------- | --------------------- | ------------------------------------------------------------------- | +| Keine Stopps nur mit Plan | PR A | strict-agentic-Runtime-Tests und `approval-turn-tool-followthrough` | +| Kein Fake-Fortschritt oder Fake-Tool-Abschluss | PR A + PR D | Anzahl der Fake-Success-Fälle bei Parität plus szenariobezogene Berichtsdetails | +| Keine falsche `/elevated full`-Anleitung | PR B | deterministische Runtime-Wahrhaftigkeits-Suites | +| Replay-/Liveness-Fehler bleiben explizit | PR C + PR D | Lifecycle-/Replay-Suites plus `compaction-retry-mutating-tool` | +| GPT-5.4 entspricht Opus 4.6 oder übertrifft es | PR D | `qa-agentic-parity-report.md` und `qa-agentic-parity-summary.json` | + +## Prüfer-Kurzform: vorher vs nachher + +| Zuvor benutzersichtbares Problem | Prüfsignal nachher | +| ----------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| GPT-5.4 stoppte nach der Planung | PR A zeigt Handeln-oder-Blockieren-Verhalten statt Abschluss nur mit Kommentar | +| Tool-Nutzung wirkte mit strikten OpenAI-/Codex-Schemas fragil | PR C hält Tool-Registrierung und parameterfreie Aufrufe vorhersehbar | +| Hinweise zu `/elevated full` waren manchmal irreführend | PR B bindet Hinweise an die tatsächliche Runtime-Fähigkeit und Blockiert-Gründe | +| Langzeit-Tasks konnten in Replay-/Compaction-Mehrdeutigkeit verschwinden | PR C gibt explizite Zustände für pausiert, blockiert, aufgegeben und replay-invalid aus | +| Paritätsaussagen waren anekdotisch | PR D erstellt einen Bericht plus JSON-Urteil mit derselben Szenarioabdeckung für beide Modelle | diff --git a/docs/de/help/gpt54-codex-agentic-parity.md b/docs/de/help/gpt54-codex-agentic-parity.md new file mode 100644 index 000000000..70404693d --- /dev/null +++ b/docs/de/help/gpt54-codex-agentic-parity.md @@ -0,0 +1,229 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:49Z" + model: gpt-5.4 + provider: openai + source_hash: 7ee6b925b8a0f8843693cea9d50b40544657b5fb8a9e0860e2ff5badb273acb6 + source_path: help/gpt54-codex-agentic-parity.md + workflow: 15 +--- + +# GPT-5.4 / Codex Agentic-Parität in OpenClaw + +OpenClaw funktionierte bereits gut mit Frontier-Modellen, die Tools verwenden, aber GPT-5.4- und Codex-ähnliche Modelle blieben in einigen praktischen Punkten noch hinter den Erwartungen zurück: + +- sie konnten nach der Planung aufhören, statt die Arbeit auszuführen +- sie konnten strikte OpenAI/Codex-Tool-Schemata falsch verwenden +- sie konnten nach `/elevated full` fragen, selbst wenn voller Zugriff unmöglich war +- sie konnten bei Replay oder Kompaktierung den Status langlaufender Aufgaben verlieren +- Paritätsaussagen gegenüber Claude Opus 4.6 basierten auf Anekdoten statt auf wiederholbaren Szenarien + +Dieses Paritätsprogramm schließt diese Lücken in vier überprüfbaren Teilbereichen. + +## Was sich geändert hat + +### PR A: strikte agentische Ausführung + +Dieser Teilbereich ergänzt einen optionalen `strict-agentic`-Ausführungsvertrag für eingebettete Pi-GPT-5-Läufe. + +Wenn aktiviert, akzeptiert OpenClaw rein planbasierte Züge nicht mehr als „ausreichend gute“ Fertigstellung. Wenn das Modell nur sagt, was es tun will, und weder tatsächlich Tools verwendet noch Fortschritt macht, versucht OpenClaw es erneut mit einer „jetzt handeln“-Steuerung und schlägt dann explizit mit einem blockierten Status fehl, statt die Aufgabe stillschweigend zu beenden. + +Das verbessert die GPT-5.4-Erfahrung besonders bei: + +- kurzen „ok mach es“-Nachfassaktionen +- Code-Aufgaben, bei denen der erste Schritt offensichtlich ist +- Abläufen, bei denen `update_plan` Fortschrittsverfolgung statt Fülltext sein sollte + +### PR B: Laufzeitwahrhaftigkeit + +Dieser Teilbereich sorgt dafür, dass OpenClaw in zwei Punkten die Wahrheit sagt: + +- warum der Provider-/Laufzeitaufruf fehlgeschlagen ist +- ob `/elevated full` tatsächlich verfügbar ist + +Das bedeutet, dass GPT-5.4 bessere Laufzeitsignale für fehlenden Scope, fehlgeschlagene Auth-Aktualisierungen, HTML-403-Auth-Fehler, Proxy-Probleme, DNS- oder Timeout-Fehler und blockierte Vollzugriffsmodi erhält. Das Modell halluziniert dadurch seltener die falsche Abhilfemaßnahme oder fordert weiter einen Berechtigungsmodus an, den die Laufzeit nicht bereitstellen kann. + +### PR C: Ausführungskorrektheit + +Dieser Teilbereich verbessert zwei Arten von Korrektheit: + +- provider-eigene OpenAI/Codex-Tool-Schema-Kompatibilität +- Sichtbarmachung von Replay und Langzeitaufgaben-Lebendigkeit + +Die Tool-Kompatibilitätsarbeit reduziert Schema-Reibung bei strikter OpenAI/Codex-Tool-Registrierung, insbesondere bei parameterlosen Tools und strikten Erwartungen an ein Object-Root. Die Replay-/Lebendigkeitsarbeit macht langlaufende Aufgaben besser beobachtbar, sodass pausierte, blockierte und aufgegebene Zustände sichtbar sind, statt in generischem Fehlertext zu verschwinden. + +### PR D: Paritätsharness + +Dieser Teilbereich fügt das erste QA-lab-Paritätspaket hinzu, damit GPT-5.4 und Opus 4.6 durch dieselben Szenarien geführt und anhand gemeinsamer Belege verglichen werden können. + +Das Paritätspaket ist die Nachweisebene. Es verändert das Laufzeitverhalten selbst nicht. + +Sobald zwei `qa-suite-summary.json`-Artefakte vorliegen, erzeugen Sie den Vergleich für das Release-Gate mit: + +```bash +pnpm openclaw qa parity-report \ + --repo-root . \ + --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \ + --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \ + --output-dir .artifacts/qa-e2e/parity +``` + +Dieser Befehl schreibt: + +- einen menschenlesbaren Markdown-Bericht +- ein maschinenlesbares JSON-Urteil +- ein explizites `pass`- / `fail`-Gate-Ergebnis + +## Warum das GPT-5.4 in der Praxis verbessert + +Vor dieser Arbeit konnte sich GPT-5.4 auf OpenClaw in realen Coding-Sitzungen weniger agentisch anfühlen als Opus, weil die Laufzeit Verhaltensweisen tolerierte, die für Modelle im GPT-5-Stil besonders schädlich sind: + +- rein kommentierende Züge +- Schema-Reibung bei Tools +- vages Berechtigungsfeedback +- stilles Versagen bei Replay oder Kompaktierung + +Das Ziel ist nicht, GPT-5.4 dazu zu bringen, Opus zu imitieren. Das Ziel ist, GPT-5.4 einen Laufzeitvertrag zu geben, der echten Fortschritt belohnt, klarere Tool- und Berechtigungssemantik liefert und Fehlermodi in explizite, maschinen- und menschenlesbare Zustände verwandelt. + +Dadurch ändert sich die Benutzererfahrung von: + +- „das Modell hatte einen guten Plan, hat aber aufgehört“ + +zu: + +- „das Modell hat entweder gehandelt, oder OpenClaw hat den genauen Grund angezeigt, warum es nicht konnte“ + +## Vorher vs. nachher für GPT-5.4-Nutzer + +| Vor diesem Programm | Nach PR A-D | +| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| GPT-5.4 konnte nach einem vernünftigen Plan aufhören, ohne den nächsten Tool-Schritt zu tun | PR A macht aus „nur planen“ „jetzt handeln oder einen blockierten Status anzeigen“ | +| Strikte Tool-Schemata konnten parameterlose oder OpenAI/Codex-geformte Tools verwirrend ablehnen | PR C macht provider-eigene Tool-Registrierung und -Aufruf vorhersehbarer | +| Die Anleitung zu `/elevated full` konnte in blockierten Laufzeiten vage oder falsch sein | PR B gibt GPT-5.4 und dem Nutzer wahrheitsgemäße Laufzeit- und Berechtigungshinweise | +| Replay- oder Kompaktierungsfehler konnten wirken, als sei die Aufgabe still verschwunden | PR C zeigt pausierte, blockierte, aufgegebene und replay-ungültige Ergebnisse explizit | +| „GPT-5.4 fühlt sich schlechter an als Opus“ war meist anekdotisch | PR D macht daraus dasselbe Szenariopaket, dieselben Metriken und ein hartes Pass/Fail-Gate | + +## Architektur + +```mermaid +flowchart TD + A["User request"] --> B["Embedded Pi runtime"] + B --> C["Strict-agentic execution contract"] + B --> D["Provider-owned tool compatibility"] + B --> E["Runtime truthfulness"] + B --> F["Replay and liveness state"] + C --> G["Tool call or explicit blocked state"] + D --> G + E --> G + F --> G + G --> H["QA-lab parity pack"] + H --> I["Scenario report and parity gate"] +``` + +## Release-Ablauf + +```mermaid +flowchart LR + A["Merged runtime slices (PR A-C)"] --> B["Run GPT-5.4 parity pack"] + A --> C["Run Opus 4.6 parity pack"] + B --> D["qa-suite-summary.json"] + C --> E["qa-suite-summary.json"] + D --> F["openclaw qa parity-report"] + E --> F + F --> G["qa-agentic-parity-report.md"] + F --> H["qa-agentic-parity-summary.json"] + H --> I{"Gate pass?"} + I -- "yes" --> J["Evidence-backed parity claim"] + I -- "no" --> K["Keep runtime/review loop open"] +``` + +## Szenariopaket + +Das Paritätspaket der ersten Welle deckt derzeit fünf Szenarien ab: + +### `approval-turn-tool-followthrough` + +Prüft, dass das Modell nach einer kurzen Zustimmung nicht bei „Ich mache das“ stehen bleibt. Es sollte im selben Zug die erste konkrete Aktion ausführen. + +### `model-switch-tool-continuity` + +Prüft, dass Tool-gestützte Arbeit über Modell-/Laufzeitwechsel hinweg kohärent bleibt, statt in Kommentare zurückzufallen oder den Ausführungskontext zu verlieren. + +### `source-docs-discovery-report` + +Prüft, dass das Modell Quellcode und Dokumentation lesen, Ergebnisse synthetisieren und die Aufgabe agentisch fortsetzen kann, statt nur eine dünne Zusammenfassung zu liefern und früh zu stoppen. + +### `image-understanding-attachment` + +Prüft, dass gemischte Aufgaben mit Anhängen handlungsfähig bleiben und nicht in vage Beschreibung zusammenbrechen. + +### `compaction-retry-mutating-tool` + +Prüft, dass eine Aufgabe mit einer echten verändernden Schreiboperation Replay-Unsicherheit explizit hält, statt stillschweigend replay-sicher zu wirken, wenn der Lauf unter Druck kompaktiert, erneut versucht wird oder den Antwortstatus verliert. + +## Szenariomatrix + +| Szenario | Was es testet | Gutes GPT-5.4-Verhalten | Fehlersignal | +| ---------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| `approval-turn-tool-followthrough` | Kurze Zustimmungszüge nach einem Plan | Startet die erste konkrete Tool-Aktion sofort, statt nur die Absicht zu wiederholen | nur planbasierte Nachfolge, keine Tool-Aktivität oder blockierter Zug ohne echten Blocker | +| `model-switch-tool-continuity` | Laufzeit-/Modellwechsel unter Tool-Nutzung | Behält den Aufgabenkontext bei und handelt kohärent weiter | fällt in Kommentare zurück, verliert Tool-Kontext oder stoppt nach dem Wechsel | +| `source-docs-discovery-report` | Quellcode lesen + synthetisieren + handeln | Findet Quellen, verwendet Tools und erstellt einen nützlichen Bericht ohne Stocken | dünne Zusammenfassung, fehlende Tool-Arbeit oder unvollständiger Zug-Stopp | +| `image-understanding-attachment` | agentische Arbeit auf Basis von Anhängen | Interpretiert den Anhang, verbindet ihn mit Tools und setzt die Aufgabe fort | vage Beschreibung, Anhang ignoriert oder keine konkrete nächste Aktion | +| `compaction-retry-mutating-tool` | verändernde Arbeit unter Kompaktierungsdruck | Führt eine echte Schreiboperation aus und hält Replay-Unsicherheit nach dem Seiteneffekt explizit | verändernde Schreiboperation passiert, aber Replay-Sicherheit wird impliziert, fehlt oder ist widersprüchlich | + +## Release-Gate + +GPT-5.4 kann nur dann als auf Parität oder besser betrachtet werden, wenn die zusammengeführte Laufzeit gleichzeitig das Paritätspaket und die Regressionen zur Laufzeitwahrhaftigkeit besteht. + +Erforderliche Ergebnisse: + +- kein rein planbasierter Stillstand, wenn die nächste Tool-Aktion klar ist +- keine vorgetäuschte Fertigstellung ohne echte Ausführung +- keine falsche `/elevated full`-Anleitung +- kein stilles Aufgeben bei Replay oder Kompaktierung +- Paritätspaket-Metriken, die mindestens so stark sind wie die vereinbarte Opus-4.6-Baseline + +Für das Harness der ersten Welle vergleicht das Gate: + +- Abschlussrate +- Rate unbeabsichtigter Stopps +- Rate gültiger Tool-Aufrufe +- Anzahl vorgetäuschter Erfolge + +Die Paritätsbelege sind absichtlich auf zwei Ebenen aufgeteilt: + +- PR D belegt mit QA-lab dasselbe Szenarioverhalten von GPT-5.4 vs. Opus 4.6 +- deterministische Suiten aus PR B belegen Auth-, Proxy-, DNS- und `/elevated full`-Wahrhaftigkeit außerhalb des Harness + +## Ziel-zu-Beleg-Matrix + +| Element des Abschluss-Gates | Zuständige PR | Belegquelle | Pass-Signal | +| --------------------------------------------------------- | ------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| GPT-5.4 bleibt nach der Planung nicht länger stehen | PR A | `approval-turn-tool-followthrough` plus PR-A-Laufzeitsuiten | Zustimmungszüge lösen echte Arbeit oder einen explizit blockierten Status aus | +| GPT-5.4 täuscht keinen Fortschritt und keine Tool-Fertigstellung mehr vor | PR A + PR D | Szenarioergebnisse des Paritätsberichts und Anzahl vorgetäuschter Erfolge | keine verdächtigen Pass-Ergebnisse und keine rein kommentierende Fertigstellung | +| GPT-5.4 gibt keine falsche `/elevated full`-Anleitung mehr | PR B | deterministische Wahrhaftigkeitssuiten | blockierte Gründe und Vollzugriffshinweise bleiben laufzeitgenau | +| Replay-/Lebendigkeitsfehler bleiben explizit | PR C + PR D | PR-C-Lebenszyklus-/Replay-Suiten plus `compaction-retry-mutating-tool` | verändernde Arbeit hält Replay-Unsicherheit explizit, statt stillschweigend zu verschwinden | +| GPT-5.4 erreicht oder übertrifft Opus 4.6 bei den vereinbarten Metriken | PR D | `qa-agentic-parity-report.md` und `qa-agentic-parity-summary.json` | dieselbe Szenarioabdeckung und keine Regression bei Abschluss, Stoppverhalten oder gültiger Tool-Nutzung | + +## So lesen Sie das Paritätsurteil + +Verwenden Sie das Urteil in `qa-agentic-parity-summary.json` als endgültige maschinenlesbare Entscheidung für das Paritätspaket der ersten Welle. + +- `pass` bedeutet, dass GPT-5.4 dieselben Szenarien wie Opus 4.6 abgedeckt hat und bei den vereinbarten aggregierten Metriken keine Regression gezeigt hat. +- `fail` bedeutet, dass mindestens ein hartes Gate ausgelöst wurde: schwächerer Abschluss, schlechtere unbeabsichtigte Stopps, schwächere gültige Tool-Nutzung, ein beliebiger Fall von vorgetäuschtem Erfolg oder nicht übereinstimmende Szenarioabdeckung. +- „shared/base CI issue“ ist für sich genommen kein Paritätsergebnis. Wenn CI-Rauschen außerhalb von PR D einen Lauf blockiert, sollte das Urteil auf eine saubere Ausführung der zusammengeführten Laufzeit warten, statt aus Logs aus der Branch-Ära abgeleitet zu werden. +- Auth-, Proxy-, DNS- und `/elevated full`-Wahrhaftigkeit kommen weiterhin aus den deterministischen Suiten von PR B, daher benötigt die endgültige Release-Aussage beides: ein bestehendes PR-D-Paritätsurteil und grüne PR-B-Wahrhaftigkeitsabdeckung. + +## Wer `strict-agentic` aktivieren sollte + +Verwenden Sie `strict-agentic`, wenn: + +- vom Agenten erwartet wird, dass er sofort handelt, wenn ein nächster Schritt offensichtlich ist +- Modelle der GPT-5.4- oder Codex-Familie die primäre Laufzeit sind +- Sie explizite blockierte Zustände gegenüber „hilfreichen“ Antworten bevorzugen, die nur zusammenfassen + +Behalten Sie den Standardvertrag bei, wenn: + +- Sie das bisherige lockerere Verhalten möchten +- Sie keine Modelle der GPT-5-Familie verwenden +- Sie Prompts statt Laufzeitdurchsetzung testen diff --git a/docs/de/plugins/architecture.md b/docs/de/plugins/architecture.md index 2015f38e3..6fe4b4b51 100644 --- a/docs/de/plugins/architecture.md +++ b/docs/de/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - Sie erstellen oder debuggen native OpenClaw-Plugins - - Sie möchten das Plugin-Fähigkeitsmodell oder Ownership-Grenzen verstehen - - Sie arbeiten an der Plugin-Ladepipeline oder Registry - - Sie implementieren Provider-Laufzeit-Hooks oder Kanal-Plugins + - Erstellen oder Debuggen nativer OpenClaw-Plugins + - Das Fähigkeitsmodell oder die Eigentumsgrenzen von Plugins verstehen + - An der Ladepipeline oder Registry von Plugins arbeiten + - Implementieren von Provider-Laufzeit-Hooks oder Kanal-Plugins sidebarTitle: Internals -summary: 'Plugin-Interna: Fähigkeitsmodell, Ownership, Verträge, Ladepipeline und Laufzeit-Helfer' +summary: 'Plugin-Interna: Fähigkeitsmodell, Eigentümerschaft, Verträge, Ladepipeline und Laufzeit-Hilfsfunktionen' title: Plugin-Interna x-i18n: - generated_at: "2026-04-09T01:31:44Z" + generated_at: "2026-04-11T15:15:58Z" model: gpt-5.4 provider: openai - source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 + source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 source_path: plugins/architecture.md workflow: 15 --- @@ -19,11 +19,11 @@ x-i18n: # Plugin-Interna - Dies ist die **Referenz für die tiefgehende Architektur**. Praktische Anleitungen finden Sie hier: - - [Plugins installieren und verwenden](/de/tools/plugin) — Benutzerleitfaden + Dies ist die **umfassende Architekturreferenz**. Praktische Anleitungen finden Sie unter: + - [Plugins installieren und verwenden](/de/tools/plugin) — Benutzerhandbuch - [Erste Schritte](/de/plugins/building-plugins) — erstes Plugin-Tutorial - [Kanal-Plugins](/de/plugins/sdk-channel-plugins) — einen Messaging-Kanal erstellen - - [Provider-Plugins](/de/plugins/sdk-provider-plugins) — einen Modellanbieter erstellen + - [Provider-Plugins](/de/plugins/sdk-provider-plugins) — einen Modell-Provider erstellen - [SDK-Überblick](/de/plugins/sdk-overview) — Importzuordnung und Registrierungs-API @@ -31,50 +31,51 @@ Diese Seite behandelt die interne Architektur des OpenClaw-Plugin-Systems. ## Öffentliches Fähigkeitsmodell -Fähigkeiten sind das öffentliche Modell für **native Plugins** innerhalb von OpenClaw. Jedes +Fähigkeiten sind das öffentliche Modell für **native Plugins** in OpenClaw. Jedes native OpenClaw-Plugin registriert sich für einen oder mehrere Fähigkeitstypen: -| Fähigkeit | Registrierungsmethode | Beispiel-Plugins | -| ---------------------- | ------------------------------------------------ | ------------------------------------ | -| Textinferenz | `api.registerProvider(...)` | `openai`, `anthropic` | -| CLI-Inferenz-Backend | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Sprache | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Echtzeit-Transkription | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Echtzeit-Sprache | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Medienverständnis | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Bildgenerierung | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Musikgenerierung | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Videogenerierung | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Web-Abruf | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Websuche | `api.registerWebSearchProvider(...)` | `google` | -| Kanal / Messaging | `api.registerChannel(...)` | `msteams`, `matrix` | +| Fähigkeit | Registrierungsmethode | Beispiel-Plugins | +| ---------------------- | ------------------------------------------------- | ------------------------------------ | +| Textinferenz | `api.registerProvider(...)` | `openai`, `anthropic` | +| CLI-Inferenz-Backend | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Sprache | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Echtzeit-Transkription | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Echtzeit-Stimme | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Medienverständnis | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Bildgenerierung | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Musikgenerierung | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Videogenerierung | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Web-Abruf | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Websuche | `api.registerWebSearchProvider(...)` | `google` | +| Kanal / Messaging | `api.registerChannel(...)` | `msteams`, `matrix` | Ein Plugin, das null Fähigkeiten registriert, aber Hooks, Tools oder -Services bereitstellt, ist ein **Legacy-Hook-only**-Plugin. Dieses Muster wird weiterhin vollständig unterstützt. +Dienste bereitstellt, ist ein **Legacy-Plugin nur mit Hooks**. Dieses Muster wird +weiterhin vollständig unterstützt. ### Haltung zur externen Kompatibilität -Das Fähigkeitsmodell ist im Kernsystem eingeführt und wird heute von gebündelten/nativen Plugins -verwendet, aber für die Kompatibilität externer Plugins braucht es weiterhin eine strengere Messlatte als „es ist +Das Fähigkeitsmodell ist im Kern angekommen und wird heute von gebündelten/nativen Plugins +verwendet, aber die Kompatibilität externer Plugins braucht weiterhin einen strengeren Maßstab als „es ist exportiert, also ist es eingefroren“. Aktuelle Richtlinien: -- **bestehende externe Plugins:** halten Sie hook-basierte Integrationen funktionsfähig; behandeln Sie - dies als Kompatibilitäts-Basislinie -- **neue gebündelte/native Plugins:** bevorzugen Sie explizite Fähigkeitsregistrierung statt - anbieterspezifischer Eingriffe oder neuer Hook-only-Designs -- **externe Plugins, die Fähigkeitsregistrierung übernehmen:** erlaubt, aber behandeln Sie - fähigkeitsspezifische Helferoberflächen als weiterentwickelbar, sofern die Dokumentation einen +- **bestehende externe Plugins:** hook-basierte Integrationen funktionsfähig halten; behandeln + Sie dies als Kompatibilitätsgrundlage +- **neue gebündelte/native Plugins:** explizite Fähigkeitsregistrierung gegenüber + anbieterspezifischen Zugriffen oder neuen Nur-Hook-Designs bevorzugen +- **externe Plugins, die Fähigkeitsregistrierung übernehmen:** erlaubt, aber die + fähigkeitsspezifischen Hilfsoberflächen als weiterentwickelnd behandeln, sofern die Dokumentation einen Vertrag nicht ausdrücklich als stabil kennzeichnet Praktische Regel: -- APIs zur Fähigkeitsregistrierung sind die vorgesehene Richtung -- Legacy-Hooks bleiben während des - Übergangs der sicherste Weg ohne Inkompatibilitäten für externe Plugins -- exportierte Helper-Subpaths sind nicht alle gleich; bevorzugen Sie den schmalen dokumentierten - Vertrag, nicht beiläufig exportierte Helfer +- APIs zur Fähigkeitsregistrierung sind die beabsichtigte Richtung +- Legacy-Hooks bleiben während des Übergangs der sicherste Weg ohne + Kompatibilitätsbrüche für externe Plugins +- exportierte Hilfs-Unterpfade sind nicht alle gleich; bevorzugen Sie den schmalen dokumentierten + Vertrag, nicht zufällig exportierte Hilfsfunktionen ### Plugin-Formen @@ -84,42 +85,42 @@ Registrierungsverhaltens in eine Form (nicht nur anhand statischer Metadaten): - **plain-capability** -- registriert genau einen Fähigkeitstyp (zum Beispiel ein reines Provider-Plugin wie `mistral`) - **hybrid-capability** -- registriert mehrere Fähigkeitstypen (zum Beispiel - `openai` besitzt Textinferenz, Sprache, Medienverständnis und Bild- - generierung) -- **hook-only** -- registriert nur Hooks (typisiert oder benutzerdefiniert), keine Fähigkeiten, - Tools, Befehle oder Services -- **non-capability** -- registriert Tools, Befehle, Services oder Routen, aber keine + besitzt `openai` Textinferenz, Sprache, Medienverständnis und + Bildgenerierung) +- **hook-only** -- registriert nur Hooks (typisiert oder benutzerdefiniert), keine + Fähigkeiten, Tools, Befehle oder Dienste +- **non-capability** -- registriert Tools, Befehle, Dienste oder Routen, aber keine Fähigkeiten -Verwenden Sie `openclaw plugins inspect `, um die Form und die Aufschlüsselung der -Fähigkeiten eines Plugins anzuzeigen. Details finden Sie in der [CLI-Referenz](/cli/plugins#inspect). +Verwenden Sie `openclaw plugins inspect `, um die Form und die Aufschlüsselung der Fähigkeiten +eines Plugins zu sehen. Details finden Sie in der [CLI-Referenz](/cli/plugins#inspect). ### Legacy-Hooks Der Hook `before_agent_start` bleibt als Kompatibilitätspfad für -Hook-only-Plugins unterstützt. Bestehende Plugins aus der Praxis hängen weiterhin davon ab. +Plugins nur mit Hooks unterstützt. Reale Legacy-Plugins sind weiterhin davon abhängig. Ausrichtung: - funktionsfähig halten -- als Legacy dokumentieren -- `before_model_resolve` für Arbeiten an Modell-/Provider-Überschreibungen bevorzugen -- `before_prompt_build` für Arbeiten an Prompt-Mutationen bevorzugen -- erst entfernen, wenn die reale Nutzung sinkt und die Abdeckung durch Fixtures eine sichere Migration belegt +- als veraltet dokumentieren +- `before_model_resolve` für Arbeiten zur Modell-/Provider-Überschreibung bevorzugen +- `before_prompt_build` für Arbeiten zur Prompt-Mutation bevorzugen +- erst entfernen, wenn die reale Nutzung sinkt und die Fixture-Abdeckung die Sicherheit der Migration belegt ### Kompatibilitätssignale Wenn Sie `openclaw doctor` oder `openclaw plugins inspect ` ausführen, sehen Sie möglicherweise eines dieser Labels: -| Signal | Bedeutung | -| -------------------------- | ---------------------------------------------------------- | -| **config valid** | Konfiguration wird korrekt geparst und Plugins werden aufgelöst | -| **compatibility advisory** | Plugin verwendet ein unterstütztes, aber älteres Muster (z. B. `hook-only`) | -| **legacy warning** | Plugin verwendet `before_agent_start`, das veraltet ist | -| **hard error** | Konfiguration ist ungültig oder Plugin konnte nicht geladen werden | +| Signal | Bedeutung | +| -------------------------- | ----------------------------------------------------------- | +| **config valid** | Die Konfiguration wird sauber geparst und Plugins werden aufgelöst | +| **compatibility advisory** | Das Plugin verwendet ein unterstütztes, aber älteres Muster (z. B. `hook-only`) | +| **legacy warning** | Das Plugin verwendet `before_agent_start`, was veraltet ist | +| **hard error** | Die Konfiguration ist ungültig oder das Plugin konnte nicht geladen werden | -Weder `hook-only` noch `before_agent_start` machen Ihr Plugin heute kaputt -- +Weder `hook-only` noch `before_agent_start` führen heute dazu, dass Ihr Plugin nicht mehr funktioniert -- `hook-only` ist ein Hinweis, und `before_agent_start` löst nur eine Warnung aus. Diese Signale erscheinen auch in `openclaw status --all` und `openclaw plugins doctor`. @@ -127,60 +128,60 @@ Signale erscheinen auch in `openclaw status --all` und `openclaw plugins doctor` Das Plugin-System von OpenClaw hat vier Ebenen: -1. **Manifest + Discovery** - OpenClaw findet potenzielle Plugins aus konfigurierten Pfaden, Workspace-Wurzeln, - globalen Extension-Wurzeln und gebündelten Extensions. Discovery liest zuerst native +1. **Manifest + Erkennung** + OpenClaw findet mögliche Plugins aus konfigurierten Pfaden, Workspace-Wurzeln, + globalen Erweiterungswurzeln und gebündelten Erweiterungen. Die Erkennung liest zuerst native `openclaw.plugin.json`-Manifeste sowie unterstützte Bundle-Manifeste. 2. **Aktivierung + Validierung** - Der Kern entscheidet, ob ein entdecktes Plugin aktiviert, deaktiviert, blockiert oder + Der Kern entscheidet, ob ein erkanntes Plugin aktiviert, deaktiviert, blockiert oder für einen exklusiven Slot wie Speicher ausgewählt wird. 3. **Laufzeitladen** - Native OpenClaw-Plugins werden über jiti im Prozess geladen und registrieren + Native OpenClaw-Plugins werden im Prozess per jiti geladen und registrieren Fähigkeiten in einer zentralen Registry. Kompatible Bundles werden in Registry-Einträge normalisiert, ohne Laufzeitcode zu importieren. -4. **Oberflächennutzung** +4. **Nutzung der Oberflächen** Der Rest von OpenClaw liest die Registry, um Tools, Kanäle, Provider- - Einrichtung, Hooks, HTTP-Routen, CLI-Befehle und Services bereitzustellen. + Einrichtung, Hooks, HTTP-Routen, CLI-Befehle und Dienste bereitzustellen. Speziell für die Plugin-CLI ist die Erkennung von Root-Befehlen in zwei Phasen aufgeteilt: - Parse-Zeit-Metadaten kommen aus `registerCli(..., { descriptors: [...] })` -- das eigentliche Plugin-CLI-Modul kann lazy bleiben und sich erst beim ersten Aufruf registrieren +- das eigentliche Plugin-CLI-Modul kann träge bleiben und sich beim ersten Aufruf registrieren -Dadurch bleibt die dem Plugin gehörende CLI im Plugin, während OpenClaw dennoch -Root-Befehlsnamen vor dem Parsen reservieren kann. +Dadurch bleibt Plugin-eigener CLI-Code innerhalb des Plugins, während OpenClaw +Root-Befehlsnamen weiterhin vor dem Parsen reservieren kann. Die wichtige Designgrenze: -- Discovery + Konfigurationsvalidierung sollten anhand von **Manifest-/Schema-Metadaten** +- Erkennung + Konfigurationsvalidierung sollten anhand von **Manifest-/Schema-Metadaten** funktionieren, ohne Plugin-Code auszuführen - natives Laufzeitverhalten kommt aus dem Pfad `register(api)` des Plugin-Moduls -Diese Trennung ermöglicht OpenClaw, Konfigurationen zu validieren, fehlende/deaktivierte Plugins -zu erklären und UI-/Schema-Hinweise zu erzeugen, bevor die vollständige Laufzeit aktiv ist. +Diese Trennung ermöglicht OpenClaw, Konfigurationen zu validieren, fehlende/deaktivierte Plugins zu erklären und +UI-/Schema-Hinweise aufzubauen, bevor die vollständige Laufzeit aktiv ist. -### Kanal-Plugins und das gemeinsame `message`-Tool +### Kanal-Plugins und das gemeinsame Nachrichtentool -Kanal-Plugins müssen für normale Chat-Aktionen kein separates Tool zum Senden/Bearbeiten/Reagieren registrieren. +Kanal-Plugins müssen für normale Chat-Aktionen kein separates Senden-/Bearbeiten-/Reagieren-Tool registrieren. OpenClaw behält ein gemeinsames `message`-Tool im Kern, und -Kanal-Plugins besitzen die kanalspezifische Discovery und Ausführung dahinter. +Kanal-Plugins besitzen die kanalspezifische Erkennung und Ausführung dahinter. Die aktuelle Grenze ist: - der Kern besitzt den gemeinsamen `message`-Tool-Host, Prompt-Verdrahtung, Sitzungs-/Thread- - Buchführung und Ausführungs-Dispatch -- Kanal-Plugins besitzen Scoped-Action-Discovery, Fähigkeits-Discovery und beliebige - kanalspezifische Schemafragmente -- Kanal-Plugins besitzen anbieterspezifische Sitzungs-/Unterhaltungsgrammatik, etwa - wie Unterhaltungs-IDs Thread-IDs kodieren oder von Elternunterhaltungen erben -- Kanal-Plugins führen die endgültige Aktion über ihren Action-Adapter aus + Buchführung und den Ausführungs-Dispatch +- Kanal-Plugins besitzen die erkennungsbezogene Bereichslogik für Aktionen, die Fähigkeitserkennung + und alle kanalspezifischen Schemafragmente +- Kanal-Plugins besitzen die providerspezifische Sitzungs-Konversationsgrammatik, etwa + wie Konversations-IDs Thread-IDs kodieren oder von Elternkonversationen erben +- Kanal-Plugins führen die endgültige Aktion über ihren Aktionsadapter aus Für Kanal-Plugins ist die SDK-Oberfläche -`ChannelMessageActionAdapter.describeMessageTool(...)`. Dieser einheitliche Discovery- -Aufruf erlaubt es einem Plugin, seine sichtbaren Aktionen, Fähigkeiten und Schema- -Beiträge zusammen zurückzugeben, damit diese Teile nicht auseinanderdriften. +`ChannelMessageActionAdapter.describeMessageTool(...)`. Dieser vereinheitlichte Erkennungsaufruf +ermöglicht es einem Plugin, seine sichtbaren Aktionen, Fähigkeiten und Schemaparameter +gemeinsam zurückzugeben, damit diese Teile nicht auseinanderlaufen. -Der Kern übergibt den Laufzeitkontext in diesen Discovery-Schritt. Wichtige Felder sind: +Der Kern übergibt den Laufzeitbereich an diesen Erkennungsschritt. Wichtige Felder sind: - `accountId` - `currentChannelId` @@ -192,123 +193,126 @@ Der Kern übergibt den Laufzeitkontext in diesen Discovery-Schritt. Wichtige Fel - vertrauenswürdige eingehende `requesterSenderId` Das ist für kontextsensitive Plugins wichtig. Ein Kanal kann -Nachrichtenaktionen abhängig vom aktiven Konto, dem aktuellen Raum/Thread/der aktuellen Nachricht oder -der vertrauenswürdigen Anforderer-Identität ein- oder ausblenden, ohne +Nachrichtenaktionen basierend auf dem aktiven Konto, dem aktuellen Raum/Thread/Nachricht oder der +vertrauenswürdigen Identität des Anfragenden ausblenden oder einblenden, ohne kanalspezifische Verzweigungen im Kern-`message`-Tool fest zu verdrahten. Deshalb sind Änderungen am Embedded-Runner-Routing weiterhin Plugin-Arbeit: Der Runner ist dafür verantwortlich, die aktuelle Chat-/Sitzungsidentität in die Plugin- -Discovery-Grenze weiterzuleiten, damit das gemeinsame `message`-Tool die richtige, dem Kanal gehörende -Oberfläche für den aktuellen Turn bereitstellt. +Erkennungsgrenze weiterzugeben, damit das gemeinsame `message`-Tool die richtige +kanaleigene Oberfläche für den aktuellen Turn bereitstellt. -Für kanaleigene Ausführungshelfer sollten gebündelte Plugins die Ausführungs- -Laufzeit innerhalb ihrer eigenen Extension-Module behalten. Der Kern besitzt nicht mehr die Laufzeiten -für Discord-, Slack-, Telegram- oder WhatsApp-Nachrichtenaktionen unter `src/agents/tools`. -Wir veröffentlichen keine separaten `plugin-sdk/*-action-runtime`-Subpaths, und gebündelte +Für kanal-eigene Ausführungshilfen sollten gebündelte Plugins die Ausführungs- +Laufzeit innerhalb ihrer eigenen Erweiterungsmodule halten. Der Kern besitzt nicht mehr die Discord-, +Slack-, Telegram- oder WhatsApp-Nachrichtenaktions-Laufzeiten unter `src/agents/tools`. +Wir veröffentlichen keine separaten `plugin-sdk/*-action-runtime`-Unterpfade, und gebündelte Plugins sollten ihren eigenen lokalen Laufzeitcode direkt aus ihren -Extension-eigenen Modulen importieren. +erweiterungseigenen Modulen importieren. -Dieselbe Grenze gilt allgemein für providerbenannte SDK-Seams: Der Kern sollte +Dieselbe Grenze gilt im Allgemeinen auch für providerbenannte SDK-Seams: Der Kern sollte keine kanalspezifischen Convenience-Barrels für Slack, Discord, Signal, -WhatsApp oder ähnliche Extensions importieren. Wenn der Kern ein Verhalten benötigt, dann entweder -über das eigene Barrel `api.ts` / `runtime-api.ts` des gebündelten Plugins oder durch Anheben -dieses Bedarfs in eine schmale generische Fähigkeit im gemeinsamen SDK. +WhatsApp oder ähnliche Erweiterungen importieren. Wenn der Kern ein Verhalten benötigt, sollte er entweder +das eigene Barrel `api.ts` / `runtime-api.ts` des gebündelten Plugins verwenden oder den Bedarf +in eine schmale generische Fähigkeit im gemeinsamen SDK überführen. Speziell für Umfragen gibt es zwei Ausführungspfade: -- `outbound.sendPoll` ist die gemeinsame Basis für Kanäle, die zum gemeinsamen +- `outbound.sendPoll` ist die gemeinsame Grundlage für Kanäle, die in das gemeinsame Umfragemodell passen - `actions.handleAction("poll")` ist der bevorzugte Pfad für kanalspezifische Umfragesemantik oder zusätzliche Umfrageparameter -Der Kern verschiebt das gemeinsame Umfrage-Parsing jetzt so lange, bis der -Plugin-Umfrage-Dispatch die Aktion ablehnt, damit plugin-eigene Umfrage-Handler -kanalspezifische Umfragefelder akzeptieren können, ohne zuerst vom generischen -Umfrage-Parser blockiert zu werden. +Der Kern verschiebt das gemeinsame Parsing von Umfragen jetzt, bis der +Plugin-eigene Umfrage-Dispatch die Aktion abgelehnt hat, sodass Plugin-eigene +Umfrage-Handler kanalspezifische Umfragefelder akzeptieren können, ohne zuerst +vom generischen Umfrageparser blockiert zu werden. -Die vollständige Startsequenz finden Sie unter [Ladepipeline](#load-pipeline). +Siehe [Ladepipeline](#load-pipeline) für die vollständige Startsequenz. -## Ownership-Modell für Fähigkeiten +## Modell der Fähigkeits-Eigentümerschaft -OpenClaw behandelt ein natives Plugin als Ownership-Grenze für ein **Unternehmen** oder ein -**Feature**, nicht als Sammelsurium unabhängiger Integrationen. +OpenClaw behandelt ein natives Plugin als Eigentumsgrenze für ein **Unternehmen** oder ein +**Feature**, nicht als Sammelsurium nicht zusammenhängender Integrationen. Das bedeutet: -- ein Unternehmens-Plugin sollte normalerweise alle OpenClaw-seitigen +- ein Unternehmens-Plugin sollte normalerweise alle OpenClaw-bezogenen Oberflächen dieses Unternehmens besitzen -- ein Feature-Plugin sollte normalerweise die gesamte von ihm eingeführte Feature-Oberfläche besitzen -- Kanäle sollten gemeinsame Kernfähigkeiten konsumieren, statt Provider-Verhalten ad hoc +- ein Feature-Plugin sollte normalerweise die vollständige Oberfläche des von ihm eingeführten + Features besitzen +- Kanäle sollten gemeinsame Kernfähigkeiten nutzen, statt Provider-Verhalten ad hoc neu zu implementieren Beispiele: -- das gebündelte Plugin `openai` besitzt das OpenAI-Modellprovider-Verhalten und OpenAI- - Verhalten für Sprache + Echtzeit-Sprache + Medienverständnis + Bildgenerierung -- das gebündelte Plugin `elevenlabs` besitzt das ElevenLabs-Sprachverhalten -- das gebündelte Plugin `microsoft` besitzt das Microsoft-Sprachverhalten -- das gebündelte Plugin `google` besitzt das Google-Modellprovider-Verhalten sowie Google- +- das gebündelte Plugin `openai` besitzt OpenAI-Modell-Provider-Verhalten und OpenAI- + Verhalten für Sprache + Echtzeit-Stimme + Medienverständnis + Bildgenerierung +- das gebündelte Plugin `elevenlabs` besitzt das Sprachverhalten von ElevenLabs +- das gebündelte Plugin `microsoft` besitzt das Sprachverhalten von Microsoft +- das gebündelte Plugin `google` besitzt das Google-Modell-Provider-Verhalten sowie Google- Verhalten für Medienverständnis + Bildgenerierung + Websuche -- das gebündelte Plugin `firecrawl` besitzt das Firecrawl-Web-Abruf-Verhalten +- das gebündelte Plugin `firecrawl` besitzt das Web-Abruf-Verhalten von Firecrawl - die gebündelten Plugins `minimax`, `mistral`, `moonshot` und `zai` besitzen ihre Backends für Medienverständnis +- das gebündelte Plugin `qwen` besitzt das Qwen-Text-Provider-Verhalten sowie + Medienverständnis- und Videogenerierungsverhalten - das Plugin `voice-call` ist ein Feature-Plugin: Es besitzt Anruftransport, Tools, - CLI, Routen und Twilio-Medienstrom-Bridging, nutzt aber gemeinsame Sprach- sowie - Echtzeit-Transkriptions- und Echtzeit-Sprach-Fähigkeiten, statt Anbieter-Plugins direkt + CLI, Routen und Twilio-Media-Stream-Bridging, nutzt aber gemeinsame Fähigkeiten für Sprache + sowie Echtzeit-Transkription und Echtzeit-Stimme, statt Anbieter-Plugins direkt zu importieren Der angestrebte Endzustand ist: - OpenAI lebt in einem Plugin, auch wenn es Textmodelle, Sprache, Bilder und - künftig Video umfasst + zukünftiges Video umfasst - ein anderer Anbieter kann dasselbe für seinen eigenen Oberflächenbereich tun -- Kanäle ist es egal, welches Anbieter-Plugin den Provider besitzt; sie konsumieren den +- Kanäle kümmern sich nicht darum, welches Anbieter-Plugin den Provider besitzt; sie nutzen den gemeinsamen Fähigkeitsvertrag, den der Kern bereitstellt -Das ist die zentrale Unterscheidung: +Das ist der entscheidende Unterschied: -- **Plugin** = Ownership-Grenze -- **Fähigkeit** = Kernvertrag, den mehrere Plugins implementieren oder konsumieren können +- **plugin** = Eigentumsgrenze +- **capability** = Kernvertrag, den mehrere Plugins implementieren oder nutzen können -Wenn OpenClaw also eine neue Domäne wie Video hinzufügt, ist die erste Frage nicht -„welcher Provider sollte die Videoverarbeitung fest einkodieren?“ Die erste Frage lautet „wie sieht -der Kernvertrag für die Videofähigkeit aus?“ Sobald dieser Vertrag existiert, können sich Anbieter- -Plugins dagegen registrieren und Kanal-/Feature-Plugins ihn konsumieren. +Wenn OpenClaw also eine neue Domäne wie Video hinzufügt, lautet die erste Frage nicht +„welcher Provider sollte die Videoverarbeitung fest verdrahten?“ Die erste Frage ist „was ist +der zentrale Video-Fähigkeitsvertrag?“ Sobald dieser Vertrag existiert, können Anbieter-Plugins +sich dafür registrieren und Kanal-/Feature-Plugins ihn nutzen. -Wenn die Fähigkeit noch nicht existiert, ist der richtige Weg in der Regel: +Wenn die Fähigkeit noch nicht existiert, ist der richtige Schritt normalerweise: 1. die fehlende Fähigkeit im Kern definieren 2. sie typisiert über die Plugin-API/Laufzeit verfügbar machen -3. Kanäle/Features gegen diese Fähigkeit verdrahten -4. Anbieter-Plugins Implementierungen registrieren lassen +3. Kanäle/Features an diese Fähigkeit anbinden +4. Anbieter-Plugins ihre Implementierungen registrieren lassen -So bleibt Ownership explizit, ohne Kernverhalten zu schaffen, das von -einem einzelnen Anbieter oder einem einmaligen plugin-spezifischen Codepfad abhängt. +So bleibt Eigentümerschaft explizit, während Kernverhalten vermieden wird, das von einem +einzigen Anbieter oder einem einmaligen plugin-spezifischen Codepfad abhängt. -### Schichtung von Fähigkeiten +### Fähigkeitsschichtung -Verwenden Sie dieses mentale Modell, um zu entscheiden, wohin Code gehört: +Verwenden Sie dieses Denkmodell, wenn Sie entscheiden, wohin Code gehört: -- **Kern-Fähigkeitsschicht**: gemeinsame Orchestrierung, Richtlinien, Fallback, Konfigurations- - Merge-Regeln, Bereitstellungssemantik und typisierte Verträge -- **Anbieter-Plugin-Schicht**: anbieterspezifische APIs, Authentifizierung, Modellkataloge, Sprach- +- **Kern-Fähigkeitsebene**: gemeinsame Orchestrierung, Richtlinien, Fallback, + Regeln zum Zusammenführen von Konfigurationen, Zustellungssemantik und typisierte Verträge +- **Anbieter-Plugin-Ebene**: anbieterspezifische APIs, Authentifizierung, Modellkataloge, Sprach- synthese, Bildgenerierung, zukünftige Video-Backends, Nutzungsendpunkte -- **Kanal-/Feature-Plugin-Schicht**: Slack/Discord/voice-call/etc.-Integration, - die Kernfähigkeiten konsumiert und auf einer Oberfläche präsentiert +- **Kanal-/Feature-Plugin-Ebene**: Integration für Slack/Discord/voice-call/usw., + die Kernfähigkeiten nutzt und auf einer Oberfläche bereitstellt -Zum Beispiel folgt TTS dieser Form: +Zum Beispiel folgt TTS dieser Struktur: -- der Kern besitzt TTS-Richtlinien zur Antwortzeit, Fallback-Reihenfolge, Präferenzen und Kanalzustellung -- `openai`, `elevenlabs` und `microsoft` besitzen Syntheseimplementierungen -- `voice-call` konsumiert den Laufzeithelfer für Telefonie-TTS +- der Kern besitzt die TTS-Richtlinie zur Antwortzeit, Fallback-Reihenfolge, Präferenzen und Kanalzustellung +- `openai`, `elevenlabs` und `microsoft` besitzen die Synthese-Implementierungen +- `voice-call` nutzt die Laufzeit-Hilfsfunktion für Telefonie-TTS Dasselbe Muster sollte für zukünftige Fähigkeiten bevorzugt werden. ### Beispiel für ein Unternehmens-Plugin mit mehreren Fähigkeiten Ein Unternehmens-Plugin sollte sich von außen kohärent anfühlen. Wenn OpenClaw gemeinsame -Verträge für Modelle, Sprache, Echtzeit-Transkription, Echtzeit-Sprache, Medien- -verständnis, Bildgenerierung, Videogenerierung, Web-Abruf und Websuche hat, +Verträge für Modelle, Sprache, Echtzeit-Transkription, Echtzeit-Stimme, Medienverständnis, +Bildgenerierung, Videogenerierung, Web-Abruf und Websuche hat, kann ein Anbieter alle seine Oberflächen an einer Stelle besitzen: ```ts @@ -363,63 +367,63 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Entscheidend sind nicht die exakten Helper-Namen. Entscheidend ist die Form: +Wichtig sind nicht die genauen Namen der Hilfsfunktionen. Die Struktur ist entscheidend: - ein Plugin besitzt die Anbieteroberfläche - der Kern besitzt weiterhin die Fähigkeitsverträge -- Kanäle und Feature-Plugins konsumieren `api.runtime.*`-Helfer, nicht Anbieter-Code -- Vertragstests können prüfen, dass das Plugin die Fähigkeiten registriert hat, die es - laut eigener Angabe besitzt +- Kanal- und Feature-Plugins nutzen Hilfsfunktionen aus `api.runtime.*`, nicht Anbietercode +- Vertragstests können prüfen, dass das Plugin die Fähigkeiten registriert hat, + die es für sich beansprucht ### Fähigkeitsbeispiel: Videoverständnis OpenClaw behandelt Bild-/Audio-/Videoverständnis bereits als eine gemeinsame -Fähigkeit. Dasselbe Ownership-Modell gilt auch hier: +Fähigkeit. Dasselbe Eigentumsmodell gilt auch dort: 1. der Kern definiert den Vertrag für Medienverständnis -2. Anbieter-Plugins registrieren je nach Bedarf `describeImage`, `transcribeAudio` und +2. Anbieter-Plugins registrieren je nach Anwendbarkeit `describeImage`, `transcribeAudio` und `describeVideo` -3. Kanal- und Feature-Plugins konsumieren das gemeinsame Kernverhalten, statt - direkt mit Anbieter-Code verdrahtet zu sein +3. Kanal- und Feature-Plugins nutzen das gemeinsame Kernverhalten, statt + direkt Anbietercode anzubinden -Dadurch wird vermieden, die Video-Annahmen eines einzelnen Providers in den Kern einzubacken. Das Plugin besitzt +So wird vermieden, die Video-Annahmen eines Anbieters im Kern fest einzubauen. Das Plugin besitzt die Anbieteroberfläche; der Kern besitzt den Fähigkeitsvertrag und das Fallback-Verhalten. -Die Videogenerierung folgt bereits derselben Sequenz: Der Kern besitzt den typisierten -Fähigkeitsvertrag und den Laufzeithelfer, und Anbieter-Plugins registrieren -`api.registerVideoGenerationProvider(...)`-Implementierungen dagegen. +Videogenerierung verwendet bereits genau diese Reihenfolge: Der Kern besitzt den typisierten +Fähigkeitsvertrag und die Laufzeit-Hilfsfunktion, und Anbieter-Plugins registrieren +Implementierungen von `api.registerVideoGenerationProvider(...)` dafür. -Sie brauchen eine konkrete Checkliste für die Einführung? Siehe +Benötigen Sie eine konkrete Checkliste für die Einführung? Siehe [Capability Cookbook](/de/plugins/architecture). ## Verträge und Durchsetzung -Die Oberfläche der Plugin-API ist absichtlich typisiert und in +Die Plugin-API-Oberfläche ist absichtlich typisiert und in `OpenClawPluginApi` zentralisiert. Dieser Vertrag definiert die unterstützten Registrierungspunkte und -die Laufzeit-Helfer, auf die sich ein Plugin verlassen darf. +die Laufzeit-Hilfsfunktionen, auf die sich ein Plugin verlassen darf. Warum das wichtig ist: -- Plugin-Autorinnen und -Autoren erhalten einen stabilen internen Standard -- der Kern kann doppelte Ownership ablehnen, etwa wenn zwei Plugins dieselbe +- Plugin-Autoren erhalten einen stabilen internen Standard +- der Kern kann doppelte Eigentümerschaft ablehnen, etwa wenn zwei Plugins dieselbe Provider-ID registrieren -- beim Start können verwertbare Diagnosen für fehlerhafte Registrierungen ausgegeben werden -- Vertragstests können die Ownership gebündelter Plugins durchsetzen und stilles Driften verhindern +- beim Start können umsetzbare Diagnosen für fehlerhafte Registrierungen angezeigt werden +- Vertragstests können die Eigentümerschaft gebündelter Plugins durchsetzen und lautlose Abweichungen verhindern Es gibt zwei Ebenen der Durchsetzung: 1. **Durchsetzung bei der Laufzeitregistrierung** - Die Plugin-Registry validiert Registrierungen während Plugins geladen werden. Beispiele: - doppelte Provider-IDs, doppelte Speech-Provider-IDs und fehlerhafte - Registrierungen erzeugen Plugin-Diagnosen statt undefiniertem Verhalten. + Die Plugin-Registry validiert Registrierungen während des Ladens der Plugins. Beispiele: + doppelte Provider-IDs, doppelte Sprach-Provider-IDs und fehlerhafte + Registrierungen erzeugen Plugin-Diagnosen statt undefiniertes Verhalten. 2. **Vertragstests** - Gebündelte Plugins werden in Vertrag-Registries während Testläufen erfasst, damit - OpenClaw Ownership explizit prüfen kann. Heute wird dies für Modell- - provider, Speech-Provider, Websuch-Provider und die Ownership gebündelter Registrierungen verwendet. + Gebündelte Plugins werden bei Testläufen in Vertrags-Registries erfasst, sodass + OpenClaw Eigentümerschaft explizit prüfen kann. Heute wird das für Modell- + Provider, Sprach-Provider, Websuch-Provider und gebündelte Registrierungseigentümerschaft verwendet. -Der praktische Effekt ist, dass OpenClaw von Anfang an weiß, welches Plugin welche -Oberfläche besitzt. Dadurch können Kern und Kanäle nahtlos zusammenspielen, weil Ownership -deklariert, typisiert und testbar ist statt implizit. +Der praktische Effekt ist, dass OpenClaw von vornherein weiß, welches Plugin welche +Oberfläche besitzt. Das ermöglicht es Kern und Kanälen, nahtlos zusammenzusetzen, weil +Eigentümerschaft deklariert, typisiert und testbar ist statt implizit. ### Was in einen Vertrag gehört @@ -430,41 +434,41 @@ Gute Plugin-Verträge sind: - fähigkeitsspezifisch - im Besitz des Kerns - von mehreren Plugins wiederverwendbar -- von Kanälen/Features ohne Anbieterwissen konsumierbar +- von Kanälen/Features ohne Anbieterwissen nutzbar Schlechte Plugin-Verträge sind: -- im Kern versteckte anbieterspezifische Richtlinien -- einmalige Plugin-Escape-Hatches, die die Registry umgehen -- Kanal-Code, der direkt in eine Anbieterimplementierung greift +- anbieterspezifische Richtlinien, die im Kern verborgen sind +- einmalige Plugin-Notausgänge, die die Registry umgehen +- Kanalcode, der direkt in eine Anbieterimplementierung greift - ad hoc erzeugte Laufzeitobjekte, die nicht Teil von `OpenClawPluginApi` oder `api.runtime` sind -Wenn Sie unsicher sind, heben Sie die Abstraktionsebene an: Definieren Sie zuerst die Fähigkeit und -lassen Sie dann Plugins daran andocken. +Im Zweifel: heben Sie die Abstraktionsebene an. Definieren Sie zuerst die Fähigkeit und lassen Sie +dann Plugins daran andocken. ## Ausführungsmodell Native OpenClaw-Plugins laufen **im Prozess** mit dem Gateway. Sie sind nicht -sandboxed. Ein geladenes natives Plugin hat dieselbe Vertrauen-Grenze auf Prozessebene wie +sandboxed. Ein geladenes natives Plugin hat dieselbe prozessweite Vertrauensgrenze wie Kerncode. Auswirkungen: -- ein natives Plugin kann Tools, Netzwerk-Handler, Hooks und Services registrieren +- ein natives Plugin kann Tools, Netzwerk-Handler, Hooks und Dienste registrieren - ein Fehler in einem nativen Plugin kann das Gateway zum Absturz bringen oder destabilisieren -- ein bösartiges natives Plugin ist gleichbedeutend mit beliebiger Codeausführung innerhalb - des OpenClaw-Prozesses +- ein bösartiges natives Plugin entspricht beliebiger Codeausführung innerhalb des + OpenClaw-Prozesses -Kompatible Bundles sind standardmäßig sicherer, weil OpenClaw sie derzeit -als Metadaten-/Content-Pakete behandelt. In aktuellen Releases bedeutet das meist -gebündelte Skills. +Kompatible Bundles sind standardmäßig sicherer, weil OpenClaw sie derzeit als +Metadaten-/Inhaltspakete behandelt. In aktuellen Releases bedeutet das größtenteils gebündelte +Skills. Verwenden Sie Allowlists und explizite Installations-/Ladepfade für nicht gebündelte Plugins. Behandeln Sie -Workspace-Plugins als Entwicklungszeit-Code, nicht als Produktionsstandard. +Workspace-Plugins als Code für die Entwicklungszeit, nicht als Produktionsstandard. -Bei gebündelten Workspace-Paketnamen sollte die Plugin-ID im npm- -Namen verankert bleiben: standardmäßig `@openclaw/` oder ein genehmigtes typisiertes Suffix wie +Für gebündelte Workspace-Paketnamen sollte die Plugin-ID im npm-Namen verankert bleiben: +standardmäßig `@openclaw/` oder ein genehmigtes typisiertes Suffix wie `-provider`, `-plugin`, `-speech`, `-sandbox` oder `-media-understanding`, wenn das Paket absichtlich eine engere Plugin-Rolle bereitstellt. @@ -472,78 +476,83 @@ Wichtiger Vertrauenshinweis: - `plugins.allow` vertraut **Plugin-IDs**, nicht der Herkunft der Quelle. - Ein Workspace-Plugin mit derselben ID wie ein gebündeltes Plugin überschattet - absichtlich die gebündelte Kopie, wenn dieses Workspace-Plugin aktiviert/allowlisted ist. + absichtlich die gebündelte Kopie, wenn dieses Workspace-Plugin aktiviert/in der Allowlist ist. - Das ist normal und nützlich für lokale Entwicklung, Patch-Tests und Hotfixes. ## Exportgrenze -OpenClaw exportiert Fähigkeiten, keine Implementierungs-Convenience. +OpenClaw exportiert Fähigkeiten, nicht Implementierungs-Bequemlichkeit. -Halten Sie Fähigkeitsregistrierungen öffentlich. Reduzieren Sie nicht-vertragliche Helper-Exporte: +Halten Sie die Fähigkeitsregistrierung öffentlich. Beschneiden Sie Nicht-Vertrags-Hilfsexporte: -- gebündelte plugin-spezifische Helper-Subpaths -- Laufzeit-Plumbing-Subpaths, die nicht als öffentliche API gedacht sind -- anbieterspezifische Convenience-Helper -- Setup-/Onboarding-Helfer, die Implementierungsdetails sind +- Hilfs-Unterpfade spezifisch für gebündelte Plugins +- Laufzeit-Plumbing-Unterpfade, die nicht als öffentliche API gedacht sind +- anbieterspezifische Convenience-Hilfsfunktionen +- Setup-/Onboarding-Hilfsfunktionen, die Implementierungsdetails sind -Einige Helper-Subpaths gebündelter Plugins verbleiben aus Kompatibilitäts- und Wartungsgründen -weiterhin in der generierten SDK-Exportzuordnung. Aktuelle Beispiele sind +Einige Hilfs-Unterpfade gebündelter Plugins bleiben aus Kompatibilitätsgründen und für die Pflege +gebündelter Plugins weiterhin in der generierten SDK-Exportzuordnung enthalten. Aktuelle Beispiele sind `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` und mehrere `plugin-sdk/matrix*`-Seams. Behandeln Sie diese als -reservierte Exporte für Implementierungsdetails, nicht als empfohlenes SDK-Muster für +reservierte, implementierungsbezogene Exporte und nicht als das empfohlene SDK-Muster für neue Drittanbieter-Plugins. ## Ladepipeline Beim Start macht OpenClaw grob Folgendes: -1. potenzielle Plugin-Wurzeln entdecken +1. mögliche Plugin-Wurzeln erkennen 2. native oder kompatible Bundle-Manifeste und Paketmetadaten lesen 3. unsichere Kandidaten ablehnen 4. Plugin-Konfiguration normalisieren (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. Aktivierung für jeden Kandidaten entscheiden +5. für jeden Kandidaten die Aktivierung entscheiden 6. aktivierte native Module per jiti laden -7. native Hooks `register(api)` (oder `activate(api)` — ein Legacy-Alias) aufrufen und Registrierungen in die Plugin-Registry einsammeln -8. die Registry für Befehle/Laufzeitoberflächen bereitstellen +7. native Hooks `register(api)` (oder `activate(api)` — ein Legacy-Alias) aufrufen und Registrierungen in der Plugin-Registry sammeln +8. die Registry für Befehle/Laufzeitoberflächen verfügbar machen -`activate` ist ein Legacy-Alias für `register` — der Loader löst auf, was vorhanden ist (`def.register ?? def.activate`), und ruft es an derselben Stelle auf. Alle gebündelten Plugins verwenden `register`; bevorzugen Sie `register` für neue Plugins. +`activate` ist ein Legacy-Alias für `register` — der Loader löst den vorhandenen Hook auf (`def.register ?? def.activate`) und ruft ihn an derselben Stelle auf. Alle gebündelten Plugins verwenden `register`; bevorzugen Sie `register` für neue Plugins. Die Sicherheitsprüfungen erfolgen **vor** der Laufzeitausführung. Kandidaten werden blockiert, wenn der Einstiegspunkt die Plugin-Wurzel verlässt, der Pfad weltweit beschreibbar ist oder die Pfad- -Ownership bei nicht gebündelten Plugins verdächtig aussieht. +Eigentümerschaft bei nicht gebündelten Plugins verdächtig aussieht. -### Manifest-first-Verhalten +### Manifest-First-Verhalten -Das Manifest ist die Quelle der Wahrheit auf der Control-Plane. OpenClaw verwendet es, um: +Das Manifest ist die Quelle der Wahrheit für die Steuerungsebene. OpenClaw nutzt es, um: - das Plugin zu identifizieren -- deklarierte Kanäle/Skills/Konfigurationsschema oder Bundle-Fähigkeiten zu entdecken +- deklarierte Kanäle/Skills/Konfigurationsschema oder Bundle-Fähigkeiten zu erkennen - `plugins.entries..config` zu validieren -- Labels/Platzhalter in der Control UI zu ergänzen +- Labels/Platzhalter der Control UI zu ergänzen - Installations-/Katalogmetadaten anzuzeigen +- günstige Aktivierungs- und Setup-Deskriptoren zu erhalten, ohne die Plugin-Laufzeit zu laden -Für native Plugins ist das Laufzeitmodul der Data-Plane-Teil. Es registriert +Für native Plugins ist das Laufzeitmodul der Teil der Datenebene. Es registriert tatsächliches Verhalten wie Hooks, Tools, Befehle oder Provider-Flows. -### Was der Loader cached +Optionale Manifest-Blöcke `activation` und `setup` bleiben auf der Steuerungsebene. +Sie sind reine Metadaten-Deskriptoren für Aktivierungsplanung und Setup-Erkennung; +sie ersetzen nicht die Laufzeitregistrierung, `register(...)` oder `setupEntry`. -OpenClaw hält kurze In-Process-Caches für: +### Was der Loader zwischenspeichert -- Discovery-Ergebnisse -- Daten der Manifest-Registry +OpenClaw hält kurze prozessinterne Caches für: + +- Erkennungsergebnisse +- Manifest-Registry-Daten - geladene Plugin-Registries -Diese Caches reduzieren burstartige Starts und den Overhead wiederholter Befehle. Man kann sie -als kurzlebige Performance-Caches betrachten, nicht als Persistenz. +Diese Caches reduzieren burstartigen Startaufwand und den Overhead wiederholter Befehle. Sie lassen sich sicher +als kurzlebige Performance-Caches verstehen, nicht als Persistenz. -Leistungshinweis: +Hinweis zur Performance: - Setzen Sie `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` oder `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, um diese Caches zu deaktivieren. -- Passen Sie Cache-Fenster mit `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` und +- Passen Sie die Cache-Fenster mit `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` und `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` an. ## Registry-Modell @@ -553,7 +562,7 @@ zentralen Plugin-Registry. Die Registry verfolgt: -- Plugin-Einträge (Identität, Quelle, Herkunft, Status, Diagnosen) +- Plugin-Einträge (Identität, Quelle, Ursprung, Status, Diagnosen) - Tools - Legacy-Hooks und typisierte Hooks - Kanäle @@ -561,23 +570,23 @@ Die Registry verfolgt: - Gateway-RPC-Handler - HTTP-Routen - CLI-Registrare -- Hintergrund-Services -- plugin-eigene Befehle +- Hintergrunddienste +- Plugin-eigene Befehle -Kern-Features lesen dann aus dieser Registry, statt direkt mit Plugin-Modulen -zu sprechen. Dadurch bleibt das Laden eindirektional: +Kernfunktionen lesen dann aus dieser Registry, statt direkt mit Plugin-Modulen zu sprechen. +Dadurch bleibt das Laden einseitig: - Plugin-Modul -> Registry-Registrierung -- Kern-Laufzeit -> Registry-Konsum +- Kern-Laufzeit -> Registry-Nutzung -Diese Trennung ist für die Wartbarkeit wichtig. Sie bedeutet, dass die meisten Kernoberflächen nur -einen Integrationspunkt brauchen: „Registry lesen“, nicht „jedes Plugin-Modul gesondert behandeln“. +Diese Trennung ist wichtig für die Wartbarkeit. Sie bedeutet, dass die meisten Kernoberflächen nur +einen Integrationspunkt brauchen: „die Registry lesen“, nicht „jedes Plugin-Modul speziell behandeln“. -## Callbacks für Konversationsbindung +## Rückrufe für Konversationsbindung -Plugins, die eine Konversation binden, können reagieren, wenn eine Genehmigung entschieden wurde. +Plugins, die eine Konversation binden, können reagieren, wenn eine Genehmigung aufgelöst wird. -Verwenden Sie `api.onConversationBindingResolved(...)`, um einen Callback zu erhalten, nachdem eine Bindungs- +Verwenden Sie `api.onConversationBindingResolved(...)`, um einen Rückruf zu erhalten, nachdem eine Bindungs- anfrage genehmigt oder abgelehnt wurde: ```ts @@ -598,27 +607,27 @@ export default { }; ``` -Felder der Callback-Nutzlast: +Felder der Rückrufnutzlast: - `status`: `"approved"` oder `"denied"` - `decision`: `"allow-once"`, `"allow-always"` oder `"deny"` - `binding`: die aufgelöste Bindung für genehmigte Anfragen -- `request`: die ursprüngliche Anforderungszusammenfassung, Detach-Hinweis, Sender-ID und +- `request`: die ursprüngliche Anfragezusammenfassung, Trennhinweis, Sender-ID und Konversationsmetadaten -Dieser Callback dient nur zur Benachrichtigung. Er ändert nicht, wer eine -Konversation binden darf, und läuft erst, nachdem die Kernbehandlung der Genehmigung abgeschlossen ist. +Dieser Rückruf dient nur zur Benachrichtigung. Er ändert nicht, wer eine Konversation binden darf, +und er läuft, nachdem die Genehmigungsverarbeitung des Kerns abgeschlossen ist. ## Provider-Laufzeit-Hooks Provider-Plugins haben jetzt zwei Ebenen: -- Manifest-Metadaten: `providerAuthEnvVars` für günstige Provider- - Env-Auth-Erkennung vor dem Laden der Laufzeit, `providerAuthAliases` für Provider-Varianten, die sich - Auth teilen, `channelEnvVars` für günstige Kanal-Env-/Setup-Erkennung vor dem - Laden der Laufzeit sowie `providerAuthChoices` für günstige Labels bei Onboarding/Auth-Auswahl und +- Manifest-Metadaten: `providerAuthEnvVars` für günstige Provider-Umgebungs-Auth-Abfragen + vor dem Laden der Laufzeit, `providerAuthAliases` für Provider-Varianten, die sich + Auth teilen, `channelEnvVars` für günstige Kanal-Umgebungs-/Setup-Abfragen vor dem Laden der Laufzeit, + sowie `providerAuthChoices` für günstige Onboarding-/Auth-Auswahllabels und CLI-Flag-Metadaten vor dem Laden der Laufzeit -- Hooks zur Konfigurationszeit: `catalog` / Legacy-`discovery` sowie `applyConfigDefaults` +- Hooks zur Konfigurationszeit: `catalog` / Legacy-`discovery` plus `applyConfigDefaults` - Laufzeit-Hooks: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -639,87 +648,87 @@ Provider-Plugins haben jetzt zwei Ebenen: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw besitzt weiterhin die generische Agent-Schleife, den Failover, die Verarbeitung von Transkripten und +OpenClaw besitzt weiterhin die generische Agent-Schleife, Failover, Transkriptbehandlung und Tool-Richtlinien. Diese Hooks sind die Erweiterungsoberfläche für anbieterspezifisches Verhalten, ohne einen vollständig benutzerdefinierten Inferenztransport zu benötigen. -Verwenden Sie das Manifest `providerAuthEnvVars`, wenn der Provider env-basierte -Anmeldedaten hat, die generische Auth-/Status-/Modell-Picker-Pfade sehen sollen, ohne die Plugin-Laufzeit -zu laden. Verwenden Sie Manifest-`providerAuthAliases`, wenn eine Provider-ID die Env-Variablen, -Auth-Profile, konfigurationsgestützte Auth und die API-Key-Onboarding-Wahl einer anderen Provider-ID -wiederverwenden soll. Verwenden Sie Manifest-`providerAuthChoices`, wenn CLI-Oberflächen -für Onboarding/Auth-Auswahl die Choice-ID des Providers, Gruppenlabels und einfache -Auth-Verdrahtung per Einzelflag kennen sollen, ohne die Provider-Laufzeit zu laden. Behalten Sie in der Provider-Laufzeit -`envVars` für operatorseitige Hinweise wie Onboarding-Labels oder -Setup-Variablen für OAuth-Client-ID/Client-Secret. +Verwenden Sie Manifest-`providerAuthEnvVars`, wenn der Provider umgebungsbasierte Anmeldedaten hat, +die generische Auth-/Status-/Modellauswahlpfade sehen sollen, ohne die Plugin- +Laufzeit zu laden. Verwenden Sie Manifest-`providerAuthAliases`, wenn eine Provider-ID die +Umgebungsvariablen, Auth-Profile, konfigurationsgestützte Authentifizierung und die +API-Schlüssel-Onboarding-Auswahl einer anderen Provider-ID wiederverwenden soll. Verwenden Sie Manifest-`providerAuthChoices`, wenn +CLI-Oberflächen für Onboarding-/Auth-Auswahl die Auswahl-ID, Gruppenlabels und einfache +Auth-Verdrahtung mit einem Flag des Providers kennen sollen, ohne die Provider-Laufzeit zu laden. Behalten Sie in der Provider-Laufzeit +`envVars` für operatorseitige Hinweise wie Onboarding-Labels oder OAuth- +client-id-/client-secret-Setup-Variablen. -Verwenden Sie Manifest-`channelEnvVars`, wenn ein Kanal env-gesteuerte Auth oder Einrichtung hat, -die generischer Shell-Env-Fallback, Konfigurations-/Statusprüfungen oder Setup-Prompts sehen sollen, +Verwenden Sie Manifest-`channelEnvVars`, wenn ein Kanal umgebungsgetriebene Authentifizierung oder Einrichtung hat, +die generischer Shell-Umgebungs-Fallback, Konfigurations-/Statusprüfungen oder Setup-Prompts sehen sollen, ohne die Kanal-Laufzeit zu laden. ### Hook-Reihenfolge und Verwendung -Für Modell-/Provider-Plugins ruft OpenClaw Hooks ungefähr in dieser Reihenfolge auf. -Die Spalte „Wann verwenden“ ist die schnelle Entscheidungshilfe. +Für Modell-/Provider-Plugins ruft OpenClaw Hooks in ungefähr dieser Reihenfolge auf. +Die Spalte „Wann verwenden“ ist der schnelle Entscheidungsleitfaden. | # | Hook | Was er macht | Wann verwenden | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Provider-Konfiguration bei der Generierung von `models.json` in `models.providers` veröffentlichen | Der Provider besitzt einen Katalog oder Standardwerte für `baseUrl` | -| 2 | `applyConfigDefaults` | plugin-eigene globale Konfigurationsstandards während der Konfigurationsmaterialisierung anwenden | Standardwerte hängen von Auth-Modus, Env oder der Semantik der Provider-Modellfamilie ab | -| -- | _(integrierte Modellsuche)_ | OpenClaw versucht zuerst den normalen Registry-/Katalog-Pfad | _(kein Plugin-Hook)_ | -| 3 | `normalizeModelId` | Legacy- oder Preview-Aliase für Modell-IDs vor der Suche normalisieren | Der Provider besitzt Alias-Bereinigung vor der kanonischen Modellauflösung | -| 4 | `normalizeTransport` | Provider-Familien-`api` / `baseUrl` vor generischer Modellzusammenstellung normalisieren | Der Provider besitzt Transport-Bereinigung für benutzerdefinierte Provider-IDs in derselben Transportfamilie | -| 5 | `normalizeConfig` | `models.providers.` vor Laufzeit-/Provider-Auflösung normalisieren | Der Provider benötigt Konfigurationsbereinigung, die beim Plugin leben sollte; gebündelte Google-Familien-Helper fangen auch unterstützte Google-Konfigurationseinträge ab | -| 6 | `applyNativeStreamingUsageCompat` | Native Streaming-Usage-Kompatibilitäts-Umschreibungen auf Konfigurationsprovider anwenden | Der Provider benötigt endpunktgesteuerte Korrekturen für native Streaming-Usage-Metadaten | -| 7 | `resolveConfigApiKey` | Env-Marker-Auth für Konfigurationsprovider vor dem Laden der Laufzeit-Auth auflösen | Der Provider besitzt eine plugin-eigene Auflösung von Env-Marker-API-Keys; `amazon-bedrock` hat hier ebenfalls einen eingebauten AWS-Env-Marker-Resolver | -| 8 | `resolveSyntheticAuth` | lokale/self-hosted oder konfigurationsgestützte Auth anzeigen, ohne Klartext zu persistieren | Der Provider kann mit einem synthetischen/lokalen Credential-Marker arbeiten | -| 9 | `resolveExternalAuthProfiles` | plugin-eigene externe Auth-Profile überlagern; Standard-`persistence` ist `runtime-only` für CLI-/app-eigene Credentials | Der Provider verwendet externe Auth-Credentials wieder, ohne kopierte Refresh-Tokens zu persistieren | -| 10 | `shouldDeferSyntheticProfileAuth` | gespeicherte synthetische Profil-Platzhalter hinter env-/konfigurationsgestützter Auth zurückstufen | Der Provider speichert synthetische Platzhalterprofile, die keine Priorität haben sollten | -| 11 | `resolveDynamicModel` | synchroner Fallback für plugin-eigene Modell-IDs, die noch nicht in der lokalen Registry sind | Der Provider akzeptiert beliebige Upstream-Modell-IDs | -| 12 | `prepareDynamicModel` | asynchrones Warm-up, dann läuft `resolveDynamicModel` erneut | Der Provider benötigt Netzwerkmetadaten, bevor unbekannte IDs aufgelöst werden können | -| 13 | `normalizeResolvedModel` | endgültige Umschreibung, bevor der Embedded-Runner das aufgelöste Modell verwendet | Der Provider benötigt Transport-Umschreibungen, verwendet aber weiterhin einen Kerntransport | -| 14 | `contributeResolvedModelCompat` | Kompatibilitätsflags für Anbietermodelle hinter einem anderen kompatiblen Transport beisteuern | Der Provider erkennt seine eigenen Modelle auf Proxy-Transporten, ohne den Provider zu übernehmen | -| 15 | `capabilities` | plugin-eigene Transkript-/Tooling-Metadaten, die von gemeinsamer Kernlogik verwendet werden | Der Provider benötigt Besonderheiten für Transkripte/Provider-Familien | -| 16 | `normalizeToolSchemas` | Tool-Schemas normalisieren, bevor der Embedded-Runner sie sieht | Der Provider benötigt schemaseitige Bereinigung für eine Transportfamilie | -| 17 | `inspectToolSchemas` | plugin-eigene Schema-Diagnosen nach der Normalisierung ausgeben | Der Provider möchte Keyword-Warnungen ausgeben, ohne dem Kern anbieterspezifische Regeln beizubringen | -| 18 | `resolveReasoningOutputMode` | nativen versus getaggten Vertrag für Reasoning-Ausgaben auswählen | Der Provider benötigt getaggtes Reasoning/finale Ausgabe statt nativer Felder | -| 19 | `prepareExtraParams` | Normalisierung von Anfrageparametern vor generischen Stream-Option-Wrappern | Der Provider benötigt Standard-Anfrageparameter oder anbieterspezifische Parameterbereinigung | -| 20 | `createStreamFn` | normalen Stream-Pfad vollständig durch einen benutzerdefinierten Transport ersetzen | Der Provider benötigt ein benutzerdefiniertes Wire-Protokoll, nicht nur einen Wrapper | -| 21 | `wrapStreamFn` | Stream-Wrapper, nachdem generische Wrapper angewendet wurden | Der Provider benötigt Wrapper für Anfrageheader/Body/Modell-Kompatibilität ohne benutzerdefinierten Transport | -| 22 | `resolveTransportTurnState` | native turnbezogene Transport-Header oder -Metadaten anhängen | Der Provider möchte, dass generische Transporte die providereigene Turn-Identität senden | -| 23 | `resolveWebSocketSessionPolicy` | native WebSocket-Header oder Richtlinien zur Session-Abkühlung anhängen | Der Provider möchte, dass generische WS-Transporte Session-Header oder Fallback-Richtlinien abstimmen | -| 24 | `formatApiKey` | Auth-Profil-Formatierer: gespeichertes Profil wird zur Laufzeit-Zeichenfolge `apiKey` | Der Provider speichert zusätzliche Auth-Metadaten und benötigt eine benutzerdefinierte Laufzeit-Tokenform | -| 25 | `refreshOAuth` | OAuth-Refresh-Override für benutzerdefinierte Refresh-Endpunkte oder Richtlinien bei Refresh-Fehlschlägen | Der Provider passt nicht zu den gemeinsamen `pi-ai`-Refreshern | -| 26 | `buildAuthDoctorHint` | Reparaturhinweis, der angehängt wird, wenn OAuth-Refresh fehlschlägt | Der Provider benötigt plugin-eigene Hinweise zur Auth-Reparatur nach einem Refresh-Fehler | -| 27 | `matchesContextOverflowError` | plugin-eigener Matcher für Überläufe des Kontextfensters | Der Provider hat rohe Overflow-Fehler, die generische Heuristiken übersehen würden | -| 28 | `classifyFailoverReason` | plugin-eigene Klassifizierung des Failover-Grunds | Der Provider kann rohe API-/Transportfehler auf Ratenbegrenzung/Überlast/etc. abbilden | -| 29 | `isCacheTtlEligible` | Richtlinie für Prompt-Cache bei Proxy-/Backhaul-Providern | Der Provider benötigt proxy-spezifisches Cache-TTL-Gating | -| 30 | `buildMissingAuthMessage` | Ersatz für die generische Wiederherstellungsnachricht bei fehlender Auth | Der Provider benötigt einen provider-spezifischen Hinweis zur Wiederherstellung fehlender Auth | -| 31 | `suppressBuiltInModel` | Unterdrückung veralteter Upstream-Modelle plus optionaler benutzerseitiger Fehlerhinweis | Der Provider muss veraltete Upstream-Zeilen ausblenden oder durch einen Anbieterhinweis ersetzen | -| 32 | `augmentModelCatalog` | synthetische/endgültige Katalogzeilen, die nach Discovery angehängt werden | Der Provider benötigt synthetische Vorwärtskompatibilitäts-Zeilen in `models list` und Pickern | -| 33 | `isBinaryThinking` | Ein/Aus-Reasoning-Umschaltung für Anbieter mit binärem Thinking | Der Provider bietet nur binäres Thinking an/aus an | +| 1 | `catalog` | Provider-Konfiguration während der Generierung von `models.json` in `models.providers` veröffentlichen | Der Provider besitzt einen Katalog oder Standardwerte für die Basis-URL | +| 2 | `applyConfigDefaults` | Provider-eigene globale Konfigurationsstandardwerte bei der Materialisierung der Konfiguration anwenden | Standardwerte hängen vom Auth-Modus, der Umgebung oder der Semantik der Provider-Modellfamilie ab | +| -- | _(integrierte Modellsuche)_ | OpenClaw versucht zuerst den normalen Registry-/Katalogpfad | _(kein Plugin-Hook)_ | +| 3 | `normalizeModelId` | Legacy- oder Vorschau-Aliasse für Modell-IDs vor der Suche normalisieren | Der Provider besitzt die Alias-Bereinigung vor der kanonischen Modellauflösung | +| 4 | `normalizeTransport` | `api` / `baseUrl` einer Provider-Familie vor der generischen Modellzusammensetzung normalisieren | Der Provider besitzt die Transport-Bereinigung für benutzerdefinierte Provider-IDs in derselben Transportfamilie | +| 5 | `normalizeConfig` | `models.providers.` vor der Laufzeit-/Provider-Auflösung normalisieren | Der Provider benötigt Konfigurationsbereinigung, die beim Plugin liegen sollte; gebündelte Hilfsfunktionen der Google-Familie stützen auch unterstützte Google-Konfigurationseinträge ab | +| 6 | `applyNativeStreamingUsageCompat` | Umschreibungen für Kompatibilität der nativen Streaming-Nutzung auf Konfigurations-Provider anwenden | Der Provider benötigt endpunktgesteuerte Korrekturen an Metadaten zur nativen Streaming-Nutzung | +| 7 | `resolveConfigApiKey` | Authentifizierung über Umgebungsmarker für Konfigurations-Provider vor dem Laden der Laufzeit-Auth auflösen | Der Provider besitzt die Auflösung von API-Schlüsseln über Umgebungsmarker; `amazon-bedrock` hat hier ebenfalls einen eingebauten AWS-Umgebungsmarker-Resolver | +| 8 | `resolveSyntheticAuth` | lokale/self-hosted oder konfigurationsgestützte Authentifizierung bereitstellen, ohne Klartext zu persistieren | Der Provider kann mit einem synthetischen/lokalen Anmeldedatenmarker arbeiten | +| 9 | `resolveExternalAuthProfiles` | provider-eigene externe Auth-Profile überlagern; standardmäßige `persistence` ist `runtime-only` für CLI-/app-eigene Anmeldedaten | Der Provider verwendet externe Auth-Anmeldedaten wieder, ohne kopierte Refresh-Tokens zu persistieren | +| 10 | `shouldDeferSyntheticProfileAuth` | gespeicherte synthetische Profil-Platzhalter hinter umgebungs-/konfigurationsgestützter Authentifizierung einordnen | Der Provider speichert synthetische Platzhalterprofile, die keinen Vorrang haben sollten | +| 11 | `resolveDynamicModel` | synchrones Fallback für provider-eigene Modell-IDs, die noch nicht in der lokalen Registry sind | Der Provider akzeptiert beliebige vorgelagerte Modell-IDs | +| 12 | `prepareDynamicModel` | asynchrones Aufwärmen, dann wird `resolveDynamicModel` erneut ausgeführt | Der Provider benötigt Netzwerkmetadaten, bevor unbekannte IDs aufgelöst werden können | +| 13 | `normalizeResolvedModel` | endgültige Umschreibung, bevor der eingebettete Runner das aufgelöste Modell verwendet | Der Provider benötigt Transport-Umschreibungen, verwendet aber weiterhin einen Kern-Transport | +| 14 | `contributeResolvedModelCompat` | Kompatibilitäts-Flags für Anbietermodelle hinter einem anderen kompatiblen Transport beitragen | Der Provider erkennt seine eigenen Modelle auf Proxy-Transporten, ohne den Provider zu übernehmen | +| 15 | `capabilities` | provider-eigene Transkript-/Tooling-Metadaten, die von gemeinsamer Kernlogik genutzt werden | Der Provider benötigt Besonderheiten für Transkripte oder Provider-Familien | +| 16 | `normalizeToolSchemas` | Tool-Schemata normalisieren, bevor der eingebettete Runner sie sieht | Der Provider benötigt Schemabereinigung für Transportfamilien | +| 17 | `inspectToolSchemas` | provider-eigene Schemadiagnosen nach der Normalisierung sichtbar machen | Der Provider möchte Schlüsselwortwarnungen anzeigen, ohne dem Kern providerspezifische Regeln beizubringen | +| 18 | `resolveReasoningOutputMode` | nativen oder getaggten Vertrag für Reasoning-Ausgaben auswählen | Der Provider benötigt getaggte Reasoning-/Final-Ausgabe statt nativer Felder | +| 19 | `prepareExtraParams` | Normalisierung von Anfrageparametern vor generischen Wrappern für Stream-Optionen | Der Provider benötigt Standard-Anfrageparameter oder providerbezogene Parameterbereinigung | +| 20 | `createStreamFn` | den normalen Stream-Pfad vollständig durch einen benutzerdefinierten Transport ersetzen | Der Provider benötigt ein benutzerdefiniertes Wire-Protokoll, nicht nur einen Wrapper | +| 21 | `wrapStreamFn` | Stream-Wrapper, nachdem generische Wrapper angewendet wurden | Der Provider benötigt Kompatibilitäts-Wrapper für Anfrage-Header/Body/Modell ohne benutzerdefinierten Transport | +| 22 | `resolveTransportTurnState` | native turnbezogene Transport-Header oder Metadaten anhängen | Der Provider möchte, dass generische Transporte die native Turn-Identität des Providers senden | +| 23 | `resolveWebSocketSessionPolicy` | native WebSocket-Header oder Richtlinie für Session-Abklingzeit anhängen | Der Provider möchte, dass generische WS-Transporte Session-Header oder Fallback-Richtlinien abstimmen | +| 24 | `formatApiKey` | Formatter für Auth-Profile: gespeichertes Profil wird zur Laufzeitzeichenfolge `apiKey` | Der Provider speichert zusätzliche Auth-Metadaten und benötigt eine benutzerdefinierte Laufzeit-Tokenform | +| 25 | `refreshOAuth` | OAuth-Refresh-Override für benutzerdefinierte Refresh-Endpunkte oder Richtlinien bei Refresh-Fehlern | Der Provider passt nicht zu den gemeinsamen `pi-ai`-Refreshern | +| 26 | `buildAuthDoctorHint` | Reparaturhinweis, der angehängt wird, wenn der OAuth-Refresh fehlschlägt | Der Provider benötigt provider-eigene Hinweise zur Auth-Reparatur nach einem Refresh-Fehler | +| 27 | `matchesContextOverflowError` | provider-eigener Matcher für Überläufe des Kontextfensters | Der Provider hat rohe Überlauffehler, die generische Heuristiken übersehen würden | +| 28 | `classifyFailoverReason` | provider-eigene Klassifizierung von Failover-Gründen | Der Provider kann rohe API-/Transportfehler auf Ratenbegrenzung/Überlastung/usw. abbilden | +| 29 | `isCacheTtlEligible` | Richtlinie für Prompt-Cache bei Proxy-/Backhaul-Providern | Der Provider benötigt proxyspezifische Steuerung für Cache-TTL | +| 30 | `buildMissingAuthMessage` | Ersatz für die generische Wiederherstellungsnachricht bei fehlender Authentifizierung | Der Provider benötigt einen providerspezifischen Wiederherstellungshinweis bei fehlender Authentifizierung | +| 31 | `suppressBuiltInModel` | Unterdrückung veralteter vorgelagerter Modelle plus optionaler benutzerseitiger Fehlerhinweis | Der Provider muss veraltete vorgelagerte Zeilen ausblenden oder durch einen Anbieterhinweis ersetzen | +| 32 | `augmentModelCatalog` | synthetische/endgültige Katalogzeilen, die nach der Erkennung angehängt werden | Der Provider benötigt synthetische Vorwärtskompatibilitäts-Zeilen in `models list` und Auswahllisten | +| 33 | `isBinaryThinking` | Reasoning-Umschalter Ein/Aus für Provider mit binärem Thinking | Der Provider bietet nur binäres Thinking Ein/Aus an | | 34 | `supportsXHighThinking` | `xhigh`-Reasoning-Unterstützung für ausgewählte Modelle | Der Provider möchte `xhigh` nur für eine Teilmenge von Modellen | -| 35 | `resolveDefaultThinkingLevel` | Standard-`/think`-Level für eine bestimmte Modellfamilie | Der Provider besitzt die Standard-`/think`-Richtlinie für eine Modellfamilie | -| 36 | `isModernModelRef` | Matcher für moderne Modelle für Live-Profil-Filter und Smoke-Auswahl | Der Provider besitzt das Matching bevorzugter Modelle für Live/Smoke | -| 37 | `prepareRuntimeAuth` | konfiguriertes Credential direkt vor der Inferenz in das tatsächliche Laufzeit-Token/den Schlüssel umtauschen | Der Provider benötigt einen Tokenaustausch oder kurzlebige Anfrage-Credentials | -| 38 | `resolveUsageAuth` | Credentials für Nutzung/Abrechnung für `/usage` und verwandte Statusoberflächen auflösen | Der Provider benötigt benutzerdefinierte Tokenanalyse für Nutzung/Quota oder andere Usage-Credentials | -| 39 | `fetchUsageSnapshot` | provider-spezifische Nutzung-/Quota-Snapshots abrufen und normalisieren, nachdem Auth aufgelöst wurde | Der Provider benötigt einen provider-spezifischen Usage-Endpunkt oder Payload-Parser | -| 40 | `createEmbeddingProvider` | plugin-eigenen Embedding-Adapter für Speicher/Suche bauen | Verhalten für Memory-Embeddings gehört zum Provider-Plugin | -| 41 | `buildReplayPolicy` | eine Replay-Richtlinie zurückgeben, die den Umgang des Providers mit Transkripten steuert | Der Provider benötigt eine benutzerdefinierte Transkript-Richtlinie (zum Beispiel Entfernen von Thinking-Blöcken) | -| 42 | `sanitizeReplayHistory` | Replay-Verlauf nach generischer Transkript-Bereinigung umschreiben | Der Provider benötigt provider-spezifische Replay-Umschreibungen über gemeinsame Kompaktion-Helper hinaus | -| 43 | `validateReplayTurns` | endgültige Validierung oder Umformung von Replay-Turns vor dem Embedded-Runner | Der Provider-Transport benötigt strengere Turn-Validierung nach generischer Bereinigung | -| 44 | `onModelSelected` | plugin-eigene Nebeneffekte nach Auswahl des Modells ausführen | Der Provider benötigt Telemetrie oder provider-eigenen Zustand, wenn ein Modell aktiv wird | +| 35 | `resolveDefaultThinkingLevel` | Standardstufe für `/think` für eine bestimmte Modellfamilie auflösen | Der Provider besitzt die Standardrichtlinie für `/think` einer Modellfamilie | +| 36 | `isModernModelRef` | Matcher für moderne Modelle für Live-Profilfilter und Smoke-Auswahl | Der Provider besitzt das Matching bevorzugter Modelle für Live-/Smoke-Tests | +| 37 | `prepareRuntimeAuth` | eine konfigurierte Anmeldedate in das tatsächliche Laufzeit-Token/den tatsächlichen Schlüssel direkt vor der Inferenz umwandeln | Der Provider benötigt einen Tokenaustausch oder kurzlebige Anfrage-Anmeldedaten | +| 38 | `resolveUsageAuth` | Nutzungs-/Abrechnungs-Anmeldedaten für `/usage` und verwandte Statusoberflächen auflösen | Der Provider benötigt benutzerdefiniertes Token-Parsen für Nutzung/Kontingente oder andere Nutzungs-Anmeldedaten | +| 39 | `fetchUsageSnapshot` | provider-spezifische Nutzungs-/Kontingent-Snapshots abrufen und normalisieren, nachdem die Authentifizierung aufgelöst wurde | Der Provider benötigt einen provider-spezifischen Nutzungsendpunkt oder Payload-Parser | +| 40 | `createEmbeddingProvider` | einen provider-eigenen Embedding-Adapter für Speicher/Suche erstellen | Embedding-Verhalten für Speicher gehört zum Provider-Plugin | +| 41 | `buildReplayPolicy` | eine Replay-Richtlinie zurückgeben, die die Transkriptbehandlung für den Provider steuert | Der Provider benötigt eine benutzerdefinierte Transkript-Richtlinie (zum Beispiel das Entfernen von Thinking-Blöcken) | +| 42 | `sanitizeReplayHistory` | Replay-Verlauf nach generischer Transkriptbereinigung umschreiben | Der Provider benötigt provider-spezifische Umschreibungen des Replay-Verlaufs über gemeinsame Hilfsfunktionen zur Kompaktierung hinaus | +| 43 | `validateReplayTurns` | endgültige Validierung oder Umformung von Replay-Turns vor dem eingebetteten Runner | Der Provider-Transport benötigt strengere Turn-Validierung nach generischer Bereinigung | +| 44 | `onModelSelected` | provider-eigene Seiteneffekte nach der Modellauswahl ausführen | Der Provider benötigt Telemetrie oder provider-eigenen Zustand, wenn ein Modell aktiv wird | `normalizeModelId`, `normalizeTransport` und `normalizeConfig` prüfen zuerst das -zugeordnete Provider-Plugin und greifen dann auf andere hook-fähige Provider-Plugins zurück, -bis eines tatsächlich die Modell-ID oder den Transport/die Konfiguration ändert. Das hält -Alias-/Kompatibilitäts-Provider-Shims funktionsfähig, ohne vom Aufrufer zu verlangen zu wissen, -welches gebündelte Plugin die Umschreibung besitzt. Wenn kein Provider-Hook einen unterstützten -Google-Familien-Konfigurationseintrag umschreibt, greift weiterhin der gebündelte Google-Konfigurations- -Normalizer für diese Kompatibilitätsbereinigung. +zugeordnete Provider-Plugin und fallen dann auf andere Hook-fähige Provider-Plugins zurück, +bis eines tatsächlich die Modell-ID oder den Transport/die Konfiguration ändert. So bleiben +Alias-/Kompatibilitäts-Shims für Provider funktionsfähig, ohne dass der Aufrufer wissen muss, welches +gebündelte Plugin die Umschreibung besitzt. Wenn kein Provider-Hook einen unterstützten +Google-Familien-Konfigurationseintrag umschreibt, führt der gebündelte Google-Konfigurationsnormalisierer +diese Kompatibilitätsbereinigung weiterhin aus. -Wenn der Provider ein vollständig benutzerdefiniertes Wire-Protokoll oder einen benutzerdefinierten Request- -Executor benötigt, ist das eine andere Klasse von Erweiterung. Diese Hooks sind für Provider-Verhalten gedacht, +Wenn der Provider ein vollständig benutzerdefiniertes Wire-Protokoll oder einen benutzerdefinierten Anfrage-Ausführer benötigt, +ist das eine andere Klasse von Erweiterung. Diese Hooks sind für Provider-Verhalten gedacht, das weiterhin auf der normalen Inferenzschleife von OpenClaw läuft. ### Provider-Beispiel @@ -782,114 +791,114 @@ api.registerProvider({ `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` und `wrapStreamFn`, weil es Vorwärtskompatibilität für Claude 4.6, - Hinweise zur Provider-Familie, Anleitungen zur Auth-Reparatur, Integration von - Nutzungsendpunkten, Prompt-Cache-Eignung, auth-bewusste Konfigurationsstandards, die - Standard-/adaptive Thinking-Richtlinie für Claude sowie Anthropic-spezifisches Stream-Shaping für + Hinweise für Provider-Familien, Leitlinien zur Auth-Reparatur, Integration von Nutzungsendpunkten, + Prompt-Cache-Eignung, auth-sensitive Konfigurationsstandardwerte, die + Standard-/adaptive Thinking-Richtlinie für Claude und Anthropic-spezifische Stream-Gestaltung für Beta-Header, `/fast` / `serviceTier` und `context1m` besitzt. -- Die Claude-spezifischen Stream-Helper von Anthropic verbleiben vorerst in der eigenen - öffentlichen Naht `api.ts` / `contract-api.ts` des gebündelten Plugins. Diese Paketoberfläche +- Die Claude-spezifischen Stream-Hilfsfunktionen von Anthropic bleiben vorerst in der eigenen + öffentlichen `api.ts` / `contract-api.ts`-Seam des gebündelten Plugins. Diese Paketoberfläche exportiert `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` sowie die Low-Level- - Anthropic-Wrapper-Builder, statt das generische SDK um die Beta-Header-Regeln eines - einzelnen Providers zu erweitern. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` und die niedrigeren + Builder für Anthropic-Wrapper, statt das generische SDK um die Beta-Header-Regeln + eines einzelnen Providers zu erweitern. - OpenAI verwendet `resolveDynamicModel`, `normalizeResolvedModel` und `capabilities` sowie `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` und `isModernModelRef`, weil es Vorwärtskompatibilität für GPT-5.4, die direkte OpenAI- - Normalisierung `openai-completions` -> `openai-responses`, Codex-bewusste Auth- - Hinweise, Spark-Unterdrückung, synthetische OpenAI-Listenzeilen und GPT-5-Thinking-/ - Live-Modell-Richtlinien besitzt; die Stream-Familie `openai-responses-defaults` besitzt die - gemeinsamen nativen OpenAI-Responses-Wrapper für Zuordnungsheader, - `/fast`/`serviceTier`, Textausführlichkeit, native Codex-Websuche, - Reasoning-kompatibles Payload-Shaping und Responses-Kontextverwaltung. + Normalisierung `openai-completions` -> `openai-responses`, Codex-sensible Auth- + Hinweise, Spark-Unterdrückung, synthetische OpenAI-Listenzeilen und die Thinking- / + Live-Modell-Richtlinie für GPT-5 besitzt; die Stream-Familie `openai-responses-defaults` besitzt die + gemeinsamen nativen OpenAI-Responses-Wrapper für Attribution-Header, + `/fast`/`serviceTier`, Text-Verbosity, native Codex-Websuche, + kompatible Formung von Reasoning-Payloads und Responses-Kontextverwaltung. - OpenRouter verwendet `catalog` sowie `resolveDynamicModel` und `prepareDynamicModel`, weil der Provider ein Pass-through ist und neue - Modell-IDs verfügbar machen kann, bevor der statische Katalog von OpenClaw aktualisiert wird; außerdem nutzt es + Modell-IDs verfügbar machen kann, bevor der statische Katalog von OpenClaw aktualisiert wird; außerdem verwendet es `capabilities`, `wrapStreamFn` und `isCacheTtlEligible`, um - provider-spezifische Request-Header, Routing-Metadaten, Reasoning-Patches und + provider-spezifische Anfrage-Header, Routing-Metadaten, Reasoning-Patches und Prompt-Cache-Richtlinien aus dem Kern herauszuhalten. Seine Replay-Richtlinie stammt aus der Familie `passthrough-gemini`, während die Stream-Familie `openrouter-thinking` - Proxy-Reasoning-Injection und das Überspringen nicht unterstützter Modelle bzw. von `auto` besitzt. + die Proxy-Reasoning-Injektion und das Überspringen von nicht unterstützten Modellen / `auto` besitzt. - GitHub Copilot verwendet `catalog`, `auth`, `resolveDynamicModel` und `capabilities` sowie `prepareRuntimeAuth` und `fetchUsageSnapshot`, weil es - provider-eigenes Device-Login, Modell-Fallback-Verhalten, Besonderheiten bei Claude-Transkripten, + provider-eigenen Device-Login, Modell-Fallback-Verhalten, Eigenheiten von Claude-Transkripten, einen GitHub-Token -> Copilot-Token-Austausch und einen provider-eigenen Nutzungsendpunkt benötigt. - OpenAI Codex verwendet `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` und `augmentModelCatalog` sowie `prepareExtraParams`, `resolveUsageAuth` und `fetchUsageSnapshot`, weil es - weiterhin auf Kern-OpenAI-Transporten läuft, aber seine Transport-/`baseUrl`- - Normalisierung, Richtlinien zum OAuth-Refresh-Fallback, die Standardwahl des Transports, + weiterhin auf Kern-OpenAI-Transporten läuft, aber seine Transport-/Basis-URL- + Normalisierung, OAuth-Refresh-Fallback-Richtlinie, Standard-Transportauswahl, synthetische Codex-Katalogzeilen und die Integration des ChatGPT-Nutzungsendpunkts besitzt; es - teilt sich dieselbe Stream-Familie `openai-responses-defaults` wie direktes OpenAI. + teilt dieselbe Stream-Familie `openai-responses-defaults` wie direktes OpenAI. - Google AI Studio und Gemini CLI OAuth verwenden `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` und `isModernModelRef`, weil die - Replay-Familie `google-gemini` den Vorwärtskompatibilitäts-Fallback für Gemini 3.1, - native Gemini-Replay-Validierung, Bootstrap-Replay-Säuberung, den getaggten - Reasoning-Ausgabemodus und das Matching moderner Modelle besitzt, während die + Replay-Familie `google-gemini` Vorwärtskompatibilitäts-Fallback für Gemini 3.1, + native Replay-Validierung für Gemini, Bereinigung von Bootstrap-Replays, + getaggten Reasoning-Output-Modus und Matching für moderne Modelle besitzt, während die Stream-Familie `google-thinking` die Normalisierung von Gemini-Thinking-Payloads besitzt; Gemini CLI OAuth verwendet außerdem `formatApiKey`, `resolveUsageAuth` und - `fetchUsageSnapshot` für Token-Formatierung, Token-Parsing und - Verdrahtung des Quota-Endpunkts. + `fetchUsageSnapshot` für Tokenformatierung, Token-Parsen und Verdrahtung des + Kontingent-Endpunkts. - Anthropic Vertex verwendet `buildReplayPolicy` über die - Replay-Familie `anthropic-by-model`, damit Claude-spezifische Replay-Bereinigung - auf Claude-IDs beschränkt bleibt statt auf jeden Transport `anthropic-messages`. + Replay-Familie `anthropic-by-model`, sodass Claude-spezifische Replay-Bereinigung + auf Claude-IDs beschränkt bleibt statt auf jeden `anthropic-messages`-Transport. - Amazon Bedrock verwendet `buildReplayPolicy`, `matchesContextOverflowError`, `classifyFailoverReason` und `resolveDefaultThinkingLevel`, weil es - Bedrock-spezifische Klassifizierung von Throttle-/Not-ready-/Context-Overflow-Fehlern - für Anthropic-auf-Bedrock-Datenverkehr besitzt; seine Replay-Richtlinie teilt sich weiterhin denselben - nur-für-Claude-Schutz `anthropic-by-model`. + die Bedrock-spezifische Klassifizierung von Fehlern wie Drosselung/Nicht-bereit/Kontextüberlauf + für Anthropic-on-Bedrock-Datenverkehr besitzt; seine Replay-Richtlinie teilt weiterhin denselben + Claude-spezifischen Guard `anthropic-by-model`. - OpenRouter, Kilocode, Opencode und Opencode Go verwenden `buildReplayPolicy` über die Replay-Familie `passthrough-gemini`, weil sie Gemini- Modelle über OpenAI-kompatible Transporte proxien und eine Bereinigung von Gemini- - Thought-Signatures ohne native Gemini-Replay-Validierung oder - Bootstrap-Umschreibungen benötigen. + Thought-Signaturen benötigen, jedoch keine native Gemini-Replay-Validierung oder + Bootstrap-Umschreibungen. - MiniMax verwendet `buildReplayPolicy` über die - Replay-Familie `hybrid-anthropic-openai`, weil ein Provider sowohl Semantik - für Anthropic-Nachrichten als auch OpenAI-Kompatibilität besitzt; Claude-spezifisches - Entfernen von Thinking-Blöcken bleibt auf der Anthropic-Seite, während der - Reasoning-Ausgabemodus zurück auf nativ gesetzt wird, und die Stream-Familie `minimax-fast-mode` + Replay-Familie `hybrid-anthropic-openai`, weil ein Provider sowohl + Anthropic-Nachrichten- als auch OpenAI-kompatible Semantik besitzt; dadurch bleibt das + Entfernen von Thinking-Blöcken nur auf der Anthropic-Seite auf Claude beschränkt, während der + Reasoning-Output-Modus wieder auf nativ zurückgesetzt wird, und die Stream-Familie `minimax-fast-mode` besitzt Umschreibungen für den Fast-Modus auf dem gemeinsamen Stream-Pfad. - Moonshot verwendet `catalog` sowie `wrapStreamFn`, weil es weiterhin den gemeinsamen OpenAI-Transport nutzt, aber provider-eigene Normalisierung von Thinking-Payloads benötigt; die - Stream-Familie `moonshot-thinking` ordnet Konfiguration plus `/think`-Zustand seiner - nativen binären Thinking-Payload zu. + Stream-Familie `moonshot-thinking` bildet Konfiguration plus `/think`-Status auf ihre + native binäre Thinking-Payload ab. - Kilocode verwendet `catalog`, `capabilities`, `wrapStreamFn` und - `isCacheTtlEligible`, weil es provider-eigene Request-Header, - Normalisierung von Reasoning-Payloads, Hinweise für Gemini-Transkripte und Anthropic- - Cache-TTL-Gating benötigt; die Stream-Familie `kilocode-thinking` hält die Kilo- - Thinking-Injektion auf dem gemeinsamen Proxy-Stream-Pfad, während `kilo/auto` und - andere Proxy-Modell-IDs, die keine expliziten Reasoning-Payloads unterstützen, ausgelassen werden. + `isCacheTtlEligible`, weil es provider-eigene Anfrage-Header, + Normalisierung von Reasoning-Payloads, Gemini-Transkripthinweise und Anthropic- + Cache-TTL-Steuerung benötigt; die Stream-Familie `kilocode-thinking` hält die Kilo-Thinking- + Injektion auf dem gemeinsamen Proxy-Stream-Pfad, während `kilo/auto` und + andere Proxy-Modell-IDs übersprungen werden, die keine expliziten Reasoning-Payloads unterstützen. - Z.AI verwendet `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, `resolveUsageAuth` und `fetchUsageSnapshot`, weil es GLM-5-Fallback, - Standardwerte für `tool_stream`, binäre Thinking-UX, Matching moderner Modelle sowie - sowohl Usage-Auth als auch Quota-Abruf besitzt; die Stream-Familie `tool-stream-default-on` - hält den standardmäßig aktivierten `tool_stream`-Wrapper aus handgeschriebenem - Glue-Code pro Provider heraus. + Standardwerte für `tool_stream`, UX für binäres Thinking, Matching moderner Modelle sowie sowohl + Nutzungs-Auth als auch Kontingentabruf besitzt; die Stream-Familie `tool-stream-default-on` hält + den standardmäßig aktivierten `tool_stream`-Wrapper aus handgeschriebenem Glue pro Provider heraus. - xAI verwendet `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` und `isModernModelRef`, weil es die Normalisierung des nativen xAI-Responses-Transports, Umschreibungen von Grok- - Fast-Mode-Aliassen, Standardwerte für `tool_stream`, Bereinigung für strikte Tools / Reasoning-Payloads, - Wiederverwendung von Fallback-Auth für plugin-eigene Tools, Vorwärtskompatibilitäts- - Auflösung von Grok-Modellen und provider-eigene Kompatibilitätspatches wie xAI-Tool-Schema- - Profil, nicht unterstützte Schema-Keywords, natives `web_search` und HTML-Entity- - Dekodierung für Tool-Call-Argumente besitzt. + Fast-Mode-Aliassen, standardmäßiges `tool_stream`, Bereinigung von Strict-Tool / Reasoning-Payload, + Fallback-Wiederverwendung von Auth für plugin-eigene Tools, Vorwärtskompatibilitäts-Auflösung von Grok- + Modellen und provider-eigene Kompatibilitätspatches wie xAI-Tool-Schema- + Profil, nicht unterstützte Schema-Schlüsselwörter, natives `web_search` und HTML-Entity- + Dekodierung von Tool-Call-Argumenten besitzt. - Mistral, OpenCode Zen und OpenCode Go verwenden nur `capabilities`, um - Besonderheiten bei Transkripten/Tooling aus dem Kern herauszuhalten. -- Nur-Katalog-gebündelte Provider wie `byteplus`, `cloudflare-ai-gateway`, + Eigenheiten von Transkripten/Tooling aus dem Kern herauszuhalten. +- Gebündelte Provider nur mit Katalog wie `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` und `volcengine` verwenden nur `catalog`. -- Qwen verwendet `catalog` für seinen Textprovider sowie gemeinsame Registrierungen für - Medienverständnis und Videogenerierung für seine multimodalen Oberflächen. -- MiniMax und Xiaomi verwenden `catalog` sowie Usage-Hooks, weil ihr `/usage`- - Verhalten plugin-eigen ist, obwohl die Inferenz weiterhin über die gemeinsamen Transporte läuft. +- Qwen verwendet `catalog` für seinen Text-Provider sowie gemeinsame Registrierungen für Medienverständnis und + Videogenerierung für seine multimodalen Oberflächen. +- MiniMax und Xiaomi verwenden `catalog` sowie Nutzungs-Hooks, weil ihr `/usage`- + Verhalten dem Plugin gehört, auch wenn die Inferenz weiterhin über die gemeinsamen + Transporte läuft. -## Laufzeit-Helfer +## Laufzeit-Hilfsfunktionen -Plugins können über `api.runtime` auf ausgewählte Kern-Helper zugreifen. Für TTS: +Plugins können über `api.runtime` auf ausgewählte Kern-Hilfsfunktionen zugreifen. Für TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -910,14 +919,14 @@ const voices = await api.runtime.tts.listVoices({ Hinweise: -- `textToSpeech` gibt die normale Kern-TTS-Ausgabe-Nutzlast für Datei-/Voice-Note-Oberflächen zurück. -- Verwendet die Kernkonfiguration `messages.tts` und Provider-Auswahl. -- Gibt PCM-Audiopuffer + Samplerate zurück. Plugins müssen für Provider neu sampeln/kodieren. -- `listVoices` ist pro Provider optional. Verwenden Sie es für anbietereigene Sprach-Auswahllisten oder Setup-Flows. -- Sprachlisten können reichere Metadaten wie Gebietsschema, Geschlecht und Persönlichkeits-Tags für providerbewusste Picker enthalten. +- `textToSpeech` gibt die normale Kern-TTS-Ausgabe-Payload für Datei-/Sprachnotiz-Oberflächen zurück. +- Verwendet die Kernkonfiguration `messages.tts` und die Providerauswahl. +- Gibt PCM-Audiopuffer + Abtastrate zurück. Plugins müssen für Provider neu sampeln/kodieren. +- `listVoices` ist je nach Provider optional. Verwenden Sie es für anbieter-eigene Sprachauswahlfelder oder Setup-Flows. +- Sprachlisten können umfangreichere Metadaten wie Sprache, Geschlecht und Persönlichkeitstags für providerbewusste Auswahllisten enthalten. - OpenAI und ElevenLabs unterstützen heute Telefonie. Microsoft nicht. -Plugins können auch Speech-Provider über `api.registerSpeechProvider(...)` registrieren. +Plugins können auch Sprach-Provider über `api.registerSpeechProvider(...)` registrieren. ```ts api.registerSpeechProvider({ @@ -938,14 +947,14 @@ api.registerSpeechProvider({ Hinweise: - Behalten Sie TTS-Richtlinien, Fallback und Antwortzustellung im Kern. -- Verwenden Sie Speech-Provider für anbietereigene Syntheseimplementierungen. +- Verwenden Sie Sprach-Provider für anbieter-eigenes Syntheseverhalten. - Legacy-Microsoft-`edge`-Eingabe wird auf die Provider-ID `microsoft` normalisiert. -- Das bevorzugte Ownership-Modell ist unternehmensorientiert: Ein Anbieter-Plugin kann - Text-, Sprach-, Bild- und künftige Medien-Provider besitzen, wenn OpenClaw diese +- Das bevorzugte Eigentumsmodell ist unternehmensorientiert: Ein Anbieter-Plugin kann + Text-, Sprach-, Bild- und zukünftige Medien-Provider besitzen, wenn OpenClaw diese Fähigkeitsverträge hinzufügt. Für Bild-/Audio-/Videoverständnis registrieren Plugins einen typisierten -Provider für Medienverständnis statt eines generischen Schlüssel/Wert-Sacks: +Provider für Medienverständnis statt eines generischen Schlüssel-/Wert-Sacks: ```ts api.registerMediaUnderstandingProvider({ @@ -963,12 +972,12 @@ Hinweise: - Behalten Sie Anbieterverhalten im Provider-Plugin. - Additive Erweiterungen sollten typisiert bleiben: neue optionale Methoden, neue optionale Ergebnisfelder, neue optionale Fähigkeiten. -- Die Videogenerierung folgt bereits demselben Muster: - - der Kern besitzt den Fähigkeitsvertrag und den Laufzeithelfer +- Videogenerierung folgt bereits demselben Muster: + - der Kern besitzt den Fähigkeitsvertrag und die Laufzeit-Hilfsfunktion - Anbieter-Plugins registrieren `api.registerVideoGenerationProvider(...)` - - Feature-/Kanal-Plugins konsumieren `api.runtime.videoGeneration.*` + - Feature-/Kanal-Plugins nutzen `api.runtime.videoGeneration.*` -Für Laufzeit-Helfer des Medienverständnisses können Plugins Folgendes aufrufen: +Für Laufzeit-Hilfsfunktionen des Medienverständnisses können Plugins Folgendes aufrufen: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -983,8 +992,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Für Audiotranskription können Plugins entweder die Laufzeit des Medienverständnisses -oder das ältere STT-Alias verwenden: +Für Audio-Transkription können Plugins entweder die Laufzeit des Medienverständnisses +oder den älteren STT-Alias verwenden: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ @@ -999,11 +1008,11 @@ Hinweise: - `api.runtime.mediaUnderstanding.*` ist die bevorzugte gemeinsame Oberfläche für Bild-/Audio-/Videoverständnis. -- Verwendet die Audio-Konfiguration des Kern-Medienverständnisses (`tools.media.audio`) und die Provider-Fallback-Reihenfolge. +- Verwendet die Audiokonfiguration des Kern-Medienverständnisses (`tools.media.audio`) und die Fallback-Reihenfolge der Provider. - Gibt `{ text: undefined }` zurück, wenn keine Transkriptionsausgabe erzeugt wird (zum Beispiel bei übersprungenen/nicht unterstützten Eingaben). -- `api.runtime.stt.transcribeAudioFile(...)` bleibt als Kompatibilitäts-Alias bestehen. +- `api.runtime.stt.transcribeAudioFile(...)` bleibt als Kompatibilitätsalias bestehen. -Plugins können auch Hintergrundläufe von Subagents über `api.runtime.subagent` starten: +Plugins können auch Hintergrund-Subagent-Läufe über `api.runtime.subagent` starten: ```ts const result = await api.runtime.subagent.run({ @@ -1018,13 +1027,13 @@ const result = await api.runtime.subagent.run({ Hinweise: - `provider` und `model` sind optionale Überschreibungen pro Lauf, keine persistenten Sitzungsänderungen. -- OpenClaw berücksichtigt diese Override-Felder nur für vertrauenswürdige Aufrufer. +- OpenClaw berücksichtigt diese Überschreibungsfelder nur für vertrauenswürdige Aufrufer. - Für plugin-eigene Fallback-Läufe müssen Operatoren mit `plugins.entries..subagent.allowModelOverride: true` zustimmen. -- Verwenden Sie `plugins.entries..subagent.allowedModels`, um vertrauenswürdige Plugins auf bestimmte kanonische Ziele `provider/model` zu beschränken, oder `"*"`, um explizit jedes Ziel zu erlauben. -- Läufe von Subagents durch nicht vertrauenswürdige Plugins funktionieren weiterhin, aber Override-Anfragen werden abgelehnt, statt stillschweigend zurückzufallen. +- Verwenden Sie `plugins.entries..subagent.allowedModels`, um vertrauenswürdige Plugins auf bestimmte kanonische Ziele `provider/model` zu beschränken, oder `"*"`, um jedes Ziel explizit zu erlauben. +- Läufe untrusted Plugin-Subagenten funktionieren weiterhin, aber Überschreibungsanfragen werden abgelehnt, statt stillschweigend auf Fallback umzuschalten. -Für die Websuche können Plugins den gemeinsamen Laufzeit-Helfer konsumieren, statt -in die Verdrahtung des Agent-Tools zu greifen: +Für Websuche können Plugins die gemeinsame Laufzeit-Hilfsfunktion nutzen, statt +in die Verdrahtung des Agent-Tools einzugreifen: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1045,9 +1054,9 @@ Plugins können Websuch-Provider auch über Hinweise: -- Behalten Sie Provider-Auswahl, Auflösung von Credentials und gemeinsame Request-Semantik im Kern. +- Behalten Sie Providerauswahl, Auflösung von Anmeldedaten und gemeinsame Anfrage-Semantik im Kern. - Verwenden Sie Websuch-Provider für anbieterspezifische Suchtransporte. -- `api.runtime.webSearch.*` ist die bevorzugte gemeinsame Oberfläche für Feature-/Kanal-Plugins, die Suchverhalten benötigen, ohne von dem Agent-Tool-Wrapper abhängig zu sein. +- `api.runtime.webSearch.*` ist die bevorzugte gemeinsame Oberfläche für Feature-/Kanal-Plugins, die Suchverhalten benötigen, ohne von dem Wrapper des Agent-Tools abhängig zu sein. ### `api.runtime.imageGeneration` @@ -1062,12 +1071,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: ein Bild mit der konfigurierten Kette von Bildgenerierungs-Providern erzeugen. -- `listProviders(...)`: verfügbare Bildgenerierungs-Provider und ihre Fähigkeiten auflisten. +- `generate(...)`: ein Bild mit der konfigurierten Provider-Kette für Bildgenerierung erzeugen. +- `listProviders(...)`: verfügbare Provider für Bildgenerierung und ihre Fähigkeiten auflisten. ## Gateway-HTTP-Routen -Plugins können HTTP-Endpunkte mit `api.registerHttpRoute(...)` bereitstellen. +Plugins können HTTP-Endpunkte mit `api.registerHttpRoute(...)` verfügbar machen. ```ts api.registerHttpRoute({ @@ -1085,34 +1094,34 @@ api.registerHttpRoute({ Routenfelder: - `path`: Routenpfad unter dem Gateway-HTTP-Server. -- `auth`: erforderlich. Verwenden Sie `"gateway"`, um normale Gateway-Auth zu verlangen, oder `"plugin"` für pluginverwaltete Auth/Webhook-Verifikation. +- `auth`: erforderlich. Verwenden Sie `"gateway"`, um normale Gateway-Authentifizierung zu verlangen, oder `"plugin"` für pluginverwaltete Authentifizierung/Webhook-Verifizierung. - `match`: optional. `"exact"` (Standard) oder `"prefix"`. -- `replaceExisting`: optional. Erlaubt demselben Plugin, seine eigene bestehende Routenregistrierung zu ersetzen. +- `replaceExisting`: optional. Erlaubt demselben Plugin, seine eigene vorhandene Routenregistrierung zu ersetzen. - `handler`: gibt `true` zurück, wenn die Route die Anfrage verarbeitet hat. Hinweise: -- `api.registerHttpHandler(...)` wurde entfernt und führt zu einem Fehler beim Laden des Plugins. Verwenden Sie stattdessen `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` wurde entfernt und verursacht einen Plugin-Ladefehler. Verwenden Sie stattdessen `api.registerHttpRoute(...)`. - Plugin-Routen müssen `auth` explizit deklarieren. -- Exakte Konflikte von `path + match` werden abgelehnt, außer `replaceExisting: true` ist gesetzt, und ein Plugin kann keine Route eines anderen Plugins ersetzen. -- Überlappende Routen mit unterschiedlichen `auth`-Leveln werden abgelehnt. Halten Sie `exact`-/`prefix`-Fallthrough-Ketten nur auf derselben Auth-Stufe. -- Routen mit `auth: "plugin"` erhalten nicht automatisch Runtime-Scopes des Operators. Sie sind für pluginverwaltete Webhooks/Signaturprüfung gedacht, nicht für privilegierte Gateway-Helper-Aufrufe. -- Routen mit `auth: "gateway"` laufen innerhalb eines Gateway-Request-Runtime-Scopes, aber dieser Scope ist bewusst konservativ: - - Bearer-Auth mit Shared Secret (`gateway.auth.mode = "token"` / `"password"`) hält die Runtime-Scopes von Plugin-Routen auf `operator.write` fest, selbst wenn der Aufrufer `x-openclaw-scopes` sendet - - vertrauenswürdige HTTP-Modi mit identitätstragenden Daten (zum Beispiel `trusted-proxy` oder `gateway.auth.mode = "none"` an einem privaten Ingress) beachten `x-openclaw-scopes` nur, wenn der Header ausdrücklich vorhanden ist - - wenn `x-openclaw-scopes` bei solchen identitätstragenden Plugin-Routenanfragen fehlt, fällt der Runtime-Scope auf `operator.write` zurück -- Praktische Regel: Gehen Sie nicht davon aus, dass eine Gateway-authentifizierte Plugin-Route implizit eine Admin-Oberfläche ist. Wenn Ihre Route rein administratives Verhalten braucht, verlangen Sie einen identitätstragenden Auth-Modus und dokumentieren Sie den expliziten Vertragsumfang des Headers `x-openclaw-scopes`. +- Exakte Konflikte bei `path + match` werden abgelehnt, es sei denn, `replaceExisting: true` ist gesetzt, und ein Plugin kann die Route eines anderen Plugins nicht ersetzen. +- Überlappende Routen mit unterschiedlichen `auth`-Stufen werden abgelehnt. Halten Sie Fallthrough-Ketten mit `exact`/`prefix` nur auf derselben Auth-Stufe. +- Routen mit `auth: "plugin"` erhalten **nicht** automatisch Operator-Laufzeit-Scope. Sie sind für pluginverwaltete Webhooks/Signaturverifizierung gedacht, nicht für privilegierte Gateway-Hilfsaufrufe. +- Routen mit `auth: "gateway"` laufen innerhalb eines Gateway-Anfrage-Laufzeit-Scopes, aber dieser Scope ist absichtlich konservativ: + - Bearer-Authentifizierung mit gemeinsamem Secret (`gateway.auth.mode = "token"` / `"password"`) hält die Laufzeit-Scopes für Plugin-Routen auf `operator.write` fest, auch wenn der Aufrufer `x-openclaw-scopes` sendet + - vertrauenswürdige HTTP-Modi mit Identität (zum Beispiel `trusted-proxy` oder `gateway.auth.mode = "none"` bei privatem Ingress) berücksichtigen `x-openclaw-scopes` nur, wenn der Header explizit vorhanden ist + - wenn `x-openclaw-scopes` bei solchen identitätstragenden Plugin-Routenanfragen fehlt, fällt der Laufzeit-Scope auf `operator.write` zurück +- Praktische Regel: Gehen Sie nicht davon aus, dass eine gateway-auth-Plugin-Route implizit eine Admin-Oberfläche ist. Wenn Ihre Route Verhalten nur für Admins benötigt, verlangen Sie einen identitätstragenden Auth-Modus und dokumentieren Sie den expliziten Header-Vertrag `x-openclaw-scopes`. ## Importpfade des Plugin SDK -Verwenden Sie SDK-Subpaths statt des monolithischen Imports `openclaw/plugin-sdk`, -wenn Sie Plugins erstellen: +Verwenden Sie SDK-Unterpfade statt des monolithischen Imports `openclaw/plugin-sdk`, wenn +Sie Plugins erstellen: -- `openclaw/plugin-sdk/plugin-entry` für Plugin-Registrierungsprimitive. +- `openclaw/plugin-sdk/plugin-entry` für Primitiven zur Plugin-Registrierung. - `openclaw/plugin-sdk/core` für den generischen gemeinsamen pluginseitigen Vertrag. -- `openclaw/plugin-sdk/config-schema` für den Export des Zod-Schemas der Wurzel `openclaw.json` - (`OpenClawSchema`). -- Stabile Kanal-Primitive wie `openclaw/plugin-sdk/channel-setup`, +- `openclaw/plugin-sdk/config-schema` für den Export des Zod-Schemas des + Root-`openclaw.json` (`OpenClawSchema`). +- Stabile Kanal-Primitiven wie `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1126,16 +1135,16 @@ wenn Sie Plugins erstellen: `openclaw/plugin-sdk/secret-input` und `openclaw/plugin-sdk/webhook-ingress` für gemeinsame Setup-/Auth-/Antwort-/Webhook- Verdrahtung. `channel-inbound` ist die gemeinsame Heimat für Debounce, Mention-Matching, - Helper für Inbound-Mention-Richtlinien, Envelope-Formatierung und - Kontext-Helper für Inbound-Envelopes. - `channel-setup` ist die schmale optionale Setup-Naht. + Hilfsfunktionen für eingehende Mention-Richtlinien, Envelope-Formatierung und Hilfsfunktionen für + den Kontext eingehender Envelopes. + `channel-setup` ist die schmale Setup-Seam für optionale Installationen. `setup-runtime` ist die laufzeitsichere Setup-Oberfläche, die von `setupEntry` / - verzögertem Start verwendet wird, einschließlich der importsicheren Setup-Patch-Adapter. - `setup-adapter-runtime` ist die env-bewusste Naht für Account-Setup-Adapter. - `setup-tools` ist die kleine Naht für CLI-/Archiv-/Dokumentations-Helfer (`formatCliCommand`, + verzögertem Start verwendet wird, einschließlich importsicherer Setup-Patch-Adapter. + `setup-adapter-runtime` ist die umgebungsbewusste Seam für Account-Setup-Adapter. + `setup-tools` ist die kleine Hilfs-Seam für CLI/Archiv/Dokumentation (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Domänen-Subpaths wie `openclaw/plugin-sdk/channel-config-helpers`, +- Domänen-Unterpfade wie `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1153,157 +1162,155 @@ wenn Sie Plugins erstellen: `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` und - `openclaw/plugin-sdk/directory-runtime` für gemeinsame Laufzeit-/Konfigurations-Helfer. - `telegram-command-config` ist die schmale öffentliche Naht für Normalisierung/Validierung von benutzerdefinierten Telegram- - Befehlen und bleibt verfügbar, selbst wenn die Vertragsoberfläche des gebündelten - Telegram vorübergehend nicht verfügbar ist. - `text-runtime` ist die gemeinsame Naht für Text/Markdown/Logging, einschließlich - Entfernen von für Assistenten sichtbarem Text, Helpern für Markdown-Rendering/Chunking, Redaktions- - Helpern, Helpern für Richtlinien-Tags und Safe-Text-Utilities. -- Kanalspezifische Approval-Seams sollten bevorzugt einen einzigen `approvalCapability`- - Vertrag auf dem Plugin verwenden. Der Kern liest dann Auth, Bereitstellung, Rendering, - natives Routing und lazy natives Handler-Verhalten für Approvals über diese eine Fähigkeit, - statt Approval-Verhalten in unabhängige Plugin-Felder zu mischen. -- `openclaw/plugin-sdk/channel-runtime` ist veraltet und verbleibt nur als - Kompatibilitäts-Shim für ältere Plugins. Neuer Code sollte stattdessen die schmaleren - generischen Primitive importieren, und Repo-Code sollte keine neuen Importe dieses + `openclaw/plugin-sdk/directory-runtime` für gemeinsame Laufzeit-/Konfigurations-Hilfsfunktionen. + `telegram-command-config` ist die schmale öffentliche Seam für die Normalisierung/Validierung benutzerdefinierter + Telegram-Befehle und bleibt verfügbar, auch wenn die gebündelte + Telegram-Vertragsoberfläche vorübergehend nicht verfügbar ist. + `text-runtime` ist die gemeinsame Text-/Markdown-/Logging-Seam, einschließlich + des Entfernens von für Assistenten sichtbarem Text, Hilfsfunktionen zum Rendern/Chunking von Markdown, Redaktions- + Hilfsfunktionen, Hilfsfunktionen für Direktiven-Tags und sichere Text-Hilfsfunktionen. +- Kanalspezifische Seams für Freigaben sollten einen einzigen Vertrag `approvalCapability` + auf dem Plugin bevorzugen. Der Kern liest dann Authentifizierung, Zustellung, Rendering, + natives Routing und träges natives Handler-Verhalten für Freigaben über diese eine Fähigkeit, + statt Freigabeverhalten in nicht zusammenhängende Plugin-Felder zu mischen. +- `openclaw/plugin-sdk/channel-runtime` ist veraltet und bleibt nur als + Kompatibilitäts-Shim für ältere Plugins bestehen. Neuer Code sollte stattdessen die schmaleren + generischen Primitiven importieren, und Repo-Code sollte keine neuen Importe dieses Shims hinzufügen. -- Interne Elemente gebündelter Extensions bleiben privat. Externe Plugins sollten nur - `openclaw/plugin-sdk/*`-Subpaths verwenden. OpenClaw-Kern-/Test-Code kann die - öffentlichen Repo-Einstiegspunkte unter einer Plugin-Paketwurzel wie `index.js`, `api.js`, +- Interna gebündelter Erweiterungen bleiben privat. Externe Plugins sollten nur + Unterpfade `openclaw/plugin-sdk/*` verwenden. OpenClaw-Kern-/Testcode darf die öffentlichen + Repo-Einstiegspunkte unter einer Plugin-Paketwurzel wie `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js` und eng begrenzte Dateien wie `login-qr-api.js` verwenden. Importieren Sie niemals `src/*` eines Plugin-Pakets aus dem Kern oder aus - einer anderen Extension. + einer anderen Erweiterung. - Aufteilung der Repo-Einstiegspunkte: - `/api.js` ist das Barrel für Helfer/Typen, - `/runtime-api.js` ist das nur-Laufzeit-Barrel, - `/index.js` ist der Einstieg des gebündelten Plugins, - und `/setup-entry.js` ist der Einstieg des Setup-Plugins. + `/api.js` ist das Barrel für Hilfsfunktionen/Typen, + `/runtime-api.js` ist das Barrel nur für die Laufzeit, + `/index.js` ist der Einstiegspunkt des gebündelten Plugins + und `/setup-entry.js` ist der Einstiegspunkt des Setup-Plugins. - Aktuelle Beispiele für gebündelte Provider: - - Anthropic verwendet `api.js` / `contract-api.js` für Claude-Stream-Helper wie - `wrapAnthropicProviderStream`, Helper für Beta-Header und Parsing von `service_tier`. - - OpenAI verwendet `api.js` für Provider-Builder, Helper für Standardmodelle und + - Anthropic verwendet `api.js` / `contract-api.js` für Claude-Stream-Hilfsfunktionen wie + `wrapAnthropicProviderStream`, Hilfsfunktionen für Beta-Header und das Parsen von `service_tier`. + - OpenAI verwendet `api.js` für Provider-Builder, Hilfsfunktionen für Standardmodelle und Builder für Realtime-Provider. - - OpenRouter verwendet `api.js` für seinen Provider-Builder sowie Onboarding-/Konfigurations- - Helper, während `register.runtime.js` weiterhin generische - `plugin-sdk/provider-stream`-Helper für die repo-lokale Nutzung re-exportieren kann. -- Über Fassade geladene öffentliche Einstiegspunkte bevorzugen den aktiven Laufzeit- - Konfigurations-Snapshot, wenn einer existiert, und fallen andernfalls auf die auf der Platte aufgelöste Konfigurationsdatei zurück, - wenn OpenClaw noch keinen Laufzeit-Snapshot bereitstellt. -- Generische gemeinsame Primitive bleiben der bevorzugte öffentliche SDK-Vertrag. Ein kleiner - reservierter Kompatibilitätssatz gebündelter, kanalmarkierter Helper-Seams existiert weiterhin. - Behandeln Sie diese als Seams für gebündelte Wartung/Kompatibilität, nicht als neue - Importziele für Drittanbieter; neue kanalübergreifende Verträge sollten weiterhin auf - generischen `plugin-sdk/*`-Subpaths oder den plugin-lokalen Barrels `api.js` / + - OpenRouter verwendet `api.js` für seinen Provider-Builder sowie Hilfsfunktionen für Onboarding/Konfiguration, + während `register.runtime.js` weiterhin generische + Hilfsfunktionen `plugin-sdk/provider-stream` für die repo-lokale Nutzung reexportieren kann. +- Öffentlich verfügbare Einstiegspunkte, die über Fassaden geladen werden, bevorzugen den aktiven Laufzeit-Konfigurations-Snapshot, + wenn einer vorhanden ist, und fallen dann auf die auf der Festplatte aufgelöste Konfigurationsdatei zurück, wenn + OpenClaw noch keinen Laufzeit-Snapshot bereitstellt. +- Generische gemeinsame Primitiven bleiben der bevorzugte öffentliche SDK-Vertrag. Eine kleine + reservierte Kompatibilitätsmenge an Hilfs-Seams mit Branding gebündelter Kanäle existiert weiterhin. + Behandeln Sie diese als Seams für Pflege/Kompatibilität gebündelter Komponenten, nicht als neue Importziele für Drittanbieter; + neue kanalübergreifende Verträge sollten weiterhin auf generischen Unterpfaden `plugin-sdk/*` oder in den plugin-lokalen Barrels `api.js` / `runtime-api.js` landen. Kompatibilitätshinweis: - Vermeiden Sie für neuen Code das Root-Barrel `openclaw/plugin-sdk`. -- Bevorzugen Sie zuerst die schmalen stabilen Primitive. Die neueren Subpaths für setup/pairing/reply/ +- Bevorzugen Sie zuerst die schmalen stabilen Primitiven. Die neueren Unterpfade für setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool sind der vorgesehene Vertrag für neue + allowlist/status/message-tool sind der beabsichtigte Vertrag für neue gebündelte und externe Plugin-Arbeit. - Target-Parsing/-Matching gehört auf `openclaw/plugin-sdk/channel-targets`. - Gates für Message-Actions und Helper für Reaktions-Message-IDs gehören auf + Zielparsing/-matching gehört auf `openclaw/plugin-sdk/channel-targets`. + Gates für Nachrichtenaktionen und Hilfsfunktionen für Reaktions-Nachrichten-IDs gehören auf `openclaw/plugin-sdk/channel-actions`. -- Extensionspezifische Helper-Barrels gebündelter Plugins sind standardmäßig nicht stabil. Wenn ein - Helper nur von einer gebündelten Extension benötigt wird, behalten Sie ihn hinter der - lokalen Naht `api.js` oder `runtime-api.js` der Extension, statt ihn nach +- Hilfs-Barrels für gebündelte erweiterungsspezifische Komponenten sind standardmäßig nicht stabil. Wenn eine + Hilfsfunktion nur von einer gebündelten Erweiterung benötigt wird, behalten Sie sie hinter der + lokalen Seam `api.js` oder `runtime-api.js` der Erweiterung, statt sie nach `openclaw/plugin-sdk/` zu befördern. -- Neue gemeinsame Helper-Seams sollten generisch sein, nicht kanalmarkiert. Gemeinsames Target- +- Neue gemeinsam genutzte Hilfs-Seams sollten generisch sein, nicht kanalgebrandet. Gemeinsames Ziel- Parsing gehört auf `openclaw/plugin-sdk/channel-targets`; kanalspezifische - Interna bleiben hinter dem lokalen `api.js` oder `runtime-api.js` des besitzenden Plugins. -- Fähigkeitsspezifische Subpaths wie `image-generation`, + Interna bleiben hinter der lokalen Seam `api.js` oder `runtime-api.js` des besitzenden Plugins. +- Fähigkeitsspezifische Unterpfade wie `image-generation`, `media-understanding` und `speech` existieren, weil gebündelte/native Plugins sie - heute verwenden. Ihre Existenz bedeutet für sich genommen nicht, dass jeder exportierte Helper ein + heute verwenden. Ihre Existenz bedeutet nicht automatisch, dass jede exportierte Hilfsfunktion ein langfristig eingefrorener externer Vertrag ist. -## Schemas für das Message-Tool +## Schemata des Nachrichtentools -Plugins sollten kanalspezifische Schema-Beiträge für `describeMessageTool(...)` -besitzen. Behalten Sie providerspezifische Felder im Plugin, nicht im gemeinsamen Kern. +Plugins sollten kanalspezifische Schemabeiträge für +`describeMessageTool(...)` besitzen. Behalten Sie providerspezifische Felder im Plugin, nicht im gemeinsamen Kern. -Für gemeinsame portable Schemafragmente verwenden Sie die generischen Helper, die über +Für gemeinsam nutzbare portable Schemafragmente verwenden Sie die generischen Hilfsfunktionen wieder, die über `openclaw/plugin-sdk/channel-actions` exportiert werden: -- `createMessageToolButtonsSchema()` für Payloads im Stil von Schaltflächengittern +- `createMessageToolButtonsSchema()` für Payloads im Stil eines Button-Rasters - `createMessageToolCardSchema()` für strukturierte Karten-Payloads Wenn eine Schemaform nur für einen Provider sinnvoll ist, definieren Sie sie im -eigenen Quellcode dieses Plugins, statt sie in das gemeinsame SDK zu befördern. +eigenen Quellcode dieses Plugins, statt sie in das gemeinsame SDK zu übernehmen. ## Auflösung von Kanalzielen -Kanal-Plugins sollten die kanalspezifische Zielsemantik besitzen. Halten Sie den gemeinsamen -Outbound-Host generisch und verwenden Sie die Oberfläche des Messaging-Adapters für Provider-Regeln: +Kanal-Plugins sollten kanalspezifische Zielsemantik besitzen. Halten Sie den gemeinsamen +ausgehenden Host generisch und verwenden Sie die Oberfläche des Messaging-Adapters für Provider-Regeln: - `messaging.inferTargetChatType({ to })` entscheidet, ob ein normalisiertes Ziel vor der Verzeichnissuche als `direct`, `group` oder `channel` behandelt werden soll. - `messaging.targetResolver.looksLikeId(raw, normalized)` teilt dem Kern mit, ob eine - Eingabe direkt in die Auflösung einer ID-ähnlichen Form übergehen soll, statt in die Verzeichnissuche. -- `messaging.targetResolver.resolveTarget(...)` ist der Plugin-Fallback, wenn - der Kern nach der Normalisierung oder nach einem Verzeichnis-Fehlschlag eine endgültige - providereigene Auflösung benötigt. -- `messaging.resolveOutboundSessionRoute(...)` besitzt die providerspezifische Konstruktion der Sitzungsroute, - sobald ein Ziel aufgelöst ist. + Eingabe direkt zur ID-ähnlichen Auflösung springen soll statt zur Verzeichnissuche. +- `messaging.targetResolver.resolveTarget(...)` ist das Plugin-Fallback, wenn + der Kern nach der Normalisierung oder nach einem Verzeichnis-Fehlschlag eine endgültige provider-eigene Auflösung braucht. +- `messaging.resolveOutboundSessionRoute(...)` besitzt die providerspezifische Sitzungs- + Routenbildung, sobald ein Ziel aufgelöst ist. Empfohlene Aufteilung: -- Verwenden Sie `inferTargetChatType` für Kategorientscheidungen, die vor - der Suche nach Peers/Gruppen stattfinden sollten. -- Verwenden Sie `looksLikeId` für Prüfungen wie „dies als explizite/native Ziel-ID behandeln“. -- Verwenden Sie `resolveTarget` für provider-spezifischen Normalisierungs-Fallback, nicht für - umfangreiche Verzeichnissuche. -- Behalten Sie native Provider-IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum-IDs +- Verwenden Sie `inferTargetChatType` für Kategorieentscheidungen, die vor der + Suche nach Peers/Gruppen getroffen werden sollten. +- Verwenden Sie `looksLikeId` für Prüfungen vom Typ „dies als explizite/native Ziel-ID behandeln“. +- Verwenden Sie `resolveTarget` für provider-spezifisches Normalisierungs-Fallback, nicht für eine + allgemeine Verzeichnissuche. +- Behalten Sie provider-native IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum-IDs innerhalb von `target`-Werten oder providerspezifischen Parametern, nicht in generischen SDK-Feldern. ## Konfigurationsgestützte Verzeichnisse Plugins, die Verzeichniseinträge aus der Konfiguration ableiten, sollten diese Logik im -Plugin behalten und die gemeinsamen Helper aus +Plugin behalten und die gemeinsamen Hilfsfunktionen aus `openclaw/plugin-sdk/directory-runtime` wiederverwenden. Verwenden Sie dies, wenn ein Kanal konfigurationsgestützte Peers/Gruppen benötigt, wie etwa: -- Allowlist-gesteuerte DM-Peers +- allowlist-gesteuerte DM-Peers - konfigurierte Kanal-/Gruppenzuordnungen - kontobezogene statische Verzeichnis-Fallbacks -Die gemeinsamen Helper in `directory-runtime` behandeln nur generische Operationen: +Die gemeinsamen Hilfsfunktionen in `directory-runtime` verarbeiten nur generische Operationen: -- Query-Filterung +- Abfragefilterung - Anwenden von Limits -- Helfer für Deduplizierung/Normalisierung -- Erstellen von `ChannelDirectoryEntry[]` +- Hilfsfunktionen für Deduplizierung/Normalisierung +- Aufbau von `ChannelDirectoryEntry[]` -Kanalspezifische Kontoinspektion und ID-Normalisierung sollten in der -Plugin-Implementierung verbleiben. +Kanalspezifische Kontoprüfung und ID-Normalisierung sollten in der +Plugin-Implementierung bleiben. ## Provider-Kataloge -Provider-Plugins können Modellkataloge für die Inferenz definieren mit +Provider-Plugins können Modellkataloge für Inferenz definieren mit `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` gibt dieselbe Form zurück, die OpenClaw in `models.providers` schreibt: -- `{ provider }` für einen Provider-Eintrag -- `{ providers }` für mehrere Provider-Einträge +- `{ provider }` für einen Providereintrag +- `{ providers }` für mehrere Providereinträge -Verwenden Sie `catalog`, wenn das Plugin providerspezifische Modell-IDs, Standardwerte für `baseUrl` +Verwenden Sie `catalog`, wenn das Plugin providerspezifische Modell-IDs, Standardwerte für Basis-URLs oder auth-gesteuerte Modellmetadaten besitzt. `catalog.order` steuert, wann der Katalog eines Plugins relativ zu den integrierten impliziten Providern von OpenClaw zusammengeführt wird: -- `simple`: einfache API-Key- oder env-gesteuerte Provider +- `simple`: einfache API-Schlüssel- oder umgebungsgetriebene Provider - `profile`: Provider, die erscheinen, wenn Auth-Profile vorhanden sind -- `paired`: Provider, die mehrere zusammengehörige Provider-Einträge synthetisieren -- `late`: letzter Durchlauf, nach anderen impliziten Providern +- `paired`: Provider, die mehrere zusammengehörige Providereinträge synthetisieren +- `late`: letzter Durchgang, nach anderen impliziten Providern Spätere Provider gewinnen bei Schlüsselkollisionen, sodass Plugins absichtlich einen -integrierten Provider-Eintrag mit derselben Provider-ID überschreiben können. +integrierten Providereintrag mit derselben Provider-ID überschreiben können. Kompatibilität: @@ -1312,39 +1319,39 @@ Kompatibilität: ## Schreibgeschützte Kanalinspektion -Wenn Ihr Plugin einen Kanal registriert, bevorzugen Sie die Implementierung von -`plugin.config.inspectAccount(cfg, accountId)` zusammen mit `resolveAccount(...)`. +Wenn Ihr Plugin einen Kanal registriert, sollten Sie bevorzugt +`plugin.config.inspectAccount(cfg, accountId)` neben `resolveAccount(...)` implementieren. Warum: -- `resolveAccount(...)` ist der Laufzeitpfad. Es darf davon ausgehen, dass Credentials - vollständig materialisiert sind, und bei fehlenden erforderlichen Secrets schnell fehlschlagen. +- `resolveAccount(...)` ist der Laufzeitpfad. Er darf davon ausgehen, dass Anmeldedaten + vollständig materialisiert sind, und kann schnell fehlschlagen, wenn erforderliche Secrets fehlen. - Schreibgeschützte Befehlspfade wie `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` und Doctor-/Konfigurations- - Reparaturabläufe sollten keine Laufzeit-Credentials materialisieren müssen, nur um - Konfiguration zu beschreiben. + `openclaw channels status`, `openclaw channels resolve` und doctor/config- + Reparaturabläufe sollten keine Laufzeit-Anmeldedaten materialisieren müssen, nur um + die Konfiguration zu beschreiben. Empfohlenes Verhalten von `inspectAccount(...)`: -- Nur beschreibenden Kontozustand zurückgeben. -- `enabled` und `configured` beibehalten. -- Felder zu Credential-Quelle/-Status einschließen, wenn relevant, z. B.: +- Geben Sie nur beschreibenden Kontozustand zurück. +- Behalten Sie `enabled` und `configured`. +- Schließen Sie relevante Felder für Quelle/Status von Anmeldedaten ein, zum Beispiel: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Sie müssen keine rohen Tokenwerte zurückgeben, nur um schreibgeschützte - Verfügbarkeit zu melden. Die Rückgabe von `tokenStatus: "available"` (und dem zugehörigen - Quellenfeld) reicht für statusartige Befehle aus. -- Verwenden Sie `configured_unavailable`, wenn ein Credential über SecretRef konfiguriert ist, im - aktuellen Befehlspfad aber nicht verfügbar ist. +- Sie müssen keine rohen Tokenwerte zurückgeben, nur um die schreibgeschützte + Verfügbarkeit zu melden. `tokenStatus: "available"` (und das passende Quellfeld) + reicht für statusartige Befehle aus. +- Verwenden Sie `configured_unavailable`, wenn Anmeldedaten über SecretRef konfiguriert sind, aber + im aktuellen Befehlspfad nicht verfügbar sind. Dadurch können schreibgeschützte Befehle „konfiguriert, aber in diesem Befehlspfad nicht verfügbar“ melden, statt abzustürzen oder das Konto fälschlich als nicht konfiguriert zu melden. ## Paket-Packs -Ein Plugin-Verzeichnis kann ein `package.json` mit `openclaw.extensions` enthalten: +Ein Plugin-Verzeichnis kann eine `package.json` mit `openclaw.extensions` enthalten: ```json { @@ -1356,10 +1363,10 @@ Ein Plugin-Verzeichnis kann ein `package.json` mit `openclaw.extensions` enthalt } ``` -Jeder Eintrag wird zu einem Plugin. Wenn das Pack mehrere Extensions auflistet, wird die Plugin-ID +Jeder Eintrag wird zu einem Plugin. Wenn das Pack mehrere Erweiterungen aufführt, wird die Plugin-ID zu `name/`. -Wenn Ihr Plugin npm-Abhängigkeiten importiert, installieren Sie sie in diesem Verzeichnis, damit +Wenn Ihr Plugin npm-Abhängigkeiten importiert, installieren Sie sie in diesem Verzeichnis, sodass `node_modules` verfügbar ist (`npm install` / `pnpm install`). Sicherheitsleitplanke: Jeder Eintrag in `openclaw.extensions` muss nach der Auflösung von Symlinks innerhalb des Plugin- @@ -1367,55 +1374,55 @@ Verzeichnisses bleiben. Einträge, die das Paketverzeichnis verlassen, werden abgelehnt. Sicherheitshinweis: `openclaw plugins install` installiert Plugin-Abhängigkeiten mit -`npm install --omit=dev --ignore-scripts` (keine Lifecycle-Skripte, keine Dev-Abhängigkeiten zur Laufzeit). Halten Sie Plugin-Abhängigkeits- -Bäume „reines JS/TS“ und vermeiden Sie Pakete, die `postinstall`-Builds benötigen. +`npm install --omit=dev --ignore-scripts` (keine Lifecycle-Skripte, keine Dev-Abhängigkeiten zur Laufzeit). Halten Sie die Bäume der Plugin-Abhängigkeiten +„reines JS/TS“ und vermeiden Sie Pakete, die `postinstall`-Builds benötigen. -Optional: `openclaw.setupEntry` kann auf ein leichtgewichtiges Nur-Setup-Modul verweisen. +Optional: `openclaw.setupEntry` kann auf ein leichtgewichtiges Modul nur für das Setup zeigen. Wenn OpenClaw Setup-Oberflächen für ein deaktiviertes Kanal-Plugin benötigt oder wenn ein Kanal-Plugin aktiviert, aber noch nicht konfiguriert ist, lädt es `setupEntry` -statt des vollständigen Plugin-Einstiegs. Das hält Start und Einrichtung leichter, -wenn Ihr Haupteinstieg außerdem Tools, Hooks oder anderen rein laufzeitbezogenen +anstelle des vollständigen Plugin-Einstiegspunkts. Das hält Start und Setup leichter, +wenn Ihr Haupteinstiegspunkt des Plugins zusätzlich Tools, Hooks oder anderen nur zur Laufzeit nötigen Code verdrahtet. Optional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -kann ein Kanal-Plugin während der Phase vor `listen` beim Gateway-Start ebenfalls in denselben `setupEntry`- -Pfad opt-in versetzen, selbst wenn der Kanal bereits konfiguriert ist. +kann ein Kanal-Plugin während der Pre-Listen-Startphase des Gateways in denselben `setupEntry`-Pfad aufnehmen, +selbst wenn der Kanal bereits konfiguriert ist. -Verwenden Sie dies nur, wenn `setupEntry` die Startoberfläche vollständig abdeckt, die -existieren muss, bevor das Gateway zu lauschen beginnt. In der Praxis bedeutet das, dass der -Setup-Einstieg jede kanaleigene Fähigkeit registrieren muss, von der der Start abhängt, wie z. B.: +Verwenden Sie dies nur, wenn `setupEntry` die Startoberfläche vollständig abdeckt, die vor dem +Beginn des Lauschen des Gateways existieren muss. In der Praxis bedeutet das, dass der Setup-Einstiegspunkt +jede kanal-eigene Fähigkeit registrieren muss, von der der Start abhängt, zum Beispiel: - die Kanalregistrierung selbst -- beliebige HTTP-Routen, die verfügbar sein müssen, bevor das Gateway zu lauschen beginnt -- beliebige Gateway-Methoden, Tools oder Services, die in diesem Zeitraum vorhanden sein müssen +- alle HTTP-Routen, die verfügbar sein müssen, bevor das Gateway beginnt zu lauschen +- alle Gateway-Methoden, Tools oder Dienste, die in diesem selben Zeitfenster existieren müssen -Wenn Ihr vollständiger Einstieg noch eine erforderliche Startfähigkeit besitzt, aktivieren Sie -dieses Flag nicht. Behalten Sie das Standardverhalten bei und lassen Sie OpenClaw den -vollständigen Einstieg während des Starts laden. +Wenn Ihr vollständiger Einstiegspunkt weiterhin eine erforderliche Startfähigkeit besitzt, aktivieren Sie +dieses Flag nicht. Behalten Sie das Standardverhalten für das Plugin bei und lassen Sie OpenClaw den +vollständigen Einstiegspunkt während des Starts laden. -Gebündelte Kanäle können auch nur-Setup-Helfer für Vertragsoberflächen veröffentlichen, die der Kern -abfragen kann, bevor die vollständige Kanal-Laufzeit geladen ist. Die aktuelle Oberfläche -für Setup-Promotion ist: +Gebündelte Kanäle können auch Hilfsfunktionen für die Vertragoberfläche nur für das Setup veröffentlichen, die der Kern +konsultieren kann, bevor die vollständige Kanal-Laufzeit geladen ist. Die aktuelle Oberfläche für Setup- +Promotion ist: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Der Kern nutzt diese Oberfläche, wenn er eine Legacy-Einzelkonto-Kanal- -Konfiguration in `channels..accounts.*` überführen muss, ohne den vollständigen Plugin-Einstieg zu laden. +Der Kern verwendet diese Oberfläche, wenn er eine Legacy-Einkonto-Kanal- +Konfiguration nach `channels..accounts.*` befördern muss, ohne den vollständigen Plugin-Einstiegspunkt zu laden. Matrix ist das aktuelle gebündelte Beispiel: Es verschiebt nur Auth-/Bootstrap-Schlüssel in ein -benanntes hochgestuftes Konto, wenn bereits benannte Konten existieren, und es kann -einen konfigurierten nicht-kanonischen Standard-Kontoschlüssel beibehalten, statt immer -`accounts.default` zu erstellen. +benanntes befördertes Konto, wenn bereits benannte Konten existieren, und es kann einen +konfigurierten nicht-kanonischen Standardschlüssel für das Standardkonto beibehalten, statt immer +`accounts.default` zu erzeugen. -Diese Setup-Patch-Adapter halten die Discovery gebündelter Vertragsoberflächen lazy. Die Importzeit -bleibt gering; die Promotionsoberfläche wird nur bei der ersten Verwendung geladen, statt beim Modulimport -erneut den Start gebündelter Kanäle zu betreten. +Diese Setup-Patch-Adapter halten die Erkennung der Vertragoberfläche gebündelter Komponenten träge. Die Import- +Zeit bleibt leicht; die Promotionsoberfläche wird erst bei der ersten Verwendung geladen, statt den Start +gebündelter Kanäle beim Modulimport erneut zu betreten. Wenn diese Startoberflächen Gateway-RPC-Methoden enthalten, behalten Sie sie auf einem -plugin-spezifischen Präfix. Kern-Admin-Namespaces (`config.*`, +pluginspezifischen Präfix. Kern-Admin-Namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) bleiben reserviert und werden immer -nach `operator.admin` aufgelöst, selbst wenn ein Plugin einen schmaleren Scope anfordert. +zu `operator.admin` aufgelöst, selbst wenn ein Plugin einen schmaleren Scope anfordert. Beispiel: @@ -1432,10 +1439,10 @@ Beispiel: } ``` -### Katalogmetadaten für Kanäle +### Metadaten des Kanalkatalogs -Kanal-Plugins können Setup-/Discovery-Metadaten über `openclaw.channel` und -Installationshinweise über `openclaw.install` bekanntgeben. Dadurch bleiben die Katalogdaten des Kerns datenfrei. +Kanal-Plugins können Setup-/Erkennungsmetadaten über `openclaw.channel` und +Installationshinweise über `openclaw.install` bekanntgeben. Dadurch bleibt der Kerndatenkatalog frei von Daten. Beispiel: @@ -1463,41 +1470,41 @@ Beispiel: } ``` -Nützliche Felder in `openclaw.channel` über das Minimalbeispiel hinaus: +Nützliche Felder von `openclaw.channel` über das Minimalbeispiel hinaus: -- `detailLabel`: sekundäres Label für reichhaltigere Katalog-/Statusoberflächen +- `detailLabel`: sekundäres Label für umfassendere Katalog-/Statusoberflächen - `docsLabel`: Linktext für den Dokumentationslink überschreiben -- `preferOver`: Plugin-/Kanal-IDs niedrigerer Priorität, die dieser Katalogeintrag übertreffen sollte -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: Steuerung von Texten auf Auswahloberflächen -- `markdownCapable`: markiert den Kanal für Entscheidungen zur Outbound-Formatierung als Markdown-fähig -- `exposure.configured`: blendet den Kanal aus Oberflächen mit konfigurierten Kanälen aus, wenn auf `false` gesetzt -- `exposure.setup`: blendet den Kanal aus interaktiven Setup-/Configure-Pickern aus, wenn auf `false` gesetzt -- `exposure.docs`: markiert den Kanal für Dokumentations-Navigationsoberflächen als intern/privat -- `showConfigured` / `showInSetup`: Legacy-Aliase werden aus Kompatibilitätsgründen weiterhin akzeptiert; bevorzugen Sie `exposure` -- `quickstartAllowFrom`: nimmt den Kanal in den Standard-Quickstart-Ablauf `allowFrom` auf -- `forceAccountBinding`: explizite Kontobindung erzwingen, selbst wenn nur ein Konto existiert -- `preferSessionLookupForAnnounceTarget`: Sitzungs-Lookup bei der Auflösung von Ankündigungszielen bevorzugen +- `preferOver`: IDs von Plugins/Kanälen mit niedrigerer Priorität, die dieser Katalogeintrag übertreffen soll +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: Steuerelemente für Text auf Auswahloberflächen +- `markdownCapable`: markiert den Kanal als Markdown-fähig für Entscheidungen zur ausgehenden Formatierung +- `exposure.configured`: blendet den Kanal in Oberflächen zur Auflistung konfigurierter Kanäle aus, wenn auf `false` gesetzt +- `exposure.setup`: blendet den Kanal in interaktiven Setup-/Konfigurations-Auswahllisten aus, wenn auf `false` gesetzt +- `exposure.docs`: markiert den Kanal für Oberflächen der Dokumentationsnavigation als intern/privat +- `showConfigured` / `showInSetup`: Legacy-Aliasse werden aus Kompatibilitätsgründen weiterhin akzeptiert; bevorzugen Sie `exposure` +- `quickstartAllowFrom`: nimmt den Kanal in den standardmäßigen Quickstart-Flow `allowFrom` auf +- `forceAccountBinding`: erzwingt explizite Kontobindung, selbst wenn nur ein Konto existiert +- `preferSessionLookupForAnnounceTarget`: bevorzugt die Sitzungssuche beim Auflösen von Ankündigungszielen -OpenClaw kann auch **externe Kanalkataloge** zusammenführen (zum Beispiel einen Export aus einer MPM- +OpenClaw kann auch **externe Kanalkataloge** zusammenführen (zum Beispiel einen Export einer MPM- Registry). Legen Sie eine JSON-Datei an einem der folgenden Orte ab: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -Oder setzen Sie `OPENCLAW_PLUGIN_CATALOG_PATHS` (oder `OPENCLAW_MPM_CATALOG_PATHS`) auf +Oder verweisen Sie mit `OPENCLAW_PLUGIN_CATALOG_PATHS` (oder `OPENCLAW_MPM_CATALOG_PATHS`) auf eine oder mehrere JSON-Dateien (durch Komma/Semikolon/`PATH` getrennt). Jede Datei sollte -`{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }` enthalten. Der Parser akzeptiert auch `"packages"` oder `"plugins"` als Legacy-Aliase für den Schlüssel `"entries"`. +`{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }` enthalten. Der Parser akzeptiert außerdem `"packages"` oder `"plugins"` als Legacy-Aliasse für den Schlüssel `"entries"`. -## Context-Engine-Plugins +## Plugins für die Kontext-Engine -Context-Engine-Plugins besitzen die Orchestrierung des Sitzungs-Kontexts für Ingest, Zusammenstellung -und Kompaktierung. Registrieren Sie sie aus Ihrem Plugin mit +Plugins für die Kontext-Engine besitzen die Orchestrierung des Sitzungskontexts für Ingest, Zusammenstellung +und Kompaktierung. Registrieren Sie sie in Ihrem Plugin mit `api.registerContextEngine(id, factory)` und wählen Sie dann die aktive Engine mit -`plugins.slots.contextEngine`. +`plugins.slots.contextEngine` aus. -Verwenden Sie dies, wenn Ihr Plugin die Standard- -Context-Pipeline ersetzen oder erweitern muss, statt nur Memory Search oder Hooks hinzuzufügen. +Verwenden Sie dies, wenn Ihr Plugin die Standard-Kontext- +Pipeline ersetzen oder erweitern muss, statt nur Erinnerungssuche oder Hooks hinzuzufügen. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1525,8 +1532,8 @@ export default function (api) { } ``` -Wenn Ihre Engine den Kompaktierungsalgorithmus **nicht** besitzt, implementieren Sie `compact()` -trotzdem und delegieren Sie ihn explizit: +Wenn Ihre Engine den Kompaktierungsalgorithmus **nicht** besitzt, behalten Sie `compact()` +implementiert und delegieren Sie ihn explizit: ```ts import { @@ -1564,43 +1571,43 @@ export default function (api) { ## Eine neue Fähigkeit hinzufügen Wenn ein Plugin Verhalten benötigt, das nicht in die aktuelle API passt, umgehen Sie -das Plugin-System nicht mit einem privaten Reach-in. Fügen Sie die fehlende Fähigkeit hinzu. +das Plugin-System nicht mit einem privaten Zugriff. Fügen Sie die fehlende Fähigkeit hinzu. Empfohlene Reihenfolge: 1. den Kernvertrag definieren - Entscheiden Sie, welches gemeinsame Verhalten der Kern besitzen soll: Richtlinie, Fallback, Konfigurations-Merge, - Lebenszyklus, kanalorientierte Semantik und Form des Laufzeit-Helfers. + Entscheiden Sie, welches gemeinsame Verhalten der Kern besitzen soll: Richtlinie, Fallback, Zusammenführung von Konfigurationen, + Lebenszyklus, kanalseitige Semantik und Form der Laufzeit-Hilfsfunktion. 2. typisierte Oberflächen für Plugin-Registrierung/Laufzeit hinzufügen - Erweitern Sie `OpenClawPluginApi` und/oder `api.runtime` um die kleinste nützliche + Erweitern Sie `OpenClawPluginApi` und/oder `api.runtime` um die kleinste sinnvolle typisierte Fähigkeitsoberfläche. -3. Kern + Kanal-/Feature-Konsumenten verdrahten - Kanäle und Feature-Plugins sollten die neue Fähigkeit über den Kern konsumieren, - nicht durch direkten Import einer Anbieterimplementierung. +3. Kern + Kanal-/Feature-Konsumenten anbinden + Kanäle und Feature-Plugins sollten die neue Fähigkeit über den Kern nutzen, + nicht durch direktes Importieren einer Anbieterimplementierung. 4. Anbieterimplementierungen registrieren - Anbieter-Plugins registrieren dann ihre Backends gegen die Fähigkeit. + Anbieter-Plugins registrieren dann ihre Backends für diese Fähigkeit. 5. Vertragsabdeckung hinzufügen - Fügen Sie Tests hinzu, damit Ownership und Registrierungsform im Laufe der Zeit explizit bleiben. + Fügen Sie Tests hinzu, damit Eigentümerschaft und Registrierungsform über die Zeit explizit bleiben. -So bleibt OpenClaw meinungsstark, ohne an die Sichtweise eines einzelnen -Providers hart gekoppelt zu werden. Eine konkrete Dateicheckliste und ein ausgearbeitetes Beispiel finden Sie im [Capability Cookbook](/de/plugins/architecture). +So bleibt OpenClaw meinungsstark, ohne fest auf das Weltbild eines einzelnen +Providers codiert zu werden. Ein konkretes Datei-Checklisten- und Beispiel finden Sie im [Capability Cookbook](/de/plugins/architecture). ### Checkliste für Fähigkeiten -Wenn Sie eine neue Fähigkeit hinzufügen, sollte die Implementierung in der Regel diese +Wenn Sie eine neue Fähigkeit hinzufügen, sollte die Implementierung normalerweise diese Oberflächen gemeinsam berühren: - Kernvertragstypen in `src//types.ts` -- Kern-Runner/Laufzeit-Helper in `src//runtime.ts` +- Kern-Runner/Laufzeit-Hilfsfunktion in `src//runtime.ts` - Plugin-API-Registrierungsoberfläche in `src/plugins/types.ts` -- Verdrahtung der Plugin-Registry in `src/plugins/registry.ts` -- Bereitstellung der Plugin-Laufzeit in `src/plugins/runtime/*`, wenn Feature-/Kanal- - Plugins sie konsumieren müssen -- Capture-/Test-Helper in `src/test-utils/plugin-registration.ts` -- Ownership-/Vertragsprüfungen in `src/plugins/contracts/registry.ts` +- Plugin-Registry-Verdrahtung in `src/plugins/registry.ts` +- Plugin-Laufzeitfreigabe in `src/plugins/runtime/*`, wenn Feature-/Kanal- + Plugins sie nutzen müssen +- Erfassungs-/Test-Hilfsfunktionen in `src/test-utils/plugin-registration.ts` +- Assertions zu Eigentümerschaft/Verträgen in `src/plugins/contracts/registry.ts` - Operator-/Plugin-Dokumentation in `docs/` -Wenn eine dieser Oberflächen fehlt, ist das in der Regel ein Zeichen dafür, dass die Fähigkeit +Wenn eine dieser Oberflächen fehlt, ist das normalerweise ein Zeichen dafür, dass die Fähigkeit noch nicht vollständig integriert ist. ### Vorlage für Fähigkeiten @@ -1637,9 +1644,9 @@ Muster für Vertragstests: expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Das hält die Regel einfach: +Damit bleibt die Regel einfach: - der Kern besitzt den Fähigkeitsvertrag + die Orchestrierung - Anbieter-Plugins besitzen Anbieterimplementierungen -- Feature-/Kanal-Plugins konsumieren Laufzeit-Helfer -- Vertragstests halten Ownership explizit +- Feature-/Kanal-Plugins nutzen Laufzeit-Hilfsfunktionen +- Vertragstests halten Eigentümerschaft explizit diff --git a/docs/de/plugins/manifest.md b/docs/de/plugins/manifest.md index 75acef89d..80f6e79e2 100644 --- a/docs/de/plugins/manifest.md +++ b/docs/de/plugins/manifest.md @@ -2,13 +2,13 @@ read_when: - Sie erstellen ein OpenClaw-Plugin - Sie müssen ein Plugin-Konfigurationsschema bereitstellen oder Fehler bei der Plugin-Validierung beheben -summary: Plugin-Manifest- + JSON-Schema-Anforderungen (strikte Konfigurationsvalidierung) +summary: Plugin-Manifest- und JSON-Schema-Anforderungen (strikte Konfigurationsvalidierung) title: Plugin-Manifest x-i18n: - generated_at: "2026-04-11T02:46:08Z" + generated_at: "2026-04-11T15:15:59Z" model: gpt-5.4 provider: openai - source_hash: 6b254c121d1eb5ea19adbd4148243cf47339c960442ab1ca0e0bfd52e0154c88 + source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 source_path: plugins/manifest.md workflow: 15 --- @@ -22,24 +22,24 @@ Kompatible Bundle-Layouts finden Sie unter [Plugin-Bundles](/de/plugins/bundles) Kompatible Bundle-Formate verwenden andere Manifestdateien: - Codex-Bundle: `.codex-plugin/plugin.json` -- Claude-Bundle: `.claude-plugin/plugin.json` oder das Standard-Layout für Claude-Komponenten - ohne Manifest +- Claude-Bundle: `.claude-plugin/plugin.json` oder das standardmäßige Claude-Komponenten- + Layout ohne Manifest - 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 `openclaw.plugin.json`-Schema validiert. Für kompatible Bundles liest OpenClaw derzeit Bundle-Metadaten sowie deklarierte -Skill-Roots, Claude-Command-Roots, Standardwerte aus `settings.json` des Claude-Bundles, -Claude-Bundle-LSP-Standardwerte und unterstützte Hook-Packs, wenn das Layout den -Laufzeiterwartungen von OpenClaw entspricht. +Skill-Stammverzeichnisse, Claude-Befehls-Stammverzeichnisse, Claude-Bundle- +`settings.json`-Standardwerte, Claude-Bundle-LSP-Standardwerte und unterstützte Hook-Pakete, +wenn das Layout den Laufzeiterwartungen von OpenClaw entspricht. -Jedes native OpenClaw-Plugin **muss** im **Plugin-Root** eine Datei `openclaw.plugin.json` -bereitstellen. OpenClaw verwendet dieses Manifest, um die Konfiguration zu validieren, -**ohne Plugin-Code auszuführen**. Fehlende oder ungültige Manifestdateien werden als +Jedes native OpenClaw-Plugin **muss** eine `openclaw.plugin.json`-Datei 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. -Die vollständige Anleitung zum Plugin-System finden Sie unter: [Plugins](/de/tools/plugin). +Den vollständigen Leitfaden zum Plugin-System finden Sie unter: [Plugins](/de/tools/plugin). Zum nativen Fähigkeitsmodell und zur aktuellen Anleitung für externe Kompatibilität: [Fähigkeitsmodell](/de/plugins/architecture#public-capability-model). @@ -52,21 +52,22 @@ Verwenden Sie sie für: - Plugin-Identität - Konfigurationsvalidierung -- Auth- und Onboarding-Metadaten, die verfügbar sein sollen, ohne die Plugin- +- Authentifizierungs- 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 lädt -- Kurzschreibweise-Metadaten zur Eigentümerschaft von Modellfamilien, die das - Plugin automatisch aktivieren sollen, bevor die Laufzeit lädt -- statische Snapshots der Fähigkeitseigentümerschaft, die für gebündeltes Compat-Wiring und - Vertragsabdeckung verwendet werden -- kanalspezifische Konfigurationsmetadaten, die in Katalog- und Validierungs- - Oberflächen zusammengeführt werden sollen, ohne die Laufzeit zu laden -- Hinweise für die Konfigurations-UI +- kostengünstige Aktivierungshinweise, die von Control-Plane-Oberflächen vor dem Laden der Laufzeit geprüft werden können +- kostengünstige Einrichtungsdeskriptoren, die von Einrichtungs-/Onboarding-Oberflächen vor dem Laden der Laufzeit geprüft werden können +- Alias- und Auto-Aktivierungs-Metadaten, die aufgelöst werden sollen, bevor die Plugin-Laufzeit geladen wird +- Kurzform-Metadaten zur Eigentümerschaft von Modellfamilien, die das + Plugin vor dem Laden der Laufzeit automatisch aktivieren sollen +- statische Snapshots der Fähigkeitszuordnung, die für gebündelte Kompatibilitätsverdrahtung und Vertragsabdeckung verwendet werden +- kanalspezifische Konfigurationsmetadaten, die in Katalog- und Validierungsoberflächen + zusammengeführt werden sollen, ohne die Laufzeit zu laden +- Hinweise für die Konfigurations-Benutzeroberfläche Verwenden Sie sie nicht für: -- das Registrieren von Laufzeitverhalten -- das Deklarieren von Code-Entrypoints +- Registrierung von Laufzeitverhalten +- Deklaration von Code-Einstiegspunkten - npm-Installationsmetadaten Diese gehören in Ihren Plugin-Code und in `package.json`. @@ -142,60 +143,62 @@ Diese gehören in Ihren Plugin-Code und in `package.json`. ## Referenz der Felder auf oberster Ebene -| Feld | Erforderlich | Typ | Bedeutung | -| ----------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Ja | `string` | Kanonische Plugin-ID. Dies ist die ID, die in `plugins.entries.` verwendet wird. | -| `configSchema` | Ja | `object` | Inline-JSON-Schema für die Konfiguration dieses Plugins. | -| `enabledByDefault` | Nein | `true` | 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 Modell-Referenzen 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. Verwendet für Erkennung und Konfigurationsvalidierung. | -| `providers` | Nein | `string[]` | Provider-IDs, die diesem Plugin gehören. | -| `modelSupport` | Nein | `object` | Manifest-eigene Kurzschreibweise-Metadaten für 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. Verwendet für die Autoaktivierung beim Start aus expliziten Konfigurationsreferenzen. | -| `commandAliases` | Nein | `object[]` | Befehlsnamen, die diesem Plugin gehören und pluginbewusste Konfigurations- und CLI-Diagnosen erzeugen sollen, bevor die Laufzeit lädt. | -| `providerAuthEnvVars` | Nein | `Record` | Günstige Env-Metadaten für Provider-Auth, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. | -| `providerAuthAliases` | Nein | `Record` | Provider-IDs, die für die Auth-Suche eine andere Provider-ID wiederverwenden sollen, z. B. ein Coding-Provider, der denselben API-Schlüssel und dieselben Auth-Profile wie der Basis-Provider verwendet. | -| `channelEnvVars` | Nein | `Record` | Günstige Env-Metadaten für Kanäle, die OpenClaw prüfen kann, ohne Plugin-Code zu laden. Verwenden Sie dies für env-gesteuertes Kanal-Setup oder Auth-Oberflächen, die generische Start-/Konfigurationshelfer sehen sollen. | -| `providerAuthChoices` | Nein | `object[]` | Günstige Metadaten für Auth-Auswahlmöglichkeiten für Onboarding-Picker, bevorzugte Provider-Auflösung und einfache CLI-Flag-Verdrahtung. | -| `contracts` | Nein | `object` | Statischer Snapshot gebündelter Fähigkeiten für Sprache, Echtzeit-Transkription, Echtzeit-Stimme, Medienverständnis, Bildgenerierung, Musikgenerierung, Videogenerierung, Web-Fetch, Websuche und Tool-Eigentümerschaft. | -| `channelConfigs` | Nein | `Record` | Manifest-eigene Metadaten zur Kanalkonfiguration, die vor dem Laden der Laufzeit in Erkennungs- und Validierungsoberflächen zusammengeführt werden. | -| `skills` | Nein | `string[]` | Skill-Verzeichnisse, die relativ zum Plugin-Root geladen werden sollen. | -| `name` | Nein | `string` | Menschlich lesbarer Plugin-Name. | -| `description` | Nein | `string` | Kurze Zusammenfassung, die in Plugin-Oberflächen angezeigt wird. | -| `version` | Nein | `string` | Informative Plugin-Version. | -| `uiHints` | Nein | `Record` | UI-Beschriftungen, Platzhalter und Hinweise zur Sensitivität für Konfigurationsfelder. | +| Feld | Erforderlich | Typ | Bedeutung | +| ----------------------------------- | ------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Ja | `string` | Kanonische Plugin-ID. Dies ist die ID, die in `plugins.entries.` verwendet wird. | +| `configSchema` | Ja | `object` | Inline-JSON-Schema für die Konfiguration dieses Plugins. | +| `enabledByDefault` | Nein | `true` | Kennzeichnet ein gebündeltes Plugin als standardmäßig aktiviert. Lassen Sie das Feld weg oder setzen Sie einen anderen Wert als `true`, damit das Plugin standardmäßig deaktiviert bleibt. | +| `legacyPluginIds` | Nein | `string[]` | Veraltete IDs, die auf diese kanonische Plugin-ID normalisiert werden. | +| `autoEnableWhenConfiguredProviders` | Nein | `string[]` | Provider-IDs, die dieses Plugin automatisch aktivieren sollen, wenn Authentifizierung, Konfiguration oder Modellreferenzen sie erwähnen. | +| `kind` | Nein | `"memory"` \| `"context-engine"` | Deklariert einen exklusiven Plugin-Typ, der 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` | Dem Manifest gehörende Kurzform-Metadaten zu Modellfamilien, die verwendet werden, um das Plugin vor der Laufzeit automatisch zu laden. | +| `cliBackends` | Nein | `string[]` | CLI-Inferenz-Backend-IDs, die diesem Plugin gehören. Wird für die automatische Aktivierung beim Start aus expliziten Konfigurationsreferenzen verwendet. | +| `commandAliases` | Nein | `object[]` | Befehlsnamen, die diesem Plugin gehören und noch vor dem Laden der Laufzeit pluginbewusste Konfigurations- und CLI-Diagnosen erzeugen sollen. | +| `providerAuthEnvVars` | Nein | `Record` | Kostengünstige Umgebungsvariablen-Metadaten für Provider-Authentifizierung, die OpenClaw ohne Laden von Plugin-Code prüfen kann. | +| `providerAuthAliases` | Nein | `Record` | Provider-IDs, die für die Authentifizierung eine andere Provider-ID wiederverwenden sollen, zum Beispiel ein Coding-Provider, der den API-Schlüssel und die Authentifizierungsprofile des Basis-Providers teilt. | +| `channelEnvVars` | Nein | `Record` | Kostengünstige Umgebungsvariablen-Metadaten für Kanäle, die OpenClaw ohne Laden von Plugin-Code prüfen kann. Verwenden Sie dies für env-gesteuerte Kanaleinrichtung oder Authentifizierungsoberflächen, die generische Start-/Konfigurationshilfen sehen sollen. | +| `providerAuthChoices` | Nein | `object[]` | Kostengünstige Metadaten zu Authentifizierungsoptionen für Onboarding-Auswahlen, bevorzugte Provider-Auflösung und einfache Verdrahtung von CLI-Flags. | +| `activation` | Nein | `object` | Kostengünstige Aktivierungshinweise für provider-, befehls-, kanal-, routing- und fähigkeitsausgelöstes Laden. Nur Metadaten; das tatsächliche Verhalten bleibt Eigentum der Plugin-Laufzeit. | +| `setup` | Nein | `object` | Kostengünstige Einrichtungs-/Onboarding-Deskriptoren, die von Erkennungs- und Einrichtungsoberflächen geprüft werden können, ohne die Plugin-Laufzeit zu laden. | +| `contracts` | Nein | `object` | Statischer Snapshot gebündelter Fähigkeiten für speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, Websuche und Tool-Eigentümerschaft. | +| `channelConfigs` | Nein | `Record` | Dem Manifest gehörende Kanal-Konfigurationsmetadaten, die vor dem Laden der Laufzeit in Erkennungs- und Validierungsoberflächen zusammengeführt werden. | +| `skills` | Nein | `string[]` | Zu ladende Skills-Verzeichnisse, relativ zum Plugin-Stammverzeichnis. | +| `name` | Nein | `string` | Lesbarer Plugin-Name. | +| `description` | Nein | `string` | Kurze Zusammenfassung, die in Plugin-Oberflächen angezeigt wird. | +| `version` | Nein | `string` | Informative Plugin-Version. | +| `uiHints` | Nein | `Record` | UI-Beschriftungen, Platzhalter und Hinweise zur Vertraulichkeit für Konfigurationsfelder. | -## Referenz zu `providerAuthChoices` +## Referenz für `providerAuthChoices` -Jeder Eintrag in `providerAuthChoices` beschreibt eine Onboarding- oder Auth-Auswahl. +Jeder Eintrag in `providerAuthChoices` beschreibt eine Onboarding- oder Authentifizierungsoption. OpenClaw liest dies, bevor die Provider-Laufzeit geladen wird. | Feld | Erforderlich | Typ | Bedeutung | | --------------------- | ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `provider` | Ja | `string` | Provider-ID, zu der diese Auswahl gehört. | -| `method` | Ja | `string` | ID der Auth-Methode, an die weitergeleitet 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, fällt OpenClaw auf `choiceId` zurück. | -| `choiceHint` | Nein | `string` | Kurzer Hilfetext für den Picker. | -| `assistantPriority` | Nein | `number` | Niedrigere Werte werden in assistentengesteuerten interaktiven Pickern früher sortiert. | -| `assistantVisibility` | Nein | `"visible"` \| `"manual-only"` | Blendet die Auswahl in Assistenten-Pickern aus, erlaubt aber weiterhin die manuelle Auswahl per CLI. | -| `deprecatedChoiceIds` | Nein | `string[]` | Legacy-IDs von Auswahlmöglichkeiten, die Benutzer auf diese Ersatzauswahl umleiten sollen. | -| `groupId` | Nein | `string` | Optionale Gruppen-ID zum Gruppieren verwandter Auswahlmöglichkeiten. | -| `groupLabel` | Nein | `string` | Benutzerseitige Beschriftung für diese Gruppe. | +| `provider` | Ja | `string` | Provider-ID, zu der diese Option gehört. | +| `method` | Ja | `string` | ID der Authentifizierungsmethode, an die weitergeleitet werden soll. | +| `choiceId` | Ja | `string` | Stabile ID der Authentifizierungsoption, die von Onboarding- und CLI-Abläufen verwendet wird. | +| `choiceLabel` | Nein | `string` | Benutzerseitige Bezeichnung. Wenn sie weggelassen wird, verwendet OpenClaw stattdessen `choiceId`. | +| `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 Option in Assistenten-Auswahlen aus, erlaubt aber weiterhin die manuelle Auswahl über die CLI. | +| `deprecatedChoiceIds` | Nein | `string[]` | Veraltete Options-IDs, die Benutzer zu dieser Ersatzoption umleiten sollen. | +| `groupId` | Nein | `string` | Optionale Gruppen-ID zum Gruppieren verwandter Optionen. | +| `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 nur einem Flag. | +| `optionKey` | Nein | `string` | Interner Optionsschlüssel für einfache Authentifizierungsabläufe mit nur einem Flag. | | `cliFlag` | Nein | `string` | Name des CLI-Flags, z. B. `--openrouter-api-key`. | -| `cliOption` | Nein | `string` | Vollständige Form der CLI-Option, z. B. `--openrouter-api-key `. | -| `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 Standardwert `["text-inference"]`. | +| `cliOption` | Nein | `string` | Vollständige Form der CLI-Option, z. B. `--openrouter-api-key `. | +| `cliDescription` | Nein | `string` | Beschreibung, die in der CLI-Hilfe verwendet wird. | +| `onboardingScopes` | Nein | `Array<"text-inference" \| "image-generation">` | In welchen Onboarding-Oberflächen diese Option erscheinen soll. Wenn weggelassen, ist der Standardwert `["text-inference"]`. | -## Referenz zu `commandAliases` +## Referenz für `commandAliases` Verwenden Sie `commandAliases`, wenn ein Plugin einen Laufzeit-Befehlsnamen besitzt, den Benutzer -möglicherweise fälschlicherweise in `plugins.allow` eintragen oder als CLI-Befehl auf Root-Ebene ausführen möchten. OpenClaw -verwendet diese Metadaten für Diagnosen, ohne den Laufzeitcode des Plugins zu importieren. +versehentlich in `plugins.allow` eintragen oder als CLI-Stammbefehl ausführen +möchten. OpenClaw verwendet diese Metadaten für Diagnosen, ohne Plugin-Laufzeitcode zu importieren. ```json { @@ -209,22 +212,93 @@ verwendet diese Metadaten für Diagnosen, ohne den Laufzeitcode des Plugins zu i } ``` -| Feld | Erforderlich | Typ | Bedeutung | -| ------------ | ------------ | ----------------- | -------------------------------------------------------------------------------- | -| `name` | Ja | `string` | Befehlsname, der zu diesem Plugin gehört. | -| `kind` | Nein | `"runtime-slash"` | Kennzeichnet den Alias als Chat-Slash-Befehl statt als CLI-Befehl auf Root-Ebene. | -| `cliCommand` | Nein | `string` | Zugehöriger CLI-Befehl auf Root-Ebene, der für CLI-Operationen vorgeschlagen werden soll, falls vorhanden. | +| Feld | Erforderlich | Typ | Bedeutung | +| ------------ | ------------ | ----------------- | ------------------------------------------------------------------------- | +| `name` | Ja | `string` | Befehlsname, der zu diesem Plugin gehört. | +| `kind` | Nein | `"runtime-slash"` | Kennzeichnet den Alias als Chat-Slash-Befehl statt als CLI-Stammbefehl. | +| `cliCommand` | Nein | `string` | Zugehöriger CLI-Stammbefehl, der für CLI-Vorgänge empfohlen werden kann, falls vorhanden. | -## Referenz zu `uiHints` +## Referenz für `activation` -`uiHints` ist eine Zuordnung von Konfigurationsfeldnamen zu kleinen Render-Hinweisen. +Verwenden Sie `activation`, wenn das Plugin kostengünstig deklarieren kann, welche Control-Plane-Ereignisse +es später aktivieren sollen. + +Dieser Block enthält nur Metadaten. Er registriert kein Laufzeitverhalten und +ersetzt nicht `register(...)`, `setupEntry` oder andere Laufzeit-/Plugin-Einstiegspunkte. + +```json +{ + "activation": { + "onProviders": ["openai"], + "onCommands": ["models"], + "onChannels": ["web"], + "onRoutes": ["gateway-webhook"], + "onCapabilities": ["provider", "tool"] + } +} +``` + +| Feld | Erforderlich | Typ | Bedeutung | +| ---------------- | ------------ | ---------------------------------------------------- | ----------------------------------------------------------------- | +| `onProviders` | Nein | `string[]` | Provider-IDs, die dieses Plugin bei Anforderung aktivieren sollen. | +| `onCommands` | Nein | `string[]` | Befehls-IDs, die dieses Plugin aktivieren sollen. | +| `onChannels` | Nein | `string[]` | Kanal-IDs, die dieses Plugin aktivieren sollen. | +| `onRoutes` | Nein | `string[]` | Routenarten, die dieses Plugin aktivieren sollen. | +| `onCapabilities` | Nein | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Allgemeine Fähigkeitshinweise, die bei der Aktivierungsplanung der Control Plane verwendet werden. | + +## Referenz für `setup` + +Verwenden Sie `setup`, wenn Einrichtungs- und Onboarding-Oberflächen kostengünstige, dem Plugin gehörende Metadaten +benötigen, bevor die Laufzeit geladen wird. + +```json +{ + "setup": { + "providers": [ + { + "id": "openai", + "authMethods": ["api-key"], + "envVars": ["OPENAI_API_KEY"] + } + ], + "cliBackends": ["openai-cli"], + "configMigrations": ["legacy-openai-auth"], + "requiresRuntime": false + } +} +``` + +Das Top-Level-Feld `cliBackends` bleibt gültig und beschreibt weiterhin CLI-Inferenz- +Backends. `setup.cliBackends` ist die einrichtungsspezifische Deskriptoroberfläche für +Control-Plane-/Einrichtungsabläufe, die nur Metadaten bleiben soll. + +### Referenz für `setup.providers` + +| Feld | Erforderlich | Typ | Bedeutung | +| ------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------- | +| `id` | Ja | `string` | Provider-ID, die während der Einrichtung oder des Onboardings bereitgestellt wird. | +| `authMethods` | Nein | `string[]` | IDs von Einrichtungs-/Authentifizierungsmethoden, die dieser Provider ohne vollständige Laufzeit unterstützt. | +| `envVars` | Nein | `string[]` | Umgebungsvariablen, die generische Einrichtungs-/Statusoberflächen prüfen können, bevor die Plugin-Laufzeit geladen wird. | + +### `setup`-Felder + +| Feld | Erforderlich | Typ | Bedeutung | +| ------------------ | ------------ | ---------- | --------------------------------------------------------------------------- | +| `providers` | Nein | `object[]` | Provider-Einrichtungsdeskriptoren, die während Einrichtung und Onboarding bereitgestellt werden. | +| `cliBackends` | Nein | `string[]` | Backend-IDs zur Einrichtungszeit, die ohne vollständige Laufzeitaktivierung verfügbar sind. | +| `configMigrations` | Nein | `string[]` | IDs von Konfigurationsmigrationen, die der Einrichtungsoberfläche dieses Plugins gehören. | +| `requiresRuntime` | Nein | `boolean` | Ob die Einrichtung nach dem Nachschlagen des Deskriptors weiterhin die Ausführung der Plugin-Laufzeit erfordert. | + +## Referenz für `uiHints` + +`uiHints` ist eine Zuordnung von Konfigurationsfeldnamen zu kleinen Darstellungshinweisen. ```json { "uiHints": { "apiKey": { - "label": "API-Schlüssel", - "help": "Wird für OpenRouter-Anfragen verwendet", + "label": "API key", + "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -234,19 +308,19 @@ verwendet diese Metadaten für Diagnosen, ohne den Laufzeitcode des Plugins zu i Jeder Feldhinweis kann Folgendes enthalten: -| Feld | Typ | Bedeutung | -| ------------- | ---------- | ------------------------------------------ | -| `label` | `string` | Benutzerseitige Feldbezeichnung. | -| `help` | `string` | Kurzer Hilfetext. | -| `tags` | `string[]` | Optionale UI-Tags. | -| `advanced` | `boolean` | Kennzeichnet das Feld als erweitert. | +| Feld | Typ | Bedeutung | +| ------------- | ---------- | ----------------------------------------- | +| `label` | `string` | Benutzerseitige Feldbezeichnung. | +| `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. | +| `placeholder` | `string` | Platzhaltertext für Formulareingaben. | -## Referenz zu `contracts` +## Referenz für `contracts` -Verwenden Sie `contracts` nur für statische Metadaten zur Fähigkeitseigentümerschaft, die OpenClaw -lesen kann, ohne die Plugin-Laufzeit zu importieren. +Verwenden Sie `contracts` nur für statische Metadaten zur Fähigkeitszuordnung, die OpenClaw +ohne Import der Plugin-Laufzeit lesen kann. ```json { @@ -266,22 +340,22 @@ lesen kann, ohne die Plugin-Laufzeit zu importieren. Jede Liste ist optional: -| Feld | Typ | Bedeutung | -| -------------------------------- | ---------- | --------------------------------------------------------------- | -| `speechProviders` | `string[]` | Sprach-Provider-IDs, die diesem Plugin gehören. | -| `realtimeTranscriptionProviders` | `string[]` | Provider-IDs für Echtzeit-Transkription, die diesem Plugin gehören. | -| `realtimeVoiceProviders` | `string[]` | Provider-IDs für Echtzeit-Stimme, die diesem Plugin gehören. | -| `mediaUnderstandingProviders` | `string[]` | Provider-IDs für Medienverständnis, die diesem Plugin gehören. | -| `imageGenerationProviders` | `string[]` | Provider-IDs für Bildgenerierung, die diesem Plugin gehören. | -| `videoGenerationProviders` | `string[]` | Provider-IDs für Videogenerierung, die diesem Plugin gehören. | -| `webFetchProviders` | `string[]` | Provider-IDs für Web-Fetch, die diesem Plugin gehören. | -| `webSearchProviders` | `string[]` | Provider-IDs für Websuche, die diesem Plugin gehören. | -| `tools` | `string[]` | Agent-Tool-Namen, die diesem Plugin für gebündelte Vertragsprüfungen gehören. | +| Feld | Typ | Bedeutung | +| -------------------------------- | ---------- | ----------------------------------------------------------- | +| `speechProviders` | `string[]` | Speech-Provider-IDs, die diesem Plugin gehören. | +| `realtimeTranscriptionProviders` | `string[]` | Realtime-Transcription-Provider-IDs, die diesem Plugin gehören. | +| `realtimeVoiceProviders` | `string[]` | Realtime-Voice-Provider-IDs, die diesem Plugin gehören. | +| `mediaUnderstandingProviders` | `string[]` | Media-understanding-Provider-IDs, die diesem Plugin gehören. | +| `imageGenerationProviders` | `string[]` | Image-generation-Provider-IDs, die diesem Plugin gehören. | +| `videoGenerationProviders` | `string[]` | Video-generation-Provider-IDs, die diesem Plugin gehören. | +| `webFetchProviders` | `string[]` | Web-fetch-Provider-IDs, die diesem Plugin gehören. | +| `webSearchProviders` | `string[]` | Web-search-Provider-IDs, die diesem Plugin gehören. | +| `tools` | `string[]` | Namen von Agent-Tools, die diesem Plugin für gebündelte Vertragsprüfungen gehören. | -## Referenz zu `channelConfigs` +## Referenz für `channelConfigs` -Verwenden Sie `channelConfigs`, wenn ein Kanal-Plugin günstige Konfigurationsmetadaten benötigt, bevor -die Laufzeit lädt. +Verwenden Sie `channelConfigs`, wenn ein Kanal-Plugin kostengünstige Konfigurationsmetadaten benötigt, bevor +die Laufzeit geladen wird. ```json { @@ -296,12 +370,12 @@ die Laufzeit lädt. }, "uiHints": { "homeserverUrl": { - "label": "Homeserver-URL", + "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Verbindung zum Matrix-Homeserver", + "description": "Matrix-Homeserver-Verbindung", "preferOver": ["matrix-legacy"] } } @@ -310,19 +384,19 @@ die Laufzeit lädt. Jeder Kanaleintrag kann Folgendes enthalten: -| Feld | Typ | Bedeutung | -| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON-Schema für `channels.`. Für jeden deklarierten Kanalkonfigurationseintrag erforderlich. | -| `uiHints` | `Record` | Optionale UI-Beschriftungen/Platzhalter/Hinweise zur Sensitivität für diesen Abschnitt der Kanalkonfiguration. | -| `label` | `string` | Kanalbeschriftung, die in Picker- und Inspektionsoberflächen zusammengeführt wird, wenn Laufzeitmetadaten noch nicht bereit sind. | -| `description` | `string` | Kurze Kanalbeschreibung für Inspektions- und Katalogoberflächen. | -| `preferOver` | `string[]` | Legacy- oder Plug-in-IDs mit geringerer Priorität, die dieser Kanal in Auswahloberflächen übertreffen soll. | +| Feld | Typ | Bedeutung | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | +| `schema` | `object` | JSON-Schema für `channels.`. Für jeden deklarierten Kanal-Konfigurationseintrag erforderlich. | +| `uiHints` | `Record` | Optionale UI-Beschriftungen/Platzhalter/Hinweise zur Vertraulichkeit für diesen Abschnitt der Kanal-Konfiguration. | +| `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[]` | Veraltete oder niedriger priorisierte Plugin-IDs, die dieser Kanal in Auswahloberflächen übertreffen soll. | -## Referenz zu `modelSupport` +## Referenz für `modelSupport` Verwenden Sie `modelSupport`, wenn OpenClaw Ihr Provider-Plugin aus -Kurzschreibweisen von Modell-IDs wie `gpt-5.4` oder `claude-sonnet-4.6` ableiten soll, bevor die Plugin-Laufzeit -lädt. +Kurzform-Modell-IDs wie `gpt-5.4` oder `claude-sonnet-4.6` ableiten soll, bevor die Plugin-Laufzeit +geladen wird. ```json { @@ -333,9 +407,9 @@ lädt. } ``` -OpenClaw wendet folgende Priorität an: +OpenClaw wendet diese Rangfolge an: -- explizite `provider/model`-Referenzen verwenden die Manifest-Metadaten des besitzenden `providers` +- explizite `provider/model`-Referenzen verwenden die zugehörigen `providers`-Manifestmetadaten - `modelPatterns` haben Vorrang vor `modelPrefixes` - wenn ein nicht gebündeltes Plugin und ein gebündeltes Plugin beide passen, gewinnt das nicht gebündelte Plugin @@ -343,66 +417,65 @@ OpenClaw wendet folgende Priorität an: Felder: -| Feld | Typ | Bedeutung | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Präfixe, die mit `startsWith` gegen Kurzschreibweisen von Modell-IDs abgeglichen werden. | -| `modelPatterns` | `string[]` | Regex-Quellen, die nach dem Entfernen von Profilsuffixen gegen Kurzschreibweisen von Modell-IDs abgeglichen werden. | +| Feld | Typ | Bedeutung | +| --------------- | ---------- | ------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | Präfixe, die mit `startsWith` gegen Kurzform-Modell-IDs abgeglichen werden. | +| `modelPatterns` | `string[]` | Regex-Quellen, die nach Entfernen des Profilsuffixes mit Kurzform-Modell-IDs abgeglichen werden. | -Legacy-Fähigkeitsschlüssel auf oberster Ebene sind veraltet. Verwenden Sie `openclaw doctor --fix`, um +Veraltete Fähigkeits-Schlüssel auf oberster Ebene sind deprecated. Verwenden Sie `openclaw doctor --fix`, um `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` und `webSearchProviders` unter `contracts` zu verschieben; das normale -Laden des Manifests behandelt diese Felder auf oberster Ebene nicht mehr als -Fähigkeitseigentümerschaft. +`webFetchProviders` und `webSearchProviders` unter `contracts` zu +verschieben; das normale Laden des Manifests behandelt diese Felder auf oberster Ebene nicht mehr als +Fähigkeitszuordnung. -## Manifest im Vergleich zu `package.json` +## Manifest im Vergleich zu package.json Die beiden Dateien erfüllen unterschiedliche Aufgaben: -| Datei | Verwenden Sie sie für | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Erkennung, Konfigurationsvalidierung, Metadaten für Auth-Auswahlmöglichkeiten und UI-Hinweise, die vorhanden sein müssen, bevor der Plugin-Code ausgeführt wird | -| `package.json` | npm-Metadaten, Abhängigkeitsinstallation und den `openclaw`-Block, der für Entrypoints, Installations-Gating, Setup oder Katalog-Metadaten verwendet wird | +| Datei | Verwendung | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Erkennung, Konfigurationsvalidierung, Metadaten zu Authentifizierungsoptionen und UI-Hinweise, die vorhanden sein müssen, bevor Plugin-Code ausgeführt wird | +| `package.json` | npm-Metadaten, Installation von Abhängigkeiten und der `openclaw`-Block für Einstiegspunkte, Installationsfreigabe, Einrichtung oder Katalogmetadaten | -Wenn Sie unsicher sind, wo ein Metadatenelement hingehö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, Entry-Dateien oder das npm-Installationsverhalten geht, gehört es in `package.json` +- wenn es um Paketierung, Einstiegsdateien oder das npm-Installationsverhalten geht, gehört es in `package.json` ### `package.json`-Felder, die die Erkennung beeinflussen -Einige Plugin-Metadaten vor der Laufzeit liegen absichtlich in `package.json` unter dem +Einige Metadaten von Plugins vor der Laufzeit befinden sich absichtlich in `package.json` unter dem `openclaw`-Block statt in `openclaw.plugin.json`. Wichtige Beispiele: -| Feld | Bedeutung | -| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Deklariert native Plugin-Entrypoints. | -| `openclaw.setupEntry` | Leichtgewichtiger Setup-only-Entrypoint, der während des Onboardings und beim verzögerten Kanalstart verwendet wird. | -| `openclaw.channel` | Leichtgewichtige Kanal-Katalogmetadaten wie Beschriftungen, Dokumentationspfade, Aliasse und Auswahltext. | -| `openclaw.channel.configuredState` | Leichtgewichtige Metadaten für den Prüfer des konfigurierten Status, die beantworten können: „Existiert env-only-Setup bereits?“, ohne die vollständige Kanal-Laufzeit zu laden. | -| `openclaw.channel.persistedAuthState` | Leichtgewichtige Metadaten für den Prüfer persistierter Authentifizierung, die beantworten können: „Ist bereits irgendetwas angemeldet?“, ohne die vollständige Kanal-Laufzeit 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` | Minimal unterstützte OpenClaw-Host-Version mit einer Semver-Untergrenze wie `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Erlaubt einen eng begrenzten Wiederherstellungspfad für die Neuinstallation gebündelter Plugins, wenn die Konfiguration ungültig ist. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Ermöglicht das Laden von Setup-only-Kanaloberflächen vor dem vollständigen Kanal-Plugin während des Starts. | +| Feld | Bedeutung | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Deklariert native Plugin-Einstiegspunkte. | +| `openclaw.setupEntry` | Leichtgewichtiger Einstiegspunkt nur für die Einrichtung, verwendet während des Onboardings und beim verzögerten Kanalstart. | +| `openclaw.channel` | Kostengünstige Katalogmetadaten für Kanäle wie Bezeichnungen, Dokumentationspfade, Aliasse und Auswahltexte. | +| `openclaw.channel.configuredState` | Leichtgewichtige Metadaten für die Prüfung des konfigurierten Zustands, die „existiert bereits eine env-only-Einrichtung?“ beantworten können, ohne die vollständige Kanal-Laufzeit zu laden. | +| `openclaw.channel.persistedAuthState` | Leichtgewichtige Metadaten für die Prüfung des persistenten Authentifizierungszustands, die „ist bereits irgendwo eine Anmeldung vorhanden?“ beantworten können, ohne die vollständige Kanal-Laufzeit 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` | Minimal unterstützte OpenClaw-Host-Version, mit einer SemVer-Untergrenze wie `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Erlaubt einen eng begrenzten Wiederherstellungspfad zur 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 beim Start. | -`openclaw.install.minHostVersion` wird während der Installation und beim Laden des -Manifest-Registrys 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 begrenzt. Es macht -nicht beliebige defekte Konfigurationen installierbar. Derzeit erlaubt es nur Installations- -Abläufen, sich von bestimmten veralteten Upgrade-Fehlern gebündelter Plugins zu erholen, etwa einem -fehlenden Pfad zu einem gebündelten Plugin oder einem veralteten `channels.`-Eintrag für genau dieses -gebündelte Plugin. Nicht zusammenhängende Konfigurationsfehler blockieren die Installation weiterhin und schicken -Operatoren zu `openclaw doctor --fix`. +nicht beliebige fehlerhafte Konfigurationen installierbar. Derzeit erlaubt es nur Installationsabläufen, +sich von bestimmten veralteten Upgrade-Fehlern gebündelter Plugins zu erholen, zum Beispiel einem +fehlenden Pfad zu einem gebündelten Plugin oder einem veralteten `channels.`-Eintrag für dasselbe +gebündelte Plugin. Nicht zusammenhängende Konfigurationsfehler blockieren weiterhin die Installation und verweisen Operatoren +auf `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` ist Paketmetadaten für ein kleines Prüfer- -Modul: +`openclaw.channel.persistedAuthState` ist Paketmetadaten für ein kleines Prüfmodul: ```json { @@ -418,13 +491,13 @@ Modul: } ``` -Verwenden Sie dies, wenn Setup-, Doctor- oder Abläufe für den konfigurierten Status vor dem Laden des vollständigen -Kanal-Plugins eine günstige Ja/Nein-Auth-Probe benötigen. Der Ziel-Export sollte eine kleine -Funktion sein, die nur persistierten Status liest; leiten Sie dies nicht über das vollständige -Barrel der Kanal-Laufzeit. +Verwenden Sie dies, wenn Einrichtungs-, Doctor- oder configured-state-Abläufe eine kostengünstige Ja/Nein- +Auth-Prüfung benötigen, bevor das vollständige Kanal-Plugin geladen wird. Das Zielexport sollte eine kleine +Funktion sein, die nur persistenten Zustand liest; leiten Sie dies nicht über das vollständige +Kanal-Laufzeit-Barrel. -`openclaw.channel.configuredState` folgt derselben Form für günstige env-only- -Prüfungen des konfigurierten Status: +`openclaw.channel.configuredState` verwendet dieselbe Form für kostengünstige env-only- +Prüfungen des konfigurierten Zustands: ```json { @@ -440,8 +513,8 @@ Prüfungen des konfigurierten Status: } ``` -Verwenden Sie dies, wenn ein Kanal den konfigurierten Status aus env oder anderen kleinen -Nicht-Laufzeit-Eingaben beantworten kann. Wenn die Prüfung eine vollständige Konfigurationsauflösung oder die echte +Verwenden Sie dies, wenn ein Kanal den konfigurierten Zustand aus env oder anderen kleinen +Nicht-Laufzeiteingaben beantworten kann. Wenn die Prüfung vollständige Konfigurationsauflösung oder die echte Kanal-Laufzeit benötigt, belassen Sie diese Logik stattdessen im Hook `config.hasConfiguredState` des Plugins. @@ -457,47 +530,48 @@ des Plugins. ein Plugin-Manifest deklariert. - `plugins.entries.`, `plugins.allow`, `plugins.deny` und `plugins.slots.*` müssen auf **erkennbare** Plugin-IDs verweisen. Unbekannte IDs sind **Fehler**. -- Wenn ein Plugin installiert ist, aber ein defektes oder fehlendes Manifest oder Schema hat, +- Wenn ein Plugin installiert ist, aber ein fehlerhaftes oder fehlendes Manifest oder Schema hat, schlägt die Validierung fehl und Doctor meldet den Plugin-Fehler. - Wenn eine Plugin-Konfiguration existiert, das Plugin aber **deaktiviert** ist, bleibt die Konfiguration erhalten und - in Doctor + Logs wird eine **Warnung** ausgegeben. + in Doctor + Protokollen wird eine **Warnung** angezeigt. -Das vollständige Schema von `plugins.*` finden Sie unter [Konfigurationsreferenz](/de/gateway/configuration). +Die vollständige `plugins.*`-Schema-Referenz finden Sie unter [Konfigurationsreferenz](/de/gateway/configuration). ## 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 Erkennung + Validierung. -- Native Manifeste werden mit JSON5 geparst, daher werden Kommentare, nachgestellte Kommata und - nicht in Anführungszeichen gesetzte Schlüssel akzeptiert, solange der Endwert weiterhin ein Objekt ist. +- 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-Probes, Validierung von Env-Markern - und ähnliche Provider-Auth-Oberflächen, die die Plugin-Laufzeit nicht starten sollten, nur um Env-Namen zu prüfen. -- `providerAuthAliases` erlaubt es Providervarianten, die Auth- - Env-Variablen, Auth-Profile, konfigurationsgestützte Authentifizierung und die - API-Schlüssel-Onboarding-Auswahl eines anderen Providers wiederzuverwenden, ohne diese Beziehung im Core fest zu codieren. -- `channelEnvVars` ist der günstige Metadatenpfad für Shell-Env-Fallback, Setup- - Prompts 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 Picker für Auth-Auswahlmöglichkeiten, - Auflösung von `--auth-choice`, Zuordnung bevorzugter Provider und einfache Registrierung von Onboarding- - CLI-Flags, bevor die Provider-Laufzeit lädt. Für Metadaten von Laufzeit-Wizards, - die Providercode benötigen, siehe +- `providerAuthEnvVars` ist der kostengünstige Metadatenpfad für Authentifizierungsprüfungen, env-marker- + Validierung und ähnliche Oberflächen für Provider-Authentifizierung, die die Plugin-Laufzeit nicht starten sollten, + nur um env-Namen zu prüfen. +- `providerAuthAliases` erlaubt es Provider-Varianten, die Authentifizierungs- + Umgebungsvariablen, Authentifizierungsprofile, konfigurationsgestützte Authentifizierung und API-Schlüssel-Onboarding-Optionen eines anderen Providers wiederzuverwenden, + ohne diese Beziehung im Core fest zu codieren. +- `channelEnvVars` ist der kostengünstige Metadatenpfad für Shell-env-Fallback, Einrichtungs- + Eingabeaufforderungen und ähnliche Kanaloberflächen, die die Plugin-Laufzeit nicht starten sollten, + nur um env-Namen zu prüfen. +- `providerAuthChoices` ist der kostengünstige Metadatenpfad für Auswahlfelder von Authentifizierungsoptionen, + die Auflösung von `--auth-choice`, bevorzugte Provider-Zuordnung und die einfache Registrierung von + Onboarding-CLI-Flags, bevor die Provider-Laufzeit geladen wird. Informationen für Laufzeit- + Assistenten, die Provider-Code erfordern, finden Sie unter [Provider-Laufzeit-Hooks](/de/plugins/architecture#provider-runtime-hooks). - Exklusive Plugin-Arten werden über `plugins.slots.*` ausgewählt. - - `kind: "memory"` wird durch `plugins.slots.memory` ausgewählt. - - `kind: "context-engine"` wird durch `plugins.slots.contextEngine` - ausgewählt (Standard: eingebautes `legacy`). + - `kind: "memory"` wird über `plugins.slots.memory` ausgewählt. + - `kind: "context-engine"` wird über `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 Allowlist des Paketmanagers (zum Beispiel pnpm `allow-build-scripts` + Anforderungen an die Paketmanager-Allowlist (zum Beispiel pnpm `allow-build-scripts` - `pnpm rebuild `). ## Verwandt -- [Plugins erstellen](/de/plugins/building-plugins) — Einstieg in Plugins +- [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 +- [SDK-Übersicht](/de/plugins/sdk-overview) — Referenz zum Plugin SDK diff --git a/docs/de/reference/rich-output-protocol.md b/docs/de/reference/rich-output-protocol.md new file mode 100644 index 000000000..f3ccf6435 --- /dev/null +++ b/docs/de/reference/rich-output-protocol.md @@ -0,0 +1,60 @@ +--- +x-i18n: + generated_at: "2026-04-11T15:15:49Z" + model: gpt-5.4 + provider: openai + source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035 + source_path: reference/rich-output-protocol.md + workflow: 15 +--- + +# Rich-Output-Protokoll + +Die Assistentenausgabe kann eine kleine Menge an Übermittlungs-/Render-Anweisungen enthalten: + +- `MEDIA:` für die Zustellung von Anhängen +- `[[audio_as_voice]]` für Hinweise zur Audio-Wiedergabe +- `[[reply_to_current]]` / `[[reply_to:]]` für Antwort-Metadaten +- `[embed ...]` für umfangreiches Rendering in der Control UI + +Diese Anweisungen sind getrennt. `MEDIA:` sowie Antwort-/Sprach-Tags bleiben Übermittlungsmetadaten; `[embed ...]` ist der reine Rich-Render-Pfad für das Web. + +## `[embed ...]` + +`[embed ...]` ist die einzige agentenseitige Syntax für umfangreiches Rendering in der Control UI. + +Selbstschließendes Beispiel: + +```text +[embed ref="cv_123" title="Status" /] +``` + +Regeln: + +- `[view ...]` ist für neue Ausgaben nicht mehr gültig. +- Embed-Shortcodes werden nur in der Nachrichtenoberfläche des Assistenten gerendert. +- Nur URL-basierte Embeds werden gerendert. Verwende `ref="..."` oder `url="..."`. +- Inline-HTML-Embed-Shortcodes in Blockform werden nicht gerendert. +- Die Web-UI entfernt den Shortcode aus dem sichtbaren Text und rendert das Embed inline. +- `MEDIA:` ist kein Alias für Embeds und sollte nicht für umfangreiches Embed-Rendering verwendet werden. + +## Gespeicherte Rendering-Struktur + +Der normalisierte/gespeicherte Inhaltsblock des Assistenten ist ein strukturiertes `canvas`-Element: + +```json +{ + "type": "canvas", + "preview": { + "kind": "canvas", + "surface": "assistant_message", + "render": "url", + "viewId": "cv_123", + "url": "/__openclaw__/canvas/documents/cv_123/index.html", + "title": "Status", + "preferredHeight": 320 + } +} +``` + +Gespeicherte/gerenderte Rich-Blöcke verwenden direkt diese `canvas`-Struktur. `present_view` wird nicht erkannt. diff --git a/docs/de/tools/video-generation.md b/docs/de/tools/video-generation.md index f6a9759fb..2cf2bba58 100644 --- a/docs/de/tools/video-generation.md +++ b/docs/de/tools/video-generation.md @@ -1,35 +1,34 @@ --- read_when: - - Videos über den Agenten erzeugen - - Provider und Modelle für die Videoerzeugung konfigurieren + - Videos über den Agenten generieren + - Video-Generierungs-Provider und -Modelle konfigurieren - Die Parameter des Tools `video_generate` verstehen -summary: Videos aus Text, Bildern oder vorhandenen Videos mit 12 Provider-Backends generieren -title: Videoerzeugung +summary: Erstellen Sie Videos aus Text, Bildern oder vorhandenen Videos mit 14 Provider-Backends. +title: Videogenerierung x-i18n: - generated_at: "2026-04-11T02:48:15Z" + generated_at: "2026-04-11T15:15:57Z" model: gpt-5.4 provider: openai - source_hash: 6848d03ef578181902517d068e8d9fe2f845e572a90481bbdf7bd9f1c591f245 + source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263 source_path: tools/video-generation.md workflow: 15 --- -# Videoerzeugung +# Videogenerierung -OpenClaw-Agenten können Videos aus Text-Prompts, Referenzbildern oder vorhandenen Videos erzeugen. Zwölf Provider-Backends werden unterstützt, jeweils mit unterschiedlichen Modelloptionen, Eingabemodi und Funktionsumfängen. Der Agent wählt automatisch den richtigen Provider anhand Ihrer Konfiguration und verfügbaren API-Schlüssel aus. +OpenClaw-Agenten können Videos aus Text-Prompts, Referenzbildern oder vorhandenen Videos generieren. Vierzehn Provider-Backends werden unterstützt, jeweils mit unterschiedlichen Modelloptionen, Eingabemodi und Funktionssätzen. Der Agent wählt automatisch den passenden Provider basierend auf Ihrer Konfiguration und den verfügbaren API-Schlüsseln aus. -Das Tool `video_generate` erscheint nur, wenn mindestens ein Provider für Videoerzeugung verfügbar ist. Wenn Sie es nicht in den Agent-Tools sehen, setzen Sie einen API-Schlüssel für einen Provider oder konfigurieren Sie `agents.defaults.videoGenerationModel`. +Das Tool `video_generate` erscheint nur, wenn mindestens ein Provider für die Videogenerierung verfügbar ist. Wenn Sie es nicht in den Agenten-Tools sehen, setzen Sie einen Provider-API-Schlüssel oder konfigurieren Sie `agents.defaults.videoGenerationModel`. -OpenClaw behandelt die Videoerzeugung als drei Runtime-Modi: +OpenClaw behandelt die Videogenerierung als drei Laufzeitmodi: - `generate` für Text-zu-Video-Anfragen ohne Referenzmedien - `imageToVideo`, wenn die Anfrage ein oder mehrere Referenzbilder enthält - `videoToVideo`, wenn die Anfrage ein oder mehrere Referenzvideos enthält -Provider können jede beliebige Teilmenge dieser Modi unterstützen. Das Tool validiert den aktiven -Modus vor dem Absenden und meldet unterstützte Modi in `action=list`. +Provider können jede beliebige Teilmenge dieser Modi unterstützen. Das Tool validiert den aktiven Modus vor dem Absenden und meldet die unterstützten Modi in `action=list`. ## Schnellstart @@ -39,7 +38,7 @@ Modus vor dem Absenden und meldet unterstützte Modi in `action=list`. export GEMINI_API_KEY="your-key" ``` -2. Optional: Legen Sie ein Standardmodell fest: +2. Legen Sie optional ein Standardmodell fest: ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" @@ -47,33 +46,33 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 3. Fragen Sie den Agenten: -> Erzeuge ein 5 Sekunden langes cineastisches Video von einem freundlichen Hummer, der bei Sonnenuntergang surft. +> Generiere ein 5-sekündiges filmisches Video eines freundlichen Hummers, der bei Sonnenuntergang surft. -Der Agent ruft `video_generate` automatisch auf. Keine Tool-Allowlist ist erforderlich. +Der Agent ruft `video_generate` automatisch auf. Es ist keine Tool-Allowlist erforderlich. -## Was passiert, wenn Sie ein Video erzeugen +## Was passiert, wenn Sie ein Video generieren -Die Videoerzeugung ist asynchron. Wenn der Agent in einer Sitzung `video_generate` aufruft: +Die Videogenerierung erfolgt asynchron. Wenn der Agent `video_generate` in einer Sitzung aufruft: 1. OpenClaw sendet die Anfrage an den Provider und gibt sofort eine Aufgaben-ID zurück. -2. Der Provider verarbeitet den Job im Hintergrund (typischerweise 30 Sekunden bis 5 Minuten, abhängig von Provider und Auflösung). -3. Wenn das Video fertig ist, weckt OpenClaw dieselbe Sitzung mit einem internen Abschlussereignis auf. -4. Der Agent stellt das fertige Video wieder in der ursprünglichen Unterhaltung bereit. +2. Der Provider verarbeitet den Auftrag im Hintergrund (typischerweise 30 Sekunden bis 5 Minuten, je nach Provider und Auflösung). +3. Wenn das Video bereit ist, reaktiviert OpenClaw dieselbe Sitzung mit einem internen Abschlussereignis. +4. Der Agent stellt das fertige Video zurück in die ursprüngliche Unterhaltung. -Während ein Job läuft, geben doppelte Aufrufe von `video_generate` in derselben Sitzung den aktuellen Aufgabenstatus zurück, statt eine weitere Erzeugung zu starten. Verwenden Sie `openclaw tasks list` oder `openclaw tasks show `, um den Fortschritt in der CLI zu prüfen. +Während ein Auftrag läuft, geben doppelte `video_generate`-Aufrufe in derselben Sitzung den aktuellen Aufgabenstatus zurück, anstatt eine weitere Generierung zu starten. Verwenden Sie `openclaw tasks list` oder `openclaw tasks show `, um den Fortschritt über die CLI zu prüfen. -Außerhalb von sitzungsgestützten Agent-Läufen (zum Beispiel bei direkten Tool-Aufrufen) fällt das Tool auf Inline-Erzeugung zurück und gibt im selben Turn den endgültigen Medienpfad zurück. +Außerhalb von sitzungsbasierten Agentenläufen (zum Beispiel bei direkten Tool-Aufrufen) greift das Tool auf Inline-Generierung zurück und gibt den endgültigen Medienpfad im selben Durchlauf zurück. ### Aufgabenlebenszyklus Jede `video_generate`-Anfrage durchläuft vier Zustände: 1. **queued** -- Aufgabe erstellt, wartet darauf, dass der Provider sie annimmt. -2. **running** -- der Provider verarbeitet sie (typischerweise 30 Sekunden bis 5 Minuten, abhängig von Provider und Auflösung). -3. **succeeded** -- Video bereit; der Agent wird aufgeweckt und stellt es in der Unterhaltung bereit. -4. **failed** -- Provider-Fehler oder Timeout; der Agent wird mit Fehlerdetails aufgeweckt. +2. **running** -- Provider verarbeitet die Anfrage (typischerweise 30 Sekunden bis 5 Minuten, je nach Provider und Auflösung). +3. **succeeded** -- Video bereit; der Agent wird reaktiviert und stellt es in die Unterhaltung. +4. **failed** -- Provider-Fehler oder Zeitüberschreitung; der Agent wird mit Fehlerdetails reaktiviert. -Status in der CLI prüfen: +Status über die CLI prüfen: ```bash openclaw tasks list @@ -81,49 +80,49 @@ openclaw tasks show openclaw tasks cancel ``` -Vermeidung von Duplikaten: Wenn für die aktuelle Sitzung bereits eine Videoaufgabe `queued` oder `running` ist, gibt `video_generate` den Status der vorhandenen Aufgabe zurück, statt eine neue zu starten. Verwenden Sie `action: "status"`, um explizit zu prüfen, ohne eine neue Erzeugung auszulösen. +Vermeidung von Duplikaten: Wenn für die aktuelle Sitzung bereits eine Videoaufgabe `queued` oder `running` ist, gibt `video_generate` den bestehenden Aufgabenstatus zurück, anstatt eine neue Aufgabe zu starten. Verwenden Sie `action: "status"`, um den Status ausdrücklich zu prüfen, ohne eine neue Generierung auszulösen. ## Unterstützte Provider -| Provider | Standardmodell | Text | Bildreferenz | Videoreferenz | API-Schlüssel | -| -------- | ------------------------------ | ---- | ----------------- | ---------------- | ----------------------------------------- | -| Alibaba | `wan2.6-t2v` | Ja | Ja (Remote-URL) | Ja (Remote-URL) | `MODELSTUDIO_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | Ja | 1 Bild | Nein | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Ja | 1 Bild | Nein | `COMFY_API_KEY` oder `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Ja | 1 Bild | Nein | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | Ja | 1 Bild | 1 Video | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Ja | 1 Bild | Nein | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | Ja | 1 Bild | 1 Video | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Ja | Ja (Remote-URL) | Ja (Remote-URL) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Ja | 1 Bild | 1 Video | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Ja | 1 Bild | Nein | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Ja | 1 Bild (`kling`) | Nein | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Ja | 1 Bild | 1 Video | `XAI_API_KEY` | +| Provider | Standardmodell | Text | Bildreferenz | Videoreferenz | API key | +| --------------------- | ------------------------------- | ---- | ---------------------------------------------------- | --------------- | ---------------------------------------- | +| Alibaba | `wan2.6-t2v` | Ja | Ja (Remote-URL) | Ja (Remote-URL) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | Ja | Bis zu 2 Bilder (nur I2V-Modelle; erstes + letztes Bild) | Nein | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Ja | Bis zu 2 Bilder (erstes + letztes Bild per Rolle) | Nein | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Ja | Bis zu 9 Referenzbilder | Bis zu 3 Videos | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Ja | 1 Bild | Nein | `COMFY_API_KEY` oder `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Ja | 1 Bild | Nein | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Ja | 1 Bild | 1 Video | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Ja | 1 Bild | Nein | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Ja | 1 Bild | 1 Video | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Ja | Ja (Remote-URL) | Ja (Remote-URL) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Ja | 1 Bild | 1 Video | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Ja | 1 Bild | Nein | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Ja | 1 Bild (`kling`) | Nein | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Ja | 1 Bild | 1 Video | `XAI_API_KEY` | -Einige Provider akzeptieren zusätzliche oder alternative API-Schlüssel-Umgebungsvariablen. Details finden Sie auf den jeweiligen [Provider-Seiten](#related). +Einige Provider akzeptieren zusätzliche oder alternative API-Schlüssel-Umgebungsvariablen. Einzelheiten finden Sie auf den jeweiligen [Provider-Seiten](#related). -Führen Sie `video_generate action=list` aus, um verfügbare Provider, Modelle und -Runtime-Modi zur Laufzeit zu prüfen. +Führen Sie `video_generate action=list` aus, um verfügbare Provider, Modelle und Laufzeitmodi zur Laufzeit zu prüfen. -### Deklarierte Capability-Matrix +### Deklarierte Fähigkeitsmatrix -Dies ist der explizite Modusvertrag, der von `video_generate`, Vertragstests -und dem gemeinsamen Live-Sweep verwendet wird. +Dies ist der explizite Modusvertrag, der von `video_generate`, Vertragstests und dem gemeinsamen Live-Sweep verwendet wird. -| Provider | `generate` | `imageToVideo` | `videoToVideo` | Gemeinsame Live-Umgebungen heute | -| -------- | ---------- | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider Remote-`http(s)`-Video-URLs benötigt | -| BytePlus | Ja | Ja | Nein | `generate`, `imageToVideo` | -| ComfyUI | Ja | Ja | Nein | Nicht im gemeinsamen Sweep; workflowspezifische Abdeckung liegt bei den Comfy-Tests | -| fal | Ja | Ja | Nein | `generate`, `imageToVideo` | -| Google | Ja | Ja | Ja | `generate`, `imageToVideo`; gemeinsames `videoToVideo` übersprungen, weil der aktuelle buffergestützte Gemini-/Veo-Sweep diese Eingabe nicht akzeptiert | -| MiniMax | Ja | Ja | Nein | `generate`, `imageToVideo` | +| Provider | `generate` | `imageToVideo` | `videoToVideo` | Gemeinsame Live-Lanes heute | +| -------- | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider Remote-`http(s)`-Video-URLs benötigt | +| BytePlus | Ja | Ja | Nein | `generate`, `imageToVideo` | +| ComfyUI | Ja | Ja | Nein | Nicht im gemeinsamen Sweep; workflowspezifische Abdeckung liegt bei den Comfy-Tests | +| fal | Ja | Ja | Nein | `generate`, `imageToVideo` | +| Google | Ja | Ja | Ja | `generate`, `imageToVideo`; gemeinsames `videoToVideo` übersprungen, weil der aktuelle Gemini/Veo-Sweep mit pufferbasierten Eingaben diese Eingabe nicht akzeptiert | +| MiniMax | Ja | Ja | Nein | `generate`, `imageToVideo` | | OpenAI | Ja | Ja | Ja | `generate`, `imageToVideo`; gemeinsames `videoToVideo` übersprungen, weil dieser Organisations-/Eingabepfad derzeit providerseitigen Inpaint-/Remix-Zugriff benötigt | -| Qwen | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider Remote-`http(s)`-Video-URLs benötigt | -| Runway | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` läuft nur, wenn das ausgewählte Modell `runway/gen4_aleph` ist | -| Together | Ja | Ja | Nein | `generate`, `imageToVideo` | -| Vydra | Ja | Ja | Nein | `generate`; gemeinsames `imageToVideo` übersprungen, weil das gebündelte `veo3` nur Text unterstützt und das gebündelte `kling` eine Remote-Bild-URL benötigt | -| xAI | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider derzeit eine Remote-MP4-URL benötigt | +| Qwen | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider Remote-`http(s)`-Video-URLs benötigt | +| Runway | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` läuft nur, wenn das ausgewählte Modell `runway/gen4_aleph` ist | +| Together | Ja | Ja | Nein | `generate`, `imageToVideo` | +| Vydra | Ja | Ja | Nein | `generate`; gemeinsames `imageToVideo` übersprungen, weil das gebündelte `veo3` nur Text unterstützt und das gebündelte `kling` eine Remote-Bild-URL erfordert | +| xAI | Ja | Ja | Ja | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider derzeit eine Remote-MP4-URL benötigt | ## Tool-Parameter @@ -131,68 +130,107 @@ und dem gemeinsamen Live-Sweep verwendet wird. | Parameter | Typ | Beschreibung | | --------- | ------ | --------------------------------------------------------------------------- | -| `prompt` | string | Textbeschreibung des zu erzeugenden Videos (erforderlich für `action: "generate"`) | +| `prompt` | string | Textbeschreibung des zu generierenden Videos (erforderlich für `action: "generate"`) | ### Inhaltseingaben -| Parameter | Typ | Beschreibung | -| --------- | -------- | -------------------------------------- | -| `image` | string | Einzelnes Referenzbild (Pfad oder URL) | -| `images` | string[] | Mehrere Referenzbilder (bis zu 5) | -| `video` | string | Einzelnes Referenzvideo (Pfad oder URL) | -| `videos` | string[] | Mehrere Referenzvideos (bis zu 4) | +| Parameter | Typ | Beschreibung | +| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `image` | string | Einzelnes Referenzbild (Pfad oder URL) | +| `images` | string[] | Mehrere Referenzbilder (bis zu 9) | +| `imageRoles` | string[] | Optionale positionsbezogene Rollenhinweise parallel zur kombinierten Bildliste. Kanonische Werte: `first_frame`, `last_frame`, `reference_image` | +| `video` | string | Einzelnes Referenzvideo (Pfad oder URL) | +| `videos` | string[] | Mehrere Referenzvideos (bis zu 4) | +| `videoRoles` | string[] | Optionale positionsbezogene Rollenhinweise parallel zur kombinierten Videoliste. Kanonischer Wert: `reference_video` | +| `audioRef` | string | Einzelne Referenz-Audiodatei (Pfad oder URL). Wird z. B. für Hintergrundmusik oder Stimmreferenzen verwendet, wenn der Provider Audioeingaben unterstützt | +| `audioRefs` | string[] | Mehrere Referenz-Audiodateien (bis zu 3) | +| `audioRoles` | string[] | Optionale positionsbezogene Rollenhinweise parallel zur kombinierten Audioliste. Kanonischer Wert: `reference_audio` | -### Stilsteuerung +Rollenhinweise werden unverändert an den Provider weitergeleitet. Kanonische Werte stammen aus der Union `VideoGenerationAssetRole`, aber Provider können zusätzliche Rollen-Strings akzeptieren. `*Roles`-Arrays dürfen nicht mehr Einträge haben als die entsprechende Referenzliste; Off-by-one-Fehler schlagen mit einer klaren Fehlermeldung fehl. Verwenden Sie einen leeren String, um einen Platz nicht zu setzen. -| Parameter | Typ | Beschreibung | -| ----------------- | ------- | ------------------------------------------------------------------------ | -| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | `480P`, `720P`, `768P` oder `1080P` | -| `durationSeconds` | number | Zieldauer in Sekunden (auf den nächsten vom Provider unterstützten Wert gerundet) | -| `size` | string | Größenhinweis, wenn der Provider ihn unterstützt | -| `audio` | boolean | Erzeugten Ton aktivieren, wenn unterstützt | -| `watermark` | boolean | Watermarking des Providers umschalten, wenn unterstützt | +### Stilsteuerungen + +| Parameter | Typ | Beschreibung | +| ----------------- | ------- | --------------------------------------------------------------------------------------- | +| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` oder `adaptive` | +| `resolution` | string | `480P`, `720P`, `768P` oder `1080P` | +| `durationSeconds` | number | Zieldauer in Sekunden (auf den nächsten vom Provider unterstützten Wert gerundet) | +| `size` | string | Größenhinweis, wenn der Provider dies unterstützt | +| `audio` | boolean | Generierten Ton in der Ausgabe aktivieren, wenn unterstützt. Unterscheidet sich von `audioRef*` (Eingaben) | +| `watermark` | boolean | Provider-Wasserzeichen aktivieren oder deaktivieren, wenn unterstützt | + +`adaptive` ist ein providerspezifischer Sentinel-Wert: Er wird unverändert an Provider weitergeleitet, die `adaptive` in ihren Fähigkeiten deklarieren (z. B. verwendet BytePlus Seedance ihn, um das Seitenverhältnis automatisch aus den Abmessungen des Eingabebildes zu erkennen). Provider, die ihn nicht deklarieren, geben den Wert über `details.ignoredOverrides` im Tool-Ergebnis aus, damit sichtbar ist, dass er verworfen wurde. ### Erweitert -| Parameter | Typ | Beschreibung | -| ---------- | ------ | --------------------------------------------------- | -| `action` | string | `"generate"` (Standard), `"status"` oder `"list"` | -| `model` | string | Provider-/Modell-Override (z. B. `runway/gen4.5`) | -| `filename` | string | Hinweis für den Ausgabedateinamen | +| Parameter | Typ | Beschreibung | +| ----------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `action` | string | `"generate"` (Standard), `"status"` oder `"list"` | +| `model` | string | Provider-/Modell-Override (z. B. `runway/gen4.5`) | +| `filename` | string | Hinweis für den Ausgabedateinamen | +| `providerOptions` | object | Providerspezifische Optionen als JSON-Objekt (z. B. `{"seed": 42, "draft": true}`). Provider, die ein typisiertes Schema deklarieren, validieren Schlüssel und Typen; unbekannte Schlüssel oder Typabweichungen führen dazu, dass der Kandidat beim Fallback übersprungen wird. Provider ohne deklariertes Schema erhalten die Optionen unverändert. Führen Sie `video_generate action=list` aus, um zu sehen, was jeder Provider akzeptiert | -Nicht alle Provider unterstützen alle Parameter. OpenClaw normalisiert die Dauer bereits auf den jeweils nächstunterstützten Provider-Wert und ordnet außerdem übersetzte Geometriehinweise wie Größe-zu-Seitenverhältnis um, wenn ein Fallback-Provider eine andere Steueroberfläche bereitstellt. Wirklich nicht unterstützte Overrides werden nach bestem Bemühen ignoriert und als Warnungen im Tool-Ergebnis gemeldet. Harte Capability-Grenzen (zum Beispiel zu viele Referenzeingaben) schlagen vor dem Absenden fehl. +Nicht alle Provider unterstützen alle Parameter. OpenClaw normalisiert die Dauer bereits auf den nächstgelegenen vom Provider unterstützten Wert und ordnet außerdem übersetzte Geometriehinweise wie Größen-zu-Seitenverhältnis neu zu, wenn ein Fallback-Provider eine andere Steuerungsoberfläche bereitstellt. Wirklich nicht unterstützte Overrides werden nach bestem Bemühen ignoriert und als Warnungen im Tool-Ergebnis gemeldet. Harte Fähigkeitsgrenzen (wie zu viele Referenzeingaben) schlagen vor dem Absenden fehl. -Tool-Ergebnisse melden die angewendeten Einstellungen. Wenn OpenClaw während eines Provider-Fallbacks Dauer oder Geometrie umordnet, spiegeln die zurückgegebenen Werte für `durationSeconds`, `size`, `aspectRatio` und `resolution` das wider, was tatsächlich übermittelt wurde, und `details.normalization` erfasst die Übersetzung von angefordert zu angewendet. +Tool-Ergebnisse melden die angewendeten Einstellungen. Wenn OpenClaw Dauer oder Geometrie während des Provider-Fallbacks neu zuordnet, spiegeln die zurückgegebenen Werte `durationSeconds`, `size`, `aspectRatio` und `resolution` wider, was tatsächlich übermittelt wurde, und `details.normalization` erfasst die Übersetzung von angefordert zu angewendet. -Referenzeingaben wählen außerdem den Runtime-Modus: +Referenzeingaben wählen auch den Laufzeitmodus aus: - Keine Referenzmedien: `generate` - Beliebige Bildreferenz: `imageToVideo` - Beliebige Videoreferenz: `videoToVideo` +- Referenz-Audioeingaben ändern den aufgelösten Modus nicht; sie werden zusätzlich zu dem durch Bild-/Videoreferenzen gewählten Modus angewendet und funktionieren nur mit Providern, die `maxInputAudios` deklarieren -Gemischte Bild- und Videoreferenzen sind keine stabile gemeinsame Capability-Oberfläche. +Gemischte Bild- und Videoreferenzen sind keine stabile gemeinsame Fähigkeitsoberfläche. Bevorzugen Sie einen Referenztyp pro Anfrage. +#### Fallback und typisierte Optionen + +Einige Fähigkeitsprüfungen werden auf der Fallback-Ebene statt an der +Tool-Grenze angewendet, damit eine Anfrage, die die Limits des primären +Providers überschreitet, trotzdem auf einem geeigneten Fallback ausgeführt +werden kann: + +- Wenn der aktive Kandidat kein `maxInputAudios` deklariert (oder es als + `0` deklariert), wird er übersprungen, wenn die Anfrage Audio-Referenzen + enthält, und der nächste Kandidat wird versucht. +- Wenn `maxDurationSeconds` des aktiven Kandidaten unter den angeforderten + `durationSeconds` liegt und der Kandidat keine + `supportedDurationSeconds`-Liste deklariert, wird er übersprungen. +- Wenn die Anfrage `providerOptions` enthält und der aktive Kandidat + ausdrücklich ein typisiertes `providerOptions`-Schema deklariert, wird der Kandidat + übersprungen, wenn die angegebenen Schlüssel nicht im Schema enthalten sind oder die Werttypen nicht + übereinstimmen. Provider, die noch kein Schema deklariert haben, erhalten die + Optionen unverändert (rückwärtskompatibles Durchreichen). Ein Provider kann + sich ausdrücklich von allen Provider-Optionen abmelden, indem er ein leeres Schema + deklariert (`capabilities.providerOptions: {}`), was zum selben Überspringen wie bei einem + Typkonflikt führt. + +Der erste Überspringgrund in einer Anfrage wird mit `warn` protokolliert, damit Betreiber sehen, +wann ihr primärer Provider übergangen wurde; nachfolgende Überspringungen werden mit +`debug` protokolliert, damit lange Fallback-Ketten ruhig bleiben. Wenn jeder Kandidat übersprungen wird, +enthält der aggregierte Fehler den Überspringgrund für jeden einzelnen. + ## Aktionen - **generate** (Standard) -- ein Video aus dem angegebenen Prompt und optionalen Referenzeingaben erstellen. -- **status** -- den Zustand der laufenden Videoaufgabe für die aktuelle Sitzung prüfen, ohne eine weitere Erzeugung zu starten. -- **list** -- verfügbare Provider, Modelle und deren Capabilities anzeigen. +- **status** -- den Status der laufenden Videoaufgabe für die aktuelle Sitzung prüfen, ohne eine weitere Generierung zu starten. +- **list** -- verfügbare Provider, Modelle und deren Fähigkeiten anzeigen. ## Modellauswahl -Beim Erzeugen eines Videos löst OpenClaw das Modell in dieser Reihenfolge auf: +Beim Generieren eines Videos löst OpenClaw das Modell in dieser Reihenfolge auf: -1. **Tool-Parameter `model`** -- falls der Agent beim Aufruf einen angibt. +1. **`model`-Tool-Parameter** -- wenn der Agent in dem Aufruf einen angibt. 2. **`videoGenerationModel.primary`** -- aus der Konfiguration. -3. **`videoGenerationModel.fallbacks`** -- werden der Reihe nach versucht. +3. **`videoGenerationModel.fallbacks`** -- wird in der angegebenen Reihenfolge versucht. 4. **Automatische Erkennung** -- verwendet Provider mit gültiger Authentifizierung, beginnend mit dem aktuellen Standard-Provider, dann die übrigen Provider in alphabetischer Reihenfolge. Wenn ein Provider fehlschlägt, wird automatisch der nächste Kandidat versucht. Wenn alle Kandidaten fehlschlagen, enthält der Fehler Details aus jedem Versuch. Setzen Sie `agents.defaults.mediaGenerationAutoProviderFallback: false`, wenn Sie möchten, -dass die Videoerzeugung nur die expliziten Einträge `model`, `primary` und `fallbacks` verwendet. +dass die Videogenerierung nur die expliziten Einträge `model`, `primary` und `fallbacks` +verwendet. ```json5 { @@ -207,56 +245,30 @@ dass die Videoerzeugung nur die expliziten Einträge `model`, `primary` und `fal } ``` -HeyGen video-agent auf fal kann festgelegt werden mit: - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/fal-ai/heygen/v2/video-agent", - }, - }, - }, -} -``` - -Seedance 2.0 auf fal kann festgelegt werden mit: - -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "fal/bytedance/seedance-2.0/fast/text-to-video", - }, - }, - }, -} -``` - ## Hinweise zu Providern -| Provider | Hinweise | -| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Verwendet den asynchronen DashScope-/Model-Studio-Endpoint. Referenzbilder und -videos müssen Remote-`http(s)`-URLs sein. | -| BytePlus | Nur eine einzelne Bildreferenz. | -| ComfyUI | Workflow-gesteuerte lokale oder Cloud-Ausführung. Unterstützt Text-zu-Video und Bild-zu-Video über den konfigurierten Graphen. | -| fal | Verwendet einen warteschlangengestützten Ablauf für lang laufende Jobs. Nur eine einzelne Bildreferenz. Enthält HeyGen video-agent und Seedance 2.0 Text-zu-Video- und Bild-zu-Video-Modell-Refs. | -| Google | Verwendet Gemini/Veo. Unterstützt ein Bild oder ein Video als Referenz. | -| MiniMax | Nur eine einzelne Bildreferenz. | -| OpenAI | Nur der Override `size` wird weitergegeben. Andere Stil-Overrides (`aspectRatio`, `resolution`, `audio`, `watermark`) werden mit einer Warnung ignoriert. | -| Qwen | Dasselbe DashScope-Backend wie Alibaba. Referenzeingaben müssen Remote-`http(s)`-URLs sein; lokale Dateien werden vorab abgelehnt. | -| Runway | Unterstützt lokale Dateien über Data-URIs. Video-zu-Video erfordert `runway/gen4_aleph`. Rein textbasierte Läufe stellen die Seitenverhältnisse `16:9` und `9:16` bereit. | -| Together | Nur eine einzelne Bildreferenz. | -| Vydra | Verwendet direkt `https://www.vydra.ai/api/v1`, um Redirects zu vermeiden, die Authentifizierung verlieren. `veo3` ist gebündelt nur als Text-zu-Video; `kling` erfordert eine Remote-Bild-URL. | -| xAI | Unterstützt Text-zu-Video, Bild-zu-Video und Remote-Workflows zum Bearbeiten/Erweitern von Videos. | +| Provider | Hinweise | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Verwendet den asynchronen DashScope-/Model-Studio-Endpunkt. Referenzbilder und -videos müssen Remote-`http(s)`-URLs sein. | +| BytePlus (1.0) | Provider-ID `byteplus`. Modelle: `seedance-1-0-pro-250528` (Standard), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. T2V-Modelle (`*-t2v-*`) akzeptieren keine Bildeingaben; I2V-Modelle und allgemeine `*-pro-*`-Modelle unterstützen ein einzelnes Referenzbild (erstes Frame). Übergeben Sie das Bild positionsbezogen oder setzen Sie `role: "first_frame"`. T2V-Modell-IDs werden bei Bereitstellung eines Bildes automatisch auf die entsprechende I2V-Variante umgestellt. Unterstützte `providerOptions`-Schlüssel: `seed` (number), `draft` (boolean, erzwingt 480p), `camera_fixed` (boolean). | +| BytePlus Seedance 1.5 | Erfordert das Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Provider-ID `byteplus-seedance15`. Modell: `seedance-1-5-pro-251215`. Verwendet die einheitliche `content[]`-API. Unterstützt höchstens 2 Eingabebilder (first_frame + last_frame). Alle Eingaben müssen Remote-`https://`-URLs sein. Setzen Sie `role: "first_frame"` / `"last_frame"` für jedes Bild oder übergeben Sie Bilder positionsbezogen. `aspectRatio: "adaptive"` erkennt das Verhältnis automatisch aus dem Eingabebild. `audio: true` wird auf `generate_audio` abgebildet. `providerOptions.seed` (number) wird weitergeleitet. | +| BytePlus Seedance 2.0 | Erfordert das Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Provider-ID `byteplus-seedance2`. Modelle: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Verwendet die einheitliche `content[]`-API. Unterstützt bis zu 9 Referenzbilder, 3 Referenzvideos und 3 Referenz-Audiodateien. Alle Eingaben müssen Remote-`https://`-URLs sein. Setzen Sie `role` für jedes Asset — unterstützte Werte: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` erkennt das Verhältnis automatisch aus dem Eingabebild. `audio: true` wird auf `generate_audio` abgebildet. `providerOptions.seed` (number) wird weitergeleitet. | +| ComfyUI | Workflow-gesteuerte lokale oder Cloud-Ausführung. Unterstützt Text-zu-Video und Bild-zu-Video über den konfigurierten Graphen. | +| fal | Verwendet einen warteschlangenbasierten Ablauf für langlaufende Aufträge. Nur eine einzelne Bildreferenz. | +| Google | Verwendet Gemini/Veo. Unterstützt eine Bild- oder eine Videoreferenz. | +| MiniMax | Nur eine einzelne Bildreferenz. | +| OpenAI | Nur das Override `size` wird weitergeleitet. Andere Stil-Overrides (`aspectRatio`, `resolution`, `audio`, `watermark`) werden mit einer Warnung ignoriert. | +| Qwen | Gleiches DashScope-Backend wie Alibaba. Referenzeingaben müssen Remote-`http(s)`-URLs sein; lokale Dateien werden vorab abgelehnt. | +| Runway | Unterstützt lokale Dateien über Daten-URIs. Für Video-zu-Video ist `runway/gen4_aleph` erforderlich. Reine Textläufe bieten die Seitenverhältnisse `16:9` und `9:16`. | +| Together | Nur eine einzelne Bildreferenz. | +| Vydra | Verwendet direkt `https://www.vydra.ai/api/v1`, um Redirects zu vermeiden, bei denen die Authentifizierung verloren geht. `veo3` ist gebündelt nur als Text-zu-Video verfügbar; `kling` erfordert eine Remote-Bild-URL. | +| xAI | Unterstützt Text-zu-Video, Bild-zu-Video sowie Remote-Abläufe zum Bearbeiten/Erweitern von Videos. | -## Provider-Capability-Modi +## Provider-Fähigkeitsmodi -Der gemeinsame Vertrag für Videoerzeugung erlaubt Providern jetzt, modusspezifische -Capabilities zu deklarieren, statt nur flache aggregierte Grenzen. Neue Provider- -Implementierungen sollten explizite Modusblöcke bevorzugen: +Der gemeinsame Vertrag für die Videogenerierung erlaubt es Providern jetzt, modusspezifische +Fähigkeiten zu deklarieren, statt nur flache aggregierte Limits. Neue Provider-Implementierungen +sollten explizite Modusblöcke bevorzugen: ```typescript capabilities: { @@ -280,15 +292,15 @@ capabilities: { } ``` -Flache aggregierte Felder wie `maxInputImages` und `maxInputVideos` reichen nicht -aus, um Unterstützung für Transformationsmodi auszuweisen. Provider sollten +Flache aggregierte Felder wie `maxInputImages` und `maxInputVideos` reichen +nicht aus, um die Unterstützung von Transformationsmodi auszuweisen. Provider sollten `generate`, `imageToVideo` und `videoToVideo` explizit deklarieren, damit Live-Tests, Vertragstests und das gemeinsame Tool `video_generate` die Modusunterstützung deterministisch validieren können. ## Live-Tests -Opt-in-Live-Abdeckung für die gemeinsamen gebündelten Provider: +Opt-in-Live-Abdeckung für die gemeinsam gebündelten Provider: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -301,21 +313,21 @@ pnpm test:live:media video ``` Diese Live-Datei lädt fehlende Provider-Umgebungsvariablen aus `~/.profile`, bevorzugt -standardmäßig API-Schlüssel aus Live-/Umgebungsvariablen gegenüber gespeicherten Auth-Profilen und führt die -deklarierten Modi aus, die sie sicher mit lokalen Medien testen kann: +standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Auth-Profilen und führt die +deklarierten Modi aus, die sie mit lokalen Medien sicher testen kann: - `generate` für jeden Provider im Sweep - `imageToVideo`, wenn `capabilities.imageToVideo.enabled` -- `videoToVideo`, wenn `capabilities.videoToVideo.enabled` und Provider/Modell - buffergestützte lokale Videoeingaben im gemeinsamen Sweep akzeptiert +- `videoToVideo`, wenn `capabilities.videoToVideo.enabled` und der Provider/das Modell + im gemeinsamen Sweep pufferbasierte lokale Videoeingaben akzeptiert -Heute deckt die gemeinsame `videoToVideo`-Live-Umgebung ab: +Heute deckt die gemeinsame `videoToVideo`-Live-Lane Folgendes ab: - `runway` nur, wenn Sie `runway/gen4_aleph` auswählen ## Konfiguration -Legen Sie das Standardmodell für die Videoerzeugung in Ihrer OpenClaw-Konfiguration fest: +Legen Sie das Standardmodell für die Videogenerierung in Ihrer OpenClaw-Konfiguration fest: ```json5 { @@ -338,8 +350,8 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Verwandt -- [Tools Overview](/de/tools) -- [Background Tasks](/de/automation/tasks) -- Aufgabenverfolgung für asynchrone Videoerzeugung +- [Tool-Übersicht](/de/tools) +- [Hintergrundaufgaben](/de/automation/tasks) -- Aufgabenverfolgung für asynchrone Videogenerierung - [Alibaba Model Studio](/de/providers/alibaba) - [BytePlus](/de/concepts/model-providers#byteplus-international) - [ComfyUI](/de/providers/comfy) @@ -352,5 +364,5 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 - [Together AI](/de/providers/together) - [Vydra](/de/providers/vydra) - [xAI](/de/providers/xai) -- [Configuration Reference](/de/gateway/configuration-reference#agent-defaults) -- [Models](/de/concepts/models) +- [Konfigurationsreferenz](/de/gateway/configuration-reference#agent-defaults) +- [Modelle](/de/concepts/models)