llama.cpp 提供商

llama-cpp 是用于本地 GGUF 嵌入的官方外部提供商插件。它注册嵌入提供商 ID local，并负责管理 memorySearch.provider: "local" 使用的 node-llama-cpp 运行时依赖。

使用本地记忆嵌入前，请先安装它：

openclaw plugins install @openclaw/llama-cpp-provider

主 openclaw npm 软件包不包含 node-llama-cpp。将原生依赖保留在此插件中，可防止常规 OpenClaw npm 更新删除手动安装在 OpenClaw 软件包目录内的运行时。

配置

将 memorySearch.provider 设置为 local：

{  agents: {    defaults: {      memorySearch: {        provider: "local",        local: {          modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",        },      },    },  },}

local.modelPath 默认为上面所示的 hf: URI（embeddinggemma-300m-qat-Q8_0.gguf）。若要使用其他模型，请将其指向其他 hf: URI 或本地 .gguf 文件。local.modelCacheDir 可覆盖下载模型的缓存位置（默认值：~/.node-llama-cpp/models），而 local.contextSize 接受整数或 "auto"。

当 local.contextSize 为数值时，提供商还会将该要求传递给 node-llama-cpp 的自动 GPU 层放置功能。这样，node-llama-cpp 就能在保留内存安全检查的同时，合理容纳模型和嵌入上下文。使用 "auto" 时，node-llama-cpp 会保持常规的自动放置方式。

原生运行时

使用 Node 24 可获得最顺畅的原生安装体验。使用 pnpm 的源代码检出可能需要批准并重新构建原生依赖：

pnpm approve-buildspnpm rebuild node-llama-cpp

运行时诊断

提供商加载后，运行 openclaw memory status --deep，可检查所选后端和构建版本、设备名称、GPU 卸载层数、请求的上下文大小，以及最近观测到的 VRAM 或统一内存快照。VRAM 值包含观测时间戳，因为被动状态读取不会重新加载模型或轮询设备。

如果正在运行的 Gateway 网关已经使用过本地提供商，同样的最近已知信息也可能出现在 openclaw doctor 中。常规状态或 Doctor 命令不会仅为了收集诊断信息而加载模型。

故障排查

如果 node-llama-cpp 缺失或加载失败，OpenClaw 会报告故障，并提供以下解决步骤：

1. 安装插件：openclaw plugins install @openclaw/llama-cpp-provider。
2. 使用 Node 24 进行原生安装或更新。
3. 对于 pnpm 源代码检出：运行 pnpm approve-builds，然后运行 pnpm rebuild node-llama-cpp。

若希望以更省事的方式使用本地嵌入，而不执行原生构建步骤，请改为将 memorySearch.provider 设置为远程嵌入提供商，例如 lmstudio、ollama、openai 或 voyage。