Was macht Compaction UI v2.1.0?
Speicherkomprimierungssystem für die OpenClaw Control UI — Hintergrundausführung mit Toast-Benachrichtigungen, automatischer Auslöser bei konfigurierbaren Token-Schwellenwerten, Zusammenfassungsabsätze im komprimierten Output, dedizierter Einstellungs-Tab mit Modellauswahl und Ergebnishistorie.
Status: ✅ Aktiv
| Komponente | Status |
|---|---|
| Kontext-Messanzeige-Button | ✅ Funktionsfähig |
| Hintergrundkomprimierung (Toast) | ✅ Funktionsfähig |
| Automatischer Komprimierungsauslöser | ✅ Funktionsfähig |
| Gesprächszusammenfassungsabsatz | ✅ Funktionsfähig |
| Einstellungs-Tab (Plugin-registriert) | ✅ Funktionsfähig |
| Modellauswahl | ✅ Funktionsfähig |
| Letzte Ergebnis-Speicherung & -Anzeige | ✅ Funktionsfähig |
| Einstellungs-Persistenz & -Wiederherstellung | ✅ Funktionsfähig |
| Auth-Hierarchie (OAuth > API > Fallback) | ✅ Funktionsfähig |
| Chatverlaufsfilter | ✅ Funktionsfähig |
| Vollständige Hintergrundisolation (keine Chat-Interferenz) | ✅ Funktionsfähig |
Funktionen
1. Kontext-Messanzeige-Button (app-render.helpers.ts)
Ein kreisförmiger SVG-Fortschrittsring in der Chat-Symbolleiste, der gleichzeitig als manueller Komprimierungsauslöser dient.
- Platzierung: Nach dem Session-Auswahl-Dropdown in
renderChatControls() - Datenquelle:
sessionsResult.sessions[].totalTokensundcontextTokensaus Session-Zeilen - Farben: Grün (<60%), Gelb (60-85%), Rot (≥85%)
- Deaktiviert: Wenn die Auslastung <20% beträgt oder während einer aktiven Komprimierung
- Tooltip: Zeigt "Kontext: XK / YK Tokens (Z%)" an
2. Hintergrundkomprimierung (Toast)
Beim Klick (oder automatischem Auslösen) läuft die Komprimierung im Hintergrund über das standardmäßige Toast-System unten rechts — kein blockierendes Modal. Die Benutzeroberfläche bleibt vollständig interaktiv.
- Laufender Toast: Zeigt "Speicherkomprimierung" mit Spinner
- Abschluss-Toast: Zeigt "Komprimiert: XK → YK" mit Häkchen (verschwindet automatisch nach 5s)
- Fehler-Toast: Zeigt Fehlermeldung (verschwindet automatisch nach 5s)
- Verwendet das
backgroundJobToasts-System, das mit allen anderen Hintergrundprozessen konsistent ist (Cron, Wissensextraktion usw.)
3. Automatische Komprimierung
Nach jeder Chat-Antwort (final-Ereignis) überprüft die UI die Token-Nutzung gegen den konfigurierten Schwellenwert. Wenn überschritten:
- Hintergrundkomprimierung wird automatisch ausgelöst
- Toast zeigt "Automatische Komprimierung (X%)" mit der aktuellen Auslastung
- 5-Minuten-Entprellung verhindert wiederholte Auslöser
- Chat wird nach erfolgreicher Komprimierung automatisch aktualisiert
- Stiller Toast-Entfernung, wenn nichts komprimiert wurde
4. Gesprächszusammenfassungsabsatz
Jeder Komprimierungsoutput beginnt jetzt mit einem Abschnitt ## Gesprächszusammenfassung vor dem strukturierten Abschnitt ## Ziel. Dies ist ein Absatz in natürlicher Sprache mit 3-6 Sätzen, der:
- Die allgemeinen Themen des Gesprächs beschreibt
- Den Diskussionsverlauf und wichtige Übergänge erklärt
- Zusammenfasst, wie sich das Gespräch entwickelt hat
- Im Präteritum als erzählerischer Überblick verfasst ist
Implementierung: Benutzerdefinierte Anweisungen werden dem vorgelagerten Komprimierungs-LLM-Aufruf über compact.ts hinzugefügt. Die Anweisung wird allen vom Benutzer bereitgestellten benutzerdefinierten Anweisungen (von /compact [Anweisungen]) vorangestellt, sodass beide nebeneinander existieren.
Beispielausgabe:
## Gesprächszusammenfassung
Das Gespräch begann damit, dass der Benutzer Verbesserungen am Komprimierungssystem
anforderte, insbesondere den Wechsel von einem blockierenden Modal zu Hintergrund-Toasts.
Die Diskussion verlagerte sich dann auf das Hinzufügen eines Einstellungs-Tabs mit
Steuerelementen für die automatische Komprimierung. Nach der Implementierung und dem
Testen dieser Funktionen stellte der Benutzer fest, dass die Einstellungen beim
Navigieren zwischen Tabs nicht erhalten blieben, was zu einer Behebung des
Modulstatus-Caches führte. Schließlich forderte der Benutzer das Hinzufügen eines
erzählerischen Zusammenfassungsabsatzes zum Komprimierungsoutput für einen besseren
Kontext.
## Ziel
...
5. Einstellungs-Tab (Plugin-Registriert)
Ein dedizierter Komprimierungs-Tab unter der Navigationsgruppe Agent, registriert über die Plugin-UI-Architektur.
Registrierung: plugins-ui.ts → BUILTIN_UI_VIEWS mit id: "compaction", group: "agent", position: 7, icon: "archive"
Karten:
Karte: Automatische Komprimierung
- Schalter: Automatische Komprimierung aktivieren/deaktivieren
- Schieberegler für Schwellenwert: 10% bis 95% (Standard: 60%)
- Farbcodiert: Grün (<60%), Gelb (60-85%), Rot (≥85%)
Karte: Modell
- Dropdown: Ein bestimmtes Modell für die Komprimierung auswählen oder das Session-Standardmodell verwenden
- Nach Anbieter gruppiert mit angezeigten Kontextfenstergrößen
- Warnhinweis bei Auswahl eines benutzerdefinierten Modells (Erinnerung an API-Schlüssel)
- Fallback: Wenn das benutzerdefinierte Modell fehlschlägt, automatischer Rückgriff auf das Session-Standardmodell
Karte: Ergebnis-Speicherung
- Schalter: Opt-in zum Speichern des komprimierten Zusammenfassungstexts zur Überprüfung
Karte: Letzte Komprimierung
- Vorher/Nachher: Große, gestaltete Token-Zahlen in einem 2-Spalten-Raster
- Statistiken: Gespeicherte Tokens, prozentuale Reduzierung, Auslöser-Typ, Zeitstempel, Session-Schlüssel
- Ergebnisse anzeigen: Erweiterbarer Zusammenfassungs-Viewer (wenn Speicherung aktiviert ist)
- Löschen: Gespeichertes Ergebnis zurücksetzen
- Hinweis: Zeigt Meldung "Ergebnisse speichern aktivieren" an, wenn die Speicherung deaktiviert ist
Zustandsverwaltung:
- Der Modulstatus bleibt über Neudarstellungen innerhalb einer Session hinweg erhalten
- Einstellungen werden bei jedem Besuch des Tabs vom Backend neu geladen (2-Sekunden-Veraltungsgrenze)
resetCompactionSettingsState()wird für Tests und Tab-Wechsel exportiert
6. Auth-Hierarchie
Die Komprimierung verwendet resolveApiKeyForProvider über getApiKeyForModel — die gleiche Authentifizierungskette wie der Chat:
OAuth → API-Key → Fallback
Keine separate Konfiguration erforderlich. Wenn OAuth (Claude Max) als primäres Authentifizierungsprofil konfiguriert ist, verwendet die Komprimierung es automatisch. Die benutzerdefinierte Modellauswahl verwendet diese gleiche Authentifizierungskette unabhängig.
7. Ergebnis-Speicherung
Wenn aktiviert, wird das letzte Komprimierungsergebnis in {agentDir}/compaction-config.json gespeichert:
{
"settings": {
"autoEnabled": true,
"autoThresholdPercent": 60,
"storeLastResult": true,
"compactionModel": "anthropic/claude-sonnet-4-6"
},
"lastResult": {
"timestamp": 1709283600000,
"trigger": "manual",
"tokensBefore": 50614,
"tokensAfter": 4766,
"tokensSaved": 45848,
"percentReduction": 91,
"sessionKey": "agent:main:main",
"summary": "## Gesprächszusammenfassung\nDas Gespräch konzentrierte sich auf...\n\n## Ziel\n..."
}
}
Wenn die Speicherung deaktiviert ist, werden Metadaten (Zeitstempel, Token-Anzahlen) weiterhin gespeichert, der Zusammenfassungstext jedoch weggelassen.
8. Chatverlaufsfilter
- NO_REPLY/HEARTBEAT_OK-Filterung: Überspringt Assistentennachrichten mit genau diesen Texten
- Komprimierungs-Trennzeichen: Zeigt beschriftete Trennlinie für
__openclaw.kind === "compaction"Nachrichten an
Architektur
Backend-RPCs
| Methode | Beschreibung |
|---|---|
sessions.compact | Komprimierung ausführen (zeichnet Ergebnis nach Abschluss auf) |
compaction.getSettings | Einstellungen aus Konfigurationsdatei lesen |
compaction.saveSettings | Einstellungen aktualisieren (Schwellenwert automatisch auf 10-95% begrenzt) |
compaction.getLastResult | Gespeichertes letztes Komprimierungsergebnis abrufen |
compaction.clearLastResult | Gespeichertes Ergebnis löschen |
Geänderte Dateien
| Datei | Zweck |
|---|---|
src/gateway/server-methods/compaction.ts | Einstellungs-RPCs, Konfigurations-I/O, Ergebnisaufzeichnung |
src/gateway/server-methods/sessions.ts | sessions.compact RPC (zeichnet Ergebnis nach Komprimierung auf) |
src/gateway/server-methods/plugins-ui.ts | Plugin-Ansichtsregistrierung |
src/gateway/server-methods.ts | Handler-Verkabelung |
src/gateway/server-methods-list.ts | Methodenregistrierung |
src/gateway/method-scopes.ts | Bereichsregistrierung |
src/agents/pi-embedded-runner/compact.ts | Chat-Zusammenfassungsanweisungseinfügung |
ui/src/ui/app-render.helpers.ts | Kontext-Messanzeige + Hintergrund-Toast-Auslöser |
ui/src/ui/app-gateway.ts | Automatische Komprimierungsprüfung nach finalem Ereignis |
ui/src/ui/views/compaction-settings.ts | Einstellungs-Tab-Ansicht |
ui/src/ui/app-render.ts | Ansichtsverkabelung + Import |
ui/src/ui/views/chat.ts | Chatverlaufsfilter |
Konfigurationsdatei
{agentDir}/compaction-config.json — pro Agent, wird beim ersten Speichern der Einstellungen erstellt.
Plugin-Registrierung
Der Komprimierungs-Tab wird als integrierte Plugin-Ansicht in plugins-ui.ts registriert:
{
id: "compaction",
label: "Komprimierung",
subtitle: "Speicherverwaltung",
icon: "archive",
group: "agent",
position: 7,
pluginId: "compaction-ui",
}
Bekannte Fallstricke
- Einstellungen bleiben beim Tab-Wechsel nicht erhalten: Behoben in v2.1.0. Das modulweite
_state.loaded-Flag verhinderte das Neuladen. Jetzt erfolgt ein Neuladen alle 2 Sekunden beim erneuten Betreten des Tabs. - Modellauswahl erfordert API-Schlüssel: Wenn Sie ein benutzerdefiniertes Modell auswählen, stellen Sie sicher, dass der API-Schlüssel des Anbieters konfiguriert ist. Die UI zeigt einen Warnhinweis an.
- Komprimierungsmodellformat: Muss das Format
"Anbieter/Modell"sein (z.B."anthropic/claude-sonnet-4-6"). Ungültige Formate werden stillschweigend ignoriert und fallen auf das Session-Standardmodell zurück. - parentId-Skipset-Weitergabe muss nachrichtenbasiert sein: Beim Filtern von Speicherlöschungsnachrichten aus
readSessionMessagesdarf das Skipset NUR über Einträge mit einemmessage-Feld weitergegeben werden. Nicht-Nachrichten-Protokolleinträge (type:"custom") überbrücken logische Gesprächswechsel – wenn ihre IDs in das Skipset gelangen, wird der gesamte restliche Gesprächsverlauf ausgeblendet. Die Lösung: Nurparsed?.message-Einträge gegen das Skipset prüfen und nur deren IDs hinzufügen. - Kein blockierendes Modal – nie: Der Messanzeige-Button in
app-render.helpers.tsdarf NIEMALS ein Vollbild-Overlay-Modal rendern. Die Komprimierung ist ein Hintergrundprozess; der gesamte Status wird über das Toast-System unten rechts kommuniziert. Entfernen Sie jeglichesposition:fixed; inset:0Overlay, das voncompactState.phaseabhängt. Der Button kann während der Ausführung ein Spinner-Symbol anzeigen, darf aber die UI nicht blockieren.
Änderungsprotokoll
v2.1.0
- Gesprächszusammenfassungsabsatz: Der Komprimierungsoutput beginnt jetzt mit einem erzählerischen Absatz
## Gesprächszusammenfassungvor den strukturierten Abschnitten - Modellauswahl: Wählen Sie ein bestimmtes Modell für die Komprimierung oder verwenden Sie das Session-Standardmodell, mit nach Anbieter gruppiertem Dropdown
- Einstellungs-Neuladefix: Der Tab lädt jetzt alle 2 Sekunden Einstellungen vom Backend neu, anstatt sie dauerhaft zu cachen
- Referenzdateien aktualisiert:
references/mit aktueller Quelle synchronisiert
v2.0.0
- Hintergrundkomprimierung: Blockierendes Vollbild-Modal durch Hintergrund-Job-Toast ersetzt
- Automatische Komprimierung: Wird nach Chat-Antwort ausgelöst, wenn die Token-Nutzung den Schwellenwert überschreitet (konfigurierbar, Standard 60%, 5-Minuten-Entprellung)
- Einstellungs-Tab: Plugin-registrierter Komprimierungs-Tab unter der Agent-Navigationsgruppe
- Ergebnisaufzeichnung:
sessions.compactzeichnet Token-Anzahlen vorher/nachher und optionale Zusammenfassung auf - Auth-Hierarchie: Gleiche OAuth → API → Fallback-Kette wie der Chat
- Einstellungs-RPCs:
compaction.getSettings,compaction.saveSettings,compaction.getLastResult,compaction.clearLastResult
v1.0.0
- Erstveröffentlichung: Kontext-Messanzeige-Button, blockierendes Modal mit animierten Phasen,
sessions.compactRPC mit LLM-Zusammenfassung, Chatverlaufsfilterung NO_REPLY/HEARTBEAT_OK, Komprimierungs-Trennlinien