🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 61 篇，OpenClaw 最佳实战「2026」系列第 31 篇

大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。

我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

OpenClaw 会话管理架构图 1：OpenClaw 会话管理核心架构

在搭建 AI Agent 系统时，会话管理是绕不开的核心问题。如果你遇到过这些情况：

多个用户给同一个 Agent 发消息，它把 A 的对话内容泄露给了 B会话状态越积越多，磁盘占用持续增长，却不知道如何清理想要 Agent 之间互相通信，但不知道怎么实现这些问题的根源都在于：没有理解会话管理的底层机制。

OpenClaw 提供了一套完整的会话管理方案：从多用户隔离、状态持久化，到基于 TTL 的智能修剪。本文将从底层原理出发，解析这套机制的设计思想。

1. Session 核心概念：AI Agent 的记忆中枢会话定义OpenClaw 将每个 Agent 的直接聊天会话视为核心单元。会话是 Agent 记忆的载体，承载着对话历史、上下文状态和令牌计数等关键信息。

直接聊天会话的键格式为：

代码语言：javascript复制agent::

默认 mainKey 为 main。群组和频道聊天拥有独立的键，遵循不同的命名规则。

会话的生命周期会话从创建到过期经历以下阶段：

创建：首次消息触发会话创建活跃：持续接收消息，状态更新过期：超过 pruneAfter 时间未活跃清理：维护机制清理过期会话会话被重用直到过期，过期评估在下一个入站消息时进行。这意味着会话不是每次消息都新建，而是复用已有会话直到它不再有效。

默认重置策略OpenClaw 默认在 gateway 主机本地时间凌晨 4:00 执行每日重置。

此外，还可以配置 空闲重置（idleMinutes）——添加滑动空闲窗口。当同时配置每日和空闲重置时，先到期的强制创建新会话。

代码语言：javascript复制{

session: {

reset: {

daily: "04:00",

idleMinutes: 60, // 空闲 60 分钟后重置

},

},

}

会话生命周期流程图 2：会话生命周期状态机

2. 会话键映射：4 种隔离模式dmScope 配置session.dmScope 控制直接消息的分组方式，提供 4 种隔离模式：

模式

键格式

适用场景

main

agent::

单用户场景，所有 DM 共享主会话

per-peer

agent::direct:

按发送者隔离

per-channel-peer

agent:::direct:

多用户收件箱（推荐）

per-account-channel-peer

agent::::direct:

多账户收件箱

安全 DM 模式（重要）安全警告：如果 Agent 可以接收来自多人的 DM，必须启用安全 DM 模式。否则所有用户共享相同的对话上下文，可能导致用户之间的私人信息泄露。

问题场景：

Alice 向 Agent 发送私人话题（如医疗预约）Bob 询问"我们在谈论什么？"因为两个 DM 共享同一个会话，模型可能使用 Alice 的上下文回答 Bob解决方案：设置 dmScope 隔离每个用户的会话：

代码语言：javascript复制{

session: {

dmScope: "per-channel-peer",

},

}

4种隔离模式对比图 3：4 种 dmScope 隔离模式对比

群组聊天键映射群组聊天的会话键格式为：

代码语言：javascript复制agent:::group:

Telegram 论坛主题附加 :topic:，形成更细粒度的隔离。

其他来源的键映射来源类型

键格式

Cron jobs

cron:

Webhooks

hook:

Node runs

node-

identityLinks 跨频道映射使用 session.identityLinks 将提供商前缀的对等 ID 映射到规范身份，这样同一个人在使用 per-peer、per-channel-peer 或 per-account-channel-peer 时可以跨频道共享 DM 会话。

代码语言：javascript复制{

session: {

dmScope: "per-peer",

identityLinks: {

"discord:123456": "user:alice",

"slack:U789": "user:alice",

},

},

}

上面的配置让 Alice 在 Discord 和 Slack 上都使用同一个会话。

3. 状态存储：Gateway 是真理之源架构设计所有会话状态由 gateway（"master" OpenClaw）拥有。这是一个关键的设计决策：

