古法编程

Appearance

配置 OpenClaw 的 memory-lancedb 插件后，即可在本地 LanceDB 中存储长期记忆，利用向量嵌入进行语义召回。关键步骤：安装 @openclaw/memory-lancedb，设置 plugins.slots.memory，在 plugins.entries 中指定嵌入提供方及模型。用 openclaw plugins list 确认加载，用 openclaw ltm 命令管理记忆。若自动捕获未生效，检查 autoCapture 与 customTriggers。对于 Ollama 嵌入需设置 dimensions，遇到输入超长错误时降低 recallMaxChars（默认 1000）并重启 Gateway。

OpenClaw LanceDB 记忆插件配置与故障排除 ​

memory-lancedb 是 OpenClaw 官方外部记忆插件，将长期记忆存储在 LanceDB 中，并使用嵌入向量进行语义召回。它能在模型响应前自动召回相关记忆，也可在响应后捕获重要信息。

当你需要本地向量数据库管理记忆、使用 OpenAI 兼容的嵌入端点，或希望将记忆数据库独立于内置存储时，使用此插件。

安装 ​

在设置 plugins.slots.memory = "memory-lancedb" 之前，先安装插件：

bash
openclaw plugins install @openclaw/memory-lancedb

此插件发布在 npm 上，不随 OpenClaw 运行时镜像打包。安装器会写入插件入口，并在无其他插件占用记忆槽时切换记忆槽。

INFO

memory-lancedb 是活跃记忆插件。需通过 plugins.slots.memory = "memory-lancedb" 显式激活记忆槽。辅助插件如 memory-wiki 可与其共存，但只有一个插件拥有活跃记忆槽。

快速入门 ​

json5
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

修改插件配置后重启 Gateway：

bash
openclaw gateway restart

然后验证插件已加载：

bash
openclaw plugins list

Provider 支持的嵌入 ​

memory-lancedb 可使用与 memory-core 相同的记忆嵌入提供适配器。设置 embedding.provider 并省略 embedding.apiKey，即可使用该提供方已配置的认证配置、环境变量或 models.providers.<provider>.apiKey。

json5
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
        },
      },
    },
  },
}

这种方式适用于已暴露嵌入凭证的 Provider 认证配置。例如，当 Copilot 配置/计划支持嵌入时，可使用 GitHub Copilot：

json5
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "github-copilot",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

OpenAI Codex / ChatGPT OAuth（openai-codex）并非 OpenAI Platform 嵌入凭证。如需使用 OpenAI 嵌入，请使用 OpenAI API Key 认证配置、OPENAI_API_KEY 环境变量或 models.providers.openai.apiKey。仅使用 OAuth 的用户可选用其他支持嵌入的 Provider，如 GitHub Copilot 或 Ollama。

Ollama 嵌入 ​

对于 Ollama 嵌入，优先使用捆绑的 Ollama 嵌入提供适配器。它使用原生 Ollama /api/embed 端点，并遵循与 Ollama 相同的认证/基础 URL 规则。

json5
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "ollama",
            baseUrl: "http://127.0.0.1:11434",
            model: "mxbai-embed-large",
            dimensions: 1024,
          },
          recallMaxChars: 400,
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}

为非标准嵌入模型设置 dimensions。OpenClaw 已知 text-embedding-3-small 和 text-embedding-3-large 的维度；自定义模型需要在配置中指定维度值，以便 LanceDB 创建向量列。

对于小型本地嵌入模型，如果遇到本地服务器返回的上下文长度错误，可降低 recallMaxChars。

OpenAI 兼容提供方 ​

部分 OpenAI 兼容的嵌入提供方会拒绝 encoding_format 参数，另一些则忽略该参数并始终返回 number[] 向量。memory-lancedb 因此在嵌入请求中省略 encoding_format，并接受浮点数组或 base64 编码的 float32 响应。

如果你有原始的 OpenAI 兼容嵌入端点，但没有捆绑的提供适配器，可省略 embedding.provider（或保留为 openai），并设置 embedding.apiKey 和 embedding.baseUrl。这将保留直接的 OpenAI 兼容客户端路径。

对于模型维度未内置的提供方，设置 embedding.dimensions。例如，智谱 embedding-3 使用 2048 维度：

json5
{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            apiKey: "${ZHIPU_API_KEY}",
            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
            model: "embedding-3",
            dimensions: 2048,
          },
        },
      },
    },
  },
}

召回与捕获限制 ​

memory-lancedb 有两个独立的文本限制：

设置默认值范围适用场景
recallMaxChars1000100-10000发送给嵌入 API 用于召回的文本
captureMaxChars500100-10000符合自动捕获条件的消息长度
customTriggers[]0-50使自动捕获考虑该消息的字面短语

recallMaxChars 控制自动召回、memory_recall 工具、memory_forget 查询路径以及 openclaw ltm search。自动召回优先使用当前轮次的最新用户消息，仅在无用户消息时回退到完整提示。这样可避免通道元数据和大型提示块进入嵌入请求。

captureMaxChars 控制响应是否足够短，从而被自动捕获考虑。它不限制召回查询的嵌入。

customTriggers 允许添加字面自动捕获短语，无需编写正则表达式。内置触发器包括常见的英语、捷克语、中文、日语和韩语记忆短语。

命令 ​

当 memory-lancedb 是活跃记忆插件时，它会注册 ltm CLI 命名空间：

bash
openclaw ltm list
openclaw ltm search "project preferences"
openclaw ltm stats

query 子命令直接对 LanceDB 表运行非向量查询：

bash
openclaw ltm query --cols id,text,createdAt --limit 20
openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc
  • --cols <columns>：逗号分隔的列允许列表（默认：id, text, importance, category, createdAt）。
  • --filter <condition>：SQL 风格的 WHERE 子句；上限 200 字符，仅限字母数字、比较运算符、引号、括号及少量安全标点。
  • --limit <n>：正整数；默认 10。
  • --order-by &lt;column&gt;:<asc|desc>：过滤后应用的内存排序；排序列自动包含在投影中。

智能体还会从活跃记忆插件获得 LanceDB 记忆工具：

  • memory_recall：基于 LanceDB 的召回
  • memory_store：保存重要事实、偏好、决策、实体
  • memory_forget：删除匹配的记忆

存储位置 ​

默认情况下，LanceDB 数据存储在 ~/.openclaw/memory/lancedb。可通过 dbPath 覆盖：

json5
{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "~/.openclaw/memory/lancedb",
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

storageOptions 接受字符串键/值对用于 LanceDB 存储后端，并支持 ${ENV_VAR} 展开：

json5
{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "s3://memory-bucket/openclaw",
          storageOptions: {
            access_key: "${AWS_ACCESS_KEY_ID}",
            secret_key: "${AWS_SECRET_ACCESS_KEY}",
            endpoint: "${AWS_ENDPOINT_URL}",
          },
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

运行时依赖 ​

memory-lancedb 依赖原生 @lancedb/lancedb 包。打包后的 OpenClaw 将该包视为插件包的一部分。Gateway 启动时不会修复插件依赖；如果依赖缺失，请重新安装或更新插件包，并重启 Gateway。

如果旧安装在插件加载时记录丢失的 dist/package.json 或丢失的 @lancedb/lancedb 错误，请升级 OpenClaw 并重启 Gateway。

如果插件记录 LanceDB 在 darwin-x64 上不可用，请在该机器上使用默认记忆后端，或将 Gateway 迁移到支持的平台，或禁用 memory-lancedb。

故障排除 ​

输入长度超过上下文长度 ​

这通常意味着嵌入模型拒绝了召回查询：

text
memory-lancedb: recall failed: Error: 400 the input length exceeds the context length

设置更低的 recallMaxChars，然后重启 Gateway：

json5
{
  plugins: {
    entries: {
      "memory-lancedb": {
        config: {
          recallMaxChars: 400,
        },
      },
    },
  },
}

对于 Ollama，还需要验证嵌入服务器是否可从 Gateway 主机访问：

bash
curl http://127.0.0.1:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"mxbai-embed-large","input":"hello"}'

不支持的嵌入模型 ​

如果没有 dimensions，只有内置的 OpenAI 嵌入维度已知。对于本地或自定义嵌入模型，请在配置中设置 embedding.dimensions 为该模型报告的向量大小。

插件已加载但没有记忆 ​

检查 plugins.slots.memory 是否指向 memory-lancedb，然后运行：

bash
openclaw ltm stats
openclaw ltm search "recent preference"

如果 autoCapture 已禁用，插件可以召回现有记忆，但不会自动存储新记忆。如需自动捕获，可使用 memory_store 工具或启用 autoCapture。

相关文档 ​

常见问题 ​

为什么我用 Ollama 配置了嵌入但 openclaw ltm search 返回空结果？ ​

先确认 Ollama 嵌入模型已正确拉取并运行：curl http://127.0.0.1:11434/api/embeddings -d '{"model":"mxbai-embed-large","prompt":"test"}'。其次检查 embedding.dimensions 是否设置正确（例如 mxbai-embed-large 为 1024）。最后用 openclaw ltm stats 查看表状态，如果表为空，可能是 autoCapture 未开启且未调用 memory_store 工具。

如何将 LanceDB 数据存储到 S3？ ​

在 plugins.entries["memory-lancedb"].config 中设置 dbPath 为 S3 URI（如 s3://memory-bucket/openclaw），并通过 storageOptions 传递 AWS 访问密钥、密钥和端点。支持 ${ENV_VAR} 环境变量展开。

自动捕获 autoCapture 不生效怎么办？ ​

检查 autoCapture 是否设置为 true（默认 false）。确认响应文本长度不超过 captureMaxChars（默认 500）。如果使用了 customTriggers，确保触发的消息包含其中字面短语。另外，只有 plugins.slots.memory 指向 memory-lancedb 时自动捕获才会工作。

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

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