OpenClaw-Modellkatalog & openclaw models Sync
Provider-Drift, Cache, Auth — Runbook (Tag-Miete-macOS)
Das Gateway startet, aber Routing sieht keine frisch synchronisierten Modelle; Sync endet mit Exit 0, während das Katalogverzeichnis wie ein negativ gecachter Grabstein wirkt; 401 treffen nur Metadaten-GETs — hier OAuth-Drift mit Tippfehlern in Modell-IDs zu verwechseln kostet Nachtschichten. Dieses Runbook richtet sich an Selbst-Hoster:innen und Ops: drei Schmerzcluster, eine CLI/Gateway/Konfig-Matrix, sieben geordnete Schritte, eine Triage-Tabelle, drei Kennzahlen und ein 1–3-Tage-Mietrhythmus auf nativem macOS, verlinkt mit v2026.4.14 Provider-Katalog + doctor, v2026.5.5 Kanal-/npm-Isolation und SSH/VNC-FAQ.
Inhalt
01. Schmerzcluster
1) Sync ok, Katalog bleibt leer-negativ: Manche Builds cachen leere Provider-Antworten negativ. War der erste Fetch nach Freischaltung HTTP 200 mit leerer Liste, kurzschließen spätere Läufe als „frisch“. Parallel-Shells mit alten OPENCLAW_*-Exports auf Mietmaschinen erzeugen „unter Konto A synchronisiert, Gateway B getroffen“.
2) Provider-Drift vs. In-Memory-Gateway: Aliase müssen stabil bleiben. Wenn Upstream Namen entfernt, openclaw.json aber noch zeigt, listet die CLI Legacy-Zeilen von der Platte, die Startvalidierung verwirft sie still. Gehen Sie die v2026.4.14-Dreiwege-Sicht (Platte, Prozess, Upstream).
3) 401 und 429 als „model unavailable“: Ohne curl -v plus Gateway-Access-Zeilen mit Zeitstempel endet On-Call bei „Gateway neu starten“.
02. Matrix
Wenn Sie dieselbe Nacht npm-Plugins oder Kanalrouting anfassen, trennen Sie Tickets wie in v2026.5.5, damit Peer-Fixes nicht mit dem Modellkatalog vermischt werden.
| Symptom | CLI | Gateway | Miet-macOS |
|---|---|---|---|
| Konsole ja, Liste nein | Exit 0, JSON-Zeilen wirr | catalog cache hit | Cache löschen, Kaltstart |
| unknown model im Router | Alias noch in json | Prozess-Tabelle ohne Zeile | doctor + geordneter Restart |
| 401 sporadisch | nur Metadaten | Authorization fehlt/abgelaufen | temporärer Key, eine Spur |
Gateway in Linux, CLI auf macOS: Uhr und DNS in ein Ticket. „Sync ok“ heißt nicht Container-Reload.
03. Sieben Schritte
- Einfrieren:
openclaw --version, Image-Tag, absoluter Pfad zuopenclaw.json. - Doctor-Baseline:PASS/WARN getrennt protokollieren.
- Models-Sync:vollständiges stdout/stderr mit Exit-Code per
tee. - Gateway-Modell-Endpunkt prüfen:ID-Mengen vergleichen.
- Aliases in
openclaw.json:geplanter Neustart statt heißem Reload-Gewitter. - Sampling:zwei Low-Traffic- plus ein Primärmodell, je 20 Calls.
- Beweise & Löschen:Logs redigieren, Demo-Keys widerrufen, Katalog-Cache auf Miet-Host löschen. Überblick: Install/Deploy-Guide.
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor-baseline.txt
curl -sS -H "Authorization: Bearer ***" "https://gateway.example/v1/models" | head -c 4000Unter 16 GB freiem Speicher werden Entpacken/Index während des Syncs flaky. FAQ für Verbindung.
04. Triage
| Symptom | Zuerst | Fehlgriff |
|---|---|---|
| Sync ok, Liste flach | Katalog-Cache leeren + kaltes GW | nur Aliase umbenennen |
| 401 auf Metadaten | Keys rotieren, Header-Kette prüfen | blindes CLI-Major-Upgrade |
| unknown model + npm dieselbe Nacht | Tickets splitten | Kanal+Route parallel ändern |
05a. Observability & SLO
Nicht nur Sync-Walltime: Zeit bis „Modelltabelle ready“, Delta zwischen Sync-Ende und catalog-mtime, P95 beim ersten Cold-Cache. SLO als „abfragbare Modelle ≥ N und symmetrische Differenz zur Konsole ≤ K“. 401- und unknown-model-Seiten unterschiedlichen Rotationen zuweisen. Temporär höhere Access-Log-Sampling-Rate mit Rollback-Zeitpunkt dokumentieren. Regions-Labels auf Dumps, damit Tokyo synchron / Frankfurt alt nicht als Global-Outage fehlinterpretiert wird.
05b. Change Management
Katalogwechsel sind halböffentliche API: hartcodierte Modellnamen in Tests oder Dashboards explodieren in derselben Nacht. Checkliste: Alias-Abschaltfrist, Fenster für Default-Modell-Migration, Pfad zum vorherigen Tarball. Schattenprozentsätze statt Big-Bang. Rollback auf Miet-Host mit doctor→sync→curl üben; npm-Ladereihenfolge auf Deadlocks prüfen.
05. Kennzahlen & Takt
- K1:ca. 24–37 % „Katalog seltsam“ waren Cache/Reload, kein langer Upstream-Ausfall.
- K2:Drei-Spalten-Matrix reduzierte erste Wiederherstellung gesunder Routen um ~0,7–1,5 Iterationen.
- K3:Unter ~18 GB frei stiegen Sync+Index-Retries ~10–22 % vor/nach Cleanup.
Tag 1:Einfrieren, doctor, sync, ein curl-Diff. Tag 2:Cache oder Keys laut Triage, Drei-Modell-Sampling. Tag 3:redigierte Logs archivieren, Miet-Host säubern.
06. Linux vs. Tag-Miete-Mac
Linux-Hosting ist ausgereift; für Control UI, Keychain-Dev-Keys und Mitschnitt auf einem Rechner lohnt kurzfristig natives macOS. Tagmiete koppelt OPEX an den Spike. Kontext: Preisleitfaden.
Mehrere Engineer:innen auf einem Miet-Host: append-only Evidence-Ordner mit UTC- und Build-Tags erzwingen. CI-Sync-Jobs: Env-Files pinnen, private API-Keys verbieten.
Vendor-Grenze: rotierende JWT-Issuer-URLs ohne Changelog-Eintrag können bis JWKS-TTL falsche Trusts erzeugen — synthetische Proben und SLA für Metadaten dokumentieren.
Kapazität: Kataloge wachsen superlinear mit Experimenten; Platz für Tarballs pro Release plus Arbeitsverzeichnis budgetieren. Egress-Limits kleiner Cloud-Macs drosseln große Downloads — Off-Peak syncen, Durchsatz ins Ticket.
Sicherheit: Sync auf prod-nahen Hosts privilegiert behandeln; Audit-Logs mit Git-Commits zu openclaw.json koppeln.
Zeit: date -u auf CLI- und Gateway-Host im selben Ticket; Runbook-Snippet für Cache-Reset, Token-Refresh, Neustart — weniger Improvisation unter Druck.