Voice

Blackbox Openclaw

Name: Blackbox Openclaw
Rating: 3.5 (1 reviews)
Author: round1topo

By round1topo ⭐ 1 stars 👁 8 views ▲ 0 votes

OpenClaw tool-call observability plugin — records every AI agent tool call with session timeline, risk audit, health metrics and MCP query tools

GitHub

Install

npm install
cd

Configuration Example

{
  "plugins": {
    "load": {
      "paths": ["/你的路径/blackbox-openclaw"]
    },
    "entries": {
      "blackbox": { "enabled": true }
    }
  }
}

README

# Blackbox — OpenClaw 工具调用观测插件

记录 AI agent 的每一次工具调用，提供会话时间线、风险审计、健康指标三个视角。

> **前提**：需要已安装并运行 [OpenClaw](https://openclaw.ai)。

---

## 环境要求

- Node.js 22+
- pnpm 9+

---

## 安装

```bash
# 1. 克隆本仓库
git clone https://github.com/round1topo/blackbox-openclaw.git
cd blackbox-openclaw

# 2. 安装依赖
pnpm install
cd blackbox-ui && pnpm install && cd ..
```

在 `~/.openclaw/openclaw.json` 的 `plugins` 字段加入（路径改为你实际的克隆位置）：

```json
{
  "plugins": {
    "load": {
      "paths": ["/你的路径/blackbox-openclaw"]
    },
    "entries": {
      "blackbox": { "enabled": true }
    }
  }
}
```

重启 OpenClaw App 后，日志出现以下两行说明加载成功：

```
[plugins] [blackbox] SQLite opened at ~/.openclaw/blackbox.db
[plugins] [blackbox] REST API on http://127.0.0.1:4321
```

---

## 启动观测面板

```bash
cd blackbox-ui
pnpm dev
# → http://localhost:5173
```

> **注意**：插件只记录**新建 session** 的数据。向已有 session 发消息不会触发记录。
> 发 `/new` 开启新会话，或在新窗口打开对话。

---

## 目录结构

```
blackbox-openclaw/
├── src/           # 插件核心（hooks、SQLite、REST API、MCP 工具）
├── test/          # 单元测试
├── scripts/       # 辅助脚本（seed-demo.mjs 生成演示数据）
├── blackbox-ui/   # React + Vite 观测面板（4 个页面）
│   ├── src/
│   └── e2e/       # Playwright E2E 测试（22 个用例）
├── index.ts       # 插件入口
└── openclaw.plugin.json
```

---

## 四个页面

### Sessions — 会话时间线

**看什么**：每个 agent 会话做了什么，按时间顺序展开。

| 列 | 含义 |
|---|---|
| Agent | 哪个 agent（main / dev / search…） |
| Duration | 会话持续时间 |
| Tools | 工具调用总次数 |
| Status | `ok` 全部成功 / `error` 有失败 / `running` 进行中 |

- 点击 session 行 → 右侧展开事件时间线
- 点击事件行 → 展开该次调用的参数和返回值
- 红底行 = 该 session 有错误；`ERROR` 标签 = 该次工具调用失败

---

### High Risk Audit — 高风险操作审计

**看什么**：所有有副作用或需要确认的操作，按时间倒序。

- `SIDE-EFFECT` = 写文件、执行命令、调用外部 MCP 工具
- `CONFIRM` = Bash 和 Write（破坏性最强的两类）
- 粘贴 session ID → 只看这个会话的高风险操作

**典型用法**：agent 完成任务后，到这里核查它动了哪些文件、跑了哪些命令。

---

### Tool Health — 工具健康指标

**看什么**：每类工具的调用量、成功率、延迟分布。

| 列 | 含义 |
|---|---|
| Calls | 总调用次数 |
| Success Rate | 成功率（绿 ≥90% / 黄 ≥70% / 红 <70%） |
| Avg Latency | 平均延迟 |
| P95 Latency | 95 分位延迟（需 ≥20 次调用才显示，否则显示 `p95 n/a <20`） |
| Errors | 失败次数 |

---

### Error Attribution — 错误归因

**看什么**：哪些工具在出错，出什么类型的错，最近一次是什么时候。

- `WebFetch` + `RateLimitError` → agent 被限速，可能影响任务质量
- `Bash` + `ExitCode1` → 命令写法有问题，agent 在自动重试

---

## 演示数据

没有真实会话数据时，可以用 seed 脚本填充演示数据：

```bash
node scripts/seed-demo.mjs
```

包含 4 个场景：清理临时文件（含被阻止的 rm -rf）、代码 review、网络调研（含限速错误）、长时编码任务。

---

## 数据说明

**敏感字段自动脱敏**：`token` / `key` / `password` / `secret` / `api_key` 等字段值自动替换为 `***`。

**风险分类规则**：

| 工具 | Side Effect | Confirm | Target |
|---|---|---|---|
| Bash | ✓ | ✓ | shell |
| Write | ✓ | ✓ | filesystem |
| Edit / NotebookEdit | ✓ | — | filesystem |
| Read / Glob / Grep | — | — | filesystem |
| WebFetch / WebSearch | — | — | web |
| mcp__* | ✓ | — | mcp |

---

## 相关文档

- [AI 操作文档](./AGENT.md) — agent 如何通过 MCP 工具查询和使用观测数据

voice