企业官网建设流程全解析

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

openclaw memory是 OpenClaw 中负责语义记忆索引与检索的管理命令，包含status、index、search三个子命令，用于查看记忆搜索索引状态、探测嵌入模型可用性、触发重新索引以及执行语义检索。本文以该命令为核心，结合 memory-core 插件的源码实现，完整讲解每个子命令的选项、输出字段、底层执行流程与典型排障场景，帮助你快速诊断和调优 OpenClaw 的记忆系统。

背景：OpenClaw 记忆系统的核心设计

在深入命令之前，先理解它管理的对象。OpenClaw 的记忆是智能体工作空间中的纯 Markdown 文件，文件本身就是唯一的事实来源——模型只"记住"写入磁盘的内容，这一设计详见 docs/zh-CN/concepts/memory.md。

默认工作空间（agents.defaults.workspace，默认~/.openclaw/workspace）使用两个记忆层：

• memory/YYYY-MM-DD.md：每日日志（仅追加），会话开始时读取今天和昨天的内容；
• MEMORY.md：精心整理的长期记忆，仅在主要的私人会话中加载，绝不在群组上下文中加载。

围绕这些 Markdown 文件，OpenClaw 暴露两个面向智能体的工具：memory_search（对已索引片段做语义召回）和memory_get（按路径/行范围定向读取记忆文件）。而记忆搜索工具及本命令本身，都由活跃的记忆插件提供。默认插件是memory-core（见 extensions/memory-core/index.ts 中的definePluginEntry({ id: "memory-core", kind: "memory" })）；若想禁用，可将配置设为plugins.slots.memory = "none"。

命令总览与示例

openclaw memory的命令级描述是"Search, inspect, and reindex memory files"（搜索、检查并重建记忆索引），在 extensions/memory-core/src/cli.ts 中注册。以下示例覆盖了三个子命令的典型用法：

openclaw memory status openclaw memory status --deep openclaw memory status --deep --index openclaw memory status --deep --index --verbose openclaw memory index openclaw memory index --verbose openclaw memory search "release checklist" openclaw memory status --agent main openclaw memory index --agent main --verbose

此外，cli.ts的帮助文本中还展示了更多实用形态（如脚本化输出与限制结果数量）：

openclaw memory status --json openclaw memory index --force openclaw memory search "meeting notes" openclaw memory search --query "deployment" --max-results 20

子命令一：memory status—— 查看记忆索引状态

memory status是诊断记忆系统健康度的第一入口，功能是"Show memory search index status"。

支持的选项

输出的核心字段

结合 extensions/memory-core/src/cli.runtime.ts 的实现，非 JSON 模式会按智能体分组打印：

• Provider：当前实际使用的嵌入提供方（如local、openai、gemini、voyage、mistral、ollama、qmd），并标注(requested: ...)请求值；
• Model：使用的嵌入模型名；
• Sources：索引来源（memory、sessions，取决于配置）；
• Extra paths：通过memorySearch.extraPaths配置的所有额外路径（源码formatExtraPaths会展开并做~缩写）；
• 索引进度：<已索引文件数>/<磁盘文件总数> files · <chunks 数> chunks；
• 数据库路径与工作空间路径；
• 若发生从本地到远程嵌入的回退，会以Fallback字段给出警示。

--deep模式下，源码会依次执行两步探测（进度条显示为 "Probing vector…" 与 "Probing embeddings…"）：

1. probeVectorAvailability()：探测向量存储（sqlite-vec 扩展是否可用）是否就绪；
2. probeEmbeddingAvailability()：探测嵌入提供方及其密钥能否解析成功。

--deep --index组合则在探测之后调用manager.sync({ reason: "cli", force })执行增量同步：仅在索引存在脏标记（有未同步变更）时重建，若后端不支持手动重建会明确提示 "Memory backend does not support manual reindex."。

--json模式下，结果通过defaultRuntime.writeJson(allResults)输出为结构化数组（每个智能体一条，含status、embeddingProbe、indexError、scan），方便 CI 脚本或监控工具消费。

