古法编程

Appearance

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

OpenClaw 记忆搜索配置参考：嵌入模型、QMD、混合搜索全解析 ​

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

注意：如果你要找的是 active memory 功能开关和子代理配置，那在 plugins.entries.active-memory 下，不在 memorySearch 里。Active memory 使用双闸控制：插件必须启用且目标指定当前 agent ID；请求必须是符合条件的交互式持久聊天会话。详见 Active Memory。

嵌入提供商选择 ​

键名类型默认值说明
providerstring自动检测嵌入适配器 ID：bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai, voyage；也可以是已配置的 models.providers.<id>（其 api 指向上述适配器之一）
modelstring提供商默认嵌入模型名称
fallbackstring"none"主提供商失败时使用的备用适配器 ID
enabledbooleantrue启用或禁用记忆搜索

自动检测顺序 ​

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

  1. local — memorySearch.local.modelPath 已配置且文件存在。
  2. github-copilot — GitHub Copilot token 可解析（环境变量或 auth profile）。
  3. openai — OpenAI 密钥可解析。
  4. gemini — Gemini 密钥可解析。
  5. voyage — Voyage 密钥可解析。
  6. mistral — Mistral 密钥可解析。
  7. deepinfra — DeepInfra 密钥可解析。
  8. bedrock — AWS SDK 凭证链可解析（实例角色、访问密钥、profile、SSO、web identity 或共享配置）。

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

自定义提供商 ID ​

memorySearch.provider 可以指向一个自定义的 models.providers.<id> 条目。OpenClaw 会用该提供商的 api 所有者来确定嵌入适配器，同时保留自定义 ID 用于端点、认证和模型前缀处理。这允许多 GPU 或多主机环境为记忆嵌入指定专属的本地端点：

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

API 密钥解析 ​

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

提供商环境变量配置键
BedrockAWS 凭证链无需 API 密钥
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN通过设备登录的 Auth profile
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY（占位符）--
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey

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

远程端点配置 ​

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

remote.baseUrl string

remote.apiKey string

remote.headers object

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

提供商专项配置 ​

Gemini 配置

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
| `outputDimensionality` | `number` | `3072` | Embedding 2：可选 768, 1536, 3072 |

<Warning>修改模型或 `outputDimensionality` 会触发自动全量重新索引。</Warning>

OpenAI 兼容输入类型

OpenAI 兼容的嵌入端点可以选择 `input_type` 请求字段。这对于需要为查询和文档嵌入使用不同标签的非对称嵌入模型很有用。

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `inputType` | `string` | 未设置 | 共享的 `input_type`（查询和文档都使用） |
| `queryInputType` | `string` | 未设置 | 查询时的 `input_type`；覆盖 `inputType` |
| `documentInputType` | `string` | 未设置 | 索引/文档时的 `input_type`；覆盖 `inputType` |

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

修改这些值会影响提供商批量索引的嵌入缓存标识。上游模型对不同标签的处理方式不同时，建议在修改后重新索引记忆。

Bedrock 嵌入配置

Bedrock 使用 AWS SDK 默认凭证链，无需 API 密钥。如果 OpenClaw 运行在启用了 Bedrock 实例角色的 EC2 上，只需设置提供商和模型：

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

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
| `outputDimensionality` | `number` | 模型默认 | Titan V2：256, 512, 1024 |

**支持的模型**（含家族检测和维度默认值）：

| 模型 ID | 提供商 | 默认维度 | 可配置维度 |
| --- | --- | --- | --- |
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |

吞吐量后缀变体（如 `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
```

本地嵌入（GGUF + node-llama-cpp）

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件路径 |
| `local.modelCacheDir` | `string` | node-llama-cpp 默认 | 已下载模型的缓存目录 |
| `local.contextSize` | `number \| "auto"` | `4096` | 嵌入上下文的窗口大小。4096 可覆盖典型 chunk（128-512 tokens）同时控制非权重 VRAM。资源受限的主机上可降至 1024-2048。`"auto"` 使用模型训练的最大值——不建议用于 8B+ 模型（Qwen3-Embedding-8B：40,960 tokens → 约 32 GB VRAM vs 8.8 GB @ 4096）。 |

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

使用独立 CLI 验证 Gateway 使用的相同提供商路径：
```bash
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
```

如果 `provider` 是 `auto`，只有在 `local.modelPath` 指向一个已存在的本地文件时，`local` 才会被选中。`hf:` 和 HTTP(S) 模型引用可以显式地与 `provider: "local"` 一起使用，但在模型下载到磁盘前不会让 `auto` 选择 local。

内联嵌入超时 ​

sync.embeddingBatchTimeoutSeconds number

覆盖记忆索引期间内联嵌入批次的超时时间。

未设置时使用提供商默认值：本地/自托管提供商（如 local, ollama, lmstudio）为 600 秒，托管提供商为 120 秒。如果本地 CPU 密集型嵌入批次运行正常但偏慢，可以增加此值。

混合搜索配置 ​

所有配置位于 memorySearch.query.hybrid 下：

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

MMR 多样性

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |

时间衰减（近期优先）

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `temporalDecay.enabled` | `boolean` | `false` | 启用近期加成 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 每 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.nonBatchConcurrencynumber4并行内联嵌入数
remote.batch.enabledbooleanfalse启用批量嵌入 API
remote.batch.concurrencynumber2并行批量任务数
remote.batch.waitbooleantrue等待批次完成
remote.batch.pollIntervalMsnumber--轮询间隔
remote.batch.timeoutMinutesnumber--批次超时时间

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

remote.nonBatchConcurrency 控制内联嵌入调用，用于本地/自托管提供商以及未使用提供商批量 API 的托管提供商。Ollama 在非批量索引时默认值为 1，以避免压垮较小的本地主机。更大的机器上可以设置更高的值。

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

Session 记忆搜索（实验性） ​

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

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

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 可执行文件路径；当服务 PATH 与你的 shell 不同时，使用绝对路径
searchModestringsearch搜索命令：search, vsearch, query
includeDefaultMemorybooleantrue自动索引 MEMORY.md + memory/**/*.md
paths[]array--额外路径：{ name, path, pattern? }
sessions.enabledbooleanfalse索引 session 转录
sessions.retentionDaysnumber--转录保留天数
sessions.exportDirstring--导出目录

searchMode: "search" 是纯词法/BM25 搜索。OpenClaw 不会为此模式运行语义向量就绪性探测或 QMD 嵌入维护，包括在 memory status --deep 期间；vsearch 和 query 模式仍需 QMD 向量就绪和嵌入。

OpenClaw 优先使用当前的 QMD collection 和 MCP query 格式，但在检测到旧版 QMD 时会回退到传统 --mask 标记和旧的 MCP 工具名。当 QMD 声明支持多个 collection 过滤器时，同源的 collection 会用一个 QMD 进程搜索；旧版 QMD 保持每个 collection 的兼容路径。同源指持久记忆 collection 被分组在一起，而 session 转录 collection 保持独立组，因此来源多样化仍有两个输入。

注意：QMD 模型覆盖配置在 QMD 侧而非 OpenClaw 配置中。如需全局覆盖 QMD 的模型，可在 gateway 运行时环境中设置 QMD_EMBED_MODEL、QMD_RERANK_MODEL 和 QMD_GENERATE_MODEL。

更新计划

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `update.interval` | `string` | `5m` | 刷新间隔 |
| `update.debounceMs` | `number` | `15000` | 文件变更防抖时间 |
| `update.onBoot` | `boolean` | `true` | 长驻 QMD manager 打开时刷新；同时也作为启动刷新的 opt-in 门控 |
| `update.startup` | `string` | `off` | 可选的 Gateway 启动刷新：`off`, `idle`, 或 `immediate` |
| `update.startupDelayMs` | `number` | `120000` | `startup: "idle"` 刷新开始前的延迟 |
| `update.waitForBootSync` | `boolean` | `false` | 阻塞 manager 打开，直到初始刷新完成 |
| `update.embedInterval` | `string` | -- | 单独的嵌入节奏 |
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时 |
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时 |
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时 |

限制

| 键名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
| `limits.maxSnippetChars` | `number` | -- | 截断片段长度 |
| `limits.maxInjectedChars` | `number` | -- | 截断总注入字符数 |
| `limits.timeoutMs` | `number` | `4000` | 搜索超时 |

作用域

控制哪些 session 能收到 QMD 搜索结果。与 [`session.sendPolicy`](/ai/ai-tools/openclaw/gateway/configuration-reference#session) 使用相同的 schema：

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

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

引用标注

`memory.citations` 适用于所有后端：

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

QMD 启动刷新在 Gateway 启动期间使用一次性子进程路径。当记忆搜索为交互式使用打开后，长驻 QMD manager 接管常规文件监听器和间隔定时器。

完整 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" }],
    },
  },
}

Dreaming（实验性） ​

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

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

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

用户配置 ​

键名类型默认值说明
enabledbooleanfalse启用或禁用 Dreaming
frequencystring0 3 * * *全量 Dreaming 扫描的 cron 节奏
modelstring默认模型可选的 Dream Diary 子代理模型覆盖

示例 ​

json5
{
  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",
          },
        },
      },
    },
  },
}

注意：

  • Dreaming 将机器状态写入 memory/.dreams/。
  • Dreaming 将人类可读的叙述输出写入 DREAMS.md（或已有的 dreams.md）。
  • dreaming.model 使用现有的插件子代理信任门控；需先设置 plugins.entries.memory-core.subagent.allowModelOverride: true 再启用。
  • Dream Diary 在配置的模型不可用时，会用 session 默认模型重试一次。信任或允许列表失败会被记录，不会静默重试。
  • light/deep/REM 阶段的策略和阈值是内部行为，不对外暴露配置。

相关 ​

常见问题 ​

怎么确认当前用的是哪个嵌入提供商？ ​

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

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

需要。切换嵌入模型（或修改 outputDimensionality）后，向量空间发生变化，旧索引会失效。Gemini 和 Bedrock 等提供商会自动触发全量重新索引。

QMD 和内置引擎怎么选？ ​

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

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

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