核心用法
Black Box 是一个面向 AI Agent 的不可篡改审计日志系统，类比航空领域的"黑匣子"飞行数据记录仪。其核心功能围绕两个 CLI 操作展开：
- 日志写入：通过
python run.py --action log --level ERROR --message "..."将关键事件、错误和推理链实时流式写入 TiDB Zero 云端数据库 - 日志检索：通过
python run.py --action read --limit N快速回溯最近 N 条操作记录，默认返回 10 条，上限可调
系统采用极简的 agent_logs 表结构，包含时间戳、日志级别、消息内容和 JSON 元数据四个字段，兼顾查询效率与扩展灵活性。
显著优点
1. 灾难恢复能力：容器崩溃或本地存储丢失时，云端日志依然完整可恢复，解决传统本地日志的脆弱性问题
2. 合规审计价值：提供不可抵赖的操作轨迹记录，满足金融、医疗等强监管场景的审计溯源需求
3. 零配置快速启动：支持自动预配模式，未检测到环境变量时自动调用 TiDB Zero API 创建临时数据库，DSN 缓存至本地避免重复创建
4. 实时流式写入：关键事件即时持久化，降低数据丢失窗口
潜在局限
- 网络依赖性：完全依赖出站连接到 TiDB Cloud（4000 端口），离线或网络隔离环境无法工作
- 数据主权风险：日志存储于第三方云服务，敏感数据需评估跨境合规要求
- 自动预配隐患：临时数据库的生命周期管理不透明，长期使用可能面临连接失效或数据清理
- 无本地冗余：纯云端架构意味着网络中断期间日志完全无法记录
适合人群
- 运行长期任务或关键业务 Agent 的开发者
- 需要满足 SOC2、ISO27001 等合规要求的团队
- 容器化部署（K8s/Docker）且担心节点故障导致日志丢失的运维场景
- 需要跨会话、跨实例追踪 Agent 行为链的调试场景
常规风险
- 凭证泄露：
TIDB_PASSWORD等环境变量若未妥善保管，可能导致整个审计库被非法访问 - 缓存文件权限：
~/.openclaw_black_box_dsn若权限设置过宽，可能被本地其他进程读取 - API 滥用：自动预配模式下，频繁创建临时数据库可能触发云服务商速率限制或产生意外费用
- 注入风险：
--message参数虽经 Python 脚本处理，但若直接拼接 SQL 仍存在潜在的日志内容注入隐患（需确认 ORM/参数化实现）