Skip to main content
此页面列出了 OpenClaw 记忆搜索的所有配置项。有关概念性概览,请参阅:

记忆概览

记忆的工作原理。

内置引擎

默认 SQLite 后端。

QMD 引擎

本地优先的边车服务。

记忆搜索

搜索流程和调优。

主动记忆

用于交互式会话的记忆子智能体。
所有共享记忆设置都位于 openclaw.json 的顶层 memory 下。搜索默认值使用 memory.search;每个智能体的搜索覆盖项使用 agents.entries.*.memory.search
对于推荐的个人智能体工作流,请使用 memory.search.rememberAcrossConversations。高级主动记忆的目标选择、 模型、提示词和延迟控制位于 plugins.entries.active-memory 下。有关两种激活路径、记录持久化和安全上线指南,请参阅主动记忆

跨对话记忆

如果只有受信任的个人智能体应使用跨对话的记录回忆,请为该智能体配置:
该值遵循常规 memory.search 继承规则,并可按智能体覆盖。未设置时,仅当全局 session.dmScope 未设置或为 "main",且没有任何绑定包含 session.dmScope 覆盖项时,才默认开启。配置任何私信隔离都会使其默认关闭。显式设置的 truefalse 始终优先。启用此设置意味着为会话记录建立索引,并将 sessions 添加到智能体解析后的记忆来源中。使用 QMD 时,还会启用该智能体的会话导出;此模式不需要单独配置 memory.qmd.sessions.enabled OpenClaw 的内置记忆提供商通过内置和 QMD 后端支持此受保护路径。其他记忆提供商仍可使用其自身的回忆钩子和高级主动记忆工具,但除非当前提供商支持受保护的私密记录回忆,否则会跳过此设置。 openclaw doctor 会报告不受支持的提供商,或报告显式主动记忆 toolsAllow 列表遗漏了 memory_search 此检索边界比常规会话搜索更窄:
  • 只有同一智能体已识别的私密对话才符合条件
  • 排除当前正在回复的对话
  • 群组和频道均不能作为来源或目标
  • 遇到未知对话类型时以关闭状态失败
  • 沙箱隔离的回忆无法使用特殊的跨对话授权
此设置不会更改 tools.sessions.visibility、会话键、记录存储、投递路由,也不会更改 sessions_listsessions_historysessions_send 的权限。主动记忆会执行有界的只读检索过程;检索不可用或超时不会阻止回复。

提供商选择

未设置 provider 时,OpenClaw 使用 OpenAI 嵌入。显式设置 provider 以使用 Bedrock、DeepInfra、Gemini、GitHub Copilot、Mistral、Ollama、Voyage、本地 GGUF 模型或兼容 OpenAI 的 /v1/embeddings 端点。 仍使用 provider: "auto" 的旧版配置会解析为 openai
更改嵌入提供商、模型、提供商设置、来源、作用域、分块方式或分词器可能导致现有 SQLite 向量索引不兼容。 OpenClaw 会暂停向量搜索并报告索引标识警告,而不是自动重新嵌入所有内容。准备就绪后,使用 openclaw memory status --index --agent <id>openclaw memory index --force --agent <id> 重建。
provider 未设置、存在旧版 provider: "auto",或 provider: "none" 有意选择仅 FTS 模式时,嵌入不可用的情况下,记忆回忆仍可使用词法 FTS 排序。 显式指定的非本地提供商会以关闭状态失败。如果将 memory.search.provider 设置为具体的远程后端提供商,例如 Bedrock、DeepInfra、Gemini、GitHub Copilot、LM Studio、Mistral、Ollama、OpenAI、Voyage 或兼容 OpenAI 的自定义提供商,而该提供商在运行时不可用,则 memory_search 会返回不可用结果,而不会静默改用仅 FTS 回忆。请修复提供商或身份验证配置、切换到可访问的提供商,或者如果希望有意使用仅 FTS 回忆,请设置 provider: "none"

自定义提供商 ID

memory.search.provider 可以指向自定义 models.providers.<id> 条目,用于 ollama 等记忆专用提供商适配器,或 openai-responses / openai-completions 等兼容 OpenAI 的模型 API。OpenClaw 会为嵌入适配器解析该提供商的 api 所有者,同时保留自定义提供商 ID,以便处理端点、身份验证和模型前缀。这样,多 GPU 或多主机设置就能将记忆嵌入专用于特定本地端点:

API 密钥解析

远程嵌入需要 API 密钥。Bedrock 则使用 AWS SDK 默认凭证链(实例角色、SSO、访问密钥或 Bedrock API 密钥)。
Codex OAuth 仅涵盖聊天/补全,不能满足嵌入请求。

远程端点配置

对于不应继承全局 OpenAI 聊天凭证的通用兼容 OpenAI 的 /v1/embeddings 服务器,请使用 provider: "openai-compatible"
string
自定义 API 基础 URL。
string
覆盖 API 密钥。
object
额外的 HTTP 标头(与提供商默认值合并)。

