OpenClaw Sessions 系统：AI 对话的记忆管理大师引言：为什么需要 Sessions 系统？想象你正在

引言：为什么需要 Sessions 系统？

想象你正在和朋友聊天：

没有记忆的对话：

你："昨天我问你的那个问题，结果如何？"
朋友："什么问题？我不记得了。"
你："就是关于 Python 的那个..."
朋友："抱歉，我完全不记得我们聊过 Python。"

有记忆的对话：

你："昨天我问你的那个问题，结果如何？"
朋友："哦，你说的是那个 Python 脚本优化的问题吧！我研究了一下..."
你："太好了！那关于性能测试的部分呢？"
朋友："对对，我们之前讨论到了多线程方案..."

OpenClaw 的 Sessions 系统就是 AI 的"记忆系统"：

🧠 记住对话历史：AI 知道你们之前聊过什么
🔒 隔离不同对话：工作群和家庭群的对话不会混在一起
💾 持久化存储：重启服务器后对话历史还在
🗂️ 智能管理：自动清理旧对话，节省存储空间
🔄 灵活重置：可以随时开始新对话
👥 多人支持：每个人都有自己独立的对话记录

第一部分：Sessions 系统解决什么问题？

1.1 问题场景

问题 1：对话没有记忆

第一天：
你："帮我写个 Python 脚本处理 CSV 文件"
AI："好的，这是脚本..."

第二天：
你："继续优化昨天的脚本"
AI（没有 Sessions）："什么脚本？我不记得昨天的对话。"
❌ 每次都要重新解释

AI（有 Sessions）："当然，我记得昨天的 CSV 处理脚本，让我优化一下..."
✅ 对话连续，上下文完整

问题 2：不同对话混在一起

你在多个群组：
- 家庭群聊天
- 工作群讨论项目
- 朋友群闲聊

❌ 没有隔离：
  家庭群："AI，今天晚饭吃什么？"
  AI："关于项目进度，我建议..."
  （错乱！AI 把工作群的上下文带到家庭群了）

✅ 有隔离：
  家庭群："AI，今天晚饭吃什么？"
  AI："根据你的口味，我推荐..."

  工作群："AI，项目进度如何？"
  AI："根据我们之前讨论的计划..."

  （每个群独立的对话历史，互不干扰）

问题 3：对话历史无限增长

对话 1000 轮后：
- 对话记录占用 500MB 磁盘空间
- 每次 AI 回复都要加载所有历史
- 响应越来越慢
- Token 成本越来越高
- 最终：内存溢出 ❌

✅ 需要智能管理：
  - 自动清理旧对话
  - 压缩不重要的历史
  - 重要信息保存到 Memory
  - 保持系统高性能

问题 4：多设备/多渠道对话连续性

场景：你在多个平台和 AI 聊天

早上（WhatsApp）："帮我查一下北京的天气"
AI："北京今天晴天，25°C"

中午（Telegram）："那明天呢？"
❌ 没有连续性：AI 不知道你在问什么
✅ 有连续性：AI 知道你在继续问北京天气

晚上（Discord）："谢谢，我知道了"
AI："不客气！如果还需要查询其他城市的天气，随时告诉我。"

1.2 Sessions 系统的解决方案

Sessions 系统提供 6 大核心能力：

✅ 1. 对话记忆管理

每个 Session 包含：
- 完整的对话历史
- 用户偏好设置（思考模式、详细程度）
- 模型选择（Opus、Sonnet、Haiku）
- Token 使用统计
- 压缩次数记录

效果：

AI 记住之前说过的话
上下文连续，无需重复解释
可以引用历史内容

✅ 2. 智能隔离策略

4 种隔离策略：

1. main（默认）
   → 所有直接消息共享一个 Session
   适合：单用户，多设备

2. per-peer
   → 按发送者隔离，跨渠道共享
   适合：多用户，跨平台连续性

3. per-channel-peer（推荐）
   → 按渠道+发送者隔离
   适合：多用户，强隔离

4. per-account-channel-peer
   → 按账号+渠道+发送者隔离
   适合：多账号场景

效果：

灵活选择隔离级别
防止对话串话
保护隐私和安全

✅ 3. 自动重置机制

3 种重置策略：

1. 定时重置（daily）
   → 每天凌晨 4 点自动开始新对话

2. 空闲重置（idle）
   → 超过 2 小时不活跃自动重置

3. 混合模式
   → 定时 + 空闲，哪个先到触发哪个

效果：

自动清理旧对话
保持对话新鲜
防止上下文过载

✅ 4. 持久化存储

两层存储架构：

Layer 1：sessions.json（索引）
- 轻量级元数据
- 快速查找
- 记录会话状态

Layer 2：<sessionId>.jsonl（内容）
- 完整对话记录
- JSONL 格式（每行一条消息）
- 高效追加写入

效果：

重启服务器对话不丢失
高效读写
可以随时恢复对话

✅ 5. 资源管理

