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

chore(i18n): refresh de translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 01:52:08 +00:00
parent 3cf3b351cb
commit c7aca71a8a
37 changed files with 5043 additions and 4472 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
docs/de/automation/tasks.md
View File

@ -1,48 +1,48 @@
---
read_when:
- Laufende oder kürzlich abgeschlossene Hintergrundarbeiten prüfen
- Debugging von Zustellungsfehlern für abgekoppelte Agent-Ausführungen
- Verstehen, wie Hintergrundläufe mit Sitzungen, Cron und Heartbeat zusammenhängen
- Fehlerbehebung bei Zustellungsfehlern für losgelöste Agentenläufe
- Verstehen, wie Hintergrundausführungen mit Sitzungen, Cron und Heartbeat zusammenhängen
sidebarTitle: Background tasks
summary: Nachverfolgung von Hintergrundaufgaben für ACP-Ausführungen, Unteragenten, isolierte Cron-Jobs und CLI-Vorgänge
summary: Nachverfolgung von Hintergrundaufgaben für ACP-Ausführungen, Subagenten, isolierte Cron-Jobs und CLI-Vorgänge
title: Hintergrundaufgaben
x-i18n:
generated_at: "2026-05-01T06:41:00Z"
generated_at: "2026-05-05T01:44:24Z"
model: gpt-5.5
provider: openai
source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991
source_path: automation/tasks.md
workflow: 16
---
<Note>
Suchen Sie nach Planung? Siehe [Automatisierung und Aufgaben](/de/automation), um den richtigen Mechanismus auszuwählen. Diese Seite ist das Aktivitätsprotokoll für Hintergrundarbeit, nicht der Planer.
Suchen Sie nach Planung? Unter [Automatisierung und Aufgaben](/de/automation) finden Sie Hilfe bei der Wahl des richtigen Mechanismus. Diese Seite ist das Aktivitätsprotokoll für Hintergrundarbeit, nicht der Scheduler.
</Note>
Hintergrundaufgaben verfolgen Arbeit, die **außerhalb Ihrer Hauptunterhaltungssitzung** läuft: ACP-Ausführungen, Subagent-Starts, isolierte Cron-Job-Ausführungen und über die CLI gestartete Vorgänge.
Hintergrundaufgaben verfolgen Arbeit, die **außerhalb Ihrer Haupt-Konversationssitzung** ausgeführt wird: ACP-Ausführungen, Subagent-Starts, isolierte Cron-Job-Ausführungen und über die CLI gestartete Vorgänge.
Tasks ersetzen **keine** Sitzungen, Cron-Jobs oder Heartbeats – sie sind das **Aktivitätsprotokoll**, das aufzeichnet, welche entkoppelte Arbeit stattgefunden hat, wann sie ausgeführt wurde und ob sie erfolgreich war.
Aufgaben ersetzen **nicht** Sitzungen, Cron-Jobs oder Heartbeats — sie sind das **Aktivitätsprotokoll**, das erfasst, welche losgelöste Arbeit wann stattgefunden hat und ob sie erfolgreich war.
<Note>
Nicht jeder Agent-Lauf erstellt eine Task. Heartbeat-Turns und normaler interaktiver Chat tun dies nicht. Alle Cron-Ausführungen, ACP-Starts, Subagent-Starts und CLI-Agent-Befehle tun dies.
Nicht jeder Agent-Lauf erstellt eine Aufgabe. Heartbeat-Turns und normaler interaktiver Chat tun dies nicht. Alle Cron-Ausführungen, ACP-Starts, Subagent-Starts und CLI-Agent-Befehle tun dies.
</Note>
## Kurzfassung
- Tasks sind **Datensätze**, keine Planer – Cron und Heartbeat entscheiden, _wann_ Arbeit läuft, Tasks verfolgen, _was passiert ist_.
- ACP, Subagents, alle Cron-Jobs und CLI-Vorgänge erstellen Tasks. Heartbeat-Turns tun dies nicht.
- Jede Task durchläuft `queued → running → terminal` (succeeded, failed, timed_out, cancelled oder lost).
- Cron-Tasks bleiben aktiv, solange die Cron-Laufzeit den Job noch besitzt; wenn der
In-Memory-Laufzeitstatus weg ist, prüft die Task-Wartung zuerst den dauerhaften Cron-
Ausführungsverlauf, bevor sie eine Task als verloren markiert.
- Abschluss ist push-gesteuert: Entkoppelte Arbeit kann direkt benachrichtigen oder die
anfordernde Sitzung/den Heartbeat wecken, wenn sie fertig ist. Status-Polling-Schleifen
sind daher normalerweise die falsche Form.
- Isolierte Cron-Läufe und Subagent-Abschlüsse bereinigen nach bestem Aufwand nachverfolgte Browser-Tabs/Prozesse für ihre Kind-Sitzung, bevor die abschließende Bereinigungsbuchhaltung erfolgt.
- Isolierte Cron-Zustellung unterdrückt veraltete vorläufige Parent-Antworten, während nachgelagerte Subagent-Arbeit noch ausläuft, und bevorzugt die endgültige Ausgabe nachgelagerter Tasks, wenn diese vor der Zustellung eintrifft.
- Abschlussbenachrichtigungen werden direkt an einen Kanal zugestellt oder für den nächsten Heartbeat eingereiht.
- `openclaw tasks list` zeigt alle Tasks; `openclaw tasks audit` macht Probleme sichtbar.
- Terminale Datensätze werden 7 Tage lang aufbewahrt und dann automatisch bereinigt.
- Aufgaben sind **Datensätze**, keine Scheduler — Cron und Heartbeat entscheiden, _wann_ Arbeit ausgeführt wird, Aufgaben verfolgen, _was passiert ist_.
- ACP, Subagents, alle Cron-Jobs und CLI-Vorgänge erstellen Aufgaben. Heartbeat-Turns tun dies nicht.
- Jede Aufgabe durchläuft `queued → running → terminal` (succeeded, failed, timed_out, cancelled oder lost).
- Cron-Aufgaben bleiben aktiv, solange die Cron-Runtime den Job noch besitzt; wenn der
In-Memory-Runtime-Zustand verschwunden ist, prüft die Aufgabenwartung zuerst den dauerhaften Cron-
Ausführungsverlauf, bevor eine Aufgabe als lost markiert wird.
- Abschluss ist pushgesteuert: Losgelöste Arbeit kann direkt benachrichtigen oder die
anfragende Sitzung/den Heartbeat wecken, wenn sie beendet ist, sodass Status-Polling-Schleifen
in der Regel die falsche Form sind.
- Isolierte Cron-Läufe und Subagent-Abschlüsse bereinigen nach bestem Aufwand verfolgte Browser-Tabs/Prozesse für ihre Child-Session vor der abschließenden Bereinigungsbuchführung.
- Die Auslieferung isolierter Cron-Läufe unterdrückt veraltete vorläufige Parent-Antworten, während nachgelagerte Subagent-Arbeit noch abgearbeitet wird, und bevorzugt die endgültige Ausgabe der Nachfahren, wenn diese vor der Auslieferung eintrifft.
- Abschlussbenachrichtigungen werden direkt an einen Kanal ausgeliefert oder für den nächsten Heartbeat in die Warteschlange gestellt.
- `openclaw tasks list` zeigt alle Aufgaben; `openclaw tasks audit` macht Probleme sichtbar.
- Terminal-Datensätze werden 7 Tage aufbewahrt und dann automatisch bereinigt.
## Schnellstart
@ -95,35 +95,35 @@ Nicht jeder Agent-Lauf erstellt eine Task. Heartbeat-Turns und normaler interakt
</Tab>
</Tabs>
## Was eine Task erstellt
## Was eine Aufgabe erstellt
| Quelle | Laufzeittyp | Wann ein Task-Datensatz erstellt wird | Standard-Benachrichtigungsrichtlinie |
| ---------------------- | ------------ | ------------------------------------------------------ | ------------------------------------ |
| ACP-Hintergrundläufe | `acp` | Starten einer ACP-Kind-Sitzung | `done_only` |
| Subagent-Orchestrierung | `subagent` | Starten eines Subagents über `sessions_spawn` | `done_only` |
| Cron-Jobs (alle Typen) | `cron` | Jede Cron-Ausführung (Hauptsitzung und isoliert) | `silent` |
| CLI-Vorgänge | `cli` | `openclaw agent`-Befehle, die über den Gateway laufen | `silent` |
| Agent-Medienjobs | `cli` | Sitzungsbasierte `music_generate`/`video_generate`-Läufe | `silent` |
| Quelle | Runtime-Typ | Wann ein Aufgabendatensatz erstellt wird | Standard-Benachrichtigungsrichtlinie |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| ACP-Hintergrundläufe | `acp` | Beim Starten einer Child-ACP-Sitzung | `done_only` |
| Subagent-Orchestrierung | `subagent` | Beim Starten eines Subagents über `sessions_spawn` | `done_only` |
| Cron-Jobs (alle Typen) | `cron` | Bei jeder Cron-Ausführung (Hauptsitzung und isoliert) | `silent` |
| CLI-Vorgänge | `cli` | `openclaw agent`-Befehle, die über den Gateway laufen | `silent` |
| Agent-Medienjobs | `cli` | Sitzungsbasierte `music_generate`-/`video_generate`-Läufe | `silent` |
<AccordionGroup>
<Accordion title="Notify defaults for cron and media">
Cron-Tasks der Hauptsitzung verwenden standardmäßig die Benachrichtigungsrichtlinie `silent` – sie erstellen Datensätze zur Nachverfolgung, erzeugen aber keine Benachrichtigungen. Isolierte Cron-Tasks verwenden ebenfalls standardmäßig `silent`, sind aber sichtbarer, weil sie in ihrer eigenen Sitzung laufen.
Cron-Aufgaben der Hauptsitzung verwenden standardmäßig die Benachrichtigungsrichtlinie `silent` — sie erstellen Datensätze zur Nachverfolgung, erzeugen aber keine Benachrichtigungen. Isolierte Cron-Aufgaben verwenden ebenfalls standardmäßig `silent`, sind aber sichtbarer, da sie in ihrer eigenen Sitzung laufen.
Sitzungsbasierte `music_generate`- und `video_generate`-Läufe verwenden ebenfalls die Benachrichtigungsrichtlinie `silent`. Sie erstellen weiterhin Task-Datensätze, aber der Abschluss wird als internes Wake an die ursprüngliche Agent-Sitzung zurückgegeben, damit der Agent die Follow-up-Nachricht schreiben und die fertigen Medien selbst anhängen kann. Wenn Sie `tools.media.asyncCompletion.directSend` aktivieren, können asynchrone `video_generate`-Abschlüsse zuerst eine direkte Kanalzustellung versuchen; asynchrone `music_generate`-Abschlüsse bleiben auf dem Wake-Pfad der anfordernden Sitzung.
Sitzungsbasierte `music_generate`- und `video_generate`-Läufe verwenden ebenfalls die Benachrichtigungsrichtlinie `silent`. Sie erstellen weiterhin Aufgabendatensätze, aber der Abschluss wird als internes Wake an die ursprüngliche Agent-Sitzung zurückgegeben, damit der Agent die Folgenachricht schreiben und das fertige Medium selbst anhängen kann. Abschlüsse in Gruppen/Kanälen folgen der normalen Richtlinie für sichtbare Antworten, sodass der Agent das Nachrichtenwerkzeug verwendet, wenn die Quellzustellung dies erfordert.
</Accordion>
<Accordion title="Concurrent video_generate guardrail">
Während eine sitzungsbasierte `video_generate`-Task noch aktiv ist, wirkt das Tool auch als Schutzmechanismus: Wiederholte `video_generate`-Aufrufe in derselben Sitzung geben den Status der aktiven Task zurück, statt eine zweite parallele Generierung zu starten. Verwenden Sie `action: "status"`, wenn Sie von Agent-Seite aus eine explizite Fortschritts-/Statusabfrage wünschen.
Während eine sitzungsbasierte `video_generate`-Aufgabe noch aktiv ist, dient das Werkzeug auch als Leitplanke: Wiederholte `video_generate`-Aufrufe in derselben Sitzung geben den aktiven Aufgabenstatus zurück, anstatt eine zweite parallele Generierung zu starten. Verwenden Sie `action: "status"`, wenn Sie eine explizite Fortschritts-/Statusabfrage von der Agent-Seite wünschen.
</Accordion>
<Accordion title="What does not create tasks">
- Heartbeat-Turns – Hauptsitzung; siehe [Heartbeat](/de/gateway/heartbeat)
- Heartbeat-Turns — Hauptsitzung; siehe [Heartbeat](/de/gateway/heartbeat)
- Normale interaktive Chat-Turns
- Direkte `/command`-Antworten
</Accordion>
</AccordionGroup>
## Task-Lebenszyklus
## Aufgabenlebenszyklus
```mermaid
stateDiagram-v2
@ -137,58 +137,58 @@ stateDiagram-v2
running --> lost : session gone > 5 min
```
| Status | Bedeutung |
| Status | Bedeutung |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Erstellt, wartet darauf, dass der Agent startet |
| `queued` | Erstellt, wartet auf den Start des Agents |
| `running` | Agent-Turn wird aktiv ausgeführt |
| `succeeded` | Erfolgreich abgeschlossen |
| `failed` | Mit einem Fehler abgeschlossen |
| `timed_out` | Konfiguriertes Timeout überschritten |
| `cancelled` | Vom Operator über `openclaw tasks cancel` gestoppt |
| `lost` | Die Laufzeit hat nach einer 5-minütigen Kulanzfrist den autoritativen Stützzustand verloren |
| `succeeded` | Erfolgreich abgeschlossen |
| `failed` | Mit einem Fehler abgeschlossen |
| `timed_out` | Konfiguriertes Timeout überschritten |
| `cancelled` | Durch den Operator über `openclaw tasks cancel` gestoppt |
| `lost` | Die Runtime hat den autoritativen unterstützenden Zustand nach einer 5-minütigen Kulanzfrist verloren |
Übergänge passieren automatisch – wenn der zugehörige Agent-Lauf endet, wird der Task-Status entsprechend aktualisiert.
Übergänge erfolgen automatisch — wenn der zugehörige Agent-Lauf endet, wird der Aufgabenstatus entsprechend aktualisiert.
Der Abschluss eines Agent-Laufs ist für aktive Task-Datensätze maßgeblich. Ein erfolgreicher entkoppelter Lauf wird als `succeeded` finalisiert, gewöhnliche Laufzeitfehler als `failed`, und Timeout- oder Abbruchergebnisse als `timed_out`. Wenn ein Operator die Task bereits abgebrochen hat oder die Laufzeit bereits einen stärkeren terminalen Status wie `failed`, `timed_out` oder `lost` aufgezeichnet hat, stuft ein späteres Erfolgssignal diesen terminalen Status nicht herab.
Der Abschluss des Agent-Laufs ist für aktive Aufgabendatensätze autoritativ. Ein erfolgreicher losgelöster Lauf wird als `succeeded` finalisiert, gewöhnliche Laufzeitfehler als `failed` und Timeout- oder Abbruchergebnisse als `timed_out`. Wenn ein Operator die Aufgabe bereits abgebrochen hat oder die Runtime bereits einen stärkeren Terminal-Zustand wie `failed`, `timed_out` oder `lost` erfasst hat, stuft ein späteres Erfolgssignal diesen Terminal-Status nicht herunter.
`lost` ist laufzeitbewusst:
`lost` ist runtimebewusst:
- ACP-Tasks: Die Metadaten der stützenden ACP-Kind-Sitzung sind verschwunden.
- Subagent-Tasks: Die stützende Kind-Sitzung ist aus dem Ziel-Agent-Speicher verschwunden.
- Cron-Tasks: Die Cron-Laufzeit verfolgt den Job nicht mehr als aktiv und der dauerhafte
Cron-Ausführungsverlauf zeigt kein terminales Ergebnis für diesen Lauf. Ein Offline-CLI-
Audit behandelt seinen eigenen leeren In-Process-Cron-Laufzeitstatus nicht als Autorität.
- CLI-Tasks: Isolierte Kind-Sitzungs-Tasks verwenden die Kind-Sitzung; chat-gestützte
CLI-Tasks verwenden stattdessen den Live-Laufkontext, sodass verbleibende
- ACP-Aufgaben: Unterstützende ACP-Child-Session-Metadaten sind verschwunden.
- Subagent-Aufgaben: Unterstützende Child-Session ist aus dem Ziel-Agent-Speicher verschwunden.
- Cron-Aufgaben: Die Cron-Runtime verfolgt den Job nicht mehr als aktiv und der dauerhafte
Cron-Ausführungsverlauf zeigt kein Terminal-Ergebnis für diesen Lauf. Ein Offline-CLI-
Audit behandelt seinen eigenen leeren In-Process-Cron-Runtime-Zustand nicht als Autorität.
- CLI-Aufgaben: Isolierte Child-Session-Aufgaben verwenden die Child-Session; chatbasierte
CLI-Aufgaben verwenden stattdessen den Live-Ausführungskontext, sodass verbleibende
Kanal-/Gruppen-/Direktsitzungszeilen sie nicht aktiv halten. Gateway-gestützte
`openclaw agent`-Läufe werden ebenfalls aus ihrem Laufergebnis finalisiert, sodass abgeschlossene Läufe
`openclaw agent`-Läufe werden ebenfalls anhand ihres Laufergebnisses finalisiert, sodass abgeschlossene Läufe
nicht aktiv bleiben, bis der Sweeper sie als `lost` markiert.
## Zustellung und Benachrichtigungen
## Auslieferung und Benachrichtigungen
Wenn eine Task einen terminalen Status erreicht, benachrichtigt OpenClaw Sie. Es gibt zwei Zustellpfade:
Wenn eine Aufgabe einen Terminal-Zustand erreicht, benachrichtigt OpenClaw Sie. Es gibt zwei Auslieferungspfade:
**Direkte Zustellung** – wenn die Task ein Kanalziel hat (`requesterOrigin`), geht die Abschlussnachricht direkt an diesen Kanal (Telegram, Discord, Slack usw.). Bei Subagent-Abschlüssen bewahrt OpenClaw außerdem gebundenes Thread-/Topic-Routing, wenn verfügbar, und kann ein fehlendes `to` / Konto aus der gespeicherten Route der anfordernden Sitzung (`lastChannel` / `lastTo` / `lastAccountId`) ergänzen, bevor die direkte Zustellung aufgegeben wird.
**Direkte Auslieferung** — wenn die Aufgabe ein Kanalziel hat (den `requesterOrigin`), geht die Abschlussnachricht direkt an diesen Kanal (Telegram, Discord, Slack usw.). Für Subagent-Abschlüsse bewahrt OpenClaw außerdem gebundene Thread-/Topic-Routen, wenn verfügbar, und kann ein fehlendes `to` / Konto aus der gespeicherten Route der anfragenden Sitzung (`lastChannel` / `lastTo` / `lastAccountId`) ergänzen, bevor die direkte Auslieferung aufgegeben wird.
**Sitzungs-eingereihte Zustellung** – wenn die direkte Zustellung fehlschlägt oder kein Ursprung festgelegt ist, wird die Aktualisierung als Systemereignis in der Sitzung des Anforderers eingereiht und beim nächsten Heartbeat sichtbar.
**Sitzungswarteschlangen-Auslieferung** — wenn die direkte Auslieferung fehlschlägt oder kein Ursprung gesetzt ist, wird die Aktualisierung als Systemereignis in die Sitzung der anfragenden Person eingereiht und beim nächsten Heartbeat sichtbar.
<Tip>
Der Task-Abschluss löst ein sofortiges Heartbeat-Wake aus, sodass Sie das Ergebnis schnell sehen – Sie müssen nicht auf den nächsten geplanten Heartbeat-Tick warten.
Der Aufgabenabschluss löst ein sofortiges Heartbeat-Wake aus, sodass Sie das Ergebnis schnell sehen — Sie müssen nicht auf den nächsten geplanten Heartbeat-Tick warten.
</Tip>
Das bedeutet, dass der übliche Workflow push-basiert ist: Starten Sie entkoppelte Arbeit einmal und lassen Sie dann die Laufzeit Sie beim Abschluss wecken oder benachrichtigen. Fragen Sie den Task-Status nur ab, wenn Sie Debugging, Eingriff oder ein explizites Audit benötigen.
Das bedeutet, dass der übliche Workflow pushbasiert ist: Starten Sie losgelöste Arbeit einmal und lassen Sie die Runtime Sie beim Abschluss wecken oder benachrichtigen. Fragen Sie den Aufgabenstatus nur ab, wenn Sie Debugging, Eingriffe oder ein explizites Audit benötigen.
### Benachrichtigungsrichtlinien
Steuern Sie, wie viel Sie über jede Task hören:
Steuern Sie, wie viel Sie zu jeder Aufgabe hören:
| Richtlinie | Was zugestellt wird |
| Richtlinie | Was ausgeliefert wird |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (Standard) | Nur terminaler Status (succeeded, failed usw.) – **dies ist der Standard** |
| `state_changes` | Jeder Statusübergang und jede Fortschrittsaktualisierung |
| `silent` | Gar nichts |
| `done_only` (Standard) | Nur Terminal-Zustand (succeeded, failed usw.) — **dies ist der Standard** |
| `state_changes` | Jeder Zustandsübergang und jede Fortschrittsaktualisierung |
| `silent` | Gar nichts |
Ändern Sie die Richtlinie, während eine Task läuft:
Ändern Sie die Richtlinie, während eine Aufgabe läuft:
```bash
openclaw tasks notify <lookup> state_changes
@ -202,7 +202,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
Ausgabespalten: Task-ID, Art, Status, Zustellung, Lauf-ID, Kind-Sitzung, Zusammenfassung.
Ausgabespalten: Aufgaben-ID, Art, Status, Auslieferung, Lauf-ID, Child-Session, Zusammenfassung.
</Accordion>
<Accordion title="tasks show">
@ -210,7 +210,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
Das Such-Token akzeptiert eine Task-ID, Lauf-ID oder einen Sitzungsschlüssel. Zeigt den vollständigen Datensatz einschließlich Timing, Zustellstatus, Fehler und terminaler Zusammenfassung.
Das Lookup-Token akzeptiert eine Aufgaben-ID, Lauf-ID oder einen Sitzungsschlüssel. Zeigt den vollständigen Datensatz einschließlich Timing, Auslieferungszustand, Fehler und Terminal-Zusammenfassung.
</Accordion>
<Accordion title="tasks cancel">
@ -218,7 +218,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
Bei ACP- und Subagent-Tasks beendet dies die Kind-Sitzung. Bei CLI-verfolgten Tasks wird der Abbruch im Task-Registry aufgezeichnet (es gibt kein separates Handle der Kind-Laufzeit). Der Status wechselt zu `cancelled` und eine Zustellbenachrichtigung wird gesendet, sofern zutreffend.
Bei ACP- und Subagent-Aufgaben beendet dies die Child-Session. Bei CLI-verfolgten Aufgaben wird der Abbruch in der Aufgabenregistrierung erfasst (es gibt keinen separaten Child-Runtime-Handle). Der Status wechselt zu `cancelled`, und eine Auslieferungsbenachrichtigung wird gesendet, sofern zutreffend.
</Accordion>
<Accordion title="tasks notify">
@ -233,14 +233,14 @@ openclaw tasks notify <lookup> state_changes
Macht betriebliche Probleme sichtbar. Befunde erscheinen auch in `openclaw status`, wenn Probleme erkannt werden.
| Befund | Schweregrad | Auslöser |
| ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `stale_queued` | warn | Seit mehr als 10 Minuten in der Warteschlange |
| `stale_running` | error | Seit mehr als 30 Minuten laufend |
| `lost` | warn/error | Runtime-gestützte Aufgabenverantwortung ist verschwunden; beibehaltene verlorene Aufgaben warnen bis `cleanupAfter` und werden dann zu Fehlern |
| `delivery_failed` | warn | Zustellung fehlgeschlagen und Benachrichtigungsrichtlinie ist nicht `silent` |
| `missing_cleanup` | warn | Terminale Aufgabe ohne Cleanup-Zeitstempel |
| `inconsistent_timestamps` | warn | Timeline-Verstoß (zum Beispiel beendet, bevor gestartet) |
| Ergebnis | Schweregrad | Auslöser |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| `stale_queued` | Warnung | Seit mehr als 10 Minuten eingereiht |
| `stale_running` | Fehler | Seit mehr als 30 Minuten laufend |
| `lost` | Warnung/Fehler | Die durch die Laufzeitumgebung gestützte Aufgabeninhaberschaft ist verschwunden; beibehaltene verlorene Aufgaben werden bis `cleanupAfter` als Warnungen gemeldet und danach zu Fehlern |
| `delivery_failed` | Warnung | Zustellung fehlgeschlagen und Benachrichtigungsrichtlinie ist nicht `silent` |
| `missing_cleanup` | Warnung | Beendete Aufgabe ohne Bereinigungszeitstempel |
| `inconsistent_timestamps` | Warnung | Zeitachsenverstoß (zum Beispiel beendet, bevor gestartet) |
</Accordion>
<Accordion title="tasks maintenance">
@ -249,22 +249,22 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks maintenance --apply [--json]
```
Verwenden Sie dies, um Abgleich, Cleanup-Stempelung und Bereinigung für Aufgaben und Task-Flow-Zustand in der Vorschau anzuzeigen oder anzuwenden.
Verwenden Sie dies, um Abgleich, Bereinigungsstempelung und Pruning für Aufgaben und Task-Flow-Zustand in der Vorschau anzuzeigen oder anzuwenden.
Der Abgleich ist runtime-bewusst:
Der Abgleich berücksichtigt die Laufzeitumgebung:
- ACP-/Subagent-Aufgaben prüfen ihre zugrunde liegende untergeordnete Sitzung.
- Subagent-Aufgaben, deren untergeordnete Sitzung einen Tombstone für Neustart-Wiederherstellung hat, werden als verloren markiert, anstatt als wiederherstellbare zugrunde liegende Sitzungen behandelt zu werden.
- Cron-Aufgaben prüfen, ob die Cron-Runtime den Job noch besitzt, und stellen dann den terminalen Status aus persistierten Cron-Ausführungsprotokollen/Job-Zustand wieder her, bevor sie auf `lost` zurückfallen. Nur der Gateway-Prozess ist autoritativ für die aktive In-Memory-Job-Menge von Cron; ein Offline-CLI-Audit verwendet dauerhafte Historie, markiert eine Cron-Aufgabe aber nicht allein deshalb als verloren, weil dieses lokale Set leer ist.
- Subagent-Aufgaben, deren untergeordnete Sitzung einen Tombstone für die Neustartwiederherstellung hat, werden als verloren markiert, statt als wiederherstellbare zugrunde liegende Sitzungen behandelt zu werden.
- Cron-Aufgaben prüfen, ob die Cron-Laufzeitumgebung den Job noch besitzt, und stellen dann den beendeten Status aus persistierten Cron-Ausführungsprotokollen/dem Job-Zustand wieder her, bevor sie auf `lost` zurückfallen. Nur der Gateway-Prozess ist für die speicherinterne Menge aktiver Cron-Jobs autoritativ; der Offline-CLI-Audit verwendet dauerhafte Historie, markiert eine Cron-Aufgabe aber nicht allein deshalb als verloren, weil dieses lokale Set leer ist.
- Chat-gestützte CLI-Aufgaben prüfen den besitzenden Live-Ausführungskontext, nicht nur die Chat-Sitzungszeile.
Completion-Cleanup ist ebenfalls runtime-bewusst:
Die Bereinigung nach Abschluss berücksichtigt ebenfalls die Laufzeitumgebung:
- Subagent-Completion schließt nach bestem Aufwand verfolgte Browser-Tabs/Prozesse für die untergeordnete Sitzung, bevor das Ankündigungs-Cleanup fortfährt.
- Completion isolierter Cron-Ausführungen schließt nach bestem Aufwand verfolgte Browser-Tabs/Prozesse für die Cron-Sitzung, bevor die Ausführung vollständig abgebaut wird.
- Die Zustellung isolierter Cron-Ausführungen wartet bei Bedarf auf nachgelagerte Subagent-Folgearbeiten und unterdrückt veralteten Bestätigungstext des übergeordneten Elements, anstatt ihn anzukündigen.
- Die Zustellung von Subagent-Completion bevorzugt den neuesten sichtbaren Assistant-Text; wenn dieser leer ist, fällt sie auf bereinigten neuesten Tool-/toolResult-Text zurück, und reine Timeout-Tool-Call-Ausführungen können zu einer kurzen Teilfortschrittszusammenfassung verdichtet werden. Terminal fehlgeschlagene Ausführungen melden den Fehlerstatus, ohne erfassten Antworttext erneut wiederzugeben.
- Cleanup-Fehler verdecken nicht das tatsächliche Aufgabenergebnis.
- Beim Subagent-Abschluss werden nach bestem Aufwand nachverfolgte Browser-Tabs/-Prozesse für die untergeordnete Sitzung geschlossen, bevor die Ankündigungsbereinigung fortgesetzt wird.
- Beim isolierten Cron-Abschluss werden nach bestem Aufwand nachverfolgte Browser-Tabs/-Prozesse für die Cron-Sitzung geschlossen, bevor die Ausführung vollständig beendet wird.
- Die isolierte Cron-Zustellung wartet bei Bedarf auf Nachläufe nachgeordneter Subagents und unterdrückt veralteten Bestätigungstext des übergeordneten Elements, statt ihn anzukündigen.
- Die Zustellung des Subagent-Abschlusses bevorzugt den neuesten sichtbaren Assistententext; wenn dieser leer ist, fällt sie auf bereinigten neuesten tool/toolResult-Text zurück, und reine Timeout-Tool-Call-Ausführungen können zu einer kurzen Teilfortschrittszusammenfassung zusammengefasst werden. Beendete fehlgeschlagene Ausführungen kündigen den Fehlerstatus an, ohne erfassten Antworttext erneut wiederzugeben.
- Bereinigungsfehler verdecken nicht das tatsächliche Aufgabenergebnis.
</Accordion>
<Accordion title="tasks flow list | show | cancel">
@ -274,20 +274,20 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks flow cancel <lookup>
```
Verwenden Sie diese Befehle, wenn der orchestrierende Task Flow für Sie relevant ist und nicht ein einzelner Hintergrundaufgabeneintrag.
Verwenden Sie diese Befehle, wenn der orchestrierende Task Flow für Sie relevant ist und nicht ein einzelner Hintergrundaufgabendatensatz.
</Accordion>
</AccordionGroup>
## Chat-Aufgabenboard (`/tasks`)
## Chat-Aufgabenübersicht (`/tasks`)
Verwenden Sie `/tasks` in jeder Chat-Sitzung, um mit dieser Sitzung verknüpfte Hintergrundaufgaben anzuzeigen. Das Board zeigt aktive und kürzlich abgeschlossene Aufgaben mit Runtime, Status, Zeitangaben sowie Fortschritts- oder Fehlerdetails.
Verwenden Sie `/tasks` in jeder Chat-Sitzung, um Hintergrundaufgaben zu sehen, die mit dieser Sitzung verknüpft sind. Die Übersicht zeigt aktive und kürzlich abgeschlossene Aufgaben mit Laufzeitumgebung, Status, Timing sowie Fortschritts- oder Fehlerdetails.
Wenn die aktuelle Sitzung keine sichtbaren verknüpften Aufgaben hat, fällt `/tasks` auf agent-lokale Aufgabenzahlen zurück, sodass Sie weiterhin eine Übersicht erhalten, ohne Details anderer Sitzungen offenzulegen.
Wenn die aktuelle Sitzung keine sichtbaren verknüpften Aufgaben hat, fällt `/tasks` auf agentenlokale Aufgabenzählungen zurück, sodass Sie weiterhin einen Überblick erhalten, ohne Details anderer Sitzungen offenzulegen.
Für das vollständige Betreiber-Ledger verwenden Sie die CLI: `openclaw tasks list`.
Für das vollständige Operator-Protokoll verwenden Sie die CLI: `openclaw tasks list`.
## Statusintegration (Aufgabendruck)
## Statusintegration (Aufgabenbelastung)
`openclaw status` enthält eine Aufgabenübersicht auf einen Blick:
@ -297,81 +297,81 @@ Tasks: 3 queued · 2 running · 1 issues
Die Zusammenfassung meldet:
- **aktiv** — Anzahl von `queued` + `running`
- **Fehler** — Anzahl von `failed` + `timed_out` + `lost`
- **active** — Anzahl von `queued` + `running`
- **failures** — Anzahl von `failed` + `timed_out` + `lost`
- **byRuntime** — Aufschlüsselung nach `acp`, `subagent`, `cron`, `cli`
Sowohl `/status` als auch das Tool `session_status` verwenden einen cleanup-bewussten Aufgaben-Snapshot: Aktive Aufgaben werden bevorzugt, veraltete abgeschlossene Zeilen werden ausgeblendet, und aktuelle Fehler werden nur angezeigt, wenn keine aktive Arbeit verbleibt. So bleibt die Statuskarte auf das konzentriert, was jetzt relevant ist.
Sowohl `/status` als auch das Tool `session_status` verwenden einen bereinigungsbewussten Aufgaben-Snapshot: aktive Aufgaben werden bevorzugt, veraltete abgeschlossene Zeilen werden ausgeblendet, und aktuelle Fehler werden nur angezeigt, wenn keine aktive Arbeit mehr verbleibt. So bleibt die Statuskarte auf das fokussiert, was im Moment wichtig ist.
## Speicherung und Wartung
### Wo Aufgaben gespeichert werden
### Speicherort der Aufgaben
Aufgabeneinträge werden in SQLite persistiert unter:
Aufgabendatensätze werden in SQLite persistiert unter:
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
Die Registry wird beim Gateway-Start in den Speicher geladen und synchronisiert Schreibvorgänge nach SQLite, um Dauerhaftigkeit über Neustarts hinweg sicherzustellen.
Der Gateway hält das SQLite-Write-Ahead-Log begrenzt, indem er den Standard-Autocheckpoint-Schwellenwert von SQLite sowie periodische und Shutdown-`TRUNCATE`-Checkpoints verwendet.
Die Registry wird beim Start des Gateway in den Speicher geladen und synchronisiert Schreibvorgänge zur Dauerhaftigkeit über Neustarts hinweg nach SQLite.
Der Gateway hält das SQLite-Write-Ahead-Log begrenzt, indem er die standardmäßige Autocheckpoint-Schwelle von SQLite sowie periodische und beim Herunterfahren ausgeführte `TRUNCATE`-Checkpoints verwendet.
### Automatische Wartung
Ein Sweeper läuft alle **60 Sekunden** und behandelt vier Dinge:
Ein Bereinigungsprozess läuft alle **60 Sekunden** und behandelt vier Dinge:
<Steps>
<Step title="Abgleich">
Prüft, ob aktive Aufgaben noch autoritative Runtime-Unterstützung haben. ACP-/Subagent-Aufgaben verwenden den Zustand der untergeordneten Sitzung, Cron-Aufgaben verwenden die aktive Job-Verantwortung, und Chat-gestützte CLI-Aufgaben verwenden den besitzenden Ausführungskontext. Wenn dieser zugrunde liegende Zustand länger als 5 Minuten verschwunden ist, wird die Aufgabe als `lost` markiert.
Prüft, ob aktive Aufgaben noch autoritative Laufzeitunterstützung haben. ACP-/Subagent-Aufgaben verwenden den Zustand der untergeordneten Sitzung, Cron-Aufgaben verwenden die Inhaberschaft aktiver Jobs, und chat-gestützte CLI-Aufgaben verwenden den besitzenden Ausführungskontext. Wenn dieser unterstützende Zustand länger als 5 Minuten verschwunden ist, wird die Aufgabe als `lost` markiert.
</Step>
<Step title="ACP-Sitzungsreparatur">
Schließt terminale oder verwaiste, vom übergeordneten Element besessene einmalige ACP-Sitzungen und schließt veraltete terminale oder verwaiste persistente ACP-Sitzungen nur dann, wenn keine aktive Konversationsbindung verbleibt.
Schließt beendete oder verwaiste, parent-eigene einmalige ACP-Sitzungen und schließt veraltete beendete oder verwaiste persistente ACP-Sitzungen nur dann, wenn keine aktive Konversationsbindung mehr besteht.
</Step>
<Step title="Cleanup-Stempelung">
Setzt einen `cleanupAfter`-Zeitstempel für terminale Aufgaben (endedAt + 7 Tage). Während der Aufbewahrung erscheinen verlorene Aufgaben im Audit weiterhin als Warnungen; nachdem `cleanupAfter` abläuft oder wenn Cleanup-Metadaten fehlen, sind sie Fehler.
<Step title="Bereinigungsstempelung">
Setzt einen `cleanupAfter`-Zeitstempel für beendete Aufgaben (endedAt + 7 Tage). Während der Aufbewahrungsfrist erscheinen verlorene Aufgaben im Audit weiterhin als Warnungen; nachdem `cleanupAfter` abgelaufen ist oder wenn Bereinigungsmetadaten fehlen, sind sie Fehler.
</Step>
<Step title="Bereinigung">
Löscht Einträge nach ihrem `cleanupAfter`-Datum.
<Step title="Pruning">
Löscht Datensätze nach ihrem `cleanupAfter`-Datum.
</Step>
</Steps>
<Note>
**Aufbewahrung:** Terminale Aufgabeneinträge werden **7 Tage** aufbewahrt und dann automatisch bereinigt. Keine Konfiguration erforderlich.
**Aufbewahrung:** beendete Aufgabendatensätze werden **7 Tage** lang aufbewahrt und dann automatisch bereinigt. Keine Konfiguration erforderlich.
</Note>
## Wie Aufgaben mit anderen Systemen zusammenhängen
<AccordionGroup>
<Accordion title="Aufgaben und Task Flow">
[Task Flow](/de/automation/taskflow) ist die Flow-Orchestrierungsebene über Hintergrundaufgaben. Ein einzelner Flow kann über seine Lebensdauer hinweg mehrere Aufgaben koordinieren, indem verwaltete oder gespiegelte Synchronisierungsmodi verwendet werden. Verwenden Sie `openclaw tasks`, um einzelne Aufgabeneinträge zu prüfen, und `openclaw tasks flow`, um den orchestrierenden Flow zu prüfen.
[Task Flow](/de/automation/taskflow) ist die Orchestrierungsschicht für Abläufe oberhalb von Hintergrundaufgaben. Ein einzelner Flow kann über seine Lebensdauer hinweg mehrere Aufgaben mit verwalteten oder gespiegelten Synchronisierungsmodi koordinieren. Verwenden Sie `openclaw tasks`, um einzelne Aufgabendatensätze zu prüfen, und `openclaw tasks flow`, um den orchestrierenden Flow zu prüfen.
Weitere Details finden Sie unter [Task Flow](/de/automation/taskflow).
Details finden Sie unter [Task Flow](/de/automation/taskflow).
</Accordion>
<Accordion title="Aufgaben und Cron">
Eine Cron-Job-**Definition** befindet sich in `~/.openclaw/cron/jobs.json`; der Runtime-Ausführungszustand befindet sich daneben in `~/.openclaw/cron/jobs-state.json`. **Jede** Cron-Ausführung erstellt einen Aufgabeneintrag — sowohl Hauptsitzung als auch isolierte Ausführung. Cron-Aufgaben in Hauptsitzungen verwenden standardmäßig die Benachrichtigungsrichtlinie `silent`, sodass sie nachverfolgt werden, ohne Benachrichtigungen zu erzeugen.
Eine Cron-Job-**Definition** befindet sich in `~/.openclaw/cron/jobs.json`; der Laufzeitausführungszustand liegt daneben in `~/.openclaw/cron/jobs-state.json`. **Jede** Cron-Ausführung erstellt einen Aufgabendatensatz — sowohl in der Hauptsitzung als auch isoliert. Cron-Aufgaben in der Hauptsitzung verwenden standardmäßig die Benachrichtigungsrichtlinie `silent`, sodass sie nachverfolgt werden, ohne Benachrichtigungen zu erzeugen.
Siehe [Cron-Jobs](/de/automation/cron-jobs).
</Accordion>
<Accordion title="Aufgaben und Heartbeat">
Heartbeat-Ausführungen sind Hauptsitzungs-Turns — sie erstellen keine Aufgabeneinträge. Wenn eine Aufgabe abgeschlossen wird, kann sie ein Heartbeat-Aufwecken auslösen, damit Sie das Ergebnis zeitnah sehen.
Heartbeat-Ausführungen sind Hauptsitzungs-Turns — sie erstellen keine Aufgabendatensätze. Wenn eine Aufgabe abgeschlossen wird, kann sie ein Heartbeat-Wecken auslösen, damit Sie das Ergebnis umgehend sehen.
Siehe [Heartbeat](/de/gateway/heartbeat).
</Accordion>
<Accordion title="Aufgaben und Sitzungen">
Eine Aufgabe kann auf einen `childSessionKey` (wo die Arbeit ausgeführt wird) und einen `requesterSessionKey` (wer sie gestartet hat) verweisen. Sitzungen sind Konversationskontext; Aufgaben sind Aktivitätsverfolgung darüber.
Eine Aufgabe kann auf einen `childSessionKey` (wo die Arbeit ausgeführt wird) und einen `requesterSessionKey` (wer sie gestartet hat) verweisen. Sitzungen sind Konversationskontext; Aufgaben sind die Aktivitätsverfolgung darüber.
</Accordion>
<Accordion title="Aufgaben und Agent-Ausführungen">
Die `runId` einer Aufgabe verweist auf die Agent-Ausführung, die die Arbeit erledigt. Agent-Lebenszyklusereignisse (Start, Ende, Fehler) aktualisieren den Aufgabenstatus automatisch — Sie müssen den Lebenszyklus nicht manuell verwalten.
Die `runId` einer Aufgabe verknüpft sie mit der Agent-Ausführung, die die Arbeit erledigt. Agent-Lebenszyklusereignisse (Start, Ende, Fehler) aktualisieren den Aufgabenstatus automatisch — Sie müssen den Lebenszyklus nicht manuell verwalten.
</Accordion>
</AccordionGroup>
## Verwandt
## Verwandte Themen
- [Automatisierung und Aufgaben](/de/automation) — alle Automatisierungsmechanismen auf einen Blick
- [Automatisierung & Aufgaben](/de/automation) — alle Automatisierungsmechanismen auf einen Blick
- [CLI: Aufgaben](/de/cli/tasks) — CLI-Befehlsreferenz
- [Heartbeat](/de/gateway/heartbeat) — periodische Hauptsitzungs-Turns
- [Geplante Aufgaben](/de/automation/cron-jobs) — Hintergrundarbeit planen
- [Task Flow](/de/automation/taskflow) — Flow-Orchestrierung über Aufgaben
- [Task Flow](/de/automation/taskflow) — Flow-Orchestrierung oberhalb von Aufgaben

666
docs/de/channels/slack.md
View File

File diff suppressed because it is too large Load Diff

411
docs/de/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- Sie müssen nachvollziehen, warum ein CI-Job ausgeführt wurde oder nicht
- Sie debuggen eine fehlgeschlagene GitHub Actions-Prüfung
- Sie koordinieren einen Durchlauf oder erneuten Durchlauf der Release-Validierung.
- Sie ändern die ClawSweeper-Auslösung oder die Weiterleitung von GitHub-Aktivitäten
summary: CI-Jobgraph, Bereichs-Gates, Release-Dachworkflows und lokale Befehlsäquivalente
- Sie debuggen einen fehlgeschlagenen GitHub Actions-Check
- Sie koordinieren einen Lauf oder erneuten Lauf der Release-Validierung
- Sie ändern den ClawSweeper-Dispatch oder die Weiterleitung von GitHub-Aktivitäten
summary: CI-Job-Graph, Scope-Gates, Release-Umbrellas und lokale Befehlsäquivalente
title: CI-Pipeline
x-i18n:
generated_at: "2026-05-04T06:41:37Z"
generated_at: "2026-05-05T01:44:26Z"
model: gpt-5.5
provider: openai
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66
source_path: ci.md
workflow: 16
---
OpenClaw CI läuft bei jedem Push nach `main` und jedem Pull Request. Der `preflight`-Job klassifiziert den Diff und deaktiviert teure Lanes, wenn sich nur nicht zusammenhängende Bereiche geändert haben. Manuelle `workflow_dispatch`-Läufe umgehen bewusst das intelligente Scoping und fächern den vollständigen Graphen für Release-Kandidaten und breite Validierung auf. Android-Lanes bleiben über `include_android` Opt-in. Release-spezifische Plugin-Abdeckung befindet sich im separaten Workflow [`Plugin-Vorabrelease`](#plugin-prerelease) und läuft nur über [`Vollständige Release-Validierung`](#full-release-validation) oder einen expliziten manuellen Dispatch.
OpenClaw CI läuft bei jedem Push nach `main` und bei jedem Pull Request. Der Job `preflight` klassifiziert den Diff und schaltet teure Lanes ab, wenn nur nicht zusammenhängende Bereiche geändert wurden. Manuelle `workflow_dispatch`-Läufe umgehen das Smart Scoping absichtlich und fächern für Release-Kandidaten und breite Validierung den vollständigen Graphen auf. Android-Lanes bleiben über `include_android` opt-in. Release-spezifische Plugin-Abdeckung befindet sich im separaten Workflow [`Plugin Prerelease`](#plugin-prerelease) und läuft nur aus [`Full Release Validation`](#full-release-validation) oder einem expliziten manuellen Dispatch.
## Pipeline-Übersicht
## Pipeline-Überblick
| Job | Zweck | Wann er läuft |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Erweiterungen und erstellt das CI-Manifest | Immer bei Nicht-Draft-Pushes und PRs |
| `security-scm-fast` | Erkennung privater Schlüssel und Workflow-Audit über `zizmor` | Immer bei Nicht-Draft-Pushes und PRs |
| `security-dependency-audit` | Produktions-Lockfile-Audit ohne Abhängigkeiten gegen npm-Advisories | Immer bei Nicht-Draft-Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheits-Jobs | Immer bei Nicht-Draft-Pushes und PRs |
| `check-dependencies` | Produktions-Knip-Durchlauf nur für Abhängigkeiten plus Guard für die Allowlist ungenutzter Dateien | Node-relevante Änderungen |
| `build-artifacts` | Erstellt `dist/`, Control UI, Built-Artifact-Prüfungen und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen |
| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie gebündelte/Plugin-Vertrags-/Protokollprüfungen | Node-relevante Änderungen |
| `checks-fast-contracts-channels` | Gesplittete Channel-Vertragsprüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen |
| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, gebündelte, Vertrags- und Erweiterungs-Lanes | Node-relevante Änderungen |
| `check` | Gesplittetes Äquivalent zum lokalen Haupt-Gate: Prod-Typen, Lint, Guards, Testtypen und strikter Smoke | Node-relevante Änderungen |
| `check-additional` | Architektur, gesplitteter Boundary-/Prompt-Drift, Erweiterungs-Guards, Paketgrenze und Gateway Watch | Node-relevante Änderungen |
| `build-smoke` | Built-CLI-Smoke-Tests und Startup-Memory-Smoke | Node-relevante Änderungen |
| `checks` | Verifier für Built-Artifact-Channel-Tests | Node-relevante Änderungen |
| `checks-node-compat-node22` | Node-22-Kompatibilitäts-Build und Smoke-Lane | Manueller CI-Dispatch für Releases |
| `check-docs` | Docs-Formatierung, Lint und Prüfungen auf defekte Links | Docs geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus Regressionen bei gemeinsamen Runtime-Import-Spezifizierern | Windows-relevante Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsamen Built Artifacts | macOS-relevante Änderungen |
| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen |
| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Android-relevante Änderungen |
| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Main-CI-Erfolg oder manueller Dispatch |
| `openclaw-performance` | Tägliche/bedarfsweise Kova-Runtime-Performance-Berichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplanter und manueller Dispatch |
| Job | Zweck | Wann er läuft |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `preflight` | Erkennt reine Docs-Änderungen, geänderte Scopes, geänderte Plugins und erstellt das CI-Manifest | Immer bei Nicht-Entwurf-Pushes und PRs |
| `security-scm-fast` | Private-Key-Erkennung und Workflow-Audit über `zizmor` | Immer bei Nicht-Entwurf-Pushes und PRs |
| `security-dependency-audit` | Produktions-Lockfile-Audit ohne Dependency-Installation gegen npm-Advisories | Immer bei Nicht-Entwurf-Pushes und PRs |
| `security-fast` | Erforderliches Aggregat für die schnellen Sicherheits-Jobs | Immer bei Nicht-Entwurf-Pushes und PRs |
| `check-dependencies` | Reiner Produktions-Knip-Dependency-Durchlauf plus Guard für die Allowlist ungenutzter Dateien | Node-relevante Änderungen |
| `build-artifacts` | Baut `dist/`, Control UI, Prüfungen gebauter Artefakte und wiederverwendbare Downstream-Artefakte | Node-relevante Änderungen |
| `checks-fast-core` | Schnelle Linux-Korrektheits-Lanes wie Prüfungen für gebündelte Plugins, Plugin-Verträge und Protokolle | Node-relevante Änderungen |
| `checks-fast-contracts-channels` | Shard-basierte Channel-Vertragsprüfungen mit stabilem aggregiertem Prüfergebnis | Node-relevante Änderungen |
| `checks-node-core-test` | Core-Node-Test-Shards, ohne Channel-, Bündel-, Vertrags- und Plugin-Lanes | Node-relevante Änderungen |
| `check` | Shard-basiertes Äquivalent des lokalen Haupt-Gates: Produktionstypen, Lint, Guards, Testtypen und strikter Smoke | Node-relevante Änderungen |
| `check-additional` | Architektur, shard-basierter Boundary-/Prompt-Drift, Plugin-Guards, Package-Boundary und Gateway-Watch | Node-relevante Änderungen |
| `build-smoke` | Smoke-Tests für gebaute CLI und Smoke-Test für Startspeicher | Node-relevante Änderungen |
| `checks` | Verifier für Channel-Tests mit gebauten Artefakten | Node-relevante Änderungen |
| `checks-node-compat-node22` | Node-22-Kompatibilitätsbuild und Smoke-Lane | Manueller CI-Dispatch für Releases |
| `check-docs` | Docs-Formatierung, Lint und Prüfungen auf defekte Links | Docs geändert |
| `skills-python` | Ruff + pytest für Python-gestützte Skills | Python-Skill-relevante Änderungen |
| `checks-windows` | Windows-spezifische Prozess-/Pfadtests plus gemeinsame Regressionen für Runtime-Import-Spezifizierer | Windows-relevante Änderungen |
| `macos-node` | macOS-TypeScript-Test-Lane mit den gemeinsam genutzten gebauten Artefakten | macOS-relevante Änderungen |
| `macos-swift` | Swift-Lint, Build und Tests für die macOS-App | macOS-relevante Änderungen |
| `android` | Android-Unit-Tests für beide Flavors plus ein Debug-APK-Build | Android-relevante Änderungen |
| `test-performance-agent` | Tägliche Codex-Optimierung langsamer Tests nach vertrauenswürdiger Aktivität | Erfolg der Main-CI oder manueller Dispatch |
| `openclaw-performance` | Tägliche/bei Bedarf erstellte Kova-Runtime-Performanceberichte mit Mock-Provider-, Deep-Profile- und GPT-5.4-Live-Lanes | Geplanter und manueller Dispatch |
## Fail-Fast-Reihenfolge
1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik für `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs.
1. `preflight` entscheidet, welche Lanes überhaupt existieren. Die Logik `docs-scope` und `changed-scope` sind Schritte innerhalb dieses Jobs, keine eigenständigen Jobs.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` und `skills-python` schlagen schnell fehl, ohne auf die schwereren Artefakt- und Plattform-Matrix-Jobs zu warten.
3. `build-artifacts` überschneidet sich mit den schnellen Linux-Lanes, damit Downstream-Consumer starten können, sobald der gemeinsame Build bereit ist.
3. `build-artifacts` überlappt sich mit den schnellen Linux-Lanes, damit Downstream-Consumer starten können, sobald der gemeinsame Build bereit ist.
4. Schwerere Plattform- und Runtime-Lanes fächern danach auf: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` und `android`.
GitHub kann ersetzte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR- oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch der neueste Lauf für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, sodass sie normale Shard-Fehler weiterhin melden, aber nicht mehr in die Warteschlange gehen, nachdem der gesamte Workflow bereits ersetzt wurde. Der automatische CI-Concurrency-Key ist versioniert (`CI-v7-*`), damit ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann. Manuelle Läufe der vollständigen Suite verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab.
GitHub kann überholte Jobs als `cancelled` markieren, wenn ein neuerer Push auf demselben PR- oder `main`-Ref landet. Behandeln Sie das als CI-Rauschen, sofern nicht auch der neueste Lauf für denselben Ref fehlschlägt. Aggregierte Shard-Prüfungen verwenden `!cancelled() && always()`, sodass sie normale Shard-Fehler weiterhin melden, aber nicht mehr eingereiht werden, nachdem der gesamte Workflow bereits überholt wurde. Der automatische CI-Concurrency-Key ist versioniert (`CI-v7-*`), damit ein GitHub-seitiger Zombie in einer alten Queue-Gruppe neuere Main-Läufe nicht unbegrenzt blockieren kann. Manuelle Läufe der vollständigen Suite verwenden `CI-manual-v1-*` und brechen laufende Läufe nicht ab.
## Scope und Routing
Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und ist durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Erkennung geänderter Scopes und lässt das Preflight-Manifest so handeln, als hätte sich jeder gescopte Bereich geändert.
Die Scope-Logik befindet sich in `scripts/ci-changed-scope.mjs` und wird durch Unit-Tests in `src/scripts/ci-changed-scope.test.ts` abgedeckt. Manueller Dispatch überspringt die Changed-Scope-Erkennung und lässt das Preflight-Manifest so agieren, als wäre jeder gescopte Bereich geändert worden.
- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Source-Änderungen beschränkt.
- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und schmale Plugin-Vertrags-Helper-/Test-Routing-Änderungen** verwenden einen schnellen Node-only-Manifestpfad: `preflight`, Sicherheit und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Verträge, vollständige Core-Shards, Bundled-Plugin-Shards und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Helper-Oberflächen beschränkt ist, die die schnelle Aufgabe direkt ausführt.
- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helper, Paketmanager-Konfiguration und die CI-Workflow-Oberflächen beschränkt, die diese Lane ausführen; nicht zusammenhängende Source-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes.
- **CI-Workflow-Änderungen** validieren den Node-CI-Graphen plus Workflow-Linting, erzwingen aber für sich genommen keine nativen Windows-, Android- oder macOS-Builds; diese Plattform-Lanes bleiben auf Plattform-Quelländerungen gescopet.
- **Reine CI-Routing-Änderungen, ausgewählte günstige Core-Test-Fixture-Änderungen und enge Plugin-Vertrags-Helper-/Test-Routing-Änderungen** verwenden einen schnellen Node-only-Manifestpfad: `preflight`, Sicherheit und eine einzelne `checks-fast-core`-Aufgabe. Dieser Pfad überspringt Build-Artefakte, Node-22-Kompatibilität, Channel-Verträge, vollständige Core-Shards, Shards gebündelter Plugins und zusätzliche Guard-Matrizen, wenn die Änderung auf die Routing- oder Helper-Oberflächen beschränkt ist, die die schnelle Aufgabe direkt ausübt.
- **Windows-Node-Prüfungen** sind auf Windows-spezifische Prozess-/Pfad-Wrapper, npm-/pnpm-/UI-Runner-Helper, Package-Manager-Konfiguration und die CI-Workflow-Oberflächen gescopet, die diese Lane ausführen; nicht zusammenhängende Source-, Plugin-, Install-Smoke- und reine Teständerungen bleiben auf den Linux-Node-Lanes.
Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, damit jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Verträge laufen als drei gewichtete Shards, Core-Unit-Fast-/Support-Lanes laufen separat, Core-Runtime-Infrastruktur ist zwischen State- und Process-/Config-Shards aufgeteilt, Auto-Reply läuft als ausbalancierte Worker (mit dem Reply-Teilbaum aufgeteilt in Agent-Runner-, Dispatch- und Commands-/State-Routing-Shards), und agentische Gateway-/Server-Konfigurationen sind über Chat-/Auth-/Model-/HTTP-Plugin-/Runtime-/Startup-Lanes aufgeteilt, statt auf Built Artifacts zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-all. Include-Pattern-Shards erfassen Timing-Einträge mit dem CI-Shard-Namen, sodass `.artifacts/vitest-shard-timings.json` eine ganze Konfiguration von einem gefilterten Shard unterscheiden kann. `check-additional` hält Compile-/Canary-Arbeit zur Paketgrenze zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; die Boundary-Guard-Liste ist über vier Matrix-Shards gestreift, von denen jeder ausgewählte unabhängige Guards parallel ausführt und Timings pro Prüfung ausgibt, einschließlich `pnpm prompt:snapshots:check`, damit Prompt-Drift im Happy Path der Codex-Runtime dem PR zugeordnet bleibt, der sie verursacht hat. Gateway Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut sind.
Die langsamsten Node-Testfamilien sind aufgeteilt oder ausbalanciert, sodass jeder Job klein bleibt, ohne Runner übermäßig zu reservieren: Channel-Verträge laufen als drei gewichtete Shards, schnelle Core-Unit-/Support-Lanes laufen separat, Core-Runtime-Infrastruktur ist zwischen State- und Process-/Config-Shards aufgeteilt, Auto-Reply läuft als ausbalancierte Worker (mit dem Reply-Teilbaum aufgeteilt in Agent-Runner-, Dispatch- und Commands-/State-Routing-Shards), und agentische Gateway-/Server-Konfigurationen sind über Chat-/Auth-/Model-/HTTP-Plugin-/Runtime-/Startup-Lanes verteilt, statt auf gebaute Artefakte zu warten. Breite Browser-, QA-, Medien- und sonstige Plugin-Tests verwenden ihre dedizierten Vitest-Konfigurationen statt des gemeinsamen Plugin-Catch-all. Include-Pattern-Shards zeichnen Timing-Einträge mit dem CI-Shard-Namen auf, sodass `.artifacts/vitest-shard-timings.json` eine ganze Konfiguration von einem gefilterten Shard unterscheiden kann. `check-additional` hält Package-Boundary-Compile-/Canary-Arbeit zusammen und trennt Runtime-Topologie-Architektur von Gateway-Watch-Abdeckung; die Boundary-Guard-Liste wird über vier Matrix-Shards gestreift, wobei jeder ausgewählte unabhängige Guards parallel ausführt und Timings pro Prüfung ausgibt, einschließlich `pnpm prompt:snapshots:check`, damit Prompt-Drift im Codex-Runtime-Happy-Path an den PR gebunden ist, der sie verursacht hat. Gateway-Watch, Channel-Tests und der Core-Support-Boundary-Shard laufen innerhalb von `build-artifacts` parallel, nachdem `dist/` und `dist-runtime/` bereits gebaut wurden.
Android CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und erstellt anschließend das Play-Debug-APK. Der Third-Party-Flavor hat kein separates Source Set oder Manifest; seine Unit-Test-Lane kompiliert den Flavor weiterhin mit den SMS-/Anrufprotokoll-BuildConfig-Flags, vermeidet aber bei jedem Android-relevanten Push einen doppelten Debug-APK-Paketierungsjob.
Android-CI führt sowohl `testPlayDebugUnitTest` als auch `testThirdPartyDebugUnitTest` aus und baut anschließend das Play-Debug-APK. Der Third-Party-Flavor hat kein separates Source-Set oder Manifest; seine Unit-Test-Lane kompiliert den Flavor weiterhin mit den SMS-/Call-Log-`BuildConfig`-Flags, vermeidet aber bei jedem Android-relevanten Push einen doppelten Debug-APK-Package-Job.
Der `check-dependencies`-Shard führt `pnpm deadcode:dependencies` (einen Produktions-Knip-Durchlauf nur für Abhängigkeiten, fixiert auf die neueste Knip-Version, wobei pnpm's Mindest-Release-Alter für die `dlx`-Installation deaktiviert ist) und `pnpm deadcode:unused-files` aus, das Knips Produktionsfunde ungenutzter Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Guard für ungenutzte Dateien schlägt fehl, wenn ein PR eine neue, nicht geprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtlich dynamische Plugin-, generierte, Build-, Live-Test- und Paket-Bridge-Oberflächen erhalten bleiben, die Knip statisch nicht auflösen kann.
Der Shard `check-dependencies` führt `pnpm deadcode:dependencies` (einen reinen Produktions-Knip-Dependency-Durchlauf, der an die neueste Knip-Version gebunden ist, wobei das Mindest-Release-Alter von pnpm für die `dlx`-Installation deaktiviert ist) und `pnpm deadcode:unused-files` aus, das Knips Produktionsfunde ungenutzter Dateien mit `scripts/deadcode-unused-files.allowlist.mjs` vergleicht. Der Guard für ungenutzte Dateien schlägt fehl, wenn ein PR eine neue ungeprüfte ungenutzte Datei hinzufügt oder einen veralteten Allowlist-Eintrag zurücklässt, während absichtliche dynamische Plugin-, generierte, Build-, Live-Test- und Package-Bridge-Oberflächen erhalten bleiben, die Knip statisch nicht auflösen kann.
## ClawSweeper-Aktivitätsweiterleitung
## Weiterleitung von ClawSweeper-Aktivität
`.github/workflows/clawsweeper-dispatch.yml` ist die zielseitige Bridge von OpenClaw-Repository-Aktivität zu ClawSweeper. Sie checkt keinen nicht vertrauenswürdigen Pull-Request-Code aus und führt ihn nicht aus. Der Workflow erstellt aus `CLAWSWEEPER_APP_PRIVATE_KEY` ein GitHub-App-Token und dispatcht dann kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`.
`.github/workflows/clawsweeper-dispatch.yml` ist die Zielseiten-Brücke von OpenClaw-Repository-Aktivität zu ClawSweeper. Sie checkt keinen nicht vertrauenswürdigen Pull-Request-Code aus und führt ihn nicht aus. Der Workflow erstellt aus `CLAWSWEEPER_APP_PRIVATE_KEY` ein GitHub-App-Token und dispatcht anschließend kompakte `repository_dispatch`-Payloads an `openclaw/clawsweeper`.
Der Workflow hat vier Lanes:
- `clawsweeper_item` für exakte Review-Anfragen zu Issues und Pull Requests;
- `clawsweeper_comment` für explizite ClawSweeper-Befehle in Issue-Kommentaren;
- `clawsweeper_commit_review` für Review-Anfragen auf Commit-Ebene bei `main`-Pushes;
- `github_activity` für allgemeine GitHub-Aktivität, die der ClawSweeper-Agent inspizieren kann.
- `github_activity` für allgemeine GitHub-Aktivität, die der ClawSweeper-Agent prüfen kann.
Die `github_activity`-Lane leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Akteur, Repository, Item-Nummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet bewusst die Weiterleitung des vollständigen Webhook-Bodys. Der empfangende Workflow in `openclaw/clawsweeper` ist `.github/workflows/github-activity.yml`, der das normalisierte Ereignis an den OpenClaw-Gateway-Hook für den ClawSweeper-Agent postet.
Die Lane `github_activity` leitet nur normalisierte Metadaten weiter: Ereignistyp, Aktion, Akteur, Repository, Item-Nummer, URL, Titel, Status und kurze Auszüge für Kommentare oder Reviews, sofern vorhanden. Sie vermeidet absichtlich die Weiterleitung des vollständigen Webhook-Bodys. Der empfangende Workflow in `openclaw/clawsweeper` ist `.github/workflows/github-activity.yml`; er postet das normalisierte Ereignis an den OpenClaw-Gateway-Hook für den ClawSweeper-Agent.
Allgemeine Aktivität ist Beobachtung, nicht standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann in `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder betrieblich nützlich ist. Routinemäßige Opens, Edits, Bot-Aktivität, doppeltes Webhook-Rauschen und normaler Review-Verkehr sollten zu `NO_REPLY` führen.
Allgemeine Aktivität ist Beobachtung, keine standardmäßige Zustellung. Der ClawSweeper-Agent erhält das Discord-Ziel in seinem Prompt und sollte nur dann an `#clawsweeper` posten, wenn das Ereignis überraschend, handlungsrelevant, riskant oder operativ nützlich ist. Routinemäßige Eröffnungen, Bearbeitungen, Bot-Aktivität, doppeltes Webhook-Rauschen und normaler Review-Verkehr sollten zu `NO_REPLY` führen.
Behandeln Sie GitHub-Titel, Kommentare, Bodies, Review-Text, Branch-Namen und Commit-Nachrichten in diesem gesamten Pfad als nicht vertrauenswürdige Daten. Sie sind Eingaben für Zusammenfassung und Triage, keine Anweisungen für den Workflow oder die Agent-Runtime.
Behandeln Sie GitHub-Titel, Kommentare, Bodys, Review-Texte, Branchnamen und Commit-Nachrichten in diesem gesamten Pfad als nicht vertrauenswürdige Daten. Sie sind Eingaben für Zusammenfassung und Triage, keine Anweisungen für den Workflow oder die Agent-Runtime.
## Manuelle Dispatches
Manuelle CI-Dispatches führen denselben Job-Graphen wie die normale CI aus, erzwingen jedoch jede nicht auf Android begrenzte Lane: Linux Node-Shards, gebündelte Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Dokumentationsprüfungen, Python-Skills, Windows, macOS und Control UI i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; der vollständige Release-Umbrella aktiviert Android durch Übergabe von `include_android=true`. Statische Plugin-Prerelease-Prüfungen, der nur für Releases vorgesehene `agentic-plugins`-Shard, die vollständige Erweiterungs-Batch-Prüfung und Docker-Lanes für Plugin-Prereleases sind von der CI ausgeschlossen. Die Docker-Prerelease-Suite wird nur ausgeführt, wenn `Full Release Validation` den separaten `Plugin Prerelease`-Workflow mit aktiviertem Release-Validation-Gate dispatcht.
Manuelle CI-Dispatches führen denselben Job-Graphen wie die normale CI aus, erzwingen aber jede nicht auf Android beschränkte Lane: Linux-Node-Shards, Bundled-Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Prüfungen, Python-Skills, Windows, macOS und Control-UI-i18n. Eigenständige manuelle CI-Dispatches führen Android nur mit `include_android=true` aus; das vollständige Release-Umbrella aktiviert Android, indem es `include_android=true` übergibt. Statische Plugin-Prerelease-Prüfungen, der nur für Releases vorgesehene `agentic-plugins`-Shard, der vollständige Extension-Batch-Sweep und Plugin-Prerelease-Docker-Lanes sind von der CI ausgeschlossen. Die Docker-Prerelease-Suite läuft nur, wenn `Full Release Validation` den separaten `Plugin Prerelease`-Workflow mit aktivierter Release-Validation-Gate dispatcht.
Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, damit eine vollständige Suite für einen Release-Kandidaten nicht durch einen anderen Push- oder PR-Lauf auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` ermöglicht einem vertrauenswürdigen Aufrufer, diesen Graphen gegen einen Branch, ein Tag oder eine vollständige Commit-SHA auszuführen, während die Workflow-Datei aus dem ausgewählten Dispatch-Ref verwendet wird.
Manuelle Läufe verwenden eine eindeutige Concurrency-Gruppe, sodass eine vollständige Release-Candidate-Suite nicht durch einen anderen Push- oder PR-Lauf auf demselben Ref abgebrochen wird. Die optionale Eingabe `target_ref` ermöglicht es einem vertrauenswürdigen Aufrufer, diesen Graphen gegen einen Branch, Tag oder vollständigen Commit-SHA auszuführen, während die Workflow-Datei aus dem ausgewählten Dispatch-Ref verwendet wird.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -98,17 +98,17 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Runner
| Runner | Jobs |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, schnelle Security-Jobs und Aggregationen (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Vertrags-/gebündelte Prüfungen, geshardete Channel-Vertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregationen, Aggregat-Prüfer für Node-Tests, Dokumentationsprüfungen, Python-Skills, workflow-sanity, labeler, auto-response; install-smoke preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher eingereiht werden kann |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, weniger gewichtige Erweiterungs-Shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` und `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, Linux Node-Test-Shards, gebündelte Plugin-Test-Shards, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (CPU-sensitiv genug, dass 8 vCPU mehr kosteten, als sie einsparten); install-smoke-Docker-Builds (32-vCPU-Warteschlangenzeit kostete mehr, als sie einsparte) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
| Runner | Jobs |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, schnelle Security-Jobs und Aggregationen (`security-scm-fast`, `security-dependency-audit`, `security-fast`), schnelle Protokoll-/Vertrags-/Bundled-Prüfungen, geshardete Channel-Vertragsprüfungen, `check`-Shards außer Lint, `check-additional`-Shards und Aggregationen, Node-Test-Aggregatverifizierer, Docs-Prüfungen, Python-Skills, Workflow-Sanity, Labeler, Auto-Response; Install-Smoke-Preflight verwendet ebenfalls GitHub-gehostetes Ubuntu, damit die Blacksmith-Matrix früher in die Warteschlange kann |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, leichtere Extension-Shards, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` und `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, Build-Smoke, Linux-Node-Test-Shards, Bundled-Plugin-Test-Shards, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (CPU-empfindlich genug, dass 8 vCPU mehr kosteten, als sie sparten); Install-Smoke-Docker-Builds (32-vCPU-Warteschlangenzeit kostete mehr, als sie sparte) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` auf `openclaw/openclaw`; Forks fallen auf `macos-latest` zurück |
## Lokale Entsprechungen
## Lokale Äquivalente
```bash
pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD
@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
## OpenClaw Performance
`OpenClaw Performance` ist der Produkt-/Runtime-Performance-Workflow. Er läuft täglich auf `main` und kann manuell dispatcht werden:
`OpenClaw Performance` ist der Workflow für Produkt- und Runtime-Performance. Er läuft täglich auf `main` und kann manuell dispatcht werden:
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@ -145,21 +145,21 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
```
Ein manueller Dispatch benchmarkt normalerweise den Workflow-Ref. Setzen Sie `target_ref`, um ein Release-Tag oder einen anderen Branch mit der aktuellen Workflow-Implementierung zu benchmarken. Veröffentlichte Berichtspfade und latest-Zeiger werden nach dem getesteten Ref geschlüsselt, und jede `index.md` erfasst den getesteten Ref/SHA, Workflow-Ref/SHA, Kova-Ref, Profil, Lane-Auth-Modus, Modell, Wiederholungsanzahl und Szenariofilter.
Ein manueller Dispatch benchmarked normalerweise den Workflow-Ref. Setzen Sie `target_ref`, um ein Release-Tag oder einen anderen Branch mit der aktuellen Workflow-Implementierung zu benchmarken. Veröffentlichte Berichtspfade und Latest-Pointer werden nach dem getesteten Ref geschlüsselt, und jede `index.md` zeichnet den getesteten Ref/SHA, Workflow-Ref/SHA, Kova-Ref, Profil, Lane-Auth-Modus, Modell, Wiederholungsanzahl und Szenariofilter auf.
Der Workflow installiert OCM aus einem gepinnten Release und Kova aus `openclaw/Kova` mit der gepinnten Eingabe `kova_ref` und führt dann drei Lanes aus:
- `mock-provider`: Kova-Diagnoseszenarien gegen eine lokal gebaute Runtime mit deterministischer gefälschter OpenAI-kompatibler Authentifizierung.
- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Start-, Gateway- und Agent-Turn-Hotspots.
- `mock-provider`: Kova-Diagnoseszenarien gegen eine Runtime aus lokalem Build mit deterministischer, gefakter OpenAI-kompatibler Authentifizierung.
- `mock-deep-profile`: CPU-/Heap-/Trace-Profiling für Startup-, Gateway- und Agent-Turn-Hotspots.
- `live-gpt54`: ein echter OpenAI-`openai/gpt-5.4`-Agent-Turn, der übersprungen wird, wenn `OPENAI_API_KEY` nicht verfügbar ist.
Die mock-provider-Lane führt nach dem Kova-Durchlauf außerdem OpenClaw-native Source-Probes aus: Gateway-Start-Timing und Speicher über Standard-, Hook- und 50-Plugin-Startfälle hinweg; wiederholte mock-OpenAI-`channel-chat-baseline`-Hello-Loops; und CLI-Startbefehle gegen das gestartete Gateway. Die Markdown-Zusammenfassung der Source-Probe liegt unter `source/index.md` im Berichtsbundle, mit Roh-JSON daneben.
Die Mock-Provider-Lane führt nach dem Kova-Durchlauf außerdem OpenClaw-native Source-Probes aus: Gateway-Boot-Timing und Speicher über die Startup-Fälle Default, Hook und 50 Plugins hinweg; wiederholte Mock-OpenAI-`channel-chat-baseline`-Hello-Schleifen; und CLI-Startup-Befehle gegen das gestartete Gateway. Die Markdown-Zusammenfassung der Source-Probe liegt unter `source/index.md` im Berichtsbundle, mit Roh-JSON daneben.
Jede Lane lädt GitHub-Artefakte hoch. Wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist, committet der Workflow außerdem `report.json`, `report.md`, Bundles, `index.md` und Source-Probe-Artefakte in `openclaw/clawgrit-reports` unter `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Der aktuelle tested-ref-Zeiger wird als `openclaw-performance/<tested-ref>/latest-<lane>.json` geschrieben.
Jede Lane lädt GitHub-Artefakte hoch. Wenn `CLAWGRIT_REPORTS_TOKEN` konfiguriert ist, committet der Workflow außerdem `report.json`, `report.md`, Bundles, `index.md` und Source-Probe-Artefakte nach `openclaw/clawgrit-reports` unter `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Der aktuelle Tested-Ref-Pointer wird als `openclaw-performance/<tested-ref>/latest-<lane>.json` geschrieben.
## Vollständige Release-Validierung
`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, ein Tag oder eine vollständige Commit-SHA, dispatcht den manuellen `CI`-Workflow mit diesem Ziel, dispatcht `Plugin Prerelease` für nur für Releases vorgesehene Plugin-/Paket-/statische/Docker-Nachweise und dispatcht `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, Docker-Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix und Telegram-Lanes. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus den Release-Prüfungen aus. Nach der Veröffentlichung übergeben Sie `npm_telegram_package_spec`, um dieselbe Telegram-Paket-Lane gegen das veröffentlichte npm-Paket erneut auszuführen.
`Full Release Validation` ist der manuelle Umbrella-Workflow für „alles vor dem Release ausführen“. Er akzeptiert einen Branch, ein Tag oder einen vollständigen Commit-SHA, dispatcht den manuellen `CI`-Workflow mit diesem Ziel, dispatcht `Plugin Prerelease` für nur Release-bezogene Plugin-/Paket-/statische/Docker-Nachweise und dispatcht `OpenClaw Release Checks` für Install-Smoke, Paketakzeptanz, Cross-OS-Paketprüfungen, QA-Lab-Parität, Matrix und Telegram-Lanes. Stabile/Default-Läufe halten vollständige Live-/E2E- und Docker-Release-Path-Abdeckung hinter `run_release_soak=true`; `release_profile=full` erzwingt diese Soak-Abdeckung, sodass breite Advisory-Validierung breit bleibt. Mit `rerun_group=all` und `release_profile=full` führt er außerdem `NPM Telegram Beta E2E` gegen das Artefakt `release-package-under-test` aus den Release-Prüfungen aus. Übergeben Sie nach der Veröffentlichung `npm_telegram_package_spec`, um dieselbe Telegram-Paket-Lane gegen das veröffentlichte npm-Paket erneut auszuführen.
Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für die
Stage-Matrix, exakten Workflow-Jobnamen, Profilunterschiede, Artefakte und
@ -169,7 +169,7 @@ gezielte Rerun-Handles.
von `release/YYYY.M.D` oder `main`, nachdem das Release-Tag existiert und nachdem der
OpenClaw-npm-Preflight erfolgreich war. Er verifiziert `pnpm plugins:sync:check`,
dispatcht `Plugin NPM Release` für alle veröffentlichbaren Plugin-Pakete, dispatcht
`Plugin ClawHub Release` für dieselbe Release-SHA und dispatcht erst dann
`Plugin ClawHub Release` für denselben Release-SHA und dispatcht erst dann
`OpenClaw NPM Release` mit der gespeicherten `preflight_run_id`.
```bash
@ -180,7 +180,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Für einen gepinnten Commit-Nachweis auf einem sich schnell bewegenden Branch verwenden Sie den Helper anstelle von
Für gepinnten Commit-Nachweis auf einem sich schnell bewegenden Branch verwenden Sie den Helper statt
`gh workflow run ... --ref main -f ref=<sha>`:
```bash
@ -188,36 +188,37 @@ pnpm ci:full-release --sha <full-sha>
```
GitHub-Workflow-Dispatch-Refs müssen Branches oder Tags sein, keine rohen Commit-SHAs. Der
Helper pusht einen temporären Branch `release-ci/<sha>-...` auf der Ziel-SHA,
dispatcht `Full Release Validation` von diesem gepinnten Ref, verifiziert, dass jede untergeordnete
Workflow-`headSha` dem Ziel entspricht, und löscht den temporären Branch, wenn der
Lauf abgeschlossen ist. Der Umbrella-Verifizierer schlägt außerdem fehl, wenn ein untergeordneter Workflow mit einer
Helper pusht einen temporären Branch `release-ci/<sha>-...` am Ziel-SHA,
dispatcht `Full Release Validation` von diesem gepinnten Ref, verifiziert, dass jeder untergeordnete
Workflow-`headSha` mit dem Ziel übereinstimmt, und löscht den temporären Branch, wenn der
Lauf abgeschlossen ist. Der Umbrella-Verifizierer schlägt außerdem fehl, wenn ein untergeordneter Workflow mit einem
anderen SHA lief.
`release_profile` steuert die Live-/Provider-Breite, die an Release-Prüfungen übergeben wird. Die
manuellen Release-Workflows verwenden standardmäßig `stable`; verwenden Sie `full` nur, wenn Sie
bewusst die breite beratende Provider-/Medienmatrix ausführen möchten.
bewusst die breite beratende Provider-/Medien-Matrix ausführen möchten. `run_release_soak`
steuert, ob stabile/standardmäßige Release-Prüfungen den umfassenden Live-/E2E- und
Docker-Release-Pfad-Soak ausführen; `full` erzwingt Soak.
- `minimum` behält die schnellsten OpenAI-/Core-Lanes bei, die für Releases kritisch sind.
- `stable` fügt das stabile Provider-/Backend-Set hinzu.
- `full` führt die breite beratende Provider-/Medienmatrix aus.
- `minimum` behält die schnellsten OpenAI-/Core-releasekritischen Lanes bei.
- `stable` fügt den stabilen Provider-/Backend-Satz hinzu.
- `full` führt die breite beratende Provider-/Medien-Matrix aus.
Der Umbrella zeichnet die IDs der gestarteten Child-Runs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Ergebnisse der Child-Runs erneut und hängt Tabellen mit den langsamsten Jobs für jeden Child-Run an. Wenn ein Child-Workflow erneut ausgeführt wird und grün wird, führen Sie nur den Parent-Verifier-Job erneut aus, um das Umbrella-Ergebnis und die Timing-Zusammenfassung zu aktualisieren.
Der Umbrella zeichnet die ausgelösten Child-Run-IDs auf, und der abschließende Job `Verify full validation` prüft die aktuellen Child-Run-Ergebnisse erneut und hängt Tabellen mit den langsamsten Jobs für jeden Child-Run an. Wenn ein Child-Workflow erneut ausgeführt wird und grün wird, führen Sie nur den übergeordneten Verifizierer-Job erneut aus, um das Umbrella-Ergebnis und die Zeitübersicht zu aktualisieren.
Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release-Kandidaten, `ci` nur für das normale vollständige CI-Child, `plugin-prerelease` nur für das Plugin-Prerelease-Child, `release-checks` für jedes Release-Child oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` auf dem Umbrella. Dadurch bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einer gezielten Korrektur begrenzt.
Für die Wiederherstellung akzeptieren sowohl `Full Release Validation` als auch `OpenClaw Release Checks` `rerun_group`. Verwenden Sie `all` für einen Release Candidate, `ci` nur für das normale vollständige CI-Child, `plugin-prerelease` nur für das Plugin-Prerelease-Child, `release-checks` für jedes Release-Child oder eine engere Gruppe: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` oder `npm-telegram` auf dem Umbrella. Dadurch bleibt die erneute Ausführung einer fehlgeschlagenen Release-Box nach einer gezielten Korrektur begrenzt. Für eine fehlgeschlagene Cross-OS-Lane kombinieren Sie `rerun_group=cross-os` mit `cross_os_suite_filter`, zum Beispiel `windows/packaged-upgrade`; lange Cross-OS-Befehle geben Heartbeat-Zeilen aus, und Packaged-Upgrade-Zusammenfassungen enthalten Zeitangaben pro Phase. QA-Release-Check-Lanes sind beratend, daher warnen reine QA-Fehler, blockieren aber den Release-Check-Verifizierer nicht.
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Referenz, um die ausgewählte Referenz einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann sowohl an den Docker-Workflow für den Live-/E2E-Release-Pfad als auch an den Package-Acceptance-Shard. Dadurch bleiben die Paketbytes über Release-Boxen hinweg konsistent, und derselbe Kandidat muss nicht in mehreren Child-Jobs neu gepackt werden.
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Referenz, um die ausgewählte Referenz einmal in ein `release-package-under-test`-Tarball aufzulösen, und übergibt dieses Artefakt dann an Cross-OS-Prüfungen und die Paketakzeptanz sowie an den Live-/E2E-Release-Pfad-Docker-Workflow, wenn Soak-Abdeckung ausgeführt wird. Dadurch bleiben die Paketbytes über Release-Boxen hinweg konsistent, und derselbe Kandidat muss nicht in mehreren Child-Jobs neu gepackt werden.
Doppelte `Full Release Validation`-Runs für `ref=main` und `rerun_group=all`
ersetzen den älteren Umbrella. Der Parent-Monitor bricht jeden Child-Workflow ab,
den er bereits gestartet hat, wenn der Parent abgebrochen wird, sodass eine neuere
Main-Validierung nicht hinter einem veralteten zweistündigen Release-Check-Run
wartet. Die Validierung von Release-Branches/-Tags und gezielte Rerun-Gruppen
behalten `cancel-in-progress: false` bei.
ersetzen den älteren Umbrella. Der übergeordnete Monitor bricht jeden Child-Workflow ab, den er
bereits ausgelöst hat, wenn der Parent abgebrochen wird, sodass neuere Main-Validierung
nicht hinter einem veralteten zweistündigen Release-Check-Run wartet. Validierung von Release-Branches/-Tags
und gezielte Rerun-Gruppen behalten `cancel-in-progress: false`.
## Live- und E2E-Shards
Das Release-Live-/E2E-Child behält die breite native Abdeckung durch `pnpm test:live` bei, führt sie aber über `scripts/test-live-shard.mjs` als benannte Shards aus statt als einen seriellen Job:
Das Release-Live-/E2E-Child behält die breite native `pnpm test:live`-Abdeckung bei, führt sie aber als benannte Shards über `scripts/test-live-shard.mjs` statt als einen seriellen Job aus:
- `native-live-src-agents`
- `native-live-src-gateway-core`
@ -231,33 +232,33 @@ Das Release-Live-/E2E-Child behält die breite native Abdeckung durch `pnpm test
- `native-live-extensions-xai`
- aufgeteilte Medien-Audio-/Video-Shards und Provider-gefilterte Musik-Shards
Das behält dieselbe Dateiabdeckung bei und macht langsame Live-Provider-Fehler leichter erneut ausführbar und diagnostizierbar. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle Einmal-Reruns gültig.
Dadurch bleibt dieselbe Dateiabdeckung erhalten, während langsame Live-Provider-Fehler leichter erneut ausgeführt und diagnostiziert werden können. Die aggregierten Shard-Namen `native-live-extensions-o-z`, `native-live-extensions-media` und `native-live-extensions-media-music` bleiben für manuelle einmalige Reruns gültig.
Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut vom Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medien-Jobs verifizieren nur die Binärdateien vor dem Setup. Belassen Sie Docker-gestützte Live-Suites auf normalen Blacksmith-Runnern — Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten.
Die nativen Live-Medien-Shards laufen in `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, gebaut vom Workflow `Live Media Runner Image`. Dieses Image installiert `ffmpeg` und `ffprobe` vor; Medienjobs prüfen vor dem Setup nur die Binärdateien. Belassen Sie Docker-gestützte Live-Suiten auf normalen Blacksmith-Runnern — Container-Jobs sind der falsche Ort, um verschachtelte Docker-Tests zu starten.
Docker-gestützte Live-Modell-/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:<sha>` pro ausgewähltem Commit. Der Live-Release-Workflow baut und pusht dieses Image einmal; anschließend laufen die Docker-Live-Modell-, Provider-geshardeten Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards tragen explizite Timeout-Obergrenzen auf Skriptebene unterhalb des Workflow-Job-Timeouts, damit ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit durch doppelte Image-Builds.
Docker-gestützte Live-Modell-/Backend-Shards verwenden ein separates gemeinsames Image `ghcr.io/openclaw/openclaw-live-test:<sha>` pro ausgewähltem Commit. Der Live-Release-Workflow baut und pusht dieses Image einmal, danach laufen die Docker-Live-Modell-, Provider-geshardeten Gateway-, CLI-Backend-, ACP-Bind- und Codex-Harness-Shards mit `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway-Docker-Shards tragen explizite Timeout-Begrenzungen auf Skriptebene unterhalb des Workflow-Job-Timeouts, damit ein hängender Container oder Cleanup-Pfad schnell fehlschlägt, statt das gesamte Release-Check-Budget zu verbrauchen. Wenn diese Shards das vollständige Source-Docker-Target unabhängig neu bauen, ist der Release-Run falsch konfiguriert und verschwendet Laufzeit mit doppelten Image-Builds.
## Paketabnahme
## Paketakzeptanz
Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Sie unterscheidet sich von normalem CI: Normales CI validiert den Quellbaum, während Package Acceptance ein einzelnes Tarball über denselben Docker-E2E-Harness validiert, den Benutzer nach Installation oder Update ausführen.
Verwenden Sie `Package Acceptance`, wenn die Frage lautet: „Funktioniert dieses installierbare OpenClaw-Paket als Produkt?“ Sie unterscheidet sich von normalem CI: Normales CI validiert den Source Tree, während die Paketakzeptanz ein einzelnes Tarball über dasselbe Docker-E2E-Harness validiert, das Benutzer nach Installation oder Update ausführen.
### Jobs
1. `resolve_package` checkt `workflow_ref` aus, löst einen Paketkandidaten auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Referenz, Paket-Referenz, Version, SHA-256 und Profil in der GitHub-Step-Zusammenfassung aus.
2. `docker_acceptance` ruft `openclaw-live-and-e2e-checks-reusable.yml` mit `ref=workflow_ref` und `package_artifact_name=package-under-test` auf. Der wiederverwendbare Workflow lädt dieses Artefakt herunter, validiert das Tarball-Inventar, bereitet bei Bedarf Package-Digest-Docker-Images vor und führt die ausgewählten Docker-Lanes gegen dieses Paket aus, statt den Workflow-Checkout zu packen. Wenn ein Profil mehrere gezielte `docker_lanes` auswählt, bereitet der wiederverwendbare Workflow das Paket und die gemeinsamen Images einmal vor und fächert diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten auf.
3. `package_telegram` ruft optional `NPM Telegram Beta E2E` auf. Es läuft, wenn `telegram_mode` nicht `none` ist, und installiert dasselbe Artefakt `package-under-test`, wenn Package Acceptance eines aufgelöst hat; ein eigenständiger Telegram-Dispatch kann weiterhin eine veröffentlichte npm-Spezifikation installieren.
4. `summary` lässt den Workflow fehlschlagen, wenn die Paketauflösung, Docker Acceptance oder die optionale Telegram-Lane fehlgeschlagen ist.
1. `resolve_package` checkt `workflow_ref` aus, löst einen Paketkandidaten auf, schreibt `.artifacts/docker-e2e-package/openclaw-current.tgz`, schreibt `.artifacts/docker-e2e-package/package-candidate.json`, lädt beide als Artefakt `package-under-test` hoch und gibt Quelle, Workflow-Referenz, Paket-Referenz, Version, SHA-256 und Profil in der GitHub-Schrittzusammenfassung aus.
2. `docker_acceptance` ruft `openclaw-live-and-e2e-checks-reusable.yml` mit `ref=workflow_ref` und `package_artifact_name=package-under-test` auf. Der wiederverwendbare Workflow lädt dieses Artefakt herunter, validiert das Tarball-Inventar, bereitet bei Bedarf Package-Digest-Docker-Images vor und führt die ausgewählten Docker-Lanes gegen dieses Paket aus, statt den Workflow-Checkout zu packen. Wenn ein Profil mehrere gezielte `docker_lanes` auswählt, bereitet der wiederverwendbare Workflow das Paket und die gemeinsamen Images einmal vor und verteilt diese Lanes dann als parallele gezielte Docker-Jobs mit eindeutigen Artefakten.
3. `package_telegram` ruft optional `NPM Telegram Beta E2E` auf. Es läuft, wenn `telegram_mode` nicht `none` ist, und installiert dasselbe Artefakt `package-under-test`, wenn die Paketakzeptanz eines aufgelöst hat; ein eigenständiger Telegram-Dispatch kann weiterhin eine veröffentlichte npm-Spezifikation installieren.
4. `summary` lässt den Workflow fehlschlagen, wenn Paketauflösung, Docker-Akzeptanz oder die optionale Telegram-Lane fehlgeschlagen sind.
### Kandidatenquellen
- `source=npm` akzeptiert nur `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für die Abnahme veröffentlichter Prerelease-/Stable-Versionen.
- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver ruft OpenClaw-Branches/-Tags ab, verifiziert, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten in einem detached Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`.
- `source=url` lädt ein HTTPS-`.tgz` herunter; `package_sha256` ist erforderlich.
- `source=artifact` lädt ein `.tgz` aus `artifact_run_id` und `artifact_name` herunter; `package_sha256` ist optional, sollte aber für extern geteilte Artefakte angegeben werden.
- `source=npm` akzeptiert nur `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-Version wie `openclaw@2026.4.27-beta.2`. Verwenden Sie dies für veröffentlichte Prerelease-/Stable-Akzeptanz.
- `source=ref` packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA. Der Resolver holt OpenClaw-Branches/-Tags, prüft, dass der ausgewählte Commit aus der Repository-Branch-Historie oder einem Release-Tag erreichbar ist, installiert Abhängigkeiten in einem getrennten Worktree und packt ihn mit `scripts/package-openclaw-for-docker.mjs`.
- `source=url` lädt eine HTTPS-`.tgz` herunter; `package_sha256` ist erforderlich.
- `source=artifact` lädt eine `.tgz` aus `artifact_run_id` und `artifact_name` herunter; `package_sha256` ist optional, sollte aber für extern geteilte Artefakte angegeben werden.
Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der vertrauenswürdige Workflow-/Harness-Code, der den Test ausführt. `package_ref` ist der Source-Commit, der gepackt wird, wenn `source=ref` verwendet wird. Dadurch kann der aktuelle Test-Harness ältere vertrauenswürdige Source-Commits validieren, ohne alte Workflow-Logik auszuführen.
Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der vertrauenswürdige Workflow-/Harness-Code, der den Test ausführt. `package_ref` ist der Source-Commit, der gepackt wird, wenn `source=ref`. Dadurch kann das aktuelle Test-Harness ältere vertrauenswürdige Source-Commits validieren, ohne alte Workflow-Logik auszuführen.
### Suite-Profile
### Suitenprofile
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
@ -265,25 +266,25 @@ Halten Sie `workflow_ref` und `package_ref` getrennt. `workflow_ref` ist der ver
- `full` — vollständige Docker-Release-Pfad-Chunks mit OpenWebUI
- `custom` — exakte `docker_lanes`; erforderlich, wenn `suite_profile=custom`
Das Profil `package` verwendet Offline-Plugin-Abdeckung, sodass die Validierung veröffentlichter Pakete nicht von der Live-Verfügbarkeit von ClawHub abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der Pfad für veröffentlichte npm-Spezifikationen bleibt für eigenständige Dispatches erhalten.
Das Profil `package` verwendet Offline-Plugin-Abdeckung, sodass die Validierung veröffentlichter Pakete nicht von der Live-Verfügbarkeit von ClawHub abhängt. Die optionale Telegram-Lane verwendet das Artefakt `package-under-test` in `NPM Telegram Beta E2E` wieder; der veröffentlichte npm-Spezifikationspfad bleibt für eigenständige Dispatches erhalten.
Für die dedizierte Update- und Plugin-Test-Richtlinie, einschließlich lokaler Befehle,
Docker-Lanes, Package-Acceptance-Eingaben, Release-Standards und Fehlertriage,
siehe [Updates und Plugins testen](/de/help/testing-updates-plugins).
Die dedizierte Richtlinie für Update- und Plugin-Tests, einschließlich lokaler Befehle,
Docker-Lanes, Paketakzeptanz-Eingaben, Release-Standards und Fehlertriage,
finden Sie unter [Updates und Plugins testen](/de/help/testing-updates-plugins).
Release-Prüfungen rufen Package Acceptance mit `source=artifact`, dem vorbereiteten Release-Paketartefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` und `telegram_mode=mock-openai` auf. Dadurch bleiben Paketmigration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Reparatur der Installation konfigurierter Plugins, Offline-Plugin, Plugin-Update und Telegram-Nachweis auf demselben aufgelösten Paket-Tarball. Setzen Sie `package_acceptance_package_spec` in Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Paket statt gegen das SHA-gebaute Artefakt auszuführen. Cross-OS-Release-Prüfungen decken weiterhin betriebssystemspezifisches Onboarding-, Installer- und Plattformverhalten ab; Produktvalidierung für Paket/Update sollte mit Package Acceptance beginnen. Die Docker-Lane `published-upgrade-survivor` validiert pro Run eine veröffentlichte Paketbaseline. In Package Acceptance ist das aufgelöste Tarball `package-under-test` immer der Kandidat, und `published_upgrade_survivor_baseline` wählt die veröffentlichte Fallback-Baseline aus, standardmäßig `openclaw@latest`; Rerun-Befehle für fehlgeschlagene Lanes bewahren diese Baseline. Setzen Sie `published_upgrade_survivor_baselines=all-since-2026.4.23`, um Full Release CI auf jedes stabile npm-Release von `2026.4.23` bis `latest` auszuweiten; `release-history` bleibt für manuelles breiteres Sampling mit dem älteren Vor-Datum-Anker verfügbar. Setzen Sie `published_upgrade_survivor_scenarios=reported-issues`, um dieselben Baselines auf issue-geformte Fixtures für Feishu-Konfiguration, bewahrte Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeitsroots auszuweiten. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn die Frage umfassende Bereinigung veröffentlichter Updates ist, nicht die normale Breite von Full Release CI. Lokale Aggregat-Runs können exakte Paketspezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, eine einzelne Lane mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` wie `openclaw@2026.4.15` behalten oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenariomatrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebetteten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft `/healthz`, `/readyz` sowie den RPC-Status nach dem Gateway-Start. Die Windows-Packaged- und Installer-Fresh-Lanes verifizieren außerdem, dass ein installiertes Paket einen Browser-Control-Override aus einem rohen absoluten Windows-Pfad importieren kann. Der OpenAI-Cross-OS-Agent-Turn-Smoke verwendet standardmäßig `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn gesetzt, andernfalls `openai/gpt-5.4`, sodass der Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleibt und GPT-4.x-Standards vermieden werden.
Release-Prüfungen rufen die Paketakzeptanz mit `source=artifact`, dem vorbereiteten Release-Paketartefakt, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` und `telegram_mode=mock-openai` auf. Dadurch bleiben Paketmigration, Update, Bereinigung veralteter Plugin-Abhängigkeiten, Reparatur installierter konfigurierter Plugins, Offline-Plugin, Plugin-Update und Telegram-Nachweis auf demselben aufgelösten Paket-Tarball. Setzen Sie `package_acceptance_package_spec` in Full Release Validation oder OpenClaw Release Checks, um dieselbe Matrix gegen ein ausgeliefertes npm-Paket statt gegen das aus dem SHA gebaute Artefakt auszuführen. Cross-OS-Release-Prüfungen decken weiterhin OS-spezifisches Onboarding, Installer- und Plattformverhalten ab; Produktvalidierung für Paket/Update sollte mit Paketakzeptanz beginnen. Die Docker-Lane `published-upgrade-survivor` validiert eine veröffentlichte Paket-Baseline pro Run im blockierenden Release-Pfad. In der Paketakzeptanz ist das aufgelöste Tarball `package-under-test` immer der Kandidat, und `published_upgrade_survivor_baseline` wählt die Fallback-Baseline aus veröffentlichten Paketen, standardmäßig `openclaw@latest`; Rerun-Befehle für fehlgeschlagene Lanes bewahren diese Baseline. Full Release Validation mit `run_release_soak=true` oder `release_profile=full` setzt `published_upgrade_survivor_baselines=all-since-2026.4.23` und `published_upgrade_survivor_scenarios=reported-issues`, um über jedes stabile npm-Release von `2026.4.23` bis `latest` sowie issue-förmige Fixtures für Feishu-Konfiguration, bewahrte Bootstrap-/Persona-Dateien, konfigurierte OpenClaw-Plugin-Installationen, Tilde-Logpfade und veraltete Legacy-Plugin-Abhängigkeitswurzeln zu erweitern. Der separate Workflow `Update Migration` verwendet die Docker-Lane `update-migration` mit `all-since-2026.4.23` und `plugin-deps-cleanup`, wenn es um umfassende Bereinigung veröffentlichter Updates geht, nicht um die normale Breite von Full Release CI. Lokale aggregierte Runs können exakte Paketspezifikationen mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` übergeben, mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` eine einzelne Lane beibehalten, etwa `openclaw@2026.4.15`, oder `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` für die Szenario-Matrix setzen. Die veröffentlichte Lane konfiguriert die Baseline mit einem eingebrannten `openclaw config set`-Befehlsrezept, zeichnet Rezeptschritte in `summary.json` auf und prüft `/healthz`, `/readyz` sowie RPC-Status nach dem Gateway-Start. Die frischen Windows-Packaged- und Installer-Lanes prüfen außerdem, dass ein installiertes Paket einen Browser-Control-Override aus einem rohen absoluten Windows-Pfad importieren kann. Der OpenAI-Cross-OS-Agent-Turn-Smoke verwendet standardmäßig `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn gesetzt, andernfalls `openai/gpt-5.4`, sodass der Installations- und Gateway-Nachweis auf einem GPT-5-Testmodell bleibt und GPT-4.x-Standards vermieden werden.
### Legacy-Kompatibilitätsfenster
Package Acceptance hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, dürfen den Kompatibilitätspfad verwenden:
Die Paketakzeptanz hat begrenzte Legacy-Kompatibilitätsfenster für bereits veröffentlichte Pakete. Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, dürfen den Kompatibilitätspfad verwenden:
- bekannte private QA-Einträge in `dist/postinstall-inventory.json` dürfen auf Dateien verweisen, die im Tarball ausgelassen wurden;
- `doctor-switch` darf den Unterfall für die Persistenz von `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht bereitstellt;
- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus dem aus dem Tarball abgeleiteten Fake-Git-Fixture entfernen und darf fehlendes persistiertes `update.channel` protokollieren;
- Plugin-Smokes dürfen Legacy-Install-Record-Speicherorte lesen oder fehlende Persistenz des Marketplace-Install-Records akzeptieren;
- `plugin-update` darf die Migration von Konfigurationsmetadaten zulassen, muss aber weiterhin verlangen, dass Install-Record und No-Reinstall-Verhalten unverändert bleiben.
- `doctor-switch` darf den Unterfall zur Persistenz von `gateway install --wrapper` überspringen, wenn das Paket dieses Flag nicht offenlegt;
- `update-channel-switch` darf fehlende `pnpm.patchedDependencies` aus dem aus dem Tarball abgeleiteten Fake-Git-Fixture entfernen und fehlendes persistiertes `update.channel` protokollieren;
- Plugin-Smokes dürfen Legacy-Install-Record-Speicherorte lesen oder fehlende Marketplace-Install-Record-Persistenz akzeptieren;
- `plugin-update` darf Migration von Konfigurationsmetadaten erlauben, während weiterhin erforderlich bleibt, dass Install-Record und No-Reinstall-Verhalten unverändert bleiben.
Das veröffentlichte Paket `2026.4.26` darf außerdem Warnungen für lokale Build-Metadaten-Stempeldateien ausgeben, die bereits ausgeliefert wurden. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen dann fehl, statt zu warnen oder zu überspringen.
Das veröffentlichte Paket `2026.4.26` darf auch für lokale Build-Metadaten-Stempeldateien warnen, die bereits ausgeliefert wurden. Spätere Pakete müssen die modernen Verträge erfüllen; dieselben Bedingungen schlagen fehl, statt zu warnen oder übersprungen zu werden.
### Beispiele
@ -326,60 +327,60 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Wenn Sie einen fehlgeschlagenen Package-Acceptance-Lauf debuggen, beginnen Sie bei der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und dessen Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasen-Timings und Befehle für erneute Läufe. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, statt die vollständige Release-Validierung erneut auszuführen.
Beginnen Sie beim Debuggen eines fehlgeschlagenen Package-Acceptance-Laufs mit der Zusammenfassung `resolve_package`, um Paketquelle, Version und SHA-256 zu bestätigen. Prüfen Sie anschließend den untergeordneten Lauf `docker_acceptance` und dessen Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`, Lane-Logs, Phasen-Timings und Befehle für erneute Läufe. Führen Sie bevorzugt das fehlgeschlagene Paketprofil oder die exakten Docker-Lanes erneut aus, anstatt die vollständige Release-Validierung neu zu starten.
## Installations-Smoke-Test
## Install-Smoke
Der separate Workflow `Install Smoke` verwendet dasselbe Scope-Skript über seinen eigenen Job `preflight` wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke` auf.
Der separate Workflow `Install Smoke` verwendet dasselbe Scope-Skript über seinen eigenen `preflight`-Job wieder. Er teilt die Smoke-Abdeckung in `run_fast_install_smoke` und `run_full_install_smoke` auf.
- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paket-Oberflächen, Änderungen an Paket/Manifest gebündelter Plugins oder Core-Plugin-/Channel-/Gateway-/Plugin-SDK-Oberflächen berühren, die von den Docker-Smoke-Jobs geprüft werden. Reine Quelländerungen an gebündelten Plugins, reine Teständerungen und reine Dokumentationsänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den CLI-Smoke-Test zum Löschen von Agents im gemeinsam genutzten Arbeitsbereich aus, führt den Container-Gateway-Netzwerk-E2E aus, verifiziert ein Build-Argument für eine gebündelte Erweiterung und führt das begrenzte Docker-Profil für gebündelte Plugins mit einem aggregierten Befehls-Timeout von 240 Sekunden aus (jeder Docker-Lauf eines Szenarios ist separat begrenzt).
- **Vollständiger Pfad** behält die QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtliche geplante Läufe, manuelle Dispatches, Release-Prüfungen per Workflow-Call und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Oberflächen berühren. Im vollständigen Modus bereitet install-smoke ein GHCR-Root-Dockerfile-Smoke-Image für den Ziel-SHA vor oder verwendet es wieder und führt dann QR-Paketinstallation, Root-Dockerfile-/Gateway-Smoke-Tests, Installer-/Update-Smoke-Tests und den schnellen Docker-E2E für gebündelte Plugins als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smoke-Tests warten muss.
- **Schneller Pfad** läuft für Pull Requests, die Docker-/Paket-Surfaces, gebündelte Plugin-Paket-/Manifest-Änderungen oder Core-Plugin-/Channel-/Gateway-/Plugin SDK-Surfaces berühren, die von den Docker-Smoke-Jobs ausgeführt werden. Reine Quelländerungen an gebündelten Plugins, reine Teständerungen und reine Dokumentationsänderungen reservieren keine Docker-Worker. Der schnelle Pfad baut das Root-Dockerfile-Image einmal, prüft die CLI, führt den CLI-Smoke für das Löschen von Agenten im geteilten Workspace aus, führt das Container-Gateway-Netzwerk-E2E aus, verifiziert ein Build-Argument für eine gebündelte Erweiterung und führt das begrenzte Docker-Profil für gebündelte Plugins unter einem aggregierten Befehls-Timeout von 240 Sekunden aus (jeder Docker-Lauf eines Szenarios ist separat begrenzt).
- **Vollständiger Pfad** behält die QR-Paketinstallation sowie Installer-Docker-/Update-Abdeckung für nächtlich geplante Läufe, manuelle Dispatches, Release-Prüfungen per Workflow-Call und Pull Requests bei, die tatsächlich Installer-/Paket-/Docker-Surfaces berühren. Im vollständigen Modus bereitet install-smoke ein GHCR-Root-Dockerfile-Smoke-Image für die Ziel-SHA vor oder verwendet es wieder. Danach führt es QR-Paketinstallation, Root-Dockerfile-/Gateway-Smokes, Installer-/Update-Smokes und das schnelle Docker-E2E für gebündelte Plugins als separate Jobs aus, damit Installer-Arbeit nicht hinter den Root-Image-Smokes warten muss.
`main`-Pushes (einschließlich Merge-Commits) erzwingen nicht den vollständigen Pfad; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke-Test bei und überlässt den vollständigen Installations-Smoke-Test der nächtlichen oder Release-Validierung.
`main`-Pushes (einschließlich Merge-Commits) erzwingen nicht den vollständigen Pfad; wenn die Changed-Scope-Logik bei einem Push vollständige Abdeckung anfordern würde, behält der Workflow den schnellen Docker-Smoke bei und überlässt den vollständigen Install-Smoke der nächtlichen oder Release-Validierung.
Der langsame Bun-Global-Install-Image-Provider-Smoke-Test wird separat durch `run_bun_global_install_smoke` gesteuert. Er läuft im nächtlichen Zeitplan und aus dem Workflow für Release-Prüfungen heraus; manuelle `Install Smoke`-Dispatches können ihn aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen installationsfokussierten Dockerfiles.
Der langsame Bun-Global-Install-Image-Provider-Smoke wird separat durch `run_bun_global_install_smoke` gesteuert. Er läuft im nächtlichen Zeitplan und aus dem Release-Checks-Workflow heraus, und manuelle `Install Smoke`-Dispatches können ihn aktivieren, Pull Requests und `main`-Pushes jedoch nicht. QR- und Installer-Docker-Tests behalten ihre eigenen install-fokussierten Dockerfiles.
## Lokaler Docker-E2E
## Lokales Docker-E2E
`pnpm test:docker:all` baut ein gemeinsam genutztes Live-Test-Image vor, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsam genutzte `scripts/e2e/Dockerfile`-Images:
`pnpm test:docker:all` baut ein gemeinsames Live-Test-Image vor, packt OpenClaw einmal als npm-Tarball und baut zwei gemeinsame Images aus `scripts/e2e/Dockerfile`:
- einen schlanken Node-/Git-Runner für Installer-/Update-/Plugin-Abhängigkeits-Lanes;
- ein funktionales Image, das denselben Tarball für normale Funktionalitäts-Lanes in `/app` installiert.
- einen einfachen Node-/Git-Runner für Installer-/Update-/Plugin-Dependency-Lanes;
- ein funktionsfähiges Image, das denselben Tarball für normale Funktions-Lanes in `/app` installiert.
Docker-Lane-Definitionen befinden sich in `scripts/lib/docker-e2e-scenarios.mjs`, die Planerlogik befindet sich in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt dann Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus.
Docker-Lane-Definitionen liegen in `scripts/lib/docker-e2e-scenarios.mjs`, die Planner-Logik liegt in `scripts/lib/docker-e2e-plan.mjs`, und der Runner führt nur den ausgewählten Plan aus. Der Scheduler wählt das Image pro Lane mit `OPENCLAW_DOCKER_E2E_BARE_IMAGE` und `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` aus und führt die Lanes anschließend mit `OPENCLAW_SKIP_DOCKER_BUILD=1` aus.
### Einstellbare Parameter
| Variable | Standard | Zweck |
| -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Slot-Anzahl des Provider-sensitiven Tail-Pools. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limit für gleichzeitige Live-Lanes, damit Provider nicht drosseln. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limit für gleichzeitige npm-Installations-Lanes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limit für gleichzeitige Multi-Service-Lanes. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Versatz zwischen Lane-Starts, um Docker-Daemon-Create-Spitzen zu vermeiden; `0` deaktiviert ihn. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden engere Grenzen. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Kommagetrennte exakte Lane-Liste; überspringt Cleanup-Smoke, damit Agents eine fehlgeschlagene Lane reproduzieren können. |
| Variable | Standard | Zweck |
| -------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Slot-Anzahl des Haupt-Pools für normale Lanes. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Slot-Anzahl des Provider-sensiblen Tail-Pools. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Begrenzung gleichzeitiger Live-Lanes, damit Provider nicht drosseln. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Begrenzung gleichzeitiger npm-Install-Lanes. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Begrenzung gleichzeitiger Multi-Service-Lanes. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Staffelung zwischen Lane-Starts, um Docker-Daemon-Create-Spitzen zu vermeiden; setzen Sie `0` für keine Staffelung. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Fallback-Timeout pro Lane (120 Minuten); ausgewählte Live-/Tail-Lanes verwenden engere Grenzen. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` gibt den Scheduler-Plan aus, ohne Lanes auszuführen. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Kommagetrennte Liste exakter Lanes; überspringt Cleanup-Smoke, damit Agenten eine fehlgeschlagene Lane reproduzieren können. |
Eine Lane, die schwerer als ihre effektive Grenze ist, kann trotzdem aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale Aggregation prüft Docker vorab, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für eine längste-zuerst-Sortierung und stoppt standardmäßig die Planung neuer gepoolter Lanes nach dem ersten Fehler.
Eine Lane, die schwerer als ihre effektive Grenze ist, kann trotzdem aus einem leeren Pool starten und läuft dann allein, bis sie Kapazität freigibt. Die lokale aggregierte Vorprüfung prüft Docker, entfernt veraltete OpenClaw-E2E-Container, gibt den Status aktiver Lanes aus, persistiert Lane-Timings für Longest-First-Reihenfolge und plant standardmäßig nach dem ersten Fehler keine neuen gepoolten Lanes mehr ein.
### Wiederverwendbarer Live-/E2E-Workflow
Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welche Paket-, Image-Typ-, Live-Image-, Lane- und Credential-Abdeckung erforderlich ist. `scripts/docker-e2e.mjs` wandelt diesen Plan anschließend in GitHub-Ausgaben und Zusammenfassungen um. Er packt OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paket-Artefakt des aktuellen Laufs herunter oder lädt ein Paket-Artefakt aus `package_artifact_run_id`; validiert das Tarball-Inventar; baut und pusht paket-digest-getaggte Bare-/Functional-GHCR-Docker-E2E-Images über Blacksmiths Docker-Layer-Cache, wenn der Plan Lanes mit installiertem Paket benötigt; und verwendet bereitgestellte Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Package-Digest-Images wieder, statt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch erneut versucht, sodass ein festhängender Registry-/Cache-Stream schnell wiederholt wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen.
Der wiederverwendbare Live-/E2E-Workflow fragt `scripts/test-docker-all.mjs --plan-json`, welche Paket-, Image-Art, Live-Image-, Lane- und Credential-Abdeckung erforderlich ist. `scripts/docker-e2e.mjs` wandelt diesen Plan anschließend in GitHub-Ausgaben und Zusammenfassungen um. Es packt OpenClaw entweder über `scripts/package-openclaw-for-docker.mjs`, lädt ein Paketartefakt aus dem aktuellen Lauf herunter oder lädt ein Paketartefakt aus `package_artifact_run_id` herunter; validiert das Tarball-Inventar; baut und pusht Bare-/Functional-GHCR-Docker-E2E-Images mit Paket-Digest-Tags über Blacksmiths Docker-Layer-Cache, wenn der Plan paketinstallierte Lanes benötigt; und verwendet bereitgestellte Eingaben `docker_e2e_bare_image`/`docker_e2e_functional_image` oder vorhandene Paket-Digest-Images wieder, anstatt neu zu bauen. Docker-Image-Pulls werden mit einem begrenzten Timeout von 180 Sekunden pro Versuch wiederholt, damit ein hängender Registry-/Cache-Stream schnell neu versucht wird, statt den Großteil des kritischen CI-Pfads zu verbrauchen.
### Release-Pfad-Chunks
Release-Docker-Abdeckung läuft in kleineren, aufgeteilten Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Chunk nur den benötigten Image-Typ zieht und mehrere Lanes über denselben gewichteten Scheduler ausführt:
Die Release-Docker-Abdeckung läuft in kleineren Chunk-Jobs mit `OPENCLAW_SKIP_DOCKER_BUILD=1`, sodass jeder Chunk nur die benötigte Image-Art zieht und mehrere Lanes über denselben gewichteten Scheduler ausführt:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
Aktuelle Release-Docker-Chunks sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` und `plugins-runtime-install-a` bis `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` und `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliasse. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Rerun-Alias für beide Provider-Installer-Lanes.
Aktuelle Release-Docker-Chunks sind `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` sowie `plugins-runtime-install-a` bis `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` und `plugins-integrations` bleiben aggregierte Plugin-/Runtime-Aliase. Der Lane-Alias `install-e2e` bleibt der aggregierte manuelle Rerun-Alias für beide Provider-Installer-Lanes.
OpenWebUI wird in `plugins-runtime-services` integriert, wenn vollständige Release-Pfad-Abdeckung dies anfordert, und behält nur für reine OpenWebUI-Dispatches einen eigenständigen Chunk `openwebui`. Update-Lanes für gebündelte Channels wiederholen bei vorübergehenden npm-Netzwerkfehlern einmal.
OpenWebUI wird in `plugins-runtime-services` integriert, wenn vollständige Release-Pfad-Abdeckung dies anfordert, und behält einen eigenständigen Chunk `openwebui` nur für OpenWebUI-only-Dispatches. Update-Lanes für gebündelte Channels wiederholen einmal bei vorübergehenden npm-Netzwerkfehlern.
Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Logs, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Befehlen für erneute Läufe pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus, statt die Chunk-Jobs zu verwenden. Dadurch bleibt das Debugging fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt und das Paket-Artefakt für diesen Lauf wird vorbereitet, heruntergeladen oder wiederverwendet; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image lokal für diesen erneuten Lauf. Generierte GitHub-Rerun-Befehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und vorbereitete Image-Eingaben, sofern diese Werte vorhanden sind, sodass eine fehlgeschlagene Lane exakt dasselbe Paket und dieselben Images aus dem fehlgeschlagenen Lauf wiederverwenden kann.
Jeder Chunk lädt `.artifacts/docker-tests/` mit Lane-Logs, Timings, `summary.json`, `failures.json`, Phasen-Timings, Scheduler-Plan-JSON, Tabellen langsamer Lanes und Rerun-Befehlen pro Lane hoch. Die Workflow-Eingabe `docker_lanes` führt ausgewählte Lanes gegen die vorbereiteten Images aus, anstatt die Chunk-Jobs zu verwenden. Dadurch bleibt das Debugging fehlgeschlagener Lanes auf einen gezielten Docker-Job begrenzt und das Paketartefakt für diesen Lauf wird vorbereitet, heruntergeladen oder wiederverwendet; wenn eine ausgewählte Lane eine Live-Docker-Lane ist, baut der gezielte Job das Live-Test-Image lokal für diesen erneuten Lauf. Generierte GitHub-Rerun-Befehle pro Lane enthalten `package_artifact_run_id`, `package_artifact_name` und Eingaben für vorbereitete Images, sofern diese Werte existieren, sodass eine fehlgeschlagene Lane exakt das Paket und die Images aus dem fehlgeschlagenen Lauf wiederverwenden kann.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
@ -388,48 +389,48 @@ pnpm test:docker:timings <summary> # slow-lane and phase critical-path summari
Der geplante Live-/E2E-Workflow führt die vollständige Release-Pfad-Docker-Suite täglich aus.
## Plugin Prerelease
## Plugin-Prerelease
`Plugin Prerelease` ist eine aufwendigere Produkt-/Paket-Abdeckung und daher ein separater Workflow, der von `Full Release Validation` oder einem expliziten Operator ausgelöst wird. Normale Pull Requests, `main`-Pushes und eigenständige manuelle CI-Dispatches lassen diese Suite deaktiviert. Er balanciert Tests gebündelter Plugins über acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap aus, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der nur für Releases vorgesehene Docker-Prerelease-Pfad bündelt gezielte Docker-Lanes in kleinen Gruppen, um nicht Dutzende Runner für ein- bis dreiminütige Jobs zu reservieren.
`Plugin Prerelease` ist aufwendigere Produkt-/Paket-Abdeckung und daher ein separater Workflow, der durch `Full Release Validation` oder explizit durch einen Operator ausgelöst wird. Normale Pull Requests, `main`-Pushes und eigenständige manuelle CI-Dispatches lassen diese Suite ausgeschaltet. Er verteilt Tests für gebündelte Plugins auf acht Erweiterungs-Worker; diese Erweiterungs-Shard-Jobs führen bis zu zwei Plugin-Konfigurationsgruppen gleichzeitig mit einem Vitest-Worker pro Gruppe und einem größeren Node-Heap aus, damit importlastige Plugin-Batches keine zusätzlichen CI-Jobs erzeugen. Der release-only Docker-Prerelease-Pfad bündelt gezielte Docker-Lanes in kleinen Gruppen, um nicht Dutzende Runner für Jobs von ein bis drei Minuten zu reservieren.
## QA Lab
QA Lab verfügt über dedizierte CI-Lanes außerhalb des hauptsächlichen Smart-Scoped-Workflows. Agentische Parität ist unter den breiten QA- und Release-Harnessen verschachtelt, nicht als eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität mit einem breiten Validierungslauf mitlaufen soll.
QA Lab hat dedizierte CI-Lanes außerhalb des smart gescopten Haupt-Workflows. Agentische Parität ist unter den breiten QA- und Release-Harnesses verschachtelt, nicht als eigenständiger PR-Workflow. Verwenden Sie `Full Release Validation` mit `rerun_group=qa-parity`, wenn Parität zusammen mit einem breiten Validierungslauf laufen soll.
- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Paritäts-Lane, die Live-Matrix-Lane sowie die Live-Telegram- und Live-Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases.
- Der Workflow `QA-Lab - All Lanes` läuft nächtlich auf `main` und bei manuellem Dispatch; er fächert die Mock-Parity-Lane, die Live-Matrix-Lane sowie die Live-Telegram- und Discord-Lanes als parallele Jobs auf. Live-Jobs verwenden die Umgebung `qa-live-shared`, und Telegram/Discord verwenden Convex-Leases.
Release-Prüfungen führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, sodass der Channel-Vertrag von Live-Modelllatenz und normalem Provider-Plugin-Start isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, weil QA-Parität das Speicherverhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Live-Modell-, nativen Provider- und Docker-Provider-Suites abgedeckt.
Release-Prüfungen führen Matrix- und Telegram-Live-Transport-Lanes mit dem deterministischen Mock-Provider und mock-qualifizierten Modellen (`mock-openai/gpt-5.5` und `mock-openai/gpt-5.5-alt`) aus, damit der Channel-Vertrag von Live-Modell-Latenz und normalem Provider-Plugin-Start isoliert ist. Das Live-Transport-Gateway deaktiviert die Speichersuche, weil QA-Parität Speicherverhalten separat abdeckt; Provider-Konnektivität wird durch die separaten Live-Modell-, Native-Provider- und Docker-Provider-Suites abgedeckt.
Matrix verwendet `--profile fast` für geplante und Release-Gates und fügt `--fail-fast` nur hinzu, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standardwert und die manuelle Workflow-Eingabe bleiben `all`; manueller Dispatch mit `matrix_profile=all` shardet die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`.
Matrix verwendet `--profile fast` für geplante und Release-Gates und fügt `--fail-fast` nur hinzu, wenn die ausgecheckte CLI dies unterstützt. Der CLI-Standard und die manuelle Workflow-Eingabe bleiben `all`; ein manueller Dispatch mit `matrix_profile=all` shardet die vollständige Matrix-Abdeckung immer in die Jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` und `e2ee-cli`.
`OpenClaw Release Checks` führt außerdem die release-kritischen QA-Lab-Lanes vor der Release-Genehmigung aus; sein QA-Paritäts-Gate führt Kandidaten- und Baseline-Pakete als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Berichtsjob für den abschließenden Paritätsvergleich herunter.
`OpenClaw Release Checks` führt vor der Release-Freigabe außerdem die releasekritischen QA-Lab-Lanes aus; das QA-Parity-Gate führt Kandidaten- und Baseline-Packs als parallele Lane-Jobs aus und lädt anschließend beide Artefakte in einen kleinen Report-Job für den finalen Paritätsvergleich herunter.
Für normale PRs folgen Sie gescopter CI-/Check-Evidenz, statt Parität als erforderlichen Status zu behandeln.
Folgen Sie bei normalen PRs gescopten CI-/Check-Nachweisen, anstatt Parität als erforderlichen Status zu behandeln.
## CodeQL
Der `CodeQL`-Workflow ist bewusst ein schmaler Sicherheits-Scan im ersten Durchlauf, nicht der vollständige Repository-Durchlauf. Tägliche, manuelle und nicht als Entwurf markierte Pull-Request-Guard-Läufe scannen Actions-Workflow-Code plus die JavaScript-/TypeScript-Oberflächen mit dem höchsten Risiko mit hochzuverlässigen Sicherheitsabfragen, gefiltert auf hohe/kritische `security-severity`.
Der `CodeQL`-Workflow ist bewusst ein schmaler Sicherheitsscanner für den ersten Durchlauf, kein vollständiger Repository-Sweep. Tägliche, manuelle und Guard-Läufe für nicht als Draft markierte Pull Requests scannen Actions-Workflow-Code sowie die risikoreichsten JavaScript/TypeScript-Oberflächen mit hochzuverlässigen Sicherheitsabfragen, gefiltert auf hohe/kritische `security-severity`.
Der Pull-Request-Guard bleibt schlank: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src`, und er führt dieselbe hochzuverlässige Sicherheitsmatrix aus wie der geplante Workflow. Android- und macOS-CodeQL bleiben außerhalb der PR-Standardeinstellungen.
Der Pull-Request-Guard bleibt leichtgewichtig: Er startet nur bei Änderungen unter `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` oder `src` und führt dieselbe hochzuverlässige Sicherheitsmatrix wie der geplante Workflow aus. Android- und macOS-CodeQL bleiben außerhalb der PR-Standards.
### Sicherheitskategorien
| Kategorie | Oberfläche |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Gateway-Baseline |
| `/codeql-security-high/channel-runtime-boundary` | Implementierungsverträge des Core-Kanals plus Channel-Plugin-Laufzeit, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte |
| `/codeql-security-high/network-ssrf-boundary` | Core-SSRF, IP-Parsing, Netzwerk-Guard, Web-Fetch und SSRF-Richtlinienoberflächen des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfsfunktionen zur Prozessausführung, ausgehende Zustellung und Gates für die Tool-Ausführung von Agenten |
| `/codeql-security-high/plugin-trust-boundary` | Plugin-Installation, Loader, Manifest, Registry, Package-Manager-Installation, Source-Loading und Vertrauensoberflächen des Plugin-SDK-Paketvertrags |
| Kategorie | Oberfläche |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, Secrets, Sandbox, Cron und Gateway-Baseline |
| `/codeql-security-high/channel-runtime-boundary` | Kernverträge der Channel-Implementierung plus Channel-Plugin-Runtime, Gateway, Plugin SDK, Secrets, Audit-Berührungspunkte |
| `/codeql-security-high/network-ssrf-boundary` | Kernoberflächen für SSRF, IP-Parsing, Netzwerk-Guard, Web-Fetch und SSRF-Richtlinien des Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP-Server, Hilfsfunktionen für Prozessausführung, ausgehende Zustellung und Gates für Agent-Tool-Ausführung |
| `/codeql-security-high/plugin-trust-boundary` | Vertrauensoberflächen für Plugin-Installation, Loader, Manifest, Registry, Package-Manager-Installation, Source-Loading und Plugin-SDK-Package-Vertrag |
### Plattformspezifische Sicherheits-Shards
- `CodeQL Android Critical Security` — geplanter Android-Sicherheits-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, der von der Workflow-Sanity-Prüfung akzeptiert wird. Lädt unter `/codeql-critical-security/android` hoch.
- `CodeQL macOS Critical Security` — wöchentlicher/manueller macOS-Sicherheits-Shard. Baut die macOS-App manuell für CodeQL auf Blacksmith macOS, filtert Build-Ergebnisse von Abhängigkeiten aus der hochgeladenen SARIF-Datei heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standardeinstellungen, weil der macOS-Build die Laufzeit auch im sauberen Zustand dominiert.
- `CodeQL Android Critical Security` — geplanter Android-Sicherheits-Shard. Baut die Android-App manuell für CodeQL auf dem kleinsten Blacksmith-Linux-Runner, den die Workflow-Sanity akzeptiert. Lädt unter `/codeql-critical-security/android` hoch.
- `CodeQL macOS Critical Security` — wöchentlicher/manueller macOS-Sicherheits-Shard. Baut die macOS-App manuell für CodeQL auf Blacksmith macOS, filtert Dependency-Build-Ergebnisse aus dem hochgeladenen SARIF heraus und lädt unter `/codeql-critical-security/macos` hoch. Bleibt außerhalb der täglichen Standards, weil der macOS-Build die Laufzeit auch bei sauberem Ergebnis dominiert.
### Critical-Quality-Kategorien
### Kategorien für kritische Qualität
`CodeQL Critical Quality` ist der passende nicht sicherheitsbezogene Shard. Er führt nur JavaScript-/TypeScript-Qualitätsabfragen mit Error-Schweregrad und ohne Sicherheitsbezug über schmale, hochwertige Oberflächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist bewusst kleiner als das geplante Profil: Nicht als Entwurf markierte PRs führen nur die passenden Shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` und `plugin-sdk-reply-runtime` für Änderungen an Agent-Befehls-/Modell-/Tool-Ausführung und Antwort-Dispatch-Code, Konfigurationsschema-/Migrations-/IO-Code, Authentifizierungs-/Secrets-/Sandbox-/Sicherheitscode, Core-Kanal- und gebündelter Channel-Plugin-Laufzeit, Gateway-Protokoll-/Server-Methoden, Memory-Laufzeit-/SDK-Verbindungscode, MCP-/Prozess-/ausgehender Zustellung, Provider-Laufzeit-/Modellkatalog, Sitzungsdiagnose-/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Paketvertrag oder Plugin-SDK-Antwortlaufzeit aus. Änderungen an CodeQL-Konfiguration und Qualitäts-Workflow führen alle zwölf PR-Quality-Shards aus.
`CodeQL Critical Quality` ist der entsprechende Nicht-Sicherheits-Shard. Er führt nur JavaScript/TypeScript-Qualitätsabfragen mit Fehler-Schweregrad und ohne Sicherheitsbezug über schmale, hochwertige Oberflächen auf dem kleineren Blacksmith-Linux-Runner aus. Sein Pull-Request-Guard ist bewusst kleiner als das geplante Profil: Nicht-Draft-PRs führen nur die passenden Shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` und `plugin-sdk-reply-runtime` für Agent-Befehls-/Modell-/Tool-Ausführung und Antwort-Dispatch-Code, Config-Schema-/Migration-/IO-Code, Auth-/Secrets-/Sandbox-/Sicherheitscode, Kern-Channel- und gebündelte Channel-Plugin-Runtime, Gateway-Protokoll-/Server-Methoden, Memory-Runtime-/SDK-Verknüpfung, MCP-/Prozess-/ausgehende Zustellung, Provider-Runtime-/Modellkatalog, Sitzungsdiagnosen/Zustellungswarteschlangen, Plugin-Loader, Plugin-SDK-/Package-Vertrag oder Plugin-SDK-Antwort-Runtime-Änderungen aus. Änderungen an CodeQL-Konfiguration und Qualitätsworkflow führen alle zwölf PR-Qualitäts-Shards aus.
Manueller Dispatch akzeptiert:
@ -437,40 +438,40 @@ Manueller Dispatch akzeptiert:
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
Die schmalen Profile sind Lehr-/Iterations-Hooks, um einen Qualitäts-Shard isoliert auszuführen.
Die schmalen Profile sind Hooks für Schulung und Iteration, um einen Qualitäts-Shard isoliert auszuführen.
| Kategorie | Oberfläche |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Authentifizierung, Secrets, Sandbox, Cron und Code der Gateway-Sicherheitsgrenze |
| `/codeql-critical-quality/config-boundary` | Konfigurationsschema, Migration, Normalisierung und IO-Verträge |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemata und Server-Methodenverträge |
| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge für Core-Kanal und gebündeltes Channel-Plugin |
| `/codeql-critical-quality/agent-runtime-boundary` | Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie ACP-Control-Plane-Laufzeitverträge |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Hilfsfunktionen zur Prozessüberwachung und Verträge für ausgehende Zustellung |
| `/codeql-critical-quality/memory-runtime-boundary` | Memory Host SDK, Memory-Laufzeitfassaden, Memory-Plugin-SDK-Aliasse, Verbindungscode zur Aktivierung der Memory-Laufzeit und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Antwortwarteschlange, Sitzungszustellungswarteschlangen, Hilfsfunktionen für ausgehende Sitzungsbindung/-zustellung, Diagnoseereignis-/Log-Bundle-Oberflächen und CLI-Verträge des Sitzungs-Doctor |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Eingehender Antwort-Dispatch des Plugin SDK, Antwort-Payload-/Chunking-/Laufzeit-Hilfsfunktionen, Channel-Antwortoptionen, Zustellungswarteschlangen und Hilfsfunktionen zur Sitzungs-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisierung des Modellkatalogs, Provider-Authentifizierung und -Discovery, Provider-Laufzeitregistrierung, Provider-Standardeinstellungen/-Kataloge sowie Web-/Search-/Fetch-/Embedding-Registries |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap der Control UI, lokale Persistenz, Gateway-Control-Flows und Task-Control-Plane-Laufzeitverträge |
| `/codeql-critical-quality/web-media-runtime-boundary` | Core-Web-Fetch/Search, Medien-IO, Medienverständnis, Bildgenerierung und Laufzeitverträge für Mediengenerierung |
| `/codeql-critical-quality/plugin-boundary` | Loader-, Registry-, Public-Surface- und Plugin-SDK-Entrypoint-Verträge |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichter paketbasierter Plugin-SDK-Quellcode und Hilfsfunktionen für Plugin-Paketverträge |
| Kategorie | Oberfläche |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Code für Auth, Secrets, Sandbox, Cron und Gateway-Sicherheitsgrenzen |
| `/codeql-critical-quality/config-boundary` | Verträge für Config-Schema, Migration, Normalisierung und IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Gateway-Protokollschemas und Verträge für Server-Methoden |
| `/codeql-critical-quality/channel-runtime-boundary` | Implementierungsverträge für Kern-Channel und gebündelte Channel-Plugins |
| `/codeql-critical-quality/agent-runtime-boundary` | Laufzeitverträge für Befehlsausführung, Modell-/Provider-Dispatch, Auto-Reply-Dispatch und Warteschlangen sowie ACP-Control-Plane |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-Server und Tool-Bridges, Hilfsfunktionen zur Prozessüberwachung und Verträge für ausgehende Zustellung |
| `/codeql-critical-quality/memory-runtime-boundary` | Memory Host SDK, Memory-Runtime-Fassaden, Memory-Plugin-SDK-Aliase, Verknüpfung zur Aktivierung der Memory-Runtime und Memory-Doctor-Befehle |
| `/codeql-critical-quality/session-diagnostics-boundary` | Interna der Antwortwarteschlange, Sitzungs-Zustellungswarteschlangen, Hilfsfunktionen für ausgehende Sitzungsbindung/-zustellung, Diagnoseereignis-/Log-Bundle-Oberflächen und Sitzungs-Doctor-CLI-Verträge |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Eingehender Antwort-Dispatch des Plugin SDK, Antwort-Payload-/Chunking-/Runtime-Hilfsfunktionen, Channel-Antwortoptionen, Zustellungswarteschlangen und Hilfsfunktionen für Sitzungs-/Thread-Bindung |
| `/codeql-critical-quality/provider-runtime-boundary` | Modellkatalog-Normalisierung, Provider-Auth und -Discovery, Provider-Runtime-Registrierung, Provider-Standards/-Kataloge sowie Web-/Search-/Fetch-/Embedding-Registries |
| `/codeql-critical-quality/ui-control-plane` | Control-UI-Bootstrap, lokale Persistenz, Gateway-Control-Flows und Laufzeitverträge der Task-Control-Plane |
| `/codeql-critical-quality/web-media-runtime-boundary` | Laufzeitverträge für Kern-Web-Fetch/-Search, Media-IO, Media Understanding, Bildgenerierung und Mediengenerierung |
| `/codeql-critical-quality/plugin-boundary` | Verträge für Loader, Registry, öffentliche Oberfläche und Plugin-SDK-Entrypoints |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Veröffentlichter package-seitiger Plugin-SDK-Source und Hilfsfunktionen für Plugin-Package-Verträge |
Quality bleibt von Security getrennt, damit Quality-Befunde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Security-Signal zu verdecken. Die Erweiterung von CodeQL für Swift, Python und gebündelte Plugins sollte erst wieder als eingegrenzte oder geshardete Folgearbeit hinzugefügt werden, nachdem die schmalen Profile stabile Laufzeit und stabile Signale haben.
Qualität bleibt von Sicherheit getrennt, damit Qualitätsbefunde geplant, gemessen, deaktiviert oder erweitert werden können, ohne das Sicherheitssignal zu verdecken. Swift-, Python- und gebündelte-Plugin-CodeQL-Erweiterungen sollten erst wieder als nachgelagerte, scoped oder geshardete Arbeit hinzugefügt werden, nachdem die schmalen Profile stabile Laufzeit und stabiles Signal haben.
## Wartungs-Workflows
## Wartungsworkflows
### Docs Agent
Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur, um bestehende Dokumentation mit kürzlich gelandeten Änderungen abzugleichen. Er hat keinen reinen Zeitplan: Ein erfolgreicher nicht von Bots stammender Push-CI-Lauf auf `main` kann ihn auslösen, und manueller Dispatch kann ihn direkt ausführen. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergewandert ist oder wenn in der letzten Stunde ein anderer nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er läuft, überprüft er den Commit-Bereich von der vorherigen nicht übersprungenen Docs-Agent-Quell-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle seit dem letzten Dokumentationsdurchlauf angesammelten Main-Änderungen abdecken kann.
Der `Docs Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur, um bestehende Dokumentation an kürzlich gelandete Änderungen anzupassen. Er hat keinen reinen Zeitplan: Ein erfolgreicher, nicht von einem Bot stammender Push-CI-Lauf auf `main` kann ihn auslösen, und manueller Dispatch kann ihn direkt ausführen. Workflow-Run-Aufrufe werden übersprungen, wenn `main` weitergewandert ist oder wenn in der letzten Stunde ein anderer nicht übersprungener Docs-Agent-Lauf erstellt wurde. Wenn er läuft, prüft er den Commit-Bereich von der vorherigen nicht übersprungenen Docs-Agent-Quell-SHA bis zum aktuellen `main`, sodass ein stündlicher Lauf alle Main-Änderungen abdecken kann, die seit dem letzten Dokumentationsdurchlauf aufgelaufen sind.
### Test Performance Agent
Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher nicht von Bots stammender Push-CI-Lauf auf `main` kann ihn auslösen, aber er wird übersprungen, wenn an diesem UTC-Tag bereits ein anderer Workflow-Run-Aufruf gelaufen ist oder gerade läuft. Manueller Dispatch umgeht dieses tägliche Aktivitäts-Gate. Die Spur erstellt einen gruppierten Vitest-Performance-Bericht für die vollständige Suite, lässt Codex nur kleine, die Abdeckung erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt anschließend den Bericht für die vollständige Suite erneut aus und verwirft Änderungen, die die Baseline-Anzahl bestandener Tests verringern. Wenn die Baseline fehlschlagende Tests enthält, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Bericht nach dem Agenten muss bestehen, bevor etwas committet wird. Wenn `main` vor dem Bot-Push weiterläuft, rebaset die Spur den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; kollidierende veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitshaltung wie der Docs Agent beibehalten kann.
Der `Test Performance Agent`-Workflow ist eine ereignisgesteuerte Codex-Wartungsspur für langsame Tests. Er hat keinen reinen Zeitplan: Ein erfolgreicher, nicht von einem Bot stammender Push-CI-Lauf auf `main` kann ihn auslösen, aber er wird übersprungen, wenn an diesem UTC-Tag bereits ein anderer Workflow-Run-Aufruf gelaufen ist oder läuft. Manueller Dispatch umgeht dieses tägliche Aktivitäts-Gate. Die Spur erstellt einen gruppierten Vitest-Performance-Report für die vollständige Suite, lässt Codex nur kleine, coverage-erhaltende Test-Performance-Fixes statt breiter Refactorings vornehmen, führt den Full-Suite-Report danach erneut aus und weist Änderungen zurück, die die bestehende Anzahl bestandener Baseline-Tests reduzieren. Wenn die Baseline fehlgeschlagene Tests hat, darf Codex nur offensichtliche Fehler beheben, und der Full-Suite-Report nach dem Agent muss bestehen, bevor etwas committet wird. Wenn `main` weiterläuft, bevor der Bot-Push landet, rebased die Spur den validierten Patch, führt `pnpm check:changed` erneut aus und versucht den Push erneut; widersprüchliche veraltete Patches werden übersprungen. Sie verwendet GitHub-gehostetes Ubuntu, damit die Codex-Action dieselbe Drop-Sudo-Sicherheitsposition wie der Docs Agent beibehalten kann.
### Duplicate PRs After Merge
### Doppelte PRs nach Merge
Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow für die Bereinigung von Duplikaten nach dem Landen. Er verwendet standardmäßig Dry-Run und schließt nur explizit aufgelistete PRs, wenn `apply=true` gesetzt ist. Vor Änderungen an GitHub überprüft er, dass der gelandete PR gemergt ist und dass jedes Duplikat entweder ein gemeinsam referenziertes Issue oder überlappende geänderte Hunks hat.
Der `Duplicate PRs After Merge`-Workflow ist ein manueller Maintainer-Workflow für die Bereinigung von Duplikaten nach dem Landen. Standardmäßig läuft er als Dry-Run und schließt nur explizit aufgeführte PRs, wenn `apply=true` ist. Bevor GitHub mutiert wird, prüft er, dass der gelandete PR gemergt ist und dass jedes Duplikat entweder ein gemeinsames referenziertes Issue oder überlappende geänderte Hunks hat.
```bash
gh workflow run duplicate-after-merge.yml \
@ -483,33 +484,33 @@ gh workflow run duplicate-after-merge.yml \
Die lokale Changed-Lane-Logik liegt in `scripts/changed-lanes.mjs` und wird von `scripts/check-changed.mjs` ausgeführt. Dieses lokale Check-Gate ist bei Architekturgrenzen strenger als der breite CI-Plattformumfang:
- Änderungen an Core-Produktionscode führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/-Guards aus;
- Änderungen nur an Core-Tests führen nur Core-Test-Typecheck plus Core-Lint aus;
- Änderungen an Extension-Produktionscode führen Extension-Prod- und Extension-Test-Typecheck plus Extension-Lint aus;
- Änderungen nur an Extension-Tests führen Extension-Test-Typecheck plus Extension-Lint aus;
- Änderungen am öffentlichen Plugin SDK oder an Plugin-Contracts erweitern auf Extension-Typecheck, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit);
- Release-Metadaten-only-Version-Bumps führen gezielte Versions-/Konfigurations-/Root-Abhängigkeitsprüfungen aus;
- unbekannte Root-/Konfigurationsänderungen fallen sicherheitshalber auf alle Check-Lanes zurück.
- Änderungen an Core-Production führen Core-Prod- und Core-Test-Typecheck plus Core-Lint/Guards aus;
- reine Core-Test-Änderungen führen nur Core-Test-Typecheck plus Core-Lint aus;
- Änderungen an Extension-Production führen Extension-Prod- und Extension-Test-Typecheck plus Extension-Lint aus;
- reine Extension-Test-Änderungen führen Extension-Test-Typecheck plus Extension-Lint aus;
- Änderungen am öffentlichen Plugin SDK oder Plugin-Vertrag erweitern auf Extension-Typecheck, weil Extensions von diesen Core-Verträgen abhängen (Vitest-Extension-Sweeps bleiben explizite Testarbeit);
- Release-Metadata-only-Versionsbumps führen gezielte Versions-/Config-/Root-Dependency-Checks aus;
- unbekannte Root-/Config-Änderungen fallen sicherheitshalber auf alle Check-Lanes zurück.
Das lokale Changed-Test-Routing liegt in `scripts/test-projects.test-support.mjs` und ist bewusst günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Quellcodeänderungen bevorzugen explizite Mappings, danach gleichgeordnete Tests und Import-Graph-Abhängige. Die gemeinsame Group-Room-Zustellungskonfiguration ist eines der expliziten Mappings: Änderungen an der für Gruppen sichtbaren Antwortkonfiguration, am Quell-Antwortzustellungsmodus oder am System-Prompt des Message-Tools laufen über die Core-Antworttests plus Discord- und Slack-Zustellungsregressionen, damit eine gemeinsame Standardänderung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung so harness-weit ist, dass die günstige gemappte Menge kein vertrauenswürdiger Proxy ist.
Lokales Changed-Test-Routing liegt in `scripts/test-projects.test-support.mjs` und ist bewusst günstiger als `check:changed`: Direkte Teständerungen führen sich selbst aus, Source-Änderungen bevorzugen explizite Mappings, danach Sibling-Tests und Import-Graph-Dependents. Shared-Group-Room-Delivery-Config ist eines der expliziten Mappings: Änderungen an der Config für gruppensichtbare Antworten, am Source-Reply-Delivery-Modus oder an der System-Prompt-Route des Message-Tools laufen über die Core-Reply-Tests plus Discord- und Slack-Zustellungsregressionen, damit eine gemeinsame Standardänderung vor dem ersten PR-Push fehlschlägt. Verwenden Sie `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` nur, wenn die Änderung harness-weit genug ist, dass das günstige gemappte Set kein vertrauenswürdiger Proxy ist.
## Testbox-Validierung
Führen Sie Testbox aus dem Repo-Root aus und bevorzugen Sie für breiten Nachweis eine frisch vorgewärmte Box. Bevor Sie eine langsame Gate-Prüfung auf einer Box ausführen, die wiederverwendet wurde, abgelaufen ist oder gerade eine unerwartet große Synchronisierung gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` in der Box aus.
Führen Sie Testbox vom Repo-Root aus aus, und bevorzugen Sie für breit angelegten Nachweis eine frisch vorgewärmte Box. Bevor Sie ein langsames Gate auf einer Box ausführen, die wiederverwendet wurde, abgelaufen ist oder gerade eine unerwartet große Synchronisierung gemeldet hat, führen Sie zuerst `pnpm testbox:sanity` innerhalb der Box aus.
Die Sanity-Prüfung schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 nachverfolgte Löschungen anzeigt. Das bedeutet normalerweise, dass der Remote-Sync-Zustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie stattdessen eine frische vor, anstatt den Produkttestfehler zu debuggen. Für absichtliche PRs mit vielen Löschungen setzen Sie für diesen Sanity-Lauf `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1`.
Die Plausibilitätsprüfung schlägt schnell fehl, wenn erforderliche Root-Dateien wie `pnpm-lock.yaml` verschwunden sind oder wenn `git status --short` mindestens 200 nachverfolgte Löschungen zeigt. Das bedeutet normalerweise, dass der entfernte Synchronisierungszustand keine vertrauenswürdige Kopie des PR ist; stoppen Sie diese Box und wärmen Sie stattdessen eine frische auf, anstatt den Produkttestfehler zu debuggen. Setzen Sie für PRs mit beabsichtigten großen Löschungen `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` für diesen Plausibilitätslauf.
`pnpm testbox:run` beendet außerdem einen lokalen Blacksmith-CLI-Aufruf, der länger als fünf Minuten ohne Ausgabe nach der Synchronisierung in der Sync-Phase bleibt. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diesen Schutz zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs.
`pnpm testbox:run` beendet außerdem einen lokalen Blacksmith-CLI-Aufruf, der länger als fünf Minuten ohne Ausgabe nach der Synchronisierung in der Synchronisierungsphase bleibt. Setzen Sie `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, um diese Schutzmaßnahme zu deaktivieren, oder verwenden Sie einen größeren Millisekundenwert für ungewöhnlich große lokale Diffs.
Crabbox ist der repo-eigene Remote-Box-Wrapper für Linux-Nachweise durch Maintainer. Verwenden Sie ihn, wenn eine Prüfung zu breit für einen lokalen Bearbeitungs-Loop ist, wenn CI-Parität wichtig ist oder wenn der Nachweis Secrets, Docker, Paket-Lanes, wiederverwendbare Boxen oder Remote-Logs benötigt. Das normale OpenClaw-Backend ist `blacksmith-testbox`; eigene AWS/Hetzner-Kapazität ist ein Fallback für Blacksmith-Ausfälle, Quotenprobleme oder explizite Tests mit eigener Kapazität.
Crabbox ist der repo-eigene Remote-Box-Wrapper für Linux-Nachweise durch Maintainer. Verwenden Sie ihn, wenn eine Prüfung zu breit für einen lokalen Bearbeitungszyklus ist, wenn CI-Parität wichtig ist oder wenn der Nachweis Secrets, Docker, Paket-Lanes, wiederverwendbare Boxen oder Remote-Logs benötigt. Das normale OpenClaw-Backend ist `blacksmith-testbox`; eigene AWS/Hetzner-Kapazität ist ein Fallback für Blacksmith-Ausfälle, Kontingentprobleme oder explizite Tests mit eigener Kapazität.
Prüfen Sie vor einem ersten Lauf den Wrapper aus dem Repo-Root:
Prüfen Sie den Wrapper vor dem ersten Lauf vom Repo-Root aus:
```bash
pnpm crabbox:run -- --help | sed -n '1,120p'
```
Der Repo-Wrapper verweigert eine veraltete Crabbox-Binärdatei, die `blacksmith-testbox` nicht ausweist. Geben Sie den Provider explizit an, obwohl `.crabbox.yaml` Standardwerte für die eigene Cloud enthält.
Der Repo-Wrapper lehnt eine veraltete Crabbox-Binärdatei ab, die `blacksmith-testbox` nicht ausweist. Übergeben Sie den Provider explizit, auch wenn `.crabbox.yaml` Defaults für die eigene Cloud enthält.
Changed-Gate:
@ -526,7 +527,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
```
Fokussierte Testwiederholung:
Fokussierter Test-Wiederholungslauf:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
@ -556,14 +557,14 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
```
Lesen Sie die abschließende JSON-Zusammenfassung. Die nützlichen Felder sind `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` und `totalMs`. Einmalige Blacksmith-gestützte Crabbox-Läufe sollten die Testbox automatisch stoppen; wenn ein Lauf unterbrochen wurde oder die Bereinigung unklar ist, prüfen Sie die Live-Boxen und stoppen Sie nur die Boxen, die Sie erstellt haben:
Lesen Sie die abschließende JSON-Zusammenfassung. Die nützlichen Felder sind `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` und `totalMs`. Einmalige Crabbox-Läufe mit Blacksmith-Unterstützung sollten die Testbox automatisch stoppen; wenn ein Lauf unterbrochen wird oder die Bereinigung unklar ist, prüfen Sie die Live-Boxen und stoppen Sie nur die Boxen, die Sie erstellt haben:
```bash
blacksmith testbox list
blacksmith testbox stop --id <tbx_id>
```
Verwenden Sie Wiederverwendung nur, wenn Sie absichtlich mehrere Befehle auf derselben hydratisierten Box benötigen:
Verwenden Sie Wiederverwendung nur, wenn Sie absichtlich mehrere Befehle auf derselben hydrierten Box benötigen:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
@ -578,7 +579,7 @@ blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_id>
```
Eskalieren Sie nur dann auf eigene Crabbox-Kapazität, wenn Blacksmith ausgefallen, durch Quoten begrenzt oder ohne die benötigte Umgebung ist oder wenn eigene Kapazität explizit das Ziel ist:
Eskalieren Sie nur dann auf eigene Crabbox-Kapazität, wenn Blacksmith ausgefallen ist, durch Kontingente eingeschränkt wird, die benötigte Umgebung fehlt oder eigene Kapazität ausdrücklich das Ziel ist:
```bash
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
@ -587,9 +588,9 @@ pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` verwaltet die Standardwerte für Provider, Synchronisierung und GitHub-Actions-Hydratisierung für eigene Cloud-Lanes. Sie schließt lokales `.git` aus, damit der hydratisierte Actions-Checkout seine eigenen Remote-Git-Metadaten behält, anstatt maintainer-lokale Remotes und Objektspeicher zu synchronisieren, und sie schließt lokale Laufzeit-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` verwaltet Checkout, Node-/pnpm-Einrichtung, `origin/main`-Fetch und die nicht geheime Umgebungsübergabe für eigene Cloud-Befehle vom Typ `crabbox run --id <cbx_id>`.
`.crabbox.yaml` besitzt die Defaults für Provider, Synchronisierung und GitHub-Actions-Hydrierung für Lanes der eigenen Cloud. Sie schließt lokales `.git` aus, damit der hydrierte Actions-Checkout seine eigenen entfernten Git-Metadaten behält, statt maintainer-lokale Remotes und Objektspeicher zu synchronisieren, und sie schließt lokale Laufzeit-/Build-Artefakte aus, die niemals übertragen werden sollten. `.github/workflows/crabbox-hydrate.yml` besitzt Checkout, Node/pnpm-Einrichtung, `origin/main`-Abruf und die nicht geheime Umgebungsübergabe für eigene Cloud-Befehle vom Typ `crabbox run --id <cbx_id>`.
## Verwandt
## Verwandte Themen
- [Installationsübersicht](/de/install)
- [Entwicklungskanäle](/de/install/development-channels)

28
docs/de/cli/dashboard.md
View File

@ -2,15 +2,15 @@
read_when:
- Sie möchten die Control UI mit Ihrem aktuellen Token öffnen
- Sie möchten die URL ausgeben, ohne einen Browser zu starten
summary: CLI-Referenz für `openclaw dashboard` (die Control UI öffnen)
title: Dashboard
summary: CLI-Referenz für `openclaw dashboard` (die Steuerungs-UI öffnen)
title: Übersicht
x-i18n:
generated_at: "2026-04-25T13:43:30Z"
model: gpt-5.4
generated_at: "2026-05-05T01:44:21Z"
model: gpt-5.5
provider: openai
source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c
source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f
source_path: cli/dashboard.md
workflow: 15
workflow: 16
---
# `openclaw dashboard`
@ -24,13 +24,17 @@ openclaw dashboard --no-open
Hinweise:
- `dashboard` löst konfigurierte SecretRefs für `gateway.auth.token` nach Möglichkeit auf.
- `dashboard` folgt `gateway.tls.enabled`: Bei TLS-aktivierten Gateways werden
`https://`-Control-UI-URLs ausgegeben/geöffnet und die Verbindung erfolgt über `wss://`.
- Für SecretRef-verwaltete Tokens (aufgelöst oder nicht aufgelöst) gibt/kopiert/öffnet `dashboard` eine URL ohne Token, um zu vermeiden, dass externe Geheimnisse in Terminalausgaben, der Zwischenablagehistorie oder Browser-Startargumenten offengelegt werden.
- Wenn `gateway.auth.token` in diesem Befehlsablauf per SecretRef verwaltet wird, aber nicht aufgelöst ist, gibt der Befehl eine URL ohne Token und explizite Hinweise zur Behebung aus, anstatt einen ungültigen Token-Platzhalter einzubetten.
- `dashboard` löst konfigurierte `gateway.auth.token`-SecretRefs auf, wenn möglich.
- `dashboard` folgt `gateway.tls.enabled`: Gateways mit aktiviertem TLS geben/öffnen
Control-UI-URLs mit `https://` aus und verbinden sich über `wss://`.
- Wenn die Übergabe an Zwischenablage/Browser für eine tokenauthentifizierte Dashboard-URL fehlschlägt,
protokolliert `dashboard` einen sicheren Hinweis zur manuellen Authentifizierung, der `OPENCLAW_GATEWAY_TOKEN`,
`gateway.auth.token` und den Fragment-Schlüssel `token` nennt, ohne den Tokenwert
auszugeben.
- Für SecretRef-verwaltete Token (aufgelöst oder nicht aufgelöst) gibt/kopiert/öffnet `dashboard` eine URL ohne Token, um zu vermeiden, dass externe Secrets in der Terminalausgabe, im Zwischenablageverlauf oder in Browser-Startargumenten offengelegt werden.
- Wenn `gateway.auth.token` SecretRef-verwaltet ist, aber in diesem Befehlspfad nicht aufgelöst wurde, gibt der Befehl eine URL ohne Token und explizite Hinweise zur Behebung aus, statt einen ungültigen Token-Platzhalter einzubetten.
## Verwandt
## Verwandte Themen
- [CLI-Referenz](/de/cli)
- [Dashboard](/de/web/dashboard)

68
docs/de/cli/doctor.md
View File

@ -1,23 +1,23 @@
---
read_when:
- Sie haben Verbindungs- oder Authentifizierungsprobleme und möchten angeleitete Behebungen
- Sie haben aktualisiert und möchten eine kurze Plausibilitätsprüfung
- Sie haben Verbindungs- oder Authentifizierungsprobleme und möchten eine geführte Fehlerbehebung
- Sie haben aktualisiert und möchten eine Plausibilitätsprüfung
summary: CLI-Referenz für `openclaw doctor` (Integritätsprüfungen + geführte Reparaturen)
title: Diagnose
x-i18n:
generated_at: "2026-05-04T02:22:34Z"
generated_at: "2026-05-05T01:44:14Z"
model: gpt-5.5
provider: openai
source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905
source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5
source_path: cli/doctor.md
workflow: 16
---
# `openclaw doctor`
Health Checks + Schnellkorrekturen für Gateway und Kanäle.
Health Checks + Schnellreparaturen für das Gateway und die Kanäle.
Zugehörig:
Verwandte Themen:
- Fehlerbehebung: [Fehlerbehebung](/de/gateway/troubleshooting)
- Sicherheitsaudit: [Sicherheit](/de/gateway/security)
@ -34,40 +34,40 @@ openclaw doctor --generate-gateway-token
## Optionen
- `--no-workspace-suggestions`: Workspace-Speicher-/Suchvorschläge deaktivieren
- `--yes`: Standardwerte ohne Nachfrage akzeptieren
- `--repair`: empfohlene nicht dienstbezogene Reparaturen ohne Nachfrage anwenden; Gateway-Dienstinstallationen und Neuschreibungen erfordern weiterhin eine interaktive Bestätigung oder explizite Gateway-Befehle
- `--no-workspace-suggestions`: Workspace-Memory-/Suchvorschläge deaktivieren
- `--yes`: Standardwerte ohne Rückfrage akzeptieren
- `--repair`: empfohlene Reparaturen ohne Dienstbezug ohne Rückfrage anwenden; Gateway-Dienstinstallationen und -Neuschreibungen erfordern weiterhin interaktive Bestätigung oder explizite Gateway-Befehle
- `--fix`: Alias für `--repair`
- `--force`: aggressive Reparaturen anwenden, einschließlich Überschreiben benutzerdefinierter Dienstkonfigurationen, wenn nötig
- `--non-interactive`: ohne Eingabeaufforderungen ausführen; nur sichere Migrationen und nicht dienstbezogene Reparaturen
- `--generate-gateway-token`: ein Gateway-Token generieren und konfigurieren
- `--force`: aggressive Reparaturen anwenden, einschließlich Überschreiben benutzerdefinierter Dienstkonfiguration, wenn nötig
- `--non-interactive`: ohne Rückfragen ausführen; nur sichere Migrationen und Reparaturen ohne Dienstbezug
- `--generate-gateway-token`: ein Gateway-Token erzeugen und konfigurieren
- `--deep`: Systemdienste auf zusätzliche Gateway-Installationen prüfen
Hinweise:
- Interaktive Eingabeaufforderungen (wie Keychain-/OAuth-Korrekturen) werden nur ausgeführt, wenn stdin ein TTY ist und `--non-interactive` **nicht** gesetzt ist. Headless-Ausführungen (Cron, Telegram, kein Terminal) überspringen Eingabeaufforderungen.
- Performance: Nicht interaktive `doctor`-Ausführungen überspringen das eifrige Laden von Plugins, damit Headless-Health-Checks schnell bleiben. Interaktive Sitzungen laden Plugins weiterhin vollständig, wenn ein Check deren Beitrag benötigt.
- Interaktive Eingabeaufforderungen (wie Schlüsselbund-/OAuth-Korrekturen) werden nur ausgeführt, wenn stdin ein TTY ist und `--non-interactive` **nicht** gesetzt ist. Headless-Ausführungen (Cron, Telegram, kein Terminal) überspringen Eingabeaufforderungen.
- Performance: Nicht interaktive `doctor`-Ausführungen überspringen vorsorgliches Plugin-Laden, damit Headless-Health-Checks schnell bleiben. Interaktive Sitzungen laden Plugins weiterhin vollständig, wenn ein Check deren Beitrag benötigt.
- `--fix` (Alias für `--repair`) schreibt ein Backup nach `~/.openclaw/openclaw.json.bak` und entfernt unbekannte Konfigurationsschlüssel, wobei jede Entfernung aufgelistet wird.
- `doctor --fix --non-interactive` meldet fehlende oder veraltete Gateway-Dienstdefinitionen, installiert oder überschreibt sie jedoch nicht außerhalb des Update-Reparaturmodus. Führen Sie `openclaw gateway install` für einen fehlenden Dienst aus oder `openclaw gateway install --force`, wenn Sie den Launcher bewusst ersetzen möchten.
- Integritätsprüfungen des Zustands erkennen jetzt verwaiste Transkriptdateien im Sitzungsverzeichnis. Das Archivieren als `.deleted.<timestamp>` erfordert eine interaktive Bestätigung; `--fix`, `--yes` und Headless-Ausführungen lassen sie unverändert.
- Doctor durchsucht außerdem `~/.openclaw/cron/jobs.json` (oder `cron.store`) nach alten Cron-Job-Formaten und kann sie direkt umschreiben, bevor der Scheduler sie zur Laufzeit automatisch normalisieren muss.
- Unter Linux warnt Doctor, wenn die Crontab des Benutzers weiterhin das alte `~/.openclaw/bin/ensure-whatsapp.sh` ausführt; dieses Skript wird nicht mehr gepflegt und kann falsche WhatsApp-Gateway-Ausfälle protokollieren, wenn Cron die systemd-User-Bus-Umgebung fehlt.
- Doctor bereinigt alten Plugin-Abhängigkeits-Staging-Zustand, der von älteren OpenClaw-Versionen erstellt wurde. Es repariert außerdem fehlende konfigurierte herunterladbare Plugins, wenn die Registry sie auflösen kann, und der Doctor-Durchlauf 2026.5.2 installiert automatisch herunterladbare Plugins, die eine ältere Konfiguration bereits verwendet, bevor die Konfiguration für diese Version als geändert markiert wird. Wenn der Download fehlschlägt, meldet Doctor den Installationsfehler und bewahrt den konfigurierten Plugin-Eintrag für den nächsten Reparaturversuch auf.
- Doctor repariert veraltete Plugin-Konfigurationen, indem fehlende Plugin-IDs aus `plugins.allow`/`plugins.entries` entfernt werden, plus passende hängende Kanalkonfiguration, Heartbeat-Ziele und Kanalmodell-Overrides, wenn die Plugin-Erkennung fehlerfrei ist.
- Doctor isoliert ungültige Plugin-Konfigurationen, indem der betroffene Eintrag `plugins.entries.<id>` deaktiviert und seine ungültige `config`-Payload entfernt wird. Der Gateway-Start überspringt bereits nur dieses fehlerhafte Plugin, sodass andere Plugins und Kanäle weiterlaufen können.
- Setzen Sie `OPENCLAW_SERVICE_REPAIR_POLICY=external`, wenn ein anderer Supervisor den Gateway-Lebenszyklus verwaltet. Doctor meldet weiterhin Gateway-/Dienstzustand und wendet nicht dienstbezogene Reparaturen an, überspringt aber Dienstinstallation, Start, Neustart, Bootstrap und Bereinigung alter Dienste.
- Unter Linux ignoriert Doctor inaktive zusätzliche Gateway-ähnliche systemd-Units und schreibt während der Reparatur keine Befehls-/Entrypoint-Metadaten für einen laufenden systemd-Gateway-Dienst um. Stoppen Sie zuerst den Dienst oder verwenden Sie `openclaw gateway install --force`, wenn Sie den aktiven Launcher bewusst ersetzen möchten.
- Doctor migriert alte flache Talk-Konfiguration (`talk.voiceId`, `talk.modelId` und verwandte Einstellungen) automatisch nach `talk.provider` + `talk.providers.<provider>`.
- Wiederholte `doctor --fix`-Ausführungen melden/wenden die Talk-Normalisierung nicht mehr an, wenn der einzige Unterschied die Reihenfolge von Objektschlüsseln ist.
- Doctor enthält einen Bereitschaftscheck für Memory-Suche und kann `openclaw configure --section model` empfehlen, wenn Embedding-Anmeldedaten fehlen.
- Doctor warnt, wenn kein Befehlsinhaber konfiguriert ist. Der Befehlsinhaber ist das menschliche Betreiberkonto, das Befehle nur für Inhaber ausführen und gefährliche Aktionen genehmigen darf. DM-Pairing erlaubt nur, dass jemand mit dem Bot spricht; wenn Sie einen Absender genehmigt haben, bevor der Bootstrap für den ersten Inhaber existierte, setzen Sie `commands.ownerAllowFrom` explizit.
- Doctor warnt, wenn Agenten im Codex-Modus konfiguriert sind und persönliche Codex-CLI-Assets im Codex-Home des Betreibers vorhanden sind. Lokale Codex-App-Server-Starts verwenden isolierte Homes pro Agent, nutzen Sie daher `openclaw migrate codex --dry-run`, um Assets zu inventarisieren, die bewusst übernommen werden sollten.
- `doctor --fix --non-interactive` meldet fehlende oder veraltete Gateway-Dienstdefinitionen, installiert oder schreibt sie außerhalb des Update-Reparaturmodus jedoch nicht neu. Führen Sie `openclaw gateway install` für einen fehlenden Dienst aus oder `openclaw gateway install --force`, wenn Sie den Launcher bewusst ersetzen möchten.
- Integritätsprüfungen des Zustands erkennen jetzt verwaiste Transkriptdateien im Sitzungsverzeichnis. Deren Archivierung als `.deleted.<timestamp>` erfordert eine interaktive Bestätigung; `--fix`, `--yes` und Headless-Ausführungen lassen sie bestehen.
- Doctor prüft auch `~/.openclaw/cron/jobs.json` (oder `cron.store`) auf veraltete Cron-Job-Formate und kann sie direkt umschreiben, bevor der Scheduler sie zur Laufzeit automatisch normalisieren muss.
- Unter Linux warnt Doctor, wenn die Crontab des Benutzers weiterhin das veraltete `~/.openclaw/bin/ensure-whatsapp.sh` ausführt; dieses Skript wird nicht mehr gepflegt und kann falsche WhatsApp-Gateway-Ausfälle protokollieren, wenn Cron die systemd-Benutzerbus-Umgebung fehlt.
- Doctor bereinigt veralteten Staging-Zustand für Plugin-Abhängigkeiten, der von älteren OpenClaw-Versionen erstellt wurde. Außerdem repariert es fehlende herunterladbare Plugins, die in der Konfiguration referenziert werden, etwa `plugins.entries`, konfigurierte Kanäle, konfigurierte Provider-/Sucheinstellungen oder konfigurierte Agent-Runtimes. Während Paketaktualisierungen überspringt Doctor die Plugin-Reparatur durch den Paketmanager, bis der Paketaustausch abgeschlossen ist; führen Sie danach erneut `openclaw doctor --fix` aus, wenn ein konfiguriertes Plugin weiterhin Wiederherstellung benötigt. Wenn der Download fehlschlägt, meldet Doctor den Installationsfehler und behält den konfigurierten Plugin-Eintrag für den nächsten Reparaturversuch bei.
- Doctor repariert veraltete Plugin-Konfiguration, indem fehlende Plugin-IDs aus `plugins.allow`/`plugins.entries` entfernt werden, außerdem passende verwaiste Kanalkonfiguration, Heartbeat-Ziele und Kanalmodell-Overrides, wenn die Plugin-Erkennung fehlerfrei ist.
- Doctor stellt ungültige Plugin-Konfiguration unter Quarantäne, indem der betroffene Eintrag `plugins.entries.<id>` deaktiviert und seine ungültige `config`-Nutzlast entfernt wird. Der Gateway-Start überspringt bereits nur dieses fehlerhafte Plugin, sodass andere Plugins und Kanäle weiterlaufen können.
- Setzen Sie `OPENCLAW_SERVICE_REPAIR_POLICY=external`, wenn ein anderer Supervisor den Gateway-Lebenszyklus verwaltet. Doctor meldet weiterhin Gateway-/Dienstzustand und wendet Reparaturen ohne Dienstbezug an, überspringt jedoch Dienstinstallation/-Start/-Neustart/-Bootstrap und die Bereinigung veralteter Dienste.
- Unter Linux ignoriert Doctor inaktive zusätzliche Gateway-ähnliche systemd-Units und schreibt bei der Reparatur keine Befehls-/Entrypoint-Metadaten für einen laufenden systemd-Gateway-Dienst neu. Stoppen Sie zuerst den Dienst oder verwenden Sie `openclaw gateway install --force`, wenn Sie den aktiven Launcher bewusst ersetzen möchten.
- Doctor migriert automatisch veraltete flache Talk-Konfiguration (`talk.voiceId`, `talk.modelId` und verwandte Einträge) nach `talk.provider` + `talk.providers.<provider>`.
- Wiederholte `doctor --fix`-Ausführungen melden/wenden keine Talk-Normalisierung mehr an, wenn der einzige Unterschied die Reihenfolge von Objektschlüsseln ist.
- Doctor enthält einen Readiness-Check für Memory-Suche und kann `openclaw configure --section model` empfehlen, wenn Embedding-Anmeldedaten fehlen.
- Doctor warnt, wenn kein Befehls-Owner konfiguriert ist. Der Befehls-Owner ist das menschliche Betreiberkonto, das Owner-only-Befehle ausführen und gefährliche Aktionen genehmigen darf. DM-Pairing erlaubt nur, mit dem Bot zu sprechen; wenn Sie einen Absender genehmigt haben, bevor das Bootstrap für den ersten Owner existierte, setzen Sie `commands.ownerAllowFrom` explizit.
- Doctor warnt, wenn Agenten im Codex-Modus konfiguriert sind und persönliche Codex-CLI-Assets im Codex-Home des Betreibers vorhanden sind. Lokale Codex-App-Server-Starts verwenden isolierte Homes pro Agent. Verwenden Sie daher `openclaw migrate codex --dry-run`, um Assets zu inventarisieren, die bewusst hochgestuft werden sollten.
- Doctor warnt, wenn Skills, die für den Standardagenten erlaubt sind, in der aktuellen Runtime-Umgebung nicht verfügbar sind, weil Binaries, Umgebungsvariablen, Konfiguration oder OS-Anforderungen fehlen. `doctor --fix` kann diese nicht verfügbaren Skills mit `skills.entries.<skill>.enabled=false` deaktivieren; installieren/konfigurieren Sie stattdessen die fehlende Anforderung, wenn Sie den Skill aktiv halten möchten.
- Wenn der Sandbox-Modus aktiviert ist, Docker aber nicht verfügbar ist, meldet Doctor eine prägnante Warnung mit Abhilfe (`install Docker` oder `openclaw config set agents.defaults.sandbox.mode off`).
- Wenn alte Sandbox-Registry-Dateien (`~/.openclaw/sandbox/containers.json` oder `~/.openclaw/sandbox/browsers.json`) vorhanden sind, meldet Doctor sie; `openclaw doctor --fix` migriert gültige Einträge in geshardete Registry-Verzeichnisse und isoliert ungültige alte Dateien.
- Wenn `gateway.auth.token`/`gateway.auth.password` von SecretRef verwaltet werden und im aktuellen Befehlspfad nicht verfügbar sind, meldet Doctor eine schreibgeschützte Warnung und schreibt keine Klartext-Fallback-Anmeldedaten.
- Wenn die Channel-SecretRef-Inspektion in einem Fix-Pfad fehlschlägt, fährt Doctor fort und meldet eine Warnung, statt frühzeitig zu beenden.
- Nach Zustandsverzeichnis-Migrationen warnt Doctor, wenn aktivierte Standard-Telegram- oder Discord-Konten von einem Env-Fallback abhängen und `TELEGRAM_BOT_TOKEN` oder `DISCORD_BOT_TOKEN` für den Doctor-Prozess nicht verfügbar ist.
- Wenn der Sandbox-Modus aktiviert ist, Docker aber nicht verfügbar ist, meldet Doctor eine aussagekräftige Warnung mit Abhilfe (`install Docker` oder `openclaw config set agents.defaults.sandbox.mode off`).
- Wenn veraltete Sandbox-Registry-Dateien (`~/.openclaw/sandbox/containers.json` oder `~/.openclaw/sandbox/browsers.json`) vorhanden sind, meldet Doctor sie; `openclaw doctor --fix` migriert gültige Einträge in geshardete Registry-Verzeichnisse und stellt ungültige Legacy-Dateien unter Quarantäne.
- Wenn `gateway.auth.token`/`gateway.auth.password` per SecretRef verwaltet werden und im aktuellen Befehlspfad nicht verfügbar sind, meldet Doctor eine schreibgeschützte Warnung und schreibt keine Plaintext-Fallback-Anmeldedaten.
- Wenn die SecretRef-Inspektion eines Kanals in einem Korrekturpfad fehlschlägt, fährt Doctor fort und meldet eine Warnung, statt frühzeitig zu beenden.
- Nach Migrationen des Zustandsverzeichnisses warnt Doctor, wenn aktivierte Standardkonten für Telegram oder Discord von einem Env-Fallback abhängen und `TELEGRAM_BOT_TOKEN` oder `DISCORD_BOT_TOKEN` für den Doctor-Prozess nicht verfügbar ist.
- Die automatische Auflösung von Telegram-`allowFrom`-Benutzernamen (`doctor --fix`) erfordert ein auflösbares Telegram-Token im aktuellen Befehlspfad. Wenn die Token-Inspektion nicht verfügbar ist, meldet Doctor eine Warnung und überspringt die automatische Auflösung für diesen Durchlauf.
## macOS: `launchctl`-Env-Overrides
@ -82,7 +82,7 @@ launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```
## Zugehörig
## Verwandte Themen
- [CLI-Referenz](/de/cli)
- [Gateway Doctor](/de/gateway/doctor)

255
docs/de/cli/gateway.md
View File

@ -1,27 +1,27 @@
---
read_when:
- Gateway über die CLI ausführen (Entwicklung oder Server)
- Debuggen der Gateway-Authentifizierung, Bind-Modi und Konnektivität
- Gateways über Bonjour erkennen (lokales + Weitbereichs-DNS-SD)
- Fehlersuche bei Gateway-Authentifizierung, Bind-Modi und Konnektivität
- Gateways über Bonjour erkennen (lokales + Wide-Area-DNS-SD)
sidebarTitle: Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — Gateways starten, abfragen und entdecken
summary: OpenClaw Gateway CLI (`openclaw gateway`) — Gateways ausführen, abfragen und entdecken
title: Gateway
x-i18n:
generated_at: "2026-05-04T18:23:39Z"
generated_at: "2026-05-05T01:44:23Z"
model: gpt-5.5
provider: openai
source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038
source_path: cli/gateway.md
workflow: 16
---
The Gateway ist OpenClaws WebSocket-Server (Kanäle, Nodes, Sitzungen, Hooks). Die Unterbefehle auf dieser Seite befinden sich unter `openclaw gateway …`.
Der Gateway ist OpenClaws WebSocket-Server (Kanäle, Nodes, Sitzungen, Hooks). Die Unterbefehle auf dieser Seite befinden sich unter `openclaw gateway …`.
<CardGroup cols={3}>
<Card title="Bonjour-Erkennung" href="/de/gateway/bonjour">
Lokales mDNS + Wide-Area-DNS-SD-Einrichtung.
Lokale mDNS- und Wide-Area-DNS-SD-Einrichtung.
</Card>
<Card title="Discovery-Übersicht" href="/de/gateway/discovery">
<Card title="Erkennungsübersicht" href="/de/gateway/discovery">
Wie OpenClaw Gateways ankündigt und findet.
</Card>
<Card title="Konfiguration" href="/de/gateway/configuration">
@ -37,7 +37,7 @@ Führen Sie einen lokalen Gateway-Prozess aus:
openclaw gateway
```
Alias für den Vordergrund:
Vordergrund-Alias:
```bash
openclaw gateway run
@ -45,11 +45,11 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="Startverhalten">
- Standardmäßig verweigert der Gateway den Start, sofern `gateway.mode=local` nicht in `~/.openclaw/openclaw.json` gesetzt ist. Verwenden Sie `--allow-unconfigured` für Ad-hoc-/Entwicklungsstarts.
- Von `openclaw onboard --mode local` und `openclaw setup` wird erwartet, dass sie `gateway.mode=local` schreiben. Wenn die Datei vorhanden ist, aber `gateway.mode` fehlt, behandeln Sie dies als fehlerhafte oder überschriebene Konfiguration und reparieren Sie sie, statt den lokalen Modus implizit anzunehmen.
- Wenn die Datei vorhanden ist und `gateway.mode` fehlt, behandelt der Gateway dies als verdächtigen Konfigurationsschaden und verweigert es, für Sie „lokal zu raten“.
- Standardmäßig verweigert der Gateway den Start, wenn `gateway.mode=local` nicht in `~/.openclaw/openclaw.json` gesetzt ist. Verwenden Sie `--allow-unconfigured` für Ad-hoc-/Entwicklungs-Ausführungen.
- Von `openclaw onboard --mode local` und `openclaw setup` wird erwartet, dass sie `gateway.mode=local` schreiben. Wenn die Datei existiert, aber `gateway.mode` fehlt, behandeln Sie dies als beschädigte oder überschriebene Konfiguration und reparieren Sie sie, statt implizit den lokalen Modus anzunehmen.
- Wenn die Datei existiert und `gateway.mode` fehlt, behandelt der Gateway dies als verdächtige Konfigurationsbeschädigung und weigert sich, für Sie „lokal zu erraten“.
- Das Binden über loopback hinaus ohne Authentifizierung wird blockiert (Sicherheitsleitplanke).
- `SIGUSR1` löst einen prozessinternen Neustart aus, wenn dies autorisiert ist (`commands.restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um einen manuellen Neustart zu blockieren, während Anwenden/Aktualisieren von Gateway-Tool/-Konfiguration weiterhin erlaubt bleibt).
- `SIGUSR1` löst einen Neustart im Prozess aus, wenn er autorisiert ist (`commands.restart` ist standardmäßig aktiviert; setzen Sie `commands.restart: false`, um manuelle Neustarts zu blockieren, während Anwenden/Aktualisieren von Gateway-Tools/-Konfiguration weiterhin erlaubt bleibt).
- `SIGINT`-/`SIGTERM`-Handler stoppen den Gateway-Prozess, stellen aber keinen benutzerdefinierten Terminalzustand wieder her. Wenn Sie die CLI mit einer TUI oder Raw-Mode-Eingabe umschließen, stellen Sie das Terminal vor dem Beenden wieder her.
</Accordion>
@ -58,37 +58,37 @@ openclaw gateway run
### Optionen
<ParamField path="--port <port>" type="number">
WebSocket-Port (Standardwert stammt aus Konfiguration/Env; normalerweise `18789`).
WebSocket-Port (Standardwert stammt aus Konfiguration/Env; üblicherweise `18789`).
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
Bind-Modus des Listeners.
Bindungsmodus des Listeners.
</ParamField>
<ParamField path="--auth <token|password>" type="string">
Überschreibung des Authentifizierungsmodus.
</ParamField>
<ParamField path="--token <token>" type="string">
Token-Überschreibung (setzt auch `OPENCLAW_GATEWAY_TOKEN` für den Prozess).
Token-Überschreibung (setzt außerdem `OPENCLAW_GATEWAY_TOKEN` für den Prozess).
</ParamField>
<ParamField path="--password <password>" type="string">
Passwortüberschreibung.
Passwort-Überschreibung.
</ParamField>
<ParamField path="--password-file <path>" type="string">
Gateway-Passwort aus einer Datei lesen.
Das Gateway-Passwort aus einer Datei lesen.
</ParamField>
<ParamField path="--tailscale <off|serve|funnel>" type="string">
Gateway über Tailscale verfügbar machen.
Den Gateway über Tailscale verfügbar machen.
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
Tailscale-Serve-/Funnel-Konfiguration beim Herunterfahren zurücksetzen.
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
Gateway-Start ohne `gateway.mode=local` in der Konfiguration erlauben. Umgeht die Startschutzprüfung nur für Ad-hoc-/Entwicklungs-Bootstrapping; schreibt oder repariert die Konfigurationsdatei nicht.
Gateway-Start ohne `gateway.mode=local` in der Konfiguration erlauben. Umgeht die Startschutzprüfung nur für Ad-hoc-/Entwicklungs-Bootstrap; schreibt oder repariert die Konfigurationsdatei nicht.
</ParamField>
<ParamField path="--dev" type="boolean">
Entwicklungskonfiguration + Workspace erstellen, falls sie fehlen (überspringt BOOTSTRAP.md).
Eine Entwicklungskonfiguration und einen Workspace erstellen, falls sie fehlen (überspringt BOOTSTRAP.md).
</ParamField>
<ParamField path="--reset" type="boolean">
Entwicklungskonfiguration + Anmeldedaten + Sitzungen + Workspace zurücksetzen (erfordert `--dev`).
Entwicklungskonfiguration, Anmeldedaten, Sitzungen und Workspace zurücksetzen (erfordert `--dev`).
</ParamField>
<ParamField path="--force" type="boolean">
Vor dem Start jeden vorhandenen Listener auf dem ausgewählten Port beenden.
@ -106,10 +106,10 @@ openclaw gateway run
Alias für `--ws-log compact`.
</ParamField>
<ParamField path="--raw-stream" type="boolean">
Rohdaten von Modell-Stream-Ereignissen in jsonl protokollieren.
Rohereignisse des Modellstreams als jsonl protokollieren.
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
jsonl-Pfad für Rohdatenstreams.
jsonl-Pfad für Rohstreams.
</ParamField>
## Gateway neu starten
@ -120,26 +120,26 @@ openclaw gateway restart --safe
openclaw gateway restart --force
```
`openclaw gateway restart --safe` fordert den laufenden Gateway auf, aktive OpenClaw-Arbeit vor dem Neustart vorab zu prüfen. Wenn Warteschlangenoperationen, Antwortzustellung, eingebettete Läufe oder Task-Läufe aktiv sind, meldet der Gateway die Blocker, fasst doppelte sichere Neustartanforderungen zusammen und startet neu, sobald die aktive Arbeit abgearbeitet ist. Einfaches `restart` behält das bestehende Service-Manager-Verhalten aus Kompatibilitätsgründen bei. Verwenden Sie `--force` nur, wenn Sie ausdrücklich den sofortigen Override-Pfad wünschen.
`openclaw gateway restart --safe` fordert den laufenden Gateway auf, aktive OpenClaw-Arbeit vor dem Neustart per Preflight zu prüfen. Wenn eingereihte Vorgänge, Antwortzustellung, eingebettete Ausführungen oder Task-Ausführungen aktiv sind, meldet der Gateway die Blocker, fasst doppelte sichere Neustartanforderungen zusammen und startet neu, sobald die aktive Arbeit abgearbeitet ist. Einfaches `restart` behält aus Kompatibilitätsgründen das bestehende Service-Manager-Verhalten bei. Verwenden Sie `--force` nur, wenn Sie ausdrücklich den unmittelbaren Override-Pfad möchten.
<Warning>
Inline-`--password` kann in lokalen Prozesslisten sichtbar werden. Bevorzugen Sie `--password-file`, Env oder ein SecretRef-gestütztes `gateway.auth.password`.
Inline-`--password` kann in lokalen Prozesslisten offengelegt werden. Bevorzugen Sie `--password-file`, Env oder ein SecretRef-gestütztes `gateway.auth.password`.
</Warning>
### Start-Profiling
- Setzen Sie `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, um Phasenzeiten während des Gateway-Starts zu protokollieren, einschließlich `eventLoopMax`-Verzögerung pro Phase sowie Plugin-Lookup-Table-Zeiten für installed-index, Manifest-Registry, Startplanung und owner-map-Arbeit.
- Setzen Sie `OPENCLAW_DIAGNOSTICS=timeline` mit `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`, um eine Best-Effort-JSONL-Startdiagnose-Timeline für externe QA-Harnesses zu schreiben. Sie können das Flag auch mit `diagnostics.flags: ["timeline"]` in der Konfiguration aktivieren; der Pfad wird weiterhin über Env bereitgestellt. Fügen Sie `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` hinzu, um Event-Loop-Samples einzubeziehen.
- Führen Sie `pnpm test:startup:gateway -- --runs 5 --warmup 1` aus, um den Gateway-Start zu benchmarken. Der Benchmark erfasst die erste Prozessausgabe, `/healthz`, `/readyz`, Start-Trace-Zeiten, Event-Loop-Verzögerung und Zeitdetails der Plugin-Lookup-Table.
- Setzen Sie `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, um Phasenzeiten während des Gateway-Starts zu protokollieren, einschließlich `eventLoopMax`-Verzögerung pro Phase und Plugin-Lookup-Table-Zeiten für installierten Index, Manifest-Registry, Startplanung und Owner-Map-Arbeit.
- Setzen Sie `OPENCLAW_DIAGNOSTICS=timeline` mit `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>`, um eine Best-Effort-JSONL-Startdiagnose-Zeitleiste für externe QA-Harnesses zu schreiben. Sie können das Flag auch mit `diagnostics.flags: ["timeline"]` in der Konfiguration aktivieren; der Pfad wird weiterhin über Env bereitgestellt. Fügen Sie `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` hinzu, um Event-Loop-Samples einzuschließen.
- Führen Sie `pnpm test:startup:gateway -- --runs 5 --warmup 1` aus, um den Gateway-Start zu benchmarken. Der Benchmark zeichnet die erste Prozessausgabe, `/healthz`, `/readyz`, Start-Trace-Zeiten, Event-Loop-Verzögerung und Zeitdetails der Plugin-Lookup-Table auf.
## Laufenden Gateway abfragen
Alle Abfragebefehle verwenden WebSocket RPC.
Alle Abfragebefehle verwenden WebSocket-RPC.
<Tabs>
<Tab title="Ausgabemodi">
- Standard: menschenlesbar (farbig in TTY).
- `--json`: maschinenlesbares JSON (kein Styling/Spinner).
- Standard: menschenlesbar (in TTY farbig).
- `--json`: maschinenlesbares JSON (ohne Styling/Spinner).
- `--no-color` (oder `NO_COLOR=1`): ANSI deaktivieren, während das menschenlesbare Layout beibehalten wird.
</Tab>
@ -163,7 +163,7 @@ Wenn Sie `--url` setzen, fällt die CLI nicht auf Konfigurations- oder Umgebungs
openclaw gateway health --url ws://127.0.0.1:18789
```
Der HTTP-Endpunkt `/healthz` ist eine Liveness-Probe: Er antwortet, sobald der Server HTTP beantworten kann. Der HTTP-Endpunkt `/readyz` ist strenger und bleibt rot, während Start-Plugin-Sidecars, Kanäle oder konfigurierte Hooks noch initialisiert werden. Lokale oder authentifizierte detaillierte Readiness-Antworten enthalten einen `eventLoop`-Diagnoseblock mit Event-Loop-Verzögerung, Event-Loop-Auslastung, CPU-Kern-Verhältnis und einem `degraded`-Flag.
Der HTTP-Endpunkt `/healthz` ist eine Liveness-Probe: Er antwortet, sobald der Server HTTP beantworten kann. Der HTTP-Endpunkt `/readyz` ist strenger und bleibt rot, solange Start-Plugin-Sidecars, Kanäle oder konfigurierte Hooks noch hochfahren. Lokale oder authentifizierte detaillierte Readiness-Antworten enthalten einen `eventLoop`-Diagnoseblock mit Event-Loop-Verzögerung, Event-Loop-Auslastung, CPU-Kern-Verhältnis und einem `degraded`-Flag.
### `gateway usage-cost`
@ -181,7 +181,7 @@ openclaw gateway usage-cost --json
### `gateway stability`
Aktuellen Diagnose-Stabilitätsrecorder von einem laufenden Gateway abrufen.
Den aktuellen Diagnose-Stabilitätsrekorder von einem laufenden Gateway abrufen.
```bash
openclaw gateway stability
@ -192,19 +192,19 @@ openclaw gateway stability --json
```
<ParamField path="--limit <limit>" type="number" default="25">
Maximale Anzahl der einzubeziehenden aktuellen Ereignisse (max. `1000`).
Maximale Anzahl einzubeziehender aktueller Ereignisse (max. `1000`).
</ParamField>
<ParamField path="--type <type>" type="string">
Nach Diagnoseereignistyp filtern, zum Beispiel `payload.large` oder `diagnostic.memory.pressure`.
Nach Diagnoseereignistyp filtern, etwa `payload.large` oder `diagnostic.memory.pressure`.
</ParamField>
<ParamField path="--since-seq <seq>" type="number">
Nur Ereignisse nach einer Diagnosesequenznummer einbeziehen.
Nur Ereignisse nach einer Diagnosesequenznummer einschließen.
</ParamField>
<ParamField path="--bundle [path]" type="string">
Ein persistiertes Stabilitäts-Bundle lesen, statt den laufenden Gateway aufzurufen. Verwenden Sie `--bundle latest` (oder nur `--bundle`) für das neueste Bundle unter dem Zustandsverzeichnis, oder übergeben Sie direkt einen Bundle-JSON-Pfad.
</ParamField>
<ParamField path="--export" type="boolean">
Eine teilbare ZIP-Datei mit Support-Diagnosen schreiben, statt Stabilitätsdetails auszugeben.
Eine teilbare Support-Diagnose-ZIP schreiben, statt Stabilitätsdetails auszugeben.
</ParamField>
<ParamField path="--output <path>" type="string">
Ausgabepfad für `--export`.
@ -212,15 +212,15 @@ openclaw gateway stability --json
<AccordionGroup>
<Accordion title="Datenschutz und Bundle-Verhalten">
- Datensätze behalten Betriebsmetadaten: Ereignisnamen, Zählwerte, Bytegrößen, Speichermesswerte, Warteschlangen-/Sitzungszustand, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Sie behalten keine Chat-Texte, Webhook-Bodys, Tool-Ausgaben, Rohdaten von Anfrage- oder Antwortbodys, Tokens, Cookies, geheime Werte, Hostnamen oder rohen Sitzungs-IDs. Setzen Sie `diagnostics.enabled: false`, um den Recorder vollständig zu deaktivieren.
- Bei fatalen Gateway-Beendigungen, Shutdown-Timeouts und Startfehlern nach Neustarts schreibt OpenClaw denselben Diagnose-Snapshot nach `~/.openclaw/logs/stability/openclaw-stability-*.json`, wenn der Recorder Ereignisse enthält. Prüfen Sie das neueste Bundle mit `openclaw gateway stability --bundle latest`; `--limit`, `--type` und `--since-seq` gelten auch für Bundle-Ausgaben.
- Datensätze behalten operative Metadaten: Ereignisnamen, Zähler, Bytegrößen, Speicherwerte, Queue-/Sitzungszustand, Kanal-/Plugin-Namen und redigierte Sitzungszusammenfassungen. Sie behalten keinen Chattext, keine Webhook-Bodys, Tool-Ausgaben, rohen Anfrage- oder Antwortbodys, Tokens, Cookies, geheimen Werte, Hostnamen oder rohen Sitzungs-IDs. Setzen Sie `diagnostics.enabled: false`, um den Rekorder vollständig zu deaktivieren.
- Bei fatalen Gateway-Exits, Shutdown-Timeouts und Startfehlern nach Neustarts schreibt OpenClaw denselben Diagnose-Snapshot nach `~/.openclaw/logs/stability/openclaw-stability-*.json`, wenn der Rekorder Ereignisse enthält. Prüfen Sie das neueste Bundle mit `openclaw gateway stability --bundle latest`; `--limit`, `--type` und `--since-seq` gelten ebenfalls für die Bundle-Ausgabe.
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
Schreibt eine lokale Diagnose-ZIP-Datei, die zum Anhängen an Fehlerberichte gedacht ist. Informationen zum Datenschutzmodell und zu Bundle-Inhalten finden Sie unter [Diagnoseexport](/de/gateway/diagnostics).
Eine lokale Diagnose-ZIP schreiben, die zum Anhängen an Fehlerberichte gedacht ist. Informationen zum Datenschutzmodell und zu den Bundle-Inhalten finden Sie unter [Diagnoseexport](/de/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@ -232,10 +232,10 @@ openclaw gateway diagnostics export --json
Ausgabe-ZIP-Pfad. Standardmäßig ein Support-Export unter dem Zustandsverzeichnis.
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
Maximale Anzahl bereinigter Logzeilen, die einbezogen werden.
Maximale Anzahl bereinigter Logzeilen, die eingeschlossen werden.
</ParamField>
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
Maximale Anzahl an Logbytes, die geprüft werden.
Maximale Anzahl Logbytes, die geprüft werden.
</ParamField>
<ParamField path="--url <url>" type="string">
Gateway-WebSocket-URL für den Health-Snapshot.
@ -250,15 +250,15 @@ openclaw gateway diagnostics export --json
Timeout für Status-/Health-Snapshot.
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
Suche nach persistiertem Stabilitäts-Bundle überspringen.
Lookup persistierter Stabilitäts-Bundles überspringen.
</ParamField>
<ParamField path="--json" type="boolean">
Geschriebenen Pfad, Größe und Manifest als JSON ausgeben.
Den geschriebenen Pfad, die Größe und das Manifest als JSON ausgeben.
</ParamField>
Der Export enthält ein Manifest, eine Markdown-Zusammenfassung, Konfigurationsstruktur, bereinigte Konfigurationsdetails, bereinigte Logzusammenfassungen, bereinigte Gateway-Status-/Health-Snapshots und das neueste Stabilitäts-Bundle, falls eines vorhanden ist.
Der Export enthält ein Manifest, eine Markdown-Zusammenfassung, Konfigurationsform, bereinigte Konfigurationsdetails, bereinigte Logzusammenfassungen, bereinigte Gateway-Status-/Health-Snapshots und das neueste Stabilitäts-Bundle, falls eines existiert.
Er ist zum Teilen gedacht. Er behält Betriebsdetails, die beim Debugging helfen, etwa sichere OpenClaw-Logfelder, Subsystemnamen, Statuscodes, Dauern, konfigurierte Modi, Ports, Plugin-IDs, Provider-IDs, nicht geheime Feature-Einstellungen und redigierte operative Logmeldungen. Er lässt Chat-Texte, Webhook-Bodys, Tool-Ausgaben, Anmeldedaten, Cookies, Konto-/Nachrichtenkennungen, Prompt-/Anweisungstext, Hostnamen und geheime Werte aus oder redigiert sie. Wenn eine LogTape-artige Meldung wie Benutzer-/Chat-/Tool-Payload-Text aussieht, behält der Export nur bei, dass eine Meldung ausgelassen wurde, plus deren Byteanzahl.
Er ist zum Teilen gedacht. Er behält operative Details, die beim Debugging helfen, etwa sichere OpenClaw-Logfelder, Subsystemnamen, Statuscodes, Dauern, konfigurierte Modi, Ports, Plugin-IDs, Provider-IDs, nicht geheime Feature-Einstellungen und redigierte operative Logmeldungen. Er lässt Chattext, Webhook-Bodys, Tool-Ausgaben, Anmeldedaten, Cookies, Konto-/Nachrichtenkennungen, Prompt-/Anweisungstext, Hostnamen und geheime Werte aus oder redigiert sie. Wenn eine LogTape-artige Meldung wie Benutzer-/Chat-/Tool-Nutzlasttext aussieht, behält der Export nur bei, dass eine Meldung ausgelassen wurde, plus deren Byteanzahl.
### `gateway status`
@ -271,56 +271,56 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
Fügen Sie ein explizites Prüfziel hinzu. Die konfigurierte Gegenstelle und localhost werden weiterhin geprüft.
Fügt ein explizites Probe-Ziel hinzu. Konfigurierte Remote-Ziele und localhost werden weiterhin geprüft.
</ParamField>
<ParamField path="--token <token>" type="string">
Token-Authentifizierung für die Prüfung.
Token-Auth für die Probe.
</ParamField>
<ParamField path="--password <password>" type="string">
Passwortauthentifizierung für die Prüfung.
Passwort-Auth für die Probe.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
Zeitlimit für die Prüfung.
Probe-Timeout.
</ParamField>
<ParamField path="--no-probe" type="boolean">
Überspringen Sie die Konnektivitätsprüfung (nur Service-Ansicht).
Überspringt die Konnektivitäts-Probe (nur Service-Ansicht).
</ParamField>
<ParamField path="--deep" type="boolean">
Auch Dienste auf Systemebene scannen.
Auch systemweite Services scannen.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
Stufen Sie die Standard-Konnektivitätsprüfung auf eine Leseprüfung hoch und beenden Sie mit einem Nicht-Null-Code, wenn diese Leseprüfung fehlschlägt. Kann nicht mit `--no-probe` kombiniert werden.
Stuft die Standard-Konnektivitäts-Probe zu einer Lese-Probe hoch und beendet mit einem Nicht-Null-Code, wenn diese Lese-Probe fehlschlägt. Kann nicht mit `--no-probe` kombiniert werden.
</ParamField>
<AccordionGroup>
<Accordion title="Statussemantik">
- `gateway status` bleibt für Diagnosen verfügbar, selbst wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
- Das standardmäßige `gateway status` weist Service-Zustand, WebSocket-Verbindung und die zum Handshake-Zeitpunkt sichtbare Authentifizierungsfähigkeit nach. Es weist keine Lese-/Schreib-/Admin-Vorgänge nach.
- Diagnoseprüfungen verändern bei erstmaliger Geräteauthentifizierung nichts: Sie verwenden ein vorhandenes zwischengespeichertes Geräte-Token erneut, wenn eines existiert, erstellen aber keine neue CLI-Geräteidentität oder schreibgeschützte Geräte-Pairing-Aufzeichnung nur zur Statusprüfung.
- `gateway status` löst konfigurierte Authentifizierungs-SecretRefs für die Prüf-Authentifizierung nach Möglichkeit auf.
- Wenn ein erforderlicher Authentifizierungs-SecretRef in diesem Befehlszweig nicht aufgelöst wird, meldet `gateway status --json` `rpc.authWarning`, wenn Prüfkonnektivität/Authentifizierung fehlschlägt; übergeben Sie `--token`/`--password` explizit oder lösen Sie zuerst die Secret-Quelle auf.
- Wenn die Prüfung erfolgreich ist, werden Warnungen zu nicht aufgelösten Authentifizierungsreferenzen unterdrückt, um Fehlalarme zu vermeiden.
- Verwenden Sie `--require-rpc` in Skripten und Automatisierung, wenn ein lauschender Dienst nicht ausreicht und auch RPC-Aufrufe mit Leseumfang funktionieren müssen.
- `--deep` fügt einen Best-Effort-Scan nach zusätzlichen launchd/systemd/schtasks-Installationen hinzu. Wenn mehrere gateway-ähnliche Dienste erkannt werden, gibt die menschenlesbare Ausgabe Bereinigungshinweise aus und warnt, dass die meisten Setups ein Gateway pro Maschine ausführen sollten.
- Die menschenlesbare Ausgabe enthält den aufgelösten Datei-Logpfad sowie eine Momentaufnahme der CLI-vs-Service-Konfigurationspfade/-Gültigkeit, um Profil- oder Statusverzeichnis-Abweichungen zu diagnostizieren.
- `gateway status` bleibt für Diagnosen verfügbar, auch wenn die lokale CLI-Konfiguration fehlt oder ungültig ist.
- Standardmäßig weist `gateway status` den Service-Status, die WebSocket-Verbindung und die zum Handshake-Zeitpunkt sichtbare Auth-Fähigkeit nach. Lese-/Schreib-/Admin-Operationen werden damit nicht nachgewiesen.
- Diagnose-Probes verändern bei erstmaliger Geräte-Auth nichts: Sie verwenden ein vorhandenes zwischengespeichertes Geräte-Token erneut, falls eines existiert, erstellen aber keine neue CLI-Geräteidentität und keinen schreibgeschützten Geräte-Pairing-Eintrag nur zur Statusprüfung.
- `gateway status` löst konfigurierte Auth-SecretRefs nach Möglichkeit für die Probe-Auth auf.
- Wenn eine erforderliche Auth-SecretRef in diesem Befehlspfad nicht aufgelöst wird, meldet `gateway status --json` `rpc.authWarning`, wenn Probe-Konnektivität/Auth fehlschlägt; übergeben Sie `--token`/`--password` explizit oder lösen Sie zuerst die Secret-Quelle auf.
- Wenn die Probe erfolgreich ist, werden Warnungen zu nicht aufgelösten Auth-Refs unterdrückt, um Fehlalarme zu vermeiden.
- Verwenden Sie `--require-rpc` in Skripten und Automatisierung, wenn ein lauschender Service nicht ausreicht und auch RPC-Aufrufe mit Lesebereich fehlerfrei sein müssen.
- `--deep` fügt einen Best-Effort-Scan nach zusätzlichen launchd-/systemd-/schtasks-Installationen hinzu. Wenn mehrere gateway-artige Services erkannt werden, gibt die Ausgabe für Menschen Bereinigungshinweise aus und warnt, dass die meisten Setups ein Gateway pro Maschine ausführen sollten.
- Die Ausgabe für Menschen enthält den aufgelösten Dateilogpfad sowie eine Momentaufnahme der CLI-gegen-Service-Konfigurationspfade und ihrer Gültigkeit, um Profil- oder State-Dir-Abweichungen zu diagnostizieren.
</Accordion>
<Accordion title="Auth-Drift-Prüfungen für Linux systemd">
- Bei Linux-systemd-Installationen lesen Service-Auth-Drift-Prüfungen sowohl `Environment=`- als auch `EnvironmentFile=`-Werte aus der Unit (einschließlich `%h`, zitierter Pfade, mehrerer Dateien und optionaler `-`-Dateien).
- Drift-Prüfungen lösen `gateway.auth.token`-SecretRefs mithilfe der zusammengeführten Laufzeitumgebung auf (zuerst Service-Befehlsumgebung, dann Prozessumgebung als Fallback).
- Wenn Token-Authentifizierung nicht effektiv aktiv ist (expliziter `gateway.auth.mode` von `password`/`none`/`trusted-proxy` oder nicht gesetzter Modus, bei dem Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Drift-Prüfungen die Auflösung des Konfigurations-Tokens.
<Accordion title="Linux-systemd-Prüfungen auf Auth-Drift">
- Bei Linux-systemd-Installationen lesen Prüfungen auf Service-Auth-Drift sowohl `Environment=`- als auch `EnvironmentFile=`-Werte aus der Unit (einschließlich `%h`, zitierter Pfade, mehrerer Dateien und optionaler `-`-Dateien).
- Drift-Prüfungen lösen `gateway.auth.token`-SecretRefs mit der zusammengeführten Runtime-Umgebung auf (zuerst Service-Befehlsumgebung, dann Prozessumgebung als Fallback).
- Wenn Token-Auth nicht effektiv aktiv ist (expliziter `gateway.auth.mode` von `password`/`none`/`trusted-proxy` oder nicht gesetzter Modus, bei dem Passwort gewinnen kann und kein Token-Kandidat gewinnen kann), überspringen Token-Drift-Prüfungen die Auflösung des Konfigurationstokens.
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` ist der Befehl zum „Alles debuggen“. Er prüft immer:
`gateway probe` ist der Befehl zum „alles debuggen“. Er prüft immer:
- Ihr konfiguriertes Remote-Gateway (falls gesetzt), und
- localhost (loopback) **auch wenn remote konfiguriert ist**.
- Ihr konfiguriertes Remote-Gateway (falls gesetzt) und
- localhost (loopback) **auch wenn Remote konfiguriert ist**.
Wenn Sie `--url` übergeben, wird dieses explizite Ziel vor beiden hinzugefügt. Die menschenlesbare Ausgabe beschriftet die Ziele als:
Wenn Sie `--url` übergeben, wird dieses explizite Ziel vor beiden hinzugefügt. Die Ausgabe für Menschen kennzeichnet die Ziele als:
- `URL (explicit)`
- `Remote (configured)` oder `Remote (configured, inactive)`
@ -338,11 +338,11 @@ openclaw gateway probe --json
<AccordionGroup>
<Accordion title="Interpretation">
- `Reachable: yes` bedeutet, dass mindestens ein Ziel eine WebSocket-Verbindung akzeptiert hat.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` meldet, was die Prüfung über die Authentifizierung nachweisen konnte. Das ist von der Erreichbarkeit getrennt.
- `Read probe: ok` bedeutet, dass Detail-RPC-Aufrufe mit Leseumfang (`health`/`status`/`system-presence`/`config.get`) ebenfalls erfolgreich waren.
- `Read probe: limited - missing scope: operator.read` bedeutet, dass die Verbindung erfolgreich war, der RPC mit Leseumfang aber eingeschränkt ist. Dies wird als **eingeschränkte** Erreichbarkeit gemeldet, nicht als vollständiger Fehler.
- `Read probe: failed` nach `Connect: ok` bedeutet, dass das Gateway die WebSocket-Verbindung akzeptiert hat, nachfolgende Lesediagnosen aber abgelaufen oder fehlgeschlagen sind. Auch dies ist **eingeschränkte** Erreichbarkeit, kein unerreichbares Gateway.
- Wie `gateway status` verwendet die Prüfung vorhandene zwischengespeicherte Geräteauthentifizierung erneut, erstellt aber keine erstmalige Geräteidentität oder keinen Pairing-Zustand.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` meldet, was die Probe über Auth nachweisen konnte. Dies ist getrennt von der Erreichbarkeit.
- `Read probe: ok` bedeutet, dass Detail-RPC-Aufrufe mit Lesebereich (`health`/`status`/`system-presence`/`config.get`) ebenfalls erfolgreich waren.
- `Read probe: limited - missing scope: operator.read` bedeutet, dass die Verbindung erfolgreich war, aber RPC mit Lesebereich eingeschränkt ist. Dies wird als **eingeschränkte** Erreichbarkeit gemeldet, nicht als vollständiger Fehler.
- `Read probe: failed` nach `Connect: ok` bedeutet, dass das Gateway die WebSocket-Verbindung akzeptiert hat, aber nachfolgende Lesediagnosen ein Timeout hatten oder fehlgeschlagen sind. Auch dies ist **eingeschränkte** Erreichbarkeit, kein unerreichbares Gateway.
- Wie `gateway status` verwendet die Probe vorhandene zwischengespeicherte Geräte-Auth erneut, erstellt aber keine erstmalige Geräteidentität oder keinen Pairing-Zustand.
- Der Exit-Code ist nur dann ungleich null, wenn kein geprüftes Ziel erreichbar ist.
</Accordion>
@ -350,38 +350,38 @@ openclaw gateway probe --json
Oberste Ebene:
- `ok`: Mindestens ein Ziel ist erreichbar.
- `degraded`: Mindestens ein Ziel hat eine Verbindung akzeptiert, aber die vollständige Detail-RPC-Diagnose nicht abgeschlossen.
- `capability`: beste Fähigkeit, die über erreichbare Ziele hinweg gesehen wurde (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` oder `unknown`).
- `primaryTargetId`: bestes Ziel, das in dieser Reihenfolge als aktiver Gewinner behandelt werden sollte: explizite URL, SSH-Tunnel, konfigurierte Gegenstelle, dann local loopback.
- `warnings[]`: Best-Effort-Warndatensätze mit `code`, `message` und optionalen `targetIds`.
- `degraded`: Mindestens ein Ziel hat eine Verbindung akzeptiert, aber keine vollständigen Detail-RPC-Diagnosen abgeschlossen.
- `capability`: beste Fähigkeit, die über erreichbare Ziele hinweg beobachtet wurde (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` oder `unknown`).
- `primaryTargetId`: bestes Ziel, das in dieser Reihenfolge als aktiver Gewinner behandelt werden soll: explizite URL, SSH-Tunnel, konfiguriertes Remote-Ziel, dann local loopback.
- `warnings[]`: Best-Effort-Warnungsdatensätze mit `code`, `message` und optionalen `targetIds`.
- `network`: local loopback-/Tailnet-URL-Hinweise, abgeleitet aus aktueller Konfiguration und Host-Netzwerk.
- `discovery.timeoutMs` und `discovery.count`: das tatsächliche Ermittlungsbudget bzw. die Ergebnisanzahl, die für diesen Prüfdurchlauf verwendet wurden.
- `discovery.timeoutMs` und `discovery.count`: das tatsächliche Discovery-Budget und die Ergebnisanzahl, die für diesen Probe-Durchlauf verwendet wurden.
Pro Ziel (`targets[].connect`):
- `ok`: Erreichbarkeit nach Verbindung + eingeschränkter Klassifizierung.
- `ok`: Erreichbarkeit nach Verbindung plus eingeschränkter Klassifizierung.
- `rpcOk`: vollständiger Detail-RPC-Erfolg.
- `scopeLimited`: Detail-RPC ist wegen fehlendem Operator-Umfang fehlgeschlagen.
- `scopeLimited`: Detail-RPC ist wegen fehlendem Operator-Bereich fehlgeschlagen.
Pro Ziel (`targets[].auth`):
- `role`: in `hello-ok` gemeldete Authentifizierungsrolle, sofern verfügbar.
- `scopes`: in `hello-ok` gemeldete gewährte Umfänge, sofern verfügbar.
- `capability`: die offengelegte Klassifizierung der Authentifizierungsfähigkeit für dieses Ziel.
- `role`: in `hello-ok` gemeldete Auth-Rolle, falls verfügbar.
- `scopes`: in `hello-ok` gemeldete gewährte Bereiche, falls verfügbar.
- `capability`: die offengelegte Auth-Fähigkeitsklassifizierung für dieses Ziel.
</Accordion>
<Accordion title="Häufige Warncodes">
- `ssh_tunnel_failed`: SSH-Tunnel-Einrichtung ist fehlgeschlagen; der Befehl ist auf direkte Prüfungen zurückgefallen.
- `multiple_gateways`: Mehr als ein Ziel war erreichbar; das ist ungewöhnlich, sofern Sie nicht absichtlich isolierte Profile ausführen, etwa einen Rescue-Bot.
- `auth_secretref_unresolved`: Ein konfigurierter Authentifizierungs-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
- `probe_scope_limited`: WebSocket-Verbindung war erfolgreich, aber die Leseprüfung wurde durch fehlendes `operator.read` eingeschränkt.
- `ssh_tunnel_failed`: Einrichtung des SSH-Tunnels fehlgeschlagen; der Befehl ist auf direkte Probes zurückgefallen.
- `multiple_gateways`: Mehr als ein Ziel war erreichbar; dies ist ungewöhnlich, sofern Sie nicht absichtlich isolierte Profile ausführen, zum Beispiel einen Rescue-Bot.
- `auth_secretref_unresolved`: Eine konfigurierte Auth-SecretRef konnte für ein fehlgeschlagenes Ziel nicht aufgelöst werden.
- `probe_scope_limited`: WebSocket-Verbindung war erfolgreich, aber die Lese-Probe wurde durch fehlendes `operator.read` eingeschränkt.
</Accordion>
</AccordionGroup>
#### Remote über SSH (Parität zur Mac-App)
Der macOS-App-Modus „Remote über SSH“ verwendet eine lokale Port-Weiterleitung, sodass das Remote-Gateway (das möglicherweise nur an loopback gebunden ist) unter `ws://127.0.0.1:<port>` erreichbar wird.
Der macOS-App-Modus „Remote über SSH“ verwendet eine lokale Portweiterleitung, sodass das Remote-Gateway (das möglicherweise nur an loopback gebunden ist) unter `ws://127.0.0.1:<port>` erreichbar wird.
CLI-Äquivalent:
@ -396,10 +396,10 @@ openclaw gateway probe --ssh user@gateway-host
Identitätsdatei.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
Wählen Sie den ersten ermittelten Gateway-Host als SSH-Ziel aus dem aufgelösten Ermittlungsendpunkt (`local.` plus die konfigurierte Wide-Area-Domain, falls vorhanden). Nur-TXT-Hinweise werden ignoriert.
Wählt den ersten erkannten Gateway-Host aus dem aufgelösten Discovery-Endpunkt als SSH-Ziel aus (`local.` plus die konfigurierte Wide-Area-Domain, falls vorhanden). Reine TXT-Hinweise werden ignoriert.
</ParamField>
Konfiguration (optional, wird als Standardwerte verwendet):
Konfiguration (optional, als Standardwerte verwendet):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
@ -426,10 +426,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Gateway-Passwort.
</ParamField>
<ParamField path="--timeout <ms>" type="number">
Zeitbudget.
Timeout-Budget.
</ParamField>
<ParamField path="--expect-final" type="boolean">
Hauptsächlich für agentenartige RPCs, die Zwischenereignisse vor einer finalen Nutzlast streamen.
Hauptsächlich für agent-artige RPCs, die Zwischenereignisse vor einer finalen Nutzlast streamen.
</ParamField>
<ParamField path="--json" type="boolean">
Maschinenlesbare JSON-Ausgabe.
@ -439,7 +439,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
`--params` muss gültiges JSON sein.
</Note>
## Gateway-Dienst verwalten
## Gateway-Service verwalten
```bash
openclaw gateway install
@ -451,9 +451,9 @@ openclaw gateway uninstall
### Mit einem Wrapper installieren
Verwenden Sie `--wrapper`, wenn der verwaltete Dienst über eine andere ausführbare Datei starten muss, zum Beispiel ein
Secrets-Manager-Shim oder ein Run-as-Helfer. Der Wrapper erhält die normalen Gateway-Argumente und ist
dafür verantwortlich, letztlich `openclaw` oder Node mit diesen Argumenten per exec zu starten.
Verwenden Sie `--wrapper`, wenn der verwaltete Service über eine andere ausführbare Datei starten muss, zum Beispiel einen
Secrets-Manager-Shim oder einen Run-as-Helfer. Der Wrapper erhält die normalen Gateway-Argumente und ist
dafür verantwortlich, am Ende `openclaw` oder Node mit diesen Argumenten per exec auszuführen.
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -467,8 +467,8 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
Sie können den Wrapper auch über die Umgebung festlegen. `gateway install` validiert, dass der Pfad eine
ausführbare Datei ist, schreibt den Wrapper in die Service-`ProgramArguments` und persistiert
Sie können den Wrapper auch über die Umgebung setzen. `gateway install` prüft, dass der Pfad eine
ausführbare Datei ist, schreibt den Wrapper in die Service-`ProgramArguments` und speichert
`OPENCLAW_WRAPPER` in der Service-Umgebung für spätere erzwungene Neuinstallationen, Updates und Doctor-
Reparaturen.
@ -477,7 +477,7 @@ OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --
openclaw doctor
```
Um einen persistierten Wrapper zu entfernen, leeren Sie `OPENCLAW_WRAPPER` während der Neuinstallation:
Um einen gespeicherten Wrapper zu entfernen, leeren Sie `OPENCLAW_WRAPPER` während der Neuinstallation:
```bash
OPENCLAW_WRAPPER= openclaw gateway install --force
@ -488,44 +488,45 @@ openclaw gateway restart
<Accordion title="Befehlsoptionen">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--force`, `--wait <duration>`, `--json`
- `gateway restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="Lebenszyklusverhalten">
- Verwenden Sie `gateway restart`, um einen verwalteten Dienst neu zu starten. Verketten Sie `gateway stop` und `gateway start` nicht als Neustartersatz; unter macOS deaktiviert `gateway stop` den LaunchAgent absichtlich, bevor er gestoppt wird.
<Accordion title="Lifecycle-Verhalten">
- Verwenden Sie `gateway restart`, um einen verwalteten Service neu zu starten. Verketten Sie `gateway stop` und `gateway start` nicht als Ersatz für einen Neustart; unter macOS deaktiviert `gateway stop` den LaunchAgent absichtlich, bevor er ihn stoppt.
- `gateway restart --safe` fordert das laufende Gateway auf, aktive OpenClaw-Arbeit vorab zu prüfen und den Neustart aufzuschieben, bis Antwortzustellung, eingebettete Ausführungen und Task-Ausführungen abgearbeitet sind. `--safe` kann nicht mit `--force` oder `--wait` kombiniert werden.
- `gateway restart --wait 30s` überschreibt das konfigurierte Restart-Drain-Budget für diesen Neustart. Reine Zahlen sind Millisekunden; Einheiten wie `s`, `m` und `h` werden akzeptiert. `--wait 0` wartet unbegrenzt.
- `gateway restart --force` überspringt das Drain aktiver Arbeit und startet sofort neu. Verwenden Sie dies, wenn ein Operator die aufgeführten Task-Blocker bereits geprüft hat und das Gateway jetzt zurückhaben möchte.
- Lebenszyklusbefehle akzeptieren `--json` für Skripting.
- `gateway restart --force` überspringt das Abarbeiten aktiver Arbeit und startet sofort neu. Verwenden Sie dies, wenn ein Operator die aufgeführten Task-Blocker bereits geprüft hat und das Gateway jetzt wieder verfügbar haben möchte.
- Lifecycle-Befehle akzeptieren `--json` für Skripting.
</Accordion>
<Accordion title="Authentifizierung und SecretRefs zur Installationszeit">
- Wenn Token-Authentifizierung ein Token erfordert und `gateway.auth.token` per SecretRef verwaltet wird, validiert `gateway install`, dass der SecretRef auflösbar ist, persistiert das aufgelöste Token aber nicht in Service-Umgebungsmetadaten.
- Wenn Token-Authentifizierung ein Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst ist, schlägt die Installation geschlossen fehl, statt Fallback-Klartext zu persistieren.
- Für Passwortauthentifizierung bei `gateway run` bevorzugen Sie `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` oder ein SecretRef-gestütztes `gateway.auth.password` gegenüber inline `--password`.
- Im abgeleiteten Authentifizierungsmodus lockert ein nur in der Shell gesetztes `OPENCLAW_GATEWAY_PASSWORD` die Token-Anforderungen bei der Installation nicht; verwenden Sie dauerhafte Konfiguration (`gateway.auth.password` oder Konfigurations-`env`), wenn Sie einen verwalteten Dienst installieren.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, wird die Installation blockiert, bis der Modus explizit gesetzt wird.
- Wenn Token-Authentifizierung ein Token erfordert und `gateway.auth.token` von SecretRef verwaltet wird, validiert `gateway install`, dass die SecretRef auflösbar ist, speichert das aufgelöste Token aber nicht in den Metadaten der Service-Umgebung.
- Wenn Token-Authentifizierung ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist, schlägt die Installation geschlossen fehl, statt Ersatz-Klartext zu speichern.
- Verwenden Sie für Passwortauthentifizierung bei `gateway run` bevorzugt `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` oder ein durch SecretRef gestütztes `gateway.auth.password` anstelle von inline `--password`.
- Im abgeleiteten Authentifizierungsmodus lockert ein nur in der Shell gesetztes `OPENCLAW_GATEWAY_PASSWORD` die Anforderungen an Installations-Token nicht; verwenden Sie dauerhafte Konfiguration (`gateway.auth.password` oder config `env`), wenn Sie einen verwalteten Service installieren.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, wird die Installation blockiert, bis der Modus ausdrücklich gesetzt wird.
</Accordion>
</AccordionGroup>
## Gateways ermitteln (Bonjour)
## Gateways erkennen (Bonjour)
`gateway discover` scannt nach Gateway-Beacons (`_openclaw-gw._tcp`).
`gateway discover` sucht nach Gateway-Beacons (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
- Unicast DNS-SD (Wide-Area Bonjour): Wählen Sie eine Domain (Beispiel: `openclaw.internal.`) und richten Sie Split-DNS + einen DNS-Server ein; siehe [Bonjour](/de/gateway/bonjour).
- Multicast-DNS-SD: `local.`
- Unicast-DNS-SD (Wide-Area Bonjour): Wählen Sie eine Domain (Beispiel: `openclaw.internal.`) und richten Sie Split-DNS + einen DNS-Server ein; siehe [Bonjour](/de/gateway/bonjour).
Nur Gateways mit aktivierter Bonjour-Erkennung (Standard) kündigen den Beacon an.
Nur Gateways mit aktivierter Bonjour-Erkennung (Standard) kündigen das Beacon an.
Wide-Area-Erkennungsdatensätze enthalten (TXT):
Wide-Area-Erkennungseinträge enthalten (TXT):
- `role` (Hinweis auf die Gateway-Rolle)
- `role` (Hinweis auf Gateway-Rolle)
- `transport` (Transporthinweis, z. B. `gateway`)
- `gatewayPort` (WebSocket-Port, normalerweise `18789`)
- `sshPort` (optional; Clients verwenden standardmäßig `22` als SSH-Ziel, wenn er fehlt)
- `tailnetDns` (MagicDNS-Hostname, wenn verfügbar)
- `gatewayTls` / `gatewayTlsSha256` (TLS aktiviert + Zertifikat-Fingerabdruck)
- `gatewayPort` (WebSocket-Port, üblicherweise `18789`)
- `sshPort` (optional; Clients verwenden standardmäßig SSH-Ziele mit `22`, wenn er fehlt)
- `tailnetDns` (MagicDNS-Hostname, sofern verfügbar)
- `gatewayTls` / `gatewayTlsSha256` (TLS aktiviert + Zertifikatsfingerabdruck)
- `cliPath` (Remote-Installationshinweis, der in die Wide-Area-Zone geschrieben wird)
### `gateway discover`
@ -535,10 +536,10 @@ openclaw gateway discover
```
<ParamField path="--timeout <ms>" type="number" default="2000">
Timeout pro Befehl (Durchsuchen/Auflösen).
Zeitlimit pro Befehl (Durchsuchen/Auflösen).
</ParamField>
<ParamField path="--json" type="boolean">
Maschinenlesbare Ausgabe (deaktiviert auch Formatierung/Spinner).
Maschinenlesbare Ausgabe (deaktiviert auch Styling/Spinner).
</ParamField>
Beispiele:
@ -549,9 +550,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- Die CLI scannt `local.` plus die konfigurierte Wide-Area-Domain, wenn eine aktiviert ist.
- Die CLI durchsucht `local.` plus die konfigurierte Wide-Area-Domain, wenn eine aktiviert ist.
- `wsUrl` in der JSON-Ausgabe wird aus dem aufgelösten Service-Endpunkt abgeleitet, nicht aus reinen TXT-Hinweisen wie `lanHost` oder `tailnetDns`.
- Bei `local.`-mDNS werden `sshPort` und `cliPath` nur per Broadcast gesendet, wenn `discovery.mdns.mode` auf `full` gesetzt ist. Wide-Area-DNS-SD schreibt `cliPath` weiterhin; `sshPort` bleibt auch dort optional.
- Bei `local.` mDNS werden `sshPort` und `cliPath` nur gesendet, wenn `discovery.mdns.mode` auf `full` gesetzt ist. Wide-Area-DNS-SD schreibt weiterhin `cliPath`; `sshPort` bleibt dort ebenfalls optional.
</Note>

186
docs/de/cli/plugins.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Sie möchten Gateway-Plugins oder kompatible Bundles installieren oder verwalten
- Sie möchten Plugin-Ladefehler debuggen
- Sie möchten Ladefehler von Plugins debuggen
sidebarTitle: Plugins
summary: CLI-Referenz für `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
summary: CLI-Referenz für `openclaw plugins` (auflisten, installieren, Marketplace, deinstallieren, aktivieren/deaktivieren, Diagnose)
title: Plugins
x-i18n:
generated_at: "2026-05-04T09:37:07Z"
generated_at: "2026-05-05T01:44:20Z"
model: gpt-5.5
provider: openai
source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a
source_path: cli/plugins.md
workflow: 16
---
Verwalten Sie Gateway-Plugins, Hook-Pakete und kompatible Bundles.
Verwalten Sie Gateway-Plugins, Hook-Packs und kompatible Bundles.
<CardGroup cols={2}>
<Card title="Plugin system" href="/de/tools/plugin">
Endbenutzerleitfaden zum Installieren, Aktivieren und Beheben von Problemen mit Plugins.
<Card title="Plugin-System" href="/de/tools/plugin">
Leitfaden für Endbenutzer zum Installieren, Aktivieren und Beheben von Problemen mit Plugins.
</Card>
<Card title="Manage plugins" href="/de/plugins/manage-plugins">
Kurze Beispiele für Installation, Auflisten, Aktualisierung, Deinstallation und Veröffentlichung.
<Card title="Plugins verwalten" href="/de/plugins/manage-plugins">
Kurze Beispiele für Installation, Auflisten, Aktualisieren, Deinstallieren und Veröffentlichen.
</Card>
<Card title="Plugin bundles" href="/de/plugins/bundles">
Bundle-Kompatibilitätsmodell.
<Card title="Plugin-Bundles" href="/de/plugins/bundles">
Kompatibilitätsmodell für Bundles.
</Card>
<Card title="Plugin manifest" href="/de/plugins/manifest">
Manifestfelder und Konfigurationsschema.
<Card title="Plugin-Manifest" href="/de/plugins/manifest">
Manifest-Felder und Konfigurationsschema.
</Card>
<Card title="Security" href="/de/gateway/security">
<Card title="Sicherheit" href="/de/gateway/security">
Sicherheitshärtung für Plugin-Installationen.
</Card>
</CardGroup>
@ -62,16 +62,14 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Führen Sie zur Untersuchung langsamer Installations-, Prüf-, Deinstallations- oder Registry-Aktualisierungsvorgänge den
Befehl mit `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` aus. Der Trace schreibt Phasen-Timings
nach stderr und hält die JSON-Ausgabe parsebar. Siehe [Debugging](/de/help/debugging#plugin-lifecycle-trace).
Führen Sie für die Untersuchung langsamer Installations-, Inspektions-, Deinstallations- oder Registry-Refresh-Vorgänge den Befehl mit `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` aus. Der Trace schreibt Phasenzeiten nach stderr und hält JSON-Ausgaben parsebar. Siehe [Debugging](/de/help/debugging#plugin-lifecycle-trace).
<Note>
Gebündelte Plugins werden mit OpenClaw ausgeliefert. Einige sind standardmäßig aktiviert (zum Beispiel gebündelte Modell-Provider, gebündelte Sprach-Provider und das gebündelte Browser-Plugin); andere erfordern `plugins enable`.
Gebündelte Plugins werden mit OpenClaw ausgeliefert. Einige sind standardmäßig aktiviert, zum Beispiel gebündelte Modell-Provider, gebündelte Sprach-Provider und das gebündelte Browser-Plugin; andere erfordern `plugins enable`.
Native OpenClaw-Plugins müssen `openclaw.plugin.json` mit einem Inline-JSON-Schema (`configSchema`, auch wenn leer) ausliefern. Kompatible Bundles verwenden stattdessen ihre eigenen Bundle-Manifeste.
`plugins list` zeigt `Format: openclaw` oder `Format: bundle`. Ausführliche list/info-Ausgaben zeigen außerdem den Bundle-Subtyp (`codex`, `claude` oder `cursor`) sowie erkannte Bundle-Funktionen.
`plugins list` zeigt `Format: openclaw` oder `Format: bundle`. Ausführliche Listen-/Info-Ausgaben zeigen außerdem den Bundle-Subtyp (`codex`, `claude` oder `cursor`) sowie erkannte Bundle-Fähigkeiten.
</Note>
### Installieren
@ -96,65 +94,57 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
Reine Paketnamen werden während der Launch-Umstellung standardmäßig von npm installiert. Verwenden Sie `clawhub:<package>` für ClawHub. Behandeln Sie Plugin-Installationen wie das Ausführen von Code. Bevorzugen Sie gepinnte Versionen.
</Warning>
`plugins search` fragt ClawHub nach installierbaren Plugin-Paketen ab und gibt
installationsbereite Paketnamen aus. Es sucht Code-Plugin- und Bundle-Plugin-Pakete,
keine Skills. Verwenden Sie `openclaw skills search` für ClawHub-Skills.
`plugins search` fragt ClawHub nach installierbaren Plugin-Paketen ab und gibt installationsbereite Paketnamen aus. Es durchsucht Code-Plugin- und Bundle-Plugin-Pakete, nicht Skills. Verwenden Sie `openclaw skills search` für ClawHub-Skills.
<Note>
ClawHub ist die primäre Distributions- und Discovery-Oberfläche für die meisten Plugins. Npm
bleibt ein unterstützter Fallback- und Direktinstallationspfad. OpenClaw-eigene
`@openclaw/*`-Plugin-Pakete werden wieder auf npm veröffentlicht; die aktuelle Liste finden Sie
auf [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) oder im
[Plugin-Inventar](/de/plugins/plugin-inventory). Stabile Installationen verwenden `latest`.
Beta-Channel-Installationen und -Updates bevorzugen den npm-`beta`-Dist-Tag, wenn dieses Tag
verfügbar ist, und fallen dann auf `latest` zurück.
ClawHub ist die primäre Oberfläche für Verteilung und Auffindbarkeit der meisten Plugins. Npm bleibt ein unterstützter Fallback und direkter Installationspfad. OpenClaw-eigene `@openclaw/*`-Plugin-Pakete werden wieder auf npm veröffentlicht; die aktuelle Liste finden Sie auf [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) oder im [Plugin-Inventar](/de/plugins/plugin-inventory). Stabile Installationen verwenden `latest`. Installationen und Updates aus dem Beta-Kanal bevorzugen den npm-`beta`-dist-tag, wenn dieses Tag verfügbar ist, und fallen dann auf `latest` zurück.
</Note>
<AccordionGroup>
<Accordion title="Config includes and invalid-config repair">
Wenn Ihr Abschnitt `plugins` durch ein einzelnes Datei-`$include` gestützt wird, schreiben `plugins install/update/enable/disable/uninstall` in diese eingebundene Datei durch und lassen `openclaw.json` unverändert. Root-Includes, Include-Arrays und Includes mit danebenliegenden Überschreibungen scheitern geschlossen, statt abgeflacht zu werden. Siehe [Config-Includes](/de/gateway/configuration) für die unterstützten Formen.
<Accordion title="Konfigurations-Includes und Reparatur ungültiger Konfiguration">
Wenn Ihr Abschnitt `plugins` durch ein einzeiliges `$include` gesichert ist, schreiben `plugins install/update/enable/disable/uninstall` in diese eingebundene Datei durch und lassen `openclaw.json` unverändert. Root-Includes, Include-Arrays und Includes mit benachbarten Überschreibungen schlagen geschlossen fehl, statt abgeflacht zu werden. Siehe [Konfigurations-Includes](/de/gateway/configuration) für die unterstützten Formen.
Wenn die Konfiguration während der Installation ungültig ist, scheitert `plugins install` normalerweise geschlossen und fordert Sie auf, zuerst `openclaw doctor --fix` auszuführen. Beim Gateway-Start und Hot Reload scheitert ungültige Plugin-Konfiguration geschlossen wie jede andere ungültige Konfiguration; `openclaw doctor --fix` kann den ungültigen Plugin-Eintrag isolieren. Die einzige dokumentierte Ausnahme zur Installationszeit ist ein enger Wiederherstellungspfad für gebündelte Plugins, die sich explizit für `openclaw.install.allowInvalidConfigRecovery` entscheiden.
Wenn die Konfiguration während der Installation ungültig ist, schlägt `plugins install` normalerweise geschlossen fehl und weist Sie an, zuerst `openclaw doctor --fix` auszuführen. Beim Gateway-Start und beim Hot Reload schlägt eine ungültige Plugin-Konfiguration wie jede andere ungültige Konfiguration geschlossen fehl; `openclaw doctor --fix` kann den ungültigen Plugin-Eintrag quarantänisieren. Die einzige dokumentierte Ausnahme zur Installationszeit ist ein enger Wiederherstellungspfad für gebündelte Plugins, die sich ausdrücklich für `openclaw.install.allowInvalidConfigRecovery` entscheiden.
</Accordion>
<Accordion title="--force and reinstall vs update">
`--force` verwendet das vorhandene Installationsziel wieder und überschreibt ein bereits installiertes Plugin oder Hook-Paket direkt. Verwenden Sie es, wenn Sie dieselbe ID bewusst von einem neuen lokalen Pfad, Archiv, ClawHub-Paket oder npm-Artefakt neu installieren. Für routinemäßige Upgrades eines bereits verfolgten npm-Plugins bevorzugen Sie `openclaw plugins update <id-or-npm-spec>`.
<Accordion title="--force und Neuinstallation gegenüber Update">
`--force` verwendet das vorhandene Installationsziel wieder und überschreibt ein bereits installiertes Plugin oder Hook-Pack direkt. Verwenden Sie es, wenn Sie absichtlich dieselbe ID aus einem neuen lokalen Pfad, Archiv, ClawHub-Paket oder npm-Artefakt neu installieren. Für routinemäßige Upgrades eines bereits nachverfolgten npm-Plugins bevorzugen Sie `openclaw plugins update <id-or-npm-spec>`.
Wenn Sie `plugins install` für eine Plugin-ID ausführen, die bereits installiert ist, stoppt OpenClaw und verweist Sie für ein normales Upgrade auf `plugins update <id-or-npm-spec>` oder auf `plugins install <package> --force`, wenn Sie die aktuelle Installation wirklich aus einer anderen Quelle überschreiben möchten.
Wenn Sie `plugins install` für eine bereits installierte Plugin-ID ausführen, hält OpenClaw an und verweist Sie für ein normales Upgrade auf `plugins update <id-or-npm-spec>` oder auf `plugins install <package> --force`, wenn Sie die aktuelle Installation wirklich aus einer anderen Quelle überschreiben möchten.
</Accordion>
<Accordion title="--pin scope">
`--pin` gilt nur für npm-Installationen. Es wird mit `git:`-Installationen nicht unterstützt; verwenden Sie eine explizite Git-Referenz wie `git:github.com/acme/plugin@v1.2.3`, wenn Sie eine gepinnte Quelle möchten. Es wird mit `--marketplace` nicht unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation speichern.
<Accordion title="Geltungsbereich von --pin">
`--pin` gilt nur für npm-Installationen. Es wird bei `git:`-Installationen nicht unterstützt; verwenden Sie eine explizite Git-Ref wie `git:github.com/acme/plugin@v1.2.3`, wenn Sie eine gepinnte Quelle möchten. Es wird mit `--marketplace` nicht unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation speichern.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` ist eine Notfalloption für falsch positive Treffer im integrierten Scanner für gefährlichen Code. Sie erlaubt, dass die Installation fortgesetzt wird, auch wenn der integrierte Scanner `critical`-Befunde meldet, umgeht aber **keine** Plugin-`before_install`-Hook-Richtlinienblöcke und umgeht **keine** Scanfehler.
`--dangerously-force-unsafe-install` ist eine Notfalloption für False Positives im integrierten Scanner für gefährlichen Code. Sie erlaubt, dass die Installation fortgesetzt wird, auch wenn der integrierte Scanner `critical`-Befunde meldet, umgeht aber **keine** Policy-Sperren von Plugin-`before_install`-Hooks und umgeht **keine** Scan-Fehlschläge.
Dieses CLI-Flag gilt für Plugin-Installations-/Update-Abläufe. Gateway-gestützte Installationen von Skill-Abhängigkeiten verwenden die entsprechende `dangerouslyForceUnsafeInstall`-Request-Überschreibung, während `openclaw skills install` ein separater ClawHub-Skill-Download-/Installationsablauf bleibt.
Dieses CLI-Flag gilt für Plugin-Installations-/Update-Flows. Gateway-gestützte Skill-Abhängigkeitsinstallationen verwenden die passende Request-Überschreibung `dangerouslyForceUnsafeInstall`, während `openclaw skills install` ein separater ClawHub-Skill-Download-/Installations-Flow bleibt.
Wenn ein von Ihnen auf ClawHub veröffentlichtes Plugin durch einen Registry-Scan blockiert wird, verwenden Sie die Publisher-Schritte in [ClawHub](/de/tools/clawhub).
</Accordion>
<Accordion title="Hook packs and npm specs">
`plugins install` ist auch die Installationsoberfläche für Hook-Pakete, die `openclaw.hooks` in `package.json` bereitstellen. Verwenden Sie `openclaw hooks` für gefilterte Hook-Sichtbarkeit und Aktivierung einzelner Hooks, nicht für die Paketinstallation.
<Accordion title="Hook-Packs und npm-Spezifikationen">
`plugins install` ist auch die Installationsoberfläche für Hook-Packs, die `openclaw.hooks` in `package.json` bereitstellen. Verwenden Sie `openclaw hooks` für gefilterte Hook-Sichtbarkeit und Aktivierung einzelner Hooks, nicht für Paketinstallationen.
Npm-Spezifikationen sind **nur Registry** (Paketname + optionale **exakte Version** oder **Dist-Tag**). Git-/URL-/Dateispezifikationen und Semver-Bereiche werden abgelehnt. Abhängigkeitsinstallationen laufen aus Sicherheitsgründen projektlokal mit `--ignore-scripts`, selbst wenn Ihre Shell globale npm-Installationseinstellungen hat.
Npm-Spezifikationen sind **nur Registry** (Paketname + optionale **exakte Version** oder **dist-tag**). Git-/URL-/Datei-Spezifikationen und Semver-Bereiche werden abgelehnt. Abhängigkeitsinstallationen laufen aus Sicherheitsgründen projektlokal mit `--ignore-scripts`, selbst wenn Ihre Shell globale npm-Installationseinstellungen hat.
Verwenden Sie `npm:<package>`, wenn Sie die npm-Auflösung explizit machen möchten. Reine Paketspezifikationen werden während der Launch-Umstellung ebenfalls direkt von npm installiert.
Reine Spezifikationen und `@latest` bleiben auf dem stabilen Track. Datumsstempel-Korrekturversionen von OpenClaw wie `2026.5.3-1` sind für diese Prüfung stabile Releases. Wenn npm eine davon zu einem Prerelease auflöst, stoppt OpenClaw und fordert Sie auf, sich explizit mit einem Prerelease-Tag wie `@beta`/`@rc` oder einer exakten Prerelease-Version wie `@1.2.3-beta.4` zu entscheiden.
Reine Spezifikationen und `@latest` bleiben auf dem stabilen Track. Datumsstempel-Korrekturversionen von OpenClaw wie `2026.5.3-1` sind für diese Prüfung stabile Releases. Wenn npm eines davon zu einem Prerelease auflöst, hält OpenClaw an und fordert Sie auf, explizit mit einem Prerelease-Tag wie `@beta`/`@rc` oder einer exakten Prerelease-Version wie `@1.2.3-beta.4` zuzustimmen.
Wenn eine reine Installationsspezifikation mit einer offiziellen Plugin-ID übereinstimmt (zum Beispiel `diffs`), installiert OpenClaw den Katalogeintrag direkt. Um ein npm-Paket mit demselben Namen zu installieren, verwenden Sie eine explizite scoped Spezifikation (zum Beispiel `@scope/diffs`).
Wenn eine reine Installationsspezifikation mit einer offiziellen Plugin-ID übereinstimmt, zum Beispiel `diffs`, installiert OpenClaw den Katalogeintrag direkt. Um ein npm-Paket mit demselben Namen zu installieren, verwenden Sie eine explizite bereichsbezogene Spezifikation, zum Beispiel `@scope/diffs`.
</Accordion>
<Accordion title="Git repositories">
<Accordion title="Git-Repositorys">
Verwenden Sie `git:<repo>`, um direkt aus einem Git-Repository zu installieren. Unterstützte Formen umfassen `git:github.com/owner/repo`, `git:owner/repo`, vollständige `https://`-, `ssh://`-, `git://`-, `file://`- und `git@host:owner/repo.git`-Clone-URLs. Fügen Sie `@<ref>` oder `#<ref>` hinzu, um vor der Installation einen Branch, ein Tag oder einen Commit auszuchecken.
Git-Installationen klonen in ein temporäres Verzeichnis, checken die angeforderte Referenz aus, wenn vorhanden, und verwenden dann den normalen Plugin-Verzeichnisinstaller. Das bedeutet, dass Manifestvalidierung, Scan auf gefährlichen Code, Paketmanager-Installationsarbeit und Installationsdatensätze sich wie bei npm-Installationen verhalten. Aufgezeichnete Git-Installationen enthalten die Quell-URL/Referenz sowie den aufgelösten Commit, damit `openclaw plugins update` die Quelle später erneut auflösen kann.
Git-Installationen klonen in ein temporäres Verzeichnis, checken die angeforderte Ref aus, wenn vorhanden, und verwenden dann den normalen Plugin-Verzeichnis-Installer. Das bedeutet, dass Manifest-Validierung, Scans auf gefährlichen Code, Package-Manager-Installationsarbeit und Installationsdatensätze sich wie bei npm-Installationen verhalten. Aufgezeichnete Git-Installationen enthalten die Quell-URL/-Ref plus den aufgelösten Commit, damit `openclaw plugins update` die Quelle später erneut auflösen kann.
Verwenden Sie nach der Installation aus Git `openclaw plugins inspect <id> --runtime --json`, um Laufzeitregistrierungen wie Gateway-Methoden und CLI-Befehle zu prüfen. Wenn das Plugin eine CLI-Root mit `api.registerCli` registriert hat, führen Sie diesen Befehl direkt über die OpenClaw-Root-CLI aus, zum Beispiel `openclaw demo-plugin ping`.
Verwenden Sie nach der Installation aus Git `openclaw plugins inspect <id> --runtime --json`, um Laufzeitregistrierungen wie Gateway-Methoden und CLI-Befehle zu prüfen. Wenn das Plugin mit `api.registerCli` eine CLI-Root registriert hat, führen Sie diesen Befehl direkt über die OpenClaw-Root-CLI aus, zum Beispiel `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="Archives">
<Accordion title="Archive">
Unterstützte Archive: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Native OpenClaw-Plugin-Archive müssen ein gültiges `openclaw.plugin.json` im extrahierten Plugin-Root enthalten; Archive, die nur `package.json` enthalten, werden abgelehnt, bevor OpenClaw Installationsdatensätze schreibt.
Claude-Marketplace-Installationen werden ebenfalls unterstützt.
@ -175,14 +165,14 @@ Reine npm-sichere Plugin-Spezifikationen werden während der Launch-Umstellung s
openclaw plugins install openclaw-codex-app-server
```
Verwenden Sie `npm:`, um die npm-only-Auflösung explizit zu machen:
Verwenden Sie `npm:`, um die Nur-npm-Auflösung explizit zu machen:
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw prüft vor der Installation die angekündigte Plugin-API-/Mindest-Gateway-Kompatibilität. Wenn die ausgewählte ClawHub-Version ein ClawPack-Artefakt veröffentlicht, lädt OpenClaw das versionierte npm-Pack-`.tgz` herunter, verifiziert den ClawHub-Digest-Header und den Artefakt-Digest und installiert es dann über den normalen Archivpfad. Ältere ClawHub-Versionen ohne ClawPack-Metadaten werden weiterhin über den Legacy-Paketarchiv-Verifizierungspfad installiert. Aufgezeichnete Installationen behalten ihre ClawHub-Quellmetadaten, Artefaktart, npm-Integrität, npm-shasum, Tarball-Namen und ClawPack-Digest-Fakten für spätere Updates.
OpenClaw prüft die beworbene Plugin-API-/Mindest-Gateway-Kompatibilität vor der Installation. Wenn die ausgewählte ClawHub-Version ein ClawPack-Artefakt veröffentlicht, lädt OpenClaw das versionierte npm-pack-`.tgz` herunter, prüft den ClawHub-Digest-Header und den Artefakt-Digest und installiert es dann über den normalen Archivpfad. Ältere ClawHub-Versionen ohne ClawPack-Metadaten werden weiterhin über den alten Pfad zur Paketarchivprüfung installiert. Aufgezeichnete Installationen behalten ihre ClawHub-Quellmetadaten, Artefaktart, npm-Integrität, npm-Shasum, Tarball-Namen und ClawPack-Digest-Fakten für spätere Updates.
Unversionierte ClawHub-Installationen behalten eine unversionierte aufgezeichnete Spezifikation, damit `openclaw plugins update` neueren ClawHub-Releases folgen kann; explizite Versions- oder Tag-Selektoren wie `clawhub:pkg@1.2.3` und `clawhub:pkg@beta` bleiben an diesen Selektor gepinnt.
#### Marketplace-Kurzform
@ -206,14 +196,14 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
<Tabs>
<Tab title="Marketplace-Quellen">
- ein Claude-Name eines bekannten Marketplace aus `~/.claude/plugins/known_marketplaces.json`
- ein lokaler Marketplace-Stamm oder ein `marketplace.json`-Pfad
- eine GitHub-Repo-Kurzschreibweise wie `owner/repo`
- eine GitHub-Repo-URL wie `https://github.com/owner/repo`
- ein lokaler Marketplace-Stammordner oder `marketplace.json`-Pfad
- eine GitHub-Repository-Kurzform wie `owner/repo`
- eine GitHub-Repository-URL wie `https://github.com/owner/repo`
- eine Git-URL
</Tab>
<Tab title="Regeln für Remote-Marketplaces">
Bei Remote-Marketplaces, die aus GitHub oder Git geladen werden, müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repos bleiben. OpenClaw akzeptiert relative Pfadquellen aus diesem Repo und weist HTTP(S)-, absolute Pfad-, Git-, GitHub- und andere Nicht-Pfad-Plugin-Quellen aus Remote-Manifesten zurück.
Für Remote-Marketplaces, die von GitHub oder Git geladen werden, müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repositorys bleiben. OpenClaw akzeptiert relative Pfadquellen aus diesem Repository und weist HTTP(S)-, absolute Pfad-, Git-, GitHub- und andere Nicht-Pfad-Plugin-Quellen aus Remote-Manifesten zurück.
</Tab>
</Tabs>
@ -225,7 +215,7 @@ Für lokale Pfade und Archive erkennt OpenClaw automatisch:
- Cursor-kompatible Bundles (`.cursor-plugin/plugin.json`)
<Note>
Kompatible Bundles werden im normalen Plugin-Stamm installiert und nehmen am selben Ablauf für Auflisten/Info/Aktivieren/Deaktivieren teil. Heute werden Bundle-Skills, Claude-Command-Skills, Standardwerte aus Claude-`settings.json`, Standardwerte aus Claude-`.lsp.json` / per Manifest deklarierte `lspServers`, Cursor-Command-Skills und kompatible Codex-Hook-Verzeichnisse unterstützt; andere erkannte Bundle-Fähigkeiten werden in Diagnose/Info angezeigt, sind aber noch nicht in die Laufzeitausführung eingebunden.
Kompatible Bundles werden im normalen Plugin-Stammverzeichnis installiert und nehmen am selben Ablauf für Auflisten/Info/Aktivieren/Deaktivieren teil. Derzeit werden Bundle-Skills, Claude-Befehls-Skills, Claude-Standardwerte aus `settings.json`, Claude-Standardwerte aus `.lsp.json` / per Manifest deklarierte `lspServers`, Cursor-Befehls-Skills und kompatible Codex-Hook-Verzeichnisse unterstützt; andere erkannte Bundle-Fähigkeiten werden in Diagnosen/Info angezeigt, sind aber noch nicht in die Laufzeitausführung eingebunden.
</Note>
### Auflisten
@ -247,49 +237,53 @@ openclaw plugins search <query> --json
Von der Tabellenansicht zu Detailzeilen pro Plugin mit Metadaten zu Quelle/Ursprung/Version/Aktivierung wechseln.
</ParamField>
<ParamField path="--json" type="boolean">
Maschinenlesbares Inventar plus Registry-Diagnosen und Installationsstatus von Paketabhängigkeiten.
Maschinenlesbarer Bestand plus Registrierungsdiagnosen und Installationsstatus der Paketabhängigkeiten.
</ParamField>
<Note>
`plugins list` liest zuerst die dauerhaft gespeicherte lokale Plugin-Registry, mit einem nur aus Manifesten abgeleiteten Fallback, wenn die Registry fehlt oder ungültig ist. Das ist nützlich, um zu prüfen, ob ein Plugin installiert, aktiviert und für die Kaltstartplanung sichtbar ist, ist aber keine Live-Laufzeitprüfung eines bereits laufenden Gateway-Prozesses. Starten Sie nach Änderungen an Plugin-Code, Aktivierung, Hook-Richtlinie oder `plugins.load.paths` das Gateway neu, das den Kanal bereitstellt, bevor Sie erwarten, dass neuer `register(api)`-Code oder Hooks ausgeführt werden. Stellen Sie bei Remote-/Container-Bereitstellungen sicher, dass Sie den tatsächlichen untergeordneten `openclaw gateway run`-Prozess neu starten, nicht nur einen Wrapper-Prozess.
`plugins list` liest zuerst die persistierte lokale Plugin-Registry, mit einem nur aus Manifesten abgeleiteten Fallback, wenn die Registry fehlt oder ungültig ist. Das ist nützlich, um zu prüfen, ob ein Plugin installiert, aktiviert und für die Planung eines Kaltstarts sichtbar ist, aber es ist keine Live-Laufzeitprüfung eines bereits laufenden Gateway-Prozesses. Nachdem Sie Plugin-Code, Aktivierung, Hook-Richtlinie oder `plugins.load.paths` geändert haben, starten Sie den Gateway neu, der den Kanal bereitstellt, bevor Sie erwarten, dass neuer `register(api)`-Code oder Hooks ausgeführt werden. Prüfen Sie bei Remote-/Container-Bereitstellungen, dass Sie den tatsächlichen `openclaw gateway run`-Kindprozess neu starten, nicht nur einen Wrapper-Prozess.
`plugins list --json` enthält für jedes Plugin dessen `dependencyStatus` aus `package.json`
`dependencies` und `optionalDependencies`. OpenClaw prüft, ob diese Paketnamen entlang des normalen Node-`node_modules`-Suchpfads des Plugins vorhanden sind; es importiert keinen Plugin-Laufzeitcode, führt keinen Paketmanager aus und repariert keine fehlenden Abhängigkeiten.
`plugins list --json` enthält für jedes Plugin den `dependencyStatus` aus `package.json`
`dependencies` und `optionalDependencies`. OpenClaw prüft, ob diese Paketnamen
entlang des normalen Node-`node_modules`-Suchpfads des Plugins vorhanden sind; es
importiert keinen Plugin-Laufzeitcode, führt keinen Paketmanager aus und repariert
fehlende Abhängigkeiten nicht.
</Note>
`plugins search` ist eine Remote-ClawHub-Katalogsuche. Es prüft keinen lokalen
Status, verändert keine Konfiguration, installiert keine Pakete und lädt keinen Plugin-Laufzeitcode. Suchergebnisse enthalten den ClawHub-Paketnamen, die Familie, den Kanal, die Version, eine Zusammenfassung und
einen Installationshinweis wie `openclaw plugins install clawhub:<package>`.
`plugins search` ist eine Remote-ClawHub-Katalogsuche. Sie prüft keinen lokalen
Zustand, ändert keine Konfiguration, installiert keine Pakete und lädt keinen
Plugin-Laufzeitcode. Suchergebnisse enthalten den ClawHub-Paketnamen, die Familie,
den Kanal, die Version, die Zusammenfassung und einen Installationshinweis wie
`openclaw plugins install clawhub:<package>`.
Für Arbeiten an gebündelten Plugins innerhalb eines paketierten Docker-Images binden Sie das Plugin-Quellverzeichnis
über den passenden paketierten Quellpfad ein, z. B.
Für Arbeiten an gebündelten Plugins innerhalb eines paketierten Docker-Images binden Sie das Plugin-Quellverzeichnis per Bind-Mount über den passenden paketierten Quellpfad ein, zum Beispiel
`/app/extensions/synology-chat`. OpenClaw erkennt dieses eingehängte Quell-Overlay
vor `/app/dist/extensions/synology-chat`; ein einfach kopiertes Quellverzeichnis
bleibt inaktiv, sodass normale paketierte Installationen weiterhin das kompilierte Dist verwenden.
bleibt inaktiv, sodass normale paketierte Installationen weiterhin die kompilierte Distribution verwenden.
Für das Debugging von Laufzeit-Hooks:
Für die Laufzeit-Hook-Fehlersuche:
- `openclaw plugins inspect <id> --runtime --json` zeigt registrierte Hooks und Diagnosen aus einem Inspektionsdurchlauf mit geladenem Modul. Die Laufzeitinspektion installiert niemals Abhängigkeiten; verwenden Sie `openclaw doctor --fix`, um veralteten Abhängigkeitszustand zu bereinigen oder fehlende konfigurierte herunterladbare Plugins zu installieren.
- `openclaw gateway status --deep --require-rpc` bestätigt das erreichbare Gateway, Dienst-/Prozesshinweise, den Konfigurationspfad und die RPC-Funktionsfähigkeit.
- `openclaw plugins inspect <id> --runtime --json` zeigt registrierte Hooks und Diagnosen aus einem Inspektionsdurchlauf mit geladenem Modul. Die Laufzeitinspektion installiert niemals Abhängigkeiten; verwenden Sie `openclaw doctor --fix`, um veralteten Abhängigkeitszustand zu bereinigen oder fehlende herunterladbare Plugins wiederherzustellen, auf die in der Konfiguration verwiesen wird.
- `openclaw gateway status --deep --require-rpc` bestätigt den erreichbaren Gateway, Dienst-/Prozesshinweise, den Konfigurationspfad und die RPC-Funktionsfähigkeit.
- Nicht gebündelte Konversations-Hooks (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) erfordern `plugins.entries.<id>.hooks.allowConversationAccess=true`.
Verwenden Sie `--link`, um das Kopieren eines lokalen Verzeichnisses zu vermeiden (fügt es `plugins.load.paths` hinzu):
Verwenden Sie `--link`, um das Kopieren eines lokalen Verzeichnisses zu vermeiden (fügt zu `plugins.load.paths` hinzu):
```bash
openclaw plugins install -l ./my-plugin
```
<Note>
`--force` wird mit `--link` nicht unterstützt, weil verknüpfte Installationen den Quellpfad wiederverwenden, anstatt über ein verwaltetes Installationsziel zu kopieren.
`--force` wird mit `--link` nicht unterstützt, weil verlinkte Installationen den Quellpfad wiederverwenden, statt über ein verwaltetes Installationsziel zu kopieren.
Verwenden Sie `--pin` bei npm-Installationen, um die aufgelöste exakte Spezifikation (`name@version`) im verwalteten Plugin-Index zu speichern, während das Standardverhalten ungepinnt bleibt.
Verwenden Sie `--pin` bei npm-Installationen, um die aufgelöste exakte Spezifikation (`name@version`) im verwalteten Plugin-Index zu speichern, während das Standardverhalten unfixiert bleibt.
</Note>
### Plugin-Index
Plugin-Installationsmetadaten sind maschinell verwalteter Zustand, keine Benutzerkonfiguration. Installationen und Aktualisierungen schreiben sie in `plugins/installs.json` unter dem aktiven OpenClaw-Zustandsverzeichnis. Die oberste `installRecords`-Map ist die dauerhafte Quelle der Installationsmetadaten, einschließlich Einträgen für defekte oder fehlende Plugin-Manifeste. Das `plugins`-Array ist der aus Manifesten abgeleitete Kalt-Registry-Cache. Die Datei enthält eine Warnung, sie nicht zu bearbeiten, und wird von `openclaw plugins update`, Deinstallation, Diagnosen und der Kalt-Plugin-Registry verwendet.
Plugin-Installationsmetadaten sind maschinenverwalteter Zustand, keine Benutzerkonfiguration. Installationen und Aktualisierungen schreiben sie unter `plugins/installs.json` in das aktive OpenClaw-Zustandsverzeichnis. Die oberste `installRecords`-Map ist die dauerhafte Quelle für Installationsmetadaten, einschließlich Einträgen für beschädigte oder fehlende Plugin-Manifeste. Das `plugins`-Array ist der aus Manifesten abgeleitete Kalt-Registry-Cache. Die Datei enthält eine Nicht-bearbeiten-Warnung und wird von `openclaw plugins update`, Deinstallation, Diagnosen und der kalten Plugin-Registry verwendet.
Wenn OpenClaw ausgelieferte veraltete `plugins.installs`-Einträge in der Konfiguration sieht, verschiebt es sie in den Plugin-Index und entfernt den Konfigurationsschlüssel; wenn einer der Schreibvorgänge fehlschlägt, bleiben die Konfigurationseinträge erhalten, damit die Installationsmetadaten nicht verloren gehen.
Wenn OpenClaw ausgelieferte Legacy-`plugins.installs`-Einträge in der Konfiguration sieht, verschiebt es sie in den Plugin-Index und entfernt den Konfigurationsschlüssel; wenn einer der Schreibvorgänge fehlschlägt, bleiben die Konfigurationseinträge erhalten, damit die Installationsmetadaten nicht verloren gehen.
### Deinstallieren
@ -299,7 +293,7 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` entfernt Plugin-Einträge aus `plugins.entries`, dem dauerhaft gespeicherten Plugin-Index, den Allow-/Deny-List-Einträgen für Plugins und, falls zutreffend, verknüpften `plugins.load.paths`-Einträgen. Sofern `--keep-files` nicht gesetzt ist, entfernt die Deinstallation außerdem das nachverfolgte verwaltete Installationsverzeichnis, wenn es sich innerhalb des Plugin-Erweiterungsstamms von OpenClaw befindet. Bei Active-Memory-Plugins wird der Speicher-Slot auf `memory-core` zurückgesetzt.
`uninstall` entfernt Plugin-Einträge aus `plugins.entries`, dem persistierten Plugin-Index, den Plugin-Erlaubnis-/Sperrlisten-Einträgen und, sofern zutreffend, verlinkten `plugins.load.paths`-Einträgen. Sofern `--keep-files` nicht gesetzt ist, entfernt die Deinstallation auch das nachverfolgte verwaltete Installationsverzeichnis, wenn es innerhalb des Plugin-Erweiterungsstammverzeichnisses von OpenClaw liegt. Bei Active-Memory-Plugins wird der Speicher-Slot auf `memory-core` zurückgesetzt.
<Note>
`--keep-config` wird als veralteter Alias für `--keep-files` unterstützt.
@ -315,29 +309,29 @@ openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Aktualisierungen gelten für nachverfolgte Plugin-Installationen im verwalteten Plugin-Index und nachverfolgte Hook-Pack-Installationen in `hooks.internal.installs`.
Aktualisierungen gelten für nachverfolgte Plugin-Installationen im verwalteten Plugin-Index und für nachverfolgte Hook-Pack-Installationen in `hooks.internal.installs`.
<AccordionGroup>
<Accordion title="Plugin-ID gegenüber npm-Spezifikation auflösen">
Wenn Sie eine Plugin-ID übergeben, verwendet OpenClaw die für dieses Plugin aufgezeichnete Installationsspezifikation wieder. Das bedeutet, dass zuvor gespeicherte Dist-Tags wie `@beta` und exakt gepinnte Versionen auch bei späteren `update <id>`-Läufen weiter verwendet werden.
Wenn Sie eine Plugin-ID übergeben, verwendet OpenClaw die für dieses Plugin aufgezeichnete Installationsspezifikation erneut. Das bedeutet, dass zuvor gespeicherte Dist-Tags wie `@beta` und exakt fixierte Versionen bei späteren `update <id>`-Läufen weiterverwendet werden.
Für npm-Installationen können Sie auch eine explizite npm-Paketspezifikation mit einem Dist-Tag oder einer exakten Version übergeben. OpenClaw löst diesen Paketnamen wieder auf den nachverfolgten Plugin-Eintrag auf, aktualisiert dieses installierte Plugin und zeichnet die neue npm-Spezifikation für zukünftige ID-basierte Aktualisierungen auf.
Bei npm-Installationen können Sie auch eine explizite npm-Paketspezifikation mit einem Dist-Tag oder einer exakten Version übergeben. OpenClaw löst diesen Paketnamen zurück auf den nachverfolgten Plugin-Eintrag auf, aktualisiert dieses installierte Plugin und zeichnet die neue npm-Spezifikation für zukünftige ID-basierte Aktualisierungen auf.
Wenn Sie den npm-Paketnamen ohne Version oder Tag übergeben, wird er ebenfalls wieder auf den nachverfolgten Plugin-Eintrag aufgelöst. Verwenden Sie dies, wenn ein Plugin auf eine exakte Version gepinnt war und Sie es zurück auf die Standard-Release-Linie der Registry verschieben möchten.
Wenn Sie den npm-Paketnamen ohne Version oder Tag übergeben, wird er ebenfalls zurück auf den nachverfolgten Plugin-Eintrag aufgelöst. Verwenden Sie dies, wenn ein Plugin auf eine exakte Version fixiert war und Sie es wieder auf die Standard-Release-Linie der Registry zurückführen möchten.
</Accordion>
<Accordion title="Beta-Kanal-Aktualisierungen">
`openclaw plugins update` verwendet die nachverfolgte Plugin-Spezifikation wieder, sofern Sie keine neue Spezifikation übergeben. `openclaw update` kennt zusätzlich den aktiven OpenClaw-Aktualisierungskanal: Auf dem Beta-Kanal versuchen npm- und ClawHub-Plugin-Einträge der Standardlinie zuerst `@beta` und fallen dann auf die aufgezeichnete Standard-/Latest-Spezifikation zurück, wenn kein Plugin-Beta-Release existiert. Exakte Versionen und explizite Tags bleiben an diesen Selektor gepinnt.
<Accordion title="Aktualisierungen im Beta-Kanal">
`openclaw plugins update` verwendet die nachverfolgte Plugin-Spezifikation erneut, sofern Sie keine neue Spezifikation übergeben. `openclaw update` kennt zusätzlich den aktiven OpenClaw-Aktualisierungskanal: Im Beta-Kanal versuchen npm- und ClawHub-Plugin-Einträge der Standardlinie zuerst `@beta` und fallen dann auf die aufgezeichnete Standard-/Latest-Spezifikation zurück, wenn keine Plugin-Beta-Version existiert. Exakte Versionen und explizite Tags bleiben an diesen Selektor gebunden.
</Accordion>
<Accordion title="Versionsprüfungen und Integritätsabweichungen">
Vor einer Live-npm-Aktualisierung prüft OpenClaw die installierte Paketversion anhand der npm-Registry-Metadaten. Wenn die installierte Version und die aufgezeichnete Artefaktidentität bereits mit dem aufgelösten Ziel übereinstimmen, wird die Aktualisierung übersprungen, ohne etwas herunterzuladen, neu zu installieren oder `openclaw.json` neu zu schreiben.
Vor einer Live-npm-Aktualisierung prüft OpenClaw die installierte Paketversion gegen die Metadaten der npm-Registry. Wenn die installierte Version und die aufgezeichnete Artefaktidentität bereits mit dem aufgelösten Ziel übereinstimmen, wird die Aktualisierung übersprungen, ohne herunterzuladen, neu zu installieren oder `openclaw.json` neu zu schreiben.
Wenn ein gespeicherter Integritäts-Hash vorhanden ist und sich der Hash des abgerufenen Artefakts ändert, behandelt OpenClaw dies als npm-Artefaktabweichung. Der interaktive Befehl `openclaw plugins update` gibt die erwarteten und tatsächlichen Hashes aus und fragt vor dem Fortfahren nach Bestätigung. Nicht interaktive Aktualisierungshelfer schlagen geschlossen fehl, sofern der Aufrufer keine explizite Fortsetzungsrichtlinie bereitstellt.
Wenn ein gespeicherter Integritäts-Hash existiert und sich der Hash des abgerufenen Artefakts ändert, behandelt OpenClaw dies als npm-Artefaktabweichung. Der interaktive Befehl `openclaw plugins update` gibt die erwarteten und tatsächlichen Hashes aus und bittet um Bestätigung, bevor er fortfährt. Nicht interaktive Aktualisierungshelfer schlagen geschlossen fehl, sofern der Aufrufer keine explizite Fortsetzungsrichtlinie bereitstellt.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install bei update">
`--dangerously-force-unsafe-install` ist auch bei `plugins update` als Notfall-Override für falsch positive Treffer des integrierten Dangerous-Code-Scans während Plugin-Aktualisierungen verfügbar. Es umgeht weiterhin keine Plugin-`before_install`-Richtliniensperren oder Sperren aufgrund von Scan-Fehlern und gilt nur für Plugin-Aktualisierungen, nicht für Hook-Pack-Aktualisierungen.
<Accordion title="--dangerously-force-unsafe-install bei Aktualisierung">
`--dangerously-force-unsafe-install` ist auch bei `plugins update` als Notfall-Override für falsch positive Treffer des integrierten Gefährlicher-Code-Scans während Plugin-Aktualisierungen verfügbar. Es umgeht weiterhin keine Plugin-`before_install`-Richtlinienblockaden oder Blockaden durch Scan-Fehler und gilt nur für Plugin-Aktualisierungen, nicht für Hook-Pack-Aktualisierungen.
</Accordion>
</AccordionGroup>
@ -349,11 +343,11 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Inspect zeigt Identität, Ladestatus, Quelle, Manifest-Fähigkeiten, Richtlinien-Flags, Diagnosen, Installationsmetadaten, Bundle-Fähigkeiten und jede erkannte MCP- oder LSP-Serverunterstützung an, ohne standardmäßig Plugin-Laufzeit zu importieren. Fügen Sie `--runtime` hinzu, um das Plugin-Modul zu laden und registrierte Hooks, Tools, Befehle, Dienste, Gateway-Methoden und HTTP-Routen einzubeziehen. Die Laufzeitinspektion meldet fehlende Plugin-Abhängigkeiten direkt; Installationen und Reparaturen bleiben in `openclaw plugins install`, `openclaw plugins update` und `openclaw doctor --fix`.
Inspect zeigt Identität, Ladestatus, Quelle, Manifestfähigkeiten, Richtlinien-Flags, Diagnosen, Installationsmetadaten, Bundle-Fähigkeiten und jede erkannte MCP- oder LSP-Server-Unterstützung an, ohne standardmäßig Plugin-Laufzeit zu importieren. Fügen Sie `--runtime` hinzu, um das Plugin-Modul zu laden und registrierte Hooks, Tools, Befehle, Dienste, Gateway-Methoden und HTTP-Routen einzuschließen. Die Laufzeitinspektion meldet fehlende Plugin-Abhängigkeiten direkt; Installationen und Reparaturen bleiben in `openclaw plugins install`, `openclaw plugins update` und `openclaw doctor --fix`.
Plugin-eigene CLI-Befehle werden als Root-`openclaw`-Befehlsgruppen installiert. Nachdem `inspect --runtime` einen Befehl unter `cliCommands` anzeigt, führen Sie ihn als `openclaw <command> ...` aus; zum Beispiel kann ein Plugin, das `demo-git` registriert, mit `openclaw demo-git ping` verifiziert werden.
Plugin-eigene CLI-Befehle werden als Stamm-`openclaw`-Befehlsgruppen installiert. Nachdem `inspect --runtime` einen Befehl unter `cliCommands` anzeigt, führen Sie ihn als `openclaw <command> ...` aus; zum Beispiel kann ein Plugin, das `demo-git` registriert, mit `openclaw demo-git ping` geprüft werden.
Jedes Plugin wird danach klassifiziert, was es zur Laufzeit tatsächlich registriert:
Jedes Plugin wird danach klassifiziert, was es tatsächlich zur Laufzeit registriert:
- **plain-capability** — ein Fähigkeitstyp (z. B. ein reines Provider-Plugin)
- **hybrid-capability** — mehrere Fähigkeitstypen (z. B. Text + Sprache + Bilder)
@ -363,7 +357,7 @@ Jedes Plugin wird danach klassifiziert, was es zur Laufzeit tatsächlich registr
Weitere Informationen zum Fähigkeitsmodell finden Sie unter [Plugin-Formen](/de/plugins/architecture#plugin-shapes).
<Note>
Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der sich für Skripting und Audits eignet. `inspect --all` rendert eine flottenweite Tabelle mit Spalten für Form, Fähigkeitsarten, Kompatibilitätshinweise, Bundle-Fähigkeiten und Hook-Zusammenfassung. `info` ist ein Alias für `inspect`.
Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der für Skripting und Audits geeignet ist. `inspect --all` rendert eine flottenweite Tabelle mit Spalten für Form, Fähigkeitsarten, Kompatibilitätshinweise, Bundle-Fähigkeiten und Hook-Zusammenfassung. `info` ist ein Alias für `inspect`.
</Note>
### Doctor
@ -372,11 +366,11 @@ Das Flag `--json` gibt einen maschinenlesbaren Bericht aus, der sich für Skript
openclaw plugins doctor
```
`doctor` meldet Plugin-Ladefehler, Manifest-/Discovery-Diagnosen und Kompatibilitätshinweise. Wenn alles sauber ist, gibt es `No plugin issues detected.` aus.
`doctor` meldet Plugin-Ladefehler, Manifest-/Erkennungsdiagnosen und Kompatibilitätshinweise. Wenn alles sauber ist, gibt es `No plugin issues detected.` aus.
Wenn ein konfiguriertes Plugin auf der Festplatte vorhanden ist, aber durch die Pfadsicherheitsprüfungen des Loaders blockiert wird, behält die Konfigurationsvalidierung den Plugin-Eintrag bei und meldet ihn als `present but blocked`. Beheben Sie die vorangehende Diagnose zum blockierten Plugin, etwa Pfadbesitz oder weltweit schreibbare Berechtigungen, statt die Konfiguration `plugins.entries.<id>` oder `plugins.allow` zu entfernen.
Wenn ein konfiguriertes Plugin auf dem Datenträger vorhanden ist, aber durch die Pfadsicherheitsprüfungen des Loaders blockiert wird, behält die Konfigurationsvalidierung den Plugin-Eintrag bei und meldet ihn als `present but blocked`. Beheben Sie die vorhergehende Diagnose zum blockierten Plugin, etwa Pfadeigentum oder weltweit beschreibbare Berechtigungen, statt die Konfiguration `plugins.entries.<id>` oder `plugins.allow` zu entfernen.
Bei Modulform-Fehlern wie fehlenden `register`-/`activate`-Exporten führen Sie den Befehl mit `OPENCLAW_PLUGIN_LOAD_DEBUG=1` erneut aus, um eine kompakte Zusammenfassung der Exportform in die Diagnoseausgabe aufzunehmen.
Bei Modulform-Fehlern wie fehlenden `register`/`activate`-Exporten führen Sie den Befehl erneut mit `OPENCLAW_PLUGIN_LOAD_DEBUG=1` aus, um eine kompakte Zusammenfassung der Exportform in die Diagnoseausgabe aufzunehmen.
### Registry
@ -386,14 +380,14 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
Die lokale Plugin-Registry ist OpenClaws dauerhaft gespeichertes Kalt-Lesemodell für installierte Plugin-Identität, Aktivierung, Quellenmetadaten und Verantwortlichkeit für Beiträge. Normaler Start, Provider-Owner-Lookup, Klassifizierung des Kanal-Setups und Plugin-Inventar können sie lesen, ohne Plugin-Laufzeitmodule zu importieren.
Die lokale Plugin-Registry ist das persistierte Kaltlesemodell von OpenClaw für installierte Plugin-Identität, Aktivierung, Quellenmetadaten und Beitragsverantwortung. Normaler Start, Provider-Besitzerauflösung, Klassifizierung der Kanaleinrichtung und Plugin-Bestand können sie lesen, ohne Plugin-Laufzeitmodule zu importieren.
Verwenden Sie `plugins registry`, um zu prüfen, ob die persistierte Registry vorhanden, aktuell oder veraltet ist. Verwenden Sie `--refresh`, um sie aus dem persistierten Plugin-Index, der Konfigurationsrichtlinie und den Manifest-/Paketmetadaten neu aufzubauen. Dies ist ein Reparaturpfad, kein Pfad zur Laufzeitaktivierung.
`openclaw doctor --fix` repariert außerdem Registry-nahe Abweichungen bei verwaltetem npm: Wenn ein verwaistes oder wiederhergestelltes `@openclaw/*`-Paket unter dem verwalteten Plugin-npm-Root ein gebündeltes Plugin überschattet, entfernt doctor dieses veraltete Paket und baut die Registry neu auf, damit der Start gegen das gebündelte Manifest validiert.
`openclaw doctor --fix` repariert außerdem verwaltete npm-Abweichungen im Umfeld der Registry: Wenn ein verwaistes oder wiederhergestelltes `@openclaw/*`-Paket unter dem verwalteten Plugin-npm-Root ein gebündeltes Plugin überschattet, entfernt doctor dieses veraltete Paket und baut die Registry neu auf, sodass der Start gegen das gebündelte Manifest validiert.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` ist ein veralteter Notfall-Kompatibilitätsschalter für Registry-Lesefehler. Bevorzugen Sie `plugins registry --refresh` oder `openclaw doctor --fix`; der Env-Fallback ist nur für die Notfall-Wiederherstellung beim Start vorgesehen, während die Migration ausgerollt wird.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` ist ein veralteter Notfall-Kompatibilitätsschalter für Lesefehler der Registry. Bevorzugen Sie `plugins registry --refresh` oder `openclaw doctor --fix`; der Umgebungs-Fallback ist nur für die Notfallwiederherstellung beim Start vorgesehen, während die Migration ausgerollt wird.
</Warning>
### Marktplatz
@ -403,9 +397,9 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Die Marktplatzliste akzeptiert einen lokalen Marktplatzpfad, einen `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL. `--json` gibt das aufgelöste Quelllabel sowie das geparste Marktplatzmanifest und die Plugin-Einträge aus.
Der Marktplatz-Listenbefehl akzeptiert einen lokalen Marktplatzpfad, einen `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL. `--json` gibt die aufgelöste Quellbezeichnung sowie das geparste Marktplatzmanifest und die Plugin-Einträge aus.
## Verwandte Themen
## Zugehörige Themen
- [Plugins erstellen](/de/plugins/building-plugins)
- [CLI-Referenz](/de/cli)

73
docs/de/cli/sessions.md
View File

@ -1,52 +1,70 @@
---
read_when:
- Sie möchten gespeicherte Sitzungen auflisten und aktuelle Aktivitäten anzeigen
summary: CLI-Referenz für `openclaw sessions` (gespeicherte Sitzungen auflisten + Nutzung)
summary: CLI-Referenz für `openclaw sessions` (gespeicherte Sitzungen auflisten + Verwendung)
title: Sitzungen
x-i18n:
generated_at: "2026-05-04T06:41:15Z"
generated_at: "2026-05-05T01:44:08Z"
model: gpt-5.5
provider: openai
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7
source_path: cli/sessions.md
workflow: 16
---
# `openclaw sessions`
Gespeicherte Konversationssitzungen auflisten.
Listet gespeicherte Konversationssitzungen auf.
Sitzungslisten sind keine Liveness-Prüfungen für Kanäle/Provider. Sie zeigen persistierte Konversationszeilen aus Sitzungsspeichern. Ein inaktiver Discord-, Slack-, Telegram- oder anderer Kanal kann sich erfolgreich neu verbinden, ohne eine neue Sitzungszeile zu erstellen, bis eine Nachricht verarbeitet wird. Verwenden Sie `openclaw channels status --probe`, `openclaw status --deep` oder `openclaw health --verbose`, wenn Sie Live-Kanalkonnektivität benötigen.
Sitzungslisten sind keine Live-Prüfungen für Kanäle/Provider. Sie zeigen persistierte
Konversationszeilen aus Sitzungsspeichern. Ein inaktiver Discord-, Slack-, Telegram- oder
anderer Kanal kann erfolgreich wiederverbunden werden, ohne eine neue Sitzungszeile
anzulegen, bis eine Nachricht verarbeitet wird. Verwenden Sie `openclaw channels status --probe`,
`openclaw status --deep` oder `openclaw health --verbose`, wenn Sie Live-
Kanalverbindung benötigen.
Gateway-`sessions.list`-Antworten sind standardmäßig begrenzt, damit große, langlebige Speicher die Gateway-Ereignisschleife nicht monopolisieren können. Übergeben Sie von RPC-Clients ein explizites positives `limit`, wenn ein anderes Ergebnisfenster benötigt wird; Antworten enthalten `totalCount`, `limitApplied` und `hasMore`, wenn Aufrufer anzeigen müssen, dass weitere Zeilen vorhanden sind.
`openclaw sessions`- und Gateway-`sessions.list`-Antworten sind standardmäßig
begrenzt, damit große, langlebige Stores den CLI-Prozess oder den Gateway-
Event-Loop nicht monopolisieren können. Die CLI gibt standardmäßig die neuesten 100 Sitzungen zurück; übergeben Sie
`--limit <n>` für ein kleineres/größeres Fenster oder `--limit all`, wenn Sie bewusst
den vollständigen Store benötigen. JSON-Antworten enthalten `totalCount`, `limitApplied` und
`hasMore`, wenn Aufrufer anzeigen müssen, dass weitere Zeilen vorhanden sind.
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --verbose
openclaw sessions --json
```
Bereichsauswahl:
- Standard: konfigurierter Speicher des Standard-Agents
- Standard: konfigurierter Standard-Agent-Store
- `--verbose`: ausführliche Protokollierung
- `--agent <id>`: ein konfigurierter Agent-Speicher
- `--all-agents`: alle konfigurierten Agent-Speicher aggregieren
- `--store <path>`: expliziter Speicherpfad (kann nicht mit `--agent` oder `--all-agents` kombiniert werden)
- `--agent <id>`: ein konfigurierter Agent-Store
- `--all-agents`: alle konfigurierten Agent-Stores zusammenfassen
- `--store <path>`: expliziter Store-Pfad (kann nicht mit `--agent` oder `--all-agents` kombiniert werden)
- `--limit <n|all>`: maximale Anzahl auszugebender Zeilen (Standard `100`; `all` stellt die vollständige Ausgabe wieder her)
Ein Trajectory-Bundle für eine gespeicherte Sitzung exportieren:
Exportieren Sie ein Trajectory-Bundle für eine gespeicherte Sitzung:
```bash
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
```
Dies ist der Befehlspfad, der vom Slash-Befehl `/export-trajectory` verwendet wird, nachdem der Owner die Exec-Anforderung genehmigt hat. Das Ausgabeverzeichnis wird immer innerhalb von `.openclaw/trajectory-exports/` unter dem ausgewählten Workspace aufgelöst.
Dies ist der Befehlspfad, der vom Slash-Befehl `/export-trajectory` verwendet wird, nachdem
der Owner die Ausführungsanfrage genehmigt hat. Das Ausgabeverzeichnis wird immer
innerhalb von `.openclaw/trajectory-exports/` unter dem ausgewählten Workspace aufgelöst.
`openclaw sessions --all-agents` liest konfigurierte Agent-Speicher. Die Sitzungserkennung von Gateway und ACP ist breiter: Sie schließt auch reine Datenträgerspeicher ein, die unter dem standardmäßigen `agents/`-Root oder einem vorlagenbasierten `session.store`-Root gefunden werden. Diese erkannten Speicher müssen zu regulären `sessions.json`-Dateien innerhalb des Agent-Roots aufgelöst werden; Symlinks und Pfade außerhalb des Roots werden übersprungen.
`openclaw sessions --all-agents` liest konfigurierte Agent-Stores. Die Sitzungserkennung von Gateway und ACP
ist breiter: Sie umfasst auch reine Datenträger-Stores, die unter dem
Standard-Root `agents/` oder einem vorlagenbasierten `session.store`-Root gefunden werden. Diese
entdeckten Stores müssen zu regulären `sessions.json`-Dateien innerhalb des
Agent-Roots aufgelöst werden; Symlinks und Pfade außerhalb des Roots werden übersprungen.
JSON-Beispiele:
@ -61,6 +79,9 @@ JSON-Beispiele:
],
"allAgents": true,
"count": 2,
"totalCount": 2,
"limitApplied": 100,
"hasMore": false,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
@ -69,9 +90,9 @@ JSON-Beispiele:
}
```
## Cleanup-Wartung
## Wartung der Bereinigung
Wartung jetzt ausführen (statt auf den nächsten Schreibzyklus zu warten):
Führen Sie die Wartung jetzt aus (statt auf den nächsten Schreibzyklus zu warten):
```bash
openclaw sessions cleanup --dry-run
@ -82,21 +103,23 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123
openclaw sessions cleanup --json
```
`openclaw sessions cleanup` verwendet die `session.maintenance`-Einstellungen aus der Konfiguration:
`openclaw sessions cleanup` verwendet `session.maintenance`-Einstellungen aus der Konfiguration:
- Bereichshinweis: `openclaw sessions cleanup` wartet Sitzungsspeicher, Transkripte und Trajectory-Sidecars. Es bereinigt keine Cron-Ausführungsprotokolle (`cron/runs/<jobId>.jsonl`); diese werden durch `cron.runLog.maxBytes` und `cron.runLog.keepLines` in der [Cron-Konfiguration](/de/automation/cron-jobs#configuration) verwaltet und in der [Cron-Wartung](/de/automation/cron-jobs#maintenance) erläutert.
- Hinweis zum Bereich: `openclaw sessions cleanup` wartet Sitzungsspeicher, Transkripte und Trajectory-Sidecars. Es bereinigt keine Cron-Ausführungsprotokolle (`cron/runs/<jobId>.jsonl`), die über `cron.runLog.maxBytes` und `cron.runLog.keepLines` in der [Cron-Konfiguration](/de/automation/cron-jobs#configuration) verwaltet und in der [Cron-Wartung](/de/automation/cron-jobs#maintenance) erläutert werden.
- `--dry-run`: Vorschau, wie viele Einträge ohne Schreiben bereinigt/begrenzt würden.
- Im Textmodus gibt der Probelauf eine Aktionstabelle pro Sitzung aus (`Action`, `Key`, `Age`, `Model`, `Flags`), damit Sie sehen können, was beibehalten oder entfernt würde.
- `--enforce`: Wartung anwenden, auch wenn `session.maintenance.mode` auf `warn` gesetzt ist.
- `--fix-missing`: Einträge entfernen, deren Transkriptdateien fehlen, selbst wenn sie normalerweise noch nicht aufgrund von Alter/Anzahl entfernt würden.
- `--active-key <key>`: einen bestimmten aktiven Schlüssel vor der Entfernung aufgrund des Datenträgerbudgets schützen. Dauerhafte externe Konversationszeiger, wie Gruppensitzungen und threadbezogene Chat-Sitzungen, werden ebenfalls durch Wartung nach Alter/Anzahl/Datenträgerbudget beibehalten.
- `--agent <id>`: Cleanup für einen konfigurierten Agent-Speicher ausführen.
- `--all-agents`: Cleanup für alle konfigurierten Agent-Speicher ausführen.
- Im Textmodus gibt dry-run eine Aktionstabelle pro Sitzung aus (`Action`, `Key`, `Age`, `Model`, `Flags`), damit Sie sehen können, was beibehalten bzw. entfernt würde.
- `--enforce`: Wartung anwenden, auch wenn `session.maintenance.mode` `warn` ist.
- `--fix-missing`: Einträge entfernen, deren Transkriptdateien fehlen, auch wenn sie normalerweise noch nicht nach Alter/Anzahl aussortiert würden.
- `--active-key <key>`: einen bestimmten aktiven Schlüssel vor der Verdrängung durch das Datenträgerbudget schützen. Dauerhafte externe Konversationszeiger, etwa Gruppensitzungen und threadbezogene Chatsitzungen, werden ebenfalls durch Wartung nach Alter/Anzahl/Datenträgerbudget beibehalten.
- `--agent <id>`: Bereinigung für einen konfigurierten Agent-Store ausführen.
- `--all-agents`: Bereinigung für alle konfigurierten Agent-Stores ausführen.
- `--store <path>`: gegen eine bestimmte `sessions.json`-Datei ausführen.
- `--json`: eine JSON-Zusammenfassung ausgeben. Mit `--all-agents` enthält die Ausgabe eine Zusammenfassung pro Speicher.
- `--json`: eine JSON-Zusammenfassung ausgeben. Mit `--all-agents` enthält die Ausgabe eine Zusammenfassung pro Store.
Wenn ein Gateway erreichbar ist, wird Cleanup ohne Probelauf für konfigurierte Agent-Speicher über das Gateway gesendet, damit derselbe Sitzungsspeicher-Writer wie beim Laufzeitverkehr verwendet wird. Verwenden Sie `--store <path>` für die explizite Offline-Reparatur einer Speicherdatei.
Wenn ein Gateway erreichbar ist, wird eine nicht als dry-run ausgeführte Bereinigung für konfigurierte Agent-Stores
über das Gateway gesendet, sodass sie denselben Sitzungsspeicher-Writer wie der Laufzeit-
Datenverkehr nutzt. Verwenden Sie `--store <path>` für eine explizite Offline-Reparatur einer Store-Datei.
`openclaw sessions cleanup --all-agents --dry-run --json`:

140
docs/de/cli/update.md
View File

@ -2,21 +2,21 @@
read_when:
- Sie möchten einen Quellcode-Checkout sicher aktualisieren
- Sie debuggen die Ausgabe oder Optionen von `openclaw update`
- Sie müssen das Verhalten der `--update`-Kurzschreibweise verstehen
summary: CLI-Referenz für `openclaw update` (relativ sichere Quellcode-Aktualisierung + automatischer Gateway-Neustart)
- Sie müssen das Verhalten der Kurzschreibweise `--update` verstehen
summary: CLI-Referenz für `openclaw update` (relativ sichere Quellcodeaktualisierung + automatischer Gateway-Neustart)
title: Aktualisieren
x-i18n:
generated_at: "2026-05-03T21:29:48Z"
generated_at: "2026-05-05T01:44:57Z"
model: gpt-5.5
provider: openai
source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8
source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f
source_path: cli/update.md
workflow: 16
---
# `openclaw update`
Aktualisieren Sie OpenClaw sicher und wechseln Sie zwischen Stable-, Beta- und Dev-Kanälen.
Aktualisieren Sie OpenClaw sicher und wechseln Sie zwischen Stable-/Beta-/Dev-Kanälen.
Wenn Sie über **npm/pnpm/bun** installiert haben (globale Installation, keine Git-Metadaten),
erfolgen Updates über den Paketmanager-Ablauf in [Aktualisierung](/de/install/updating).
@ -40,24 +40,23 @@ openclaw --update
## Optionen
- `--no-restart`: Überspringt den Neustart des Gateway-Diensts nach einem erfolgreichen Update. Paketmanager-Updates, die den Gateway neu starten, prüfen, ob der neu gestartete Dienst die erwartete aktualisierte Version meldet, bevor der Befehl erfolgreich abgeschlossen wird.
- `--no-restart`: Überspringt den Neustart des Gateway-Dienstes nach einem erfolgreichen Update. Paketmanager-Updates, die das Gateway neu starten, prüfen vor dem erfolgreichen Abschluss des Befehls, ob der neu gestartete Dienst die erwartete aktualisierte Version meldet.
- `--channel <stable|beta|dev>`: Legt den Update-Kanal fest (Git + npm; wird in der Konfiguration gespeichert).
- `--tag <dist-tag|version|spec>`: Überschreibt das Paketziel nur für dieses Update. Bei Paketinstallationen wird `main` auf `github:openclaw/openclaw#main` abgebildet.
- `--dry-run`: Zeigt die geplanten Update-Aktionen (Kanal/Tag/Ziel/Neustart-Ablauf) an, ohne Konfiguration zu schreiben, zu installieren, Plugins zu synchronisieren oder neu zu starten.
- `--dry-run`: Zeigt die geplanten Update-Aktionen (Kanal/Tag/Ziel/Neustartablauf) als Vorschau an, ohne Konfiguration zu schreiben, zu installieren, Plugins zu synchronisieren oder neu zu starten.
- `--json`: Gibt maschinenlesbares `UpdateRunResult`-JSON aus, einschließlich
`postUpdate.plugins.integrityDrifts`, wenn beim Plugin-Sync nach dem Update
Abweichungen bei npm-Plugin-Artefakten erkannt werden.
- `--timeout <seconds>`: Timeout pro Schritt (Standard ist 1800 s).
- `--yes`: Überspringt Bestätigungsabfragen (zum Beispiel Downgrade-Bestätigung).
`postUpdate.plugins.integrityDrifts`, wenn während der Plugin-Synchronisierung
nach dem Update Drift bei npm-Plugin-Artefakten erkannt wird.
- `--timeout <seconds>`: Zeitlimit pro Schritt (Standard ist 1800s).
- `--yes`: Überspringt Bestätigungsaufforderungen (zum Beispiel die Bestätigung für ein Downgrade).
`openclaw update` hat kein `--verbose`-Flag. Verwenden Sie `--dry-run`, um die
geplanten Kanal-/Tag-/Installations-/Neustart-Aktionen vorab anzuzeigen,
`--json` für maschinenlesbare Ergebnisse und `openclaw update status --json`,
wenn Sie nur Kanal- und Verfügbarkeitsdetails benötigen. Wenn Sie Gateway-Logs
rund um ein Update debuggen, sind Konsolen-Ausführlichkeit und Datei-Log-Level
getrennt: Gateway `--verbose` beeinflusst Terminal-/WebSocket-Ausgaben,
während Datei-Logs `logging.level: "debug"` oder `"trace"` in der Konfiguration
erfordern. Siehe [Gateway-Logging](/de/gateway/logging).
`openclaw update` hat kein `--verbose`-Flag. Verwenden Sie `--dry-run`, um eine Vorschau
der geplanten Kanal-/Tag-/Installations-/Neustartaktionen anzuzeigen, `--json` für maschinenlesbare
Ergebnisse und `openclaw update status --json`, wenn Sie nur Kanal- und
Verfügbarkeitsdetails benötigen. Wenn Sie Gateway-Protokolle rund um ein Update debuggen,
sind Konsolenausführlichkeit und Datei-Protokollstufe getrennt: Gateway `--verbose` beeinflusst
Terminal-/WebSocket-Ausgabe, während Datei-Protokolle `logging.level: "debug"` oder
`"trace"` in der Konfiguration erfordern. Siehe [Gateway-Protokollierung](/de/gateway/logging).
<Warning>
Downgrades erfordern eine Bestätigung, da ältere Versionen die Konfiguration beschädigen können.
@ -65,7 +64,7 @@ Downgrades erfordern eine Bestätigung, da ältere Versionen die Konfiguration b
## `update status`
Zeigt den aktiven Update-Kanal + Git-Tag/Branch/SHA (bei Quell-Checkouts) sowie die Update-Verfügbarkeit an.
Zeigt den aktiven Update-Kanal + Git-Tag/-Branch/-SHA (für Quellcode-Checkouts) sowie die Update-Verfügbarkeit an.
```bash
openclaw update status
@ -76,19 +75,19 @@ openclaw update status --timeout 10
Optionen:
- `--json`: Gibt maschinenlesbares Status-JSON aus.
- `--timeout <seconds>`: Timeout für Prüfungen (Standard ist 3 s).
- `--timeout <seconds>`: Zeitlimit für Prüfungen (Standard ist 3s).
## `update wizard`
Interaktiver Ablauf zum Auswählen eines Update-Kanals und zum Bestätigen, ob der Gateway
nach dem Update neu gestartet werden soll (Standard ist Neustart). Wenn Sie `dev` ohne Git-Checkout auswählen,
Interaktiver Ablauf zur Auswahl eines Update-Kanals und zur Bestätigung, ob das Gateway
nach der Aktualisierung neu gestartet werden soll (Standard ist Neustart). Wenn Sie `dev` ohne Git-Checkout auswählen,
wird angeboten, einen zu erstellen.
Optionen:
- `--timeout <seconds>`: Timeout für jeden Update-Schritt (Standard `1800`)
- `--timeout <seconds>`: Zeitlimit für jeden Update-Schritt (Standard `1800`)
## Was es macht
## Funktionsweise
Wenn Sie Kanäle explizit wechseln (`--channel ...`), hält OpenClaw auch die
Installationsmethode synchron:
@ -96,51 +95,51 @@ Installationsmethode synchron:
- `dev` → stellt einen Git-Checkout sicher (Standard: `~/openclaw`, überschreibbar mit `OPENCLAW_GIT_DIR`),
aktualisiert ihn und installiert die globale CLI aus diesem Checkout.
- `stable` → installiert aus npm mit `latest`.
- `beta` → bevorzugt den npm-dist-tag `beta`, fällt aber auf `latest` zurück, wenn beta
- `beta` → bevorzugt den npm-Dist-Tag `beta`, fällt aber auf `latest` zurück, wenn Beta
fehlt oder älter als die aktuelle Stable-Version ist.
Der automatische Updater des Gateway-Kerns (wenn per Konfiguration aktiviert) startet den CLI-Update-Pfad
außerhalb des Live-Gateway-Request-Handlers. Control-Plane-`update.run`-Paketmanager-
Updates erzwingen nach dem Pakettausch einen nicht aufgeschobenen Update-Neustart ohne Cooldown,
da der alte Gateway-Prozess möglicherweise noch In-Memory-Chunks hat, die auf
Dateien zeigen, die vom neuen Paket entfernt wurden.
Updates erzwingen nach dem Pakettausch einen nicht verzögerten Update-Neustart ohne Abklingzeit,
weil der alte Gateway-Prozess möglicherweise noch In-Memory-Chunks enthält, die auf
Dateien zeigen, die durch das neue Paket entfernt wurden.
Bei Paketmanager-Installationen löst `openclaw update` die Zielpaketversion auf,
bevor der Paketmanager aufgerufen wird. Globale npm-Installationen verwenden eine gestaffelte
Bei Paketmanager-Installationen löst `openclaw update` die Zielpaketversion
auf, bevor der Paketmanager aufgerufen wird. Globale npm-Installationen verwenden eine gestaffelte
Installation: OpenClaw installiert das neue Paket in ein temporäres npm-Präfix, prüft
dort das paketierte `dist`-Inventar und tauscht dann diesen sauberen Paketbaum in das
echte globale Präfix ein. Wenn die Prüfung fehlschlägt, werden Doctor nach dem Update,
Plugin-Sync und Neustartarbeiten nicht aus dem verdächtigen Baum ausgeführt. Selbst wenn die installierte Version
dort das gepackte `dist`-Inventar und tauscht dann diesen sauberen Paketbaum in das
echte globale Präfix. Wenn die Prüfung fehlschlägt, werden Doctor nach dem Update, Plugin-Synchronisierung und
Neustartarbeiten nicht aus dem verdächtigen Baum ausgeführt. Selbst wenn die installierte Version
bereits dem Ziel entspricht, aktualisiert der Befehl die globale Paketinstallation,
führt dann Plugin-Sync, eine Aktualisierung der Core-Command-Completion und Neustartarbeiten aus. Dadurch
bleiben paketierte Sidecars und kanalverwaltete Plugin-Datensätze mit dem
installierten OpenClaw-Build synchron, während vollständige Neuaufbauten der Plugin-Command-Completion
führt anschließend Plugin-Synchronisierung, eine Aktualisierung der Kernbefehlsvervollständigung und Neustartarbeiten aus. Dadurch
bleiben gepackte Sidecars und kanalverwaltete Plugin-Datensätze mit dem
installierten OpenClaw-Build synchron, während vollständige Neuaufbauten der Plugin-Befehlsvervollständigung
expliziten `openclaw completion --write-state`-Läufen vorbehalten bleiben.
Wenn ein lokaler verwalteter Gateway-Dienst installiert und Neustart aktiviert ist,
stoppen Paketmanager-Updates den laufenden Dienst, bevor der Paketbaum ersetzt wird,
Wenn ein lokal verwalteter Gateway-Dienst installiert und Neustart aktiviert ist,
stoppen Paketmanager-Updates den laufenden Dienst vor dem Ersetzen des Paketbaums,
aktualisieren dann die Dienstmetadaten aus der aktualisierten Installation, starten den
Dienst neu und prüfen, ob der neu gestartete Gateway die erwartete Version meldet,
bevor Erfolg gemeldet wird. Unter macOS prüft die Nach-Update-Prüfung außerdem, ob der LaunchAgent
für das aktive Profil geladen/ausgeführt wird und der konfigurierte loopback-Port
funktionsfähig ist. Wenn die plist installiert ist, aber nicht von launchd überwacht wird, bootstrapt OpenClaw
den LaunchAgent automatisch neu und führt dann die
Bereitschaftsprüfungen für Zustand/Version/Kanal erneut aus. Ein frischer Bootstrap lädt den RunAtLoad-
Job direkt, daher führt die Update-Wiederherstellung nicht sofort `kickstart -k` für den neu
gestarteten Gateway aus. Wenn der Gateway weiterhin nicht gesund wird, beendet sich der Befehl
mit einem Fehlercode ungleich null und gibt den Neustart-Logpfad sowie explizite Anweisungen
für Neustart, Neuinstallation und Paket-Rollback aus. Mit `--no-restart`
läuft der Paketaustausch weiterhin, aber der verwaltete Dienst wird nicht gestoppt oder
neu gestartet, sodass der laufende Gateway alten Code behalten kann, bis Sie ihn
Dienst neu und prüfen, ob das neu gestartete Gateway die erwartete Version meldet, bevor
Erfolg gemeldet wird. Unter macOS prüft die Prüfung nach dem Update außerdem, ob der LaunchAgent
für das aktive Profil geladen/ausgeführt wird und der konfigurierte Loopback-Port
fehlerfrei ist. Wenn die plist installiert ist, aber nicht von launchd überwacht wird, bootstrapt OpenClaw
den LaunchAgent automatisch neu und führt anschließend die
Health-/Versions-/Kanal-Bereitschaftsprüfungen erneut aus. Ein frischer Bootstrap lädt den RunAtLoad-
Job direkt, sodass die Update-Wiederherstellung das neu
gestartete Gateway nicht sofort mit `kickstart -k` startet. Wenn das Gateway weiterhin nicht fehlerfrei wird, beendet sich der Befehl
mit einem Nicht-Null-Code und gibt den Pfad zum Neustartprotokoll sowie explizite Anweisungen für Neustart, Neuinstallation und
Paket-Rollback aus. Mit `--no-restart`
wird der Paketersatz weiterhin ausgeführt, aber der verwaltete Dienst wird nicht gestoppt oder
neu gestartet, sodass das laufende Gateway alten Code behalten kann, bis Sie es
manuell neu starten.
## Git-Checkout-Ablauf
### Kanalauswahl
- `stable`: Checkt den neuesten Nicht-Beta-Tag aus, baut anschließend und führt Doctor aus.
- `beta`: Bevorzugt den neuesten `-beta`-Tag, fällt aber auf den neuesten Stable-Tag zurück, wenn beta fehlt oder älter ist.
- `dev`: Checkt `main` aus, führt dann Fetch und Rebase aus.
- `stable`: Checkt das neueste Nicht-Beta-Tag aus, baut anschließend und führt Doctor aus.
- `beta`: Bevorzugt das neueste `-beta`-Tag, fällt aber auf das neueste Stable-Tag zurück, wenn Beta fehlt oder älter ist.
- `dev`: Checkt `main` aus, führt anschließend Fetch und Rebase aus.
### Update-Schritte
@ -155,49 +154,50 @@ manuell neu starten.
Nur Dev.
</Step>
<Step title="Preflight-Build (nur Dev)">
Führt Lint und TypeScript-Build in einem temporären Worktree aus. Wenn der Tip fehlschlägt, geht es bis zu 10 Commits zurück, um den neuesten sauberen Build zu finden.
Führt Lint und TypeScript-Build in einem temporären Worktree aus. Wenn die Spitze fehlschlägt, geht der Ablauf bis zu 10 Commits zurück, um den neuesten sauberen Build zu finden.
</Step>
<Step title="Rebase">
Führt einen Rebase auf den ausgewählten Commit aus (nur Dev).
</Step>
<Step title="Abhängigkeiten installieren">
Verwendet den Paketmanager des Repos. Bei pnpm-Checkouts bootstrapt der Updater `pnpm` bei Bedarf (zuerst über `corepack`, dann als Fallback über ein temporäres `npm install pnpm@10`), anstatt `npm run build` innerhalb eines pnpm-Workspaces auszuführen.
Verwendet den Paketmanager des Repos. Bei pnpm-Checkouts bootstrapt der Updater `pnpm` bei Bedarf (zuerst über `corepack`, dann als Fallback ein temporäres `npm install pnpm@10`), anstatt `npm run build` innerhalb eines pnpm-Workspaces auszuführen.
</Step>
<Step title="Control UI bauen">
Baut den Gateway und die Control UI.
Baut das Gateway und die Control UI.
</Step>
<Step title="Doctor ausführen">
`openclaw doctor` läuft als abschließende Safe-Update-Prüfung.
`openclaw doctor` wird als finale Safe-Update-Prüfung ausgeführt.
</Step>
<Step title="Plugins synchronisieren">
Synchronisiert Plugins mit dem aktiven Kanal. Dev verwendet gebündelte Plugins; stable und beta verwenden npm. Aktualisiert nachverfolgte Plugin-Installationen.
Synchronisiert Plugins mit dem aktiven Kanal. Dev verwendet gebündelte Plugins; Stable und Beta verwenden npm. Aktualisiert nachverfolgte Plugin-Installationen.
</Step>
</Steps>
Im Beta-Update-Kanal versuchen nachverfolgte npm- und ClawHub-Plugin-Installationen, die der
default/latest-Linie folgen, zuerst ein Plugin-Release `@beta`. Wenn das Plugin kein
Beta-Release hat, fällt OpenClaw auf die aufgezeichnete default/latest-Spezifikation zurück. Exakte
Versionen und explizite Tags werden nicht umgeschrieben.
Auf dem Beta-Update-Kanal versuchen nachverfolgte npm- und ClawHub-Plugin-Installationen, die der
Standard-/Latest-Linie folgen, zuerst eine Plugin-`@beta`-Version. Wenn das Plugin keine
Beta-Version hat, fällt OpenClaw auf die aufgezeichnete Standard-/Latest-Spezifikation zurück. Bei npm-
Plugins fällt OpenClaw auch zurück, wenn das Beta-Paket existiert, aber die Installationsvalidierung
fehlschlägt. Exakte Versionen und explizite Tags werden nicht umgeschrieben.
<Warning>
Wenn ein exakt gepinntes npm-Plugin-Update zu einem Artefakt aufgelöst wird, dessen Integrität vom gespeicherten Installationsdatensatz abweicht, bricht `openclaw update` dieses Plugin-Artefakt-Update ab, anstatt es zu installieren. Installieren oder aktualisieren Sie das Plugin nur dann explizit neu, nachdem Sie geprüft haben, dass Sie dem neuen Artefakt vertrauen.
Wenn ein exakt gepinntes npm-Plugin-Update zu einem Artefakt aufgelöst wird, dessen Integrität vom gespeicherten Installationsdatensatz abweicht, bricht `openclaw update` dieses Plugin-Artefakt-Update ab, statt es zu installieren. Installieren oder aktualisieren Sie das Plugin erst dann explizit, nachdem Sie geprüft haben, dass Sie dem neuen Artefakt vertrauen.
</Warning>
<Note>
Fehler beim Plugin-Sync nach dem Update lassen das Update-Ergebnis fehlschlagen und stoppen nachgelagerte Neustartarbeiten. Beheben Sie den Plugin-Installations- oder Update-Fehler und führen Sie dann `openclaw update` erneut aus.
Fehler bei der Plugin-Synchronisierung nach dem Update lassen das Update-Ergebnis fehlschlagen und stoppen die nachfolgenden Neustartarbeiten. Beheben Sie den Plugin-Installations- oder Update-Fehler und führen Sie anschließend `openclaw update` erneut aus.
Wenn der aktualisierte Gateway startet, ist das Laden von Plugins nur eine Prüfung: Der Start führt keine Paketmanager aus und verändert keine Abhängigkeitsbäume. Paketmanager-`update.run`-Neustarts umgehen die normale Idle-Aufschiebung und den Neustart-Cooldown, nachdem der Paketbaum ausgetauscht wurde, sodass der alte Prozess entfernte Chunks nicht weiter per Lazy Loading laden kann.
Wenn das aktualisierte Gateway startet, ist das Laden von Plugins nur prüfend: Der Start führt keine Paketmanager aus und verändert keine Abhängigkeitsbäume. Paketmanager-`update.run`-Neustarts umgehen die normale Leerlaufverzögerung und Neustart-Abklingzeit, nachdem der Paketbaum getauscht wurde, sodass der alte Prozess entfernte Chunks nicht weiter lazy-loaden kann.
Wenn der pnpm-Bootstrap weiterhin fehlschlägt, stoppt der Updater früh mit einem paketmanager-spezifischen Fehler, anstatt `npm run build` innerhalb des Checkouts zu versuchen.
Wenn der pnpm-Bootstrap weiterhin fehlschlägt, stoppt der Updater frühzeitig mit einem paketmanager-spezifischen Fehler, statt `npm run build` innerhalb des Checkouts zu versuchen.
</Note>
## `--update`-Kurzform
`openclaw --update` wird zu `openclaw update` umgeschrieben (nützlich für Shells und Launcher-Skripte).
## Verwandt
## Verwandte Themen
- `openclaw doctor` (bietet bei Git-Checkouts an, zuerst update auszuführen)
- [Development-Kanäle](/de/install/development-channels)
- `openclaw doctor` (bietet bei Git-Checkouts an, zuerst ein Update auszuführen)
- [Entwicklungskanäle](/de/install/development-channels)
- [Aktualisierung](/de/install/updating)
- [CLI-Referenz](/de/cli)

153
docs/de/concepts/models.md
View File

@ -1,23 +1,23 @@
---
read_when:
- Hinzufügen oder Ändern der models-CLI (models list/set/scan/aliases/fallbacks)
- Modell-Fallback-Verhalten oder Auswahl-UX ändern
- Modellscan-Probes aktualisieren (Tools/Bilder)
- Modelle-CLI hinzufügen oder ändern (models list/set/scan/aliases/fallbacks)
- Ändern des Fallback-Verhaltens für Modelle oder der Auswahl-UX
- Aktualisieren von Modellscan-Prüfungen (Tools/Bilder)
sidebarTitle: Models CLI
summary: 'Modelle-CLI: Auflisten, Festlegen, Aliasse, Fallbacks, Scannen, Status'
summary: 'Modelle-CLI: list, set, aliases, fallbacks, scan, status'
title: Modelle-CLI
x-i18n:
generated_at: "2026-05-02T20:45:41Z"
generated_at: "2026-05-05T01:45:06Z"
model: gpt-5.5
provider: openai
source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f
source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f
source_path: concepts/models.md
workflow: 16
---
<CardGroup cols={2}>
<Card title="Modell-Failover" href="/de/concepts/model-failover">
Rotation von Auth-Profilen, Cooldowns und wie dies mit Fallbacks zusammenspielt.
Auth-Profil-Rotation, Cooldowns und wie dies mit Fallbacks zusammenspielt.
</Card>
<Card title="Modell-Provider" href="/de/concepts/model-providers">
Kurzer Provider-Überblick und Beispiele.
@ -26,11 +26,11 @@ x-i18n:
PI, Codex und andere Agent-Loop-Laufzeiten.
</Card>
<Card title="Konfigurationsreferenz" href="/de/gateway/config-agents#agent-defaults">
Modellkonfigurationsschlüssel.
Modell-Konfigurationsschlüssel.
</Card>
</CardGroup>
Modell-Refs wählen einen Provider und ein Modell aus. Normalerweise wählen sie nicht die Low-Level-Agent-Laufzeit aus. Beispielsweise kann `openai/gpt-5.5` je nach `agents.defaults.agentRuntime.id` über den normalen OpenAI-Provider-Pfad oder über die Codex-App-Server-Laufzeit ausgeführt werden. Im Codex-Laufzeitmodus bedeutet die Ref `openai/gpt-*` keine Abrechnung über API-Schlüssel; die Authentifizierung kann über ein Codex-Konto oder ein Auth-Profil `openai-codex` erfolgen. Siehe [Agent-Laufzeiten](/de/concepts/agent-runtimes).
Modellreferenzen wählen einen Provider und ein Modell aus. Sie wählen normalerweise nicht die Low-Level-Agent-Laufzeit aus. Beispielsweise kann `openai/gpt-5.5` je nach `agents.defaults.agentRuntime.id` über den normalen OpenAI-Provider-Pfad oder über die Codex-App-Server-Laufzeit ausgeführt werden. Im Codex-Laufzeitmodus bedeutet die Referenz `openai/gpt-*` keine Abrechnung über API-Schlüssel; die Authentifizierung kann aus einem Codex-Konto oder einem `openai-codex`-Auth-Profil stammen. Siehe [Agent-Laufzeiten](/de/concepts/agent-runtimes).
## So funktioniert die Modellauswahl
@ -41,42 +41,42 @@ OpenClaw wählt Modelle in dieser Reihenfolge aus:
`agents.defaults.model.primary` (oder `agents.defaults.model`).
</Step>
<Step title="Fallbacks">
`agents.defaults.model.fallbacks` (in Reihenfolge).
`agents.defaults.model.fallbacks` (in dieser Reihenfolge).
</Step>
<Step title="Provider-Auth-Failover">
Auth-Failover erfolgt innerhalb eines Providers, bevor zum nächsten Modell gewechselt wird.
Auth-Failover findet innerhalb eines Providers statt, bevor zum nächsten Modell gewechselt wird.
</Step>
</Steps>
<AccordionGroup>
<Accordion title="Verwandte Modelloberflächen">
- `agents.defaults.models` ist die Allowlist/der Katalog der Modelle, die OpenClaw verwenden kann (plus Aliasse).
- `agents.defaults.imageModel` wird **nur dann** verwendet, wenn das primäre Modell keine Bilder akzeptieren kann.
- `agents.defaults.pdfModel` wird vom Tool `pdf` verwendet. Falls ausgelassen, fällt das Tool auf `agents.defaults.imageModel` und dann auf das aufgelöste Sitzungs-/Standardmodell zurück.
- `agents.defaults.imageGenerationModel` wird von der gemeinsamen Bildgenerierungsfunktion verwendet. Falls ausgelassen, kann `image_generate` weiterhin einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die übrigen registrierten Bildgenerierungs-Provider in Reihenfolge der Provider-ID. Wenn Sie einen bestimmten Provider/ein bestimmtes Modell festlegen, konfigurieren Sie auch die Authentifizierung/den API-Schlüssel dieses Providers.
- `agents.defaults.musicGenerationModel` wird von der gemeinsamen Musikgenerierungsfunktion verwendet. Falls ausgelassen, kann `music_generate` weiterhin einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die übrigen registrierten Musikgenerierungs-Provider in Reihenfolge der Provider-ID. Wenn Sie einen bestimmten Provider/ein bestimmtes Modell festlegen, konfigurieren Sie auch die Authentifizierung/den API-Schlüssel dieses Providers.
- `agents.defaults.videoGenerationModel` wird von der gemeinsamen Videogenerierungsfunktion verwendet. Falls ausgelassen, kann `video_generate` weiterhin einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und dann die übrigen registrierten Videogenerierungs-Provider in Reihenfolge der Provider-ID. Wenn Sie einen bestimmten Provider/ein bestimmtes Modell festlegen, konfigurieren Sie auch die Authentifizierung/den API-Schlüssel dieses Providers.
- Agent-spezifische Standards können `agents.defaults.model` über `agents.list[].model` plus Bindungen überschreiben (siehe [Multi-Agent-Routing](/de/concepts/multi-agent)).
- `agents.defaults.models` ist die Allowlist/der Katalog der Modelle, die OpenClaw verwenden kann (plus Aliase).
- `agents.defaults.imageModel` wird **nur verwendet, wenn** das primäre Modell keine Bilder akzeptieren kann.
- `agents.defaults.pdfModel` wird vom `pdf`-Tool verwendet. Wenn es ausgelassen wird, fällt das Tool auf `agents.defaults.imageModel` und danach auf das aufgelöste Sitzungs-/Standardmodell zurück.
- `agents.defaults.imageGenerationModel` wird von der gemeinsam genutzten Bildgenerierungsfähigkeit verwendet. Wenn es ausgelassen wird, kann `image_generate` dennoch einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die übrigen registrierten Bildgenerierungs-Provider in Provider-ID-Reihenfolge. Wenn Sie einen bestimmten Provider/ein bestimmtes Modell festlegen, konfigurieren Sie auch die Authentifizierung/den API-Schlüssel dieses Providers.
- `agents.defaults.musicGenerationModel` wird von der gemeinsam genutzten Musikgenerierungsfähigkeit verwendet. Wenn es ausgelassen wird, kann `music_generate` dennoch einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die übrigen registrierten Musikgenerierungs-Provider in Provider-ID-Reihenfolge. Wenn Sie einen bestimmten Provider/ein bestimmtes Modell festlegen, konfigurieren Sie auch die Authentifizierung/den API-Schlüssel dieses Providers.
- `agents.defaults.videoGenerationModel` wird von der gemeinsam genutzten Videogenerierungsfähigkeit verwendet. Wenn es ausgelassen wird, kann `video_generate` dennoch einen auth-gestützten Provider-Standard ableiten. Es versucht zuerst den aktuellen Standard-Provider und danach die übrigen registrierten Videogenerierungs-Provider in Provider-ID-Reihenfolge. Wenn Sie einen bestimmten Provider/ein bestimmtes Modell festlegen, konfigurieren Sie auch die Authentifizierung/den API-Schlüssel dieses Providers.
- Pro-Agent-Standards können `agents.defaults.model` über `agents.list[].model` plus Bindings überschreiben (siehe [Multi-Agent-Routing](/de/concepts/multi-agent)).
</Accordion>
</AccordionGroup>
## Auswahlquelle und Fallback-Verhalten
Dasselbe `provider/model` kann je nach Herkunft unterschiedliche Dinge bedeuten:
Dasselbe `provider/model` kann je nach Herkunft Unterschiedliches bedeuten:
- Konfigurierte Standards (`agents.defaults.model.primary` und Agent-spezifische primäre Modelle) sind der normale Ausgangspunkt und verwenden `agents.defaults.model.fallbacks`.
- Automatische Fallback-Auswahlen sind temporärer Wiederherstellungszustand. Sie werden mit `modelOverrideSource: "auto"` gespeichert, damit spätere Turns die Fallback-Kette weiterverwenden können, ohne zuerst ein bekannt fehlerhaftes primäres Modell zu testen.
- Benutzerauswahlen für Sitzungen sind exakt. `/model`, der Modell-Picker, `session_status(model=...)` und `sessions.patch` speichern `modelOverrideSource: "user"`; wenn dieser ausgewählte Provider/dieses ausgewählte Modell nicht erreichbar ist, schlägt OpenClaw sichtbar fehl, statt auf ein anderes konfiguriertes Modell weiterzufallen.
- Konfigurierte Standards (`agents.defaults.model.primary` und agent-spezifische primäre Modelle) sind der normale Ausgangspunkt und verwenden `agents.defaults.model.fallbacks`.
- Automatische Fallback-Auswahlen sind ein temporärer Wiederherstellungszustand. Sie werden mit `modelOverrideSource: "auto"` gespeichert, damit spätere Turns die Fallback-Kette weiter verwenden können, ohne zuerst ein bekanntermaßen fehlerhaftes primäres Modell zu prüfen.
- Benutzersitzungsauswahlen sind exakt. `/model`, der Modellauswähler, `session_status(model=...)` und `sessions.patch` speichern `modelOverrideSource: "user"`; wenn dieser ausgewählte Provider/dieses Modell nicht erreichbar ist, schlägt OpenClaw sichtbar fehl, statt auf ein anderes konfiguriertes Modell durchzufallen.
- Cron `--model` / Payload `model` ist ein primäres Modell pro Job. Es verwendet weiterhin konfigurierte Fallbacks, sofern der Job keine expliziten Payload-`fallbacks` bereitstellt (verwenden Sie `fallbacks: []` für einen strikten Cron-Lauf).
- CLI-Standardmodell- und Allowlist-Picker respektieren `models.mode: "replace"`, indem sie explizite `models.providers.*.models` auflisten, statt den vollständigen integrierten Katalog zu laden.
- Der Modell-Picker der Control UI fragt das Gateway nach seiner konfigurierten Modellansicht: `agents.defaults.models`, wenn vorhanden, andernfalls explizite `models.providers.*.models` plus Provider mit nutzbarer Authentifizierung. Der vollständige integrierte Katalog ist expliziten Browse-Ansichten wie `models.list` mit `view: "all"` oder `openclaw models list --all` vorbehalten.
- CLI-Standardmodell- und Allowlist-Auswähler respektieren `models.mode: "replace"`, indem sie explizite `models.providers.*.models` auflisten, anstatt den vollständigen integrierten Katalog zu laden.
- Der Modellauswähler in der Control UI fragt beim Gateway die konfigurierte Modellansicht ab: `agents.defaults.models`, sofern vorhanden, andernfalls explizite `models.providers.*.models` plus Provider mit nutzbarer Authentifizierung. Der vollständige integrierte Katalog ist expliziten Browse-Ansichten wie `models.list` mit `view: "all"` oder `openclaw models list --all` vorbehalten.
## Kurze Modellrichtlinie
## Schnelle Modellrichtlinie
- Legen Sie Ihr primäres Modell auf das stärkste Modell der neuesten Generation fest, das Ihnen zur Verfügung steht.
- Verwenden Sie Fallbacks für kosten-/latenzsensible Aufgaben und Chat mit geringerem Risiko.
- Vermeiden Sie bei toolfähigen Agents oder nicht vertrauenswürdigen Eingaben ältere/schwächere Modellstufen.
- Vermeiden Sie bei tool-fähigen Agents oder nicht vertrauenswürdigen Eingaben ältere/schwächere Modellstufen.
## Onboarding (empfohlen)
@ -86,7 +86,7 @@ Wenn Sie die Konfiguration nicht von Hand bearbeiten möchten, führen Sie das O
openclaw onboard
```
Es kann Modell + Authentifizierung für gängige Provider einrichten, einschließlich **OpenAI Code (Codex) subscription** (OAuth) und **Anthropic** (API-Schlüssel oder Claude CLI).
Es kann Modell + Auth für gängige Provider einrichten, einschließlich **OpenAI Code (Codex)-Abonnement** (OAuth) und **Anthropic** (API-Schlüssel oder Claude CLI).
## Konfigurationsschlüssel (Überblick)
@ -95,13 +95,13 @@ Es kann Modell + Authentifizierung für gängige Provider einrichten, einschlie
- `agents.defaults.pdfModel.primary` und `agents.defaults.pdfModel.fallbacks`
- `agents.defaults.imageGenerationModel.primary` und `agents.defaults.imageGenerationModel.fallbacks`
- `agents.defaults.videoGenerationModel.primary` und `agents.defaults.videoGenerationModel.fallbacks`
- `agents.defaults.models` (Allowlist + Aliasse + Provider-Parameter)
- `agents.defaults.models` (Allowlist + Aliase + Provider-Parameter)
- `models.providers` (benutzerdefinierte Provider, die in `models.json` geschrieben werden)
<Note>
Modell-Refs werden auf Kleinbuchstaben normalisiert. Provider-Aliasse wie `z.ai/*` werden zu `zai/*` normalisiert.
Modellreferenzen werden in Kleinbuchstaben normalisiert. Provider-Aliase wie `z.ai/*` werden zu `zai/*` normalisiert.
Provider-Konfigurationsbeispiele (einschließlich OpenCode) finden Sie unter [OpenCode](/de/providers/opencode).
Provider-Konfigurationsbeispiele (einschließlich OpenCode) finden Sie in [OpenCode](/de/providers/opencode).
</Note>
### Sichere Allowlist-Bearbeitungen
@ -114,37 +114,40 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
<AccordionGroup>
<Accordion title="Regeln zum Schutz vor Überschreiben">
`openclaw config set` schützt Modell-/Provider-Maps vor versehentlichem Überschreiben. Eine einfache Objektzuweisung an `agents.defaults.models`, `models.providers` oder `models.providers.<id>.models` wird abgelehnt, wenn dadurch vorhandene Einträge entfernt würden. Verwenden Sie `--merge` für additive Änderungen; verwenden Sie `--replace` nur, wenn der bereitgestellte Wert zum vollständigen Zielwert werden soll.
`openclaw config set` schützt Modell-/Provider-Maps vor versehentlichem Überschreiben. Eine einfache Objektzuweisung an `agents.defaults.models`, `models.providers` oder `models.providers.<id>.models` wird abgelehnt, wenn sie vorhandene Einträge entfernen würde. Verwenden Sie `--merge` für additive Änderungen; verwenden Sie `--replace` nur, wenn der bereitgestellte Wert zum vollständigen Zielwert werden soll.
Die interaktive Provider-Einrichtung und `openclaw configure --section model` führen ebenfalls Provider-bezogene Auswahlen in die vorhandene Allowlist zusammen, sodass das Hinzufügen von Codex, Ollama oder einem anderen Provider keine nicht zusammenhängenden Modelleinträge entfernt. Configure bewahrt ein vorhandenes `agents.defaults.model.primary`, wenn die Provider-Authentifizierung erneut angewendet wird. Explizite Befehle zum Festlegen des Standards wie `openclaw models auth login --provider <id> --set-default` und `openclaw models set <model>` ersetzen weiterhin `agents.defaults.model.primary`.
Die interaktive Provider-Einrichtung und `openclaw configure --section model` führen Provider-bezogene Auswahlen ebenfalls mit der vorhandenen Allowlist zusammen, sodass das Hinzufügen von Codex, Ollama oder einem anderen Provider keine nicht verwandten Modelleinträge entfernt. Configure bewahrt ein vorhandenes `agents.defaults.model.primary`, wenn Provider-Auth erneut angewendet wird. Explizite Befehle zum Setzen von Standards wie `openclaw models auth login --provider <id> --set-default` und `openclaw models set <model>` ersetzen weiterhin `agents.defaults.model.primary`.
</Accordion>
</AccordionGroup>
## „Modell ist nicht erlaubt“ (und warum Antworten stoppen)
## "Modell ist nicht erlaubt" (und warum Antworten stoppen)
Wenn `agents.defaults.models` festgelegt ist, wird es zur **Allowlist** für `/model` und für Sitzungsüberschreibungen. Wenn ein Benutzer ein Modell auswählt, das nicht in dieser Allowlist enthalten ist, gibt OpenClaw Folgendes zurück:
Wenn `agents.defaults.models` festgelegt ist, wird es zur **Allowlist** für `/model` und für Sitzungsüberschreibungen. Wenn ein Benutzer ein Modell auswählt, das nicht in dieser Allowlist steht, gibt OpenClaw Folgendes zurück:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
<Warning>
Dies geschieht **bevor** eine normale Antwort generiert wird, daher kann sich die Nachricht so anfühlen, als hätte sie „nicht geantwortet“. Die Lösung besteht darin, entweder:
Dies geschieht **bevor** eine normale Antwort generiert wird, sodass die Nachricht wirken kann, als hätte sie "nicht geantwortet". Die Lösung ist, entweder:
- Das Modell zu `agents.defaults.models` hinzuzufügen, oder
- Die Allowlist zu leeren (`agents.defaults.models` entfernen), oder
- Ein Modell aus `/model list` auszuwählen.
- die Allowlist zu leeren (`agents.defaults.models` entfernen), oder
- ein Modell aus `/model list` auszuwählen.
</Warning>
Speichern Sie für lokale/GGUF-Modelle die vollständige Provider-präfixierte Ref in der Allowlist,
Wenn der abgelehnte Befehl eine Laufzeitüberschreibung wie `/model openai/gpt-5.5 --runtime codex` enthielt, korrigieren Sie zuerst die Allowlist und versuchen Sie dann denselben Befehl `/model ... --runtime ...` erneut. Für native Codex-Ausführung bleibt das ausgewählte Modell `openai/gpt-5.5`; die `codex`-Laufzeit wählt das Harness aus und verwendet Codex-Auth separat.
Speichern Sie für lokale/GGUF-Modelle die vollständige Provider-präfixierte Referenz in der Allowlist,
zum Beispiel `ollama/gemma4:26b`, `lmstudio/Gemma4-26b-a4-it-gguf` oder die
exakte Provider-/Modellangabe, die von `openclaw models list --provider <provider>` angezeigt wird.
Bloße lokale Dateinamen oder Anzeigenamen reichen nicht aus, wenn die Allowlist
aktiv ist.
Beispiel für eine Allowlist-Konfiguration:
Beispiel-Allowlist-Konfiguration:
```json5
{
@ -160,7 +163,7 @@ Beispiel für eine Allowlist-Konfiguration:
## Modelle im Chat wechseln (`/model`)
Sie können Modelle für die aktuelle Sitzung wechseln, ohne neu zu starten:
Sie können Modelle für die aktuelle Sitzung ohne Neustart wechseln:
```
/model
@ -173,28 +176,28 @@ Sie können Modelle für die aktuelle Sitzung wechseln, ohne neu zu starten:
<AccordionGroup>
<Accordion title="Picker-Verhalten">
- `/model` (und `/model list`) ist ein kompakter, nummerierter Picker (Modellfamilie + verfügbare Provider).
- Auf Discord öffnen `/model` und `/models` einen interaktiven Picker mit Provider- und Modell-Dropdowns sowie einem Absenden-Schritt.
- Auf Telegram sind `/models`-Picker-Auswahlen sitzungsbezogen; sie ändern nicht den persistenten Standard des Agents in `openclaw.json`.
- `/models add` ist veraltet und gibt jetzt eine Deprecation-Nachricht zurück, statt Modelle aus dem Chat zu registrieren.
- Auf Discord öffnen `/model` und `/models` einen interaktiven Picker mit Provider- und Modell-Dropdowns plus einem Absenden-Schritt.
- Auf Telegram sind Picker-Auswahlen über `/models` sitzungsbezogen; sie ändern den persistenten Standard des Agents in `openclaw.json` nicht.
- `/models add` ist veraltet und gibt nun eine Veraltungsmeldung zurück, statt Modelle aus dem Chat zu registrieren.
- `/model <#>` wählt aus diesem Picker aus.
</Accordion>
<Accordion title="Persistenz und Live-Wechsel">
- `/model` speichert die neue Sitzungsauswahl sofort.
- Wenn der Agent inaktiv ist, verwendet der nächste Lauf sofort das neue Modell.
- Wenn bereits ein Lauf aktiv ist, markiert OpenClaw einen Live-Wechsel als ausstehend und startet erst an einem sauberen Retry-Punkt in das neue Modell neu.
- Wenn Tool-Aktivität oder Antwortausgabe bereits begonnen hat, kann der ausstehende Wechsel bis zu einer späteren Retry-Gelegenheit oder bis zum nächsten Benutzer-Turn in der Warteschlange bleiben.
- Eine vom Benutzer ausgewählte `/model`-Ref ist für diese Sitzung strikt: Wenn der ausgewählte Provider/das ausgewählte Modell nicht erreichbar ist, schlägt die Antwort sichtbar fehl, statt stillschweigend aus `agents.defaults.model.fallbacks` zu antworten. Dies unterscheidet sich von konfigurierten Standards und primären Modellen für Cron-Jobs, die weiterhin Fallback-Ketten verwenden können.
- Wenn der Agent im Leerlauf ist, verwendet der nächste Lauf sofort das neue Modell.
- Wenn bereits ein Lauf aktiv ist, markiert OpenClaw einen Live-Wechsel als ausstehend und startet erst an einem sauberen Wiederholungspunkt mit dem neuen Modell neu.
- Wenn Tool-Aktivität oder Antwortausgabe bereits begonnen hat, kann der ausstehende Wechsel bis zu einer späteren Wiederholungsmöglichkeit oder bis zum nächsten Benutzer-Turn in der Warteschlange bleiben.
- Eine vom Benutzer ausgewählte `/model`-Referenz ist für diese Sitzung strikt: Wenn der ausgewählte Provider/das ausgewählte Modell nicht erreichbar ist, schlägt die Antwort sichtbar fehl, statt stillschweigend aus `agents.defaults.model.fallbacks` zu antworten. Dies unterscheidet sich von konfigurierten Standards und primären Cron-Job-Modellen, die weiterhin Fallback-Ketten verwenden können.
- `/model status` ist die Detailansicht (Auth-Kandidaten und, wenn konfiguriert, Provider-Endpunkt `baseUrl` + `api`-Modus).
</Accordion>
<Accordion title="Ref-Parsing">
- Modell-Refs werden durch Aufteilen am **ersten** `/` geparst. Verwenden Sie `provider/model`, wenn Sie `/model <ref>` eingeben.
<Accordion title="Referenz-Parsing">
- Modellreferenzen werden durch Aufteilen am **ersten** `/` geparst. Verwenden Sie `provider/model`, wenn Sie `/model <ref>` eingeben.
- Wenn die Modell-ID selbst `/` enthält (OpenRouter-Stil), müssen Sie das Provider-Präfix angeben (Beispiel: `/model openrouter/moonshotai/kimi-k2`).
- Wenn Sie den Provider weglassen, löst OpenClaw die Eingabe in dieser Reihenfolge auf:
1. Alias-Übereinstimmung
2. eindeutige Übereinstimmung eines konfigurierten Providers für genau diese unpräfixierte Modell-ID
3. veralteter Fallback auf den konfigurierten Standard-Provider — wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw stattdessen auf das erste konfigurierte Provider-/Modellpaar zurück, um keinen veralteten entfernten Provider-Standard offenzulegen.
2. eindeutige Übereinstimmung eines konfigurierten Providers für genau diese nicht präfixierte Modell-ID
3. veralteter Fallback auf den konfigurierten Standard-Provider — wenn dieser Provider das konfigurierte Standardmodell nicht mehr anbietet, fällt OpenClaw stattdessen auf den ersten konfigurierten Provider/das erste konfigurierte Modell zurück, um zu vermeiden, dass ein veralteter Standard eines entfernten Providers angezeigt wird.
</Accordion>
</AccordionGroup>
@ -227,10 +230,10 @@ openclaw models image-fallbacks clear
### `models list`
Zeigt standardmäßig konfigurierte/auth-verfügbare Modelle an. Nützliche Flags:
Zeigt standardmäßig konfigurierte bzw. mit verfügbarer Authentifizierung nutzbare Modelle an. Nützliche Flags:
<ParamField path="--all" type="boolean">
Vollständiger Katalog. Enthält gebündelte, Provider-eigene statische Katalogzeilen, bevor die Authentifizierung konfiguriert ist, damit reine Erkennungsansichten Modelle anzeigen können, die nicht verfügbar sind, bis Sie passende Provider-Zugangsdaten hinzufügen.
Vollständiger Katalog. Enthält gebündelte, Provider-eigene statische Katalogzeilen, bevor die Authentifizierung konfiguriert ist, damit reine Erkennungsansichten Modelle anzeigen können, die erst verfügbar sind, wenn Sie passende Provider-Anmeldedaten hinzufügen.
</ParamField>
<ParamField path="--local" type="boolean">
Nur lokale Provider.
@ -247,21 +250,21 @@ Zeigt standardmäßig konfigurierte/auth-verfügbare Modelle an. Nützliche Flag
### `models status`
Zeigt das aufgelöste primäre Modell, Fallbacks, das Bildmodell und eine Authentifizierungsübersicht der konfigurierten Provider an. Außerdem wird der OAuth-Ablaufstatus für Profile angezeigt, die im Authentifizierungsspeicher gefunden wurden (standardmäßig Warnung innerhalb von 24 Stunden). `--plain` gibt nur das aufgelöste primäre Modell aus.
Zeigt das aufgelöste primäre Modell, Fallbacks, Bildmodell und eine Authentifizierungsübersicht der konfigurierten Provider an. Außerdem wird der Ablaufstatus von OAuth für Profile angezeigt, die im Auth-Store gefunden wurden (warnt standardmäßig innerhalb von 24 Stunden). `--plain` gibt nur das aufgelöste primäre Modell aus.
<AccordionGroup>
<Accordion title="Authentifizierungs- und Prüfverhalten">
- Der OAuth-Status wird immer angezeigt (und in der `--json`-Ausgabe enthalten). Wenn ein konfigurierter Provider keine Zugangsdaten hat, gibt `models status` einen Abschnitt **Fehlende Authentifizierung** aus.
- JSON enthält `auth.oauth` (Warnfenster + Profile) und `auth.providers` (effektive Authentifizierung pro Provider, einschließlich umgebungsbasierter Zugangsdaten). `auth.oauth` beschreibt nur den Zustand der Profile im Authentifizierungsspeicher; reine Umgebungs-Provider erscheinen dort nicht.
- Der OAuth-Status wird immer angezeigt (und in die `--json`-Ausgabe aufgenommen). Wenn ein konfigurierter Provider keine Anmeldedaten hat, gibt `models status` einen Abschnitt **Fehlende Authentifizierung** aus.
- JSON enthält `auth.oauth` (Warnfenster + Profile) und `auth.providers` (effektive Authentifizierung pro Provider, einschließlich env-gestützter Anmeldedaten). `auth.oauth` ist nur die Integrität von Auth-Store-Profilen; reine env-Provider erscheinen dort nicht.
- Verwenden Sie `--check` für Automatisierung (Exit `1` bei fehlender/abgelaufener Authentifizierung, `2` bei bald ablaufender Authentifizierung).
- Verwenden Sie `--probe` für Live-Authentifizierungsprüfungen; Prüfzeilen können aus Authentifizierungsprofilen, Umgebungszugangsdaten oder `models.json` stammen.
- Verwenden Sie `--probe` für Live-Authentifizierungsprüfungen; Prüfzeilen können aus Auth-Profilen, env-Anmeldedaten oder `models.json` stammen.
- Wenn explizites `auth.order.<provider>` ein gespeichertes Profil auslässt, meldet die Prüfung `excluded_by_auth_order`, statt es zu versuchen. Wenn Authentifizierung vorhanden ist, aber für diesen Provider kein prüfbares Modell aufgelöst werden kann, meldet die Prüfung `status: no_model`.
</Accordion>
</AccordionGroup>
<Note>
Die Authentifizierungswahl hängt vom Provider/Konto ab. Für dauerhaft aktive Gateway-Hosts sind API-Schlüssel in der Regel am verlässlichsten; die Wiederverwendung der Claude CLI sowie vorhandene Anthropic-OAuth-/Token-Profile werden ebenfalls unterstützt.
Die Wahl der Authentifizierung hängt vom Provider/Konto ab. Für ständig aktive Gateway-Hosts sind API-Schlüssel normalerweise am berechenbarsten; die Wiederverwendung der Claude CLI und vorhandene Anthropic OAuth-/Token-Profile werden ebenfalls unterstützt.
</Note>
Beispiel (Claude CLI):
@ -279,13 +282,13 @@ openclaw models status
Live-Prüfungen überspringen (nur Metadaten).
</ParamField>
<ParamField path="--min-params <b>" type="number">
Mindestparametergröße (Milliarden).
Mindestgröße der Parameter (Milliarden).
</ParamField>
<ParamField path="--max-age-days <days>" type="number">
Ältere Modelle überspringen.
</ParamField>
<ParamField path="--provider <name>" type="string">
Provider-Präfixfilter.
Filter für Provider-Präfix.
</ParamField>
<ParamField path="--max-candidates <n>" type="number">
Größe der Fallback-Liste.
@ -298,7 +301,7 @@ openclaw models status
</ParamField>
<Note>
Der OpenRouter-Katalog `/models` ist öffentlich, daher können reine Metadaten-Scans kostenlose Kandidaten ohne Schlüssel auflisten. Prüfungen und Inferenz erfordern weiterhin einen OpenRouter-API-Schlüssel (aus Authentifizierungsprofilen oder `OPENROUTER_API_KEY`). Wenn kein Schlüssel verfügbar ist, fällt `openclaw models scan` auf reine Metadatenausgabe zurück und lässt die Konfiguration unverändert. Verwenden Sie `--no-probe`, um den reinen Metadatenmodus explizit anzufordern.
Der OpenRouter-`/models`-Katalog ist öffentlich, daher können reine Metadatenscans kostenlose Kandidaten ohne Schlüssel auflisten. Prüfungen und Inferenz erfordern weiterhin einen OpenRouter-API-Schlüssel (aus Auth-Profilen oder `OPENROUTER_API_KEY`). Wenn kein Schlüssel verfügbar ist, fällt `openclaw models scan` auf reine Metadatenausgabe zurück und lässt die Konfiguration unverändert. Verwenden Sie `--no-probe`, um den reinen Metadatenmodus explizit anzufordern.
</Note>
Scan-Ergebnisse werden nach folgenden Kriterien sortiert:
@ -310,36 +313,36 @@ Scan-Ergebnisse werden nach folgenden Kriterien sortiert:
Eingabe:
- OpenRouter-Liste `/models` (Filter `:free`)
- Live-Prüfungen erfordern einen OpenRouter-API-Schlüssel aus Authentifizierungsprofilen oder `OPENROUTER_API_KEY` (siehe [Umgebungsvariablen](/de/help/environment))
- OpenRouter-`/models`-Liste (Filter `:free`)
- Live-Prüfungen erfordern einen OpenRouter-API-Schlüssel aus Auth-Profilen oder `OPENROUTER_API_KEY` (siehe [Umgebungsvariablen](/de/help/environment))
- Optionale Filter: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
- Anfrage-/Prüfsteuerung: `--timeout`, `--concurrency`
Wenn Live-Prüfungen in einem TTY ausgeführt werden, können Sie Fallbacks interaktiv auswählen. Im nicht interaktiven Modus übergeben Sie `--yes`, um Standardwerte zu akzeptieren. Reine Metadatenergebnisse dienen nur zur Information; `--set-default` und `--set-image` erfordern Live-Prüfungen, damit OpenClaw kein unbrauchbares OpenRouter-Modell ohne Schlüssel konfiguriert.
Wenn Live-Prüfungen in einem TTY ausgeführt werden, können Sie Fallbacks interaktiv auswählen. Im nicht interaktiven Modus übergeben Sie `--yes`, um Standardwerte zu akzeptieren. Reine Metadatenergebnisse dienen nur zur Information; `--set-default` und `--set-image` erfordern Live-Prüfungen, damit OpenClaw kein unbrauchbares schlüsselloses OpenRouter-Modell konfiguriert.
## Modellregistrierung (`models.json`)
Benutzerdefinierte Provider in `models.providers` werden unter dem Agent-Verzeichnis in `models.json` geschrieben (Standard: `~/.openclaw/agents/<agentId>/agent/models.json`). Diese Datei wird standardmäßig zusammengeführt, sofern `models.mode` nicht auf `replace` gesetzt ist.
Benutzerdefinierte Provider in `models.providers` werden in `models.json` im Agent-Verzeichnis geschrieben (Standard `~/.openclaw/agents/<agentId>/agent/models.json`). Diese Datei wird standardmäßig zusammengeführt, sofern `models.mode` nicht auf `replace` gesetzt ist.
<AccordionGroup>
<Accordion title="Rangfolge im Zusammenführungsmodus">
Rangfolge im Zusammenführungsmodus für übereinstimmende Provider-IDs:
<Accordion title="Rangfolge des Zusammenführungsmodus">
Rangfolge des Zusammenführungsmodus für übereinstimmende Provider-IDs:
- Eine nicht leere `baseUrl`, die bereits in der `models.json` des Agents vorhanden ist, gewinnt.
- Ein nicht leerer `apiKey` in der `models.json` des Agents gewinnt nur, wenn dieser Provider im aktuellen Konfigurations-/Authentifizierungsprofilkontext nicht SecretRef-verwaltet ist.
- SecretRef-verwaltete Provider-`apiKey`-Werte werden aus Quellmarkierungen (`ENV_VAR_NAME` für Umgebungsreferenzen, `secretref-managed` für Datei-/Ausführungsreferenzen) aktualisiert, statt aufgelöste Secrets dauerhaft zu speichern.
- SecretRef-verwaltete Provider-Headerwerte werden aus Quellmarkierungen aktualisiert (`secretref-env:ENV_VAR_NAME` für Umgebungsreferenzen, `secretref-managed` für Datei-/Ausführungsreferenzen).
- Leere oder fehlende Agent-`apiKey`/`baseUrl` fallen auf `models.providers` aus der Konfiguration zurück.
- Eine nicht leere `baseUrl`, die bereits in der Agent-`models.json` vorhanden ist, gewinnt.
- Ein nicht leerer `apiKey` in der Agent-`models.json` gewinnt nur, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profilkontext nicht SecretRef-verwaltet ist.
- SecretRef-verwaltete Provider-`apiKey`-Werte werden aus Quellmarkern (`ENV_VAR_NAME` für env-Refs, `secretref-managed` für Datei-/Exec-Refs) aktualisiert, statt aufgelöste Geheimnisse dauerhaft zu speichern.
- SecretRef-verwaltete Provider-Header-Werte werden aus Quellmarkern (`secretref-env:ENV_VAR_NAME` für env-Refs, `secretref-managed` für Datei-/Exec-Refs) aktualisiert.
- Leere oder fehlende Agent-`apiKey`/`baseUrl` fallen auf die Konfiguration `models.providers` zurück.
- Andere Provider-Felder werden aus der Konfiguration und normalisierten Katalogdaten aktualisiert.
</Accordion>
</AccordionGroup>
<Note>
Die Persistenz von Markierungen ist quellautoritativ: OpenClaw schreibt Markierungen aus dem aktiven Quell-Konfigurationssnapshot (vor der Auflösung), nicht aus aufgelösten Laufzeit-Secret-Werten. Dies gilt immer, wenn OpenClaw `models.json` neu generiert, einschließlich befehlsgesteuerter Pfade wie `openclaw agent`.
Marker-Persistenz ist quellautoritativ: OpenClaw schreibt Marker aus dem aktiven Quellkonfigurations-Snapshot (vor der Auflösung), nicht aus aufgelösten Laufzeit-Geheimniswerten. Dies gilt immer, wenn OpenClaw `models.json` neu erzeugt, einschließlich befehlsgesteuerter Pfade wie `openclaw agent`.
</Note>
## Verwandt
## Verwandte Themen
- [Agent-Laufzeiten](/de/concepts/agent-runtimes) — PI, Codex und andere Agent-Loop-Laufzeiten
- [Konfigurationsreferenz](/de/gateway/config-agents#agent-defaults) — Modellkonfigurationsschlüssel

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

@ -1,70 +1,70 @@
---
read_when:
- Verstehen, wie der QA-Stack zusammenhängt
- qa-lab, qa-channel oder einen Transportadapter erweitern
- Verstehen, wie der QA-Stack zusammenpasst
- Erweitern von qa-lab, qa-channel oder einem Transportadapter
- Repo-gestützte QA-Szenarien hinzufügen
- Aufbau realistischerer QA-Automatisierung rund um das Gateway-Dashboard
summary: 'Überblick über den QA-Stack: qa-lab, qa-channel, repositorygestützte Szenarien, Live-Transport-Lanes, Transportadapter und Berichterstellung.'
- Aufbau realitätsnäherer QA-Automatisierung rund um das Gateway-Dashboard
summary: 'QA-Stack-Übersicht: qa-lab, qa-channel, Repository-gestützte Szenarien, Live-Transport-Lanes, Transportadapter und Berichterstattung.'
title: QA-Übersicht
x-i18n:
generated_at: "2026-05-04T06:42:07Z"
generated_at: "2026-05-05T01:45:10Z"
model: gpt-5.5
provider: openai
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
Der private QA-Stack soll OpenClaw auf realistischere,
channel-ähnliche Weise testen, als es ein einzelner Unit-Test kann.
kanalnahe Weise ausüben, als es ein einzelner Unit-Test kann.
Aktuelle Komponenten:
Aktuelle Bestandteile:
- `extensions/qa-channel`: synthetischer Nachrichtenkanal mit DM-, Kanal-, Thread-,
Reaktions-, Bearbeitungs- und Löschflächen.
- `extensions/qa-channel`: synthetischer Nachrichtenkanal mit Oberflächen für DM, Kanal, Thread,
Reaktion, Bearbeiten und Löschen.
- `extensions/qa-lab`: Debugger-UI und QA-Bus zum Beobachten des Transkripts,
Einspeisen eingehender Nachrichten und Exportieren eines Markdown-Berichts.
- `extensions/qa-matrix`, künftige Runner-Plugins: Live-Transport-Adapter, die
einen echten Kanal innerhalb eines untergeordneten QA-Gateway steuern.
- `qa/`: repository-gestützte Seed-Assets für die Kickoff-Aufgabe und Baseline-QA-
- `qa/`: repo-gestützte Seed-Assets für die Kickoff-Aufgabe und Baseline-QA-
Szenarien.
- [Mantis](/de/concepts/mantis): Vorher- und Nachher-Live-Verifizierung für Bugs, die
echte Transporte, Browser-Screenshots, VM-Status und PR-Nachweise benötigen.
echte Transporte, Browser-Screenshots, VM-Zustand und PR-Nachweise benötigen.
## Befehlsoberfläche
Jeder QA-Flow läuft unter `pnpm openclaw qa <subcommand>`. Viele haben `pnpm qa:*`-
Skript-Aliase; beide Formen werden unterstützt.
Skript-Aliasse; beide Formen werden unterstützt.
| Befehl | Zweck |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Gebündelter QA-Selbsttest; schreibt einen Markdown-Bericht. |
| `qa suite` | Führt repository-gestützte Szenarien gegen die QA-Gateway-Lane aus. Aliase: `pnpm openclaw qa suite --runner multipass` für eine kurzlebige Linux-VM. |
| `qa coverage` | Gibt das Markdown-Inventar der Szenarioabdeckung aus (`--json` für maschinenlesbare Ausgabe). |
| `qa parity-report` | Vergleicht zwei `qa-suite-summary.json`-Dateien und schreibt den agentischen Paritätsbericht. |
| `qa character-eval` | Führt das Charakter-QA-Szenario über mehrere Live-Modelle hinweg mit bewertetem Bericht aus. Siehe [Berichterstattung](#reporting). |
| `qa manual` | Führt einen einmaligen Prompt gegen die ausgewählte Provider-/Modell-Lane aus. |
| `qa ui` | Startet die QA-Debugger-UI und den lokalen QA-Bus (Alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Baut das vorgefertigte QA-Docker-Image. |
| `qa docker-scaffold` | Schreibt ein docker-compose-Gerüst für das QA-Dashboard und die Gateway-Lane. |
| `qa up` | Baut die QA-Site, startet den Docker-gestützten Stack und gibt die URL aus (Alias: `pnpm qa:lab:up`; die Variante `:fast` ergänzt `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Startet nur den AIMock-Provider-Server. |
| `qa mock-openai` | Startet nur den szenariobewussten `mock-openai`-Provider-Server. |
| `qa credentials doctor` / `add` / `list` / `remove` | Verwaltet den gemeinsam genutzten Convex-Anmeldedatenpool. |
| `qa matrix` | Live-Transport-Lane gegen einen kurzlebigen Tuwunel-Homeserver. Siehe [Matrix-QA](/de/concepts/qa-matrix). |
| `qa telegram` | Live-Transport-Lane gegen eine echte private Telegram-Gruppe. |
| `qa discord` | Live-Transport-Lane gegen einen echten privaten Discord-Guild-Kanal. |
| `qa slack` | Live-Transport-Lane gegen einen echten privaten Slack-Kanal. |
| `qa mantis` | Vorher- und Nachher-Verifizierungs-Runner für Live-Transport-Bugs, mit Discord-Statusreaktionsnachweisen, Crabbox-Desktop-/Browser-Smoke und Slack-in-VNC-Smoke. Siehe [Mantis](/de/concepts/mantis). |
| Befehl | Zweck |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Gebündelter QA-Selbstcheck; schreibt einen Markdown-Bericht. |
| `qa suite` | Führt repo-gestützte Szenarien gegen die QA-Gateway-Lane aus. Aliasse: `pnpm openclaw qa suite --runner multipass` für eine kurzlebige Linux-VM. |
| `qa coverage` | Gibt das Markdown-Inventar der Szenarioabdeckung aus (`--json` für maschinenlesbare Ausgabe). |
| `qa parity-report` | Vergleicht zwei `qa-suite-summary.json`-Dateien und schreibt den agentischen Paritätsbericht. |
| `qa character-eval` | Führt das Character-QA-Szenario über mehrere Live-Modelle hinweg mit einem beurteilten Bericht aus. Siehe [Berichterstattung](#reporting). |
| `qa manual` | Führt einen einmaligen Prompt gegen die ausgewählte Provider-/Modell-Lane aus. |
| `qa ui` | Startet die QA-Debugger-UI und den lokalen QA-Bus (Alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Baut das vorgebackene QA-Docker-Image. |
| `qa docker-scaffold` | Schreibt ein docker-compose-Gerüst für das QA-Dashboard und die Gateway-Lane. |
| `qa up` | Baut die QA-Site, startet den Docker-gestützten Stack und gibt die URL aus (Alias: `pnpm qa:lab:up`; die Variante `:fast` fügt `--use-prebuilt-image --bind-ui-dist --skip-ui-build` hinzu). |
| `qa aimock` | Startet nur den AIMock-Provider-Server. |
| `qa mock-openai` | Startet nur den szenariobewussten `mock-openai`-Provider-Server. |
| `qa credentials doctor` / `add` / `list` / `remove` | Verwaltet den gemeinsam genutzten Convex-Anmeldeinformationspool. |
| `qa matrix` | Live-Transport-Lane gegen einen kurzlebigen Tuwunel-Homeserver. Siehe [Matrix QA](/de/concepts/qa-matrix). |
| `qa telegram` | Live-Transport-Lane gegen eine echte private Telegram-Gruppe. |
| `qa discord` | Live-Transport-Lane gegen einen echten privaten Discord-Guild-Kanal. |
| `qa slack` | Live-Transport-Lane gegen einen echten privaten Slack-Kanal. |
| `qa mantis` | Vorher- und Nachher-Verifizierungsrunner für Live-Transport-Bugs, mit Discord-Statusreaktionsnachweisen, Crabbox-Desktop-/Browser-Smoke und Slack-in-VNC-Smoke. Siehe [Mantis](/de/concepts/mantis). |
## Operator-Flow
## Operator-Ablauf
Der aktuelle QA-Operator-Flow ist eine zweigeteilte QA-Site:
Der aktuelle QA-Operator-Ablauf ist eine zweigeteilte QA-Site:
- Links: Gateway-Dashboard (Control UI) mit dem Agenten.
- Rechts: QA Lab, mit dem Slack-artigen Transkript und dem Szenarioplan.
- Rechts: QA Lab, das das Slack-ähnliche Transkript und den Szenarioplan zeigt.
Führen Sie ihn aus mit:
Führen Sie es aus mit:
```bash
pnpm qa:lab:up
@ -72,11 +72,11 @@ pnpm qa:lab:up
Das baut die QA-Site, startet die Docker-gestützte Gateway-Lane und stellt die
QA-Lab-Seite bereit, auf der ein Operator oder eine Automatisierungsschleife dem
Agenten eine QA-Mission geben, echtes Kanalverhalten beobachten und aufzeichnen
kann, was funktioniert hat, fehlgeschlagen ist oder blockiert blieb.
Agenten eine QA-Mission geben, echtes Kanalverhalten beobachten und aufzeichnen kann,
was funktioniert hat, fehlgeschlagen ist oder blockiert blieb.
Für schnellere QA-Lab-UI-Iteration ohne jedes Mal das Docker-Image neu zu bauen,
starten Sie den Stack mit einem per Bind-Mount eingebundenen QA-Lab-Bundle:
starten Sie den Stack mit einem bind-gemounteten QA-Lab-Bundle:
```bash
pnpm openclaw qa docker-build-image
@ -85,40 +85,40 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` hält die Docker-Dienste auf einem vorgefertigten Image und bind-mountet
`qa:lab:up:fast` hält die Docker-Dienste auf einem vorgebauten Image und bind-mountet
`extensions/qa-lab/web/dist` in den `qa-lab`-Container. `qa:lab:watch`
baut dieses Bundle bei Änderungen neu, und der Browser lädt automatisch neu, wenn sich der
Asset-Hash von QA Lab ändert.
baut dieses Bundle bei Änderungen neu, und der Browser lädt automatisch neu, wenn sich
der QA-Lab-Asset-Hash ändert.
Für einen lokalen OpenTelemetry-Trace-Smoke führen Sie Folgendes aus:
Für einen lokalen OpenTelemetry-Trace-Smoke führen Sie aus:
```bash
pnpm qa:otel:smoke
```
Dieses Skript startet einen lokalen OTLP/HTTP-Trace-Empfänger, führt das
QA-Szenario `otel-trace-smoke` mit aktiviertem Plugin `diagnostics-otel` aus,
dekodiert anschließend die exportierten Protobuf-Spans und prüft die release-kritische Form:
`otel-trace-smoke`-QA-Szenario mit aktiviertem `diagnostics-otel`-Plugin aus,
dekodiert anschließend die exportierten protobuf-Spans und prüft die release-kritische Form:
`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
`openclaw.context.assembled` und `openclaw.message.delivery` müssen vorhanden sein;
Modellaufrufe dürfen bei erfolgreichen Turns kein `StreamAbandoned` exportieren; rohe Diagnose-IDs und
`openclaw.content.*`-Attribute müssen aus dem Trace herausbleiben. Es schreibt
`otel-smoke-summary.json` neben die QA-Suite-Artefakte.
Observability-QA bleibt nur für Source-Checkouts verfügbar. Der npm-Tarball lässt
QA Lab absichtlich aus, daher führen Docker-Package-Release-Lanes keine `qa`-Befehle aus. Verwenden Sie
`pnpm qa:otel:smoke` aus einem gebauten Source-Checkout heraus, wenn Sie die Diagnose-
Instrumentierung ändern.
Observability-QA bleibt nur für Source-Checkouts. Der npm-Tarball lässt
QA Lab absichtlich aus, daher führen Package-Docker-Release-Lanes keine `qa`-Befehle aus. Verwenden Sie
`pnpm qa:otel:smoke` aus einem gebauten Source-Checkout, wenn Sie Diagnose-
Instrumentation ändern.
Für eine transport-echte Matrix-Smoke-Lane führen Sie Folgendes aus:
Für eine transportechte Matrix-Smoke-Lane führen Sie aus:
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
Die vollständige CLI-Referenz, der Profil-/Szenariokatalog, die Env-Vars und das Artefaktlayout für diese Lane befinden sich in [Matrix-QA](/de/concepts/qa-matrix). Kurzüberblick: Sie stellt einen kurzlebigen Tuwunel-Homeserver in Docker bereit, registriert temporäre Driver-/SUT-/Observer-Benutzer, führt das echte Matrix-Plugin innerhalb eines untergeordneten QA-Gateway aus, das auf diesen Transport beschränkt ist (kein `qa-channel`), und schreibt anschließend einen Markdown-Bericht, eine JSON-Zusammenfassung, ein Artefakt mit beobachteten Ereignissen und ein kombiniertes Ausgabelog unter `.artifacts/qa-e2e/matrix-<timestamp>/`.
Die vollständige CLI-Referenz, der Profil-/Szenariokatalog, Env-Vars und das Artefaktlayout für diese Lane stehen in [Matrix QA](/de/concepts/qa-matrix). Kurz gesagt: Sie stellt einen kurzlebigen Tuwunel-Homeserver in Docker bereit, registriert temporäre Driver-/SUT-/Observer-Benutzer, führt das echte Matrix-Plugin innerhalb eines untergeordneten QA-Gateway aus, das auf diesen Transport beschränkt ist (kein `qa-channel`), und schreibt dann einen Markdown-Bericht, eine JSON-Zusammenfassung, ein Observed-Events-Artefakt und ein kombiniertes Ausgabelog unter `.artifacts/qa-e2e/matrix-<timestamp>/`.
Für transport-echte Telegram-, Discord- und Slack-Smoke-Lanes:
Für transportechte Telegram-, Discord- und Slack-Smoke-Lanes:
```bash
pnpm openclaw qa telegram
@ -126,9 +126,9 @@ pnpm openclaw qa discord
pnpm openclaw qa slack
```
Sie zielen auf einen bereits vorhandenen echten Kanal mit zwei Bots (Driver + SUT). Erforderliche Env-Vars, Szenariolisten, Ausgabeartefakte und der Convex-Anmeldedatenpool sind unten in der [QA-Referenz für Telegram, Discord und Slack](#telegram-discord-and-slack-qa-reference) dokumentiert.
Sie zielen auf einen bereits vorhandenen echten Kanal mit zwei Bots (Driver + SUT). Erforderliche Env-Vars, Szenariolisten, Ausgabeartefakte und der Convex-Anmeldeinformationspool sind unten in der [Telegram-, Discord- und Slack-QA-Referenz](#telegram-discord-and-slack-qa-reference) dokumentiert.
Für einen vollständigen Slack-Desktop-VM-Lauf mit VNC-Rettung führen Sie Folgendes aus:
Für einen vollständigen Slack-Desktop-VM-Lauf mit VNC-Rettung führen Sie aus:
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
@ -140,76 +140,76 @@ pnpm openclaw qa mantis slack-desktop-smoke \
Dieser Befehl least eine Crabbox-Desktop-/Browser-Maschine, führt die Slack-Live-Lane
innerhalb der VM aus, öffnet Slack Web im VNC-Browser, erfasst den Desktop und
kopiert `slack-qa/` sowie `slack-desktop-smoke.png` zurück in das Mantis-Artefakt-
verzeichnis. Verwenden Sie `--lease-id <cbx_...>` erneut, nachdem Sie sich manuell
über VNC bei Slack Web angemeldet haben. Mit `--gateway-setup` lässt Mantis ein
persistentes OpenClaw-Slack-Gateway innerhalb der VM auf Port `38973` laufen; ohne diese Option führt der Befehl die
Verzeichnis. Verwenden Sie `--lease-id <cbx_...>` erneut, nachdem Sie sich manuell
über VNC bei Slack Web angemeldet haben. Mit `--gateway-setup` lässt Mantis ein dauerhaftes OpenClaw-Slack-
Gateway innerhalb der VM auf Port `38973` laufen; ohne diese Option führt der Befehl die
normale Bot-zu-Bot-Slack-QA-Lane aus und beendet sich nach der Artefakterfassung.
Bevor Sie gepoolte Live-Anmeldedaten verwenden, führen Sie Folgendes aus:
Bevor Sie gepoolte Live-Anmeldeinformationen verwenden, führen Sie aus:
```bash
pnpm openclaw qa credentials doctor
```
Der Doctor prüft die Convex-Broker-Umgebung, validiert Endpoint-Einstellungen und verifiziert die Erreichbarkeit von Admin/List, wenn das Maintainer-Secret vorhanden ist. Für Secrets meldet er nur den Status gesetzt/fehlend.
Der Doctor prüft die Convex-Broker-Env, validiert Endpoint-Einstellungen und verifiziert die Admin-/Listen-Erreichbarkeit, wenn das Maintainer-Secret vorhanden ist. Er meldet für Secrets nur den Status gesetzt/fehlend.
## Live-Transport-Abdeckung
Live-Transport-Lanes teilen sich einen Vertrag, statt dass jede ihre eigene Form für Szenariolisten erfindet. `qa-channel` ist die breite synthetische Suite für Produktverhalten und gehört nicht zur Live-Transport-Abdeckungsmatrix.
Live-Transport-Lanes teilen sich einen Vertrag, statt jeweils ihre eigene Szenariolistenform zu erfinden. `qa-channel` ist die breite synthetische Suite für Produktverhalten und ist nicht Teil der Live-Transport-Abdeckungsmatrix.
| Lane | Canary | Mention-Gating | Bot-zu-Bot | Allowlist-Block | Top-Level-Antwort | Neustart-Fortsetzung | Thread-Follow-up | Thread-Isolation | Reaktionsbeobachtung | Hilfebefehl | Native Befehlsregistrierung |
| -------- | ------ | -------------- | ---------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | --------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
| Lane | Canary | Mention-Gating | Bot-zu-Bot | Allowlist-Block | Top-Level-Antwort | Restart-Resume | Thread-Follow-up | Thread-Isolation | Reaktionsbeobachtung | Help-Befehl | Native Befehlsregistrierung |
| -------- | ------ | -------------- | ---------- | --------------- | ----------------- | -------------- | ---------------- | ---------------- | --------------------- | ----------- | --------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
So bleibt `qa-channel` die breite Suite für Produktverhalten, während Matrix,
Telegram und künftige Live-Transporte eine gemeinsame explizite Checkliste für den Transportvertrag
teilen.
Telegram und künftige Live-Transporte eine gemeinsame explizite Transportvertrags-
Checkliste nutzen.
Für eine kurzlebige Linux-VM-Lane ohne Docker in den QA-Pfad einzubeziehen, führen Sie Folgendes aus:
Für eine kurzlebige Linux-VM-Lane, ohne Docker in den QA-Pfad zu bringen, führen Sie aus:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
Dies startet einen frischen Multipass-Gast, installiert Abhängigkeiten, baut OpenClaw
im Gast, führt `qa suite` aus und kopiert dann den normalen QA-Bericht und die
Zusammenfassung zurück nach `.artifacts/qa-e2e/...` auf dem Host.
Es verwendet dasselbe Verhalten für die Szenarioauswahl wie `qa suite` auf dem Host.
Host- und Multipass-Suite-Läufe führen standardmäßig mehrere ausgewählte Szenarien parallel
mit isolierten Gateway-Workern aus. `qa-channel` verwendet standardmäßig eine Nebenläufigkeit
von 4, begrenzt durch die Anzahl der ausgewählten Szenarien. Verwenden Sie `--concurrency <count>`,
um die Anzahl der Worker anzupassen, oder `--concurrency 1` für serielle Ausführung.
Der Befehl beendet sich mit einem Nicht-Null-Code, wenn ein Szenario fehlschlägt. Verwenden Sie
`--allow-failures`, wenn Sie Artefakte ohne fehlschlagenden Exit-Code erhalten möchten.
Live-Läufe leiten die unterstützten QA-Authentifizierungseingaben weiter, die für den
innerhalb des Gasts, führt `qa suite` aus und kopiert dann den normalen QA-Bericht und
die Zusammenfassung zurück nach `.artifacts/qa-e2e/...` auf dem Host.
Es verwendet dasselbe Verhalten zur Szenarioauswahl wie `qa suite` auf dem Host.
Suite-Ausführungen auf Host und Multipass führen 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 <count>`, um
die Worker-Anzahl anzupassen, oder `--concurrency 1` für serielle Ausführung.
Der Befehl wird mit einem Exit-Code ungleich null beendet, wenn ein Szenario fehlschlägt. Verwenden Sie `--allow-failures`, wenn
Sie Artefakte ohne fehlgeschlagenen Exit-Code möchten.
Live-Ausführungen leiten die unterstützten QA-Auth-Eingaben weiter, die für den
Gast praktikabel sind: env-basierte Provider-Schlüssel, den Pfad zur QA-Live-Provider-Konfiguration und
`CODEX_HOME`, wenn vorhanden. Belassen Sie `--output-dir` unterhalb des Repo-Roots, damit der Gast
über den eingehängten Arbeitsbereich zurückschreiben kann.
`CODEX_HOME`, wenn vorhanden. Belassen Sie `--output-dir` unterhalb des Repo-Root, damit der Gast
über den gemounteten Workspace zurückschreiben kann.
## Referenz für Telegram-, Discord- und Slack-QA
## QA-Referenz für Telegram, Discord und Slack
Matrix hat wegen seiner Szenarioanzahl und der Docker-gestützten Homeserver-Bereitstellung eine [eigene Seite](/de/concepts/qa-matrix). Telegram, Discord und Slack sind kleiner: jeweils eine Handvoll Szenarien, kein Profilsystem, gegen bereits vorhandene echte Kanäle. Daher befindet sich ihre Referenz hier.
Matrix hat eine [eigene Seite](/de/concepts/qa-matrix), weil die Anzahl der Szenarien und die Docker-gestützte Bereitstellung des Homeservers größer sind. Telegram, Discord und Slack sind kleiner — jeweils eine Handvoll Szenarien, kein Profilsystem, gegen vorhandene echte Kanäle — deshalb befindet sich ihre Referenz hier.
### Gemeinsame CLI-Flags
Diese Lanes registrieren sich über `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` und akzeptieren dieselben Flags:
| Flag | Standard | Beschreibung |
| ------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Nur dieses Szenario ausführen. Wiederholbar. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Ort, an den Berichte/Zusammenfassung/beobachtete Nachrichten und das Ausgabelog geschrieben werden. Relative Pfade werden relativ zu `--repo-root` aufgelöst. |
| `--repo-root <path>` | `process.cwd()` | Repository-Root beim Aufruf aus einem neutralen Arbeitsverzeichnis. |
| `--sut-account <id>` | `sut` | Temporäre Konto-ID innerhalb der QA-Gateway-Konfiguration. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` oder `live-frontier` (das ältere `live-openai` funktioniert weiterhin). |
| `--model <ref>` / `--alt-model <ref>` | Provider-Standard | Primäre/alternative Modell-Refs. |
| `--fast` | aus | Schneller Provider-Modus, sofern unterstützt. |
| `--credential-source <env\|convex>` | `env` | Siehe [Convex-Anmeldeinformationspool](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` in CI, andernfalls `maintainer` | Rolle, die bei `--credential-source convex` verwendet wird. |
| Flag | Standard | Beschreibung |
| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Führt nur dieses Szenario aus. Wiederholbar. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Speicherort für Berichte/Zusammenfassung/beobachtete Nachrichten und das Ausgabelog. Relative Pfade werden gegen `--repo-root` aufgelöst. |
| `--repo-root <path>` | `process.cwd()` | Repository-Root beim Aufruf aus einem neutralen cwd. |
| `--sut-account <id>` | `sut` | Temporäre Konto-ID in der QA-Gateway-Konfiguration. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` oder `live-frontier` (das ältere `live-openai` funktioniert weiterhin). |
| `--model <ref>` / `--alt-model <ref>` | Provider-Standard | Primäre/alternative Modell-Refs. |
| `--fast` | aus | Provider-Schnellmodus, sofern unterstützt. |
| `--credential-source <env\|convex>` | `env` | Siehe [Convex-Anmeldeinformationspool](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` in CI, sonst `maintainer` | Rolle, die verwendet wird, wenn `--credential-source convex` gesetzt ist. |
Jede Lane beendet sich bei einem fehlgeschlagenen Szenario mit einem Nicht-Null-Code. `--allow-failures` schreibt Artefakte, ohne einen fehlschlagenden Exit-Code zu setzen.
Jede Lane wird mit einem Exit-Code ungleich null beendet, wenn ein Szenario fehlschlägt. `--allow-failures` schreibt Artefakte, ohne einen fehlgeschlagenen Exit-Code zu setzen.
### Telegram-QA
@ -217,7 +217,7 @@ Jede Lane beendet sich bei einem fehlgeschlagenen Szenario mit einem Nicht-Null-
pnpm openclaw qa telegram
```
Zielt auf eine echte private Telegram-Gruppe mit zwei unterschiedlichen Bots (Treiber + SUT). Der SUT-Bot muss einen Telegram-Benutzernamen haben; Bot-zu-Bot-Beobachtung funktioniert am besten, wenn beide Bots in `@BotFather` den **Bot-to-Bot Communication Mode** aktiviert haben.
Zielt auf eine echte private Telegram-Gruppe mit zwei unterschiedlichen Bots (Driver + SUT). Der SUT-Bot muss einen Telegram-Benutzernamen haben; Bot-zu-Bot-Beobachtung funktioniert am besten, wenn bei beiden Bots der **Bot-to-Bot Communication Mode** in `@BotFather` aktiviert ist.
Erforderliche env bei `--credential-source env`:
@ -243,7 +243,7 @@ Szenarien (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime
Ausgabeartefakte:
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — enthält RTT pro Antwort (Treibersendung → beobachtete SUT-Antwort), beginnend mit dem Canary.
- `telegram-qa-summary.json` — enthält Antwort-RTT pro Antwort (Driver-Senden → beobachtete SUT-Antwort), beginnend mit dem Canary.
- `telegram-qa-observed-messages.json` — Texte geschwärzt, außer `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
### Discord-QA
@ -252,7 +252,7 @@ Ausgabeartefakte:
pnpm openclaw qa discord
```
Zielt auf einen echten privaten Discord-Guild-Kanal mit zwei Bots: einen vom Harness gesteuerten Treiber-Bot und einen SUT-Bot, der vom untergeordneten OpenClaw-Gateway über das gebündelte Discord-Plugin gestartet wird. Prüft die Verarbeitung von Kanal-Erwähnungen, dass der SUT-Bot den nativen `/help`-Befehl bei Discord registriert hat, sowie optionale Mantis-Beweisszenarien.
Zielt auf einen echten privaten Discord-Guild-Kanal mit zwei Bots: einem Driver-Bot, der durch den Harness gesteuert wird, und einem SUT-Bot, der durch das untergeordnete OpenClaw-Gateway über das gebündelte Discord-Plugin gestartet wird. Überprüft die Verarbeitung von Kanal-Erwähnungen, dass der SUT-Bot den nativen Befehl `/help` bei Discord registriert hat, sowie optionale Mantis-Evidenzszenarien.
Erforderliche env bei `--credential-source env`:
@ -260,7 +260,7 @@ Erforderliche env bei `--credential-source env`:
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — muss mit der von Discord zurückgegebenen Benutzer-ID des SUT-Bots übereinstimmen (andernfalls schlägt die Lane früh fehl).
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — muss mit der von Discord zurückgegebenen SUT-Bot-Benutzer-ID übereinstimmen (sonst schlägt die Lane sofort fehl).
Optional:
@ -271,7 +271,7 @@ Szenarien (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.t
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
- `discord-status-reactions-tool-only` — optionales Mantis-Szenario. Läuft für sich allein, weil es den SUT auf immer aktive, reine Tool-Guild-Antworten mit `messages.statusReactions.enabled=true` umschaltet und dann eine REST-Reaktions-Timeline plus ein visuelles HTML/PNG-Artefakt erfasst.
- `discord-status-reactions-tool-only` — optionales Mantis-Szenario. Läuft für sich allein, weil es den SUT auf always-on, nur-Tool-Guild-Antworten mit `messages.statusReactions.enabled=true` umstellt und dann eine REST-Reaktionszeitleiste sowie ein visuelles HTML/PNG-Artefakt erfasst.
Führen Sie das Mantis-Statusreaktionsszenario explizit aus:
@ -297,7 +297,7 @@ Ausgabeartefakte:
pnpm openclaw qa slack
```
Zielt auf einen echten privaten Slack-Kanal mit zwei unterschiedlichen Bots: einen vom Harness gesteuerten Treiber-Bot und einen SUT-Bot, der vom untergeordneten OpenClaw-Gateway über das gebündelte Slack-Plugin gestartet wird.
Zielt auf einen echten privaten Slack-Kanal mit zwei unterschiedlichen Bots: einem Driver-Bot, der durch den Harness gesteuert wird, und einem SUT-Bot, der durch das untergeordnete OpenClaw-Gateway über das gebündelte Slack-Plugin gestartet wird.
Erforderliche env bei `--credential-source env`:
@ -321,43 +321,213 @@ Ausgabeartefakte:
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — Texte geschwärzt, außer `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
### Convex-Anmeldeinformationspool
#### Einrichten des Slack-Workspace
Telegram-, Discord- und Slack-Lanes können Anmeldeinformationen aus einem gemeinsamen Convex-Pool leasen, statt die obigen env vars zu lesen. Übergeben Sie `--credential-source convex` (oder setzen Sie `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab erwirbt einen exklusiven Lease, sendet während des Laufs Heartbeats dafür und gibt ihn beim Herunterfahren frei. Pool-Arten sind `"telegram"`, `"discord"` und `"slack"`.
Die Lane benötigt zwei unterschiedliche Slack-Apps in einem Workspace sowie einen Kanal, in dem beide Bots Mitglieder sind:
- `channelId` — die `Cxxxxxxxxxx`-ID eines Kanals, in den beide Bots eingeladen wurden. Verwenden Sie einen dedizierten Kanal; die Lane postet bei jeder Ausführung.
- `driverBotToken` — Bot-Token (`xoxb-...`) der **Driver**-App.
- `sutBotToken` — Bot-Token (`xoxb-...`) der **SUT**-App, die eine separate Slack-App vom Driver sein muss, damit ihre Bot-Benutzer-ID unterschiedlich ist.
- `sutAppToken` — App-Level-Token (`xapp-...`) der SUT-App mit `connections:write`, das von Socket Mode verwendet wird, damit die SUT-App Ereignisse empfangen kann.
Bevorzugen Sie einen Slack-Workspace, der QA gewidmet ist, statt einen Produktions-Workspace wiederzuverwenden.
Das folgende SUT-Manifest entspricht der Produktionsinstallation des gebündelten Slack-Plugins (`extensions/slack/src/setup-shared.ts:10`). Für die Einrichtung des Produktionskanals, wie Benutzer sie sehen, siehe [Schnelleinrichtung für den Slack-Kanal](/de/channels/slack#quick-setup); das QA-Driver/SUT-Paar ist absichtlich getrennt, weil die Lane zwei unterschiedliche Bot-Benutzer-IDs in einem Workspace benötigt.
**1. Erstellen Sie die Driver-App**
Gehen Sie zu [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → wählen Sie den QA-Workspace aus, fügen Sie das folgende Manifest ein und wählen Sie dann _Install to Workspace_:
```json
{
"display_information": {
"name": "OpenClaw QA Driver",
"description": "Test driver bot for OpenClaw QA Slack live lane"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA Driver",
"always_online": true
}
},
"oauth_config": {
"scopes": {
"bot": ["chat:write", "channels:history", "groups:history", "users:read"]
}
},
"settings": {
"socket_mode_enabled": false
}
}
```
Kopieren Sie den _Bot User OAuth Token_ (`xoxb-...`) — dieser wird zu `driverBotToken`. Der Driver muss nur Nachrichten posten und sich selbst identifizieren; keine Ereignisse, kein Socket Mode.
**2. Erstellen Sie die SUT-App**
Wiederholen Sie _Create New App → From a manifest_ im selben Workspace. Der Umfangssatz entspricht der Produktionsinstallation des gebündelten Slack-Plugins (`extensions/slack/src/setup-shared.ts:10`):
```json
{
"display_information": {
"name": "OpenClaw QA SUT",
"description": "OpenClaw QA SUT connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA SUT",
"always_online": true
},
"app_home": {
"home_tab_enabled": true,
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
}
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"usergroups:read",
"users:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_home_opened",
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
}
}
}
```
Nachdem Slack die App erstellt hat, erledigen Sie zwei Dinge auf ihrer Einstellungsseite:
- _Install to Workspace_ → kopieren Sie den _Bot User OAuth Token_ → dieser wird zu `sutBotToken`.
- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → fügen Sie den Scope `connections:write` hinzu → speichern → kopieren Sie den Wert `xapp-...` → dieser wird zu `sutAppToken`.
Verifizieren Sie, dass die beiden Bots unterschiedliche Benutzer-IDs haben, indem Sie für jedes Token `auth.test` aufrufen. Die Runtime unterscheidet Driver und SUT anhand der Benutzer-ID; wenn dieselbe App für beide wiederverwendet wird, schlägt die Prüfung der Erwähnungen sofort fehl.
**3. Kanal erstellen**
Erstellen Sie im QA-Workspace einen Kanal (z. B. `#openclaw-qa`) und laden Sie beide Bots aus dem Kanal heraus ein:
```
/invite @OpenClaw QA Driver
/invite @OpenClaw QA SUT
```
Kopieren Sie die ID `Cxxxxxxxxxx` aus _channel info → About → Channel ID_ — sie wird zu `channelId`. Ein öffentlicher Kanal funktioniert; wenn Sie einen privaten Kanal verwenden, haben beide Apps bereits `groups:history`, sodass die History-Lesezugriffe des Harness weiterhin erfolgreich sind.
**4. Zugangsdaten registrieren**
Es gibt zwei Optionen. Verwenden Sie Env Vars für das Debugging auf einem einzelnen Rechner (setzen Sie die vier Variablen `OPENCLAW_QA_SLACK_*` und übergeben Sie `--credential-source env`), oder befüllen Sie den gemeinsamen Convex-Pool, damit CI und andere Maintainer sie ausleihen können.
Für den Convex-Pool schreiben Sie die vier Felder in eine JSON-Datei:
```json
{
"channelId": "Cxxxxxxxxxx",
"driverBotToken": "xoxb-...",
"sutBotToken": "xoxb-...",
"sutAppToken": "xapp-..."
}
```
Wenn `OPENCLAW_QA_CONVEX_SITE_URL` und `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` in Ihrer Shell exportiert sind, registrieren und verifizieren Sie:
```bash
pnpm openclaw qa credentials add \
--kind slack \
--payload-file slack-creds.json \
--note "QA Slack pool seed"
pnpm openclaw qa credentials list --kind slack --status all --json
```
Erwarten Sie `count: 1`, `status: "active"` und kein Feld `lease`.
**5. Ende-zu-Ende verifizieren**
Führen Sie die Lane lokal aus, um zu bestätigen, dass beide Bots über den Broker miteinander sprechen können:
```bash
pnpm openclaw qa slack \
--credential-source convex \
--credential-role maintainer \
--output-dir .artifacts/qa-e2e/slack-local
```
Ein erfolgreicher Lauf ist in deutlich unter 30 Sekunden abgeschlossen, und `slack-qa-report.md` zeigt sowohl `slack-canary` als auch `slack-mention-gating` mit dem Status `pass`. Wenn die Lane ca. 90 Sekunden hängt und mit `Convex credential pool exhausted for kind "slack"` beendet wird, ist entweder der Pool leer oder jede Zeile ist ausgeliehen — `qa credentials list --kind slack --status all --json` zeigt Ihnen, was zutrifft.
### Convex-Zugangsdatenpool
Telegram-, Discord- und Slack-Lanes können Zugangsdaten aus einem gemeinsamen Convex-Pool ausleihen, anstatt die oben genannten Env Vars zu lesen. Übergeben Sie `--credential-source convex` (oder setzen Sie `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab erwirbt eine exklusive Leihe, sendet für die Dauer des Laufs Heartbeats dafür und gibt sie beim Herunterfahren frei. Pool-Arten sind `"telegram"`, `"discord"` und `"slack"`.
Payload-Formen, die der Broker bei `admin/add` validiert:
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` muss ein numerischer Chat-ID-String sein.
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` muss eine numerische Chat-ID-Zeichenkette sein.
- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` muss `^[A-Z][A-Z0-9]+$` entsprechen (eine Slack-ID wie `Cxxxxxxxxxx`). Siehe [Slack-Workspace einrichten](#setting-up-the-slack-workspace) für App- und Scope-Bereitstellung.
Betriebliche env vars und der Vertrag des Convex-Broker-Endpunkts befinden sich unter [Testing → Gemeinsame Telegram-Anmeldeinformationen über Convex](/de/help/testing#shared-telegram-credentials-via-convex-v1) (der Abschnittsname stammt aus der Zeit vor der Discord-Unterstützung; die Broker-Semantik ist für beide Arten identisch).
Operative Env Vars und der Endpoint-Vertrag des Convex-Brokers stehen unter [Testen → Gemeinsame Telegram-Zugangsdaten über Convex](/de/help/testing#shared-telegram-credentials-via-convex-v1) (der Abschnittsname stammt aus der Zeit vor der Discord-Unterstützung; die Broker-Semantik ist für beide Arten identisch).
## Repo-gestützte Seeds
Seed-Assets befinden sich in `qa/`:
Seed-Assets liegen in `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
Diese liegen absichtlich in Git, damit der QA-Plan sowohl für Menschen als auch für den
Agent sichtbar ist.
Diese liegen absichtlich in git, damit der QA-Plan sowohl für Menschen als auch für den Agent sichtbar ist.
`qa-lab` sollte ein generischer Markdown-Runner bleiben. Jede Szenario-Markdown-Datei ist
die Quelle der Wahrheit für einen Testlauf und sollte Folgendes definieren:
`qa-lab` sollte ein generischer Markdown-Runner bleiben. Jede Szenario-Markdown-Datei ist die Source of Truth für einen Testlauf und sollte Folgendes definieren:
- Szenario-Metadaten
- optionale Kategorie-, Capability-, Lane- und Risikometadaten
- Docs- und Code-Refs
- optionale Kategorie-, Capability-, Lane- und Risiko-Metadaten
- Dokumentations- und Code-Referenzen
- optionale Plugin-Anforderungen
- optionaler Gateway-Konfigurationspatch
- den ausführbaren `qa-flow`
- optionaler Gateway-Konfigurations-Patch
- der ausführbare `qa-flow`
Die wiederverwendbare Laufzeitoberfläche, die `qa-flow` unterstützt, darf generisch
und querschnittlich bleiben. Beispielsweise können Markdown-Szenarien transportseitige
Hilfsfunktionen mit browserseitigen Hilfsfunktionen kombinieren, die die eingebettete Control UI über den
Gateway-`browser.request`-Seam steuern, ohne einen Sonderfall-Runner hinzuzufügen.
Die wiederverwendbare Runtime-Oberfläche, die `qa-flow` unterstützt, darf generisch und querschnittlich bleiben. Markdown-Szenarien können beispielsweise transportseitige Helper mit browserseitigen Helpern kombinieren, die die eingebettete Control UI über die Gateway-Nahtstelle `browser.request` steuern, ohne einen Sonderfall-Runner hinzuzufügen.
Szenariodateien sollten nach Produkt-Capability gruppiert werden, nicht nach Source-Tree-Ordner. Halten Sie Szenario-IDs stabil, wenn Dateien verschoben werden; verwenden Sie `docsRefs` und `codeRefs` für Implementierungsnachverfolgbarkeit.
Szenario-Dateien sollten nach Produkt-Capability statt nach Source-Tree-Ordner gruppiert werden. Halten Sie Szenario-IDs stabil, wenn Dateien verschoben werden; verwenden Sie `docsRefs` und `codeRefs` für die Nachverfolgbarkeit der Implementierung.
Die Baseline-Liste sollte breit genug bleiben, um Folgendes abzudecken:
@ -365,9 +535,9 @@ Die Baseline-Liste sollte breit genug bleiben, um Folgendes abzudecken:
- Thread-Verhalten
- Lebenszyklus von Nachrichtenaktionen
- Cron-Callbacks
- Speicherabruf
- Memory-Abruf
- Modellwechsel
- Subagent-Übergabe
- Übergabe an Subagent
- Repo-Lesen und Docs-Lesen
- eine kleine Build-Aufgabe wie Lobster Invaders
@ -375,78 +545,71 @@ Die Baseline-Liste sollte breit genug bleiben, um Folgendes abzudecken:
`qa suite` hat zwei lokale Provider-Mock-Lanes:
- `mock-openai` ist der szenariobewusste OpenClaw-Mock. Er bleibt die standardmäßige
deterministische Mock-Lane für repo-gestützte QA und Parity-Gates.
- `aimock` startet einen AIMock-gestützten Provider-Server für experimentelle Protokoll-,
Fixture-, Record/Replay- und Chaos-Abdeckung. Er ist additiv und ersetzt nicht
den `mock-openai`-Szenario-Dispatcher.
- `mock-openai` ist der szenariobewusste OpenClaw-Mock. Er bleibt die standardmäßige deterministische Mock-Lane für repo-gestützte QA und Paritäts-Gates.
- `aimock` startet einen AIMock-gestützten Provider-Server für experimentelle Protokoll-, Fixture-, Record/Replay- und Chaos-Abdeckung. Er ist additiv und ersetzt den Szenario-Dispatcher `mock-openai` nicht.
Die Implementierung der Provider-Lanes befindet sich unter `extensions/qa-lab/src/providers/`.
Jeder Provider besitzt seine Defaults, den Start des lokalen Servers, die Gateway-Modellkonfiguration,
Staging-Anforderungen für Authentifizierungsprofile und Live-/Mock-Capability-Flags. Gemeinsamer Suite- und
Gateway-Code sollte über die Provider-Registry routen, statt nach
Provider-Namen zu verzweigen.
Die Implementierung der Provider-Lanes liegt unter `extensions/qa-lab/src/providers/`. Jeder Provider besitzt seine Defaults, den Start des lokalen Servers, die Gateway-Modellkonfiguration, Anforderungen an das Auth-Profile-Staging sowie Live-/Mock-Capability-Flags. Gemeinsamer Suite- und Gateway-Code sollte über die Provider-Registry routen, anstatt nach Provider-Namen zu verzweigen.
## Transportadapter
## Transport-Adapter
`qa-lab` besitzt einen generischen Transport-Seam für Markdown-QA-Szenarien. `qa-channel` ist der erste Adapter an diesem Seam, aber das Entwurfsziel ist breiter: Künftige echte oder synthetische Kanäle sollten sich in denselben Suite-Runner einklinken, statt einen transportspezifischen QA-Runner hinzuzufügen.
`qa-lab` besitzt eine generische Transport-Nahtstelle für Markdown-QA-Szenarien. `qa-channel` ist der erste Adapter auf dieser Nahtstelle, aber das Entwurfsziel ist breiter: Künftige echte oder synthetische Kanäle sollten sich in denselben Suite-Runner einklinken, anstatt einen transportspezifischen QA-Runner hinzuzufügen.
Auf Architekturebene ist die Aufteilung:
- `qa-lab` besitzt generische Szenarioausführung, Worker-Nebenläufigkeit, Artefaktschreiben und Reporting.
- Der Transportadapter besitzt Gateway-Konfiguration, Bereitschaft, eingehende und ausgehende Beobachtung, Transportaktionen und normalisierten Transportzustand.
- Markdown-Szenariodateien unter `qa/scenarios/` definieren den Testlauf; `qa-lab` stellt die wiederverwendbare Laufzeitoberfläche bereit, die sie ausführt.
- `qa-lab` besitzt generische Szenarioausführung, Worker-Parallelität, Artefaktschreiben und Reporting.
- Der Transport-Adapter besitzt Gateway-Konfiguration, Bereitschaft, eingehende und ausgehende Beobachtung, Transport-Aktionen und normalisierten Transportzustand.
- Markdown-Szenariodateien unter `qa/scenarios/` definieren den Testlauf; `qa-lab` stellt die wiederverwendbare Runtime-Oberfläche bereit, die sie ausführt.
### Einen Kanal hinzufügen
### Kanal hinzufügen
Das Hinzufügen eines Kanals zum Markdown-QA-System erfordert genau zwei Dinge:
1. Einen Transportadapter für den Kanal.
2. Ein Szenariopaket, das den Kanalvertrag ausübt.
1. Einen Transport-Adapter für den Kanal.
2. Ein Szenariopaket, das den Kanalvertrag testet.
Fügen Sie keinen neuen Top-Level-QA-Befehls-Root hinzu, wenn der gemeinsame `qa-lab`-Host den Flow besitzen kann.
Fügen Sie keinen neuen QA-Befehl auf oberster Ebene hinzu, wenn der gemeinsame Host `qa-lab` den Flow besitzen kann.
`qa-lab` ist für die gemeinsamen Host-Mechaniken zuständig:
`qa-lab` besitzt die gemeinsamen Host-Mechaniken:
- die Befehlswurzel `openclaw qa`
- den Befehls-Root `openclaw qa`
- Start und Teardown der Suite
- Worker-Parallelität
- Schreiben von Artefakten
- Berichtserstellung
- Artefaktschreiben
- Berichtserzeugung
- Szenarioausführung
- Kompatibilitätsaliasse für ältere `qa-channel`-Szenarien
- Kompatibilitätsaliase für ältere `qa-channel`-Szenarien
Runner-Plugins sind für den Transportvertrag zuständig:
Runner-Plugins besitzen den Transportvertrag:
- wie `openclaw qa <runner>` unterhalb der gemeinsamen `qa`-Wurzel eingebunden wird
- wie der Gateway für diesen Transport konfiguriert wird
- wie `openclaw qa <runner>` unter dem gemeinsamen Root `qa` eingehängt wird
- wie das Gateway für diesen Transport konfiguriert wird
- wie Bereitschaft geprüft wird
- wie eingehende Events injiziert werden
- wie ausgehende Nachrichten beobachtet werden
- wie Transkripte und normalisierter Transportzustand offengelegt werden
- wie Transkripte und normalisierter Transportzustand bereitgestellt werden
- wie transportgestützte Aktionen ausgeführt werden
- wie transportspezifisches Zurücksetzen oder Bereinigen behandelt wird
- wie transportspezifisches Zurücksetzen oder Bereinigen gehandhabt wird
Die Mindestanforderungen für die Einführung eines neuen Kanals:
1. Behalten Sie `qa-lab` als Owner der gemeinsamen `qa`-Wurzel bei.
2. Implementieren Sie den Transport-Runner auf der gemeinsamen Host-Naht von `qa-lab`.
3. Behalten Sie transportspezifische Mechaniken im Runner-Plugin oder Channel-Harness.
4. Binden Sie den Runner als `openclaw qa <runner>` ein, statt einen konkurrierenden Root-Befehl zu registrieren. Runner-Plugins sollten `qaRunners` in `openclaw.plugin.json` deklarieren und ein passendes `qaRunnerCliRegistrations`-Array aus `runtime-api.ts` exportieren. Halten Sie `runtime-api.ts` schlank; Lazy-CLI und Runner-Ausführung sollten hinter separaten Einstiegspunkten bleiben.
5. Erstellen oder adaptieren Sie Markdown-Szenarien unter den thematisch gegliederten `qa/scenarios/`-Verzeichnissen.
6. Verwenden Sie die generischen Szenario-Helfer für neue Szenarien.
7. Halten Sie vorhandene Kompatibilitätsaliasse funktionsfähig, sofern das Repo keine absichtliche Migration durchführt.
1. Behalten Sie `qa-lab` als Owner des gemeinsamen Roots `qa`.
2. Implementieren Sie den Transport-Runner auf der gemeinsamen Host-Nahtstelle von `qa-lab`.
3. Halten Sie transportspezifische Mechaniken im Runner-Plugin oder Channel-Harness.
4. Hängen Sie den Runner als `openclaw qa <runner>` ein, anstatt einen konkurrierenden Root-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 Entrypoints bleiben.
5. Erstellen oder adaptieren Sie Markdown-Szenarien unter den thematischen Verzeichnissen `qa/scenarios/`.
6. Verwenden Sie die generischen Szenario-Helper für neue Szenarien.
7. Halten Sie bestehende Kompatibilitätsaliase funktionsfähig, es sei denn, das Repo führt eine beabsichtigte Migration durch.
Die Entscheidungsregel ist strikt:
- Wenn Verhalten einmalig in `qa-lab` ausgedrückt werden kann, platzieren Sie es in `qa-lab`.
- Wenn Verhalten von einem Channel-Transport abhängt, behalten Sie es in diesem Runner-Plugin oder Plugin-Harness.
- Wenn ein Szenario eine neue Fähigkeit benötigt, die mehr als ein Channel verwenden kann, fügen Sie einen generischen Helfer hinzu statt eines channelspezifischen Zweigs in `suite.ts`.
- Wenn ein Verhalten nur für einen Transport sinnvoll ist, halten Sie das Szenario transportspezifisch und machen Sie das im Szenariovertrag explizit.
- Wenn Verhalten einmal in `qa-lab` ausgedrückt werden kann, legen Sie es in `qa-lab` ab.
- Wenn Verhalten von einem Kanaltransport abhängt, behalten Sie es in diesem Runner-Plugin oder Plugin-Harness.
- Wenn ein Szenario eine neue Capability benötigt, die mehr als ein Kanal verwenden kann, fügen Sie einen generischen Helper hinzu statt einer kanalspezifischen Verzweigung in `suite.ts`.
- Wenn ein Verhalten nur für einen Transport sinnvoll ist, halten Sie das Szenario transportspezifisch und machen Sie dies im Szenariovertrag explizit.
### Namen von Szenario-Helfern
### Namen von Szenario-Helpern
Bevorzugte generische Helfer für neue Szenarien:
Bevorzugte generische Helper für neue Szenarien:
- `waitForTransportReady`
- `waitForChannelReady`
@ -461,21 +624,21 @@ Bevorzugte generische Helfer für neue Szenarien:
- `formatTransportTranscript`
- `resetTransport`
Kompatibilitätsaliasse bleiben für vorhandene Szenarien verfügbar — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — aber neue Szenarien sollten die generischen Namen verwenden. Die Aliasse existieren, um eine Flag-Day-Migration zu vermeiden, nicht als Modell für die Zukunft.
Kompatibilitätsaliase bleiben für bestehende Szenarien verfügbar — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — aber beim Erstellen neuer Szenarien sollten die generischen Namen verwendet werden. Die Aliase existieren, um eine erzwungene Stichtagsmigration zu vermeiden, nicht als künftiges Modell.
## Berichterstattung
## Reporting
`qa-lab` exportiert einen Markdown-Protokollbericht aus der beobachteten Bus-Zeitleiste.
`qa-lab` exportiert einen Markdown-Protokollbericht aus der beobachteten Bus-Timeline.
Der Bericht sollte beantworten:
- Was funktioniert hat
- Was fehlgeschlagen ist
- Was blockiert geblieben ist
- Welche Folgeszenarien ergänzt werden sollten
- Welche Folgeszenarien sinnvoll ergänzt werden sollten
Für das Inventar der verfügbaren Szenarien — nützlich beim Dimensionieren von Folgearbeiten oder beim Verdrahten eines neuen Transports — führen Sie `pnpm openclaw qa coverage` aus (fügen Sie `--json` für maschinenlesbare Ausgabe hinzu).
Für das Inventar verfügbarer Szenarien — nützlich beim Abschätzen von Folgearbeiten oder beim Verdrahten eines neuen Transports — führen Sie `pnpm openclaw qa coverage` aus (fügen Sie `--json` für maschinenlesbare Ausgabe hinzu).
Für Zeichen- und Stilprüfungen führen Sie dasselbe Szenario über mehrere Live-Modell-Refs aus und schreiben einen bewerteten Markdown-Bericht:
Für Zeichen- und Stilprüfungen führen Sie dasselbe Szenario mit mehreren Live-Modell-Refs aus und schreiben Sie einen bewerteten Markdown-Bericht:
```bash
pnpm openclaw qa character-eval \
@ -494,17 +657,23 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
Der Befehl führt lokale QA-Gateway-Child-Prozesse aus, nicht Docker. Character-Eval-Szenarien sollten die Persona über `SOUL.md` setzen und dann normale Benutzer-Turns ausführen, etwa Chat, Workspace-Hilfe und kleine Dateiaufgaben. Dem Kandidatenmodell sollte nicht mitgeteilt werden, dass es evaluiert wird. Der Befehl bewahrt jedes vollständige Transkript auf, zeichnet grundlegende Laufstatistiken auf und bittet dann die Judge-Modelle im schnellen Modus mit `xhigh`-Reasoning, soweit unterstützt, die Läufe nach Natürlichkeit, Vibe und Humor zu bewerten.
Verwenden Sie `--blind-judge-models`, wenn Sie Provider vergleichen: Der Judge-Prompt erhält weiterhin jedes Transkript und jeden Laufstatus, aber Kandidaten-Refs werden durch neutrale Labels wie `candidate-01` ersetzt; der Bericht ordnet die Rankings nach dem Parsen wieder den echten Refs zu.
Kandidatenläufe verwenden standardmäßig `high`-Thinking, mit `medium` für GPT-5.5 und `xhigh` für ältere OpenAI-Eval-Refs, die es unterstützen. Überschreiben Sie einen bestimmten Kandidaten inline mit `--model provider/model,thinking=<level>`. `--thinking <level>` setzt weiterhin einen globalen Fallback, und die ältere Form `--model-thinking <provider/model=level>` bleibt aus Kompatibilitätsgründen erhalten.
OpenAI-Kandidaten-Refs verwenden standardmäßig den schnellen Modus, damit Priority Processing genutzt wird, sofern der Provider es unterstützt. Fügen Sie inline `,fast`, `,no-fast` oder `,fast=false` hinzu, wenn ein einzelner Kandidat oder Judge eine Überschreibung benötigt. Übergeben Sie `--fast` nur, wenn Sie den schnellen Modus für jedes Kandidatenmodell erzwingen möchten. Kandidaten- und Judge-Dauern werden im Bericht für Benchmark-Analysen aufgezeichnet, aber Judge-Prompts sagen ausdrücklich, nicht nach Geschwindigkeit zu ranken.
Kandidaten- und Judge-Modellläufe verwenden beide standardmäßig Parallelität 16. Senken Sie `--concurrency` oder `--judge-concurrency`, wenn Provider-Limits oder lokaler Gateway-Druck einen Lauf zu verrauscht machen.
Wenn kein Kandidat `--model` übergeben wird, verwendet die Character-Eval standardmäßig `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` und `google/gemini-3.1-pro-preview`, wenn kein `--model` übergeben wird.
Wenn kein `--judge-model` übergeben wird, verwenden die Judges standardmäßig `openai/gpt-5.5,thinking=xhigh,fast` und `anthropic/claude-opus-4-6,thinking=high`.
Der Befehl führt lokale untergeordnete QA-Gateway-Prozesse aus, nicht Docker. Charakter-Evaluierungsszenarien sollten die Persona über `SOUL.md` festlegen und dann normale Benutzereingaben wie Chat, Workspace-Hilfe und kleine Dateiaufgaben ausführen. Dem Kandidatenmodell sollte nicht mitgeteilt werden, dass es evaluiert wird. Der Befehl bewahrt jedes vollständige Transkript auf, zeichnet grundlegende Laufstatistiken auf und bittet dann die Judge-Modelle im schnellen Modus mit `xhigh`-Reasoning, sofern unterstützt, die Läufe nach Natürlichkeit, Atmosphäre und Humor zu bewerten.
Verwenden Sie `--blind-judge-models` beim Vergleich von Providern: Der Judge-Prompt erhält weiterhin jedes Transkript und jeden Laufstatus, aber Kandidatenreferenzen werden durch neutrale Labels wie `candidate-01` ersetzt; der Bericht ordnet die Ranglisten nach dem Parsen wieder den echten Referenzen zu.
Kandidatenläufe verwenden standardmäßig `high` Thinking, mit `medium` für GPT-5.5 und `xhigh` für ältere OpenAI-Evaluierungsreferenzen, die dies unterstützen. Überschreiben Sie einen bestimmten Kandidaten inline mit `--model provider/model,thinking=<level>`. `--thinking <level>` legt weiterhin einen globalen Fallback fest, und die ältere Form `--model-thinking <provider/model=level>` bleibt aus Kompatibilitätsgründen erhalten.
OpenAI-Kandidatenreferenzen verwenden standardmäßig den schnellen Modus, sodass Prioritätsverarbeitung genutzt wird, wenn der Provider sie unterstützt. Fügen Sie inline `,fast`, `,no-fast` oder `,fast=false` hinzu, wenn ein einzelner Kandidat oder Judge eine Überschreibung benötigt. Übergeben Sie `--fast` nur, wenn Sie den schnellen Modus für jedes Kandidatenmodell erzwingen möchten. Die Dauer von Kandidaten- und Judge-Läufen wird für die Benchmark-Analyse im Bericht aufgezeichnet, aber die Judge-Prompts weisen ausdrücklich an, nicht nach Geschwindigkeit zu bewerten.
Kandidaten- und Judge-Modellläufe verwenden beide standardmäßig eine Parallelität von 16. Senken Sie `--concurrency` oder `--judge-concurrency`, wenn Provider-Limits oder lokaler Gateway-Druck einen Lauf zu verrauscht machen.
Wenn kein Kandidaten-`--model` übergeben wird, verwendet die Charakter-Evaluierung standardmäßig
`openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
`moonshot/kimi-k2.5` und
`google/gemini-3.1-pro-preview`, wenn kein `--model` übergeben wird.
Wenn kein `--judge-model` übergeben wird, verwenden die Judges standardmäßig
`openai/gpt-5.5,thinking=xhigh,fast` und
`anthropic/claude-opus-4-6,thinking=high`.
## Zugehörige Dokumentation
## Verwandte Dokumentation
- [Matrix-QA](/de/concepts/qa-matrix)
- [QA Channel](/de/channels/qa-channel)
- [Testen](/de/help/testing)
- [QA-Kanal](/de/channels/qa-channel)
- [Tests](/de/help/testing)
- [Dashboard](/de/web/dashboard)

238
docs/de/gateway/config-tools.md
View File

@ -1,59 +1,59 @@
---
read_when:
- Konfiguration von `tools.*`-Richtlinien, Allowlists oder experimentellen Funktionen
- Konfigurieren der `tools.*`-Richtlinie, von Zulassungslisten oder experimentellen Funktionen
- Benutzerdefinierte Provider registrieren oder Basis-URLs überschreiben
- OpenAI-kompatible selbst gehostete Endpunkte einrichten
sidebarTitle: Tools and custom providers
summary: Tools-Konfiguration (Richtlinie, experimentelle Schalter, Provider-gestützte Tools) und Einrichtung benutzerdefinierter Provider-/Basis-URLs
title: Konfiguration — Werkzeuge und benutzerdefinierte Provider
summary: Tool-Konfiguration (Richtlinie, experimentelle Umschalter, Provider-gestützte Tools) und Einrichtung benutzerdefinierter Provider/Basis-URLs
title: Konfiguration — Tools und benutzerdefinierte Provider
x-i18n:
generated_at: "2026-05-03T21:31:46Z"
generated_at: "2026-05-05T01:45:57Z"
model: gpt-5.5
provider: openai
source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da
source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883
source_path: gateway/config-tools.md
workflow: 16
---
`tools.*`-Konfigurationsschlüssel und benutzerdefinierte Provider- und Basis-URL-Einrichtung. Informationen zu Agenten, Kanälen und anderen Konfigurationsschlüsseln auf oberster Ebene finden Sie in der [Konfigurationsreferenz](/de/gateway/configuration-reference).
`tools.*`-Konfigurationsschlüssel und benutzerdefinierte Provider-/Basis-URL-Einrichtung. Für Agenten, Kanäle und andere Konfigurationsschlüssel der obersten Ebene siehe [Konfigurationsreferenz](/de/gateway/configuration-reference).
## Tools
## Werkzeuge
### Tool-Profile
### Werkzeugprofile
`tools.profile` legt eine Basis-Erlaubnisliste vor `tools.allow`/`tools.deny` fest:
`tools.profile` legt eine Basis-Allowlist vor `tools.allow`/`tools.deny` fest:
<Note>
Lokales Onboarding setzt neue lokale Konfigurationen standardmäßig auf `tools.profile: "coding"`, wenn es nicht gesetzt ist (bestehende explizite Profile bleiben erhalten).
Lokales Onboarding setzt neue lokale Konfigurationen standardmäßig auf `tools.profile: "coding"`, wenn nichts festgelegt ist (bestehende explizite Profile bleiben erhalten).
</Note>
| Profil | Enthält |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` | nur `session_status` |
| Profil | Enthält |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `minimal` | Nur `session_status` |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `full` | Keine Einschränkung (wie nicht gesetzt) |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `full` | Keine Einschränkung (wie nicht gesetzt) |
### Tool-Gruppen
### Werkzeuggruppen
| Gruppe | Tools |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` wird als Alias für `exec` akzeptiert) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
| `group:web` | `web_search`, `x_search`, `web_fetch` |
| `group:ui` | `browser`, `canvas` |
| `group:automation` | `cron`, `gateway` |
| `group:messaging` | `message` |
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
| `group:openclaw` | Alle integrierten Tools (schließt Provider-Plugins aus) |
| Gruppe | Werkzeuge |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` wird als Alias für `exec` akzeptiert) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
| `group:web` | `web_search`, `x_search`, `web_fetch` |
| `group:ui` | `browser`, `canvas` |
| `group:automation` | `cron`, `gateway` |
| `group:messaging` | `message` |
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
| `group:openclaw` | Alle integrierten Werkzeuge (schließt Provider-Plugins aus) |
### `tools.allow` / `tools.deny`
Globale Erlauben/Verweigern-Richtlinie für Tools (Verweigern gewinnt). Groß-/Kleinschreibung wird ignoriert, unterstützt `*`-Platzhalter. Wird auch angewendet, wenn die Docker-Sandbox deaktiviert ist.
Globale Allow-/Deny-Richtlinie für Werkzeuge (Deny gewinnt). Groß-/Kleinschreibung wird ignoriert, unterstützt `*`-Wildcards. Wird auch angewendet, wenn die Docker-Sandbox deaktiviert ist.
```json5
{
@ -61,7 +61,7 @@ Globale Erlauben/Verweigern-Richtlinie für Tools (Verweigern gewinnt). Groß-/K
}
```
`write` und `apply_patch` sind separate Tool-IDs. `allow: ["write"]` aktiviert für kompatible Modelle auch `apply_patch`, aber `deny: ["write"]` verweigert `apply_patch` nicht. Um alle Dateimutationen zu blockieren, verweigern Sie `group:fs` oder listen Sie jedes mutierende Tool explizit auf:
`write` und `apply_patch` sind separate Werkzeug-IDs. `allow: ["write"]` aktiviert für kompatible Modelle auch `apply_patch`, aber `deny: ["write"]` verweigert `apply_patch` nicht. Um alle Dateimutationen zu blockieren, verweigern Sie `group:fs` oder listen Sie jedes mutierende Werkzeug explizit auf:
```json5
{
@ -71,7 +71,7 @@ Globale Erlauben/Verweigern-Richtlinie für Tools (Verweigern gewinnt). Groß-/K
### `tools.byProvider`
Schränkt Tools für bestimmte Provider oder Modelle weiter ein. Reihenfolge: Basisprofil → Provider-Profil → Erlauben/Verweigern.
Beschränkt Werkzeuge für bestimmte Provider oder Modelle weiter. Reihenfolge: Basisprofil → Provider-Profil → Allow/Deny.
```json5
{
@ -103,9 +103,9 @@ Steuert erhöhten `exec`-Zugriff außerhalb der Sandbox:
}
```
- Die Überschreibung pro Agent (`agents.list[].tools.elevated`) kann nur weiter einschränken.
- Überschreibung pro Agent (`agents.list[].tools.elevated`) kann nur weiter einschränken.
- `/elevated on|off|ask|full` speichert den Zustand pro Sitzung; Inline-Direktiven gelten für eine einzelne Nachricht.
- Erhöhtes `exec` umgeht die Sandbox und verwendet den konfigurierten Escape-Pfad (standardmäßig `gateway`, oder `node`, wenn das `exec`-Ziel `node` ist).
- Erhöhtes `exec` umgeht Sandboxing und verwendet den konfigurierten Escape-Pfad (`gateway` standardmäßig oder `node`, wenn das `exec`-Ziel `node` ist).
### `tools.exec`
@ -129,7 +129,7 @@ Steuert erhöhten `exec`-Zugriff außerhalb der Sandbox:
### `tools.loopDetection`
Sicherheitsprüfungen für Tool-Schleifen sind **standardmäßig deaktiviert**. Setzen Sie `enabled: true`, um die Erkennung zu aktivieren. Einstellungen können global in `tools.loopDetection` definiert und pro Agent unter `agents.list[].tools.loopDetection` überschrieben werden.
Sicherheitsprüfungen für Werkzeugschleifen sind **standardmäßig deaktiviert**. Setzen Sie `enabled: true`, um die Erkennung zu aktivieren. Einstellungen können global in `tools.loopDetection` definiert und pro Agent unter `agents.list[].tools.loopDetection` überschrieben werden.
```json5
{
@ -151,25 +151,25 @@ Sicherheitsprüfungen für Tool-Schleifen sind **standardmäßig deaktiviert**.
```
<ParamField path="historySize" type="number">
Maximaler Tool-Aufrufverlauf, der für die Schleifenanalyse aufbewahrt wird.
Maximale Historie von Werkzeugaufrufen, die für die Schleifenanalyse aufbewahrt wird.
</ParamField>
<ParamField path="warningThreshold" type="number">
Schwellenwert für wiederkehrende Muster ohne Fortschritt, ab dem Warnungen ausgegeben werden.
Schwellenwert für sich wiederholende Muster ohne Fortschritt, ab dem Warnungen ausgegeben werden.
</ParamField>
<ParamField path="criticalThreshold" type="number">
Höherer Wiederholungsschwellenwert zum Blockieren kritischer Schleifen.
</ParamField>
<ParamField path="globalCircuitBreakerThreshold" type="number">
Hartes Stopplimit für jeden Lauf ohne Fortschritt.
Harter Stopp-Schwellenwert für jeden Durchlauf ohne Fortschritt.
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
Warnt bei wiederholten Aufrufen desselben Tools mit denselben Argumenten.
Warnen bei wiederholten Aufrufen mit demselben Werkzeug und denselben Argumenten.
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
Warnt/blockiert bei bekannten Polling-Tools (`process.poll`, `command_status` usw.).
Warnen/blockieren bei bekannten Poll-Werkzeugen (`process.poll`, `command_status` usw.).
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
Warnt/blockiert bei abwechselnden Paarmustern ohne Fortschritt.
Warnen/blockieren bei alternierenden Paarmustern ohne Fortschritt.
</ParamField>
<Warning>
@ -208,7 +208,7 @@ Wenn `warningThreshold >= criticalThreshold` oder `criticalThreshold >= globalCi
### `tools.media`
Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video):
Konfiguriert das Verständnis eingehender Medien (Bild/Audio/Video):
```json5
{
@ -216,7 +216,7 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video):
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // opt-in: send finished async video directly to the channel
directSend: false, // deprecated: completions stay agent-mediated
},
audio: {
enabled: true,
@ -246,7 +246,7 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video):
```
<AccordionGroup>
<Accordion title="Media model entry fields">
<Accordion title="Felder für Medienmodelleinträge">
**Provider-Eintrag** (`type: "provider"` oder ausgelassen):
- `provider`: API-Provider-ID (`openai`, `anthropic`, `google`/`gemini`, `groq` usw.)
@ -255,21 +255,21 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video):
**CLI-Eintrag** (`type: "cli"`):
- `command`: auszuführbares Programm
- `command`: auszuführbare Datei
- `args`: vorlagenbasierte Argumente (unterstützt `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` usw.; `openclaw doctor --fix` migriert veraltete `{input}`-Platzhalter zu `{{MediaPath}}`)
**Gemeinsame Felder:**
- `capabilities`: optionale Liste (`image`, `audio`, `video`). Standardwerte: `openai`/`anthropic`/`minimax` → Bild, `google` → Bild+Audio+Video, `groq` → Audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: Überschreibungen pro Eintrag.
- `tools.media.image.timeoutSeconds` und passende `timeoutSeconds`-Einträge des Bildmodells gelten auch, wenn der Agent das explizite `image`-Tool aufruft.
- Bei Fehlern wird auf den nächsten Eintrag zurückgegriffen.
- `tools.media.image.timeoutSeconds` und passende `timeoutSeconds`-Einträge für Bildmodelle gelten auch, wenn der Agent das explizite `image`-Tool aufruft.
- Fehler fallen auf den nächsten Eintrag zurück.
Die Provider-Authentifizierung folgt der Standardreihenfolge: `auth-profiles.json` → Umgebungsvariablen → `models.providers.*.apiKey`.
**Felder für asynchrone Fertigstellung:**
**Felder für asynchrone Abschlüsse:**
- `asyncCompletion.directSend`: Wenn `true`, versuchen abgeschlossene asynchrone Medienaufgaben, die direkte Auslieferung der Fertigstellung unterstützen, zuerst die direkte Kanalauslieferung. Standard: `false` (Requester-Session-Weck-/Modellauslieferungspfad). Derzeit gilt dies für asynchrones `video_generate`; asynchrone `music_generate`-Fertigstellungen bleiben über die Requester-Session vermittelt, auch wenn dies aktiviert ist.
- `asyncCompletion.directSend`: veraltetes Kompatibilitäts-Flag. Abgeschlossene asynchrone Medienaufgaben bleiben über die anfragende Sitzung vermittelt, damit der Agent das Ergebnis erhält, entscheidet, wie er den Benutzer informiert, und das Nachrichten-Tool verwendet, wenn die Zustellung an die Quelle dies erfordert.
</Accordion>
</AccordionGroup>
@ -289,9 +289,9 @@ Konfiguriert das Verstehen eingehender Medien (Bild/Audio/Video):
### `tools.sessions`
Steuert, welche Sessions von den Session-Tools (`sessions_list`, `sessions_history`, `sessions_send`) als Ziel verwendet werden können.
Steuert, welche Sitzungen von den Sitzungs-Tools (`sessions_list`, `sessions_history`, `sessions_send`) adressiert werden können.
Standard: `tree` (aktuelle Session + von ihr gestartete Sessions, z. B. Subagenten).
Standard: `tree` (aktuelle Sitzung + von ihr gestartete Sitzungen, z. B. Subagents).
```json5
{
@ -305,19 +305,19 @@ Standard: `tree` (aktuelle Session + von ihr gestartete Sessions, z. B. Subagent
```
<AccordionGroup>
<Accordion title="Visibility scopes">
- `self`: nur der aktuelle Session-Schlüssel.
- `tree`: aktuelle Session + von der aktuellen Session gestartete Sessions (Subagenten).
- `agent`: jede Session, die zur aktuellen Agent-ID gehört (kann andere Benutzer einschließen, wenn Sie Absender-spezifische Sessions unter derselben Agent-ID ausführen).
- `all`: jede Session. Agent-übergreifende Zielauswahl erfordert weiterhin `tools.agentToAgent`.
- Sandbox-Begrenzung: Wenn die aktuelle Session in einer Sandbox ausgeführt wird und `agents.defaults.sandbox.sessionToolsVisibility="spawned"` gilt, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"` gesetzt ist.
<Accordion title="Sichtbarkeitsbereiche">
- `self`: nur der Schlüssel der aktuellen Sitzung.
- `tree`: aktuelle Sitzung + von der aktuellen Sitzung gestartete Sitzungen (Subagents).
- `agent`: jede Sitzung, die zur aktuellen Agent-ID gehört (kann andere Benutzer einschließen, wenn Sie sitzungsbezogene Sender-Sitzungen unter derselben Agent-ID ausführen).
- `all`: jede Sitzung. Agent-übergreifendes Targeting erfordert weiterhin `tools.agentToAgent`.
- Sandbox-Begrenzung: Wenn die aktuelle Sitzung in einer Sandbox ausgeführt wird und `agents.defaults.sandbox.sessionToolsVisibility="spawned"` gilt, wird die Sichtbarkeit auf `tree` erzwungen, selbst wenn `tools.sessions.visibility="all"` gesetzt ist.
</Accordion>
</AccordionGroup>
### `tools.sessions_spawn`
Steuert die Unterstützung für Inline-Anhänge bei `sessions_spawn`.
Steuert die Unterstützung für Inline-Anhänge für `sessions_spawn`.
```json5
{
@ -337,12 +337,12 @@ Steuert die Unterstützung für Inline-Anhänge bei `sessions_spawn`.
<AccordionGroup>
<Accordion title="Hinweise zu Anhängen">
- Anhänge werden nur für `runtime: "subagent"` unterstützt. Die ACP-Laufzeit weist sie zurück.
- Dateien werden im untergeordneten Workspace unter `.openclaw/attachments/<uuid>/` mit einer `.manifest.json` materialisiert.
- Anhangsinhalte werden automatisch aus der Transkript-Persistenz redigiert.
- Base64-Eingaben werden mit strengen Alphabet-/Padding-Prüfungen und einer Größenabsicherung vor dem Dekodieren validiert.
- Anhänge werden nur für `runtime: "subagent"` unterstützt. Die ACP-Laufzeit lehnt sie ab.
- Dateien werden im untergeordneten Arbeitsbereich unter `.openclaw/attachments/<uuid>/` mit einer `.manifest.json` materialisiert.
- Anhangsinhalte werden automatisch aus der Transkriptpersistenz redigiert.
- Base64-Eingaben werden mit strengen Prüfungen für Alphabet/Auffüllung und einer Größenprüfung vor dem Dekodieren validiert.
- Dateiberechtigungen sind `0700` für Verzeichnisse und `0600` für Dateien.
- Die Bereinigung folgt der `cleanup`-Richtlinie: `delete` entfernt Anhänge immer; `keep` behält sie nur bei, wenn `retainOnSessionKeep: true` gesetzt ist.
- Die Bereinigung folgt der `cleanup`-Richtlinie: `delete` entfernt Anhänge immer; `keep` behält sie nur bei, wenn `retainOnSessionKeep: true` gilt.
</Accordion>
</AccordionGroup>
@ -351,7 +351,7 @@ Steuert die Unterstützung für Inline-Anhänge bei `sessions_spawn`.
### `tools.experimental`
Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, sofern keine automatische Aktivierungsregel für strikt agentische GPT-5-Runs greift.
Experimentelle Flags für integrierte Tools. Standardmäßig deaktiviert, sofern keine automatische Aktivierungsregel für strikt agentische GPT-5 gilt.
```json5
{
@ -364,8 +364,8 @@ Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, sofern keine
```
- `planTool`: aktiviert das strukturierte Tool `update_plan` für die Nachverfolgung nicht trivialer mehrstufiger Arbeiten.
- Standard: `false`, sofern `agents.defaults.embeddedPi.executionContract` (oder eine Überschreibung pro Agent) für einen OpenAI- oder OpenAI Codex-Run aus der GPT-5-Familie nicht auf `"strict-agentic"` gesetzt ist. Setzen Sie `true`, um das Tool außerhalb dieses Bereichs zu erzwingen, oder `false`, um es selbst für strikt agentische GPT-5-Runs deaktiviert zu lassen.
- Wenn aktiviert, fügt der System-Prompt außerdem Nutzungshinweise hinzu, damit das Modell es nur für umfangreiche Arbeiten verwendet und höchstens einen Schritt auf `in_progress` hält.
- Standard: `false`, sofern `agents.defaults.embeddedPi.executionContract` (oder eine agentenspezifische Überschreibung) nicht für einen Lauf mit OpenAI- oder OpenAI Codex-Modellen der GPT-5-Familie auf `"strict-agentic"` gesetzt ist. Setzen Sie `true`, um das Tool außerhalb dieses Geltungsbereichs zu erzwingen, oder `false`, um es auch für strikt agentische GPT-5-Läufe deaktiviert zu lassen.
- Wenn aktiviert, ergänzt der System-Prompt außerdem Nutzungshinweise, damit das Modell es nur für umfangreiche Arbeiten verwendet und höchstens einen Schritt auf `in_progress` hält.
### `agents.defaults.subagents`
@ -385,8 +385,8 @@ Experimentelle integrierte Tool-Flags. Standardmäßig deaktiviert, sofern keine
}
```
- `model`: Standardmodell für gestartete Sub-Agents. Wenn ausgelassen, übernehmen Sub-Agents das Modell des Aufrufers.
- `allowAgents`: standardmäßige Allowlist von Ziel-Agent-IDs für `sessions_spawn`, wenn der anfragende Agent keine eigenen `subagents.allowAgents` setzt (`["*"]` = beliebig; Standard: nur derselbe Agent).
- `model`: Standardmodell für gestartete Sub-Agents. Wenn weggelassen, erben Sub-Agents das Modell des Aufrufers.
- `allowAgents`: Standard-Allowlist der Ziel-Agent-IDs für `sessions_spawn`, wenn der anfragende Agent kein eigenes `subagents.allowAgents` festlegt (`["*"]` = beliebig; Standard: nur derselbe Agent).
- `runTimeoutSeconds`: Standard-Timeout (Sekunden) für `sessions_spawn`, wenn der Tool-Aufruf `runTimeoutSeconds` auslässt. `0` bedeutet kein Timeout.
- Tool-Richtlinie pro Sub-Agent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
@ -426,17 +426,17 @@ OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte
<AccordionGroup>
<Accordion title="Authentifizierung und Merge-Priorität">
- Verwenden Sie `authHeader: true` + `headers` für benutzerdefinierte Authentifizierungsanforderungen.
- Überschreiben Sie das Root-Verzeichnis der Agent-Konfiguration mit `OPENCLAW_AGENT_DIR` (oder `PI_CODING_AGENT_DIR`, einem Alias einer veralteten Umgebungsvariablen).
- Überschreiben Sie den Agent-Konfigurationsstamm mit `OPENCLAW_AGENT_DIR` (oder `PI_CODING_AGENT_DIR`, einem Alias einer Legacy-Umgebungsvariable).
- Merge-Priorität für übereinstimmende Provider-IDs:
- Nicht leere `baseUrl`-Werte aus `models.json` des Agents gewinnen.
- Nicht leere `apiKey`-Werte des Agents gewinnen nur, wenn dieser Provider im aktuellen Konfigurations-/Auth-Profil-Kontext nicht SecretRef-verwaltet ist.
- SecretRef-verwaltete Provider-`apiKey`-Werte werden aus Quellmarkern (`ENV_VAR_NAME` für Umgebungsreferenzen, `secretref-managed` für Datei-/Exec-Referenzen) aktualisiert, statt aufgelöste Secrets zu persistieren.
- SecretRef-verwaltete Provider-Header-Werte werden aus Quellmarkern (`secretref-env:ENV_VAR_NAME` für Umgebungsreferenzen, `secretref-managed` für Datei-/Exec-Referenzen) aktualisiert.
- Leere oder fehlende Agent-`apiKey`-/`baseUrl`-Werte fallen auf `models.providers` in der Konfiguration zurück.
- Nicht leere Werte aus Agent-`models.json` für `baseUrl` gewinnen.
- Nicht leere Agent-Werte für `apiKey` gewinnen nur, wenn dieser Provider im aktuellen Konfigurations-/Authentifizierungsprofilkontext nicht von SecretRef verwaltet wird.
- Von SecretRef verwaltete Provider-Werte für `apiKey` werden aus Quellmarkierungen (`ENV_VAR_NAME` für env-Referenzen, `secretref-managed` für Datei-/Exec-Referenzen) aktualisiert, statt aufgelöste Geheimnisse zu persistieren.
- Von SecretRef verwaltete Provider-Header-Werte werden aus Quellmarkierungen (`secretref-env:ENV_VAR_NAME` für env-Referenzen, `secretref-managed` für Datei-/Exec-Referenzen) aktualisiert.
- Leere oder fehlende Agent-Werte für `apiKey`/`baseUrl` fallen auf `models.providers` in der Konfiguration zurück.
- Übereinstimmende Modellwerte für `contextWindow`/`maxTokens` verwenden den höheren Wert aus expliziter Konfiguration und impliziten Katalogwerten.
- Übereinstimmende Modellwerte für `contextTokens` behalten eine explizite Laufzeitobergrenze bei, wenn vorhanden; verwenden Sie dies, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern.
- Übereinstimmende Modellwerte für `contextTokens` bewahren eine explizite Laufzeitbegrenzung, wenn vorhanden; verwenden Sie sie, um den effektiven Kontext zu begrenzen, ohne native Modellmetadaten zu ändern.
- Verwenden Sie `models.mode: "replace"`, wenn die Konfiguration `models.json` vollständig neu schreiben soll.
- Marker-Persistenz ist quellautoritativ: Marker werden aus dem aktiven Quell-Konfigurationssnapshot (vor der Auflösung) geschrieben, nicht aus aufgelösten Laufzeit-Secret-Werten.
- Markierungspersistenz ist quellenautoritativ: Markierungen werden aus dem aktiven Quellkonfigurations-Snapshot (vor der Auflösung) geschrieben, nicht aus aufgelösten Laufzeit-Geheimniswerten.
</Accordion>
</AccordionGroup>
@ -446,62 +446,62 @@ OpenClaw verwendet den integrierten Modellkatalog. Fügen Sie benutzerdefinierte
<AccordionGroup>
<Accordion title="Katalog auf oberster Ebene">
- `models.mode`: Verhalten des Provider-Katalogs (`merge` oder `replace`).
- `models.providers`: Map benutzerdefinierter Provider, nach Provider-ID verschlüsselt.
- `models.providers`: Zuordnung benutzerdefinierter Provider, nach Provider-ID indiziert.
- Sichere Änderungen: Verwenden Sie `openclaw config set models.providers.<id> '<json>' --strict-json --merge` oder `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` für additive Aktualisierungen. `config set` verweigert destruktive Ersetzungen, sofern Sie nicht `--replace` übergeben.
</Accordion>
<Accordion title="Provider-Verbindung und Authentifizierung">
- `models.providers.*.api`: Request-Adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` usw.). Für selbst gehostete `/v1/chat/completions`-Backends wie MLX, vLLM, SGLang und die meisten OpenAI-kompatiblen lokalen Server verwenden Sie `openai-completions`. Ein benutzerdefinierter Provider mit `baseUrl`, aber ohne `api`, verwendet standardmäßig `openai-completions`; setzen Sie `openai-responses` nur, wenn das Backend `/v1/responses` unterstützt.
- `models.providers.*.apiKey`: Provider-Anmeldedaten (SecretRef-/Umgebungsersetzung bevorzugen).
- `models.providers.*.api`: Anfrageadapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` usw.). Für selbst gehostete `/v1/chat/completions`-Backends wie MLX, vLLM, SGLang und die meisten OpenAI-kompatiblen lokalen Server verwenden Sie `openai-completions`. Ein benutzerdefinierter Provider mit `baseUrl`, aber ohne `api`, verwendet standardmäßig `openai-completions`; setzen Sie `openai-responses` nur, wenn das Backend `/v1/responses` unterstützt.
- `models.providers.*.apiKey`: Provider-Anmeldeinformation (bevorzugt SecretRef/env-Ersetzung).
- `models.providers.*.auth`: Authentifizierungsstrategie (`api-key`, `token`, `oauth`, `aws-sdk`).
- `models.providers.*.contextWindow`: standardmäßiges natives Kontextfenster für Modelle unter diesem Provider, wenn der Modelleintrag `contextWindow` nicht setzt.
- `models.providers.*.contextTokens`: standardmäßige effektive Laufzeit-Kontextobergrenze für Modelle unter diesem Provider, wenn der Modelleintrag `contextTokens` nicht setzt.
- `models.providers.*.maxTokens`: standardmäßige Ausgabetoken-Obergrenze für Modelle unter diesem Provider, wenn der Modelleintrag `maxTokens` nicht setzt.
- `models.providers.*.timeoutSeconds`: optionaler HTTP-Request-Timeout pro Provider-Modell in Sekunden, einschließlich Verbindungsaufbau, Headern, Body und Abbruchbehandlung für den gesamten Request.
- `models.providers.*.injectNumCtxForOpenAICompat`: für Ollama + `openai-completions` `options.num_ctx` in Requests injizieren (Standard: `true`).
- `models.providers.*.authHeader`: Transport der Anmeldedaten im `Authorization`-Header erzwingen, wenn erforderlich.
- `models.providers.*.contextWindow`: Standardmäßiges natives Kontextfenster für Modelle unter diesem Provider, wenn der Modelleintag `contextWindow` nicht festlegt.
- `models.providers.*.contextTokens`: Standardmäßige effektive Laufzeit-Kontextbegrenzung für Modelle unter diesem Provider, wenn der Modelleintag `contextTokens` nicht festlegt.
- `models.providers.*.maxTokens`: Standardmäßige Ausgabe-Token-Begrenzung für Modelle unter diesem Provider, wenn der Modelleintag `maxTokens` nicht festlegt.
- `models.providers.*.timeoutSeconds`: Optionaler modellbezogener HTTP-Anfrage-Timeout pro Provider in Sekunden, einschließlich Verbindung, Headern, Body und Behandlung eines Abbruchs der gesamten Anfrage.
- `models.providers.*.injectNumCtxForOpenAICompat`: Für Ollama + `openai-completions` `options.num_ctx` in Anfragen einfügen (Standard: `true`).
- `models.providers.*.authHeader`: Erzwingt bei Bedarf die Übertragung der Anmeldeinformation im `Authorization`-Header.
- `models.providers.*.baseUrl`: Basis-URL der Upstream-API.
- `models.providers.*.headers`: zusätzliche statische Header für Proxy-/Mandanten-Routing.
- `models.providers.*.headers`: Zusätzliche statische Header für Proxy-/Tenant-Routing.
</Accordion>
<Accordion title="Überschreibungen für Request-Transport">
`models.providers.*.request`: Transportüberschreibungen für HTTP-Requests an Modell-Provider.
<Accordion title="Überschreibungen für den Anfrage-Transport">
`models.providers.*.request`: Transportüberschreibungen für HTTP-Anfragen an Modell-Provider.
- `request.headers`: zusätzliche Header (mit Provider-Standards zusammengeführt). Werte akzeptieren SecretRef.
- `request.headers`: Zusätzliche Header (mit Provider-Standards zusammengeführt). Werte akzeptieren SecretRef.
- `request.auth`: Überschreibung der Authentifizierungsstrategie. Modi: `"provider-default"` (integrierte Authentifizierung des Providers verwenden), `"authorization-bearer"` (mit `token`), `"header"` (mit `headerName`, `value`, optional `prefix`).
- `request.proxy`: HTTP-Proxy-Überschreibung. Modi: `"env-proxy"` (`HTTP_PROXY`-/`HTTPS_PROXY`-Umgebungsvariablen verwenden), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren ein optionales `tls`-Unterobjekt.
- `request.proxy`: HTTP-Proxy-Überschreibung. Modi: `"env-proxy"` (`HTTP_PROXY`/`HTTPS_PROXY`-env-Variablen verwenden), `"explicit-proxy"` (mit `url`). Beide Modi akzeptieren ein optionales `tls`-Unterobjekt.
- `request.tls`: TLS-Überschreibung für direkte Verbindungen. Felder: `ca`, `cert`, `key`, `passphrase` (alle akzeptieren SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: Wenn `true`, HTTPS zu `baseUrl` zulassen, wenn DNS auf private, CGNAT- oder ähnliche Bereiche auflöst, über den HTTP-Fetch-Schutz des Providers (Operator-Opt-in für vertrauenswürdige selbst gehostete OpenAI-kompatible Endpunkte). local loopback-Modell-Provider-Stream-URLs wie `localhost`, `127.0.0.1` und `[::1]` sind automatisch zulässig, sofern dies nicht explizit auf `false` gesetzt ist; LAN-, Tailnet- und private DNS-Hosts erfordern weiterhin ein Opt-in. WebSocket verwendet dieselbe `request` für Header/TLS, aber nicht dieses Fetch-SSRF-Gate. Standard `false`.
- `request.allowPrivateNetwork`: Wenn `true`, HTTPS zu `baseUrl` erlauben, wenn DNS auf private, CGNAT- oder ähnliche Bereiche auflöst, über den HTTP-Fetch-Schutz des Providers (operatorseitige Zustimmung für vertrauenswürdige selbst gehostete OpenAI-kompatible Endpunkte). Loopback-Stream-URLs für Modell-Provider wie `localhost`, `127.0.0.1` und `[::1]` sind automatisch erlaubt, sofern dies nicht explizit auf `false` gesetzt ist; LAN-, Tailnet- und private DNS-Hosts erfordern weiterhin eine Zustimmung. WebSocket verwendet dieselbe `request` für Header/TLS, aber nicht dieses Fetch-SSRF-Gate. Standard `false`.
</Accordion>
<Accordion title="Modellkatalogeinträge">
- `models.providers.*.models`: explizite Modellkatalogeinträge des Providers.
- `models.providers.*.models.*.input`: Eingabemodalitäten des Modells. Verwenden Sie `["text"]` für reine Textmodelle und `["text", "image"]` für native Bild-/Vision-Modelle. Bildanhänge werden nur in Agent-Turns injiziert, wenn das ausgewählte Modell als bildfähig markiert ist.
- `models.providers.*.models.*.contextWindow`: native Kontextfenster-Metadaten des Modells. Dies überschreibt `contextWindow` auf Provider-Ebene für dieses Modell.
- `models.providers.*.models.*.contextTokens`: optionale Laufzeit-Kontextobergrenze. Dies überschreibt `contextTokens` auf Provider-Ebene; verwenden Sie es, wenn Sie ein kleineres effektives Kontextbudget als das native `contextWindow` des Modells wünschen; `openclaw models list` zeigt beide Werte an, wenn sie sich unterscheiden.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: optionaler Kompatibilitätshinweis. Für `api: "openai-completions"` mit einer nicht leeren, nicht nativen `baseUrl` (Host nicht `api.openai.com`) erzwingt OpenClaw dies zur Laufzeit auf `false`. Leere/ausgelassene `baseUrl` behält das Standardverhalten von OpenAI bei.
- `models.providers.*.models.*.compat.requiresStringContent`: optionaler Kompatibilitätshinweis für reine String-OpenAI-kompatible Chat-Endpunkte. Wenn `true`, reduziert OpenClaw reine Text-`messages[].content`-Arrays vor dem Senden des Requests auf einfache Strings.
- `models.providers.*.models`: Explizite Modellkatalogeinträge des Providers.
- `models.providers.*.models.*.input`: Eingabemodalitäten des Modells. Verwenden Sie `["text"]` für reine Textmodelle und `["text", "image"]` für native Bild-/Vision-Modelle. Bildanhänge werden nur in Agent-Turns eingefügt, wenn das ausgewählte Modell als bildfähig markiert ist.
- `models.providers.*.models.*.contextWindow`: Metadaten des nativen Modell-Kontextfensters. Dies überschreibt `contextWindow` auf Provider-Ebene für dieses Modell.
- `models.providers.*.models.*.contextTokens`: Optionale Laufzeit-Kontextbegrenzung. Dies überschreibt `contextTokens` auf Provider-Ebene; verwenden Sie es, wenn Sie ein kleineres effektives Kontextbudget als das native `contextWindow` des Modells möchten; `openclaw models list` zeigt beide Werte an, wenn sie sich unterscheiden.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: Optionaler Kompatibilitätshinweis. Für `api: "openai-completions"` mit einer nicht leeren, nicht nativen `baseUrl` (Host nicht `api.openai.com`) erzwingt OpenClaw dies zur Laufzeit auf `false`. Eine leere/ausgelassene `baseUrl` behält das OpenAI-Standardverhalten bei.
- `models.providers.*.models.*.compat.requiresStringContent`: Optionaler Kompatibilitätshinweis für OpenAI-kompatible Chat-Endpunkte, die nur Strings akzeptieren. Wenn `true`, wandelt OpenClaw reine Text-Arrays in `messages[].content` vor dem Senden der Anfrage in einfache Strings um.
</Accordion>
<Accordion title="Amazon-Bedrock-Erkennung">
- `plugins.entries.amazon-bedrock.config.discovery`: Root der Einstellungen für die automatische Bedrock-Erkennung.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: implizite Erkennung ein-/ausschalten.
<Accordion title="Amazon Bedrock-Erkennung">
- `plugins.entries.amazon-bedrock.config.discovery`: Stamm der Einstellungen für die automatische Bedrock-Erkennung.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: Implizite Erkennung ein-/ausschalten.
- `plugins.entries.amazon-bedrock.config.discovery.region`: AWS-Region für die Erkennung.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: optionaler Provider-ID-Filter für gezielte Erkennung.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: Optionaler Provider-ID-Filter für gezielte Erkennung.
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: Abfrageintervall für die Aktualisierung der Erkennung.
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: Fallback-Kontextfenster für erkannte Modelle.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: Fallback für maximale Ausgabetoken für erkannte Modelle.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: Fallback-Maximalzahl an Ausgabe-Tokens für erkannte Modelle.
</Accordion>
</AccordionGroup>
Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe für gängige Vision-Modell-IDs wie GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V und GLM-4V ab und überspringt die zusätzliche Frage für bekannte reine Textfamilien. Unbekannte Modell-IDs fragen weiterhin nach Bildunterstützung. Nicht interaktives Onboarding verwendet dieselbe Ableitung; übergeben Sie `--custom-image-input`, um bildfähige Metadaten zu erzwingen, oder `--custom-text-input`, um reine Textmetadaten zu erzwingen.
Das interaktive Onboarding benutzerdefinierter Provider leitet die Bildeingabe für gängige Vision-Modell-IDs wie GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V und GLM-4V ab und überspringt die zusätzliche Frage für bekannte reine Textfamilien. Unbekannte Modell-IDs fragen weiterhin nach Bildunterstützung. Nicht interaktives Onboarding verwendet dieselbe Ableitung; übergeben Sie `--custom-image-input`, um bildfähige Metadaten zu erzwingen, oder `--custom-text-input`, um reine Textmetadaten zu erzwingen.
### Provider-Beispiele
<AccordionGroup>
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
Das gebündelte `cerebras`-Provider-Plugin kann dies über `openclaw onboard --auth-choice cerebras-api-key` konfigurieren. Verwenden Sie explizite Provider-Konfiguration nur, wenn Sie Standardwerte überschreiben.
Das gebündelte `cerebras`-Provider-Plugin kann dies über `openclaw onboard --auth-choice cerebras-api-key` konfigurieren. Verwenden Sie eine explizite Provider-Konfiguration nur, wenn Sie Standardwerte überschreiben.
```json5
{
@ -538,7 +538,7 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
Verwenden Sie `cerebras/zai-glm-4.7` für Cerebras; `zai/glm-4.7` für Z.AI direkt.
</Accordion>
<Accordion title="Kimi-Coding">
<Accordion title="Kimi Coding">
```json5
{
env: { KIMI_API_KEY: "sk-..." },
@ -551,13 +551,13 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
}
```
Anthropic-kompatibler, integrierter Provider. Kürzel: `openclaw onboard --auth-choice kimi-code-api-key`.
Anthropic-kompatibler, integrierter Provider. Kurzform: `openclaw onboard --auth-choice kimi-code-api-key`.
</Accordion>
<Accordion title="Lokale Modelle (LM Studio)">
Siehe [Lokale Modelle](/de/gateway/local-models). Kurzfassung: Führen Sie ein großes lokales Modell über die LM Studio Responses API auf leistungsfähiger Hardware aus; halten Sie gehostete Modelle als Fallback zusammengeführt.
<Accordion title="Local models (LM Studio)">
Siehe [Lokale Modelle](/de/gateway/local-models). Kurzfassung: Führen Sie ein großes lokales Modell über die LM Studio Responses API auf leistungsfähiger Hardware aus; lassen Sie gehostete Modelle als Fallback zusammengeführt.
</Accordion>
<Accordion title="MiniMax M2.7 (direkt)">
<Accordion title="MiniMax M2.7 (direct)">
```json5
{
agents: {
@ -592,7 +592,7 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
}
```
Setzen Sie `MINIMAX_API_KEY`. Kürzel: `openclaw onboard --auth-choice minimax-global-api` oder `openclaw onboard --auth-choice minimax-cn-api`. Der Modellkatalog verwendet standardmäßig nur M2.7. Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw MiniMax Thinking standardmäßig, sofern Sie `thinking` nicht ausdrücklich selbst setzen. `/fast on` oder `params.fastMode: true` schreibt `MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um.
Setzen Sie `MINIMAX_API_KEY`. Kurzformen: `openclaw onboard --auth-choice minimax-global-api` oder `openclaw onboard --auth-choice minimax-cn-api`. Der Modellkatalog ist standardmäßig nur auf M2.7 eingestellt. Auf dem Anthropic-kompatiblen Streaming-Pfad deaktiviert OpenClaw das Thinking von MiniMax standardmäßig, sofern Sie `thinking` nicht selbst explizit setzen. `/fast on` oder `params.fastMode: true` schreibt `MiniMax-M2.7` in `MiniMax-M2.7-highspeed` um.
</Accordion>
<Accordion title="Moonshot AI (Kimi)">
@ -631,7 +631,7 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
Für den China-Endpunkt: `baseUrl: "https://api.moonshot.cn/v1"` oder `openclaw onboard --auth-choice moonshot-api-key-cn`.
Native Moonshot-Endpunkte geben Streaming-Usage-Kompatibilität auf dem gemeinsamen `openai-completions`-Transport an, und OpenClaw richtet sich dabei nach den Endpunktfähigkeiten statt nur nach der integrierten Provider-ID.
Native Moonshot-Endpunkte geben Streaming-Usage-Kompatibilität auf dem gemeinsamen `openai-completions`-Transport an, und OpenClaw macht dies an den Endpunktfähigkeiten fest, nicht allein an der integrierten Provider-ID.
</Accordion>
<Accordion title="OpenCode">
@ -646,10 +646,10 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
}
```
Setzen Sie `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`). Verwenden Sie `opencode/...`-Referenzen für den Zen-Katalog oder `opencode-go/...`-Referenzen für den Go-Katalog. Kürzel: `openclaw onboard --auth-choice opencode-zen` oder `openclaw onboard --auth-choice opencode-go`.
Setzen Sie `OPENCODE_API_KEY` (oder `OPENCODE_ZEN_API_KEY`). Verwenden Sie `opencode/...`-Referenzen für den Zen-Katalog oder `opencode-go/...`-Referenzen für den Go-Katalog. Kurzform: `openclaw onboard --auth-choice opencode-zen` oder `openclaw onboard --auth-choice opencode-go`.
</Accordion>
<Accordion title="Synthetic (Anthropic-kompatibel)">
<Accordion title="Synthetic (Anthropic-compatible)">
```json5
{
env: { SYNTHETIC_API_KEY: "sk-..." },
@ -683,7 +683,7 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
}
```
Die Basis-URL sollte `/v1` auslassen (der Anthropic-Client hängt es an). Kürzel: `openclaw onboard --auth-choice synthetic-api-key`.
Die Basis-URL sollte `/v1` auslassen (der Anthropic-Client hängt es an). Kurzform: `openclaw onboard --auth-choice synthetic-api-key`.
</Accordion>
<Accordion title="Z.AI (GLM-4.7)">
@ -698,11 +698,11 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
}
```
Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Aliasse akzeptiert. Kürzel: `openclaw onboard --auth-choice zai-api-key`.
Setzen Sie `ZAI_API_KEY`. `z.ai/*` und `z-ai/*` werden als Aliasse akzeptiert. Kurzform: `openclaw onboard --auth-choice zai-api-key`.
- Allgemeiner Endpunkt: `https://api.z.ai/api/paas/v4`
- Coding-Endpunkt (Standard): `https://api.z.ai/api/coding/paas/v4`
- Definieren Sie für den allgemeinen Endpunkt einen benutzerdefinierten Provider mit der Basis-URL-Überschreibung.
- Definieren Sie für den allgemeinen Endpunkt einen benutzerdefinierten Provider mit der Überschreibung der Basis-URL.
</Accordion>
</AccordionGroup>
@ -713,5 +713,5 @@ Das interaktive Onboarding für benutzerdefinierte Provider leitet Bildeingabe f
- [Konfiguration — Agents](/de/gateway/config-agents)
- [Konfiguration — Kanäle](/de/gateway/config-channels)
- [Konfigurationsreferenz](/de/gateway/configuration-reference) — andere Schlüssel auf oberster Ebene
- [Werkzeuge und Plugins](/de/tools)
- [Konfigurationsreferenz](/de/gateway/configuration-reference) — weitere Schlüssel auf oberster Ebene
- [Tools und Plugins](/de/tools)

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

@ -1,74 +1,63 @@
---
read_when:
- Sie benötigen exakte Konfigurationssemantik auf Feldebene oder Standardwerte
- Sie benötigen genaue Konfigurationssemantik auf Feldebene oder Standardwerte
- Sie validieren Kanal-, Modell-, Gateway- oder Tool-Konfigurationsblöcke
summary: Gateway-Konfigurationsreferenz für zentrale OpenClaw-Schlüssel, Standardwerte und Links zu dedizierten Subsystemreferenzen
summary: Gateway-Konfigurationsreferenz für zentrale OpenClaw-Schlüssel, Standardwerte und Verweise auf dedizierte Subsystemreferenzen
title: Konfigurationsreferenz
x-i18n:
generated_at: "2026-05-03T21:31:56Z"
generated_at: "2026-05-05T01:45:55Z"
model: gpt-5.5
provider: openai
source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9
source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684
source_path: gateway/configuration-reference.md
workflow: 16
---
Kernkonfigurationsreferenz für `~/.openclaw/openclaw.json`. Eine aufgabenorientierte Übersicht finden Sie unter [Konfiguration](/de/gateway/configuration).
Kern-Konfigurationsreferenz für `~/.openclaw/openclaw.json`. Eine aufgabenorientierte Übersicht finden Sie unter [Konfiguration](/de/gateway/configuration).
Behandelt die wichtigsten OpenClaw-Konfigurationsoberflächen und verlinkt auf weiterführende Referenzen, wenn ein Subsystem eine eigene detailliertere Referenz hat. Kanal- und Plugin-eigene Befehlskataloge sowie detaillierte Memory-/QMD-Einstellungen befinden sich auf eigenen Seiten statt auf dieser.
Deckt die wichtigsten OpenClaw-Konfigurationsoberflächen ab und verweist auf eigene, ausführlichere Referenzen, wenn ein Subsystem eine solche besitzt. Channel- und Plugin-eigene Befehlsverzeichnisse sowie tiefe Speicher-/QMD-Schalter befinden sich auf eigenen Seiten und nicht auf dieser.
Code-Wahrheit:
Maßgeblicher Code:
- `openclaw config schema` gibt das Live-JSON-Schema aus, das für Validierung und Control UI verwendet wird; gebündelte/Plugin-/Kanal-Metadaten werden zusammengeführt, wenn verfügbar
- `config.schema.lookup` gibt einen pfadbezogenen Schemaknoten für Drill-down-Tools zurück
- `openclaw config schema` gibt das Live-JSON-Schema aus, das für Validierung und Control UI verwendet wird, mit zusammengeführten gebündelten/Plugin-/Channel-Metadaten, sofern verfügbar
- `config.schema.lookup` gibt einen pfadbezogenen Schemaknoten für Drill-down-Werkzeuge zurück
- `pnpm config:docs:check` / `pnpm config:docs:gen` validieren den Baseline-Hash der Konfigurationsdokumentation gegen die aktuelle Schemaoberfläche
Agent-Suchpfad: Verwenden Sie die `gateway`-Tool-Aktion `config.schema.lookup` für
exakte Feld-Dokumentation und Einschränkungen vor Bearbeitungen. Nutzen Sie
[Konfiguration](/de/gateway/configuration) für aufgabenorientierte Anleitung und diese Seite
für die breitere Feldübersicht, Standardwerte und Links zu Subsystem-Referenzen.
Agent-Lookup-Pfad: Verwenden Sie die `gateway`-Tool-Aktion `config.schema.lookup` für exakte feldbezogene Dokumentation und Einschränkungen vor Änderungen. Verwenden Sie [Konfiguration](/de/gateway/configuration) für aufgabenorientierte Anleitung und diese Seite für die breitere Feldübersicht, Standardwerte und Links zu Subsystem-Referenzen.
Eigene Detailreferenzen:
Dedizierte Detailreferenzen:
- [Memory-Konfigurationsreferenz](/de/reference/memory-config) für `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` und Dreaming-Konfiguration unter `plugins.entries.memory-core.config.dreaming`
- [Slash-Befehle](/de/tools/slash-commands) für den aktuellen integrierten und gebündelten Befehlskatalog
- Zuständige Kanal-/Plugin-Seiten für kanalspezifische Befehlsoberflächen
- [Speicherkonfigurationsreferenz](/de/reference/memory-config) für `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` und Dreaming-Konfiguration unter `plugins.entries.memory-core.config.dreaming`
- [Slash-Befehle](/de/tools/slash-commands) für den aktuellen integrierten und gebündelten Befehls-Katalog
- Zuständige Channel-/Plugin-Seiten für channel-spezifische Befehlsoberflächen
Das Konfigurationsformat ist **JSON5** (Kommentare und nachgestellte Kommas sind erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie weggelassen werden.
Das Konfigurationsformat ist **JSON5** (Kommentare und nachgestellte Kommas sind erlaubt). Alle Felder sind optional — OpenClaw verwendet sichere Standardwerte, wenn sie ausgelassen werden.
---
## Kanäle
## Channels
Kanalspezifische Konfigurationsschlüssel wurden auf eine eigene Seite verschoben — siehe
[Konfiguration — Kanäle](/de/gateway/config-channels) für `channels.*`,
einschließlich Slack, Discord, Telegram, WhatsApp, Matrix, iMessage und anderer
gebündelter Kanäle (Authentifizierung, Zugriffskontrolle, Mehrfachkonten, Mention-Gating).
Konfigurationsschlüssel pro Channel wurden auf eine eigene Seite verschoben — siehe [Konfiguration — Channels](/de/gateway/config-channels) für `channels.*`, einschließlich Slack, Discord, Telegram, WhatsApp, Matrix, iMessage und anderer gebündelter Channels (Authentifizierung, Zugriffskontrolle, Mehrfachkonten, Mention-Gating).
## Agent-Standardwerte, Multi-Agent, Sitzungen und Nachrichten
## Agent-Standardeinstellungen, Multi-Agent, Sitzungen und Nachrichten
Auf eine eigene Seite verschoben — siehe
[Konfiguration — Agenten](/de/gateway/config-agents) für:
Wurde auf eine eigene Seite verschoben — siehe [Konfiguration — Agents](/de/gateway/config-agents) für:
- `agents.defaults.*` (Arbeitsbereich, Modell, Thinking, Heartbeat, Memory, Medien, Skills, Sandbox)
- `multiAgent.*` (Multi-Agent-Routing und Bindings)
- `agents.defaults.*` (Arbeitsbereich, Modell, Denken, Heartbeat, Speicher, Medien, Skills, Sandbox)
- `multiAgent.*` (Multi-Agent-Routing und Bindungen)
- `session.*` (Sitzungslebenszyklus, Compaction, Bereinigung)
- `messages.*` (Nachrichtenzustellung, TTS, Markdown-Rendering)
- `talk.*` (Talk-Modus)
- `talk.speechLocale`: optionale BCP-47-Locale-ID für die Talk-Spracherkennung unter iOS/macOS
- `talk.silenceTimeoutMs`: wenn nicht gesetzt, behält Talk das Standard-Pausenfenster der Plattform vor dem Senden des Transkripts bei (`700 ms on macOS and Android, 900 ms on iOS`)
- `talk.speechLocale`: optionale BCP-47-Locale-ID für Talk-Spracherkennung unter iOS/macOS
- `talk.silenceTimeoutMs`: wenn nicht gesetzt, behält Talk das plattformseitige Standard-Pausenfenster vor dem Senden des Transkripts bei (`700 ms on macOS and Android, 900 ms on iOS`)
## Tools und benutzerdefinierte Provider
## Werkzeuge und benutzerdefinierte Provider
Tool-Richtlinien, experimentelle Umschalter, Provider-gestützte Tool-Konfiguration und Einrichtung
benutzerdefinierter Provider / Basis-URLs wurden auf eine eigene Seite verschoben — siehe
[Konfiguration — Tools und benutzerdefinierte Provider](/de/gateway/config-tools).
Tool-Richtlinie, experimentelle Schalter, providergestützte Tool-Konfiguration und Einrichtung benutzerdefinierter Provider bzw. Basis-URLs wurden auf eine eigene Seite verschoben — siehe [Konfiguration — Werkzeuge und benutzerdefinierte Provider](/de/gateway/config-tools).
## Modelle
Provider-Definitionen, Modell-Allowlists und die Einrichtung benutzerdefinierter Provider befinden sich in
[Konfiguration — Tools und benutzerdefinierte Provider](/de/gateway/config-tools#custom-providers-and-base-urls).
Der Root-Schlüssel `models` verwaltet außerdem das globale Verhalten des Modellkatalogs.
Provider-Definitionen, Modell-Allowlists und Einrichtung benutzerdefinierter Provider befinden sich unter [Konfiguration — Werkzeuge und benutzerdefinierte Provider](/de/gateway/config-tools#custom-providers-and-base-urls). Der Root `models` verwaltet außerdem globales Modellkatalog-Verhalten.
```json5
{
@ -79,19 +68,13 @@ Der Root-Schlüssel `models` verwaltet außerdem das globale Verhalten des Model
}
```
- `models.mode`: Verhalten des Provider-Katalogs (`merge` oder `replace`).
- `models.providers`: Zuordnung benutzerdefinierter Provider nach Provider-ID.
- `models.pricing.enabled`: steuert den Preis-Bootstrap im Hintergrund, der
startet, nachdem Sidecars und Kanäle den Bereitschaftspfad des Gateway erreicht haben. Wenn `false`,
überspringt das Gateway Preis-Katalogabrufe von OpenRouter und LiteLLM; konfigurierte
`models.providers.*.models[].cost`-Werte funktionieren weiterhin für lokale Kostenschätzungen.
- `models.mode`: Provider-Katalogverhalten (`merge` oder `replace`).
- `models.providers`: Map benutzerdefinierter Provider, nach Provider-ID geschlüsselt.
- `models.pricing.enabled`: steuert den Hintergrund-Bootstrap für Preise, der startet, nachdem Sidecars und Channels den Gateway-Ready-Pfad erreicht haben. Wenn `false`, überspringt der Gateway OpenRouter- und LiteLLM-Preiskatalog-Abrufe; konfigurierte `models.providers.*.models[].cost`-Werte funktionieren weiterhin für lokale Kostenschätzungen.
## MCP
Von OpenClaw verwaltete MCP-Serverdefinitionen liegen unter `mcp.servers` und werden
von eingebettetem Pi und anderen Runtime-Adaptern verwendet. Die Befehle `openclaw mcp list`,
`show`, `set` und `unset` verwalten diesen Block, ohne während Konfigurationsänderungen eine Verbindung zum
Zielserver herzustellen.
Von OpenClaw verwaltete MCP-Serverdefinitionen befinden sich unter `mcp.servers` und werden von eingebettetem Pi und anderen Laufzeitadaptern verwendet. Die Befehle `openclaw mcp list`, `show`, `set` und `unset` verwalten diesen Block, ohne während der Konfigurationsänderungen eine Verbindung zum Zielserver herzustellen.
```json5
{
@ -115,20 +98,11 @@ Zielserver herzustellen.
}
```
- `mcp.servers`: benannte Stdio- oder Remote-MCP-Serverdefinitionen für Runtimes, die
konfigurierte MCP-Tools bereitstellen.
Remote-Einträge verwenden `transport: "streamable-http"` oder `transport: "sse"`;
`type: "http"` ist ein CLI-nativer Alias, den `openclaw mcp set` und
`openclaw doctor --fix` in das kanonische Feld `transport` normalisieren.
- `mcp.sessionIdleTtlMs`: Leerlauf-TTL für sitzungsbezogene gebündelte MCP-Runtimes.
Einmalige eingebettete Läufe fordern eine Bereinigung am Laufende an; diese TTL ist der Rückhalt für
langlebige Sitzungen und zukünftige Aufrufer.
- Änderungen unter `mcp.*` werden durch Verwerfen zwischengespeicherter Sitzungs-MCP-Runtimes im laufenden Betrieb angewendet.
Die nächste Tool-Erkennung/-Verwendung erstellt sie aus der neuen Konfiguration neu, sodass entfernte
`mcp.servers`-Einträge sofort entfernt werden, statt auf die Leerlauf-TTL zu warten.
- `mcp.servers`: benannte stdio- oder Remote-MCP-Serverdefinitionen für Laufzeiten, die konfigurierte MCP-Tools verfügbar machen. Remote-Einträge verwenden `transport: "streamable-http"` oder `transport: "sse"`; `type: "http"` ist ein CLI-nativer Alias, den `openclaw mcp set` und `openclaw doctor --fix` in das kanonische `transport`-Feld normalisieren.
- `mcp.sessionIdleTtlMs`: Leerlauf-TTL für sitzungsbezogene gebündelte MCP-Laufzeiten. Einmalige eingebettete Läufe fordern eine Bereinigung am Laufende an; diese TTL ist die Absicherung für langlebige Sitzungen und zukünftige Aufrufer.
- Änderungen unter `mcp.*` werden per Hot-Apply übernommen, indem zwischengespeicherte Sitzungs-MCP-Laufzeiten verworfen werden. Die nächste Tool-Erkennung/-Nutzung erstellt sie aus der neuen Konfiguration neu, sodass entfernte `mcp.servers`-Einträge sofort entfernt werden, statt auf die Leerlauf-TTL zu warten.
Siehe [MCP](/de/cli/mcp#openclaw-as-an-mcp-client-registry) und
[CLI-Backends](/de/gateway/cli-backends#bundle-mcp-overlays) zum Runtime-Verhalten.
Siehe [MCP](/de/cli/mcp#openclaw-as-an-mcp-client-registry) und [CLI-Backends](/de/gateway/cli-backends#bundle-mcp-overlays) für Laufzeitverhalten.
## Skills
@ -157,11 +131,9 @@ Siehe [MCP](/de/cli/mcp#openclaw-as-an-mcp-client-registry) und
- `allowBundled`: optionale Allowlist nur für gebündelte Skills (verwaltete/Arbeitsbereich-Skills bleiben unberührt).
- `load.extraDirs`: zusätzliche gemeinsame Skill-Roots (niedrigste Priorität).
- `install.preferBrew`: wenn true, werden Homebrew-Installer bevorzugt, wenn `brew` verfügbar ist,
bevor auf andere Installer-Arten zurückgegriffen wird.
- `install.nodeManager`: bevorzugter Node-Installer für `metadata.openclaw.install`-Spezifikationen
(`npm` | `pnpm` | `yarn` | `bun`).
- `entries.<skillKey>.enabled: false` deaktiviert eine Skill, auch wenn sie gebündelt/installiert ist.
- `install.preferBrew`: wenn true, Homebrew-Installer bevorzugen, wenn `brew` verfügbar ist, bevor auf andere Installerarten zurückgefallen wird.
- `install.nodeManager`: Node-Installer-Präferenz für `metadata.openclaw.install`-Spezifikationen (`npm` | `pnpm` | `yarn` | `bun`).
- `entries.<skillKey>.enabled: false` deaktiviert einen Skill, selbst wenn er gebündelt/installiert ist.
- `entries.<skillKey>.apiKey`: Komfortfeld für Skills, die eine primäre Umgebungsvariable deklarieren (Klartext-String oder SecretRef-Objekt).
---
@ -173,6 +145,7 @@ Siehe [MCP](/de/cli/mcp#openclaw-as-an-mcp-client-registry) und
plugins: {
enabled: true,
allow: ["voice-call"],
bundledDiscovery: "allowlist",
deny: [],
load: {
paths: ["~/Projects/oss/voice-call-plugin"],
@ -191,40 +164,41 @@ Siehe [MCP](/de/cli/mcp#openclaw-as-an-mcp-client-registry) und
```
- Geladen aus `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions` sowie `plugins.load.paths`.
- Discovery akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles im Standardlayout.
- Discovery akzeptiert native OpenClaw-Plugins sowie kompatible Codex-Bundles und Claude-Bundles, einschließlich manifestloser Claude-Bundles mit Standardlayout.
- **Konfigurationsänderungen erfordern einen Gateway-Neustart.**
- `allow`: optionale Allowlist (nur aufgeführte Plugins werden geladen). `deny` hat Vorrang.
- `plugins.entries.<id>.apiKey`: Komfortfeld für API-Schlüssel auf Plugin-Ebene (wenn vom Plugin unterstützt).
- `plugins.entries.<id>.env`: Plugin-bezogene Zuordnung von Umgebungsvariablen.
- `plugins.entries.<id>.hooks.allowPromptInjection`: wenn `false`, blockiert der Core `before_prompt_build` und ignoriert prompt-verändernde Felder aus dem veralteten `before_agent_start`, während veraltetes `modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte, von Bundles bereitgestellte Hook-Verzeichnisse.
- `bundledDiscovery`: Standard ist `"allowlist"` für neue Konfigurationen, sodass ein nicht leeres `plugins.allow` auch gebündelte Provider-Plugins steuert, einschließlich Web-Search-Laufzeit-Providern. Doctor schreibt `"compat"` für migrierte Legacy-Allowlist-Konfigurationen, um vorhandenes Verhalten gebündelter Provider beizubehalten, bis Sie sich dafür entscheiden.
- `plugins.entries.<id>.apiKey`: API-Key-Komfortfeld auf Plugin-Ebene (wenn vom Plugin unterstützt).
- `plugins.entries.<id>.env`: Plugin-bezogene Umgebungsvariablen-Map.
- `plugins.entries.<id>.hooks.allowPromptInjection`: wenn `false`, blockiert der Core `before_prompt_build` und ignoriert prompt-mutierende Felder aus Legacy-`before_agent_start`, während Legacy-`modelOverride` und `providerOverride` erhalten bleiben. Gilt für native Plugin-Hooks und unterstützte von Bundles bereitgestellte Hook-Verzeichnisse.
- `plugins.entries.<id>.hooks.allowConversationAccess`: wenn `true`, dürfen vertrauenswürdige nicht gebündelte Plugins rohe Gesprächsinhalte aus typisierten Hooks wie `llm_input`, `llm_output`, `before_agent_finalize` und `agent_end` lesen.
- `plugins.entries.<id>.subagent.allowModelOverride`: vertraut diesem Plugin ausdrücklich, pro Lauf `provider`- und `model`-Overrides für Hintergrund-Subagent-Läufe anzufordern.
- `plugins.entries.<id>.subagent.allowModelOverride`: diesem Plugin ausdrücklich vertrauen, pro Lauf `provider`- und `model`-Overrides für Hintergrund-Subagent-Läufe anzufordern.
- `plugins.entries.<id>.subagent.allowedModels`: optionale Allowlist kanonischer `provider/model`-Ziele für vertrauenswürdige Subagent-Overrides. Verwenden Sie `"*"` nur, wenn Sie bewusst jedes Modell erlauben möchten.
- `plugins.entries.<id>.config`: vom Plugin definiertes Konfigurationsobjekt (validiert durch natives OpenClaw-Plugin-Schema, wenn verfügbar).
- Konto-/Runtime-Einstellungen von Kanal-Plugins befinden sich unter `channels.<id>` und sollten durch die `channelConfigs`-Metadaten des Manifests des zuständigen Plugins beschrieben werden, nicht durch eine zentrale OpenClaw-Optionsregistrierung.
- `plugins.entries.<id>.config`: Plugin-definiertes Konfigurationsobjekt (validiert durch natives OpenClaw-Plugin-Schema, sofern verfügbar).
- Channel-Plugin-Konto-/Laufzeiteinstellungen befinden sich unter `channels.<id>` und sollten durch die `channelConfigs`-Metadaten im Manifest des zuständigen Plugins beschrieben werden, nicht durch eine zentrale OpenClaw-Optionsregistrierung.
- `plugins.entries.firecrawl.config.webFetch`: Firecrawl-Web-Fetch-Provider-Einstellungen.
- `apiKey`: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt zurück auf `plugins.entries.firecrawl.config.webSearch.apiKey`, das veraltete `tools.web.fetch.firecrawl.apiKey` oder die Umgebungsvariable `FIRECRAWL_API_KEY`.
- `baseUrl`: Firecrawl-API-Basis-URL (Standard: `https://api.firecrawl.dev`; Self-Hosted-Overrides müssen auf private/interne Endpunkte zeigen).
- `apiKey`: Firecrawl-API-Schlüssel (akzeptiert SecretRef). Fällt auf `plugins.entries.firecrawl.config.webSearch.apiKey`, Legacy-`tools.web.fetch.firecrawl.apiKey` oder die Umgebungsvariable `FIRECRAWL_API_KEY` zurück.
- `baseUrl`: Firecrawl-API-Basis-URL (Standard: `https://api.firecrawl.dev`; selbst gehostete Overrides müssen private/interne Endpunkte anvisieren).
- `onlyMainContent`: nur den Hauptinhalt aus Seiten extrahieren (Standard: `true`).
- `maxAgeMs`: maximales Cache-Alter in Millisekunden (Standard: `172800000` / 2 Tage).
- `timeoutSeconds`: Timeout für Scrape-Anfragen in Sekunden (Standard: `60`).
- `plugins.entries.xai.config.xSearch`: xAI X Search (Grok-Websuche)-Einstellungen.
- `enabled`: aktiviert den X-Search-Provider.
- `model`: für die Suche zu verwendendes Grok-Modell (z. B. `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: Memory-Dreaming-Einstellungen. Siehe [Dreaming](/de/concepts/dreaming) für Phasen und Schwellenwerte.
- `enabled`: zentraler Dreaming-Schalter (Standard `false`).
- `frequency`: Cron-Takt für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`).
- `model`: optionaler Modell-Override für den Dream-Diary-Subagent. Erfordert `plugins.entries.memory-core.subagent.allowModelOverride: true`; kombinieren Sie dies mit `allowedModels`, um Ziele einzuschränken. Fehler wegen nicht verfügbarer Modelle werden einmal mit dem Standardmodell der Sitzung erneut versucht; Vertrauens- oder Allowlist-Fehler fallen nicht stillschweigend zurück.
- `enabled`: den X Search-Provider aktivieren.
- `model`: Grok-Modell, das für die Suche verwendet werden soll (z. B. `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: Speicher-Dreaming-Einstellungen. Siehe [Dreaming](/de/concepts/dreaming) für Phasen und Schwellenwerte.
- `enabled`: Hauptschalter für Dreaming (Standard `false`).
- `frequency`: Cron-Taktung für jeden vollständigen Dreaming-Durchlauf (standardmäßig `"0 3 * * *"`).
- `model`: optionaler Modell-Override für den Dream-Diary-Subagent. Erfordert `plugins.entries.memory-core.subagent.allowModelOverride: true`; mit `allowedModels` kombinieren, um Ziele einzuschränken. Fehler wegen nicht verfügbarer Modelle werden einmal mit dem Sitzungs-Standardmodell wiederholt; Vertrauens- oder Allowlist-Fehler fallen nicht stillschweigend zurück.
- Phasenrichtlinien und Schwellenwerte sind Implementierungsdetails (keine benutzerseitigen Konfigurationsschlüssel).
- Die vollständige Memory-Konfiguration befindet sich in der [Memory-Konfigurationsreferenz](/de/reference/memory-config):
- Die vollständige Speicherkonfiguration befindet sich in der [Speicherkonfigurationsreferenz](/de/reference/memory-config):
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- Aktivierte Claude-Bundle-Plugins können auch eingebettete Pi-Standardwerte aus `settings.json` beitragen; OpenClaw wendet diese als bereinigte Agent-Einstellungen an, nicht als rohe OpenClaw-Konfigurations-Patches.
- `plugins.slots.memory`: wählt die ID des aktiven Memory-Plugins aus oder `"none"`, um Memory-Plugins zu deaktivieren.
- `plugins.slots.contextEngine`: wählt die ID des aktiven Kontext-Engine-Plugins aus; standardmäßig `"legacy"`, sofern Sie keine andere Engine installieren und auswählen.
- Aktivierte Claude-Bundle-Plugins können außerdem eingebettete Pi-Standardwerte aus `settings.json` beitragen; OpenClaw wendet diese als bereinigte Agent-Einstellungen an, nicht als rohe OpenClaw-Konfigurationspatches.
- `plugins.slots.memory`: wählt die aktive Speicher-Plugin-ID oder `"none"`, um Speicher-Plugins zu deaktivieren.
- `plugins.slots.contextEngine`: wählt die aktive Context-Engine-Plugin-ID; Standard ist `"legacy"`, sofern Sie keine andere Engine installieren und auswählen.
Siehe [Plugins](/de/tools/plugin).
@ -232,12 +206,12 @@ Siehe [Plugins](/de/tools/plugin).
## Commitments
`commitments` steuert inferred Follow-up Memory: OpenClaw kann Check-ins aus Gesprächsrunden erkennen und sie über Heartbeat-Läufe zustellen.
`commitments` steuert abgeleiteten Follow-up-Speicher: OpenClaw kann Check-ins aus Gesprächsrunden erkennen und sie über Heartbeat-Läufe zustellen.
- `commitments.enabled`: aktiviert verborgene LLM-Extraktion, Speicherung und Heartbeat-Zustellung für inferred Follow-up Commitments. Standard: `false`.
- `commitments.maxPerDay`: maximale Anzahl inferred Follow-up Commitments, die pro Agent-Sitzung an einem rollierenden Tag zugestellt werden. Standard: `3`.
- `commitments.enabled`: aktiviert verborgene LLM-Extraktion, Speicherung und Heartbeat-Zustellung für abgeleitete Follow-up-Commitments. Standard: `false`.
- `commitments.maxPerDay`: maximale Anzahl abgeleiteter Follow-up-Commitments, die pro Agent-Sitzung in einem rollierenden Tag zugestellt werden. Standard: `3`.
Siehe [Inferred Commitments](/de/concepts/commitments).
Siehe [Abgeleitete Commitments](/de/concepts/commitments).
---
@ -288,51 +262,53 @@ Siehe [Inferred Commitments](/de/concepts/commitments).
```
- `evaluateEnabled: false` deaktiviert `act:evaluate` und `wait --fn`.
- `tabCleanup` gibt nach Leerlaufzeit oder wenn eine Sitzung ihre Obergrenze überschreitet verfolgte Tabs des primären Agenten frei. Setzen Sie `idleMinutes: 0` oder `maxTabsPerSession: 0`, um diese einzelnen Bereinigungsmodi zu deaktivieren.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist deaktiviert, wenn nicht gesetzt; dadurch bleibt die Browser-Navigation standardmäßig strikt.
- `tabCleanup` gibt verfolgte Tabs des primären Agenten nach Leerlaufzeit oder wenn eine
Sitzung ihr Limit überschreitet wieder frei. Setzen Sie `idleMinutes: 0` oder `maxTabsPerSession: 0`, um
diese einzelnen Bereinigungsmodi zu deaktivieren.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` ist deaktiviert, wenn es nicht gesetzt ist, daher bleibt die Browser-Navigation standardmäßig strikt.
- Setzen Sie `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` nur, wenn Sie Browser-Navigation im privaten Netzwerk bewusst vertrauen.
- Im strikten Modus unterliegen Remote-CDP-Profil-Endpunkte (`profiles.*.cdpUrl`) bei Erreichbarkeits- und Discovery-Prüfungen derselben Blockierung privater Netzwerke.
- `ssrfPolicy.allowPrivateNetwork` wird weiterhin als Legacy-Alias unterstützt.
- Im strikten Modus unterliegen Remote-CDP-Profil-Endpunkte (`profiles.*.cdpUrl`) während Erreichbarkeits- und Discovery-Prüfungen derselben Blockierung privater Netzwerke.
- `ssrfPolicy.allowPrivateNetwork` bleibt als Legacy-Alias unterstützt.
- Verwenden Sie im strikten Modus `ssrfPolicy.hostnameAllowlist` und `ssrfPolicy.allowedHostnames` für explizite Ausnahmen.
- Remote-Profile sind nur zum Anhängen vorgesehen (Start/Stopp/Zurücksetzen deaktiviert).
- Remote-Profile sind attach-only (Start/Stopp/Zurücksetzen deaktiviert).
- `profiles.*.cdpUrl` akzeptiert `http://`, `https://`, `ws://` und `wss://`.
Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` ermitteln soll; verwenden Sie WS(S),
Verwenden Sie HTTP(S), wenn OpenClaw `/json/version` erkennen soll; verwenden Sie WS(S),
wenn Ihr Provider Ihnen eine direkte DevTools-WebSocket-URL bereitstellt.
- `remoteCdpTimeoutMs` und `remoteCdpHandshakeTimeoutMs` gelten für die CDP-Erreichbarkeit von Remote- und
`attachOnly`-Profilen sowie für Anfragen zum Öffnen von Tabs. Verwaltete loopback
Profile behalten die lokalen CDP-Standardeinstellungen.
`attachOnly`-Profilen sowie für Anfragen zum Öffnen von Tabs. Verwaltete loopback-Profile
behalten die lokalen CDP-Standardwerte bei.
- Wenn ein extern verwalteter CDP-Dienst über loopback erreichbar ist, setzen Sie für dieses
Profil `attachOnly: true`; andernfalls behandelt OpenClaw den loopback-Port als
lokal verwaltetes Browser-Profil und meldet möglicherweise Fehler zum lokalen Port-Besitz.
- `existing-session`-Profile verwenden Chrome MCP statt CDP und können sich auf
dem ausgewählten Host oder über einen verbundenen Browser-Knoten anhängen.
lokal verwaltetes Browser-Profil und meldet möglicherweise Fehler zur lokalen Port-Eigentümerschaft.
- `existing-session`-Profile verwenden Chrome MCP statt CDP und können auf dem
ausgewählten Host oder über einen verbundenen Browser-Node anhängen.
- `existing-session`-Profile können `userDataDir` setzen, um ein bestimmtes
Chromium-basiertes Browser-Profil wie Brave oder Edge anzusteuern.
- `existing-session`-Profile behalten die aktuellen Chrome-MCP-Routenbeschränkungen bei:
Snapshot-/Ref-gesteuerte Aktionen statt CSS-Selektor-Targeting, Hooks für Uploads einzelner Dateien,
keine Dialog-Timeout-Overrides, kein `wait --load networkidle` und keine
`responsebody`-, PDF-Export-, Download-Abfang- oder Batch-Aktionen.
- `existing-session`-Profile behalten die aktuellen Chrome-MCP-Routenlimits bei:
Snapshot-/ref-gesteuerte Aktionen statt CSS-Selector-Targeting, Upload-Hooks für eine Datei,
keine Overrides für Dialog-Timeouts, kein `wait --load networkidle` und keine
`responsebody`, PDF-Exporte, Download-Interception oder Batch-Aktionen.
- Lokal verwaltete `openclaw`-Profile weisen `cdpPort` und `cdpUrl` automatisch zu; setzen Sie
`cdpUrl` nur explizit für Remote-CDP.
- Lokal verwaltete Profile können `executablePath` setzen, um das globale
`cdpUrl` nur für Remote-CDP explizit.
- Lokal verwaltete Profile können `executablePath` setzen, um den globalen
`browser.executablePath` für dieses Profil zu überschreiben. Verwenden Sie dies, um ein Profil in
Chrome und ein anderes in Brave auszuführen.
- Lokal verwaltete Profile verwenden `browser.localLaunchTimeoutMs` für die Chrome-CDP-HTTP-
Discovery nach dem Prozessstart und `browser.localCdpReadyTimeoutMs` für die
CDP-WebSocket-Bereitschaft nach dem Start. Erhöhen Sie diese Werte auf langsameren Hosts, auf denen Chrome
erfolgreich startet, die Bereitschaftsprüfungen aber mit dem Startvorgang konkurrieren. Beide Werte müssen
erfolgreich startet, aber Bereitschaftsprüfungen mit dem Start konkurrieren. Beide Werte müssen
positive Ganzzahlen bis `120000` ms sein; ungültige Konfigurationswerte werden abgelehnt.
- Reihenfolge der automatischen Erkennung: Standardbrowser, falls Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary.
- Automatische Erkennungsreihenfolge: Standardbrowser, falls Chromium-basiert → Chrome → Brave → Edge → Chromium → Chrome Canary.
- `browser.executablePath` und `browser.profiles.<name>.executablePath` akzeptieren beide
`~` und `~/...` für das Home-Verzeichnis Ihres Betriebssystems vor dem Chromium-Start.
Profilbezogenes `userDataDir` bei `existing-session`-Profilen wird ebenfalls mit Tilde erweitert.
- Steuerdienst: nur loopback (Port abgeleitet von `gateway.port`, Standard `18791`).
`~` und `~/...` für Ihr OS-Home-Verzeichnis vor dem Chromium-Start.
Profilbezogenes `userDataDir` bei `existing-session`-Profilen wird ebenfalls per Tilde erweitert.
- Steuerungsdienst: nur loopback (Port aus `gateway.port` abgeleitet, Standard `18791`).
- `extraArgs` hängt zusätzliche Start-Flags an den lokalen Chromium-Start an (zum Beispiel
`--disable-gpu`, Fenstergrößen oder Debug-Flags).
`--disable-gpu`, Fenstergröße oder Debug-Flags).
---
## UI
## Benutzeroberfläche
```json5
{
@ -346,7 +322,7 @@ Siehe [Inferred Commitments](/de/concepts/commitments).
}
```
- `seamColor`: Akzentfarbe für die Chrome-Oberfläche der nativen App (Talk-Mode-Sprechblasentönung usw.).
- `seamColor`: Akzentfarbe für die Chrome der nativen App-Benutzeroberfläche (Talk-Mode-Sprechblasenfärbung usw.).
- `assistant`: Identitäts-Override für die Control UI. Fällt auf die Identität des aktiven Agenten zurück.
---
@ -425,52 +401,45 @@ Siehe [Inferred Commitments](/de/concepts/commitments).
<Accordion title="Gateway field details">
- `mode`: `local` (Gateway ausführen) oder `remote` (mit Remote-Gateway verbinden). Gateway verweigert den Start, sofern nicht `local` festgelegt ist.
- `port`: einzelner multiplexter Port für WS + HTTP. Vorrang: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `mode`: `local` (Gateway ausführen) oder `remote` (mit entferntem Gateway verbinden). Gateway verweigert den Start, sofern nicht `local` festgelegt ist.
- `port`: einzelner multiplexierter Port für WS + HTTP. Vorrang: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `bind`: `auto`, `loopback` (Standard), `lan` (`0.0.0.0`), `tailnet` (nur Tailscale-IP) oder `custom`.
- **Legacy-Bind-Aliasse**: Verwenden Sie Bind-Moduswerte in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), keine Host-Aliasse (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Docker-Hinweis**: Das standardmäßige `loopback`-Binding lauscht im Container auf `127.0.0.1`. Bei Docker-Bridge-Netzwerk (`-p 18789:18789`) trifft der Traffic auf `eth0` ein, sodass der Gateway nicht erreichbar ist. Verwenden Sie `--network host`, oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), um auf allen Interfaces zu lauschen.
- **Auth**: standardmäßig erforderlich. Nicht-Loopback-Bindings erfordern Gateway-Auth. Praktisch bedeutet das ein gemeinsames Token/Passwort oder einen identity-aware Reverse-Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- sowie Service-Installations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und der Modus nicht gesetzt ist.
- `gateway.auth.mode: "none"`: expliziter Modus ohne Auth. Nur für vertrauenswürdige local loopback-Setups verwenden; dies wird von Onboarding-Prompts absichtlich nicht angeboten.
- `gateway.auth.mode: "trusted-proxy"`: Browser-/Benutzerauthentifizierung an einen identity-aware Reverse-Proxy delegieren und Identitäts-Headern von `gateway.trustedProxies` vertrauen (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet standardmäßig eine **Nicht-Loopback**-Proxy-Quelle; Loopback-Reverse-Proxys auf demselben Host erfordern explizit `gateway.auth.trustedProxy.allowLoopback = true`. Interne Aufrufer auf demselben Host können `gateway.auth.password` als lokalen direkten Fallback verwenden; `gateway.auth.token` bleibt mit dem Trusted-Proxy-Modus gegenseitig exklusiv.
- `gateway.auth.allowTailscale`: Wenn `true`, können Tailscale Serve-Identitäts-Header die Control UI-/WebSocket-Auth erfüllen (verifiziert über `tailscale whois`). HTTP-API-Endpunkte verwenden diese Tailscale-Header-Auth **nicht**; sie folgen stattdessen dem normalen HTTP-Auth-Modus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Standardmäßig `true`, wenn `tailscale.mode = "serve"` gilt.
- **Docker-Hinweis**: Der standardmäßige `loopback`-Bind lauscht innerhalb des Containers auf `127.0.0.1`. Bei Docker-Bridge-Netzwerk (`-p 18789:18789`) kommt der Traffic auf `eth0` an, sodass das Gateway nicht erreichbar ist. Verwenden Sie `--network host`, oder setzen Sie `bind: "lan"` (oder `bind: "custom"` mit `customBindHost: "0.0.0.0"`), um auf allen Schnittstellen zu lauschen.
- **Auth**: standardmäßig erforderlich. Nicht-Loopback-Binds erfordern Gateway-Auth. In der Praxis bedeutet das ein gemeinsam genutztes Token/Passwort oder einen identitätsbewussten Reverse Proxy mit `gateway.auth.mode: "trusted-proxy"`. Der Onboarding-Assistent erzeugt standardmäßig ein Token.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind (einschließlich SecretRefs), setzen Sie `gateway.auth.mode` explizit auf `token` oder `password`. Start- und Dienstinstallations-/Reparaturabläufe schlagen fehl, wenn beide konfiguriert sind und der Modus nicht gesetzt ist.
- `gateway.auth.mode: "none"`: expliziter Modus ohne Auth. Nur für vertrauenswürdige local loopback-Setups verwenden; dies wird absichtlich nicht in Onboarding-Eingabeaufforderungen angeboten.
- `gateway.auth.mode: "trusted-proxy"`: Browser-/Benutzer-Auth an einen identitätsbewussten Reverse Proxy delegieren und Identitätsheadern von `gateway.trustedProxies` vertrauen (siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth)). Dieser Modus erwartet standardmäßig eine **Nicht-Loopback**-Proxy-Quelle; Same-Host-Loopback-Reverse-Proxies erfordern explizit `gateway.auth.trustedProxy.allowLoopback = true`. Interne Same-Host-Aufrufer können `gateway.auth.password` als lokalen direkten Fallback verwenden; `gateway.auth.token` bleibt mit dem Trusted-Proxy-Modus gegenseitig exklusiv.
- `gateway.auth.allowTailscale`: Wenn `true`, können Tailscale Serve-Identitätsheader die Control-UI-/WebSocket-Auth erfüllen (verifiziert über `tailscale whois`). HTTP-API-Endpunkte verwenden diese Tailscale-Header-Auth **nicht**; sie folgen stattdessen dem normalen HTTP-Auth-Modus des Gateways. Dieser tokenlose Ablauf setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Standardmäßig `true`, wenn `tailscale.mode = "serve"`.
- `gateway.auth.rateLimit`: optionaler Limiter für fehlgeschlagene Auth. Gilt pro Client-IP und pro Auth-Bereich (Shared-Secret und Device-Token werden unabhängig verfolgt). Blockierte Versuche geben `429` + `Retry-After` zurück.
- Auf dem asynchronen Tailscale Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, clientIp}` vor dem Schreiben des Fehlers serialisiert. Gleichzeitige fehlerhafte Versuche desselben Clients können daher den Limiter bereits bei der zweiten Anfrage auslösen, statt beide als einfache Nichtübereinstimmungen durchlaufen zu lassen.
- `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie es auf `false`, wenn Sie bewusst auch localhost-Traffic rate-limitieren möchten (für Test-Setups oder strikte Proxy-Deployments).
- Browser-Origin-WS-Auth-Versuche werden immer gedrosselt, wobei die Loopback-Ausnahme deaktiviert ist (Defense-in-Depth gegen browserbasiertes localhost-Brute-Force).
- Auf Loopback sind diese Browser-Origin-Sperren pro normalisiertem `Origin`-
Wert isoliert, sodass wiederholte Fehler von einem localhost-Origin nicht automatisch
einen anderen Origin sperren.
- Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe `{scope, clientIp}` vor dem Schreiben des Fehlers serialisiert. Gleichzeitige fehlerhafte Versuche desselben Clients können den Limiter daher schon bei der zweiten Anfrage auslösen, statt beide als einfache Nichtübereinstimmungen durchlaufen zu lassen.
- `gateway.auth.rateLimit.exemptLoopback` ist standardmäßig `true`; setzen Sie `false`, wenn Sie localhost-Traffic absichtlich ebenfalls rate-limitieren möchten (für Test-Setups oder strikte Proxy-Deployments).
- Browser-Origin-WS-Auth-Versuche werden immer gedrosselt, wobei die Loopback-Ausnahme deaktiviert ist (Defense-in-depth gegen browserbasierte localhost-Brute-Force-Angriffe).
- Auf Loopback sind diese Browser-Origin-Sperren pro normalisiertem `Origin`-Wert isoliert, sodass wiederholte Fehlschläge von einer localhost-Origin nicht automatisch eine andere Origin sperren.
- `tailscale.mode`: `serve` (nur Tailnet, Loopback-Bind) oder `funnel` (öffentlich, erfordert Auth).
- `controlUi.allowedOrigins`: explizite Browser-Origin-Allowlist für Gateway-WebSocket-Verbindungen. Erforderlich, wenn Browser-Clients von Nicht-Loopback-Origins erwartet werden.
- `controlUi.chatMessageMaxWidth`: optionale Maximalbreite für gruppierte Control UI-Chatnachrichten. Akzeptiert eingeschränkte CSS-Breitenwerte wie `960px`, `82%`, `min(1280px, 82%)` und `calc(100% - 2rem)`.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Host-Header-Origin-Fallback für Deployments aktiviert, die sich bewusst auf Host-Header-Origin-Policy stützen.
- `controlUi.chatMessageMaxWidth`: optionale Maximalbreite für gruppierte Control-UI-Chatnachrichten. Akzeptiert eingeschränkte CSS-Breitenwerte wie `960px`, `82%`, `min(1280px, 82%)` und `calc(100% - 2rem)`.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: gefährlicher Modus, der Host-Header-Origin-Fallback für Deployments aktiviert, die sich absichtlich auf Host-Header-Origin-Policy verlassen.
- `remote.transport`: `ssh` (Standard) oder `direct` (ws/wss). Für `direct` muss `remote.url` `ws://` oder `wss://` sein.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: Break-Glass-Override über die clientseitige Prozessumgebung,
der Klartext-`ws://` zu vertrauenswürdigen IPs in privaten Netzwerken erlaubt;
Standard bleibt Loopback-only für Klartext. Es gibt kein `openclaw.json`-
Äquivalent, und Browser-Private-Network-Konfiguration wie
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` wirkt sich nicht auf Gateway-
WebSocket-Clients aus.
- `gateway.remote.token` / `.password` sind Zugangsdatenfelder für Remote-Clients. Sie konfigurieren für sich genommen keine Gateway-Auth.
- `gateway.push.apns.relay.baseUrl`: Basis-HTTPS-URL für das externe APNs-Relay, das von offiziellen/TestFlight-iOS-Builds verwendet wird, nachdem sie relaygestützte Registrierungen am Gateway veröffentlicht haben. Diese URL muss mit der in den iOS-Build kompilierten Relay-URL übereinstimmen.
- `gateway.push.apns.relay.timeoutMs`: Gateway-zu-Relay-Sende-Timeout in Millisekunden. Standardmäßig `10000`.
- Relaygestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die gekoppelte iOS-App ruft `gateway.identity.get` ab, nimmt diese Identität in die Relay-Registrierung auf und leitet eine registrierungsspezifische Sendeberechtigung an den Gateway weiter. Ein anderer Gateway kann diese gespeicherte Registrierung nicht wiederverwenden.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: clientseitiger Break-Glass-Override per Prozessumgebung, der Klartext-`ws://` zu vertrauenswürdigen Private-Network-IPs erlaubt; der Standard bleibt für Klartext nur Loopback. Es gibt kein `openclaw.json`-Äquivalent, und Browser-Private-Network-Konfigurationen wie `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` wirken sich nicht auf Gateway-WebSocket-Clients aus.
- `gateway.remote.token` / `.password` sind Zugangsdatenfelder für Remote-Clients. Sie konfigurieren Gateway-Auth nicht selbst.
- `gateway.push.apns.relay.baseUrl`: Basis-HTTPS-URL für das externe APNs-Relay, das von offiziellen/TestFlight-iOS-Builds verwendet wird, nachdem sie relaygestützte Registrierungen am Gateway veröffentlicht haben. Diese URL muss mit der Relay-URL übereinstimmen, die in den iOS-Build einkompiliert ist.
- `gateway.push.apns.relay.timeoutMs`: Sendetimeout vom Gateway zum Relay in Millisekunden. Standardwert: `10000`.
- Relaygestützte Registrierungen werden an eine bestimmte Gateway-Identität delegiert. Die gekoppelte iOS-App ruft `gateway.identity.get` ab, nimmt diese Identität in die Relay-Registrierung auf und leitet eine registrierungsspezifische Sendegewährung an das Gateway weiter. Ein anderes Gateway kann diese gespeicherte Registrierung nicht wiederverwenden.
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: temporäre Env-Overrides für die obige Relay-Konfiguration.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für Entwicklung vorgesehene Ausweichoption für Loopback-HTTP-Relay-URLs. Produktions-Relay-URLs sollten bei HTTPS bleiben.
- `gateway.handshakeTimeoutMs`: Pre-Auth-Gateway-WebSocket-Handshake-Timeout in Millisekunden. Standard: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` hat Vorrang, wenn gesetzt. Erhöhen Sie dies auf ausgelasteten oder leistungsschwachen Hosts, auf denen lokale Clients eine Verbindung herstellen können, während sich das Start-Warmup noch stabilisiert.
- `gateway.channelHealthCheckMinutes`: Intervall des Kanal-Health-Monitors in Minuten. Setzen Sie `0`, um Health-Monitor-Neustarts global zu deaktivieren. Standard: `5`.
- `gateway.channelStaleEventThresholdMinutes`: Schwellwert für veraltete Sockets in Minuten. Halten Sie diesen größer oder gleich `gateway.channelHealthCheckMinutes`. Standard: `30`.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: nur für Entwicklung vorgesehene Escape Hatch für Loopback-HTTP-Relay-URLs. Produktions-Relay-URLs sollten bei HTTPS bleiben.
- `gateway.handshakeTimeoutMs`: Pre-Auth-Gateway-WebSocket-Handshake-Timeout in Millisekunden. Standard: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` hat Vorrang, wenn gesetzt. Erhöhen Sie dies auf ausgelasteten oder leistungsschwachen Hosts, auf denen lokale Clients eine Verbindung herstellen können, während sich der Startup-Warmup noch stabilisiert.
- `gateway.channelHealthCheckMinutes`: Health-Monitor-Intervall für Kanäle in Minuten. Setzen Sie `0`, um Health-Monitor-Neustarts global zu deaktivieren. Standard: `5`.
- `gateway.channelStaleEventThresholdMinutes`: Schwelle für veraltete Sockets in Minuten. Halten Sie diesen Wert größer oder gleich `gateway.channelHealthCheckMinutes`. Standard: `30`.
- `gateway.channelMaxRestartsPerHour`: maximale Health-Monitor-Neustarts pro Kanal/Konto in einer rollierenden Stunde. Standard: `10`.
- `channels.<provider>.healthMonitor.enabled`: Opt-out pro Kanal für Health-Monitor-Neustarts, während der globale Monitor aktiviert bleibt.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: Override pro Konto für Multi-Account-Kanäle. Wenn gesetzt, hat dies Vorrang vor dem Override auf Kanalebene.
- Lokale Gateway-Aufrufpfade können `gateway.remote.*` nur dann als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist.
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht auflösbar ist, schlägt die Auflösung geschlossen fehl (keine Verschleierung durch Remote-Fallback).
- `trustedProxies`: Reverse-Proxy-IPs, die TLS terminieren oder Forwarded-Client-Header injizieren. Listen Sie nur Proxys auf, die Sie kontrollieren. Loopback-Einträge sind weiterhin für Proxy-/Lokalerkennungs-Setups auf demselben Host gültig (zum Beispiel Tailscale Serve oder ein lokaler Reverse-Proxy), sie machen Loopback-Anfragen jedoch **nicht** für `gateway.auth.mode: "trusted-proxy"` zulässig.
- `allowRealIpFallback`: Wenn `true`, akzeptiert der Gateway `X-Real-IP`, falls `X-Forwarded-For` fehlt. Standard `false` für Fail-Closed-Verhalten.
- `gateway.nodes.pairing.autoApproveCidrs`: optionale CIDR/IP-Allowlist zum automatischen Genehmigen erstmaliger Node-Gerätekopplung ohne angeforderte Scopes. Sie ist deaktiviert, wenn nicht gesetzt. Dies genehmigt keine Operator-/Browser-/Control UI-/WebChat-Kopplung automatisch und genehmigt auch keine Rollen-, Scope-, Metadaten- oder Public-Key-Upgrades automatisch.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: globale Allow-/Deny-Steuerung für deklarierte Node-Befehle nach Kopplung und Plattform-Allowlist-Auswertung. Verwenden Sie `allowCommands`, um gefährliche Node-Befehle wie `camera.snap`, `camera.clip` und `screen.record` zu aktivieren; `denyCommands` entfernt einen Befehl, selbst wenn ein Plattformstandard oder eine explizite Allow-Regel ihn sonst einschließen würde. Nachdem eine Node ihre deklarierte Befehlsliste geändert hat, lehnen Sie die Gerätekopplung ab und genehmigen Sie sie erneut, damit der Gateway den aktualisierten Befehls-Snapshot speichert.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: Override pro Konto für Multi-Account-Kanäle. Wenn gesetzt, hat er Vorrang vor dem Override auf Kanalebene.
- Lokale Gateway-Aufrufpfade können `gateway.remote.*` nur als Fallback verwenden, wenn `gateway.auth.*` nicht gesetzt ist.
- Wenn `gateway.auth.token` / `gateway.auth.password` explizit über SecretRef konfiguriert und nicht auflösbar ist, schlägt die Auflösung geschlossen fehl (keine Maskierung durch Remote-Fallback).
- `trustedProxies`: IPs von Reverse Proxies, die TLS terminieren oder Forwarded-Client-Header injizieren. Listen Sie nur Proxies auf, die Sie kontrollieren. Loopback-Einträge sind weiterhin für Same-Host-Proxy-/Local-Detection-Setups gültig (zum Beispiel Tailscale Serve oder ein lokaler Reverse Proxy), sie machen Loopback-Anfragen aber **nicht** für `gateway.auth.mode: "trusted-proxy"` berechtigt.
- `allowRealIpFallback`: Wenn `true`, akzeptiert das Gateway `X-Real-IP`, wenn `X-Forwarded-For` fehlt. Standard ist `false` für fail-closed-Verhalten.
- `gateway.nodes.pairing.autoApproveCidrs`: optionale CIDR/IP-Allowlist zum automatischen Genehmigen erstmaliger Node-Device-Kopplungen ohne angeforderte Scopes. Sie ist deaktiviert, wenn nicht gesetzt. Dies genehmigt Operator-/Browser-/Control-UI-/WebChat-Kopplungen nicht automatisch und genehmigt auch Rollen-, Scope-, Metadaten- oder Public-Key-Upgrades nicht automatisch.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: globale Allow-/Deny-Formung für deklarierte Node-Befehle nach der Kopplung und der Auswertung der Plattform-Allowlist. Verwenden Sie `allowCommands`, um gefährliche Node-Befehle wie `camera.snap`, `camera.clip` und `screen.record` ausdrücklich zuzulassen; `denyCommands` entfernt einen Befehl, auch wenn ein Plattformstandard oder eine explizite Allow-Regel ihn sonst einschließen würde. Nachdem ein Node seine deklarierte Befehlsliste geändert hat, lehnen Sie die Gerätekopplung ab und genehmigen Sie sie erneut, damit das Gateway den aktualisierten Befehls-Snapshot speichert.
- `gateway.tools.deny`: zusätzliche Tool-Namen, die für HTTP `POST /tools/invoke` blockiert werden (erweitert die Standard-Deny-Liste).
- `gateway.tools.allow`: Tool-Namen aus der Standard-HTTP-Deny-Liste entfernen.
@ -480,16 +449,15 @@ Siehe [Inferred Commitments](/de/concepts/commitments).
- Chat Completions: standardmäßig deaktiviert. Aktivieren mit `gateway.http.endpoints.chatCompletions.enabled: true`.
- Responses API: `gateway.http.endpoints.responses.enabled`.
- Responses-URL-Eingabehärtung:
- Härtung für Responses-URL-Eingaben:
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
Leere Allowlists werden als nicht gesetzt behandelt; verwenden Sie `gateway.http.endpoints.responses.files.allowUrl=false`
und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um URL-Abrufe zu deaktivieren.
Leere Allowlists werden als nicht gesetzt behandelt; verwenden Sie `gateway.http.endpoints.responses.files.allowUrl=false` und/oder `gateway.http.endpoints.responses.images.allowUrl=false`, um URL-Abruf zu deaktivieren.
- Optionaler Header zur Response-Härtung:
- `gateway.http.securityHeaders.strictTransportSecurity` (nur für von Ihnen kontrollierte HTTPS-Origins setzen; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth#tls-termination-and-hsts))
- `gateway.http.securityHeaders.strictTransportSecurity` (nur für HTTPS-Origins setzen, die Sie kontrollieren; siehe [Trusted Proxy Auth](/de/gateway/trusted-proxy-auth#tls-termination-and-hsts))
### Multi-Instanz-Isolierung
### Isolation mehrerer Instanzen
Führen Sie mehrere Gateways auf einem Host mit eindeutigen Ports und State-Verzeichnissen aus:
@ -501,7 +469,7 @@ openclaw gateway --port 19001
Komfort-Flags: `--dev` (verwendet `~/.openclaw-dev` + Port `19001`), `--profile <name>` (verwendet `~/.openclaw-<name>`).
Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
Siehe [Mehrere Gateways](/de/gateway/multiple-gateways).
### `gateway.tls`
@ -519,10 +487,10 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
}
```
- `enabled`: aktiviert die TLS-Terminierung am Gateway-Listener (HTTPS/WSS) (Standard: `false`).
- `enabled`: aktiviert TLS-Terminierung am Gateway-Listener (HTTPS/WSS) (Standard: `false`).
- `autoGenerate`: erzeugt automatisch ein lokales selbstsigniertes Zertifikat/Schlüsselpaar, wenn keine expliziten Dateien konfiguriert sind; nur für lokale/Dev-Nutzung.
- `certPath`: Dateisystempfad zur TLS-Zertifikatsdatei.
- `keyPath`: Dateisystempfad zur privaten TLS-Schlüsseldatei; Berechtigungen eingeschränkt halten.
- `keyPath`: Dateisystempfad zur TLS-Private-Key-Datei; halten Sie die Berechtigungen eingeschränkt.
- `caPath`: optionaler CA-Bundle-Pfad für Client-Verifizierung oder benutzerdefinierte Vertrauensketten.
### `gateway.reload`
@ -541,11 +509,11 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
- `mode`: steuert, wie Konfigurationsänderungen zur Laufzeit angewendet werden.
- `"off"`: Live-Änderungen ignorieren; Änderungen erfordern einen expliziten Neustart.
- `"restart"`: den Gateway-Prozess bei Konfigurationsänderung immer neu starten.
- `"restart"`: den Gateway-Prozess bei Konfigurationsänderungen immer neu starten.
- `"hot"`: Änderungen im Prozess ohne Neustart anwenden.
- `"hybrid"` (Standard): zuerst Hot Reload versuchen; bei Bedarf auf Neustart zurückfallen.
- `debounceMs`: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nicht negative Ganzzahl).
- `deferralTimeoutMs`: optionale Maximalzeit in ms, um vor dem Erzwingen eines Neustarts auf laufende Vorgänge zu warten. Weglassen, um die standardmäßige begrenzte Wartezeit (`300000`) zu verwenden; auf `0` setzen, um unbegrenzt zu warten und regelmäßige Still-Pending-Warnungen zu protokollieren.
- `debounceMs`: Debounce-Fenster in ms, bevor Konfigurationsänderungen angewendet werden (nichtnegative Ganzzahl).
- `deferralTimeoutMs`: optionale maximale Zeit in ms, um vor einem erzwungenen Neustart auf laufende Vorgänge zu warten. Weglassen, um die standardmäßige begrenzte Wartezeit (`300000`) zu verwenden; auf `0` setzen, um unbegrenzt zu warten und periodische Warnungen zu weiterhin ausstehenden Vorgängen zu protokollieren.
---
@ -583,23 +551,23 @@ Siehe [Multiple Gateways](/de/gateway/multiple-gateways).
```
Authentifizierung: `Authorization: Bearer <token>` oder `x-openclaw-token: <token>`.
Hook-Tokens in Query-Strings werden abgelehnt.
Hook-Token in Query-Strings werden abgelehnt.
Validierungs- und Sicherheitshinweise:
- `hooks.enabled=true` erfordert ein nicht leeres `hooks.token`.
- `hooks.token` muss sich von `gateway.auth.token` **unterscheiden**; die Wiederverwendung des Gateway-Tokens wird abgelehnt.
- `hooks.path` darf nicht `/` sein; verwenden Sie einen dedizierten Unterpfad wie `/hooks`.
- Wenn `hooks.allowRequestSessionKey=true`, beschränken Sie `hooks.allowedSessionKeyPrefixes` (zum Beispiel `["hook:"]`).
- Wenn ein Mapping oder Preset einen vorlagenbasierten `sessionKey` verwendet, setzen Sie `hooks.allowedSessionKeyPrefixes` und `hooks.allowRequestSessionKey=true`. Statische Mapping-Schlüssel erfordern dieses Opt-in nicht.
- Wenn `hooks.allowRequestSessionKey=true` ist, schränken Sie `hooks.allowedSessionKeyPrefixes` ein, zum Beispiel `["hook:"]`.
- Wenn ein Mapping oder Preset einen templatisierten `sessionKey` verwendet, setzen Sie `hooks.allowedSessionKeyPrefixes` und `hooks.allowRequestSessionKey=true`. Statische Mapping-Schlüssel erfordern dieses Opt-in nicht.
**Endpunkte:**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- `sessionKey` aus der Anfrage-Payload wird nur akzeptiert, wenn `hooks.allowRequestSessionKey=true` ist (Standard: `false`).
- `POST /hooks/<name>` → aufgelöst über `hooks.mappings`
- Per Template gerenderte Mapping-Werte für `sessionKey` werden als extern bereitgestellt behandelt und erfordern ebenfalls `hooks.allowRequestSessionKey=true`.
- `sessionKey` aus der Request-Payload wird nur akzeptiert, wenn `hooks.allowRequestSessionKey=true` ist (Standard: `false`).
- `POST /hooks/<name>` → wird über `hooks.mappings` aufgelöst
- Durch Templates gerenderte Mapping-Werte für `sessionKey` werden als extern bereitgestellt behandelt und erfordern ebenfalls `hooks.allowRequestSessionKey=true`.
<Accordion title="Mapping-Details">
@ -608,22 +576,22 @@ Validierungs- und Sicherheitshinweise:
- Templates wie `{{messages[0].subject}}` lesen aus der Payload.
- `transform` kann auf ein JS/TS-Modul verweisen, das eine Hook-Aktion zurückgibt.
- `transform.module` muss ein relativer Pfad sein und innerhalb von `hooks.transformsDir` bleiben (absolute Pfade und Traversal werden abgelehnt).
- Belassen Sie `hooks.transformsDir` unter `~/.openclaw/hooks/transforms`; Workspace-Skill-Verzeichnisse werden abgelehnt. Wenn `openclaw doctor` diesen Pfad als ungültig meldet, verschieben Sie das Transform-Modul in das Hooks-Transform-Verzeichnis oder entfernen Sie `hooks.transformsDir`.
- Belassen Sie `hooks.transformsDir` unter `~/.openclaw/hooks/transforms`; Workspace-Skill-Verzeichnisse werden abgelehnt. Wenn `openclaw doctor` diesen Pfad als ungültig meldet, verschieben Sie das Transformationsmodul in das Hook-Transformationsverzeichnis oder entfernen Sie `hooks.transformsDir`.
- `agentId` leitet an einen bestimmten Agenten weiter; unbekannte IDs fallen auf den Standard zurück.
- `allowedAgentIds`: beschränkt explizites Routing (`*` oder ausgelassen = alle zulassen, `[]` = alle verweigern).
- `defaultSessionKey`: optionaler fester Sitzungsschlüssel für Hook-Agent-Ausführungen ohne expliziten `sessionKey`.
- `allowedAgentIds`: schränkt explizites Routing ein (`*` oder ausgelassen = alle erlauben, `[]` = alle verweigern).
- `defaultSessionKey`: optionaler fester Sitzungsschlüssel für Hook-Agent-Läufe ohne expliziten `sessionKey`.
- `allowRequestSessionKey`: erlaubt Aufrufern von `/hooks/agent` und templategesteuerten Mapping-Sitzungsschlüsseln, `sessionKey` zu setzen (Standard: `false`).
- `allowedSessionKeyPrefixes`: optionale Präfix-Allowlist für explizite `sessionKey`-Werte (Anfrage + Mapping), z. B. `["hook:"]`. Sie wird erforderlich, wenn ein Mapping oder Preset einen vorlagenbasierten `sessionKey` verwendet.
- `deliver: true` sendet die endgültige Antwort an einen Kanal; `channel` ist standardmäßig `last`.
- `model` überschreibt das LLM für diese Hook-Ausführung (muss erlaubt sein, wenn der Modellkatalog gesetzt ist).
- `allowedSessionKeyPrefixes`: optionale Präfix-Allowlist für explizite `sessionKey`-Werte (Request + Mapping), z. B. `["hook:"]`. Sie wird erforderlich, wenn ein Mapping oder Preset einen templatisierten `sessionKey` verwendet.
- `deliver: true` sendet die finale Antwort an einen Kanal; `channel` ist standardmäßig `last`.
- `model` überschreibt das LLM für diesen Hook-Lauf (muss erlaubt sein, wenn der Modellkatalog gesetzt ist).
</Accordion>
### Gmail-Integration
- Das integrierte Gmail-Preset verwendet `sessionKey: "hook:gmail:{{messages[0].id}}"`.
- Wenn Sie dieses Routing pro Nachricht beibehalten, setzen Sie `hooks.allowRequestSessionKey: true` und beschränken Sie `hooks.allowedSessionKeyPrefixes` passend zum Gmail-Namespace, zum Beispiel `["hook:", "hook:gmail:"]`.
- Wenn Sie `hooks.allowRequestSessionKey: false` benötigen, überschreiben Sie das Preset mit einem statischen `sessionKey` statt mit dem vorlagenbasierten Standard.
- Wenn Sie dieses Routing pro Nachricht beibehalten, setzen Sie `hooks.allowRequestSessionKey: true` und schränken Sie `hooks.allowedSessionKeyPrefixes` so ein, dass sie zum Gmail-Namespace passen, zum Beispiel `["hook:", "hook:gmail:"]`.
- Wenn Sie `hooks.allowRequestSessionKey: false` benötigen, überschreiben Sie das Preset mit einem statischen `sessionKey` statt des templatisierten Standards.
```json5
{
@ -647,7 +615,7 @@ Validierungs- und Sicherheitshinweise:
```
- Gateway startet `gog gmail watch serve` beim Booten automatisch, wenn es konfiguriert ist. Setzen Sie `OPENCLAW_SKIP_GMAIL_WATCHER=1`, um dies zu deaktivieren.
- Führen Sie kein separates `gog gmail watch serve` neben dem Gateway aus.
- Führen Sie kein separates `gog gmail watch serve` parallel zum Gateway aus.
---
@ -663,18 +631,18 @@ Validierungs- und Sicherheitshinweise:
}
```
- Stellt vom Agenten bearbeitbares HTML/CSS/JS und A2UI über HTTP unter dem Gateway-Port bereit:
- Stellt agenteneditierbares HTML/CSS/JS und A2UI per HTTP unter dem Gateway-Port bereit:
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- Nur lokal: behalten Sie `gateway.bind: "loopback"` bei (Standard).
- Nicht-loopback-Bindings: Canvas-Routen erfordern Gateway-Authentifizierung (Token/Passwort/Trusted-Proxy), genau wie andere HTTP-Oberflächen des Gateway.
- Node-WebViews senden typischerweise keine Auth-Header; nachdem ein Node gekoppelt und verbunden wurde, veröffentlicht der Gateway node-spezifische Capability-URLs für Canvas-/A2UI-Zugriff.
- Nur lokal: belassen Sie `gateway.bind: "loopback"` (Standard).
- Nicht-Loopback-Bindungen: Canvas-Routen erfordern Gateway-Authentifizierung (Token/Passwort/vertrauenswürdiger Proxy), genau wie andere Gateway-HTTP-Oberflächen.
- Node WebViews senden normalerweise keine Auth-Header; nachdem ein Node gekoppelt und verbunden ist, bewirbt das Gateway Node-bezogene Capability-URLs für den Canvas-/A2UI-Zugriff.
- Capability-URLs sind an die aktive Node-WS-Sitzung gebunden und laufen schnell ab. IP-basierter Fallback wird nicht verwendet.
- Injiziert einen Live-Reload-Client in bereitgestelltes HTML.
- Injiziert den Live-Reload-Client in bereitgestelltes HTML.
- Erstellt automatisch eine Starter-`index.html`, wenn leer.
- Stellt A2UI auch unter `/__openclaw__/a2ui/` bereit.
- Änderungen erfordern einen Gateway-Neustart.
- Deaktivieren Sie Live-Reload für große Verzeichnisse oder bei `EMFILE`-Fehlern.
- Deaktivieren Sie Live Reload für große Verzeichnisse oder bei `EMFILE`-Fehlern.
---
@ -692,11 +660,11 @@ Validierungs- und Sicherheitshinweise:
}
```
- `minimal` (Standard, wenn das gebündelte `bonjour`-Plugin aktiviert ist): lässt `cliPath` + `sshPort` aus TXT-Einträgen aus.
- `minimal` (Standard, wenn das gebündelte `bonjour`-Plugin aktiviert ist): lässt `cliPath` + `sshPort` in TXT-Records aus.
- `full`: schließt `cliPath` + `sshPort` ein; LAN-Multicast-Ankündigung erfordert weiterhin, dass das gebündelte `bonjour`-Plugin aktiviert ist.
- `off`: unterdrückt LAN-Multicast-Ankündigung, ohne die Plugin-Aktivierung zu ändern.
- Das gebündelte `bonjour`-Plugin startet auf macOS-Hosts automatisch und ist auf Linux, Windows und containerisierten Gateway-Bereitstellungen Opt-in.
- Der Hostname ist standardmäßig der Systemhostname, wenn er ein gültiges DNS-Label ist, andernfalls `openclaw`. Überschreiben Sie ihn mit `OPENCLAW_MDNS_HOSTNAME`.
- Das gebündelte `bonjour`-Plugin startet auf macOS-Hosts automatisch und ist auf Linux, Windows und containerisierten Gateway-Deployments Opt-in.
- Der Hostname ist standardmäßig der Systemhostname, wenn er ein gültiges DNS-Label ist; andernfalls wird auf `openclaw` zurückgefallen. Überschreiben Sie ihn mit `OPENCLAW_MDNS_HOSTNAME`.
### Wide-Area (DNS-SD)
@ -708,7 +676,7 @@ Validierungs- und Sicherheitshinweise:
}
```
Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für Discovery über Netzwerkgrenzen hinweg kombinieren Sie dies mit einem DNS-Server (CoreDNS empfohlen) + Tailscale-Split-DNS.
Schreibt eine Unicast-DNS-SD-Zone unter `~/.openclaw/dns/`. Für netzwerkübergreifende Discovery kombinieren Sie dies mit einem DNS-Server (CoreDNS empfohlen) + Tailscale Split-DNS.
Einrichtung: `openclaw dns setup --apply`.
@ -716,7 +684,7 @@ Einrichtung: `openclaw dns setup --apply`.
## Umgebung
### `env` (Inline-Env-Variablen)
### `env` (Inline-Umgebungsvariablen)
```json5
{
@ -733,14 +701,14 @@ Einrichtung: `openclaw dns setup --apply`.
}
```
- Inline-Env-Variablen werden nur angewendet, wenn der Prozessumgebung der Schlüssel fehlt.
- `.env`-Dateien: CWD-`.env` + `~/.openclaw/.env` (keine davon überschreibt vorhandene Variablen).
- Inline-Umgebungsvariablen werden nur angewendet, wenn in der Prozessumgebung der Schlüssel fehlt.
- `.env`-Dateien: CWD `.env` + `~/.openclaw/.env` (keine davon überschreibt vorhandene Variablen).
- `shellEnv`: importiert fehlende erwartete Schlüssel aus Ihrem Login-Shell-Profil.
- Siehe [Umgebung](/de/help/environment) für die vollständige Vorrangfolge.
- Die vollständige Vorrangreihenfolge finden Sie unter [Umgebung](/de/help/environment).
### Ersetzung von Env-Variablen
### Ersetzung von Umgebungsvariablen
Verweisen Sie in beliebigen Konfigurationszeichenfolgen mit `${VAR_NAME}` auf Env-Variablen:
Referenzieren Sie Umgebungsvariablen in jeder Konfigurationszeichenfolge mit `${VAR_NAME}`:
```json5
{
@ -750,16 +718,16 @@ Verweisen Sie in beliebigen Konfigurationszeichenfolgen mit `${VAR_NAME}` auf En
}
```
- Nur großgeschriebene Namen werden abgeglichen: `[A-Z_][A-Z0-9_]*`.
- Nur Namen in Großbuchstaben werden erkannt: `[A-Z_][A-Z0-9_]*`.
- Fehlende/leere Variablen lösen beim Laden der Konfiguration einen Fehler aus.
- Escapen Sie mit `$${VAR}` für ein literales `${VAR}`.
- Mit `$${VAR}` maskieren Sie ein literales `${VAR}`.
- Funktioniert mit `$include`.
---
## Secrets
Secret-Refs sind additiv: Klartextwerte funktionieren weiterhin.
Secret-Referenzen sind additiv: Klartextwerte funktionieren weiterhin.
### `SecretRef`
@ -772,18 +740,18 @@ Verwenden Sie eine Objektform:
Validierung:
- `provider`-Muster: `^[a-z][a-z0-9_-]{0,63}$`
- `source: "env"`-`id`-Muster: `^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"`-`id`: absoluter JSON-Pointer (zum Beispiel `"/providers/openai/apiKey"`)
- `source: "exec"`-`id`-Muster: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "env"`-ID-Muster: `^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"`-ID: absoluter JSON-Pointer (zum Beispiel `"/providers/openai/apiKey"`)
- `source: "exec"`-ID-Muster: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"`-IDs dürfen keine durch Schrägstriche getrennten Pfadsegmente `.` oder `..` enthalten (zum Beispiel wird `a/../b` abgelehnt)
### Unterstützte Zugangsdatenoberfläche
### Unterstützte Oberfläche für Anmeldeinformationen
- Kanonische Matrix: [SecretRef-Zugangsdatenoberfläche](/de/reference/secretref-credential-surface)
- `secrets apply` zielt auf unterstützte `openclaw.json`-Zugangsdatenpfade ab.
- `auth-profiles.json`-Refs sind in die Laufzeitauflösung und Audit-Abdeckung einbezogen.
- Kanonische Matrix: [SecretRef-Oberfläche für Anmeldeinformationen](/de/reference/secretref-credential-surface)
- `secrets apply` zielt auf unterstützte Anmeldeinformationspfade in `openclaw.json`.
- `auth-profiles.json`-Referenzen sind in Laufzeitauflösung und Audit-Abdeckung enthalten.
### Konfiguration von Secret-Providern
### Secret-Provider-Konfiguration
```json5
{
@ -814,17 +782,17 @@ Validierung:
Hinweise:
- Der `file`-Provider unterstützt `mode: "json"` und `mode: "singleValue"` (`id` muss im singleValue-Modus `"value"` sein).
- Datei- und exec-Provider-Pfade schlagen geschlossen fehl, wenn die Windows-ACL-Verifizierung nicht verfügbar ist. Setzen Sie `allowInsecurePath: true` nur für vertrauenswürdige Pfade, die nicht verifiziert werden können.
- Datei- und exec-Provider-Pfade schlagen sicher fehl, wenn die Windows-ACL-Verifizierung nicht verfügbar ist. Setzen Sie `allowInsecurePath: true` nur für vertrauenswürdige Pfade, die nicht verifiziert werden können.
- Der `exec`-Provider erfordert einen absoluten `command`-Pfad und verwendet Protokoll-Payloads über stdin/stdout.
- Standardmäßig werden Symlink-Befehlspfade abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zu erlauben, während der aufgelöste Zielpfad validiert wird.
- Wenn `trustedDirs` konfiguriert ist, gilt die Prüfung des vertrauenswürdigen Verzeichnisses für den aufgelösten Zielpfad.
- Standardmäßig werden Symlink-Befehlspfade abgelehnt. Setzen Sie `allowSymlinkCommand: true`, um Symlink-Pfade zuzulassen und dabei den aufgelösten Zielpfad zu validieren.
- Wenn `trustedDirs` konfiguriert ist, wird die Prüfung des vertrauenswürdigen Verzeichnisses auf den aufgelösten Zielpfad angewendet.
- Die `exec`-Kindumgebung ist standardmäßig minimal; übergeben Sie erforderliche Variablen explizit mit `passEnv`.
- Secret-Refs werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst; danach lesen Anfragepfade nur den Snapshot.
- Die Filterung aktiver Oberflächen wird während der Aktivierung angewendet: Nicht aufgelöste Refs auf aktivierten Oberflächen lassen Start/Neuladen fehlschlagen, während inaktive Oberflächen mit Diagnosen übersprungen werden.
- Secret-Referenzen werden zur Aktivierungszeit in einen In-Memory-Snapshot aufgelöst; anschließend lesen Anforderungspfade nur den Snapshot.
- Während der Aktivierung wird nach aktiven Oberflächen gefiltert: Nicht aufgelöste Referenzen auf aktivierten Oberflächen lassen Start/Neuladen fehlschlagen, während inaktive Oberflächen mit Diagnosen übersprungen werden.
---
## Auth-Speicher
## Auth-Speicherung
```json5
{
@ -842,14 +810,14 @@ Hinweise:
}
```
- Profile pro Agent werden unter `<agentDir>/auth-profiles.json` gespeichert.
- `auth-profiles.json` unterstützt Refs auf Wertebene (`keyRef` für `api_key`, `tokenRef` für `token`) für statische Zugangsdatenmodi.
- Legacy-flache `auth-profiles.json`-Maps wie `{ "provider": { "apiKey": "..." } }` sind kein Laufzeitformat; `openclaw doctor --fix` schreibt sie in kanonische `provider:default`-API-Key-Profile mit einem `.legacy-flat.*.bak`-Backup um.
- OAuth-Modus-Profile (`auth.profiles.<id>.mode = "oauth"`) unterstützen keine durch SecretRef gestützten Zugangsdaten für Auth-Profile.
- Statische Laufzeit-Zugangsdaten stammen aus im Arbeitsspeicher aufgelösten Snapshots; Legacy-statische `auth.json`-Einträge werden bereinigt, wenn sie entdeckt werden.
- Legacy-OAuth-Importe aus `~/.openclaw/credentials/oauth.json`.
- Pro-Agent-Profile werden unter `<agentDir>/auth-profiles.json` gespeichert.
- `auth-profiles.json` unterstützt Referenzen auf Wertebene (`keyRef` für `api_key`, `tokenRef` für `token`) für statische Anmeldeinformationsmodi.
- Alte flache `auth-profiles.json`-Zuordnungen wie `{ "provider": { "apiKey": "..." } }` sind kein Laufzeitformat; `openclaw doctor --fix` schreibt sie in kanonische `provider:default`-API-Schlüsselprofile mit einer `.legacy-flat.*.bak`-Sicherung um.
- Profile im OAuth-Modus (`auth.profiles.<id>.mode = "oauth"`) unterstützen keine SecretRef-gestützten Auth-Profil-Anmeldeinformationen.
- Statische Laufzeit-Anmeldeinformationen stammen aus aufgelösten In-Memory-Snapshots; alte statische `auth.json`-Einträge werden bereinigt, wenn sie gefunden werden.
- Alte OAuth-Importe stammen aus `~/.openclaw/credentials/oauth.json`.
- Siehe [OAuth](/de/concepts/oauth).
- Laufzeitverhalten von Secrets und `audit/configure/apply`-Tooling: [Secrets-Verwaltung](/de/gateway/secrets).
- Laufzeitverhalten von Secrets und Werkzeuge für `audit/configure/apply`: [Secrets-Verwaltung](/de/gateway/secrets).
### `auth.cooldowns`
@ -872,19 +840,19 @@ Hinweise:
```
- `billingBackoffHours`: Basis-Backoff in Stunden, wenn ein Profil aufgrund echter
Abrechnungs-/Guthabenfehler fehlschlägt (Standard: `5`). Expliziter Abrechnungstext kann
hier selbst bei `401`/`403`-Antworten weiterhin landen, aber Provider-spezifische Text-
Abrechnungs-/Guthaben-unzureichend-Fehler fehlschlägt (Standard: `5`). Expliziter Abrechnungstext kann
auch bei `401`/`403`-Antworten weiterhin hier landen, aber Provider-spezifische Text-
Matcher bleiben auf den Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter
`Key limit exceeded`). Wiederholbare HTTP-`402`-Meldungen zu Nutzungsfenstern oder
Ausgabenlimits für Organisation/Workspace bleiben stattdessen im `rate_limit`-Pfad.
- `billingBackoffHoursByProvider`: optionale Provider-spezifische Überschreibungen für Abrechnungs-Backoff-Stunden.
- `billingMaxHours`: Obergrenze in Stunden für das exponentielle Wachstum des Abrechnungs-Backoffs (Standard: `24`).
- `authPermanentBackoffMinutes`: Basis-Backoff in Minuten für mit hoher Sicherheit erkannte `auth_permanent`-Fehler (Standard: `10`).
- `authPermanentMaxMinutes`: Obergrenze in Minuten für das Wachstum des `auth_permanent`-Backoffs (Standard: `60`).
- `failureWindowHours`: rollierendes Zeitfenster in Stunden, das für Backoff-Zähler verwendet wird (Standard: `24`).
- `overloadedProfileRotations`: maximale Anzahl von Auth-Profil-Rotationen beim selben Provider für Überlastungsfehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Provider-Auslastungsformen wie `ModelNotReadyException` landen hier.
`Key limit exceeded`). Wiederholbare HTTP-`402`-Nutzungsfenster- oder
Organisations-/Workspace-Ausgabenlimit-Meldungen bleiben stattdessen im `rate_limit`-Pfad.
- `billingBackoffHoursByProvider`: optionale Überschreibungen pro Provider für Abrechnungs-Backoff-Stunden.
- `billingMaxHours`: Obergrenze in Stunden für exponentielles Wachstum des Abrechnungs-Backoffs (Standard: `24`).
- `authPermanentBackoffMinutes`: Basis-Backoff in Minuten für hochzuverlässige `auth_permanent`-Fehlschläge (Standard: `10`).
- `authPermanentMaxMinutes`: Obergrenze in Minuten für `auth_permanent`-Backoff-Wachstum (Standard: `60`).
- `failureWindowHours`: rollierendes Fenster in Stunden für Backoff-Zähler (Standard: `24`).
- `overloadedProfileRotations`: maximale Auth-Profil-Rotationen beim selben Provider für Überlastungsfehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Provider-ausgelastet-Formen wie `ModelNotReadyException` landen hier.
- `overloadedBackoffMs`: feste Verzögerung vor dem erneuten Versuch einer überlasteten Provider-/Profil-Rotation (Standard: `0`).
- `rateLimitedProfileRotations`: maximale Anzahl von Auth-Profil-Rotationen beim selben Provider für Rate-Limit-Fehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Rate-Limit-Bucket umfasst Provider-geprägten Text wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`.
- `rateLimitedProfileRotations`: maximale Auth-Profil-Rotationen beim selben Provider für Ratenlimitfehler, bevor auf Modell-Fallback umgeschaltet wird (Standard: `1`). Dieser Ratenlimit-Bucket enthält Provider-geprägten Text wie `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` und `resource exhausted`.
---
@ -904,10 +872,10 @@ Hinweise:
```
- Standard-Protokolldatei: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
- Legen Sie `logging.file` für einen stabilen Pfad fest.
- Setzen Sie `logging.file` für einen stabilen Pfad.
- `consoleLevel` wird bei `--verbose` auf `debug` angehoben.
- `maxFileBytes`: maximale Größe der aktiven Protokolldatei in Bytes vor der Rotation (positive Ganzzahl; Standard: `104857600` = 100 MB). OpenClaw behält bis zu fünf nummerierte Archive neben der aktiven Datei.
- `redactSensitive` / `redactPatterns`: Best-Effort-Maskierung für Konsolenausgabe, Datei-Logs, OTLP-Log-Datensätze und persistierten Sitzungstranskripttext. `redactSensitive: "off"` deaktiviert nur diese allgemeine Log-/Transkript-Richtlinie; UI-/Tool-/Diagnose-Sicherheitsflächen schwärzen Geheimnisse weiterhin vor der Ausgabe.
- `maxFileBytes`: maximale Größe der aktiven Protokolldatei in Byte vor der Rotation (positive Ganzzahl; Standard: `104857600` = 100 MB). OpenClaw behält bis zu fünf nummerierte Archive neben der aktiven Datei.
- `redactSensitive` / `redactPatterns`: Best-Effort-Maskierung für Konsolenausgabe, Datei-Protokolle, OTLP-Protokolldatensätze und persistierten Sitzungstranskripttext. `redactSensitive: "off"` deaktiviert nur diese allgemeine Protokoll-/Transkript-Richtlinie; UI-/Tool-/Diagnose-Sicherheitsflächen schwärzen Geheimnisse weiterhin vor der Ausgabe.
---
@ -955,29 +923,29 @@ Hinweise:
}
```
- `enabled`: globaler Hauptschalter für Instrumentierungsausgabe (Standard: `true`).
- `flags`: Array von Flag-Strings, die gezielte Log-Ausgabe aktivieren (unterstützt Wildcards wie `"telegram.*"` oder `"*"`).
- `stuckSessionWarnMs`: Altersgrenze ohne Fortschritt in ms, um lang laufende Verarbeitungssitzungen als `session.long_running`, `session.stalled` oder `session.stuck` zu klassifizieren. Antwort, Tool, Status, Block und ACP-Fortschritt setzen den Timer zurück; wiederholte `session.stuck`-Diagnosen verwenden Backoff, solange sich nichts ändert.
- `enabled`: Hauptschalter für Instrumentierungsausgabe (Standard: `true`).
- `flags`: Array von Flag-Strings, die gezielte Protokollausgabe aktivieren (unterstützt Platzhalter wie `"telegram.*"` oder `"*"`).
- `stuckSessionWarnMs`: Schwellenwert für Alter ohne Fortschritt in ms, um lang laufende Verarbeitungssitzungen als `session.long_running`, `session.stalled` oder `session.stuck` zu klassifizieren. Antwort-, Tool-, Status-, Block- und ACP-Fortschritt setzen den Timer zurück; wiederholte `session.stuck`-Diagnosen wenden Backoff an, solange sie unverändert bleiben.
- `otel.enabled`: aktiviert die OpenTelemetry-Export-Pipeline (Standard: `false`). Die vollständige Konfiguration, den Signalkatalog und das Datenschutzmodell finden Sie unter [OpenTelemetry-Export](/de/gateway/opentelemetry).
- `otel.endpoint`: Collector-URL für OTel-Export.
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: optionale signalspezifische OTLP-Endpunkte. Wenn gesetzt, überschreiben sie `otel.endpoint` nur für dieses Signal.
- `otel.protocol`: `"http/protobuf"` (Standard) oder `"grpc"`.
- `otel.headers`: zusätzliche HTTP-/gRPC-Metadaten-Header, die mit OTel-Exportanfragen gesendet werden.
- `otel.headers`: zusätzliche HTTP-/gRPC-Metadaten-Header, die mit OTel-Exportanforderungen gesendet werden.
- `otel.serviceName`: Dienstname für Ressourcenattribute.
- `otel.traces` / `otel.metrics` / `otel.logs`: Trace-, Metrik- oder Log-Export aktivieren.
- `otel.sampleRate`: Trace-Sampling-Rate `0`–`1`.
- `otel.traces` / `otel.metrics` / `otel.logs`: aktiviert Trace-, Metrik- oder Protokollexport.
- `otel.sampleRate`: Trace-Samplingrate `0`–`1`.
- `otel.flushIntervalMs`: periodisches Telemetrie-Flush-Intervall in ms.
- `otel.captureContent`: Opt-in-Erfassung von Rohinhalten für OTEL-Span-Attribute. Standardmäßig deaktiviert. Boolesches `true` erfasst Nicht-System-Nachrichten-/Tool-Inhalte; die Objektform ermöglicht Ihnen, `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` und `systemPrompt` explizit zu aktivieren.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: Umgebungsschalter für die neuesten experimentellen GenAI-Span-Provider-Attribute. Standardmäßig behalten Spans aus Kompatibilitätsgründen das Legacy-Attribut `gen_ai.system`; GenAI-Metriken verwenden begrenzte semantische Attribute.
- `OPENCLAW_OTEL_PRELOADED=1`: Umgebungsschalter für Hosts, die bereits ein globales OpenTelemetry-SDK registriert haben. OpenClaw überspringt dann das Starten/Herunterfahren des Plugin-eigenen SDK, während Diagnose-Listener aktiv bleiben.
- `otel.captureContent`: Opt-in-Erfassung von Rohinhalten für OTEL-Span-Attribute. Standardmäßig deaktiviert. Boolesch `true` erfasst Nicht-System-Nachrichten-/Tool-Inhalte; die Objektform lässt Sie `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` und `systemPrompt` explizit aktivieren.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: Umgebungsumschalter für die neuesten experimentellen GenAI-Span-Provider-Attribute. Standardmäßig behalten Spans aus Kompatibilitätsgründen das Legacy-Attribut `gen_ai.system`; GenAI-Metriken verwenden begrenzte semantische Attribute.
- `OPENCLAW_OTEL_PRELOADED=1`: Umgebungsumschalter für Hosts, die bereits ein globales OpenTelemetry-SDK registriert haben. OpenClaw überspringt dann den Plugin-eigenen SDK-Start/-Stopp, während Diagnose-Listener aktiv bleiben.
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` und `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: signalspezifische Endpunkt-Umgebungsvariablen, die verwendet werden, wenn der passende Konfigurationsschlüssel nicht gesetzt ist.
- `cacheTrace.enabled`: Cache-Trace-Snapshots für eingebettete Läufe protokollieren (Standard: `false`).
- `cacheTrace.enabled`: Cache-Trace-Snapshots für eingebettete Ausführungen protokollieren (Standard: `false`).
- `cacheTrace.filePath`: Ausgabepfad für Cache-Trace-JSONL (Standard: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: steuern, was in der Cache-Trace-Ausgabe enthalten ist (alle Standard: `true`).
---
## Aktualisierung
## Update
```json5
{
@ -995,12 +963,12 @@ Hinweise:
}
```
- `channel`: Release-Kanal für npm-/Git-Installationen — `"stable"`, `"beta"` oder `"dev"`.
- `checkOnStart`: beim Start des Gateway auf npm-Aktualisierungen prüfen (Standard: `true`).
- `channel`: Release-Kanal für npm-/git-Installationen — `"stable"`, `"beta"` oder `"dev"`.
- `checkOnStart`: beim Start des Gateway nach npm-Updates suchen (Standard: `true`).
- `auto.enabled`: automatische Hintergrundaktualisierung für Paketinstallationen aktivieren (Standard: `false`).
- `auto.stableDelayHours`: Mindestverzögerung in Stunden vor der automatischen Anwendung im Stable-Kanal (Standard: `6`; max.: `168`).
- `auto.stableJitterHours`: zusätzliches Rollout-Verteilungsfenster im Stable-Kanal in Stunden (Standard: `12`; max.: `168`).
- `auto.betaCheckIntervalHours`: Häufigkeit der Prüfungen im Beta-Kanal in Stunden (Standard: `1`; max.: `24`).
- `auto.stableDelayHours`: minimale Verzögerung in Stunden vor automatischer Anwendung im Stable-Kanal (Standard: `6`; max.: `168`).
- `auto.stableJitterHours`: zusätzliches Rollout-Streuungsfenster im Stable-Kanal in Stunden (Standard: `12`; max.: `168`).
- `auto.betaCheckIntervalHours`: wie oft Prüfungen im Beta-Kanal in Stunden ausgeführt werden (Standard: `1`; max.: `24`).
---
@ -1033,19 +1001,19 @@ Hinweise:
}
```
- `enabled`: globales ACP-Feature-Gate (Standard: `true`; setzen Sie `false`, um ACP-Dispatch und Spawn-Bedienelemente auszublenden).
- `dispatch.enabled`: unabhängiges Gate für ACP-Sitzungs-Turn-Dispatch (Standard: `true`). Setzen Sie `false`, um ACP-Befehle verfügbar zu halten, aber die Ausführung zu blockieren.
- `backend`: Standard-ID des ACP-Runtime-Backends (muss mit einem registrierten ACP-Runtime-Plugin übereinstimmen).
Installieren Sie zuerst das Backend-Plugin, und wenn `plugins.allow` gesetzt ist, nehmen Sie die Backend-Plugin-ID (zum Beispiel `acpx`) auf, sonst wird das ACP-Backend nicht geladen.
- `enabled`: globales ACP-Feature-Gate (Standard: `true`; auf `false` setzen, um ACP-Dispatch- und Spawn-Bedienelemente auszublenden).
- `dispatch.enabled`: unabhängiges Gate für ACP-Sitzungs-Turn-Dispatch (Standard: `true`). Auf `false` setzen, um ACP-Befehle verfügbar zu halten, während die Ausführung blockiert wird.
- `backend`: Standard-ACP-Runtime-Backend-ID (muss zu einem registrierten ACP-Runtime-Plugin passen).
Installieren Sie zuerst das Backend-Plugin, und falls `plugins.allow` gesetzt ist, nehmen Sie die Backend-Plugin-ID (zum Beispiel `acpx`) auf, sonst wird das ACP-Backend nicht geladen.
- `defaultAgent`: Fallback-ACP-Ziel-Agent-ID, wenn Spawns kein explizites Ziel angeben.
- `allowedAgents`: Allowlist von Agent-IDs, die für ACP-Runtime-Sitzungen zulässig sind; leer bedeutet keine zusätzliche Einschränkung.
- `maxConcurrentSessions`: maximale Anzahl gleichzeitig aktiver ACP-Sitzungen.
- `stream.coalesceIdleMs`: Leerlauf-Flush-Fenster in ms für gestreamten Text.
- `stream.maxChunkChars`: maximale Chunk-Größe vor dem Aufteilen der gestreamten Block-Projektion.
- `stream.maxChunkChars`: maximale Chunk-Größe vor dem Aufteilen der gestreamten Blockprojektion.
- `stream.repeatSuppression`: wiederholte Status-/Tool-Zeilen pro Turn unterdrücken (Standard: `true`).
- `stream.deliveryMode`: `"live"` streamt inkrementell; `"final_only"` puffert bis zu terminalen Turn-Ereignissen.
- `stream.hiddenBoundarySeparator`: Trennzeichen vor sichtbarem Text nach versteckten Tool-Ereignissen (Standard: `"paragraph"`).
- `stream.maxOutputChars`: maximale Zeichenanzahl der Assistant-Ausgabe, die pro ACP-Turn projiziert wird.
- `stream.hiddenBoundarySeparator`: Trennzeichen vor sichtbarem Text nach ausgeblendeten Tool-Ereignissen (Standard: `"paragraph"`).
- `stream.maxOutputChars`: maximale Anzahl von Ausgabezeichen des Assistant, die pro ACP-Turn projiziert werden.
- `stream.maxSessionUpdateChars`: maximale Zeichenanzahl für projizierte ACP-Status-/Aktualisierungszeilen.
- `stream.tagVisibility`: Datensatz von Tag-Namen zu booleschen Sichtbarkeitsüberschreibungen für gestreamte Ereignisse.
- `runtime.ttlMinutes`: Leerlauf-TTL in Minuten für ACP-Sitzungs-Worker vor möglicher Bereinigung.
@ -1065,10 +1033,10 @@ Hinweise:
}
```
- `cli.banner.taglineMode` steuert den Stil der Banner-Tagline:
- `"random"` (Standard): rotierende witzige/saisonale Taglines.
- `cli.banner.taglineMode` steuert den Banner-Tagline-Stil:
- `"random"` (Standard): rotierende lustige/saisonale Taglines.
- `"default"`: feste neutrale Tagline (`All your chats, one OpenClaw.`).
- `"off"`: kein Tagline-Text (Banner-Titel/-Version werden weiterhin angezeigt).
- `"off"`: kein Tagline-Text (Banner-Titel/-Version wird weiterhin angezeigt).
- Um das gesamte Banner auszublenden (nicht nur Taglines), setzen Sie die Umgebungsvariable `OPENCLAW_HIDE_BANNER=1`.
---
@ -1093,13 +1061,13 @@ Metadaten, die von geführten CLI-Einrichtungsabläufen (`onboard`, `configure`,
## Identität
Siehe `agents.list`-Identitätsfelder unter [Agent-Standards](/de/gateway/config-agents#agent-defaults).
Siehe `agents.list`-Identitätsfelder unter [Agent-Standardeinstellungen](/de/gateway/config-agents#agent-defaults).
---
## Bridge (Legacy, entfernt)
Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über das Gateway-WebSocket. `bridge.*`-Schlüssel sind nicht mehr Teil des Konfigurationsschemas (Validierung schlägt fehl, bis sie entfernt wurden; `openclaw doctor --fix` kann unbekannte Schlüssel entfernen).
Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über den Gateway WebSocket. `bridge.*`-Schlüssel sind nicht mehr Teil des Konfigurationsschemas (Validierung schlägt fehl, bis sie entfernt sind; `openclaw doctor --fix` kann unbekannte Schlüssel entfernen).
<Accordion title="Legacy-Bridge-Konfiguration (historische Referenz)">
@ -1139,9 +1107,9 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über
}
```
- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Laufsitzungen vor dem Entfernen aus `sessions.json` aufbewahrt werden. Steuert außerdem die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; setzen Sie `false`, um dies zu deaktivieren.
- `runLog.maxBytes`: maximale Größe pro Laufprotokolldatei (`cron/runs/<jobId>.jsonl`) vor dem Beschneiden. Standard: `2_000_000` Bytes.
- `runLog.keepLines`: neueste Zeilen, die beibehalten werden, wenn das Beschneiden des Laufprotokolls ausgelöst wird. Standard: `2000`.
- `sessionRetention`: wie lange abgeschlossene isolierte Cron-Ausführungssitzungen vor dem Entfernen aus `sessions.json` aufbewahrt werden. Steuert auch die Bereinigung archivierter gelöschter Cron-Transkripte. Standard: `24h`; auf `false` setzen, um zu deaktivieren.
- `runLog.maxBytes`: maximale Größe pro Ausführungsprotokolldatei (`cron/runs/<jobId>.jsonl`) vor dem Bereinigen. Standard: `2_000_000` Byte.
- `runLog.keepLines`: neueste Zeilen, die beibehalten werden, wenn die Ausführungsprotokoll-Bereinigung ausgelöst wird. Standard: `2000`.
- `webhookToken`: Bearer-Token, der für Cron-Webhook-POST-Zustellung (`delivery.mode = "webhook"`) verwendet wird; wenn weggelassen, wird kein Auth-Header gesendet.
- `webhook`: veraltete Legacy-Fallback-Webhook-URL (http/https), die nur für gespeicherte Jobs verwendet wird, die noch `notify: true` haben.
@ -1159,7 +1127,7 @@ Aktuelle Builds enthalten die TCP-Bridge nicht mehr. Nodes verbinden sich über
}
```
- `maxAttempts`: maximale Anzahl von Wiederholungen für Einmaljobs bei vorübergehenden Fehlern (Standard: `3`; Bereich: `0`–`10`).
- `maxAttempts`: maximale Anzahl von Wiederholungen für einmalige Jobs bei vorübergehenden Fehlern (Standard: `3`; Bereich: `0`–`10`).
- `backoffMs`: Array von Backoff-Verzögerungen in ms für jeden Wiederholungsversuch (Standard: `[30000, 60000, 300000]`; 1–10 Einträge).
- `retryOn`: Fehlertypen, die Wiederholungen auslösen — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Weglassen, um alle vorübergehenden Typen zu wiederholen.
@ -1182,12 +1150,12 @@ Gilt nur für einmalige Cron-Jobs. Wiederkehrende Jobs verwenden eine separate F
}
```
- `enabled`: Fehlerwarnungen für Cron-Jobs aktivieren (Standard: `false`).
- `after`: aufeinanderfolgende Fehler, bevor eine Warnung ausgelöst wird (positive Ganzzahl, Min.: `1`).
- `cooldownMs`: Mindestanzahl von Millisekunden zwischen wiederholten Warnungen für denselben Job (nicht negative Ganzzahl).
- `includeSkipped`: aufeinanderfolgend übersprungene Ausführungen auf den Warnungsschwellenwert anrechnen (Standard: `false`). Übersprungene Ausführungen werden separat nachverfolgt und wirken sich nicht auf den Backoff bei Ausführungsfehlern aus.
- `mode`: Zustellmodus — `"announce"` sendet über eine Kanalnachricht; `"webhook"` postet an den konfigurierten Webhook.
- `accountId`: optionale Konto- oder Kanal-ID, um die Warnungszustellung einzugrenzen.
- `enabled`: Fehlerbenachrichtigungen für Cron-Jobs aktivieren (Standard: `false`).
- `after`: aufeinanderfolgende Fehler, bevor eine Benachrichtigung ausgelöst wird (positive Ganzzahl, min.: `1`).
- `cooldownMs`: minimale Millisekunden zwischen wiederholten Benachrichtigungen für denselben Job (nicht negative Ganzzahl).
- `includeSkipped`: aufeinanderfolgende übersprungene Ausführungen auf den Benachrichtigungsschwellenwert anrechnen (Standard: `false`). Übersprungene Ausführungen werden separat nachverfolgt und beeinflussen den Backoff bei Ausführungsfehlern nicht.
- `mode`: Zustellmodus — `"announce"` sendet über eine Kanalnachricht; `"webhook"` sendet an den konfigurierten Webhook.
- `accountId`: optionale Konto- oder Kanal-ID zur Eingrenzung der Benachrichtigungszustellung.
### `cron.failureDestination`
@ -1205,12 +1173,12 @@ Gilt nur für einmalige Cron-Jobs. Wiederkehrende Jobs verwenden eine separate F
```
- Standardziel für Cron-Fehlerbenachrichtigungen über alle Jobs hinweg.
- `mode`: `"announce"` oder `"webhook"`; fällt standardmäßig auf `"announce"` zurück, wenn genügend Zieldaten vorhanden sind.
- `channel`: Kanalüberschreibung für die Zustellung per Announcement. `"last"` verwendet den letzten bekannten Zustellungskanal erneut.
- `to`: explizites Announcement-Ziel oder Webhook-URL. Erforderlich für den Webhook-Modus.
- `mode`: `"announce"` oder `"webhook"`; standardmäßig `"announce"`, wenn genügend Zieldaten vorhanden sind.
- `channel`: Kanalüberschreibung für die Zustellung per Announce. `"last"` verwendet den zuletzt bekannten Zustellungskanal wieder.
- `to`: explizites Announce-Ziel oder Webhook-URL. Für den Webhook-Modus erforderlich.
- `accountId`: optionale Kontoüberschreibung für die Zustellung.
- `delivery.failureDestination` pro Job überschreibt diesen globalen Standard.
- Wenn weder ein globales noch ein jobspezifisches Fehlerziel festgelegt ist, fallen Jobs, die bereits per `announce` zustellen, bei einem Fehler auf dieses primäre Announcement-Ziel zurück.
- Pro Job überschreibt `delivery.failureDestination` diesen globalen Standard.
- Wenn weder ein globales noch ein jobspezifisches Fehlerziel festgelegt ist, fallen Jobs, die bereits über `announce` zustellen, bei Fehlern auf dieses primäre Announce-Ziel zurück.
- `delivery.failureDestination` wird nur für Jobs mit `sessionTarget="isolated"` unterstützt, es sei denn, der primäre `delivery.mode` des Jobs ist `"webhook"`.
Siehe [Cron-Jobs](/de/automation/cron-jobs). Isolierte Cron-Ausführungen werden als [Hintergrundaufgaben](/de/automation/tasks) nachverfolgt.
@ -1231,24 +1199,24 @@ Template-Platzhalter, die in `tools.media.models[].args` erweitert werden:
| `{{MessageSid}}` | Kanalnachrichten-ID |
| `{{SessionId}}` | Aktuelle Sitzungs-UUID |
| `{{IsNewSession}}` | `"true"`, wenn eine neue Sitzung erstellt wurde |
| `{{MediaUrl}}` | Eingehende Medien-Pseudo-URL |
| `{{MediaUrl}}` | Pseudo-URL für eingehende Medien |
| `{{MediaPath}}` | Lokaler Medienpfad |
| `{{MediaType}}` | Medientyp (Bild/Audio/Dokument/…) |
| `{{Transcript}}` | Audio-Transkript |
| `{{Transcript}}` | Audiotranskript |
| `{{Prompt}}` | Aufgelöster Medien-Prompt für CLI-Einträge |
| `{{MaxChars}}` | Aufgelöste maximale Ausgabezeichen für CLI-Einträge |
| `{{ChatType}}` | `"direct"` oder `"group"` |
| `{{GroupSubject}}` | Gruppenbetreff (bestmöglich) |
| `{{GroupMembers}}` | Vorschau der Gruppenmitglieder (bestmöglich) |
| `{{SenderName}}` | Anzeigename des Absenders (bestmöglich) |
| `{{SenderE164}}` | Telefonnummer des Absenders (bestmöglich) |
| `{{GroupSubject}}` | Gruppenbetreff (nach bestem Aufwand) |
| `{{GroupMembers}}` | Vorschau der Gruppenmitglieder (nach bestem Aufwand) |
| `{{SenderName}}` | Anzeigename des Absenders (nach bestem Aufwand) |
| `{{SenderE164}}` | Telefonnummer des Absenders (nach bestem Aufwand) |
| `{{Provider}}` | Provider-Hinweis (whatsapp, telegram, discord usw.) |
---
## Konfigurations-Includes (`$include`)
Konfiguration auf mehrere Dateien aufteilen:
Konfiguration in mehrere Dateien aufteilen:
```json5
// ~/.openclaw/openclaw.json
@ -1265,11 +1233,11 @@ Konfiguration auf mehrere Dateien aufteilen:
- Einzelne Datei: ersetzt das enthaltende Objekt.
- Array von Dateien: wird der Reihe nach tief zusammengeführt (spätere überschreiben frühere).
- Geschwisterschlüssel: werden nach Includes zusammengeführt (überschreiben eingeschlossene Werte).
- Geschwisterschlüssel: werden nach Includes zusammengeführt (überschreiben eingebundene Werte).
- Verschachtelte Includes: bis zu 10 Ebenen tief.
- Pfade: werden relativ zur einschließenden Datei aufgelöst, müssen aber innerhalb des obersten Konfigurationsverzeichnisses bleiben (`dirname` von `openclaw.json`). Absolute/`../`-Formen sind nur zulässig, wenn sie weiterhin innerhalb dieser Grenze aufgelöst werden.
- Schreibvorgänge von OpenClaw, die nur einen obersten Abschnitt ändern, der durch ein Single-File-Include gesichert ist, schreiben in diese eingeschlossene Datei durch. Beispielsweise aktualisiert `plugins install` `plugins: { $include: "./plugins.json5" }` in `plugins.json5` und lässt `openclaw.json` unverändert.
- Root-Includes, Include-Arrays und Includes mit Geschwisterüberschreibungen sind für Schreibvorgänge von OpenClaw schreibgeschützt; diese Schreibvorgänge schlagen geschlossen fehl, anstatt die Konfiguration zu flatten.
- Pfade: werden relativ zur einbindenden Datei aufgelöst, müssen aber innerhalb des obersten Konfigurationsverzeichnisses bleiben (`dirname` von `openclaw.json`). Absolute/`../`-Formen sind nur erlaubt, wenn sie weiterhin innerhalb dieser Grenze aufgelöst werden.
- OpenClaw-eigene Schreibvorgänge, die nur einen obersten Abschnitt ändern, der durch ein Einzeldatei-Include hinterlegt ist, schreiben direkt in diese eingebundene Datei. Beispielsweise aktualisiert `plugins install` `plugins: { $include: "./plugins.json5" }` in `plugins.json5` und lässt `openclaw.json` unverändert.
- Root-Includes, Include-Arrays und Includes mit Geschwisterüberschreibungen sind für OpenClaw-eigene Schreibvorgänge schreibgeschützt; diese Schreibvorgänge schlagen geschlossen fehl, anstatt die Konfiguration zu reduzieren.
- Fehler: klare Meldungen für fehlende Dateien, Parse-Fehler und zirkuläre Includes.
---

199
docs/de/gateway/diagnostics.md
View File

@ -1,27 +1,26 @@
---
read_when:
- Fehlerbericht oder Supportanfrage vorbereiten
- Debugging von Gateway-Abstürzen, Neustarts, Speicherdruck oder übergroßen Payloads
- Einen Fehlerbericht oder eine Supportanfrage vorbereiten
- Fehlerbehebung bei Gateway-Abstürzen, Neustarts, Speicherdruck oder übermäßig großen Nutzlasten
- Überprüfen, welche Diagnosedaten aufgezeichnet oder geschwärzt werden
summary: Teilbare Gateway-Diagnosepakete für Fehlerberichte erstellen
title: Diagnoseexport
x-i18n:
generated_at: "2026-05-03T21:32:12Z"
generated_at: "2026-05-05T01:46:07Z"
model: gpt-5.5
provider: openai
source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b
source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382
source_path: gateway/diagnostics.md
workflow: 16
---
OpenClaw kann eine lokale Diagnose-ZIP für Fehlerberichte erstellen. Sie kombiniert
bereinigten Gateway-Status, Health-Informationen, Logs, Konfigurationsstruktur
und aktuelle stabilitätsbezogene Ereignisse ohne Payloads.
OpenClaw kann eine lokale Diagnose-ZIP-Datei für Fehlerberichte erstellen. Sie kombiniert
bereinigten Gateway-Status, Zustand, Logs, Konfigurationsform und aktuelle Stabilitätsereignisse
ohne Payloads.
Behandeln Sie Diagnosepakete wie Geheimnisse, bis Sie sie geprüft haben. Sie sind
darauf ausgelegt, Payloads und Zugangsdaten auszulassen oder zu schwärzen, aber
sie fassen dennoch lokale Gateway-Logs und den Laufzeitstatus auf Host-Ebene
zusammen.
Behandeln Sie Diagnose-Bundles wie Geheimnisse, bis Sie sie geprüft haben. Sie sind
dafür ausgelegt, Payloads und Zugangsdaten auszulassen oder zu schwärzen, fassen aber
dennoch lokale Gateway-Logs und den Laufzeitzustand auf Host-Ebene zusammen.
## Schnellstart
@ -29,8 +28,7 @@ zusammen.
openclaw gateway diagnostics export
```
Der Befehl gibt den Pfad der geschriebenen ZIP-Datei aus. Um einen Pfad
auszuwählen:
Der Befehl gibt den geschriebenen ZIP-Pfad aus. So wählen Sie einen Pfad:
```bash
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
@ -44,47 +42,40 @@ openclaw gateway diagnostics export --json
## Chat-Befehl
Owner können `/diagnostics [note]` im Chat verwenden, um einen lokalen
Gateway-Export anzufordern. Verwenden Sie dies, wenn der Fehler in einer echten
Unterhaltung aufgetreten ist und Sie einen kopierbaren Bericht für den Support
möchten:
Besitzer können im Chat `/diagnostics [note]` verwenden, um einen lokalen Gateway-Export
anzufordern. Verwenden Sie dies, wenn der Fehler in einer echten Unterhaltung aufgetreten ist
und Sie einen Bericht für den Support benötigen, den Sie direkt kopieren und einfügen können:
1. Senden Sie `/diagnostics` in der Unterhaltung, in der Ihnen das Problem
aufgefallen ist. Fügen Sie eine kurze Notiz hinzu, wenn sie hilft, zum
Beispiel `/diagnostics bad tool choice`.
2. OpenClaw sendet die Diagnose-Einleitung und fordert eine explizite
Exec-Freigabe an. Die Freigabe führt `openclaw gateway diagnostics export --json`
aus. Genehmigen Sie Diagnosen nicht über eine Allow-all-Regel.
3. Nach der Freigabe antwortet OpenClaw mit einem einfügbaren Bericht, der den
lokalen Paketpfad, eine Manifest-Zusammenfassung, Datenschutzhinweise und
relevante Sitzungs-IDs enthält.
1. Senden Sie `/diagnostics` in der Unterhaltung, in der Sie das Problem bemerkt haben. Fügen Sie
eine kurze Notiz hinzu, wenn sie hilfreich ist, zum Beispiel `/diagnostics bad tool choice`.
2. OpenClaw sendet die Diagnose-Präambel und fordert eine explizite Exec-Genehmigung an.
Die Genehmigung führt `openclaw gateway diagnostics export --json` aus.
Genehmigen Sie Diagnosen nicht über eine Allow-all-Regel.
3. Nach der Genehmigung antwortet OpenClaw mit einem einfügbaren Bericht, der den lokalen
Bundle-Pfad, eine Manifest-Zusammenfassung, Datenschutzhinweise und relevante Sitzungs-IDs enthält.
In Gruppenchats kann ein Owner weiterhin `/diagnostics` ausführen, aber OpenClaw
postet die Diagnosedetails nicht zurück in den gemeinsamen Chat. Es sendet die
Einleitung, Freigabeaufforderungen, das Gateway-Exportergebnis und die
Aufschlüsselung der Codex-Sitzung/des Threads über die private Freigaberoute an
den Owner. Die Gruppe erhält nur einen kurzen Hinweis, dass der Diagnoseablauf
privat gesendet wurde. Wenn OpenClaw keine private Owner-Route finden kann,
schlägt der Befehl geschlossen fehl und fordert den Owner auf, ihn aus einer DM
In Gruppenchats kann ein Besitzer weiterhin `/diagnostics` ausführen, aber OpenClaw veröffentlicht
die Diagnosedetails nicht im gemeinsamen Chat. Es sendet die Präambel,
Genehmigungsaufforderungen, das Gateway-Exportergebnis und die Codex-Sitzungs-/Thread-Aufschlüsselung
über die private Genehmigungsroute an den Besitzer. Die Gruppe erhält nur einen kurzen Hinweis,
dass der Diagnoseablauf privat gesendet wurde. Wenn OpenClaw keine private Route zum Besitzer
finden kann, schlägt der Befehl geschlossen fehl und fordert den Besitzer auf, ihn aus einer DM
auszuführen.
Wenn die aktive OpenClaw-Sitzung das native OpenAI Codex-Harness verwendet,
deckt dieselbe Exec-Freigabe auch einen OpenAI-Feedback-Upload für die
Codex-Laufzeit-Threads ab, die OpenClaw kennt. Dieser Upload ist vom lokalen
Gateway-ZIP getrennt und erscheint nur für Codex-Harness-Sitzungen. Vor der
Freigabe erklärt die Aufforderung, dass die Genehmigung von Diagnosen auch
Codex-Feedback sendet, listet aber keine Codex-Sitzungs- oder Thread-IDs auf.
Nach der Freigabe listet die Chat-Antwort die Kanäle, OpenClaw-Sitzungs-IDs,
Codex-Thread-IDs und lokalen Resume-Befehle für die Threads auf, die an
OpenAI-Server gesendet wurden. Wenn Sie die Freigabe ablehnen oder ignorieren,
führt OpenClaw den Export nicht aus, sendet kein Codex-Feedback und gibt die
Codex-IDs nicht aus.
Wenn die aktive OpenClaw-Sitzung das native OpenAI-Codex-Harness verwendet,
deckt dieselbe Exec-Genehmigung auch einen OpenAI-Feedback-Upload für die Codex-Laufzeit-Threads ab,
die OpenClaw kennt. Dieser Upload ist vom lokalen Gateway-ZIP getrennt und erscheint nur
für Codex-Harness-Sitzungen. Vor der Genehmigung erklärt die Aufforderung, dass die Genehmigung
der Diagnosen auch Codex-Feedback sendet, listet aber keine Codex-Sitzungs- oder Thread-IDs auf.
Nach der Genehmigung listet die Chat-Antwort die Kanäle, OpenClaw-Sitzungs-IDs,
Codex-Thread-IDs und lokalen Resume-Befehle für die Threads auf, die an OpenAI-Server gesendet wurden.
Wenn Sie die Genehmigung ablehnen oder ignorieren, führt OpenClaw den Export nicht aus,
sendet kein Codex-Feedback und gibt die Codex-IDs nicht aus.
Dadurch wird der übliche Codex-Debugging-Ablauf kurz: Auffälliges Verhalten in
Telegram, Discord oder einem anderen Kanal bemerken, `/diagnostics` ausführen,
einmal freigeben, den Bericht mit dem Support teilen und anschließend den
ausgegebenen Befehl `codex resume <thread-id>` lokal ausführen, wenn Sie den
nativen Codex-Thread selbst prüfen möchten. Siehe
Damit ist die übliche Codex-Debugging-Schleife kurz: Bemerken Sie das fehlerhafte Verhalten in
Telegram, Discord oder einem anderen Kanal, führen Sie `/diagnostics` aus, genehmigen Sie einmal,
teilen Sie den Bericht mit dem Support und führen Sie dann lokal den ausgegebenen Befehl
`codex resume <thread-id>` aus, wenn Sie den nativen Codex-Thread selbst prüfen möchten. Siehe
[Codex-Harness](/de/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) für
diesen Prüfablauf.
@ -93,58 +84,61 @@ diesen Prüfablauf.
Die ZIP-Datei enthält:
- `summary.md`: menschenlesbare Übersicht für den Support.
- `diagnostics.json`: maschinenlesbare Zusammenfassung von Konfiguration, Logs,
Status, Health-Informationen und Stabilitätsdaten.
- `manifest.json`: Export-Metadaten und Dateiliste.
- Bereinigte Konfigurationsstruktur und nicht geheime Konfigurationsdetails.
- `diagnostics.json`: maschinenlesbare Zusammenfassung von Konfiguration, Logs, Status, Zustand
und Stabilitätsdaten.
- `manifest.json`: Exportmetadaten und Dateiliste.
- Bereinigte Konfigurationsform und nicht geheime Konfigurationsdetails.
- Bereinigte Log-Zusammenfassungen und aktuelle geschwärzte Log-Zeilen.
- Best-Effort-Snapshots von Gateway-Status und Health-Informationen.
- `stability/latest.json`: neuestes persistiertes Stabilitätspaket, sofern verfügbar.
- Bestmögliche Gateway-Status- und Zustand-Snapshots.
- `stability/latest.json`: neuestes persistiertes Stabilitäts-Bundle, sofern verfügbar.
Der Export ist auch dann nützlich, wenn der Gateway fehlerhaft ist. Wenn der
Gateway keine Status- oder Health-Anfragen beantworten kann, werden die lokalen
Logs, die Konfigurationsstruktur und das neueste Stabilitätspaket dennoch
gesammelt, sofern verfügbar.
Der Export ist auch nützlich, wenn der Gateway fehlerhaft ist. Wenn der Gateway
Status- oder Zustandsanfragen nicht beantworten kann, werden lokale Logs, Konfigurationsform
und das neueste Stabilitäts-Bundle dennoch erfasst, sofern verfügbar.
## Datenschutzmodell
Diagnosen sind so gestaltet, dass sie geteilt werden können. Der Export behält
Betriebsdaten, die beim Debugging helfen, zum Beispiel:
Diagnosen sind so ausgelegt, dass sie geteilt werden können. Der Export behält Betriebsdaten bei,
die beim Debugging helfen, zum Beispiel:
- Subsystemnamen, Plugin-IDs, Provider-IDs, Kanal-IDs und konfigurierte Modi
- Statuscodes, Dauern, Byte-Zähler, Warteschlangenstatus und Speichermesswerte
- bereinigte Log-Metadaten und geschwärzte betriebliche Meldungen
- Konfigurationsstruktur und nicht geheime Funktionseinstellungen
- Statuscodes, Dauerwerte, Byte-Zähler, Warteschlangenzustand und Speichermesswerte
- bereinigte Log-Metadaten und geschwärzte Betriebsmeldungen
- Konfigurationsform und nicht geheime Funktionseinstellungen
Der Export lässt Folgendes aus oder schwärzt es:
Der Export lässt aus oder schwärzt:
- Chattext, Prompts, Anweisungen, Webhook-Bodys und Tool-Ausgaben
- Chat-Text, Prompts, Anweisungen, Webhook-Bodies und Tool-Ausgaben
- Zugangsdaten, API-Schlüssel, Tokens, Cookies und geheime Werte
- rohe Request- oder Response-Bodys
- Rohdaten von Anfrage- oder Antwort-Bodies
- Konto-IDs, Nachrichten-IDs, rohe Sitzungs-IDs, Hostnamen und lokale Benutzernamen
Wenn eine Log-Meldung wie Benutzer-, Chat-, Prompt- oder Tool-Payload-Text wirkt,
behält der Export nur bei, dass eine Nachricht ausgelassen wurde, sowie die
Byte-Anzahl.
Wenn eine Log-Nachricht wie Benutzer-, Chat-, Prompt- oder Tool-Payload-Text aussieht, behält der
Export nur bei, dass eine Nachricht ausgelassen wurde, sowie die Byte-Anzahl.
## Stabilitätsrecorder
## Stabilitätsaufzeichnung
Der Gateway zeichnet standardmäßig einen begrenzten Stabilitätsstrom ohne
Payloads auf, wenn Diagnosen aktiviert sind. Er ist für betriebliche Fakten
gedacht, nicht für Inhalte.
Der Gateway zeichnet standardmäßig einen begrenzten, payloadfreien Stabilitätsstream auf, wenn
Diagnosen aktiviert sind. Er ist für betriebliche Fakten gedacht, nicht für Inhalte.
Derselbe Diagnose-Heartbeat zeichnet Liveness-Beispiele auf, wenn der Gateway
weiterläuft, aber die Node.js-Event-Loop oder CPU gesättigt wirkt. Diese
`diagnostic.liveness.warning`-Ereignisse enthalten Event-Loop-Verzögerung,
Event-Loop-Auslastung, CPU-Core-Verhältnis und die Anzahl aktiver/wartender/
eingereihter Sitzungen. Idle-Beispiele bleiben in der Telemetrie auf `info`-
Ebene. Liveness-Beispiele werden nur dann zu Gateway-Warnungen, wenn Arbeit
wartet oder eingereiht ist oder wenn aktive Arbeit mit anhaltender
Event-Loop-Verzögerung überlappt. Vorübergehende Max-Delay-Spitzen während
ansonsten gesunder Hintergrundarbeit bleiben in Debug-Logs. Sie starten den
Gateway nicht von selbst neu.
Derselbe Diagnose-Heartbeat zeichnet Liveness-Samples auf, wenn der Gateway weiterläuft,
aber die Node.js-Event-Loop oder CPU ausgelastet wirkt. Diese
`diagnostic.liveness.warning`-Ereignisse enthalten Event-Loop-Verzögerung, Event-Loop-Auslastung,
CPU-Core-Verhältnis, Anzahlen aktiver/wartender/eingereihter Sitzungen, die aktuelle
Start-/Laufzeitphase, sofern bekannt, aktuelle Phasenspannen und begrenzte aktive/eingereihte
Arbeitslabels. Leerlauf-Samples bleiben in der Telemetrie auf `info`-Ebene. Liveness-Samples
werden nur dann zu Gateway-Warnungen, wenn Arbeit wartet oder eingereiht ist oder wenn aktive Arbeit
mit anhaltender Event-Loop-Verzögerung überlappt. Vorübergehende Max-Delay-Spitzen während
ansonsten gesunder Hintergrundarbeit bleiben in Debug-Logs. Sie starten den Gateway nicht
eigenständig neu.
Den Live-Recorder prüfen:
Startphasen geben außerdem `diagnostic.phase.completed`-Ereignisse mit Wall-Clock- und
CPU-Timing aus. Diagnosen zu blockierten eingebetteten Läufen setzen `terminalProgressStale=true`,
wenn der letzte Bridge-Fortschritt terminal aussah, etwa ein rohes Response-Item oder
ein Response-Completion-Ereignis, der Gateway den eingebetteten Lauf aber weiterhin als
aktiv betrachtet.
Live-Aufzeichnung prüfen:
```bash
openclaw gateway stability
@ -152,21 +146,20 @@ openclaw gateway stability --type payload.large
openclaw gateway stability --json
```
Das neueste persistierte Stabilitätspaket nach einem fatalen Beenden, einem
Shutdown-Timeout oder einem Fehler beim Neustart prüfen:
Neuestes persistiertes Stabilitäts-Bundle nach einem fatalen Exit, Shutdown-Timeout
oder Fehler beim Neustart prüfen:
```bash
openclaw gateway stability --bundle latest
```
Eine Diagnose-ZIP aus dem neuesten persistierten Paket erstellen:
Eine Diagnose-ZIP aus dem neuesten persistierten Bundle erstellen:
```bash
openclaw gateway stability --bundle latest --export
```
Persistierte Pakete liegen unter `~/.openclaw/logs/stability/`, wenn Ereignisse
vorhanden sind.
Persistierte Bundles liegen unter `~/.openclaw/logs/stability/`, wenn Ereignisse vorhanden sind.
## Nützliche Optionen
@ -178,19 +171,19 @@ openclaw gateway diagnostics export \
```
- `--output <path>`: in einen bestimmten ZIP-Pfad schreiben.
- `--log-lines <count>`: maximale Anzahl bereinigter Log-Zeilen, die eingeschlossen werden.
- `--log-bytes <bytes>`: maximale Anzahl Log-Bytes, die geprüft werden.
- `--url <url>`: Gateway-WebSocket-URL für Status- und Health-Snapshots.
- `--token <token>`: Gateway-Token für Status- und Health-Snapshots.
- `--password <password>`: Gateway-Passwort für Status- und Health-Snapshots.
- `--timeout <ms>`: Timeout für Status- und Health-Snapshots.
- `--no-stability-bundle`: Suche nach persistiertem Stabilitätspaket überspringen.
- `--json`: maschinenlesbare Export-Metadaten ausgeben.
- `--log-lines <count>`: maximale Anzahl bereinigter Log-Zeilen, die aufgenommen werden.
- `--log-bytes <bytes>`: maximale Anzahl von Log-Bytes, die geprüft werden.
- `--url <url>`: Gateway-WebSocket-URL für Status- und Zustand-Snapshots.
- `--token <token>`: Gateway-Token für Status- und Zustand-Snapshots.
- `--password <password>`: Gateway-Passwort für Status- und Zustand-Snapshots.
- `--timeout <ms>`: Timeout für Status- und Zustand-Snapshots.
- `--no-stability-bundle`: Suche nach persistiertem Stabilitäts-Bundle überspringen.
- `--json`: maschinenlesbare Exportmetadaten ausgeben.
## Diagnosen deaktivieren
Diagnosen sind standardmäßig aktiviert. Um den Stabilitätsrecorder und die
Erfassung von Diagnoseereignissen zu deaktivieren:
Diagnosen sind standardmäßig aktiviert. So deaktivieren Sie die Stabilitätsaufzeichnung und
die Sammlung von Diagnoseereignissen:
```json5
{
@ -200,8 +193,8 @@ Erfassung von Diagnoseereignissen zu deaktivieren:
}
```
Das Deaktivieren von Diagnosen reduziert die Detailtiefe von Fehlerberichten. Es
wirkt sich nicht auf das normale Gateway-Logging aus.
Das Deaktivieren von Diagnosen reduziert die Details in Fehlerberichten. Es wirkt sich nicht
auf das normale Gateway-Logging aus.
## Verwandte Themen
@ -209,4 +202,4 @@ wirkt sich nicht auf das normale Gateway-Logging aus.
- [Gateway-CLI](/de/cli/gateway#gateway-diagnostics-export)
- [Gateway-Protokoll](/de/gateway/protocol#system-and-identity)
- [Logging](/de/logging)
- [OpenTelemetry-Export](/de/gateway/opentelemetry) — separater Ablauf zum Streamen von Diagnosedaten an einen Collector
- [OpenTelemetry-Export](/de/gateway/opentelemetry) — separater Ablauf zum Streamen von Diagnosen an einen Collector

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

@ -1,20 +1,20 @@
---
read_when:
- Doctor-Migrationen hinzufügen oder ändern
- Einführen nicht abwärtskompatibler Konfigurationsänderungen
- Einführen inkompatibler Konfigurationsänderungen
sidebarTitle: Doctor
summary: 'Doctor-Befehl: Integritätsprüfungen, Konfigurationsmigrationen und Reparaturschritte'
title: Diagnose
x-i18n:
generated_at: "2026-05-04T09:37:05Z"
generated_at: "2026-05-05T01:46:19Z"
model: gpt-5.5
provider: openai
source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` ist das Reparatur- und Migrationstool für OpenClaw. Es behebt veraltete Konfigurationen und Zustände, prüft den Zustand und bietet umsetzbare Reparaturschritte.
`openclaw doctor` ist das Reparatur- und Migrationstool für OpenClaw. Es behebt veraltete Konfigurationen/Zustände, prüft die Integrität und stellt umsetzbare Reparaturschritte bereit.
## Schnellstart
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Standardwerte ohne Nachfrage akzeptieren (einschließlich Neustart-, Dienst- und Sandbox-Reparaturschritten, sofern zutreffend).
Standardwerte ohne Rückfragen akzeptieren (einschließlich Neustart-/Dienst-/Sandbox-Reparaturschritten, sofern zutreffend).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
Empfohlene Reparaturen ohne Nachfrage anwenden (Reparaturen und Neustarts, wenn sicher).
Empfohlene Reparaturen ohne Rückfragen anwenden (Reparaturen und Neustarts, wo sicher).
</Tab>
<Tab title="--repair --force">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Ohne Eingabeaufforderungen ausführen und nur sichere Migrationen anwenden (Konfigurationsnormalisierung und Verschiebungen des Zustands auf dem Datenträger). Überspringt Neustart-, Dienst- und Sandbox-Aktionen, die eine menschliche Bestätigung erfordern. Legacy-Zustandsmigrationen werden automatisch ausgeführt, wenn sie erkannt werden.
Ohne Rückfragen ausführen und nur sichere Migrationen anwenden (Konfigurationsnormalisierung und Verschiebungen des Zustands auf Datenträger). Überspringt Neustart-/Dienst-/Sandbox-Aktionen, die menschliche Bestätigung erfordern. Migrationen von Legacy-Zuständen werden automatisch ausgeführt, wenn sie erkannt werden.
</Tab>
<Tab title="--deep">
@ -62,7 +62,7 @@ openclaw doctor
openclaw doctor --deep
```
Systemdienste nach zusätzlichen Gateway-Installationen durchsuchen (launchd/systemd/schtasks).
Systemdienste auf zusätzliche Gateway-Installationen prüfen (launchd/systemd/schtasks).
</Tab>
</Tabs>
@ -76,110 +76,112 @@ cat ~/.openclaw/openclaw.json
## Was es tut (Zusammenfassung)
<AccordionGroup>
<Accordion title="Zustand, UI und Updates">
<Accordion title="Integrität, UI und Updates">
- Optionales Preflight-Update für Git-Installationen (nur interaktiv).
- UI-Protokoll-Aktualitätsprüfung (erstellt die Control UI neu, wenn das Protokollschema neuer ist).
- Zustandsprüfung und Neustartabfrage.
- Skills-Statuszusammenfassung (geeignet/fehlend/blockiert) und Plugin-Status.
- Aktualitätsprüfung des UI-Protokolls (baut die Control UI neu, wenn das Protokollschema neuer ist).
- Integritätsprüfung und Neustartaufforderung.
- Skills-Statusübersicht (geeignet/fehlend/blockiert) und Plugin-Status.
</Accordion>
<Accordion title="Konfiguration und Migrationen">
- Konfigurationsnormalisierung für Legacy-Werte.
- Migration der Talk-Konfiguration von Legacy-Flachfeldern `talk.*` zu `talk.provider` + `talk.providers.<provider>`.
- Talk-Konfigurationsmigration von Legacy-Feldern im flachen Format `talk.*` nach `talk.provider` + `talk.providers.<provider>`.
- Browser-Migrationsprüfungen für Legacy-Konfigurationen der Chrome-Erweiterung und Chrome-MCP-Bereitschaft.
- Warnungen zu OpenCode-Provider-Overrides (`models.providers.opencode` / `models.providers.opencode-go`).
- Warnungen zu Codex-OAuth-Shadowing (`models.providers.openai-codex`).
- Prüfung der OAuth-TLS-Voraussetzungen für OpenAI-Codex-OAuth-Profile.
- Warnungen zur Plugin-/Tool-Zulassungsliste, wenn `plugins.allow` restriktiv ist, die Tool-Richtlinie aber weiterhin Wildcard- oder Plugin-eigene Tools anfordert.
- Legacy-Zustandsmigration auf dem Datenträger (Sitzungen/Agentenverzeichnis/WhatsApp-Authentifizierung).
- Migration von Legacy-Plugin-Manifestvertragsschlüsseln (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migration des Legacy-Cron-Speichers (`jobId`, `schedule.cron`, Felder für Zustellung/Payload auf oberster Ebene, Payload-`provider`, einfache `notify: true`-Webhook-Fallback-Jobs).
- Migration der Legacy-Agentenlaufzeitrichtlinie zu `agents.defaults.agentRuntime` und `agents.list[].agentRuntime`.
- Bereinigung veralteter Plugin-Konfigurationen, wenn Plugins aktiviert sind; wenn `plugins.enabled=false`, werden veraltete Plugin-Referenzen als inerte Containment-Konfiguration behandelt und beibehalten.
- Warnungen zur Plugin-/Tool-Allowlist, wenn `plugins.allow` restriktiv ist, die Tool-Richtlinie aber weiterhin Wildcards oder Plugin-eigene Tools anfordert.
- Migration von Legacy-Zuständen auf Datenträger (Sitzungen/Agent-Verzeichnis/WhatsApp-Auth).
- Migration von Legacy-Schlüsseln im Plugin-Manifestvertrag (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migration des Legacy-Cron-Speichers (`jobId`, `schedule.cron`, Felder auf oberster Ebene für Zustellung/Payload, Payload-`provider`, einfache `notify: true`-Webhook-Fallback-Jobs).
- Migration der Legacy-Agent-Laufzeitrichtlinie zu `agents.defaults.agentRuntime` und `agents.list[].agentRuntime`.
- Bereinigung veralteter Plugin-Konfigurationen, wenn Plugins aktiviert sind; wenn `plugins.enabled=false`, werden veraltete Plugin-Referenzen als inerte Eindämmungskonfiguration behandelt und beibehalten.
</Accordion>
<Accordion title="Zustand und Integrität">
- Prüfung von Sitzungs-Sperrdateien und Bereinigung veralteter Sperren.
- Reparatur von Sitzungstranskripten für duplizierte Prompt-Rewrite-Branches, die von betroffenen Builds vom 2026-04-24 erstellt wurden.
- Erkennung von Tombstones zur Neustart-Wiederherstellung festhängender Subagents, mit `--fix`-Unterstützung zum Löschen veralteter abgebrochener Wiederherstellungs-Flags, damit der Start den Child nicht weiterhin als neustartabgebrochen behandelt.
- Integritäts- und Berechtigungsprüfungen für den Zustand (Sitzungen, Transkripte, Zustandsverzeichnis).
- Berechtigungsprüfungen für Konfigurationsdateien (chmod 600) bei lokaler Ausführung.
- Zustand der Modellauthentifizierung: prüft OAuth-Ablauf, kann bald ablaufende Tokens aktualisieren und meldet Cooldown-/Deaktivierungszustände von Authentifizierungsprofilen.
- Erkennung zusätzlicher Workspace-Verzeichnisse (`~/openclaw`).
- Reparatur von Sitzungstranskripten für duplizierte Prompt-Rewrite-Branches, die von betroffenen Builds vom 2026.4.24 erstellt wurden.
- Erkennung von Tombstones für die Neustartwiederherstellung festgefahrener Subagenten, mit `--fix`-Unterstützung zum Entfernen veralteter abgebrochener Wiederherstellungsmarkierungen, damit der Start das Kind nicht weiter als neustartabgebrochen behandelt.
- Zustandsintegritäts- und Berechtigungsprüfungen (Sitzungen, Transkripte, Zustandsverzeichnis).
- Berechtigungsprüfungen der Konfigurationsdatei (chmod 600) bei lokaler Ausführung.
- Modell-Auth-Integrität: prüft OAuth-Ablauf, kann bald ablaufende Tokens aktualisieren und meldet Cooldown-/Deaktiviert-Zustände von Auth-Profilen.
- Erkennung zusätzlicher Arbeitsbereichsverzeichnisse (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, Dienste und Supervisoren">
- Reparatur des Sandbox-Images, wenn Sandboxing aktiviert ist.
- Legacy-Dienstmigration und Erkennung zusätzlicher Gateways.
- Migration von Legacy-Diensten und Erkennung zusätzlicher Gateways.
- Migration des Legacy-Zustands des Matrix-Kanals (im Modus `--fix` / `--repair`).
- Gateway-Laufzeitprüfungen (Dienst installiert, aber nicht aktiv; zwischengespeichertes launchd-Label).
- Kanalstatuswarnungen (vom laufenden Gateway abgefragt).
- Prüfung der Supervisor-Konfiguration (launchd/systemd/schtasks) mit optionaler Reparatur.
- Audit der Supervisor-Konfiguration (launchd/systemd/schtasks) mit optionaler Reparatur.
- Bereinigung der eingebetteten Proxy-Umgebung für Gateway-Dienste, die während Installation oder Update Shell-Werte für `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` erfasst haben.
- Gateway-Laufzeitprüfungen für bewährte Verfahren (Node vs. Bun, Pfade von Versionsmanagern).
- Diagnose von Gateway-Portkonflikten (Standard `18789`).
- Best-Practice-Prüfungen für die Gateway-Laufzeit (Node vs. Bun, Versionsmanager-Pfade).
- Gateway-Portkollisionsdiagnose (Standard `18789`).
</Accordion>
<Accordion title="Authentifizierung, Sicherheit und Kopplung">
<Accordion title="Auth, Sicherheit und Pairing">
- Sicherheitswarnungen für offene DM-Richtlinien.
- Gateway-Authentifizierungsprüfungen für lokalen Token-Modus (bietet Token-Erzeugung an, wenn keine Token-Quelle vorhanden ist; überschreibt keine Token-SecretRef-Konfigurationen).
- Erkennung von Problemen bei der Gerätekopplung (ausstehende erstmalige Kopplungsanfragen, ausstehende Rollen-/Scope-Upgrades, Drift veralteter lokaler Geräte-Token-Caches und Authentifizierungsdrift gekoppelter Datensätze).
- Gateway-Auth-Prüfungen für den lokalen Token-Modus (bietet Token-Generierung an, wenn keine Token-Quelle vorhanden ist; überschreibt keine Token-SecretRef-Konfigurationen).
- Erkennung von Problemen beim Geräte-Pairing (ausstehende erstmalige Pairing-Anfragen, ausstehende Rollen-/Scope-Upgrades, veraltete Drift im lokalen Geräte-Token-Cache und Auth-Drift bei gekoppelten Datensätzen).
</Accordion>
<Accordion title="Workspace und Shell">
<Accordion title="Arbeitsbereich und Shell">
- systemd-Linger-Prüfung unter Linux.
- Größenprüfung der Workspace-Bootstrap-Datei (Warnungen zu Kürzung/nahe Grenzwerten für Kontextdateien).
- Skills-Bereitschaftsprüfung für den Standardagenten; meldet erlaubte Skills mit fehlenden Binaries, Umgebungsvariablen, Konfigurationen oder Betriebssystemanforderungen, und `--fix` kann nicht verfügbare Skills in `skills.entries` deaktivieren.
- Prüfung der Größe der Arbeitsbereich-Bootstrap-Datei (Warnungen bei Kürzung/Nahe-am-Limit für Kontextdateien).
- Skills-Bereitschaftsprüfung für den Standard-Agenten; meldet erlaubte Skills mit fehlenden Binaries, Env, Konfiguration oder OS-Anforderungen, und `--fix` kann nicht verfügbare Skills in `skills.entries` deaktivieren.
- Statusprüfung und automatische Installation/Aktualisierung der Shell-Vervollständigung.
- Bereitschaftsprüfung des Embedding-Providers für die Speichersuche (lokales Modell, Remote-API-Schlüssel oder QMD-Binary).
- Prüfungen für Quellinstallationen (pnpm-Workspace-Abweichung, fehlende UI-Assets, fehlendes tsx-Binary).
- Schreibt aktualisierte Konfiguration und Assistentenmetadaten.
- Prüfungen für Quellinstallationen (pnpm-Arbeitsbereich stimmt nicht überein, fehlende UI-Assets, fehlendes tsx-Binary).
- Schreibt aktualisierte Konfiguration und Wizard-Metadaten.
</Accordion>
</AccordionGroup>
## Dreams-UI-Backfill und Zurücksetzen
Die Dreams-Szene der Control UI enthält die Aktionen **Backfill**, **Reset** und **Clear Grounded** für den geerdeten Dreaming-Workflow. Diese Aktionen verwenden Gateway-RPC-Methoden im Stil von doctor, sind aber **nicht** Teil der CLI-Reparatur/-Migration von `openclaw doctor`.
Die Dreams-Szene der Control UI enthält die Aktionen **Backfill**, **Reset** und **Clear Grounded** für den Grounded-Dreaming-Workflow. Diese Aktionen verwenden RPC-Methoden im Doctor-Stil des Gateways, sind aber **nicht** Teil der Reparatur/Migration der `openclaw doctor`-CLI.
Was sie tun:
- **Backfill** durchsucht historische `memory/YYYY-MM-DD.md`-Dateien im aktiven Workspace, führt den geerdeten REM-Tagebuchdurchlauf aus und schreibt reversible Backfill-Einträge in `DREAMS.md`.
- **Reset** entfernt nur diese markierten Backfill-Tagebucheinträge aus `DREAMS.md`.
- **Clear Grounded** entfernt nur bereitgestellte, rein geerdete Kurzzeiteinträge, die aus historischer Wiedergabe stammen und noch keinen Live-Recall oder tägliche Unterstützung angesammelt haben.
- **Backfill** durchsucht historische `memory/YYYY-MM-DD.md`-Dateien im aktiven Arbeitsbereich, führt den Grounded-REM-Diary-Durchlauf aus und schreibt umkehrbare Backfill-Einträge in `DREAMS.md`.
- **Reset** entfernt nur diese markierten Backfill-Diary-Einträge aus `DREAMS.md`.
- **Clear Grounded** entfernt nur bereitgestellte, ausschließlich Grounded-Kurzzeiteinträge, die aus historischer Wiedergabe stammen und noch keinen Live-Recall oder tägliche Unterstützung angesammelt haben.
Was sie allein **nicht** tun:
Was sie für sich genommen **nicht** tun:
- Sie bearbeiten `MEMORY.md` nicht
- Sie führen keine vollständigen doctor-Migrationen aus
- Sie stellen geerdete Kandidaten nicht automatisch im Live-Kurzzeit-Promotion-Speicher bereit, sofern Sie nicht zuerst explizit den bereitgestellten CLI-Pfad ausführen
- sie bearbeiten `MEMORY.md` nicht
- sie führen keine vollständigen Doctor-Migrationen aus
- sie stellen Grounded-Kandidaten nicht automatisch im Live-Kurzzeit-Promotion-Speicher bereit, es sei denn, Sie führen zuvor explizit den bereitstellenden CLI-Pfad aus
Wenn Sie möchten, dass geerdete historische Wiedergabe die normale Deep-Promotion-Lane beeinflusst, verwenden Sie stattdessen den CLI-Ablauf:
Wenn Sie möchten, dass Grounded-History-Replay die normale Deep-Promotion-Lane beeinflusst, verwenden Sie stattdessen den CLI-Ablauf:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Das stellt geerdete dauerhafte Kandidaten im Kurzzeit-Dreaming-Speicher bereit, während `DREAMS.md` die Prüfoberfläche bleibt.
Dadurch werden Grounded-Durable-Kandidaten im Kurzzeit-Dreaming-Speicher bereitgestellt, während `DREAMS.md` als Review-Oberfläche erhalten bleibt.
## Detailliertes Verhalten und Begründung
<AccordionGroup>
<Accordion title="0. Optionales Update (Git-Installationen)">
Wenn dies ein Git-Checkout ist und doctor interaktiv ausgeführt wird, bietet es vor dem Ausführen von doctor ein Update (fetch/rebase/build) an.
Wenn dies ein Git-Checkout ist und Doctor interaktiv läuft, bietet es an, vor dem Ausführen von Doctor zu aktualisieren (fetch/rebase/build).
</Accordion>
<Accordion title="1. Konfigurationsnormalisierung">
Wenn die Konfiguration Legacy-Wertformen enthält (zum Beispiel `messages.ackReaction` ohne kanalspezifischen Override), normalisiert doctor sie in das aktuelle Schema.
Wenn die Konfiguration Legacy-Wertformen enthält (zum Beispiel `messages.ackReaction` ohne kanalspezifischen Override), normalisiert Doctor sie in das aktuelle Schema.
Dazu gehören Legacy-Flachfelder von Talk. Die aktuelle öffentliche Talk-Konfiguration ist `talk.provider` + `talk.providers.<provider>`. Doctor schreibt alte Formen von `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` in die Provider-Map um.
Das umfasst Legacy-Talk-Felder im flachen Format. Die aktuelle öffentliche Talk-Konfiguration ist `talk.provider` + `talk.providers.<provider>`. Doctor schreibt alte Formen von `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` in die Provider-Map um.
Doctor warnt außerdem, wenn `plugins.allow` nicht leer ist und die Tool-Richtlinie
Wildcard- oder Plugin-eigene Tool-Einträge verwendet. `tools.allow: ["*"]` entspricht nur Tools
aus Plugins, die tatsächlich geladen werden; es umgeht nicht die exklusive Plugin-
Zulassungsliste.
Wildcard- oder Plugin-eigene Tooleinträge verwendet. `tools.allow: ["*"]` passt nur auf Tools
aus Plugins, die tatsächlich geladen werden; es umgeht die exklusive Plugin-
Allowlist nicht. Doctor schreibt `plugins.bundledDiscovery: "compat"` für migrierte
Legacy-Allowlist-Konfigurationen, um das vorhandene Verhalten gebündelter Provider beizubehalten, und
verweist dann auf die strengere Einstellung `"allowlist"`.
</Accordion>
<Accordion title="2. Legacy-Konfigurationsschlüssel-Migrationen">
<Accordion title="2. Migrationen von Legacy-Konfigurationsschlüsseln">
Wenn die Konfiguration veraltete Schlüssel enthält, verweigern andere Befehle die Ausführung und fordern Sie auf, `openclaw doctor` auszuführen.
Doctor wird:
@ -188,7 +190,7 @@ Das stellt geerdete dauerhafte Kandidaten im Kurzzeit-Dreaming-Speicher bereit,
- Die angewendete Migration anzeigen.
- `~/.openclaw/openclaw.json` mit dem aktualisierten Schema neu schreiben.
Das Gateway führt doctor-Migrationen beim Start außerdem automatisch aus, wenn es ein Legacy-Konfigurationsformat erkennt, sodass veraltete Konfigurationen ohne manuelles Eingreifen repariert werden. Cron-Job-Speichermigrationen werden von `openclaw doctor --fix` verarbeitet.
Das Gateway führt Doctor-Migrationen beim Start außerdem automatisch aus, wenn es ein Legacy-Konfigurationsformat erkennt, sodass veraltete Konfigurationen ohne manuellen Eingriff repariert werden. Migrationen des Cron-Jobspeichers werden von `openclaw doctor --fix` verarbeitet.
Aktuelle Migrationen:
@ -196,11 +198,12 @@ Das stellt geerdete dauerhafte Kandidaten im Kurzzeit-Dreaming-Speicher bereit,
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- Configs konfigurierter Channels ohne sichtbare Antwortrichtlinie → `messages.groupChat.visibleReplies: "message_tool"`
- `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
- Konfigurationen konfigurierter Kanäle ohne sichtbare Antwortrichtlinie → `messages.groupChat.visibleReplies: "message_tool"`
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` auf oberster Ebene
- `routing.bindings` → oberste Ebene `bindings`
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- veraltetes `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- veraltet `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -214,284 +217,290 @@ Das stellt geerdete dauerhafte Kandidaten im Kurzzeit-Dreaming-Speicher bereit,
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Bei Channels mit benannten `accounts`, aber verbleibenden Top-Level-Channel-Werten für ein einzelnes Konto, verschieben Sie diese kontospezifischen Werte in das für diesen Channel ausgewählte hochgestufte Konto (`accounts.default` für die meisten Channels; Matrix kann ein vorhandenes passendes benanntes/Standard-Ziel beibehalten)
- Verschieben Sie bei Kanälen mit benannten `accounts`, aber verbliebenen Einzelkonto-Werten auf oberster Kanalebene, diese kontobezogenen Werte in das für diesen Kanal hochgestufte Konto (`accounts.default` für die meisten Kanäle; Matrix kann ein vorhandenes passendes benanntes/Standardziel beibehalten)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- `agents.defaults.llm` entfernen; verwenden Sie `models.providers.<id>.timeoutSeconds` für Timeouts langsamer Provider/Modelle
- entfernen Sie `agents.defaults.llm`; verwenden Sie `models.providers.<id>.timeoutSeconds` für Timeouts langsamer Provider/Modelle
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- `browser.relayBindHost` entfernen (veraltete Relay-Einstellung der Erweiterung)
- veraltetes `models.providers.*.api: "openai"` → `"openai-completions"` (der Gateway-Start überspringt auch Provider, deren `api` auf einen zukünftigen oder unbekannten Enum-Wert gesetzt ist, statt geschlossen fehlzuschlagen)
- entfernen Sie `browser.relayBindHost` (veraltete Extension-Relay-Einstellung)
- veraltet `models.providers.*.api: "openai"` → `"openai-completions"` (der Gateway-Start überspringt außerdem Provider, deren `api` auf einen zukünftigen oder unbekannten Enum-Wert gesetzt ist, statt geschlossen fehlzuschlagen)
Doctor-Warnungen enthalten auch Hinweise zu Standardkonten für Multi-Account-Channels:
Doctor-Warnungen enthalten außerdem Hinweise zu Standardkonten für Multi-Konto-Kanäle:
- Wenn zwei oder mehr `channels.<channel>.accounts`-Einträge ohne `channels.<channel>.defaultAccount` oder `accounts.default` konfiguriert sind, warnt Doctor, dass Fallback-Routing ein unerwartetes Konto auswählen kann.
- Wenn `channels.<channel>.defaultAccount` auf eine unbekannte Konto-ID gesetzt ist, warnt Doctor und listet die konfigurierten Konto-IDs auf.
- Wenn `channels.<channel>.defaultAccount` auf eine unbekannte Konto-ID gesetzt ist, warnt Doctor und listet konfigurierte Konto-IDs auf.
</Accordion>
<Accordion title="2b. OpenCode-Provider-Overrides">
Wenn Sie `models.providers.opencode`, `opencode-zen` oder `opencode-go` manuell hinzugefügt haben, überschreibt dies den integrierten OpenCode-Katalog aus `@mariozechner/pi-ai`. Dadurch können Modelle auf die falsche API gezwungen oder Kosten auf null gesetzt werden. Doctor warnt, damit Sie das Override entfernen und API-Routing + Kosten pro Modell wiederherstellen können.
<Accordion title="2b. OpenCode provider overrides">
Wenn Sie `models.providers.opencode`, `opencode-zen` oder `opencode-go` manuell hinzugefügt haben, überschreibt dies den integrierten OpenCode-Katalog aus `@mariozechner/pi-ai`. Dadurch können Modelle auf die falsche API gezwungen oder Kosten auf null gesetzt werden. Doctor warnt, damit Sie den Override entfernen und API-Routing + Kosten pro Modell wiederherstellen können.
</Accordion>
<Accordion title="2c. Browser-Migration und Chrome-MCP-Bereitschaft">
Wenn Ihre Browser-Konfiguration noch auf den entfernten Chrome-Erweiterungspfad verweist, normalisiert Doctor sie auf das aktuelle host-lokale Chrome-MCP-Attach-Modell:
<Accordion title="2c. Browser migration and Chrome MCP readiness">
Wenn Ihre Browser-Konfiguration noch auf den entfernten Pfad der Chrome-Erweiterung zeigt, normalisiert Doctor sie auf das aktuelle hostlokale Chrome-MCP-Attach-Modell:
- `browser.profiles.*.driver: "extension"` wird zu `"existing-session"`
- `browser.relayBindHost` wird entfernt
Doctor prüft außerdem den host-lokalen Chrome-MCP-Pfad, wenn Sie `defaultProfile: "user"` oder ein konfiguriertes `existing-session`-Profil verwenden:
Doctor prüft außerdem den hostlokalen Chrome-MCP-Pfad, wenn Sie `defaultProfile: "user"` oder ein konfiguriertes `existing-session`-Profil verwenden:
- prüft, ob Google Chrome auf demselben Host für Standardprofile mit automatischer Verbindung installiert ist
- prüft die erkannte Chrome-Version und warnt, wenn sie unter Chrome 144 liegt
- erinnert Sie daran, Remote-Debugging auf der Browser-Inspect-Seite zu aktivieren (zum Beispiel `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` oder `edge://inspect/#remote-debugging`)
Doctor kann die Chrome-seitige Einstellung nicht für Sie aktivieren. Host-lokales Chrome MCP erfordert weiterhin:
Doctor kann die Chrome-seitige Einstellung nicht für Sie aktivieren. Hostlokales Chrome MCP erfordert weiterhin:
- einen Chromium-basierten Browser 144+ auf dem Gateway/Node-Host
- den lokal laufenden Browser
- in diesem Browser aktiviertes Remote-Debugging
- das Bestätigen der ersten Attach-Zustimmungsaufforderung im Browser
- einen Chromium-basierten Browser 144+ auf dem Gateway-/Node-Host
- der Browser läuft lokal
- Remote-Debugging ist in diesem Browser aktiviert
- Bestätigung der ersten Attach-Zustimmungsaufforderung im Browser
Die Bereitschaft hier bezieht sich nur auf Voraussetzungen für lokales Attach. Existing-session behält die aktuellen Chrome-MCP-Routenlimits bei; erweiterte Routen wie `responsebody`, PDF-Export, Download-Interception und Batch-Aktionen erfordern weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil.
Die Bereitschaft hier betrifft nur lokale Attach-Voraussetzungen. Existing-session behält die aktuellen Routenlimits von Chrome MCP bei; erweiterte Routen wie `responsebody`, PDF-Export, Download-Abfangung und Batch-Aktionen erfordern weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil.
Diese Prüfung gilt **nicht** für Docker-, Sandbox-, Remote-Browser- oder andere Headless-Flows. Diese verwenden weiterhin Raw CDP.
Diese Prüfung gilt **nicht** für Docker, Sandbox, Remote-Browser oder andere Headless-Abläufe. Diese verwenden weiterhin Raw CDP.
</Accordion>
<Accordion title="2d. OAuth-TLS-Voraussetzungen">
Wenn ein OpenAI-Codex-OAuth-Profil konfiguriert ist, prüft Doctor den OpenAI-Autorisierungsendpunkt, um zu verifizieren, dass der lokale Node/OpenSSL-TLS-Stack die Zertifikatskette validieren kann. Wenn die Prüfung mit einem Zertifikatsfehler fehlschlägt (zum Beispiel `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, abgelaufenes Zertifikat oder selbstsigniertes Zertifikat), gibt Doctor plattformspezifische Hinweise zur Behebung aus. Unter macOS mit einem Homebrew-Node ist die Behebung üblicherweise `brew postinstall ca-certificates`. Mit `--deep` läuft die Prüfung auch dann, wenn der Gateway gesund ist.
<Accordion title="2d. OAuth TLS prerequisites">
Wenn ein OpenAI Codex OAuth-Profil konfiguriert ist, prüft Doctor den OpenAI-Autorisierungs-Endpunkt, um zu verifizieren, dass der lokale Node/OpenSSL-TLS-Stack die Zertifikatskette validieren kann. Wenn die Prüfung mit einem Zertifikatsfehler fehlschlägt (zum Beispiel `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, abgelaufenes Zertifikat oder selbstsigniertes Zertifikat), gibt Doctor plattformspezifische Hinweise zur Behebung aus. Unter macOS mit einem Homebrew-Node lautet die Behebung normalerweise `brew postinstall ca-certificates`. Mit `--deep` läuft die Prüfung auch dann, wenn der Gateway gesund ist.
</Accordion>
<Accordion title="2e. Codex-OAuth-Provider-Overrides">
Wenn Sie zuvor veraltete OpenAI-Transporteinstellungen unter `models.providers.openai-codex` hinzugefügt haben, können diese den integrierten Codex-OAuth-Provider-Pfad überdecken, den neuere Releases automatisch verwenden. Doctor warnt, wenn diese alten Transporteinstellungen zusammen mit Codex OAuth gefunden werden, damit Sie das veraltete Transport-Override entfernen oder neu schreiben und das integrierte Routing-/Fallback-Verhalten wiederherstellen können. Benutzerdefinierte Proxys und reine Header-Overrides werden weiterhin unterstützt und lösen diese Warnung nicht aus.
<Accordion title="2e. Codex OAuth provider overrides">
Wenn Sie zuvor veraltete OpenAI-Transporteinstellungen unter `models.providers.openai-codex` hinzugefügt haben, können diese den integrierten Codex-OAuth-Provider-Pfad überdecken, den neuere Releases automatisch verwenden. Doctor warnt, wenn es diese alten Transporteinstellungen zusammen mit Codex OAuth erkennt, damit Sie den veralteten Transport-Override entfernen oder umschreiben und das integrierte Routing-/Fallback-Verhalten zurückerhalten können. Benutzerdefinierte Proxys und reine Header-Overrides werden weiterhin unterstützt und lösen diese Warnung nicht aus.
</Accordion>
<Accordion title="2f. Codex-Plugin-Routenwarnungen">
Wenn das gebündelte Codex-Plugin aktiviert ist, prüft Doctor außerdem, ob primäre Modellreferenzen für `openai-codex/*` noch über den Standard-PI-Runner aufgelöst werden. Diese Kombination ist gültig, wenn Sie Codex-OAuth-/Abonnement-Auth über PI verwenden möchten, kann aber leicht mit dem nativen Codex-App-Server-Harness verwechselt werden. Doctor warnt und verweist auf die explizite App-Server-Form: `openai/*` plus `agentRuntime.id: "codex"` oder `OPENCLAW_AGENT_RUNTIME=codex`.
<Accordion title="2f. Codex plugin route warnings">
Wenn das gebündelte Codex-Plugin aktiviert ist, prüft Doctor außerdem, ob `openai-codex/*`-Primärmodellreferenzen weiterhin über den Standard-PI-Runner aufgelöst werden. Diese Kombination ist gültig, wenn Sie Codex-OAuth-/Abonnement-Auth über PI verwenden möchten, lässt sich aber leicht mit dem nativen Codex-App-Server-Harness verwechseln. Doctor warnt und verweist auf die explizite App-Server-Form: `openai/*` plus `agentRuntime.id: "codex"` oder `OPENCLAW_AGENT_RUNTIME=codex`.
Doctor repariert dies nicht automatisch, da beide Routen gültig sind:
- `openai-codex/*` + PI bedeutet „Codex-OAuth-/Abonnement-Auth über den normalen OpenClaw-Runner verwenden.“
- `openai/*` + `agentRuntime.id: "codex"` bedeutet „den eingebetteten Turn über den nativen Codex-App-Server ausführen.“
- `/codex ...` bedeutet „eine native Codex-Konversation aus dem Chat steuern oder binden.“
- `/codex ...` bedeutet „eine native Codex-Unterhaltung aus dem Chat steuern oder binden.“
- `/acp ...` oder `runtime: "acp"` bedeutet „den externen ACP/acpx-Adapter verwenden.“
Wenn die Warnung angezeigt wird, wählen Sie die beabsichtigte Route und bearbeiten Sie die Konfiguration manuell. Lassen Sie die Warnung unverändert, wenn PI-Codex-OAuth beabsichtigt ist.
Wenn die Warnung angezeigt wird, wählen Sie die beabsichtigte Route und bearbeiten Sie die Konfiguration manuell. Behalten Sie die Warnung unverändert bei, wenn PI Codex OAuth beabsichtigt ist.
</Accordion>
<Accordion title="3. Migrationen veralteter Zustände (Festplattenlayout)">
Doctor kann ältere On-Disk-Layouts in die aktuelle Struktur migrieren:
<Accordion title="2g. Session route cleanup">
Doctor scannt außerdem den aktiven Sitzungsspeicher auf veralteten automatisch erstellten Routenstatus, nachdem Sie das konfigurierte Standard-/Fallback-Modell oder die Runtime von einer Plugin-eigenen Route wie Codex wegbewegen.
`openclaw doctor --fix` kann automatisch erstellten veralteten Status wie `modelOverrideSource: "auto"`-Modell-Pins, Runtime-Modellmetadaten, angeheftete Harness-IDs, CLI-Sitzungsbindungen und automatische Auth-Profil-Overrides löschen, wenn die zugehörige Route nicht mehr konfiguriert ist. Explizite Benutzer- oder veraltete Sitzungsmodell-Auswahlen werden zur manuellen Prüfung gemeldet und unverändert gelassen; wechseln Sie sie mit `/model ...`, `/new` oder setzen Sie die Sitzung zurück, wenn diese Route nicht mehr beabsichtigt ist.
</Accordion>
<Accordion title="3. Legacy state migrations (disk layout)">
Doctor kann ältere Layouts auf dem Datenträger in die aktuelle Struktur migrieren:
- Sitzungsspeicher + Transkripte:
- von `~/.openclaw/sessions/` nach `~/.openclaw/agents/<agentId>/sessions/`
- Agent-Verzeichnis:
- Agentenverzeichnis:
- von `~/.openclaw/agent/` nach `~/.openclaw/agents/<agentId>/agent/`
- WhatsApp-Auth-Status (Baileys):
- von veraltetem `~/.openclaw/credentials/*.json` (außer `oauth.json`)
- nach `~/.openclaw/credentials/whatsapp/<accountId>/...` (Standardkonto-ID: `default`)
Diese Migrationen erfolgen nach bestem Aufwand und sind idempotent; Doctor gibt Warnungen aus, wenn veraltete Ordner als Backups zurückbleiben. Gateway/CLI migrieren außerdem automatisch den veralteten Sitzungsspeicher + das Agent-Verzeichnis beim Start, sodass Verlauf/Auth/Modelle ohne manuellen Doctor-Lauf im agentenspezifischen Pfad landen. WhatsApp-Auth wird absichtlich nur über `openclaw doctor` migriert. Die Normalisierung von Talk-Provider/Provider-Map vergleicht jetzt nach struktureller Gleichheit, sodass reine Key-Order-Diffs keine wiederholten No-Op-Änderungen durch `doctor --fix` mehr auslösen.
Diese Migrationen erfolgen nach bestem Aufwand und sind idempotent; Doctor gibt Warnungen aus, wenn es veraltete Ordner als Backups zurücklässt. Der Gateway/die CLI migriert außerdem den veralteten Sitzungsspeicher + das Agentenverzeichnis beim Start automatisch, sodass Verlauf/Auth/Modelle ohne manuellen Doctor-Lauf im agentenspezifischen Pfad landen. WhatsApp-Auth wird absichtlich nur über `openclaw doctor` migriert. Die Normalisierung von Talk-Provider/Provider-Map vergleicht jetzt nach struktureller Gleichheit, sodass reine Schlüsselreihenfolge-Diffs keine wiederholten wirkungslosen `doctor --fix`-Änderungen mehr auslösen.
</Accordion>
<Accordion title="3a. Migrationen veralteter Plugin-Manifeste">
Doctor scannt alle installierten Plugin-Manifeste nach veralteten Capability-Schlüsseln auf oberster Ebene (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Wenn sie gefunden werden, bietet Doctor an, sie in das `contracts`-Objekt zu verschieben und die Manifestdatei direkt zu überschreiben. Diese Migration ist idempotent; wenn der Schlüssel `contracts` bereits dieselben Werte enthält, wird der veraltete Schlüssel entfernt, ohne die Daten zu duplizieren.
<Accordion title="3a. Legacy plugin manifest migrations">
Doctor scannt alle installierten Plugin-Manifeste auf veraltete Capability-Schlüssel auf oberster Ebene (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Wenn sie gefunden werden, bietet es an, sie in das `contracts`-Objekt zu verschieben und die Manifestdatei direkt umzuschreiben. Diese Migration ist idempotent; wenn der Schlüssel `contracts` bereits dieselben Werte enthält, wird der veraltete Schlüssel entfernt, ohne die Daten zu duplizieren.
</Accordion>
<Accordion title="3b. Migrationen veralteter Cron-Speicher">
Doctor prüft außerdem den Cron-Job-Speicher (standardmäßig `~/.openclaw/cron/jobs.json` oder `cron.store`, wenn überschrieben) auf alte Job-Formen, die der Scheduler aus Kompatibilitätsgründen weiterhin akzeptiert.
<Accordion title="3b. Legacy cron store migrations">
Doctor prüft außerdem den Cron-Job-Speicher (`~/.openclaw/cron/jobs.json` standardmäßig oder `cron.store`, wenn überschrieben) auf alte Job-Formen, die der Scheduler aus Kompatibilitätsgründen weiterhin akzeptiert.
Aktuelle Cron-Bereinigungen umfassen:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- Payload-Felder auf oberster Ebene (`message`, `model`, `thinking`, ...) → `payload`
- Zustellfelder auf oberster Ebene (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- Payload-`provider`-Zustellaliasse → explizites `delivery.channel`
- einfache veraltete `notify: true`-Webhook-Fallback-Jobs → explizites `delivery.mode="webhook"` mit `delivery.to=cron.webhook`
- Zustellungsfelder auf oberster Ebene (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- Payload-`provider`-Zustellungsaliasse → explizit `delivery.channel`
- einfache veraltete `notify: true`-Webhook-Fallback-Jobs → explizit `delivery.mode="webhook"` mit `delivery.to=cron.webhook`
Doctor migriert `notify: true`-Jobs nur dann automatisch, wenn dies ohne Verhaltensänderung möglich ist. Wenn ein Job den veralteten Notify-Fallback mit einem vorhandenen Nicht-Webhook-Zustellmodus kombiniert, warnt Doctor und lässt diesen Job zur manuellen Prüfung unverändert.
Doctor migriert `notify: true`-Jobs nur dann automatisch, wenn dies ohne Verhaltensänderung möglich ist. Wenn ein Job einen veralteten Notify-Fallback mit einem vorhandenen Nicht-Webhook-Zustellungsmodus kombiniert, warnt Doctor und belässt diesen Job zur manuellen Prüfung.
Unter Linux warnt Doctor außerdem, wenn die Crontab des Benutzers noch das veraltete `~/.openclaw/bin/ensure-whatsapp.sh` aufruft. Dieses host-lokale Skript wird vom aktuellen OpenClaw nicht gepflegt und kann falsche `Gateway inactive`-Meldungen nach `~/.openclaw/logs/whatsapp-health.log` schreiben, wenn Cron den systemd-User-Bus nicht erreichen kann. Entfernen Sie den veralteten Crontab-Eintrag mit `crontab -e`; verwenden Sie `openclaw channels status --probe`, `openclaw doctor` und `openclaw gateway status` für aktuelle Health Checks.
Unter Linux warnt Doctor außerdem, wenn die Crontab des Benutzers weiterhin das veraltete `~/.openclaw/bin/ensure-whatsapp.sh` aufruft. Dieses host-lokale Skript wird vom aktuellen OpenClaw nicht gepflegt und kann falsche `Gateway inactive`-Meldungen nach `~/.openclaw/logs/whatsapp-health.log` schreiben, wenn cron den systemd-Benutzerbus nicht erreichen kann. Entfernen Sie den veralteten Crontab-Eintrag mit `crontab -e`; verwenden Sie `openclaw channels status --probe`, `openclaw doctor` und `openclaw gateway status` für aktuelle Zustandsprüfungen.
</Accordion>
<Accordion title="3c. Bereinigung von Sitzungssperren">
Doctor durchsucht jedes Agent-Sitzungsverzeichnis nach veralteten Schreibsperrdateien – Dateien, die zurückbleiben, wenn eine Sitzung abnormal beendet wurde. Für jede gefundene Sperrdatei meldet es: den Pfad, die PID, ob die PID noch aktiv ist, das Alter der Sperre und ob sie als veraltet gilt (tote PID oder älter als 30 Minuten). Im Modus `--fix` / `--repair` entfernt es veraltete Sperrdateien automatisch; andernfalls gibt es einen Hinweis aus und weist Sie an, den Befehl erneut mit `--fix` auszuführen.
<Accordion title="3c. Sitzungs-Lock-Bereinigung">
Doctor durchsucht jedes Agent-Sitzungsverzeichnis nach veralteten Schreib-Lock-Dateien — Dateien, die zurückbleiben, wenn eine Sitzung abnormal beendet wurde. Für jede gefundene Lock-Datei meldet es: den Pfad, die PID, ob die PID noch aktiv ist, das Alter des Locks und ob es als veraltet gilt (tote PID oder älter als 30 Minuten). Im Modus `--fix` / `--repair` entfernt es veraltete Lock-Dateien automatisch; andernfalls gibt es einen Hinweis aus und weist Sie an, den Befehl erneut mit `--fix` auszuführen.
</Accordion>
<Accordion title="3d. Reparatur des Sitzungstranskript-Branches">
Doctor durchsucht Agent-Sitzungsdateien im JSONL-Format nach der duplizierten Branch-Form, die durch den Fehler beim Prompt-Transkript-Rewrite vom 24.4.2026 erzeugt wurde: ein aufgegebener Benutzer-Turn mit internem OpenClaw-Laufzeitkontext sowie ein aktiver Geschwister-Branch mit demselben sichtbaren Benutzer-Prompt. Im Modus `--fix` / `--repair` sichert Doctor jede betroffene Datei neben dem Original und schreibt das Transkript auf den aktiven Branch um, sodass Gateway-Verlauf und Memory-Leser keine doppelten Turns mehr sehen.
<Accordion title="3d. Reparatur von Sitzungs-Transkript-Branches">
Doctor durchsucht Agent-Sitzungs-JSONL-Dateien nach der duplizierten Branch-Form, die durch den Fehler beim Umschreiben des Prompt-Transkripts vom 2026.4.24 erzeugt wurde: ein verlassener Benutzer-Turn mit internem OpenClaw-Laufzeitkontext plus ein aktives Geschwisterelement mit demselben sichtbaren Benutzer-Prompt. Im Modus `--fix` / `--repair` sichert Doctor jede betroffene Datei neben dem Original und schreibt das Transkript auf den aktiven Branch um, sodass Gateway-Verlauf und Memory-Reader keine doppelten Turns mehr sehen.
</Accordion>
<Accordion title="4. Integritätsprüfungen für den Zustand (Sitzungspersistenz, Routing und Sicherheit)">
Das Zustandsverzeichnis ist der operative Hirnstamm. Wenn es verschwindet, verlieren Sie Sitzungen, Anmeldedaten, Protokolle und Konfiguration (sofern Sie keine Sicherungen an anderer Stelle haben).
<Accordion title="4. Integritätsprüfungen des Zustands (Sitzungspersistenz, Routing und Sicherheit)">
Das Zustandsverzeichnis ist der operative Hirnstamm. Wenn es verschwindet, verlieren Sie Sitzungen, Zugangsdaten, Protokolle und Konfiguration (sofern Sie keine Backups an anderer Stelle haben).
Doctor prüft:
- **Zustandsverzeichnis fehlt**: warnt vor katastrophalem Zustandsverlust, fordert dazu auf, das Verzeichnis neu zu erstellen, und erinnert Sie daran, dass fehlende Daten nicht wiederhergestellt werden können.
- **Berechtigungen des Zustandsverzeichnisses**: verifiziert die Schreibbarkeit; bietet an, Berechtigungen zu reparieren (und gibt einen `chown`-Hinweis aus, wenn eine Abweichung bei Besitzer/Gruppe erkannt wird).
- **macOS-Zustandsverzeichnis mit Cloud-Synchronisierung**: warnt, wenn der Zustand unter iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) oder `~/Library/CloudStorage/...` aufgelöst wird, da synchronisationsgestützte Pfade langsamere E/A sowie Sperr-/Synchronisationsrennen verursachen können.
- **Linux-Zustandsverzeichnis auf SD oder eMMC**: warnt, wenn der Zustand auf eine `mmcblk*`-Mount-Quelle aufgelöst wird, da zufällige E/A auf SD- oder eMMC-Speicher unter Sitzungs- und Anmeldedaten-Schreibvorgängen langsamer sein und schneller verschleißen kann.
- **Zustandsverzeichnis fehlt**: warnt vor katastrophalem Zustandsverlust, fordert Sie auf, das Verzeichnis neu zu erstellen, und erinnert Sie daran, dass fehlende Daten nicht wiederhergestellt werden können.
- **Berechtigungen des Zustandsverzeichnisses**: prüft die Schreibbarkeit; bietet an, Berechtigungen zu reparieren (und gibt einen `chown`-Hinweis aus, wenn eine Abweichung bei Besitzer/Gruppe erkannt wird).
- **macOS-Zustandsverzeichnis mit Cloud-Synchronisierung**: warnt, wenn der Zustand unter iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) oder `~/Library/CloudStorage/...` aufgelöst wird, da synchronisationsgestützte Pfade langsamere I/O und Lock-/Synchronisationsrennen verursachen können.
- **Linux-Zustandsverzeichnis auf SD oder eMMC**: warnt, wenn der Zustand auf eine `mmcblk*`-Mount-Quelle aufgelöst wird, da zufällige I/O auf SD- oder eMMC-Speicher langsamer sein und bei Sitzungs- und Zugangsdaten-Schreibvorgängen schneller verschleißen kann.
- **Sitzungsverzeichnisse fehlen**: `sessions/` und das Sitzungsspeicherverzeichnis sind erforderlich, um Verlauf zu persistieren und `ENOENT`-Abstürze zu vermeiden.
- **Transkriptabweichung**: warnt, wenn bei aktuellen Sitzungseinträgen Transkriptdateien fehlen.
- **Hauptsitzung „1-line JSONL“**: markiert, wenn das Haupttranskript nur eine Zeile hat (Verlauf sammelt sich nicht an).
- **Mehrere Zustandsverzeichnisse**: warnt, wenn mehrere `~/.openclaw`-Ordner über Home-Verzeichnisse hinweg existieren oder wenn `OPENCLAW_STATE_DIR` an einen anderen Ort zeigt (Verlauf kann sich zwischen Installationen aufteilen).
- **Transkript-Abweichung**: warnt, wenn neuere Sitzungseinträge fehlende Transkriptdateien haben.
- **Hauptsitzung „1-Zeilen-JSONL“**: markiert, wenn das Haupttranskript nur eine Zeile hat (Verlauf sammelt sich nicht an).
- **Mehrere Zustandsverzeichnisse**: warnt, wenn mehrere `~/.openclaw`-Ordner über Home-Verzeichnisse hinweg existieren oder wenn `OPENCLAW_STATE_DIR` auf einen anderen Ort zeigt (Verlauf kann zwischen Installationen aufgeteilt werden).
- **Hinweis zum Remote-Modus**: wenn `gateway.mode=remote`, erinnert Doctor Sie daran, es auf dem Remote-Host auszuführen (der Zustand liegt dort).
- **Berechtigungen der Konfigurationsdatei**: warnt, wenn `~/.openclaw/openclaw.json` für Gruppe/Welt lesbar ist, und bietet an, auf `600` zu verschärfen.
- **Berechtigungen der Konfigurationsdatei**: warnt, wenn `~/.openclaw/openclaw.json` für Gruppe/Welt lesbar ist, und bietet an, die Berechtigungen auf `600` zu verschärfen.
</Accordion>
<Accordion title="5. Zustand der Modellauthentifizierung (OAuth-Ablauf)">
Doctor prüft OAuth-Profile im Authentifizierungsspeicher, warnt, wenn Tokens bald ablaufen/abgelaufen sind, und kann sie aktualisieren, wenn dies sicher ist. Wenn das Anthropic-OAuth-/Tokenprofil veraltet ist, schlägt es einen Anthropic-API-Schlüssel oder den Anthropic-Setup-Token-Pfad vor. Aktualisierungsaufforderungen erscheinen nur bei interaktiver Ausführung (TTY); `--non-interactive` überspringt Aktualisierungsversuche.
<Accordion title="5. Zustand der Modell-Authentifizierung (OAuth-Ablauf)">
Doctor prüft OAuth-Profile im Auth-Speicher, warnt, wenn Token bald ablaufen oder abgelaufen sind, und kann sie aktualisieren, wenn dies sicher ist. Wenn das Anthropic-OAuth-/Token-Profil veraltet ist, schlägt es einen Anthropic-API-Schlüssel oder den Anthropic-Setup-Token-Pfad vor. Aktualisierungsaufforderungen erscheinen nur bei interaktiver Ausführung (TTY); `--non-interactive` überspringt Aktualisierungsversuche.
Wenn eine OAuth-Aktualisierung dauerhaft fehlschlägt (zum Beispiel `refresh_token_reused`, `invalid_grant` oder ein Provider Sie auffordert, sich erneut anzumelden), meldet Doctor, dass eine erneute Authentifizierung erforderlich ist, und gibt den exakt auszuführenden Befehl `openclaw models auth login --provider ...` aus.
Wenn eine OAuth-Aktualisierung dauerhaft fehlschlägt (zum Beispiel `refresh_token_reused`, `invalid_grant` oder ein Provider, der Sie auffordert, sich erneut anzumelden), meldet Doctor, dass eine erneute Authentifizierung erforderlich ist, und gibt den exakten auszuführenden Befehl `openclaw models auth login --provider ...` aus.
Doctor meldet außerdem Authentifizierungsprofile, die vorübergehend nicht nutzbar sind aufgrund von:
Doctor meldet außerdem Auth-Profile, die vorübergehend nicht nutzbar sind aufgrund von:
- kurzen Abklingzeiten (Rate Limits/Zeitüberschreitungen/Authentifizierungsfehlern)
- längeren Deaktivierungen (Abrechnungs-/Guthabenfehlern)
- kurzen Cooldowns (Rate-Limits/Zeitüberschreitungen/Auth-Fehler)
- längeren Deaktivierungen (Abrechnungs-/Guthabenfehler)
</Accordion>
<Accordion title="6. Modellvalidierung für Hooks">
Wenn `hooks.gmail.model` gesetzt ist, validiert Doctor die Modellreferenz gegen den Katalog und die Allowlist und warnt, wenn sie nicht aufgelöst wird oder nicht erlaubt ist.
<Accordion title="6. Validierung des Hooks-Modells">
Wenn `hooks.gmail.model` gesetzt ist, validiert Doctor die Modellreferenz gegen den Katalog und die Allowlist und warnt, wenn sie nicht aufgelöst werden kann oder nicht erlaubt ist.
</Accordion>
<Accordion title="7. Reparatur von Sandbox-Images">
Wenn Sandboxing aktiviert ist, prüft Doctor Docker-Images und bietet an, sie zu bauen oder auf Legacy-Namen zu wechseln, falls das aktuelle Image fehlt.
<Accordion title="7. Reparatur des Sandbox-Images">
Wenn Sandboxing aktiviert ist, prüft Doctor Docker-Images und bietet an, zu bauen oder auf Legacy-Namen zu wechseln, wenn das aktuelle Image fehlt.
</Accordion>
<Accordion title="7b. Bereinigung der Plugin-Installation">
Doctor entfernt im Modus `openclaw doctor --fix` / `openclaw doctor --repair` von OpenClaw erzeugten Legacy-Staging-Zustand für Plugin-Abhängigkeiten. Dies umfasst veraltete generierte Abhängigkeitswurzeln, alte Installations-Staging-Verzeichnisse, paketlokale Rückstände aus früherem Reparaturcode für Abhängigkeiten gebündelter Plugins sowie verwaiste oder wiederhergestellte verwaltete npm-Kopien gebündelter `@openclaw/*`-Plugins, die das aktuelle gebündelte Manifest überdecken können.
<Accordion title="7b. Bereinigung von Plugin-Installationen">
Doctor entfernt im Modus `openclaw doctor --fix` / `openclaw doctor --repair` veralteten von OpenClaw erzeugten Staging-Zustand für Plugin-Abhängigkeiten. Dies umfasst veraltete generierte Abhängigkeits-Roots, alte Install-Stage-Verzeichnisse, paketlokale Rückstände aus früherem Reparaturcode für gebündelte Plugin-Abhängigkeiten sowie verwaiste oder wiederhergestellte verwaltete npm-Kopien gebündelter `@openclaw/*`-Plugins, die das aktuelle gebündelte Manifest überdecken können.
Doctor kann außerdem konfigurierte herunterladbare Plugins neu installieren, wenn die Konfiguration auf sie verweist, die lokale Plugin-Registry sie aber nicht finden kann. Für die Externalisierung gebündelter Plugins am 2.5.2026 installiert Doctor automatisch herunterladbare Plugins, die von der bestehenden Konfiguration bereits verwendet werden, und verlässt sich dann auf `meta.lastTouchedVersion`, damit dieser Release-Durchlauf nur einmal ausgeführt wird. Gateway-Start und Neuladen der Konfiguration führen keine Paketmanager aus; Plugin-Installationen bleiben explizite Doctor-/Installations-/Aktualisierungsarbeit.
Doctor kann außerdem fehlende herunterladbare Plugins neu installieren, wenn die Konfiguration sie referenziert, die lokale Plugin-Registry sie aber nicht finden kann. Beispiele sind materielle `plugins.entries`, konfigurierte Kanal-/Provider-/Sucheinstellungen und konfigurierte Agent-Laufzeiten. Während Paketaktualisierungen vermeidet Doctor die Ausführung der Plugin-Reparatur über den Paketmanager, während das Kernpaket ausgetauscht wird; führen Sie nach der Aktualisierung erneut `openclaw doctor --fix` aus, wenn ein konfiguriertes Plugin weiterhin wiederhergestellt werden muss. Gateway-Start und Konfigurationsneuladen führen keine Paketmanager aus; Plugin-Installationen bleiben explizite Doctor-/Install-/Update-Arbeit.
</Accordion>
<Accordion title="8. Gateway-Dienstmigrationen und Bereinigungshinweise">
Doctor erkennt Legacy-Gateway-Dienste (launchd/systemd/schtasks) und bietet an, sie zu entfernen und den OpenClaw-Dienst mit dem aktuellen Gateway-Port zu installieren. Es kann außerdem nach zusätzlichen Gateway-ähnlichen Diensten suchen und Bereinigungshinweise ausgeben. Profilbenannte OpenClaw-Gateway-Dienste gelten als erstklassig und werden nicht als „zusätzlich“ markiert.
Doctor erkennt veraltete Gateway-Dienste (launchd/systemd/schtasks) und bietet an, sie zu entfernen und den OpenClaw-Dienst mit dem aktuellen Gateway-Port zu installieren. Es kann außerdem nach zusätzlichen gateway-ähnlichen Diensten suchen und Bereinigungshinweise ausgeben. Profilbenannte OpenClaw-Gateway-Dienste gelten als erstklassig und werden nicht als „extra“ markiert.
Unter Linux installiert Doctor keinen zweiten Dienst auf Benutzerebene automatisch, wenn der Gateway-Dienst auf Benutzerebene fehlt, aber ein OpenClaw-Gateway-Dienst auf Systemebene existiert. Prüfen Sie dies mit `openclaw gateway status --deep` oder `openclaw doctor --deep`, entfernen Sie dann das Duplikat oder setzen Sie `OPENCLAW_SERVICE_REPAIR_POLICY=external`, wenn ein System-Supervisor den Gateway-Lebenszyklus verwaltet.
Unter Linux installiert Doctor nicht automatisch einen zweiten Dienst auf Benutzerebene, wenn der Gateway-Dienst auf Benutzerebene fehlt, aber ein OpenClaw-Gateway-Dienst auf Systemebene existiert. Prüfen Sie mit `openclaw gateway status --deep` oder `openclaw doctor --deep`, entfernen Sie dann das Duplikat oder setzen Sie `OPENCLAW_SERVICE_REPAIR_POLICY=external`, wenn ein System-Supervisor den Gateway-Lebenszyklus besitzt.
</Accordion>
<Accordion title="8b. Startup-Matrix-Migration">
Wenn ein Matrix-Kanalkonto eine ausstehende oder handlungsrelevante Legacy-Zustandsmigration hat, erstellt Doctor (im Modus `--fix` / `--repair`) einen Snapshot vor der Migration und führt dann die Best-Effort-Migrationsschritte aus: Legacy-Matrix-Zustandsmigration und Vorbereitung des verschlüsselten Legacy-Zustands. Beide Schritte sind nicht fatal; Fehler werden protokolliert und der Start wird fortgesetzt. Im schreibgeschützten Modus (`openclaw doctor` ohne `--fix`) wird diese Prüfung vollständig übersprungen.
Wenn ein Matrix-Kanalkonto eine ausstehende oder umsetzbare Legacy-Zustandsmigration hat, erstellt Doctor (im Modus `--fix` / `--repair`) einen Snapshot vor der Migration und führt dann die bestmöglichen Migrationsschritte aus: Legacy-Matrix-Zustandsmigration und Vorbereitung des Legacy-verschlüsselten Zustands. Beide Schritte sind nicht fatal; Fehler werden protokolliert und der Start wird fortgesetzt. Im schreibgeschützten Modus (`openclaw doctor` ohne `--fix`) wird diese Prüfung vollständig übersprungen.
</Accordion>
<Accordion title="8c. Gerätekopplung und Authentifizierungsabweichung">
Doctor prüft jetzt den Gerätekopplungszustand als Teil des normalen Zustandsdurchlaufs.
<Accordion title="8c. Gerätekopplung und Auth-Abweichungen">
Doctor prüft den Gerätekopplungszustand jetzt als Teil des normalen Zustandsdurchlaufs.
Was es meldet:
Gemeldet werden:
- ausstehende erstmalige Kopplungsanfragen
- ausstehende Erstkopplungsanfragen
- ausstehende Rollen-Upgrades für bereits gekoppelte Geräte
- ausstehende Scope-Upgrades für bereits gekoppelte Geräte
- Reparaturen bei Public-Key-Abweichungen, bei denen die Geräte-ID noch übereinstimmt, die Geräteidentität aber nicht mehr dem genehmigten Datensatz entspricht
- gekoppelte Datensätze, denen ein aktives Token für eine genehmigte Rolle fehlt
- gekoppelte Tokens, deren Scopes von der genehmigten Kopplungsbasis abweichen
- lokale zwischengespeicherte Geräte-Token-Einträge für den aktuellen Rechner, die älter sind als eine Gateway-seitige Token-Rotation oder veraltete Scope-Metadaten enthalten
- Reparaturen bei Public-Key-Abweichungen, bei denen die Geräte-ID noch übereinstimmt, die Geräteidentität aber nicht mehr mit dem genehmigten Datensatz übereinstimmt
- gekoppelte Datensätze ohne aktiven Token für eine genehmigte Rolle
- gekoppelte Token, deren Scopes von der genehmigten Kopplungs-Baseline abweichen
- lokal zwischengespeicherte Gerätetoken-Einträge für den aktuellen Rechner, die einer Gateway-seitigen Token-Rotation vorausgehen oder veraltete Scope-Metadaten tragen
Doctor genehmigt Kopplungsanfragen nicht automatisch und rotiert Geräte-Tokens nicht automatisch. Stattdessen gibt es die exakten nächsten Schritte aus:
Doctor genehmigt Kopplungsanfragen nicht automatisch und rotiert Gerätetoken nicht automatisch. Stattdessen gibt es die exakten nächsten Schritte aus:
- ausstehende Anfragen mit `openclaw devices list` prüfen
- die exakte Anfrage mit `openclaw devices approve <requestId>` genehmigen
- ein frisches Token mit `openclaw devices rotate --device <deviceId> --role <role>` rotieren
- einen frischen Token mit `openclaw devices rotate --device <deviceId> --role <role>` rotieren
- einen veralteten Datensatz mit `openclaw devices remove <deviceId>` entfernen und erneut genehmigen
Dies schließt die häufige Lücke „bereits gekoppelt, aber Kopplung weiterhin erforderlich“: Doctor unterscheidet nun erstmalige Kopplung von ausstehenden Rollen-/Scope-Upgrades und von veralteten Token-/Geräteidentitätsabweichungen.
Dies schließt die häufige Lücke „bereits gekoppelt, aber weiterhin Kopplung erforderlich“: Doctor unterscheidet jetzt Erstkopplung von ausstehenden Rollen-/Scope-Upgrades und von veralteten Token-/Geräteidentitäts-Abweichungen.
</Accordion>
<Accordion title="9. Sicherheitswarnungen">
Doctor gibt Warnungen aus, wenn ein Provider für DMs ohne Allowlist geöffnet ist oder wenn eine Richtlinie auf gefährliche Weise konfiguriert ist.
Doctor gibt Warnungen aus, wenn ein Provider für DMs ohne Allowlist offen ist oder wenn eine Richtlinie auf gefährliche Weise konfiguriert ist.
</Accordion>
<Accordion title="10. systemd-Linger (Linux)">
Wenn die Ausführung als systemd-Benutzerdienst erfolgt, stellt Doctor sicher, dass Linger aktiviert ist, damit das Gateway nach der Abmeldung aktiv bleibt.
Bei Ausführung als systemd-Benutzerdienst stellt Doctor sicher, dass Linger aktiviert ist, damit das Gateway nach dem Abmelden aktiv bleibt.
</Accordion>
<Accordion title="11. Workspace-Status (Skills, Plugins und Legacy-Verzeichnisse)">
Doctor gibt eine Zusammenfassung des Workspace-Zustands für den Standard-Agent aus:
- **Skills-Status**: zählt zulässige Skills, Skills mit fehlenden Anforderungen und durch die Allowlist blockierte Skills.
- **Skills-Status**: zählt geeignete, mit fehlenden Anforderungen versehene und durch die Allowlist blockierte Skills.
- **Legacy-Workspace-Verzeichnisse**: warnt, wenn `~/openclaw` oder andere Legacy-Workspace-Verzeichnisse neben dem aktuellen Workspace existieren.
- **Plugin-Status**: zählt aktivierte/deaktivierte/fehlerhafte Plugins; listet Plugin-IDs für alle Fehler auf; meldet Funktionen von Bundle-Plugins.
- **Plugin-Status**: zählt aktivierte/deaktivierte/fehlerhafte Plugins; listet Plugin-IDs für alle Fehler auf; meldet Fähigkeiten gebündelter Plugins.
- **Plugin-Kompatibilitätswarnungen**: markiert Plugins, die Kompatibilitätsprobleme mit der aktuellen Laufzeit haben.
- **Plugin-Diagnose**: zeigt alle Ladezeitwarnungen oder -fehler an, die von der Plugin-Registry ausgegeben wurden.
- **Plugin-Diagnosen**: zeigt alle Ladezeit-Warnungen oder -Fehler an, die von der Plugin-Registry ausgegeben wurden.
</Accordion>
<Accordion title="11b. Größe der Bootstrap-Datei">
Doctor prüft, ob Workspace-Bootstrap-Dateien (zum Beispiel `AGENTS.md`, `CLAUDE.md` oder andere injizierte Kontextdateien) nahe am oder über dem konfigurierten Zeichenbudget liegen. Es meldet pro Datei rohe vs. injizierte Zeichenzahlen, Kürzungsprozentsatz, Kürzungsursache (`max/file` oder `max/total`) und die gesamten injizierten Zeichen als Anteil am Gesamtbudget. Wenn Dateien gekürzt werden oder nahe am Limit liegen, gibt Doctor Tipps zur Anpassung von `agents.defaults.bootstrapMaxChars` und `agents.defaults.bootstrapTotalMaxChars` aus.
<Accordion title="11b. Bootstrap-Dateigröße">
Doctor prüft, ob Workspace-Bootstrap-Dateien (zum Beispiel `AGENTS.md`, `CLAUDE.md` oder andere injizierte Kontextdateien) nahe am konfigurierten Zeichenbudget liegen oder es überschreiten. Es meldet pro Datei rohe gegenüber injizierten Zeichenzahlen, Kürzungsprozentsatz, Kürzungsursache (`max/file` oder `max/total`) und die gesamten injizierten Zeichen als Anteil des Gesamtbudgets. Wenn Dateien gekürzt werden oder nahe am Limit liegen, gibt Doctor Tipps zur Abstimmung von `agents.defaults.bootstrapMaxChars` und `agents.defaults.bootstrapTotalMaxChars` aus.
</Accordion>
<Accordion title="11d. Bereinigung veralteter Kanal-Plugins">
Wenn `openclaw doctor --fix` ein fehlendes Kanal-Plugin entfernt, entfernt es auch die verwaiste kanalspezifische Konfiguration, die auf dieses Plugin verwiesen hat: `channels.<id>`-Einträge, Heartbeat-Ziele, die den Kanal benannt haben, und `agents.*.models["<channel>/*"]`-Overrides. Dies verhindert Gateway-Boot-Loops, bei denen die Kanallaufzeit verschwunden ist, die Konfiguration das Gateway aber weiterhin auffordert, daran zu binden.
Wenn `openclaw doctor --fix` ein fehlendes Kanal-Plugin entfernt, entfernt es auch die verwaiste kanalspezifische Konfiguration, die dieses Plugin referenziert hat: `channels.<id>`-Einträge, Heartbeat-Ziele, die den Kanal benannt haben, und `agents.*.models["<channel>/*"]`-Overrides. Dies verhindert Gateway-Bootschleifen, bei denen die Kanallaufzeit entfernt wurde, die Konfiguration das Gateway aber weiterhin auffordert, daran zu binden.
</Accordion>
<Accordion title="11c. Shell-Vervollständigung">
Doctor prüft, ob Tab-Vervollständigung für die aktuelle Shell installiert ist (zsh, bash, fish oder PowerShell):
Doctor prüft, ob Tab-Vervollständigung für die aktuelle Shell (zsh, bash, fish oder PowerShell) installiert ist:
- Wenn das Shell-Profil ein langsames dynamisches Vervollständigungsmuster verwendet (`source <(openclaw completion ...)`), aktualisiert Doctor es auf die schnellere Variante mit zwischengespeicherter Datei.
- Wenn Vervollständigung im Profil konfiguriert ist, aber die Cache-Datei fehlt, generiert Doctor den Cache automatisch neu.
- Wenn überhaupt keine Vervollständigung konfiguriert ist, fordert Doctor zur Installation auf (nur interaktiver Modus; wird mit `--non-interactive` übersprungen).
- Wenn das Shell-Profil ein langsames dynamisches Vervollständigungsmuster verwendet (`source <(openclaw completion ...)`), aktualisiert Doctor es auf die schnellere Variante mit Cache-Datei.
- Wenn Vervollständigung im Profil konfiguriert ist, die Cache-Datei aber fehlt, generiert Doctor den Cache automatisch neu.
- Wenn überhaupt keine Vervollständigung konfiguriert ist, fordert Doctor zur Installation auf (nur im interaktiven Modus; mit `--non-interactive` übersprungen).
Führen Sie `openclaw completion --write-state` aus, um den Cache manuell neu zu generieren.
</Accordion>
<Accordion title="12. Gateway-Authentifizierungsprüfungen (lokales Token)">
<Accordion title="12. Gateway-Auth-Prüfungen (lokaler Token)">
Doctor prüft die Bereitschaft der lokalen Gateway-Token-Authentifizierung.
- Wenn der Token-Modus ein Token benötigt und keine Token-Quelle vorhanden ist, bietet Doctor an, eines zu generieren.
- Wenn `gateway.auth.token` SecretRef-verwaltet, aber nicht verfügbar ist, warnt Doctor und überschreibt es nicht mit Klartext.
- `openclaw doctor --generate-gateway-token` erzwingt die Generierung nur, wenn keine Token-SecretRef konfiguriert ist.
- Wenn der Token-Modus einen Token benötigt und keine Token-Quelle existiert, bietet Doctor an, einen zu generieren.
- Wenn `gateway.auth.token` SecretRef-verwaltet, aber nicht verfügbar ist, warnt Doctor und überschreibt ihn nicht mit Klartext.
- `openclaw doctor --generate-gateway-token` erzwingt die Generierung nur, wenn kein Token-SecretRef konfiguriert ist.
</Accordion>
<Accordion title="12b. Schreibgeschützte SecretRef-bewusste Reparaturen">
Einige Reparaturabläufe müssen konfigurierte Anmeldedaten prüfen, ohne das Fail-Fast-Verhalten der Laufzeit abzuschwächen.
Einige Reparaturabläufe müssen konfigurierte Zugangsdaten prüfen, ohne das Fail-Fast-Verhalten der Laufzeit abzuschwächen.
- `openclaw doctor --fix` verwendet jetzt dasselbe schreibgeschützte SecretRef-Zusammenfassungsmodell wie Status-Family-Befehle für gezielte Konfigurationsreparaturen.
- Beispiel: Die Telegram-Reparatur von `allowFrom` / `groupAllowFrom` `@username` versucht, konfigurierte Bot-Anmeldedaten zu verwenden, wenn sie verfügbar sind.
- Wenn das Telegram-Bot-Token über SecretRef konfiguriert, aber im aktuellen Befehlspfad nicht verfügbar ist, meldet Doctor, dass die Anmeldedaten konfiguriert, aber nicht verfügbar sind, und überspringt die automatische Auflösung, statt abzustürzen oder das Token fälschlich als fehlend zu melden.
- `openclaw doctor --fix` verwendet jetzt dasselbe schreibgeschützte SecretRef-Zusammenfassungsmodell wie Befehle der Status-Familie für gezielte Konfigurationsreparaturen.
- Beispiel: Die Reparatur von Telegram `allowFrom` / `groupAllowFrom` `@username` versucht, konfigurierte Bot-Anmeldedaten zu verwenden, wenn sie verfügbar sind.
- Wenn das Telegram-Bot-Token über SecretRef konfiguriert ist, aber im aktuellen Befehlspfad nicht verfügbar ist, meldet doctor, dass die Anmeldedaten konfiguriert, aber nicht verfügbar sind, und überspringt die automatische Auflösung, statt abzustürzen oder das Token fälschlicherweise als fehlend zu melden.
</Accordion>
<Accordion title="13. Gateway-Integritätsprüfung + Neustart">
Doctor führt eine Integritätsprüfung aus und bietet an, das Gateway neu zu starten, wenn es fehlerhaft wirkt.
<Accordion title="13. Gateway-Zustandsprüfung + Neustart">
Doctor führt eine Zustandsprüfung aus und bietet an, das Gateway neu zu starten, wenn es fehlerhaft wirkt.
</Accordion>
<Accordion title="13b. Bereitschaft der Speichersuche">
Doctor prüft, ob der konfigurierte Embedding-Provider für die Speichersuche für den Standardagenten bereit ist. Das Verhalten hängt vom konfigurierten Backend und Provider ab:
- **QMD-Backend**: Prüft, ob die Binärdatei `qmd` verfügbar und startbar ist. Falls nicht, werden Hinweise zur Behebung ausgegeben, einschließlich des npm-Pakets und einer Option für einen manuellen Binärpfad.
- **QMD-Backend**: Prüft, ob die `qmd`-Binärdatei verfügbar und startbar ist. Falls nicht, gibt es Reparaturhinweise aus, einschließlich des npm-Pakets und einer Option für einen manuellen Binärpfad.
- **Expliziter lokaler Provider**: Prüft auf eine lokale Modelldatei oder eine erkannte Remote-/herunterladbare Modell-URL. Falls sie fehlt, wird vorgeschlagen, zu einem Remote-Provider zu wechseln.
- **Expliziter Remote-Provider** (`openai`, `voyage` usw.): Prüft, ob ein API-Schlüssel in der Umgebung oder im Auth-Speicher vorhanden ist. Gibt umsetzbare Hinweise zur Behebung aus, falls er fehlt.
- **Expliziter Remote-Provider** (`openai`, `voyage` usw.): Überprüft, ob ein API-Schlüssel in der Umgebung oder im Auth-Speicher vorhanden ist. Gibt umsetzbare Reparaturhinweise aus, wenn er fehlt.
- **Auto-Provider**: Prüft zuerst die Verfügbarkeit des lokalen Modells und versucht dann jeden Remote-Provider in der Reihenfolge der automatischen Auswahl.
Wenn ein zwischengespeichertes Ergebnis einer Gateway-Prüfung verfügbar ist (das Gateway war zum Zeitpunkt der Prüfung fehlerfrei), gleicht Doctor dessen Ergebnis mit der für die CLI sichtbaren Konfiguration ab und weist auf Abweichungen hin. Doctor startet im Standardpfad keinen neuen Embedding-Ping; verwenden Sie den tiefgehenden Speicherstatusbefehl, wenn Sie eine Live-Prüfung des Providers wünschen.
Wenn ein zwischengespeichertes Gateway-Prüfergebnis verfügbar ist (das Gateway war zum Zeitpunkt der Prüfung fehlerfrei), gleicht doctor dessen Ergebnis mit der für die CLI sichtbaren Konfiguration ab und weist auf Abweichungen hin. Doctor startet im Standardpfad keinen neuen Embedding-Ping; verwenden Sie den ausführlichen Speicherstatusbefehl, wenn Sie eine Live-Prüfung des Providers wünschen.
Verwenden Sie `openclaw memory status --deep`, um die Embedding-Bereitschaft zur Laufzeit zu prüfen.
Verwenden Sie `openclaw memory status --deep`, um die Embedding-Bereitschaft zur Laufzeit zu überprüfen.
</Accordion>
<Accordion title="14. Kanalstatus-Warnungen">
Wenn das Gateway fehlerfrei ist, führt Doctor eine Kanalstatusprüfung aus und meldet Warnungen mit vorgeschlagenen Behebungen.
<Accordion title="14. Kanalstatuswarnungen">
Wenn das Gateway fehlerfrei ist, führt doctor eine Kanalstatusprüfung aus und meldet Warnungen mit vorgeschlagenen Reparaturen.
</Accordion>
<Accordion title="15. Supervisor-Konfigurationsaudit + Reparatur">
Doctor prüft die installierte Supervisor-Konfiguration (launchd/systemd/schtasks) auf fehlende oder veraltete Standards (z. B. systemd-Abhängigkeiten von network-online und Neustartverzögerung). Wenn eine Abweichung gefunden wird, empfiehlt Doctor eine Aktualisierung und kann die Servicedatei/Aufgabe auf die aktuellen Standards umschreiben.
<Accordion title="15. Supervisor-Konfigurationsprüfung + Reparatur">
Doctor prüft die installierte Supervisor-Konfiguration (launchd/systemd/schtasks) auf fehlende oder veraltete Standardwerte (z. B. systemd-Abhängigkeiten von network-online und Neustartverzögerung). Wenn eine Abweichung gefunden wird, empfiehlt es eine Aktualisierung und kann die Servicedatei/Aufgabe auf die aktuellen Standardwerte umschreiben.
Hinweise:
- `openclaw doctor` fragt vor dem Umschreiben der Supervisor-Konfiguration nach.
- `openclaw doctor --yes` akzeptiert die Standard-Reparaturabfragen.
- `openclaw doctor --repair` wendet empfohlene Behebungen ohne Nachfragen an.
- `openclaw doctor --repair --force` überschreibt angepasste Supervisor-Konfigurationen.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` hält Doctor für den Gateway-Service-Lebenszyklus schreibgeschützt. Servicezustand wird weiterhin gemeldet und Nicht-Service-Reparaturen werden ausgeführt, aber Serviceinstallation/-start/-neustart/-bootstrap, Umschreiben der Supervisor-Konfiguration und Bereinigung veralteter Services werden übersprungen, da ein externer Supervisor diesen Lebenszyklus besitzt.
- Unter Linux schreibt Doctor Befehls-/Einstiegspunkt-Metadaten nicht um, während die passende systemd-Gateway-Unit aktiv ist. Außerdem ignoriert Doctor inaktive zusätzliche nicht-veraltete Gateway-ähnliche Units während der Suche nach doppelten Services, damit begleitende Servicedateien keinen Bereinigungsrauschen erzeugen.
- Wenn Token-Auth ein Token erfordert und `gateway.auth.token` von SecretRef verwaltet wird, validiert die Doctor-Serviceinstallation/-reparatur die SecretRef, speichert aber keine aufgelösten Klartext-Tokenwerte in den Umgebungsmetadaten des Supervisor-Service.
- Doctor erkennt verwaltete `.env`-/SecretRef-gestützte Service-Umgebungswerte, die ältere LaunchAgent-, systemd- oder Windows-Scheduled-Task-Installationen inline eingebettet haben, und schreibt die Servicemetadaten so um, dass diese Werte aus der Laufzeitquelle statt aus der Supervisor-Definition geladen werden.
- Doctor erkennt, wenn der Servicebefehl nach Änderungen an `gateway.port` weiterhin einen alten `--port` festlegt, und schreibt die Servicemetadaten auf den aktuellen Port um.
- Wenn Token-Auth ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst werden kann, blockiert Doctor den Installations-/Reparaturpfad mit umsetzbaren Hinweisen.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, blockiert Doctor Installation/Reparatur, bis der Modus ausdrücklich gesetzt ist.
- Für Linux-user-systemd-Units berücksichtigen die Token-Drift-Prüfungen von Doctor jetzt sowohl `Environment=`- als auch `EnvironmentFile=`-Quellen beim Vergleich der Service-Auth-Metadaten.
- `openclaw doctor` fragt nach, bevor die Supervisor-Konfiguration umgeschrieben wird.
- `openclaw doctor --yes` akzeptiert die Standard-Reparaturaufforderungen.
- `openclaw doctor --repair` wendet empfohlene Reparaturen ohne Nachfragen an.
- `openclaw doctor --repair --force` überschreibt benutzerdefinierte Supervisor-Konfigurationen.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` hält doctor für den Gateway-Service-Lebenszyklus schreibgeschützt. Es meldet weiterhin den Servicezustand und führt Nicht-Service-Reparaturen aus, überspringt aber Serviceinstallation/-start/-neustart/-bootstrap, Umschreibungen der Supervisor-Konfiguration und die Bereinigung veralteter Services, weil ein externer Supervisor diesen Lebenszyklus besitzt.
- Unter Linux schreibt doctor keine Befehls-/Entrypoint-Metadaten um, solange die passende systemd-Gateway-Unit aktiv ist. Außerdem ignoriert es inaktive, nicht veraltete zusätzliche Gateway-ähnliche Units während der Suche nach doppelten Services, damit begleitende Servicedateien keinen Bereinigungsrauschen erzeugen.
- Wenn Token-Authentifizierung ein Token erfordert und `gateway.auth.token` über SecretRef verwaltet wird, validiert die doctor-Serviceinstallation/-reparatur den SecretRef, speichert aber keine aufgelösten Klartext-Tokenwerte in den Umgebungsmetadaten des Supervisor-Service.
- Doctor erkennt verwaltete `.env`-/SecretRef-gestützte Serviceumgebungswerte, die ältere LaunchAgent-, systemd- oder Windows-Scheduled-Task-Installationen inline eingebettet haben, und schreibt die Servicemetadaten so um, dass diese Werte aus der Laufzeitquelle statt aus der Supervisor-Definition geladen werden.
- Doctor erkennt, wenn der Servicebefehl nach Änderungen an `gateway.port` noch einen alten `--port` festlegt, und schreibt die Servicemetadaten auf den aktuellen Port um.
- Wenn Token-Authentifizierung ein Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst ist, blockiert doctor den Installations-/Reparaturpfad mit umsetzbaren Hinweisen.
- Wenn sowohl `gateway.auth.token` als auch `gateway.auth.password` konfiguriert sind und `gateway.auth.mode` nicht gesetzt ist, blockiert doctor Installation/Reparatur, bis der Modus explizit gesetzt ist.
- Für Linux-user-systemd-Units beziehen doctor-Prüfungen auf Token-Abweichungen jetzt sowohl `Environment=`- als auch `EnvironmentFile=`-Quellen ein, wenn Service-Auth-Metadaten verglichen werden.
- Doctor-Service-Reparaturen verweigern das Umschreiben, Stoppen oder Neustarten eines Gateway-Service aus einer älteren OpenClaw-Binärdatei, wenn die Konfiguration zuletzt von einer neueren Version geschrieben wurde. Siehe [Gateway-Fehlerbehebung](/de/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Sie können jederzeit ein vollständiges Umschreiben über `openclaw gateway install --force` erzwingen.
- Sie können jederzeit ein vollständiges Umschreiben mit `openclaw gateway install --force` erzwingen.
</Accordion>
<Accordion title="16. Gateway-Laufzeit + Portdiagnose">
Doctor prüft die Service-Laufzeit (PID, letzter Exit-Status) und warnt, wenn der Service installiert ist, aber nicht tatsächlich läuft. Außerdem wird auf Portkonflikte am Gateway-Port (Standard `18789`) geprüft und wahrscheinliche Ursachen werden gemeldet (Gateway läuft bereits, SSH-Tunnel).
Doctor prüft die Servicelaufzeit (PID, letzter Exit-Status) und warnt, wenn der Service installiert ist, aber nicht tatsächlich läuft. Außerdem prüft es auf Portkollisionen am Gateway-Port (Standard `18789`) und meldet wahrscheinliche Ursachen (Gateway läuft bereits, SSH-Tunnel).
</Accordion>
<Accordion title="17. Bewährte Verfahren für die Gateway-Laufzeit">
Doctor warnt, wenn der Gateway-Service auf Bun oder einem versionsverwalteten Node-Pfad (`nvm`, `fnm`, `volta`, `asdf` usw.) läuft. WhatsApp- und Telegram-Kanäle erfordern Node, und Pfade von Versionsmanagern können nach Upgrades brechen, da der Service Ihre Shell-Initialisierung nicht lädt. Doctor bietet an, zu einer System-Node-Installation zu migrieren, sofern verfügbar (Homebrew/apt/choco).
<Accordion title="17. Bewährte Praktiken für die Gateway-Laufzeit">
Doctor warnt, wenn der Gateway-Service auf Bun oder einem versionsverwalteten Node-Pfad (`nvm`, `fnm`, `volta`, `asdf` usw.) läuft. WhatsApp- und Telegram-Kanäle erfordern Node, und Versionsmanager-Pfade können nach Upgrades brechen, weil der Service Ihre Shell-Initialisierung nicht lädt. Doctor bietet an, zu einer System-Node-Installation zu migrieren, wenn sie verfügbar ist (Homebrew/apt/choco).
Neu installierte oder reparierte macOS-LaunchAgents verwenden einen kanonischen System-PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`), statt den interaktiven Shell-PATH zu kopieren. Dadurch ändern Volta, asdf, fnm, pnpm und andere Versionsmanager-Verzeichnisse nicht, welche Node-Kindprozesse aufgelöst werden. Linux-Services behalten weiterhin explizite Umgebungswurzeln (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) und stabile Benutzer-bin-Verzeichnisse bei, aber vermutete Fallback-Verzeichnisse von Versionsmanagern werden nur dann in den Service-PATH geschrieben, wenn diese Verzeichnisse auf dem Datenträger existieren.
Neu installierte oder reparierte macOS-LaunchAgents verwenden einen kanonischen System-PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`), statt den interaktiven Shell-PATH zu kopieren, sodass Volta-, asdf-, fnm-, pnpm- und andere Versionsmanager-Verzeichnisse nicht ändern, welche Node-Kindprozesse aufgelöst werden. Linux-Services behalten weiterhin explizite Umgebungswurzeln (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) und stabile Benutzer-bin-Verzeichnisse bei, aber erratene Fallback-Verzeichnisse von Versionsmanagern werden nur dann in den Service-PATH geschrieben, wenn diese Verzeichnisse auf der Festplatte existieren.
</Accordion>
<Accordion title="18. Schreiben der Konfiguration + Wizard-Metadaten">
Doctor speichert alle Konfigurationsänderungen und versieht die Wizard-Metadaten mit einem Eintrag, um den Doctor-Lauf zu protokollieren.
<Accordion title="18. Konfigurationsschreiben + Wizard-Metadaten">
Doctor speichert alle Konfigurationsänderungen dauerhaft und versieht Wizard-Metadaten mit einem Zeitstempel, um den doctor-Lauf zu erfassen.
</Accordion>
<Accordion title="19. Workspace-Tipps (Backup + Speichersystem)">
Doctor schlägt ein Workspace-Speichersystem vor, wenn es fehlt, und gibt einen Backup-Tipp aus, wenn der Workspace noch nicht unter git steht.
Siehe [/concepts/agent-workspace](/de/concepts/agent-workspace) für eine vollständige Anleitung zur Workspace-Struktur und zum git-Backup (empfohlen: privates GitHub oder GitLab).
Siehe [/concepts/agent-workspace](/de/concepts/agent-workspace) für eine vollständige Anleitung zur Workspace-Struktur und git-Backup (empfohlen: privates GitHub oder GitLab).
</Accordion>
</AccordionGroup>

97
docs/de/gateway/logging.md
View File

@ -5,10 +5,10 @@ read_when:
summary: Logging-Oberflächen, Datei-Logs, WS-Log-Stile und Konsolenformatierung
title: Gateway-Protokollierung
x-i18n:
generated_at: "2026-05-02T06:33:33Z"
generated_at: "2026-05-05T01:46:37Z"
model: gpt-5.5
provider: openai
source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13
source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246
source_path: gateway/logging.md
workflow: 16
---
@ -17,18 +17,29 @@ x-i18n:
Eine benutzerorientierte Übersicht (CLI + Control UI + Konfiguration) finden Sie unter [/logging](/de/logging).
OpenClaw hat zwei Log-„Oberflächen“:
OpenClaw hat zwei Protokollierungs-„Oberflächen“:
- **Konsolenausgabe** (was Sie im Terminal / in der Debug-Oberfläche sehen).
- **Datei-Logs** (JSON-Zeilen), geschrieben vom Gateway-Logger.
- **Konsolenausgabe** (was Sie im Terminal / in der Debug-UI sehen).
- **Dateiprotokolle** (JSON-Zeilen), die vom Gateway-Logger geschrieben werden.
Beim Start protokolliert das Gateway das aufgelöste standardmäßige Agentenmodell zusammen mit den
Modus-Standardwerten, die neue Sitzungen betreffen, zum Beispiel:
```text
agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)
```
`thinking` stammt vom Standard-Agenten, von Modellparametern oder vom globalen Agentenstandard;
wenn es nicht gesetzt ist, zeigt die Startzusammenfassung `medium`. `fast` stammt vom
Standard-Agenten oder aus den `fastMode`-Parametern des Modells.
## Dateibasierter Logger
- Die standardmäßige rotierende Logdatei liegt unter `/tmp/openclaw/` (eine Datei pro Tag): `openclaw-YYYY-MM-DD.log`
- Die standardmäßige rotierende Protokolldatei liegt unter `/tmp/openclaw/` (eine Datei pro Tag): `openclaw-YYYY-MM-DD.log`
- Das Datum verwendet die lokale Zeitzone des Gateway-Hosts.
- Aktive Logdateien rotieren bei `logging.maxFileBytes` (Standard: 100 MB), behalten
bis zu fünf nummerierte Archive und schreiben anschließend in eine neue aktive Datei weiter.
- Der Pfad und das Level der Logdatei können über `~/.openclaw/openclaw.json` konfiguriert werden:
- Aktive Protokolldateien rotieren bei `logging.maxFileBytes` (Standard: 100 MB), behalten
bis zu fünf nummerierte Archive und schreiben anschließend in eine neue aktive Datei.
- Pfad und Level der Protokolldatei können über `~/.openclaw/openclaw.json` konfiguriert werden:
- `logging.file`
- `logging.level`
@ -43,61 +54,61 @@ openclaw logs --follow
**Ausführlichkeit vs. Log-Level**
- **Datei-Logs** werden ausschließlich durch `logging.level` gesteuert.
- `--verbose` wirkt sich nur auf die **Konsolenausführlichkeit** (und den WS-Logstil) aus; es erhöht **nicht**
das Datei-Log-Level.
- Um nur bei ausführlicher Ausgabe verfügbare Details in Datei-Logs zu erfassen, setzen Sie `logging.level` auf `debug` oder
- **Dateiprotokolle** werden ausschließlich durch `logging.level` gesteuert.
- `--verbose` wirkt sich nur auf die **Konsolenausführlichkeit** (und den WS-Protokollstil) aus; es erhöht **nicht**
das Log-Level der Datei.
- Um nur bei ausführlicher Ausgabe sichtbare Details in Dateiprotokollen zu erfassen, setzen Sie `logging.level` auf `debug` oder
`trace`.
- Trace-Logging enthält außerdem diagnostische Timing-Zusammenfassungen für ausgewählte Hot Paths,
etwa die Vorbereitung der Plugin-Tool-Factory. Siehe
- Trace-Protokollierung enthält außerdem diagnostische Timing-Zusammenfassungen für ausgewählte Hot Paths,
wie etwa die Vorbereitung von Plugin-Tool-Factories. Siehe
[/tools/plugin#slow-plugin-tool-setup](/de/tools/plugin#slow-plugin-tool-setup).
## Konsolenerfassung
Die CLI erfasst `console.log/info/warn/error/debug/trace` und schreibt sie in Datei-Logs,
während sie weiterhin nach stdout/stderr ausgibt.
Die CLI erfasst `console.log/info/warn/error/debug/trace` und schreibt sie in Dateiprotokolle,
während sie weiterhin auf stdout/stderr ausgibt.
Sie können die Konsolenausführlichkeit unabhängig anpassen über:
Sie können die Konsolenausführlichkeit unabhängig einstellen über:
- `logging.consoleLevel` (Standard `info`)
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
## Maskierung
## Schwärzung
OpenClaw kann sensible Tokens maskieren, bevor Log- oder Transkriptausgabe den
Prozess verlässt. Diese Maskierungsrichtlinie für Logging wird auf Text-Sinks für Konsole, Datei-Logs, OTLP-
Logeinträge und Sitzungsprotokolle angewendet, sodass übereinstimmende geheime Werte
OpenClaw kann sensible Tokens maskieren, bevor Protokoll- oder Transkriptausgaben den
Prozess verlassen. Diese Richtlinie zur Protokollschwärzung wird auf Text-Senken für Konsole, Dateiprotokoll, OTLP-
Log-Record und Sitzungstranskript angewendet, sodass übereinstimmende geheime Werte
maskiert werden, bevor JSONL-Zeilen oder Nachrichten auf die Festplatte geschrieben werden.
- `logging.redactSensitive`: `off` | `tools` (Standard: `tools`)
- `logging.redactPatterns`: Array von Regex-Strings (überschreibt die Standardwerte)
- `logging.redactPatterns`: Array von Regex-Strings (überschreibt Standardwerte)
- Verwenden Sie rohe Regex-Strings (automatisch `gi`) oder `/pattern/flags`, wenn Sie benutzerdefinierte Flags benötigen.
- Treffer werden maskiert, indem die ersten 6 + letzten 4 Zeichen behalten werden (Länge >= 18), andernfalls `***`.
- Die Standardwerte decken gängige Schlüsselzuweisungen, CLI-Flags, JSON-Felder, Bearer-Header, PEM-Blöcke, verbreitete Token-Präfixe und Feldnamen für Zahlungsdaten wie Kartennummer, CVC/CVV, geteiltes Zahlungstoken und Zahlungsdaten ab.
- Treffer werden maskiert, indem die ersten 6 + letzten 4 Zeichen beibehalten werden (Länge >= 18), andernfalls `***`.
- Standardwerte decken gängige Schlüsselzuweisungen, CLI-Flags, JSON-Felder, Bearer-Header, PEM-Blöcke, verbreitete Token-Präfixe und Feldnamen für Zahlungszugangsdaten wie Kartennummer, CVC/CVV, gemeinsames Zahlungstoken und Zahlungszugangsdaten ab.
Einige Sicherheitsgrenzen maskieren immer, unabhängig von `logging.redactSensitive`.
Dazu gehören Tool-Call-Ereignisse der Control UI, `sessions_history`-Tool-Ausgabe,
Einige Sicherheitsgrenzen schwärzen immer, unabhängig von `logging.redactSensitive`.
Dazu gehören Tool-Call-Ereignisse der Control UI, Tool-Ausgaben von `sessions_history`,
Diagnose-Support-Exporte, Provider-Fehlerbeobachtungen, die Anzeige von Exec-Freigabebefehlen
und Gateway-WebSocket-Protokoll-Logs. Diese Oberflächen können weiterhin
und Gateway-WebSocket-Protokolle. Diese Oberflächen können weiterhin
`logging.redactPatterns` als zusätzliche Muster verwenden, aber `redactSensitive: "off"`
führt nicht dazu, dass sie rohe Geheimnisse ausgeben.
führt nicht dazu, dass sie rohe geheime Werte ausgeben.
## Gateway-WebSocket-Logs
## Gateway-WebSocket-Protokolle
Das Gateway gibt WebSocket-Protokoll-Logs in zwei Modi aus:
Das Gateway gibt WebSocket-Protokolle in zwei Modi aus:
- **Normalmodus (kein `--verbose`)**: Nur „interessante“ RPC-Ergebnisse werden ausgegeben:
- **Normaler Modus (kein `--verbose`)**: Nur „interessante“ RPC-Ergebnisse werden ausgegeben:
- Fehler (`ok=false`)
- langsame Aufrufe (Standardschwellenwert: `>= 50ms`)
- langsame Aufrufe (Standardschwelle: `>= 50ms`)
- Parse-Fehler
- **Ausführlicher Modus (`--verbose`)**: Gibt den gesamten WS-Anfrage-/Antwortverkehr aus.
### WS-Logstil
### WS-Protokollstil
`openclaw gateway` unterstützt eine Stilumschaltung pro Gateway:
`openclaw gateway` unterstützt einen Stil-Umschalter pro Gateway:
- `--ws-log auto` (Standard): Normalmodus ist optimiert; ausführlicher Modus verwendet kompakte Ausgabe
- `--ws-log compact`: kompakte Ausgabe (gepaarte Anfrage/Antwort) bei ausführlicher Ausgabe
- `--ws-log auto` (Standard): normaler Modus ist optimiert; ausführlicher Modus verwendet kompakte Ausgabe
- `--ws-log compact`: kompakte Ausgabe (gekoppelte Anfrage/Antwort) bei ausführlicher Ausgabe
- `--ws-log full`: vollständige Ausgabe pro Frame bei ausführlicher Ausgabe
- `--compact`: Alias für `--ws-log compact`
@ -114,24 +125,24 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Konsolenformatierung (Subsystem-Logging)
## Konsolenformatierung (Subsystem-Protokollierung)
Der Konsolenformatter ist **TTY-bewusst** und gibt konsistente, präfixierte Zeilen aus.
Subsystem-Logger halten die Ausgabe gruppiert und gut scanbar.
Subsystem-Logger halten Ausgaben gruppiert und gut erfassbar.
Verhalten:
- **Subsystem-Präfixe** in jeder Zeile (z. B. `[gateway]`, `[canvas]`, `[tailscale]`)
- **Subsystem-Farben** (stabil pro Subsystem) plus Level-Färbung
- **Subsystem-Farben** (stabil pro Subsystem) plus Level-Farbgebung
- **Farbe, wenn die Ausgabe ein TTY ist oder die Umgebung wie ein Rich-Terminal wirkt** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), berücksichtigt `NO_COLOR`
- **Verkürzte Subsystem-Präfixe**: entfernt führendes `gateway/` + `channels/`, behält die letzten 2 Segmente (z. B. `whatsapp/outbound`)
- **Verkürzte Subsystem-Präfixe**: entfernt führende `gateway/` + `channels/`, behält die letzten 2 Segmente (z. B. `whatsapp/outbound`)
- **Sub-Logger nach Subsystem** (automatisches Präfix + strukturiertes Feld `{ subsystem }`)
- **`logRaw()`** für QR-/UX-Ausgabe (kein Präfix, keine Formatierung)
- **Konsolenstile** (z. B. `pretty | compact | json`)
- **Konsolen-Log-Level** getrennt vom Datei-Log-Level (Datei behält vollständige Details, wenn `logging.level` auf `debug`/`trace` gesetzt ist)
- **WhatsApp-Nachrichtentexte** werden mit `debug` protokolliert (verwenden Sie `--verbose`, um sie zu sehen)
- **WhatsApp-Nachrichtentexte** werden auf `debug` protokolliert (verwenden Sie `--verbose`, um sie zu sehen)
Dadurch bleiben bestehende Datei-Logs stabil, während interaktive Ausgaben gut scanbar werden.
Dadurch bleiben bestehende Dateiprotokolle stabil, während interaktive Ausgaben gut erfassbar werden.
## Verwandte Themen

131
docs/de/help/debugging.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Sie müssen die unverarbeitete Modellausgabe auf durchgesickerte Schlussfolgerungsinhalte prüfen
- Sie möchten den Gateway während der Iteration im Watch-Modus ausführen
- Sie müssen die unverarbeitete Modellausgabe auf unbeabsichtigte Offenlegung von Begründungsinhalten prüfen
- Sie möchten das Gateway im Watch-Modus ausführen, während Sie iterieren
- Sie benötigen einen wiederholbaren Debugging-Workflow
summary: 'Werkzeuge zur Fehlersuche: Überwachungsmodus, rohe Modell-Datenströme und Nachverfolgung von Lecks in der Schlussfolgerung'
summary: 'Debugging-Tools: Watch-Modus, unverarbeitete Modell-Datenströme und Nachverfolgung von Reasoning-Leaks'
title: Fehlersuche
x-i18n:
generated_at: "2026-05-03T21:34:15Z"
generated_at: "2026-05-05T01:46:59Z"
model: gpt-5.5
provider: openai
source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc
source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec
source_path: help/debugging.md
workflow: 16
---
Debugging-Hilfen für Streaming-Ausgabe, insbesondere wenn ein Provider Reasoning in normalen Text mischt.
## Debug-Overrides zur Laufzeit
## Debug-Überschreibungen zur Laufzeit
Verwenden Sie `/debug` im Chat, um **nur zur Laufzeit geltende** Konfigurations-Overrides zu setzen (Speicher, nicht Datenträger).
Verwenden Sie `/debug` im Chat, um **nur zur Laufzeit geltende** Konfigurationsüberschreibungen festzulegen (Speicher, nicht Datenträger).
`/debug` ist standardmäßig deaktiviert; aktivieren Sie es mit `commands.debug: true`.
Das ist praktisch, wenn Sie schwer auffindbare Einstellungen umschalten müssen, ohne `openclaw.json` zu bearbeiten.
@ -31,7 +31,7 @@ Beispiele:
/debug reset
```
`/debug reset` löscht alle Overrides und kehrt zur Konfiguration auf dem Datenträger zurück.
`/debug reset` löscht alle Überschreibungen und kehrt zur Konfiguration auf dem Datenträger zurück.
## Sitzungs-Trace-Ausgabe
@ -46,16 +46,16 @@ Beispiele:
/trace off
```
Verwenden Sie `/trace` für Plugin-Diagnosen wie Active Memory Debug-Zusammenfassungen.
Nutzen Sie weiterhin `/verbose` für normale ausführliche Status-/Tool-Ausgabe, und nutzen Sie weiterhin
`/debug` für nur zur Laufzeit geltende Konfigurations-Overrides.
Verwenden Sie `/trace` für Plugin-Diagnosen wie Debug-Zusammenfassungen von Active Memory.
Verwenden Sie weiterhin `/verbose` für normale ausführliche Status-/Tool-Ausgabe und weiterhin
`/debug` für nur zur Laufzeit geltende Konfigurationsüberschreibungen.
## Plugin-Lebenszyklus-Trace
Verwenden Sie `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`, wenn Plugin-Lebenszyklusbefehle langsam wirken
und Sie eine eingebaute Phasenaufschlüsselung für Plugin-Metadaten, Erkennung, Registry,
Runtime-Mirror, Konfigurationsänderungen und Aktualisierungsarbeit benötigen. Der Trace ist optional und schreibt
nach stderr, sodass JSON-Befehlsausgabe weiterhin parsebar bleibt.
und Sie eine integrierte Phasenaufschlüsselung für Plugin-Metadaten, Erkennung, Registry,
Runtime-Spiegelung, Konfigurationsänderungen und Aktualisierungsarbeiten benötigen. Der Trace ist optional und schreibt
nach stderr, sodass JSON-Befehlsausgaben weiterhin parsebar bleiben.
Beispiel:
@ -72,7 +72,7 @@ Beispielausgabe:
```
Verwenden Sie dies für Untersuchungen des Plugin-Lebenszyklus, bevor Sie zu einem CPU-Profiler greifen.
Wenn der Befehl aus einem Source-Checkout ausgeführt wird, bevorzugen Sie die Messung der gebauten
Wenn der Befehl aus einem Source-Checkout ausgeführt wird, messen Sie bevorzugt die gebaute
Runtime mit `node dist/entry.js ...` nach `pnpm build`; `pnpm openclaw ...`
misst außerdem den Overhead des Source-Runners.
@ -93,8 +93,18 @@ Für einmaliges Profiling über den normalen Source-Runner setzen Sie
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
```
Der Source-Runner fügt Node-CPU-Profilflags hinzu und schreibt ein `.cpuprofile` für den
Befehl. Verwenden Sie dies, bevor Sie temporäre Instrumentierung zum Befehlscode hinzufügen.
Der Source-Runner fügt Node-CPU-Profil-Flags hinzu und schreibt ein `.cpuprofile` für den
Befehl. Verwenden Sie dies, bevor Sie temporäre Instrumentierung zu Befehlscode hinzufügen.
Für Start-Hänger, die wie synchrone Dateisystem- oder Module-Loader-Arbeit aussehen,
fügen Sie Nodes Sync-I/O-Trace-Flag über den Source-Runner hinzu:
```bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```
`pnpm gateway:watch` aktiviert dieses Flag standardmäßig für das überwachte Gateway-Kind.
Setzen Sie `OPENCLAW_TRACE_SYNC_IO=0`, um Node-Sync-I/O-Trace-Ausgabe im Watch-Modus zu unterdrücken.
## Gateway-Watch-Modus
@ -107,7 +117,7 @@ pnpm gateway:watch
Standardmäßig startet oder startet dies eine tmux-Sitzung namens
`openclaw-gateway-watch-main` neu (oder eine profil-/portspezifische Variante wie
`openclaw-gateway-watch-dev-19001`) und hängt sich von interaktiven Terminals automatisch an.
Nicht interaktive Shells, CI und Agent-Exec-Aufrufe bleiben getrennt und geben stattdessen
Nicht-interaktive Shells, CI und Agent-Exec-Aufrufe bleiben getrennt und geben stattdessen
Anweisungen zum Anhängen aus. Hängen Sie sich bei Bedarf manuell an:
```bash
@ -128,21 +138,21 @@ pnpm gateway:watch:raw
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
```
Deaktivieren Sie das automatische Anhängen, behalten Sie aber die tmux-Verwaltung bei:
Deaktivieren Sie das automatische Anhängen, während die tmux-Verwaltung beibehalten wird:
```bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```
Profilieren Sie die CPU-Zeit des beobachteten Gateway beim Debuggen von Start-/Runtime-Hotspots:
Profilieren Sie die CPU-Zeit des überwachten Gateway, wenn Sie Start-/Runtime-Hotspots debuggen:
```bash
pnpm gateway:watch --benchmark
```
Der Watch-Wrapper verarbeitet `--benchmark`, bevor er das Gateway aufruft, und schreibt
bei jedem Beenden eines Gateway-Kindprozesses ein V8-`.cpuprofile` unter
`.artifacts/gateway-watch-profiles/`. Stoppen oder starten Sie das beobachtete Gateway neu, um
Der Watch-Wrapper verbraucht `--benchmark`, bevor er das Gateway aufruft, und schreibt
pro Exit eines Gateway-Kinds ein V8-`.cpuprofile` unter
`.artifacts/gateway-watch-profiles/`. Stoppen oder starten Sie das überwachte Gateway neu, um
das aktuelle Profil zu schreiben, und öffnen Sie es dann mit Chrome DevTools oder Speedscope:
```bash
@ -150,44 +160,49 @@ npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
```
Verwenden Sie `--benchmark-dir <path>`, wenn Sie Profile an einem anderen Ort speichern möchten.
Verwenden Sie `--benchmark-no-force`, wenn der benchmarkierte Kindprozess die
standardmäßige `--force`-Portbereinigung überspringen und schnell fehlschlagen soll, falls der Gateway-Port bereits
belegt ist.
Verwenden Sie `--benchmark-no-force`, wenn das benchmarkte Kind die standardmäßige
`--force`-Portbereinigung überspringen und schnell fehlschlagen soll, falls der Gateway-Port bereits
verwendet wird.
Der Benchmark-Modus unterdrückt Sync-I/O-Trace-Spam standardmäßig. Setzen Sie
`OPENCLAW_TRACE_SYNC_IO=1` mit `--benchmark`, wenn Sie ausdrücklich sowohl CPU-Profile
als auch Node-Sync-I/O-Stacktraces wünschen. Im Benchmark-Modus werden diese Trace-Blöcke
in `gateway-watch-output.log` unter dem Benchmark-Verzeichnis geschrieben und
aus dem Terminalbereich herausgefiltert; normale Gateway-Logs bleiben sichtbar.
Der tmux-Wrapper übernimmt gängige nicht geheime Runtime-Selektoren wie
Der tmux-Wrapper übernimmt gängige nicht geheime Runtime-Auswahlen wie
`OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`,
`OPENCLAW_GATEWAY_PORT` und `OPENCLAW_SKIP_CHANNELS` in den Bereich. Legen Sie
Provider-Zugangsdaten in Ihrem normalen Profil/Ihrer normalen Konfiguration ab, oder verwenden Sie den rohen Vordergrundmodus
für einmalige flüchtige Secrets.
Wenn das beobachtete Gateway während des Starts beendet wird, führt der Watcher einmal
`openclaw doctor --fix --non-interactive` aus und startet den Gateway-Kindprozess neu.
Wenn das überwachte Gateway während des Starts beendet wird, führt der Watcher einmal
`openclaw doctor --fix --non-interactive` aus und startet das Gateway-Kind neu.
Verwenden Sie `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0`, wenn Sie den ursprünglichen Startfehler
ohne den nur für Entwicklung gedachten Reparaturdurchlauf sehen möchten.
ohne den nur für die Entwicklung gedachten Reparaturdurchlauf möchten.
Der verwaltete tmux-Bereich verwendet außerdem standardmäßig farbige Gateway-Logs für bessere Lesbarkeit;
setzen Sie `FORCE_COLOR=0`, wenn Sie `pnpm gateway:watch` starten, um ANSI-Ausgabe zu deaktivieren.
Der Watcher startet bei buildrelevanten Dateien unter `src/`, Extension-Quelldateien,
Der Watcher startet bei build-relevanten Dateien unter `src/`, Extension-Quelldateien,
Extension-`package.json`- und `openclaw.plugin.json`-Metadaten, `tsconfig.json`,
`package.json` und `tsdown.config.ts` neu. Änderungen an Extension-Metadaten starten das
Gateway neu, ohne einen `tsdown`-Rebuild zu erzwingen; Quell- und Konfigurationsänderungen bauen weiterhin
zuerst `dist`.
Gateway neu, ohne einen `tsdown`-Rebuild zu erzwingen; Source- und Konfigurationsänderungen
bauen weiterhin zuerst `dist`.
Fügen Sie Gateway-CLI-Flags nach `gateway:watch` hinzu, und sie werden bei
jedem Neustart durchgereicht. Das erneute Ausführen desselben Watch-Befehls startet den benannten tmux-Bereich neu, und
der rohe Watcher behält weiterhin seine Einzel-Watcher-Sperre bei, sodass doppelte Watcher-Elternprozesse
Fügen Sie beliebige Gateway-CLI-Flags nach `gateway:watch` hinzu; sie werden bei
jedem Neustart durchgereicht. Das erneute Ausführen desselben Watch-Befehls erzeugt den benannten tmux-Bereich neu, und
der rohe Watcher behält weiterhin seine Einzel-Watcher-Sperre bei, sodass doppelte Watcher-Eltern
ersetzt werden, statt sich anzusammeln.
## Dev-Profil + Dev-Gateway (--dev)
## Entwicklungsprofil + Entwicklungs-Gateway (--dev)
Verwenden Sie das Dev-Profil, um Zustand zu isolieren und eine sichere, wegwerfbare Einrichtung zum
Debuggen zu starten. Es gibt **zwei** `--dev`-Flags:
Verwenden Sie das Entwicklungsprofil, um State zu isolieren und ein sicheres, wegwerfbares Setup für
Debugging zu starten. Es gibt **zwei** `--dev`-Flags:
- **Globales `--dev` (Profil):** isoliert Zustand unter `~/.openclaw-dev` und
- **Globales `--dev` (Profil):** isoliert State unter `~/.openclaw-dev` und
setzt den Gateway-Port standardmäßig auf `19001` (abgeleitete Ports verschieben sich entsprechend).
- **`gateway --dev`: weist das Gateway an, bei Bedarf automatisch eine Standardkonfiguration +
Workspace zu erstellen** (und BOOTSTRAP.md zu überspringen).
- **`gateway --dev`: weist das Gateway an, bei Fehlen automatisch eine Standardkonfiguration +
einen Workspace zu erstellen** (und BOOTSTRAP.md zu überspringen).
Empfohlener Ablauf (Dev-Profil + Dev-Bootstrap):
Empfohlener Ablauf (Entwicklungsprofil + Entwicklungs-Bootstrap):
```bash
pnpm gateway:dev
@ -204,14 +219,14 @@ Das bewirkt Folgendes:
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
- `OPENCLAW_GATEWAY_PORT=19001` (Browser/Canvas verschieben sich entsprechend)
2. **Dev-Bootstrap** (`gateway --dev`)
- Schreibt eine minimale Konfiguration, falls sie fehlt (`gateway.mode=local`, bind local loopback).
- Setzt `agent.workspace` auf den Dev-Workspace.
2. **Entwicklungs-Bootstrap** (`gateway --dev`)
- Schreibt bei Fehlen eine minimale Konfiguration (`gateway.mode=local`, bind loopback).
- Setzt `agent.workspace` auf den Entwicklungs-Workspace.
- Setzt `agent.skipBootstrap=true` (kein BOOTSTRAP.md).
- Erstellt fehlende Workspace-Dateien:
- Seedet die Workspace-Dateien, falls sie fehlen:
`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`.
- Standardidentität: **C3‑PO** (Protokolldroide).
- Überspringt Channel-Provider im Dev-Modus (`OPENCLAW_SKIP_CHANNELS=1`).
- Überspringt Channel-Provider im Entwicklungsmodus (`OPENCLAW_SKIP_CHANNELS=1`).
Reset-Ablauf (frischer Start):
@ -220,7 +235,7 @@ pnpm gateway:dev:reset
```
<Note>
`--dev` ist ein **globales** Profilflag und wird von einigen Runnern verbraucht. Wenn Sie es ausdrücklich angeben müssen, verwenden Sie die Env-Var-Form:
`--dev` ist ein **globales** Profil-Flag und wird von einigen Runnern verbraucht. Wenn Sie es explizit angeben müssen, verwenden Sie die Env-Var-Form:
```bash
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
@ -228,11 +243,11 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
</Note>
`--reset` löscht Konfiguration, Zugangsdaten, Sitzungen und den Dev-Workspace (mit
`trash`, nicht `rm`) und erstellt dann die Standard-Dev-Einrichtung neu.
`--reset` löscht Konfiguration, Zugangsdaten, Sitzungen und den Entwicklungs-Workspace (mit
`trash`, nicht `rm`) und erstellt dann das Standard-Entwicklungs-Setup neu.
<Tip>
Wenn bereits ein Nicht-Dev-Gateway läuft (launchd oder systemd), stoppen Sie es zuerst:
Wenn bereits ein Nicht-Entwicklungs-Gateway läuft (launchd oder systemd), stoppen Sie es zuerst:
```bash
openclaw gateway stop
@ -242,9 +257,9 @@ openclaw gateway stop
## Roh-Stream-Logging (OpenClaw)
OpenClaw kann den **rohen Assistenten-Stream** vor jeglicher Filterung/Formatierung protokollieren.
Dies ist die beste Möglichkeit zu sehen, ob Reasoning als Klartext-Deltas
(oder als separate Denkblöcke) ankommt.
OpenClaw kann den **rohen Assistant-Stream** vor jeglicher Filterung/Formatierung loggen.
Das ist die beste Möglichkeit zu sehen, ob Reasoning als Klartext-Deltas
(oder als separate Thinking-Blöcke) ankommt.
Aktivieren Sie es über die CLI:
@ -252,13 +267,13 @@ Aktivieren Sie es über die CLI:
pnpm gateway:watch --raw-stream
```
Optionaler Pfad-Override:
Optionale Pfadüberschreibung:
```bash
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
```
Äquivalente Env-Vars:
Äquivalente Env Vars:
```bash
OPENCLAW_RAW_STREAM=1
@ -293,7 +308,7 @@ Standarddatei:
## Sicherheitshinweise
- Roh-Stream-Logs können vollständige Prompts, Tool-Ausgabe und Benutzerdaten enthalten.
- Roh-Stream-Logs können vollständige Prompts, Tool-Ausgaben und Benutzerdaten enthalten.
- Bewahren Sie Logs lokal auf und löschen Sie sie nach dem Debugging.
- Wenn Sie Logs teilen, entfernen Sie zuerst Secrets und personenbezogene Daten.

252
docs/de/help/faq-models.md
View File

@ -1,49 +1,49 @@
---
read_when:
- Modelle auswählen oder wechseln, Aliasse konfigurieren
- Fehlerbehebung bei Modell-Failover / „Alle Modelle sind fehlgeschlagen“
- Debugging von Modell-Failover / „Alle Modelle sind fehlgeschlagen“
- Authentifizierungsprofile verstehen und verwalten
sidebarTitle: Models FAQ
summary: 'FAQ: Modellvorgaben, Auswahl, Aliasse, Wechsel, Failover und Authentifizierungsprofile'
summary: 'FAQ: Modellstandardwerte, Auswahl, Aliasse, Wechsel, Failover und Authentifizierungsprofile'
title: 'FAQ: Modelle und Authentifizierung'
x-i18n:
generated_at: "2026-05-02T06:36:31Z"
generated_at: "2026-05-05T01:47:00Z"
model: gpt-5.5
provider: openai
source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884
source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54
source_path: help/faq-models.md
workflow: 16
---
Modell- und Authentifizierungsprofil-Q&A. Informationen zu Einrichtung, Sitzungen, Gateway, Kanälen und
Fragen und Antworten zu Modell- und Auth-Profilen. Einrichtung, Sitzungen, Gateway, Kanäle und
Fehlerbehebung finden Sie in der Haupt-[FAQ](/de/help/faq).
## Modelle: Defaults, Auswahl, Aliasse, Wechsel
## Modelle: Standardwerte, Auswahl, Aliasse, Wechsel
<AccordionGroup>
<Accordion title='Was ist das "default model"?'>
Das Default-Modell von OpenClaw ist das, was Sie hier festlegen:
<Accordion title='Was ist das "Standardmodell"?'>
Das Standardmodell von OpenClaw ist das, was Sie hier festlegen:
```
agents.defaults.model.primary
```
Modelle werden als `provider/model` referenziert (Beispiel: `openai/gpt-5.5` oder `openai-codex/gpt-5.5`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige Übereinstimmung mit einem konfigurierten Provider für genau diese Modell-ID und fällt erst danach als veralteten Kompatibilitätspfad auf den konfigurierten Default-Provider zurück. Wenn dieser Provider das konfigurierte Default-Modell nicht mehr bereitstellt, fällt OpenClaw auf den ersten konfigurierten Provider/das erste konfigurierte Modell zurück, statt ein veraltetes entferntes Provider-Default anzuzeigen. Sie sollten `provider/model` dennoch **explizit** festlegen.
Modelle werden als `provider/model` referenziert (Beispiel: `openai/gpt-5.5` oder `openai-codex/gpt-5.5`). Wenn Sie den Provider weglassen, versucht OpenClaw zuerst einen Alias, dann eine eindeutige Übereinstimmung mit einem konfigurierten Provider für genau diese Modell-ID, und fällt erst danach als veralteter Kompatibilitätspfad auf den konfigurierten Standard-Provider zurück. Wenn dieser Provider das konfigurierte Standardmodell nicht mehr bereitstellt, fällt OpenClaw auf den ersten konfigurierten Provider/das erste konfigurierte Modell zurück, statt einen veralteten Standard eines entfernten Providers anzuzeigen. Sie sollten `provider/model` trotzdem **explizit** festlegen.
</Accordion>
<Accordion title="Welches Modell empfehlen Sie?">
**Empfohlenes Default:** Verwenden Sie das stärkste Modell der neuesten Generation, das in Ihrem Provider-Stack verfügbar ist.
**Für Agents mit Tool-Nutzung oder nicht vertrauenswürdigen Eingaben:** Priorisieren Sie Modellstärke vor Kosten.
**Für Routine-Chat mit geringem Risiko:** Verwenden Sie günstigere Fallback-Modelle und routen Sie nach Agent-Rolle.
**Empfohlener Standard:** Verwenden Sie das stärkste Modell der neuesten Generation, das in Ihrem Provider-Stack verfügbar ist.
**Für Agenten mit Tools oder nicht vertrauenswürdigen Eingaben:** Priorisieren Sie Modellstärke gegenüber Kosten.
**Für routinemäßigen Chat mit geringem Risiko:** Verwenden Sie günstigere Fallback-Modelle und routen Sie nach Agentenrolle.
MiniMax hat eigene Dokumentation: [MiniMax](/de/providers/minimax) und
[Lokale Modelle](/de/gateway/local-models).
Faustregel: Verwenden Sie für Arbeit mit hohem Risiko 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
Faustregel: Verwenden Sie für wichtige Arbeiten das **beste Modell, das Sie sich leisten können**, und ein günstigeres
Modell für routinemäßigen 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-Agents](/de/tools/subagents).
[Sub-Agenten](/de/tools/subagents).
Deutliche Warnung: Schwächere oder übermäßig quantisierte Modelle sind anfälliger für Prompt
Injection und unsicheres Verhalten. Siehe [Sicherheit](/de/gateway/security).
@ -62,10 +62,10 @@ x-i18n:
- `openclaw configure --section model` (interaktiv)
- `agents.defaults.model` in `~/.openclaw/openclaw.json` bearbeiten
Vermeiden Sie `config.apply` mit einem Teilobjekt, es sei denn, Sie möchten die gesamte Konfiguration ersetzen.
Prüfen Sie bei RPC-Bearbeitungen zuerst mit `config.schema.lookup` und bevorzugen Sie `config.patch`. Die Lookup-Payload liefert Ihnen den normalisierten Pfad, flache Schema-Dokumentation/Einschränkungen und direkte Zusammenfassungen der untergeordneten Elemente.
Vermeiden Sie `config.apply` mit einem Teilobjekt, sofern Sie nicht die gesamte Konfiguration ersetzen möchten.
Prüfen Sie bei RPC-Bearbeitungen zuerst mit `config.schema.lookup` und bevorzugen Sie `config.patch`. Die Lookup-Nutzlast liefert Ihnen den normalisierten Pfad, oberflächliche Schema-Dokumentation/-Einschränkungen und direkte Zusammenfassungen der untergeordneten Elemente
für Teilaktualisierungen.
Wenn Sie die Konfiguration überschrieben haben, stellen Sie sie aus einem Backup wieder her oder führen Sie erneut `openclaw doctor` aus, um sie zu reparieren.
Wenn Sie die Konfiguration überschrieben haben, stellen Sie sie aus einem Backup wieder her oder führen Sie erneut `openclaw doctor` zur Reparatur aus.
Dokumentation: [Modelle](/de/concepts/models), [Konfigurieren](/de/cli/configure), [Konfiguration](/de/cli/config), [Doctor](/de/gateway/doctor).
@ -77,7 +77,7 @@ x-i18n:
Schnellste Einrichtung:
1. Installieren Sie Ollama von `https://ollama.com/download`
2. Laden Sie ein lokales Modell, zum Beispiel `ollama pull gemma4`
2. Laden Sie ein lokales Modell, zum Beispiel mit `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`
@ -85,12 +85,12 @@ x-i18n:
Hinweise:
- `Cloud + Local` gibt Ihnen Cloud-Modelle plus Ihre lokalen Ollama-Modelle
- Cloud-Modelle wie `kimi-k2.5:cloud` benötigen keinen lokalen Pull
- Cloud-Modelle wie `kimi-k2.5:cloud` benötigen keinen lokalen Download
- Verwenden Sie für manuelles Wechseln `openclaw models list` und `openclaw models set ollama/<model>`
Sicherheitshinweis: Kleinere oder stark quantisierte Modelle sind anfälliger für Prompt
Injection. Wir empfehlen dringend **große Modelle** für jeden Bot, der Tools verwenden kann.
Wenn Sie dennoch kleine Modelle verwenden möchten, aktivieren Sie Sandboxing und strikte Tool-Allowlists.
Wenn Sie trotzdem kleine Modelle verwenden möchten, aktivieren Sie Sandboxing und strenge Tool-Allowlists.
Dokumentation: [Ollama](/de/providers/ollama), [Lokale Modelle](/de/gateway/local-models),
[Modell-Provider](/de/concepts/model-providers), [Sicherheit](/de/gateway/security),
@ -99,13 +99,13 @@ x-i18n:
</Accordion>
<Accordion title="Welche Modelle verwenden OpenClaw, Flawd und Krill?">
- Diese Deployments können unterschiedlich sein und sich im Laufe der Zeit ändern; es gibt keine feste Provider-Empfehlung.
- Prüfen Sie die aktuelle Runtime-Einstellung auf jedem Gateway mit `openclaw models status`.
- Verwenden Sie für sicherheitssensitive Agents oder Agents mit Tool-Nutzung das stärkste verfügbare Modell der neuesten Generation.
- Diese Deployments können sich unterscheiden und sich im Lauf der Zeit ändern; es gibt keine feste Provider-Empfehlung.
- Prüfen Sie die aktuelle Laufzeiteinstellung auf jedem Gateway mit `openclaw models status`.
- Verwenden Sie für sicherheitssensitive Agenten oder Agenten mit Tools das stärkste verfügbare Modell der neuesten Generation.
</Accordion>
<Accordion title="Wie wechsle ich Modelle spontan (ohne Neustart)?">
<Accordion title="Wie wechsle ich Modelle im laufenden Betrieb (ohne Neustart)?">
Verwenden Sie den Befehl `/model` als eigenständige Nachricht:
```
@ -128,17 +128,17 @@ x-i18n:
/model 3
```
Sie können außerdem ein bestimmtes Authentifizierungsprofil für den Provider erzwingen (pro Sitzung):
Sie können außerdem ein bestimmtes Auth-Profil für den Provider erzwingen (pro Sitzung):
```
/model opus@anthropic:default
/model opus@anthropic:work
```
Tipp: `/model status` zeigt, welcher Agent aktiv ist, welche `auth-profiles.json`-Datei verwendet wird und welches Authentifizierungsprofil als Nächstes versucht wird.
Außerdem zeigt es, sofern verfügbar, den konfigurierten Provider-Endpunkt (`baseUrl`) und den API-Modus (`api`).
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`), sofern verfügbar.
**Wie löse ich die Bindung an ein Profil, das ich mit @profile festgelegt habe?**
**Wie löse ich ein Profil, das ich mit @profile festgelegt habe?**
Führen Sie `/model` erneut **ohne** das Suffix `@profile` aus:
@ -146,28 +146,28 @@ x-i18n:
/model anthropic/claude-opus-4-6
```
Wenn Sie zum Default zurückkehren möchten, wählen Sie es aus `/model` aus (oder senden Sie `/model <default provider/model>`).
Verwenden Sie `/model status`, um zu bestätigen, welches Authentifizierungsprofil aktiv ist.
Wenn Sie zum Standard zurückkehren möchten, wählen Sie ihn über `/model` aus (oder senden Sie `/model <default provider/model>`).
Verwenden Sie `/model status`, um zu bestätigen, welches Auth-Profil aktiv ist.
</Accordion>
<Accordion title="Kann ich GPT 5.5 für tägliche Aufgaben und Codex 5.5 fürs Coding verwenden?">
Ja. Behandeln Sie Modellauswahl und Runtime-Auswahl getrennt:
<Accordion title="Kann ich GPT 5.5 für tägliche Aufgaben und Codex 5.5 zum Programmieren verwenden?">
Ja. Behandeln Sie Modellauswahl und Laufzeitauswahl getrennt:
- **Nativer Codex-Coding-Agent:** Setzen Sie `agents.defaults.model.primary` auf `openai/gpt-5.5` und `agents.defaults.agentRuntime.id` auf `"codex"`. Melden Sie sich mit `openclaw models auth login --provider openai-codex` an, wenn Sie ChatGPT/Codex-Abonnementauthentifizierung verwenden möchten.
- **Direkte OpenAI-API-Aufgaben über PI:** Verwenden Sie `/model openai/gpt-5.5` ohne Codex-Runtime-Override und konfigurieren Sie `OPENAI_API_KEY`.
- **Nativer Codex-Coding-Agent:** Setzen Sie `agents.defaults.model.primary` auf `openai/gpt-5.5` und `agents.defaults.agentRuntime.id` auf `"codex"`. Melden Sie sich mit `openclaw models auth login --provider openai-codex` an, wenn Sie ChatGPT-/Codex-Abonnement-Auth verwenden möchten.
- **Direkte OpenAI-API-Aufgaben über PI:** Verwenden Sie `/model openai/gpt-5.5` ohne Codex-Laufzeitüberschreibung und konfigurieren Sie `OPENAI_API_KEY`.
- **Codex OAuth über PI:** Verwenden Sie `/model openai-codex/gpt-5.5` nur, wenn Sie bewusst den normalen PI-Runner mit Codex OAuth möchten.
- **Sub-Agents:** Routen Sie Coding-Aufgaben an einen reinen Codex-Agent mit eigenem Modell und eigenem `agentRuntime`-Default.
- **Sub-Agenten:** Routen Sie Coding-Aufgaben an einen reinen Codex-Agenten mit eigenem Modell und eigenem Standard für `agentRuntime`.
Siehe [Modelle](/de/concepts/models) und [Slash-Befehle](/de/tools/slash-commands).
</Accordion>
<Accordion title="Wie konfiguriere ich Fast Mode für GPT 5.5?">
Verwenden Sie entweder einen Sitzungsumschalter oder ein Konfigurations-Default:
<Accordion title="Wie konfiguriere ich den Schnellmodus für GPT 5.5?">
Verwenden Sie entweder einen Sitzungsumschalter oder einen Konfigurationsstandard:
- **Pro Sitzung:** Senden Sie `/fast on`, während die Sitzung `openai/gpt-5.5` oder `openai-codex/gpt-5.5` verwendet.
- **Pro Modell-Default:** Setzen Sie `agents.defaults.models["openai/gpt-5.5"].params.fastMode` oder `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` auf `true`.
- **Als Standard pro Modell:** Setzen Sie `agents.defaults.models["openai/gpt-5.5"].params.fastMode` oder `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` auf `true`.
Beispiel:
@ -187,40 +187,44 @@ x-i18n:
}
```
Für OpenAI wird Fast Mode bei unterstützten nativen Responses-Anfragen auf `service_tier = "priority"` abgebildet. Sitzungs-Overrides mit `/fast` haben Vorrang vor Konfigurations-Defaults.
Für OpenAI wird der Schnellmodus bei unterstützten nativen Responses-Anfragen auf `service_tier = "priority"` abgebildet. Sitzungsbezogene `/fast`-Überschreibungen haben Vorrang vor Konfigurationsstandards.
Siehe [Thinking und Fast Mode](/de/tools/thinking) und [OpenAI Fast Mode](/de/providers/openai#fast-mode).
Siehe [Denken und Schnellmodus](/de/tools/thinking) und [OpenAI-Schnellmodus](/de/providers/openai#fast-mode).
</Accordion>
<Accordion title='Warum sehe ich "Model ... is not allowed" und dann keine Antwort?'>
<Accordion title='Warum sehe ich "Model ... is not allowed" und danach keine Antwort?'>
Wenn `agents.defaults.models` gesetzt ist, wird es zur **Allowlist** für `/model` und alle
Sitzungs-Overrides. Die Auswahl eines Modells, das nicht in dieser Liste enthalten ist, gibt Folgendes zurück:
Sitzungsüberschreibungen. Die Auswahl eines Modells, das nicht in dieser Liste steht, gibt Folgendes zurück:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
Dieser Fehler wird **anstelle** einer normalen Antwort zurückgegeben. Lösung: Fügen Sie das Modell zu
`agents.defaults.models` hinzu, entfernen Sie die Allowlist oder wählen Sie ein Modell aus `/model list`.
Wenn der Befehl auch `--runtime codex` enthielt, fügen Sie zuerst das Modell hinzu und wiederholen Sie dann
denselben Befehl `/model provider/model --runtime codex`.
</Accordion>
<Accordion title='Warum sehe ich "Unknown model: minimax/MiniMax-M2.7"?'>
Das bedeutet, dass der **Provider nicht konfiguriert ist** (es wurde keine MiniMax-Provider-Konfiguration und kein Authentifizierungsprofil gefunden), sodass das Modell nicht aufgelöst werden kann.
Das bedeutet, dass der **Provider nicht konfiguriert ist** (es wurde keine MiniMax-Provider-Konfiguration und kein Auth-
Profil gefunden), sodass das Modell nicht aufgelöst werden kann.
Checkliste zur Behebung:
1. Aktualisieren Sie auf eine aktuelle OpenClaw-Version (oder führen Sie aus dem Source-Branch `main` aus) und starten Sie dann das Gateway neu.
2. Stellen Sie sicher, dass MiniMax konfiguriert ist (Assistent oder JSON) oder dass MiniMax-Authentifizierung
in Umgebungsvariablen/Authentifizierungsprofilen vorhanden ist, damit der passende Provider injiziert werden kann
1. Aktualisieren Sie auf eine aktuelle OpenClaw-Version (oder führen Sie den Quellstand `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 env/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 (Groß-/Kleinschreibung beachten) für Ihren Authentifizierungspfad:
`minimax/MiniMax-M2.7` oder `minimax/MiniMax-M2.7-highspeed` für ein API-Key-
Setup, oder `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed` für ein OAuth-Setup.
4. Führen Sie Folgendes aus:
3. Verwenden Sie die genaue Modell-ID (Groß-/Kleinschreibung beachten) für Ihren Auth-Pfad:
`minimax/MiniMax-M2.7` oder `minimax/MiniMax-M2.7-highspeed` für eine API-Key-
Einrichtung, oder `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed` für eine OAuth-Einrichtung.
4. Führen Sie aus:
```bash
openclaw models list
@ -232,9 +236,9 @@ x-i18n:
</Accordion>
<Accordion title="Kann ich MiniMax als Default und OpenAI für komplexe Aufgaben verwenden?">
Ja. Verwenden Sie **MiniMax als Default** und wechseln Sie Modelle **pro Sitzung**, wenn nötig.
Fallbacks sind für **Fehler** gedacht, nicht für "schwere Aufgaben"; verwenden Sie daher `/model` oder einen separaten Agent.
<Accordion title="Kann ich MiniMax als Standard und OpenAI für komplexe Aufgaben verwenden?">
Ja. Verwenden Sie **MiniMax als Standard** und wechseln Sie Modelle **pro Sitzung**, wenn nötig.
Fallbacks sind für **Fehler** gedacht, nicht für "schwierige Aufgaben"; verwenden Sie daher `/model` oder einen separaten Agenten.
**Option A: pro Sitzung wechseln**
@ -259,29 +263,29 @@ x-i18n:
/model gpt
```
**Option B: separate Agents**
**Option B: separate Agenten**
- Agent A Default: MiniMax
- Agent B Default: OpenAI
- Routen Sie nach Agent oder verwenden Sie `/agent`, um zu wechseln
- Standard von Agent A: MiniMax
- Standard von Agent B: OpenAI
- Nach Agent routen oder mit `/agent` wechseln
Dokumentation: [Modelle](/de/concepts/models), [Multi-Agent-Routing](/de/concepts/multi-agent), [MiniMax](/de/providers/minimax), [OpenAI](/de/providers/openai).
</Accordion>
<Accordion title="Sind opus / sonnet / gpt integrierte Kurzbefehle?">
Ja. OpenClaw liefert einige Default-Kurzschreibweisen mit (werden nur angewendet, wenn das Modell in `agents.defaults.models` existiert):
Ja. OpenClaw liefert einige Standard-Kurzformen aus (werden nur angewendet, wenn das Modell in `agents.defaults.models` vorhanden ist):
- `opus` → `anthropic/claude-opus-4-6`
- `sonnet` → `anthropic/claude-sonnet-4-6`
- `gpt` → `openai/gpt-5.5` für API-Key-Setups oder `openai-codex/gpt-5.5`, wenn für Codex OAuth konfiguriert
- `gpt` → `openai/gpt-5.5` für API-Key-Einrichtungen oder `openai-codex/gpt-5.5`, wenn für Codex OAuth konfiguriert
- `gpt-mini` → `openai/gpt-5.4-mini`
- `gpt-nano` → `openai/gpt-5.4-nano`
- `gemini` → `google/gemini-3.1-pro-preview`
- `gemini-flash` → `google/gemini-3-flash-preview`
- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
Wenn Sie Ihren eigenen Alias mit demselben Namen setzen, hat Ihr Wert Vorrang.
Wenn Sie Ihren eigenen Alias mit demselben Namen festlegen, hat Ihr Wert Vorrang.
</Accordion>
@ -303,7 +307,7 @@ x-i18n:
}
```
Dann wird `/model sonnet` (oder `/<alias>`, sofern unterstützt) zu dieser Modell-ID aufgelöst.
Dann wird `/model sonnet` (oder `/<alias>`, wenn unterstützt) zu dieser Modell-ID aufgelöst.
</Accordion>
@ -336,53 +340,53 @@ x-i18n:
}
```
Wenn Sie auf einen Provider/ein Modell verweisen, aber der erforderliche Provider-Schlüssel fehlt, erhalten Sie einen Authentifizierungsfehler zur Laufzeit (z. B. `No API key found for provider "zai"`).
Wenn Sie einen Provider/ein Modell referenzieren, aber der erforderliche Provider-Schlüssel fehlt, erhalten Sie zur Laufzeit einen Authentifizierungsfehler (z. B. `No API key found for provider "zai"`).
**Kein API-Schlüssel für Provider gefunden, nachdem ein neuer Agent hinzugefügt wurde**
**Kein API-Schlüssel für den Provider gefunden, nachdem ein neuer Agent hinzugefügt wurde**
Das bedeutet normalerweise, dass der **neue Agent** einen leeren Auth-Speicher hat. Auth ist agentenspezifisch und
wird hier gespeichert:
Das bedeutet normalerweise, dass der **neue Agent** einen leeren Auth-Speicher hat. Authentifizierung ist agentspezifisch und
wird gespeichert in:
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
Optionen zur Behebung:
Behebungsoptionen:
- Führen Sie `openclaw agents add <id>` aus und konfigurieren Sie Auth während des Assistenten.
- Oder kopieren Sie nur portable statische `api_key`- / `token`-Profile aus dem Auth-Speicher des Haupt-Agenten in den Auth-Speicher des neuen Agenten.
- Melden Sie sich bei OAuth-Profilen über den neuen Agenten an, wenn dieser ein eigenes Konto benötigt; andernfalls kann OpenClaw bis zum Standard-/Haupt-Agenten durchlesen, ohne Refresh-Tokens zu klonen.
- Führen Sie `openclaw agents add <id>` aus und konfigurieren Sie die Authentifizierung im Assistenten.
- Oder kopieren Sie nur portable statische `api_key`- / `token`-Profile aus dem Auth-Speicher des Haupt-Agents in den Auth-Speicher des neuen Agents.
- Melden Sie sich bei OAuth-Profilen vom neuen Agent aus an, wenn dieser ein eigenes Konto benötigt; andernfalls kann OpenClaw auf den Standard-/Haupt-Agent zugreifen, ohne Refresh-Tokens zu klonen.
Verwenden Sie `agentDir` **nicht** agentenübergreifend wieder; das verursacht Auth-/Sitzungskollisionen.
Verwenden Sie `agentDir` **nicht** für mehrere Agents erneut; dies führt zu Authentifizierungs-/Sitzungskollisionen.
</Accordion>
</AccordionGroup>
## Modell-Failover und „Alle Modelle fehlgeschlagen“
## Modell-Failover und "Alle Modelle fehlgeschlagen"
<AccordionGroup>
<Accordion title="Wie funktioniert Failover?">
Failover erfolgt in zwei Stufen:
Failover erfolgt in zwei Phasen:
1. **Auth-Profil-Rotation** innerhalb desselben Providers.
2. **Modell-Fallback** zum nächsten Modell in `agents.defaults.model.fallbacks`.
1. **Rotation von Auth-Profilen** innerhalb desselben Providers.
2. **Modell-Fallback** auf das nächste Modell in `agents.defaults.model.fallbacks`.
Cooldowns gelten für fehlgeschlagene Profile (exponentielles Backoff), sodass OpenClaw weiter antworten kann, selbst wenn ein Provider rate-limitiert ist oder vorübergehend ausfällt.
Cooldowns gelten für fehlgeschlagene Profile (exponentielles Backoff), sodass OpenClaw weiter antworten kann, selbst wenn ein Provider rate-limitiert ist oder vorübergehend fehlschlägt.
Der Rate-Limit-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
Nutzungslimit-Fenster (`weekly/monthly limit reached`) als
Rate-Limits, die ein Failover rechtfertigen.
Nutzungfensterlimits (`weekly/monthly limit reached`) als Rate Limits,
die Failover rechtfertigen.
Einige Antworten, die nach Abrechnung aussehen, sind keine `402`, und einige HTTP-`402`-
Einige Antworten, die nach Abrechnung aussehen, sind nicht `402`, und einige HTTP-`402`-
Antworten bleiben ebenfalls in diesem transienten Bucket. Wenn ein Provider
expliziten Abrechnungstext bei `401` oder `403` zurückgibt, kann OpenClaw dies weiterhin in
der Abrechnungsspur halten, aber providerspezifische Text-Matcher bleiben auf den
Provider beschränkt, dem sie gehören (zum Beispiel OpenRouter `Key limit exceeded`). Wenn eine `402`-
Meldung stattdessen wie ein wiederholbares Nutzungslimit-Fenster oder
ein Ausgabenlimit für Organisation/Workspace aussieht (`daily limit reached, resets tomorrow`,
Meldung stattdessen wie ein wiederholbares Nutzungfenster- oder
Organisations-/Workspace-Ausgabenlimit aussieht (`daily limit reached, resets tomorrow`,
`organization spending limit exceeded`), behandelt OpenClaw sie als
`rate_limit`, nicht als langfristige Abrechnungsdeaktivierung.
@ -393,39 +397,39 @@ x-i18n:
exceeded` bleiben auf dem Compaction-/Retry-Pfad, statt zum Modell-
Fallback überzugehen.
Generischer Serverfehler-Text ist absichtlich enger gefasst als „alles mit
unknown/error darin“. OpenClaw behandelt providerbezogene transiente Formen
wie Anthropic ohne Zusatztext `An unknown error occurred`, OpenRouter ohne Zusatztext
Allgemeiner Serverfehlertext ist absichtlich enger gefasst als „alles mit
unknown/error darin“. OpenClaw behandelt providerbezogene transiente Muster
wie Anthropic mit bloßem `An unknown error occurred`, OpenRouter mit bloßem
`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-ausgelastet-Fehler wie `ModelNotReadyException` als
Timeout-/Überlastungssignale, die ein Failover rechtfertigen, wenn der Provider-Kontext
error`) und Provider-Überlastungsfehler wie `ModelNotReadyException` als
Failover-würdige Timeout-/Überlastungssignale, 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 genommen keinen Modell-Fallback aus.
Allgemeiner interner Fallback-Text wie `LLM request failed with an unknown
error.` bleibt konservativ und löst für sich allein keinen Modell-Fallback aus.
</Accordion>
<Accordion title='Was bedeutet „No credentials found for profile anthropic:default“?'>
Es bedeutet, dass das System versucht hat, die Auth-Profil-ID `anthropic:default` zu verwenden, dafür aber im erwarteten Auth-Speicher keine Zugangsdaten finden konnte.
<Accordion title='Was bedeutet "No credentials found for profile anthropic:default"?'>
Es bedeutet, dass das System versucht hat, die Auth-Profil-ID `anthropic:default` zu verwenden, dafür aber keine Zugangsdaten im erwarteten Auth-Speicher finden konnte.
**Checkliste zur Behebung:**
- **Bestätigen Sie, wo Auth-Profile liegen** (neue vs. Legacy-Pfade)
- **Bestätigen Sie, wo Auth-Profile gespeichert sind** (neue vs. Legacy-Pfade)
- Aktuell: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- Legacy: `~/.openclaw/agent/*` (migriert durch `openclaw doctor`)
- **Bestätigen Sie, dass Ihre Env-Var vom Gateway geladen wird**
- Wenn Sie `ANTHROPIC_API_KEY` in Ihrer Shell setzen, 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**
- **Bestätigen Sie, dass Ihre Umgebungsvariable vom Gateway geladen wird**
- Wenn Sie `ANTHROPIC_API_KEY` in Ihrer Shell setzen, das Gateway aber über systemd/launchd ausführen, erbt es sie möglicherweise nicht. Legen Sie sie in `~/.openclaw/.env` ab oder aktivieren Sie `env.shellEnv`.
- **Stellen Sie sicher, dass Sie den richtigen Agent bearbeiten**
- Multi-Agent-Setups bedeuten, dass es mehrere `auth-profiles.json`-Dateien geben kann.
- **Prüfen Sie Modell-/Auth-Status grob**
- Verwenden Sie `openclaw models status`, um konfigurierte Modelle anzuzeigen und zu sehen, ob Provider authentifiziert sind.
- **Plausibilitätsprüfung von Modell-/Auth-Status**
- Verwenden Sie `openclaw models status`, um konfigurierte Modelle anzuzeigen und zu prüfen, ob Provider authentifiziert sind.
**Checkliste zur Behebung für „No credentials found for profile anthropic“**
**Checkliste zur Behebung für "No credentials found for profile anthropic"**
Das bedeutet, dass der Lauf auf ein Anthropic-Auth-Profil festgelegt ist, das Gateway
dieses aber in seinem Auth-Speicher nicht finden kann.
Das bedeutet, dass der Lauf an ein Anthropic-Auth-Profil gebunden ist, das Gateway
es aber nicht in seinem Auth-Speicher finden kann.
- **Claude CLI verwenden**
- Führen Sie `openclaw models auth login --provider anthropic --method cli --set-default` auf dem Gateway-Host aus.
@ -438,58 +442,60 @@ x-i18n:
```
- **Bestätigen Sie, dass Sie Befehle auf dem Gateway-Host ausführen**
- Im Remote-Modus liegen Auth-Profile auf der Gateway-Maschine, nicht auf Ihrem Laptop.
- Im Remote-Modus befinden sich Auth-Profile auf dem Gateway-Rechner, nicht auf Ihrem Laptop.
</Accordion>
<Accordion title="Warum wurde auch Google Gemini versucht und ist fehlgeschlagen?">
Wenn Ihre Modellkonfiguration Google Gemini als Fallback enthält (oder Sie zu einer Gemini-Kurzform gewechselt sind), versucht OpenClaw es während des Modell-Fallbacks. Wenn Sie keine Google-Zugangsdaten 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 haben), versucht OpenClaw es während des Modell-Fallbacks. Wenn Sie keine Google-Zugangsdaten konfiguriert haben, sehen Sie `No API key found for provider "google"`.
Behebung: Stellen Sie entweder Google-Auth bereit oder entfernen/vermeiden Sie Google-Modelle in `agents.defaults.model.fallbacks` / Aliassen, damit der Fallback nicht dorthin routet.
Behebung: Stellen Sie entweder Google-Auth bereit oder entfernen/vermeiden Sie Google-Modelle in `agents.defaults.model.fallbacks` / Aliasen, damit der Fallback nicht dorthin weiterleitet.
**LLM-Anfrage abgelehnt: Thinking-Signatur erforderlich (Google Antigravity)**
Ursache: Der Sitzungsverlauf enthält **Thinking-Blöcke ohne Signaturen** (oft aus
einem abgebrochenen/teilweisen Stream). Google Antigravity verlangt Signaturen für Thinking-Blöcke.
einem abgebrochenen/partiellen Stream). Google Antigravity erfordert Signaturen für Thinking-Blöcke.
Behebung: OpenClaw entfernt jetzt unsignierte Thinking-Blöcke für Google Antigravity Claude. Wenn es weiterhin auftritt, starten Sie eine **neue Sitzung** oder setzen Sie `/thinking off` für diesen Agenten.
Behebung: OpenClaw entfernt jetzt unsignierte Thinking-Blöcke für Google Antigravity Claude. Wenn dies weiterhin auftritt, starten Sie eine **neue Sitzung** oder setzen Sie `/thinking off` für diesen Agent.
</Accordion>
</AccordionGroup>
## Auth-Profile: was sie sind und wie Sie sie verwalten
Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Flows, Token-Speicherung, Multi-Account-Muster)
Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Abläufe, Token-Speicherung, Muster für mehrere Konten)
<AccordionGroup>
<Accordion title="Was ist ein Auth-Profil?">
Ein Auth-Profil ist ein benannter Zugangsdaten-Datensatz (OAuth oder API-Schlüssel), der an einen Provider gebunden ist. Profile liegen in:
Ein Auth-Profil ist ein benannter Anmeldedatensatz (OAuth oder API-Schlüssel), der mit einem Provider verknüpft ist. Profile befinden sich in:
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
Um gespeicherte Profile zu prüfen, ohne Geheimnisse auszugeben, führen Sie `openclaw models auth list` aus (optional `--provider <id>` oder `--json`). Details finden Sie unter [Models CLI](/de/cli/models#openclaw-models-auth-list).
</Accordion>
<Accordion title="Was sind typische Profil-IDs?">
OpenClaw verwendet providerpräfixierte IDs wie:
OpenClaw verwendet IDs mit Provider-Präfix wie:
- `anthropic:default` (üblich, wenn keine E-Mail-Identität vorhanden ist)
- `anthropic:default` (üblich, wenn keine E-Mail-Identität existiert)
- `anthropic:<email>` für OAuth-Identitäten
- benutzerdefinierte IDs, die Sie wählen (z. B. `anthropic:work`)
- benutzerdefinierte IDs Ihrer Wahl (z. B. `anthropic:work`)
</Accordion>
<Accordion title="Kann ich steuern, welches Auth-Profil zuerst versucht wird?">
Ja. Die Konfiguration unterstützt optionale Metadaten für Profile und eine Reihenfolge pro Provider (`auth.order.<provider>`). Dadurch werden **keine** Secrets gespeichert; es ordnet IDs Provider/Modus zu und legt die Rotationsreihenfolge fest.
Ja. Die Konfiguration unterstützt optionale Metadaten für Profile und eine Reihenfolge pro Provider (`auth.order.<provider>`). Dabei werden **keine** Geheimnisse gespeichert; IDs werden Provider/Modus zugeordnet und die Rotationsreihenfolge wird festgelegt.
OpenClaw kann ein Profil vorübergehend überspringen, wenn es sich in einem kurzen **Cooldown** (Rate-Limits/Timeouts/Auth-Fehler) oder einem längeren **deaktivierten** Zustand (Abrechnung/unzureichende Guthaben) befindet. Um dies zu prüfen, führen Sie `openclaw models status --json` aus und prüfen Sie `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 in einem längeren **deaktivierten** Zustand (Abrechnung/unzureichendes Guthaben) befindet. Um dies zu prüfen, führen Sie `openclaw models status --json` aus und prüfen Sie `auth.unusableProfiles`. Feinabstimmung: `auth.cooldowns.billingBackoffHours*`.
Rate-Limit-Cooldowns können modellspezifisch sein. Ein Profil, das für
ein Modell im Cooldown ist, kann weiterhin für ein Geschwistermodell desselben Providers
Cooldowns für Ratenlimits können modellspezifisch sein. Ein Profil, das
für ein Modell im Cooldown ist, kann weiterhin für ein verwandtes Modell beim selben Provider
nutzbar sein, während Abrechnungs-/Deaktivierungsfenster weiterhin das gesamte Profil blockieren.
Sie können außerdem eine Reihenfolge-Überschreibung **pro Agent** festlegen (gespeichert in der `auth-state.json` dieses Agenten) über die CLI:
Sie können außerdem über die CLI eine **pro-Agent**-Reihenfolgeüberschreibung festlegen (gespeichert in der `auth-state.json` dieses Agent):
```bash
# Defaults to the configured default agent (omit --agent)
@ -505,28 +511,28 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Flows, Token-Speicherung,
openclaw models auth order clear --provider anthropic
```
Um einen bestimmten Agenten anzusteuern:
Um einen bestimmten Agent anzusprechen:
```bash
openclaw models auth order set --provider anthropic --agent main anthropic:default
```
Um zu prüfen, was tatsächlich versucht wird, verwenden Sie:
Um zu überprüfen, was tatsächlich versucht wird, verwenden Sie:
```bash
openclaw models status --probe
```
Wenn ein gespeichertes Profil in der expliziten Reihenfolge ausgelassen wird, meldet Probe
`excluded_by_auth_order` für dieses Profil, statt es stillschweigend zu versuchen.
Wenn ein gespeichertes Profil in der expliziten Reihenfolge ausgelassen wird, meldet die Probe
`excluded_by_auth_order` für dieses Profil, anstatt es stillschweigend zu versuchen.
</Accordion>
<Accordion title="OAuth vs. API-Schlüssel – was ist der Unterschied?">
<Accordion title="OAuth vs. API-Schlüssel - was ist der Unterschied?">
OpenClaw unterstützt beides:
- **OAuth** nutzt häufig Abonnementzugriff (sofern zutreffend).
- **API-Schlüssel** verwenden Pay-per-Token-Abrechnung.
- **API-Schlüssel** verwenden Abrechnung pro Token.
Der Assistent unterstützt ausdrücklich Anthropic Claude CLI, OpenAI Codex OAuth und API-Schlüssel.
@ -536,6 +542,6 @@ Verwandt: [/concepts/oauth](/de/concepts/oauth) (OAuth-Flows, Token-Speicherung,
## Verwandt
- [FAQ](/de/help/faq) — die Haupt-FAQ
- [FAQ — Schnellstart und Einrichtung beim ersten Start](/de/help/faq-first-run)
- [FAQ — Schnellstart und Ersteinrichtung](/de/help/faq-first-run)
- [Modellauswahl](/de/concepts/model-providers)
- [Modell-Failover](/de/concepts/model-failover)

251
docs/de/help/testing-updates-plugins.md
View File

@ -1,52 +1,51 @@
---
read_when:
- OpenClaw-Update-, Diagnose-, Paketakzeptanz- oder Plugin-Installationsverhalten ändern
- Einen Release Candidate vorbereiten oder freigeben
- Fehlerbehebung bei Paketaktualisierungs-, Plugin-Abhängigkeitsbereinigungs- oder Plugin-Installationsregressionen
- OpenClaw-Verhalten für Updates, doctor, Paketabnahme oder Plugin-Installationen ändern
- Release Candidate vorbereiten oder genehmigen
- Debugging von Regressionen bei Paketaktualisierungen, der Bereinigung von Plugin-Abhängigkeiten oder der Plugin-Installation
sidebarTitle: Update and plugin tests
summary: Wie OpenClaw Update-Pfade, Paketmigrationen und das Installations-/Update-Verhalten von Plugins validiert
title: 'Testen: Updates und Plugins'
summary: Wie OpenClaw Aktualisierungspfade, Paketmigrationen und das Plugin-Installations-/Aktualisierungsverhalten validiert
title: 'Tests: Updates und Plugins'
x-i18n:
generated_at: "2026-05-03T21:34:53Z"
generated_at: "2026-05-05T01:47:35Z"
model: gpt-5.5
provider: openai
source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd
source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286
source_path: help/testing-updates-plugins.md
workflow: 16
---
Dies ist die dedizierte Checkliste für Update- und Plugin-Validierung. Das Ziel ist
einfach: nachweisen, dass das installierbare Paket echten Benutzerzustand aktualisieren,
veralteten Legacy-Zustand über `doctor` reparieren und Plugins aus den unterstützten
Quellen weiterhin installieren, laden, aktualisieren und deinstallieren kann.
einfach: nachweisen, dass das installierbare Paket realen Benutzerzustand aktualisieren,
veralteten Legacy-Zustand über `doctor` reparieren und weiterhin Plugins aus den
unterstützten Quellen installieren, laden, aktualisieren und deinstallieren kann.
Für die breitere Übersicht der Test-Runner siehe [Testen](/de/help/testing). Für Live-Provider-
Für die breitere Test-Runner-Übersicht siehe [Testen](/de/help/testing). Für Live-Provider-
Schlüssel und Suites mit Netzwerkzugriff siehe [Live testen](/de/help/testing-live).
## Was wir schützen
Update- und Plugin-Tests schützen diese Verträge:
- Ein Paket-Tarball ist vollständig, enthält eine gültige `dist/postinstall-inventory.json`
und hängt nicht von entpackten Repository-Dateien ab.
- Ein Benutzer kann von einem älteren veröffentlichten Paket zum Kandidatenpaket wechseln,
ohne Konfiguration, Agents, Sitzungen, Workspaces, Plugin-Allowlists oder
- Ein Paket-Tarball ist vollständig, hat eine gültige `dist/postinstall-inventory.json`
und hängt nicht von entpackten Repo-Dateien ab.
- Ein Benutzer kann von einem älteren veröffentlichten Paket zum Kandidatenpaket
wechseln, ohne Konfiguration, Agents, Sitzungen, Arbeitsbereiche, Plugin-Allowlists oder
Kanalkonfiguration zu verlieren.
- `openclaw doctor --fix --non-interactive` besitzt Legacy-Bereinigungs- und Reparaturpfade.
Der Startvorgang sollte keine versteckten Kompatibilitätsmigrationen für veralteten
Plugin-Zustand bekommen.
- Plugin-Installationen funktionieren aus lokalen Verzeichnissen, Git-Repositories,
npm-Paketen und dem ClawHub-Registrypfad.
- npm-Abhängigkeiten von Plugins werden im verwalteten npm-Root installiert, vor dem
Vertrauen gescannt und bei der Deinstallation über npm entfernt, damit hochgezogene
Beim Start sollten keine versteckten Kompatibilitätsmigrationen für veralteten
Plugin-Zustand entstehen.
- Plugin-Installationen funktionieren aus lokalen Verzeichnissen, Git-Repos, npm-Paketen und dem
ClawHub-Registrierungspfad.
- Plugin-npm-Abhängigkeiten werden im verwalteten npm-Root installiert, vor
Vertrauen gescannt und bei der Deinstallation über npm entfernt, damit hoisted
Abhängigkeiten nicht zurückbleiben.
- Plugin-Updates sind stabil, wenn sich nichts geändert hat: Installationsdatensätze,
aufgelöste Quelle, Layout installierter Abhängigkeiten und aktivierter Zustand bleiben
intakt.
- Plugin-Update ist stabil, wenn sich nichts geändert hat: Installationsdatensätze, aufgelöste
Quelle, Layout der installierten Abhängigkeiten und aktivierter Zustand bleiben intakt.
## Lokaler Nachweis während der Entwicklung
Beginnen Sie eng fokussiert:
Beginnen Sie eng gefasst:
```bash
pnpm changed:lanes --json
@ -54,29 +53,28 @@ pnpm check:changed
pnpm test:changed
```
Führen Sie bei Änderungen an Plugin-Installation, Deinstallation, Abhängigkeiten oder
Paketinventar außerdem die fokussierten Tests aus, die die bearbeitete Schnittstelle
abdecken:
Führen Sie bei Änderungen an Plugin-Installation, Deinstallation, Abhängigkeiten oder Paket-Inventar außerdem
die fokussierten Tests aus, die die bearbeitete Schnittstelle abdecken:
```bash
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
```
Bevor eine Paket-Docker-Lane einen Tarball verwendet, weisen Sie das Paketartefakt nach:
Bevor eine Paket-Docker-Lane einen Tarball verwendet, weisen Sie das Paket-Artefakt nach:
```bash
pnpm release:check
```
`release:check` führt Prüfungen auf Konfigurations-/Dokumentations-/API-Drift aus,
schreibt das Paket-Dist-Inventar, führt `npm pack --dry-run` aus, weist unzulässige
gepackte Dateien zurück, installiert den Tarball in ein temporäres Präfix, führt
postinstall aus und smoke-testet gebündelte Kanal-Einstiegspunkte.
`release:check` führt Drift-Prüfungen für Konfiguration/Dokumentation/API aus, schreibt das Paket-Dist-
Inventar, führt `npm pack --dry-run` aus, weist verbotene gepackte Dateien zurück, installiert
den Tarball in ein temporäres Präfix, führt postinstall aus und smoke-testet gebündelte Kanal-
Einstiegspunkte.
## Docker-Lanes
Die Docker-Lanes sind der Nachweis auf Produktebene. Sie installieren oder aktualisieren
ein echtes Paket innerhalb von Linux-Containern und prüfen das Verhalten über CLI-Befehle,
Die Docker-Lanes sind der Nachweis auf Produktebene. Sie installieren oder aktualisieren ein echtes
Paket in Linux-Containern und prüfen das Verhalten über CLI-Befehle,
Gateway-Start, HTTP-Probes, RPC-Status und Dateisystemzustand.
Verwenden Sie beim Iterieren fokussierte Lanes:
@ -92,35 +90,32 @@ pnpm test:docker:update-migration
Wichtige Lanes:
- `test:docker:plugins` validiert den Smoke-Test für Plugin-Installation, Installationen
aus lokalen Ordnern, Überspringverhalten bei Updates lokaler Ordner, lokale Ordner mit
vorinstallierten Abhängigkeiten, `file:`-Paketinstallationen, Git-Installationen mit
CLI-Ausführung, Updates von beweglichen Git-Refs, npm-Registry-Installationen mit
hochgezogenen transitiven Abhängigkeiten, npm-Update-No-Ops, lokale ClawHub-Fixture-
Installationen und Update-No-Ops, Marketplace-Update-Verhalten sowie Aktivieren/Prüfen
des Claude-Bundles. Setzen Sie `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, um den ClawHub-Block
hermetisch/offline zu halten.
- `test:docker:plugins` validiert Plugin-Installations-Smoke, Installationen aus lokalen Ordnern,
das Überspringverhalten bei Updates lokaler Ordner, lokale Ordner mit vorinstallierten
Abhängigkeiten, `file:`-Paketinstallationen, Git-Installationen mit CLI-Ausführung, Git-
Moving-Ref-Updates, npm-Registrierungsinstallationen mit hoisted transitiven
Abhängigkeiten, npm-Update-No-Ops, lokale ClawHub-Fixture-Installationen und Update-
No-Ops, Marketplace-Update-Verhalten sowie Claude-Bundle-Aktivieren/Inspect. Setzen Sie
`OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, um den ClawHub-Block hermetisch/offline zu halten.
- `test:docker:plugin-lifecycle-matrix` installiert das Kandidatenpaket in einem leeren
Container, führt ein npm-Plugin durch Installation, Prüfung, Deaktivierung, Aktivierung,
explizites Upgrade, explizites Downgrade und Deinstallation nach dem Löschen des
Plugin-Codes. Für jede Phase werden RSS- und CPU-Metriken protokolliert.
- `test:docker:plugin-update` validiert, dass ein unverändertes installiertes Plugin
während `openclaw plugins update` nicht neu installiert wird und keine
Installationsmetadaten verliert.
Container, führt ein npm-Plugin durch Installation, Inspect, Deaktivieren, Aktivieren,
explizites Upgrade, explizites Downgrade und Deinstallation nach Löschen des Plugin-
Codes. Es protokolliert RSS- und CPU-Metriken für jede Phase.
- `test:docker:plugin-update` validiert, dass ein unverändertes installiertes Plugin während
`openclaw plugins update` nicht neu installiert wird und keine Installationsmetadaten verliert.
- `test:docker:upgrade-survivor` installiert den Kandidaten-Tarball über eine verschmutzte
alte Benutzer-Fixture, führt Paketupdate plus nicht interaktiven doctor aus, startet
anschließend ein local loopback Gateway und prüft die Zustandserhaltung.
- `test:docker:published-upgrade-survivor` installiert zuerst eine veröffentlichte
Basisversion, konfiguriert sie über ein eingebettetes `openclaw config set`-Rezept,
aktualisiert sie auf den Kandidaten-Tarball, führt doctor aus, prüft die
Legacy-Bereinigung, startet das Gateway und probt `/healthz`, `/readyz` und den
RPC-Status.
- `test:docker:update-migration` ist die bereinigungsintensive Lane für veröffentlichte
Updates. Sie startet mit einem konfigurierten Benutzerzustand im Discord/Telegram-Stil,
führt den Basis-doctor aus, damit konfigurierte Plugin-Abhängigkeiten materialisiert
werden können, legt Legacy-Plugin-Abhängigkeitsreste für ein konfiguriertes paketiertes
Plugin an, aktualisiert auf den Kandidaten-Tarball und verlangt, dass post-update doctor
die Legacy-Abhängigkeitsroots entfernt.
Altbenutzer-Fixture, führt Paket-Update plus nicht-interaktiven doctor aus, startet dann
ein Loopback-Gateway und prüft die Zustandserhaltung.
- `test:docker:published-upgrade-survivor` installiert zuerst eine veröffentlichte Baseline,
konfiguriert sie über ein eingebettetes `openclaw config set`-Rezept, aktualisiert sie auf den
Kandidaten-Tarball, führt doctor aus, prüft Legacy-Bereinigung, startet den Gateway und
probt `/healthz`, `/readyz` und den RPC-Status.
- `test:docker:update-migration` ist die bereinigungsintensive Lane für veröffentlichte Updates. Sie
startet mit einem konfigurierten Discord/Telegram-artigen Benutzerzustand, führt Baseline-
doctor aus, damit konfigurierte Plugin-Abhängigkeiten materialisiert werden können, erzeugt
Legacy-Plugin-Abhängigkeitsreste für ein konfiguriertes paketiertes Plugin, aktualisiert auf
den Kandidaten-Tarball und verlangt, dass post-update doctor die Legacy-
Abhängigkeits-Roots entfernt.
Nützliche Varianten für published-upgrade survivor:
@ -135,15 +130,14 @@ pnpm test:docker:published-upgrade-survivor
```
Verfügbare Szenarien sind `base`, `feishu-channel`, `bootstrap-persona`,
`plugin-deps-cleanup`, `configured-plugin-installs`, `tilde-log-path` und
`versioned-runtime-deps`. In aggregierten Läufen wird
`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` auf alle gemeldeten,
issue-förmigen Szenarien erweitert, einschließlich der Migration installierter
konfigurierter Plugins.
`plugin-deps-cleanup`, `configured-plugin-installs`,
`stale-source-plugin-shadow`, `tilde-log-path` und `versioned-runtime-deps`. In aggregierten Läufen
wird `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` auf alle gemeldeten
issue-artigen Szenarien erweitert, einschließlich der konfigurierten Plugin-Installationsmigration.
Die vollständige Update-Migration ist absichtlich von Full Release CI getrennt. Verwenden
Sie den manuellen Workflow `Update Migration`, wenn die Release-Frage lautet: „Kann jede
veröffentlichte stabile Version ab 2026.4.23 auf diesen Kandidaten aktualisieren und
Die vollständige Update-Migration ist absichtlich von Full Release CI getrennt. Verwenden Sie den
manuellen `Update Migration`-Workflow, wenn die Release-Frage lautet: „Kann jedes
veröffentlichte stabile Release ab 2026.4.23 auf diesen Kandidaten aktualisiert werden und
Plugin-Abhängigkeitsreste bereinigen?“:
```bash
@ -157,26 +151,25 @@ gh workflow run update-migration.yml \
## Package Acceptance
Package Acceptance ist das GitHub-native Paket-Gate. Es löst ein Kandidatenpaket in einen
`package-under-test`-Tarball auf, zeichnet Version und SHA-256 auf und führt anschließend
wiederverwendbare Docker-E2E-Lanes gegen genau diesen Tarball aus. Der Workflow-Harness-Ref
ist vom Paketquellen-Ref getrennt, sodass aktuelle Testlogik ältere vertrauenswürdige
Releases validieren kann.
Package Acceptance ist das GitHub-native Paket-Gate. Es löst ein Kandidatenpaket
in einen `package-under-test`-Tarball auf, zeichnet Version und SHA-256 auf und
führt anschließend wiederverwendbare Docker-E2E-Lanes gegen genau diesen Tarball aus. Die Workflow-Harness-
Ref ist von der Paketquellen-Ref getrennt, sodass aktuelle Testlogik ältere
vertrauenswürdige Releases validieren kann.
Kandidatenquellen:
- `source=npm`: `openclaw@beta`, `openclaw@latest` oder eine exakte veröffentlichte
Version validieren.
- `source=ref`: einen vertrauenswürdigen Branch, Tag oder Commit mit dem ausgewählten
aktuellen Harness packen.
- `source=url`: einen HTTPS-Tarball mit erforderlichem `package_sha256` validieren.
- `source=artifact`: einen von einem anderen Actions-Lauf hochgeladenen Tarball
wiederverwenden.
- `source=npm`: validiert `openclaw@beta`, `openclaw@latest` oder eine exakte
veröffentlichte Version.
- `source=ref`: packt einen vertrauenswürdigen Branch, Tag oder Commit mit dem ausgewählten aktuellen
Harness.
- `source=url`: validiert einen HTTPS-Tarball mit erforderlichem `package_sha256`.
- `source=artifact`: verwendet einen von einem anderen Actions-Lauf hochgeladenen Tarball erneut.
Full Release Validation verwendet standardmäßig `source=artifact`, gebaut aus dem
aufgelösten Release-SHA. Für den Nachweis nach der Veröffentlichung übergeben Sie
`package_acceptance_package_spec=openclaw@YYYY.M.D`, damit dieselbe Upgrade-Matrix
stattdessen das ausgelieferte npm-Paket anvisiert.
stattdessen auf das ausgelieferte npm-Paket zielt.
Release-Prüfungen rufen Package Acceptance mit dem Paket-/Update-/Plugin-Set auf:
@ -192,19 +185,17 @@ published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai
```
Dadurch bleiben Paketmigration, Update-Channel-Umschaltung, Bereinigung veralteter
Plugin-Abhängigkeiten, Offline-Plugin-Abdeckung, Plugin-Update-Verhalten und Telegram-
Paket-QA auf demselben aufgelösten Artefakt.
Dadurch bleiben Paketmigration, Update-Channel-Wechsel, Bereinigung veralteter Plugin-Abhängigkeiten,
Offline-Plugin-Abdeckung, Plugin-Update-Verhalten und Telegram-Paket-
QA auf demselben aufgelösten Artefakt.
`all-since-2026.4.23` ist die Full Release CI-Upgrade-Stichprobe: jede stabile,
auf npm veröffentlichte Version von `2026.4.23` bis `latest`. Verwenden Sie für
vollständige Abdeckung der Migration veröffentlichter Updates `all-since-2026.4.23`
im separaten Update-Migration-Workflow statt in Full Release CI. `release-history`
bleibt für breitere manuelle Stichproben verfügbar, wenn Sie auch den älteren
Anker vor diesem Datum einbeziehen möchten.
`all-since-2026.4.23` ist die Upgrade-Stichprobe von Full Release CI: jedes stabile, auf npm veröffentlichte Release von `2026.4.23` bis `latest`. Für exhaustive Abdeckung veröffentlichter
Update-Migrationen verwenden Sie `all-since-2026.4.23` im separaten Update-
Migration-Workflow statt in Full Release CI. `release-history` bleibt
für manuelle breitere Stichproben verfügbar, wenn Sie auch den älteren
Vor-Datums-Anker möchten.
Führen Sie ein Paketprofil manuell aus, wenn Sie einen Kandidaten vor dem Release
validieren:
Führen Sie ein Paketprofil manuell aus, wenn Sie einen Kandidaten vor dem Release validieren:
```bash
gh workflow run package-acceptance.yml \
@ -219,60 +210,58 @@ gh workflow run package-acceptance.yml \
```
Verwenden Sie `suite_profile=product`, wenn die Release-Frage MCP-Kanäle,
Cron-/Subagent-Bereinigung, OpenAI-Websuche oder OpenWebUI umfasst. Verwenden Sie
`suite_profile=full` nur, wenn Sie vollständige Docker-Abdeckung des Release-Pfads
benötigen.
Cron/Subagent-Bereinigung, OpenAI-Websuche oder OpenWebUI umfasst. Verwenden Sie `suite_profile=full`
nur, wenn Sie vollständige Docker-Abdeckung des Release-Pfads benötigen.
## Release-Standard
Für Release-Kandidaten ist der Standard-Nachweisstapel:
Für Release-Kandidaten ist der standardmäßige Nachweis-Stack:
1. `pnpm check:changed` und `pnpm test:changed` für Regressionen auf Source-Ebene.
2. `pnpm release:check` für die Integrität des Paketartefakts.
3. Package Acceptance-Profil `package` oder die benutzerdefinierten Paket-Lanes der
Release-Prüfung für Installations-/Update-/Plugin-Verträge.
4. Cross-OS-Release-Prüfungen für OS-spezifisches Installer-, Onboarding- und
Plattformverhalten.
5. Live-Suites nur, wenn die geänderte Oberfläche Provider- oder Hosted-Service-Verhalten
betrifft.
1. `pnpm check:changed` und `pnpm test:changed` für Regressionen auf Quellcodeebene.
2. `pnpm release:check` für die Integrität des Paket-Artefakts.
3. Package Acceptance-`package`-Profil oder die benutzerdefinierten Paket-
Lanes der Release-Prüfung für Installations-/Update-/Plugin-Verträge.
4. Plattformübergreifende Release-Prüfungen für OS-spezifisches Installationsprogramm, Onboarding und Plattform-
Verhalten.
5. Live-Suites nur, wenn die geänderte Oberfläche Provider- oder gehostetes Service-
Verhalten berührt.
Auf Maintainer-Maschinen sollten breite Gates und Docker-/Paket-Produktnachweise in
Testbox laufen, sofern nicht ausdrücklich ein lokaler Nachweis durchgeführt wird.
Testbox laufen, sofern nicht ausdrücklich lokaler Nachweis durchgeführt wird.
## Legacy-Kompatibilität
Kompatibilitätsnachsicht ist eng und zeitlich begrenzt:
Kompatibilitätsnachsicht ist eng gefasst und zeitlich begrenzt:
- Pakete bis einschließlich `2026.4.25`, einschließlich `2026.4.25-beta.*`, dürfen
bereits ausgelieferte Lücken in Paketmetadaten in Package Acceptance tolerieren.
- Das veröffentlichte Paket `2026.4.26` darf für bereits ausgelieferte lokale
Build-Metadatenstempeldateien warnen.
- Spätere Pakete müssen moderne Verträge erfüllen. Dieselben Lücken schlagen fehl,
statt zu warnen oder übersprungen zu werden.
bereits ausgelieferte Paketmetadaten-Lücken in Package Acceptance tolerieren.
- Das veröffentlichte Paket `2026.4.26` darf für bereits ausgelieferte lokale Build-Metadatenstempel-
Dateien warnen.
- Spätere Pakete müssen moderne Verträge erfüllen. Dieselben Lücken schlagen fehl, statt
zu warnen oder zu überspringen.
Fügen Sie keine neuen Startmigrationen für diese alten Formen hinzu. Fügen Sie eine
doctor-Reparatur hinzu oder erweitern Sie eine, und weisen Sie sie anschließend mit
`upgrade-survivor` oder `published-upgrade-survivor` nach.
Fügen Sie für diese alten Formen keine neuen Startmigrationen hinzu. Fügen Sie eine doctor-
Reparatur hinzu oder erweitern Sie sie und weisen Sie sie dann mit `upgrade-survivor` oder `published-upgrade-survivor` nach.
## Abdeckung hinzufügen
Wenn Sie Update- oder Plugin-Verhalten ändern, fügen Sie Abdeckung auf der niedrigsten
Ebene hinzu, die aus dem richtigen Grund fehlschlagen kann:
Wenn Sie Update- oder Plugin-Verhalten ändern, fügen Sie Abdeckung auf der niedrigsten Ebene hinzu, die
aus dem richtigen Grund fehlschlagen kann:
- Reine Pfad- oder Metadatenlogik: Unit-Test neben der Quelle.
- Paketinventar- oder Packed-File-Verhalten: `package-dist-inventory`- oder Tarball-
- Paket-Inventar oder Verhalten gepackter Dateien: `package-dist-inventory` oder Tarball-
Checker-Test.
- CLI-Installations-/Update-Verhalten: Docker-Lane-Assertion oder Fixture.
- Migrationsverhalten veröffentlichter Releases: `published-upgrade-survivor`-Szenario.
- Registry-/Paketquellenverhalten: `test:docker:plugins`-Fixture oder ClawHub-
- Registrierungs-/Paketquellenverhalten: `test:docker:plugins`-Fixture oder ClawHub-
Fixture-Server.
- Abhängigkeitslayout- oder Bereinigungsverhalten: sowohl Laufzeitausführung als auch
die Dateisystemgrenze prüfen. npm-Abhängigkeiten können unter den verwalteten npm-Root
hochgezogen werden, daher sollten Tests nachweisen, dass der Root gescannt/bereinigt
wird, statt von einem paketlokalen `node_modules`-Baum auszugehen.
- Verhalten von Abhängigkeitslayout oder Bereinigung: prüfen Sie sowohl Runtime-Ausführung als auch die
Dateisystemgrenze. npm-Abhängigkeiten können unter dem verwalteten npm-
Root gehoistet werden, daher sollten Tests nachweisen, dass der Root gescannt/bereinigt wird, statt von einem
paketlokalen `node_modules`-Baum auszugehen.
Halten Sie neue Docker-Fixtures standardmäßig hermetisch. Verwenden Sie lokale
Fixture-Registries und Fake-Pakete, außer der Zweck des Tests ist Live-Registry-Verhalten.
Halten Sie neue Docker-Fixtures standardmäßig hermetisch. Verwenden Sie lokale Fixture-Registries und
Fake-Pakete, sofern nicht Live-Registrierungsverhalten der Zweck des Tests ist.
## Fehlertriage
@ -280,11 +269,11 @@ Beginnen Sie mit der Artefaktidentität:
- Package Acceptance-`resolve_package`-Zusammenfassung: Quelle, Version, SHA-256 und
Artefaktname.
- Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`, `failures.json`,
Lane-Logs und Befehle zum erneuten Ausführen.
- Docker-Artefakte: `.artifacts/docker-tests/**/summary.json`,
`failures.json`, Lane-Logs und Rerun-Befehle.
- Upgrade-Survivor-Zusammenfassung: `.artifacts/upgrade-survivor/summary.json`,
einschließlich Basisversion, Kandidatenversion, Szenario, Phasen-Timings und
einschließlich Baseline-Version, Kandidatenversion, Szenario, Phasen-Timings und
Rezeptschritten.
Bevorzugen Sie das erneute Ausführen der exakt fehlgeschlagenen Lane mit demselben
Paketartefakt gegenüber dem erneuten Ausführen des gesamten Release-Umbrellas.
Ziehen Sie es vor, die exakt fehlgeschlagene Lane mit demselben Paket-Artefakt erneut auszuführen, statt
den gesamten Release-Umbrella erneut auszuführen.

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

File diff suppressed because it is too large Load Diff

162
docs/de/plugins/bundles.md
View File

@ -1,38 +1,37 @@
---
read_when:
- Sie möchten ein mit Codex, Claude oder Cursor kompatibles Bundle installieren
- Sie müssen verstehen, wie OpenClaw Bundle-Inhalte nativen Funktionen zuordnet
- Sie möchten ein Codex-, Claude- oder Cursor-kompatibles Bundle installieren
- Sie müssen verstehen, wie OpenClaw Bundle-Inhalte nativen Funktionen zuordnet.
- Sie debuggen die Bundle-Erkennung oder fehlende Funktionen
summary: Codex-, Claude- und Cursor-Bundles als OpenClaw-Plugins installieren und verwenden
title: Plugin-Pakete
summary: Codex-, Claude- und Cursor-Pakete als OpenClaw-Plugins installieren und verwenden
title: Plugin-Bundles
x-i18n:
generated_at: "2026-05-02T06:39:47Z"
generated_at: "2026-05-05T01:47:51Z"
model: gpt-5.5
provider: openai
source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4
source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157
source_path: plugins/bundles.md
workflow: 16
---
OpenClaw kann Plugins aus drei externen Ökosystemen installieren: **Codex**, **Claude**
und **Cursor**. Diese werden **Bundles** genannt: Inhalts- und Metadatenpakete, die
und **Cursor**. Diese heißen **Bundles**: Inhalts- und Metadatenpakete, die
OpenClaw nativen Funktionen wie Skills, Hooks und MCP-Tools zuordnet.
<Info>
Bundles sind **nicht** dasselbe wie native OpenClaw-Plugins. Native Plugins laufen
im Prozess und können jede Capability registrieren. Bundles sind Inhaltspakete mit
im Prozess und können jede Fähigkeit registrieren. Bundles sind Inhaltspakete mit
selektiver Funktionszuordnung und einer engeren Vertrauensgrenze.
</Info>
## Warum es Bundles gibt
Viele nützliche Plugins werden im Codex-, Claude- oder Cursor-Format veröffentlicht. Anstatt
von Autorinnen und Autoren zu verlangen, sie als native OpenClaw-Plugins neu zu schreiben,
erkennt OpenClaw diese Formate und ordnet ihre unterstützten Inhalte dem nativen
Funktionsumfang zu. Das bedeutet, dass Sie ein Claude-Befehlspaket oder ein Codex-Skill-Bundle
installieren und sofort verwenden können.
Viele nützliche Plugins werden im Codex-, Claude- oder Cursor-Format veröffentlicht. Statt
Autorinnen und Autoren zu verlangen, sie als native OpenClaw-Plugins neu zu schreiben, erkennt OpenClaw
diese Formate und ordnet ihre unterstützten Inhalte dem nativen Funktionsumfang zu. Das bedeutet, Sie können ein Claude-Befehlspaket oder ein Codex-Skill-Bundle installieren
und es sofort verwenden.
## Bundle installieren
## Ein Bundle installieren
<Steps>
<Step title="Aus einem Verzeichnis, Archiv oder Marketplace installieren">
@ -50,7 +49,7 @@ installieren und sofort verwenden können.
</Step>
<Step title="Erkennung verifizieren">
<Step title="Erkennung prüfen">
```bash
openclaw plugins list
openclaw plugins inspect <id>
@ -73,18 +72,18 @@ installieren und sofort verwenden können.
## Was OpenClaw aus Bundles zuordnet
Nicht jede Bundle-Funktion läuft heute in OpenClaw. Hier sehen Sie, was funktioniert und was
erkannt, aber noch nicht angebunden ist.
erkannt, aber noch nicht verdrahtet ist.
### Derzeit unterstützt
| Funktion | Wie sie zugeordnet wird | Gilt für |
| Funktion | Zuordnung | Gilt für |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
| Skill-Inhalt | Bundle-Skill-Roots werden als normale OpenClaw-Skills geladen | Alle Formate |
| Befehle | `commands/` und `.cursor/commands/` werden als Skill-Roots behandelt | Claude, Cursor |
| Hook-Pakete | OpenClaw-Layouts mit `HOOK.md` + `handler.ts` | Codex |
| Hook-Pakete | OpenClaw-artige Layouts mit `HOOK.md` + `handler.ts` | Codex |
| MCP-Tools | Bundle-MCP-Konfiguration wird in eingebettete Pi-Einstellungen zusammengeführt; unterstützte stdio- und HTTP-Server werden geladen | Alle Formate |
| LSP-Server | Claude `.lsp.json` und im Manifest deklarierte `lspServers` werden in eingebettete Pi-LSP-Standards zusammengeführt | Claude |
| Einstellungen | Claude `settings.json` wird als eingebettete Pi-Standards importiert | Claude |
| LSP-Server | Claude-`.lsp.json` und im Manifest deklarierte `lspServers` werden in eingebettete Pi-LSP-Standards zusammengeführt | Claude |
| Einstellungen | Claude-`settings.json` wird als eingebettete Pi-Standards importiert | Claude |
#### Skill-Inhalt
@ -92,8 +91,8 @@ erkannt, aber noch nicht angebunden ist.
- Claude-`commands`-Roots werden als zusätzliche Skill-Roots behandelt
- Cursor-`.cursor/commands`-Roots werden als zusätzliche Skill-Roots behandelt
Das bedeutet, dass Claude-Markdown-Befehlsdateien über den normalen OpenClaw-Skill-
Loader funktionieren. Cursor-Befehls-Markdown funktioniert über denselben Pfad.
Das bedeutet, Claude-Markdown-Befehlsdateien funktionieren über den normalen OpenClaw-Skill-
Loader. Cursor-Befehls-Markdown funktioniert über denselben Pfad.
#### Hook-Pakete
@ -104,23 +103,20 @@ Loader funktionieren. Cursor-Befehls-Markdown funktioniert über denselben Pfad.
#### MCP für Pi
- Aktivierte Bundles können MCP-Server-Konfiguration beitragen
- OpenClaw führt Bundle-MCP-Konfiguration in den effektiven eingebetteten Pi-Einstellungen als
`mcpServers` zusammen
- OpenClaw stellt unterstützte Bundle-MCP-Tools während eingebetteter Pi-Agent-Turns bereit, indem
stdio-Server gestartet oder Verbindungen zu HTTP-Servern hergestellt werden
- Die Tool-Profile `coding` und `messaging` enthalten Bundle-MCP-Tools standardmäßig;
verwenden Sie `tools.deny: ["bundle-mcp"]`, um dies für einen Agenten oder Gateway zu deaktivieren
- Projektlokale Pi-Einstellungen gelten weiterhin nach Bundle-Standards, sodass Workspace-
- aktivierte Bundles können MCP-Serverkonfiguration beitragen
- OpenClaw führt die Bundle-MCP-Konfiguration als `mcpServers` in die wirksamen eingebetteten Pi-Einstellungen zusammen
- OpenClaw stellt unterstützte Bundle-MCP-Tools während eingebetteter Pi-Agent-Turns bereit, indem es stdio-Server startet oder sich mit HTTP-Servern verbindet
- die Tool-Profile `coding` und `messaging` enthalten Bundle-MCP-Tools standardmäßig; verwenden Sie `tools.deny: ["bundle-mcp"]`, um sie für einen Agent oder Gateway auszuschließen
- projektlokale Pi-Einstellungen gelten weiterhin nach Bundle-Standards, sodass Workspace-
Einstellungen Bundle-MCP-Einträge bei Bedarf überschreiben können
- Bundle-MCP-Tool-Kataloge werden vor der Registrierung deterministisch sortiert, damit
- Bundle-MCP-Tool-Kataloge werden vor der Registrierung deterministisch sortiert, sodass
Änderungen der Upstream-`listTools()`-Reihenfolge Prompt-Cache-Tool-Blöcke nicht unnötig verändern
##### Transports
##### Transporte
MCP-Server können stdio- oder HTTP-Transport verwenden:
**Stdio** startet einen Child-Prozess:
**Stdio** startet einen Kindprozess:
```json
{
@ -136,7 +132,7 @@ MCP-Server können stdio- oder HTTP-Transport verwenden:
}
```
**HTTP** verbindet sich standardmäßig über `sse` mit einem laufenden MCP-Server oder über `streamable-http`, wenn angefordert:
**HTTP** verbindet sich standardmäßig über `sse` mit einem laufenden MCP-Server oder bei Anforderung über `streamable-http`:
```json
{
@ -157,13 +153,13 @@ MCP-Server können stdio- oder HTTP-Transport verwenden:
- `transport` kann auf `"streamable-http"` oder `"sse"` gesetzt werden; wenn ausgelassen, verwendet OpenClaw `sse`
- `type: "http"` ist eine CLI-native Downstream-Form; verwenden Sie `transport: "streamable-http"` in der OpenClaw-Konfiguration. `openclaw mcp set` und `openclaw doctor --fix` normalisieren den gängigen Alias.
- Nur URL-Schemata `http:` und `https:` sind erlaubt
- nur URL-Schemas `http:` und `https:` sind erlaubt
- `headers`-Werte unterstützen `${ENV_VAR}`-Interpolation
- Ein Server-Eintrag mit sowohl `command` als auch `url` wird abgelehnt
- URL-Zugangsdaten (userinfo und Query-Parameter) werden aus Tool-
Beschreibungen und Logs redigiert
- `connectionTimeoutMs` überschreibt das standardmäßige 30-Sekunden-Verbindungs-Timeout für
stdio- und HTTP-Transports
- ein Servereintrag mit sowohl `command` als auch `url` wird abgelehnt
- URL-Zugangsdaten (userinfo und query params) werden in Tool-
Beschreibungen und Logs geschwärzt
- `connectionTimeoutMs` überschreibt das standardmäßige Verbindungs-Timeout von 30 Sekunden für
stdio- und HTTP-Transporte
##### Tool-Benennung
@ -172,19 +168,19 @@ OpenClaw registriert Bundle-MCP-Tools mit Provider-sicheren Namen in der Form
`memory_search`-Tool bereitstellt, als `vigil-harbor__memory_search` registriert.
- Zeichen außerhalb von `A-Za-z0-9_-` werden durch `-` ersetzt
- Server-Präfixe sind auf 30 Zeichen begrenzt
- Vollständige Tool-Namen sind auf 64 Zeichen begrenzt
- Leere Servernamen fallen auf `mcp` zurück
- Kollidierende bereinigte Namen werden mit numerischen Suffixen eindeutig gemacht
- Die endgültig bereitgestellte Tool-Reihenfolge ist nach sicherem Namen deterministisch, damit wiederholte Pi-
Turns cache-stabil bleiben
- Serverpräfixe sind auf 30 Zeichen begrenzt
- vollständige Tool-Namen sind auf 64 Zeichen begrenzt
- leere Servernamen fallen auf `mcp` zurück
- kollidierende bereinigte Namen werden mit numerischen Suffixen eindeutig gemacht
- die endgültig bereitgestellte Tool-Reihenfolge ist nach sicherem Namen deterministisch, um wiederholte Pi-
Turns cache-stabil zu halten
- Profilfilterung behandelt alle Tools von einem Bundle-MCP-Server als Plugin-eigen
durch `bundle-mcp`, sodass Profil-Allowlisten und Deny-Listen entweder
einzelne bereitgestellte Tool-Namen oder den `bundle-mcp`-Plugin-Schlüssel enthalten können
von `bundle-mcp`, sodass Profil-Allowlists und -Deny-Listen entweder
einzelne bereitgestellte Tool-Namen oder den Plugin-Schlüssel `bundle-mcp` enthalten können
#### Eingebettete Pi-Einstellungen
- Claude `settings.json` wird als standardmäßige eingebettete Pi-Einstellungen importiert, wenn das
- Claude-`settings.json` wird als standardmäßige eingebettete Pi-Einstellungen importiert, wenn das
Bundle aktiviert ist
- OpenClaw bereinigt Shell-Override-Schlüssel, bevor sie angewendet werden
@ -195,19 +191,19 @@ Bereinigte Schlüssel:
#### Eingebettetes Pi-LSP
- Aktivierte Claude-Bundles können LSP-Server-Konfiguration beitragen
- aktivierte Claude-Bundles können LSP-Serverkonfiguration beitragen
- OpenClaw lädt `.lsp.json` plus alle im Manifest deklarierten `lspServers`-Pfade
- Bundle-LSP-Konfiguration wird in die effektiven eingebetteten Pi-LSP-Standards zusammengeführt
- Nur unterstützte stdio-gestützte LSP-Server sind heute ausführbar; nicht unterstützte
Transports werden weiterhin in `openclaw plugins inspect <id>` angezeigt
- Bundle-LSP-Konfiguration wird in die wirksamen eingebetteten Pi-LSP-Standards zusammengeführt
- nur unterstützte stdio-gestützte LSP-Server sind heute ausführbar; nicht unterstützte
Transporte werden weiterhin in `openclaw plugins inspect <id>` angezeigt
### Erkannt, aber nicht ausgeführt
Diese werden erkannt und in Diagnosen angezeigt, aber OpenClaw führt sie nicht aus:
- Claude `agents`, `hooks.json`-Automatisierung, `outputStyles`
- Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
- Codex-Inline-/App-Metadaten über Capability-Berichte hinaus
- Claude-`agents`, `hooks.json`-Automatisierung, `outputStyles`
- Cursor-`.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
- Codex-Inline-/App-Metadaten über Fähigkeitsberichte hinaus
## Bundle-Formate
@ -217,8 +213,8 @@ Diese werden erkannt und in Diagnosen angezeigt, aber OpenClaw führt sie nicht
Optionale Inhalte: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
Codex-Bundles passen am besten zu OpenClaw, wenn sie Skill-Roots und Hook-Paket-Verzeichnisse
im OpenClaw-Stil verwenden (`HOOK.md` + `handler.ts`).
Codex-Bundles passen am besten zu OpenClaw, wenn sie Skill-Roots und OpenClaw-artige
Hook-Paket-Verzeichnisse (`HOOK.md` + `handler.ts`) verwenden.
</Accordion>
@ -235,7 +231,7 @@ Diese werden erkannt und in Diagnosen angezeigt, aber OpenClaw führt sie nicht
- `.mcp.json` stellt unterstützte stdio-Tools für eingebettetes Pi bereit
- `.lsp.json` plus im Manifest deklarierte `lspServers`-Pfade werden in eingebettete Pi-LSP-Standards geladen
- `hooks/hooks.json` wird erkannt, aber nicht ausgeführt
- Benutzerdefinierte Komponentenpfade im Manifest sind additiv (sie erweitern Standards, statt sie zu ersetzen)
- benutzerdefinierte Komponentenpfade im Manifest sind additiv (sie erweitern Standards, ersetzen sie nicht)
</Accordion>
@ -245,51 +241,51 @@ Diese werden erkannt und in Diagnosen angezeigt, aber OpenClaw führt sie nicht
Optionale Inhalte: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
- `.cursor/commands/` wird als Skill-Inhalt behandelt
- `.cursor/rules/`, `.cursor/agents/` und `.cursor/hooks.json` dienen nur der Erkennung
- `.cursor/rules/`, `.cursor/agents/` und `.cursor/hooks.json` dienen nur zur Erkennung
</Accordion>
</AccordionGroup>
## Erkennungsreihenfolge
## Erkennungspriorität
OpenClaw prüft zuerst auf das native Plugin-Format:
1. `openclaw.plugin.json` oder gültige `package.json` mit `openclaw.extensions` — wird als **natives Plugin** behandelt
2. Bundle-Marker (`.codex-plugin/`, `.claude-plugin/` oder Standard-Claude-/Cursor-Layout) — wird als **Bundle** behandelt
Wenn ein Verzeichnis beides enthält, verwendet OpenClaw den nativen Pfad. Dadurch wird verhindert,
dass Dual-Format-Pakete teilweise als Bundles installiert werden.
Wenn ein Verzeichnis beides enthält, verwendet OpenClaw den nativen Pfad. Dies verhindert,
dass Pakete mit zwei Formaten teilweise als Bundles installiert werden.
## Laufzeitabhängigkeiten und Bereinigung
- Drittanbieter-kompatible Bundles erhalten keine Startup-`npm install`-Reparatur. Sie
sollten über `openclaw plugins install` installiert werden und alles mitliefern,
was sie im installierten Plugin-Verzeichnis benötigen.
- OpenClaw-eigene gebündelte Plugins werden entweder leichtgewichtig im Core ausgeliefert oder
über den Plugin-Installer herunterladbar gemacht. Beim Gateway-Start wird für sie niemals ein
Paketmanager ausgeführt.
- `openclaw doctor --fix` entfernt alte bereitgestellte Abhängigkeitsverzeichnisse und kann
konfigurierte herunterladbare Plugins installieren, die im lokalen
Plugin-Index fehlen.
- Drittanbieter-kompatible Bundles erhalten keine Start-`npm install`-Reparatur. Sie
sollten über `openclaw plugins install` installiert werden und alles, was sie benötigen,
im installierten Plugin-Verzeichnis mitliefern.
- OpenClaw-eigene gebündelte Plugins werden entweder schlank im Kern ausgeliefert oder
über den Plugin-Installer herunterladbar gemacht. Der Gateway-Start führt für sie niemals einen
Paketmanager aus.
- `openclaw doctor --fix` entfernt veraltete bereitgestellte Abhängigkeitsverzeichnisse und kann
herunterladbare Plugins wiederherstellen, die im lokalen Plugin-Index fehlen, wenn
die Konfiguration auf sie verweist.
## Sicherheit
Bundles haben eine engere Vertrauensgrenze als native Plugins:
- OpenClaw lädt **keine** beliebigen Bundle-Laufzeitmodule im Prozess
- Skills- und Hook-Paket-Pfade müssen innerhalb des Plugin-Roots bleiben (mit Boundary-Prüfung)
- Einstellungsdateien werden mit denselben Boundary-Prüfungen gelesen
- Unterstützte stdio-MCP-Server können als Subprozesse gestartet werden
- OpenClaw lädt keine beliebigen Bundle-Laufzeitmodule im Prozess
- Skills und Hook-Paket-Pfade müssen innerhalb des Plugin-Roots bleiben (Grenze wird geprüft)
- Einstellungsdateien werden mit denselben Grenzprüfungen gelesen
- unterstützte stdio-MCP-Server können als Subprozesse gestartet werden
Dadurch sind Bundles standardmäßig sicherer, aber Sie sollten Drittanbieter-
Bundles trotzdem als vertrauenswürdige Inhalte für die Funktionen behandeln, die sie bereitstellen.
Bundles weiterhin als vertrauenswürdigen Inhalt für die Funktionen behandeln, die sie bereitstellen.
## Fehlerbehebung
<AccordionGroup>
<Accordion title="Bundle wird erkannt, aber Capabilities laufen nicht">
Führen Sie `openclaw plugins inspect <id>` aus. Wenn eine Capability aufgeführt, aber als
nicht angebunden markiert ist, ist das eine Produktgrenze und keine fehlerhafte Installation.
<Accordion title="Bundle wird erkannt, aber Fähigkeiten werden nicht ausgeführt">
Führen Sie `openclaw plugins inspect <id>` aus. Wenn eine Fähigkeit aufgeführt, aber als
nicht verdrahtet markiert ist, ist das eine Produktgrenze und keine fehlerhafte Installation.
</Accordion>
<Accordion title="Claude-Befehlsdateien erscheinen nicht">
@ -298,17 +294,17 @@ Bundles trotzdem als vertrauenswürdige Inhalte für die Funktionen behandeln, d
</Accordion>
<Accordion title="Claude-Einstellungen werden nicht angewendet">
Nur eingebettete Pi-Einstellungen aus `settings.json` werden unterstützt. OpenClaw behandelt
Es werden nur eingebettete Pi-Einstellungen aus `settings.json` unterstützt. OpenClaw behandelt
Bundle-Einstellungen nicht als rohe Konfigurations-Patches.
</Accordion>
<Accordion title="Claude-Hooks werden nicht ausgeführt">
`hooks/hooks.json` dient nur der Erkennung. Wenn Sie ausführbare Hooks benötigen, verwenden Sie das
`hooks/hooks.json` dient nur zur Erkennung. Wenn Sie ausführbare Hooks benötigen, verwenden Sie das
OpenClaw-Hook-Paket-Layout oder liefern Sie ein natives Plugin aus.
</Accordion>
</AccordionGroup>
## Verwandte Themen
## Verwandt
- [Plugins installieren und konfigurieren](/de/tools/plugin)
- [Plugins erstellen](/de/plugins/building-plugins) — ein natives Plugin erstellen

802
docs/de/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

97
docs/de/plugins/dependency-resolution.md
View File

@ -1,61 +1,61 @@
---
read_when:
- Sie debuggen Installationen von Plugin-Paketen
- Sie ändern das Startverhalten von Plugins, doctor oder das Installationsverhalten des Package-Managers
- Sie verwalten paketierte OpenClaw-Installationen oder gebündelte Plugin-Manifeste
- Sie ändern das Verhalten beim Plugin-Start, bei doctor oder bei Installationen über den Paketmanager
- Sie pflegen paketierte OpenClaw-Installationen oder gebündelte Plugin-Manifeste
sidebarTitle: Dependencies
summary: Wie OpenClaw Plugin-Pakete installiert und Plugin-Abhängigkeiten auflöst
title: Plugin-Abhängigkeitsauflösung
title: Auflösung von Plugin-Abhängigkeiten
x-i18n:
generated_at: "2026-05-03T21:36:01Z"
generated_at: "2026-05-05T01:47:57Z"
model: gpt-5.5
provider: openai
source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d
source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20
source_path: plugins/dependency-resolution.md
workflow: 16
---
# Auflösung von Plugin-Abhängigkeiten
# Plugin-Abhängigkeitsauflösung
OpenClaw hält Arbeiten an Plugin-Abhängigkeiten auf den Zeitpunkt der Installation/Aktualisierung beschränkt. Das Laden zur Laufzeit
OpenClaw erledigt Plugin-Abhängigkeitsarbeit zur Installations-/Aktualisierungszeit. Das Laden zur Laufzeit
führt keine Paketmanager aus, repariert keine Abhängigkeitsbäume und verändert nicht das OpenClaw-
Paketverzeichnis.
## Aufteilung der Verantwortlichkeiten
## Verantwortungsaufteilung
Plugin-Pakete besitzen ihren Abhängigkeitsgraphen:
- Laufzeitabhängigkeiten befinden sich in `dependencies` oder
- Laufzeitabhängigkeiten befinden sich in den `dependencies` oder
`optionalDependencies` des Plugin-Pakets
- SDK-/Core-Importe sind Peer- oder von OpenClaw bereitgestellte Importe
- lokale Entwicklungs-Plugins bringen ihre eigenen bereits installierten Abhängigkeiten mit
- npm- und git-Plugins werden in OpenClaw-eigene Paket-Roots installiert
- SDK-/Core-Importe sind Peer-Imports oder von OpenClaw bereitgestellte Importe
- lokale Entwicklungs-Plugins bringen ihre bereits installierten Abhängigkeiten selbst mit
- npm- und git-Plugins werden in OpenClaw-eigene Paket-Wurzeln installiert
OpenClaw besitzt nur den Plugin-Lebenszyklus:
- die Plugin-Quelle erkennen
- die Plugin-Quelle ermitteln
- das Paket installieren oder aktualisieren, wenn dies ausdrücklich angefordert wird
- die Installationsmetadaten aufzeichnen
- den Plugin-Einstiegspunkt laden
- mit einem umsetzbaren Fehler fehlschlagen, wenn Abhängigkeiten fehlen
## Installations-Roots
## Installations-Wurzeln
OpenClaw verwendet stabile Roots pro Quelle:
OpenClaw verwendet stabile Wurzeln pro Quelle:
- npm-Pakete werden unter `~/.openclaw/npm` installiert
- git-Pakete werden unter `~/.openclaw/git` geklont
- lokale/Pfad-/Archivinstallationen werden ohne Abhängigkeitsreparatur kopiert oder referenziert
- lokale/Pfad-/Archiv-Installationen werden ohne Abhängigkeitsreparatur kopiert oder referenziert
npm-Installationen laufen im npm-Root mit:
npm-Installationen laufen in der npm-Wurzel mit:
```bash
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
```
npm kann transitive Abhängigkeiten nach `~/.openclaw/npm/node_modules` neben
das Plugin-Paket hoisten. OpenClaw scannt den verwalteten npm-Root, bevor es der
Installation vertraut, und verwendet npm, um npm-verwaltete Pakete bei der Deinstallation zu entfernen, sodass gehoistete
das Plugin-Paket hoisten. OpenClaw scannt die verwaltete npm-Wurzel, bevor der
Installation vertraut wird, und verwendet npm, um npm-verwaltete Pakete bei der Deinstallation zu entfernen, sodass gehoistete
Laufzeitabhängigkeiten innerhalb der verwalteten Bereinigungsgrenze bleiben.
git-Installationen klonen oder aktualisieren das Repository und führen dann aus:
@ -64,27 +64,27 @@ git-Installationen klonen oder aktualisieren das Repository und führen dann aus
npm install --omit=dev --ignore-scripts --no-audit --no-fund
```
Das installierte Plugin wird anschließend aus diesem Paketverzeichnis geladen, sodass die Auflösung von paketlokalen
und übergeordneten `node_modules` genauso funktioniert wie bei einem normalen
Das installierte Plugin wird anschließend aus diesem Paketverzeichnis geladen, sodass die paketlokale
und übergeordnete `node_modules`-Auflösung genauso funktioniert wie bei einem normalen
Node-Paket.
## Lokale Plugins
Lokale Plugins werden als entwicklerkontrollierte Verzeichnisse behandelt. OpenClaw führt dafür kein
`npm install`, `pnpm install` und keine Abhängigkeitsreparatur aus. Wenn ein lokales
Lokale Plugins werden als entwicklerkontrollierte Verzeichnisse behandelt. OpenClaw führt für sie kein
`npm install`, `pnpm install` oder keine Abhängigkeitsreparatur aus. Wenn ein lokales
Plugin Abhängigkeiten hat, installieren Sie diese in diesem Plugin, bevor Sie es laden.
Drittanbieter-TypeScript-Plugins können lokal den Jiti-Notfallpfad verwenden. Paketierte
Lokale TypeScript-Plugins von Drittanbietern können den Jiti-Notfallpfad verwenden. Paketierte
JavaScript-Plugins und gebündelte interne Plugins werden über natives
import/require statt über Jiti geladen.
## Start und Neuladen
Gateway-Start und Konfigurations-Neuladen installieren niemals Plugin-Abhängigkeiten. Sie lesen
Gateway-Start und Konfigurationsneuladen installieren niemals Plugin-Abhängigkeiten. Sie lesen
die Plugin-Installationsdatensätze, berechnen den Einstiegspunkt und laden ihn.
Wenn zur Laufzeit eine Abhängigkeit fehlt, kann das Plugin nicht geladen werden, und der Fehler
sollte den Betreiber auf eine explizite Behebung verweisen:
Wenn zur Laufzeit eine Abhängigkeit fehlt, schlägt das Laden des Plugins fehl und der Fehler
sollte den Betreiber auf eine ausdrückliche Behebung hinweisen:
```bash
openclaw plugins update <id>
@ -92,44 +92,45 @@ openclaw plugins install <source>
openclaw doctor --fix
```
`doctor --fix` kann alten, von OpenClaw generierten Abhängigkeitszustand bereinigen und
konfigurierte herunterladbare Plugins installieren, die in den lokalen Installationsdatensätzen fehlen.
Es repariert keine Abhängigkeiten für ein bereits installiertes lokales Plugin.
`doctor --fix` kann veralteten, von OpenClaw erzeugten Abhängigkeitszustand bereinigen und
herunterladbare Plugins wiederherstellen, die in den lokalen Installationsdatensätzen fehlen, wenn die Konfiguration
auf sie verweist. Doctor repariert keine Abhängigkeiten für ein bereits installiertes
lokales Plugin.
## Gebündelte Plugins
Leichtgewichtige und Core-kritische gebündelte Plugins werden als Teil von OpenClaw ausgeliefert.
Leichtgewichtige und core-kritische gebündelte Plugins werden als Teil von OpenClaw ausgeliefert.
Sie sollten entweder keinen schweren Laufzeit-Abhängigkeitsbaum haben oder in ein
herunterladbares Paket auf ClawHub/npm ausgelagert werden.
herunterladbares Paket auf ClawHub/npm verschoben werden.
Die aktuelle generierte Liste der Plugins, die im Core-Paket ausgeliefert, extern
installiert oder nur als Quellcode behalten werden, finden Sie im [Plugin-Inventar](/de/plugins/plugin-inventory).
installiert oder nur als Quellcode beibehalten werden, finden Sie im [Plugin-Inventar](/de/plugins/plugin-inventory).
Manifeste gebündelter Plugins dürfen kein Dependency Staging anfordern. Große oder optionale
Plugin-Funktionalität sollte als normales Plugin paketiert und über
denselben npm-/git-/ClawHub-Pfad wie Drittanbieter-Plugins installiert werden.
denselben npm/git/ClawHub-Pfad wie Drittanbieter-Plugins installiert werden.
In Source-Checkouts behandelt OpenClaw das Repository als pnpm-Monorepo. Nach
`pnpm install` werden gebündelte Plugins aus `extensions/<id>` geladen, sodass paketlokale
Workspace-Abhängigkeiten verfügbar sind und Änderungen direkt übernommen werden. Die Entwicklung in Source-
Checkouts ist ausschließlich pnpm-basiert; ein einfaches `npm install` im Repository-Root ist
Checkouts ist ausschließlich pnpm-basiert; ein einfaches `npm install` in der Repository-Wurzel ist
kein unterstützter Weg, um Abhängigkeiten gebündelter Plugins vorzubereiten.
| Installationsform | Speicherort des gebündelten Plugins | Verantwortlicher für Abhängigkeiten |
| Installationsform | Speicherort gebündelter Plugins | Eigentümer der Abhängigkeiten |
| -------------------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| `npm install -g openclaw` | Gebauter Laufzeitbaum innerhalb des Pakets | OpenClaw-Paket und explizite Plugin-Installations-/Aktualisierungs-/doctor-Abläufe |
| Git-Checkout plus `pnpm install` | Workspace-Pakete in `extensions/<id>` | Der pnpm-Workspace, einschließlich der eigenen Abhängigkeiten jedes Plugin-Pakets |
| `openclaw plugins install ...` | Verwalteter npm-/git-/ClawHub-Plugin-Root | Der Plugin-Installations-/Aktualisierungsablauf |
| `npm install -g openclaw` | Gebauter Laufzeitbaum im Paket | OpenClaw-Paket und explizite Plugin-Installations-/Aktualisierungs-/Doctor-Flows |
| Git-Checkout plus `pnpm install` | `extensions/<id>`-Workspace-Pakete | Der pnpm-Workspace, einschließlich der eigenen Abhängigkeiten jedes Plugin-Pakets |
| `openclaw plugins install ...` | Verwaltete npm/git/ClawHub-Plugin-Wurzel | Der Plugin-Installations-/Aktualisierungs-Flow |
## Legacy-Bereinigung
## Bereinigung veralteter Reste
Ältere OpenClaw-Versionen erzeugten Roots für Abhängigkeiten gebündelter Plugins beim Start oder
während der doctor-Reparatur. Die aktuelle doctor-Bereinigung entfernt diese veralteten Verzeichnisse und
Symlinks, wenn `--fix` verwendet wird, einschließlich alter `plugin-runtime-deps`-Roots, globaler
Node-Präfix-Paket-Symlinks, die auf bereinigte `plugin-runtime-deps`-Ziele verweisen,
Ältere OpenClaw-Versionen erzeugten Wurzeln für Abhängigkeiten gebündelter Plugins beim Start oder
während der Doctor-Reparatur. Die aktuelle Doctor-Bereinigung entfernt diese veralteten Verzeichnisse und
Symlinks, wenn `--fix` verwendet wird, einschließlich alter `plugin-runtime-deps`-Wurzeln, globaler
Node-Präfix-Paket-Symlinks, die auf entfernte `plugin-runtime-deps`-Ziele zeigen,
`.openclaw-runtime-deps*`-Manifeste, generierte Plugin-`node_modules`, Installations-
Stage-Verzeichnisse und paketlokale pnpm-Stores. Das paketierte postinstall entfernt außerdem
diese globalen Symlinks, bevor die alten Ziel-Roots bereinigt werden, damit Upgrades
keine hängenden ESM-Paketimporte zurücklassen.
Stage-Verzeichnisse und paketlokale pnpm-Stores. Das paketierte Postinstall entfernt außerdem
diese globalen Symlinks, bevor die veralteten Zielwurzeln bereinigt werden, damit Upgrades
keine hängenden ESM-Paketimporte hinterlassen.
Diese Pfade sind nur Legacy-Überreste. Neue Installationen sollten sie nicht erstellen.
Diese Pfade sind nur veraltete Überreste. Neue Installationen sollten sie nicht erstellen.

90
docs/de/plugins/manage-plugins.md
View File

@ -1,22 +1,21 @@
---
read_when:
- Sie möchten kurze Beispiele zum Installieren, Auflisten, Aktualisieren oder Deinstallieren von Plugins
- Sie möchten zwischen ClawHub und der Plugin-Verteilung über npm wählen
- Sie möchten schnelle Beispiele zum Installieren, Auflisten, Aktualisieren oder Deinstallieren von Plugins
- Sie möchten zwischen ClawHub und der Plugin-Distribution über npm wählen
- Sie veröffentlichen ein Plugin-Paket
sidebarTitle: Manage plugins
summary: Kurze Beispiele zum Installieren, Auflisten, Deinstallieren, Aktualisieren und Veröffentlichen von OpenClaw-Plugins
title: Plugins verwalten
x-i18n:
generated_at: "2026-05-02T22:19:48Z"
generated_at: "2026-05-05T01:48:32Z"
model: gpt-5.5
provider: openai
source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320
source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c
source_path: plugins/manage-plugins.md
workflow: 16
---
Die meisten Plugin-Workflows bestehen aus wenigen Befehlen: suchen, installieren, den Gateway neu starten,
prüfen und deinstallieren, wenn Sie das Plugin nicht mehr benötigen.
Die meisten Plugin-Workflows bestehen aus wenigen Befehlen: suchen, installieren, den Gateway neu starten, verifizieren und deinstallieren, wenn Sie das Plugin nicht mehr benötigen.
## Plugins auflisten
@ -28,17 +27,17 @@ openclaw plugins list --json
```
Verwenden Sie `--json` für Skripte. Es enthält Registry-Diagnosen und den
statischen `dependencyStatus` jedes Plugins, wenn das Plugin-Paket `dependencies` oder
`optionalDependencies` deklariert.
statischen `dependencyStatus` jedes Plugins, wenn das Plugin-Paket `dependencies`
oder `optionalDependencies` deklariert.
```bash
openclaw plugins list --json \
| jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
```
`plugins list` ist eine kalte Inventarprüfung. Sie zeigt, was OpenClaw aus
Konfiguration, Manifesten und der Plugin-Registry erkennen kann; sie beweist
nicht, dass ein bereits laufender Gateway-Prozess die Plugin-Runtime importiert hat.
`plugins list` ist eine Bestandsprüfung ohne Laufzeitstart. Sie zeigt, was OpenClaw
aus Konfiguration, Manifesten und der Plugin-Registry erkennen kann; sie belegt
nicht, dass ein bereits laufender Gateway-Prozess die Plugin-Laufzeit importiert hat.
## Plugins installieren
@ -72,9 +71,9 @@ openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
```
Verwenden Sie `inspect --runtime`, wenn Sie einen Nachweis benötigen, dass das Plugin Runtime-
Oberflächen wie Tools, Hooks, Dienste, Gateway-Methoden oder Plugin-eigene CLI-
Befehle registriert hat.
Verwenden Sie `inspect --runtime`, wenn Sie einen Nachweis benötigen, dass das Plugin
Laufzeitoberflächen wie Tools, Hooks, Services, Gateway-Methoden oder Plugin-eigene
CLI-Befehle registriert hat.
## Plugins aktualisieren
@ -84,22 +83,25 @@ openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
```
Wenn ein Plugin aus einem npm-Dist-Tag wie `@beta` installiert wurde, verwenden spätere
Aufrufe von `update <plugin-id>` dieses gespeicherte Tag erneut. Wenn Sie eine explizite npm-Spezifikation
übergeben, wird die nachverfolgte Installation für zukünftige Updates auf diese Spezifikation umgestellt.
Wenn ein Plugin von einem npm-dist-tag wie `@beta` installiert wurde, verwenden spätere
`update <plugin-id>`-Aufrufe dieses aufgezeichnete Tag wieder. Durch Übergabe einer
expliziten npm-Angabe wird die nachverfolgte Installation für zukünftige Updates auf
diese Angabe umgestellt.
```bash
openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin
```
Der zweite Befehl verschiebt ein Plugin zurück auf die Standard-Release-Linie
der Registry, wenn es zuvor auf eine genaue Version oder ein Tag festgelegt war.
Der zweite Befehl verschiebt ein Plugin zurück auf die Standard-Release-Linie der Registry,
wenn es zuvor auf eine genaue Version oder ein Tag festgelegt war.
Wenn `openclaw update` im Beta-Kanal ausgeführt wird, versuchen npm- und ClawHub-
Plugin-Einträge der Standardlinie zuerst das passende Plugin-Release `@beta`. Wenn dieses Beta-
Release nicht existiert, fällt OpenClaw auf die gespeicherte Standard-/Latest-Spezifikation zurück.
Genaue Versionen und explizite Tags wie `@rc` oder `@beta` bleiben erhalten.
Plugin-Einträge der Standardlinie zuerst das passende Plugin-Release `@beta`. Wenn dieses
Beta-Release nicht existiert, fällt OpenClaw auf die aufgezeichnete Standard-/Latest-Angabe
zurück. Bei npm-Plugins fällt OpenClaw auch dann zurück, wenn das Beta-Paket existiert,
aber die Installationsvalidierung fehlschlägt. Genaue Versionen und explizite Tags wie
`@rc` oder `@beta` bleiben erhalten.
## Plugins deinstallieren
@ -110,20 +112,19 @@ openclaw plugins uninstall <plugin-id> --keep-files
openclaw gateway restart
```
Die Deinstallation entfernt den Konfigurationseintrag des Plugins, den Plugin-Indexeintrag, Allow-/Deny-List-
Einträge und verknüpfte Ladepfade, sofern zutreffend. Verwaltete Installationsverzeichnisse werden
entfernt, sofern Sie nicht `--keep-files` übergeben.
Die Deinstallation entfernt den Konfigurationseintrag des Plugins, den Plugin-Indexeintrag,
Allow-/Deny-List-Einträge und verknüpfte Ladepfade, sofern zutreffend. Verwaltete
Installationsverzeichnisse werden entfernt, sofern Sie nicht `--keep-files` übergeben.
## Plugins veröffentlichen
Sie können externe Plugins auf [ClawHub](https://clawhub.ai), npmjs.com oder
beiden veröffentlichen.
Sie können externe Plugins auf [ClawHub](https://clawhub.ai), npmjs.com oder beidem
veröffentlichen.
### Auf ClawHub veröffentlichen
ClawHub ist die primäre öffentliche Discovery-Oberfläche für OpenClaw-Plugins. Es bietet
Benutzern durchsuchbare Metadaten, Versionsverlauf und Registry-Scan-Ergebnisse vor der
Installation.
ClawHub ist die primäre öffentliche Auffindbarkeitsoberfläche für OpenClaw-Plugins. Sie bietet
Benutzern vor der Installation durchsuchbare Metadaten, Versionsverlauf und Registry-Scanergebnisse.
```bash
npm i -g clawhub
@ -133,19 +134,19 @@ clawhub package publish your-org/your-plugin
clawhub package publish your-org/your-plugin@v1.0.0
```
Benutzer installieren aus ClawHub mit:
Benutzer installieren von ClawHub mit:
```bash
openclaw plugins install clawhub:<package>
openclaw plugins install <package>
```
Die Kurzform prüft weiterhin zuerst ClawHub.
Die Form ohne Präfix prüft weiterhin zuerst ClawHub.
### Auf npmjs.com veröffentlichen
Native npm-Plugins müssen ein Plugin-Manifest und OpenClaw-
Entrypoint-Metadaten in `package.json` enthalten.
Native npm-Plugins müssen ein Plugin-Manifest und OpenClaw-Entrypoint-Metadaten in
`package.json` enthalten.
```json package.json
{
@ -170,23 +171,22 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
```
Wenn dasselbe Paket auch auf ClawHub verfügbar ist, überspringt `npm:` die ClawHub-Suche und
erzwingt die npm-Auflösung.
Wenn dasselbe Paket auch auf ClawHub verfügbar ist, überspringt `npm:` die ClawHub-Suche
und erzwingt die npm-Auflösung.
## Quellauswahl
## Quellenauswahl
- **ClawHub**: verwenden, wenn Sie OpenClaw-native Discovery, Scan-Zusammenfassungen,
Versionen und Installationshinweise möchten.
- **ClawHub**: verwenden, wenn Sie OpenClaw-native Auffindbarkeit, Scan-Zusammenfassungen,
Versionen und Installationshinweise wünschen.
- **npmjs.com**: verwenden, wenn Sie bereits JavaScript-Pakete ausliefern oder npm-
Dist-Tags-/Private-Registry-Workflows benötigen.
- **Git**: verwenden, wenn Sie direkt aus einem Branch, Tag oder Commit installieren möchten.
- **Lokaler Pfad**: verwenden, wenn Sie ein Plugin auf demselben
Rechner entwickeln oder testen.
dist-tags/private Registry-Workflows benötigen.
- **Git**: verwenden, wenn Sie direkt von einem Branch, Tag oder Commit installieren möchten.
- **Lokaler Pfad**: verwenden, wenn Sie ein Plugin auf demselben Computer entwickeln oder testen.
## Verwandte Themen
- [Plugins](/de/tools/plugin) - Überblick und Fehlerbehebung
- [Plugins](/de/tools/plugin) - Übersicht und Fehlerbehebung
- [`openclaw plugins`](/de/cli/plugins) - vollständige CLI-Referenz
- [ClawHub](/de/tools/clawhub) - Veröffentlichungs- und Registry-Vorgänge
- [ClawHub](/de/tools/clawhub) - Veröffentlichung und Registry-Vorgänge
- [Plugins erstellen](/de/plugins/building-plugins) - ein Plugin-Paket erstellen
- [Plugin-Manifest](/de/plugins/manifest) - Manifest- und Paketmetadaten

86
docs/de/providers/openrouter.md
View File

@ -4,19 +4,19 @@ read_when:
- Sie möchten Modelle über OpenRouter in OpenClaw ausführen
- Sie möchten OpenRouter für die Bildgenerierung verwenden
- Sie möchten OpenRouter für die Videogenerierung verwenden
summary: Verwenden Sie die einheitliche API von OpenRouter, um auf viele Modelle in OpenClaw zuzugreifen
summary: Verwenden Sie die einheitliche API von OpenRouter, um in OpenClaw auf viele Modelle zuzugreifen
title: OpenRouter
x-i18n:
generated_at: "2026-05-04T02:25:32Z"
generated_at: "2026-05-05T01:48:42Z"
model: gpt-5.5
provider: openai
source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244
source_path: providers/openrouter.md
workflow: 16
---
OpenRouter stellt eine **einheitliche API** bereit, die Anfragen über einen einzelnen
Endpunkt und API-Schlüssel an viele Modelle weiterleitet. Sie ist OpenAI-kompatibel, sodass die meisten OpenAI-SDKs durch Umstellen der Basis-URL funktionieren.
OpenRouter stellt eine **einheitliche API** bereit, die Anfragen über einen einzigen
Endpunkt und API-Schlüssel an viele Modelle weiterleitet. Sie ist OpenAI-kompatibel, daher funktionieren die meisten OpenAI-SDKs durch Umstellen der Basis-URL.
## Erste Schritte
@ -30,7 +30,7 @@ Endpunkt und API-Schlüssel an viele Modelle weiterleitet. Sie ist OpenAI-kompat
```
</Step>
<Step title="(Optional) Zu einem bestimmten Modell wechseln">
Onboarding verwendet standardmäßig `openrouter/auto`. Wählen Sie später ein konkretes Modell aus:
Beim Onboarding ist `openrouter/auto` voreingestellt. Wählen Sie später ein konkretes Modell:
```bash
openclaw models set openrouter/<provider>/<model>
@ -59,12 +59,12 @@ Modellreferenzen folgen dem Muster `openrouter/<provider>/<model>`. Die vollstä
verfügbaren Provider und Modelle finden Sie unter [/concepts/model-providers](/de/concepts/model-providers).
</Note>
Gebündelte Fallback-Beispiele:
Mitgelieferte Fallback-Beispiele:
| Modellreferenz | Hinweise |
| --------------------------------- | ------------------------------------ |
| Modellreferenz | Hinweise |
| --------------------------------- | -------------------------------- |
| `openrouter/auto` | Automatisches Routing von OpenRouter |
| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 über MoonshotAI |
| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 über MoonshotAI |
## Bilderzeugung
@ -84,7 +84,7 @@ OpenRouter kann auch das Tool `image_generate` unterstützen. Verwenden Sie ein
}
```
OpenClaw sendet Bildanfragen mit `modalities: ["image", "text"]` an die Chat-Completions-Bild-API von OpenRouter. Gemini-Bildmodelle erhalten unterstützte Hinweise für `aspectRatio` und `resolution` über OpenRouters `image_config`. Verwenden Sie `agents.defaults.imageGenerationModel.timeoutMs` für langsamere OpenRouter-Bildmodelle; der pro Aufruf gesetzte Parameter `timeoutMs` des Tools `image_generate` hat weiterhin Vorrang.
OpenClaw sendet Bildanfragen an die Chat-Completions-Bild-API von OpenRouter mit `modalities: ["image", "text"]`. Gemini-Bildmodelle erhalten unterstützte Hinweise für `aspectRatio` und `resolution` über `image_config` von OpenRouter. Verwenden Sie `agents.defaults.imageGenerationModel.timeoutMs` für langsamere OpenRouter-Bildmodelle; der `timeoutMs`-Parameter pro Aufruf des Tools `image_generate` hat weiterhin Vorrang.
## Videoerzeugung
@ -103,14 +103,14 @@ OpenRouter kann auch das Tool `video_generate` über seine asynchrone `/videos`-
}
```
OpenClaw sendet Text-zu-Video- und Bild-zu-Video-Jobs an OpenRouter, fragt
OpenClaw übermittelt Text-zu-Video- und Bild-zu-Video-Jobs an OpenRouter, fragt
die zurückgegebene `polling_url` ab und lädt das fertige Video von
OpenRouters `unsigned_urls` oder dem dokumentierten Job-Inhaltsendpunkt herunter.
Referenzbilder werden standardmäßig als erstes/letztes Frame-Bild gesendet; Bilder,
`unsigned_urls` von OpenRouter oder dem dokumentierten Job-Inhaltsendpunkt herunter.
Referenzbilder werden standardmäßig als Bilder für den ersten/letzten Frame gesendet; Bilder,
die mit `reference_image` markiert sind, werden als OpenRouter-Eingabereferenzen gesendet. Der
gebündelte Standard `google/veo-3.1-fast` gibt die derzeit unterstützten Dauern von 4/6/8
Sekunden, Auflösungen `720P`/`1080P` und Seitenverhältnisse `16:9`/`9:16`
an. Video-zu-Video ist für OpenRouter nicht registriert, da die vorgelagerte
mitgelieferte Standard `google/veo-3.1-fast` bewirbt die derzeit unterstützten Dauern von 4/6/8
Sekunden, Auflösungen `720P`/`1080P` und Seitenverhältnisse `16:9`/`9:16`.
Video-zu-Video ist für OpenRouter nicht registriert, da die vorgelagerte
Videoerzeugungs-API derzeit Text- und Bildreferenzen akzeptiert.
## Text-to-Speech
@ -136,8 +136,8 @@ Endpunkt `/audio/speech` verwendet werden.
}
```
Wenn `messages.tts.providers.openrouter.apiKey` ausgelassen wird, verwendet TTS
`models.providers.openrouter.apiKey` erneut und danach `OPENROUTER_API_KEY`.
Wenn `messages.tts.providers.openrouter.apiKey` ausgelassen wird, verwendet TTS erneut
`models.providers.openrouter.apiKey` und danach `OPENROUTER_API_KEY`.
## Authentifizierung und Header
@ -154,14 +154,14 @@ die dokumentierten App-Attributions-Header von OpenRouter hinzu:
<Warning>
Wenn Sie den OpenRouter-Provider auf einen anderen Proxy oder eine andere Basis-URL umstellen, injiziert OpenClaw
diese OpenRouter-spezifischen Header oder Anthropic-Cache-Marker **nicht**.
diese OpenRouter-spezifischen Header oder Anthropic-Cache-Markierungen **nicht**.
</Warning>
## Erweiterte Konfiguration
<AccordionGroup>
<Accordion title="Antwort-Caching">
OpenRouter-Antwort-Caching ist optional. Aktivieren Sie es pro OpenRouter-Modell mit
OpenRouter-Antwort-Caching ist Opt-in. Aktivieren Sie es pro OpenRouter-Modell mit
Modellparametern:
```json5
@ -183,30 +183,30 @@ diese OpenRouter-spezifischen Header oder Anthropic-Cache-Marker **nicht**.
OpenClaw sendet `X-OpenRouter-Cache: true` und, wenn konfiguriert,
`X-OpenRouter-Cache-TTL`. `responseCacheClear: true` erzwingt eine Aktualisierung für
die aktuelle Anfrage und speichert die Ersatzantwort. Snake_case-Aliase
die aktuelle Anfrage und speichert die ersetzende Antwort. Snake_case-Aliasse
(`response_cache`, `response_cache_ttl_seconds` und
`response_cache_clear`) werden ebenfalls akzeptiert.
Dies ist getrennt vom Provider-Prompt-Caching und von OpenRouters
Anthropic-`cache_control`-Markern. Es wird nur auf verifizierten
`openrouter.ai`-Routen angewendet, nicht auf benutzerdefinierten Proxy-Basis-URLs.
Dies ist getrennt vom Prompt-Caching des Providers und von den Anthropic-Markierungen
`cache_control` von OpenRouter. Es wird nur auf verifizierte
`openrouter.ai`-Routen angewendet, nicht auf benutzerdefinierte Proxy-Basis-URLs.
</Accordion>
<Accordion title="Anthropic-Cache-Marker">
<Accordion title="Anthropic-Cache-Markierungen">
Auf verifizierten OpenRouter-Routen behalten Anthropic-Modellreferenzen die
OpenRouter-spezifischen Anthropic-`cache_control`-Marker, die OpenClaw für eine
bessere Wiederverwendung des Prompt-Caches bei System-/Entwickler-Prompt-Blöcken nutzt.
OpenRouter-spezifischen Anthropic-Markierungen `cache_control` bei, die OpenClaw für
bessere Wiederverwendung des Prompt-Cache in System-/Developer-Prompt-Blöcken nutzt.
</Accordion>
<Accordion title="Anthropic-Reasoning-Prefill">
Auf verifizierten OpenRouter-Routen entfernen Anthropic-Modellreferenzen mit aktiviertem Reasoning
nachfolgende Assistant-Prefill-Turns, bevor die Anfrage OpenRouter erreicht.
Dies entspricht der Anforderung von Anthropic, dass Reasoning-Konversationen mit einem Benutzer-
Auf verifizierten OpenRouter-Routen verwerfen Anthropic-Modellreferenzen mit aktiviertem Reasoning
abschließende Assistant-Prefill-Turns, bevor die Anfrage OpenRouter erreicht.
Das entspricht der Anforderung von Anthropic, dass Reasoning-Konversationen mit einem User-
Turn enden.
</Accordion>
<Accordion title="Thinking-/Reasoning-Injektion">
<Accordion title="Thinking- / Reasoning-Injektion">
Auf unterstützten Nicht-`auto`-Routen ordnet OpenClaw die ausgewählte Thinking-Stufe
OpenRouter-Proxy-Reasoning-Payloads zu. Nicht unterstützte Modellhinweise und
`openrouter/auto` überspringen diese Reasoning-Injektion. Hunter Alpha überspringt außerdem
@ -216,20 +216,22 @@ diese OpenRouter-spezifischen Header oder Anthropic-Cache-Marker **nicht**.
<Accordion title="DeepSeek-V4-Reasoning-Replay">
Auf verifizierten OpenRouter-Routen füllen `openrouter/deepseek/deepseek-v4-flash` und
`openrouter/deepseek/deepseek-v4-pro` fehlendes `reasoning_content` in
wiedergegebenen Assistant-Turns auf, damit Thinking-/Tool-Konversationen die von DeepSeek V4
erforderliche Anschlussform behalten.
`openrouter/deepseek/deepseek-v4-pro` fehlenden `reasoning_content` bei
wiedergegebenen Assistant-Turns auf, sodass Thinking-/Tool-Konversationen die für DeepSeek V4
erforderliche Follow-up-Form behalten. OpenClaw sendet von OpenRouter unterstützte
`reasoning_effort`-Werte für diese Routen; `xhigh` ist die höchste beworbene
Stufe, und veraltete `max`-Overrides werden `xhigh` zugeordnet.
</Accordion>
<Accordion title="Nur-OpenAI-Anfrageformung">
OpenRouter läuft weiterhin über den Proxy-artigen OpenAI-kompatiblen Pfad, sodass
native nur für OpenAI geltende Anfrageformung wie `serviceTier`, Responses `store`,
OpenAI-Reasoning-Kompatibilitäts-Payloads und Prompt-Cache-Hinweise nicht weitergeleitet werden.
OpenRouter läuft weiterhin über den Proxy-artigen OpenAI-kompatiblen Pfad, daher
wird native, nur für OpenAI geltende Anfrageformung wie `serviceTier`, Responses `store`,
OpenAI-Reasoning-Kompatibilitätspayloads und Prompt-Cache-Hinweise nicht weitergeleitet.
</Accordion>
<Accordion title="Gemini-gestützte Routen">
Gemini-gestützte OpenRouter-Referenzen bleiben auf dem Proxy-Gemini-Pfad: OpenClaw behält
dort die Bereinigung von Gemini-Gedankensignaturen bei, aktiviert aber keine native Gemini-
dort die Bereinigung von Gemini-Denksignaturen bei, aktiviert aber keine native Gemini-
Replay-Validierung oder Bootstrap-Rewrites.
</Accordion>
@ -239,13 +241,13 @@ diese OpenRouter-spezifischen Header oder Anthropic-Cache-Marker **nicht**.
</Accordion>
</AccordionGroup>
## Verwandt
## Verwandte Themen
<CardGroup cols={2}>
<Card title="Modellauswahl" href="/de/concepts/model-providers" icon="layers">
Provider, Modellreferenzen und Failover-Verhalten auswählen.
Auswahl von Providern, Modellreferenzen und Failover-Verhalten.
</Card>
<Card title="Konfigurationsreferenz" href="/de/gateway/configuration-reference" icon="gear">
Vollständige Konfigurationsreferenz für Agenten, Modelle und Provider.
Vollständige Konfigurationsreferenz für Agents, Modelle und Provider.
</Card>
</CardGroup>

642
docs/de/reference/RELEASING.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Suche nach Definitionen öffentlicher Release-Kanäle
- Release-Validierung oder Paketakzeptanz ausführen
- Suche nach Versionsbenennung und Veröffentlichungsrhythmus
summary: Release-Lanes, Operator-Checkliste, Validierungsboxen, Versionsbenennung und Kadenz
- Suche nach Definitionen für öffentliche Veröffentlichungskanäle
- Release-Validierung oder Paketabnahme ausführen
- Suchen nach Versionsbenennung und Veröffentlichungsrhythmus
summary: Release-Lanes, Betreiber-Checkliste, Validierungsboxen, Versionsbenennung und Taktung
title: Release-Richtlinie
x-i18n:
generated_at: "2026-05-04T06:43:44Z"
generated_at: "2026-05-05T01:48:49Z"
model: gpt-5.5
provider: openai
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw hat drei öffentliche Release-Spuren:
OpenClaw hat drei öffentliche Release-Kanäle:
- stable: getaggte Releases, die standardmäßig auf npm `beta` veröffentlichen oder auf npm `latest`, wenn dies ausdrücklich angefordert wird
- beta: Vorab-Release-Tags, die auf npm `beta` veröffentlichen
- dev: der sich fortlaufend bewegende Stand von `main`
- stable: getaggte Releases, die standardmäßig auf npm `beta` veröffentlichen, oder auf npm `latest`, wenn dies ausdrücklich angefordert wird
- beta: Prerelease-Tags, die auf npm `beta` veröffentlichen
- dev: der bewegliche Stand von `main`
## Versionsbenennung
@ -26,249 +26,250 @@ OpenClaw hat drei öffentliche Release-Spuren:
- Git-Tag: `vYYYY.M.D`
- Stabile Korrektur-Release-Version: `YYYY.M.D-N`
- Git-Tag: `vYYYY.M.D-N`
- Beta-Vorab-Release-Version: `YYYY.M.D-beta.N`
- Beta-Prerelease-Version: `YYYY.M.D-beta.N`
- Git-Tag: `vYYYY.M.D-beta.N`
- Monat oder Tag nicht mit führenden Nullen auffüllen
- `latest` bedeutet das aktuell hochgestufte stabile npm-Release
- `beta` bedeutet das aktuelle Beta-Installationsziel
- Stabile und stabile Korrektur-Releases veröffentlichen standardmäßig auf npm `beta`; Release-Verantwortliche können ausdrücklich `latest` anvisieren oder einen geprüften Beta-Build später hochstufen
- Jedes stabile OpenClaw-Release liefert das npm-Paket und die macOS-App zusammen aus;
Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paketpfad, wobei
Build, Signierung und Notarisierung der Mac-App stabilen Releases vorbehalten bleiben, sofern nicht ausdrücklich angefordert
- `latest` bezeichnet das aktuell promotete stabile npm-Release
- `beta` bezeichnet das aktuelle Beta-Installationsziel
- Stabile und stabile Korrektur-Releases veröffentlichen standardmäßig auf npm `beta`; Release-Operatoren können ausdrücklich `latest` als Ziel wählen oder später einen geprüften Beta-Build promoten
- Jedes stabile OpenClaw-Release liefert das npm-Paket und die macOS-App gemeinsam aus;
Beta-Releases validieren und veröffentlichen normalerweise zuerst den npm-/Paket-Pfad, wobei
Build/Signieren/Notarisieren der macOS-App stabilen Releases vorbehalten bleibt, sofern nicht ausdrücklich angefordert
## Release-Takt
- Releases bewegen sich zuerst über Beta
- Releases laufen zuerst über Beta
- Stable folgt erst, nachdem die neueste Beta validiert wurde
- Maintainer erstellen Releases normalerweise von einem `release/YYYY.M.D`-Branch, der
vom aktuellen `main` erstellt wurde, damit Release-Validierung und Korrekturen neue
- Maintainer erstellen Releases normalerweise aus einem Branch `release/YYYY.M.D`, der
aus dem aktuellen `main` erstellt wurde, damit Release-Validierung und Fixes neue
Entwicklung auf `main` nicht blockieren
- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und eine Korrektur benötigt, erstellen Maintainer
den nächsten `-beta.N`-Tag, statt den alten Beta-Tag zu löschen oder neu zu erstellen
- Detailliertes Release-Verfahren, Freigaben, Anmeldedaten und Wiederherstellungshinweise sind
ausschließlich für Maintainer bestimmt
- Wenn ein Beta-Tag gepusht oder veröffentlicht wurde und einen Fix benötigt, erstellen Maintainer
das nächste `-beta.N`-Tag, statt das alte Beta-Tag zu löschen oder neu zu erstellen
- Detailliertes Release-Verfahren, Freigaben, Zugangsdaten und Wiederherstellungshinweise sind
nur für Maintainer bestimmt
## Checkliste für Release-Verantwortliche
## Checkliste für Release-Operatoren
Diese Checkliste ist die öffentliche Form des Release-Ablaufs. Private Anmeldedaten,
Signierung, Notarisierung, Wiederherstellung von dist-tags und Details zu Notfall-Rollbacks bleiben im
Diese Checkliste ist die öffentliche Form des Release-Ablaufs. Private Zugangsdaten,
Signierung, Notarisierung, dist-tag-Wiederherstellung und Details zum Notfall-Rollback bleiben im
nur für Maintainer bestimmten Release-Runbook.
1. Beginnen Sie vom aktuellen `main`: neuesten Stand pullen, bestätigen, dass der Ziel-Commit gepusht ist,
und bestätigen, dass die aktuelle CI auf `main` ausreichend grün ist, um davon zu branchen.
2. Schreiben Sie den obersten Abschnitt von `CHANGELOG.md` anhand der echten Commit-Historie mit
`/changelog` neu, halten Sie Einträge nutzerorientiert, committen und pushen Sie ihn, und führen Sie vor dem Branching
noch einmal Rebase/Pull aus.
1. Starten Sie vom aktuellen `main`: neuesten Stand pullen, bestätigen, dass der Ziel-Commit gepusht ist,
und bestätigen, dass die aktuelle `main`-CI ausreichend grün ist, um davon zu branchen.
2. Schreiben Sie den obersten Abschnitt von `CHANGELOG.md` aus der echten Commit-Historie mit
`/changelog` neu, halten Sie Einträge nutzerorientiert, committen und pushen Sie ihn, und rebasen/pullen
Sie vor dem Branching noch einmal.
3. Prüfen Sie Release-Kompatibilitätsdatensätze in
`src/plugins/compat/registry.ts` und
`src/commands/doctor/shared/deprecation-compat.ts`. Entfernen Sie abgelaufene
Kompatibilität nur, wenn der Upgrade-Pfad weiterhin abgedeckt bleibt, oder dokumentieren Sie, warum sie
absichtlich weitergeführt wird.
4. Erstellen Sie `release/YYYY.M.D` vom aktuellen `main`; führen Sie normale Release-Arbeit nicht
direkt auf `main` aus.
5. Erhöhen Sie jede erforderliche Versionsstelle für den vorgesehenen Tag, führen Sie
`pnpm plugins:sync` aus, damit veröffentlichbare Plugin-Pakete die Release-
Version und Kompatibilitätsmetadaten teilen, und führen Sie anschließend den lokalen deterministischen Preflight aus:
bewusst beibehalten wird.
4. Erstellen Sie `release/YYYY.M.D` aus dem aktuellen `main`; führen Sie normale Release-Arbeiten nicht
direkt auf `main` durch.
5. Erhöhen Sie jede erforderliche Versionsstelle für das vorgesehene Tag, führen Sie
`pnpm plugins:sync` aus, damit veröffentlichbare Plugin-Pakete die Release-Version
und Kompatibilitätsmetadaten teilen, und führen Sie anschließend den lokalen deterministischen Preflight aus:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` und
`pnpm release:check`.
6. Führen Sie `OpenClaw NPM Release` mit `preflight_only=true` aus. Bevor ein Tag existiert,
ist ein vollständiger 40-stelliger Release-Branch-SHA für ausschließlich validierenden
Preflight zulässig. Speichern Sie die erfolgreiche `preflight_run_id`.
ist ein vollständiger 40-Zeichen-SHA des Release-Branchs für einen reinen Validierungs-Preflight zulässig.
Speichern Sie die erfolgreiche `preflight_run_id`.
7. Starten Sie alle Pre-Release-Tests mit `Full Release Validation` für den
Release-Branch, Tag oder vollständigen Commit-SHA. Dies ist der eine manuelle Einstiegspunkt
Release-Branch, das Tag oder den vollständigen Commit-SHA. Dies ist der einzige manuelle Einstiegspunkt
für die vier großen Release-Testboxen: Vitest, Docker, QA Lab und Package.
8. Wenn die Validierung fehlschlägt, beheben Sie das Problem auf dem Release-Branch und führen Sie die kleinste fehlgeschlagene
Datei, Spur, den Workflow-Job, das Package-Profil, den Provider oder die Modell-Allowlist erneut aus, die
die Korrektur belegt. Führen Sie das vollständige Dach nur erneut aus, wenn die geänderte Oberfläche
frühere Nachweise veraltet macht.
9. Für Beta taggen Sie `vYYYY.M.D-beta.N` und führen anschließend `OpenClaw Release Publish` vom
passenden `release/YYYY.M.D`-Branch aus. Es verifiziert `pnpm plugins:sync:check`,
8. Wenn die Validierung fehlschlägt, beheben Sie das Problem im Release-Branch und führen Sie die kleinste fehlgeschlagene
Datei, Lane, Workflow-Job, Paketprofil, Provider- oder Modell-Allowlist erneut aus, die
den Fix nachweist. Führen Sie das vollständige Umbrella nur erneut aus, wenn die geänderte Oberfläche
frühere Nachweise veralten lässt.
9. Für Beta taggen Sie `vYYYY.M.D-beta.N` und führen dann `OpenClaw Release Publish` aus
dem passenden Branch `release/YYYY.M.D` aus. Es verifiziert `pnpm plugins:sync:check`,
veröffentlicht zuerst alle veröffentlichbaren Plugin-Pakete auf npm, veröffentlicht denselben
Satz danach auf ClawHub als ClawPack-npm-pack-Tarballs und stuft dann das
vorbereitete OpenClaw-npm-Preflight-Artefakt mit dem passenden dist-tag hoch. Nach der
Veröffentlichung führen Sie die Package-Akzeptanz nach der Veröffentlichung gegen das veröffentlichte
Paket `openclaw@YYYY.M.D-beta.N` oder `openclaw@beta` aus. Wenn ein gepushter oder veröffentlichter Vorab-Release eine Korrektur benötigt,
erstellen Sie die nächste passende Vorab-Release-Nummer; löschen oder überschreiben Sie den alten
Vorab-Release nicht.
Satz anschließend als ClawPack npm-pack-Tarballs auf ClawHub und promotet dann das
vorbereitete OpenClaw-npm-Preflight-Artefakt mit dem passenden dist-tag. Führen Sie nach
der Veröffentlichung die Package-Acceptance nach dem Publish gegen das veröffentlichte
Paket `openclaw@YYYY.M.D-beta.N` oder `openclaw@beta` aus. Wenn ein gepushter oder veröffentlichter
Prerelease einen Fix benötigt, erstellen Sie die nächste passende Prerelease-Nummer; löschen oder überschreiben Sie den alten
Prerelease nicht.
10. Für Stable fahren Sie erst fort, nachdem die geprüfte Beta oder der Release Candidate die
erforderlichen Validierungsnachweise hat. Die stabile npm-Veröffentlichung läuft ebenfalls über
`OpenClaw Release Publish`, wobei das erfolgreiche Preflight-Artefakt über
`preflight_run_id` wiederverwendet wird; die Release-Bereitschaft für stabiles macOS erfordert außerdem die
paketierten `.zip`, `.dmg`, `.dSYM.zip` und die aktualisierte `appcast.xml` auf `main`.
11. Nach der Veröffentlichung führen Sie den npm-Post-Publish-Verifizierer aus, optional die eigenständige
Telegram-E2E mit veröffentlichtem npm, wenn Sie Channel-Nachweis nach der Veröffentlichung benötigen,
dist-tag-Hochstufung bei Bedarf, GitHub-Release-/Vorab-Release-Notizen aus dem
vollständigen passenden Abschnitt von `CHANGELOG.md` sowie die Schritte für die Release-Ankündigung.
`OpenClaw Release Publish` und verwendet das erfolgreiche Preflight-Artefakt über
`preflight_run_id` wieder; die Release-Bereitschaft für stabiles macOS erfordert außerdem die
gepackten `.zip`, `.dmg`, `.dSYM.zip` und eine aktualisierte `appcast.xml` auf `main`.
11. Führen Sie nach der Veröffentlichung den npm-Post-Publish-Verifier aus, optional das eigenständige
veröffentlichte-npm-Telegram-E2E, wenn Sie einen Nachweis für den Kanal nach der Veröffentlichung benötigen,
dist-tag-Promotion bei Bedarf, GitHub-Release-/Prerelease-Notes aus dem
vollständig passenden Abschnitt von `CHANGELOG.md` sowie die Schritte zur Release-Ankündigung.
## Release-Preflight
- Führen Sie `pnpm check:test-types` vor dem Release-Preflight aus, damit Test-TypeScript
außerhalb des schnelleren lokalen `pnpm check`-Gates abgedeckt bleibt
- Führen Sie `pnpm check:architecture` vor dem Release-Preflight aus, damit die umfassenderen Prüfungen auf Importzyklen
- Führen Sie `pnpm check:test-types` vor dem Release-Preflight aus, damit Test-TypeScript auch außerhalb des schnelleren lokalen `pnpm check`-Gates
abgedeckt bleibt
- Führen Sie `pnpm check:architecture` vor dem Release-Preflight aus, damit die umfassenderen Prüfungen für Importzyklen
und Architekturgrenzen außerhalb des schnelleren lokalen Gates grün sind
- Führen Sie `pnpm build && pnpm ui:build` vor `pnpm release:check` aus, damit die erwarteten
`dist/*`-Release-Artefakte und das Control-UI-Bundle für den Pack-
`dist/*`-Release-Artefakte und das Control UI-Bundle für den Pack-
Validierungsschritt vorhanden sind
- Führen Sie `pnpm plugins:sync` nach dem Root-Versionsbump und vor dem Tagging aus. Es
aktualisiert veröffentlichbare Plugin-Paketversionen, OpenClaw-Peer/API-Kompatibilitäts-
Metadaten, Build-Metadaten und Plugin-Changelog-Stubs passend zur Core-
Release-Version. `pnpm plugins:sync:check` ist der nicht mutierende Release-Guard;
der Veröffentlichungs-Workflow schlägt vor jeder Registry-Mutation fehl, wenn dieser Schritt
- Führen Sie `pnpm plugins:sync` nach dem Root-Versions-Bump und vor dem Tagging aus. Es
aktualisiert die Versionen veröffentlichbarer Plugin-Pakete, OpenClaw-Peer-/API-Kompatibilitäts-
Metadaten, Build-Metadaten und Plugin-Changelog-Stubs, damit sie zur Core-
Release-Version passen. `pnpm plugins:sync:check` ist der nicht verändernde Release-Guard;
der Publish-Workflow schlägt vor jeder Registry-Mutation fehl, wenn dieser Schritt
vergessen wurde.
- Führen Sie den manuellen `Full Release Validation`-Workflow vor der Release-Freigabe aus, um
alle Pre-Release-Testboxen von einem Einstiegspunkt aus zu starten. Er akzeptiert einen Branch,
Tag oder vollständigen Commit-SHA, stößt manuelles `CI` an und stößt
`OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Docker-
Release-Pfad-Suites, Live/E2E, OpenWebUI, QA-Lab-Parität, Matrix- und Telegram-
Lanes an. Mit `release_profile=full` und `rerun_group=all` führt er außerdem Package
Telegram E2E gegen das `release-package-under-test`-Artefakt aus den Release-
Checks aus. Geben Sie `npm_telegram_package_spec` nach der Veröffentlichung an, wenn derselbe
Telegram E2E auch das veröffentlichte npm-Paket nachweisen soll. Geben Sie
alle Pre-Release-Testboxen über einen Einstiegspunkt zu starten. Er akzeptiert einen Branch,
ein Tag oder einen vollständigen Commit-SHA, dispatcht manuelles `CI` und dispatcht
`OpenClaw Release Checks` für Install-Smoke, Package Acceptance, Cross-OS-
Paketprüfungen, QA Lab-Parität, Matrix- und Telegram-Lanes. Stabile/standardmäßige Läufe
halten umfassende Live-/E2E- und Docker-Release-Pfad-Soaks hinter
`run_release_soak=true`; `release_profile=full` erzwingt den Soak. Mit
`release_profile=full` und `rerun_group=all` wird außerdem Paket-Telegram-
E2E gegen das `release-package-under-test`-Artefakt aus den Release Checks ausgeführt.
Geben Sie `npm_telegram_package_spec` nach der Veröffentlichung an, wenn dasselbe
Telegram-E2E auch das veröffentlichte npm-Paket nachweisen soll. Geben Sie
`package_acceptance_package_spec` nach der Veröffentlichung an, wenn Package Acceptance
seine Paket-/Update-Matrix gegen das ausgelieferte npm-Paket statt
gegen das aus dem SHA gebaute Artefakt ausführen soll. Geben Sie
`evidence_package_spec` an, wenn der private Evidenzbericht nachweisen soll, dass die
Validierung zu einem veröffentlichten npm-Paket passt, ohne Telegram E2E zu erzwingen.
Validierung einem veröffentlichten npm-Paket entspricht, ohne Telegram-E2E zu erzwingen.
Beispiel:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- Führen Sie den manuellen `Package Acceptance`-Workflow aus, wenn Sie Side-Channel-Nachweise
für einen Paketkandidaten wünschen, während die Release-Arbeit weiterläuft. Verwenden Sie `source=npm` für
für einen Paketkandidaten benötigen, während die Release-Arbeit weiterläuft. Verwenden Sie `source=npm` für
`openclaw@beta`, `openclaw@latest` oder eine exakte Release-Version; `source=ref`,
um einen vertrauenswürdigen `package_ref`-Branch/Tag/SHA mit dem aktuellen
um einen vertrauenswürdigen `package_ref`-Branch/-Tag/-SHA mit dem aktuellen
`workflow_ref`-Harness zu packen; `source=url` für einen HTTPS-Tarball mit erforderlichem
SHA-256; oder `source=artifact` für einen Tarball, der von einem anderen GitHub-
SHA-256; oder `source=artifact` für einen Tarball, der von einem anderen GitHub
Actions-Lauf hochgeladen wurde. Der Workflow löst den Kandidaten zu
`package-under-test` auf, verwendet den Docker-E2E-Release-Scheduler gegen diesen
Tarball wieder und kann Telegram-QA gegen denselben Tarball mit
Tarball wieder und kann Telegram QA gegen denselben Tarball mit
`telegram_mode=mock-openai` oder `telegram_mode=live-frontier` ausführen. Wenn die
ausgewählten Docker-Lanes `published-upgrade-survivor` enthalten, ist das Paket-
Artefakt der Kandidat und `published_upgrade_survivor_baseline` wählt
die veröffentlichte Baseline aus.
ausgewählten Docker-Lanes `published-upgrade-survivor` enthalten, ist das Paketartefakt
der Kandidat und `published_upgrade_survivor_baseline` wählt die veröffentlichte Baseline aus.
Beispiel: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
Häufige Profile:
- `smoke`: Installations-/Kanal-/Agent-, Gateway-Netzwerk- und Konfigurations-Reload-Lanes
Gängige Profile:
- `smoke`: Installations-/Kanal-/Agent-, Gateway-Netzwerk- und Config-Reload-Lanes
- `package`: artefaktnative Paket-/Update-/Plugin-Lanes ohne OpenWebUI oder Live-ClawHub
- `product`: Paketprofil plus MCP-Kanäle, Cron-/Subagent-Bereinigung,
OpenAI-Websuche und OpenWebUI
- `full`: Docker-Release-Pfad-Blöcke mit OpenWebUI
- `full`: Docker-Release-Pfad-Chunks mit OpenWebUI
- `custom`: exakte `docker_lanes`-Auswahl für einen fokussierten erneuten Lauf
- Führen Sie den manuellen `CI`-Workflow direkt aus, wenn Sie nur die vollständige normale CI-
Abdeckung für den Release-Kandidaten benötigen. Manuelle CI-Dispatches umgehen das Changed-
Scoping und erzwingen die Linux-Node-Shards, Bundled-Plugin-Shards, Kanal-
Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke,
Docs-Prüfungen, Python-Skills, Windows, macOS, Android und Control-UI-i18n-
Docs-Prüfungen, Python-Skills, Windows, macOS, Android und Control UI-i18n-
Lanes.
Beispiel: `gh workflow run ci.yml --ref release/YYYY.M.D`
- Führen Sie `pnpm qa:otel:smoke` aus, wenn Sie Release-Telemetrie validieren. Es führt
QA-Lab über einen lokalen OTLP/HTTP-Empfänger aus und verifiziert die exportierten Trace-
Span-Namen, begrenzten Attribute sowie Inhalts-/Kennungs-Redaktion, ohne
Opik, Langfuse oder einen anderen externen Collector zu benötigen.
- Führen Sie `pnpm qa:otel:smoke` aus, wenn Sie Release-Telemetrie validieren. Es übt
QA-Lab über einen lokalen OTLP/HTTP-Receiver aus und prüft die exportierten Trace-
Span-Namen, begrenzten Attribute sowie die Redaktion von Inhalt/Identifiern, ohne
Opik, Langfuse oder einen anderen externen Collector zu erfordern.
- Führen Sie `pnpm release:check` vor jedem getaggten Release aus
- Führen Sie `OpenClaw Release Publish` für die mutierende Veröffentlichungssequenz aus, nachdem das
- Führen Sie `OpenClaw Release Publish` für die verändernde Publish-Sequenz aus, nachdem das
Tag existiert. Dispatchen Sie ihn von `release/YYYY.M.D` (oder `main`, wenn Sie ein
von main erreichbares Tag veröffentlichen), übergeben Sie das Release-Tag und die erfolgreiche OpenClaw-npm-
`preflight_run_id` und behalten Sie den standardmäßigen Plugin-Veröffentlichungsumfang
`all-publishable` bei, sofern Sie nicht bewusst eine fokussierte Reparatur ausführen. Der
Workflow serialisiert Plugin-npm-Veröffentlichung, Plugin-ClawHub-Veröffentlichung und OpenClaw-
npm-Veröffentlichung, damit das Core-Paket nicht vor seinen externalisierten
`preflight_run_id`, und behalten Sie den standardmäßigen Plugin-Publish-Scope
`all-publishable` bei, außer Sie führen bewusst eine fokussierte Reparatur aus. Der
Workflow serialisiert Plugin-npm-Publish, Plugin-ClawHub-Publish und OpenClaw-
npm-Publish, damit das Core-Paket nicht vor seinen externalisierten
Plugins veröffentlicht wird.
- Release-Prüfungen laufen jetzt in einem separaten manuellen Workflow:
- Release Checks laufen jetzt in einem separaten manuellen Workflow:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` führt vor der Release-Freigabe außerdem die QA-Lab-Mock-Paritäts-Lane sowie das schnelle
- `OpenClaw Release Checks` führt außerdem vor der Release-Freigabe die QA Lab-Mock-Parity-Lane plus das schnelle
Live-Matrix-Profil und die Telegram-QA-Lane aus. Die Live-
Lanes verwenden die Umgebung `qa-live-shared`; Telegram verwendet außerdem Convex-CI-
Lanes verwenden die `qa-live-shared`-Umgebung; Telegram verwendet außerdem Convex-CI-
Credential-Leases. Führen Sie den manuellen `QA-Lab - All Lanes`-Workflow mit
`matrix_profile=all` und `matrix_shards=true` aus, wenn Sie vollständigen Matrix-
Transport, Medien und E2EE-Inventar parallel wünschen.
- Cross-OS-Installations- und Upgrade-Laufzeitvalidierung ist Teil der öffentlichen
`matrix_profile=all` und `matrix_shards=true` aus, wenn Sie das vollständige Matrix-
Transport-, Medien- und E2EE-Inventar parallel benötigen.
- Cross-OS-Installations- und Upgrade-Runtime-Validierung ist Teil der öffentlichen
`OpenClaw Release Checks` und `Full Release Validation`, die den
wiederverwendbaren Workflow
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml` direkt aufrufen
- Diese Aufteilung ist beabsichtigt: Der echte npm-Release-Pfad bleibt kurz,
deterministisch und artefaktorientiert, während langsamere Live-Prüfungen in ihrer
eigenen Lane bleiben, damit sie die Veröffentlichung nicht verzögern oder blockieren
- Diese Aufteilung ist beabsichtigt: Halten Sie den echten npm-Release-Pfad kurz,
deterministisch und artefaktfokussiert, während langsamere Live-Prüfungen in ihrer
eigenen Lane bleiben, damit sie Publish nicht verzögern oder blockieren
- Release-Prüfungen mit Secrets sollten über `Full Release
Validation` oder aus der `main`-/Release-Workflow-Ref dispatcht werden, damit Workflow-Logik und
Validation` oder vom `main`-/Release-Workflow-Ref dispatcht werden, damit Workflow-Logik und
Secrets kontrolliert bleiben
- `OpenClaw Release Checks` akzeptiert einen Branch, ein Tag oder einen vollständigen Commit-SHA, solange
der aufgelöste Commit von einem OpenClaw-Branch oder Release-Tag erreichbar ist
- Der reine Validierungs-Preflight von `OpenClaw NPM Release` akzeptiert auch den aktuellen
vollständigen 40-Zeichen-Workflow-Branch-Commit-SHA, ohne ein gepushtes Tag zu erfordern
- Dieser SHA-Pfad dient nur der Validierung und kann nicht in eine echte Veröffentlichung
- Der nur validierende Preflight von `OpenClaw NPM Release` akzeptiert außerdem den aktuellen
vollständigen 40-Zeichen-Workflow-Branch-Commit-SHA, ohne ein gepushtes Tag zu verlangen
- Dieser SHA-Pfad ist nur für die Validierung vorgesehen und kann nicht in einen echten Publish
überführt werden
- Im SHA-Modus synthetisiert der Workflow `v<package.json version>` nur für die
Paketmetadatenprüfung; echte Veröffentlichung erfordert weiterhin ein echtes Release-Tag
- Beide Workflows behalten den echten Veröffentlichungs- und Promotion-Pfad auf GitHub-gehosteten
Runnern, während der nicht mutierende Validierungspfad die größeren
Paketmetadatenprüfung; ein echter Publish erfordert weiterhin ein echtes Release-Tag
- Beide Workflows belassen den echten Publish- und Promotion-Pfad auf GitHub-gehosteten
Runnern, während der nicht verändernde Validierungspfad die größeren
Blacksmith-Linux-Runner verwenden kann
- Dieser Workflow führt
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
unter Verwendung der Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus
mit den Workflow-Secrets `OPENAI_API_KEY` und `ANTHROPIC_API_KEY` aus
- Der npm-Release-Preflight wartet nicht mehr auf die separate Release-Checks-Lane
- Führen Sie `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(oder das passende Beta-/Korrektur-Tag) vor der Freigabe aus
- Führen Sie nach der npm-Veröffentlichung
(oder das passende Beta-/Correction-Tag) vor der Freigabe aus
- Führen Sie nach dem npm-Publish
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(oder die passende Beta-/Korrekturversion) aus, um den veröffentlichten Registry-
Installationspfad in einem frischen temporären Präfix zu verifizieren
- Führen Sie nach einer Beta-Veröffentlichung `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
aus, um Installed-Package-Onboarding, Telegram-Einrichtung und echtes Telegram E2E
gegen das veröffentlichte npm-Paket mit dem gemeinsamen geleasten Telegram-Credential-
Pool zu verifizieren. Lokale Maintainer-Einmalläufe können die Convex-Variablen weglassen und die drei
(oder die passende Beta-/Correction-Version) aus, um den veröffentlichten Registry-
Installationspfad in einem frischen temporären Präfix zu prüfen
- Führen Sie nach einem Beta-Publish `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
aus, um Installed-Package-Onboarding, Telegram-Einrichtung und echtes Telegram-E2E
gegen das veröffentlichte npm-Paket mit dem gemeinsam geleasten Telegram-Credential-
Pool zu prüfen. Lokale einmalige Maintainer-Läufe können die Convex-Variablen weglassen und die drei
`OPENCLAW_QA_TELEGRAM_*`-Env-Credentials direkt übergeben.
- Um den vollständigen Post-Publish-Beta-Smoke von einem Maintainer-Rechner aus auszuführen, verwenden Sie `pnpm release:beta-smoke -- --beta betaN`. Der Helper führt Parallels-npm-Update-/Fresh-Target-Validierung aus, dispatcht `NPM Telegram Beta E2E`, pollt den exakten Workflow-Lauf, lädt das Artefakt herunter und gibt den Telegram-Bericht aus.
- Um den vollständigen Post-Publish-Beta-Smoke von einem Maintainer-Rechner auszuführen, verwenden Sie `pnpm release:beta-smoke -- --beta betaN`. Der Helper führt Parallels-npm-Update-/Fresh-Target-Validierung aus, dispatcht `NPM Telegram Beta E2E`, pollt den exakten Workflow-Lauf, lädt das Artefakt herunter und gibt den Telegram-Bericht aus.
- Maintainer können dieselbe Post-Publish-Prüfung über GitHub Actions mit dem
manuellen `NPM Telegram Beta E2E`-Workflow ausführen. Er ist absichtlich nur manuell und
läuft nicht bei jedem Merge.
- Maintainer-Release-Automatisierung verwendet jetzt Preflight-dann-Promote:
- echte npm-Veröffentlichung muss eine erfolgreiche npm-`preflight_run_id` bestanden haben
- die echte npm-Veröffentlichung muss vom selben `main`- oder
manuellen `NPM Telegram Beta E2E`-Workflow ausführen. Er ist absichtlich nur manuell
und läuft nicht bei jedem Merge.
- Maintainer-Release-Automation verwendet jetzt Preflight-dann-Promote:
- echter npm-Publish muss eine erfolgreiche npm-`preflight_run_id` bestehen
- der echte npm-Publish muss vom selben `main`- oder
`release/YYYY.M.D`-Branch dispatcht werden wie der erfolgreiche Preflight-Lauf
- stabile npm-Releases verwenden standardmäßig `beta`
- stabile npm-Veröffentlichung kann über Workflow-Eingabe explizit `latest` anvisieren
- tokenbasierte npm-Dist-Tag-Mutation liegt jetzt in
- stabiler npm-Publish kann über Workflow-Eingabe explizit `latest` anvisieren
- tokenbasierte npm-dist-tag-Mutation lebt jetzt in
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
aus Sicherheitsgründen, weil `npm dist-tag add` weiterhin `NPM_TOKEN` benötigt, während das
öffentliche Repo OIDC-only-Veröffentlichung beibehält
- öffentliches `macOS Release` dient nur der Validierung; wenn ein Tag nur auf einem
Release-Branch existiert, der Workflow aber von `main` dispatcht wird, setzen Sie
öffentliche Repo OIDC-only Publish beibehält
- öffentliches `macOS Release` ist nur validierend; wenn ein Tag nur auf einem
Release-Branch lebt, der Workflow aber von `main` dispatcht wird, setzen Sie
`public_release_branch=release/YYYY.M.D`
- echte private Mac-Veröffentlichung muss erfolgreiche private Mac-
`preflight_run_id` und `validate_run_id` bestanden haben
- die echten Veröffentlichungspfade promoten vorbereitete Artefakte, statt sie
erneut zu bauen
- Für stabile Korrektur-Releases wie `YYYY.M.D-N` prüft der Post-Publish-Verifier
außerdem denselben Temp-Präfix-Upgrade-Pfad von `YYYY.M.D` zu `YYYY.M.D-N`,
damit Release-Korrekturen ältere globale Installationen nicht unbemerkt auf der
stabilen Basis-Payload zurücklassen können
- echter privater Mac-Publish muss erfolgreiche private Mac-
`preflight_run_id` und `validate_run_id` bestehen
- die echten Publish-Pfade promoten vorbereitete Artefakte, statt sie erneut
zu bauen
- Bei stabilen Correction-Releases wie `YYYY.M.D-N` prüft der Post-Publish-Verifier
außerdem denselben Temp-Prefix-Upgrade-Pfad von `YYYY.M.D` zu `YYYY.M.D-N`,
damit Release-Corrections ältere globale Installationen nicht stillschweigend auf dem
Basis-Stable-Payload belassen können
- Der npm-Release-Preflight schlägt geschlossen fehl, sofern der Tarball nicht sowohl
`dist/control-ui/index.html` als auch eine nicht leere `dist/control-ui/assets/`-Payload enthält,
`dist/control-ui/index.html` als auch einen nicht leeren `dist/control-ui/assets/`-Payload enthält,
damit wir nicht erneut ein leeres Browser-Dashboard ausliefern
- Die Post-Publish-Verifizierung prüft außerdem, dass veröffentlichte Plugin-Einstiegspunkte und
- Die Post-Publish-Validierung prüft außerdem, dass veröffentlichte Plugin-Entrypoints und
Paketmetadaten im installierten Registry-Layout vorhanden sind. Ein Release, das
fehlende Plugin-Runtime-Payloads ausliefert, lässt den Postpublish-Verifier fehlschlagen und
fehlende Plugin-Runtime-Payloads ausliefert, schlägt im Postpublish-Verifier fehl und
kann nicht zu `latest` promotet werden.
- `pnpm test:install:smoke` erzwingt außerdem das npm-Pack-`unpackedSize`-Budget für
den Kandidaten-Update-Tarball, sodass Installer-E2E versehentliches Pack-Bloat
vor dem Release-Veröffentlichungspfad erkennt
- `pnpm test:install:smoke` erzwingt außerdem das npm-pack-`unpackedSize`-Budget für
den Kandidaten-Update-Tarball, damit Installer-E2E versehentlichen Pack-Bloat
vor dem Release-Publish-Pfad erkennt
- Wenn die Release-Arbeit CI-Planung, Extension-Timing-Manifeste oder
Extension-Testmatrizen berührt hat, generieren und prüfen Sie vor der Freigabe die vom Planner verwalteten
Extension-Testmatrizen berührt hat, regenerieren und prüfen Sie vor der Freigabe die planner-eigenen
`plugin-prerelease-extension-shard`-Matrix-Ausgaben aus
`.github/workflows/plugin-prerelease.yml`, damit Release Notes keine
veraltete CI-Struktur beschreiben
- Die Bereitschaft eines stabilen macOS-Releases umfasst auch die Updater-Oberflächen:
- das GitHub-Release muss am Ende die gepackte `.zip`, `.dmg` und `.dSYM.zip` enthalten
- `appcast.xml` auf `main` muss nach der Veröffentlichung auf die neue stabile Zip verweisen
- die gepackte App muss eine Nicht-Debug-Bundle-ID, eine nicht leere Sparkle-Feed-
`.github/workflows/plugin-prerelease.yml`, damit Release Notes kein veraltetes CI-Layout
beschreiben
- Die Bereitschaft für stabile macOS-Releases umfasst außerdem die Updater-Oberflächen:
- Das GitHub-Release muss am Ende das paketierte `.zip`, `.dmg` und `.dSYM.zip` enthalten
- `appcast.xml` auf `main` muss nach dem Publish auf das neue stabile Zip zeigen
- Die paketierte App muss eine nicht-Debug-Bundle-ID, eine nicht leere Sparkle-Feed-
URL und eine `CFBundleVersion` auf oder über dem kanonischen Sparkle-Build-Floor
für diese Release-Version behalten
## Release-Testboxen
`Full Release Validation` ist der Weg, wie Operatoren alle Pre-Release-Tests von
einem Einstiegspunkt aus starten. Für einen gepinnten Commit-Nachweis auf einem schnelllebigen Branch verwenden Sie den
Helper, damit jeder Child-Workflow von einem temporären Branch ausgeht, der auf den Ziel-
`Full Release Validation` ist die Methode, mit der Betreiber alle Pre-Release-Tests von
einem Einstiegspunkt aus starten. Für einen gepinnten Commit-Nachweis auf einem schnell beweglichen Branch verwenden Sie den
Helper, damit jeder Child-Workflow von einem temporären Branch ausgeführt wird, der auf den Ziel-
SHA fixiert ist:
```bash
@ -276,11 +277,11 @@ pnpm ci:full-release --sha <full-sha>
```
Der Helper pusht `release-ci/<sha>-...`, dispatcht `Full Release Validation`
von diesem Branch mit `ref=<sha>`, verifiziert, dass jede Child-Workflow-`headSha`
zum Ziel passt, und löscht dann den temporären Branch. Dadurch wird vermieden, versehentlich einen
neueren `main`-Child-Lauf nachzuweisen.
von diesem Branch mit `ref=<sha>`, prüft, dass jeder Child-Workflow-`headSha`
dem Ziel entspricht, und löscht dann den temporären Branch. Dies verhindert, dass versehentlich ein
neuerer `main`-Child-Lauf nachgewiesen wird.
Für Release-Branch- oder Tag-Validierung führen Sie ihn von der vertrauenswürdigen `main`-Workflow-
Für Release-Branch- oder Tag-Validierung führen Sie ihn vom vertrauenswürdigen `main`-Workflow-
Ref aus und übergeben den Release-Branch oder das Tag als `ref`:
```bash
@ -295,45 +296,51 @@ gh workflow run full-release-validation.yml \
Der Workflow löst die Ziel-Ref auf, dispatcht manuell `CI` mit
`target_ref=<release-ref>`, dispatcht `OpenClaw Release Checks`, bereitet ein
übergeordnetes `release-package-under-test`-Artefakt für packagebezogene Checks
vor und dispatcht eigenständiges Package-Telegram-E2E, wenn `release_profile=full` mit
`rerun_group=all` verwendet wird oder wenn `npm_telegram_package_spec` gesetzt ist. `OpenClaw Release
Checks` fächert anschließend in Install-Smoke, Cross-OS-Release-Checks,
Live/E2E-Docker-Abdeckung für den Release-Pfad, Package Acceptance mit Telegram-Package-QA, QA Lab
Parity, Live Matrix und Live Telegram auf. Ein vollständiger Lauf ist nur akzeptabel, wenn die
Zusammenfassung von `Full Release Validation` `normal_ci` und `release_checks` als erfolgreich
anzeigt. Im full/all-Modus muss auch das Kind `npm_telegram` erfolgreich sein; außerhalb von full/all wird es übersprungen,
übergeordnetes `release-package-under-test`-Artefakt für paketbezogene Prüfungen
vor und dispatcht eigenständige Paket-Telegram-E2E, wenn `release_profile=full`
mit `rerun_group=all` verwendet wird oder wenn `npm_telegram_package_spec` gesetzt ist. `OpenClaw Release
Checks` fächert dann Install-Smoke, Cross-OS-Release-Prüfungen, Live-/E2E-Docker-
Release-Pfad-Abdeckung bei aktiviertem Soak, Package Acceptance mit Telegram-
Paket-QA, QA-Lab-Parität, Live-Matrix und Live-Telegram auf. Ein vollständiger Lauf ist nur akzeptabel, wenn die
Zusammenfassung von `Full Release Validation`
`normal_ci` und `release_checks` als erfolgreich ausweist. Im Full-/All-Modus
muss auch das Kind `npm_telegram` erfolgreich sein; außerhalb von Full/All wird es übersprungen,
sofern keine veröffentlichte `npm_telegram_package_spec` angegeben wurde. Die abschließende
Verifier-Zusammenfassung enthält Tabellen der langsamsten Jobs für jeden Kindlauf, sodass die Release-Verantwortlichen
den aktuellen kritischen Pfad sehen können, ohne Logs herunterzuladen.
Verifier-Zusammenfassung enthält Tabellen mit den langsamsten Jobs für jeden Kindlauf, damit der Release
Manager den aktuellen kritischen Pfad sehen kann, ohne Logs herunterzuladen.
Siehe [Vollständige Release-Validierung](/de/reference/full-release-validation) für die
vollständige Stufenmatrix, exakte Workflow-Jobnamen, Unterschiede zwischen stable- und full-Profil,
Artefakte und fokussierte Rerun-Handles.
vollständige Stufenmatrix, exakte Workflow-Jobnamen, Unterschiede zwischen Stable- und Full-Profil,
Artefakte und gezielte Rerun-Handles.
Kind-Workflows werden von der vertrauenswürdigen Ref dispatcht, die `Full Release
Validation` ausführt, normalerweise `--ref main`, auch wenn die Ziel-`ref` auf einen
älteren Release-Branch oder Tag zeigt. Es gibt keine separate Full-Release-Validation-
Workflow-Ref-Eingabe; wählen Sie den vertrauenswürdigen Harness, indem Sie die Ref des Workflow-Laufs wählen.
Validation` ausführt, normalerweise `--ref main`, selbst wenn die Ziel-`ref` auf einen
älteren Release-Branch oder Tag zeigt. Es gibt keine separate Workflow-Ref-Eingabe für Full Release Validation;
wählen Sie den vertrauenswürdigen Harness, indem Sie die Ref des Workflow-Laufs wählen.
Verwenden Sie `--ref main -f ref=<sha>` nicht für exakten Commit-Nachweis auf einem beweglichen `main`;
rohe Commit-SHAs können keine Workflow-Dispatch-Refs sein, verwenden Sie daher
`pnpm ci:full-release --sha <sha>`, um den gepinnten temporären Branch zu erstellen.
`pnpm ci:full-release --sha <sha>`, um den angehefteten temporären Branch zu erstellen.
Verwenden Sie `release_profile`, um die Live-/Provider-Breite auszuwählen:
- `minimum`: schnellster releasekritischer OpenAI-/Core-Live- und Docker-Pfad
- `stable`: minimum plus stabile Provider-/Backend-Abdeckung für die Release-Freigabe
- `full`: stable plus breite Advisory-Provider-/Media-Abdeckung
- `minimum`: schnellster release-kritischer OpenAI-/Core-Live- und Docker-Pfad
- `stable`: Minimum plus stabile Provider-/Backend-Abdeckung für die Release-Freigabe
- `full`: Stable plus breite beratende Provider-/Medienabdeckung
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die Ziel-Ref
einmal als `release-package-under-test` aufzulösen, und verwendet dieses Artefakt sowohl in
Docker-Checks für den Release-Pfad als auch in Package Acceptance erneut. Dadurch bleiben alle
packagebezogenen Boxen auf denselben Bytes und wiederholte Package-Builds werden vermieden.
Verwenden Sie `run_release_soak=true` mit `stable`, wenn die release-blockierenden Lanes
grün sind und Sie vor der Promotion den erschöpfenden Live-/E2E-, Docker-Release-Pfad- und
All-since-2026.4.23-Upgrade-Survivor-Sweep wünschen. `full` impliziert
`run_release_soak=true`.
`OpenClaw Release Checks` verwendet die vertrauenswürdige Workflow-Ref, um die Ziel-
Ref einmal als `release-package-under-test` aufzulösen, und verwendet dieses Artefakt in Cross-OS,
Package Acceptance und Release-Pfad-Docker-Prüfungen wieder, wenn Soak läuft. Dadurch bleiben
alle paketbezogenen Boxen auf denselben Bytes und wiederholte Paket-Builds werden vermieden.
Der Cross-OS-OpenAI-Install-Smoke verwendet `OPENCLAW_CROSS_OS_OPENAI_MODEL`, wenn die
Repo-/Org-Variable gesetzt ist, andernfalls `openai/gpt-5.4`, weil diese Lane
Package-Installation, Onboarding, Gateway-Start und eine Live-Agent-Runde nachweist,
Paketinstallation, Onboarding, Gateway-Start und eine Live-Agent-Runde nachweist,
statt das langsamste Standardmodell zu benchmarken. Die breitere Live-Provider-
Matrix bleibt der Ort für modellspezifische Abdeckung.
Verwenden Sie diese Varianten je nach Release-Stufe:
Verwenden Sie diese Varianten abhängig von der Release-Stufe:
```bash
# Validate an unpublished release candidate branch.
@ -363,41 +370,44 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
Verwenden Sie den vollständigen Umbrella nicht als ersten Rerun nach einem fokussierten Fix. Wenn eine Box
fehlschlägt, verwenden Sie für den nächsten Nachweis den fehlgeschlagenen Kind-Workflow, Job,
die Docker-Lane, das Package-Profil, den Modell-Provider oder die QA-Lane. Führen Sie den vollständigen Umbrella erst dann
erneut aus, wenn der Fix gemeinsame Release-Orchestrierung geändert oder frühere All-Box-Nachweise
veraltet gemacht hat. Der abschließende Verifier des Umbrella prüft die aufgezeichneten Kind-Workflow-Run-
Verwenden Sie den vollständigen Umbrella nicht als ersten Rerun nach einem gezielten Fix. Wenn eine Box
fehlschlägt, verwenden Sie für den nächsten Nachweis den fehlgeschlagenen Kind-Workflow, Job, die Docker-Lane,
das Paketprofil, den Modell-Provider oder die QA-Lane. Führen Sie den vollständigen Umbrella nur dann erneut aus, wenn
der Fix die gemeinsame Release-Orchestrierung geändert oder frühere All-Box-Nachweise
veraltet gemacht hat. Der abschließende Verifier des Umbrellas prüft die aufgezeichneten Kind-Workflow-Lauf-
IDs erneut. Nachdem ein Kind-Workflow erfolgreich erneut ausgeführt wurde, führen Sie daher nur den fehlgeschlagenen
übergeordneten Job `Verify full validation` erneut aus.
Für begrenzte Wiederherstellung übergeben Sie `rerun_group` an den Umbrella. `all` ist der echte
Release-Candidate-Lauf, `ci` führt nur das normale CI-Kind aus, `plugin-prerelease`
führt nur das releaseexklusive Plugin-Kind aus, `release-checks` führt jede Release-
Box aus, und die engeren Release-Gruppen sind `install-smoke`, `cross-os`,
führt nur das release-spezifische Plugin-Kind aus, `release-checks` führt jede Release-
Box aus, und die schmaleren Release-Gruppen sind `install-smoke`, `cross-os`,
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` und `npm-telegram`.
Fokussierte `npm-telegram`-Reruns erfordern `npm_telegram_package_spec`; full/all-Läufe
mit `release_profile=full` verwenden das Package-Artefakt der Release-Checks.
Gezielte `npm-telegram`-Reruns benötigen `npm_telegram_package_spec`; Full-/All-Läufe
mit `release_profile=full` verwenden das Paketartefakt aus den Release-Prüfungen. Gezielte
Cross-OS-Reruns können `cross_os_suite_filter=windows/packaged-upgrade` oder
einen anderen OS-/Suite-Filter hinzufügen. QA-Release-Check-Fehler sind beratend; ein reiner QA-
Fehler blockiert die Release-Validierung nicht.
### Vitest
Die Vitest-Box ist der manuelle `CI`-Kind-Workflow. Manuelle CI umgeht bewusst
Changed-Scoping und erzwingt den normalen Testgraphen für den Release-
Candidate: Linux-Node-Shards, Bundled-Plugin-Shards, Channel-Contracts, Node-22-
Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Checks, Python-
Die Vitest-Box ist der manuelle Kind-Workflow `CI`. Manuelles CI umgeht
bewusst Changed-Scoping und erzwingt den normalen Testgraphen für den Release
Candidate: Linux-Node-Shards, gebündelte Plugin-Shards, Channel-Verträge, Node-22-
Kompatibilität, `check`, `check-additional`, Build-Smoke, Docs-Prüfungen, Python-
Skills, Windows, macOS, Android und Control-UI-i18n.
Verwenden Sie diese Box, um zu beantworten: „Hat der Source Tree die vollständige normale Testsuite bestanden?“
Das ist nicht dasselbe wie Produktvalidierung für den Release-Pfad. Aufzubewahrende Nachweise:
Sie ist nicht dasselbe wie Produktvalidierung auf dem Release-Pfad. Aufzubewahrende Nachweise:
- `Full Release Validation`-Zusammenfassung mit der URL des dispatchten `CI`-Laufs
- grüner `CI`-Lauf auf der exakten Ziel-SHA
- fehlgeschlagene oder langsame Shard-Namen aus den CI-Jobs bei der Untersuchung von Regressionen
- Zusammenfassung von `Full Release Validation` mit der URL des dispatchten `CI`-Laufs
- grüner `CI`-Lauf auf dem exakten Ziel-SHA
- Namen fehlgeschlagener oder langsamer Shards aus den CI-Jobs bei der Untersuchung von Regressionen
- Vitest-Timing-Artefakte wie `.artifacts/vitest-shard-timings.json`, wenn
ein Lauf Performance-Analyse benötigt
Führen Sie manuelle CI nur dann direkt aus, wenn der Release deterministische normale CI benötigt, aber
nicht die Docker-, QA-Lab-, Live-, Cross-OS- oder Package-Boxen:
Führen Sie manuelles CI nur dann direkt aus, wenn das Release deterministisches normales CI benötigt, aber
nicht die Docker-, QA-Lab-, Live-, Cross-OS- oder Paket-Boxen:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -405,19 +415,19 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Die Docker-Box lebt in `OpenClaw Release Checks` über
`openclaw-live-and-e2e-checks-reusable.yml` plus den Release-Modus-
`install-smoke`-Workflow. Sie validiert den Release-Candidate über paketierte
Docker-Umgebungen statt nur über Tests auf Source-Ebene.
Die Docker-Box liegt in `OpenClaw Release Checks` über
`openclaw-live-and-e2e-checks-reusable.yml` sowie im Release-Modus-
Workflow `install-smoke`. Sie validiert den Release Candidate über paketierte
Docker-Umgebungen statt nur über Source-Level-Tests.
Die Release-Docker-Abdeckung umfasst:
Release-Docker-Abdeckung umfasst:
- vollständiger Install-Smoke mit aktiviertem langsamen globalen Bun-Install-Smoke
- vollständiger Install-Smoke mit aktiviertem langsamem Bun-Global-Install-Smoke
- Vorbereitung/Wiederverwendung des Root-Dockerfile-Smoke-Images nach Ziel-SHA, wobei QR-,
Root-/Gateway- und Installer-/Bun-Smoke-Jobs als separate Install-Smoke-
Shards laufen
- Repository-E2E-Lanes
- Docker-Chunks für den Release-Pfad: `core`, `package-update-openai`,
- Release-Pfad-Docker-Chunks: `core`, `package-update-openai`,
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
`plugins-runtime-services`,
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
@ -425,93 +435,94 @@ Die Release-Docker-Abdeckung umfasst:
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
`plugins-runtime-install-g` und `plugins-runtime-install-h`
- OpenWebUI-Abdeckung innerhalb des Chunks `plugins-runtime-services`, wenn angefordert
- aufgeteilte Lanes für Installation/Deinstallation gebündelter Plugins
- aufgeteilte Install-/Uninstall-Lanes für gebündelte Plugins
`bundled-plugin-install-uninstall-0` bis
`bundled-plugin-install-uninstall-23`
- Live/E2E-Provider-Suiten und Docker-Live-Modellabdeckung, wenn Release-Checks
Live-Suiten enthalten
- Live-/E2E-Provider-Suites und Docker-Live-Modellabdeckung, wenn Release-Prüfungen
Live-Suites enthalten
Verwenden Sie Docker-Artefakte vor einem Rerun. Der Scheduler für den Release-Pfad lädt
Verwenden Sie Docker-Artefakte vor einem Rerun. Der Release-Pfad-Scheduler lädt
`.artifacts/docker-tests/` mit Lane-Logs, `summary.json`, `failures.json`,
Phasen-Timings, Scheduler-Plan-JSON und Rerun-Befehlen hoch. Für fokussierte Wiederherstellung
verwenden Sie `docker_lanes=<lane[,lane]>` im wiederverwendbaren Live/E2E-Workflow statt
alle Release-Chunks erneut auszuführen. Generierte Rerun-Befehle enthalten frühere
`package_artifact_run_id` und vorbereitete Docker-Image-Eingaben, wenn verfügbar, sodass eine
fehlgeschlagene Lane denselben Tarball und dieselben GHCR-Images erneut verwenden kann.
Phasen-Timings, Scheduler-Plan-JSON und Rerun-Befehlen hoch. Für gezielte Wiederherstellung
verwenden Sie `docker_lanes=<lane[,lane]>` im wiederverwendbaren Live-/E2E-Workflow statt
alle Release-Chunks erneut auszuführen. Generierte Rerun-Befehle enthalten vorherige
`package_artifact_run_id`- und vorbereitete Docker-Image-Eingaben, wenn verfügbar, sodass eine
fehlgeschlagene Lane denselben Tarball und dieselben GHCR-Images wiederverwenden kann.
### QA Lab
Die QA-Lab-Box ist ebenfalls Teil von `OpenClaw Release Checks`. Sie ist das agentische
Verhaltens- und Channel-Level-Release-Gate, getrennt von Vitest und Docker-
Package-Mechanik.
Verhaltens- und Channel-Level-Release-Gate, getrennt von Vitest- und Docker-
Paketmechanik.
Die Release-QA-Lab-Abdeckung umfasst:
Release-QA-Lab-Abdeckung umfasst:
- Mock-Parity-Lane, die die OpenAI-Candidate-Lane anhand des agentischen Parity-Packs
mit der Opus-4.6-Baseline vergleicht
- Mock-Paritäts-Lane, die die OpenAI-Candidate-Lane mit der Opus-4.6-
Baseline unter Verwendung des agentischen Paritätspakets vergleicht
- schnelles Live-Matrix-QA-Profil mit der Umgebung `qa-live-shared`
- Live-Telegram-QA-Lane mit Convex-CI-Credential-Leases
- `pnpm qa:otel:smoke`, wenn Release-Telemetrie expliziten lokalen Nachweis benötigt
Verwenden Sie diese Box, um zu beantworten: „Verhält sich der Release in QA-Szenarien und
Live-Channel-Flows korrekt?“ Bewahren Sie die Artefakt-URLs für Parity-, Matrix- und Telegram-
Lanes auf, wenn Sie den Release freigeben. Vollständige Matrix-Abdeckung bleibt als
manueller, geshardeter QA-Lab-Lauf verfügbar statt als standardmäßige releasekritische Lane.
Verwenden Sie diese Box, um zu beantworten: „Verhält sich das Release in QA-Szenarien und
Live-Channel-Flows korrekt?“ Bewahren Sie die Artefakt-URLs für Paritäts-, Matrix- und Telegram-
Lanes auf, wenn Sie das Release freigeben. Vollständige Matrix-Abdeckung bleibt als
manueller geshardeter QA-Lab-Lauf verfügbar und ist nicht die standardmäßige release-kritische Lane.
### Package
### Paket
Die Package-Box ist das Gate für das installierbare Produkt. Sie wird durch
Die Paket-Box ist das Gate für das installierbare Produkt. Sie wird durch
`Package Acceptance` und den Resolver
`scripts/resolve-openclaw-package-candidate.mjs` gestützt. Der Resolver normalisiert einen
Candidate in den `package-under-test`-Tarball, der von Docker-E2E verbraucht wird, validiert
das Package-Inventar, zeichnet Package-Version und SHA-256 auf und hält die
Workflow-Harness-Ref von der Package-Source-Ref getrennt.
Candidate in den `package-under-test`-Tarball, der von Docker E2E verwendet wird, validiert
das Paketinventar, zeichnet Paketversion und SHA-256 auf und hält die
Workflow-Harness-Ref getrennt von der Paket-Source-Ref.
Unterstützte Candidate-Quellen:
- `source=npm`: `openclaw@beta`, `openclaw@latest` oder eine exakte OpenClaw-Release-
Version
- `source=ref`: einen vertrauenswürdigen `package_ref`-Branch, Tag oder vollständigen Commit-SHA
mit dem ausgewählten `workflow_ref`-Harness packen
- `source=url`: ein HTTPS-`.tgz` mit erforderlicher `package_sha256` herunterladen
- `source=artifact`: ein von einem anderen GitHub-Actions-Lauf hochgeladenes `.tgz` wiederverwenden
- `source=ref`: packt einen vertrauenswürdigen `package_ref`-Branch, -Tag oder vollständigen Commit-SHA
mit dem ausgewählten `workflow_ref`-Harness
- `source=url`: lädt eine HTTPS-`.tgz` mit erforderlicher `package_sha256` herunter
- `source=artifact`: verwendet eine von einem anderen GitHub-Actions-Lauf hochgeladene `.tgz` wieder
`OpenClaw Release Checks` führt Package Acceptance mit `source=artifact`, dem
vorbereiteten Release-Package-Artefakt, `suite_profile=custom`,
vorbereiteten Release-Paketartefakt, `suite_profile=custom`,
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
`published_upgrade_survivor_scenarios=reported-issues` und
`telegram_mode=mock-openai` aus. Package Acceptance hält Migration, Update, Bereinigung veralteter
Plugin-Abhängigkeiten, Offline-Plugin-Fixtures, Plugin-Update und Telegram-
Package-QA gegen denselben aufgelösten Tarball. Die Upgrade-Matrix deckt jede stabile npm-veröffentlichte Baseline von `2026.4.23` bis `latest` ab; verwenden Sie
Paket-QA gegen denselben aufgelösten Tarball. Blockierende Release-Prüfungen verwenden die
standardmäßige neueste veröffentlichte Paket-Baseline; `run_release_soak=true` oder
`release_profile=full` erweitert dies auf jede stabile npm-veröffentlichte Baseline von
`2026.4.23` bis `latest` plus Fixtures für gemeldete Issues. Verwenden Sie
Package Acceptance mit `source=npm` für einen bereits ausgelieferten Candidate oder
`source=ref`/`source=artifact` für einen SHA-gestützten lokalen npm-Tarball vor der
Veröffentlichung. Es ist der GitHub-native
Ersatz für den Großteil der Package-/Update-Abdeckung, die zuvor Parallels erforderte.
Cross-OS-Release-Checks bleiben für OS-spezifisches Onboarding,
Installer- und Plattformverhalten wichtig, aber Package-/Update-Produktvalidierung sollte
Ersatz für den Großteil der Paket-/Update-Abdeckung, die zuvor
Parallels erforderte. Cross-OS-Release-Prüfungen bleiben für OS-spezifisches Onboarding,
Installer und Plattformverhalten wichtig, aber Paket-/Update-Produktvalidierung sollte
Package Acceptance bevorzugen.
Die kanonische Checkliste für Update- und Plugin-Validierung ist
[Updates und Plugins testen](/de/help/testing-updates-plugins). Verwenden Sie sie, wenn
Sie entscheiden, welche lokale, Docker-, Package-Acceptance- oder Release-Check-Lane eine
Plugin-Installation/ein Plugin-Update, Doctor-Bereinigung oder eine Published-Package-Migrationsänderung nachweist.
Vollständige veröffentlichte Update-Migration aus jedem stabilen `2026.4.23+`-Package ist
ein separater manueller `Update Migration`-Workflow, nicht Teil der vollständigen Release-CI.
Plugin-Installation/-Aktualisierung, Doctor-Bereinigung oder veröffentlichte Paketmigration nachweist.
Erschöpfende veröffentlichte Update-Migration von jedem stabilen `2026.4.23+`-Paket ist
ein separater manueller `Update Migration`-Workflow, nicht Teil von Full Release CI.
Legacy-Package-Acceptance-Toleranz ist absichtlich zeitlich begrenzt. Packages bis
`2026.4.25` dürfen den Kompatibilitätspfad für Metadatenlücken verwenden, die bereits
auf npm veröffentlicht wurden: private QA-Inventareinträge, die im Tarball fehlen, fehlendes
`gateway install --wrapper`, fehlende Patch-Dateien im aus dem Tarball abgeleiteten Git-
Fixture, fehlende persistierte `update.channel`, Legacy-Speicherorte für Plugin-Install-Records,
fehlende Persistenz von Marketplace-Install-Records und Config-Metadatenmigration während
`plugins update`. Das veröffentlichte Package `2026.4.26` darf für lokale Build-Metadaten-
Stamp-Dateien warnen, die bereits ausgeliefert wurden. Spätere Packages müssen
die modernen Package-Verträge erfüllen; dieselben Lücken lassen die Release-
Legacy-Nachsicht bei Package Acceptance ist bewusst zeitlich begrenzt. Pakete bis
`2026.4.25` dürfen den Kompatibilitätspfad für bereits auf npm veröffentlichte Metadatenlücken nutzen:
private QA-Inventareinträge, die im Tarball fehlen, fehlendes
`gateway install --wrapper`, fehlende Patch-Dateien in der aus dem Tarball abgeleiteten Git-
Fixture, fehlender persistierter `update.channel`, Legacy-Speicherorte für Plugin-Installationsdatensätze,
fehlende Persistenz von Marketplace-Installationsdatensätzen und Konfigurationsmetadaten-
Migration während `plugins update`. Das veröffentlichte Paket `2026.4.26` darf
für lokale Build-Metadatenstempeldateien warnen, die bereits ausgeliefert wurden. Spätere Pakete
müssen die modernen Paketverträge erfüllen; dieselben Lücken lassen die Release-
Validierung fehlschlagen.
Verwenden Sie breitere Package-Acceptance-Profile, wenn die Release-Frage ein
tatsächlich installierbares Package betrifft:
tatsächlich installierbares Paket betrifft:
```bash
gh workflow run package-acceptance.yml \
@ -523,37 +534,37 @@ gh workflow run package-acceptance.yml \
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
```
Gängige Package-Profile:
Gängige Paketprofile:
- `smoke`: schnelle Lanes für Paketinstallation/Kanal/Agent, Gateway-Netzwerk und
erneutes Laden der Konfiguration
- `package`: Installations-/Update-/Plugin-Paketverträge ohne Live-ClawHub; dies ist der
Standard für Release-Checks
- `product`: `package` plus MCP-Kanäle, Cron-/Subagent-Bereinigung, OpenAI-Websuche
- `smoke`: schnelle Lanes für Paketinstallation, Kanal/Agent, Gateway-Netzwerk und
Neuladen der Konfiguration
- `package`: Installations-, Aktualisierungs- und Plugin-Paketverträge ohne Live-ClawHub; dies ist die
Standardeinstellung der Release-Prüfung
- `product`: `package` plus MCP-Kanäle, Bereinigung von Cron/Subagent, OpenAI-Websuche
und OpenWebUI
- `full`: Docker-Release-Pfad-Abschnitte mit OpenWebUI
- `custom`: exakte `docker_lanes`-Liste für fokussierte Wiederholungen
Aktivieren Sie für den Telegram-Nachweis mit Paketkandidat `telegram_mode=mock-openai` oder
Für Telegram-Nachweise zu Paketkandidaten aktivieren Sie `telegram_mode=mock-openai` oder
`telegram_mode=live-frontier` in Package Acceptance. Der Workflow übergibt den
aufgelösten `package-under-test`-Tarball an die Telegram-Lane; der eigenständige
Telegram-Workflow akzeptiert weiterhin eine veröffentlichte npm-Spezifikation für Prüfungen nach der Veröffentlichung.
## Automatisierung der Release-Veröffentlichung
`OpenClaw Release Publish` ist der normale mutierende Einstiegspunkt für Veröffentlichungen. Er
orchestriert die Trusted-Publisher-Workflows in der Reihenfolge, die das Release benötigt:
`OpenClaw Release Publish` ist der normale ändernde Einstiegspunkt für Veröffentlichungen. Er
orchestriert die Trusted-Publisher-Workflows in der für das Release benötigten Reihenfolge:
1. Release-Tag auschecken und dessen Commit-SHA auflösen.
2. Prüfen, ob der Tag von `main` oder `release/*` erreichbar ist.
2. Prüfen, dass das Tag von `main` oder `release/*` aus erreichbar ist.
3. `pnpm plugins:sync:check` ausführen.
4. `Plugin NPM Release` mit `publish_scope=all-publishable` und
`ref=<release-sha>` auslösen.
5. `Plugin ClawHub Release` mit demselben Scope und derselben SHA auslösen.
6. `OpenClaw NPM Release` mit Release-Tag, npm-Dist-Tag und
gespeichertem `preflight_run_id` auslösen.
6. `OpenClaw NPM Release` mit dem Release-Tag, dem npm-Dist-Tag und der
gespeicherten `preflight_run_id` auslösen.
Beispiel für eine Beta-Veröffentlichung:
Beispiel für Beta-Veröffentlichung:
```bash
gh workflow run openclaw-release-publish.yml \
@ -563,7 +574,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Stabile Veröffentlichung mit dem standardmäßigen Beta-Dist-Tag:
Stabile Veröffentlichung auf das standardmäßige Beta-Dist-Tag:
```bash
gh workflow run openclaw-release-publish.yml \
@ -573,7 +584,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Stabile Promotion direkt zu `latest` ist explizit:
Stabile Hochstufung direkt auf `latest` ist explizit:
```bash
gh workflow run openclaw-release-publish.yml \
@ -583,91 +594,94 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=latest
```
Verwenden Sie die niedrigeren Workflows `Plugin NPM Release` und `Plugin ClawHub Release`
nur für fokussierte Reparatur- oder erneute Veröffentlichungsarbeiten. Für eine ausgewählte Plugin-Reparatur übergeben Sie
Verwenden Sie die untergeordneten Workflows `Plugin NPM Release` und `Plugin ClawHub Release`
nur für fokussierte Reparaturen oder erneute Veröffentlichungen. Übergeben Sie für eine ausgewählte Plugin-Reparatur
`plugin_publish_scope=selected` und `plugins=@openclaw/name` an
`OpenClaw Release Publish`, oder lösen Sie den untergeordneten Workflow direkt aus, wenn das
OpenClaw-Paket nicht veröffentlicht werden darf.
## NPM-Workflow-Eingaben
`OpenClaw NPM Release` akzeptiert diese operatorgesteuerten Eingaben:
`OpenClaw NPM Release` akzeptiert diese durch Operatoren gesteuerten Eingaben:
- `tag`: erforderlicher Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder
`v2026.4.2-beta.1`; wenn `preflight_only=true` ist, darf es auch die aktuelle
vollständige 40-stellige Commit-SHA des Workflow-Branches für einen rein validierenden Preflight sein
- `tag`: erforderliches Release-Tag wie `v2026.4.2`, `v2026.4.2-1` oder
`v2026.4.2-beta.1`; wenn `preflight_only=true` gesetzt ist, kann es auch die aktuelle
vollständige 40-stellige Commit-SHA des Workflow-Branches für einen reinen Validierungs-Preflight sein
- `preflight_only`: `true` nur für Validierung/Build/Paket, `false` für den
echten Veröffentlichungspfad
- `preflight_run_id`: im echten Veröffentlichungspfad erforderlich, damit der Workflow
den vorbereiteten Tarball aus dem erfolgreichen Preflight-Lauf wiederverwendet
- `npm_dist_tag`: npm-Ziel-Tag für den Veröffentlichungspfad; standardmäßig `beta`
`OpenClaw Release Publish` akzeptiert diese operatorgesteuerten Eingaben:
`OpenClaw Release Publish` akzeptiert diese durch Operatoren gesteuerten Eingaben:
- `tag`: erforderlicher Release-Tag; muss bereits existieren
- `preflight_run_id`: erfolgreiche `OpenClaw NPM Release`-Preflight-Lauf-ID;
erforderlich, wenn `publish_openclaw_npm=true` ist
- `tag`: erforderliches Release-Tag; muss bereits existieren
- `preflight_run_id`: erfolgreiche `OpenClaw NPM Release`-Preflight-Run-ID;
erforderlich, wenn `publish_openclaw_npm=true`
- `npm_dist_tag`: npm-Ziel-Tag für das OpenClaw-Paket
- `plugin_publish_scope`: standardmäßig `all-publishable`; verwenden Sie `selected` nur
für fokussierte Reparaturarbeiten
- `plugins`: kommagetrennte `@openclaw/*`-Paketnamen, wenn
`plugin_publish_scope=selected`
- `publish_openclaw_npm`: standardmäßig `true`; setzen Sie dies nur auf `false`, wenn Sie den
- `publish_openclaw_npm`: standardmäßig `true`; setzen Sie dies nur dann auf `false`, wenn Sie den
Workflow als reinen Plugin-Reparatur-Orchestrator verwenden
`OpenClaw Release Checks` akzeptiert diese operatorgesteuerten Eingaben:
`OpenClaw Release Checks` akzeptiert diese durch Operatoren gesteuerten Eingaben:
- `ref`: Branch, Tag oder vollständige Commit-SHA, die validiert werden soll. Prüfungen mit Secrets
erfordern, dass der aufgelöste Commit von einem OpenClaw-Branch oder
Release-Tag erreichbar ist.
Release-Tag aus erreichbar ist.
- `run_release_soak`: exhaustive Live/E2E-, Docker-Release-Pfad- und
all-since Upgrade-Survivor-Soak-Prüfungen für stabile/standardmäßige Release-Prüfungen aktivieren. Dies wird
durch `release_profile=full` erzwungen.
Regeln:
- Stabile und Korrektur-Tags dürfen entweder nach `beta` oder `latest` veröffentlichen
- Beta-Prerelease-Tags dürfen nur nach `beta` veröffentlichen
- Stabile Tags und Korrektur-Tags dürfen entweder auf `beta` oder `latest` veröffentlichen
- Beta-Prerelease-Tags dürfen nur auf `beta` veröffentlichen
- Für `OpenClaw NPM Release` ist die Eingabe einer vollständigen Commit-SHA nur erlaubt, wenn
`preflight_only=true` ist
- `OpenClaw Release Checks` und `Full Release Validation` sind immer
nur zur Validierung
- Der echte Veröffentlichungspfad muss denselben `npm_dist_tag` verwenden, der während des Preflights verwendet wurde;
`preflight_only=true`
- `OpenClaw Release Checks` und `Full Release Validation` dienen immer
ausschließlich der Validierung
- Der echte Veröffentlichungspfad muss dasselbe `npm_dist_tag` verwenden, das während des Preflight verwendet wurde;
der Workflow prüft diese Metadaten, bevor die Veröffentlichung fortgesetzt wird
## Stabile npm-Release-Abfolge
## Stabile npm-Release-Sequenz
Beim Schneiden eines stabilen npm-Releases:
Wenn Sie ein stabiles npm-Release schneiden:
1. Führen Sie `OpenClaw NPM Release` mit `preflight_only=true` aus
- Bevor ein Tag existiert, können Sie die aktuelle vollständige Commit-SHA des Workflow-Branches
für einen rein validierenden Trockenlauf des Preflight-Workflows verwenden
2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-zuerst-Ablauf oder `latest` nur,
wenn Sie bewusst eine direkte stabile Veröffentlichung wünschen
für einen reinen Validierungs-Testlauf des Preflight-Workflows verwenden
2. Wählen Sie `npm_dist_tag=beta` für den normalen Beta-zuerst-Ablauf oder `latest` nur dann,
wenn Sie bewusst eine direkte stabile Veröffentlichung möchten
3. Führen Sie `Full Release Validation` auf dem Release-Branch, Release-Tag oder der vollständigen
Commit-SHA aus, wenn Sie normale CI plus Live-Prompt-Cache, Docker, QA Lab,
Matrix und Telegram-Abdeckung aus einem manuellen Workflow wünschen
4. Wenn Sie bewusst nur den deterministischen normalen Testgraphen benötigen, führen Sie stattdessen den
manuellen `CI`-Workflow auf der Release-Referenz aus
manuellen `CI`-Workflow auf der Release-Ref aus
5. Speichern Sie die erfolgreiche `preflight_run_id`
6. Führen Sie `OpenClaw Release Publish` mit demselben `tag`, demselben `npm_dist_tag`
und der gespeicherten `preflight_run_id` aus; dies veröffentlicht externalisierte Plugins in npm
und ClawHub, bevor das OpenClaw-npm-Paket promoted wird
und der gespeicherten `preflight_run_id` aus; er veröffentlicht externalisierte Plugins auf npm
und ClawHub, bevor das OpenClaw-npm-Paket hochgestuft wird
7. Wenn das Release auf `beta` gelandet ist, verwenden Sie den privaten
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`-Workflow,
um diese stabile Version von `beta` nach `latest` zu promoten
8. Wenn das Release bewusst direkt nach `latest` veröffentlicht wurde und `beta`
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`-
Workflow, um diese stabile Version von `beta` auf `latest` hochzustufen
8. Wenn das Release absichtlich direkt auf `latest` veröffentlicht wurde und `beta`
sofort demselben stabilen Build folgen soll, verwenden Sie denselben privaten
Workflow, um beide Dist-Tags auf die stabile Version zu zeigen, oder lassen Sie dessen geplante
Self-Healing-Synchronisierung `beta` später verschieben
Workflow, um beide Dist-Tags auf die stabile Version zeigen zu lassen, oder lassen Sie dessen geplante
selbstheilende Synchronisierung `beta` später verschieben
Die Dist-Tag-Mutation liegt aus Sicherheitsgründen im privaten Repo, weil sie weiterhin
`NPM_TOKEN` erfordert, während das öffentliche Repo nur OIDC-Veröffentlichung beibehält.
Die Dist-Tag-Mutation liegt aus Sicherheitsgründen im privaten Repo, da sie weiterhin
`NPM_TOKEN` erfordert, während das öffentliche Repo ausschließlich OIDC-Veröffentlichungen nutzt.
Dadurch bleiben der direkte Veröffentlichungspfad und der Beta-zuerst-Promotion-Pfad beide
Dadurch bleiben sowohl der direkte Veröffentlichungspfad als auch der Beta-zuerst-Hochstufungspfad
dokumentiert und für Operatoren sichtbar.
Wenn ein Maintainer auf lokale npm-Authentifizierung zurückfallen muss, führen Sie alle 1Password-
CLI-Befehle (`op`) nur innerhalb einer dedizierten tmux-Sitzung aus. Rufen Sie `op` nicht
direkt aus der Haupt-Agent-Shell auf; wenn es in tmux bleibt, sind Prompts,
Warnungen und OTP-Handhabung beobachtbar, und wiederholte Host-Warnungen werden verhindert.
Wenn ein Maintainer auf lokale npm-Authentifizierung zurückgreifen muss, führen Sie alle 1Password-
CLI-(`op`)-Befehle nur innerhalb einer dedizierten tmux-Sitzung aus. Rufen Sie `op` nicht
direkt aus der Haupt-Agent-Shell auf; die Ausführung innerhalb von tmux macht Eingabeaufforderungen,
Warnungen und OTP-Handling beobachtbar und verhindert wiederholte Host-Warnungen.
## Öffentliche Referenzen

194
docs/de/reference/full-release-validation.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Vollständige Release-Validierung ausführen oder erneut ausführen
- Vergleich der stabilen und vollständigen Release-Validierungsprofile
- Fehlerbehebung bei Fehlern in Release-Validierungsstufen
- Vergleich von stabilen und vollständigen Release-Validierungsprofilen
- Fehlersuche bei Fehlern in Release-Validierungsstufen
summary: Phasen der vollständigen Release-Validierung, untergeordnete Workflows, Release-Profile, Handles für erneute Ausführungen und Nachweise
title: Vollständige Release-Validierung
x-i18n:
generated_at: "2026-05-03T21:37:35Z"
generated_at: "2026-05-05T01:48:59Z"
model: gpt-5.5
provider: openai
source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7
source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d
source_path: reference/full-release-validation.md
workflow: 16
---
`Full Release Validation` ist der Release-Rahmen. Er ist der einzige manuelle
Einstiegspunkt für den Pre-Release-Nachweis, aber die meiste Arbeit erfolgt in untergeordneten Workflows, damit eine
fehlgeschlagene Box erneut ausgeführt werden kann, ohne den gesamten Release neu zu starten.
`Full Release Validation` ist der Release-Dachworkflow. Er ist der einzige manuelle
Einstiegspunkt für den Nachweis vor dem Release, aber die meiste Arbeit findet in untergeordneten Workflows statt, sodass eine
fehlgeschlagene Box erneut ausgeführt werden kann, ohne das gesamte Release neu zu starten.
Führen Sie ihn von einer vertrauenswürdigen Workflow-Ref aus, normalerweise `main`, und übergeben Sie den Release-Branch,
Führen Sie ihn von einer vertrauenswürdigen Workflow-Referenz aus, normalerweise `main`, und übergeben Sie den Release-Branch,
das Tag oder die vollständige Commit-SHA als `ref`:
```bash
@ -30,32 +30,36 @@ gh workflow run full-release-validation.yml \
-f release_profile=stable
```
Untergeordnete Workflows verwenden die vertrauenswürdige Workflow-Ref für den Harness und die Eingabe
Untergeordnete Workflows verwenden die vertrauenswürdige Workflow-Referenz für das Harness und die Eingabe
`ref` für den zu testenden Kandidaten. Dadurch bleibt neue Validierungslogik verfügbar,
wenn ein älterer Release-Branch oder ein älteres Tag validiert wird.
Package Acceptance erstellt normalerweise den Kandidaten-Tarball aus der aufgelösten
`ref`, einschließlich vollständiger SHA-Läufe, die mit `pnpm ci:full-release` ausgelöst wurden. Übergeben Sie nach
der Veröffentlichung `package_acceptance_package_spec=openclaw@YYYY.M.D` (oder
`openclaw@beta`/`openclaw@latest`), um stattdessen dieselbe Paket-/Update-Matrix gegen
Standardmäßig führt `release_profile=stable` die release-blockierenden Lanes aus und überspringt
den umfassenden Live-/Docker-Soak. Übergeben Sie `run_release_soak=true`, um die
Soak-Lanes in einen Stable-Lauf einzubeziehen. `release_profile=full` aktiviert Soak-Lanes immer, damit
das breite Advisory-Profil nicht stillschweigend Abdeckung verliert.
Package Acceptance baut normalerweise den Kandidaten-Tarball aus der aufgelösten
`ref`, einschließlich Full-SHA-Läufen, die mit `pnpm ci:full-release` ausgelöst wurden. Nach der
Veröffentlichung übergeben Sie `package_acceptance_package_spec=openclaw@YYYY.M.D` (oder
`openclaw@beta`/`openclaw@latest`), um dieselbe Paket-/Update-Matrix stattdessen gegen
das ausgelieferte npm-Paket auszuführen.
## Übergeordnete Phasen
| Phase | Details |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zielauflösung | **Job:** `Resolve target ref`<br />**Untergeordneter Workflow:** keiner<br />**Weist nach:** löst den Release-Branch, das Tag oder die vollständige Commit-SHA auf und zeichnet die ausgewählten Eingaben auf.<br />**Erneut ausführen:** führen Sie den Rahmen erneut aus, wenn dies fehlschlägt. |
| Vitest und normale CI | **Job:** `Run normal full CI`<br />**Untergeordneter Workflow:** `CI`<br />**Weist nach:** manueller vollständiger CI-Graph gegen die Ziel-Ref, einschließlich Linux-Node-Lanes, gebündelter Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Dokumentationsprüfungen, Python-Skills, Windows, macOS, Control-UI-i18n und Android über den Rahmen.<br />**Erneut ausführen:** `rerun_group=ci`. |
| Plugin-Prerelease | **Job:** `Run plugin prerelease validation`<br />**Untergeordneter Workflow:** `Plugin Prerelease`<br />**Weist nach:** release-spezifische statische Plugin-Prüfungen, agentische Plugin-Abdeckung, vollständige Extension-Batch-Shards und Plugin-Prerelease-Docker-Lanes.<br />**Erneut ausführen:** `rerun_group=plugin-prerelease`. |
| Release-Prüfungen | **Job:** `Run release/live/Docker/QA validation`<br />**Untergeordneter Workflow:** `OpenClaw Release Checks`<br />**Weist nach:** Installations-Smoke, plattformübergreifende Paketprüfungen, Live-/E2E-Suiten, Docker-Release-Path-Chunks, Package Acceptance, QA-Lab-Parität, Live-Matrix und Live-Telegram.<br />**Erneut ausführen:** `rerun_group=release-checks` oder ein enger gefasster Release-Checks-Handle. |
| Paketartefakt | **Job:** `Prepare release package artifact`<br />**Untergeordneter Workflow:** keiner<br />**Weist nach:** erstellt den übergeordneten Tarball `release-package-under-test` früh genug für paketbezogene Prüfungen, die nicht auf `OpenClaw Release Checks` warten müssen.<br />**Erneut ausführen:** führen Sie den Rahmen erneut aus oder geben Sie `npm_telegram_package_spec` für `rerun_group=npm-telegram` an. |
| Paket-Telegram | **Job:** `Run package Telegram E2E`<br />**Untergeordneter Workflow:** `NPM Telegram Beta E2E`<br />**Weist nach:** Telegram-Paketnachweis auf Basis des übergeordneten Artefakts für `rerun_group=all` mit `release_profile=full` oder Telegram-Nachweis für veröffentlichte Pakete, wenn `npm_telegram_package_spec` gesetzt ist.<br />**Erneut ausführen:** `rerun_group=npm-telegram` mit `npm_telegram_package_spec`. |
| Rahmen-Verifier | **Job:** `Verify full validation`<br />**Untergeordneter Workflow:** keiner<br />**Weist nach:** prüft aufgezeichnete Ergebnisse untergeordneter Läufe erneut und hängt Tabellen mit den langsamsten Jobs aus untergeordneten Workflows an.<br />**Erneut ausführen:** führen Sie nur diesen Job erneut aus, nachdem ein fehlgeschlagener untergeordneter Lauf erfolgreich wurde. |
| Phase | Details |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zielauflösung | **Job:** `Resolve target ref`<br />**Untergeordneter Workflow:** keiner<br />**Belegt:** löst den Release-Branch, das Tag oder die vollständige Commit-SHA auf und zeichnet ausgewählte Eingaben auf.<br />**Erneute Ausführung:** Führen Sie den Dachworkflow erneut aus, wenn dies fehlschlägt. |
| Vitest und normale CI | **Job:** `Run normal full CI`<br />**Untergeordneter Workflow:** `CI`<br />**Belegt:** manuellen vollständigen CI-Graphen gegen die Ziel-Referenz, einschließlich Linux-Node-Lanes, gebündelter Plugin-Shards, Channel-Verträge, Node-22-Kompatibilität, `check`, `check-additional`, Build-Smoke, Dokumentationsprüfungen, Python-Skills, Windows, macOS, Control-UI-i18n und Android über den Dachworkflow.<br />**Erneute Ausführung:** `rerun_group=ci`. |
| Plugin-Prerelease | **Job:** `Run plugin prerelease validation`<br />**Untergeordneter Workflow:** `Plugin Prerelease`<br />**Belegt:** release-spezifische statische Plugin-Prüfungen, agentische Plugin-Abdeckung, vollständige Extension-Batch-Shards und Plugin-Prerelease-Docker-Lanes.<br />**Erneute Ausführung:** `rerun_group=plugin-prerelease`. |
| Release-Prüfungen | **Job:** `Run release/live/Docker/QA validation`<br />**Untergeordneter Workflow:** `OpenClaw Release Checks`<br />**Belegt:** Install-Smoke, plattformübergreifende Paketprüfungen, Package Acceptance, QA-Lab-Parität, Live Matrix und Live Telegram. Mit `run_release_soak=true` oder `release_profile=full` werden außerdem umfassende Live-/E2E-Suites und Docker-Release-Pfad-Chunks ausgeführt.<br />**Erneute Ausführung:** `rerun_group=release-checks` oder ein engerer Release-Checks-Handle. |
| Paketartefakt | **Job:** `Prepare release package artifact`<br />**Untergeordneter Workflow:** keiner<br />**Belegt:** erstellt den übergeordneten Tarball `release-package-under-test` früh genug für paketbezogene Prüfungen, die nicht auf `OpenClaw Release Checks` warten müssen.<br />**Erneute Ausführung:** Führen Sie den Dachworkflow erneut aus oder geben Sie `npm_telegram_package_spec` für `rerun_group=npm-telegram` an. |
| Paket Telegram | **Job:** `Run package Telegram E2E`<br />**Untergeordneter Workflow:** `NPM Telegram Beta E2E`<br />**Belegt:** durch ein übergeordnetes Artefakt gestützten Telegram-Paketnachweis für `rerun_group=all` mit `release_profile=full` oder Telegram-Nachweis für veröffentlichte Pakete, wenn `npm_telegram_package_spec` gesetzt ist.<br />**Erneute Ausführung:** `rerun_group=npm-telegram` mit `npm_telegram_package_spec`. |
| Dachworkflow-Verifier | **Job:** `Verify full validation`<br />**Untergeordneter Workflow:** keiner<br />**Belegt:** prüft aufgezeichnete Ergebnisse untergeordneter Läufe erneut und hängt Tabellen der langsamsten Jobs aus untergeordneten Workflows an.<br />**Erneute Ausführung:** Führen Sie nur diesen Job erneut aus, nachdem ein fehlgeschlagener untergeordneter Lauf erfolgreich erneut ausgeführt wurde. |
Für `ref=main` und `rerun_group=all` ersetzt ein neuerer Rahmen einen älteren.
Für `ref=main` und `rerun_group=all` ersetzt ein neuerer Dachworkflow einen älteren.
Wenn der übergeordnete Lauf abgebrochen wird, bricht sein Monitor alle untergeordneten Workflows ab, die er bereits
ausgelöst hat. Validierungsläufe für Release-Branches und Tags brechen sich standardmäßig
nicht gegenseitig ab.
ausgelöst hat. Validierungsläufe für Release-Branches und Tags brechen einander standardmäßig nicht ab.
## Phasen der Release-Prüfungen
@ -63,28 +67,28 @@ nicht gegenseitig ab.
einmal auf und bereitet ein gemeinsames Artefakt `release-package-under-test` vor, wenn paket-
oder Docker-bezogene Phasen es benötigen.
| Phase | Details |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Release-Ziel | **Job:** `Resolve target ref`<br />**Zugrunde liegender Workflow:** keiner<br />**Tests:** ausgewählte Ref, optionale erwartete SHA, Profil, Gruppe für erneutes Ausführen und fokussierter Live-Suite-Filter.<br />**Erneut ausführen:** `rerun_group=release-checks`. |
| Paketartefakt | **Job:** `Prepare release package artifact`<br />**Zugrunde liegender Workflow:** keiner<br />**Tests:** packt oder löst einen Kandidaten-Tarball auf und lädt `release-package-under-test` für nachgelagerte paketbezogene Prüfungen hoch.<br />**Erneut ausführen:** die betroffene Paket-, Cross-OS- oder Live-/E2E-Gruppe. |
| Installations-Smoke | **Job:** `Run install smoke`<br />**Zugrunde liegender Workflow:** `Install Smoke`<br />**Tests:** vollständiger Installationspfad mit Wiederverwendung des Root-Dockerfile-Smoke-Images, QR-Paketinstallation, Root- und Gateway-Docker-Smokes, Installer-Docker-Tests, Bun-Global-Install-Image-Provider-Smoke und schnelles E2E für Installation/Deinstallation gebündelter Plugins.<br />**Erneut ausführen:** `rerun_group=install-smoke`. |
| Cross-OS | **Job:** `cross_os_release_checks`<br />**Zugrunde liegender Workflow:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Tests:** Fresh- und Upgrade-Lanes auf Linux, Windows und macOS für den ausgewählten Provider und Modus, unter Verwendung des Kandidaten-Tarballs plus eines Baseline-Pakets.<br />**Erneut ausführen:** `rerun_group=cross-os`. |
| Repo und Live-E2E | **Job:** `Run repo/live E2E validation`<br />**Zugrunde liegender Workflow:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Tests:** Repository-E2E, Live-Cache, OpenAI-Websocket-Streaming, native Live-Provider- und Plugin-Shards sowie Docker-gestützte Live-Modell-/Backend-/Gateway-Harnesses, die durch `release_profile` ausgewählt werden.<br />**Erneut ausführen:** `rerun_group=live-e2e`, optional mit `live_suite_filter`. |
| Docker-Release-Pfad | **Job:** `Run Docker release-path validation`<br />**Zugrunde liegender Workflow:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Tests:** Docker-Chunks für den Release-Pfad gegen das gemeinsame Paketartefakt.<br />**Erneut ausführen:** `rerun_group=live-e2e`. |
| Package Acceptance | **Job:** `Run package acceptance`<br />**Zugrunde liegender Workflow:** `Package Acceptance`<br />**Tests:** Offline-Plugin-Paket-Fixtures, Plugin-Update, Mock-OpenAI-Telegram-Package-Acceptance und Prüfungen überlebender veröffentlichter Upgrades von jedem stabilen npm-Release ab `2026.4.23` gegen denselben Tarball.<br />**Erneut ausführen:** `rerun_group=package`. |
| QA-Parität | **Job:** `Run QA Lab parity lane` und `Run QA Lab parity report`<br />**Zugrunde liegender Workflow:** direkte Jobs<br />**Tests:** Kandidaten- und Baseline-Pakete für agentische Parität, danach der Paritätsbericht.<br />**Erneut ausführen:** `rerun_group=qa-parity` oder `rerun_group=qa`. |
| QA-Live-Matrix | **Job:** `Run QA Lab live Matrix lane`<br />**Zugrunde liegender Workflow:** direkter Job<br />**Tests:** schnelles Live-Matrix-QA-Profil in der Umgebung `qa-live-shared`.<br />**Erneut ausführen:** `rerun_group=qa-live` oder `rerun_group=qa`. |
| QA-Live-Telegram | **Job:** `Run QA Lab live Telegram lane`<br />**Zugrunde liegender Workflow:** direkter Job<br />**Tests:** Live-Telegram-QA mit Convex-CI-Credential-Leases.<br />**Erneut ausführen:** `rerun_group=qa-live` oder `rerun_group=qa`. |
| Release-Verifier | **Job:** `Verify release checks`<br />**Zugrunde liegender Workflow:** keiner<br />**Tests:** erforderliche Release-Check-Jobs für die ausgewählte Gruppe für erneutes Ausführen.<br />**Erneut ausführen:** erneut ausführen, nachdem fokussierte untergeordnete Jobs erfolgreich sind. |
| Phase | Details |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Release-Ziel | **Job:** `Resolve target ref`<br />**Unterstützender Workflow:** keiner<br />**Tests:** ausgewählte Referenz, optionale erwartete SHA, Profil, Rerun-Gruppe und fokussierter Live-Suite-Filter.<br />**Rerun:** `rerun_group=release-checks`. |
| Paketartefakt | **Job:** `Prepare release package artifact`<br />**Unterstützender Workflow:** keiner<br />**Tests:** packt oder ermittelt einen Kandidaten-Tarball und lädt `release-package-under-test` für nachgelagerte paketbezogene Prüfungen hoch.<br />**Rerun:** die betroffene Paket-, Cross-OS- oder Live/E2E-Gruppe. |
| Installations-Smoke-Test | **Job:** `Run install smoke`<br />**Unterstützender Workflow:** `Install Smoke`<br />**Tests:** vollständiger Installationspfad mit Wiederverwendung des Smoke-Images aus dem Root-Dockerfile, QR-Paketinstallation, Root- und Gateway-Docker-Smokes, Installer-Docker-Tests, Bun-Globalinstallations-Image-Provider-Smoke und schnellem E2E für Installation/Deinstallation gebündelter Plugins.<br />**Rerun:** `rerun_group=install-smoke`. |
| Cross-OS | **Job:** `cross_os_release_checks`<br />**Unterstützender Workflow:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Tests:** Neuinstallations- und Upgrade-Lanes unter Linux, Windows und macOS für den ausgewählten Provider und Modus, mit dem Kandidaten-Tarball plus Baseline-Paket.<br />**Rerun:** `rerun_group=cross-os`. |
| Repo und Live-E2E | **Job:** `Run repo/live E2E validation`<br />**Unterstützender Workflow:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Tests:** Repository-E2E, Live-Cache, OpenAI-WebSocket-Streaming, native Live-Provider- und Plugin-Shards sowie Docker-gestützte Live-Harnesses für Modell/Backend/Gateway, ausgewählt durch `release_profile`.<br />**Läuft bei:** `run_release_soak=true`, `release_profile=full` oder fokussiertem `rerun_group=live-e2e`.<br />**Rerun:** `rerun_group=live-e2e`, optional mit `live_suite_filter`. |
| Docker-Release-Pfad | **Job:** `Run Docker release-path validation`<br />**Unterstützender Workflow:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Tests:** Docker-Abschnitte für den Release-Pfad gegen das gemeinsame Paketartefakt.<br />**Läuft bei:** `run_release_soak=true`, `release_profile=full` oder fokussiertem `rerun_group=live-e2e`.<br />**Rerun:** `rerun_group=live-e2e`. |
| Paketakzeptanz | **Job:** `Run package acceptance`<br />**Unterstützender Workflow:** `Package Acceptance`<br />**Tests:** Offline-Plugin-Paket-Fixtures, Plugin-Update, Mock-OpenAI-Telegram-Paketakzeptanz und Published-Upgrade-Survivor-Prüfungen gegen denselben Tarball. Blockierende Release-Prüfungen verwenden die standardmäßig zuletzt veröffentlichte Baseline; Soak-Prüfungen erweitern dies auf jede stabile npm-Version ab `2026.4.23` sowie Fixtures für gemeldete Issues.<br />**Rerun:** `rerun_group=package`. |
| QA-Parität | **Job:** `Run QA Lab parity lane` und `Run QA Lab parity report`<br />**Unterstützender Workflow:** direkte Jobs<br />**Tests:** Agentic-Paritätspakete für Kandidat und Baseline, anschließend der Paritätsbericht.<br />**Rerun:** `rerun_group=qa-parity` oder `rerun_group=qa`. |
| QA-Live-Matrix | **Job:** `Run QA Lab live Matrix lane`<br />**Unterstützender Workflow:** direkter Job<br />**Tests:** schnelles Live-Matrix-QA-Profil in der Umgebung `qa-live-shared`.<br />**Rerun:** `rerun_group=qa-live` oder `rerun_group=qa`. |
| QA-Live-Telegram | **Job:** `Run QA Lab live Telegram lane`<br />**Unterstützender Workflow:** direkter Job<br />**Tests:** Live-Telegram-QA mit Convex-CI-Anmeldeinformations-Leases.<br />**Rerun:** `rerun_group=qa-live` oder `rerun_group=qa`. |
| Release-Verifizierung | **Job:** `Verify release checks`<br />**Unterstützender Workflow:** keiner<br />**Tests:** erforderliche Release-Prüfjobs für die ausgewählte Rerun-Gruppe.<br />**Rerun:** erneut ausführen, nachdem fokussierte Child-Jobs bestanden haben. |
## Docker-Release-Path-Chunks
## Docker-Release-Pfad-Abschnitte
Die Docker-Release-Path-Phase führt diese Chunks aus, wenn `live_suite_filter`
Die Docker-Release-Pfad-Phase führt diese Abschnitte aus, wenn `live_suite_filter`
leer ist:
| Chunk | Abdeckung |
| Abschnitt | Abdeckung |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `core` | Core-Docker-Release-Path-Smoke-Lanes. |
| `core` | Core-Docker-Smoke-Lanes für den Release-Pfad. |
| `package-update-openai` | Installations- und Update-Verhalten des OpenAI-Pakets. |
| `package-update-anthropic` | Installations- und Update-Verhalten des Anthropic-Pakets. |
| `package-update-core` | Provider-neutrales Paket- und Update-Verhalten. |
@ -92,61 +96,62 @@ leer ist:
| `plugins-runtime-services` | Service-gestützte Plugin-Runtime-Lanes; enthält OpenWebUI, wenn angefordert. |
| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Plugin-Installations-/Runtime-Batches, aufgeteilt für parallele Release-Validierung. |
Verwenden Sie gezielt `docker_lanes=<lane[,lane]>` im wiederverwendbaren Live-/E2E-Workflow, wenn
nur ein Docker-Ausführungspfad fehlgeschlagen ist. Die Release-Artefakte enthalten Wiederholungsbefehle pro Ausführungspfad
mit Eingaben zur Wiederverwendung von Paketartefakten und Images, sofern verfügbar.
Verwenden Sie gezielt `docker_lanes=<lane[,lane]>` im wiederverwendbaren Live/E2E-Workflow, wenn
nur eine Docker-Lane fehlgeschlagen ist. Die Release-Artefakte enthalten pro Lane Rerun-
Befehle mit Paketartefakt- und Image-Wiederverwendungseingaben, sofern verfügbar.
## Release-Profile
`release_profile` steuert hauptsächlich die Live-/Provider-Breite innerhalb der Release-Prüfungen.
Es entfernt nicht die normale vollständige CI, Plugin Prerelease, Install Smoke, Paketakzeptanz,
QA Lab oder Docker-Release-Pfad-Abschnitte. `full` sorgt außerdem dafür, dass der
Umbrella-Lauf Paket-Telegram-E2E gegen das übergeordnete Release-Paketartefakt ausführt, wenn
`rerun_group=all` gesetzt ist, sodass ein vollständiger Kandidat vor der Veröffentlichung diesen
Telegram-Paket-Ausführungspfad nicht stillschweigend überspringt.
`release_profile` steuert hauptsächlich die Breite von Live/Provider innerhalb der Release-Prüfungen.
Es entfernt nicht die normale vollständige CI, Plugin-Prerelease, Installations-Smoke-Tests, Paket-
akzeptanz oder QA Lab. Für `stable` sind ausführliche Repo/Live-E2E- und Docker-
Release-Pfad-Abschnitte Soak-Abdeckung und laufen, wenn `run_release_soak=true`.
`full` erzwingt Soak-Abdeckung und veranlasst außerdem den Umbrella-Lauf, Paket-Telegram-
E2E gegen das übergeordnete Release-Paketartefakt auszuführen, wenn `rerun_group=all`, damit ein vollständiger
Pre-Publish-Kandidat diese Telegram-Paket-Lane nicht stillschweigend überspringt.
| Profil | Vorgesehene Verwendung | Enthaltene Live-/Provider-Abdeckung |
| --------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Schnellster releasekritischer Smoke. | OpenAI-/Core-Live-Pfad, Docker-Live-Modelle für OpenAI, nativer Gateway-Core, natives OpenAI-Gateway-Profil, natives OpenAI-Plugin und Docker-Live-Gateway OpenAI. |
| `stable` | Standardprofil für Release-Freigaben. | `minimum` plus Anthropic-Smoke, Google, MiniMax, Backend, natives Live-Test-Harness, Docker-Live-CLI-Backend, Docker-ACP-Bind, Docker-Codex-Harness und ein OpenCode-Go-Smoke-Shard. |
| `full` | Breiter Beratungssweep. | `stable` plus beratende Provider, Plugin-Live-Shards und Medien-Live-Shards. |
| Profil | Vorgesehene Verwendung | Enthaltene Live/Provider-Abdeckung |
| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Schnellster releasekritischer Smoke-Test. | OpenAI/Core-Live-Pfad, Docker-Live-Modelle für OpenAI, nativer Gateway-Core, natives OpenAI-Gateway-Profil, natives OpenAI-Plugin und Docker-Live-Gateway OpenAI. |
| `stable` | Standardprofil für Release-Freigabe. | `minimum` plus Anthropic-Smoke, Google, MiniMax, Backend, natives Live-Test-Harness, Docker-Live-CLI-Backend, Docker-ACP-Bind, Docker-Codex-Harness und ein OpenCode-Go-Smoke-Shard. |
| `full` | Breite Advisory-Prüfung. | `stable` plus Advisory-Provider, Plugin-Live-Shards und Medien-Live-Shards. |
## Nur in full enthaltene Ergänzungen
## Nur in Full enthaltene Ergänzungen
Diese Suites werden von `stable` übersprungen und von `full` eingeschlossen:
| Bereich | Nur in full enthaltene Abdeckung |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Docker-Live-Modelle | OpenCode Go, OpenRouter, xAI, Z.ai und Fireworks. |
| Docker-Live-Gateway | Beratende Provider, aufgeteilt in DeepSeek/Fireworks-, OpenCode Go/OpenRouter- und xAI/Z.ai-Shards. |
| Bereich | Nur in Full enthaltene Abdeckung |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Docker-Live-Modelle | OpenCode Go, OpenRouter, xAI, Z.ai und Fireworks. |
| Docker-Live-Gateway | Advisory-Provider, aufgeteilt in DeepSeek/Fireworks-, OpenCode Go/OpenRouter- und xAI/Z.ai-Shards. |
| Native Gateway-Provider-Profile | Vollständige Anthropic-Opus- und Sonnet/Haiku-Shards, Fireworks, DeepSeek, vollständige OpenCode-Go-Modell-Shards, OpenRouter, xAI und Z.ai. |
| Native Plugin-Live-Shards | Plugins A-K, L-N, O-Z Sonstige, Moonshot und xAI. |
| Native Medien-Live-Shards | Audio, Google-Musik, MiniMax-Musik und Videogruppen A-D. |
| Native Plugin-Live-Shards | Plugins A-K, L-N, O-Z andere, Moonshot und xAI. |
| Native Medien-Live-Shards | Audio, Google-Musik, MiniMax-Musik und Videogruppen A-D. |
`stable` enthält `native-live-src-gateway-profiles-anthropic-smoke` und
`native-live-src-gateway-profiles-opencode-go-smoke`; `full` verwendet stattdessen die breiteren
Anthropic- und OpenCode-Go-Modell-Shards. Fokussierte Wiederholungen können weiterhin die
aggregierten Handles `native-live-src-gateway-profiles-anthropic` oder
Anthropic- und OpenCode-Go-Modell-Shards. Fokussierte Reruns können weiterhin die aggregierten
Handles `native-live-src-gateway-profiles-anthropic` oder
`native-live-src-gateway-profiles-opencode-go` verwenden.
## Fokussierte Wiederholungen
## Fokussierte Reruns
Verwenden Sie `rerun_group`, um nicht zusammenhängende Release-Boxen nicht erneut auszuführen:
Verwenden Sie `rerun_group`, um das Wiederholen nicht zusammenhängender Release-Boxen zu vermeiden:
| Handle | Umfang |
| ------------------- | --------------------------------------------------------------------- |
| `all` | Alle Stufen von Full Release Validation. |
| `ci` | Nur untergeordnete manuelle vollständige CI. |
| `plugin-prerelease` | Nur untergeordneter Plugin Prerelease. |
| `release-checks` | Alle Stufen von OpenClaw Release Checks. |
| `install-smoke` | Install Smoke über Release-Prüfungen hinweg. |
| `cross-os` | Cross-OS-Release-Prüfungen. |
| `live-e2e` | Repo-/Live-E2E und Docker-Release-Pfad-Validierung. |
| `package` | Package Acceptance. |
| `qa` | QA-Parität plus QA-Live-Ausführungspfade. |
| `qa-parity` | Nur QA-Paritäts-Ausführungspfade und Bericht. |
| `qa-live` | Nur QA-Live-Matrix und Telegram. |
| `npm-telegram` | Telegram-E2E für veröffentlichtes Paket; erfordert `npm_telegram_package_spec`. |
| Handle | Umfang |
| ------------------- | -------------------------------------------------------------------- |
| `all` | Alle Full Release Validation-Stufen. |
| `ci` | Nur manueller vollständiger CI-Child. |
| `plugin-prerelease` | Nur Plugin Prerelease-Child. |
| `release-checks` | Alle OpenClaw Release Checks-Stufen. |
| `install-smoke` | Install Smoke bis zu den Release Checks. |
| `cross-os` | Cross-OS-Release Checks. |
| `live-e2e` | Repo-/Live-E2E- und Docker-Release-Pfad-Validierung. |
| `package` | Package Acceptance. |
| `qa` | QA-Parität plus QA-Live-Lanes. |
| `qa-parity` | Nur QA-Paritäts-Lanes und Bericht. |
| `qa-live` | Nur QA-Live-Matrix und Telegram. |
| `npm-telegram` | Published-Package-Telegram-E2E; erfordert `npm_telegram_package_spec`. |
Verwenden Sie `live_suite_filter` mit `rerun_group=live-e2e`, wenn eine Live-Suite fehlgeschlagen ist.
Gültige Filter-IDs sind im wiederverwendbaren Live-/E2E-Workflow definiert, einschließlich
@ -156,22 +161,33 @@ Gültige Filter-IDs sind im wiederverwendbaren Live-/E2E-Workflow definiert, ein
`live-cli-backend-docker`, `live-acp-bind-docker` und
`live-codex-harness-docker`.
Der Handle `live-gateway-advisory-docker` ist ein aggregierter Wiederholungs-Handle für seine
drei Provider-Shards, daher fächert er weiterhin auf alle beratenden Docker-Gateway-Jobs auf.
Der `live-gateway-advisory-docker`-Handle ist ein aggregierter Rerun-Handle für seine
drei Provider-Shards, daher fächert er weiterhin auf alle Advisory-Docker-Gateway-Jobs auf.
Verwenden Sie `cross_os_suite_filter` mit `rerun_group=cross-os`, wenn eine Cross-OS-Lane
fehlgeschlagen ist. Der Filter akzeptiert eine OS-ID, eine Suite-ID oder ein OS/Suite-Paar, zum
Beispiel `windows/packaged-upgrade`, `windows` oder `packaged-fresh`. Cross-OS-
Zusammenfassungen enthalten phasenbezogene Timings für Packaged-Upgrade-Lanes, und lang laufende
Befehle geben Heartbeat-Zeilen aus, sodass ein hängendes Windows-Update vor dem
Job-Timeout sichtbar ist.
QA-Release-Check-Lanes sind beratend. Ein reiner QA-Fehler wird als Warnung
gemeldet und blockiert den Release-Check-Verifier nicht; führen Sie `rerun_group=qa`,
`qa-parity` oder `qa-live` erneut aus, wenn Sie aktuelle QA-Nachweise benötigen.
## Aufzubewahrende Nachweise
Behalten Sie die Zusammenfassung `Full Release Validation` als releaseweite Übersicht. Sie verlinkt
untergeordnete Lauf-IDs und enthält Tabellen der langsamsten Jobs. Prüfen Sie bei Fehlern zuerst den untergeordneten
Workflow und wiederholen Sie dann den kleinsten passenden Handle oben.
Bewahren Sie die `Full Release Validation`-Zusammenfassung als Release-Ebene-Index auf. Sie verlinkt
Child-Run-IDs und enthält Tabellen der langsamsten Jobs. Prüfen Sie bei Fehlern zuerst den Child-
Workflow und führen Sie dann den kleinsten passenden Handle oben erneut aus.
Nützliche Artefakte:
- `release-package-under-test` aus dem übergeordneten Full-Release-Validation-Lauf und `OpenClaw Release Checks`
- `release-package-under-test` aus dem Full Release Validation-Parent und `OpenClaw Release Checks`
- Docker-Release-Pfad-Artefakte unter `.artifacts/docker-tests/`
- Package-Acceptance-`package-under-test` und Docker-Acceptance-Artefakte
- Package Acceptance `package-under-test` und Docker-Acceptance-Artefakte
- Cross-OS-Release-Check-Artefakte für jedes OS und jede Suite
- QA-Parität-, Matrix- und Telegram-Artefakte
- QA-Paritäts-, Matrix- und Telegram-Artefakte
## Workflow-Dateien

108
docs/de/reference/test.md
View File

@ -1,63 +1,63 @@
---
read_when:
- Tests ausführen oder korrigieren
summary: So führen Sie Tests lokal aus (vitest) und wann Sie Force-/Coverage-Modi verwenden
- Tests ausführen oder beheben
summary: Wie Sie Tests lokal ausführen (vitest) und wann Sie Force-/Coverage-Modi verwenden
title: Tests
x-i18n:
generated_at: "2026-05-02T21:02:41Z"
generated_at: "2026-05-05T01:48:55Z"
model: gpt-5.5
provider: openai
source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f
source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605
source_path: reference/test.md
workflow: 16
---
- Vollständiges Testkit (Test-Suites, Live, Docker): [Tests](/de/help/testing)
- Validierung von Updates und Plugin-Paketen: [Updates und Plugins testen](/de/help/testing-updates-plugins)
- Vollständiges Testkit (Test-Suites, Live-Tests, Docker): [Tests](/de/help/testing)
- Update- und Plugin-Paketvalidierung: [Updates und Plugins testen](/de/help/testing-updates-plugins)
- `pnpm test:force`: Beendet alle verbliebenen Gateway-Prozesse, die den Standard-Control-Port belegen, und führt dann die vollständige Vitest-Suite mit einem isolierten Gateway-Port aus, damit Server-Tests nicht mit einer laufenden Instanz kollidieren. Verwenden Sie dies, wenn ein vorheriger Gateway-Lauf Port 18789 belegt gelassen hat.
- `pnpm test:coverage`: Führt die Unit-Suite mit V8-Coverage aus (über `vitest.unit.config.ts`). Dies ist ein Unit-Coverage-Gate für geladene Dateien, keine All-File-Coverage für das gesamte Repo. Schwellenwerte sind 70 % für Zeilen/Funktionen/Statements und 55 % für Branches. Da `coverage.all` false ist, misst das Gate Dateien, die von der Unit-Coverage-Suite geladen werden, statt jede Split-Lane-Quelldatei als nicht abgedeckt zu behandeln.
- `pnpm test:force`: Beendet jeden verbliebenen Gateway-Prozess, der den standardmäßigen Control-Port belegt, und führt dann die vollständige Vitest-Suite mit einem isolierten Gateway-Port aus, damit Server-Tests nicht mit einer laufenden Instanz kollidieren. Verwenden Sie dies, wenn ein vorheriger Gateway-Lauf Port 18789 belegt zurückgelassen hat.
- `pnpm test:coverage`: Führt die Unit-Suite mit V8-Coverage aus (über `vitest.unit.config.ts`). Dies ist ein Unit-Coverage-Gate für geladene Dateien, keine All-File-Coverage für das gesamte Repository. Die Schwellenwerte sind 70 % für Zeilen/Funktionen/Statements und 55 % für Branches. Da `coverage.all` false ist, misst das Gate Dateien, die von der Unit-Coverage-Suite geladen werden, statt jede Split-Lane-Quelldatei als ungetestet zu behandeln.
- `pnpm test:coverage:changed`: Führt Unit-Coverage nur für Dateien aus, die seit `origin/main` geändert wurden.
- `pnpm test:changed`: günstiger intelligenter Changed-Testlauf. Er führt präzise Ziele aus direkten Teständerungen, benachbarten `*.test.ts`-Dateien, expliziten Source-Mappings und dem lokalen Importgraphen aus. Breite/config/package-Änderungen werden übersprungen, sofern sie nicht präzisen Tests zugeordnet werden.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: expliziter breiter Changed-Testlauf. Verwenden Sie dies, wenn eine Änderung an Test-Harness/config/package auf Vitests breiteres Changed-Test-Verhalten zurückfallen soll.
- `pnpm changed:lanes`: zeigt die architektonischen Lanes, die durch den Diff gegen `origin/main` ausgelöst werden.
- `pnpm check:changed`: führt das intelligente Changed-Check-Gate für den Diff gegen `origin/main` aus. Es führt Typecheck-, Lint- und Guard-Befehle für die betroffenen architektonischen Lanes aus, aber keine Vitest-Tests. Verwenden Sie `pnpm test:changed` oder explizit `pnpm test <target>` für Testnachweise.
- `pnpm test`: leitet explizite Datei-/Verzeichnisziele durch gescopte Vitest-Lanes. Läufe ohne Ziel verwenden feste Shard-Gruppen und expandieren für lokale parallele Ausführung zu Leaf-Configs; die Plugin-Gruppe expandiert immer zu den Shard-Configs pro Plugin statt zu einem riesigen Root-Project-Prozess.
- Test-Wrapper-Läufe enden mit einer kurzen `[test] passed|failed|skipped ... in ...`-Zusammenfassung. Vitests eigene Laufzeitzeile bleibt das Detail pro Shard.
- Gemeinsamer OpenClaw-Testzustand: Verwenden Sie `src/test-utils/openclaw-test-state.ts` aus Vitest, wenn ein Test ein isoliertes `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, Config-Fixture, Workspace, Agent-Verzeichnis oder einen Auth-Profile-Store benötigt.
- Process-E2E-Helper: Verwenden Sie `test/helpers/openclaw-test-instance.ts`, wenn ein Vitest-Prozesslevel-E2E-Test ein laufendes Gateway, CLI-Env, Log-Erfassung und Cleanup an einer Stelle benötigt.
- Docker/Bash-E2E-Helper: Lanes, die `scripts/lib/docker-e2e-image.sh` sourcen, können `docker_e2e_test_state_shell_b64 <label> <scenario>` in den Container übergeben und es mit `scripts/lib/openclaw-e2e-instance.sh` decodieren; Multi-Home-Skripte können `docker_e2e_test_state_function_b64` übergeben und in jedem Flow `openclaw_test_state_create <label> <scenario>` aufrufen. Aufrufer auf niedrigerer Ebene können `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` für ein In-Container-Shell-Snippet verwenden oder `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` für eine per `source` einbindbare Host-Env-Datei. Das `--` vor `create` verhindert, dass neuere Node-Runtimes `--env-file` als Node-Flag behandeln. Docker/Bash-Lanes, die ein Gateway starten, können `scripts/lib/openclaw-e2e-instance.sh` innerhalb des Containers sourcen für Entrypoint-Auflösung, Mock-OpenAI-Start, Gateway-Start im Vordergrund/Hintergrund, Readiness-Probes, State-Env-Export, Log-Dumps und Prozess-Cleanup.
- Full-, Plugin- und Include-Pattern-Shard-Läufe aktualisieren lokale Timing-Daten in `.artifacts/vitest-shard-timings.json`; spätere Whole-Config-Läufe verwenden diese Timings, um langsame und schnelle Shards auszubalancieren. Include-Pattern-CI-Shards hängen den Shard-Namen an den Timing-Schlüssel an, wodurch gefilterte Shard-Timings sichtbar bleiben, ohne Whole-Config-Timing-Daten zu ersetzen. Setzen Sie `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, um das lokale Timing-Artefakt zu ignorieren.
- Ausgewählte `plugin-sdk`- und `commands`-Testdateien werden jetzt durch dedizierte Light-Lanes geleitet, die nur `test/setup.ts` behalten, während runtime-lastige Fälle auf ihren bestehenden Lanes bleiben.
- Quelldateien mit benachbarten Tests werden diesem benachbarten Test zugeordnet, bevor auf breitere Verzeichnis-Globs zurückgefallen wird. Helper-Änderungen unter `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` und `src/plugins/contracts` verwenden einen lokalen Importgraphen, um importierende Tests auszuführen, statt jeden Shard breit auszuführen, wenn der Abhängigkeitspfad präzise ist.
- `auto-reply` wird jetzt außerdem in drei dedizierte Configs aufgeteilt (`core`, `top-level`, `reply`), damit der Reply-Harness die leichteren Top-Level-Status-/Token-/Helper-Tests nicht dominiert.
- Die Basis-Vitest-Config verwendet jetzt standardmäßig `pool: "threads"` und `isolate: false`, wobei der gemeinsame nicht isolierte Runner repo-weit in den Configs aktiviert ist.
- `pnpm test:changed`: günstiger intelligenter Changed-Testlauf. Er führt präzise Ziele aus direkten Teständerungen, benachbarten `*.test.ts`-Dateien, expliziten Source-Mappings und dem lokalen Importgraphen aus. Breite Konfigurations-/Paketänderungen werden übersprungen, sofern sie nicht präzisen Tests zugeordnet werden.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: expliziter breiter Changed-Testlauf. Verwenden Sie ihn, wenn eine Änderung an Test-Harness/Konfiguration/Paket auf das breitere Changed-Test-Verhalten von Vitest zurückfallen soll.
- `pnpm changed:lanes`: zeigt die vom Diff gegen `origin/main` ausgelösten Architektur-Lanes.
- `pnpm check:changed`: führt das intelligente Changed-Check-Gate für den Diff gegen `origin/main` aus. Es führt Typecheck-, Lint- und Guard-Befehle für die betroffenen Architektur-Lanes aus, aber keine Vitest-Tests. Verwenden Sie `pnpm test:changed` oder explizit `pnpm test <target>` als Testnachweis.
- `pnpm test`: leitet explizite Datei-/Verzeichnisziele durch bereichsbezogene Vitest-Lanes. Nicht zielgerichtete Läufe verwenden feste Shard-Gruppen und werden für lokale parallele Ausführung auf Leaf-Konfigurationen erweitert; die Extension-Gruppe wird immer auf die Shard-Konfigurationen pro Extension erweitert, statt als ein riesiger Root-Project-Prozess zu laufen.
- Test-Wrapper-Läufe enden mit einer kurzen Zusammenfassung `[test] passed|failed|skipped ... in ...`. Die eigene Dauerzeile von Vitest bleibt das Detail pro Shard.
- Gemeinsamer OpenClaw-Testzustand: Verwenden Sie `src/test-utils/openclaw-test-state.ts` aus Vitest, wenn ein Test ein isoliertes `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, eine Konfigurations-Fixture, einen Workspace, ein Agent-Verzeichnis oder einen Auth-Profile-Store benötigt.
- Prozess-E2E-Helfer: Verwenden Sie `test/helpers/openclaw-test-instance.ts`, wenn ein Vitest-Prozess-Level-E2E-Test einen laufenden Gateway, CLI-Env, Log-Erfassung und Cleanup an einer Stelle benötigt.
- Docker-/Bash-E2E-Helfer: Lanes, die `scripts/lib/docker-e2e-image.sh` sourcen, können `docker_e2e_test_state_shell_b64 <label> <scenario>` in den Container übergeben und es mit `scripts/lib/openclaw-e2e-instance.sh` dekodieren; Multi-Home-Skripte können `docker_e2e_test_state_function_b64` übergeben und in jedem Flow `openclaw_test_state_create <label> <scenario>` aufrufen. Low-Level-Aufrufer können `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` für ein Shell-Snippet im Container verwenden oder `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` für eine sourcebare Host-Env-Datei. Das `--` vor `create` verhindert, dass neuere Node-Runtimes `--env-file` als Node-Flag behandeln. Docker-/Bash-Lanes, die einen Gateway starten, können `scripts/lib/openclaw-e2e-instance.sh` im Container sourcen für Entrypoint-Auflösung, Mock-OpenAI-Start, Gateway-Start im Vordergrund/Hintergrund, Readiness-Probes, State-Env-Export, Log-Dumps und Prozess-Cleanup.
- Full-, Extension- und Include-Pattern-Shard-Läufe aktualisieren lokale Timing-Daten in `.artifacts/vitest-shard-timings.json`; spätere Whole-Config-Läufe verwenden diese Timings, um langsame und schnelle Shards auszugleichen. Include-Pattern-CI-Shards hängen den Shard-Namen an den Timing-Key an, wodurch gefilterte Shard-Timings sichtbar bleiben, ohne Whole-Config-Timing-Daten zu ersetzen. Setzen Sie `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, um das lokale Timing-Artefakt zu ignorieren.
- Ausgewählte `plugin-sdk`- und `commands`-Testdateien laufen jetzt durch dedizierte Light-Lanes, die nur `test/setup.ts` beibehalten, während runtime-schwere Fälle auf ihren bestehenden Lanes bleiben.
- Quelldateien mit benachbarten Tests werden zuerst diesem benachbarten Test zugeordnet, bevor auf breitere Verzeichnis-Globs zurückgefallen wird. Änderungen an Helfern unter `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` und `src/plugins/contracts` verwenden einen lokalen Importgraphen, um importierende Tests auszuführen, statt jeden Shard breit auszuführen, wenn der Abhängigkeitspfad präzise ist.
- `auto-reply` wird jetzt ebenfalls in drei dedizierte Konfigurationen (`core`, `top-level`, `reply`) aufgeteilt, damit der Reply-Harness die leichteren Top-Level-Status-/Token-/Helper-Tests nicht dominiert.
- Die Basis-Vitest-Konfiguration verwendet jetzt standardmäßig `pool: "threads"` und `isolate: false`, mit dem gemeinsamen nicht isolierten Runner über die Repository-Konfigurationen hinweg aktiviert.
- `pnpm test:channels` führt `vitest.channels.config.ts` aus.
- `pnpm test:extensions` und `pnpm test extensions` führen alle Plugin-Shards aus. Schwere Channel-Plugins, das Browser-Plugin und OpenAI laufen als dedizierte Shards; andere Plugin-Gruppen bleiben gebündelt. Verwenden Sie `pnpm test extensions/<id>` für eine gebündelte Plugin-Lane.
- `pnpm test:perf:imports`: aktiviert Vitest-Berichte zu Importdauer und Importaufschlüsselung, während für explizite Datei-/Verzeichnisziele weiterhin gescoptes Lane-Routing verwendet wird.
- `pnpm test:extensions` und `pnpm test extensions` führen alle Extension-/Plugin-Shards aus. Schwere Channel-Plugins, das Browser-Plugin und OpenAI laufen als dedizierte Shards; andere Plugin-Gruppen bleiben gebündelt. Verwenden Sie `pnpm test extensions/<id>` für eine gebündelte Plugin-Lane.
- `pnpm test:perf:imports`: aktiviert Vitest-Berichte zu Importdauer und Importaufschlüsselung, während für explizite Datei-/Verzeichnisziele weiterhin bereichsbezogenes Lane-Routing verwendet wird.
- `pnpm test:perf:imports:changed`: dasselbe Import-Profiling, aber nur für Dateien, die seit `origin/main` geändert wurden.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarkt den gerouteten Changed-Mode-Pfad gegen den nativen Root-Project-Lauf für denselben committeten Git-Diff.
- `pnpm test:perf:changed:bench -- --worktree` benchmarkt das aktuelle Worktree-Änderungsset, ohne vorher zu committen.
- `pnpm test:perf:profile:main`: schreibt ein CPU-Profil für den Vitest-Hauptthread (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:changed:bench -- --ref <git-ref>` benchmarket den gerouteten Changed-Mode-Pfad gegen den nativen Root-Project-Lauf für denselben committeten Git-Diff.
- `pnpm test:perf:changed:bench -- --worktree` benchmarket das aktuelle Worktree-Changeset, ohne zuerst zu committen.
- `pnpm test:perf:profile:main`: schreibt ein CPU-Profil für den Vitest-Main-Thread (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: schreibt CPU- und Heap-Profile für den Unit-Runner (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: führt jede Full-Suite-Vitest-Leaf-Config seriell aus und schreibt gruppierte Laufzeitdaten plus JSON-/Log-Artefakte pro Config. Der Test Performance Agent verwendet dies als Baseline, bevor er Slow-Test-Fixes versucht.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: vergleicht gruppierte Berichte nach einer performance-fokussierten Änderung.
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: führt jede Full-Suite-Vitest-Leaf-Konfiguration seriell aus und schreibt gruppierte Dauer-Daten sowie JSON-/Log-Artefakte pro Konfiguration. Der Test Performance Agent verwendet dies als Baseline, bevor er versucht, langsame Tests zu beheben.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: vergleicht gruppierte Berichte nach einer performanceorientierten Änderung.
- Gateway-Integration: Opt-in über `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` oder `pnpm test:gateway`.
- `pnpm test:e2e`: Führt Gateway-End-to-End-Smoke-Tests aus (Multi-Instanz-WS/HTTP/Node-Pairing). Standardmäßig `threads` + `isolate: false` mit adaptiven Workern in `vitest.e2e.config.ts`; passen Sie dies mit `OPENCLAW_E2E_WORKERS=<n>` an und setzen Sie `OPENCLAW_E2E_VERBOSE=1` für ausführliche Logs.
- `pnpm test:live`: Führt Provider-Live-Tests aus (minimax/zai). Benötigt API-Schlüssel und `LIVE=1` (oder Provider-spezifisch `*_LIVE_TEST=1`), damit sie nicht übersprungen werden.
- `pnpm test:docker:all`: Baut das gemeinsame Live-Test-Image, packt OpenClaw einmal als npm-Tarball, baut/verwendet ein Bare-Node/Git-Runner-Image plus ein funktionales Image wieder, das diesen Tarball in `/app` installiert, und führt dann Docker-Smoke-Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` über einen gewichteten Scheduler aus. Das Bare-Image (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) wird für Installer-/Update-/Plugin-Abhängigkeits-Lanes verwendet; diese Lanes mounten den vorgebauten Tarball, statt kopierte Repo-Quellen zu verwenden. Das funktionale Image (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) wird für normale Built-App-Funktionalitäts-Lanes verwendet. `scripts/package-openclaw-for-docker.mjs` ist der einzige lokale/CI-Package-Packer und validiert den Tarball plus `dist/postinstall-inventory.json`, bevor Docker ihn nutzt. Docker-Lane-Definitionen liegen in `scripts/lib/docker-e2e-scenarios.mjs`; Planner-Logik liegt in `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` führt den ausgewählten Plan aus. `node scripts/test-docker-all.mjs --plan-json` gibt den Scheduler-eigenen CI-Plan für ausgewählte Lanes, Image-Arten, Package-/Live-Image-Bedarf, State-Szenarien und Credential-Checks aus, ohne Docker zu bauen oder auszuführen. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` steuert Prozess-Slots und ist standardmäßig 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` steuert den Provider-sensitiven Tail-Pool und ist standardmäßig 10. Caps für schwere Lanes sind standardmäßig `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` und `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; Provider-Caps sind standardmäßig eine schwere Lane pro Provider über `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` und `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Verwenden Sie `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` oder `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` für größere Hosts. Wenn eine Lane auf einem Host mit niedriger Parallelität die effektive Gewichts- oder Ressourcengrenze überschreitet, kann sie dennoch aus einem leeren Pool starten und allein laufen, bis sie Kapazität freigibt. Lane-Starts werden standardmäßig um 2 Sekunden gestaffelt, um lokale Docker-Daemon-Create-Stürme zu vermeiden; überschreiben Sie dies mit `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Der Runner führt standardmäßig Docker-Preflights aus, bereinigt veraltete OpenClaw-E2E-Container, gibt alle 30 Sekunden Active-Lane-Status aus, teilt Provider-CLI-Tool-Caches zwischen kompatiblen Lanes, wiederholt transiente Live-Provider-Fehler standardmäßig einmal (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) und speichert Lane-Timings in `.artifacts/docker-tests/lane-timings.json` für Longest-First-Reihenfolge in späteren Läufen. Verwenden Sie `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, um das Lane-Manifest auszugeben, ohne Docker auszuführen, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>`, um die Statusausgabe anzupassen, oder `OPENCLAW_DOCKER_ALL_TIMINGS=0`, um Timing-Wiederverwendung zu deaktivieren. Verwenden Sie `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` nur für deterministische/lokale Lanes oder `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` nur für Live-Provider-Lanes; Package-Aliasse sind `pnpm test:docker:local:all` und `pnpm test:docker:live:all`. Der Live-only-Modus führt Main- und Tail-Live-Lanes zu einem Longest-First-Pool zusammen, damit Provider-Buckets Claude-, Codex- und Gemini-Arbeit gemeinsam packen können. Der Runner plant nach dem ersten Fehler keine neuen gepoolten Lanes mehr, sofern `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` nicht gesetzt ist, und jede Lane hat einen 120-Minuten-Fallback-Timeout, der mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` überschrieben werden kann; ausgewählte Live-/Tail-Lanes verwenden engere Caps pro Lane. CLI-Backend-Docker-Setup-Befehle haben ihr eigenes Timeout über `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (Standard 180). Logs pro Lane, `summary.json`, `failures.json` und Phase-Timings werden unter `.artifacts/docker-tests/<run-id>/` geschrieben; verwenden Sie `pnpm test:docker:timings <summary.json>`, um langsame Lanes zu inspizieren, und `pnpm test:docker:rerun <run-id|summary.json|failures.json>`, um günstige gezielte Rerun-Befehle auszugeben.
- `pnpm test:docker:browser-cdp-snapshot`: Baut einen Chromium-gestützten Source-E2E-Container, startet rohes CDP plus ein isoliertes Gateway, führt `browser doctor --deep` aus und verifiziert, dass CDP-Rollen-Snapshots Link-URLs, cursor-promoted Clickables, iframe-Refs und Frame-Metadaten enthalten.
- CLI-Backend-Live-Docker-Probes können als fokussierte Lanes ausgeführt werden, zum Beispiel `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` oder `pnpm test:docker:live-cli-backend:codex:mcp`. Claude und Gemini haben entsprechende `:resume`- und `:mcp`-Aliasse.
- `pnpm test:docker:openwebui`: Startet dockerisiertes OpenClaw + Open WebUI, meldet sich über Open WebUI an, prüft `/api/models` und führt dann einen echten proxied Chat über `/api/chat/completions` aus. Benötigt einen nutzbaren Live-Modellschlüssel (zum Beispiel OpenAI in `~/.profile`), zieht ein externes Open WebUI-Image und ist nicht erwartungsgemäß CI-stabil wie die normalen Unit-/E2E-Suites.
- `pnpm test:docker:mcp-channels`: Startet einen vorbestückten Gateway-Container und einen zweiten Client-Container, der `openclaw mcp serve` startet, und verifiziert dann geroutete Conversation-Discovery, Transcript-Lesezugriffe, Attachment-Metadaten, Live-Event-Queue-Verhalten, ausgehendes Send-Routing und Claude-artige Channel- und Berechtigungsbenachrichtigungen über die echte stdio-Bridge. Die Claude-Benachrichtigungs-Assertion liest die rohen stdio-MCP-Frames direkt, damit der Smoke widerspiegelt, was die Bridge tatsächlich emittiert.
- `pnpm test:docker:upgrade-survivor`: Installiert den gepackten OpenClaw-Tarball über einem verschmutzten Fixture eines alten Benutzers, führt Paket-Update plus nicht interaktiven Doctor ohne Live-Provider- oder Channel-Schlüssel aus, startet anschließend ein Loopback-Gateway und prüft, dass Agents, Channel-Konfiguration, Plugin-Allowlists, Workspace-/Sitzungsdateien, veralteter Legacy-Plugin-Abhängigkeitsstatus, Startvorgang und RPC-Status erhalten bleiben.
- `pnpm test:docker:published-upgrade-survivor`: Installiert standardmäßig `openclaw@latest`, legt realistische Dateien bestehender Benutzer ohne Live-Provider- oder Channel-Schlüssel an, konfiguriert diese Ausgangsbasis mit einem eingebetteten `openclaw config set`-Befehlsrezept, aktualisiert diese veröffentlichte Installation auf den gepackten OpenClaw-Tarball, führt den nicht interaktiven Doctor aus, schreibt `.artifacts/upgrade-survivor/summary.json`, startet anschließend ein Loopback-Gateway und prüft, dass konfigurierte Intents, Workspace-/Sitzungsdateien, veraltete Plugin-Konfiguration und Legacy-Abhängigkeitsstatus, Startvorgang, `/healthz`, `/readyz` und RPC-Status erhalten bleiben oder sauber repariert werden. Überschreiben Sie eine Ausgangsbasis mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, erweitern Sie eine exakte Matrix mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` wie `all-since-2026.4.23`, oder fügen Sie Szenario-Fixtures mit `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` hinzu; der Satz `reported-issues` enthält `configured-plugin-installs`, um zu prüfen, dass konfigurierte externe OpenClaw-Plugins während des Upgrades automatisch installiert werden. Package Acceptance stellt diese als `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` und `published_upgrade_survivor_scenarios` bereit.
- `pnpm test:docker:update-migration`: Führt den Published-Upgrade-Survivor-Harness im bereinigungsintensiven Szenario `plugin-deps-cleanup` aus und startet standardmäßig bei `openclaw@2026.4.23`. Der separate Workflow `Update Migration` erweitert diese Lane mit `baselines=all-since-2026.4.23`, sodass jedes stabile veröffentlichte Paket ab `.23` auf den Kandidaten aktualisiert wird und die Bereinigung konfigurierter Plugin-Abhängigkeiten außerhalb der Full-Release-CI nachweist.
- `pnpm test:docker:plugins`: Führt Installations-/Update-Smoke-Tests für lokale Pfade, `file:`, npm-Registry-Pakete mit gehobenen Abhängigkeiten, bewegliche Git-Refs, ClawHub-Fixtures, Marketplace-Updates und Aktivierung/Inspektion von Claude-Bundles aus.
- `pnpm test:e2e`: Führt Gateway-End-to-End-Smoke-Tests aus (Multi-Instance-WS/HTTP/Node-Pairing). Standardmäßig `threads` + `isolate: false` mit adaptiven Workern in `vitest.e2e.config.ts`; passen Sie dies mit `OPENCLAW_E2E_WORKERS=<n>` an und setzen Sie `OPENCLAW_E2E_VERBOSE=1` für ausführliche Logs.
- `pnpm test:live`: Führt Provider-Live-Tests aus (minimax/zai). Erfordert API-Schlüssel und `LIVE=1` (oder Provider-spezifisch `*_LIVE_TEST=1`), um sie zu aktivieren.
- `pnpm test:docker:all`: Baut das gemeinsame Live-Test-Image, packt OpenClaw einmal als npm-Tarball, baut/verwendet ein Bare-Node-/Git-Runner-Image sowie ein funktionales Image, das diesen Tarball nach `/app` installiert, und führt dann Docker-Smoke-Lanes mit `OPENCLAW_SKIP_DOCKER_BUILD=1` über einen gewichteten Scheduler aus. Das Bare-Image (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) wird für Installer-/Update-/Plugin-Abhängigkeits-Lanes verwendet; diese Lanes mounten den vorab gebauten Tarball, statt kopierte Repository-Quellen zu verwenden. Das funktionale Image (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) wird für normale Built-App-Funktions-Lanes verwendet. `scripts/package-openclaw-for-docker.mjs` ist der einzige lokale/CI-Package-Packer und validiert den Tarball sowie `dist/postinstall-inventory.json`, bevor Docker ihn verwendet. Docker-Lane-Definitionen liegen in `scripts/lib/docker-e2e-scenarios.mjs`; die Planner-Logik liegt in `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` führt den ausgewählten Plan aus. `node scripts/test-docker-all.mjs --plan-json` gibt den schedulerverwalteten CI-Plan für ausgewählte Lanes, Image-Arten, Paket-/Live-Image-Bedarf, State-Szenarien und Credential-Prüfungen aus, ohne Docker zu bauen oder auszuführen. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` steuert Prozess-Slots und ist standardmäßig 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` steuert den Provider-sensitiven Tail-Pool und ist standardmäßig 10. Caps für schwere Lanes sind standardmäßig `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` und `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; Provider-Caps sind standardmäßig eine schwere Lane pro Provider über `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` und `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Verwenden Sie `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` oder `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` für größere Hosts. Wenn eine Lane auf einem Host mit geringer Parallelität das effektive Gewicht oder Resource-Cap überschreitet, kann sie dennoch aus einem leeren Pool starten und läuft allein, bis sie Kapazität freigibt. Lane-Starts werden standardmäßig um 2 Sekunden gestaffelt, um lokale Create-Stürme des Docker-Daemons zu vermeiden; überschreiben Sie dies mit `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Der Runner führt standardmäßig Docker-Preflights aus, bereinigt veraltete OpenClaw-E2E-Container, gibt alle 30 Sekunden Active-Lane-Status aus, teilt Provider-CLI-Tool-Caches zwischen kompatiblen Lanes, wiederholt transiente Live-Provider-Fehler standardmäßig einmal (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) und speichert Lane-Timings in `.artifacts/docker-tests/lane-timings.json` für Longest-First-Reihenfolge bei späteren Läufen. Verwenden Sie `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, um das Lane-Manifest auszugeben, ohne Docker auszuführen, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>`, um Statusausgaben anzupassen, oder `OPENCLAW_DOCKER_ALL_TIMINGS=0`, um Timing-Wiederverwendung zu deaktivieren. Verwenden Sie `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` nur für deterministische/lokale Lanes oder `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` nur für Live-Provider-Lanes; Paket-Aliase sind `pnpm test:docker:local:all` und `pnpm test:docker:live:all`. Der Live-Only-Modus führt Main- und Tail-Live-Lanes in einem Longest-First-Pool zusammen, damit Provider-Buckets Claude-, Codex- und Gemini-Arbeit gemeinsam packen können. Der Runner stoppt das Scheduling neuer gepoolter Lanes nach dem ersten Fehler, sofern `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` nicht gesetzt ist, und jede Lane hat einen 120-Minuten-Fallback-Timeout, der mit `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` überschrieben werden kann; ausgewählte Live-/Tail-Lanes verwenden engere Caps pro Lane. Docker-Setup-Befehle für das CLI-Backend haben ihren eigenen Timeout über `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (Standard 180). Logs pro Lane, `summary.json`, `failures.json` und Phase-Timings werden unter `.artifacts/docker-tests/<run-id>/` geschrieben; verwenden Sie `pnpm test:docker:timings <summary.json>`, um langsame Lanes zu untersuchen, und `pnpm test:docker:rerun <run-id|summary.json|failures.json>`, um günstige zielgerichtete Rerun-Befehle auszugeben.
- `pnpm test:docker:browser-cdp-snapshot`: Baut einen Chromium-gestützten Source-E2E-Container, startet rohes CDP plus einen isolierten Gateway, führt `browser doctor --deep` aus und verifiziert, dass CDP-Rollen-Snapshots Link-URLs, cursor-promoted Clickables, iframe-Refs und Frame-Metadaten enthalten.
- CLI-Backend-Live-Docker-Probes können als fokussierte Lanes ausgeführt werden, zum Beispiel `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` oder `pnpm test:docker:live-cli-backend:codex:mcp`. Claude und Gemini haben entsprechende Aliase `:resume` und `:mcp`.
- `pnpm test:docker:openwebui`: Startet dockerisiertes OpenClaw + Open WebUI, meldet sich über Open WebUI an, prüft `/api/models` und führt dann einen echten proxied Chat über `/api/chat/completions` aus. Erfordert einen verwendbaren Live-Modellschlüssel (zum Beispiel OpenAI in `~/.profile`), zieht ein externes Open WebUI-Image und ist nicht so CI-stabil zu erwarten wie die normalen Unit-/E2E-Suiten.
- `pnpm test:docker:mcp-channels`: Startet einen vorbefüllten Gateway-Container und einen zweiten Client-Container, der `openclaw mcp serve` spawnt, und verifiziert dann routed Conversation Discovery, Transcript-Lesevorgänge, Attachment-Metadaten, Live-Event-Queue-Verhalten, Outbound-Send-Routing sowie Channel- und Berechtigungsbenachrichtigungen im Claude-Stil über die echte stdio-Bridge. Die Claude-Benachrichtigungs-Assertion liest die rohen stdio-MCP-Frames direkt, damit der Smoke widerspiegelt, was die Bridge tatsächlich ausgibt.
- `pnpm test:docker:upgrade-survivor`: Installiert den gepackten OpenClaw-Tarball über einer veränderten Fixture für alte Benutzer, führt eine Paketaktualisierung sowie den nicht interaktiven Doctor ohne Live-Provider- oder Kanalschlüssel aus, startet anschließend ein Loopback-Gateway und prüft, ob Agenten, Kanalkonfiguration, Plugin-Allowlists, Arbeitsbereichs-/Sitzungsdateien, veralteter Zustand von Legacy-Plugin-Abhängigkeiten, Startvorgang und RPC-Status erhalten bleiben.
- `pnpm test:docker:published-upgrade-survivor`: Installiert standardmäßig `openclaw@latest`, initialisiert realistische Dateien bestehender Benutzer ohne Live-Provider- oder Kanalschlüssel, konfiguriert diese Ausgangsbasis mit einem eingebetteten `openclaw config set`-Befehlsrezept, aktualisiert diese veröffentlichte Installation auf den gepackten OpenClaw-Tarball, führt den nicht interaktiven Doctor aus, schreibt `.artifacts/upgrade-survivor/summary.json`, startet anschließend ein Loopback-Gateway und prüft, ob konfigurierte Intents, Arbeitsbereichs-/Sitzungsdateien, veraltete Plugin-Konfiguration und Legacy-Abhängigkeitszustand, Startvorgang, `/healthz`, `/readyz` und RPC-Status erhalten bleiben oder sauber repariert werden. Überschreiben Sie eine Ausgangsbasis mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, erweitern Sie eine exakte Matrix mit `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` wie `all-since-2026.4.23`, oder fügen Sie Szenario-Fixtures mit `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` hinzu; die Gruppe der gemeldeten Probleme enthält `configured-plugin-installs`, um zu verifizieren, dass konfigurierte externe OpenClaw-Plugins während des Upgrades automatisch installiert werden, sowie `stale-source-plugin-shadow`, um zu verhindern, dass reine Quell-Plugin-Schatten den Startvorgang beschädigen. Package Acceptance stellt diese als `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` und `published_upgrade_survivor_scenarios` bereit.
- `pnpm test:docker:update-migration`: Führt den Harness für veröffentlichte Upgrade-Überlebensprüfungen im bereinigungsintensiven Szenario `plugin-deps-cleanup` aus und startet standardmäßig bei `openclaw@2026.4.23`. Der separate Workflow `Update Migration` erweitert diese Lane mit `baselines=all-since-2026.4.23`, sodass jedes stabile veröffentlichte Paket ab `.23` auf den Kandidaten aktualisiert wird und die Bereinigung konfigurierter Plugin-Abhängigkeiten außerhalb der Full Release CI nachweist.
- `pnpm test:docker:plugins`: Führt Installations-/Aktualisierungs-Smoke-Tests für lokale Pfade, `file:`, npm-Registry-Pakete mit hoisted Abhängigkeiten, bewegliche Git-Refs, ClawHub-Fixtures, Marketplace-Updates sowie Aktivieren/Untersuchen des Claude-Bundles aus.
## Lokales PR-Gate
Führen Sie für lokale PR-Land-/Gate-Prüfungen Folgendes aus:
Für lokale PR-Land-/Gate-Prüfungen führen Sie aus:
- `pnpm check:changed`
- `pnpm check`
@ -66,27 +66,27 @@ Führen Sie für lokale PR-Land-/Gate-Prüfungen Folgendes aus:
- `pnpm test`
- `pnpm check:docs`
Wenn `pnpm test` auf einem ausgelasteten Host flaket, führen Sie es einmal erneut aus, bevor Sie es als Regression behandeln, und isolieren Sie es anschließend mit `pnpm test <path/to/test>`. Verwenden Sie für Hosts mit begrenztem Arbeitsspeicher:
Wenn `pnpm test` auf einem ausgelasteten Host fluktuiert, führen Sie es einmal erneut aus, bevor Sie es als Regression behandeln, und isolieren Sie es anschließend mit `pnpm test <path/to/test>`. Für Hosts mit begrenztem Arbeitsspeicher verwenden Sie:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Model-Latenz-Benchmark (lokale Schlüssel)
## Modelllatenz-Benchmark (lokale Schlüssel)
Skript: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
Verwendung:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Optionale Env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Optionale Umgebungsvariablen: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Standard-Prompt: „Antworten Sie mit einem einzelnen Wort: ok. Keine Satzzeichen oder zusätzlicher Text.“
Letzter Lauf (2025-12-31, 20 Läufe):
- minimax Median 1279ms (Min. 1114, Max. 2431)
- opus Median 2454ms (Min. 1224, Max. 3170)
- minimax Median 1279 ms (Min. 1114, Max. 2431)
- opus Median 2454 ms (Min. 1224, Max. 3170)
## CLI-Startup-Benchmark
## CLI-Start-Benchmark
Skript: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -114,12 +114,12 @@ Voreinstellungen:
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: beide Voreinstellungen
Die Ausgabe enthält `sampleCount`, Durchschnitt, p50, p95, Min./Max., Exit-Code-/Signal-Verteilung und Max-RSS-Zusammenfassungen für jeden Befehl. Optional schreibt `--cpu-prof-dir` / `--heap-prof-dir` V8-Profile pro Lauf, sodass Timing und Profilerfassung denselben Harness verwenden.
Die Ausgabe enthält `sampleCount`, Durchschnitt, p50, p95, Min./Max., Exit-Code-/Signalverteilung und Max-RSS-Zusammenfassungen für jeden Befehl. Optional schreibt `--cpu-prof-dir` / `--heap-prof-dir` V8-Profile pro Lauf, sodass Timing und Profilerfassung denselben Harness verwenden.
Konventionen für gespeicherte Ausgaben:
- `pnpm test:startup:bench:smoke` schreibt das gezielte Smoke-Artefakt nach `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` schreibt das Artefakt der vollständigen Suite mit `runs=5` und `warmup=1` nach `.artifacts/cli-startup-bench-all.json`
- `pnpm test:startup:bench:save` schreibt das Full-Suite-Artefakt nach `.artifacts/cli-startup-bench-all.json` mit `runs=5` und `warmup=1`
- `pnpm test:startup:bench:update` aktualisiert das eingecheckte Baseline-Fixture unter `test/fixtures/cli-startup-bench.json` mit `runs=5` und `warmup=1`
Eingechecktes Fixture:
@ -128,27 +128,27 @@ Eingechecktes Fixture:
- Aktualisieren mit `pnpm test:startup:bench:update`
- Aktuelle Ergebnisse mit `pnpm test:startup:bench:check` gegen das Fixture vergleichen
## Onboarding-E2E (Docker)
## Onboarding E2E (Docker)
Docker ist optional; dies wird nur für containerisierte Onboarding-Smoke-Tests benötigt.
Vollständiger Kaltstart-Ablauf in einem sauberen Linux-Container:
Vollständiger Cold-Start-Flow in einem sauberen Linux-Container:
```bash
scripts/e2e/onboard-docker.sh
```
Dieses Skript steuert den interaktiven Assistenten über ein Pseudo-TTY, prüft Config-/Workspace-/Session-Dateien, startet anschließend das Gateway und führt `openclaw health` aus.
Dieses Skript steuert den interaktiven Wizard über ein Pseudo-TTY, verifiziert Konfigurations-/Workspace-/Sitzungsdateien, startet dann den Gateway und führt `openclaw health` aus.
## QR-Import-Smoke (Docker)
Stellt sicher, dass der gepflegte QR-Runtime-Helper unter den unterstützten Docker-Node-Runtimes geladen wird (Node 24 standardmäßig, Node 22 kompatibel):
Stellt sicher, dass der gepflegte QR-Runtime-Helper unter den unterstützten Docker-Node-Runtimes geladen wird (Node 24 Standard, Node 22 kompatibel):
```bash
pnpm test:docker:qr
```
## Verwandt
## Verwandte Themen
- [Testen](/de/help/testing)
- [Live testen](/de/help/testing-live)

135
docs/de/reference/transcript-hygiene.md
View File

@ -1,46 +1,46 @@
---
read_when:
- Sie untersuchen Ablehnungen von Provider-Anfragen, die mit der Transkriptstruktur zusammenhängen.
- Sie untersuchen Ablehnungen von Provider-Anfragen, die mit der Transkriptstruktur zusammenhängen
- Sie ändern die Transkriptbereinigung oder die Reparaturlogik für Tool-Aufrufe
- Sie untersuchen Abweichungen bei Tool-Aufruf-IDs über Provider hinweg
summary: 'Referenz: Provider-spezifische Regeln für Transkriptbereinigung und Reparatur'
title: Transkript-Hygiene
- Sie untersuchen Unstimmigkeiten bei Tool-Call-IDs zwischen Providern
summary: 'Referenz: Provider-spezifische Regeln zur Transkriptbereinigung und Reparatur'
title: Transkripthygiene
x-i18n:
generated_at: "2026-05-03T06:43:44Z"
generated_at: "2026-05-05T01:49:18Z"
model: gpt-5.5
provider: openai
source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab
source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0
source_path: reference/transcript-hygiene.md
workflow: 16
---
OpenClaw wendet **Provider-spezifische Korrekturen** auf Transkripte an, bevor ein Lauf beginnt (beim Aufbau des Modellkontexts). Die meisten davon sind **In-Memory**-Anpassungen, um strikte Provider-Anforderungen zu erfüllen. Ein separater Reparaturlauf für Session-Dateien kann gespeicherte JSONL-Daten ebenfalls neu schreiben, bevor die Session geladen wird, aber nur bei fehlerhaften Zeilen oder persistierten Turns, die keine gültigen dauerhaften Datensätze sind. Zugestellte Assistentenantworten bleiben auf dem Datenträger erhalten; Provider-spezifisches Entfernen von Assistenten-Prefill geschieht nur beim Erstellen ausgehender Payloads. Wenn eine Reparatur erfolgt, wird die Originaldatei neben der Session-Datei gesichert.
OpenClaw wendet **Provider-spezifische Korrekturen** auf Transkripte an, bevor ein Lauf startet (beim Aufbau des Modellkontexts). Die meisten davon sind **In-Memory**-Anpassungen, um strenge Provider-Anforderungen zu erfüllen. Ein separater Reparaturlauf für Sitzungsdateien kann gespeicherte JSONL-Dateien ebenfalls neu schreiben, bevor die Sitzung geladen wird, jedoch nur bei fehlerhaften Zeilen oder persistierten Nachrichtenwechseln, die keine gültigen dauerhaften Datensätze sind. Ausgelieferte Assistentenantworten bleiben auf dem Datenträger erhalten; Provider-spezifisches Entfernen von Assistant-Prefill erfolgt nur beim Erstellen ausgehender Payloads. Wenn eine Reparatur erfolgt, wird die Originaldatei neben der Sitzungsdatei gesichert.
Der Umfang umfasst:
- Reiner Runtime-Prompt-Kontext bleibt außerhalb der für Benutzer sichtbaren Transkript-Turns
- Bereinigung von Tool-Call-IDs
- Validierung von Tool-Call-Eingaben
- Reparatur der Zuordnung von Tool-Ergebnissen
- Turn-Validierung/Reihenfolge
- Nur zur Laufzeit verwendeter Prompt-Kontext bleibt außerhalb nutzersichtbarer Transkript-Nachrichtenwechsel
- Bereinigung von Tool-Aufruf-IDs
- Validierung von Tool-Aufruf-Eingaben
- Reparatur der Paarung von Tool-Ergebnissen
- Validierung / Reihenfolge von Nachrichtenwechseln
- Bereinigung von Thought-Signaturen
- Bereinigung von Thinking-Signaturen
- Bereinigung von Bild-Payloads
- Bereinigung leerer Textblöcke vor Provider-Replay
- Herkunftsmarkierung von Benutzereingaben (für zwischen Sessions weitergeleitete Prompts)
- Reparatur leerer Assistenten-Fehler-Turns für Bedrock-Converse-Replay
- Bereinigung leerer Textblöcke vor der Provider-Wiedergabe
- Herkunftskennzeichnung von Nutzereingaben (für sitzungsübergreifend weitergeleitete Prompts)
- Reparatur leerer Assistenten-Fehler-Nachrichtenwechsel für Bedrock-Converse-Wiedergabe
Wenn Sie Details zur Transkriptspeicherung benötigen, siehe:
- [Session-Management im Detail](/de/reference/session-management-compaction)
- [Ausführliche Informationen zur Sitzungsverwaltung](/de/reference/session-management-compaction)
---
## Globale Regel: Runtime-Kontext ist kein Benutzertranskript
## Globale Regel: Laufzeitkontext ist kein Nutzertranskript
Runtime-/Systemkontext kann dem Modell-Prompt für einen Turn hinzugefügt werden, ist aber kein vom Endbenutzer verfasster Inhalt. OpenClaw hält einen separaten transkriptbezogenen Prompt-Body für Gateway-Antworten, eingereihte Follow-ups, ACP, CLI und eingebettete Pi-Läufe vor. Gespeicherte sichtbare Benutzer-Turns verwenden diesen Transkript-Body statt des mit Runtime-Kontext angereicherten Prompts.
Laufzeit-/Systemkontext kann dem Modell-Prompt für einen Nachrichtenwechsel hinzugefügt werden, ist aber kein vom Endnutzer verfasster Inhalt. OpenClaw verwaltet einen separaten transkriptbezogenen Prompt-Body für Gateway-Antworten, eingereihte Folgeanfragen, ACP, CLI und eingebettete Pi-Läufe. Gespeicherte sichtbare Nutzer-Nachrichtenwechsel verwenden diesen Transkript-Body anstelle des mit Laufzeitkontext angereicherten Prompts.
Für Legacy-Sessions, die Runtime-Wrapper bereits persistiert haben, wenden Gateway-Verlaufsoberflächen eine Anzeigeprojektion an, bevor Nachrichten an WebChat-, TUI-, REST- oder SSE-Clients zurückgegeben werden.
Für Altsitzungen, die Laufzeit-Wrapper bereits persistiert haben, wenden Gateway-Verlaufsoberflächen eine Anzeigeprojektion an, bevor sie Nachrichten an WebChat-, TUI-, REST- oder SSE-Clients zurückgeben.
---
@ -48,12 +48,12 @@ Für Legacy-Sessions, die Runtime-Wrapper bereits persistiert haben, wenden Gate
Die gesamte Transkript-Hygiene ist im eingebetteten Runner zentralisiert:
- Richtlinienauswahl: `src/agents/transcript-policy.ts`
- Policy-Auswahl: `src/agents/transcript-policy.ts`
- Anwendung von Bereinigung/Reparatur: `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/replay-history.ts`
Die Richtlinie verwendet `provider`, `modelApi` und `modelId`, um zu entscheiden, was angewendet wird.
Die Policy verwendet `provider`, `modelApi` und `modelId`, um zu entscheiden, was angewendet wird.
Getrennt von der Transkript-Hygiene werden Session-Dateien vor dem Laden repariert (falls nötig):
Getrennt von der Transkript-Hygiene werden Sitzungsdateien vor dem Laden repariert (falls nötig):
- `repairSessionFileIfNeeded` in `src/agents/session-file-repair.ts`
- Aufgerufen aus `run/attempt.ts` und `compact.ts` (eingebetteter Runner)
@ -62,22 +62,22 @@ Getrennt von der Transkript-Hygiene werden Session-Dateien vor dem Laden reparie
## Globale Regel: Bildbereinigung
Bild-Payloads werden immer bereinigt, um Provider-seitige Ablehnung aufgrund von Größenbeschränkungen zu verhindern (Herunterskalieren/Neukomprimieren übergroßer Base64-Bilder).
Bild-Payloads werden immer bereinigt, um Provider-seitige Ablehnungen aufgrund von Größenbeschränkungen zu verhindern (Herunterskalieren/Neukomprimieren übergroßer Base64-Bilder).
Dies hilft außerdem, den durch Bilder verursachten Token-Druck für vision-fähige Modelle zu kontrollieren. Kleinere Maximalabmessungen reduzieren im Allgemeinen die Token-Nutzung; größere Abmessungen erhalten Details.
Dies hilft außerdem, den bildbedingten Token-Druck für vision-fähige Modelle zu kontrollieren. Niedrigere maximale Abmessungen reduzieren im Allgemeinen die Token-Nutzung; höhere Abmessungen bewahren Details.
Implementierung:
- `sanitizeSessionMessagesImages` in `src/agents/pi-embedded-helpers/images.ts`
- `sanitizeContentBlocksImages` in `src/agents/tool-images.ts`
- Die maximale Bildseite ist über `agents.defaults.imageMaxDimensionPx` konfigurierbar (Standard: `1200`).
- Leere Textblöcke werden entfernt, während dieser Durchlauf Replay-Inhalte durchläuft. Assistenten-Turns, die dadurch leer werden, werden aus der Replay-Kopie entfernt; Benutzer- und Tool-Ergebnis-Turns, die leer werden, erhalten einen nicht leeren Platzhalter für ausgelassene Inhalte.
- Leere Textblöcke werden entfernt, während dieser Lauf Wiedergabeinhalte durchläuft. Assistenten-Nachrichtenwechsel, die dadurch leer werden, werden aus der Wiedergabekopie entfernt; Nutzer- und Tool-Ergebnis-Nachrichtenwechsel, die dadurch leer werden, erhalten einen nicht leeren Platzhalter für ausgelassenen Inhalt.
---
## Globale Regel: fehlerhafte Tool-Aufrufe
Assistenten-Tool-Call-Blöcke, denen sowohl `input` als auch `arguments` fehlen, werden entfernt, bevor der Modellkontext aufgebaut wird. Dies verhindert Provider-Ablehnungen durch teilweise persistierte Tool-Aufrufe (zum Beispiel nach einem Rate-Limit-Fehler).
Assistenten-Tool-Aufrufblöcke, denen sowohl `input` als auch `arguments` fehlen, werden verworfen, bevor der Modellkontext aufgebaut wird. Dies verhindert Provider-Ablehnungen durch teilweise persistierte Tool-Aufrufe (zum Beispiel nach einem Ratenlimitfehler).
Implementierung:
@ -86,15 +86,15 @@ Implementierung:
---
## Globale Regel: Herkunft von Eingaben zwischen Sessions
## Globale Regel: Herkunft sitzungsübergreifender Eingaben
Wenn ein Agent über `sessions_send` einen Prompt in eine andere Session sendet (einschließlich Antwort-/Ankündigungsschritten von Agent zu Agent), persistiert OpenClaw den erstellten Benutzer-Turn mit:
Wenn ein Agent über `sessions_send` einen Prompt in eine andere Sitzung sendet (einschließlich Agent-zu-Agent-Antwort-/Ankündigungsschritten), persistiert OpenClaw den erstellten Nutzer-Nachrichtenwechsel mit:
- `message.provenance.kind = "inter_session"`
OpenClaw stellt dem weitergeleiteten Prompt-Text außerdem im selben Turn eine Markierung `[Inter-session message ... isUser=false]` voran, damit der aktive Modellaufruf Ausgaben fremder Sessions von externen Endbenutzeranweisungen unterscheiden kann. Diese Markierung enthält, sofern verfügbar, die Quell-Session, den Channel und das Tool. Das Transkript verwendet aus Provider-Kompatibilitätsgründen weiterhin `role: "user"`, aber sowohl der sichtbare Text als auch die Herkunftsmetadaten markieren den Turn als Daten zwischen Sessions.
OpenClaw stellt dem weitergeleiteten Prompt-Text außerdem im selben Nachrichtenwechsel eine Markierung `[Inter-session message ... isUser=false]` voran, damit der aktive Modellaufruf fremde Sitzungsausgabe von externen Endnutzeranweisungen unterscheiden kann. Diese Markierung enthält, sofern verfügbar, Quellsitzung, Kanal und Tool. Das Transkript verwendet aus Provider-Kompatibilitätsgründen weiterhin `role: "user"`, aber sichtbarer Text und Herkunftsmetadaten kennzeichnen den Nachrichtenwechsel beide als sitzungsübergreifende Daten.
Beim Neuaufbau des Kontexts wendet OpenClaw dieselbe Markierung auf ältere persistierte Inter-Session-Benutzer-Turns an, die nur Herkunftsmetadaten haben.
Beim Neuaufbau des Kontexts wendet OpenClaw dieselbe Markierung auf ältere persistierte sitzungsübergreifende Nutzer-Nachrichtenwechsel an, die nur Herkunftsmetadaten haben.
---
@ -103,47 +103,48 @@ Beim Neuaufbau des Kontexts wendet OpenClaw dieselbe Markierung auf ältere pers
**OpenAI / OpenAI Codex**
- Nur Bildbereinigung.
- Verwaiste Reasoning-Signaturen (eigenständige Reasoning-Elemente ohne folgenden Inhaltsblock) für OpenAI-Responses-/Codex-Transkripte entfernen und replay-fähiges OpenAI-Reasoning nach einem Modellroutenwechsel entfernen.
- Replay-fähige Reasoning-Element-Payloads von OpenAI Responses beibehalten, einschließlich verschlüsselter Elemente mit leerer Zusammenfassung, damit manuelles/WebSocket-Replay den erforderlichen `rs_*`-Status mit Assistentenausgabeelementen gekoppelt hält.
- Keine Bereinigung von Tool-Call-IDs.
- Die Reparatur der Tool-Ergebnis-Zuordnung kann echte passende Ausgaben verschieben und Codex-artige `aborted`-Ausgaben für fehlende Tool-Aufrufe synthetisieren.
- Keine Turn-Validierung oder Neuordnung.
- Fehlende Tool-Ausgaben der OpenAI-Responses-Familie werden als `aborted` synthetisiert, passend zur Codex-Replay-Normalisierung.
- Verwaiste Reasoning-Signaturen (eigenständige Reasoning-Elemente ohne folgenden Inhaltsblock) für OpenAI-Responses-/Codex-Transkripte verwerfen und wiedergabefähiges OpenAI-Reasoning nach einem Modellroutenwechsel verwerfen.
- Wiedergabefähige OpenAI-Responses-Reasoning-Element-Payloads einschließlich verschlüsselter Empty-Summary-Elemente beibehalten, damit manuelle/WebSocket-Wiedergabe den erforderlichen `rs_*`-Zustand mit Assistentenausgabe-Elementen gepaart hält.
- Native ChatGPT-Codex-Responses folgt der Codex-Wire-Parität, indem frühere Responses-Reasoning-/Message-/Function-Payloads ohne frühere Element-IDs wiedergegeben werden, während der Sitzungs-`prompt_cache_key` erhalten bleibt.
- Keine Bereinigung von Tool-Aufruf-IDs.
- Die Reparatur der Paarung von Tool-Ergebnissen kann echte zugeordnete Ausgaben verschieben und Codex-artige `aborted`-Ausgaben für fehlende Tool-Aufrufe synthetisieren.
- Keine Validierung oder Neuordnung von Nachrichtenwechseln.
- Fehlende Tool-Ausgaben der OpenAI-Responses-Familie werden als `aborted` synthetisiert, um der Codex-Wiedergabenormalisierung zu entsprechen.
- Kein Entfernen von Thought-Signaturen.
**OpenAI-kompatibles Gemma 4**
- Historische Assistenten-Thinking-/Reasoning-Blöcke werden vor dem Replay entfernt, damit lokale OpenAI-kompatible Gemma-4-Server keine Reasoning-Inhalte aus vorherigen Turns erhalten.
- Aktuelle Tool-Call-Fortsetzungen im selben Turn behalten den Assistenten-Reasoning-Block am Tool-Aufruf, bis das Tool-Ergebnis erneut abgespielt wurde.
- Historische Assistenten-Thinking-/Reasoning-Blöcke werden vor der Wiedergabe entfernt, damit lokale OpenAI-kompatible Gemma-4-Server keine Reasoning-Inhalte aus früheren Nachrichtenwechseln erhalten.
- Aktuelle Tool-Aufruf-Fortsetzungen im selben Nachrichtenwechsel behalten den Assistenten-Reasoning-Block am Tool-Aufruf angehängt, bis das Tool-Ergebnis wiedergegeben wurde.
**Google (Generative AI / Gemini CLI / Antigravity)**
- Bereinigung von Tool-Call-IDs: strikt alphanumerisch.
- Reparatur der Tool-Ergebnis-Zuordnung und synthetische Tool-Ergebnisse.
- Turn-Validierung (Turn-Wechsel im Gemini-Stil).
- Korrektur der Google-Turn-Reihenfolge (kleines Benutzer-Bootstrap voranstellen, wenn der Verlauf mit dem Assistenten beginnt).
- Antigravity Claude: Thinking-Signaturen normalisieren; unsignierte Thinking-Blöcke entfernen.
- Bereinigung von Tool-Aufruf-IDs: strikt alphanumerisch.
- Reparatur der Paarung von Tool-Ergebnissen und synthetische Tool-Ergebnisse.
- Validierung von Nachrichtenwechseln (Gemini-artige Alternation der Nachrichtenwechsel).
- Korrektur der Google-Nachrichtenwechsel-Reihenfolge (einen winzigen Nutzer-Bootstrap voranstellen, wenn der Verlauf mit dem Assistenten beginnt).
- Antigravity Claude: Thinking-Signaturen normalisieren; unsignierte Thinking-Blöcke verwerfen.
**Anthropic / Minimax (Anthropic-kompatibel)**
- Reparatur der Tool-Ergebnis-Zuordnung und synthetische Tool-Ergebnisse.
- Turn-Validierung (aufeinanderfolgende Benutzer-Turns zusammenführen, um strikte Alternation zu erfüllen).
- Nachfolgende Assistenten-Prefill-Turns werden aus ausgehenden Anthropic-Messages-Payloads entfernt, wenn Thinking aktiviert ist, einschließlich Cloudflare-AI-Gateway-Routen.
- Thinking-Blöcke mit fehlenden, leeren oder nur aus Leerraum bestehenden Replay-Signaturen werden vor der Provider-Konvertierung entfernt. Wenn dadurch ein Assistenten-Turn leer wird, behält OpenClaw die Turn-Form mit nicht leerem Text für ausgelassenes Reasoning bei.
- Ältere reine Thinking-Assistenten-Turns, die entfernt werden müssen, werden durch nicht leeren Text für ausgelassenes Reasoning ersetzt, damit Provider-Adapter den Replay-Turn nicht verwerfen.
- Reparatur der Paarung von Tool-Ergebnissen und synthetische Tool-Ergebnisse.
- Validierung von Nachrichtenwechseln (aufeinanderfolgende Nutzer-Nachrichtenwechsel zusammenführen, um strikte Alternation zu erfüllen).
- Abschließende Assistant-Prefill-Nachrichtenwechsel werden aus ausgehenden Anthropic-Messages-Payloads entfernt, wenn Thinking aktiviert ist, einschließlich Cloudflare-AI-Gateway-Routen.
- Thinking-Blöcke mit fehlenden, leeren oder nur aus Leerzeichen bestehenden Wiedergabe-Signaturen werden vor der Provider-Konvertierung entfernt. Wenn dadurch ein Assistenten-Nachrichtenwechsel leer wird, behält OpenClaw die Form des Nachrichtenwechsels mit nicht leerem Text für ausgelassenes Reasoning bei.
- Ältere reine Thinking-Assistenten-Nachrichtenwechsel, die entfernt werden müssen, werden durch nicht leeren Text für ausgelassenes Reasoning ersetzt, damit Provider-Adapter den Wiedergabe-Nachrichtenwechsel nicht verwerfen.
**Amazon Bedrock (Converse API)**
- Leere Assistenten-Stream-Error-Turns werden vor dem Replay zu einem nicht leeren Fallback-Textblock repariert. Bedrock Converse lehnt Assistentennachrichten mit `content: []` ab; daher werden persistierte Assistenten-Turns mit `stopReason: "error"` und leerem Inhalt vor dem Laden auch auf dem Datenträger repariert.
- Assistenten-Stream-Error-Turns, die nur leere Textblöcke enthalten, werden aus der In-Memory-Replay-Kopie entfernt, statt einen ungültigen leeren Block erneut abzuspielen.
- Claude-Thinking-Blöcke mit fehlenden, leeren oder nur aus Leerraum bestehenden Replay-Signaturen werden vor dem Converse-Replay entfernt. Wenn dadurch ein Assistenten-Turn leer wird, behält OpenClaw die Turn-Form mit nicht leerem Text für ausgelassenes Reasoning bei.
- Ältere reine Thinking-Assistenten-Turns, die entfernt werden müssen, werden durch nicht leeren Text für ausgelassenes Reasoning ersetzt, damit das Converse-Replay die strikte Turn-Form beibehält.
- Replay filtert Delivery-Mirror- und Gateway-injizierte Assistenten-Turns von OpenClaw.
- Bildbereinigung erfolgt über die globale Regel.
- Leere Assistenten-Stream-Fehler-Nachrichtenwechsel werden vor der Wiedergabe in einen nicht leeren Fallback-Textblock repariert. Bedrock Converse lehnt Assistentennachrichten mit `content: []` ab, daher werden persistierte Assistenten-Nachrichtenwechsel mit `stopReason: "error"` und leerem Inhalt vor dem Laden auch auf dem Datenträger repariert.
- Assistenten-Stream-Fehler-Nachrichtenwechsel, die nur leere Textblöcke enthalten, werden aus der In-Memory-Wiedergabekopie entfernt, statt einen ungültigen leeren Block wiederzugeben.
- Claude-Thinking-Blöcke mit fehlenden, leeren oder nur aus Leerzeichen bestehenden Wiedergabe-Signaturen werden vor der Converse-Wiedergabe entfernt. Wenn dadurch ein Assistenten-Nachrichtenwechsel leer wird, behält OpenClaw die Form des Nachrichtenwechsels mit nicht leerem Text für ausgelassenes Reasoning bei.
- Ältere reine Thinking-Assistenten-Nachrichtenwechsel, die entfernt werden müssen, werden durch nicht leeren Text für ausgelassenes Reasoning ersetzt, damit die Converse-Wiedergabe die strikte Form der Nachrichtenwechsel beibehält.
- Die Wiedergabe filtert OpenClaw-Auslieferungsspiegel- und Gateway-injizierte Assistenten-Nachrichtenwechsel.
- Bildbereinigung wird über die globale Regel angewendet.
**Mistral (einschließlich modell-ID-basierter Erkennung)**
- Bereinigung von Tool-Call-IDs: strict9 (alphanumerisch, Länge 9).
- Bereinigung von Tool-Aufruf-IDs: strict9 (alphanumerisch, Länge 9).
**OpenRouter Gemini**
@ -151,9 +152,9 @@ Beim Neuaufbau des Kontexts wendet OpenClaw dieselbe Markierung auf ältere pers
**OpenRouter Anthropic**
- Nachfolgende Assistenten-Prefill-Turns werden aus verifizierten OpenRouter-OpenAI-kompatiblen Anthropic-Modell-Payloads entfernt, wenn Reasoning aktiviert ist, passend zum Replay-Verhalten von direktem Anthropic und Cloudflare Anthropic.
- Abschließende Assistant-Prefill-Nachrichtenwechsel werden aus verifizierten OpenRouter-OpenAI-kompatiblen Anthropic-Modell-Payloads entfernt, wenn Reasoning aktiviert ist, entsprechend dem Wiedergabeverhalten von direktem Anthropic und Cloudflare Anthropic.
**Alles andere**
**Alles Weitere**
- Nur Bildbereinigung.
@ -161,20 +162,20 @@ Beim Neuaufbau des Kontexts wendet OpenClaw dieselbe Markierung auf ältere pers
## Historisches Verhalten (vor 2026.1.22)
Vor dem Release 2026.1.22 wendete OpenClaw mehrere Schichten der Transkript-Hygiene an:
Vor dem Release 2026.1.22 wendete OpenClaw mehrere Ebenen der Transkript-Hygiene an:
- Eine **transcript-sanitize-Erweiterung** lief bei jedem Kontextaufbau und konnte:
- Tool-Use-/Ergebnis-Zuordnung reparieren.
- Tool-Call-IDs bereinigen (einschließlich eines nicht strikten Modus, der `_`/`-` beibehielt).
- Der Runner führte außerdem Provider-spezifische Bereinigung durch, wodurch Arbeit dupliziert wurde.
- Zusätzliche Mutationen erfolgten außerhalb der Provider-Richtlinie, darunter:
- Eine **Transcript-Sanitize-Erweiterung** lief bei jedem Kontextaufbau und konnte:
- Tool-Nutzung-/Ergebnis-Paarung reparieren.
- Tool-Aufruf-IDs bereinigen (einschließlich eines nicht strikten Modus, der `_`/`-` beibehielt).
- Der Runner führte außerdem Provider-spezifische Bereinigung aus, was Arbeit duplizierte.
- Zusätzliche Mutationen erfolgten außerhalb der Provider-Policy, darunter:
- Entfernen von `<final>`-Tags aus Assistententext vor der Persistierung.
- Entfernen leerer Assistenten-Fehler-Turns.
- Verwerfen leerer Assistenten-Fehler-Nachrichtenwechsel.
- Kürzen von Assistenteninhalten nach Tool-Aufrufen.
Diese Komplexität verursachte providerübergreifende Regressionen (insbesondere bei der `call_id|fc_id`-Zuordnung von `openai-responses`). Die Bereinigung in 2026.1.22 entfernte die Erweiterung, zentralisierte die Logik im Runner und machte OpenAI jenseits der Bildbereinigung **no-touch**.
Diese Komplexität verursachte providerübergreifende Regressionen (insbesondere bei der `openai-responses`-Paarung von `call_id|fc_id`). Die Bereinigung in 2026.1.22 entfernte die Erweiterung, zentralisierte die Logik im Runner und machte OpenAI über die Bildbereinigung hinaus **unangetastet**.
## Verwandt
- [Session-Management](/de/concepts/session)
- [Session-Pruning](/de/concepts/session-pruning)
- [Sitzungsverwaltung](/de/concepts/session)
- [Sitzungsbereinigung](/de/concepts/session-pruning)

105
docs/de/security/network-proxy.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Sie möchten mehrschichtigen Schutz gegen SSRF- und DNS-Rebinding-Angriffe
- Externen Forward-Proxy für OpenClaw-Runtime-Datenverkehr konfigurieren
summary: So leiten Sie den HTTP- und WebSocket-Datenverkehr der OpenClaw-Laufzeit über einen vom Betreiber verwalteten Filter-Proxy
- Sie möchten mehrschichtige Schutzmaßnahmen gegen SSRF- und DNS-Rebinding-Angriffe
- Externen Forward-Proxy für OpenClaw-Laufzeitdatenverkehr konfigurieren
summary: So leiten Sie HTTP- und WebSocket-Traffic der OpenClaw-Runtime über einen vom Betreiber verwalteten Filter-Proxy
title: Netzwerk-Proxy
x-i18n:
generated_at: "2026-05-04T18:24:31Z"
generated_at: "2026-05-05T01:49:19Z"
model: gpt-5.5
provider: openai
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
source_path: security/network-proxy.md
workflow: 16
---
# Netzwerk-Proxy
OpenClaw kann HTTP- und WebSocket-Datenverkehr zur Laufzeit über einen vom Betreiber verwalteten Forward-Proxy leiten. Dies ist eine optionale mehrschichtige Schutzmaßnahme für Bereitstellungen, die zentrale Egress-Kontrolle, stärkeren SSRF-Schutz und bessere Überprüfbarkeit des Netzwerks wünschen.
OpenClaw kann Laufzeit-HTTP- und WebSocket-Datenverkehr über einen vom Betreiber verwalteten Forward-Proxy leiten. Dies ist eine optionale Defense-in-Depth-Maßnahme für Bereitstellungen, die zentrale Egress-Kontrolle, stärkeren SSRF-Schutz und bessere Netzwerkprüfbarkeit wünschen.
OpenClaw liefert keinen Proxy mit, lädt keinen Proxy herunter, startet, konfiguriert oder zertifiziert keinen Proxy. Sie betreiben die Proxy-Technologie, die zu Ihrer Umgebung passt, und OpenClaw leitet normale prozesslokale HTTP- und WebSocket-Clients darüber.
OpenClaw liefert keinen Proxy aus, lädt keinen Proxy herunter, startet, konfiguriert oder zertifiziert keinen Proxy. Sie betreiben die Proxy-Technologie, die zu Ihrer Umgebung passt, und OpenClaw leitet normale prozesslokale HTTP- und WebSocket-Clients darüber.
## Warum einen Proxy verwenden?
Ein Proxy gibt Betreibern einen zentralen Netzwerk-Kontrollpunkt für ausgehenden HTTP- und WebSocket-Datenverkehr. Das kann auch außerhalb der SSRF-Härtung nützlich sein:
Ein Proxy bietet Betreibern einen zentralen Netzwerk-Kontrollpunkt für ausgehenden HTTP- und WebSocket-Datenverkehr. Das kann auch außerhalb von SSRF-Härtung nützlich sein:
- Zentrale Richtlinie: Pflegen Sie eine Egress-Richtlinie, statt sich darauf zu verlassen, dass jede HTTP-Aufrufstelle der Anwendung die Netzwerkregeln korrekt umsetzt.
- Prüfungen zur Verbindungszeit: Bewerten Sie das Ziel nach der DNS-Auflösung und unmittelbar bevor der Proxy die Upstream-Verbindung öffnet.
- Schutz vor DNS-Rebinding: Reduzieren Sie die Lücke zwischen einer DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung.
- Prüfungen beim Verbindungsaufbau: Bewerten Sie das Ziel nach der DNS-Auflösung und unmittelbar bevor der Proxy die Upstream-Verbindung öffnet.
- Schutz vor DNS-Rebinding: Verringern Sie die Lücke zwischen einer DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung.
- Breitere JavaScript-Abdeckung: Leiten Sie gewöhnliche `fetch`-, `node:http`-, `node:https`-, WebSocket-, axios-, got-, node-fetch- und ähnliche Clients über denselben Pfad.
- Überprüfbarkeit: Protokollieren Sie erlaubte und verweigerte Ziele an der Egress-Grenze.
- Betriebliche Kontrolle: Erzwingen Sie Zielregeln, Netzwerksegmentierung, Ratenlimits oder ausgehende Allowlists, ohne OpenClaw neu zu bauen.
- Prüfbarkeit: Protokollieren Sie erlaubte und abgelehnte Ziele an der Egress-Grenze.
- Betriebliche Kontrolle: Erzwingen Sie Zielregeln, Netzwerksegmentierung, Ratenbegrenzungen oder ausgehende Allowlists, ohne OpenClaw neu zu bauen.
Proxy-Routing ist eine Guardrail auf Prozessebene für normalen HTTP- und WebSocket-Egress. Es gibt Betreibern einen Fail-Closed-Pfad, um unterstützte JavaScript-HTTP-Clients über ihren eigenen filternden Proxy zu leiten, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene und bedeutet nicht, dass OpenClaw die Zielrichtlinie des Proxys zertifiziert.
Proxy-Routing ist eine Schutzleitplanke auf Prozessebene für normalen HTTP- und WebSocket-Egress. Es gibt Betreibern einen Fail-Closed-Pfad, um unterstützte JavaScript-HTTP-Clients über ihren eigenen filternden Proxy zu leiten, ist aber keine Netzwerksandbox auf Betriebssystemebene und bedeutet nicht, dass OpenClaw die Zielrichtlinie des Proxys zertifiziert.
## Wie OpenClaw Datenverkehr leitet
Wenn `proxy.enabled=true` ist und eine Proxy-URL konfiguriert wurde, leiten geschützte Laufzeitprozesse wie `openclaw gateway run`, `openclaw node run` und `openclaw agent --local` normalen HTTP- und WebSocket-Egress über den konfigurierten Proxy:
Wenn `proxy.enabled=true` und eine Proxy-URL konfiguriert ist, leiten geschützte Laufzeitprozesse wie `openclaw gateway run`, `openclaw node run` und `openclaw agent --local` normalen HTTP- und WebSocket-Egress über den konfigurierten Proxy:
```text
OpenClaw process
@ -43,27 +43,28 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
Der öffentliche Vertrag ist das Routing-Verhalten, nicht die internen Node-Hooks, mit denen es implementiert wird. OpenClaw Gateway-Control-Plane-WebSocket-Clients verwenden einen schmalen direkten Pfad für lokalen Gateway-RPC-Datenverkehr über local loopback, wenn die Gateway-URL `localhost` oder eine wörtliche Loopback-IP wie `127.0.0.1` oder `[::1]` verwendet. Dieser Control-Plane-Pfad muss Loopback-Gateways erreichen können, selbst wenn der Betreiber-Proxy Loopback-Ziele blockiert. Normale HTTP- und WebSocket-Anfragen zur Laufzeit verwenden weiterhin den konfigurierten Proxy.
Der öffentliche Vertrag ist das Routing-Verhalten, nicht die internen Node-Hooks, mit denen es implementiert wird. OpenClaw-Gateway-Control-Plane-WebSocket-Clients verwenden einen schmalen direkten Pfad für local loopback-Gateway-RPC-Datenverkehr, wenn die Gateway-URL `localhost` oder eine literale Loopback-IP wie `127.0.0.1` oder `[::1]` verwendet. Dieser Control-Plane-Pfad muss Loopback-Gateways erreichen können, auch wenn der Betreiber-Proxy Loopback-Ziele blockiert. Normale Laufzeit-HTTP- und WebSocket-Anfragen verwenden weiterhin den konfigurierten Proxy.
Intern verwendet OpenClaw für diese Funktion zwei Routing-Hooks auf Prozessebene:
- Undici-Dispatcher-Routing deckt `fetch`, Undici-basierte Clients und Transports ab, die ihren eigenen Undici-Dispatcher bereitstellen.
- Undici-Dispatcher-Routing deckt `fetch`, Undici-basierte Clients und Transporte ab, die ihren eigenen Undici-Dispatcher bereitstellen.
- `global-agent`-Routing deckt Node-Core-Aufrufer von `node:http` und `node:https` ab, einschließlich vieler Bibliotheken, die auf `http.request`, `https.request`, `http.get` und `https.get` aufbauen. Der verwaltete Proxy-Modus erzwingt diesen globalen Agent, damit explizite Node-HTTP-Agents den Betreiber-Proxy nicht versehentlich umgehen.
Einige Plugins besitzen eigene Transports, die eine explizite Proxy-Verdrahtung benötigen, auch wenn Routing auf Prozessebene vorhanden ist. Beispielsweise verwendet der Bot-API-Transport von Telegram seinen eigenen HTTP/1-Undici-Dispatcher und berücksichtigt deshalb die Prozess-Proxy-Umgebung plus den verwalteten `OPENCLAW_PROXY_URL`-Fallback in diesem owner-spezifischen Transport-Pfad.
Einige Plugins besitzen benutzerdefinierte Transporte, die explizite Proxy-Verdrahtung benötigen, auch wenn Routing auf Prozessebene vorhanden ist. Beispielsweise verwendet der Bot-API-Transport von Telegram seinen eigenen HTTP/1-Undici-Dispatcher und berücksichtigt daher die Prozess-Proxy-Umgebung sowie den verwalteten `OPENCLAW_PROXY_URL`-Fallback in diesem owner-spezifischen Transportpfad.
Die Proxy-URL selbst muss `http://` verwenden. HTTPS-Ziele werden über den Proxy weiterhin mit HTTP `CONNECT` unterstützt; das bedeutet lediglich, dass OpenClaw einen einfachen HTTP-Forward-Proxy-Listener wie `http://127.0.0.1:3128` erwartet.
Die Proxy-URL selbst muss `http://` verwenden. HTTPS-Ziele werden weiterhin über den Proxy mit HTTP `CONNECT` unterstützt; das bedeutet lediglich, dass OpenClaw einen einfachen HTTP-Forward-Proxy-Listener wie `http://127.0.0.1:3128` erwartet.
Während der Proxy aktiv ist, entfernt OpenClaw `no_proxy`, `NO_PROXY` und `GLOBAL_AGENT_NO_PROXY`. Diese Umgehungslisten sind zielbasiert; wenn dort `localhost` oder `127.0.0.1` verbleiben würde, könnten risikoreiche SSRF-Ziele den filternden Proxy überspringen.
Während der Proxy aktiv ist, löscht OpenClaw `no_proxy`, `NO_PROXY` und `GLOBAL_AGENT_NO_PROXY`. Diese Bypass-Listen sind zielbasiert, sodass `localhost` oder `127.0.0.1` dort risikoreiche SSRF-Ziele den filternden Proxy umgehen lassen würden.
Beim Herunterfahren stellt OpenClaw die vorherige Proxy-Umgebung wieder her und setzt zwischengespeicherten Prozess-Routing-Status zurück.
Beim Herunterfahren stellt OpenClaw die vorherige Proxy-Umgebung wieder her und setzt den zwischengespeicherten Prozess-Routing-Zustand zurück.
## Verwandte Proxy-Begriffe
- `proxy.enabled` / `proxy.proxyUrl`: ausgehendes Forward-Proxy-Routing für OpenClaw-Laufzeit-Egress. Diese Seite dokumentiert diese Funktion.
- `gateway.auth.mode: "trusted-proxy"`: eingehende identitätsbewusste Reverse-Proxy-Authentifizierung für Gateway-Zugriff. Siehe [Authentifizierung über vertrauenswürdigen Proxy](/de/gateway/trusted-proxy-auth).
- `openclaw proxy`: lokaler Debug-Proxy und Capture-Inspector für Entwicklung und Support. Siehe [openclaw proxy](/de/cli/proxy).
- Kanal- oder Provider-spezifische Proxy-Einstellungen: owner-spezifische Überschreibungen für einen bestimmten Transport. Bevorzugen Sie den verwalteten Netzwerk-Proxy, wenn das Ziel eine zentrale Egress-Kontrolle über die Laufzeit hinweg ist.
- `gateway.auth.mode: "trusted-proxy"`: eingehende identitätsbewusste Reverse-Proxy-Authentifizierung für Gateway-Zugriff. Siehe [Trusted-Proxy-Authentifizierung](/de/gateway/trusted-proxy-auth).
- `openclaw proxy`: lokaler Debug-Proxy und Erfassungsinspektor für Entwicklung und Support. Siehe [openclaw proxy](/de/cli/proxy).
- `tools.web.fetch.useTrustedEnvProxy`: Opt-in für `web_fetch`, damit ein betreibergesteuerter HTTP(S)-Umgebungsproxy DNS auflösen kann, während die standardmäßig strikte DNS-Pinning- und Hostnamen-Richtlinie beibehalten wird. Siehe [Web-Fetch](/de/tools/web-fetch#trusted-env-proxy).
- Kanal- oder Provider-spezifische Proxy-Einstellungen: owner-spezifische Überschreibungen für einen bestimmten Transport. Bevorzugen Sie den verwalteten Netzwerk-Proxy, wenn das Ziel zentrale Egress-Kontrolle über die Laufzeit hinweg ist.
## Konfiguration
@ -81,9 +82,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` hat Vorrang vor `OPENCLAW_PROXY_URL`.
Wenn `enabled=true` ist, aber keine gültige Proxy-URL konfiguriert wurde, schlagen geschützte Befehle beim Start fehl, statt auf direkten Netzwerkzugriff zurückzufallen.
Wenn `enabled=true` ist, aber keine gültige Proxy-URL konfiguriert ist, schlagen geschützte Befehle beim Start fehl, statt auf direkten Netzwerkzugriff zurückzufallen.
Für verwaltete Gateway-Dienste, die mit `openclaw gateway start` gestartet werden, sollten Sie die URL bevorzugt in der Konfiguration speichern:
Für verwaltete Gateway-Dienste, die mit `openclaw gateway start` gestartet werden, speichern Sie die URL vorzugsweise in der Konfiguration:
```bash
openclaw config set proxy.enabled true
@ -92,9 +93,9 @@ openclaw gateway install --force
openclaw gateway start
```
Der Umgebungs-Fallback eignet sich am besten für Vordergrundläufe. Wenn Sie ihn mit einem installierten Dienst verwenden, legen Sie `OPENCLAW_PROXY_URL` in der dauerhaften Umgebung des Dienstes ab, etwa in `$OPENCLAW_STATE_DIR/.env` oder `~/.openclaw/.env`, und installieren Sie den Dienst anschließend neu, damit launchd, systemd oder Geplante Aufgaben das Gateway mit diesem Wert startet.
Der Umgebungs-Fallback eignet sich am besten für Vordergrundläufe. Wenn Sie ihn mit einem installierten Dienst verwenden, legen Sie `OPENCLAW_PROXY_URL` in der dauerhaften Umgebung des Dienstes ab, etwa in `$OPENCLAW_STATE_DIR/.env` oder `~/.openclaw/.env`, und installieren Sie den Dienst anschließend neu, damit launchd, systemd oder Scheduled Tasks das Gateway mit diesem Wert startet.
Für `openclaw --container ...`-Befehle leitet OpenClaw `OPENCLAW_PROXY_URL` an die containerbezogene Child-CLI weiter, wenn es gesetzt ist. Die URL muss aus dem Container heraus erreichbar sein; `127.0.0.1` verweist auf den Container selbst, nicht auf den Host. OpenClaw weist Loopback-Proxy-URLs für containerbezogene Befehle zurück, es sei denn, Sie überschreiben diese Sicherheitsprüfung ausdrücklich.
Für `openclaw --container ...`-Befehle leitet OpenClaw `OPENCLAW_PROXY_URL` an die containerbezogene untergeordnete CLI weiter, wenn sie gesetzt ist. Die URL muss aus dem Container heraus erreichbar sein; `127.0.0.1` bezieht sich auf den Container selbst, nicht auf den Host. OpenClaw lehnt Loopback-Proxy-URLs für containerbezogene Befehle ab, sofern Sie diese Sicherheitsprüfung nicht explizit überschreiben.
## Proxy-Anforderungen
@ -102,30 +103,30 @@ Die Proxy-Richtlinie ist die Sicherheitsgrenze. OpenClaw kann nicht überprüfen
Konfigurieren Sie den Proxy so, dass er:
- Nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet.
- Den Zugriff so einschränkt, dass nur der OpenClaw-Prozess, Host, Container oder das Dienstkonto ihn verwenden kann.
- nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet.
- den Zugriff so einschränkt, dass nur der OpenClaw-Prozess, Host, Container oder das Dienstkonto ihn verwenden kann.
- Ziele selbst auflöst und Ziel-IPs nach der DNS-Auflösung blockiert.
- Richtlinien zur Verbindungszeit sowohl für einfache HTTP-Anfragen als auch für HTTPS-`CONNECT`-Tunnel anwendet.
- Zielbasierte Umgehungen für Loopback-, private, link-lokale, Metadaten-, Multicast-, reservierte oder Dokumentationsbereiche ablehnt.
- Hostname-Allowlists vermeidet, es sei denn, Sie vertrauen dem DNS-Auflösungspfad vollständig.
- Ziel, Entscheidung, Status und Grund protokolliert, ohne Anfragetexte, Autorisierungs-Header, Cookies oder andere Geheimnisse zu protokollieren.
- Proxy-Richtlinien unter Versionskontrolle hält und Änderungen wie sicherheitssensitive Konfiguration prüft.
- Richtlinien beim Verbindungsaufbau sowohl für einfache HTTP-Anfragen als auch für HTTPS-`CONNECT`-Tunnel anwendet.
- zielbasierte Umgehungen für Loopback-, private, linklokale, Metadaten-, Multicast-, reservierte oder Dokumentationsbereiche ablehnt.
- Hostnamen-Allowlists vermeidet, sofern Sie dem DNS-Auflösungspfad nicht vollständig vertrauen.
- Ziel, Entscheidung, Status und Grund protokolliert, ohne Anfrage-Bodys, Autorisierungs-Header, Cookies oder andere Secrets zu protokollieren.
- die Proxy-Richtlinie unter Versionskontrolle hält und Änderungen wie sicherheitssensible Konfiguration prüft.
## Empfohlene blockierte Ziele
Verwenden Sie diese Denylist als Ausgangspunkt für jeden Forward-Proxy sowie jede Firewall- oder Egress-Richtlinie.
Verwenden Sie diese Denylist als Ausgangspunkt für jeden Forward-Proxy, jede Firewall oder jede Egress-Richtlinie.
Die Klassifizierungslogik auf OpenClaw-Anwendungsebene befindet sich in `src/infra/net/ssrf.ts` und `src/shared/net/ip.ts`. Die relevanten Paritäts-Hooks sind `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` und die eingebettete IPv4-Sentinel-Behandlung für NAT64, 6to4, Teredo, ISATAP und IPv4-gemappte Formen. Diese Dateien sind nützliche Referenzen bei der Pflege einer externen Proxy-Richtlinie, aber OpenClaw exportiert oder erzwingt diese Regeln nicht automatisch in Ihrem Proxy.
Die Klassifizierungslogik auf OpenClaw-Anwendungsebene befindet sich in `src/infra/net/ssrf.ts` und `src/shared/net/ip.ts`. Die relevanten Parity-Hooks sind `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` und die eingebettete IPv4-Sentinel-Behandlung für NAT64, 6to4, Teredo, ISATAP und IPv4-gemappte Formen. Diese Dateien sind nützliche Referenzen, wenn Sie eine externe Proxy-Richtlinie pflegen, aber OpenClaw exportiert oder erzwingt diese Regeln nicht automatisch in Ihrem Proxy.
| Bereich oder Host | Warum blockieren |
| Bereich oder Host | Warum blockieren |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4-Loopback |
| `::1/128` | IPv6-Loopback |
| `0.0.0.0/8`, `::/128` | Nicht angegebene und This-Network-Adressen |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Private Netzwerke nach RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | Link-lokale Adressen und gängige Cloud-Metadatenpfade |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Private RFC1918-Netzwerke |
| `169.254.0.0/16`, `fe80::/10` | Linklokale Adressen und gängige Cloud-Metadatenpfade |
| `169.254.169.254`, `metadata.google.internal` | Cloud-Metadatendienste |
| `100.64.0.0/10` | Gemeinsamer Adressraum für Carrier-Grade-NAT |
| `100.64.0.0/10` | Gemeinsamer Adressraum für Carrier-Grade-NAT |
| `198.18.0.0/15`, `2001:2::/48` | Benchmarking-Bereiche |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-Use- und Dokumentationsbereiche |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
@ -140,15 +141,15 @@ Wenn Ihr Cloud-Provider oder Ihre Netzwerkplattform zusätzliche Metadaten-Hosts
## Validierung
Validieren Sie den Proxy von demselben Host, Container oder Dienstkonto aus, auf dem OpenClaw läuft:
Validieren Sie den Proxy vom selben Host, Container oder Dienstkonto aus, das OpenClaw ausführt:
```bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
Standardmäßig prüft der Befehl, wenn keine benutzerdefinierten Ziele angegeben werden, dass `https://example.com/` erfolgreich ist, und startet einen temporären Loopback-Canary, den der Proxy nicht erreichen darf. Die standardmäßige verweigerte Prüfung gilt als bestanden, wenn der Proxy eine Nicht-2xx-Verweigerungsantwort zurückgibt oder den Canary mit einem Transportfehler blockiert; sie schlägt fehl, wenn eine erfolgreiche Antwort den Canary erreicht. Wenn kein Proxy aktiviert und konfiguriert ist, meldet die Validierung ein Konfigurationsproblem; verwenden Sie `--proxy-url` für einen einmaligen Preflight, bevor Sie die Konfiguration ändern. Verwenden Sie `--allowed-url` und `--denied-url`, um bereitstellungsspezifische Erwartungen zu testen. Fügen Sie `--apns-reachable` hinzu, um außerdem zu prüfen, ob direkte APNs-HTTP/2-Zustellung einen CONNECT-Tunnel durch den Proxy öffnen und eine Sandbox-APNs-Antwort empfangen kann; die Prüfung verwendet absichtlich ein ungültiges Provider-Token, daher wird `403 InvalidProviderToken` erwartet und zählt als erreichbar. Benutzerdefinierte verweigerte Ziele sind Fail-Closed: Jede HTTP-Antwort bedeutet, dass das Ziel über den Proxy erreichbar war, und jeder Transportfehler wird als nicht eindeutig gemeldet, weil OpenClaw nicht beweisen kann, dass der Proxy einen erreichbaren Ursprung blockiert hat. Bei einem Validierungsfehler beendet sich der Befehl mit Code 1.
Standardmäßig prüft der Befehl, wenn keine benutzerdefinierten Ziele angegeben sind, dass `https://example.com/` erfolgreich ist, und startet einen temporären Loopback-Canary, den der Proxy nicht erreichen darf. Die standardmäßige Ablehnungsprüfung gilt als bestanden, wenn der Proxy eine Nicht-2xx-Ablehnungsantwort zurückgibt oder den Canary mit einem Transportfehler blockiert; sie schlägt fehl, wenn eine erfolgreiche Antwort den Canary erreicht. Wenn kein Proxy aktiviert und konfiguriert ist, meldet die Validierung ein Konfigurationsproblem; verwenden Sie `--proxy-url` für einen einmaligen Preflight vor einer Konfigurationsänderung. Verwenden Sie `--allowed-url` und `--denied-url`, um bereitstellungsspezifische Erwartungen zu testen. Fügen Sie `--apns-reachable` hinzu, um außerdem zu prüfen, ob direkte APNs-HTTP/2-Zustellung einen CONNECT-Tunnel über den Proxy öffnen und eine Sandbox-APNs-Antwort empfangen kann; die Prüfung verwendet absichtlich ein ungültiges Provider-Token, daher wird `403 InvalidProviderToken` erwartet und als erreichbar gewertet. Benutzerdefinierte abgelehnte Ziele sind Fail-Closed: Jede HTTP-Antwort bedeutet, dass das Ziel über den Proxy erreichbar war, und jeder Transportfehler wird als nicht schlüssig gemeldet, weil OpenClaw nicht beweisen kann, dass der Proxy einen erreichbaren Ursprung blockiert hat. Bei einem Validierungsfehler beendet sich der Befehl mit Code 1.
Verwenden Sie `--json` für Automatisierung. Die JSON-Ausgabe enthält das Gesamtergebnis, die effektive Proxy-Konfigurationsquelle, alle Konfigurationsfehler und jede Zielprüfung. Zugangsdaten in Proxy-URLs werden in Text- und JSON-Ausgabe redigiert:
Verwenden Sie `--json` zur Automatisierung. Die JSON-Ausgabe enthält das Gesamtergebnis, die effektive Quelle der Proxy-Konfiguration, etwaige Konfigurationsfehler und jede Zielprüfung. Anmeldedaten in Proxy-URLs werden in Text- und JSON-Ausgabe geschwärzt:
```json
{
@ -184,7 +185,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
Die öffentliche Anfrage sollte erfolgreich sein. Die Loopback- und Metadatenanfragen sollten vom Proxy blockiert werden. Bei `openclaw proxy validate` kann die integrierte Loopback-Canary-Prüfung eine Proxy-Ablehnung von einem erreichbaren Ursprung unterscheiden. Benutzerdefinierte `--denied-url`-Prüfungen haben diese Canary-Prüfung nicht. Behandeln Sie daher sowohl HTTP-Antworten als auch mehrdeutige Transportfehler als Validierungsfehler, es sei denn, Ihr Proxy stellt ein bereitstellungsspezifisches Ablehnungssignal bereit, das Sie separat verifizieren können.
Die öffentliche Anfrage sollte erfolgreich sein. Die Loopback- und Metadatenanfragen sollten vom Proxy blockiert werden. Bei `openclaw proxy validate` kann der eingebaute Loopback-Canary eine Proxy-Ablehnung von einem erreichbaren Ursprung unterscheiden. Benutzerdefinierte `--denied-url`-Prüfungen haben diesen Canary nicht. Behandeln Sie daher sowohl HTTP-Antworten als auch mehrdeutige Transportfehler als Validierungsfehler, sofern Ihr Proxy kein deploymentspezifisches Ablehnungssignal bereitstellt, das Sie separat verifizieren können.
Aktivieren Sie anschließend das OpenClaw-Proxy-Routing:
@ -194,7 +195,7 @@ openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run
```
oder legen Sie fest:
oder legen Sie Folgendes fest:
```yaml
proxy:
@ -202,13 +203,13 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
## Einschränkungen
## Grenzen
- Der Proxy verbessert die Abdeckung für prozesslokale JavaScript-HTTP- und WebSocket-Clients, ist aber keine Netzwerk-Sandbox auf Betriebssystemebene.
- Raw-`net`-, `tls`- und `http2`-Sockets, native Addons und untergeordnete Prozesse können das Proxy-Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht übernehmen und beachten.
- IRC ist ein Raw-TCP/TLS-Kanal außerhalb des operatorverwalteten Forward-Proxy-Routings. Setzen Sie in Bereitstellungen, die den gesamten ausgehenden Datenverkehr über diesen Forward Proxy erfordern, `channels.irc.enabled=false`, sofern direkter ausgehender IRC-Datenverkehr nicht ausdrücklich genehmigt ist.
- Der lokale Debug-Proxy ist ein Diagnosewerkzeug, und seine direkte Upstream-Weiterleitung für Proxy-Anfragen und CONNECT-Tunnel ist standardmäßig deaktiviert, während der verwaltete Proxy-Modus aktiv ist; aktivieren Sie direkte Weiterleitung nur für genehmigte lokale Diagnosen.
- Lokale WebUIs der Benutzer und lokale Modellserver sollten bei Bedarf in der Operator-Proxy-Richtlinie auf die Allowlist gesetzt werden; OpenClaw stellt für sie keine allgemeine Umgehung des lokalen Netzwerks bereit.
- Die Proxy-Umgehung der Gateway-Control-Plane ist absichtlich auf `localhost` und literale Loopback-IP-URLs beschränkt. Verwenden Sie `ws://127.0.0.1:18789`, `ws://[::1]:18789` oder `ws://localhost:18789` für lokale direkte Gateway-Control-Plane-Verbindungen; andere Hostnamen werden wie gewöhnlicher hostnamebasierter Datenverkehr geroutet.
- Rohe `net`-, `tls`- und `http2`-Sockets, native Add-ons und untergeordnete Prozesse können das Proxy-Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht erben und beachten.
- IRC ist ein roher TCP/TLS-Kanal außerhalb des operatorverwalteten Forward-Proxy-Routings. Setzen Sie in Deployments, die gesamten ausgehenden Datenverkehr über diesen Forward-Proxy erfordern, `channels.irc.enabled=false`, sofern direkter IRC-Egress nicht ausdrücklich genehmigt ist.
- Der lokale Debug-Proxy ist Diagnosewerkzeug. Seine direkte Upstream-Weiterleitung für Proxy-Anfragen und CONNECT-Tunnel ist standardmäßig deaktiviert, solange der verwaltete Proxy-Modus aktiv ist. Aktivieren Sie direkte Weiterleitung nur für genehmigte lokale Diagnosen.
- Lokale WebUIs der Benutzer und lokale Modellserver sollten bei Bedarf in der Operator-Proxy-Richtlinie auf die Allowlist gesetzt werden; OpenClaw stellt für sie keinen allgemeinen Bypass für lokale Netzwerke bereit.
- Der Proxy-Bypass der Gateway-Steuerungsebene ist absichtlich auf `localhost` und literale Loopback-IP-URLs beschränkt. Verwenden Sie `ws://127.0.0.1:18789`, `ws://[::1]:18789` oder `ws://localhost:18789` für lokale direkte Gateway-Verbindungen zur Steuerungsebene; andere Hostnamen werden wie gewöhnlicher hostnamenbasierter Datenverkehr geroutet.
- OpenClaw prüft, testet oder zertifiziert Ihre Proxy-Richtlinie nicht.
- Behandeln Sie Änderungen an Proxy-Richtlinien als sicherheitssensible betriebliche Änderungen.
- Behandeln Sie Änderungen an der Proxy-Richtlinie als sicherheitssensible betriebliche Änderungen.

77
docs/de/tools/loop-detection.md
View File

@ -1,29 +1,29 @@
---
read_when:
- Ein Benutzer meldet, dass Agenten beim Wiederholen von Tool-Aufrufen hängen bleiben
- Sie müssen den Schutz vor wiederholten Aufrufen feinabstimmen
- Sie bearbeiten Richtlinien für Agentenwerkzeuge und -Laufzeiten
summary: So aktivieren und optimieren Sie Schutzmechanismen, die sich wiederholende Tool-Aufruf-Schleifen erkennen
title: Erkennung von Tool-Schleifen
- Sie müssen den Schutz vor wiederholten Aufrufen anpassen
- Sie bearbeiten Richtlinien für Agenten-Tools und Laufzeitumgebungen
summary: So aktivieren und konfigurieren Sie Schutzmechanismen, die sich wiederholende Tool-Aufruf-Schleifen erkennen
title: Tool-Loop-Erkennung
x-i18n:
generated_at: "2026-05-03T21:39:38Z"
generated_at: "2026-05-05T01:49:38Z"
model: gpt-5.5
provider: openai
source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97
source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb
source_path: tools/loop-detection.md
workflow: 16
---
OpenClaw kann verhindern, dass Agenten in wiederholten Tool-Aufrufmustern stecken bleiben.
Der Schutzmechanismus ist **standardmäßig deaktiviert**.
Der Schutz ist **standardmäßig deaktiviert**.
Aktivieren Sie ihn nur dort, wo er benötigt wird, da er bei strengen Einstellungen legitime wiederholte Aufrufe blockieren kann.
## Warum dies existiert
- Erkennen repetitiver Sequenzen, die keinen Fortschritt erzielen.
- Erkennen hochfrequenter Schleifen ohne Ergebnis (gleiches Tool, gleiche Eingaben, wiederholte Fehler).
- Erkennen bestimmter Muster wiederholter Aufrufe für bekannte Polling-Tools.
- Sich wiederholende Sequenzen erkennen, die keinen Fortschritt machen.
- Hochfrequente Schleifen ohne Ergebnis erkennen (gleiches Tool, gleiche Eingaben, wiederholte Fehler).
- Spezifische Muster wiederholter Aufrufe für bekannte Polling-Tools erkennen.
## Konfigurationsblock
@ -69,43 +69,66 @@ Globale Standardwerte:
}
```
### Feldverhalten
### Verhalten der Felder
- `enabled`: Hauptschalter. `false` bedeutet, dass keine Schleifenerkennung durchgeführt wird.
- `historySize`: Anzahl der letzten Tool-Aufrufe, die für die Analyse vorgehalten werden.
- `historySize`: Anzahl der jüngsten Tool-Aufrufe, die für die Analyse vorgehalten werden.
- `warningThreshold`: Schwellenwert, ab dem ein Muster als reine Warnung eingestuft wird.
- `criticalThreshold`: Schwellenwert zum Blockieren repetitiver Schleifenmuster.
- `globalCircuitBreakerThreshold`: globaler Schwellenwert für den Unterbrecher bei ausbleibendem Fortschritt.
- `detectors.genericRepeat`: erkennt wiederholte Muster aus gleichem Tool und gleichen Parametern.
- `detectors.knownPollNoProgress`: erkennt bekannte polling-ähnliche Muster ohne Zustandsänderung.
- `criticalThreshold`: Schwellenwert zum Blockieren sich wiederholender Schleifenmuster.
- `globalCircuitBreakerThreshold`: Globaler Schwellenwert für den Abbruch bei fehlendem Fortschritt.
- `detectors.genericRepeat`: erkennt wiederholte Muster mit gleichem Tool + gleichen Parametern.
- `detectors.knownPollNoProgress`: erkennt bekannte polling-artige Muster ohne Zustandsänderung.
- `detectors.pingPong`: erkennt alternierende Ping-Pong-Muster.
Für `exec` vergleichen Prüfungen auf ausbleibenden Fortschritt stabile Befehlsresultate und ignorieren flüchtige Laufzeitmetadaten wie Dauer, PID, Sitzungs-ID und Arbeitsverzeichnis.
Wenn eine Run-ID verfügbar ist, wird der Verlauf der letzten Tool-Aufrufe nur innerhalb dieses Runs ausgewertet, sodass geplante Heartbeat-Zyklen und neue Runs keine veralteten Schleifenzähler aus früheren Runs übernehmen.
Für `exec` vergleichen Prüfungen auf fehlenden Fortschritt stabile Befehlsresultate und ignorieren flüchtige Laufzeitmetadaten wie Dauer, PID, Sitzungs-ID und Arbeitsverzeichnis.
Wenn eine Run-ID verfügbar ist, wird der jüngste Verlauf der Tool-Aufrufe nur innerhalb dieses Runs ausgewertet, sodass geplante Heartbeat-Zyklen und neue Runs keine veralteten Schleifenzähler aus früheren Runs übernehmen.
## Empfohlene Einrichtung
- Für kleinere Modelle beginnen Sie mit `enabled: true` und unveränderten Standardwerten. Flaggschiffmodelle benötigen selten Schleifenerkennung und können sie deaktiviert lassen.
- Aktivieren Sie für kleinere Modelle zunächst `enabled: true` und lassen Sie die Standardwerte unverändert. Flaggschiffmodelle benötigen Schleifenerkennung selten und können sie deaktiviert lassen.
- Halten Sie die Schwellenwerte in der Reihenfolge `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- Wenn Fehlalarme auftreten:
- erhöhen Sie `warningThreshold` und/oder `criticalThreshold`
- erhöhen Sie (optional) `globalCircuitBreakerThreshold`
- erhöhen Sie optional `globalCircuitBreakerThreshold`
- deaktivieren Sie nur den Detector, der Probleme verursacht
- reduzieren Sie `historySize` für weniger strikten historischen Kontext
- verringern Sie `historySize`, um den historischen Kontext weniger streng zu machen
## Logs und erwartetes Verhalten
## Post-Compaction-Schutz
Wenn eine Schleife erkannt wird, meldet OpenClaw ein Schleifenereignis und blockiert oder dämpft den nächsten Tool-Zyklus abhängig vom Schweregrad.
Wenn der Runner einen automatischen Compaction-Wiederholungsversuch abschließt (nach einem Kontextüberlauf), aktiviert er für ein kurzes Fenster einen Schutz, der die nächsten wenigen Tool-Aufrufe beobachtet. Wenn der Agent innerhalb dieses Fensters mehrfach dasselbe `(toolName, args, result)`-Tripel ausgibt, folgert der Schutz, dass die Compaction die Schleife nicht unterbrochen hat, und bricht den Run mit einem Fehler `compaction_loop_persisted` ab.
Dies ist ein separater Codepfad neben den globalen `tools.loopDetection`-Detectors. Er ist unabhängig konfigurierbar:
```json5
{
tools: {
loopDetection: {
enabled: true, // existing master switch; set false to disable loop guards
postCompactionGuard: {
windowSize: 3, // default: 3
},
},
},
}
```
- `windowSize`: Anzahl der Tool-Aufrufe nach der Compaction, während derer der Schutz aktiv bleibt, _und_ Anzahl identischer Tripel aus (Tool, Argumenten, Ergebnis), die einen Abbruch auslösen.
Der Schutz bricht niemals ab, wenn sich Ergebnisse ändern, sondern nur, wenn Ergebnisse über das Fenster hinweg byte-identisch sind. Er ist absichtlich eng gefasst: Er greift nur unmittelbar nach einem Compaction-Wiederholungsversuch.
## Protokolle und erwartetes Verhalten
Wenn eine Schleife erkannt wird, meldet OpenClaw ein Schleifenereignis und blockiert oder dämpft den nächsten Tool-Zyklus je nach Schweregrad.
Dies schützt Benutzer vor ausuferndem Token-Verbrauch und Blockaden, während der normale Tool-Zugriff erhalten bleibt.
- Bevorzugen Sie zuerst Warnungen und temporäre Unterdrückung.
- Eskalieren Sie erst, wenn sich wiederholte Evidenz ansammelt.
- Bevorzugen Sie zunächst Warnungen und temporäre Unterdrückung.
- Eskalieren Sie nur, wenn sich wiederholte Hinweise ansammeln.
## Hinweise
- `tools.loopDetection` wird mit Überschreibungen auf Agentenebene zusammengeführt.
- `tools.loopDetection` wird mit Overrides auf Agent-Ebene zusammengeführt.
- Die Konfiguration pro Agent überschreibt oder erweitert globale Werte vollständig.
- Wenn keine Konfiguration vorhanden ist, bleiben Schutzmechanismen ausgeschaltet.
- Wenn keine Konfiguration vorhanden ist, bleiben die Schutzmechanismen deaktiviert.
## Verwandte Themen

127
docs/de/tools/media-overview.md
View File

@ -1,16 +1,16 @@
---
read_when:
- Suchen Sie nach einer Übersicht über die Medienfunktionen von OpenClaw
- Suchen Sie nach einem Überblick über die Medienfunktionen von OpenClaw
- Entscheiden, welcher Medien-Provider konfiguriert werden soll
- Verstehen, wie asynchrone Mediengenerierung funktioniert
sidebarTitle: Media overview
summary: Funktionen für Bild, Video, Musik, Sprache und Medienverständnis auf einen Blick
title: Medienübersicht
x-i18n:
generated_at: "2026-04-30T07:19:08Z"
generated_at: "2026-05-05T01:50:18Z"
model: gpt-5.5
provider: openai
source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508
source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
source_path: tools/media-overview.md
workflow: 16
---
@ -18,39 +18,39 @@ x-i18n:
OpenClaw generiert Bilder, Videos und Musik, versteht eingehende Medien
(Bilder, Audio, Video) und spricht Antworten per Text-to-Speech laut aus. Alle
Medienfunktionen sind toolgesteuert: Der Agent entscheidet anhand der
Konversation, wann sie verwendet werden, und jedes Tool erscheint nur, wenn
mindestens ein unterstützender Provider konfiguriert ist.
Unterhaltung, wann sie verwendet werden, und jedes Tool erscheint nur, wenn
mindestens ein zugrunde liegender Provider konfiguriert ist.
## Fähigkeiten
## Funktionen
<CardGroup cols={2}>
<Card title="Bildgenerierung" href="/de/tools/image-generation" icon="image">
<Card title="Image generation" href="/de/tools/image-generation" icon="image">
Erstellen und bearbeiten Sie Bilder aus Text-Prompts oder Referenzbildern über
`image_generate`. Synchron — wird inline mit der Antwort abgeschlossen.
</Card>
<Card title="Videogenerierung" href="/de/tools/video-generation" icon="video">
<Card title="Video generation" href="/de/tools/video-generation" icon="video">
Text-zu-Video, Bild-zu-Video und Video-zu-Video über `video_generate`.
Asynchron — läuft im Hintergrund und sendet das Ergebnis, sobald es bereit ist.
Asynchron — läuft im Hintergrund und postet das Ergebnis, sobald es bereit ist.
</Card>
<Card title="Musikgenerierung" href="/de/tools/music-generation" icon="music">
Generieren Sie Musik oder Audiospuren über `music_generate`. Asynchron bei gemeinsam genutzten
Providern; der ComfyUI-Workflow-Pfad läuft synchron.
<Card title="Music generation" href="/de/tools/music-generation" icon="music">
Generieren Sie Musik oder Audiospuren über `music_generate`. Asynchron bei gemeinsam
genutzten Providern; der ComfyUI-Workflow-Pfad läuft synchron.
</Card>
<Card title="Text-to-Speech" href="/de/tools/tts" icon="microphone">
Wandeln Sie ausgehende Antworten über das Tool `tts` plus
`messages.tts`-Konfiguration in gesprochene Audiodaten um. Synchron.
<Card title="Text-to-speech" href="/de/tools/tts" icon="microphone">
Konvertieren Sie ausgehende Antworten über das `tts`-Tool plus
`messages.tts`-Konfiguration in gesprochene Audiodaten. Synchron.
</Card>
<Card title="Medienverständnis" href="/de/nodes/media-understanding" icon="eye">
Fassen Sie eingehende Bilder, Audio und Video mit vision-fähigen Modell-
Providern und dedizierten Medienverständnis-Plugins zusammen.
<Card title="Media understanding" href="/de/nodes/media-understanding" icon="eye">
Fassen Sie eingehende Bilder, Audio und Video mit bildfähigen Modell-Providern
und dedizierten Medienverständnis-Plugins zusammen.
</Card>
<Card title="Speech-to-Text" href="/de/nodes/audio" icon="ear-listen">
Transkribieren Sie eingehende Sprachnachrichten über Batch-STT oder Voice Call-
Streaming-STT-Provider.
<Card title="Speech-to-text" href="/de/nodes/audio" icon="ear-listen">
Transkribieren Sie eingehende Sprachnachrichten über Batch-STT oder Streaming-STT-Provider
für Sprachanrufe.
</Card>
</CardGroup>
## Provider-Fähigkeitsmatrix
## Provider-Funktionsmatrix
| Provider | Bild | Video | Musik | TTS | STT | Echtzeit-Sprache | Medienverständnis |
| ----------- | :--: | :---: | :---: | :-: | :-: | :--------------: | :---------------: |
@ -63,7 +63,7 @@ mindestens ein unterstützender Provider konfiguriert ist.
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| Lokale CLI | | | | ✓ | | | |
| Local CLI | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
@ -78,73 +78,74 @@ mindestens ein unterstützender Provider konfiguriert ist.
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
<Note>
Medienverständnis verwendet jedes vision-fähige oder audiofähige Modell, das
in Ihrer Provider-Konfiguration registriert ist. Die Matrix oben listet Provider
mit dedizierter Medienverständnis-Unterstützung auf; die meisten multimodalen
LLM-Provider (Anthropic, Google, OpenAI usw.) können eingehende Medien ebenfalls
verstehen, wenn sie als aktives Antwortmodell konfiguriert sind.
Medienverständnis verwendet jedes bildfähige oder audiofähige Modell, das
in Ihrer Provider-Konfiguration registriert ist. Die obige Matrix listet Provider mit dedizierter
Unterstützung für Medienverständnis auf; die meisten multimodalen LLM-Provider (Anthropic, Google,
OpenAI usw.) können eingehende Medien ebenfalls verstehen, wenn sie als aktives
Antwortmodell konfiguriert sind.
</Note>
## Asynchron vs. synchron
## Asynchron im Vergleich zu synchron
| Fähigkeit | Modus | Warum |
| --------------- | ----------- | ----------------------------------------------------------------- |
| Bild | Synchron | Provider-Antworten werden in Sekunden zurückgegeben; Abschluss inline mit der Antwort. |
| Text-to-Speech | Synchron | Provider-Antworten werden in Sekunden zurückgegeben; an das Antwortaudio angehängt. |
| Video | Asynchron | Die Provider-Verarbeitung dauert 30 s bis mehrere Minuten. |
| Musik (geteilt) | Asynchron | Gleiche Provider-Verarbeitungseigenschaft wie bei Video. |
| Musik (ComfyUI) | Synchron | Lokaler Workflow läuft inline gegen den konfigurierten ComfyUI-Server. |
| Funktion | Modus | Warum |
| --------------- | ------------ | ----------------------------------------------------------------- |
| Bild | Synchron | Provider-Antworten kommen in Sekunden zurück; wird inline mit der Antwort abgeschlossen. |
| Text-to-Speech | Synchron | Provider-Antworten kommen in Sekunden zurück; an die Antwort-Audiodatei angehängt. |
| Video | Asynchron | Die Provider-Verarbeitung dauert 30 s bis mehrere Minuten. |
| Musik (geteilt) | Asynchron | Dieselbe Provider-Verarbeitungseigenschaft wie bei Video. |
| Musik (ComfyUI) | Synchron | Lokaler Workflow läuft inline gegen den konfigurierten ComfyUI-Server. |
Für asynchrone Tools sendet OpenClaw die Anfrage an den Provider, gibt sofort
eine Aufgaben-ID zurück und verfolgt den Job im Aufgaben-Ledger. Der Agent
antwortet weiter auf andere Nachrichten, während der Job läuft. Wenn der
Provider fertig ist, weckt OpenClaw den Agent, damit er die fertigen Medien
zurück in den ursprünglichen Kanal posten kann.
Für asynchrone Tools übermittelt OpenClaw die Anfrage an den Provider, gibt sofort
eine Task-ID zurück und verfolgt den Job im Task-Ledger. Der Agent fährt fort,
auf andere Nachrichten zu antworten, während der Job läuft. Wenn der Provider fertig ist,
weckt OpenClaw den Agent mit den generierten Medienpfaden, damit er es dem
Benutzer mitteilen und, wenn es die Richtlinie für die Zustellung über die Quelle erfordert, das Ergebnis über
das Nachrichtentool weiterleiten kann.
## Speech-to-Text und Voice Call
## Speech-to-Text und Sprachanruf
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio und xAI können alle
eingehendes Audio über den Batch-Pfad `tools.media.audio` transkribieren, wenn sie konfiguriert sind.
Kanal-Plugins, die eine Sprachnotiz für Mention-Gating oder Befehlsparsing
eingehende Audiodaten über den Batch-Pfad `tools.media.audio` transkribieren, wenn sie konfiguriert sind.
Channel-Plugins, die eine Sprachnotiz für Mention-Gating oder Befehls-Parsing
vorab prüfen, markieren den transkribierten Anhang im eingehenden Kontext, sodass der gemeinsame
Medienverständnis-Durchlauf dieses Transkript wiederverwendet, statt einen zweiten
STT-Aufruf für dasselbe Audio auszuführen.
Medienverständnis-Durchlauf dieses Transkript wiederverwendet, anstatt einen zweiten
STT-Aufruf für dieselben Audiodaten auszuführen.
Deepgram, ElevenLabs, Mistral, OpenAI und xAI registrieren außerdem Voice Call-
Streaming-STT-Provider, sodass Live-Telefonaudio an den ausgewählten
Vendor weitergeleitet werden kann, ohne auf eine abgeschlossene Aufnahme zu warten.
Deepgram, ElevenLabs, Mistral, OpenAI und xAI registrieren außerdem
Streaming-STT-Provider für Sprachanrufe, sodass Live-Telefonaudio an den ausgewählten
Vendor weitergeleitet werden kann, ohne auf eine abgeschlossene Aufzeichnung zu warten.
## Provider-Zuordnungen (wie Vendors Oberflächen aufteilen)
## Provider-Zuordnungen (wie Vendors auf Oberflächen verteilt sind)
<AccordionGroup>
<Accordion title="Google">
Bild-, Video-, Musik-, Batch-TTS-, Backend-Echtzeit-Sprache- und
Medienverständnis-Oberflächen.
Oberflächen für Bild, Video, Musik, Batch-TTS, Backend-Echtzeit-Sprache und
Medienverständnis.
</Accordion>
<Accordion title="OpenAI">
Bild-, Video-, Batch-TTS-, Batch-STT-, Voice Call-Streaming-STT-, Backend-
Echtzeit-Sprache- und Memory-Embedding-Oberflächen.
Oberflächen für Bild, Video, Batch-TTS, Batch-STT, Streaming-STT für Sprachanrufe, Backend-
Echtzeit-Sprache und Memory-Embedding.
</Accordion>
<Accordion title="DeepInfra">
Chat-/Modell-Routing, Bildgenerierung/-bearbeitung, Text-zu-Video, Batch-TTS,
Batch-STT, Bild-Medienverständnis und Memory-Embedding-Oberflächen.
DeepInfra-native Rerank-, Klassifizierungs- und Objekterkennungsmodelle werden nicht
Oberflächen für Chat-/Modell-Routing, Bildgenerierung/-bearbeitung, Text-zu-Video, Batch-TTS,
Batch-STT, Bild-Medienverständnis und Memory-Embedding.
DeepInfra-native Modelle für Reranking/Klassifikation/Objekterkennung werden nicht
registriert, bis OpenClaw dedizierte Provider-Verträge für diese
Kategorien hat.
</Accordion>
<Accordion title="xAI">
Bild, Video, Suche, Codeausführung, Batch-TTS, Batch-STT und Voice
Call-Streaming-STT. xAI Realtime Voice ist eine Upstream-Fähigkeit, wird aber
in OpenClaw nicht registriert, bis der gemeinsame Echtzeit-Sprachvertrag sie
abbilden kann.
Bild, Video, Suche, Codeausführung, Batch-TTS, Batch-STT und Streaming-STT für Sprachanrufe.
xAI Realtime Voice ist eine Upstream-Funktion, wird in OpenClaw aber
erst registriert, wenn der gemeinsame Vertrag für Echtzeit-Sprache sie
darstellen kann.
</Accordion>
</AccordionGroup>
## Verwandt
## Verwandte Themen
- [Bildgenerierung](/de/tools/image-generation)
- [Videogenerierung](/de/tools/video-generation)
- [Musikgenerierung](/de/tools/music-generation)
- [Text-to-Speech](/de/tools/tts)
- [Medienverständnis](/de/nodes/media-understanding)
- [Audioknoten](/de/nodes/audio)
- [Audio-Knoten](/de/nodes/audio)

200
docs/de/tools/music-generation.md
View File

@ -4,43 +4,44 @@ read_when:
- Musikgenerierungs-Provider und -Modelle konfigurieren
- Die Parameter des Tools music_generate verstehen
sidebarTitle: Music generation
summary: Musik über music_generate in Google Lyria-, MiniMax- und ComfyUI-Workflows generieren
summary: Musik über music_generate in Workflows für Google Lyria, MiniMax und ComfyUI generieren
title: Musikgenerierung
x-i18n:
generated_at: "2026-05-02T21:04:21Z"
generated_at: "2026-05-05T01:50:19Z"
model: gpt-5.5
provider: openai
source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
source_path: tools/music-generation.md
workflow: 16
---
Das Tool `music_generate` ermöglicht es dem Agent, Musik oder Audio über die
gemeinsame Musikgenerierungsfunktion mit konfigurierten Providern zu erstellen —
heute Google, MiniMax und per Workflow konfigurierte ComfyUI.
Das Tool `music_generate` ermöglicht dem Agent, Musik oder Audio über die
gemeinsame Musikgenerierungsfunktion mit konfigurierten Providern zu erstellen — derzeit Google,
MiniMax und per Workflow konfigurierte ComfyUI.
Für sitzungsbasierte Agent-Ausführungen startet OpenClaw die Musikgenerierung als
Hintergrundaufgabe, verfolgt sie im Task-Ledger und weckt den Agent erneut,
wenn der Track bereit ist, damit der Agent das fertige Audio wieder in den
ursprünglichen Kanal posten kann.
Bei sitzungsgestützten Agent-Ausführungen startet OpenClaw die Musikgenerierung als
Hintergrundaufgabe, verfolgt sie im Aufgabenprotokoll und weckt den Agent anschließend erneut,
wenn der Track bereit ist, damit der Agent den Benutzer informieren und das
fertige Audio anhängen kann. In Gruppen-/Kanal-Chats, die für sichtbare
Zustellung ausschließlich das Nachrichten-Tool verwenden, übermittelt der Agent das Ergebnis über das Nachrichten-Tool.
<Note>
Das integrierte gemeinsame Tool erscheint nur, wenn mindestens ein
Musikgenerierungs-Provider verfügbar ist. Wenn Sie `music_generate` nicht in den
Tools Ihres Agent sehen, konfigurieren Sie `agents.defaults.musicGenerationModel`
oder richten Sie einen Provider-API-Schlüssel ein.
Das integrierte gemeinsame Tool wird nur angezeigt, wenn mindestens ein Musikgenerierungs-
Provider verfügbar ist. Wenn Sie `music_generate` nicht in den Tools Ihres Agents sehen,
konfigurieren Sie `agents.defaults.musicGenerationModel` oder richten Sie einen
Provider-API-Schlüssel ein.
</Note>
## Schnellstart
<Tabs>
<Tab title="Shared provider-backed">
<Tab title="Gemeinsam, Provider-gestützt">
<Steps>
<Step title="Configure auth">
Legen Sie einen API-Schlüssel für mindestens einen Provider fest — zum
Beispiel `GEMINI_API_KEY` oder `MINIMAX_API_KEY`.
<Step title="Authentifizierung konfigurieren">
Legen Sie einen API-Schlüssel für mindestens einen Provider fest — zum Beispiel
`GEMINI_API_KEY` oder `MINIMAX_API_KEY`.
</Step>
<Step title="Pick a default model (optional)">
<Step title="Ein Standardmodell auswählen (optional)">
```json5
{
agents: {
@ -53,30 +54,30 @@ oder richten Sie einen Provider-API-Schlüssel ein.
}
```
</Step>
<Step title="Ask the agent">
_„Erzeuge einen schwungvollen Synthpop-Track über eine Nachtfahrt durch
eine Neonstadt.“_
<Step title="Den Agent fragen">
_"Generate an upbeat synthpop track about a night drive through a
neon city."_
Der Agent ruft `music_generate` automatisch auf. Es ist keine
Tool-Zulassungsliste erforderlich.
Tool-Allowlist erforderlich.
</Step>
</Steps>
Für direkte synchrone Kontexte ohne sitzungsbasierte Agent-Ausführung fällt
das integrierte Tool weiterhin auf Inline-Generierung zurück und gibt den
finalen Medienpfad im Tool-Ergebnis zurück.
Für direkte synchrone Kontexte ohne sitzungsgestützte Agent-Ausführung
fällt das integrierte Tool weiterhin auf Inline-Generierung zurück und gibt
den endgültigen Medienpfad im Tool-Ergebnis zurück.
</Tab>
<Tab title="ComfyUI workflow">
<Tab title="ComfyUI-Workflow">
<Steps>
<Step title="Configure the workflow">
Konfigurieren Sie `plugins.entries.comfy.config.music` mit einem Workflow-
JSON sowie Prompt- und Ausgabeknoten.
<Step title="Den Workflow konfigurieren">
Konfigurieren Sie `plugins.entries.comfy.config.music` mit einer Workflow-
JSON und Prompt-/Ausgabeknoten.
</Step>
<Step title="Cloud auth (optional)">
Legen Sie für Comfy Cloud `COMFY_API_KEY` oder `COMFY_CLOUD_API_KEY` fest.
<Step title="Cloud-Authentifizierung (optional)">
Für Comfy Cloud legen Sie `COMFY_API_KEY` oder `COMFY_CLOUD_API_KEY` fest.
</Step>
<Step title="Call the tool">
<Step title="Das Tool aufrufen">
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
@ -97,10 +98,10 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## Unterstützte Provider
| Provider | Standardmodell | Referenzeingaben | Unterstützte Steuerelemente | Authentifizierung |
| -------- | ---------------------- | ---------------- | -------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Bis zu 1 Bild | Workflow-definierte Musik oder Audio | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Bis zu 10 Bilder | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| Provider | Standardmodell | Referenzeingaben | Unterstützte Steuerungen | Authentifizierung |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Bis zu 1 Bild | Workflow-definierte Musik oder Audio | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Bis zu 10 Bilder | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Keine | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` oder MiniMax OAuth |
### Funktionsmatrix
@ -108,7 +109,7 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
Der explizite Modusvertrag, der von `music_generate`, Vertragstests und dem
gemeinsamen Live-Sweep verwendet wird:
| Provider | `generate` | `edit` | Bearbeitungslimit | Gemeinsame Live-Lanes |
| Provider | `generate` | `edit` | Bearbeitungslimit | Gemeinsame Live-Lanes |
| -------- | :--------: | :----: | ----------------- | ------------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 Bild | Nicht im gemeinsamen Sweep; abgedeckt durch `extensions/comfy/comfy.live.test.ts` |
| Google | ✓ | ✓ | 10 Bilder | `generate`, `edit` |
@ -121,8 +122,7 @@ Laufzeit zu prüfen:
/tool music_generate action=list
```
Verwenden Sie `action: "status"`, um die aktive sitzungsbasierte Musikaufgabe zu
prüfen:
Verwenden Sie `action: "status"`, um die aktive sitzungsgestützte Musikaufgabe zu prüfen:
```text
/tool music_generate action=status
@ -137,20 +137,20 @@ Beispiel für direkte Generierung:
## Tool-Parameter
<ParamField path="prompt" type="string" required>
Prompt zur Musikgenerierung. Erforderlich für `action: "generate"`.
Prompt für die Musikgenerierung. Erforderlich für `action: "generate"`.
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` gibt die aktuelle Sitzungsaufgabe zurück; `"list"` prüft Provider.
</ParamField>
<ParamField path="model" type="string">
Provider-/Modell-Überschreibung (z. B. `google/lyria-3-pro-preview`,
Provider-/Modell-Override (z. B. `google/lyria-3-pro-preview`,
`comfy/workflow`).
</ParamField>
<ParamField path="lyrics" type="string">
Optionale Liedtexte, wenn der Provider explizite Liedtexteingabe unterstützt.
Optionale Lyrics, wenn der Provider explizite Liedtexteingaben unterstützt.
</ParamField>
<ParamField path="instrumental" type="boolean">
Fordert eine rein instrumentale Ausgabe an, wenn der Provider dies unterstützt.
Instrumentale Ausgabe anfordern, wenn der Provider dies unterstützt.
</ParamField>
<ParamField path="image" type="string">
Einzelner Referenzbildpfad oder URL.
@ -162,52 +162,50 @@ Beispiel für direkte Generierung:
Zieldauer in Sekunden, wenn der Provider Dauerhinweise unterstützt.
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
Hinweis zum Ausgabeformat, wenn der Provider dies unterstützt.
Hinweis für das Ausgabeformat, wenn der Provider dies unterstützt.
</ParamField>
<ParamField path="filename" type="string">Hinweis zum Ausgabedateinamen.</ParamField>
<ParamField path="timeoutMs" type="number">Optionales Zeitlimit für Provider-Anfragen in Millisekunden. Werte unter 10000ms werden auf 10000ms angehoben und im Tool-Ergebnis gemeldet.</ParamField>
<ParamField path="filename" type="string">Hinweis für den Ausgabedateinamen.</ParamField>
<ParamField path="timeoutMs" type="number">Optionales Timeout für Provider-Anfragen in Millisekunden. Werte unter 10000ms werden auf 10000ms angehoben und im Tool-Ergebnis gemeldet.</ParamField>
<Note>
Nicht alle Provider unterstützen alle Parameter. OpenClaw validiert weiterhin
harte Grenzen wie Eingabeanzahlen vor der Übermittlung. Wenn ein Provider eine
Nicht alle Provider unterstützen alle Parameter. OpenClaw validiert dennoch harte
Grenzwerte wie Eingabeanzahlen vor der Übermittlung. Wenn ein Provider eine
Dauer unterstützt, aber ein kürzeres Maximum als den angeforderten Wert verwendet,
begrenzt OpenClaw auf die nächstliegende unterstützte Dauer. Wirklich nicht
unterstützte optionale Hinweise werden mit einer Warnung ignoriert, wenn der
ausgewählte Provider oder das ausgewählte Modell sie nicht erfüllen kann.
Tool-Ergebnisse melden die angewendeten Einstellungen; `details.normalization`
begrenzt OpenClaw auf die nächstliegende unterstützte Dauer. Tatsächlich nicht unterstützte optionale Hinweise
werden mit einer Warnung ignoriert, wenn der ausgewählte Provider oder das Modell
sie nicht berücksichtigen kann. Tool-Ergebnisse melden die angewendeten Einstellungen; `details.normalization`
erfasst jede Zuordnung von angefordert zu angewendet.
</Note>
## Asynchrones Verhalten
Sitzungsbasierte Musikgenerierung wird als Hintergrundaufgabe ausgeführt:
Sitzungsgestützte Musikgenerierung läuft als Hintergrundaufgabe:
- **Hintergrundaufgabe:** `music_generate` erstellt eine Hintergrundaufgabe,
gibt sofort eine gestartet-/Aufgaben-Antwort zurück und postet den fertigen
Track später in einer nachfolgenden Agent-Nachricht.
- **Vermeidung von Duplikaten:** Solange eine Aufgabe `queued` oder `running`
ist, geben spätere `music_generate`-Aufrufe in derselben Sitzung den
Aufgabenstatus zurück, anstatt eine weitere Generierung zu starten. Verwenden
Sie `action: "status"`, um explizit zu prüfen.
- **Hintergrundaufgabe:** `music_generate` erstellt eine Hintergrundaufgabe, gibt sofort eine
gestartete/Aufgaben-Antwort zurück und postet den fertigen Track später in
einer nachfolgenden Agent-Nachricht.
- **Duplikatvermeidung:** Während eine Aufgabe `queued` oder `running` ist, geben spätere
`music_generate`-Aufrufe in derselben Sitzung den Aufgabenstatus zurück, statt
eine weitere Generierung zu starten. Verwenden Sie `action: "status"` zur expliziten Prüfung.
- **Statusabfrage:** `openclaw tasks list` oder `openclaw tasks show <taskId>`
prüft wartende, laufende und terminale Status.
- **Abschluss-Wecken:** OpenClaw injiziert ein internes Abschlussereignis zurück
in dieselbe Sitzung, damit das Modell die nutzerseitige Folgenachricht selbst
schreiben kann.
- **Prompt-Hinweis:** Spätere Benutzer-/manuelle Turns in derselben Sitzung
erhalten einen kleinen Laufzeithinweis, wenn bereits eine Musikaufgabe läuft,
damit das Modell `music_generate` nicht blind erneut aufruft.
- **Fallback ohne Sitzung:** Direkte/lokale Kontexte ohne echte Agent-Sitzung
laufen inline und geben das finale Audioergebnis im selben Turn zurück.
- **Abschluss-Weckruf:** OpenClaw injiziert ein internes Abschlussereignis zurück
in dieselbe Sitzung, damit das Modell die benutzerseitige Folgeantwort
selbst schreiben kann.
- **Prompt-Hinweis:** Spätere Benutzer-/manuelle Turns in derselben Sitzung erhalten einen kleinen
Laufzeithinweis, wenn bereits eine Musikaufgabe läuft, damit das Modell
`music_generate` nicht blind erneut aufruft.
- **Fallback ohne Sitzung:** Direkte/lokale Kontexte ohne echte Agent-
Sitzung laufen inline und geben das endgültige Audioergebnis im selben Turn zurück.
### Aufgabenlebenszyklus
| Status | Bedeutung |
| Zustand | Bedeutung |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued` | Aufgabe erstellt, wartet darauf, dass der Provider sie annimmt. |
| `running` | Provider verarbeitet sie (typischerweise 30 Sekunden bis 3 Minuten, abhängig von Provider und Dauer). |
| `running` | Provider verarbeitet sie (typischerweise 30 Sekunden bis 3 Minuten, je nach Provider und Dauer). |
| `succeeded` | Track bereit; der Agent wacht auf und postet ihn in die Unterhaltung. |
| `failed` | Provider-Fehler oder Zeitlimit; der Agent wacht mit Fehlerdetails auf. |
| `failed` | Provider-Fehler oder Timeout; der Agent wacht mit Fehlerdetails auf. |
Status über die CLI prüfen:
@ -241,47 +239,45 @@ OpenClaw versucht Provider in dieser Reihenfolge:
1. `model`-Parameter aus dem Tool-Aufruf (wenn der Agent einen angibt).
2. `musicGenerationModel.primary` aus der Konfiguration.
3. `musicGenerationModel.fallbacks` der Reihe nach.
4. Automatische Erkennung nur anhand authentifizierungsbasierter Provider-Standards:
4. Automatische Erkennung ausschließlich über auth-gestützte Provider-Standards:
- aktueller Standard-Provider zuerst;
- übrige registrierte Musikgenerierungs-Provider in Provider-ID-Reihenfolge.
Wenn ein Provider fehlschlägt, wird der nächste Kandidat automatisch versucht.
Wenn alle fehlschlagen, enthält der Fehler Details zu jedem Versuch.
Wenn ein Provider fehlschlägt, wird automatisch der nächste Kandidat versucht. Wenn alle
fehlschlagen, enthält der Fehler Details aus jedem Versuch.
Setzen Sie `agents.defaults.mediaGenerationAutoProviderFallback: false`, um nur
explizite `model`-, `primary`- und `fallbacks`-Einträge zu verwenden.
explizite Einträge für `model`, `primary` und `fallbacks` zu verwenden.
## Provider-Hinweise
<AccordionGroup>
<Accordion title="ComfyUI">
Workflow-gesteuert und abhängig vom konfigurierten Graphen sowie der
Knotenzuordnung für Prompt-/Ausgabefelder. Das gebündelte `comfy`-Plugin
bindet sich über die Provider-Registry für Musikgenerierung in das gemeinsame
Tool `music_generate` ein.
Workflow-gesteuert und abhängig vom konfigurierten Graphen sowie der Knotenzuordnung
für Prompt-/Ausgabefelder. Das gebündelte `comfy`-Plugin bindet sich über die Musikgenerierungs-Provider-
Registry in das gemeinsame Tool `music_generate` ein.
</Accordion>
<Accordion title="Google (Lyria 3)">
Verwendet Lyria-3-Batch-Generierung. Der aktuelle gebündelte Flow unterstützt
Verwendet Lyria-3-Batch-Generierung. Der aktuelle gebündelte Ablauf unterstützt
Prompt, optionalen Liedtext und optionale Referenzbilder.
</Accordion>
<Accordion title="MiniMax">
Verwendet den Batch-Endpunkt `music_generation`. Unterstützt Prompt,
optionale Liedtexte, Instrumentalmodus, Dauersteuerung und mp3-Ausgabe über
entweder `minimax`-API-Schlüssel-Authentifizierung oder `minimax-portal` OAuth.
Verwendet den Batch-Endpunkt `music_generation`. Unterstützt Prompt, optionale
Lyrics, Instrumentalmodus, Dauersteuerung und MP3-Ausgabe über
entweder `minimax`-API-Key-Auth oder `minimax-portal` OAuth.
</Accordion>
</AccordionGroup>
## Den richtigen Pfad wählen
- **Shared provider-backed**, wenn Sie Modellauswahl, Provider-Failover und den
integrierten asynchronen Aufgaben-/Status-Flow möchten.
- **Plugin-Pfad (ComfyUI)**, wenn Sie einen benutzerdefinierten Workflow-Graphen
oder einen Provider benötigen, der nicht Teil der gemeinsamen gebündelten
Musikfunktion ist.
- **Gemeinsam, Provider-gestützt**, wenn Sie Modellauswahl, Provider-
Failover und den integrierten asynchronen Aufgaben-/Statusablauf wünschen.
- **Plugin-Pfad (ComfyUI)**, wenn Sie einen benutzerdefinierten Workflow-Graphen oder einen
Provider benötigen, der nicht Teil der gemeinsamen gebündelten Musikfunktion ist.
Wenn Sie ComfyUI-spezifisches Verhalten debuggen, siehe
[ComfyUI](/de/providers/comfy). Wenn Sie gemeinsames Provider-Verhalten debuggen,
beginnen Sie mit [Google (Gemini)](/de/providers/google) oder
[ComfyUI](/de/providers/comfy). Wenn Sie gemeinsames Provider-
Verhalten debuggen, beginnen Sie mit [Google (Gemini)](/de/providers/google) oder
[MiniMax](/de/providers/minimax).
## Provider-Funktionsmodi
@ -309,11 +305,10 @@ capabilities: {
}
```
Legacy-Flachfelder wie `maxInputImages`, `supportsLyrics` und
`supportsFormat` reichen **nicht** aus, um Bearbeitungsunterstützung zu
bewerben. Provider sollten `generate` und `edit` explizit deklarieren, damit
Live-Tests, Vertragstests und das gemeinsame Tool `music_generate` die
Modusunterstützung deterministisch validieren können.
Ältere flache Felder wie `maxInputImages`, `supportsLyrics` und
`supportsFormat` reichen **nicht** aus, um Bearbeitungsunterstützung zu bewerben. Provider
sollten `generate` und `edit` explizit deklarieren, damit Live-Tests, Vertragstests
und das gemeinsame Tool `music_generate` Modusunterstützung deterministisch validieren können.
## Live-Tests
@ -329,11 +324,10 @@ Repo-Wrapper:
pnpm test:live:media music
```
Diese Live-Datei lädt fehlende Provider-Umgebungsvariablen aus `~/.profile`,
bevorzugt standardmäßig Live-/Env-API-Schlüssel vor gespeicherten
Authentifizierungsprofilen und führt sowohl `generate`- als auch deklarierte
`edit`-Abdeckung aus, wenn der Provider den Bearbeitungsmodus aktiviert. Aktuelle
Abdeckung:
Diese Live-Datei lädt fehlende Provider-Umgebungsvariablen aus `~/.profile`, bevorzugt
standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen und führt sowohl
`generate` als auch deklarierte `edit`-Abdeckung aus, wenn der Provider den Bearbeitungsmodus
aktiviert. Aktuelle Abdeckung:
- `google`: `generate` plus `edit`
- `minimax`: nur `generate`
@ -345,12 +339,12 @@ Opt-in-Live-Abdeckung für den gebündelten ComfyUI-Musikpfad:
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
Die Comfy-Live-Datei behandelt auch Comfy-Bild- und Video-Workflows, wenn diese
Die Comfy-Live-Datei deckt außerdem Comfy-Bild- und Videoworkflows ab, wenn diese
Abschnitte konfiguriert sind.
## Verwandte Themen
- [Hintergrundaufgaben](/de/automation/tasks) — Aufgabenverfolgung für entkoppelte `music_generate`-Läufe
- [Hintergrundaufgaben](/de/automation/tasks) — Aufgabenverfolgung für losgelöste `music_generate`-Ausführungen
- [ComfyUI](/de/providers/comfy)
- [Konfigurationsreferenz](/de/gateway/config-agents#agent-defaults) — `musicGenerationModel`-Konfiguration
- [Google (Gemini)](/de/providers/google)

500
docs/de/tools/plugin.md
View File

@ -7,27 +7,27 @@ sidebarTitle: Install and Configure
summary: OpenClaw-Plugins installieren, konfigurieren und verwalten
title: Plugins
x-i18n:
generated_at: "2026-05-03T21:39:42Z"
generated_at: "2026-05-05T01:50:18Z"
model: gpt-5.5
provider: openai
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004
source_path: tools/plugin.md
workflow: 16
---
Plugins erweitern OpenClaw um neue Funktionen: Kanäle, Modell-Provider,
Agent-Harnesses, Tools, Skills, Sprache, Echtzeit-Transkription, Echtzeit-
Sprache, Medienverständnis, Bildgenerierung, Videogenerierung, Web-Abruf, Web-
Suche und mehr. Einige Plugins sind **core** (mit OpenClaw ausgeliefert), andere
sind **extern**. Die meisten externen Plugins werden über
[ClawHub](/de/tools/clawhub) veröffentlicht und gefunden. Npm bleibt für direkte Installationen und für eine
vorübergehende Gruppe von OpenClaw-eigenen Plugin-Paketen unterstützt, während
diese Migration abgeschlossen wird.
Sprache, Medienverständnis, Bildgenerierung, Videogenerierung, Webabruf, Web-
Suche und mehr. Einige Plugins sind **Kern-Plugins** (mit OpenClaw ausgeliefert),
andere sind **extern**. Die meisten externen Plugins werden über
[ClawHub](/de/tools/clawhub) veröffentlicht und gefunden. Npm bleibt für direkte
Installationen und für einen temporären Satz von OpenClaw-eigenen Plugin-
Paketen unterstützt, bis diese Migration abgeschlossen ist.
## Schnellstart
Beispiele zum Kopieren und Einfügen für Installation, Auflisten, Deinstallation,
Aktualisierung und Veröffentlichung finden Sie unter
Beispiele zum Kopieren und Einfügen für Installation, Auflistung,
Deinstallation, Aktualisierung und Veröffentlichung finden Sie unter
[Plugins verwalten](/de/plugins/manage-plugins).
<Steps>
@ -39,19 +39,19 @@ Aktualisierung und Veröffentlichung finden Sie unter
<Step title="Ein Plugin installieren">
```bash
# ClawHub-Plugins suchen
# Search ClawHub plugins
openclaw plugins search "calendar"
# Von ClawHub
# From ClawHub
openclaw plugins install clawhub:openclaw-codex-app-server
# Von npm
# From npm
openclaw plugins install npm:@acme/openclaw-plugin
# Von git
# From git
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
# Aus einem lokalen Verzeichnis oder Archiv
# From a local directory or archive
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```
@ -63,36 +63,40 @@ Aktualisierung und Veröffentlichung finden Sie unter
openclaw gateway restart
```
Konfigurieren Sie anschließend `plugins.entries.\<id\>.config` in Ihrer Konfigurationsdatei.
Konfigurieren Sie anschließend `plugins.entries.\<id\>.config` in Ihrer
Konfigurationsdatei.
</Step>
<Step title="Chat-native Verwaltung">
In einem laufenden Gateway lösen die nur für Owner verfügbaren Befehle `/plugins enable` und `/plugins disable`
den Konfigurations-Neulader des Gateway aus. Das Gateway lädt die Plugin-Runtime-
Oberflächen im Prozess neu, und neue Agent-Turns bauen ihre Tool-Liste aus der
aktualisierten Registry neu auf. `/plugins install` ändert Plugin-Quellcode, daher
fordert das Gateway einen Neustart an, statt vorzugeben, der aktuelle Prozess könne
bereits importierte Module sicher neu laden.
In einem laufenden Gateway lösen die nur für Besitzer verfügbaren Befehle
`/plugins enable` und `/plugins disable` den Konfigurations-Neulader des
Gateway aus. Das Gateway lädt Plugin-Laufzeitoberflächen im Prozess neu, und
neue Agent-Durchläufe bauen ihre Tool-Liste aus der aktualisierten Registry
neu auf. `/plugins install` ändert den Plugin-Quellcode, daher fordert das
Gateway einen Neustart an, statt vorzugeben, dass der aktuelle Prozess
bereits importierte Module sicher neu laden kann.
</Step>
<Step title="Plugin verifizieren">
<Step title="Plugin überprüfen">
```bash
openclaw plugins inspect <plugin-id> --runtime --json
# Wenn das Plugin einen CLI-Root registriert hat, führen Sie einen Befehl aus diesem Root aus.
# If the plugin registered a CLI root, run one command from that root.
openclaw <plugin-command> --help
```
Verwenden Sie `--runtime`, wenn Sie registrierte Tools, Dienste, Gateway-
Methoden, Hooks oder Plugin-eigene CLI-Befehle nachweisen müssen. Reines
`inspect` ist eine kalte Manifest-/Registry-Prüfung und vermeidet bewusst den Import der Plugin-Runtime.
Methoden, Hooks oder Plugin-eigene CLI-Befehle nachweisen müssen. Ein
einfaches `inspect` ist eine kalte Manifest-/Registry-Prüfung und vermeidet
absichtlich den Import der Plugin-Laufzeit.
</Step>
</Steps>
Wenn Sie chat-native Steuerung bevorzugen, aktivieren Sie `commands.plugins: true` und verwenden Sie:
Wenn Sie chat-native Steuerung bevorzugen, aktivieren Sie `commands.plugins: true`
und verwenden Sie:
```text
/plugin install clawhub:<package>
@ -100,84 +104,97 @@ Wenn Sie chat-native Steuerung bevorzugen, aktivieren Sie `commands.plugins: tru
/plugin enable <plugin-id>
```
Der Installationspfad verwendet denselben Resolver wie die CLI: lokaler Pfad/Archiv, explizites
`clawhub:<pkg>`, explizites `npm:<pkg>`, explizites `git:<repo>` oder eine einfache Paketspezifikation
über npm.
Der Installationspfad verwendet denselben Resolver wie die CLI: lokalen
Pfad/Archiv, explizites `clawhub:<pkg>`, explizites `npm:<pkg>`, explizites
`git:<repo>` oder eine reine Paketspezifikation über npm.
Wenn die Konfiguration ungültig ist, schlägt die Installation normalerweise geschlossen fehl und verweist Sie auf
`openclaw doctor --fix`. Die einzige Wiederherstellungsausnahme ist ein enger Neuinstallationspfad für gebündelte Plugins
für Plugins, die sich für
`openclaw.install.allowInvalidConfigRecovery` entscheiden.
Während des Gateway-Starts schlägt ungültige Plugin-Konfiguration wie jede andere ungültige
Konfiguration geschlossen fehl. Führen Sie `openclaw doctor --fix` aus, um die fehlerhafte Plugin-Konfiguration zu quarantänisieren, indem
dieser Plugin-Eintrag deaktiviert und seine ungültige Konfigurationsnutzlast entfernt wird; das normale
Konfigurations-Backup behält die vorherigen Werte.
Wenn eine Kanalkonfiguration auf ein Plugin verweist, das nicht mehr auffindbar ist, aber dieselbe veraltete Plugin-ID in der Plugin-Konfiguration oder in Installationsdatensätzen verbleibt, protokolliert der Gateway-Start
Wenn die Konfiguration ungültig ist, schlägt die Installation normalerweise
geschlossen fehl und verweist Sie auf `openclaw doctor --fix`. Die einzige
Wiederherstellungsausnahme ist ein enger Neuinstallationspfad für gebündelte
Plugins, die sich für `openclaw.install.allowInvalidConfigRecovery` entscheiden.
Während des Gateway-Starts schlägt ungültige Plugin-Konfiguration geschlossen
fehl wie jede andere ungültige Konfiguration. Führen Sie `openclaw doctor --fix`
aus, um die fehlerhafte Plugin-Konfiguration zu isolieren, indem dieser Plugin-
Eintrag deaktiviert und seine ungültige Konfigurationsnutzlast entfernt wird; die
normale Konfigurationssicherung behält die vorherigen Werte.
Wenn eine Kanalkonfiguration auf ein Plugin verweist, das nicht mehr auffindbar
ist, dieselbe veraltete Plugin-ID aber weiterhin in der Plugin-Konfiguration oder
in Installationsdatensätzen vorhanden ist, protokolliert der Gateway-Start
Warnungen und überspringt diesen Kanal, statt jeden anderen Kanal zu blockieren.
Führen Sie `openclaw doctor --fix` aus, um die veralteten Kanal-/Plugin-Einträge zu entfernen; unbekannte
Kanalschlüssel ohne Nachweis eines veralteten Plugins schlagen weiterhin bei der Validierung fehl, damit Tippfehler
sichtbar bleiben.
Wenn `plugins.enabled: false` gesetzt ist, werden veraltete Plugin-Verweise als inaktiv behandelt:
Der Gateway-Start überspringt Plugin-Erkennung/-Laden und `openclaw doctor` behält
die deaktivierte Plugin-Konfiguration bei, statt sie automatisch zu entfernen. Aktivieren Sie Plugins wieder, bevor
Sie die Doctor-Bereinigung ausführen, wenn veraltete Plugin-IDs entfernt werden sollen.
Führen Sie `openclaw doctor --fix` aus, um die veralteten Kanal-/Plugin-Einträge
zu entfernen; unbekannte Kanalschlüssel ohne Nachweis eines veralteten Plugins
schlagen weiterhin bei der Validierung fehl, damit Tippfehler sichtbar bleiben.
Wenn `plugins.enabled: false` gesetzt ist, werden veraltete Plugin-Verweise als
inaktiv behandelt: Der Gateway-Start überspringt Plugin-Erkennung und -Laden, und
`openclaw doctor` behält die deaktivierte Plugin-Konfiguration bei, statt sie
automatisch zu entfernen. Aktivieren Sie Plugins wieder, bevor Sie die Doctor-
Bereinigung ausführen, wenn Sie veraltete Plugin-IDs entfernen möchten.
Die Installation von Plugin-Abhängigkeiten erfolgt nur während expliziter Installations-/Update- oder
Doctor-Reparaturabläufe. Gateway-Start, Konfigurations-Neuladen und Runtime-Inspektion
führen keine Paketmanager aus und reparieren keine Abhängigkeitsbäume. Lokale Plugins müssen ihre
Abhängigkeiten bereits installiert haben, während npm-, git- und ClawHub-Plugins
unter den von OpenClaw verwalteten Plugin-Roots installiert werden. npm-Abhängigkeiten können
innerhalb von OpenClaws verwaltetem npm-Root gehoistet werden; Installation/Update durchsucht diesen verwalteten Root vor
Vertrauen, und Deinstallation entfernt npm-verwaltete Pakete über npm. Externe Plugins
und benutzerdefinierte Ladepfade müssen weiterhin über `openclaw plugins install` installiert werden.
Verwenden Sie `openclaw plugins list --json`, um den statischen `dependencyStatus` für jedes
sichtbare Plugin zu sehen, ohne Runtime-Code zu importieren oder Abhängigkeiten zu reparieren.
Siehe [Plugin-Abhängigkeitsauflösung](/de/plugins/dependency-resolution) für den
Installationszeit-Lebenszyklus.
Die Installation von Plugin-Abhängigkeiten erfolgt nur während expliziter
Installations-/Aktualisierungs- oder Doctor-Reparaturabläufe. Gateway-Start,
Konfigurationsneuladen und Laufzeitinspektion führen keine Paketmanager aus und
reparieren keine Abhängigkeitsbäume. Lokale Plugins müssen ihre Abhängigkeiten
bereits installiert haben, während npm-, git- und ClawHub-Plugins unter den von
OpenClaw verwalteten Plugin-Roots installiert werden. npm-Abhängigkeiten können
innerhalb des von OpenClaw verwalteten npm-Roots gehoistet werden; Installation/
Aktualisierung scannt diesen verwalteten Root vor der Vertrauensentscheidung, und
die Deinstallation entfernt npm-verwaltete Pakete über npm. Externe Plugins und
benutzerdefinierte Ladepfade müssen weiterhin über `openclaw plugins install`
installiert werden. Verwenden Sie `openclaw plugins list --json`, um den
statischen `dependencyStatus` für jedes sichtbare Plugin zu sehen, ohne
Laufzeitcode zu importieren oder Abhängigkeiten zu reparieren.
Weitere Informationen zum Installationszeit-Lebenszyklus finden Sie unter
[Auflösung von Plugin-Abhängigkeiten](/de/plugins/dependency-resolution).
Bei npm-Installationen werden veränderliche Selektoren wie `latest` oder ein dist-tag
vor der Installation aufgelöst und anschließend auf die exakt verifizierte Version in OpenClaws
verwaltetem npm-Root gepinnt. Nachdem npm abgeschlossen ist, verifiziert OpenClaw, dass der installierte
`package-lock.json`-Eintrag weiterhin zur aufgelösten Version und Integrität passt. Wenn
npm andere Paketmetadaten schreibt, schlägt die Installation fehl und das verwaltete Paket
Bei npm-Installationen werden veränderliche Selektoren wie `latest` oder ein
Dist-Tag vor der Installation aufgelöst und dann auf die exakte verifizierte
Version im von OpenClaw verwalteten npm-Root festgelegt. Nachdem npm abgeschlossen
ist, überprüft OpenClaw, dass der installierte `package-lock.json`-Eintrag
weiterhin der aufgelösten Version und Integrität entspricht. Wenn npm andere
Paketmetadaten schreibt, schlägt die Installation fehl und das verwaltete Paket
wird zurückgesetzt, statt ein anderes Plugin-Artefakt zu akzeptieren.
Source-Checkouts sind pnpm-Workspaces. Wenn Sie OpenClaw klonen, um an gebündelten
Plugins zu arbeiten, führen Sie `pnpm install` aus; OpenClaw lädt gebündelte Plugins dann aus
`extensions/<id>`, sodass Änderungen und paketlokale Abhängigkeiten direkt verwendet werden.
Reine npm-Root-Installationen sind für paketiertes OpenClaw gedacht, nicht für die Entwicklung in
Source-Checkouts.
Quellcode-Checkouts sind pnpm-Workspaces. Wenn Sie OpenClaw klonen, um an
gebündelten Plugins zu arbeiten, führen Sie `pnpm install` aus; OpenClaw lädt
gebündelte Plugins dann aus `extensions/<id>`, sodass Änderungen und
paketlokale Abhängigkeiten direkt verwendet werden. Einfache npm-Root-
Installationen sind für paketiertes OpenClaw gedacht, nicht für die Entwicklung
in Quellcode-Checkouts.
## Plugin-Typen
OpenClaw erkennt zwei Plugin-Formate:
| Format | Funktionsweise | Beispiele |
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + Runtime-Modul; wird im Prozess ausgeführt | Offizielle Plugins, Community-npm-Pakete |
| **Bundle** | Codex-/Claude-/Cursor-kompatibles Layout; wird OpenClaw-Funktionen zugeordnet | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| Format | Funktionsweise | Beispiele |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + Laufzeitmodul; wird im Prozess ausgeführt | Offizielle Plugins, Community-npm-Pakete |
| **Bundle** | Codex-/Claude-/Cursor-kompatibles Layout; auf OpenClaw-Funktionen abgebildet | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Beide erscheinen unter `openclaw plugins list`. Siehe [Plugin-Bundles](/de/plugins/bundles) für Bundle-Details.
Beide erscheinen unter `openclaw plugins list`. Details zu Bundles finden Sie unter [Plugin-Bundles](/de/plugins/bundles).
Wenn Sie ein natives Plugin schreiben, beginnen Sie mit [Plugins erstellen](/de/plugins/building-plugins)
und der [Plugin-SDK-Übersicht](/de/plugins/sdk-overview).
## Paket-Einstiegspunkte
Native Plugin-npm-Pakete müssen `openclaw.extensions` in `package.json` deklarieren.
Jeder Eintrag muss innerhalb des Paketverzeichnisses bleiben und zu einer lesbaren
Runtime-Datei auflösen oder zu einer TypeScript-Quelldatei mit einem abgeleiteten gebauten JavaScript-
Pendant wie `src/index.ts` zu `dist/index.js`.
Paketierte Installationen müssen diese JavaScript-Runtime-Ausgabe ausliefern. Der TypeScript-
Quell-Fallback ist für Source-Checkouts und lokale Entwicklungspfade gedacht, nicht für
npm-Pakete, die in OpenClaws verwaltetem Plugin-Root installiert werden.
Native Plugin-npm-Pakete müssen `openclaw.extensions` in `package.json`
deklarieren. Jeder Eintrag muss innerhalb des Paketverzeichnisses bleiben und zu
einer lesbaren Laufzeitdatei auflösen oder zu einer TypeScript-Quelldatei mit
einem abgeleiteten gebauten JavaScript-Peer, etwa `src/index.ts` zu
`dist/index.js`.
Paketierte Installationen müssen diese JavaScript-Laufzeitausgabe enthalten. Der
TypeScript-Quellfallback ist für Quellcode-Checkouts und lokale Entwicklungspfade
gedacht, nicht für npm-Pakete, die in den von OpenClaw verwalteten Plugin-Root
installiert werden.
Verwenden Sie `openclaw.runtimeExtensions`, wenn veröffentlichte Runtime-Dateien nicht an denselben
Pfaden wie die Quelleinträge liegen. Wenn vorhanden, muss `runtimeExtensions`
genau einen Eintrag für jeden `extensions`-Eintrag enthalten. Nicht übereinstimmende Listen lassen Installation und
Plugin-Erkennung fehlschlagen, statt stillschweigend auf Quellpfade zurückzufallen. Wenn Sie außerdem
`openclaw.setupEntry` veröffentlichen, verwenden Sie `openclaw.runtimeSetupEntry` für dessen gebautes
JavaScript-Pendant; diese Datei ist erforderlich, wenn sie deklariert wird.
Verwenden Sie `openclaw.runtimeExtensions`, wenn veröffentlichte Laufzeitdateien
nicht unter denselben Pfaden liegen wie die Quelleinträge. Wenn vorhanden, muss
`runtimeExtensions` genau einen Eintrag für jeden `extensions`-Eintrag enthalten.
Nicht übereinstimmende Listen lassen Installation und Plugin-Erkennung
fehlschlagen, statt stillschweigend auf Quellpfade zurückzufallen. Wenn Sie auch
`openclaw.setupEntry` veröffentlichen, verwenden Sie `openclaw.runtimeSetupEntry`
für den gebauten JavaScript-Peer; diese Datei ist erforderlich, wenn sie
deklariert wird.
```json
{
@ -193,15 +210,17 @@ JavaScript-Pendant; diese Datei ist erforderlich, wenn sie deklariert wird.
### OpenClaw-eigene npm-Pakete während der Migration
ClawHub ist der primäre Verteilungsweg für die meisten Plugins. Aktuelle paketierte
OpenClaw-Releases bündeln bereits viele offizielle Plugins, daher benötigen diese in normalen Setups
keine separaten npm-Installationen. Bis jedes OpenClaw-eigene Plugin zu
ClawHub migriert ist, liefert OpenClaw weiterhin einige `@openclaw/*`-Plugin-Pakete auf
npm für ältere/benutzerdefinierte Installationen und direkte npm-Workflows aus.
ClawHub ist der primäre Verteilungsweg für die meisten Plugins. Aktuelle
paketierte OpenClaw-Releases bündeln bereits viele offizielle Plugins, sodass
diese in normalen Setups keine separaten npm-Installationen benötigen. Bis jedes
OpenClaw-eigene Plugin zu ClawHub migriert ist, liefert OpenClaw weiterhin einige
`@openclaw/*`-Plugin-Pakete auf npm für ältere/benutzerdefinierte Installationen
und direkte npm-Workflows aus.
Wenn npm ein `@openclaw/*`-Plugin-Paket als veraltet meldet, stammt diese Paketversion
aus einem älteren externen Paketzweig. Verwenden Sie das gebündelte Plugin aus
aktuellem OpenClaw oder einen lokalen Checkout, bis ein neueres npm-Paket veröffentlicht wird.
Wenn npm ein `@openclaw/*`-Plugin-Paket als veraltet meldet, stammt diese
Paketversion aus einer älteren externen Paketlinie. Verwenden Sie das gebündelte
Plugin aus dem aktuellen OpenClaw oder einen lokalen Checkout, bis ein neueres
npm-Paket veröffentlicht wird.
| Plugin | Paket | Dokumentation |
| --------------- | -------------------------- | ------------------------------------------ |
@ -219,7 +238,7 @@ aktuellem OpenClaw oder einen lokalen Checkout, bis ein neueres npm-Paket veröf
| Zalo | `@openclaw/zalo` | [Zalo](/de/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/de/plugins/zalouser) |
### Core (mit OpenClaw ausgeliefert)
### Kern (mit OpenClaw ausgeliefert)
<AccordionGroup>
<Accordion title="Modell-Provider (standardmäßig aktiviert)">
@ -231,11 +250,12 @@ aktuellem OpenClaw oder einen lokalen Checkout, bis ein neueres npm-Paket veröf
</Accordion>
<Accordion title="Memory-Plugins">
- `memory-core` — gebündelte Speichersuche (Standard über `plugins.slots.memory`)
- `memory-core` — gebündelte Memory-Suche (standardmäßig über `plugins.slots.memory`)
- `memory-lancedb` — LanceDB-gestütztes Langzeitgedächtnis mit automatischem Abruf/Erfassen (setzen Sie `plugins.slots.memory = "memory-lancedb"`)
Siehe [Memory LanceDB](/de/plugins/memory-lancedb) für OpenAI-kompatible
Embedding-Einrichtung, Ollama-Beispiele, Abruflimits und Fehlerbehebung.
Informationen zur OpenAI-kompatiblen Embedding-Einrichtung, zu Ollama-
Beispielen, Abruflimits und Fehlerbehebung finden Sie unter
[Memory LanceDB](/de/plugins/memory-lancedb).
</Accordion>
@ -243,8 +263,8 @@ aktuellem OpenClaw oder einen lokalen Checkout, bis ein neueres npm-Paket veröf
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="Sonstige">
- `browser` — gebündeltes Browser-Plugin für das Browser-Tool, die `openclaw browser`-CLI, die Gateway-Methode `browser.request`, die Browser-Runtime und den standardmäßigen Browser-Steuerungsdienst (standardmäßig aktiviert; vor dem Ersetzen deaktivieren)
<Accordion title="Sonstiges">
- `browser` — gebündeltes Browser-Plugin für das Browser-Tool, die `openclaw browser`-CLI, die Gateway-Methode `browser.request`, die Browser-Laufzeit und den standardmäßigen Browser-Steuerungsdienst (standardmäßig aktiviert; vor dem Ersetzen deaktivieren)
- `copilot-proxy` — VS Code Copilot Proxy-Bridge (standardmäßig deaktiviert)
</Accordion>
@ -268,105 +288,113 @@ Suchen Sie Drittanbieter-Plugins? Siehe [Community-Plugins](/de/plugins/communit
}
```
| Feld | Beschreibung |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Hauptschalter (Standard: `true`) |
| `allow` | Plugin-Allowlist (optional) |
| `deny` | Plugin-Denylist (optional; Deny hat Vorrang) |
| `load.paths` | Zusätzliche Plugin-Dateien/-Verzeichnisse |
| `slots` | Exklusive Slot-Selektoren (z. B. `memory`, `contextEngine`) |
| `entries.\<id\>` | Schalter pro Plugin + Konfiguration |
| Feld | Beschreibung |
| ------------------ | ------------------------------------------------------------- |
| `enabled` | Hauptschalter (Standard: `true`) |
| `allow` | Plugin-Zulassungsliste (optional) |
| `bundledDiscovery` | Erkennungsmodus für gebündelte Plugins (standardmäßig `allowlist`) |
| `deny` | Plugin-Sperrliste (optional; Sperren hat Vorrang) |
| `load.paths` | Zusätzliche Plugin-Dateien/-Verzeichnisse |
| `slots` | Exklusive Slot-Auswahlen (z. B. `memory`, `contextEngine`) |
| `entries.\<id\>` | Schalter und Konfiguration pro Plugin |
`plugins.allow` ist exklusiv. Wenn sie nicht leer ist, können nur aufgelistete Plugins geladen werden
oder Tools verfügbar machen, selbst wenn `tools.allow` `"*"` oder einen bestimmten Plugin-eigenen
Tool-Namen enthält. Wenn eine Tool-Allowlist auf Plugin-Tools verweist, fügen Sie die zugehörigen Plugin-IDs
`plugins.allow` ist exklusiv. Wenn es nicht leer ist, können nur aufgeführte Plugins geladen werden
oder Tools bereitstellen, selbst wenn `tools.allow` `"*"` oder einen bestimmten Plugin-eigenen
Tool-Namen enthält. Wenn eine Tool-Zulassungsliste auf Plugin-Tools verweist, fügen Sie die besitzenden Plugin-IDs
zu `plugins.allow` hinzu oder entfernen Sie `plugins.allow`; `openclaw doctor` warnt vor dieser
Form.
`plugins.bundledDiscovery` ist bei neuen Konfigurationen standardmäßig `"allowlist"`, sodass ein
restriktives `plugins.allow`-Inventar auch ausgelassene gebündelte Provider-Plugins blockiert,
einschließlich der Laufzeit-Erkennung von Websuche-Providern. Doctor versieht ältere
restriktive Allowlist-Konfigurationen während der Migration mit `"compat"`, damit Upgrades das
bisherige Verhalten gebündelter Provider beibehalten, bis der Operator den strengeren Modus aktiviert.
Ein leeres `plugins.allow` wird weiterhin als nicht gesetzt/offen behandelt.
Konfigurationsänderungen über `/plugins enable` oder `/plugins disable` lösen ein
In-Process-Neuladen der Gateway-Plugins aus. Neue Agent-Turns erstellen ihre Tool-Liste aus der
aktualisierten Plugin-Registry neu. Quellcodeändernde Vorgänge wie Installieren,
Aktualisieren und Deinstallieren starten den Gateway-Prozess weiterhin neu, da bereits importierte
Plugin-Module nicht sicher direkt ersetzt werden können.
prozessinternes Neuladen der Gateway-Plugins aus. Neue Agent-Turns erstellen ihre Tool-Liste aus
der aktualisierten Plugin-Registry neu. Quellenändernde Vorgänge wie Installation,
Update und Deinstallation starten den Gateway-Prozess weiterhin neu, da bereits importierte
Plugin-Module nicht sicher im laufenden Prozess ersetzt werden können.
`openclaw plugins list` ist ein lokaler Snapshot der Plugin-Registry/-Konfiguration. Ein dort
`enabled` Plugin bedeutet, dass die persistierte Registry und die aktuelle Konfiguration dem
Plugin die Teilnahme erlauben. Es beweist nicht, dass ein bereits laufender Remote-Gateway
neu geladen oder in denselben Plugin-Code neu gestartet wurde. Senden Sie bei VPS-/Container-Setups
mit Wrapper-Prozessen Neustarts oder schreibende Vorgänge, die ein Neuladen auslösen, an den tatsächlichen
`openclaw gateway run`-Prozess, oder verwenden Sie `openclaw gateway restart` gegen den
laufenden Gateway, wenn das Neuladen einen Fehler meldet.
`openclaw plugins list` ist ein lokaler Snapshot der Plugin-Registry/-Konfiguration. Ein dort als
`enabled` markiertes Plugin bedeutet, dass die persistierte Registry und die aktuelle Konfiguration dem
Plugin die Teilnahme erlauben. Es beweist nicht, dass ein bereits laufendes entferntes Gateway
mit demselben Plugin-Code neu geladen oder neu gestartet wurde. In VPS-/Container-Setups
mit Wrapper-Prozessen senden Sie Neustarts oder Reload-auslösende Schreibvorgänge an den tatsächlichen
`openclaw gateway run`-Prozess, oder verwenden Sie `openclaw gateway restart` für das
laufende Gateway, wenn das Neuladen einen Fehler meldet.
<Accordion title="Plugin-Zustände: deaktiviert vs. fehlend vs. ungültig">
- **Deaktiviert**: Plugin existiert, aber Aktivierungsregeln haben es ausgeschaltet. Die Konfiguration bleibt erhalten.
- **Fehlend**: Die Konfiguration verweist auf eine Plugin-ID, die die Discovery nicht gefunden hat.
- **Ungültig**: Plugin existiert, aber seine Konfiguration entspricht nicht dem deklarierten Schema. Der Gateway-Start überspringt nur dieses Plugin; `openclaw doctor --fix` kann den ungültigen Eintrag quarantänisieren, indem er ihn deaktiviert und seine Konfigurationsnutzlast entfernt.
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **Deaktiviert**: Plugin ist vorhanden, wurde aber durch Aktivierungsregeln abgeschaltet. Die Konfiguration bleibt erhalten.
- **Fehlend**: Die Konfiguration verweist auf eine Plugin-ID, die bei der Erkennung nicht gefunden wurde.
- **Ungültig**: Plugin ist vorhanden, aber seine Konfiguration entspricht nicht dem deklarierten Schema. Der Gateway-Start überspringt nur dieses Plugin; `openclaw doctor --fix` kann den ungültigen Eintrag quarantänisieren, indem es ihn deaktiviert und seine Konfigurationsnutzlast entfernt.
</Accordion>
## Discovery und Priorität
## Erkennung und Vorrang
OpenClaw sucht nach Plugins in dieser Reihenfolge (erster Treffer gewinnt):
OpenClaw sucht Plugins in dieser Reihenfolge (erster Treffer gewinnt):
<Steps>
<Step title="Konfigurationspfade">
`plugins.load.paths` — explizite Datei- oder Verzeichnispfade. Pfade, die auf
OpenClaws eigene paketierte gebündelte Plugin-Verzeichnisse zurückzeigen, werden ignoriert;
führen Sie `openclaw doctor --fix` aus, um diese veralteten Aliase zu entfernen.
<Step title="Config paths">
`plugins.load.paths` — explizite Datei- oder Verzeichnispfade. Pfade, die
zurück auf OpenClaws eigene paketierte gebündelte Plugin-Verzeichnisse zeigen, werden ignoriert;
führen Sie `openclaw doctor --fix` aus, um diese veralteten Aliasse zu entfernen.
</Step>
<Step title="Workspace-Plugins">
<Step title="Workspace plugins">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` und `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Globale Plugins">
<Step title="Global plugins">
`~/.openclaw/<plugin-root>/*.ts` und `~/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Gebündelte Plugins">
<Step title="Bundled plugins">
Mit OpenClaw ausgeliefert. Viele sind standardmäßig aktiviert (Modell-Provider, Sprache).
Andere erfordern explizite Aktivierung.
Andere müssen explizit aktiviert werden.
</Step>
</Steps>
Paketierte Installationen und Docker-Images lösen gebündelte Plugins normalerweise aus dem
kompilierten `dist/extensions`-Baum auf. Wenn ein Quellverzeichnis eines gebündelten Plugins
per Bind-Mount über den passenden paketierten Quellpfad gelegt wird, zum Beispiel
`/app/extensions/synology-chat`, behandelt OpenClaw dieses gemountete Quellverzeichnis
als gebündeltes Quell-Overlay und entdeckt es vor dem paketierten
`/app/dist/extensions/synology-chat`-Bundle. Dadurch funktionieren Maintainer-Container-Loops
weiter, ohne jedes gebündelte Plugin zurück auf TypeScript-Quellcode umzustellen.
Setzen Sie `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, um paketierte Dist-Bundles
zu erzwingen, selbst wenn Quell-Overlay-Mounts vorhanden sind.
`/app/extensions/synology-chat`, behandelt OpenClaw dieses eingehängte Quellverzeichnis
als gebündeltes Quell-Overlay und erkennt es vor dem paketierten
`/app/dist/extensions/synology-chat`-Bundle. Dadurch funktionieren Maintainer-Container-Loops,
ohne jedes gebündelte Plugin wieder auf TypeScript-Quellen umzustellen.
Setzen Sie `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, um paketierte Dist-Bundles zu erzwingen,
selbst wenn Quell-Overlay-Mounts vorhanden sind.
### Aktivierungsregeln
- `plugins.enabled: false` deaktiviert alle Plugins und überspringt Plugin-Discovery/-Ladevorgänge
- `plugins.enabled: false` deaktiviert alle Plugins und überspringt die Plugin-Erkennung/-Ladearbeit
- `plugins.deny` hat immer Vorrang vor allow
- `plugins.entries.\<id\>.enabled: false` deaktiviert dieses Plugin
- Plugins aus dem Workspace sind **standardmäßig deaktiviert** (müssen explizit aktiviert werden)
- Gebündelte Plugins folgen dem integrierten standardmäßig aktivierten Satz, sofern nicht überschrieben
- Gebündelte Plugins folgen dem integrierten standardmäßig-aktiviert-Satz, sofern nicht überschrieben
- Exklusive Slots können das ausgewählte Plugin für diesen Slot zwangsaktivieren
- Einige gebündelte Opt-in-Plugins werden automatisch aktiviert, wenn die Konfiguration eine
Plugin-eigene Oberfläche benennt, etwa eine Provider-Modellreferenz, Channel-Konfiguration oder Harness-
Runtime
Plugin-eigene Oberfläche benennt, etwa eine Provider-Modellreferenz, Kanalkonfiguration oder Harness-
Laufzeit
- Veraltete Plugin-Konfiguration bleibt erhalten, solange `plugins.enabled: false` aktiv ist;
aktivieren Sie Plugins wieder, bevor Sie die Doctor-Bereinigung ausführen, wenn veraltete IDs entfernt werden sollen
- OpenAI-Familie-Codex-Routen behalten getrennte Plugin-Grenzen bei:
aktivieren Sie Plugins erneut, bevor Sie die Doctor-Bereinigung ausführen, wenn veraltete IDs entfernt werden sollen
- OpenAI-Familien-Codex-Routen behalten getrennte Plugin-Grenzen:
`openai-codex/*` gehört zum OpenAI-Plugin, während das gebündelte Codex-
App-Server-Plugin durch `agentRuntime.id: "codex"` oder Legacy-
App-Server-Plugin durch `agentRuntime.id: "codex"` oder ältere
`codex/*`-Modellreferenzen ausgewählt wird
## Fehlerbehebung für Runtime-Hooks
## Fehlerbehebung bei Laufzeit-Hooks
Wenn ein Plugin in `plugins list` erscheint, aber `register(api)`-Seiteneffekte oder Hooks
Wenn ein Plugin in `plugins list` erscheint, aber `register(api)`-Nebeneffekte oder Hooks
im Live-Chat-Verkehr nicht ausgeführt werden, prüfen Sie zuerst Folgendes:
- Führen Sie `openclaw gateway status --deep --require-rpc` aus und bestätigen Sie, dass die aktive
Gateway-URL, das Profil, der Konfigurationspfad und der Prozess diejenigen sind, die Sie bearbeiten.
- Starten Sie den Live-Gateway nach Plugin-Installations-, Konfigurations- oder Codeänderungen neu. In Wrapper-
- Starten Sie das Live-Gateway nach Änderungen an Plugin-Installation, Konfiguration oder Code neu. In Wrapper-
Containern ist PID 1 möglicherweise nur ein Supervisor; starten Sie den untergeordneten
`openclaw gateway run`-Prozess neu oder senden Sie ihm ein Signal.
`openclaw gateway run`-Prozess neu oder signalisieren Sie ihn.
- Verwenden Sie `openclaw plugins inspect <id> --runtime --json`, um Hook-Registrierungen und
Diagnosen zu bestätigen. Nicht gebündelte Conversation-Hooks wie `llm_input`,
`llm_output`, `before_agent_finalize` und `agent_end` benötigen
@ -374,13 +402,13 @@ im Live-Chat-Verkehr nicht ausgeführt werden, prüfen Sie zuerst Folgendes:
- Für Modellwechsel bevorzugen Sie `before_model_resolve`. Es läuft vor der Modell-
Auflösung für Agent-Turns; `llm_output` läuft erst, nachdem ein Modellversuch
Assistant-Ausgabe erzeugt hat.
- Als Nachweis des effektiven Sitzungsmodells verwenden Sie `openclaw sessions` oder die
Gateway-Sitzungs-/Statusoberflächen und starten beim Debuggen von Provider-Payloads den
Gateway mit `--raw-stream --raw-stream-path <path>`.
- Als Nachweis für das effektive Sitzungsmodell verwenden Sie `openclaw sessions` oder die
Gateway-Sitzungs-/Statusoberflächen und starten Sie beim Debuggen von Provider-Nutzlasten
das Gateway mit `--raw-stream --raw-stream-path <path>`.
### Langsame Einrichtung von Plugin-Tools
Wenn Agent-Turns beim Vorbereiten von Tools zu stocken scheinen, aktivieren Sie Trace-Logging und
Wenn Agent-Turns beim Vorbereiten von Tools zu hängen scheinen, aktivieren Sie Trace-Logging und
prüfen Sie auf Timing-Zeilen der Plugin-Tool-Factory:
```bash
@ -394,18 +422,18 @@ Suchen Sie nach:
[trace:plugin-tools] factory timings ...
```
Die Zusammenfassung listet die gesamte Factory-Zeit und die langsamsten Plugin-Tool-Factories auf,
Die Zusammenfassung listet die gesamte Factory-Zeit und die langsamsten Plugin-Tool-Factorys auf,
einschließlich Plugin-ID, deklarierter Tool-Namen, Ergebnisform und ob das Tool
optional ist. Langsame Zeilen werden zu Warnungen hochgestuft, wenn eine einzelne Factory mindestens
1 s benötigt oder die gesamte Vorbereitung der Plugin-Tool-Factory mindestens 5 s dauert.
optional ist. Langsame Zeilen werden zu Warnungen hochgestuft, wenn eine einzelne Factory
mindestens 1 s benötigt oder die gesamte Vorbereitung der Plugin-Tool-Factorys mindestens 5 s dauert.
OpenClaw cached erfolgreiche Ergebnisse von Plugin-Tool-Factories für wiederholte Auflösungen
mit demselben effektiven Request-Kontext. Der Cache-Schlüssel enthält die effektive
Runtime-Konfiguration, Workspace, Agent-/Sitzungs-IDs, Sandbox-Richtlinie, Browsereinstellungen,
Auslieferungskontext, Requester-Identität und Besitzstatus, sodass Factories, die
OpenClaw cached erfolgreiche Ergebnisse von Plugin-Tool-Factorys für wiederholte Auflösungen
mit demselben effektiven Anfragekontext. Der Cache-Schlüssel enthält die effektive
Laufzeitkonfiguration, Workspace, Agent-/Sitzungs-IDs, Sandbox-Richtlinie, Browser-Einstellungen,
Delivery-Kontext, Requester-Identität und Besitzstatus, sodass Factorys, die
von diesen vertrauenswürdigen Feldern abhängen, erneut ausgeführt werden, wenn sich der Kontext ändert.
Wenn ein Plugin das Timing dominiert, prüfen Sie seine Runtime-Registrierungen:
Wenn ein Plugin das Timing dominiert, prüfen Sie seine Laufzeitregistrierungen:
```bash
openclaw plugins inspect <plugin-id> --runtime --json
@ -413,9 +441,9 @@ openclaw plugins inspect <plugin-id> --runtime --json
Aktualisieren, reinstallieren oder deaktivieren Sie dann dieses Plugin. Plugin-Autoren sollten
teures Laden von Abhängigkeiten hinter den Tool-Ausführungspfad verschieben, statt es
innerhalb der Tool-Factory auszuführen.
innerhalb der Tool-Factory zu tun.
### Doppelte Channel- oder Tool-Eigentümerschaft
### Doppelte Kanal- oder Tool-Zuständigkeit
Symptome:
@ -423,9 +451,9 @@ Symptome:
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
Diese bedeuten, dass mehr als ein aktiviertes Plugin versucht, denselben Channel,
Setup-Flow oder Tool-Namen zu besitzen. Die häufigste Ursache ist ein externes Channel-Plugin,
das neben einem gebündelten Plugin installiert ist, das jetzt dieselbe Channel-ID bereitstellt.
Diese bedeuten, dass mehr als ein aktiviertes Plugin versucht, denselben Kanal,
Setup-Ablauf oder Tool-Namen zu besitzen. Die häufigste Ursache ist ein externes Kanal-Plugin,
das neben einem gebündelten Plugin installiert ist, das jetzt dieselbe Kanal-ID bereitstellt.
Debug-Schritte:
@ -433,25 +461,25 @@ Debug-Schritte:
und seinen Ursprung zu sehen.
- Führen Sie `openclaw plugins inspect <id> --runtime --json` für jedes verdächtige Plugin aus und
vergleichen Sie `channels`, `channelConfigs`, `tools` und Diagnosen.
- Führen Sie `openclaw plugins registry --refresh` nach dem Installieren oder Entfernen von
Plugin-Paketen aus, damit persistierte Metadaten die aktuelle Installation widerspiegeln.
- Starten Sie den Gateway nach Installations-, Registry- oder Konfigurationsänderungen neu.
- Führen Sie `openclaw plugins registry --refresh` aus, nachdem Sie
Plugin-Pakete installiert oder entfernt haben, damit persistierte Metadaten die aktuelle Installation widerspiegeln.
- Starten Sie das Gateway nach Installations-, Registry- oder Konfigurationsänderungen neu.
Behebungsoptionen:
- Wenn ein Plugin absichtlich ein anderes für dieselbe Channel-ID ersetzt, sollte das
bevorzugte Plugin `channelConfigs.<channel-id>.preferOver` mit der
Plugin-ID niedrigerer Priorität deklarieren. Siehe [/plugins/manifest#replacing-another-channel-plugin](/de/plugins/manifest#replacing-another-channel-plugin).
- Wenn das Duplikat unbeabsichtigt ist, deaktivieren Sie eine Seite mit
- Wenn ein Plugin absichtlich ein anderes für dieselbe Kanal-ID ersetzt, sollte das
bevorzugte Plugin `channelConfigs.<channel-id>.preferOver` mit
der niedriger priorisierten Plugin-ID deklarieren. Siehe [/plugins/manifest#replacing-another-channel-plugin](/de/plugins/manifest#replacing-another-channel-plugin).
- Wenn das Duplikat versehentlich ist, deaktivieren Sie eine Seite mit
`plugins.entries.<plugin-id>.enabled: false` oder entfernen Sie die veraltete Plugin-
Installation.
- Wenn Sie beide Plugins explizit aktiviert haben, behält OpenClaw diese Anforderung bei und
meldet den Konflikt. Wählen Sie einen Besitzer für den Channel oder benennen Sie Plugin-eigene
Tools um, damit die Runtime-Oberfläche eindeutig ist.
- Wenn Sie beide Plugins explizit aktiviert haben, behält OpenClaw diese Anfrage bei und
meldet den Konflikt. Wählen Sie einen Besitzer für den Kanal oder benennen Sie Plugin-eigene
Tools um, damit die Laufzeitoberfläche eindeutig ist.
## Plugin-Slots (exklusive Kategorien)
Einige Kategorien sind exklusiv (nur eine aktive gleichzeitig):
Einige Kategorien sind exklusiv (nur eine ist jeweils aktiv):
```json5
{
@ -467,7 +495,7 @@ Einige Kategorien sind exklusiv (nur eine aktive gleichzeitig):
| Slot | Was er steuert | Standard |
| --------------- | -------------------- | ------------------- |
| `memory` | Active-Memory-Plugin | `memory-core` |
| `contextEngine` | Aktive Context Engine | `legacy` (integriert) |
| `contextEngine` | Aktive Kontext-Engine | `legacy` (integriert) |
## CLI-Referenz
@ -517,35 +545,35 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Mitgelieferte Plugins werden mit OpenClaw ausgeliefert. Viele sind standardmäßig aktiviert (zum Beispiel mitgelieferte Modell-Provider, mitgelieferte Speech-Provider und das mitgelieferte Browser-Plugin). Andere mitgelieferte Plugins benötigen weiterhin `openclaw plugins enable <id>`.
Gebündelte Plugins werden mit OpenClaw ausgeliefert. Viele sind standardmäßig aktiviert, beispielsweise gebündelte Modell-Provider, gebündelte Speech-Provider und das gebündelte Browser-Plugin. Andere gebündelte Plugins benötigen weiterhin `openclaw plugins enable <id>`.
`--force` überschreibt ein vorhandenes installiertes Plugin oder Hook Pack direkt an Ort und Stelle. Verwenden Sie `openclaw plugins update <id-or-npm-spec>` für routinemäßige Upgrades nachverfolgter npm-Plugins. Dies wird nicht mit `--link` unterstützt, das den Quellpfad wiederverwendet, statt über ein verwaltetes Installationsziel zu kopieren.
`--force` überschreibt ein vorhandenes installiertes Plugin oder Hook-Paket direkt am Zielort. Verwenden Sie `openclaw plugins update <id-or-npm-spec>` für routinemäßige Upgrades nachverfolgter npm-Plugins. Dies wird nicht mit `--link` unterstützt, da dabei der Quellpfad wiederverwendet wird, statt über ein verwaltetes Installationsziel zu kopieren.
Wenn `plugins.allow` bereits gesetzt ist, fügt `openclaw plugins install` die installierte Plugin-ID dieser Allowlist hinzu, bevor es das Plugin aktiviert. Wenn dieselbe Plugin-ID in `plugins.deny` vorhanden ist, entfernt die Installation diesen veralteten Deny-Eintrag, damit die explizite Installation nach einem Neustart sofort geladen werden kann.
Wenn `plugins.allow` bereits gesetzt ist, fügt `openclaw plugins install` die installierte Plugin-ID vor der Aktivierung dieser Allowlist hinzu. Wenn dieselbe Plugin-ID in `plugins.deny` vorhanden ist, entfernt die Installation diesen veralteten Deny-Eintrag, damit die explizite Installation nach einem Neustart sofort ladbar ist.
OpenClaw speichert eine persistierte lokale Plugin-Registry als Cold-Read-Modell für Plugin-Inventar, Besitz von Beiträgen und Startplanung. Installations-, Update-, Deinstallations-, Aktivierungs- und Deaktivierungsabläufe aktualisieren diese Registry, nachdem sie den Plugin-Zustand geändert haben. Dieselbe Datei `plugins/installs.json` enthält dauerhafte Installationsmetadaten in `installRecords` auf oberster Ebene und wiederherstellbare Manifestmetadaten in `plugins`. Wenn die Registry fehlt, veraltet oder ungültig ist, baut `openclaw plugins registry --refresh` ihre Manifestansicht aus Installationsdatensätzen, Konfigurationsrichtlinie und Manifest-/Paketmetadaten neu auf, ohne Plugin-Runtime-Module zu laden.
`openclaw plugins update <id-or-npm-spec>` gilt für nachverfolgte Installationen. Die Übergabe einer npm-Paketspezifikation mit Dist-Tag oder exakter Version löst den Paketnamen zurück zum nachverfolgten Plugin-Datensatz auf und speichert die neue Spezifikation für zukünftige Updates. Die Übergabe des Paketnamens ohne Version verschiebt eine exakt gepinnte Installation zurück auf die Standard-Release-Linie der Registry. Wenn das installierte npm-Plugin bereits der aufgelösten Version und der gespeicherten Artefaktidentität entspricht, überspringt OpenClaw das Update, ohne herunterzuladen, neu zu installieren oder die Konfiguration neu zu schreiben.
Wenn `openclaw update` im Beta-Kanal ausgeführt wird, versuchen npm- und ClawHub-Plugin-Datensätze der Standardlinie zuerst `@beta` und fallen auf default/latest zurück, wenn keine Plugin-Beta-Version vorhanden ist. Exakte Versionen und explizite Tags bleiben gepinnt.
OpenClaw führt eine persistierte lokale Plugin-Registry als Kaltlesemodell für Plugin-Inventar, Besitz von Beiträgen und Startplanung. Installations-, Update-, Deinstallations-, Aktivierungs- und Deaktivierungsabläufe aktualisieren diese Registry, nachdem sie den Plugin-Zustand geändert haben. Dieselbe Datei `plugins/installs.json` enthält dauerhafte Installationsmetadaten in `installRecords` auf oberster Ebene und neu erstellbare Manifestmetadaten in `plugins`. Wenn die Registry fehlt, veraltet oder ungültig ist, baut `openclaw plugins registry --refresh` ihre Manifestansicht aus Installationsdatensätzen, Konfigurationsrichtlinie sowie Manifest-/Paketmetadaten neu auf, ohne Plugin-Runtime-Module zu laden.
`openclaw plugins update <id-or-npm-spec>` gilt für nachverfolgte Installationen. Wenn Sie eine npm-Paketspezifikation mit einem Dist-Tag oder einer exakten Version übergeben, wird der Paketname zurück zum nachverfolgten Plugin-Datensatz aufgelöst und die neue Spezifikation für zukünftige Updates gespeichert. Wenn Sie den Paketnamen ohne Version übergeben, wird eine exakt gepinnte Installation wieder auf die standardmäßige Release-Linie der Registry gesetzt. Wenn das installierte npm-Plugin bereits der aufgelösten Version und der aufgezeichneten Artefaktidentität entspricht, überspringt OpenClaw das Update, ohne herunterzuladen, neu zu installieren oder die Konfiguration neu zu schreiben.
Wenn `openclaw update` im Beta-Kanal läuft, versuchen npm- und ClawHub-Plugin-Datensätze der Standardlinie zuerst `@beta` und fallen auf Standard/Latest zurück, wenn kein Plugin-Beta-Release vorhanden ist. Exakte Versionen und explizite Tags bleiben gepinnt.
`--pin` ist nur für npm. Es wird nicht mit `--marketplace` unterstützt, weil Marketplace-Installationen Marketplace-Quellmetadaten anstelle einer npm-Spezifikation persistieren.
`--pin` gilt nur für npm. Es wird nicht mit `--marketplace` unterstützt, da Marketplace-Installationen Marketplace-Quellmetadaten statt einer npm-Spezifikation persistieren.
`--dangerously-force-unsafe-install` ist eine Break-Glass-Übersteuerung für Fehlalarme des integrierten Scanners für gefährlichen Code. Sie erlaubt Plugin-Installationen und Plugin-Updates, trotz integrierter `critical`-Befunde fortzufahren, umgeht aber weiterhin keine Plugin-`before_install`-Richtlinienblockaden oder Blockaden durch Scan-Fehlschläge. Installationsscans ignorieren übliche Testdateien und Verzeichnisse wie `tests/`, `__tests__/`, `*.test.*` und `*.spec.*`, um das Blockieren gepackter Test-Mocks zu vermeiden; deklarierte Plugin-Runtime-Einstiegspunkte werden weiterhin gescannt, selbst wenn sie einen dieser Namen verwenden.
`--dangerously-force-unsafe-install` ist eine Break-Glass-Überschreibung für Fehlalarme des eingebauten Scanners für gefährlichen Code. Sie ermöglicht Plugin-Installationen und Plugin-Updates trotz eingebauter `critical`-Befunde fortzusetzen, umgeht aber weiterhin keine Plugin-`before_install`-Richtlinienblockaden oder Blockierungen durch Scan-Fehler. Installationsscans ignorieren gängige Testdateien und Verzeichnisse wie `tests/`, `__tests__/`, `*.test.*` und `*.spec.*`, um das Blockieren paketierter Test-Mocks zu vermeiden; deklarierte Plugin-Runtime-Einstiegspunkte werden weiterhin gescannt, selbst wenn sie einen dieser Namen verwenden.
Dieses CLI-Flag gilt nur für Plugin-Installations-/Update-Abläufe. Gateway-gestützte Installationen von Skill-Abhängigkeiten verwenden stattdessen die passende `dangerouslyForceUnsafeInstall`-Anforderungsübersteuerung, während `openclaw skills install` der separate ClawHub-Ablauf zum Herunterladen/Installieren von Skills bleibt.
Dieses CLI-Flag gilt nur für Plugin-Installations-/Update-Abläufe. Gateway-gestützte Skills-Abhängigkeitsinstallationen verwenden stattdessen die passende Anfrageüberschreibung `dangerouslyForceUnsafeInstall`, während `openclaw skills install` der separate ClawHub-Download-/Installationsablauf für Skills bleibt.
Wenn ein von Ihnen auf ClawHub veröffentlichtes Plugin durch einen Scan verborgen oder blockiert ist, öffnen Sie das ClawHub-Dashboard oder führen Sie `clawhub package rescan <name>` aus, um ClawHub zu bitten, es erneut zu prüfen. `--dangerously-force-unsafe-install` betrifft nur Installationen auf Ihrem eigenen Rechner; es fordert ClawHub nicht auf, das Plugin erneut zu scannen oder eine blockierte Veröffentlichung öffentlich zu machen.
Wenn ein Plugin, das Sie auf ClawHub veröffentlicht haben, durch einen Scan ausgeblendet oder blockiert wird, öffnen Sie das ClawHub-Dashboard oder führen Sie `clawhub package rescan <name>` aus, um ClawHub zu bitten, es erneut zu prüfen. `--dangerously-force-unsafe-install` wirkt sich nur auf Installationen auf Ihrem eigenen Rechner aus; es fordert ClawHub nicht auf, das Plugin erneut zu scannen oder ein blockiertes Release öffentlich zu machen.
Kompatible Bundles nehmen am selben Ablauf zum Auflisten/Prüfen/Aktivieren/Deaktivieren von Plugins teil. Die aktuelle Runtime-Unterstützung umfasst Bundle-Skills, Claude-Befehl-Skills, Claude-`settings.json`-Standardeinstellungen, Claude-`.lsp.json`- und im Manifest deklarierte `lspServers`-Standardeinstellungen, Cursor-Befehl-Skills und kompatible Codex-Hook-Verzeichnisse.
Kompatible Bundles nehmen am selben Ablauf zum Auflisten, Inspizieren, Aktivieren und Deaktivieren von Plugins teil. Die aktuelle Runtime-Unterstützung umfasst Bundle-Skills, Claude-Befehl-Skills, Claude-`settings.json`-Standardwerte, Claude-`.lsp.json`- und manifestdeklarierte `lspServers`-Standardwerte, Cursor-Befehl-Skills und kompatible Codex-Hook-Verzeichnisse.
`openclaw plugins inspect <id>` meldet außerdem erkannte Bundle-Fähigkeiten sowie unterstützte oder nicht unterstützte MCP- und LSP-Servereinträge für Bundle-gestützte Plugins.
Marketplace-Quellen können ein Claude-Name aus bekannten Marketplaces aus `~/.claude/plugins/known_marketplaces.json`, ein lokaler Marketplace-Root oder `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL sein. Bei Remote-Marketplaces müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repos bleiben und ausschließlich relative Pfadquellen verwenden.
Marketplace-Quellen können ein bekannter Claude-Marketplace-Name aus `~/.claude/plugins/known_marketplaces.json`, ein lokales Marketplace-Root oder ein `marketplace.json`-Pfad, eine GitHub-Kurzform wie `owner/repo`, eine GitHub-Repo-URL oder eine Git-URL sein. Bei Remote-Marketplaces müssen Plugin-Einträge innerhalb des geklonten Marketplace-Repos bleiben und ausschließlich relative Pfadquellen verwenden.
Vollständige Details finden Sie in der [`openclaw plugins` CLI-Referenz](/de/cli/plugins).
Vollständige Details finden Sie in der [`openclaw plugins`-CLI-Referenz](/de/cli/plugins).
## Überblick über die Plugin-API
Native Plugins exportieren ein Entry-Objekt, das `register(api)` bereitstellt. Ältere Plugins können weiterhin `activate(api)` als Legacy-Alias verwenden, neue Plugins sollten jedoch `register` verwenden.
Native Plugins exportieren ein Einstiegsobjekt, das `register(api)` bereitstellt. Ältere Plugins können weiterhin `activate(api)` als Legacy-Alias verwenden, neue Plugins sollten jedoch `register` verwenden.
```typescript
export default definePluginEntry({
@ -565,60 +593,60 @@ export default definePluginEntry({
});
```
OpenClaw lädt das Entry-Objekt und ruft während der Plugin-Aktivierung `register(api)` auf. Der Loader fällt für ältere Plugins weiterhin auf `activate(api)` zurück, aber mitgelieferte Plugins und neue externe Plugins sollten `register` als öffentlichen Vertrag behandeln.
OpenClaw lädt das Einstiegsobjekt und ruft während der Plugin-Aktivierung `register(api)` auf. Der Loader fällt für ältere Plugins weiterhin auf `activate(api)` zurück, gebündelte Plugins und neue externe Plugins sollten `register` jedoch als öffentlichen Vertrag behandeln.
`api.registrationMode` teilt einem Plugin mit, warum sein Entry geladen wird:
`api.registrationMode` teilt einem Plugin mit, warum sein Einstieg geladen wird:
| Modus | Bedeutung |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Runtime-Aktivierung. Registriert Tools, Hooks, Dienste, Befehle, Routen und andere Live-Nebeneffekte. |
| `discovery` | Schreibgeschützte Fähigkeitserkennung. Registriert Provider und Metadaten; vertrauenswürdiger Plugin-Entry-Code kann laden, überspringt aber Live-Nebeneffekte. |
| `setup-only` | Laden von Channel-Setup-Metadaten über einen leichtgewichtigen Setup-Entry. |
| `setup-runtime` | Channel-Setup-Laden, das zusätzlich den Runtime-Entry benötigt. |
| `cli-metadata` | Nur Sammlung von CLI-Befehlsmetadaten. |
| Modus | Bedeutung |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `full` | Runtime-Aktivierung. Registrieren Sie Tools, Hooks, Dienste, Befehle, Routen und andere Live-Nebeneffekte. |
| `discovery` | Schreibgeschützte Fähigkeitserkennung. Registrieren Sie Provider und Metadaten; vertrauenswürdiger Plugin-Einstiegscode kann geladen werden, sollte aber Live-Nebeneffekte überspringen. |
| `setup-only` | Laden von Channel-Setup-Metadaten über einen schlanken Setup-Einstieg. |
| `setup-runtime` | Channel-Setup-Laden, das zusätzlich den Runtime-Einstieg benötigt. |
| `cli-metadata` | Nur Erfassung von CLI-Befehlsmetadaten. |
Plugin-Entries, die Sockets, Datenbanken, Hintergrund-Worker oder langlebige Clients öffnen, sollten diese Nebeneffekte mit `api.registrationMode === "full"` schützen. Discovery-Ladevorgänge werden getrennt von Aktivierungs-Ladevorgängen gecacht und ersetzen nicht die laufende Gateway-Registry. Discovery ist nicht aktivierend, aber nicht importfrei: OpenClaw kann den vertrauenswürdigen Plugin-Entry oder das Channel-Plugin-Modul auswerten, um den Snapshot zu erstellen. Halten Sie Module-Top-Level leichtgewichtig und frei von Nebeneffekten, und verschieben Sie Netzwerk-Clients, Subprozesse, Listener, Credential-Lesevorgänge und Dienststarts hinter Full-Runtime-Pfade.
Plugin-Einstiege, die Sockets, Datenbanken, Hintergrund-Worker oder langlebige Clients öffnen, sollten diese Nebeneffekte mit `api.registrationMode === "full"` absichern. Discovery-Ladevorgänge werden separat von aktivierenden Ladevorgängen gecacht und ersetzen nicht die laufende Gateway-Registry. Discovery ist nicht aktivierend, aber nicht importfrei: OpenClaw kann den vertrauenswürdigen Plugin-Einstieg oder das Channel-Plugin-Modul auswerten, um den Snapshot zu erstellen. Halten Sie die oberste Modulebene schlank und frei von Nebeneffekten, und verschieben Sie Netzwerk-Clients, Subprozesse, Listener, Anmeldedaten-Lesevorgänge und Dienststarts hinter vollständige Runtime-Pfade.
Häufige Registrierungsmethoden:
Gängige Registrierungsmethoden:
| Methode | Was registriert wird |
| --------------------------------------- | -------------------------------- |
| `registerProvider` | Modell-Provider (LLM) |
| `registerChannel` | Chat-Channel |
| `registerTool` | Agent-Tool |
| `registerHook` / `on(...)` | Lifecycle-Hooks |
| `registerSpeechProvider` | Text-to-Speech / STT |
| `registerRealtimeTranscriptionProvider` | Streaming-STT |
| `registerRealtimeVoiceProvider` | Duplex-Realtime-Voice |
| `registerMediaUnderstandingProvider` | Bild-/Audioanalyse |
| `registerImageGenerationProvider` | Bilderzeugung |
| `registerMusicGenerationProvider` | Musikerzeugung |
| `registerVideoGenerationProvider` | Videoerzeugung |
| `registerWebFetchProvider` | Web-Fetch-/Scrape-Provider |
| `registerWebSearchProvider` | Websuche |
| `registerHttpRoute` | HTTP-Endpunkt |
| `registerCommand` / `registerCli` | CLI-Befehle |
| `registerContextEngine` | Kontext-Engine |
| `registerService` | Hintergrunddienst |
| Methode | Was registriert wird |
| --------------------------------------- | -------------------------- |
| `registerProvider` | Modell-Provider (LLM) |
| `registerChannel` | Chat-Channel |
| `registerTool` | Agent-Tool |
| `registerHook` / `on(...)` | Lifecycle-Hooks |
| `registerSpeechProvider` | Text-to-Speech / STT |
| `registerRealtimeTranscriptionProvider` | Streaming-STT |
| `registerRealtimeVoiceProvider` | Duplex-Echtzeitstimme |
| `registerMediaUnderstandingProvider` | Bild-/Audioanalyse |
| `registerImageGenerationProvider` | Bilderzeugung |
| `registerMusicGenerationProvider` | Musikerzeugung |
| `registerVideoGenerationProvider` | Videoerzeugung |
| `registerWebFetchProvider` | Web-Fetch-/Scrape-Provider |
| `registerWebSearchProvider` | Websuche |
| `registerHttpRoute` | HTTP-Endpunkt |
| `registerCommand` / `registerCli` | CLI-Befehle |
| `registerContextEngine` | Kontext-Engine |
| `registerService` | Hintergrunddienst |
Hook-Guard-Verhalten für typisierte Lifecycle-Hooks:
- `before_tool_call`: `{ block: true }` ist terminal; Handler mit niedrigerer Priorität werden übersprungen.
- `before_tool_call`: `{ block: false }` ist ein No-op und hebt eine frühere Blockierung nicht auf.
- `before_tool_call`: `{ block: false }` ist ein No-op und löscht keinen früheren Block.
- `before_install`: `{ block: true }` ist terminal; Handler mit niedrigerer Priorität werden übersprungen.
- `before_install`: `{ block: false }` ist ein No-op und hebt eine frühere Blockierung nicht auf.
- `before_install`: `{ block: false }` ist ein No-op und löscht keinen früheren Block.
- `message_sending`: `{ cancel: true }` ist terminal; Handler mit niedrigerer Priorität werden übersprungen.
- `message_sending`: `{ cancel: false }` ist ein No-op und hebt ein früheres Abbrechen nicht auf.
- `message_sending`: `{ cancel: false }` ist ein No-op und löscht kein früheres Cancel.
Der native Codex-App-Server führt Codex-native Tool-Ereignisse zurück in diese Hook-Oberfläche. Plugins können native Codex-Tools über `before_tool_call` blockieren, Ergebnisse über `after_tool_call` beobachten und an Genehmigungen für Codex-`PermissionRequest` teilnehmen. Die Bridge schreibt Argumente Codex-nativer Tools noch nicht um. Die genaue Grenze der Codex-Runtime-Unterstützung steht im [Codex-Harness-v1-Supportvertrag](/de/plugins/codex-harness#v1-support-contract).
Der native Codex-App-Server leitet Codex-native Tool-Ereignisse zurück in diese Hook-Oberfläche. Plugins können native Codex-Tools über `before_tool_call` blockieren, Ergebnisse über `after_tool_call` beobachten und an Codex-`PermissionRequest`-Genehmigungen teilnehmen. Die Bridge schreibt Codex-native Tool-Argumente noch nicht um. Die genaue Grenze der Codex-Runtime-Unterstützung steht im [Codex-Harness-v1-Supportvertrag](/de/plugins/codex-harness#v1-support-contract).
Das vollständig typisierte Hook-Verhalten finden Sie im [SDK-Überblick](/de/plugins/sdk-overview#hook-decision-semantics).
Das vollständige Verhalten typisierter Hooks finden Sie im [SDK-Überblick](/de/plugins/sdk-overview#hook-decision-semantics).
## Verwandt
## Verwandte
- [Plugins erstellen](/de/plugins/building-plugins) — eigenes Plugin erstellen
- [Plugin-Bundles](/de/plugins/bundles) — Codex-/Claude-/Cursor-Bundle-Kompatibilität
- [Plugins erstellen](/de/plugins/building-plugins) — Ihr eigenes Plugin erstellen
- [Plugin-Bundles](/de/plugins/bundles) — Bundle-Kompatibilität mit Codex/Claude/Cursor
- [Plugin-Manifest](/de/plugins/manifest) — Manifest-Schema
- [Tools registrieren](/de/plugins/building-plugins#registering-agent-tools) — Agent-Tools in einem Plugin hinzufügen
- [Plugin-Interna](/de/plugins/architecture) — Fähigkeitsmodell und Ladepipeline
- [Community-Plugins](/de/plugins/community) — Einträge von Drittanbietern
- [Plugin-Interna](/de/plugins/architecture) — Capability-Modell und Ladepipeline
- [Community-Plugins](/de/plugins/community) — Verzeichnisse von Drittanbietern

147
docs/de/tools/thinking.md
View File

@ -1,144 +1,145 @@
---
read_when:
- Anpassen der Auswertung oder Standardwerte für Denkmodus-, Schnellmodus- oder Ausführlichkeitsdirektiven
summary: Direktivensyntax für /think, /fast, /verbose, /trace und die Sichtbarkeit der Denkprozesse
- Anpassen des Parsings oder der Standardwerte für Denk-, Schnellmodus- oder Ausführlichkeitsdirektiven
summary: Direktivensyntax für /think, /fast, /verbose, /trace und die Sichtbarkeit des Reasonings
title: Denkstufen
x-i18n:
generated_at: "2026-05-04T18:24:30Z"
generated_at: "2026-05-05T01:50:23Z"
model: gpt-5.5
provider: openai
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
source_path: tools/thinking.md
workflow: 16
---
## Funktionsweise
## Was es macht
- Inline-Direktive in einem beliebigen eingehenden Inhalt: `/t <level>`, `/think:<level>` oder `/thinking <level>`.
- Inline-Direktive in jedem eingehenden Inhalt: `/t <level>`, `/think:<level>` oder `/thinking <level>`.
- Stufen (Aliasse): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → „denken“
- low → „gründlich denken“
- medium → „noch gründlicher denken“
- high → „ultradenken“ (maximales Budget)
- xhigh → „ultradenken+“ (GPT-5.2+ und Codex-Modelle sowie Anthropic Claude Opus 4.7-Aufwand)
- adaptive → Provider-verwaltetes adaptives Denken (unterstützt für Claude 4.6 auf Anthropic/Bedrock, Anthropic Claude Opus 4.7 und dynamisches Denken von Google Gemini)
- max → maximales Provider-Reasoning (Anthropic Claude Opus 4.7; Ollama ordnet dies seinem höchsten nativen `think`-Aufwand zu)
- low → „intensiv denken“
- medium → „intensiver denken“
- high → „ultrathink“ (maximales Budget)
- xhigh → „ultrathink+“ (GPT-5.2+ und Codex-Modelle sowie Anthropic Claude Opus 4.7 Effort)
- adaptive → vom Provider verwaltetes adaptives Denken (unterstützt für Claude 4.6 auf Anthropic/Bedrock, Anthropic Claude Opus 4.7 und Google Gemini Dynamic Thinking)
- max → maximale Provider-Reasoning (Anthropic Claude Opus 4.7; Ollama ordnet dies seinem höchsten nativen `think`-Effort zu)
- `x-high`, `x_high`, `extra-high`, `extra high` und `extra_high` werden `xhigh` zugeordnet.
- `highest` wird `high` zugeordnet.
- Provider-Hinweise:
- Denken-Menüs und Auswahlfelder werden vom Provider-Profil gesteuert. Provider-Plugins deklarieren den exakten Stufensatz für das ausgewählte Modell, einschließlich Labels wie binärem `on`.
- `adaptive`, `xhigh` und `max` werden nur für Provider-/Modellprofile angezeigt, die sie unterstützen. Eingegebene Direktiven für nicht unterstützte Stufen werden mit den gültigen Optionen dieses Modells zurückgewiesen.
- Vorhandene gespeicherte nicht unterstützte Stufen werden anhand der Rangfolge des Provider-Profils neu zugeordnet. `adaptive` fällt bei nicht adaptiven Modellen auf `medium` zurück, während `xhigh` und `max` auf die größte unterstützte nicht-`off`-Stufe für das ausgewählte Modell zurückfallen.
- Anthropic Claude 4.6-Modelle verwenden standardmäßig `adaptive`, wenn keine explizite Denkstufe festgelegt ist.
- Anthropic Claude Opus 4.7 verwendet nicht standardmäßig adaptives Denken. Sein API-Effort-Standardwert bleibt Provider-eigen, sofern Sie nicht explizit eine Denkstufe festlegen.
- Anthropic Claude Opus 4.7 ordnet `/think xhigh` adaptivem Denken plus `output_config.effort: "xhigh"` zu, weil `/think` eine Denken-Direktive ist und `xhigh` die Opus 4.7-Effort-Einstellung ist.
- Anthropic Claude Opus 4.7 stellt außerdem `/think max` bereit; es wird demselben Provider-eigenen maximalen Effort-Pfad zugeordnet.
- DeepSeek V4-Modelle stellen `/think xhigh|max` bereit; beide werden DeepSeek `reasoning_effort: "max"` zugeordnet, während niedrigere nicht-`off`-Stufen `high` zugeordnet werden.
- Denk-Menüs und Auswahlfelder werden über Provider-Profile gesteuert. Provider-Plugins deklarieren den exakten Stufensatz für das ausgewählte Modell, einschließlich Labels wie binärem `on`.
- `adaptive`, `xhigh` und `max` werden nur für Provider-/Modellprofile angezeigt, die sie unterstützen. Eingegebene Direktiven für nicht unterstützte Stufen werden mit den für dieses Modell gültigen Optionen abgelehnt.
- Bereits gespeicherte, nicht unterstützte Stufen werden anhand des Provider-Profilrangs neu zugeordnet. `adaptive` fällt bei nicht adaptiven Modellen auf `medium` zurück, während `xhigh` und `max` auf die größte unterstützte Nicht-`off`-Stufe für das ausgewählte Modell zurückfallen.
- Anthropic-Claude-4.6-Modelle verwenden standardmäßig `adaptive`, wenn keine explizite Denkstufe gesetzt ist.
- Anthropic Claude Opus 4.7 verwendet adaptives Denken nicht standardmäßig. Der API-Effort-Standard bleibt Provider-eigen, sofern Sie nicht explizit eine Denkstufe setzen.
- Anthropic Claude Opus 4.7 ordnet `/think xhigh` adaptivem Denken plus `output_config.effort: "xhigh"` zu, weil `/think` eine Denk-Direktive ist und `xhigh` die Opus-4.7-Effort-Einstellung ist.
- Anthropic Claude Opus 4.7 stellt außerdem `/think max` bereit; dies wird demselben Provider-eigenen Pfad für maximalen Effort zugeordnet.
- Direkte DeepSeek-V4-Modelle stellen `/think xhigh|max` bereit; beide werden DeepSeek `reasoning_effort: "max"` zugeordnet, während niedrigere Nicht-`off`-Stufen `high` zugeordnet werden.
- Über OpenRouter geroutete DeepSeek-V4-Modelle stellen `/think xhigh` bereit und senden von OpenRouter unterstützte `reasoning_effort`-Werte. Gespeicherte `max`-Overrides fallen auf `xhigh` zurück.
- Denkfähige Ollama-Modelle stellen `/think low|medium|high|max` bereit; `max` wird nativem `think: "high"` zugeordnet, weil Ollamas native API die Effort-Strings `low`, `medium` und `high` akzeptiert.
- OpenAI-GPT-Modelle ordnen `/think` über die modellspezifische Effort-Unterstützung der Responses API zu. `/think off` sendet `reasoning.effort: "none"` nur, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die deaktivierte Reasoning-Nutzlast weg, statt einen nicht unterstützten Wert zu senden.
- Benutzerdefinierte OpenAI-kompatible Katalogeinträge können `/think xhigh` aktivieren, indem `models.providers.<provider>.models[].compat.supportedReasoningEfforts` so gesetzt wird, dass es `"xhigh"` enthält. Dies verwendet dieselben Kompatibilitätsmetadaten, die ausgehende OpenAI-Reasoning-Effort-Nutzlasten zuordnen, sodass Menüs, Sitzungsvalidierung, Agent-CLI und `llm-task` mit dem Transportverhalten übereinstimmen.
- Veraltete konfigurierte OpenRouter Hunter Alpha-Refs überspringen die Proxy-Reasoning-Injektion, weil diese eingestellte Route finalen Antworttext über Reasoning-Felder zurückgeben konnte.
- Google Gemini ordnet `/think adaptive` dem Provider-eigenen dynamischen Denken von Gemini zu. Gemini 3-Anfragen lassen ein festes `thinkingLevel` weg, während Gemini 2.5-Anfragen `thinkingBudget: -1` senden; feste Stufen werden weiterhin der nächstliegenden Gemini-`thinkingLevel`- oder Budget-Einstellung für diese Modellfamilie zugeordnet.
- MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Denken nicht explizit in Modellparametern oder Anfrageparametern festlegen. Dadurch werden ungewollt weitergeleitete `reasoning_content`-Deltas aus dem nicht nativen Anthropic-Stream-Format von MiniMax vermieden.
- Z.AI (`zai/*`) unterstützt nur binäres Denken (`on`/`off`). Jede nicht-`off`-Stufe wird als `on` behandelt (`low` zugeordnet).
- Moonshot (`moonshot/*`) ordnet `/think off` `thinking: { type: "disabled" }` zu und jede nicht-`off`-Stufe `thinking: { type: "enabled" }`. Wenn Denken aktiviert ist, akzeptiert Moonshot nur `tool_choice` `auto|none`; OpenClaw normalisiert inkompatible Werte zu `auto`.
- OpenAI-GPT-Modelle ordnen `/think` der modellspezifischen Effort-Unterstützung der Responses API zu. `/think off` sendet `reasoning.effort: "none"` nur, wenn das Zielmodell dies unterstützt; andernfalls lässt OpenClaw die deaktivierte Reasoning-Nutzlast weg, statt einen nicht unterstützten Wert zu senden.
- Benutzerdefinierte OpenAI-kompatible Katalogeinträge können `/think xhigh` aktivieren, indem `models.providers.<provider>.models[].compat.supportedReasoningEfforts` so gesetzt wird, dass `"xhigh"` enthalten ist. Dies nutzt dieselben Kompatibilitätsmetadaten, die ausgehende OpenAI-Reasoning-Effort-Nutzlasten zuordnen, sodass Menüs, Sitzungsvalidierung, Agent-CLI und `llm-task` mit dem Transportverhalten übereinstimmen.
- Veraltete konfigurierte OpenRouter-Hunter-Alpha-Referenzen überspringen die Proxy-Reasoning-Injektion, weil diese eingestellte Route endgültigen Antworttext über Reasoning-Felder zurückgeben konnte.
- Google Gemini ordnet `/think adaptive` dem Provider-eigenen Dynamic Thinking von Gemini zu. Gemini-3-Anfragen lassen ein festes `thinkingLevel` weg, während Gemini-2.5-Anfragen `thinkingBudget: -1` senden; feste Stufen werden weiterhin dem nächstliegenden Gemini-`thinkingLevel` oder Budget für diese Modellfamilie zugeordnet.
- MiniMax (`minimax/*`) auf dem Anthropic-kompatiblen Streaming-Pfad verwendet standardmäßig `thinking: { type: "disabled" }`, sofern Sie Denken nicht explizit in Modellparametern oder Anfrageparametern setzen. Dies verhindert durchgesickerte `reasoning_content`-Deltas aus MiniMax’ nicht nativem Anthropic-Streamformat.
- Z.AI (`zai/*`) unterstützt nur binäres Denken (`on`/`off`). Jede Nicht-`off`-Stufe wird als `on` behandelt (`low` zugeordnet).
- Moonshot (`moonshot/*`) ordnet `/think off` `thinking: { type: "disabled" }` und jede Nicht-`off`-Stufe `thinking: { type: "enabled" }` zu. Wenn Denken aktiviert ist, akzeptiert Moonshot nur `tool_choice` `auto|none`; OpenClaw normalisiert inkompatible Werte zu `auto`.
## Auflösungsreihenfolge
1. Inline-Direktive in der Nachricht (gilt nur für diese Nachricht).
2. Sitzungsüberschreibung (durch Senden einer Nachricht, die nur aus einer Direktive besteht).
2. Sitzungs-Override (gesetzt durch das Senden einer reinen Direktivenachricht).
3. Standard pro Agent (`agents.list[].thinkingDefault` in der Konfiguration).
4. Globaler Standard (`agents.defaults.thinkingDefault` in der Konfiguration).
5. Fallback: Provider-deklarierter Standardwert, wenn verfügbar; andernfalls werden Reasoning-fähige Modelle zu `medium` oder zur nächstliegenden unterstützten nicht-`off`-Stufe für dieses Modell aufgelöst, und nicht Reasoning-fähige Modelle bleiben `off`.
5. Fallback: vom Provider deklarierter Standard, sofern verfügbar; andernfalls werden reasoning-fähige Modelle auf `medium` oder die nächstliegende unterstützte Nicht-`off`-Stufe für dieses Modell aufgelöst, und Modelle ohne Reasoning bleiben `off`.
## Sitzungsstandard festlegen
## 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); gelöscht durch `/think:off` oder eine Leerlauf-Zurücksetzung der Sitzung.
- 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 zurückgewiesen und der Sitzungszustand bleibt unverändert.
- Senden Sie eine Nachricht, die **nur** aus der Direktive besteht (Leerraum erlaubt), z. B. `/think:medium` oder `/t high`.
- Dies bleibt für die aktuelle Sitzung bestehen (standardmäßig pro Absender); gelöscht durch `/think:off` oder das Zurücksetzen bei Sitzungsinaktivität.
- Eine Bestätigungsantwort wird 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 Denkstufe anzuzeigen.
## Anwendung pro Agent
## Anwendung nach Agent
- **Eingebettetes Pi**: Die aufgelöste Stufe wird an die prozessinterne Pi-Agent-Laufzeit übergeben.
- **Eingebetteter Pi**: Die aufgelöste Stufe wird an die prozessinterne Pi-Agent-Laufzeit übergeben.
- **Claude-CLI-Backend**: Nicht-`off`-Stufen werden bei Verwendung von `claude-cli` als `--effort` an Claude Code übergeben; siehe [CLI-Backends](/de/gateway/cli-backends).
## Schnellmodus (/fast)
## Schneller Modus (/fast)
- Stufen: `on|off`.
- Eine Direktive-only-Nachricht 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 aktuell wirksamen Schnellmodus-Zustand anzuzeigen.
- OpenClaw löst den Schnellmodus in dieser Reihenfolge auf:
1. Inline-/Direktive-only `/fast on|off`
2. Sitzungsüberschreibung
- Eine reine Direktivenachricht schaltet einen Sitzungs-Override für den schnellen Modus um und antwortet mit `Fast mode enabled.` / `Fast mode disabled.`.
- Senden Sie `/fast` (oder `/fast status`) ohne Modus, um den aktuell wirksamen Status des schnellen Modus anzuzeigen.
- OpenClaw löst den schnellen Modus in dieser Reihenfolge auf:
1. Inline-/reine Direktive `/fast on|off`
2. Sitzungs-Override
3. Standard pro Agent (`agents.list[].fastModeDefault`)
4. Konfiguration pro Modell: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Für `openai/*` wird der Schnellmodus OpenAI-Prioritätsverarbeitung zugeordnet, 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 `/fast`-Schalter für beide Authentifizierungspfade bei.
- Für direkte öffentliche `anthropic/*`-Anfragen, einschließlich per OAuth authentifiziertem Traffic an `api.anthropic.com`, wird der Schnellmodus Anthropic-Service-Tiers zugeordnet: `/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` zu `MiniMax-M2.7-highspeed` um.
- Explizite Anthropic-Modellparameter `serviceTier` / `service_tier` überschreiben den Schnellmodus-Standardwert, wenn beide gesetzt sind. OpenClaw überspringt weiterhin die Anthropic-Service-Tier-Injektion für nicht-Anthropic-Proxy-Basis-URLs.
- `/status` zeigt `Fast` nur an, wenn der Schnellmodus aktiviert ist.
- Für `openai/*` wird der schnelle Modus OpenAI Priority Processing zugeordnet, indem bei unterstützten Responses-Anfragen `service_tier=priority` gesendet wird.
- Für `openai-codex/*` sendet der schnelle Modus dasselbe `service_tier=priority`-Flag bei Codex Responses. OpenClaw verwendet einen gemeinsamen `/fast`-Schalter für beide Authentifizierungspfade.
- Für direkte öffentliche `anthropic/*`-Anfragen, einschließlich OAuth-authentifiziertem Traffic an `api.anthropic.com`, wird der schnelle Modus Anthropic-Service-Tiers zugeordnet: `/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-`serviceTier`- / `service_tier`-Modellparameter überschreiben den Standard des schnellen Modus, wenn beide gesetzt sind. OpenClaw überspringt weiterhin die Anthropic-Service-Tier-Injektion für Nicht-Anthropic-Proxy-Basis-URLs.
- `/status` zeigt `Fast` nur an, wenn der schnelle Modus aktiviert ist.
## Ausführliche Direktiven (/verbose oder /v)
- Stufen: `on` (minimal) | `full` | `off` (Standard).
- Eine Direktive-only-Nachricht schaltet die ausführliche Sitzungsprotokollierung um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Stufen geben 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` wählen.
- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; andernfalls gelten Sitzungs-/globale Standards.
- Eine reine Direktivenachricht schaltet ausführliche Sitzungsprotokollierung um und antwortet mit `Verbose logging enabled.` / `Verbose logging disabled.`; ungültige Stufen geben einen Hinweis zurück, ohne den Status zu ändern.
- `/verbose off` speichert einen expliziten Sitzungs-Override; löschen Sie ihn über die Sessions-UI, indem Sie `inherit` auswählen.
- Eine Inline-Direktive wirkt nur auf diese Nachricht; andernfalls gelten Sitzungs-/globale Standards.
- Senden Sie `/verbose` (oder `/verbose:`) ohne Argument, um die aktuelle Ausführlichkeitsstufe anzuzeigen.
- Wenn verbose aktiviert ist, senden Agents, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agents), jeden Tool-Aufruf als eigene Nur-Metadaten-Nachricht zurück, mit dem Präfix `<emoji> <tool-name>: <arg>`, wenn verfügbar. Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Nachrichtenblasen), nicht als Streaming-Deltas.
- Tool-Fehlerzusammenfassungen bleiben im Normalmodus sichtbar, aber Rohdetails zu Fehlern als Suffixe werden ausgeblendet, sofern verbose nicht `on` oder `full` ist.
- Wenn verbose `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Nachrichtenblase, auf eine sichere Länge gekürzt). Wenn Sie `/verbose on|full|off` umschalten, während ein Lauf läuft, beachten nachfolgende Tool-Nachrichtenblasen die neue Einstellung.
- `agents.defaults.toolProgressDetail` steuert die Form der `/verbose`-Tool-Zusammenfassungen und Tool-Zeilen in Fortschrittsentwürfen. Verwenden Sie `"explain"` (Standard) für kompakte menschliche Labels wie `🛠️ Exec: checking JS syntax`; verwenden Sie `"raw"`, wenn Sie außerdem den rohen Befehl bzw. das rohe Detail zum Debuggen anhängen möchten. `agents.list[].toolProgressDetail` pro Agent überschreibt den Standard.
- Wenn ausführliche Ausgabe aktiviert ist, senden Agents, die strukturierte Tool-Ergebnisse ausgeben (Pi, andere JSON-Agents), jeden Tool-Aufruf als eigene reine Metadaten-Nachricht zurück, sofern verfügbar mit `<emoji> <tool-name>: <arg>` vorangestellt. Diese Tool-Zusammenfassungen werden gesendet, sobald jedes Tool startet (separate Sprechblasen), nicht als Streaming-Deltas.
- Tool-Fehlerzusammenfassungen bleiben im normalen Modus sichtbar, aber Rohfehlerdetailsuffixe werden ausgeblendet, sofern ausführliche Ausgabe nicht `on` oder `full` ist.
- Wenn ausführliche Ausgabe `full` ist, werden Tool-Ausgaben nach Abschluss ebenfalls weitergeleitet (separate Sprechblase, auf eine sichere Länge gekürzt). Wenn Sie während eines laufenden Durchlaufs `/verbose on|full|off` umschalten, beachten nachfolgende Tool-Sprechblasen die neue Einstellung.
- `agents.defaults.toolProgressDetail` steuert die Form von `/verbose`-Tool-Zusammenfassungen und Tool-Zeilen in Fortschrittsentwürfen. Verwenden Sie `"explain"` (Standard) für kompakte menschenlesbare Labels wie `🛠️ Exec: checking JS syntax`; verwenden Sie `"raw"`, wenn zusätzlich der rohe Befehl bzw. das rohe Detail zum Debuggen angehängt werden soll. `agents.list[].toolProgressDetail` pro Agent überschreibt den Standard.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## Plugin-Trace-Direktiven (/trace)
- Stufen: `on` | `off` (Standard).
- Eine Direktive-only-Nachricht schaltet die Plugin-Trace-Ausgabe der Sitzung um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`.
- Eine Inline-Direktive wirkt sich nur auf diese Nachricht aus; andernfalls gelten Sitzungs-/globale Standards.
- Eine reine Direktivenachricht schaltet die Plugin-Trace-Ausgabe der Sitzung um und antwortet mit `Plugin trace enabled.` / `Plugin trace disabled.`.
- Eine Inline-Direktive wirkt nur auf diese Nachricht; andernfalls gelten Sitzungs-/globale Standards.
- Senden Sie `/trace` (oder `/trace:`) ohne Argument, um die aktuelle Trace-Stufe anzuzeigen.
- `/trace` ist enger gefasst als `/verbose`: Es legt nur Plugin-eigene Trace-/Debug-Zeilen offen, z. B. Active Memory-Debug-Zusammenfassungen.
- Trace-Zeilen können in `/status` und als nachfolgende Diagnosenachricht nach der normalen Assistant-Antwort erscheinen.
- `/trace` ist enger gefasst als `/verbose`: Es legt nur Plugin-eigene Trace-/Debug-Zeilen offen, etwa Active Memory-Debug-Zusammenfassungen.
- Trace-Zeilen können in `/status` und als nachfolgende Diagnosemeldung nach der normalen Assistentenantwort erscheinen.
## Reasoning-Sichtbarkeit (/reasoning)
- Stufen: `on|off|stream`.
- Eine Direktive-only-Nachricht schaltet um, ob Denkblöcke in Antworten angezeigt werden.
- Eine reine Direktivenachricht schaltet um, ob Denkblöcke in Antworten angezeigt werden.
- Wenn aktiviert, wird Reasoning als **separate Nachricht** mit dem Präfix `Reasoning:` gesendet.
- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfsblase, während die Antwort generiert wird, und sendet danach die finale Antwort ohne Reasoning.
- `stream` (nur Telegram): streamt Reasoning in die Telegram-Entwurfsblase, während die Antwort generiert wird, und sendet anschließend die endgültige Antwort ohne Reasoning.
- Alias: `/reason`.
- Senden Sie `/reasoning` (oder `/reasoning:`) ohne Argument, um die aktuelle Reasoning-Stufe anzuzeigen.
- Auflösungsreihenfolge: Inline-Direktive, dann Sitzungsüberschreibung, dann Standard pro Agent (`agents.list[].reasoningDefault`), dann Fallback (`off`).
- Auflösungsreihenfolge: Inline-Direktive, dann Sitzungs-Override, dann Standard pro Agent (`agents.list[].reasoningDefault`), dann Fallback (`off`).
Fehlerhafte Reasoning-Tags lokaler Modelle werden konservativ behandelt. Geschlossene <think>...</think>-Blöcke bleiben bei normalen Antworten ausgeblendet, und nicht geschlossenes Reasoning nach bereits sichtbarem Text wird ebenfalls ausgeblendet. Wenn eine Antwort vollständig in ein einzelnes nicht geschlossenes öffnendes Tag eingeschlossen ist und andernfalls als leerer Text ausgeliefert würde, entfernt OpenClaw das fehlerhafte öffnende Tag und liefert den verbleibenden Text aus.
Fehlgeformte Reasoning-Tags lokaler Modelle werden konservativ behandelt. Geschlossene `<think>...</think>`-Blöcke bleiben bei normalen Antworten verborgen, und nicht geschlossene Reasoning-Anteile nach bereits sichtbarem Text werden ebenfalls verborgen. Wenn eine Antwort vollständig in ein einzelnes nicht geschlossenes öffnendes Tag eingeschlossen ist und andernfalls als leerer Text geliefert würde, entfernt OpenClaw das fehlgeformte öffnende Tag und liefert den verbleibenden Text.
## Siehe auch
## Verwandt
- Die Dokumentation zum erhöhten Modus finden Sie unter [Erhöhter Modus](/de/tools/elevated).
- Dokumentation zum erhöhten Modus finden Sie unter [Erhöhter Modus](/de/tools/elevated).
## Heartbeats
- Der Inhalt der Heartbeat-Prüfung 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 gewohnt (vermeiden Sie jedoch, Sitzungsstandards aus Heartbeats heraus zu ändern).
- Die Heartbeat-Zustellung verwendet standardmäßig nur die finale Nutzlast. Um zusätzlich die separate Nachricht `Reasoning:` zu senden (wenn verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder pro Agent `agents.list[].heartbeat.includeReasoning: true`.
- Der Heartbeat-Probetext 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 aus Heartbeats heraus zu ändern).
- Die Heartbeat-Zustellung verwendet standardmäßig nur die endgültige Nutzlast. Um zusätzlich die separate `Reasoning:`-Nachricht zu senden (wenn verfügbar), setzen Sie `agents.defaults.heartbeat.includeReasoning: true` oder pro Agent `agents.list[].heartbeat.includeReasoning: true`.
## Webchat-UI
- Die Denken-Auswahl im Webchat spiegelt beim Laden der Seite die gespeicherte Stufe der Sitzung aus dem eingehenden Sitzungsspeicher bzw. der Konfiguration wider.
- Wenn Sie eine andere Stufe auswählen, wird die Sitzungsüberschreibung sofort per `sessions.patch` geschrieben; sie wartet nicht auf das nächste Senden und ist keine einmalige `thinkingOnce`-Überschreibung.
- Der Denk-Selector des Webchats spiegelt beim Laden der Seite die gespeicherte Stufe der Sitzung aus dem eingehenden Sitzungsspeicher bzw. der Konfiguration wider.
- Die Auswahl einer anderen Stufe schreibt den Sitzungs-Override sofort über `sessions.patch`; sie wartet nicht auf das nächste Senden und ist kein einmaliger `thinkingOnce`-Override.
- Die erste Option ist immer `Default (<resolved level>)`, wobei der aufgelöste Standard aus dem Provider-Denkprofil des aktiven Sitzungsmodells plus derselben Fallback-Logik stammt, die `/status` und `session_status` verwenden.
- Das Auswahlfeld verwendet `thinkingLevels`, die von der Gateway-Sitzungszeile bzw. den Standardwerten zurückgegeben werden, wobei `thinkingOptions` als Legacy-Label-Liste beibehalten wird. Die Browser-UI hält keine eigene Provider-Regex-Liste vor; Plugins besitzen modellspezifische Stufensätze.
- Das Auswahlfeld verwendet `thinkingLevels`, die von der Gateway-Sitzungszeile bzw. den Standards zurückgegeben werden, wobei `thinkingOptions` als Legacy-Labelliste beibehalten wird. Die Browser-UI führt keine eigene Provider-Regex-Liste; Plugins besitzen modellspezifische Stufensätze.
- `/think:<level>` funktioniert weiterhin und aktualisiert dieselbe gespeicherte Sitzungsstufe, sodass Chat-Direktiven und Auswahlfeld synchron bleiben.
## Provider-Profile
- Provider-Plugins können `resolveThinkingProfile(ctx)` bereitstellen, um die unterstützten Stufen und den Standardwert des Modells zu definieren.
- Provider-Plugins, die Claude-Modelle per Proxy weiterleiten, sollten `resolveClaudeThinkingProfile(modelId)` aus `openclaw/plugin-sdk/provider-model-shared` wiederverwenden, damit direkte Anthropic- und Proxy-Kataloge abgestimmt bleiben.
- Provider-Plugins, die Claude-Modelle per Proxy bereitstellen, sollten `resolveClaudeThinkingProfile(modelId)` aus `openclaw/plugin-sdk/provider-model-shared` wiederverwenden, damit direkte Anthropic- und Proxy-Kataloge synchron bleiben.
- Jede Profilstufe 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" }`.
- Tool-Plugins, die eine explizite Thinking-Überschreibung validieren müssen, sollten `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)` verwenden; sie sollten keine eigenen Provider-/Modell-Stufenlisten pflegen.
- Tool-Plugins mit Zugriff auf konfigurierte benutzerdefinierte Modellmetadaten können `catalog` an `resolveThinkingPolicy` übergeben, damit Opt-ins für `compat.supportedReasoningEfforts` in der Plugin-seitigen Validierung berücksichtigt werden.
- Werkzeug-Plugins, die eine explizite Thinking-Überschreibung validieren müssen, sollten `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)` verwenden; sie sollten keine eigenen Provider-/Modellstufenlisten pflegen.
- Werkzeug-Plugins mit Zugriff auf konfigurierte benutzerdefinierte Modellmetadaten können `catalog` an `resolveThinkingPolicy` übergeben, damit `compat.supportedReasoningEfforts`-Opt-ins in der Plugin-seitigen Validierung berücksichtigt werden.
- Veröffentlichte Legacy-Hooks (`supportsXHighThinking`, `isBinaryThinking` und `resolveDefaultThinkingLevel`) bleiben als Kompatibilitätsadapter bestehen, aber neue benutzerdefinierte Stufensätze sollten `resolveThinkingProfile` verwenden.
- Gateway-Zeilen/-Standardwerte stellen `thinkingLevels`, `thinkingOptions` und `thinkingDefault` bereit, damit ACP-/Chat-Clients dieselben Profil-IDs und Labels rendern, die auch die Laufzeitvalidierung verwendet.
- Gateway-Zeilen/-Standardwerte stellen `thinkingLevels`, `thinkingOptions` und `thinkingDefault` bereit, damit ACP-/Chat-Clients dieselben Profil-IDs und Labels rendern, die auch die Runtime-Validierung verwendet.

379
docs/de/tools/video-generation.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Videos über den Agenten generieren
- Videogenerierungs-Provider und -Modelle konfigurieren
- Parameter des Tools video_generate verstehen
- Provider und Modelle für die Videogenerierung konfigurieren
- Die Parameter des Tools video_generate verstehen
sidebarTitle: Video generation
summary: Generieren Sie Videos über video_generate aus Text-, Bild- oder Videoreferenzen über 16 Provider-Backends hinweg
summary: Videos mit video_generate aus Text-, Bild- oder Videoreferenzen über 16 Provider-Backends hinweg generieren
title: Videogenerierung
x-i18n:
generated_at: "2026-04-30T07:20:12Z"
generated_at: "2026-05-05T01:50:30Z"
model: gpt-5.5
provider: openai
source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf
source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
source_path: tools/video-generation.md
workflow: 16
---
OpenClaw-Agenten können Videos aus Textprompts, Referenzbildern oder
vorhandenen Videos erzeugen. Sechzehn Provider-Backends werden unterstützt,
OpenClaw-Agenten können Videos aus Text-Prompts, Referenzbildern oder
bestehenden Videos generieren. Sechzehn Provider-Backends werden unterstützt,
jeweils mit unterschiedlichen Modelloptionen, Eingabemodi und Funktionsumfängen.
Der Agent wählt anhand Ihrer Konfiguration und der verfügbaren API-Schlüssel
automatisch den richtigen Provider aus.
Der Agent wählt den richtigen Provider automatisch anhand Ihrer Konfiguration
und der verfügbaren API-Schlüssel aus.
<Note>
Das Tool `video_generate` erscheint nur, wenn mindestens ein Provider für
Videogenerierung verfügbar ist. Wenn Sie es in Ihren Agent-Tools nicht sehen,
setzen Sie einen Provider-API-Schlüssel oder konfigurieren Sie
legen Sie einen Provider-API-Schlüssel fest oder konfigurieren Sie
`agents.defaults.videoGenerationModel`.
</Note>
OpenClaw behandelt Videogenerierung als drei Laufzeitmodi:
- `generate` — Text-zu-Video-Anfragen ohne Referenzmedien.
- `imageToVideo` — Anfrage enthält ein oder mehrere Referenzbilder.
- `videoToVideo` — Anfrage enthält ein oder mehrere Referenzvideos.
- `imageToVideo` — die Anfrage enthält ein oder mehrere Referenzbilder.
- `videoToVideo` — die Anfrage enthält ein oder mehrere Referenzvideos.
Provider können beliebige Teilmengen dieser Modi unterstützen. Das Tool
Provider können eine beliebige Teilmenge dieser Modi unterstützen. Das Tool
validiert den aktiven Modus vor dem Absenden und meldet unterstützte Modi in
`action=list`.
@ -42,62 +42,63 @@ validiert den aktiven Modus vor dem Absenden und meldet unterstützte Modi in
<Steps>
<Step title="Authentifizierung konfigurieren">
Setzen Sie einen API-Schlüssel für einen beliebigen unterstützten Provider:
Legen Sie einen API-Schlüssel für einen unterstützten Provider fest:
```bash
export GEMINI_API_KEY="your-key"
```
</Step>
<Step title="Standardmodell auswählen (optional)">
<Step title="Ein Standardmodell auswählen (optional)">
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
</Step>
<Step title="Den Agenten fragen">
> Erzeuge ein 5-sekündiges filmisches Video eines freundlichen Hummers, der bei Sonnenuntergang surft.
> Generieren Sie ein 5-sekündiges filmisches Video eines freundlichen Hummers, der bei Sonnenuntergang surft.
Der Agent ruft `video_generate` automatisch auf. Es ist keine
Tool-Zulassungsliste erforderlich.
Der Agent ruft `video_generate` automatisch auf. Es ist keine Tool-Allowlist
erforderlich.
</Step>
</Steps>
## So funktioniert asynchrone Generierung
## Wie asynchrone Generierung funktioniert
Videogenerierung ist asynchron. Wenn der Agent `video_generate` in einer
Sitzung aufruft:
1. OpenClaw sendet die Anfrage an den Provider und gibt sofort eine Task-ID zurück.
2. Der Provider verarbeitet den Auftrag im Hintergrund (typischerweise 30 Sekunden bis 5 Minuten, abhängig von Provider und Auflösung).
2. Der Provider verarbeitet den Auftrag im Hintergrund (typischerweise 30 Sekunden bis 5 Minuten, je nach Provider und Auflösung).
3. Wenn das Video bereit ist, weckt OpenClaw dieselbe Sitzung mit einem internen Abschlussereignis.
4. Der Agent postet das fertige Video zurück in die ursprüngliche Unterhaltung.
4. Der Agent informiert den Benutzer und hängt das fertige Video an. In Gruppen-/Kanal-
Chats, die nur über das Message-Tool sichtbare Zustellung verwenden, leitet der Agent
das Ergebnis über das Message-Tool weiter, statt dass OpenClaw es direkt postet.
Während ein Auftrag läuft, geben doppelte `video_generate`-Aufrufe in derselben
Sitzung den aktuellen Task-Status zurück, statt eine weitere Generierung zu
starten. Verwenden Sie `openclaw tasks list` oder `openclaw tasks show <taskId>`,
um den Fortschritt über die CLI zu prüfen.
Außerhalb sitzungsgebundener Agent-Ausführungen (zum Beispiel bei direkten
Außerhalb von sitzungsbasierten Agent-Ausführungen (zum Beispiel bei direkten
Tool-Aufrufen) fällt das Tool auf Inline-Generierung zurück und gibt den finalen
Medienpfad im selben Zug zurück.
Medienpfad im selben Durchlauf zurück.
Generierte Videodateien werden im von OpenClaw verwalteten Medienspeicher
gespeichert, wenn der Provider Bytes zurückgibt. Die standardmäßige
Speicherobergrenze für generierte Videos folgt dem Videomedienlimit, und
`agents.defaults.mediaMaxMb` erhöht sie für größere Renderings. Wenn ein
Provider zusätzlich eine gehostete Ausgabe-URL zurückgibt, kann OpenClaw diese
URL ausliefern, statt den Task fehlschlagen zu lassen, wenn die lokale
Persistierung eine zu große Datei ablehnt.
gespeichert, wenn der Provider Bytes zurückgibt. Die standardmäßige Speicherobergrenze
für generierte Videos folgt dem Videomedienlimit, und `agents.defaults.mediaMaxMb`
erhöht sie für größere Renderings. Wenn ein Provider außerdem eine gehostete
Ausgabe-URL zurückgibt, kann OpenClaw diese URL zustellen, statt den Task fehlschlagen
zu lassen, wenn die lokale Persistierung eine zu große Datei ablehnt.
### Task-Lebenszyklus
| Zustand | Bedeutung |
| Status | Bedeutung |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | Task erstellt, wartet darauf, dass der Provider ihn annimmt. |
| `running` | Provider verarbeitet ihn (typischerweise 30 Sekunden bis 5 Minuten, abhängig von Provider und Auflösung). |
| `succeeded` | Video bereit; der Agent wacht auf und postet es in die Unterhaltung. |
| `failed` | Provider-Fehler oder Timeout; der Agent wacht mit Fehlerdetails auf. |
| `queued` | Task erstellt, wartet darauf, dass der Provider ihn annimmt. |
| `running` | Provider verarbeitet (typischerweise 30 Sekunden bis 5 Minuten, je nach Provider und Auflösung). |
| `succeeded` | Video bereit; der Agent wacht auf und postet es in die Unterhaltung. |
| `failed` | Provider-Fehler oder Zeitüberschreitung; der Agent wacht mit Fehlerdetails auf. |
Status über die CLI prüfen:
@ -107,66 +108,66 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
Wenn für die aktuelle Sitzung bereits ein Video-Task `queued` oder `running`
ist, gibt `video_generate` den bestehenden Task-Status zurück, statt einen neuen
zu starten. Verwenden Sie `action: "status"`, um ausdrücklich zu prüfen, ohne
eine neue Generierung auszulösen.
Wenn für die aktuelle Sitzung bereits ein Video-Task `queued` oder `running` ist,
gibt `video_generate` den bestehenden Task-Status zurück, statt einen neuen zu
starten. Verwenden Sie `action: "status"`, um explizit zu prüfen, ohne eine neue
Generierung auszulösen.
## Unterstützte Provider
| Provider | Standardmodell | Text | Bildreferenz | Videoreferenz | Authentifizierung |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Ja (Remote-URL) | Ja (Remote-URL) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Bis zu 2 Bilder (nur I2V-Modelle; erstes + letztes Frame) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Bis zu 2 Bilder (erstes + letztes Frame über Rolle) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Bis zu 9 Referenzbilder | Bis zu 3 Videos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 Bild | — | `COMFY_API_KEY` oder `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 Bild; bis zu 9 mit Seedance Reference-to-Video | Bis zu 3 Videos mit Seedance Reference-to-Video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 Bild | 1 Video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 Bild | — | `MINIMAX_API_KEY` oder MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 Bild | 1 Video | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Bis zu 4 Bilder (erstes/letztes Frame oder Referenzen) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Ja (Remote-URL) | Ja (Remote-URL) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 Bild | 1 Video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 Bild | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 Bild (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 Erst-Frame-Bild oder bis zu 7 `reference_image`s | 1 Video | `XAI_API_KEY` |
| Provider | Standardmodell | Text | Bildreferenz | Videoreferenz | Authentifizierung |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ---------------------------------------------- | ----------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Ja (Remote-URL) | Ja (Remote-URL) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Bis zu 2 Bilder (nur I2V-Modelle; erstes + letztes Frame) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Bis zu 2 Bilder (erstes + letztes Frame über Rolle) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Bis zu 9 Referenzbilder | Bis zu 3 Videos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 Bild | — | `COMFY_API_KEY` oder `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 Bild; bis zu 9 mit Seedance reference-to-video | Bis zu 3 Videos mit Seedance reference-to-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 Bild | 1 Video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 Bild | — | `MINIMAX_API_KEY` oder MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 Bild | 1 Video | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Bis zu 4 Bilder (erstes/letztes Frame oder Referenzen) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Ja (Remote-URL) | Ja (Remote-URL) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 Bild | 1 Video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 Bild | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 Bild (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 Erst-Frame-Bild oder bis zu 7 `reference_image`s | 1 Video | `XAI_API_KEY` |
Einige Provider akzeptieren zusätzliche oder alternative API-Schlüssel-Umgebungsvariablen.
Details finden Sie auf den einzelnen [Provider-Seiten](#related).
Führen Sie `video_generate action=list` aus, um verfügbare Provider, Modelle
und Laufzeitmodi zur Laufzeit zu prüfen.
Führen Sie `video_generate action=list` aus, um verfügbare Provider, Modelle und
Laufzeitmodi zur Laufzeit zu prüfen.
### Funktionsmatrix
### Fähigkeitsmatrix
Der explizite Modusvertrag, der von `video_generate`, Vertragstests und dem
gemeinsamen Live-Sweep verwendet wird:
| Provider | `generate` | `imageToVideo` | `videoToVideo` | Gemeinsame Live-Lanes heute |
| Provider | `generate` | `imageToVideo` | `videoToVideo` | Gemeinsame Live-Lanes heute |
| ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` übersprungen, da dieser Provider Remote-`http(s)`-Video-URLs benötigt |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider Remote-`http(s)`-Video-URLs benötigt |
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | Nicht im gemeinsamen Sweep; workflow-spezifische Abdeckung liegt bei den Comfy-Tests |
| DeepInfra | ✓ | — | — | `generate`; native DeepInfra-Videoschemas sind Text-zu-Video im gebündelten Vertrag |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` nur bei Verwendung von Seedance Reference-to-Video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; gemeinsames `videoToVideo` übersprungen, da der aktuelle pufferbasierte Gemini/Veo-Sweep diese Eingabe nicht akzeptiert |
| ComfyUI | ✓ | ✓ | — | Nicht im gemeinsamen Sweep; workflow-spezifische Abdeckung liegt bei Comfy-Tests |
| DeepInfra | ✓ | — | — | `generate`; native DeepInfra-Videoschemata sind im gebündelten Vertrag Text-zu-Video |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` nur bei Verwendung von Seedance reference-to-video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; gemeinsames `videoToVideo` übersprungen, weil der aktuelle pufferbasierte Gemini/Veo-Sweep diese Eingabe nicht akzeptiert |
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; gemeinsames `videoToVideo` übersprungen, da dieser Organisations-/Eingabepfad derzeit Provider-seitigen Inpaint-/Remix-Zugriff benötigt |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; gemeinsames `videoToVideo` übersprungen, weil dieser Org-/Eingabepfad derzeit Provider-seitigen Inpaint-/Remix-Zugriff benötigt |
| OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` übersprungen, da dieser Provider Remote-`http(s)`-Video-URLs benötigt |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider Remote-`http(s)`-Video-URLs benötigt |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` läuft nur, wenn das ausgewählte Modell `runway/gen4_aleph` ist |
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`; gemeinsames `imageToVideo` übersprungen, da das gebündelte `veo3` nur Text unterstützt und das gebündelte `kling` eine Remote-Bild-URL erfordert |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` übersprungen, da dieser Provider derzeit eine Remote-MP4-URL benötigt |
| Vydra | ✓ | ✓ | — | `generate`; gemeinsames `imageToVideo` übersprungen, weil gebündeltes `veo3` nur Text unterstützt und gebündeltes `kling` eine Remote-Bild-URL erfordert |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` übersprungen, weil dieser Provider derzeit eine Remote-MP4-URL benötigt |
## Tool-Parameter
### Erforderlich
<ParamField path="prompt" type="string" required>
Textbeschreibung des zu erzeugenden Videos. Erforderlich für `action: "generate"`.
Textbeschreibung des zu generierenden Videos. Erforderlich für `action: "generate"`.
</ParamField>
### Inhaltseingaben
@ -184,7 +185,7 @@ Optionale positionsbezogene Rollenhinweise parallel zur kombinierten Videoliste.
Kanonischer Wert: `reference_video`.
</ParamField>
<ParamField path="audioRef" type="string">
Einzelnes Referenzaudio (Pfad oder URL). Wird für Hintergrundmusik oder als
Einzelnes Referenzaudio (Pfad oder URL). Wird für Hintergrundmusik oder
Stimmreferenz verwendet, wenn der Provider Audioeingaben unterstützt.
</ParamField>
<ParamField path="audioRefs" type="string[]">Mehrere Referenzaudios (bis zu 3).</ParamField>
@ -194,15 +195,13 @@ Kanonischer Wert: `reference_audio`.
</ParamField>
<Note>
Rollenhinweise werden unverändert an den Provider weitergeleitet. Kanonische
Werte stammen aus der Union `VideoGenerationAssetRole`, aber Provider können
zusätzliche Rollen-Strings akzeptieren. `*Roles`-Arrays dürfen nicht mehr
Einträge haben als die entsprechende Referenzliste; Off-by-one-Fehler schlagen
mit einer klaren Fehlermeldung fehl. Verwenden Sie eine leere Zeichenfolge,
um einen Slot nicht festzulegen. Für xAI setzen Sie jede Bildrolle auf
`reference_image`, um den Generierungsmodus `reference_images` zu verwenden;
lassen Sie die Rolle weg oder verwenden Sie `first_frame` für Bild-zu-Video
mit einem einzelnen Bild.
Rollenhinweise werden unverändert an den Provider weitergeleitet. Kanonische Werte stammen aus
der Union `VideoGenerationAssetRole`, aber Provider können zusätzliche
Rollenzeichenfolgen akzeptieren. `*Roles`-Arrays dürfen nicht mehr Einträge haben als die
entsprechende Referenzliste; Off-by-one-Fehler schlagen mit einem klaren Fehler fehl.
Verwenden Sie eine leere Zeichenfolge, um einen Slot nicht zu setzen. Setzen Sie bei xAI jede Bildrolle auf
`reference_image`, um dessen Generierungsmodus `reference_images` zu verwenden; lassen Sie die
Rolle weg oder verwenden Sie `first_frame` für Einzelbild-Bild-zu-Video.
</Note>
### Stilsteuerungen
@ -212,47 +211,45 @@ mit einem einzelnen Bild.
</ParamField>
<ParamField path="resolution" type="string">`480P`, `720P`, `768P` oder `1080P`.</ParamField>
<ParamField path="durationSeconds" type="number">
Zieldauer in Sekunden (auf den nächstgelegenen vom Provider unterstützten Wert gerundet).
Zieldauer in Sekunden (auf den nächsten vom Provider unterstützten Wert gerundet).
</ParamField>
<ParamField path="size" type="string">Größenhinweis, wenn der Provider ihn unterstützt.</ParamField>
<ParamField path="audio" type="boolean">
Aktivieren Sie generiertes Audio in der Ausgabe, wenn unterstützt. Unterschiedlich von `audioRef*` (Eingaben).
Generiertes Audio in der Ausgabe aktivieren, wenn unterstützt. Unterscheidet sich von `audioRef*` (Eingaben).
</ParamField>
<ParamField path="watermark" type="boolean">Provider-Wasserzeichen umschalten, wenn unterstützt.</ParamField>
`adaptive` ist ein Provider-spezifischer Sentinel: Er wird unverändert an
Provider weitergeleitet, die `adaptive` in ihren Fähigkeiten deklarieren
(z. B. verwendet BytePlus Seedance dies, um das Seitenverhältnis automatisch
aus den Abmessungen des Eingabebilds zu erkennen). Provider, die dies nicht
deklarieren, zeigen den Wert über `details.ignoredOverrides` im Tool-Ergebnis
an, sodass das Verwerfen sichtbar ist.
Provider weitergeleitet, die `adaptive` in ihren Fähigkeiten deklarieren (z. B. verwendet BytePlus
Seedance dies, um das Verhältnis automatisch aus den Abmessungen des Eingabebilds
zu erkennen). Provider, die dies nicht deklarieren, geben den Wert über
`details.ignoredOverrides` im Tool-Ergebnis aus, damit das Verwerfen sichtbar ist.
### Erweitert
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` gibt die aktuelle Session-Aufgabe zurück; `"list"` prüft Provider.
`"status"` gibt die aktuelle Sitzungsaufgabe zurück; `"list"` inspiziert Provider.
</ParamField>
<ParamField path="model" type="string">Provider-/Modell-Override (z. B. `runway/gen4.5`).</ParamField>
<ParamField path="model" type="string">Provider-/Modellüberschreibung (z. B. `runway/gen4.5`).</ParamField>
<ParamField path="filename" type="string">Hinweis für den Ausgabedateinamen.</ParamField>
<ParamField path="timeoutMs" type="number">Optionales Timeout für Provider-Anfragen in Millisekunden.</ParamField>
<ParamField path="timeoutMs" type="number">Optionales Provider-Anfrage-Timeout in Millisekunden.</ParamField>
<ParamField path="providerOptions" type="object">
Provider-spezifische Optionen als JSON-Objekt (z. B. `{"seed": 42, "draft": true}`).
Provider, die ein typisiertes Schema deklarieren, validieren die Schlüssel und Typen;
unbekannte Schlüssel oder Nichtübereinstimmungen überspringen den Kandidaten während
des Fallbacks. Provider ohne deklariertes Schema erhalten die Optionen unverändert.
Führen Sie `video_generate action=list` aus, um zu sehen, was jeder Provider akzeptiert.
Provider, die ein typisiertes Schema deklarieren, validieren die Schlüssel und Typen; unbekannte
Schlüssel oder Abweichungen überspringen den Kandidaten während des Fallbacks. Provider ohne
deklariertes Schema erhalten die Optionen unverändert. Führen Sie `video_generate action=list` aus,
um zu sehen, was jeder Provider akzeptiert.
</ParamField>
<Note>
Nicht alle Provider unterstützen alle Parameter. OpenClaw normalisiert die
Dauer auf den nächstgelegenen vom Provider unterstützten Wert und ordnet
übersetzte Geometriehinweise wie Größe-zu-Seitenverhältnis neu zu, wenn ein
Fallback-Provider eine andere Steuerungsoberfläche bereitstellt. Wirklich
nicht unterstützte Overrides werden nach bestem Aufwand ignoriert und im
Tool-Ergebnis als Warnungen gemeldet. Harte Fähigkeitsgrenzen (z. B. zu viele
Referenzeingaben) schlagen vor dem Absenden fehl. Tool-Ergebnisse melden die
angewendeten Einstellungen; `details.normalization` erfasst jede Übersetzung
von angefragt zu angewendet.
Nicht alle Provider unterstützen alle Parameter. OpenClaw normalisiert die Dauer auf
den nächstliegenden vom Provider unterstützten Wert und ordnet übersetzte Geometriehinweise
wie Größe-zu-Seitenverhältnis neu zu, wenn ein Fallback-Provider eine andere
Steuerungsoberfläche bereitstellt. Wirklich nicht unterstützte Überschreibungen werden nach Best Effort
ignoriert und im Tool-Ergebnis als Warnungen gemeldet. Harte Fähigkeitsgrenzen
(wie zu viele Referenzeingaben) schlagen vor der Übermittlung fehl. Tool-Ergebnisse
melden angewendete Einstellungen; `details.normalization` erfasst jede
Übersetzung von angefordert zu angewendet.
</Note>
Referenzeingaben wählen den Laufzeitmodus aus:
@ -260,9 +257,9 @@ Referenzeingaben wählen den Laufzeitmodus aus:
- Keine Referenzmedien → `generate`
- Beliebige Bildreferenz → `imageToVideo`
- Beliebige Videoreferenz → `videoToVideo`
- Referenzaudio-Eingaben ändern den aufgelösten Modus **nicht**; sie werden
zusätzlich zu dem Modus angewendet, den die Bild-/Videoreferenzen auswählen,
und funktionieren nur mit Providern, die `maxInputAudios` deklarieren.
- Referenzaudioeingaben ändern den aufgelösten Modus **nicht**; sie werden zusätzlich
zu dem Modus angewendet, den die Bild-/Videoreferenzen auswählen, und funktionieren nur
mit Providern, die `maxInputAudios` deklarieren.
Gemischte Bild- und Videoreferenzen sind keine stabile gemeinsame Fähigkeitsoberfläche.
Bevorzugen Sie einen Referenztyp pro Anfrage.
@ -270,54 +267,50 @@ Bevorzugen Sie einen Referenztyp pro Anfrage.
#### Fallback und typisierte Optionen
Einige Fähigkeitsprüfungen werden auf der Fallback-Ebene statt an der
Tool-Grenze angewendet, sodass eine Anfrage, die die Grenzen des primären
Providers überschreitet, weiterhin auf einem geeigneten Fallback ausgeführt
werden kann:
Tool-Grenze angewendet, sodass eine Anfrage, die die Grenzen des primären Providers überschreitet,
trotzdem auf einem fähigen Fallback ausgeführt werden kann:
- Aktiver Kandidat, der kein `maxInputAudios` (oder `0`) deklariert, wird
übersprungen, wenn die Anfrage Audioreferenzen enthält; der nächste Kandidat
wird ausprobiert.
- `maxDurationSeconds` des aktiven Kandidaten liegt unter dem angefragten
`durationSeconds` und es gibt keine deklarierte Liste `supportedDurationSeconds`
→ übersprungen.
- Anfrage enthält `providerOptions` und der aktive Kandidat deklariert explizit
ein typisiertes `providerOptions`-Schema → übersprungen, wenn bereitgestellte
Schlüssel nicht im Schema enthalten sind oder Werttypen nicht übereinstimmen.
Provider ohne deklariertes Schema erhalten Optionen unverändert
(rückwärtskompatible Durchreichung). Ein Provider kann alle Provider-Optionen
ablehnen, indem er ein leeres Schema deklariert (`capabilities.providerOptions: {}`),
was zum gleichen Überspringen wie eine Typabweichung führt.
- Aktiver Kandidat, der kein `maxInputAudios` (oder `0`) deklariert, wird übersprungen, wenn
die Anfrage Audioreferenzen enthält; der nächste Kandidat wird versucht.
- `maxDurationSeconds` des aktiven Kandidaten liegt unter dem angeforderten `durationSeconds`
ohne deklarierte Liste `supportedDurationSeconds` → übersprungen.
- Anfrage enthält `providerOptions` und der aktive Kandidat deklariert ausdrücklich
ein typisiertes `providerOptions`-Schema → übersprungen, wenn bereitgestellte Schlüssel
nicht im Schema enthalten sind oder Werttypen nicht übereinstimmen. Provider ohne
deklariertes Schema erhalten Optionen unverändert (rückwärtskompatible
Durchreichung). Ein Provider kann alle Provider-Optionen ablehnen, indem er
ein leeres Schema deklariert (`capabilities.providerOptions: {}`), was
dasselbe Überspringen wie eine Typabweichung verursacht.
Der erste Überspringgrund in einer Anfrage wird mit `warn` protokolliert,
damit Betreiber sehen, wenn ihr primärer Provider übergangen wurde; nachfolgende
Überspringvorgänge werden mit `debug` protokolliert, um lange Fallback-Ketten
ruhig zu halten. Wenn jeder Kandidat übersprungen wird, enthält der aggregierte
Fehler den Überspringgrund für jeden Kandidaten.
Der erste Überspringgrund in einer Anfrage wird mit `warn` protokolliert, damit Betreiber sehen,
wann ihr primärer Provider übergangen wurde; nachfolgende Übersprünge werden mit `debug` protokolliert, um
lange Fallback-Ketten ruhig zu halten. Wenn jeder Kandidat übersprungen wird, enthält der
aggregierte Fehler den Überspringgrund für jeden.
## Aktionen
| Aktion | Was sie tut |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `generate` | Standard. Erstellt ein Video aus dem angegebenen Prompt und optionalen Referenzeingaben. |
| `status` | Prüft den Status der laufenden Videoaufgabe für die aktuelle Session, ohne eine weitere Generierung zu starten. |
| `list` | Zeigt verfügbare Provider, Modelle und deren Fähigkeiten an. |
| Aktion | Was es bewirkt |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `generate` | Standard. Erstellt ein Video aus dem angegebenen Prompt und optionalen Referenzeingaben. |
| `status` | Prüft den Status der laufenden Videoaufgabe für die aktuelle Sitzung, ohne eine weitere Generierung zu starten. |
| `list` | Zeigt verfügbare Provider, Modelle und deren Fähigkeiten an. |
## Modellauswahl
OpenClaw löst das Modell in dieser Reihenfolge auf:
1. **`model`-Tool-Parameter** — wenn der Agent einen im Aufruf angibt.
1. **Tool-Parameter `model`** — wenn der Agent einen im Aufruf angibt.
2. **`videoGenerationModel.primary`** aus der Konfiguration.
3. **`videoGenerationModel.fallbacks`** der Reihe nach.
3. **`videoGenerationModel.fallbacks`** in Reihenfolge.
4. **Automatische Erkennung** — Provider mit gültiger Authentifizierung, beginnend mit dem
aktuellen Standard-Provider, danach die verbleibenden Provider in alphabetischer
aktuellen Standard-Provider, danach verbleibende Provider in alphabetischer
Reihenfolge.
Wenn ein Provider fehlschlägt, wird der nächste Kandidat automatisch ausprobiert.
Wenn alle Kandidaten fehlschlagen, enthält der Fehler Details zu jedem Versuch.
Wenn ein Provider fehlschlägt, wird automatisch der nächste Kandidat versucht. Wenn alle
Kandidaten fehlschlagen, enthält der Fehler Details aus jedem Versuch.
Setzen Sie `agents.defaults.mediaGenerationAutoProviderFallback: false`, um
nur die expliziten Einträge `model`, `primary` und `fallbacks` zu verwenden.
nur die ausdrücklichen Einträge `model`, `primary` und `fallbacks` zu verwenden.
```json5
{
@ -336,8 +329,8 @@ nur die expliziten Einträge `model`, `primary` und `fallbacks` zu verwenden.
<AccordionGroup>
<Accordion title="Alibaba">
Verwendet den asynchronen Endpunkt von DashScope / Model Studio. Referenzbilder
und -videos müssen entfernte `http(s)`-URLs sein.
Verwendet den asynchronen Endpunkt von DashScope / Model Studio. Referenzbilder und
-videos müssen entfernte `http(s)`-URLs sein.
</Accordion>
<Accordion title="BytePlus (1.0)">
Provider-ID: `byteplus`.
@ -347,13 +340,13 @@ nur die expliziten Einträge `model`, `primary` und `fallbacks` zu verwenden.
`seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`.
T2V-Modelle (`*-t2v-*`) akzeptieren keine Bildeingaben; I2V-Modelle und
allgemeine `*-pro-*`-Modelle unterstützen ein einzelnes Referenzbild
(erstes Frame). Übergeben Sie das Bild positionsbezogen oder setzen Sie
`role: "first_frame"`. T2V-Modell-IDs werden automatisch auf die entsprechende
I2V-Variante umgestellt, wenn ein Bild bereitgestellt wird.
allgemeine `*-pro-*`-Modelle unterstützen ein einzelnes Referenzbild (erstes
Frame). Übergeben Sie das Bild positionsbezogen oder setzen Sie `role: "first_frame"`.
T2V-Modell-IDs werden automatisch auf die entsprechende I2V-Variante
umgestellt, wenn ein Bild bereitgestellt wird.
Unterstützte `providerOptions`-Schlüssel: `seed` (number), `draft` (boolean —
erzwingt 480p), `camera_fixed` (boolean).
Unterstützte `providerOptions`-Schlüssel: `seed` (Zahl), `draft` (Boolean —
erzwingt 480p), `camera_fixed` (Boolean).
</Accordion>
<Accordion title="BytePlus Seedance 1.5">
@ -361,14 +354,14 @@ nur die expliziten Einträge `model`, `primary` und `fallbacks` zu verwenden.
Provider-ID: `byteplus-seedance15`. Modell:
`seedance-1-5-pro-251215`.
Verwendet die einheitliche `content[]`-API. Unterstützt höchstens 2 Eingabebilder
(`first_frame` + `last_frame`). Alle Eingaben müssen entfernte `https://`-URLs
sein. Setzen Sie `role: "first_frame"` / `"last_frame"` für jedes Bild, oder
Verwendet die einheitliche API `content[]`. Unterstützt höchstens 2 Eingabebilder
(`first_frame` + `last_frame`). Alle Eingaben müssen entfernte `https://`-
URLs sein. Setzen Sie `role: "first_frame"` / `"last_frame"` für jedes Bild oder
übergeben Sie Bilder positionsbezogen.
`aspectRatio: "adaptive"` erkennt das Seitenverhältnis automatisch aus dem Eingabebild.
`aspectRatio: "adaptive"` erkennt das Verhältnis automatisch aus dem Eingabebild.
`audio: true` wird auf `generate_audio` abgebildet. `providerOptions.seed`
(number) wird weitergeleitet.
(Zahl) wird weitergeleitet.
</Accordion>
<Accordion title="BytePlus Seedance 2.0">
@ -377,15 +370,15 @@ nur die expliziten Einträge `model`, `primary` und `fallbacks` zu verwenden.
`dreamina-seedance-2-0-260128`,
`dreamina-seedance-2-0-fast-260128`.
Verwendet die einheitliche `content[]`-API. Unterstützt bis zu 9 Referenzbilder,
Verwendet die einheitliche API `content[]`. Unterstützt bis zu 9 Referenzbilder,
3 Referenzvideos und 3 Referenzaudios. Alle Eingaben müssen entfernte
`https://`-URLs sein. Setzen Sie `role` für jedes Asset — unterstützte Werte:
`"first_frame"`, `"last_frame"`, `"reference_image"`,
`"reference_video"`, `"reference_audio"`.
`aspectRatio: "adaptive"` erkennt das Seitenverhältnis automatisch aus dem Eingabebild.
`aspectRatio: "adaptive"` erkennt das Verhältnis automatisch aus dem Eingabebild.
`audio: true` wird auf `generate_audio` abgebildet. `providerOptions.seed`
(number) wird weitergeleitet.
(Zahl) wird weitergeleitet.
</Accordion>
<Accordion title="ComfyUI">
@ -393,58 +386,56 @@ nur die expliziten Einträge `model`, `primary` und `fallbacks` zu verwenden.
Bild-zu-Video über den konfigurierten Graphen.
</Accordion>
<Accordion title="fal">
Verwendet einen warteschlangengestützten Ablauf für lang laufende Jobs. Die meisten
fal-Videomodelle akzeptieren eine einzelne Bildreferenz. Seedance-2.0-Referenz-zu-Video-
Modelle akzeptieren bis zu 9 Bilder, 3 Videos und 3 Audioreferenzen mit
Verwendet einen warteschlangenbasierten Ablauf für lang laufende Aufträge. Die meisten fal-Videomodelle
akzeptieren eine einzelne Bildreferenz. Seedance-2.0-Referenz-zu-Video-
Modelle akzeptieren bis zu 9 Bilder, 3 Videos und 3 Audioreferenzen, mit
höchstens 12 Referenzdateien insgesamt.
</Accordion>
<Accordion title="Google (Gemini / Veo)">
Unterstützt eine Bild- oder eine Videoreferenz.
</Accordion>
<Accordion title="MiniMax">
Nur einzelne Bildreferenz.
Nur eine einzelne Bildreferenz.
</Accordion>
<Accordion title="OpenAI">
Nur der `size`-Override wird weitergeleitet. Andere Stil-Overrides
(`aspectRatio`, `resolution`, `audio`, `watermark`) werden mit einer
Warnung ignoriert.
Nur die Überschreibung `size` wird weitergeleitet. Andere Stilüberschreibungen
(`aspectRatio`, `resolution`, `audio`, `watermark`) werden mit
einer Warnung ignoriert.
</Accordion>
<Accordion title="OpenRouter">
Verwendet die asynchrone `/videos`-API von OpenRouter. OpenClaw sendet den
Job, fragt `polling_url` ab und lädt entweder `unsigned_urls` oder den
dokumentierten Inhaltsendpunkt des Jobs herunter. Der gebündelte Standard
`google/veo-3.1-fast` bewirbt Dauern von 4/6/8 Sekunden, Auflösungen
`720P`/`1080P` und Seitenverhältnisse `16:9`/`9:16`.
Verwendet die asynchrone API `/videos` von OpenRouter. OpenClaw übermittelt den
Auftrag, pollt `polling_url` und lädt entweder `unsigned_urls` oder den
dokumentierten Inhaltsendpunkt des Auftrags herunter. Der gebündelte Standard `google/veo-3.1-fast`
weist Dauern von 4/6/8 Sekunden, Auflösungen `720P`/`1080P` und
Seitenverhältnisse `16:9`/`9:16` aus.
</Accordion>
<Accordion title="Qwen">
Dasselbe DashScope-Backend wie Alibaba. Referenzeingaben müssen entfernte
`http(s)`-URLs sein; lokale Dateien werden im Voraus abgelehnt.
`http(s)`-URLs sein; lokale Dateien werden vorab abgelehnt.
</Accordion>
<Accordion title="Runway">
Unterstützt lokale Dateien über Daten-URIs. Video-zu-Video erfordert
`runway/gen4_aleph`. Reine Textläufe stellen Seitenverhältnisse `16:9`
und `9:16` bereit.
`runway/gen4_aleph`. Reine Textläufe stellen die Seitenverhältnisse `16:9` und `9:16`
bereit.
</Accordion>
<Accordion title="Together">
Nur einzelne Bildreferenz.
Nur eine einzelne Bildreferenz.
</Accordion>
<Accordion title="Vydra">
Verwendet `https://www.vydra.ai/api/v1` direkt, um Weiterleitungen zu vermeiden,
die Authentifizierung entfernen. `veo3` ist nur als Text-zu-Video gebündelt;
`kling` erfordert eine entfernte Bild-URL.
die Authentifizierung verwerfen. `veo3` wird nur als Text-zu-Video gebündelt; `kling` erfordert
eine entfernte Bild-URL.
</Accordion>
<Accordion title="xAI">
Unterstützt Text-zu-Video, Bild-zu-Video mit einem einzelnen ersten Frame, bis zu
7 `reference_image`-Eingaben über xAI `reference_images` sowie entfernte
Unterstützt Text-zu-Video, Einzelbild-Bild-zu-Video mit erstem Frame, bis zu 7
`reference_image`-Eingaben über xAI `reference_images` sowie entfernte
Video-Bearbeitungs-/Erweiterungsabläufe.
</Accordion>
</AccordionGroup>
## Provider-Fähigkeitsmodi
Der gemeinsame Vertrag für die Videogenerierung unterstützt modusbezogene Fähigkeiten
statt nur flacher aggregierter Limits. Neue Provider-Implementierungen
sollten explizite Modusblöcke bevorzugen:
Der gemeinsame Vertrag für die Videogenerierung unterstützt moduspezifische Fähigkeiten statt nur flacher aggregierter Grenzwerte. Neue Provider-Implementierungen sollten explizite Modusblöcke bevorzugen:
```typescript
capabilities: {
@ -469,19 +460,13 @@ capabilities: {
}
```
Flache aggregierte Felder wie `maxInputImages` und `maxInputVideos` reichen
**nicht** aus, um Unterstützung für Transformationsmodi auszuweisen. Provider sollten
`generate`, `imageToVideo` und `videoToVideo` explizit deklarieren, damit Live-Tests,
Vertragstests und das gemeinsame Tool `video_generate` die Modusunterstützung
deterministisch validieren können.
Flache aggregierte Felder wie `maxInputImages` und `maxInputVideos` reichen **nicht** aus, um Unterstützung für Transformationsmodi auszuweisen. Provider sollten `generate`, `imageToVideo` und `videoToVideo` explizit deklarieren, damit Live-Tests, Vertragstests und das gemeinsame `video_generate`-Tool die Modusunterstützung deterministisch validieren können.
Wenn ein Modell in einem Provider breitere Unterstützung für Referenzeingaben hat als
die übrigen, verwenden Sie `maxInputImagesByModel`, `maxInputVideosByModel` oder
`maxInputAudiosByModel`, statt das modusweite Limit zu erhöhen.
Wenn ein Modell in einem Provider breitere Unterstützung für Referenzeingaben hat als die übrigen, verwenden Sie `maxInputImagesByModel`, `maxInputVideosByModel` oder `maxInputAudiosByModel`, statt den modusweiten Grenzwert zu erhöhen.
## Live-Tests
Optionale Live-Abdeckung für die gemeinsamen gebündelten Provider:
Opt-in-Live-Abdeckung für die gemeinsamen gebündelten Provider:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -493,32 +478,24 @@ Repo-Wrapper:
pnpm test:live:media video
```
Diese Live-Datei lädt fehlende Provider-Umgebungsvariablen aus `~/.profile`, bevorzugt
standardmäßig Live-/Umgebungs-API-Schlüssel vor gespeicherten Authentifizierungsprofilen
und führt standardmäßig einen release-sicheren Smoke-Test aus:
Diese Live-Datei lädt fehlende Provider-Umgebungsvariablen aus `~/.profile`, bevorzugt standardmäßig Live-/Env-API-Schlüssel vor gespeicherten Auth-Profilen und führt standardmäßig einen release-sicheren Smoke-Test aus:
- `generate` für jeden Nicht-FAL-Provider im Sweep.
- Einsekündiger Hummer-Prompt.
- Vorgangslimit pro Provider aus
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` standardmäßig).
- Operationslimit pro Provider aus `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` standardmäßig).
FAL ist optional, da die Queue-Latenz auf Provider-Seite die Release-Zeit dominieren kann:
FAL ist Opt-in, weil die Queue-Latenz auf Provider-Seite die Release-Zeit dominieren kann:
```bash
pnpm test:live:media video --video-providers fal
```
Setzen Sie `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, um zusätzlich deklarierte
Transformationsmodi auszuführen, die der gemeinsame Sweep sicher mit lokalen Medien
ausüben kann:
Setzen Sie `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, um auch deklarierte Transformationsmodi auszuführen, die der gemeinsame Sweep sicher mit lokalen Medien testen kann:
- `imageToVideo`, wenn `capabilities.imageToVideo.enabled`.
- `videoToVideo`, wenn `capabilities.videoToVideo.enabled` und der
Provider/das Modell pufferbasierte lokale Videoeingaben im gemeinsamen
Sweep akzeptiert.
- `videoToVideo`, wenn `capabilities.videoToVideo.enabled` und der Provider/das Modell buffer-gestützte lokale Videoeingaben im gemeinsamen Sweep akzeptiert.
Derzeit deckt die gemeinsame `videoToVideo`-Live-Lane `runway` nur ab, wenn Sie
`runway/gen4_aleph` auswählen.
Derzeit deckt die gemeinsame `videoToVideo`-Live-Lane `runway` nur ab, wenn Sie `runway/gen4_aleph` auswählen.
## Konfiguration
@ -543,7 +520,7 @@ Oder über die CLI:
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"
```
## Verwandt
## Verwandte Themen
- [Alibaba Model Studio](/de/providers/alibaba)
- [Hintergrundaufgaben](/de/automation/tasks) — Aufgabenverfolgung für asynchrone Videogenerierung

128
docs/de/web/dashboard.md
View File

@ -1,108 +1,112 @@
---
read_when:
- Ändern der Authentifizierung oder der Freigabemodi des Dashboards
summary: Zugriff auf das Gateway-Dashboard (Control UI) und Authentifizierung
title: Dashboard
- Dashboard-Authentifizierung oder Expositionsmodi ändern
summary: Zugriff und Authentifizierung für das Gateway-Dashboard (Control UI)
title: Übersicht
x-i18n:
generated_at: "2026-04-25T13:59:41Z"
model: gpt-5.4
generated_at: "2026-05-05T01:50:44Z"
model: gpt-5.5
provider: openai
source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a
source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1
source_path: web/dashboard.md
workflow: 15
workflow: 16
---
Das Gateway-Dashboard ist die browserbasierte Control UI, die standardmäßig unter `/` bereitgestellt wird
(überschreibbar mit `gateway.controlUi.basePath`).
(überschreiben mit `gateway.controlUi.basePath`).
Schnell öffnen (lokales Gateway):
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (oder [http://localhost:18789/](http://localhost:18789/))
- Mit `gateway.tls.enabled: true` verwende `https://127.0.0.1:18789/` und
- Mit `gateway.tls.enabled: true` verwenden Sie `https://127.0.0.1:18789/` und
`wss://127.0.0.1:18789` für den WebSocket-Endpunkt.
Wichtige Referenzen:
- [Control UI](/de/web/control-ui) für Nutzung und UI-Funktionen.
- [Tailscale](/de/gateway/tailscale) für die Automatisierung mit Serve/Funnel.
- [Web surfaces](/de/web) für Bindungsmodi und Sicherheitshinweise.
- [Tailscale](/de/gateway/tailscale) für Serve/Funnel-Automatisierung.
- [Web-Oberflächen](/de/web) für Bind-Modi und Sicherheitshinweise.
Die Authentifizierung wird beim WebSocket-Handshake über den konfigurierten Gateway-
Authentifizierungspfad erzwungen:
- `connect.params.auth.token`
- `connect.params.auth.password`
- Tailscale-Serve-Identity-Header, wenn `gateway.auth.allowTailscale: true`
- Identity-Header vertrauenswürdiger Proxys, wenn `gateway.auth.mode: "trusted-proxy"`
- Tailscale Serve-Identitäts-Header, wenn `gateway.auth.allowTailscale: true`
- Trusted-Proxy-Identitäts-Header, wenn `gateway.auth.mode: "trusted-proxy"`
Siehe `gateway.auth` in der [Gateway-Konfiguration](/de/gateway/configuration).
Sicherheitshinweis: Die Control UI ist eine **Admin-Oberfläche** (Chat, Konfiguration, Ausführungsfreigaben).
Sie sollte nicht öffentlich zugänglich gemacht werden. Die UI speichert Dashboard-URL-Token in `sessionStorage`
Sicherheitshinweis: Die Control UI ist eine **Admin-Oberfläche** (Chat, Konfiguration, Ausführungsgenehmigungen).
Machen Sie sie nicht öffentlich zugänglich. Die UI speichert Dashboard-URL-Tokens in sessionStorage
für die aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL und entfernt sie nach dem Laden aus der URL.
Bevorzuge localhost, Tailscale Serve oder einen SSH-Tunnel.
Bevorzugen Sie localhost, Tailscale Serve oder einen SSH-Tunnel.
## Schnellpfad (empfohlen)
## Schneller Weg (empfohlen)
- Nach dem Onboarding öffnet die CLI das Dashboard automatisch und gibt einen sauberen Link ohne Token aus.
- Jederzeit erneut öffnen: `openclaw dashboard` (kopiert den Link, öffnet den Browser, wenn möglich, und zeigt einen SSH-Hinweis an, wenn headless).
- Wenn die UI nach einer Authentifizierung mit gemeinsamem Geheimnis fragt, füge das konfigurierte Token oder
- Nach dem Onboarding öffnet die CLI automatisch das Dashboard und gibt einen sauberen (nicht tokenisierten) Link aus.
- Jederzeit erneut öffnen: `openclaw dashboard` (kopiert den Link, öffnet wenn möglich den Browser, zeigt bei Headless-Umgebungen einen SSH-Hinweis).
- Wenn Zwischenablage und Browser-Übergabe fehlschlagen, gibt `openclaw dashboard` trotzdem die
saubere URL aus und weist Sie an, das Token aus `OPENCLAW_GATEWAY_TOKEN` oder
`gateway.auth.token` als URL-Fragment-Schlüssel `token` zu verwenden; Token-
Werte werden nicht in Logs ausgegeben.
- Wenn die UI zur Shared-Secret-Authentifizierung auffordert, fügen Sie das konfigurierte Token oder
Passwort in die Einstellungen der Control UI ein.
## Grundlagen der Authentifizierung (lokal vs. remote)
## Auth-Grundlagen (lokal vs. remote)
- **Localhost**: Öffne `http://127.0.0.1:18789/`.
- **Gateway-TLS**: Wenn `gateway.tls.enabled: true`, verwenden
Dashboard-/Status-Links `https://` und Control-UI-WebSocket-Links `wss://`.
- **Quelle für Shared-Secret-Token**: `gateway.auth.token` (oder
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` kann es über ein URL-Fragment
für einmaliges Bootstrap übergeben, und die Control UI speichert es in `sessionStorage` für die
aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL statt in `localStorage`.
- Wenn `gateway.auth.token` als SecretRef verwaltet wird, gibt `openclaw dashboard`
absichtlich eine URL ohne Token aus, kopiert und öffnet sie. Dadurch wird vermieden,
extern verwaltete Token in Shell-Logs, der Zwischenablagen-Historie oder Browser-Startargumenten offenzulegen.
- Wenn `gateway.auth.token` als SecretRef konfiguriert ist und in deiner
aktuellen Shell nicht aufgelöst werden kann, gibt `openclaw dashboard` dennoch eine URL ohne Token sowie
konkrete Hinweise zur Einrichtung der Authentifizierung aus.
- **Shared-Secret-Passwort**: Verwende das konfigurierte `gateway.auth.password` (oder
- **Localhost**: Öffnen Sie `http://127.0.0.1:18789/`.
- **Gateway-TLS**: Wenn `gateway.tls.enabled: true`, verwenden Dashboard-/Statuslinks
`https://` und WebSocket-Links der Control UI `wss://`.
- **Shared-Secret-Token-Quelle**: `gateway.auth.token` (oder
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` kann es für ein einmaliges
Bootstrap über das URL-Fragment übergeben, und die Control UI speichert es in sessionStorage für die
aktuelle Browser-Tab-Sitzung und die ausgewählte Gateway-URL statt in localStorage.
- Wenn `gateway.auth.token` SecretRef-verwaltet ist, gibt `openclaw dashboard`
absichtlich eine nicht tokenisierte URL aus/kopiert/öffnet sie. Dadurch wird vermieden,
extern verwaltete Tokens in Shell-Logs, dem Verlauf der Zwischenablage oder Browser-Startargumenten offenzulegen.
- Wenn `gateway.auth.token` als SecretRef konfiguriert ist und in Ihrer
aktuellen Shell nicht aufgelöst ist, gibt `openclaw dashboard` trotzdem eine nicht tokenisierte URL plus
umsetzbare Hinweise zur Auth-Einrichtung aus.
- **Shared-Secret-Passwort**: Verwenden Sie das konfigurierte `gateway.auth.password` (oder
`OPENCLAW_GATEWAY_PASSWORD`). Das Dashboard speichert Passwörter nicht über
Neuladevorgänge hinweg.
- **Modi mit Identitätsübertragung**: Tailscale Serve kann die Authentifizierung für Control UI/WebSocket
über Identity-Header erfüllen, wenn `gateway.auth.allowTailscale: true`, und ein
nicht auf Loopback beschränkter Reverse-Proxy mit Identitätsbewusstsein kann dies bei
`gateway.auth.mode: "trusted-proxy"` ebenfalls leisten. In diesen Modi benötigt das Dashboard
- **Identitätstragende Modi**: Tailscale Serve kann die Authentifizierung für Control UI/WebSocket
über Identitäts-Header erfüllen, wenn `gateway.auth.allowTailscale: true`, und ein
nicht auf loopback beschränkter identitätsbewusster Reverse Proxy kann
`gateway.auth.mode: "trusted-proxy"` erfüllen. In diesen Modi benötigt das Dashboard
kein eingefügtes Shared Secret für den WebSocket.
- **Nicht localhost**: Verwende Tailscale Serve, ein nicht auf Loopback beschränktes Shared-Secret-Binding, einen
nicht auf Loopback beschränkten Reverse-Proxy mit Identitätsbewusstsein und
- **Nicht localhost**: Verwenden Sie Tailscale Serve, eine nicht auf loopback beschränkte Shared-Secret-Bindung, einen
nicht auf loopback beschränkten identitätsbewussten Reverse Proxy mit
`gateway.auth.mode: "trusted-proxy"` oder einen SSH-Tunnel. HTTP-APIs verwenden weiterhin
die Shared-Secret-Authentifizierung, es sei denn, du betreibst absichtlich einen privaten Ingress mit
`gateway.auth.mode: "none"` oder HTTP-Authentifizierung über trusted-proxy. Siehe
[Web surfaces](/de/web).
Shared-Secret-Authentifizierung, sofern Sie nicht bewusst den Private-Ingress-Modus
`gateway.auth.mode: "none"` oder Trusted-Proxy-HTTP-Auth verwenden. Siehe
[Web-Oberflächen](/de/web).
<a id="if-you-see-unauthorized-1008"></a>
## Wenn du „unauthorized“ / 1008 siehst
## Wenn Sie „unauthorized“ / 1008 sehen
- Stelle sicher, dass das Gateway erreichbar ist (lokal: `openclaw status`; remote: SSH-Tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host` und dann `http://127.0.0.1:18789/` öffnen).
- Bei `AUTH_TOKEN_MISMATCH` können Clients einen vertrauenswürdigen Wiederholungsversuch mit einem zwischengespeicherten Gerätetoken durchführen, wenn das Gateway Retry-Hinweise zurückgibt. Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet die zwischengespeicherten genehmigten Scopes des Tokens erneut; Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten ihren angeforderten Scope-Satz bei. Wenn die Authentifizierung nach diesem Wiederholungsversuch weiterhin fehlschlägt, behebe die Token-Abweichung manuell.
- Außerhalb dieses Wiederholungspfads ist die Priorität für Connect-Authentifizierung wie folgt: zuerst explizites Shared 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 dasselbe
`{scope, ip}` serialisiert, bevor der Failed-Auth-Limiter sie erfasst, daher kann bereits der zweite gleichzeitige fehlerhafte Wiederholungsversuch `retry later` anzeigen.
- Für Schritte zur Behebung von Token-Abweichungen folge der [Checkliste zur Wiederherstellung bei Token-Abweichung](/de/cli/devices#token-drift-recovery-checklist).
- Hole oder übergib das Shared Secret vom Gateway-Host:
- Stellen Sie sicher, dass das Gateway erreichbar ist (lokal: `openclaw status`; remote: SSH-Tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host`, dann `http://127.0.0.1:18789/` öffnen).
- Bei `AUTH_TOKEN_MISMATCH` können Clients einen vertrauenswürdigen Wiederholungsversuch mit einem zwischengespeicherten Geräte-Token durchführen, wenn das Gateway Wiederholungshinweise zurückgibt. Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet die zwischengespeicherten genehmigten Scopes des Tokens wieder; Aufrufer mit explizitem `deviceToken` / expliziten `scopes` behalten ihren angeforderten Scope-Satz. Wenn die Authentifizierung nach diesem Wiederholungsversuch weiterhin fehlschlägt, beheben Sie die Token-Abweichung manuell.
- Außerhalb dieses Wiederholungspfads gilt für die Verbindungs-Authentifizierung diese Priorität: zuerst explizites Shared Token/Passwort, dann explizites `deviceToken`, dann gespeichertes Geräte-Token, dann Bootstrap-Token.
- Auf dem asynchronen Tailscale Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dieselbe
`{scope, ip}` serialisiert, bevor der Failed-Auth-Limiter sie aufzeichnet, sodass
der zweite gleichzeitig fehlerhafte Wiederholungsversuch bereits `retry later` anzeigen kann.
- Schritte zur Reparatur von Token-Abweichungen finden Sie in der [Checkliste zur Wiederherstellung bei Token-Abweichung](/de/cli/devices#token-drift-recovery-checklist).
- Rufen Sie das Shared Secret vom Gateway-Host ab oder stellen Sie es dort bereit:
- Token: `openclaw config get gateway.auth.token`
- Passwort: das konfigurierte `gateway.auth.password` oder
`OPENCLAW_GATEWAY_PASSWORD` auflösen
- SecretRef-verwaltetes Token: den externen Secret-Anbieter auflösen oder
`OPENCLAW_GATEWAY_TOKEN` in dieser Shell exportieren und dann `openclaw dashboard`
erneut ausführen
- Passwort: Lösen Sie das konfigurierte `gateway.auth.password` oder
`OPENCLAW_GATEWAY_PASSWORD` auf
- SecretRef-verwaltetes Token: Lösen Sie den externen Secret-Provider auf oder exportieren Sie
`OPENCLAW_GATEWAY_TOKEN` in dieser Shell und führen Sie dann `openclaw dashboard` erneut aus
- Kein Shared Secret konfiguriert: `openclaw doctor --generate-gateway-token`
- Füge in den Dashboard-Einstellungen das Token oder Passwort in das Auth-Feld ein
und verbinde dich dann.
- Die Sprachauswahl der UI befindet sich unter **Overview -> Gateway Access -> Language**.
Sie ist Teil der Zugriffskarte, nicht des Bereichs Appearance.
- Fügen Sie in den Dashboard-Einstellungen das Token oder Passwort in das Auth-Feld ein,
und verbinden Sie sich dann.
- Die Sprachauswahl der UI befindet sich unter **Übersicht -> Gateway-Zugriff -> Sprache**.
Sie ist Teil der Zugriffskarte, nicht des Bereichs Darstellung.
## Zugehörig
## Verwandt
- [Control UI](/de/web/control-ui)
- [WebChat](/de/web/webchat)