Skip to main content
本页列出了 OpenClaw 内存搜索的每一个配置项。概念性概览请参见：

内存概览

内存如何工作。

内置引擎

默认的 SQLite 后端。

QMD 引擎

本地优先的 sidecar。

内存搜索

搜索流程与调优。

活动内存

用于交互式会话的内存子代理。
除非另有说明，所有内存搜索设置都位于 openclaw.json 中的 agents.defaults.memorySearch 下。
如果你在寻找 活动内存 功能开关和子代理配置，它位于 plugins.entries.active-memory 下，而不是 memorySearch。活动内存使用双门控模型：
  1. 插件必须启用并且目标指向当前 agent id
  2. 请求必须是符合条件的交互式持久聊天会话
有关激活模型、插件拥有的配置、对话转录持久化以及安全发布模式，请参见 活动内存。

​
提供方选择

KeyTypeDefaultDescription
providerstring"openai"嵌入适配器 ID，例如 bedrock、deepinfra、gemini、github-copilot、local、mistral、ollama、openai、openai-compatible 或 voyage；也可以是已配置的 models.providers.<id>，其 api 指向内存嵌入适配器或 OpenAI 兼容的模型 API
modelstringprovider default嵌入模型名称
fallbackstring"none"主提供方失败时使用的回退适配器 ID
enabledbooleantrue启用或禁用内存搜索
当未设置 provider 时，OpenClaw 使用 OpenAI 嵌入。显式设置 provider 即可使用 Gemini、Voyage、Mistral、DeepInfra、Bedrock、GitHub Copilot、 Ollama、本地 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 排名。 显式的非本地提供方会失败关闭。如果你将 memorySearch.provider 设置为 诸如 OpenAI、Gemini、Voyage、Mistral、 Bedrock、GitHub Copilot、DeepInfra、Ollama、LM Studio 或 OpenAI 兼容 自定义提供方这样的具体远程后端，而该提供方在运行时不可用，memory_search 会返回不可用结果，而不会静默退回到仅 FTS 召回。请修复 提供方/认证配置，切换到可访问的提供方，或在你希望明确使用仅 FTS 召回时 设置 provider: "none"。

​
自定义 provider id

memorySearch.provider 可以指向自定义的 models.providers.<id> 条目，用于内存专用的提供方适配器，例如 ollama，或用于 OpenAI 兼容的模型 API，例如 openai-responses / openai-completions。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" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

​
API 密钥解析

远程嵌入需要 API 密钥。Bedrock 则使用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。
ProviderEnv varConfig key
BedrockAWS credential chain不需要 API 密钥
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN、GH_TOKEN、GITHUB_TOKEN通过设备登录的认证配置文件
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY（占位符）—
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.providers.voyage.apiKey
Codex OAuth 仅覆盖聊天/补全，不满足嵌入请求。

​
远程端点配置

对于不应继承全局 OpenAI 聊天凭证的通用 OpenAI 兼容 /v1/embeddings 服务，请使用 provider: "openai-compatible"。
​
remote.baseUrl
string
自定义 API 基础 URL。
​
remote.apiKey
string
覆盖 API 密钥。
​
remote.headers
object
额外的 HTTP 标头（与提供方默认值合并）。
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai-compatible",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

​
提供方特定配置

KeyTypeDefaultDescription
modelstringgemini-embedding-001也支持 gemini-embedding-2-preview
outputDimensionalitynumber3072对于 Embedding 2：768、1536 或 3072
更改模型或 outputDimensionality 会改变索引身份。OpenClaw 会暂停向量搜索，直到你显式重建内存索引。
OpenAI 兼容的嵌入端点可以选择启用提供方特定的 input_type 请求字段。这对于需要为查询和文档嵌入使用不同标签的非对称嵌入模型很有用。
KeyTypeDefaultDescription
inputTypestringunset查询和文档嵌入共享的 input_type
queryInputTypestringunset查询时的 input_type；覆盖 inputType
documentInputTypestringunset索引/文档的 input_type；覆盖 inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai-compatible",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "${EMBEDDINGS_API_KEY}",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
更改这些值会影响提供方批量索引的嵌入缓存标识，当上游模型对这些标签的处理方式不同时时，应随后执行一次内存重建索引。

