OpenClaw 本地 Memory 配置指南：Ubuntu 下 CUDA 与 llama.cpp 集成实践

注意：

• modelPath 应使用 HuggingFace 模型名称而非本地路径，这是容易踩坑的地方。
• extensionPath 需指向 sqlite-vec 的动态库实际位置，后文会详述如何获取。

2. Ubuntu 24.04 环境搭建

安装 CUDA 和 cuDNN

按照 NVIDIA 官方教程操作。首先添加仓库密钥并安装工具包：

mkdir -p /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，若显示版本号则成功。

接着安装 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 查看安装目录。建议安装 Anaconda 和 PyTorch 后运行测试脚本确认 CUDA 可用性。

3. 编译 llama.cpp

node-llama-cpp 默认可能回退到 CPU 版本，因此我们需要手动编译支持 CUDA 的版本。

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build -DGGML_CUDA=ON -DLLAMA_OPENSSL=ON
cmake --build build --config Release

提示： -DLLAMA_OPENSSL=ON 是关键参数，否则后续推理时可能会报错。编译成功后，可尝试运行 CLI 验证：

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

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

4. 安装 node-llama-cpp

全局安装 Node.js 封装库：

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

前置条件： 确保已按顺序完成 CUDA、cuDNN 安装及 llama.cpp 编译。如果直接安装失败，可能需要先执行原生构建命令：

npx node-llama-cpp source download
npx node-llama-cpp source build

5. 解决 sqlite-vec 问题

运行 openclaw doctor 时，常会遇到 sqlite-vec unavailable 错误。这是因为系统找不到动态链接库。

解决方案：

1. 通过 npm 安装 sqlite-vec，它会自动下载预编译的二进制文件。

   npm install -g sqlite-vec
   

2. 找到生成的 .so 文件路径，通常位于 ~/.npm-global/lib/node_modules/sqlite-vec/node_modules/sqlite-vec-linux-x64/vec0.so。
3. 将上述路径填入 openclaw.json 中的 extensionPath 字段。

6. 验证与调试

重启网关并检查状态：

openclaw gateway restart
openclaw memory status --deep

此时应能看到模型自动下载到 ~/.node-llama-cpp/models 目录，且不再报 sqlite-vec 错误。

常见问题排查

• Vulkan 报错： 如果看到 Vulkan 检测失败但 CUDA 正常，通常不影响使用，可忽略。
• 模型加载慢： 首次运行会下载 embedding 模型，请耐心等待。
• 权限问题： 确保 ~/.openclaw 目录有正确的读写权限。

通过以上步骤，即可在 Ubuntu 环境下成功启用 OpenClaw 的本地 Memory 功能，无需依赖外部 API。