跳转至

活动记忆故障排除

调试

如果活动记忆没有出现在预期位置:

  1. 确认插件已在 plugins.entries.active-memory.enabled 下启用。
  2. 对于跨会话记忆,确认该 agent 实际生效的 memory.search.rememberAcrossConversations 设置已启用,运行 openclaw doctor 以验证当前记忆提供商支持受保护的转录召回,并在显式配置时确认 config.toolsAllow 包含 memory_search。对于高级活动记忆,确认 agent ID 已列在 config.agents 中。
  3. 确认你正在通过符合条件的交互式持久会话进行测试。
  4. 记住群组与频道从不使用跨会话转录召回。
  5. 打开 config.logging: true 并查看网关日志。
  6. 使用 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