OpenClaw会话管理完整教程

会话管理是 OpenClaw 用于控制智能体会话的分组、隔离、存储、生命周期及传输映射，适配多用户、多渠道、多账号的复杂使用场景。本教程严格遵循官方文档逻辑，保留所有核心配置与细节，分享一些配套实操配置示例。

一、会话基础定义

OpenClaw 对会话的核心界定的是：每个智能体的一个私聊会话视为主会话，具体分组规则如下：

1. 私聊会话：默认折叠到 agent:<agentId>:<mainKey>（mainKey 默认值为 main）；

2. 群组/频道聊天：不共享主会话，会生成独立的会话键，单独管理；

3. 核心控制：通过 session.mainKey 统一规范主会话标识，通过 session.dmScope 控制私信会话的分组逻辑（核心配置项）。

二、核心配置：dmScope 私信分组控制

dmScope 是控制私信会话如何分组的关键参数，用于适配不同使用场景（多用户、多渠道、多账号），共4种可选值，默认值为 main，具体说明如下：

配置值	核心作用	适用场景
main（默认）	所有私信共享一个主会话，保持对话连续性	单用户、单渠道使用（如个人专属智能体）
per-peer	跨渠道按「发送者 ID」隔离会话	多用户私聊，但无需区分渠道
per-channel-peer	按「渠道 + 发送者 ID」隔离会话	多用户收件箱（推荐，避免跨渠道会话混淆）
per-account-channel-peer	按「账号 + 渠道 + 发送者 ID」隔离会话	多账号收件箱（如同一渠道下多个智能体账号）

补充配置：identityLinks 跨渠道会话共享

如果同一个用户通过多个渠道（如Telegram、Discord）联系智能体，可通过 session.identityLinks 将该用户的不同渠道ID映射到同一个「规范身份」，实现跨渠道私信会话共享，避免同一个用户在不同渠道出现多个独立会话。

示例配置（映射用户Alice的多渠道ID）：

// ~/.openclaw/openclaw.
{
“session”: {
“identityLinks”: {
“alice”: [“telegram:123456789”, “discord:987654321012345678”]
}
}
}

三、安全私信模式（推荐配置）

如果你的智能体允许接收多个人的私信（如开启 dmPolicy: “open”、设置多用户配对审批或私信白名单），必须启用安全私信模式，避免不同用户的对话上下文泄露。

实操配置步骤

1. 打开 OpenClaw 核心配置文件：~/.openclaw/openclaw.；

2. 添加 dmScope 配置，设置为 per-channel-peer（推荐）：

{
“session”: {
// 安全私信模式：按渠道+发送者隔离会话，避免上下文泄露
“dmScope”: “per-channel-peer”
}
}

关键注意事项：

1. 默认 dmScope: “main”，所有私信共享主会话，仅适合单用户使用；

2. 多账号收件箱（同一渠道多个智能体账号），优先使用 per-account-channel-peer；

3. 同一用户跨渠道访问，需配合 identityLinks 配置，实现会话共享。

四、核心原则：Gateway 网关是会话的“真相来源”

所有会话状态（会话列表、令牌计数、会话历史）均由 Gateway 网关（主 OpenClaw 服务）统一管理，UI 客户端（macOS 应用、WebChat 等）需遵守以下规则：

1. 不得读取本地文件获取会话信息，必须向 Gateway 网关查询会话列表和令牌计数；

2. 远程模式下，会话存储在远程 Gateway 网关主机，而非本地设备（如你的 Mac）；

3. UI 中显示的令牌计数（inputTokens、outputTokens 等），直接来自 Gateway 网关存储，客户端不解析本地 L 记录修正计数。

五、会话状态存储位置（Gateway 网关主机）

会话相关的存储文件均位于 Gateway 网关主机的指定目录，可直接查看、修改或删除（删除后会按需重新创建），具体路径如下：

1. 核心存储文件

会话映射文件（每个智能体独立）：~/.openclaw/agents/<agentId>/sessions/sessions.

存储格式：sessionKey -> { sessionId, updatedAt, … }，记录所有会话的核心信息；

会话历史记录（每个会话独立）：~/.openclaw/agents/<agentId>/sessions/<SessionId>.l

