学了个寂寞

Appearance

记忆配置参考 ​

本页涵盖 OpenClaw 记忆搜索的完整配置选项。关于概念性介绍（文件布局、记忆工具、何时写入记忆、自动刷新机制），请参见 记忆系统。

记忆搜索默认行为 ​

  • 默认启用。
  • 监听记忆文件变更（防抖处理）。
  • 在 agents.defaults.memorySearch 下配置（不是顶层的 memorySearch）。
  • memorySearch.provider 和 memorySearch.fallback 接受由活跃记忆插件注册的适配器 ID。
  • 默认的 memory-core 插件注册了以下内置适配器 ID：local、openai、gemini、voyage、mistral、ollama。
  • 使用默认 memory-core 插件时，若未设置 memorySearch.provider，OpenClaw 按以下优先级自动选择：
    1. 若配置了 memorySearch.local.modelPath 且文件存在，使用 local。
    2. 若能解析到 OpenAI 密钥，使用 openai。
    3. 若能解析到 Gemini 密钥，使用 gemini。
    4. 若能解析到 Voyage 密钥，使用 voyage。
    5. 若能解析到 Mistral 密钥，使用 mistral。
    6. 否则记忆搜索保持禁用，直到完成配置。
  • 本地模式使用 node-llama-cpp，可能需要运行 pnpm approve-builds。
  • 有 sqlite-vec 时使用其加速 SQLite 内部的向量搜索。
  • 使用默认 memory-core 插件时，memorySearch.provider = "ollama" 同样支持本地/自托管 Ollama 嵌入（/api/embeddings），但不会自动选择。

远程嵌入必须为嵌入提供商配置 API Key。OpenClaw 从 auth profiles、models.providers.*.apiKey 或环境变量中解析密钥。Codex OAuth 仅覆盖聊天/补全，不满足记忆搜索的嵌入需求。Gemini 使用 GEMINI_API_KEY 或 models.providers.google.apiKey；Voyage 使用 VOYAGE_API_KEY 或 models.providers.voyage.apiKey；Mistral 使用 MISTRAL_API_KEY 或 models.providers.mistral.apiKey。Ollama 通常不需要真实 API Key（本地策略需要时，用占位符 OLLAMA_API_KEY=ollama-local 即可）。 使用自定义 OpenAI 兼容端点时，需设置 memorySearch.remote.apiKey（以及可选的 memorySearch.remote.headers）。

QMD 后端（实验性） ​

设置 memory.backend = "qmd" 可将内置 SQLite 索引器替换为 QMD：一个结合了 BM25 + 向量 + 重排序的本地优先搜索边车服务。Markdown 仍是事实来源；OpenClaw 调用 QMD 完成检索。关键说明：

前置条件 ​

  • 默认禁用。通过配置文件逐个开启（memory.backend = "qmd"）。
  • 单独安装 QMD CLI（bun install -g https://github.com/tobi/qmd 或下载发布版本），并确保 qmd 二进制文件在 gateway 的 PATH 中。
  • QMD 需要支持扩展的 SQLite 构建（macOS 上使用 brew install sqlite）。
  • QMD 通过 Bun + node-llama-cpp 完全本地运行，首次使用时会自动从 HuggingFace 下载 GGUF 模型（无需单独的 Ollama 守护进程）。
  • Gateway 将 QMD 运行在 ~/.openclaw/agents/<agentId>/qmd/ 下的独立 XDG home 中，通过设置 XDG_CONFIG_HOME 和 XDG_CACHE_HOME 实现隔离。
  • 操作系统支持：macOS 和 Linux 在安装 Bun + SQLite 后开箱即用。Windows 建议通过 WSL2 运行。

