当前位置：首页 > news >正文

AgentWatch MCP 服务说明文档

news 2026/6/10 9:39:55

1. 服务概述

一句话简介：一个本地可观测性和控制平面工具，用于监控机器上所有AI编码代理的会话、令牌、成本和异常检测，提供终端实时跟踪和浏览器仪表板。

服务名称：AgentWatch
版本号：v0.0.3
开发者/提供方：mishanefedov
协议类型：MCP (Model Context Protocol)

2. 核心功能

该MCP服务提供的主要功能点：

实时多代理时间线：统一显示Claude Code、Codex、Gemini CLI、Cursor、Hermes和OpenClaw的事件流
事件详情面板：查看完整的工具调用、结果、令牌使用、成本和持续时间
子代理钻取：深入查看子代理的内部工具调用（支持Claude Code的Task工具）
项目和会话导航：按项目和会话组织事件，支持跨会话搜索
精确成本跟踪：支持缓存记账的令牌归因，包含cache_read和cache_create
异常检测：MAD z-score异常检测、循环检测（周期1-4）、预算警报
压缩可视化：显示上下文填充百分比和自动压缩标记
OpenTelemetry导出：支持导出到Jaeger、Tempo、Grafana，使用gen_ai.*语义约定
MCP服务器模式：代理可以查询自己的历史记录（5个工具通过stdio）
权限视图：显示每个代理的权限配置和风险标记

3. 使用场景

该服务适合在以下情况下使用：

多代理监控：在同一台机器上运行多个AI编码代理，需要统一的监控界面
成本管理：跟踪AI代理的令牌使用和成本，设置预算警报
异常检测：检测代理的异常行为，如循环模式、成本激增
会话分析：回放和分析代理会话，理解代理的决策过程
权限审计：查看和审计代理的权限配置，识别安全风险
可观测性集成：将代理事件导出到现有的可观测性工具（Grafana、Jaeger）
开发调试：调试AI代理的行为，查看工具调用和结果

4. 接入方式

4.1 服务端点

本地Web界面：http://127.0.0.1:3456

支持TUI（终端用户界面）和Web UI两种界面模式。

4.2 认证与权限

本地运行：

无需认证，完全本地运行
无云依赖，无遥测，无登录要求
所有数据存储在本地

4.3 数据格式

服务读取以下代理的日志文件：

Claude Code:~/.claude
Codex:~/.codex
Gemini CLI:~/.gemini
Hermes Agent:~/.hermes/state.db(SQLite)
OpenClaw: JSONL日志文件
Cursor: 配置级别（MCP服务器、.cursorrules）

4.4 服务器配置

安装：

npm i -g @misha_misha/agentwatch

启动TUI和Web UI：

agentwatch

仅启动Web UI：

agentwatch serve

运行MCP服务器：

agentwatch mcp

检查代理安装状态：

agentwatch doctor

环境变量：

AGENTWATCH_PORT=3456 AGENTWATCH_HOST=127.0.0.1

5. 接口定义

该服务提供Web UI路由和MCP服务器工具：

5.1 Web UI路由

路由	功能
/	实时时间线（SSE流），支持代理和类型过滤
/projects	检测到的项目网格，显示成本和会话数
/sessions/:id	按时间顺序的事件列表，支持导出.md/.json
/sessions/:id/tokens	每轮令牌堆叠区域图
/sessions/:id/compaction	上下文填充百分比和压缩标记
/sessions/:id/graph	调用图（d3-hierarchy SVG）
/sessions/:id/diffs	写入操作与触发它的提示配对
/sessions/:id/replay	编辑提示并在单轮执行中重新运行代理
/search	统一搜索（实时/跨会话/语义）
/trends	成本、缓存命中率、每个代理的事件（默认30天）

5.2 MCP服务器工具

MCP服务器模式提供5个工具，允许代理查询自己的历史记录：

查询会话历史：获取过去的会话和事件
搜索事件：跨会话搜索特定事件
获取统计信息：令牌使用、成本等统计数据
分析模式：识别行为模式和异常
导出数据：导出会话数据

5.3 代理覆盖范围

功能	Claude Code	Codex	Gemini CLI	Cursor	OpenClaw	Hermes
实时事件	✅	✅	✅	🟡	✅	✅
令牌使用+成本	✅	✅	✅	❌	✅	✅
工具调用配对	✅	✅	✅	❌	🟡	✅
预算警报	✅	✅	✅	❌	✅	✅
异常检测	✅	✅	✅	🟡	✅	✅
压缩可视化	✅	✅	❌	—	❌	❌

6. 快速开始

6.1 环境要求

Node.js ≥ 20（在CI中测试过20和22版本）
macOS或Linux（Windows在v0.x版本中不在支持范围内）
至少一个支持的AI编码代理（Claude Code、Codex、Gemini CLI等）

6.2 示例代码

快速启动：

npm i -g @misha_misha/agentwatch agentwatch doctor # 检测已安装的代理和就绪状态 agentwatch # 启动TUI和Web UI

配置预算警报（~/.agentwatch/budgets.json）：

{ "perSessionUsd": 5, "perDayUsd": 20 }

配置自定义触发器（~/.agentwatch/triggers.json）：

[ { "match": "curl .* \\| (bash|sh)", "title": "pipe-to-shell", "body": "{{agent}}: {{cmd}}" }, { "type": "file_write", "pathMatch": "^/etc/", "title": "/etc write" }, { "thresholdUsd": 0.5, "title": "expensive turn", "body": "cost {{cost}}" } ]