子命令二：memory index—— 手动触发重新索引

memory index的功能是 "Reindex memory files"，当文件被修改、但 watcher 尚未触发同步，或你想强制重建全部索引时使用。

支持的选项

--verbose下，源码会输出每个阶段的详细诊断：Provider/Model/Sources/Extra paths/Fallback 来源，并在索引期间以每秒刷新显示elapsed（已耗时）与eta（预计剩余时间）；索引完成后还会给出 QMD 后端下的索引文件摘要（QMD index: <路径> (<size> bytes)），并打印 "Memory index updated ( )." 作为成功标志。

需要说明的是，日常使用中重新索引多数是自动完成的：OpenClaw 会在会话启动、搜索时或按固定间隔异步同步；当索引存储的"嵌入 Provider/Model + 端点指纹 + 分块参数"任一发生变化时（例如换了一个嵌入模型），系统会自动重置并全量重建整个索引库。memory index --force是当自动机制异常或你想立即落盘时的主动手段。

子命令三：memory search—— 语义检索记忆

memory search的功能是 "Search memory files"，用自然语言对已索引的 Markdown 片段做语义查询，即使措辞与原文不同也能命中相关笔记。

支持的选项

注意：若同时未提供位置参数和--query，命令会报错 "Missing search query. Provide a positional query or use --query." 并以退出码 1 结束（见 cli.runtime.ts）。

默认情况下，maxResults为 6、minScore为 0.35（这两个默认值定义在 src/agents/memory-search.ts）。非 JSON 模式下每条结果按以下格式输出：

<score> <path>:<startLine>-<endLine> <snippet>

即相似度分数（保留三位小数）、命中的文件路径与行号范围、以及片段文本，直接可读可溯源。--json模式则返回结构化结果，便于二次加工。

通用选项与多智能体行为

两个通用选项作用于所有子命令：

• --agent <id>：限定到单个智能体。若不传，status/index会遍历agents.list中所有已配置的智能体并逐个输出；search则默认解析到默认智能体（resolveDefaultAgentId）。
• --verbose：输出详细日志。在status/index的探测与索引阶段打印 Provider、Model、Sources、批处理活动等中间信息。

实现上，每个智能体对应一个独立的内存搜索管理器（per-agent SQLite 索引，默认位于~/.openclaw/memory/<agentId>.sqlite，可通过agents.defaults.memorySearch.store.path配置并支持{agentId}令牌），因此多智能体场景下索引互不干扰。

从源码看命令执行流程

以memory status为例，完整调用链为（cli.runtime.ts）：

1. 密钥解析：loadMemoryCommandConfig通过resolveCommandSecretRefsViaGateway解析命令相关的秘密引用，目标项为agents.defaults.memorySearch.remote.apiKey与agents.list[].memorySearch.remote.apiKey，任何解析告警会以[secrets]前缀输出；
2. 智能体解析：resolveAgentIds决定遍历范围；
3. 管理器获取：withMemoryManagerForAgent获取该智能体的内存搜索管理器（后端可能是内置 SQLite 索引器或 QMD 边车）；
4. 探测与同步：probeVectorAvailability→probeEmbeddingAvailability→ （若--index）sync；
5. 结果输出：按智能体聚合状态，JSON 或人类可读文本。

memory search与memory index复用同一套管理器管线，区别仅在同步/搜索阶段。这套实现同时支撑了doctor中的记忆健康检查（见 src/commands/doctor-memory-search.ts，纯配置检查、无网络调用），因此openclaw doctor的 Memory search 检查项与openclaw memory status --deep结论应当一致。

配置联动：memory status背后到底探测了什么

memory status --deep的"嵌入可用性"探测结果直接取决于agents.defaults.memorySearch.*配置。理解自动选择与回退规则，才能准确解读 status 输出：

