记忆配置参考

本页列出了 OpenClaw 记忆搜索的所有配置选项。有关概念性概览，请参阅：

除非另有说明，否则所有记忆搜索设置都位于 openclaw.json 中的 agents.defaults.memorySearch 下（或按智能体配置的 agents.list[].memorySearch 覆盖项中）。

提供商选择

未设置 provider 时，OpenClaw 使用 OpenAI 嵌入。要使用 Bedrock、DeepInfra、Gemini、GitHub Copilot、Mistral、Ollama、Voyage、本地 GGUF 模型或 OpenAI 兼容的 /v1/embeddings 端点，请显式设置 provider。 仍使用 provider: "auto" 的旧配置会解析为 openai。

当 provider 未设置、存在旧版 provider: "auto"，或 provider: "none" 有意选择仅 FTS 模式时，即使嵌入不可用，记忆召回仍可使用 FTS 词法排名。

显式指定的非本地提供商会采用失败关闭策略。如果将 memorySearch.provider 设置为 由远程服务支持的具体提供商，例如 Bedrock、DeepInfra、Gemini、GitHub Copilot、LM Studio、Mistral、Ollama、OpenAI、Voyage 或 OpenAI 兼容的 自定义提供商，而该提供商在运行时不可用，则 memory_search 会返回不可用结果，而不是静默使用仅 FTS 召回。请修复 提供商/身份验证配置、切换到可访问的提供商；如果确实需要仅 FTS 召回，也可以设置 provider: "none"。

自定义提供商 ID

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

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

API 密钥解析

远程嵌入需要 API 密钥。Bedrock 则使用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥或 Bedrock API 密钥）。

远程端点配置

对于不应继承全局 OpenAI 聊天凭证的通用 OpenAI 兼容 /v1/embeddings 服务器，请使用 provider: "openai-compatible"。

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        model: "text-embedding-3-small",        remote: {          baseUrl: "https://api.example.com/v1/",          apiKey: "YOUR_KEY",        },      },    },  },}

提供商专用配置

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${EMBEDDINGS_API_KEY}",        },        model: "asymmetric-embedder",        queryInputType: "query",        documentInputType: "passage",      },    },  },}

{  agents: {    defaults: {      memorySearch: {        provider: "bedrock",        model: "amazon.titan-embed-text-v2:0",      },    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

内联嵌入超时

索引行为

除非另有说明，以下配置均位于 memorySearch.sync 下：

混合搜索配置

以下配置均位于 memorySearch.query 下：

以下配置位于 memorySearch.query.hybrid 下：

完整示例

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          hybrid: {            vectorWeight: 0.7,            textWeight: 0.3,            mmr: { enabled: true, lambda: 0.7 },            temporalDecay: { enabled: true, halfLifeDays: 30 },          },        },      },    },  },}

其他记忆路径

{  agents: {    defaults: {      memorySearch: {        extraPaths: ["../team-docs", "/srv/shared-notes"],      },    },  },}

路径可以是绝对路径，也可以是相对于工作区的路径。系统会递归扫描目录中的 .md 文件。符号链接的处理方式取决于启用的后端：内置引擎会跳过符号链接，而 QMD 则遵循底层 QMD 扫描器的行为。

对于 Agent 范围内的跨 Agent 对话记录搜索，请使用 agents.list[].memorySearch.qmd.extraCollections，而不是 memory.qmd.paths。这些额外集合采用相同的 { path, name, pattern? } 结构，但会按 Agent 合并；当路径指向当前工作区之外时，还可保留显式指定的共享名称。如果 memory.qmd.paths 和 memorySearch.qmd.extraCollections 中出现相同的解析后路径，QMD 会保留第一项并跳过重复项。

多模态记忆（Gemini）

使用 Gemini Embedding 2，将图像和音频与 Markdown 一同建立索引：

支持的格式：.jpg、.jpeg、.png、.webp、.gif、.heic、.heif（图像）；.mp3、.wav、.ogg、.opus、.m4a、.aac、.flac（音频）。

嵌入缓存

可防止在重新索引或更新会话记录时对未更改的文本重新生成嵌入。将 maxEntries 保持未设置可使用无上限缓存；当磁盘增长比重新索引的峰值速度更重要时，请设置该值。设置后，一旦缓存超过限制，将首先清理最旧的条目（按最后更新时间排序）。

