vivekchand/clawmetry

# 🦞 ClawMetry **洞察您的智能体思考。** 针对[OpenClaw](https://github.com/openclaw/openclaw) AI智能体的实时可观测性。 一条命令。零配置。自动检测一切。 ``` pip install clawmetry && clawmetry ``` 在 **http://localhost:8900** 打开即完成。  ## 您将获得什么 - **流程** — 实时动画图表，展示消息在通道、大脑、工具间流动并返回的过程 - **概览** — 健康检查、活动热图、会话计数、模型信息 - **用量** — Token 和成本跟踪，支持每日/每周/每月明细 - **会话** — 活跃的智能体会话，包含模型、Token、最后活动信息 - **定时任务** — 计划作业，包含状态、下次运行时间、持续时间 - **日志** — 颜色编码的实时日志流 - **记忆** — 浏览 SOUL.md、MEMORY.md、AGENTS.md、每日笔记 - **对话记录** — 用于阅读会话历史的聊天气泡界面 - **警报** — 预算上限、错误率触发器、智能体离线检测；路由至 Slack、Discord、PagerDuty、Telegram、电子邮件 - **审批** — 将破坏性删除、强制推送、数据库修改、sudo、软件包安装、网络调用等操作置于一键签核之后 ## 截图 ### 🧠 大脑 — 实时智能体事件流  ### 📊 概览 — Token 用量与会话摘要  ### ⚡ 流程 — 实时工具调用反馈  ### 💰 Token — 按模型与会话划分的成本明细  ### 🧬 记忆 — 工作区文件浏览器  ### 🔐 安全 — 态势与审计日志  ### 🚨 警报 — 预算上限、错误率触发器、到 Slack / Discord / PagerDuty / 邮件的 Webhook  ### ✋ 审批 — 将有风险的工具调用置于手动签核之后；基于策略的保护规则  ## 安装 **单行命令（推荐）：** ``` curl -sSL https://raw.githubusercontent.com/vivekchand/clawmetry/main/install.sh | bash ``` **pip 安装：** ``` pip install clawmetry clawmetry ``` **从源码安装：** ``` git clone https://github.com/vivekchand/clawmetry.git cd clawmetry && pip install flask && python3 dashboard.py ``` ## v2 前端开发 v2 版本的 React 应用位于 `frontend/` 目录，当 Flask 服务器启用 v2 功能启动时，通过 `/v2` 路径提供服务。 开发时建议使用两个终端： ``` # 终端 1: Flask API/服务器在 :8900 CLAWMETRY_V2=1 python3 dashboard.py ``` ``` # 终端 2: Vite 开发服务器在 :5173 cd frontend nvm use npm ci npm run dev ``` 打开 `http://localhost:5173/v2/`。Vite 会将 `/api` 请求代理到 `http://localhost:8900`，因此 React 应用无需额外设置 CORS 即可与本地 Flask 服务器通信。 构建随 Python 包分发的 bundle： ``` cd frontend npm run build ``` 生产环境 bundle 将写入 `clawmetry/static/v2/dist/`。 ## 运行时 / 智能体兼容性 ClawMetry 可以观察多种 AI 智能体运行时，不仅仅是 OpenClaw。每个非 OpenClaw 的运行时都附带一个专用的读取器适配器，将其原生的会话格式转换为 ClawMetry 的统一结构；守护进程会将它们导入到同一个 DuckDB 存储 + 云端快照中，并标记运行时来源，当存在多个运行时时，会话回放标签页会显示一个**运行时切换器**。有关完整的兼容矩阵和添加运行时的指南，请参见 [`docs/compatibility.md`](docs/compatibility.md)，有关 OpenClaw 系列运行时的入门说明，请参见 [`docs/RUNTIME_FAMILY.md`](docs/RUNTIME_FAMILY.md)。 | 运行时 / 智能体 | 状态 | 备注 | |---|---|---| | **OpenClaw** | 原生支持 | 参考运行时，自动检测 | | **PicoClaw** | Beta 适配器 | 扁平 `providers.Message` JSONL (`~/.picoclaw/workspace/sessions`)。对话记录、模型、工具调用。 | | **NanoClaw** | Beta 适配器 | 按会话存储的 SQLite (`data/v2-sessions`)。对话记录 + 消息计数。 | | **Hermes** | Beta 适配器 | SQLite `~/.hermes/state.db`。对话记录、模型、Token/成本。 | | **Claude Code** | Beta 适配器 | JSONL `~/.claude/projects/.../.jsonl`。对话记录、模型、工具调用 + 思考过程、Token 用量。 | | **Codex** | Beta 适配器 | 发布版 JSONL `~/.codex/sessions/...`。对话记录、模型、工具调用、Token 用量。 | | **Cursor** | Beta 适配器 | SQLite `state.vscdb`。聊天/作曲家对话记录、模型。 | | **Aider** | Beta 适配器 | 每个项目下的 `.aider.chat.history.md`。对话记录、模型、Token 计数。 | | **Goose** | Beta 适配器 | SQLite `~/.local/share/goose`。对话记录、模型、工具调用、Token 总量。 | | **opencode** | Beta 适配器 | SQLite `~/.local/share/opencode`。对话记录、模型、工具调用、Token + 成本。 | | **Qwen Code** | Beta 适配器 | JSONL `~/.qwen/projects/.../chats`。对话记录、模型、工具调用、Token 用量。 | “Beta 适配器”意味着 ClawMetry 提供了针对该运行时真实磁盘格式的读取器，每个都基于真实机器上的真实安装进行了构建和验证（参见 `tests/fixtures/runtimes//`）。适配器是只读的；每个适配器都如实反映其运行时实际存储的内容（例如 PicoClaw/NanoClaw/Cursor 不会将 Token 成本写入磁盘）。当多个运行时在同一节点上运行时，运行时切换器可以将会话视图限定为其中一个，以便进行深入分析。 ## OpenTelemetry — 厂商中立，将追踪数据发送到任何地方 ClawMetry 在两端都支持 **OpenTelemetry**，并使用 **GenAI 语义约定**，因此您的智能体追踪数据不会被锁定在单一工具中。 **导出**每个会话 — LLM 调用、工具、子智能体、Token、成本 — 作为 OTLP/HTTP GenAI spans 发送到任何收集器（Datadog、Grafana、Honeycomb 或您自己的 OTel Collector）： ``` clawmetry --otel-export http://localhost:4318/v1/traces # 等价于: CLAWMETRY_OTEL_EXPORT_ENDPOINT=http://localhost:4318/v1/traces clawmetry ``` 认证头和轮询间隔是可选的环境变量： ``` CLAWMETRY_OTEL_EXPORT_HEADERS='{"X-API-Key":"…"}' # extra HTTP headers CLAWMETRY_OTEL_EXPORT_INTERVAL=60 # seconds (default 60) ``` **接入** — 内置的 OTLP 接收器在 `/v1/traces` 和 `/v1/metrics` 路径接受来自任何其他来源的追踪和指标数据（运行 `pip install clawmetry[otel]` 以支持 protobuf 接入）。 您将获得零配置、本地优先的 ClawMetry 仪表板，**同时**数据也会保留在您团队已使用的任何后端中 — 无锁定，无需安装第二个智能体。 ## 配置 大多数人不需要任何配置。ClawMetry 会自动检测您的工作区、日志、会话和定时任务。 如果需要自定义： ``` clawmetry --port 9000 # Custom port (default: 8900) clawmetry --host 127.0.0.1 # Bind to localhost only clawmetry --workspace ~/mybot # Custom workspace path clawmetry --name "Alice" # Your name in Flow visualization ``` 查看所有选项：`clawmetry --help` ## 支持的通道 ClawMetry 会为您配置的每个 OpenClaw 通道显示实时活动。只有在您的 `openclaw.json` 中实际设置的通道才会出现在流程图中 — 未配置的通道会自动隐藏。 点击流程图中的任何通道节点，即可查看包含传入/传出消息计数的实时聊天气泡视图。 | 通道 | 状态 | 实时弹窗 | 备注 | |---------|--------|------------|-------| | 📱 **Telegram** | ✅ 完整 | ✅ | 消息、统计、10秒刷新 | | 💬 **iMessage** | ✅ 完整 | ✅ | 直接读取 `~/Library/Messages/chat.db` | | 💚 **WhatsApp** | ✅ 完整 | ✅ | 通过 WhatsApp Web (Baileys) | | 🔵 **Signal** | ✅ 完整 | ✅ | 通过 signal-cli | | 🟣 **Discord** | ✅ 完整 | ✅ | 服务器 + 通道检测 | | 🟪 **Slack** | ✅ 完整 | ✅ | 工作区 + 通道检测 | | 🌐 **Webchat** | ✅ 完整 | ✅ | 内置 Web UI 会话 | | 📡 **IRC** | ✅ 完整 | ✅ | 终端风格气泡界面 | | 🍏 **BlueBubbles** | ✅ 完整 | ✅ | 通过 BlueBubbles REST API 使用 iMessage | | 🔵 **Google Chat** | ✅ 完整 | ✅ | 通过 Chat API Webhooks | | 🟣 **MS Teams** | ✅ 完整 | ✅ | 通过 Teams 机器人插件 | | 🔷 **Mattermost** | ✅ 完整 | ✅ | 自托管团队聊天 | | 🟩 **Matrix** | ✅ 完整 | ✅ | 去中心化，支持端到端加密 | | 🟢 **LINE** | ✅ 完整 | ✅ | LINE Messaging API | | ⚡ **Nostr** | ✅ 完整 | ✅ | 去中心化 NIP-04 私信 | | 🟣 **Twitch** | ✅ 完整 | ✅ | 通过 IRC 连接聊天 | | 🔷 **飞书/Lark** | ✅ 完整 | ✅ | WebSocket 事件订阅 | | 🔵 **Zalo** | ✅ 完整 | ✅ | Zalo Bot API | ## Docker 部署 想在容器中运行 ClawMetry？没问题！🐳 **使用 Docker 快速启动：** ``` # 构建镜像 docker build -t clawmetry . # 使用默认设置运行 docker run -p 8900:8900 clawmetry # 或挂载你的 OpenClaw 工作区 docker run -p 8900:8900 \ -v ~/.openclaw:/root/.openclaw \ -v /tmp/moltbot:/tmp/moltbot \ clawmetry ``` **Docker Compose 示例：** ``` version: '3.8' services: clawmetry: build: . ports: - "8900:8900" volumes: - ~/.openclaw:/root/.openclaw:ro - /tmp/moltbot:/tmp/moltbot:ro restart: unless-stopped ``` ## 系统要求 - Python 3.8+ - Flask（通过 pip 自动安装） - OpenClaw 运行在同一台机器上（或用于 Docker 的挂载卷） - Linux 或 macOS ### 工作原理 ClawMetry 通过两种方式检测 NemoClaw： 1. **二进制检测** — 检查 `nemoclaw` CLI 并运行 `nemoclaw status` 获取沙盒信息 2. **容器检测** — 扫描运行中的 Docker 容器，查找 `openshell`、`nemoclaw` 或 `ghcr.io/nvidia/` 镜像，然后通过卷挂载或 `docker cp` 读取会话文件。 从 NemoClaw 容器同步的会话文件在云仪表板中标记有 `runtime=nemoclaw` 和 `container_id` 元数据，因此您可以一眼将其与标准 OpenClaw 会话区分开来。 ### 推荐设置：在宿主机上运行同步守护进程 为获得最佳体验，请在**宿主机**（而非沙盒内部）上运行 ClawMetry 的同步守护进程。这可以避免 NemoClaw 网络策略的限制。 ``` # 在宿主机上 (沙箱外部) pip install clawmetry clawmetry connect clawmetry sync ``` 同步守护进程将自动查找任何正在运行的 OpenShell 容器内的会话。 ### 可选：指定沙盒名称 如果自动检测不起作用，可以将 ClawMetry 指向正确的沙盒： ``` export NEMOCLAW_SANDBOX=my-sandbox-name clawmetry sync ``` ### 在沙盒内部运行（高级） 如果必须在 OpenShell 沙盒**内部**运行同步守护进程，请将此出口规则添加到您的 NemoClaw 网络策略中，以便它可以访问 ClawMetry 接入 API： ``` # nemoclaw-policy.yaml network: egress: - host: ingest.clawmetry.com port: 443 protocol: https ``` 应用配置： ``` nemoclaw policy apply --file nemoclaw-policy.yaml ``` ### 端口和端点 | 端点 | 端口 | 协议 | 是否必需 | |---|---|---|---| | `ingest.clawmetry.com` | 443 | HTTPS | 是（同步守护进程 → 云） | | `localhost:8900` | 8900 | HTTP | 是（本地仪表板 UI） | | Docker 套接字 (`/var/run/docker.sock`) | — | Unix 套接字 | 用于容器会话发现 | 同步守护进程仅向 `ingest.clawmetry.com` 发起出站 HTTPS 调用。无需入站端口。 ## 云部署 有关 SSH 隧道、反向代理和 Docker 的信息，请参阅 **[云测试指南](https://github.com/vivekchand/clawmetry/blob/main/docs/CLOUD_TESTING.md)**。 ## 测试 本项目使用 BrowserStack 进行测试。 [](https://browserstack.com) ## 遥测 当您在新机器上首次运行 `clawmetry` CLI 时，ClawMetry 会向 `https://app.clawmetry.com/api/install` 发送一次匿名的“首次运行”ping。我们使用它来统计安装量（这是我们对开源项目唯一的营销指标）以及了解用户安装了哪些智能体框架。 **每次安装仅发送一次 POST 请求**，包含： | 字段 | 示例 | 原因 | |---|---|---| | `install_id` | 存储于 `~/.clawmetry/install_id` 的随机 UUID | 用于去重；不关联您的邮箱或 api_key | | `version` | `0.12.167` | 了解实际使用的版本分布 | | `os` / `os_version` | `Darwin` / `25.3.0` | 平台支持优先级 | | `python` | `3.11.15` | Python 版本支持矩阵 | | `agent` | `openclaw` / `nemoclaw` / `hermes` / `none` | 我们下一步应集成哪些智能体 | | `is_ci` / `ci_provider` | `true` / `github_actions` | 区分人类安装和 CI 环境的噪音 | **我们不发送**：IP 地址（云服务端从请求中派生国家代码，然后丢弃 IP）、主机名、用户名、工作区路径、文件内容、您的 api_key、您的邮箱，以及任何 PII 或特定于工作区的数据。线路负载可在 [`clawmetry/telemetry.py`](clawmetry/telemetry.py) 中审计。 **选择退出**（以下任意一种方式均可永久禁用）： ``` export CLAWMETRY_NO_TELEMETRY=1 # per-shell export DO_NOT_TRACK=1 # W3C cross-tool standard touch ~/.clawmetry/notelemetry # persistent file marker ``` 此处的网络故障永远不会阻止 `clawmetry` 运行 — ping 操作在守护线程上以“发后即忘”方式执行，超时时间为 3 秒。 ## 许可证 MIT

🦞 洞察您的智能体思考
_{由 @vivekchand 构建 · clawmetry.com · OpenClaw 生态系统的一部分}

标签：AI agents, AI监控, API集成, OpenClaw, Web前端, 仪表板, 会话管理, 可观测性, 性能追踪, 成本追踪, 批准门控, 流可视化, 用户代理, 监控工具, 自动化监控, 警报系统, 请求拦截, 逆向工具