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 1. **Bring Your Own Database (Recommended):** Set `TIDB_*` environment variables. 2. **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: ```bash 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): ```bash python {baseDir}/run.py --action read --limit 20 ``` ## Schema This skill creates a table `agent_logs` with columns: `timestamp`, `level`, `message`, `metadata` (JSON).