openclaw-debugging skill

OpenClaw Debugging

Behavior differs between local tests, live models, providers, code mode, Tool Search, Crabbox, CI: get debug signal before guessing.

Read First

• docs/logging.md: log files, openclaw logs, targeted debug flags.
• docs/reference/test.md: local test commands.
• docs/tools/code-mode.md: code-mode exec/wait + tool catalog rules.
• $openclaw-testing: test-lane choice.
• $crabbox: broad, Docker, package, Linux, live-key, CI-parity proof.

Default Loop

stream/SSE, transcript replay, worker/runtime, package/dist, CI.

1. State suspected boundary: config, tool construction, provider payload, fetch,

unless model itself = tested variable.

1. Add/enable narrowest signal proving boundary.
2. Reproduce with same provider/model/config. Never randomly switch models

1. Compare configured state with actual run activation.
2. Patch root cause.
3. Rerun exact failing probe; broaden only if contract requires.

Model Transport Logs

Model request shape/stream timing: targeted env flags over global 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

Useful flags:

headers, first SSE event, stream done, transport errors at info.

• OPENCLAWDEBUGMODEL_TRANSPORT=1: request start, fetch response, SDK

Only while debugging; prompts/message text may still appear.

• OPENCLAWDEBUGMODEL_PAYLOAD=summary: bounded payload summary.
• OPENCLAWDEBUGMODEL_PAYLOAD=tools: all model-facing tool names.
• OPENCLAWDEBUGMODEL_PAYLOAD=full-redacted: capped, redacted JSON payload.

• OPENCLAWDEBUGSSE=events: first-event + stream-completion timing.
• OPENCLAWDEBUGSSE=peek: first five redacted SSE events.
• OPENCLAWDEBUGCODE_MODE=1: code-mode tool-surface diagnostics.

Watch logs:

openclaw logs --follow

Common Boundaries

raw run, empty allowlist, missing model tool support. Check actual visible tools before enforcing provider payload invariants.

• Config vs activation: enabled config can coexist with disabled run tools,

config. Code mode = exactly exec + wait only after actual activation.

• Tool surface: inspect final model-visible tool names, not only registry/

reasoning, input size, metadata keys, prompt-cache key presence, tool names.

• Provider payload: before SDK call, log fields, model id, service tier,

proves provider body progress. Gap here = stream/body/provider issue, not tool execution.

• Fetch vs SSE: fetch response proves HTTP headers arrived; first SSE event

runtime boundaries, published paths → pnpm build.

• Worker/dist: touching workers, dynamic imports, package exports, lazy

declaring live proof blocked. Env checks presence-only; never print secrets.

• Live keys: missing provider keys → configured secret workflow before

Fetching Sessions and Transcripts

Chat-session bug report: fetch actual transcript, sender attribution, attachments as evidence.

CLI first (needs configured install; safe against live gateway):

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

Docs: store layout docs/reference/database-schemas.md; CLI https://docs.openclaw.ai/cli/sessions.

Raw store: CLI unavailable (e.g. remote host over SSH) or event-level detail needed:

Canonical schema: src/state/openclaw-agent-schema.sql.

• Per-agent data plane: ~/.openclaw/agents//agent/openclaw-agent.sqlite.

not root's. Root may have separate stray install with different agents. Expected agent dir missing: locate real DB with find / -maxdepth 6 -name openclaw-agent.sqlite.

• Hosted/systemd state: service user's home (e.g. /home/openclaw/.openclaw/...),

Resolve in sessionnodes: sessionkey LIKE '%%' → currentsessionid, display_name. Key shape: agent:::; subagent sessions use surface subagent.

• Web chat URL session-id fragment: /chat//-.

event_json.message: role (user/assistant/toolResult) + content (string or parts of type text/toolCall/image).

• Transcript: transcriptevents (sessionid, seq, event_json).

(senderId, senderName, senderIsOwner); runtime-synthesized inputs do not. Distinguish operator-authored text from injected prompts with this.

• Sender provenance: real user messages carry message.__openclaw

message.openclaw.media[] entries: url (media://inbound/), contentType, kind, fileName. Parts-only extractor misses every image; grep raw eventjson for media://. Remote host: scp files locally (one remote path per scp argument); read there.

• Full-text transcript search: sessiontranscriptfts.
• Attachments: media://inbound/ URLs → /media/inbound/.
• User-attached images ≠ image content parts. Message envelope carries

Hosts without sqlite3 binary still have Node: node:sqlite needs no dependencies.

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-path> <session-id>

(root AGENTS.md Validation rules).

• Always open live stores readOnly: true; never write running gateway's state

• Realistic-data work: copy DB into dev state dir first.

Code Pointers

src/agents/openai-transport-stream.ts

• Model payload + Responses stream: