可观测性

wesclaw 提供丰富的可观测性功能，帮助你了解 AI 的使用情况、Token 消耗、运行状态和问题诊断。

概述

wesclaw 的可观测性覆盖以下维度：

Token 用量查询

基本用量

在 设置 → 用量统计 中可以查看 Token 用量概览：

• 总输入 Token 数
• 总输出 Token 数
• 按模型分组的用量
• 按日期的用量趋势

用量统计维度

Token 用量支持多维度查询和聚合：

查看详细用量

记忆中心的"Token 统计"页签提供更详细的分析：

按日期筛选

支持按时间范围筛选用量数据：

• 今天 — 查看当日用量
• 本周 — 查看本周汇总
• 本月 — 查看当月汇总
• 自定义范围 — 选择起止日期

费用估算

如果使用按量付费的 Provider，Token 用量可以帮助估算费用：

估算费用 ≈ 输入 Token × 输入单价 + 输出 Token × 输出单价

注意：实际费用以 Provider 账单为准。缓存命中的 Token 通常享受折扣。

Run 追踪

查看 Run 列表

在 记忆中心 → 运行日志 中查看所有 Run 的执行记录：

Run 详情

点击某个 Run 可以查看详细信息：

基本信息

• Run ID
• 开始和结束时间
• 终止原因（end_turn / interrupted / cycle_detected 等）
• 总 Token 用量

工具调用追踪

每个 Run 中的工具调用都有详细记录：

[1] web_search("天气预报") → 200ms
    输入: {"query": "北京今天天气"}
    输出: "晴，25°C，东风3级"

[2] read_file("notes.md") → 15ms
    输入: {"path": "/notes.md"}
    输出: "# 今日待办..."

[3] edit_file("notes.md") → 20ms
    输入: {"path": "/notes.md", "content": "..."}
    输出: "文件已保存"

Turn 追踪

Run 中每一轮 LLM 调用的详细信息：

Run 筛选

支持按以下条件筛选 Run：

• Agent — 按 AI 角色筛选
• 会话 — 按对话筛选
• 状态 — 成功 / 失败 / 中断
• 日期范围 — 按时间筛选
• 时长 — 按执行时长排序

会话统计

基本统计

Cell 运行时统计

通过 设置 → 关于 查看 Cell 运行时状态：

崩溃日志

崩溃日志位置

引擎崩溃时的堆栈信息保存在数据目录下：

崩溃日志内容

崩溃日志包含：

• 崩溃时间
• 引擎版本
• Go 运行时堆栈信息
• 最近的操作上下文

引擎 stderr 日志

引擎将 fd 2 重定向到文件，用于捕获 Go runtime 的 panic 信息：

$DATA_DIR/logs/wesgine-stderr.log

这是排查引擎崩溃的第一个应该查看的文件。Go 的 panic 栈直接写 fd 2，不经过标准日志系统。

查看崩溃日志

# macOS
ls -la ~/Library/Application\ Support/wesclaw/crashes/
cat ~/Library/Application\ Support/wesclaw/crashes/最新的崩溃文件

# 查看引擎 stderr
cat ~/Library/Application\ Support/wesclaw/logs/wesgine-stderr.log

证据链（Evidence）

wesclaw 支持审计证据链功能，记录 AI 操作的完整轨迹：

什么是证据链

证据链是一系列带有哈希关联的事件记录，确保操作历史不可篡改。每个事件包含：

• 事件类型（工具调用、LLM 请求、决策等）
• 时间戳
• 输入和输出
• 前一个事件的哈希

查看证据链

证据链数据可以通过 API 导出：

GET /cells/{cellID}/observe/evidence

返回 JSONL 格式的事件流。

证据链功能主要用于合规审计场景。普通用户通常不需要直接查看。

监控建议

日常关注

性能基线

建议记录以下基线数据，便于对比分析：

• 每日平均 Token 消耗
• 每次 Run 的平均时长
• 每次 Run 的平均工具调用次数
• 每日 Run 成功率

异常告警

注意以下异常信号：

• Token 用量突然增加 → 可能存在循环或冗余调用
• Run 成功率下降 → 可能 Provider 不稳定
• Run 时长增加 → 可能上下文过长或网络变慢

SaaS 版差异

SaaS 云端版本的可观测性：

• Token 用量通过 WES 平台统一计费和展示
• Run 追踪功能相同
• 崩溃日志由运维团队管理，用户无需关注
• 额外提供跨设备的用量聚合视图

下一步

• 故障排查 — 根据观测数据排查问题
• Cell 管理 — 了解 Cell 运行时状态
• 数据备份与恢复 — 日志和数据的备份方法