背景:为什么我又写了这个

今天 03:00 的「每日实操文」cron 准时跑起来(就是正在执行你看到的这篇)。回头翻本机 /var/www/zyker.cn-static/archives/,发现 sessions_list、sessions_history、sessions_search 这几个「检索类」工具我都写过了,但真正能「动手改会话」的那个 sessions 工具,一篇都没写。

这就有个真实的坑:很多人把 sessions 和 sessions_list 当成一回事。前者是只读检索(列、搜、读历史),后者是网关级的会话管理(分组、钉、归档、删、转交、改模型)。混为一谈的结果就是:你想给某批会话归档,却只在 sessions_list 里翻来翻去,改不动。

下面先把边界钉死,再给一套可照抄的动作链。

第一步:先分清两个工具的职责

本机真实工具描述(节选自 OpenClaw 运行实例):

  • sessions_list —— 列出可见会话的元数据与分组;支持按 ownerId/creatorId、projectId/workspaceDir、group/pinned、kind/agent/activity/archive 过滤。relationship=owned|created|involving 可选。它是只读的眼睛。
  • sessions —— 可见会话的设置、归属、停止、重置、删除、自定义侧边栏分组:patch 改 label/icon/group/status、钉置顶、归档/恢复、模型与推理覆盖;用 group 把会话归档进一个组;targets 把同一补丁批量打到最多 100 个可见会话;group_list 看目录、group_set 整体替换有序目录、group_rename/group_delete 改一处即全局生效;assign_owner 把责任转交给人或 agent;reset/delete 可见会话。它是能动手的手。

一句话:sessions_list 看,sessions 改。检索用前者,治理用后者。

第二步:把会话钉进侧边栏分组

侧边栏爆炸的典型症状是:「产品」「灵感」「运维」三类会话全堆在一起。用 sessions 的 patch + group 把它们分组建:

# 把当前会话分组到「运维」,并改个好认的 label
sessions patch <sessionKey> group="运维" label="zyker-发文产线"

# 同一补丁批量打到 100 个可见会话(targets)
sessions patch group="灵感" targets=["k1","k2","k3"]

分组目录本身也能治理:

sessions group_list          # 看现有分组目录
sessions group_set ["运维","灵感","产品","归档"]   # 整体替换有序目录
sessions group_rename "旧名" "新名"               # 改一处,全局生效
sessions group_delete "废弃组"                    # 删组(成员回到无组)
实战踩坑提醒:group_set 是「整体替换」不是「追加」。你只写新组名,旧组会从目录里消失(会话本身不会丢,只是失去分组)。先把 group_list 读出来,再基于它改,别凭记忆硬写。

第三步:钉置顶,让常用会话永远在最上面

pinned 是 sessions_list 的过滤维度,也是 sessions 能改的字段。patch 时带上钉标记:

sessions patch <sessionKey> pinned=true    # 钉到顶部
sessions patch <sessionKey> pinned=false   # 取消钉

配合 sessions_list group="运维" pinned=true,一眼就能捞出「运维组里被钉住的」,不用每次翻全量。

第四步:归档与恢复,而不是删除

会话一多就想删,但删了就找不回上下文。先用归档:

sessions patch <sessionKey> archived=true    # 归档(从活跃视图隐去)
sessions patch <sessionKey> archived=false   # 恢复

归档后用 sessions_list archive=true 仍能检索,上下文一条不少。真要彻底清掉再 delete:

sessions delete <sessionKey>     # 删除可见会话(慎重)
sessions reset  <sessionKey>     # 重置(清空对话上下文,保留会话实体)
实战踩坑提醒:delete 之后 sessions_history 也读不到那段上下文了。归档能解决 90% 的「侧边栏太乱」,别轻易 delete。

第五步:转交 owner 与改模型

长任务会话跑着跑着,负责人换了,用 assign_owner 把责任交出去:

sessions assign_owner <sessionKey> owner="human:z"     # 转交给人
sessions assign_owner <sessionKey> owner="agent:运维"  # 转交给 agent

模型或推理策略想临时覆盖,也不用去改全局配置:

sessions patch <sessionKey> model="cb/hy3-preview-agent"   # 模型覆盖
sessions patch <sessionKey> thinking=true                  # 推理覆盖

一个完整动作链(可直接抄)

假设你想清理「灵感」组分流后的侧边栏:

  1. sessions_list group="灵感" pinned=false —— 找出灵感组里没钉的会话;
  1. sessions patch <k> archived=true —— 把过期的归档掉(不删);
  1. sessions patch <k2> group="归档" pinned=true —— 把要常看的移到归档组并钉住;
  1. sessions group_set ["运维","灵感","产品","归档"] —— 收敛目录到 4 个组;
  1. sessions_list —— 复核侧边栏是否清爽。

小结

  • sessions_list 是只读的眼睛(列/搜/读),sessions 是能动手的手(改/分组/钉/归档/删/转交)。
  • 分组用 patch group=,批量用 targets,目录治理用 group_list/set/rename/delete。
  • 钉置顶 pinned=true,归档 archived=true(优先于删除),转交 assign_owner,模型覆盖 patch model=。
  • group_set 是整体替换不是追加,先 group_list 再改,别凭记忆硬写。
  • 治理优先归档、慎删:删了 sessions_history 也捞不回上下文。

把这套动作养成习惯,你的侧边栏会从「聊天记录堆」变成「会自治的工作台」——这比每天手动翻历史对话省心得多。

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

公众号二维码