核心用法
session-logs 提供了一套基于 JSONL 格式的命令行工具链，用于对本地存储的会话历史进行结构化查询与分析。核心依赖 jq（JSON 处理器）和 rg（ripgrep，高性能文本搜索）。用户可通过路径 ~/.openclaw/agents/<agentId>/sessions/ 定位会话文件，其中 sessions.json 为索引，<session-id>.jsonl 为完整对话记录。
显著优点
1. 结构化查询能力：利用 jq 的筛选语法，可按角色（user/assistant/toolResult）、消息类型（text/thinking/toolCall）、时间戳、成本等维度精确提取信息。
2. 跨会话全文检索：结合 rg 实现关键词在全部历史会话中的快速定位，解决"之前提过什么"的记忆断层问题。
3. 成本与用量审计：内置成本累加、消息计数、Token 统计等聚合查询，便于用量监控与预算管理。
4. 轻量无依赖：仅依赖两个常见命令行工具，无需数据库或复杂运行时。
潜在局限
- 本地文件限制：仅作用于已持久化到本地的 JSONL 文件，若会话未保存或已被清理则无法恢复。
- 技术门槛：需熟悉 jq 语法和 shell 脚本，非技术用户上手成本较高。
- 性能瓶颈：超大会话（数 MB）或高频查询时，反复解析 JSONL 可能带来 I/O 开销，建议结合
head/tail采样。 - 隐私风险：历史日志可能含敏感信息，跨会话搜索时需注意结果脱敏。
适合人群
- 需要追溯多轮对话上下文的高级用户
- 对 API 调用成本敏感、需定期审计的技术团队
- 开发调试 Agent 行为、分析工具调用模式的开发者
常规风险
- 数据泄露：日志文件以明文存储，共享环境需确保目录权限隔离。
- 误操作覆盖：虽为 append-only，但错误的 jq 输出重定向可能意外截断文件。
- 结果误读：jq 查询语法错误可能导致漏报或误报，关键决策应人工复核。