边车服务的运行方式 ​

  • Gateway 在 ~/.openclaw/agents/<agentId>/qmd/ 下写入独立的 QMD home（包含配置、缓存和 SQLite DB）。
  • 从 memory.qmd.paths（加上默认工作区记忆文件）通过 qmd collection add 创建集合，启动时和可配置间隔（memory.qmd.update.interval，默认 5 分钟）运行 qmd update + qmd embed。
  • Gateway 在启动时初始化 QMD manager，因此即使在第一次 memory_search 调用之前，周期性更新定时器也已经就绪。
  • 启动刷新默认在后台运行，不阻塞聊天启动；若需恢复旧的阻塞行为，设置 memory.qmd.update.waitForBootSync = true。
  • 搜索通过 memory.qmd.searchMode（默认 qmd search --json；也支持 vsearch 和 query）运行。如果所选模式不支持你的 QMD 版本的标志，OpenClaw 会自动重试 qmd query。如果 QMD 失败或二进制文件缺失，OpenClaw 会自动回退到内置 SQLite manager，记忆工具持续可用。
  • OpenClaw 目前不暴露 QMD embed 批量大小调优；批处理行为由 QMD 自身控制。
  • 首次搜索可能较慢：QMD 可能在首次 qmd query 时下载本地 GGUF 模型（重排序/查询扩展）。

    • OpenClaw 运行 QMD 时会自动设置 XDG_CONFIG_HOME/XDG_CACHE_HOME。

    • 如需手动预下载模型（并预热 OpenClaw 使用的相同索引），可使用 agent 的 XDG 目录运行一次查询：

      OpenClaw 的 QMD 状态存储在状态目录下（默认为 ~/.openclaw）。 通过导出 OpenClaw 使用的相同 XDG 变量，可将 qmd 指向完全相同的索引：

      bash
      # 使用与 OpenClaw 相同的状态目录
STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"

export XDG_CONFIG_HOME="$STATE_DIR/agents/main/qmd/xdg-config"
export XDG_CACHE_HOME="$STATE_DIR/agents/main/qmd/xdg-cache"

# （可选）强制刷新索引 + 嵌入
qmd update
qmd embed

# 预热 / 触发首次模型下载
qmd query "test" -c memory-root --json >/dev/null 2>&1

配置项（memory.qmd.*） ​

  • command（默认 qmd）：覆盖可执行文件路径。
  • searchMode（默认 search）：选择支持 memory_search 的 QMD 命令（search、vsearch、query）。
  • includeDefaultMemory（默认 true）：自动索引 MEMORY.md + memory/**/*.md。
  • paths[]：添加额外目录/文件（path、可选 pattern、可选稳定 name）。
  • sessions：启用会话 JSONL 索引（enabled、retentionDays、exportDir）。
  • update：控制刷新频率和维护执行（interval、debounceMs、onBoot、waitForBootSync、embedInterval、commandTimeoutMs、updateTimeoutMs、embedTimeoutMs）。
  • limits：限制召回载荷（maxResults、maxSnippetChars、maxInjectedChars、timeoutMs）。
  • scope：与 session.sendPolicy 相同的 schema。默认仅限私聊（deny 全部，allow 私聊）；可放宽以在群组/频道中显示 QMD 结果。
    • match.keyPrefix 匹配规范化的会话键（小写，去除开头的 agent:<id>:）。示例：discord:channel:。
    • match.rawKeyPrefix 匹配原始会话键（小写），包含 agent:<id>:。示例：agent:main:discord:。
    • 遗留：match.keyPrefix: "agent:..." 仍被视为原始键前缀，但建议使用 rawKeyPrefix 以提高清晰度。
  • 当 scope 拒绝搜索时，OpenClaw 会记录包含派生的 channel/chatType 的警告，便于排查空结果。
  • 工作区以外的代码片段在 memory_search 结果中显示为 qmd/<collection>/<relative-path>；memory_get 理解该前缀，并从配置的 QMD collection 根目录读取。
  • 当 memory.qmd.sessions.enabled = true 时，OpenClaw 将净化后的会话转录（用户/助手轮次）导出到 ~/.openclaw/agents/<id>/qmd/sessions/ 下的专属 QMD collection，使 memory_search 可以召回近期对话，而无需触及内置 SQLite 索引。
  • 当 memory.citations 为 auto/on 时，memory_search 代码片段会包含 Source: <path#line> 页脚；设置 memory.citations = "off" 可保持路径元数据内部使用（agent 仍会收到 memory_get 的路径，但代码片段文本省略页脚，系统提示会警告 agent 不要引用）。

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" } },
        // 规范化会话键前缀（去除 `agent:<id>:`）
        { action: "deny", match: { keyPrefix: "discord:channel:" } },
        // 原始会话键前缀（包含 `agent:<id>:`）
        { action: "deny", match: { rawKeyPrefix: "agent:main:discord:" } },
      ]
    },
    paths: [
      { name: "docs", path: "~/notes", pattern: "**/*.md" }
    ]
  }
}

引用与回退 ​

  • memory.citations 无论使用哪种后端都适用（auto/on/off）。
  • 当 qmd 运行时，我们在 status().backend = "qmd" 中标记，以便诊断时知道是哪个引擎提供了结果。如果 QMD 子进程退出或 JSON 输出无法解析，搜索 manager 会记录警告并返回内置提供商（现有的 Markdown 嵌入），直到 QMD 恢复。

