OpenClaw Memory 本地模式配置：Ubuntu+CUDA+llama.cpp 实战

注意：

1. modelPath 必须使用官方推荐的模型名称，而非本地绝对路径，否则无法自动下载。
2. extensionPath 需要指向实际编译好的 sqlite-vec 动态库位置，后续会详细说明。

Ubuntu 24.04 安装 CUDA 和 cuDNN

Node-llama-cpp 默认可能回退到 CPU 版本，为了发挥 GPU 性能，我们需要先搭建好 CUDA 环境。按照 NVIDIA 官网教程操作，这里直接给出关键步骤。

1. 安装 CUDA Toolkit

mkdir /opt/nvidia
cd /opt/nvidia
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-ubuntu2404.pin
sudo mv cuda-ubuntu2404.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/13.1.1/local_installers/cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2404-13-1-local_13.1.1-590.48.01-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2404-13-1-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-1

安装完成后，记得设置环境变量：

echo 'export PATH=/usr/local/cuda-13.1/bin${PATH:+:${PATH}}' | sudo tee -a /etc/profile.d/cuda.sh
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-13.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' | sudo tee -a /etc/profile.d/cuda.sh
source /etc/profile.d/cuda.sh

验证安装是否成功：

nvcc --version

![nvcc --version 验证截图]

2. 安装 cuDNN

wget https://developer.download.nvidia.com/compute/cudnn/9.19.0/local_installers/cudnn-local-repo-ubuntu2404-9.19.0_1.0-1_amd64.deb
sudo dpkg -i cudnn-local-repo-ubuntu2404-9.19.0_1.0-1_amd64.deb
sudo cp /var/cudnn-local-repo-ubuntu2404-9.19.0/cudnn-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get -y install cudnn

查看安装目录以确认文件存在：

dpkg -L libcudnn9-cuda-13
dpkg -l | grep cudnn

最后，建议安装 Anaconda 和 PyTorch，编写一个简单的 test_cuda.py 脚本进行最终验证。

编译 llama.cpp

这一步至关重要。node-llama-cpp 虽然会自动尝试构建，但如果底层 C++ 库没配好，它很容易 fallback 到 CPU。为了避免这种情况，我们手动编译一个支持 CUDA 的版本。

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
# 前提：确保环境变量已设置，DLLAMA_OPENSSL 是必要的，后面会有提示
cmake -B build -DGGML_CUDA=ON -DLLAMA_OPENSSL=ON
cmake --build build --config Release

验证方案 1：CLI 推理测试

访问 HuggingFace 模型页，选择 CLI 方案进行测试：

./build/bin/llama-cli -hf Qwen/Qwen3-0.6B-GGUF:Q8_0

如果遇到 OpenSSL 相关错误，请重新编译并加上 -DLLAMA_OPENSSL=ON 参数。

![llama-cli 运行截图]

验证方案 2：下载并运行 Llama-2 7B 模型

如果上述小模型测试通过，可以尝试更大模型。需先安装 Git LFS：

sudo apt install git-lfs
git lfs install

安装 node-llama-cpp

配置好底层环境后，再安装 Node.js 封装库。注意，这里不要盲目跟随某些过时的文档，正确的顺序应该是先有 CUDA 环境，再装 Node 库。

npm install -g node-llama-cpp
node-llama-cpp --version # 3.16.1

验证 Memory

重启网关并检查状态：

openclaw gateway restart
openclaw memory status --deep

此时应该能看到正在下载模型到 ~/.node-llama-cpp/models，说明本地模式已激活。

![Memory 状态验证截图]

sqlite-vec unavailable 问题处理

在执行 openclaw memory status --deep 时，可能会遇到 sqlite-vec unavailable 错误，提示找不到 .so 文件。这是路径配置问题。

虽然官网提供了编译教程，但我发现了一个更直接的取巧办法：直接通过 npm 安装依赖，然后手动指定路径。

# 安装 sqlite-vec
npm install -g sqlite-vec

安装完成后，找到生成的 .so 文件路径（通常在 ~/.npm-global/lib/node_modules/sqlite-vec/node_modules/sqlite-vec-linux-x64/vec0.so）。回到 openclaw.json，更新 extensionPath 配置：

"extensionPath": "~/.npm-global/lib/node_modules/sqlite-vec/node_modules/sqlite-vec-linux-x64/vec0.so"

重启 gateway 后，该错误即可消失。

踩过的坑

安装 node-llama-cpp 的一些提示

OpenClaw 文档提到，当 memorySearch.provider = "local" 时，node-llama-cpp 会解析 modelPath。如果 GGUF 缺失，它会尝试自动下载。但前提是原生构建要求必须满足。

如果你运行 openclaw doctor 提示 no local model file was found，通常是因为没有正确安装 node-llama-cpp 或其依赖项。

安装 node-llama-cpp 的前置条件

正确的依赖链条是：

1. 安装 CUDA
2. 安装 cuDNN
3. 编译 llama.cpp
4. 原生编译安装 node-llama-cpp

有些用户尝试直接在 ~/.openclaw/extensions 下安装，结果不起作用。建议在全局环境下安装，并确保 pnpm approve-builds 已通过。

Using node-llama-cpp With Vulkan

如果在验证 GPU 时发现 Vulkan 报错，目前看对主要功能影响不大，可以暂时忽略，专注于 CUDA 路径的配置。

通过以上步骤，你应该能顺利在 Ubuntu 上跑通 OpenClaw 的本地 Memory 功能。整个过程最耗时的部分是编译 llama.cpp 和排查依赖路径，一旦搞定，后续的 Token 节省效果立竿见影。