自动维护：
- 清理超过 30 天的旧 Session
- 限制最多 500 个活跃 Session
- 压缩超大对话记录
- 归档已删除的 Session
- 磁盘空间预算控制

效果：

系统不会爆满
性能始终稳定
成本可控

✅ 6. 跨 Session 通信

支持：
- Agent 之间互相发消息
- 生成子 Session 并行处理任务
- Session 之间传递信息

效果：

多个 AI 协作
并行处理复杂任务
工作流自动化

第二部分：Session 的基本概念

2.1 什么是 Session？

Session = 一个独立的对话容器

Session 包含：

┌────────────────────────────────────┐
│ Session Key（唯一标识）            │
│ agent:main:whatsapp:direct:+155... │
├────────────────────────────────────┤
│ 元数据（sessions.json）            │
│ - sessionId: "abc-123-def"         │
│ - updatedAt: 1234567890            │
│ - inputTokens: 50000               │
│ - outputTokens: 30000              │
│ - thinkingLevel: "medium"          │
│ - modelOverride: "opus-4"          │
├────────────────────────────────────┤
│ 对话记录（abc-123-def.jsonl）      │
│ [用户] 你好                        │
│ [AI] 你好！有什么可以帮助你的？    │
│ [用户] 写个 Python 脚本            │
│ [AI] 当然，这是脚本...             │
│ [工具] read("script.py")           │
│ [工具结果] [文件内容]              │
│ [AI] 已经生成好了...               │
└────────────────────────────────────┘

2.2 Session Key 规则

Session Key 决定对话是否共享历史记录。

直接消息（DM）

策略 1：main（默认）

Session Key: agent:main:main

所有渠道的 DM 共享同一个 Session：
WhatsApp  ─┐
Telegram  ─┼→ 同一个对话历史
Discord   ─┘

适合：单用户多设备

策略 2：per-peer

Session Key: agent:main:direct:<peerId>

按发送者隔离，跨渠道共享：

Alice 的消息：
  WhatsApp  ─┐
  Telegram  ─┼→ agent:main:direct:alice
  Discord   ─┘

Bob 的消息：
  WhatsApp  ─┐
  Telegram  ─┼→ agent:main:direct:bob
  Discord   ─┘

适合：多用户，跨平台连续性
需要配置 identityLinks 告诉系统哪些 ID 属于同一个人

策略 3：per-channel-peer（推荐）

Session Key: agent:main:<channel>:direct:<peerId>

按渠道 + 发送者隔离：

Alice 的消息：
  WhatsApp  → agent:main:whatsapp:direct:alice
  Telegram  → agent:main:telegram:direct:alice
  Discord   → agent:main:discord:direct:alice

适合：多用户，强隔离（推荐）

策略 4：per-account-channel-peer

Session Key: agent:main:<accountId>:<channel>:direct:<peerId>

按账号 + 渠道 + 发送者隔离：

Alice 发到：
  个人 WhatsApp  → agent:main:personal:whatsapp:direct:alice
  工作 WhatsApp  → agent:main:work:whatsapp:direct:alice

适合：多账号场景（最细粒度）

群组消息

群组消息永远独立，不受 dmScope 影响：

Session Key: agent:main:<channel>:group:<groupId>

WhatsApp 群 A  → agent:main:whatsapp:group:120363...@g.us
WhatsApp 群 B  → agent:main:whatsapp:group:120364...@g.us
Telegram 群 C  → agent:main:telegram:group:-1001234567890

每个群独立对话历史 ✅

线程消息

Discord/Slack 线程：

Session Key: agent:main:<channel>:channel:<id>:thread:<threadId>

主频道：agent:main:discord:channel:123456
线程 1：agent:main:discord:channel:123456:thread:789
线程 2：agent:main:discord:channel:123456:thread:101

Telegram 论坛话题：

Session Key: agent:main:telegram:group:<id>:topic:<topicId>

群组：agent:main:telegram:group:-1001234:topic:0
话题 1：agent:main:telegram:group:-1001234:topic:42
话题 2：agent:main:telegram:group:-1001234:topic:99

2.3 身份链接（Identity Links）

告诉系统哪些平台 ID 属于同一个人：

{
  "session": {
    "dmScope": "per-peer",
    "identityLinks": {
      "alice": [
        "telegram:123456789",
        "discord:987654321012345678",
        "whatsapp:+15551234567"
      ],
      "bob": [
        "telegram:987654321",
        "signal:+15559876543"
      ]
    }
  }
}

效果：

Alice 在不同平台发消息：

Telegram："我昨天问的那个问题..."
→ Session: agent:main:direct:alice

Discord（第二天）："继续昨天的话题"
→ Session: agent:main:direct:alice（同一个！）
→ AI 可以访问 Telegram 的对话历史 ✅

WhatsApp："谢谢，已经解决了"
→ Session: agent:main:direct:alice
→ AI 知道你在感谢之前的帮助 ✅

第三部分：Session 生命周期

3.1 Session 创建

触发时机：第一次收到消息

