2026 OPENCLAW
SKILLS_
SNAPSHOT_
STALE_
RESET.

Wenn Sie 2026 neue Skills aus ClawHub oder unter ~/.openclaw/skills/ installieren, der Agent in Telegram, Slack oder Teams aber wie eine alte Version wirkt — obwohl Sie /new oder sessions.reset ausgeführt haben und in den Logs kein erwartetes skillsSnapshot-Update erscheint — liegt das meist nicht an einem fehlgeschlagenen Paketinstall, sondern an nicht abgestimmten Ebenen: Session-Snapshot, Disk-Mapping und Gateway-Prozesscache. Dieser datengetriebene Artikel liefert nummerierte Pain-Points, eine Entscheidungsmatrix, ein Sechs-Schritte-Runbook, drei Akzeptanz-Gates, eine Fallstudie mit messbaren Schwellen, Betriebs- und DSGVO-relevante Hinweise sowie FAQ — mit Querverweisen zu invalid config & doctor --fix, Fallback-Drift & sessions und Multi-Channel-JSONL & Bootstrap.

1. Pain-Points: Reset leert Chat, nicht zwingend den Skill-Graph-Snapshot

1) skillsSnapshot ≠ Session-Reset-Semantik: /new und sessions.reset setzen in den meisten Builds primär Konversationskontext und Routing-Keys zurück. Das Gateway cached aus Latenzgründen die aufgelöste Skill-Verzeichnisstruktur (skillsSnapshot). Bleibt der Cache-Key ohne Invalidierung bei geändertem mtime des Skill-Ordners, sehen Sie neue SKILL.md-Dateien auf der Platte, aber dieselbe Tool-Liste zur Laufzeit. In Stichproben aus Produktions-Tickets (MACGPU-Interne Auswertung Q1–Q2 2026, n≈140 Gateway-Incidents) lag der Anteil „Install OK, Snapshot stale“ bei 34 % — deutlich vor echten Install-Fehlern (~11 %).

2) auto model / auto auth-Overrides: Nach 429-Failover oder Kanalrichtlinien können Laufzeitmodell und Provider-Token in sessions.json unter runtimeOverrides hängen bleiben. Ein Reset, der diese Felder nicht berührt, routet neue Skills (z. B. Browser/Vision) weiter über ein reines Textmodell — still, ohne Schema-Fehler.

3) Veraltetes sessions.json-Mapping: Bei Multi-Account/Multi-Channel bleiben gelöschte sessionId- oder Workspace-Pfade gebunden; nach Reset wird der falsche Slot wiederverwendet.

4) CLI ≠ Gateway: openclaw status in der Shell kann grün sein, während der launchd-gestützte Gateway-Prozess den Skill-Graph vom Startzeitpunkt hält. Pflicht: gateway restart --force --wait plus Lausch-Ready-Check.

5) Remote-7×24-„Schein-Refresh“: Skills auf dem Laptop, nicht auf dem Server — oder umgekehrt. Vor jeder Eskalation: Hash der Skills-Verzeichnisse und Gateway-PID-Startzeit beider Knoten vergleichen, nicht sofort npm i -g wiederholen.

2. Entscheidungsmatrix: Snapshot, sessions oder Force-Restart?

Signal	Primäraktion	Verboten / Fallback
Neue Skill-Dateien auf Disk, Tool-Liste unverändert	mtime/hash → restart --force --wait → neue Session + Sonde	Nur Kanal refreshen ohne Gateway
Nach reset weiterhin Fallback-Modell	runtimeOverrides / auto-Felder in sessions.json prüfen	Ganze Datei ohne Backup löschen
Nur ein Kanal betroffen	Eintrag pro channelId bereinigen, dann reset	Global sessions.json truncaten
Nach v2026.5.x alle Kanäle „dümmer“	openclaw.json agents + doctor	Parallel Skills + plist ändern ohne Snapshot
Audit / DSGVO-Änderungsfenster	Identisches Runbook auf Remote-Referenzhost	Produktions-sessions.json in Peak ändern

3. Architektur-Kurzreferenz: drei Ebenen im Gateway-Prozess

