╔╗╚╝

Skill

openclaw-blackbox

CLI TOOLS🦞
Back to list
Up
+Down
Move selection
Left
+Right
Collapse / expand folder
Enter
Open selected file
C
Copy active file
Backspace
Back to list
?
Keyboard help
╔╗╚╝
╠═Files════════════════════════════════════════════════════════════╣
╔╗╚╝
╠═Preview════════════════════════════════════════════════════════════╣

openclaw-blackbox Skill

SKILL.md

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

  • inspect always prints a terminal snapshot
  • Markdown defaults to reports/<run>.md unless --out is set
  • Set BLACKBOX_REPORT_DIR to change the default report directory
  • Discovery commands support --json for machine-readable output
  • --view simple is the default triage report; --view full includes fuller evidence and timeline details

Agent Notes

  • Prefer Blackbox before guessing why an OpenClaw run failed if local evidence exists
  • find request / inspect --query are 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, and unknown_error
  • Evidence labels include missing_transcript, transcript_deleted, transcript_reset, missing_trajectory, checkpoint_present, and session_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