1. 用户发消息 → Routing 系统解析
2. 生成 Session Key（根据路由规则）
3. 检查 Session 是否存在
4. 不存在 → 创建新 Session
   - 生成 sessionId（UUID）
   - 创建 sessions.json 条目
   - 创建 .jsonl 文件
5. 存在 → 检查是否需要重置
   - 检查重置策略
   - 如果需要重置 → 归档旧 Session，创建新的
   - 如果不需要 → 继续使用

示例：

第一次对话：
用户："你好"
系统：
  1. 生成 Session Key: agent:main:whatsapp:direct:+15551234567
  2. 创建新 Session
  3. sessionId = "abc-123-def-456"
  4. 写入 sessions.json
  5. 创建 abc-123-def-456.jsonl
  6. 记录对话："[用户] 你好"

AI 回复："你好！有什么可以帮助你的？"
系统：
  - 追加到 abc-123-def-456.jsonl
  - 更新 sessions.json（updatedAt、Token 统计）

3.2 Session 重置

自动重置（3 种策略）

策略 1：定时重置（daily）

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4  // 每天凌晨 4 点
    }
  }
}

工作原理：

今天凌晨 4 点之前：
用户："继续昨天的项目"
AI："好的，我记得昨天我们讨论的..."
（使用现有 Session）

今天凌晨 4 点之后：
用户："继续昨天的项目"
系统：检测到跨越了重置边界
  1. 归档旧 Session（abc-123.reset.1234567890.jsonl）
  2. 创建新 Session（xyz-789）
  3. 保留用户偏好（思考模式、模型选择）

AI："早上好！开始新的一天。你想继续昨天的项目吗？"
（新的 Session，但记得用户偏好）

策略 2：空闲重置（idle）

{
  "session": {
    "reset": {
      "mode": "idle",
      "idleMinutes": 120  // 2 小时不活跃
    }
  }
}

工作原理：

10:00 AM：用户："帮我写个脚本"
10:30 AM：用户："继续优化"
（Session 活跃，继续使用）

12:40 PM：用户："测试一下"
系统：检测到距离上次活跃（10:30 AM）已过 2 小时 10 分钟
  1. 触发空闲重置
  2. 归档旧 Session
  3. 创建新 Session

AI："好的，我们开始新的对话。需要什么帮助？"

策略 3：混合模式（daily + idle）

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    }
  }
}

工作原理：哪个条件先满足就触发哪个

情况 1：凌晨 4 点到了（定时触发）
  → 自动重置

情况 2：超过 2 小时不活跃（空闲触发）
  → 自动重置

情况 3：凌晨 3 点，距离上次活跃 3 小时
  → 空闲重置触发（早于定时重置）

按对话类型重置

不同类型的对话可以有不同的重置策略：

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    },
    "resetByType": {
      "direct": {
        "mode": "idle",
        "idleMinutes": 240  // DM：4 小时不活跃重置
      },
      "group": {
        "mode": "idle",
        "idleMinutes": 60   // 群组：1 小时不活跃重置
      },
      "thread": {
        "mode": "daily",
        "atHour": 4         // 线程：每天重置
      }
    }
  }
}

按渠道重置

不同渠道可以有不同的重置策略：

{
  "session": {
    "resetByChannel": {
      "discord": {
        "mode": "idle",
        "idleMinutes": 10080  // Discord：1 周不活跃重置
      },
      "telegram": {
        "mode": "daily",
        "atHour": 6           // Telegram：每天早上 6 点重置
      }
    }
  }
}

手动重置

用户命令：
- /new        → 开始新对话（带欢迎消息）
- /reset      → 重置对话（带欢迎消息）
- /new opus   → 重置并切换到 Opus 模型
- /new 继续昨天的项目 → 重置并发送消息

效果：
1. 归档当前 Session
2. 创建新 Session
3. 保留用户偏好（思考模式、模型选择等）
4. 可选：发送欢迎消息或用户指定的消息

3.3 Session 归档

当 Session 重置时，旧的对话记录会被归档：

原始文件：
  abc-123-def-456.jsonl

重置后归档：
  abc-123-def-456.reset.1234567890.jsonl
  （文件名加上 .reset.<时间戳>）

保留时间：
  默认 14 天（可配置 resetArchiveRetention）

自动清理：
  超过 14 天自动删除归档文件

3.4 Session 维护

自动维护机制确保系统健康运行：

维护配置

{
  "session": {
    "maintenance": {
      "mode": "enforce",      // "warn" 或 "enforce"
      "pruneAfter": "30d",    // 清理超过 30 天的旧 Session
      "maxEntries": 500,      // 最多保留 500 个 Session
      "rotateBytes": "10mb",  // sessions.json 超过 10MB 时轮换
      "resetArchiveRetention": "14d",  // 归档文件保留 14 天
      "maxDiskBytes": "1gb",  // 磁盘空间上限（可选）
      "highWaterBytes": "800mb"  // 清理后的目标大小
    }
  }
}

维护流程

自动执行（每次写入 sessions.json 时检查）：

1. 清理过期 Session
   → 删除超过 30 天未活跃的 Session

2. 限制 Session 数量
   → 如果超过 500 个，删除最旧的

3. 归档孤儿文件
   → 找到 .jsonl 文件但不在 sessions.json 中的
   → 移动到 .deleted.<时间戳>.jsonl

4. 清理旧归档
   → 删除超过 14 天的 .reset.* 和 .deleted.* 文件

5. 轮换索引文件
   → sessions.json 超过 10MB
   → 备份为 sessions.json.1, .2, ...
   → 创建新的 sessions.json（只保留活跃 Session）

6. 磁盘空间控制（可选）
   → 计算总磁盘使用量
   → 超过 1GB → 删除文件直到降到 800MB
   → 删除顺序：归档文件 → 孤儿文件 → 最旧 Session

手动维护

# 查看需要清理的内容（不实际删除）
openclaw sessions cleanup --dry-run

# 执行清理
openclaw sessions cleanup --enforce

# 清理特定 Agent
openclaw sessions cleanup --agent work --enforce

# 清理所有 Agent
openclaw sessions cleanup --all-agents --enforce

# JSON 输出（用于脚本）
openclaw sessions cleanup --dry-run --json

第四部分：配置 Sessions 系统

4.1 基础配置

最简单的配置（单用户）

{
  "session": {
    "dmScope": "main",  // 所有 DM 共享一个 Session
    "reset": {
      "mode": "daily",
      "atHour": 4       // 每天凌晨 4 点重置
    }
  }
}

适合：

个人使用
想要跨设备/跨渠道连续性
不需要严格隔离

高级配置（企业级）

{
  "session": {
    "dmScope": "per-account-channel-peer",
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 480  // 8 小时
    },
    "resetByType": {
      "direct": {
        "mode": "idle",
        "idleMinutes": 480
      },
      "group": {
        "mode": "idle",
        "idleMinutes": 120
      }
    },
    "resetByChannel": {
      "discord": {
        "mode": "idle",
        "idleMinutes": 10080  // 1 周
      }
    },
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "7d",      // 更激进的清理
      "maxEntries": 1000,
      "maxDiskBytes": "5gb",
      "highWaterBytes": "4gb"
    },
    "sendPolicy": {
      "rules": [
        {
          "action": "deny",
          "match": {
            "channel": "discord",
            "chatType": "group"
          }
        }
      ],
      "default": "allow"
    }
  }
}

适合：

大规模部署
多账号管理
精细化控制

4.2 身份链接配置

{
  "session": {
    "dmScope": "per-peer",
    "identityLinks": {
      "alice": [
        "telegram:123456789",
        "discord:987654321012345678",
        "whatsapp:+15551234567",
        "signal:+15551234567"
      ],
      "bob": [
        "telegram:987654321",
        "whatsapp:+15559876543"
      ],
      "carol": [
        "discord:111222333444555666",
        "slack:U01234567"
      ]
    }
  }
}

效果：

Alice 在 4 个平台的消息共享同一个 Session
Bob 在 2 个平台的消息共享同一个 Session
Carol 在 2 个平台的消息共享同一个 Session
Alice、Bob、Carol 之间完全隔离

4.3 发送策略配置

阻止特定类型的 Session 发送消息：

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "action": "deny",
          "match": {
            "channel": "discord",
            "chatType": "group"  // 禁止 Discord 群组发送
          }
        },
        {
          "action": "deny",
          "match": {
            "keyPrefix": "cron:"  // 禁止定时任务发送
          }
        }
      ],
      "default": "allow"
    }
  }
}

运行时覆盖（用户命令）：

/send on      → 允许当前 Session 发送
/send off     → 禁止当前 Session 发送
/send inherit → 恢复配置默认值

第五部分：实战场景

场景 1：个人助手（单用户）

需求：

我一个人使用
在 WhatsApp、Telegram、Discord 都和 AI 聊天
希望对话在所有平台连续

配置：

{
  "session": {
    "dmScope": "main",  // 所有 DM 共享
    "reset": {
      "mode": "daily",
      "atHour": 4
    },
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "30d",
      "maxEntries": 100
    }
  }
}

效果：

早上（WhatsApp）：
你："帮我写个 Python 脚本处理 CSV"
AI："好的，这是脚本..."
[Session: agent:main:main]

中午（Telegram）：
你："继续优化早上的脚本"
AI："当然，我记得早上的 CSV 处理脚本..."
[Session: agent:main:main]（同一个！）

晚上（Discord）：
你："那个脚本已经测试通过了，谢谢！"
AI："太好了！还需要其他帮助吗？"
[Session: agent:main:main]

✅ 跨平台连续性
✅ 完整的上下文
✅ 每天自动重置，保持新鲜

场景 2：家庭共用（多用户）

需求：

4 个家庭成员共用一个 OpenClaw
每人都用 WhatsApp 和 Telegram
希望每人有独立的对话历史

配置：

