OpenClaw Blackbox

Debug OpenClaw runs from your terminal. Built for agent operators, still readable by humans.

blackbox doctor                         # Can Blackbox see OpenClaw state?
blackbox list failures --limit 10       # Recent failed or suspicious cron runs
blackbox list sessions --agent all      # Local session artifacts across agents
blackbox find request --query "..."     # Find the session behind a user request
blackbox inspect --session-id <id>      # Generate a report for one run

Blackbox answers the useful question first:

What happened in this agent run, and why did it fail or get weird?

It reads local OpenClaw evidence — transcripts, trajectory files, cron history, checkpoints, locks, delivery metadata, and tool traces — then renders deterministic reports as terminal output, Markdown, JSON, or static HTML.

Small warning: this is a local debugging tool. Reports can include prompts, tool arguments/results, URLs, and local paths. Review before sharing.

Install

npm install -g @shan8851/blackbox

Or from source:

git clone https://github.com/shan8851/openclaw-blackbox.git
cd openclaw-blackbox
pnpm install
pnpm run build
pnpm link --global

Blackbox reads ~/.openclaw by default. To inspect another OpenClaw home:

OPENCLAW_HOME=/path/to/.openclaw blackbox doctor

Commands

| Command | What it does | | --- | --- | | blackbox doctor | Check resolved paths and visible OpenClaw evidence | | blackbox list failures | Show failed or suspicious cron runs | | blackbox list sessions | Show local session transcript/trajectory artifacts | | blackbox find request | Find the session behind a user message/query | | blackbox inspect | Build a focused report for one run/session/request |

Examples

Inspect the latest failed run for a cron job:

blackbox inspect --cron-job "Example nightly research job" --latest-error

Generate a full Markdown report:

blackbox inspect \
  --cron-job example-nightly-research \
  --cron-run example-session-001 \
  --view full \
  --out reports/example-context-overflow.md

Open a local HTML report:

blackbox inspect --query "summarise the failed run" --agent all --open

Write JSON for downstream tooling:

blackbox inspect --session-id example-session-001 --json-out reports/example.json

Find the run behind a Discord/Telegram/etc request:

blackbox find request --query "summarise the failed run" --agent all
blackbox find request --message-id example-message-001 --agent main
blackbox find request --query "summarise the failed run" --agent all --commands

inspect --query is conservative: it only proceeds when matches resolve to one unique session. If the text spans multiple sessions, run find request first and inspect by the chosen --session-id.

Output modes

inspect always prints a terminal snapshot and writes a Markdown report unless you choose another path.

blackbox inspect --session-id example-session-001
blackbox inspect --session-id example-session-001 --view full
blackbox inspect --session-id example-session-001 --out report.md
blackbox inspect --session-id example-session-001 --json-out report.json
blackbox inspect --session-id example-session-001 --html-out report.html --open

Markdown has two views:

• --view simple — default triage report: outcome, likely cause, next checks, evidence summary.
• --view full — fuller postmortem: identity, evidence files, timeline, context pressure, tool footprint, raw snippets, compactions, recommendations.

JSON output uses the full deterministic BlackboxReport object. Simple/full are render modes over the same report model.

Agent-friendly bits

Human list/find output includes copy-pasteable Inspect: commands.

blackbox list failures --commands
blackbox list sessions --agent all --commands
blackbox find request --query "failed to send" --commands

Discovery commands support --json:

blackbox doctor --json
blackbox list failures --json
blackbox list sessions --agent all --json
blackbox find request --message-id 123 --json

Exit codes are explicit enough for scripts:

• 0 success
• 1 unexpected failure
• 2 usage / invalid argument
• 3 not found / missing OpenClaw state
• 4 ambiguous request match

Configuration

| Environment variable | Purpose | | --- | --- | | OPENCLAW_HOME | OpenClaw state directory. Defaults to ~/.openclaw. | | BLACKBOX_REPORT_DIR | Default report output directory. Defaults to reports/. |

Explicit output flags always win over BLACKBOX_REPORT_DIR.

Failure labels

The classifier is deterministic and based on local OpenClaw failure shapes. Current cause labels include:

• context_overflow
• message_delivery_failed
• timeout
• session_lock_timeout
• gateway_restart_interrupted
• model/auth labels
• tool read/write/edit/apply-patch labels
• unknown_error

Evidence conditions are separate from causes: missing_transcript, transcript_deleted, transcript_reset, missing_trajectory, checkpoint_present, and session_write_in_progress.

Reports also include confidence: high|medium|low. That describes evidence quality, not agent quality.

Development

pnpm install
pnpm run validate
npm pack --dry-run

During development you can run the CLI directly:

pnpm dev doctor
pnpm dev inspect --session-id example-session-001

Screenshots

HTML report

Inspect snapshot

Failure list

Doctor

License

MIT