08 · Session 与心跳——时间的维度

——翔宇

要点速览

• Session（会话）有生命周期——默认凌晨 4 点重置，空闲超时也会重置
• 会话重置不删记忆——只是「换一张白纸」，笔记本还在
• 心跳让 Agent 从「被动接线员」升级为「主动巡检员」
• Cron（定时任务）三种模式：at（一次性）/ every（固定间隔）/ cron（表达式）
• 主会话模式 vs 隔离模式：在你耳边说话 vs 去会议室干完活发消息

1. 一个好问题

你的 Agent 下午 3 点到明天早上 7 点都没人找它。

这 16 个小时，它在干嘛？

错误直觉

「等着呗。没人说话就没事做。」

如果只是等着，那 Agent 和 ChatGPT 有什么区别？ChatGPT 也是「有人问才答」。

OpenClaw 的 Agent 不只是等着——它有心跳（Heartbeat，周期性存活检测），会定期自动醒来巡检；它有 Cron 定时任务，会按时间表执行预设工作。

这就是「时间维度」——Agent 不只是空间上存在（有 Workspace（工作区），有记忆），还在时间上主动行动。

2. Session 生命周期：为什么需要「重启」

2.1 对话不能永远持续

前面讲过，上下文窗口是有限的。如果一个 Session 永远不重置，对话历史会无限增长，最终触发压缩。频繁压缩（Compaction，上下文有损压缩） = 频繁丢信息。

🧠 底层逻辑

定期重置 Session 是「主动瘦身」——不等上下文爆满才被动压缩，而是每天清空一次，从头开始。重要信息已经存进了记忆文件，不怕丢。

2.2 三种重置方式

为什么默认凌晨 4 点？

💬 说人话

大部分人凌晨 4 点在睡觉。选这个时间重置，用户感知最小——早上醒来就是一个「干净」的 Agent，但记忆还在。

2.3 idle timeout 的权衡

📌 记住这点

会话重置不删除 Memory。重置只是「换一张白纸开始工作」——笔记本（memory/ 和 MEMORY.md）还在。Agent 重启后会从记忆加载历史信息。

2.4 反事实：如果没有 daily reset

想象一个 Agent 连续运行 30 天不重置：

• 第 1 天：对话历史 5,000 token（词元，AI 的计量单位），一切正常
• 第 7 天：对话历史 80,000 token，开始触发压缩
• 第 14 天：压缩过多次了，早期的决策细节全丢了
• 第 30 天：Agent 的行为和第 1 天完全不同——它的上下文里全是压缩摘要的摘要 daily reset 阻止了这种退化。每天重新加载 SOUL.md + 最近记忆，Agent 的行为保持一致。

2.5 Session Key 映射详解

Session 的底层是一个 key——谁在哪说话，就映射到哪个 Session。

格式长这样：

agent:<agentId>:<mainKey>

比如 agent:ceo:main，代表 CEO Agent 的主会话。

🧠 底层逻辑

为什么需要 Session Key？因为一个 Agent 可能同时和很多人、在很多渠道对话。Key 决定了「谁和谁共享同一段对话历史」。

关键问题来了：不同人找同一个 Agent，应该共享对话还是隔离对话？

这取决于 dmScope（私信会话范围）的设置。OpenClaw 提供四种模式：

用公司来理解：

• main 模式像一个 CEO 只有一个秘书，所有人的要求都记在同一本笔记本上。CEO 随时能看到全貌——但隐私？不存在
• per-peer 模式像客服中心，每个客户有自己的工单。张三的投诉和李四的咨询互不干扰
• per-channel-peer 模式像大型企业的分区客服——你打电话投诉是一个工单，你发邮件咨询是另一个工单，即使是同一个人
• per-account-channel-peer 模式像跨国集团——不同国家的子公司（账号）、不同部门（渠道）、不同客户，全部三维隔离

2.6 反直觉：main 模式的隐私陷阱

⚠️ 注意

默认 main 模式下，不同用户的私聊消息不隔离。如果你让多个人都能私信你的 Agent，A 说的话会出现在 B 的上下文里。

举个场景：

1. 用户 A 给 Agent 私信：「帮我查一下我的考试成绩」
2. Agent 在 main session 里处理了这条消息
3. 用户 B 给 Agent 私信：「你今天都干了什么？」
4. Agent 会回答：「我帮一个人查了考试成绩，然后……」 A 的隐私就这么泄露了。