{
  "session": {
    "dmScope": "per-peer",  // 按发送者隔离
    "identityLinks": {
      "dad": [
        "telegram:111111111",
        "whatsapp:+15551111111"
      ],
      "mom": [
        "telegram:222222222",
        "whatsapp:+15552222222"
      ],
      "kid1": [
        "telegram:333333333",
        "whatsapp:+15553333333"
      ],
      "kid2": [
        "telegram:444444444",
        "whatsapp:+15554444444"
      ]
    },
    "reset": {
      "mode": "idle",
      "idleMinutes": 240  // 4 小时不活跃重置
    }
  }
}

效果：

爸爸（Telegram）：
"帮我分析股票走势"
[Session: agent:main:direct:dad]

妈妈（WhatsApp）：
"今晚做什么菜好？"
[Session: agent:main:direct:mom]

孩子 1（Telegram）：
"什么是光合作用？"
[Session: agent:main:direct:kid1]

第二天，爸爸（WhatsApp）：
"继续昨天的股票分析"
AI："好的，我记得昨天我们分析的几只股票..."
[Session: agent:main:direct:dad]（跨平台连续）

✅ 每人独立对话历史
✅ 跨平台连续性（通过 identityLinks）
✅ 4 小时不活跃自动重置
✅ 完全隔离，互不干扰

场景 3：客服系统（高并发）

需求：

WhatsApp 客服账号，每天处理 1000+ 对话
需要严格隔离每个客户
自动清理旧对话，节省空间

配置：

{
  "session": {
    "dmScope": "per-channel-peer",  // 严格隔离
    "reset": {
      "mode": "idle",
      "idleMinutes": 120  // 2 小时不活跃重置
    },
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "7d",      // 7 天后清理
      "maxEntries": 2000,      // 最多 2000 个活跃 Session
      "maxDiskBytes": "10gb",  // 磁盘上限 10GB
      "highWaterBytes": "8gb"  // 清理后降到 8GB
    }
  }
}

效果：

客户 A 第一次咨询（10:00 AM）：
"你们的产品怎么购买？"
[Session: agent:main:whatsapp:direct:+15551111111]
AI："您可以通过..."

客户 A 继续咨询（10:30 AM）：
"有优惠吗？"
AI："根据我们刚才讨论的产品..."
[同一个 Session，上下文连续]

客户 B 同时咨询（10:15 AM）：
"退货流程是什么？"
[Session: agent:main:whatsapp:direct:+15552222222]
[完全独立，与客户 A 隔离]

客户 A 再次咨询（1:00 PM）：
"我想购买刚才说的产品"
[距离上次活跃超过 2 小时]
[触发空闲重置，创建新 Session]
AI："您好！需要什么帮助？"
（虽然是新 Session，但 AI 可以通过 Memory 查找历史）

自动维护（每天执行）：
- 删除超过 7 天的旧 Session
- 保持 Session 数量 ≤ 2000
- 磁盘使用控制在 10GB 以内

✅ 高并发支持（2000+ 并发对话）
✅ 自动清理，系统永不爆满
✅ 严格隔离，防止客户信息泄露
✅ 空闲重置，释放资源

场景 4：项目团队（多群组）

需求：

5 个项目，每个项目一个 WhatsApp 群
每个群独立对话
群组 2 小时不活跃自动重置
DM 保持长期连续性

配置：

{
  "session": {
    "dmScope": "per-channel-peer",
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 480  // DM：8 小时
    },
    "resetByType": {
      "group": {
        "mode": "idle",
        "idleMinutes": 120  // 群组：2 小时
      }
    },
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "14d",
      "maxEntries": 200
    }
  }
}

效果：

项目 Alpha 群（10:00 AM）：
成员："@ai 当前进度如何？"
AI："根据我们之前的讨论，目前..."
[Session: agent:main:whatsapp:group:120363111111111111@g.us]

项目 Beta 群（10:15 AM）：
成员："@ai 遇到一个 bug"
AI："让我看看..."
[Session: agent:main:whatsapp:group:120363222222222222@g.us]
（独立 Session，与 Alpha 群隔离）

项目 Alpha 群（1:00 PM）：
成员："@ai 继续讨论"
[距离上次活跃超过 2 小时]
[触发空闲重置]
AI："你好！有什么可以帮助的？"
（新的 Session，上下文重置）

项目经理 DM（任意时间）：
"汇总所有项目进度"
[Session: agent:main:whatsapp:direct:+15551234567]
（独立的 DM Session，8 小时空闲重置）
AI："好的，让我查看各项目状态..."

✅ 每个群独立对话
✅ 群组 2 小时自动重置（避免上下文过载）
✅ DM 长期连续性（8 小时）
✅ 自动清理 14 天旧对话

场景 5：Discord 社区（线程管理）

需求：

Discord 服务器有 100+ 讨论线程
每个线程独立对话
线程 1 周不活跃自动重置
主频道每天重置

配置：

{
  "session": {
    "resetByType": {
      "channel": {
        "mode": "daily",
        "atHour": 4  // 主频道每天重置
      },
      "thread": {
        "mode": "idle",
        "idleMinutes": 10080  // 线程：1 周（7 天 × 24 小时 × 60 分钟）
      }
    },
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "30d",
      "maxEntries": 500
    }
  }
}

