本页内容

本页内容

会话和内存

会话管理

OpenClaw 会根据每条入站消息的来源将其路由到一个 会话:私信、群聊、定时任务等。所有会话状态都由 gateway 持有;UI 客户端会向 gateway 查询会话数据。

会话列表在返回行之前协调无效的元数据。如果本机会话在列表读取期间更改所有权,则网关会重试其运行时元数据一次。持续的更改会暂时使用该行的已配置模型元数据,同时其他会话仍然可用。下一个列表读取重试其本机元数据。

要在 Control UI、终端或编程工具中继续使用同一个由 Gateway 持有的会话,请参阅会话同步与附加。

如需了解个人代理的默认设置——所有 DM 频道共享一个持续滚动的会话,群组活动和后台工作也会流入其中——请参阅 主会话。

从共享调度程序传递的命令交换也是对话历史记录。 OpenClaw 将用户的命令和传递的回复作为普通的 user/assistant 消息附加。 Discord 和 Telegram、Slack 参数菜单以及 Mattermost 模型选择器上的本机菜单和命令确认在交付后也会保留。以后可以翻阅这些交流和聊天记录。登录、配对和敏感 /config set 或 /debug set 值在存储前经过编辑。 /new和/reset将确认交换放在新的会话中;他们不会重写旧的会话。 /btw 和 /side 保持短暂状态,消息编辑或删除不会重写较早的记录行。

消息如何路由

来源 行为
直接消息 默认共享会话
群聊 默认情况下每组隔离
Rooms/channels 默认情况下每个房间都是隔离的
Cron 任务 每次运行生成新会话
网络钩子 每个 hook 独立

本机目录源 ID、Matrix 房间和线程 ID 以及 Signal 组 ID 区分大小写:仅大小写不同的 ID 标识不同的对话。

对于 session.scope: "global",所选代理仍拥有其会话。共享密钥 global 不会合并不同座席的对话:命令、技能、回复和后台任务通知保留路由或显式请求选择的座席。会话列表、模型过滤器、预览和共享控件还保留存储的对话的代理,而不是聚合视图的默认代理。重命名、固定或编辑会话元数据会保留现有消息预览,而无需重新读取文字记录。新消息、文字记录替换、已完成的文字记录修复以及冷存储恢复刷新预览;模型选择或回退状态的更改会刷新相关模型事实。使用 /stop 停止、删除、重置或存档会话只会取消该座席对所选对话的工作。即使代理使用相同的会话密钥,也会保留另一个代理的活动轮次和排队消息。

自动会话名称

当网关发送消息时,没有明确名称的交互式聊天会话会在后台生成主题标题。命名与工作树和回复准备同时开始;它不会等待代理的第一个进度事件,也不会阻止转弯。标题模型完成后,名称就会出现。如果标题请求在重叠回合时失败,则会在该回合结束后重试一次。显式名称和手动重命名将被保留。

DM 隔离

默认情况下,所有 DM 共享一个会话以保证连续性,这对于单用户设置来说非常合适。