💡 划重点

如果你的 Agent 面向多个用户提供服务——哪怕只有两个人——必须切到 per-peer 模式。main 模式只适合「只有你一个人用」的私人 Agent。

2.7 跨渠道身份关联

一个更高级的场景：同一个人用 Telegram 和 Discord 都联系了你的 Agent。

• 在 per-channel-peer 模式下，这是两个独立 Session——Telegram 的对话和 Discord 的对话各走各的
• 在 per-peer 模式下，如果 OpenClaw 能识别出两个账号属于同一个人（通过 peerId 映射），它们共享同一个 Session

🎯 打个比方

per-channel-peer 像你在淘宝和京东分别注册了账号——两边的购物车完全独立。per-peer 像你用同一个手机号注册了两个平台——系统知道你是同一个人，购物偏好互通。

什么时候需要跨渠道共享？

• 你的私人 Agent 同时接入了 Telegram 和 Discord，你希望「不管从哪个平台找它，它都记得之前说过什么」

• 用 per-peer 模式 + 统一的用户 ID 映射即可实现 什么时候需要跨渠道隔离？

• 你的 Agent 在 Telegram 是客服角色，在 Discord 是社群管理角色——同一个人在两个平台的对话场景完全不同

• 用 per-channel-peer 模式保证各渠道独立

3. 心跳机制：从等待到巡检

3.1 什么是心跳

Heartbeat 让 Agent 每隔一段时间自动醒来，按 HEARTBEAT.md 里的清单执行检查。

🎯 打个比方

没有心跳的 Agent 像坐在桌前等电话的接线员——有人打才动。有心跳的 Agent 像巡逻的保安——每隔一小时主动查看一轮，有没有异常、有没有待办到期、有没有新消息没处理。

3.2 HEARTBEAT.md 清单

一个典型的心跳清单：

3.3 反事实：如果没有心跳

🔑 关键点

心跳是 Agent 从「工具」变成「员工」的关键——工具等你用，员工会主动干活。

3.4 心跳的完整工作流程

心跳不是「发个信号证明活着」——那是服务器的心跳。OpenClaw 的心跳是一次完整的 LLM（大语言模型） 调用，Agent 会真正「思考」。

完整流程：

定时器触发（每 55 分钟）
  ↓
Gateway 给 Agent 发送 [heartbeat] 事件
  ↓
Agent 加载 HEARTBEAT.md 清单

  ↓
逐项执行检查：
  - 读 inbox/ 有没有新任务文件
  - 查待办有没有到期项
  - 检查系统状态（API 可用？服务正常？）
  - 扫描最近日志，提炼到 MEMORY.md
  ↓
把结果写入日志（logs/ 目录）
  ↓
如果发现异常 → 主动通知用户
如果一切正常 → 静默结束，不打扰

🎯 打个比方

想象一个保安每小时巡逻一次。他不是走一圈就完了——他带着一张检查表：消防栓水压正常吗？门锁好了吗？监控在录吗？全部打勾后签字归档。发现异常才打电话给你。

关键细节：心跳期间 Agent 有完整的思考能力。 它不是执行一个脚本，而是用 LLM 理解当前状态、判断是否需要行动。这意味着心跳可以做相当复杂的事——比如「检查待办列表，如果有任务 deadline 在两小时内，给用户发 Telegram 提醒」。

3.5 心跳成本计算

心跳不是免费的。每次心跳 = 一次 LLM 调用 = 消耗 token = 花钱。

💡 划重点

在决定心跳频率之前，先算账。不算账的自动化就是自动烧钱。

以 55 分钟一次的心跳为例：

$23/月只是一个 Agent。 如果你有 5 个 Agent 都是 55 分钟心跳，月成本 $117——这已经超过很多人的 API 预算了。

分级策略可以大幅降低成本：

📌 记住这点

从 $117 降到 $5，不是减少了功能——是精确匹配了需求。CEO Agent 需要高频巡检，内容 Agent 不需要凌晨 3 点检查有没有新文章要写。

3.6 活跃时段配置

心跳不需要 7×24 运行。你凌晨 3 点在睡觉，Agent 凌晨 3 点检查 inbox 发现没人给它留任务——这次心跳纯浪费。

活跃时段（Active Hours） 让心跳只在你需要的时间段执行：

🧠 底层逻辑

活跃时段不是「Agent 睡觉了」——它只是心跳停了。用户在凌晨 3 点给 Agent 发消息，Agent 照样会响应（因为消息触发是独立于心跳的）。活跃时段控制的只是「Agent 主动巡检」的时间窗口。

反直觉点： 有些场景偏偏需要深夜心跳。比如你的 Agent 负责监控服务器——服务器凌晨挂了，你希望 Agent 能发现并通知你。这种场景就不能限制活跃时段，要全天候运行。

3.7 心跳分级策略

不是所有 Agent 都需要同样频率的心跳。

💡 划重点

心跳有成本——每次心跳都是一次 LLM 调用。55 分钟一次 = 每天 26 次调用。按需设频率，别一刀切。

4. Cron 定时任务：按时间表干活

心跳是「定期巡检」，Cron 是「按时间表执行具体任务」。

4.1 三种模式

4.2 主会话 vs 隔离模式

Cron 任务可以在两种模式下运行：

🎯 打个比方

主会话像你正在办公，同事走过来说「这个做完了」——直接在你面前。隔离模式像同事在会议室里悄悄干活，干完后发一封邮件告诉你结果。

📌 记住这点

监控类任务（视频检测、推特动态）用隔离模式——不要污染主对话的上下文。周报、周复盘用主会话模式——结果直接可见。

4.3 时区陷阱

💡 划重点

Cron 表达式默认使用 UTC 时区。如果你在北京（UTC+8），想让任务在本地早上 9 点执行，表达式里要写凌晨 1 点（9 - 8 = 1）。不注意这个，你的「早上 9 点发周报」会在下午 5 点执行。

5. Webhook（外部触发钩子） 与 Hooks（钩子）：事件驱动

到目前为止，我们讲了三种时间机制：Session 重置（每日）、心跳（周期）、Cron（定时）。它们的共同点是——时间驱动，到点就执行。

但有些事不该等时间到了才做。GitHub 有人提了 PR，你希望 Agent 立刻做 Code Review——不是等下一次心跳碰巧发现。

这就需要事件驱动。

5.1 Webhook：外部系统触发 Agent

Webhook 是一个 URL 端点。外部系统发生事件时，向这个 URL 发送 HTTP 请求，Agent 就收到通知了。

🎯 打个比方

Webhook 像公司的前台电话。外面有人打电话来（GitHub 推送、Stripe 付款、用户注册），前台接到后转给对应的同事处理。Agent 不需要每隔 5 分钟去 GitHub 检查「有没有新 PR」——GitHub 会主动告诉它。

典型流程：

GitHub 有人推送代码
  ↓
GitHub 向 Agent 的 Webhook URL 发送 POST 请求
  ↓
Gateway 接收请求，找到对应的 Agent
  ↓
Agent 收到事件数据（谁推了什么代码）
  ↓
Agent 执行 Code Review，把结果评论到 PR 上

Webhook vs 轮询（Cron）的差别：

📌 记住这点

如果外部系统支持 Webhook，优先用 Webhook 而不是 Cron 轮询。省钱、更快、更优雅。

5.2 Hooks：Agent 内部的事件钩子

Webhook 是「外部 → Agent」。Hooks 是「Agent 内部的事件拦截」。

当 Agent 执行特定操作时，Hooks 允许你在操作前后插入自定义逻辑。

🎯 打个比方

Hooks 像公司的审批流程。员工（Agent）要花钱（调用工具），不是直接花——先经过主管审批（before hook），花完后记账存档（after hook）。

8 个 Hook 时机和它们的公司比喻：

🧠 底层逻辑

Hooks 的核心价值是「关注点分离」。Agent 的主逻辑专注于回答用户问题，而审计、安全检查、日志记录这些横切关注点，通过 Hooks 插入，不污染主逻辑。这和软件工程里的 AOP（面向切面编程）是同一个思想。

5.3 四种时间机制的完整对比

现在我们有了全套武器。对比一下：

💬 说人话

• Cron = 「每周一早上 9 点发周报」——你定时间，它准时干

• Heartbeat = 「每小时巡查一圈」——通用检查，不针对特定任务

• Hooks = 「每次调工具前先审批」——内部流程控制

• Webhook = 「GitHub 有 PR 就告诉我」——外部世界主动推送

5.4 真实自动化场景

把这四种机制组合起来，可以构建强大的自动化流程：

场景 1：每日晨报

触发：Cron — 每天早上 8:30（UTC 0:30）
动作：
  1. 读取 inbox/ 中的待处理任务
  2. 检查日历今日安排
  3. 汇总昨日完成的工作（从日志提取）
  4. 生成晨报，发送到 Telegram

场景 2：服务器监控 + 告警

触发：Heartbeat — 每 55 分钟
动作：
  1. 检查 Gateway 健康状态
  2. 检查各 Agent 最后活跃时间
  3. 如果某个 Agent 超过 2 小时无心跳 → 发 Telegram 告警
  4. 如果 API 余额低于 $5 → 发预警通知

场景 3：Code Review 自动化

触发：Webhook — GitHub PR 创建事件
动作：
  1. 拉取 PR 变更的文件列表
  2. 分析代码变更，检查常见问题
  3. 把 Review 意见评论到 GitHub PR
Hook 附加：after_tool_call 记录每次 GitHub API 调用的耗时

场景 4：会议前自动简报

触发：Cron — 会议前 15 分钟（at 模式，一次性）
动作：
  1. 读取会议议程
  2. 汇总与会人员最近的工作日志
  3. 准备讨论要点，发送到对话

场景 5：依赖安全扫描

触发：Cron — 每周日 02:00 UTC
动作：
  1. 扫描项目的 package.json / requirements.txt
  2. 检查是否有已知安全漏洞
  3. 如果发现高危漏洞 → 创建 GitHub Issue + 通知用户
Hook 附加：error_occurred 时自动保存扫描日志

💡 划重点

自动化不是「越多越好」——是「精确匹配需求」。每个自动化都有维护成本。从最痛的场景开始（比如忘记做周报、服务器挂了不知道），逐步扩展。

6. 设计权衡

设计权衡

一句话检验

• Session 重置会丢记忆吗？ → 不会。只是换白纸，笔记本还在
• 为什么默认凌晨 4 点重置？ → 大部分人在睡觉，感知最小
• main 模式下两个用户的私聊会互相可见吗？ → 是的。main 模式共享同一个 Session，所有人的消息都在同一个上下文里
• 三种 dmScope 怎么选？ → 只有你一个人用选 main，多用户选 per-peer，跨渠道要隔离选 per-channel-peer
• 心跳和 Cron 的区别？ → 心跳是「定期巡检」（通用检查清单），Cron 是「按时间表做具体任务」
• 心跳一个月多少钱？ → 55 分钟一次约 $23/月，分级 + 活跃时段可降到 $5/月
• Webhook 和 Cron 轮询怎么选？ → 外部系统支持 Webhook 就用 Webhook，省钱且实时；不支持才用 Cron 轮询
• Hooks 会拖慢 Agent 吗？ → 每个 Hook 增加几百毫秒延迟，按需开启，别全部打开
• 主会话 vs 隔离模式？ → 主会话结果直接出现在聊天里，隔离模式在后台静默执行

CC 提示词

🚀 对 Claude Code 说 帮我检查 OpenClaw 的定时任务配置： - 读取 /你的路径/.openclaw/openclaw.json 中的 cron 配置

• 列出所有定时任务：名称、表达式、执行频率、使用哪个 Agent、主会话还是隔离模式

• 把 cron 表达式转换成北京时间的可读描述

• 检查是否有时区问题——任务的实际执行时间是否符合预期

• 检查心跳间隔是否合理——是否有 Agent 心跳过于频繁浪费 token

• 给出优化建议

🚀 对 Claude Code 说 帮我查看 OpenClaw Agent 的 Session 状态： - 运行 openclaw status 查看当前 Session 信息

• 检查 session 重置配置（daily reset 时间、idle timeout）

• 看最近一次 Session 重置是什么时候

• 检查 HEARTBEAT.md 内容，告诉我这个 Agent 的心跳巡检清单

• 评估当前配置是否合理

延伸阅读

• 翔宇版 04《核心概念深度解析》— Session 生命周期、会话键映射
• 翔宇版 08《自动化与集成》— Cron 完整配置、Hooks、Webhook
• 翔宇版 05《Gateway 配置大全》— Session 重置参数详解
• 深度教程-05《上下文——最贵的资源》— 为什么需要定期重置来控制上下文大小
• 深度教程-06《Workspace——Agent 的灵魂容器》— HEARTBEAT.md 在 Workspace 中的角色