Zur Fehlervermeidung hilft ein mentales Modell: Ebene Disk (SKILL.md, Manifest, Hooks) → Ebene Prozess (skillsSnapshot im RAM des Gateway-PID, gebaut beim Start oder nach explizitem Rescan) → Ebene Session (sessions.json + pro-Kanal-jsonl, inkl. runtimeOverrides). /new operiert primär auf Ebene Session (Transcript/Routing), nicht zwingend auf Ebene Prozess. Deshalb ist die Reihenfolge in der Praxis fast immer: Disk verifizieren → Session gezielt bereinigen → Prozess neu starten → Session-Probe. Wer diese Reihenfolge umdreht, verliert Zeit in Endlosschleifen aus Resets.

Unter macOS 15/16 mit launchd beachten Sie zusätzlich: der supervised Prozess erbt nicht automatisch Änderungen aus .zshrc. Wenn Sie Skills als Login-User installieren, der Gateway-Daemon aber unter minimalem Environment läuft, divergieren Pfade still. Ein diff <(launchctl print … | grep -i openclaw) <(env | grep -i openclaw) (konkrete Syntax je Label anpassen) gehört in reife Runbooks — nicht nur in Forenthreads.

4. Sechs-Schritte-Runbook: von erklärbar zu auditierbar

Step 1 — Evidenz-Quadrupel einfrieren

Vor dem ersten Write: OpenClaw-Version, Gateway-PID-Startzeit, Skill-Dateianzahl/SHA-256-Fingerprint, Session-Key des Zielkanals. Anhängen: openclaw status, openclaw gateway status, letzte 200 Gateway-Logzeilen. Ohne Quadrupel kein paralleles „sessions löschen + Skills reinstallieren + plist patchen“.

Step 2 — Disk als Source of Truth

Skills unter ~/.openclaw/skills/ oder Workspace-Pfad für den gleichen Unix-User wie launchd sichtbar? Remote per rsync --checksum oder Pipeline angleichen. ClawHub: Paketname + Version im Ticket — später gegen Snapshot-Zeile diffen.

Step 3 — sessions.json schichtweise (nicht rm -rf)

cp sessions.json sessions.json.bak.$(date +%Y%m%d%H%M). Mit jq nur Einträge des Ziel-channelId/account mit runtimeOverrides, veraltetem model oder hängender sessionId entfernen. Bei >2 MB sessions.json oder >20 MB Kanal-jsonl zuerst Archiv/Strip gemäß JSONL-Leitfaden — sonst frisst Bootstrap die Akzeptanzzeit.

Step 4 — reset + Sofort-Sonde

/new oder sessions.reset, dann sofort eine Sonde („Liste alle verfügbaren Tools/Skills“). Zweimal ohne Effekt → Step 5; kein drittes blindes reset (Schwellenwert §7).

Step 5 — Gateway force restart

openclaw gateway restart --force --wait. launchd: ggf. launchctl kickstart -k gui/$(id -u)/…, danach 3× gateway status. Während Restart-Sturm: kein openclaw.json-Edit (fail-closed-Leitfaden).

Step 6 — Remote-7×24-Matrix

Steps 1–5 auf Referenz-Mac wiederholen; Log-Zeilen zu skillsSnapshot (Tool-Count, Hash, Scan-ms) diffen. Produktionsfreigabe erst nach 30 Minuten stabiler Sonde und grünem channels.probe. Closure: Screenshots + Log-Slice im Ticket — relevant für DSGVO Art. 5 Abs. 2 (Rechenschaftspflicht) und interne Change-Protokolle.

5. Drei Akzeptanz-Gates (SOP, nicht Esoterik)

Gate A — Snapshot: Nach Restart muss Tool-/Skill-Count im status/Log mit find … SKILL.md | wc -l übereinstimmen; Abweichung ≥1 → kein „Skill live“-Kommentar im Ticket.

Gate B — Session: Erste Sonde nach reset muss neues Skill treffen; Rückfall innerhalb 10 Min → sessions.json.bak restore, Writes einfrieren.

Gate C — Umgebung: Shell vs. launchd: OPENCLAW_*, Skills-Pfad, PID-Startzeit — diff muss leer sein; Remote- vs. Dev-Hash ungleich → kein Produktions-Merge.

6. Fallstudie mit Kennzahlen

Content-Ops-Team, Mai 2026: summarize, browser, calendar installiert — ClawHub „success“. Telegram-Sonden: weiter 7 Tools. Logs: kein skills-rescan bis restart --force --wait → Scan-Zeile, Count 7→10. Zweiter Schnitt: jq löschte nur den Gruppen-runtimeOverrides-Block; 30-Minuten-Fenster ohne Rückfall. MTTR vor Runbook-Einführung: median 4,2 h (n=6 interne Vorfälle); danach 28 min (n=4). Kein Rückgriff auf Ad-hoc-Skripte nötig.

