夜雨聆风Agent 不等于 Session
理解 OpenClaw 的 Session 系统，要先搞清楚一个容易混淆的概念区分：Agent 和 Session 是两件不同的事。
Agent 是配置层面的存在——它定义了用哪个模型、工作目录在哪里、有哪些工具权限、人格是什么样的。它存在于 openclaw.json 里，是静态的。
Session 是状态层面的存在——它持有一段具体对话的完整历史、当前的上下文、模型临时覆盖设置。它存在于磁盘上的 JSONL 文件里，随着每条消息的到来不断增长。
一个 Agent 可以同时拥有几十个 Session：一个来自 Telegram 私信的 Session，五个来自不同 Discord 群组的 Session，十几个定时任务各自独立的 Session，以及若干子 Agent Session。每个 Session 互不干扰，就像同一个人在处理不同的项目，各个项目有各自的文件夹。
这个设计的核心价值是隔离。你在 Discord 群里讨论的内容，不会泄漏到 Telegram 私信的对话上下文里。定时任务看不到你的私聊内容。子 Agent 只能看到自己被授权访问的 Session。这些隔离边界不是靠君子协定维持的，而是靠 SessionKey 的结构硬编码进去的。
SessionKey：冒号分隔的路由地址
每个 Session 有一个唯一标识符，叫 SessionKey。它是一个冒号分隔的字符串，编码了这个 Session 的完整路由上下文。只要看一眼 SessionKey，你就知道它属于哪个 Agent、来自哪个通道、是什么类型的对话。
私信 Session 的结构是 agent:<agentId>:<mainKey>，比如 agent:main:main。这是最常见的形式，代表"默认 Agent 的主会话"。多个平台的私信默认都折叠到同一个主 Session 里——无论你从 Telegram 还是 WhatsApp 发消息，只要都指向同一个 Agent，对话历史是共享连续的，Agent 记得你上次在哪个平台说过什么。
群组和频道的 Session 有自己独立的键，结构包含通道标识和对等方 ID，比如 Discord 的一个服务器频道对应的键形如 agent:main:discord:default:group:<serverId>:<channelId>。不同群组的 Session 天然隔离，不会串台。
定时任务 Session 的键以 cron: 为前缀，每次运行都铸造一个全新的 sessionId，永远不复用旧的对话历史。这是故意的设计——定时任务应该每次都从干净的状态出发，不应该被上一次运行的残留上下文干扰。
子 Agent Session 的键包含父 Session 的信息，形如 agent:main:subagent:<uuid>，明确记录了它的亲缘关系。
这种"键即路由"的设计有一个深刻的工程优雅之处：系统里没有独立的路由表，Session 的所有路由信息都内嵌在键的结构里。当一条消息到来，resolveSessionKey() 函数解析路由上下文，直接得出目标 SessionKey，不需要查询任何外部状态。
dmScope：控制私信的折叠方式
默认情况下，所有来自不同平台的私信都折叠到同一个主 Session，这对单人使用场景非常方便——你在 Telegram 说的话，在 WhatsApp 里继续，Agent 完整记得。
但有些场景需要更细粒度的隔离，比如你的 Agent 同时服务多个用户（家庭成员、团队同事），这时不同人的私信绝对不能共享上下文。session.dmScope 配置项控制这个行为，支持四种模式。
main 是默认模式，所有私信折叠到主 Session。适合单人使用。
per-peer 按发送者隔离，每个人有自己独立的 Session。适合服务多个已知用户的场景。
per-channel-peer 按通道加发送者隔离，同一个人在不同平台上的私信也是独立的。适合你希望 Telegram 和 WhatsApp 的对话完全分开的场景。
per-account-channel-peer 是最细粒度的模式，按账号加通道加发送者三重隔离。适合配置了多个平台账号（比如两个 Telegram Bot）的共享收件箱场景，确保每个账号收到的消息都完全独立。
identityLinks：跨平台的统一身份
per-peer 和 per-channel-peer 模式带来了一个新问题：同一个真实的人，在 Telegram 里有一个 ID，在 Discord 里有另一个 ID，默认情况下会被识别为两个不同的对话者，各自有独立的 Session。
session.identityLinks 解决了这个问题。你可以在配置里声明：
{session: {identityLinks: {alice: ["telegram:123456789", "discord:987654321012345678"],}}}
这告诉系统：这两个平台 ID 背后是同一个人，叫 alice。之后 alice 无论从 Telegram 还是 Discord 发消息，resolveSessionKey() 都会把她的 ID 替换成 alice 这个规范化身份，两个平台共享同一个 Session 和完整的对话历史。
SessionStore：注册表与元数据
所有活跃 Session 的元数据集中存在一个 JSON 文件里：
~/.openclaw/agents/<agentId>/sessions/sessions.json这个文件是 SessionKey 到 SessionEntry 的映射，每个 Entry 包含：sessionId（UUID，用于定位 JSONL 文件）、updatedAt（最后活跃时间）、totalTokens（累计 Token 用量）、model（当前会话使用的模型）、deliveryContext（回复投递的路由信息）、以及 origin（来源元数据：标签、通道 ID、发送方/接收方原始 ID）。
群组 Session 的 Entry 还包含 displayName、channel、subject、room、space 等字段，让 Web UI 和 TUI 能以有意义的名字展示每个 Session，而不是一堆机器 ID。
SessionStore 的所有写操作都通过 updateSessionStore() 函数处理，内部用 Promise 链实现了一个互斥锁，防止并发写入时产生竞争条件。任何删除 sessions.json 里某个键的操作都是安全的——下一条消息到来时，Session 会被自动重建，只是对话历史从空白重新开始。
JSONL Transcript：对话的真正容器
每个 Session 的完整对话历史存在一个独立的 JSONL 文件里：
~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonlTelegram topic（话题群）的 Session 使用稍微不同的命名格式：
~/.openclaw/agents/<agentId>/sessions/<sessionId>-topic-<threadId>.jsonlJSONL（JSON Lines）格式是每行一个独立的 JSON 对象。文件以一个 header 行开头，记录 Session 的元数据：
{"type":"session","version":1,"id":"abc-def-123","timestamp":"2026-01-28T10:00:00.000Z","cwd":"/home/user/.openclaw/workspace"}之后每一行是一条消息记录：用户输入、模型回复、工具调用、工具执行结果，按时间顺序排列。特别值得注意的是，当 Agent 把回复发送出去时，还会额外追加一条"投递镜像"记录，内容是实际发送给用户的文字。这意味着 JSONL 不只是"模型生成了什么"的记录，而是"模型生成了什么、用户实际收到了什么"的完整双轨记录。
JSONL 格式有三个工程上的优点：追加写入高效，不需要读取和重写整个文件；崩溃时已写入的行不会丢失；用 cat 和 jq 就能直接检查内容，完全透明可调试。
写锁：防止并发写入的竞争
一个常驻后台的 AI 助手很容易遭遇这个场景：你在 Telegram 发了一条消息，Agent 正在处理；与此同时一个定时任务触发了，也要往同一个 Session 写入内容；甚至你在处理过程中又发了一条追问。
如果没有并发保护，多个执行流同时追加 JSONL 文件，会产生交错的内容，导致对话历史乱序，下一次 Agent 读取历史时会看到一堆混乱的输入。
写锁机制解决了这个问题，实现在 src/agents/pi-embedded-runner/run/attempt.ts 里。每个 Session 在执行开始时获取一个文件级别的写锁，执行结束时释放。锁的最大持有时间通过 resolveSessionLockMaxHoldFromTimeout() 从当前运行的超时配置里推算，防止死锁——如果一个执行因为某种原因卡住，锁会在超时后自动释放，不会永久阻塞这个 Session。
等待写锁的请求会在队列里排队，按顺序依次执行，不会丢弃。这意味着你快速发送多条连续消息，Agent 会按顺序逐条处理，每条都完整地看到前面所有消息的上下文。
Session 的自动重置
对话历史会随时间不断增长，上下文窗口是有限的。OpenClaw 提供了一套自动重置机制，通过 session.reset 配置项控制，支持两种触发方式。
daily 模式在每天固定时刻重置 Session，默认是凌晨 4 点（以 Gateway 所在机器的本地时间为准）。新的一天开始，上下文从干净的状态出发，防止历史记录无限堆积。
idle 模式在 Session 空闲超过指定分钟数后重置，比如 idleMinutes: 120 表示两小时无消息则重置。适合"一次短暂的帮助对话，结束后不需要保留上下文"的场景。
两种模式可以同时配置，谁先触发谁生效。还可以按 Session 类型分别设置不同的策略：
{session: {resetByType: {thread: { mode: "daily", atHour: 4 },dm: { mode: "idle", idleMinutes: 240 },group: { mode: "idle", idleMinutes: 120 },},resetByChannel: {discord: { mode: "idle", idleMinutes: 10080 }, // Discord 群组保留一周},}}
重置只是开始一个新的 sessionId，旧的 JSONL 文件不会被删除，仍然保存在磁盘上可以随时查阅。如果重置时记忆系统开启，Agent 会在重置前自动把重要内容写入长期记忆，保证跨 Session 的连续性。
用户也可以随时发送 /new 或 /reset 命令主动重置当前 Session。/new <模型名> 还支持在重置的同时切换当前 Session 使用的模型，比如 /new claude-opus 表示开始一段新对话，并把这段对话的模型切换到 Opus。
回复投递策略：sendPolicy
Session 管理的最后一个重要机制是 sendPolicy——控制哪些 Session 类型的回复可以被投递出去。
这听起来有点奇怪：为什么要阻止回复被发送？实际场景里有几种情况需要这个控制。有时候你在测试一个新的工作流，不希望测试消息真的发到 Discord 群里；有时候定时任务的输出只需要记录在日志里，不需要推送到消息平台；有时候你在多账号配置里，需要限制某个账号只响应私信，不响应群组消息。
sendPolicy 通过规则列表实现，支持 allow 和 deny 两种动作，匹配条件包括通道名（channel）、对话类型（chatType）、Session 键前缀（keyPrefix）、原始 Session 键前缀（rawKeyPrefix），没有命中任何规则的请求遵循 default 字段的默认行为：
{session: {sendPolicy: {rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } },{ action: "deny", match: { keyPrefix: "cron:" } },],default: "allow",}}}
这个配置的效果是：所有 Discord 群组消息的回复被静默丢弃，所有定时任务的输出不被投递，其他所有 Session 正常投递。
存储维护：防止无限增长
一个高流量的 OpenClaw 部署很快会积累大量 Session 文件。session.maintenance 配置提供了自动清理机制：在每次 Session 写入时顺带触发维护检查，也可以手动运行 openclaw sessions cleanup。
维护逻辑支持两个维度的清理：按 Session 数量上限（maxSessions）清理最旧的 Session，以及按磁盘占用上限（maxDiskBytes）优先清理最大的 JSONL 文件。mode: "warn" 模式只报告会被清理的内容而不真正删除，适合先检查再决策。
小结
OpenClaw 的 Session 系统是整个对话框架的地基。SessionKey 的层次结构把路由信息编码进标识符本身，消除了独立路由表；JSONL 格式让对话历史可追加、可检查、崩溃安全；写锁机制保证了多并发场景下的数据一致性；dmScope 和 identityLinks 提供了从单人到多人的灵活身份管理；自动重置和存储维护让系统能长期健康运行。
下一篇，我们进入整个系统最核心的部分：Agent 运行时。PiEmbeddedRunner 是怎么把一条消息变成一次完整 AI 执行的？
源码参考：src/config/sessions/store.ts · src/config/sessions/reset.ts · src/agents/pi-embedded-runner/run/attempt.ts · src/agents/agent-scope.ts · docs/concepts/session.md基于 commit bf6ec64f 版本
