古法编程

Appearance

本页列出 OpenClaw 记忆搜索的每一个配置项。涵盖嵌入提供商自动检测逻辑、API 密钥解析、Gemini/Bedrock/本地嵌入专项配置、混合搜索调优（BM25+向量权重、MMR 多样性、时间衰减）、多模态索引、QMD 后端完整参数，以及 Dreaming 实验性功能的配置入口。

记忆搜索配置参考 ​

本页列出 OpenClaw 记忆搜索的所有配置项。概念层面的说明请参见：

除非另有说明，所有记忆搜索配置均位于 openclaw.json 的 agents.defaults.memorySearch 下。

提供商选择 ​

配置项类型默认值说明
providerstring自动检测嵌入适配器 ID：openai、gemini、voyage、mistral、bedrock、ollama、local
modelstring提供商默认嵌入模型名称
fallbackstring"none"主提供商失败时的备用适配器 ID
enabledbooleantrue启用或禁用记忆搜索

自动检测顺序 ​

未设置 provider 时，OpenClaw 按顺序选择第一个可用的：

  1. local — 如果 memorySearch.local.modelPath 已配置且文件存在。
  2. openai — 如果能解析到 OpenAI 密钥。
  3. gemini — 如果能解析到 Gemini 密钥。
  4. voyage — 如果能解析到 Voyage 密钥。
  5. mistral — 如果能解析到 Mistral 密钥。
  6. bedrock — 如果 AWS SDK 凭证链能解析（实例角色、访问密钥、profile、SSO、Web identity 或共享配置）。

ollama 支持但不会自动检测（需要显式设置）。

API 密钥解析 ​

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

提供商环境变量配置项
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
BedrockAWS 凭证链不需要 API 密钥
OllamaOLLAMA_API_KEY（占位符）—

Codex OAuth 只覆盖 chat/completions，不满足嵌入请求。

远程端点配置 ​

自定义 OpenAI 兼容端点或覆盖提供商默认值：

配置项类型说明
remote.baseUrlstring自定义 API 基础 URL
remote.apiKeystring覆盖 API 密钥
remote.headersobject额外 HTTP 头（与提供商默认值合并）
json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Gemini 专项配置 ​

配置项类型默认值说明
modelstringgemini-embedding-001也支持 gemini-embedding-2-preview
outputDimensionalitynumber3072Embedding 2 支持 768、1536 或 3072

注意：修改 model 或 outputDimensionality 会触发自动全量重新索引。

Bedrock 嵌入配置 ​

Bedrock 使用 AWS SDK 默认凭证链，不需要 API 密钥。如果 OpenClaw 运行在有 Bedrock 权限的 EC2 上，只需设置提供商和模型：

json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
配置项类型默认值说明
modelstringamazon.titan-embed-text-v2:0任意 Bedrock 嵌入模型 ID
outputDimensionalitynumber模型默认Titan V2 支持 256、512 或 1024

支持的模型 ​

模型 ID提供商默认维度可配置维度
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536—
amazon.titan-embed-g1-text-02Amazon1536—
amazon.titan-embed-image-v1Amazon1024—
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024—
cohere.embed-multilingual-v3Cohere1024—
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512—
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024—

吞吐量后缀变体（如 amazon.titan-embed-text-v1:2:8k）继承基础模型配置。

认证顺序 ​

Bedrock 使用标准 AWS SDK 凭证解析顺序：

  1. 环境变量（AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY）
  2. SSO token 缓存
  3. Web identity token 凭证
  4. 共享凭证和配置文件
  5. ECS 或 EC2 元数据凭证

Region 从 AWS_REGION、AWS_DEFAULT_REGION、amazon-bedrock 提供商 baseUrl 解析，默认 us-east-1。

IAM 权限 ​

IAM 角色或用户需要：

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

最小权限，可将 InvokeModel 限定到具体模型：

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

本地嵌入配置 ​

配置项类型默认值说明
local.modelPathstring自动下载GGUF 模型文件路径
local.modelCacheDirstringnode-llama-cpp 默认下载模型的缓存目录

