跨对话记忆
对于个人或完全可信的智能体,可通过一个按智能体设置启用对其其他 私密对话的受限召回:session.dmScope 必须
未设置或为 "main",并且任何绑定都不得覆盖 session.dmScope。配置任何
私信隔离都会使其默认关闭。显式设置 true 或 false 始终优先。启用后,
OpenClaw 会索引该智能体的会话转录,并在符合条件的私密回复之前运行一次主动
记忆检索。该过程可以读取同一智能体其他私密对话中的
相关转录摘录。
它会排除当前正在回复的对话。
隐私边界是固定的:
- 私密直接对话和持久显式 UI 对话可以相互召回
- 群组和频道既不能作为召回来源,也不能作为召回目标
- 其他智能体的转录绝不符合条件
- 没有足够对话元数据的未知或已归档转录会被拒绝
tools.sessions.visibility,也不会授予更广泛的 sessions_* 工具访问权限。共享
工作区记忆(MEMORY.md 和 memory/*.md)保持现有行为。
主动记忆必须保持启用。检索会为符合条件的回复增加一个受限的阻塞步骤;
超时、搜索不可用和结果为空时,回复都会在没有召回转录上下文的情况下继续。
OpenClaw 的内置记忆提供商通过 builtin 和 QMD 后端
支持这种受保护的转录召回路径。其他记忆提供商保留各自的召回行为,但
不会自动获得私密转录授权。openclaw doctor
会报告不受支持的提供商或缺少 memory_search 工具。
高级主动记忆快速开始
将以下内容粘贴到openclaw.json,以使用高级安全默认配置:启用插件,范围限定为
main,仅限私信会话,模型从会话继承。
plugins.entries.*(包括 active-memory.config)属于无需重启的
配置类别:
Gateway 网关会自动重新加载插件运行时,无需手动重启。
如果仍想强制完整重启,请运行:
plugins.entries.active-memory.enabled: true启用插件config.agents: ["main"]仅选择加入main智能体config.allowedChatTypes: ["direct"]将范围限定为私信会话(群组/频道需要显式选择加入)config.model(可选)固定专用召回模型;未设置时继承当前会话模型- 仅在无法解析显式模型或继承模型时使用
config.modelFallback config.fastMode可选择仅为召回覆盖快速模式,而不改变主智能体config.promptStyle: "balanced"是recent模式的默认值- 主动记忆仍然只会为符合条件的交互式持久聊天会话运行(参见运行时机)
工作原理
阻塞式子智能体只能调用已配置的记忆召回工具(参见 记忆工具)。如果查询与 可用记忆之间的关联较弱,它会返回NONE,主回复将在
没有额外上下文的情况下继续。
主动记忆是一项对话增强功能,而不是平台级
推理功能:
适合在以下情况下使用:会话是持久且面向用户的,智能体拥有
值得搜索的长期记忆,并且连续性/个性化比
原始提示词确定性更重要,例如稳定偏好、重复习惯、
应自然呈现的长期上下文。它不适合
自动化、内部工作进程、单次 API 任务,或任何隐藏式
个性化会令人意外的场景。
运行时机
主动记忆有两条激活路径:- 跨对话记忆会自动以有效
memory.search.rememberAcrossConversations设置已启用的智能体为目标,但 仅限私密直接对话或持久显式 UI 对话。 - 高级主动记忆以
plugins.entries.active-memory.config.agents中列出的智能体 ID 为目标,并应用插件的聊天 类型和聊天 ID 控制。
/active-memory off 会暂停该对话的两条
路径。如果任何条件不满足,主动记忆不会在该轮运行,
主回复不受影响。
会话类型
config.allowedChatTypes 控制哪些类型的对话可以运行
高级主动记忆路径。它无法扩大跨对话记忆的范围:
即使允许高级主动记忆在群组或频道中运行,该产品设置仍然仅限私密对话。
默认值:
direct、group、channel、explicit(具有不透明会话 ID 的门户式会话,
例如 agent:main:explicit:portal-123)。
私信会话默认运行;群组、频道和显式会话
需要选择加入:
config.allowedChatIds 和 config.deniedChatIds:
allowedChatIds是已解析对话 ID 的允许列表。非空时, 主动记忆仅对对话 ID 位于该列表中的会话运行——这会同时缩小 所有允许聊天类型的范围,包括 私信。要在保留所有私信的同时仅缩小群组范围, 也请将私聊对端 ID 添加到allowedChatIds,或者使allowedChatTypes仅作用于正在测试的群组/频道发布范围。deniedChatIds是拒绝列表,其优先级始终高于allowedChatTypes和allowedChatIds。
chat_id/open_id、Telegram 聊天 ID、Slack 频道 ID)。匹配
不区分大小写。如果 allowedChatIds 非空,而 OpenClaw 无法
解析会话的对话 ID,主动记忆会跳过该轮,
而不是进行猜测。
会话开关
无需编辑配置,即可暂停或恢复当前聊天会话的主动记忆:plugins.entries.active-memory.config.enabled、智能体的
memory.search.rememberAcrossConversations 设置或其他全局
配置。
要改为针对所有会话暂停/恢复,请使用全局形式(需要
所有者或 operator.admin):
plugins.entries.active-memory.config.enabled,但
保持 plugins.entries.active-memory.enabled 开启,因此之后仍可使用该命令
重新开启主动记忆。
如何查看
默认情况下,主动记忆会注入一个隐藏的不可信提示词前缀, 该前缀不会显示在正常回复中。开启与所需输出匹配的会话开关:/verbose on添加状态行:🧩 Active Memory: status=ok elapsed=842ms query=recent summary=34 chars/trace on添加调试摘要:🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
/trace raw 后,跟踪的 Model Input (User Role) 块会显示原始
隐藏前缀:
查询模式
config.queryMode 控制阻塞式子智能体可以看到多少对话内容。
选择仍能良好回答后续问题的最小模式;随着上下文规模增长,
逐步扩大 timeoutMs,从 message 到 recent,再到 full。
- message
- recent
- 完整
仅发送最新的用户消息。适用于需要最快行为、最强的稳定偏好召回倾向,
且后续轮次不需要对话上下文的情况。对于
config.timeoutMs,可从 3000-5000 ms 左右开始。提示词风格
config.promptStyle 控制子智能体在返回记忆时的积极程度或严格程度:
未设置
config.promptStyle 时的默认映射:
config.promptStyle 始终会覆盖此映射。
模型回退策略
如果未设置config.model,主动记忆将按以下顺序解析模型:
config.modelFallbackPolicy 是为旧配置保留的已弃用兼容字段;
它不再改变运行时行为——modelFallback 严格来说只是上述链中的最后手段,
而不是在已解析模型出错时换用另一模型的运行时故障转移机制。
速度建议
不设置config.model(继承会话模型)是最安全的
默认选择:它会遵循现有的提供商、身份验证和模型偏好。若要降低延迟,
请改用专用的快速模型——回忆质量固然重要,但此处延迟比主回答路径
更重要,而且工具范围很窄(仅包含记忆回忆工具)。
合适的快速模型选项:
cerebras/gpt-oss-120b,专用的低延迟回忆模型google/gemini-3-flash,无需更改主聊天模型的低延迟回退模型- 不设置
config.model,使用常规会话模型
Cerebras 设置
chat/completions 访问权限——
仅有 /v1/models 可见性并不能保证这一点。
记忆工具
config.toolsAllow 设置阻塞式子智能体在高级主动记忆中
可以调用的具体工具名称。默认值取决于当前记忆提供商:
如果配置的工具均不可用,或子智能体运行失败,
主动记忆会跳过本轮回忆,主回复将在没有记忆上下文的情况下
继续。对于自定义回忆工具,非空且对模型可见的工具输出
会被视为回忆证据,除非结构化结果字段明确报告结果为空或失败。
toolsAllow 仅接受具体的记忆工具名称:通配符、group:*
条目以及核心智能体工具(read、exec、message、web_search 和
类似工具)会在隐藏子智能体启动前被静默过滤掉。
内置记忆
无需显式设置toolsAllow:
LanceDB 记忆
安装并配置 LanceDB 后,主动 记忆会自动使用memory_recall;无需显式设置 toolsAllow:
memory.search.rememberAcrossConversations 不会通过 memory_recall
公开私有会话记录。当 LanceDB 是当前记忆提供商时,请使用 LanceDB 的自动回忆
或上述高级配置。
Lossless Claw
Lossless Claw 是一个 外部上下文引擎插件(openclaw plugins install @martian-engineering/lossless-claw),拥有自己的回忆工具。请先将其设置为
上下文引擎;参阅上下文引擎。然后
将主动记忆指向其工具:
lcm_expand 添加到 toolsAllow;Lossless Claw 将其用作
委托式扩展的底层工具,不供顶层主动记忆子智能体使用。
Lossless Claw 会更改上下文组装方式,但不会替换当前记忆提供商。
同时使用 rememberAcrossConversations 时,请在 toolsAllow 中保留 memory_search;
仅包含 LCM 工具的列表仍适用于高级主动记忆,但会禁用产品的会话记录回忆
路径。
高级应急选项
这些选项不属于推荐设置。config.thinking 会覆盖子智能体的思考级别(默认值为 "off",
因为主动记忆在回复路径中运行,额外的思考时间会直接增加
用户可感知的延迟):
config.fastMode 仅覆盖阻塞式记忆子智能体的快速模式。
使用 true、false 或 "auto";不设置则继承常规
智能体、会话和模型的默认值。"auto" 使用回忆模型配置的
fastAutoOnSeconds 截止值:
config.promptAppend 会在默认提示词之后、对话上下文之前添加操作员指令——
当非核心记忆插件需要特定的工具顺序或查询塑形时,
请将其与自定义 toolsAllow 配合使用:
config.promptOverride 会完全替换默认提示词(之后仍会追加对话
上下文)。除非是有意测试不同的回忆契约,否则不建议这样做——
默认提示词经过调优,会为主模型返回 NONE
或精简的用户事实上下文:
会话记录持久化
阻塞式子智能体运行期间会创建真实的session.jsonl 会话记录。
默认情况下,它会写入临时目录,并在运行完成后立即删除。
若要将这些会话记录保留在磁盘上以便调试:
config.transcriptDir 更改相对子目录。请谨慎使用:
在繁忙会话中,会话记录可能迅速累积,full 查询
模式会复制大量对话上下文,而且这些会话记录包含
隐藏的提示词上下文以及回忆出的记忆。
配置
所有主动记忆配置均位于plugins.entries.active-memory 下。
实用的调优字段:
推荐设置
从recent 开始:
/verbose on 显示状态行,并使用 /trace on 显示调试摘要
——两者都会在主回复之后作为后续消息发送,而不是在主回复
之前发送。然后切换到 message 以降低延迟;如果额外上下文
值得以更慢的子智能体运行为代价,则切换到 full。
冷启动宽限期
在 v2026.5.2 之前,插件会在冷启动期间静默地将timeoutMs 额外延长 30000
ms,使模型预热、嵌入索引加载和首次
召回可以共享一个更大的预算。v2026.5.2 将该宽限期移至显式
setupGraceTimeoutMs 配置之后:除非你选择启用,否则 timeoutMs 现在默认就是召回工作
预算。阻塞钩子会在该预算外包裹两个固定阶段:召回
开始前,最多使用 1500 ms 进行会话/配置预检;
召回工作停止后,再单独固定使用 1500 ms 进行中止收尾和转录记录
恢复。这两个宽限都不会延长模型或工具
执行时间。
如果你从 v2026.4.x 升级而来,并且针对旧的
隐式宽限机制调整过 timeoutMs(推荐的初始值 timeoutMs: 15000 就是一个
示例),请设置 setupGraceTimeoutMs: 30000,以恢复 v5.2 之前的有效
预算:
timeoutMs + setupGraceTimeoutMs + 3000 ms(配置的
回忆工作预算,加上最多 1500 ms 的预检时间,再加上固定的
1500 ms 回忆后完成宽限时间)。嵌入式回忆运行器使用
相同的有效超时预算,因此 setupGraceTimeoutMs 同时涵盖
外层提示词构建看门狗和内层阻塞式回忆运行。
对于资源紧张且可接受冷启动延迟这一
权衡的 Gateway 网关,较低的值(5000-15000 ms)也可用——代价是
Gateway 网关重启后的首次回忆更有可能在
预热完成期间返回空结果。
调试
如果主动记忆未出现在预期位置:- 确认已在
plugins.entries.active-memory.enabled下启用该插件。 - 若要跨对话使用“记住”功能,请确认该智能体的有效
memory.search.rememberAcrossConversations设置已启用,运行openclaw doctor以验证当前记忆提供商支持受保护的 对话记录回忆,并确认显式配置时config.toolsAllow包含memory_search。 对于高级主动记忆,请确认该智能体 ID 已列在config.agents中。 - 确认你是在符合条件的交互式持久对话中进行测试。
- 请记住,群组和频道绝不会使用跨对话的对话记录回忆。
- 启用
config.logging: true并查看 Gateway 网关日志。 - 使用
openclaw status --deep验证记忆搜索本身是否正常工作。
maxSummaryChars。如果主动记忆速度太
慢,请降低 queryMode、降低 timeoutMs,或者减少最近轮次数和
每轮字符上限。
常见问题
高级主动记忆依赖已配置记忆插件的回忆 管线,因此大多数意外的回忆结果都源于嵌入提供商问题,而不是 主动记忆缺陷。默认的memory-core 路径使用 memory_search 和
memory_get;memory-lancedb 插槽使用 memory_recall。如果使用其他
记忆插件,请确认 config.toolsAllow 指定的是该插件实际
注册的工具。跨对话的“记住”功能范围更窄:当前记忆
提供商必须支持 OpenClaw 受保护的同智能体/私有会话回忆
路径。
嵌入提供商已切换或停止工作
嵌入提供商已切换或停止工作
如果未设置
memory.search.provider,OpenClaw 将使用 OpenAI 嵌入。对于 Bedrock、DeepInfra、Gemini、GitHub
Copilot、LM Studio、本地、Mistral、Ollama、Voyage 或 OpenAI 兼容
嵌入,请显式设置 memory.search.provider。如果配置的提供商无法运行,memory_search 可能
降级为仅使用词法检索;提供商已经选定后出现的运行时故障
不会自动回退。仅当需要有意设置单一回退方案时,才设置可选的
memory.search.fallback。有关提供商完整列表和示例,请参阅记忆搜索。回忆感觉缓慢、无结果或不一致
回忆感觉缓慢、无结果或不一致
- 启用
/trace on,以在会话中显示由插件负责的主动记忆调试 摘要。 - 启用
/verbose on,还可在每次回复后查看🧩 Active Memory: ...状态行。 - 查看 Gateway 网关日志中是否出现
active-memory: ... start|done、memory sync failed (search-bootstrap)或提供商嵌入错误。 - 运行
openclaw status --deep,检查记忆搜索后端和 索引健康状况。 - 如果使用
ollama,请确认已安装嵌入模型 (ollama list)。
Gateway 网关重启后的首次回忆返回 `status=timeout`
Gateway 网关重启后的首次回忆返回 `status=timeout`
在 v2026.5.2 及更高版本中,如果首次回忆触发时冷启动设置(模型预热 + 嵌入
索引加载)尚未完成,该次运行
可能达到配置的
timeoutMs 预算,并返回 status=timeout
及空输出。Gateway 网关日志会在重启后的首次符合条件的回复附近显示
active-memory timeout after Nms。有关推荐的 setupGraceTimeoutMs 值,请参阅“推荐设置”下的冷启动宽限。