• Provider 自动选择：当memorySearch.provider未设置时，OpenClaw 按序自动选择：①local（配置了local.modelPath且文件存在）→ ②openai（可解析 OpenAI 密钥）→ ③gemini（可解析 Gemini 密钥）→ ④voyage→ ⑤mistral→ ⑥ 否则记忆搜索保持禁用，直到配置完成。memorySearch.provider = "ollama"也支持本地/自托管 Ollama 嵌入（/api/embeddings），但不会被自动选中。
• 密钥来源：远程嵌入需要 API 密钥，可从 auth 配置文件、models.providers.*.apiKey或环境变量解析。注意Codex OAuth 只覆盖聊天/补全，不满足记忆搜索的嵌入需求。Gemini 用GEMINI_API_KEY或models.providers.google.apiKey，Voyage 用VOYAGE_API_KEY，Mistral 用MISTRAL_API_KEY；自定义 OpenAI 兼容端点时设置memorySearch.remote.apiKey（及可选的remote.headers）。
• 回退：memorySearch.fallback可设为openai、gemini、voyage、mistral、ollama、local或none，仅当主 Provider 失败时启用。
• 额外路径：memorySearch.extraPaths允许索引默认布局之外的 Markdown 文件（绝对或工作空间相对路径，目录递归扫描.md，符号链接被忽略）。这正是memory status中Extra paths字段的内容来源。
• 混合检索与重排：memorySearch.query.hybrid默认开启（向量权重 0.7 + BM25 文本权重 0.3），可独立启用 MMR 多样性重排（lambda默认 0.7）与时间衰减（默认半衰期 30 天，MEMORY.md与无日期文件名永不过期），详情参见 docs/zh-CN/concepts/memory.md。
• 向量加速与缓存：sqlite-vec 可用时在 SQLite 虚拟表vec0中执行向量距离查询；嵌入缓存默认开启（maxEntries默认 50000），避免重复文本反复嵌入。
• 会话记忆（实验性）：experimental.sessionMemory: true配合sources: ["memory", "sessions"]可索引会话转写，阈值默认deltaBytes: 100000、deltaMessages: 50。
• QMD 后端：设memory.backend = "qmd"可切换到 QMD 本地搜索边车（BM25 + 向量 + 重排），此时status().backend = "qmd"，诊断输出会标记实际服务引擎；QMD 失败时会自动回退到内置 SQLite 管理器。

上述默认值（分块 400 token / 80 重叠、watcher 去抖 1500ms、批处理并发 2、轮询间隔 2000ms、超时 60 分钟等）均可从 src/agents/memory-search.ts 的常量定义逐一核实。

典型排查场景

结合 docs/zh-CN/cli/memory.md 的定位（"调试记忆可用性或索引问题"），几个高频场景与对应命令：

1. 记忆搜索完全不可用：先openclaw memory status --deep，确认Provider是否为空或提示未配置密钥；若为本地模式，检查local.modelPath的 GGUF 是否已下载（node-llama-cpp会自动下载，可能需要先pnpm approve-builds完成原生构建）。
2. 索引滞后、搜不到刚写入的笔记：openclaw memory status --deep --index触发未同步变更的重新索引，再openclaw memory search "<关键词>"验证。
3. 结果冗余或陈旧：在memorySearch.query.hybrid中开启mmr减少近重复片段、开启temporalDecay让新笔记排名更高；调整后openclaw memory index --force --verbose重建并观察各阶段输出。
4. 脚本化监控：openclaw memory status --json输出结构化状态，可接入 CI 或告警；openclaw memory search --query "..." --max-results 20 --json适合批量校验检索质量。

总结

openclaw memory以三个子命令覆盖了语义记忆的完整生命周期：status负责健康诊断（探测向量存储与嵌入提供方、显示 extraPaths 与索引进度）、index负责主动重建（--force全量、--verbose全阶段可见）、search负责语义召回（支持分数阈值与结果数控制、JSON 输出）。其能力边界完全由agents.defaults.memorySearch.*配置与 memory-core 插件决定——理解 Provider 自动选择顺序、密钥解析规则和回退机制，是读懂status输出并快速定位"记忆不可用/索引不新鲜/结果不理想"这三类问题的关键。

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