OpenClaw 本地 Memory 配置指南
在之前的实践中，我遇到了 OpenClaw 的 Memory（长期记忆检索）功能无法生效的问题。默认情况下，memory_search 仅支持 openai、gemini 或 local 模式，前两者需要 API Key。为了节省 Token 并实现完全本地化，我决定配置 local 模式。
核心思路是修改配置文件，安装 CUDA/cuDNN 环境，编译支持 GPU 加速的 llama.cpp，并正确部署 node-llama-cpp。
1. 配置 OpenClaw Memory
参考官方文档，我们需要修改 ~/.openclaw/openclaw.json 文件。关键是在 agents.defaults.memorySearch 部分启用 local 模式。
"agents": {
"defaults": {
"model": { "primary": "zai/glm-5" },
"models": { "zai/glm-5": { "alias": "GLM" } },
"workspace": "/home/band/.openclaw/workspace",
"compaction": {
"mode": "safeguard",
"reserveTokensFloor": 20000,
"memoryFlush": {
"enabled": true,
"softThresholdTokens": 4000,
"systemPrompt": "Session nearing compaction. Store durable memories now.",
"prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
}
},
"maxConcurrent": 4,
"subagents": { "maxConcurrent": 8 },
"memorySearch": {
"provider": "local",
"local": {
"modelPath": "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf"
},
"fallback": "none",
"sources": [ "memory", "sessions" ],
"experimental": { "sessionMemory": true },
"store": {
"vector": {
"enabled": true,
"extensionPath": "~/.npm-global/lib/node_modules/sqlite-vec/node_modules/sqlite-vec-linux-x64/vec0.so"
}
}
}
}
}
注意：
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 错误。这是因为系统找不到动态链接库。
解决方案：
- 通过 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字段。
6. 验证与调试
重启网关并检查状态：
openclaw gateway restart
openclaw memory status --deep
此时应能看到模型自动下载到 ~/.node-llama-cpp/models 目录，且不再报 sqlite-vec 错误。
常见问题排查
- Vulkan 报错： 如果看到 Vulkan 检测失败但 CUDA 正常，通常不影响使用，可忽略。
- 模型加载慢： 首次运行会下载 embedding 模型，请耐心等待。
- 权限问题： 确保
~/.openclaw目录有正确的读写权限。
通过以上步骤，即可在 Ubuntu 环境下成功启用 OpenClaw 的本地 Memory 功能，无需依赖外部 API。