Verkettung mit Fallback-Drift (openclaw.json als Config-Wahrheit) vs. diesem Artikel (Session + Prozesscache). Bei Gateway-CPU 100 % ohne frische Logs zuerst JSONL-Bootstrap ausschließen.

7. Betrieb, Branche & DSGVO-relevante Dokumentation

2026 standardisieren Agent-Gateways Skill-Graph-Snapshots für Latenz — Ops braucht Disziplin: wann force-refresh der Prozessansicht. Prüfer und Kunden fragen nicht „haben Sie npm aktualisiert?“, sondern „gibt es nach Skill-Change einen nachvollziehbaren Abgleich (PID, hash, sessions-diff)?“ Für EU-Teams: Skill-Inhalte und Session-Metadaten können personenbezogene Kontexte enthalten (Chat-IDs, Tokens). Datenminimierung (Art. 5 Abs. 1 lit. c DSGVO): gezieltes jq-Löschen statt Voll-rm sessions.json; Backups verschlüsselt und retention-begrenzt; Remote-Mac in EU-Rechenzentrum/Vertrag dokumentieren. MACGPU-Miet-Macs eignen sich als Gold-Referenz: identisches Runbook, vergleichbare Logs, keine Vermischung von GUI-Session und launchd auf dem Entwickler-Notebook.

Best Practice 2026: Skill-Install nur im Change-Fenster; Install-Skript endet mit gateway restart --wait; sessions pro Kanal bereinigen. Vier Karten im „OpenClaw-Pass“: Config (doctor), Sessions, Snapshot, Gateway-Ready — fehlt eine, kein Nacht-Merge.

8. Zitierbare numerische Schwellen

① Gateway-Laufzeit >7 Tage + Skills-Ordner geändert → Pflicht restart --force --wait, nicht nur reset. ② >2 erfolglose /new pro Kanal → sessions.json analysieren, kein drittes reset. ③ sessions.json >2 MB oder Kanal-jsonl >20 MB → zuerst Archiv. ④ Akzeptanzfenster ≥30 min ohne Tool-Rückfall. ⑤ Remote- vs. Prod-Skills-Hash ungleich → kein „Prod updated“.

9. Observability: messbare Signale statt Bauchgefühl

Teams, die skillsSnapshot-Probleme in unter einer Stunde eingrenzen, hängen selten an zufälligen UI-Klicks — sie standardisieren drei Log-Muster. Erstens: eine Zeile nach Gateway-Start mit Skill-Scan-Dauer und Tool-Count (oft skills.scan oder äquivalent im Gateway-Log); fehlt sie nach Install, ist der Prozess nicht neu gestartet. Zweitens: Korrelation zwischen sessions.reset-Events und anschließender erster User-Message — wenn reset „ok“ meldet, die erste Antwort aber weiterhin alte Tool-IDs referenziert, liegt der Fehler fast immer in runtimeOverrides, nicht im Skill-Paket. Drittens: Side-by-Side shasum der SKILL.md-Dateien auf Dev- vs. Remote-Host; Abweichungen über 0 % erklären „Laptop grün, Produktion rot“ ohne weitere Hypothesen.

Für Grafana/Datadog-affine Shops empfiehlt sich ein leichtgewichtiges Dashboard: Gateway-Uptime in Tagen, letzter Skill-Ordner-mtime, Größe von sessions.json, Anzahl aktiver Kanäle mit runtimeOverrides. Schwellen aus §7 als rote Linien einzeichnen — z. B. Uptime >7 Tage bei geändertem Skill-Ordner löst automatisch ein Ticket „Force-Restart erforderlich“ aus, noch bevor Nutzer eskalieren. Das reduziert in unseren Kundenumgebungen wiederkehrende Nacht-Eskalationen um geschätzte 40–55 % (Rolling 90-Tage-Vergleich, Q2 2026).

DSGVO-Hinweis zu Logs: Session-IDs, Kanal-Handles und Provider-Token in Log-Slices vor Weitergabe an Dritte (Ticket-System, SIEM) pseudonymisieren oder kürzen; Aufbewahrungsfristen im Verarbeitungsverzeichnis festhalten. Remote-Mac-Anbieter-Verträge sollten Subprocessor-Klauseln und EU-Standort explizit benennen — besonders wenn Sonde-Nachrichten Kundeninhalte enthalten.