批量索引

适用于 gemini、openai 和 voyage。对于大规模回填，OpenAI 批处理通常速度最快且成本最低。

remote.nonBatchConcurrency 控制本地/自托管提供商以及未启用提供商批处理 API 时托管提供商所使用的内联嵌入调用。对于非批量索引，Ollama 默认为 1，以避免让较小的本地主机不堪重负；在性能更强的机器上可设置更高的值。

这与 sync.embeddingBatchTimeoutSeconds 不同，后者控制内联嵌入调用的超时时间。

会话记忆搜索（实验性）

为会话记录建立索引，并通过 memory_search 呈现结果：

会话记录命中结果也遵循 tools.sessions.visibility。默认的 tree 可见性仅公开当前会话及其派生的会话。若要从另一个 会话（例如私信）中召回由 Gateway 网关分发的同一智能体但不相关的会话， 请有意将可见性扩大到 agent（仅当还需要跨智能体召回且智能体间策略允许时， 才使用 all）。

以下示例将这些设置放在 agents.defaults 下。如果只有一个 智能体应索引和搜索会话记录，也可以在该智能体的覆盖配置中 应用等效的 memorySearch 设置。

对于从 Gateway 网关到私信的同一智能体召回：

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

使用 QMD 时，仅设置 agents.defaults.memorySearch.experimental.sessionMemory 和 sources: ["sessions"] 不会将会话记录导出到 QMD。还需要设置 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 期间；vsearch 和 query 仍需要 QMD 向量就绪和嵌入。

rerank: false 仅更改 QMD 的 query 模式，并且需要 QMD 2.1 或更高版本。在直接 CLI 模式下，OpenClaw 会传递 --no-rerank；在由 mcporter 支持的 MCP 模式下，它会向 QMD 的统一查询工具传递 rerank: false。保持未设置可使用 QMD 的默认查询重排序行为。

OpenClaw 优先使用当前的 QMD 集合和 MCP 查询形式，但在需要时会尝试兼容的集合模式标志和旧版 MCP 工具名称，以保持旧版 QMD 正常工作。当 QMD 声明支持多个集合过滤器时，同源集合会由单个 QMD 进程搜索；旧版 QMD 构建则继续使用按集合区分的兼容路径。“同源”是指持久记忆集合（默认记忆文件加自定义路径）归为一组，而会话记录集合仍作为单独一组，因此来源多样化仍具有两类输入。

mcporter 集成

所有设置均位于 memory.qmd.mcporter 下。通过长时间运行的 mcporter MCP 守护进程路由 QMD 搜索，而不是每次查询都启动 qmd，从而减少大型模型的冷启动开销。

需要安装 mcporter 并确保其位于 PATH 中，还需要配置一个运行 qmd mcp 的 mcporter 服务器。对于可以接受每次查询启动进程开销的简单本地设置，请保持禁用。

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

启用 Gateway 网关启动时 QMD 初始化后，OpenClaw 只会为符合条件的智能体启动 QMD。如果 update.onBoot 为 true，且未配置间隔/嵌入维护，启动时会使用一次性管理器执行启动刷新，然后将其关闭。如果配置了更新或嵌入间隔，启动时会打开长驻 QMD 管理器，由其管理监视器和间隔计时器；update.onBoot: false 只跳过启动时的立即刷新。

完整 QMD 示例

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, timeoutMs: 4000 },      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

Dreaming

Dreaming 在 plugins.entries.memory-core.config.dreaming 下配置，而不是在 agents.defaults.memorySearch 下配置。

Dreaming 作为一次定时扫描运行，并将内部的轻度/深度/REM 阶段作为实现细节。

有关概念行为和斜杠命令，请参阅 Dreaming。

用户设置

示例

{  plugins: {    entries: {      "memory-core": {        subagent: {          allowModelOverride: true,          allowedModels: ["anthropic/claude-sonnet-4-6"],        },        config: {          dreaming: {            enabled: true,            frequency: "0 3 * * *",            model: "anthropic/claude-sonnet-4-6",          },        },      },    },  },}

相关内容

• 配置参考
• 记忆概览
• 记忆搜索