活动记忆故障排除
调试¶
如果活动记忆没有出现在预期位置:
- 确认插件已在
plugins.entries.active-memory.enabled下启用。 - 对于跨会话记忆,确认该 agent 实际生效的
memory.search.rememberAcrossConversations设置已启用,运行openclaw doctor以验证当前记忆提供商支持受保护的转录召回,并在显式配置时确认config.toolsAllow包含memory_search。对于高级活动记忆,确认 agent ID 已列在config.agents中。 - 确认你正在通过符合条件的交互式持久会话进行测试。
- 记住群组与频道从不使用跨会话转录召回。
- 打开
config.logging: true并查看网关日志。 - 使用
openclaw status --deep验证记忆搜索本身是否正常工作。
触发召回和跨会话记忆是两条独立路径。运行 /active-memory status 以检查会话开关和这两项配置设置。即使 agent 不在 plugins.entries.active-memory.config.agents 中,跨会话记忆也可能处于开启状态。会话暂停不会更改这些配置设置;目标策略和工具策略仍然适用。
当 agent 不在该允许列表中时,调试日志会包含 lane-1 skipped reason=agent-not-configured agent=<id>。在 config.logging: true 下,同一诊断信息会以 info 级别出现。
如果记忆命中结果噪声较大,请收紧 maxSummaryChars。如果活动记忆太慢,请降低 queryMode、降低 timeoutMs,或减少最近轮次数量以及每轮字符上限。
常见问题¶
高级活动记忆依赖于已配置记忆插件的召回管道,因此大多数召回异常都是嵌入提供商问题,而不是活动记忆 bug。默认 memory-core 路径使用 memory_search 和 memory_get;memory-lancedb 插槽使用 memory_recall。如果你使用其他记忆插件,请确认 config.toolsAllow 中列出了该插件实际注册的工具。跨会话记忆的范围更窄:当前记忆提供商必须支持 OpenClaw 的受保护同 agent/私有会话召回路径。
已注册的召回工具返回 status=policy-disabled
此状态表示已配置的召回工具均未保留在父 agent 的授权工具集合中。活动记忆会跳过阻塞性子 agent,主回复将继续,但不包含召回上下文。
- 检查所选 agent 的 profile 以及显式
tools.alsoAllow授权。在限制性 profile 下,仅在config.toolsAllow中列出插件工具并不会授权它们。请使用作用域限定的 Lossless Claw 示例。 - 检查显式拒绝以及提供商、agent 和沙箱工具策略。
alsoAllow会扩展 profile;它不会覆盖这些限制。特定提供商的 profile 拥有自己的alsoAllow配置。 - 确认
config.toolsAllow包含预期的具体召回名称。活动记忆只能使用此列表与父 agent 有效工具的交集。使用跨会话记忆时,请保留memory_search。 - 使用
openclaw plugins inspect lossless-claw --runtime --json检查注册情况。列出的工具表示已注册,但该输出并不能证明父 agent 或活动记忆有权调用它。
嵌入提供商已切换或停止工作
如果 memory.search.provider 未设置,OpenClaw 会使用 OpenAI 嵌入。对于 Bedrock、DeepInfra、Gemini、GitHub Copilot、LM Studio、local、Mistral、Ollama、Voyage 或 OpenAI 兼容嵌入,请显式设置 memory.search.provider。如果已配置的提供商无法运行,memory_search 可能降级为仅词法检索;在提供商已选择后发生的运行时故障不会自动回退。
仅当你希望有意的单一回退时,才设置可选的 memory.search.fallback。有关完整提供商列表和示例,请参阅 记忆搜索。
召回感觉缓慢、为空或不一致
- 打开
/trace on,以在会话中显示插件拥有的活动记忆调试摘要。 - 打开
/verbose on,以在每条回复后也看到🧩 Active Memory: ...状态行。 - 查看网关日志中的
active-memory: ... start|done、memory sync failed (search-bootstrap),或提供商嵌入错误。 - 运行
openclaw status --deep以检查记忆搜索后端和索引健康状态。 - 如果你使用
ollama,请确认嵌入模型已安装(ollama list)。
网关重启后首次召回返回 status=timeout
在 v2026.5.2 及更高版本中,如果冷启动设置(模型预热 + 嵌入索引加载)在首次召回触发时尚未完成,该运行可能达到已配置的 timeoutMs 预算并返回 status=timeout 且输出为空。网关日志会在重启后第一条符合条件的回复附近显示 active-memory timeout after Nms。
请参阅推荐设置下的 冷启动宽限期,以获取推荐的 setupGraceTimeoutMs 值。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw