AgentMeter 使用指南¶

AgentMeter 是一款桌面端 Agent 用量工具，用于查看本机编码 Agent 的账号、额度和 Token 使用情况。将 AgentMeter 接入观测云后，还可以把用量指标及 Agent 运行链路上报到当前工作空间，统一分析 Agent 的使用量、性能和调用过程。

AgentMeter 当前支持 Codex、Claude Code 和 WorkBuddy。不同 Agent 可提供的数据有所不同：

安装 AgentMeter¶

安装前，请先在当前设备安装并登录需要查看的 Agent。根据操作系统和处理器架构下载对应安装包：

macOS¶

1. 打开下载的 DMG 文件；
2. 将 AgentMeter 拖入 Applications（应用程序）；
3. 从应用程序目录启动 AgentMeter。

AgentMeter 启动后常驻菜单栏，不显示 Dock 图标。

Windows¶

1. 解压下载的 ZIP 文件；
2. 运行其中的安装程序；
3. 安装完成后启动 AgentMeter。

AgentMeter 启动后常驻系统托盘。

Linux¶

Debian 或 Ubuntu 使用以下命令安装 DEB 包：

sudo apt install ./AgentMeter-latest-linux-<架构>.deb

Fedora 或 RHEL 使用以下命令安装 RPM 包：

sudo dnf install ./AgentMeter-latest-linux-<架构>.rpm

将 <架构> 替换为 arm64 或 amd64。安装完成后，从应用列表启动 AgentMeter。

查看 Agent 用量¶

启动 AgentMeter 后，点击菜单栏或系统托盘中的 AgentMeter 图标打开悬浮面板。AgentMeter 会自动检测当前设备中已安装的 Agent，并展示可读取的用量信息。

• 点击刷新，立即更新账号、额度及用量数据；
• 点击 Token 指标，查看按日、月历或趋势图展示的历史用量；
• 进入设置 > Agents，选择需要在悬浮面板或系统栏中展示的 Agent，并拖动调整展示顺序；
• 进入设置 > 通用，配置语言、外观和开机自动启动；
• 进入设置 > 关于，检查并安装 AgentMeter 更新。

Claude Code 首次接入额度读取后，需要打开或重启一次 Claude Code 会话。若当前账号或 Claude Code 版本没有返回订阅额度字段，AgentMeter 仍可展示本机 Token 历史。

接入观测云¶

如需将 Agent 数据上报到观测云，进入 设置 > 服务接入。服务接入包含以下两种采集层级：

基础采集由 AgentMeter 内置；增强采集由 AgentMeter 管理 obs-agent-connector。两种采集可分别按 Agent 开启。

第一步：配置连接¶

进入 Agent 监测 > 总览 > 接入 Agent，在接入配置页面获取当前工作空间的 Data Endpoint 和 X-Token。然后在 设置 > 服务接入 > 连接配置中导入 JSON 配置文件，或手动填写以下信息：

导入文件使用以下格式：

{
  "schemaVersion": 1,
  "ingestEndpoint": "<Data Endpoint>",
  "xToken": "<X-Token>",
  "user_id": "<User ID>",
  "user_name": "<User Name>"
}

配置文件必须使用 .json 扩展名，且大小不超过 64 KB。保存后，AgentMeter 会隐藏 X-Token，不会在界面中显示完整值。

第二步：开启基础采集¶

在基础采集区域，为需要上报用量指标的 Agent 开启开关。开启后 AgentMeter 会立即上报一次数据，之后每 60 秒上报最新快照。

基础采集数据写入 agent_runtime 指标集，AgentMeter 指标字段以 agent_meter_ 开头。基础采集只包含用量和账户快照，不会生成 Session 或 Trace 数据。

第三步：开启增强采集¶

1. 在增强采集区域点击安装连接器；
2. 安装完成后，为需要采集运行链路的 Agent 开启增强采集；
3. 根据页面提示完成配置和验证；
4. 重启正在运行的 Agent 会话，使采集配置生效；
5. 使用 Agent 发起一次新会话或新任务。

AgentMeter 只管理当前设备中已检测到且受支持的 Agent。连接器安装后，可以继续在服务接入页面按 Agent 单独启用、停用、验证或移除集成。

验证数据¶

完成服务接入后，可按采集层级验证数据：

• 基础采集：在指标分析中选择 agent_runtime 指标集，查询以 agent_meter_ 开头的指标字段；
• 增强采集：进入 Agent 监测 > 查看器，按 Agent 类型、User、Session 或 Trace 查看数据；
• 趋势分析：进入 Agent 监测 > 分析看板，按 Agent 类型、Agent ID 或 Agent 名称筛选数据。

若刚开启增强采集，请使用 Agent 完成一次新任务后再查询。采集配置不会补传启用前的完整 Trace 数据。

配置长任务通知¶

AgentMeter 支持在 Codex 长任务完成后通过飞书群机器人发送通知。

1. 进入设置 > 通知；
2. 开启通知和长任务完成通知；
3. 填写飞书群机器人的 Webhook 地址；
4. 如机器人启用了签名校验，同时填写签名密钥；
5. 设置长任务阈值并保存；
6. 点击测试通知，确认群聊可以正常收到消息。

只有执行时间达到阈值的 Codex 任务才会发送完成通知。

常见问题¶

未检测到 Agent¶

确认 Agent 已安装且至少成功启动一次，然后在 设置 > Agents 点击刷新。Codex 还需要完成账号登录。Linux 当前不支持检测 WorkBuddy Desktop。

Claude Code 没有额度数据¶

打开或重启一次 Claude Code 会话，等待 AgentMeter 收到首个额度响应。部分账号套餐或 Claude Code 版本不提供额度字段，这种情况下 Token 历史仍可使用。

基础采集没有数据¶

确认连接配置已保存、目标 Agent 的基础采集开关已开启，并等待至少一个上报周期。随后点击查看基础采集诊断，检查最近采集时间、上报时间和错误信息。

增强采集没有 Trace¶

确认连接器已安装、目标 Agent 的增强采集开关已开启且验证通过。重启 Agent 后发起一次新任务，再到 Agent 监测查看器中查询。仍无数据时，点击查看诊断信息检查连接器状态。

查看诊断日志¶

AgentMeter 的诊断日志不会记录任务正文、完整 Token、Webhook 或签名密钥。默认日志路径如下：

历史日志使用 .1 至 .4 后缀。提交问题时，建议同时提供 AgentMeter 版本、操作系统、Agent 类型以及脱敏后的诊断日志。

更多阅读¶