会话管理

OpenClaw 将每个代理的一个私聊会话视为主会话。私聊折叠到 agent:<agentId>:<mainKey>(默认 main),而群组/频道聊天获得自己的键。session.mainKey 会被遵守。

使用 session.dmScope 来控制私信如何分组:

main(默认):所有私信共享主会话以保持连续性。
per-peer:跨频道按发送者 id 隔离。
per-channel-peer:按频道 + 发送者隔离(推荐用于多用户收件箱)。
per-account-channel-peer:按账号 + 频道 + 发送者隔离(推荐用于多账号收件箱)。使用 session.identityLinks 将带提供商前缀的对等 id 映射到规范身份,这样同一个人在使用 per-peer、per-channel-peer 或 per-account-channel-peer 时可以跨频道共享私信会话。

安全私信模式(推荐)

如果你的代理可以接收来自多个人的私信(多个发送者的配对审批、包含多个条目的私信白名单,或 dmPolicy: "open"),启用安全私信模式以避免跨用户上下文泄漏:

json5

// ~/.openclaw/openclaw.json
{
  session: {
    // Secure DM mode: isolate DM context per channel + sender.
    dmScope: "per-channel-peer",
  },
}

注意:

默认为 dmScope: "main" 以保持连续性(所有私信共享主会话)。
对于同一频道上的多账号收件箱,优先使用 per-account-channel-peer。
如果同一个人通过多个频道联系你,使用 session.identityLinks 将他们的私信会话折叠为一个规范身份。

网关是真相来源

所有会话状态都归网关所有("主" OpenClaw)。UI 客户端(macOS 应用、WebChat 等)必须向网关查询会话列表和令牌计数,而不是读取本地文件。

在远程模式下,你关心的会话存储位于远程网关主机上,而不是你的 Mac 上。
UI 中显示的令牌计数来自网关存储字段(inputTokens、outputTokens、totalTokens、contextTokens)。客户端不解析 JSONL 记录来"修正"总数。

状态存储位置

在网关主机上:
- 存储文件:~/.openclaw/agents/<agentId>/sessions/sessions.json(每个代理)。
记录:~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl(Telegram 主题会话使用 .../<SessionId>-topic-<threadId>.jsonl)。
存储是一个映射 sessionKey -> { sessionId, updatedAt, ... }。删除条目是安全的;它们会按需重新创建。
群组条目可能包含 displayName、channel、subject、room 和 space 以在 UI 中标记会话。
会话条目包含 origin 元数据(标签 + 路由提示),以便 UI 可以解释会话来自何处。
OpenClaw 不读取旧版 Pi/Tau 会话文件夹。

会话修剪

OpenClaw 默认在 LLM 调用之前从内存上下文中修剪旧的工具结果。这不会重写 JSONL 历史。参见 /concepts/session-pruning。

压缩前内存刷新

当会话接近自动压缩时,OpenClaw 可以运行静默内存刷新回合, 提醒模型将持久化笔记写入磁盘。这仅在工作区可写时运行。参见内存和压缩。

传输映射到会话键

私聊遵循 session.dmScope(默认 main)。
- main:agent:<agentId>:<mainKey>(跨设备/频道的连续性)。
  - 多个电话号码和频道可以映射到同一个代理主键;它们充当进入一个对话的传输。
- per-peer:agent:<agentId>:dm:<peerId>。
- per-channel-peer:agent:<agentId>:<channel>:dm:<peerId>。
- per-account-channel-peer:agent:<agentId>:<channel>:<accountId>:dm:<peerId>(accountId 默认为 default)。
- 如果 session.identityLinks 匹配带提供商前缀的对等 id(例如 telegram:123),规范键替换 <peerId>,这样同一个人可以跨频道共享会话。
群聊隔离状态:agent:<agentId>:<channel>:group:<id>(房间/频道使用 agent:<agentId>:<channel>:channel:<id>)。
- Telegram 论坛主题在群组 id 后附加 :topic:<threadId> 以实现隔离。
- 旧版 group:<id> 键仍然被识别以用于迁移。
入站上下文仍可能使用 group:<id>;频道从 Provider 推断并标准化为规范的 agent:<agentId>:<channel>:group:<id> 形式。
其他来源:
- 定时任务:cron:<job.id>
- Webhooks:hook:<uuid>(除非由钩子显式设置)
- 节点运行:node-<nodeId>

生命周期

