会话管理

Session（会话）是 Agent 与用户交互的有状态容器。每个会话维护独立的对话历史、上下文与配置。

会话基础

核心规则

每个 Agent 对每个用户维护一个直接聊天（DM）会话。群组会话按群组 ID 独立创建。

会话键（Session Keys）

会话通过唯一的 Session Key 标识：

# 直接消息（DM）会话
agent::<peer-id>

# 群组会话
agent:::<group-id>:<peer-id>

DM 会话示例

general::user_12345
coder::telegram_67890
writer::whatsapp_11111

群组会话示例

general:::group_dev_team:user_12345
coder:::group_code_review:telegram_67890

会话状态存储

sessions.json

会话元数据保存在 sessions.json 中：

{
  "general::user_12345": {
    "sessionKey": "general::user_12345",
    "agentName": "general",
    "peerId": "user_12345",
    "channel": "telegram",
    "createdAt": "2025-01-15T08:00:00Z",
    "lastActiveAt": "2025-01-15T10:30:00Z",
    "messageCount": 42,
    "model": "openai/gpt-4o"
  }
}

JSONL 转录

对话历史以 JSONL（JSON Lines）格式存储：

~/.openclaw/sessions/general::user_12345/transcript.jsonl

每行一条消息记录：

{"role":"user","content":"你好","timestamp":1705305600000}
{"role":"assistant","content":"你好！有什么可以帮助你的吗？","timestamp":1705305601500}

DM 作用域（dmScope）

dmScope 控制直接消息会话的隔离粒度：

模式	说明	会话键示例
main	所有 DM 共享一个会话	agent::main
per-peer	每个用户独立会话	agent::user123
per-channel-peer	每个渠道+用户独立	agent::telegram:user123
per-account-channel-peer	每个账号+渠道+用户独立	agent::acc1:telegram:user123

# 配置 DM 作用域
dmScope: per-peer  # 推荐：每个用户独立会话

选择建议

• 个人使用 → main（一个会话即可）
• 多用户服务 → per-peer（每个用户独立上下文）
• 多渠道运营 → per-channel-peer（同一用户在不同渠道独立）

会话重置

会话可通过以下方式重置：

自动重置

# 每日凌晨 4 点自动重置
sessionReset:
  daily: "04:00"
  
# 或基于空闲时间重置
sessionReset:
  idleTimeout: 3600  # 空闲 1 小时后重置（秒）

手动重置

# 用户命令
/new     # 创建新会话
/reset   # 重置当前会话

重置影响

会话重置会清除内存中的对话历史，但 JSONL 转录文件会保留。长期记忆（MEMORY.md）不受影响。

会话覆写（Overrides）

可按消息类型或渠道覆写会话配置：

# 全局默认
model: openai/gpt-4o
maxTokens: 4096

# 按渠道覆写
overrides:
  telegram:
    model: anthropic/claude-3-5-sonnet
    maxTokens: 8192
  whatsapp:
    model: deepseek/deepseek-chat
    maxTokens: 2048
    blockStreamingDefault: true

会话维护

修剪旧条目

定期清理过期会话以释放存储空间：

maintenance:
  pruneAfterDays: 30     # 30 天未活跃的会话自动清理
  maxSessions: 1000       # 最大会话数量

文件轮转

JSONL 转录文件按大小轮转：

transcriptRotation:
  maxFileSize: 10MB       # 单文件最大大小
  maxFiles: 5             # 保留的历史文件数

数量上限

sessions:
  maxPerAgent: 500        # 每个 Agent 最大会话数
  maxPerUser: 10          # 每个用户最大会话数

会话生命周期

创建                   活跃                   重置/过期
Created  ─────────▶  Active  ─────────────▶  Reset
   │                    │                      │
   ▼                    ▼                      ▼
初始化会话状态     处理消息、更新历史     清除历史、保留转录
分配 Session Key   更新 lastActiveAt      可选保留 MEMORY.md

🇨🇳 中国用户须知

• 会话重置时间建议设置为北京时间凌晨（配合 timezone: Asia/Shanghai）
• 如在国内部署，建议适当增加 maxSessions 以应对高并发场景
• JSONL 文件支持中文内容，无需额外编码配置

下一步

• 了解 会话修剪 的详细清理策略
• 查看 会话工具 了解内置管理命令
• 探索 压缩机制 了解上下文摘要