# Debug OpenClaw Models

Diagnose model, tool and streaming failures with logs and probes before code changes.

- Repository: https://github.com/openclaw/openclaw (393636 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add openclaw/openclaw --skill openclaw-debugging -g -a claude-code -y`
Codex: `npx skills add openclaw/openclaw --skill openclaw-debugging -g -a codex -y`
Cursor: `npx skills add openclaw/openclaw --skill openclaw-debugging -g -a cursor -y`
Gemini CLI: `npx skills add openclaw/openclaw --skill openclaw-debugging -g -a gemini-cli -y`

## Description

Debug OpenClaw model/provider/tool-surface/code-mode/streaming and live/Crabbox behavior; choose logs, probes, proof path before code changes; fetch stored sessions, transcripts, attachments as evidence.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

1. State suspected boundary: config, tool construction, provider payload, fetch,
   stream/SSE, transcript replay, worker/runtime, package/dist, CI.
2. Add/enable narrowest signal proving boundary.
3. Reproduce with same provider/model/config. Never randomly switch models
   unless model itself = tested variable.
4. Compare configured state with actual run activation.
5. Patch root cause.
6. Rerun exact failing probe; broaden only if contract requires.

## Model Transport Logs

Model request shape/stream timing: targeted env flags over global debug:

```bash
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, 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.
  Only while debugging; prompts/message text may still appear.
- `OPENCLAW_DEBUG_SSE=events`: first-event + stream-completion timing.
- `OPENCLAW_DEBUG_SSE=peek`: first five redacted SSE events.
- `OPENCLAW_DEBUG_CODE_MODE=1`: code-mode tool-surface diagnostics.

Watch logs:

```bash
openclaw logs --follow
```

## Common Boundaries

The rest: https://github.com/openclaw/openclaw/blob/HEAD/.agents/skills/openclaw-debugging/SKILL.md