diff --git a/docs/de/automation/cron-jobs.md b/docs/de/automation/cron-jobs.md index f7116b09b..5a75c47f1 100644 --- a/docs/de/automation/cron-jobs.md +++ b/docs/de/automation/cron-jobs.md @@ -1,22 +1,22 @@ --- read_when: - - Planen von Hintergrundjobs oder Aufweckvorgängen + - Hintergrundjobs oder Aufweckvorgänge planen - Externe Trigger (Webhooks, Gmail) in OpenClaw integrieren - - Entscheiden zwischen Heartbeat und Cron für geplante Aufgaben + - Zwischen Heartbeat und Cron für geplante Aufgaben entscheiden summary: Geplante Jobs, Webhooks und Gmail-PubSub-Trigger für den Gateway-Scheduler title: Geplante Aufgaben x-i18n: - generated_at: "2026-04-21T06:22:57Z" + generated_at: "2026-04-21T13:35:27Z" model: gpt-5.4 provider: openai - source_hash: e25f4dc8ee7b8f88e22d5cbc86e4527a9f5ac0ab4921e7874f76b186054682a3 + source_hash: ac08f67af43bc85a1713558899a220c935479620f1ef74aa76336259daac2828 source_path: automation/cron-jobs.md workflow: 15 --- # Geplante Aufgaben (Cron) -Cron ist der integrierte Scheduler des Gateway. Er speichert Jobs dauerhaft, weckt den Agenten zum richtigen Zeitpunkt auf und kann Ausgaben an einen Chat-Kanal oder einen Webhook-Endpunkt zurückliefern. +Cron ist der integrierte Scheduler des Gateway. Er speichert Jobs dauerhaft, weckt den Agenten zum richtigen Zeitpunkt und kann Ausgaben zurück an einen Chat-Kanal oder einen Webhook-Endpunkt zustellen. ## Schnellstart @@ -32,6 +32,7 @@ openclaw cron add \ # Ihre Jobs prüfen openclaw cron list +openclaw cron show # Ausführungsverlauf anzeigen openclaw cron runs --id @@ -40,97 +41,95 @@ openclaw cron runs --id ## So funktioniert Cron - Cron läuft **innerhalb des Gateway**-Prozesses (nicht innerhalb des Modells). -- Job-Definitionen werden unter `~/.openclaw/cron/jobs.json` dauerhaft gespeichert, damit Zeitpläne bei Neustarts nicht verloren gehen. -- Der Laufzeit-Ausführungsstatus wird daneben in `~/.openclaw/cron/jobs-state.json` gespeichert. Wenn Sie Cron-Definitionen in Git nachverfolgen, verfolgen Sie `jobs.json` und setzen Sie `jobs-state.json` in `.gitignore`. -- Nach der Aufteilung können ältere OpenClaw-Versionen `jobs.json` lesen, Jobs aber möglicherweise als neu behandeln, weil Laufzeitfelder jetzt in `jobs-state.json` liegen. -- Alle Cron-Ausführungen erstellen Einträge für [Hintergrundaufgaben](/de/automation/tasks). +- Job-Definitionen werden unter `~/.openclaw/cron/jobs.json` dauerhaft gespeichert, sodass Neustarts Zeitpläne nicht verlieren. +- Der Laufzeit-Ausführungsstatus wird daneben in `~/.openclaw/cron/jobs-state.json` gespeichert. Wenn Sie Cron-Definitionen in Git verfolgen, verfolgen Sie `jobs.json` und fügen Sie `jobs-state.json` zu `.gitignore` hinzu. +- Nach der Aufteilung können ältere OpenClaw-Versionen `jobs.json` lesen, behandeln Jobs aber möglicherweise als neu, weil Laufzeitfelder jetzt in `jobs-state.json` liegen. +- Alle Cron-Ausführungen erzeugen Einträge für [Hintergrundaufgaben](/de/automation/tasks). - Einmalige Jobs (`--at`) werden nach erfolgreicher Ausführung standardmäßig automatisch gelöscht. -- Isolierte Cron-Ausführungen schließen nach bestem Bemühen nach Abschluss des Laufs verfolgte Browser-Tabs/Prozesse für ihre Sitzung `cron:`, damit abgekoppelte Browser-Automatisierung keine verwaisten Prozesse hinterlässt. -- Isolierte Cron-Ausführungen schützen außerdem vor veralteten Bestätigungsantworten. Wenn das erste Ergebnis nur ein vorläufiges Status-Update ist (`on it`, `pulling everything together` und ähnliche Hinweise) und kein untergeordneter Subagent-Lauf mehr für die endgültige Antwort verantwortlich ist, fordert OpenClaw vor der Zustellung einmalig erneut das eigentliche Ergebnis an. +- Isolierte Cron-Ausführungen schließen nach bestem Bemühen verfolgte Browser-Tabs/Prozesse für ihre Sitzung `cron:`, wenn die Ausführung abgeschlossen ist, damit abgekoppelte Browser-Automatisierung keine verwaisten Prozesse hinterlässt. +- Isolierte Cron-Ausführungen schützen auch vor veralteten Bestätigungsantworten. Wenn das erste Ergebnis nur ein vorläufiges Status-Update ist (`on it`, `pulling everything together` und ähnliche Hinweise) und keine nachgeordnete Subagent-Ausführung noch für die endgültige Antwort verantwortlich ist, fordert OpenClaw einmal erneut zum eigentlichen Ergebnis auf, bevor es zugestellt wird. -Die Aufgabenabstimmung für Cron ist laufzeitgesteuert: Eine aktive Cron-Aufgabe bleibt aktiv, solange die Cron-Laufzeit diesen Job noch als laufend verfolgt, selbst wenn noch eine alte untergeordnete Sitzungszeile existiert. -Sobald die Laufzeit den Job nicht mehr verwaltet und das 5-Minuten-Toleranzfenster abgelaufen ist, kann die Wartung die Aufgabe als `lost` markieren. +Die Aufgabenabstimmung für Cron gehört der Laufzeit: Eine aktive Cron-Aufgabe bleibt aktiv, solange die Cron-Laufzeit diesen Job noch als laufend verfolgt, selbst wenn noch ein alter Kind-Sitzungseintrag existiert. +Sobald die Laufzeit den Job nicht mehr besitzt und das 5-Minuten-Gnadenfenster abgelaufen ist, kann die Wartung die Aufgabe als `lost` markieren. ## Zeitplantypen -| Art | CLI-Flag | Beschreibung | -| ------- | -------- | ------------------------------------------------------ | -| `at` | `--at` | Einmaliger Zeitstempel (ISO 8601 oder relativ wie `20m`) | -| `every` | `--every` | Festes Intervall | -| `cron` | `--cron` | 5-Feld- oder 6-Feld-Cron-Ausdruck mit optionalem `--tz` | +| Art | CLI-Flag | Beschreibung | +| ------- | -------- | ------------------------------------------------------------- | +| `at` | `--at` | Einmaliger Zeitstempel (ISO 8601 oder relativ wie `20m`) | +| `every` | `--every`| Fester Intervall | +| `cron` | `--cron` | Cron-Ausdruck mit 5 oder 6 Feldern mit optionalem `--tz` | -Zeitstempel ohne Zeitzone werden als UTC behandelt. Fügen Sie `--tz America/New_York` hinzu, um nach lokaler Uhrzeit zu planen. +Zeitstempel ohne Zeitzone werden als UTC behandelt. Fügen Sie `--tz America/New_York` für eine lokale Uhrzeitplanung hinzu. -Wiederkehrende Ausdrücke zur vollen Stunde werden automatisch um bis zu 5 Minuten gestaffelt, um Lastspitzen zu verringern. Verwenden Sie `--exact`, um exaktes Timing zu erzwingen, oder `--stagger 30s` für ein explizites Fenster. +Wiederkehrende Ausdrücke zur vollen Stunde werden automatisch um bis zu 5 Minuten gestaffelt, um Lastspitzen zu reduzieren. Verwenden Sie `--exact`, um exaktes Timing zu erzwingen, oder `--stagger 30s` für ein explizites Fenster. -### Tag-des-Monats und Wochentag verwenden ODER-Logik +### Tag des Monats und Wochentag verwenden ODER-Logik -Cron-Ausdrücke werden von [croner](https://github.com/Hexagon/croner) geparst. Wenn sowohl die Felder für Tag-des-Monats als auch für Wochentag keine Wildcards sind, trifft croner zu, wenn **eines** der beiden Felder passt — nicht beide. Das ist das Standardverhalten von Vixie-Cron. +Cron-Ausdrücke werden von [croner](https://github.com/Hexagon/croner) geparst. Wenn sowohl die Felder für Tag des Monats als auch Wochentag kein Wildcard sind, trifft croner zu, wenn **eines** der Felder passt — nicht beide. Dies ist das standardmäßige Vixie-Cron-Verhalten. ``` # Beabsichtigt: "9 Uhr am 15., aber nur wenn es ein Montag ist" -# Tatsächlich: "9 Uhr an jedem 15., UND 9 Uhr an jedem Montag" +# Tatsächlich: "9 Uhr an jedem 15., UND 9 Uhr an jedem Montag" 0 9 15 * 1 ``` -Dies wird etwa 5–6 Mal pro Monat ausgelöst statt 0–1 Mal pro Monat. OpenClaw verwendet hier das standardmäßige ODER-Verhalten von Croner. Wenn beide Bedingungen erforderlich sein sollen, verwenden Sie den `+`-Wochentagsmodifikator von Croner (`0 9 15 * +1`) oder planen Sie nach einem Feld und prüfen Sie das andere im Prompt oder Befehl Ihres Jobs. +Dies wird etwa 5–6-mal pro Monat ausgelöst statt 0–1-mal pro Monat. OpenClaw verwendet hier das standardmäßige ODER-Verhalten von Croner. Um beide Bedingungen zu verlangen, verwenden Sie den `+`-Wochentag-Modifikator von Croner (`0 9 15 * +1`) oder planen Sie nach einem Feld und prüfen Sie das andere im Prompt oder Befehl Ihres Jobs. ## Ausführungsstile -| Stil | Wert für `--session` | Läuft in | Am besten geeignet für | -| --------------- | -------------------- | ------------------------ | ------------------------------ | -| Hauptsitzung | `main` | Nächste Heartbeat-Runde | Erinnerungen, Systemereignisse | -| Isoliert | `isolated` | Dedizierte `cron:` | Berichte, Hintergrundaufgaben | -| Aktuelle Sitzung | `current` | Beim Erstellen gebunden | Wiederkehrende kontextbezogene Arbeit | +| Stil | Wert von `--session` | Läuft in | Am besten geeignet für | +| --------------- | -------------------- | ------------------------ | -------------------------------- | +| Hauptsitzung | `main` | Nächste Heartbeat-Runde | Erinnerungen, Systemereignisse | +| Isoliert | `isolated` | Dedizierte `cron:`| Berichte, Hintergrundaufgaben | +| Aktuelle Sitzung| `current` | Bei Erstellung gebunden | Kontextbewusste wiederkehrende Arbeit | | Benutzerdefinierte Sitzung | `session:custom-id` | Dauerhafte benannte Sitzung | Workflows, die auf Verlauf aufbauen | -Jobs der **Hauptsitzung** reihen ein Systemereignis ein und wecken optional den Heartbeat (`--wake now` oder `--wake next-heartbeat`). **Isolierte** Jobs führen eine dedizierte Agent-Runde mit einer frischen Sitzung aus. **Benutzerdefinierte Sitzungen** (`session:xxx`) behalten Kontext über mehrere Läufe hinweg bei und ermöglichen Workflows wie tägliche Standups, die auf vorherigen Zusammenfassungen aufbauen. +Jobs in der **Hauptsitzung** stellen ein Systemereignis in die Warteschlange und wecken optional den Heartbeat (`--wake now` oder `--wake next-heartbeat`). **Isolierte** Jobs führen eine dedizierte Agent-Runde mit einer frischen Sitzung aus. **Benutzerdefinierte Sitzungen** (`session:xxx`) behalten Kontext über mehrere Ausführungen hinweg bei und ermöglichen Workflows wie tägliche Standups, die auf vorherigen Zusammenfassungen aufbauen. -Bei isolierten Jobs umfasst der Laufzeitabbau jetzt auch das nach bestem Bemühen ausgeführte Browser-Cleanup für diese Cron-Sitzung. Fehler beim Cleanup werden ignoriert, damit das eigentliche Cron-Ergebnis weiterhin Vorrang hat. +Bei isolierten Jobs umfasst der Laufzeitabbau jetzt auch die Browser-Bereinigung nach bestem Bemühen für diese Cron-Sitzung. Fehler bei der Bereinigung werden ignoriert, sodass das tatsächliche Cron-Ergebnis weiterhin Vorrang hat. -Wenn isolierte Cron-Ausführungen Subagenten orchestrieren, bevorzugt die Zustellung außerdem die endgültige Ausgabe des Nachfahren gegenüber veraltetem vorläufigem Text des Elternteils. Wenn Nachfahren noch laufen, unterdrückt OpenClaw dieses teilweise Eltern-Update, statt es anzukündigen. +Wenn isolierte Cron-Ausführungen Subagenten orchestrieren, bevorzugt die Zustellung außerdem die endgültige Ausgabe der nachgeordneten Ausführung gegenüber veraltetem vorläufigem Text der übergeordneten Ausführung. Wenn nachgeordnete Ausführungen noch laufen, unterdrückt OpenClaw dieses partielle Update der übergeordneten Ausführung, statt es anzukündigen. -### Nutzlastoptionen für isolierte Jobs +### Payload-Optionen für isolierte Jobs - `--message`: Prompt-Text (für isolierte Jobs erforderlich) -- `--model` / `--thinking`: Überschreibungen für Modell und Denkstufe -- `--light-context`: Überspringt die Injektion der Bootstrap-Datei für den Workspace -- `--tools exec,read`: Schränkt ein, welche Tools der Job verwenden darf +- `--model` / `--thinking`: Überschreibungen für Modell und Thinking-Level +- `--light-context`: Dateiinjektion beim Workspace-Bootstrap überspringen +- `--tools exec,read`: einschränken, welche Tools der Job verwenden kann -`--model` verwendet das für diesen Job ausgewählte zulässige Modell. Wenn das angeforderte Modell nicht zulässig ist, protokolliert Cron eine Warnung und fällt stattdessen auf die Modellwahl des Agenten/Standards für den Job zurück. Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache Modellüberschreibung ohne explizite Fallback-Liste pro Job hängt den primären Agenten nicht mehr als verstecktes zusätzliches Retry-Ziel an. +`--model` verwendet das für diesen Job ausgewählte erlaubte Modell. Wenn das angeforderte Modell nicht erlaubt ist, protokolliert Cron eine Warnung und fällt stattdessen auf die Modellauswahl des Agenten/Standardmodells für den Job zurück. Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache Modellüberschreibung ohne explizite jobbezogene Fallback-Liste hängt das primäre Agentenmodell nicht mehr als verborgenes zusätzliches Wiederholungsziel an. -Die Reihenfolge der Modellwahl für isolierte Jobs ist: +Die Reihenfolge der Modellauswahl für isolierte Jobs ist: -1. Gmail-Hook-Modellüberschreibung (wenn der Lauf von Gmail kam und diese Überschreibung zulässig ist) -2. `model` in der Nutzlast pro Job +1. Modellüberschreibung des Gmail-Hooks (wenn die Ausführung von Gmail kam und diese Überschreibung erlaubt ist) +2. Jobbezogenes Payload-`model` 3. Gespeicherte Modellüberschreibung der Cron-Sitzung -4. Modellwahl des Agenten/Standards +4. Modellauswahl des Agenten/Standardmodells -Der Schnellmodus folgt ebenfalls der aufgelösten Live-Auswahl. Wenn die ausgewählte Modellkonfiguration `params.fastMode` hat, verwendet isoliertes Cron dies standardmäßig. Eine gespeicherte Sitzungsüberschreibung `fastMode` hat in beide Richtungen weiterhin Vorrang vor der Konfiguration. +Der Fast-Modus folgt ebenfalls der aufgelösten Live-Auswahl. Wenn die ausgewählte Modellkonfiguration `params.fastMode` hat, verwendet isoliertes Cron dies standardmäßig. Eine gespeicherte Sitzungsüberschreibung für `fastMode` hat in beide Richtungen weiterhin Vorrang vor der Konfiguration. -Wenn ein isolierter Lauf auf eine Live-Modellwechsel-Übergabe stößt, versucht Cron es mit dem umgeschalteten Provider/Modell erneut und speichert diese Live-Auswahl vor dem erneuten Versuch. Wenn der Wechsel auch ein neues Auth-Profil mitbringt, speichert Cron auch diese Auth-Profil-Überschreibung. Wiederholungen sind begrenzt: Nach dem ersten Versuch plus 2 Wechsel-Wiederholungen bricht Cron ab, statt endlos zu schleifen. +Wenn eine isolierte Ausführung auf eine Live-Modellwechsel-Übergabe trifft, versucht Cron es mit dem gewechselten Provider/Modell erneut und speichert diese Live-Auswahl vor dem erneuten Versuch. Wenn der Wechsel auch ein neues Auth-Profil enthält, speichert Cron auch diese Überschreibung des Auth-Profils. Wiederholungen sind begrenzt: Nach dem ersten Versuch plus 2 Wechsel-Wiederholungen bricht Cron ab, statt endlos zu schleifen. ## Zustellung und Ausgabe -| Modus | Was passiert | -| ---------- | ----------------------------------------------------------- | -| `announce` | Zustellung der Zusammenfassung an den Zielkanal (Standard für isolierte Jobs) | -| `webhook` | Sendet die Nutzlast des abgeschlossenen Ereignisses per POST an eine URL | -| `none` | Nur intern, keine Zustellung | +| Modus | Was passiert | +| ---------- | ---------------------------------------------------------------- | +| `announce` | Stellt den finalen Text ersatzweise an das Ziel zu, falls der Agent nichts gesendet hat | +| `webhook` | POSTet die Nutzlast des abgeschlossenen Ereignisses an eine URL | +| `none` | Keine Fallback-Zustellung durch den Runner | -Verwenden Sie `--announce --channel telegram --to "-1001234567890"` für die Zustellung an einen Kanal. Für Telegram-Forenthemen verwenden Sie `-1001234567890:topic:123`. Slack-/Discord-/Mattermost-Ziele sollten explizite Präfixe verwenden (`channel:`, `user:`). +Verwenden Sie `--announce --channel telegram --to "-1001234567890"` für die Zustellung an einen Kanal. Für Telegram-Forenthemen verwenden Sie `-1001234567890:topic:123`. Ziele für Slack/Discord/Mattermost sollten explizite Präfixe verwenden (`channel:`, `user:`). -Bei isolierten Jobs in Besitz von Cron verwaltet der Runner den endgültigen Zustellpfad. Der Agent wird aufgefordert, eine Klartext-Zusammenfassung zurückzugeben, und diese Zusammenfassung wird dann über `announce` oder `webhook` gesendet oder bei `none` intern behalten. `--no-deliver` gibt die Zustellung nicht an den Agenten zurück; der Lauf bleibt intern. - -Wenn in der ursprünglichen Aufgabe ausdrücklich steht, dass ein externer Empfänger benachrichtigt werden soll, sollte der Agent in seiner Ausgabe vermerken, wer/wo benachrichtigt werden soll, statt zu versuchen, direkt zu senden. +Bei isolierten Jobs ist die Chat-Zustellung gemeinsam genutzt. Wenn eine Chat-Route verfügbar ist, kann der Agent das Tool `message` verwenden, auch wenn der Job `--no-deliver` verwendet. Wenn der Agent an das konfigurierte/aktuelle Ziel sendet, überspringt OpenClaw das Fallback-`announce`. Andernfalls steuern `announce`, `webhook` und `none` nur, was der Runner nach der Agent-Runde mit der endgültigen Antwort macht. Fehlerbenachrichtigungen folgen einem separaten Zielpfad: - `cron.failureDestination` setzt einen globalen Standard für Fehlerbenachrichtigungen. - `job.delivery.failureDestination` überschreibt dies pro Job. -- Wenn keines von beiden gesetzt ist und der Job bereits über `announce` zustellt, fallen Fehlerbenachrichtigungen jetzt auf dieses primäre Ankündigungsziel zurück. +- Wenn keines von beiden gesetzt ist und der Job bereits über `announce` zustellt, fallen Fehlerbenachrichtigungen jetzt auf dieses primäre `announce`-Ziel zurück. - `delivery.failureDestination` wird nur bei Jobs mit `sessionTarget="isolated"` unterstützt, es sei denn, der primäre Zustellmodus ist `webhook`. ## CLI-Beispiele @@ -160,7 +159,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -Isolierter Job mit Überschreibung von Modell und Denkstufe: +Isolierter Job mit Modell- und Thinking-Überschreibung: ```bash openclaw cron add \ @@ -199,7 +198,7 @@ Tokens in der Query-String werden abgelehnt. ### POST /hooks/wake -Reiht ein Systemereignis für die Hauptsitzung ein: +Stellt ein Systemereignis für die Hauptsitzung in die Warteschlange: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -226,23 +225,23 @@ Felder: `message` (erforderlich), `name`, `agentId`, `wakeMode`, `deliver`, `cha ### Zugeordnete Hooks (POST /hooks/\) -Benutzerdefinierte Hook-Namen werden über `hooks.mappings` in der Konfiguration aufgelöst. Zuordnungen können beliebige Nutzlasten mit Vorlagen oder Code-Transformationen in `wake`- oder `agent`-Aktionen umwandeln. +Benutzerdefinierte Hook-Namen werden über `hooks.mappings` in der Konfiguration aufgelöst. Zuordnungen können beliebige Payloads mit Vorlagen oder Code-Transformationen in Aktionen vom Typ `wake` oder `agent` umwandeln. ### Sicherheit - Halten Sie Hook-Endpunkte hinter Loopback, Tailnet oder einem vertrauenswürdigen Reverse-Proxy. -- Verwenden Sie ein dediziertes Hook-Token; verwenden Sie Gateway-Auth-Tokens nicht erneut. +- Verwenden Sie ein dediziertes Hook-Token; verwenden Sie keine Gateway-Auth-Tokens erneut. - Halten Sie `hooks.path` auf einem dedizierten Unterpfad; `/` wird abgelehnt. -- Setzen Sie `hooks.allowedAgentIds`, um explizites `agentId`-Routing einzuschränken. -- Belassen Sie `hooks.allowRequestSessionKey=false`, sofern Sie keine vom Aufrufer ausgewählten Sitzungen benötigen. -- Wenn Sie `hooks.allowRequestSessionKey` aktivieren, setzen Sie zusätzlich `hooks.allowedSessionKeyPrefixes`, um zulässige Formen von Sitzungsschlüsseln einzuschränken. -- Hook-Nutzlasten werden standardmäßig mit Sicherheitsgrenzen umschlossen. +- Setzen Sie `hooks.allowedAgentIds`, um explizites `agentId`-Routing zu begrenzen. +- Belassen Sie `hooks.allowRequestSessionKey=false`, es sei denn, Sie benötigen vom Aufrufer ausgewählte Sitzungen. +- Wenn Sie `hooks.allowRequestSessionKey` aktivieren, setzen Sie auch `hooks.allowedSessionKeyPrefixes`, um erlaubte Formen von Sitzungsschlüsseln einzuschränken. +- Hook-Payloads werden standardmäßig mit Sicherheitsgrenzen umschlossen. ## Gmail-PubSub-Integration Verbinden Sie Gmail-Posteingangs-Trigger über Google PubSub mit OpenClaw. -**Voraussetzungen**: `gcloud` CLI, `gog` (gogcli), aktivierte OpenClaw-Hooks, Tailscale für den öffentlichen HTTPS-Endpunkt. +**Voraussetzungen**: `gcloud`-CLI, `gog` (gogcli), aktivierte OpenClaw-Hooks, Tailscale für den öffentlichen HTTPS-Endpunkt. ### Einrichtung per Assistent (empfohlen) @@ -250,11 +249,11 @@ Verbinden Sie Gmail-Posteingangs-Trigger über Google PubSub mit OpenClaw. openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Dies schreibt die Konfiguration `hooks.gmail`, aktiviert die Gmail-Voreinstellung und verwendet Tailscale Funnel für den Push-Endpunkt. +Dies schreibt die Konfiguration `hooks.gmail`, aktiviert das Gmail-Preset und verwendet Tailscale Funnel für den Push-Endpunkt. -### Automatischer Gateway-Start +### Gateway-Autostart -Wenn `hooks.enabled=true` und `hooks.gmail.account` gesetzt ist, startet das Gateway beim Booten `gog gmail watch serve` und erneuert die Überwachung automatisch. Setzen Sie `OPENCLAW_SKIP_GMAIL_WATCHER=1`, um dies zu deaktivieren. +Wenn `hooks.enabled=true` und `hooks.gmail.account` gesetzt ist, startet das Gateway beim Booten `gog gmail watch serve` und erneuert die Watch automatisch. Setzen Sie `OPENCLAW_SKIP_GMAIL_WATCHER=1`, um dies zu deaktivieren. ### Manuelle einmalige Einrichtung @@ -266,7 +265,7 @@ gcloud config set project gcloud services enable gmail.googleapis.com pubsub.googleapis.com ``` -2. Erstellen Sie ein Topic und gewähren Sie Gmail Zugriff für Push: +2. Topic erstellen und Gmail Push-Zugriff gewähren: ```bash gcloud pubsub topics create gog-gmail-watch @@ -275,7 +274,7 @@ gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ --role=roles/pubsub.publisher ``` -3. Starten Sie die Überwachung: +3. Die Watch starten: ```bash gog gmail watch start \ @@ -303,10 +302,13 @@ gog gmail watch start \ # Alle Jobs auflisten openclaw cron list +# Einen Job anzeigen, einschließlich aufgelöster Zustellroute +openclaw cron show + # Einen Job bearbeiten openclaw cron edit --message "Updated prompt" --model "opus" -# Einen Job jetzt sofort ausführen +# Einen Job jetzt erzwungen ausführen openclaw cron run # Nur ausführen, wenn fällig @@ -318,17 +320,17 @@ openclaw cron runs --id --limit 50 # Einen Job löschen openclaw cron remove -# Agent-Auswahl (Multi-Agent-Setups) +# Agent-Auswahl (Setups mit mehreren Agenten) openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops openclaw cron edit --clear-agent ``` Hinweis zur Modellüberschreibung: -- `openclaw cron add|edit --model ...` ändert das ausgewählte Modell des Jobs. -- Wenn das Modell zulässig ist, erreicht genau dieser Provider/dieses Modell den isolierten Agent-Lauf. -- Wenn es nicht zulässig ist, gibt Cron eine Warnung aus und fällt auf die Modellwahl des Agenten/Standards für den Job zurück. -- Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache `--model`-Überschreibung ohne explizite Fallback-Liste pro Job fällt nicht mehr auf den primären Agenten als stilles zusätzliches Retry-Ziel zurück. +- `openclaw cron add|edit --model ...` ändert das für den Job ausgewählte Modell. +- Wenn das Modell erlaubt ist, erreicht genau dieser Provider/dieses Modell die isolierte Agent-Ausführung. +- Wenn es nicht erlaubt ist, gibt Cron eine Warnung aus und fällt auf die Auswahl des Agenten-/Standardmodells des Jobs zurück. +- Konfigurierte Fallback-Ketten gelten weiterhin, aber eine einfache `--model`-Überschreibung ohne explizite jobbezogene Fallback-Liste fällt nicht mehr stillschweigend auf das primäre Agentenmodell als zusätzliches Wiederholungsziel zurück. ## Konfiguration @@ -350,21 +352,21 @@ Hinweis zur Modellüberschreibung: } ``` -Die Sidecar-Datei für den Laufzeitzustand wird aus `cron.store` abgeleitet: Ein `.json`-Store wie +Der Laufzeit-Zustands-Sidecar wird aus `cron.store` abgeleitet: Ein `.json`-Store wie `~/clawd/cron/jobs.json` verwendet `~/clawd/cron/jobs-state.json`, während ein Store-Pfad -ohne Suffix `.json` `-state.json` anhängt. +ohne `.json`-Suffix `-state.json` anhängt. Cron deaktivieren: `cron.enabled: false` oder `OPENCLAW_SKIP_CRON=1`. -**Wiederholung bei einmaligen Jobs**: Vorübergehende Fehler (Rate-Limit, Überlastung, Netzwerk, Serverfehler) werden mit exponentiellem Backoff bis zu 3-mal wiederholt. Permanente Fehler deaktivieren den Job sofort. +**Wiederholungen für Einmaljobs**: Vorübergehende Fehler (Rate-Limit, Überlastung, Netzwerk, Serverfehler) werden mit exponentiellem Backoff bis zu 3-mal wiederholt. Permanente Fehler werden sofort deaktiviert. -**Wiederholung bei wiederkehrenden Jobs**: Exponentieller Backoff (30 s bis 60 min) zwischen Wiederholungen. Der Backoff wird nach dem nächsten erfolgreichen Lauf zurückgesetzt. +**Wiederholungen für wiederkehrende Jobs**: Exponentieller Backoff (30 s bis 60 min) zwischen Wiederholungen. Der Backoff wird nach der nächsten erfolgreichen Ausführung zurückgesetzt. -**Wartung**: `cron.sessionRetention` (Standard `24h`) bereinigt Einträge isolierter Lauf-Sitzungen. `cron.runLog.maxBytes` / `cron.runLog.keepLines` kürzen Run-Log-Dateien automatisch. +**Wartung**: `cron.sessionRetention` (Standard `24h`) bereinigt isolierte Lauf-Sitzungseinträge. `cron.runLog.maxBytes` / `cron.runLog.keepLines` bereinigen Run-Log-Dateien automatisch. ## Fehlerbehebung -### Befehlsreihenfolge +### Befehlsleiter ```bash openclaw status @@ -380,23 +382,23 @@ openclaw doctor ### Cron wird nicht ausgelöst - Prüfen Sie `cron.enabled` und die Umgebungsvariable `OPENCLAW_SKIP_CRON`. -- Stellen Sie sicher, dass das Gateway kontinuierlich läuft. -- Verifizieren Sie bei `cron`-Zeitplänen die Zeitzone (`--tz`) im Vergleich zur Host-Zeitzone. -- `reason: not-due` in der Ausführungsausgabe bedeutet, dass der manuelle Lauf mit `openclaw cron run --due` geprüft wurde und der Job noch nicht fällig war. +- Bestätigen Sie, dass das Gateway kontinuierlich läuft. +- Prüfen Sie bei `cron`-Zeitplänen die Zeitzone (`--tz`) im Vergleich zur Zeitzone des Hosts. +- `reason: not-due` in der Ausführungsausgabe bedeutet, dass die manuelle Ausführung mit `openclaw cron run --due` geprüft wurde und der Job noch nicht fällig war. ### Cron wurde ausgelöst, aber keine Zustellung -- Der Zustellmodus `none` bedeutet, dass keine externe Nachricht erwartet wird. +- Zustellmodus `none` bedeutet, dass keine Fallback-Zustellung durch den Runner zu erwarten ist. Der Agent kann bei verfügbarer Chat-Route weiterhin direkt mit dem Tool `message` senden. - Fehlendes/ungültiges Zustellziel (`channel`/`to`) bedeutet, dass ausgehende Zustellung übersprungen wurde. - Kanal-Authentifizierungsfehler (`unauthorized`, `Forbidden`) bedeuten, dass die Zustellung durch Anmeldedaten blockiert wurde. -- Wenn der isolierte Lauf nur das stille Token (`NO_REPLY` / `no_reply`) zurückgibt, unterdrückt OpenClaw die direkte ausgehende Zustellung und auch den Fallback-Pfad mit der eingereihten Zusammenfassung, sodass nichts zurück in den Chat gepostet wird. -- Erwarten Sie bei isolierten Jobs in Besitz von Cron nicht, dass der Agent das Nachrichtentool als Fallback verwendet. Der Runner verwaltet die endgültige Zustellung; `--no-deliver` hält sie intern, statt ein direktes Senden zu erlauben. +- Wenn die isolierte Ausführung nur das stille Token (`NO_REPLY` / `no_reply`) zurückgibt, unterdrückt OpenClaw die direkte ausgehende Zustellung und auch den Fallback-Pfad der in die Warteschlange gestellten Zusammenfassung, sodass nichts zurück in den Chat gepostet wird. +- Wenn der Agent dem Nutzer selbst eine Nachricht senden soll, prüfen Sie, dass der Job eine nutzbare Route hat (`channel: "last"` mit einem vorherigen Chat oder ein expliziter Kanal/ein explizites Ziel). ### Zeitzonen-Fallstricke - Cron ohne `--tz` verwendet die Zeitzone des Gateway-Hosts. - `at`-Zeitpläne ohne Zeitzone werden als UTC behandelt. -- Heartbeat `activeHours` verwendet die konfigurierte Zeitzonenauflösung. +- Heartbeat-`activeHours` verwendet die konfigurierte Zeitzonenauflösung. ## Verwandt diff --git a/docs/de/channels/bluebubbles.md b/docs/de/channels/bluebubbles.md index af568ecfb..eaadc8973 100644 --- a/docs/de/channels/bluebubbles.md +++ b/docs/de/channels/bluebubbles.md @@ -1,43 +1,43 @@ --- read_when: - - BlueBubbles-Kanal einrichten + - Einrichten des BlueBubbles-Kanals - Fehlerbehebung bei der Webhook-Kopplung - - iMessage auf macOS konfigurieren + - Konfigurieren von iMessage unter macOS summary: iMessage über den BlueBubbles-macOS-Server (REST-Senden/-Empfangen, Tippen, Reaktionen, Kopplung, erweiterte Aktionen). title: BlueBubbles x-i18n: - generated_at: "2026-04-21T06:22:56Z" + generated_at: "2026-04-21T13:35:27Z" model: gpt-5.4 provider: openai - source_hash: b3d8d617fc86ca1b191ff4dd2ae26b464e4d3f456a79c67b484a3a76d75de0d2 + source_hash: 30ce50ae8a17140b42fa410647c367e0eefdffb1646b1ff92d8e1af63f2e1155 source_path: channels/bluebubbles.md workflow: 15 --- # BlueBubbles (macOS REST) -Status: Gebündeltes Plugin, das über HTTP mit dem BlueBubbles-macOS-Server kommuniziert. **Empfohlen für die iMessage-Integration** aufgrund der umfangreicheren API und der einfacheren Einrichtung im Vergleich zum Legacy-imsg-Kanal. +Status: gebündeltes Plugin, das über HTTP mit dem BlueBubbles-macOS-Server kommuniziert. **Empfohlen für die iMessage-Integration** aufgrund der umfangreicheren API und der einfacheren Einrichtung im Vergleich zum veralteten imsg-Kanal. ## Gebündeltes Plugin -Aktuelle OpenClaw-Versionen enthalten BlueBubbles gebündelt, daher benötigen normale paketierte Builds keinen separaten Schritt `openclaw plugins install`. +Aktuelle OpenClaw-Releases enthalten BlueBubbles bereits gebündelt, daher ist bei normalen paketierten Builds kein separater Schritt `openclaw plugins install` erforderlich. -## Übersicht +## Überblick - Läuft auf macOS über die BlueBubbles-Hilfs-App ([bluebubbles.app](https://bluebubbles.app)). -- Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Bearbeiten ist auf Tahoe derzeit defekt, und Aktualisierungen von Gruppensymbolen können Erfolg melden, ohne zu synchronisieren. +- Empfohlen/getestet: macOS Sequoia (15). macOS Tahoe (26) funktioniert; Bearbeiten ist auf Tahoe derzeit defekt, und Aktualisierungen von Gruppensymbolen können Erfolg melden, aber nicht synchronisiert werden. - OpenClaw kommuniziert damit über die REST-API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). - Eingehende Nachrichten kommen über Webhooks an; ausgehende Antworten, Tippindikatoren, Lesebestätigungen und Tapbacks sind REST-Aufrufe. - Anhänge und Sticker werden als eingehende Medien aufgenommen (und dem Agenten nach Möglichkeit bereitgestellt). - Kopplung/Allowlist funktioniert genauso wie bei anderen Kanälen (`/channels/pairing` usw.) mit `channels.bluebubbles.allowFrom` + Kopplungscodes. -- Reaktionen werden wie bei Slack/Telegram als Systemereignisse bereitgestellt, sodass Agenten sie vor einer Antwort „erwähnen“ können. +- Reaktionen werden genau wie bei Slack/Telegram als Systemereignisse dargestellt, sodass Agenten sie vor dem Antworten „erwähnen“ können. - Erweiterte Funktionen: Bearbeiten, Zurückziehen, Antwort-Threading, Nachrichteneffekte, Gruppenverwaltung. ## Schnellstart 1. Installieren Sie den BlueBubbles-Server auf Ihrem Mac (folgen Sie den Anweisungen unter [bluebubbles.app/install](https://bluebubbles.app/install)). 2. Aktivieren Sie in der BlueBubbles-Konfiguration die Web-API und legen Sie ein Passwort fest. -3. Führen Sie `openclaw onboard` aus und wählen Sie BlueBubbles aus, oder konfigurieren Sie manuell: +3. Führen Sie `openclaw onboard` aus und wählen Sie BlueBubbles aus, oder konfigurieren Sie es manuell: ```json5 { @@ -53,19 +53,19 @@ Aktuelle OpenClaw-Versionen enthalten BlueBubbles gebündelt, daher benötigen n ``` 4. Leiten Sie BlueBubbles-Webhooks an Ihr Gateway weiter (Beispiel: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). -5. Starten Sie das Gateway; es registriert den Webhook-Handler und startet die Kopplung. +5. Starten Sie das Gateway; es registriert den Webhook-Handler und beginnt mit der Kopplung. Sicherheitshinweis: - Legen Sie immer ein Webhook-Passwort fest. -- Webhook-Authentifizierung ist immer erforderlich. OpenClaw weist BlueBubbles-Webhook-Anfragen zurück, sofern sie kein Passwort/guid enthalten, das mit `channels.bluebubbles.password` übereinstimmt (zum Beispiel `?password=` oder `x-password`), unabhängig von local loopback-/Proxy-Topologie. -- Die Passwortauthentifizierung wird geprüft, bevor vollständige Webhook-Bodys gelesen/geparst werden. +- Webhook-Authentifizierung ist immer erforderlich. OpenClaw weist BlueBubbles-Webhook-Anfragen zurück, sofern sie kein Passwort/GUID enthalten, das mit `channels.bluebubbles.password` übereinstimmt (zum Beispiel `?password=` oder `x-password`), unabhängig von local loopback-/Proxy-Topologie. +- Die Passwortauthentifizierung wird geprüft, bevor vollständige Webhook-Bodies gelesen/geparst werden. -## Messages.app aktiv halten (VM- / Headless-Setups) +## Messages.app aktiv halten (VM-/headless-Setups) -Einige macOS-VM- / Always-on-Setups können dazu führen, dass Messages.app „inaktiv“ wird (eingehende Ereignisse stoppen, bis die App geöffnet/in den Vordergrund gebracht wird). Eine einfache Umgehung besteht darin, **Messages alle 5 Minuten anzustoßen** – mit einem AppleScript + LaunchAgent. +Bei einigen macOS-VM-/Always-on-Setups kann Messages.app in einen „Leerlauf“-Zustand geraten (eingehende Ereignisse stoppen, bis die App geöffnet/in den Vordergrund gebracht wird). Eine einfache Behelfslösung ist, **Messages alle 5 Minuten anzustoßen** – mit einem AppleScript + LaunchAgent. -### 1) Das AppleScript speichern +### 1) AppleScript speichern Speichern Sie dies als: @@ -125,10 +125,10 @@ Speichern Sie dies als: Hinweise: -- Dies läuft **alle 300 Sekunden** und **bei der Anmeldung**. -- Der erste Lauf kann macOS-Eingabeaufforderungen für **Automation** auslösen (`osascript` → Messages). Bestätigen Sie diese in derselben Benutzersitzung, in der der LaunchAgent ausgeführt wird. +- Dies wird **alle 300 Sekunden** und **bei der Anmeldung** ausgeführt. +- Beim ersten Ausführen können macOS-Aufforderungen für **Automation** erscheinen (`osascript` → Messages). Bestätigen Sie diese in derselben Benutzersitzung, in der der LaunchAgent läuft. -Laden Sie es: +Laden Sie ihn: ```bash launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true @@ -145,13 +145,13 @@ openclaw onboard Der Assistent fragt nach: -- **Server URL** (erforderlich): BlueBubbles-Serveradresse (z. B. `http://192.168.1.100:1234`) -- **Password** (erforderlich): API-Passwort aus den BlueBubbles-Servereinstellungen -- **Webhook path** (optional): Standard ist `/bluebubbles-webhook` -- **DM policy**: pairing, allowlist, open oder disabled -- **Allow list**: Telefonnummern, E-Mail-Adressen oder Chat-Ziele +- **Server-URL** (erforderlich): BlueBubbles-Serveradresse (z. B. `http://192.168.1.100:1234`) +- **Passwort** (erforderlich): API-Passwort aus den BlueBubbles-Servereinstellungen +- **Webhook-Pfad** (optional): Standard ist `/bluebubbles-webhook` +- **DM-Richtlinie**: pairing, allowlist, open oder disabled +- **Allowlist**: Telefonnummern, E-Mail-Adressen oder Chat-Ziele -Sie können BlueBubbles auch per CLI hinzufügen: +Sie können BlueBubbles auch über die CLI hinzufügen: ``` openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password @@ -163,24 +163,24 @@ DMs: - Standard: `channels.bluebubbles.dmPolicy = "pairing"`. - Unbekannte Absender erhalten einen Kopplungscode; Nachrichten werden ignoriert, bis sie genehmigt werden (Codes laufen nach 1 Stunde ab). -- Genehmigung über: +- Genehmigen über: - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` -- Kopplung ist der standardmäßige Token-Austausch. Details: [Kopplung](/de/channels/pairing) +- Kopplung ist der Standard-Tokenaustausch. Details: [Pairing](/de/channels/pairing) Gruppen: - `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (Standard: `allowlist`). -- `channels.bluebubbles.groupAllowFrom` steuert, wer in Gruppen Trigger auslösen kann, wenn `allowlist` gesetzt ist. +- `channels.bluebubbles.groupAllowFrom` steuert, wer in Gruppen Auslöser sein darf, wenn `allowlist` gesetzt ist. ### Anreicherung von Kontaktnamen (macOS, optional) BlueBubbles-Gruppen-Webhooks enthalten oft nur rohe Teilnehmeradressen. Wenn der Kontext `GroupMembers` stattdessen lokale Kontaktnamen anzeigen soll, können Sie unter macOS die lokale Contacts-Anreicherung aktivieren: -- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` aktiviert die Suche. Standard: `false`. -- Suchen werden nur ausgeführt, nachdem Gruppenzugriff, Befehlsautorisierung und Mention-Gating die Nachricht zugelassen haben. +- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` aktiviert die Nachschlagefunktion. Standard: `false`. +- Nachschlagen erfolgt nur, nachdem Gruppenzugriff, Befehlsautorisierung und Mention-Gating die Nachricht durchgelassen haben. - Nur unbenannte Telefonteilnehmer werden angereichert. -- Rohe Telefonnummern bleiben der Fallback, wenn keine lokale Übereinstimmung gefunden wird. +- Rohe Telefonnummern bleiben die Rückfalloption, wenn keine lokale Übereinstimmung gefunden wird. ```json5 { @@ -194,11 +194,11 @@ BlueBubbles-Gruppen-Webhooks enthalten oft nur rohe Teilnehmeradressen. Wenn der ### Mention-Gating (Gruppen) -BlueBubbles unterstützt Mention-Gating für Gruppenchats und entspricht damit dem Verhalten von iMessage/WhatsApp: +BlueBubbles unterstützt Mention-Gating für Gruppenchats, entsprechend dem Verhalten von iMessage/WhatsApp: - Verwendet `agents.list[].groupChat.mentionPatterns` (oder `messages.groupChat.mentionPatterns`) zur Erkennung von Erwähnungen. - Wenn `requireMention` für eine Gruppe aktiviert ist, antwortet der Agent nur, wenn er erwähnt wird. -- Kontrollbefehle von autorisierten Absendern umgehen das Mention-Gating. +- Steuerbefehle von autorisierten Absendern umgehen das Mention-Gating. Konfiguration pro Gruppe: @@ -210,22 +210,22 @@ Konfiguration pro Gruppe: groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // Standard für alle Gruppen - "iMessage;-;chat123": { requireMention: false }, // Überschreibung für bestimmte Gruppe + "iMessage;-;chat123": { requireMention: false }, // Überschreibung für eine bestimmte Gruppe }, }, }, } ``` -### Command-Gating +### Befehls-Gating -- Kontrollbefehle (z. B. `/config`, `/model`) erfordern eine Autorisierung. +- Steuerbefehle (z. B. `/config`, `/model`) erfordern Autorisierung. - Verwendet `allowFrom` und `groupAllowFrom`, um die Befehlsautorisierung zu bestimmen. -- Autorisierte Absender können Kontrollbefehle auch ohne Erwähnung in Gruppen ausführen. +- Autorisierte Absender können Steuerbefehle auch ohne Erwähnung in Gruppen ausführen. -### Systemprompt pro Gruppe +### System-Prompt pro Gruppe -Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert einen optionalen String `systemPrompt`. Der Wert wird bei jeder Runde, die eine Nachricht in dieser Gruppe verarbeitet, in den Systemprompt des Agenten eingefügt, sodass Sie pro Gruppe Persona- oder Verhaltensregeln festlegen können, ohne Agent-Prompts zu bearbeiten: +Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert eine optionale Zeichenfolge `systemPrompt`. Der Wert wird bei jeder Verarbeitung einer Nachricht in dieser Gruppe in den System-Prompt des Agenten eingefügt, sodass Sie pro Gruppe Persona- oder Verhaltensregeln festlegen können, ohne Agent-Prompts zu bearbeiten: ```json5 { @@ -233,7 +233,7 @@ Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert einen optionalen bluebubbles: { groups: { "iMessage;-;chat123": { - systemPrompt: "Halte Antworten unter 3 Sätzen. Übernimm den lockeren Ton der Gruppe.", + systemPrompt: "Halte Antworten unter 3 Sätzen. Spiegele den lockeren Ton der Gruppe.", }, }, }, @@ -241,11 +241,11 @@ Jeder Eintrag unter `channels.bluebubbles.groups.*` akzeptiert einen optionalen } ``` -Der Schlüssel entspricht allem, was BlueBubbles als `chatGuid` / `chatIdentifier` / numerische `chatId` für die Gruppe meldet, und ein Platzhalter-Eintrag `"*"` stellt einen Standard für jede Gruppe ohne exakte Übereinstimmung bereit (dasselbe Muster wird für `requireMention` und Tool-Richtlinien pro Gruppe verwendet). Exakte Übereinstimmungen haben immer Vorrang vor dem Platzhalter. DMs ignorieren dieses Feld; verwenden Sie stattdessen Anpassungen auf Agenten- oder Kontoebene. +Der Schlüssel entspricht dem, was BlueBubbles für die Gruppe als `chatGuid` / `chatIdentifier` / numerische `chatId` meldet, und ein Platzhaltereintrag `"*"` stellt einen Standard für jede Gruppe ohne exakte Übereinstimmung bereit (dasselbe Muster wird von `requireMention` und gruppenspezifischen Tool-Richtlinien verwendet). Exakte Übereinstimmungen haben immer Vorrang vor dem Platzhalter. DMs ignorieren dieses Feld; verwenden Sie stattdessen Prompt-Anpassungen auf Agenten- oder Kontoebene. -#### Durchgearbeitetes Beispiel: Thread-Antworten und Tapback-Reaktionen (Private API) +#### Ausgearbeitetes Beispiel: Thread-Antworten und Tapback-Reaktionen (Private API) -Wenn die BlueBubbles Private API aktiviert ist, kommen eingehende Nachrichten mit kurzen Nachrichten-IDs an (zum Beispiel `[[reply_to:5]]`), und der Agent kann `action=reply` aufrufen, um in eine bestimmte Nachricht zu threaden, oder `action=react`, um ein Tapback zu setzen. Ein `systemPrompt` pro Gruppe ist eine zuverlässige Möglichkeit, damit der Agent das richtige Tool auswählt: +Mit aktivierter BlueBubbles Private API kommen eingehende Nachrichten mit kurzen Nachrichten-IDs an (zum Beispiel `[[reply_to:5]]`), und der Agent kann `action=reply` aufrufen, um in eine bestimmte Nachricht zu threaden, oder `action=react`, um ein Tapback zu setzen. Ein `systemPrompt` pro Gruppe ist eine zuverlässige Möglichkeit, damit der Agent das richtige Tool auswählt: ```json5 { @@ -255,12 +255,12 @@ Wenn die BlueBubbles Private API aktiviert ist, kommen eingehende Nachrichten mi "iMessage;+;chat-family": { systemPrompt: [ "Wenn du in dieser Gruppe antwortest, rufe immer action=reply mit der", - "messageId `[[reply_to:N]]` aus dem Kontext auf, damit deine Antwort", - "unter der auslösenden Nachricht eingeordnet wird. Sende niemals eine neue, nicht verknüpfte Nachricht.", + "[[reply_to:N]] messageId aus dem Kontext auf, damit deine Antwort", + "unter der auslösenden Nachricht gethreadet wird. Sende niemals eine neue, nicht verknüpfte Nachricht.", "", "Verwende für kurze Bestätigungen ('ok', 'verstanden', 'bin dran')", "action=react mit einem passenden Tapback-Emoji (❤️, 👍, 😂, ‼️, ❓)", - "anstatt eine Textantwort zu senden.", + "anstelle einer Textantwort.", ].join(" "), }, }, @@ -269,20 +269,20 @@ Wenn die BlueBubbles Private API aktiviert ist, kommen eingehende Nachrichten mi } ``` -Tapback-Reaktionen und Thread-Antworten erfordern beide die BlueBubbles Private API; siehe [Erweiterte Aktionen](#advanced-actions) und [Nachrichten-IDs](#message-ids-short-vs-full) für die zugrunde liegende Mechanik. +Tapback-Reaktionen und Thread-Antworten erfordern beide die BlueBubbles Private API; die zugrunde liegenden Mechanismen finden Sie unter [Erweiterte Aktionen](#advanced-actions) und [Nachrichten-IDs](#message-ids-short-vs-full). ## ACP-Gesprächsbindungen -BlueBubbles-Chats können in dauerhafte ACP-Workspaces umgewandelt werden, ohne die Transportschicht zu ändern. +BlueBubbles-Chats können in dauerhafte ACP-Arbeitsbereiche umgewandelt werden, ohne die Transportebene zu ändern. Schneller Operator-Ablauf: - Führen Sie `/acp spawn codex --bind here` innerhalb des DM- oder erlaubten Gruppenchats aus. -- Zukünftige Nachrichten in derselben BlueBubbles-Konversation werden an die erzeugte ACP-Sitzung weitergeleitet. +- Künftige Nachrichten in derselben BlueBubbles-Konversation werden an die erzeugte ACP-Sitzung weitergeleitet. - `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung an Ort und Stelle zurück. - `/acp close` schließt die ACP-Sitzung und entfernt die Bindung. -Konfigurierte persistente Bindungen werden ebenfalls über Top-Level-Einträge `bindings[]` mit `type: "acp"` und `match.channel: "bluebubbles"` unterstützt. +Konfigurierte persistente Bindungen werden auch über Top-Level-Einträge `bindings[]` mit `type: "acp"` und `match.channel: "bluebubbles"` unterstützt. `match.peer.id` kann jede unterstützte BlueBubbles-Zielform verwenden: @@ -291,7 +291,7 @@ Konfigurierte persistente Bindungen werden ebenfalls über Top-Level-Einträge ` - `chat_guid:` - `chat_identifier:` -Für stabile Gruppenbindungen sollten Sie `chat_id:*` oder `chat_identifier:*` bevorzugen. +Für stabile Gruppenbindungen bevorzugen Sie `chat_id:*` oder `chat_identifier:*`. Beispiel: @@ -323,13 +323,13 @@ Beispiel: } ``` -Siehe [ACP Agents](/de/tools/acp-agents) für gemeinsames ACP-Bindungsverhalten. +Siehe [ACP Agents](/de/tools/acp-agents) für das gemeinsame Verhalten von ACP-Bindungen. -## Tippen + Lesebestätigungen +## Tippindikatoren + Lesebestätigungen - **Tippindikatoren**: Werden automatisch vor und während der Antwortgenerierung gesendet. - **Lesebestätigungen**: Gesteuert durch `channels.bluebubbles.sendReadReceipts` (Standard: `true`). -- **Tippindikatoren**: OpenClaw sendet Ereignisse für den Tippbeginn; BlueBubbles beendet das Tippen beim Senden oder nach einem Timeout automatisch (manuelles Stoppen über DELETE ist unzuverlässig). +- **Tippindikatoren**: OpenClaw sendet Tippstart-Ereignisse; BlueBubbles entfernt den Tippstatus beim Senden oder per Timeout automatisch (manuelles Stoppen per DELETE ist unzuverlässig). ```json5 { @@ -351,12 +351,12 @@ BlueBubbles unterstützt erweiterte Nachrichtenaktionen, wenn sie in der Konfigu bluebubbles: { actions: { reactions: true, // Tapbacks (Standard: true) - edit: true, // gesendete Nachrichten bearbeiten (macOS 13+, auf macOS 26 Tahoe defekt) + edit: true, // gesendete Nachrichten bearbeiten (macOS 13+, defekt unter macOS 26 Tahoe) unsend: true, // Nachrichten zurückziehen (macOS 13+) - reply: true, // Antwort-Threading nach Nachrichten-GUID + reply: true, // Antwort-Threading per Nachrichten-GUID sendWithEffect: true, // Nachrichteneffekte (slam, loud usw.) renameGroup: true, // Gruppenchats umbenennen - setGroupIcon: true, // Gruppenchatsymbol/-foto festlegen (instabil auf macOS 26 Tahoe) + setGroupIcon: true, // Gruppenchatsymbol/-foto festlegen (unzuverlässig unter macOS 26 Tahoe) addParticipant: true, // Teilnehmer zu Gruppen hinzufügen removeParticipant: true, // Teilnehmer aus Gruppen entfernen leaveGroup: true, // Gruppenchats verlassen @@ -375,29 +375,127 @@ Verfügbare Aktionen: - **reply**: Auf eine bestimmte Nachricht antworten (`messageId`, `text`, `to`) - **sendWithEffect**: Mit iMessage-Effekt senden (`text`, `to`, `effectId`) - **renameGroup**: Einen Gruppenchat umbenennen (`chatGuid`, `displayName`) -- **setGroupIcon**: Das Symbol/Foto eines Gruppenchats festlegen (`chatGuid`, `media`) — instabil auf macOS 26 Tahoe (API kann Erfolg zurückgeben, aber das Symbol synchronisiert nicht). +- **setGroupIcon**: Das Symbol/Foto eines Gruppenchats festlegen (`chatGuid`, `media`) — unzuverlässig unter macOS 26 Tahoe (die API kann Erfolg zurückgeben, aber das Symbol wird nicht synchronisiert). - **addParticipant**: Jemanden zu einer Gruppe hinzufügen (`chatGuid`, `address`) - **removeParticipant**: Jemanden aus einer Gruppe entfernen (`chatGuid`, `address`) - **leaveGroup**: Einen Gruppenchat verlassen (`chatGuid`) - **upload-file**: Medien/Dateien senden (`to`, `buffer`, `filename`, `asVoice`) - - Sprachmemos: Setzen Sie `asVoice: true` mit **MP3**- oder **CAF**-Audio, um es als iMessage-Sprachnachricht zu senden. BlueBubbles konvertiert MP3 → CAF beim Senden von Sprachmemos. -- Legacy-Alias: `sendAttachment` funktioniert weiterhin, aber `upload-file` ist der kanonische Aktionsname. + - Sprachnachrichten: Setzen Sie `asVoice: true` mit **MP3**- oder **CAF**-Audio, um als iMessage-Sprachnachricht zu senden. BlueBubbles konvertiert beim Senden von Sprachnotizen MP3 → CAF. +- Veralteter Alias: `sendAttachment` funktioniert weiterhin, aber `upload-file` ist der kanonische Aktionsname. ### Nachrichten-IDs (kurz vs. vollständig) OpenClaw kann _kurze_ Nachrichten-IDs (z. B. `1`, `2`) bereitstellen, um Tokens zu sparen. - `MessageSid` / `ReplyToId` können kurze IDs sein. -- `MessageSidFull` / `ReplyToIdFull` enthalten die vollständigen Provider-IDs. -- Kurze IDs sind im Speicher; sie können nach einem Neustart oder einer Cache-Bereinigung ablaufen. -- Aktionen akzeptieren kurze oder vollständige `messageId`, aber kurze IDs erzeugen einen Fehler, wenn sie nicht mehr verfügbar sind. +- `MessageSidFull` / `ReplyToIdFull` enthalten die vollständigen IDs des Providers. +- Kurze IDs sind im Speicher; sie können bei einem Neustart oder bei Cache-Verdrängung verfallen. +- Aktionen akzeptieren kurze oder vollständige `messageId`, aber kurze IDs führen zu Fehlern, wenn sie nicht mehr verfügbar sind. Verwenden Sie vollständige IDs für dauerhafte Automatisierungen und Speicherung: -- Templates: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` +- Vorlagen: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` - Kontext: `MessageSidFull` / `ReplyToIdFull` in eingehenden Payloads -Siehe [Konfiguration](/de/gateway/configuration) für Template-Variablen. +Siehe [Konfiguration](/de/gateway/configuration) für Vorlagenvariablen. + +## Zusammenführen von Split-Send-DMs (Befehl + URL in einer Eingabe) + +Wenn ein Benutzer in iMessage einen Befehl und eine URL zusammen eingibt – z. B. `Dump https://example.com/article` – teilt Apple das Senden in **zwei separate Webhook-Zustellungen** auf: + +1. Eine Textnachricht (`"Dump"`). +2. Eine URL-Vorschau-Bubble (`"https://..."`) mit OG-Vorschaubildern als Anhänge. + +Die beiden Webhooks treffen bei OpenClaw auf den meisten Setups mit etwa 0,8–2,0 s Abstand ein. Ohne Zusammenführung erhält der Agent in Turn 1 nur den Befehl, antwortet (oft mit „schick mir die URL“), und sieht die URL erst in Turn 2 – zu diesem Zeitpunkt ist der Befehlskontext bereits verloren. + +`channels.bluebubbles.coalesceSameSenderDms` aktiviert für DMs das Zusammenführen aufeinanderfolgender Webhooks desselben Absenders in einen einzigen Agent-Turn. Gruppenchats bleiben weiter nach Nachricht getrennt, damit die Turn-Struktur mit mehreren Benutzern erhalten bleibt. + +### Wann aktivieren + +Aktivieren Sie dies, wenn: + +- Sie Skills bereitstellen, die `Befehl + Payload` in einer Nachricht erwarten (dump, paste, save, queue usw.). +- Ihre Benutzer URLs, Bilder oder lange Inhalte zusammen mit Befehlen einfügen. +- Sie die zusätzliche DM-Turn-Latenz akzeptieren können (siehe unten). + +Lassen Sie es deaktiviert, wenn: + +- Sie minimale Befehlslatenz für einwortige DM-Trigger benötigen. +- Alle Ihre Abläufe One-Shot-Befehle ohne nachfolgende Payloads sind. + +### Aktivierung + +```json5 +{ + channels: { + bluebubbles: { + coalesceSameSenderDms: true, // aktivieren (Standard: false) + }, + }, +} +``` + +Mit aktiviertem Flag und ohne explizites `messages.inbound.byChannel.bluebubbles` erweitert sich das Debounce-Fenster auf **2500 ms** (der Standard ohne Zusammenführung beträgt 500 ms). Das breitere Fenster ist erforderlich – Apples Split-Send-Takt von 0,8–2,0 s passt nicht in das engere Standardfenster. + +So passen Sie das Fenster selbst an: + +```json5 +{ + messages: { + inbound: { + byChannel: { + // 2500 ms funktionieren für die meisten Setups; erhöhen Sie auf 4000 ms, + // wenn Ihr Mac langsam ist oder unter Speicherdruck steht + // (die beobachtete Lücke kann dann über 2 s hinausgehen). + bluebubbles: 2500, + }, + }, + }, +} +``` + +### Abwägungen + +- **Zusätzliche Latenz für DM-Steuerbefehle.** Mit aktiviertem Flag warten DM-Steuerbefehle (wie `Dump`, `Save` usw.) nun bis zur Länge des Debounce-Fensters vor dem Versand, falls ein Payload-Webhook folgt. Befehle in Gruppenchats werden weiterhin sofort versendet. +- **Zusammengeführte Ausgabe ist begrenzt** – zusammengeführter Text ist auf 4000 Zeichen mit einem expliziten Marker `…[truncated]` begrenzt; Anhänge sind auf 20 begrenzt; Quelleneinträge sind auf 10 begrenzt (darüber hinaus bleiben erster und neuester erhalten). Jede Quell-`messageId` erreicht weiterhin die Inbound-Deduplizierung, sodass ein späteres MessagePoller-Replay eines einzelnen Ereignisses als Duplikat erkannt wird. +- **Opt-in, pro Kanal.** Andere Kanäle (Telegram, WhatsApp, Slack, …) sind nicht betroffen. + +### Szenarien und was der Agent sieht + +| Benutzer gibt ein | Apple liefert | Flag aus (Standard) | Flag an + 2500-ms-Fenster | +| ------------------------------------------------------------------- | ------------------------- | --------------------------------------- | ---------------------------------------------------------------------- | +| `Dump https://example.com` (einmal senden) | 2 Webhooks mit ~1 s Abstand | Zwei Agent-Turns: nur „Dump“, dann URL | Ein Turn: zusammengeführter Text `Dump https://example.com` | +| `Save this 📎image.jpg caption` (Anhang + Text) | 2 Webhooks | Zwei Turns | Ein Turn: Text + Bild | +| `/status` (eigenständiger Befehl) | 1 Webhook | Sofortiger Versand | **Wartet bis zum Fensterende, dann Versand** | +| Nur URL eingefügt | 1 Webhook | Sofortiger Versand | Sofortiger Versand (nur ein Eintrag im Bucket) | +| Text + URL als zwei bewusst getrennte Nachrichten, Minuten auseinander gesendet | 2 Webhooks außerhalb des Fensters | Zwei Turns | Zwei Turns (Fenster läuft dazwischen ab) | +| Schnelle Flut (>10 kleine DMs innerhalb des Fensters) | N Webhooks | N Turns | Ein Turn, begrenzte Ausgabe (erster + neuester, Text-/Anhang-Limits angewendet) | + +### Fehlerbehebung für das Zusammenführen von Split-Sends + +Wenn das Flag aktiviert ist und Split-Sends trotzdem als zwei Turns ankommen, prüfen Sie jede Ebene: + +1. **Konfiguration tatsächlich geladen.** + + ``` + grep coalesceSameSenderDms ~/.openclaw/openclaw.json + ``` + + Dann `openclaw gateway restart` – das Flag wird bei der Erstellung der Debouncer-Registry eingelesen. + +2. **Debounce-Fenster breit genug für Ihr Setup.** Sehen Sie sich das BlueBubbles-Serverlog unter `~/Library/Logs/bluebubbles-server/main.log` an: + + ``` + grep -E "Dispatching event to webhook" main.log | tail -20 + ``` + + Messen Sie die Lücke zwischen dem Versand des Textes im Stil von `"Dump"` und dem nachfolgenden Versand `"https://..."; Attachments:`. Erhöhen Sie `messages.inbound.byChannel.bluebubbles`, sodass diese Lücke sicher abgedeckt ist. + +3. **JSONL-Zeitstempel der Sitzung ≠ Webhook-Ankunft.** Zeitstempel von Sitzungsereignissen (`~/.openclaw/agents//sessions/*.jsonl`) zeigen den Zeitpunkt, zu dem das Gateway eine Nachricht an den Agenten übergibt, **nicht** den Zeitpunkt, zu dem der Webhook eingetroffen ist. Eine in die Warteschlange gestellte zweite Nachricht mit dem Tag `[Queued messages while agent was busy]` bedeutet, dass der erste Turn noch lief, als der zweite Webhook eintraf – der Coalesce-Bucket war bereits geleert. Stimmen Sie das Fenster auf das BB-Serverlog ab, nicht auf das Sitzungslog. + +4. **Speicherdruck verlangsamt den Antwortversand.** Auf kleineren Maschinen (8 GB) können Agent-Turns so lange dauern, dass der Coalesce-Bucket geleert wird, bevor die Antwort fertig ist, und die URL als zweiter Turn in der Warteschlange landet. Prüfen Sie `memory_pressure` und `ps -o rss -p $(pgrep openclaw-gateway)`; wenn das Gateway über ~500 MB RSS liegt und der Compressor aktiv ist, schließen Sie andere schwere Prozesse oder wechseln Sie auf einen größeren Host. + +5. **Senden mit Antwortzitat ist ein anderer Pfad.** Wenn der Benutzer `Dump` als **Antwort** auf eine vorhandene URL-Bubble getippt hat (iMessage zeigt auf der Dump-Bubble ein Abzeichen „1 Reply“), befindet sich die URL in `replyToBody`, nicht in einem zweiten Webhook. Zusammenführung greift hier nicht – das ist ein Thema für Skill/Prompt, nicht für den Debouncer. ## Block-Streaming @@ -416,8 +514,8 @@ Steuern Sie, ob Antworten als einzelne Nachricht gesendet oder in Blöcken gestr ## Medien + Limits - Eingehende Anhänge werden heruntergeladen und im Medien-Cache gespeichert. -- Medienobergrenze über `channels.bluebubbles.mediaMaxMb` für ein- und ausgehende Medien (Standard: 8 MB). -- Ausgehender Text wird auf `channels.bluebubbles.textChunkLimit` gestückelt (Standard: 4000 Zeichen). +- Medienlimit über `channels.bluebubbles.mediaMaxMb` für eingehende und ausgehende Medien (Standard: 8 MB). +- Ausgehender Text wird auf `channels.bluebubbles.textChunkLimit` segmentiert (Standard: 4000 Zeichen). ## Konfigurationsreferenz @@ -425,29 +523,30 @@ Vollständige Konfiguration: [Konfiguration](/de/gateway/configuration) Provider-Optionen: -- `channels.bluebubbles.enabled`: Den Kanal aktivieren/deaktivieren. -- `channels.bluebubbles.serverUrl`: BlueBubbles-REST-API-Basis-URL. +- `channels.bluebubbles.enabled`: Kanal aktivieren/deaktivieren. +- `channels.bluebubbles.serverUrl`: Basis-URL der BlueBubbles-REST-API. - `channels.bluebubbles.password`: API-Passwort. - `channels.bluebubbles.webhookPath`: Pfad des Webhook-Endpunkts (Standard: `/bluebubbles-webhook`). - `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (Standard: `pairing`). - `channels.bluebubbles.allowFrom`: DM-Allowlist (Handles, E-Mails, E.164-Nummern, `chat_id:*`, `chat_guid:*`). - `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (Standard: `allowlist`). -- `channels.bluebubbles.groupAllowFrom`: Absender-Allowlist für Gruppen. -- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Unter macOS unbenannte Gruppenteilnehmer optional aus lokalen Contacts anreichern, nachdem das Gating bestanden wurde. Standard: `false`. +- `channels.bluebubbles.groupAllowFrom`: Allowlist für Gruppenabsender. +- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Unter macOS unbenannte Gruppenteilnehmer nach erfolgreichem Gating optional mit lokalen Kontakten anreichern. Standard: `false`. - `channels.bluebubbles.groups`: Konfiguration pro Gruppe (`requireMention` usw.). - `channels.bluebubbles.sendReadReceipts`: Lesebestätigungen senden (Standard: `true`). - `channels.bluebubbles.blockStreaming`: Block-Streaming aktivieren (Standard: `false`; erforderlich für Streaming-Antworten). - `channels.bluebubbles.textChunkLimit`: Größe ausgehender Blöcke in Zeichen (Standard: 4000). -- `channels.bluebubbles.sendTimeoutMs`: Timeout pro Anfrage in ms für ausgehende Textsendungen über `/api/v1/message/text` (Standard: 30000). Erhöhen Sie diesen Wert auf macOS-26-Setups, bei denen iMessage-Sendungen über die Private API im iMessage-Framework 60+ Sekunden hängen können; zum Beispiel `45000` oder `60000`. Probes, Chat-Lookups, Reaktionen, Bearbeitungen und Zustandsprüfungen behalten derzeit den kürzeren Standardwert von 10 s; eine Ausweitung auf Reaktionen und Bearbeitungen ist als Folgearbeit geplant. Überschreibung pro Konto: `channels.bluebubbles.accounts..sendTimeoutMs`. -- `channels.bluebubbles.chunkMode`: `length` (Standard) teilt nur, wenn `textChunkLimit` überschritten wird; `newline` teilt an Leerzeilen (Absatzgrenzen) vor der Längenteilung. -- `channels.bluebubbles.mediaMaxMb`: Medienobergrenze für ein- und ausgehende Medien in MB (Standard: 8). +- `channels.bluebubbles.sendTimeoutMs`: Timeout pro Anfrage in ms für ausgehende Textsendungen über `/api/v1/message/text` (Standard: 30000). Erhöhen Sie dies auf macOS-26-Setups, bei denen Private-API-iMessage-Sendungen im iMessage-Framework 60+ Sekunden hängen können, z. B. auf `45000` oder `60000`. Probes, Chat-Lookups, Reaktionen, Bearbeitungen und Health Checks behalten derzeit den kürzeren Standard von 10 s; eine Ausweitung auf Reaktionen und Bearbeitungen ist als Follow-up geplant. Überschreibung pro Konto: `channels.bluebubbles.accounts..sendTimeoutMs`. +- `channels.bluebubbles.chunkMode`: `length` (Standard) teilt nur, wenn `textChunkLimit` überschritten wird; `newline` teilt an Leerzeilen (Absatzgrenzen) vor der Längensegmentierung. +- `channels.bluebubbles.mediaMaxMb`: Medienlimit für ein- und ausgehende Medien in MB (Standard: 8). - `channels.bluebubbles.mediaLocalRoots`: Explizite Allowlist absoluter lokaler Verzeichnisse, die für ausgehende lokale Medienpfade erlaubt sind. Das Senden lokaler Pfade wird standardmäßig verweigert, sofern dies nicht konfiguriert ist. Überschreibung pro Konto: `channels.bluebubbles.accounts..mediaLocalRoots`. +- `channels.bluebubbles.coalesceSameSenderDms`: Führt aufeinanderfolgende DM-Webhooks desselben Absenders zu einem Agent-Turn zusammen, sodass Apples Split-Send von Text+URL als eine einzelne Nachricht ankommt (Standard: `false`). Siehe [Zusammenführen von Split-Send-DMs](#coalescing-split-send-dms-command--url-in-one-composition) für Szenarien, Fenstertuning und Abwägungen. Erweitert das Standard-Debounce-Fenster für eingehende Nachrichten von 500 ms auf 2500 ms, wenn aktiviert, ohne ein explizites `messages.inbound.byChannel.bluebubbles`. - `channels.bluebubbles.historyLimit`: Maximale Anzahl an Gruppennachrichten für den Kontext (0 deaktiviert). -- `channels.bluebubbles.dmHistoryLimit`: DM-Verlaufslimit. +- `channels.bluebubbles.dmHistoryLimit`: Verlaufslimit für DMs. - `channels.bluebubbles.actions`: Bestimmte Aktionen aktivieren/deaktivieren. - `channels.bluebubbles.accounts`: Multi-Account-Konfiguration. -Verwandte globale Optionen: +Zugehörige globale Optionen: - `agents.list[].groupChat.mentionPatterns` (oder `messages.groupChat.mentionPatterns`). - `messages.responsePrefix`. @@ -460,31 +559,32 @@ Bevorzugen Sie `chat_guid` für stabiles Routing: - `chat_id:123` - `chat_identifier:...` - Direkte Handles: `+15555550123`, `user@example.com` - - Wenn für ein direktes Handle noch kein DM-Chat existiert, erstellt OpenClaw einen über `POST /api/v1/chat/new`. Dafür muss die BlueBubbles Private API aktiviert sein. + - Wenn ein direkter Handle keinen bestehenden DM-Chat hat, erstellt OpenClaw einen über `POST /api/v1/chat/new`. Dafür muss die BlueBubbles Private API aktiviert sein. ## Sicherheit - Webhook-Anfragen werden authentifiziert, indem `guid`-/`password`-Query-Parameter oder Header mit `channels.bluebubbles.password` verglichen werden. - Halten Sie das API-Passwort und den Webhook-Endpunkt geheim (behandeln Sie sie wie Zugangsdaten). -- Es gibt keinen Localhost-Bypass für die BlueBubbles-Webhook-Authentifizierung. Wenn Sie Webhook-Datenverkehr proxyen, behalten Sie das BlueBubbles-Passwort Ende-zu-Ende in der Anfrage bei. `gateway.trustedProxies` ersetzt `channels.bluebubbles.password` hier nicht. Siehe [Gateway-Sicherheit](/de/gateway/security#reverse-proxy-configuration). +- Es gibt keine localhost-Umgehung für die BlueBubbles-Webhook-Authentifizierung. Wenn Sie Webhook-Traffic per Proxy weiterleiten, behalten Sie das BlueBubbles-Passwort Ende-zu-Ende in der Anfrage bei. `gateway.trustedProxies` ersetzt `channels.bluebubbles.password` hier nicht. Siehe [Gateway-Sicherheit](/de/gateway/security#reverse-proxy-configuration). - Aktivieren Sie HTTPS + Firewall-Regeln auf dem BlueBubbles-Server, wenn Sie ihn außerhalb Ihres LAN bereitstellen. ## Fehlerbehebung - Wenn Tipp-/Leseereignisse nicht mehr funktionieren, prüfen Sie die BlueBubbles-Webhook-Logs und vergewissern Sie sich, dass der Gateway-Pfad mit `channels.bluebubbles.webhookPath` übereinstimmt. -- Kopplungscodes laufen nach einer Stunde ab; verwenden Sie `openclaw pairing list bluebubbles` und `openclaw pairing approve bluebubbles `. +- Kopplungscodes verfallen nach einer Stunde; verwenden Sie `openclaw pairing list bluebubbles` und `openclaw pairing approve bluebubbles `. - Reaktionen erfordern die BlueBubbles Private API (`POST /api/v1/message/react`); stellen Sie sicher, dass die Serverversion sie bereitstellt. - Bearbeiten/Zurückziehen erfordern macOS 13+ und eine kompatible BlueBubbles-Serverversion. Unter macOS 26 (Tahoe) ist Bearbeiten derzeit aufgrund von Änderungen an der Private API defekt. -- Aktualisierungen von Gruppensymbolen können unter macOS 26 (Tahoe) instabil sein: Die API kann Erfolg zurückgeben, aber das neue Symbol synchronisiert nicht. -- OpenClaw blendet bekannte defekte Aktionen basierend auf der macOS-Version des BlueBubbles-Servers automatisch aus. Wenn Bearbeiten unter macOS 26 (Tahoe) weiterhin angezeigt wird, deaktivieren Sie es manuell mit `channels.bluebubbles.actions.edit=false`. +- Aktualisierungen von Gruppensymbolen können unter macOS 26 (Tahoe) unzuverlässig sein: Die API kann Erfolg melden, aber das neue Symbol wird nicht synchronisiert. +- OpenClaw blendet bekannte defekte Aktionen anhand der macOS-Version des BlueBubbles-Servers automatisch aus. Wenn Bearbeiten unter macOS 26 (Tahoe) weiterhin angezeigt wird, deaktivieren Sie es manuell mit `channels.bluebubbles.actions.edit=false`. +- `coalesceSameSenderDms` ist aktiviert, aber Split-Sends (z. B. `Dump` + URL) kommen weiterhin als zwei Turns an: siehe die Checkliste zur [Fehlerbehebung für das Zusammenführen von Split-Sends](#split-send-coalescing-troubleshooting) — häufige Ursachen sind ein zu enges Debounce-Fenster, Sitzungslog-Zeitstempel, die fälschlich als Webhook-Ankunft interpretiert werden, oder ein Senden mit Antwortzitat (das `replyToBody` verwendet, nicht einen zweiten Webhook). - Für Status-/Health-Informationen: `openclaw status --all` oder `openclaw status --deep`. -Für allgemeine Referenzen zum Kanalablauf siehe [Kanäle](/de/channels) und den Leitfaden [Plugins](/de/tools/plugin). +Eine allgemeine Referenz zum Kanal-Workflow finden Sie unter [Kanäle](/de/channels) und im Leitfaden [Plugins](/de/tools/plugin). ## Verwandt - [Kanalübersicht](/de/channels) — alle unterstützten Kanäle -- [Kopplung](/de/channels/pairing) — DM-Authentifizierung und Kopplungsablauf -- [Gruppen](/de/channels/groups) — Verhalten von Gruppenchats und Mention-Gating +- [Pairing](/de/channels/pairing) — DM-Authentifizierung und Kopplungsablauf +- [Gruppen](/de/channels/groups) — Verhalten in Gruppenchats und Mention-Gating - [Kanal-Routing](/de/channels/channel-routing) — Sitzungsrouting für Nachrichten - [Sicherheit](/de/gateway/security) — Zugriffsmodell und Härtung diff --git a/docs/de/channels/slack.md b/docs/de/channels/slack.md index d6eca36ae..c17c71001 100644 --- a/docs/de/channels/slack.md +++ b/docs/de/channels/slack.md @@ -4,10 +4,10 @@ read_when: summary: Slack-Einrichtung und Laufzeitverhalten (Socket Mode + HTTP-Request-URLs) title: Slack x-i18n: - generated_at: "2026-04-12T23:27:58Z" + generated_at: "2026-04-21T13:35:27Z" model: gpt-5.4 provider: openai - source_hash: 4b80c1a612b8815c46c675b688639c207a481f367075996dde3858a83637313b + source_hash: 2fe3c3c344e1c20c09b29773f4f68d2790751e76d8bbaa3c6157e3ff75978acf source_path: channels/slack.md workflow: 15 --- @@ -36,10 +36,10 @@ Status: produktionsreif für DMs + Channels über Slack-App-Integrationen. Der S Klicken Sie in den Slack-App-Einstellungen auf die Schaltfläche **[Create New App](https://api.slack.com/apps/new)**: - - wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus - - fügen Sie das [Beispielmanifest](#manifest-and-scope-checklist) von unten ein und fahren Sie mit dem Erstellen fort - - generieren Sie ein **App-Level-Token** (`xapp-...`) mit `connections:write` - - installieren Sie die App und kopieren Sie das angezeigte **Bot-Token** (`xoxb-...`) + - Wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus + - Fügen Sie das [Beispiel-Manifest](#manifest-and-scope-checklist) von unten ein und fahren Sie mit der Erstellung fort + - Erzeugen Sie ein **App-Level-Token** (`xapp-...`) mit `connections:write` + - Installieren Sie die App und kopieren Sie das angezeigte **Bot Token** (`xoxb-...`) @@ -82,10 +82,10 @@ openclaw gateway Klicken Sie in den Slack-App-Einstellungen auf die Schaltfläche **[Create New App](https://api.slack.com/apps/new)**: - - wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus - - fügen Sie das [Beispielmanifest](#manifest-and-scope-checklist) ein und aktualisieren Sie die URLs vor dem Erstellen - - speichern Sie das **Signing Secret** für die Anfrageverifizierung - - installieren Sie die App und kopieren Sie das angezeigte **Bot-Token** (`xoxb-...`) + - Wählen Sie **from a manifest** und wählen Sie einen Workspace für Ihre App aus + - Fügen Sie das [Beispiel-Manifest](#manifest-and-scope-checklist) ein und aktualisieren Sie die URLs vor der Erstellung + - Speichern Sie das **Signing Secret** für die Request-Verifizierung + - Installieren Sie die App und kopieren Sie das angezeigte **Bot Token** (`xoxb-...`) @@ -289,16 +289,16 @@ openclaw gateway -### Zusätzliche Manifesteinstellungen +### Zusätzliche Manifest-Einstellungen -Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellungen erweitern. +Machen Sie unterschiedliche Funktionen sichtbar, die die oben genannten Standardwerte erweitern. - Mehrere [native Slash-Befehle](#commands-and-slash-behavior) können mit Nuancen anstelle eines einzelnen konfigurierten Befehls verwendet werden: + Mehrere [native Slash-Befehle](#commands-and-slash-behavior) können statt eines einzelnen konfigurierten Befehls mit gewissen Besonderheiten verwendet werden: - - Verwenden Sie `/agentstatus` anstelle von `/status`, weil der Befehl `/status` reserviert ist. + - Verwenden Sie `/agentstatus` anstelle von `/status`, da der Befehl `/status` reserviert ist. - Es können nicht mehr als 25 Slash-Befehle gleichzeitig verfügbar gemacht werden. Ersetzen Sie Ihren vorhandenen Abschnitt `features.slash_commands` durch eine Teilmenge der [verfügbaren Befehle](/de/tools/slash-commands#command-list): @@ -333,8 +333,8 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/think", - "description": "Die Denkstufe festlegen", - "usage_hint": "" + "description": "Das Denk-Level festlegen", + "usage_hint": "" }, { "command": "/verbose", @@ -348,7 +348,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/reasoning", - "description": "Sichtbarkeit von Begründungen umschalten", + "description": "Sichtbarkeit der Begründung umschalten", "usage_hint": "[on|off|stream]" }, { @@ -358,7 +358,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/exec", - "description": "Exec-Standardeinstellungen anzeigen oder festlegen", + "description": "Exec-Standards anzeigen oder festlegen", "usage_hint": "host= security= ask= node=" }, { @@ -368,7 +368,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/models", - "description": "Anbieter oder Modelle für einen Anbieter auflisten", + "description": "Provider oder Modelle für einen Provider auflisten", "usage_hint": "[provider] [page] [limit=|size=|all]" }, { @@ -386,7 +386,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/agentstatus", - "description": "Laufzeitstatus anzeigen, einschließlich Anbieternutzung/Kontingent, wenn verfügbar" + "description": "Laufzeitstatus anzeigen, einschließlich Provider-Nutzung/Kontingent, falls verfügbar" }, { "command": "/tasks", @@ -399,11 +399,11 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/whoami", - "description": "Ihre Absenderidentität anzeigen" + "description": "Ihre Sender-Identität anzeigen" }, { "command": "/skill", - "description": "Eine Skill anhand des Namens ausführen", + "description": "Eine Skills nach Namen ausführen", "usage_hint": " [input]" }, { @@ -413,7 +413,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/usage", - "description": "Die Nutzungsfußzeile steuern oder Kostenzusammenfassung anzeigen", + "description": "Die Nutzungsfußzeile steuern oder die Kostenzusammenfassung anzeigen", "usage_hint": "off|tokens|full|cost" } ] @@ -454,8 +454,8 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/think", - "description": "Die Denkstufe festlegen", - "usage_hint": "", + "description": "Das Denk-Level festlegen", + "usage_hint": "", "url": "https://gateway-host.example.com/slack/events" }, { @@ -472,7 +472,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/reasoning", - "description": "Sichtbarkeit von Begründungen umschalten", + "description": "Sichtbarkeit der Begründung umschalten", "usage_hint": "[on|off|stream]", "url": "https://gateway-host.example.com/slack/events" }, @@ -484,7 +484,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/exec", - "description": "Exec-Standardeinstellungen anzeigen oder festlegen", + "description": "Exec-Standards anzeigen oder festlegen", "usage_hint": "host= security= ask= node=", "url": "https://gateway-host.example.com/slack/events" }, @@ -496,7 +496,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/models", - "description": "Anbieter oder Modelle für einen Anbieter auflisten", + "description": "Provider oder Modelle für einen Provider auflisten", "usage_hint": "[provider] [page] [limit=|size=|all]", "url": "https://gateway-host.example.com/slack/events" }, @@ -518,7 +518,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/agentstatus", - "description": "Laufzeitstatus anzeigen, einschließlich Anbieternutzung/Kontingent, wenn verfügbar", + "description": "Laufzeitstatus anzeigen, einschließlich Provider-Nutzung/Kontingent, falls verfügbar", "url": "https://gateway-host.example.com/slack/events" }, { @@ -534,12 +534,12 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/whoami", - "description": "Ihre Absenderidentität anzeigen", + "description": "Ihre Sender-Identität anzeigen", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/skill", - "description": "Eine Skill anhand des Namens ausführen", + "description": "Eine Skills nach Namen ausführen", "usage_hint": " [input]", "url": "https://gateway-host.example.com/slack/events" }, @@ -551,7 +551,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge }, { "command": "/usage", - "description": "Die Nutzungsfußzeile steuern oder Kostenzusammenfassung anzeigen", + "description": "Die Nutzungsfußzeile steuern oder die Kostenzusammenfassung anzeigen", "usage_hint": "off|tokens|full|cost", "url": "https://gateway-host.example.com/slack/events" } @@ -562,14 +562,14 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge - - Fügen Sie den Bot-Scope `chat:write.customize` hinzu, wenn ausgehende Nachrichten die aktive Agent-Identität (benutzerdefinierter Benutzername und Icon) statt der Standardidentität der Slack-App verwenden sollen. + + Fügen Sie den Bot-Scope `chat:write.customize` hinzu, wenn ausgehende Nachrichten die Identität des aktiven Agenten (benutzerdefinierter Benutzername und Icon) statt der Standardidentität der Slack-App verwenden sollen. Wenn Sie ein Emoji-Icon verwenden, erwartet Slack die Syntax `:emoji_name:`. - Wenn Sie `channels.slack.userToken` konfigurieren, sind typische Lesescopes: + Wenn Sie `channels.slack.userToken` konfigurieren, sind typische Lese-Scopes: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -577,7 +577,7 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (wenn Sie von Slack-Suchlesevorgängen abhängig sind) + - `search:read` (wenn Sie auf Slack-Suchlesevorgänge angewiesen sind) @@ -591,20 +591,20 @@ Machen Sie verschiedene Funktionen sichtbar, die die obigen Standardeinstellunge - Der Env-Fallback `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` gilt nur für das Standardkonto. - `userToken` (`xoxp-...`) ist nur per Konfiguration verfügbar (kein Env-Fallback) und verwendet standardmäßig schreibgeschütztes Verhalten (`userTokenReadOnly: true`). -Verhalten des Status-Snapshots: +Verhalten der Statusübersicht: -- Die Slack-Kontoinspektion verfolgt pro Zugangsdaten `*Source`- und `*Status`-Felder (`botToken`, `appToken`, `signingSecret`, `userToken`). +- Die Slack-Kontoinspektion verfolgt pro Anmeldedatenfeld `*Source`- und `*Status`-Felder (`botToken`, `appToken`, `signingSecret`, `userToken`). - Der Status ist `available`, `configured_unavailable` oder `missing`. -- `configured_unavailable` bedeutet, dass das Konto über SecretRef oder eine andere nicht-inline Geheimnisquelle konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den tatsächlichen Wert aber nicht auflösen konnte. -- Im HTTP-Modus wird `signingSecretStatus` eingeschlossen; im Socket Mode ist das erforderliche Paar `botTokenStatus` + `appTokenStatus`. +- `configured_unavailable` bedeutet, dass das Konto über SecretRef oder eine andere nicht-inline Secret-Quelle konfiguriert ist, der aktuelle Befehls-/Laufzeitpfad den tatsächlichen Wert aber nicht auflösen konnte. +- Im HTTP-Modus wird `signingSecretStatus` einbezogen; im Socket Mode ist das erforderliche Paar `botTokenStatus` + `appTokenStatus`. -Für Aktions-/Verzeichnislesevorgänge kann das User-Token bevorzugt werden, wenn es konfiguriert ist. Für Schreibvorgänge bleibt das Bot-Token bevorzugt; Schreibvorgänge mit User-Token sind nur zulässig, wenn `userTokenReadOnly: false` gesetzt ist und kein Bot-Token verfügbar ist. +Für Aktionen/Verzeichnislesevorgänge kann das User-Token bevorzugt werden, wenn es konfiguriert ist. Für Schreibvorgänge bleibt das Bot-Token bevorzugt; User-Token-Schreibvorgänge sind nur zulässig, wenn `userTokenReadOnly: false` gesetzt ist und kein Bot-Token verfügbar ist. ## Aktionen und Gates -Slack-Aktionen werden durch `channels.slack.actions.*` gesteuert. +Slack-Aktionen werden über `channels.slack.actions.*` gesteuert. Verfügbare Aktionsgruppen im aktuellen Slack-Tooling: @@ -622,18 +622,18 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down - `channels.slack.dmPolicy` steuert den DM-Zugriff (Legacy: `channels.slack.dm.policy`): + `channels.slack.dmPolicy` steuert den DM-Zugriff (alt: `channels.slack.dm.policy`): - `pairing` (Standard) - `allowlist` - - `open` (erfordert, dass `channels.slack.allowFrom` `"*"` enthält; Legacy: `channels.slack.dm.allowFrom`) + - `open` (erfordert, dass `channels.slack.allowFrom` `"*"` enthält; alt: `channels.slack.dm.allowFrom`) - `disabled` DM-Flags: - - `dm.enabled` (standardmäßig true) + - `dm.enabled` (Standard true) - `channels.slack.allowFrom` (bevorzugt) - - `dm.allowFrom` (Legacy) + - `dm.allowFrom` (alt) - `dm.groupEnabled` (Gruppen-DMs standardmäßig false) - `dm.groupChannels` (optionale MPIM-Allowlist) @@ -643,7 +643,7 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down - Benannte Konten übernehmen `channels.slack.allowFrom`, wenn ihr eigenes `allowFrom` nicht gesetzt ist. - Benannte Konten übernehmen nicht `channels.slack.accounts.default.allowFrom`. - Das Pairing in DMs verwendet `openclaw pairing approve slack `. + Die Kopplung in DMs verwendet `openclaw pairing approve slack `. @@ -654,26 +654,26 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down - `allowlist` - `disabled` - Die Channel-Allowlist liegt unter `channels.slack.channels` und sollte stabile Channel-IDs verwenden. + Die Channel-Allowlist befindet sich unter `channels.slack.channels` und sollte stabile Channel-IDs verwenden. - Laufzeithinweis: Wenn `channels.slack` vollständig fehlt (nur Env-Setup), fällt die Laufzeit auf `groupPolicy="allowlist"` zurück und protokolliert eine Warnung (selbst wenn `channels.defaults.groupPolicy` gesetzt ist). + Laufzeithinweis: Wenn `channels.slack` vollständig fehlt (nur Env-Setup), fällt die Laufzeit auf `groupPolicy="allowlist"` zurück und protokolliert eine Warnung (auch wenn `channels.defaults.groupPolicy` gesetzt ist). - Namens-/ID-Auflösung: + Auflösung von Namen/IDs: - - Channel-Allowlist-Einträge und DM-Allowlist-Einträge werden beim Start aufgelöst, wenn der Token-Zugriff dies erlaubt - - nicht aufgelöste Channel-Namenseinträge bleiben wie konfiguriert erhalten, werden für das Routing standardmäßig aber ignoriert - - eingehende Autorisierung und Channel-Routing sind standardmäßig ID-first; direktes Abgleichen von Benutzernamen/Slugs erfordert `channels.slack.dangerouslyAllowNameMatching: true` + - Einträge in der Channel-Allowlist und DM-Allowlist werden beim Start aufgelöst, wenn der Token-Zugriff dies zulässt + - nicht aufgelöste Channel-Namenseinträge bleiben wie konfiguriert erhalten, werden aber standardmäßig für das Routing ignoriert + - Eingangsautorisierung und Channel-Routing sind standardmäßig ID-first; direktes Matching von Benutzernamen/Slugs erfordert `channels.slack.dangerouslyAllowNameMatching: true` - Channel-Nachrichten sind standardmäßig durch Erwähnungen gated. + Channel-Nachrichten sind standardmäßig durch Erwähnungen begrenzt. - Erwähnungsquellen: + Quellen für Erwähnungen: - explizite App-Erwähnung (`<@botId>`) - - Erwähnungs-Regex-Muster (`agents.list[].groupChat.mentionPatterns`, Fallback `messages.groupChat.mentionPatterns`) - - implizites Reply-to-Bot-Thread-Verhalten (deaktiviert, wenn `thread.requireExplicitMention` `true` ist) + - Regex-Muster für Erwähnungen (`agents.list[].groupChat.mentionPatterns`, Fallback `messages.groupChat.mentionPatterns`) + - implizites Antwort-auf-Bot-Thread-Verhalten (deaktiviert, wenn `thread.requireExplicitMention` `true` ist) Steuerelemente pro Channel (`channels.slack.channels.`; Namen nur über Startauflösung oder `dangerouslyAllowNameMatching`): @@ -684,7 +684,7 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down - `systemPrompt` - `tools`, `toolsBySender` - Schlüsselformat für `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oder Platzhalter `"*"` - (Legacy-Schlüssel ohne Präfix werden weiterhin nur `id:` zugeordnet) + (Altschlüssel ohne Präfix werden weiterhin nur `id:` zugeordnet) @@ -692,27 +692,27 @@ Zu den aktuellen Slack-Nachrichtenaktionen gehören `send`, `upload-file`, `down ## Threads, Sitzungen und Antwort-Tags - DMs werden als `direct` geroutet; Channels als `channel`; MPIMs als `group`. -- Mit dem Standard `session.dmScope=main` werden Slack-DMs in die Hauptsitzung des Agenten zusammengeführt. +- Mit dem Standardwert `session.dmScope=main` werden Slack-DMs zur Hauptsitzung des Agenten zusammengeführt. - Channel-Sitzungen: `agent::slack:channel:`. - Thread-Antworten können bei Bedarf Thread-Sitzungssuffixe (`:thread:`) erzeugen. -- Der Standardwert von `channels.slack.thread.historyScope` ist `thread`; der Standardwert von `thread.inheritParent` ist `false`. -- `channels.slack.thread.initialHistoryLimit` steuert, wie viele vorhandene Thread-Nachrichten abgerufen werden, wenn eine neue Thread-Sitzung beginnt (Standard `20`; setzen Sie `0`, um dies zu deaktivieren). -- `channels.slack.thread.requireExplicitMention` (Standard `false`): Wenn `true`, werden implizite Thread-Erwähnungen unterdrückt, sodass der Bot in Threads nur auf explizite `@bot`-Erwähnungen antwortet, selbst wenn der Bot bereits am Thread teilgenommen hat. Ohne dies umgehen Antworten in einem Thread mit Bot-Beteiligung das `requireMention`-Gating. +- `channels.slack.thread.historyScope` ist standardmäßig `thread`; `thread.inheritParent` ist standardmäßig `false`. +- `channels.slack.thread.initialHistoryLimit` steuert, wie viele vorhandene Thread-Nachrichten abgerufen werden, wenn eine neue Thread-Sitzung startet (Standard `20`; setzen Sie `0`, um dies zu deaktivieren). +- `channels.slack.thread.requireExplicitMention` (Standard `false`): Wenn `true`, werden implizite Thread-Erwähnungen unterdrückt, sodass der Bot in Threads nur auf explizite `@bot`-Erwähnungen antwortet, selbst wenn der Bot bereits am Thread teilgenommen hat. Ohne dies umgehen Antworten in einem Thread mit Bot-Beteiligung das `requireMention`-Gate. -Steuerelemente für Antwort-Threading: +Steuerelemente für Antwort-Threads: - `channels.slack.replyToMode`: `off|first|all|batched` (Standard `off`) - `channels.slack.replyToModeByChatType`: pro `direct|group|channel` -- Legacy-Fallback für direkte Chats: `channels.slack.dm.replyToMode` +- Alt-Fallback für direkte Chats: `channels.slack.dm.replyToMode` Manuelle Antwort-Tags werden unterstützt: - `[[reply_to_current]]` - `[[reply_to:]]` -Hinweis: `replyToMode="off"` deaktiviert in Slack **jegliches** Antwort-Threading, einschließlich expliziter `[[reply_to_*]]`-Tags. Dies unterscheidet sich von Telegram, wo explizite Tags im Modus `"off"` weiterhin beachtet werden. Der Unterschied spiegelt die Threading-Modelle der Plattformen wider: Slack-Threads blenden Nachrichten aus dem Channel aus, während Telegram-Antworten im Haupt-Chatverlauf sichtbar bleiben. +Hinweis: `replyToMode="off"` deaktiviert **sämtliches** Antwort-Threading in Slack, einschließlich expliziter `[[reply_to_*]]`-Tags. Dies unterscheidet sich von Telegram, wo explizite Tags auch im Modus `"off"` weiterhin berücksichtigt werden. Der Unterschied spiegelt die Threading-Modelle der Plattformen wider: Slack-Threads verbergen Nachrichten im Channel, während Telegram-Antworten im Haupt-Chatverlauf sichtbar bleiben. -## Bestätigungsreaktionen +## Ack-Reaktionen `ackReaction` sendet ein Bestätigungs-Emoji, während OpenClaw eine eingehende Nachricht verarbeitet. @@ -721,7 +721,7 @@ Auflösungsreihenfolge: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- Emoji-Fallback der Agent-Identität (`agents.list[].identity.emoji`, sonst `"👀"`) +- Emoji-Fallback der Agentenidentität (`agents.list[].identity.emoji`, sonst "👀") Hinweise: @@ -733,19 +733,19 @@ Hinweise: `channels.slack.streaming` steuert das Verhalten der Live-Vorschau: - `off`: Live-Vorschau-Streaming deaktivieren. -- `partial` (Standard): Vorschautext durch die neueste partielle Ausgabe ersetzen. +- `partial` (Standard): Vorschautext durch die neueste Teilausgabe ersetzen. - `block`: Vorschauaktualisierungen in Blöcken anhängen. -- `progress`: Fortschrittsstatustext während der Generierung anzeigen und dann den endgültigen Text senden. +- `progress`: Während der Generierung einen Fortschrittsstatustext anzeigen und dann den endgültigen Text senden. `channels.slack.streaming.nativeTransport` steuert natives Slack-Text-Streaming, wenn `channels.slack.streaming.mode` auf `partial` gesetzt ist (Standard: `true`). -- Für natives Text-Streaming und die Anzeige des Slack-Assistant-Thread-Status muss ein Antwort-Thread verfügbar sein. Die Thread-Auswahl folgt weiterhin `replyToMode`. +- Für natives Text-Streaming und die Anzeige des Slack-Assistenten-Thread-Status muss ein Antwort-Thread verfügbar sein. Die Thread-Auswahl folgt weiterhin `replyToMode`. - Channel- und Gruppenchat-Wurzeln können weiterhin die normale Entwurfsvorschau verwenden, wenn natives Streaming nicht verfügbar ist. -- Slack-DMs der obersten Ebene bleiben standardmäßig ohne Thread, daher zeigen sie keine Vorschau im Thread-Stil an; verwenden Sie Thread-Antworten oder `typingReaction`, wenn Sie dort sichtbaren Fortschritt wünschen. -- Medien und Nicht-Text-Payloads fallen auf die normale Zustellung zurück. -- Wenn das Streaming mitten in einer Antwort fehlschlägt, fällt OpenClaw für die verbleibenden Payloads auf die normale Zustellung zurück. +- Slack-DMs auf oberster Ebene bleiben standardmäßig außerhalb von Threads, daher zeigen sie keine Vorschau im Thread-Stil an; verwenden Sie Thread-Antworten oder `typingReaction`, wenn dort sichtbarer Fortschritt angezeigt werden soll. +- Medien- und Nicht-Text-Payloads fallen auf normale Zustellung zurück. +- Wenn Streaming während einer Antwort fehlschlägt, fällt OpenClaw für die verbleibenden Payloads auf normale Zustellung zurück. -Verwenden Sie die Entwurfsvorschau anstelle von nativem Slack-Text-Streaming: +Entwurfsvorschau anstelle von nativem Slack-Text-Streaming verwenden: ```json5 { @@ -760,15 +760,15 @@ Verwenden Sie die Entwurfsvorschau anstelle von nativem Slack-Text-Streaming: } ``` -Legacy-Schlüssel: +Altschlüssel: -- `channels.slack.streamMode` (`replace | status_final | append`) wird automatisch nach `channels.slack.streaming.mode` migriert. -- boolesches `channels.slack.streaming` wird automatisch nach `channels.slack.streaming.mode` und `channels.slack.streaming.nativeTransport` migriert. -- Legacy-`channels.slack.nativeStreaming` wird automatisch nach `channels.slack.streaming.nativeTransport` migriert. +- `channels.slack.streamMode` (`replace | status_final | append`) wird automatisch zu `channels.slack.streaming.mode` migriert. +- Boolesches `channels.slack.streaming` wird automatisch zu `channels.slack.streaming.mode` und `channels.slack.streaming.nativeTransport` migriert. +- Das alte `channels.slack.nativeStreaming` wird automatisch zu `channels.slack.streaming.nativeTransport` migriert. ## Typing-Reaction-Fallback -`typingReaction` fügt der eingehenden Slack-Nachricht vorübergehend eine Reaktion hinzu, während OpenClaw eine Antwort verarbeitet, und entfernt sie wieder, wenn der Lauf beendet ist. Dies ist besonders nützlich außerhalb von Thread-Antworten, die standardmäßig einen Statusindikator „is typing...“ verwenden. +`typingReaction` fügt der eingehenden Slack-Nachricht vorübergehend eine Reaktion hinzu, während OpenClaw eine Antwort verarbeitet, und entfernt sie wieder, wenn der Lauf abgeschlossen ist. Dies ist besonders nützlich außerhalb von Thread-Antworten, die standardmäßig einen Statusindikator „is typing...“ verwenden. Auflösungsreihenfolge: @@ -778,23 +778,23 @@ Auflösungsreihenfolge: Hinweise: - Slack erwartet Shortcodes (zum Beispiel `"hourglass_flowing_sand"`). -- Die Reaktion erfolgt nach bestem Bemühen, und die Bereinigung wird automatisch versucht, nachdem die Antwort oder der Fehlerpfad abgeschlossen ist. +- Die Reaktion erfolgt nach bestem Aufwand und die Bereinigung wird nach Abschluss des Antwort- oder Fehlerpfads automatisch versucht. ## Medien, Chunking und Zustellung - Slack-Dateianhänge werden von Slack-gehosteten privaten URLs heruntergeladen (token-authentifizierter Anfragefluss) und in den Medienspeicher geschrieben, wenn der Abruf erfolgreich ist und Größenlimits dies erlauben. + Slack-Dateianhänge werden von privat gehosteten Slack-URLs heruntergeladen (token-authentifizierter Request-Ablauf) und in den Medienspeicher geschrieben, wenn das Abrufen erfolgreich ist und Größenlimits dies zulassen. - Die Laufzeitobergrenze für eingehende Größen beträgt standardmäßig `20MB`, sofern sie nicht durch `channels.slack.mediaMaxMb` überschrieben wird. + Die Laufzeitgrenze für eingehende Daten beträgt standardmäßig `20MB`, sofern sie nicht durch `channels.slack.mediaMaxMb` überschrieben wird. - Text-Chunks verwenden `channels.slack.textChunkLimit` (Standard 4000) - - `channels.slack.chunkMode="newline"` aktiviert paragrafenorientiertes Aufteilen - - Dateisendungen verwenden Slack-Upload-APIs und können Thread-Antworten (`thread_ts`) enthalten - - Das Limit für ausgehende Medien folgt bei Konfiguration `channels.slack.mediaMaxMb`; andernfalls verwenden Channel-Sendungen die MIME-Typ-Standards aus der Medienpipeline + - `channels.slack.chunkMode="newline"` aktiviert eine absatzorientierte Aufteilung + - Dateisendungen verwenden Slack-Upload-APIs und können Thread-Antworten (`thread_ts`) einschließen + - Die Obergrenze für ausgehende Medien folgt `channels.slack.mediaMaxMb`, wenn konfiguriert; andernfalls verwenden Channel-Sendungen MIME-Art-Standards aus der Medienpipeline @@ -803,14 +803,14 @@ Hinweise: - `user:` für DMs - `channel:` für Channels - Slack-DMs werden über die Slack-Conversation-APIs geöffnet, wenn an Benutzerziele gesendet wird. + Slack-DMs werden beim Senden an Benutzerziele über Slack-Conversations-APIs geöffnet. ## Befehle und Slash-Verhalten -Slash-Befehle erscheinen in Slack entweder als einzelner konfigurierter Befehl oder als mehrere native Befehle. Konfigurieren Sie `channels.slack.slashCommand`, um die Befehlsstandards zu ändern: +Slash-Befehle erscheinen in Slack entweder als einzelner konfigurierter Befehl oder als mehrere native Befehle. Konfigurieren Sie `channels.slack.slashCommand`, um Befehlsstandards zu ändern: - `enabled: false` - `name: "openclaw"` @@ -821,7 +821,7 @@ Slash-Befehle erscheinen in Slack entweder als einzelner konfigurierter Befehl o /openclaw /help ``` -Native Befehle erfordern [zusätzliche Manifesteinstellungen](#additional-manifest-settings) in Ihrer Slack-App und werden stattdessen mit `channels.slack.commands.native: true` oder `commands.native: true` in globalen Konfigurationen aktiviert. +Native Befehle erfordern [zusätzliche Manifest-Einstellungen](#additional-manifest-settings) in Ihrer Slack-App und werden stattdessen mit `channels.slack.commands.native: true` oder `commands.native: true` in globalen Konfigurationen aktiviert. - Der automatische native Befehlsmodus ist für Slack **deaktiviert**, daher aktiviert `commands.native: "auto"` keine nativen Slack-Befehle. @@ -829,22 +829,22 @@ Native Befehle erfordern [zusätzliche Manifesteinstellungen](#additional-manife /help ``` -Native Argumentmenüs verwenden eine adaptive Renderstrategie, die vor dem Senden eines ausgewählten Optionswerts ein Bestätigungsmodal anzeigt: +Native Argumentmenüs verwenden eine adaptive Rendering-Strategie, die vor dem Absenden eines ausgewählten Optionswerts ein Bestätigungsmodal anzeigt: - bis zu 5 Optionen: Button-Blöcke -- 6–100 Optionen: statisches Auswahlmenü -- mehr als 100 Optionen: externe Auswahl mit asynchroner Optionsfilterung, wenn Interaktivitäts-Options-Handler verfügbar sind -- überschrittene Slack-Limits: codierte Optionswerte fallen auf Buttons zurück +- 6-100 Optionen: statisches Auswahlmenü +- mehr als 100 Optionen: externe Auswahl mit asynchroner Optionsfilterung, wenn Handler für Interaktivitätsoptionen verfügbar sind +- bei Überschreitung der Slack-Limits: codierte Optionswerte fallen auf Buttons zurück ```txt /think ``` -Slash-Sitzungen verwenden isolierte Schlüssel wie `agent::slack:slash:` und leiten Befehlsausführungen weiterhin über `CommandTargetSessionKey` an die Ziel-Konversationssitzung weiter. +Slash-Sitzungen verwenden isolierte Schlüssel wie `agent::slack:slash:` und leiten Befehlsausführungen weiterhin mit `CommandTargetSessionKey` an die Ziel-Konversationssitzung weiter. ## Interaktive Antworten -Slack kann von Agenten verfasste interaktive Antwortsteuerungen rendern, aber diese Funktion ist standardmäßig deaktiviert. +Slack kann interaktive, vom Agenten verfasste Antwortsteuerelemente rendern, aber diese Funktion ist standardmäßig deaktiviert. Global aktivieren: @@ -878,30 +878,30 @@ Oder nur für ein Slack-Konto aktivieren: } ``` -Wenn aktiviert, können Agenten nur für Slack bestimmte Antwortdirektiven ausgeben: +Wenn aktiviert, können Agenten nur für Slack gültige Antwortdirektiven ausgeben: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Diese Direktiven werden in Slack Block Kit kompiliert und leiten Klicks oder Auswahlen über den vorhandenen Slack-Interaktionsereignispfad zurück. +Diese Direktiven werden zu Slack Block Kit kompiliert und leiten Klicks oder Auswahlen über den bestehenden Slack-Interaktionsereignispfad zurück. Hinweise: - Dies ist eine Slack-spezifische UI. Andere Channels übersetzen Slack-Block-Kit-Direktiven nicht in ihre eigenen Button-Systeme. -- Die Werte interaktiver Callbacks sind von OpenClaw generierte undurchsichtige Token, keine unbearbeiteten, vom Agenten verfassten Werte. -- Wenn generierte interaktive Blöcke die Slack-Block-Kit-Limits überschreiten würden, fällt OpenClaw auf die ursprüngliche Textantwort zurück, anstatt eine ungültige Blocks-Payload zu senden. +- Die interaktiven Callback-Werte sind von OpenClaw erzeugte opake Tokens, keine rohen, vom Agenten verfassten Werte. +- Wenn erzeugte interaktive Blöcke die Slack-Block-Kit-Limits überschreiten würden, fällt OpenClaw auf die ursprüngliche Textantwort zurück, anstatt eine ungültige Blocks-Payload zu senden. -## Exec-Freigaben in Slack +## Exec-Genehmigungen in Slack -Slack kann als nativer Freigabe-Client mit interaktiven Buttons und Interaktionen dienen, anstatt auf die Web-UI oder das Terminal zurückzufallen. +Slack kann als nativer Genehmigungsclient mit interaktiven Buttons und Interaktionen fungieren, statt auf die Web-UI oder das Terminal zurückzufallen. -- Exec-Freigaben verwenden `channels.slack.execApprovals.*` für natives DM-/Channel-Routing. -- Plugin-Freigaben können weiterhin über dieselbe native Slack-Button-Oberfläche aufgelöst werden, wenn die Anfrage bereits in Slack landet und die Freigabe-ID-Art `plugin:` ist. -- Die Autorisierung der Freigebenden wird weiterhin erzwungen: Nur als Freigebende identifizierte Benutzer können Anfragen über Slack genehmigen oder ablehnen. +- Exec-Genehmigungen verwenden `channels.slack.execApprovals.*` für natives DM-/Channel-Routing. +- Plugin-Genehmigungen können weiterhin über dieselbe Slack-native Button-Oberfläche aufgelöst werden, wenn die Anfrage bereits in Slack landet und die Genehmigungs-ID-Art `plugin:` ist. +- Die Autorisierung der Genehmigenden wird weiterhin erzwungen: Nur als Genehmigende identifizierte Benutzer können Anfragen über Slack genehmigen oder ablehnen. -Dies verwendet dieselbe gemeinsame Freigabe-Button-Oberfläche wie andere Channels. Wenn `interactivity` in Ihren Slack-App-Einstellungen aktiviert ist, werden Freigabeaufforderungen direkt als Block-Kit-Buttons in der Konversation gerendert. -Wenn diese Buttons vorhanden sind, sind sie die primäre Freigabe-UX; OpenClaw -sollte einen manuellen `/approve`-Befehl nur einschließen, wenn das Tool-Ergebnis sagt, dass Chat-Freigaben nicht verfügbar sind oder manuelle Freigabe der einzige Weg ist. +Dies verwendet dieselbe gemeinsame Genehmigungs-Button-Oberfläche wie andere Channels. Wenn `interactivity` in Ihren Slack-App-Einstellungen aktiviert ist, werden Genehmigungsabfragen direkt in der Konversation als Block-Kit-Buttons gerendert. +Wenn diese Buttons vorhanden sind, sind sie die primäre Genehmigungs-UX; OpenClaw +sollte einen manuellen `/approve`-Befehl nur dann einschließen, wenn das Tool-Ergebnis sagt, dass Chat-Genehmigungen nicht verfügbar sind oder die manuelle Genehmigung der einzige Weg ist. Konfigurationspfad: @@ -910,11 +910,11 @@ Konfigurationspfad: - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, Standard: `dm`) - `agentFilter`, `sessionFilter` -Slack aktiviert native Exec-Freigaben automatisch, wenn `enabled` nicht gesetzt oder `"auto"` ist und sich mindestens ein -Freigebender auflösen lässt. Setzen Sie `enabled: false`, um Slack explizit als nativen Freigabe-Client zu deaktivieren. -Setzen Sie `enabled: true`, um native Freigaben zu erzwingen, wenn sich Freigebende auflösen lassen. +Slack aktiviert native Exec-Genehmigungen automatisch, wenn `enabled` nicht gesetzt ist oder `"auto"` ist und mindestens ein +Genehmigender aufgelöst wird. Setzen Sie `enabled: false`, um Slack explizit als nativen Genehmigungsclient zu deaktivieren. +Setzen Sie `enabled: true`, um native Genehmigungen zu erzwingen, wenn Genehmigende aufgelöst werden. -Standardverhalten ohne explizite Slack-Exec-Freigabekonfiguration: +Standardverhalten ohne explizite Slack-Exec-Genehmigungskonfiguration: ```json5 { @@ -924,8 +924,8 @@ Standardverhalten ohne explizite Slack-Exec-Freigabekonfiguration: } ``` -Eine explizite Slack-native Konfiguration ist nur erforderlich, wenn Sie Freigebende überschreiben, Filter hinzufügen oder -sich für die Zustellung an den Ursprungschat entscheiden möchten: +Eine explizite Slack-native Konfiguration ist nur erforderlich, wenn Sie Genehmigende überschreiben, Filter hinzufügen oder +sich für die Zustellung an den Ursprungs-Chat entscheiden möchten: ```json5 { @@ -941,20 +941,20 @@ sich für die Zustellung an den Ursprungschat entscheiden möchten: } ``` -Gemeinsame `approvals.exec`-Weiterleitung ist getrennt. Verwenden Sie sie nur, wenn Exec-Freigabeaufforderungen zusätzlich -an andere Chats oder explizite Ziele außerhalb des Bandes weitergeleitet werden müssen. Gemeinsame `approvals.plugin`-Weiterleitung ist ebenfalls -getrennt; native Slack-Buttons können Plugin-Freigaben weiterhin auflösen, wenn diese Anfragen bereits in Slack landen. +Gemeinsame Weiterleitung über `approvals.exec` ist davon getrennt. Verwenden Sie sie nur, wenn Exec-Genehmigungsabfragen zusätzlich +an andere Chats oder explizite Out-of-Band-Ziele weitergeleitet werden müssen. Gemeinsame Weiterleitung über `approvals.plugin` ist ebenfalls +getrennt; Slack-native Buttons können Plugin-Genehmigungen weiterhin auflösen, wenn diese Anfragen bereits in Slack landen. -`/approve` im selben Chat funktioniert ebenfalls in Slack-Channels und DMs, die bereits Befehle unterstützen. Siehe [Exec approvals](/de/tools/exec-approvals) für das vollständige Modell zur Freigabeweiterleitung. +`/approve` im selben Chat funktioniert auch in Slack-Channels und DMs, die bereits Befehle unterstützen. Siehe [Exec-Genehmigungen](/de/tools/exec-approvals) für das vollständige Modell zur Genehmigungsweiterleitung. -## Ereignisse und Laufzeitverhalten +## Ereignisse und Betriebsverhalten - Nachrichtenbearbeitungen/-löschungen/Thread-Broadcasts werden in Systemereignisse abgebildet. -- Hinzugefügte/entfernte Reaktionen werden in Systemereignisse abgebildet. -- Beitritt/Austritt von Mitgliedern, Erstellung/Umbenennung von Channels und Hinzufügen/Entfernen von Pins werden in Systemereignisse abgebildet. +- Reaktions-Hinzufügen/-Entfernen-Ereignisse werden in Systemereignisse abgebildet. +- Ereignisse zu Beitritt/Austritt von Mitgliedern, erstellten/umbenannten Channels und hinzugefügten/entfernten Pins werden in Systemereignisse abgebildet. - `channel_id_changed` kann Channel-Konfigurationsschlüssel migrieren, wenn `configWrites` aktiviert ist. -- Channel-Topic-/Purpose-Metadaten werden als nicht vertrauenswürdiger Kontext behandelt und können in den Routing-Kontext eingefügt werden. -- Thread-Starter und das anfängliche Seedings des Thread-Verlaufs-Kontexts werden, sofern zutreffend, durch konfigurierte Absender-Allowlists gefiltert. +- Channel-Topic-/Purpose-Metadaten werden als nicht vertrauenswürdiger Kontext behandelt und können in den Routing-Kontext injiziert werden. +- Thread-Starter und anfängliches Kontext-Seeding aus dem Thread-Verlauf werden, sofern zutreffend, nach konfigurierten Sender-Allowlists gefiltert. - Block-Aktionen und Modal-Interaktionen erzeugen strukturierte Systemereignisse `Slack interaction: ...` mit umfangreichen Payload-Feldern: - Block-Aktionen: ausgewählte Werte, Labels, Picker-Werte und `workflow_*`-Metadaten - Modal-Ereignisse `view_submission` und `view_closed` mit gerouteten Channel-Metadaten und Formulareingaben @@ -967,8 +967,8 @@ Primäre Referenz: Wichtige Slack-Felder: - Modus/Auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - - DM-Zugriff: `dm.enabled`, `dmPolicy`, `allowFrom` (Legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - - Kompatibilitätsschalter: `dangerouslyAllowNameMatching` (Break-Glass; deaktiviert lassen, sofern nicht benötigt) + - DM-Zugriff: `dm.enabled`, `dmPolicy`, `allowFrom` (alt: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` + - Kompatibilitätsumschalter: `dangerouslyAllowNameMatching` (nur im Notfall; ausgeschaltet lassen, sofern nicht benötigt) - Channel-Zugriff: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - Threading/Verlauf: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - Zustellung: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport` @@ -983,7 +983,7 @@ Primäre Referenz: - `groupPolicy` - Channel-Allowlist (`channels.slack.channels`) - `requireMention` - - `users`-Allowlist pro Channel + - Allowlist `users` pro Channel Nützliche Befehle: @@ -999,8 +999,8 @@ openclaw doctor Prüfen Sie: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy` (oder Legacy `channels.slack.dm.policy`) - - Pairing-Freigaben / Allowlist-Einträge + - `channels.slack.dmPolicy` (oder alt `channels.slack.dm.policy`) + - Kopplungsgenehmigungen / Allowlist-Einträge ```bash openclaw pairing list slack @@ -1024,9 +1024,9 @@ openclaw pairing list slack - Signing Secret - Webhook-Pfad - Slack-Request-URLs (Events + Interaktivität + Slash-Befehle) - - eindeutiger `webhookPath` pro HTTP-Konto + - eindeutigen `webhookPath` pro HTTP-Konto - Wenn `signingSecretStatus: "configured_unavailable"` in Konto-Snapshots + Wenn `signingSecretStatus: "configured_unavailable"` in Kontoübersichten erscheint, ist das HTTP-Konto konfiguriert, aber die aktuelle Laufzeit konnte das durch SecretRef gestützte Signing Secret nicht auflösen. @@ -1035,10 +1035,10 @@ openclaw pairing list slack Prüfen Sie, ob Sie Folgendes beabsichtigt haben: - - nativen Befehlsmodus (`channels.slack.commands.native: true`) mit passenden in Slack registrierten Slash-Befehlen - - oder Modus mit einzelnem Slash-Befehl (`channels.slack.slashCommand.enabled: true`) + - nativer Befehlsmodus (`channels.slack.commands.native: true`) mit passend in Slack registrierten Slash-Befehlen + - oder Einzel-Slash-Befehlsmodus (`channels.slack.slashCommand.enabled: true`) - Prüfen Sie außerdem `commands.useAccessGroups` und Channel-/Benutzer-Allowlists. + Prüfen Sie außerdem `commands.useAccessGroups` sowie Channel-/Benutzer-Allowlists. diff --git a/docs/de/concepts/messages.md b/docs/de/concepts/messages.md index f215e3e78..d821fa581 100644 --- a/docs/de/concepts/messages.md +++ b/docs/de/concepts/messages.md @@ -1,53 +1,48 @@ --- read_when: - - Erklären, wie eingehende Nachrichten zu Antworten werden - - Erläutern von Sitzungen, Warteschlangenmodi oder Streaming-Verhalten - - Dokumentieren der Sichtbarkeit des Denkprozesses und der Auswirkungen auf die Nutzung -summary: Nachrichtenfluss, Sitzungen, Warteschlangenbildung und Sichtbarkeit des Denkprozesses + - Erklärung, wie eingehende Nachrichten zu Antworten werden + - Erläuterung von Sitzungen, Warteschlangenmodi oder Streaming-Verhalten + - Dokumentation der Sichtbarkeit der Argumentation und der Auswirkungen auf die Nutzung +summary: Nachrichtenfluss, Sitzungen, Warteschlangenbildung und Sichtbarkeit der Argumentation title: Nachrichten x-i18n: - generated_at: "2026-04-21T06:23:59Z" + generated_at: "2026-04-21T13:35:27Z" model: gpt-5.4 provider: openai - source_hash: ddf88b91f3489bfdfb4a84f8a287a1ec0b0d71a765dfe27c666c6f43d0145022 + source_hash: 4f535d01872e7fcf0f3d99a5c5ac01feddbf7fb562ff61d9ccdf18f109f9922f source_path: concepts/messages.md workflow: 15 --- # Nachrichten -Diese Seite fasst zusammen, wie OpenClaw eingehende Nachrichten, Sitzungen, Warteschlangenbildung, -Streaming und die Sichtbarkeit des Denkprozesses verarbeitet. +Diese Seite führt zusammen, wie OpenClaw eingehende Nachrichten, Sitzungen, Warteschlangenbildung, Streaming und die Sichtbarkeit der Argumentation verarbeitet. -## Nachrichtenfluss (Überblick) +## Nachrichtenfluss (allgemein) ``` -Eingehende Nachricht - -> Routing/Bindings -> Sitzungsschlüssel - -> Warteschlange (wenn ein Lauf aktiv ist) - -> Agent-Lauf (Streaming + Tools) - -> Ausgehende Antworten (Kanalgrenzen + Aufteilung) +Inbound message + -> routing/bindings -> session key + -> queue (if a run is active) + -> agent run (streaming + tools) + -> outbound replies (channel limits + chunking) ``` Wichtige Stellschrauben befinden sich in der Konfiguration: - `messages.*` für Präfixe, Warteschlangenbildung und Gruppenverhalten. -- `agents.defaults.*` für Standardwerte bei Block-Streaming und Aufteilung. -- Kanalüberschreibungen (`channels.whatsapp.*`, `channels.telegram.*` usw.) für Grenzen und Streaming-Umschalter. +- `agents.defaults.*` für Standardwerte für Block-Streaming und Chunking. +- Kanalüberschreibungen (`channels.whatsapp.*`, `channels.telegram.*` usw.) für Obergrenzen und Streaming-Umschalter. -Siehe [Konfiguration](/de/gateway/configuration) für das vollständige Schema. +Siehe [Configuration](/de/gateway/configuration) für das vollständige Schema. ## Deduplizierung eingehender Nachrichten -Kanäle können nach Wiederverbindungen dieselbe Nachricht erneut zustellen. OpenClaw hält einen -kurzlebigen Cache, der nach Kanal/Konto/Peer/Sitzung/Nachrichten-ID geschlüsselt ist, damit doppelte -Zustellungen keinen weiteren Agent-Lauf auslösen. +Kanäle können nach erneuten Verbindungen dieselbe Nachricht erneut zustellen. OpenClaw führt einen kurzlebigen Cache, der nach Kanal/Konto/Peer/Sitzung/Nachrichten-ID schlüsselt, damit doppelte Zustellungen keinen weiteren Agent-Durchlauf auslösen. ## Entprellung eingehender Nachrichten -Schnell aufeinanderfolgende Nachrichten vom **gleichen Absender** können über `messages.inbound` -zu einer einzelnen Agent-Runde zusammengefasst werden. Die Entprellung ist pro Kanal + Unterhaltung -begrenzt und verwendet die zuletzt eingegangene Nachricht für Antwort-Threading/IDs. +Schnell aufeinanderfolgende Nachrichten vom **gleichen Absender** können über `messages.inbound` zu einem einzelnen Agent-Turn zusammengefasst werden. Die Entprellung ist auf Kanal + Konversation beschränkt und verwendet die zuletzt empfangene Nachricht für Antwort-Threading/IDs. Konfiguration (globaler Standard + kanalbezogene Überschreibungen): @@ -68,88 +63,74 @@ Konfiguration (globaler Standard + kanalbezogene Überschreibungen): Hinweise: -- Entprellung gilt für **reine Textnachrichten**; Medien/Anhänge werden sofort durchgereicht. -- Steuerbefehle umgehen die Entprellung, damit sie eigenständig bleiben. +- Entprellung gilt für **reine Textnachrichten**; Medien/Anhänge werden sofort geleert. +- Steuerbefehle umgehen die Entprellung, damit sie eigenständig bleiben — **außer**, wenn ein Kanal ausdrücklich Same-Sender-DM-Coalescing aktiviert (z. B. [BlueBubbles `coalesceSameSenderDms`](/de/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)); dann warten DM-Befehle innerhalb des Entprellungsfensters, damit eine Split-Send-Nutzlast demselben Agent-Turn beitreten kann. ## Sitzungen und Geräte Sitzungen gehören dem Gateway, nicht den Clients. -- Direktchats werden auf den Hauptsitzungsschlüssel des Agenten zusammengeführt. -- Gruppen/Kanäle erhalten eigene Sitzungsschlüssel. -- Sitzungsspeicher und Transkripte liegen auf dem Gateway-Host. +- Direkte Chats werden auf den Haupt-Sitzungsschlüssel des Agenten reduziert. +- Gruppen/Kanäle erhalten ihre eigenen Sitzungsschlüssel. +- Der Sitzungsspeicher und die Transkripte liegen auf dem Gateway-Host. -Mehrere Geräte/Kanäle können derselben Sitzung zugeordnet sein, aber der Verlauf wird nicht vollständig -an jeden Client zurücksynchronisiert. Empfehlung: Verwenden Sie für lange Unterhaltungen ein primäres Gerät, -um auseinanderlaufenden Kontext zu vermeiden. Die Control UI und die TUI zeigen immer das vom Gateway -gestützte Sitzungsprotokoll an und sind daher die Quelle der Wahrheit. +Mehrere Geräte/Kanäle können derselben Sitzung zugeordnet sein, aber der Verlauf wird nicht vollständig an jeden Client zurücksynchronisiert. Empfehlung: Verwenden Sie für lange Unterhaltungen ein primäres Gerät, um auseinanderlaufenden Kontext zu vermeiden. Das Control UI und die TUI zeigen immer das Gateway-gestützte Sitzungsprotokoll an und sind daher die Quelle der Wahrheit. -Details: [Sitzungsverwaltung](/de/concepts/session). +Details: [Session management](/de/concepts/session). -## Eingehende Inhalte und Verlaufskontext +## Eingehende Nachrichtentexte und Verlaufskontext OpenClaw trennt den **Prompt-Text** vom **Befehlstext**: -- `Body`: Prompt-Text, der an den Agenten gesendet wird. Er kann Kanal-Umschläge und - optionale Verlaufs-Wrapper enthalten. -- `CommandBody`: Rohtext des Nutzers für Richtlinien-/Befehls-Parsing. -- `RawBody`: veralteter Alias für `CommandBody` (aus Kompatibilitätsgründen beibehalten). +- `Body`: Prompt-Text, der an den Agenten gesendet wird. Dieser kann Kanalumschläge und optionale Verlaufs-Wrapper enthalten. +- `CommandBody`: Roher Benutzertest für die Verarbeitung von Direktiven/Befehlen. +- `RawBody`: Veralteter Alias für `CommandBody` (aus Kompatibilitätsgründen beibehalten). Wenn ein Kanal Verlauf bereitstellt, verwendet er einen gemeinsamen Wrapper: -- `[Chat-Nachrichten seit Ihrer letzten Antwort - für Kontext]` -- `[Aktuelle Nachricht - antworten Sie darauf]` +- `[Chat messages since your last reply - for context]` +- `[Current message - respond to this]` -Bei **Nicht-Direktchats** (Gruppen/Kanäle/Räume) wird dem **Inhalt der aktuellen Nachricht** das -Absender-Label vorangestellt (im selben Stil wie bei Verlaufseinträgen). So bleiben Echtzeit- und -Warteschlangen-/Verlaufsnachrichten im Agent-Prompt konsistent. +Bei **nicht direkten Chats** (Gruppen/Kanälen/Räumen) wird dem **Text der aktuellen Nachricht** das Absenderlabel vorangestellt (im selben Stil wie bei Verlaufseinträgen). So bleiben Echtzeit- sowie in Warteschlange/Verlauf befindliche Nachrichten im Agent-Prompt konsistent. -Verlaufspuffer sind **nur ausstehend**: Sie enthalten Gruppennachrichten, die _keinen_ -Lauf ausgelöst haben (zum Beispiel durch Mention-Gating blockierte Nachrichten), und **schließen** -Nachrichten aus, die bereits im Sitzungsprotokoll vorhanden sind. +Verlaufspuffer sind **nur ausstehend**: Sie enthalten Gruppennachrichten, die _keinen_ Durchlauf ausgelöst haben (zum Beispiel durch Mention-Gating gefilterte Nachrichten), und **schließen** Nachrichten aus, die bereits im Sitzungsprotokoll stehen. -Das Entfernen von Richtlinien gilt nur für den Abschnitt der **aktuellen Nachricht**, damit der Verlauf -intakt bleibt. Kanäle, die Verlauf umschließen, sollten `CommandBody` (oder -`RawBody`) auf den ursprünglichen Nachrichtentext setzen und `Body` als kombinierten Prompt beibehalten. -Verlaufspuffer sind konfigurierbar über `messages.groupChat.historyLimit` (globaler -Standard) und kanalbezogene Überschreibungen wie `channels.slack.historyLimit` oder -`channels.telegram.accounts..historyLimit` (`0` zum Deaktivieren). +Das Entfernen von Direktiven gilt nur für den Abschnitt der **aktuellen Nachricht**, damit der Verlauf intakt bleibt. Kanäle, die Verlauf umschließen, sollten `CommandBody` (oder `RawBody`) auf den ursprünglichen Nachrichtentext setzen und `Body` als kombinierten Prompt beibehalten. Verlaufspuffer sind über `messages.groupChat.historyLimit` (globaler Standard) und kanalbezogene Überschreibungen wie `channels.slack.historyLimit` oder `channels.telegram.accounts..historyLimit` konfigurierbar (`0` zum Deaktivieren). -## Warteschlangenbildung und Nachfassaktionen +## Warteschlangenbildung und Folgeanfragen -Wenn bereits ein Lauf aktiv ist, können eingehende Nachrichten in die Warteschlange gestellt, in den -aktuellen Lauf gelenkt oder für eine nachfolgende Runde gesammelt werden. +Wenn bereits ein Durchlauf aktiv ist, können eingehende Nachrichten in die Warteschlange gestellt, in den aktuellen Durchlauf gelenkt oder für einen Folge-Turn gesammelt werden. - Konfiguration über `messages.queue` (und `messages.queue.byChannel`). - Modi: `interrupt`, `steer`, `followup`, `collect` sowie Backlog-Varianten. -Details: [Warteschlangenbildung](/de/concepts/queue). +Details: [Queueing](/de/concepts/queue). -## Streaming, Aufteilung und Bündelung +## Streaming, Chunking und Batching Block-Streaming sendet Teilantworten, während das Modell Textblöcke erzeugt. -Die Aufteilung beachtet Textgrenzen der Kanäle und vermeidet das Trennen von eingefasstem Code. +Chunking berücksichtigt Textlimits des Kanals und vermeidet das Aufteilen von Fenced-Code. Wichtige Einstellungen: -- `agents.defaults.blockStreamingDefault` (`on|off`, Standard aus) +- `agents.defaults.blockStreamingDefault` (`on|off`, Standard ist off) - `agents.defaults.blockStreamingBreak` (`text_end|message_end`) - `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`) -- `agents.defaults.blockStreamingCoalesce` (Leerlaufbasierte Bündelung) +- `agents.defaults.blockStreamingCoalesce` (leerlaufbasiertes Batching) - `agents.defaults.humanDelay` (menschenähnliche Pause zwischen Blockantworten) -- Kanalüberschreibungen: `*.blockStreaming` und `*.blockStreamingCoalesce` (Kanäle außer Telegram erfordern explizit `*.blockStreaming: true`) +- Kanalüberschreibungen: `*.blockStreaming` und `*.blockStreamingCoalesce` (Nicht-Telegram-Kanäle erfordern explizit `*.blockStreaming: true`) -Details: [Streaming + Aufteilung](/de/concepts/streaming). +Details: [Streaming + chunking](/de/concepts/streaming). -## Sichtbarkeit des Denkprozesses und Tokens +## Sichtbarkeit der Argumentation und Tokens -OpenClaw kann das Reasoning des Modells sichtbar machen oder verbergen: +OpenClaw kann Modellargumentation sichtbar machen oder verbergen: - `/reasoning on|off|stream` steuert die Sichtbarkeit. -- Reasoning-Inhalte zählen weiterhin zum Token-Verbrauch, wenn sie vom Modell erzeugt werden. -- Telegram unterstützt das Streamen von Reasoning in die Entwurfsblase. +- Argumentationsinhalte zählen weiterhin zur Tokennutzung, wenn sie vom Modell erzeugt werden. +- Telegram unterstützt das Streamen der Argumentation in die Entwurfsblase. -Details: [Thinking- + Reasoning-Richtlinien](/de/tools/thinking) und [Token-Nutzung](/de/reference/token-use). +Details: [Thinking + reasoning directives](/de/tools/thinking) und [Token use](/de/reference/token-use). ## Präfixe, Threading und Antworten @@ -158,19 +139,18 @@ Die Formatierung ausgehender Nachrichten ist zentral in `messages` gebündelt: - `messages.responsePrefix`, `channels..responsePrefix` und `channels..accounts..responsePrefix` (Kaskade für ausgehende Präfixe) sowie `channels.whatsapp.messagePrefix` (eingehendes WhatsApp-Präfix) - Antwort-Threading über `replyToMode` und kanalbezogene Standards -Details: [Konfiguration](/de/gateway/configuration-reference#messages) und die Kanaldokumentation. +Details: [Configuration](/de/gateway/configuration-reference#messages) und die Kanaldokumentation. ## Stille Antworten -Das exakte stille Token `NO_REPLY` / `no_reply` bedeutet „keine für Nutzer sichtbare Antwort zustellen“. -OpenClaw löst dieses Verhalten je nach Unterhaltungstyp auf: +Das exakte Silent-Token `NO_REPLY` / `no_reply` bedeutet „keine für Benutzer sichtbare Antwort zustellen“. +OpenClaw löst dieses Verhalten je nach Konversationstyp auf: -- Direkte Unterhaltungen erlauben standardmäßig keine Stille und schreiben eine reine stille - Antwort in einen kurzen sichtbaren Fallback um. -- Gruppen/Kanäle erlauben standardmäßig Stille. -- Interne Orchestrierung erlaubt standardmäßig Stille. +- Direkte Konversationen lassen Stille standardmäßig nicht zu und schreiben eine reine stille Antwort in eine kurze sichtbare Fallback-Antwort um. +- Gruppen/Kanäle erlauben Stille standardmäßig. +- Interne Orchestrierung erlaubt Stille standardmäßig. -Standardwerte liegen unter `agents.defaults.silentReply` und +Standardwerte befinden sich unter `agents.defaults.silentReply` und `agents.defaults.silentReplyRewrite`; `surfaces..silentReply` und `surfaces..silentReplyRewrite` können sie pro Oberfläche überschreiben. diff --git a/docs/de/concepts/model-providers.md b/docs/de/concepts/model-providers.md index 8013ea24a..27a4be0b4 100644 --- a/docs/de/concepts/model-providers.md +++ b/docs/de/concepts/model-providers.md @@ -1,14 +1,14 @@ --- read_when: - Sie benötigen eine anbieterweise Referenz zur Modelleinrichtung - - Sie möchten Beispielkonfigurationen oder CLI-Onboarding-Befehle für Modellanbieter -summary: Überblick über Modellanbieter mit Beispielkonfigurationen + CLI-Abläufen + - Sie möchten Beispielkonfigurationen oder CLI-Onboarding-Befehle für Modellanbieter. +summary: Übersicht über Modellanbieter mit Beispielkonfigurationen + CLI-Abläufen title: Modellanbieter x-i18n: - generated_at: "2026-04-21T06:24:06Z" + generated_at: "2026-04-21T13:35:27Z" model: gpt-5.4 provider: openai - source_hash: e433dfd51d1721832480089cb35ab1243e5c873a587f9968e14744840cb912cf + source_hash: 6732ab672757579c09395583a0f7d110348c909d4e4ab1d2accad68ad054c636 source_path: concepts/model-providers.md workflow: 15 --- @@ -16,135 +16,263 @@ x-i18n: # Modellanbieter Diese Seite behandelt **LLM-/Modellanbieter** (nicht Chat-Kanäle wie WhatsApp/Telegram). -Für Regeln zur Modellauswahl siehe [/concepts/models](/de/concepts/models). +Zu Regeln für die Modellauswahl siehe [/concepts/models](/de/concepts/models). -## Schnellregeln +## Schnelle Regeln -- Modell-Referenzen verwenden `provider/model` (Beispiel: `opencode/claude-opus-4-6`). -- Wenn Sie `agents.defaults.models` setzen, wird es zur Allowlist. -- CLI-Helfer: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Laufzeitregeln für Fallbacks, Cooldown-Probes und die Persistenz von Sitzungs-Overrides sind in [/concepts/model-failover](/de/concepts/model-failover) dokumentiert. -- `models.providers.*.models[].contextWindow` ist native Modellmetadaten; `models.providers.*.models[].contextTokens` ist die effektive Laufzeitgrenze. -- Anbieter-Plugins können Modellkataloge über `registerProvider({ catalog })` injizieren; OpenClaw führt diese Ausgabe in `models.providers` zusammen, bevor `models.json` geschrieben wird. -- Anbietermanifeste können `providerAuthEnvVars` und `providerAuthAliases` deklarieren, damit generische env-basierte Auth-Probes und Anbietervarianten die Plugin-Laufzeit nicht laden müssen. Die verbleibende Core-Env-Var-Map ist jetzt nur noch für Nicht-Plugin-/Core-Anbieter und einige generische Vorrangfälle gedacht, etwa Anthropic-Onboarding mit API-Schlüssel zuerst. -- Anbieter-Plugins können außerdem das Laufzeitverhalten des Anbieters besitzen über `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `contributeResolvedModelCompat`, `capabilities`, `normalizeToolSchemas`, `inspectToolSchemas`, `resolveReasoningOutputMode`, `prepareExtraParams`, `createStreamFn`, `wrapStreamFn`, `resolveTransportTurnState`, `resolveWebSocketSessionPolicy`, `createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`, `matchesContextOverflowError`, `classifyFailoverReason`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `supportsAdaptiveThinking`, `supportsMaxThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot` und `onModelSelected`. -- Hinweis: Laufzeit-`capabilities` des Anbieters sind gemeinsame Runner-Metadaten (Anbieterfamilie, Transcript-/Tooling-Eigenheiten, Transport-/Cache-Hinweise). Sie sind nicht dasselbe wie das [öffentliche Fähigkeitsmodell](/de/plugins/architecture#public-capability-model), das beschreibt, was ein Plugin registriert (Text-Inferenz, Sprache usw.). -- Der gebündelte Anbieter `codex` ist mit dem gebündelten Codex-Agent-Harness gekoppelt. Verwenden Sie `codex/gpt-*`, wenn Sie Codex-eigenen Login, Modellerkennung, native Thread-Fortsetzung und App-Server-Ausführung möchten. Einfache `openai/gpt-*`-Referenzen verwenden weiterhin den OpenAI-Anbieter und den normalen OpenClaw-Anbietertransport. Reine Codex-Deployments können den automatischen PI-Fallback mit `agents.defaults.embeddedHarness.fallback: "none"` deaktivieren; siehe [Codex Harness](/de/plugins/codex-harness). +- Modellreferenzen verwenden `provider/model` (Beispiel: `opencode/claude-opus-4-6`). +- Wenn Sie `agents.defaults.models` festlegen, wird es zur Zulassungsliste. +- CLI-Hilfen: `openclaw onboard`, `openclaw models list`, `openclaw models set `. +- Fallback-Laufzeitregeln, Cooldown-Sondierungen und die Persistenz von Sitzungsüberschreibungen + sind in [/concepts/model-failover](/de/concepts/model-failover) dokumentiert. +- `models.providers.*.models[].contextWindow` sind native Modellmetadaten; + `models.providers.*.models[].contextTokens` ist die effektive Laufzeitobergrenze. +- Anbieter-Plugins können Modellkataloge über `registerProvider({ catalog })` einschleusen; + OpenClaw führt diese Ausgabe vor dem Schreiben von + `models.json` in `models.providers` zusammen. +- Anbieter-Manifeste können `providerAuthEnvVars` und + `providerAuthAliases` deklarieren, sodass generische umgebungsvariablenbasierte Authentifizierungsprüfungen und Anbietervarianten + die Plugin-Laufzeit nicht laden müssen. Die verbleibende Kern-Zuordnung für Umgebungsvariablen ist jetzt + nur noch für Nicht-Plugin-/Kern-Anbieter und einige generische Präzedenzfälle gedacht, etwa + Anthropic-Onboarding mit API-Schlüssel zuerst. +- Anbieter-Plugins können auch das Laufzeitverhalten des Anbieters über + `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, + `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, + `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, + `resolveDynamicModel`, `prepareDynamicModel`, + `normalizeResolvedModel`, `contributeResolvedModelCompat`, + `capabilities`, `normalizeToolSchemas`, + `inspectToolSchemas`, `resolveReasoningOutputMode`, + `prepareExtraParams`, `createStreamFn`, `wrapStreamFn`, + `resolveTransportTurnState`, `resolveWebSocketSessionPolicy`, + `createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`, + `buildAuthDoctorHint`, + `matchesContextOverflowError`, `classifyFailoverReason`, + `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, + `augmentModelCatalog`, `resolveThinkingProfile`, `isBinaryThinking`, + `supportsXHighThinking`, `resolveDefaultThinkingLevel`, + `applyConfigDefaults`, `isModernModelRef`, + `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot` und + `onModelSelected` besitzen. +- Hinweis: Laufzeit-`capabilities` des Anbieters sind gemeinsame Runner-Metadaten (Anbieterfamilie, + Eigenheiten bei Transkripten/Tooling, Hinweise zu Transport/Cache). Sie sind nicht + dasselbe wie das [öffentliche Fähigkeitsmodell](/de/plugins/architecture#public-capability-model), + das beschreibt, was ein Plugin registriert (Textinferenz, Sprache usw.). +- Der gebündelte `codex`-Anbieter ist mit dem gebündelten Codex-Agent-Harness gekoppelt. + Verwenden Sie `codex/gpt-*`, wenn Sie Codex-eigenes Login, Modellerkennung, natives + Fortsetzen von Threads und Ausführung auf dem App-Server möchten. Einfache Referenzen wie `openai/gpt-*` + verwenden weiterhin den OpenAI-Anbieter und den normalen OpenClaw-Anbietertransport. + Rein auf Codex ausgerichtete Deployments können automatischen PI-Fallback mit + `agents.defaults.embeddedHarness.fallback: "none"` deaktivieren; siehe + [Codex Harness](/de/plugins/codex-harness). ## Plugin-eigenes Anbieterverhalten -Anbieter-Plugins können nun den Großteil der anbieterspezifischen Logik besitzen, während OpenClaw die generische Inferenzschleife beibehält. +Anbieter-Plugins können jetzt den Großteil der anbieterspezifischen Logik besitzen, während OpenClaw +die generische Inferenzschleife beibehält. Typische Aufteilung: -- `auth[].run` / `auth[].runNonInteractive`: Anbieter besitzt Onboarding-/Login-Abläufe für `openclaw onboard`, `openclaw models auth` und Headless-Setup -- `wizard.setup` / `wizard.modelPicker`: Anbieter besitzt Beschriftungen für Auth-Auswahl, Legacy-Aliasse, Hinweise zur Onboarding-Allowlist und Setup-Einträge in Onboarding-/Modell-Pickern -- `catalog`: Anbieter erscheint in `models.providers` -- `normalizeModelId`: Anbieter normalisiert Legacy-/Vorschau-Modell-IDs vor Lookup oder Kanonisierung -- `normalizeTransport`: Anbieter normalisiert `api` / `baseUrl` der Transportfamilie vor dem generischen Modellaufbau; OpenClaw prüft zuerst den passenden Anbieter, dann andere hook-fähige Anbieter-Plugins, bis eines den Transport tatsächlich ändert -- `normalizeConfig`: Anbieter normalisiert die Konfiguration `models.providers.`, bevor die Laufzeit sie verwendet; OpenClaw prüft zuerst den passenden Anbieter, dann andere hook-fähige Anbieter-Plugins, bis eines die Konfiguration tatsächlich ändert. Wenn kein Anbieter-Hook die Konfiguration umschreibt, normalisieren gebündelte Google-Familien-Helfer weiterhin unterstützte Google-Anbietereinträge. -- `applyNativeStreamingUsageCompat`: Anbieter wendet endpoint-gesteuerte native Kompatibilitätsumschreibungen für Streaming-Nutzung auf Konfigurationsanbieter an -- `resolveConfigApiKey`: Anbieter löst Env-Marker-Auth für Konfigurationsanbieter auf, ohne das vollständige Laden der Laufzeit-Auth zu erzwingen. `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, obwohl die Bedrock-Laufzeit-Auth die AWS-SDK-Standardkette verwendet. -- `resolveSyntheticAuth`: Anbieter kann lokale/self-hosted oder andere konfigurationsgestützte Auth-Verfügbarkeit verfügbar machen, ohne Klartext-Geheimnisse zu persistieren -- `shouldDeferSyntheticProfileAuth`: Anbieter kann gespeicherte synthetische Profil-Platzhalter als niedrigere Priorität als env-/konfigurationsgestützte Auth markieren -- `resolveDynamicModel`: Anbieter akzeptiert Modell-IDs, die noch nicht im lokalen statischen Katalog vorhanden sind -- `prepareDynamicModel`: Anbieter benötigt eine Aktualisierung der Metadaten, bevor die dynamische Auflösung erneut versucht wird -- `normalizeResolvedModel`: Anbieter benötigt Umschreibungen von Transport oder Basis-URL -- `contributeResolvedModelCompat`: Anbieter steuert Kompatibilitätsflags für seine Vendor-Modelle bei, selbst wenn sie über einen anderen kompatiblen Transport eintreffen -- `capabilities`: Anbieter veröffentlicht Eigenheiten von Transcript/Tooling/Anbieterfamilie -- `normalizeToolSchemas`: Anbieter bereinigt Tool-Schemas, bevor der eingebettete Runner sie sieht -- `inspectToolSchemas`: Anbieter macht transportspezifische Schemawarnungen nach der Normalisierung sichtbar -- `resolveReasoningOutputMode`: Anbieter wählt native oder getaggte Verträge für Reasoning-Ausgabe -- `prepareExtraParams`: Anbieter setzt Standardwerte oder normalisiert anfragespezifische Parameter pro Modell -- `createStreamFn`: Anbieter ersetzt den normalen Stream-Pfad durch einen vollständig benutzerdefinierten Transport -- `wrapStreamFn`: Anbieter wendet Wrapper für Anfrage-Header/Body/Modell-Kompatibilität an -- `resolveTransportTurnState`: Anbieter liefert native Header oder Metadaten des Transports pro Turn -- `resolveWebSocketSessionPolicy`: Anbieter liefert native Header für WebSocket-Sitzungen oder eine Sitzungs-Cooldown-Richtlinie -- `createEmbeddingProvider`: Anbieter besitzt das Verhalten von Memory Embeddings, wenn es zum Anbieter-Plugin statt zum Core-Embedding-Switchboard gehört -- `formatApiKey`: Anbieter formatiert gespeicherte Auth-Profile in den von dem Transport erwarteten Laufzeit-String `apiKey` -- `refreshOAuth`: Anbieter besitzt das OAuth-Refresh, wenn die gemeinsamen `pi-ai`-Refresher nicht ausreichen -- `buildAuthDoctorHint`: Anbieter ergänzt Reparaturhinweise, wenn das OAuth-Refresh fehlschlägt -- `matchesContextOverflowError`: Anbieter erkennt anbieterspezifische Fehler bei Überschreitung des Kontextfensters, die generische Heuristiken übersehen würden -- `classifyFailoverReason`: Anbieter ordnet anbieterspezifische rohe Transport-/API-Fehler Failover-Gründen wie Rate Limit oder Überlastung zu -- `isCacheTtlEligible`: Anbieter entscheidet, welche Upstream-Modell-IDs Prompt-Cache-TTL unterstützen -- `buildMissingAuthMessage`: Anbieter ersetzt den generischen Fehler des Auth-Speichers durch einen anbieterspezifischen Wiederherstellungshinweis -- `suppressBuiltInModel`: Anbieter blendet veraltete Upstream-Zeilen aus und kann für direkte Auflösungsfehler einen Vendor-eigenen Fehler zurückgeben -- `augmentModelCatalog`: Anbieter hängt nach Erkennung und Konfigurationszusammenführung synthetische/finale Katalogzeilen an -- `isBinaryThinking`: Anbieter besitzt die UX für binäres Thinking mit Ein/Aus -- `supportsXHighThinking`: Anbieter aktiviert `xhigh` für ausgewählte Modelle -- `supportsAdaptiveThinking`: Anbieter aktiviert `adaptive` für ausgewählte Modelle -- `supportsMaxThinking`: Anbieter aktiviert `max` für ausgewählte Modelle -- `resolveDefaultThinkingLevel`: Anbieter besitzt die Standardrichtlinie von `/think` für eine Modellfamilie -- `applyConfigDefaults`: Anbieter wendet anbieterspezifische globale Standardwerte während der Konfigurationsmaterialisierung an, basierend auf Auth-Modus, env oder Modellfamilie -- `isModernModelRef`: Anbieter besitzt die Zuordnung bevorzugter Modelle für Live-/Smoke-Tests -- `prepareRuntimeAuth`: Anbieter wandelt konfigurierte Zugangsdaten in ein kurzlebiges Laufzeit-Token um -- `resolveUsageAuth`: Anbieter löst Nutzungs-/Quota-Zugangsdaten für `/usage` und verwandte Status-/Reporting-Oberflächen auf -- `fetchUsageSnapshot`: Anbieter besitzt das Abrufen/Parsen des Nutzungsendpunkts, während der Core weiterhin die Zusammenfassungshülle und Formatierung besitzt -- `onModelSelected`: Anbieter führt Nebeneffekte nach der Modellauswahl aus, etwa Telemetrie oder anbieter-eigene Sitzungsbuchführung +- `auth[].run` / `auth[].runNonInteractive`: Der Anbieter besitzt Onboarding-/Login- + Abläufe für `openclaw onboard`, `openclaw models auth` und Headless-Setup +- `wizard.setup` / `wizard.modelPicker`: Der Anbieter besitzt Labels für die Authentifizierungsauswahl, + Legacy-Aliasse, Hinweise zur Zulassungsliste beim Onboarding und Setup-Einträge in Onboarding-/Modellauswahlen +- `catalog`: Der Anbieter erscheint in `models.providers` +- `normalizeModelId`: Der Anbieter normalisiert Legacy-/Vorschau-Modell-IDs vor + Nachschlagen oder Kanonisierung +- `normalizeTransport`: Der Anbieter normalisiert die Transportfamilie `api` / `baseUrl` + vor der generischen Modellzusammenstellung; OpenClaw prüft zuerst den passenden Anbieter, + dann andere Hook-fähige Anbieter-Plugins, bis eines den + Transport tatsächlich ändert +- `normalizeConfig`: Der Anbieter normalisiert die Konfiguration `models.providers.` vor + der Verwendung zur Laufzeit; OpenClaw prüft zuerst den passenden Anbieter, dann andere + Hook-fähige Anbieter-Plugins, bis eines die Konfiguration tatsächlich ändert. Falls kein + Anbieter-Hook die Konfiguration umschreibt, normalisieren die gebündelten Helfer der Google-Familie weiterhin + unterstützte Google-Anbietereinträge. +- `applyNativeStreamingUsageCompat`: Der Anbieter wendet endpointgesteuerte native Streaming-/Nutzungs-Kompatibilitäts-Umschreibungen für Konfigurationsanbieter an +- `resolveConfigApiKey`: Der Anbieter löst Authentifizierung über Umgebungsvariablenmarker für Konfigurationsanbieter auf, + ohne das vollständige Laden der Laufzeit-Authentifizierung zu erzwingen. `amazon-bedrock` hat hier + ebenfalls einen eingebauten AWS-Resolver für Umgebungsvariablenmarker, obwohl die Bedrock-Laufzeit-Authentifizierung + die Standardkette des AWS SDK verwendet. +- `resolveSyntheticAuth`: Der Anbieter kann lokale/selbstgehostete oder andere + konfigurationsgestützte Authentifizierungsverfügbarkeit offenlegen, ohne Klartext-Geheimnisse zu speichern +- `shouldDeferSyntheticProfileAuth`: Der Anbieter kann gespeicherte synthetische Profil- + Platzhalter als niedrigere Priorität als umgebungs-/konfigurationsgestützte Authentifizierung markieren +- `resolveDynamicModel`: Der Anbieter akzeptiert Modell-IDs, die im lokalen + statischen Katalog noch nicht vorhanden sind +- `prepareDynamicModel`: Der Anbieter benötigt eine Metadatenaktualisierung, bevor die + dynamische Auflösung erneut versucht wird +- `normalizeResolvedModel`: Der Anbieter benötigt Umschreibungen von Transport oder Basis-URL +- `contributeResolvedModelCompat`: Der Anbieter steuert Kompatibilitäts-Flags für seine + Herstellermodelle bei, auch wenn diese über einen anderen kompatiblen Transport ankommen +- `capabilities`: Der Anbieter veröffentlicht Eigenheiten zu Transkripten/Tooling/Anbieterfamilie +- `normalizeToolSchemas`: Der Anbieter bereinigt Tool-Schemata, bevor der eingebettete + Runner sie sieht +- `inspectToolSchemas`: Der Anbieter zeigt transportspezifische Schemawarnungen + nach der Normalisierung an +- `resolveReasoningOutputMode`: Der Anbieter wählt native oder getaggte + Verträge für die Ausgabebegründung +- `prepareExtraParams`: Der Anbieter setzt Standardwerte oder normalisiert anfragebezogene Parameter pro Modell +- `createStreamFn`: Der Anbieter ersetzt den normalen Streaming-Pfad durch einen vollständig + benutzerdefinierten Transport +- `wrapStreamFn`: Der Anbieter wendet Wrapper für Anfrage-Header/Body/Modell-Kompatibilität an +- `resolveTransportTurnState`: Der Anbieter liefert native Transport- + Header oder Metadaten pro Zug +- `resolveWebSocketSessionPolicy`: Der Anbieter liefert native WebSocket-Sitzungs- + Header oder Cooldown-Richtlinien für Sitzungen +- `createEmbeddingProvider`: Der Anbieter besitzt das Verhalten für Speicher-Embeddings, wenn es + eher zum Anbieter-Plugin als zum Kern-Switchboard für Embeddings gehört +- `formatApiKey`: Der Anbieter formatiert gespeicherte Authentifizierungsprofile in den zur Laufzeit + vom Transport erwarteten `apiKey`-String +- `refreshOAuth`: Der Anbieter besitzt die OAuth-Aktualisierung, wenn die gemeinsamen + `pi-ai`-Aktualisierer nicht ausreichen +- `buildAuthDoctorHint`: Der Anbieter fügt Reparaturhinweise an, wenn die OAuth-Aktualisierung + fehlschlägt +- `matchesContextOverflowError`: Der Anbieter erkennt anbieterspezifische + Fehler bei Überschreitung des Kontextfensters, die generische Heuristiken übersehen würden +- `classifyFailoverReason`: Der Anbieter ordnet anbieterspezifische rohe Transport-/API- + Fehler Failover-Gründen wie Ratenbegrenzung oder Überlastung zu +- `isCacheTtlEligible`: Der Anbieter entscheidet, welche Upstream-Modell-IDs Prompt-Cache-TTL unterstützen +- `buildMissingAuthMessage`: Der Anbieter ersetzt den generischen Fehler des Authentifizierungsspeichers + durch einen anbieterspezifischen Wiederherstellungshinweis +- `suppressBuiltInModel`: Der Anbieter blendet veraltete Upstream-Zeilen aus und kann bei + direkten Auflösungsfehlern einen herstellereigenen Fehler zurückgeben +- `augmentModelCatalog`: Der Anbieter fügt nach Erkennung und Konfigurationszusammenführung + synthetische/finale Katalogzeilen an +- `resolveThinkingProfile`: Der Anbieter besitzt die genaue Menge an `/think`-Stufen, + optionale Anzeigelabels und die Standardstufe für ein ausgewähltes Modell +- `isBinaryThinking`: Kompatibilitäts-Hook für binäre Denk-UX mit Ein/Aus +- `supportsXHighThinking`: Kompatibilitäts-Hook für ausgewählte `xhigh`-Modelle +- `resolveDefaultThinkingLevel`: Kompatibilitäts-Hook für die Standardrichtlinie von `/think` +- `applyConfigDefaults`: Der Anbieter wendet anbieterspezifische globale Standardwerte + während der Konfigurationsmaterialisierung basierend auf Authentifizierungsmodus, Umgebung oder Modellfamilie an +- `isModernModelRef`: Der Anbieter besitzt den Abgleich bevorzugter Modelle für Live-/Smoke-Tests +- `prepareRuntimeAuth`: Der Anbieter wandelt ein konfiguriertes Zugangsmittel in ein kurzlebiges + Laufzeit-Token um +- `resolveUsageAuth`: Der Anbieter löst Zugangsdaten für Nutzung/Kontingent für `/usage` + und verwandte Status-/Berichtsoberflächen auf +- `fetchUsageSnapshot`: Der Anbieter besitzt das Abrufen/Parsen des Nutzungsendpunkts, während der + Kern weiterhin die Zusammenfassungs-Shell und Formatierung besitzt +- `onModelSelected`: Der Anbieter führt Nebeneffekte nach der Auswahl aus, etwa + Telemetrie oder anbietereigene Sitzungsbuchführung Aktuelle gebündelte Beispiele: -- `anthropic`: Claude-4.6-Vorwärtskompatibilitäts-Fallback, Hinweise zur Auth-Reparatur, Abruf des Nutzungsendpunkts, Metadaten zu Cache-TTL/Anbieterfamilie und Auth-bewusste globale Konfigurationsstandards -- `amazon-bedrock`: Anbieter-eigenes Matching für Kontextüberlauf und Klassifizierung von Failover-Gründen für Bedrock-spezifische Drosselungs-/Nicht-bereit-Fehler sowie die gemeinsame Replay-Familie `anthropic-by-model` für Claude-exklusive Replay-Policy-Schutzmechanismen auf Anthropic-Datenverkehr -- `anthropic-vertex`: Claude-exklusive Replay-Policy-Schutzmechanismen auf Anthropic-Message-Datenverkehr -- `openrouter`: Durchreichen von Modell-IDs, Anfrage-Wrapper, Hinweise zu Anbieterfähigkeiten, Bereinigung von Gemini-Thought-Signaturen auf Proxy-Gemini-Datenverkehr, Proxy-Reasoning-Injektion über die Stream-Familie `openrouter-thinking`, Weiterleitung von Routing-Metadaten und Cache-TTL-Richtlinie -- `github-copilot`: Onboarding/Geräte-Login, Vorwärtskompatibilitäts-Fallback für Modelle, Hinweise zu Claude-Thinking-Transkripten, Austausch von Laufzeit-Token und Abruf des Nutzungsendpunkts -- `openai`: GPT-5.4-Vorwärtskompatibilitäts-Fallback, direkte Normalisierung des OpenAI-Transports, Codex-bewusste Hinweise für fehlende Auth, Unterdrückung von Spark, synthetische OpenAI-/Codex-Katalogzeilen, Thinking-/Live-Modell-Richtlinie, Alias-Normalisierung für Usage-Token (`input` / `output` und `prompt` / `completion`-Familien), die gemeinsame Stream-Familie `openai-responses-defaults` für native OpenAI-/Codex-Wrapper, Metadaten zur Anbieterfamilie, gebündelte Registrierung des Bildgenerierungsanbieters für `gpt-image-1` und gebündelte Registrierung des Videogenerierungsanbieters für `sora-2` -- `google` und `google-gemini-cli`: Gemini-3.1-Vorwärtskompatibilitäts-Fallback, native Gemini-Replay-Validierung, Bereinigung von Bootstrap-Replay, getaggter Ausgabemodus für Reasoning, modernes Modell-Matching, gebündelte Registrierung des Bildgenerierungsanbieters für Gemini-Image-Preview-Modelle und gebündelte Registrierung des Videogenerierungsanbieters für Veo-Modelle; Gemini-CLI-OAuth besitzt außerdem die Formatierung von Auth-Profil-Token, das Parsen von Usage-Token und das Abrufen von Quotenendpunkten für Usage-Oberflächen -- `moonshot`: gemeinsamer Transport, Plugin-eigene Normalisierung der Thinking-Payload -- `kilocode`: gemeinsamer Transport, Plugin-eigene Anfrage-Header, Normalisierung der Reasoning-Payload, Bereinigung von Proxy-Gemini-Thought-Signaturen und Cache-TTL-Richtlinie -- `zai`: GLM-5-Vorwärtskompatibilitäts-Fallback, Standardwerte für `tool_stream`, Cache-TTL-Richtlinie, Richtlinie für binäres Thinking/Live-Modelle und Usage-Auth + Quotenabruf; unbekannte `glm-5*`-IDs werden aus der gebündelten Vorlage `glm-4.7` synthetisiert -- `xai`: native Normalisierung des Responses-Transports, Umschreibungen von `/fast`-Aliasen für schnelle Grok-Varianten, Standard `tool_stream`, xAI-spezifische Bereinigung von Tool-Schemas / Reasoning-Payload und gebündelte Registrierung des Videogenerierungsanbieters für `grok-imagine-video` -- `mistral`: Plugin-eigene Metadaten zu Fähigkeiten -- `opencode` und `opencode-go`: Plugin-eigene Metadaten zu Fähigkeiten sowie Bereinigung von Proxy-Gemini-Thought-Signaturen -- `alibaba`: Plugin-eigener Videogenerierungskatalog für direkte Wan-Modell-Referenzen wie `alibaba/wan2.6-t2v` -- `byteplus`: Plugin-eigene Kataloge sowie gebündelte Registrierung des Videogenerierungsanbieters für Seedance-Text-zu-Video-/Bild-zu-Video-Modelle -- `fal`: gebündelte Registrierung des Videogenerierungsanbieters für gehostete Bildgenerierungsanbieter-Registrierung für FLUX-Bildmodelle sowie gebündelte Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter-Videomodelle -- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` und `volcengine`: nur Plugin-eigene Kataloge -- `qwen`: Plugin-eigene Kataloge für Textmodelle sowie gemeinsame Registrierungen von Anbietern für Medienverständnis und Videogenerierung für seine multimodalen Oberflächen; die Videogenerierung von Qwen verwendet die Standard-DashScope-Videoendpunkte mit gebündelten Wan-Modellen wie `wan2.6-t2v` und `wan2.7-r2v` -- `runway`: Plugin-eigene Registrierung des Videogenerierungsanbieters für native, auf Aufgaben basierende Runway-Modelle wie `gen4.5` -- `minimax`: Plugin-eigene Kataloge, gebündelte Registrierung des Videogenerierungsanbieters für Hailuo-Videomodelle, gebündelte Registrierung des Bildgenerierungsanbieters für `image-01`, hybride Auswahl der Anthropic-/OpenAI-Replay-Policy und Usage-Auth-/Snapshot-Logik -- `together`: Plugin-eigene Kataloge sowie gebündelte Registrierung des Videogenerierungsanbieters für Wan-Videomodelle -- `xiaomi`: Plugin-eigene Kataloge sowie Usage-Auth-/Snapshot-Logik +- `anthropic`: Claude-4.6-Vorwärtskompatibilitäts-Fallback, Hinweise zur Authentifizierungsreparatur, Abrufen des Nutzungsendpunkts, + Cache-TTL-/Anbieterfamilien-Metadaten und auth-bewusste globale + Konfigurationsstandards +- `amazon-bedrock`: anbieterseitige Erkennung von Kontextüberläufen und Failover- + Klassifizierung für Bedrock-spezifische Drosselungs-/Nicht-bereit-Fehler, plus + die gemeinsame Replay-Familie `anthropic-by-model` für Claude-spezifische Replay-Richtlinien- + Schutzmechanismen für Anthropic-Datenverkehr +- `anthropic-vertex`: Claude-spezifische Replay-Richtlinien-Schutzmechanismen für Anthropic-Message- + Datenverkehr +- `openrouter`: Durchreichen von Modell-IDs, Anfrage-Wrapper, Hinweise auf Anbieterfähigkeiten, + Bereinigung von Gemini-Thought-Signaturen bei proxied Gemini-Datenverkehr, Proxy- + Begründungsinjektion über die Stream-Familie `openrouter-thinking`, Weiterleitung von Routing- + Metadaten und Cache-TTL-Richtlinie +- `github-copilot`: Onboarding/Geräte-Login, Vorwärtskompatibilitäts-Modell-Fallback, + Hinweise zu Claude-Thinking-Transkripten, Austausch von Laufzeit-Token und Abrufen des Nutzungsendpunkts +- `openai`: GPT-5.4-Vorwärtskompatibilitäts-Fallback, direkte OpenAI-Transport- + Normalisierung, Codex-bewusste Hinweise bei fehlender Authentifizierung, Spark-Unterdrückung, + synthetische OpenAI-/Codex-Katalogzeilen, Thinking-/Live-Modell-Richtlinie, Normalisierung von + Nutzungs-Token-Aliasen (`input` / `output` und `prompt` / `completion`-Familien), die + gemeinsame Stream-Familie `openai-responses-defaults` für native OpenAI-/Codex- + Wrapper, Anbieterfamilien-Metadaten, gebündelte Registrierung des Bildgenerierungsanbieters + für `gpt-image-1` und gebündelte Registrierung des Videogenerierungsanbieters + für `sora-2` +- `google` und `google-gemini-cli`: Gemini-3.1-Vorwärtskompatibilitäts-Fallback, + native Gemini-Replay-Validierung, Bootstrap-Replay-Bereinigung, getaggter + Begründungsausgabemodus, Abgleich moderner Modelle, gebündelte Registrierung des Bildgenerierungs- + anbieter für Gemini-Image-Preview-Modelle und gebündelte + Registrierung des Videogenerierungsanbieters für Veo-Modelle; Gemini-CLI-OAuth + besitzt außerdem die Formatierung von Authentifizierungsprofil-Token, das Parsen von Nutzungs-Token + und das Abrufen des Kontingent-Endpunkts für Nutzungsoberflächen +- `moonshot`: gemeinsamer Transport, plugin-eigene Normalisierung von Thinking-Payloads +- `kilocode`: gemeinsamer Transport, plugin-eigene Anfrage-Header, Normalisierung von Reasoning-Payloads, + Bereinigung von Proxy-Gemini-Thought-Signaturen und Cache-TTL- + Richtlinie +- `zai`: GLM-5-Vorwärtskompatibilitäts-Fallback, `tool_stream`-Standards, Cache-TTL- + Richtlinie, binäre Thinking-/Live-Modell-Richtlinie und Nutzungsauthentifizierung + Abruf von Kontingenten; + unbekannte `glm-5*`-IDs werden aus der gebündelten Vorlage `glm-4.7` synthetisiert +- `xai`: native Responses-Transportnormalisierung, Umschreibungen von `/fast`-Aliasen für + schnelle Grok-Varianten, Standardwert `tool_stream`, xAI-spezifische Bereinigung von Tool-Schemata / + Reasoning-Payloads und gebündelte Registrierung des Videogenerierungsanbieters + für `grok-imagine-video` +- `mistral`: plugin-eigene Fähigkeitsmetadaten +- `opencode` und `opencode-go`: plugin-eigene Fähigkeitsmetadaten plus + Bereinigung von Proxy-Gemini-Thought-Signaturen +- `alibaba`: plugin-eigener Videogenerierungskatalog für direkte Wan-Modellreferenzen + wie `alibaba/wan2.6-t2v` +- `byteplus`: plugin-eigene Kataloge plus gebündelte Registrierung des Videogenerierungsanbieters + für Seedance-Text-zu-Video-/Bild-zu-Video-Modelle +- `fal`: gebündelte Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter- + Registrierung des Bildgenerierungsanbieters für FLUX-Bildmodelle plus gebündelte + Registrierung des Videogenerierungsanbieters für gehostete Drittanbieter-Videomodelle +- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, + `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` und `volcengine`: + nur plugin-eigene Kataloge +- `qwen`: plugin-eigene Kataloge für Textmodelle plus gemeinsame + Registrierungen für Medienverständnis- und Videogenerierungsanbieter für seine + multimodalen Oberflächen; die Qwen-Videogenerierung verwendet die Standard-DashScope-Video- + Endpunkte mit gebündelten Wan-Modellen wie `wan2.6-t2v` und `wan2.7-r2v` +- `runway`: plugin-eigene Registrierung des Videogenerierungsanbieters für native + aufgabenbasierte Runway-Modelle wie `gen4.5` +- `minimax`: plugin-eigene Kataloge, gebündelte Registrierung des Videogenerierungsanbieters + für Hailuo-Videomodelle, gebündelte Registrierung des Bildgenerierungsanbieters + für `image-01`, hybride Auswahl von Anthropic-/OpenAI-Replay-Richtlinien + und Nutzungsauthentifizierung/Snapshot-Logik +- `together`: plugin-eigene Kataloge plus gebündelte Registrierung des Videogenerierungsanbieters + für Wan-Videomodelle +- `xiaomi`: plugin-eigene Kataloge plus Nutzungsauthentifizierung/Snapshot-Logik -Das gebündelte Plugin `openai` besitzt nun beide Anbieter-IDs: `openai` und `openai-codex`. +Das gebündelte Plugin `openai` besitzt jetzt beide Anbieter-IDs: `openai` und +`openai-codex`. -Damit sind Anbieter abgedeckt, die noch in die normalen Transporte von OpenClaw passen. Ein Anbieter, der einen vollständig benutzerdefinierten Anfrage-Executor benötigt, ist eine separate, tiefere Erweiterungsoberfläche. +Damit sind Anbieter abgedeckt, die noch in die normalen Transporte von OpenClaw passen. Ein Anbieter, +der einen vollständig benutzerdefinierten Anfrage-Executor benötigt, ist eine separate, tiefere Erweiterungsoberfläche. -## API-Schlüssel-Rotation +## API-Schlüsselrotation - Unterstützt generische Anbieterrotation für ausgewählte Anbieter. - Konfigurieren Sie mehrere Schlüssel über: - - `OPENCLAW_LIVE__KEY` (einzelner Live-Override, höchste Priorität) - - `_API_KEYS` (durch Komma oder Semikolon getrennte Liste) + - `OPENCLAW_LIVE__KEY` (einzelne Live-Überschreibung, höchste Priorität) + - `_API_KEYS` (kommagetrennte oder semikolongetrennte Liste) - `_API_KEY` (primärer Schlüssel) - `_API_KEY_*` (nummerierte Liste, z. B. `_API_KEY_1`) -- Für Google-Anbieter wird `GOOGLE_API_KEY` zusätzlich als Fallback einbezogen. -- Die Reihenfolge der Schlüsselauswahl bewahrt die Priorität und entfernt doppelte Werte. -- Anfragen werden nur bei Antworten mit Rate-Limit mit dem nächsten Schlüssel wiederholt (zum Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` oder periodische Meldungen zu Usage-Limits). -- Fehler, die keine Rate-Limits sind, schlagen sofort fehl; es wird keine Schlüsselrotation versucht. -- Wenn alle Kandidatenschlüssel fehlschlagen, wird der letzte Fehler des letzten Versuchs zurückgegeben. +- Für Google-Anbieter ist `GOOGLE_API_KEY` zusätzlich als Fallback enthalten. +- Die Reihenfolge der Schlüsselauswahl bewahrt die Priorität und dedupliziert Werte. +- Anfragen werden nur bei Antworten mit Ratenbegrenzung mit dem nächsten Schlüssel wiederholt (zum + Beispiel `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +concurrent requests`, `ThrottlingException`, `concurrency limit reached`, + `workers_ai ... quota limit exceeded` oder periodische Meldungen über Nutzungslimits). +- Fehler, die keine Ratenbegrenzung sind, schlagen sofort fehl; es wird keine Schlüsselrotation versucht. +- Wenn alle Kandidatenschlüssel fehlschlagen, wird der letzte Fehler aus dem letzten Versuch zurückgegeben. -## Eingebaute Anbieter (pi-ai-Katalog) +## Integrierte Anbieter (pi-ai-Katalog) -OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **keine** Konfiguration in `models.providers`; setzen Sie einfach Auth und wählen Sie ein Modell. +OpenClaw wird mit dem pi-ai-Katalog ausgeliefert. Diese Anbieter benötigen **keine** +Konfiguration in `models.providers`; setzen Sie einfach die Authentifizierung und wählen Sie ein Modell. ### OpenAI - Anbieter: `openai` -- Auth: `OPENAI_API_KEY` -- Optionale Rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2` sowie `OPENCLAW_LIVE_OPENAI_KEY` (einzelner Override) +- Authentifizierung: `OPENAI_API_KEY` +- Optionale Rotation: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (einzelne Überschreibung) - Beispielmodelle: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Standardtransport ist `auto` (WebSocket zuerst, SSE als Fallback) -- Pro Modell überschreiben über `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) -- OpenAI-Responses-WebSocket-Warm-up ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`) -- OpenAI-Prioritätsverarbeitung kann über `agents.defaults.models["openai/"].params.serviceTier` aktiviert werden -- `/fast` und `params.fastMode` ordnen direkte `openai/*`-Responses-Anfragen `service_tier=priority` auf `api.openai.com` zu -- Verwenden Sie `params.serviceTier`, wenn Sie eine explizite Stufe statt des gemeinsamen Schalters `/fast` möchten -- Versteckte OpenClaw-Attributions-Header (`originator`, `version`, `User-Agent`) gelten nur für nativen OpenAI-Datenverkehr zu `api.openai.com`, nicht für generische OpenAI-kompatible Proxys -- Native OpenAI-Routen behalten außerdem Responses-`store`, Prompt-Cache-Hinweise und OpenAI-Reasoning-kompatibles Payload-Shaping bei; Proxy-Routen nicht -- `openai/gpt-5.3-codex-spark` wird in OpenClaw absichtlich unterdrückt, weil die Live-OpenAI-API es ablehnt; Spark wird als Codex-exklusiv behandelt +- Der Standardtransport ist `auto` (zuerst WebSocket, SSE als Fallback) +- Überschreiben Sie pro Modell über `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) +- Das OpenAI-Responses-WebSocket-Warm-up ist standardmäßig über `params.openaiWsWarmup` aktiviert (`true`/`false`) +- Die OpenAI-Prioritätsverarbeitung kann über `agents.defaults.models["openai/"].params.serviceTier` aktiviert werden +- `/fast` und `params.fastMode` ordnen direkte `openai/*`-Responses-Anfragen auf `api.openai.com` `service_tier=priority` zu +- Verwenden Sie `params.serviceTier`, wenn Sie statt des gemeinsamen `/fast`-Schalters einen expliziten Tier wünschen +- Versteckte OpenClaw-Attributions-Header (`originator`, `version`, + `User-Agent`) gelten nur für nativen OpenAI-Datenverkehr zu `api.openai.com`, nicht + für generische OpenAI-kompatible Proxys +- Native OpenAI-Routen behalten außerdem `store` für Responses, Prompt-Cache-Hinweise und + OpenAI-Reasoning-kompatible Payload-Formung bei; Proxy-Routen nicht +- `openai/gpt-5.3-codex-spark` wird in OpenClaw absichtlich unterdrückt, weil die Live-OpenAI-API es ablehnt; Spark wird als nur für Codex behandelt ```json5 { @@ -155,13 +283,13 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### Anthropic - Anbieter: `anthropic` -- Auth: `ANTHROPIC_API_KEY` -- Optionale Rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2` sowie `OPENCLAW_LIVE_ANTHROPIC_KEY` (einzelner Override) +- Authentifizierung: `ANTHROPIC_API_KEY` +- Optionale Rotation: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (einzelne Überschreibung) - Beispielmodell: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Direkte öffentliche Anthropic-Anfragen unterstützen den gemeinsamen Schalter `/fast` und `params.fastMode`, einschließlich mit API-Schlüssel und OAuth authentifiziertem Datenverkehr an `api.anthropic.com`; OpenClaw ordnet das Anthropic-`service_tier` zu (`auto` vs `standard_only`) -- Anthropic-Hinweis: Mitarbeitende von Anthropic haben uns mitgeteilt, dass die Verwendung im Stil der Claude CLI mit OpenClaw wieder erlaubt ist, daher behandelt OpenClaw die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. -- Anthropic-Setup-Token bleibt als unterstützter OpenClaw-Tokenpfad verfügbar, aber OpenClaw bevorzugt nun, wenn verfügbar, die Wiederverwendung der Claude CLI und `claude -p`. +- Direkte öffentliche Anthropic-Anfragen unterstützen auch den gemeinsamen `/fast`-Schalter und `params.fastMode`, einschließlich per API-Schlüssel und OAuth authentifiziertem Datenverkehr an `api.anthropic.com`; OpenClaw ordnet das Anthropic-`service_tier` zu (`auto` vs `standard_only`) +- Anthropic-Hinweis: Anthropic-Mitarbeitende haben uns mitgeteilt, dass OpenClaw-artige Claude-CLI-Nutzung wieder erlaubt ist, daher behandelt OpenClaw die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. +- Anthropic-Setup-Token bleibt als unterstützter OpenClaw-Tokenpfad verfügbar, aber OpenClaw bevorzugt jetzt die Wiederverwendung der Claude CLI und `claude -p`, wenn verfügbar. ```json5 { @@ -172,16 +300,18 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### OpenAI Code (Codex) - Anbieter: `openai-codex` -- Auth: OAuth (ChatGPT) +- Authentifizierung: OAuth (ChatGPT) - Beispielmodell: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` oder `openclaw models auth login --provider openai-codex` -- Standardtransport ist `auto` (WebSocket zuerst, SSE als Fallback) -- Pro Modell überschreiben über `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) -- `params.serviceTier` wird ebenfalls bei nativen Codex-Responses-Anfragen weitergereicht (`chatgpt.com/backend-api`) -- Versteckte OpenClaw-Attributions-Header (`originator`, `version`, `User-Agent`) werden nur an nativen Codex-Datenverkehr zu `chatgpt.com/backend-api` angehängt, nicht an generische OpenAI-kompatible Proxys -- Teilt sich denselben Schalter `/fast` und dieselbe Konfiguration `params.fastMode` wie direktes `openai/*`; OpenClaw ordnet dies `service_tier=priority` zu -- `openai-codex/gpt-5.3-codex-spark` bleibt verfügbar, wenn der Codex-OAuth-Katalog es bereitstellt; abhängig von den Berechtigungen -- `openai-codex/gpt-5.4` behält natives `contextWindow = 1050000` und standardmäßig Laufzeit-`contextTokens = 272000`; überschreiben Sie die Laufzeitgrenze mit `models.providers.openai-codex.models[].contextTokens` +- Der Standardtransport ist `auto` (zuerst WebSocket, SSE als Fallback) +- Überschreiben Sie pro Modell über `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` oder `"auto"`) +- `params.serviceTier` wird ebenfalls bei nativen Codex-Responses-Anfragen weitergeleitet (`chatgpt.com/backend-api`) +- Versteckte OpenClaw-Attributions-Header (`originator`, `version`, + `User-Agent`) werden nur an nativen Codex-Datenverkehr zu + `chatgpt.com/backend-api` angehängt, nicht an generische OpenAI-kompatible Proxys +- Nutzt denselben `/fast`-Schalter und dieselbe Konfiguration `params.fastMode` wie direkte `openai/*`; OpenClaw ordnet dies `service_tier=priority` zu +- `openai-codex/gpt-5.3-codex-spark` bleibt verfügbar, wenn der Codex-OAuth-Katalog es bereitstellt; abhängig von Berechtigungen +- `openai-codex/gpt-5.4` behält natives `contextWindow = 1050000` und eine Standard-Laufzeitobergrenze von `contextTokens = 272000`; überschreiben Sie die Laufzeitobergrenze mit `models.providers.openai-codex.models[].contextTokens` - Richtlinienhinweis: OpenAI-Codex-OAuth wird ausdrücklich für externe Tools/Workflows wie OpenClaw unterstützt. ```json5 @@ -204,13 +334,13 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### Andere gehostete Optionen im Abonnementstil -- [Qwen Cloud](/de/providers/qwen): Qwen-Cloud-Anbieteroberfläche sowie Endpoint-Zuordnung für Alibaba DashScope und Coding Plan -- [MiniMax](/de/providers/minimax): Zugriff per MiniMax-Coding-Plan-OAuth oder API-Schlüssel +- [Qwen Cloud](/de/providers/qwen): Qwen-Cloud-Anbieteroberfläche plus Zuordnung der Alibaba-DashScope- und Coding-Plan-Endpunkte +- [MiniMax](/de/providers/minimax): MiniMax-Coding-Plan-OAuth- oder API-Schlüsselzugriff - [GLM Models](/de/providers/glm): Z.AI Coding Plan oder allgemeine API-Endpunkte ### OpenCode -- Auth: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`) +- Authentifizierung: `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`) - Zen-Laufzeitanbieter: `opencode` - Go-Laufzeitanbieter: `opencode-go` - Beispielmodelle: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` @@ -225,18 +355,20 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### Google Gemini (API-Schlüssel) - Anbieter: `google` -- Auth: `GEMINI_API_KEY` -- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, Fallback `GOOGLE_API_KEY` und `OPENCLAW_LIVE_GEMINI_KEY` (einzelner Override) +- Authentifizierung: `GEMINI_API_KEY` +- Optionale Rotation: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, Fallback auf `GOOGLE_API_KEY` und `OPENCLAW_LIVE_GEMINI_KEY` (einzelne Überschreibung) - Beispielmodelle: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Kompatibilität: Legacy-OpenClaw-Konfiguration mit `google/gemini-3.1-flash-preview` wird zu `google/gemini-3-flash-preview` normalisiert - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Direkte Gemini-Läufe akzeptieren außerdem `agents.defaults.models["google/"].params.cachedContent` (oder das Legacy-`cached_content`), um einen anbieter-nativen Handle `cachedContents/...` weiterzureichen; Gemini-Cache-Treffer erscheinen als OpenClaw-`cacheRead` +- Direkte Gemini-Ausführungen akzeptieren außerdem `agents.defaults.models["google/"].params.cachedContent` + (oder das Legacy-`cached_content`), um ein anbieternatives + Handle `cachedContents/...` weiterzuleiten; Gemini-Cache-Treffer erscheinen als OpenClaw-`cacheRead` ### Google Vertex und Gemini CLI - Anbieter: `google-vertex`, `google-gemini-cli` -- Auth: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Ablauf -- Vorsicht: Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Nutzer haben von Einschränkungen ihres Google-Kontos nach der Verwendung von Drittanbieter-Clients berichtet. Prüfen Sie die Google-Nutzungsbedingungen und verwenden Sie ein unkritisches Konto, wenn Sie sich dafür entscheiden. +- Authentifizierung: Vertex verwendet gcloud ADC; Gemini CLI verwendet seinen OAuth-Ablauf +- Vorsicht: Gemini-CLI-OAuth in OpenClaw ist eine inoffizielle Integration. Einige Nutzer haben nach der Verwendung von Drittanbieter-Clients Einschränkungen bei Google-Konten gemeldet. Prüfen Sie die Google-Bedingungen und verwenden Sie ein unkritisches Konto, wenn Sie fortfahren möchten. - Gemini-CLI-OAuth wird als Teil des gebündelten `google`-Plugins ausgeliefert. - Installieren Sie zuerst Gemini CLI: - `brew install gemini-cli` @@ -244,14 +376,16 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k - Aktivieren: `openclaw plugins enable google` - Anmelden: `openclaw models auth login --provider google-gemini-cli --set-default` - Standardmodell: `google-gemini-cli/gemini-3-flash-preview` - - Hinweis: Sie fügen **keine** Client-ID und kein Secret in `openclaw.json` ein. Der CLI-Login-Ablauf speichert Token in Auth-Profilen auf dem Gateway-Host. - - Wenn Anfragen nach dem Login fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder `GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host. - - JSON-Antworten von Gemini CLI werden aus `response` geparst; die Nutzung greift auf `stats` zurück, wobei `stats.cached` in OpenClaw-`cacheRead` normalisiert wird. + - Hinweis: Sie fügen **keine** Client-ID und kein Secret in `openclaw.json` ein. Der CLI-Anmeldeablauf speichert + Token in Authentifizierungsprofilen auf dem Gateway-Host. + - Wenn Anfragen nach der Anmeldung fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder `GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host. + - Gemini-CLI-JSON-Antworten werden aus `response` geparst; die Nutzung greift auf + `stats` zurück, wobei `stats.cached` in OpenClaw-`cacheRead` normalisiert wird. ### Z.AI (GLM) - Anbieter: `zai` -- Auth: `ZAI_API_KEY` +- Authentifizierung: `ZAI_API_KEY` - Beispielmodell: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Aliasse: `z.ai/*` und `z-ai/*` werden zu `zai/*` normalisiert @@ -260,19 +394,22 @@ OpenClaw wird mit dem pi‑ai-Katalog ausgeliefert. Diese Anbieter erfordern **k ### Vercel AI Gateway - Anbieter: `vercel-ai-gateway` -- Auth: `AI_GATEWAY_API_KEY` +- Authentifizierung: `AI_GATEWAY_API_KEY` - Beispielmodell: `vercel-ai-gateway/anthropic/claude-opus-4.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway - Anbieter: `kilocode` -- Auth: `KILOCODE_API_KEY` +- Authentifizierung: `KILOCODE_API_KEY` - Beispielmodell: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - Basis-URL: `https://api.kilo.ai/api/gateway/` -- Der statische Fallback-Katalog enthält `kilocode/kilo/auto`; die Live-Erkennung über `https://api.kilo.ai/api/gateway/models` kann den Laufzeitkatalog weiter erweitern. -- Das genaue Upstream-Routing hinter `kilocode/kilo/auto` wird von Kilo Gateway verwaltet und ist nicht fest in OpenClaw codiert. +- Der statische Fallback-Katalog liefert `kilocode/kilo/auto`; die Live- + Erkennung unter `https://api.kilo.ai/api/gateway/models` kann den Laufzeit- + Katalog weiter erweitern. +- Das genaue Upstream-Routing hinter `kilocode/kilo/auto` gehört zu Kilo Gateway + und ist nicht in OpenClaw fest kodiert. Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails. @@ -280,17 +417,26 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails. - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Beispielmodell: `openrouter/auto` -- OpenClaw wendet die dokumentierten App-Attributions-Header von OpenRouter nur an, wenn die Anfrage tatsächlich an `openrouter.ai` geht -- OpenRouter-spezifische Anthropic-`cache_control`-Marker sind ebenfalls auf verifizierte OpenRouter-Routen beschränkt, nicht auf beliebige Proxy-URLs -- OpenRouter bleibt auf dem proxyartigen OpenAI-kompatiblen Pfad, daher werden natives, nur für OpenAI geltendes Anfrage-Shaping (`serviceTier`, Responses-`store`, Prompt-Cache-Hinweise, OpenAI-Reasoning-kompatible Payloads) nicht weitergereicht -- Gemini-gestützte OpenRouter-Referenzen behalten nur die Bereinigung von Proxy-Gemini-Thought-Signaturen; native Gemini-Replay-Validierung und Bootstrap-Umschreibungen bleiben deaktiviert +- OpenClaw wendet die dokumentierten App-Attributions-Header von OpenRouter nur an, wenn + die Anfrage tatsächlich an `openrouter.ai` geht +- OpenRouter-spezifische Anthropic-`cache_control`-Marker sind ebenso auf + verifizierte OpenRouter-Routen beschränkt, nicht auf beliebige Proxy-URLs +- OpenRouter bleibt auf dem Proxy-artigen OpenAI-kompatiblen Pfad, daher wird die native, + nur für OpenAI geltende Anfrageformung (`serviceTier`, Responses-`store`, + Prompt-Cache-Hinweise, OpenAI-Reasoning-kompatible Payloads) nicht weitergeleitet +- Auf Gemini basierende OpenRouter-Referenzen behalten nur die Bereinigung von Proxy-Gemini-Thought-Signaturen + bei; native Gemini-Replay-Validierung und Bootstrap-Umschreibungen bleiben deaktiviert - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Beispielmodell: `kilocode/kilo/auto` -- Gemini-gestützte Kilo-Referenzen behalten denselben Bereinigungspfad für Proxy-Gemini-Thought-Signaturen; `kilocode/kilo/auto` und andere Hinweise ohne Unterstützung für Proxy-Reasoning überspringen die Proxy-Reasoning-Injektion +- Auf Gemini basierende Kilo-Referenzen behalten denselben Pfad zur Bereinigung von Proxy-Gemini-Thought-Signaturen; + `kilocode/kilo/auto` und andere Hinweise ohne Unterstützung für Proxy-Reasoning + überspringen die Injektion von Proxy-Reasoning - MiniMax: `minimax` (API-Schlüssel) und `minimax-portal` (OAuth) -- Auth: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal` +- Authentifizierung: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal` - Beispielmodell: `minimax/MiniMax-M2.7` oder `minimax-portal/MiniMax-M2.7` -- MiniMax-Onboarding/API-Key-Setup schreibt explizite M2.7-Modell-Definitionen mit `input: ["text", "image"]`; der gebündelte Anbieterkatalog hält die Chat-Referenzen nur für Text, bis diese Anbieter-Konfiguration materialisiert ist +- MiniMax-Onboarding/API-Schlüssel-Einrichtung schreibt explizite M2.7-Modelldefinitionen mit + `input: ["text", "image"]`; der gebündelte Anbieter-Katalog belässt die Chat-Referenzen + als nur Text, bis diese Anbieterkonfiguration materialisiert wird - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Beispielmodell: `moonshot/kimi-k2.6` - Kimi Coding: `kimi` (`KIMI_API_KEY` oder `KIMICODE_API_KEY`) @@ -317,8 +463,11 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails. - Beispielmodell: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - Native gebündelte xAI-Anfragen verwenden den xAI-Responses-Pfad - - `/fast` oder `params.fastMode: true` schreiben `grok-3`, `grok-3-mini`, `grok-4` und `grok-4-0709` auf ihre `*-fast`-Varianten um - - `tool_stream` ist standardmäßig aktiviert; setzen Sie `agents.defaults.models["xai/"].params.tool_stream` auf `false`, um es zu deaktivieren + - `/fast` oder `params.fastMode: true` schreiben `grok-3`, `grok-3-mini`, + `grok-4` und `grok-4-0709` auf ihre `*-fast`-Varianten um + - `tool_stream` ist standardmäßig aktiviert; setzen Sie + `agents.defaults.models["xai/"].params.tool_stream` auf `false`, um + dies zu deaktivieren - Mistral: `mistral` (`MISTRAL_API_KEY`) - Beispielmodell: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` @@ -331,16 +480,21 @@ Siehe [/providers/kilocode](/de/providers/kilocode) für Einrichtungsdetails. ## Anbieter über `models.providers` (benutzerdefiniert/Basis-URL) -Verwenden Sie `models.providers` (oder `models.json`), um **benutzerdefinierte** Anbieter oder OpenAI-/Anthropic-kompatible Proxys hinzuzufügen. +Verwenden Sie `models.providers` (oder `models.json`), um **benutzerdefinierte** Anbieter oder +OpenAI-/Anthropic-kompatible Proxys hinzuzufügen. -Viele der unten aufgeführten gebündelten Anbieter-Plugins veröffentlichen bereits einen Standardkatalog. Verwenden Sie explizite Einträge `models.providers.` nur dann, wenn Sie die Standard-Basis-URL, Header oder Modellliste überschreiben möchten. +Viele der unten aufgeführten gebündelten Anbieter-Plugins veröffentlichen bereits einen Standardkatalog. +Verwenden Sie explizite Einträge in `models.providers.` nur dann, wenn Sie die +Standard-Basis-URL, Header oder Modellliste überschreiben möchten. ### Moonshot AI (Kimi) -Moonshot wird als gebündeltes Anbieter-Plugin ausgeliefert. Verwenden Sie standardmäßig den eingebauten Anbieter und fügen Sie nur dann einen expliziten Eintrag `models.providers.moonshot` hinzu, wenn Sie die Basis-URL oder Modellmetadaten überschreiben müssen: +Moonshot wird als gebündeltes Anbieter-Plugin ausgeliefert. Verwenden Sie standardmäßig den integrierten Anbieter +und fügen Sie nur dann einen expliziten Eintrag `models.providers.moonshot` hinzu, wenn Sie die Basis-URL oder Modellmetadaten +überschreiben müssen: - Anbieter: `moonshot` -- Auth: `MOONSHOT_API_KEY` +- Authentifizierung: `MOONSHOT_API_KEY` - Beispielmodell: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` oder `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -380,7 +534,7 @@ Kimi-K2-Modell-IDs: Kimi Coding verwendet den Anthropic-kompatiblen Endpunkt von Moonshot AI: - Anbieter: `kimi` -- Auth: `KIMI_API_KEY` +- Authentifizierung: `KIMI_API_KEY` - Beispielmodell: `kimi/kimi-code` ```json5 @@ -392,14 +546,14 @@ Kimi Coding verwendet den Anthropic-kompatiblen Endpunkt von Moonshot AI: } ``` -Legacy-`kimi/k2p5` wird weiterhin als kompatible Modell-ID akzeptiert. +Legacy-`kimi/k2p5` bleibt als Kompatibilitäts-Modell-ID akzeptiert. ### Volcano Engine (Doubao) -Volcano Engine (火山引擎) bietet in China Zugriff auf Doubao und andere Modelle. +Volcano Engine (火山引擎) bietet Zugriff auf Doubao und andere Modelle in China. - Anbieter: `volcengine` (Coding: `volcengine-plan`) -- Auth: `VOLCANO_ENGINE_API_KEY` +- Authentifizierung: `VOLCANO_ENGINE_API_KEY` - Beispielmodell: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -411,9 +565,13 @@ Volcano Engine (火山引擎) bietet in China Zugriff auf Doubao und andere Mode } ``` -Beim Onboarding wird standardmäßig die Coding-Oberfläche verwendet, aber der allgemeine Katalog `volcengine/*` wird gleichzeitig registriert. +Standardmäßig verwendet Onboarding die Coding-Oberfläche, aber der allgemeine Katalog `volcengine/*` +wird gleichzeitig registriert. -In Onboarding-/Konfigurations-Modell-Pickern bevorzugt die Volcengine-Auth-Auswahl sowohl Zeilen `volcengine/*` als auch `volcengine-plan/*`. Wenn diese Modelle noch nicht geladen sind, greift OpenClaw auf den ungefilterten Katalog zurück, anstatt einen leeren anbieterbezogenen Picker anzuzeigen. +In den Modell-Auswahlen für Onboarding/Konfiguration bevorzugt die Volcengine-Authentifizierungsoption sowohl +Zeilen `volcengine/*` als auch `volcengine-plan/*`. Wenn diese Modelle noch nicht geladen sind, +fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere +anbieterspezifische Auswahl anzuzeigen. Verfügbare Modelle: @@ -431,12 +589,12 @@ Coding-Modelle (`volcengine-plan`): - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (international) +### BytePlus (International) BytePlus ARK bietet internationalen Nutzern Zugriff auf dieselben Modelle wie Volcano Engine. - Anbieter: `byteplus` (Coding: `byteplus-plan`) -- Auth: `BYTEPLUS_API_KEY` +- Authentifizierung: `BYTEPLUS_API_KEY` - Beispielmodell: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -448,9 +606,13 @@ BytePlus ARK bietet internationalen Nutzern Zugriff auf dieselben Modelle wie Vo } ``` -Beim Onboarding wird standardmäßig die Coding-Oberfläche verwendet, aber der allgemeine Katalog `byteplus/*` wird gleichzeitig registriert. +Standardmäßig verwendet Onboarding die Coding-Oberfläche, aber der allgemeine Katalog `byteplus/*` +wird gleichzeitig registriert. -In Onboarding-/Konfigurations-Modell-Pickern bevorzugt die BytePlus-Auth-Auswahl sowohl Zeilen `byteplus/*` als auch `byteplus-plan/*`. Wenn diese Modelle noch nicht geladen sind, greift OpenClaw auf den ungefilterten Katalog zurück, anstatt einen leeren anbieterbezogenen Picker anzuzeigen. +In den Modell-Auswahlen für Onboarding/Konfiguration bevorzugt die BytePlus-Authentifizierungsoption sowohl +Zeilen `byteplus/*` als auch `byteplus-plan/*`. Wenn diese Modelle noch nicht geladen sind, +fällt OpenClaw auf den ungefilterten Katalog zurück, statt eine leere +anbieterspezifische Auswahl anzuzeigen. Verfügbare Modelle: @@ -471,7 +633,7 @@ Coding-Modelle (`byteplus-plan`): Synthetic stellt Anthropic-kompatible Modelle hinter dem Anbieter `synthetic` bereit: - Anbieter: `synthetic` -- Auth: `SYNTHETIC_API_KEY` +- Authentifizierung: `SYNTHETIC_API_KEY` - Beispielmodell: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` @@ -502,28 +664,31 @@ MiniMax wird über `models.providers` konfiguriert, weil es benutzerdefinierte E - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` - MiniMax API-Schlüssel (Global): `--auth-choice minimax-global-api` - MiniMax API-Schlüssel (CN): `--auth-choice minimax-cn-api` -- Auth: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder `MINIMAX_API_KEY` für `minimax-portal` +- Authentifizierung: `MINIMAX_API_KEY` für `minimax`; `MINIMAX_OAUTH_TOKEN` oder + `MINIMAX_API_KEY` für `minimax-portal` Siehe [/providers/minimax](/de/providers/minimax) für Einrichtungsdetails, Modelloptionen und Konfigurationsbeispiele. -Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw standardmäßig Thinking, sofern Sie es nicht explizit setzen, und `/fast on` schreibt `MiniMax-M2.7` auf `MiniMax-M2.7-highspeed` um. +Auf dem Anthropic-kompatiblen Streaming-Pfad von MiniMax deaktiviert OpenClaw Thinking +standardmäßig, sofern Sie es nicht explizit setzen, und `/fast on` schreibt +`MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um. -Plugin-eigene Aufteilung der Fähigkeiten: +Plugin-eigene Fähigkeitsaufteilung: -- Standardwerte für Text/Chat bleiben auf `minimax/MiniMax-M2.7` +- Standards für Text/Chat bleiben auf `minimax/MiniMax-M2.7` - Bildgenerierung ist `minimax/image-01` oder `minimax-portal/image-01` -- Bildverständnis ist das Plugin-eigene `MiniMax-VL-01` auf beiden MiniMax-Auth-Pfaden -- Die Websuche bleibt auf der Anbieter-ID `minimax` +- Bildverständnis ist plugin-eigenes `MiniMax-VL-01` auf beiden MiniMax-Authentifizierungspfaden +- Websuche bleibt auf Anbieter-ID `minimax` ### LM Studio LM Studio wird als gebündeltes Anbieter-Plugin ausgeliefert, das die native API verwendet: - Anbieter: `lmstudio` -- Auth: `LM_API_TOKEN` +- Authentifizierung: `LM_API_TOKEN` - Standard-Basis-URL für Inferenz: `http://localhost:1234/v1` -Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `http://localhost:1234/api/v1/models` zurückgegeben werden): +Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `http://localhost:1234/api/v1/models` zurückgegeben werden): ```json5 { @@ -533,7 +698,8 @@ Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `http:// } ``` -OpenClaw verwendet die nativen Endpunkte `/api/v1/models` und `/api/v1/models/load` von LM Studio für Erkennung + automatisches Laden und standardmäßig `/v1/chat/completions` für die Inferenz. +OpenClaw verwendet die nativen Endpunkte `/api/v1/models` und `/api/v1/models/load` von LM Studio +für Erkennung + automatisches Laden und standardmäßig `/v1/chat/completions` für Inferenz. Siehe [/providers/lmstudio](/de/providers/lmstudio) für Einrichtung und Fehlerbehebung. ### Ollama @@ -541,12 +707,12 @@ Siehe [/providers/lmstudio](/de/providers/lmstudio) für Einrichtung und Fehlerb Ollama wird als gebündeltes Anbieter-Plugin ausgeliefert und verwendet die native API von Ollama: - Anbieter: `ollama` -- Auth: Nicht erforderlich (lokaler Server) +- Authentifizierung: Keine erforderlich (lokaler Server) - Beispielmodell: `ollama/llama3.3` - Installation: [https://ollama.com/download](https://ollama.com/download) ```bash -# Ollama installieren, dann ein Modell laden: +# Installieren Sie Ollama und laden Sie dann ein Modell: ollama pull llama3.3 ``` @@ -558,23 +724,27 @@ ollama pull llama3.3 } ``` -Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie sich mit `OLLAMA_API_KEY` dafür entscheiden, und das gebündelte Anbieter-Plugin fügt Ollama direkt zu `openclaw onboard` und dem Modell-Picker hinzu. Siehe [/providers/ollama](/de/providers/ollama) für Onboarding, Cloud-/lokalen Modus und benutzerdefinierte Konfiguration. +Ollama wird lokal unter `http://127.0.0.1:11434` erkannt, wenn Sie mit +`OLLAMA_API_KEY` zustimmen, und das gebündelte Anbieter-Plugin fügt Ollama direkt zu +`openclaw onboard` und der Modellauswahl hinzu. Siehe [/providers/ollama](/de/providers/ollama) +für Onboarding, Cloud-/Lokalmodus und benutzerdefinierte Konfiguration. ### vLLM -vLLM wird als gebündeltes Anbieter-Plugin für lokale/self-hosted OpenAI-kompatible Server ausgeliefert: +vLLM wird als gebündeltes Anbieter-Plugin für lokale/selbstgehostete OpenAI-kompatible +Server ausgeliefert: - Anbieter: `vllm` -- Auth: Optional (abhängig von Ihrem Server) +- Authentifizierung: Optional (abhängig von Ihrem Server) - Standard-Basis-URL: `http://127.0.0.1:8000/v1` -Um sich lokal für die automatische Erkennung zu entscheiden (jeder Wert funktioniert, wenn Ihr Server keine Auth erzwingt): +So stimmen Sie der automatischen lokalen Erkennung zu (jeder Wert funktioniert, wenn Ihr Server keine Authentifizierung erzwingt): ```bash export VLLM_API_KEY="vllm-local" ``` -Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): +Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): ```json5 { @@ -588,19 +758,21 @@ Siehe [/providers/vllm](/de/providers/vllm) für Details. ### SGLang -SGLang wird als gebündeltes Anbieter-Plugin für schnelle self-hosted OpenAI-kompatible Server ausgeliefert: +SGLang wird als gebündeltes Anbieter-Plugin für schnelle selbstgehostete +OpenAI-kompatible Server ausgeliefert: - Anbieter: `sglang` -- Auth: Optional (abhängig von Ihrem Server) +- Authentifizierung: Optional (abhängig von Ihrem Server) - Standard-Basis-URL: `http://127.0.0.1:30000/v1` -Um sich lokal für die automatische Erkennung zu entscheiden (jeder Wert funktioniert, wenn Ihr Server keine Auth erzwingt): +So stimmen Sie der automatischen lokalen Erkennung zu (jeder Wert funktioniert, wenn Ihr Server keine +Authentifizierung erzwingt): ```bash export SGLANG_API_KEY="sglang-local" ``` -Setzen Sie dann ein Modell (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): +Legen Sie dann ein Modell fest (ersetzen Sie es durch eine der IDs, die von `/v1/models` zurückgegeben werden): ```json5 { @@ -657,10 +829,13 @@ Hinweise: - `contextWindow: 200000` - `maxTokens: 8192` - Empfohlen: Setzen Sie explizite Werte, die zu Ihren Proxy-/Modellgrenzen passen. -- Für `api: "openai-completions"` auf nicht-nativen Endpunkten (jede nicht leere `baseUrl`, deren Host nicht `api.openai.com` ist) erzwingt OpenClaw `compat.supportsDeveloperRole: false`, um 400-Fehler des Anbieters bei nicht unterstützten `developer`-Rollen zu vermeiden. -- Proxy-artige OpenAI-kompatible Routen überspringen außerdem natives, nur für OpenAI geltendes Anfrage-Shaping: kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise, kein OpenAI-Reasoning-kompatibles Payload-Shaping und keine versteckten OpenClaw-Attributions-Header. -- Wenn `baseUrl` leer ist oder weggelassen wird, behält OpenClaw das Standardverhalten von OpenAI bei (das zu `api.openai.com` aufgelöst wird). -- Aus Sicherheitsgründen wird ein explizites `compat.supportsDeveloperRole: true` auf nicht-nativen Endpunkten `openai-completions` weiterhin überschrieben. +- Für `api: "openai-completions"` auf nicht-nativen Endpunkten (jede nicht leere `baseUrl`, deren Host nicht `api.openai.com` ist), erzwingt OpenClaw `compat.supportsDeveloperRole: false`, um 400-Fehler des Anbieters bei nicht unterstützten `developer`-Rollen zu vermeiden. +- Proxy-artige OpenAI-kompatible Routen überspringen auch die native, nur für OpenAI geltende Anfrageformung: + kein `service_tier`, kein Responses-`store`, keine Prompt-Cache-Hinweise, keine + OpenAI-Reasoning-kompatible Payload-Formung und keine versteckten OpenClaw-Attributions- + Header. +- Wenn `baseUrl` leer ist oder ausgelassen wird, behält OpenClaw das Standardverhalten von OpenAI bei (das zu `api.openai.com` aufgelöst wird). +- Zur Sicherheit wird ein explizites `compat.supportsDeveloperRole: true` auf nicht-nativen `openai-completions`-Endpunkten weiterhin überschrieben. ## CLI-Beispiele @@ -676,5 +851,5 @@ Siehe auch: [/gateway/configuration](/de/gateway/configuration) für vollständi - [Models](/de/concepts/models) — Modellkonfiguration und Aliasse - [Model Failover](/de/concepts/model-failover) — Fallback-Ketten und Wiederholungsverhalten -- [Konfigurationsreferenz](/de/gateway/configuration-reference#agent-defaults) — Modell-Konfigurationsschlüssel -- [Anbieter](/de/providers) — anbieterbezogene Einrichtungsanleitungen +- [Configuration Reference](/de/gateway/configuration-reference#agent-defaults) — Schlüssel der Modellkonfiguration +- [Providers](/de/providers) — Einrichtungsanleitungen pro Anbieter diff --git a/docs/de/gateway/troubleshooting.md b/docs/de/gateway/troubleshooting.md index 22e77b47b..08138e67d 100644 --- a/docs/de/gateway/troubleshooting.md +++ b/docs/de/gateway/troubleshooting.md @@ -1,21 +1,21 @@ --- read_when: - - Das Hub für die Fehlerbehebung hat Sie für eine tiefergehende Diagnose hierher verwiesen - - Sie benötigen stabile, symptombasierte Runbook-Abschnitte mit exakten Befehlen -summary: Detailliertes Runbook zur Fehlerbehebung für Gateway, Kanäle, Automatisierung, Nodes und Browser + - Der Hub zur Fehlerbehebung hat Sie für eine tiefergehende Diagnose hierher verwiesen. + - Sie benötigen stabile symptomorientierte Runbook-Abschnitte mit exakten Befehlen. +summary: Tiefer Runbook zur Fehlerbehebung für Gateway, Channels, Automatisierung, Nodes und Browser title: Fehlerbehebung x-i18n: - generated_at: "2026-04-21T06:25:46Z" + generated_at: "2026-04-21T13:35:28Z" model: gpt-5.4 provider: openai - source_hash: 2afb105376bb467e5a344e6d73726908cb718fa13116b751fddb494a0b641c42 + source_hash: add7625785e3b78897c750b4785b7fe84a3d91c23c4175de750c4834272967f9 source_path: gateway/troubleshooting.md workflow: 15 --- # Fehlerbehebung beim Gateway -Diese Seite ist das ausführliche Runbook. +Diese Seite ist das tiefe Runbook. Beginnen Sie bei [/help/troubleshooting](/de/help/troubleshooting), wenn Sie zuerst den schnellen Triage-Ablauf möchten. ## Befehlsleiter @@ -30,11 +30,11 @@ openclaw doctor openclaw channels status --probe ``` -Erwartete Signale für einen gesunden Zustand: +Erwartete Signale bei gesundem Zustand: - `openclaw gateway status` zeigt `Runtime: running`, `Connectivity probe: ok` und eine Zeile `Capability: ...`. - `openclaw doctor` meldet keine blockierenden Konfigurations-/Serviceprobleme. -- `openclaw channels status --probe` zeigt Live-Transportstatus pro Konto und, +- `openclaw channels status --probe` zeigt den Live-Transportstatus pro Konto und, wo unterstützt, Probe-/Audit-Ergebnisse wie `works` oder `audit ok`. ## Anthropic 429: zusätzliche Nutzung für langen Kontext erforderlich @@ -48,17 +48,17 @@ openclaw models status openclaw config get agents.defaults.models ``` -Achten Sie auf: +Achten Sie auf Folgendes: - Das ausgewählte Anthropic-Opus-/Sonnet-Modell hat `params.context1m: true`. -- Die aktuelle Anthropic-Anmeldedaten sind nicht für die Nutzung mit langem Kontext geeignet. -- Anfragen schlagen nur bei langen Sitzungen/Modelläufen fehl, die den 1M-Beta-Pfad benötigen. +- Die aktuelle Anthropic-Anmeldung ist nicht für die Nutzung mit langem Kontext berechtigt. +- Anfragen schlagen nur bei langen Sitzungen/Modellausführungen fehl, die den 1M-Betapfad benötigen. Optionen zur Behebung: 1. Deaktivieren Sie `context1m` für dieses Modell, um auf das normale Kontextfenster zurückzufallen. -2. Verwenden Sie Anthropic-Anmeldedaten, die für Anfragen mit langem Kontext geeignet sind, oder wechseln Sie zu einem Anthropic-API-Schlüssel. -3. Konfigurieren Sie Fallback-Modelle, damit Läufe fortgesetzt werden, wenn Anthropic-Anfragen mit langem Kontext abgelehnt werden. +2. Verwenden Sie eine Anthropic-Anmeldung, die für Langkontext-Anfragen berechtigt ist, oder wechseln Sie zu einem Anthropic-API-Schlüssel. +3. Konfigurieren Sie Fallback-Modelle, damit Ausführungen weiterlaufen, wenn Anthropic-Langkontext-Anfragen abgelehnt werden. Verwandt: @@ -66,13 +66,13 @@ Verwandt: - [/reference/token-use](/de/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/de/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Läufe schlagen fehl +## Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Ausführungen schlagen fehl Verwenden Sie dies, wenn: - `curl ... /v1/models` funktioniert -- kleine direkte `/v1/chat/completions`-Aufrufe funktionieren -- OpenClaw-Modelläufe nur bei normalen Agent-Turns fehlschlagen +- winzige direkte `/v1/chat/completions`-Aufrufe funktionieren +- OpenClaw-Modellausführungen nur bei normalen Agent-Zügen fehlschlagen ```bash curl http://127.0.0.1:1234/v1/models @@ -83,35 +83,33 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -Achten Sie auf: +Achten Sie auf Folgendes: -- direkte kleine Aufrufe sind erfolgreich, aber OpenClaw-Läufe schlagen nur bei größeren Prompts fehl -- Backend-Fehler darüber, dass `messages[].content` einen String erwartet -- Backend-Abstürze, die nur bei höherer Prompt-Token-Zahl oder vollständigen Agent- - Laufzeit-Prompts auftreten +- direkte winzige Aufrufe sind erfolgreich, aber OpenClaw-Ausführungen schlagen nur bei größeren Prompts fehl +- Backend-Fehler dazu, dass `messages[].content` einen String erwartet +- Backend-Abstürze, die nur bei größeren Prompt-Token-Anzahlen oder vollständigen Agent-Laufzeit-Prompts auftreten Häufige Signaturen: -- `messages[...].content: invalid type: sequence, expected a string` → Backend - lehnt strukturierte Chat-Completions-Content-Teile ab. Behebung: setzen Sie +- `messages[...].content: invalid type: sequence, expected a string` → Das Backend + lehnt strukturierte Chat-Completions-Content-Teile ab. Behebung: Setzen Sie `models.providers..models[].compat.requiresStringContent: true`. -- direkte kleine Anfragen sind erfolgreich, aber OpenClaw-Agent-Turns schlagen mit Backend-/Modell- - Abstürzen fehl (zum Beispiel Gemma auf einigen `inferrs`-Builds) → OpenClaw-Transport ist - wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Form des Agent- - Laufzeit-Prompts. -- Fehler gehen nach dem Deaktivieren von Tools zurück, verschwinden aber nicht → Tool-Schemas waren - Teil des Drucks, aber das verbleibende Problem liegt weiterhin in der vorgelagerten Modell-/Server- - Kapazität oder einem Backend-Fehler. +- direkte winzige Anfragen sind erfolgreich, aber OpenClaw-Agent-Ausführungen schlagen mit Backend-/Modell-Abstürzen fehl + (zum Beispiel Gemma auf einigen `inferrs`-Builds) → OpenClaw-Transport ist + wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Prompt-Form der Agent-Laufzeit. +- Fehler werden geringer, nachdem Tools deaktiviert wurden, verschwinden aber nicht → + Tool-Schemas waren Teil des Drucks, aber das verbleibende Problem ist weiterhin + eine Upstream-Modell-/Server-Kapazitätsgrenze oder ein Backend-Fehler. Optionen zur Behebung: 1. Setzen Sie `compat.requiresStringContent: true` für Chat-Completions-Backends, die nur Strings unterstützen. 2. Setzen Sie `compat.supportsTools: false` für Modelle/Backends, die die Tool-Schema-Oberfläche von OpenClaw nicht zuverlässig verarbeiten können. -3. Verringern Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzerer +3. Reduzieren Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzerer Sitzungsverlauf, leichteres lokales Modell oder ein Backend mit stärkerer Unterstützung für langen Kontext. -4. Wenn direkte kleine Anfragen weiterhin erfolgreich sind, während OpenClaw-Agent-Turns im Backend noch immer abstürzen, - behandeln Sie dies als vorgelagerte Server-/Modellbeschränkung und melden Sie dort +4. Wenn direkte winzige Anfragen weiterhin erfolgreich sind, während OpenClaw-Agent-Züge im Backend weiter abstürzen, + behandeln Sie dies als Upstream-Server-/Modell-Einschränkung und melden Sie dort eine Reproduktion mit der akzeptierten Payload-Form. Verwandt: @@ -122,7 +120,7 @@ Verwandt: ## Keine Antworten -Wenn Kanäle aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinie, bevor Sie irgendetwas neu verbinden. +Wenn Channels aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinien, bevor Sie irgendetwas erneut verbinden. ```bash openclaw status @@ -132,17 +130,17 @@ openclaw config get channels openclaw logs --follow ``` -Achten Sie auf: +Achten Sie auf Folgendes: - Pairing ausstehend für DM-Absender. - Erwähnungs-Gating in Gruppen (`requireMention`, `mentionPatterns`). -- Nicht passende Kanal-/Gruppen-Allowlist-Konfigurationen. +- Nicht übereinstimmende Channel-/Gruppen-Allowlists. Häufige Signaturen: - `drop guild message (mention required` → Gruppennachricht wird ignoriert, bis eine Erwähnung erfolgt. -- `pairing request` → Absender benötigt Genehmigung. -- `blocked` / `allowlist` → Absender/Kanal wurde durch Richtlinie gefiltert. +- `pairing request` → Absender benötigt eine Freigabe. +- `blocked` / `allowlist` → Absender/Channel wurde durch Richtlinien gefiltert. Verwandt: @@ -162,52 +160,51 @@ openclaw doctor openclaw gateway status --json ``` -Achten Sie auf: +Achten Sie auf Folgendes: -- korrekte Probe-URL und Dashboard-URL. -- Authentifizierungsmodus-/Token-Fehlanpassung zwischen Client und Gateway. -- HTTP-Nutzung, wenn Geräteidentität erforderlich ist. +- korrekte Probe-URL und Dashboard-URL +- Nichtübereinstimmung von Authentifizierungsmodus/Token zwischen Client und Gateway +- HTTP-Nutzung, wo Geräteidentität erforderlich ist Häufige Signaturen: - `device identity required` → unsicherer Kontext oder fehlende Geräteauthentifizierung. - `origin not allowed` → Browser-`Origin` ist nicht in `gateway.controlUi.allowedOrigins` - (oder Sie verbinden sich von einem Nicht-Loopback-Browser-Origin ohne explizite + (oder Sie verbinden sich von einer Browser-`Origin` außerhalb von Loopback ohne eine explizite Allowlist). -- `device nonce required` / `device nonce mismatch` → Client führt den - challenge-basierten Geräteauthentifizierungsablauf nicht vollständig aus (`connect.challenge` + `device.nonce`). +- `device nonce required` / `device nonce mismatch` → Client schließt den + challengebasierten Geräteauthentifizierungsablauf nicht ab (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → Client hat die falsche Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert. - `AUTH_TOKEN_MISMATCH` mit `canRetryWithDeviceToken=true` → Client kann einen vertrauenswürdigen Wiederholungsversuch mit zwischengespeichertem Gerätetoken durchführen. -- Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet den zwischengespeicherten Scope-Satz erneut, der mit dem gekoppelten - Gerätetoken gespeichert wurde. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihren - angeforderten Scope-Satz. -- Außerhalb dieses Wiederholungswegs ist die Priorität der Verbindungsauthentifizierung: - zuerst explizites gemeinsames Token/Passwort, dann explizites - `deviceToken`, dann gespeichertes Gerätetoken, +- Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet die mit dem gekoppelten + Gerätetoken gespeicherte Scope-Menge erneut. Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten stattdessen ihre + angeforderte Scope-Menge bei. +- Außerhalb dieses Wiederholungswegs ist die Priorität der Verbindungsauthentifizierung zuerst explizites gemeinsames + Token/Passwort, dann explizites `deviceToken`, dann gespeichertes Gerätetoken, dann Bootstrap-Token. -- Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für denselben - `{scope, ip}` serialisiert, bevor der Limiter den Fehler aufzeichnet. Zwei fehlerhafte - gleichzeitige Wiederholungsversuche vom selben Client können daher beim zweiten Versuch - `retry later` anzeigen statt zwei einfacher Fehlanpassungen. +- Im asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dieselbe + `{scope, ip}` serialisiert, bevor der Limiter den Fehler erfasst. Zwei falsche + gleichzeitige Wiederholungsversuche vom selben Client können daher beim zweiten Versuch `retry later` + ausgeben statt zwei einfacher Nichtübereinstimmungen. - `too many failed authentication attempts (retry later)` von einem Browser-Origin- - Loopback-Client → wiederholte Fehlschläge von demselben normalisierten `Origin` werden - vorübergehend gesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket. -- wiederholtes `unauthorized` danach → Drift bei gemeinsamem Token/Gerätetoken; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Gerätetoken bei Bedarf erneut. -- `gateway connect failed:` → falsches Host-/Port-/URL-Ziel. + Loopback-Client → wiederholte Fehlschläge von derselben normalisierten `Origin` werden + vorübergehend gesperrt; eine andere localhost-Origin verwendet einen separaten Bucket. +- wiederholtes `unauthorized` nach diesem Wiederholungsversuch → Abweichung bei gemeinsamem Token/Gerätetoken; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Gerätetoken bei Bedarf erneut. +- `gateway connect failed:` → falscher Host-/Port-/URL-Zielwert. -### Kurzübersicht der Auth-Detailcodes +### Kurzzuordnung der Authentifizierungs-Detailcodes Verwenden Sie `error.details.code` aus der fehlgeschlagenen `connect`-Antwort, um die nächste Aktion auszuwählen: -| Detailcode | Bedeutung | Empfohlene Aktion | -| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Client hat kein erforderliches gemeinsames Token gesendet. | Fügen Sie das Token im Client ein/setzen Sie es und versuchen Sie es erneut. Für Dashboard-Pfade: `openclaw config get gateway.auth.token` und dann in die Control-UI-Einstellungen einfügen. | -| `AUTH_TOKEN_MISMATCH` | Gemeinsames Token stimmte nicht mit dem Gateway-Auth-Token überein. | Wenn `canRetryWithDeviceToken=true`, erlauben Sie einen vertrauenswürdigen Wiederholungsversuch. Wiederholungen mit zwischengespeichertem Token verwenden gespeicherte genehmigte Scopes erneut; Aufrufer mit explizitem `deviceToken` / `scopes` behalten angeforderte Scopes. Wenn es weiterhin fehlschlägt, führen Sie die [Checkliste zur Token-Drift-Behebung](/cli/devices#token-drift-recovery-checklist) aus. | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Zwischengespeichertes gerätespezifisches Token ist veraltet oder widerrufen. | Rotieren/genehmigen Sie das Gerätetoken mit [devices CLI](/cli/devices) erneut und verbinden Sie sich dann erneut. | -| `PAIRING_REQUIRED` | Geräteidentität benötigt Genehmigung. Prüfen Sie `error.details.reason` auf `not-paired`, `scope-upgrade`, `role-upgrade` oder `metadata-upgrade` und verwenden Sie `requestId` / `remediationHint`, falls vorhanden. | Genehmigen Sie die ausstehende Anfrage: `openclaw devices list` und dann `openclaw devices approve `. Scope-/Rollen-Upgrades verwenden denselben Ablauf, nachdem Sie den angeforderten Zugriff geprüft haben. | +| Detailcode | Bedeutung | Empfohlene Aktion | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | Der Client hat kein erforderliches gemeinsames Token gesendet. | Fügen Sie das Token im Client ein bzw. setzen Sie es und versuchen Sie es erneut. Für Dashboard-Pfade: `openclaw config get gateway.auth.token`, dann in die Einstellungen der Control UI einfügen. | +| `AUTH_TOKEN_MISMATCH` | Das gemeinsame Token stimmte nicht mit dem Gateway-Authentifizierungstoken überein. | Wenn `canRetryWithDeviceToken=true`, lassen Sie einen vertrauenswürdigen Wiederholungsversuch zu. Wiederholungen mit zwischengespeichertem Token verwenden erneut die gespeicherten genehmigten Scopes; Aufrufer mit explizitem `deviceToken` / `scopes` behalten die angeforderte Scope-Menge. Falls es weiterhin fehlschlägt, führen Sie die [Checkliste zur Behebung von Token-Abweichungen](/cli/devices#token-drift-recovery-checklist) aus. | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Das zwischengespeicherte gerätespezifische Token ist veraltet oder widerrufen. | Rotieren/genehmigen Sie das Gerätetoken mit der [devices CLI](/cli/devices) erneut und verbinden Sie sich dann erneut. | +| `PAIRING_REQUIRED` | Die Geräteidentität benötigt eine Freigabe. Prüfen Sie `error.details.reason` auf `not-paired`, `scope-upgrade`, `role-upgrade` oder `metadata-upgrade`, und verwenden Sie `requestId` / `remediationHint`, wenn vorhanden. | Genehmigen Sie die ausstehende Anfrage: `openclaw devices list` und dann `openclaw devices approve `. Scope-/Rollen-Upgrades verwenden nach Prüfung des angeforderten Zugriffs denselben Ablauf. | -Prüfung der Migration zu Geräteauthentifizierung v2: +Prüfung der Migration zu Device Auth v2: ```bash openclaw --version @@ -215,7 +212,7 @@ openclaw doctor openclaw gateway status ``` -Wenn Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Client und prüfen Sie, dass er: +Wenn die Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Client und prüfen Sie, dass er: 1. auf `connect.challenge` wartet 2. die an die Challenge gebundene Payload signiert @@ -223,8 +220,8 @@ Wenn Logs Nonce-/Signaturfehler zeigen, aktualisieren Sie den verbindenden Clien Wenn `openclaw devices rotate` / `revoke` / `remove` unerwartet verweigert wird: -- Sitzungen mit Token gekoppelter Geräte können nur **ihr eigenes** - Gerät verwalten, es sei denn, der Aufrufer hat auch `operator.admin` +- Sitzungen mit gekoppeltem Gerätetoken können nur **ihr eigenes** Gerät verwalten, es sei denn, der + Aufrufer hat zusätzlich `operator.admin` - `openclaw devices rotate --scope ...` kann nur Operator-Scopes anfordern, die die Aufrufer-Sitzung bereits besitzt @@ -236,32 +233,32 @@ Verwandt: - [/gateway/remote](/de/gateway/remote) - [/cli/devices](/cli/devices) -## Gateway-Dienst läuft nicht +## Gateway-Service läuft nicht -Verwenden Sie dies, wenn der Dienst installiert ist, der Prozess aber nicht aktiv bleibt. +Verwenden Sie dies, wenn der Service installiert ist, der Prozess aber nicht dauerhaft aktiv bleibt. ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # scannt auch Dienste auf Systemebene +openclaw gateway status --deep # scannt auch Services auf Systemebene ``` -Achten Sie auf: +Achten Sie auf Folgendes: - `Runtime: stopped` mit Hinweisen zum Exit. -- Fehlanpassung der Dienstkonfiguration (`Config (cli)` vs `Config (service)`). +- Nichtübereinstimmung der Service-Konfiguration (`Config (cli)` vs `Config (service)`). - Port-/Listener-Konflikte. -- Zusätzliche launchd-/systemd-/schtasks-Installationen, wenn `--deep` verwendet wird. -- Hinweise zur Bereinigung von `Other gateway-like services detected (best effort)`. +- Zusätzliche launchd-/systemd-/schtasks-Installationen bei Verwendung von `--deep`. +- Hinweise zur Bereinigung bei `Other gateway-like services detected (best effort)`. Häufige Signaturen: -- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → der lokale Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde beschädigt und hat `gateway.mode` verloren. Behebung: Setzen Sie `gateway.mode="local"` in Ihrer Konfiguration, oder führen Sie `openclaw onboard --mode local` / `openclaw setup` erneut aus, um die erwartete Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardpfad für die Konfiguration `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bindung ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder, falls konfiguriert, Trusted Proxy). +- `Gateway start blocked: set gateway.mode=local` oder `existing config is missing gateway.mode` → der lokale Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde überschrieben und hat `gateway.mode` verloren. Behebung: Setzen Sie `gateway.mode="local"` in Ihrer Konfiguration oder führen Sie `openclaw onboard --mode local` / `openclaw setup` erneut aus, um die erwartete Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardpfad für die Konfiguration `~/.openclaw/openclaw.json`. +- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad (Token/Passwort oder, falls konfiguriert, Trusted Proxy). - `another gateway instance is already listening` / `EADDRINUSE` → Portkonflikt. -- `Other gateway-like services detected (best effort)` → veraltete oder parallele launchd-/systemd-/schtasks-Units sind vorhanden. Die meisten Setups sollten ein Gateway pro Maschine verwenden; wenn Sie tatsächlich mehr als eines benötigen, isolieren Sie Ports + Konfiguration/Status/Workspace. Siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → veraltete oder parallele launchd-/systemd-/schtasks-Units sind vorhanden. Die meisten Setups sollten ein Gateway pro Maschine behalten; wenn Sie tatsächlich mehr als eines benötigen, isolieren Sie Ports sowie Konfiguration/Status/Workspace. Siehe [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host). Verwandt: @@ -269,9 +266,9 @@ Verwandt: - [/gateway/configuration](/de/gateway/configuration) - [/gateway/doctor](/de/gateway/doctor) -## Gateway hat die zuletzt als gut bekannte Konfiguration wiederhergestellt +## Gateway hat die zuletzt bekannte funktionierende Konfiguration wiederhergestellt -Verwenden Sie dies, wenn das Gateway startet, die Logs aber sagen, dass `openclaw.json` wiederhergestellt wurde. +Verwenden Sie dies, wenn das Gateway startet, die Logs aber melden, dass `openclaw.json` wiederhergestellt wurde. ```bash openclaw logs --follow @@ -280,20 +277,20 @@ openclaw config validate openclaw doctor ``` -Achten Sie auf: +Achten Sie auf Folgendes: - `Config auto-restored from last-known-good` - `gateway: invalid config was restored from last-known-good backup` - `config reload restored last-known-good config after invalid-config` - Eine mit Zeitstempel versehene Datei `openclaw.json.clobbered.*` neben der aktiven Konfiguration -- Ein Systemereignis des Haupt-Agent, das mit `Config recovery warning` beginnt +- Ein Systemereignis des Haupt-Agenten, das mit `Config recovery warning` beginnt -Was passiert ist: +Was ist passiert: -- Die abgelehnte Konfiguration bestand die Validierung beim Start oder beim Hot Reload nicht. -- OpenClaw hat die abgelehnte Payload als `.clobbered.*` bewahrt. -- Die aktive Konfiguration wurde aus der zuletzt validierten, zuletzt als gut bekannten Kopie wiederhergestellt. -- Der nächste Turn des Haupt-Agent wird gewarnt, die abgelehnte Konfiguration nicht blind neu zu schreiben. +- Die abgelehnte Konfiguration hat die Validierung beim Start oder beim Hot-Reload nicht bestanden. +- OpenClaw hat die abgelehnte Payload als `.clobbered.*` erhalten. +- Die aktive Konfiguration wurde aus der zuletzt validierten, zuletzt bekannten funktionierenden Kopie wiederhergestellt. +- Der nächste Zug des Haupt-Agenten wird davor gewarnt, die abgelehnte Konfiguration blind neu zu schreiben. Untersuchen und reparieren: @@ -307,16 +304,16 @@ openclaw doctor Häufige Signaturen: -- `.clobbered.*` existiert → eine externe direkte Bearbeitung oder ein Startup-Read wurde wiederhergestellt. -- `.rejected.*` existiert → ein von OpenClaw verwalteter Konfigurationsschreibvorgang scheiterte vor dem Commit an Schema- oder Clobber-Prüfungen. -- `Config write rejected:` → der Schreibvorgang versuchte, die erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder eine ungültige Konfiguration zu speichern. +- `.clobbered.*` ist vorhanden → eine externe direkte Bearbeitung oder ein Start-Lesevorgang wurde wiederhergestellt. +- `.rejected.*` ist vorhanden → ein von OpenClaw selbst durchgeführter Konfigurationsschreibvorgang hat vor dem Commit die Schema- oder Überschreibungsprüfungen nicht bestanden. +- `Config write rejected:` → der Schreibvorgang hätte versucht, eine erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder eine ungültige Konfiguration zu persistieren. - `Config last-known-good promotion skipped` → der Kandidat enthielt redigierte Secret-Platzhalter wie `***`. Optionen zur Behebung: 1. Behalten Sie die wiederhergestellte aktive Konfiguration bei, wenn sie korrekt ist. 2. Kopieren Sie nur die beabsichtigten Schlüssel aus `.clobbered.*` oder `.rejected.*` und wenden Sie sie dann mit `openclaw config set` oder `config.patch` an. -3. Führen Sie `openclaw config validate` vor dem Neustart aus. +3. Führen Sie vor einem Neustart `openclaw config validate` aus. 4. Wenn Sie von Hand bearbeiten, behalten Sie die vollständige JSON5-Konfiguration bei, nicht nur das partielle Objekt, das Sie ändern wollten. Verwandt: @@ -336,18 +333,18 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -Achten Sie auf: +Achten Sie auf Folgendes: - `warnings[].code` und `primaryTargetId` in der JSON-Ausgabe. -- Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Refs bezieht. +- Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Referenzen bezieht. Häufige Signaturen: -- `SSH tunnel failed to start; falling back to direct probes.` → das SSH-Setup ist fehlgeschlagen, aber der Befehl hat trotzdem direkte konfigurierte/Loopback-Ziele versucht. -- `multiple reachable gateways detected` → mehr als ein Ziel hat geantwortet. Das bedeutet normalerweise ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener. -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → Verbindung funktionierte, aber Detail-RPC ist durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Anmeldedaten mit `operator.read`. -- `Capability: pairing-pending` oder `gateway closed (1008): pairing required` → das Gateway hat geantwortet, aber dieser Client benötigt noch Pairing/Genehmigung vor normalem Operatorzugriff. -- nicht aufgelöster `gateway.auth.*` / `gateway.remote.*`-SecretRef-Warntext → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar. +- `SSH tunnel failed to start; falling back to direct probes.` → Das SSH-Setup ist fehlgeschlagen, aber der Befehl hat weiterhin direkte konfigurierte/Loopback-Ziele versucht. +- `multiple reachable gateways detected` → mehr als ein Ziel hat geantwortet. Normalerweise bedeutet dies ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → die Verbindung hat funktioniert, aber Detail-RPC ist durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Anmeldedaten mit `operator.read`. +- `Capability: pairing-pending` oder `gateway closed (1008): pairing required` → das Gateway hat geantwortet, aber dieser Client benötigt weiterhin Pairing/Freigabe vor normalem Operator-Zugriff. +- nicht aufgelöster `gateway.auth.*` / `gateway.remote.*`-SecretRef-Warntext → Authentifizierungsmaterial war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar. Verwandt: @@ -355,9 +352,9 @@ Verwandt: - [/gateway#multiple-gateways-same-host](/de/gateway#multiple-gateways-same-host) - [/gateway/remote](/de/gateway/remote) -## Kanal verbunden, aber Nachrichten fließen nicht +## Channel verbunden, aber Nachrichten fließen nicht -Wenn der Kanalstatus „verbunden“ ist, der Nachrichtenfluss aber tot ist, konzentrieren Sie sich auf Richtlinien, Berechtigungen und kanalspezifische Zustellregeln. +Wenn der Channel-Status verbunden ist, aber der Nachrichtenfluss tot ist, konzentrieren Sie sich auf Richtlinien, Berechtigungen und channelspezifische Zustellregeln. ```bash openclaw channels status --probe @@ -367,17 +364,17 @@ openclaw logs --follow openclaw config get channels ``` -Achten Sie auf: +Achten Sie auf Folgendes: - DM-Richtlinie (`pairing`, `allowlist`, `open`, `disabled`). - Gruppen-Allowlist und Erwähnungsanforderungen. -- Fehlende API-Berechtigungen/Scopes des Kanals. +- Fehlende Channel-API-Berechtigungen/Scopes. Häufige Signaturen: -- `mention required` → Nachricht wird durch die Gruppen-Erwähnungsrichtlinie ignoriert. -- `pairing` / Spuren ausstehender Genehmigung → Absender ist nicht genehmigt. -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → Problem mit Kanal-Authentifizierung/-Berechtigungen. +- `mention required` → Nachricht wird durch die Gruppenerwähnungsrichtlinie ignoriert. +- `pairing` / Spuren ausstehender Freigaben → Absender ist nicht freigegeben. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → Problem mit Channel-Authentifizierung/Berechtigungen. Verwandt: @@ -386,9 +383,9 @@ Verwandt: - [/channels/telegram](/de/channels/telegram) - [/channels/discord](/de/channels/discord) -## Zustellung von Cron und Heartbeat +## Cron- und Heartbeat-Zustellung -Wenn Cron oder Heartbeat nicht ausgeführt wurde oder nicht zugestellt hat, prüfen Sie zuerst den Scheduler-Status und dann das Zustellziel. +Wenn Cron oder Heartbeat nicht ausgeführt wurde oder nicht zugestellt wurde, prüfen Sie zuerst den Scheduler-Status und dann das Zustellziel. ```bash openclaw cron status @@ -398,21 +395,21 @@ openclaw system heartbeat last openclaw logs --follow ``` -Achten Sie auf: +Achten Sie auf Folgendes: -- Cron aktiviert und nächstes Aufwachen vorhanden. +- Cron ist aktiviert und der nächste Wake ist vorhanden. - Status der Job-Ausführungshistorie (`ok`, `skipped`, `error`). -- Gründe für das Überspringen des Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). +- Gründe für übersprungene Heartbeats (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). Häufige Signaturen: -- `cron: scheduler disabled; jobs will not run automatically` → Cron deaktiviert. +- `cron: scheduler disabled; jobs will not run automatically` → Cron ist deaktiviert. - `cron: timer tick failed` → Scheduler-Tick fehlgeschlagen; prüfen Sie Datei-/Log-/Laufzeitfehler. -- `heartbeat skipped` mit `reason=quiet-hours` → außerhalb des Fensters aktiver Zeiten. -- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` existiert, enthält aber nur Leerzeilen / Markdown-Überschriften, daher überspringt OpenClaw den Modellaufruf. +- `heartbeat skipped` mit `reason=quiet-hours` → außerhalb des aktiven Stundenfensters. +- `heartbeat skipped` mit `reason=empty-heartbeat-file` → `HEARTBEAT.md` ist vorhanden, enthält aber nur leere Zeilen / Markdown-Überschriften, daher überspringt OpenClaw den Modellaufruf. - `heartbeat skipped` mit `reason=no-tasks-due` → `HEARTBEAT.md` enthält einen `tasks:`-Block, aber bei diesem Tick ist keine der Aufgaben fällig. - `heartbeat: unknown accountId` → ungültige Konto-ID für das Heartbeat-Zustellziel. -- `heartbeat skipped` mit `reason=dm-blocked` → Heartbeat-Ziel wurde zu einem Ziel im DM-Stil aufgelöst, während `agents.defaults.heartbeat.directPolicy` (oder die Überschreibung pro Agent) auf `block` gesetzt ist. +- `heartbeat skipped` mit `reason=dm-blocked` → das Heartbeat-Ziel wurde zu einem Ziel im DM-Stil aufgelöst, während `agents.defaults.heartbeat.directPolicy` (oder die agentenspezifische Überschreibung) auf `block` gesetzt ist. Verwandt: @@ -420,9 +417,9 @@ Verwandt: - [/automation/cron-jobs](/de/automation/cron-jobs) - [/gateway/heartbeat](/de/gateway/heartbeat) -## Tool auf gekoppeltem Node schlägt fehl +## Gepairtes Node-Tool schlägt fehl -Wenn ein Node gekoppelt ist, aber Tools fehlschlagen, isolieren Sie Vordergrund-, Berechtigungs- und Genehmigungsstatus. +Wenn ein Node gepairt ist, aber Tools fehlschlagen, isolieren Sie Vordergrund-, Berechtigungs- und Freigabestatus. ```bash openclaw nodes status @@ -432,18 +429,18 @@ openclaw logs --follow openclaw status ``` -Achten Sie auf: +Achten Sie auf Folgendes: -- Node online mit den erwarteten Fähigkeiten. -- Vom Betriebssystem gewährte Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm. -- Exec-Genehmigungen und Allowlist-Status. +- Node online mit den erwarteten Capabilities. +- OS-Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm. +- Exec-Freigaben und Allowlist-Status. Häufige Signaturen: -- `NODE_BACKGROUND_UNAVAILABLE` → Node-App muss im Vordergrund sein. -- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → fehlende Betriebssystemberechtigung. -- `SYSTEM_RUN_DENIED: approval required` → Exec-Genehmigung ausstehend. -- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl durch Allowlist blockiert. +- `NODE_BACKGROUND_UNAVAILABLE` → die Node-App muss im Vordergrund sein. +- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → fehlende OS-Berechtigung. +- `SYSTEM_RUN_DENIED: approval required` → Exec-Freigabe ausstehend. +- `SYSTEM_RUN_DENIED: allowlist miss` → Befehl wurde durch die Allowlist blockiert. Verwandt: @@ -463,43 +460,44 @@ openclaw logs --follow openclaw doctor ``` -Achten Sie auf: +Achten Sie auf Folgendes: - Ob `plugins.allow` gesetzt ist und `browser` enthält. -- Gültigen Pfad zur Browser-Executable. +- Gültiger Pfad zur Browser-Executable. - Erreichbarkeit des CDP-Profils. -- Verfügbarkeit von lokalem Chrome für Profile `existing-session` / `user`. +- Lokale Chrome-Verfügbarkeit für `existing-session`- / `user`-Profile. Häufige Signaturen: - `unknown command "browser"` oder `unknown command 'browser'` → das gebündelte Browser-Plugin ist durch `plugins.allow` ausgeschlossen. - Browser-Tool fehlt / ist nicht verfügbar, obwohl `browser.enabled=true` → `plugins.allow` schließt `browser` aus, daher wurde das Plugin nie geladen. - `Failed to start Chrome CDP on port` → Browser-Prozess konnte nicht gestartet werden. -- `browser.executablePath not found` → konfigurierter Pfad ist ungültig. +- `browser.executablePath not found` → der konfigurierte Pfad ist ungültig. - `browser.cdpUrl must be http(s) or ws(s)` → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema wie `file:` oder `ftp:`. - `browser.cdpUrl has invalid port` → die konfigurierte CDP-URL hat einen ungültigen oder außerhalb des Bereichs liegenden Port. +- `Could not find DevToolsActivePort for chrome` → Chrome MCP `existing-session` konnte sich noch nicht an das ausgewählte Browser-Datenverzeichnis anhängen. Öffnen Sie die Browser-Inspect-Seite, aktivieren Sie Remote-Debugging, lassen Sie den Browser geöffnet, genehmigen Sie die erste Attach-Aufforderung und versuchen Sie es dann erneut. Wenn kein angemeldeter Zustand erforderlich ist, bevorzugen Sie das verwaltete Profil `openclaw`. - `No Chrome tabs found for profile="user"` → das Chrome-MCP-Attach-Profil hat keine geöffneten lokalen Chrome-Tabs. - `Remote CDP for profile "" is not reachable` → der konfigurierte Remote-CDP-Endpunkt ist vom Gateway-Host aus nicht erreichbar. -- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → das Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber das CDP-WebSocket konnte trotzdem nicht geöffnet werden. -- `Playwright is not available in this gateway build; '' is unsupported.` → der aktuellen Gateway-Installation fehlt das vollständige Playwright-Paket; ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, AI-Snapshots, Element-Screenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar. -- `fullPage is not supported for element screenshots` → Screenshot-Anfrage hat `--full-page` mit `--ref` oder `--element` kombiniert. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Screenshot-Aufrufe für Chrome MCP / `existing-session` müssen Seitenerfassung oder ein Snapshot-`--ref` verwenden, nicht CSS-`--element`. +- `Browser attachOnly is enabled ... not reachable` oder `Browser attachOnly is enabled and CDP websocket ... is not reachable` → das Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber das CDP-WebSocket konnte dennoch nicht geöffnet werden. +- `Playwright is not available in this gateway build; '' is unsupported.` → in der aktuellen Gateway-Installation fehlt das vollständige Playwright-Paket; ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, KI-Snapshots, Element-Screenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar. +- `fullPage is not supported for element screenshots` → die Screenshot-Anfrage hat `--full-page` mit `--ref` oder `--element` kombiniert. +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Screenshot-Aufrufe für Chrome MCP / `existing-session` müssen Seitenerfassung oder eine Snapshot-`--ref` verwenden, nicht CSS-`--element`. - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Upload-Hooks für Chrome MCP benötigen Snapshot-Refs, keine CSS-Selektoren. -- `existing-session file uploads currently support one file at a time.` → senden Sie pro Aufruf einen Upload auf Chrome-MCP-Profilen. -- `existing-session dialog handling does not support timeoutMs.` → Dialog-Hooks auf Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen. +- `existing-session file uploads currently support one file at a time.` → senden Sie bei Chrome-MCP-Profilen einen Upload pro Aufruf. +- `existing-session dialog handling does not support timeoutMs.` → Dialog-Hooks bei Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen. - `response body is not supported for existing-session profiles yet.` → `responsebody` erfordert weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil. -- veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline auf Attach-only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile ` aus, um die aktive Steuerungssitzung zu schließen und den Playwright-/CDP-Emulationsstatus freizugeben, ohne das gesamte Gateway neu zu starten. +- veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline auf Attach-only- oder Remote-CDP-Profilen → führen Sie `openclaw browser stop --browser-profile ` aus, um die aktive Kontrollsitzung zu schließen und den Playwright-/CDP-Emulationsstatus freizugeben, ohne das gesamte Gateway neu zu starten. Verwandt: - [/tools/browser-linux-troubleshooting](/de/tools/browser-linux-troubleshooting) - [/tools/browser](/de/tools/browser) -## Wenn nach einem Upgrade plötzlich etwas kaputtging +## Wenn Sie ein Upgrade durchgeführt haben und plötzlich etwas nicht mehr funktioniert -Die meisten Probleme nach Upgrades sind Konfigurationsdrift oder jetzt erzwungene strengere Standardwerte. +Die meisten Probleme nach einem Upgrade sind Konfigurationsabweichungen oder striktere Standards, die jetzt erzwungen werden. -### 1) Verhalten von Auth und URL-Überschreibungen hat sich geändert +### 1) Verhalten bei Authentifizierung und URL-Überschreibung hat sich geändert ```bash openclaw gateway status @@ -508,17 +506,17 @@ openclaw config get gateway.remote.url openclaw config get gateway.auth.mode ``` -Was Sie prüfen sollten: +Was zu prüfen ist: -- Wenn `gateway.mode=remote`, können CLI-Aufrufe auf remote zielen, während Ihr lokaler Dienst in Ordnung ist. -- Explizite `--url`-Aufrufe greifen nicht auf gespeicherte Anmeldedaten zurück. +- Wenn `gateway.mode=remote`, können CLI-Aufrufe das Remote-Ziel ansprechen, während Ihr lokaler Service in Ordnung ist. +- Explizite Aufrufe mit `--url` fallen nicht auf gespeicherte Anmeldedaten zurück. Häufige Signaturen: - `gateway connect failed:` → falsches URL-Ziel. - `unauthorized` → Endpunkt erreichbar, aber falsche Authentifizierung. -### 2) Bindungs- und Auth-Guardrails sind strenger +### 2) Bind- und Authentifizierungs-Schutzmechanismen sind strenger ```bash openclaw config get gateway.bind @@ -528,15 +526,15 @@ openclaw gateway status openclaw logs --follow ``` -Was Sie prüfen sollten: +Was zu prüfen ist: -- Nicht-Loopback-Bindungen (`lan`, `tailnet`, `custom`) benötigen einen gültigen Gateway-Authentifizierungspfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte Nicht-Loopback-`trusted-proxy`-Bereitstellung. +- Nicht-Loopback-Binds (`lan`, `tailnet`, `custom`) benötigen einen gültigen Gateway-Authentifizierungspfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte `trusted-proxy`-Bereitstellung ohne Loopback. - Alte Schlüssel wie `gateway.token` ersetzen `gateway.auth.token` nicht. Häufige Signaturen: -- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bindung ohne gültigen Gateway-Authentifizierungspfad. -- `Connectivity probe: failed`, während die Laufzeit läuft → Gateway ist aktiv, aber mit aktueller Authentifizierung/URL nicht erreichbar. +- `refusing to bind gateway ... without auth` → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad. +- `Connectivity probe: failed` während die Runtime läuft → Gateway aktiv, aber mit aktueller Authentifizierung/URL nicht erreichbar. ### 3) Pairing- und Geräteidentitätsstatus haben sich geändert @@ -547,17 +545,17 @@ openclaw logs --follow openclaw doctor ``` -Was Sie prüfen sollten: +Was zu prüfen ist: -- Ausstehende Gerätegenehmigungen für Dashboard/Nodes. -- Ausstehende DM-Pairing-Genehmigungen nach Änderungen an Richtlinie oder Identität. +- Ausstehende Gerätefreigaben für Dashboard/Nodes. +- Ausstehende DM-Pairing-Freigaben nach Richtlinien- oder Identitätsänderungen. Häufige Signaturen: - `device identity required` → Geräteauthentifizierung nicht erfüllt. -- `pairing required` → Absender/Gerät muss genehmigt werden. +- `pairing required` → Absender/Gerät muss freigegeben werden. -Wenn Dienstkonfiguration und Laufzeit nach den Prüfungen weiterhin nicht übereinstimmen, installieren Sie die Dienstmetadaten aus demselben Profil-/Statusverzeichnis neu: +Wenn Service-Konfiguration und Runtime nach den Prüfungen weiterhin nicht übereinstimmen, installieren Sie die Service-Metadaten aus demselben Profil-/Statusverzeichnis erneut: ```bash openclaw gateway install --force diff --git a/docs/de/help/faq.md b/docs/de/help/faq.md index 3e94c4c3c..f0c73251d 100644 --- a/docs/de/help/faq.md +++ b/docs/de/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - Beantwortung häufiger Fragen zu Einrichtung, Installation, Onboarding oder Laufzeit-Support - - Triage von von Benutzern gemeldeten Problemen vor tiefergehendem Debugging + - Triage von von Nutzern gemeldeten Problemen vor einer tieferen Fehlersuche summary: Häufig gestellte Fragen zur Einrichtung, Konfiguration und Nutzung von OpenClaw title: FAQ x-i18n: - generated_at: "2026-04-21T06:25:57Z" + generated_at: "2026-04-21T13:35:26Z" model: gpt-5.4 provider: openai - source_hash: 8bde531507540bc91bc131c3e27d72a8be76cc53ef46a5e01aaeaf02a71cc8a2 + source_hash: 3bd1df258baa4b289bc95ba0f7757b61c1412e230d93ebb137cb7117fbc3a2f1 source_path: help/faq.md workflow: 15 --- # FAQ -Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale Entwicklung, VPS, Multi-Agent, OAuth/API-Schlüssel, Model Failover). Für Laufzeitdiagnosen siehe [Troubleshooting](/de/gateway/troubleshooting). Für die vollständige Konfigurationsreferenz siehe [Configuration](/de/gateway/configuration). +Schnelle Antworten plus tiefergehende Fehlersuche für reale Setups (lokale Entwicklung, VPS, Multi-Agent, OAuth/API-Schlüssel, Modell-Failover). Für Laufzeitdiagnosen siehe [Fehlersuche](/de/gateway/troubleshooting). Für die vollständige Konfigurationsreferenz siehe [Konfiguration](/de/gateway/configuration). ## Die ersten 60 Sekunden, wenn etwas kaputt ist @@ -25,15 +25,15 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw status ``` - Schnelle lokale Zusammenfassung: Betriebssystem + Update, Erreichbarkeit von Gateway/Service, Agenten/Sitzungen, Provider-Konfiguration + Laufzeitprobleme (wenn das Gateway erreichbar ist). + Schnelle lokale Zusammenfassung: Betriebssystem + Update, Erreichbarkeit von Gateway/Service, Agents/Sitzungen, Provider-Konfiguration + Laufzeitprobleme (wenn das Gateway erreichbar ist). -2. **Teilbarer Bericht (sicher zum Weitergeben)** +2. **Einfügbarer Bericht (sicher zum Teilen)** ```bash openclaw status --all ``` - Nur lesende Diagnose mit Log-Tail (Tokens geschwärzt). + Schreibgeschützte Diagnose mit Log-Ende (Tokens redigiert). 3. **Daemon- + Port-Status** @@ -41,15 +41,15 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw gateway status ``` - Zeigt Supervisor-Laufzeit vs. RPC-Erreichbarkeit, die Ziel-URL der Prüfung und welche Konfiguration der Service wahrscheinlich verwendet hat. + Zeigt Supervisor-Laufzeit im Vergleich zur RPC-Erreichbarkeit, die Probe-Ziel-URL und welche Konfiguration der Service wahrscheinlich verwendet hat. -4. **Tiefere Prüfungen** +4. **Tiefgehende Probes** ```bash openclaw status --deep ``` - Führt eine Live-Gateway-Gesundheitsprüfung aus, einschließlich Kanalprüfungen, wenn unterstützt + Führt eine Live-Zustandsprüfung des Gateways aus, einschließlich Kanal-Probes, wenn unterstützt (erfordert ein erreichbares Gateway). Siehe [Health](/de/gateway/health). 5. **Aktuellstes Log verfolgen** @@ -58,13 +58,13 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw logs --follow ``` - Wenn RPC nicht verfügbar ist, verwenden Sie stattdessen: + Wenn RPC nicht verfügbar ist, stattdessen verwenden: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Dateilogs sind von Service-Logs getrennt; siehe [Logging](/de/logging) und [Troubleshooting](/de/gateway/troubleshooting). + Dateilogs sind von Service-Logs getrennt; siehe [Logging](/de/logging) und [Fehlersuche](/de/gateway/troubleshooting). 6. **Doctor ausführen (Reparaturen)** @@ -72,13 +72,13 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw doctor ``` - Repariert/migriert Konfiguration/Status + führt Gesundheitsprüfungen aus. Siehe [Doctor](/de/gateway/doctor). + Repariert/migriert Konfiguration/Zustand + führt Zustandsprüfungen aus. Siehe [Doctor](/de/gateway/doctor). 7. **Gateway-Snapshot** ```bash openclaw health --json - openclaw health --verbose # zeigt bei Fehlern die Ziel-URL + den Konfigurationspfad + openclaw health --verbose # zeigt die Ziel-URL + den Konfigurationspfad bei Fehlern ``` Fragt das laufende Gateway nach einem vollständigen Snapshot (nur WS). Siehe [Health](/de/gateway/health). @@ -86,30 +86,30 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E ## Schnellstart und Einrichtung beim ersten Start - - Verwenden Sie einen lokalen KI-Agenten, der **Ihren Rechner sehen** kann. Das ist deutlich effektiver, als - in Discord zu fragen, weil die meisten Fälle von „Ich stecke fest“ **lokale Konfigurations- oder Umgebungsprobleme** sind, - die entfernte Helfer nicht untersuchen können. + + Verwenden Sie einen lokalen KI-Agent, der **Ihre Maschine sehen** kann. Das ist deutlich effektiver als + in Discord zu fragen, weil die meisten Fälle von „Ich hänge fest“ **lokale Konfigurations- oder Umgebungsprobleme** sind, die + entfernte Helfer nicht prüfen können. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Diese Werkzeuge können das Repo lesen, Befehle ausführen, Logs prüfen und helfen, Probleme auf Maschinenebene - zu beheben (PATH, Services, Berechtigungen, Auth-Dateien). Geben Sie ihnen den **vollständigen Quellcode-Checkout** über - die hackbare (git)-Installation: + Diese Werkzeuge können das Repository lesen, Befehle ausführen, Logs prüfen und dabei helfen, Ihre Einrichtung auf Maschinenebene zu beheben + (PATH, Services, Berechtigungen, Auth-Dateien). Geben Sie ihnen den **vollständigen ausgecheckten Quellcode** über + die hackbare (git-)Installation: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Dadurch wird OpenClaw **aus einem git-Checkout** installiert, sodass der Agent Code + Docs lesen und - über die exakte Version nachdenken kann, die Sie ausführen. Sie können jederzeit später wieder auf stable wechseln, - indem Sie den Installer ohne `--install-method git` erneut ausführen. + Dadurch wird OpenClaw **aus einem git-Checkout** installiert, sodass der Agent den Code + die Dokumentation lesen und + auf Basis der exakten Version, die Sie ausführen, argumentieren kann. Sie können später jederzeit wieder auf die stabile Version umstellen, + indem Sie das Installationsprogramm ohne `--install-method git` erneut ausführen. - Tipp: Bitten Sie den Agenten, die Behebung zu **planen und zu überwachen** (Schritt für Schritt) und dann nur die - notwendigen Befehle auszuführen. Das hält Änderungen klein und leichter prüfbar. + Tipp: Bitten Sie den Agenten, die Behebung **zu planen und zu überwachen** (Schritt für Schritt) und dann nur die + notwendigen Befehle auszuführen. Dadurch bleiben Änderungen klein und leichter zu prüfen. - Wenn Sie einen echten Bug oder Fix entdecken, erstellen Sie bitte ein GitHub-Issue oder senden Sie einen PR: + Wenn Sie einen echten Fehler oder eine echte Korrektur entdecken, erstellen Sie bitte ein GitHub-Issue oder senden Sie einen PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) @@ -123,42 +123,42 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E Was sie tun: - - `openclaw status`: schneller Snapshot von Gateway-/Agentengesundheit + grundlegender Konfiguration. + - `openclaw status`: schneller Snapshot des Zustands von Gateway/Agent + grundlegende Konfiguration. - `openclaw models status`: prüft Provider-Authentifizierung + Modellverfügbarkeit. - - `openclaw doctor`: validiert und repariert häufige Konfigurations-/Statusprobleme. + - `openclaw doctor`: validiert und repariert häufige Konfigurations-/Zustandsprobleme. Weitere nützliche CLI-Prüfungen: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Schneller Debug-Loop: [Die ersten 60 Sekunden, wenn etwas kaputt ist](#die-ersten-60-sekunden-wenn-etwas-kaputt-ist). - Installationsdokumentation: [Install](/de/install), [Installer flags](/de/install/installer), [Updating](/de/install/updating). + Schnelle Debug-Schleife: [Die ersten 60 Sekunden, wenn etwas kaputt ist](#die-ersten-60-sekunden-wenn-etwas-kaputt-ist). + Installationsdokumentation: [Installation](/de/install), [Installer-Flags](/de/install/installer), [Aktualisieren](/de/install/updating). - Häufige Gründe, warum Heartbeat übersprungen wird: + Häufige Gründe, warum der Heartbeat übersprungen wird: - - `quiet-hours`: außerhalb des konfigurierten Aktivstunden-Fensters - - `empty-heartbeat-file`: `HEARTBEAT.md` existiert, enthält aber nur leeres/Header-only-Gerüst - - `no-tasks-due`: Der Aufgabenmodus von `HEARTBEAT.md` ist aktiv, aber keine der Aufgabenintervalle ist bereits fällig - - `alerts-disabled`: die gesamte Heartbeat-Sichtbarkeit ist deaktiviert (`showOk`, `showAlerts` und `useIndicator` sind alle ausgeschaltet) + - `quiet-hours`: außerhalb des konfigurierten active-hours-Fensters + - `empty-heartbeat-file`: `HEARTBEAT.md` existiert, enthält aber nur leere/header-only-Gerüste + - `no-tasks-due`: Der Aufgabenmodus von `HEARTBEAT.md` ist aktiv, aber noch keine der Aufgabenintervalle ist fällig + - `alerts-disabled`: die gesamte Heartbeat-Sichtbarkeit ist deaktiviert (`showOk`, `showAlerts` und `useIndicator` sind alle aus) - Im Aufgabenmodus werden Fälligkeitszeitstempel erst weitergeschoben, nachdem ein echter Heartbeat-Lauf - abgeschlossen ist. Übersprungene Läufe markieren Aufgaben nicht als abgeschlossen. + Im Aufgabenmodus werden Fälligkeitszeitstempel erst nach einem echten Heartbeat-Lauf + weitergeschoben. Übersprungene Läufe markieren Aufgaben nicht als abgeschlossen. - Dokumentation: [Heartbeat](/de/gateway/heartbeat), [Automation & Tasks](/de/automation). + Dokumentation: [Heartbeat](/de/gateway/heartbeat), [Automatisierung & Aufgaben](/de/automation). - Das Repo empfiehlt, aus dem Quellcode zu arbeiten und Onboarding zu verwenden: + Das Repository empfiehlt, aus dem Quellcode zu starten und das Onboarding zu verwenden: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - Der Assistent kann UI-Assets auch automatisch bauen. Nach dem Onboarding läuft das Gateway typischerweise auf Port **18789**. + Der Assistent kann auch UI-Assets automatisch bauen. Nach dem Onboarding führen Sie das Gateway normalerweise auf Port **18789** aus. Aus dem Quellcode (Mitwirkende/Entwicklung): @@ -176,62 +176,62 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E - Der Assistent öffnet direkt nach dem Onboarding Ihren Browser mit einer sauberen (nicht tokenisierten) Dashboard-URL und gibt den Link auch in der Zusammenfassung aus. Lassen Sie diesen Tab geöffnet; wenn er nicht gestartet wurde, kopieren Sie die ausgegebene URL auf demselben Rechner in den Browser. + Der Assistent öffnet Ihren Browser direkt nach dem Onboarding mit einer sauberen (nicht tokenisierten) Dashboard-URL und gibt den Link außerdem in der Zusammenfassung aus. Lassen Sie diesen Tab geöffnet; falls er nicht gestartet wurde, kopieren Sie die ausgegebene URL auf derselben Maschine in den Browser. - - **Localhost (derselbe Rechner):** + + **Localhost (dieselbe Maschine):** - Öffnen Sie `http://127.0.0.1:18789/`. - - Wenn nach Shared-Secret-Authentifizierung gefragt wird, fügen Sie den konfigurierten Token oder das Passwort in die Einstellungen der Control UI ein. + - Wenn nach Shared-Secret-Authentifizierung gefragt wird, fügen Sie das konfigurierte Token oder Passwort in die Einstellungen der Control UI ein. - Token-Quelle: `gateway.auth.token` (oder `OPENCLAW_GATEWAY_TOKEN`). - Passwort-Quelle: `gateway.auth.password` (oder `OPENCLAW_GATEWAY_PASSWORD`). - - Wenn noch kein Shared Secret konfiguriert ist, erzeugen Sie einen Token mit `openclaw doctor --generate-gateway-token`. + - Wenn noch kein Shared Secret konfiguriert ist, erzeugen Sie mit `openclaw doctor --generate-gateway-token` ein Token. **Nicht auf localhost:** - - **Tailscale Serve** (empfohlen): Behalten Sie loopback bind bei, führen Sie `openclaw gateway --tailscale serve` aus und öffnen Sie `https:///`. Wenn `gateway.auth.allowTailscale` auf `true` steht, erfüllen Identitäts-Header die Authentifizierung für Control UI/WebSocket (kein eingefügtes Shared Secret, setzt vertrauenswürdigen Gateway-Host voraus); HTTP-APIs erfordern weiterhin Shared-Secret-Authentifizierung, außer Sie verwenden bewusst `none` für privaten Ingress oder HTTP-Authentifizierung über einen vertrauenswürdigen Proxy. - Schlechte gleichzeitige Serve-Authentifizierungsversuche vom selben Client werden serialisiert, bevor der Limiter für fehlgeschlagene Authentifizierungen sie erfasst, sodass der zweite schlechte Wiederholungsversuch bereits `retry later` anzeigen kann. - - **Tailnet-Bind**: Führen Sie `openclaw gateway --bind tailnet --token ""` aus (oder konfigurieren Sie Passwortauthentifizierung), öffnen Sie `http://:18789/` und fügen Sie dann das passende Shared Secret in die Dashboard-Einstellungen ein. - - **Identity-aware Reverse Proxy**: Betreiben Sie das Gateway hinter einem nicht-loopback vertrauenswürdigen Proxy, konfigurieren Sie `gateway.auth.mode: "trusted-proxy"` und öffnen Sie dann die Proxy-URL. - - **SSH-Tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` und dann `http://127.0.0.1:18789/` öffnen. Shared-Secret-Authentifizierung gilt auch über den Tunnel; fügen Sie bei Aufforderung den konfigurierten Token oder das Passwort ein. + - **Tailscale Serve** (empfohlen): Bindung an loopback beibehalten, `openclaw gateway --tailscale serve` ausführen, `https:///` öffnen. Wenn `gateway.auth.allowTailscale` auf `true` gesetzt ist, erfüllen Identitäts-Header die Authentifizierung für Control UI/WebSocket (kein eingefügtes Shared Secret, setzt einen vertrauenswürdigen Gateway-Host voraus); HTTP-APIs erfordern weiterhin Shared-Secret-Authentifizierung, außer Sie verwenden absichtlich private-ingress `none` oder HTTP-Authentifizierung über einen trusted-proxy. + Schlechte gleichzeitige Serve-Authentifizierungsversuche vom selben Client werden serialisiert, bevor der Failed-Auth-Limiter sie erfasst, sodass der zweite schlechte Wiederholungsversuch bereits `retry later` anzeigen kann. + - **Tailnet-Bindung**: Führen Sie `openclaw gateway --bind tailnet --token ""` aus (oder konfigurieren Sie Passwort-Authentifizierung), öffnen Sie `http://:18789/` und fügen Sie dann das passende Shared Secret in die Dashboard-Einstellungen ein. + - **Identity-aware Reverse Proxy**: Behalten Sie das Gateway hinter einem trusted-proxy ohne loopback bei, konfigurieren Sie `gateway.auth.mode: "trusted-proxy"` und öffnen Sie dann die Proxy-URL. + - **SSH-Tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` und dann `http://127.0.0.1:18789/` öffnen. Shared-Secret-Authentifizierung gilt weiterhin über den Tunnel; fügen Sie bei Aufforderung das konfigurierte Token oder Passwort ein. - Siehe [Dashboard](/web/dashboard) und [Web surfaces](/web) für Bind-Modi und Authentifizierungsdetails. + Siehe [Dashboard](/web/dashboard) und [Web surfaces](/web) für Bindungsmodi und Authentifizierungsdetails. - + Sie steuern unterschiedliche Ebenen: - - `approvals.exec`: leitet Freigabeaufforderungen an Chat-Ziele weiter - - `channels..execApprovals`: macht diesen Kanal zu einem nativen Approval-Client für Exec-Freigaben + - `approvals.exec`: leitet Genehmigungsaufforderungen an Chat-Ziele weiter + - `channels..execApprovals`: lässt diesen Kanal als nativen Genehmigungs-Client für exec-Genehmigungen fungieren - Die Host-Exec-Richtlinie ist weiterhin das eigentliche Freigabe-Gate. Die Chat-Konfiguration steuert nur, wo Freigabe- - aufforderungen erscheinen und wie Personen antworten können. + Die exec-Richtlinie des Hosts ist weiterhin das eigentliche Genehmigungs-Gate. Die Chat-Konfiguration steuert nur, wo Genehmigungs- + aufforderungen erscheinen und wie Personen darauf antworten können. In den meisten Setups benötigen Sie **nicht** beides: - Wenn der Chat bereits Befehle und Antworten unterstützt, funktioniert `/approve` im selben Chat über den gemeinsamen Pfad. - - Wenn ein unterstützter nativer Kanal Freigebende sicher ableiten kann, aktiviert OpenClaw jetzt automatisch DM-first-native Freigaben, wenn `channels..execApprovals.enabled` nicht gesetzt ist oder auf `"auto"` steht. - - Wenn native Freigabekarten/-schaltflächen verfügbar sind, ist diese native UI der primäre Pfad; der Agent sollte nur dann einen manuellen `/approve`-Befehl einfügen, wenn das Tool-Ergebnis sagt, dass Chat-Freigaben nicht verfügbar sind oder nur manuelle Freigabe möglich ist. - - Verwenden Sie `approvals.exec` nur dann, wenn Aufforderungen zusätzlich an andere Chats oder explizite Ops-Räume weitergeleitet werden müssen. - - Verwenden Sie `channels..execApprovals.target: "channel"` oder `"both"` nur dann, wenn Sie ausdrücklich möchten, dass Freigabeaufforderungen zurück in den ursprünglichen Raum/das ursprüngliche Thema gepostet werden. - - Plugin-Freigaben sind wiederum separat: Sie verwenden standardmäßig `/approve` im selben Chat, optionales `approvals.plugin`-Forwarding, und nur einige native Kanäle behalten native Plugin-Freigabe-Verarbeitung zusätzlich bei. + - Wenn ein unterstützter nativer Kanal Genehmigende sicher ableiten kann, aktiviert OpenClaw jetzt native DM-first-Genehmigungen automatisch, wenn `channels..execApprovals.enabled` nicht gesetzt oder `"auto"` ist. + - Wenn native Genehmigungskarten/-schaltflächen verfügbar sind, ist diese native UI der primäre Pfad; der Agent sollte nur dann einen manuellen `/approve`-Befehl einfügen, wenn das Tool-Ergebnis sagt, dass Chat-Genehmigungen nicht verfügbar sind oder eine manuelle Genehmigung der einzige Weg ist. + - Verwenden Sie `approvals.exec` nur, wenn Aufforderungen zusätzlich an andere Chats oder explizite Ops-Räume weitergeleitet werden müssen. + - Verwenden Sie `channels..execApprovals.target: "channel"` oder `"both"` nur dann, wenn Sie Genehmigungsaufforderungen ausdrücklich wieder im ursprünglichen Raum/Thema posten möchten. + - Plugin-Genehmigungen sind noch einmal getrennt: Sie verwenden standardmäßig `/approve` im selben Chat, optionales `approvals.plugin`-Weiterleiten, und nur einige native Kanäle behalten zusätzlich native Behandlung von Plugin-Genehmigungen bei. - Kurzfassung: Forwarding dient dem Routing, native Client-Konfiguration dem reichhaltigeren kanalspezifischen UX. + Kurz gesagt: Weiterleiten dient dem Routing, native Client-Konfiguration dient einer reichhaltigeren kanalspezifischen UX. Siehe [Exec Approvals](/de/tools/exec-approvals). - + Node **>= 22** ist erforderlich. `pnpm` wird empfohlen. Bun wird für das Gateway **nicht empfohlen**. - Ja. Das Gateway ist leichtgewichtig – in der Dokumentation werden **512MB–1GB RAM**, **1 Kern** und etwa **500MB** - Speicherplatz als ausreichend für den persönlichen Einsatz genannt, und es wird darauf hingewiesen, dass ein **Raspberry Pi 4 es ausführen kann**. + Ja. Das Gateway ist leichtgewichtig – die Dokumentation nennt **512 MB–1 GB RAM**, **1 Kern** und etwa **500 MB** + Speicherplatz als ausreichend für die persönliche Nutzung und weist darauf hin, dass ein **Raspberry Pi 4 es ausführen kann**. - Wenn Sie etwas mehr Spielraum möchten (Logs, Medien, andere Services), werden **2GB empfohlen**, aber das + Wenn Sie etwas mehr Spielraum möchten (Logs, Medien, andere Services), werden **2 GB empfohlen**, aber das ist kein hartes Minimum. Tipp: Ein kleiner Pi/VPS kann das Gateway hosten, und Sie können **Nodes** auf Ihrem Laptop/Telefon koppeln für @@ -239,30 +239,30 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E - - Kurzfassung: Es funktioniert, aber rechnen Sie mit Ecken und Kanten. + + Kurz gesagt: Es funktioniert, aber rechnen Sie mit Ecken und Kanten. - - Verwenden Sie ein **64-Bit**-OS und behalten Sie Node >= 22. - - Bevorzugen Sie die **hackbare (git)-Installation**, damit Sie Logs sehen und schnell aktualisieren können. - - Starten Sie ohne Kanäle/Skills und fügen Sie sie dann einzeln hinzu. + - Verwenden Sie ein **64-Bit**-Betriebssystem und halten Sie Node auf >= 22. + - Bevorzugen Sie die **hackbare (git-)Installation**, damit Sie Logs sehen und schnell aktualisieren können. + - Starten Sie ohne Kanäle/Skills und fügen Sie sie dann nacheinander hinzu. - Wenn Sie auf seltsame Binärprobleme stoßen, ist das meist ein **ARM-Kompatibilitäts**problem. - Dokumentation: [Linux](/de/platforms/linux), [Install](/de/install). + Dokumentation: [Linux](/de/platforms/linux), [Installation](/de/install). - + Dieser Bildschirm hängt davon ab, dass das Gateway erreichbar und authentifiziert ist. Die TUI sendet auch - „Wake up, my friend!“ automatisch beim ersten Schlüpfen. Wenn Sie diese Zeile mit **keiner Antwort** + „Wake up, my friend!“ beim ersten Schlüpfen automatisch. Wenn Sie diese Zeile mit **keiner Antwort** sehen und Tokens bei 0 bleiben, wurde der Agent nie ausgeführt. - 1. Starten Sie das Gateway neu: + 1. Gateway neu starten: ```bash openclaw gateway restart ``` - 2. Prüfen Sie Status + Authentifizierung: + 2. Status + Auth prüfen: ```bash openclaw status @@ -270,37 +270,37 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw logs --follow ``` - 3. Wenn es weiterhin hängt, führen Sie aus: + 3. Wenn es weiterhin hängt, führen Sie Folgendes aus: ```bash openclaw doctor ``` Wenn das Gateway remote ist, stellen Sie sicher, dass die Tunnel-/Tailscale-Verbindung aktiv ist und dass die UI - auf das richtige Gateway zeigt. Siehe [Remote access](/de/gateway/remote). + auf das richtige Gateway zeigt. Siehe [Remote-Zugriff](/de/gateway/remote). - + Ja. Kopieren Sie das **Statusverzeichnis** und den **Workspace** und führen Sie dann einmal Doctor aus. Dadurch - bleibt Ihr Bot „genau gleich“ (Memory, Sitzungsverlauf, Authentifizierung und Kanal- - status), solange Sie **beide** Orte kopieren: + bleibt Ihr Bot „exakt gleich“ (Memory, Sitzungsverlauf, Auth und Kanal- + status), solange Sie **beide** Speicherorte kopieren: - 1. Installieren Sie OpenClaw auf dem neuen Rechner. - 2. Kopieren Sie `$OPENCLAW_STATE_DIR` (Standard: `~/.openclaw`) vom alten Rechner. + 1. Installieren Sie OpenClaw auf der neuen Maschine. + 2. Kopieren Sie `$OPENCLAW_STATE_DIR` (Standard: `~/.openclaw`) von der alten Maschine. 3. Kopieren Sie Ihren Workspace (Standard: `~/.openclaw/workspace`). 4. Führen Sie `openclaw doctor` aus und starten Sie den Gateway-Service neu. - Dadurch bleiben Konfiguration, Auth-Profile, WhatsApp-Credentials, Sitzungen und Memory erhalten. Wenn Sie sich im - Remote-Modus befinden, denken Sie daran, dass der Gateway-Host den Sitzungsspeicher und den Workspace besitzt. + Dadurch bleiben Konfiguration, Auth-Profile, WhatsApp-Anmeldedaten, Sitzungen und Memory erhalten. Wenn Sie im + Remote-Modus arbeiten, beachten Sie, dass der Gateway-Host den Sitzungsspeicher und den Workspace besitzt. **Wichtig:** Wenn Sie nur Ihren Workspace in GitHub committen/pushen, sichern Sie - **Memory + Bootstrap-Dateien**, aber **nicht** den Sitzungsverlauf oder die Authentifizierung. Diese liegen + **Memory + Bootstrap-Dateien**, aber **nicht** Sitzungsverlauf oder Auth. Diese liegen unter `~/.openclaw/` (zum Beispiel `~/.openclaw/agents//sessions/`). - Verwandt: [Migrating](/de/install/migrating), [Wo Dinge auf der Festplatte liegen](#where-things-live-on-disk), - [Agent workspace](/de/concepts/agent-workspace), [Doctor](/de/gateway/doctor), - [Remote mode](/de/gateway/remote). + Verwandte Themen: [Migration](/de/install/migrating), [Wo Dinge auf der Festplatte liegen](#where-things-live-on-disk), + [Agent-Workspace](/de/concepts/agent-workspace), [Doctor](/de/gateway/doctor), + [Remote-Modus](/de/gateway/remote). @@ -309,42 +309,42 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) Die neuesten Einträge stehen oben. Wenn der oberste Abschnitt als **Unreleased** markiert ist, ist der nächste datierte - Abschnitt die zuletzt ausgelieferte Version. Einträge sind nach **Highlights**, **Changes** und - **Fixes** gruppiert (plus Docs-/andere Abschnitte bei Bedarf). + Abschnitt die zuletzt veröffentlichte Version. Die Einträge sind nach **Highlights**, **Änderungen** und + **Fehlerbehebungen** gruppiert (plus Dokumentation/andere Abschnitte, wenn nötig). - + Einige Comcast/Xfinity-Verbindungen blockieren `docs.openclaw.ai` fälschlicherweise über Xfinity - Advanced Security. Deaktivieren Sie dies oder setzen Sie `docs.openclaw.ai` auf die Zulassungsliste und versuchen Sie es erneut. - Bitte helfen Sie uns, die Blockierung aufzuheben, indem Sie dies hier melden: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Advanced Security. Deaktivieren Sie dies oder setzen Sie `docs.openclaw.ai` auf die Allowlist und versuchen Sie es dann erneut. + Bitte helfen Sie uns, die Blockierung aufzuheben, indem Sie es hier melden: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Wenn Sie die Website weiterhin nicht erreichen können, sind die Docs auf GitHub gespiegelt: + Wenn Sie die Website weiterhin nicht erreichen können, sind die Dokumente auf GitHub gespiegelt: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - **Stable** und **beta** sind **npm dist-tags**, keine separaten Code-Linien: + **Stable** und **beta** sind **npm dist-tags**, keine getrennten Code-Linien: - `latest` = stable - `beta` = früher Build zum Testen - Normalerweise landet ein stable Release zuerst auf **beta**, dann verschiebt ein expliziter - Promotionsschritt dieselbe Version auf `latest`. Maintainer können bei Bedarf auch + Normalerweise landet eine stable-Version zuerst auf **beta**, dann verschiebt ein expliziter + Promotion-Schritt genau diese Version auf `latest`. Maintainer können bei Bedarf auch direkt auf `latest` veröffentlichen. Deshalb können beta und stable nach der Promotion auf **dieselbe Version** zeigen. - Was sich geändert hat: + Sehen Sie nach, was sich geändert hat: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Einzeiler für die Installation und den Unterschied zwischen beta und dev finden Sie im Accordion unten. + Einzeilige Installationsbefehle und den Unterschied zwischen beta und dev finden Sie im Akkordeon unten. - - **Beta** ist das npm dist-tag `beta` (kann nach der Promotion mit `latest` übereinstimmen). - **Dev** ist der bewegliche Head von `main` (git); wenn veröffentlicht, verwendet es das npm dist-tag `dev`. + + **Beta** ist das npm-dist-tag `beta` (kann nach der Promotion mit `latest` übereinstimmen). + **Dev** ist der bewegliche Stand von `main` (git); wenn veröffentlicht, verwendet es das npm-dist-tag `dev`. Einzeiler (macOS/Linux): @@ -359,11 +359,11 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E Windows-Installer (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Mehr Details: [Development channels](/de/install/development-channels) und [Installer flags](/de/install/installer). + Mehr Details: [Entwicklungskanäle](/de/install/development-channels) und [Installer-Flags](/de/install/installer). - + Zwei Optionen: 1. **Dev-Kanal (git-Checkout):** @@ -372,7 +372,7 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw update --channel dev ``` - Dadurch wechseln Sie auf den Branch `main` und aktualisieren aus dem Quellcode. + Dadurch wird auf den Branch `main` gewechselt und aus dem Quellcode aktualisiert. 2. **Hackbare Installation (von der Installer-Website):** @@ -380,9 +380,9 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Dadurch erhalten Sie ein lokales Repo, das Sie bearbeiten und dann per git aktualisieren können. + Dadurch erhalten Sie ein lokales Repository, das Sie bearbeiten und dann über git aktualisieren können. - Wenn Sie lieber manuell einen sauberen Clone bevorzugen, verwenden Sie: + Wenn Sie lieber manuell einen sauberen Klon erstellen möchten, verwenden Sie: ```bash git clone https://github.com/openclaw/openclaw.git @@ -391,36 +391,36 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E pnpm build ``` - Docs: [Update](/cli/update), [Development channels](/de/install/development-channels), - [Install](/de/install). + Dokumentation: [Update](/cli/update), [Entwicklungskanäle](/de/install/development-channels), + [Installation](/de/install). - Grobe Orientierung: + Grobe Richtwerte: - **Installation:** 2–5 Minuten - **Onboarding:** 5–15 Minuten, je nachdem, wie viele Kanäle/Modelle Sie konfigurieren - Wenn es hängt, verwenden Sie [Installer hängt](#quick-start-and-first-run-setup) - und den schnellen Debug-Loop in [Ich stecke fest](#quick-start-and-first-run-setup). + Wenn es hängt, verwenden Sie [Installer hängt?](#quick-start-and-first-run-setup) + und die schnelle Debug-Schleife unter [Ich hänge fest](#quick-start-and-first-run-setup). - + Führen Sie den Installer mit **ausführlicher Ausgabe** erneut aus: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Beta-Installation mit verbose: + Beta-Installation mit ausführlicher Ausgabe: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Für eine hackbare (git)-Installation: + Für eine hackbare (git-)Installation: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose @@ -435,44 +435,44 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E Set-PSDebug -Trace 0 ``` - Weitere Optionen: [Installer flags](/de/install/installer). + Weitere Optionen: [Installer-Flags](/de/install/installer). - + Zwei häufige Windows-Probleme: - **1) npm-Fehler spawn git / git nicht gefunden** + **1) npm-Fehler spawn git / git not found** - - Installieren Sie **Git for Windows** und stellen Sie sicher, dass `git` in Ihrem PATH ist. - - Schließen Sie PowerShell und öffnen Sie es erneut, dann führen Sie den Installer erneut aus. + - Installieren Sie **Git for Windows** und stellen Sie sicher, dass `git` auf Ihrem PATH liegt. + - Schließen und öffnen Sie PowerShell erneut und führen Sie dann den Installer erneut aus. **2) openclaw wird nach der Installation nicht erkannt** - - Ihr globaler npm-bin-Ordner ist nicht im PATH. + - Ihr globaler npm-bin-Ordner ist nicht auf PATH. - Prüfen Sie den Pfad: ```powershell npm config get prefix ``` - - Fügen Sie dieses Verzeichnis zu Ihrem Benutzer-PATH hinzu (unter Windows ist kein Suffix `\bin` nötig; auf den meisten Systemen ist es `%AppData%\npm`). - - Schließen Sie PowerShell nach der PATH-Aktualisierung und öffnen Sie es erneut. + - Fügen Sie dieses Verzeichnis zu Ihrem Benutzer-PATH hinzu (unter Windows ist kein `\bin`-Suffix nötig; auf den meisten Systemen ist es `%AppData%\npm`). + - Schließen und öffnen Sie PowerShell erneut, nachdem Sie PATH aktualisiert haben. Wenn Sie das reibungsloseste Windows-Setup möchten, verwenden Sie **WSL2** statt nativem Windows. - Docs: [Windows](/de/platforms/windows). + Dokumentation: [Windows](/de/platforms/windows). - - Das ist normalerweise eine nicht passende Konsolen-Codepage in nativen Windows-Shells. + + Das ist normalerweise ein Mismatch der Konsolen-Codepage in nativen Windows-Shells. Symptome: - - `system.run`-/`exec`-Ausgabe stellt Chinesisch als Mojibake dar - - Derselbe Befehl sieht in einem anderen Terminalprofil korrekt aus + - Die Ausgabe von `system.run`/`exec` stellt Chinesisch als Mojibake dar + - Derselbe Befehl sieht in einem anderen Terminal-Profil korrekt aus - Schnelle Zwischenlösung in PowerShell: + Schnelle Umgehung in PowerShell: ```powershell chcp 65001 @@ -487,30 +487,30 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw gateway restart ``` - Wenn Sie dies weiterhin mit der neuesten OpenClaw-Version reproduzieren, verfolgen/melden Sie es hier: + Wenn sich das auf dem neuesten OpenClaw weiterhin reproduzieren lässt, verfolgen/melden Sie es hier: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - Verwenden Sie die **hackbare (git)-Installation**, damit Sie den vollständigen Quellcode und die Docs lokal haben, und fragen Sie dann - Ihren Bot (oder Claude/Codex) _aus diesem Ordner heraus_, sodass er das Repo lesen und präzise antworten kann. + + Verwenden Sie die **hackbare (git-)Installation**, damit Sie den vollständigen Quellcode und die vollständige Dokumentation lokal haben, und fragen Sie dann + Ihren Bot (oder Claude/Codex) _aus diesem Ordner heraus_, damit er das Repository lesen und präzise antworten kann. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Mehr Details: [Install](/de/install) und [Installer flags](/de/install/installer). + Mehr Details: [Installation](/de/install) und [Installer-Flags](/de/install/installer). - Kurze Antwort: Folgen Sie der Linux-Anleitung und führen Sie dann das Onboarding aus. + Kurzantwort: Folgen Sie der Linux-Anleitung und führen Sie dann das Onboarding aus. - Schneller Linux-Pfad + Service-Installation: [Linux](/de/platforms/linux). - - Vollständige Anleitung: [Getting Started](/de/start/getting-started). - - Installer + Updates: [Install & updates](/de/install/updating). + - Vollständige Schritt-für-Schritt-Anleitung: [Erste Schritte](/de/start/getting-started). + - Installer + Updates: [Installation & Updates](/de/install/updating). @@ -523,30 +523,30 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E - Wir haben einen **Hosting-Hub** mit den gängigen Anbietern. Wählen Sie einen aus und folgen Sie der Anleitung: + Wir haben ein **Hosting-Hub** mit den gängigen Anbietern. Wählen Sie einen aus und folgen Sie der Anleitung: - - [VPS hosting](/de/vps) (alle Anbieter an einem Ort) + - [VPS-Hosting](/de/vps) (alle Anbieter an einem Ort) - [Fly.io](/de/install/fly) - [Hetzner](/de/install/hetzner) - [exe.dev](/de/install/exe-dev) So funktioniert es in der Cloud: Das **Gateway läuft auf dem Server**, und Sie greifen - von Ihrem Laptop/Telefon über die Control UI (oder Tailscale/SSH) darauf zu. Ihr Status + Workspace - liegen auf dem Server, behandeln Sie also den Host als Quelle der Wahrheit und sichern Sie ihn. + von Ihrem Laptop/Telefon über die Control UI (oder Tailscale/SSH) darauf zu. Ihr Zustand + Workspace + liegen auf dem Server, behandeln Sie den Host also als Source of Truth und sichern Sie ihn entsprechend. - Sie können **Nodes** (Mac/iOS/Android/headless) mit diesem Cloud-Gateway koppeln, um auf - lokalen Bildschirm/Kamera/Canvas zuzugreifen oder Befehle auf Ihrem Laptop auszuführen, während das + Sie können **Nodes** (Mac/iOS/Android/headless) mit diesem Cloud-Gateway koppeln, um Zugriff auf + lokalen Bildschirm/Kamera/Canvas zu erhalten oder Befehle auf Ihrem Laptop auszuführen, während das Gateway in der Cloud bleibt. - Hub: [Platforms](/de/platforms). Remote-Zugriff: [Gateway remote](/de/gateway/remote). + Hub: [Plattformen](/de/platforms). Remote-Zugriff: [Gateway remote](/de/gateway/remote). Nodes: [Nodes](/de/nodes), [Nodes CLI](/cli/nodes). - Kurze Antwort: **möglich, nicht empfohlen**. Der Update-Ablauf kann das - Gateway neu starten (wodurch die aktive Sitzung verloren geht), eventuell einen sauberen git-Checkout benötigen und - nach Bestätigung fragen. Sicherer: Führen Sie Updates als Operator in einer Shell aus. + Kurzantwort: **möglich, nicht empfohlen**. Der Update-Ablauf kann das + Gateway neu starten (wodurch die aktive Sitzung verloren geht), erfordert möglicherweise ein sauberes git-Checkout und + kann nach einer Bestätigung fragen. Sicherer ist es, Updates als Operator aus einer Shell auszuführen. Verwenden Sie die CLI: @@ -558,79 +558,79 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E openclaw update --no-restart ``` - Wenn Sie unbedingt von einem Agenten aus automatisieren müssen: + Wenn Sie es von einem Agenten aus automatisieren müssen: ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - Docs: [Update](/cli/update), [Updating](/de/install/updating). + Dokumentation: [Update](/cli/update), [Aktualisieren](/de/install/updating). - + `openclaw onboard` ist der empfohlene Einrichtungsweg. Im **lokalen Modus** führt es Sie durch: - **Modell-/Auth-Einrichtung** (Provider-OAuth, API-Schlüssel, Anthropic-Setup-Token sowie lokale Modelloptionen wie LM Studio) - **Workspace**-Speicherort + Bootstrap-Dateien - - **Gateway-Einstellungen** (Bind/Port/Auth/tailscale) + - **Gateway-Einstellungen** (bind/port/auth/tailscale) - **Kanäle** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage sowie gebündelte Kanal-Plugins wie QQ Bot) - - **Daemon-Installation** (LaunchAgent unter macOS; systemd-User-Unit unter Linux/WSL2) - - **Health Checks** und **Skills**-Auswahl + - **Daemon-Installation** (LaunchAgent unter macOS; systemd-Benutzereinheit unter Linux/WSL2) + - **Health-Checks** und **Skills**-Auswahl - Es warnt auch, wenn Ihr konfiguriertes Modell unbekannt ist oder Authentifizierung fehlt. + Es warnt außerdem, wenn Ihr konfiguriertes Modell unbekannt ist oder Auth fehlt. Nein. Sie können OpenClaw mit **API-Schlüsseln** (Anthropic/OpenAI/andere) oder mit **rein lokalen Modellen** ausführen, sodass Ihre Daten auf Ihrem Gerät bleiben. Abonnements (Claude - Pro/Max oder OpenAI Codex) sind optionale Methoden, um diese Provider zu authentifizieren. + Pro/Max oder OpenAI Codex) sind optionale Möglichkeiten zur Authentifizierung bei diesen Providern. - Für Anthropic in OpenClaw ist die praktische Aufteilung: + Für Anthropic in OpenClaw ist die praktische Unterscheidung: - - **Anthropic-API-Schlüssel**: normale Anthropic-API-Abrechnung - - **Claude-CLI- / Claude-Abonnement-Authentifizierung in OpenClaw**: Anthropic-Mitarbeiter - haben uns mitgeteilt, dass diese Nutzung wieder erlaubt ist, und OpenClaw behandelt die Nutzung von `claude -p` - als für diese Integration zulässig, sofern Anthropic keine neue + - **Anthropic API key**: normale Anthropic-API-Abrechnung + - **Claude CLI / Claude-Abonnement-Auth in OpenClaw**: Anthropic-Mitarbeiter + haben uns gesagt, dass diese Nutzung wieder erlaubt ist, und OpenClaw behandelt die Nutzung von `claude -p` + für diese Integration als genehmigt, sofern Anthropic keine neue Richtlinie veröffentlicht Für langlebige Gateway-Hosts sind Anthropic-API-Schlüssel weiterhin die besser - vorhersagbare Einrichtung. OpenAI-Codex-OAuth wird ausdrücklich für externe - Tools wie OpenClaw unterstützt. + vorhersehbare Einrichtung. OpenAI Codex OAuth wird für externe + Werkzeuge wie OpenClaw ausdrücklich unterstützt. - OpenClaw unterstützt auch andere gehostete abonnementartige Optionen, darunter + OpenClaw unterstützt außerdem weitere gehostete abonnementähnliche Optionen, darunter **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** und **Z.AI / GLM Coding Plan**. - Docs: [Anthropic](/de/providers/anthropic), [OpenAI](/de/providers/openai), + Dokumentation: [Anthropic](/de/providers/anthropic), [OpenAI](/de/providers/openai), [Qwen Cloud](/de/providers/qwen), [MiniMax](/de/providers/minimax), [GLM Models](/de/providers/glm), - [Local models](/de/gateway/local-models), [Models](/de/concepts/models). + [Lokale Modelle](/de/gateway/local-models), [Modelle](/de/concepts/models). Ja. - Anthropic-Mitarbeiter haben uns mitgeteilt, dass die Claude-CLI-Nutzung im Stil von OpenClaw wieder erlaubt ist, daher - behandelt OpenClaw die Claude-Abonnement-Authentifizierung und die Nutzung von `claude -p` als für diese Integration - zulässig, sofern Anthropic keine neue Richtlinie veröffentlicht. Wenn Sie das - möglichst vorhersagbare serverseitige Setup möchten, verwenden Sie stattdessen einen Anthropic-API-Schlüssel. + Anthropic-Mitarbeiter haben uns gesagt, dass die OpenClaw-artige Nutzung der Claude CLI wieder erlaubt ist, daher + behandelt OpenClaw Claude-Abonnement-Auth und die Nutzung von `claude -p` für diese Integration als genehmigt, + sofern Anthropic keine neue Richtlinie veröffentlicht. Wenn Sie die am besten vorhersehbare serverseitige Einrichtung möchten, + verwenden Sie stattdessen einen Anthropic API key. - + Ja. - Anthropic-Mitarbeiter haben uns mitgeteilt, dass diese Nutzung wieder erlaubt ist, daher behandelt OpenClaw - die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` als für diese Integration zulässig, + Anthropic-Mitarbeiter haben uns gesagt, dass diese Nutzung wieder erlaubt ist, daher behandelt OpenClaw + die Wiederverwendung der Claude CLI und die Nutzung von `claude -p` für diese Integration als genehmigt, sofern Anthropic keine neue Richtlinie veröffentlicht. Das Anthropic-Setup-Token ist weiterhin als unterstützter OpenClaw-Tokenpfad verfügbar, aber OpenClaw bevorzugt jetzt die Wiederverwendung der Claude CLI und `claude -p`, wenn verfügbar. - Für Produktions- oder Multi-User-Workloads ist die Authentifizierung per Anthropic-API-Schlüssel weiterhin die - sicherere und vorhersagbarere Wahl. Wenn Sie andere gehostete abonnementartige + Für Produktion oder Multi-User-Workloads bleibt Anthropic-API-key-Auth die + sicherere, besser vorhersehbare Wahl. Wenn Sie andere gehostete abonnementähnliche Optionen in OpenClaw möchten, siehe [OpenAI](/de/providers/openai), [Qwen / Model Cloud](/de/providers/qwen), [MiniMax](/de/providers/minimax) und [GLM Models](/de/providers/glm). @@ -639,71 +639,71 @@ Schnelle Antworten plus tiefergehende Fehlerbehebung für reale Setups (lokale E -Das bedeutet, dass Ihr **Anthropic-Kontingent/Ratenlimit** für das aktuelle Zeitfenster ausgeschöpft ist. Wenn Sie -**Claude CLI** verwenden, warten Sie, bis das Zeitfenster zurückgesetzt wird, oder upgraden Sie Ihren Tarif. Wenn Sie -einen **Anthropic-API-Schlüssel** verwenden, prüfen Sie die Anthropic Console -auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. +Das bedeutet, dass Ihr **Anthropic-Kontingent/Ratenlimit** für das aktuelle Zeitfenster erschöpft ist. Wenn Sie +**Claude CLI** verwenden, warten Sie, bis das Zeitfenster zurückgesetzt wird, oder aktualisieren Sie Ihren Tarif. Wenn Sie +einen **Anthropic API key** verwenden, prüfen Sie die Anthropic Console +auf Nutzung/Abrechnung und erhöhen Sie die Limits nach Bedarf. Wenn die Meldung konkret lautet: `Extra usage is required for long context requests`, versucht die Anfrage, - die 1M-Kontext-Beta von Anthropic zu verwenden (`context1m: true`). Das funktioniert nur, wenn Ihre - Credentials für Long-Context-Abrechnung berechtigt sind (API-Schlüssel-Abrechnung oder der + die 1M-Context-Beta von Anthropic zu verwenden (`context1m: true`). Das funktioniert nur, wenn Ihre + Anmeldedaten für Long-Context-Abrechnung geeignet sind (API-key-Abrechnung oder der OpenClaw-Claude-Login-Pfad mit aktiviertem Extra Usage). - Tipp: Setzen Sie ein **Fallback-Modell**, damit OpenClaw weiter antworten kann, während ein Provider ratenlimitiert ist. + Tipp: Legen Sie ein **Fallback-Modell** fest, damit OpenClaw weiter antworten kann, während ein Provider rate-limitiert ist. Siehe [Models](/cli/models), [OAuth](/de/concepts/oauth) und [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/de/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Ja. OpenClaw enthält einen gebündelten **Amazon Bedrock (Converse)**-Provider. Wenn AWS-Env-Marker vorhanden sind, kann OpenClaw den Streaming-/Text-Bedrock-Katalog automatisch erkennen und ihn als impliziten `amazon-bedrock`-Provider zusammenführen; andernfalls können Sie `plugins.entries.amazon-bedrock.config.discovery.enabled` explizit aktivieren oder einen manuellen Provider-Eintrag hinzufügen. Siehe [Amazon Bedrock](/de/providers/bedrock) und [Model providers](/de/providers/models). Wenn Sie einen verwalteten Key-Flow bevorzugen, bleibt ein OpenAI-kompatibler Proxy vor Bedrock weiterhin eine gültige Option. + Ja. OpenClaw hat einen gebündelten **Amazon Bedrock (Converse)**-Provider. Wenn AWS-Umgebungsmarker vorhanden sind, kann OpenClaw den Streaming-/Text-Bedrock-Katalog automatisch erkennen und ihn als impliziten `amazon-bedrock`-Provider zusammenführen; andernfalls können Sie `plugins.entries.amazon-bedrock.config.discovery.enabled` explizit aktivieren oder einen manuellen Provider-Eintrag hinzufügen. Siehe [Amazon Bedrock](/de/providers/bedrock) und [Modell-Provider](/de/providers/models). Wenn Sie einen verwalteten Key-Ablauf bevorzugen, bleibt ein OpenAI-kompatibler Proxy vor Bedrock weiterhin eine gültige Option. - - OpenClaw unterstützt **OpenAI Code (Codex)** über OAuth (ChatGPT-Anmeldung). Das Onboarding kann den OAuth-Ablauf ausführen und setzt das Standardmodell bei Bedarf auf `openai-codex/gpt-5.4`. Siehe [Model providers](/de/concepts/model-providers) und [Onboarding (CLI)](/de/start/wizard). + + OpenClaw unterstützt **OpenAI Code (Codex)** über OAuth (ChatGPT-Anmeldung). Das Onboarding kann den OAuth-Ablauf ausführen und setzt das Standardmodell bei Bedarf auf `openai-codex/gpt-5.4`. Siehe [Modell-Provider](/de/concepts/model-providers) und [Onboarding (CLI)](/de/start/wizard). OpenClaw behandelt die beiden Wege getrennt: - - `openai-codex/gpt-5.4` = ChatGPT/Codex-OAuth + - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth - `openai/gpt-5.4` = direkte OpenAI-Platform-API - In OpenClaw ist die ChatGPT/Codex-Anmeldung an den Pfad `openai-codex/*` gebunden, - nicht an den direkten Pfad `openai/*`. Wenn Sie den direkten API-Pfad in + In OpenClaw ist die ChatGPT/Codex-Anmeldung mit dem `openai-codex/*`-Pfad verknüpft, + nicht mit dem direkten `openai/*`-Pfad. Wenn Sie den direkten API-Pfad in OpenClaw möchten, setzen Sie `OPENAI_API_KEY` (oder die entsprechende OpenAI-Provider-Konfiguration). - Wenn Sie ChatGPT/Codex-Anmeldung in OpenClaw möchten, verwenden Sie `openai-codex/*`. + Wenn Sie die ChatGPT/Codex-Anmeldung in OpenClaw möchten, verwenden Sie `openai-codex/*`. `openai-codex/*` verwendet den Codex-OAuth-Pfad, und seine nutzbaren Kontingentfenster werden - von OpenAI verwaltet und hängen vom Tarif ab. In der Praxis können sich diese Limits von - der Erfahrung auf der ChatGPT-Website/App unterscheiden, selbst wenn beide mit demselben Konto verknüpft sind. + von OpenAI verwaltet und hängen vom Tarif ab. In der Praxis können sich diese Limits von der + ChatGPT-Website-/App-Erfahrung unterscheiden, selbst wenn beide an dasselbe Konto gebunden sind. - OpenClaw kann die aktuell sichtbaren Nutzungs-/Kontingentfenster des Providers in + OpenClaw kann die aktuell sichtbaren Provider-Nutzungs-/Kontingentfenster in `openclaw models status` anzeigen, erfindet oder normalisiert aber keine ChatGPT-Web- - Berechtigungen zu direktem API-Zugriff um. Wenn Sie den direkten OpenAI-Platform- + Berechtigungen zu direktem API-Zugriff. Wenn Sie den direkten OpenAI-Platform- Abrechnungs-/Limitpfad möchten, verwenden Sie `openai/*` mit einem API-Schlüssel. - - Ja. OpenClaw unterstützt **OpenAI Code (Codex) Abonnement-OAuth** vollständig. - OpenAI erlaubt die Nutzung von Abonnement-OAuth in externen Tools/Workflows - wie OpenClaw ausdrücklich. Das Onboarding kann den OAuth-Ablauf für Sie ausführen. + + Ja. OpenClaw unterstützt **OpenAI Code (Codex) subscription OAuth** vollständig. + OpenAI erlaubt die Nutzung von subscription OAuth ausdrücklich in externen Werkzeugen/Workflows + wie OpenClaw. Das Onboarding kann den OAuth-Ablauf für Sie ausführen. - Siehe [OAuth](/de/concepts/oauth), [Model providers](/de/concepts/model-providers) und [Onboarding (CLI)](/de/start/wizard). + Siehe [OAuth](/de/concepts/oauth), [Modell-Provider](/de/concepts/model-providers) und [Onboarding (CLI)](/de/start/wizard). - Gemini CLI verwendet einen **Plugin-Authentifizierungsablauf**, keine Client-ID und kein Secret in `openclaw.json`. + Gemini CLI verwendet einen **Plugin-Auth-Ablauf**, keine Client-ID oder kein Secret in `openclaw.json`. Schritte: - 1. Installieren Sie Gemini CLI lokal, sodass `gemini` im `PATH` liegt + 1. Installieren Sie Gemini CLI lokal, sodass `gemini` auf `PATH` liegt - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` 2. Aktivieren Sie das Plugin: `openclaw plugins enable google` @@ -711,62 +711,62 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. 4. Standardmodell nach der Anmeldung: `google-gemini-cli/gemini-3-flash-preview` 5. Wenn Anfragen fehlschlagen, setzen Sie `GOOGLE_CLOUD_PROJECT` oder `GOOGLE_CLOUD_PROJECT_ID` auf dem Gateway-Host - Dadurch werden OAuth-Tokens in Auth-Profilen auf dem Gateway-Host gespeichert. Details: [Model providers](/de/concepts/model-providers). + Dadurch werden OAuth-Tokens in Auth-Profilen auf dem Gateway-Host gespeichert. Details: [Modell-Provider](/de/concepts/model-providers). - - Normalerweise nein. OpenClaw benötigt großen Kontext + starke Sicherheit; kleine Karten kürzen ab und lecken. Wenn Sie unbedingt müssen, führen Sie den **größten** Modell-Build lokal aus, den Sie können (LM Studio), und siehe [/gateway/local-models](/de/gateway/local-models). Kleinere/quantisierte Modelle erhöhen das Risiko von Prompt Injection – siehe [Security](/de/gateway/security). + + Meistens nein. OpenClaw braucht großen Kontext + starke Sicherheit; kleine Karten kürzen ab und leaken. Wenn Sie es unbedingt möchten, führen Sie lokal den **größten** Modell-Build aus, den Sie können (LM Studio), und siehe [/gateway/local-models](/de/gateway/local-models). Kleinere/quantisierte Modelle erhöhen das Risiko für Prompt Injection – siehe [Sicherheit](/de/gateway/security). - - Wählen Sie regiongebundene Endpunkte. OpenRouter bietet in den USA gehostete Optionen für MiniMax, Kimi und GLM; wählen Sie die in den USA gehostete Variante, um Daten in der Region zu halten. Sie können weiterhin Anthropic/OpenAI daneben auflisten, indem Sie `models.mode: "merge"` verwenden, sodass Fallbacks verfügbar bleiben und gleichzeitig der von Ihnen ausgewählte regiongebundene Provider respektiert wird. + + Wählen Sie regiongebundene Endpunkte. OpenRouter bietet in den USA gehostete Optionen für MiniMax, Kimi und GLM; wählen Sie die in den USA gehostete Variante, um Daten in der Region zu halten. Sie können Anthropic/OpenAI weiterhin daneben auflisten, indem Sie `models.mode: "merge"` verwenden, sodass Fallbacks verfügbar bleiben, während der von Ihnen gewählte regiongebundene Provider eingehalten wird. - Nein. OpenClaw läuft auf macOS oder Linux (Windows über WSL2). Ein Mac mini ist optional – manche Leute + Nein. OpenClaw läuft unter macOS oder Linux (Windows über WSL2). Ein Mac mini ist optional – manche Leute kaufen einen als Always-on-Host, aber auch ein kleiner VPS, Homeserver oder eine Box in Raspberry-Pi-Klasse funktioniert. - Sie benötigen nur für **nur-macOS-Tools** einen Mac. Für iMessage verwenden Sie [BlueBubbles](/de/channels/bluebubbles) (empfohlen) – der BlueBubbles-Server läuft auf jedem Mac, und das Gateway kann auf Linux oder anderswo laufen. Wenn Sie andere nur-macOS-Tools möchten, führen Sie das Gateway auf einem Mac aus oder koppeln Sie einen macOS-Node. + Sie brauchen einen Mac nur **für rein macOS-spezifische Werkzeuge**. Für iMessage verwenden Sie [BlueBubbles](/de/channels/bluebubbles) (empfohlen) – der BlueBubbles-Server läuft auf jedem Mac, und das Gateway kann unter Linux oder anderswo laufen. Wenn Sie andere rein macOS-spezifische Werkzeuge möchten, führen Sie das Gateway auf einem Mac aus oder koppeln Sie einen macOS Node. - Docs: [BlueBubbles](/de/channels/bluebubbles), [Nodes](/de/nodes), [Mac remote mode](/de/platforms/mac/remote). + Dokumentation: [BlueBubbles](/de/channels/bluebubbles), [Nodes](/de/nodes), [Mac-Remote-Modus](/de/platforms/mac/remote). - Sie benötigen **irgendein macOS-Gerät**, das bei Messages angemeldet ist. Es muss **kein** Mac mini sein – - jeder Mac funktioniert. **Verwenden Sie [BlueBubbles](/de/channels/bluebubbles)** (empfohlen) für iMessage – der BlueBubbles-Server läuft auf macOS, während das Gateway auf Linux oder anderswo laufen kann. + Sie brauchen **irgendein macOS-Gerät**, das bei Messages angemeldet ist. Es muss **kein** Mac mini sein – + jeder Mac funktioniert. Verwenden Sie für iMessage **[BlueBubbles](/de/channels/bluebubbles)** (empfohlen) – der BlueBubbles-Server läuft unter macOS, während das Gateway unter Linux oder anderswo laufen kann. Häufige Setups: - Führen Sie das Gateway auf Linux/VPS aus und den BlueBubbles-Server auf einem beliebigen Mac, der bei Messages angemeldet ist. - - Führen Sie alles auf dem Mac aus, wenn Sie das einfachste Einzelrechner-Setup möchten. + - Führen Sie alles auf dem Mac aus, wenn Sie das einfachste Single-Machine-Setup möchten. - Docs: [BlueBubbles](/de/channels/bluebubbles), [Nodes](/de/nodes), - [Mac remote mode](/de/platforms/mac/remote). + Dokumentation: [BlueBubbles](/de/channels/bluebubbles), [Nodes](/de/nodes), + [Mac-Remote-Modus](/de/platforms/mac/remote). - + Ja. Der **Mac mini kann das Gateway ausführen**, und Ihr MacBook Pro kann sich als **Node** (Begleitgerät) verbinden. Nodes führen das Gateway nicht aus – sie stellen zusätzliche Fähigkeiten wie Bildschirm/Kamera/Canvas und `system.run` auf diesem Gerät bereit. Häufiges Muster: - - Gateway auf dem Mac mini (always-on). + - Gateway auf dem Mac mini (Always-on). - Das MacBook Pro führt die macOS-App oder einen Node-Host aus und koppelt sich mit dem Gateway. - Verwenden Sie `openclaw nodes status` / `openclaw nodes list`, um es anzuzeigen. - Docs: [Nodes](/de/nodes), [Nodes CLI](/cli/nodes). + Dokumentation: [Nodes](/de/nodes), [Nodes CLI](/cli/nodes). - Bun wird **nicht empfohlen**. Wir sehen Laufzeitfehler, insbesondere mit WhatsApp und Telegram. + Bun wird **nicht empfohlen**. Wir sehen Laufzeitfehler, besonders mit WhatsApp und Telegram. Verwenden Sie **Node** für stabile Gateways. - Wenn Sie trotzdem mit Bun experimentieren möchten, tun Sie das auf einem nicht produktiven Gateway + Wenn Sie trotzdem mit Bun experimentieren möchten, tun Sie das auf einem Nicht-Produktions-Gateway ohne WhatsApp/Telegram. @@ -774,7 +774,7 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. `channels.telegram.allowFrom` ist **die Telegram-Benutzer-ID des menschlichen Absenders** (numerisch). Es ist nicht der Bot-Benutzername. - Das Setup fragt nur nach numerischen Benutzer-IDs. Wenn Sie bereits alte `@username`-Einträge in der Konfiguration haben, kann `openclaw doctor --fix` versuchen, sie aufzulösen. + Beim Setup werden nur numerische Benutzer-IDs abgefragt. Wenn Sie bereits ältere `@username`-Einträge in der Konfiguration haben, kann `openclaw doctor --fix` versuchen, sie aufzulösen. Sicherer (kein Drittanbieter-Bot): @@ -786,22 +786,22 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Drittanbieter (weniger privat): - - Senden Sie eine DM an `@userinfobot` oder `@getidsbot`. + - Senden Sie `@userinfobot` oder `@getidsbot` eine DM. Siehe [/channels/telegram](/de/channels/telegram#access-control-and-activation). - Ja, über **Multi-Agent Routing**. Binden Sie die WhatsApp-**DM** jedes Absenders (Peer `kind: "direct"`, Absender-E.164 wie `+15551234567`) an eine andere `agentId`, sodass jede Person ihren eigenen Workspace und Sitzungsspeicher erhält. Antworten kommen weiterhin vom **gleichen WhatsApp-Konto**, und die DM-Zugriffskontrolle (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) gilt global pro WhatsApp-Konto. Siehe [Multi-Agent Routing](/de/concepts/multi-agent) und [WhatsApp](/de/channels/whatsapp). + Ja, über **Multi-Agent-Routing**. Binden Sie die WhatsApp-**DM** jedes Absenders (Peer `kind: "direct"`, Absender-E.164 wie `+15551234567`) an eine andere `agentId`, damit jede Person ihren eigenen Workspace und Sitzungsspeicher erhält. Antworten kommen weiterhin vom **gleichen WhatsApp-Konto**, und die DM-Zugriffskontrolle (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) ist global pro WhatsApp-Konto. Siehe [Multi-Agent-Routing](/de/concepts/multi-agent) und [WhatsApp](/de/channels/whatsapp). - - Ja. Verwenden Sie Multi-Agent Routing: Geben Sie jedem Agenten sein eigenes Standardmodell und binden Sie dann eingehende Routen (Provider-Konto oder bestimmte Peers) an jeden Agenten. Eine Beispielkonfiguration finden Sie unter [Multi-Agent Routing](/de/concepts/multi-agent). Siehe auch [Models](/de/concepts/models) und [Configuration](/de/gateway/configuration). + + Ja. Verwenden Sie Multi-Agent-Routing: Geben Sie jedem Agenten sein eigenes Standardmodell und binden Sie dann eingehende Routen (Provider-Konto oder bestimmte Peers) an jeden Agenten. Beispielkonfigurationen finden Sie unter [Multi-Agent Routing](/de/concepts/multi-agent). Siehe auch [Models](/de/concepts/models) und [Configuration](/de/gateway/configuration). - Ja. Homebrew unterstützt Linux (Linuxbrew). Schnelle Einrichtung: + Ja. Homebrew unterstützt Linux (Linuxbrew). Schnelles Setup: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -810,25 +810,25 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. brew install ``` - Wenn Sie OpenClaw über systemd ausführen, stellen Sie sicher, dass der Service-PATH `/home/linuxbrew/.linuxbrew/bin` (oder Ihr brew-Präfix) enthält, damit mit `brew` installierte Tools in Nicht-Login-Shells aufgelöst werden. - Neuere Builds stellen unter Linux-systemd-Services auch gängige Benutzer-bin-Verzeichnisse voran (zum Beispiel `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) und berücksichtigen `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` und `FNM_DIR`, wenn gesetzt. + Wenn Sie OpenClaw über systemd ausführen, stellen Sie sicher, dass der PATH des Service `/home/linuxbrew/.linuxbrew/bin` (oder Ihr brew-Präfix) enthält, damit mit `brew` installierte Werkzeuge in Non-Login-Shells aufgelöst werden. + Neuere Builds stellen unter Linux-systemd-Services außerdem gängige Benutzer-bin-Verzeichnisse voran (zum Beispiel `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) und berücksichtigen `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` und `FNM_DIR`, wenn sie gesetzt sind. - - **Hackbare (git)-Installation:** vollständiger Quellcode-Checkout, bearbeitbar, am besten für Mitwirkende. - Sie bauen lokal und können Code/Docs patchen. - - **npm install:** globale CLI-Installation, kein Repo, am besten für „einfach nur ausführen“. - Updates kommen über npm dist-tags. + - **Hackbare (git-)Installation:** vollständiger Quellcode-Checkout, bearbeitbar, am besten für Mitwirkende. + Sie führen Builds lokal aus und können Code/Dokumentation patchen. + - **npm install:** globale CLI-Installation, kein Repository, am besten für „einfach nur ausführen“. + Updates kommen über npm-dist-tags. - Docs: [Getting started](/de/start/getting-started), [Updating](/de/install/updating). + Dokumentation: [Erste Schritte](/de/start/getting-started), [Aktualisieren](/de/install/updating). Ja. Installieren Sie die andere Variante und führen Sie dann Doctor aus, damit der Gateway-Service auf den neuen Einstiegspunkt zeigt. - Dadurch werden **Ihre Daten nicht gelöscht** – es wird nur die OpenClaw-Codeinstallation geändert. Ihr Status - (`~/.openclaw`) und Ihr Workspace (`~/.openclaw/workspace`) bleiben unberührt. + Dadurch werden Ihre Daten **nicht gelöscht** – es ändert nur die OpenClaw-Code-Installation. Ihr Zustand + (`~/.openclaw`) und Workspace (`~/.openclaw/workspace`) bleiben unberührt. Von npm zu git: @@ -849,68 +849,68 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. openclaw gateway restart ``` - Doctor erkennt einen Mismatch beim Einstiegspunkt des Gateway-Service und bietet an, die Service-Konfiguration passend zur aktuellen Installation umzuschreiben (verwenden Sie `--repair` in der Automatisierung). + Doctor erkennt einen Einstiegspunkt-Mismatch des Gateway-Service und bietet an, die Service-Konfiguration so umzuschreiben, dass sie zur aktuellen Installation passt (verwenden Sie `--repair` in der Automatisierung). - Backup-Tipps: siehe [Backup strategy](#where-things-live-on-disk). + Backup-Tipps: siehe [Backup-Strategie](#where-things-live-on-disk). - - Kurz gesagt: **Wenn Sie 24/7-Zuverlässigkeit möchten, verwenden Sie einen VPS**. Wenn Sie die - geringste Reibung möchten und Schlafmodus/Neustarts okay sind, führen Sie es lokal aus. + + Kurzantwort: **Wenn Sie 24/7-Zuverlässigkeit möchten, verwenden Sie einen VPS**. Wenn Sie den + geringsten Aufwand möchten und Schlafmodus/Neustarts in Ordnung sind, führen Sie es lokal aus. **Laptop (lokales Gateway)** - - **Vorteile:** keine Serverkosten, direkter Zugriff auf lokale Dateien, sichtbares Browserfenster. - - **Nachteile:** Schlafmodus/Netzausfälle = Verbindungsabbrüche, Betriebssystem-Updates/Neustarts unterbrechen, Rechner muss wach bleiben. + - **Vorteile:** keine Serverkosten, direkter Zugriff auf lokale Dateien, sichtbares Browserfenster in Echtzeit. + - **Nachteile:** Schlafmodus/Netzwerkabbrüche = Verbindungsabbrüche, Betriebssystem-Updates/Neustarts unterbrechen, muss wach bleiben. **VPS / Cloud** - - **Vorteile:** always-on, stabiles Netzwerk, keine Probleme durch Laptop-Schlafmodus, leichter dauerhaft am Laufen zu halten. - - **Nachteile:** oft headless betrieben (Screenshots verwenden), nur Remote-Dateizugriff, Sie müssen sich für Updates per SSH verbinden. + - **Vorteile:** immer an, stabiles Netzwerk, keine Probleme durch Laptop-Schlafmodus, leichter dauerhaft am Laufen zu halten. + - **Nachteile:** läuft oft headless (verwenden Sie Screenshots), nur Remote-Dateizugriff, Sie müssen für Updates SSH verwenden. - **OpenClaw-spezifischer Hinweis:** WhatsApp/Telegram/Slack/Mattermost/Discord funktionieren alle problemlos auf einem VPS. Der einzige echte Trade-off ist **headless browser** vs. sichtbares Fenster. Siehe [Browser](/de/tools/browser). + **OpenClaw-spezifischer Hinweis:** WhatsApp/Telegram/Slack/Mattermost/Discord funktionieren alle problemlos auf einem VPS. Der einzige echte Kompromiss ist **headless browser** gegenüber einem sichtbaren Fenster. Siehe [Browser](/de/tools/browser). - **Empfohlener Standard:** VPS, wenn Sie zuvor Gateway-Verbindungsabbrüche hatten. Lokal ist großartig, wenn Sie den Mac aktiv nutzen und lokalen Dateizugriff oder UI-Automatisierung mit sichtbarem Browser wollen. + **Empfohlener Standard:** VPS, wenn Sie zuvor Gateway-Verbindungsabbrüche hatten. Lokal ist großartig, wenn Sie den Mac aktiv verwenden und lokalen Dateizugriff oder UI-Automatisierung mit sichtbarem Browser möchten. - + Nicht erforderlich, aber **für Zuverlässigkeit und Isolation empfohlen**. - - **Dedizierter Host (VPS/Mac mini/Pi):** always-on, weniger Unterbrechungen durch Schlafmodus/Neustarts, sauberere Berechtigungen, leichter dauerhaft am Laufen zu halten. - - **Gemeinsam genutzter Laptop/Desktop:** völlig in Ordnung zum Testen und für aktive Nutzung, aber rechnen Sie mit Pausen, wenn der Rechner schläft oder Updates ausführt. + - **Dedizierter Host (VPS/Mac mini/Pi):** immer an, weniger Unterbrechungen durch Schlafmodus/Neustarts, sauberere Berechtigungen, leichter am Laufen zu halten. + - **Gemeinsam genutzter Laptop/Desktop:** völlig in Ordnung für Tests und aktive Nutzung, aber rechnen Sie mit Pausen, wenn die Maschine schläft oder Updates installiert. - Wenn Sie das Beste aus beiden Welten möchten, behalten Sie das Gateway auf einem dedizierten Host und koppeln Sie Ihren Laptop als **Node** für lokale Bildschirm-/Kamera-/Exec-Tools. Siehe [Nodes](/de/nodes). - Für Sicherheitshinweise lesen Sie [Security](/de/gateway/security). + Wenn Sie das Beste aus beiden Welten möchten, behalten Sie das Gateway auf einem dedizierten Host und koppeln Sie Ihren Laptop als **Node** für lokale Bildschirm-/Kamera-/exec-Werkzeuge. Siehe [Nodes](/de/nodes). + Sicherheitshinweise finden Sie unter [Sicherheit](/de/gateway/security). - - OpenClaw ist leichtgewichtig. Für ein einfaches Gateway + einen Chat-Kanal: + + OpenClaw ist leichtgewichtig. Für ein grundlegendes Gateway + einen Chat-Kanal: - - **Absolutes Minimum:** 1 vCPU, 1GB RAM, ~500MB Festplatte. - - **Empfohlen:** 1–2 vCPU, 2GB RAM oder mehr als Reserve (Logs, Medien, mehrere Kanäle). Node-Tools und Browser-Automatisierung können ressourcenhungrig sein. + - **Absolutes Minimum:** 1 vCPU, 1 GB RAM, ~500 MB Speicherplatz. + - **Empfohlen:** 1–2 vCPU, 2 GB RAM oder mehr als Spielraum (Logs, Medien, mehrere Kanäle). Node-Werkzeuge und Browser-Automatisierung können ressourcenhungrig sein. Betriebssystem: Verwenden Sie **Ubuntu LTS** (oder ein anderes modernes Debian/Ubuntu). Der Linux-Installationspfad ist dort am besten getestet. - Docs: [Linux](/de/platforms/linux), [VPS hosting](/de/vps). + Dokumentation: [Linux](/de/platforms/linux), [VPS-Hosting](/de/vps). - Ja. Behandeln Sie eine VM wie einen VPS: Sie muss immer eingeschaltet, erreichbar und mit genug + Ja. Behandeln Sie eine VM wie einen VPS: Sie muss immer eingeschaltet, erreichbar und mit ausreichend RAM für das Gateway und alle aktivierten Kanäle ausgestattet sein. - Grundlegende Orientierung: + Grundlegende Richtwerte: - - **Absolutes Minimum:** 1 vCPU, 1GB RAM. - - **Empfohlen:** 2GB RAM oder mehr, wenn Sie mehrere Kanäle, Browser-Automatisierung oder Medientools ausführen. + - **Absolutes Minimum:** 1 vCPU, 1 GB RAM. + - **Empfohlen:** 2 GB RAM oder mehr, wenn Sie mehrere Kanäle, Browser-Automatisierung oder Medienwerkzeuge ausführen. - **Betriebssystem:** Ubuntu LTS oder ein anderes modernes Debian/Ubuntu. - Wenn Sie unter Windows sind, ist **WSL2 das einfachste VM-artige Setup** und hat die beste Tooling- - Kompatibilität. Siehe [Windows](/de/platforms/windows), [VPS hosting](/de/vps). - Wenn Sie macOS in einer VM ausführen, siehe [macOS VM](/de/install/macos-vm). + Wenn Sie unter Windows arbeiten, ist **WSL2 das einfachste VM-ähnliche Setup** und hat die beste + Werkzeugkompatibilität. Siehe [Windows](/de/platforms/windows), [VPS-Hosting](/de/vps). + Wenn Sie macOS in einer VM ausführen, siehe [macOS-VM](/de/install/macos-vm). @@ -919,29 +919,29 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - OpenClaw ist ein persönlicher KI-Assistent, den Sie auf Ihren eigenen Geräten ausführen. Er antwortet auf den Messaging-Oberflächen, die Sie bereits nutzen (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat und gebündelte Kanal-Plugins wie QQ Bot) und kann auf unterstützten Plattformen auch Sprache + ein Live-Canvas bereitstellen. Das **Gateway** ist die always-on Control Plane; der Assistent ist das Produkt. + OpenClaw ist ein persönlicher KI-Assistent, den Sie auf Ihren eigenen Geräten ausführen. Er antwortet auf den Messaging-Oberflächen, die Sie bereits verwenden (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat und gebündelte Kanal-Plugins wie QQ Bot) und kann auf unterstützten Plattformen auch Sprache + ein Live-Canvas nutzen. Das **Gateway** ist die immer aktive Steuerungsebene; der Assistent ist das Produkt. - OpenClaw ist nicht „nur ein Claude-Wrapper“. Es ist eine **local-first Control Plane**, mit der Sie einen - leistungsfähigen Assistenten auf **Ihrer eigenen Hardware** ausführen können, erreichbar über die Chat-Apps, die Sie bereits nutzen, mit - zustandsbehafteten Sitzungen, Memory und Tools – ohne die Kontrolle über Ihre Workflows an ein gehostetes + OpenClaw ist nicht „nur ein Claude-Wrapper“. Es ist eine **Local-First-Steuerungsebene**, mit der Sie einen + leistungsfähigen Assistenten auf **Ihrer eigenen Hardware** ausführen können, erreichbar aus den Chat-Apps, die Sie bereits verwenden, mit + zustandsbehafteten Sitzungen, Memory und Werkzeugen – ohne die Kontrolle über Ihre Workflows an ein gehostetes SaaS abzugeben. Highlights: - - **Ihre Geräte, Ihre Daten:** Führen Sie das Gateway aus, wo immer Sie möchten (Mac, Linux, VPS) und behalten Sie + - **Ihre Geräte, Ihre Daten:** Führen Sie das Gateway aus, wo immer Sie möchten (Mac, Linux, VPS), und behalten Sie Workspace + Sitzungsverlauf lokal. - - **Echte Kanäle, keine Web-Sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/usw., + - **Echte Kanäle, keine Web-Sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc., plus mobile Sprache und Canvas auf unterstützten Plattformen. - - **Modellagnostisch:** Verwenden Sie Anthropic, OpenAI, MiniMax, OpenRouter usw. mit agentenspezifischem Routing + - **Modellagnostisch:** Verwenden Sie Anthropic, OpenAI, MiniMax, OpenRouter usw. mit agentenbezogenem Routing und Failover. - - **Rein lokale Option:** Führen Sie lokale Modelle aus, sodass **alle Daten auf Ihrem Gerät bleiben können**, wenn Sie möchten. - - **Multi-Agent Routing:** separate Agenten pro Kanal, Konto oder Aufgabe, jeweils mit eigenem + - **Nur-lokal-Option:** Führen Sie lokale Modelle aus, sodass **alle Daten auf Ihrem Gerät bleiben können**, wenn Sie möchten. + - **Multi-Agent-Routing:** Separate Agenten pro Kanal, Konto oder Aufgabe, jeweils mit eigenem Workspace und Standardwerten. - - **Open Source und hackbar:** prüfen, erweitern und selbst hosten ohne Vendor Lock-in. + - **Open Source und hackbar:** Prüfen, erweitern und selbst hosten ohne Vendor Lock-in. - Docs: [Gateway](/de/gateway), [Channels](/de/channels), [Multi-agent](/de/concepts/multi-agent), + Dokumentation: [Gateway](/de/gateway), [Kanäle](/de/channels), [Multi-Agent](/de/concepts/multi-agent), [Memory](/de/concepts/memory). @@ -950,50 +950,49 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Gute erste Projekte: - Eine Website bauen (WordPress, Shopify oder eine einfache statische Website). - - Eine Mobile-App prototypisieren (Gliederung, Screens, API-Plan). - - Dateien und Ordner organisieren (Aufräumen, Benennung, Tagging). + - Eine mobile App prototypen (Struktur, Screens, API-Plan). + - Dateien und Ordner organisieren (Aufräumen, Benennen, Taggen). - Gmail verbinden und Zusammenfassungen oder Follow-ups automatisieren. Es kann große Aufgaben bewältigen, funktioniert aber am besten, wenn Sie sie in Phasen aufteilen und - Sub-Agents für parallele Arbeit verwenden. + Sub-Agenten für parallele Arbeit verwenden. - - Alltägliche Erfolge sehen normalerweise so aus: + + Alltägliche Erfolge sehen meistens so aus: - - **Persönliche Briefings:** Zusammenfassungen von Posteingang, Kalender und Nachrichten, die Sie interessieren. - - **Recherche und Entwürfe:** schnelle Recherche, Zusammenfassungen und erste Entwürfe für E-Mails oder Docs. - - **Erinnerungen und Follow-ups:** Cron- oder Heartbeat-gesteuerte Nudges und Checklisten. - - **Browser-Automatisierung:** Formulare ausfüllen, Daten sammeln und Web-Aufgaben wiederholen. + - **Persönliche Briefings:** Zusammenfassungen von Inbox, Kalender und Nachrichten, die Sie interessieren. + - **Recherche und Entwürfe:** Schnelle Recherche, Zusammenfassungen und erste Entwürfe für E-Mails oder Dokumente. + - **Erinnerungen und Follow-ups:** Durch Cron oder Heartbeat gesteuerte Erinnerungen und Checklisten. + - **Browser-Automatisierung:** Formulare ausfüllen, Daten sammeln und Webaufgaben wiederholen. - **Geräteübergreifende Koordination:** Senden Sie eine Aufgabe von Ihrem Telefon, lassen Sie das Gateway sie auf einem Server ausführen und erhalten Sie das Ergebnis im Chat zurück. - - Ja für **Recherche, Qualifizierung und Entwürfe**. Es kann Websites scannen, Shortlists erstellen, - Interessenten zusammenfassen und Outreach- oder Ad-Copy-Entwürfe schreiben. + + Ja, für **Recherche, Qualifizierung und Entwürfe**. Es kann Websites scannen, Shortlists erstellen, + Interessenten zusammenfassen und Entwürfe für Outreach- oder Werbetexte schreiben. - Für **Outreach oder Ad-Läufe** sollte ein Mensch eingebunden bleiben. Vermeiden Sie Spam, befolgen Sie lokale Gesetze und - Plattformrichtlinien und prüfen Sie alles, bevor es versendet wird. Das sicherste Muster ist, dass - OpenClaw entwirft und Sie freigeben. + Für **Outreach oder Werbekampagnen** sollten Menschen eingebunden bleiben. Vermeiden Sie Spam, befolgen Sie lokale Gesetze und + Plattformrichtlinien und prüfen Sie alles, bevor es versendet wird. Das sicherste Muster ist, OpenClaw entwerfen zu lassen und Sie genehmigen. - Docs: [Security](/de/gateway/security). + Dokumentation: [Sicherheit](/de/gateway/security). - - OpenClaw ist ein **persönlicher Assistent** und eine Koordinationsschicht, kein IDE-Ersatz. Verwenden Sie - Claude Code oder Codex für den schnellsten direkten Coding-Loop innerhalb eines Repos. Verwenden Sie OpenClaw, wenn Sie - dauerhaftes Memory, geräteübergreifenden Zugriff und Tool-Orchestrierung möchten. + + OpenClaw ist ein **persönlicher Assistent** und eine Koordinationsebene, kein IDE-Ersatz. Verwenden Sie + Claude Code oder Codex für die schnellste direkte Coding-Schleife in einem Repository. Verwenden Sie OpenClaw, wenn Sie + dauerhaftes Memory, geräteübergreifenden Zugriff und Werkzeugorchestrierung möchten. Vorteile: - **Persistentes Memory + Workspace** über Sitzungen hinweg - **Plattformübergreifender Zugriff** (WhatsApp, Telegram, TUI, WebChat) - - **Tool-Orchestrierung** (Browser, Dateien, Planung, Hooks) - - **Always-on Gateway** (auf einem VPS ausführen, von überall interagieren) - - **Nodes** für lokalen Browser/Bildschirm/Kamera/Exec + - **Werkzeugorchestrierung** (Browser, Dateien, Planung, Hooks) + - **Immer aktives Gateway** (auf einem VPS ausführen, von überall interagieren) + - **Nodes** für lokalen Browser/Bildschirm/Kamera/exec Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1003,77 +1002,77 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. ## Skills und Automatisierung - - Verwenden Sie verwaltete Überschreibungen, statt die Repo-Kopie zu bearbeiten. Legen Sie Ihre Änderungen in `~/.openclaw/skills//SKILL.md` ab (oder fügen Sie über `skills.load.extraDirs` in `~/.openclaw/openclaw.json` einen Ordner hinzu). Die Priorität ist `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → gebündelt → `skills.load.extraDirs`, sodass verwaltete Überschreibungen weiterhin Vorrang vor gebündelten Skills haben, ohne git zu berühren. Wenn der Skill global installiert sein soll, aber nur für einige Agenten sichtbar, behalten Sie die gemeinsame Kopie in `~/.openclaw/skills` und steuern Sie die Sichtbarkeit mit `agents.defaults.skills` und `agents.list[].skills`. Nur Änderungen, die upstream-würdig sind, sollten im Repo liegen und als PRs hinausgehen. + + Verwenden Sie verwaltete Überschreibungen statt die Kopie im Repository zu bearbeiten. Legen Sie Ihre Änderungen in `~/.openclaw/skills//SKILL.md` ab (oder fügen Sie über `skills.load.extraDirs` in `~/.openclaw/openclaw.json` einen Ordner hinzu). Die Priorität ist `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → gebündelt → `skills.load.extraDirs`, sodass verwaltete Überschreibungen weiterhin vor gebündelten Skills gewinnen, ohne git zu berühren. Wenn Sie den Skill global installiert brauchen, aber nur für einige Agenten sichtbar machen wollen, behalten Sie die gemeinsame Kopie in `~/.openclaw/skills` und steuern Sie die Sichtbarkeit mit `agents.defaults.skills` und `agents.list[].skills`. Nur Änderungen, die upstream-tauglich sind, sollten im Repository leben und als PR eingereicht werden. - Ja. Fügen Sie zusätzliche Verzeichnisse über `skills.load.extraDirs` in `~/.openclaw/openclaw.json` hinzu (niedrigste Priorität). Die Standardpriorität ist `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → gebündelt → `skills.load.extraDirs`. `clawhub` installiert standardmäßig nach `./skills`, was OpenClaw in der nächsten Sitzung als `/skills` behandelt. Wenn der Skill nur für bestimmte Agenten sichtbar sein soll, kombinieren Sie das mit `agents.defaults.skills` oder `agents.list[].skills`. + Ja. Fügen Sie zusätzliche Verzeichnisse über `skills.load.extraDirs` in `~/.openclaw/openclaw.json` hinzu (niedrigste Priorität). Die Standardpriorität ist `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → gebündelt → `skills.load.extraDirs`. `clawhub` installiert standardmäßig in `./skills`, was OpenClaw in der nächsten Sitzung als `/skills` behandelt. Wenn der Skill nur für bestimmte Agenten sichtbar sein soll, kombinieren Sie das mit `agents.defaults.skills` oder `agents.list[].skills`. - Heute sind die unterstützten Muster: + Heute werden folgende Muster unterstützt: - - **Cron-Jobs**: isolierte Jobs können pro Job ein `model`-Override setzen. - - **Sub-Agents**: leiten Sie Aufgaben an separate Agenten mit unterschiedlichen Standardmodellen weiter. - - **On-demand-Wechsel**: Verwenden Sie `/model`, um das Modell der aktuellen Sitzung jederzeit zu wechseln. + - **Cron-Jobs**: Isolierte Jobs können pro Job ein `model`-Override setzen. + - **Sub-Agenten**: Leiten Sie Aufgaben an separate Agenten mit unterschiedlichen Standardmodellen weiter. + - **On-Demand-Wechsel**: Verwenden Sie `/model`, um das aktuelle Sitzungsmodell jederzeit zu wechseln. - Siehe [Cron-Jobs](/de/automation/cron-jobs), [Multi-Agent Routing](/de/concepts/multi-agent) und [Slash commands](/de/tools/slash-commands). + Siehe [Cron-Jobs](/de/automation/cron-jobs), [Multi-Agent-Routing](/de/concepts/multi-agent) und [Slash-Befehle](/de/tools/slash-commands). - Verwenden Sie **Sub-Agents** für lange oder parallele Aufgaben. Sub-Agents laufen in ihrer eigenen Sitzung, + Verwenden Sie **Sub-Agenten** für lange oder parallele Aufgaben. Sub-Agenten laufen in ihrer eigenen Sitzung, geben eine Zusammenfassung zurück und halten Ihren Hauptchat reaktionsfähig. - Bitten Sie Ihren Bot, „einen Sub-Agenten für diese Aufgabe zu starten“, oder verwenden Sie `/subagents`. - Verwenden Sie `/status` im Chat, um zu sehen, was das Gateway gerade tut (und ob es beschäftigt ist). + Bitten Sie Ihren Bot, „für diese Aufgabe einen Sub-Agenten zu starten“, oder verwenden Sie `/subagents`. + Verwenden Sie `/status` im Chat, um zu sehen, was das Gateway gerade tut (und ob es ausgelastet ist). - Token-Tipp: Lange Aufgaben und Sub-Agents verbrauchen beide Tokens. Wenn Kosten ein Problem sind, setzen Sie ein - günstigeres Modell für Sub-Agents über `agents.defaults.subagents.model`. + Token-Tipp: Sowohl lange Aufgaben als auch Sub-Agenten verbrauchen Tokens. Wenn Kosten ein Thema sind, setzen Sie ein + günstigeres Modell für Sub-Agenten über `agents.defaults.subagents.model`. - Docs: [Sub-agents](/de/tools/subagents), [Background Tasks](/de/automation/tasks). + Dokumentation: [Sub-Agenten](/de/tools/subagents), [Hintergrundaufgaben](/de/automation/tasks). - - Verwenden Sie Thread-Bindings. Sie können einen Discord-Thread an einen Sub-Agenten oder ein Sitzungsziel binden, sodass Follow-up-Nachrichten in diesem Thread auf dieser gebundenen Sitzung bleiben. + + Verwenden Sie Thread-Bindungen. Sie können einen Discord-Thread an ein Subagent- oder Sitzungsziel binden, sodass Folgemeldungen in diesem Thread auf dieser gebundenen Sitzung bleiben. - Grundlegender Ablauf: + Grundablauf: - - Starten Sie mit `sessions_spawn` unter Verwendung von `thread: true` (und optional `mode: "session"` für persistente Follow-ups). + - Starten Sie mit `sessions_spawn` unter Verwendung von `thread: true` (und optional `mode: "session"` für persistente Folgeaktionen). - Oder binden Sie manuell mit `/focus `. - - Verwenden Sie `/agents`, um den Binding-Status zu prüfen. - - Verwenden Sie `/session idle ` und `/session max-age `, um automatisches Unfocus zu steuern. + - Verwenden Sie `/agents`, um den Bindungsstatus zu prüfen. + - Verwenden Sie `/session idle ` und `/session max-age `, um das automatische Lösen des Fokus zu steuern. - Verwenden Sie `/unfocus`, um den Thread zu lösen. Erforderliche Konfiguration: - Globale Standardwerte: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Discord-Überschreibungen: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Auto-Bind beim Start: Setzen Sie `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Discord-Overrides: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Automatische Bindung beim Start: Setzen Sie `channels.discord.threadBindings.spawnSubagentSessions: true`. - Docs: [Sub-agents](/de/tools/subagents), [Discord](/de/channels/discord), [Configuration Reference](/de/gateway/configuration-reference), [Slash commands](/de/tools/slash-commands). + Dokumentation: [Sub-Agenten](/de/tools/subagents), [Discord](/de/channels/discord), [Konfigurationsreferenz](/de/gateway/configuration-reference), [Slash-Befehle](/de/tools/slash-commands). - - Prüfen Sie zuerst die aufgelöste Requester-Route: + + Prüfen Sie zuerst die aufgelöste Anforderer-Route: - - Die Zustellung von Sub-Agenten im Completion-Modus bevorzugt jeden gebundenen Thread oder jede Konversationsroute, wenn eine existiert. - - Wenn der Completion-Ursprung nur einen Kanal enthält, fällt OpenClaw auf die im Requester-Session gespeicherte Route zurück (`lastChannel` / `lastTo` / `lastAccountId`), sodass direkte Zustellung weiterhin funktionieren kann. - - Wenn weder eine gebundene Route noch eine nutzbare gespeicherte Route existiert, kann direkte Zustellung fehlschlagen und das Ergebnis fällt statt eines sofortigen Posts in den Chat auf die Zustellung über die Sitzungswarteschlange zurück. - - Ungültige oder veraltete Ziele können weiterhin Queue-Fallback oder endgültiges Zustellungsversagen erzwingen. - - Wenn die letzte sichtbare Assistant-Antwort des Child genau das stille Token `NO_REPLY` / `no_reply` oder genau `ANNOUNCE_SKIP` ist, unterdrückt OpenClaw die Ankündigung absichtlich, statt veralteten früheren Fortschritt zu posten. - - Wenn das Child nach ausschließlich Tool-Aufrufen ein Timeout hatte, kann die Ankündigung dies zu einer kurzen Zusammenfassung des Teilfortschritts verdichten, statt rohe Tool-Ausgabe erneut abzuspielen. + - Die Zustellung von Sub-Agenten im Abschlussmodus bevorzugt jeden gebundenen Thread oder jede Konversationsroute, wenn eine existiert. + - Wenn der Abschlussursprung nur einen Kanal enthält, greift OpenClaw auf die gespeicherte Route der Anforderer-Sitzung (`lastChannel` / `lastTo` / `lastAccountId`) zurück, sodass direkte Zustellung trotzdem gelingen kann. + - Wenn weder eine gebundene Route noch eine nutzbare gespeicherte Route existiert, kann die direkte Zustellung fehlschlagen und das Ergebnis fällt stattdessen auf zugestellte Sitzungswarteschlange zurück, anstatt sofort im Chat gepostet zu werden. + - Ungültige oder veraltete Ziele können weiterhin einen Rückfall auf die Warteschlange oder einen endgültigen Zustellungsfehler erzwingen. + - Wenn die letzte sichtbare Assistant-Antwort des Childs exakt das stille Token `NO_REPLY` / `no_reply` oder exakt `ANNOUNCE_SKIP` ist, unterdrückt OpenClaw die Ankündigung absichtlich, anstatt veralteten früheren Fortschritt zu posten. + - Wenn das Child nach nur Tool-Aufrufen ein Timeout hatte, kann die Ankündigung dies zu einer kurzen Teilfortschrittszusammenfassung verdichten, anstatt rohe Tool-Ausgabe wiederzugeben. - Debugging: + Debug: ```bash openclaw tasks show ``` - Docs: [Sub-agents](/de/tools/subagents), [Background Tasks](/de/automation/tasks), [Session Tools](/de/concepts/session-tool). + Dokumentation: [Sub-Agenten](/de/tools/subagents), [Hintergrundaufgaben](/de/automation/tasks), [Session Tools](/de/concepts/session-tool). @@ -1085,69 +1084,68 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - Bestätigen Sie, dass Cron aktiviert ist (`cron.enabled`) und `OPENCLAW_SKIP_CRON` nicht gesetzt ist. - Prüfen Sie, dass das Gateway 24/7 läuft (kein Schlafmodus/keine Neustarts). - - Verifizieren Sie die Zeitzoneneinstellungen für den Job (`--tz` vs. Host-Zeitzone). + - Verifizieren Sie die Zeitzoneneinstellungen für den Job (`--tz` im Vergleich zur Host-Zeitzone). - Debugging: + Debug: ```bash openclaw cron run openclaw cron runs --id --limit 50 ``` - Docs: [Cron jobs](/de/automation/cron-jobs), [Automation & Tasks](/de/automation). + Dokumentation: [Cron-Jobs](/de/automation/cron-jobs), [Automatisierung & Aufgaben](/de/automation). Prüfen Sie zuerst den Zustellmodus: - - `--no-deliver` / `delivery.mode: "none"` bedeutet, dass keine externe Nachricht erwartet wird. + - `--no-deliver` / `delivery.mode: "none"` bedeutet, dass kein Fallback-Senden durch den Runner zu erwarten ist. - Fehlendes oder ungültiges Ankündigungsziel (`channel` / `to`) bedeutet, dass der Runner die ausgehende Zustellung übersprungen hat. - - Kanal-Authentifizierungsfehler (`unauthorized`, `Forbidden`) bedeuten, dass der Runner die Zustellung versucht hat, aber die Credentials sie blockiert haben. - - Ein stilles isoliertes Ergebnis (`NO_REPLY` / `no_reply` allein) wird als absichtlich nicht zustellbar behandelt, daher unterdrückt der Runner auch die Zustellung über den Queue-Fallback. + - Fehler bei der Kanal-Authentifizierung (`unauthorized`, `Forbidden`) bedeuten, dass der Runner die Zustellung versucht hat, aber die Anmeldedaten sie blockiert haben. + - Ein stilles isoliertes Ergebnis (`NO_REPLY` / `no_reply` allein) wird als absichtlich nicht zustellbar behandelt, daher unterdrückt der Runner auch die Fallback-Zustellung aus der Warteschlange. - Bei isolierten Cron-Jobs übernimmt der Runner die endgültige Zustellung. Vom Agenten wird erwartet, - eine Klartext-Zusammenfassung zurückzugeben, die der Runner senden kann. `--no-deliver` hält - dieses Ergebnis intern; es erlaubt dem Agenten nicht, stattdessen direkt mit dem - Nachrichtentool zu senden. + Bei isolierten Cron-Jobs kann der Agent weiterhin direkt mit dem `message`- + Tool senden, wenn eine Chat-Route verfügbar ist. `--announce` steuert nur den Runner- + Fallback-Pfad für finalen Text, den der Agent nicht bereits selbst gesendet hat. - Debugging: + Debug: ```bash openclaw cron runs --id --limit 50 openclaw tasks show ``` - Docs: [Cron jobs](/de/automation/cron-jobs), [Background Tasks](/de/automation/tasks). + Dokumentation: [Cron-Jobs](/de/automation/cron-jobs), [Hintergrundaufgaben](/de/automation/tasks). - Das ist normalerweise der Pfad für Live-Modellwechsel, nicht doppelte Planung. + Das ist normalerweise der Live-Modellwechselpfad, nicht doppelte Planung. - Isoliertes Cron kann eine Laufzeit-Übergabe des Modells persistieren und erneut versuchen, wenn der aktive + Isoliertes Cron kann eine Laufzeit-Modellübergabe persistieren und erneut versuchen, wenn der aktive Lauf `LiveSessionModelSwitchError` auslöst. Der erneute Versuch behält den gewechselten - Provider/das gewechselte Modell bei, und falls der Wechsel ein neues Auth-Profil-Override mitbrachte, persistiert Cron - auch das vor dem Retry. + Provider/das gewechselte Modell bei, und wenn der Wechsel ein neues Auth-Profil-Override mitbrachte, persistiert Cron + dieses ebenfalls vor dem erneuten Versuch. - Zugehörige Auswahlregeln: + Verwandte Auswahlregeln: - Das Gmail-Hook-Modell-Override gewinnt zuerst, wenn zutreffend. - - Dann das jobbezogene `model`. - - Dann jedes gespeicherte Modell-Override der Cron-Sitzung. - - Dann die normale Auswahl des Agent-/Standardmodells. + - Dann pro Job `model`. + - Dann jedes gespeicherte Cron-Sitzungsmodell-Override. + - Dann die normale Agent-/Standardmodellauswahl. - Die Retry-Schleife ist begrenzt. Nach dem initialen Versuch plus 2 Wechsel-Retries - bricht Cron ab, statt endlos zu schleifen. + Die Retry-Schleife ist begrenzt. Nach dem ersten Versuch plus 2 Wechsel-Retries + bricht Cron ab, anstatt endlos zu schleifen. - Debugging: + Debug: ```bash openclaw cron runs --id --limit 50 openclaw tasks show ``` - Docs: [Cron jobs](/de/automation/cron-jobs), [cron CLI](/cli/cron). + Dokumentation: [Cron-Jobs](/de/automation/cron-jobs), [cron CLI](/cli/cron). @@ -1166,41 +1164,41 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. openclaw skills check ``` - Native `openclaw skills install` schreibt in das aktive Workspace-Verzeichnis `skills/`. - Installieren Sie die separate `clawhub`-CLI nur, wenn Sie Ihre eigenen Skills veröffentlichen oder + Native `openclaw skills install` schreibt in das `skills/`- + Verzeichnis des aktiven Workspace. Installieren Sie die separate `clawhub`-CLI nur, wenn Sie Ihre eigenen Skills veröffentlichen oder synchronisieren möchten. Für gemeinsame Installationen über mehrere Agenten legen Sie den Skill unter `~/.openclaw/skills` ab und verwenden `agents.defaults.skills` oder - `agents.list[].skills`, wenn Sie einschränken möchten, welche Agenten ihn sehen können. + `agents.list[].skills`, wenn Sie eingrenzen möchten, welche Agenten ihn sehen können. - + Ja. Verwenden Sie den Gateway-Scheduler: - **Cron-Jobs** für geplante oder wiederkehrende Aufgaben (bleiben über Neustarts hinweg erhalten). - **Heartbeat** für periodische Prüfungen der „Hauptsitzung“. - - **Isolierte Jobs** für autonome Agenten, die Zusammenfassungen posten oder in Chats zustellen. + - **Isolierte Jobs** für autonome Agenten, die Zusammenfassungen posten oder an Chats zustellen. - Docs: [Cron jobs](/de/automation/cron-jobs), [Automation & Tasks](/de/automation), + Dokumentation: [Cron-Jobs](/de/automation/cron-jobs), [Automatisierung & Aufgaben](/de/automation), [Heartbeat](/de/gateway/heartbeat). - - Nicht direkt. macOS-Skills werden durch `metadata.openclaw.os` plus erforderliche Binaries gesteuert, und Skills erscheinen nur dann im System-Prompt, wenn sie auf dem **Gateway-Host** geeignet sind. Unter Linux werden `darwin`-only-Skills (wie `apple-notes`, `apple-reminders`, `things-mac`) nicht geladen, sofern Sie dieses Gating nicht überschreiben. + + Nicht direkt. macOS-Skills werden durch `metadata.openclaw.os` plus erforderliche Binärdateien gesteuert, und Skills erscheinen nur dann im System-Prompt, wenn sie auf dem **Gateway-Host** geeignet sind. Unter Linux werden reine `darwin`-Skills (wie `apple-notes`, `apple-reminders`, `things-mac`) nicht geladen, sofern Sie das Gating nicht überschreiben. - Sie haben drei unterstützte Muster: + Es gibt drei unterstützte Muster: **Option A – das Gateway auf einem Mac ausführen (am einfachsten).** - Führen Sie das Gateway dort aus, wo die macOS-Binaries vorhanden sind, und verbinden Sie sich dann von Linux im [Remote-Modus](#gateway-ports-already-running-and-remote-mode) oder über Tailscale. Die Skills werden normal geladen, weil der Gateway-Host macOS ist. + Führen Sie das Gateway dort aus, wo die macOS-Binärdateien vorhanden sind, und verbinden Sie sich dann von Linux aus im [Remote-Modus](#gateway-ports-already-running-and-remote-mode) oder über Tailscale. Die Skills werden normal geladen, weil der Gateway-Host macOS ist. - **Option B – einen macOS-Node verwenden (ohne SSH).** - Führen Sie das Gateway auf Linux aus, koppeln Sie einen macOS-Node (Menüleisten-App) und setzen Sie **Node Run Commands** auf dem Mac auf „Always Ask“ oder „Always Allow“. OpenClaw kann macOS-only-Skills als geeignet behandeln, wenn die erforderlichen Binaries auf dem Node vorhanden sind. Der Agent führt diese Skills über das Tool `nodes` aus. Wenn Sie „Always Ask“ wählen, fügt das Bestätigen von „Always Allow“ in der Eingabeaufforderung diesen Befehl zur Zulassungsliste hinzu. + **Option B – einen macOS Node verwenden (ohne SSH).** + Führen Sie das Gateway unter Linux aus, koppeln Sie einen macOS Node (Menüleisten-App), und setzen Sie **Node Run Commands** auf „Always Ask“ oder „Always Allow“ auf dem Mac. OpenClaw kann reine macOS-Skills als geeignet behandeln, wenn die erforderlichen Binärdateien auf dem Node vorhanden sind. Der Agent führt diese Skills über das `nodes`-Tool aus. Wenn Sie „Always Ask“ wählen, fügt das Genehmigen von „Always Allow“ in der Aufforderung diesen Befehl zur Allowlist hinzu. - **Option C – macOS-Binaries über SSH proxien (fortgeschritten).** - Lassen Sie das Gateway auf Linux, aber sorgen Sie dafür, dass sich die erforderlichen CLI-Binaries zu SSH-Wrappern auflösen, die auf einem Mac ausgeführt werden. Überschreiben Sie dann den Skill so, dass Linux erlaubt ist, damit er geeignet bleibt. + **Option C – macOS-Binärdateien über SSH proxien (fortgeschritten).** + Behalten Sie das Gateway unter Linux, aber sorgen Sie dafür, dass die erforderlichen CLI-Binärdateien auf SSH-Wrapper aufgelöst werden, die auf einem Mac ausgeführt werden. Überschreiben Sie dann den Skill, um Linux zu erlauben, damit er weiterhin geeignet bleibt. - 1. Erstellen Sie einen SSH-Wrapper für das Binary (Beispiel: `memo` für Apple Notes): + 1. Erstellen Sie einen SSH-Wrapper für die Binärdatei (Beispiel: `memo` für Apple Notes): ```bash #!/usr/bin/env bash @@ -1208,13 +1206,13 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Legen Sie den Wrapper auf dem Linux-Host in den `PATH` (zum Beispiel `~/bin/memo`). + 2. Legen Sie den Wrapper auf `PATH` auf dem Linux-Host ab (zum Beispiel `~/bin/memo`). 3. Überschreiben Sie die Skill-Metadaten (Workspace oder `~/.openclaw/skills`), um Linux zu erlauben: ```markdown --- name: apple-notes - description: Apple Notes über die memo-CLI auf macOS verwalten. + description: Apple Notes über die memo-CLI unter macOS verwalten. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` @@ -1223,21 +1221,21 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - - Derzeit nicht integriert. + + Heute nicht integriert. Optionen: - **Benutzerdefinierter Skill / Plugin:** am besten für zuverlässigen API-Zugriff (Notion/HeyGen haben beide APIs). - **Browser-Automatisierung:** funktioniert ohne Code, ist aber langsamer und fragiler. - Wenn Sie den Kontext pro Kunde beibehalten möchten (Agentur-Workflows), ist ein einfaches Muster: + Wenn Sie Kontext pro Client behalten möchten (Agentur-Workflows), ist ein einfaches Muster: - - Eine Notion-Seite pro Kunde (Kontext + Präferenzen + aktive Arbeit). + - Eine Notion-Seite pro Client (Kontext + Präferenzen + aktive Arbeit). - Bitten Sie den Agenten, diese Seite zu Beginn einer Sitzung abzurufen. - Wenn Sie eine native Integration möchten, öffnen Sie eine Feature-Anfrage oder bauen Sie einen Skill, - der diese APIs anspricht. + Wenn Sie eine native Integration möchten, erstellen Sie eine Feature-Anfrage oder bauen Sie einen Skill, + der auf diese APIs zielt. Skills installieren: @@ -1246,11 +1244,11 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. openclaw skills update --all ``` - Native Installationen landen im aktiven Workspace-Verzeichnis `skills/`. Für gemeinsame Skills über Agenten hinweg legen Sie sie in `~/.openclaw/skills//SKILL.md` ab. Wenn nur einige Agenten eine gemeinsame Installation sehen sollen, konfigurieren Sie `agents.defaults.skills` oder `agents.list[].skills`. Einige Skills erwarten Binaries, die über Homebrew installiert wurden; unter Linux bedeutet das Linuxbrew (siehe den Linux-FAQ-Eintrag zu Homebrew oben). Siehe [Skills](/de/tools/skills), [Skills config](/de/tools/skills-config) und [ClawHub](/de/tools/clawhub). + Native Installationen landen im `skills/`-Verzeichnis des aktiven Workspace. Für gemeinsame Skills über Agenten hinweg legen Sie sie in `~/.openclaw/skills//SKILL.md` ab. Wenn nur einige Agenten eine gemeinsame Installation sehen sollen, konfigurieren Sie `agents.defaults.skills` oder `agents.list[].skills`. Manche Skills erwarten Binärdateien, die über Homebrew installiert wurden; unter Linux bedeutet das Linuxbrew (siehe den Homebrew-Linux-FAQ-Eintrag oben). Siehe [Skills](/de/tools/skills), [Skills-Konfiguration](/de/tools/skills-config) und [ClawHub](/de/tools/clawhub). - + Verwenden Sie das integrierte Browser-Profil `user`, das sich über Chrome DevTools MCP verbindet: ```bash @@ -1265,13 +1263,13 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. openclaw browser --browser-profile chrome-live tabs ``` - Dieser Pfad kann den lokalen Host-Browser oder einen verbundenen Browser-Node verwenden. Wenn das Gateway woanders läuft, führen Sie entweder einen Node-Host auf dem Browser-Rechner aus oder verwenden Sie stattdessen Remote-CDP. + Dieser Pfad kann den Browser des lokalen Hosts oder einen verbundenen Browser-Node verwenden. Wenn das Gateway anderswo läuft, führen Sie entweder einen Node-Host auf der Browser-Maschine aus oder verwenden Sie stattdessen Remote-CDP. Aktuelle Einschränkungen von `existing-session` / `user`: - - Aktionen sind ref-basiert, nicht CSS-Selektor-basiert + - Aktionen sind ref-basiert, nicht CSS-Selector-basiert - Uploads erfordern `ref` / `inputRef` und unterstützen derzeit jeweils nur eine Datei - - `responsebody`, PDF-Export, Download-Interception und Batch-Aktionen benötigen weiterhin einen verwalteten Browser oder ein rohes CDP-Profil + - `responsebody`, PDF-Export, Download-Abfangen und Batch-Aktionen benötigen weiterhin einen verwalteten Browser oder ein rohes CDP-Profil @@ -1279,39 +1277,39 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. ## Sandboxing und Memory - - Ja. Siehe [Sandboxing](/de/gateway/sandboxing). Für Docker-spezifisches Setup (vollständiges Gateway in Docker oder Sandbox-Images) siehe [Docker](/de/install/docker). + + Ja. Siehe [Sandboxing](/de/gateway/sandboxing). Für Docker-spezifische Einrichtung (volles Gateway in Docker oder Sandbox-Images) siehe [Docker](/de/install/docker). - - Das Standard-Image ist sicherheitsorientiert und läuft als Benutzer `node`, daher enthält es - keine Systempakete, kein Homebrew und keine gebündelten Browser. Für ein vollständigeres Setup: + + Das Standard-Image ist sicherheitsorientiert und läuft als Benutzer `node`, daher enthält es keine + Systempakete, kein Homebrew und keine gebündelten Browser. Für ein vollständigeres Setup: - Persistieren Sie `/home/node` mit `OPENCLAW_HOME_VOLUME`, damit Caches erhalten bleiben. - Backen Sie Systemabhängigkeiten mit `OPENCLAW_DOCKER_APT_PACKAGES` in das Image ein. - Installieren Sie Playwright-Browser über die gebündelte CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - - Setzen Sie `PLAYWRIGHT_BROWSERS_PATH` und stellen Sie sicher, dass dieser Pfad persistent gespeichert wird. + - Setzen Sie `PLAYWRIGHT_BROWSERS_PATH` und stellen Sie sicher, dass der Pfad persistent ist. - Docs: [Docker](/de/install/docker), [Browser](/de/tools/browser). + Dokumentation: [Docker](/de/install/docker), [Browser](/de/tools/browser). - - Ja – wenn Ihr privater Verkehr **DMs** und Ihr öffentlicher Verkehr **Gruppen** sind. + + Ja – wenn Ihr privater Traffic **DMs** sind und Ihr öffentlicher Traffic **Gruppen**. - Verwenden Sie `agents.defaults.sandbox.mode: "non-main"`, damit Gruppen-/Kanal-Sitzungen (non-main-Schlüssel) im konfigurierten Sandbox-Backend laufen, während die Haupt-DM-Sitzung auf dem Host bleibt. Docker ist das Standard-Backend, wenn Sie keines auswählen. Schränken Sie dann über `tools.sandbox.tools` ein, welche Tools in sandboxed Sitzungen verfügbar sind. + Verwenden Sie `agents.defaults.sandbox.mode: "non-main"`, damit Gruppen-/Kanal-Sitzungen (Nicht-Hauptschlüssel) im konfigurierten Sandbox-Backend laufen, während die Haupt-DM-Sitzung auf dem Host bleibt. Docker ist das Standard-Backend, wenn Sie keines auswählen. Beschränken Sie dann mit `tools.sandbox.tools`, welche Tools in sandboxed Sitzungen verfügbar sind. - Einrichtungsanleitung + Beispielkonfiguration: [Groups: personal DMs + public groups](/de/channels/groups#pattern-personal-dms-public-groups-single-agent) + Einrichtungsanleitung + Beispielkonfiguration: [Gruppen: persönliche DMs + öffentliche Gruppen](/de/channels/groups#pattern-personal-dms-public-groups-single-agent) - Referenz für die Schlüsselkonfiguration: [Gateway configuration](/de/gateway/configuration-reference#agentsdefaultssandbox) + Wichtige Konfigurationsreferenz: [Gateway-Konfiguration](/de/gateway/configuration-reference#agentsdefaultssandbox) - Setzen Sie `agents.defaults.sandbox.docker.binds` auf `["host:path:mode"]` (z. B. `"/home/user/src:/src:ro"`). Globale und agentenspezifische Binds werden zusammengeführt; agentenspezifische Binds werden ignoriert, wenn `scope: "shared"` gesetzt ist. Verwenden Sie `:ro` für alles Sensible und denken Sie daran, dass Binds die Dateisystemgrenzen der Sandbox umgehen. + Setzen Sie `agents.defaults.sandbox.docker.binds` auf `["host:path:mode"]` (z. B. `"/home/user/src:/src:ro"`). Globale + agentenspezifische Bindings werden zusammengeführt; agentenspezifische Bindings werden ignoriert, wenn `scope: "shared"` gesetzt ist. Verwenden Sie `:ro` für alles Sensible und denken Sie daran, dass Bindings die Dateisystemgrenzen der Sandbox umgehen. - OpenClaw validiert Bind-Quellen sowohl gegen den normalisierten Pfad als auch gegen den kanonischen Pfad, der über den tiefsten existierenden Vorgänger aufgelöst wird. Das bedeutet, dass Ausbrüche über Symlink-Eltern weiterhin Fail-Closed scheitern, selbst wenn das letzte Pfadsegment noch nicht existiert, und dass Prüfungen erlaubter Roots auch nach der Symlink-Auflösung weiterhin gelten. + OpenClaw validiert Bind-Quellen sowohl gegen den normalisierten Pfad als auch gegen den kanonischen Pfad, der durch den tiefsten existierenden Vorfahren aufgelöst wird. Das bedeutet, dass Escapes über symlink-Parents weiterhin fail-closed fehlschlagen, selbst wenn das letzte Pfadsegment noch nicht existiert, und Allowed-Root-Prüfungen auch nach der Symlink-Auflösung weiterhin gelten. Siehe [Sandboxing](/de/gateway/sandboxing#custom-bind-mounts) und [Sandbox vs Tool Policy vs Elevated](/de/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) für Beispiele und Sicherheitshinweise. @@ -1323,53 +1321,54 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - Tagesnotizen in `memory/YYYY-MM-DD.md` - Kuratierte Langzeitnotizen in `MEMORY.md` (nur Haupt-/private Sitzungen) - OpenClaw führt außerdem einen **stillen Memory-Flush vor der Compaction** aus, um das Modell - daran zu erinnern, dauerhafte Notizen zu schreiben, bevor automatische Compaction erfolgt. Dies läuft nur, wenn der Workspace - beschreibbar ist (schreibgeschützte Sandboxes überspringen es). Siehe [Memory](/de/concepts/memory). + OpenClaw führt außerdem vor der automatischen Compaction einen **stillen Memory-Flush** aus, um das Modell + daran zu erinnern, vor der automatischen Compaction dauerhafte Notizen zu schreiben. Dies läuft nur, wenn der Workspace + beschreibbar ist (schreibgeschützte Sandboxes überspringen dies). Siehe [Memory](/de/concepts/memory). - + Bitten Sie den Bot, **die Tatsache in Memory zu schreiben**. Langzeitnotizen gehören in `MEMORY.md`, - kurzfristiger Kontext in `memory/YYYY-MM-DD.md`. + kurzfristiger Kontext kommt in `memory/YYYY-MM-DD.md`. - Das ist weiterhin ein Bereich, den wir verbessern. Es hilft, das Modell daran zu erinnern, Memories zu speichern; - es weiß dann, was zu tun ist. Wenn es trotzdem weiter vergisst, prüfen Sie, ob das Gateway bei jedem Lauf denselben - Workspace verwendet. + Das ist weiterhin ein Bereich, den wir verbessern. Es hilft, das Modell daran zu erinnern, Erinnerungen zu speichern; + es weiß dann, was zu tun ist. Wenn es weiter Dinge vergisst, prüfen Sie, ob das Gateway bei jedem + Lauf denselben Workspace verwendet. - Docs: [Memory](/de/concepts/memory), [Agent workspace](/de/concepts/agent-workspace). + Dokumentation: [Memory](/de/concepts/memory), [Agent-Workspace](/de/concepts/agent-workspace). Memory-Dateien liegen auf der Festplatte und bleiben erhalten, bis Sie sie löschen. Die Grenze ist Ihr - Speicherplatz, nicht das Modell. Der **Sitzungskontext** ist weiterhin durch das Modell- - Kontextfenster begrenzt, daher können lange Unterhaltungen komprimiert oder gekürzt werden. Deshalb - gibt es die Memory-Suche – sie holt nur die relevanten Teile zurück in den Kontext. + Speicherplatz, nicht das Modell. Der **Sitzungskontext** ist weiterhin durch das Kontextfenster des Modells + begrenzt, daher können lange Gespräche komprimiert oder gekürzt werden. Deshalb gibt es die + Memory-Suche – sie zieht nur die relevanten Teile zurück in den Kontext. - Docs: [Memory](/de/concepts/memory), [Context](/de/concepts/context). + Dokumentation: [Memory](/de/concepts/memory), [Kontext](/de/concepts/context). - - Nur wenn Sie **OpenAI-Embeddings** verwenden. Codex-OAuth deckt Chat/Completions ab und - gewährt **keinen** Zugriff auf Embeddings, daher hilft **die Anmeldung mit Codex (OAuth oder - dem Codex-CLI-Login)** nicht bei der semantischen Memory-Suche. OpenAI-Embeddings + + Nur wenn Sie **OpenAI-Embeddings** verwenden. Codex OAuth deckt Chat/Completions ab und + gewährt **keinen** Zugriff auf Embeddings, daher hilft **die Anmeldung mit Codex (OAuth oder der + Codex-CLI-Anmeldung)** nicht bei der semantischen Memory-Suche. OpenAI-Embeddings benötigen weiterhin einen echten API-Schlüssel (`OPENAI_API_KEY` oder `models.providers.openai.apiKey`). Wenn Sie keinen Provider explizit festlegen, wählt OpenClaw automatisch einen Provider aus, wenn es - einen API-Schlüssel auflösen kann (Auth-Profile, `models.providers.*.apiKey` oder Env-Variablen). - Es bevorzugt OpenAI, wenn ein OpenAI-Schlüssel aufgelöst wird, andernfalls Gemini, wenn ein Gemini-Schlüssel - aufgelöst wird, dann Voyage, dann Mistral. Wenn kein Remote-Schlüssel verfügbar ist, bleibt die Memory- - Suche deaktiviert, bis Sie sie konfigurieren. Wenn Sie einen konfigurierten und vorhandenen lokalen Modellpfad haben, bevorzugt OpenClaw + einen API-Schlüssel auflösen kann (Auth-Profile, `models.providers.*.apiKey` oder Umgebungsvariablen). + Es bevorzugt OpenAI, wenn sich ein OpenAI-Schlüssel auflösen lässt, andernfalls Gemini, wenn sich ein Gemini-Schlüssel + auflösen lässt, dann Voyage, dann Mistral. Wenn kein Remote-Schlüssel verfügbar ist, bleibt die Memory- + Suche deaktiviert, bis Sie sie konfigurieren. Wenn Sie einen lokalen Modellpfad + konfiguriert haben und dieser vorhanden ist, bevorzugt OpenClaw `local`. Ollama wird unterstützt, wenn Sie explizit `memorySearch.provider = "ollama"` setzen. Wenn Sie lieber lokal bleiben möchten, setzen Sie `memorySearch.provider = "local"` (und optional `memorySearch.fallback = "none"`). Wenn Sie Gemini-Embeddings möchten, setzen Sie - `memorySearch.provider = "gemini"` und geben `GEMINI_API_KEY` an (oder - `memorySearch.remote.apiKey`). Wir unterstützen Embedding- - Modelle von **OpenAI, Gemini, Voyage, Mistral, Ollama oder local** – siehe [Memory](/de/concepts/memory) für die Setup-Details. + `memorySearch.provider = "gemini"` und geben Sie `GEMINI_API_KEY` (oder + `memorySearch.remote.apiKey`) an. Wir unterstützen Embedding- + Modelle von **OpenAI, Gemini, Voyage, Mistral, Ollama oder lokal** – siehe [Memory](/de/concepts/memory) für die Einrichtungsdetails. @@ -1378,48 +1377,48 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - Nein – **der Status von OpenClaw ist lokal**, aber **externe Dienste sehen weiterhin, was Sie ihnen senden**. + Nein – **der Zustand von OpenClaw ist lokal**, aber **externe Services sehen weiterhin, was Sie an sie senden**. - **Standardmäßig lokal:** Sitzungen, Memory-Dateien, Konfiguration und Workspace liegen auf dem Gateway-Host (`~/.openclaw` + Ihr Workspace-Verzeichnis). - - **Notwendigerweise remote:** Nachrichten, die Sie an Modell-Provider (Anthropic/OpenAI/etc.) senden, gehen an - deren APIs, und Chat-Plattformen (WhatsApp/Telegram/Slack/etc.) speichern Nachrichtendaten auf ihren + - **Zwangsläufig remote:** Nachrichten, die Sie an Modell-Provider (Anthropic/OpenAI/usw.) senden, gehen an + deren APIs, und Chat-Plattformen (WhatsApp/Telegram/Slack/usw.) speichern Nachrichtendaten auf ihren Servern. - - **Sie kontrollieren den Footprint:** Mit lokalen Modellen bleiben Prompts auf Ihrem Rechner, aber Kanal- - verkehr geht weiterhin über die Server des jeweiligen Kanals. + - **Sie steuern den Footprint:** Die Verwendung lokaler Modelle hält Prompts auf Ihrer Maschine, aber Kanal- + Traffic läuft weiterhin über die Server des jeweiligen Kanals. - Verwandt: [Agent workspace](/de/concepts/agent-workspace), [Memory](/de/concepts/memory). + Verwandte Themen: [Agent-Workspace](/de/concepts/agent-workspace), [Memory](/de/concepts/memory). Alles liegt unter `$OPENCLAW_STATE_DIR` (Standard: `~/.openclaw`): - | Pfad | Zweck | + | Path | Zweck | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | Hauptkonfiguration (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy-OAuth-Import (bei erster Verwendung in Auth-Profile kopiert) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth-Profile (OAuth, API-Schlüssel und optionale `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Optionale dateigestützte Secret-Payload für `file`-SecretRef-Provider | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy-OAuth-Import (wird bei der ersten Nutzung in Auth-Profile kopiert) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth-Profile (OAuth, API-Schlüssel und optional `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Optionaler dateigestützter Secret-Payload für `file` SecretRef-Provider | | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy-Kompatibilitätsdatei (statische `api_key`-Einträge bereinigt) | - | `$OPENCLAW_STATE_DIR/credentials/` | Provider-Status (z. B. `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Status pro Agent (agentDir + Sitzungen) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Unterhaltungsverlauf & Status (pro Agent) | + | `$OPENCLAW_STATE_DIR/credentials/` | Provider-Zustand (z. B. `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Pro-Agent-Zustand (agentDir + Sitzungen) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Gesprächsverlauf & Zustand (pro Agent) | | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Sitzungsmetadaten (pro Agent) | - Legacy-Einzelagent-Pfad: `~/.openclaw/agent/*` (migriert durch `openclaw doctor`). + Legacy-Single-Agent-Pfad: `~/.openclaw/agent/*` (migriert durch `openclaw doctor`). - Ihr **Workspace** (`AGENTS.md`, Memory-Dateien, Skills usw.) ist separat und wird über `agents.defaults.workspace` konfiguriert (Standard: `~/.openclaw/workspace`). + Ihr **Workspace** (`AGENTS.md`, Memory-Dateien, Skills usw.) ist getrennt und wird über `agents.defaults.workspace` konfiguriert (Standard: `~/.openclaw/workspace`). Diese Dateien liegen im **Agent-Workspace**, nicht in `~/.openclaw`. - - **Workspace (pro Agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + - **Workspace (pro Agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md` (oder Legacy-Fallback `memory.md`, wenn `MEMORY.md` fehlt), `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`. - - **State-Verzeichnis (`~/.openclaw`)**: Konfiguration, Kanal-/Provider-Status, Auth-Profile, Sitzungen, Logs + - **State dir (`~/.openclaw`)**: Konfiguration, Kanal-/Provider-Zustand, Auth-Profile, Sitzungen, Logs, und gemeinsame Skills (`~/.openclaw/skills`). Der Standard-Workspace ist `~/.openclaw/workspace`, konfigurierbar über: @@ -1430,44 +1429,44 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. } ``` - Wenn der Bot nach einem Neustart „vergisst“, prüfen Sie, ob das Gateway bei jedem Start denselben + Wenn der Bot nach einem Neustart „vergisst“, prüfen Sie, dass das Gateway bei jedem Start denselben Workspace verwendet (und denken Sie daran: Der Remote-Modus verwendet den Workspace des **Gateway-Hosts**, nicht den Ihres lokalen Laptops). Tipp: Wenn Sie ein dauerhaftes Verhalten oder eine Präferenz möchten, bitten Sie den Bot, es **in AGENTS.md oder MEMORY.md zu schreiben**, statt sich auf den Chat-Verlauf zu verlassen. - Siehe [Agent workspace](/de/concepts/agent-workspace) und [Memory](/de/concepts/memory). + Siehe [Agent-Workspace](/de/concepts/agent-workspace) und [Memory](/de/concepts/memory). - Legen Sie Ihren **Agent-Workspace** in ein **privates** git-Repo und sichern Sie ihn an einem - privaten Ort (zum Beispiel GitHub private). Dadurch werden Memory + AGENTS/SOUL/USER- - Dateien erfasst, und Sie können den „Geist“ des Assistenten später wiederherstellen. + Legen Sie Ihren **Agent-Workspace** in ein **privates** git-Repository und sichern Sie ihn an einem + privaten Ort (zum Beispiel GitHub private). Damit erfassen Sie Memory + AGENTS/SOUL/USER- + Dateien und können den „Geist“ des Assistenten später wiederherstellen. - Committen Sie **nichts** unter `~/.openclaw` (`Credentials`, Sitzungen, Tokens oder verschlüsselte Secret-Payloads). + Committen Sie **nichts** unter `~/.openclaw` (`credentials`, Sitzungen, Tokens oder verschlüsselte Secret-Payloads). Wenn Sie eine vollständige Wiederherstellung benötigen, sichern Sie sowohl den Workspace als auch das State-Verzeichnis separat (siehe die Migrationsfrage oben). - Docs: [Agent workspace](/de/concepts/agent-workspace). + Dokumentation: [Agent-Workspace](/de/concepts/agent-workspace). - Siehe die dedizierte Anleitung: [Uninstall](/de/install/uninstall). + Siehe die spezielle Anleitung: [Deinstallieren](/de/install/uninstall). Ja. Der Workspace ist das **Standard-cwd** und der Memory-Anker, keine harte Sandbox. Relative Pfade werden innerhalb des Workspace aufgelöst, aber absolute Pfade können auf andere - Host-Orte zugreifen, sofern Sandboxing nicht aktiviert ist. Wenn Sie Isolation benötigen, verwenden Sie + Host-Speicherorte zugreifen, sofern Sandboxing nicht aktiviert ist. Wenn Sie Isolation benötigen, verwenden Sie [`agents.defaults.sandbox`](/de/gateway/sandboxing) oder agentenspezifische Sandbox-Einstellungen. Wenn Sie - möchten, dass ein Repo das Standard-Arbeitsverzeichnis ist, setzen Sie den `workspace` - dieses Agenten auf das Root des Repos. Das OpenClaw-Repo ist nur Quellcode; halten Sie den - Workspace getrennt, es sei denn, Sie möchten ausdrücklich, dass der Agent darin arbeitet. + möchten, dass ein Repository das Standard-Arbeitsverzeichnis ist, setzen Sie den + `workspace` dieses Agenten auf das Repository-Root. Das OpenClaw-Repository ist nur Quellcode; halten Sie den + Workspace getrennt, es sei denn, Sie möchten absichtlich, dass der Agent darin arbeitet. - Beispiel (Repo als Standard-cwd): + Beispiel (Repository als Standard-cwd): ```json5 { @@ -1482,29 +1481,29 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - Der Sitzungsstatus gehört dem **Gateway-Host**. Wenn Sie im Remote-Modus sind, befindet sich der relevante Sitzungsspeicher auf dem Remote-Rechner, nicht auf Ihrem lokalen Laptop. Siehe [Session management](/de/concepts/session). + Der Sitzungszustand gehört dem **Gateway-Host**. Wenn Sie sich im Remote-Modus befinden, liegt der relevante Sitzungsspeicher auf der Remote-Maschine, nicht auf Ihrem lokalen Laptop. Siehe [Sitzungsverwaltung](/de/concepts/session). ## Grundlagen der Konfiguration - + OpenClaw liest eine optionale **JSON5**-Konfiguration aus `$OPENCLAW_CONFIG_PATH` (Standard: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Wenn die Datei fehlt, verwendet es halbwegs sichere Standardwerte (einschließlich eines Standard-Workspace von `~/.openclaw/workspace`). + Wenn die Datei fehlt, verwendet es einigermaßen sichere Standardwerte (einschließlich eines Standard-Workspace von `~/.openclaw/workspace`). - - Nicht-loopback-Binds **erfordern einen gültigen Gateway-Authentifizierungspfad**. In der Praxis bedeutet das: + + Bindungen außerhalb von loopback **erfordern einen gültigen Gateway-Auth-Pfad**. In der Praxis bedeutet das: - - Shared-Secret-Authentifizierung: Token oder Passwort - - `gateway.auth.mode: "trusted-proxy"` hinter einem korrekt konfigurierten nicht-loopback Identity-aware Reverse Proxy + - Shared-Secret-Auth: Token oder Passwort + - `gateway.auth.mode: "trusted-proxy"` hinter einem korrekt konfigurierten Identity-aware-Reverse-Proxy ohne loopback ```json5 { @@ -1520,26 +1519,26 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Hinweise: - - `gateway.remote.token` / `.password` aktivieren lokale Gateway-Authentifizierung nicht von selbst. - - Lokale Aufrufpfade können `gateway.remote.*` nur dann als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist. - - Für Passwort-Authentifizierung setzen Sie stattdessen `gateway.auth.mode: "password"` plus `gateway.auth.password` (oder `OPENCLAW_GATEWAY_PASSWORD`). - - Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht aufgelöst ist, schlägt die Auflösung Fail-Closed fehl (kein Remote-Fallback, das dies maskiert). - - Shared-Secret-Control-UI-Setups authentifizieren über `connect.params.auth.token` oder `connect.params.auth.password` (gespeichert in App-/UI-Einstellungen). Identitätstragende Modi wie Tailscale Serve oder `trusted-proxy` verwenden stattdessen Request-Header. Vermeiden Sie es, Shared Secrets in URLs zu platzieren. - - Mit `gateway.auth.mode: "trusted-proxy"` erfüllen Reverse Proxys auf demselben Host mit loopback weiterhin **nicht** die trusted-proxy-Authentifizierung. Der Trusted Proxy muss eine konfigurierte nicht-loopback-Quelle sein. + - `gateway.remote.token` / `.password` aktivieren lokale Gateway-Auth **nicht** von selbst. + - Lokale Call-Pfade können `gateway.remote.*` nur dann als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist. + - Für Passwort-Auth setzen Sie stattdessen `gateway.auth.mode: "password"` plus `gateway.auth.password` (oder `OPENCLAW_GATEWAY_PASSWORD`). + - 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). + - Shared-Secret-Control-UI-Setups authentifizieren sich über `connect.params.auth.token` oder `connect.params.auth.password` (gespeichert in App-/UI-Einstellungen). Modi mit Identitätsinformationen wie Tailscale Serve oder `trusted-proxy` verwenden stattdessen Request-Header. Vermeiden Sie es, Shared Secrets in URLs zu platzieren. + - Mit `gateway.auth.mode: "trusted-proxy"` erfüllen Reverse-Proxys über loopback auf demselben Host **nicht** die trusted-proxy-Auth. Der trusted proxy muss eine konfigurierte Quelle ohne loopback sein. - - OpenClaw erzwingt standardmäßig Gateway-Authentifizierung, auch auf loopback. Im normalen Standardpfad bedeutet das Token-Authentifizierung: Wenn kein expliziter Authentifizierungspfad konfiguriert ist, löst der Gateway-Start auf den Token-Modus auf und erzeugt automatisch einen Token, den es in `gateway.auth.token` speichert, sodass **lokale WS-Clients sich authentifizieren müssen**. Dadurch werden andere lokale Prozesse daran gehindert, das Gateway aufzurufen. + + OpenClaw erzwingt standardmäßig Gateway-Auth, einschließlich loopback. Im normalen Standardpfad bedeutet das Token-Auth: Wenn kein expliziter Auth-Pfad konfiguriert ist, wird beim Gateway-Start der Token-Modus aufgelöst und automatisch ein Token erzeugt, das in `gateway.auth.token` gespeichert wird, sodass **lokale WS-Clients authentifiziert werden müssen**. Dadurch wird verhindert, dass andere lokale Prozesse das Gateway aufrufen. - Wenn Sie einen anderen Authentifizierungspfad bevorzugen, können Sie explizit den Passwortmodus wählen (oder für nicht-loopback Identity-aware Reverse Proxys `trusted-proxy`). Wenn Sie **wirklich** offenes loopback möchten, setzen Sie explizit `gateway.auth.mode: "none"` in Ihrer Konfiguration. Doctor kann jederzeit einen Token für Sie erzeugen: `openclaw doctor --generate-gateway-token`. + Wenn Sie einen anderen Auth-Pfad bevorzugen, können Sie explizit den Passwortmodus wählen (oder, für Identity-aware-Reverse-Proxys ohne loopback, `trusted-proxy`). Wenn Sie **wirklich** offenes loopback möchten, setzen Sie explizit `gateway.auth.mode: "none"` in Ihrer Konfiguration. Doctor kann jederzeit ein Token für Sie erzeugen: `openclaw doctor --generate-gateway-token`. - Das Gateway überwacht die Konfiguration und unterstützt Hot Reload: + Das Gateway überwacht die Konfiguration und unterstützt Hot-Reload: - - `gateway.reload.mode: "hybrid"` (Standard): sichere Änderungen per Hot Apply, Neustart für kritische Änderungen + - `gateway.reload.mode: "hybrid"` (Standard): sichere Änderungen hot anwenden, für kritische Änderungen neu starten - `hot`, `restart`, `off` werden ebenfalls unterstützt @@ -1560,11 +1559,11 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - `off`: blendet den Tagline-Text aus, behält aber die Titel-/Versionszeile des Banners bei. - `default`: verwendet jedes Mal `All your chats, one OpenClaw.`. - `random`: rotierende lustige/saisonale Taglines (Standardverhalten). - - Wenn Sie überhaupt kein Banner möchten, setzen Sie die Env-Variable `OPENCLAW_HIDE_BANNER=1`. + - Wenn Sie überhaupt kein Banner möchten, setzen Sie die Umgebungsvariable `OPENCLAW_HIDE_BANNER=1`. - + `web_fetch` funktioniert ohne API-Schlüssel. `web_search` hängt von Ihrem ausgewählten Provider ab: @@ -1574,7 +1573,7 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - SearXNG ist schlüsselfrei/self-hosted; konfigurieren Sie `SEARXNG_BASE_URL` oder `plugins.entries.searxng.config.webSearch.baseUrl`. **Empfohlen:** Führen Sie `openclaw configure --section web` aus und wählen Sie einen Provider. - Alternativen über die Umgebung: + Umgebungsalternativen: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1609,7 +1608,7 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. }, fetch: { enabled: true, - provider: "firecrawl", // optional; weglassen für automatische Erkennung + provider: "firecrawl", // optional; omit for auto-detect }, }, }, @@ -1617,68 +1616,68 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. ``` Provider-spezifische Websuche-Konfiguration liegt jetzt unter `plugins.entries..config.webSearch.*`. - Alte Provider-Pfade unter `tools.web.search.*` werden aus Kompatibilitätsgründen vorübergehend weiterhin geladen, sollten aber für neue Konfigurationen nicht mehr verwendet werden. - Die Firecrawl-Web-Fetch-Fallback-Konfiguration liegt unter `plugins.entries.firecrawl.config.webFetch.*`. + Legacy-Provider-Pfade unter `tools.web.search.*` werden aus Kompatibilitätsgründen vorübergehend noch geladen, sollten aber nicht für neue Konfigurationen verwendet werden. + Firecrawl-Web-Fetch-Fallback-Konfiguration liegt unter `plugins.entries.firecrawl.config.webFetch.*`. Hinweise: - - Wenn Sie Zulassungslisten verwenden, fügen Sie `web_search`/`web_fetch`/`x_search` oder `group:web` hinzu. + - Wenn Sie Allowlists verwenden, fügen Sie `web_search`/`web_fetch`/`x_search` oder `group:web` hinzu. - `web_fetch` ist standardmäßig aktiviert (sofern nicht explizit deaktiviert). - - Wenn `tools.web.fetch.provider` weggelassen wird, erkennt OpenClaw automatisch den ersten bereiten Fetch-Fallback-Provider aus den verfügbaren Credentials. Derzeit ist der gebündelte Provider Firecrawl. - - Daemons lesen Env-Variablen aus `~/.openclaw/.env` (oder aus der Service-Umgebung). + - Wenn `tools.web.fetch.provider` weggelassen wird, erkennt OpenClaw automatisch den ersten bereiten Fetch-Fallback-Provider aus den verfügbaren Anmeldedaten. Der gebündelte Provider ist derzeit Firecrawl. + - Daemons lesen Umgebungsvariablen aus `~/.openclaw/.env` (oder der Service-Umgebung). - Docs: [Web tools](/de/tools/web). + Dokumentation: [Web-Tools](/de/tools/web). - + `config.apply` ersetzt die **gesamte Konfiguration**. Wenn Sie ein partielles Objekt senden, wird alles andere entfernt. - OpenClaw schützt derzeit vor vielen versehentlichen Überschreibungen: + Das aktuelle OpenClaw schützt vor vielen versehentlichen Überschreibungen: - - Von OpenClaw selbst ausgelöste Konfigurationsschreibvorgänge validieren die vollständige Konfiguration nach der Änderung, bevor sie geschrieben wird. - - Ungültige oder destruktive von OpenClaw ausgelöste Schreibvorgänge werden abgelehnt und als `openclaw.json.rejected.*` gespeichert. - - Wenn eine direkte Bearbeitung den Start oder Hot Reload kaputt macht, stellt das Gateway die letzte funktionierende Konfiguration wieder her und speichert die abgelehnte Datei als `openclaw.json.clobbered.*`. - - Der Hauptagent erhält nach der Wiederherstellung eine Boot-Warnung, damit er die schlechte Konfiguration nicht blind erneut schreibt. + - Von OpenClaw selbst vorgenommene Konfigurationsschreibvorgänge validieren die vollständige Konfiguration nach der Änderung vor dem Schreiben. + - Ungültige oder destruktive, von OpenClaw selbst vorgenommene Schreibvorgänge werden abgelehnt und als `openclaw.json.rejected.*` gespeichert. + - Wenn eine direkte Bearbeitung den Start oder Hot-Reload kaputt macht, stellt das Gateway die letzte bekannte funktionierende Konfiguration wieder her und speichert die abgelehnte Datei als `openclaw.json.clobbered.*`. + - Der Haupt-Agent erhält nach der Wiederherstellung eine Startwarnung, damit er die fehlerhafte Konfiguration nicht blind erneut schreibt. - Wiederherstellung: + Wiederherstellen: - Prüfen Sie `openclaw logs --follow` auf `Config auto-restored from last-known-good`, `Config write rejected:` oder `config reload restored last-known-good config`. - Prüfen Sie die neueste `openclaw.json.clobbered.*` oder `openclaw.json.rejected.*` neben der aktiven Konfiguration. - Behalten Sie die aktive wiederhergestellte Konfiguration, wenn sie funktioniert, und kopieren Sie dann nur die beabsichtigten Schlüssel mit `openclaw config set` oder `config.patch` zurück. - Führen Sie `openclaw config validate` und `openclaw doctor` aus. - - Wenn Sie keine letzte funktionierende oder abgelehnte Payload haben, stellen Sie sie aus einem Backup wieder her oder führen Sie `openclaw doctor` erneut aus und konfigurieren Kanäle/Modelle neu. - - Wenn das unerwartet war, melden Sie einen Bug und fügen Ihre zuletzt bekannte Konfiguration oder ein vorhandenes Backup bei. + - Wenn Sie keine letzte bekannte funktionierende oder abgelehnte Payload haben, stellen Sie aus einem Backup wieder her oder führen Sie `openclaw doctor` erneut aus und konfigurieren Kanäle/Modelle neu. + - Wenn dies unerwartet war, melden Sie einen Bug und fügen Sie Ihre letzte bekannte Konfiguration oder ein Backup bei. - Ein lokaler Coding-Agent kann oft aus Logs oder Verlauf eine funktionierende Konfiguration rekonstruieren. - So vermeiden Sie es: + Vermeiden: - Verwenden Sie `openclaw config set` für kleine Änderungen. - Verwenden Sie `openclaw configure` für interaktive Bearbeitungen. - - Verwenden Sie zuerst `config.schema.lookup`, wenn Sie sich bei einem exakten Pfad oder der Feldform unsicher sind; es gibt einen flachen Schemaknoten plus Zusammenfassungen der direkten Kindknoten für Drill-down zurück. - - Verwenden Sie `config.patch` für partielle RPC-Bearbeitungen; reservieren Sie `config.apply` nur für vollständigen Konfigurationsersatz. - - Wenn Sie das nur für Eigentümer gedachte Tool `gateway` aus einem Agentenlauf verwenden, lehnt es weiterhin Schreibvorgänge an `tools.exec.ask` / `tools.exec.security` ab (einschließlich alter `tools.bash.*`-Aliasse, die auf dieselben geschützten Exec-Pfade normalisiert werden). + - Verwenden Sie zuerst `config.schema.lookup`, wenn Sie sich bei einem exakten Pfad oder der Form eines Felds nicht sicher sind; es gibt einen flachen Schema-Knoten plus unmittelbare Child-Zusammenfassungen zur schrittweisen Vertiefung zurück. + - Verwenden Sie `config.patch` für partielle RPC-Bearbeitungen; reservieren Sie `config.apply` nur für den vollständigen Ersatz der Konfiguration. + - Wenn Sie das nur für Eigentümer verfügbare `gateway`-Tool aus einem Agent-Lauf verwenden, lehnt es weiterhin Schreibvorgänge in `tools.exec.ask` / `tools.exec.security` ab (einschließlich Legacy-`tools.bash.*`-Aliasse, die auf dieselben geschützten exec-Pfade normalisiert werden). - Docs: [Config](/cli/config), [Configure](/cli/configure), [Gateway troubleshooting](/de/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/de/gateway/doctor). + Dokumentation: [Config](/cli/config), [Configure](/cli/configure), [Gateway-Fehlersuche](/de/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/de/gateway/doctor). - + Das übliche Muster ist **ein Gateway** (z. B. Raspberry Pi) plus **Nodes** und **Agenten**: - **Gateway (zentral):** besitzt Kanäle (Signal/WhatsApp), Routing und Sitzungen. - **Nodes (Geräte):** Macs/iOS/Android verbinden sich als Peripheriegeräte und stellen lokale Tools bereit (`system.run`, `canvas`, `camera`). - - **Agenten (Worker):** getrennte Gehirne/Workspaces für spezielle Rollen (z. B. „Hetzner ops“, „Personal data“). - - **Sub-Agents:** starten Hintergrundarbeit von einem Hauptagenten aus, wenn Sie Parallelität möchten. + - **Agenten (Worker):** separate Gehirne/Workspaces für spezielle Rollen (z. B. „Hetzner ops“, „Persönliche Daten“). + - **Sub-Agenten:** starten Hintergrundarbeit von einem Haupt-Agenten aus, wenn Sie Parallelität möchten. - **TUI:** mit dem Gateway verbinden und Agenten/Sitzungen wechseln. - Docs: [Nodes](/de/nodes), [Remote access](/de/gateway/remote), [Multi-Agent Routing](/de/concepts/multi-agent), [Sub-agents](/de/tools/subagents), [TUI](/web/tui). + Dokumentation: [Nodes](/de/nodes), [Remote-Zugriff](/de/gateway/remote), [Multi-Agent-Routing](/de/concepts/multi-agent), [Sub-Agenten](/de/tools/subagents), [TUI](/web/tui). - Ja. Es ist eine Konfigurationsoption: + Ja. Das ist eine Konfigurationsoption: ```json5 { @@ -1691,18 +1690,18 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. } ``` - Standard ist `false` (headful). Headless löst auf manchen Websites eher Anti-Bot-Prüfungen aus. Siehe [Browser](/de/tools/browser). + Der Standard ist `false` (mit sichtbarem Browserfenster). Headless löst auf manchen Websites eher Anti-Bot-Prüfungen aus. Siehe [Browser](/de/tools/browser). - Headless verwendet **denselben Chromium-Engine** und funktioniert für die meisten Automatisierungen (Formulare, Klicks, Scraping, Logins). Die Hauptunterschiede: + Headless verwendet **dieselbe Chromium-Engine** und funktioniert für die meisten Automatisierungen (Formulare, Klicks, Scraping, Logins). Die Hauptunterschiede: - - Kein sichtbares Browserfenster (verwenden Sie Screenshots, wenn Sie visuelle Informationen brauchen). + - Kein sichtbares Browserfenster (verwenden Sie Screenshots, wenn Sie Visuals brauchen). - Manche Websites sind im Headless-Modus strenger bei Automatisierung (CAPTCHAs, Anti-Bot). - Zum Beispiel blockiert X/Twitter Headless-Sitzungen häufig. + Zum Beispiel blockiert X/Twitter häufig Headless-Sitzungen. - - Setzen Sie `browser.executablePath` auf Ihr Brave-Binary (oder einen anderen Chromium-basierten Browser) und starten Sie das Gateway neu. + + Setzen Sie `browser.executablePath` auf Ihre Brave-Binärdatei (oder einen beliebigen Chromium-basierten Browser) und starten Sie das Gateway neu. Siehe die vollständigen Konfigurationsbeispiele unter [Browser](/de/tools/browser#use-brave-or-another-chromium-based-browser). @@ -1712,24 +1711,24 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Telegram-Nachrichten werden vom **Gateway** verarbeitet. Das Gateway führt den Agenten aus und - ruft erst dann Nodes über den **Gateway WebSocket** auf, wenn ein Node-Tool benötigt wird: + ruft erst dann Nodes über den **Gateway-WebSocket** auf, wenn ein Node-Tool benötigt wird: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes sehen keinen eingehenden Provider-Verkehr; sie empfangen nur Node-RPC-Aufrufe. + Nodes sehen keinen eingehenden Provider-Traffic; sie erhalten nur Node-RPC-Aufrufe. - - Kurz gesagt: **Koppeln Sie Ihren Rechner als Node**. Das Gateway läuft woanders, kann aber - `node.*`-Tools (Bildschirm, Kamera, System) auf Ihrem lokalen Rechner über den Gateway WebSocket aufrufen. + + Kurzantwort: **Koppeln Sie Ihren Computer als Node**. Das Gateway läuft anderswo, kann aber + `node.*`-Tools (Bildschirm, Kamera, System) auf Ihrer lokalen Maschine über den Gateway-WebSocket aufrufen. Typisches Setup: - 1. Führen Sie das Gateway auf dem always-on-Host aus (VPS/Homeserver). - 2. Bringen Sie den Gateway-Host und Ihren Rechner in dasselbe Tailnet. - 3. Stellen Sie sicher, dass der Gateway-WS erreichbar ist (Tailnet-Bind oder SSH-Tunnel). - 4. Öffnen Sie die macOS-App lokal und verbinden Sie sich im Modus **Remote over SSH** (oder direkt per Tailnet), + 1. Führen Sie das Gateway auf dem Always-on-Host aus (VPS/Homeserver). + 2. Bringen Sie den Gateway-Host und Ihren Computer in dasselbe Tailnet. + 3. Stellen Sie sicher, dass der Gateway-WS erreichbar ist (Tailnet-Bindung oder SSH-Tunnel). + 4. Öffnen Sie lokal die macOS-App und verbinden Sie sich im Modus **Remote over SSH** (oder direkt über Tailnet), damit sie sich als Node registrieren kann. 5. Genehmigen Sie den Node auf dem Gateway: @@ -1738,12 +1737,12 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. openclaw devices approve ``` - Es ist keine separate TCP-Bridge erforderlich; Nodes verbinden sich über den Gateway WebSocket. + Es ist keine separate TCP-Bridge erforderlich; Nodes verbinden sich über den Gateway-WebSocket. - Sicherheitserinnerung: Das Koppeln eines macOS-Node erlaubt `system.run` auf diesem Rechner. Koppeln Sie nur - Geräte, denen Sie vertrauen, und lesen Sie [Security](/de/gateway/security). + Sicherheitshinweis: Das Koppeln eines macOS Node erlaubt `system.run` auf dieser Maschine. Koppeln Sie nur + Geräte, denen Sie vertrauen, und lesen Sie [Sicherheit](/de/gateway/security). - Docs: [Nodes](/de/nodes), [Gateway protocol](/de/gateway/protocol), [macOS remote mode](/de/platforms/mac/remote), [Security](/de/gateway/security). + Dokumentation: [Nodes](/de/nodes), [Gateway-Protokoll](/de/gateway/protocol), [macOS-Remote-Modus](/de/platforms/mac/remote), [Sicherheit](/de/gateway/security). @@ -1751,94 +1750,94 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Prüfen Sie die Grundlagen: - Gateway läuft: `openclaw gateway status` - - Gateway-Health: `openclaw status` - - Kanal-Health: `openclaw channels status` + - Gateway-Zustand: `openclaw status` + - Kanal-Zustand: `openclaw channels status` Verifizieren Sie dann Authentifizierung und Routing: - Wenn Sie Tailscale Serve verwenden, stellen Sie sicher, dass `gateway.auth.allowTailscale` korrekt gesetzt ist. - - Wenn Sie sich über SSH-Tunnel verbinden, bestätigen Sie, dass der lokale Tunnel aktiv ist und auf den richtigen Port zeigt. - - Bestätigen Sie, dass Ihre Zulassungslisten (DM oder Gruppe) Ihr Konto enthalten. + - Wenn Sie sich über einen SSH-Tunnel verbinden, bestätigen Sie, dass der lokale Tunnel aktiv ist und auf den richtigen Port zeigt. + - Bestätigen Sie, dass Ihre Allowlists (DM oder Gruppe) Ihr Konto enthalten. - Docs: [Tailscale](/de/gateway/tailscale), [Remote access](/de/gateway/remote), [Channels](/de/channels). + Dokumentation: [Tailscale](/de/gateway/tailscale), [Remote-Zugriff](/de/gateway/remote), [Kanäle](/de/channels). Ja. Es gibt keine eingebaute „Bot-zu-Bot“-Bridge, aber Sie können das auf einige - zuverlässige Arten verdrahten: + zuverlässige Arten aufsetzen: - **Am einfachsten:** Verwenden Sie einen normalen Chat-Kanal, auf den beide Bots Zugriff haben (Telegram/Slack/WhatsApp). + **Am einfachsten:** Verwenden Sie einen normalen Chat-Kanal, auf den beide Bots zugreifen können (Telegram/Slack/WhatsApp). Lassen Sie Bot A eine Nachricht an Bot B senden, und lassen Sie Bot B dann wie gewohnt antworten. **CLI-Bridge (generisch):** Führen Sie ein Skript aus, das das andere Gateway mit - `openclaw agent --message ... --deliver` aufruft, gerichtet an einen Chat, in dem der andere Bot + `openclaw agent --message ... --deliver` aufruft und auf einen Chat zielt, in dem der andere Bot zuhört. Wenn ein Bot auf einem Remote-VPS läuft, richten Sie Ihre CLI auf dieses Remote-Gateway - per SSH/Tailscale aus (siehe [Remote access](/de/gateway/remote)). + über SSH/Tailscale aus (siehe [Remote-Zugriff](/de/gateway/remote)). - Beispielmuster (ausgeführt von einem Rechner, der das Ziel-Gateway erreichen kann): + Beispielmuster (von einer Maschine ausführen, die das Ziel-Gateway erreichen kann): ```bash - openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to + openclaw agent --message "Hallo vom lokalen Bot" --deliver --channel telegram --reply-to ``` - Tipp: Fügen Sie ein Guardrail hinzu, damit die beiden Bots nicht endlos schleifen (nur Erwähnung, Kanal- - zulassungslisten oder eine Regel „nicht auf Bot-Nachrichten antworten“). + Tipp: Fügen Sie eine Guardrail hinzu, damit die beiden Bots nicht endlos in Schleifen laufen (nur bei Erwähnung, Kanal- + Allowlists oder eine Regel „nicht auf Bot-Nachrichten antworten“). - Docs: [Remote access](/de/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/de/tools/agent-send). + Dokumentation: [Remote-Zugriff](/de/gateway/remote), [Agent-CLI](/cli/agent), [Agent send](/de/tools/agent-send). - Nein. Ein Gateway kann mehrere Agenten hosten, jeder mit eigenem Workspace, Standardmodellen + Nein. Ein Gateway kann mehrere Agenten hosten, jeder mit eigenem Workspace, Modell-Standards, und Routing. Das ist das normale Setup und viel günstiger und einfacher als ein VPS pro Agent. - Verwenden Sie separate VPSes nur, wenn Sie harte Isolation benötigen (Sicherheitsgrenzen) oder sehr - unterschiedliche Konfigurationen, die Sie nicht teilen möchten. Andernfalls behalten Sie ein Gateway und - verwenden mehrere Agenten oder Sub-Agents. + Verwenden Sie separate VPSes nur, wenn Sie harte Isolation (Sicherheitsgrenzen) oder sehr + unterschiedliche Konfigurationen brauchen, die Sie nicht teilen möchten. Andernfalls behalten Sie ein Gateway und + verwenden mehrere Agenten oder Sub-Agenten. - Ja – Nodes sind der erstklassige Weg, um von einem Remote-Gateway aus Ihren Laptop zu erreichen, und sie - ermöglichen mehr als nur Shell-Zugriff. Das Gateway läuft auf macOS/Linux (Windows über WSL2) und ist - leichtgewichtig (ein kleiner VPS oder eine Box in Raspberry-Pi-Klasse reicht aus; 4 GB RAM sind mehr als genug), daher ist ein häufiges + Ja – Nodes sind der erstklassige Weg, Ihren Laptop von einem Remote-Gateway aus zu erreichen, und sie + ermöglichen mehr als nur Shell-Zugriff. Das Gateway läuft unter macOS/Linux (Windows über WSL2) und ist + leichtgewichtig (ein kleiner VPS oder eine Box in Raspberry-Pi-Klasse reicht aus; 4 GB RAM sind reichlich), daher ist ein häufiges Setup ein Always-on-Host plus Ihr Laptop als Node. - - **Kein eingehendes SSH erforderlich.** Nodes verbinden sich ausgehend mit dem Gateway WebSocket und verwenden Device Pairing. - - **Sicherere Ausführungskontrollen.** `system.run` wird auf diesem Laptop durch Node-Zulassungslisten/Freigaben gesteuert. - - **Mehr Gerätetools.** Nodes stellen zusätzlich zu `system.run` auch `canvas`, `camera` und `screen` bereit. + - **Kein eingehendes SSH erforderlich.** Nodes verbinden sich ausgehend mit dem Gateway-WebSocket und verwenden Gerätekopplung. + - **Sicherere Ausführungssteuerung.** `system.run` wird auf diesem Laptop durch Node-Allowlists/Genehmigungen gesteuert. + - **Mehr Geräte-Tools.** Nodes stellen zusätzlich zu `system.run` auch `canvas`, `camera` und `screen` bereit. - **Lokale Browser-Automatisierung.** Behalten Sie das Gateway auf einem VPS, führen Sie Chrome aber lokal über einen Node-Host auf dem Laptop aus oder verbinden Sie sich über Chrome MCP mit lokalem Chrome auf dem Host. - SSH ist in Ordnung für ad-hoc-Shell-Zugriff, aber Nodes sind für laufende Agent-Workflows und + SSH ist für ad-hoc-Shell-Zugriff in Ordnung, aber Nodes sind für laufende Agent-Workflows und Geräteautomatisierung einfacher. - Docs: [Nodes](/de/nodes), [Nodes CLI](/cli/nodes), [Browser](/de/tools/browser). + Dokumentation: [Nodes](/de/nodes), [Nodes CLI](/cli/nodes), [Browser](/de/tools/browser). - Nein. Pro Host sollte nur **ein Gateway** laufen, außer Sie betreiben absichtlich isolierte Profile (siehe [Multiple gateways](/de/gateway/multiple-gateways)). Nodes sind Peripheriegeräte, die sich + Nein. Pro Host sollte nur **ein Gateway** laufen, es sei denn, Sie betreiben absichtlich isolierte Profile (siehe [Mehrere Gateways](/de/gateway/multiple-gateways)). Nodes sind Peripheriegeräte, die sich mit dem Gateway verbinden (iOS-/Android-Nodes oder macOS-„Node-Modus“ in der Menüleisten-App). Für headless Node- Hosts und CLI-Steuerung siehe [Node host CLI](/cli/node). - Für Änderungen an `gateway`, `discovery` und `canvasHost` ist ein vollständiger Neustart erforderlich. + Ein vollständiger Neustart ist für Änderungen an `gateway`, `discovery` und `canvasHost` erforderlich. - + Ja. - - `config.schema.lookup`: einen Konfigurations-Teilbaum mit flachem Schemaknoten, passendem UI-Hinweis und Zusammenfassungen der direkten Kindknoten vor dem Schreiben prüfen + - `config.schema.lookup`: einen Konfigurations-Teilbaum mit seinem flachen Schema-Knoten, passendem UI-Hinweis und unmittelbaren Child-Zusammenfassungen prüfen, bevor geschrieben wird - `config.get`: den aktuellen Snapshot + Hash abrufen - - `config.patch`: sicheres partielles Update (für die meisten RPC-Bearbeitungen bevorzugt); führt nach Möglichkeit Hot Reload durch und startet bei Bedarf neu - - `config.apply`: validieren + vollständige Konfiguration ersetzen; führt nach Möglichkeit Hot Reload durch und startet bei Bedarf neu - - Das nur für Eigentümer gedachte Laufzeit-Tool `gateway` weigert sich weiterhin, `tools.exec.ask` / `tools.exec.security` umzuschreiben; alte `tools.bash.*`-Aliasse werden auf dieselben geschützten Exec-Pfade normalisiert + - `config.patch`: sichere partielle Aktualisierung (für die meisten RPC-Bearbeitungen bevorzugt); führt nach Möglichkeit Hot-Reload aus und startet bei Bedarf neu + - `config.apply`: validiert + ersetzt die vollständige Konfiguration; führt nach Möglichkeit Hot-Reload aus und startet bei Bedarf neu + - Das nur für Eigentümer verfügbare Runtime-Tool `gateway` weigert sich weiterhin, `tools.exec.ask` / `tools.exec.security` umzuschreiben; Legacy-`tools.bash.*`-Aliasse normalisieren auf dieselben geschützten exec-Pfade - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1846,21 +1845,21 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. } ``` - Damit wird Ihr Workspace festgelegt und eingeschränkt, wer den Bot auslösen kann. + Dadurch wird Ihr Workspace gesetzt und eingeschränkt, wer den Bot auslösen kann. Minimale Schritte: - 1. **Auf dem VPS installieren + anmelden** + 1. **Installieren + auf dem VPS anmelden** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Auf Ihrem Mac installieren + anmelden** + 2. **Installieren + auf Ihrem Mac anmelden** - Verwenden Sie die Tailscale-App und melden Sie sich im selben Tailnet an. 3. **MagicDNS aktivieren (empfohlen)** - Aktivieren Sie in der Tailscale-Admin-Konsole MagicDNS, damit der VPS einen stabilen Namen hat. @@ -1874,16 +1873,16 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. openclaw gateway --tailscale serve ``` - Dadurch bleibt das Gateway an loopback gebunden und wird per Tailscale über HTTPS verfügbar gemacht. Siehe [Tailscale](/de/gateway/tailscale). + Dadurch bleibt das Gateway an loopback gebunden und stellt HTTPS über Tailscale bereit. Siehe [Tailscale](/de/gateway/tailscale). - Serve stellt **Gateway Control UI + WS** bereit. Nodes verbinden sich über denselben Gateway-WS-Endpunkt. + Serve stellt die **Gateway Control UI + WS** bereit. Nodes verbinden sich über denselben Gateway-WS-Endpunkt. Empfohlenes Setup: - 1. **Stellen Sie sicher, dass VPS + Mac im selben Tailnet sind**. + 1. **Stellen Sie sicher, dass sich VPS + Mac im selben Tailnet befinden**. 2. **Verwenden Sie die macOS-App im Remote-Modus** (das SSH-Ziel kann der Tailnet-Hostname sein). Die App tunnelt dann den Gateway-Port und verbindet sich als Node. 3. **Genehmigen Sie den Node** auf dem Gateway: @@ -1893,34 +1892,34 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. openclaw devices approve ``` - Docs: [Gateway protocol](/de/gateway/protocol), [Discovery](/de/gateway/discovery), [macOS remote mode](/de/platforms/mac/remote). + Dokumentation: [Gateway-Protokoll](/de/gateway/protocol), [Discovery](/de/gateway/discovery), [macOS-Remote-Modus](/de/platforms/mac/remote). - - Wenn Sie auf dem zweiten Laptop nur **lokale Tools** (Bildschirm/Kamera/Exec) benötigen, fügen Sie ihn als - **Node** hinzu. Dadurch bleibt ein einziges Gateway erhalten und doppelte Konfiguration wird vermieden. Lokale Node-Tools sind - derzeit nur für macOS verfügbar, wir planen aber, sie auf andere Betriebssysteme auszuweiten. + + Wenn Sie auf dem zweiten Laptop nur **lokale Tools** (Bildschirm/Kamera/exec) benötigen, fügen Sie ihn als + **Node** hinzu. Dadurch behalten Sie ein einzelnes Gateway und vermeiden doppelte Konfiguration. Lokale Node-Tools sind + derzeit nur unter macOS verfügbar, wir planen aber, sie auf weitere Betriebssysteme auszuweiten. - Installieren Sie nur dann ein zweites Gateway, wenn Sie **harte Isolation** oder zwei vollständig getrennte Bots benötigen. + Installieren Sie ein zweites Gateway nur dann, wenn Sie **harte Isolation** oder zwei vollständig getrennte Bots brauchen. - Docs: [Nodes](/de/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/de/gateway/multiple-gateways). + Dokumentation: [Nodes](/de/nodes), [Nodes CLI](/cli/nodes), [Mehrere Gateways](/de/gateway/multiple-gateways). -## Env-Variablen und Laden von `.env` +## Umgebungsvariablen und .env-Laden - OpenClaw liest Env-Variablen aus dem übergeordneten Prozess (Shell, launchd/systemd, CI usw.) und lädt zusätzlich: + OpenClaw liest Umgebungsvariablen aus dem Parent-Prozess (Shell, launchd/systemd, CI usw.) und lädt zusätzlich: - `.env` aus dem aktuellen Arbeitsverzeichnis - eine globale Fallback-`.env` aus `~/.openclaw/.env` (auch bekannt als `$OPENCLAW_STATE_DIR/.env`) - Keine `.env`-Datei überschreibt bestehende Env-Variablen. + Keine der beiden `.env`-Dateien überschreibt bestehende Umgebungsvariablen. - Sie können auch Inline-Env-Variablen in der Konfiguration definieren (werden nur angewendet, wenn sie im Prozess-Env fehlen): + Sie können auch Inline-Umgebungsvariablen in der Konfiguration definieren (werden nur angewendet, wenn sie in der Prozessumgebung fehlen): ```json5 { @@ -1935,11 +1934,11 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - + Zwei häufige Lösungen: - 1. Legen Sie die fehlenden Schlüssel in `~/.openclaw/.env` ab, damit sie auch dann erfasst werden, wenn der Service Ihre Shell-Umgebung nicht erbt. - 2. Aktivieren Sie Shell-Import (optionale Komfortfunktion): + 1. Legen Sie die fehlenden Schlüssel in `~/.openclaw/.env` ab, damit sie auch dann übernommen werden, wenn der Service Ihre Shell-Umgebung nicht erbt. + 2. Aktivieren Sie Shell-Import (Opt-in-Komfortfunktion): ```json5 { @@ -1952,27 +1951,27 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. } ``` - Dadurch wird Ihre Login-Shell ausgeführt und nur fehlende erwartete Schlüssel werden importiert (nie überschrieben). Äquivalente Env-Variablen: + Dadurch wird Ihre Login-Shell ausgeführt und es werden nur fehlende erwartete Schlüssel importiert (nie überschrieben). Äquivalente Umgebungsvariablen: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - + `openclaw models status` meldet, ob **Shell-Env-Import** aktiviert ist. „Shell env: off“ - bedeutet **nicht**, dass Ihre Env-Variablen fehlen – es bedeutet nur, dass OpenClaw Ihre - Login-Shell nicht automatisch lädt. + bedeutet **nicht**, dass Ihre Umgebungsvariablen fehlen – es bedeutet nur, dass OpenClaw + Ihre Login-Shell nicht automatisch lädt. Wenn das Gateway als Service läuft (launchd/systemd), erbt es Ihre Shell- Umgebung nicht. Beheben Sie das auf eine dieser Arten: - 1. Legen Sie den Token in `~/.openclaw/.env` ab: + 1. Legen Sie das Token in `~/.openclaw/.env` ab: ``` COPILOT_GITHUB_TOKEN=... ``` 2. Oder aktivieren Sie Shell-Import (`env.shellEnv.enabled: true`). - 3. Oder fügen Sie ihn Ihrem `env`-Block in der Konfiguration hinzu (wird nur angewendet, wenn er fehlt). + 3. Oder fügen Sie es in Ihren `env`-Block der Konfiguration ein (gilt nur, wenn es fehlt). Starten Sie dann das Gateway neu und prüfen Sie erneut: @@ -1990,14 +1989,14 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - Senden Sie `/new` oder `/reset` als eigenständige Nachricht. Siehe [Session management](/de/concepts/session). + Senden Sie `/new` oder `/reset` als eigenständige Nachricht. Siehe [Sitzungsverwaltung](/de/concepts/session). - Sitzungen können nach `session.idleMinutes` ablaufen, aber dies ist **standardmäßig deaktiviert** (Standard **0**). - Setzen Sie den Wert auf einen positiven Wert, um den Inaktivitätsablauf zu aktivieren. Wenn aktiviert, startet die **nächste** - Nachricht nach der Inaktivitätsperiode eine neue Sitzungs-ID für diesen Chat-Schlüssel. - Dadurch werden keine Transkripte gelöscht – es beginnt nur eine neue Sitzung. + Sitzungen können nach `session.idleMinutes` ablaufen, dies ist aber **standardmäßig deaktiviert** (Standard **0**). + Setzen Sie einen positiven Wert, um den Leerlauf-Ablauf zu aktivieren. Wenn er aktiviert ist, startet die **nächste** + Nachricht nach dem Leerlaufzeitraum eine neue Sitzungs-ID für diesen Chat-Schlüssel. + Dadurch werden Transkripte nicht gelöscht – es wird nur eine neue Sitzung gestartet. ```json5 { @@ -2009,47 +2008,47 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - - Ja, über **Multi-Agent Routing** und **Sub-Agents**. Sie können einen koordinierenden - Agenten und mehrere Worker-Agenten mit eigenen Workspaces und Modellen erstellen. + + Ja, über **Multi-Agent-Routing** und **Sub-Agenten**. Sie können einen Koordinator- + Agenten und mehrere Worker-Agenten mit ihren eigenen Workspaces und Modellen erstellen. - Dennoch sollte man das am besten als **spaßiges Experiment** sehen. Es verbraucht viele Tokens und ist oft - weniger effizient, als einen Bot mit getrennten Sitzungen zu verwenden. Das typische Modell, das wir + Allerdings sollte dies eher als **lustiges Experiment** gesehen werden. Es ist tokenintensiv und oft + weniger effizient als ein Bot mit getrennten Sitzungen. Das typische Modell, das wir uns vorstellen, ist ein Bot, mit dem Sie sprechen, mit verschiedenen Sitzungen für parallele Arbeit. Dieser - Bot kann bei Bedarf auch Sub-Agents starten. + Bot kann bei Bedarf auch Sub-Agenten starten. - Docs: [Multi-agent routing](/de/concepts/multi-agent), [Sub-agents](/de/tools/subagents), [Agents CLI](/cli/agents). + Dokumentation: [Multi-Agent-Routing](/de/concepts/multi-agent), [Sub-Agenten](/de/tools/subagents), [Agents CLI](/cli/agents). Der Sitzungskontext ist durch das Modellfenster begrenzt. Lange Chats, große Tool-Ausgaben oder viele - Dateien können Compaction oder Trunkierung auslösen. + Dateien können Compaction oder Kürzung auslösen. - Was hilft: + Hilfreich ist: - - Bitten Sie den Bot, den aktuellen Status zusammenzufassen und in eine Datei zu schreiben. - - Verwenden Sie `/compact` vor langen Aufgaben und `/new`, wenn Sie das Thema wechseln. + - Bitten Sie den Bot, den aktuellen Stand zusammenzufassen und in eine Datei zu schreiben. + - Verwenden Sie `/compact` vor langen Aufgaben und `/new` beim Themenwechsel. - Halten Sie wichtigen Kontext im Workspace und bitten Sie den Bot, ihn erneut zu lesen. - - Verwenden Sie Sub-Agents für lange oder parallele Arbeit, damit der Hauptchat kleiner bleibt. + - Verwenden Sie Sub-Agenten für lange oder parallele Arbeit, damit der Hauptchat kleiner bleibt. - Wählen Sie ein Modell mit größerem Kontextfenster, wenn das häufig passiert. - + Verwenden Sie den Reset-Befehl: ```bash openclaw reset ``` - Nicht-interaktiver vollständiger Reset: + Nicht interaktiver vollständiger Reset: ```bash openclaw reset --scope full --yes --non-interactive ``` - Führen Sie dann das Setup erneut aus: + Führen Sie dann die Einrichtung erneut aus: ```bash openclaw onboard --install-daemon @@ -2057,16 +2056,16 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Hinweise: - - Onboarding bietet auch **Reset** an, wenn es eine bestehende Konfiguration erkennt. Siehe [Onboarding (CLI)](/de/start/wizard). - - Wenn Sie Profile verwendet haben (`--profile` / `OPENCLAW_PROFILE`), setzen Sie jedes State-Verzeichnis zurück (Standards sind `~/.openclaw-`). - - Dev-Reset: `openclaw gateway --dev --reset` (nur für Entwicklung; löscht Dev-Konfiguration + Credentials + Sitzungen + Workspace). + - Onboarding bietet auch **Reset** an, wenn eine bestehende Konfiguration erkannt wird. Siehe [Onboarding (CLI)](/de/start/wizard). + - Wenn Sie Profile verwendet haben (`--profile` / `OPENCLAW_PROFILE`), setzen Sie jedes State-Verzeichnis zurück (Standardwerte sind `~/.openclaw-`). + - Dev-Reset: `openclaw gateway --dev --reset` (nur für Entwicklung; löscht Dev-Konfiguration + Anmeldedaten + Sitzungen + Workspace). - + Verwenden Sie eine dieser Möglichkeiten: - - **Compaction** (behält die Unterhaltung, fasst aber ältere Züge zusammen): + - **Compaction** (behält die Unterhaltung, fasst aber ältere Turns zusammen): ``` /compact @@ -2074,7 +2073,7 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. oder `/compact `, um die Zusammenfassung zu steuern. - - **Reset** (neue Sitzungs-ID für denselben Chat-Schlüssel): + - **Zurücksetzen** (neue Sitzungs-ID für denselben Chat-Schlüssel): ``` /new @@ -2083,24 +2082,24 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Wenn es weiterhin passiert: - - Aktivieren oder justieren Sie **Session Pruning** (`agents.defaults.contextPruning`), um alte Tool-Ausgaben zu kürzen. + - Aktivieren oder optimieren Sie **Session Pruning** (`agents.defaults.contextPruning`), um alte Tool-Ausgaben zu kürzen. - Verwenden Sie ein Modell mit größerem Kontextfenster. - Docs: [Compaction](/de/concepts/compaction), [Session pruning](/de/concepts/session-pruning), [Session management](/de/concepts/session). + Dokumentation: [Compaction](/de/concepts/compaction), [Session Pruning](/de/concepts/session-pruning), [Sitzungsverwaltung](/de/concepts/session). Dies ist ein Provider-Validierungsfehler: Das Modell hat einen `tool_use`-Block ohne das erforderliche - `input` ausgegeben. Das bedeutet meist, dass der Sitzungsverlauf veraltet oder beschädigt ist (oft nach langen Threads - oder einer Tool-/Schema-Änderung). + `input` ausgegeben. Das bedeutet normalerweise, dass der Sitzungsverlauf veraltet oder beschädigt ist (oft nach langen Threads + oder einer Änderung an Tool/Schema). - Lösung: Starten Sie mit `/new` (eigenständige Nachricht) eine neue Sitzung. + Lösung: Starten Sie mit `/new` eine frische Sitzung (eigenständige Nachricht). - Heartbeats laufen standardmäßig alle **30m** (**1h** bei Verwendung von OAuth-Authentifizierung). Passen Sie sie an oder deaktivieren Sie sie: + Heartbeats laufen standardmäßig alle **30 m** (**1 h** bei Verwendung von OAuth-Auth). Passen Sie sie an oder deaktivieren Sie sie: ```json5 { @@ -2114,19 +2113,19 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. } ``` - Wenn `HEARTBEAT.md` existiert, aber effektiv leer ist (nur leere Zeilen und Markdown- + Wenn `HEARTBEAT.md` existiert, aber praktisch leer ist (nur Leerzeilen und Markdown- Überschriften wie `# Heading`), überspringt OpenClaw den Heartbeat-Lauf, um API-Aufrufe zu sparen. Wenn die Datei fehlt, läuft der Heartbeat trotzdem und das Modell entscheidet, was zu tun ist. - Überschreibungen pro Agent verwenden `agents.list[].heartbeat`. Docs: [Heartbeat](/de/gateway/heartbeat). + Pro-Agent-Overrides verwenden `agents.list[].heartbeat`. Dokumentation: [Heartbeat](/de/gateway/heartbeat). - - Nein. OpenClaw läuft auf **Ihrem eigenen Konto**, also kann OpenClaw die Gruppe sehen, wenn Sie in der Gruppe sind. - Standardmäßig werden Gruppenantworten blockiert, bis Sie Absender zulassen (`groupPolicy: "allowlist"`). + + Nein. OpenClaw läuft auf **Ihrem eigenen Konto**, also kann OpenClaw die Gruppe sehen, wenn Sie darin sind. + Standardmäßig sind Gruppenantworten blockiert, bis Sie Absender erlauben (`groupPolicy: "allowlist"`). - Wenn Sie möchten, dass nur **Sie** Gruppenantworten auslösen können: + Wenn nur **Sie** Gruppenantworten auslösen können sollen: ```json5 { @@ -2142,7 +2141,7 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - Option 1 (am schnellsten): Logs verfolgen und eine Testnachricht in die Gruppe senden: + Option 1 (am schnellsten): Logs mitverfolgen und eine Testnachricht in die Gruppe senden: ```bash openclaw logs --follow --json @@ -2151,116 +2150,116 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Suchen Sie nach `chatId` (oder `from`), das auf `@g.us` endet, zum Beispiel: `1234567890-1234567890@g.us`. - Option 2 (wenn bereits konfiguriert/auf der Zulassungsliste): Gruppen aus der Konfiguration auflisten: + Option 2 (wenn bereits konfiguriert/auf der Allowlist): Gruppen aus der Konfiguration auflisten: ```bash openclaw directory groups list --channel whatsapp ``` - Docs: [WhatsApp](/de/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). + Dokumentation: [WhatsApp](/de/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). Zwei häufige Ursachen: - - Erwähnungssteuerung ist aktiv (Standard). Sie müssen den Bot per @mention erwähnen (oder `mentionPatterns` treffen). - - Sie haben `channels.whatsapp.groups` ohne `"*"` konfiguriert und die Gruppe steht nicht auf der Zulassungsliste. + - Mention-Gating ist aktiviert (Standard). Sie müssen den Bot mit @ erwähnen (oder `mentionPatterns` treffen). + - Sie haben `channels.whatsapp.groups` ohne `"*"` konfiguriert und die Gruppe steht nicht auf der Allowlist. - Siehe [Groups](/de/channels/groups) und [Group messages](/de/channels/group-messages). + Siehe [Gruppen](/de/channels/groups) und [Gruppennachrichten](/de/channels/group-messages). - - Direktchats fallen standardmäßig in die Hauptsitzung zusammen. Gruppen/Kanäle haben ihre eigenen Sitzungsschlüssel, und Telegram-Themen / Discord-Threads sind separate Sitzungen. Siehe [Groups](/de/channels/groups) und [Group messages](/de/channels/group-messages). + + Direktchats werden standardmäßig in die Hauptsitzung zusammengeführt. Gruppen/Kanäle haben ihre eigenen Sitzungsschlüssel, und Telegram-Themen / Discord-Threads sind getrennte Sitzungen. Siehe [Gruppen](/de/channels/groups) und [Gruppennachrichten](/de/channels/group-messages). Keine harten Limits. Dutzende (sogar Hunderte) sind in Ordnung, aber achten Sie auf: - - **Wachstum des Speicherplatzes:** Sitzungen + Transkripte liegen unter `~/.openclaw/agents//sessions/`. - - **Token-Kosten:** mehr Agenten bedeuten mehr gleichzeitige Modellnutzung. - - **Ops-Overhead:** agentenspezifische Auth-Profile, Workspaces und Kanal-Routing. + - **Wachstum des Speicherplatzbedarfs:** Sitzungen + Transkripte liegen unter `~/.openclaw/agents//sessions/`. + - **Token-Kosten:** Mehr Agenten bedeuten mehr gleichzeitige Modellnutzung. + - **Ops-Aufwand:** Pro-Agent-Auth-Profile, Workspaces und Kanal-Routing. Tipps: - - Halten Sie einen **aktiven** Workspace pro Agent (`agents.defaults.workspace`). - - Bereinigen Sie alte Sitzungen (JSONL- oder Store-Einträge löschen), wenn der Speicherplatz wächst. - - Verwenden Sie `openclaw doctor`, um verirrte Workspaces und Profil-Mismatches zu erkennen. + - Behalten Sie pro Agent einen **aktiven** Workspace (`agents.defaults.workspace`). + - Bereinigen Sie alte Sitzungen (löschen Sie JSONL- oder Store-Einträge), wenn der Speicherplatzbedarf wächst. + - Verwenden Sie `openclaw doctor`, um verstreute Workspaces und Profil-Mismatches zu erkennen. - Ja. Verwenden Sie **Multi-Agent Routing**, um mehrere isolierte Agenten auszuführen und eingehende Nachrichten nach + Ja. Verwenden Sie **Multi-Agent-Routing**, um mehrere isolierte Agenten auszuführen und eingehende Nachrichten nach Kanal/Konto/Peer zu routen. Slack wird als Kanal unterstützt und kann an bestimmte Agenten gebunden werden. - Browser-Zugriff ist leistungsfähig, aber nicht „alles, was ein Mensch kann“ – Anti-Bot, CAPTCHAs und MFA können - Automatisierung weiterhin blockieren. Für die zuverlässigste Browsersteuerung verwenden Sie lokales Chrome MCP auf dem Host - oder CDP auf dem Rechner, auf dem der Browser tatsächlich läuft. + Browser-Zugriff ist leistungsstark, aber nicht „alles, was ein Mensch kann“ – Anti-Bot, CAPTCHAs und MFA können + Automatisierung weiterhin blockieren. Für die zuverlässigste Browser-Steuerung verwenden Sie lokales Chrome MCP auf dem Host + oder CDP auf der Maschine, auf der der Browser tatsächlich läuft. Best-Practice-Setup: - Always-on-Gateway-Host (VPS/Mac mini). - Ein Agent pro Rolle (Bindings). - - Slack-Kanal/-Kanäle an diese Agenten gebunden. - - Lokaler Browser über Chrome MCP oder bei Bedarf ein Node. + - An diese Agenten gebundene Slack-Kanäle. + - Lokaler Browser über Chrome MCP oder bei Bedarf einen Node. - Docs: [Multi-Agent Routing](/de/concepts/multi-agent), [Slack](/de/channels/slack), + Dokumentation: [Multi-Agent-Routing](/de/concepts/multi-agent), [Slack](/de/channels/slack), [Browser](/de/tools/browser), [Nodes](/de/nodes). -## Modelle: Standardwerte, Auswahl, Aliasse, Umschalten +## Modelle: Standards, Auswahl, Aliasse, Wechsel - Das Standardmodell von OpenClaw ist das, was Sie hier festlegen: + Das Standardmodell von OpenClaw ist das, was Sie hier setzen: ``` agents.defaults.model.primary ``` - Modelle werden als `provider/model` referenziert (Beispiel: `openai/gpt-5.4`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann einen eindeutigen Treffer eines konfigurierten Providers für genau diese Modell-ID und fällt erst danach als veralteten Kompatibilitätspfad auf den konfigurierten Standard-Provider zurück. Wenn dieser Provider das konfigurierte Standardmodell nicht mehr anbietet, fällt OpenClaw auf das erste konfigurierte Provider-/Modellpaar zurück, statt einen veralteten entfernten Provider-Standard anzuzeigen. Sie sollten dennoch **explizit** `provider/model` setzen. + Modelle werden als `provider/model` referenziert (Beispiel: `openai/gpt-5.4`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige configured-provider-Übereinstimmung für genau diese Modell-ID und greift erst danach als veralteten Kompatibilitätspfad auf den konfigurierten Standard-Provider zurück. Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, greift OpenClaw auf das erste konfigurierte Provider-/Modellpaar zurück, statt ein veraltetes entferntes Provider-Standardmodell anzuzeigen. Sie sollten dennoch **explizit** `provider/model` setzen. - **Empfohlener Standard:** Verwenden Sie das stärkste Modell der neuesten Generation, das in Ihrem Provider-Stack verfügbar ist. - **Für tool-fähige Agenten oder nicht vertrauenswürdige Eingaben:** Priorisieren Sie Modellstärke vor Kosten. + **Empfohlener Standard:** Verwenden Sie das stärkste aktuelle Modell, das in Ihrem Provider-Stack verfügbar ist. + **Für tool-fähige Agenten oder Agenten mit nicht vertrauenswürdigen Eingaben:** Priorisieren Sie Modellstärke vor Kosten. **Für Routine-/Low-Stakes-Chat:** Verwenden Sie günstigere Fallback-Modelle und routen Sie nach Agentenrolle. - MiniMax hat eigene Docs: [MiniMax](/de/providers/minimax) und - [Local models](/de/gateway/local-models). + MiniMax hat eigene Dokumentation: [MiniMax](/de/providers/minimax) und + [Lokale Modelle](/de/gateway/local-models). - Faustregel: Verwenden Sie für hochkritische Arbeit das **beste Modell, das Sie sich leisten können**, und ein günstigeres - Modell für Routine-Chat oder Zusammenfassungen. Sie können Modelle pro Agent routen und Sub-Agents verwenden, um - lange Aufgaben zu parallelisieren (jeder Sub-Agent verbraucht Tokens). Siehe [Models](/de/concepts/models) und - [Sub-agents](/de/tools/subagents). + Faustregel: Verwenden Sie für risikoreiche Arbeit das **beste Modell, das Sie sich leisten können**, und ein günstigeres + Modell für Routine-Chat oder Zusammenfassungen. Sie können Modelle pro Agent routen und Sub-Agenten verwenden, um + lange Aufgaben zu parallelisieren (jeder Sub-Agent verbraucht Tokens). Siehe [Modelle](/de/concepts/models) und + [Sub-Agenten](/de/tools/subagents). - Deutliche Warnung: Schwächere/zu stark quantisierte Modelle sind anfälliger für Prompt - Injection und unsicheres Verhalten. Siehe [Security](/de/gateway/security). + Deutliche Warnung: Schwächere/übermäßig quantisierte Modelle sind anfälliger für Prompt + Injection und unsicheres Verhalten. Siehe [Sicherheit](/de/gateway/security). - Mehr Kontext: [Models](/de/concepts/models). + Mehr Kontext: [Modelle](/de/concepts/models). - Verwenden Sie **Modellbefehle** oder bearbeiten Sie nur die **Modell**-Felder. Vermeiden Sie vollständiges Ersetzen der Konfiguration. + Verwenden Sie **Modell-Befehle** oder bearbeiten Sie nur die Felder für das **Modell**. Vermeiden Sie vollständiges Ersetzen der Konfiguration. Sichere Optionen: - `/model` im Chat (schnell, pro Sitzung) - - `openclaw models set ...` (aktualisiert nur die Modellkonfiguration) + - `openclaw models set ...` (aktualisiert nur die Modell-Konfiguration) - `openclaw configure --section model` (interaktiv) - `agents.defaults.model` in `~/.openclaw/openclaw.json` bearbeiten - Vermeiden Sie `config.apply` mit einem partiellen Objekt, außer Sie möchten wirklich die ganze Konfiguration ersetzen. - Für RPC-Bearbeitungen prüfen Sie zuerst mit `config.schema.lookup` und bevorzugen `config.patch`. Die Lookup-Payload liefert Ihnen den normalisierten Pfad, flache Schema-Dokumentation/-Constraints und Zusammenfassungen der direkten Kindknoten - für partielle Updates. - Wenn Sie die Konfiguration doch überschrieben haben, stellen Sie sie aus einem Backup wieder her oder führen Sie `openclaw doctor` erneut aus, um zu reparieren. + Vermeiden Sie `config.apply` mit einem partiellen Objekt, es sei denn, Sie möchten die gesamte Konfiguration ersetzen. + Für RPC-Bearbeitungen zuerst mit `config.schema.lookup` prüfen und `config.patch` bevorzugen. Die Lookup-Payload gibt Ihnen den normalisierten Pfad, flache Schema-Dokumentation/-Constraints und unmittelbare Child-Zusammenfassungen + für partielle Aktualisierungen. + Wenn Sie die Konfiguration doch überschrieben haben, stellen Sie sie aus einem Backup wieder her oder führen Sie `openclaw doctor` erneut aus, um sie zu reparieren. - Docs: [Models](/de/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/de/gateway/doctor). + Dokumentation: [Modelle](/de/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/de/gateway/doctor). @@ -2270,7 +2269,7 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Schnellstes Setup: 1. Installieren Sie Ollama von `https://ollama.com/download` - 2. Ziehen Sie ein lokales Modell wie `ollama pull gemma4` + 2. Pullen Sie ein lokales Modell wie `ollama pull gemma4` 3. Wenn Sie auch Cloud-Modelle möchten, führen Sie `ollama signin` aus 4. Führen Sie `openclaw onboard` aus und wählen Sie `Ollama` 5. Wählen Sie `Local` oder `Cloud + Local` @@ -2279,25 +2278,25 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - `Cloud + Local` gibt Ihnen Cloud-Modelle plus Ihre lokalen Ollama-Modelle - Cloud-Modelle wie `kimi-k2.5:cloud` benötigen keinen lokalen Pull - - Für manuelles Umschalten verwenden Sie `openclaw models list` und `openclaw models set ollama/` + - Für manuelles Wechseln verwenden Sie `openclaw models list` und `openclaw models set ollama/` Sicherheitshinweis: Kleinere oder stark quantisierte Modelle sind anfälliger für Prompt Injection. Wir empfehlen für jeden Bot, der Tools verwenden kann, dringend **große Modelle**. - Wenn Sie trotzdem kleine Modelle möchten, aktivieren Sie Sandboxing und strikte Tool-Zulassungslisten. + Wenn Sie dennoch kleine Modelle verwenden möchten, aktivieren Sie Sandboxing und strikte Tool-Allowlists. - Docs: [Ollama](/de/providers/ollama), [Local models](/de/gateway/local-models), - [Model providers](/de/concepts/model-providers), [Security](/de/gateway/security), + Dokumentation: [Ollama](/de/providers/ollama), [Lokale Modelle](/de/gateway/local-models), + [Modell-Provider](/de/concepts/model-providers), [Sicherheit](/de/gateway/security), [Sandboxing](/de/gateway/sandboxing). - - Diese Deployments können sich unterscheiden und sich im Laufe der Zeit ändern; es gibt keine feste Provider-Empfehlung. + - Diese Deployments können unterschiedlich sein und sich mit der Zeit ändern; es gibt keine feste Provider-Empfehlung. - Prüfen Sie die aktuelle Laufzeiteinstellung auf jedem Gateway mit `openclaw models status`. - - Für sicherheitssensible/tool-fähige Agenten verwenden Sie das stärkste Modell der neuesten Generation, das verfügbar ist. + - Für sicherheitssensitive/tool-fähige Agenten verwenden Sie das stärkste aktuelle Modell, das verfügbar ist. - + Verwenden Sie den Befehl `/model` als eigenständige Nachricht: ``` @@ -2312,9 +2311,9 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Dies sind die eingebauten Aliasse. Benutzerdefinierte Aliasse können über `agents.defaults.models` hinzugefügt werden. - Verfügbare Modelle können Sie mit `/model`, `/model list` oder `/model status` auflisten. + Sie können verfügbare Modelle mit `/model`, `/model list` oder `/model status` auflisten. - `/model` (und `/model list`) zeigt eine kompakte, nummerierte Auswahl. Auswahl per Nummer: + `/model` (und `/model list`) zeigt einen kompakten nummerierten Picker. Wählen Sie per Nummer: ``` /model 3 @@ -2327,10 +2326,10 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. /model opus@anthropic:work ``` - Tipp: `/model status` zeigt, welcher Agent aktiv ist, welche Datei `auth-profiles.json` verwendet wird und welches Auth-Profil als Nächstes versucht wird. - Es zeigt außerdem den konfigurierten Provider-Endpunkt (`baseUrl`) und den API-Modus (`api`), wenn verfügbar. + Tipp: `/model status` zeigt, welcher Agent aktiv ist, welche `auth-profiles.json`-Datei verwendet wird und welches Auth-Profil als Nächstes versucht wird. + Außerdem werden der konfigurierte Provider-Endpunkt (`baseUrl`) und der API-Modus (`api`) angezeigt, wenn verfügbar. - **Wie löse ich die Fixierung eines mit @profile gesetzten Profils?** + **Wie löse ich die Profilanheftung, die ich mit @profile gesetzt habe?** Führen Sie `/model` erneut **ohne** den Suffix `@profile` aus: @@ -2338,28 +2337,28 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. /model anthropic/claude-opus-4-6 ``` - Wenn Sie zum Standard zurückkehren möchten, wählen Sie ihn aus `/model` (oder senden Sie `/model `). + Wenn Sie zum Standard zurückkehren möchten, wählen Sie ihn über `/model` aus (oder senden Sie `/model `). Verwenden Sie `/model status`, um zu bestätigen, welches Auth-Profil aktiv ist. - - Ja. Setzen Sie eines als Standard und wechseln Sie bei Bedarf: + + Ja. Setzen Sie eines als Standard und wechseln Sie nach Bedarf: - - **Schneller Wechsel (pro Sitzung):** `/model gpt-5.4` für tägliche Aufgaben, `/model openai-codex/gpt-5.4` fürs Coding mit Codex OAuth. - - **Standard + Wechsel:** setzen Sie `agents.defaults.model.primary` auf `openai/gpt-5.4` und wechseln Sie dann beim Coding zu `openai-codex/gpt-5.4` (oder umgekehrt). - - **Sub-Agents:** Leiten Sie Coding-Aufgaben an Sub-Agents mit einem anderen Standardmodell weiter. + - **Schneller Wechsel (pro Sitzung):** `/model gpt-5.4` für tägliche Aufgaben, `/model openai-codex/gpt-5.4` fürs Programmieren mit Codex OAuth. + - **Standard + Wechsel:** Setzen Sie `agents.defaults.model.primary` auf `openai/gpt-5.4` und wechseln Sie dann beim Programmieren zu `openai-codex/gpt-5.4` (oder umgekehrt). + - **Sub-Agenten:** Leiten Sie Programmieraufgaben an Sub-Agenten mit einem anderen Standardmodell weiter. - Siehe [Models](/de/concepts/models) und [Slash commands](/de/tools/slash-commands). + Siehe [Modelle](/de/concepts/models) und [Slash-Befehle](/de/tools/slash-commands). - - Verwenden Sie entweder einen Sitzungsschalter oder einen Konfigurationsstandard: + + Verwenden Sie entweder einen Sitzungs-Toggle oder einen Konfigurationsstandard: - - **Pro Sitzung:** senden Sie `/fast on`, während die Sitzung `openai/gpt-5.4` oder `openai-codex/gpt-5.4` verwendet. - - **Standard pro Modell:** setzen Sie `agents.defaults.models["openai/gpt-5.4"].params.fastMode` auf `true`. - - **Auch Codex OAuth:** wenn Sie zusätzlich `openai-codex/gpt-5.4` verwenden, setzen Sie dort dasselbe Flag. + - **Pro Sitzung:** Senden Sie `/fast on`, während die Sitzung `openai/gpt-5.4` oder `openai-codex/gpt-5.4` verwendet. + - **Standard pro Modell:** Setzen Sie `agents.defaults.models["openai/gpt-5.4"].params.fastMode` auf `true`. + - **Auch für Codex OAuth:** Wenn Sie außerdem `openai-codex/gpt-5.4` verwenden, setzen Sie dort dieselbe Flag. Beispiel: @@ -2384,22 +2383,22 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. } ``` - Für OpenAI wird der schnelle Modus bei unterstützten nativen Responses-Anfragen auf `service_tier = "priority"` abgebildet. Sitzungsschalter über `/fast` haben Vorrang vor Konfigurationsstandards. + Für OpenAI wird Fast Mode bei unterstützten nativen Responses-Requests auf `service_tier = "priority"` abgebildet. Sitzungs-`/fast`-Overrides haben Vorrang vor Konfigurationsstandards. Siehe [Thinking and fast mode](/de/tools/thinking) und [OpenAI fast mode](/de/providers/openai#openai-fast-mode). - - Wenn `agents.defaults.models` gesetzt ist, wird es zur **Zulassungsliste** für `/model` und alle - Sitzungsüberschreibungen. Wenn Sie ein Modell wählen, das nicht in dieser Liste steht, erhalten Sie: + + Wenn `agents.defaults.models` gesetzt ist, wird es zur **Allowlist** für `/model` und alle + Sitzungs-Overrides. Wenn Sie ein Modell wählen, das nicht in dieser Liste steht, erhalten Sie: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` Dieser Fehler wird **anstelle** einer normalen Antwort zurückgegeben. Lösung: Fügen Sie das Modell zu - `agents.defaults.models` hinzu, entfernen Sie die Zulassungsliste oder wählen Sie ein Modell aus `/model list`. + `agents.defaults.models` hinzu, entfernen Sie die Allowlist oder wählen Sie ein Modell aus `/model list`. @@ -2409,14 +2408,14 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Checkliste zur Behebung: - 1. Aktualisieren Sie auf ein aktuelles OpenClaw-Release (oder führen Sie `main` aus dem Quellcode aus) und starten Sie dann das Gateway neu. - 2. Stellen Sie sicher, dass MiniMax konfiguriert ist (Assistent oder JSON) oder dass MiniMax-Authentifizierung - in Env/Auth-Profilen existiert, sodass der passende Provider injiziert werden kann - (`MINIMAX_API_KEY` für `minimax`, `MINIMAX_OAUTH_TOKEN` oder gespeichertes MiniMax- + 1. Aktualisieren Sie auf eine aktuelle OpenClaw-Version (oder führen Sie den Quellcode-Branch `main` aus) und starten Sie dann das Gateway neu. + 2. Stellen Sie sicher, dass MiniMax konfiguriert ist (Assistent oder JSON) oder dass MiniMax-Auth + in den Umgebungsvariablen/Auth-Profilen vorhanden ist, sodass der passende Provider injiziert + werden kann (`MINIMAX_API_KEY` für `minimax`, `MINIMAX_OAUTH_TOKEN` oder gespeichertes MiniMax- OAuth für `minimax-portal`). - 3. Verwenden Sie die exakte Modell-ID (case-sensitive) für Ihren Auth-Pfad: - `minimax/MiniMax-M2.7` oder `minimax/MiniMax-M2.7-highspeed` für API-Key- - Setup, oder `minimax-portal/MiniMax-M2.7` / + 3. Verwenden Sie die exakte Modell-ID (Groß-/Kleinschreibung beachten) für Ihren Auth-Pfad: + `minimax/MiniMax-M2.7` oder `minimax/MiniMax-M2.7-highspeed` für API-key- + Setup oder `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed` für OAuth-Setup. 4. Führen Sie aus: @@ -2426,13 +2425,13 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. und wählen Sie aus der Liste (oder `/model list` im Chat). - Siehe [MiniMax](/de/providers/minimax) und [Models](/de/concepts/models). + Siehe [MiniMax](/de/providers/minimax) und [Modelle](/de/concepts/models). - Ja. Verwenden Sie **MiniMax als Standard** und wechseln Sie **pro Sitzung** das Modell, wenn nötig. - Fallbacks sind für **Fehler**, nicht für „schwere Aufgaben“, verwenden Sie also `/model` oder einen separaten Agenten. + Ja. Verwenden Sie **MiniMax als Standard** und wechseln Sie Modelle **pro Sitzung**, wenn nötig. + Fallbacks sind für **Fehler**, nicht für „schwierige Aufgaben“, daher verwenden Sie `/model` oder einen separaten Agenten. **Option A: pro Sitzung wechseln** @@ -2459,16 +2458,16 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. **Option B: separate Agenten** - - Agent A Standard: MiniMax - - Agent B Standard: OpenAI - - Nach Agent routen oder mit `/agent` wechseln + - Standard von Agent A: MiniMax + - Standard von Agent B: OpenAI + - Nach Agent routen oder `/agent` zum Wechseln verwenden - Docs: [Models](/de/concepts/models), [Multi-Agent Routing](/de/concepts/multi-agent), [MiniMax](/de/providers/minimax), [OpenAI](/de/providers/openai). + Dokumentation: [Modelle](/de/concepts/models), [Multi-Agent-Routing](/de/concepts/multi-agent), [MiniMax](/de/providers/minimax), [OpenAI](/de/providers/openai). - - Ja. OpenClaw liefert einige Standard-Kurzformen mit (sie werden nur angewendet, wenn das Modell in `agents.defaults.models` existiert): + + Ja. OpenClaw liefert einige Standard-Kurzformen mit (werden nur angewendet, wenn das Modell in `agents.defaults.models` existiert): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2483,8 +2482,8 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - - Aliasse stammen aus `agents.defaults.models..alias`. Beispiel: + + Aliasse kommen aus `agents.defaults.models..alias`. Beispiel: ```json5 { @@ -2505,8 +2504,8 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. - - OpenRouter (Bezahlung pro Token; viele Modelle): + + OpenRouter (Pay-per-Token; viele Modelle): ```json5 { @@ -2534,11 +2533,11 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. } ``` - Wenn Sie auf einen Provider/ein Modell verweisen, aber der erforderliche Provider-Schlüssel fehlt, erhalten Sie einen Laufzeit-Authentifizierungsfehler (z. B. `No API key found for provider "zai"`). + Wenn Sie auf ein Provider-/Modellpaar verweisen, aber der erforderliche Provider-Schlüssel fehlt, erhalten Sie einen Laufzeit-Auth-Fehler (z. B. `No API key found for provider "zai"`). **No API key found for provider nach dem Hinzufügen eines neuen Agenten** - Das bedeutet normalerweise, dass der **neue Agent** einen leeren Auth-Store hat. Authentifizierung ist pro Agent und + Das bedeutet normalerweise, dass der **neue Agent** einen leeren Auth-Store hat. Auth ist pro Agent und wird hier gespeichert: ``` @@ -2547,15 +2546,15 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. Möglichkeiten zur Behebung: - - Führen Sie `openclaw agents add ` aus und konfigurieren Sie die Authentifizierung während des Assistenten. - - Oder kopieren Sie `auth-profiles.json` aus dem `agentDir` des Hauptagenten in das `agentDir` des neuen Agenten. + - Führen Sie `openclaw agents add ` aus und konfigurieren Sie Auth während des Assistenten. + - Oder kopieren Sie `auth-profiles.json` aus dem `agentDir` des Haupt-Agenten in das `agentDir` des neuen Agenten. - Verwenden Sie **nicht** dasselbe `agentDir` für mehrere Agenten; das verursacht Kollisionen bei Authentifizierung/Sitzungen. + Verwenden Sie `agentDir` **nicht** für mehrere Agenten gemeinsam; das verursacht Auth-/Sitzungskollisionen. -## Model Failover und „All models failed“ +## Modell-Failover und „All models failed“ @@ -2564,90 +2563,90 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. 1. **Rotation des Auth-Profils** innerhalb desselben Providers. 2. **Modell-Fallback** zum nächsten Modell in `agents.defaults.model.fallbacks`. - Für fehlschlagende Profile gelten Cooldowns (exponentielles Backoff), sodass OpenClaw weiter antworten kann, selbst wenn ein Provider ratenlimitiert ist oder vorübergehend ausfällt. + Cooldowns gelten für fehlschlagende Profile (exponentielles Backoff), sodass OpenClaw weiter antworten kann, selbst wenn ein Provider rate-limitiert ist oder vorübergehend ausfällt. - Der Rate-Limit-Bucket umfasst mehr als nur einfache `429`-Antworten. OpenClaw + Der Ratenlimit-Bucket umfasst mehr als einfache `429`-Antworten. OpenClaw behandelt auch Meldungen wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` und periodische - Nutzungsfenster-Limits (`weekly/monthly limit reached`) als - failover-würdige Rate-Limits. + Nutzungsfenster-Limits (`weekly/monthly limit reached`) als Failover-würdige + Ratenlimits. - Manche Antworten, die nach Abrechnung aussehen, sind nicht `402`, und manche HTTP-`402`- + Einige Antworten, die nach Abrechnung aussehen, sind kein `402`, und einige HTTP-`402`- Antworten bleiben ebenfalls in diesem transienten Bucket. Wenn ein Provider - expliziten Abrechnungstext auf `401` oder `403` zurückgibt, kann OpenClaw dies dennoch in - der Billing-Spur halten, aber provider-spezifische Textmatcher bleiben auf den - Provider begrenzt, dem sie gehören (zum Beispiel OpenRouter `Key limit exceeded`). Wenn eine `402`- - Meldung stattdessen wie ein wiederholbares Nutzungsfenster oder - ein Ausgabenlimit für Organisation/Workspace aussieht (`daily limit reached, resets tomorrow`, + expliziten Abrechnungstext auf `401` oder `403` zurückgibt, kann OpenClaw das weiterhin + in der Billing-Spur behalten, aber provider-spezifische Text-Matcher bleiben auf den + Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter `Key limit exceeded`). Wenn eine `402`- + Nachricht stattdessen wie ein wiederholbares Nutzungsfenster oder + ein Organization-/Workspace-Ausgabenlimit aussieht (`daily limit reached, resets tomorrow`, `organization spending limit exceeded`), behandelt OpenClaw dies als - `rate_limit`, nicht als lange Billing-Deaktivierung. + `rate_limit`, nicht als langfristige Billing-Deaktivierung. Kontextüberlauf-Fehler sind anders: Signaturen wie `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` oder `ollama error: context length - exceeded` bleiben auf dem Pfad für Compaction/Retry, statt den Modell- - Fallback voranzutreiben. + exceeded` bleiben auf dem Compaction-/Retry-Pfad, anstatt den Modell- + Fallback weiterzuschalten. - Generischer Server-Fehlertext ist absichtlich enger als „alles mit - unknown/error darin“. OpenClaw behandelt provider-spezifische transiente Formen - wie Anthropic ohne Zusatz `An unknown error occurred`, OpenRouter ohne Zusatz + Generischer Serverfehler-Text ist absichtlich enger gefasst als „alles mit + unknown/error darin“. OpenClaw behandelt provider-bezogene transiente Muster + wie Anthropic bare `An unknown error occurred`, OpenRouter bare `Provider returned error`, Stop-Reason-Fehler wie `Unhandled stop reason: error`, JSON-`api_error`-Payloads mit transientem Servertext (`internal server error`, `unknown error, 520`, `upstream error`, `backend error`) und provider-busy-Fehler wie `ModelNotReadyException` als - failover-würdige Timeout-/Überlastungssignale, wenn der Provider-Kontext + Failover-würdige Timeout-/Overloaded-Signale, wenn der Provider-Kontext passt. Generischer interner Fallback-Text wie `LLM request failed with an unknown - error.` bleibt konservativ und löst für sich allein keinen Modell-Fallback aus. + error.` bleibt konservativ und löst nicht von selbst Modell-Fallback aus. - Das bedeutet, dass das System versucht hat, die Auth-Profil-ID `anthropic:default` zu verwenden, dafür aber im erwarteten Auth-Store keine Credentials finden konnte. + Das bedeutet, dass das System versucht hat, die Auth-Profil-ID `anthropic:default` zu verwenden, aber dafür keine Anmeldedaten im erwarteten Auth-Store finden konnte. **Checkliste zur Behebung:** - - **Bestätigen Sie, wo Auth-Profile liegen** (neue vs. alte Pfade) + - **Bestätigen Sie, wo Auth-Profile liegen** (neue vs. Legacy-Pfade) - Aktuell: `~/.openclaw/agents//agent/auth-profiles.json` - Legacy: `~/.openclaw/agent/*` (migriert durch `openclaw doctor`) - - **Bestätigen Sie, dass Ihre Env-Variable vom Gateway geladen wird** - - Wenn Sie `ANTHROPIC_API_KEY` in Ihrer Shell gesetzt haben, das Gateway aber über systemd/launchd läuft, wird sie möglicherweise nicht geerbt. Legen Sie sie in `~/.openclaw/.env` ab oder aktivieren Sie `env.shellEnv`. + - **Bestätigen Sie, dass Ihre Umgebungsvariable vom Gateway geladen wird** + - Wenn Sie `ANTHROPIC_API_KEY` in Ihrer Shell gesetzt haben, das Gateway aber über systemd/launchd ausführen, wird sie möglicherweise nicht geerbt. Legen Sie sie in `~/.openclaw/.env` ab oder aktivieren Sie `env.shellEnv`. - **Stellen Sie sicher, dass Sie den richtigen Agenten bearbeiten** - - Bei Multi-Agent-Setups kann es mehrere Dateien `auth-profiles.json` geben. - - **Prüfen Sie den Modell-/Auth-Status** - - Verwenden Sie `openclaw models status`, um konfigurierte Modelle und den Authentifizierungsstatus der Provider anzuzeigen. + - Multi-Agent-Setups bedeuten, dass es mehrere `auth-profiles.json`-Dateien geben kann. + - **Plausibilitätsprüfung von Modell-/Auth-Status** + - Verwenden Sie `openclaw models status`, um konfigurierte Modelle und den Authentifizierungsstatus der Provider zu sehen. **Checkliste zur Behebung für "No credentials found for profile anthropic"** - Das bedeutet, dass der Lauf auf ein Anthropic-Auth-Profil fixiert ist, das Gateway + Das bedeutet, dass der Lauf an ein Anthropic-Auth-Profil angeheftet ist, das Gateway es aber in seinem Auth-Store nicht finden kann. - **Claude CLI verwenden** - Führen Sie `openclaw models auth login --provider anthropic --method cli --set-default` auf dem Gateway-Host aus. - **Wenn Sie stattdessen einen API-Schlüssel verwenden möchten** - Legen Sie `ANTHROPIC_API_KEY` in `~/.openclaw/.env` auf dem **Gateway-Host** ab. - - Löschen Sie jede fixierte Reihenfolge, die ein fehlendes Profil erzwingt: + - Entfernen Sie jede angeheftete Reihenfolge, die ein fehlendes Profil erzwingt: ```bash openclaw models auth order clear --provider anthropic ``` - **Bestätigen Sie, dass Sie Befehle auf dem Gateway-Host ausführen** - - Im Remote-Modus liegen Auth-Profile auf dem Gateway-Rechner, nicht auf Ihrem Laptop. + - Im Remote-Modus liegen Auth-Profile auf der Gateway-Maschine, nicht auf Ihrem Laptop. - Wenn Ihre Modellkonfiguration Google Gemini als Fallback enthält (oder Sie zu einem Gemini-Kürzel gewechselt haben), versucht OpenClaw es während des Modell-Fallbacks. Wenn Sie keine Google-Credentials konfiguriert haben, sehen Sie `No API key found for provider "google"`. + Wenn Ihre Modellkonfiguration Google Gemini als Fallback enthält (oder Sie zu einer Gemini-Kurzform gewechselt sind), versucht OpenClaw es beim Modell-Fallback damit. Wenn Sie keine Google-Anmeldedaten konfiguriert haben, sehen Sie `No API key found for provider "google"`. - Lösung: Geben Sie entweder Google-Authentifizierung an oder entfernen/vermeiden Sie Google-Modelle in `agents.defaults.model.fallbacks` / Aliassen, damit der Fallback nicht dorthin routet. + Lösung: Geben Sie entweder Google-Auth an oder entfernen/vermeiden Sie Google-Modelle in `agents.defaults.model.fallbacks` / Aliasen, damit der Fallback nicht dorthin routet. **LLM request rejected: thinking signature required (Google Antigravity)** Ursache: Der Sitzungsverlauf enthält **Thinking-Blöcke ohne Signaturen** (oft aus - einem abgebrochenen/partiellen Stream). Google Antigravity verlangt Signaturen für Thinking-Blöcke. + einem abgebrochenen/teilweisen Stream). Google Antigravity erfordert Signaturen für Thinking-Blöcke. Lösung: OpenClaw entfernt jetzt unsignierte Thinking-Blöcke für Google Antigravity Claude. Wenn es weiterhin erscheint, starten Sie eine **neue Sitzung** oder setzen Sie `/thinking off` für diesen Agenten. @@ -2656,11 +2655,11 @@ auf Nutzung/Abrechnung und erhöhen Sie die Limits bei Bedarf. ## Auth-Profile: was sie sind und wie man sie verwaltet -Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicherung, Multi-Account-Muster) +Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Flows, Token-Speicherung, Multi-Account-Muster) - Ein Auth-Profil ist ein benannter Credential-Eintrag (OAuth oder API-Schlüssel), der an einen Provider gebunden ist. Profile liegen unter: + Ein Auth-Profil ist ein benannter Anmeldedatensatz (OAuth oder API-Schlüssel), der an einen Provider gebunden ist. Profile liegen in: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2668,64 +2667,64 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - + OpenClaw verwendet Provider-präfixierte IDs wie: - - `anthropic:default` (üblich, wenn keine E-Mail-Identität existiert) + - `anthropic:default` (häufig, wenn keine E-Mail-Identität existiert) - `anthropic:` für OAuth-Identitäten - benutzerdefinierte IDs Ihrer Wahl (z. B. `anthropic:work`) - Ja. Die Konfiguration unterstützt optionale Metadaten für Profile und eine Reihenfolge pro Provider (`auth.order.`). Dadurch werden **keine** Secrets gespeichert; es ordnet IDs Provider/Modus zu und setzt die Rotationsreihenfolge. + Ja. Die Konfiguration unterstützt optionale Metadaten für Profile und eine Reihenfolge pro Provider (`auth.order.`). Dadurch werden **keine** Secrets gespeichert; es ordnet IDs Provider/Modus zu und setzt die Rotationsreihenfolge fest. - OpenClaw kann ein Profil vorübergehend überspringen, wenn es sich in einem kurzen **Cooldown** befindet (Rate-Limits/Timeouts/Auth-Fehler) oder in einem längeren **deaktivierten** Zustand (Abrechnung/ungenügende Credits). Um dies zu prüfen, führen Sie `openclaw models status --json` aus und prüfen `auth.unusableProfiles`. Tuning: `auth.cooldowns.billingBackoffHours*`. + OpenClaw kann ein Profil vorübergehend überspringen, wenn es sich in einem kurzen **Cooldown** (Ratenlimits/Timeouts/Auth-Fehler) oder einem längeren **disabled**-Zustand (Abrechnung/ungenügende Credits) befindet. Um dies zu prüfen, führen Sie `openclaw models status --json` aus und prüfen Sie `auth.unusableProfiles`. Tuning: `auth.cooldowns.billingBackoffHours*`. - Rate-Limit-Cooldowns können modellbezogen sein. Ein Profil, das für ein Modell - im Cooldown ist, kann für ein Schwestermodell beim selben Provider weiterhin nutzbar sein, - während Billing-/Deaktivierungsfenster weiterhin das ganze Profil blockieren. + Ratenlimit-Cooldowns können modellbezogen sein. Ein Profil, das für ein Modell + im Cooldown ist, kann für ein benachbartes Modell desselben Providers weiterhin nutzbar sein, + während Billing-/disabled-Fenster weiterhin das ganze Profil blockieren. - Sie können über die CLI auch ein **agentenspezifisches** Override der Reihenfolge setzen (gespeichert in `auth-state.json` dieses Agenten): + Sie können auch über die CLI eine **pro-Agent**-Reihenfolgenüberschreibung setzen (gespeichert in `auth-state.json` dieses Agenten): ```bash - # Standard ist der konfigurierte Standard-Agent (lassen Sie --agent weg) + # Standardmäßig der konfigurierte Standard-Agent (lassen Sie --agent weg) openclaw models auth order get --provider anthropic - # Rotation auf ein einzelnes Profil festlegen (nur dieses versuchen) + # Rotation auf ein einzelnes Profil sperren (nur dieses versuchen) openclaw models auth order set --provider anthropic anthropic:default # Oder eine explizite Reihenfolge setzen (Fallback innerhalb des Providers) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Override löschen (zurück auf config auth.order / Round-Robin) + # Überschreibung löschen (auf config auth.order / Round-Robin zurückfallen) openclaw models auth order clear --provider anthropic ``` - Um einen bestimmten Agenten anzusprechen: + Um auf einen bestimmten Agenten zu zielen: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Um zu verifizieren, was tatsächlich versucht wird, verwenden Sie: + Um zu prüfen, was tatsächlich versucht wird, verwenden Sie: ```bash openclaw models status --probe ``` - Wenn ein gespeichertes Profil in der expliziten Reihenfolge fehlt, meldet Probe - `excluded_by_auth_order` für dieses Profil, statt es stillschweigend zu versuchen. + Wenn ein gespeichertes Profil in der expliziten Reihenfolge fehlt, meldet probe + für dieses Profil `excluded_by_auth_order`, anstatt es stillschweigend zu versuchen. - + OpenClaw unterstützt beides: - - **OAuth** nutzt oft, wo anwendbar, Abonnement-Zugriff. - - **API-Schlüssel** verwenden Bezahlung pro Token. + - **OAuth** nutzt oft Abo-Zugriff (wo zutreffend). + - **API keys** verwenden Pay-per-Token-Abrechnung. - Der Assistent unterstützt ausdrücklich Anthropic Claude CLI, OpenAI Codex OAuth und API-Schlüssel. + Der Assistent unterstützt explizit Anthropic Claude CLI, OpenAI Codex OAuth und API keys. @@ -2734,7 +2733,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - `gateway.port` steuert den einzelnen multiplexen Port für WebSocket + HTTP (Control UI, Hooks usw.). + `gateway.port` steuert den einzelnen multiplexten Port für WebSocket + HTTP (Control UI, Hooks usw.). Priorität: @@ -2745,13 +2744,13 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - Weil „running“ die Sicht des **Supervisors** ist (launchd/systemd/schtasks). Die Connectivity Probe bedeutet, dass sich die CLI tatsächlich mit dem Gateway WebSocket verbindet. + Weil „running“ die Sicht des **Supervisors** ist (launchd/systemd/schtasks). Die Connectivity-Probe ist die CLI, die sich tatsächlich mit dem Gateway-WebSocket verbindet. Verwenden Sie `openclaw gateway status` und verlassen Sie sich auf diese Zeilen: - `Probe target:` (die URL, die die Probe tatsächlich verwendet hat) - `Listening:` (was tatsächlich an den Port gebunden ist) - - `Last gateway error:` (häufige Grundursache, wenn der Prozess lebt, der Port aber nicht lauscht) + - `Last gateway error:` (häufige Ursache, wenn der Prozess lebt, aber der Port nicht lauscht) @@ -2764,19 +2763,19 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru openclaw gateway install --force ``` - Führen Sie das aus derselben `--profile`-/Umgebung aus, die der Service verwenden soll. + Führen Sie dies aus derselben `--profile`-/Umgebung aus, die der Service verwenden soll. - OpenClaw erzwingt eine Laufzeitsperre, indem es den WebSocket-Listener sofort beim Start bindet (Standard `ws://127.0.0.1:18789`). Wenn das Binden mit `EADDRINUSE` fehlschlägt, wirft es `GatewayLockError`, was anzeigt, dass bereits eine andere Instanz lauscht. + OpenClaw erzwingt eine Laufzeitsperre, indem es den WebSocket-Listener beim Start sofort bindet (Standard `ws://127.0.0.1:18789`). Wenn das Binden mit `EADDRINUSE` fehlschlägt, wirft es `GatewayLockError`, was darauf hinweist, dass bereits eine andere Instanz lauscht. - Lösung: Stoppen Sie die andere Instanz, geben Sie den Port frei oder führen Sie mit `openclaw gateway --port ` aus. + Lösung: Stoppen Sie die andere Instanz, geben Sie den Port frei oder starten Sie mit `openclaw gateway --port `. - - Setzen Sie `gateway.mode: "remote"` und zeigen Sie auf eine Remote-WebSocket-URL, optional mit Shared-Secret-Remote-Credentials: + + Setzen Sie `gateway.mode: "remote"` und zeigen Sie auf eine Remote-WebSocket-URL, optional mit Remote-Anmeldedaten per Shared Secret: ```json5 { @@ -2793,98 +2792,98 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru Hinweise: - - `openclaw gateway` startet nur, wenn `gateway.mode` auf `local` steht (oder Sie das Override-Flag übergeben). - - Die macOS-App überwacht die Konfigurationsdatei und wechselt live die Modi, wenn sich diese Werte ändern. - - `gateway.remote.token` / `.password` sind nur clientseitige Remote-Credentials; sie aktivieren lokale Gateway-Authentifizierung nicht von selbst. + - `openclaw gateway` startet nur, wenn `gateway.mode` auf `local` steht (oder Sie die Override-Flag übergeben). + - Die macOS-App überwacht die Konfigurationsdatei und wechselt live den Modus, wenn sich diese Werte ändern. + - `gateway.remote.token` / `.password` sind nur clientseitige Remote-Anmeldedaten; sie aktivieren lokale Gateway-Auth nicht von selbst. - Ihr Gateway-Authentifizierungspfad und die Authentifizierungsmethode der UI stimmen nicht überein. + Der Auth-Pfad Ihres Gateways und die Auth-Methode der UI passen nicht zusammen. Fakten (aus dem Code): - - Die Control UI hält den Token in `sessionStorage` für die aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL, sodass Aktualisierungen im selben Tab weiter funktionieren, ohne langlebige Token-Persistenz in `localStorage` wiederherzustellen. - - Bei `AUTH_TOKEN_MISMATCH` können vertrauenswürdige Clients einen begrenzten Retry mit einem zwischengespeicherten Device-Token versuchen, wenn das Gateway Retry-Hinweise zurückgibt (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Dieser Retry mit zwischengespeichertem Token verwendet jetzt die zwischengespeicherten genehmigten Scopes, die mit dem Device-Token gespeichert sind, wieder. Explizite Aufrufer mit `deviceToken` / expliziten `scopes` behalten weiterhin ihre angeforderte Scope-Menge, statt zwischengespeicherte Scopes zu übernehmen. - - Außerhalb dieses Retry-Pfads ist die Priorität der Verbindungs-Authentifizierung: expliziter Shared Token/Passwort zuerst, dann explizites `deviceToken`, dann gespeichertes Device-Token, dann Bootstrap-Token. - - Prüfungen des Bootstrap-Token-Scopes sind rollenpräfixiert. Die eingebaute Bootstrap-Operator-Zulassungsliste erfüllt nur Operator-Anfragen; Node- oder andere Nicht-Operator-Rollen benötigen weiterhin Scopes unter ihrem eigenen Rollenpräfix. + - Die Control UI speichert das Token in `sessionStorage` für die aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL, sodass Aktualisierungen im selben Tab weiter funktionieren, ohne langlebige lokaleStorage-Token-Persistenz wiederherzustellen. + - Bei `AUTH_TOKEN_MISMATCH` können vertrauenswürdige Clients einen begrenzten Retry mit einem gecachten Device-Token versuchen, wenn das Gateway Retry-Hinweise zurückgibt (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Dieser Retry mit gecachtem Token verwendet nun die gecachten genehmigten Scopes, die mit dem Device-Token gespeichert wurden. Explizite `deviceToken`-/explizite-`scopes`-Aufrufer behalten weiterhin ihren angeforderten Scope-Satz, statt gecachte Scopes zu übernehmen. + - Außerhalb dieses Retry-Pfads ist die Priorität bei connect-Auth: zuerst explizites Shared Token/Passwort, dann explizites `deviceToken`, dann gespeichertes Device-Token, dann Bootstrap-Token. + - Scope-Prüfungen für Bootstrap-Token sind rollenpräfixiert. Die eingebaute Bootstrap-Operator-Allowlist erfüllt nur Operator-Anfragen; Node- oder andere Nicht-Operator-Rollen benötigen weiterhin Scopes unter ihrem eigenen Rollenpräfix. Lösung: - - Am schnellsten: `openclaw dashboard` (gibt die Dashboard-URL aus und kopiert sie, versucht zu öffnen; zeigt einen SSH-Hinweis an, wenn headless). - - Wenn Sie noch keinen Token haben: `openclaw doctor --generate-gateway-token`. - - Wenn remote: erst tunneln: `ssh -N -L 18789:127.0.0.1:18789 user@host`, dann `http://127.0.0.1:18789/` öffnen. - - Shared-Secret-Modus: setzen Sie `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` oder `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` und fügen Sie dann das passende Secret in die Control-UI-Einstellungen ein. - - Tailscale-Serve-Modus: Stellen Sie sicher, dass `gateway.auth.allowTailscale` aktiviert ist und Sie die Serve-URL öffnen, nicht eine rohe loopback-/tailnet-URL, die Tailscale-Identitäts-Header umgeht. - - Trusted-Proxy-Modus: Stellen Sie sicher, dass Sie über den konfigurierten nicht-loopback Identity-aware Proxy kommen, nicht über einen Loopback-Proxy auf demselben Host oder eine rohe Gateway-URL. - - Wenn der Mismatch nach dem einen Retry bestehen bleibt, rotieren/genehmigen Sie den gekoppelten Device-Token erneut: + - Am schnellsten: `openclaw dashboard` (gibt die Dashboard-URL aus + kopiert sie, versucht zu öffnen; zeigt SSH-Hinweis, wenn headless). + - Wenn Sie noch kein Token haben: `openclaw doctor --generate-gateway-token`. + - Wenn remote, zuerst tunneln: `ssh -N -L 18789:127.0.0.1:18789 user@host` und dann `http://127.0.0.1:18789/` öffnen. + - Shared-Secret-Modus: Setzen Sie `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` oder `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` und fügen Sie dann das passende Secret in die Einstellungen der Control UI ein. + - Tailscale-Serve-Modus: Stellen Sie sicher, dass `gateway.auth.allowTailscale` aktiviert ist und dass Sie die Serve-URL öffnen, nicht eine rohe loopback-/Tailnet-URL, die Tailscale-Identitäts-Header umgeht. + - Trusted-proxy-Modus: Stellen Sie sicher, dass Sie über den konfigurierten Identity-aware-Proxy ohne loopback kommen, nicht über einen loopback-Proxy auf demselben Host oder eine rohe Gateway-URL. + - Wenn das Mismatch nach dem einen Retry bestehen bleibt, rotieren/genehmigen Sie das gekoppelte Device-Token neu: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - Wenn dieser Rotate-Aufruf sagt, dass er abgelehnt wurde, prüfen Sie zwei Dinge: - - Sitzungen gekoppelter Geräte können nur ihr **eigenes** Gerät rotieren, außer sie haben zusätzlich `operator.admin` - - explizite `--scope`-Werte dürfen die aktuellen Operator-Scopes des Aufrufers nicht überschreiten - - Immer noch festgefahren? Führen Sie `openclaw status --all` aus und folgen Sie [Troubleshooting](/de/gateway/troubleshooting). Siehe [Dashboard](/web/dashboard) für Authentifizierungsdetails. + - Sitzungen gekoppelter Geräte können nur ihr **eigenes** Gerät rotieren, es sei denn, sie haben zusätzlich `operator.admin` + - Explizite `--scope`-Werte dürfen die aktuellen Operator-Scopes des Aufrufers nicht überschreiten + - Immer noch fest? Führen Sie `openclaw status --all` aus und folgen Sie [Fehlersuche](/de/gateway/troubleshooting). Siehe [Dashboard](/web/dashboard) für Auth-Details. - `tailnet`-Bind wählt eine Tailscale-IP aus Ihren Netzwerkschnittstellen aus (100.64.0.0/10). Wenn der Rechner nicht in Tailscale ist (oder die Schnittstelle down ist), gibt es nichts, woran gebunden werden könnte. + Die Bindung `tailnet` wählt eine Tailscale-IP aus Ihren Netzwerkschnittstellen (100.64.0.0/10). Wenn die Maschine nicht in Tailscale ist (oder die Schnittstelle down ist), gibt es nichts, woran gebunden werden kann. Lösung: - - Starten Sie Tailscale auf diesem Host (damit es eine 100.x-Adresse hat), oder - - Wechseln Sie zu `gateway.bind: "loopback"` / `"lan"`. + - Starten Sie Tailscale auf diesem Host (damit er eine 100.x-Adresse hat), oder + - wechseln Sie zu `gateway.bind: "loopback"` / `"lan"`. - Hinweis: `tailnet` ist explizit. `auto` bevorzugt loopback; verwenden Sie `gateway.bind: "tailnet"`, wenn Sie einen tailnet-only-Bind möchten. + Hinweis: `tailnet` ist explizit. `auto` bevorzugt loopback; verwenden Sie `gateway.bind: "tailnet"`, wenn Sie eine Bindung nur ans Tailnet möchten. - - Normalerweise nein – ein Gateway kann mehrere Messaging-Kanäle und Agenten ausführen. Verwenden Sie mehrere Gateways nur, wenn Sie Redundanz (z. B. Rettungs-Bot) oder harte Isolation benötigen. + + Normalerweise nein – ein Gateway kann mehrere Messaging-Kanäle und Agenten betreiben. Verwenden Sie mehrere Gateways nur, wenn Sie Redundanz (z. B. Rescue-Bot) oder harte Isolation benötigen. Ja, aber Sie müssen isolieren: - - `OPENCLAW_CONFIG_PATH` (Konfiguration pro Instanz) - - `OPENCLAW_STATE_DIR` (Status pro Instanz) + - `OPENCLAW_CONFIG_PATH` (pro Instanz eigene Konfiguration) + - `OPENCLAW_STATE_DIR` (pro Instanz eigener Zustand) - `agents.defaults.workspace` (Workspace-Isolation) - `gateway.port` (eindeutige Ports) Schnelles Setup (empfohlen): - Verwenden Sie `openclaw --profile ...` pro Instanz (erstellt automatisch `~/.openclaw-`). - - Setzen Sie einen eindeutigen `gateway.port` in jeder Profilkonfiguration (oder übergeben Sie `--port` für manuelle Läufe). + - Setzen Sie in jeder Profil-Konfiguration einen eindeutigen `gateway.port` (oder übergeben Sie `--port` bei manuellen Läufen). - Installieren Sie einen Service pro Profil: `openclaw --profile gateway install`. - Profile hängen auch Suffixe an Servicenamen an (`ai.openclaw.`; Legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). - Vollständige Anleitung: [Multiple gateways](/de/gateway/multiple-gateways). + Profile suffixieren auch die Service-Namen (`ai.openclaw.`; Legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Vollständige Anleitung: [Mehrere Gateways](/de/gateway/multiple-gateways). - - Das Gateway ist ein **WebSocket-Server** und erwartet, dass die allererste Nachricht + + Das Gateway ist ein **WebSocket-Server**, und es erwartet, dass die allererste Nachricht ein `connect`-Frame ist. Wenn es etwas anderes empfängt, schließt es die Verbindung - mit **code 1008** (policy violation). + mit **Code 1008** (Policy Violation). Häufige Ursachen: - - Sie haben die **HTTP**-URL in einem Browser geöffnet (`http://...`) statt in einem WS-Client. + - Sie haben die **HTTP**-URL in einem Browser geöffnet (`http://...`) statt mit einem WS-Client. - Sie haben den falschen Port oder Pfad verwendet. - - Ein Proxy oder Tunnel hat Authentifizierungs-Header entfernt oder eine Nicht-Gateway-Anfrage gesendet. + - Ein Proxy oder Tunnel hat Auth-Header entfernt oder eine Nicht-Gateway-Anfrage gesendet. Schnelle Lösungen: 1. Verwenden Sie die WS-URL: `ws://:18789` (oder `wss://...` bei HTTPS). 2. Öffnen Sie den WS-Port nicht in einem normalen Browser-Tab. - 3. Wenn Authentifizierung aktiv ist, geben Sie Token/Passwort im `connect`-Frame mit. + 3. Wenn Auth aktiviert ist, geben Sie das Token/Passwort im `connect`-Frame mit. - Wenn Sie CLI oder TUI verwenden, sollte die URL so aussehen: + Wenn Sie die CLI oder TUI verwenden, sollte die URL so aussehen: ``` openclaw tui --url ws://:18789 --token ``` - Protokolldetails: [Gateway protocol](/de/gateway/protocol). + Protokolldetails: [Gateway-Protokoll](/de/gateway/protocol). @@ -2899,9 +2898,9 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Sie können einen stabilen Pfad über `logging.file` setzen. Das Dateilog-Level wird über `logging.level` gesteuert. Die Konsolen-Verbosity wird über `--verbose` und `logging.consoleLevel` gesteuert. + Sie können einen stabilen Pfad über `logging.file` setzen. Das Dateilog-Level wird durch `logging.level` gesteuert. Die Konsolen-Verbosity wird durch `--verbose` und `logging.consoleLevel` gesteuert. - Schnellster Log-Tail: + Schnellstes Log-Tailing: ```bash openclaw logs --follow @@ -2913,7 +2912,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Siehe [Troubleshooting](/de/gateway/troubleshooting) für mehr. + Siehe [Fehlersuche](/de/gateway/troubleshooting) für mehr. @@ -2925,7 +2924,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru openclaw gateway restart ``` - Wenn Sie das Gateway manuell ausführen, kann `openclaw gateway --force` den Port zurückholen. Siehe [Gateway](/de/gateway). + Wenn Sie das Gateway manuell ausführen, kann `openclaw gateway --force` den Port zurückerobern. Siehe [Gateway](/de/gateway). @@ -2934,7 +2933,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru **1) WSL2 (empfohlen):** Das Gateway läuft innerhalb von Linux. - Öffnen Sie PowerShell, gehen Sie in WSL und starten Sie dann neu: + Öffnen Sie PowerShell, wechseln Sie in WSL und starten Sie dann neu: ```powershell wsl @@ -2963,12 +2962,12 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru openclaw gateway run ``` - Docs: [Windows (WSL2)](/de/platforms/windows), [Gateway service runbook](/de/gateway). + Dokumentation: [Windows (WSL2)](/de/platforms/windows), [Gateway-Service-Runbook](/de/gateway). - Beginnen Sie mit einem schnellen Health-Durchlauf: + Beginnen Sie mit einer schnellen Zustandsprüfung: ```bash openclaw status @@ -2979,14 +2978,14 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru Häufige Ursachen: - - Modell-Authentifizierung auf dem **Gateway-Host** nicht geladen (prüfen Sie `models status`). - - Kanal-Pairing/Zulassungsliste blockiert Antworten (prüfen Sie Kanalkonfiguration + Logs). - - WebChat/Dashboard ist ohne den richtigen Token geöffnet. + - Modell-Auth wurde auf dem **Gateway-Host** nicht geladen (prüfen Sie `models status`). + - Kanal-Kopplung/Allowlist blockiert Antworten (prüfen Sie Kanal-Konfiguration + Logs). + - WebChat/Dashboard ist ohne das richtige Token geöffnet. - Wenn Sie remote sind, bestätigen Sie, dass die Tunnel-/Tailscale-Verbindung aktiv ist und der - Gateway WebSocket erreichbar ist. + Wenn Sie remote sind, bestätigen Sie, dass die Tunnel-/Tailscale-Verbindung aktiv ist und dass der + Gateway-WebSocket erreichbar ist. - Docs: [Channels](/de/channels), [Troubleshooting](/de/gateway/troubleshooting), [Remote access](/de/gateway/remote). + Dokumentation: [Kanäle](/de/channels), [Fehlersuche](/de/gateway/troubleshooting), [Remote-Zugriff](/de/gateway/remote). @@ -2995,16 +2994,16 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru 1. Läuft das Gateway? `openclaw gateway status` 2. Ist das Gateway gesund? `openclaw status` - 3. Hat die UI den richtigen Token? `openclaw dashboard` + 3. Hat die UI das richtige Token? `openclaw dashboard` 4. Wenn remote: Ist die Tunnel-/Tailscale-Verbindung aktiv? - Verfolgen Sie dann die Logs: + Dann Logs mitverfolgen: ```bash openclaw logs --follow ``` - Docs: [Dashboard](/web/dashboard), [Remote access](/de/gateway/remote), [Troubleshooting](/de/gateway/troubleshooting). + Dokumentation: [Dashboard](/web/dashboard), [Remote-Zugriff](/de/gateway/remote), [Fehlersuche](/de/gateway/troubleshooting). @@ -3018,17 +3017,17 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru Ordnen Sie dann den Fehler zu: - - `BOT_COMMANDS_TOO_MUCH`: Das Telegram-Menü hat zu viele Einträge. OpenClaw kürzt bereits auf das Telegram-Limit und versucht es mit weniger Befehlen erneut, aber einige Menüeinträge müssen weiterhin entfernt werden. Reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie `channels.telegram.commands.native`, wenn Sie das Menü nicht benötigen. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` oder ähnliche Netzwerkfehler: Wenn Sie auf einem VPS oder hinter einem Proxy sind, bestätigen Sie, dass ausgehendes HTTPS erlaubt ist und DNS für `api.telegram.org` funktioniert. + - `BOT_COMMANDS_TOO_MUCH`: Das Telegram-Menü hat zu viele Einträge. OpenClaw kürzt bereits auf das Telegram-Limit und versucht es mit weniger Befehlen erneut, aber einige Menüeinträge müssen trotzdem entfernt werden. Reduzieren Sie Plugin-/Skill-/benutzerdefinierte Befehle oder deaktivieren Sie `channels.telegram.commands.native`, wenn Sie das Menü nicht benötigen. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` oder ähnliche Netzwerkfehler: Wenn Sie auf einem VPS oder hinter einem Proxy arbeiten, bestätigen Sie, dass ausgehendes HTTPS erlaubt ist und DNS für `api.telegram.org` funktioniert. - Wenn das Gateway remote ist, stellen Sie sicher, dass Sie die Logs auf dem Gateway-Host betrachten. + Wenn das Gateway remote ist, stellen Sie sicher, dass Sie die Logs auf dem Gateway-Host prüfen. - Docs: [Telegram](/de/channels/telegram), [Channel troubleshooting](/de/channels/troubleshooting). + Dokumentation: [Telegram](/de/channels/telegram), [Kanal-Fehlersuche](/de/channels/troubleshooting). - Bestätigen Sie zuerst, dass das Gateway erreichbar ist und der Agent ausgeführt werden kann: + Bestätigen Sie zuerst, dass das Gateway erreichbar ist und der Agent laufen kann: ```bash openclaw status @@ -3037,13 +3036,13 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru ``` Verwenden Sie in der TUI `/status`, um den aktuellen Zustand zu sehen. Wenn Sie Antworten in einem Chat- - Kanal erwarten, stellen Sie sicher, dass Zustellung aktiviert ist (`/deliver on`). + Kanal erwarten, stellen Sie sicher, dass die Zustellung aktiviert ist (`/deliver on`). - Docs: [TUI](/web/tui), [Slash commands](/de/tools/slash-commands). + Dokumentation: [TUI](/web/tui), [Slash-Befehle](/de/tools/slash-commands). - + Wenn Sie den Service installiert haben: ```bash @@ -3051,16 +3050,16 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru openclaw gateway start ``` - Dadurch wird der **überwachte Service** gestoppt/gestartet (launchd auf macOS, systemd auf Linux). - Verwenden Sie dies, wenn das Gateway im Hintergrund als Daemon läuft. + Dadurch wird der **überwachte Service** gestoppt/gestartet (launchd unter macOS, systemd unter Linux). + Verwenden Sie dies, wenn das Gateway als Daemon im Hintergrund läuft. - Wenn Sie es im Vordergrund ausführen, stoppen Sie es mit Ctrl-C und dann: + Wenn Sie es im Vordergrund ausführen, stoppen Sie mit Strg-C und dann: ```bash openclaw gateway run ``` - Docs: [Gateway service runbook](/de/gateway). + Dokumentation: [Gateway-Service-Runbook](/de/gateway). @@ -3074,7 +3073,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - Starten Sie das Gateway mit `--verbose`, um mehr Details auf der Konsole zu erhalten. Prüfen Sie dann die Logdatei auf Kanal-Authentifizierung, Modell-Routing und RPC-Fehler. + Starten Sie das Gateway mit `--verbose`, um mehr Konsolendetails zu erhalten. Prüfen Sie dann die Logdatei auf Kanal-Auth, Modell-Routing und RPC-Fehler. @@ -3082,7 +3081,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - Ausgehende Anhänge vom Agenten müssen eine Zeile `MEDIA:` enthalten (in eigener Zeile). Siehe [OpenClaw assistant setup](/de/start/openclaw) und [Agent send](/de/tools/agent-send). + Ausgehende Anhänge vom Agenten müssen eine `MEDIA:`-Zeile enthalten (in einer eigenen Zeile). Siehe [OpenClaw-Assistant-Einrichtung](/de/start/openclaw) und [Agent send](/de/tools/agent-send). Senden per CLI: @@ -3092,12 +3091,12 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru Prüfen Sie außerdem: - - Der Zielkanal unterstützt ausgehende Medien und wird nicht durch Zulassungslisten blockiert. - - Die Datei liegt innerhalb der Größenlimits des Providers (Bilder werden auf maximal 2048px skaliert). - - `tools.fs.workspaceOnly=true` beschränkt das Senden lokaler Pfade auf Workspace, temp/media-store und sandbox-validierte Dateien. - - `tools.fs.workspaceOnly=false` erlaubt `MEDIA:`, Host-lokale Dateien zu senden, die der Agent bereits lesen kann, aber nur für Medien plus sichere Dokumenttypen (Bilder, Audio, Video, PDF und Office-Dokumente). Klartext- und secret-ähnliche Dateien werden weiterhin blockiert. + - Der Zielkanal unterstützt ausgehende Medien und wird nicht von Allowlists blockiert. + - Die Datei liegt innerhalb der Größenlimits des Providers (Bilder werden auf maximal 2048 px skaliert). + - `tools.fs.workspaceOnly=true` hält das Senden lokaler Pfade auf Workspace, temp/media-store und sandbox-validierte Dateien beschränkt. + - `tools.fs.workspaceOnly=false` erlaubt `MEDIA:`, host-lokale Dateien zu senden, die der Agent bereits lesen kann, aber nur für Medien plus sichere Dokumenttypen (Bilder, Audio, Video, PDF und Office-Dokumente). Reiner Text und Secret-ähnliche Dateien bleiben weiterhin blockiert. - Siehe [Images](/de/nodes/images). + Siehe [Bilder](/de/nodes/images). @@ -3106,86 +3105,86 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - Behandeln Sie eingehende DMs als nicht vertrauenswürdige Eingaben. Die Standardwerte sind darauf ausgelegt, das Risiko zu verringern: + Behandeln Sie eingehende DMs als nicht vertrauenswürdige Eingabe. Die Standardwerte sind darauf ausgelegt, das Risiko zu verringern: - Standardverhalten auf DM-fähigen Kanälen ist **Pairing**: - Unbekannte Absender erhalten einen Pairing-Code; der Bot verarbeitet ihre Nachricht nicht. - Genehmigen mit: `openclaw pairing approve --channel [--account ] ` - - Ausstehende Anfragen sind auf **3 pro Kanal** begrenzt; prüfen Sie mit `openclaw pairing list --channel [--account ]`, wenn kein Code angekommen ist. - - DMs öffentlich zu öffnen erfordert ein explizites Opt-in (`dmPolicy: "open"` und Zulassungsliste `"*"`). + - Ausstehende Anfragen sind auf **3 pro Kanal** begrenzt; prüfen Sie `openclaw pairing list --channel [--account ]`, wenn kein Code angekommen ist. + - Das öffentliche Öffnen von DMs erfordert explizites Opt-in (`dmPolicy: "open"` und Allowlist `"*"`). Führen Sie `openclaw doctor` aus, um riskante DM-Richtlinien sichtbar zu machen. - - Nein. Prompt Injection betrifft **nicht vertrauenswürdige Inhalte**, nicht nur die Frage, wer dem Bot eine DM senden kann. - Wenn Ihr Assistent externe Inhalte liest (Websuche/Web Fetch, Browser-Seiten, E-Mails, - Docs, Anhänge, eingefügte Logs), können diese Inhalte Anweisungen enthalten, die versuchen, - das Modell zu kapern. Das kann auch passieren, wenn **Sie der einzige Absender** sind. + + Nein. Prompt Injection betrifft **nicht vertrauenswürdige Inhalte**, nicht nur, wer dem Bot eine DM schicken kann. + Wenn Ihr Assistent externe Inhalte liest (Websuche/Web-Fetch, Browser-Seiten, E-Mails, + Dokumente, Anhänge, eingefügte Logs), können diese Inhalte Anweisungen enthalten, die + versuchen, das Modell zu kapern. Das kann selbst dann passieren, wenn **Sie der einzige Absender** sind. Das größte Risiko besteht, wenn Tools aktiviert sind: Das Modell kann dazu verleitet werden, Kontext zu exfiltrieren oder Tools in Ihrem Namen aufzurufen. Verringern Sie den Blast Radius, indem Sie: - einen schreibgeschützten oder tool-deaktivierten „Reader“-Agenten verwenden, um nicht vertrauenswürdige Inhalte zusammenzufassen - `web_search` / `web_fetch` / `browser` für tool-fähige Agenten deaktiviert lassen - - auch dekodierten Datei-/Dokumenttext als nicht vertrauenswürdig behandeln: OpenResponses - `input_file` und Medienanhang-Extraktion kapseln extrahierten Text beide in - explizite Markierungen für externe Inhaltsgrenzen, statt rohen Dateitext weiterzugeben - - Sandboxing und strikte Tool-Zulassungslisten verwenden + - auch dekodierten Datei-/Dokumenttext als nicht vertrauenswürdig behandeln: OpenResponses- + `input_file` und die Extraktion von Medienanhängen kapseln extrahierten Text beide in + explizite Grenzmarker für externe Inhalte, statt rohen Dateitext durchzureichen + - Sandboxing und strikte Tool-Allowlists einsetzen - Details: [Security](/de/gateway/security). + Details: [Sicherheit](/de/gateway/security). - + Ja, für die meisten Setups. Die Isolation des Bots mit separaten Konten und Telefonnummern - verringert den Blast Radius, falls etwas schiefgeht. Außerdem ist es dadurch leichter, Credentials zu rotieren - oder Zugriff zu widerrufen, ohne Ihre persönlichen Konten zu beeinträchtigen. + verringert den Blast Radius, falls etwas schiefgeht. So lässt sich auch leichter + mit Anmeldedaten rotieren oder Zugriff widerrufen, ohne Ihre persönlichen Konten zu beeinträchtigen. Fangen Sie klein an. Geben Sie nur Zugriff auf die Tools und Konten, die Sie tatsächlich benötigen, und erweitern Sie später bei Bedarf. - Docs: [Security](/de/gateway/security), [Pairing](/de/channels/pairing). + Dokumentation: [Sicherheit](/de/gateway/security), [Pairing](/de/channels/pairing). Wir empfehlen **keine** vollständige Autonomie über Ihre persönlichen Nachrichten. Das sicherste Muster ist: - - Behalten Sie DMs im **Pairing-Modus** oder mit einer engen Zulassungsliste. - - Verwenden Sie eine **separate Nummer oder ein separates Konto**, wenn Sie möchten, dass es in Ihrem Namen Nachrichten sendet. - - Lassen Sie es Entwürfe erstellen und **genehmigen Sie vor dem Senden**. + - Behalten Sie DMs im **Pairing-Modus** oder mit einer engen Allowlist. + - Verwenden Sie eine **separate Nummer oder ein separates Konto**, wenn Sie möchten, dass er in Ihrem Namen Nachrichten verschickt. + - Lassen Sie ihn Entwürfe erstellen und **genehmigen Sie sie vor dem Senden**. - Wenn Sie experimentieren möchten, tun Sie dies auf einem dedizierten Konto und halten Sie es isoliert. Siehe - [Security](/de/gateway/security). + Wenn Sie experimentieren möchten, tun Sie es mit einem dedizierten Konto und halten Sie es isoliert. Siehe + [Sicherheit](/de/gateway/security). - Ja, **wenn** der Agent nur Chat verwendet und die Eingaben vertrauenswürdig sind. Kleinere Stufen sind - anfälliger für Instruction Hijacking, vermeiden Sie sie daher bei tool-fähigen Agenten - oder beim Lesen nicht vertrauenswürdiger Inhalte. Wenn Sie trotzdem ein kleineres Modell verwenden müssen, sperren Sie - Tools und arbeiten Sie innerhalb einer Sandbox. Siehe [Security](/de/gateway/security). + Ja, **wenn** der Agent nur chatbasiert ist und die Eingabe vertrauenswürdig ist. Kleinere Tiers sind + anfälliger für Anweisungskapern, daher sollten Sie sie für tool-fähige Agenten + oder beim Lesen nicht vertrauenswürdiger Inhalte vermeiden. Wenn Sie doch ein kleineres Modell verwenden müssen, sperren Sie + Tools und arbeiten Sie innerhalb einer Sandbox. Siehe [Sicherheit](/de/gateway/security). Pairing-Codes werden **nur** gesendet, wenn ein unbekannter Absender dem Bot schreibt und `dmPolicy: "pairing"` aktiviert ist. `/start` allein erzeugt keinen Code. - Prüfen Sie ausstehende Anfragen: + Ausstehende Anfragen prüfen: ```bash openclaw pairing list telegram ``` - Wenn Sie sofortigen Zugriff möchten, setzen Sie Ihre Absender-ID auf die Zulassungsliste oder setzen Sie `dmPolicy: "open"` + Wenn Sie sofortigen Zugriff möchten, setzen Sie Ihre Absender-ID auf die Allowlist oder setzen Sie `dmPolicy: "open"` für dieses Konto. - - Nein. Die Standard-DM-Richtlinie für WhatsApp ist **Pairing**. Unbekannte Absender erhalten nur einen Pairing-Code und ihre Nachricht wird **nicht verarbeitet**. OpenClaw antwortet nur auf Chats, die es erhält, oder auf explizite Sendungen, die Sie auslösen. + + Nein. Die Standard-DM-Richtlinie für WhatsApp ist **Pairing**. Unbekannte Absender erhalten nur einen Pairing-Code und ihre Nachricht wird **nicht verarbeitet**. OpenClaw antwortet nur auf Chats, die es empfängt, oder auf explizite Sendevorgänge, die Sie auslösen. Pairing genehmigen mit: @@ -3199,7 +3198,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru openclaw pairing list whatsapp ``` - Eingabeaufforderung des Assistenten für die Telefonnummer: Sie wird verwendet, um Ihre **Zulassungsliste/Ihren Eigentümer** festzulegen, sodass Ihre eigenen DMs erlaubt sind. Sie wird nicht für automatisches Senden verwendet. Wenn Sie mit Ihrer persönlichen WhatsApp-Nummer arbeiten, verwenden Sie diese Nummer und aktivieren Sie `channels.whatsapp.selfChatMode`. + Eingabeaufforderung der Telefonnummer im Assistenten: Sie wird verwendet, um Ihre **Allowlist/Ihren Owner** zu setzen, damit Ihre eigenen DMs erlaubt sind. Sie wird nicht für automatisches Senden verwendet. Wenn Sie unter Ihrer persönlichen WhatsApp-Nummer arbeiten, verwenden Sie diese Nummer und aktivieren Sie `channels.whatsapp.selfChatMode`. @@ -3210,7 +3209,7 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru Die meisten internen oder Tool-Nachrichten erscheinen nur, wenn **verbose**, **trace** oder **reasoning** für diese Sitzung aktiviert ist. - Lösung im Chat, in dem Sie das sehen: + Korrigieren Sie es in dem Chat, in dem Sie es sehen: ``` /verbose off @@ -3222,12 +3221,12 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru auf **inherit**. Bestätigen Sie außerdem, dass Sie kein Bot-Profil mit `verboseDefault` auf `on` in der Konfiguration verwenden. - Docs: [Thinking and verbose](/de/tools/thinking), [Security](/de/gateway/security#reasoning-verbose-output-in-groups). + Dokumentation: [Thinking and verbose](/de/tools/thinking), [Sicherheit](/de/gateway/security#reasoning-verbose-output-in-groups). - Senden Sie eine der folgenden Nachrichten **als eigenständige Nachricht** (ohne Slash): + Senden Sie eine der folgenden Zeichenfolgen **als eigenständige Nachricht** (ohne Slash): ``` stop @@ -3253,21 +3252,21 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru Dies sind Abbruch-Trigger (keine Slash-Befehle). - Bei Hintergrundprozessen (vom Exec-Tool) können Sie den Agenten bitten, Folgendes auszuführen: + Bei Hintergrundprozessen (vom exec-Tool) können Sie den Agenten bitten, Folgendes auszuführen: ``` process action:kill sessionId:XXX ``` - Übersicht über Slash-Befehle: siehe [Slash commands](/de/tools/slash-commands). + Übersicht über Slash-Befehle: siehe [Slash-Befehle](/de/tools/slash-commands). - Die meisten Befehle müssen als **eigenständige** Nachricht gesendet werden, die mit `/` beginnt, aber einige Abkürzungen (wie `/status`) funktionieren für Absender auf der Zulassungsliste auch inline. + Die meisten Befehle müssen als **eigenständige** Nachricht gesendet werden, die mit `/` beginnt, aber einige Kurzbefehle (wie `/status`) funktionieren für Absender auf der Allowlist auch inline. - OpenClaw blockiert standardmäßig **providerübergreifendes** Messaging. Wenn ein Tool-Aufruf - an Telegram gebunden ist, sendet es nicht an Discord, außer Sie erlauben dies explizit. + OpenClaw blockiert **providerübergreifendes** Messaging standardmäßig. Wenn ein Tool-Aufruf an + Telegram gebunden ist, sendet er nicht an Discord, es sei denn, Sie erlauben es explizit. Aktivieren Sie providerübergreifendes Messaging für den Agenten: @@ -3288,16 +3287,16 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru - + Der Queue-Modus steuert, wie neue Nachrichten mit einem laufenden Run interagieren. Verwenden Sie `/queue`, um Modi zu ändern: - `steer` - neue Nachrichten lenken die aktuelle Aufgabe um - - `followup` - Nachrichten nacheinander ausführen + - `followup` - Nachrichten einzeln nacheinander ausführen - `collect` - Nachrichten bündeln und einmal antworten (Standard) - - `steer-backlog` - jetzt umlenken, dann den Backlog verarbeiten - - `interrupt` - aktuellen Run abbrechen und neu beginnen + - `steer-backlog` - jetzt umlenken, dann Backlog abarbeiten + - `interrupt` - aktuellen Run abbrechen und frisch starten - Sie können Optionen wie `debounce:2s cap:25 drop:summarize` für Follow-up-Modi hinzufügen. + Sie können Optionen wie `debounce:2s cap:25 drop:summarize` für Followup-Modi hinzufügen. @@ -3305,11 +3304,11 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicheru ## Sonstiges - - In OpenClaw sind Credentials und Modellauswahl getrennt. Das Setzen von `ANTHROPIC_API_KEY` (oder das Speichern eines Anthropic-API-Schlüssels in Auth-Profilen) aktiviert die Authentifizierung, aber das tatsächliche Standardmodell ist das, was Sie in `agents.defaults.model.primary` konfigurieren (zum Beispiel `anthropic/claude-sonnet-4-6` oder `anthropic/claude-opus-4-6`). Wenn Sie `No credentials found for profile "anthropic:default"` sehen, bedeutet das, dass das Gateway im erwarteten `auth-profiles.json` für den laufenden Agenten keine Anthropic-Credentials finden konnte. + + In OpenClaw sind Anmeldedaten und Modellauswahl getrennt. Das Setzen von `ANTHROPIC_API_KEY` (oder das Speichern eines Anthropic API key in Auth-Profilen) aktiviert die Authentifizierung, aber das tatsächliche Standardmodell ist das, was Sie in `agents.defaults.model.primary` konfigurieren (zum Beispiel `anthropic/claude-sonnet-4-6` oder `anthropic/claude-opus-4-6`). Wenn Sie `No credentials found for profile "anthropic:default"` sehen, bedeutet das, dass das Gateway keine Anthropic-Anmeldedaten in der erwarteten `auth-profiles.json` für den gerade laufenden Agenten finden konnte. --- -Immer noch festgefahren? Fragen Sie in [Discord](https://discord.com/invite/clawd) oder eröffnen Sie eine [GitHub discussion](https://github.com/openclaw/openclaw/discussions). +Immer noch fest? Fragen Sie in [Discord](https://discord.com/invite/clawd) oder eröffnen Sie eine [GitHub-Diskussion](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/de/help/testing.md b/docs/de/help/testing.md index e3b0c71d0..e057812cc 100644 --- a/docs/de/help/testing.md +++ b/docs/de/help/testing.md @@ -2,26 +2,26 @@ read_when: - Tests lokal oder in CI ausführen - Regressionen für Modell-/Provider-Fehler hinzufügen - - Fehlerbehebung bei Gateway- und Agent-Verhalten + - Gateway- und Agentenverhalten debuggen summary: 'Test-Kit: Unit-/E2E-/Live-Suiten, Docker-Runner und was jeder Test abdeckt' -title: Tests +title: Testen x-i18n: - generated_at: "2026-04-21T06:26:11Z" + generated_at: "2026-04-21T13:35:27Z" model: gpt-5.4 provider: openai - source_hash: ef5bf36f969a6334efd2e8373a0c8002f9e6461af53c4ff630b38ad8e37f73de + source_hash: 3290113f28dab37f4b6ceb0bda6ced70c7d2b24ad3fccac6488b6aab1ad65e52 source_path: help/testing.md workflow: 15 --- -# Tests +# Testen -OpenClaw hat drei Vitest-Suiten (Unit/Integration, E2E, Live) und eine kleine Anzahl von Docker-Runnern. +OpenClaw hat drei Vitest-Suiten (Unit/Integration, E2E, Live) und eine kleine Gruppe von Docker-Runnern. -Dieses Dokument ist eine Anleitung dazu, „wie wir testen“: +Dieses Dokument ist ein Leitfaden dazu, „wie wir testen“: - Was jede Suite abdeckt (und was sie bewusst _nicht_ abdeckt) -- Welche Befehle für häufige Workflows auszuführen sind (lokal, vor dem Push, Debugging) +- Welche Befehle für gängige Workflows ausgeführt werden sollen (lokal, vor dem Pushen, Debugging) - Wie Live-Tests Anmeldedaten erkennen und Modelle/Provider auswählen - Wie Regressionen für reale Modell-/Provider-Probleme hinzugefügt werden @@ -29,96 +29,103 @@ Dieses Dokument ist eine Anleitung dazu, „wie wir testen“: An den meisten Tagen: -- Vollständiges Gate (vor dem Push erwartet): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Vollständiges Gate (vor dem Pushen erwartet): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Schnellere lokale Ausführung der vollständigen Suite auf einem leistungsfähigen Rechner: `pnpm test:max` - Direkte Vitest-Watch-Schleife: `pnpm test:watch` -- Direktes Ansteuern von Dateien leitet jetzt auch Erweiterungs-/Kanalpfade weiter: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Bevorzugen Sie bei der Iteration auf einen einzelnen Fehler zuerst gezielte Ausführungen. +- Direktes Targeting von Dateien leitet jetzt auch Pfade für Plugins/Channels weiter: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Bevorzuge zuerst gezielte Läufe, wenn du an einem einzelnen Fehler arbeitest. - Docker-gestützte QA-Site: `pnpm qa:lab:up` -- Linux-VM-gestützte QA-Strecke: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Linux-VM-gestützte QA-Lane: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Wenn Sie Tests anfassen oder zusätzliche Sicherheit möchten: +Wenn du Tests anfasst oder zusätzliche Sicherheit möchtest: - Coverage-Gate: `pnpm test:coverage` - E2E-Suite: `pnpm test:e2e` -Beim Debuggen echter Provider/Modelle (erfordert echte Anmeldedaten): +Beim Debugging echter Provider/Modelle (erfordert echte Anmeldedaten): -- Live-Suite (Modelle + Gateway-Tool-/Image-Prüfungen): `pnpm test:live` -- Eine einzelne Live-Datei ohne viel Ausgabe ansteuern: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Moonshot/Kimi-Kosten-Smoketest: Setzen Sie `MOONSHOT_API_KEY`, führen Sie dann - `openclaw models list --provider moonshot --json` aus und danach einen isolierten +- Live-Suite (Modelle + Gateway-Tool-/Image-Sonden): `pnpm test:live` +- Eine Live-Datei gezielt und leise ausführen: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Moonshot/Kimi-Kosten-Smoke: Mit gesetztem `MOONSHOT_API_KEY` führe + `openclaw models list --provider moonshot --json` aus und dann eine isolierte `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - gegen `moonshot/kimi-k2.6`. Verifizieren Sie, dass das JSON Moonshot/K2.6 meldet und das - Assistenten-Transkript normalisierte `usage.cost` speichert. + gegen `moonshot/kimi-k2.6`. Verifiziere, dass das JSON Moonshot/K2.6 meldet und das + Assistant-Transkript normalisierte `usage.cost` speichert. -Tipp: Wenn Sie nur einen einzelnen fehlerhaften Fall benötigen, sollten Sie Live-Tests bevorzugt über die unten beschriebenen Allowlist-Umgebungsvariablen eingrenzen. +Tipp: Wenn du nur einen einzelnen fehlschlagenden Fall brauchst, bevorzuge das Eingrenzen von Live-Tests über die unten beschriebenen Allowlist-Umgebungsvariablen. ## QA-spezifische Runner -Diese Befehle stehen neben den Haupttestsuiten, wenn Sie mehr Realismus aus qa-lab benötigen: +Diese Befehle stehen neben den Haupt-Testsuiten bereit, wenn du die Realitätsnähe von qa-lab brauchst: - `pnpm openclaw qa suite` - Führt repo-gestützte QA-Szenarien direkt auf dem Host aus. - Führt standardmäßig mehrere ausgewählte Szenarien parallel mit isolierten Gateway-Workern aus. `qa-channel` verwendet standardmäßig Parallelität 4 (begrenzt durch die - Anzahl der ausgewählten Szenarien). Verwenden Sie `--concurrency `, um die Anzahl - der Worker anzupassen, oder `--concurrency 1` für die ältere serielle Strecke. - - Beendet sich mit einem Fehlercode ungleich null, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn Sie - Artefakte ohne fehlerhaften Exit-Code möchten. + Anzahl der ausgewählten Szenarien). Verwende `--concurrency `, um die Anzahl + der Worker anzupassen, oder `--concurrency 1` für die ältere serielle Lane. + - Beendet sich mit einem Fehlercode ungleich null, wenn irgendein Szenario fehlschlägt. Verwende `--allow-failures`, wenn du + Artefakte ohne fehlschlagenden Exit-Code möchtest. - Unterstützt die Provider-Modi `live-frontier`, `mock-openai` und `aimock`. `aimock` startet einen lokalen AIMock-gestützten Provider-Server für experimentelle Fixture- und Protokoll-Mock-Abdeckung, ohne die szenariobewusste - Strecke `mock-openai` zu ersetzen. + `mock-openai`-Lane zu ersetzen. - `pnpm openclaw qa suite --runner multipass` - - Führt dieselbe QA-Suite innerhalb einer wegwerfbaren Multipass-Linux-VM aus. + - Führt dieselbe QA-Suite in einer temporären Multipass-Linux-VM aus. - Behält dasselbe Verhalten bei der Szenarioauswahl wie `qa suite` auf dem Host bei. - - Verwendet dieselben Provider-/Modellauswahl-Flags wie `qa suite`. + - Verwendet dieselben Flags zur Provider-/Modellauswahl wie `qa suite`. - Live-Läufe leiten die unterstützten QA-Auth-Eingaben weiter, die für den Gast praktikabel sind: - umgebungsbasierte Provider-Schlüssel, den Konfigurationspfad des QA-Live-Providers und - `CODEX_HOME`, wenn vorhanden. - - Ausgabeverzeichnisse müssen unter der Repository-Wurzel bleiben, damit der Gast über - den eingebundenen Workspace zurückschreiben kann. + env-basierte Provider-Schlüssel, den QA-Live-Provider-Konfigurationspfad und + `CODEX_HOME`, falls vorhanden. + - Ausgabeverzeichnisse müssen unterhalb der Repo-Wurzel bleiben, damit der Gast über + den eingehängten Workspace zurückschreiben kann. - Schreibt den normalen QA-Bericht + die Zusammenfassung sowie Multipass-Logs unter `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Startet die Docker-gestützte QA-Site für operatorartige QA-Arbeit. + - Startet die Docker-gestützte QA-Site für operatorähnliche QA-Arbeit. +- `pnpm test:docker:bundled-channel-deps` + - Packt und installiert den aktuellen OpenClaw-Build in Docker, startet das Gateway + mit konfiguriertem OpenAI und aktiviert dann Telegram und Discord über Konfigurationsänderungen. + - Verifiziert, dass der erste Gateway-Neustart die Laufzeitabhängigkeiten jedes gebündelten Channel-Plugins + bei Bedarf installiert und dass ein zweiter Neustart keine bereits aktivierten + Abhängigkeiten erneut installiert. - `pnpm openclaw qa aimock` - - Startet nur den lokalen AIMock-Provider-Server für direkte Protokoll-Smoketests. + - Startet nur den lokalen AIMock-Provider-Server für direktes Protokoll-Smoke- + Testing. - `pnpm openclaw qa matrix` - - Führt die Matrix-Live-QA-Strecke gegen einen wegwerfbaren, Docker-gestützten Tuwunel-Homeserver aus. - - Dieser QA-Host ist derzeit nur für Repo/Entwicklung gedacht. Gepackte OpenClaw-Installationen liefern + - Führt die Matrix-Live-QA-Lane gegen einen temporären Docker-gestützten Tuwunel-Homeserver aus. + - Dieser QA-Host ist heute nur für Repo/Entwicklung gedacht. Gepackte OpenClaw-Installationen liefern `qa-lab` nicht mit aus und stellen daher `openclaw qa` nicht bereit. - - Repository-Checkouts laden den gebündelten Runner direkt; kein separater Installationsschritt für Plugins ist nötig. - - Stellt drei temporäre Matrix-Nutzer (`driver`, `sut`, `observer`) sowie einen privaten Raum bereit und startet dann einen untergeordneten QA-Gateway-Prozess mit dem echten Matrix-Plugin als SUT-Transport. - - Verwendet standardmäßig das fixierte stabile Tuwunel-Image `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Überschreiben Sie es mit `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, wenn Sie ein anderes Image testen müssen. - - Matrix bietet keine gemeinsamen Flags für Anmeldedatenquellen, da die Strecke lokal temporäre Nutzer bereitstellt. - - Schreibt einen Matrix-QA-Bericht, eine Zusammenfassung, ein Artefakt mit beobachteten Ereignissen und ein kombiniertes stdout/stderr-Ausgabelog unter `.artifacts/qa-e2e/...`. + - Repo-Checkouts laden den gebündelten Runner direkt; kein separater Plugin-Installationsschritt + ist nötig. + - Stellt drei temporäre Matrix-Benutzer (`driver`, `sut`, `observer`) plus einen privaten Raum bereit und startet dann einen QA-Gateway-Child mit dem echten Matrix-Plugin als SUT-Transport. + - Verwendet standardmäßig das festgelegte stabile Tuwunel-Image `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Überschreibe es mit `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, wenn du ein anderes Image testen musst. + - Matrix stellt keine gemeinsamen Credential-Source-Flags bereit, da die Lane lokal temporäre Benutzer bereitstellt. + - Schreibt einen Matrix-QA-Bericht, eine Zusammenfassung, ein Observed-Events-Artefakt und ein kombiniertes stdout/stderr-Ausgabelog unter `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Führt die Telegram-Live-QA-Strecke gegen eine echte private Gruppe mit den Bot-Tokens für Driver und SUT aus den Umgebungsvariablen aus. + - Führt die Telegram-Live-QA-Lane gegen eine echte private Gruppe aus und verwendet dabei die Driver- und SUT-Bot-Tokens aus den Umgebungsvariablen. - Erfordert `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` und `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Die Gruppen-ID muss die numerische Telegram-Chat-ID sein. - - Unterstützt `--credential-source convex` für gemeinsame gepoolte Anmeldedaten. Verwenden Sie standardmäßig den Umgebungsmodus oder setzen Sie `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, um gepoolte Leases zu verwenden. - - Beendet sich mit einem Fehlercode ungleich null, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn Sie - Artefakte ohne fehlerhaften Exit-Code möchten. - - Erfordert zwei unterschiedliche Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellen muss. - - Für stabile Beobachtung von Bot-zu-Bot-Kommunikation aktivieren Sie den Modus „Bot-to-Bot Communication Mode“ in `@BotFather` für beide Bots und stellen Sie sicher, dass der Driver-Bot Bot-Verkehr in der Gruppe beobachten kann. - - Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und ein Artefakt mit beobachteten Nachrichten unter `.artifacts/qa-e2e/...`. + - Unterstützt `--credential-source convex` für gemeinsam genutzte gepoolte Anmeldedaten. Verwende standardmäßig den env-Modus oder setze `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, um gepoolte Leases zu nutzen. + - Beendet sich mit einem Fehlercode ungleich null, wenn irgendein Szenario fehlschlägt. Verwende `--allow-failures`, wenn du + Artefakte ohne fehlschlagenden Exit-Code möchtest. + - Erfordert zwei unterschiedliche Bots in derselben privaten Gruppe, wobei der SUT-Bot einen Telegram-Benutzernamen bereitstellt. + - Für stabile Bot-zu-Bot-Beobachtung aktiviere den Bot-zu-Bot-Kommunikationsmodus in `@BotFather` für beide Bots und stelle sicher, dass der Driver-Bot Bot-Traffic in der Gruppe beobachten kann. + - Schreibt einen Telegram-QA-Bericht, eine Zusammenfassung und ein Observed-Messages-Artefakt unter `.artifacts/qa-e2e/...`. -Live-Transport-Strecken teilen sich einen einheitlichen Standardvertrag, damit neue Transporte nicht auseinanderdriften: +Live-Transport-Lanes teilen sich einen standardisierten Vertrag, damit neue Transporte nicht auseinanderdriften: -`qa-channel` bleibt die breite synthetische QA-Suite und ist nicht Teil der Live- -Transport-Abdeckungsmatrix. +`qa-channel` bleibt die breit angelegte synthetische QA-Suite und ist nicht Teil der Live-Transport-Abdeckungsmatrix. -| Strecke | Canary | Mention-Gating | Allowlist-Block | Antwort auf oberster Ebene | Fortsetzen nach Neustart | Thread-Nachfassaktion | Thread-Isolation | Reaktionsbeobachtung | Hilfebefehl | -| -------- | ------ | -------------- | --------------- | -------------------------- | ------------------------ | --------------------- | ---------------- | -------------------- | ----------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Mention-Gating | Allowlist-Block | Antwort auf oberster Ebene | Neustart-Fortsetzung | Thread-Nachverfolgung | Thread-Isolation | Reaktionsbeobachtung | Help-Befehl | +| -------- | ------ | -------------- | --------------- | -------------------------- | -------------------- | --------------------- | ---------------- | -------------------- | ----------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Gemeinsame Telegram-Anmeldedaten über Convex (v1) Wenn `--credential-source convex` (oder `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) für `openclaw qa telegram` aktiviert ist, bezieht QA lab ein exklusives Lease aus einem Convex-gestützten Pool, sendet -Heartbeat-Signale für dieses Lease, während die Strecke läuft, und gibt das Lease beim Herunterfahren frei. +Heartbeat-Signale für dieses Lease, während die Lane läuft, und gibt das Lease beim Herunterfahren frei. Referenz-Gerüst für ein Convex-Projekt: @@ -130,9 +137,9 @@ Erforderliche Umgebungsvariablen: - Ein Secret für die ausgewählte Rolle: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` für `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` für `ci` -- Auswahl der Rollen für Anmeldedaten: +- Auswahl der Credential-Rolle: - CLI: `--credential-role maintainer|ci` - - Standard über Umgebungsvariable: `OPENCLAW_QA_CREDENTIAL_ROLE` (standardmäßig `ci` in CI, sonst `maintainer`) + - Env-Standard: `OPENCLAW_QA_CREDENTIAL_ROLE` (standardmäßig `ci` in CI, sonst `maintainer`) Optionale Umgebungsvariablen: @@ -142,12 +149,12 @@ Optionale Umgebungsvariablen: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (Standard `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (Standard `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (optionale Trace-ID) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` erlaubt loopback-`http://`-Convex-URLs nur für lokale Entwicklung. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` erlaubt loopback-`http://`-Convex-URLs für lokale Entwicklung. `OPENCLAW_QA_CONVEX_SITE_URL` sollte im normalen Betrieb `https://` verwenden. Maintainer-Admin-Befehle (Pool hinzufügen/entfernen/auflisten) erfordern -ausdrücklich `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +speziell `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. CLI-Helfer für Maintainer: @@ -157,9 +164,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Verwenden Sie `--json` für maschinenlesbare Ausgabe in Skripten und CI-Hilfsprogrammen. +Verwende `--json` für maschinenlesbare Ausgabe in Skripten und CI-Hilfsprogrammen. -Standard-Endpunktvertrag (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Standard-Endpoint-Vertrag (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Anfrage: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -177,68 +184,68 @@ Standard-Endpunktvertrag (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /admin/remove` (nur mit Maintainer-Secret) - Anfrage: `{ credentialId, actorId }` - Erfolg: `{ status: "ok", changed, credential }` - - Schutz bei aktivem Lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Schutz vor aktivem Lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (nur mit Maintainer-Secret) - Anfrage: `{ kind?, status?, includePayload?, limit? }` - Erfolg: `{ status: "ok", credentials, count }` -Nutzlastform für Telegram-Art: +Payload-Form für die Art Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` muss eine numerische Zeichenfolge der Telegram-Chat-ID sein. -- `admin/add` validiert diese Form für `kind: "telegram"` und weist fehlerhafte Nutzlasten zurück. +- `groupId` muss eine numerische Telegram-Chat-ID als String sein. +- `admin/add` validiert diese Form für `kind: "telegram"` und weist fehlerhafte Payloads zurück. -### Einen Kanal zur QA hinzufügen +### Einen Channel zu QA hinzufügen -Das Hinzufügen eines Kanals zum Markdown-QA-System erfordert genau zwei Dinge: +Das Hinzufügen eines Channels zum Markdown-QA-System erfordert genau zwei Dinge: -1. Einen Transport-Adapter für den Kanal. -2. Ein Szenario-Paket, das den Kanalvertrag ausübt. +1. Einen Transport-Adapter für den Channel. +2. Ein Szenario-Paket, das den Channel-Vertrag testet. -Fügen Sie keinen neuen Top-Level-Befehlsstamm für QA hinzu, wenn der gemeinsame `qa-lab`-Host +Füge keine neue Top-Level-Befehlswurzel für QA hinzu, wenn der gemeinsame `qa-lab`-Host den Ablauf übernehmen kann. -`qa-lab` gehört die gemeinsame Host-Mechanik: +`qa-lab` ist für die gemeinsamen Host-Mechanismen zuständig: -- der Befehlsstamm `openclaw qa` -- Start und Herunterfahren der Suite +- die Befehlswurzel `openclaw qa` +- Start und Beenden der Suite - Worker-Parallelität - Schreiben von Artefakten -- Berichtsgenerierung +- Berichtserstellung - Ausführung von Szenarien - Kompatibilitäts-Aliase für ältere `qa-channel`-Szenarien -Runner-Plugins gehören der Transportvertrag: +Runner-Plugins sind für den Transportvertrag zuständig: -- wie `openclaw qa ` unter dem gemeinsamen Stamm `qa` eingebunden wird +- wie `openclaw qa ` unter der gemeinsamen `qa`-Wurzel eingebunden wird - wie das Gateway für diesen Transport konfiguriert wird -- wie die Bereitschaft geprüft wird +- wie Bereitschaft geprüft wird - wie eingehende Ereignisse injiziert werden - wie ausgehende Nachrichten beobachtet werden -- wie Transkripte und normalisierter Transportzustand bereitgestellt werden +- wie Transkripte und normalisierter Transportstatus bereitgestellt werden - wie transportgestützte Aktionen ausgeführt werden -- wie transportspezifisches Zurücksetzen oder Bereinigen behandelt wird +- wie transportspezifisches Zurücksetzen oder Aufräumen behandelt wird -Die minimale Übernahmeschwelle für einen neuen Kanal ist: +Die minimale Hürde für die Aufnahme eines neuen Channels ist: -1. Behalten Sie `qa-lab` als Eigentümer des gemeinsamen Stamms `qa`. -2. Implementieren Sie den Transport-Runner auf der gemeinsamen Host-Schnittstelle von `qa-lab`. -3. Behalten Sie transportspezifische Mechanik im Runner-Plugin oder Kanal-Harness. -4. Binden Sie den Runner als `openclaw qa ` ein, statt einen konkurrierenden Stamm-Befehl zu registrieren. - Runner-Plugins sollten `qaRunners` in `openclaw.plugin.json` deklarieren und ein passendes Array `qaRunnerCliRegistrations` aus `runtime-api.ts` exportieren. - Halten Sie `runtime-api.ts` schlank; Lazy-CLI und Runner-Ausführung sollten hinter separaten Entry-Points bleiben. -5. Erstellen oder passen Sie Markdown-Szenarien unter den thematischen Verzeichnissen `qa/scenarios/` an. -6. Verwenden Sie die generischen Szenario-Helfer für neue Szenarien. -7. Halten Sie bestehende Kompatibilitäts-Aliase funktionsfähig, sofern das Repository keine absichtliche Migration durchführt. +1. Behalte `qa-lab` als Eigentümer der gemeinsamen `qa`-Wurzel bei. +2. Implementiere den Transport-Runner am gemeinsamen `qa-lab`-Host-Seam. +3. Halte transportspezifische Mechanismen innerhalb des Runner-Plugins oder Channel-Harness. +4. Binde den Runner als `openclaw qa ` ein, statt eine konkurrierende Root-Command zu registrieren. + Runner-Plugins sollten `qaRunners` in `openclaw.plugin.json` deklarieren und ein passendes `qaRunnerCliRegistrations`-Array aus `runtime-api.ts` exportieren. + Halte `runtime-api.ts` schlank; lazy CLI und Runner-Ausführung sollten hinter separaten Entry-Points bleiben. +5. Erstelle oder passe Markdown-Szenarien unter den thematischen Verzeichnissen `qa/scenarios/` an. +6. Verwende die generischen Szenario-Helfer für neue Szenarien. +7. Halte bestehende Kompatibilitäts-Aliase funktionsfähig, sofern das Repo keine absichtliche Migration durchführt. Die Entscheidungsregel ist strikt: -- Wenn sich Verhalten einmalig in `qa-lab` ausdrücken lässt, gehört es in `qa-lab`. -- Wenn Verhalten von einem Kanaltransport abhängt, behalten Sie es im Runner-Plugin oder Plugin-Harness dieses Transports. -- Wenn ein Szenario eine neue Fähigkeit benötigt, die mehr als ein Kanal verwenden kann, fügen Sie einen generischen Helfer hinzu statt eines kanalspezifischen Zweigs in `suite.ts`. -- Wenn ein Verhalten nur für einen Transport sinnvoll ist, behalten Sie das Szenario transportspezifisch und machen Sie das im Szenariovertrag ausdrücklich. +- Wenn sich das Verhalten einmalig in `qa-lab` ausdrücken lässt, lege es in `qa-lab` ab. +- Wenn das Verhalten von einem einzelnen Channel-Transport abhängt, halte es in diesem Runner-Plugin oder Plugin-Harness. +- Wenn ein Szenario eine neue Fähigkeit benötigt, die mehr als ein Channel nutzen kann, füge einen generischen Helfer hinzu statt eines channel-spezifischen Branches in `suite.ts`. +- Wenn ein Verhalten nur für einen Transport sinnvoll ist, halte das Szenario transportspezifisch und mache das im Szenario-Vertrag ausdrücklich. -Bevorzugte generische Helfernamen für neue Szenarien sind: +Bevorzugte Namen für generische Helfer in neuen Szenarien sind: - `waitForTransportReady` - `waitForChannelReady` @@ -261,105 +268,105 @@ Kompatibilitäts-Aliase bleiben für bestehende Szenarien verfügbar, darunter: - `formatConversationTranscript` - `resetBus` -Neue Kanalarbeit sollte die generischen Helfernamen verwenden. -Kompatibilitäts-Aliase existieren, um eine Migration an einem Stichtag zu vermeiden, nicht als Modell für -das Verfassen neuer Szenarien. +Neue Channel-Arbeit sollte die generischen Helfernamen verwenden. +Kompatibilitäts-Aliase existieren, um eine Flag-Day-Migration zu vermeiden, nicht als Modell für +neue Szenario-Erstellung. -## Testsuiten (was wo läuft) +## Test-Suiten (was wo läuft) -Betrachten Sie die Suiten als „zunehmenden Realismus“ (und zunehmende Unzuverlässigkeit/Kosten): +Betrachte die Suiten als „zunehmenden Realismus“ (und zunehmende Instabilität/Kosten): ### Unit / Integration (Standard) - Befehl: `pnpm test` -- Konfiguration: zehn sequentielle Shard-Läufe (`vitest.full-*.config.ts`) über die vorhandenen abgegrenzten Vitest-Projekte -- Dateien: Core-/Unit-Inventare unter `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` und die freigegebenen `ui`-Node-Tests, die von `vitest.unit.config.ts` abgedeckt werden +- Konfiguration: zehn sequentielle Shard-Läufe (`vitest.full-*.config.ts`) über die bestehenden eingegrenzten Vitest-Projekte +- Dateien: Core-/Unit-Inventare unter `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` und die per Whitelist zugelassenen `ui`-Node-Tests, die von `vitest.unit.config.ts` abgedeckt werden - Umfang: - Reine Unit-Tests - - In-Process-Integrationstests (Gateway-Auth, Routing, Tooling, Parsing, Konfiguration) + - In-Process-Integrationstests (Gateway-Authentifizierung, Routing, Tooling, Parsing, Konfiguration) - Deterministische Regressionen für bekannte Fehler - Erwartungen: - Läuft in CI - Keine echten Schlüssel erforderlich - Sollte schnell und stabil sein - Hinweis zu Projekten: - - Nicht zielgerichtetes `pnpm test` führt jetzt elf kleinere Shard-Konfigurationen (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) statt eines riesigen nativen Root-Project-Prozesses aus. Das senkt den Spitzen-RSS auf ausgelasteten Maschinen und verhindert, dass Auto-Reply-/Erweiterungsarbeit nicht verwandte Suiten ausbremst. - - `pnpm test --watch` verwendet weiterhin den nativen Root-Project-Graph `vitest.config.ts`, weil eine Watch-Schleife über mehrere Shards nicht praktikabel ist. - - `pnpm test`, `pnpm test:watch` und `pnpm test:perf:imports` leiten explizite Datei-/Verzeichnisziele jetzt zuerst über abgegrenzte Strecken, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die vollständigen Startkosten des Root-Projekts bezahlen muss. - - `pnpm test:changed` erweitert geänderte Git-Pfade auf dieselben abgegrenzten Strecken, wenn der Diff nur routingfähige Quell-/Testdateien betrifft; Änderungen an Konfiguration/Setup fallen weiterhin auf die breite erneute Ausführung des Root-Projekts zurück. - - `pnpm check:changed` ist das normale intelligente lokale Gate für eng begrenzte Arbeit. Es klassifiziert den Diff in Core, Core-Tests, Erweiterungen, Erweiterungstests, Apps, Dokumentation und Tooling und führt dann die passenden Strecken für Typecheck/Lint/Tests aus. Änderungen am öffentlichen Plugin SDK und an Plugin-Verträgen schließen Erweiterungsvalidierung ein, weil Erweiterungen von diesen Core-Verträgen abhängen. - - Import-leichte Unit-Tests aus Agents, Commands, Plugins, Auto-Reply-Helfern, `plugin-sdk` und ähnlichen reinen Utility-Bereichen laufen über die Strecke `unit-fast`, die `test/setup-openclaw-runtime.ts` überspringt; zustandsbehaftete/laufzeitschwere Dateien bleiben auf den bestehenden Strecken. - - Ausgewählte Quell-Hilfsdateien aus `plugin-sdk` und `commands` ordnen Läufe im Changed-Modus auch expliziten Nachbartests in diesen leichten Strecken zu, sodass Änderungen an Hilfsfunktionen nicht die komplette schwere Suite für dieses Verzeichnis erneut ausführen. - - `auto-reply` hat jetzt drei dedizierte Buckets: Core-Helfer auf oberster Ebene, `reply.*`-Integrationstests auf oberster Ebene und den Teilbaum `src/auto-reply/reply/**`. So bleibt die schwerste Reply-Harness-Arbeit von günstigen Status-/Chunk-/Token-Tests getrennt. + - Ungezieltes `pnpm test` führt jetzt elf kleinere Shard-Konfigurationen aus (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) statt eines einzigen riesigen nativen Root-Project-Prozesses. Das reduziert die Spitzen-RSS auf ausgelasteten Maschinen und verhindert, dass auto-reply-/Extension-Arbeit unabhängige Suiten ausbremst. + - `pnpm test --watch` verwendet weiterhin den nativen Root-`vitest.config.ts`-Projektgraphen, weil eine Multi-Shard-Watch-Schleife nicht praktikabel ist. + - `pnpm test`, `pnpm test:watch` und `pnpm test:perf:imports` leiten explizite Datei-/Verzeichnisziele jetzt zuerst durch eingegrenzte Lanes, sodass `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` nicht die vollen Startkosten des Root-Projekts zahlen muss. + - `pnpm test:changed` erweitert geänderte Git-Pfade auf dieselben eingegrenzten Lanes, wenn der Diff nur routbare Quell-/Testdateien betrifft; Änderungen an Konfiguration/Setup fallen weiterhin auf den breiten Root-Project-Neulauf zurück. + - `pnpm check:changed` ist das normale intelligente lokale Gate für eng begrenzte Arbeit. Es klassifiziert den Diff in Core, Core-Tests, Extensions, Extension-Tests, Apps, Doku und Tooling und führt dann die passenden Typecheck-/Lint-/Test-Lanes aus. Änderungen am öffentlichen Plugin SDK und an Plugin-Verträgen schließen Extension-Validierung ein, weil Extensions von diesen Core-Verträgen abhängen. + - Import-leichte Unit-Tests aus Agents, Commands, Plugins, auto-reply-Helfern, `plugin-sdk` und ähnlichen reinen Utility-Bereichen laufen über die `unit-fast`-Lane, die `test/setup-openclaw-runtime.ts` überspringt; zustandsbehaftete/laufzeitintensive Dateien bleiben auf den bestehenden Lanes. + - Ausgewählte Hilfsquellendateien aus `plugin-sdk` und `commands` ordnen Läufe im Changed-Modus ebenfalls expliziten Nachbartests in diesen leichten Lanes zu, sodass Hilfsänderungen nicht die gesamte schwere Suite für dieses Verzeichnis neu ausführen. + - `auto-reply` hat jetzt drei dedizierte Buckets: Core-Helfer auf oberster Ebene, `reply.*`-Integrationstests auf oberster Ebene und den Teilbaum `src/auto-reply/reply/**`. Dadurch bleibt die schwerste Reply-Harness-Arbeit von den günstigen Status-/Chunk-/Token-Tests getrennt. - Hinweis zum eingebetteten Runner: - - Wenn Sie Eingaben für die Erkennung von Nachrichtentools oder den Laufzeitkontext von Compaction ändern, - behalten Sie beide Abdeckungsebenen bei. - - Fügen Sie fokussierte Helfer-Regressionen für reine Routing-/Normalisierungsgrenzen hinzu. - - Halten Sie außerdem die Integrationstests des eingebetteten Runners gesund: + - Wenn du Eingaben für die Message-Tool-Erkennung oder den Compaction-Laufzeitkontext änderst, + halte beide Abdeckungsebenen aufrecht. + - Füge fokussierte Helfer-Regressionen für reine Routing-/Normalisierungsgrenzen hinzu. + - Halte auch die Integrationssuiten des eingebetteten Runners gesund: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` und `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Diese Suiten verifizieren, dass abgegrenzte IDs und Compaction-Verhalten weiterhin - durch die echten Pfade `run.ts` / `compact.ts` fließen; reine Helfertests sind kein + - Diese Suiten verifizieren, dass Scoped-IDs und Compaction-Verhalten weiterhin + durch die echten Pfade `run.ts` / `compact.ts` fließen; reine Helfer-Tests sind kein ausreichender Ersatz für diese Integrationspfade. - Hinweis zum Pool: - Die Basis-Vitest-Konfiguration verwendet jetzt standardmäßig `threads`. - - Die gemeinsam genutzte Vitest-Konfiguration setzt außerdem fest `isolate: false` und verwendet den nicht isolierten Runner über Root-Projekte, E2E- und Live-Konfigurationen hinweg. - - Die Root-UI-Strecke behält ihr `jsdom`-Setup und ihren Optimizer, läuft jetzt aber ebenfalls auf dem gemeinsam genutzten nicht isolierten Runner. - - Jeder Shard von `pnpm test` erbt dieselben Standardwerte `threads` + `isolate: false` aus der gemeinsam genutzten Vitest-Konfiguration. - - Der gemeinsam genutzte Launcher `scripts/run-vitest.mjs` fügt jetzt standardmäßig auch `--no-maglev` für Vitest-Child-Node-Prozesse hinzu, um V8-Kompilieraufwand bei großen lokalen Läufen zu reduzieren. Setzen Sie `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, wenn Sie gegen das Standardverhalten von V8 vergleichen müssen. + - Die gemeinsame Vitest-Konfiguration setzt außerdem `isolate: false` fest und verwendet den nicht isolierten Runner über Root-Projekte, E2E- und Live-Konfigurationen hinweg. + - Die Root-UI-Lane behält ihr `jsdom`-Setup und ihren Optimizer, läuft jetzt aber ebenfalls auf dem gemeinsamen nicht isolierten Runner. + - Jeder `pnpm test`-Shard übernimmt dieselben Standardwerte `threads` + `isolate: false` aus der gemeinsamen Vitest-Konfiguration. + - Der gemeinsame Launcher `scripts/run-vitest.mjs` fügt jetzt standardmäßig auch `--no-maglev` für Vitest-Child-Node-Prozesse hinzu, um bei großen lokalen Läufen den V8-Kompilierungsaufwand zu reduzieren. Setze `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, wenn du mit dem Standardverhalten von V8 vergleichen musst. - Hinweis zur schnellen lokalen Iteration: - - `pnpm changed:lanes` zeigt, welche architektonischen Strecken ein Diff auslöst. - - Der Pre-Commit-Hook führt nach gestuftem Formatieren/Linting `pnpm check:changed --staged` aus, sodass reine Core-Commits nicht die Kosten von Erweiterungstests verursachen, sofern sie keine öffentlichen, erweiterungsrelevanten Verträge berühren. - - `pnpm test:changed` leitet über abgegrenzte Strecken, wenn die geänderten Pfade sauber auf eine kleinere Suite abgebildet werden können. - - `pnpm test:max` und `pnpm test:changed:max` behalten dasselbe Routing-Verhalten bei, nur mit höherem Worker-Limit. - - Die automatische lokale Skalierung der Worker ist jetzt absichtlich konservativ und fährt auch zurück, wenn die Host-Load-Average bereits hoch ist, sodass mehrere gleichzeitige Vitest-Läufe standardmäßig weniger Schaden anrichten. - - Die Basis-Vitest-Konfiguration markiert die Projekte/Konfigurationsdateien als `forceRerunTriggers`, damit erneute Läufe im Changed-Modus korrekt bleiben, wenn sich die Testverdrahtung ändert. - - Die Konfiguration hält `OPENCLAW_VITEST_FS_MODULE_CACHE` auf unterstützten Hosts aktiviert; setzen Sie `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, wenn Sie einen expliziten Cache-Ort für direktes Profiling möchten. + - `pnpm changed:lanes` zeigt, welche Architekturlanes ein Diff auslöst. + - Der Pre-Commit-Hook führt `pnpm check:changed --staged` nach gestuftem Formatting/Linting aus, sodass reine Core-Commits keine Extension-Testkosten verursachen, sofern sie keine öffentlichen, Extension-seitigen Verträge berühren. + - `pnpm test:changed` leitet durch eingegrenzte Lanes, wenn die geänderten Pfade sauber auf eine kleinere Suite abbildbar sind. + - `pnpm test:max` und `pnpm test:changed:max` behalten dasselbe Routing-Verhalten bei, nur mit einem höheren Worker-Limit. + - Die automatische Skalierung lokaler Worker ist jetzt absichtlich konservativ und fährt auch zurück, wenn die Host-Load-Average bereits hoch ist, sodass mehrere gleichzeitige Vitest-Läufe standardmäßig weniger Schaden anrichten. + - Die Basis-Vitest-Konfiguration markiert die Projekte-/Konfigurationsdateien als `forceRerunTriggers`, damit Wiederholungsläufe im Changed-Modus korrekt bleiben, wenn sich die Test-Verdrahtung ändert. + - Die Konfiguration lässt `OPENCLAW_VITEST_FS_MODULE_CACHE` auf unterstützten Hosts aktiviert; setze `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, wenn du einen expliziten Cache-Speicherort für direktes Profiling möchtest. - Hinweis zum Performance-Debugging: - - `pnpm test:perf:imports` aktiviert die Berichterstattung zur Importdauer von Vitest plus Ausgabe der Importaufschlüsselung. - - `pnpm test:perf:imports:changed` begrenzt dieselbe Profiling-Ansicht auf Dateien, die seit `origin/main` geändert wurden. -- `pnpm test:perf:changed:bench -- --ref ` vergleicht geroutetes `test:changed` mit dem nativen Root-Project-Pfad für diesen festgeschriebenen Diff und gibt Laufzeit sowie macOS-Max-RSS aus. -- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen veränderten Arbeitsbaum, indem die Liste geänderter Dateien durch `scripts/test-projects.mjs` und die Root-Vitest-Konfiguration geleitet wird. - - `pnpm test:perf:profile:main` schreibt ein CPU-Profil des Main-Threads für Vitest/Vite-Start- und Transformations-Overhead. - - `pnpm test:perf:profile:runner` schreibt CPU- + Heap-Profile des Runners für die Unit-Suite bei deaktivierter Dateiparallelität. + - `pnpm test:perf:imports` aktiviert die Import-Dauer-Berichterstattung von Vitest sowie die Ausgabe der Import-Aufschlüsselung. + - `pnpm test:perf:imports:changed` begrenzt dieselbe Profiling-Ansicht auf Dateien, die sich seit `origin/main` geändert haben. +- `pnpm test:perf:changed:bench -- --ref ` vergleicht geroutetes `test:changed` mit dem nativen Root-Project-Pfad für diesen commiteten Diff und gibt Wall-Time plus macOS-Max-RSS aus. +- `pnpm test:perf:changed:bench -- --worktree` benchmarkt den aktuellen dirty Tree, indem die Liste geänderter Dateien durch `scripts/test-projects.mjs` und die Root-Vitest-Konfiguration geleitet wird. + - `pnpm test:perf:profile:main` schreibt ein CPU-Profil des Main-Threads für Vitest/Vite-Start und Transform-Overhead. + - `pnpm test:perf:profile:runner` schreibt Runner-CPU-+Heap-Profile für die Unit-Suite bei deaktivierter Dateiparallelität. -### E2E (Gateway-Smoketest) +### E2E (Gateway-Smoke) - Befehl: `pnpm test:e2e` - Konfiguration: `vitest.e2e.config.ts` - Dateien: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Laufzeitstandards: - - Verwendet Vitest `threads` mit `isolate: false`, passend zum Rest des Repositorys. +- Laufzeit-Standards: + - Verwendet Vitest-`threads` mit `isolate: false`, passend zum Rest des Repos. - Verwendet adaptive Worker (CI: bis zu 2, lokal: standardmäßig 1). - - Läuft standardmäßig im Silent-Modus, um den Overhead durch Konsolen-I/O zu reduzieren. + - Läuft standardmäßig im Silent-Modus, um den Console-I/O-Overhead zu reduzieren. - Nützliche Überschreibungen: - - `OPENCLAW_E2E_WORKERS=`, um die Anzahl der Worker zu erzwingen (begrenzt auf 16). - - `OPENCLAW_E2E_VERBOSE=1`, um ausführliche Konsolenausgabe wieder zu aktivieren. + - `OPENCLAW_E2E_WORKERS=`, um die Worker-Anzahl zu erzwingen (begrenzt auf 16). + - `OPENCLAW_E2E_VERBOSE=1`, um ausführliche Console-Ausgabe wieder zu aktivieren. - Umfang: - - End-to-End-Verhalten des Gateway mit mehreren Instanzen - - WebSocket-/HTTP-Oberflächen, Node-Pairing und schwereres Networking + - Multi-Instance-Gateway-End-to-End-Verhalten + - WebSocket-/HTTP-Oberflächen, Node-Pairing und schwergewichtigere Netzwerkarbeit - Erwartungen: - Läuft in CI (wenn in der Pipeline aktiviert) - Keine echten Schlüssel erforderlich - Mehr bewegliche Teile als Unit-Tests (kann langsamer sein) -### E2E: OpenShell-Backend-Smoketest +### E2E: OpenShell-Backend-Smoke - Befehl: `pnpm test:e2e:openshell` - Datei: `test/openshell-sandbox.e2e.test.ts` - Umfang: - - Startet ein isoliertes OpenShell-Gateway auf dem Host über Docker + - Startet über Docker ein isoliertes OpenShell-Gateway auf dem Host - Erstellt eine Sandbox aus einem temporären lokalen Dockerfile - - Übt das OpenShell-Backend von OpenClaw über echtes `sandbox ssh-config` + SSH-Exec aus - - Verifiziert kanonisches Remote-Dateisystemverhalten über die Sandbox-FS-Bridge + - Testet OpenClaws OpenShell-Backend über echtes `sandbox ssh-config` + SSH-Exec + - Verifiziert remote-kanonisches Dateisystemverhalten über die Sandbox-fs-Bridge - Erwartungen: - - Nur Opt-in; nicht Teil des Standardlaufs `pnpm test:e2e` + - Nur per Opt-in; nicht Teil des standardmäßigen `pnpm test:e2e`-Laufs - Erfordert eine lokale `openshell`-CLI plus einen funktionierenden Docker-Daemon - Verwendet isoliertes `HOME` / `XDG_CONFIG_HOME` und zerstört dann Test-Gateway und Sandbox - Nützliche Überschreibungen: - `OPENCLAW_E2E_OPENSHELL=1`, um den Test zu aktivieren, wenn die breitere E2E-Suite manuell ausgeführt wird - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, um auf eine nicht standardmäßige CLI-Binärdatei oder ein Wrapper-Skript zu zeigen + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, um auf eine nicht standardmäßige CLI-Binärdatei oder ein Wrapper-Skript zu verweisen ### Live (echte Provider + echte Modelle) @@ -369,140 +376,140 @@ Betrachten Sie die Suiten als „zunehmenden Realismus“ (und zunehmende Unzuve - Standard: **aktiviert** durch `pnpm test:live` (setzt `OPENCLAW_LIVE_TEST=1`) - Umfang: - „Funktioniert dieser Provider/dieses Modell _heute_ tatsächlich mit echten Anmeldedaten?“ - - Erkennt Änderungen im Provider-Format, Eigenheiten bei Tool-Aufrufen, Auth-Probleme und Rate-Limit-Verhalten + - Erfasst Provider-Formatänderungen, Tool-Calling-Eigenheiten, Auth-Probleme und Rate-Limit-Verhalten - Erwartungen: - - Nicht von Natur aus CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Quoten, Ausfälle) - - Kostet Geld / verbraucht Rate-Limits - - Bevorzugt eingeschränkte Teilmengen statt „alles“ -- Live-Läufe beziehen `~/.profile` ein, um fehlende API-Schlüssel zu übernehmen. -- Standardmäßig isolieren Live-Läufe weiterhin `HOME` und kopieren Konfigurations-/Auth-Material in ein temporäres Test-Home, damit Unit-Fixtures Ihr echtes `~/.openclaw` nicht verändern können. -- Setzen Sie `OPENCLAW_LIVE_USE_REAL_HOME=1` nur dann, wenn Live-Tests bewusst Ihr echtes Home-Verzeichnis verwenden sollen. -- `pnpm test:live` verwendet jetzt standardmäßig einen ruhigeren Modus: Es behält die Fortschrittsausgabe `[live] ...` bei, unterdrückt aber den zusätzlichen Hinweis zu `~/.profile` und schaltet Bootstrap-Logs des Gateway/Bonjour-Geräusche stumm. Setzen Sie `OPENCLAW_LIVE_TEST_QUIET=0`, wenn Sie die vollständigen Start-Logs wieder haben möchten. -- API-Schlüsselrotation (providerspezifisch): Setzen Sie `*_API_KEYS` im Komma-/Semikolonformat oder `*_API_KEY_1`, `*_API_KEY_2` (zum Beispiel `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oder eine pro-Live-Überschreibung über `OPENCLAW_LIVE_*_KEY`; Tests wiederholen bei Rate-Limit-Antworten. + - Absichtlich nicht CI-stabil (echte Netzwerke, echte Provider-Richtlinien, Quoten, Ausfälle) + - Kostet Geld / verbraucht Rate Limits + - Bevorzuge eingegrenzte Teilmengen statt „alles“ +- Live-Läufe sourcen `~/.profile`, um fehlende API-Schlüssel aufzugreifen. +- Standardmäßig isolieren Live-Läufe weiterhin `HOME` und kopieren Konfigurations-/Auth-Material in ein temporäres Test-Home, damit Unit-Fixtures dein echtes `~/.openclaw` nicht verändern können. +- Setze `OPENCLAW_LIVE_USE_REAL_HOME=1` nur, wenn du absichtlich möchtest, dass Live-Tests dein echtes Home-Verzeichnis verwenden. +- `pnpm test:live` verwendet jetzt standardmäßig einen leiseren Modus: Es behält die Fortschrittsausgabe `[live] ...` bei, unterdrückt aber den zusätzlichen Hinweis zu `~/.profile` und schaltet Gateway-Bootstrap-Logs/Bonjour-Chattyness stumm. Setze `OPENCLAW_LIVE_TEST_QUIET=0`, wenn du die vollständigen Start-Logs wiederhaben möchtest. +- API-Key-Rotation (providerspezifisch): setze `*_API_KEYS` im Komma-/Semikolon-Format oder `*_API_KEY_1`, `*_API_KEY_2` (zum Beispiel `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) oder einen provider-live-spezifischen Override über `OPENCLAW_LIVE_*_KEY`; Tests wiederholen sich bei Rate-Limit-Antworten. - Fortschritts-/Heartbeat-Ausgabe: - - Live-Suiten geben Fortschrittszeilen jetzt nach stderr aus, damit lange Provider-Aufrufe sichtbar aktiv bleiben, selbst wenn die Vitest-Konsolenerfassung ruhig ist. - - `vitest.live.config.ts` deaktiviert die Konsolenabfangung von Vitest, sodass Fortschrittszeilen von Provider/Gateway bei Live-Läufen sofort gestreamt werden. - - Passen Sie Heartbeats direkter Modelle mit `OPENCLAW_LIVE_HEARTBEAT_MS` an. - - Passen Sie Heartbeats für Gateway/Probe mit `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` an. + - Live-Suiten geben jetzt Fortschrittszeilen auf stderr aus, sodass lange Provider-Aufrufe sichtbar aktiv bleiben, auch wenn die Vitest-Console-Erfassung leise ist. + - `vitest.live.config.ts` deaktiviert die Vitest-Console-Abfanglogik, sodass Provider-/Gateway-Fortschrittszeilen bei Live-Läufen sofort gestreamt werden. + - Passe Heartbeats für direkte Modelle mit `OPENCLAW_LIVE_HEARTBEAT_MS` an. + - Passe Heartbeats für Gateway/Sonden mit `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` an. ## Welche Suite sollte ich ausführen? -Verwenden Sie diese Entscheidungstabelle: +Verwende diese Entscheidungstabelle: -- Logik/Tests bearbeiten: `pnpm test` ausführen (und `pnpm test:coverage`, wenn Sie viel geändert haben) -- Gateway-Networking / WS-Protokoll / Pairing anfassen: `pnpm test:e2e` hinzufügen -- „Mein Bot ist down“ / providerspezifische Fehler / Tool-Calling debuggen: eine eingeschränkte `pnpm test:live` ausführen +- Logik/Tests bearbeiten: `pnpm test` ausführen (und `pnpm test:coverage`, wenn du viel geändert hast) +- Gateway-Netzwerk / WS-Protokoll / Pairing anfassen: zusätzlich `pnpm test:e2e` +- „Mein Bot ist down“ / provider-spezifische Fehler / Tool Calling debuggen: ein eingegrenztes `pnpm test:live` ausführen -## Live: Android-Node-Fähigkeitstest +## Live: Android-Node-Capability-Sweep - Test: `src/gateway/android-node.capabilities.live.test.ts` - Skript: `pnpm android:test:integration` -- Ziel: **Jeden aktuell angekündigten Befehl** eines verbundenen Android-Node aufrufen und das Vertragsverhalten des Befehls prüfen. +- Ziel: **jeden aktuell beworbenen Befehl** eines verbundenen Android-Node aufrufen und das Befehlsvertragsverhalten prüfen. - Umfang: - Vorbereitete/manuelle Einrichtung (die Suite installiert/startet/paired die App nicht). - - Gateway-`node.invoke`-Validierung für jeden Befehl des ausgewählten Android-Node. -- Erforderliche Vorbereitung: - - Android-App ist bereits mit dem Gateway verbunden und gepaart. - - App bleibt im Vordergrund. - - Berechtigungen/Erfassungszustimmung sind für Fähigkeiten erteilt, die erfolgreich sein sollen. -- Optionale Zielüberschreibungen: + - Gateway-Validierung von `node.invoke` Befehl für Befehl für den ausgewählten Android-Node. +- Erforderliche Vorab-Einrichtung: + - Android-App bereits mit dem Gateway verbunden + gepairt. + - App im Vordergrund halten. + - Berechtigungen/Capture-Zustimmung für Fähigkeiten erteilt, deren Bestehen du erwartest. +- Optionale Target-Überschreibungen: - `OPENCLAW_ANDROID_NODE_ID` oder `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Vollständige Details zur Android-Einrichtung: [Android-App](/de/platforms/android) +- Vollständige Details zur Android-Einrichtung: [Android App](/de/platforms/android) -## Live: Modell-Smoketest (Profilschlüssel) +## Live: Modell-Smoke (Profil-Schlüssel) -Live-Tests sind in zwei Ebenen aufgeteilt, damit Fehler isoliert werden können: +Live-Tests sind in zwei Ebenen aufgeteilt, damit wir Fehler isolieren können: -- „Direktes Modell“ zeigt uns, ob der Provider/das Modell mit dem gegebenen Schlüssel überhaupt antworten kann. -- „Gateway-Smoketest“ zeigt uns, ob die vollständige Gateway+Agent-Pipeline für dieses Modell funktioniert (Sitzungen, Verlauf, Tools, Sandbox-Richtlinie usw.). +- „Direct model“ zeigt uns, dass der Provider/das Modell mit dem angegebenen Schlüssel überhaupt antworten kann. +- „Gateway smoke“ zeigt uns, dass die vollständige Gateway-+Agent-Pipeline für dieses Modell funktioniert (Sitzungen, Verlauf, Tools, Sandbox-Policy usw.). ### Ebene 1: Direkte Modell-Completion (ohne Gateway) - Test: `src/agents/models.profiles.live.test.ts` - Ziel: - Erkannte Modelle aufzählen - - Mit `getApiKeyForModel` Modelle auswählen, für die Sie Anmeldedaten haben + - `getApiKeyForModel` verwenden, um Modelle auszuwählen, für die du Anmeldedaten hast - Eine kleine Completion pro Modell ausführen (und gezielte Regressionen, wo nötig) - Aktivierung: - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) -- Setzen Sie `OPENCLAW_LIVE_MODELS=modern` (oder `all`, Alias für modern), um diese Suite tatsächlich auszuführen; andernfalls wird sie übersprungen, damit `pnpm test:live` auf den Gateway-Smoketest fokussiert bleibt +- Setze `OPENCLAW_LIVE_MODELS=modern` (oder `all`, Alias für modern), um diese Suite tatsächlich auszuführen; andernfalls wird sie übersprungen, damit `pnpm test:live` auf Gateway-Smoke fokussiert bleibt - Modellauswahl: - `OPENCLAW_LIVE_MODELS=modern`, um die moderne Allowlist auszuführen (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` ist ein Alias für die moderne Allowlist - - oder `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (kommagetrennte Allowlist) - - Sweeps mit modern/all verwenden standardmäßig ein kuratiertes High-Signal-Limit; setzen Sie `OPENCLAW_LIVE_MAX_MODELS=0` für einen vollständigen modernen Sweep oder einen positiven Wert für ein kleineres Limit. + - oder `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (durch Kommata getrennte Allowlist) + - Modern-/All-Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setze `OPENCLAW_LIVE_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze. - Providerauswahl: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (kommagetrennte Allowlist) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (durch Kommata getrennte Allowlist) - Woher die Schlüssel kommen: - - Standardmäßig: Profilspeicher und Fallbacks aus der Umgebung - - Setzen Sie `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um **nur** den Profilspeicher zu erzwingen -- Warum das existiert: + - Standardmäßig: Profilspeicher und Env-Fallbacks + - Setze `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um **nur den Profilspeicher** zu erzwingen +- Warum es das gibt: - Trennt „Provider-API ist kaputt / Schlüssel ist ungültig“ von „Gateway-Agent-Pipeline ist kaputt“ - Enthält kleine, isolierte Regressionen (Beispiel: OpenAI-Responses/Codex-Responses-Reasoning-Replay + Tool-Call-Flows) -### Ebene 2: Gateway + dev-Agent-Smoketest (was `@openclaw` tatsächlich tut) +### Ebene 2: Gateway + Dev-Agent-Smoke (was „@openclaw“ tatsächlich macht) - Test: `src/gateway/gateway-models.profiles.live.test.ts` - Ziel: - - Ein In-Process-Gateway starten - - Eine Sitzung `agent:dev:*` erstellen/anpassen (Modellüberschreibung pro Lauf) + - Ein In-Process-Gateway hochfahren + - Eine Sitzung `agent:dev:*` erstellen/patchen (Modell-Override pro Lauf) - Modelle mit Schlüsseln durchlaufen und prüfen: - „sinnvolle“ Antwort (ohne Tools) - - ein echter Tool-Aufruf funktioniert (Read-Probe) - - optionale zusätzliche Tool-Probes (Exec+Read-Probe) - - OpenAI-Regressionspfade (nur Tool-Call → Nachfassaktion) funktionieren weiter -- Details zu den Probes (damit Fehler schnell erklärt werden können): + - eine echte Tool-Invocation funktioniert (Read-Probe) + - optionale zusätzliche Tool-Sonden (Exec+Read-Probe) + - OpenAI-Regressionspfade (nur Tool-Call → Follow-up) weiter funktionieren +- Sondendetails (damit du Fehler schnell erklären kannst): - `read`-Probe: Der Test schreibt eine Nonce-Datei in den Workspace und fordert den Agenten auf, sie zu `read`en und die Nonce zurückzugeben. - - `exec+read`-Probe: Der Test fordert den Agenten auf, per `exec` eine Nonce in eine temporäre Datei zu schreiben und sie dann per `read` wieder einzulesen. - - Bild-Probe: Der Test hängt eine erzeugte PNG-Datei an (Katze + zufälliger Code) und erwartet, dass das Modell `cat ` zurückgibt. - - Referenz zur Implementierung: `src/gateway/gateway-models.profiles.live.test.ts` und `src/gateway/live-image-probe.ts`. + - `exec+read`-Probe: Der Test fordert den Agenten auf, per `exec` eine Nonce in eine temporäre Datei zu schreiben und sie dann per `read` zurückzugeben. + - Image-Probe: Der Test hängt ein generiertes PNG an (Katze + zufälliger Code) und erwartet, dass das Modell `cat ` zurückgibt. + - Implementierungsreferenz: `src/gateway/gateway-models.profiles.live.test.ts` und `src/gateway/live-image-probe.ts`. - Aktivierung: - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) - Modellauswahl: - Standard: moderne Allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` ist ein Alias für die moderne Allowlist - - Oder setzen Sie `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (oder eine Kommaliste), um einzugrenzen - - Gateway-Sweeps mit modern/all verwenden standardmäßig ein kuratiertes High-Signal-Limit; setzen Sie `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` für einen vollständigen modernen Sweep oder einen positiven Wert für ein kleineres Limit. -- Providerauswahl (vermeiden Sie „alles über OpenRouter“): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (kommagetrennte Allowlist) -- Tool- + Bild-Probes sind in diesem Live-Test immer aktiv: - - `read`-Probe + `exec+read`-Probe (Tool-Stress) - - Bild-Probe läuft, wenn das Modell Unterstützung für Bildeingaben ankündigt - - Ablauf (Überblick): - - Der Test erzeugt eine winzige PNG-Datei mit „CAT“ + Zufallscode (`src/gateway/live-image-probe.ts`) - - Sendet sie über `agent` mit `attachments: [{ mimeType: "image/png", content: "" }]` - - Das Gateway parst Anhänge in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Der eingebettete Agent leitet eine multimodale Nutzernachricht an das Modell weiter + - Oder setze `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (oder eine durch Kommata getrennte Liste), um einzugrenzen + - Modern-/All-Gateway-Sweeps verwenden standardmäßig eine kuratierte Obergrenze mit hohem Signal; setze `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` für einen vollständigen modernen Sweep oder eine positive Zahl für eine kleinere Obergrenze. +- Providerauswahl (vermeide „OpenRouter alles“): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (durch Kommata getrennte Allowlist) +- Tool- + Image-Sonden sind in diesem Live-Test immer aktiv: + - `read`-Probe + `exec+read`-Probe (Tool-Stresstest) + - Die Image-Probe läuft, wenn das Modell Unterstützung für Bildeingaben bewirbt + - Ablauf (grobe Übersicht): + - Der Test erzeugt ein kleines PNG mit „CAT“ + Zufallscode (`src/gateway/live-image-probe.ts`) + - Sendet es über `agent` `attachments: [{ mimeType: "image/png", content: "" }]` + - Das Gateway parst Attachments in `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Der eingebettete Agent leitet eine multimodale Benutzernachricht an das Modell weiter - Prüfung: Die Antwort enthält `cat` + den Code (OCR-Toleranz: kleine Fehler sind erlaubt) -Tipp: Um zu sehen, was Sie auf Ihrer Maschine testen können (und die exakten IDs `provider/model`), führen Sie Folgendes aus: +Tipp: Um zu sehen, was du auf deinem Rechner testen kannst (und die genauen `provider/model`-IDs), führe Folgendes aus: ```bash openclaw models list openclaw models list --json ``` -## Live: CLI-Backend-Smoketest (Claude, Codex, Gemini oder andere lokale CLIs) +## Live: CLI-Backend-Smoke (Claude, Codex, Gemini oder andere lokale CLIs) - Test: `src/gateway/gateway-cli-backend.live.test.ts` -- Ziel: Die Pipeline aus Gateway + Agent mit einem lokalen CLI-Backend validieren, ohne Ihre Standardkonfiguration anzutasten. -- Die standardspezifischen Smokewerte pro Backend liegen bei der `cli-backend.ts`-Definition der zuständigen Erweiterung. +- Ziel: die Gateway-+Agent-Pipeline mit einem lokalen CLI-Backend validieren, ohne deine Standardkonfiguration anzufassen. +- Backend-spezifische Smoke-Standards befinden sich in der Definition `cli-backend.ts` der zuständigen Extension. - Aktivierung: - `pnpm test:live` (oder `OPENCLAW_LIVE_TEST=1`, wenn Vitest direkt aufgerufen wird) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Standardwerte: +- Standards: - Standard-Provider/-Modell: `claude-cli/claude-sonnet-4-6` - - Verhalten von Command/Args/Bild stammt aus den Metadaten des zuständigen CLI-Backend-Plugins. + - Verhalten für Command/Args/Image kommt aus den Metadaten des zuständigen CLI-Backend-Plugins. - Überschreibungen (optional): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, um einen echten Bildanhang zu senden (Pfade werden in den Prompt injiziert). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, um Bilddateipfade als CLI-Argumente statt per Prompt-Injektion zu übergeben. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oder `"list"`), um zu steuern, wie Bildargumente übergeben werden, wenn `IMAGE_ARG` gesetzt ist. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, um eine zweite Runde zu senden und den Resume-Flow zu validieren. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, um die standardmäßig aktive Kontinuitätsprobe Claude Sonnet -> Opus in derselben Sitzung zu deaktivieren (auf `1` setzen, um sie zu erzwingen, wenn das ausgewählte Modell ein Wechselziel unterstützt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, um ein echtes Bild-Attachment zu senden (Pfade werden in den Prompt injiziert). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, um Bilddateipfade als CLI-Args statt per Prompt-Injektion zu übergeben. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (oder `"list"`), um zu steuern, wie Bild-Args übergeben werden, wenn `IMAGE_ARG` gesetzt ist. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, um einen zweiten Turn zu senden und den Resume-Flow zu validieren. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, um die standardmäßige Claude-Sonnet-→-Opus-Gleiches-Sitzung-Kontinuitätsprobe zu deaktivieren (setze auf `1`, um sie zu erzwingen, wenn das ausgewählte Modell ein Switch-Ziel unterstützt). Beispiel: @@ -530,27 +537,27 @@ pnpm test:docker:live-cli-backend:gemini Hinweise: - Der Docker-Runner liegt unter `scripts/test-live-cli-backend-docker.sh`. -- Er führt den Live-CLI-Backend-Smoketest innerhalb des Docker-Images des Repositorys als nicht-root Nutzer `node` aus. -- Er löst Metadaten zum CLI-Smoketest aus der zuständigen Erweiterung auf und installiert dann das passende Linux-CLI-Paket (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`) in ein gecachtes beschreibbares Präfix unter `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (Standard: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` erfordert portable OAuth für Claude Code Subscription entweder über `~/.claude/.credentials.json` mit `claudeAiOauth.subscriptionType` oder `CLAUDE_CODE_OAUTH_TOKEN` aus `claude setup-token`. Es prüft zuerst direktes `claude -p` in Docker und führt dann zwei Gateway-CLI-Backend-Runden aus, ohne Anthropic-API-Key-Umgebungsvariablen beizubehalten. Diese Subscription-Strecke deaktiviert standardmäßig die MCP-/Tool- und Bild-Probes von Claude, weil Claude die Nutzung durch Drittanbieter-Apps derzeit über Zusatznutzungs-Abrechnung statt über normale Subscription-Planlimits routet. -- Der Live-CLI-Backend-Smoketest übt jetzt denselben End-to-End-Ablauf für Claude, Codex und Gemini aus: Textrunde, Bildklassifizierungsrunde, dann MCP-Tool-Call `cron`, verifiziert über die Gateway-CLI. -- Der Standard-Smoketest für Claude passt außerdem die Sitzung von Sonnet auf Opus an und prüft, dass sich die fortgesetzte Sitzung weiterhin an eine frühere Notiz erinnert. +- Er führt den Live-CLI-Backend-Smoke im Repo-Docker-Image als Nicht-Root-Benutzer `node` aus. +- Er löst CLI-Smoke-Metadaten aus der zuständigen Extension auf und installiert dann das passende Linux-CLI-Paket (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`) in ein zwischengespeichertes beschreibbares Präfix unter `OPENCLAW_DOCKER_CLI_TOOLS_DIR` auf (Standard: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` erfordert portable Claude-Code-Subscription-OAuth entweder über `~/.claude/.credentials.json` mit `claudeAiOauth.subscriptionType` oder `CLAUDE_CODE_OAUTH_TOKEN` aus `claude setup-token`. Es beweist zuerst direktes `claude -p` in Docker und führt dann zwei Gateway-CLI-Backend-Turns aus, ohne Anthropic-API-Key-Umgebungsvariablen beizubehalten. Diese Subscription-Lane deaktiviert standardmäßig die Claude-MCP-/Tool- und Image-Sonden, weil Claude die Nutzung durch Drittanbieter-Apps derzeit über Zusatznutzungs-Abrechnung statt über normale Subscription-Planlimits abrechnet. +- Der Live-CLI-Backend-Smoke testet jetzt denselben End-to-End-Flow für Claude, Codex und Gemini: Text-Turn, Bildklassifizierungs-Turn, dann MCP-Tool-Call `cron`, verifiziert über die Gateway-CLI. +- Claudes Standard-Smoke patcht außerdem die Sitzung von Sonnet auf Opus und verifiziert, dass sich die fortgesetzte Sitzung weiterhin an eine frühere Notiz erinnert. -## Live: ACP-Bind-Smoketest (`/acp spawn ... --bind here`) +## Live: ACP-Bind-Smoke (`/acp spawn ... --bind here`) - Test: `src/gateway/gateway-acp-bind.live.test.ts` -- Ziel: Den echten ACP-Konversations-Bind-Flow mit einem Live-ACP-Agenten validieren: +- Ziel: den echten ACP-Conversation-Bind-Flow mit einem Live-ACP-Agenten validieren: - `/acp spawn --bind here` senden - - eine synthetische Konversation eines Nachrichtenkanals an Ort und Stelle binden - - eine normale Nachfassnachricht in derselben Konversation senden - - verifizieren, dass die Nachfassnachricht im Transkript der gebundenen ACP-Sitzung landet + - eine synthetische Message-Channel-Konversation direkt vor Ort binden + - ein normales Follow-up in derselben Konversation senden + - verifizieren, dass das Follow-up im gebundenen ACP-Sitzungstranskript landet - Aktivierung: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Standardwerte: +- Standards: - ACP-Agenten in Docker: `claude,codex,gemini` - ACP-Agent für direktes `pnpm test:live ...`: `claude` - - Synthetischer Kanal: Slack-DM-artiger Konversationskontext + - Synthetischer Channel: Slack-DM-ähnlicher Konversationskontext - ACP-Backend: `acpx` - Überschreibungen: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -559,8 +566,8 @@ Hinweise: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Hinweise: - - Diese Strecke verwendet die Gateway-Oberfläche `chat.send` mit nur für Admins bestimmten synthetischen Feldern der Ursprungsroute, damit Tests Kontext eines Nachrichtenkanals anhängen können, ohne vorzugeben, extern zuzustellen. - - Wenn `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nicht gesetzt ist, verwendet der Test die eingebaute Agent-Registry des eingebetteten Plugins `acpx` für den ausgewählten ACP-Harness-Agenten. + - Diese Lane verwendet die Gateway-Oberfläche `chat.send` mit nur für Admins bestimmten synthetischen Feldern für die Ursprungsroute, damit Tests Message-Channel-Kontext anhängen können, ohne vorzugeben, extern zuzustellen. + - Wenn `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` nicht gesetzt ist, verwendet der Test die integrierte Agent-Registry des eingebetteten `acpx`-Plugins für den ausgewählten ACP-Harness-Agenten. Beispiel: @@ -584,33 +591,33 @@ pnpm test:docker:live-acp-bind:codex pnpm test:docker:live-acp-bind:gemini ``` -Hinweise zu Docker: +Docker-Hinweise: - Der Docker-Runner liegt unter `scripts/test-live-acp-bind-docker.sh`. -- Standardmäßig führt er den ACP-Bind-Smoketest gegen alle unterstützten Live-CLI-Agenten nacheinander aus: `claude`, `codex`, dann `gemini`. -- Verwenden Sie `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oder `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, um die Matrix einzugrenzen. -- Er lädt `~/.profile`, stellt das passende CLI-Auth-Material in den Container bereit, installiert `acpx` in ein beschreibbares npm-Präfix und installiert dann die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`), falls sie fehlt. -- Innerhalb von Docker setzt der Runner `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, sodass acpx Provider-Umgebungsvariablen aus dem geladenen Profil für die untergeordnete Harness-CLI verfügbar hält. +- Standardmäßig führt er den ACP-Bind-Smoke nacheinander gegen alle unterstützten Live-CLI-Agenten aus: `claude`, `codex`, dann `gemini`. +- Verwende `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` oder `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, um die Matrix einzugrenzen. +- Er sourced `~/.profile`, überführt das passende CLI-Auth-Material in den Container, installiert `acpx` in ein beschreibbares npm-Präfix und installiert dann die angeforderte Live-CLI (`@anthropic-ai/claude-code`, `@openai/codex` oder `@google/gemini-cli`), falls sie fehlt. +- Innerhalb von Docker setzt der Runner `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, damit acpx die Provider-Umgebungsvariablen aus dem gesourcten Profil für die untergeordnete Harness-CLI verfügbar hält. -## Live: Codex-App-Server-Harness-Smoketest +## Live: Codex-App-Server-Harness-Smoke -- Ziel: Das plugin-eigene Codex-Harness über die normale Gateway- +- Ziel: den plugin-eigenen Codex-Harness über die normale Gateway- Methode `agent` validieren: - - das gebündelte Plugin `codex` laden + - das gebündelte `codex`-Plugin laden - `OPENCLAW_AGENT_RUNTIME=codex` auswählen - - eine erste Gateway-Agent-Runde an `codex/gpt-5.4` senden - - eine zweite Runde an dieselbe OpenClaw-Sitzung senden und verifizieren, dass der App-Server- + - einen ersten Gateway-Agent-Turn an `codex/gpt-5.4` senden + - einen zweiten Turn an dieselbe OpenClaw-Sitzung senden und verifizieren, dass der App-Server- Thread fortgesetzt werden kann - - `/codex status` und `/codex models` über denselben Gateway-Befehlspfad - ausführen + - `/codex status` und `/codex models` über denselben Gateway-Befehls- + pfad ausführen - Test: `src/gateway/gateway-codex-harness.live.test.ts` - Aktivierung: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Standardmodell: `codex/gpt-5.4` -- Optionale Bild-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Optionale Image-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Optionale MCP-/Tool-Probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Der Smoketest setzt `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, damit ein defektes Codex- - Harness nicht stillschweigend bestehen kann, indem es auf PI zurückfällt. -- Auth: `OPENAI_API_KEY` aus Shell/Profil sowie optional kopierte +- Der Smoke setzt `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, damit ein defekter Codex- + Harness nicht unbemerkt durch stilles Fallback auf Pi bestehen kann. +- Auth: `OPENAI_API_KEY` aus der Shell/dem Profil sowie optional kopierte `~/.codex/auth.json` und `~/.codex/config.toml` Lokales Rezept: @@ -631,18 +638,18 @@ source ~/.profile pnpm test:docker:live-codex-harness ``` -Hinweise zu Docker: +Docker-Hinweise: - Der Docker-Runner liegt unter `scripts/test-live-codex-harness-docker.sh`. -- Er lädt das eingebundene `~/.profile`, übergibt `OPENAI_API_KEY`, kopiert Codex-CLI- - Auth-Dateien, wenn vorhanden, installiert `@openai/codex` in ein beschreibbares eingebundenes npm- - Präfix, stellt den Quellbaum bereit und führt dann nur den Live-Test des Codex-Harness aus. -- Docker aktiviert die Bild- und MCP-/Tool-Probes standardmäßig. Setzen Sie +- Er sourced das eingehängte `~/.profile`, übergibt `OPENAI_API_KEY`, kopiert Codex-CLI- + Auth-Dateien, wenn vorhanden, installiert `@openai/codex` in ein beschreibbares eingehängtes npm- + Präfix, staged den Quellbaum und führt dann nur den Codex-Harness-Live-Test aus. +- Docker aktiviert standardmäßig die Image- und MCP-/Tool-Sonden. Setze `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` oder - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, wenn Sie einen engeren Debug-Lauf benötigen. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, wenn du einen engeren Debug-Lauf brauchst. - Docker exportiert außerdem `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, passend zur Live- - Testkonfiguration, damit ein Fallback auf `openai-codex/*` oder PI keine Regression - des Codex-Harness verbergen kann. + Testkonfiguration, damit `openai-codex/*`- oder Pi-Fallback keinen Codex-Harness- + Regressionsfehler verbergen kann. ### Empfohlene Live-Rezepte @@ -651,34 +658,34 @@ Enge, explizite Allowlists sind am schnellsten und am wenigsten fehleranfällig: - Einzelnes Modell, direkt (ohne Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Einzelnes Modell, Gateway-Smoketest: +- Einzelnes Modell, Gateway-Smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool-Calling über mehrere Provider hinweg: +- Tool Calling über mehrere Provider hinweg: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Google-Fokus (Gemini-API-Schlüssel + Antigravity): - - Gemini (API-Schlüssel): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Google-Fokus (Gemini-API-Key + Antigravity): + - Gemini (API-Key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Hinweise: -- `google/...` verwendet die Gemini-API (API-Schlüssel). -- `google-antigravity/...` verwendet die Antigravity-OAuth-Bridge (Cloud-Code-Assist-ähnlicher Agent-Endpunkt). -- `google-gemini-cli/...` verwendet die lokale Gemini CLI auf Ihrem Rechner (separate Auth + Eigenheiten bei Tooling). +- `google/...` verwendet die Gemini-API (API-Key). +- `google-antigravity/...` verwendet die Antigravity-OAuth-Bridge (Agent-Endpoint im Stil von Cloud Code Assist). +- `google-gemini-cli/...` verwendet die lokale Gemini-CLI auf deinem Rechner (separate Authentifizierung + Tooling-Eigenheiten). - Gemini-API vs. Gemini-CLI: - - API: OpenClaw ruft die gehostete Gemini-API von Google über HTTP auf (API-Schlüssel / Profil-Auth); das ist in der Regel gemeint, wenn Nutzer von „Gemini“ sprechen. - - CLI: OpenClaw führt lokal eine Binärdatei `gemini` aus; sie hat ihre eigene Authentifizierung und kann sich anders verhalten (Streaming/Tool-Unterstützung/Versionsabweichung). + - API: OpenClaw ruft Googles gehostete Gemini-API über HTTP auf (API-Key / Profil-Auth); das ist in der Regel das, was Nutzer mit „Gemini“ meinen. + - CLI: OpenClaw ruft eine lokale `gemini`-Binärdatei per Shell auf; sie hat ihre eigene Authentifizierung und kann sich anders verhalten (Streaming/Tool-Unterstützung/Versionsabweichungen). ## Live: Modellmatrix (was wir abdecken) -Es gibt keine feste „CI-Modellliste“ (Live ist Opt-in), aber dies sind die **empfohlenen** Modelle, die regelmäßig auf einem Entwicklerrechner mit Schlüsseln abgedeckt werden sollten. +Es gibt keine feste „CI-Modellliste“ (Live ist Opt-in), aber dies sind die **empfohlenen** Modelle, die auf einem Entwicklungsrechner mit Schlüsseln regelmäßig abgedeckt werden sollten. -### Modernes Smoketest-Set (Tool-Calling + Bild) +### Modernes Smoke-Set (Tool Calling + Bild) -Dies ist der Lauf mit den „gängigen Modellen“, von dem wir erwarten, dass er weiter funktioniert: +Dies ist der „Common Models“-Lauf, den wir funktionsfähig halten wollen: -- OpenAI (nicht Codex): `openai/gpt-5.4` (optional: `openai/gpt-5.4-mini`) +- OpenAI (nicht-Codex): `openai/gpt-5.4` (optional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (oder `anthropic/claude-sonnet-4-6`) - Google (Gemini-API): `google/gemini-3.1-pro-preview` und `google/gemini-3-flash-preview` (ältere Gemini-2.x-Modelle vermeiden) @@ -686,12 +693,12 @@ Dies ist der Lauf mit den „gängigen Modellen“, von dem wir erwarten, dass e - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Gateway-Smoketest mit Tools + Bild ausführen: +Gateway-Smoke mit Tools + Bild ausführen: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: Tool-Calling (Read + optional Exec) +### Baseline: Tool Calling (Read + optionales Exec) -Wählen Sie mindestens eines pro Provider-Familie: +Wähle mindestens eines pro Provider-Familie: - OpenAI: `openai/gpt-5.4` (oder `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (oder `anthropic/claude-sonnet-4-6`) @@ -702,72 +709,72 @@ Wählen Sie mindestens eines pro Provider-Familie: Optionale zusätzliche Abdeckung (nice to have): - xAI: `xai/grok-4` (oder die neueste verfügbare Version) -- Mistral: `mistral/`… (wählen Sie ein „tools“-fähiges Modell, das Sie aktiviert haben) -- Cerebras: `cerebras/`… (wenn Sie Zugriff haben) -- LM Studio: `lmstudio/`… (lokal; Tool-Calling hängt vom API-Modus ab) +- Mistral: `mistral/`… (wähle ein „tools“-fähiges Modell, das du aktiviert hast) +- Cerebras: `cerebras/`… (falls du Zugriff hast) +- LM Studio: `lmstudio/`… (lokal; Tool Calling hängt vom API-Modus ab) -### Vision: Bild senden (Anhang → multimodale Nachricht) +### Vision: Bild senden (Attachment → multimodale Nachricht) -Schließen Sie mindestens ein bildfähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` ein (Claude/Gemini/OpenAI-Varianten mit Vision-Unterstützung usw.), um die Bild-Probe auszuführen. +Nimm mindestens ein bildfähiges Modell in `OPENCLAW_LIVE_GATEWAY_MODELS` auf (Claude-/Gemini-/OpenAI-Varianten mit Bildunterstützung usw.), um die Image-Probe auszuführen. ### Aggregatoren / alternative Gateways -Wenn Sie aktivierte Schlüssel haben, unterstützen wir auch Tests über: +Wenn du aktivierte Schlüssel hast, unterstützen wir auch Tests über: -- OpenRouter: `openrouter/...` (Hunderte von Modellen; verwenden Sie `openclaw models scan`, um Kandidaten mit Tool- + Bild-Unterstützung zu finden) +- OpenRouter: `openrouter/...` (Hunderte Modelle; verwende `openclaw models scan`, um Kandidaten mit Tool-+Bild-Unterstützung zu finden) - OpenCode: `opencode/...` für Zen und `opencode-go/...` für Go (Auth über `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Weitere Provider, die Sie in die Live-Matrix aufnehmen können (wenn Sie Anmeldedaten/Konfiguration haben): +Weitere Provider, die du in die Live-Matrix aufnehmen kannst (wenn du Anmeldedaten/Konfiguration hast): - Integriert: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Über `models.providers` (benutzerdefinierte Endpunkte): `minimax` (Cloud/API) sowie jeder OpenAI-/Anthropic-kompatible Proxy (LM Studio, vLLM, LiteLLM usw.) +- Über `models.providers` (benutzerdefinierte Endpoints): `minimax` (Cloud/API) sowie jeder OpenAI-/Anthropic-kompatible Proxy (LM Studio, vLLM, LiteLLM usw.) -Tipp: Versuchen Sie nicht, in der Dokumentation „alle Modelle“ hart zu kodieren. Die maßgebliche Liste ist das, was `discoverModels(...)` auf Ihrem Rechner zurückgibt + welche Schlüssel verfügbar sind. +Tipp: Versuche nicht, „alle Modelle“ in der Doku hart zu codieren. Die maßgebliche Liste ist das, was `discoverModels(...)` auf deinem Rechner zurückgibt, plus die verfügbaren Schlüssel. ## Anmeldedaten (niemals committen) Live-Tests erkennen Anmeldedaten auf dieselbe Weise wie die CLI. Praktische Auswirkungen: - Wenn die CLI funktioniert, sollten Live-Tests dieselben Schlüssel finden. -- Wenn ein Live-Test „keine Anmeldedaten“ meldet, debuggen Sie genauso, wie Sie `openclaw models list` / Modellauswahl debuggen würden. +- Wenn ein Live-Test „keine Anmeldedaten“ meldet, debugge auf dieselbe Weise wie bei `openclaw models list` / Modellauswahl. -- Auth-Profile pro Agent: `~/.openclaw/agents//agent/auth-profiles.json` (das ist es, was in den Live-Tests mit „Profilschlüssel“ gemeint ist) +- Pro-Agent-Auth-Profile: `~/.openclaw/agents//agent/auth-profiles.json` (das ist es, was „Profil-Schlüssel“ in den Live-Tests bedeutet) - Konfiguration: `~/.openclaw/openclaw.json` (oder `OPENCLAW_CONFIG_PATH`) -- Altes Zustandsverzeichnis: `~/.openclaw/credentials/` (wird, wenn vorhanden, in das bereitgestellte Live-Test-Home kopiert, aber nicht in den Hauptspeicher für Profilschlüssel) -- Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, `auth-profiles.json`-Dateien pro Agent, das alte `credentials/` und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; bereitgestellte Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfadüberschreibungen `agents.*.workspace` / `agentDir` werden entfernt, damit Probes von Ihrem echten Host-Workspace fernbleiben. +- Legacy-Statusverzeichnis: `~/.openclaw/credentials/` (wird in das gestagte Live-Home kopiert, wenn vorhanden, ist aber nicht der Hauptspeicher für Profil-Schlüssel) +- Lokale Live-Läufe kopieren standardmäßig die aktive Konfiguration, pro-Agent-`auth-profiles.json`-Dateien, Legacy-`credentials/` und unterstützte externe CLI-Auth-Verzeichnisse in ein temporäres Test-Home; gestagte Live-Homes überspringen `workspace/` und `sandboxes/`, und Pfad-Overrides für `agents.*.workspace` / `agentDir` werden entfernt, damit Sonden nicht in deinem echten Host-Workspace laufen. -Wenn Sie auf Umgebungsschlüssel setzen möchten (z. B. in Ihrem `~/.profile` exportiert), führen Sie lokale Tests nach `source ~/.profile` aus oder verwenden Sie die Docker-Runner unten (diese können `~/.profile` in den Container einbinden). +Wenn du dich auf Env-Schlüssel verlassen willst (z. B. exportiert in deinem `~/.profile`), führe lokale Tests nach `source ~/.profile` aus oder verwende die Docker-Runner unten (sie können `~/.profile` in den Container mounten). -## Deepgram live (Audio-Transkription) +## Deepgram live (Audiotranskription) - Test: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Aktivierung: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus Coding-Plan live +## BytePlus-Coding-Plan live - Test: `src/agents/byteplus.live.test.ts` - Aktivierung: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` -- Optionale Modellüberschreibung: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Optionale Modell-Überschreibung: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## ComfyUI-Workflow-Medien live - Test: `extensions/comfy/comfy.live.test.ts` - Aktivierung: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Umfang: - - Führt die gebündelten Comfy-Pfade für Bild, Video und `music_generate` aus + - Testet die gebündelten Comfy-Pfade für Bild, Video und `music_generate` - Überspringt jede Fähigkeit, sofern `models.providers.comfy.` nicht konfiguriert ist - Nützlich nach Änderungen an Comfy-Workflow-Übermittlung, Polling, Downloads oder Plugin-Registrierung -## Bildgenerierung live +## Live-Bildgenerierung - Test: `src/image-generation/runtime.live.test.ts` - Befehl: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Umfang: - - Zählt jedes registrierte Provider-Plugin für Bildgenerierung auf - - Lädt fehlende Provider-Umgebungsvariablen vor dem Prüfen aus Ihrer Login-Shell (`~/.profile`) - - Verwendet standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken - - Überspringt Provider ohne nutzbare Auth/Profile/Modelle + - Zählt jedes registrierte Plugin für Bildgenerierungs-Provider auf + - Lädt fehlende Provider-Umgebungsvariablen vor der Prüfung aus deiner Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Überspringt Provider ohne verwendbare Auth/Profile/Modelle - Führt die Standardvarianten der Bildgenerierung über die gemeinsame Laufzeitfähigkeit aus: - `google:flash-generate` - `google:pro-generate` @@ -781,74 +788,74 @@ Wenn Sie auf Umgebungsschlüssel setzen möchten (z. B. in Ihrem `~/.profile` ex - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Optionales Auth-Verhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth nur aus dem Profilspeicher zu erzwingen und rein umgebungsbasierte Überschreibungen zu ignorieren + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren -## Musikgenerierung live +## Live-Musikgenerierung - Test: `extensions/music-generation-providers.live.test.ts` - Aktivierung: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Umfang: - - Führt den gemeinsam genutzten Pfad für gebündelte Provider der Musikgenerierung aus + - Testet den gemeinsamen gebündelten Provider-Pfad für Musikgenerierung - Deckt derzeit Google und MiniMax ab - - Lädt vor dem Prüfen Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`) - - Verwendet standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken - - Überspringt Provider ohne nutzbare Auth/Profile/Modelle + - Lädt Provider-Umgebungsvariablen vor der Prüfung aus deiner Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Überspringt Provider ohne verwendbare Auth/Profile/Modelle - Führt beide deklarierten Laufzeitmodi aus, wenn verfügbar: - - `generate` mit Eingabe nur als Prompt + - `generate` mit ausschließlich promptbasierter Eingabe - `edit`, wenn der Provider `capabilities.edit.enabled` deklariert - - Aktuelle Abdeckung der gemeinsamen Strecke: + - Aktuelle gemeinsame Lane-Abdeckung: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: separate Comfy-Live-Datei, nicht Teil dieses gemeinsamen Sweeps + - `comfy`: separate Comfy-Live-Datei, nicht dieser gemeinsame Sweep - Optionale Eingrenzung: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Optionales Auth-Verhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth nur aus dem Profilspeicher zu erzwingen und rein umgebungsbasierte Überschreibungen zu ignorieren + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren -## Videogenerierung live +## Live-Videogenerierung - Test: `extensions/video-generation-providers.live.test.ts` - Aktivierung: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Umfang: - - Führt den gemeinsam genutzten Pfad für gebündelte Provider der Videogenerierung aus - - Verwendet standardmäßig den release-sicheren Smoketest-Pfad: Nicht-FAL-Provider, eine Text-zu-Video-Anfrage pro Provider, ein einsekündiger Lobster-Prompt und ein providerbezogenes Operationslimit aus `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (standardmäßig `180000`) - - Überspringt FAL standardmäßig, weil providerseitige Queue-Latenz die Release-Zeit dominieren kann; übergeben Sie `--video-providers fal` oder `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, um es explizit auszuführen - - Lädt vor dem Prüfen Provider-Umgebungsvariablen aus Ihrer Login-Shell (`~/.profile`) - - Verwendet standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken - - Überspringt Provider ohne nutzbare Auth/Profile/Modelle + - Testet den gemeinsamen gebündelten Provider-Pfad für Videogenerierung + - Verwendet standardmäßig den release-sicheren Smoke-Pfad: keine FAL-Provider, eine Text-zu-Video-Anfrage pro Provider, ein einsekündiger Hummer-Prompt und eine providerbezogene Operationsgrenze aus `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (standardmäßig `180000`) + - Überspringt FAL standardmäßig, weil providerseitige Queue-Latenz die Release-Zeit dominieren kann; übergib `--video-providers fal` oder `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, um es explizit auszuführen + - Lädt Provider-Umgebungsvariablen vor der Prüfung aus deiner Login-Shell (`~/.profile`) + - Verwendet standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen, damit veraltete Testschlüssel in `auth-profiles.json` echte Shell-Anmeldedaten nicht verdecken + - Überspringt Provider ohne verwendbare Auth/Profile/Modelle - Führt standardmäßig nur `generate` aus - - Setzen Sie `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, um zusätzlich deklarierte Transformationsmodi auszuführen, wenn verfügbar: - - `imageToVideo`, wenn der Provider `capabilities.imageToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell in diesem gemeinsamen Sweep lokale Bildeingaben auf Buffer-Basis akzeptiert - - `videoToVideo`, wenn der Provider `capabilities.videoToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell in diesem gemeinsamen Sweep lokale Videoeingaben auf Buffer-Basis akzeptiert - - Derzeit deklarierte, aber im gemeinsamen Sweep übersprungene `imageToVideo`-Provider: - - `vydra`, weil das gebündelte `veo3` nur Text unterstützt und das gebündelte `kling` eine Remote-Bild-URL erfordert - - Providerspezifische Vydra-Abdeckung: + - Setze `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, um zusätzlich deklarierte Transform-Modi auszuführen, wenn verfügbar: + - `imageToVideo`, wenn der Provider `capabilities.imageToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep buffer-gestützte lokale Bildeingaben akzeptiert + - `videoToVideo`, wenn der Provider `capabilities.videoToVideo.enabled` deklariert und der ausgewählte Provider/das ausgewählte Modell im gemeinsamen Sweep buffer-gestützte lokale Videoeingaben akzeptiert + - Aktuell deklarierte, aber im gemeinsamen Sweep übersprungene `imageToVideo`-Provider: + - `vydra`, weil gebündeltes `veo3` nur Text unterstützt und gebündeltes `kling` eine Remote-Bild-URL erfordert + - Provider-spezifische Vydra-Abdeckung: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - diese Datei führt `veo3` Text-zu-Video plus eine `kling`-Strecke aus, die standardmäßig ein Fixture mit Remote-Bild-URL verwendet + - diese Datei führt `veo3` Text-zu-Video sowie standardmäßig eine `kling`-Lane aus, die ein Remote-Bild-URL-Fixture verwendet - Aktuelle `videoToVideo`-Live-Abdeckung: - nur `runway`, wenn das ausgewählte Modell `runway/gen4_aleph` ist - - Derzeit deklarierte, aber im gemeinsamen Sweep übersprungene `videoToVideo`-Provider: - - `alibaba`, `qwen`, `xai`, weil diese Pfade derzeit Remote-Referenz-URLs mit `http(s)` / MP4 erfordern - - `google`, weil die aktuelle gemeinsame Gemini/Veo-Strecke lokale Eingaben auf Buffer-Basis verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird - - `openai`, weil der aktuellen gemeinsamen Strecke Garantien für organisationsspezifischen Zugriff auf Video-Inpaint/Remix fehlen + - Aktuell deklarierte, aber im gemeinsamen Sweep übersprungene `videoToVideo`-Provider: + - `alibaba`, `qwen`, `xai`, weil diese Pfade derzeit Remote-Referenz-URLs für `http(s)` / MP4 erfordern + - `google`, weil die aktuelle gemeinsame Gemini-/Veo-Lane lokale buffer-gestützte Eingaben verwendet und dieser Pfad im gemeinsamen Sweep nicht akzeptiert wird + - `openai`, weil der aktuellen gemeinsamen Lane Garantien für org-spezifischen Zugriff auf Video-Inpaint/Remix fehlen - Optionale Eingrenzung: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, um jeden Provider in den Standard-Sweep einzuschließen, einschließlich FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, um das Operationslimit pro Provider für einen aggressiven Smoketest zu reduzieren + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, um jeden Provider in den Standard-Sweep aufzunehmen, einschließlich FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, um die Operationsgrenze pro Provider für einen aggressiven Smoke-Lauf zu reduzieren - Optionales Auth-Verhalten: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth nur aus dem Profilspeicher zu erzwingen und rein umgebungsbasierte Überschreibungen zu ignorieren + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um Auth aus dem Profilspeicher zu erzwingen und reine Env-Overrides zu ignorieren -## Media-Live-Harness +## Medien-Live-Harness - Befehl: `pnpm test:live:media` - Zweck: - - Führt die gemeinsam genutzten Live-Suiten für Bild, Musik und Video über einen nativen Repository-Einstiegspunkt aus + - Führt die gemeinsamen Live-Suiten für Bild, Musik und Video über einen repo-nativen Entry-Point aus - Lädt fehlende Provider-Umgebungsvariablen automatisch aus `~/.profile` - - Grenzt jede Suite standardmäßig automatisch auf Provider ein, die aktuell nutzbare Auth haben + - Grenzt jede Suite standardmäßig automatisch auf Provider ein, die derzeit verwendbare Auth haben - Verwendet `scripts/test-live.mjs` wieder, sodass Heartbeat- und Quiet-Mode-Verhalten konsistent bleiben - Beispiele: - `pnpm test:live:media` @@ -856,155 +863,155 @@ Wenn Sie auf Umgebungsschlüssel setzen möchten (z. B. in Ihrem `~/.profile` ex - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker-Runner (optionale „funktioniert unter Linux“-Prüfungen) +## Docker-Runner (optionale Prüfungen „funktioniert unter Linux“) -Diese Docker-Runner teilen sich in zwei Gruppen: +Diese Docker-Runner teilen sich in zwei Gruppen auf: -- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur ihre jeweils passende Live-Datei mit Profilschlüsseln innerhalb des Docker-Images des Repositorys aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`), wobei Ihr lokales Konfigurationsverzeichnis und Ihr Workspace eingebunden werden (und `~/.profile` geladen wird, wenn es eingebunden ist). Die passenden lokalen Entry-Points sind `test:live:models-profiles` und `test:live:gateway-profiles`. -- Docker-Live-Runner verwenden standardmäßig ein kleineres Smoke-Limit, damit ein vollständiger Docker-Sweep praktikabel bleibt: +- Live-Modell-Runner: `test:docker:live-models` und `test:docker:live-gateway` führen nur ihre jeweils passende Live-Datei für Profil-Schlüssel im Repo-Docker-Image aus (`src/agents/models.profiles.live.test.ts` und `src/gateway/gateway-models.profiles.live.test.ts`) und mounten dabei dein lokales Konfigurationsverzeichnis und deinen Workspace (und sourcen `~/.profile`, falls gemountet). Die passenden lokalen Entry-Points sind `test:live:models-profiles` und `test:live:gateway-profiles`. +- Docker-Live-Runner verwenden standardmäßig eine kleinere Smoke-Obergrenze, damit ein vollständiger Docker-Sweep praktikabel bleibt: `test:docker:live-models` verwendet standardmäßig `OPENCLAW_LIVE_MAX_MODELS=12`, und `test:docker:live-gateway` verwendet standardmäßig `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` und - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Überschreiben Sie diese Umgebungsvariablen, wenn Sie - ausdrücklich den größeren vollständigen Scan möchten. -- `test:docker:all` baut das Live-Docker-Image einmal über `test:docker:live-build` und verwendet es dann für die beiden Docker-Live-Strecken erneut. -- Container-Smoketest-Runner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` und `test:docker:plugins` starten einen oder mehrere echte Container und verifizieren höherstufige Integrationspfade. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Überschreibe diese Env-Variablen, wenn du + ausdrücklich den größeren vollständigen Scan möchtest. +- `test:docker:all` baut das Live-Docker-Image einmal über `test:docker:live-build` und verwendet es dann für die beiden Docker-Live-Lanes wieder. +- Container-Smoke-Runner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` und `test:docker:plugins` booten einen oder mehrere echte Container und verifizieren Integrationspfade auf höherer Ebene. -Die Docker-Runner für Live-Modelle binden außerdem nur die benötigten CLI-Auth-Homes ein (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit OAuth externer CLI-Tools Tokens aktualisieren kann, ohne den Auth-Speicher des Hosts zu verändern: +Die Docker-Runner für Live-Modelle binden außerdem nur die benötigten CLI-Auth-Homes ein (oder alle unterstützten, wenn der Lauf nicht eingegrenzt ist) und kopieren sie dann vor dem Lauf in das Container-Home, damit externe CLI-OAuth Token aktualisieren kann, ohne den Host-Auth-Speicher zu verändern: - Direkte Modelle: `pnpm test:docker:live-models` (Skript: `scripts/test-live-models-docker.sh`) -- ACP-Bind-Smoketest: `pnpm test:docker:live-acp-bind` (Skript: `scripts/test-live-acp-bind-docker.sh`) -- CLI-Backend-Smoketest: `pnpm test:docker:live-cli-backend` (Skript: `scripts/test-live-cli-backend-docker.sh`) -- Codex-App-Server-Harness-Smoketest: `pnpm test:docker:live-codex-harness` (Skript: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + dev-Agent: `pnpm test:docker:live-gateway` (Skript: `scripts/test-live-gateway-models-docker.sh`) -- Open-WebUI-Live-Smoketest: `pnpm test:docker:openwebui` (Skript: `scripts/e2e/openwebui-docker.sh`) +- ACP-Bind-Smoke: `pnpm test:docker:live-acp-bind` (Skript: `scripts/test-live-acp-bind-docker.sh`) +- CLI-Backend-Smoke: `pnpm test:docker:live-cli-backend` (Skript: `scripts/test-live-cli-backend-docker.sh`) +- Codex-App-Server-Harness-Smoke: `pnpm test:docker:live-codex-harness` (Skript: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + Dev-Agent: `pnpm test:docker:live-gateway` (Skript: `scripts/test-live-gateway-models-docker.sh`) +- Open-WebUI-Live-Smoke: `pnpm test:docker:openwebui` (Skript: `scripts/e2e/openwebui-docker.sh`) - Onboarding-Assistent (TTY, vollständiges Scaffolding): `pnpm test:docker:onboard` (Skript: `scripts/e2e/onboard-docker.sh`) - Gateway-Networking (zwei Container, WS-Auth + Health): `pnpm test:docker:gateway-network` (Skript: `scripts/e2e/gateway-network-docker.sh`) -- MCP-Kanal-Bridge (vorinitialisiertes Gateway + stdio-Bridge + roher Claude-Benachrichtigungsframe-Smoketest): `pnpm test:docker:mcp-channels` (Skript: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (Installations-Smoketest + `/plugin`-Alias + Neustartsemantik des Claude-Bundles): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) +- MCP-Channel-Bridge (vorgefülltes Gateway + stdio-Bridge + roher Claude-Benachrichtigungsframe-Smoke): `pnpm test:docker:mcp-channels` (Skript: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (Installations-Smoke + `/plugin`-Alias + Neustartsemantik des Claude-Bundles): `pnpm test:docker:plugins` (Skript: `scripts/e2e/plugins-docker.sh`) -Die Docker-Runner für Live-Modelle binden außerdem den aktuellen Checkout schreibgeschützt ein und -stellen ihn in ein temporäres Arbeitsverzeichnis innerhalb des Containers bereit. So bleibt das Laufzeit- -Image schlank, während Vitest trotzdem gegen Ihren exakten lokalen Quellcode/Ihre Konfiguration läuft. -Der Bereitstellungsschritt überspringt große lokale Caches und Build-Ausgaben von Apps wie -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` sowie app-lokale `.build`- oder -Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht minutenlang maschinenspezifische -Artefakte kopieren. -Sie setzen außerdem `OPENCLAW_SKIP_CHANNELS=1`, damit Gateway-Live-Probes im Container keine -echten Kanal-Worker für Telegram/Discord usw. starten. -`test:docker:live-models` führt weiterhin `pnpm test:live` aus, leiten Sie daher bei Bedarf auch -`OPENCLAW_LIVE_GATEWAY_*` durch, wenn Sie Gateway-Live-Abdeckung in dieser Docker-Strecke -eingrenzen oder ausschließen möchten. -`test:docker:openwebui` ist ein höherstufiger Kompatibilitäts-Smoketest: Er startet einen -OpenClaw-Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpunkten, -startet einen fixierten Open-WebUI-Container gegen dieses Gateway, meldet sich über -Open WebUI an, prüft, dass `/api/models` `openclaw/default` bereitstellt, und sendet dann eine -echte Chat-Anfrage über den Proxy `/api/chat/completions` von Open WebUI. -Der erste Lauf kann spürbar langsamer sein, weil Docker möglicherweise erst das -Open-WebUI-Image ziehen muss und Open WebUI möglicherweise erst sein eigenes Kaltstart-Setup abschließen muss. -Diese Strecke erwartet einen nutzbaren Live-Modellschlüssel, und `OPENCLAW_PROFILE_FILE` -(`~/.profile` standardmäßig) ist die primäre Methode, ihn in Docker-Läufen bereitzustellen. -Erfolgreiche Läufe geben eine kleine JSON-Nutzlast wie `{ "ok": true, "model": -"openclaw/default", ... }` aus. +Die Docker-Runner für Live-Modelle mounten den aktuellen Checkout außerdem read-only und +stagen ihn in ein temporäres Workdir innerhalb des Containers. Dadurch bleibt das Runtime- +Image schlank, während Vitest trotzdem gegen deinen exakt lokalen Quellcode/deine Konfiguration ausgeführt wird. +Der Staging-Schritt überspringt große rein lokale Caches und App-Build-Ausgaben wie +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` und app-lokale `.build`- oder +Gradle-Ausgabeverzeichnisse, damit Docker-Live-Läufe nicht minutenlang +maschinenspezifische Artefakte kopieren. +Sie setzen außerdem `OPENCLAW_SKIP_CHANNELS=1`, sodass Gateway-Live-Sonden keine +echten Telegram-/Discord-/usw.-Channel-Worker im Container starten. +`test:docker:live-models` führt weiterhin `pnpm test:live` aus, also gib +auch `OPENCLAW_LIVE_GATEWAY_*` weiter, wenn du Gateway- +Live-Abdeckung in dieser Docker-Lane eingrenzen oder ausschließen musst. +`test:docker:openwebui` ist ein Compatibility-Smoke auf höherer Ebene: Es startet einen +OpenClaw-Gateway-Container mit aktivierten OpenAI-kompatiblen HTTP-Endpoints, +startet einen festgelegten Open-WebUI-Container gegen dieses Gateway, meldet sich über +Open WebUI an, verifiziert, dass `/api/models` `openclaw/default` bereitstellt, und sendet dann eine +echte Chat-Anfrage über Open WebUIs Proxy `/api/chat/completions`. +Der erste Lauf kann merklich langsamer sein, weil Docker möglicherweise zuerst das +Open-WebUI-Image ziehen muss und Open WebUI möglicherweise seine eigene Cold-Start-Einrichtung abschließen muss. +Diese Lane erwartet einen verwendbaren Live-Modell-Schlüssel, und `OPENCLAW_PROFILE_FILE` +(standardmäßig `~/.profile`) ist der primäre Weg, ihn in Docker-Läufen bereitzustellen. +Erfolgreiche Läufe geben ein kleines JSON-Payload aus wie `{ "ok": true, "model": +"openclaw/default", ... }`. `test:docker:mcp-channels` ist absichtlich deterministisch und benötigt kein -echtes Telegram-, Discord- oder iMessage-Konto. Es startet einen vorinitialisierten Gateway- -Container, startet einen zweiten Container, der `openclaw mcp serve` ausführt, und -verifiziert dann geroutete Konversationsentdeckung, das Lesen von Transkripten, Attachment-Metadaten, -das Verhalten der Live-Ereignis-Warteschlange, Routing für ausgehendes Senden sowie Claude-artige Kanal- + -Berechtigungsbenachrichtigungen über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung -untersucht die rohen stdio-MCP-Frames direkt, sodass der Smoketest validiert, was die -Bridge tatsächlich ausgibt, und nicht nur das, was ein bestimmtes Client-SDK zufällig sichtbar macht. +echtes Telegram-, Discord- oder iMessage-Konto. Es bootet ein vorgefülltes Gateway- +Container, startet einen zweiten Container, der `openclaw mcp serve` startet, und +verifiziert dann geroutete Konversationsentdeckung, Transkript-Lesevorgänge, Attachment-Metadaten, +Verhalten der Live-Event-Queue, Routing ausgehender Sendungen und Benachrichtigungen im Claude-Stil zu Channel + +Berechtigungen über die echte stdio-MCP-Bridge. Die Benachrichtigungsprüfung +inspiziert die rohen stdio-MCP-Frames direkt, sodass der Smoke validiert, was die +Bridge tatsächlich ausgibt, nicht nur das, was ein bestimmtes Client-SDK zufällig bereitstellt. -Manueller ACP-Smoketest für Plain-Language-Threads (nicht CI): +Manueller ACP-Plain-Language-Thread-Smoke (nicht CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Behalten Sie dieses Skript für Regressions-/Debugging-Workflows. Es könnte für die Validierung des ACP-Thread-Routings erneut benötigt werden, daher nicht löschen. +- Dieses Skript für Regressions-/Debug-Workflows beibehalten. Es könnte erneut für die ACP-Thread-Routing-Validierung benötigt werden, also nicht löschen. -Nützliche Umgebungsvariablen: +Nützliche Env-Variablen: -- `OPENCLAW_CONFIG_DIR=...` (Standard: `~/.openclaw`) eingebunden nach `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (Standard: `~/.openclaw/workspace`) eingebunden nach `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`) eingebunden nach `/home/node/.profile` und vor dem Ausführen der Tests geladen -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, um nur Umgebungsvariablen zu verifizieren, die aus `OPENCLAW_PROFILE_FILE` geladen wurden, unter Verwendung temporärer Konfigurations-/Workspace-Verzeichnisse und ohne externe CLI-Auth-Mounts -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`) eingebunden nach `/home/node/.npm-global` für gecachte CLI-Installationen innerhalb von Docker -- Externe CLI-Auth-Verzeichnisse/-Dateien unter `$HOME` werden schreibgeschützt unter `/host-auth...` eingebunden und dann vor dem Start der Tests nach `/home/node/...` kopiert +- `OPENCLAW_CONFIG_DIR=...` (Standard: `~/.openclaw`), gemountet nach `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (Standard: `~/.openclaw/workspace`), gemountet nach `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (Standard: `~/.profile`), gemountet nach `/home/node/.profile` und vor dem Ausführen der Tests gesourced +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, um nur Env-Variablen zu verifizieren, die aus `OPENCLAW_PROFILE_FILE` gesourced wurden, mit temporären Konfigurations-/Workspace-Verzeichnissen und ohne externe CLI-Auth-Mounts +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (Standard: `~/.cache/openclaw/docker-cli-tools`), gemountet nach `/home/node/.npm-global` für zwischengespeicherte CLI-Installationen innerhalb von Docker +- Externe CLI-Auth-Verzeichnisse/-Dateien unter `$HOME` werden read-only unter `/host-auth...` gemountet und dann vor Testbeginn nach `/home/node/...` kopiert - Standardverzeichnisse: `.minimax` - Standarddateien: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Eingeschränkte Provider-Läufe binden nur die benötigten Verzeichnisse/Dateien ein, die aus `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` abgeleitet werden - - Manuell überschreiben mit `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oder einer Kommaliste wie `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Eingegrenzte Provider-Läufe mounten nur die benötigten Verzeichnisse/Dateien, die aus `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` abgeleitet werden + - Manuell überschreiben mit `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` oder einer durch Kommata getrennten Liste wie `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, um den Lauf einzugrenzen - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, um Provider im Container zu filtern -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, um ein vorhandenes Image `openclaw:local-live` für erneute Läufe zu verwenden, die keinen Neubau benötigen -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Anmeldedaten aus dem Profilspeicher kommen (nicht aus der Umgebung) -- `OPENCLAW_OPENWEBUI_MODEL=...`, um das vom Gateway für den Open-WebUI-Smoketest bereitgestellte Modell auszuwählen -- `OPENCLAW_OPENWEBUI_PROMPT=...`, um den für den Open-WebUI-Smoketest verwendeten Prompt mit Nonce-Prüfung zu überschreiben -- `OPENWEBUI_IMAGE=...`, um das fixierte Image-Tag von Open WebUI zu überschreiben +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, um ein bestehendes Image `openclaw:local-live` für Wiederholungsläufe ohne Neubau wiederzuverwenden +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, um sicherzustellen, dass Anmeldedaten aus dem Profilspeicher kommen (nicht aus Env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, um das vom Gateway für den Open-WebUI-Smoke bereitgestellte Modell auszuwählen +- `OPENCLAW_OPENWEBUI_PROMPT=...`, um den für den Open-WebUI-Smoke verwendeten Nonce-Check-Prompt zu überschreiben +- `OPENWEBUI_IMAGE=...`, um das festgelegte Open-WebUI-Image-Tag zu überschreiben ## Doku-Sanity -Führen Sie nach Dokumentationsänderungen Doku-Prüfungen aus: `pnpm check:docs`. -Führen Sie die vollständige Mintlify-Anchor-Validierung aus, wenn Sie zusätzlich Prüfungen für In-Page-Überschriften benötigen: `pnpm docs:check-links:anchors`. +Führe Doku-Prüfungen nach Doku-Bearbeitungen aus: `pnpm check:docs`. +Führe die vollständige Mintlify-Anchor-Validierung aus, wenn du auch In-Page-Heading-Prüfungen brauchst: `pnpm docs:check-links:anchors`. ## Offline-Regression (CI-sicher) Dies sind Regressionen der „echten Pipeline“ ohne echte Provider: -- Gateway-Tool-Calling (Mock OpenAI, echtes Gateway + Agent-Loop): `src/gateway/gateway.test.ts` (Fall: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Gateway-Wizard (WS `wizard.start`/`wizard.next`, schreibt Konfiguration + Auth erzwungen): `src/gateway/gateway.test.ts` (Fall: "runs wizard over ws and writes auth token config") +- Gateway-Tool Calling (Mock OpenAI, echtes Gateway + Agent-Loop): `src/gateway/gateway.test.ts` (Fall: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway-Assistent (WS `wizard.start`/`wizard.next`, schreibt Konfiguration + erzwungene Auth): `src/gateway/gateway.test.ts` (Fall: "runs wizard over ws and writes auth token config") -## Evaluierungen der Agent-Zuverlässigkeit (Skills) +## Agent-Zuverlässigkeits-Evals (Skills) -Wir haben bereits einige CI-sichere Tests, die sich wie „Evaluierungen der Agent-Zuverlässigkeit“ verhalten: +Wir haben bereits einige CI-sichere Tests, die sich wie „Agent-Zuverlässigkeits-Evals“ verhalten: -- Mock-Tool-Calling durch die echte Gateway- + Agent-Loop (`src/gateway/gateway.test.ts`). -- End-to-End-Wizard-Flows, die Sitzungsverdrahtung und Konfigurationseffekte validieren (`src/gateway/gateway.test.ts`). +- Mock-Tool-Calling durch den echten Gateway- + Agent-Loop (`src/gateway/gateway.test.ts`). +- End-to-End-Assistenten-Flows, die Sitzungsverdrahtung und Konfigurationseffekte validieren (`src/gateway/gateway.test.ts`). Was für Skills noch fehlt (siehe [Skills](/de/tools/skills)): -- **Entscheidungsfindung:** Wenn Skills im Prompt aufgelistet sind, wählt der Agent den richtigen Skill (oder vermeidet irrelevante)? -- **Compliance:** Liest der Agent vor der Nutzung `SKILL.md` und befolgt erforderliche Schritte/Argumente? -- **Workflow-Verträge:** Mehrzügige Szenarien, die Tool-Reihenfolge, Übernahme des Sitzungsverlaufs und Sandbox-Grenzen prüfen. +- **Entscheidungsfindung:** Wenn Skills im Prompt aufgeführt sind, wählt der Agent den richtigen Skill aus (oder vermeidet irrelevante)? +- **Compliance:** Liest der Agent `SKILL.md` vor der Verwendung und befolgt erforderliche Schritte/Args? +- **Workflow-Verträge:** Multi-Turn-Szenarien, die Tool-Reihenfolge, Sitzungsverlauf-Übernahme und Sandbox-Grenzen prüfen. -Zukünftige Evaluierungen sollten zuerst deterministisch bleiben: +Zukünftige Evals sollten zuerst deterministisch bleiben: -- Ein Szenario-Runner mit Mock-Providern, um Tool-Aufrufe + Reihenfolge, das Lesen von Skill-Dateien und Sitzungsverdrahtung zu prüfen. -- Eine kleine Suite auf Skills fokussierter Szenarien (verwenden vs. vermeiden, Gating, Prompt Injection). -- Optionale Live-Evaluierungen (Opt-in, über Umgebungsvariablen gesteuert) erst, nachdem die CI-sichere Suite vorhanden ist. +- Ein Szenario-Runner mit Mock-Providern, um Tool-Calls + Reihenfolge, Skill-Datei-Lesevorgänge und Sitzungsverdrahtung zu prüfen. +- Eine kleine Suite skill-fokussierter Szenarien (verwenden vs. vermeiden, Gating, Prompt Injection). +- Optionale Live-Evals (Opt-in, env-gesteuert) erst, nachdem die CI-sichere Suite vorhanden ist. -## Vertragstests (Plugin- und Kanalform) +## Vertragstests (Plugin- und Channel-Form) -Vertragstests prüfen, dass jedes registrierte Plugin und jeder Kanal seinem +Vertragstests verifizieren, dass jedes registrierte Plugin und jeder Channel seinem Schnittstellenvertrag entspricht. Sie iterieren über alle erkannten Plugins und führen eine Suite von -Prüfungen zu Form und Verhalten aus. Die Standard-Unit-Strecke `pnpm test` -überspringt diese gemeinsam genutzten Seam- und Smoke-Dateien bewusst; führen Sie die Vertragstests explizit aus, -wenn Sie gemeinsame Oberflächen von Kanal oder Provider anfassen. +Form- und Verhaltensprüfungen aus. Die standardmäßige Unit-Lane `pnpm test` +überspringt diese gemeinsamen Seam- und Smoke-Dateien absichtlich; führe die Vertragsbefehle explizit aus, +wenn du gemeinsame Channel- oder Provider-Oberflächen anfasst. ### Befehle - Alle Verträge: `pnpm test:contracts` -- Nur Kanalverträge: `pnpm test:contracts:channels` +- Nur Channel-Verträge: `pnpm test:contracts:channels` - Nur Provider-Verträge: `pnpm test:contracts:plugins` -### Kanalverträge +### Channel-Verträge Zu finden unter `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Grundlegende Plugin-Form (ID, Name, Fähigkeiten) - **setup** - Vertrag des Setup-Assistenten -- **session-binding** - Verhalten der Sitzungsbindung -- **outbound-payload** - Struktur der Nachrichten-Nutzlast +- **session-binding** - Verhalten bei Sitzungsbindung +- **outbound-payload** - Struktur der Nachrichtennutzlast - **inbound** - Verarbeitung eingehender Nachrichten -- **actions** - Handler für Kanalaktionen +- **actions** - Channel-Aktions-Handler - **threading** - Behandlung von Thread-IDs -- **directory** - API für Verzeichnis/Roster +- **directory** - Verzeichnis-/Roster-API - **group-policy** - Durchsetzung von Gruppenrichtlinien ### Provider-Statusverträge Zu finden unter `src/plugins/contracts/*.contract.test.ts`. -- **status** - Kanalstatus-Probes +- **status** - Channel-Status-Sonden - **registry** - Form der Plugin-Registry ### Provider-Verträge @@ -1015,28 +1022,28 @@ Zu finden unter `src/plugins/contracts/*.contract.test.ts`: - **auth-choice** - Auth-Auswahl/Selektion - **catalog** - API des Modellkatalogs - **discovery** - Plugin-Erkennung -- **loader** - Laden von Plugins +- **loader** - Plugin-Laden - **runtime** - Provider-Laufzeit - **shape** - Plugin-Form/Schnittstelle - **wizard** - Setup-Assistent ### Wann ausführen -- Nach Änderungen an Exports oder Unterpfaden des Plugin SDK -- Nach dem Hinzufügen oder Ändern eines Kanal- oder Provider-Plugins +- Nach Änderungen an plugin-sdk-Exports oder Subpaths +- Nach dem Hinzufügen oder Ändern eines Channel- oder Provider-Plugins - Nach Refactorings an Plugin-Registrierung oder -Erkennung Vertragstests laufen in CI und erfordern keine echten API-Schlüssel. -## Regressionen hinzufügen (Leitlinien) +## Regressionen hinzufügen (Leitfaden) -Wenn Sie ein in Live entdecktes Provider-/Modellproblem beheben: +Wenn du ein Provider-/Modell-Problem behebst, das in Live entdeckt wurde: -- Fügen Sie nach Möglichkeit eine CI-sichere Regression hinzu (Mock-/Stub-Provider oder erfassen Sie die exakte Transformation der Request-Form) -- Wenn es von Natur aus nur live testbar ist (Rate-Limits, Auth-Richtlinien), halten Sie den Live-Test eng begrenzt und per Umgebungsvariablen als Opt-in -- Bevorzugen Sie die kleinste Ebene, die den Fehler erkennt: - - Fehler bei Konvertierung/Wiedergabe von Provider-Requests → Test direkter Modelle - - Fehler in Gateway-Sitzung/Verlauf/Tool-Pipeline → Gateway-Live-Smoketest oder CI-sicherer Gateway-Mocktest -- Guardrail für SecretRef-Traversierung: - - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet pro SecretRef-Klasse ein Beispielziel aus den Registry-Metadaten (`listSecretTargetRegistryEntries()`) ab und prüft dann, dass Exec-IDs von Traversierungssegmenten abgelehnt werden. - - Wenn Sie in `src/secrets/target-registry-data.ts` eine neue SecretRef-Zielfamilie mit `includeInPlan` hinzufügen, aktualisieren Sie `classifyTargetClass` in diesem Test. Der Test schlägt absichtlich bei nicht klassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden. +- Füge nach Möglichkeit eine CI-sichere Regression hinzu (Mock-/Stub-Provider oder die exakte Transformation der Request-Form erfassen) +- Wenn es inhärent nur live testbar ist (Rate Limits, Auth-Richtlinien), halte den Live-Test eng begrenzt und opt-in über Env-Variablen +- Bevorzuge die kleinste Ebene, die den Fehler erfasst: + - Fehler bei Provider-Request-Konvertierung/-Replay → direkter Modelltest + - Fehler in Gateway-Sitzungs-/Verlaufs-/Tool-Pipeline → Gateway-Live-Smoke oder CI-sicherer Gateway-Mock-Test +- Schutzplanke für SecretRef-Traversal: + - `src/secrets/exec-secret-ref-id-parity.test.ts` leitet aus Registry-Metadaten (`listSecretTargetRegistryEntries()`) ein gesampeltes Ziel pro SecretRef-Klasse ab und prüft dann, dass Exec-IDs von Traversal-Segmenten abgewiesen werden. + - Wenn du in `src/secrets/target-registry-data.ts` eine neue SecretRef-Zielfamilie mit `includeInPlan` hinzufügst, aktualisiere `classifyTargetClass` in diesem Test. Der Test schlägt absichtlich bei nicht klassifizierten Ziel-IDs fehl, damit neue Klassen nicht stillschweigend übersprungen werden können. diff --git a/docs/de/plugins/architecture.md b/docs/de/plugins/architecture.md index 28421167d..477bac316 100644 --- a/docs/de/plugins/architecture.md +++ b/docs/de/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - Erstellen oder Debuggen nativer OpenClaw-Plugins - - Verstehen des Plugin-Fähigkeitsmodells oder der Ownership-Grenzen + - Verständnis des Plugin-Fähigkeitsmodells oder der Zuständigkeitsgrenzen - Arbeiten an der Plugin-Ladepipeline oder der Registry - - Implementieren von Provider-Laufzeit-Hooks oder Channel-Plugins + - Implementierung 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, Zuständigkeit, Verträge, Ladepipeline und Laufzeithelfer' title: Plugin-Interna x-i18n: - generated_at: "2026-04-21T06:27:23Z" + generated_at: "2026-04-21T13:36:01Z" model: gpt-5.4 provider: openai - source_hash: 05b612f75189ba32f8c92e5a261241abdf9ad8d4a685c1d8da0cf9605d7158b7 + source_hash: 4b1fb42e659d4419033b317e88563a59b3ddbfad0523f32225c868c8e828fd16 source_path: plugins/architecture.md workflow: 15 --- @@ -19,8 +19,8 @@ x-i18n: # Plugin-Interna - Dies ist die **ausführliche Architekturreferenz**. Für praktische Anleitungen siehe: - - [Install and use plugins](/de/tools/plugin) — Benutzeranleitung + Dies ist die **umfassende Architekturreferenz**. Praktische Anleitungen finden Sie hier: + - [Install and use plugins](/de/tools/plugin) — Benutzerleitfaden - [Getting Started](/de/plugins/building-plugins) — erstes Plugin-Tutorial - [Channel Plugins](/de/plugins/sdk-channel-plugins) — einen Messaging-Kanal erstellen - [Provider Plugins](/de/plugins/sdk-provider-plugins) — einen Modell-Provider erstellen @@ -34,46 +34,47 @@ Diese Seite behandelt die interne Architektur des Plugin-Systems von OpenClaw. Fähigkeiten sind das öffentliche Modell für **native Plugins** innerhalb von OpenClaw. Jedes native OpenClaw-Plugin registriert sich für einen oder mehrere Fähigkeitstypen: -| Fähigkeit | Registrierungsmethode | Beispiel-Plugins | -| ---------------------- | ----------------------------------------------- | ------------------------------------ | -| Textinferenz | `api.registerProvider(...)` | `openai`, `anthropic` | -| CLI-Inferenz-Backend | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Sprache | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Echtzeit-Transkription | `api.registerRealtimeTranscriptionProvider(...)`| `openai` | -| Echtzeit-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` | +| Bilderzeugung | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Musikerzeugung | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Videoerzeugung | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Web-Abruf | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Websuche | `api.registerWebSearchProvider(...)` | `google` | +| Kanal / Messaging | `api.registerChannel(...)` | `msteams`, `matrix` | Ein Plugin, das null Fähigkeiten registriert, aber Hooks, Tools oder -Dienste bereitstellt, ist ein **Legacy-Hook-only**-Plugin. Dieses Muster wird weiterhin vollständig unterstützt. +Dienste bereitstellt, ist ein **Legacy-hook-only**-Plugin. Dieses Muster wird weiterhin vollständig unterstützt. ### Haltung zur externen Kompatibilität Das Fähigkeitsmodell ist im Core eingeführt und wird heute von gebündelten/nativen Plugins -verwendet, aber externe Plugin-Kompatibilität braucht weiterhin strengere Maßstäbe als „es ist +verwendet, aber die Kompatibilität externer Plugins braucht weiterhin eine strengere Messlatte als „es ist exportiert, also ist es eingefroren“. Aktuelle Leitlinien: -- **bestehende externe Plugins:** hookbasierte Integrationen funktionsfähig halten; behandle - dies als Kompatibilitäts-Basislinie +- **bestehende externe Plugins:** Hook-basierte Integrationen funktionsfähig halten; dies + als Kompatibilitätsbasis behandeln - **neue gebündelte/native Plugins:** explizite Fähigkeitsregistrierung gegenüber - anbieterspezifischen Reach-ins oder neuen Hook-only-Designs bevorzugen -- **externe Plugins, die Fähigkeitsregistrierung übernehmen:** erlaubt, aber behandle die - fähigkeitsspezifischen Hilfsoberflächen als in Entwicklung, sofern die Dokumentation einen - Vertrag nicht ausdrücklich als stabil markiert + anbieterspezifischen Sonderzugriffen oder neuen Hook-only-Designs bevorzugen +- **externe Plugins, die Fähigkeitsregistrierung übernehmen:** erlaubt, aber die + fähigkeitsspezifischen Hilfsoberflächen als in Entwicklung behandeln, sofern die Dokumentation einen + Vertrag nicht ausdrücklich als stabil kennzeichnet Praktische Regel: - APIs zur Fähigkeitsregistrierung sind die beabsichtigte Richtung -- Legacy-Hooks bleiben während des Übergangs der sicherste Weg ohne Brüche für externe Plugins -- exportierte Helper-Subpaths sind nicht alle gleich; bevorzuge den schmalen dokumentierten - Vertrag, nicht beiläufige Helper-Exporte +- Legacy-Hooks bleiben während + des Übergangs der sicherste No-Breakage-Pfad für externe Plugins +- exportierte Hilfs-Subpfade sind nicht alle gleich; den schmalen dokumentierten + Vertrag bevorzugen, nicht beiläufig exportierte Hilfen ### Plugin-Formen @@ -83,111 +84,108 @@ Registrierungsverhaltens in eine Form (nicht nur anhand statischer Metadaten): - **plain-capability** -- registriert genau einen Fähigkeitstyp (zum Beispiel ein reines Provider-Plugin wie `mistral`) - **hybrid-capability** -- registriert mehrere Fähigkeitstypen (zum Beispiel - besitzt `openai` Textinferenz, Sprache, Medienverständnis und Bild- - generierung) + besitzt `openai` Textinferenz, Sprache, Medienverständnis und Bilderzeugung) - **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 -Verwende `openclaw plugins inspect `, um die Form und die Fähigkeitsaufschlüsselung eines Plugins zu sehen. Siehe [CLI reference](/cli/plugins#inspect) für Details. +Verwenden Sie `openclaw plugins inspect `, um die Form und die Fähigkeitsaufschlüsselung +eines Plugins anzuzeigen. Siehe [CLI reference](/cli/plugins#inspect) für Details. ### Legacy-Hooks Der Hook `before_agent_start` bleibt als Kompatibilitätspfad für -Hook-only-Plugins unterstützt. Legacy-Plugins aus der Praxis hängen weiterhin davon ab. +Hook-only-Plugins unterstützt. Reale Legacy-Plugins hängen weiterhin davon ab. Richtung: - funktionsfähig halten - als Legacy dokumentieren -- `before_model_resolve` für Arbeiten an Modell-/Provider-Overrides bevorzugen -- `before_prompt_build` für Arbeiten an Prompt-Mutationen bevorzugen -- erst entfernen, wenn die tatsächliche Nutzung sinkt und Fixture-Abdeckung sichere Migration belegt +- `before_model_resolve` für Arbeit an Modell-/Provider-Überschreibungen bevorzugen +- `before_prompt_build` für Arbeit an Prompt-Mutationen bevorzugen +- erst entfernen, wenn die reale Nutzung sinkt und Fixture-Abdeckung eine sichere Migration belegt ### Kompatibilitätssignale -Wenn du `openclaw doctor` oder `openclaw plugins inspect ` ausführst, siehst du möglicherweise +Wenn Sie `openclaw doctor` oder `openclaw plugins inspect ` ausführen, sehen Sie möglicherweise eine dieser Kennzeichnungen: | 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`, was veraltet ist | +| **legacy warning** | Plugin verwendet `before_agent_start`, das veraltet ist | | **hard error** | Konfiguration ist ungültig oder Plugin konnte nicht geladen werden | -Weder `hook-only` noch `before_agent_start` werden dein Plugin heute kaputt machen -- -`hook-only` ist ein Hinweis, und `before_agent_start` erzeugt nur eine Warnung. Diese +Weder `hook-only` noch `before_agent_start` führen heute zum Ausfall Ihres Plugins -- +`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`. ## Architekturüberblick -Das Plugin-System von OpenClaw hat vier Schichten: +Das Plugin-System von OpenClaw hat vier Ebenen: -1. **Manifest + Discovery** - OpenClaw findet Kandidaten-Plugins aus konfigurierten Pfaden, Workspace-Roots, - globalen Extension-Roots und gebündelten Extensions. Discovery liest zuerst native - `openclaw.plugin.json`-Manifeste plus unterstützte Bundle-Manifeste. +1. **Manifest + Erkennung** + OpenClaw findet potenzielle 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 Core entscheidet, ob ein entdecktes Plugin aktiviert, deaktiviert, blockiert oder + Der Core entscheidet, ob ein erkanntes Plugin aktiviert, deaktiviert, blockiert oder für einen exklusiven Slot wie Speicher ausgewählt ist. 3. **Laufzeitladen** - Native OpenClaw-Plugins werden In-Process über jiti geladen und registrieren - Fähigkeiten in einer zentralen Registry. Kompatible Bundles werden zu - Registry-Einträgen normalisiert, ohne Laufzeitcode zu importieren. -4. **Oberflächennutzung** + Native OpenClaw-Plugins werden prozessintern über jiti geladen und registrieren + Fähigkeiten in einer zentralen Registry. Kompatible Bundles werden in + Registry-Einträge normalisiert, ohne Laufzeitcode zu importieren. +4. **Oberflächenkonsum** Der Rest von OpenClaw liest die Registry, um Tools, Kanäle, Provider- - Einrichtung, Hooks, HTTP-Routen, CLI-Befehle und Dienste bereitzustellen. + Setup, Hooks, HTTP-Routen, CLI-Befehle und Dienste bereitzustellen. -Speziell für die Plugin-CLI ist die Root-Command-Discovery in zwei Phasen aufgeteilt: +Speziell für die Plugin-CLI ist die Erkennung von Root-Befehlen in zwei Phasen aufgeteilt: -- Parse-Time-Metadaten kommen aus `registerCli(..., { descriptors: [...] })` +- Metadaten zur Parse-Zeit stammen aus `registerCli(..., { descriptors: [...] })` - das echte Plugin-CLI-Modul kann lazy bleiben und sich beim ersten Aufruf registrieren -Dadurch bleibt plugin-eigener CLI-Code im Plugin, während OpenClaw trotzdem -Root-Befehlsnamen vor dem Parsing reservieren kann. +So bleibt der plugin-eigene CLI-Code im Plugin, während OpenClaw dennoch +Root-Befehlsnamen vor dem Parsen reservieren kann. -Die wichtige Designgrenze: +Die wichtige Entwurfsgrenze: -- Discovery + Konfigurationsvalidierung sollen aus **Manifest-/Schema-Metadaten** - funktionieren, ohne Plugin-Code auszuführen -- natives Laufzeitverhalten kommt aus dem `register(api)`-Pfad des Plugin-Moduls +- Erkennung + Konfigurationsvalidierung sollten anhand von **Manifest-/Schema-Metadaten** + funktionieren, ohne Plugincode auszuführen +- natives Laufzeitverhalten stammt aus dem Pfad `register(api)` des Plugin-Moduls -Diese Aufteilung ermöglicht es OpenClaw, Konfiguration 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 es OpenClaw, Konfiguration zu validieren, fehlende/deaktivierte Plugins zu erklären und +UI-/Schema-Hinweise zu erstellen, bevor die vollständige Laufzeit aktiv ist. -### Channel-Plugins und das gemeinsame Message-Tool +### Kanal-Plugins und das gemeinsame Nachrichtentool -Channel-Plugins müssen für normale Chat-Aktionen kein separates Send/Edit/React-Tool registrieren. -OpenClaw hält ein gemeinsames `message`-Tool im Core, und Channel-Plugins besitzen die -kanalspezifische Discovery und Ausführung dahinter. +Kanal-Plugins müssen für normale Chat-Aktionen kein separates Send/Edit/React-Tool registrieren. OpenClaw behält ein gemeinsames `message`-Tool im Core, und +Kanal-Plugins besitzen die kanalspezifische Erkennung und Ausführung dahinter. Die aktuelle Grenze ist: -- der Core besitzt den gemeinsamen `message`-Tool-Host, Prompt-Verkabelung, Session-/Thread- - Bookkeeping und Ausführungs-Dispatch -- Channel-Plugins besitzen scoped Action-Discovery, Fähigkeits-Discovery und alle - kanalspezifischen Schema-Fragmente -- Channel-Plugins besitzen die provider-spezifische Session-Konversationsgrammatik, zum Beispiel - wie Konversations-IDs Thread-IDs kodieren oder von übergeordneten Konversationen erben -- Channel-Plugins führen die endgültige Aktion über ihren Action-Adapter aus +- der Core besitzt den gemeinsamen `message`-Tool-Host, Prompt-Verdrahtung, Sitzungs-/Thread- + Verwaltung und die Ausführungsweiterleitung +- Kanal-Plugins besitzen die bereichsspezifische Aktionserkennung, Fähigkeitserkennung und alle + kanalspezifischen Schemafragmente +- Kanal-Plugins besitzen providerspezifische Grammatik für Sitzungs-Konversationen, z. B. + wie Konversations-IDs Thread-IDs codieren oder von übergeordneten Konversationen erben +- Kanal-Plugins führen die endgültige Aktion über ihren Action-Adapter aus -Für Channel-Plugins ist die SDK-Oberfläche -`ChannelMessageActionAdapter.describeMessageTool(...)`. Dieser vereinheitlichte Discovery-Aufruf -ermöglicht einem Plugin, sichtbare Aktionen, Fähigkeiten und Schema-Beiträge -gemeinsam zurückzugeben, damit diese Teile nicht auseinanderdriften. +Für Kanal-Plugins ist die SDK-Oberfläche +`ChannelMessageActionAdapter.describeMessageTool(...)`. Dieser einheitliche Erkennungsaufruf ermöglicht es einem Plugin, seine sichtbaren Aktionen, Fähigkeiten und Schemabeiträge gemeinsam zurückzugeben, damit diese Teile nicht auseinanderdriften. -Wenn ein kanalspezifischer Message-Tool-Parameter eine Medienquelle wie einen -lokalen Pfad oder eine Remote-Medien-URL trägt, sollte das Plugin außerdem +Wenn ein kanalspezifischer Nachrichtentool-Parameter eine Medienquelle wie einen +lokalen Pfad oder eine Remote-Medien-URL enthält, sollte das Plugin auch `mediaSourceParams` aus `describeMessageTool(...)` zurückgeben. Der Core verwendet diese explizite Liste, um Sandbox-Pfadnormalisierung und Hinweise für ausgehenden Medienzugriff anzuwenden, -ohne plugin-eigene Parameternamen hart zu kodieren. -Bevorzuge dort action-scoped Maps, nicht eine kanalweite flache Liste, damit ein -profilbezogener Medienparameter nicht bei nicht zusammenhängenden Aktionen wie +ohne plugin-eigene Parameternamen fest zu codieren. +Bevorzugen Sie dort aktionsbezogene Maps statt einer flachen kanalweiten Liste, damit ein +nur profilbezogener Medienparameter nicht bei nicht verwandten Aktionen wie `send` normalisiert wird. -Der Core übergibt Laufzeit-Scope in diesen Discovery-Schritt. Wichtige Felder sind: +Der Core übergibt Laufzeit-Scope in diesen Erkennungsschritt. Wichtige Felder sind: - `accountId` - `currentChannelId` @@ -198,91 +196,91 @@ Der Core übergibt Laufzeit-Scope in diesen Discovery-Schritt. Wichtige Felder s - `agentId` - vertrauenswürdige eingehende `requesterSenderId` -Das ist wichtig für kontextsensitive Plugins. Ein Kanal kann Message-Aktionen -abhängig vom aktiven Konto, aktuellem Raum/Thread/Nachricht oder vertrauenswürdiger -Requester-Identität ausblenden oder einblenden, ohne kanalspezifische Verzweigungen im -gemeinsamen Core-`message`-Tool hart zu kodieren. +Das ist für kontextsensitive Plugins wichtig. Ein Kanal kann +Nachrichtenaktionen basierend auf dem aktiven Konto, dem aktuellen Raum/Thread/der aktuellen Nachricht oder der +vertrauenswürdigen Anfordereridentität ausblenden oder anzeigen, ohne kanalspezifische Verzweigungen +im gemeinsamen `message`-Tool des Core fest zu codieren. Deshalb bleiben Änderungen am Embedded-Runner-Routing weiterhin Plugin-Arbeit: Der Runner ist -dafür verantwortlich, die aktuelle Chat-/Session-Identität in die Plugin- -Discovery-Grenze weiterzuleiten, damit das gemeinsame `message`-Tool die richtige kanal- -eigene Oberfläche für den aktuellen Zug freilegt. +dafür verantwortlich, die aktuelle Chat-/Sitzungsidentität in die +pluginseitige Erkennungsgrenze weiterzugeben, damit das gemeinsame `message`-Tool die richtige, kanalbesitzte +Oberfläche für den aktuellen Turn bereitstellt. -Für kanal-eigene Ausführungs-Helper sollten gebündelte Plugins die Ausführungs- -Laufzeit in ihren eigenen Extension-Modulen behalten. Der Core besitzt nicht länger die -Message-Action-Laufzeiten für Discord, Slack, Telegram oder WhatsApp unter `src/agents/tools`. -Wir veröffentlichen keine separaten `plugin-sdk/*-action-runtime`-Subpaths, und gebündelte -Plugins sollten ihren eigenen lokalen Laufzeitcode direkt aus ihren extension-eigenen -Modulen importieren. +Für kanalbesitzte Ausführungshilfen sollten gebündelte Plugins die Ausführungs- +Laufzeit in ihren eigenen Erweiterungsmodulen behalten. Der Core besitzt nicht mehr die Discord-, +Slack-, Telegram- oder WhatsApp-Nachrichtenaktions-Laufzeiten unter `src/agents/tools`. +Wir veröffentlichen keine separaten `plugin-sdk/*-action-runtime`-Subpfade, und gebündelte +Plugins sollten ihren eigenen lokalen Laufzeitcode direkt aus ihren +erweiterungsbesitzten Modulen importieren. -Dieselbe Grenze gilt generell für provider-benannte SDK-Seams: Der Core sollte +Dieselbe Grenze gilt allgemein für providerbenannte SDK-Seams: Der Core sollte keine kanalspezifischen Convenience-Barrels für Slack, Discord, Signal, -WhatsApp oder ähnliche Extensions importieren. Wenn der Core ein Verhalten braucht, -entweder das eigene `api.ts`- / `runtime-api.ts`-Barrel des gebündelten Plugins verwenden oder -den Bedarf in eine schmale generische Fähigkeit im gemeinsamen SDK überführen. +WhatsApp oder ähnliche Erweiterungen importieren. Wenn der Core ein Verhalten benötigt, entweder das +eigene `api.ts`-/`runtime-api.ts`-Barrel des gebündelten Plugins nutzen 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 allgemeinen Umfragemodell passen - `actions.handleAction("poll")` ist der bevorzugte Pfad für kanalspezifische - Umfrage-Semantik oder zusätzliche Umfrageparameter + Umfragesemantik oder zusätzliche Umfrageparameter -Der Core verzögert jetzt das gemeinsame Poll-Parsing, bis der Plugin-Poll-Dispatch -die Aktion ablehnt, damit plugin-eigene Poll-Handler kanalspezifische Poll- -Felder akzeptieren können, ohne zuerst vom generischen Poll-Parser blockiert zu werden. +Der Core verschiebt das gemeinsame Umfrage-Parsing jetzt, bis die pluginseitige Umfrage- +Weiterleitung die Aktion ablehnt, sodass plugin-eigene Umfrage-Handler kanalspezifische +Umfragefelder akzeptieren können, ohne zuvor vom generischen Umfrage-Parser blockiert zu werden. Siehe [Load pipeline](#load-pipeline) für die vollständige Startsequenz. -## Ownership-Modell für Fähigkeiten +## Modell für Fähigkeitszuständigkeit -OpenClaw behandelt ein natives Plugin als Ownership-Grenze für ein **Unternehmen** oder ein +OpenClaw behandelt ein natives Plugin als Zuständigkeitsgrenze für ein **Unternehmen** oder ein **Feature**, nicht als Sammelsurium unzusammenhängender Integrationen. Das bedeutet: -- ein Unternehmens-Plugin sollte in der Regel alle diesem Unternehmen zugewandten - OpenClaw-Oberflächen besitzen -- ein Feature-Plugin sollte in der Regel die vollständige von ihm eingeführte +- ein Unternehmens-Plugin sollte normalerweise alle OpenClaw-bezogenen + Oberflächen dieses Unternehmens besitzen +- ein Feature-Plugin sollte normalerweise die vollständige von ihm eingeführte Feature-Oberfläche besitzen -- Kanäle sollten gemeinsame Core-Fähigkeiten nutzen, statt Provider-Verhalten ad hoc - neu zu implementieren +- Kanäle sollten gemeinsame Core-Fähigkeiten nutzen, anstatt + Provider-Verhalten ad hoc neu zu implementieren Beispiele: -- das gebündelte `openai`-Plugin besitzt das OpenAI-Modell-Provider-Verhalten sowie OpenAI- - Sprache + Echtzeit-Sprache + Medienverständnis + Bildgenerierungsverhalten +- das gebündelte `openai`-Plugin besitzt das Verhalten des OpenAI-Modell-Providers und das OpenAI-Verhalten für + Sprache + Echtzeit-Stimme + Medienverständnis + Bilderzeugung - das gebündelte `elevenlabs`-Plugin besitzt das ElevenLabs-Sprachverhalten - das gebündelte `microsoft`-Plugin besitzt das Microsoft-Sprachverhalten -- das gebündelte `google`-Plugin besitzt das Google-Modell-Provider-Verhalten plus Google- - Medienverständnis + Bildgenerierung + Websuchverhalten +- das gebündelte `google`-Plugin besitzt das Verhalten des Google-Modell-Providers sowie das Google-Verhalten für + Medienverständnis + Bilderzeugung + Websuche - das gebündelte `firecrawl`-Plugin besitzt das Firecrawl-Web-Abruf-Verhalten - die gebündelten Plugins `minimax`, `mistral`, `moonshot` und `zai` besitzen ihre - Medienverständnis-Backends -- das gebündelte `qwen`-Plugin besitzt das Qwen-Text-Provider-Verhalten plus - Medienverständnis- und Videogenerierungsverhalten -- das Plugin `voice-call` ist ein Feature-Plugin: Es besitzt Call-Transport, Tools, - CLI, Routen und Twilio-Media-Stream-Bridge, nutzt aber gemeinsame Sprache- - sowie Echtzeit-Transkriptions- und Echtzeit-Sprache-Fähigkeiten, statt + Backends für Medienverständnis +- das gebündelte `qwen`-Plugin besitzt das Qwen-Text-Provider-Verhalten sowie + das Verhalten für Medienverständnis und Videoerzeugung +- das `voice-call`-Plugin ist ein Feature-Plugin: Es besitzt Anruftransport, Tools, + CLI, Routen und Twilio-Medienstream-Überbrückung, nutzt aber gemeinsame Fähigkeiten für Sprache + sowie Echtzeit-Transkription und Echtzeit-Stimme, anstatt Anbieter-Plugins direkt zu importieren -Der beabsichtigte Endzustand ist: +Der angestrebte Endzustand ist: -- OpenAI lebt in einem Plugin, auch wenn es Textmodelle, Sprache, Bilder und - zukünftiges Video umfasst -- ein anderer Anbieter kann dasselbe für seine eigene Oberflächenbreite tun -- Kanäle kümmern sich nicht darum, welches Anbieter-Plugin den Provider besitzt; sie nutzen den +- OpenAI lebt in einem einzigen Plugin, auch wenn es Textmodelle, Sprache, Bilder und + künftig Video umfasst +- ein anderer Anbieter kann dasselbe für seinen eigenen Oberflächenbereich tun +- Kanäle interessiert nicht, welches Anbieter-Plugin den Provider besitzt; sie nutzen den gemeinsamen Fähigkeitsvertrag, den der Core bereitstellt -Das ist der zentrale Unterschied: +Das ist der entscheidende Unterschied: -- **Plugin** = Ownership-Grenze +- **Plugin** = Zuständigkeitsgrenze - **Fähigkeit** = Core-Vertrag, den mehrere Plugins implementieren oder nutzen können -Wenn OpenClaw also eine neue Domäne wie Video hinzufügt, lautet die erste Frage nicht -„welcher Provider sollte Video-Handling hart kodieren?“ Die erste Frage lautet „was ist -der Core-Fähigkeitsvertrag für Video?“ Sobald dieser Vertrag existiert, können -Anbieter-Plugins ihn registrieren und Kanal-/Feature-Plugins ihn nutzen. +Wenn OpenClaw also einen neuen Bereich wie Video hinzufügt, lautet die erste Frage nicht +„welcher Provider sollte die Videoverarbeitung fest codieren?“ Die erste Frage lautet „wie sieht +der Core-Vertrag für die Videofähigkeit aus?“ Sobald dieser Vertrag existiert, können Anbieter-Plugins +sich dafür registrieren, und Kanal-/Feature-Plugins können ihn nutzen. Wenn die Fähigkeit noch nicht existiert, ist der richtige Schritt normalerweise: @@ -291,34 +289,34 @@ Wenn die Fähigkeit noch nicht existiert, ist der richtige Schritt normalerweise 3. Kanäle/Features gegen diese Fähigkeit verdrahten 4. Anbieter-Plugins Implementierungen registrieren lassen -Das hält Ownership explizit und vermeidet gleichzeitig Core-Verhalten, das von einem +So bleibt die Zuständigkeit explizit, während Core-Verhalten vermieden wird, das von einem einzigen Anbieter oder einem einmaligen plugin-spezifischen Codepfad abhängt. -### Fähigkeits-Schichtenmodell +### Fähigkeitsschichtung -Verwende dieses mentale Modell, um zu entscheiden, wo Code hingehört: +Verwenden Sie dieses mentale Modell, wenn Sie entscheiden, wohin Code gehört: -- **Core-Fähigkeitsschicht**: gemeinsame Orchestrierung, Richtlinie, Fallback, Konfigurations- - Merge-Regeln, Zustellungssemantik und typisierte Verträge +- **Core-Fähigkeitsschicht**: gemeinsame Orchestrierung, Richtlinien, Fallback, + Regeln zur Konfigurationszusammenführung, Auslieferungssemantik und typisierte Verträge - **Anbieter-Plugin-Schicht**: anbieterspezifische APIs, Authentifizierung, Modellkataloge, Sprache- - Synthese, Bildgenerierung, zukünftige Video-Backends, Usage-Endpunkte -- **Kanal-/Feature-Plugin-Schicht**: Integration von Slack/Discord/voice-call/usw., + synthese, Bilderzeugung, künftige Video-Backends, Nutzungsendpunkte +- **Kanal-/Feature-Plugin-Schicht**: Slack-/Discord-/voice-call-/usw.-Integration, die Core-Fähigkeiten nutzt und auf einer Oberfläche präsentiert Zum Beispiel folgt TTS dieser Form: -- der Core besitzt die TTS-Richtlinie zur Antwortzeit, Fallback-Reihenfolge, Präferenzen und Kanalzustellung -- `openai`, `elevenlabs` und `microsoft` besitzen Synthese-Implementierungen -- `voice-call` nutzt den Laufzeit-Helper für Telephony-TTS +- der Core besitzt die TTS-Richtlinie zur Antwortzeit, Fallback-Reihenfolge, Präferenzen und Kanalauslieferung +- `openai`, `elevenlabs` und `microsoft` besitzen Syntheseimplementierungen +- `voice-call` nutzt den TTS-Laufzeithelfer für Telefonie -Dasselbe Muster sollte für zukünftige Fähigkeiten bevorzugt werden. +Dasselbe Muster sollte für künftige Fähigkeiten bevorzugt werden. -### Beispiel für ein Multi-Fähigkeits-Unternehmens-Plugin +### 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, -kann ein Anbieter all seine Oberflächen an einem Ort besitzen: +Verträge für Modelle, Sprache, Echtzeit-Transkription, Echtzeit-Stimme, Medien- +verständnis, Bilderzeugung, Videoerzeugung, Web-Abruf und Websuche hat, +kann ein Anbieter alle seine Oberflächen an einem Ort besitzen: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -372,63 +370,63 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Wichtig sind nicht die exakten Helper-Namen. Entscheidend ist die Form: +Wichtig sind nicht die exakten Hilfsnamen. Wichtig ist die Form: - ein Plugin besitzt die Anbieteroberfläche - der Core besitzt weiterhin die Fähigkeitsverträge -- Kanal- und Feature-Plugins nutzen `api.runtime.*`-Helper, nicht Anbietercode -- Vertragstests können prüfen, dass das Plugin die Fähigkeiten registriert hat, die - es zu besitzen beansprucht +- Kanäle und Feature-Plugins nutzen `api.runtime.*`-Hilfen, nicht Anbietercode +- Vertragstests können prüfen, dass das Plugin die Fähigkeiten registriert hat, die es + nach eigener Aussage besitzt ### Fähigkeitsbeispiel: Videoverständnis OpenClaw behandelt Bild-/Audio-/Videoverständnis bereits als eine gemeinsame -Fähigkeit. Dasselbe Ownership-Modell gilt auch dort: +Fähigkeit. Dasselbe Zuständigkeitsmodell gilt auch hier: 1. der Core definiert den Vertrag für Medienverständnis -2. Anbieter-Plugins registrieren je nach Anwendbarkeit `describeImage`, `transcribeAudio` und +2. Anbieter-Plugins registrieren je nach Fall `describeImage`, `transcribeAudio` und `describeVideo` 3. Kanal- und Feature-Plugins nutzen das gemeinsame Core-Verhalten, statt direkt an Anbietercode zu verdrahten -So werden die Video-Annahmen eines einzelnen Providers nicht in den Core eingebaut. Das Plugin besitzt +So werden die Videoannahmen eines einzelnen Providers nicht in den Core eingebrannt. Das Plugin besitzt die Anbieteroberfläche; der Core besitzt den Fähigkeitsvertrag und das Fallback-Verhalten. -Videogenerierung verwendet bereits dieselbe Reihenfolge: Der Core besitzt den typisierten -Fähigkeitsvertrag und den Laufzeit-Helper, und Anbieter-Plugins registrieren -Implementierungen von `api.registerVideoGenerationProvider(...)` dagegen. +Die Videoerzeugung verwendet bereits dieselbe Reihenfolge: Der Core besitzt den typisierten +Fähigkeitsvertrag und den Laufzeithelfer, und Anbieter-Plugins registrieren +`api.registerVideoGenerationProvider(...)`-Implementierungen dafür. -Du brauchst eine konkrete Rollout-Checkliste? 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 bewusst typisiert und zentralisiert in -`OpenClawPluginApi`. Dieser Vertrag definiert die unterstützten Registrierungspunkte und -die Laufzeit-Helper, auf die sich ein Plugin verlassen darf. +Die Plugin-API-Oberfläche ist absichtlich typisiert und in +`OpenClawPluginApi` zentralisiert. Dieser Vertrag definiert die unterstützten Registrierungspunkte und +die Laufzeithelfer, auf die sich ein Plugin verlassen darf. Warum das wichtig ist: - Plugin-Autoren erhalten einen stabilen internen Standard -- der Core kann doppelte Ownership ablehnen, etwa wenn zwei Plugins dieselbe +- der Core kann doppelte Zuständigkeit ablehnen, etwa wenn zwei Plugins dieselbe Provider-ID registrieren -- beim Start können umsetzbare Diagnosen für fehlerhafte Registrierung angezeigt werden -- Vertragstests können die Ownership gebündelter Plugins durchsetzen und stilles Drift verhindern +- beim Start können umsetzbare Diagnosen für fehlerhafte Registrierungen angezeigt werden +- Vertragstests können die Zuständigkeit gebündelter Plugins durchsetzen und stilles Driften verhindern Es gibt zwei Ebenen der Durchsetzung: -1. **Durchsetzung bei Laufzeitregistrierung** - Die Plugin-Registry validiert Registrierungen beim Laden von Plugins. Beispiele: - doppelte Provider-IDs, doppelte Sprach-Provider-IDs und fehlerhafte +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. 2. **Vertragstests** - Gebündelte Plugins werden bei Testläufen in Vertrags-Registries erfasst, damit - OpenClaw Ownership explizit prüfen kann. Heute wird das für Modell- - Provider, Sprach-Provider, Websuch-Provider und Ownership gebündelter Registrierungen verwendet. + Gebündelte Plugins werden während Testläufen in Vertrags-Registries erfasst, sodass + OpenClaw Zuständigkeit explizit prüfen kann. Heute wird das für Modell- + Provider, Speech-Provider, Websuch-Provider und die Zuständigkeit gebündelter Registrierungen verwendet. Der praktische Effekt ist, dass OpenClaw im Voraus weiß, welches Plugin welche -Oberfläche besitzt. Dadurch können Core und Kanäle nahtlos zusammenspielen, weil Ownership -deklariert, typisiert und testbar ist, statt implizit zu sein. +Oberfläche besitzt. Dadurch können Core und Kanäle nahtlos zusammenspielen, weil die Zuständigkeit +deklariert, typisiert und testbar ist, statt implizit zu bleiben. ### Was in einen Vertrag gehört @@ -443,34 +441,34 @@ Gute Plugin-Verträge sind: Schlechte Plugin-Verträge sind: -- anbieterspezifische Richtlinie, die im Core versteckt ist -- einmalige Escape Hatches für Plugins, die die Registry umgehen +- anbieterspezifische Richtlinien, die im Core verborgen sind +- einmalige Plugin-Ausnahmepfade, die die Registry umgehen - Kanalcode, der direkt in eine Anbieterimplementierung greift - ad hoc Laufzeitobjekte, die nicht Teil von `OpenClawPluginApi` oder `api.runtime` sind -Im Zweifel hebe die Abstraktionsebene an: Definiere zuerst die Fähigkeit, dann -lass Plugins daran andocken. +Im Zweifel die Abstraktionsebene anheben: zuerst die Fähigkeit definieren, dann +Plugins daran anschließen lassen. ## Ausführungsmodell -Native OpenClaw-Plugins laufen **in-process** mit dem Gateway. Sie sind nicht -sandboxed. Ein geladenes natives Plugin hat dieselbe Trust-Grenze auf Prozessebene wie +Native OpenClaw-Plugins laufen **im Prozess** mit dem Gateway. Sie sind nicht +sandboxed. Ein geladenes natives Plugin hat dieselbe Vertrauensgrenze auf Prozessebene wie Core-Code. -Implikationen: +Auswirkungen: - ein natives Plugin kann Tools, Netzwerk-Handler, Hooks und Dienste registrieren -- ein Bug in einem nativen Plugin kann das Gateway abstürzen lassen oder destabilisieren -- ein bösartiges natives Plugin entspricht willkürlicher Codeausführung innerhalb des - OpenClaw-Prozesses +- ein Fehler in einem nativen Plugin kann das Gateway zum Absturz bringen oder destabilisieren +- ein bösartiges natives Plugin entspricht willkürlicher 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. -Verwende Allowlists und explizite Installations-/Ladepfade für nicht gebündelte Plugins. Behandle -Workspace-Plugins als Code zur Entwicklungszeit, nicht als Produktionsstandard. +Verwenden Sie Allowlists und explizite Installations-/Ladepfade für nicht gebündelte Plugins. Behandeln Sie +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 @@ -481,134 +479,131 @@ 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/auf der Allowlist ist. - Das ist normal und nützlich für lokale Entwicklung, Patch-Tests und Hotfixes. -## Export-Grenze +## Exportgrenze -OpenClaw exportiert Fähigkeiten, nicht Implementierungs-Convience. +OpenClaw exportiert Fähigkeiten, nicht Implementierungs-Komfortfunktionen. -Halte Fähigkeitsregistrierung öffentlich. Beschneide nicht-vertragliche Helper-Exporte: +Halten Sie die Fähigkeitsregistrierung öffentlich. Reduzieren Sie Nicht-Vertrags-Hilfsexporte: -- Helper-Subpaths spezifisch für gebündelte Plugins -- Laufzeit-Plumbing-Subpaths, die nicht als öffentliche API gedacht sind -- anbieterspezifische Convenience-Helper -- Setup-/Onboarding-Helper, die Implementierungsdetails sind +- hilfsspezifische Subpfade für gebündelte Plugins +- Laufzeit-Verdrahtungs-Subpfade, die nicht als öffentliche API gedacht sind +- anbieterspezifische Komforthelfer +- Setup-/Onboarding-Helfer, die Implementierungsdetails sind -Einige Helper-Subpaths gebündelter Plugins verbleiben aus Kompatibilitätsgründen und für die -Wartung gebündelter Plugins weiterhin in der generierten SDK-Export-Map. Aktuelle Beispiele sind +Einige Hilfs-Subpfade gebündelter Plugins verbleiben aus Kompatibilitätsgründen und für die +Pflege gebündelter Plugins noch in der generierten SDK-Export-Map. Aktuelle Beispiele sind `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` und mehrere `plugin-sdk/matrix*`-Seams. Behandle diese als +`plugin-sdk/zalo-setup` und mehrere `plugin-sdk/matrix*`-Seams. Behandeln Sie diese als reservierte Exporte für Implementierungsdetails, nicht als das empfohlene SDK-Muster für -neue Plugins von Drittanbietern. +neue Drittanbieter-Plugins. ## Ladepipeline -Beim Start macht OpenClaw grob Folgendes: +Beim Start führt OpenClaw ungefähr Folgendes aus: -1. Plugin-Roots für Kandidaten entdecken +1. Wurzeln potenzieller Plugins 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. Aktivierung für jeden Kandidaten festlegen 6. aktivierte native Module über jiti laden -7. native `register(api)`-Hooks (oder `activate(api)` — ein Legacy-Alias) aufrufen und Registrierungen in die Plugin-Registry einsammeln +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 bereitstellen -`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`; bevorzuge `register` für neue Plugins. +`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`; für neue Plugins `register` bevorzugen. -Die Sicherheitsschranken greifen **vor** der Laufzeitausführung. Kandidaten werden blockiert, -wenn der Einstiegspunkt aus dem Plugin-Root ausbricht, der Pfad world-writable ist oder die Pfad- -Ownership bei nicht gebündelten Plugins verdächtig aussieht. +Die Sicherheitsprüfungen erfolgen **vor** der Laufzeitausführung. Kandidaten werden blockiert, +wenn der Einstiegspunkt die Plugin-Wurzel verlässt, der Pfad weltweit beschreibbar ist oder die +Pfadinhaberschaft bei nicht gebündelten Plugins verdächtig aussieht. -### Manifest-First-Verhalten +### Manifest-first-Verhalten -Das Manifest ist die Control-Plane-Quelle der Wahrheit. OpenClaw verwendet es, um: +Das Manifest ist die Quelle der Wahrheit auf der Steuerungsebene. OpenClaw verwendet 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 +- Control-UI-Beschriftungen/-Platzhalter zu ergänzen - Installations-/Katalogmetadaten anzuzeigen -- kostengünstige Aktivierungs- und Setup-Deskriptoren zu bewahren, ohne die Plugin-Laufzeit zu laden +- günstige Aktivierungs- und Setup-Deskriptoren zu erhalten, ohne die Plugin-Laufzeit zu laden -Bei nativen Plugins ist das Laufzeitmodul der Data-Plane-Teil. Es registriert das +Für native Plugins ist das Laufzeitmodul der Teil der Datenebene. Es registriert das tatsächliche Verhalten wie Hooks, Tools, Befehle oder Provider-Flows. -Optionale Manifest-Blöcke `activation` und `setup` bleiben auf der Control Plane. -Sie sind rein metadatenbasierte Deskriptoren für Aktivierungsplanung und Setup-Discovery; -sie ersetzen weder Laufzeitregistrierung, `register(...)` noch `setupEntry`. -Die ersten Live-Aktivierungs-Consumer verwenden jetzt Manifest-Hinweise zu Befehlen, Kanälen und Providern, -um das Laden von Plugins vor einer breiteren Materialisierung der Registry einzugrenzen: +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 Laufzeitregistrierung, `register(...)` oder `setupEntry`. +Die ersten Live-Aktivierungskonsumenten verwenden nun Manifest-Hinweise zu Befehlen, Kanälen und Providern, +um das Laden von Plugins einzugrenzen, bevor eine breitere Materialisierung der Registry erfolgt: - CLI-Laden wird auf Plugins eingegrenzt, die den angeforderten primären Befehl besitzen -- Kanal-Setup-/Plugin-Auflösung wird auf Plugins eingegrenzt, die die angeforderte +- Kanal-Setup/Plugin-Auflösung wird auf Plugins eingegrenzt, die die angeforderte Kanal-ID besitzen -- explizite Provider-Setup-/Laufzeit-Auflösung wird auf Plugins eingegrenzt, die die +- explizite Provider-Setup-/Laufzeitauflösung wird auf Plugins eingegrenzt, die die angeforderte Provider-ID besitzen -Die Setup-Discovery bevorzugt jetzt descriptor-eigene IDs wie `setup.providers` und +Die Setup-Erkennung bevorzugt nun Deskriptor-besessene IDs wie `setup.providers` und `setup.cliBackends`, um Kandidaten-Plugins einzugrenzen, bevor sie auf -`setup-api` für Plugins zurückfällt, die weiterhin Laufzeit-Hooks zur Setup-Zeit benötigen. Wenn mehr als -ein entdecktes Plugin dieselbe normalisierte Setup-Provider- oder CLI-Backend- -ID beansprucht, lehnt die Setup-Suche den mehrdeutigen Besitzer ab, statt sich auf die Discovery- -Reihenfolge zu verlassen. +`setup-api` für Plugins zurückfällt, die weiterhin Setup-Laufzeit-Hooks benötigen. Wenn mehr als +ein erkanntes Plugin dieselbe normalisierte Setup-Provider- oder CLI-Backend- +ID beansprucht, verweigert die Setup-Auflösung den mehrdeutigen Eigentümer, anstatt sich auf die Erkennungsreihenfolge zu verlassen. ### Was der Loader zwischenspeichert -OpenClaw hält kurze In-Process-Caches für: +OpenClaw hält kurze prozessinterne Caches für: -- Discovery-Ergebnisse +- Erkennungsergebnisse - Daten der Manifest-Registry - geladene Plugin-Registries -Diese Caches reduzieren burstartige Startvorgänge und den Overhead wiederholter Befehle. Man kann sie -sicher als kurzlebige Performance-Caches verstehen, nicht als Persistenz. +Diese Caches reduzieren stoßartige Startvorgänge und den Overhead wiederholter Befehle. Man kann sie +sicher als kurzlebige Performance-Caches betrachten, nicht als Persistenz. Hinweis zur Performance: -- Setze `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` oder +- Setzen Sie `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` oder `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, um diese Caches zu deaktivieren. -- Passe Cache-Fenster mit `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` und +- Passen Sie Cache-Fenster mit `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` und `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS` an. ## Registry-Modell -Geladene Plugins mutieren nicht direkt zufällige globale Core-Zustände. Sie registrieren sich in einer +Geladene Plugins verändern nicht direkt beliebige globale Core-Zustände. Sie registrieren sich in einer zentralen Plugin-Registry. Die Registry verfolgt: -- Plugin-Einträge (Identität, Quelle, Herkunft, Status, Diagnostik) +- Plugin-Einträge (Identität, Quelle, Herkunft, Status, Diagnosen) - Tools - Legacy-Hooks und typisierte Hooks - Kanäle - Provider - Gateway-RPC-Handler - HTTP-Routen -- CLI-Registrare +- CLI-Registrars - Hintergrunddienste - plugin-eigene Befehle -Core-Features lesen dann aus dieser Registry, statt direkt mit Plugin-Modulen -zu sprechen. Dadurch bleibt das Laden einseitig: +Core-Features lesen dann aus dieser Registry, anstatt direkt mit Plugin-Modulen zu kommunizieren. +Dadurch bleibt das Laden unidirektional: - Plugin-Modul -> Registry-Registrierung - Core-Laufzeit -> Registry-Nutzung -Diese Trennung ist wichtig für Wartbarkeit. Sie bedeutet, dass die meisten Core-Oberflächen nur -einen Integrationspunkt brauchen: „Registry lesen“, nicht „jedes Plugin- -Modul speziell behandeln“. +Diese Trennung ist für die Wartbarkeit wichtig. Sie bedeutet, dass die meisten Core-Oberflächen nur +einen Integrationspunkt benötigen: „die Registry lesen“, nicht „jedes Plugin-Modul speziell behandeln“. -## Callbacks für Konversations-Bindings +## Callbacks für Konversationsbindung Plugins, die eine Konversation binden, können reagieren, wenn eine Genehmigung aufgelöst wird. -Verwende `api.onConversationBindingResolved(...)`, um einen Callback zu erhalten, nachdem eine Bind- -Anfrage genehmigt oder abgelehnt wurde: +Verwenden Sie `api.onConversationBindingResolved(...)`, um nach der Genehmigung oder Ablehnung einer Bindungsanfrage einen Callback zu erhalten: ```ts export default { @@ -632,23 +627,23 @@ Felder der Callback-Nutzlast: - `status`: `"approved"` oder `"denied"` - `decision`: `"allow-once"`, `"allow-always"` oder `"deny"` -- `binding`: das aufgelöste Binding für genehmigte Anfragen -- `request`: die ursprüngliche Anfragezusammenfassung, Detach-Hinweis, Sender-ID und +- `binding`: die aufgelöste Bindung für genehmigte Anfragen +- `request`: die ursprüngliche Anforderungszusammenfassung, Hinweis zum Trennen, Absender-ID und Konversationsmetadaten Dieser Callback dient nur der Benachrichtigung. Er ändert nicht, wer eine -Konversation binden darf, und läuft, nachdem die Core-Behandlung der Genehmigung abgeschlossen ist. +Konversation binden darf, und er wird ausgeführt, nachdem die Core-Verarbeitung der Genehmigung abgeschlossen ist. ## Provider-Laufzeit-Hooks -Provider-Plugins haben jetzt zwei Schichten: +Provider-Plugins haben jetzt zwei Ebenen: -- Manifest-Metadaten: `providerAuthEnvVars` für günstige Provider-Env-Auth-Suche - vor dem Laufzeitladen, `providerAuthAliases` für Provider-Varianten mit gemeinsamer - Authentifizierung, `channelEnvVars` für günstige Kanal-Env-/Setup-Suche vor dem Laufzeit- - Laden sowie `providerAuthChoices` für günstige Onboarding-/Auth-Choice-Labels und - CLI-Flag-Metadaten vor dem Laufzeitladen -- Hooks zur Konfigurationszeit: `catalog` / Legacy-`discovery` plus `applyConfigDefaults` +- Manifest-Metadaten: `providerAuthEnvVars` für günstige env-auth- + Abfrage von Providern vor dem Laden der Laufzeit, `providerAuthAliases` für Provider-Varianten, die sich + Authentifizierung teilen, `channelEnvVars` für günstige env-/Setup-Abfrage von Kanälen vor dem Laden der Laufzeit, + sowie `providerAuthChoices` für günstige Onboarding-/Auth-Choice-Labels und + CLI-Flag-Metadaten vor dem Laden der Laufzeit +- Hooks zur Konfigurationszeit: `catalog` / Legacy-`discovery` sowie `applyConfigDefaults` - Laufzeit-Hooks: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -663,97 +658,94 @@ Provider-Plugins haben jetzt zwei Schichten: `buildAuthDoctorHint`, `matchesContextOverflowError`, `classifyFailoverReason`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, - `isBinaryThinking`, `supportsXHighThinking`, `supportsAdaptiveThinking`, - `supportsMaxThinking`, + `resolveThinkingProfile`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, `createEmbeddingProvider`, `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw besitzt weiterhin die generische Agent-Schleife, das Failover, die Transcript-Verarbeitung und -Tool-Richtlinien. Diese Hooks sind die Erweiterungsoberfläche für anbieterspezifisches Verhalten, ohne -einen vollständig benutzerdefinierten Inferenz-Transport zu benötigen. +OpenClaw besitzt weiterhin die generische Agent-Schleife, Failover, Transkriptverarbeitung und +Tool-Richtlinien. Diese Hooks sind die Erweiterungsoberfläche für providerspezifisches Verhalten, ohne +einen vollständig benutzerdefinierten Inferenztransport zu benötigen. -Verwende Manifest-`providerAuthEnvVars`, wenn der Provider envbasierte Anmeldedaten -hat, die generische Auth-/Status-/Model-Picker-Pfade ohne Laden der Plugin-Laufzeit sehen -sollen. Verwende Manifest-`providerAuthAliases`, wenn eine Provider-ID die Env-Variablen, -Auth-Profile, config-gestützte Authentifizierung und API-Key-Onboarding-Auswahl einer -anderen Provider-ID wiederverwenden soll. Verwende Manifest-`providerAuthChoices`, wenn -Onboarding-/Auth-Choice-CLI-Oberflächen die Choice-ID des Providers, Gruppenlabels und einfache -Auth-Verdrahtung mit einem Flag kennen sollen, ohne die Provider-Laufzeit zu laden. Behalte in der Provider- -Laufzeit `envVars` für operatorbezogene Hinweise wie Onboarding-Labels oder OAuth- +Verwenden Sie Manifest-`providerAuthEnvVars`, wenn der Provider env-basierte Anmeldedaten hat, +die generische Auth-/Status-/Modellwähler-Pfade ohne Laden der Plugin- +Laufzeit sehen sollen. Verwenden Sie Manifest-`providerAuthAliases`, wenn eine Provider-ID die +env vars, Auth-Profile, konfigurationsgestützte Authentifizierung und die API-Key- +Onboarding-Auswahl 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 +Authentifizierungsverdrahtung mit einem einzelnen Flag kennen sollen, ohne die Provider-Laufzeit zu laden. Behalten Sie Provider-Laufzeit- +`envVars` für operatorseitige Hinweise wie Onboarding-Labels oder OAuth- Client-ID-/Client-Secret-Setup-Variablen. -Verwende Manifest-`channelEnvVars`, wenn ein Kanal envgesteuerte Authentifizierung oder Setup hat, -die generischer Shell-Env-Fallback, Konfigurations-/Statusprüfungen oder Setup-Prompts sehen -sollen, ohne die Kanal-Laufzeit zu laden. +Verwenden Sie Manifest-`channelEnvVars`, wenn ein Kanal env-gesteuerte Authentifizierung oder Setup hat, +die generischer Shell-env-Fallback, Konfigurations-/Statusprüfungen oder Setup-Prompts ohne Laden der Kanal-Laufzeit sehen sollen. ### Hook-Reihenfolge und Verwendung -Für Modell-/Provider-Plugins ruft OpenClaw Hooks grob in dieser Reihenfolge auf. -Die Spalte „Wann verwenden“ ist die schnelle Entscheidungshilfe. +Für Modell-/Provider-Plugins ruft OpenClaw Hooks ungefähr in dieser Reihenfolge auf. +Die Spalte „When to use“ ist die kurze Entscheidungshilfe. -| # | Hook | Was er macht | Wann verwenden | +| # | Hook | Was er bewirkt | Wann verwenden | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Veröffentlicht die Provider-Konfiguration in `models.providers` während der Generierung von `models.json` | Der Provider besitzt einen Katalog oder Standardwerte für `baseUrl` | -| 2 | `applyConfigDefaults` | Wendet provider-eigene globale Konfigurations-Standardwerte während der Materialisierung der Konfiguration an | Standardwerte hängen von Auth-Modus, Env oder Semantik der Provider-Modellfamilie ab | -| -- | _(eingebaute Modellsuche)_ | OpenClaw versucht zuerst den normalen Registry-/Katalogpfad | _(kein Plugin-Hook)_ | -| 3 | `normalizeModelId` | Normalisiert Legacy- oder Preview-Aliase für Modell-IDs vor der Suche | Der Provider besitzt Alias-Bereinigung vor der kanonischen Modellauflösung | -| 4 | `normalizeTransport` | Normalisiert `api` / `baseUrl` einer Provider-Familie vor der generischen Modellassemblierung | Der Provider besitzt Transport-Bereinigung für benutzerdefinierte Provider-IDs in derselben Transportfamilie | -| 5 | `normalizeConfig` | Normalisiert `models.providers.` vor der Laufzeit-/Provider-Auflösung | Der Provider benötigt Konfigurationsbereinigung, die beim Plugin liegen sollte; gebündelte Helper der Google-Familie stützen auch unterstützte Google-Konfigurationseinträge ab | -| 6 | `applyNativeStreamingUsageCompat` | Wendet native Streaming-Usage-Kompatibilitäts-Umschreibungen auf Konfigurations-Provider an | Der Provider benötigt endpunktgesteuerte Korrekturen für native Streaming-Usage-Metadaten | -| 7 | `resolveConfigApiKey` | Löst Authentifizierung über Env-Marker für Konfigurations-Provider vor dem Laden der Laufzeit-Authentifizierung auf | Der Provider hat provider-eigene Auflösung von API-Keys über Env-Marker; `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver | -| 8 | `resolveSyntheticAuth` | Macht lokale/selbstgehostete oder konfigurationsgestützte Authentifizierung sichtbar, ohne Klartext zu persistieren | Der Provider kann mit einem synthetischen/lokalen Marker für Anmeldedaten arbeiten | -| 9 | `resolveExternalAuthProfiles` | Legt provider-eigene externe Auth-Profile darüber; Standard `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` | Stuft gespeicherte synthetische Profil-Platzhalter hinter env-/config-gestützte Authentifizierung herab | Der Provider speichert synthetische Platzhalterprofile, die keine höhere Priorität haben sollten | -| 11 | `resolveDynamicModel` | Synchroner Fallback für provider-eigene Modell-IDs, die noch nicht in der lokalen Registry sind | Der Provider akzeptiert beliebige Upstream-Modell-IDs | -| 12 | `prepareDynamicModel` | Asynchrones Warm-up, danach läuft `resolveDynamicModel` erneut | Der Provider benötigt Netzwerk-Metadaten, bevor unbekannte IDs aufgelöst werden können | -| 13 | `normalizeResolvedModel` | Letzte Umschreibung, bevor der Embedded Runner das aufgelöste Modell verwendet | Der Provider benötigt Transport-Umschreibungen, verwendet aber weiterhin einen Core-Transport | -| 14 | `contributeResolvedModelCompat` | Liefert Kompatibilitäts-Flags für Anbieter-Modelle hinter einem anderen kompatiblen Transport | Der Provider erkennt eigene Modelle auf Proxy-Transporten, ohne die Provider-Rolle zu übernehmen | -| 15 | `capabilities` | Provider-eigene Transcript-/Tooling-Metadaten, die von gemeinsamer Core-Logik verwendet werden | Der Provider benötigt Besonderheiten für Transcript/Provider-Familie | -| 16 | `normalizeToolSchemas` | Normalisiert Tool-Schemas, bevor der Embedded Runner sie sieht | Der Provider benötigt Bereinigung von Schemas der Transportfamilie | -| 17 | `inspectToolSchemas` | Macht provider-eigene Schema-Diagnostik nach der Normalisierung sichtbar | Der Provider möchte Keyword-Warnungen, ohne dem Core provider-spezifische Regeln beizubringen | -| 18 | `resolveReasoningOutputMode` | Wählt nativen oder getaggten Vertrag für Reasoning-Output | Der Provider benötigt getaggten Reasoning-/Final-Output statt nativer Felder | -| 19 | `prepareExtraParams` | Normalisierung von Request-Parametern vor generischen Wrappern für Stream-Optionen | Der Provider benötigt Standard-Request-Parameter oder providerbezogene Bereinigung von Parametern | +| 1 | `catalog` | Veröffentlicht die Provider-Konfiguration während der Generierung von `models.json` in `models.providers` | Der Provider besitzt einen Katalog oder Standardwerte für die Basis-URL | +| 2 | `applyConfigDefaults` | Wendet provider-eigene globale Konfigurationsstandardwerte während der Materialisierung der Konfiguration an | Standardwerte hängen vom Authentifizierungsmodus, von env oder von der Modellfamilien-Semantik des Providers ab | +| -- | _(built-in model lookup)_ | OpenClaw versucht zuerst den normalen Registry-/Katalogpfad | _(kein Plugin-Hook)_ | +| 3 | `normalizeModelId` | Normalisiert Legacy- oder Vorschau-Aliasse für Modell-IDs vor der Auflösung | Der Provider besitzt die Alias-Bereinigung vor der kanonischen Modellauflösung | +| 4 | `normalizeTransport` | Normalisiert Provider-Familien-`api` / `baseUrl` vor der generischen Modellzusammenstellung | Der Provider besitzt die Transport-Bereinigung für benutzerdefinierte Provider-IDs in derselben Transportfamilie | +| 5 | `normalizeConfig` | Normalisiert `models.providers.` vor der Laufzeit-/Provider-Auflösung | Der Provider benötigt Konfigurationsbereinigung, die beim Plugin liegen sollte; gebündelte Hilfen der Google-Familie stützen auch unterstützte Google-Konfigurationseinträge ab | +| 6 | `applyNativeStreamingUsageCompat` | Wendet Compat-Umschreibungen für native Streaming-Nutzung auf Konfigurations-Provider an | Der Provider benötigt endpoint-gesteuerte Korrekturen für Metadaten der nativen Streaming-Nutzung | +| 7 | `resolveConfigApiKey` | Löst env-marker-Authentifizierung für Konfigurations-Provider vor dem Laden der Laufzeit-Authentifizierung auf | Der Provider besitzt provider-eigene env-marker-API-Key-Auflösung; `amazon-bedrock` hat hier ebenfalls einen eingebauten AWS-env-marker-Resolver | +| 8 | `resolveSyntheticAuth` | Macht lokale/self-hosted oder konfigurationsgestützte Authentifizierung verfügbar, ohne Klartext zu persistieren | Der Provider kann mit einem synthetischen/lokalen Credential-Marker arbeiten | +| 9 | `resolveExternalAuthProfiles` | Legt provider-eigene externe Auth-Profile darüber; Standard für `persistence` ist `runtime-only` bei CLI-/app-eigenen Credentials | Der Provider verwendet externe Auth-Credentials wieder, ohne kopierte Refresh-Tokens zu persistieren | +| 10 | `shouldDeferSyntheticProfileAuth` | Stuften gespeicherte synthetische Profil-Platzhalter hinter env-/konfigurationsgestützter Authentifizierung herab | Der Provider speichert synthetische Platzhalterprofile, die keinen Vorrang haben sollten | +| 11 | `resolveDynamicModel` | Synchroner Fallback für provider-eigene Modell-IDs, die noch nicht in der lokalen Registry stehen | Der Provider akzeptiert beliebige vorgelagerte Modell-IDs | +| 12 | `prepareDynamicModel` | Asynchrone Aufwärmphase, danach läuft `resolveDynamicModel` erneut | Der Provider benötigt Netzwerkmetadaten, bevor unbekannte IDs aufgelöst werden können | +| 13 | `normalizeResolvedModel` | Finale Umschreibung, bevor der Embedded Runner das aufgelöste Modell verwendet | Der Provider benötigt Transport-Umschreibungen, verwendet aber weiterhin einen Core-Transport | +| 14 | `contributeResolvedModelCompat` | Steuert Compat-Flags für Anbietermodelle hinter einem anderen kompatiblen Transport bei | Der Provider erkennt seine eigenen Modelle auf Proxy-Transporten, ohne den Provider zu übernehmen | +| 15 | `capabilities` | Provider-eigene Metadaten für Transkripte/Tools, die von gemeinsamer Core-Logik verwendet werden | Der Provider benötigt Besonderheiten für Transkripte/Provider-Familien | +| 16 | `normalizeToolSchemas` | Normalisiert Tool-Schemas, bevor der Embedded Runner sie sieht | Der Provider benötigt Schema-Bereinigung für Transportfamilien | +| 17 | `inspectToolSchemas` | Macht provider-eigene Schema-Diagnosen nach der Normalisierung sichtbar | Der Provider möchte Keyword-Warnungen, ohne dem Core providerspezifische Regeln beizubringen | +| 18 | `resolveReasoningOutputMode` | Wählt nativen oder getaggten Vertrag für Reasoning-Ausgabe | Der Provider benötigt getaggte Argumentation/finale Ausgabe statt nativer Felder | +| 19 | `prepareExtraParams` | Normalisierung von Anforderungsparametern vor generischen Wrappern für Stream-Optionen | Der Provider benötigt Standard-Anforderungsparameter oder providerbezogene Parameterbereinigung | | 20 | `createStreamFn` | Ersetzt den normalen Stream-Pfad vollständig durch einen benutzerdefinierten Transport | Der Provider benötigt ein benutzerdefiniertes Wire-Protokoll, nicht nur einen Wrapper | -| 21 | `wrapStreamFn` | Stream-Wrapper, nachdem generische Wrapper angewendet wurden | Der Provider benötigt Wrapper für Request-Header/Body/Modell-Kompatibilität ohne benutzerdefinierten Transport | -| 22 | `resolveTransportTurnState` | Hängt native Header oder Metadaten pro Turn für den Transport an | Der Provider möchte, dass generische Transporte provider-native Turn-Identität senden | -| 23 | `resolveWebSocketSessionPolicy` | Hängt native WebSocket-Header oder eine Session-Abkühlrichtlinie an | Der Provider möchte, dass generische WS-Transporte Session-Header oder Fallback-Richtlinien anpassen | -| 24 | `formatApiKey` | Auth-Profile-Formatter: gespeichertes Profil wird zur Laufzeitzeichenfolge `apiKey` | Der Provider speichert zusätzliche Auth-Metadaten und benötigt eine benutzerdefinierte Laufzeit-Token-Form | -| 25 | `refreshOAuth` | OAuth-Refresh-Override für benutzerdefinierte Refresh-Endpunkte oder Richtlinie bei Refresh-Fehlern | Der Provider passt nicht zu den gemeinsamen `pi-ai`-Refreshern | -| 26 | `buildAuthDoctorHint` | Reparaturhinweis, der angehängt wird, wenn OAuth-Refresh fehlschlägt | Der Provider benötigt provider-eigene Auth-Reparaturhinweise nach einem Refresh-Fehler | -| 27 | `matchesContextOverflowError` | Provider-eigener Matcher für Überläufe des Kontextfensters | Der Provider hat rohe Overflow-Fehler, die generische Heuristiken übersehen würden | -| 28 | `classifyFailoverReason` | Provider-eigene Klassifizierung von Failover-Gründen | Der Provider kann rohe API-/Transport-Fehler auf Rate-Limit/Überlastung/usw. abbilden | +| 21 | `wrapStreamFn` | Stream-Wrapper, nachdem generische Wrapper angewendet wurden | Der Provider benötigt Wrapper für Anforderungsheader/Body/Modell-Compat ohne benutzerdefinierten Transport | +| 22 | `resolveTransportTurnState` | Hängt native turn-spezifische Transport-Header oder Metadaten an | Der Provider möchte, dass generische Transporte provider-native Turn-Identität senden | +| 23 | `resolveWebSocketSessionPolicy` | Hängt native WebSocket-Header oder eine Session-Cool-down-Richtlinie an | 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-Token-Form | +| 25 | `refreshOAuth` | OAuth-Refresh-Überschreibung für benutzerdefinierte Refresh-Endpunkte oder Richtlinien bei Refresh-Fehlern | Der Provider passt nicht zu den gemeinsamen `pi-ai`-Refresh-Mechanismen | +| 26 | `buildAuthDoctorHint` | Reparaturhinweis, der angehängt wird, wenn 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 Overflow des Kontextfensters | Der Provider hat rohe Overflow-Fehler, die generische Heuristiken übersehen würden | +| 28 | `classifyFailoverReason` | Provider-eigene Klassifizierung von Failover-Gründen | Der Provider kann rohe API-/Transportfehler auf Rate-Limit/Überlastung/usw. abbilden | | 29 | `isCacheTtlEligible` | Prompt-Cache-Richtlinie für Proxy-/Backhaul-Provider | Der Provider benötigt proxyspezifisches TTL-Gating für den Cache | -| 30 | `buildMissingAuthMessage` | Ersatz für die generische Wiederherstellungsnachricht bei fehlender Authentifizierung | Der Provider benötigt einen provider-spezifischen Wiederherstellungshinweis bei fehlender Authentifizierung | -| 31 | `suppressBuiltInModel` | Unterdrückung veralteter Upstream-Modelle plus optionaler benutzerorientierter Fehlerhinweis | Der Provider muss veraltete Upstream-Zeilen ausblenden oder durch einen Anbieterhinweis ersetzen | -| 32 | `augmentModelCatalog` | Synthetische/finale Katalogzeilen, die nach der Discovery angehängt werden | Der Provider benötigt synthetische Vorwärtskompatibilitäts-Zeilen in `models list` und Pickern | -| 33 | `isBinaryThinking` | On/Off-Reasoning-Toggle für Provider mit binärem Thinking | Der Provider stellt nur binäres Thinking an/aus bereit | -| 34 | `supportsXHighThinking` | Unterstützung für `xhigh`-Reasoning bei ausgewählten Modellen | Der Provider möchte `xhigh` nur für eine Teilmenge von Modellen | -| 35 | `supportsAdaptiveThinking` | Unterstützung für `adaptive` Thinking bei ausgewählten Modellen | Der Provider möchte `adaptive` nur für Modelle anzeigen, bei denen der Provider adaptives Thinking verwaltet | -| 36 | `supportsMaxThinking` | Unterstützung für `max`-Reasoning bei ausgewählten Modellen | Der Provider möchte `max` nur für Modelle anzeigen, die Provider-Max-Thinking unterstützen | -| 37 | `resolveDefaultThinkingLevel` | Standard-`/think`-Level für eine bestimmte Modellfamilie | Der Provider besitzt die Standard-`/think`-Richtlinie für eine Modellfamilie | -| 38 | `isModernModelRef` | Matcher für moderne Modelle für Live-Profilfilter und Smoke-Auswahl | Der Provider besitzt das Matching für bevorzugte Live-/Smoke-Modelle | -| 39 | `prepareRuntimeAuth` | Tauscht konfigurierte Anmeldedaten unmittelbar vor der Inferenz gegen das tatsächliche Laufzeit-Token/den Schlüssel aus | Der Provider benötigt einen Token-Austausch oder kurzlebige Request-Anmeldedaten | -| 40 | `resolveUsageAuth` | Löst Usage-/Billing-Anmeldedaten für `/usage` und verwandte Statusoberflächen auf | Der Provider benötigt benutzerdefiniertes Parsing von Usage-/Quota-Tokens oder andere Usage-Anmeldedaten | -| 41 | `fetchUsageSnapshot` | Holt und normalisiert providerspezifische Usage-/Quota-Snapshots, nachdem die Authentifizierung aufgelöst wurde | Der Provider benötigt einen providerspezifischen Usage-Endpunkt oder Payload-Parser | -| 42 | `createEmbeddingProvider` | Baut einen provider-eigenen Embedding-Adapter für Speicher/Suche | Verhalten von Memory-Embeddings gehört zum Provider-Plugin | -| 43 | `buildReplayPolicy` | Gibt eine Replay-Richtlinie zurück, die die Transcript-Verarbeitung für den Provider steuert | Der Provider benötigt benutzerdefinierte Transcript-Richtlinien (zum Beispiel das Entfernen von Thinking-Blöcken) | -| 44 | `sanitizeReplayHistory` | Schreibt den Replay-Verlauf nach generischer Transcript-Bereinigung um | Der Provider benötigt providerspezifische Replay-Umschreibungen über gemeinsame Compaction-Helper hinaus | -| 45 | `validateReplayTurns` | Endgültige Validierung oder Umformung von Replay-Turns vor dem Embedded Runner | Der Provider-Transport benötigt strengere Turn-Validierung nach generischer Bereinigung | -| 46 | `onModelSelected` | Führt provider-eigene Seiteneffekte nach der Modellauswahl aus | Der Provider benötigt Telemetrie oder provider-eigenen Status, wenn ein Modell aktiv wird | +| 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 Upstream-Modelle plus optionaler benutzerseitiger Fehlerhinweis | Der Provider muss veraltete Upstream-Zeilen ausblenden oder durch einen Anbieterhinweis ersetzen | +| 32 | `augmentModelCatalog` | Synthetische/finale Katalogzeilen, die nach der Erkennung angehängt werden | Der Provider benötigt synthetische Zeilen für Vorwärtskompatibilität in `models list` und Auswahllisten | +| 33 | `resolveThinkingProfile` | Modellspezifische `/think`-Stufe, Anzeigelabels und Standardwert | Der Provider stellt für ausgewählte Modelle eine benutzerdefinierte Thinking-Stufenleiter oder ein binäres Label bereit | +| 34 | `isBinaryThinking` | Compat-Hook für Argumentations-Umschalter an/aus | Der Provider stellt nur binäres Thinking an/aus bereit | +| 35 | `supportsXHighThinking` | Compat-Hook für Unterstützung von `xhigh`-Argumentation | Der Provider möchte `xhigh` nur für eine Teilmenge von Modellen | +| 36 | `resolveDefaultThinkingLevel` | Compat-Hook für die standardmäßige `/think`-Stufe | Der Provider besitzt die standardmäßige `/think`-Richtlinie für eine Modellfamilie | +| 37 | `isModernModelRef` | Matcher für moderne Modelle für Live-Profilfilter und Smoke-Auswahl | Der Provider besitzt die Zuordnung bevorzugter Modelle für Live/Smoke | +| 38 | `prepareRuntimeAuth` | Tauscht ein konfiguriertes Credential unmittelbar vor der Inferenz gegen das tatsächliche Laufzeit-Token/den Schlüssel aus | Der Provider benötigt einen Token-Austausch oder ein kurzlebiges Anforderungs-Credential | +| 39 | `resolveUsageAuth` | Löst Nutzungs-/Abrechnungs-Credentials für `/usage` und verwandte Statusoberflächen auf | Der Provider benötigt benutzerdefiniertes Parsen von Nutzungs-/Quota-Tokens oder ein anderes Nutzungs-Credential | +| 40 | `fetchUsageSnapshot` | Ruft providerspezifische Nutzungs-/Quota-Snapshots ab und normalisiert sie, nachdem die Authentifizierung aufgelöst wurde | Der Provider benötigt einen providerspezifischen Nutzungsendpunkt oder einen Payload-Parser | +| 41 | `createEmbeddingProvider` | Erstellt einen provider-eigenen Embedding-Adapter für Speicher/Suche | Das Verhalten von Speicher-Embeddings gehört zum Provider-Plugin | +| 42 | `buildReplayPolicy` | Gibt eine Replay-Richtlinie zurück, die die Transkriptverarbeitung für den Provider steuert | Der Provider benötigt eine benutzerdefinierte Transkript-Richtlinie (zum Beispiel das Entfernen von Thinking-Blöcken) | +| 43 | `sanitizeReplayHistory` | Schreibt den Replay-Verlauf nach der generischen Transkriptbereinigung um | Der Provider benötigt providerspezifische Replay-Umschreibungen über gemeinsame Compaction-Hilfen hinaus | +| 44 | `validateReplayTurns` | Finale Validierung oder Umformung von Replay-Turns vor dem Embedded Runner | Der Provider-Transport benötigt nach der generischen Bereinigung eine strengere Turn-Validierung | +| 45 | `onModelSelected` | Führt provider-eigene Nebeneffekte nach der Modellauswahl aus | 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 fallen dann auf andere Hook-fähige Provider-Plugins -zurück, bis eines die Modell-ID oder Transport/Konfiguration tatsächlich ä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 Eintrag -der Google-Familie in der Konfiguration umschreibt, wendet der gebündelte Google-Konfigurationsnormalisierer diese -Kompatibilitätsbereinigung weiterhin an. +zugeordnete Provider-Plugin und gehen dann andere Hook-fähige Provider-Plugins durch, +bis eines tatsächlich die Modell-ID oder den Transport/die Konfiguration ändert. So bleiben +Alias-/Compat-Provider-Shims funktionsfähig, ohne dass der Aufrufer wissen muss, welches +gebündelte Plugin die Umschreibung besitzt. Wenn kein Provider-Hook einen unterstützten +Konfigurationseintrag der Google-Familie umschreibt, wendet der gebündelte Google-Konfigurationsnormalisierer +diese Kompatibilitätsbereinigung weiterhin an. -Wenn der Provider ein vollständig benutzerdefiniertes Wire-Protokoll oder einen benutzerdefinierten Request-Executor benötigt, -ist das eine andere Klasse von Erweiterung. Diese Hooks sind für Provider-Verhalten gedacht, -das weiterhin auf der normalen Inferenzschleife von OpenClaw läuft. +Wenn der Provider ein vollständig benutzerdefiniertes Wire-Protokoll oder einen benutzerdefinierten +Request-Executor benötigt, ist das eine andere Klasse von Erweiterung. Diese Hooks sind für +Provider-Verhalten gedacht, das weiterhin in OpenClaws normaler Inferenzschleife läuft. ### Provider-Beispiel @@ -813,114 +805,115 @@ api.registerProvider({ - Anthropic verwendet `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, - `supportsAdaptiveThinking`, `supportsMaxThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - und `wrapStreamFn`, weil es Vorwärtskompatibilität für Claude 4.6, - Hinweise zur Provider-Familie, Hinweise zur Auth-Reparatur, Integration des Usage-Endpunkts, - Eignung für Prompt-Cache, authbewusste Konfigurations-Standardwerte, die - Standard-/adaptive Thinking-Richtlinie von Claude und anthropic-spezifische Stream-Formung für + `resolveThinkingProfile`, `applyConfigDefaults`, `isModernModelRef` + und `wrapStreamFn`, weil es Claude-4.6-Vorwärtskompatibilität, + Hinweise zur Provider-Familie, Hinweise zur Auth-Reparatur, Integration des Nutzungsendpunkts, + Eignung für Prompt-Cache, auth-bewusste Konfigurationsstandardwerte, die + standardmäßige/adaptive Thinking-Richtlinie von Claude und anthropic-spezifische Stream-Formung für Beta-Header, `/fast` / `serviceTier` und `context1m` besitzt. -- Die Claude-spezifischen Stream-Helper von Anthropic bleiben vorerst in der eigenen +- Anthropics Claude-spezifische Stream-Hilfen verbleiben vorerst in der eigenen öffentlichen `api.ts`- / `contract-api.ts`-Seam des gebündelten Plugins. Diese Paketoberfläche exportiert `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` und die Low-Level- - Wrapper-Builder für Anthropic, statt das generische SDK um die + Anthropic-Wrapper-Builder, anstatt das generische SDK um die Beta-Header-Regeln eines einzelnen Providers zu erweitern. - OpenAI verwendet `resolveDynamicModel`, `normalizeResolvedModel` und - `capabilities` plus `buildMissingAuthMessage`, `suppressBuiltInModel`, - `augmentModelCatalog`, `supportsXHighThinking` und `isModernModelRef`, - weil es Vorwärtskompatibilität für GPT-5.4, die direkte OpenAI- + `capabilities` sowie `buildMissingAuthMessage`, `suppressBuiltInModel`, + `augmentModelCatalog`, `resolveThinkingProfile` und `isModernModelRef`, + weil es GPT-5.4-Vorwärtskompatibilität, die direkte OpenAI- Normalisierung `openai-completions` -> `openai-responses`, Codex-bewusste Auth- - Hinweise, Spark-Unterdrückung, synthetische OpenAI-List-Zeilen und die GPT-5-Thinking- / - Live-Model-Richtlinie besitzt; die Stream-Familie `openai-responses-defaults` besitzt die - gemeinsamen nativen OpenAI-Responses-Wrapper für Attribution-Header, - `/fast`/`serviceTier`, Textausführlichkeit, native Codex-Websuche, - Shaping der Reasoning-Kompatibilitäts-Payload und Context-Management für Responses. -- OpenRouter verwendet `catalog` plus `resolveDynamicModel` und - `prepareDynamicModel`, weil der Provider als Pass-through arbeitet und neue - Modell-IDs anbieten kann, bevor sich der statische Katalog von OpenClaw aktualisiert; außerdem verwendet er + Hinweise, Spark-Unterdrückung, synthetische OpenAI-Listenzeilen und die Thinking- / + Live-Modell-Richtlinie von GPT-5 besitzt; die Stream-Familie `openai-responses-defaults` besitzt die + gemeinsamen nativen OpenAI-Responses-Wrapper für Attributions-Header, + `/fast`/`serviceTier`, Text-Verbosity, native Codex-Websuche, + Payload-Formung für Reasoning-Compat und Context-Management für Responses. +- OpenRouter verwendet `catalog` sowie `resolveDynamicModel` und + `prepareDynamicModel`, weil der Provider pass-through ist und neue + Modell-IDs bereitstellen kann, bevor OpenClaws statischer Katalog aktualisiert wird; außerdem verwendet es `capabilities`, `wrapStreamFn` und `isCacheTtlEligible`, um providerspezifische Request-Header, Routing-Metadaten, Reasoning-Patches und - Prompt-Cache-Richtlinien aus dem Core herauszuhalten. Seine Replay-Richtlinie kommt aus der + Prompt-Cache-Richtlinien aus dem Core herauszuhalten. Seine Replay-Richtlinie stammt aus der Familie `passthrough-gemini`, während die Stream-Familie `openrouter-thinking` - die Proxy-Injektion von Reasoning und das Überspringen nicht unterstützter Modelle bzw. von `auto` besitzt. + Proxy-Reasoning-Injektion und das Überspringen nicht unterstützter Modelle bzw. von `auto` besitzt. - GitHub Copilot verwendet `catalog`, `auth`, `resolveDynamicModel` und - `capabilities` plus `prepareRuntimeAuth` und `fetchUsageSnapshot`, weil es - provider-eigenes Device-Login, Modell-Fallback-Verhalten, Claude-Transcript- - Besonderheiten, einen GitHub-Token-zu-Copilot-Token-Austausch und einen provider-eigenen - Usage-Endpunkt benötigt. + `capabilities` sowie `prepareRuntimeAuth` und `fetchUsageSnapshot`, weil es + geräteeigenes Login, Modell-Fallback-Verhalten, Claude-Transkript- + Besonderheiten, einen Austausch GitHub-Token -> Copilot-Token und einen provider-eigenen Nutzungsendpunkt benötigt. - OpenAI Codex verwendet `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` und `augmentModelCatalog` plus + `normalizeResolvedModel`, `refreshOAuth` und `augmentModelCatalog` sowie `prepareExtraParams`, `resolveUsageAuth` und `fetchUsageSnapshot`, weil es - weiterhin auf Core-OpenAI-Transporten läuft, aber seine Transport-/Base-URL- - Normalisierung, OAuth-Refresh-Fallback-Richtlinie, Standard-Transportauswahl, - synthetische Codex-Katalogzeilen und die Integration des ChatGPT-Usage-Endpunkts besitzt; es - teilt dieselbe Stream-Familie `openai-responses-defaults` wie direktes OpenAI. + weiterhin auf den gemeinsamen OpenAI-Transporten läuft, aber seine Transport-/Basis-URL- + Normalisierung, OAuth-Refresh-Fallback-Richtlinie, standardmäßige Transportwahl, + synthetische Codex-Katalogzeilen und die Integration des ChatGPT-Nutzungsendpunkts besitzt; es + teilt sich dieselbe Stream-Familie `openai-responses-defaults` wie direktes OpenAI. - Google AI Studio und Gemini CLI OAuth verwenden `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` und `isModernModelRef`, weil die - Replay-Familie `google-gemini` den Fallback für Vorwärtskompatibilität von Gemini 3.1, - native Gemini-Replay-Validierung, Bootstrap-Replay-Bereinigung, den getaggten - Reasoning-Output-Modus und modernes Modell-Matching besitzt, während die + Replay-Familie `google-gemini` den Gemini-3.1-Fallback für Vorwärtskompatibilität, + native Gemini-Replay-Validierung, Bereinigung des Bootstrap-Replays, den getaggten + Modus der Reasoning-Ausgabe und modernes Modell-Matching besitzt, während die Stream-Familie `google-thinking` die Normalisierung der Gemini-Thinking-Payload besitzt; Gemini CLI OAuth verwendet außerdem `formatApiKey`, `resolveUsageAuth` und - `fetchUsageSnapshot` für Token-Formatierung, Token-Parsing und die Verdrahtung des Quota-Endpunkts. + `fetchUsageSnapshot` für Token-Formatierung, Token-Parsing und Verdrahtung des Quota-Endpunkts. - Anthropic Vertex verwendet `buildReplayPolicy` über die - Replay-Familie `anthropic-by-model`, damit Claude-spezifische Replay-Bereinigung - auf Claude-IDs begrenzt bleibt statt auf jeden `anthropic-messages`-Transport. + Replay-Familie `anthropic-by-model`, sodass Claude-spezifische Replay-Bereinigung + auf Claude-IDs beschränkt bleibt statt auf jeden Transport `anthropic-messages`. - Amazon Bedrock verwendet `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` und `resolveDefaultThinkingLevel`, weil es - Bedrock-spezifische Klassifizierung von Throttle-/Not-ready-/Kontext-Overflow-Fehlern - für Anthropic-auf-Bedrock-Datenverkehr besitzt; seine Replay-Richtlinie teilt sich weiterhin denselben - rein Claude-bezogenen Guard `anthropic-by-model`. + `classifyFailoverReason` und `resolveThinkingProfile`, weil es + die Bedrock-spezifische Klassifizierung von Throttle-/Not-ready-/Context-overflow-Fehlern + für Anthropic-on-Bedrock-Verkehr besitzt; seine Replay-Richtlinie teilt sich weiterhin denselben + ausschließlich auf Claude bezogenen Schutz `anthropic-by-model`. - OpenRouter, Kilocode, Opencode und Opencode Go verwenden `buildReplayPolicy` über die Replay-Familie `passthrough-gemini`, weil sie Gemini- - Modelle über OpenAI-kompatible Transporte proxien und eine Bereinigung der Gemini- - Thought-Signature ohne native Gemini-Replay-Validierung oder Bootstrap-Umschreibungen benötigen. + Modelle über OpenAI-kompatible Transporte proxien und Bereinigung von Gemini- + Thought-Signatures ohne native Gemini-Replay-Validierung oder + Bootstrap-Umschreibungen benötigen. - MiniMax verwendet `buildReplayPolicy` über die Replay-Familie `hybrid-anthropic-openai`, weil ein Provider sowohl - Anthropic-Messages- als auch OpenAI-kompatible Semantik besitzt; es behält das - Entfernen von Claude-Thinking-Blöcken nur auf der Anthropic-Seite bei, während der Reasoning- - Output-Modus zurück auf nativ überschrieben wird, und die Stream-Familie `minimax-fast-mode` - besitzt Umschreibungen für Fast-Mode-Modelle auf dem gemeinsamen Stream-Pfad. -- Moonshot verwendet `catalog` plus `wrapStreamFn`, weil es weiterhin den gemeinsamen - OpenAI-Transport nutzt, aber provider-eigene Normalisierung der Thinking-Payload benötigt; die - Stream-Familie `moonshot-thinking` bildet Konfiguration plus `/think`-Status auf ihre + Semantik von Anthropic-Nachrichten als auch OpenAI-kompatible Semantik besitzt; es behält das Entfernen von + ausschließlich auf Claude bezogenen Thinking-Blöcken auf der Anthropic-Seite bei, während es den + Modus der Reasoning-Ausgabe wieder auf nativ zurücksetzt, und die Stream-Familie `minimax-fast-mode` besitzt + Umschreibungen für den Fast-Modus auf dem gemeinsamen Stream-Pfad. +- Moonshot verwendet `catalog`, `resolveThinkingProfile` und `wrapStreamFn`, weil es weiterhin den gemeinsamen + OpenAI-Transport verwendet, aber provider-eigene Normalisierung der Thinking-Payload benötigt; die + Stream-Familie `moonshot-thinking` bildet Konfiguration plus `/think`-Zustand auf ihre native binäre Thinking-Payload ab. - Kilocode verwendet `catalog`, `capabilities`, `wrapStreamFn` und `isCacheTtlEligible`, weil es provider-eigene Request-Header, - Normalisierung der Reasoning-Payload, Hinweise für Gemini-Transcripts und Anthropic- - Cache-TTL-Gating benötigt; die Stream-Familie `kilocode-thinking` hält die Injektion von - Kilo-Thinking auf dem gemeinsamen Proxy-Stream-Pfad, während `kilo/auto` und - andere Proxy-Modell-IDs übersprungen werden, die keine expliziten Reasoning-Payloads unterstützen. + Normalisierung der Reasoning-Payload, Hinweise für Gemini-Transkripte und Anthropic- + Cache-TTL-Gating benötigt; die Stream-Familie `kilocode-thinking` behält Kilo-Thinking- + Injektion auf dem gemeinsamen Proxy-Stream-Pfad bei und überspringt `kilo/auto` sowie + andere Proxy-Modell-IDs, die keine expliziten Reasoning-Payloads unterstützen. - Z.AI verwendet `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, - `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` und `fetchUsageSnapshot`, weil es den GLM-5-Fallback, - Standardwerte für `tool_stream`, die UX für binäres Thinking, modernes Modell-Matching und sowohl - Usage-Auth als auch das Abrufen von Quoten besitzt; die Stream-Familie `tool-stream-default-on` - hält den standardmäßig aktivierten Wrapper für `tool_stream` aus handgeschriebenem Glue pro Provider heraus. + `isCacheTtlEligible`, `resolveThinkingProfile`, `isModernModelRef`, + `resolveUsageAuth` und `fetchUsageSnapshot`, weil es GLM-5-Fallback, + Standardwerte für `tool_stream`, binäre Thinking-UX, modernes Modell-Matching sowie sowohl + Nutzungs-Auth als auch das Abrufen von Quoten besitzt; die Stream-Familie `tool-stream-default-on` hält + den standardmäßig aktivierten `tool_stream`-Wrapper aus handgeschriebenem Klebstoff pro Provider heraus. - xAI verwendet `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` und `isModernModelRef`, - weil es die native xAI-Responses-Transportnormalisierung, Umschreibungen für Grok- - Fast-Mode-Aliase, Standard-`tool_stream`, Bereinigung strikter Tool-/Reasoning-Payloads, - Wiederverwendung von Fallback-Authentifizierung für plugin-eigene Tools, Auflösung von Grok- - Modellen mit Vorwärtskompatibilität und provider-eigene Kompatibilitäts-Patches wie das xAI-Tool-Schema- - Profil, nicht unterstützte Schema-Keywords, natives `web_search` und das Dekodieren von HTML-Entities in - Tool-Call-Argumenten besitzt. + weil es native Normalisierung des xAI-Responses-Transports, Umschreibungen von + Grok-Fast-Mode-Aliassen, standardmäßiges `tool_stream`, Bereinigung von Strict-Tool / Reasoning-Payload, + Fallback-Wiederverwendung von Authentifizierung für plugin-eigene Tools, Vorwärtskompatibilität bei der Auflösung von Grok- + Modellen und provider-eigene Compat-Patches wie das xAI-Tool-Schema- + Profil, nicht unterstützte Schema-Keywords, natives `web_search` und das Decodieren von + Tool-Call-Argumenten mit HTML-Entities besitzt. - Mistral, OpenCode Zen und OpenCode Go verwenden nur `capabilities`, um - Besonderheiten bei Transcript/Tooling aus dem Core herauszuhalten. -- Gebündelte Provider, die nur den Katalog besitzen, wie `byteplus`, `cloudflare-ai-gateway`, + Besonderheiten von Transkripten/Tools aus dem Core herauszuhalten. +- Nur-Katalog-gebündelte Provider wie `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, - `synthetic`, `together`, `venice`, `vercel-ai-gateway` und `volcengine`, verwenden + `synthetic`, `together`, `venice`, `vercel-ai-gateway` und `volcengine` verwenden nur `catalog`. -- Qwen verwendet `catalog` für seinen Text-Provider plus gemeinsame Registrierungen für Medienverständnis und - Videogenerierung für seine multimodalen Oberflächen. -- MiniMax und Xiaomi verwenden `catalog` plus Usage-Hooks, weil ihr Verhalten für `/usage` - 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 + Videoerzeugung für seine multimodalen Oberflächen. +- MiniMax und Xiaomi verwenden `catalog` plus Usage-Hooks, weil ihr `/usage`- + Verhalten plugin-eigen ist, auch wenn die Inferenz weiterhin über die gemeinsamen + Transporte läuft. -## Laufzeit-Helper +## Laufzeithelfer -Plugins können über `api.runtime` auf ausgewählte Core-Helper zugreifen. Für TTS: +Plugins können über `api.runtime` auf ausgewählte Core-Helfer zugreifen. Für TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -941,12 +934,12 @@ const voices = await api.runtime.tts.listVoices({ Hinweise: -- `textToSpeech` gibt die normale Core-TTS-Ausgabe-Payload für Datei-/Sprachnotiz-Oberflächen zurück. +- `textToSpeech` gibt die normale Core-TTS-Ausgabe-Nutzlast für Datei-/Sprachnachrichten-Oberflächen zurück. - Verwendet die Core-Konfiguration `messages.tts` und Provider-Auswahl. - Gibt PCM-Audiopuffer + Sample-Rate zurück. Plugins müssen für Provider neu sampeln/kodieren. -- `listVoices` ist je Provider optional. Verwende es für provider-eigene Voice-Picker oder Setup-Flows. -- Voice-Listen können umfangreichere Metadaten wie Locale, Geschlecht und Personality-Tags für providerbewusste Picker enthalten. -- OpenAI und ElevenLabs unterstützen heute Telephony. Microsoft nicht. +- `listVoices` ist je nach Provider optional. Verwenden Sie es für anbietereigene Voice-Picker oder Setup-Flows. +- Sprachlisten können umfangreichere Metadaten wie Locale, Geschlecht und Personality-Tags für providerbewusste Auswahllisten enthalten. +- OpenAI und ElevenLabs unterstützen heute Telefonie. Microsoft nicht. Plugins können außerdem Sprach-Provider über `api.registerSpeechProvider(...)` registrieren. @@ -968,15 +961,15 @@ api.registerSpeechProvider({ Hinweise: -- Halte TTS-Richtlinie, Fallback und Antwortzustellung im Core. -- Verwende Sprach-Provider für anbietereigenes Syntheseverhalten. -- Die Legacy-Eingabe `edge` von Microsoft wird zur Provider-ID `microsoft` normalisiert. -- Das bevorzugte Ownership-Modell ist unternehmensorientiert: Ein Anbieter-Plugin kann - Text-, Sprach-, Bild- und zukünftige Medien-Provider besitzen, sobald OpenClaw diese +- TTS-Richtlinien, Fallback und Antwortzustellung im Core belassen. +- Sprach-Provider für anbietereigenes Syntheseverhalten verwenden. +- Das Legacy-Microsoft-`edge`-Eingabefeld wird zur Provider-ID `microsoft` normalisiert. +- Das bevorzugte Zuständigkeitsmodell ist unternehmensorientiert: Ein Anbieter-Plugin kann + Text-, Sprach-, Bild- und künftige Medien-Provider besitzen, wenn OpenClaw diese Fähigkeitsverträge hinzufügt. Für Bild-/Audio-/Videoverständnis registrieren Plugins einen typisierten -Provider für Medienverständnis statt eines generischen Key/Value-Bags: +Provider für Medienverständnis statt einer generischen Key/Value-Bag: ```ts api.registerMediaUnderstandingProvider({ @@ -990,16 +983,16 @@ api.registerMediaUnderstandingProvider({ Hinweise: -- Behalte Orchestrierung, Fallback, Konfiguration und Kanal-Verdrahtung im Core. -- Behalte Anbieterverhalten im Provider-Plugin. +- Orchestrierung, Fallback, Konfiguration und Kanalverdrahtung im Core belassen. +- Anbieterverhalten im Provider-Plugin belassen. - Additive Erweiterung sollte typisiert bleiben: neue optionale Methoden, neue optionale Ergebnisfelder, neue optionale Fähigkeiten. -- Videogenerierung folgt bereits demselben Muster: - - der Core besitzt den Fähigkeitsvertrag und den Laufzeit-Helper +- Die Videoerzeugung folgt bereits demselben Muster: + - der Core besitzt den Fähigkeitsvertrag und den Laufzeithelfer - Anbieter-Plugins registrieren `api.registerVideoGenerationProvider(...)` - - Feature-/Channel-Plugins nutzen `api.runtime.videoGeneration.*` + - Feature-/Kanal-Plugins verwenden `api.runtime.videoGeneration.*` -Für Laufzeit-Helper des Medienverständnisses können Plugins Folgendes aufrufen: +Für Laufzeithelfer zum Medienverständnis können Plugins Folgendes aufrufen: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -1014,7 +1007,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Für Audio-Transkription können Plugins entweder die Laufzeit des Medienverständnisses +Für Audiotranskription können Plugins entweder die Laufzeit für Medienverständnis oder den älteren STT-Alias verwenden: ```ts @@ -1030,11 +1023,11 @@ Hinweise: - `api.runtime.mediaUnderstanding.*` ist die bevorzugte gemeinsame Oberfläche für Bild-/Audio-/Videoverständnis. -- Verwendet die Core-Audiokonfiguration für Medienverständnis (`tools.media.audio`) und die Fallback-Reihenfolge für Provider. +- Verwendet die Core-Audiokonfiguration für Medienverständnis (`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 erhalten. +- `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-Durchläufe über `api.runtime.subagent` starten: ```ts const result = await api.runtime.subagent.run({ @@ -1048,14 +1041,14 @@ const result = await api.runtime.subagent.run({ Hinweise: -- `provider` und `model` sind optionale Overrides pro Lauf, keine persistenten Sitzungsänderungen. -- OpenClaw berücksichtigt diese Override-Felder nur für vertrauenswürdige Aufrufer. -- Für plugin-eigene Fallback-Läufe müssen Operatoren mit `plugins.entries..subagent.allowModelOverride: true` zustimmen. -- Verwende `plugins.entries..subagent.allowedModels`, um vertrauenswürdige Plugins auf bestimmte kanonische Ziele `provider/model` zu beschränken, oder `"*"`, um jedes Ziel ausdrücklich zu erlauben. -- Nicht vertrauenswürdige Subagent-Läufe von Plugins funktionieren weiterhin, aber Override-Anfragen werden abgelehnt, statt stillschweigend auf Fallback zurückzufallen. +- `provider` und `model` sind optionale Überschreibungen pro Durchlauf, keine dauerhaften Sitzungsänderungen. +- OpenClaw berücksichtigt diese Überschreibungsfelder nur für vertrauenswürdige Aufrufer. +- Für plugin-eigene Fallback-Durchläufe müssen Betreiber mit `plugins.entries..subagent.allowModelOverride: true` zustimmen. +- Verwenden Sie `plugins.entries..subagent.allowedModels`, um vertrauenswürdige Plugins auf bestimmte kanonische Ziele `provider/model` zu beschränken, oder `"*"`, um jedes Ziel ausdrücklich zu erlauben. +- Nicht vertrauenswürdige Subagent-Durchläufe von Plugins funktionieren weiterhin, aber Überschreibungsanfragen werden abgelehnt, anstatt stillschweigend auf Fallback zurückzufallen. -Für Websuche können Plugins den gemeinsamen Laufzeit-Helper verwenden, statt -in die Tool-Verdrahtung des Agents einzugreifen: +Für Websuche können Plugins den gemeinsamen Laufzeithelfer nutzen, anstatt +in die Verdrahtung des Agent-Tools zu greifen: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1071,14 +1064,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugins können Websuch-Provider auch über +Plugins können Websuch-Provider außerdem über `api.registerWebSearchProvider(...)` registrieren. Hinweise: -- Behalte Providerauswahl, Auflösung von Anmeldedaten und gemeinsame Request-Semantik im Core. -- Verwende Websuch-Provider für anbieterspezifische Suchtransporte. -- `api.runtime.webSearch.*` ist die bevorzugte gemeinsame Oberfläche für Feature-/Channel-Plugins, die Suchverhalten benötigen, ohne von dem Agent-Tool-Wrapper abzuhängen. +- Provider-Auswahl, Auflösung von Credentials und gemeinsame Anforderungssemantik im Core belassen. +- Websuch-Provider für anbieterspezifische Suchtransporte verwenden. +- `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 abzuhängen. ### `api.runtime.imageGeneration` @@ -1093,8 +1086,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: ein Bild mit der konfigurierten Provider-Kette für Bildgenerierung erzeugen. -- `listProviders(...)`: verfügbare Provider für Bildgenerierung und ihre Fähigkeiten auflisten. +- `generate(...)`: ein Bild mit der konfigurierten Provider-Kette für Bilderzeugung erzeugen. +- `listProviders(...)`: verfügbare Provider für Bilderzeugung und ihre Fähigkeiten auflisten. ## Gateway-HTTP-Routen @@ -1116,34 +1109,34 @@ api.registerHttpRoute({ Routenfelder: - `path`: Routenpfad unter dem Gateway-HTTP-Server. -- `auth`: erforderlich. Verwende `"gateway"`, um normale Gateway-Authentifizierung zu verlangen, oder `"plugin"` für pluginverwaltete Authentifizierung/Webhook-Verifizierung. +- `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. - `handler`: `true` zurückgeben, wenn die Route die Anfrage verarbeitet hat. Hinweise: -- `api.registerHttpHandler(...)` wurde entfernt und verursacht einen Fehler beim Laden des Plugins. Verwende stattdessen `api.registerHttpRoute(...)`. -- Plugin-Routen müssen `auth` ausdrücklich deklarieren. -- Konflikte bei exakt gleichem `path + match` werden abgelehnt, sofern nicht `replaceExisting: true` gesetzt ist, und ein Plugin kann die Route eines anderen Plugins nicht ersetzen. -- Überlappende Routen mit unterschiedlichen `auth`-Stufen werden abgelehnt. Halte Fallthrough-Ketten mit `exact`/`prefix` nur auf derselben `auth`-Stufe. -- Routen mit `auth: "plugin"` erhalten **nicht** automatisch Runtime-Scopes für Operatoren. Sie sind für pluginverwaltete Webhooks/Signaturverifizierung gedacht, nicht für privilegierte Gateway-Helper-Aufrufe. -- Routen mit `auth: "gateway"` laufen innerhalb eines Gateway-Request-Runtime-Scopes, aber dieser Scope ist absichtlich konservativ: - - Shared-Secret-Bearer-Authentifizierung (`gateway.auth.mode = "token"` / `"password"`) hält Runtime-Scopes für Plugin-Routen auf `operator.write` fest, selbst wenn der Aufrufer `x-openclaw-scopes` sendet - - vertrauenswürdige HTTP-Modi mit identitätsbezogenen Daten (zum Beispiel `trusted-proxy` oder `gateway.auth.mode = "none"` auf einem privaten Ingress) berücksichtigen `x-openclaw-scopes` nur dann, wenn der Header ausdrücklich vorhanden ist - - wenn `x-openclaw-scopes` bei solchen identitätsbezogenen Plugin-Routen-Anfragen fehlt, fällt der Runtime-Scope auf `operator.write` zurück -- Praktische Regel: Gehe nicht davon aus, dass eine gateway-auth-Plugin-Route implizit eine Admin-Oberfläche ist. Wenn deine Route Verhalten nur für Administratoren benötigt, verlange einen identitätsbezogenen Auth-Modus und dokumentiere den ausdrücklichen Header-Vertrag für `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` wurde entfernt und verursacht einen Fehler beim Laden des Plugins. Verwenden Sie stattdessen `api.registerHttpRoute(...)`. +- Plugin-Routen müssen `auth` explizit deklarieren. +- Exakte Konflikte bei `path + match` werden abgelehnt, sofern nicht `replaceExisting: true` gesetzt ist, und ein Plugin kann die Route eines anderen Plugins nicht ersetzen. +- Sich überschneidende Routen mit unterschiedlichen `auth`-Stufen werden abgelehnt. `exact`-/`prefix`-Fallthrough-Ketten nur innerhalb derselben `auth`-Stufe beibehalten. +- Routen mit `auth: "plugin"` erhalten **nicht** automatisch Runtime-Scopes des Operators. Sie sind für pluginverwaltete Webhooks/Signaturverifizierung gedacht, nicht für privilegierte Gateway-Helferaufrufe. +- Routen mit `auth: "gateway"` laufen innerhalb eines Gateway-Anfrage-Runtime-Scopes, aber dieser Scope ist absichtlich konservativ: + - Shared-Secret-Bearer-Authentifizierung (`gateway.auth.mode = "token"` / `"password"`) hält Runtime-Scopes von Plugin-Routen auf `operator.write` fest, selbst wenn der Aufrufer `x-openclaw-scopes` sendet + - vertrauenswürdige HTTP-Modi mit Identitätsträger (zum Beispiel `trusted-proxy` oder `gateway.auth.mode = "none"` auf einem privaten Ingress) berücksichtigen `x-openclaw-scopes` nur, wenn der Header ausdrücklich vorhanden ist + - wenn `x-openclaw-scopes` bei diesen identitätstragenden Plugin-Routenanfragen fehlt, fällt der Runtime-Scope auf `operator.write` zurück +- Praktische Regel: Gehen Sie nicht davon aus, dass eine pluginseitige Route mit Gateway-Authentifizierung implizit eine Admin-Oberfläche ist. Wenn Ihre Route Verhalten nur für Administratoren benötigt, verlangen Sie einen HTTP-Modus mit Identitätsträger und dokumentieren Sie den expliziten Header-Vertrag `x-openclaw-scopes`. -## Importpfade des Plugin SDK +## SDK-Importpfade für Plugins -Verwende SDK-Subpaths statt des monolithischen Imports `openclaw/plugin-sdk`, -wenn du Plugins entwickelst: +Verwenden Sie SDK-Subpfade statt des monolithischen Imports `openclaw/plugin-sdk`, wenn +Sie Plugins erstellen: -- `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 Root-`openclaw.json` - (`OpenClawSchema`). -- Stabile Channel-Primitiven wie `openclaw/plugin-sdk/channel-setup`, +- `openclaw/plugin-sdk/plugin-entry` für Plugin-Registrierungsprimitiven. +- `openclaw/plugin-sdk/core` für den generischen gemeinsamen, pluginseitigen Vertrag. +- `openclaw/plugin-sdk/config-schema` für den Export des Zod-Schemas + des Wurzel-`openclaw.json` (`OpenClawSchema`). +- Stabile Kanalprimitiven wie `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1156,17 +1149,17 @@ wenn du Plugins entwickelst: `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` und `openclaw/plugin-sdk/webhook-ingress` für gemeinsame Verdrahtung von Setup/Auth/Antwort/Webhook. - `channel-inbound` ist die gemeinsame Heimat für Debounce, Mention-Matching, - Helper für eingehende Mention-Richtlinien, Envelope-Formatierung und - Kontext-Helper für eingehende Envelopes. - `channel-setup` ist die schmale optionale Setup-Seam für Installationen. + `channel-inbound` ist die gemeinsame Heimat für Entprellung, Mention-Matching, + Hilfen für eingehende Mention-Richtlinien, Umschlagformatierung und Hilfen zum + Kontext eingehender Umschläge. + `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 envbewusste Adapter-Seam für Account-Setup. - `setup-tools` ist die kleine Helper-Seam für CLI/Archive/Dokumentation (`formatCliCommand`, + `setup-adapter-runtime` ist die env-bewusste Adapter-Seam für Konto-Setup. + `setup-tools` ist die kleine CLI-/Archiv-/Dokumentations-Helfer-Seam (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Domänen-Subpaths wie `openclaw/plugin-sdk/channel-config-helpers`, +- Bereichs-Subpfade wie `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1184,128 +1177,128 @@ wenn du Plugins entwickelst: `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-Helper. - `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 + `openclaw/plugin-sdk/directory-runtime` für gemeinsame Laufzeit-/Konfigurationshelfer. + `telegram-command-config` ist die schmale öffentliche Seam für Telegram-spezifische + Normalisierung/Validierung benutzerdefinierter 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 für den Assistant sichtbaren Texts, Render-/Chunking-Helpern für Markdown, Redaction- - Helpern, Helpern für Directive-Tags und Safe-Text-Dienstprogrammen. -- Kanalspezifische Seams für Genehmigungen sollten einen einzigen Vertrag `approvalCapability` - auf dem Plugin bevorzugen. Der Core liest dann Authentifizierung, Zustellung, Rendering, - natives Routing und Lazy-Verhalten nativer Handler für Genehmigungen über diese eine Fähigkeit, - statt Genehmigungsverhalten in nicht zusammenhängende Plugin-Felder zu mischen. + `text-runtime` ist die gemeinsame Seam für Text/Markdown/Logging, einschließlich + des Entfernens von für Assistenten sichtbarem Text, Hilfen zum Rendern/Chunking von Markdown, Redaktions- + Hilfen, Hilfen für Directive-Tags und Safe-Text-Dienstprogrammen. +- Kanalspezifische Seams für Genehmigungen sollten einen einzelnen `approvalCapability`- + Vertrag auf dem Plugin bevorzugen. Der Core liest dann Authentifizierung, Zustellung, Rendering, + natives Routing und das Verhalten des lazy nativen Handlers für Genehmigungen über diese eine Fähigkeit, + anstatt Genehmigungsverhalten in nicht zusammenhängende Plugin-Felder zu mischen. - `openclaw/plugin-sdk/channel-runtime` ist veraltet und bleibt nur als - Kompatibilitäts-Shim für ältere Plugins erhalten. Neuer Code sollte stattdessen die engeren + Kompatibilitäts-Shim für ältere Plugins bestehen. Neuer Code sollte stattdessen die schmaleren generischen Primitiven importieren, und Repo-Code sollte keine neuen Importe des - Shim hinzufügen. -- Gebündelte Extension-Interna bleiben privat. Externe Plugins sollten nur - `openclaw/plugin-sdk/*`-Subpaths verwenden. OpenClaw-Core-/Test-Code darf die repo- - öffentlichen Einstiegspunkte unter einem Plugin-Paket-Root verwenden, etwa `index.js`, `api.js`, + Shims hinzufügen. +- Interne Bestandteile gebündelter Erweiterungen bleiben privat. Externe Plugins sollten nur + `openclaw/plugin-sdk/*`-Subpfade verwenden. OpenClaw-Core-/Test-Code kann die öffentlichen + Repo-Einstiegspunkte unter einer Plugin-Paketwurzel wie `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js` und eng begrenzte Dateien wie - `login-qr-api.js`. Importiere niemals `src/*` eines Plugin-Pakets aus dem Core oder aus - einer anderen Extension. + `login-qr-api.js` verwenden. Niemals `src/*` eines Plugin-Pakets aus dem Core oder aus + einer anderen Erweiterung importieren. - Aufteilung der Repo-Einstiegspunkte: - `/api.js` ist das Barrel für Helper/Typen, - `/runtime-api.js` ist das reine Runtime-Barrel, - `/index.js` ist der Einstiegspunkt des gebündelten Plugins - und `/setup-entry.js` ist der Setup-Einstiegspunkt des Plugins. + `/api.js` ist das Barrel für Helfer/Typen, + `/runtime-api.js` ist das Barrel nur für Laufzeit, + `/index.js` ist der Einstiegspunkt für das gebündelte Plugin, + und `/setup-entry.js` ist der Einstiegspunkt für das Setup-Plugin. - 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 das Parsing von `service_tier`. - - OpenAI verwendet `api.js` für Provider-Builder, Helper für Standardmodelle und - Builder für Echtzeit-Provider. - - OpenRouter verwendet `api.js` für seinen Provider-Builder plus Onboarding-/Konfigurations- - Helper, während `register.runtime.js` weiterhin generische - `plugin-sdk/provider-stream`-Helper zur repo-lokalen Verwendung re-exportieren kann. -- Öffentlich zugängliche Einstiegspunkte, die über Facades geladen werden, bevorzugen den aktiven Laufzeit-Snapshot der Konfiguration, - wenn einer existiert, und fallen sonst auf die auf dem Datenträger 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 Helper-Seams mit Branding gebündelter Kanäle existiert weiterhin. Behandle diese als - Seams für Wartung/Kompatibilität gebündelter Plugins, nicht als neue Importziele für Drittanbieter; neue kanalübergreifende Verträge sollten weiterhin auf - generischen `plugin-sdk/*`-Subpaths oder den pluginlokalen Barrels `api.js` / + - Anthropic verwendet `api.js` / `contract-api.js` für Claude-Stream-Hilfen wie + `wrapAnthropicProviderStream`, Hilfen für Beta-Header und Parsing von `service_tier`. + - OpenAI verwendet `api.js` für Provider-Builder, Hilfen für Standardmodelle und + Builder für Realtime-Provider. + - OpenRouter verwendet `api.js` für seinen Provider-Builder sowie Hilfen für Onboarding/Konfiguration, + während `register.runtime.js` für repo-lokale Nutzung weiterhin generische + `plugin-sdk/provider-stream`-Hilfen re-exportieren kann. +- Öffentlich zugängliche Einstiegspunkte, die über eine Fassade geladen werden, bevorzugen den aktiven Runtime-Snapshot der Konfiguration, + wenn einer vorhanden ist, und greifen sonst auf die auf der Festplatte aufgelöste Konfigurationsdatei zurück, wenn + OpenClaw noch keinen Runtime-Snapshot bereitstellt. +- Generische gemeinsame Primitive bleiben der bevorzugte öffentliche SDK-Vertrag. Ein kleiner + reservierter Kompatibilitätssatz gebündelter, kanalgebrandeter Hilfs-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/*`-Subpfaden oder den pluginlokalen Barrels `api.js` / `runtime-api.js` landen. -Kompatibilitätshinweis: +Hinweis zur Kompatibilität: -- Vermeide für neuen Code das Root-Barrel `openclaw/plugin-sdk`. -- Bevorzuge zuerst die schmalen stabilen Primitiven. Die neueren Subpaths für setup/pairing/reply/ - feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool sind der beabsichtigte Vertrag für neue +- Vermeiden Sie das Root-Barrel `openclaw/plugin-sdk` für neuen Code. +- Bevorzugen Sie zuerst die schmalen stabilen Primitive. Die neueren Setup-/Pairing-/Reply-/ + Feedback-/Contract-/Inbound-/Threading-/Command-/Secret-input-/Webhook-/Infra-/ + Allowlist-/Status-/Message-tool-Subpfade sind der beabsichtigte Vertrag für neue gebündelte und externe Plugin-Arbeit. - Parsing/Matching von Zielen gehört auf `openclaw/plugin-sdk/channel-targets`. - Gates für Message-Aktionen und Reaction-Helper für Message-IDs gehören auf + Ziel-Parsing/-Matching gehört zu `openclaw/plugin-sdk/channel-targets`. + Gates für Nachrichtenaktionen und Hilfen für Reaktions-Nachrichten-IDs gehören zu `openclaw/plugin-sdk/channel-actions`. -- Helper-Barrels, die spezifisch für gebündelte Extensions sind, sind standardmäßig nicht stabil. Wenn ein - Helper nur von einer gebündelten Extension benötigt wird, behalte ihn hinter der - lokalen Seam `api.js` oder `runtime-api.js` der Extension, statt ihn in - `openclaw/plugin-sdk/` hochzustufen. -- Neue gemeinsame Helper-Seams sollten generisch sein, nicht kanalgebrandet. Gemeinsames Parsing von Zielen - gehört auf `openclaw/plugin-sdk/channel-targets`; kanalspezifische +- Hilfs-Barrels, die spezifisch für gebündelte Erweiterungen sind, sind standardmäßig nicht stabil. Wenn ein + Helfer nur von einer gebündelten Erweiterung benötigt wird, behalten Sie ihn hinter der + lokalen Seam `api.js` oder `runtime-api.js` der Erweiterung, statt ihn in + `openclaw/plugin-sdk/` zu befördern. +- Neue gemeinsame Helper-Seams sollten generisch sein, nicht kanalgebrandet. Gemeinsames Ziel- + Parsing gehört zu `openclaw/plugin-sdk/channel-targets`; kanalspezifische Interna bleiben hinter der lokalen Seam `api.js` oder `runtime-api.js` des besitzenden Plugins. -- Fähigkeitsspezifische Subpaths wie `image-generation`, +- Fähigkeitsspezifische Subpfade 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 für sich genommen nicht, dass jeder exportierte Helfer ein langfristig eingefrorener externer Vertrag ist. -## Schemas für Message-Tools +## Nachrichtentool-Schemas -Plugins sollten kanalspezifische Schema-Beiträge für `describeMessageTool(...)` -besitzen. Behalte providerspezifische Felder im Plugin, nicht im gemeinsamen Core. +Plugins sollten kanalspezifische Schemabeiträge für `describeMessageTool(...)` +besitzen. Providerspezifische Felder im Plugin behalten, nicht im gemeinsamen Core. -Für gemeinsame portable Schema-Fragmente verwende die generischen Helper wieder, die über -`openclaw/plugin-sdk/channel-actions` exportiert werden: +Für gemeinsam portable Schemafragmente die über +`openclaw/plugin-sdk/channel-actions` exportierten generischen Helfer wiederverwenden: -- `createMessageToolButtonsSchema()` für Payloads im Stil eines Button-Rasters -- `createMessageToolCardSchema()` für strukturierte Card-Payloads +- `createMessageToolButtonsSchema()` für Payloads im Stil von Button-Rastern +- `createMessageToolCardSchema()` für strukturierte Karten-Payloads -Wenn eine Schema-Form nur für einen Provider sinnvoll ist, definiere sie in den -eigenen Quelldateien dieses Plugins, statt sie in das gemeinsame SDK hochzustufen. +Wenn eine Schemaform nur für einen Provider sinnvoll ist, definieren Sie sie in der +eigenen Quelle dieses Plugins, statt sie in das gemeinsame SDK zu befördern. -## Auflösung von Channel-Zielen +## Auflösung von Kanalzielen -Channel-Plugins sollten kanalspezifische Zielsemantik besitzen. Halte den gemeinsamen -ausgehenden Host generisch und verwende die Oberfläche des Messaging-Adapters für Provider-Regeln: +Kanal-Plugins sollten kanalspezifische Zielsemantik besitzen. Den gemeinsamen +ausgehenden Host generisch halten und die Oberfläche des Messaging-Adapters für Provider-Regeln verwenden: - `messaging.inferTargetChatType({ to })` entscheidet, ob ein normalisiertes Ziel - als `direct`, `group` oder `channel` behandelt werden soll, bevor eine Verzeichnissuche erfolgt. + vor dem Directory-Lookup als `direct`, `group` oder `channel` behandelt werden soll. - `messaging.targetResolver.looksLikeId(raw, normalized)` teilt dem Core mit, ob eine - Eingabe direkt zur idartigen Auflösung springen soll statt zur Verzeichnissuche. -- `messaging.targetResolver.resolveTarget(...)` ist der Plugin-Fallback, wenn - der Core nach der Normalisierung oder nach einem Verzeichnis-Fehltreffer eine endgültige provider-eigene Auflösung benötigt. -- `messaging.resolveOutboundSessionRoute(...)` besitzt den providerspezifischen Sitzungs- - Routenaufbau, sobald ein Ziel aufgelöst ist. + Eingabe direkt zur id-ähnlichen Auflösung springen soll statt zur Directory-Suche. +- `messaging.targetResolver.resolveTarget(...)` ist der Plugin-Fallback, wenn der + Core nach der Normalisierung oder nach einem Directory-Miss eine abschließende provider-eigene Auflösung benötigt. +- `messaging.resolveOutboundSessionRoute(...)` besitzt die providerspezifische Sitzungs- + Routen-Konstruktion, sobald ein Ziel aufgelöst ist. Empfohlene Aufteilung: -- Verwende `inferTargetChatType` für Kategorieentscheidungen, die vor der - Suche nach Peers/Gruppen stattfinden sollten. -- Verwende `looksLikeId` für Prüfungen vom Typ „als explizite/native Ziel-ID behandeln“. -- Verwende `resolveTarget` für providerspezifische Normalisierungs-Fallbacks, nicht für - breite Verzeichnissuche. -- Halte provider-native IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum- - IDs innerhalb von `target`-Werten oder providerspezifischen Parametern, nicht in generischen SDK- +- `inferTargetChatType` für Kategorieentscheidungen verwenden, die vor dem + Durchsuchen von Peers/Gruppen erfolgen sollten. +- `looksLikeId` für Prüfungen im Stil „dies als explizite/native Ziel-ID behandeln“ verwenden. +- `resolveTarget` für providerspezifischen Normalisierungs-Fallback verwenden, nicht für + breite Directory-Suche. +- Provider-native IDs wie Chat-IDs, Thread-IDs, JIDs, Handles und Raum- + IDs innerhalb von `target`-Werten oder providerspezifischen Parametern halten, nicht in generischen SDK- Feldern. -## Konfigurationsgestützte Verzeichnisse +## Konfigurationsgestützte Directories -Plugins, die Verzeichniseinträge aus der Konfiguration ableiten, sollten diese Logik im -Plugin halten und die gemeinsamen Helper aus +Plugins, die Directory-Einträge aus der Konfiguration ableiten, sollten diese Logik im +Plugin behalten und die gemeinsamen Helfer aus `openclaw/plugin-sdk/directory-runtime` wiederverwenden. -Verwende dies, wenn ein Kanal konfigurationsgestützte Peers/Gruppen benötigt, etwa: +Verwenden Sie dies, wenn ein Kanal konfigurationsgestützte Peers/Gruppen benötigt, wie etwa: -- DM-Peers auf Basis von Allowlists -- konfigurierte Kanal-/Gruppenzuordnungen -- kontobezogene statische Verzeichnis-Fallbacks +- durch Allowlist gesteuerte DM-Peers +- konfigurierte Kanal-/Gruppen-Maps +- kontoabhängige statische Directory-Fallbacks -Die gemeinsamen Helper in `directory-runtime` behandeln nur generische Operationen: +Die gemeinsamen Helfer in `directory-runtime` verarbeiten nur generische Operationen: -- Filtern von Abfragen -- Anwenden von Limits -- Helper für Deduplizierung/Normalisierung -- Erzeugen von `ChannelDirectoryEntry[]` +- Query-Filterung +- Anwendung von Limits +- Helfer für Deduplizierung/Normalisierung +- Aufbau von `ChannelDirectoryEntry[]` Kanalspezifische Kontoprüfung und ID-Normalisierung sollten in der Plugin-Implementierung bleiben. @@ -1318,63 +1311,63 @@ Provider-Plugins können Modellkataloge für Inferenz definieren mit `catalog.run(...)` gibt dieselbe Form zurück, die OpenClaw in `models.providers` schreibt: -- `{ provider }` für einen Providereintrag -- `{ providers }` für mehrere Providereinträge +- `{ provider }` für einen einzelnen Provider-Eintrag +- `{ providers }` für mehrere Provider-Einträge -Verwende `catalog`, wenn das Plugin providerspezifische Modell-IDs, Standardwerte für `baseUrl` -oder authgesteuerte Modellmetadaten besitzt. +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 eingebauten impliziten Providern von OpenClaw zusammengeführt wird: -- `simple`: einfache Provider mit API-Key oder envgesteuert +- `simple`: einfache API-Key- oder env-gesteuerte Provider - `profile`: Provider, die erscheinen, wenn Auth-Profile existieren -- `paired`: Provider, die mehrere zusammenhängende Providereinträge synthetisieren -- `late`: letzter Durchlauf, nach anderen impliziten Providern +- `paired`: Provider, die mehrere verwandte Provider-Einträge synthetisieren +- `late`: letzter Durchlauf nach anderen impliziten Providern -Spätere Provider gewinnen bei Schlüsselkonflikten, sodass Plugins absichtlich einen -eingebauten Providereintrag mit derselben Provider-ID überschreiben können. +Spätere Provider gewinnen bei Schlüsselkollisionen, sodass Plugins absichtlich einen +eingebauten Provider-Eintrag mit derselben Provider-ID überschreiben können. Kompatibilität: - `discovery` funktioniert weiterhin als Legacy-Alias - wenn sowohl `catalog` als auch `discovery` registriert sind, verwendet OpenClaw `catalog` -## Schreibgeschützte Channel-Inspektion +## Schreibgeschützte Kanalinspektion -Wenn dein Plugin einen Kanal registriert, bevorzuge die Implementierung von -`plugin.config.inspectAccount(cfg, accountId)` neben `resolveAccount(...)`. +Wenn Ihr Plugin einen Kanal registriert, bevorzugen Sie die Implementierung von +`plugin.config.inspectAccount(cfg, accountId)` zusammen mit `resolveAccount(...)`. Warum: -- `resolveAccount(...)` ist der Laufzeitpfad. Er darf annehmen, dass Anmeldedaten - vollständig materialisiert sind, und schnell fehlschlagen, wenn erforderliche Secrets fehlen. +- `resolveAccount(...)` ist der Laufzeitpfad. Er darf annehmen, dass Credentials + vollständig materialisiert sind, und kann schnell fehlschlagen, wenn erforderliche Geheimnisse fehlen. - Schreibgeschützte Befehlspfade wie `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` sowie doctor-/config- - Reparaturabläufe sollten Laufzeit-Anmeldedaten nicht materialisieren müssen, nur um + `openclaw channels status`, `openclaw channels resolve` und Doctor-/Konfigurations- + Reparatur-Flows sollten keine Laufzeit-Credentials materialisieren müssen, nur um die Konfiguration zu beschreiben. Empfohlenes Verhalten für `inspectAccount(...)`: -- Nur beschreibenden Kontostatus zurückgeben. +- Nur den beschreibenden Kontozustand zurückgeben. - `enabled` und `configured` beibehalten. -- Felder für Herkunft/Status von Anmeldedaten einbeziehen, wenn relevant, etwa: +- Relevante Felder zur Credential-Quelle/zum Credential-Status einschließen, etwa: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Du musst keine rohen Token-Werte zurückgeben, nur um schreibgeschützte - Verfügbarkeit zu melden. `tokenStatus: "available"` zurückzugeben (und das passende Herkunftsfeld) - reicht für Befehle im Stil von Status aus. -- Verwende `configured_unavailable`, wenn Anmeldedaten über SecretRef konfiguriert, aber - im aktuellen Befehlspfad nicht verfügbar sind. +- Sie müssen keine rohen Token-Werte zurückgeben, nur um schreibgeschützte + Verfügbarkeit zu melden. Es reicht, `tokenStatus: "available"` (und das passende Quellenfeld) + für statusartige Befehle zurückzugeben. +- `configured_unavailable` verwenden, wenn ein Credential über SecretRef konfiguriert ist, aber + im aktuellen Befehlspfad nicht verfügbar ist. -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 auszuweisen. +So können schreibgeschützte Befehle „konfiguriert, aber in diesem Befehlspfad nicht verfügbar“ +melden, statt abzustürzen oder das Konto fälschlich als nicht konfiguriert zu melden. -## Package-Packs +## Paket-Packs -Ein Plugin-Verzeichnis kann eine `package.json` mit `openclaw.extensions` enthalten: +Ein Plugin-Verzeichnis kann ein `package.json` mit `openclaw.extensions` enthalten: ```json { @@ -1386,65 +1379,66 @@ Ein Plugin-Verzeichnis kann eine `package.json` mit `openclaw.extensions` enthal } ``` -Jeder Eintrag wird zu einem Plugin. Wenn das Pack mehrere Extensions aufführt, wird die Plugin-ID +Jeder Eintrag wird zu einem Plugin. Wenn das Pack mehrere Erweiterungen auflistet, wird die Plugin-ID zu `name/`. -Wenn dein Plugin npm-Abhängigkeiten importiert, installiere 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 Auflösung von Symlinks innerhalb des Plugin- -Verzeichnisses bleiben. Einträge, die aus dem Paketverzeichnis ausbrechen, werden +Sicherheitsleitplanke: Jeder Eintrag in `openclaw.extensions` muss nach der Auflösung von Symlinks innerhalb des Plugin- +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). Halte die Abhängigkeits- -Bäume von Plugins „reines JS/TS“ und vermeide Pakete, die `postinstall`-Builds benötigen. +`npm install --omit=dev --ignore-scripts` (keine Lifecycle-Skripte, keine Dev-Abhängigkeiten zur Laufzeit). Halten Sie Bäume von Plugin-Abhängigkeiten +„pure JS/TS“ und vermeiden Sie Pakete, die `postinstall`-Builds benötigen. -Optional: `openclaw.setupEntry` kann auf ein leichtgewichtiges, nur für Setup bestimmtes Modul zeigen. -Wenn OpenClaw Setup-Oberflächen für ein deaktiviertes Channel-Plugin benötigt oder -wenn ein Channel-Plugin aktiviert, aber noch nicht konfiguriert ist, lädt es `setupEntry` -statt des vollständigen Plugin-Einstiegspunkts. So bleiben Start und Setup leichter, -wenn dein Haupteinstiegspunkt auch Tools, Hooks oder anderen nur zur Laufzeit benötigten -Code verdrahtet. +Optional: `openclaw.setupEntry` kann auf ein leichtgewichtiges reines Setup-Modul 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` +anstelle des vollständigen Plugin-Einstiegspunkts. Das hält Start und Setup leichter, +wenn Ihr Haupteinstiegspunkt auch Tools, Hooks oder anderen Code nur für die Laufzeit +verdrahtet. Optional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -kann ein Channel-Plugin auch dann in denselben `setupEntry`-Pfad einbinden, wenn der Kanal bereits -konfiguriert ist, und zwar während der Pre-Listen-Startphase des Gateways. +kann ein Kanal-Plugin in denselben `setupEntry`-Pfad während der +Pre-Listen-Startphase des Gateways aufnehmen, selbst wenn der Kanal bereits konfiguriert ist. -Verwende dies nur, wenn `setupEntry` die gesamte Startoberfläche vollständig abdeckt, die -vor dem Starten des Gateway-Listenings existieren muss. In der Praxis bedeutet das, dass der Setup-Einstiegspunkt -jede kanal-eigene Fähigkeit registrieren muss, von der der Start abhängt, etwa: +Verwenden Sie dies nur, wenn `setupEntry` die Startoberfläche, die +vor dem Start des Gateway-Listenings existieren muss, vollständig abdeckt. In der Praxis bedeutet das, dass der +Setup-Eintrag jede kanalbesessene Fähigkeit registrieren muss, von der der Start abhängt, etwa: - die Kanalregistrierung selbst -- alle HTTP-Routen, die verfügbar sein müssen, bevor das Gateway auf Listening geht -- alle Gateway-Methoden, Tools oder Dienste, die in demselben Zeitraum existieren müssen +- alle HTTP-Routen, die verfügbar sein müssen, bevor das Gateway auf eingehende Verbindungen lauscht +- alle Gateway-Methoden, Tools oder Dienste, die in demselben Zeitfenster existieren müssen -Wenn dein vollständiger Einstiegspunkt weiterhin eine erforderliche Startfähigkeit besitzt, aktiviere -dieses Flag nicht. Behalte das Standardverhalten des Plugins und lasse OpenClaw während des -Starts den vollständigen Einstiegspunkt laden. +Wenn Ihr vollständiger Eintrag weiterhin eine erforderliche Startfähigkeit besitzt, aktivieren Sie +dieses Flag nicht. Behalten Sie das Plugin beim Standardverhalten und lassen Sie OpenClaw den +vollständigen Eintrag beim Start laden. -Gebündelte Kanäle können außerdem Setup-only-Helper für Vertragsoberflächen veröffentlichen, die der Core -konsultieren kann, bevor die vollständige Kanal-Laufzeit geladen ist. Die aktuelle Setup- -Promotion-Oberfläche ist: +Gebündelte Kanäle können auch reine Setup-Helfer für die Vertragsoberfläche veröffentlichen, die der Core +konsultieren kann, bevor die vollständige Kanal-Laufzeit geladen wird. Die aktuelle Oberfläche +für Setup-Promotion ist: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Der Core verwendet diese Oberfläche, wenn eine Legacy-Einzelkonto-Kanal- -Konfiguration in `channels..accounts.*` hochgestuft werden muss, ohne den vollständigen Plugin-Einstiegspunkt zu laden. +Der Core verwendet diese Oberfläche, wenn er eine Legacy-Konfiguration eines einzelnen Kontos +nach `channels..accounts.*` befördern muss, ohne den vollständigen Plugin-Eintrag 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 kann einen -konfigurierten nicht-kanonischen Standardkonto-Schlüssel beibehalten, statt immer -`accounts.default` zu erstellen. +benanntes befördertes Konto, wenn bereits benannte Konten existieren, und kann einen +konfigurierten nicht kanonischen Standard-Kontoschlüssel beibehalten, statt immer +`accounts.default` zu erzeugen. -Diese Setup-Patch-Adapter halten die Discovery der gebündelten Vertragsoberfläche lazy. Die Import- -Zeit bleibt leicht; die Promotion-Oberfläche wird erst bei der ersten Verwendung geladen, statt den Start gebündelter Kanäle beim Modulimport erneut auszuführen. +Diese Setup-Patch-Adapter halten die Erkennung der gebündelten Vertragsoberfläche lazy. Die Importzeit +bleibt gering; die Promotionsoberfläche wird nur bei der ersten Verwendung geladen, statt beim Modulimport +erneut in den Start des gebündelten Kanals einzutreten. -Wenn diese Startoberflächen Gateway-RPC-Methoden enthalten, halte sie auf einem +Wenn diese Startoberflächen Gateway-RPC-Methoden enthalten, behalten Sie diese auf einem pluginspezifischen Präfix. Core-Admin-Namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) bleiben reserviert und werden immer -zu `operator.admin` aufgelöst, selbst wenn ein Plugin einen engeren Scope anfordert. +zu `operator.admin` aufgelöst, auch wenn ein Plugin einen engeren Scope anfordert. Beispiel: @@ -1461,10 +1455,10 @@ Beispiel: } ``` -### Metadaten des Channel-Katalogs +### Metadaten des Kanalkatalogs -Channel-Plugins können Setup-/Discovery-Metadaten über `openclaw.channel` und -Installationshinweise über `openclaw.install` bekannt machen. Dadurch bleibt der Core-Katalog datenfrei. +Kanal-Plugins können Metadaten für Setup/Erkennung über `openclaw.channel` und +Installationshinweise über `openclaw.install` bekannt geben. So bleiben die Core-Katalogdaten frei von Daten. Beispiel: @@ -1492,41 +1486,41 @@ Beispiel: } ``` -Nützliche Felder in `openclaw.channel` über das Minimalbeispiel hinaus: +Nützliche Felder von `openclaw.channel` über das minimale Beispiel hinaus: - `detailLabel`: sekundäres Label für umfangreichere Katalog-/Statusoberflächen - `docsLabel`: überschreibt den Linktext für den Doku-Link -- `preferOver`: Plugin-/Kanal-IDs mit niedrigerer Priorität, die dieser Katalogeintrag übertreffen soll -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: Steuerelemente für Copy auf Auswahloberflächen -- `markdownCapable`: markiert den Kanal als markdownfähig für Entscheidungen zur ausgehenden Formatierung -- `exposure.configured`: blendet den Kanal aus Oberflächen für konfigurierte Kanäle 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 Doku-Navigationsoberflächen als intern/privat -- `showConfigured` / `showInSetup`: Legacy-Aliase werden aus Kompatibilitätsgründen weiterhin akzeptiert; bevorzuge `exposure` -- `quickstartAllowFrom`: optiert den Kanal in den standardmäßigen Quickstart-`allowFrom`-Ablauf ein -- `forceAccountBinding`: erzwingt explizites Account-Binding, selbst wenn nur ein Konto existiert +- `preferOver`: Plugin-/Kanal-IDs mit niedrigerer Priorität, die dieser Katalogeintrag übertreffen sollte +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: Steuerungen für Texte auf Auswahloberflächen +- `markdownCapable`: markiert den Kanal als markdown-fähig für Entscheidungen zur ausgehenden Formatierung +- `exposure.configured`: blendet den Kanal aus Oberflächen für konfigurierte Kanallisten aus, wenn auf `false` gesetzt +- `exposure.setup`: blendet den Kanal aus interaktiven Setup-/Konfigurations-Auswahllisten aus, wenn auf `false` gesetzt +- `exposure.docs`: markiert den Kanal für Oberflächen der Doku-Navigation als intern/privat +- `showConfigured` / `showInSetup`: Legacy-Aliasse werden aus Kompatibilitätsgründen weiterhin akzeptiert; `exposure` bevorzugen +- `quickstartAllowFrom`: nimmt den Kanal in den standardmäßigen Quickstart-Flow `allowFrom` auf +- `forceAccountBinding`: erzwingt explizite Kontobindung, selbst wenn nur ein Konto existiert - `preferSessionLookupForAnnounceTarget`: bevorzugt Session-Lookup beim Auflösen von Ankündigungszielen -OpenClaw kann außerdem **externe Channel-Kataloge** zusammenführen (zum Beispiel einen Export -aus einer MPM-Registry). Lege eine JSON-Datei an einem der folgenden Orte ab: +OpenClaw kann auch **externe Kanalkataloge** zusammenführen (zum Beispiel einen Export aus einem 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 setze `OPENCLAW_PLUGIN_CATALOG_PATHS` (oder `OPENCLAW_MPM_CATALOG_PATHS`) auf +Oder setzen Sie `OPENCLAW_PLUGIN_CATALOG_PATHS` (oder `OPENCLAW_MPM_CATALOG_PATHS`) auf eine oder mehrere JSON-Dateien (durch Komma/Semikolon/`PATH` getrennt). Jede Datei sollte -`{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }` enthalten. Der Parser akzeptiert außerdem `"packages"` oder `"plugins"` als 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"`. -## Plugins für die Context Engine +## Plugins für die Kontext-Engine -Plugins für die Context Engine besitzen die Orchestrierung des Sitzungskontexts für Ingest, Assembly -und Compaction. Registriere sie aus deinem Plugin mit -`api.registerContextEngine(id, factory)` und wähle dann die aktive Engine mit +Plugins für die Kontext-Engine besitzen die Orchestrierung des Sitzungskontexts für Ingest, Zusammenstellung +und Compaction. Registrieren Sie sie in Ihrem Plugin mit +`api.registerContextEngine(id, factory)` und wählen Sie dann die aktive Engine mit `plugins.slots.contextEngine` aus. -Verwende dies, wenn dein Plugin die Standard-Context-Pipeline ersetzen oder erweitern muss, -statt nur Memory-Suche oder Hooks hinzuzufügen. +Verwenden Sie dies, wenn Ihr Plugin die Standard-Kontextpipeline ersetzen oder erweitern muss, +anstatt nur Memory-Suche oder Hooks hinzuzufügen. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1554,8 +1548,8 @@ export default function (api) { } ``` -Wenn deine Engine den Compaction-Algorithmus **nicht** besitzt, halte `compact()` -implementiert und delegiere ihn ausdrücklich: +Wenn Ihre Engine den Compaction-Algorithmus **nicht** besitzt, `compact()` +implementiert lassen und ihn explizit delegieren: ```ts import { @@ -1592,43 +1586,43 @@ export default function (api) { ## Hinzufügen einer neuen Fähigkeit -Wenn ein Plugin Verhalten benötigt, das nicht in die aktuelle API passt, umgehe nicht -das Plugin-System mit einem privaten Reach-in. Füge die fehlende Fähigkeit hinzu. +Wenn ein Plugin Verhalten benötigt, das nicht in die aktuelle API passt, umgehen Sie das +Plugin-System nicht mit einem privaten Direktzugriff. Fügen Sie die fehlende Fähigkeit hinzu. Empfohlene Reihenfolge: 1. den Core-Vertrag definieren - Entscheide, welches gemeinsame Verhalten der Core besitzen soll: Richtlinie, Fallback, Konfigurations-Merge, - Lebenszyklus, kanalseitige Semantik und Form des Laufzeit-Helfers. + Entscheiden, welches gemeinsame Verhalten der Core besitzen soll: Richtlinie, Fallback, Zusammenführung der Konfiguration, + Lebenszyklus, kanalseitige Semantik und Form des Laufzeithelfers. 2. typisierte Plugin-Registrierungs-/Laufzeitoberflächen hinzufügen - Erweitere `OpenClawPluginApi` und/oder `api.runtime` um die kleinste nützliche - typisierte Fähigkeitsoberfläche. -3. Core + Verbraucher in Kanal/Feature verdrahten + `OpenClawPluginApi` und/oder `api.runtime` mit der kleinsten nützlichen + typisierten Fähigkeitsoberfläche erweitern. +3. Core- und Kanal-/Feature-Konsumenten verdrahten Kanäle und Feature-Plugins sollten die neue Fähigkeit über den Core nutzen, nicht durch direkten Import einer Anbieterimplementierung. 4. Anbieterimplementierungen registrieren - Anbieter-Plugins registrieren dann ihre Backends gegen diese Fähigkeit. + Anbieter-Plugins registrieren dann ihre Backends für diese Fähigkeit. 5. Vertragsabdeckung hinzufügen - Füge Tests hinzu, damit Ownership und Registrierungsform im Laufe der Zeit explizit bleiben. + Tests hinzufügen, damit Zuständigkeit und Registrierungsform im Laufe der Zeit explizit bleiben. -So bleibt OpenClaw meinungsstark, ohne auf das Weltbild eines einzigen -Providers hart kodiert zu werden. Siehe das [Capability Cookbook](/de/plugins/architecture) -für eine konkrete Dateicheckliste und ein ausgearbeitetes Beispiel. +So bleibt OpenClaw meinungsstark, ohne auf das Weltbild eines einzelnen +Providers fest codiert zu werden. Siehe das [Capability Cookbook](/de/plugins/architecture) +für eine konkrete Datei-Checkliste und ein ausgearbeitetes Beispiel. ### Checkliste für Fähigkeiten -Wenn du eine neue Fähigkeit hinzufügst, sollte die Implementierung diese +Wenn Sie eine neue Fähigkeit hinzufügen, sollte die Implementierung diese Oberflächen normalerweise gemeinsam berühren: - Core-Vertragstypen in `src//types.ts` -- Core-Runner/Laufzeit-Helfer in `src//runtime.ts` -- Registrierungsoberfläche der Plugin-API in `src/plugins/types.ts` +- Core-Runner/Laufzeithelfer in `src//runtime.ts` +- Plugin-API-Registrierungsoberfläche in `src/plugins/types.ts` - Verdrahtung der Plugin-Registry in `src/plugins/registry.ts` -- Plugin-Laufzeitbereitstellung in `src/plugins/runtime/*`, wenn Feature-/Channel- +- Bereitstellung in der Plugin-Laufzeit in `src/plugins/runtime/*`, wenn Feature-/Kanal- Plugins sie nutzen müssen -- Capture-/Test-Helper in `src/test-utils/plugin-registration.ts` -- Ownership-/Vertrags-Assertions in `src/plugins/contracts/registry.ts` -- Operator-/Plugin-Dokumentation in `docs/` +- Capture-/Test-Helfer in `src/test-utils/plugin-registration.ts` +- Assertions für Zuständigkeit/Verträge in `src/plugins/contracts/registry.ts` +- Betreiber-/Plugin-Dokumentation in `docs/` Wenn eine dieser Oberflächen fehlt, ist das normalerweise ein Zeichen dafür, dass die Fähigkeit noch nicht vollständig integriert ist. @@ -1667,9 +1661,9 @@ Muster für Vertragstests: expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Damit bleibt die Regel einfach: +So bleibt die Regel einfach: - der Core besitzt den Fähigkeitsvertrag + die Orchestrierung - Anbieter-Plugins besitzen Anbieterimplementierungen -- Feature-/Channel-Plugins nutzen Laufzeit-Helper -- Vertragstests halten Ownership explizit +- Feature-/Kanal-Plugins nutzen Laufzeithelfer +- Vertragstests halten Zuständigkeit explizit diff --git a/docs/de/plugins/sdk-provider-plugins.md b/docs/de/plugins/sdk-provider-plugins.md index d0881901d..0c04358a2 100644 --- a/docs/de/plugins/sdk-provider-plugins.md +++ b/docs/de/plugins/sdk-provider-plugins.md @@ -1,35 +1,40 @@ --- read_when: - - Sie erstellen ein neues Modellanbieter-Plugin + - Sie erstellen ein neues Modell-Provider-Plugin - Sie möchten einen OpenAI-kompatiblen Proxy oder ein benutzerdefiniertes LLM zu OpenClaw hinzufügen - - Sie müssen Auth, Kataloge und Laufzeit-Hooks von Anbietern verstehen + - Sie müssen Provider-Authentifizierung, Kataloge und Laufzeit-Hooks verstehen sidebarTitle: Provider Plugins -summary: Schritt-für-Schritt-Anleitung zum Erstellen eines Modellanbieter-Plugins für OpenClaw -title: Anbieter-Plugins erstellen +summary: Schritt-für-Schritt-Anleitung zum Erstellen eines Modell-Provider-Plugins für OpenClaw +title: Provider-Plugins erstellen x-i18n: - generated_at: "2026-04-21T06:29:58Z" + generated_at: "2026-04-21T13:36:28Z" model: gpt-5.4 provider: openai - source_hash: 459761118c7394c1643c170edfec97c87e1c6323b436183b53ad7a2fed783b04 + source_hash: 08494658def4a003a1e5752f68d9232bfbbbf76348cf6f319ea1a6855c2ae439 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- -# Anbieter-Plugins erstellen +# Provider-Plugins erstellen -Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das OpenClaw einen Modellanbieter (LLM) hinzufügt. Am Ende haben Sie einen Anbieter mit Modellkatalog, API-Schlüssel-Auth und dynamischer Modellauflösung. +Diese Anleitung führt Sie durch das Erstellen eines Provider-Plugins, das OpenClaw einen Modell-Provider +(LLM) hinzufügt. Am Ende haben Sie einen Provider mit einem Modellkatalog, +API-Key-Authentifizierung und dynamischer Modellauflösung. - Wenn Sie noch nie ein OpenClaw-Plugin erstellt haben, lesen Sie zuerst + Wenn Sie zuvor noch kein OpenClaw-Plugin erstellt haben, lesen Sie zuerst [Erste Schritte](/de/plugins/building-plugins) für die grundlegende Paketstruktur und die Manifest-Einrichtung. - Anbieter-Plugins fügen Modelle zur normalen Inferenzschleife von OpenClaw hinzu. Wenn das Modell über einen nativen Agent-Daemon laufen muss, der Threads, Compaction oder Tool-Ereignisse besitzt, koppeln Sie den Anbieter mit einem [agent harness](/de/plugins/sdk-agent-harness), statt Daemon-Protokolldetails in den Core zu legen. + Provider-Plugins fügen Modelle zum normalen Inferenz-Loop von OpenClaw hinzu. Wenn das Modell + über einen nativen Agent-Daemon laufen muss, der Threads, Compaction oder Tool- + Ereignisse verwaltet, kombinieren Sie den Provider stattdessen mit einem [Agent-Harness](/de/plugins/sdk-agent-harness), + anstatt Details des Daemon-Protokolls im Core unterzubringen. -## Schritt-für-Schritt +## Schritt-für-Schritt-Anleitung @@ -59,7 +64,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open { "id": "acme-ai", "name": "Acme AI", - "description": "Acme-AI-Modellanbieter", + "description": "Acme AI model provider", "providers": ["acme-ai"], "modelSupport": { "modelPrefixes": ["acme-"] @@ -75,12 +80,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open "provider": "acme-ai", "method": "api-key", "choiceId": "acme-ai-api-key", - "choiceLabel": "Acme-AI-API-Schlüssel", + "choiceLabel": "Acme AI API key", "groupId": "acme-ai", "groupLabel": "Acme AI", "cliFlag": "--acme-ai-api-key", "cliOption": "--acme-ai-api-key ", - "cliDescription": "Acme-AI-API-Schlüssel" + "cliDescription": "Acme AI API key" } ], "configSchema": { @@ -91,12 +96,18 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open ``` - Das Manifest deklariert `providerAuthEnvVars`, damit OpenClaw Zugangsdaten erkennen kann, ohne Ihre Plugin-Laufzeit zu laden. Fügen Sie `providerAuthAliases` hinzu, wenn eine Anbietervariante die Auth einer anderen Anbieter-ID wiederverwenden soll. `modelSupport` ist optional und erlaubt OpenClaw, Ihr Anbieter-Plugin automatisch aus Kurzform-Modell-IDs wie `acme-large` zu laden, bevor Laufzeit-Hooks existieren. Wenn Sie den Anbieter auf ClawHub veröffentlichen, sind diese Felder `openclaw.compat` und `openclaw.build` in `package.json` erforderlich. + Das Manifest deklariert `providerAuthEnvVars`, damit OpenClaw + Anmeldedaten erkennen kann, ohne die Laufzeit Ihres Plugins zu laden. Fügen Sie `providerAuthAliases` + hinzu, wenn eine Provider-Variante die Authentifizierung einer anderen Provider-ID wiederverwenden soll. `modelSupport` + ist optional und erlaubt OpenClaw, Ihr Provider-Plugin automatisch aus Kurzform- + Modell-IDs wie `acme-large` zu laden, bevor Laufzeit-Hooks existieren. Wenn Sie den + Provider auf ClawHub veröffentlichen, sind diese Felder `openclaw.compat` und `openclaw.build` + in `package.json` erforderlich. - - Ein minimaler Anbieter benötigt `id`, `label`, `auth` und `catalog`: + + Ein minimaler Provider benötigt `id`, `label`, `auth` und `catalog`: ```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -117,12 +128,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open createProviderApiKeyAuthMethod({ providerId: "acme-ai", methodId: "api-key", - label: "Acme-AI-API-Schlüssel", - hint: "API-Schlüssel aus Ihrem Acme-AI-Dashboard", + label: "Acme AI API key", + hint: "API key from your Acme AI dashboard", optionKey: "acmeAiApiKey", flagName: "--acme-ai-api-key", envVar: "ACME_AI_API_KEY", - promptMessage: "Geben Sie Ihren Acme-AI-API-Schlüssel ein", + promptMessage: "Enter your Acme AI API key", defaultModel: "acme-ai/acme-large", }), ], @@ -167,11 +178,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open }); ``` - Das ist ein funktionierender Anbieter. Benutzer können jetzt + Das ist ein funktionierender Provider. Nutzer können jetzt `openclaw onboard --acme-ai-api-key ` ausführen und - `acme-ai/acme-large` als Modell auswählen. + `acme-ai/acme-large` als ihr Modell auswählen. - Wenn der Upstream-Anbieter andere Steuer-Token als OpenClaw verwendet, fügen Sie eine kleine bidirektionale Texttransformation hinzu, statt den Stream-Pfad zu ersetzen: + Wenn der Upstream-Provider andere Steuer-Tokens als OpenClaw verwendet, fügen Sie eine + kleine bidirektionale Texttransformation hinzu, anstatt den Stream-Pfad zu ersetzen: ```typescript api.registerTextTransforms({ @@ -188,9 +200,13 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open }); ``` - `input` schreibt den finalen System-Prompt und den Inhalt von Textnachrichten vor dem Transport um. `output` schreibt Assistant-Text-Deltas und finalen Text um, bevor OpenClaw seine eigenen Kontrollmarker oder die Kanalzustellung parst. + `input` schreibt den finalen System-Prompt und den Inhalt von Textnachrichten vor + dem Transport um. `output` schreibt Assistant-Text-Deltas und finalen Text um, bevor + OpenClaw seine eigenen Steuer-Markierungen oder die Kanalzustellung parst. - Für gebündelte Anbieter, die nur einen Textanbieter mit API-Schlüssel-Auth plus eine einzelne kataloggestützte Laufzeit registrieren, bevorzugen Sie den schmaleren Helper `defineSingleProviderPluginEntry(...)`: + Für gebündelte Provider, die nur einen Text-Provider mit API-Key- + Authentifizierung plus eine einzelne kataloggestützte Laufzeit registrieren, bevorzugen Sie den engeren + Helper `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -205,12 +221,12 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open auth: [ { methodId: "api-key", - label: "Acme-AI-API-Schlüssel", - hint: "API-Schlüssel aus Ihrem Acme-AI-Dashboard", + label: "Acme AI API key", + hint: "API key from your Acme AI dashboard", optionKey: "acmeAiApiKey", flagName: "--acme-ai-api-key", envVar: "ACME_AI_API_KEY", - promptMessage: "Geben Sie Ihren Acme-AI-API-Schlüssel ein", + promptMessage: "Enter your Acme AI API key", defaultModel: "acme-ai/acme-large", }, ], @@ -225,21 +241,30 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open }); ``` - Wenn Ihr Auth-Ablauf zusätzlich `models.providers.*`, Aliasse und das Standard-Agentenmodell beim Onboarding patchen muss, verwenden Sie die Preset-Helper aus `openclaw/plugin-sdk/provider-onboard`. Die schmalsten Helper sind + Wenn Ihr Auth-Flow während des Onboardings außerdem `models.providers.*`, Aliase und + das Standardmodell des Agenten patchen muss, verwenden Sie die Preset-Helper aus + `openclaw/plugin-sdk/provider-onboard`. Die engsten Helper sind `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` und `createModelCatalogPresetAppliers(...)`. - Wenn ein nativer Endpunkt des Anbieters gestreamte Usage-Blöcke auf dem normalen Transport `openai-completions` unterstützt, bevorzugen Sie die gemeinsamen Katalog-Helper in `openclaw/plugin-sdk/provider-catalog-shared`, statt Anbieter-ID-Prüfungen fest zu codieren. `supportsNativeStreamingUsageCompat(...)` und `applyProviderNativeStreamingUsageCompat(...)` erkennen die Unterstützung aus der Endpunkt-Fähigkeits-Map, sodass native Endpunkte im Stil von Moonshot/DashScope weiterhin opt-in sind, selbst wenn ein Plugin eine benutzerdefinierte Anbieter-ID verwendet. + Wenn der native Endpunkt eines Providers gestreamte Nutzungsblöcke auf dem + normalen Transport `openai-completions` unterstützt, bevorzugen Sie die gemeinsamen Katalog-Helper in + `openclaw/plugin-sdk/provider-catalog-shared`, anstatt Prüfungen auf Provider-IDs fest zu codieren. + `supportsNativeStreamingUsageCompat(...)` und + `applyProviderNativeStreamingUsageCompat(...)` erkennen die Unterstützung anhand der Capability-Map des + Endpunkts, sodass native Endpunkte im Stil von Moonshot/DashScope weiterhin + optieren können, selbst wenn ein Plugin eine benutzerdefinierte Provider-ID verwendet. - Wenn Ihr Anbieter beliebige Modell-IDs akzeptiert (wie ein Proxy oder Router), fügen Sie `resolveDynamicModel` hinzu: + Wenn Ihr Provider beliebige Modell-IDs akzeptiert (wie ein Proxy oder Router), + fügen Sie `resolveDynamicModel` hinzu: ```typescript api.registerProvider({ - // ... id, label, auth, catalog von oben + // ... id, label, auth, catalog from above resolveDynamicModel: (ctx) => ({ id: ctx.modelId, @@ -256,14 +281,17 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open }); ``` - Wenn die Auflösung einen Netzwerkaufruf erfordert, verwenden Sie `prepareDynamicModel` für asynchrones Warm-up — `resolveDynamicModel` wird erneut ausgeführt, nachdem es abgeschlossen ist. + Wenn die Auflösung einen Netzwerkaufruf erfordert, verwenden Sie `prepareDynamicModel` für asynchrones + Aufwärmen — `resolveDynamicModel` läuft danach erneut. - Die meisten Anbieter benötigen nur `catalog` + `resolveDynamicModel`. Fügen Sie Hooks schrittweise hinzu, wenn Ihr Anbieter sie benötigt. + Die meisten Provider benötigen nur `catalog` + `resolveDynamicModel`. Fügen Sie Hooks + schrittweise hinzu, wenn Ihr Provider sie benötigt. - Gemeinsame Helper-Builder decken jetzt die häufigsten Familien für Replay-/Tool-Kompatibilität ab, sodass Plugins normalerweise nicht jeden Hook einzeln verdrahten müssen: + Gemeinsame Helper-Builder decken jetzt die häufigsten Replay-/Tool-Kompatibilitäts- + Familien ab, sodass Plugins in der Regel nicht jeden Hook einzeln von Hand verdrahten müssen: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -283,17 +311,17 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open }); ``` - Heute verfügbare Replay-Familien: + Verfügbare Replay-Familien heute: - | Family | Was damit verdrahtet wird | + | Familie | Was sie verdrahtet | | --- | --- | - | `openai-compatible` | Gemeinsame Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transporte, einschließlich Tool-Call-ID-Bereinigung, Korrekturen für Assistant-first-Reihenfolge und generischer Gemini-Turn-Validierung, wo der Transport sie benötigt | - | `anthropic-by-model` | Claude-bewusste Replay-Richtlinie, ausgewählt nach `modelId`, sodass Anthropic-Message-Transporte nur dann Claude-spezifische Bereinigung von Thinking-Blöcken erhalten, wenn das aufgelöste Modell tatsächlich eine Claude-ID ist | - | `google-gemini` | Native Gemini-Replay-Richtlinie plus Bereinigung von Bootstrap-Replay und getaggter Ausgabemodus für Reasoning | - | `passthrough-gemini` | Bereinigung von Gemini-Thought-Signaturen für Gemini-Modelle, die über OpenAI-kompatible Proxy-Transporte laufen; aktiviert weder native Gemini-Replay-Validierung noch Bootstrap-Umschreibungen | - | `hybrid-anthropic-openai` | Hybride Richtlinie für Anbieter, die Anthropic-Message- und OpenAI-kompatible Modelloberflächen in einem Plugin mischen; optionales Entfernen Claude-spezifischer Thinking-Blöcke bleibt auf die Anthropic-Seite beschränkt | + | `openai-compatible` | Gemeinsame Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transporte, einschließlich Bereinigung von Tool-Call-IDs, Korrekturen für Assistant-first-Reihenfolge und generischer Gemini-Turn-Validierung, wo der Transport sie benötigt | + | `anthropic-by-model` | Claude-bewusste Replay-Richtlinie, ausgewählt nach `modelId`, sodass Transports auf Basis von Anthropic-Messages nur dann Claude-spezifische Bereinigung von Thinking-Blöcken erhalten, wenn das aufgelöste Modell tatsächlich eine Claude-ID ist | + | `google-gemini` | Native Gemini-Replay-Richtlinie plus Bereinigung des Bootstrap-Replays und markierter Modus für Reasoning-Ausgabe | + | `passthrough-gemini` | Bereinigung der Gemini-Thought-Signature für Gemini-Modelle, die über OpenAI-kompatible Proxy-Transporte laufen; aktiviert weder native Gemini-Replay-Validierung noch Bootstrap-Umschreibungen | + | `hybrid-anthropic-openai` | Hybride Richtlinie für Provider, die in einem Plugin Anthropic-Message- und OpenAI-kompatible Modelloberflächen mischen; optionales Entfernen von Claude-spezifischen Thinking-Blöcken bleibt auf die Anthropic-Seite beschränkt | - Echte gebündelte Beispiele: + Reale gebündelte Beispiele: - `google` und `google-gemini-cli`: `google-gemini` - `openrouter`, `kilocode`, `opencode` und `opencode-go`: `passthrough-gemini` @@ -303,17 +331,17 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open Heute verfügbare Stream-Familien: - | Family | Was damit verdrahtet wird | + | Familie | Was sie verdrahtet | | --- | --- | - | `google-thinking` | Normalisierung der Gemini-Thinking-Payload auf dem gemeinsamen Stream-Pfad | - | `kilocode-thinking` | Kilo-Reasoning-Wrapper auf dem gemeinsamen Proxy-Stream-Pfad, wobei `kilo/auto` und nicht unterstützte Proxy-Reasoning-IDs injiziertes Thinking überspringen | - | `moonshot-thinking` | Moonshot-Mapping für binäre native Thinking-Payload aus Konfiguration + `/think`-Level | - | `minimax-fast-mode` | Umschreiben von MiniMax-Modellen im Fast-Mode auf dem gemeinsamen Stream-Pfad | - | `openai-responses-defaults` | Gemeinsame native OpenAI-/Codex-Responses-Wrapper: Attributions-Header, `/fast`/`serviceTier`, Textausführlichkeit, native Codex-Websuche, OpenAI-Reasoning-kompatibles Payload-Shaping und Responses-Kontextverwaltung | - | `openrouter-thinking` | OpenRouter-Reasoning-Wrapper für Proxy-Routen, wobei Sprünge für nicht unterstützte Modelle/`auto` zentral behandelt werden | - | `tool-stream-default-on` | Standardmäßig aktivierter `tool_stream`-Wrapper für Anbieter wie Z.AI, die Tool-Streaming wünschen, sofern es nicht explizit deaktiviert wird | + | `google-thinking` | Gemini-Thinking-Payload-Normalisierung auf dem gemeinsamen Stream-Pfad | + | `kilocode-thinking` | Kilo-Reasoning-Wrapper auf dem gemeinsamen Proxy-Stream-Pfad, wobei `kilo/auto` und nicht unterstützte Proxy-Reasoning-IDs eingefügtes Thinking überspringen | + | `moonshot-thinking` | Moonshot-Binär-Mapping für native Thinking-Payloads aus Konfiguration + `/think`-Level | + | `minimax-fast-mode` | MiniMax-Fast-Mode-Modellumschreibung auf dem gemeinsamen Stream-Pfad | + | `openai-responses-defaults` | Gemeinsame native OpenAI/Codex-Responses-Wrapper: Attributions-Header, `/fast`/`serviceTier`, Text-Verbosity, native Codex-Websuche, Reasoning-kompatible Payload-Formung und Responses-Kontextverwaltung | + | `openrouter-thinking` | OpenRouter-Reasoning-Wrapper für Proxy-Routen, wobei Überspringen bei nicht unterstützten Modellen/`auto` zentral behandelt wird | + | `tool-stream-default-on` | Standardmäßig aktivierter `tool_stream`-Wrapper für Provider wie Z.AI, die Tool-Streaming wünschen, sofern es nicht ausdrücklich deaktiviert wird | - Echte gebündelte Beispiele: + Reale gebündelte Beispiele: - `google` und `google-gemini-cli`: `google-thinking` - `kilocode`: `kilocode-thinking` @@ -323,7 +351,9 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open - `openrouter`: `openrouter-thinking` - `zai`: `tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` exportiert außerdem das Enum für Replay-Familien sowie die gemeinsamen Helper, aus denen diese Familien aufgebaut werden. Häufige öffentliche Exporte umfassen: + `openclaw/plugin-sdk/provider-model-shared` exportiert auch das Replay-Familien- + Enum sowie die gemeinsamen Helper, aus denen diese Familien aufgebaut sind. Häufige öffentliche + Exporte sind unter anderem: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` @@ -337,49 +367,65 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` und `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` stellt sowohl den Familien-Builder als - auch die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Häufige öffentliche Exporte umfassen: + `openclaw/plugin-sdk/provider-stream` stellt sowohl den Familien-Builder als auch + die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Häufige öffentliche Exporte + sind unter anderem: - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` - `composeProviderStreamWrappers(...)` - - gemeinsame OpenAI-/Codex-Wrapper wie + - gemeinsame OpenAI/Codex-Wrapper wie `createOpenAIAttributionHeadersWrapper(...)`, `createOpenAIFastModeWrapper(...)`, `createOpenAIServiceTierWrapper(...)`, `createOpenAIResponsesContextManagementWrapper(...)` und `createCodexNativeWebSearchWrapper(...)` - - gemeinsame Proxy-/Anbieter-Wrapper wie `createOpenRouterWrapper(...)`, + - gemeinsame Proxy-/Provider-Wrapper wie `createOpenRouterWrapper(...)`, `createToolStreamWrapper(...)` und `createMinimaxFastModeWrapper(...)` - Einige Stream-Helper bleiben absichtlich anbieterlokal. Aktuelles gebündeltes Beispiel: `@openclaw/anthropic-provider` exportiert + Einige Stream-Helper bleiben absichtlich Provider-lokal. Aktuelles gebündeltes + Beispiel: `@openclaw/anthropic-provider` exportiert `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` und die - Anthropic-Wrapper-Builder auf niedriger Ebene aus seiner öffentlichen Nahtstelle `api.ts` / `contract-api.ts`. Diese Helper bleiben Anthropic-spezifisch, weil sie auch die Behandlung von Claude-OAuth-Betas und `context1m`-Gating kodieren. + Wrapper-Builder auf niedrigerer Ebene für Anthropic aus seiner öffentlichen Nahtstelle `api.ts` / + `contract-api.ts`. Diese Helper bleiben Anthropic-spezifisch, weil + sie außerdem Claude-OAuth-Beta-Behandlung und `context1m`-Gating kodieren. - Andere gebündelte Anbieter behalten transportspezifische Wrapper ebenfalls lokal, wenn das Verhalten sich nicht sauber über Familien hinweg teilen lässt. Aktuelles Beispiel: Das gebündelte xAI-Plugin hält das native Shaping der xAI-Responses in seinem eigenen `wrapStreamFn`, einschließlich Umschreibungen von `/fast`-Aliasen, Standard-`tool_stream`, Bereinigung nicht unterstützter strikter Tools und Entfernung xAI-spezifischer Reasoning-Payload. + Andere gebündelte Provider behalten ebenfalls transport-spezifische Wrapper lokal, wenn + das Verhalten sich nicht sauber über Familien hinweg teilen lässt. Aktuelles Beispiel: Das + gebündelte xAI-Plugin behält die native xAI-Responses-Formung in seinem eigenen + `wrapStreamFn`, einschließlich Umschreibungen von `/fast`-Aliasen, standardmäßigem `tool_stream`, + Bereinigung nicht unterstützter Strict-Tool-Fälle und xAI-spezifischer Entfernung von + Reasoning-Payloads. - `openclaw/plugin-sdk/provider-tools` stellt derzeit eine gemeinsame Tool-Schema-Familie plus gemeinsame Schema-/Kompatibilitäts-Helper bereit: + `openclaw/plugin-sdk/provider-tools` stellt derzeit eine gemeinsame + Tool-Schema-Familie sowie gemeinsame Schema-/Kompatibilitäts-Helper bereit: - - `ProviderToolCompatFamily` dokumentiert das aktuelle Inventar der gemeinsamen Familien. - - `buildProviderToolCompatFamilyHooks("gemini")` verdrahtet Gemini-Schemabereinigung + Diagnose für Anbieter, die Gemini-sichere Tool-Schemas benötigen. - - `normalizeGeminiToolSchemas(...)` und `inspectGeminiToolSchemas(...)` sind die zugrunde liegenden öffentlichen Gemini-Schema-Helper. - - `resolveXaiModelCompatPatch()` gibt den gebündelten xAI-Kompatibilitätspatch zurück: - `toolSchemaProfile: "xai"`, nicht unterstützte Schema-Schlüsselwörter, native Unterstützung für `web_search` und das Dekodieren HTML-entity-kodierter Tool-Call-Argumente. - - `applyXaiModelCompat(model)` wendet denselben xAI-Kompatibilitätspatch auf ein aufgelöstes Modell an, bevor es den Runner erreicht. + - `ProviderToolCompatFamily` dokumentiert heute das gemeinsame Familieninventar. + - `buildProviderToolCompatFamilyHooks("gemini")` verdrahtet Gemini-Schema- + Bereinigung + Diagnostik für Provider, die Gemini-sichere Tool-Schemas benötigen. + - `normalizeGeminiToolSchemas(...)` und `inspectGeminiToolSchemas(...)` + sind die zugrunde liegenden öffentlichen Gemini-Schema-Helper. + - `resolveXaiModelCompatPatch()` gibt den gebündelten xAI-Kompatibilitäts-Patch zurück: + `toolSchemaProfile: "xai"`, nicht unterstützte Schema-Schlüsselwörter, native + Unterstützung für `web_search` und HTML-Entity-Dekodierung von Tool-Call-Argumenten. + - `applyXaiModelCompat(model)` wendet denselben xAI-Kompatibilitäts-Patch auf ein + aufgelöstes Modell an, bevor es den Runner erreicht. - Echtes gebündeltes Beispiel: Das xAI-Plugin verwendet `normalizeResolvedModel` plus `contributeResolvedModelCompat`, um diese Kompatibilitätsmetadaten beim Anbieter zu halten, statt xAI-Regeln im Core fest zu codieren. + Reales gebündeltes Beispiel: Das xAI-Plugin verwendet `normalizeResolvedModel` plus + `contributeResolvedModelCompat`, damit diese Kompatibilitätsmetadaten dem + Provider gehören, anstatt xAI-Regeln im Core fest zu codieren. - Dasselbe Muster mit Paket-Root wird auch von anderen gebündelten Anbietern verwendet: + Dasselbe Paket-Root-Muster stützt auch andere gebündelte Provider: - - `@openclaw/openai-provider`: `api.ts` exportiert Anbieter-Builder, - Helper für Standardmodelle und Builder für Realtime-Anbieter - - `@openclaw/openrouter-provider`: `api.ts` exportiert den Anbieter-Builder + - `@openclaw/openai-provider`: `api.ts` exportiert Provider-Builder, + Default-Modell-Helper und Realtime-Provider-Builder + - `@openclaw/openrouter-provider`: `api.ts` exportiert den Provider-Builder plus Onboarding-/Konfigurations-Helper - Für Anbieter, die vor jedem Inferenzaufruf einen Token-Austausch benötigen: + Für Provider, die vor jedem Inferenzaufruf einen Token-Austausch benötigen: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -393,7 +439,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open ``` - Für Anbieter, die benutzerdefinierte Anfrage-Header oder Änderungen am Body benötigen: + Für Provider, die benutzerdefinierte Request-Header oder Änderungen am Body benötigen: ```typescript // wrapStreamFn gibt eine von ctx.streamFn abgeleitete StreamFn zurück @@ -410,8 +456,8 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open }, ``` - - Für Anbieter, die native Anfrage-/Sitzungs-Header oder Metadaten auf + + Für Provider, die native Request-/Sitzungs-Header oder Metadaten auf generischen HTTP- oder WebSocket-Transporten benötigen: ```typescript @@ -432,8 +478,8 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open }), ``` - - Für Anbieter, die Usage-/Abrechnungsdaten verfügbar machen: + + Für Provider, die Nutzungs-/Abrechnungsdaten bereitstellen: ```typescript resolveUsageAuth: async (ctx) => { @@ -447,80 +493,85 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open - - OpenClaw ruft Hooks in dieser Reihenfolge auf. Die meisten Anbieter verwenden nur 2–3: + + OpenClaw ruft Hooks in dieser Reihenfolge auf. Die meisten Provider verwenden nur 2–3: | # | Hook | Wann verwenden | | --- | --- | --- | - | 1 | `catalog` | Modellkatalog oder Defaults für Basis-URL | - | 2 | `applyConfigDefaults` | Anbieter-eigene globale Defaults während der Konfigurationsmaterialisierung | - | 3 | `normalizeModelId` | Bereinigung von Legacy-/Vorschau-Modell-ID-Aliasen vor dem Lookup | - | 4 | `normalizeTransport` | Bereinigung von `api` / `baseUrl` der Anbieterfamilie vor der generischen Modellzusammensetzung | - | 5 | `normalizeConfig` | `models.providers.`-Konfiguration normalisieren | - | 6 | `applyNativeStreamingUsageCompat` | Native Streaming-Usage-Kompatibilitätsumschreibungen für Konfigurationsanbieter | - | 7 | `resolveConfigApiKey` | Anbieter-eigene Auflösung von Env-Marker-Auth | - | 8 | `resolveSyntheticAuth` | Synthetische Auth für lokal/self-hosted oder konfigurationsgestützte Fälle | - | 9 | `shouldDeferSyntheticProfileAuth` | Gespeicherte synthetische Profil-Platzhalter hinter Env-/Konfigurations-Auth zurückstufen | + | 1 | `catalog` | Modellkatalog oder Defaultwerte für `baseUrl` | + | 2 | `applyConfigDefaults` | Provider-eigene globale Standardwerte während der Materialisierung der Konfiguration | + | 3 | `normalizeModelId` | Bereinigung von Legacy-/Preview-Modell-ID-Aliasen vor dem Lookup | + | 4 | `normalizeTransport` | Bereinigung von `api` / `baseUrl` der Provider-Familie vor der generischen Modellzusammenstellung | + | 5 | `normalizeConfig` | Konfiguration `models.providers.` normalisieren | + | 6 | `applyNativeStreamingUsageCompat` | Native Streaming-Usage-Kompatibilitäts-Umschreibungen für Konfigurations-Provider | + | 7 | `resolveConfigApiKey` | Provider-eigene Auflösung von Env-Marker-Authentifizierung | + | 8 | `resolveSyntheticAuth` | Synthetische lokale/self-hosted oder konfigurationsgestützte Authentifizierung | + | 9 | `shouldDeferSyntheticProfileAuth` | Platzhalter für synthetische gespeicherte Profile hinter Env-/Konfigurations-Authentifizierung zurückstufen | | 10 | `resolveDynamicModel` | Beliebige Upstream-Modell-IDs akzeptieren | - | 11 | `prepareDynamicModel` | Asynchroner Metadatenabruf vor der Auflösung | + | 11 | `prepareDynamicModel` | Asynchrones Abrufen von Metadaten vor der Auflösung | | 12 | `normalizeResolvedModel` | Transport-Umschreibungen vor dem Runner | Hinweise zum Laufzeit-Fallback: - - `normalizeConfig` prüft zuerst den passenden Anbieter und dann andere - hook-fähige Anbieter-Plugins, bis eines die Konfiguration tatsächlich ändert. - Wenn kein Anbieter-Hook einen unterstützten Konfigurationseintrag der Google-Familie umschreibt, greift weiterhin der gebündelte Google-Konfigurationsnormalisierer. - - `resolveConfigApiKey` verwendet den Anbieter-Hook, wenn er bereitgestellt wird. Der gebündelte Pfad `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, obwohl Bedrock-Laufzeit-Auth selbst weiterhin die AWS-SDK-Standardkette verwendet. - | 13 | `contributeResolvedModelCompat` | Kompatibilitätsflags für Vendor-Modelle hinter einem anderen kompatiblen Transport | - | 14 | `capabilities` | Legacy-statischer Capability-Bag; nur zur Kompatibilität | - | 15 | `normalizeToolSchemas` | Anbieter-eigene Bereinigung von Tool-Schemas vor der Registrierung | - | 16 | `inspectToolSchemas` | Anbieter-eigene Tool-Schema-Diagnose | - | 17 | `resolveReasoningOutputMode` | Getaggter vs. nativer Vertrag für Reasoning-Ausgabe | - | 18 | `prepareExtraParams` | Standard-Anfrageparameter | + - `normalizeConfig` prüft zuerst den passenden Provider, dann andere + Hook-fähige Provider-Plugins, bis eines die Konfiguration tatsächlich ändert. + Wenn kein Provider-Hook einen unterstützten Google-Familien-Konfigurationseintrag umschreibt, wird + weiterhin der gebündelte Google-Konfigurations-Normalisierer angewendet. + - `resolveConfigApiKey` verwendet den Provider-Hook, wenn er verfügbar ist. Der gebündelte + Pfad `amazon-bedrock` hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, + auch wenn Bedrock-Laufzeit-Auth selbst weiterhin die AWS-SDK-Default- + Chain verwendet. + | 13 | `contributeResolvedModelCompat` | Kompatibilitäts-Flags für Vendor-Modelle hinter einem anderen kompatiblen Transport | + | 14 | `capabilities` | Legacy-Bag statischer Capabilities; nur aus Kompatibilitätsgründen | + | 15 | `normalizeToolSchemas` | Provider-eigene Tool-Schema-Bereinigung vor der Registrierung | + | 16 | `inspectToolSchemas` | Provider-eigene Tool-Schema-Diagnostik | + | 17 | `resolveReasoningOutputMode` | Markierter vs. nativer Vertrag für Reasoning-Ausgabe | + | 18 | `prepareExtraParams` | Standard-Request-Parameter | | 19 | `createStreamFn` | Vollständig benutzerdefinierter StreamFn-Transport | | 20 | `wrapStreamFn` | Benutzerdefinierte Header-/Body-Wrapper auf dem normalen Stream-Pfad | | 21 | `resolveTransportTurnState` | Native Header/Metadaten pro Turn | - | 22 | `resolveWebSocketSessionPolicy` | Native WS-Sitzungs-Header/Cooldown | - | 23 | `formatApiKey` | Benutzerdefinierte Form des Laufzeit-Tokens | - | 24 | `refreshOAuth` | Benutzerdefiniertes OAuth-Refresh | - | 25 | `buildAuthDoctorHint` | Hinweise zur Auth-Reparatur | - | 26 | `matchesContextOverflowError` | Anbieter-eigene Erkennung von Überläufen | - | 27 | `classifyFailoverReason` | Anbieter-eigene Klassifizierung von Rate-Limit/Überlastung | - | 28 | `isCacheTtlEligible` | Gating für Prompt-Cache-TTL | - | 29 | `buildMissingAuthMessage` | Benutzerdefinierter Hinweis für fehlende Auth | + | 22 | `resolveWebSocketSessionPolicy` | Native WS-Sitzungs-Header/Cool-down | + | 23 | `formatApiKey` | Benutzerdefinierte Laufzeit-Token-Form | + | 24 | `refreshOAuth` | Benutzerdefinierte OAuth-Aktualisierung | + | 25 | `buildAuthDoctorHint` | Hinweise zur Reparatur der Authentifizierung | + | 26 | `matchesContextOverflowError` | Provider-eigene Overflow-Erkennung | + | 27 | `classifyFailoverReason` | Provider-eigene Klassifizierung von Rate-Limit/Überlastung | + | 28 | `isCacheTtlEligible` | TTL-Gating für Prompt-Cache | + | 29 | `buildMissingAuthMessage` | Benutzerdefinierter Hinweis bei fehlender Authentifizierung | | 30 | `suppressBuiltInModel` | Veraltete Upstream-Zeilen ausblenden | - | 31 | `augmentModelCatalog` | Synthetische Vorwärtskompatibilitäts-Zeilen | - | 32 | `isBinaryThinking` | Binäres Thinking ein/aus | - | 33 | `supportsXHighThinking` | Unterstützung für `xhigh`-Reasoning | - | 34 | `supportsAdaptiveThinking` | Unterstützung für adaptives Thinking | - | 35 | `supportsMaxThinking` | Unterstützung für `max`-Reasoning | - | 36 | `resolveDefaultThinkingLevel` | Standardrichtlinie für `/think` | - | 37 | `isModernModelRef` | Abgleich von Live-/Smoke-Modellen | - | 38 | `prepareRuntimeAuth` | Token-Austausch vor der Inferenz | - | 39 | `resolveUsageAuth` | Benutzerdefiniertes Parsing von Usage-Zugangsdaten | - | 40 | `fetchUsageSnapshot` | Benutzerdefinierter Usage-Endpunkt | - | 41 | `createEmbeddingProvider` | Anbieter-eigener Embedding-Adapter für Memory/Suche | - | 42 | `buildReplayPolicy` | Benutzerdefinierte Richtlinie für Transcript-Replay/Compaction | - | 43 | `sanitizeReplayHistory` | Anbieter-spezifische Replay-Umschreibungen nach generischer Bereinigung | - | 44 | `validateReplayTurns` | Strikte Validierung von Replay-Turns vor dem eingebetteten Runner | - | 45 | `onModelSelected` | Callback nach der Auswahl (z. B. Telemetrie) | + | 31 | `augmentModelCatalog` | Synthetische Zeilen für Vorwärtskompatibilität | + | 32 | `resolveThinkingProfile` | Modellspezifischer Optionssatz für `/think` | + | 33 | `isBinaryThinking` | Kompatibilität für binäres Thinking an/aus | + | 34 | `supportsXHighThinking` | Kompatibilität für `xhigh`-Reasoning-Unterstützung | + | 35 | `resolveDefaultThinkingLevel` | Kompatibilität der Standardrichtlinie für `/think` | + | 36 | `isModernModelRef` | Abgleich von Live-/Smoke-Modellen | + | 37 | `prepareRuntimeAuth` | Token-Austausch vor Inferenz | + | 38 | `resolveUsageAuth` | Benutzerdefiniertes Parsen von Nutzungs-Anmeldedaten | + | 39 | `fetchUsageSnapshot` | Benutzerdefinierter Usage-Endpunkt | + | 40 | `createEmbeddingProvider` | Provider-eigener Embedding-Adapter für Speicher/Suche | + | 41 | `buildReplayPolicy` | Benutzerdefinierte Richtlinie für Transcript-Replay/Compaction | + | 42 | `sanitizeReplayHistory` | Provider-spezifische Replay-Umschreibungen nach generischer Bereinigung | + | 43 | `validateReplayTurns` | Strikte Validierung von Replay-Turns vor dem eingebetteten Runner | + | 44 | `onModelSelected` | Callback nach Auswahl (z. B. Telemetrie) | Hinweis zur Prompt-Abstimmung: - - `resolveSystemPromptContribution` erlaubt einem Anbieter, cache-bewusste - Hinweise für den System-Prompt in einer Modellfamilie zu injizieren. Bevorzugen Sie es gegenüber `before_prompt_build`, wenn das Verhalten zu einer Anbieter-/Modellfamilie gehört und die stabile/dynamische Cache-Aufteilung erhalten bleiben soll. + - `resolveSystemPromptContribution` erlaubt einem Provider das Einfügen Cache-bewusster + System-Prompt-Hinweise für eine Modellfamilie. Bevorzugen Sie dies gegenüber + `before_prompt_build`, wenn das Verhalten zu einer Provider-/Modellfamilie gehört + und die stabile/dynamische Cache-Aufteilung erhalten bleiben soll. Ausführliche Beschreibungen und Beispiele aus der Praxis finden Sie unter - [Internals: Provider Runtime Hooks](/de/plugins/architecture#provider-runtime-hooks). + [Internals: Provider-Laufzeit-Hooks](/de/plugins/architecture#provider-runtime-hooks). - + - Ein Anbieter-Plugin kann Sprache, Realtime-Transkription, Realtime-Stimme, - Medienverständnis, Bildgenerierung, Videogenerierung, Web-Fetch - und Websuche neben der Textinferenz registrieren: + Ein Provider-Plugin kann zusätzlich zur Textinferenz Speech, Realtime-Transkription, Realtime- + Voice, Medienverständnis, Bildgenerierung, Videogenerierung, Web-Fetch + und Websuche registrieren: ```typescript register(api) { @@ -531,7 +582,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open label: "Acme Speech", isConfigured: ({ config }) => Boolean(config.messages?.tts), synthesize: async (req) => ({ - audioBuffer: Buffer.from(/* PCM-Daten */), + audioBuffer: Buffer.from(/* PCM data */), outputFormat: "mp3", fileExtension: ".mp3", voiceCompatible: false, @@ -568,14 +619,14 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open api.registerMediaUnderstandingProvider({ id: "acme-ai", capabilities: ["image", "audio"], - describeImage: async (req) => ({ text: "Ein Foto von ..." }), - transcribeAudio: async (req) => ({ text: "Transkript ..." }), + describeImage: async (req) => ({ text: "A photo of..." }), + transcribeAudio: async (req) => ({ text: "Transcript..." }), }); api.registerImageGenerationProvider({ id: "acme-ai", label: "Acme Images", - generate: async (req) => ({ /* Bildergebnis */ }), + generate: async (req) => ({ /* image result */ }), }); api.registerVideoGenerationProvider({ @@ -603,7 +654,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "Seiten über Acmes Rendering-Backend abrufen.", + hint: "Fetch pages through Acme's rendering backend.", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -614,7 +665,7 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open acme.apiKey = value; }, createTool: () => ({ - description: "Eine Seite über Acme Fetch abrufen.", + description: "Fetch a page through Acme Fetch.", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -628,15 +679,20 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open } ``` - OpenClaw klassifiziert dies als Plugin mit **hybrider Fähigkeit**. Das ist das empfohlene Muster für Firmen-Plugins (ein Plugin pro Anbieter). Siehe [Internals: Capability Ownership](/de/plugins/architecture#capability-ownership-model). + OpenClaw klassifiziert dies als Plugin mit **hybrid-capability**. Dies ist das + empfohlene Muster für Unternehmens-Plugins (ein Plugin pro Anbieter). Siehe + [Internals: Capability Ownership](/de/plugins/architecture#capability-ownership-model). - Für die Videogenerierung bevorzugen Sie die oben gezeigte, modusbewusste Form der Fähigkeiten: + Bevorzugen Sie bei der Videogenerierung die oben gezeigte fähigkeitsform mit Modusbezug: `generate`, `imageToVideo` und `videoToVideo`. Flache aggregierte Felder wie - `maxInputImages`, `maxInputVideos` und `maxDurationSeconds` reichen nicht aus, um Unterstützung oder deaktivierte Modi für Transformationsmodi sauber zu bewerben. + `maxInputImages`, `maxInputVideos` und `maxDurationSeconds` reichen nicht + aus, um Unterstützung für Transformationsmodi oder deaktivierte Modi sauber zu bewerben. - Anbieter für Musikgenerierung sollten demselben Muster folgen: - `generate` für promptbasierte Generierung und `edit` für referenzbildbasierte Generierung. Flache aggregierte Felder wie `maxInputImages`, - `supportsLyrics` und `supportsFormat` reichen nicht aus, um Unterstützung für Bearbeitung zu bewerben; explizite Blöcke `generate` / `edit` sind der erwartete Vertrag. + Provider für Musikgenerierung sollten demselben Muster folgen: + `generate` für reine Prompt-basierte Generierung und `edit` für referenzbildbasierte + Generierung. Flache aggregierte Felder wie `maxInputImages`, + `supportsLyrics` und `supportsFormat` reichen nicht aus, um Bearbeitungs- + unterstützung zu bewerben; explizite Blöcke `generate` / `edit` sind der erwartete Vertrag. @@ -644,11 +700,11 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; - // Exportieren Sie Ihr Anbieter-Konfigurationsobjekt aus index.ts oder einer dedizierten Datei + // Export your provider config object from index.ts or a dedicated file import { acmeProvider } from "./provider.js"; describe("acme-ai provider", () => { - it("löst dynamische Modelle auf", () => { + it("resolves dynamic models", () => { const model = acmeProvider.resolveDynamicModel!({ modelId: "acme-beta-v3", } as any); @@ -656,14 +712,14 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open expect(model.provider).toBe("acme-ai"); }); - it("gibt den Katalog zurück, wenn ein Schlüssel verfügbar ist", async () => { + it("returns catalog when key is available", async () => { const result = await acmeProvider.catalog!.run({ resolveProviderApiKey: () => ({ apiKey: "test-key" }), } as any); expect(result?.provider?.models).toHaveLength(2); }); - it("gibt null für den Katalog zurück, wenn kein Schlüssel vorhanden ist", async () => { + it("returns null catalog when no key", async () => { const result = await acmeProvider.catalog!.run({ resolveProviderApiKey: () => ({ apiKey: undefined }), } as any); @@ -675,23 +731,24 @@ Diese Anleitung führt Sie durch die Erstellung eines Anbieter-Plugins, das Open -## In ClawHub veröffentlichen +## Auf ClawHub veröffentlichen -Anbieter-Plugins werden wie jeder andere externe Code-Plugin veröffentlicht: +Provider-Plugins werden auf die gleiche Weise veröffentlicht wie jedes andere externe Code-Plugin: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Verwenden Sie hier nicht den veralteten Publish-Alias nur für Skills; Plugin-Pakete sollten `clawhub package publish` verwenden. +Verwenden Sie hier nicht den veralteten Nur-Skills-Veröffentlichungsalias; Plugin-Pakete sollten +`clawhub package publish` verwenden. ## Dateistruktur ``` /acme-ai/ ├── package.json # openclaw.providers-Metadaten -├── openclaw.plugin.json # Manifest mit Anbieter-Auth-Metadaten +├── openclaw.plugin.json # Manifest mit Provider-Authentifizierungsmetadaten ├── index.ts # definePluginEntry + registerProvider └── src/ ├── provider.test.ts # Tests @@ -700,18 +757,19 @@ Verwenden Sie hier nicht den veralteten Publish-Alias nur für Skills; Plugin-Pa ## Referenz zur Katalogreihenfolge -`catalog.order` steuert, wann Ihr Katalog relativ zu eingebauten Anbietern zusammengeführt wird: +`catalog.order` steuert, wann Ihr Katalog relativ zu integrierten +Providern zusammengeführt wird: -| Order | Wann | Anwendungsfall | -| --------- | ------------- | ----------------------------------------------- | -| `simple` | Erster Durchlauf | Einfache Anbieter mit API-Schlüssel | -| `profile` | Nach simple | Anbieter, die von Auth-Profilen abhängen | -| `paired` | Nach profile | Mehrere verwandte Einträge synthetisieren | -| `late` | Letzter Durchlauf | Vorhandene Anbieter überschreiben (gewinnt bei Kollision) | +| Reihenfolge | Wann | Anwendungsfall | +| ----------- | ------------ | -------------------------------------------- | +| `simple` | Erster Durchlauf | Einfache Provider mit API-Key | +| `profile` | Nach simple | Provider, die von Auth-Profilen abhängen | +| `paired` | Nach profile | Mehrere zusammengehörige Einträge synthetisieren | +| `late` | Letzter Durchlauf | Vorhandene Provider überschreiben (gewinnt bei Kollision) | ## Nächste Schritte - [Kanal-Plugins](/de/plugins/sdk-channel-plugins) — wenn Ihr Plugin auch einen Kanal bereitstellt -- [SDK Runtime](/de/plugins/sdk-runtime) — `api.runtime`-Helper (TTS, Suche, Subagent) -- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Referenz für Subpfad-Importe -- [Plugin-Internals](/de/plugins/architecture#provider-runtime-hooks) — Hook-Details und gebündelte Beispiele +- [SDK-Laufzeit](/de/plugins/sdk-runtime) — Helper für `api.runtime` (TTS, Suche, Subagent) +- [SDK-Überblick](/de/plugins/sdk-overview) — vollständige Referenz für Subpath-Importe +- [Plugin-Interna](/de/plugins/architecture#provider-runtime-hooks) — Hook-Details und gebündelte Beispiele diff --git a/docs/de/tools/acp-agents.md b/docs/de/tools/acp-agents.md index 6ff0323a2..f1698a662 100644 --- a/docs/de/tools/acp-agents.md +++ b/docs/de/tools/acp-agents.md @@ -1,78 +1,78 @@ --- read_when: - - Coding-Harnesses über ACP ausführen - - Konversationsgebundene ACP-Sitzungen auf Messaging-Channels einrichten - - Eine Konversation in einem Message-Channel an eine persistente ACP-Sitzung binden + - Ausführen von Coding-Harnesses über ACP + - Einrichten von gesprächsgebundenen ACP-Sitzungen auf Messaging-Kanälen + - Binden einer Nachrichtenkanal-Konversation an eine persistente ACP-Sitzung - Fehlerbehebung bei ACP-Backend- und Plugin-Verdrahtung - - '`/acp`-Befehle aus dem Chat bedienen' -summary: ACP-Laufzeitsitzungen für Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP und andere Harness-Agenten verwenden + - Bedienen von `/acp`-Befehlen aus dem Chat +summary: Verwenden Sie ACP-Laufzeitsitzungen für Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP und andere Harness-Agenten. title: ACP Agents x-i18n: - generated_at: "2026-04-08T02:20:33Z" + generated_at: "2026-04-21T13:37:25Z" model: gpt-5.4 provider: openai - source_hash: 71c7c0cdae5247aefef17a0029360950a1c2987ddcee21a1bb7d78c67da52950 + source_hash: e458ff21d63e52ed0eed4ed65ba2c45aecae20563a3ef10bf4b64e948284b51a source_path: tools/acp-agents.md workflow: 15 --- -# ACP Agents +# ACP-Agents -Sitzungen mit dem [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) ermöglichen es OpenClaw, externe Coding-Harnesses (zum Beispiel Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI und andere unterstützte ACPX-Harnesses) über ein ACP-Backend-Plugin auszuführen. +Sitzungen des [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) ermöglichen es OpenClaw, externe Coding-Harnesses (zum Beispiel Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI und andere unterstützte ACPX-Harnesses) über ein ACP-Backend-Plugin auszuführen. -Wenn Sie OpenClaw in natürlicher Sprache bitten, „das in Codex auszuführen“ oder „Claude Code in einem Thread zu starten“, sollte OpenClaw diese Anfrage an die ACP-Laufzeit weiterleiten (nicht an die native Subagent-Laufzeit). Jeder ACP-Sitzungsstart wird als [Hintergrundaufgabe](/de/automation/tasks) erfasst. +Wenn Sie OpenClaw in natürlicher Sprache bitten, „das in Codex auszuführen“ oder „Claude Code in einem Thread zu starten“, sollte OpenClaw diese Anfrage an die ACP-Laufzeit weiterleiten (nicht an die native Sub-Agent-Laufzeit). Jeder ACP-Sitzungsstart wird als [Hintergrundaufgabe](/de/automation/tasks) nachverfolgt. -Wenn Sie möchten, dass Codex oder Claude Code sich stattdessen direkt als externer MCP-Client -mit bestehenden OpenClaw-Channel-Konversationen verbinden, verwenden Sie -[`openclaw mcp serve`](/cli/mcp) anstelle von ACP. +Wenn Sie möchten, dass Codex oder Claude Code direkt als externer MCP-Client +mit bestehenden OpenClaw-Kanal-Konversationen verbunden werden, verwenden Sie +anstelle von ACP [`openclaw mcp serve`](/cli/mcp). ## Welche Seite brauche ich? -Es gibt drei benachbarte Oberflächen, die leicht verwechselt werden können: +Es gibt drei nahe verwandte Oberflächen, die leicht verwechselt werden: -| Sie möchten... | Verwenden Sie dies | Hinweise | -| ----------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| Codex, Claude Code, Gemini CLI oder ein anderes externes Harness _durch_ OpenClaw ausführen | Diese Seite: ACP Agents | Chat-gebundene Sitzungen, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, Hintergrundaufgaben, Laufzeitsteuerung | -| Eine OpenClaw-Gateway-Sitzung _als_ ACP-Server für einen Editor oder Client bereitstellen | [`openclaw acp`](/cli/acp) | Bridge-Modus. IDE/Client spricht ACP über stdio/WebSocket mit OpenClaw | -| Eine lokale AI-CLI als reines Text-Fallback-Modell wiederverwenden | [CLI Backends](/de/gateway/cli-backends) | Nicht ACP. Keine OpenClaw-Tools, keine ACP-Steuerung, keine Harness-Laufzeit | +| Sie möchten... | Verwenden Sie dies | Hinweise | +| ----------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| Codex, Claude Code, Gemini CLI oder ein anderes externes Harness _über_ OpenClaw ausführen | Diese Seite: ACP-Agents | Chat-gebundene Sitzungen, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, Hintergrundaufgaben, Laufzeitsteuerung | +| Eine OpenClaw-Gateway-Sitzung _als_ ACP-Server für einen Editor oder Client bereitstellen | [`openclaw acp`](/cli/acp) | Bridge-Modus. IDE/Client spricht ACP mit OpenClaw über stdio/WebSocket | +| Eine lokale AI-CLI als reines Text-Fallback-Modell wiederverwenden | [CLI-Backends](/de/gateway/cli-backends) | Nicht ACP. Keine OpenClaw-Tools, keine ACP-Steuerung, keine Harness-Laufzeit | ## Funktioniert das sofort? Normalerweise ja. -- Frische Installationen werden jetzt standardmäßig mit aktiviertem gebündeltem `acpx`-Laufzeit-Plugin ausgeliefert. +- Frische Installationen werden jetzt standardmäßig mit aktiviertem gebündelten `acpx`-Laufzeit-Plugin ausgeliefert. - Das gebündelte `acpx`-Plugin bevorzugt seine pluginlokal angeheftete `acpx`-Binärdatei. - Beim Start prüft OpenClaw diese Binärdatei und repariert sie bei Bedarf selbst. - Beginnen Sie mit `/acp doctor`, wenn Sie eine schnelle Bereitschaftsprüfung möchten. -Was bei der ersten Verwendung trotzdem passieren kann: +Was bei der ersten Nutzung trotzdem passieren kann: -- Ein Ziel-Harness-Adapter kann bei der ersten Verwendung dieses Harnesses bei Bedarf mit `npx` abgerufen werden. -- Die Vendor-Authentifizierung muss für dieses Harness weiterhin auf dem Host vorhanden sein. -- Wenn der Host keinen npm-/Netzwerkzugriff hat, können Adapter-Abrufe beim ersten Start fehlschlagen, bis Caches vorgewärmt sind oder der Adapter auf andere Weise installiert wurde. +- Ein Ziel-Harness-Adapter kann bei der ersten Verwendung dieses Harnesses bedarfsabhängig mit `npx` abgerufen werden. +- Vendor-Authentifizierung muss auf dem Host für dieses Harness weiterhin vorhanden sein. +- Wenn der Host keinen npm-/Netzwerkzugang hat, kann das erstmalige Abrufen von Adaptern fehlschlagen, bis die Caches vorgewärmt sind oder der Adapter auf andere Weise installiert wird. Beispiele: -- `/acp spawn codex`: OpenClaw sollte bereit sein, `acpx` zu bootstrappen, aber der Codex-ACP-Adapter benötigt möglicherweise trotzdem noch einen Abruf beim ersten Lauf. -- `/acp spawn claude`: dieselbe Situation für den Claude-ACP-Adapter, plus Claude-seitige Authentifizierung auf diesem Host. +- `/acp spawn codex`: OpenClaw sollte bereit sein, `acpx` zu bootstrappen, aber der Codex-ACP-Adapter muss möglicherweise beim ersten Lauf noch abgerufen werden. +- `/acp spawn claude`: dasselbe gilt für den Claude-ACP-Adapter sowie für die Claude-seitige Authentifizierung auf diesem Host. ## Schneller Operator-Ablauf Verwenden Sie dies, wenn Sie ein praktisches `/acp`-Runbook möchten: -1. Starten Sie eine Sitzung: +1. Eine Sitzung starten: - `/acp spawn codex --bind here` - `/acp spawn codex --mode persistent --thread auto` -2. Arbeiten Sie in der gebundenen Konversation oder im Thread (oder adressieren Sie diesen Sitzungsschlüssel explizit). -3. Prüfen Sie den Laufzeitstatus: +2. In der gebundenen Konversation oder im Thread arbeiten (oder diesen Sitzungsschlüssel explizit ansprechen). +3. Laufzeitstatus prüfen: - `/acp status` -4. Passen Sie Laufzeitoptionen bei Bedarf an: +4. Laufzeitoptionen nach Bedarf anpassen: - `/acp model ` - `/acp permissions ` - `/acp timeout ` -5. Geben Sie einer aktiven Sitzung einen Schubs, ohne den Kontext zu ersetzen: +5. Eine aktive Sitzung anstoßen, ohne den Kontext zu ersetzen: - `/acp steer tighten logging and continue` -6. Beenden Sie die Arbeit: +6. Arbeit beenden: - `/acp cancel` (aktuellen Turn stoppen), oder - `/acp close` (Sitzung schließen + Bindungen entfernen) @@ -80,152 +80,152 @@ Verwenden Sie dies, wenn Sie ein praktisches `/acp`-Runbook möchten: Beispiele für natürliche Anfragen: -- „Binde diesen Discord-Channel an Codex.“ -- „Starte hier in einem Thread eine persistente Codex-Sitzung und halte sie fokussiert.“ -- „Führe das als einmalige Claude Code ACP-Sitzung aus und fasse das Ergebnis zusammen.“ -- „Binde diesen iMessage-Chat an Codex und halte Folgeanfragen im selben Workspace.“ -- „Verwende für diese Aufgabe Gemini CLI in einem Thread und halte Folgeanfragen dann in demselben Thread.“ +- „Diesen Discord-Kanal an Codex binden.“ +- „Hier eine persistente Codex-Sitzung in einem Thread starten und fokussiert halten.“ +- „Das als One-Shot-Claude-Code-ACP-Sitzung ausführen und das Ergebnis zusammenfassen.“ +- „Diesen iMessage-Chat an Codex binden und Folgeanfragen im selben Arbeitsbereich behalten.“ +- „Für diese Aufgabe Gemini CLI in einem Thread verwenden und Folgeanfragen dann in demselben Thread behalten.“ Was OpenClaw tun sollte: -1. `runtime: "acp"` auswählen. +1. `runtime: "acp"` wählen. 2. Das angeforderte Harness-Ziel auflösen (`agentId`, zum Beispiel `codex`). -3. Wenn eine Bindung an die aktuelle Konversation angefordert wird und der aktive Channel dies unterstützt, die ACP-Sitzung an diese Konversation binden. -4. Andernfalls, wenn eine Thread-Bindung angefordert wird und der aktuelle Channel dies unterstützt, die ACP-Sitzung an den Thread binden. -5. Folgeanfragen in dieser Bindung an dieselbe ACP-Sitzung weiterleiten, bis sie entfokussiert/geschlossen/abgelaufen ist. +3. Wenn eine Bindung an die aktuelle Konversation angefordert wird und der aktive Kanal dies unterstützt, die ACP-Sitzung an diese Konversation binden. +4. Andernfalls, wenn eine Thread-Bindung angefordert wird und der aktuelle Kanal dies unterstützt, die ACP-Sitzung an den Thread binden. +5. Gebundene Folgenachrichten an dieselbe ACP-Sitzung weiterleiten, bis der Fokus aufgehoben, sie geschlossen oder sie abgelaufen ist. -## ACP im Vergleich zu Subagenten +## ACP versus Sub-Agents -Verwenden Sie ACP, wenn Sie eine externe Harness-Laufzeit möchten. Verwenden Sie Subagenten, wenn Sie delegierte Ausführungen nativ in OpenClaw möchten. +Verwenden Sie ACP, wenn Sie eine externe Harness-Laufzeit möchten. Verwenden Sie Sub-Agents, wenn Sie OpenClaw-native delegierte Ausführungen möchten. -| Bereich | ACP-Sitzung | Subagent-Ausführung | +| Bereich | ACP-Sitzung | Sub-Agent-Ausführung | | ------------- | ------------------------------------- | ----------------------------------- | -| Laufzeit | ACP-Backend-Plugin (zum Beispiel acpx) | Native OpenClaw-Subagent-Laufzeit | +| Laufzeit | ACP-Backend-Plugin (zum Beispiel acpx) | OpenClaw-native Sub-Agent-Laufzeit | | Sitzungsschlüssel | `agent::acp:` | `agent::subagent:` | | Hauptbefehle | `/acp ...` | `/subagents ...` | | Spawn-Tool | `sessions_spawn` mit `runtime:"acp"` | `sessions_spawn` (Standardlaufzeit) | -Siehe auch [Sub-agents](/de/tools/subagents). +Siehe auch [Sub-Agents](/de/tools/subagents). ## Wie ACP Claude Code ausführt -Für Claude Code über ACP ist der Stack: +Für Claude Code über ACP sieht der Stack so aus: -1. OpenClaw-ACP-Sitzungs-Kontrollplane +1. OpenClaw-ACP-Sitzungs-Steuerungsebene 2. gebündeltes `acpx`-Laufzeit-Plugin 3. Claude-ACP-Adapter 4. Claude-seitige Laufzeit-/Sitzungsmechanik Wichtige Unterscheidung: -- ACP Claude ist eine Harness-Sitzung mit ACP-Steuerung, Sitzungsfortsetzung, Hintergrundaufgaben-Tracking und optionaler Konversations-/Thread-Bindung. -- CLI-Backends sind separate lokale Text-Fallback-Laufzeiten. Siehe [CLI Backends](/de/gateway/cli-backends). +- ACP Claude ist eine Harness-Sitzung mit ACP-Steuerung, Sitzungsfortsetzung, Nachverfolgung von Hintergrundaufgaben und optionaler Konversations-/Thread-Bindung. +- CLI-Backends sind separate reine Text-Local-Fallback-Laufzeiten. Siehe [CLI-Backends](/de/gateway/cli-backends). -Für Operatoren gilt praktisch: +Für Operatoren lautet die praktische Regel: -- Wenn Sie `/acp spawn`, bindbare Sitzungen, Laufzeitsteuerung oder persistente Harness-Arbeit möchten: ACP verwenden -- Wenn Sie ein einfaches lokales Text-Fallback über die rohe CLI möchten: CLI-Backends verwenden +- wenn Sie `/acp spawn`, bindbare Sitzungen, Laufzeitsteuerung oder persistente Harness-Arbeit möchten: ACP verwenden +- wenn Sie einfaches lokales Text-Fallback über die rohe CLI möchten: CLI-Backends verwenden ## Gebundene Sitzungen ### Bindungen an die aktuelle Konversation -Verwenden Sie `/acp spawn --bind here`, wenn Sie möchten, dass die aktuelle Konversation zu einem dauerhaften ACP-Workspace wird, ohne einen untergeordneten Thread zu erstellen. +Verwenden Sie `/acp spawn --bind here`, wenn die aktuelle Konversation zu einem dauerhaften ACP-Arbeitsbereich werden soll, ohne einen untergeordneten Thread zu erstellen. Verhalten: -- OpenClaw bleibt Eigentümer von Channel-Transport, Authentifizierung, Sicherheit und Zustellung. +- OpenClaw bleibt Eigentümer von Kanaltransport, Authentifizierung, Sicherheit und Zustellung. - Die aktuelle Konversation wird an den gestarteten ACP-Sitzungsschlüssel angeheftet. -- Folge-Nachrichten in dieser Konversation werden an dieselbe ACP-Sitzung weitergeleitet. +- Folgenachrichten in dieser Konversation werden an dieselbe ACP-Sitzung weitergeleitet. - `/new` und `/reset` setzen dieselbe gebundene ACP-Sitzung an Ort und Stelle zurück. - `/acp close` schließt die Sitzung und entfernt die Bindung an die aktuelle Konversation. Was das in der Praxis bedeutet: -- `--bind here` behält dieselbe Chat-Oberfläche bei. Auf Discord bleibt der aktuelle Channel der aktuelle Channel. -- `--bind here` kann trotzdem eine neue ACP-Sitzung erstellen, wenn Sie neue Arbeit starten. Die Bindung verknüpft diese Sitzung mit der aktuellen Konversation. -- `--bind here` erstellt nicht von selbst einen untergeordneten Discord-Thread oder ein Telegram-Thema. -- Die ACP-Laufzeit kann trotzdem ihr eigenes Arbeitsverzeichnis (`cwd`) oder einen backendverwalteten Workspace auf der Festplatte haben. Dieser Laufzeit-Workspace ist von der Chat-Oberfläche getrennt und impliziert keinen neuen Messaging-Thread. -- Wenn Sie zu einem anderen ACP-Agenten spawnen und kein `--cwd` übergeben, übernimmt OpenClaw standardmäßig den Workspace des **Ziel-Agenten**, nicht den des Anforderers. -- Wenn dieser übernommene Workspace-Pfad fehlt (`ENOENT`/`ENOTDIR`), fällt OpenClaw auf das Standard-`cwd` des Backends zurück, statt stillschweigend den falschen Baum wiederzuverwenden. -- Wenn der übernommene Workspace existiert, aber nicht zugänglich ist (zum Beispiel `EACCES`), gibt der Spawn den echten Zugriffsfehler zurück, statt `cwd` zu verwerfen. +- `--bind here` behält dieselbe Chat-Oberfläche. Auf Discord bleibt der aktuelle Kanal der aktuelle Kanal. +- `--bind here` kann trotzdem eine neue ACP-Sitzung erstellen, wenn Sie frische Arbeit starten. Die Bindung verknüpft diese Sitzung mit der aktuellen Konversation. +- `--bind here` erstellt nicht selbstständig einen untergeordneten Discord-Thread oder ein Telegram-Thema. +- Die ACP-Laufzeit kann weiterhin ihr eigenes Arbeitsverzeichnis (`cwd`) oder einen backendverwalteten Arbeitsbereich auf der Festplatte haben. Dieser Laufzeit-Arbeitsbereich ist von der Chat-Oberfläche getrennt und impliziert keinen neuen Messaging-Thread. +- Wenn Sie zu einem anderen ACP-Agenten starten und `--cwd` nicht übergeben, übernimmt OpenClaw standardmäßig den Arbeitsbereich des **Ziel-Agenten**, nicht den des Anforderers. +- Wenn dieser übernommene Arbeitsbereichspfad fehlt (`ENOENT`/`ENOTDIR`), fällt OpenClaw auf das Standard-`cwd` des Backends zurück, anstatt stillschweigend den falschen Baum wiederzuverwenden. +- Wenn der übernommene Arbeitsbereich existiert, aber nicht zugänglich ist (zum Beispiel `EACCES`), gibt Spawn den tatsächlichen Zugriffsfehler zurück, anstatt `cwd` zu verwerfen. Mentales Modell: -- Chat-Oberfläche: wo Menschen weiter sprechen (`Discord channel`, `Telegram topic`, `iMessage chat`) +- Chat-Oberfläche: wo Menschen weiter reden (`Discord-Kanal`, `Telegram-Thema`, `iMessage-Chat`) - ACP-Sitzung: der dauerhafte Codex-/Claude-/Gemini-Laufzeitzustand, an den OpenClaw weiterleitet - untergeordneter Thread/Thema: eine optionale zusätzliche Messaging-Oberfläche, die nur durch `--thread ...` erstellt wird -- Laufzeit-Workspace: der Dateisystemort, an dem das Harness ausgeführt wird (`cwd`, Repo-Checkout, Backend-Workspace) +- Laufzeit-Arbeitsbereich: der Dateisystemort, an dem das Harness läuft (`cwd`, Repository-Checkout, Backend-Arbeitsbereich) Beispiele: -- `/acp spawn codex --bind here`: diesen Chat beibehalten, eine Codex-ACP-Sitzung starten oder anhängen und zukünftige Nachrichten hierhin weiterleiten -- `/acp spawn codex --thread auto`: OpenClaw kann einen untergeordneten Thread/ein Thema erstellen und die ACP-Sitzung dort binden +- `/acp spawn codex --bind here`: diesen Chat beibehalten, eine Codex-ACP-Sitzung starten oder anhängen und künftige Nachrichten hierhin an sie weiterleiten +- `/acp spawn codex --thread auto`: OpenClaw kann einen untergeordneten Thread/ein Thema erstellen und dort die ACP-Sitzung binden - `/acp spawn codex --bind here --cwd /workspace/repo`: dieselbe Chat-Bindung wie oben, aber Codex läuft in `/workspace/repo` -Unterstützung für die Bindung an die aktuelle Konversation: +Unterstützung für Bindung an die aktuelle Konversation: -- Chat-/Message-Channels, die Unterstützung für die Bindung an die aktuelle Konversation ausweisen, können `--bind here` über den gemeinsamen Konversations-Bindungspfad verwenden. -- Channels mit eigener Thread-/Themen-Semantik können hinter derselben gemeinsamen Schnittstelle weiterhin channelspezifische Kanonisierung bereitstellen. +- Chat-/Nachrichtenkanäle, die die Bindung an die aktuelle Konversation unterstützen, können `--bind here` über den gemeinsamen Konversations-Bindungspfad verwenden. +- Kanäle mit benutzerdefinierter Thread-/Thema-Semantik können hinter derselben gemeinsamen Schnittstelle weiterhin kanalspezifische Kanonisierung bereitstellen. - `--bind here` bedeutet immer „die aktuelle Konversation an Ort und Stelle binden“. - Generische Bindungen an die aktuelle Konversation verwenden den gemeinsamen OpenClaw-Binding-Store und überstehen normale Gateway-Neustarts. Hinweise: - `--bind here` und `--thread ...` schließen sich bei `/acp spawn` gegenseitig aus. -- Auf Discord bindet `--bind here` den aktuellen Channel oder Thread an Ort und Stelle. `spawnAcpSessions` ist nur erforderlich, wenn OpenClaw für `--thread auto|here` einen untergeordneten Thread erstellen muss. -- Wenn der aktive Channel keine ACP-Bindungen an die aktuelle Konversation bereitstellt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt wird. -- `resume` und Fragen nach einer „neuen Sitzung“ sind ACP-Sitzungsfragen, keine Channel-Fragen. Sie können den Laufzeitzustand wiederverwenden oder ersetzen, ohne die aktuelle Chat-Oberfläche zu ändern. +- Auf Discord bindet `--bind here` den aktuellen Kanal oder Thread an Ort und Stelle. `spawnAcpSessions` ist nur erforderlich, wenn OpenClaw für `--thread auto|here` einen untergeordneten Thread erstellen muss. +- Wenn der aktive Kanal keine ACP-Bindungen an die aktuelle Konversation bereitstellt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt wird. +- `resume` und Fragen zu „neuer Sitzung“ sind Fragen zur ACP-Sitzung, nicht zum Kanal. Sie können den Laufzeitzustand wiederverwenden oder ersetzen, ohne die aktuelle Chat-Oberfläche zu ändern. ### Thread-gebundene Sitzungen -Wenn Thread-Bindungen für einen Channel-Adapter aktiviert sind, können ACP-Sitzungen an Threads gebunden werden: +Wenn Thread-Bindungen für einen Kanaladapter aktiviert sind, können ACP-Sitzungen an Threads gebunden werden: - OpenClaw bindet einen Thread an eine Ziel-ACP-Sitzung. -- Folge-Nachrichten in diesem Thread werden an die gebundene ACP-Sitzung weitergeleitet. -- ACP-Ausgaben werden an denselben Thread zurückgeliefert. -- Entfokussieren/Schließen/Archivieren/Ablauf durch Leerlauf-Timeout oder Maximalalter entfernt die Bindung. +- Folgenachrichten in diesem Thread werden an die gebundene ACP-Sitzung weitergeleitet. +- ACP-Ausgaben werden in denselben Thread zurückgeliefert. +- Fokus aufheben/Schließen/Archivieren/Leerlauf-Timeout oder Ablauf des maximalen Alters entfernt die Bindung. -Die Unterstützung für Thread-Bindungen ist adapterspezifisch. Wenn der aktive Channel-Adapter keine Thread-Bindungen unterstützt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt/verfügbar ist. +Die Unterstützung für Thread-Bindungen ist adapterspezifisch. Wenn der aktive Kanaladapter keine Thread-Bindungen unterstützt, gibt OpenClaw eine klare Meldung zurück, dass dies nicht unterstützt/verfügbar ist. -Erforderliche Feature-Flags für threadgebundenes ACP: +Erforderliche Feature-Flags für threadgebundene ACP: - `acp.enabled=true` - `acp.dispatch.enabled` ist standardmäßig aktiviert (auf `false` setzen, um ACP-Dispatch zu pausieren) -- ACP-Thread-Spawn-Flag des Channel-Adapters aktiviert (adapterspezifisch) +- ACP-Thread-Spawn-Flag des Kanaladapters aktiviert (adapterspezifisch) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -### Channels mit Thread-Unterstützung +### Kanäle mit Thread-Unterstützung -- Jeder Channel-Adapter, der die Fähigkeit zur Sitzungs-/Thread-Bindung bereitstellt. -- Aktuelle eingebaute Unterstützung: - - Discord-Threads/-Channels - - Telegram-Themen (Forum-Themen in Gruppen/Supergroups und DM-Themen) -- Plugin-Channels können Unterstützung über dieselbe Binding-Schnittstelle hinzufügen. +- Jeder Kanaladapter, der Sitzungs-/Thread-Bindungsfähigkeit bereitstellt. +- Aktuelle integrierte Unterstützung: + - Discord-Threads/-Kanäle + - Telegram-Themen (Forenthemen in Gruppen/Supergruppen und DM-Themen) +- Plugin-Kanäle können Unterstützung über dieselbe Bindungsschnittstelle hinzufügen. -## Channelspezifische Einstellungen +## Kanalspezifische Einstellungen Für nicht-ephemere Workflows konfigurieren Sie persistente ACP-Bindungen in Top-Level-Einträgen `bindings[]`. -### Binding-Modell +### Bindungsmodell - `bindings[].type="acp"` kennzeichnet eine persistente ACP-Konversationsbindung. - `bindings[].match` identifiziert die Zielkonversation: - - Discord-Channel oder -Thread: `match.channel="discord"` + `match.peer.id=""` - - Telegram-Forum-Thema: `match.channel="telegram"` + `match.peer.id=":topic:"` - - BlueBubbles-DM-/Gruppenchat: `match.channel="bluebubbles"` + `match.peer.id=""` - Bevorzugen Sie `chat_id:*` oder `chat_identifier:*` für stabile Gruppenbindungen. - - iMessage-DM-/Gruppenchat: `match.channel="imessage"` + `match.peer.id=""` - Bevorzugen Sie `chat_id:*` für stabile Gruppenbindungen. -- `bindings[].agentId` ist die zugehörige OpenClaw-Agent-ID. + - Discord-Kanal oder -Thread: `match.channel="discord"` + `match.peer.id=""` + - Telegram-Forenthema: `match.channel="telegram"` + `match.peer.id=":topic:"` + - BlueBubbles-DM/Gruppenchat: `match.channel="bluebubbles"` + `match.peer.id=""` + Für stabile Gruppenbindungen `chat_id:*` oder `chat_identifier:*` bevorzugen. + - iMessage-DM/Gruppenchat: `match.channel="imessage"` + `match.peer.id=""` + Für stabile Gruppenbindungen `chat_id:*` bevorzugen. +- `bindings[].agentId` ist die ID des besitzenden OpenClaw-Agenten. - Optionale ACP-Überschreibungen befinden sich unter `bindings[].acp`: - `mode` (`persistent` oder `oneshot`) - `label` - `cwd` - `backend` -### Laufzeit-Standards pro Agent +### Laufzeitstandards pro Agent Verwenden Sie `agents.list[].runtime`, um ACP-Standards einmal pro Agent zu definieren: @@ -235,7 +235,7 @@ Verwenden Sie `agents.list[].runtime`, um ACP-Standards einmal pro Agent zu defi - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -Priorität von Überschreibungen für gebundene ACP-Sitzungen: +Reihenfolge der Überschreibung für ACP-gebundene Sitzungen: 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` @@ -323,16 +323,16 @@ Beispiel: Verhalten: -- OpenClaw stellt vor der Verwendung sicher, dass die konfigurierte ACP-Sitzung existiert. -- Nachrichten in diesem Channel oder Thema werden an die konfigurierte ACP-Sitzung weitergeleitet. +- OpenClaw stellt sicher, dass die konfigurierte ACP-Sitzung vor der Verwendung existiert. +- Nachrichten in diesem Kanal oder Thema werden an die konfigurierte ACP-Sitzung weitergeleitet. - In gebundenen Konversationen setzen `/new` und `/reset` denselben ACP-Sitzungsschlüssel an Ort und Stelle zurück. -- Temporäre Laufzeit-Bindungen (zum Beispiel erstellt durch Thread-Focus-Abläufe) gelten weiterhin, sofern vorhanden. -- Bei agentübergreifenden ACP-Spawns ohne explizites `cwd` übernimmt OpenClaw den Workspace des Ziel-Agenten aus der Agent-Konfiguration. -- Fehlende übernommene Workspace-Pfade fallen auf das Standard-`cwd` des Backends zurück; echte Zugriffsfehler bei vorhandenen Pfaden werden als Spawn-Fehler ausgegeben. +- Temporäre Laufzeitbindungen (zum Beispiel durch Thread-Focus-Abläufe erstellt) gelten weiterhin, sofern vorhanden. +- Bei agentenübergreifenden ACP-Starts ohne explizites `cwd` übernimmt OpenClaw den Arbeitsbereich des Ziel-Agenten aus der Agentenkonfiguration. +- Fehlende übernommene Arbeitsbereichspfade fallen auf das Standard-`cwd` des Backends zurück; Zugriffsfehler bei vorhandenen Pfaden werden als Spawn-Fehler ausgegeben. ## ACP-Sitzungen starten (Schnittstellen) -### Über `sessions_spawn` +### Aus `sessions_spawn` Verwenden Sie `runtime: "acp"`, um eine ACP-Sitzung aus einem Agent-Turn oder Tool-Aufruf zu starten. @@ -348,29 +348,29 @@ Verwenden Sie `runtime: "acp"`, um eine ACP-Sitzung aus einem Agent-Turn oder To Hinweise: -- `runtime` hat standardmäßig den Wert `subagent`, setzen Sie also für ACP-Sitzungen explizit `runtime: "acp"`. -- Wenn `agentId` weggelassen wird, verwendet OpenClaw `acp.defaultAgent`, sofern konfiguriert. +- `runtime` ist standardmäßig `subagent`, setzen Sie also `runtime: "acp"` explizit für ACP-Sitzungen. +- Wenn `agentId` ausgelassen wird, verwendet OpenClaw `acp.defaultAgent`, falls konfiguriert. - `mode: "session"` erfordert `thread: true`, um eine persistente gebundene Konversation beizubehalten. -Schnittstellendetails: +Details zur Schnittstelle: -- `task` (erforderlich): initialer Prompt, der an die ACP-Sitzung gesendet wird. -- `runtime` (erforderlich für ACP): muss `"acp"` sein. -- `agentId` (optional): ACP-Ziel-Harness-ID. Fällt auf `acp.defaultAgent` zurück, wenn gesetzt. -- `thread` (optional, Standard `false`): Thread-Binding-Ablauf anfordern, wo unterstützt. -- `mode` (optional): `run` (einmalig) oder `session` (persistent). +- `task` (erforderlich): anfänglicher Prompt, der an die ACP-Sitzung gesendet wird. +- `runtime` (für ACP erforderlich): muss `"acp"` sein. +- `agentId` (optional): ACP-Ziel-Harness-ID. Fällt auf `acp.defaultAgent` zurück, falls gesetzt. +- `thread` (optional, Standard `false`): fordert einen Thread-Bindungsablauf an, sofern unterstützt. +- `mode` (optional): `run` (One-Shot) oder `session` (persistent). - Standard ist `run` - - wenn `thread: true` und `mode` weggelassen wird, kann OpenClaw je nach Laufzeitpfad standardmäßig persistentes Verhalten wählen + - wenn `thread: true` und `mode` ausgelassen werden, kann OpenClaw je nach Laufzeitpfad standardmäßig persistentes Verhalten wählen - `mode: "session"` erfordert `thread: true` -- `cwd` (optional): angefordertes Laufzeit-Arbeitsverzeichnis (validiert durch Backend-/Laufzeitrichtlinie). Wenn weggelassen, übernimmt ACP-Spawn bei entsprechender Konfiguration den Workspace des Ziel-Agenten; fehlende übernommene Pfade fallen auf Backend-Standards zurück, während echte Zugriffsfehler zurückgegeben werden. -- `label` (optional): für Operatoren sichtbares Label, das im Sitzungs-/Bannertext verwendet wird. -- `resumeSessionId` (optional): eine vorhandene ACP-Sitzung fortsetzen, statt eine neue zu erstellen. Der Agent spielt den Konversationsverlauf über `session/load` erneut ab. Erfordert `runtime: "acp"`. -- `streamTo` (optional): `"parent"` streamt Zusammenfassungen des Fortschritts des initialen ACP-Laufs als Systemereignisse zurück an die anfordernde Sitzung. - - Wenn verfügbar, enthalten akzeptierte Antworten `streamLogPath`, das auf ein JSONL-Log pro Sitzung verweist (`.acp-stream.jsonl`), das Sie für den vollständigen Relay-Verlauf mitlesen können. +- `cwd` (optional): angefordertes Laufzeit-Arbeitsverzeichnis (validiert durch Backend-/Laufzeitrichtlinie). Wenn ausgelassen, übernimmt ACP-Spawn den Arbeitsbereich des Ziel-Agenten, sofern konfiguriert; fehlende übernommene Pfade fallen auf Backend-Standards zurück, während echte Zugriffsfehler zurückgegeben werden. +- `label` (optional): für Operatoren sichtbares Label, das in Sitzungs-/Banner-Text verwendet wird. +- `resumeSessionId` (optional): setzt eine bestehende ACP-Sitzung fort, anstatt eine neue zu erstellen. Der Agent spielt seinen Gesprächsverlauf über `session/load` erneut ein. Erfordert `runtime: "acp"`. +- `streamTo` (optional): `"parent"` streamt Fortschrittszusammenfassungen des anfänglichen ACP-Laufs als Systemereignisse zurück an die anfordernde Sitzung. + - Wenn verfügbar, enthalten akzeptierte Antworten `streamLogPath`, das auf ein sitzungsbezogenes JSONL-Log (`.acp-stream.jsonl`) zeigt, das Sie für den vollständigen Relay-Verlauf beobachten können. -### Eine vorhandene Sitzung fortsetzen +### Eine bestehende Sitzung fortsetzen -Verwenden Sie `resumeSessionId`, um eine frühere ACP-Sitzung fortzusetzen, statt neu zu starten. Der Agent spielt den Konversationsverlauf über `session/load` erneut ab, sodass er mit dem vollständigen Kontext des Vorherigen fortsetzt. +Verwenden Sie `resumeSessionId`, um eine frühere ACP-Sitzung fortzusetzen, statt neu zu starten. Der Agent spielt seinen Gesprächsverlauf über `session/load` erneut ein, sodass er mit dem vollständigen Kontext dessen fortfährt, was zuvor geschehen ist. ```json { @@ -384,34 +384,34 @@ Verwenden Sie `resumeSessionId`, um eine frühere ACP-Sitzung fortzusetzen, stat Häufige Anwendungsfälle: - Eine Codex-Sitzung vom Laptop auf das Telefon übergeben — weisen Sie Ihren Agenten an, dort weiterzumachen, wo Sie aufgehört haben -- Eine Coding-Sitzung fortsetzen, die Sie interaktiv in der CLI begonnen haben, jetzt headless über Ihren Agenten -- Arbeit fortsetzen, die durch einen Gateway-Neustart oder ein Idle-Timeout unterbrochen wurde +- Eine Coding-Sitzung fortsetzen, die Sie interaktiv in der CLI begonnen haben und jetzt headless über Ihren Agenten weiterführen +- Arbeit wieder aufnehmen, die durch einen Gateway-Neustart oder ein Leerlauf-Timeout unterbrochen wurde Hinweise: -- `resumeSessionId` erfordert `runtime: "acp"` — gibt einen Fehler zurück, wenn es mit der Subagent-Laufzeit verwendet wird. -- `resumeSessionId` stellt den vorgelagerten ACP-Konversationsverlauf wieder her; `thread` und `mode` gelten weiterhin normal für die neue OpenClaw-Sitzung, die Sie erstellen, daher erfordert `mode: "session"` weiterhin `thread: true`. +- `resumeSessionId` erfordert `runtime: "acp"` — gibt einen Fehler zurück, wenn es mit der Sub-Agent-Laufzeit verwendet wird. +- `resumeSessionId` stellt den vorgelagerten ACP-Gesprächsverlauf wieder her; `thread` und `mode` gelten weiterhin normal für die neue OpenClaw-Sitzung, die Sie erstellen, daher erfordert `mode: "session"` weiterhin `thread: true`. - Der Ziel-Agent muss `session/load` unterstützen (Codex und Claude Code tun das). -- Wenn die Sitzungs-ID nicht gefunden wird, schlägt der Spawn mit einem klaren Fehler fehl — kein stiller Fallback auf eine neue Sitzung. +- Wenn die Sitzungs-ID nicht gefunden wird, schlägt der Spawn mit einem klaren Fehler fehl — kein stilles Zurückfallen auf eine neue Sitzung. -### Operator-Smoketest +### Operator-Smoke-Test -Verwenden Sie dies nach einem Gateway-Deploy, wenn Sie schnell live prüfen möchten, dass ACP-Spawn -wirklich Ende-zu-Ende funktioniert und nicht nur Unit-Tests besteht. +Verwenden Sie dies nach einem Gateway-Deployment, wenn Sie eine schnelle Live-Prüfung möchten, dass ACP-Spawn +tatsächlich Ende-zu-Ende funktioniert und nicht nur Unit-Tests besteht. Empfohlenes Gate: -1. Prüfen Sie die bereitgestellte Gateway-Version/den Commit auf dem Ziel-Host. -2. Bestätigen Sie, dass der bereitgestellte Quellcode die ACP-Lineage-Akzeptanz in +1. Überprüfen Sie die deployte Gateway-Version/den Commit auf dem Ziel-Host. +2. Bestätigen Sie, dass der deployte Quellcode die ACP-Lineage-Akzeptanz in `src/gateway/sessions-patch.ts` enthält (`subagent:* or acp:* sessions`). 3. Öffnen Sie eine temporäre ACPX-Bridge-Sitzung zu einem Live-Agenten (zum Beispiel `razor(main)` auf `jpclawhq`). -4. Bitten Sie diesen Agenten, `sessions_spawn` mit Folgendem aufzurufen: +4. Bitten Sie diesen Agenten, `sessions_spawn` aufzurufen mit: - `runtime: "acp"` - `agentId: "codex"` - `mode: "run"` - - Aufgabe: `Reply with exactly LIVE-ACP-SPAWN-OK` -5. Verifizieren Sie, dass der Agent Folgendes meldet: + - task: `Reply with exactly LIVE-ACP-SPAWN-OK` +5. Verifizieren Sie, dass der Agent meldet: - `accepted=yes` - einen echten `childSessionKey` - keinen Validator-Fehler @@ -427,11 +427,11 @@ Then report only: accepted=; childSessionKey=; error=` | -| `/acp steer` | Steueranweisung an laufende Sitzung senden. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Sitzung schließen und Thread-Ziele entbinden. | `/acp close` | -| `/acp status` | Backend, Modus, Status, Laufzeitoptionen, Fähigkeiten anzeigen. | `/acp status` | -| `/acp set-mode` | Laufzeitmodus für die Zielsitzung setzen. | `/acp set-mode plan` | -| `/acp set` | Generisches Schreiben einer Laufzeit-Konfigurationsoption. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | Überschreibung für das Laufzeit-Arbeitsverzeichnis setzen. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | Profil der Genehmigungsrichtlinie setzen. | `/acp permissions strict` | -| `/acp timeout` | Laufzeit-Timeout (Sekunden) setzen. | `/acp timeout 120` | -| `/acp model` | Überschreibung des Laufzeitmodells setzen. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | Überschreibungen der Sitzungs-Laufzeitoptionen entfernen. | `/acp reset-options` | -| `/acp sessions` | Aktuelle ACP-Sitzungen aus dem Store auflisten. | `/acp sessions` | -| `/acp doctor` | Backend-Zustand, Fähigkeiten, umsetzbare Behebungen. | `/acp doctor` | -| `/acp install` | Deterministische Installations- und Aktivierungsschritte ausgeben. | `/acp install` | +| Befehl | Funktion | Beispiel | +| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------------- | +| `/acp spawn` | ACP-Sitzung erstellen; optionale aktuelle Bindung oder Thread-Bindung. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Laufenden Turn für die Zielsitzung abbrechen. | `/acp cancel agent:codex:acp:` | +| `/acp steer` | Steueranweisung an eine laufende Sitzung senden. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | Sitzung schließen und Thread-Ziele entbinden. | `/acp close` | +| `/acp status` | Backend, Modus, Zustand, Laufzeitoptionen und Fähigkeiten anzeigen. | `/acp status` | +| `/acp set-mode` | Laufzeitmodus für die Zielsitzung festlegen. | `/acp set-mode plan` | +| `/acp set` | Generischen Laufzeit-Konfigurationswert schreiben. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | Überschreibung des Laufzeit-Arbeitsverzeichnisses setzen. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | Profil für die Genehmigungsrichtlinie festlegen. | `/acp permissions strict` | +| `/acp timeout` | Laufzeit-Timeout (Sekunden) festlegen. | `/acp timeout 120` | +| `/acp model` | Überschreibung des Laufzeitmodells festlegen. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options`| Überschreibungen der Sitzungs-Laufzeitoptionen entfernen. | `/acp reset-options` | +| `/acp sessions` | Kürzlich verwendete ACP-Sitzungen aus dem Store auflisten. | `/acp sessions` | +| `/acp doctor` | Backend-Gesundheit, Fähigkeiten, umsetzbare Korrekturen. | `/acp doctor` | +| `/acp install` | Deterministische Installations- und Aktivierungsschritte ausgeben. | `/acp install` | -`/acp sessions` liest den Store für die aktuell gebundene Sitzung oder die Sitzung des Anforderers. Befehle, die `session-key`-, `session-id`- oder `session-label`-Token akzeptieren, lösen Ziele über die Gateway-Sitzungserkennung auf, einschließlich benutzerdefinierter `session.store`-Wurzeln pro Agent. +`/acp sessions` liest den Store für die aktuelle gebundene oder anfordernde Sitzung. Befehle, die Tokens vom Typ `session-key`, `session-id` oder `session-label` akzeptieren, lösen Ziele über die Gateway-Sitzungserkennung auf, einschließlich benutzerdefinierter `session.store`-Wurzeln pro Agent. -## Zuordnung von Laufzeitoptionen +## Abbildung von Laufzeitoptionen `/acp` hat Komfortbefehle und einen generischen Setter. Äquivalente Operationen: -- `/acp model ` wird dem Laufzeit-Konfigurationsschlüssel `model` zugeordnet. -- `/acp permissions ` wird dem Laufzeit-Konfigurationsschlüssel `approval_policy` zugeordnet. -- `/acp timeout ` wird dem Laufzeit-Konfigurationsschlüssel `timeout` zugeordnet. -- `/acp cwd ` aktualisiert die Überschreibung des Laufzeit-`cwd` direkt. +- `/acp model ` wird auf den Laufzeit-Konfigurationsschlüssel `model` abgebildet. +- `/acp permissions ` wird auf den Laufzeit-Konfigurationsschlüssel `approval_policy` abgebildet. +- `/acp timeout ` wird auf den Laufzeit-Konfigurationsschlüssel `timeout` abgebildet. +- `/acp cwd ` aktualisiert direkt die Überschreibung des Laufzeit-`cwd`. - `/acp set ` ist der generische Pfad. - - Spezialfall: `key=cwd` verwendet den Pfad für die `cwd`-Überschreibung. -- `/acp reset-options` löscht alle Laufzeit-Überschreibungen für die Zielsitzung. + - Sonderfall: `key=cwd` verwendet den Pfad für die `cwd`-Überschreibung. +- `/acp reset-options` löscht alle Laufzeitüberschreibungen für die Zielsitzung. -## Unterstützung für acpx-Harnesses (aktuell) +## acpx-Harness-Unterstützung (aktuell) -Aktuelle eingebaute acpx-Harness-Aliasse: +Aktuelle integrierte acpx-Harness-Aliasse: - `claude` - `codex` @@ -599,19 +599,19 @@ Aktuelle eingebaute acpx-Harness-Aliasse: - `qwen` Wenn OpenClaw das acpx-Backend verwendet, bevorzugen Sie diese Werte für `agentId`, sofern Ihre acpx-Konfiguration keine benutzerdefinierten Agent-Aliasse definiert. -Wenn Ihre lokale Cursor-Installation ACP weiterhin als `agent acp` bereitstellt, überschreiben Sie den Befehl des `cursor`-Agenten in Ihrer acpx-Konfiguration, statt den eingebauten Standard zu ändern. +Wenn Ihre lokale Cursor-Installation ACP weiterhin als `agent acp` bereitstellt, überschreiben Sie stattdessen den Agent-Befehl `cursor` in Ihrer acpx-Konfiguration, anstatt den integrierten Standard zu ändern. -Die direkte Verwendung der acpx-CLI kann auch beliebige Adapter über `--agent ` ansteuern, aber dieser rohe Escape Hatch ist eine Funktion der acpx-CLI (nicht der normale OpenClaw-`agentId`-Pfad). +Die direkte Verwendung der acpx-CLI kann über `--agent ` auch beliebige Adapter ansprechen, aber dieser rohe Escape-Hatch ist eine acpx-CLI-Funktion (nicht der normale OpenClaw-`agentId`-Pfad). ## Erforderliche Konfiguration -Core-ACP-Baseline: +ACP-Basis in Core: ```json5 { acp: { enabled: true, - // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls. + // Optional. Standard ist true; auf false setzen, um ACP-Dispatch zu pausieren und /acp-Steuerungen beizubehalten. dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -643,7 +643,7 @@ Core-ACP-Baseline: } ``` -Die Konfiguration von Thread-Bindings ist channelspezifisch. Beispiel für Discord: +Die Thread-Bindungskonfiguration ist kanadapter-spezifisch. Beispiel für Discord: ```json5 { @@ -669,14 +669,14 @@ Wenn threadgebundener ACP-Spawn nicht funktioniert, prüfen Sie zuerst das Featu - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` -Bindungen an die aktuelle Konversation erfordern keine Erstellung eines untergeordneten Threads. Sie erfordern einen aktiven Konversationskontext und einen Channel-Adapter, der ACP-Konversationsbindungen bereitstellt. +Bindungen an die aktuelle Konversation erfordern keine Erstellung eines untergeordneten Threads. Sie erfordern einen aktiven Konversationskontext und einen Kanaladapter, der ACP-Konversationsbindungen bereitstellt. -Siehe [Configuration Reference](/de/gateway/configuration-reference). +Siehe [Konfigurationsreferenz](/de/gateway/configuration-reference). -## Plugin-Setup für das acpx-Backend +## Plugin-Einrichtung für das acpx-Backend -Frische Installationen werden standardmäßig mit aktiviertem gebündeltem `acpx`-Laufzeit-Plugin ausgeliefert, daher funktioniert ACP -normalerweise ohne einen manuellen Schritt zur Plugin-Installation. +Frische Installationen werden standardmäßig mit aktiviertem gebündelten `acpx`-Laufzeit-Plugin ausgeliefert, daher +funktioniert ACP normalerweise ohne einen manuellen Plugin-Installationsschritt. Beginnen Sie mit: @@ -684,7 +684,7 @@ Beginnen Sie mit: /acp doctor ``` -Wenn Sie `acpx` deaktiviert haben, es über `plugins.allow` / `plugins.deny` verweigert haben oder +Wenn Sie `acpx` deaktiviert, es über `plugins.allow` / `plugins.deny` verweigert oder zu einem lokalen Entwicklungs-Checkout wechseln möchten, verwenden Sie den expliziten Plugin-Pfad: ```bash @@ -698,20 +698,20 @@ Lokale Workspace-Installation während der Entwicklung: openclaw plugins install ./path/to/local/acpx-plugin ``` -Prüfen Sie dann den Zustand des Backends: +Prüfen Sie dann die Backend-Gesundheit: ```text /acp doctor ``` -### Konfiguration von acpx-Befehl und -Version +### Konfiguration von acpx-Befehl und Version Standardmäßig verwendet das gebündelte acpx-Backend-Plugin (`acpx`) die pluginlokal angeheftete Binärdatei: 1. Der Befehl ist standardmäßig die pluginlokale `node_modules/.bin/acpx` innerhalb des ACPX-Plugin-Pakets. -2. Die erwartete Version ist standardmäßig an die Extension-Pin gebunden. +2. Die erwartete Version ist standardmäßig die Anheftung der Extension. 3. Beim Start wird das ACP-Backend sofort als nicht bereit registriert. -4. Ein Hintergrund-Ensure-Job prüft `acpx --version`. +4. Ein Ensure-Job im Hintergrund prüft `acpx --version`. 5. Wenn die pluginlokale Binärdatei fehlt oder nicht übereinstimmt, wird Folgendes ausgeführt: `npm install --omit=dev --no-save acpx@` und anschließend erneut geprüft. @@ -736,120 +736,133 @@ Sie können Befehl/Version in der Plugin-Konfiguration überschreiben: Hinweise: - `command` akzeptiert einen absoluten Pfad, relativen Pfad oder Befehlsnamen (`acpx`). -- Relative Pfade werden ausgehend vom OpenClaw-Workspace-Verzeichnis aufgelöst. -- `expectedVersion: "any"` deaktiviert die strikte Versionsprüfung. +- Relative Pfade werden vom OpenClaw-Workspace-Verzeichnis aus aufgelöst. +- `expectedVersion: "any"` deaktiviert strikte Versionsprüfung. - Wenn `command` auf eine benutzerdefinierte Binärdatei/einen benutzerdefinierten Pfad zeigt, wird die pluginlokale Auto-Installation deaktiviert. -- Der OpenClaw-Start bleibt nicht blockierend, während die Zustandsprüfung des Backends läuft. +- Der OpenClaw-Start bleibt nicht blockierend, während die Backend-Gesundheitsprüfung läuft. Siehe [Plugins](/de/tools/plugin). ### Automatische Abhängigkeitsinstallation Wenn Sie OpenClaw global mit `npm install -g openclaw` installieren, werden die acpx- -Laufzeitabhängigkeiten (plattformspezifische Binärdateien) automatisch über einen Postinstall-Hook installiert. Wenn die automatische Installation fehlschlägt, startet das Gateway trotzdem +Laufzeitabhängigkeiten (plattformspezifische Binärdateien) automatisch +über einen Postinstall-Hook installiert. Falls die automatische Installation fehlschlägt, startet das Gateway dennoch normal und meldet die fehlende Abhängigkeit über `openclaw acp doctor`. -### Plugin-Tools-MCP-Bridge +### MCP-Bridge für Plugin-Tools Standardmäßig stellen ACPX-Sitzungen **keine** von OpenClaw-Plugins registrierten Tools für das ACP-Harness bereit. Wenn Sie möchten, dass ACP-Agenten wie Codex oder Claude Code installierte -OpenClaw-Plugin-Tools wie Memory recall/store aufrufen können, aktivieren Sie die dedizierte Bridge: +OpenClaw-Plugin-Tools wie Memory Recall/Store aufrufen können, aktivieren Sie die dedizierte Bridge: ```bash openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true ``` -Das bewirkt Folgendes: +Was dies bewirkt: -- Es injiziert einen eingebauten MCP-Server namens `openclaw-plugin-tools` in den ACPX-Sitzungs- +- Injiziert einen integrierten MCP-Server namens `openclaw-plugin-tools` in den ACPX-Sitzungs- Bootstrap. -- Es stellt Plugin-Tools bereit, die bereits von installierten und aktivierten OpenClaw- +- Stellt Plugin-Tools bereit, die bereits von installierten und aktivierten OpenClaw- Plugins registriert wurden. -- Das Feature bleibt explizit und standardmäßig deaktiviert. +- Hält die Funktion explizit und standardmäßig deaktiviert. Sicherheits- und Vertrauenshinweise: -- Dadurch wird die Tool-Oberfläche des ACP-Harnesses erweitert. -- ACP-Agenten erhalten nur Zugriff auf Plugin-Tools, die bereits im Gateway aktiv sind. -- Behandeln Sie dies als dieselbe Vertrauensgrenze, wie diesen Plugins die Ausführung in - OpenClaw selbst zu erlauben. -- Prüfen Sie installierte Plugins, bevor Sie es aktivieren. +- Dies erweitert die Tool-Oberfläche des ACP-Harnesses. +- ACP-Agenten erhalten nur Zugriff auf Plugin-Tools, die im Gateway bereits aktiv sind. +- Betrachten Sie dies als dieselbe Vertrauensgrenze wie das Ausführen dieser Plugins + in OpenClaw selbst. +- Prüfen Sie installierte Plugins, bevor Sie dies aktivieren. -Benutzerdefinierte `mcpServers` funktionieren weiterhin wie bisher. Die eingebaute -Plugin-Tools-Bridge ist eine zusätzliche optionale Bequemlichkeit und kein Ersatz für generische MCP-Server-Konfiguration. +Benutzerdefinierte `mcpServers` funktionieren weiterhin wie bisher. Die integrierte Plugin-Tools-Bridge ist +eine zusätzliche optionale Komfortfunktion, kein Ersatz für generische MCP-Server-Konfiguration. ### Konfiguration des Laufzeit-Timeouts -Das gebündelte `acpx`-Plugin setzt standardmäßig für eingebettete Laufzeit-Turns ein -Timeout von 120 Sekunden. Das gibt langsameren Harnesses wie Gemini CLI genug Zeit, den -ACP-Start und die Initialisierung abzuschließen. Überschreiben Sie dies, wenn Ihr Host ein anderes +Das gebündelte `acpx`-Plugin setzt für eingebettete Laufzeit-Turns standardmäßig ein +Timeout von 120 Sekunden. Das gibt langsameren Harnesses wie Gemini CLI genügend Zeit, um +ACP-Start und Initialisierung abzuschließen. Überschreiben Sie dies, wenn Ihr Host ein anderes Laufzeitlimit benötigt: ```bash openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 ``` -Starten Sie das Gateway nach dem Ändern dieses Werts neu. +Starten Sie das Gateway neu, nachdem Sie diesen Wert geändert haben. -## Konfiguration von Berechtigungen +### Konfiguration des Agents für Health-Probes -ACP-Sitzungen laufen nicht interaktiv — es gibt kein TTY, um Berechtigungsabfragen für Dateischreib- und Shell-Exec-Vorgänge zu bestätigen oder abzulehnen. Das acpx-Plugin stellt zwei Konfigurationsschlüssel bereit, die steuern, wie Berechtigungen behandelt werden: +Das gebündelte `acpx`-Plugin prüft ein Harness-Agent, während es entscheidet, ob das +eingebettete Laufzeit-Backend bereit ist. Standard ist `codex`. Wenn Ihr Deployment +einen anderen Standard-ACP-Agenten verwendet, setzen Sie den Probe-Agenten auf dieselbe ID: -Diese ACPX-Harness-Berechtigungen sind getrennt von OpenClaw-Exec-Genehmigungen und getrennt von CLI-Backend-Vendor-Bypass-Flags wie Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` ist der Break-Glass-Schalter auf Harness-Ebene für ACP-Sitzungen. +```bash +openclaw config set plugins.entries.acpx.config.probeAgent claude +``` + +Starten Sie das Gateway neu, nachdem Sie diesen Wert geändert haben. + +## Berechtigungskonfiguration + +ACP-Sitzungen laufen nicht interaktiv — es gibt kein TTY, um Aufforderungen zur Genehmigung oder Ablehnung von Schreibzugriffen auf Dateien und Shell-Ausführung zu bestätigen. Das acpx-Plugin stellt zwei Konfigurationsschlüssel bereit, die steuern, wie Berechtigungen behandelt werden: + +Diese ACPX-Harness-Berechtigungen sind getrennt von OpenClaw-Exec-Genehmigungen und getrennt von Vendor-Bypass-Flags der CLI-Backends wie Claude-CLI `--permission-mode bypassPermissions`. ACPX `approve-all` ist der Harness-seitige Break-Glass-Schalter für ACP-Sitzungen. ### `permissionMode` -Steuert, welche Operationen der Harness-Agent ohne Rückfrage ausführen kann. +Steuert, welche Operationen der Harness-Agent ohne Aufforderung ausführen kann. -| Wert | Verhalten | +| Wert | Verhalten | | ---------------- | -------------------------------------------------------- | -| `approve-all` | Alle Dateischreib- und Shell-Befehle automatisch genehmigen. | -| `approve-reads` | Nur Lesevorgänge automatisch genehmigen; Schreibvorgänge und Exec erfordern Prompts. | -| `deny-all` | Alle Berechtigungsabfragen ablehnen. | +| `approve-all` | Alle Dateischreibvorgänge und Shell-Befehle automatisch genehmigen. | +| `approve-reads` | Nur Lesevorgänge automatisch genehmigen; Schreibvorgänge und Ausführung erfordern Aufforderungen. | +| `deny-all` | Alle Berechtigungsaufforderungen ablehnen. | ### `nonInteractivePermissions` -Steuert, was passiert, wenn eine Berechtigungsabfrage angezeigt würde, aber kein interaktives TTY verfügbar ist (was bei ACP-Sitzungen immer der Fall ist). +Steuert, was passiert, wenn eine Berechtigungsaufforderung angezeigt würde, aber kein interaktives TTY verfügbar ist (was bei ACP-Sitzungen immer der Fall ist). | Wert | Verhalten | | ------ | ---------------------------------------------------------------- | | `fail` | Sitzung mit `AcpRuntimeError` abbrechen. **(Standard)** | -| `deny` | Die Berechtigung stillschweigend verweigern und fortfahren (Graceful Degradation). | +| `deny` | Berechtigung stillschweigend verweigern und fortfahren (Graceful Degradation). | ### Konfiguration -Über Plugin-Konfiguration setzen: +Über die Plugin-Konfiguration setzen: ```bash openclaw config set plugins.entries.acpx.config.permissionMode approve-all openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail ``` -Starten Sie das Gateway nach dem Ändern dieser Werte neu. +Starten Sie das Gateway neu, nachdem Sie diese Werte geändert haben. -> **Wichtig:** OpenClaw verwendet derzeit standardmäßig `permissionMode=approve-reads` und `nonInteractivePermissions=fail`. In nicht interaktiven ACP-Sitzungen kann jeder Schreib- oder Exec-Vorgang, der eine Berechtigungsabfrage auslöst, mit `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` fehlschlagen. +> **Wichtig:** OpenClaw verwendet derzeit standardmäßig `permissionMode=approve-reads` und `nonInteractivePermissions=fail`. In nicht interaktiven ACP-Sitzungen kann jeder Schreib- oder Ausführungsvorgang, der eine Berechtigungsaufforderung auslöst, mit `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` fehlschlagen. > -> Wenn Sie Berechtigungen einschränken müssen, setzen Sie `nonInteractivePermissions` auf `deny`, damit Sitzungen sich kontrolliert verschlechtern, statt abzustürzen. +> Wenn Sie Berechtigungen einschränken müssen, setzen Sie `nonInteractivePermissions` auf `deny`, damit Sitzungen sich kontrolliert verschlechtern, anstatt abzustürzen. ## Fehlerbehebung -| Symptom | Wahrscheinliche Ursache | Behebung | -| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ACP runtime backend is not configured` | Backend-Plugin fehlt oder ist deaktiviert. | Backend-Plugin installieren und aktivieren, dann `/acp doctor` ausführen. | -| `ACP is disabled by policy (acp.enabled=false)` | ACP ist global deaktiviert. | `acp.enabled=true` setzen. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch aus normalen Thread-Nachrichten ist deaktiviert. | `acp.dispatch.enabled=true` setzen. | -| `ACP agent "" is not allowed by policy` | Agent ist nicht in der Allowlist. | Erlaubte `agentId` verwenden oder `acp.allowedAgents` aktualisieren. | -| `Unable to resolve session target: ...` | Ungültiges Schlüssel-/ID-/Label-Token. | `/acp sessions` ausführen, exakten Schlüssel/Label kopieren, erneut versuchen. | -| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` wurde ohne aktive bindbare Konversation verwendet. | Zum Ziel-Chat/-Channel wechseln und erneut versuchen oder ungebundenen Spawn verwenden. | -| `Conversation bindings are unavailable for .` | Adapter besitzt keine ACP-Bindungsfähigkeit für aktuelle Konversationen. | `/acp spawn ... --thread ...` verwenden, wo unterstützt, Top-Level-`bindings[]` konfigurieren oder zu einem unterstützten Channel wechseln. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` wurde außerhalb eines Thread-Kontexts verwendet. | Zum Ziel-Thread wechseln oder `--thread auto`/`off` verwenden. | -| `Only can rebind this channel/conversation/thread.` | Ein anderer Benutzer besitzt das aktive Binding-Ziel. | Als Eigentümer neu binden oder eine andere Konversation bzw. einen anderen Thread verwenden. | -| `Thread bindings are unavailable for .` | Adapter besitzt keine Thread-Bindungsfähigkeit. | `--thread off` verwenden oder zu einem unterstützten Adapter/Channel wechseln. | -| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP-Laufzeit läuft auf dem Host; die anfordernde Sitzung ist sandboxed. | `runtime="subagent"` aus sandboxed Sitzungen verwenden oder ACP-Spawn aus einer nicht sandboxed Sitzung ausführen. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` wurde für die ACP-Laufzeit angefordert. | `runtime="subagent"` für obligatorische Sandbox-Ausführung verwenden oder ACP mit `sandbox="inherit"` aus einer nicht sandboxed Sitzung verwenden. | -| Missing ACP metadata for bound session | Veraltete/gelöschte ACP-Sitzungsmetadaten. | Mit `/acp spawn` neu erstellen und dann Thread erneut binden/fokussieren. | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blockiert Schreib-/Exec-Vorgänge in nicht interaktiver ACP-Sitzung. | `plugins.entries.acpx.config.permissionMode` auf `approve-all` setzen und Gateway neu starten. Siehe [Konfiguration von Berechtigungen](#konfiguration-von-berechtigungen). | -| ACP-Sitzung schlägt früh mit wenig Ausgabe fehl | Berechtigungsabfragen werden durch `permissionMode`/`nonInteractivePermissions` blockiert. | Gateway-Logs auf `AcpRuntimeError` prüfen. Für vollständige Berechtigungen `permissionMode=approve-all` setzen; für Graceful Degradation `nonInteractivePermissions=deny` setzen. | -| ACP-Sitzung hängt nach Abschluss der Arbeit unbegrenzt | Harness-Prozess ist beendet, aber die ACP-Sitzung hat den Abschluss nicht gemeldet. | Mit `ps aux \| grep acpx` überwachen; veraltete Prozesse manuell beenden. | +| Symptom | Wahrscheinliche Ursache | Behebung | +| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `ACP runtime backend is not configured` | Backend-Plugin fehlt oder ist deaktiviert. | Backend-Plugin installieren und aktivieren, dann `/acp doctor` ausführen. | +| `ACP is disabled by policy (acp.enabled=false)` | ACP ist global deaktiviert. | `acp.enabled=true` setzen. | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch aus normalen Thread-Nachrichten ist deaktiviert. | `acp.dispatch.enabled=true` setzen. | +| `ACP agent "" is not allowed by policy` | Agent ist nicht in der Allowlist. | Erlaubte `agentId` verwenden oder `acp.allowedAgents` aktualisieren. | +| `Unable to resolve session target: ...` | Ungültiges Schlüssel-/ID-/Label-Token. | `/acp sessions` ausführen, exakten Schlüssel/das exakte Label kopieren und erneut versuchen. | +| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` wurde ohne aktive bindbare Konversation verwendet. | In den Ziel-Chat/-Kanal wechseln und erneut versuchen oder ungebundenen Spawn verwenden. | +| `Conversation bindings are unavailable for .` | Adapter hat keine ACP-Bindungsfähigkeit für die aktuelle Konversation. | Unterstützt, `/acp spawn ... --thread ...` verwenden, Top-Level-`bindings[]` konfigurieren oder zu einem unterstützten Kanal wechseln. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` wurde außerhalb eines Thread-Kontexts verwendet. | In den Ziel-Thread wechseln oder `--thread auto`/`off` verwenden. | +| `Only can rebind this channel/conversation/thread.` | Ein anderer Benutzer besitzt das aktive Bindungsziel. | Als Eigentümer neu binden oder eine andere Konversation bzw. einen anderen Thread verwenden. | +| `Thread bindings are unavailable for .` | Adapter hat keine Thread-Bindungsfähigkeit. | `--thread off` verwenden oder zu einem unterstützten Adapter/Kanal wechseln. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP-Laufzeit ist hostseitig; die anfordernde Sitzung läuft in einer Sandbox. | In Sandbox-Sitzungen `runtime="subagent"` verwenden oder ACP-Spawn aus einer nicht sandboxierten Sitzung ausführen. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | `sandbox="require"` wurde für die ACP-Laufzeit angefordert. | Für erforderliche Sandbox-Verwendung `runtime="subagent"` nutzen oder ACP mit `sandbox="inherit"` aus einer nicht sandboxierten Sitzung verwenden. | +| Missing ACP metadata for bound session | Veraltete/gelöschte ACP-Sitzungsmetadaten. | Mit `/acp spawn` neu erstellen, dann Thread neu binden/fokussieren. | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` blockiert Schreiben/Ausführen in einer nicht interaktiven ACP-Sitzung. | `plugins.entries.acpx.config.permissionMode` auf `approve-all` setzen und das Gateway neu starten. Siehe [Berechtigungskonfiguration](#permission-configuration). | +| ACP session fails early with little output | Berechtigungsaufforderungen werden durch `permissionMode`/`nonInteractivePermissions` blockiert. | Gateway-Logs auf `AcpRuntimeError` prüfen. Für volle Berechtigungen `permissionMode=approve-all` setzen; für Graceful Degradation `nonInteractivePermissions=deny`. | +| ACP session stalls indefinitely after completing work | Harness-Prozess ist beendet, aber die ACP-Sitzung hat den Abschluss nicht gemeldet. | Mit `ps aux \| grep acpx` überwachen; veraltete Prozesse manuell beenden. | diff --git a/docs/de/tools/agent-send.md b/docs/de/tools/agent-send.md index b8e2ab5c7..28ee69a8a 100644 --- a/docs/de/tools/agent-send.md +++ b/docs/de/tools/agent-send.md @@ -1,14 +1,14 @@ --- read_when: - - Sie möchten Agent-Läufe aus Skripten oder über die Befehlszeile auslösen - - Sie müssen Agent-Antworten programmgesteuert an einen Chat-Kanal zustellen -summary: Agent-Züge über die CLI ausführen und Antworten optional an Kanäle zustellen + - Sie möchten Agent-Ausführungen über Skripte oder die Befehlszeile auslösen. + - Sie müssen Agent-Antworten programmgesteuert an einen Chat-Channel zustellen. +summary: Führen Sie Agent-Züge über die CLI aus und stellen Sie Antworten optional an Channels zu. title: Agent Send x-i18n: - generated_at: "2026-04-05T12:56:22Z" + generated_at: "2026-04-21T13:37:13Z" model: gpt-5.4 provider: openai - source_hash: 42ea2977e89fb28d2afd07e5f6b1560ad627aea8b72fde36d8e324215c710afc + source_hash: 0550ad38efb2711f267a62b905fd150987a98801247de780ed3df97f27245704 source_path: tools/agent-send.md workflow: 15 --- @@ -16,7 +16,7 @@ x-i18n: # Agent Send `openclaw agent` führt einen einzelnen Agent-Zug über die Befehlszeile aus, ohne dass -eine eingehende Chat-Nachricht erforderlich ist. Verwenden Sie es für skriptgesteuerte Workflows, Tests und +eine eingehende Chat-Nachricht erforderlich ist. Verwenden Sie ihn für skriptgesteuerte Workflows, Tests und programmgesteuerte Zustellung. ## Schnellstart @@ -31,7 +31,7 @@ programmgesteuerte Zustellung. - + ```bash # Einen bestimmten Agenten ansprechen openclaw agent --agent ops --message "Summarize logs" @@ -45,9 +45,9 @@ programmgesteuerte Zustellung. - + ```bash - # An WhatsApp zustellen (Standardkanal) + # An WhatsApp zustellen (Standard-Channel) openclaw agent --to +15555550123 --message "Report ready" --deliver # An Slack zustellen @@ -60,32 +60,32 @@ programmgesteuerte Zustellung. ## Flags -| Flag | Beschreibung | -| ----------------------------- | ---------------------------------------------------------- | -| `--message \` | Zu sendende Nachricht (erforderlich) | -| `--to \` | Sitzungsschlüssel aus einem Ziel ableiten (Telefon, Chat-ID) | -| `--agent \` | Einen konfigurierten Agenten ansprechen (verwendet seine `main`-Sitzung) | -| `--session-id \` | Eine vorhandene Sitzung anhand der ID wiederverwenden | -| `--local` | Lokale eingebettete Laufzeit erzwingen (Gateway überspringen) | -| `--deliver` | Die Antwort an einen Chat-Kanal senden | -| `--channel \` | Zustellkanal (whatsapp, telegram, discord, slack usw.) | -| `--reply-to \` | Überschreibung des Zustellziels | -| `--reply-channel \` | Überschreibung des Zustellkanals | -| `--reply-account \` | Überschreibung der Zustellkonto-ID | -| `--thinking \` | Thinking-Level setzen (off, minimal, low, medium, high, xhigh) | -| `--verbose \` | Verbose-Level setzen | -| `--timeout \` | Agent-Timeout überschreiben | -| `--json` | Strukturiertes JSON ausgeben | +| Flag | Beschreibung | +| ----------------------------- | ----------------------------------------------------------- | +| `--message \` | Zu sendende Nachricht (erforderlich) | +| `--to \` | Leitet den Sitzungsschlüssel aus einem Ziel ab (Telefon, Chat-ID) | +| `--agent \` | Spricht einen konfigurierten Agenten an (verwendet dessen `main`-Sitzung) | +| `--session-id \` | Verwendet eine vorhandene Sitzung anhand ihrer ID wieder | +| `--local` | Erzwingt die lokal eingebettete Runtime (Gateway überspringen) | +| `--deliver` | Sendet die Antwort an einen Chat-Channel | +| `--channel \` | Zustell-Channel (whatsapp, telegram, discord, slack usw.) | +| `--reply-to \` | Überschreibung des Zustellziels | +| `--reply-channel \` | Überschreibung des Zustell-Channels | +| `--reply-account \` | Überschreibung der Zustell-Konto-ID | +| `--thinking \` | Setzt die Thinking-Stufe für das ausgewählte Modellprofil | +| `--verbose \` | Setzt die Verbose-Stufe | +| `--timeout \` | Überschreibt das Agent-Timeout | +| `--json` | Gibt strukturiertes JSON aus | ## Verhalten - Standardmäßig läuft die CLI **über das Gateway**. Fügen Sie `--local` hinzu, um die - eingebettete Laufzeit auf der aktuellen Maschine zu erzwingen. -- Wenn das Gateway nicht erreichbar ist, fällt die CLI **auf den lokalen eingebetteten Lauf** zurück. -- Sitzungsauswahl: `--to` leitet den Sitzungsschlüssel ab (Gruppen-/Kanalziele + eingebettete Runtime auf dem aktuellen Rechner zu erzwingen. +- Wenn das Gateway nicht erreichbar ist, fällt die CLI **auf die lokale eingebettete Ausführung** zurück. +- Sitzungsauswahl: `--to` leitet den Sitzungsschlüssel ab (Gruppen-/Channel-Ziele behalten die Isolation bei; direkte Chats werden zu `main` zusammengeführt). - Thinking- und Verbose-Flags werden im Sitzungsspeicher persistiert. -- Ausgabe: standardmäßig Klartext oder mit `--json` als strukturierte Payload + Metadaten. +- Ausgabe: standardmäßig Klartext oder mit `--json` strukturierte Payload + Metadaten. ## Beispiele @@ -93,15 +93,15 @@ programmgesteuerte Zustellung. # Einfacher Zug mit JSON-Ausgabe openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json -# Zug mit Thinking-Level +# Zug mit Thinking-Stufe openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium -# An einen anderen Kanal als die Sitzung zustellen +# An einen anderen Channel als die Sitzung zustellen openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin" ``` -## Verwandte Themen +## Verwandt -- [Referenz zur Agent-CLI](/cli/agent) -- [Sub-Agents](/tools/subagents) — Erzeugen von Sub-Agenten im Hintergrund +- [Agent-CLI-Referenz](/cli/agent) +- [Unter-Agenten](/de/tools/subagents) — Spawn von Hintergrund-Unter-Agenten - [Sitzungen](/de/concepts/session) — wie Sitzungsschlüssel funktionieren diff --git a/docs/de/tools/exec-approvals.md b/docs/de/tools/exec-approvals.md index 9e8f67aae..fa2bd7e6b 100644 --- a/docs/de/tools/exec-approvals.md +++ b/docs/de/tools/exec-approvals.md @@ -1,74 +1,74 @@ --- read_when: - - Konfigurieren von Ausführungsfreigaben oder Zulassungslisten - - Implementierung der UX für Ausführungsfreigaben in der macOS-App - - Überprüfung von Sandbox-Escape-Aufforderungen und ihren Auswirkungen -summary: Ausführungsfreigaben, Zulassungslisten und Sandbox-Escape-Aufforderungen -title: Ausführungsfreigaben + - Exec-Genehmigungen oder Allowlists konfigurieren + - Exec-Genehmigungs-UX in der macOS-App implementieren + - Aufforderungen zum Verlassen der Sandbox und deren Auswirkungen prüfen +summary: Exec-Genehmigungen, Allowlists und Aufforderungen zum Verlassen der Sandbox +title: Exec-Genehmigungen x-i18n: - generated_at: "2026-04-10T06:21:34Z" + generated_at: "2026-04-21T13:37:25Z" model: gpt-5.4 provider: openai - source_hash: 5f4a2e2f1f3c13a1d1926c9de0720513ea8a74d1ca571dbe74b188d8c560c14c + source_hash: 0738108dd21e24eb6317d437b7ac693312743eddc3ec295ba62c4e60356cb33e source_path: tools/exec-approvals.md workflow: 15 --- -# Ausführungsfreigaben +# Exec-Genehmigungen -Ausführungsfreigaben sind die **Sicherheitsleitplanke der Companion-App bzw. des Node-Hosts**, damit ein in einer Sandbox ausgeführter Agent Befehle auf einem echten Host (`gateway` oder `node`) ausführen kann. Sie funktionieren wie eine Sicherheitsverriegelung: -Befehle sind nur erlaubt, wenn Richtlinie + Zulassungsliste + (optionale) Benutzerfreigabe alle zustimmen. -Ausführungsfreigaben gelten **zusätzlich** zur Tool-Richtlinie und zu Elevated-Gating (außer wenn Elevated auf `full` gesetzt ist; dann werden Freigaben übersprungen). -Die effektive Richtlinie ist die **strengere** von `tools.exec.*` und den Standardwerten für Freigaben; wenn ein Feld bei den Freigaben weggelassen wird, wird stattdessen der Wert aus `tools.exec` verwendet. -Die Host-Ausführung verwendet außerdem den lokalen Freigabestatus auf diesem Rechner. Ein hostlokales -`ask: "always"` in `~/.openclaw/exec-approvals.json` sorgt weiterhin für Eingabeaufforderungen, auch wenn -Sitzungs- oder Konfigurationsstandardwerte `ask: "on-miss"` anfordern. +Exec-Genehmigungen sind die **Schutzmaßnahme der Companion-App / des Node-Hosts**, damit ein in einer Sandbox ausgeführter Agent +Befehle auf einem echten Host (`gateway` oder `node`) ausführen darf. Verstehen Sie das wie eine Sicherheitsverriegelung: +Befehle sind nur erlaubt, wenn Richtlinie + Allowlist + (optionale) Benutzerfreigabe alle übereinstimmen. +Exec-Genehmigungen gelten **zusätzlich** zur Tool-Richtlinie und zum Elevated-Gating (außer wenn elevated auf `full` gesetzt ist; dann werden Genehmigungen übersprungen). +Die wirksame Richtlinie ist die **strengere** von `tools.exec.*` und den Standardwerten der Genehmigungen; wenn ein Genehmigungsfeld fehlt, wird der Wert aus `tools.exec` verwendet. +Host-Exec verwendet auch den lokalen Genehmigungsstatus auf diesem Rechner. Ein hostlokales +`ask: "always"` in `~/.openclaw/exec-approvals.json` sorgt weiterhin für Rückfragen, selbst wenn +Sitzungs- oder Konfigurationsstandards `ask: "on-miss"` anfordern. Verwenden Sie `openclaw approvals get`, `openclaw approvals get --gateway` oder `openclaw approvals get --node `, um die angeforderte Richtlinie, -die Quellen der Host-Richtlinie und das effektive Ergebnis zu prüfen. +die Quellen der Host-Richtlinie und das wirksame Ergebnis zu prüfen. Für den lokalen Rechner zeigt `openclaw exec-policy show` dieselbe zusammengeführte Ansicht an, und `openclaw exec-policy set|preset` kann die lokal angeforderte Richtlinie in einem Schritt mit der -lokalen Host-Freigabedatei synchronisieren. Wenn ein lokaler Geltungsbereich `host=node` anfordert, -meldet `openclaw exec-policy show` diesen Geltungsbereich zur Laufzeit als von einem Node verwaltet, statt -so zu tun, als wäre die lokale Freigabedatei die tatsächlich maßgebliche Quelle. +lokalen Host-Genehmigungsdatei synchronisieren. Wenn ein lokaler Geltungsbereich `host=node` anfordert, +meldet `openclaw exec-policy show` diesen Geltungsbereich zur Laufzeit als Node-verwaltet, statt +vorzutäuschen, dass die lokale Genehmigungsdatei die tatsächlich maßgebliche Quelle ist. -Wenn die UI der Companion-App **nicht verfügbar** ist, wird jede Anforderung, die eine Eingabeaufforderung benötigt, -über das **ask-Fallback** aufgelöst (Standard: deny). +Wenn die UI der Companion-App **nicht verfügbar** ist, wird jede Anfrage, die eine Rückfrage erfordert, +durch den **Ask-Fallback** aufgelöst (Standard: deny). -Native Chat-Freigabe-Clients können außerdem kanalspezifische Bedienelemente in der ausstehenden -Freigabenachricht anzeigen. Matrix kann zum Beispiel Reaktionskürzel in der -Freigabeaufforderung vorbelegen (`✅` einmal erlauben, `❌` verweigern und `♾️` immer erlauben, sofern verfügbar), -während die `/approve ...`-Befehle in der Nachricht weiterhin als Fallback bleiben. +Native Chat-Genehmigungsclients können auf der ausstehenden Genehmigungsnachricht auch kanalspezifische Bedienmöglichkeiten anbieten. Matrix kann zum Beispiel Reaktionskürzel auf der +Genehmigungsabfrage vorbereiten (`✅` einmal erlauben, `❌` ablehnen und `♾️` immer erlauben, wenn verfügbar) +und trotzdem die `/approve ...`-Befehle als Fallback in der Nachricht belassen. ## Wo dies gilt -Ausführungsfreigaben werden lokal auf dem Ausführungshost durchgesetzt: +Exec-Genehmigungen werden lokal auf dem Ausführungshost erzwungen: -- **gateway-Host** → `openclaw`-Prozess auf dem Gateway-Rechner -- **node-Host** → Node-Runner (macOS-Companion-App oder kopfloser Node-Host) +- **Gateway-Host** → `openclaw`-Prozess auf dem Gateway-Rechner +- **Node-Host** → Node-Runner (macOS-Companion-App oder Headless-Node-Host) Hinweis zum Vertrauensmodell: -- Über das Gateway authentifizierte Aufrufer sind vertrauenswürdige Operatoren für dieses Gateway. -- Gekoppelte Nodes erweitern diese vertrauenswürdige Operatorfähigkeit auf den Node-Host. -- Ausführungsfreigaben verringern das Risiko versehentlicher Ausführung, sind aber keine Authentifizierungsgrenze pro Benutzer. +- Für das Gateway authentifizierte Aufrufer sind vertrauenswürdige Operatoren für dieses Gateway. +- Gekoppelte Nodes erweitern diese Fähigkeit als vertrauenswürdiger Operator auf den Node-Host. +- Exec-Genehmigungen verringern das Risiko versehentlicher Ausführung, sind aber keine Authentifizierungsgrenze pro Benutzer. - Genehmigte Ausführungen auf dem Node-Host binden den kanonischen Ausführungskontext: kanonisches cwd, exaktes argv, env-Bindung - sofern vorhanden und angehefteter Pfad zur ausführbaren Datei, falls zutreffend. + falls vorhanden und angehefteten ausführbaren Pfad, sofern zutreffend. - Für Shell-Skripte und direkte Interpreter-/Runtime-Dateiaufrufe versucht OpenClaw außerdem, - genau einen konkreten lokalen Dateiopeanden zu binden. Wenn sich diese gebundene Datei nach der - Freigabe, aber vor der Ausführung ändert, wird die Ausführung verweigert, statt Inhalte mit Abweichungen auszuführen. -- Diese Dateibindung ist absichtlich nur nach bestem Bemühen implementiert, nicht als vollständiges semantisches Modell jedes - Interpreter-/Runtime-Ladepfads. Wenn der Freigabemodus nicht genau eine konkrete lokale Datei zur Bindung identifizieren kann, - wird die Erzeugung einer freigabegestützten Ausführung verweigert, statt eine vollständige Abdeckung vorzutäuschen. + genau einen konkreten lokalen Dateiopeanden zu binden. Wenn sich diese gebundene Datei nach der Genehmigung, aber vor der Ausführung ändert, + wird die Ausführung verweigert, statt abgewichenen Inhalt auszuführen. +- Diese Dateibindung ist absichtlich Best-Effort und kein vollständiges semantisches Modell jedes + Interpreter-/Runtime-Ladepfads. Wenn der Genehmigungsmodus nicht genau eine konkrete lokale + Datei zur Bindung identifizieren kann, verweigert er die Erstellung einer genehmigungsgestützten Ausführung, statt vollständige Abdeckung vorzutäuschen. macOS-Aufteilung: -- Der **node host service** leitet `system.run` über lokale IPC an die **macOS-App** weiter. -- Die **macOS-App** erzwingt Freigaben und führt den Befehl im UI-Kontext aus. +- **Node-Host-Service** leitet `system.run` über lokales IPC an die **macOS-App** weiter. +- **macOS-App** erzwingt Genehmigungen und führt den Befehl im UI-Kontext aus. ## Einstellungen und Speicherung -Freigaben werden in einer lokalen JSON-Datei auf dem Ausführungshost gespeichert: +Genehmigungen liegen in einer lokalen JSON-Datei auf dem Ausführungshost: `~/.openclaw/exec-approvals.json` @@ -107,14 +107,14 @@ Beispielschema: } ``` -## Modus „YOLO“ ohne Freigaben +## „YOLO“-Modus ohne Genehmigungen -Wenn Sie möchten, dass die Host-Ausführung ohne Freigabeaufforderungen ausgeführt wird, müssen Sie **beide** Richtlinienebenen öffnen: +Wenn Host-Exec ohne Genehmigungsabfragen ausgeführt werden soll, müssen Sie **beide** Richtlinienebenen öffnen: -- angeforderte Ausführungsrichtlinie in der OpenClaw-Konfiguration (`tools.exec.*`) -- hostlokale Freigaberichtlinie in `~/.openclaw/exec-approvals.json` +- angeforderte Exec-Richtlinie in der OpenClaw-Konfiguration (`tools.exec.*`) +- hostlokale Genehmigungsrichtlinie in `~/.openclaw/exec-approvals.json` -Dies ist jetzt das Standardverhalten für den Host, sofern Sie es nicht explizit verschärfen: +Dies ist jetzt das Standardverhalten für Hosts, sofern Sie es nicht explizit verschärfen: - `tools.exec.security`: `full` auf `gateway`/`node` - `tools.exec.ask`: `off` @@ -122,15 +122,15 @@ Dies ist jetzt das Standardverhalten für den Host, sofern Sie es nicht explizit Wichtige Unterscheidung: -- `tools.exec.host=auto` wählt aus, wo die Ausführung stattfindet: in der Sandbox, wenn verfügbar, andernfalls auf dem Gateway. -- YOLO wählt aus, wie die Host-Ausführung freigegeben wird: `security=full` plus `ask=off`. -- Im YOLO-Modus legt OpenClaw keine zusätzliche heuristische Freigabeschranke für Befehlsverschleierung über die konfigurierte Host-Ausführungsrichtlinie. -- `auto` macht Gateway-Routing nicht zu einer freien Umgehung aus einer Sandbox-Sitzung heraus. Eine Anforderung pro Aufruf mit `host=node` ist aus `auto` heraus erlaubt, und `host=gateway` ist aus `auto` nur dann erlaubt, wenn keine Sandbox-Runtime aktiv ist. Wenn Sie einen stabilen Standardwert ohne `auto` möchten, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...` explizit. +- `tools.exec.host=auto` wählt aus, wo Exec ausgeführt wird: in der Sandbox, wenn verfügbar, andernfalls auf dem Gateway. +- YOLO wählt aus, wie Host-Exec genehmigt wird: `security=full` plus `ask=off`. +- Im YOLO-Modus fügt OpenClaw keine zusätzliche heuristische Genehmigungsschranke für Befehlsverschleierung und keine Skript-Preflight-Ablehnungsebene zusätzlich zur konfigurierten Host-Exec-Richtlinie hinzu. +- `auto` macht Gateway-Routing nicht zu einer freien Umgehung aus einer Sandbox-Sitzung heraus. Eine Anfrage pro Aufruf mit `host=node` ist von `auto` aus erlaubt, und `host=gateway` ist von `auto` aus nur erlaubt, wenn keine Sandbox-Runtime aktiv ist. Wenn Sie einen stabilen Nicht-`auto`-Standard wollen, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...` explizit. -Wenn Sie eine konservativere Einrichtung möchten, verschärfen Sie eine der Ebenen wieder auf `allowlist` / `on-miss` +Wenn Sie ein konservativeres Setup möchten, verschärfen Sie eine der beiden Ebenen wieder auf `allowlist` / `on-miss` oder `deny`. -Dauerhafte Einrichtung „nie nachfragen“ für den Gateway-Host: +Dauerhafte Einrichtung „nie nachfragen“ für Gateway-Hosts: ```bash openclaw config set tools.exec.host gateway @@ -139,7 +139,7 @@ openclaw config set tools.exec.ask off openclaw gateway restart ``` -Setzen Sie dann die Host-Freigabedatei passend dazu: +Setzen Sie dann die Host-Genehmigungsdatei entsprechend: ```bash openclaw approvals set --stdin <<'EOF' @@ -154,22 +154,22 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -Lokale Abkürzung für dieselbe Gateway-Host-Richtlinie auf dem aktuellen Rechner: +Lokale Kurzform für dieselbe Gateway-Host-Richtlinie auf dem aktuellen Rechner: ```bash openclaw exec-policy preset yolo ``` -Diese lokale Abkürzung aktualisiert beides: +Diese lokale Kurzform aktualisiert beides: - lokale `tools.exec.host/security/ask` - lokale Standardwerte in `~/.openclaw/exec-approvals.json` -Sie ist absichtlich nur lokal wirksam. Wenn Sie Freigaben für Gateway-Host oder Node-Host +Sie ist absichtlich nur lokal. Wenn Sie Genehmigungen für Gateway-Hosts oder Node-Hosts remote ändern müssen, verwenden Sie weiterhin `openclaw approvals set --gateway` oder `openclaw approvals set --node `. -Für einen Node-Host wenden Sie stattdessen dieselbe Freigabedatei auf diesem Node an: +Für einen Node-Host wenden Sie stattdessen dieselbe Genehmigungsdatei auf diesem Node an: ```bash openclaw approvals set --node --stdin <<'EOF' @@ -186,43 +186,43 @@ EOF Wichtige Einschränkung nur für lokal: -- `openclaw exec-policy` synchronisiert keine Node-Freigaben +- `openclaw exec-policy` synchronisiert keine Node-Genehmigungen - `openclaw exec-policy set --host node` wird abgelehnt -- Node-Ausführungsfreigaben werden zur Laufzeit vom Node abgerufen, daher müssen Node-bezogene Aktualisierungen über `openclaw approvals --node ...` erfolgen +- Node-Exec-Genehmigungen werden zur Laufzeit vom Node abgerufen, daher müssen zielgerichtete Aktualisierungen für Nodes `openclaw approvals --node ...` verwenden -Abkürzung nur für die Sitzung: +Kurzform nur für die Sitzung: - `/exec security=full ask=off` ändert nur die aktuelle Sitzung. -- `/elevated full` ist eine Break-Glass-Abkürzung, die Ausführungsfreigaben für diese Sitzung ebenfalls überspringt. +- `/elevated full` ist eine Notfall-Kurzform, die für diese Sitzung auch Exec-Genehmigungen überspringt. -Wenn die Host-Freigabedatei strenger bleibt als die Konfiguration, gewinnt weiterhin die strengere Host-Richtlinie. +Wenn die Host-Genehmigungsdatei strenger bleibt als die Konfiguration, gewinnt weiterhin die strengere Host-Richtlinie. -## Richtlinienoptionen +## Richtlinienschalter -### Security (`exec.security`) +### Sicherheit (`exec.security`) -- **deny**: blockiert alle Anfragen zur Host-Ausführung. -- **allowlist**: erlaubt nur Befehle auf der Zulassungsliste. -- **full**: erlaubt alles (entspricht elevated). +- **deny**: alle Host-Exec-Anfragen blockieren. +- **allowlist**: nur Befehle aus der Allowlist erlauben. +- **full**: alles erlauben (entspricht elevated). ### Ask (`exec.ask`) -- **off**: niemals nachfragen. -- **on-miss**: nur nachfragen, wenn die Zulassungsliste nicht passt. +- **off**: nie nachfragen. +- **on-miss**: nur nachfragen, wenn die Allowlist nicht passt. - **always**: bei jedem Befehl nachfragen. -- Dauerhaftes Vertrauen über `allow-always` unterdrückt Eingabeaufforderungen nicht, wenn der effektive ask-Modus `always` ist +- Dauerhaftes Vertrauen per `allow-always` unterdrückt Rückfragen nicht, wenn der wirksame Ask-Modus `always` ist ### Ask-Fallback (`askFallback`) -Wenn eine Eingabeaufforderung erforderlich ist, aber keine UI erreichbar ist, entscheidet das Fallback: +Wenn eine Rückfrage erforderlich ist, aber keine UI erreichbar ist, entscheidet der Fallback: - **deny**: blockieren. -- **allowlist**: nur erlauben, wenn die Zulassungsliste passt. +- **allowlist**: nur erlauben, wenn die Allowlist passt. - **full**: erlauben. -### Härtung für Inline-Interpreterauswertung (`tools.exec.strictInlineEval`) +### Härtung für Inline-Interpreter-Eval (`tools.exec.strictInlineEval`) -Wenn `tools.exec.strictInlineEval=true`, behandelt OpenClaw Formen der Inline-Codeauswertung als nur per Freigabe erlaubt, auch wenn das Interpreter-Binary selbst auf der Zulassungsliste steht. +Wenn `tools.exec.strictInlineEval=true`, behandelt OpenClaw Inline-Code-Eval-Formen als nur nach Genehmigung erlaubt, selbst wenn die Interpreter-Binärdatei selbst in der Allowlist steht. Beispiele: @@ -234,18 +234,18 @@ Beispiele: - `lua -e` - `osascript -e` -Dies ist eine zusätzliche Schutzmaßnahme für Interpreter-Lader, die sich nicht sauber auf einen stabilen Dateiopeanden abbilden lassen. Im strikten Modus gilt: +Dies ist Defense-in-Depth für Interpreter-Loader, die sich nicht sauber auf einen stabilen Dateiopeanden abbilden lassen. Im strikten Modus: -- diese Befehle benötigen weiterhin eine explizite Freigabe; -- `allow-always` speichert für sie nicht automatisch neue Zulassungslisteneinträge. +- benötigen diese Befehle weiterhin eine explizite Genehmigung; +- persistiert `allow-always` dafür nicht automatisch neue Allowlist-Einträge. -## Zulassungsliste (pro Agent) +## Allowlist (pro Agent) -Zulassungslisten gelten **pro Agent**. Wenn mehrere Agents vorhanden sind, wechseln Sie in der -macOS-App zu dem Agent, den Sie bearbeiten möchten. Muster sind **globale Abgleiche ohne Beachtung der Groß-/Kleinschreibung**. -Muster sollten zu **Binary-Pfaden** aufgelöst werden (Einträge nur mit Basename werden ignoriert). -Veraltete `agents.default`-Einträge werden beim Laden nach `agents.main` migriert. -Shell-Verkettungen wie `echo ok && pwd` erfordern weiterhin, dass jedes Segment der obersten Ebene die Regeln der Zulassungsliste erfüllt. +Allowlists gelten **pro Agent**. Wenn mehrere Agenten vorhanden sind, wechseln Sie in der macOS-App den Agenten, +den Sie bearbeiten. Muster sind **globale Übereinstimmungen ohne Beachtung der Groß-/Kleinschreibung**. +Muster sollten zu **Binärpfaden** aufgelöst werden (Einträge nur mit Basename werden ignoriert). +Alte `agents.default`-Einträge werden beim Laden nach `agents.main` migriert. +Shell-Ketten wie `echo ok && pwd` erfordern weiterhin, dass jedes Top-Level-Segment die Allowlist-Regeln erfüllt. Beispiele: @@ -253,45 +253,44 @@ Beispiele: - `~/.local/bin/*` - `/opt/homebrew/bin/rg` -Jeder Eintrag in der Zulassungsliste erfasst: +Jeder Allowlist-Eintrag verfolgt: - **id** stabile UUID für die UI-Identität (optional) - **last used** Zeitstempel - **last used command** - **last resolved path** -## CLI von Skills automatisch zulassen +## Skill-CLIs automatisch erlauben -Wenn **CLI von Skills automatisch zulassen** aktiviert ist, werden ausführbare Dateien, auf die bekannte Skills verweisen, -auf Nodes (macOS-Node oder kopfloser Node-Host) als auf der Zulassungsliste behandelt. Dazu wird -`skills.bins` über Gateway-RPC verwendet, um die Binärdateiliste des Skills abzurufen. Deaktivieren Sie dies, wenn Sie strikte manuelle Zulassungslisten möchten. +Wenn **Auto-allow skill CLIs** aktiviert ist, werden von bekannten Skills referenzierte ausführbare Dateien +auf Nodes (macOS-Node oder Headless-Node-Host) als auf der Allowlist behandelt. Dabei wird +`skills.bins` über die Gateway-RPC verwendet, um die Liste der Skill-Binaries abzurufen. Deaktivieren Sie dies, wenn Sie strikte manuelle Allowlists möchten. -Wichtige Hinweise zum Vertrauensmodell: +Wichtige Vertrauenshinweise: -- Dies ist eine **implizite Komfort-Zulassungsliste**, getrennt von manuellen Pfadeinträgen in der Zulassungsliste. -- Sie ist für vertrauenswürdige Operatorumgebungen gedacht, in denen Gateway und Node innerhalb derselben Vertrauensgrenze liegen. -- Wenn Sie striktes explizites Vertrauen benötigen, lassen Sie `autoAllowSkills: false` gesetzt und verwenden Sie nur manuelle Pfadeinträge in der Zulassungsliste. +- Dies ist eine **implizite Convenience-Allowlist**, getrennt von manuellen Pfad-Allowlist-Einträgen. +- Sie ist für vertrauenswürdige Operatorumgebungen gedacht, in denen Gateway und Node dieselbe Vertrauensgrenze teilen. +- Wenn Sie striktes explizites Vertrauen benötigen, belassen Sie `autoAllowSkills: false` und verwenden Sie nur manuelle Pfad-Allowlist-Einträge. ## Sichere Binaries (nur stdin) -`tools.exec.safeBins` definiert eine kleine Liste von **nur-stdin**-Binaries (zum Beispiel `cut`), -die im Modus `allowlist` **ohne** explizite Einträge in der Zulassungsliste ausgeführt werden können. Sichere Binaries lehnen -positionale Dateiar gumente und pfadähnliche Token ab, sodass sie nur auf dem eingehenden Stream arbeiten können. +`tools.exec.safeBins` definiert eine kleine Liste von **nur-stdin**-Binärdateien (zum Beispiel `cut`), +die im Allowlist-Modus **ohne** explizite Allowlist-Einträge ausgeführt werden können. Sichere Binaries lehnen +positionale Dateiar gumente und pfadähnliche Tokens ab, sodass sie nur auf dem eingehenden Stream arbeiten können. Behandeln Sie dies als engen Schnellpfad für Stream-Filter, nicht als allgemeine Vertrauensliste. Fügen Sie **keine** Interpreter- oder Runtime-Binaries (zum Beispiel `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) zu `safeBins` hinzu. -Wenn ein Befehl Code auswerten, Unterbefehle ausführen oder konstruktionsbedingt Dateien lesen kann, bevorzugen Sie explizite Einträge in der Zulassungsliste und lassen Sie Freigabeaufforderungen aktiviert. +Wenn ein Befehl Code auswerten, Unterbefehle ausführen oder per Design Dateien lesen kann, bevorzugen Sie explizite Allowlist-Einträge und lassen Sie Genehmigungsabfragen aktiviert. Benutzerdefinierte sichere Binaries müssen ein explizites Profil in `tools.exec.safeBinProfiles.` definieren. -Die Validierung ist allein anhand der Form von argv deterministisch (keine Prüfungen auf Dateiexistenz im Host-Dateisystem), was -Oracle-Verhalten über Dateiexistenz durch Unterschiede zwischen Erlauben und Verweigern verhindert. -Dateiorientierte Optionen werden für Standard-Safe-Bins verweigert (zum Beispiel `sort -o`, `sort --output`, +Die Validierung erfolgt deterministisch allein aus der argv-Form (keine Host-Dateisystem-Existenzprüfungen), +wodurch Oracle-Verhalten zur Dateiexistenz durch Allow/Deny-Unterschiede verhindert wird. +Dateiorientierte Optionen werden für standardmäßige sichere Binaries abgelehnt (zum Beispiel `sort -o`, `sort --output`, `sort --files0-from`, `sort --compress-program`, `sort --random-source`, `sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`, `grep -f/--file`). -Sichere Binaries erzwingen außerdem eine explizite Richtlinie pro Binary für Flags, die das Nur-stdin- -Verhalten aufheben (zum Beispiel `sort -o/--output/--compress-program` und rekursive grep-Flags). -Lange Optionen werden im Safe-Bin-Modus fehlersicher validiert: unbekannte Flags und mehrdeutige +Sichere Binaries erzwingen außerdem eine explizite Richtlinie pro Binärdatei für Flags, die das Nur-stdin-Verhalten aufheben (zum Beispiel `sort -o/--output/--compress-program` und rekursive grep-Flags). +Lange Optionen werden im Modus für sichere Binaries fail-closed validiert: unbekannte Flags und mehrdeutige Abkürzungen werden abgelehnt. -Durch Safe-Bin-Profile verweigerte Flags: +Abgelehnte Flags nach Safe-Bin-Profil: [//]: # "SAFE_BIN_DENIED_FLAGS:START" @@ -302,34 +301,34 @@ Durch Safe-Bin-Profile verweigerte Flags: [//]: # "SAFE_BIN_DENIED_FLAGS:END" -Sichere Binaries erzwingen außerdem, dass argv-Token zur Ausführungszeit als **wörtlicher Text** behandelt werden (kein Globbing -und keine `$VARS`-Erweiterung) für Nur-stdin-Segmente, sodass Muster wie `*` oder `$HOME/...` nicht -zum Einschleusen von Dateilesen verwendet werden können. -Sichere Binaries müssen außerdem aus vertrauenswürdigen Binary-Verzeichnissen aufgelöst werden (Systemstandards plus optionale -`tools.exec.safeBinTrustedDirs`). `PATH`-Einträge werden niemals automatisch als vertrauenswürdig behandelt. -Die standardmäßig vertrauenswürdigen Verzeichnisse für sichere Binaries sind absichtlich minimal: `/bin`, `/usr/bin`. -Wenn sich Ihr Safe-Bin-Executable in Paketmanager- oder Benutzerpfaden befindet (zum Beispiel +Sichere Binaries erzwingen außerdem, dass argv-Tokens zur Ausführungszeit als **wörtlicher Text** behandelt werden (kein Globbing +und keine `$VARS`-Expansion) für nur-stdin-Segmente, sodass Muster wie `*` oder `$HOME/...` nicht +verwendet werden können, um Dateilesevorgänge einzuschmuggeln. +Sichere Binaries müssen außerdem aus vertrauenswürdigen Binary-Verzeichnissen aufgelöst werden (Systemstandardwerte plus optionale +`tools.exec.safeBinTrustedDirs`). `PATH`-Einträge werden niemals automatisch als vertrauenswürdig eingestuft. +Die standardmäßigen vertrauenswürdigen Verzeichnisse für sichere Binaries sind absichtlich minimal: `/bin`, `/usr/bin`. +Wenn sich Ihre ausführbare sichere Binary in Paketmanager-/Benutzerpfaden befindet (zum Beispiel `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), fügen Sie sie explizit zu `tools.exec.safeBinTrustedDirs` hinzu. -Shell-Verkettungen und Umleitungen werden im Modus `allowlist` nicht automatisch erlaubt. +Shell-Verkettung und Umleitungen werden im Allowlist-Modus nicht automatisch erlaubt. -Shell-Verkettung (`&&`, `||`, `;`) ist erlaubt, wenn jedes Segment der obersten Ebene die Zulassungsliste erfüllt -(einschließlich sicherer Binaries oder automatischer Zulassung von Skills). Umleitungen werden im Modus `allowlist` weiterhin nicht unterstützt. -Befehlssubstitution (`$()` / Backticks) wird beim Parsen der Zulassungsliste abgelehnt, auch innerhalb +Shell-Verkettung (`&&`, `||`, `;`) ist erlaubt, wenn jedes Top-Level-Segment die Allowlist erfüllt +(einschließlich sicherer Binaries oder automatischer Skill-Allowlist). Umleitungen bleiben im Allowlist-Modus nicht unterstützt. +Befehlssubstitution (`$()` / Backticks) wird beim Allowlist-Parsen abgelehnt, auch innerhalb doppelter Anführungszeichen; verwenden Sie einfache Anführungszeichen, wenn Sie wörtlichen `$()`-Text benötigen. -Bei Freigaben der macOS-Companion-App wird roher Shell-Text, der Shell-Steuer- oder Erweiterungssyntax enthält -(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), als Nichttreffer der Zulassungsliste behandelt, sofern -das Shell-Binary selbst nicht auf der Zulassungsliste steht. -Für Shell-Wrapper (`bash|sh|zsh ... -c/-lc`) werden anforderungsbezogene env-Overrides auf eine -kleine explizite Zulassungsliste reduziert (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -Bei Entscheidungen vom Typ „immer erlauben“ im Modus `allowlist` speichern bekannte -Dispatch-Wrapper (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) innere Executable-Pfade statt Wrapper-Pfaden. -Shell-Multiplexer (`busybox`, `toybox`) werden für Shell-Applets (`sh`, `ash`, -usw.) ebenfalls entpackt, sodass innere Executables statt Multiplexer-Binaries gespeichert werden. Wenn ein Wrapper oder -Multiplexer nicht sicher entpackt werden kann, wird kein Eintrag in der Zulassungsliste automatisch gespeichert. -Wenn Sie Interpreter wie `python3` oder `node` auf die Zulassungsliste setzen, sollten Sie `tools.exec.strictInlineEval=true` bevorzugen, damit Inline-Eval weiterhin eine explizite Freigabe erfordert. Im strikten Modus kann `allow-always` weiterhin harmlose Interpreter-/Skriptaufrufe speichern, aber Träger von Inline-Eval werden nicht automatisch gespeichert. +Bei Genehmigungen in der macOS-Companion-App wird roher Shell-Text, der Shell-Steuer- oder Expansionssyntax enthält +(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), als Allowlist-Fehlschlag behandelt, sofern +nicht die Shell-Binary selbst auf der Allowlist steht. +Für Shell-Wrapper (`bash|sh|zsh ... -c/-lc`) werden anfragebezogene env-Überschreibungen auf eine +kleine explizite Allowlist reduziert (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +Bei Entscheidungen `allow-always` im Allowlist-Modus persistieren bekannte Dispatch-Wrapper +(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) innere ausführbare Pfade statt Wrapper-Pfade. +Shell-Multiplexer (`busybox`, `toybox`) werden auch für Shell-Applets (`sh`, `ash`, +usw.) entpackt, sodass innere ausführbare Dateien statt Multiplexer-Binaries persistiert werden. Wenn ein Wrapper oder +Multiplexer nicht sicher entpackt werden kann, wird kein Allowlist-Eintrag automatisch persistiert. +Wenn Sie Interpreter wie `python3` oder `node` auf die Allowlist setzen, bevorzugen Sie `tools.exec.strictInlineEval=true`, damit Inline-Eval weiterhin eine explizite Genehmigung erfordert. Im strikten Modus kann `allow-always` weiterhin harmlose Interpreter-/Skriptaufrufe persistieren, aber Inline-Eval-Träger werden nicht automatisch persistiert. -Standardmäßig sichere Binaries: +Standardmäßige sichere Binaries: [//]: # "SAFE_BIN_DEFAULTS:START" @@ -337,214 +336,214 @@ Standardmäßig sichere Binaries: [//]: # "SAFE_BIN_DEFAULTS:END" -`grep` und `sort` sind nicht in der Standardliste enthalten. Wenn Sie sich bewusst dafür entscheiden, behalten Sie explizite Einträge in der Zulassungsliste für -deren Workflows, die nicht nur stdin verwenden. +`grep` und `sort` sind nicht in der Standardliste. Wenn Sie sie aktivieren, behalten Sie explizite Allowlist-Einträge für +ihre Nicht-stdin-Workflows bei. Für `grep` im Safe-Bin-Modus geben Sie das Muster mit `-e`/`--regexp` an; die -positionale Musterform wird abgelehnt, damit Dateiopeanden nicht als mehrdeutige positionale Argumente eingeschleust werden können. +positionale Musterform wird abgelehnt, damit Dateiopeanden nicht als mehrdeutige positionale Argumente eingeschmuggelt werden können. -### Sichere Binaries im Vergleich zur Zulassungsliste +### Sichere Binaries im Vergleich zur Allowlist -| Thema | `tools.exec.safeBins` | Zulassungsliste (`exec-approvals.json`) | +| Thema | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | -| Ziel | Schmale stdin-Filter automatisch erlauben | Bestimmten Executables explizit vertrauen | -| Abgleichstyp | Executable-Name + argv-Richtlinie für sichere Binaries | Glob-Muster des aufgelösten Executable-Pfads | -| Argumentbereich | Durch Safe-Bin-Profil und Literal-Token-Regeln eingeschränkt | Nur Pfadabgleich; Argumente liegen sonst in Ihrer Verantwortung | -| Typische Beispiele | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, benutzerdefinierte CLIs | +| Ziel | Enge stdin-Filter automatisch erlauben | Bestimmten ausführbaren Dateien explizit vertrauen | +| Übereinstimmungstyp | Name der ausführbaren Datei + Safe-Bin-argv-Richtlinie | Glob-Muster für aufgelösten Pfad der ausführbaren Datei | +| Argumentbereich | Durch Safe-Bin-Profil und Regeln für Literal-Tokens eingeschränkt | Nur Pfadabgleich; Argumente liegen ansonsten in Ihrer Verantwortung | +| Typische Beispiele | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, benutzerdefinierte CLIs | | Beste Verwendung | Texttransformationen mit geringem Risiko in Pipelines | Jedes Tool mit breiterem Verhalten oder Nebeneffekten | -Ort der Konfiguration: +Konfigurationsort: -- `safeBins` stammt aus der Konfiguration (`tools.exec.safeBins` oder pro Agent `agents.list[].tools.exec.safeBins`). -- `safeBinTrustedDirs` stammt aus der Konfiguration (`tools.exec.safeBinTrustedDirs` oder pro Agent `agents.list[].tools.exec.safeBinTrustedDirs`). -- `safeBinProfiles` stammt aus der Konfiguration (`tools.exec.safeBinProfiles` oder pro Agent `agents.list[].tools.exec.safeBinProfiles`). Profilschlüssel pro Agent überschreiben globale Schlüssel. -- Einträge in der Zulassungsliste liegen hostlokal in `~/.openclaw/exec-approvals.json` unter `agents..allowlist` (oder über die Control UI / `openclaw approvals allowlist ...`). +- `safeBins` kommt aus der Konfiguration (`tools.exec.safeBins` oder pro Agent `agents.list[].tools.exec.safeBins`). +- `safeBinTrustedDirs` kommt aus der Konfiguration (`tools.exec.safeBinTrustedDirs` oder pro Agent `agents.list[].tools.exec.safeBinTrustedDirs`). +- `safeBinProfiles` kommt aus der Konfiguration (`tools.exec.safeBinProfiles` oder pro Agent `agents.list[].tools.exec.safeBinProfiles`). Profilschlüssel pro Agent überschreiben globale Schlüssel. +- Allowlist-Einträge liegen in der hostlokalen `~/.openclaw/exec-approvals.json` unter `agents..allowlist` (oder über die Control UI / `openclaw approvals allowlist ...`). - `openclaw security audit` warnt mit `tools.exec.safe_bins_interpreter_unprofiled`, wenn Interpreter-/Runtime-Binaries in `safeBins` ohne explizite Profile erscheinen. -- `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles.`-Einträge als `{}` erzeugen (anschließend prüfen und verschärfen). Interpreter-/Runtime-Binaries werden nicht automatisch erzeugt. +- `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles.`-Einträge als `{}` vorbereiten (anschließend prüfen und verschärfen). Interpreter-/Runtime-Binaries werden nicht automatisch vorbereitet. Beispiel für ein benutzerdefiniertes Profil: __OC_I18N_900005__ Wenn Sie `jq` explizit in `safeBins` aufnehmen, lehnt OpenClaw das Built-in `env` im Safe-Bin- -Modus dennoch ab, sodass `jq -n env` die Host-Prozessumgebung nicht ohne einen expliziten Pfad in der Zulassungsliste -oder eine Freigabeaufforderung ausgeben kann. +Modus weiterhin ab, sodass `jq -n env` die Host-Prozessumgebung nicht ohne expliziten Allowlist-Pfad +oder Genehmigungsabfrage ausgeben kann. -## Bearbeitung in der Control UI +## Bearbeiten in der Control UI -Verwenden Sie **Control UI → Nodes → Exec approvals**, um Standardwerte, agentbezogene -Überschreibungen und Zulassungslisten zu bearbeiten. Wählen Sie einen Geltungsbereich (Standardwerte oder einen Agent), passen Sie die Richtlinie an, -fügen Sie Muster für die Zulassungsliste hinzu oder entfernen Sie sie und klicken Sie dann auf **Save**. Die UI zeigt Metadaten zu **last used** -pro Muster an, damit Sie die Liste übersichtlich halten können. +Verwenden Sie die Karte **Control UI → Nodes → Exec approvals**, um Standardwerte, agentbezogene +Überschreibungen und Allowlists zu bearbeiten. Wählen Sie einen Geltungsbereich (Standards oder einen Agenten), passen Sie die Richtlinie an, +fügen Sie Allowlist-Muster hinzu/entfernen Sie sie und klicken Sie dann auf **Save**. Die UI zeigt +pro Muster Metadaten zu **last used** an, damit Sie die Liste übersichtlich halten können. -Mit der Zielauswahl wählen Sie **Gateway** (lokale Freigaben) oder einen **Node**. Nodes -müssen `system.execApprovals.get/set` ankündigen (macOS-App oder kopfloser Node-Host). -Wenn ein Node noch keine Ausführungsfreigaben ankündigt, bearbeiten Sie seine lokale +Die Zielauswahl wählt **Gateway** (lokale Genehmigungen) oder einen **Node**. Nodes +müssen `system.execApprovals.get/set` ankündigen (macOS-App oder Headless-Node-Host). +Wenn ein Node noch keine Exec-Genehmigungen ankündigt, bearbeiten Sie seine lokale `~/.openclaw/exec-approvals.json` direkt. -CLI: `openclaw approvals` unterstützt die Bearbeitung für Gateway oder Node (siehe [Approvals CLI](/cli/approvals)). +CLI: `openclaw approvals` unterstützt das Bearbeiten von Gateway oder Node (siehe [Approvals CLI](/cli/approvals)). -## Freigabeablauf +## Genehmigungsablauf -Wenn eine Eingabeaufforderung erforderlich ist, sendet das Gateway `exec.approval.requested` an Operator-Clients. -Die Control UI und die macOS-App lösen dies über `exec.approval.resolve` auf, dann leitet das Gateway die -genehmigte Anforderung an den Node-Host weiter. +Wenn eine Rückfrage erforderlich ist, sendet das Gateway `exec.approval.requested` an Operator-Clients. +Die Control UI und die macOS-App lösen dies über `exec.approval.resolve` auf, danach leitet das Gateway die +genehmigte Anfrage an den Node-Host weiter. -Für `host=node` enthalten Freigabeanforderungen eine kanonische `systemRunPlan`-Payload. Das Gateway verwendet -diesen Plan als maßgeblichen Kontext für Befehl/cwd/Sitzung, wenn genehmigte `system.run`- -Anforderungen weitergeleitet werden. +Für `host=node` enthalten Genehmigungsanfragen eine kanonische Payload `systemRunPlan`. Das Gateway verwendet +diesen Plan als maßgeblichen Befehls-/cwd-/Sitzungskontext, wenn genehmigte `system.run`- +Anfragen weitergeleitet werden. -Das ist für asynchrone Latenz bei Freigaben wichtig: +Das ist wichtig für die Latenz asynchroner Genehmigungen: -- der Node-Exec-Pfad bereitet im Voraus einen kanonischen Plan vor -- der Freigabedatensatz speichert diesen Plan und seine Bindungsmetadaten -- nach der Genehmigung verwendet der endgültig weitergeleitete `system.run`-Aufruf den gespeicherten Plan wieder, - statt späteren Änderungen durch den Aufrufer zu vertrauen +- der Node-Exec-Pfad bereitet einen kanonischen Plan im Voraus vor +- der Genehmigungsdatensatz speichert diesen Plan und seine Bindungsmetadaten +- nach der Genehmigung verwendet der endgültig weitergeleitete `system.run`-Aufruf den gespeicherten Plan erneut, + statt späteren Änderungen des Aufrufers zu vertrauen - wenn der Aufrufer `command`, `rawCommand`, `cwd`, `agentId` oder - `sessionKey` ändert, nachdem die Freigabeanforderung erstellt wurde, lehnt das Gateway die - weitergeleitete Ausführung als Freigabe-Nichtübereinstimmung ab + `sessionKey` ändert, nachdem die Genehmigungsanfrage erstellt wurde, lehnt das Gateway die + weitergeleitete Ausführung als Genehmigungsabweichung ab ## Interpreter-/Runtime-Befehle -Durch Freigaben abgesicherte Interpreter-/Runtime-Ausführungen sind absichtlich konservativ: +Genehmigungsgestützte Interpreter-/Runtime-Ausführungen sind absichtlich konservativ: -- Exakter Kontext aus argv/cwd/env wird immer gebunden. -- Direkte Shell-Skript- und direkte Runtime-Dateiformen werden nach bestem Bemühen an einen konkreten lokalen +- Exakter argv-/cwd-/env-Kontext wird immer gebunden. +- Direkte Shell-Skript- und direkte Runtime-Dateiformen werden bestmöglich an genau einen konkreten lokalen Dateisnapshot gebunden. -- Häufige Paketmanager-Wrapper-Formen, die sich dennoch zu einer direkten lokalen Datei auflösen lassen (zum Beispiel +- Häufige Paketmanager-Wrapper-Formen, die sich trotzdem zu genau einer direkten lokalen Datei auflösen (zum Beispiel `pnpm exec`, `pnpm node`, `npm exec`, `npx`), werden vor der Bindung entpackt. - Wenn OpenClaw für einen Interpreter-/Runtime-Befehl nicht genau eine konkrete lokale Datei identifizieren kann - (zum Beispiel Paketskripte, Eval-Formen, runtime-spezifische Loader-Ketten oder mehrdeutige Formen mit mehreren Dateien), - wird die durch Freigaben abgesicherte Ausführung verweigert, statt semantische Abdeckung zu behaupten, die tatsächlich - nicht vorhanden ist. -- Für diese Workflows sollten Sie Sandboxing, eine separate Host-Grenze oder einen expliziten vertrauenswürdigen - Workflow mit Zulassungsliste/full bevorzugen, bei dem der Operator die breitere Runtime-Semantik akzeptiert. + (zum Beispiel Paketskripte, Eval-Formen, Runtime-spezifische Loader-Ketten oder mehrdeutige Mehrdatei- + Formen), wird die genehmigungsgestützte Ausführung abgelehnt, statt semantische Abdeckung zu behaupten, die sie nicht + hat. +- Für solche Workflows bevorzugen Sie Sandboxing, eine separate Host-Grenze oder einen explizit vertrauenswürdigen + Allowlist-/Full-Workflow, bei dem der Operator die weitergehende Runtime-Semantik akzeptiert. -Wenn Freigaben erforderlich sind, gibt das Exec-Tool sofort eine Freigabe-ID zurück. Verwenden Sie diese ID, um -spätere Systemereignisse zuzuordnen (`Exec finished` / `Exec denied`). Wenn vor dem -Timeout keine Entscheidung eintrifft, wird die Anforderung als Freigabe-Timeout behandelt und als Grund für die Verweigerung angezeigt. +Wenn Genehmigungen erforderlich sind, gibt das Exec-Tool sofort mit einer Genehmigungs-ID zurück. Verwenden Sie diese ID, um +spätere Systemereignisse (`Exec finished` / `Exec denied`) zuzuordnen. Wenn vor dem +Timeout keine Entscheidung eingeht, wird die Anfrage als Genehmigungs-Timeout behandelt und als Ablehnungsgrund ausgegeben. -### Verhalten bei der Zustellung von Folgeaktionen +### Verhalten bei Follow-up-Zustellung -Nachdem eine genehmigte asynchrone Ausführung abgeschlossen ist, sendet OpenClaw einen nachfolgenden `agent`-Turn an dieselbe Sitzung. +Nachdem ein genehmigter asynchroner Exec abgeschlossen ist, sendet OpenClaw einen Follow-up-Turn des Typs `agent` an dieselbe Sitzung. -- Wenn ein gültiges externes Zustellziel vorhanden ist (zustellbarer Kanal plus Ziel `to`), verwendet die Zustellung der Folgeaktion diesen Kanal. -- In reinem Webchat oder internen Sitzungsabläufen ohne externes Ziel bleibt die Zustellung der Folgeaktion nur sitzungsintern (`deliver: false`). -- Wenn ein Aufrufer explizit eine strikte externe Zustellung anfordert, aber kein externer Kanal aufgelöst werden kann, schlägt die Anforderung mit `INVALID_REQUEST` fehl. -- Wenn `bestEffortDeliver` aktiviert ist und kein externer Kanal aufgelöst werden kann, wird die Zustellung statt eines Fehlers auf nur sitzungsintern herabgestuft. +- Wenn ein gültiges externes Zustellungsziel existiert (zustellbarer Channel plus Ziel `to`), verwendet die Follow-up-Zustellung diesen Channel. +- In reinen Webchat- oder internen Sitzungsabläufen ohne externes Ziel bleibt die Follow-up-Zustellung sitzungsintern (`deliver: false`). +- Wenn ein Aufrufer explizit strikte externe Zustellung anfordert, aber kein externer Channel aufgelöst werden kann, schlägt die Anfrage mit `INVALID_REQUEST` fehl. +- Wenn `bestEffortDeliver` aktiviert ist und kein externer Channel aufgelöst werden kann, wird die Zustellung auf sitzungsintern herabgestuft, statt fehlzuschlagen. Der Bestätigungsdialog enthält: - Befehl + Argumente - cwd - Agent-ID -- aufgelöster Executable-Pfad -- Host- und Richtlinienmetadaten +- aufgelösten Pfad der ausführbaren Datei +- Host- + Richtlinienmetadaten Aktionen: - **Allow once** → jetzt ausführen -- **Always allow** → zur Zulassungsliste hinzufügen + ausführen +- **Always allow** → zur Allowlist hinzufügen + ausführen - **Deny** → blockieren -## Weiterleitung von Freigaben an Chat-Kanäle +## Genehmigungsweiterleitung an Chat-Channels -Sie können Aufforderungen für Exec-Freigaben an jeden Chat-Kanal weiterleiten (einschließlich Plugin-Kanälen) und sie -mit `/approve` genehmigen. Dies verwendet die normale Pipeline für ausgehende Zustellung. +Sie können Exec-Genehmigungsabfragen an jeden Chat-Channel (einschließlich Plugin-Channels) weiterleiten und +sie mit `/approve` genehmigen. Dies verwendet die normale Pipeline für ausgehende Zustellung. Konfiguration: __OC_I18N_900006__ Antwort im Chat: __OC_I18N_900007__ -Der Befehl `/approve` verarbeitet sowohl Exec-Freigaben als auch Plugin-Freigaben. Wenn die ID nicht zu einer ausstehenden Exec-Freigabe passt, wird automatisch stattdessen nach Plugin-Freigaben gesucht. +Der Befehl `/approve` verarbeitet sowohl Exec-Genehmigungen als auch Plugin-Genehmigungen. Wenn die ID nicht zu einer ausstehenden Exec-Genehmigung passt, prüft er automatisch stattdessen Plugin-Genehmigungen. -### Weiterleitung von Plugin-Freigaben +### Weiterleitung von Plugin-Genehmigungen -Die Weiterleitung von Plugin-Freigaben verwendet dieselbe Zustellungspipeline wie Exec-Freigaben, hat aber eine eigene -unabhängige Konfiguration unter `approvals.plugin`. Das Aktivieren oder Deaktivieren der einen hat keine Auswirkungen auf die andere. +Die Weiterleitung von Plugin-Genehmigungen verwendet dieselbe Zustellungspipeline wie Exec-Genehmigungen, hat aber eine eigene +unabhängige Konfiguration unter `approvals.plugin`. Das Aktivieren oder Deaktivieren der einen wirkt sich nicht auf die andere aus. __OC_I18N_900008__ -Die Konfigurationsstruktur ist identisch mit `approvals.exec`: `enabled`, `mode`, `agentFilter`, -`sessionFilter` und `targets` funktionieren gleich. +Die Form der Konfiguration ist identisch mit `approvals.exec`: `enabled`, `mode`, `agentFilter`, +`sessionFilter` und `targets` funktionieren auf dieselbe Weise. -Kanäle, die gemeinsame interaktive Antworten unterstützen, stellen für Exec- und -Plugin-Freigaben dieselben Freigabeschaltflächen dar. Kanäle ohne gemeinsame interaktive UI greifen auf Klartext mit -Anweisungen für `/approve` zurück. +Channels, die gemeinsame interaktive Antworten unterstützen, rendern dieselben Genehmigungsbuttons sowohl für Exec- als auch für +Plugin-Genehmigungen. Channels ohne gemeinsame interaktive UI fallen auf Klartext mit `/approve`- +Anweisungen zurück. -### Freigaben im selben Chat auf jedem Kanal +### Genehmigungen im selben Chat auf jedem Channel -Wenn eine Exec- oder Plugin-Freigabeanforderung von einer zustellbaren Chat-Oberfläche stammt, kann derselbe Chat sie -nun standardmäßig mit `/approve` genehmigen. Das gilt für Kanäle wie Slack, Matrix und -Microsoft Teams zusätzlich zu den bereits vorhandenen Abläufen in Web-UI und Terminal-UI. +Wenn eine Exec- oder Plugin-Genehmigungsanfrage von einer zustellbaren Chat-Oberfläche ausgeht, kann derselbe Chat +sie jetzt standardmäßig mit `/approve` genehmigen. Dies gilt für Channels wie Slack, Matrix und +Microsoft Teams zusätzlich zu den bestehenden Abläufen über Web-UI und Terminal-UI. -Dieser gemeinsame Pfad über Textbefehle verwendet das normale Kanal-Authentifizierungsmodell für diese Unterhaltung. Wenn der -ursprüngliche Chat bereits Befehle senden und Antworten empfangen kann, benötigen Freigabeanforderungen keinen -separaten nativen Zustelladapter mehr, nur damit sie ausstehend bleiben. +Dieser gemeinsame Textbefehlsweg verwendet das normale Channel-Auth-Modell für diese Konversation. Wenn der +ursprüngliche Chat bereits Befehle senden und Antworten empfangen kann, benötigen Genehmigungsanfragen nicht länger einen +separaten nativen Zustellungsadapter, nur um ausstehend zu bleiben. -Discord und Telegram unterstützen ebenfalls `/approve` im selben Chat, aber diese Kanäle verwenden weiterhin ihre -aufgelöste Liste zulässiger Genehmiger zur Autorisierung, auch wenn die native Freigabezustellung deaktiviert ist. +Discord und Telegram unterstützen ebenfalls `/approve` im selben Chat, aber diese Channels verwenden weiterhin ihre +aufgelöste Liste der Genehmigenden für die Autorisierung, selbst wenn native Genehmigungszustellung deaktiviert ist. -Für Telegram und andere native Freigabe-Clients, die das Gateway direkt aufrufen, -ist dieses Fallback absichtlich auf Fehler vom Typ „Freigabe nicht gefunden“ begrenzt. Eine echte -Exec-Freigabeverweigerung bzw. ein echter Fehler wird nicht stillschweigend als Plugin-Freigabe erneut versucht. +Für Telegram und andere native Genehmigungsclients, die das Gateway direkt aufrufen, +ist dieser Fallback absichtlich auf Fehler „Genehmigung nicht gefunden“ begrenzt. Ein echter +Exec-Genehmigungsfehler bzw. eine echte Ablehnung wird nicht stillschweigend erneut als Plugin-Genehmigung versucht. -### Native Freigabezustellung +### Native Genehmigungszustellung -Einige Kanäle können außerdem als native Freigabe-Clients fungieren. Native Clients ergänzen Genehmiger-DMs, Fanout an den Ursprungs-Chat -und kanalspezifische interaktive UX für Freigaben zusätzlich zum gemeinsamen `/approve`-Ablauf im selben Chat. +Einige Channels können auch als native Genehmigungsclients fungieren. Native Clients fügen DMs für Genehmigende, Fanout in den Ursprungs-Chat +und kanalspezifische interaktive Genehmigungs-UX zusätzlich zum gemeinsamen `/approve`-Ablauf im selben Chat hinzu. -Wenn native Freigabekarten/-schaltflächen verfügbar sind, ist diese native UI der primäre -agentseitige Pfad. Der Agent sollte dann nicht zusätzlich einen doppelten einfachen Chat- -Befehl `/approve` ausgeben, es sei denn, das Tool-Ergebnis sagt, dass Chat-Freigaben nicht verfügbar sind oder -eine manuelle Freigabe der einzige verbleibende Pfad ist. +Wenn native Genehmigungskarten/-Buttons verfügbar sind, ist diese native UI der primäre +agentenseitige Pfad. Der Agent sollte dann nicht zusätzlich einen doppelten Klartext- +Befehl `/approve` im Chat ausgeben, außer wenn das Tool-Ergebnis sagt, dass Chat-Genehmigungen nicht verfügbar sind oder +manuelle Genehmigung der einzig verbleibende Weg ist. Allgemeines Modell: -- die Host-Exec-Richtlinie entscheidet weiterhin, ob eine Exec-Freigabe erforderlich ist -- `approvals.exec` steuert die Weiterleitung von Freigabeaufforderungen an andere Chat-Ziele -- `channels..execApprovals` steuert, ob dieser Kanal als nativer Freigabe-Client fungiert +- die Host-Exec-Richtlinie entscheidet weiterhin, ob eine Exec-Genehmigung erforderlich ist +- `approvals.exec` steuert die Weiterleitung von Genehmigungsabfragen an andere Chat-Ziele +- `channels..execApprovals` steuert, ob dieser Channel als nativer Genehmigungsclient fungiert -Native Freigabe-Clients aktivieren automatisch DM-first-Zustellung, wenn alle folgenden Bedingungen erfüllt sind: +Native Genehmigungsclients aktivieren standardmäßig automatisch eine Zustellung mit DMs an Genehmigende zuerst, wenn all dies zutrifft: -- der Kanal unterstützt native Freigabezustellung -- Genehmiger können aus explizitem `execApprovals.approvers` oder den - dokumentierten Fallback-Quellen dieses Kanals aufgelöst werden +- der Channel unterstützt native Genehmigungszustellung +- Genehmigende können aus expliziten `execApprovals.approvers` oder den + dokumentierten Fallback-Quellen dieses Channels aufgelöst werden - `channels..execApprovals.enabled` ist nicht gesetzt oder `"auto"` -Setzen Sie `enabled: false`, um einen nativen Freigabe-Client explizit zu deaktivieren. Setzen Sie `enabled: true`, um ihn -zu erzwingen, wenn Genehmiger aufgelöst werden. Öffentliche Zustellung an den Ursprungs-Chat bleibt explizit über +Setzen Sie `enabled: false`, um einen nativen Genehmigungsclient explizit zu deaktivieren. Setzen Sie `enabled: true`, um +ihn zu erzwingen, wenn Genehmigende aufgelöst werden. Öffentliche Zustellung an den Ursprungs-Chat bleibt explizit über `channels..execApprovals.target`. -FAQ: [Warum gibt es zwei Konfigurationen für Exec-Freigaben bei Chat-Freigaben?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) +FAQ: [Warum gibt es zwei Exec-Genehmigungskonfigurationen für Chat-Genehmigungen?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) - Discord: `channels.discord.execApprovals.*` - Slack: `channels.slack.execApprovals.*` - Telegram: `channels.telegram.execApprovals.*` -Diese nativen Freigabe-Clients ergänzen DM-Routing und optionales Fanout an den Kanal zusätzlich zum gemeinsamen -`/approve`-Ablauf im selben Chat und den gemeinsamen Freigabeschaltflächen. +Diese nativen Genehmigungsclients fügen DM-Routing und optionales Channel-Fanout zusätzlich zum gemeinsamen +`/approve`-Ablauf im selben Chat und den gemeinsamen Genehmigungsbuttons hinzu. Gemeinsames Verhalten: -- Slack, Matrix, Microsoft Teams und ähnliche zustellbare Chats verwenden das normale Kanal-Authentifizierungsmodell +- Slack, Matrix, Microsoft Teams und ähnliche zustellbare Chats verwenden das normale Channel-Auth-Modell für `/approve` im selben Chat -- wenn ein nativer Freigabe-Client automatisch aktiviert wird, ist das Standardziel für die native Zustellung Genehmiger-DMs -- für Discord und Telegram können nur aufgelöste Genehmiger genehmigen oder verweigern -- Discord-Genehmiger können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden -- Telegram-Genehmiger können explizit sein (`execApprovals.approvers`) oder aus bestehender Eigentümerkonfiguration abgeleitet werden (`allowFrom`, plus `defaultTo` für Direktnachrichten, wo unterstützt) -- Slack-Genehmiger können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden -- native Slack-Schaltflächen behalten die Art der Freigabe-ID bei, sodass `plugin:`-IDs Plugin-Freigaben +- wenn ein nativer Genehmigungsclient automatisch aktiviert wird, ist das standardmäßige native Zustellungsziel DMs für Genehmigende +- bei Discord und Telegram können nur aufgelöste Genehmigende genehmigen oder ablehnen +- Discord-Genehmigende können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden +- Telegram-Genehmigende können explizit sein (`execApprovals.approvers`) oder aus vorhandener Owner-Konfiguration abgeleitet werden (`allowFrom`, plus `defaultTo` für Direktnachrichten, wo unterstützt) +- Slack-Genehmigende können explizit sein (`execApprovals.approvers`) oder aus `commands.ownerAllowFrom` abgeleitet werden +- native Slack-Buttons bewahren die Art der Genehmigungs-ID, sodass `plugin:`-IDs Plugin-Genehmigungen ohne eine zweite Slack-lokale Fallback-Ebene auflösen können -- natives Matrix-DM-/Kanal-Routing und Reaktionskürzel verarbeiten sowohl Exec- als auch Plugin-Freigaben; - die Plugin-Autorisierung kommt weiterhin von `channels.matrix.dm.allowFrom` -- der Anforderer muss kein Genehmiger sein +- natives Matrix-DM-/Channel-Routing und Reaktionskürzel verarbeiten sowohl Exec- als auch Plugin-Genehmigungen; + die Plugin-Autorisierung kommt weiterhin aus `channels.matrix.dm.allowFrom` +- der Anfragende muss kein Genehmigender sein - der Ursprungs-Chat kann direkt mit `/approve` genehmigen, wenn dieser Chat bereits Befehle und Antworten unterstützt -- native Discord-Freigabeschaltflächen routen nach Art der Freigabe-ID: `plugin:`-IDs gehen - direkt zu Plugin-Freigaben, alles andere zu Exec-Freigaben -- native Telegram-Freigabeschaltflächen folgen demselben begrenzten Exec-zu-Plugin-Fallback wie `/approve` -- wenn natives `target` die Zustellung an den Ursprungs-Chat aktiviert, enthalten Freigabeaufforderungen den Befehlstext -- ausstehende Exec-Freigaben laufen standardmäßig nach 30 Minuten ab -- wenn keine Operator-UI oder kein konfigurierter Freigabe-Client die Anforderung annehmen kann, fällt die Aufforderung auf `askFallback` zurück +- native Discord-Genehmigungsbuttons routen nach Art der Genehmigungs-ID: `plugin:`-IDs gehen + direkt zu Plugin-Genehmigungen, alles andere geht zu Exec-Genehmigungen +- native Telegram-Genehmigungsbuttons folgen demselben begrenzten Exec-zu-Plugin-Fallback wie `/approve` +- wenn natives `target` die Zustellung an den Ursprungs-Chat aktiviert, enthalten Genehmigungsabfragen den Befehlstext +- ausstehende Exec-Genehmigungen laufen standardmäßig nach 30 Minuten ab +- wenn keine Operator-UI oder kein konfigurierter Genehmigungsclient die Anfrage annehmen kann, fällt die Abfrage auf `askFallback` zurück -Telegram verwendet standardmäßig Genehmiger-DMs (`target: "dm"`). Sie können zu `channel` oder `both` wechseln, wenn Sie -möchten, dass Freigabeaufforderungen auch im ursprünglichen Telegram-Chat/-Thema erscheinen. Bei Telegram-Forenthemen -bewahrt OpenClaw das Thema für die Freigabeaufforderung und die Folgeaktion nach der Freigabe. +Telegram verwendet standardmäßig DMs an Genehmigende (`target: "dm"`). Sie können zu `channel` oder `both` wechseln, wenn Sie möchten, +dass Genehmigungsabfragen auch im ursprünglichen Telegram-Chat/Topic erscheinen. Bei Telegram-Forenthemen +bewahrt OpenClaw das Thema sowohl für die Genehmigungsabfrage als auch für das Follow-up nach der Genehmigung. Siehe: @@ -555,38 +554,38 @@ Siehe: __OC_I18N_900009__ Sicherheitshinweise: -- Unix-Socket-Modus `0600`, Token wird in `exec-approvals.json` gespeichert. +- Unix-Socket-Modus `0600`, Token gespeichert in `exec-approvals.json`. - Same-UID-Peer-Prüfung. - Challenge/Response (Nonce + HMAC-Token + Request-Hash) + kurze TTL. ## Systemereignisse -Der Lebenszyklus von Exec wird als Systemnachrichten angezeigt: +Der Exec-Lebenszyklus wird als Systemnachrichten angezeigt: - `Exec running` (nur wenn der Befehl den Schwellenwert für die Laufmeldung überschreitet) - `Exec finished` - `Exec denied` -Diese werden in die Sitzung des Agents gepostet, nachdem der Node das Ereignis gemeldet hat. -Exec-Freigaben auf dem Gateway-Host geben dieselben Lebenszyklusereignisse aus, wenn der Befehl abgeschlossen ist (und optional, wenn er länger als den Schwellenwert läuft). -Durch Freigaben geschützte Execs verwenden die Freigabe-ID in diesen Nachrichten erneut als `runId`, damit sie leicht zugeordnet werden können. +Diese werden an die Sitzung des Agenten gesendet, nachdem der Node das Ereignis gemeldet hat. +Genehmigungen für Gateway-Host-Exec erzeugen dieselben Lebenszyklusereignisse, wenn der Befehl abgeschlossen ist (und optional, wenn er länger als der Schwellenwert läuft). +Durch Genehmigungen abgesicherte Execs verwenden in diesen Nachrichten die Genehmigungs-ID erneut als `runId`, damit sie leicht zugeordnet werden können. -## Verhalten bei verweigerter Freigabe +## Verhalten bei abgelehnter Genehmigung -Wenn eine asynchrone Exec-Freigabe verweigert wird, verhindert OpenClaw, dass der Agent -Ausgabe aus einer früheren Ausführung desselben Befehls in der Sitzung wiederverwendet. Der Grund für die Verweigerung -wird mit einem expliziten Hinweis weitergegeben, dass keine Befehlsausgabe verfügbar ist; das verhindert, -dass der Agent behauptet, es gebe neue Ausgabe, oder den verweigerten Befehl mit -veralteten Ergebnissen aus einer früheren erfolgreichen Ausführung wiederholt. +Wenn eine asynchrone Exec-Genehmigung abgelehnt wird, verhindert OpenClaw, dass der Agent +Ausgaben eines früheren Laufs desselben Befehls in der Sitzung wiederverwendet. Der Ablehnungsgrund +wird zusammen mit einer expliziten Anweisung übergeben, dass keine Befehlsausgabe verfügbar ist, was +verhindert, dass der Agent behauptet, es gebe neue Ausgabe, oder den abgelehnten Befehl mit +veralteten Ergebnissen eines früheren erfolgreichen Laufs wiederholt. ## Auswirkungen -- **full** ist leistungsstark; bevorzugen Sie nach Möglichkeit Zulassungslisten. -- **ask** bindet Sie ein, ermöglicht aber weiterhin schnelle Freigaben. -- Zulassungslisten pro Agent verhindern, dass Freigaben eines Agents in andere übergreifen. -- Freigaben gelten nur für Host-Exec-Anforderungen von **autorisierten Absendern**. Nicht autorisierte Absender können kein `/exec` ausführen. -- `/exec security=full` ist eine sitzungsbezogene Komfortfunktion für autorisierte Operatoren und überspringt Freigaben absichtlich. - Um Host-Exec hart zu blockieren, setzen Sie die Freigabesicherheit auf `deny` oder verweigern Sie das Tool `exec` über die Tool-Richtlinie. +- **full** ist mächtig; bevorzugen Sie wenn möglich Allowlists. +- **ask** hält Sie im Ablauf, ermöglicht aber weiterhin schnelle Genehmigungen. +- Allowlists pro Agent verhindern, dass die Genehmigungen eines Agenten in andere übergreifen. +- Genehmigungen gelten nur für Host-Exec-Anfragen von **autorisierten Sendern**. Nicht autorisierte Sender können `/exec` nicht ausführen. +- `/exec security=full` ist eine Sitzungs-Kurzform für autorisierte Operatoren und überspringt Genehmigungen absichtlich. + Um Host-Exec vollständig zu blockieren, setzen Sie die Genehmigungssicherheit auf `deny` oder verweigern Sie das Tool `exec` über die Tool-Richtlinie. Verwandt: @@ -598,5 +597,5 @@ Verwandt: - [Exec](/de/tools/exec) — Tool zur Ausführung von Shell-Befehlen - [Sandboxing](/de/gateway/sandboxing) — Sandbox-Modi und Workspace-Zugriff -- [Security](/de/gateway/security) — Sicherheitsmodell und Härtung -- [Sandbox vs Tool Policy vs Elevated](/de/gateway/sandbox-vs-tool-policy-vs-elevated) — wann welches verwendet werden sollte +- [Sicherheit](/de/gateway/security) — Sicherheitsmodell und Härtung +- [Sandbox vs Tool-Richtlinie vs Elevated](/de/gateway/sandbox-vs-tool-policy-vs-elevated) — wann was verwendet werden sollte diff --git a/docs/de/tools/exec.md b/docs/de/tools/exec.md index 6f2182cc4..df5d2ddbd 100644 --- a/docs/de/tools/exec.md +++ b/docs/de/tools/exec.md @@ -1,85 +1,85 @@ --- read_when: - Verwenden oder Ändern des Exec-Tools - - Debuggen des stdin- oder TTY-Verhaltens + - Fehlerbehebung beim stdin- oder TTY-Verhalten summary: Verwendung des Exec-Tools, stdin-Modi und TTY-Unterstützung title: Exec-Tool x-i18n: - generated_at: "2026-04-06T03:13:03Z" + generated_at: "2026-04-21T13:37:32Z" model: gpt-5.4 provider: openai - source_hash: 28388971c627292dba9bf65ae38d7af8cde49a33bb3b5fc8b20da4f0e350bedd + source_hash: 5018468f31bb76fc142ddef7002c7bbc617406de7ce912670d1b9edef6a9a042 source_path: tools/exec.md workflow: 15 --- # Exec-Tool -Führt Shell-Befehle im Workspace aus. Unterstützt Ausführung im Vordergrund und Hintergrund über `process`. -Wenn `process` nicht erlaubt ist, läuft `exec` synchron und ignoriert `yieldMs`/`background`. -Hintergrundsitzungen sind pro Agent begrenzt; `process` sieht nur Sitzungen desselben Agents. +Führen Sie Shell-Befehle im Workspace aus. Unterstützt Vordergrund- und Hintergrundausführung über `process`. +Wenn `process` nicht erlaubt ist, wird `exec` synchron ausgeführt und ignoriert `yieldMs`/`background`. +Hintergrundsitzungen sind pro Agent begrenzt; `process` sieht nur Sitzungen desselben Agenten. ## Parameter - `command` (erforderlich) -- `workdir` (Standard: cwd) -- `env` (Überschreibungen für Schlüssel/Wert) -- `yieldMs` (Standard 10000): automatischer Hintergrundmodus nach Verzögerung +- `workdir` (Standard ist cwd) +- `env` (Schlüssel-/Wert-Überschreibungen) +- `yieldMs` (Standard 10000): nach Verzögerung automatisch in den Hintergrund - `background` (bool): sofort im Hintergrund ausführen - `timeout` (Sekunden, Standard 1800): bei Ablauf beenden -- `pty` (bool): in einem Pseudo-Terminal ausführen, wenn verfügbar (TTY-only-CLIs, Coding-Agents, Terminal-UIs) +- `pty` (bool): in einem Pseudo-Terminal ausführen, wenn verfügbar (nur-TTY-CLIs, Coding-Agents, Terminal-UIs) - `host` (`auto | sandbox | gateway | node`): wo ausgeführt werden soll -- `security` (`deny | allowlist | full`): Durchsetzungsmodus für `gateway`/`node` -- `ask` (`off | on-miss | always`): Genehmigungsaufforderungen für `gateway`/`node` +- `security` (`deny | allowlist | full`): Erzwingungsmodus für `gateway`/`node` +- `ask` (`off | on-miss | always`): Freigabeaufforderungen für `gateway`/`node` - `node` (string): Node-ID/-Name für `host=node` -- `elevated` (bool): erhöhten Modus anfordern (aus der Sandbox auf den konfigurierten Host-Pfad ausbrechen); `security=full` wird nur erzwungen, wenn `elevated` zu `full` aufgelöst wird +- `elevated` (bool): erhöhten Modus anfordern (die Sandbox verlassen und auf dem konfigurierten Host-Pfad ausführen); `security=full` wird nur erzwungen, wenn `elevated` zu `full` aufgelöst wird Hinweise: -- `host` verwendet standardmäßig `auto`: Sandbox, wenn die Sandbox-Laufzeit für die Sitzung aktiv ist, sonst Gateway. -- `auto` ist die Standard-Routing-Strategie, kein Wildcard. `host=node` pro Aufruf ist aus `auto` heraus erlaubt; `host=gateway` pro Aufruf ist nur erlaubt, wenn keine Sandbox-Laufzeit aktiv ist. -- Ohne zusätzliche Konfiguration funktioniert `host=auto` weiterhin einfach: keine Sandbox bedeutet Auflösung zu `gateway`; eine aktive Sandbox bedeutet, dass in der Sandbox geblieben wird. -- `elevated` verlässt die Sandbox auf den konfigurierten Host-Pfad: standardmäßig `gateway` oder `node`, wenn `tools.exec.host=node` gesetzt ist (oder die Sitzungsstandardeinstellung `host=node` ist). Es ist nur verfügbar, wenn erhöhter Zugriff für die aktuelle Sitzung bzw. den aktuellen Provider aktiviert ist. -- Genehmigungen für `gateway`/`node` werden über `~/.openclaw/exec-approvals.json` gesteuert. -- `node` erfordert einen gekoppelten Node (Begleit-App oder headless Node-Host). +- `host` hat standardmäßig `auto`: `sandbox`, wenn die Sandbox-Runtime für die Sitzung aktiv ist, andernfalls `gateway`. +- `auto` ist die Standard-Routing-Strategie, kein Platzhalter. Pro Aufruf ist `host=node` von `auto` aus erlaubt; pro Aufruf ist `host=gateway` nur erlaubt, wenn keine Sandbox-Runtime aktiv ist. +- Ohne zusätzliche Konfiguration funktioniert `host=auto` weiterhin „einfach so“: ohne Sandbox wird es zu `gateway`; mit aktiver Sandbox bleibt es in der Sandbox. +- `elevated` verlässt die Sandbox auf den konfigurierten Host-Pfad: standardmäßig `gateway` oder `node`, wenn `tools.exec.host=node` gesetzt ist (oder der Sitzungsstandard `host=node` ist). Es ist nur verfügbar, wenn erhöhter Zugriff für die aktuelle Sitzung/den aktuellen Provider aktiviert ist. +- `gateway`-/`node`-Freigaben werden über `~/.openclaw/exec-approvals.json` gesteuert. +- `node` erfordert einen gepairten Node (Companion-App oder Headless-Node-Host). - Wenn mehrere Nodes verfügbar sind, setzen Sie `exec.node` oder `tools.exec.node`, um einen auszuwählen. - `exec host=node` ist der einzige Shell-Ausführungspfad für Nodes; der Legacy-Wrapper `nodes.run` wurde entfernt. -- Auf Nicht-Windows-Hosts verwendet exec `SHELL`, wenn gesetzt; wenn `SHELL` auf `fish` gesetzt ist, wird `bash` (oder `sh`) - aus `PATH` bevorzugt, um mit fish inkompatible Skripte zu vermeiden, und erst dann auf `SHELL` zurückgegriffen, wenn keines von beiden existiert. -- Auf Windows-Hosts bevorzugt exec die Erkennung von PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, dann PATH), - und fällt dann auf Windows PowerShell 5.1 zurück. +- Auf Nicht-Windows-Hosts verwendet `exec` `SHELL`, wenn gesetzt; wenn `SHELL` `fish` ist, bevorzugt es `bash` (oder `sh`) + aus `PATH`, um mit `fish` inkompatible Skripte zu vermeiden, und fällt dann auf `SHELL` zurück, wenn keines von beiden existiert. +- Auf Windows-Hosts bevorzugt `exec` die Erkennung von PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, dann PATH) + und fällt danach auf Windows PowerShell 5.1 zurück. - Host-Ausführung (`gateway`/`node`) lehnt `env.PATH` und Loader-Überschreibungen (`LD_*`/`DYLD_*`) ab, um - Binary-Hijacking oder eingeschleusten Code zu verhindern. -- OpenClaw setzt `OPENCLAW_SHELL=exec` in der Umgebungsvariablen des gestarteten Befehls (einschließlich PTY- und Sandbox-Ausführung), damit Shell-/Profilregeln den Kontext des Exec-Tools erkennen können. + Binary-Hijacking oder injizierten Code zu verhindern. +- OpenClaw setzt `OPENCLAW_SHELL=exec` in der Umgebung des gestarteten Befehls (einschließlich PTY- und Sandbox-Ausführung), damit Shell-/Profilregeln den Kontext des Exec-Tools erkennen können. - Wichtig: Sandboxing ist standardmäßig **deaktiviert**. Wenn Sandboxing deaktiviert ist, wird implizites `host=auto` zu `gateway` aufgelöst. Explizites `host=sandbox` schlägt weiterhin geschlossen fehl, statt stillschweigend - auf dem Gateway-Host zu laufen. Aktivieren Sie Sandboxing oder verwenden Sie `host=gateway` mit Genehmigungen. -- Script-Preflight-Prüfungen (für häufige Python-/Node-Shell-Syntaxfehler) untersuchen nur Dateien innerhalb der - effektiven `workdir`-Grenze. Wenn ein Skriptpfad außerhalb von `workdir` aufgelöst wird, wird der Preflight für - diese Datei übersprungen. -- Für lang laufende Arbeiten, die jetzt starten, starten Sie sie einmal und verlassen Sie sich auf das automatische - Completion-Wake, wenn es aktiviert ist und der Befehl Ausgabe erzeugt oder fehlschlägt. - Verwenden Sie `process` für Logs, Status, Eingaben oder Eingriffe; emulieren Sie kein - Scheduling mit Sleep-Schleifen, Timeout-Schleifen oder wiederholtem Polling. -- Für Arbeiten, die später oder nach Zeitplan stattfinden sollen, verwenden Sie cron statt + auf dem Gateway-Host auszuführen. Aktivieren Sie Sandboxing oder verwenden Sie `host=gateway` mit Freigaben. +- Skript-Preflight-Prüfungen (für häufige Python-/Node-Shell-Syntaxfehler) prüfen nur Dateien innerhalb der + wirksamen `workdir`-Grenze. Wenn ein Skriptpfad außerhalb von `workdir` aufgelöst wird, wird die Preflight-Prüfung + für diese Datei übersprungen. +- Für lang laufende Arbeit, die jetzt startet, starten Sie sie einmal und verlassen Sie sich auf das automatische + Abschluss-Wake-up, wenn es aktiviert ist und der Befehl Ausgabe erzeugt oder fehlschlägt. + Verwenden Sie `process` für Logs, Status, Eingaben oder Eingriffe; emulieren Sie keine + Planung mit Sleep-Schleifen, Timeout-Schleifen oder wiederholtem Polling. +- Für Arbeit, die später oder nach Zeitplan erfolgen soll, verwenden Sie Cron statt `exec`-Sleep-/Delay-Mustern. ## Konfiguration -- `tools.exec.notifyOnExit` (Standard: true): Wenn true, stellen im Hintergrund ausgeführte Exec-Sitzungen beim Beenden ein Systemereignis in die Queue und fordern einen Heartbeat an. -- `tools.exec.approvalRunningNoticeMs` (Standard: 10000): sendet einen einzelnen Hinweis „läuft“, wenn ein genehmigungspflichtiger Exec länger als diesen Wert läuft (0 deaktiviert). -- `tools.exec.host` (Standard: `auto`; wird zu `sandbox` aufgelöst, wenn die Sandbox-Laufzeit aktiv ist, sonst zu `gateway`) +- `tools.exec.notifyOnExit` (Standard: true): wenn true, stellen in den Hintergrund verschobene Exec-Sitzungen beim Beenden ein Systemereignis in die Warteschlange und fordern einen Heartbeat an. +- `tools.exec.approvalRunningNoticeMs` (Standard: 10000): gibt genau einen Hinweis „running“ aus, wenn ein freigabegesteuerter Exec länger als dies läuft (0 deaktiviert). +- `tools.exec.host` (Standard: `auto`; wird zu `sandbox` aufgelöst, wenn die Sandbox-Runtime aktiv ist, sonst zu `gateway`) - `tools.exec.security` (Standard: `deny` für Sandbox, `full` für Gateway + Node, wenn nicht gesetzt) - `tools.exec.ask` (Standard: `off`) -- Host-Exec ohne Genehmigung ist der Standard für Gateway + Node. Wenn Sie Genehmigungen/Allowlist-Verhalten möchten, verschärfen Sie sowohl `tools.exec.*` als auch die Host-`~/.openclaw/exec-approvals.json`; siehe [Exec approvals](/de/tools/exec-approvals#no-approval-yolo-mode). -- YOLO kommt von den Standardwerten der Host-Richtlinie (`security=full`, `ask=off`), nicht von `host=auto`. Wenn Sie Gateway- oder Node-Routing erzwingen möchten, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...`. -- Im Modus `security=full` plus `ask=off` folgt Host-Exec direkt der konfigurierten Richtlinie; es gibt keinen zusätzlichen heuristischen Vorfilter für Befehlsverschleierung. +- Host-Exec ohne Freigabe ist der Standard für Gateway + Node. Wenn Sie Freigaben/Allowlist-Verhalten möchten, verschärfen Sie sowohl `tools.exec.*` als auch die Host-`~/.openclaw/exec-approvals.json`; siehe [Exec approvals](/de/tools/exec-approvals#no-approval-yolo-mode). +- YOLO kommt von den Host-Richtlinienstandards (`security=full`, `ask=off`), nicht von `host=auto`. Wenn Sie Gateway- oder Node-Routing erzwingen möchten, setzen Sie `tools.exec.host` oder verwenden Sie `/exec host=...`. +- Im Modus `security=full` plus `ask=off` folgt Host-Exec direkt der konfigurierten Richtlinie; es gibt keine zusätzliche heuristische Vorfilterung zur Befehlsverschleierung oder zusätzliche Ablehnungsschicht für Skript-Preflight. - `tools.exec.node` (Standard: nicht gesetzt) -- `tools.exec.strictInlineEval` (Standard: false): Wenn true, erfordern Inline-Interpreter-Eval-Formen wie `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` und `osascript -e` immer eine explizite Genehmigung. `allow-always` kann weiterhin harmlose Interpreter-/Skriptaufrufe dauerhaft speichern, aber Inline-Eval-Formen fragen trotzdem jedes Mal nach. -- `tools.exec.pathPrepend`: Liste von Verzeichnissen, die für Exec-Läufe an `PATH` vorangestellt werden (nur Gateway + Sandbox). -- `tools.exec.safeBins`: stdin-only sichere Binaries, die ohne explizite Allowlist-Einträge ausgeführt werden können. Details zum Verhalten finden Sie unter [Safe bins](/de/tools/exec-approvals#safe-bins-stdin-only). -- `tools.exec.safeBinTrustedDirs`: zusätzliche explizite Verzeichnisse, denen bei Pfadprüfungen für `safeBins` vertraut wird. `PATH`-Einträge werden niemals automatisch als vertrauenswürdig behandelt. Eingebaute Standardwerte sind `/bin` und `/usr/bin`. -- `tools.exec.safeBinProfiles`: optionale benutzerdefinierte argv-Richtlinie pro Safe Bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`). +- `tools.exec.strictInlineEval` (Standard: false): wenn true, erfordern Inline-Interpreter-Eval-Formen wie `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` und `osascript -e` immer eine explizite Freigabe. `allow-always` kann weiterhin harmlose Interpreter-/Skriptaufrufe dauerhaft speichern, aber Inline-Eval-Formen fordern trotzdem jedes Mal erneut eine Freigabe an. +- `tools.exec.pathPrepend`: Liste von Verzeichnissen, die für Exec-Ausführungen an `PATH` vorangestellt werden sollen (nur Gateway + Sandbox). +- `tools.exec.safeBins`: nur-stdin-sichere Binaries, die ohne explizite Allowlist-Einträge ausgeführt werden können. Verhaltensdetails finden Sie unter [Safe bins](/de/tools/exec-approvals#safe-bins-stdin-only). +- `tools.exec.safeBinTrustedDirs`: zusätzliche explizite Verzeichnisse, denen bei Pfadprüfungen für `safeBins` vertraut wird. `PATH`-Einträge sind nie automatisch vertrauenswürdig. Eingebaute Standards sind `/bin` und `/usr/bin`. +- `tools.exec.safeBinProfiles`: optionale benutzerdefinierte argv-Richtlinie pro safe bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`). Beispiel: @@ -95,29 +95,29 @@ Beispiel: ### PATH-Behandlung -- `host=gateway`: führt Ihren `PATH` aus der Login-Shell mit der Exec-Umgebung zusammen. Überschreibungen von `env.PATH` werden - für Host-Ausführung abgelehnt. Der Daemon selbst läuft weiterhin mit minimalem `PATH`: +- `host=gateway`: führt Ihr Login-Shell-`PATH` mit der Exec-Umgebung zusammen. `env.PATH`-Überschreibungen werden + für die Host-Ausführung abgelehnt. Der Daemon selbst läuft weiterhin mit einem minimalen `PATH`: - macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin` - Linux: `/usr/local/bin`, `/usr/bin`, `/bin` - `host=sandbox`: führt `sh -lc` (Login-Shell) im Container aus, sodass `/etc/profile` `PATH` zurücksetzen kann. OpenClaw stellt `env.PATH` nach dem Laden des Profils über eine interne Umgebungsvariable voran (ohne Shell-Interpolation); `tools.exec.pathPrepend` gilt auch hier. -- `host=node`: Nur nicht blockierte env-Überschreibungen, die Sie übergeben, werden an den Node gesendet. Überschreibungen von `env.PATH` werden - für Host-Ausführung abgelehnt und von Node-Hosts ignoriert. Wenn Sie zusätzliche PATH-Einträge auf einem Node benötigen, - konfigurieren Sie die Service-Umgebung des Node-Hosts (systemd/launchd) oder installieren Sie Tools an Standardorten. +- `host=node`: nur nicht blockierte `env`-Überschreibungen, die Sie übergeben, werden an den Node gesendet. `env.PATH`-Überschreibungen werden + für die Host-Ausführung abgelehnt und von Node-Hosts ignoriert. Wenn Sie zusätzliche PATH-Einträge auf einem Node benötigen, + konfigurieren Sie die Dienstumgebung des Node-Hosts (systemd/launchd) oder installieren Sie Tools an Standardorten. -Node-Binding pro Agent (verwenden Sie den Index der Agent-Liste in der Konfiguration): +Node-Bindung pro Agent (verwenden Sie den Agent-Listenindex in der Konfiguration): ```bash openclaw config get agents.list openclaw config set agents.list[0].tools.exec.node "node-id-or-name" ``` -Control UI: Die Registerkarte Nodes enthält ein kleines Panel „Exec node binding“ für dieselben Einstellungen. +Control UI: Die Registerkarte „Nodes“ enthält ein kleines Panel „Exec node binding“ für dieselben Einstellungen. ## Sitzungsüberschreibungen (`/exec`) -Verwenden Sie `/exec`, um **pro Sitzung** Standardwerte für `host`, `security`, `ask` und `node` festzulegen. +Verwenden Sie `/exec`, um **pro Sitzung** Standards für `host`, `security`, `ask` und `node` festzulegen. Senden Sie `/exec` ohne Argumente, um die aktuellen Werte anzuzeigen. Beispiel: @@ -128,49 +128,49 @@ Beispiel: ## Autorisierungsmodell -`/exec` wird nur für **autorisierte Sender** berücksichtigt (Kanal-Allowlists/Pairing plus `commands.useAccessGroups`). -Es aktualisiert **nur den Sitzungsstatus** und schreibt keine Konfiguration. Um exec vollständig zu deaktivieren, sperren Sie es per Tool- -Richtlinie (`tools.deny: ["exec"]` oder pro Agent). Host-Genehmigungen gelten weiterhin, es sei denn, Sie setzen explizit +`/exec` wird nur für **autorisierte Absender** berücksichtigt (Channel-Allowlists/Pairing plus `commands.useAccessGroups`). +Es aktualisiert **nur den Sitzungsstatus** und schreibt keine Konfiguration. Um Exec hart zu deaktivieren, verweigern Sie es über die Tool- +Richtlinie (`tools.deny: ["exec"]` oder pro Agent). Host-Freigaben gelten weiterhin, es sei denn, Sie setzen explizit `security=full` und `ask=off`. -## Exec-Genehmigungen (Begleit-App / Node-Host) +## Exec approvals (Companion-App / Node-Host) -Sandboxed Agents können pro Anfrage eine Genehmigung verlangen, bevor `exec` auf dem Gateway- oder Node-Host ausgeführt wird. +Sandboxed Agents können pro Anfrage eine Freigabe verlangen, bevor `exec` auf dem Gateway- oder Node-Host ausgeführt wird. Siehe [Exec approvals](/de/tools/exec-approvals) für Richtlinie, Allowlist und UI-Ablauf. -Wenn Genehmigungen erforderlich sind, gibt das Exec-Tool sofort mit -`status: "approval-pending"` und einer Genehmigungs-ID zurück. Sobald genehmigt (oder abgelehnt / mit Timeout beendet), -sendet das Gateway Systemereignisse (`Exec finished` / `Exec denied`). Wenn der Befehl nach `tools.exec.approvalRunningNoticeMs` -noch läuft, wird ein einzelner Hinweis `Exec running` ausgegeben. -Auf Kanälen mit nativen Genehmigungskarten/-Buttons sollte sich der Agent zuerst auf diese -native UI verlassen und einen manuellen `/approve`-Befehl nur dann einfügen, wenn das Tool- -Ergebnis ausdrücklich sagt, dass Chat-Genehmigungen nicht verfügbar sind oder manuelle Genehmigung der -einzige Weg ist. +Wenn Freigaben erforderlich sind, gibt das Exec-Tool sofort mit +`status: "approval-pending"` und einer Freigabe-ID zurück. Sobald freigegeben (oder abgelehnt / Timeout), +gibt das Gateway Systemereignisse aus (`Exec finished` / `Exec denied`). Wenn der Befehl nach +`tools.exec.approvalRunningNoticeMs` noch läuft, wird genau ein Hinweis `Exec running` ausgegeben. +Auf Channels mit nativen Freigabekarten/-buttons sollte sich der Agent zuerst auf diese +native UI verlassen und nur dann einen manuellen `/approve`-Befehl einfügen, wenn das Tool- +Ergebnis ausdrücklich sagt, dass Chat-Freigaben nicht verfügbar sind oder eine manuelle Freigabe +der einzige Weg ist. -## Allowlist + Safe Bins +## Allowlist + safe bins -Die manuelle Durchsetzung der Allowlist gleicht nur **aufgelöste Binary-Pfade** ab (keine Basename-Treffer). Wenn -`security=allowlist`, werden Shell-Befehle nur dann automatisch erlaubt, wenn jedes Pipeline-Segment -allowgelistet oder ein Safe Bin ist. Verkettungen (`;`, `&&`, `||`) und Umleitungen werden im -Allowlist-Modus abgelehnt, es sei denn, jedes Top-Level-Segment erfüllt die Allowlist (einschließlich Safe Bins). +Die manuelle Allowlist-Erzwingung gleicht nur **aufgelöste Binärpfade** ab (keine Basename-Abgleiche). Wenn +`security=allowlist` gesetzt ist, werden Shell-Befehle nur dann automatisch erlaubt, wenn jedes Pipeline-Segment +auf der Allowlist steht oder ein safe bin ist. Verkettung (`;`, `&&`, `||`) und Umleitungen werden im +Allowlist-Modus abgelehnt, es sei denn, jedes Top-Level-Segment erfüllt die Allowlist (einschließlich safe bins). Umleitungen bleiben nicht unterstützt. -Dauerhaftes Vertrauen per `allow-always` umgeht diese Regel nicht: Ein verketteter Befehl erfordert weiterhin, dass jedes +Dauerhaftes `allow-always`-Vertrauen umgeht diese Regel nicht: Ein verketteter Befehl erfordert weiterhin, dass jedes Top-Level-Segment übereinstimmt. -`autoAllowSkills` ist ein separater Komfortpfad in den Exec-Genehmigungen. Er ist nicht dasselbe wie -manuelle Pfad-Allowlist-Einträge. Für strikt explizites Vertrauen lassen Sie `autoAllowSkills` deaktiviert. +`autoAllowSkills` ist ein separater Komfortpfad in Exec-Freigaben. Es ist nicht dasselbe wie +manuelle Pfad-Allowlist-Einträge. Für striktes explizites Vertrauen lassen Sie `autoAllowSkills` deaktiviert. Verwenden Sie die beiden Steuerelemente für unterschiedliche Aufgaben: -- `tools.exec.safeBins`: kleine, stdin-only Stream-Filter. -- `tools.exec.safeBinTrustedDirs`: explizite zusätzliche vertrauenswürdige Verzeichnisse für ausführbare Safe-Bin-Pfade. -- `tools.exec.safeBinProfiles`: explizite argv-Richtlinie für benutzerdefinierte Safe Bins. +- `tools.exec.safeBins`: kleine, nur-stdin-Stream-Filter. +- `tools.exec.safeBinTrustedDirs`: explizite zusätzliche vertrauenswürdige Verzeichnisse für Pfade ausführbarer safe bins. +- `tools.exec.safeBinProfiles`: explizite argv-Richtlinie für benutzerdefinierte safe bins. - Allowlist: explizites Vertrauen für Pfade zu ausführbaren Dateien. -Behandeln Sie `safeBins` nicht als generische Allowlist, und fügen Sie keine Interpreter-/Laufzeit-Binaries hinzu (zum Beispiel `python3`, `node`, `ruby`, `bash`). Wenn Sie diese benötigen, verwenden Sie explizite Allowlist-Einträge und lassen Sie Genehmigungsaufforderungen aktiviert. -`openclaw security audit` warnt, wenn bei Einträgen für Interpreter-/Laufzeit-`safeBins` explizite Profile fehlen, und `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles`-Einträge erzeugen. +Behandeln Sie `safeBins` nicht als generische Allowlist und fügen Sie keine Interpreter-/Runtime-Binaries hinzu (zum Beispiel `python3`, `node`, `ruby`, `bash`). Wenn Sie diese benötigen, verwenden Sie explizite Allowlist-Einträge und lassen Sie Freigabeaufforderungen aktiviert. +`openclaw security audit` warnt, wenn bei Interpreter-/Runtime-`safeBins`-Einträgen explizite Profile fehlen, und `openclaw doctor --fix` kann fehlende benutzerdefinierte `safeBinProfiles`-Einträge erzeugen. `openclaw security audit` und `openclaw doctor` warnen auch, wenn Sie explizit Binaries mit breitem Verhalten wie `jq` wieder zu `safeBins` hinzufügen. -Wenn Sie Interpreter explizit allowlisten, aktivieren Sie `tools.exec.strictInlineEval`, damit Inline-Code-Eval-Formen weiterhin eine neue Genehmigung erfordern. +Wenn Sie Interpreter explizit auf die Allowlist setzen, aktivieren Sie `tools.exec.strictInlineEval`, damit Inline-Code-Eval-Formen weiterhin eine neue Freigabe erfordern. Vollständige Richtliniendetails und Beispiele finden Sie unter [Exec approvals](/de/tools/exec-approvals#safe-bins-stdin-only) und [Safe bins versus allowlist](/de/tools/exec-approvals#safe-bins-versus-allowlist). @@ -189,7 +189,7 @@ Hintergrund + Poll: {"tool":"process","action":"poll","sessionId":""} ``` -Polling dient zur bedarfsgesteuerten Statusabfrage, nicht für Warteschleifen. Wenn automatisches Completion-Wake +Polling ist für Status auf Abruf gedacht, nicht für Warteschleifen. Wenn das automatische Abschluss-Wake-up aktiviert ist, kann der Befehl die Sitzung wecken, wenn er Ausgabe erzeugt oder fehlschlägt. Tasten senden (tmux-Stil): @@ -200,13 +200,13 @@ Tasten senden (tmux-Stil): {"tool":"process","action":"send-keys","sessionId":"","keys":["Up","Up","Enter"]} ``` -Submit (nur CR senden): +Absenden (nur CR senden): ```json { "tool": "process", "action": "submit", "sessionId": "" } ``` -Paste (standardmäßig mit Klammerung): +Einfügen (standardmäßig in Klammern gesetzt): ```json { "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" } @@ -214,8 +214,8 @@ Paste (standardmäßig mit Klammerung): ## apply_patch -`apply_patch` ist ein Untertool von `exec` für strukturierte Bearbeitungen über mehrere Dateien hinweg. -Es ist standardmäßig für OpenAI- und OpenAI-Codex-Modelle aktiviert. Verwenden Sie Konfiguration nur, +`apply_patch` ist ein Untertool von `exec` für strukturierte dateiübergreifende Bearbeitungen. +Es ist standardmäßig für OpenAI- und OpenAI-Codex-Modelle aktiviert. Verwenden Sie die Konfiguration nur, wenn Sie es deaktivieren oder auf bestimmte Modelle beschränken möchten: ```json5 @@ -231,14 +231,14 @@ wenn Sie es deaktivieren oder auf bestimmte Modelle beschränken möchten: Hinweise: - Nur für OpenAI-/OpenAI-Codex-Modelle verfügbar. -- Die Tool-Richtlinie gilt weiterhin; `allow: ["write"]` erlaubt implizit `apply_patch`. -- Die Konfiguration liegt unter `tools.exec.applyPatch`. +- Die Tool-Richtlinie gilt weiterhin; `allow: ["write"]` erlaubt implizit auch `apply_patch`. +- Die Konfiguration befindet sich unter `tools.exec.applyPatch`. - `tools.exec.applyPatch.enabled` ist standardmäßig `true`; setzen Sie es auf `false`, um das Tool für OpenAI-Modelle zu deaktivieren. -- `tools.exec.applyPatch.workspaceOnly` ist standardmäßig `true` (innerhalb des Workspace begrenzt). Setzen Sie es nur dann auf `false`, wenn Sie ausdrücklich möchten, dass `apply_patch` außerhalb des Workspace-Verzeichnisses schreibt/löscht. +- `tools.exec.applyPatch.workspaceOnly` ist standardmäßig `true` (auf den Workspace beschränkt). Setzen Sie es nur dann auf `false`, wenn Sie ausdrücklich möchten, dass `apply_patch` außerhalb des Workspace-Verzeichnisses schreibt/löscht. ## Verwandt -- [Exec Approvals](/de/tools/exec-approvals) — Genehmigungsschranken für Shell-Befehle +- [Exec approvals](/de/tools/exec-approvals) — Freigabeschranken für Shell-Befehle - [Sandboxing](/de/gateway/sandboxing) — Ausführen von Befehlen in sandboxed Umgebungen -- [Background Process](/de/gateway/background-process) — lang laufendes exec- und process-Tool +- [Background Process](/de/gateway/background-process) — lang laufendes `exec` und `process`-Tool - [Security](/de/gateway/security) — Tool-Richtlinie und erhöhter Zugriff diff --git a/docs/de/tools/slash-commands.md b/docs/de/tools/slash-commands.md index eba31a662..72804bb24 100644 --- a/docs/de/tools/slash-commands.md +++ b/docs/de/tools/slash-commands.md @@ -1,14 +1,14 @@ --- read_when: - - Chat-Befehle verwenden oder konfigurieren - - Befehlsrouting oder Berechtigungen debuggen + - Verwendung oder Konfiguration von Chat-Befehlen + - Fehlerbehebung bei Befehlsrouting oder Berechtigungen summary: 'Slash-Befehle: Text vs. nativ, Konfiguration und unterstützte Befehle' title: Slash-Befehle x-i18n: - generated_at: "2026-04-12T23:34:01Z" + generated_at: "2026-04-21T13:38:03Z" model: gpt-5.4 provider: openai - source_hash: 9ef6f54500fa2ce3b873a8398d6179a0882b8bf6fba38f61146c64671055505e + source_hash: d90ddee54af7c05b7fdf486590561084581d750e42cd14674d43bbdc0984df5d source_path: tools/slash-commands.md workflow: 15 --- @@ -23,14 +23,14 @@ Es gibt zwei verwandte Systeme: - **Befehle**: eigenständige `/...`-Nachrichten. - **Direktiven**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - Direktiven werden aus der Nachricht entfernt, bevor das Modell sie sieht. - - In normalen Chat-Nachrichten (nicht nur Direktiven) werden sie als „Inline-Hinweise“ behandelt und **persistieren** keine Sitzungseinstellungen. - - In Nachrichten, die nur aus Direktiven bestehen (die Nachricht enthält nur Direktiven), werden sie für die Sitzung persistent gespeichert und mit einer Bestätigung beantwortet. + - In normalen Chat-Nachrichten (nicht nur Direktiven) werden sie als „Inline-Hinweise“ behandelt und **persistieren keine** Sitzungseinstellungen. + - In Nachrichten, die nur Direktiven enthalten (die Nachricht enthält nur Direktiven), werden sie in der Sitzung persistiert und beantworten mit einer Bestätigung. - Direktiven werden nur für **autorisierte Absender** angewendet. Wenn `commands.allowFrom` gesetzt ist, ist dies die einzige - verwendete Allowlist; andernfalls ergibt sich die Autorisierung aus Channel-Allowlists/Pairing plus `commands.useAccessGroups`. - Nicht autorisierte Absender sehen Direktiven als normalen Text. + verwendete Zulassungsliste; andernfalls stammt die Autorisierung aus Kanal-Zulassungslisten/Pairing plus `commands.useAccessGroups`. + Nicht autorisierte Absender sehen Direktiven als Klartext behandelt. -Es gibt außerdem einige **Inline-Kurzbefehle** (nur für allowlistete/autorisierte Absender): `/help`, `/commands`, `/status`, `/whoami` (`/id`). -Sie werden sofort ausgeführt, werden entfernt, bevor das Modell die Nachricht sieht, und der verbleibende Text läuft normal weiter. +Es gibt außerdem einige **Inline-Kurzbefehle** (nur für zugelassene/autorisierte Absender): `/help`, `/commands`, `/status`, `/whoami` (`/id`). +Sie werden sofort ausgeführt, werden entfernt, bevor das Modell die Nachricht sieht, und der verbleibende Text läuft durch den normalen Ablauf weiter. ## Konfiguration @@ -59,92 +59,92 @@ Sie werden sofort ausgeführt, werden entfernt, bevor das Modell die Nachricht s } ``` -- `commands.text` (Standard: `true`) aktiviert das Parsen von `/...` in Chat-Nachrichten. - - Auf Oberflächen ohne native Befehle (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) funktionieren Textbefehle auch dann noch, wenn Sie dies auf `false` setzen. -- `commands.native` (Standard: `"auto"`) registriert native Befehle. - - Auto: an für Discord/Telegram; aus für Slack (bis Sie Slash-Befehle hinzufügen); ignoriert für Provider ohne native Unterstützung. - - Setzen Sie `channels.discord.commands.native`, `channels.telegram.commands.native` oder `channels.slack.commands.native`, um pro Provider zu überschreiben (Bool oder `"auto"`). +- `commands.text` (Standard `true`) aktiviert das Parsen von `/...` in Chat-Nachrichten. + - Auf Oberflächen ohne native Befehle (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) funktionieren Textbefehle weiterhin, selbst wenn Sie dies auf `false` setzen. +- `commands.native` (Standard `"auto"`) registriert native Befehle. + - Auto: an für Discord/Telegram; aus für Slack (bis Sie Slash-Befehle hinzufügen); ignoriert für Anbieter ohne native Unterstützung. + - Setzen Sie `channels.discord.commands.native`, `channels.telegram.commands.native` oder `channels.slack.commands.native`, um pro Anbieter zu überschreiben (bool oder `"auto"`). - `false` löscht beim Start zuvor registrierte Befehle auf Discord/Telegram. Slack-Befehle werden in der Slack-App verwaltet und nicht automatisch entfernt. -- `commands.nativeSkills` (Standard: `"auto"`) registriert **Skill**-Befehle nativ, wenn unterstützt. - - Auto: an für Discord/Telegram; aus für Slack (Slack erfordert einen Slash-Befehl pro Skill). - - Setzen Sie `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` oder `channels.slack.commands.nativeSkills`, um pro Provider zu überschreiben (Bool oder `"auto"`). -- `commands.bash` (Standard: `false`) aktiviert `! `, um Host-Shell-Befehle auszuführen (`/bash ` ist ein Alias; erfordert `tools.elevated`-Allowlists). -- `commands.bashForegroundMs` (Standard: `2000`) steuert, wie lange Bash wartet, bevor in den Hintergrundmodus gewechselt wird (`0` verschiebt sofort in den Hintergrund). -- `commands.config` (Standard: `false`) aktiviert `/config` (liest/schreibt `openclaw.json`). -- `commands.mcp` (Standard: `false`) aktiviert `/mcp` (liest/schreibt OpenClaw-verwaltete MCP-Konfiguration unter `mcp.servers`). -- `commands.plugins` (Standard: `false`) aktiviert `/plugins` (Plugin-Erkennung/-Status plus Installations- und Aktivierungs-/Deaktivierungssteuerung). -- `commands.debug` (Standard: `false`) aktiviert `/debug` (nur Laufzeit-Überschreibungen). -- `commands.restart` (Standard: `true`) aktiviert `/restart` plus Tool-Aktionen zum Neustart des Gateways. -- `commands.ownerAllowFrom` (optional) setzt die explizite Owner-Allowlist für nur für Owner verfügbare Befehls-/Tool-Oberflächen. Dies ist getrennt von `commands.allowFrom`. -- `commands.ownerDisplay` steuert, wie Owner-IDs im System-Prompt erscheinen: `raw` oder `hash`. +- `commands.nativeSkills` (Standard `"auto"`) registriert **Skill**-Befehle nativ, wenn unterstützt. + - Auto: an für Discord/Telegram; aus für Slack (Slack erfordert das Anlegen eines Slash-Befehls pro Skill). + - Setzen Sie `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` oder `channels.slack.commands.nativeSkills`, um pro Anbieter zu überschreiben (bool oder `"auto"`). +- `commands.bash` (Standard `false`) aktiviert `! ` zum Ausführen von Host-Shell-Befehlen (`/bash ` ist ein Alias; erfordert `tools.elevated`-Zulassungslisten). +- `commands.bashForegroundMs` (Standard `2000`) steuert, wie lange Bash wartet, bevor in den Hintergrundmodus gewechselt wird (`0` schickt sofort in den Hintergrund). +- `commands.config` (Standard `false`) aktiviert `/config` (liest/schreibt `openclaw.json`). +- `commands.mcp` (Standard `false`) aktiviert `/mcp` (liest/schreibt die von OpenClaw verwaltete MCP-Konfiguration unter `mcp.servers`). +- `commands.plugins` (Standard `false`) aktiviert `/plugins` (Plugin-Erkennung/Status plus Installations- und Aktivierungs-/Deaktivierungssteuerung). +- `commands.debug` (Standard `false`) aktiviert `/debug` (nur Laufzeit-Überschreibungen). +- `commands.restart` (Standard `true`) aktiviert `/restart` plus Gateway-Neustart-Tool-Aktionen. +- `commands.ownerAllowFrom` (optional) setzt die explizite Zulassungsliste der Eigentümer für nur-Eigentümer-Befehls-/Tool-Oberflächen. Dies ist getrennt von `commands.allowFrom`. +- `commands.ownerDisplay` steuert, wie Eigentümer-IDs im System-Prompt erscheinen: `raw` oder `hash`. - `commands.ownerDisplaySecret` setzt optional das HMAC-Secret, das verwendet wird, wenn `commands.ownerDisplay="hash"` gesetzt ist. -- `commands.allowFrom` (optional) setzt eine Provider-spezifische Allowlist für die Befehlsautorisierung. Wenn konfiguriert, ist dies die - einzige Autorisierungsquelle für Befehle und Direktiven (Channel-Allowlists/Pairing und `commands.useAccessGroups` - werden ignoriert). Verwenden Sie `"*"` als globalen Standard; Provider-spezifische Schlüssel überschreiben ihn. -- `commands.useAccessGroups` (Standard: `true`) erzwingt Allowlists/Richtlinien für Befehle, wenn `commands.allowFrom` nicht gesetzt ist. +- `commands.allowFrom` (optional) setzt eine anbieterbezogene Zulassungsliste für die Befehlsautorisierung. Wenn konfiguriert, ist sie die + einzige Autorisierungsquelle für Befehle und Direktiven (Kanal-Zulassungslisten/Pairing und `commands.useAccessGroups` + werden ignoriert). Verwenden Sie `"*"` für einen globalen Standard; anbieterbezogene Schlüssel überschreiben ihn. +- `commands.useAccessGroups` (Standard `true`) erzwingt Zulassungslisten/Richtlinien für Befehle, wenn `commands.allowFrom` nicht gesetzt ist. ## Befehlsliste -Aktuelle Source of Truth: +Aktuelle Single Source of Truth: -- Core-Built-ins stammen aus `src/auto-reply/commands-registry.shared.ts` +- Kern-Integrationen stammen aus `src/auto-reply/commands-registry.shared.ts` - generierte Dock-Befehle stammen aus `src/auto-reply/commands-registry.data.ts` -- Plugin-Befehle stammen aus Plugin-`registerCommand()`-Aufrufen -- die tatsächliche Verfügbarkeit auf Ihrem Gateway hängt weiterhin von Konfigurationsflags, der Channel-Oberfläche und installierten/aktivierten Plugins ab +- Plugin-Befehle stammen aus Plugin-Aufrufen von `registerCommand()` +- die tatsächliche Verfügbarkeit auf Ihrem Gateway hängt weiterhin von Konfigurationsflags, Kanaloberfläche und installierten/aktivierten Plugins ab -### Core-Built-in-Befehle +### Integrierte Kernbefehle Heute verfügbare integrierte Befehle: - `/new [model]` startet eine neue Sitzung; `/reset` ist der Alias zum Zurücksetzen. -- `/compact [instructions]` verdichtet den Sitzungskontext. Siehe [/concepts/compaction](/de/concepts/compaction). -- `/stop` bricht den aktuellen Durchlauf ab. -- `/session idle ` und `/session max-age ` verwalten den Ablauf der Thread-Bindung. -- `/think ` setzt die Thinking-Stufe. Aliasse: `/thinking`, `/t`. +- `/compact [instructions]` komprimiert den Sitzungskontext. Siehe [/concepts/compaction](/de/concepts/compaction). +- `/stop` bricht die aktuelle Ausführung ab. +- `/session idle ` und `/session max-age ` verwalten das Ablaufen der Thread-Bindung. +- `/think ` setzt die Thinking-Stufe. Die Optionen stammen aus dem Anbieterprofil des aktiven Modells; gängige Stufen sind `off`, `minimal`, `low`, `medium` und `high`, mit benutzerdefinierten Stufen wie `xhigh`, `adaptive`, `max` oder binärem `on` nur dort, wo unterstützt. Aliasse: `/thinking`, `/t`. - `/verbose on|off|full` schaltet ausführliche Ausgabe um. Alias: `/v`. - `/trace on|off` schaltet Plugin-Trace-Ausgabe für die aktuelle Sitzung um. -- `/fast [status|on|off]` zeigt den Schnellmodus an oder setzt ihn. +- `/fast [status|on|off]` zeigt den Fast-Modus an oder setzt ihn. - `/reasoning [on|off|stream]` schaltet die Sichtbarkeit von Reasoning um. Alias: `/reason`. - `/elevated [on|off|ask|full]` schaltet den Elevated-Modus um. Alias: `/elev`. -- `/exec host= security= ask= node=` zeigt Exec-Standardwerte an oder setzt sie. +- `/exec host= security= ask= node=` zeigt die Exec-Standards an oder setzt sie. - `/model [name|#|status]` zeigt das Modell an oder setzt es. -- `/models [provider] [page] [limit=|size=|all]` listet Provider oder Modelle für einen Provider auf. -- `/queue ` verwaltet das Queue-Verhalten (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) plus Optionen wie `debounce:2s cap:25 drop:summarize`. -- `/help` zeigt die kurze Hilfezusammenfassung. -- `/commands` zeigt den generierten Befehlskatalog. -- `/tools [compact|verbose]` zeigt, was der aktuelle Agent gerade verwenden kann. -- `/status` zeigt den Laufzeitstatus, einschließlich Provider-Nutzung/Kontingent, sofern verfügbar. +- `/models [provider] [page] [limit=|size=|all]` listet Anbieter oder Modelle für einen Anbieter auf. +- `/queue ` verwaltet Queue-Verhalten (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) plus Optionen wie `debounce:2s cap:25 drop:summarize`. +- `/help` zeigt die kurze Hilfezusammenfassung an. +- `/commands` zeigt den generierten Befehlskatalog an. +- `/tools [compact|verbose]` zeigt an, was der aktuelle Agent gerade verwenden kann. +- `/status` zeigt den Laufzeitstatus an, einschließlich Anbieternutzung/Kontingent, falls verfügbar. - `/tasks` listet aktive/aktuelle Hintergrundaufgaben für die aktuelle Sitzung auf. -- `/context [list|detail|json]` erklärt, wie Kontext zusammengesetzt wird. +- `/context [list|detail|json]` erklärt, wie Kontext zusammengestellt wird. - `/export-session [path]` exportiert die aktuelle Sitzung nach HTML. Alias: `/export`. - `/whoami` zeigt Ihre Absender-ID an. Alias: `/id`. -- `/skill [input]` führt einen Skill anhand seines Namens aus. -- `/allowlist [list|add|remove] ...` verwaltet Allowlist-Einträge. Nur Text. -- `/approve ` löst Exec-Genehmigungsaufforderungen auf. -- `/btw ` stellt eine Nebenfrage, ohne den zukünftigen Sitzungskontext zu ändern. Siehe [/tools/btw](/de/tools/btw). -- `/subagents list|kill|log|info|send|steer|spawn` verwaltet Sub-Agent-Durchläufe für die aktuelle Sitzung. +- `/skill [input]` führt einen Skill nach Namen aus. +- `/allowlist [list|add|remove] ...` verwaltet Einträge in der Zulassungsliste. Nur Text. +- `/approve ` bearbeitet Exec-Genehmigungsabfragen. +- `/btw ` stellt eine Nebenfrage, ohne den künftigen Sitzungskontext zu ändern. Siehe [/tools/btw](/de/tools/btw). +- `/subagents list|kill|log|info|send|steer|spawn` verwaltet Sub-Agent-Ausführungen für die aktuelle Sitzung. - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` verwaltet ACP-Sitzungen und Laufzeitoptionen. -- `/focus ` bindet den aktuellen Discord-Thread oder das aktuelle Telegram-Thema/die aktuelle Unterhaltung an ein Sitzungsziel. +- `/focus ` bindet den aktuellen Discord-Thread oder das aktuelle Telegram-Thema/Gespräch an ein Sitzungsziel. - `/unfocus` entfernt die aktuelle Bindung. - `/agents` listet threadgebundene Agenten für die aktuelle Sitzung auf. - `/kill ` bricht einen oder alle laufenden Sub-Agenten ab. - `/steer ` sendet Steuerung an einen laufenden Sub-Agenten. Alias: `/tell`. -- `/config show|get|set|unset` liest oder schreibt `openclaw.json`. Nur Owner. Erfordert `commands.config: true`. -- `/mcp show|get|set|unset` liest oder schreibt OpenClaw-verwaltete MCP-Server-Konfiguration unter `mcp.servers`. Nur Owner. Erfordert `commands.mcp: true`. -- `/plugins list|inspect|show|get|install|enable|disable` prüft oder verändert den Plugin-Status. `/plugin` ist ein Alias. Schreibzugriffe nur für Owner. Erfordert `commands.plugins: true`. -- `/debug show|set|unset|reset` verwaltet nur zur Laufzeit geltende Konfigurationsüberschreibungen. Nur Owner. Erfordert `commands.debug: true`. -- `/usage off|tokens|full|cost` steuert den Nutzungs-Footer pro Antwort oder gibt eine lokale Kostenzusammenfassung aus. +- `/config show|get|set|unset` liest oder schreibt `openclaw.json`. Nur Eigentümer. Erfordert `commands.config: true`. +- `/mcp show|get|set|unset` liest oder schreibt von OpenClaw verwaltete MCP-Server-Konfiguration unter `mcp.servers`. Nur Eigentümer. Erfordert `commands.mcp: true`. +- `/plugins list|inspect|show|get|install|enable|disable` untersucht oder ändert den Plugin-Status. `/plugin` ist ein Alias. Schreibvorgänge nur für Eigentümer. Erfordert `commands.plugins: true`. +- `/debug show|set|unset|reset` verwaltet nur zur Laufzeit geltende Konfigurationsüberschreibungen. Nur Eigentümer. Erfordert `commands.debug: true`. +- `/usage off|tokens|full|cost` steuert die Nutzungsfußzeile pro Antwort oder gibt eine lokale Kostenzusammenfassung aus. - `/tts on|off|status|provider|limit|summary|audio|help` steuert TTS. Siehe [/tools/tts](/de/tools/tts). -- `/restart` startet OpenClaw neu, wenn aktiviert. Standard: aktiviert; setzen Sie `commands.restart: false`, um ihn zu deaktivieren. +- `/restart` startet OpenClaw neu, wenn aktiviert. Standard: aktiviert; setzen Sie `commands.restart: false`, um es zu deaktivieren. - `/activation mention|always` setzt den Gruppenaktivierungsmodus. -- `/send on|off|inherit` setzt die Send-Richtlinie. Nur Owner. -- `/bash ` führt einen Host-Shell-Befehl aus. Nur Text. Alias: `! `. Erfordert `commands.bash: true` plus `tools.elevated`-Allowlists. +- `/send on|off|inherit` setzt die Senderichtlinie. Nur Eigentümer. +- `/bash ` führt einen Host-Shell-Befehl aus. Nur Text. Alias: `! `. Erfordert `commands.bash: true` plus `tools.elevated`-Zulassungslisten. - `!poll [sessionId]` prüft einen Bash-Hintergrundjob. - `!stop [sessionId]` stoppt einen Bash-Hintergrundjob. ### Generierte Dock-Befehle -Dock-Befehle werden aus Channel-Plugins mit Unterstützung für native Befehle generiert. Aktuell gebündelter Satz: +Dock-Befehle werden aus Kanal-Plugins mit Unterstützung für native Befehle generiert. Aktueller gebündelter Satz: - `/dock-discord` (Alias: `/dock_discord`) - `/dock-mattermost` (Alias: `/dock_mattermost`) @@ -153,14 +153,14 @@ Dock-Befehle werden aus Channel-Plugins mit Unterstützung für native Befehle g ### Gebündelte Plugin-Befehle -Gebündelte Plugins können weitere Slash-Befehle hinzufügen. Aktuelle gebündelte Befehle in diesem Repo: +Gebündelte Plugins können weitere Slash-Befehle hinzufügen. Aktuelle gebündelte Befehle in diesem Repository: - `/dreaming [on|off|status|help]` schaltet Memory Dreaming um. Siehe [Dreaming](/de/concepts/dreaming). -- `/pair [qr|status|pending|approve|cleanup|notify]` verwaltet den Geräte-Pairing-/Einrichtungsablauf. Siehe [Pairing](/de/channels/pairing). -- `/phone status|arm [duration]|disarm` aktiviert vorübergehend risikoreiche Telefon-Node-Befehle. -- `/voice status|list [limit]|set ` verwaltet die Talk-Sprachkonfiguration. Auf Discord lautet der native Befehlsname `/talkvoice`. +- `/pair [qr|status|pending|approve|cleanup|notify]` verwaltet den Ablauf für Geräte-Pairing/-Einrichtung. Siehe [Pairing](/de/channels/pairing). +- `/phone status|arm [duration]|disarm` aktiviert vorübergehend Hochrisiko-Befehle des Phone-Node. +- `/voice status|list [limit]|set ` verwaltet die Talk-Sprachkonfiguration. Auf Discord ist der native Befehlsname `/talkvoice`. - `/card ...` sendet LINE-Rich-Card-Voreinstellungen. Siehe [LINE](/de/channels/line). -- `/codex status|models|threads|resume|compact|review|account|mcp|skills` prüft und steuert das gebündelte Codex-App-Server-Harness. Siehe [Codex Harness](/de/plugins/codex-harness). +- `/codex status|models|threads|resume|compact|review|account|mcp|skills` untersucht und steuert den gebündelten Codex-App-Server-Harness. Siehe [Codex Harness](/de/plugins/codex-harness). - Nur QQBot-Befehle: - `/bot-ping` - `/bot-version` @@ -170,71 +170,71 @@ Gebündelte Plugins können weitere Slash-Befehle hinzufügen. Aktuelle gebünde ### Dynamische Skill-Befehle -Vom Nutzer aufrufbare Skills werden ebenfalls als Slash-Befehle bereitgestellt: +Vom Benutzer aufrufbare Skills werden auch als Slash-Befehle bereitgestellt: - `/skill [input]` funktioniert immer als generischer Einstiegspunkt. - Skills können auch als direkte Befehle wie `/prose` erscheinen, wenn der Skill/das Plugin sie registriert. -- die Registrierung nativer Skill-Befehle wird durch `commands.nativeSkills` und `channels..commands.nativeSkills` gesteuert. +- Die Registrierung nativer Skill-Befehle wird über `commands.nativeSkills` und `channels..commands.nativeSkills` gesteuert. Hinweise: - Befehle akzeptieren optional ein `:` zwischen Befehl und Argumenten (z. B. `/think: high`, `/send: on`, `/help:`). -- `/new ` akzeptiert einen Modellalias, `provider/model` oder einen Providernamen (unscharfe Übereinstimmung); wenn es keine Übereinstimmung gibt, wird der Text als Nachrichtentext behandelt. -- Für die vollständige Aufschlüsselung der Provider-Nutzung verwenden Sie `openclaw status --usage`. -- `/allowlist add|remove` erfordert `commands.config=true` und berücksichtigt Channel-`configWrites`. -- In Multi-Account-Channels berücksichtigen das konfigurationsbezogene `/allowlist --account ` und `/config set channels..accounts....` ebenfalls die `configWrites` des Zielkontos. -- `/usage` steuert den Nutzungs-Footer pro Antwort; `/usage cost` gibt eine lokale Kostenzusammenfassung aus den OpenClaw-Sitzungslogs aus. -- `/restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um ihn zu deaktivieren. +- `/new ` akzeptiert einen Modellalias, `provider/model` oder einen Anbieternamen (unscharfer Abgleich); wenn es keine Übereinstimmung gibt, wird der Text als Nachrichtentext behandelt. +- Für die vollständige Aufschlüsselung der Anbieternutzung verwenden Sie `openclaw status --usage`. +- `/allowlist add|remove` erfordert `commands.config=true` und beachtet kanalbezogene `configWrites`. +- In Kanälen mit mehreren Konten beachten konfigurationsbezogenes `/allowlist --account ` und `/config set channels..accounts....` auch `configWrites` des Zielkontos. +- `/usage` steuert die Nutzungsfußzeile pro Antwort; `/usage cost` gibt eine lokale Kostenzusammenfassung aus OpenClaw-Sitzungsprotokollen aus. +- `/restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um es zu deaktivieren. - `/plugins install ` akzeptiert dieselben Plugin-Spezifikationen wie `openclaw plugins install`: lokaler Pfad/Archiv, npm-Paket oder `clawhub:`. - `/plugins enable|disable` aktualisiert die Plugin-Konfiguration und kann zu einem Neustart auffordern. -- Nur nativer Discord-Befehl: `/vc join|leave|status` steuert Sprachkanäle (erfordert `channels.discord.voice` und native Befehle; nicht als Text verfügbar). -- Discord-Thread-Bindungsbefehle (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) erfordern, dass effektive Thread-Bindungen aktiviert sind (`session.threadBindings.enabled` und/oder `channels.discord.threadBindings.enabled`). +- Nur auf Discord verfügbarer nativer Befehl: `/vc join|leave|status` steuert Sprachkanäle (erfordert `channels.discord.voice` und native Befehle; nicht als Text verfügbar). +- Discord-Befehle zur Thread-Bindung (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) erfordern, dass effektive Thread-Bindungen aktiviert sind (`session.threadBindings.enabled` und/oder `channels.discord.threadBindings.enabled`). - ACP-Befehlsreferenz und Laufzeitverhalten: [ACP Agents](/de/tools/acp-agents). - `/verbose` ist für Debugging und zusätzliche Sichtbarkeit gedacht; lassen Sie es im normalen Gebrauch **aus**. -- `/trace` ist enger gefasst als `/verbose`: Es zeigt nur Plugin-eigene Trace-/Debug-Zeilen und lässt normale ausführliche Tool-Ausgaben ausgeschaltet. -- `/fast on|off` speichert eine sitzungsbezogene Überschreibung. Verwenden Sie in der Sitzungs-UI die Option `inherit`, um sie zu löschen und auf die Standardwerte der Konfiguration zurückzufallen. -- `/fast` ist provider-spezifisch: OpenAI/OpenAI Codex ordnen es auf nativen Responses-Endpunkten `service_tier=priority` zu, während direkte öffentliche Anthropic-Anfragen, einschließlich per OAuth authentifiziertem Datenverkehr an `api.anthropic.com`, es `service_tier=auto` oder `standard_only` zuordnen. Siehe [OpenAI](/de/providers/openai) und [Anthropic](/de/providers/anthropic). -- Zusammenfassungen von Tool-Fehlern werden weiterhin angezeigt, wenn relevant, aber detaillierter Fehlertext wird nur aufgenommen, wenn `/verbose` auf `on` oder `full` steht. -- `/reasoning`, `/verbose` und `/trace` sind in Gruppeneinstellungen riskant: Sie können internes Reasoning, Tool-Ausgabe oder Plugin-Diagnosen offenlegen, die Sie nicht beabsichtigt hatten offenzulegen. Lassen Sie sie vorzugsweise ausgeschaltet, besonders in Gruppenchats. -- `/model` speichert das neue Sitzungsmodell sofort persistent. -- Wenn der Agent inaktiv ist, verwendet der nächste Durchlauf es sofort. -- Wenn bereits ein Durchlauf aktiv ist, markiert OpenClaw einen Live-Wechsel als ausstehend und startet erst an einem sauberen Wiederholungszeitpunkt in das neue Modell neu. -- Wenn Tool-Aktivität oder Antwortausgabe bereits begonnen hat, kann der ausstehende Wechsel bis zu einer späteren Wiederholungsmöglichkeit oder dem nächsten Nutzerzug in der Warteschlange bleiben. -- **Schnellpfad:** Nur-Befehl-Nachrichten von allowlisteten Absendern werden sofort verarbeitet (umgehen Queue + Modell). -- **Gruppen-Erwähnungs-Schranke:** Nur-Befehl-Nachrichten von allowlisteten Absendern umgehen Erwähnungsanforderungen. -- **Inline-Kurzbefehle (nur allowlistete Absender):** bestimmte Befehle funktionieren auch eingebettet in eine normale Nachricht und werden entfernt, bevor das Modell den verbleibenden Text sieht. - - Beispiel: `hey /status` löst eine Statusantwort aus, und der verbleibende Text läuft normal weiter. -- Derzeit: `/help`, `/commands`, `/status`, `/whoami` (`/id`). -- Nicht autorisierte Nur-Befehl-Nachrichten werden stillschweigend ignoriert, und Inline-`/...`-Token werden als normaler Text behandelt. -- **Skill-Befehle:** `user-invocable` Skills werden als Slash-Befehle bereitgestellt. Namen werden auf `a-z0-9_` bereinigt (max. 32 Zeichen); bei Kollisionen werden numerische Suffixe angehängt (z. B. `_2`). - - `/skill [input]` führt einen Skill anhand des Namens aus (nützlich, wenn native Befehlsgrenzen Befehle pro Skill verhindern). +- `/trace` ist enger gefasst als `/verbose`: Es zeigt nur plugin-eigene Trace-/Debug-Zeilen an und lässt normales ausführliches Tool-Logging ausgeschaltet. +- `/fast on|off` persistiert eine Sitzungsüberschreibung. Verwenden Sie in der Sitzungs-UI die Option `inherit`, um sie zu löschen und auf Konfigurationsstandards zurückzufallen. +- `/fast` ist anbieterspezifisch: OpenAI/OpenAI Codex ordnen es auf nativen Responses-Endpunkten `service_tier=priority` zu, während direkte öffentliche Anthropic-Anfragen, einschließlich an `api.anthropic.com` gesendetem OAuth-authentifiziertem Datenverkehr, es `service_tier=auto` oder `standard_only` zuordnen. Siehe [OpenAI](/de/providers/openai) und [Anthropic](/de/providers/anthropic). +- Zusammenfassungen von Tool-Fehlern werden weiterhin angezeigt, wenn relevant, aber detaillierter Fehlertext wird nur eingeschlossen, wenn `/verbose` `on` oder `full` ist. +- `/reasoning`, `/verbose` und `/trace` sind in Gruppensettings riskant: Sie können internes Reasoning, Tool-Ausgaben oder Plugin-Diagnosen offenlegen, die Sie nicht beabsichtigt hatten. Lassen Sie sie bevorzugt deaktiviert, insbesondere in Gruppenchats. +- `/model` persistiert das neue Sitzungsmodell sofort. +- Wenn der Agent untätig ist, verwendet die nächste Ausführung es sofort. +- Wenn bereits eine Ausführung aktiv ist, markiert OpenClaw einen Live-Wechsel als ausstehend und startet erst an einem sauberen Wiederholungspunkt in das neue Modell neu. +- Wenn Tool-Aktivität oder Antwortausgabe bereits begonnen hat, kann der ausstehende Wechsel bis zu einer späteren Wiederholungsmöglichkeit oder dem nächsten Benutzerzug in der Warteschlange bleiben. +- **Schnellpfad:** Nur-Befehl-Nachrichten von zugelassenen Absendern werden sofort verarbeitet (umgehen Queue + Modell). +- **Gruppen-Erwähnungs-Gating:** Nur-Befehl-Nachrichten von zugelassenen Absendern umgehen Erwähnungsanforderungen. +- **Inline-Kurzbefehle (nur für zugelassene Absender):** Bestimmte Befehle funktionieren auch, wenn sie in eine normale Nachricht eingebettet sind, und werden entfernt, bevor das Modell den verbleibenden Text sieht. + - Beispiel: `hey /status` löst eine Statusantwort aus, und der verbleibende Text läuft durch den normalen Ablauf weiter. +- Aktuell: `/help`, `/commands`, `/status`, `/whoami` (`/id`). +- Nicht autorisierte Nur-Befehl-Nachrichten werden stillschweigend ignoriert, und Inline-`/...`-Token werden als Klartext behandelt. +- **Skill-Befehle:** `user-invocable`-Skills werden als Slash-Befehle bereitgestellt. Namen werden auf `a-z0-9_` bereinigt (maximal 32 Zeichen); bei Kollisionen werden numerische Suffixe angehängt (z. B. `_2`). + - `/skill [input]` führt einen Skill nach Namen aus (nützlich, wenn native Befehlsgrenzen Befehle pro Skill verhindern). - Standardmäßig werden Skill-Befehle als normale Anfrage an das Modell weitergeleitet. - - Skills können optional `command-dispatch: tool` deklarieren, um den Befehl direkt an ein Tool zu leiten (deterministisch, ohne Modell). + - Skills können optional `command-dispatch: tool` deklarieren, um den Befehl direkt an ein Tool zu routen (deterministisch, ohne Modell). - Beispiel: `/prose` (OpenProse-Plugin) — siehe [OpenProse](/de/prose). -- **Argumente nativer Befehle:** Discord verwendet Autocomplete für dynamische Optionen (und Button-Menüs, wenn Sie erforderliche Argumente weglassen). Telegram und Slack zeigen ein Button-Menü an, wenn ein Befehl Auswahlmöglichkeiten unterstützt und Sie das Argument weglassen. +- **Argumente nativer Befehle:** Discord verwendet Autovervollständigung für dynamische Optionen (und Button-Menüs, wenn Sie erforderliche Argumente weglassen). Telegram und Slack zeigen ein Button-Menü an, wenn ein Befehl Auswahlmöglichkeiten unterstützt und Sie das Argument weglassen. ## `/tools` -`/tools` beantwortet eine Laufzeitfrage, keine Konfigurationsfrage: **was dieser Agent in -dieser Unterhaltung gerade verwenden kann**. +`/tools` beantwortet eine Laufzeitfrage, keine Konfigurationsfrage: **was dieser Agent jetzt gerade in +diesem Gespräch verwenden kann**. - Standard-`/tools` ist kompakt und für schnelles Überfliegen optimiert. - `/tools verbose` fügt kurze Beschreibungen hinzu. -- Oberflächen mit nativen Befehlen, die Argumente unterstützen, stellen denselben Moduswechsel als `compact|verbose` bereit. -- Ergebnisse sind sitzungsbezogen, daher können Änderungen an Agent, Channel, Thread, Absenderautorisierung oder Modell +- Oberflächen mit nativen Befehlen, die Argumente unterstützen, bieten denselben Moduswechsel als `compact|verbose`. +- Ergebnisse sind sitzungsbezogen, daher kann das Ändern von Agent, Kanal, Thread, Absenderautorisierung oder Modell die Ausgabe ändern. -- `/tools` enthält Tools, die zur Laufzeit tatsächlich erreichbar sind, einschließlich Core-Tools, verbundener - Plugin-Tools und Channel-eigener Tools. +- `/tools` enthält Tools, die zur Laufzeit tatsächlich erreichbar sind, einschließlich Kern-Tools, verbundener + Plugin-Tools und kanalbezogener Tools. -Für Profil- und Override-Bearbeitung verwenden Sie das Tools-Panel in der Control UI oder Konfigurations-/Katalogoberflächen, -anstatt `/tools` als statischen Katalog zu behandeln. +Für das Bearbeiten von Profilen und Überschreibungen verwenden Sie das Tools-Panel der Control-UI oder Konfigurations-/Katalogoberflächen, statt +`/tools` als statischen Katalog zu behandeln. ## Nutzungsoberflächen (was wo angezeigt wird) -- **Provider-Nutzung/Kontingent** (Beispiel: „Claude 80% left“) wird in `/status` für den aktuellen Modell-Provider angezeigt, wenn Nutzungsverfolgung aktiviert ist. OpenClaw normalisiert Provider-Fenster auf `% left`; bei MiniMax werden Prozentfelder, die nur den verbleibenden Anteil enthalten, vor der Anzeige invertiert, und Antworten mit `model_remains` bevorzugen den Chat-Modell-Eintrag plus ein modellmarkiertes Tariflabel. -- **Token-/Cache-Zeilen** in `/status` können auf den neuesten Usage-Eintrag im Transcript zurückfallen, wenn der Live-Sitzungs-Snapshot unvollständig ist. Bereits vorhandene Live-Werte ungleich null haben weiterhin Vorrang, und der Transcript-Fallback kann auch das aktive Laufzeit-Modelllabel plus eine größere promptorientierte Gesamtsumme wiederherstellen, wenn gespeicherte Summen fehlen oder kleiner sind. -- **Tokens/Kosten pro Antwort** werden mit `/usage off|tokens|full` gesteuert (an normale Antworten angehängt). -- `/model status` bezieht sich auf **Modelle/Auth/Endpunkte**, nicht auf Nutzung. +- **Anbieternutzung/Kontingent** (Beispiel: „Claude 80% left“) erscheint in `/status` für den aktuellen Modellanbieter, wenn Nutzungsverfolgung aktiviert ist. OpenClaw normalisiert Anbieterfenster zu `% left`; bei MiniMax werden verbleibend-only-Prozentfelder vor der Anzeige invertiert, und Antworten mit `model_remains` bevorzugen den Chat-Modelleintrag plus ein modellmarkiertes Plan-Label. +- **Token-/Cache-Zeilen** in `/status` können auf den neuesten Nutzungseintrag im Transkript zurückfallen, wenn der Live-Sitzungs-Snapshot spärlich ist. Vorhandene von null verschiedene Live-Werte haben weiterhin Vorrang, und der Transkript-Fallback kann auch das aktive Laufzeitmodell-Label plus eine größere promptorientierte Gesamtsumme wiederherstellen, wenn gespeicherte Summen fehlen oder kleiner sind. +- **Tokens/Kosten pro Antwort** werden über `/usage off|tokens|full` gesteuert (an normale Antworten angehängt). +- `/model status` betrifft **Modelle/Auth/Endpunkte**, nicht die Nutzung. ## Modellauswahl (`/model`) @@ -253,14 +253,14 @@ Beispiele: Hinweise: -- `/model` und `/model list` zeigen einen kompakten nummerierten Auswahlbereich (Modellfamilie + verfügbare Provider). -- Auf Discord öffnen `/model` und `/models` einen interaktiven Auswahlbereich mit Provider- und Modell-Dropdowns plus einem Schritt zum Absenden. -- `/model <#>` wählt aus diesem Auswahlbereich aus (und bevorzugt nach Möglichkeit den aktuellen Provider). -- `/model status` zeigt die Detailansicht, einschließlich konfiguriertem Provider-Endpunkt (`baseUrl`) und API-Modus (`api`), sofern verfügbar. +- `/model` und `/model list` zeigen eine kompakte, nummerierte Auswahl an (Modellfamilie + verfügbare Anbieter). +- Auf Discord öffnen `/model` und `/models` eine interaktive Auswahl mit Dropdowns für Anbieter und Modell plus einem Submit-Schritt. +- `/model <#>` wählt aus dieser Auswahl aus (und bevorzugt wenn möglich den aktuellen Anbieter). +- `/model status` zeigt die Detailansicht an, einschließlich konfiguriertem Anbieter-Endpunkt (`baseUrl`) und API-Modus (`api`), sofern verfügbar. -## Debug-Overrides +## Debug-Überschreibungen -`/debug` ermöglicht das Setzen von **nur zur Laufzeit geltenden** Konfigurations-Overrides (Memory, nicht Festplatte). Nur Owner. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.debug: true`. +`/debug` ermöglicht das Setzen von **nur zur Laufzeit gültigen** Konfigurationsüberschreibungen (Arbeitsspeicher, nicht Festplatte). Nur Eigentümer. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.debug: true`. Beispiele: @@ -274,12 +274,12 @@ Beispiele: Hinweise: -- Overrides gelten sofort für neue Konfigurationslesevorgänge, schreiben aber **nicht** in `openclaw.json`. -- Verwenden Sie `/debug reset`, um alle Overrides zu löschen und zur Konfiguration auf der Festplatte zurückzukehren. +- Überschreibungen gelten sofort für neue Konfigurationslesevorgänge, schreiben aber **nicht** in `openclaw.json`. +- Verwenden Sie `/debug reset`, um alle Überschreibungen zu löschen und zur Konfiguration auf Datenträger zurückzukehren. ## Plugin-Trace-Ausgabe -`/trace` ermöglicht das Umschalten von **sitzungsbezogenen Plugin-Trace-/Debug-Zeilen**, ohne den vollständigen Verbose-Modus einzuschalten. +`/trace` ermöglicht das Umschalten **sitzungsbezogener pluginbezogener Trace-/Debug-Zeilen**, ohne den vollständigen ausführlichen Modus einzuschalten. Beispiele: @@ -295,12 +295,12 @@ Hinweise: - `/trace on` aktiviert Plugin-Trace-Zeilen für die aktuelle Sitzung. - `/trace off` deaktiviert sie wieder. - Plugin-Trace-Zeilen können in `/status` und als diagnostische Folgemeldung nach der normalen Assistentenantwort erscheinen. -- `/trace` ersetzt `/debug` nicht; `/debug` verwaltet weiterhin nur Laufzeit-Konfigurations-Overrides. +- `/trace` ersetzt `/debug` nicht; `/debug` verwaltet weiterhin nur zur Laufzeit gültige Konfigurationsüberschreibungen. - `/trace` ersetzt `/verbose` nicht; normale ausführliche Tool-/Statusausgabe gehört weiterhin zu `/verbose`. ## Konfigurationsaktualisierungen -`/config` schreibt in Ihre Konfiguration auf der Festplatte (`openclaw.json`). Nur Owner. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.config: true`. +`/config` schreibt in Ihre Konfiguration auf Datenträger (`openclaw.json`). Nur Eigentümer. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.config: true`. Beispiele: @@ -315,11 +315,11 @@ Beispiele: Hinweise: - Die Konfiguration wird vor dem Schreiben validiert; ungültige Änderungen werden abgelehnt. -- `/config`-Aktualisierungen bleiben über Neustarts hinweg erhalten. +- Aktualisierungen durch `/config` bleiben über Neustarts hinweg erhalten. ## MCP-Aktualisierungen -`/mcp` schreibt von OpenClaw verwaltete MCP-Serverdefinitionen unter `mcp.servers`. Nur Owner. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.mcp: true`. +`/mcp` schreibt von OpenClaw verwaltete MCP-Serverdefinitionen unter `mcp.servers`. Nur Eigentümer. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.mcp: true`. Beispiele: @@ -332,12 +332,12 @@ Beispiele: Hinweise: -- `/mcp` speichert die Konfiguration in der OpenClaw-Konfiguration, nicht in Pi-eigenen Projekteinstellungen. -- Laufzeit-Adapter entscheiden, welche Transporte tatsächlich ausführbar sind. +- `/mcp` speichert Konfiguration in der OpenClaw-Konfiguration, nicht in Pi-eigenen Projekteinstellungen. +- Laufzeitadapter entscheiden, welche Transporte tatsächlich ausführbar sind. ## Plugin-Aktualisierungen -`/plugins` ermöglicht es Operatoren, erkannte Plugins zu prüfen und deren Aktivierung in der Konfiguration umzuschalten. Schreibgeschützte Abläufe können `/plugin` als Alias verwenden. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.plugins: true`. +`/plugins` ermöglicht es Operatoren, erkannte Plugins zu prüfen und die Aktivierung in der Konfiguration umzuschalten. Nur-Lese-Abläufe können `/plugin` als Alias verwenden. Standardmäßig deaktiviert; aktivieren Sie es mit `commands.plugins: true`. Beispiele: @@ -351,41 +351,41 @@ Beispiele: Hinweise: -- `/plugins list` und `/plugins show` verwenden echte Plugin-Erkennung anhand des aktuellen Workspace plus der Konfiguration auf der Festplatte. -- `/plugins enable|disable` aktualisiert nur die Plugin-Konfiguration; Plugins werden dadurch nicht installiert oder deinstalliert. -- Starten Sie das Gateway nach Änderungen an enable/disable neu, damit sie wirksam werden. +- `/plugins list` und `/plugins show` verwenden echte Plugin-Erkennung gegen den aktuellen Workspace plus die Konfiguration auf Datenträger. +- `/plugins enable|disable` aktualisiert nur die Plugin-Konfiguration; Plugins werden nicht installiert oder deinstalliert. +- Starten Sie das Gateway nach Änderungen an Aktivieren/Deaktivieren neu, damit sie angewendet werden. ## Hinweise zu Oberflächen -- **Textbefehle** laufen in der normalen Chat-Sitzung (DMs teilen sich `main`, Gruppen haben ihre eigene Sitzung). +- **Textbefehle** laufen in der normalen Chatsitzung (DMs teilen sich `main`, Gruppen haben ihre eigene Sitzung). - **Native Befehle** verwenden isolierte Sitzungen: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (Präfix über `channels.slack.slashCommand.sessionPrefix` konfigurierbar) - - Telegram: `telegram:slash:` (zielt über `CommandTargetSessionKey` auf die Chat-Sitzung) -- **`/stop`** zielt auf die aktive Chat-Sitzung, damit der aktuelle Durchlauf abgebrochen werden kann. -- **Slack:** `channels.slack.slashCommand` wird weiterhin für einen einzelnen Befehl im Stil von `/openclaw` unterstützt. Wenn Sie `commands.native` aktivieren, müssen Sie einen Slack-Slash-Befehl pro integrierten Befehl erstellen (mit denselben Namen wie `/help`). Menüs für Befehlsargumente werden bei Slack als ephemere Block-Kit-Buttons bereitgestellt. - - Native Slack-Ausnahme: Registrieren Sie `/agentstatus` (nicht `/status`), weil Slack `/status` reserviert. Text-`/status` funktioniert in Slack-Nachrichten weiterhin. + - Telegram: `telegram:slash:` (zielt über `CommandTargetSessionKey` auf die Chatsitzung) +- **`/stop`** zielt auf die aktive Chatsitzung, damit die aktuelle Ausführung abgebrochen werden kann. +- **Slack:** `channels.slack.slashCommand` wird weiterhin für einen einzelnen Befehl im Stil von `/openclaw` unterstützt. Wenn Sie `commands.native` aktivieren, müssen Sie einen Slack-Slash-Befehl pro integriertem Befehl anlegen (mit denselben Namen wie `/help`). Menüs für Befehlsargumente werden in Slack als ephemere Block-Kit-Buttons bereitgestellt. + - Native Slack-Ausnahme: Registrieren Sie `/agentstatus` (nicht `/status`), weil Slack `/status` reserviert. Text-`/status` funktioniert weiterhin in Slack-Nachrichten. ## BTW-Nebenfragen `/btw` ist eine schnelle **Nebenfrage** zur aktuellen Sitzung. -Im Gegensatz zu normalem Chat: +Anders als normaler Chat: -- verwendet sie die aktuelle Sitzung als Hintergrundkontext, -- läuft sie als separater **tool-loser** Einmalaufruf, -- ändert sie den zukünftigen Sitzungskontext nicht, -- wird sie nicht in den Transcript-Verlauf geschrieben, -- wird sie als Live-Seitenergebnis statt als normale Assistentennachricht zugestellt. +- verwendet es die aktuelle Sitzung als Hintergrundkontext, +- läuft es als separater **tool-loser** One-Shot-Aufruf, +- ändert es den zukünftigen Sitzungskontext nicht, +- wird es nicht in den Transkriptverlauf geschrieben, +- wird es als Live-Nebenergebnis statt als normale Assistentennachricht zugestellt. -Dadurch ist `/btw` nützlich, wenn Sie eine vorübergehende Klärung möchten, während die Haupt- +Das macht `/btw` nützlich, wenn Sie eine vorübergehende Klärung möchten, während die Haupt- aufgabe weiterläuft. Beispiel: ```text -/btw what are we doing right now? +/btw was machen wir gerade? ``` -Siehe [BTW Side Questions](/de/tools/btw) für das vollständige Verhalten und die -Details der Client-UX. +Siehe [BTW Side Questions](/de/tools/btw) für das vollständige Verhalten und Details +zur Client-UX. diff --git a/docs/de/tools/thinking.md b/docs/de/tools/thinking.md index a57849074..c8bf72a72 100644 --- a/docs/de/tools/thinking.md +++ b/docs/de/tools/thinking.md @@ -1,127 +1,131 @@ --- read_when: - - Anpassen von Thinking, Schnellmodus oder der Verarbeitung bzw. Standardwerte von Direktiven für ausführliche Ausgabe -summary: Syntax für Direktiven für /think, /fast, /verbose, /trace und die Sichtbarkeit von Reasoning -title: Thinking-Stufen + - Parsing oder Standardwerte für Thinking-, Fast-Mode- oder Verbose-Direktiven anpassen +summary: Direktivsyntax für /think, /fast, /verbose, /trace und die Sichtbarkeit von Reasoning +title: Thinking-Level x-i18n: - generated_at: "2026-04-21T06:31:57Z" + generated_at: "2026-04-21T13:38:06Z" model: gpt-5.4 provider: openai - source_hash: edee9420e1cc3eccfa18d87061c4a4d6873e70cb51fff85305fafbcd6a5d6a7d + source_hash: 1b0217f6e5a5cb3400090f31ad5271ca61848a40f77d3f942851e7c2f2352886 source_path: tools/thinking.md workflow: 15 --- -# Thinking-Stufen (`/think`-Direktiven) +# Thinking-Level (/think-Direktiven) ## Was es bewirkt -- Inline-Direktive in jedem eingehenden Text: `/t `, `/think:` oder `/thinking `. -- Stufen (Aliasse): `off | minimal | low | medium | high | xhigh | adaptive | max` +- Inline-Direktive in jedem eingehenden Body: `/t `, `/think:` oder `/thinking `. +- Level (Aliase): `off | minimal | low | medium | high | xhigh | adaptive | max` - minimal → „think“ - low → „think hard“ - medium → „think harder“ - high → „ultrathink“ (maximales Budget) - - xhigh → „ultrathink+“ (GPT-5.2 + Codex-Modelle und Anthropic Claude Opus 4.7 effort) + - xhigh → „ultrathink+“ (GPT-5.2- und Codex-Modelle sowie Anthropic Claude Opus 4.7 effort) - adaptive → vom Provider verwaltetes adaptives Thinking (unterstützt für Claude 4.6 auf Anthropic/Bedrock und Anthropic Claude Opus 4.7) - - max → maximales Reasoning des Providers (derzeit Anthropic Claude Opus 4.7) + - max → maximales Provider-Reasoning (derzeit Anthropic Claude Opus 4.7) - `x-high`, `x_high`, `extra-high`, `extra high` und `extra_high` werden auf `xhigh` abgebildet. - `highest` wird auf `high` abgebildet. - Hinweise zu Providern: - - `adaptive` wird in nativen Befehlsmenüs und Auswahllisten nur für Provider/Modelle angezeigt, die Unterstützung für adaptives Thinking deklarieren. Es bleibt als getippte Direktive zur Kompatibilität mit vorhandenen Konfigurationen und Aliasen weiterhin akzeptiert. - - `max` wird in nativen Befehlsmenüs und Auswahllisten nur für Provider/Modelle angezeigt, die Unterstützung für maximales Thinking deklarieren. Vorhandene gespeicherte Einstellungen `max` werden auf die größte unterstützte Stufe für das ausgewählte Modell umgebildet, wenn das Modell `max` nicht unterstützt. - - Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive`, wenn keine explizite Thinking-Stufe gesetzt ist. - - Anthropic Claude Opus 4.7 verwendet standardmäßig kein adaptives Thinking. Der Standard für API-effort bleibt Eigentum des Providers, sofern Sie nicht explizit eine Thinking-Stufe setzen. - - Anthropic Claude Opus 4.7 bildet `/think xhigh` auf adaptives Thinking plus `output_config.effort: "xhigh"` ab, weil `/think` eine Thinking-Direktive ist und `xhigh` die Opus-4.7-Einstellung für effort ist. - - Anthropic Claude Opus 4.7 bietet auch `/think max`; es wird auf denselben vom Provider verwalteten Pfad für maximalen effort abgebildet. - - OpenAI-GPT-Modelle bilden `/think` über die modellabhängige Unterstützung der Responses API für effort ab. `/think off` sendet `reasoning.effort: "none"` nur dann, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die Payload für deaktiviertes Reasoning weg, statt einen nicht unterstützten Wert zu senden. - - MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Thinking nicht explizit in Modellparametern oder Anfrageparametern setzen. Dies vermeidet durchgesickerte Deltas von `reasoning_content` aus dem nicht nativen Anthropic-Stream-Format von MiniMax. - - Z.AI (`zai/*`) unterstützt nur binäres Thinking (`on`/`off`). Jede Stufe außer `off` wird als `on` behandelt (auf `low` abgebildet). - - Moonshot (`moonshot/*`) bildet `/think off` auf `thinking: { type: "disabled" }` und jede Stufe außer `off` auf `thinking: { type: "enabled" }` ab. Wenn Thinking aktiviert ist, akzeptiert Moonshot für `tool_choice` nur `auto|none`; OpenClaw normalisiert inkompatible Werte auf `auto`. + - Thinking-Menüs und -Picker sind providerprofilgesteuert. Provider-Plugins deklarieren den genauen Level-Satz für das ausgewählte Modell, einschließlich Labels wie binäres `on`. + - `adaptive`, `xhigh` und `max` werden nur für Provider-/Modellprofile angezeigt, die sie unterstützen. Eingegebene Direktiven für nicht unterstützte Level werden mit den gültigen Optionen dieses Modells abgelehnt. + - Bereits gespeicherte, nicht unterstützte Level, einschließlich alter `max`-Werte nach einem Modellwechsel, werden auf das höchste unterstützte Level für das ausgewählte Modell umgebildet. + - Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive`, wenn kein explizites Thinking-Level gesetzt ist. + - Anthropic Claude Opus 4.7 verwendet standardmäßig kein adaptives Thinking. Sein standardmäßiger API-effort bleibt providerseitig verwaltet, sofern Sie nicht explizit ein Thinking-Level setzen. + - Anthropic Claude Opus 4.7 bildet `/think xhigh` auf adaptives Thinking plus `output_config.effort: "xhigh"` ab, weil `/think` eine Thinking-Direktive ist und `xhigh` die Opus-4.7-effort-Einstellung ist. + - Anthropic Claude Opus 4.7 stellt auch `/think max` bereit; dies wird auf denselben providerseitigen Pfad für maximalen effort abgebildet. + - OpenAI-GPT-Modelle bilden `/think` über modellabhängige Unterstützung für effort in der Responses API ab. `/think off` sendet `reasoning.effort: "none"` nur dann, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die deaktivierte Reasoning-Payload weg, statt einen nicht unterstützten Wert zu senden. + - MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Thinking nicht explizit in Modellparametern oder Request-Parametern setzen. Dies verhindert durchgesickerte `reasoning_content`-Deltas aus dem nicht nativen Anthropic-Stream-Format von MiniMax. + - Z.AI (`zai/*`) unterstützt nur binäres Thinking (`on`/`off`). Jedes andere Level als `off` wird als `on` behandelt (abgebildet auf `low`). + - Moonshot (`moonshot/*`) bildet `/think off` auf `thinking: { type: "disabled" }` und jedes andere Level als `off` auf `thinking: { type: "enabled" }` ab. Wenn Thinking aktiviert ist, akzeptiert Moonshot für `tool_choice` nur `auto|none`; OpenClaw normalisiert inkompatible Werte auf `auto`. -## Reihenfolge der Auflösung +## Auflösungsreihenfolge 1. Inline-Direktive in der Nachricht (gilt nur für diese Nachricht). -2. Sitzungsüberschreibung (gesetzt durch das Senden einer Nachricht, die nur aus einer Direktive besteht). -3. Standard pro Agent (`agents.list[].thinkingDefault` in der Konfiguration). -4. Globaler Standard (`agents.defaults.thinkingDefault` in der Konfiguration). -5. Fallback: `adaptive` für Anthropic-Claude-4.6-Modelle, `off` für Anthropic Claude Opus 4.7, sofern nicht explizit konfiguriert, `low` für andere Reasoning-fähige Modelle, sonst `off`. +2. Sitzungsüberschreibung (gesetzt durch Senden einer Nachricht, die nur aus einer Direktive besteht). +3. Standardwert pro Agent (`agents.list[].thinkingDefault` in der Konfiguration). +4. Globaler Standardwert (`agents.defaults.thinkingDefault` in der Konfiguration). +5. Fallback: vom Provider deklarierter Standardwert, falls verfügbar, `low` für andere Katalogmodelle mit aktivierter Reasoning-Fähigkeit, sonst `off`. ## Einen Sitzungsstandard setzen -- Senden Sie eine Nachricht, die **nur** aus der Direktive besteht (Leerraum ist erlaubt), z. B. `/think:medium` oder `/t high`. -- Das bleibt für die aktuelle Sitzung bestehen (standardmäßig pro Absender); wird durch `/think:off` oder einen Leerlauf-Reset der Sitzung gelöscht. -- Es wird eine Bestätigungsantwort gesendet (`Thinking level set to high.` / `Thinking disabled.`). Wenn die Stufe ungültig ist (z. B. `/thinking big`), wird der Befehl mit einem Hinweis abgelehnt, und der Sitzungsstatus bleibt unverändert. -- Senden Sie `/think` (oder `/think:`) ohne Argument, um die aktuelle Thinking-Stufe zu sehen. +- Senden Sie eine Nachricht, die **nur** aus der Direktive besteht (Leerraum erlaubt), z. B. `/think:medium` oder `/t high`. +- Das bleibt für die aktuelle Sitzung bestehen (standardmäßig pro Absender); zurückgesetzt durch `/think:off` oder Sitzungs-Idle-Reset. +- Eine Bestätigungsantwort wird gesendet (`Thinking level set to high.` / `Thinking disabled.`). Wenn das Level ungültig ist (z. B. `/thinking big`), wird der Befehl mit einem Hinweis abgelehnt und der Sitzungszustand bleibt unverändert. +- Senden Sie `/think` (oder `/think:`) ohne Argument, um das aktuelle Thinking-Level anzuzeigen. ## Anwendung nach Agent -- **Embedded Pi**: Die aufgelöste Stufe wird an die Laufzeit des In-Process-Pi-Agenten übergeben. +- **Eingebettetes Pi**: Das aufgelöste Level wird an die In-Process-Agent-Laufzeit von Pi übergeben. -## Schnellmodus (`/fast`) +## Fast-Modus (/fast) -- Stufen: `on|off`. -- Eine Nachricht, die nur aus einer Direktive besteht, schaltet eine Sitzungsüberschreibung für den Schnellmodus um und antwortet mit `Fast mode enabled.` / `Fast mode disabled.`. -- Senden Sie `/fast` (oder `/fast status`) ohne Modus, um den aktuellen effektiven Status des Schnellmodus zu sehen. -- OpenClaw löst den Schnellmodus in dieser Reihenfolge auf: - 1. Inline-/nur-Direktive `/fast on|off` +- Level: `on|off`. +- Eine Nachricht, die nur aus einer Direktive besteht, schaltet eine Sitzungsüberschreibung für den Fast-Modus um und antwortet mit `Fast mode enabled.` / `Fast mode disabled.`. +- Senden Sie `/fast` (oder `/fast status`) ohne Modus, um den aktuell wirksamen Fast-Mode-Status anzuzeigen. +- OpenClaw löst den Fast-Modus in dieser Reihenfolge auf: + 1. Inline-/Direktive-only-`/fast on|off` 2. Sitzungsüberschreibung - 3. Standard pro Agent (`agents.list[].fastModeDefault`) + 3. Standardwert pro Agent (`agents.list[].fastModeDefault`) 4. Konfiguration pro Modell: `agents.defaults.models["/"].params.fastMode` 5. Fallback: `off` -- Für `openai/*` wird der Schnellmodus auf die Prioritätsverarbeitung von OpenAI abgebildet, indem bei unterstützten Responses-Anfragen `service_tier=priority` gesendet wird. -- Für `openai-codex/*` sendet der Schnellmodus dasselbe Flag `service_tier=priority` bei Codex Responses. OpenClaw behält einen gemeinsamen Umschalter `/fast` für beide Authentifizierungspfade bei. -- Für direkte öffentliche `anthropic/*`-Anfragen, einschließlich per OAuth authentifiziertem Datenverkehr an `api.anthropic.com`, wird der Schnellmodus auf die Service-Tiers von Anthropic abgebildet: `/fast on` setzt `service_tier=auto`, `/fast off` setzt `service_tier=standard_only`. +- Für `openai/*` wird der Fast-Modus auf priorisierte OpenAI-Verarbeitung abgebildet, indem bei unterstützten Responses-Requests `service_tier=priority` gesendet wird. +- Für `openai-codex/*` sendet der Fast-Modus dasselbe Flag `service_tier=priority` bei Codex Responses. OpenClaw verwendet einen gemeinsamen `/fast`-Schalter über beide Auth-Pfade hinweg. +- Für direkte öffentliche `anthropic/*`-Requests, einschließlich per OAuth authentifiziertem Traffic an `api.anthropic.com`, wird der Fast-Modus auf Anthropic-Service-Tiers abgebildet: `/fast on` setzt `service_tier=auto`, `/fast off` setzt `service_tier=standard_only`. - Für `minimax/*` auf dem Anthropic-kompatiblen Pfad schreibt `/fast on` (oder `params.fastMode: true`) `MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um. -- Explizite Anthropic-Modellparameter `serviceTier` / `service_tier` überschreiben den Standard des Schnellmodus, wenn beide gesetzt sind. OpenClaw überspringt weiterhin das Einfügen des Anthropic-Service-Tiers für Base-URLs von Nicht-Anthropic-Proxys. +- Explizite Anthropic-Modellparameter `serviceTier` / `service_tier` überschreiben den Standard des Fast-Modus, wenn beide gesetzt sind. OpenClaw überspringt weiterhin die Einfügung von Anthropic-Service-Tiers für nicht-Anthropic-Proxy-`baseUrl`s. -## Direktiven für ausführliche Ausgabe (`/verbose` oder `/v`) +## Verbose-Direktiven (/verbose oder /v) -- Stufen: `on` (minimal) | `full` | `off` (Standard). -- Eine Nachricht, die nur aus einer Direktive besteht, schaltet die ausführliche Ausgabe für die Sitzung um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Stufen liefern einen Hinweis, ohne den Status zu ändern. -- `/verbose off` speichert eine explizite Sitzungsüberschreibung; löschen Sie sie über die Sitzungs-UI, indem Sie `inherit` wählen. -- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; ansonsten gelten Standardwerte für Sitzung/global. -- Senden Sie `/verbose` (oder `/verbose:`) ohne Argument, um die aktuelle Stufe für ausführliche Ausgabe zu sehen. -- Wenn die ausführliche Ausgabe aktiviert ist, senden Agenten, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agenten), jeden Tool-Aufruf als eigene Nachricht nur mit Metadaten zurück, mit dem Präfix ` : `, sofern verfügbar (Pfad/Befehl). Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Blasen), nicht als Streaming-Deltas. -- Zusammenfassungen von Tool-Fehlern bleiben im normalen Modus sichtbar, aber rohe Fehlersuffixe werden verborgen, sofern `verbose` nicht `on` oder `full` ist. -- Wenn `verbose` `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Blase, auf eine sichere Länge gekürzt). Wenn Sie während eines laufenden Vorgangs `/verbose on|full|off` umschalten, berücksichtigen nachfolgende Tool-Blasen die neue Einstellung. +- Level: `on` (minimal) | `full` | `off` (Standard). +- Eine Nachricht, die nur aus einer Direktive besteht, schaltet Verbose auf Sitzungsebene um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Level liefern einen Hinweis zurück, ohne den Zustand zu ändern. +- `/verbose off` speichert eine explizite Sitzungsüberschreibung; löschen Sie sie über die Sessions-UI, indem Sie `inherit` auswählen. +- Eine Inline-Direktive gilt nur für diese Nachricht; Sitzungs-/globale Standardwerte gelten sonst. +- Senden Sie `/verbose` (oder `/verbose:`) ohne Argument, um das aktuelle Verbose-Level anzuzeigen. +- Wenn Verbose aktiviert ist, senden Agenten, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agenten), jeden Tool-Aufruf als eigene Nachricht nur mit Metadaten zurück, sofern verfügbar mit Präfix ` : ` (Pfad/Befehl). Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Bubbles), nicht als Streaming-Deltas. +- Zusammenfassungen von Tool-Fehlern bleiben im normalen Modus sichtbar, aber rohe Detailsuffixe von Fehlern werden ausgeblendet, sofern Verbose nicht `on` oder `full` ist. +- Wenn Verbose `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Bubble, auf eine sichere Länge gekürzt). Wenn Sie `/verbose on|full|off` während einer laufenden Ausführung umschalten, berücksichtigen nachfolgende Tool-Bubbles die neue Einstellung. -## Plugin-Trace-Direktiven (`/trace`) +## Plugin-Trace-Direktiven (/trace) -- Stufen: `on` | `off` (Standard). -- Eine Nachricht, die nur aus einer Direktive besteht, schaltet die Plugin-Trace-Ausgabe für die Sitzung um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`. -- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; ansonsten gelten Standardwerte für Sitzung/global. -- Senden Sie `/trace` (oder `/trace:`) ohne Argument, um die aktuelle Trace-Stufe zu sehen. -- `/trace` ist enger gefasst als `/verbose`: Es zeigt nur Plugin-eigene Trace-/Debug-Zeilen wie Active-Memory-Debug-Zusammenfassungen an. -- Trace-Zeilen können in `/status` und als nachfolgende Diagnosenachricht nach der normalen Assistentenantwort erscheinen. +- Level: `on` | `off` (Standard). +- Eine Nachricht, die nur aus einer Direktive besteht, schaltet die Plugin-Trace-Ausgabe auf Sitzungsebene um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`. +- Eine Inline-Direktive gilt nur für diese Nachricht; Sitzungs-/globale Standardwerte gelten sonst. +- Senden Sie `/trace` (oder `/trace:`) ohne Argument, um das aktuelle Trace-Level anzuzeigen. +- `/trace` ist enger als `/verbose`: Es zeigt nur plugin-eigene Trace-/Debug-Zeilen wie Debug-Zusammenfassungen von Active Memory an. +- Trace-Zeilen können in `/status` und als nachfolgende Diagnosenachricht nach der normalen Assistant-Antwort erscheinen. -## Sichtbarkeit von Reasoning (`/reasoning`) +## Sichtbarkeit von Reasoning (/reasoning) -- Stufen: `on|off|stream`. +- Level: `on|off|stream`. - Eine Nachricht, die nur aus einer Direktive besteht, schaltet um, ob Thinking-Blöcke in Antworten angezeigt werden. -- Wenn aktiviert, wird Reasoning als **separate Nachricht** gesendet, mit dem Präfix `Reasoning:`. -- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfsblase, während die Antwort erzeugt wird, und sendet dann die endgültige Antwort ohne Reasoning. +- Wenn aktiviert, wird Reasoning als **separate Nachricht** mit dem Präfix `Reasoning:` gesendet. +- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfs-Bubble, während die Antwort erzeugt wird, und sendet dann die finale Antwort ohne Reasoning. - Alias: `/reason`. -- Senden Sie `/reasoning` (oder `/reasoning:`) ohne Argument, um die aktuelle Reasoning-Stufe zu sehen. -- Reihenfolge der Auflösung: Inline-Direktive, dann Sitzungsüberschreibung, dann Standard pro Agent (`agents.list[].reasoningDefault`), dann Fallback (`off`). +- Senden Sie `/reasoning` (oder `/reasoning:`) ohne Argument, um das aktuelle Reasoning-Level anzuzeigen. +- Auflösungsreihenfolge: Inline-Direktive, dann Sitzungsüberschreibung, dann Standardwert pro Agent (`agents.list[].reasoningDefault`), dann Fallback (`off`). ## Verwandt -- Dokumentation zum Elevated-Modus finden Sie unter [Elevated mode](/de/tools/elevated). +- Die Dokumentation zum Elevated mode finden Sie unter [Elevated mode](/de/tools/elevated). ## Heartbeats -- Der Body des Heartbeat-Probes ist der konfigurierte Heartbeat-Prompt (Standard: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline-Direktiven in einer Heartbeat-Nachricht gelten wie üblich (vermeiden Sie jedoch, Sitzungsstandards über Heartbeats zu ändern). -- Die Zustellung von Heartbeat verwendet standardmäßig nur die endgültige Payload. Um auch die separate Nachricht `Reasoning:` zu senden (falls verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder pro Agent `agents.list[].heartbeat.includeReasoning: true`. +- Der Heartbeat-Probe-Body ist der konfigurierte Heartbeat-Prompt (Standard: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline-Direktiven in einer Heartbeat-Nachricht gelten wie üblich (vermeiden Sie aber, Sitzungsstandardwerte über Heartbeats zu ändern). +- Die Heartbeat-Zustellung verwendet standardmäßig nur die finale Payload. Um zusätzlich die separate `Reasoning:`-Nachricht zu senden (falls verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder pro Agent `agents.list[].heartbeat.includeReasoning: true`. -## Webchat-UI +## Web-Chat-UI -- Der Thinking-Selektor im Webchat spiegelt beim Laden der Seite die gespeicherte Stufe der Sitzung aus dem eingehenden Sitzungsspeicher bzw. der Konfiguration wider. -- Die Auswahl einer anderen Stufe schreibt die Sitzungsüberschreibung sofort über `sessions.patch`; sie wartet nicht auf das nächste Senden und ist keine einmalige Überschreibung `thinkingOnce`. -- Die erste Option ist immer `Default ()`, wobei der aufgelöste Standard vom aktiven Sitzungsmodell kommt: `adaptive` für Claude 4.6 auf Anthropic, `off` für Anthropic Claude Opus 4.7, sofern nicht konfiguriert, `low` für andere Reasoning-fähige Modelle, sonst `off`. -- Der Picker bleibt Provider-sensitiv: - - die meisten Provider zeigen `off | minimal | low | medium | high` - - Anthropic/Bedrock Claude 4.6 zeigt `off | minimal | low | medium | high | adaptive` - - Anthropic Claude Opus 4.7 zeigt `off | minimal | low | medium | high | xhigh | adaptive | max` - - Z.AI zeigt binär `off | on` -- `/think:` funktioniert weiterhin und aktualisiert dieselbe gespeicherte Sitzungsstufe, sodass Chat-Direktiven und der Picker synchron bleiben. +- Der Thinking-Selektor im Web-Chat spiegelt beim Laden der Seite das gespeicherte Level der Sitzung aus dem eingehenden Sitzungs-Store bzw. der Konfiguration wider. +- Die Auswahl eines anderen Levels schreibt die Sitzungsüberschreibung sofort über `sessions.patch`; sie wartet nicht auf das nächste Senden und ist keine einmalige `thinkingOnce`-Überschreibung. +- Die erste Option ist immer `Default ()`, wobei der aufgelöste Standardwert aus dem Thinking-Profil des Providers des aktiven Sitzungsmodells stammt. +- Der Picker verwendet `thinkingOptions`, die von der Gateway-Sitzungszeile zurückgegeben werden. Die Browser-UI verwaltet keine eigene Regex-Liste für Provider; Plugins besitzen die modellspezifischen Level-Sätze. +- `/think:` funktioniert weiterhin und aktualisiert dasselbe gespeicherte Sitzungslevel, sodass Chat-Direktiven und der Picker synchron bleiben. + +## Provider-Profile + +- Provider-Plugins können `resolveThinkingProfile(ctx)` bereitstellen, um die unterstützten Level und den Standardwert des Modells zu definieren. +- Jedes Profil-Level hat eine gespeicherte kanonische `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` oder `max`) und kann ein Anzeige-`label` enthalten. Binäre Provider verwenden `{ id: "low", label: "on" }`. +- Veröffentliche Legacy-Hooks (`supportsXHighThinking`, `isBinaryThinking` und `resolveDefaultThinkingLevel`) bleiben als Kompatibilitätsadapter erhalten, aber neue benutzerdefinierte Level-Sätze sollten `resolveThinkingProfile` verwenden. +- Gateway-Zeilen stellen `thinkingOptions` und `thinkingDefault` bereit, sodass ACP/Chat-Clients dasselbe Profil rendern, das auch von der Laufzeitvalidierung verwendet wird.