json5
{  session: {    dmScope: "per-channel-peer", // isolate by channel + sender  },}

session.dmScope 可选值:

值 行为
main(默认) 所有DM共享主会话
per-peer 按发送者隔离,跨频道生效
per-channel-peer 按频道 + 发送者隔离(推荐)
per-account-channel-peer 按账户 + 频道 + 发送者隔离

Slack 代理视图和助理视图 DM 是例外:每个可见根在 dmScope 选择的基础之上都有自己的 :thread:<rootTs> 会话,因此即使在 main 下,这些对话也保持隔离。请参阅 Agent 查看 DM。

使用 openclaw security audit 验证你的设置。

退役通道对接

渠道对接和手动跨渠道回复焦点已被移除。 /dock-* 命令不再将会话的回复目标移动到另一个通道。

使用 session.identityLinks 关联 DM 会话路由的人员身份,或使用 线程绑定会话 将支持的对话保持附加到子代理。这些是独立的功能;两者都无法恢复手动跨通道对接。

群组和房间路由

session.groupScope 控制非直接对等方存储对话上下文的位置:

值 行为
per-group(默认) 将每个组、房间或频道保留在其现有频道范围的会话中
main 将组、房间和通道路由到代理的 主会话

路由绑定可以覆盖全局值。当只有指定的团队房间应加入主要对话时,这非常有用:

json5
{  bindings: [    {      agentId: "main",      match: {        channel: "slack",        peer: { kind: "channel", id: "C0123TEAM" },      },      session: { groupScope: "main" },    },  ],}

对于将房间分类为一个组的提供商,请使用 peer.kind: "group"。绑定覆盖胜过全局 session.groupScope。此设置仅更改会话密钥选择:DM 路由、提及门控、传递上下文和对源房间的回复保持不变。

隐身会话

隐身会话仅可从 Control UI 的 New thread 屏幕使用。在启动线程之前打开 Incognito,以将其会话条目、转录和压缩状态保留在进程内存中而不是磁盘上。该线程将在创建后 24 小时或网关重新启动时过期(以先到者为准)。活动不会延长其寿命。到期将停止活动工作并删除不带存档的会话和记录。 Incognito 不会运行 OpenClaw 的自动内存刷新,并且在您重置或删除它时不会创建转录存档。 Codex-backed 运行也会以临时模式启动其harness线程,因此 Codex 不会写入任何转出或本地会话状态文件;其他模型提供者使用 HTTP API,并且在 OpenClaw 中不保留本地提供者转录。

委派的工作使用其本机执行和完成所有者。实时子代理活动和完成交付仍然可用。

incognito- 前缀段保留给 dashboard、subagent 和隐藏的内部会话键;openclaw doctor --fix 会重命名任何发生冲突的旧版持久化键。

隐身模式不会限制代理的正常工具。保存信息的显式请求或任何工具驱动的文件写入仍然可以将数据保留在隐身会话存储之外。您配置的模型提供程序仍会处理您发送的消息。隐身内容不包括在普通网关输出、传输和响应诊断、WebSocket 事件预览、原始流、缓存跟踪和 Anthropic 有效负载日志中。实时回复仍然可用,并且 OpenClaw 仍然记录操作诊断和无内容审计元数据,例如 HMAC 引用。

在多用户网关上,隐身线程仅对管理范围的连接可见,并且永远不会通过其他会话的代理会话工具或脚本搜索出现。这限制了持续的会话历史记录和通过其他网关中介会话的访问;它不会使所有工具、上传、批准或配置的诊断数据变得短暂。网关所有者或流程操作员仍然可以观察实时会话。

跨会话记忆

单独的转录会控制每个会话的本地历史。对于个人或完全受信任的代理,memory.search.rememberAcrossConversations: true 会在该代理的其他私有会话中增加一个可选的检索步骤;它不会合并这些转录内容。

私人直接和持久显式 UI 对话可以相互提供相关上下文。在默认情况下 session.groupScope: "per-group" 下,组和频道在两个方向上保持独立:它们的转录本不是私人回忆来源,并且这些对话中的回复不会收到私人转录本上下文。当前对话也被排除,因为其历史记录已加载。

此设置不会更改会话密钥、DM 范围、路由、传递,或 tools.sessions.visibility。MEMORY.md 和 memory/*.md 中的共享工作区记忆也保持其现有行为。当前记忆提供程序必须支持受保护的私有转录回忆;像 Lossless Claw 这样的上下文引擎仍然相互独立,并且可以与其并行运行。有关设置和运行时详细信息,请参见 Active Memory。

会话生命周期

独立会话可以同时初始化它们的第一轮。对同一会话的请求保持有序;父分叉和重置保留其共享状态协调。

会话会一直复用,直到你手动重置会话,或选择启用自动重置策略:

  • 不自动重置(默认 mode: "none")——会话保持相同的 sessionId;随着对话增长,压缩机制会管理活跃上下文。
  • 每日重置(mode: "daily")——在网关主机配置的本地时间 (session.reset.atHour,默认为 4,范围为 0-23)到达时启用新会话。 每日新鲜度取决于当前 sessionId 的启动时间,而不是之后的元数据写入时间。
  • 空闲重置 (mode: "idle") - 在 session.reset.idleMinutes 不活动后选择进入新会话。空闲新鲜度基于最后一次真实的 user/channel 交互,因此心跳、cron 和 exec 系统事件不会使会话保持活动状态。
  • 手动重置——在聊天中输入 /new 或 /reset。/new <model> 还会切换模型。

当同时配置了每日和空闲重置时,以先到期的那个为准。heartbeat、cron、exec 和其他系统事件轮次可能会写入会话元数据,但这些写入不会延长每日或空闲重置的新鲜度。当重置使会话滚动时,旧会话中排队的系统事件通知会被丢弃,因此过时的后台更新不会被追加到新会话的第一条提示前。

具有活跃的、由提供商拥有的 CLI 会话的会话,也遵循相同的不自动重置默认设置。当这些会话应按计时器过期时,请使用 /reset 或显式配置 session.reset。

全局启用自动重置,然后按聊天类型或频道进行覆盖:

json5
{  session: {    reset: { mode: "daily", atHour: 4 },    resetByType: {      group: { mode: "idle", idleMinutes: 120 },      thread: { mode: "daily", atHour: 6 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },  },}

resetByType 支持 direct、group 和 thread。Doctor 会将旧版的 dm 条目迁移为 direct,并将 session.idleMinutes 迁移为 session.reset.idleMinutes;该架构会拒绝这两种已弃用的形式。

网关重启恢复

当网关重新启动中断已允许的轮次(包括仍在队列中等待或准备执行的轮次)时,OpenClaw 会尝试自动继续现有会话。取消排队工作之前关闭记录恢复。如果重新启动取消在该记录提交之前完成收集的运行,则关闭将保留其恢复保管权,除非会话或运行所有者发生更改。即使调用者的中止信号保持打开状态并且生命周期持久性在回复清理后完成,后端拥有的重新启动中止仍保留相同的监护权。跳过的会话会被记录并注明原因,包括其他会话何时恢复。未能启动后端转向的三次尝试耗尽了恢复预算。一旦真正的后端轮转开始,预算就会刷新,因此稍后的网关重新启动不会消耗旧的配额。单独接受、排队或准备恢复请求不会刷新它。 CLI 不报告轮次接受情况的后端仅在观察到助手输出或工具活动后刷新预算;静默启动不会刷新它。

对于新创建的会话的合格本地、空闲、重新启动安全初始轮,sessions.create 首先提交会话,然后在确认开始运行之前一起提交输入记录和重新启动声明。这些提交之间的失败或崩溃可能会使创建的会话不保留输入字节。输入提交后,即使客户端从未收到确认,重新启动恢复也会保留该轮次。排队输入、依赖于钩子的输入、工作器放置、空闲 chat.send 以及现有持久输入的重试保留其现有的准入和恢复行为。在托管工作树准备期间重新启动会恢复已接受的轮次,并在启动代理之前准备或重用其本地工作树。恢复不会继承原始调用者运行工作树设置脚本的权限。

重播中断的转弯时,恢复会保留其记录的工具调用和结果,包括嵌套工具活动,并重用原始用户消息。当抄本编写器仍然可用时,重新启动中止的嵌入响应将保留其已流式传输的文本作为中断的辅助消息。该响应中未完成的工具调用将在持久化之前被丢弃。完成的回复或稍后的用户消息将关闭并重播。

对于经过身份验证的操作员轮流,恢复会根据当前配置文件、角色、访问授权和设备策略重新验证原始呼叫者记录的权限。因此,Control UI 管理员可以在重新启动后继续授权的自动化工作,而不会丢失 operator.admin。恢复无法获得原始调用者缺少的范围,并且撤销仍然会停止恢复的运行。没有记录授权来源的较旧的中断转弯仍然受到限制;发送新的经过身份验证的消息以继续特权工作。会话所有权或保存的显示名称永远不会授予恢复权限。

这还涵盖由子代理完成或暂停通知启动的父轮流。被中断的父进程继续独立于后来的子进程完成,并且相同通知的重试会加入该恢复而不是再次开始轮次。在让出孩子后仍在等待的父母仍归其孩子批次所有。

如果无法重建委托轮次的发送者权限,自动恢复将停止,并在记录或原始频道中记录原因和可见通知。该通知在WebChat中提供了Resume。单击提供当前操作员权限并在同一会话中继续保存的任务。仅保存的委托不会授权重新启动后重播。

重新启动恢复等待开始时发送的消息保持待处理状态。一旦恢复开始,它们就会遵循会话的正常消息队列策略。您不需要仅仅因为恢复正在等待容量而重新发送消息。停止或替换会话仍会取消挂起的工作。

如果子代理恢复在准备传入轮次时更改了会话保护事实,则回复初始化将刷新这​​些事实并在其现有的有限重试预算内重试。 Exhaustion 报告错误,要求您重试该消息。当子代理公告继续会话时,尚未到达模型的已保存用户消息仍保留为用户输入;它不会降级到后台上下文。

如果自动恢复耗尽,未完成的任务和记录仍然可用。使用 WebChat 中的 Resume 继续使用相同的会话身份、工作区、参与者和子会话。恢复会保存新的操作员输入,并在开始工作之前一起清除重新启动墓碑。它会重新检查您当前的权限;先前的批准和授权不会恢复。完成的工具结果保留在记录中,并且在重复之前必须检查不确定的效果。现有的安全重启工具限制仍然适用于延续。

已恢复到替换的会话将打开该替换;恢复两者可能会重复任务。如果 CLI 运行时无法强制执行所需的安全重启工具,则 WebChat 会在新会话 中提供Resume。未解决的最终交付记录必须在就地延续之前解决,并且丢失的成绩单需要修复。在其他通道中,/new或/reset仍然启动替换会话。

状态存放位置

  • 运行时会话行和记录:默认为 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
  • 归档的转录文件: ~/.openclaw/agents/<agentId>/sessions/
  • 旧版行迁移来源: ~/.openclaw/agents/<agentId>/sessions/sessions.json

存档发现使用选定的存储、记录的副本路径和代理目录。预代理 ~/.openclaw/sessions/ 目录不再是隐式回退;显式配置的路径仍然有效。

每个 agent 的 SQLite 数据库中的会话行会保留独立的生命周期时间戳:

  • sessionStartedAt:当前 sessionId 开始的时间;每日重置使用它。
  • lastInteractionAt:最后一次 user/channel 交互可延长空闲寿命。
  • updatedAt:最后一个存储行突变;对于列出和修剪很有用,但对于 daily/idle 重置新鲜度不具有权威性。

要从旧安装导入旧版 sessions.json 行和热记录 JSONL 历史记录,请停止网关,备份其状态,并在重新启动之前运行 openclaw doctor --fix。网关和本地 CLI 启动使用 SQLite,无需导入、恢复或重写旧会话文件。如果启动发现旧存储,它会拒绝就绪并打印活动配置文件的 Doctor 命令,而不是默默地从空历史记录开始。在 Doctor 导入期间,没有 sessionStartedAt 的行将从旧记录 JSONL 会话标头(如果可用)解析。如果较旧的行也缺少 lastInteractionAt,则空闲新鲜度会回落到该会话开始时间,而不是稍后的簿记写入。使用 openclaw doctor --session-sqlite inspect --session-sqlite-all-agents 和 Doctor 迁移序列 进行检查和验证。

会话维护

OpenClaw 通过 session.maintenance 按时间对会话存储进行约束,默认值如下:

json5
{  session: {    maintenance: {      mode: "enforce", // "enforce" applies cleanup; "warn" only reports      pruneAfter: "30d",      archiveDashboardAfter: "7d", // false or 0 disables this dashboard trigger      maxEntries: 5000,      preserveRecent: false, // opt in with a duration such as "7d"    },  },}

对于生产规模的 maxEntries 限制,Gateway 运行时写入会先使用一个较小的高水位缓冲区,并在批处理中清理回配置的上限。会话存储读取在 Gateway 启动期间不会修剪或限制条目,因此启动和独立的 cron 会话不会承担完整存储清理的成本。openclaw sessions cleanup --enforce 会立即应用该上限。

普通条目在下一个年龄边界写入并回复初始化臂后台维护,在商店保持营业的情况下每 30 分钟定期重新检查一次。这使得符合条件的会话在没有更多流量的情况下过期。回复准备不会等待不相关的保留清理。无法更改年龄或计算维护结果的写入会跳过候选扫描。自动规划在进入前台写入队列之前仅读取保留和保护元数据;年龄候选者必须达到其启用的保留阶段的截止值,并且维护仅查找活动会话祖先,除非运行时身份需要完整的会话密钥清单。上限选择仅保留所需的最旧的合格条目。自动容量清理可在最多 64 个条目的批次之间产生写入器;显式清理仍然是详尽的。编写器在应用更改之前重新检查所选行及其保护,因此会重新考虑并发更新而不是覆盖。不相关会话的活动和已结束的保护不会使计划失效。当上限通行证仅找到持久保护的条目时,普通活动就不会重复该徒劳的计划。新的合格条目、恢复的身份、丢失的条目保护以及更改的政策重新考虑。当传递清理释放会话的剩余恢复保护时,它会恢复空闲维护。针对活动会话、运行时提供程序或最近活动的临时保护不会抑制普通写入的计划;年龄期限和定期复查仍会恢复闲置清理。虽然条目压力仍然需要清理,但一旦临时写保护结束,容量维护就会重新访问条目,而不需要再次写入条目。释放获取的会话工作也会唤醒空闲容量维护;重叠的工作可以使会话受到保护,直到最终许可发布为止。如果写入使自动维护计划无效,则其替换会等待计划的重试延迟(一秒,然后两秒)。进一步写入合并到重试中,而不会无限期推迟。连续三次失效会暂停自动重试并记录原因;新的条目写入可以安排另一次尝试。 warn 模式跳过自动回收。经过认证的记录回填和使用缓存写入保留仅受保护的无操作结果,而条目更改发布和范围写入收据保持最新状态。未知写入仍然会使该结果无效,并在重新规划之前等待现有的安静窗口。

maxEntries 默认为 5000 个未归档会话行。存档的行不消耗上限。现有的明确限制保持不变。当压力超过上限时,清理会归档最早的符合条件的普通会话,而不是删除其记录。 Synthetic 运行时会话(例如 cron、hooks、heartbeat、ACP 和子代理)仍然是一次性的,可以删除。固定根会话、活动或承认的工作、模型锁定会话以及持久的外部会话指针均受到保护;因此,当仅受保护的行超过上限时,未归档的总数可以保持在上限之上。

可以固定根会话和自动父级到代理主根的会话;真正的子会话和子代理运行拒绝 pin 请求。持久子会话保留其侧边栏嵌套;子代理运行出现在脚本活动和会话脚本中。现有的子 pin 会消失,并且不再保护会话免受维护。

默认情况下,网关模型运行检查会话是短暂的。匹配 agent:*:explicit:model-run-<uuid> 的行使用固定的 24h 保留,但清理是压力门控的:它仅在达到会话条目 maintenance/cap 压力时删除过时检查行,并在更广泛的过时条目年龄截止和条目上限之前运行。正常的直接、组、线程、cron、hook、heartbeat、ACP 和子代理会话不会继承此 24 小时保留。

维护保留持久的外部对话指针,包括直接、组和线程范围的聊天会话,同时仍然允许合成 cron、hook、heartbeat、ACP 和子代理条目过期。

共享或大容量安装可以设置 preserveRecent 以保护最近活动的交互式会话以及这些会话拥有的每个 SQLite 历史生成。当省略或设置为 false 时,该选项将被禁用,因此个人安装将保留正常的最早的优先策略。 Synthetic 模型运行、cron、hook、heartbeat、ACP 和子代理会话仍然符合有界清理的条件。保护可以暂时将存储保持在其条目或磁盘目标之上;它在配置的不活动窗口之后过期。

最近会话保护不会改变托管工作树垃圾收集;默认情况下,持久仪表板会话会在 7 天不活动后自动存档,而 pruneAfter 默认情况下会在 30 天后归档其他符合条件的持久会话,并保留其会话 ID 和记录生成。一次性自动化行仍会在其年龄截止时删除。

固定会话和手动、遗留、年龄保留、陈旧仪表板或恢复存档受用户保护,并且免于自动维护。由于达到 maxEntries 而归档的会话会记录该原因并保留为 searchable/restorable,直到物理使用量超过 maxDiskBytes;然后,在较便宜的工件和未引用的历史记录耗尽后,磁盘预算清理可能会删除最旧的上限存档。没有记录归档原因的会话仍然受到保护。

跳过历史生成或存档会话后,磁盘预算清理会在考虑再次删除之前重新检查物理使用情况。测量失败会停止扫描。

后台磁盘预算检查最多每 30 分钟在条目写入时运行一次。未更改的条目补丁不会安排检查。删除和重置操作可以更快地请求检查,但重复的请求最多会合并为每个商店每分钟一次强制检查。如果清理耗尽了符合条件的历史记录,并且商店仍然超出预算,则会自动检查 30 分钟并记录一个警告,直到压力消除或预算发生变化。每个代理旧存储定位器及其规范 SQLite 路径共享此队列和退避。自定义聚合商店定位器保留其自己的维护范围。当一次pass没有回收任何东西后,下一次自动检查首先检查符合条件的数据,而不保留前台写入器;仅受保护的压力不会重复存档修剪或检查点。手动清理仍会立即运行。该警告建议提高 session.maintenance.maxDiskBytes 或导出并删除不需要的会话。检查后续活动的恢复情况; openclaw sessions cleanup --enforce 仍可立即供货。

Cleanup 首先尝试截断 WAL,而不等待读者。如果读取器阻止截断,则完整的 PASSIVE 检查点就足够了:与清理相关的帧必须已到达主数据库,即使 WAL 文件仍保持分配状态。保留的 WAL 字节仍计入物理预算。成功的清理会记录一个结果,其中包含 before/after 字节和删除计数。存档修剪测量前台写入队列之外的物理使用情况。每个删除和页面回收单元都保留自己的许可,并在回收单元之间产生产量。存档保留还会选择写入队列外部的候选者,然后重新检查并删除每次准入最多 16 行,在批次之间产生收益,同时保留每次传递相同的 256 行选择限制。并发收缩可以在下一次测量结束扫描之前修剪一个额外的最旧的派生存档;规范保留和删除资格检查保持不变。

不完整的 SQLite WAL 检查点是单独的延迟。清理会保留档案和历史记录,而不是删除被阻止的检查点后面的更多数据。结果记录前后deferredReason: "checkpoint-incomplete"、WAL字节,以及检查点结果。手动清理和后续受限制的自动检查会重试检查点:当另一个连接完成检查点而不发布其结果时,较早被阻止的观察无法无限期地暂停清理。清理工作仍然需要检查点所有者在待处理的清理工作之后记录完成情况。并发写入中的较新帧不会擦除该完成。每个 SQLite 清理删除或真空提交都需要在进一步修剪之前进行新的完成,因此固定这些更改的读者仍然会推迟清理。排序使用单调时间;经过的时间、预算更改或系统时钟校正都无法释放门。正常的定期检查点继续进行。已发布的完成允许立即重试下一个活动;否则适用正常检查间隔。

在网关日志中查找 session history disk budget deferred until a completed WAL checkpoint is observed。它的检查点字段包括显式跟踪的读取器的有界操作名称、连接和线程 ID 以及开放事务标志。收集这些事实并不能保持联系畅通或改变工人的退休生活。它们不证明哪个连接持有阻塞 SQLite 读取标记。明确的读者跟踪、其他工作人员和其他进程之外的原始本机语句可能仍然无法识别。不包含转录内容、SQL 文本或绑定值。

如果你之前使用过 DM 隔离,后来又将 session.dmScope 恢复为 main,可以使用 openclaw sessions cleanup --dry-run --fix-dm-scope 预览那些按同伴键区分、已过期的 DM 行。应用同一标志后,会退役这些旧的直接 DM 行,并将其记录保留为已删除的归档。

可以使用 openclaw sessions cleanup --dry-run 预览任何维护运行。

检查会话

命令 显示内容
openclaw status 会话存储路径和最近活动
openclaw sessions --json 所有会话(可使用 --active <minutes> 进行筛选)
在聊天中使用 /status 上下文使用情况、模型和切换项
/context list 系统提示中包含的内容

相关内容

本页有帮助吗?