$ ~/registry/skill/openclaw-agents-skills-openclaw-debugging

SKILL

openclaw-debugging

Name: openclaw-debugging
Author: openclaw

Diagnose OpenClaw issues by choosing logs, probes, and proof paths first.

Stars

★ 382,582

Source

GitHub

Updated

2026-07-11

// securityLow risk

Prompt only, no code
Open source
Community-trusted· 377.5k

Summary

The material indicates a prompt/documentation-style debugging skill with no required secrets and no declared remote endpoints. It comes from a highly trusted open-source GitHub repository, so overall risk is low; the referenced logging and debug commands appear instructional rather than capabilities of the skill itself.

CredentialsLow risk

No keys or environment variables are required per the material. Although the README mentions live-key/debug scenarios, this skill does not appear to collect, store, or manage credentials directly.

Network egressLow risk

No remote endpoints are declared, and the system flags it as prompt-only. References to providers, SSE, and gateway behavior describe the target being debugged, not network egress performed by the skill itself.

Code executionLow risk

Based on the material, this is a debugging workflow/documentation skill rather than an executable tool. Example commands such as `openclaw gateway`, `openclaw logs`, and `pnpm build` are instructional and do not show that the skill itself can spawn processes or execute code.

Data accessLow risk

The documentation discusses logs, tests, and configuration boundaries, but it does not indicate that the skill can directly read or write local files, repositories, or other data resources. No excessive access is requested.

Supply chainLow risk

The source is an open-source GitHub repository with extremely high community adoption (~377k stars), which materially lowers supply-chain risk. License and maintenance status are unspecified, but there are no clear red flags such as closed source, abandoned distribution, or suspicious packaging in the provided material.

Recommendations

Treat it as a documentation/prompt skill, and do not assume example commands in the README are safe to execute automatically.
If used for real debugging, avoid verbose logging modes that may capture prompt or message content, and verify redaction behavior first.
Review the actual repository code and recent commit activity to confirm maintenance status before production use.

Audited by: gpt-5.4 · 2026-06-17

// install

Copy the install command and let the AI configure it · recommended for beginners

Please install the "openclaw-debugging" skill from askskill:
1. Download https://raw.githubusercontent.com/openclaw/openclaw/main/.agents/skills/openclaw-debugging/SKILL.md
2. Save it as ~/.claude/skills/openclaw-debugging/SKILL.md
3. Reload skills and tell me it's ready

// download

Download SKILL.mdInstall manifest ↗

// examples

Investigate broken streaming output

Prompt

Help me debug an OpenClaw streaming issue: responses stop midway. Do not change code first. Give me a troubleshooting order, specify which logs to inspect, what probes to add, how to distinguish model-side, provider-side, tool-surface, or code-mode issues, and provide a minimal reproduction and evidence collection checklist.

Expected

A step-by-step debugging plan with log checkpoints, probe suggestions, attribution paths, and a repro checklist.

Pinpoint tool invocation failures

Prompt

OpenClaw often fails when invoking tools. Build a debugging framework across the model, provider, and tool-surface layers: what to verify at each layer, what evidence to inspect, how to decide whether to drill deeper, and end with a decision tree.

Expected

A layered debugging framework and decision tree to quickly narrow the root cause of tool invocation failures.

Analyze live/Crabbox abnormal behavior

Prompt

I’m seeing abnormal OpenClaw behavior in live/Crabbox mode. Do not jump to fixing it; first create a validation plan including observation metrics, recommended logs to collect, key control experiments, and how to prove whether the issue comes from the environment, session state, or code path.

Expected

A validation and attribution plan to prove the source of abnormal behavior and guide later fixes.

// docs

OpenClaw Debugging

Use this skill when OpenClaw behavior differs between local tests, live models, providers, code mode, Tool Search, Crabbox, or CI, and the next move should be a debug signal rather than a guess.

Read First

docs/logging.md for log files, openclaw logs, and targeted debug flags.
docs/reference/test.md for local test commands.
docs/reference/code-mode.md for code-mode exec/wait and tool catalog rules.
Use $openclaw-testing for choosing test lanes.
Use $crabbox for broad, Docker, package, Linux, live-key, or CI-parity proof.

Default Loop

State the suspected boundary: config, tool construction, provider payload, fetch, stream/SSE, transcript replay, worker/runtime, package/dist, or CI.
Add or enable the narrowest signal that proves that boundary.
Reproduce with the same provider/model/config. Do not randomly switch models unless the model itself is the variable being tested.
Compare configured state with actual run activation.
Patch the root cause.
Rerun the exact failing probe, then broaden only if the contract requires it.

Model Transport Logs

Use targeted env flags instead of global debug when the model request shape or stream timing matters:

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:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1: request start, fetch response, SDK headers, first SSE event, stream done, and transport errors at info.
OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: bounded payload summary.
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: all model-facing tool names.
OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: capped, redacted JSON payload. Use only while debugging; prompts/message text may still appear.
OPENCLAW_DEBUG_SSE=events: first-event and stream-completion timing.
OPENCLAW_DEBUG_SSE=peek: first five redacted SSE events.
OPENCLAW_DEBUG_CODE_MODE=1: code-mode tool-surface diagnostics.

Watch logs with:

openclaw logs --follow

Common Boundaries

Config vs activation: config can be enabled while the run disables tools, is raw, has an empty allowlist, or lacks model tool support. Check the actual visible tools before enforcing provider payload invariants.
Tool surface: inspect final model-visible tool names, not only the tool registry or config. Code mode means exactly exec and wait only after it actually activates.
Provider payload: log fields, model id, service tier, reasoning, input size, metadata keys, prompt-cache key presence, and tool names before SDK call.
Fetch vs SSE: fetch response proves HTTP headers arrived; first SSE event proves provider body progress. A gap here is a stream/body/provider issue, not tool execution.
Worker/dist: run pnpm build when touching workers, dynamic imports, package exports, lazy runtime boundaries, or published paths.
Live keys: use the configured secret workflow for missing provider keys before saying live proof is blocked. Env checks are presence-only; never print secrets.

Code Pointers

Model payload + Responses stream: src/agents/openai-transport-stream.ts
Guarded fetch/timing: src/agents/provider-transport-fetch.ts
OpenAI/Codex provider wrappers: src/agents/pi-embedded-runner/openai-stream-wrappers.ts
Tool construction, Tool Search, code-mode activation: src/agents/pi-embedded-runner/run/attempt.ts
Code-mode runtime and worker: src/agents/code-mode.ts src/agents/code-mode.worker.ts
Tool Search catalog: src/agents/tool-search.ts

Proof Choice

Single helper/payload bug: local targeted Vitest.
Docs/logging-only: pnpm check:docs and git diff --check.
Worker/dist/lazy import/package surface: targeted tests plus pnpm build.

…

View full docs ↗

Create OpenClaw Docker end-to-end tests and live provider lanes.

openclawGet→

$ loading_