OpenClaw 实战:用 sessions_search + sessions_history 把历史会话翻出来

为什么需要搜历史会话

OpenClaw 跑久了，会话（session）会越积越多——每天凌晨的定时任务、微信里零碎的问答、临时开的后台子任务，全都在。等你某天想找回「上周那个部署脚本到底怎么写的」「三天前排查飞书掉线时用的命令」，靠记忆根本不现实。

直接用 sessions_list 只能看到当前可见会话的列表，而且默认不带历史正文。要真正「按内容搜」和「读回当时的对话细节」，得靠两个工具配合：

• sessions_search
  ：按关键词语义搜索可见的历史会话里出现过的用户/助手文本。

• sessions_history
  ：拿到某个会话的完整历史（含工具调用、消息、pending 输入），按 sessionKey 精读。

下面用真实可操作的步骤讲清楚。

第一步：用 sessions_search 定位目标会话

sessions_search 的入参很简单，核心是 query，可选 limit（默认 25，最小 1）和 sessionKey（限定在某个会话内搜）。

基础用法：全局搜关键词

想找「飞书 WebSocket 掉线」相关的那次排查：

sessions_search({ "query": "飞书 WebSocket 掉线 排查" })

返回的是匹配的历史会话列表，每条带 sessionKey、sessionId、命中的 messageId 附近上下文。你从这里挑出最像的那个 sessionKey。

进阶：限定在某个会话内搜

如果你已经知道大概是哪个会话（比如某个 cron 任务），可以缩小范围，避免噪声：

sessions_search({
  "query": "重启 nginx 命令",
  "sessionKey": "agent:main:cron:xxxx"
})

注意：默认只搜「可见会话」。归档（archived）的会话不会被搜到，要先 sessions_list 确认它在可见范围，或先恢复归档。

第二步：用 sessions_history 读回完整上下文

拿到 sessionKey 后，用 sessions_history 把当时的完整对话拉出来看。

读取最近 N 条

sessions_history({
  "sessionKey": "agent:main:cron:xxxx",
  "limit": 50
})

limit 控制返回的消息条数（从最新往回取）。返回的每条消息里可能包含 tool 消息——也就是当时助手实际调用了什么工具、传了什么参数、拿到什么结果。这对「复刻当时做法」极其关键。

定位到具体那一条

sessions_search 会给你命中的 messageId，把它喂给 sessions_history 的 messageId 参数，可以从那条消息附近往下读：

sessions_history({
  "sessionKey": "agent:main:cron:xxxx",
  "messageId": "msg_abc123"
})

实战组合拳：三步找回那段配置

假设你忘了「9 月某天给 zyker.cn 加 nginx 反代时用的 location 配置」：

1. 搜
   ：sessions_search({ "query": "zyker nginx location 反代" }) → 得到候选 sessionKey。

1. 读
   ：sessions_history({ "sessionKey": "<得到的key>", "limit": 80 }) → 在返回的 tool 消息里找到当时 write/edit 工具写进去的 nginx 配置块。

1. 复刻
   ：把那段配置直接拷出来用，或让助手基于它生成新版本。

和其他会话工具的分工

容易混的几个，一张表分清：

| 工具 | 干什么 | 适合场景 |

|------|--------|----------|

| sessions_list | 列出当前可见会话（侧栏那些） | 想知道「现在有哪些会话」 |

| sessions_search | 按关键词搜历史会话文本 | 记得内容、忘了在哪个会话 |

| sessions_history | 读某个会话的完整历史 | 已锁定会话，要回看细节 |

| sessions_send | 给某个会话发消息并等回复 | 想「续上」那个会话继续干 |

几个踩坑点

• 归档会话搜不到
  ：sessions_search 只覆盖可见会话。会话被归档后，先在 sessions_list 带 archived:true 找到它，必要时恢复，再搜。

• pending 输入不会重放
  ：sessions_history 里的 pendingInputs 是当时没进模型历史的输入，回看时只是参考，不会自动重新执行。

• 消息量大时控制 limit
  ：历史很长的会话别一上来拉全量，先用小 limit（比如 30）定位时间窗口，再逐步扩大。

• sessionKey 优先于 label
  ：列表里看到的是可读的 label，但工具调用要用稳定的 sessionKey，label 可能重复或变化。

小结

记住一句口诀：搜不到内容用 sessions_search，锁定会话用 sessions_history，想续聊才用 sessions_send。 三个工具分工明确，配合起来，OpenClaw 跑再久也不会变成「说过什么自己都找不回」的黑盒。

关注公众号，获取更多 OpenClaw 实操技巧