I. 核心架构 - 4. Session 管理

📍 课程位置

阶段：I. 核心架构
课序：第 4 课
前置知识：I-3. Context 管理
后续课程：I-5. Memory 系统

---

🎯 本课核心问题

如果你问我：“如果两个人同时跟我聊天，Agent 会不会搞混？如果我换个设备，Agent 还能记得之前聊了什么吗？”

我会这样回答：这就涉及到 Session（会话）管理——它是 Agent 区分"谁是谁"的关键机制。

---

📚 Session 是什么？

简单的定义

Session = 一个独立的对话上下文

类比：

• 就像微信的对话框
• 每个对话框是独立的
• 不会把 A 和 B 的消息混在一起

Session 的组成

Session =
  Session ID（唯一标识）+
  对话历史（Messages）+
  状态信息（Metadata）+
  用户身份（Identity）

---

🔑 Session 的核心概念

1. Session ID（会话 ID）

是什么：每个 Session 的唯一标识

格式：

• 类似：110f8c36-ab91-4f10-8ae0-2ad68728742f
• 由 Gateway 自动生成

作用：

• 用来"找到"这个会话
• 用来"恢复"这个会话

2. Session Key（会话键）

是什么：用来路由消息到正确 Session 的标识

格式：

• peer:<peerId> - 某个用户
• channel:<channelId> - 某个频道
• guild:<guildId> - 某个群
• account:<accountId> - 某个账户

例子：

whatsapp:+1234567890 → Session A
telegram:123456789 → Session B
discord:guild123:channel456 → Session C

3. DM Scope（范围策略）

是什么：决定"多大范围内共享一个 Session"

4 种级别：

级别	说明	例子
main	所有人共享一个 Session	所有人都是同一个对话
per-peer	每个用户一个 Session	A 和 B 是不同会话
per-channel-peer	每个用户+频道一个 Session	A 在 WhatsApp 和 Telegram 是分开的
per-account-channel-peer	最细粒度	每个账户、每个频道、每个用户独立

类比：

• main = 只有一个群，大家都在里面
• per-peer = 每个人单独开对话框
• per-channel-peer = 每个人在每个平台单独对话框
• per-account-channel-peer = 每个人在每个平台的不同账号单独对话框

4. Session Reset（会话重置）

是什么：定期"清空"对话历史

两种方式：

Daily Reset（每日重置）：

• 每天某个时间点清空
• 适合：不需要记住太久远的对话

Idle Reset（空闲重置）：

• 超过一定时间没有活动就清空
• 适合：节省资源

---

🔐 安全性：DM 隔离（重要！）

什么是 DM 隔离？

DM = Direct Message（私聊）

在多用户环境下，如果不做好隔离，A 说的话可能会被 B 看到——这是严重的安全问题！

为什么 DM 隔离这么重要？

场景：

• 你有多个用户
• 用户 A 说：“我的密码是 123”
• 用户 B 也在这个系统里
• 如果 DM 隔离没做好 → 用户 B 可能看到用户 A 的密码

如何配置 DM 隔离？

{
  "session": {
    // 关键配置！
    "dmScope": "per-channel-peer",  // 推荐：每个用户+频道独立
    
    // 还可以配置：
    "reset": {
      "mode": "daily",       // 每天重置
      "atHour": 4,           // 凌晨 4 点
      "idleMinutes": 120     // 空闲 2 小时后重置
    }
  }
}

dmScope 的安全等级

dmScope	安全等级	适用场景
main	❌ 危险	绝对不要用于多用户
per-peer	⚠️ 一般	小团队，互相信任
per-channel-peer	✅ 推荐	多用户，通用场景
per-account-channel-peer	✅ 最安全	多账户，复杂场景

---

🔧 实战：管理 Session

查看 Session 列表

# 查看当前有哪些 Session
openclaw sessions list

# 查看某个 Session 的详情
openclaw sessions show <sessionId>

# 查看 Session 文件
ls -la ~/.openclaw/agents/main/sessions/

管理 Session

# 重置某个 Session
openclaw sessions reset <sessionId>

# 删除某个 Session
openclaw sessions delete <sessionId>

# 创建一个新的 Session
openclaw sessions create

配置 Session 策略

{
  "session": {
    // DM 隔离策略（最重要！）
    "dmScope": "per-channel-peer",
    
    // Session 重置策略
    "reset": {
      "mode": "daily",       // daily | idle | manual
      "atHour": 4,           // 每天几点重置
      "idleMinutes": 120,    // 空闲多久重置（分钟）
      "maxAgeHours": 0       // 最大存活时间，0=不限
    },
    
    // 线程绑定（用于 Discord 等平台）
    "threadBindings": {
      "enabled": true,
      "idleHours": 24,
      "maxAgeHours": 0
    }
  }
}

---

⚠️ 常见陷阱

陷阱	表现	原因	解决
消息混乱	A 收到 B 的消息	dmScope 设置为 main	改为 per-channel-peer
记忆丢失	Agent "失忆"了	Session 被重置	调整 reset 策略
Session 太多	系统变慢	累积了太多 Session	设置过期清理
隐私泄露	看到别人的消息	DM 隔离配置不当	检查 dmScope 设置

---

📝 学习心得

我学这一课时的体会

我以前觉得 Session 就是"保存对话"的功能，没太在意。

学完后才知道，DM 隔离是多用户场景下的生死线！如果配置错了，会导致严重的隐私泄露。

最让我震惊的是：

• dmScope: "main" 是危险的
• 很多安全问题都是因为这个配置错了
• 一定要用 per-channel-peer 或更细的级别

与其他课程的关联

• 前置课程：Context 管理 - Session 存储历史
• 后续课程：Memory 系统 - 长期记忆
• 配合课程：Multi-Agent - 多 Agent 的 Session 隔离

---

✅ 你现在应该理解的

• 解释 Session 是什么
• 说出 Session ID 和 Session Key 的区别
• 解释 4 种 dmScope 的区别
• 知道为什么 DM 隔离很重要
• 能配置基本的 Session 参数

---

📚 快速参考表

概念	简单说
Session	一个独立的对话上下文
Session ID	对话的唯一标识符
Session Key	用来路由消息的标识
dmScope	决定多大范围共享 Session
Daily Reset	每天固定时间清空对话
Idle Reset	空闲一段时间后清空

---

🔗 相关资源

官方文档：

• Session 管理：https://docs.openclaw.ai/concepts/session
• Multi-Agent：https://docs.openclaw.ai/concepts/multi-agent

相关课程：

• 上一课：I-3. Context 管理
• 下一课：I-5. Memory 系统

---

📊 本课总结

最关键的 3 点：

1. Session = 对话上下文

   • 每个 Session 独立存储
   • Session ID 唯一标识

2. dmScope 是安全关键

   • 多用户必须设置正确
   • 建议用 per-channel-peer

3. Reset 策略

   • Daily：每天定时清空
   • Idle：空闲后清空
   • 根据需求选择

---

现在你应该理解了如何区分"谁是谁"。下一课会讲更长期的"记忆"（Memory 系统）。