上篇回顾

第15篇 〖OpenClaw系列〗Agent 身份与提示词工程

我们设计了 Agent 的人格：通过 SOUL.md 定义角色、性格、能力、边界。但人格需要「记忆」来延续——这就是会话管理的核心价值。

本文将解决：

1. 会话的生命周期与状态管理
2. 长会话的上下文维护
3. 会话重置与恢复策略

阅读建议：本文偏内部机制。如果你只需要配置会话行为（隔离级别、重置时间），请直接跳到第3篇的「第四条橙带：session」章节，3分钟搞定。本文适合需要理解「为什么这样配」以及排查会话异常的读者。

会话基础概念

什么是会话

会话（Session）是用户与 Agent 之间的一系列连续交互：

• 包含对话历史（messages）
• 维护上下文状态
• 支持跨时间延续

会话 Key 格式

每个会话有唯一的标识符：

agent:{agentId}:{channel}:{chatType}:{peerId}

示例：
- agent:main:telegram:direct:123456789
- agent:coding:slack:channel:general
- agent:writing:webchat:direct:abc123

把这串看似复杂的 Key 拆开，每段含义就一目了然：

会话生命周期

状态流转

会话从创建到归档，一共会经历 4 种状态，状态之间的迁移由”消息触发”和”超时/重置”两类事件驱动：

下面这段伪代码图就是上图的文字版，对照着看更清楚：

Created（创建）
    ↓ 首次消息
Active（活跃）
    ↓ 空闲超时 / 重置触发
Idle（空闲） → Reset（重置）
    ↓ 新消息          ↓
Active（恢复）    Created（新建）

状态详解

生命周期事件

// 来自源码 session-lifecycle-events.ts
exporttype SessionLifecycleEvent = {
  sessionKey: string;       // 会话标识
  reason: string;             // 触发原因
  parentSessionKey?: string;  // 父会话（线程）
  label?: string;             // 标签
  displayName?: string;     // 显示名称
};

会话配置详解

基础配置

{
  session: {
    // 会话范围
    scope: "per-sender",  // per-sender | global

    // DM 会话范围
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer | per-account-channel-peer

    // 空闲超时（分钟）
    idleMinutes: 120,

    // 打字间隔（秒）
    typingIntervalSeconds: 3,

    // 打字模式
    typingMode: "thinking"  // never | instant | thinking | message
  }
}

重置配置

{
  session: {
    reset: {
      // 重置模式
      mode: "idle",  // daily | idle

      // 空闲重置时间（分钟）
      idleMinutes: 120,

      // 每日重置时间（小时，0-23）
      atHour: 0
    },

    // 按类型重置
    resetByType: {
      direct: { mode: "idle", idleMinutes: 120 },
      group: { mode: "daily", atHour: 9 },
      thread: { mode: "idle", idleMinutes: 60 }
    },

    // 按渠道重置
    resetByChannel: {
      telegram: { mode: "idle", idleMinutes: 240 },
      slack: { mode: "daily", atHour: 8 }
    }
  }
}

DM 范围配置

{
  session: {
    // DM 会话范围控制
    dmScope: "per-channel-peer",

    // 身份链接（跨渠道识别同一用户）
    identityLinks: {
      "user-alice": [
        "telegram:123456789",
        "slack:U123ABC"
      ]
    }
  }
}

dmScope 选项对比：

把四档隔离粒度从粗到细排成一行，挑选时一眼能定位：

长会话的上下文维护

上下文窗口限制

上下文管理策略

当会话超出窗口限制时，OpenClaw 采取以下策略：

1. 智能裁剪：保留系统提示词和最近消息
2. 摘要压缩：将早期对话压缩为摘要
3. 分片存储：长会话分片存储，按需加载

三种策略并排放在一起，对应各自的处理动作：

配置上下文限制

{
  agents: {
    defaults: {
      params: {
        // 最大上下文长度
        maxContextTokens: 100000,

        // 保留的系统消息比例
        systemMessageReserve: 0.1,

        // 摘要触发阈值
        summaryThreshold: 80000
      }
    }
  }
}

会话重置与恢复策略

重置触发方式

四种方式触发的本质都是一次 Reset，环绕关系如下：

显式重置会话

# 重置特定会话
openclaw session reset --session-id <session-key>

# 重置所有会话
openclaw session reset --all

# 在对话中使用重置命令
/reset

会话恢复

重置后的会话可以恢复基础配置：

{
  session: {
    // 重置后保留的设置
    resetTriggers: [
      "keep-soul",      // 保留 SOUL.md
      "keep-identity",  // 保留 IDENTITY.md
      "keep-memory"     // 保留记忆
    ]
  }
}

线程会话（Thread）

支持子线程会话，用于复杂任务：

主会话: agent:main:telegram:direct:123
    ↓ 创建线程
子会话: agent:main:telegram:direct:123:thread:task-456

线程配置：

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,      // 线程空闲超时
      maxAgeHours: 168    // 线程最大存活时间（7天）
    }
  }
}

会话存储与维护

存储结构

会话不是全部塞进一个文件——它在磁盘上是分层的，每个 Agent 一个目录、每条会话一份 JSONL：

落到目录上长这样：

~/.openclaw/workspace/
└── sessions/
    ├── main/
    │   ├── sessions.json           # 会话索引
    │   ├── agent-main-xxx.jsonl    # 会话数据
    │   └── agent-main-yyy.jsonl
    ├── coding/
    │   ├── sessions.json
    │   └── agent-coding-xxx.jsonl
    └── writing/
        ├── sessions.json
        └── agent-writing-xxx.jsonl

会话维护配置

{
  session: {
    maintenance: {
      // 维护模式
      mode: "warn",  // enforce | warn

      // 自动清理旧会话
      pruneAfter: "30d",  // 30天前的会话

      // 最大会话条目数
      maxEntries: 500,

      // 会话文件大小限制
      rotateBytes: "10mb",

      // 磁盘预算
      maxDiskBytes: "500mb",
      highWaterBytes: "400mb"
    }
  }
}

手动维护会话

# 查看会话列表
openclaw sessions list

# 查看会话详情
openclaw sessions info --session-key <key>

# 导出会话
openclaw sessions export --session-key <key> --output session.json

# 清理旧会话
openclaw sessions prune --before "2026-01-01"

踩坑

坑1：会话不隔离导致信息泄露

现象：用户在 Telegram 的私密对话，在 Slack 频道被引用

原因：dmScope: "main" 导致所有 DM 共享会话

解决：

{
  session: {
    // 按渠道+用户隔离会话
    dmScope: "per-channel-peer"
  }
}

坑2：会话过长导致响应变慢

现象：长对话后，AI 回复越来越慢

原因：上下文超出窗口，触发频繁裁剪

解决：

{
  session: {
    reset: {
      mode: "idle",
      idleMinutes: 60  // 缩短超时，更频繁重置
    }
  }
}

或主动重置：

# 定期重置活跃会话
openclaw session reset --older-than 24h

坑3：重置后丢失重要上下文

现象：用户反馈”AI 忘了刚才说的”

解决：

{
  agents: {
    defaults: {
      memorySearch: {
        enabled: true,
        // 重置后从记忆中恢复上下文
        restoreOnReset: true
      }
    }
  }
}

坑4：会话文件过大占用磁盘

现象：磁盘空间不足，发现 sessions 目录很大

解决：

# 查看会话存储大小
du -sh ~/.openclaw/workspace-*/sessions/

# 配置自动清理
openclaw config set session.maintenance.mode enforce
openclaw config set session.maintenance.maxDiskBytes "200mb"

# 手动清理
openclaw sessions prune --before "30d" --confirm

FAQ

Q1: 如何查看当前会话状态？

# 查看当前活跃会话
openclaw sessions list --active

# 查看特定会话
openclaw sessions info --session-key agent:main:telegram:direct:123

# 查看会话消息数
cat ~/.openclaw/workspace/sessions/main/sessions.json | jq '.[].messageCount'

Q2: 可以跨会话共享上下文吗？

默认不能，但可以通过以下方式：

{
  agents: {
    defaults: {
      memorySearch: {
        enabled: true,
        // 跨会话共享记忆
        scope: "global"
      }
    }
  }
}

Q3: 如何备份和迁移会话？

# 备份会话
 tar -czf sessions-backup.tar.gz ~/.openclaw/workspace-*/sessions/

# 迁移到新机器
scp sessions-backup.tar.gz new-machine:~/
ssh new-machine "tar -xzf sessions-backup.tar.gz -C ~/.openclaw/"

Q4: 会话重置和删除的区别？

# 重置（推荐）
openclaw session reset --session-key <key>

# 删除（谨慎）
rm ~/.openclaw/workspace/sessions/main/agent-main-xxx.jsonl

总结

本文深入讲解了 OpenClaw 的会话管理机制：

关键认知：会话管理是「记忆」的基础设施——好的会话策略让 AI 既记得住，又不被过去束缚。

下一篇预告

第17篇：上下文裁剪与 Token 优化

深入探讨长会话的性能优化：

• Token 计算与成本控制
• 上下文裁剪策略
• 智能摘要生成
• 长文档处理技巧

本文是系列第16篇。你已掌握 OpenClaw 会话管理的完整机制。

📌 觉得有用？点个「在看」 👇 👨‍💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货 ⭐ 收藏这篇文章，作为会话管理的参考手册