额外记忆路径 ​

如果你想索引默认工作区布局之外的 Markdown 文件，可以添加显式路径：

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

说明：

  • 路径可以是绝对路径或工作区相对路径。
  • 目录会递归扫描 .md 文件。
  • 默认只索引 Markdown 文件。
  • 若 memorySearch.multimodal.enabled = true，OpenClaw 还会索引 extraPaths 下支持的图片/音频文件。默认记忆根目录（MEMORY.md、memory.md、memory/**/*.md）仍仅限 Markdown。
  • 忽略符号链接（文件或目录）。

多模态记忆文件（Gemini 图片 + 音频） ​

使用 Gemini embedding 2 时，OpenClaw 可以索引 memorySearch.extraPaths 中的图片和音频文件：

json5
agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-2-preview",
      extraPaths: ["assets/reference", "voice-notes"],
      multimodal: {
        enabled: true,
        modalities: ["image", "audio"], // 或 ["all"]
        maxFileBytes: 10000000
      },
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

说明：

  • 多模态记忆目前仅支持 gemini-embedding-2-preview。
  • 多模态索引仅适用于通过 memorySearch.extraPaths 发现的文件。
  • 本阶段支持的模态：图片和音频。
  • 启用多模态记忆时，memorySearch.fallback 必须保持为 "none"。
  • 索引时，匹配的图片/音频文件字节会上传到配置的 Gemini 嵌入端点。
  • 支持的图片扩展名：.jpg、.jpeg、.png、.webp、.gif、.heic、.heif。
  • 支持的音频扩展名：.mp3、.wav、.ogg、.opus、.m4a、.aac、.flac。
  • 搜索查询仍为文本形式，但 Gemini 可以将文本查询与已索引的图片/音频嵌入进行比较。
  • memory_get 仍只读取 Markdown 文件；二进制文件可被搜索但不会以原始文件内容形式返回。

Gemini 嵌入（原生） ​

将提供商设置为 gemini 以直接使用 Gemini Embeddings API：

json5
agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-001",
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

说明：

  • remote.baseUrl 为可选项（默认使用 Gemini API base URL）。
  • remote.headers 允许在需要时添加额外请求头。
  • 默认模型：gemini-embedding-001。
  • 也支持 gemini-embedding-2-preview：8192 token 限制，可配置维度（768 / 1536 / 3072，默认 3072）。

Gemini Embedding 2（预览版） ​

json5
agents: {
  defaults: {
    memorySearch: {
      provider: "gemini",
      model: "gemini-embedding-2-preview",
      outputDimensionality: 3072,  // 可选：768、1536 或 3072（默认）
      remote: {
        apiKey: "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

需要重新索引： 从 gemini-embedding-001（768 维）切换到 gemini-embedding-2-preview（3072 维）会改变向量尺寸。在 768、1536、3072 之间修改 outputDimensionality 同样如此。 OpenClaw 检测到模型或维度变更时会自动重置并重新索引整个存储。

自定义 OpenAI 兼容端点 ​

如果想使用自定义 OpenAI 兼容端点（OpenRouter、vLLM 或代理），可以配合 OpenAI 提供商使用 remote 配置：

json5
agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_OPENAI_COMPAT_API_KEY",
        headers: { "X-Custom-Header": "value" }
      }
    }
  }
}

如果不想设置 API Key，使用 memorySearch.provider = "local" 或设置 memorySearch.fallback = "none"。

回退机制 ​

  • memorySearch.fallback 可以是任意已注册的记忆嵌入适配器 ID，或 none。
  • 使用默认 memory-core 插件时，有效的内置回退 ID 为：openai、gemini、voyage、mistral、ollama、local。
  • 回退提供商仅在主嵌入提供商失败时使用。

批量索引 ​

  • 默认禁用。设置 agents.defaults.memorySearch.remote.batch.enabled = true 可为支持批量的适配器启用批量索引。
  • 默认行为等待批次完成；如有需要，可调整 remote.batch.wait、remote.batch.pollIntervalMs 和 remote.batch.timeoutMinutes。
  • 设置 remote.batch.concurrency 控制并行提交的批次作业数量（默认：2）。
  • 使用默认 memory-core 插件时，批量索引适用于 openai、gemini 和 voyage。
  • Gemini 批次作业使用异步嵌入批处理端点，需要 Gemini Batch API 可用性。

OpenAI 批量处理速度快且经济的原因：

配置示例：

json5
agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      fallback: "openai",
      remote: {
        batch: { enabled: true, concurrency: 2 }
      },
      sync: { watch: true }
    }
  }
}

记忆工具的工作原理 ​

  • memory_search 对 MEMORY.md + memory/**/*.md 中的 Markdown 块（约 400 token 为目标，80 token 重叠）进行语义搜索。返回代码片段文本（上限约 700 字符）、文件路径、行范围、评分、提供商/模型，以及是否从本地回退到远程嵌入。不返回完整文件内容。
  • memory_get 读取特定的记忆 Markdown 文件（工作区相对路径），可选从指定行开始，读取 N 行。MEMORY.md / memory/ 以外的路径会被拒绝。
  • 两个工具仅在 agent 的 memorySearch.enabled 解析为 true 时启用。

索引内容与时机 ​

  • 文件类型：仅 Markdown（MEMORY.md、memory/**/*.md）。
  • 索引存储：每个 agent 的 SQLite，路径为 ~/.openclaw/memory/<agentId>.sqlite（可通过 agents.defaults.memorySearch.store.path 配置，支持 {agentId} 占位符）。
  • 新鲜度：监听器监视 MEMORY.md + memory/，标记索引为脏（防抖 1.5s）。同步在会话启动时、搜索时或按间隔调度，异步运行。会话转录使用增量阈值触发后台同步。
  • 重新索引触发条件：索引存储嵌入提供商/模型 + 端点指纹 + 分块参数。任何变更都会导致 OpenClaw 自动重置并重新索引整个存储。

混合搜索（BM25 + 向量） ​

启用后，OpenClaw 将以下两种方式结合：

  • 向量相似度（语义匹配，措辞可以不同）
  • BM25 关键词相关性（精确 token，如 ID、环境变量、代码符号）

如果平台不支持全文搜索，OpenClaw 回退到仅向量搜索。

为什么选择混合搜索 ​

向量搜索擅长"同义表达"：

  • "Mac Studio gateway 主机" vs "运行 gateway 的机器"
  • "防抖文件更新" vs "避免每次写入都触发索引"

但对精确的高信号 token 可能较弱：

  • ID（a828e60、b3b9895a...）
  • 代码符号（memorySearch.query.hybrid）
  • 错误字符串（"sqlite-vec unavailable"）

BM25（全文）则恰好相反：擅长精确 token，对近义词较弱。 混合搜索是务实的折中方案：同时使用两种检索信号，对"自然语言"查询和"大海捞针"查询都能获得良好结果。

结果合并方式（当前设计） ​

实现思路：

  1. 从两侧各取一批候选：
  • 向量：按余弦相似度取前 maxResults * candidateMultiplier 个。
  • BM25：按 FTS5 BM25 排名取前 maxResults * candidateMultiplier 个（排名越小越好）。
  1. 将 BM25 排名转换为 0..1 分数：
  • textScore = 1 / (1 + max(0, bm25Rank))
  1. 按 chunk id 合并候选并计算加权分数：
  • finalScore = vectorWeight * vectorScore + textWeight * textScore

说明：

  • vectorWeight + textWeight 在配置解析时归一化为 1.0，因此权重表现为百分比。
  • 如果嵌入不可用（或提供商返回零向量），仍会运行 BM25 并返回关键词匹配结果。
  • 如果 FTS5 无法创建，保持仅向量搜索（不会硬性失败）。

这不是"信息检索理论上的完美方案"，但简单、快速，在实际笔记上往往能提升召回率/精确率。 后续如需进一步优化，常见的下一步是 Reciprocal Rank Fusion（RRF）或分数归一化（min/max 或 z-score）后再混合。

后处理流水线 ​

合并向量和关键词分数后，两个可选的后处理阶段会在结果到达 agent 之前对其进行精化：

向量 + 关键词 -> 加权合并 -> 时间衰减 -> 排序 -> MMR -> Top-K 结果

两个阶段默认关闭，可独立启用。

MMR 重排序（多样性） ​

混合搜索返回结果时，多个 chunk 可能包含相似或重叠的内容。 例如，搜索"家庭网络配置"可能返回来自不同日记条目的五个几乎相同的代码片段，它们都提到了同一台路由器的配置。

MMR（最大边际相关性） 重排序结果以平衡相关性与多样性，确保顶部结果涵盖查询的不同方面，而非重复相同信息。

工作原理：

  1. 按原始相关性（向量 + BM25 加权分数）对结果打分。
  2. MMR 迭代选择结果，最大化：lambda x 相关性 - (1-lambda) x 与已选结果的最大相似度。
  3. 结果之间的相似度使用分词内容的 Jaccard 文本相似度衡量。

lambda 参数控制权衡：

  • lambda = 1.0 — 纯相关性（无多样性惩罚）
  • lambda = 0.0 — 最大多样性（忽略相关性）
  • 默认：0.7（均衡，轻微偏向相关性）

示例 — 查询："家庭网络配置"

给定以下记忆文件：

memory/2026-02-10.md  -> "配置了 Omada 路由器，VLAN 10 用于 IoT 设备"
memory/2026-02-08.md  -> "配置了 Omada 路由器，IoT 迁移到 VLAN 10"
memory/2026-02-05.md  -> "在 192.168.10.2 上设置了 AdGuard DNS"
memory/network.md     -> "路由器：Omada ER605，AdGuard：192.168.10.2，VLAN 10：IoT"

不使用 MMR — 前 3 个结果：

1. memory/2026-02-10.md  (分数: 0.92)  <- 路由器 + VLAN
2. memory/2026-02-08.md  (分数: 0.89)  <- 路由器 + VLAN（近似重复！）
3. memory/network.md     (分数: 0.85)  <- 参考文档

使用 MMR（lambda=0.7）— 前 3 个结果：

1. memory/2026-02-10.md  (分数: 0.92)  <- 路由器 + VLAN
2. memory/network.md     (分数: 0.85)  <- 参考文档（多样！）
3. memory/2026-02-05.md  (分数: 0.78)  <- AdGuard DNS（多样！）

2 月 8 日的近似重复被剔除，agent 获得三条不同信息。

何时启用： 如果你注意到 memory_search 返回冗余或近似重复的代码片段，尤其是有大量每日重复相似内容的日记条目时。

时间衰减（近期加权） ​

拥有每日日记的 agent 会随时间积累数百个带日期的文件。如果没有衰减，六个月前措辞精准的笔记可能比同一主题昨天的更新排名更高。

时间衰减 根据每个结果的年龄应用指数乘数，使近期记忆自然排名更高，而旧记忆则逐渐淡出：

衰减后分数 = 分数 x e^(-lambda x 天数)

其中 lambda = ln(2) / halfLifeDays。

默认半衰期 30 天时：

  • 今天的笔记：原始分数的 100%
  • 7 天前：约 84%
  • 30 天前：50%
  • 90 天前：12.5%
  • 180 天前：约 1.6%

常绿文件永不衰减：

  • MEMORY.md（根记忆文件）
  • memory/ 中不带日期的文件（如 memory/projects.md、memory/network.md）
  • 这些文件包含应始终正常排名的持久参考信息。

带日期的每日文件（memory/YYYY-MM-DD.md）使用从文件名提取的日期。 其他来源（如会话转录）回退到文件修改时间（mtime）。

示例 — 查询："Rod 的工作安排是什么？"

给定以下记忆文件（今天是 2 月 10 日）：

memory/2025-09-15.md  -> "Rod 周一至周五工作，每天 10 点站会，14 点结对"  （148 天前）
memory/2026-02-10.md  -> "Rod 的站会在 14:15，与 Zeb 的 1:1 在 14:45"    （今天）
memory/2026-02-03.md  -> "Rod 加入了新团队，站会改到 14:15"               （7 天前）

不使用衰减：

1. memory/2025-09-15.md  (分数: 0.91)  <- 语义匹配最好，但已过时！
2. memory/2026-02-10.md  (分数: 0.82)
3. memory/2026-02-03.md  (分数: 0.80)

使用衰减（halfLife=30）：

1. memory/2026-02-10.md  (分数: 0.82 x 1.00 = 0.82)  <- 今天，无衰减
2. memory/2026-02-03.md  (分数: 0.80 x 0.85 = 0.68)  <- 7 天，轻微衰减
3. memory/2025-09-15.md  (分数: 0.91 x 0.03 = 0.03)  <- 148 天，几乎消失

尽管 9 月的旧笔记原始语义匹配最好，它仍然落到了最底部。

何时启用： 如果你的 agent 有数月的每日日记，且你发现旧的过时信息超过了近期上下文的排名。30 天的半衰期适合以每日日记为主的工作流；如果你经常引用较早的笔记，可以增大该值（如 90 天）。

混合搜索配置 ​

两个功能均在 memorySearch.query.hybrid 下配置：