效果：

主频道 #general：
用户："@bot 欢迎新成员"
[Session: agent:main:discord:channel:123456]
（每天凌晨 4 点重置）

线程 1（技术讨论）：
用户："@bot 这个 API 怎么用？"
[Session: agent:main:discord:channel:123456:thread:789]
AI："这个 API 的用法是..."

用户（3 天后）："继续之前的讨论"
AI："好的，我记得我们之前讨论的 API..."
（同一个线程 Session，1 周内保持连续）

线程 2（另一个讨论）：
用户："@bot 帮我审查代码"
[Session: agent:main:discord:channel:123456:thread:101]
（独立 Session，与线程 1 隔离）

✅ 主频道每天重置，保持新鲜
✅ 线程长期连续性（1 周）
✅ 每个线程独立对话
✅ 自动清理 30 天旧 Session

场景 6：多账号客服（细粒度隔离）

需求：

3 个 WhatsApp 账号（个人、工作、客服）
每个账号的每个用户独立 Session
最细粒度隔离

配置：

{
  "agents": {
    "list": [
      { "id": "personal", "workspace": "~/agents/personal" },
      { "id": "work", "workspace": "~/agents/work" },
      { "id": "support", "workspace": "~/agents/support" }
    ]
  },
  "bindings": [
    { "agentId": "personal", "match": { "channel": "whatsapp", "accountId": "personal" } },
    { "agentId": "work", "match": { "channel": "whatsapp", "accountId": "work" } },
    { "agentId": "support", "match": { "channel": "whatsapp", "accountId": "support" } }
  ],
  "session": {
    "dmScope": "per-account-channel-peer",  // 最细粒度
    "reset": {
      "mode": "idle",
      "idleMinutes": 240
    }
  }
}

效果：

个人账号，朋友 Alice：
[Session: agent:personal:personal:whatsapp:direct:alice]

工作账号，同事 Alice：
[Session: agent:work:work:whatsapp:direct:alice]

客服账号，客户 Alice：
[Session: agent:support:support:whatsapp:direct:alice]

✅ 即使是同名用户（Alice），不同账号完全隔离
✅ 每个账号使用不同的 Agent（不同的"大脑"）
✅ 工作空间、Memory、配置完全独立

第六部分：高级特性

6.1 上下文压缩（Compaction）

问题：对话越来越长，Token 成本越来越高

解决方案：自动压缩旧对话

{
  "agents": {
    "defaults": {
      "compaction": {
        "enabled": true,
        "reserveTokens": 16384,     // 为下次回复预留的空间
        "keepRecentTokens": 20000   // 保留最近 20K Token 不压缩
      }
    }
  }
}

工作原理：

对话进行到 150K Token：

原始对话：
  [消息 1-50] ← 旧消息（50K Token）
  [消息 51-100] ← 中间消息（50K Token）
  [消息 101-150] ← 最近消息（50K Token）

上下文窗口：200K Token
已使用：150K Token
预留：16K Token（为下次回复）
剩余：34K Token（不够了！）

触发压缩：
  1. 保留最近 20K Token（消息 135-150）
  2. 将旧消息总结为简短摘要（消息 1-134）
     "之前的对话讨论了 Python 脚本开发、数据库优化、
      API 设计等话题。用户偏好使用 Flask 框架..."

压缩后：
  [摘要] ← 5K Token
  [消息 135-150] ← 最近消息（20K Token）

总计：25K Token（节省了 125K Token！）

6.2 预压缩记忆刷新（Memory Flush）

问题：压缩会丢失重要信息

解决方案：压缩前自动保存重要信息到 Memory

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,  // 距离压缩 4K Token 时触发
          "forceFlushTranscriptBytes": "2mb",  // 文件超过 2MB 强制触发
          "prompt": "压缩前，请将重要信息保存到 memory/"
        }
      }
    }
  }
}

工作流程：

步骤 1：检测即将压缩
  当前 Token：194K
  上下文窗口：200K
  预留空间：16K
  距离阈值：200K - 16K - 4K = 180K
  当前超过？194K > 180K → 是！触发 Memory Flush

步骤 2：静默记忆刷新轮次
  系统："压缩前，请将重要信息保存到 memory/"
  AI（静默）：
    - 使用 write 工具写入 memory/2024-01-15.md
    - 写入重要决策、待办事项、关键上下文
    - 回复 NO_REPLY（不发送给用户）

步骤 3：正常压缩
  现在可以安全压缩旧对话了，因为重要信息已保存

步骤 4：后续查询
  用户："我们之前讨论的那个决策是什么？"
  AI：
    - 使用 memory_search 查询
    - 找到 memory/2024-01-15.md
    - 读取之前保存的决策
    - 回答用户

✅ 重要信息不会丢失
✅ 用户无感知（静默执行）
✅ 压缩后仍可查询历史

6.3 跨 Session 通信

方式 1：Agent 之间发消息

