Byted Openclaw Diag

OpenClaw 诊断工具

指令模式

当用户发送 /diag 指令时，直接执行脚本，不做额外解释：

规则： 1. 无参数时默认 -s（摘要模式，最简洁） 2. full 关键词 → 去掉 -s，输出含 Run 详情 3. errors 关键词 → 执行完整报告，只摘出错误列表 4. -a、-l、日期参数直接透传给脚本 5. 去除 ANSI 颜色码：管道 | sed 's/\x1b\[[0-9;]*m//g' 6. 不支持 -f（实时跟踪），该模式需在 SSH 终端运行 7. 直出模式：脚本输出直接用 message 工具原样发送给用户，不经过模型总结。 具体做法：

• 执行脚本，将 stdout 存入变量
• 用 message(action="send", message=output) 发送原始输出
• 然后回复 NO_REPLY（避免重复发送）
• 如果输出超过 4000 字符，按 4000 字符分段发送（Telegram 消息长度限制）
• 每段用 ``` 代码块包裹，保持等宽字体排版

自然语言模式

当用户用自然语言询问（如"运行状态怎么样"、"waicode今天干了啥"）时， 自行选择合适参数执行脚本，并用中文汇总关键信息。

快速使用

# 诊断今天的数据
bash scripts/byted-openclaw-diag.sh

# 诊断指定日期
bash scripts/byted-openclaw-diag.sh 2026-03-19

# 只看摘要
bash scripts/byted-openclaw-diag.sh -s

# 实时跟踪（类似 tail -f）
bash scripts/byted-openclaw-diag.sh -f

# 高级实时跟踪（自动开启 debug 日志，退出时恢复）
bash scripts/byted-openclaw-diag.sh -f --advanced

# 只看指定 agent
bash scripts/byted-openclaw-diag.sh -a waicode

# 最近 5 个 Run
bash scripts/byted-openclaw-diag.sh -l 5

模式说明

参数可组合：-s -a main、-l 3 -a wairesearch。

实时跟踪（-f）和高级模式（--advanced）需在 SSH 终端运行，

详见 references/advanced-mode.md。

数据源

脚本有两种数据源，自动切换：

无 debug 日志时自动降级为 session 模式，核心指标（推理耗时、Token、工具统计）仍然准确。

输出内容

摘要统计

• 模型调用次数、平均推理延迟、Token 吞吐量
• 工具调用次数、成功率、总耗时
• Thinking 统计（次数、平均深度）
• Per-Agent 活动分布

Run 详情（非摘要模式）

• 每个 Run 的时间线（推理段 + 工具调用段）
• 推理耗时、输出 Token、吞吐速率
• 工具调用参数摘要

错误列表

• 最近 20 条错误，按时间倒序

使用指南

日常检查

# 快速了解今天的运行概况
bash scripts/byted-openclaw-diag.sh -s

性能排查

# 查看某天详细 Run 数据，找到慢查询
bash scripts/byted-openclaw-diag.sh 2026-03-19 -l 10

特定 Agent 分析

# 只看 waicode 的活动
bash scripts/byted-openclaw-diag.sh -a waicode -s

实时监控（SSH 终端）

# 需在 SSH 终端运行，不适合 Telegram/聊天
bash scripts/byted-openclaw-diag.sh -f
bash scripts/byted-openclaw-diag.sh -f --advanced

注意事项

• 脚本依赖 python3（3.7+，使用 datetime.fromisoformat）和 bash
• 高级模式（--advanced）会临时修改 openclaw.json 并重启 Gateway，退出时自动恢复
• 无 Swap 的机器上并发多 Agent 时注意内存
• 时间戳统一为 UTC 处理，不受本地时区影响

高级模式参考

高级模式工作原理

--advanced 仅在实时跟踪模式 (-f) 下生效：

1. 检查 openclaw.json 中 diagnostics.enabled 和 logLevel 配置 2. 如果未开启，备份配置文件，修改为 diagnostics.enabled: true + logLevel: debug 3. 自动重启 Gateway（等待最多 60 秒） 4. 开始实时跟踪 5. Ctrl+C 退出时提示是否恢复原配置

配置项

手动开启（不用 --advanced）

openclaw config set diagnostics.enabled true
openclaw config set logLevel debug
openclaw gateway restart

Session 文件结构

路径：~/.openclaw/agents/{agent}/sessions/{id}.jsonl

每行一个 JSON 对象，关键字段：

• role: user / assistant / toolCall / toolResult / custom_message
• timestamp: ISO 8601 UTC
• model: 模型名称
• usage: {input, output, cacheRead, cacheWrite, totalTokens}
• toolResult.details: {exitCode, durationMs, stdout, stderr}

虚拟 Run 构造算法

当无 debug 日志时： 1. 扫描所有 agent 的 session 文件（含 .reset. 和 .deleted.） 2. 按日期过滤消息（UTC ±1 天容错） 3. 每条 user 消息标记为 Run 起点 4. 到下一条 user 消息或文件末尾为 Run 终点 5. 聚合 Run 内的 assistant/toolCall/toolResult 统计

多 Agent 支持

脚本扫描 ~/.openclaw/agents/*/sessions/ 下所有 agent。

-a <name> 过滤逻辑：

• 批量模式：通过 session 文件路径提取 agent 名称，过滤 Run
• 实时跟踪：从日志中 sessionKey=agent:{name}:{id} 提取 agent，过滤事件