当团队规模引入多个 Claude Code 代理协同作业时，单一终端的会话监控已无法满足运维需求。代理团队可能同时处理代码审查、测试生成、文档编写等不同任务，每个代理的 token 消耗速率、当前执行状态、任务队列长度都成为资源调度与成本控制的关键信号。构建一套实时监控仪表盘，本质上是在代理可观测性（Observability）基础设施上叠加团队级别的聚合视图，使运维人员能够在单一界面掌握全局动态。

监控数据采集层设计

代理团队的监控数据来源分为两类：本地遥测与远程遥测。本地遥测指从每个代理进程的运行环境直接读取指标，例如通过 Claude Code 内置的 OpenTelemetry 导出器将每一次模型调用的 token 数量、延迟、状态码推送至后端。远程遥测则通过 MCP（Model Context Protocol）协议从任务调度层获取代理的存活状态、任务队列深度、代理间消息传递延迟。这两类数据在采集阶段就需要统一标签体系，确保后续聚合能够按团队、项目、代理角色等维度切片。

具体实现时，推荐在每个代理的工作目录下部署轻量级的 OTLP（OpenTelemetry Protocol）导出器，配置指向统一的 OpenTelemetry Collector 实例。Collector 负责接收来自数十个代理的指标流，进行初步的聚合与采样后，将数据转发至时序数据库。对于高吞吐场景，采样率可设为 10% 至 30%，但在告警路径上应保留全量数据以确保异常不被遗漏。

核心指标体系

代理团队的监控指标需要覆盖资源消耗、执行效率、协作状态三个层面。资源消耗层面最核心的指标是每个代理的 token 消耗速率，包括输入 token、输出 token、缓存读取 token、缓存写入 token 四个细分项。这四项数据可以计算出当次会话的预估成本，也是成本分摊到团队成员的依据。推荐将每千 token 的成本因子做成配置项，便于在不同模型之间切换时自动更新计算逻辑。

执行效率层面需要追踪首次响应延迟（First Token Time）、单次请求总延迟、错误率三个指标。代理团队的协作效率往往取决于最慢的那个代理，因此监控最坏情况延迟（Worst-case Latency）比平均延迟更有实际意义。协作状态层面则需要捕获当前代理数量、活跃代理数量、正在执行任务的代理数量、等待任务的代理数量，以及代理间的消息队列积压长度。这些状态指标可以通过定时轮询代理注册中心或任务调度器获得，无需在每个代理内部额外部署采集逻辑。

仪表盘布局与可视化策略

面向代理团队的仪表盘推荐采用三层结构：顶层是全局概览，包含当日累计 token 消耗、总成本、活跃代理数、任务吞吐量四个核心卡片；中层是团队或项目维度的分屏视图，按代理角色（编码、审查、测试等）分别展示各组的 token 消耗趋势与延迟分布；底层是单代理的详细面板，当点击中层某个代理组中的具体代理时，展示其最近 100 次请求的详细日志与指标。

在可视化工具选型上，Grafana 与 SigNoz 是当前生态最成熟的方案。Grafana 的优势在于社区面板丰富，可以快速搭建包含热力图、状态时间线、流量图在内的复杂布局；SigNoz 则在链路追踪（Trace）与指标关联上有天然优势，适合需要深入分析某次异常请求根因的场景。对于中小规模团队，建议使用 Grafana 搭配 Prometheus 作为后端存储，采集间隔设为 15 秒即可满足实时性需求，同时对存储压力也在可接受范围内。

告警规则与回滚机制

告警规则的设计需要在敏感度与噪声之间取得平衡。推荐的告警阈值包括：单代理每分钟 token 消耗超过预设上限的 150%、代理响应延迟超过 10 秒、代理连续失败超过 3 次、代理间消息队列积压超过 100 条。当触发告警时，系统应自动记录触发时刻的完整上下文，包括所有代理的状态快照与最近 1 分钟的指标数据，便于后续复盘。

回滚机制方面，建议为每个代理配置独立的任务超时阈值与重试策略。当代理连续超时超过阈值时，调度器自动将其从任务池中摘除，并将积压任务重新分配给其他健康代理。同时保留被摘除代理的完整日志与指标数据至少 7 天，以便排查是代理本身的代码问题还是外部依赖导致的超时。

关键配置参数

在工程落地时，以下参数需要根据实际团队规模与模型进行调优。Collector 的 OTLP 接收端口默认使用 4317（gRPC）或 4318（HTTP），确保各代理的网络策略已放行。Prometheus 的 Scrape Interval 建议设为 15 秒至 30 秒之间，过短的采集间隔会导致存储写入压力骤增。Grafana 面板的自动刷新间隔推荐与采集间隔保持一致，避免数据不同步造成的误判。对于 token 成本计算，Claude 3.5 Sonnet 的参考价格为每百万输入 token 3 美元、每百万输出 token 15 美元，实际配置时应将此因子做成环境变量便于动态调整。

监控代理团队的本质是将多代理系统的内部状态外化，使运维人员能够在问题影响扩大之前介入。通过上述架构设计与参数选型，团队可以在保证实时性的前提下，以较低的成本构建起可持续演进的监控体系。

参考资料

  • Claude Code 遥测监控器项目，通过 OpenTelemetry OTLP 协议实现实时 token 使用量与成本分析仪表板
  • SigNoz 官方文档，详解如何将 OpenTelemetry 集成至 Claude Code 可观测性实践