10. Rollback und Change-Kommunikation

Wenn Gate B fehlschlägt, ist der sichere Pfad: Gateway stoppen (supervised), sessions.json.bak zurückspielen, Gateway mit dokumentiertem Grund starten, Stakeholder informieren. Vermeiden Sie „Hot-Fix“ durch erneutes ClawHub-Installieren ohne Restart — das verdoppelt nur Disk-I/O und verschleiert die Ursache. Für Release Notes an interne Kunden: nennen Sie explizit „skillsSnapshot-Abgleich durchgeführt“ mit Tool-Count vor/nach und PID-Startzeit — das entspricht gängigen ITSM-Feldern und erleichtert DSGVO-Auskunftsanfragen, weil der Vorgang nachvollziehbar ist.

Bei Multi-Tenant-Setups (mehrere Agents unter ~/.openclaw/agents/*) gilt: Snapshot-Refresh ist pro Gateway-Prozess, nicht global pro Maschine. Ein Reset in Agent A aktualisiert nicht automatisch den Skill-Graph von Agent B. Prüfen Sie daher den Pfad in openclaw.json → agents.defaults bzw. kanalspezifische Overrides, bevor Sie sessions eines falschen Agents bereinigen.

11. Praxis-Checkliste für Nachtschicht (copy-paste-fähig)

Ticket eröffnet mit Symptom „neue Skills unsichtbar“: (1) Quadrupel erfassen und an Kommentar #1 hängen. (2) find + shasum auf Prod und Referenz-Host — bei Diff zuerst rsync/Deploy, nicht reset. (3) jq-Pfad zu runtimeOverrides des betroffenen Kanals dokumentieren; nur wenn vorhanden, selektiv löschen. (4) Genau ein gateway restart --force --wait, danach 3× status. (5) Sonde mit eindeutig neuem Skill (Tool-Name aus SKILL.md). (6) 30-Minuten-Timer starten; bei Rückfall sofort .bak restore. (7) Closure-Felder: tool_count vor/nach, PID lstart vor/nach, sessions-Diff-Zeilenanzahl. Diese Checkliste hat in internen Übungen die mittlere Zeit bis zur korrekten Ursachenzuordnung von ~95 auf ~35 Minuten reduziert, weil sie Resets vor Gateway-Restart blockiert.

In Wartungsfenstern mit DSGVO-relevanten Daten tragen Sie im Ticket zusätzlich ein: welche Kanäle betroffen waren, ob Sonde-Nachrichten personenbezogene Inhalte enthielten, und ob Logs vor Anhang pseudonymisiert wurden. Das erspart Rückfragen des Datenschutzbeauftragten bei Gateway-Neustarts auf Produktionsbots.

Vergleichen Sie abschließend Ihre Ergebnisse mit dem chinesischen Referenz-Runbook auf macgpu.com (gleiches POST-105-Thema), wenn Sie in gemischten Teams arbeiten — die Schritte sind identisch, nur die Kanalnamen (Telegram, Feishu, Slack) unterscheiden sich. Wichtig bleibt: dokumentierte Schwellen aus §8 in jedem Change-Ticket abhaken, damit Audit und Betrieb dieselbe Sprache sprechen.

12. FAQ

Nur Skill installieren, kein Restart? Kurztests auf Dev-Maschine manchmal ok; 7×24-Produktion: nein.
/new vs. sessions.reset? Nutzer → /new; Ops-Batch → sessions.reset; beides ersetzt keinen Gateway-Force-Restart.
sessions.json löschen? Nur mit Backup; bevorzugt jq pro Eintrag.
invalid config? Zuerst doctor/fail-closed-Leitfaden; dieser Artikel wenn Gateway läuft, Skills aber alt wirken.
Linux/Windows? Service-Manager anders; Schichtlogik Snapshot/sessions/Gateway bleibt.
ClawHub „success“, aber kein SKILL.md? Paketstruktur prüfen — ohne parsebare Manifest-Zeile erscheint nichts im Snapshot, auch nach Restart.

Kurzfassung für Entscheider: Ein Skill-Rollout ist erst abgeschlossen, wenn Tool-Count, PID-Alter und sessions-Diff im Ticket stehen — nicht wenn der Install-Befehl grün war.