特殊情况：Telegram 论坛主题会话，路径为 ~/.openclaw/agents/<agentId>/sessions/<SessionId>-topic-<threadId>.l。

2. 存储文件补充说明

群组会话条目：包含 displayName、channel、subject 等信息，用于 UI 中标记会话来源；
所有会话条目：包含 origin 元数据（标签 + 路由提示），用于 UI 识别会话来自哪个渠道/场景；
兼容性：OpenClaw 不读取旧版 Pi/Tau 会话文件夹，旧版会话无法直接迁移。

六、会话修剪与压缩前内存刷新

1. 会话修剪（默认启用）

OpenClaw 会在调用 LLM（大语言模型）之前，自动从内存上下文中修剪旧的工具结果，释放内存空间。

注意：此操作仅清理内存中的旧数据，不会修改或删除 L 会话历史记录。

2. 压缩前内存刷新（可选）

当会话接近自动压缩阈值时，OpenClaw 可运行静默内存刷新回合，提醒模型将持久化笔记写入磁盘（仅在工作区可写时生效）。

关联功能：需配合「内存管理」和「会话压缩」功能使用，具体可参考官方「内存」和「压缩」相关文档。

七、传输映射到会话键（核心规则）

不同类型的会话（私聊、群聊、定时任务等），会映射到不同的会话键，用于区分和隔离，核心映射规则如下：

1. 私信会话（按 dmScope 区分）

main 模式：agent:<agentId>:<mainKey>（跨设备/渠道共享会话，保持连续性）；
说明：多个电话号码、渠道可映射到同一个智能体主键，共同进入同一个对话；
per-peer 模式：agent:<agentId>:dm:<peerId>（按发送者ID隔离）；
per-channel-peer 模式：agent:<agentId>:<channel>:dm:<peerId>（按渠道+发送者隔离）；

per-account-channel-peer 模式：

agent:<agentId>:<channel>:<accountId>:dm:<peerId>（按账号+渠道+发送者隔离，accountId 默认 default）；
补充：若配置 session.identityLinks，会用「规范身份」替换 <peerId>，实现同一用户跨渠道会话共享。

2. 群聊/频道会话

群聊隔离状态：agent:<agentId>:<channel>:group:<id>；
渠道/房间会话：agent:<agentId>:<channel>:channel:<id>；
Telegram 论坛主题：在群聊ID后附加 :topic:<threadId>，即 agent:<agentId>:<channel>:group:<id>:topic:<threadId>；
兼容性：旧版 group:<id> 键仍可识别，用于迁移旧会话。

3. 其他来源会话

定时任务：cron:<job.id>；
Webhooks：hook:<uuid>（除非由钩子显式设置会话键）；
节点运行：node-<nodeId>。

八、会话生命周期（重置策略）

会话会被重复使用，直到过期；过期判断在「下一条入站消息」时触发，核心重置策略分为「默认策略」「按类型覆盖」「按渠道覆盖」，还支持手动重置。

1. 默认重置策略（全局配置）

通过 session.reset 配置，默认模式为「每日重置」，具体参数：

{
“session”: {
“reset”: {
“mode”: “daily”, // 重置模式：daily（每日）、idle（空闲）
“atHour”: 4, // 每日重置时间（Gateway 网关主机本地时间，默认凌晨4点）
“idleMinutes”: 120 // 空闲重置：滑动空闲窗口（可选，单位：分钟）
}
}
}

优先级：若同时配置「每日重置」和「空闲重置」，哪个先过期，就触发哪个；
旧版兼容：若仅设置 session.idleMinutes，未配置 session.reset/resetByType，则保持「仅空闲模式」，实现向后兼容。

2. 按类型覆盖重置（可选）

通过 session.resetByType，为「私聊（dm）、群聊（group）、线程（thread）」单独配置重置策略（thread 指 Slack/Discord 线程、Telegram 主题等）：

{
“session”: {
“resetByType”: {
“thread”: { “mode”: “daily”, “atHour”: 4 }, // 线程会话：每日凌晨4点重置
“dm”: { “mode”: “idle”, “idleMinutes”: 240 }, // 私聊会话：空闲4小时重置
“group”: { “mode”: “idle”, “idleMinutes”: 120 } // 群聊会话：空闲2小时重置
}
}
}

