OpenClaw Blackbox
OpenClaw Blackbox CLI — inspect failed, stalled, expensive, or weird OpenClaw agent runs from local disk evidence; list sessions and failures; find the session behind a request; and generate terminal, Markdown, JSON, or HTML reports. Use when debugging OpenClaw cron runs, session failures, context overflows, missing transcripts/trajectories, message delivery issues, or when an agent needs deterministic run inspection without hidden LLM calls.
OpenClaw Blackbox
Use blackbox to inspect local OpenClaw run evidence and produce deterministic debugging reports.
Setup
npm install -g @shan8851/blackbox- Requires local OpenClaw state; by default it reads
~/.openclaw - To inspect another OpenClaw home:
OPENCLAW_HOME=/path/to/.openclaw blackbox doctor
Health Check
- Check visible OpenClaw evidence:
blackbox doctor - JSON health check:
blackbox doctor --json
List Evidence
- Recent failed or suspicious cron runs:
blackbox list failures --limit 10 - Filter by label:
blackbox list failures --label context_overflow - Emit runnable inspect commands:
blackbox list failures --commands - Local sessions across agents:
blackbox list sessions --agent all --limit 20 - Sessions with specific evidence:
blackbox list sessions --evidence checkpoint_present
Inspect Runs
- Latest failed run for a cron job:
blackbox inspect --cron-job "Example nightly job" --latest-error - Known session:
blackbox inspect --session-id <session-id> - Full Markdown report:
blackbox inspect --session-id <session-id> --view full --out reports/run.md - JSON report:
blackbox inspect --session-id <session-id> --json-out reports/run.json - HTML report:
blackbox inspect --session-id <session-id> --html-out reports/run.html --open
Find Requests
- Find the session behind a user request:
blackbox find request --query "summarise the failed run" --agent all - Find by message id:
blackbox find request --message-id <message-id> --agent main - Emit inspect commands only:
blackbox find request --query "failed to send" --commands
Output
inspectalways prints a terminal snapshot- Markdown defaults to
reports/<run>.mdunless--outis set - Set
BLACKBOX_REPORT_DIRto change the default report directory - Discovery commands support
--jsonfor machine-readable output --view simpleis the default triage report;--view fullincludes fuller evidence and timeline details
Agent Notes
- Prefer Blackbox before guessing why an OpenClaw run failed if local evidence exists
find request/inspect --queryare conservative; if a query maps to multiple sessions, inspect by explicit--session-id- Reports can include prompts, tool arguments/results, URLs, and local paths; review before sharing externally
- Blackbox is disk-first and should not make hidden LLM calls by default
- Failure labels include
context_overflow,message_delivery_failed,timeout,session_lock_timeout,gateway_restart_interrupted, model/auth labels, tool failure labels, andunknown_error - Evidence labels include
missing_transcript,transcript_deleted,transcript_reset,missing_trajectory,checkpoint_present, andsession_write_in_progress
Notes
- Exit codes: 0 success, 1 unexpected failure, 2 usage/invalid argument, 3 not found/missing OpenClaw state, 4 ambiguous request match
- Package name:
@shan8851/blackbox; binary name:blackbox; skill/ClawHub slug:openclaw-blackbox
Related skills
- Downloads
- 798All time
- Security audit
- Review
- Last updated
- 6mo ago
- Current version
- v0.1.0
- License
- MIT-0