​
Bedrock 嵌入配置

Bedrock 使用 AWS SDK 默认凭证链——无需 API 密钥。如果 OpenClaw 运行在启用了 Bedrock 的 EC2 实例角色上，只需设置 provider 和 model：
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
KeyTypeDefaultDescription
modelstringamazon.titan-embed-text-v2:0任意 Bedrock 嵌入模型 ID
outputDimensionalitynumbermodel default对于 Titan V2：256、512 或 1024
支持的模型（带有家族检测和维度默认值）：
Model IDProviderDefault DimsConfigurable Dims
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 令牌缓存
  3. Web Identity 令牌凭证
  4. 共享凭证和配置文件
  5. ECS 或 EC2 元数据凭证
区域从 AWS_REGION、AWS_DEFAULT_REGION、amazon-bedrock 提供方的 baseUrl 中解析，或默认为 us-east-1。IAM 权限： IAM 角色或用户需要：
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
为遵循最小权限原则，可将 InvokeModel 限定到特定模型：
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
KeyTypeDefaultDescription
local.modelPathstringauto-downloadedGGUF 模型文件路径
local.modelCacheDirstringnode-llama-cpp default下载模型的缓存目录
local.contextSizenumber | "auto"4096嵌入上下文的上下文窗口大小。4096 可覆盖典型分块（128–512 tokens），同时限制非权重显存。受限主机上可降至 1024–2048。"auto" 使用模型训练的最大值——不建议用于 8B+ 模型（Qwen3-Embedding-8B：40 960 tokens → 约 32 GB VRAM，而在 4096 时约为 8.8 GB）。
默认模型：embeddinggemma-300m-qat-Q8_0.gguf（约 0.6 GB，自动下载）。源代码检出版本仍需要本地原生构建审批：先执行 pnpm approve-builds，再执行 pnpm rebuild node-llama-cpp。使用独立 CLI 验证 Gateway 使用的相同 provider 路径：
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
对于本地 GGUF 嵌入，请显式设置 provider: "local"。hf: 和 HTTP(S) 模型引用在显式本地配置中受支持，但不会改变默认 provider。

​
内联嵌入超时

​
sync.embeddingBatchTimeoutSeconds
number
覆盖内存索引期间内联嵌入批次的超时时间。未设置时使用提供方默认值：本地/自托管提供方（如 local、ollama 和 lmstudio）为 600 秒，托管提供方为 120 秒。当本地 CPU 受限的嵌入批次运行正常但较慢时，可增大该值。

​
混合搜索配置

全部位于 memorySearch.query.hybrid 下：
键类型默认值描述
enabledbooleantrue启用混合 BM25 + 向量搜索
vectorWeightnumber0.7向量分数权重（0-1）
textWeightnumber0.3BM25 分数权重（0-1）
candidateMultipliernumber4候选池大小乘数
键类型默认值描述
mmr.enabledbooleanfalse启用 MMR 重排序
mmr.lambdanumber0.70 = 最大多样性，1 = 最大相关性

​
完整示例

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

​
附加内存路径

