1. Debug Flags
The skill exposes a set of granular environment variable debug flags to capture logs from specific stages selectively, without enabling full global debug logging:
| Environment Variable | Purpose |
|---|---|
| OPENCLAW_DEBUG_MODEL_TRANSPORT=1 | Log request initiation, fetch responses, SDK headers, the first SSE event, stream completion, and transport-level errors |
| OPENCLAW_DEBUG_MODEL_PAYLOAD=summary | Output bounded truncated summaries of request payloads |
| OPENCLAW_DEBUG_MODEL_PAYLOAD=tools | Print all tool names visible to the LLM model |
| OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted | Output complete truncated & redacted JSON payloads (debug-only; prompt/message text may still remain visible) |
| OPENCLAW_DEBUG_SSE=events | Record timestamps for the initial stream event and full stream termination |
| OPENCLAW_DEBUG_SSE=peek | Print the first five redacted SSE event payloads |
| OPENCLAW_DEBUG_CODE_MODE=1 | Emit diagnostic logs at the code-mode tool execution layer |
Use the following command to stream real-time logs:
openclaw logs --follow
2. Boundary Classification for Rapid Troubleshooting
The skill categorizes all potential failure boundaries to narrow down investigation scope efficiently:
Config vs Activation
Configuration may enable tools, yet runtime execution can disable them via raw mode, empty allowlists, or model-native tool incompatibility. Always inspect the actual set of visible tools before enforcing provider payload constraints.
Tool Surface
Inspect the final list of tools exposed to the target model, not merely the tool registry or static config. Under code-mode, only the
exec and wait tools become active after successful activation.Provider Payload
Log request fields, model ID, service tier, inference hyperparameters, input token size, metadata keys, prompt-cache key existence, and tool names prior to SDK invocation.
Fetch vs SSE Distinction
A successful fetch response confirms HTTP headers reach the service; receiving the first SSE event proves the provider is returning streaming content. Latency between these two signals indicates stream/body/provider-side issues, not tool execution defects.
Worker & Distribution Layer
Run
pnpm build after modifying worker implementations, dynamic imports, package exports, lazy runtime boundaries, or publish target paths.Live Secret Key Validation
Validate missing provider credentials via the dedicated secret workflow; avoid aborting live validation entirely due to missing keys. Environment checks only verify variable existence and never print raw secret values.
3. Source Code Reference Index
Quick lookup table for core relevant source files and their responsibilities:
| File Path | Core Responsibility |
|---|---|
| src/agents/openai-transport-stream.ts | Model payload serialization + Responses stream handling |
| src/agents/provider-transport-fetch.ts | Guarded fetch requests & request timing tracking |
| src/agents/pi-embedded-runner/openai-stream-wrappers.ts | Wrapper logic for OpenAI / Codex model providers |
| src/agents/pi-embedded-runner/run/attempt.ts | Tool instantiation, tool search logic, code-mode activation gates |
| src/agents/code-mode.ts / src/agents/code-mode.worker.ts | Code-mode runtime logic and isolated worker process |
| src/agents/tool-search.ts | Central catalog and matching logic for tool search |
4. Targeted Proof Selection
Select the matching validation method based on the type of defect under investigation:
| Defect Type | Recommended Validation Approach |
|---|---|
| Isolated helper or payload logic bugs | Local targeted Vitest unit tests |
| Documentation or logging formatting defects | pnpm check:docs + git diff --check |
| Worker, distribution, lazy import or package surface errors | Targeted unit tests + full pnpm build rebuild |
| Live provider or model behavioral inconsistencies | Identical provider/model configuration + enabled debug flags + valid live API keys (if available) |
| Docker, package, Linux or CI environment consistency gaps | Crabbox containerized test environment |
| Continuous Integration pipeline failures | Exact commit SHA, associated job ID, full logs captured post-failure / job completion |
III. Primary Use Cases
-
Root Cause Analysis of Cross-Environment Behavioral DriftSystematically isolate fault boundaries when OpenClaw exhibits inconsistent behavior across local development environments, live model endpoints, multiple LLM providers, code-mode execution, tool search workflows, Crabbox containers, and CI pipelines.
-
Granular Debug Signal CaptureUtilize selective environment variable debug flags instead of verbose global debug logging to avoid log flooding, retaining only contextually relevant diagnostic data.
-
Consistency Validation Between Static Config and Runtime StateVerify whether declared configuration values take effect at runtime, inspect visible tool sets, and confirm successful code-mode activation.
-
Layer Separation for Transport vs Execution DefectsDifferentiate HTTP/streaming transport layer failures from tool execution logic defects by comparing fetch response timestamps against initial SSE event timestamps.
-
Fast Troubleshooting for Worker & Build Artifact IssuesValidate complete build integrity with
pnpm buildafter modifying worker logic, dynamic import declarations, or package module boundaries.
IV. Standard Debugging Workflow
1. Declare suspected fault boundary: config, tool construction, provider payload, fetch request, SSE streaming, transcript replay, worker/runtime, package/distribution, or CI pipeline
2. Enable the most precise available debug signals to prove or disprove the targeted boundary
3. Reproduce the defect using identical provider, model and configuration (unless the model itself is the controlled test variable)
4. Compare static declared configuration against live runtime activation state
5. Resolve the identified root cause
6. Re-run the minimal targeted failure reproduction test; expand investigation scope only if required by formal functional contracts
V. Core Governing Principles
- Fixed Test Variables: Retain identical provider, model and configuration during reproduction unless the model is the explicit experimental variable under test.
- Secret Safety Rule: Environment existence checks only validate whether a variable is set; raw secret values are never printed in logs or output.
- Standard Reporting Format: All debug reports must include: the tested boundary, exact redacted environment variables / CLI commands, observed diagnostic signals (tool names, first SSE event timestamps, etc.), root fix location, narrowing proof logic, and outstanding residual risk items.
VI. Summary
OpenClaw Debugging is a systematic diagnostic skill suite built around granular debug environment flags, standardized fault boundary classification, and source code reference indexes. It enables developers to rapidly identify root causes of inconsistent OpenClaw behavior across heterogeneous runtime environments. It is designed for OpenClaw engineers troubleshooting mismatches between local and production deployments, divergent behavior across LLM providers, abnormal code-mode / tool search execution, and CI pipeline failures, supporting signal-driven investigation instead of speculative trial-and-error debugging.
