OpenClaw 的多渠道会话管理机制是其架构中的核心部分。理解渠道（Channel）、Agent 和会话（Session）三层架构，以及 SessionKey 与 SessionId 的区别，是掌握 OpenClaw 上下文管理和故障排查的关键。

一、OpenClaw 的三层架构

OpenClaw 的架构分为三个核心层次：

1. 渠道层：消息传输管道

渠道层负责将各个平台（如飞书、Discord、Telegram）的消息传输到 OpenClaw Gateway。

channels:
  feishu:
    enabled: true
    appId: "cli_xxx"
    appSecret: "xxx"

作用：接收外部消息并转发给 Gateway，不处理业务逻辑。类比：快递员，只负责送货。

2. Agent 层：AI 大脑

Agent 是处理消息的核心，拥有独立的配置、工具和人格。

agents:
  list:
    - id: "main"
      workspace: "~/.openclaw/workspace"
      model:
        primary: "deepseek/deepseek-chat"

作用：接收消息、调用工具、生成回复。类比：客服，负责思考并回答问题。

3. Session 层：对话上下文

Session 层管理对话的历史记录和上下文。每个用户或群组拥有独立的 SessionKey（如 agent:main:feishu:user123）。

二、SessionKey 与 SessionId 的区别

这是最容易混淆的概念：

• SessionKey（会话键）：标识对话的"身份"，长期不变。类比：客户档案编号。
• SessionId（会话ID）：标识会话的"版本"（如 v1, v2），可能随时间变化。类比：档案版本号。

关键行为：当会话因空闲过期（默认 24 小时）或自动重置（如每日凌晨 4 点）时，SessionKey 保持不变，但会创建新的 SessionId。新 SessionId 不包含旧版本的上下文历史，但旧历史仍保存在磁盘上。

三、会话清理机制

为防止历史记录无限累积，OpenClaw 提供了多种清理策略：

1. 空闲过期（Idle Expiry）

session:
  idleMinutes: 1440  # 24 小时无活动后过期

超过设定时间无新消息，下次对话时创建新 SessionId。默认值为 0（禁用）。

2. 自动重置（Auto Reset）

session:
  reset:
    mode: "daily"
    atHour: 4  # 每天凌晨 4 点重置

3. 会话存储维护（Maintenance）

session:
  maintenance:
    mode: "enforce"
    pruneAfter: "30d"    # 清理 30 天前的条目
    maxEntries: 500     # 最多 500 个会话
    maxDiskBytes: "1gb" # 磁盘预算

4. 自动压缩（Compaction）

当上下文接近限制时，自动将旧消息压缩为摘要，减少发送给模型的 Token 数。完整历史仍保留在磁盘上。

四、如何找回历史对话

• 网页版：在会话选择器中查找（显示最近 7 天内最多 50 个会话）。
• 命令行：openclaw sessions list 列出会话，openclaw sessions export 导出历史。
• 手动切换：在网页版输入 /session agent:main:dashboard-abc。

五、推荐配置

如果希望会话长期保留上下文（不频繁断开）：

session:
  dmScope: "per-channel-peer"
  idleMinutes: 0       # 禁用空闲过期
  reset:
    mode: "off"        # 禁用自动重置
  maintenance:
    mode: "enforce"
    pruneAfter: "30d"
    maxEntries: 500

agents:
  defaults:
    compaction:
      enabled: true    # 启用自动压缩

总结

关键要点：UI 上看着是一个对话框，但实际可能对应多个 SessionId；新 SessionId 不包含旧历史，但旧历史仍在磁盘上可找回。