3. 按渠道覆盖重置（可选）

通过 session.resetByChannel，为特定渠道单独配置重置策略，优先级高于「全局重置」和「按类型重置」：

{
“session”: {
“resetByChannel”: {
“discord”: { “mode”: “idle”, “idleMinutes”: 10080 } // Discord渠道：空闲7天重置
}
}
}

4. 手动重置（实操方法）

方法1：命令触发（聊天中发送）

发送 /new 或 /reset（可在 session.resetTriggers 中添加额外触发指令），会创建新会话ID，并传递消息其余部分；
发送 /new <model>，可指定新会话的模型（支持模型别名、provider/model 或提供商名称模糊匹配）；
单独发送 /new 或 /reset，OpenClaw 会发送简短问候，确认会话已重置。

方法2：直接删除存储文件

删除 sessions. 中的特定会话条目，或删除对应会话的 L 记录；
下一条入站消息会自动重新创建会话。

5. 特殊说明

隔离的定时任务：每次运行都会创建新的 sessionId，不重用空闲会话。

九、发送策略（可选：控制会话消息传递）

通过 session.sendPolicy 配置，可阻止特定类型的会话传递，无需单独列出会话ID，核心规则如下：

实操配置示例

{
“session”: {
“sendPolicy”: {
“rules”: [
// 禁止Discord渠道的群聊会话传递
{ “action”: “deny”, “match”: { “channel”: “discord”, “chatType”: “group” } },
// 禁止定时任务会话传递
{ “action”: “deny”, “match”: { “keyPrefix”: “cron:” } },
],
“default”: “allow” // 默认允许所有会话传递
}
}
}

运行时覆盖（仅所有者可用）

在聊天中发送以下独立消息，可临时覆盖发送策略（仅对当前会话生效）：

/send on：允许当前会话传递消息；
/send off：拒绝当前会话传递消息；
/send inherit：清除临时覆盖，恢复使用配置文件中的规则。

十、完整配置示例（可直接复制使用）

以下是包含所有核心配置的完整示例，可根据自身使用场景修改参数：

// ~/.openclaw/openclaw.
{
“session”: {
“scope”: “per-sender”, // 群聊会话单独隔离
“dmScope”: “main”, // 私信会话保持连续性（多用户收件箱建议改为per-channel-peer）
“identityLinks”: {
// 映射同一用户的多渠道ID，实现跨渠道会话共享
“alice”: [“telegram:123456789”, “discord:987654321012345678”]
},
“reset”: {
// 全局默认：每日凌晨4点重置，同时设置空闲2小时重置（先过期者生效）
“mode”: “daily”,
“atHour”: 4,
“idleMinutes”: 120
},
“resetByType”: {
“thread”: { “mode”: “daily”, “atHour”: 4 },
“dm”: { “mode”: “idle”, “idleMinutes”: 240 },
“group”: { “mode”: “idle”, “idleMinutes”: 120 }
},
“resetByChannel”: {
“discord”: { “mode”: “idle”, “idleMinutes”: 10080 }
},
“resetTriggers”: [“/new”, “/reset”], // 会话重置触发指令
“store”: “~/.openclaw/agents/{agentId}/sessions/sessions.”, // 会话存储路径
“mainKey”: “main”, // 主会话默认键
“sendPolicy”: {
“rules”: [
{ “action”: “deny”, “match”: { “channel”: “discord”, “chatType”: “group” } },
{ “action”: “deny”, “match”: { “keyPrefix”: “cron:” } }
],
“default”: “allow”
}
}
}

十一、会话检查与调试（实操命令）

通过以下命令，可查看会话状态、调试问题，所有命令均在终端执行：

1. 查看会话基础状态

openclaw status # 显示会话存储路径、最近的会话信息

2. 导出所有会话（格式）

openclaw sessions – # 导出所有会话条目
openclaw sessions —active <minutes> # 仅过滤指定分钟内活跃的会话

3. 从 Gateway 网关获取会话（远程/本地）

# 本地 Gateway 网关
openclaw gateway call sessions.list –params ‘{}’

# 远程 Gateway 网关（需指定URL和Token）
openclaw gateway call sessions.list –params ‘{}’ –url <网关地址> –token <访问Token>

4. 聊天中调试（发送独立消息）