Auf dieser Seite: Abhängigkeiten und Verzeichnislayout · Gateway-Token und Ausgangs-/Egress-Beschränkungen · QueryEngine-Anbindung: Code-Schritte · Protokolle und Doctor-Inspektion
Dieses Playbook richtet sich an RAG- und Agent-Entwickler, die Dokumente bereits mit LlamaIndex indexieren und auf einem gemieteten Apple-Silicon-Host Produktionsleitplanken brauchen. Es ergänzt die LlamaIndex-Workflows-Kostenmatrix und übernimmt Gateway-Disziplin aus der Haystack-2.x-OpenClaw-Anleitung, fokussiert aber auf QueryEngine-Kompositionsbäume und Python-Tooloberflächen.
Schmerzpunkte. 1. Modelle schlagen Toolnamen vor, die der Mandant nie freigegeben hat — dann entwertet jeder HTTP-Bypass die Policy. 2. Vektorabfragen treiben Schwanz-Latenzen; ohne Timeout-Breaker blockiert der gesamte Antwortpfad und Operatoren geben dem LLM die Schuld. 3. Stille Fehler trainieren Halluzinationen bei Quellen — Sie brauchen ein kompaktes Fehler-Envelope, das der ResponseSynthesizer lesen kann.
Abhängigkeiten und Verzeichnislayout
Starten Sie mit einem sauberen Arbeitsbaum auf dem Remote-Mac. Legen Sie mit python -m venv .venv eine virtuelle Umgebung an, pinnen Sie llama-index-core plus Ihren Vektor-Client, und halten Sie Embeddings und Indexvolumen lokal zusammen, damit Kaltstarts in Demos nicht unnötig übers WAN gehen. Reservieren Sie schemas/tools/ für JSON Schema, src/retrieval/ für gekapselte Retriever, tokens/ mit Modus 0600 außerhalb von Git sowie logs/jsonl/ für Worker-Ausgaben. Dokumentieren Sie Loopback-Ports für OpenClaw und optionale lokale Reranker in einer Tabelle, die CI und Menschen gemeinsam nutzen.
Gateway-Token und Ausgangs-/Egress-Beschränkungen
Richten Sie sich nach OpenClaw 2026.4.x: Node 22 LTS, CLI aktualisieren, dann openclaw gateway listen an 127.0.0.1 mit --token-file aus dem Mandanten-Dashboard. Erreichen Sie den Port vom Laptop nur über SSH-Reverse-Tunnel. Behandeln Sie den Bearer-String als mandantenspezifische Fähigkeit: er soll ausschließlich die Tool-Routen autorisieren, die Ihre QueryEngine je aufruft — nicht pauschales Internet-Egress aus dem Python-Prozess.
Erzwingen Sie standardmäßig Verweigerung für ausgehende Verbindungen vom Mac außer Gateway-Loopback und Vektor-Datenbank-Socket. Nebenwirkungs-HTTP aus LlamaIndex-Toolfunktionen läuft ausschließlich über eine Gateway-Client-Klasse, damit jeder Pfad dieselben Header, Korrelations-IDs und Whitelist-Prüfungen erbt.
| Aspekt | OpenClaw-Gateway-Schicht | LlamaIndex QueryEngine-Schicht |
|---|---|---|
| Policy | Toolnamen- und Routen-Allowlist, Bearer-Rotation, Request-Größenobergrenzen. | Retriever-Wahl, Chunking, Synthese-Prompts, Metadaten-Filter. |
| Timeouts | HTTP-Connect- und Read-Deadlines für Tool-POST-Bodies. | asyncio.wait_for um Vektorabfragen; Zähler-Fuse und Cooldown. |
| Retries | Begrenztes Backoff bei transienten 429 oder Verbindungsfehlern am Gateway. | Kein oder ein Retry bei geschlossenem Fuse; keine Schleifen über teure Suche. |
| Fehlerform | HTTP-Codes und Gateway-Validierungsfehler. | Strukturierte retrieval_skipped-Flags im Synthesekontext. |
QueryEngine-Anbindung: Code-Schritte
Arbeiten Sie in sieben geordneten Schritten, damit Diffs reviewbar bleiben.
1. Retriever kapseln. Subklassieren oder dekorieren Sie Ihren VectorIndexRetriever, sodass jeder aretrieve-Pfad unter asyncio.wait_for mit einer Deadline liegt — etwa 450 ms in der Entwicklung und 900 ms bei warmem Index. Fangen Sie TimeoutError ab und liefern Sie eine leere Node-Liste plus Metadaten retrieval_skipped=true.
2. Zähler-Fuse. Zählen Sie aufeinanderfolgende Verletzungen modulweit, keyed nach Indexname. Nach zwei Verletzungen innerhalb eines fünfminütigen gleitenden Fensters: Fuse öffnen — weiteres Retrieval kurzschließen bis zum Cooldown und fuse_opened_at an Metadaten anhängen.
3. Gateway-HTTP zentralisieren. Implementieren Sie GatewayToolClient.post(name, payload) mit Basis-URL und Token aus der Umgebung, injizieren Sie X-Correlation-Id, und lehnen Sie jeden name ab, der nicht in Ihrer eingecheckten Allowlist steht, bevor Bytes das Netz verlassen.
4. Nutzlasten lokal validieren. Führen Sie jsonschema.validate oder Pydantic-Modelle aus, die schemas/tools/*.json spiegeln, damit fehlerhafte Toolargumente schnell scheitern ohne Modellrunden zu verbrennen.
5. Tools in LlamaIndex registrieren. Exponieren Sie nur die gekapselten Funktionen als FunctionTool-Instanzen für QueryEngineTool oder Agent-Runner — niemals rohe httpx-Sessions in Prompts geben.
6. QueryEngine bauen. Instanziieren Sie die Engine mit dem gefuseten Retriever, hängen Sie Tools an, und erweitern Sie response_synthesizer-Vorlage oder Callbacks so, dass Metadaten mit Fehler-Envelopes im Endprompt als kurze Stichpunkte erscheinen, nicht als Roh-JSON-Wände.
7. Fehler zu Zusammenfassungen mappen. Übersetzen Sie Gateway-HTTP-Fehler und Fuse-Ereignisse in ein Objekt mit Schlüsseln stage, code, correlation_id und hint. Reichen Sie es über source_nodes-Metadaten oder parallele Dicts, die der Synthesizer explizit ausliest.
# Konzeptwächter — lokale Validierung nie überspringen
# ALLOWED_TOOLS = {"search_ticket", "post_audit_log"}
# assert tool_name in ALLOWED_TOOLS
# jsonschema.validate(instance=payload, schema=load_schema(tool_name))
# async with asyncio.timeout(0.45): nodes = await retriever.aretrieve(q)Protokolle und Doctor-Inspektion
Schreiben Sie pro QueryEngine-Aufruf eine JSON-Zeile mit Pipeline-ID, Korrelations-ID, Retriever-Laufzeit in Millisekunden, Fuse-Zustand und redigierten Toolnamen. Rotieren Sie Dateien täglich unter logs/jsonl/, damit Support Mac-Syslog und Gateway-Zugriffsprotokolle joinen kann, ohne Prompts zu greppen.
Nach jedem Abhängigkeits-Upgrade openclaw doctor --json ausführen und die Ausgabe bei Release-Notes archivieren. Rufen Sie /health am Gateway im Deploy-Hook mit dem Produktions-Token auf — Deploy abbrechen, wenn Latenz oder Auth von Staging abweicht. Für dasselbe JSON-Schema- und Breaker-Vokabular siehe die PydanticAI-Gateway-Anleitung.
Zitierbare Parameter für Runbooks
- Retriever-Deadline: 450 ms Dev, 900 ms warmer Index; Fuse nach zwei aufeinanderfolgenden Timeouts.
- Gateway-HTTP: Connect 2 s, Read 8 s; Backoff-Basis 250 ms mit vollem Jitter; kein Retry bei 401.
- Cooldown: Fuse mindestens 120 s offen lassen, bevor bei Vorfällen erneut Retrieval sondiert wird.
Wenn Sie vom Laptop-Tunnel zu einem Flottenknoten wechseln, kolokieren Sie Gateway, Indizes und MLX-freundliche Embeddings auf derselben Mac mini M4-Klasse, damit Korrelations-IDs unter Last weiterhin interpretierbar bleiben.
Öffentliche Seiten (ohne Login): Tarife auf Preise, Kauf und Miete bei Bedarf öffnen, Hilfezentrum lesen und im Tech-Blog nach verwandten Gateway-Artikeln stöbern.