6.1 会话模型与状态持久化

本节介绍 OpenClaw 的会话管理机制，主要包含三个核心环节：会话作用域的划分、重置策略的设定，以及会话状态的持久化与排障。通过合理的配置，开发者能够将“串话”、“重复执行”和“状态恢复失败”等隐患，转化为可配置、可观测的工程实践。

6.1.1 会话作用域：先把会话键划清楚

OpenClaw 的会话行为由全局 session 配置控制。最重要的旋钮是 session.scope，用于定义“哪些消息会被折叠到同一条会话里”。官方示例与字段解释见：会话配置。

典型选择思路。

• 每发送者一条会话：适合私聊与个人助理。

• 每线程或每主题一条会话：适合支持线程的渠道或需要把不同话题严格隔离的场景。

• 将多个身份链接到同一会话身份：适合一个人跨 Telegram 与 Discord 使用同一智能体。

可以通过 Dashboard 的 Sessions 页面直观管理活跃的会话及其 Token 消耗情况，如下图所示：

Sessions 会话管理与用量

图 6-1：Sessions 会话管理与用量

在深入如下配置示例之前，请先参考下述会话概念词汇库，避免术语混淆：

概念	配置字段	默认值	别名或补充说明
私聊归并键	session.dmScope	main	可选值：main（所有 DM 归并为一条主会话）、per-peer（按对端隔离）、per-channel-peer（按渠道+对端隔离）、per-account-channel-peer（按账号+渠道+对端隔离）。
会话重置策略	session.reset	无统一默认	支持 mode（如 daily、idle）、atHour、idleMinutes 等字段；可通过 session.resetTriggers 配置手动重置命令。
会话身份绑定	session.identityLinks	{}	用于跨渠道绑定身份，例如把 TG 的 A 和 Discord 的 A 合并。

配置示例（从官方示例改写，突出关键字段）：

{
  session: {
    scope: "per-sender",

    // 私聊会话折叠到 agent:<agentId>:<mainKey>，用于把多条私聊归并为“主会话”。
    dmScope: "main",
    mainKey: "main",

    // 将多个渠道身份链接为同一“人”，避免跨渠道对话割裂。
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
  },
}

验收点：能解释一条消息最终会落到哪个 sessionKey，并且能在日志与会话存储中找到对应记录。

6.1.2 重置策略：把重置做成规则，不要靠手动清空

长时间运行后，会话会积累历史与上下文偏差。官方提供了按时间或按空闲时间重置的配置，并支持按会话类型分别设置（例如私聊更长，群聊更短）。参考：会话配置。

配置示例：

{
  session: {
    // 全局重置策略
    reset: {
      mode: "daily",        // 可选 "daily"、"idle" 等
      atHour: 4,            // daily 模式下每天重置的小时（本地时区）
      idleMinutes: 60,      // 空闲超过此时长后重置
    },
    // 手动重置命令
    resetTriggers: ["/new", "/reset"],
  },
}

[!NOTE] 会话重置策略通过 session.reset 全局配置。如需按会话类型（私聊、群聊、线程）做差异化重置，请参考官方文档中 session 下的细分字段说明。

验收点：在重置窗口内，会话能按预期断开历史，且不会误删正在执行的高风险作业。

6.1.3 消息队列模式：官方模式全集与默认值

除了重置策略，消息如何在会话中排队也会影响实际体验。OpenClaw 官方队列模式包含 collect、steer、followup、steer-backlog 和 interrupt，且默认值为 collect。

[!WARNING] 早期版本中常见的 queue 模式仅为 steer 的别名（legacy alias），并非排队的默认推荐模式。请避免在配置中继续使用 queue 作为模式值。

官方支持的主要队列模式：

• collect（默认）：智能体在处理当前消息时，新消息会被收集并排队，处理完上一条后才处理下一条。优点是逻辑简单、不会打断正在执行的任务。

• steer：新消息会实时注入到智能体正在处理的上下文中，智能体会根据新消息立刻调整方向。适合需要人机协作、持续纠偏的场景。

• followup/steer-backlog/interrupt：分别对应追加、积压引导与硬中断等更细分的并发控制语义（具体以官方文档为准）。

以下是一个可直接使用的排队配置示例：

// ~/.openclaw/openclaw.json
{
  messages: {
    queue: {
      mode: "collect",      // 默认值（官方）
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: {
        telegram: "collect",
        discord: "collect",
      },
    },
  },
}

[!TIP] 若经常需在智能体执行过程中修改方向（例如“先别搜了，换个关键词”），建议针对该渠道单开 steer 模式。若主要处理独立长任务且不希望被打断，保持默认的 collect 模式即可。

6.1.4 DM 会话隔离与多用户模式（安全视角）

当 OpenClaw 作为共享助手机器人（例如在 Telegram 或 WhatsApp 上面向多个不同用户开放 DM 私聊）时，理解 DM 会话隔离的安全性至关重要：

• 隔离是针对请求和记忆的：默认情况下，每个 DM 会话（例如 agent:main:telegram:dm:user_A 和 agent:main:telegram:dm:user_B）各自维护独立的 Token 窗口、历史记录与临时上下文。用户 A 看不到用户 B 和机器人的私聊历史。

• 但宿主机资源是共享的：由于同一个 Gateway 和同一个 Agent 面对的是同一套底层宿主机环境（如文件系统、Shell），如果工具策略（Tool Policy）不对权限做沙箱化限制，用户 A 依然可以通过让模型“读取宿主机文件”变相窥探到系统内的全局信息或用户 B 写入的某个临时文件。

安全模式（Secure DM mode）推荐做法：如果面向多 untrusted 用户，必须禁止他们使用 group:runtime 等高危工具，并将文件读写限制在严格的沙箱或各自独立的挂载卷内。详情参见 官方 Security 文档。

6.1.5 会话状态的双层存储机制

OpenClaw 的会话状态数据默认按智能体存储在 ~/.openclaw/agents/<agentId>/sessions/ 目录下。官方允许用 session.store 覆盖目录位置。根据底层设计，会话状态分为两层分开存储：

• Session Store (sessions.json)：主要存储会话的元数据（如 sessionId、Token 计数、压缩次数等）。这部分数据是轻量级的，即便由于意外被手动修改，也能被 Gateway 安全重建。

• Transcript (<sessionId>.jsonl)：追加式的对话历史记录（JSONL 格式）。包含了原始消息、工具调用记录以及压缩后的摘要内容。

配置示例：

{
  session: {
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
  },
}

建议：会话存储目录进入备份与审计范围；但不要把敏感内容原样同步到不可信位置，必要时启用脱敏或最小化日志。

[!TIP] 避坑：/new 命令会让你失去记忆吗？ 很多新手误以为执行 /new 命令会让当前的 AI 助手完全“失忆”。实际上，该命令仅仅是创建了一个全新的 sessionId 并清空了当前的 临时对话上下文（Transcript）。磁盘上持久化的记忆文件（如 MEMORY.md）依然存活，它们会在这个新会话中 被自动重新加载。

6.1.6 排障案例：跨渠道串话的排查过程

具体例子：用户 A 在 Telegram 提问，却收到了用户 B 在 WhatsApp 的对话上下文

某天运维收到反馈：“我问的是部署问题，但机器人回复了一段关于财务报表的内容。”排查过程如下：

1. 定位会话键：在日志中筛选用户 A 的请求，发现其 sessionKey 为 agent:main:telegram:dm:alice_tg。

2. 检查身份链接：发现 identityLinks 配置中错误地把用户 A 的 Telegram ID 和用户 B 的 WhatsApp ID 链接为同一身份：

{
  session: {
    identityLinks: {
      // 错误！alice 和 bob 被错误地绑定到同一身份
      alice: ["telegram:alice_tg_id", "whatsapp:bob_wa_id"],
    },
  },
}

1. 根因确认：由于身份链接错误，用户 B 在 WhatsApp 的对话历史被注入到用户 A 的上下文中。

2. 修复：修正 identityLinks，确保每个 identity 下只有同一个人的多渠道 ID。修复后重启，用 status --deep 验证。

排障教训：identityLinks 是会话系统的“身份合并开关”，配置错误会直接导致隐私泄露级别的串话。建议把 identityLinks 纳入变更审核清单。

6.1.7 排障命令：用状态与日志定位串话与重置异常

当出现“串话”“突然忘记上下文”“一直不重置”等问题，优先用系统自检与结构化日志定位。

# 查看整体状态（--deep 会做更深的探测）

openclaw status --deep

# 追踪日志，按需加上 --json 便于 jq 过滤

openclaw logs --follow --json

操作示例：在日志中筛选同一会话键的事件流，确认是否出现“一个会话被多个身份写入”。字段名以实际日志为准。

cat runtime.log | jq -r 'select(.type=="log") | .log | select(.sessionKey=="agent:main:whatsapp:dm:[phone]") | [.ts,.trace_id,.event,.from] | @tsv' | tail