Gateway 是真理之源，UI 客户端（macOS 应用、WebChat 等）必须向 gateway 查询会话列表和令牌计数，而不是读取本地文件。

存储位置在 gateway 主机上的存储结构：

代码语言：javascript复制~/.openclaw/agents//sessions/

├── sessions.json # 会话索引：sessionKey -> { sessionId, updatedAt, ... }

└── .jsonl # 转录文件

sessions.json 是 sessionKey -> { sessionId, updatedAt, ... } 的映射。删除条目是安全的——它们会在需要时重新创建。

存储特点集中管理：所有状态由 gateway 统一管理按 Agent 隔离：每个 Agent 有独立的 sessions 目录可重建：删除索引条目后可重新创建Gateway 状态存储架构图 4：Gateway 状态存储架构

4. Session Pruning：基于 TTL 的智能修剪核心原理Session pruning 在每次 LLM 调用前从内存上下文中修剪旧的工具结果。

关键点：

它不会重写磁盘上的会话历史（*.jsonl）仅当启用 mode: "cache-ttl" 且该会话的最后一次 Anthropic 调用远于 ttl仅对 Anthropic API 调用有效（及 OpenRouter Anthropic 模型）为什么需要修剪Anthropic prompt caching 仅在 TTL 内有效。如果会话空闲超过 TTL，下一次请求会重新缓存完整提示，除非先修剪它。

修剪的优势：

降低成本：减少 TTL 过期后第一次请求的 cacheWrite 大小TTL 重置：一旦修剪运行，缓存窗口重置，后续请求可以重用新缓存的提示可修剪内容内容类型

是否可修剪

toolResult 消息

✅ 可修剪

用户消息

❌ 从不修改

助手消息

❌ 从不修改（受保护）

保护机制：

最后 keepLastAssistants 个助手消息受保护包含图片块的工具结果被跳过修剪模式软修剪（soft-trim）：

仅针对过大的工具结果保留头部 + 尾部，插入 ...附加原始大小说明硬清除（hard-clear）：

用 hardClear.placeholder 替换整个工具结果默认配置代码语言：javascript复制{

session: {

pruning: {

mode: "cache-ttl",

ttl: "5m",

keepLastAssistants: 3,

softTrimRatio: 0.3,

hardClearRatio: 0.5,

minPrunableToolChars: 50000,

},

},

}

参数

默认值

说明

ttl

5m

缓存过期时间

keepLastAssistants

3

保护的最近助手消息数

softTrimRatio

0.3

触发软修剪的大小比例

hardClearRatio

0.5

触发硬清除的大小比例

minPrunableToolChars

50000

最小可修剪字符数

Session Pruning 工作原理图 5：Session Pruning 决策流程

5. Session Maintenance：自动化存储管理默认配置代码语言：javascript复制{

session: {

maintenance: {

mode: "warn",

pruneAfter: "30d",

maxEntries: 500,

rotateBytes: "10mb",

},

},

}

维护执行流程维护在会话存储写入期间运行，也可以通过 openclaw sessions cleanup 手动触发。

当 mode: "enforce" 时，按以下顺序应用清理：

修剪过期条目：超过 pruneAfter 的条目限制条目数量：限制到 maxEntries（最旧的优先）归档转录文件：已删除条目的转录文件清除旧归档：根据保留策略清除旧的归档文件轮转索引文件：当 sessions.json 超过 rotateBytes 时强制磁盘预算：如果设置了 maxDiskBytes性能注意事项增加成本的因素：

非常高的 maxEntries 值长的 pruneAfter 窗口大量的转录/归档文件启用磁盘预算但没有合理的修剪/上限限制优化建议：

生产环境使用 mode: "enforce"同时设置时间和数量限制（pruneAfter + maxEntries）设置 maxDiskBytes + highWaterBytes 作为硬上限6. Session Tools：Agent 间通信与子 Agent 生成OpenClaw 提供了 4 个 Session Tools，让 Agent 可以操作会话：

sessions_list列出会话，支持多种过滤条件：