默认模型：embeddinggemma-300m-qat-Q8_0.gguf（约 0.6GB，自动下载）。 需要原生构建：pnpm approve-builds 然后 pnpm rebuild node-llama-cpp。

混合搜索配置 ​

所有配置均在 memorySearch.query.hybrid 下：

配置项类型默认值说明
enabledbooleantrue启用 BM25 + 向量混合搜索
vectorWeightnumber0.7向量分数权重（0-1）
textWeightnumber0.3BM25 分数权重（0-1）
candidateMultipliernumber4候选池大小倍数

MMR（多样性） ​

配置项类型默认值说明
mmr.enabledbooleanfalse启用 MMR 重排序
mmr.lambdanumber0.70 = 最大多样性，1 = 最大相关性

时间衰减（近期优先） ​

配置项类型默认值说明
temporalDecay.enabledbooleanfalse启用近期加成
temporalDecay.halfLifeDaysnumber30每 N 天分数减半

常青文件（MEMORY.md、memory/ 下无日期文件）不会衰减。

完整示例 ​

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

额外记忆路径 ​

配置项类型说明
extraPathsstring[]额外需要索引的目录或文件
json5
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}

路径可以是绝对路径或相对 workspace 的路径。目录会递归扫描 .md 文件。符号链接处理取决于后端：内置引擎忽略符号链接，QMD 遵循底层扫描器行为。

跨 agent 的转录搜索请用 agents.list[].memorySearch.qmd.extraCollections，而非 memory.qmd.paths。Extra collections 使用相同的 { path, name, pattern? } 结构，按 agent 合并，并在路径指向 workspace 外时保留显式共享名称。若同一解析路径同时出现在 memory.qmd.paths 和 memorySearch.qmd.extraCollections 中，QMD 保留第一条并跳过重复项。

多模态记忆（Gemini） ​

使用 Gemini Embedding 2 同时索引图片和音频：

配置项类型默认值说明
multimodal.enabledbooleanfalse启用多模态索引
multimodal.modalitiesstring[]—["image"]、["audio"] 或 ["all"]
multimodal.maxFileBytesnumber10000000索引的最大文件大小

仅适用于 extraPaths 中的文件。默认记忆根目录仍只索引 Markdown。 需要 gemini-embedding-2-preview，且 fallback 必须为 "none"。

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

嵌入缓存 ​

配置项类型默认值说明
cache.enabledbooleanfalse在 SQLite 中缓存 chunk 嵌入
cache.maxEntriesnumber50000最大缓存嵌入数

在重新索引或转录更新时，避免对未变更文本重复嵌入。

批量索引 ​

配置项类型默认值说明
remote.batch.enabledbooleanfalse启用批量嵌入 API
remote.batch.concurrencynumber2并行批次数
remote.batch.waitbooleantrue等待批次完成
remote.batch.pollIntervalMsnumber—轮询间隔
remote.batch.timeoutMinutesnumber—批次超时时间

适用于 openai、gemini 和 voyage。OpenAI 批量通常最快也最便宜，适合大规模回填。

Session 记忆搜索（实验性） ​

索引 session 转录并通过 memory_search 工具展示：

配置项类型默认值说明
experimental.sessionMemorybooleanfalse启用 session 索引
sourcesstring[]["memory"]添加 "sessions" 可包含转录
sync.sessions.deltaBytesnumber100000触发重新索引的字节阈值
sync.sessions.deltaMessagesnumber50触发重新索引的消息数阈值

Session 索引需要手动开启，异步运行，结果可能略有延迟。Session 日志存储在磁盘，文件系统访问即为信任边界。

SQLite 向量加速（sqlite-vec） ​

配置项类型默认值说明
store.vector.enabledbooleantrue使用 sqlite-vec 进行向量查询
store.vector.extensionPathstring内置覆盖 sqlite-vec 路径

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

索引存储 ​

配置项类型默认值说明
store.pathstring~/.openclaw/memory/{agentId}.sqlite索引位置（支持 {agentId} token）
store.fts.tokenizerstringunicode61FTS5 分词器（unicode61 或 trigram）

