Inhalt: Entscheidungsmatrix · Minimalberechtigte Tool-Liste · JSON-Schema-Validierung · Timeout und Schutzschalter · Logfelder · Repro-Schritte · Checkliste · FAQ
Für generisches strukturiertes Fahren ohne Agent-Rahmen siehe Instructor und Gateway-JSON-Schema; für Multi-Agent-Routing CrewAI mit Gateway-Tool-Routing; für Plugin-Whitelist-Muster Semantic-Kernel-Plugins; Kosten- und Aliasfragen Multi-Modell-Routing-Matrix.
Typische Produktionsrisiken: 1) Der Agent registriert mehr Tools als das Gateway erlaubt — Aufrufe scheitern sporadisch und wirken „nicht deterministisch“. 2) Pydantic-Modelle und Gateway-Validator divergieren — JSON wirkt valide, Downstream bricht dennoch. 3) Unbegrenzte Retries nach Schema-Fehlern füllen Unified Memory und erhöhen p95. 4) Logs enthalten Rohmodelltext statt einer Fehler-Envelope mit Korrelation.
Entscheidungsmatrix: Rand vs. Agent
Die Tabelle fasst fünf Schichten zusammen, die in Abnahme- und Postmortem-Dokumente gehören — konkrete Millisekunden und Fehlerfenster ersetzen Sie durch Ihre Messreihen auf Apple Silicon.
| Schicht | Aufgabe | Leitplankenbeispiel | Risiko ohne Gate | Nachweis |
|---|---|---|---|---|
| Agent | Minimale Tool-Registrierung | Nur Runbook-Tools | Überbreite Angriffsfläche | Diff der Toolliste im MR |
| Gateway | Whitelist erzwingen | Zentraler Name → Handler | Bypass durch Skripte | 403/422 mit tool_code |
| Schema | JSON Schema draft-07 | Identisch zu Pydantic-Export | Versteckte Sonderfälle | schema_hash in CI |
| Resilienz | Timeout und Breaker | Transport < Gateway-Deadline | Retry-Stürme | breaker.trip_rate |
| Observability | Einheitliche Logfelder | request_id, phase, pointer | PII in Klartext | Redaction-Review |
Minimalberechtigte Tool-Liste
Die autoritative Liste lebt im Gateway: jeder erlaubte Toolname mappt auf einen festen Handler mit Param-Schema. Im PydanticAI-Agent registrieren Sie bewusst nur die Teilmenge, die Ihr Runbook braucht — das reduziert Halluzinations-Raten bei frei erfundenen Funktionsnamen und erleichtert Code-Reviews. Jede Änderung erhält eine Versionszeile mit schema_hash, Gateway-Build und PydanticAI-Version.
JSON-Schema-Validierung
Halten Sie eine Quelle (schema.json) in Git; daraus generieren oder testen Sie Pydantic-Modelle und Gateway-Regeln auf Gleichheit. Negative Tests müssen identische Fehler-Envelopes liefern wie in Staging — inklusive schema_pointer und http_status. Für parallele Haystack-Pipelines bleibt dieselbe OpenClaw-Basis gültig; siehe Haystack-2.x-Anleitung.
Timeout und Schutzschalter
Modellieren Sie zwei Stufen: Transport-Timeout bis zum ersten vollständigen Nutzlastkörper und optional eine zweite Grenze für nachgelagerte Validierung. Der Halboffen-Breaker zählt Schema-Fehler und 5xx in einem gleitenden Fenster — wiederholte Schema-Verletzungen sind kein Erfolgspfad und dürfen nicht endlos retried werden. Dokumentieren Sie Parallelitätsdeckel pro Mandant gegen Unified Memory, besonders wenn Desktop-Indexer auf demselben Remote-Host laufen.
Logfelder
Einheitliche Felder pro Request: request_id, tenant_id, route, model_alias, tool_name oder null, phase (transport, schema, provider), latency_ms, schema_pointer, breaker_state. Fehler-Envelopes nach außen: code, short_message, remediation_hint — niemals API-Schlüssel, keine Rohprompts, keine vollständigen Modellausgaben in zentralen Aggregatoren.
| Feld | Pflicht | Semantik |
|---|---|---|
request_id |
ja | Ende-zu-Ende-Korrelation Gateway ↔ Agent ↔ Ticket |
phase |
ja | transport | schema | provider — triagiert Breaker vs. Netz |
schema_pointer |
bei Schema-Fehlern | JSON-Pointer aus Validator, kein Roh-JSON-Body |
tool_name |
bei Tool-Pfaden | Exakter Whitelist-Name; sonst null |
latency_ms |
ja | Wall-Time am Gateway für p95-Regressionen |
Reproduzierbare Schritte
1. Frisches venv auf dem Remote-Mac; Abhängigkeiten pinnen; Secrets mit restriktiven Rechten.
2. OpenClaw an 127.0.0.1 mit festem Port; Health-Check; Token-Datei nur für den Dienstkontext.
3. Client-Basis-URL auf den OpenAI-kompatiblen Gateway-Pfad; keine direkte Anbieter-URL im Agent.
4. Gateway-Whitelist mit Handlern füllen; Agent-Toolliste auf dieselbe Namensmenge begrenzen.
5. schema.json kanonisieren; CI-Test auf Gleichheit zwischen Export und Gateway-Validator.
6. Transport-Timeout < Gateway-Deadline; Breaker-Fenster und Retry-Deckel mit Jitter setzen.
7. Logging-Pipeline mit Redaction-Profil aktivieren; Smoke-Test mit absichtlich ungültigem JSON.
# Platzhalter — Pfade anpassen
python3 -m venv .venv && source .venv/bin/activate
pip install -U pip && pip install "pydantic-ai>=0.0.14" "openai>=1.0" "pydantic>=2.0"
printf "OPENAI_API_KEY=sk-gateway-…\nOPENAI_BASE_URL=http://127.0.0.1:8080/v1\n" > .env && chmod 600 .env
openclaw gateway up --bind 127.0.0.1 --port 8080 --token-file ./gateway.token
curl -sS http://127.0.0.1:8080/v1/models -H "Authorization: Bearer $(cat gateway.token)" | headAbnahme-Checkliste
- Toolliste im MR identisch zu Gateway-Whitelist und Agent-Registrierung.
schema_hashin Staging und Produktion übereinstimmend dokumentiert.- p95 und Breaker-Trip-Rate vor und nach Änderung notiert.
- Negative Schema-Tests liefern identische Envelope wie Runbook.
- Keine Secrets und keine Rohprompts in zentralen Logs nach Stichprobe.
- Zitierbar 1: Jede Freigabe nennt Gateway-Build, schema_hash und PydanticAI-Version in einer Zeile.
- Zitierbar 2: Retry-Obergrenze und Backoff-Jitter liegen in Versionskontrolle, nicht nur im Notebook.
- Zitierbar 3: Parallelitätsdeckel pro Mandant sind gegen Unified-Memory-Budget begründet.
FAQ
Doppelte Validierung? Ja an der Vertrauensgrenze; nicht-Python-Clients profitieren gleichermaßen.
429 oder 503? Exponentielles Backoff mit Deckel; Breaker-Zustand im Health-Endpoint exponieren.
Öffentliche Einstiege: Startseite, Tech-Blog, Hilfezentrum, Preise, Kauf und Miete — ohne Login-Pflicht zum Lesen.
Kurz: Whitelist am Gateway erzwingen, PydanticAI minimal halten, JSON Schema kanonisch halten, Timeouts und Breaker budgetieren, Logfelder und Envelopes vereinheitlichen — dann wird Agent-Betrieb auf einem Remote-Mac auditierbar.