会话管理

会话管理 💬

会话是 OpenClaw 管理对话上下文的核心机制。

🎯 什么是会话？

会话是一次对话的上下文容器：

• 记录对话历史
• 保持用户偏好
• 跟踪任务状态
• 隔离不同对话

┌─────────────────────────────────────┐
│            会话 A                    │
│  ┌─────────┐    ┌───────────────┐  │
│  │ 用户A   │◄──►│  AI 代理      │  │
│  │         │    │  - 历史记录   │  │
│  │ "你好"  │    │  - 用户偏好   │  │
│  │ "帮我"  │    │  - 任务状态   │  │
│  └─────────┘    └───────────────┘  │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│            会话 B                    │
│  ┌─────────┐    ┌───────────────┐  │
│  │ 群组    │◄──►│  AI 代理      │  │
│  │         │    │  - 不同历史   │  │
│  │ 用户B,C │    │  - 群设定     │  │
│  │ @机器人 │    │  - 独立状态   │  │
│  └─────────┘    └───────────────┘  │
└─────────────────────────────────────┘

🏗️ 会话类型

1. 私信会话 (DM)

一对一对话：

• 用户 ↔️ AI 代理
• 完全隐私
• 个性化设置

会话 ID 格式：

agent:main:whatsapp:dm:+8613800138000
agent:main:telegram:dm:123456789
agent:main:discord:dm:987654321

2. 群组会话

多人对话：

• 多个用户 ↔️ AI 代理
• 共享上下文
• 提及触发

群组会话 ID：

agent:main:whatsapp:group:group-id-here
agent:main:telegram:group:-1001234567890
agent:main:discord:guild:123456789:channel:987654321

3. 频道会话

广播频道：

• 单向或有限互动
• 大范围发布
• 特定权限控制

🔧 会话配置

基本配置

{
  session: {
    // 默认会话设置
    defaults: {
      maxHistory: 20,      // 保留消息数
      timeout: 600,        // 超时时间（秒）
      persist: true        // 是否持久化
    },

    // 清理策略
    cleanup: {
      enabled: true,
      interval: 3600,      // 每小时检查
      maxAge: 86400        // 24小时后清理
    }
  }
}

私信会话配置

{
  session: {
    dm: {
      maxHistory: 50,      // 私信保留更多历史
      timeout: 1800,       // 30分钟超时
      autoReset: false,    // 不自动重置

      // 特定用户例外
      overrides: {
        "+8613800138000": {
          maxHistory: 100  // VIP 用户更多历史
        }
      }
    }
  }
}

群组会话配置

{
  session: {
    group: {
      maxHistory: 30,
      timeout: 300,        // 5分钟超时（群组更快）
      mentionOnly: true,   // 仅提及触发

      // 群组特定设置
      settings: {
        "group-id-1": {
          mentionOnly: false,  // 这个群组不需要提及
          maxHistory: 50
        }
      }
    }
  }
}

🧠 会话状态

状态类型

┌──────────┐    ┌──────────┐    ┌──────────┐
│  空闲    │───►│  活跃    │───►│  休眠    │
└──────────┘    └──────────┘    └──────────┘
    ▲                              │
    └──────────────────────────────┘
         (新消息唤醒)

状态	说明	特点
空闲	等待消息	内存占用低
活跃	正在对话	完全加载
休眠	超时未用	保存到磁盘

状态转换

// 状态转换示例
session.on('message', () => {
  if (session.state === 'idle') {
    session.activate();  // 空闲 -> 活跃
  }
  session.resetTimer();   // 重置超时
});

session.on('timeout', () => {
  session.hibernate();    // 活跃 -> 休眠
});

session.on('newMessage', () => {
  if (session.state === 'hibernating') {
    session.wake();       // 休眠 -> 活跃
  }
});

📜 会话历史

历史记录结构

interface SessionHistory {
  messages: [
    {
      role: "user" | "assistant" | "system",
      content: string,
      timestamp: Date,
      metadata: {
        platform: "whatsapp" | "telegram" | "discord",
        messageId: string,
        userId?: string
      }
    }
  ],
  summary?: string,        // 对话摘要
  context?: any           // 额外上下文
}

历史管理

添加消息：

