llama-cpp 是官方的外部提供商插件，用于进程内本地 GGUF
文本推理和嵌入。它注册文本提供商 llama-cpp、
嵌入提供商 local，并负责管理 node-llama-cpp 原生运行时。
在使用本地推理或本地内存嵌入之前，请先安装它：
openclaw npm 包不包含 node-llama-cpp。将这个原生依赖保留在此插件中，可以防止正常的 OpenClaw npm 更新删除 OpenClaw 包目录中手动安装的运行时。
本地文本推理
在交互式引导过程中选择 llama.cpp。OpenClaw 会安装官方提供商插件，然后在下载默认模型前征得确认：hf:unsloth/gemma-4-E4B-it-GGUF/gemma-4-E4B-it-Q4_K_M.gguf
Gemma 4 E4B IT Q4_K_M 文件约为 5.0 GB。OpenClaw 仅会在内存至少为 16 GiB 的计算机上提供此默认模型，为模型权重、上下文和 Gateway 开销预留空间。默认上下文会自动设置，最大为 8,192 个 token。只有在计算机内存充足时，才配置更大的上下文。
引导发现检查为只读操作。仅当默认或已配置的 GGUF 文件已经位于模型缓存中时，它才会自动提供 llama.cpp；发现过程中绝不会下载模型。Ollama 和 LM Studio 仍是独立的本地服务选项，并保留各自的发现流程。手动选择 llama.cpp 会安装运行时、提示下载默认模型，并在将设置标记为完成前验证真实的模型回复。
该提供商使用 GGUF 模型内嵌的聊天模板和原生的 node-llama-cpp 函数调用功能。文本会逐个 token 流式传输。工具调用会返回给 OpenClaw 执行，而不是在 node-llama-cpp 内部运行。
使用其他 GGUF 模型
将模型添加到models.providers.llama-cpp。在 params.modelPath 中填入本地路径或完整的 hf: 文件 URI：
hf: URI，请先将 GGUF 下载到 modelCacheDir 中。发现功能使用 node-llama-cpp 自身的只读缓存解析器，包括仓库、分支和分片文件命名。
内存嵌入配置
将memory.search.provider 设置为 local：
local.modelPath 默认使用上方所示的 hf: URI（embeddinggemma-300m-qat-Q8_0.gguf）。
将其指向不同的 hf: URI 或本地 .gguf 文件，即可使用其他模型。缓存位置和嵌入上下文大小由
llama.cpp 提供程序管理；memory.search.local 仅公开 modelPath。
原生运行时
使用 Node 24 可获得最顺畅的原生安装路径。使用 pnpm 的源码检出可能需要批准并重新构建原生依赖：内存运行时诊断
在提供程序加载完成后，运行openclaw memory status --deep，以检查
所选后端和构建、设备名称、GPU 卸载层数、请求的
上下文大小，以及最近一次观察到的 VRAM 或统一内存快照。VRAM
值包含一个观测时间戳，因为被动状态读取不会
重新加载模型或轮询设备。
当运行中的 Gateway 已经使用过本地提供程序时，相同的最新已知信息也可能出现在 openclaw doctor 中。普通的 status 或 doctor 命令
不会为了收集诊断信息而加载模型。
故障排查
如果node-llama-cpp 缺失或加载失败，OpenClaw 会按如下方式报告该失败信息：
- 安装插件：
openclaw plugins install @openclaw/llama-cpp-provider。 - 在本地安装／更新时使用 Node 24。
- 如果是从 pnpm 源码检出：先运行
pnpm approve-builds，然后运行pnpm rebuild node-llama-cpp。
memory.search.provider 设置为远程嵌入提供商，例如 lmstudio、
ollama、openai 或 voyage。