Warum meldet Chroma sqlite locked oder database is locked?

Mehrere Prozesse haben dasselbe Persistenzverzeichnis geöffnet, oder ein Backup hat SQLite-Dateien während aktiver Schreibvorgänge kopiert. Alle Chroma-Instanzen stoppen, nur einen Server oder embedded Client als Eigentümer des Pfads zulassen und Snapshots erst nach vollständigem Stopp ziehen.

Permission denied am Chroma-Pfad nach Festplattenwechsel—was ist passiert?

APFS-Volumes aus Backups oder Provider-Templates können root-gehörende Verzeichnisse tragen. chown -R für den Build-User über die Persistenzwurzel ausführen oder Ordner neu anlegen und Daten mit rsync -a samt Zeitstempeln migrieren.

Wo gehören Timeouts hin, wenn OpenClaw mein RAG-Tool aufruft?

Deadlines in der Tool-Implementierung direkt bei Chroma erzwingen (Python httpx timeout, gRPC-Deadline oder asyncio.wait_for). Das Gateway profitiert von globalen Upstream-Budgets, aber Vektor-Latenzspitzen lassen sich am zuverlässigsten im Skill-Code begrenzen.

Wie voll darf ein lokaler Vektorspeicher auf einem Miet-Mac werden?

Mindestens 15 bis 20 Prozent frei auf dem Volume mit Embeddings und SQLite-Beifiles; unter wenigen Gigabyte frei verhalten sich macOS und Indizierungstools unzuverlässig. Früher alarmieren, wenn Docker-Images oder Modellgewichte dieselbe Platte teilen.

2026 OpenClaw: Chroma-Snapshots, Abfrage-Timeouts & Plattenalarme auf gemietetem Remote-Mac

Retrieval-Augmented Generation auf gemietetem Remote-Mac nutzt häufig Chroma als lokalen Vektorspeicher direkt neben dem OpenClaw-Gateway. Dieser Leitfaden macht Persistenzpfade, konsistente Dateisystem-Snapshots, Gateway-Gesundheitsproben, Plattenkontingent-Alarme und Abfrage-Timeouts mit Schaltkreis für produktive KI-Compute-Workloads nachvollziehbar. Ohne diese Leitplanken kollidieren Skills mit unsichtbaren SQLite-Sperren, volle SSDs oder blockierenden Vektorpfaden trotz grünem /healthz. Grundlagen-Installation: OpenClaw Docker-Deploy & Härtung. Observability vertiefen: Gateway-Metriken & Prometheus-Alarme. Chroma teilt Speicher mit Containern: Docker/Podman Layer-Cache-Matrix für APFS-Freiraum-Disziplin.

Chroma-Persistenzverzeichnis und Snapshot-Schritte

Modus	RPO/RTO-Richtung	Operativer Preis
Kalter Snapshot (tar nach Stopp)	Minuten bis Stunden	Niedriges Korruptionsrisiko
rsync inkrementell	Stunden	Nach Quiesce oder Storage-Snapshots
Nur Gateway-/healthz	—	Deckt Chroma-Ausfälle nicht ab; Volume-Freiheit ergänzen

Chroma persistiert unter einem von Ihnen gewählten Verzeichnis—operativ wie eine kleine Datenbank: ein kanonischer absoluter Pfad, POSIX-Eigentümer gleich dem Account, der OpenClaw-Skills ausführt, und ausreichend freier Speicher auf einem Volume, das nicht mit macOS-Systemlogs konkurriert. Setzen Sie CHROMA_PERSIST_DIRECTORY=/Volumes/Data/chroma-prod in Shell-Profil, launchd-Plist oder Docker-Bind-Mount und referenzieren Sie identisch im OpenClaw-Skill—sonst divergieren Backup-Skripte und Laufzeit.

Kalter Snapshot (filesystem-konsistent). (1) Schreiber quieszieren: eingebetteten Client oder chroma run-Server stoppen, damit SQLite-Transaktionen abschließen. (2) Manifest festhalten: Collection-Namen, Embedding-Modell-ID, Chroma-Hauptversion (Major-Drift bricht Restore). (3) Archivieren:

# Pfade anpassen; nur bei gestopptem Chroma ausführen
export SRC="$CHROMA_PERSIST_DIRECTORY"
export STAMP=$(date -u +%Y%m%dT%H%M%SZ)
tar -C "$(dirname "$SRC")" -czf "/backup/chroma-${STAMP}.tgz" "$(basename "$SRC")"
shasum -a 256 /backup/chroma-${STAMP}.tgz > /backup/chroma-${STAMP}.tgz.sha256

Statt tar genügt rsync -a --delete zu einem NAS oder Objektspeicher, wenn Integrität und Bandbreite stimmen. Bewahren Sie mindestens zwei lokale Generationen und eine Off-Host-Kopie, solange ein einzelner Miet-Mac Ihr einziger Zustandspunkt bleibt. (4) Verifikation: Archiv auf zweitem Host entpacken und count() je Collection ausführen. (5) Produktionsprozess starten und den Restore-Befehl neben dem Backup-Zeitplan dokumentieren. Keine heißen Kopien: Chroma kombiniert SQLite mit Blob-Segmenten; parallele Writes erzeugen Locks oder stille Inkonsistenz. Für RPO unter einer Minute brauchen Sie storage-seitige Online-Snapshots oder ein kurzes Wartungsfenster.

