5.12 会话管理

核心概念核心概念

OpenClaw 的会话管理系统负责协调多个对话会话的状态存储、权限控制和生命周期管理。

核心概念

会话管理涵盖以下几个关键方面:

作用域与权限

会话系统采用分层的权限模型:

  • 网关权限: 控制哪些代理可以访问特定会话
  • 状态存储: 会话状态持久化在磁盘上的 *.jsonl 文件中
  • 内存刷新: 在压缩前自动保存关键上下文到工作区

会话裁剪

会话裁剪是一种内存管理机制,在 LLM 调用前修剪旧的工具结果,但不会修改磁盘历史记录。裁剪特性:

  • 仅在使用 Anthropic API 且模式为 "cache-ttl" 时运行
  • 当距离上次调用超过配置的 TTL (生存时间) 时触发
  • 提高缓存效率,减少 TTL 后的 cacheWrite 大小
  • 重置 TTL 窗口,跳过图片、用户/助手消息和受保护的助手内容

生命周期管理

OpenClaw 追踪每个会话的完整生命周期:

  • 创建: 初始化新会话及其元数据
  • 活动: 处理消息交换和状态更新
  • 休眠: 长时间不活动后进入低功耗状态
  • 终止: 清理资源并持久化最终状态

配置示例

{
  "session": {
    // 会话裁剪配置
    "pruning": {
      "mode": "cache-ttl",  // 启用基于缓存 TTL 的裁剪
      "ttl": "5m",          // 5分钟生存时间
      "keepLastAssistants": 3,  // 保留最后3条助手消息
      "softTrimRatio": 0.3,     // 软修剪阈值 30%
      "hardClearRatio": 0.5,    // 硬清除阈值 50%
      "minPrunableToolChars": 50000  // 最小可裁剪工具字符数
    },
    
    // 发送策略
    "sendPolicy": {
      "allowedTargets": ["main", "group"],  // 允许的目标会话类型
      "requirePermission": true             // 需要权限验证
    }
  }
}

会话裁剪高级配置

{
  "session": {
    "pruning": {
      "softTrim": {
        "maxChars": 4000,     // 保留的最大字符数
        "headChars": 1500,    // 保留开头字符数
        "tailChars": 1500     // 保留结尾字符数
      },
      "hardClear": {
        "enabled": true,
        "placeholder": "[旧工具结果内容已清除]"
      },
      "toolFilters": {
        "allow": ["read", "write"],  // 白名单:仅裁剪这些工具
        "deny": ["bash"]              // 黑名单:永不裁剪这些工具 (优先级更高)
      }
    }
  }
}

常用命令

# 列出所有会话
openclaw session list

# 查看特定会话历史
openclaw session history <session-id>

# 向另一个会话发送消息
openclaw session send <target-session> "消息内容"

# 创建新的子会话
openclaw session spawn --kind group --name "我的群组"

# 检查会话状态
openclaw status --sessions

会话类型

OpenClaw 支持多种会话类型:

  • main: 主对话会话
  • group: 群组会话,支持多个参与者
  • cron: 定时任务会话
  • hook: 事件钩子会话
  • node: 节点会话,用于分布式场景

内存刷新机制

在压缩操作前,OpenClaw 自动执行"内存刷新":

  • 将关键上下文保存到工作区的 memory/ 目录
  • 确保重要信息不会在压缩过程中丢失
  • 支持自定义内存提取策略
注意
会话裁剪只影响传递给 LLM 的内存内容,永远不会修改磁盘上的 *.jsonl 历史记录文件。所有原始对话数据都会被完整保留。
最佳实践
  • 根据实际使用场景调整 TTL 值,避免过于频繁的裁剪
  • 使用 toolFilters 保护关键工具输出不被裁剪
  • 定期使用 /compact 命令压缩长时间运行的会话
  • 通过 /status 监控会话的 token 使用情况

相关概念