代码语言：javascript复制{

"kinds": ["main", "group"],

"limit": 50,

"activeMinutes": 60,

"messageLimit": 10

}

返回字段包括：key、kind、channel、displayName、updatedAt、sessionId、model、contextTokens、totalTokens。

sessions_history获取指定会话的历史消息：

代码语言：javascript复制{

"sessionKey": "agent:my-agent:main",

"limit": 100,

"includeTools": false

}

sessions_send向另一个会话发送消息，实现 Agent 间通信：

代码语言：javascript复制{

"sessionKey": "agent:another-agent:main",

"message": "请处理这个任务",

"timeoutSeconds": 60

}

行为特点：

timeoutSeconds = 0：入队并返回 { runId, status: "accepted" }timeoutSeconds > 0：等待最多 N 秒完成包含 reply-back 循环（最多 5 轮）sessions_spawn生成子 Agent 运行任务：

代码语言：javascript复制{

"task": "分析这段代码的性能问题",

"label": "code-analysis",

"agentId": "specialized-agent",

"model": "claude-3-sonnet",

"thinking": "high",

"runTimeoutSeconds": 300,

"mode": "run",

"cleanup": "delete"

}

生成的子 Agent 会话键格式：agent::subagent:

重要限制：

子 Agent 默认使用完整工具集减去会话工具子 Agent 不允许调用 sessions_spawn（防止无限递归）沙箱会话可见性通过 tools.sessions.visibility 控制会话可见范围：

模式

说明

self

仅当前会话键

tree

当前会话 + 由当前会话生成的会话（默认）

agent

属于当前 Agent ID 的任何会话

all

任何会话

7. 生产环境配置建议基础配置代码语言：javascript复制{

session: {

// 多用户隔离

dmScope: "per-channel-peer",

// 会话维护

maintenance: {

mode: "enforce",

pruneAfter: "14d",

maxEntries: 200,

rotateBytes: "5mb",

maxDiskBytes: "500mb",

highWaterBytes: "400mb",

},

// 智能修剪

pruning: {

mode: "cache-ttl",

ttl: "5m",

keepLastAssistants: 3,

},

// 发送策略

sendPolicy: {

rules: [

{ match: { channel: "discord", chatType: "group" }, action: "deny" }

],

default: "allow",

},

},

}

调试命令CLI 命令：

openclaw status：显示存储路径和最近会话openclaw sessions --json：转储所有条目openclaw sessions cleanup --dry-run：预览清理操作openclaw sessions cleanup --enforce：强制清理聊天命令：

/status：查看会话状态/context list：查看系统提示和注入的工作区文件/compact：压缩旧上下文/new 或 /reset：启动新会话监控要点磁盘使用：监控 ~/.openclaw/agents//sessions/ 目录大小会话数量：通过 openclaw sessions --json 定期检查清理效果：使用 --dry-run 预览清理操作总结OpenClaw 的会话管理体现了几个关键设计理念：

Gateway 是真理之源：所有状态由 gateway 统一管理，避免分布式状态不一致会话隔离：通过 dmScope 实现 4 种隔离模式，支持从单用户到多账户收件箱的各种场景自动维护：通过 maintenance 机制自动管理存储增长，无需人工干预智能修剪：基于 TTL 感知的修剪优化 Anthropic 缓存使用和成本工具化操作：提供完整的会话工具集，支持 Agent 间通信和子 Agent 生成安全沙箱：支持沙箱会话和可见性控制，防止权限泄露如果你正在搭建多用户 AI Agent 系统，会话管理是不可忽视的基础设施。理解这些底层机制，能帮助你做出更合理的架构决策。

相关资源

官方文档 - Session Management：https://docs.openclaw.ai/concepts/session

官方文档 - Session Pruning：https://docs.openclaw.ai/concepts/session-pruning

官方文档 - Session Tool：https://docs.openclaw.ai/concepts/session-tool

好啦，谢谢你观看我的文章，如果喜欢可以点赞转发给需要的朋友，我们下一期再见！敬请期待！