session-logs¶

Skill 简介¶

OpenClaw Skill 中的 session-logs 是一个用于搜索和分析用户对话历史记录的工具，它利用 jq 命令行工具来解析和处理存储在 JSONL 文件中的对话数据。这个 Skill 的设计初衷是为了帮助开发者更好地管理和利用用户的会话历史，无论是查找过去的对话内容，还是分析会话中的关键信息，session-logs 都能提供强大的支持。

在实际的开发过程中，我们常常需要回顾用户的历史交互内容，以便更好地理解用户需求、提供更精准的服务或进行数据挖掘。然而，随着对话数据的不断积累，手动查找和分析这些数据变得越来越困难。session-logs 通过提供一系列便捷的命令和查询方式，帮助开发者高效地访问和分析会话日志，从而提升开发效率和用户体验。

主要功能¶

session-logs 提供了多种核心功能，以下是其中几个关键功能的详细说明：

1. 会话列表与筛选
   功能描述：开发者可以通过简单的命令行操作，列出所有的会话记录，并根据日期或文件大小进行排序和筛选。例如，使用以下命令可以按日期降序排列所有会话，并显示每个会话的文件大小：
   bash for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl; do date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1) size=$(ls -lh "$f" | awk '{print $5}') echo "$date $size $(basename $f)" done | sort -r

2. 特定日期会话查找
   功能描述：如果需要查找特定日期的会话记录，可以使用如下命令。该命令会遍历所有会话文件，筛选出包含指定日期的会话：
   bash for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl; do head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f" done

3. 用户消息提取
   功能描述：要从某个会话中提取用户的所有消息，可以使用以下命令。这个命令会过滤出所有角色为“user”的消息内容：
   bash jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl

4. 关键词搜索
   功能描述：如果需要在某个会话的助手回复中搜索特定的关键词，可以使用 rg（Ripgrep）工具。例如，以下命令会搜索所有助手回复中包含“keyword”的文本：
   bash jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl | rg -i "keyword"

5. 成本统计
   功能描述：开发者可以统计某个会话的总成本或每日成本汇总。例如，以下命令会计算某个会话的总成本：
   bash jq -s '[.[] | .message.usage.cost.total // 0] | add' <session>.jsonl
   而以下命令则可以生成每日成本汇总：
   bash for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl; do date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1) cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f") echo "$date $cost" done | awk '{a[$1]+=$2} END {for(d in a) print d, "$"a[d]}' | sort -r

6. 消息与令牌计数
   功能描述：通过以下命令，开发者可以统计某个会话中的消息数量、用户消息数量、助手消息数量，以及会话的开始和结束时间：
   bash jq -s '{ messages: length, user: [.[] | select(.message.role == "user")] | length, assistant: [.[] | select(.message.role == "assistant")] | length, first: .[0].timestamp, last: .[-1].timestamp }' <session>.jsonl

使用场景¶

1. 用户行为分析：通过分析用户的历史对话，开发者可以了解用户的使用习惯、偏好和需求，从而优化产品功能和服务。
2. 问题诊断与调试：当用户遇到问题时，开发者可以通过搜索会话日志，快速定位问题的根源，并提供有效的解决方案。
3. 性能优化：通过统计会话中的成本数据，开发者可以评估不同功能的资源消耗，进而进行性能优化。
4. 数据挖掘与机器学习：会话日志中包含大量有价值的数据，开发者可以利用这些数据进行数据挖掘和机器学习训练，提升模型的准确性和智能化水平。
5. 合规与审计：在某些行业中，需要对用户数据进行合规审查和审计，session-logs 可以提供便捷的访问和分析工具，满足合规要求。

如何使用¶

安装与配置¶

1. 安装必要的工具：
   确保系统中已安装 jq 和 rg（Ripgrep）工具。如果未安装，可以使用以下命令进行安装：
   ```bash
   # For Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install jq ripgrep

# For macOS (using Homebrew)
brew install jq ripgrep
```

1. 配置 OpenClaw Agent：
   根据 OpenClaw 的文档，配置好你的 Agent，并确保会话日志存储在 ~/.openclaw/agents/<agentId>/sessions/ 目录下。

前置条件¶

• 熟悉基本的命令行操作
• 了解 JSON 和 JSONL 格式
• 对 jq 和 rg 工具有一定了解

示例¶

示例 1：提取用户消息并搜索关键词¶

假设你想从某个会话中提取所有用户消息，并搜索包含“天气”的文本，可以使用以下命令：

jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl | rg '天气'

示例 2：统计每日成本¶

以下命令会生成一个每日成本汇总的列表：

for f in ~/.openclaw/agents/<agentId>/sessions/*.jsonl; do
  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
  cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f")
  echo "$date $cost"
done | awk '{a[$1]+=$2} END {for(d in a) print d, "$"a[d]}' | sort -r

总结¶

session-logs 是一个功能强大且灵活的工具，专为开发者设计，帮助他们高效地管理和分析用户会话历史。通过提供多种便捷的命令和查询方式，session-logs 可以显著提升开发效率，节省时间成本。无论是进行用户行为分析、问题诊断，还是数据挖掘和性能优化，session-logs 都能为开发者提供强有力的支持。对于那些需要深入了解用户需求、优化产品功能或进行数据驱动的开发者来说，session-logs 是一个不可或缺的工具。