// Agent A 给 Agent B 发消息
sessions_send({
  sessionKey: "agent:work:main",
  message: "项目 X 的进度如何？",
  timeoutSeconds: 60
})

流程：

Agent A（personal）：
  1. 调用 sessions_send 工具
  2. 消息发送到 Agent B（work）

Agent B（work）：
  1. 收到消息
  2. 处理请求
  3. 回复："项目 X 进度：80% 完成，预计下周交付"

Agent A（personal）：
  1. 收到回复
  2. 继续处理或告知用户

可配置：
- maxPingPongTurns：最多来回几轮（0-5）
- 回复 REPLY_SKIP：停止来回
- 回复 ANNOUNCE_SKIP：不通知自己的渠道

方式 2：生成子 Session

// 生成子 Session 并行处理任务
sessions_spawn({
  task: "分析日志文件并提取错误",
  agentId: "work",
  model: "claude-sonnet-4-5",
  thread: true,  // 请求线程绑定
  mode: "run",   // 运行模式："run" 或 "session"
  cleanup: "delete"  // 完成后："delete" 或 "keep"
})

流程：

主 Session（agent:main:main）：
  1. 用户："同时分析 3 个日志文件"
  2. 主 AI 决定并行处理
  3. 生成 3 个子 Session

子 Session 1（agent:main:subagent:abc-123）：
  - 任务：分析 log1.txt
  - 独立执行（工具受限）
  - 完成后回传结果

子 Session 2（agent:main:subagent:def-456）：
  - 任务：分析 log2.txt
  - 并行执行

子 Session 3（agent:main:subagent:ghi-789）：
  - 任务：分析 log3.txt
  - 并行执行

主 Session：
  1. 收到 3 个子 Session 的结果
  2. 汇总
  3. 告知用户："已分析完成，共发现 15 个错误..."

自动清理：
  - 60 分钟后自动归档子 Session（可配置）

✅ 并行处理，速度快
✅ 独立隔离，不影响主对话
✅ 自动清理，不占空间

6.4 沙箱 Session

不同类型的 Session 可以有不同的安全级别：

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",  // 仅非主 Session 沙箱化
        "scope": "session",  // 每个 Session 独立容器
        "workspaceAccess": "none"  // 群组 Session 无文件访问
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["group:messaging"],
        "deny": ["group:fs", "group:runtime"]
      }
    }
  }
}

效果：

主 Session（DM）：
  - 不沙箱化
  - 完整工具访问
  - 主机直接执行

群组 Session：
  - 沙箱化（Docker 容器）
  - 受限工具（不能访问文件系统）
  - 隔离执行

✅ DM 完全信任（你自己的对话）
✅ 群组受限（多人环境，更安全）
✅ 单个"大脑"，双重安全姿态

第七部分：最佳实践

7.1 选择正确的隔离策略

场景	推荐策略	原因
个人使用，多设备	`dmScope: "main"`	跨平台连续性
多用户共用	`dmScope: "per-channel-peer"`	严格隔离，防止串话
多账号场景	`dmScope: "per-account-channel-peer"`	最细粒度隔离
跨平台身份统一	`dmScope: "per-peer"` + `identityLinks`	平衡隔离和连续性

7.2 设置合理的重置策略

场景	推荐策略	配置
个人助手	定时重置	`mode: "daily", atHour: 4`
客服系统	空闲重置	`mode: "idle", idleMinutes: 120`
长期项目	混合模式	`mode: "daily", idleMinutes: 480`
短期任务	激进空闲	`mode: "idle", idleMinutes: 60`

7.3 维护配置建议

低频使用（个人）

{
  "session": {
    "maintenance": {
      "mode": "warn",      // 仅警告
      "pruneAfter": "90d",  // 3 个月
      "maxEntries": 100
    }
  }
}

中等频率（小团队）

{
  "session": {
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "30d",
      "maxEntries": 500,
      "rotateBytes": "10mb"
    }
  }
}

高频使用（企业）

{
  "session": {
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "7d",
      "maxEntries": 2000,
      "maxDiskBytes": "10gb",
      "highWaterBytes": "8gb",
      "rotateBytes": "5mb"
    }
  }
}

7.4 性能优化建议

1. 控制 Session 数量

✅ 推荐：
- 个人：< 100 个活跃 Session
- 小团队：< 500 个
- 企业：< 2000 个

❌ 避免：
- 超过 5000 个（写入性能下降）
- 无限增长（最终崩溃）

2. 定期清理

# 每周运行一次
openclaw sessions cleanup --enforce

# 或配置 cron 自动执行
0 2 * * 0 openclaw sessions cleanup --enforce --all-agents

3. 监控磁盘使用

