5.14 会话详解

核心概念核心概念

OpenClaw 的会话系统将与 Agent 的直接对话视为基本单元。本文档详细介绍会话管理的核心原理和配置方法。

核心原理

OpenClaw 的会话系统采用基于密钥的架构：

  • 直接消息：映射到 agent:<agentId>:<mainKey>（通常为 "main"）
  • 群组聊天：接收隔离的会话密钥

会话作用域控制

dmScope 参数决定直接消息的组织方式：

  • main（默认）：所有直接消息跨设备共享一个连续会话
  • per-peer：按频道内的发送者 ID 隔离
  • per-channel-peer：按频道加发送者隔离（适合共享收件箱）
  • per-account-channel-peer：按账户、频道和发送者隔离

identityLinks 配置可将特定提供商的对等 ID 映射到规范身份，使同一个人可以跨多个平台共享会话。

权限结构

"所有会话状态都由网关（'主' OpenClaw）拥有。" UI 客户端查询网关获取会话数据，而不是读取本地文件。这种集中式方法确保了远程部署的一致性。

文件组织

会话数据存储在网关主机上的以下位置：

~/.openclaw/agents/<agentId>/sessions/

存储文件将会话密钥映射到元数据，单独的 JSONL 记录文件捕获对话历史。

会话生命周期管理

会话根据可配置的策略进行重置：

  • 每日重置：默认为当地时间凌晨 4:00
  • 空闲重置：可选的滑动窗口（与每日重置比较评估；以先到期者为准触发更新）
  • 手动触发：/new 和 /reset 命令开始新会话
  • 按类型覆盖：分别自定义直接消息、群组和线程的重置行为

检查命令

使用以下命令监控会话：

# 显示存储位置和最近活动
openclaw status

# 导出所有条目为 JSON 格式
openclaw sessions --json

# 在聊天中检查 Agent 可用性和上下文使用情况
/status
提示
完整的会话管理文档请参考 官方英文文档。