提供商特定配置

更改模型或 outputDimensionality 会改变索引标识。OpenClaw 会暂停向量搜索,直到你显式重建记忆索引。
兼容 OpenAI 的嵌入端点可以选择使用提供商特定的 input_type 请求字段。这适用于要求查询嵌入和文档嵌入使用不同标签的非对称嵌入模型。
更改这些值会影响提供商批量索引的嵌入缓存标识;如果上游模型对这些标签的处理方式不同,则更改后应重新索引记忆。

Bedrock 嵌入配置

Bedrock 使用 AWS SDK 默认凭证链以及经 OpenClaw 检查的持有者令牌,因此配置中不会存储 API 密钥。如果 OpenClaw 在具有 Bedrock 使用权限的实例角色所对应的 EC2 上运行,只需设置提供商和模型:
支持的模型(含系列检测和默认维度):带吞吐量后缀的变体(例如 amazon.titan-embed-text-v1:2:8k)和带区域前缀的推理配置文件 ID(例如 us.amazon.titan-embed-text-v2:0)会继承基础模型的配置。**区域:**按以下顺序解析:memory.search.remote.baseUrl 覆盖值、models.providers.amazon-bedrock.baseUrl 配置、AWS_REGIONAWS_DEFAULT_REGION,最后采用默认值 us-east-1**身份验证:**OpenClaw 首先检查 AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEYAWS_BEARER_TOKEN_BEDROCK,然后回退到标准 AWS SDK 默认凭证提供商链:
  1. 环境变量(AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY),除非还设置了 AWS_PROFILE
  2. SSO(仅当配置了 SSO 字段时)
  3. 共享凭证和配置文件(fromIni,包括 AWS_PROFILE
  4. 凭证进程(AWS 配置文件中的 credential_process
  5. Web 身份令牌凭证
  6. ECS 或 EC2 实例元数据凭证
**IAM 权限:**IAM 角色或用户需要:
为遵循最小权限原则,请将 InvokeModel 限定到特定模型:
请先安装官方 llama.cpp 提供商:openclaw plugins install @openclaw/llama-cpp-provider。 默认模型:embeddinggemma-300m-qat-Q8_0.gguf(约 0.6 GB,自动下载)。源码检出仍需要原生构建批准:先执行 pnpm approve-builds,再执行 pnpm rebuild node-llama-cpp使用独立 CLI 验证 Gateway 网关所使用的同一提供商路径:
数值型 local.contextSize 值还会影响 node-llama-cpp 的 GPU 层自动放置,以便同时容纳模型权重和所请求的嵌入上下文。运行时加载后,openclaw memory status --deep 会报告最近一次已知的 llama.cpp 后端、设备、卸载情况、所请求的上下文以及带时间戳的内存信息;被动状态检查不会加载模型。对于本地 GGUF 嵌入,请显式设置 provider: "local"。显式本地配置支持 hf: 和 HTTP(S) 模型引用(通过 node-llama-cpp 的模型解析),但它们不会更改默认提供商。

索引行为

记忆引擎负责同步、批处理、监视以及压缩后的 索引启发式策略。OpenClaw 使用持续维护的默认值启用这些行为, 而不会公开按安装实例设置的时序开关。

混合搜索配置

以下各项均位于 memory.search.query 下: 混合检索保持启用;内置引擎策略仍会禁用 MMR 和时间衰减。

完整示例


其他记忆路径

路径可以是绝对路径,也可以相对于工作区。系统会递归扫描目录中的 .md 文件。符号链接的处理方式取决于当前后端:内置引擎会跳过符号链接,而 QMD 则遵循底层 QMD 扫描器的行为。 对于 Agent 范围内的跨 Agent 记录搜索,请使用 agents.entries.*.memory.search.qmd.extraCollections,而不是 memory.qmd.paths。这些额外集合遵循相同的 { path, name, pattern? } 结构,但它们会按 Agent 合并;当路径指向当前工作区之外时,还可以保留显式共享名称。如果同一解析路径同时出现在 memory.qmd.pathsmemory.search.qmd.extraCollections 中,QMD 会保留第一个条目并跳过重复项。

多模态记忆(Gemini)

使用 Gemini Embedding 2 将图像和音频与 Markdown 一同索引:
仅适用于 extraPaths 中的文件。默认记忆根目录仍仅支持 Markdown。需要 gemini-embedding-2-previewfallback 必须为 "none"
支持的格式:.jpg.jpeg.png.webp.gif.heic.heif(图像);.mp3.wav.ogg.opus.m4a.aac.flac(音频)。

嵌入缓存

避免在重新索引或更新记录期间对未更改的文本重复生成嵌入。

批量索引

适用于 geminiopenaivoyage。对于大规模回填,OpenAI 批处理通常速度最快且成本最低。 并发、轮询和超时行为由提供商负责。

会话记忆搜索

索引会话记录,并通过 memory_search 提供:
会话索引是可选功能,并且异步运行。结果可能略有滞后。会话日志存储在磁盘上,因此应将文件系统访问权限视为信任边界。
由模型调用的普通会话记录搜索遵循 tools.sessions.visibility。默认的 tree 可见性会公开当前会话、由其派生的会话,以及 通过环境群组感知功能监视的同一智能体群组会话。其他 不相关的会话需要 agent 可见性(仅当还需要跨智能体 回忆,并且智能体间策略允许时,才需要 all 可见性)。 rememberAcrossConversations 不会扩大该设置的范围。它提供一项 仅限运行时的独立授权,在有界的主动记忆处理过程中,仅允许访问同一智能体的私有 会话记录。 以下示例将这些设置放在顶层 memory.search 下。如果只有一个 智能体应索引和搜索会话记录,也可以在该智能体的 memory.search 覆盖配置中 应用等效设置。 对于同一智能体从 Gateway 网关到私信的回忆:
使用 QMD 时,仅设置 sources: ["sessions"] 不会将会话记录导出到 QMD。还需设置 memory.qmd.sessions.enabled: true。更高层级的 rememberAcrossConversations: true 设置是例外:它隐含启用该智能体所需的 QMD 会话导出。隐含导出始终保持私有: 它们始终使用默认的内部导出位置(配置的 sessions.exportDir 仅适用于显式导出),仅在该智能体进行跨对话回忆时 被搜索,并且普通的 memory_get 无法读取它们。显式设置 memory.qmd.sessions.enabled: true 会保持其现有行为,使 导出的会话记录成为普通记忆语料库的一部分。

SQLite 向量加速(sqlite-vec)

当 sqlite-vec 不可用时,OpenClaw 会自动回退到进程内余弦相似度计算。

索引存储

内置记忆索引存储在每个智能体的 OpenClaw SQLite 数据库中,路径为 agents/<agentId>/agent/openclaw-agent.sqlite

QMD 后端配置

memory.backend = "qmd" 设为启用。所有 QMD 设置均位于 memory.qmd 下: searchMode: "search" 仅使用词法/BM25。在该模式下,OpenClaw 不会运行语义向量就绪探测或 QMD 嵌入维护,包括在 memory status --deep 期间;vsearchquery 仍然要求 QMD 向量就绪并具备嵌入。 rerank: false 仅更改 QMD 的 query 模式,并要求 QMD 2.1 或更高版本。在直接 CLI 模式下,OpenClaw 会传递 --no-rerank;在由 mcporter 支持的 MCP 模式下,它会将 rerank: false 传递给 QMD 的统一查询工具。保持未设置即可使用 QMD 默认的查询重排序行为。 OpenClaw 优先使用当前的 QMD 集合和 MCP 查询结构,但会在需要时尝试兼容的集合模式标志和旧版 MCP 工具名称,以保持旧版 QMD 可用。当 QMD 声明支持多个集合筛选器时,同源集合会由一个 QMD 进程搜索;旧版 QMD 构建仍使用按集合处理的兼容路径。“同源”是指持久记忆集合(默认记忆文件加自定义路径)会被分为一组,而会话记录集合仍作为单独的一组,以便来源多样化仍可同时使用这两类输入。
QMD 模型覆盖配置保留在 QMD 端,而不在 OpenClaw 配置中。如果需要全局覆盖 QMD 的模型,请在 Gateway 网关运行时环境中设置 QMD_EMBED_MODELQMD_RERANK_MODELQMD_GENERATE_MODEL 等环境变量。
控制哪些会话可以接收 QMD 搜索结果。其结构与 session.sendPolicy 相同:
随附的默认设置仅允许私信/直接会话,拒绝群组和其他渠道类型。match.keyPrefix 匹配规范化的会话键;match.rawKeyPrefix 匹配包括 agent:<id>: 在内的原始键。
memory.citations 适用于所有后端:
QMD 在首次使用记忆时延迟初始化;其适配器负责刷新和嵌入调度。

完整 QMD 示例


Dreaming

Dreaming 配置在 plugins.entries.memory-core.config.dreaming 下,而不是 memory.search 下。 Dreaming 作为一次定时扫描运行,并将内部的轻度/深度/REM 阶段作为实现细节。 有关概念行为和斜杠命令,请参阅 Dreaming

用户设置

示例

  • Dreaming 将机器状态写入 memory/.dreams/
  • Dreaming 将人类可读的叙述输出写入 DREAMS.md(或现有的 dreams.md)。
  • dreaming.model 使用现有的插件子智能体信任门槛;启用前请设置 plugins.entries.memory-core.subagent.allowModelOverride: true
  • 当配置的模型不可用时,Dream Diary 会使用会话默认模型重试一次。信任或允许列表失败会被记录,且不会静默重试。
  • 轻度/深度/REM 阶段策略和阈值属于内部行为,不是面向用户的配置。

相关内容