openclaw-debugging

OpenClaw Debugging

Das Verhalten unterscheidet sich zwischen lokalen Tests, Live-Modellen, Anbietern (Providern), Code-Modus, Tool Search, Crabbox und CI: Debug-Signal einholen, bevor geraten wird.

Zuerst lesen

• docs/logging.md: Log-Dateien, openclaw logs, gezielte Debug-Flags.
• docs/reference/test.md: Lokale Testbefehle.
• docs/tools/code-mode.md: Code-Mode-Ausführung/Warten + Tool-Katalog-Regeln.
• $openclaw-testing: Test-Auswahl.
• $crabbox: Breite, Docker, Paket, Linux, Live-Key, CI-Paritätsprüfung.

Standardablauf

1. Verdacht auf Grenzbereich eingrenzen: Konfiguration, Tool-Konstruktion, Provider-Payload, Abruf, Stream/SSE, Transkript-Wiedergabe, Worker/Laufzeit, Paket/Verteilung, CI.
2. Engstes Signal hinzufügen/aktivieren, das den Grenzbereich beweist.
3. Mit demselben Provider/Modell/Konfiguration reproduzieren. Niemals zufällig Modelle wechseln, es sei denn, das Modell selbst ist die getestete Variable.
4. Konfigurierten Zustand mit der tatsächlichen Laufaktivierung vergleichen.
5. Ursache beheben.
6. Genauen fehlschlagenden Test erneut ausführen; nur verbreitern, wenn der Vertrag es erfordert.

Modell-Transport-Logs

Modellanforderungsform/Streaming-Timing: Gezielte Umgebungsflags statt globalem Debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway

Nützliche Flags:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: Anforderungsstart, Abruf-Antwort, SDK-Header, erstes SSE-Ereignis, Stream-Ende, Transportfehler auf info-Ebene.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: Begrenzte Payload-Zusammenfassung.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: Alle modellseitigen Tool-Namen.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: Gekürzte, geschwärzte JSON-Payload. Nur während des Debuggens; Aufforderungs-/Nachrichtentext kann weiterhin erscheinen.
• OPENCLAW_DEBUG_SSE=events: Zeitpunkt des ersten Ereignisses + Stream-Abschluss.
• OPENCLAW_DEBUG_SSE=peek: Erste fünf geschwärzte SSE-Ereignisse.
• OPENCLAW_DEBUG_CODE_MODE=1: Code-Mode-Tool-Oberflächendiagnose.

Logs verfolgen:

openclaw logs --follow

Häufige Grenzbereiche

• Konfiguration vs. Aktivierung: Aktivierte Konfiguration kann mit deaktivierten Ausführungs-Tools, roher Ausführung, leerer Whitelist, fehlender Modell-Tool-Unterstützung koexistieren. Überprüfen Sie die tatsächlich sichtbaren Tools, bevor Sie Provider-Payload-Invarianten durchsetzen.
• Tool-Oberfläche: Untersuchen Sie die endgültigen modellsichtbaren Tool-Namen, nicht nur das Registry-/Konfigurationsverzeichnis. Code-Modus = genau exec + wait nur nach tatsächlicher Aktivierung.
• Provider-Payload: Vor dem SDK-Aufruf Felder, Modell-ID, Service-Tier, Reasoning, Eingabegröße, Metadaten-Schlüssel, Vorhandensein von Prompt-Cache-Schlüsseln, Tool-Namen protokollieren.
• Abruf vs. SSE: Die Abruf-Antwort beweist, dass HTTP-Header angekommen sind; das erste SSE-Ereignis beweist den Fortschritt des Provider-Bodys. Eine Lücke hier deutet auf ein Stream-/Body-/Provider-Problem hin, nicht auf eine Tool-Ausführung.
• Worker/Verteilung: Worker, dynamische Importe, Paket-Exporte, träge Laufzeitgrenzen, veröffentlichte Pfade betreffen → pnpm build.
• Live-Keys: Fehlende Provider-Keys → konfigurierten Secret-Workflow vor der Deklaration eines blockierten Live-Beweises. Umgebungsprüfungen prüfen nur die Anwesenheit; geben niemals Geheimnisse aus.

Sitzungen und Transkripte abrufen

Chat-Sitzungs-Fehlerbericht: Tatsächliches Transkript, Absenderzuordnung, Anhänge als Beweismittel abrufen.

Zuerst CLI (benötigt konfigurierte Installation; sicher gegen Live-Gateway):

openclaw sessions list --agent <agentId> --json
openclaw sessions tail
openclaw sessions export-trajectory

Dokumentation: Store-Layout docs/reference/database-schemas.md; CLI https://docs.openclaw.ai/cli/sessions.

Roher Store: CLI nicht verfügbar (z.B. Remote-Host über SSH) oder Ereignisdetail erforderlich:

• Pro-Agent-Datenebene: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Kanonisches Schema: src/state/openclaw-agent-schema.sql.
• Gehosteter/Systemd-Zustand: Benutzer-Home des Dienstes (z.B. /home/openclaw/.openclaw/...), nicht root. Root kann eine separate fehlgeleitete Installation mit anderen Agents haben. Erwartetes Agent-Verzeichnis fehlt: Echte DB mit find / -maxdepth 6 -name openclaw-agent.sqlite finden.
• Web-Chat-URL-Sitzungs-ID-Fragment: /chat/<agentId>/<slug>-<hex>. Auflösen in session_nodes: session_key LIKE '%<hex>%' → current_session_id, display_name. Schlüsselform: agent:<agentId>:<surface>:<uuid>; Subagent-Sitzungen verwenden Surface subagent.
• Transkript: transcript_events (session_id, seq, event_json). event_json.message: role (user/assistant/toolResult) + content (String oder Teile des Typs text/toolCall/image).
• Absenderherkunft: Echte Benutzernachrichten enthalten message.__openclaw (senderId, senderName, senderIsOwner); laufzeitgenerierte Eingaben nicht. Unterscheiden Sie operatoreingetragenen Text von injizierten Aufforderungen damit.
• Volltext-Transkriptsuche: session_transcript_fts.
• Anhänge: media://inbound/<file> URLs → <state-dir>/media/inbound/<file>.
• Benutzerangehängte Bilder ≠ image-Inhaltsteile. Der Nachrichtenumschlag enthält message.__openclaw.media[] Einträge: url (media://inbound/<file>), contentType, kind, fileName. Nur-Teile-Extraktor übersieht jedes Bild; rohes event_json nach media:// durchsuchen. Remote-Host: scp-Dateien lokal (ein Remote-Pfad pro scp-Argument); dort lesen.

Hosts ohne sqlite3-Binär haben dennoch Node: node:sqlite benötigt keine Abhängigkeiten.

node -e 'const {DatabaseSync}=require("node:sqlite");
const db=new DatabaseSync(process.argv[1],{readOnly:true});
console.log(JSON.stringify(db.prepare(
  "SELECT seq,event_json FROM transcript_events WHERE session_id=? ORDER BY seq"
).all(process.argv[2])))' <db-pfad> <sitzungs-id>

• Live-Stores immer mit readOnly: true öffnen; niemals in den Zustand eines laufenden Gateways schreiben (Root AGENTS.md Validierungsregeln).
• Arbeit mit realistischen Daten: DB zuerst in das Dev-Zustandsverzeichnis kopieren.

Code-Verweise

• Modell-Payload + Responses-Stream: src/agents/openai-transport-stream.ts
• Geschützter Abruf/Timing: src/agents/provider-transport-fetch.ts
• OpenAI/Codex-Provider-Wrapper: src/llm/providers/stream-wrappers/openai.ts
• Tool-Konstruktion, Tool Search, Code-Mode-Aktivierung: src/agents/embedded-agent-runner/run/attempt.ts
• Code-Mode-Laufzeit und Worker: src/agents/code-mode.ts src/agents/code-mode.worker.ts
• Tool Search-Katalog: src/agents/tool-search.ts

Beweisauswahl

• Einzelfehler (Hilfsfunktion/Payload): Lokaler gezielter Vitest.
• Nur Dokumentation/Logging: pnpm check:docs + git diff --check.
• Worker/Verteilung/träges Import/Paket-Oberfläche: Gezielte Tests + pnpm build.
• Live-Provider/Modell-Verhalten: Gleicher Provider/Modell, Debug-Flags, echter Schlüssel falls verfügbar.
• Docker/Paket/Linux/CI-Parität: Aktueller dedizierter Linux-Worker, wenn möglich; andernfalls $crabbox.
• CI-Fehler: Exakter SHA, nur relevanter Job; Logs nur nach Fehler/Abschluss.

Ausgabegewohnheit

Berichten:

• getesteter Grenzbereich
• genauer Befehl/Umgebungsform, geschwärzt
• beobachtetes Signal, z.B. Tool-Namen oder Timing des ersten SSE-Ereignisses
• Fix-Stelle
• enger Beweis + verbleibendes Risiko