6.1 会话模型与状态持久化

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

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

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

典型选择思路。

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

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

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

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

概念	配置字段	默认值	别名或补充说明
私聊归并键	session.dmScope	direct	用于定义单对单私聊的合并策略；旧版中常被称为 direct 模式（现多统称为 main 或根据具体版本设定）。
会话重置策略	session.resetByType	无统一默认	常按 dm (私聊), group (群聊), thread (话题贴) 三类做精细化时效配置。
会话身份绑定	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", atHour: 4, idleMinutes: 60 },
    resetByType: {
      dm: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
      thread: { mode: "daily", atHour: 4 },
    },
    resetTriggers: ["/new", "/reset"],
  },
}

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

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 会话状态的双层存储机制

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.5 排障案例：跨渠道串话的排查过程

具体例子：用户 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.6 排障命令：用状态与日志定位串话与重置异常

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

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

openclaw status --deep

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

openclaw logs --follow --json

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

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