session.addMessage({
  role: "user",
  content: "你好",
  userId: "user123"
});

session.addMessage({
  role: "assistant",
  content: "你好！有什么我可以帮你的？"
});

获取历史：

const history = session.getHistory({
  limit: 10,           // 最近10条
  includeSystem: true  // 包含系统消息
});

清空历史：

# 命令行
openclaw session reset <session-id>

# 或发送消息
/reset

🎭 会话上下文

上下文类型

1. 对话上下文

{
  "currentTopic": "Python编程",
  "userIntent": "学习循环",
  "pendingTask": "解释for循环"
}

2. 用户偏好

{
  "language": "zh-CN",
  "responseStyle": "detailed",
  "expertise": "beginner"
}

3. 任务状态

{
  "activeTask": "code-review",
  "progress": 50,
  "data": { "file": "main.py" }
}

上下文持久化

保存到磁盘：

{
  session: {
    persistence: {
      enabled: true,
      storage: "local",     // local / redis / database
      path: "~/.openclaw/sessions",
      format: "json"        // json / sqlite
    }
  }
}

🔐 会话安全

隔离机制

会话 A                    会话 B
┌─────────┐              ┌─────────┐
│ 历史    │    ◄──►      │ 历史    │
│ 互相    │   不共享     │ 互相    │
│ 独立    │              │ 独立    │
└─────────┘              └─────────┘

• 会话间数据完全隔离
• 用户只能访问自己的会话
• 群组会话成员可见性可控

访问控制

{
  session: {
    accessControl: {
      // 谁可以访问会话
      rules: [
        {
          sessionPattern: "*:dm:*",
          allowedUsers: ["owner"]
        },
        {
          sessionPattern: "*:group:*",
          allowedUsers: ["members"],
          mentionOnly: true
        }
      ]
    }
  }
}

📊 会话监控

查看活跃会话

# 列出所有会话
openclaw session list

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

# 查看会话统计
openclaw session stats

会话统计信息

活跃会话: 15
├─ 私信会话: 10
├─ 群组会话: 4
└─ 频道会话: 1

今日消息: 1,234
平均响应时间: 1.2s
内存使用: 256MB

🧹 会话清理

自动清理

{
  session: {
    cleanup: {
      enabled: true,

      // 清理策略
      strategies: [
        {
          name: "timeout",
          condition: "lastActivity > 1 hour",
          action: "hibernate"
        },
        {
          name: "expired",
          condition: "age > 7 days",
          action: "delete"
        },
        {
          name: "storage",
          condition: "totalSize > 1GB",
          action: "archive"
        }
      ]
    }
  }
}

手动清理

# 清理特定会话
openclaw session clean <session-id>

# 清理所有休眠会话
openclaw session clean --hibernated

# 清理7天前的会话
openclaw session clean --older-than 7d

# 强制清理所有（谨慎！）
openclaw session clean --all --force

🔄 会话恢复

从休眠恢复

// 自动恢复
session.wake();

// 恢复后恢复上下文
await session.restoreContext();

从备份恢复

# 备份会话
openclaw session backup <session-id>

# 恢复会话
openclaw session restore backup-file.json

💡 最佳实践

1. 历史管理

• 私信保留 50-100 条
• 群组保留 20-30 条
• 定期清理旧会话

2. 超时设置

• 私信：30分钟-1小时
• 群组：5-10分钟
• 频道：立即休眠

3. 持久化策略

• 重要会话立即保存
• 普通会话定期批量保存
• 临时会话不保存

4. 隐私保护

• 敏感数据不持久化
• 用户退出时清理会话
• 加密存储历史记录

🆘 常见问题

会话丢失

原因：

• 网关重启
• 配置错误
• 存储故障

解决：

# 检查存储
openclaw doctor --check-sessions

# 恢复备份
openclaw session restore

上下文混乱

原因：

• 会话未正确隔离
• 历史记录污染
• 多用户混淆

解决：

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

# 或发送
/reset

内存占用高

原因：

• 会话过多
• 历史太长
• 未清理休眠会话

解决：

# 清理休眠会话
openclaw session clean --hibernated

# 调整配置
openclaw config set session.cleanup.enabled true

📚 相关文档

• 架构概述
• AI 代理
• 网关配置
• 故障排除