重置策略:会话被重用直到过期,并在下一条入站消息时评估过期。
每日重置:默认为网关主机本地时间凌晨 4:00。当会话的最后更新早于最近的每日重置时间时,会话即过期。
空闲重置(可选):idleMinutes 添加滑动空闲窗口。当同时配置每日和空闲重置时,先过期的强制创建新会话。
旧版仅空闲:如果你在没有任何 session.reset/resetByType 配置的情况下设置 session.idleMinutes,OpenClaw 保持仅空闲模式以实现向后兼容。
按类型覆盖(可选):resetByType 允许你覆盖 dm、group 和 thread 会话的策略(thread = Slack/Discord 线程、Telegram 主题、连接器提供的 Matrix 线程)。
按频道覆盖(可选):resetByChannel 覆盖频道的重置策略(适用于该频道的所有会话类型,并优先于 reset/resetByType)。
重置触发器:精确的 /new 或 /reset(加上 resetTriggers 中的任何额外项)启动新的会话 id 并传递消息的其余部分。/new <model> 接受模型别名、provider/model 或提供商名称(模糊匹配)以设置新会话模型。如果单独发送 /new 或 /reset,OpenClaw 运行简短的"你好"问候回合以确认重置。
手动重置:从存储中删除特定键或删除 JSONL 记录;下一条消息会重新创建它们。
隔离的定时任务总是为每次运行创建新的 sessionId(无空闲重用)。

发送策略(可选)

阻止特定会话类型的传递,而无需列出单个 id。

json5

{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } },
      ],
      default: "allow",
    },
  },
}

运行时覆盖(仅所有者):

/send on → 允许此会话
/send off → 拒绝此会话
/send inherit → 清除覆盖并使用配置规则将这些作为独立消息发送以便它们注册。

配置(可选重命名示例)

json5

// ~/.openclaw/openclaw.json
{
  session: {
    scope: "per-sender", // keep group keys separate
    dmScope: "main", // DM continuity (set per-channel-peer/per-account-channel-peer for shared inboxes)
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      // Defaults: mode=daily, atHour=4 (gateway host local time).
      // If you also set idleMinutes, whichever expires first wins.
      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.json",
    mainKey: "main",
  },
}

检查

openclaw status — 显示存储路径和最近的会话。
openclaw sessions --json — 转储每个条目(使用 --active <minutes> 过滤)。
openclaw gateway call sessions.list --params '{}' — 从运行的网关获取会话(使用 --url/--token 进行远程网关访问)。
在聊天中作为独立消息发送 /status 以查看代理是否可达、会话上下文使用了多少、当前的思考/详细切换,以及你的 WhatsApp web 凭据最后刷新时间(有助于发现重新链接需求)。
发送 /context list 或 /context detail 以查看系统提示和注入的工作区文件中的内容(以及最大的上下文贡献者)。
作为独立消息发送 /stop 以中止当前运行,清除该会话的排队后续操作,并停止从中衍生的任何子代理运行(回复包含停止计数)。
作为独立消息发送 /compact(可选指令)以总结旧的上下文并释放窗口空间。参见 /concepts/compaction。
JSONL 记录可以直接打开以查看完整回合。

提示

保持主键专用于 1:1 流量;让群组保留自己的键。
自动化清理时,删除单个键而不是整个存储,以保留其他地方的上下文。

会话来源元数据

每个会话条目记录它来自何处(尽力而为)在 origin 中:

label:人类标签(从对话标签 + 群组主题/频道解析)
provider:标准化的频道 id(包括扩展)
from/to:来自入站信封的原始路由 id
accountId:提供商账号 id(在多账号时)
threadId:当频道支持时的线程/主题 id 来源字段为私信、频道和群组填充。如果连接器仅更新传递路由(例如,保持私信主会话活跃), 它仍应提供入站上下文,以便会话保留其解释元数据。扩展可以通过发送 ConversationLabel、 GroupSubject、GroupChannel、GroupSpace 和 SenderName 在入站上下文中并调用 recordSessionMetaFromInbound(或将相同的上下文传递给 updateLastRoute)来实现这一点。

会话管理 ​

安全私信模式(推荐) ​

网关是真相来源 ​

状态存储位置 ​

会话修剪 ​

压缩前内存刷新 ​

传输映射到会话键 ​

生命周期 ​

发送策略(可选) ​

配置(可选重命名示例) ​

检查 ​

提示 ​

会话来源元数据 ​

会话管理

安全私信模式(推荐)

网关是真相来源

状态存储位置

会话修剪

压缩前内存刷新

传输映射到会话键

生命周期

发送策略(可选)

配置(可选重命名示例)

检查

提示

会话来源元数据