会话管理

OpenClaw 根据每条入站消息的来源将其路由到一个 会话：DM、群聊、cron 任务等。所有会话状态都由 Gateway 拥有；UI 客户端向 Gateway 查询会话数据。

要在 Control UI、终端或编码 harness 中继续同一个由 Gateway 拥有的会话，请参见会话同步与附加。

对于个人代理默认设置——一个由所有 DM 渠道共享的持续对话，群活动和后台工作流入其中——请参见主会话。

消息如何路由¶

当使用 session.scope: "global" 时，所选代理仍拥有其会话。 共享键 global 不会合并不同代理的对话： 命令、技能、回复和后台任务通知仍保留由路由或显式请求所选的代理。 会话列表、模型筛选器、预览和共享控件也保留所存储对话的代理，而不是聚合视图的默认代理。 使用 /stop 停止、删除、重置或归档会话时，只会取消所选对话中该代理的工作。 即使代理使用相同的会话键，另一个代理的活跃轮次和排队消息也会被保留。

DM 隔离¶

默认情况下，所有 DM 共享一个会话以保持连续性，这对单用户设置没有问题。

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

session.dmScope 选项：

Slack Agent View 和 Assistant View 的 DM 是例外：每个可见根都会在 dmScope 所选基础之上获得自己的 :thread:<rootTs> 会话，因此这些对话即使在 main 下也保持隔离。参见 Agent View DMs。

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

已弃用的渠道停靠¶

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

使用 session.identityLinks 关联一个人的身份以用于 DM 会话路由，或使用线程绑定会话 将受支持的对话保持附加到子代理。这些是独立功能；两者都不会恢复手动跨渠道停靠。

群和房间路由¶

session.groupScope 控制非直接 peer 存储对话上下文的位置：

路由绑定可以覆盖全局值。当只有指定的团队房间应加入主对话时，这很有用：

