black-box

Indestructible audit logs for agent actions, stored in TiDB Zero.

Audits

Pass

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install black-box

Black Box (Powered by TiDB Zero)

Overview

Black Box is an indestructible audit log for AI Agents. It acts as a "Flight Data Recorder" that streams critical actions, errors, and reasoning chains to a persistent cloud database (TiDB Zero) in real-time.

Security & Provisioning

Bring Your Own Database (Recommended): Set TIDB_* environment variables.
Auto-Provisioning (Fallback): If no credentials are found, this skill uses the TiDB Zero API to create a temporary database for logging. The connection string is cached in ~/.openclaw_black_box_dsn.

Why use this?

Crash Survival: Local logs vanish when containers crash. Cloud logs persist.
Audit Trail: Prove exactly what your agent did and why (compliance).
Debugging: Retrieve the last 100 actions leading up to a failure.

Prerequisites

TiDB Credentials: Standard MySQL connection parameters (TIDB_HOST, TIDB_USER, etc.).
Network: Outbound access to TiDB Cloud (port 4000).

Usage

1. Log an Event

Record a critical action or error:

python {baseDir}/run.py --action log --level ERROR --message "System crash imminent: Memory leak detected"

2. Read Logs

Retrieve the last N logs (default: 10):

python {baseDir}/run.py --action read --limit 20

Schema

This skill creates a table agent_logs with columns: timestamp, level, message, metadata (JSON).