# 查看磁盘使用情况
du -sh ~/.openclaw/agents/*/sessions

# 查看 Session 数量
openclaw sessions --json | jq 'length'

# 查看最大 Session
openclaw sessions --json | jq 'max_by(.inputTokens + .outputTokens)'

7.5 安全建议

1. 多用户场景必须隔离

{
  "session": {
    "dmScope": "per-channel-peer"  // ✅ 必须
    // "dmScope": "main"            // ❌ 危险！会混淆对话
  }
}

2. 限制 Session 工具可见性

{
  "tools": {
    "sessions": {
      "visibility": "tree"  // ✅ 只能看到自己和子 Session
      // "visibility": "all"  // ❌ 危险！可以访问所有 Session
    }
  }
}

3. 群组使用沙箱

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",  // ✅ 群组沙箱化
        "workspaceAccess": "none"  // ✅ 群组无文件访问
      }
    }
  }
}

总结

🎯 Sessions 系统的核心价值

问题	解决方案
❌ 对话没有记忆	✅ 完整的对话历史管理
❌ 不同对话混在一起	✅ 灵活的隔离策略（4 种）
❌ 对话历史无限增长	✅ 自动压缩、清理、维护
❌ 多设备不连续	✅ 跨平台对话连续性
❌ 重启后对话丢失	✅ 持久化存储（JSONL）
❌ 资源管理混乱	✅ 智能维护和预算控制

🚀 关键特性

4 种隔离策略
- main：跨平台共享
- per-peer：按人隔离
- per-channel-peer：按渠道+人隔离（推荐）
- per-account-channel-peer：最细粒度
3 种重置模式
- 定时重置（daily）
- 空闲重置（idle）
- 混合模式（daily + idle）
自动维护
- 清理过期 Session
- 限制数量上限
- 归档孤儿文件
- 磁盘空间预算
高级特性
- 上下文压缩（Compaction）
- 预压缩记忆刷新（Memory Flush）
- 跨 Session 通信
- 沙箱 Session
生产就绪
- 原子写入锁
- 并发控制
- 性能优化
- 灾难恢复

💡 使用建议

新手入门：

{
  "session": {
    "dmScope": "main",
    "reset": { "mode": "daily", "atHour": 4 }
  }
}

多用户场景：

{
  "session": {
    "dmScope": "per-channel-peer",
    "reset": { "mode": "idle", "idleMinutes": 240 },
    "maintenance": { "mode": "enforce", "pruneAfter": "30d" }
  }
}

企业场景：

{
  "session": {
    "dmScope": "per-account-channel-peer",
    "reset": { "mode": "daily", "idleMinutes": 480 },
    "resetByType": { "group": { "mode": "idle", "idleMinutes": 120 } },
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "7d",
      "maxDiskBytes": "10gb"
    }
  }
}

🎓 深入学习

Sessions 系统是 OpenClaw 的记忆核心，掌握它可以让你：

✅ 实现完美的对话连续性
✅ 构建多用户/多账号系统
✅ 优化性能和成本
✅ 保证数据安全和隐私
✅ 打造专业级企业应用

开始配置你的 Sessions 系统吧！ 🚀

OpenClaw Sessions 系统：AI 对话的记忆管理大师

引言：为什么需要 Sessions 系统？

第一部分：Sessions 系统解决什么问题？

1.1 问题场景

问题 1：对话没有记忆

问题 2：不同对话混在一起

问题 3：对话历史无限增长

问题 4：多设备/多渠道对话连续性

1.2 Sessions 系统的解决方案

✅ 1. 对话记忆管理

✅ 2. 智能隔离策略

✅ 3. 自动重置机制

✅ 4. 持久化存储

✅ 5. 资源管理

✅ 6. 跨 Session 通信

第二部分：Session 的基本概念

2.1 什么是 Session？

2.2 Session Key 规则

直接消息（DM）

群组消息

线程消息

2.3 身份链接（Identity Links）

第三部分：Session 生命周期

3.1 Session 创建

3.2 Session 重置

自动重置（3 种策略）

按对话类型重置

按渠道重置

手动重置

3.3 Session 归档

3.4 Session 维护

维护配置

维护流程

手动维护

第四部分：配置 Sessions 系统

4.1 基础配置

最简单的配置（单用户）

推荐配置（多用户）

高级配置（企业级）

4.2 身份链接配置

4.3 发送策略配置

第五部分：实战场景

场景 1：个人助手（单用户）

场景 2：家庭共用（多用户）

场景 3：客服系统（高并发）

场景 4：项目团队（多群组）

场景 5：Discord 社区（线程管理）

场景 6：多账号客服（细粒度隔离）

第六部分：高级特性

6.1 上下文压缩（Compaction）

6.2 预压缩记忆刷新（Memory Flush）

6.3 跨 Session 通信

方式 1：Agent 之间发消息

方式 2：生成子 Session

6.4 沙箱 Session

第七部分：最佳实践

7.1 选择正确的隔离策略

7.2 设置合理的重置策略

7.3 维护配置建议

低频使用（个人）

中等频率（小团队）

高频使用（企业）

7.4 性能优化建议

1. 控制 Session 数量

2. 定期清理

3. 监控磁盘使用

7.5 安全建议

1. 多用户场景必须隔离

2. 限制 Session 工具可见性

3. 群组使用沙箱

总结

🎯 Sessions 系统的核心价值

🚀 关键特性

💡 使用建议

🎓 深入学习