QMD 后端配置 ​

设置 memory.backend = "qmd" 启用。所有 QMD 配置位于 memory.qmd 下：

配置项类型默认值说明
commandstringqmdQMD 可执行文件路径
searchModestringsearch搜索命令：search、vsearch、query
includeDefaultMemorybooleantrue自动索引 MEMORY.md + memory/**/*.md
paths[]array—额外路径：{ name, path, pattern? }
sessions.enabledbooleanfalse索引 session 转录
sessions.retentionDaysnumber—转录保留天数
sessions.exportDirstring—导出目录

OpenClaw 优先使用当前 QMD collection 和 MCP query 格式，但在检测到旧版 QMD 时会回退到传统 --mask collection 标志和旧 MCP 工具名。

QMD 模型覆盖配置在 QMD 侧而非 OpenClaw 配置中。如需全局覆盖 QMD 模型，可在 gateway 运行时环境中设置 QMD_EMBED_MODEL、QMD_RERANK_MODEL、QMD_GENERATE_MODEL 等环境变量。

更新计划 ​

配置项类型默认值说明
update.intervalstring5m刷新间隔
update.debounceMsnumber15000文件变更防抖时间
update.onBootbooleantrue启动时刷新
update.waitForBootSyncbooleanfalse阻塞启动直到刷新完成
update.embedIntervalstring—单独的嵌入节奏
update.commandTimeoutMsnumber—QMD 命令超时
update.updateTimeoutMsnumber—QMD 更新操作超时
update.embedTimeoutMsnumber—QMD 嵌入操作超时

限制 ​

配置项类型默认值说明
limits.maxResultsnumber6最大搜索结果数
limits.maxSnippetCharsnumber—截断片段长度
limits.maxInjectedCharsnumber—截断总注入字符数
limits.timeoutMsnumber4000搜索超时

完整 QMD 示例 ​

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

作用域（Scope） ​

控制哪些 session 能收到 QMD 搜索结果，与 session.sendPolicy 使用相同的 schema：

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

默认仅限私信（DM）。match.keyPrefix 匹配规范化后的 session key；match.rawKeyPrefix 匹配包含 agent:<id>: 前缀的原始 key。

Citations（引用标注） ​

memory.citations 适用于所有后端：

值行为
auto（默认）在片段末尾加 Source: <path#line> 注脚
on始终加注脚
off省略注脚（路径仍在内部传递给 agent）

Dreaming（实验性） ​

Dreaming 配置位于 plugins.entries.memory-core.config.dreaming，而非 agents.defaults.memorySearch。

Dreaming 作为一个定时扫描运行，内部使用 light/deep/REM 阶段作为实现细节。

概念行为和斜杠命令请参见 Dreaming。

用户配置 ​

配置项类型默认值说明
enabledbooleanfalse启用或禁用 Dreaming
frequencystring0 3 * * *Dreaming 全量扫描的可选 cron 节奏

示例 ​

json5
{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
          },
        },
      },
    },
  },
}

说明：

  • Dreaming 将机器状态写入 memory/.dreams/。
  • Dreaming 将人类可读的叙述输出写入 DREAMS.md（或已有的 dreams.md）。
  • light/deep/REM 阶段的策略和阈值是内部行为，不对外暴露配置。

常见问题 ​

Q: 如何确认当前用的是哪个嵌入提供商？

A: 运行 openclaw doctor 可以看到记忆搜索当前使用的提供商和模型信息。如果想确认 API 密钥是否被正确识别，也可以查看启动日志中 memorySearch 相关的行。

Q: 切换嵌入模型后需要重新索引吗？

A: 是的。切换嵌入模型（或修改 outputDimensionality）后，向量空间发生变化，旧索引会失效，OpenClaw 会触发自动全量重新索引。

Q: QMD 和内置引擎应该怎么选？

A: 记忆文件不多（千级 Markdown）且不需要复杂搜索策略的情况下，用内置 SQLite 引擎开箱即用就够了。记忆量大（万级文件）或需要更精细的搜索控制（语义搜索模式、独立 embed 调度）时，考虑 QMD 后端。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策