{
  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 小时或 Gateway 重启时过期，以先到者为准。活动不会延长其生命周期。过期会停止活跃工作，并删除会话和转录，且不创建归档。隐身模式不会运行 OpenClaw 的自动内存刷新，在你重置或删除它时也不会创建转录归档。Codex 支持的运行也会以临时模式启动其 harness 线程，因此 Codex 不会写入 rollout 或本地会话状态文件；其他模型提供商使用 HTTP API，并在 OpenClaw 中不保留本地提供商转录。

委托工作使用其原生执行和完成所有者。实时子代理活动和完成投递仍可用。

incognito- 段保留给仪表板、子代理和隐藏内部会话键；openclaw doctor --fix 会重命名任何冲突的旧持久键。

隐身模式不会限制代理的正常工具。显式请求保存信息，或任何由工具驱动的文件写入，仍可能将数据持久化到隐身会话存储之外。你配置的模型提供商仍会处理你发送的消息。隐身内容会从普通 Gateway 输出、投递和响应诊断、WebSocket 事件预览、raw-stream、cache-trace 以及 Anthropic 负载日志中排除。实时回复仍可用，OpenClaw 仍会记录操作诊断和无内容审计元数据，例如 HMAC 引用。

在多用户网关上，隐身线程仅对管理员作用域连接可见，并且永远不会通过另一个会话的代理会话工具或会话记录搜索出现。这可防止它们被 storage 以及其他通过网关访问的用户看到，但不能防止网关所有者或进程操作者看到，后者始终可以观察实时会话。

跨对话记忆¶

独立的会话记录控制每个对话的本地历史。对于个人或完全受信任的代理，memory.search.rememberAcrossConversations: true 会添加一个可选的检索步骤，跨该代理的其他私有对话进行检索；它不会合并它们的会话记录。

私有直接对话和持久显式 UI 对话可以相互提供相关上下文。在默认 session.groupScope: "per-group" 下，群组与频道在两个方向上都保持隔离：它们的会话记录不是私有召回来源，这些对话中的回复也不会接收私有会话记录上下文。当前对话也会被排除，因为其历史已经加载。

此设置不会更改会话键、DM 作用域、路由、投递或 tools.sessions.visibility。MEMORY.md 和 memory/*.md 中的共享工作区记忆也保持现有行为。当前内存提供者必须支持受保护的私有会话记录召回；诸如 Lossless Claw 之类的上下文引擎保持独立，并可与其并行运行。有关设置和运行时详情，请参阅 活动记忆。

会话生命周期¶

会话会被重复使用，直到你手动重置它们或选择自动重置策略：

• 无自动重置（默认 mode: "none"）- 会话保持相同的 sessionId；随着对话增长，压缩会管理活动上下文。
• 每日重置（mode: "daily"）- 选择启用网关主机上配置的本地小时（session.reset.atHour，默认 4，0-23）开始新会话。每日新鲜度基于当前 sessionId 开始的时间，而不是后续的元数据写入。
• 空闲重置（mode: "idle"）- 在 session.reset.idleMinutes 无活动后选择开始新会话。空闲新鲜度基于最后一次真实用户/频道交互，因此心跳、cron 和 exec 系统事件不会保持会话存活。
• 手动重置 - 在聊天中输入 /new 或 /reset。/new <model> 还会切换模型。

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

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

全局启用自动重置，然后按聊天类型或频道覆盖它们：

{
  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；模式会拒绝这两种已弃用的形式。

Gateway 重启恢复¶

当 Gateway 重启中断活动轮次时，OpenClaw 会尝试自动继续现有会话。三次未能启动后端轮次的尝试会耗尽恢复预算。一旦真实后端轮次开始，预算就会刷新，因此之后的 Gateway 重启不会消耗旧的配额。仅接受、排队或准备恢复请求不会刷新它。不报告轮次接受的 CLI 后端只有在观察到助手输出或工具活动后才会刷新预算；静默启动不会刷新它。

当重放被中断的轮次时，恢复会保留其记录的工具调用和结果，包括嵌套工具活动，并复用原始用户消息。已完成的回复或后续用户消息会关闭该轮次以进行重放。

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

如果自动恢复耗尽，会话记录仍然可用。在 WebChat 中使用 在新会话中恢复，或在其他频道中使用 /new 或 /reset，以开始替代会话。

状态存储位置¶

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

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

• sessionStartedAt：当前 sessionId 开始的时间；每日重置使用此值。
• lastInteractionAt：延长空闲生命周期的最后一次用户/频道交互。
• updatedAt：最后一次存储行变更；可用于列表和修剪，但不是每日/空闲重置新鲜度的权威依据。

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

会话维护¶

OpenClaw 通过 session.maintenance 随时间限制会话存储，默认值如下：

{
  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 分钟周期性重新检查。这使 符合条件的会话无需进一步流量即可老化。无法改变 年龄或计数维护结果的写入会跳过候选扫描。自动规划在进入前台写入队列前 只读取保留和保护元数据； 上限选择只保留所需的最旧合格条目。写入器在应用更改前会检查 已准备的存储修订，因此并发更新会被重新考虑而不是覆盖。 如果写入使自动维护计划失效，其替代计划会等待 最后一次写入后的静默窗口（一秒，然后两秒）。连续 三次失效会暂停自动重试并记录原因；新的 条目写入可以安排另一次尝试。warn 模式会记录维护 年龄事实，而不构建或派发自动回收。

maxEntries 默认为 5000 行未归档会话行。归档行不占用 上限。现有显式限制保持不变。 当压力超过上限时，清理会归档最旧的合格普通 会话，而不是删除其转录。合成运行时会话，例如 cron、hooks、heartbeat、ACP 和子代理，仍是一次性的，并且可以 被移除。已固定的根会话、活动或已接纳的工作、模型锁定会话以及 持久外部会话指针受保护；因此，当受保护行本身超过上限时，未归档总数 可能仍高于上限。

根会话以及自动父级为代理 Home 根的会话可以固定； 真正的子会话和子代理运行会拒绝固定请求。持久子 会话保留其侧边栏嵌套；子代理运行显示在转录活动和 会话转录中。现有子固定会消失，并且不再保护会话 免受维护。

Gateway 模型运行探测会话默认是短命的。匹配 agent:*:explicit:model-run-<uuid> 的行使用固定 24h 保留，但清理受 压力门控：它仅在达到会话条目 维护/上限压力时移除过期探测行，并在更广泛的过期条目 老化截止和条目上限之前运行。普通直接、群组、线程、cron、hook、heartbeat、 ACP 和子代理会话不会继承此 24h 保留。

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

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

最近会话保护不会改变受管工作树垃圾回收； 持久仪表板会话默认在 7 天不活动后自动归档， 并且 pruneAfter 默认在 30 天后就地归档其他合格持久会话， 保留其会话 ID 和转录代。一次性 自动化行仍会在其老化截止时删除。

已固定会话以及手动、旧版、老化保留、过期仪表板或恢复 归档受用户保护，并豁免自动维护。因达到 maxEntries 而归档的会话会记录该原因，并在物理使用量超过 maxDiskBytes 之前保持可搜索/可恢复；磁盘预算清理随后可能 在更便宜的工件和未引用历史耗尽后删除 最旧的上限归档。没有记录归档原因的会话仍受保护。

在跳过某个历史代或已归档会话后，磁盘预算清理 在考虑另一次删除前会重新检查物理使用量。测量 失败会停止清扫。

后台磁盘预算检查在条目写入时最多每 30 分钟运行一次。 删除和重置操作可以请求更早检查，但重复请求 会合并为每个存储每分钟最多一次强制检查。如果清理耗尽 合格历史且存储仍超预算，自动检查会退避 30 分钟并记录一条警告，直到压力清除或预算变化。 警告建议提高 session.maintenance.maxDiskBytes 或导出 并删除不需要的会话。后续活动会恢复检查； openclaw sessions cleanup --enforce 仍立即可用。

清理首先尝试截断 WAL，而不等待读者。如果读者 阻止截断，完整的 PASSIVE 检查点就足够：与清理相关 的帧必须已到达主数据库，即使 WAL 文件仍保持分配。 保留的 WAL 字节仍计入物理预算。成功清理 会记录一条结果，包含前后字节数和移除数量。

不完整的 SQLite WAL 检查点是单独的延迟。清理会保留 归档和历史，而不是删除被阻塞检查点后面的更多数据。 结果会记录 deferredReason: "checkpoint-incomplete"、前后 WAL 字节 以及检查点结果。自动和手动预算通道保持 延迟，直到检查点所有者在待处理清理工作后记录完成。 并发写入产生的较新帧不会擦除该完成。每次 SQLite 清理 删除或 vacuum 提交都需要新的完成才能进一步修剪，因此 固定这些更改的读者仍会延迟清理。排序使用单调时间； 经过时间、预算变化或系统时钟校正无法释放门控。 正常周期性检查点继续，后续活动可在恢复后恢复清理。

在 Gateway 日志中查找 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 预览过期的按 peer 键控的 DM 行。应用相同标志会退役这些旧的直接 DM 行，并将其转录保留为已删除归档。

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

检查会话¶

相关¶

• 会话搜索 - 跨过往转录进行全文召回
• 会话修剪 - 修剪工具结果
• 压缩 - 总结长对话
• 会话工具 - 用于跨会话工作的代理工具
• 会话管理深入解析 - 存储模式、转录、发送策略、来源元数据和高级配置
• 多代理 - 跨代理的路由和会话隔离
• 多代理沙箱和工具 - 每个代理的沙箱和工具限制，包括会话可见性
• 转录卫生 - 在运行前应用的内存中、特定于提供方的转录清理
• 命令队列
• 渠道路由 - 入站消息如何路由到会话