json5
agents: {
  defaults: {
    memorySearch: {
      query: {
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3,
          candidateMultiplier: 4,
          // 多样性：减少冗余结果
          mmr: {
            enabled: true,    // 默认：false
            lambda: 0.7       // 0 = 最大多样性，1 = 最大相关性
          },
          // 近期：提升较新的记忆
          temporalDecay: {
            enabled: true,    // 默认：false
            halfLifeDays: 30  // 每 30 天分数减半
          }
        }
      }
    }
  }
}

两个功能可独立启用：

  • 仅 MMR — 适合有大量相似笔记但年龄不重要的场景。
  • 仅时间衰减 — 适合近期性很重要但结果已经足够多样的场景。
  • 两者同时 — 推荐给有大量长期每日日记历史的 agent。

嵌入缓存 ​

OpenClaw 可以在 SQLite 中缓存 chunk 嵌入，这样重新索引和频繁更新（尤其是会话转录）就不必重新嵌入未更改的文本。

配置：

json5
agents: {
  defaults: {
    memorySearch: {
      cache: {
        enabled: true,
        maxEntries: 50000
      }
    }
  }
}

会话记忆搜索（实验性） ​

你可以选择性地索引会话转录并通过 memory_search 检索它们。 此功能受实验性标志控制。

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

说明：

  • 会话索引是可选功能（默认关闭）。
  • 会话更新经过防抖处理，在超过增量阈值后异步索引（尽力而为）。
  • memory_search 不会阻塞等待索引；在后台同步完成之前，结果可能略有延迟。
  • 结果仍只包含代码片段；memory_get 仍限于记忆文件。
  • 会话索引按 agent 隔离（只索引该 agent 的会话日志）。
  • 会话日志存储在磁盘上（~/.openclaw/agents/<agentId>/sessions/*.jsonl）。任何有文件系统访问权限的进程/用户都可以读取，因此将磁盘访问视为信任边界。若需更严格的隔离，请在不同的操作系统用户或主机下运行 agent。

增量阈值（显示默认值）：

json5
agents: {
  defaults: {
    memorySearch: {
      sync: {
        sessions: {
          deltaBytes: 100000,   // ~100 KB
          deltaMessages: 50     // JSONL 行数
        }
      }
    }
  }
}

SQLite 向量加速（sqlite-vec） ​

当 sqlite-vec 扩展可用时，OpenClaw 将嵌入存储在 SQLite 虚拟表（vec0）中，并在数据库中执行向量距离查询。这样无需将所有嵌入加载到 JS 中，就能保持搜索速度。

配置（可选）：

json5
agents: {
  defaults: {
    memorySearch: {
      store: {
        vector: {
          enabled: true,
          extensionPath: "/path/to/sqlite-vec"
        }
      }
    }
  }
}

说明：

  • enabled 默认为 true；禁用时，搜索回退到对存储嵌入的进程内余弦相似度计算。
  • 如果 sqlite-vec 扩展缺失或加载失败，OpenClaw 会记录错误并继续使用 JS 回退（无向量表）。
  • extensionPath 覆盖内置的 sqlite-vec 路径（适用于自定义构建或非标准安装位置）。

本地嵌入自动下载 ​

  • 默认本地嵌入模型：hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf（约 0.6 GB）。
  • 当 memorySearch.provider = "local" 时，node-llama-cpp 解析 modelPath；如果 GGUF 文件缺失，会自动下载到缓存（或 local.modelCacheDir 指定的目录），然后加载。下载可续传。
  • 原生构建要求：运行 pnpm approve-builds，选择 node-llama-cpp，然后 pnpm rebuild node-llama-cpp。
  • 回退：如果本地设置失败且 memorySearch.fallback = "openai"，会自动切换到远程嵌入（openai/text-embedding-3-small，除非有覆盖配置）并记录原因。

自定义 OpenAI 兼容端点示例 ​

json5
agents: {
  defaults: {
    memorySearch: {
      provider: "openai",
      model: "text-embedding-3-small",
      remote: {
        baseUrl: "https://api.example.com/v1/",
        apiKey: "YOUR_REMOTE_API_KEY",
        headers: {
          "X-Organization": "org-id",
          "X-Project": "project-id"
        }
      }
    }
  }
}

说明：

  • remote.* 优先于 models.providers.openai.*。
  • remote.headers 与 OpenAI 请求头合并；发生键冲突时 remote 优先。省略 remote.headers 则使用 OpenAI 默认值。

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

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策