键类型描述
extraPathsstring[]要索引的额外目录或文件
{
  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 一起建立索引：
键类型默认值描述
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.enabledbooleantrue在 SQLite 中缓存分块嵌入
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 是分开的，后者控制内联嵌入调用的超时时间。

​
会话内存搜索（实验性）

索引会话记录，并通过 memory_search 暴露它们：
键类型默认值描述
experimental.sessionMemorybooleanfalse启用会话索引
sourcesstring[]["memory"]添加 "sessions" 以包含会话记录
sync.sessions.deltaBytesnumber100000重新索引的字节阈值
sync.sessions.deltaMessagesnumber50重新索引的消息阈值
会话索引需要显式启用，并且以异步方式运行。结果可能会略有延迟。会话日志保存在磁盘上，因此请将文件系统访问视为信任边界。

​
SQLite 向量加速（sqlite-vec）

键类型默认值描述
store.vector.enabledbooleantrue使用 sqlite-vec 进行向量查询
store.vector.extensionPathstringbundled覆盖 sqlite-vec 路径
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度。

​
索引存储

键类型默认值描述
store.pathstring~/.openclaw/memory/{agentId}.sqlite索引位置（支持 {agentId} 令牌）
store.fts.tokenizerstringunicode61FTS5 分词器（unicode61 或 trigram）

​
QMD 后端配置

设置 memory.backend = "qmd" 以启用。所有 QMD 设置都位于 memory.qmd 下：
键类型默认值描述
commandstringqmdQMD 可执行文件路径；当服务 PATH 与你的 shell 不同时，请设置绝对路径
searchModestringsearch搜索命令：search、vsearch、query
rerankboolean—与 searchMode: "query" 和 QMD 2.1+ 一起设为 false 可跳过 QMD 重排序
includeDefaultMemorybooleantrue自动索引 MEMORY.md + memory/**/*.md
paths[]array—额外路径：{ name, path, pattern? }
sessions.enabledbooleanfalse索引会话转录
sessions.retentionDaysnumber—转录保留时间
sessions.exportDirstring—导出目录
searchMode: "search" 仅支持词法/BM25。OpenClaw 不会为该模式运行语义向量就绪探测或 QMD 嵌入维护，包括在 memory status --deep 期间；vsearch 和 query 仍然需要 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 的模型，请在网关运行时环境中设置 QMD_EMBED_MODEL、QMD_RERANK_MODEL 和 QMD_GENERATE_MODEL 等环境变量。
键类型默认值描述
update.intervalstring5m刷新间隔
update.debounceMsnumber15000文件变更防抖
update.onBootbooleantrue当长期运行的 QMD 管理器打开时刷新；也控制显式启用的启动刷新
update.startupstringoff可选的网关启动刷新：off、idle 或 immediate
update.startupDelayMsnumber120000startup: "idle" 刷新开始前的延迟
update.waitForBootSyncbooleanfalse在初始刷新完成前阻塞管理器打开
update.embedIntervalstring—单独的嵌入节奏
update.commandTimeoutMsnumber—QMD 命令超时
update.updateTimeoutMsnumber—QMD 更新操作超时
update.embedTimeoutMsnumber—QMD 嵌入操作超时
键类型默认值描述
limits.maxResultsnumber6最大搜索结果数
limits.maxSnippetCharsnumber—截断片段长度
limits.maxInjectedCharsnumber—截断注入字符总数
limits.timeoutMsnumber4000搜索超时时间
控制哪些会话可以接收 QMD 搜索结果。与 session.sendPolicy 具有相同的 schema：
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
默认配置允许直接会话和频道会话，同时仍然拒绝群组。默认仅适用于 DM。match.keyPrefix 匹配规范化后的会话键；match.rawKeyPrefix 匹配包含 agent:<id>: 的原始键。
memory.citations 适用于所有后端：
值行为
auto（默认）在片段中包含 Source: <path#line> 页脚
on始终包含页脚
off省略页脚（路径仍会在内部传递给 agent）
QMD 启动刷新在网关启动期间使用一次性子进程路径。当内存搜索被打开用于交互式使用时，长期运行的 QMD 管理器仍然负责常规文件监听器和间隔计时器。

​
完整 QMD 示例

{
  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 作为一次计划性扫描运行，并将内部的浅层/深层/REM 阶段作为实现细节。 有关概念性行为和斜杠命令，请参见 Dreaming。

​
用户设置

KeyTypeDefaultDescription
enabledbooleanfalse完全启用或禁用 dreaming
frequencystring0 3 * * *可选的完整 dreaming 扫描 cron 频率
modelstringdefault model可选的 Dream Diary 子代理模型覆盖
phases.deep.maxPromotedSnippetTokensnumber160每个提升到 MEMORY.md 的短期回忆片段所保留的最大估计 token 数；来源元数据仍保持可见

​
示例

{
  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 会使用会话默认模型重试一次。信任或允许列表失败会被记录日志，不会被静默重试。
  • 浅层/深层/REM 阶段策略和阈值属于内部行为，不是面向用户的配置。

​
相关内容