OpenClaw-Gesundheitsproben und Alarmvorlagen

Das OpenClaw-Gateway bietet /healthz (Liveness) und /readyz (Readiness) auf dem HTTP-Listener, Standard 127.0.0.1:18789. Diese URLs sind die Herzschläge der Agent-Kontrollebene: bei Ausfall soll kein Skill—Chroma-basiert oder nicht—vorgeben, der Assistent sei zuverlässig. Prüfen Sie vom Miet-Host oder über einen SSH-Tunnel:

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

Übernehmen Sie dasselbe Scrape-Muster wie für Prometheus-static_config oder einen verwalteten Blackbox-Check; entscheidend sind stabile Labels (env=prod, role=openclaw-gateway, Provider-instance), damit Routing und Dedupe reproduzierbar bleiben.

Plattenkontingent-nahe Alarme ergänzen Gateway-Signale. Chroma wächst mit Dokumenten, Embedding-Dimension und Segment-Merges; volle Platten beenden SQLite-Zugriffe und belasten den Pagecache. Exportieren Sie freie Bytes via node_exporter, einem schlanken df -Pk-Cron mit Metrikdatei oder einem Vendor-Agenten. Richtwerte: Warnung unter rund 20 GB frei auf dem Chroma-Volume (an Batch-Größe anpassen), kritisch unter 5 GB oder wenn die extrapolierte Zeit bis 100 % bei aktuellem Ingest unter zwei Stunden liegt.

Signal	Startbedingung	Hinweis
Gateway /healthz	HTTP ≠ 200 bei zwei aufeinanderfolgenden Checks	15–30 s interaktiv
Gateway /readyz	Fehler bei gleichzeitig OK /healthz	Config/Deps—Logs zuerst
Volume freie Bytes	avail < 20e9 warn / < 5e9 crit	Pro Volume
Chroma HTTP (optional)	TCP- oder HTTP-Probe auf gebundenen Port	Nur Server-Modus

Verbinden Sie Alarme mit Ihren üblichen Kanälen und hinterlegen Sie in den Annotationen Runbook-Links zu Gateway-Token-Rotation, Sofort-Plattenanalyse und Wiederherstellung aus dem letzten validierten Chroma-Archiv.

Abfrage-Timeout- und Schaltparameter

Chroma-Abfragelatenz steigt mit Collection-Größe, Filterkomplexität und parallelem HNSW-Zugriff. Ein OpenClaw-Tool ohne Deadline blockiert den Sitzungs-Worker und verstärkt Retries über Kanäle. Setzen Sie Timeouts an der engsten Schicht—bei collection.query oder dem HTTP-Client zu chroma run—statt nur auf einen groben LLM-Upstream zu vertrauen.

Interaktive RAG-Tools: typischerweise 4–8 Sekunden Client-Deadline für Top-k mit moderaten Filtern auf Apple Silicon bis wenige Millionen Vektoren; 15–30 Sekunden nur für Batch-Jobs abseits des Nutzerpfads. Begrenzen Sie Parallelität (z. B. zwei bis vier Abfragen pro Gateway), damit Bursts den Index nicht fluten.

Schaltkreis (Circuit Breaker): zählen Sie Timeouts, 5xx oder Index-Fehler. Nach drei aufeinanderfolgenden Fehlern in fünf Minuten 30–120 Sekunden öffnen: deterministische degradierte Antwort an den Agenten plus error_class=chroma_breaker_open im Log, danach halb-offen mit einer Sondenabfrage. Passt zu projektweisen API-Budget-Fuses für externe Embeddings.

# asyncio-Deadline (illustrativ)
import asyncio

async def query_with_cap(coro, seconds=6.0):
    return await asyncio.wait_for(coro, timeout=seconds)

Synchrone Stacks: httpx.Client(timeout=6.0) oder gRPC-Deadlines liefern denselben Vertrag. Dokumentieren Sie Sekundenwerte im Skill-Manifest, damit On-Call zwischen Tuning und echtem Ausfall unterscheidet.

FAQ: typische Berechtigungs- und Pfadfehler

PermissionError: [Errno 13]. Der OpenClaw-User besitzt den Pfad nicht—typisch nach Image-Klon oder Restore. sudo chown -R $USER:staff "$CHROMA_PERSIST_DIRECTORY" oder neuen Baum mit rsync -a befüllen.

sqlite3.OperationalError: database is locked. Zwei Prozesse teilen das Verzeichnis oder ein Backup kopierte *.sqlite* während Writes. Alles stoppen, lsof prüfen, einen Prozess als alleinigen Owner neu starten.

launchd vs. SSH. Nur absolute Pfade in Plists und Compose—~/chroma expandiert unterschiedlich. APFS-Case-Sensitivity externer Volumes: Namen in Automation normalisieren. Docker: Host-Pfad vor docker compose up anlegen; später auf Linux-Worker dasselbe Muster für Labels und Rechte.