OpenClaw 会话管理：4 种隔离模式 + 1 套修剪机制，让 AI Agent 从"记忆混乱"到"多用户安全"

🚩 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 记忆的载体，承载着对话历史、上下文状态和令牌计数等关键信息。

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

agent:<agentId>:<mainKey>

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

会话的生命周期

会话从创建到过期经历以下阶段：

1. 创建：首次消息触发会话创建
2. 活跃：持续接收消息，状态更新
3. 过期：超过 pruneAfter 时间未活跃
4. 清理：维护机制清理过期会话

会话被重用直到过期，过期评估在下一个入站消息时进行。这意味着会话不是每次消息都新建，而是复用已有会话直到它不再有效。

默认重置策略

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

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

{
  session: {
    reset: {
      daily: "04:00",
      idleMinutes: 60,  // 空闲 60 分钟后重置
    },
  },
}

会话生命周期流程

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

2. 会话键映射：4 种隔离模式

dmScope 配置

session.dmScope 控制直接消息的分组方式，提供 4 种隔离模式：

安全 DM 模式（重要）

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

问题场景：

• Alice 向 Agent 发送私人话题（如医疗预约）
• Bob 询问"我们在谈论什么？"
• 因为两个 DM 共享同一个会话，模型可能使用 Alice 的上下文回答 Bob

解决方案：设置 dmScope 隔离每个用户的会话：

{
  session: {
    dmScope: "per-channel-peer",
  },
}

4种隔离模式对比

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

群组聊天键映射

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

agent:<agentId>:<channel>:group:<id>

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

其他来源的键映射

identityLinks 跨频道映射

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

{
  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 主机上的存储结构：

~/.openclaw/agents/<agentId>/sessions/
├── sessions.json      # 会话索引：sessionKey -> { sessionId, updatedAt, ... }
└── <SessionId>.jsonl  # 转录文件

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

存储特点

1. 集中管理：所有状态由 gateway 统一管理
2. 按 Agent 隔离：每个 Agent 有独立的 sessions 目录
3. 可重建：删除索引条目后可重新创建

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，下一次请求会重新缓存完整提示，除非先修剪它。

修剪的优势：

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

可修剪内容

保护机制：

• 最后 keepLastAssistants 个助手消息受保护
• 包含图片块的工具结果被跳过

修剪模式

软修剪（soft-trim）：

• 仅针对过大的工具结果
• 保留头部 + 尾部，插入 ...
• 附加原始大小说明

硬清除（hard-clear）：

• 用 hardClear.placeholder 替换整个工具结果

默认配置

{
  session: {
    pruning: {
      mode: "cache-ttl",
      ttl: "5m",
      keepLastAssistants: 3,
      softTrimRatio: 0.3,
      hardClearRatio: 0.5,
      minPrunableToolChars: 50000,
    },
  },
}

Session Pruning 工作原理

图 5：Session Pruning 决策流程

5. Session Maintenance：自动化存储管理

默认配置

{
  session: {
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
    },
  },
}

维护执行流程

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

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

1. 修剪过期条目：超过 pruneAfter 的条目
2. 限制条目数量：限制到 maxEntries（最旧的优先）
3. 归档转录文件：已删除条目的转录文件
4. 清除旧归档：根据保留策略清除旧的归档文件
5. 轮转索引文件：当 sessions.json 超过 rotateBytes 时
6. 强制磁盘预算：如果设置了 maxDiskBytes

性能注意事项

增加成本的因素：

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

优化建议：

• 生产环境使用 mode: "enforce"
• 同时设置时间和数量限制（pruneAfter + maxEntries）
• 设置 maxDiskBytes + highWaterBytes 作为硬上限

6. Session Tools：Agent 间通信与子 Agent 生成

OpenClaw 提供了 4 个 Session Tools，让 Agent 可以操作会话：

sessions_list

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

{
  "kinds": ["main", "group"],
  "limit": 50,
  "activeMinutes": 60,
  "messageLimit": 10
}

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

sessions_history

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

{
  "sessionKey": "agent:my-agent:main",
  "limit": 100,
  "includeTools": false
}

sessions_send

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

{
  "sessionKey": "agent:another-agent:main",
  "message": "请处理这个任务",
  "timeoutSeconds": 60
}

行为特点：

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

sessions_spawn

生成子 Agent 运行任务：

{
  "task": "分析这段代码的性能问题",
"label": "code-analysis",
"agentId": "specialized-agent",
"model": "claude-3-sonnet",
"thinking": "high",
"runTimeoutSeconds": 300,
"mode": "run",
"cleanup": "delete"
}

生成的子 Agent 会话键格式：agent:<agentId>:subagent:<uuid>

重要限制：

• 子 Agent 默认使用完整工具集减去会话工具
• 子 Agent 不允许调用 sessions_spawn（防止无限递归）

沙箱会话可见性

通过 tools.sessions.visibility 控制会话可见范围：

7. 生产环境配置建议

基础配置

{
  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：启动新会话

监控要点

1. 磁盘使用：监控 ~/.openclaw/agents/<agentId>/sessions/ 目录大小
2. 会话数量：通过 openclaw sessions --json 定期检查
3. 清理效果：使用 --dry-run 预览清理操作

总结

OpenClaw 的会话管理体现了几个关键设计理念：

1. Gateway 是真理之源：所有状态由 gateway 统一管理，避免分布式状态不一致
2. 会话隔离：通过 dmScope 实现 4 种隔离模式，支持从单用户到多账户收件箱的各种场景
3. 自动维护：通过 maintenance 机制自动管理存储增长，无需人工干预
4. 智能修剪：基于 TTL 感知的修剪优化 Anthropic 缓存使用和成本
5. 工具化操作：提供完整的会话工具集，支持 Agent 间通信和子 Agent 生成
6. 安全沙箱：支持沙箱会话和可见性控制，防止权限泄露

如果你正在搭建多用户 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

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