OpenClaw 本地 Memory 配置：Ubuntu、CUDA、llama.cpp

背景：先把 Memory 跑起来

执行 openclaw doctor 时，如果看到下面这类提示，说明长期记忆检索还没配好：

◇ Memory search Memory search is enabled but no embedding provider is configured. Semantic recall will not work without an embedding provider. Fix (pick one): - Set OPENAI_API_KEY or GEMINI_API_KEY in your environment - Add credentials: openclaw auth add --provider openai - For local embeddings: configure agents.defaults.memorySearch.provider and local model path - To disable: openclaw config set agents.defaults.memorySearch.enabled false Verify: openclaw memory status --deep 

这里的关键点很简单：memory_search 只认 openai | gemini | local。前两种都要额外的 API Key；如果不想依赖外部服务，用 local 最省事，也最适合自己机器上折腾。

配置 OpenClaw 的 Memory

按官方文档改 ~/.openclaw/openclaw.json，我这里直接放一份可用配置。核心是把 memorySearch.provider 切到 local，并补上本地模型路径和 sqlite-vec 扩展路径。

"agents": {
  "defaults": {
    "model": { "primary": "zai/glm-5" },
    "models": { "zai/glm-5": { "alias": "GLM" } },
    "workspace": "~/.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"
        }
      }
    }
  }
}

这里有两处我建议别省：

1. modelPath 用官方给的模型名，不要写成本地目录。这样后面换机器、换环境时少很多麻烦。
2. extensionPath 要按实际安装位置改。这个路径不是写死就能通的，装法不同，.so 的位置也会变。

Ubuntu 24.04 安装 CUDA 和 cuDNN

CUDA 我是按 NVIDIA 官网的 Ubuntu 24.04 教程装的，过程比较直，但版本号要盯紧，不然很容易装到别的仓库包。

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，确认工具链真的在。

接着装 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

我通常会再装一下 Anaconda 和 PyTorch，跑个最小测试脚本，确认 CUDA 真能用。别等到编译完别的项目才发现驱动链路有问题，那时回头找更费时间。

编译 llama.cpp

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

验证时可以直接拉 HuggingFace 模型，或者用 CLI 跑一下：

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

如果这里报 OpenSSL 相关错误，基本就是前面的编译参数没带对，-DLLAMA_OPENSSL=ON 不能省。

安装 node-llama-cpp

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

验证 Memory

openclaw gateway restart
openclaw memory status --deep

这时正常的话，会开始把模型下载到 ~/.node-llama-cpp/models。第一次跑会慢一点，但这是正常现象。

遇到 sqlite-vec unavailable 怎么办

如果报 sqlite-vec unavailable，说明缺少 SQLite 的向量扩展。这个问题不算少见，尤其是系统包和 npm 包混着装的时候。

先走系统依赖这条路：

sudo apt-get update
sudo apt-get install unzip
sudo apt install -y libsqlite3-dev
git clone https://github.com/asg017/sqlite-vec
cd sqlite-vec
./scripts/vendor.sh
make loadable

如果想省事，也可以直接用 npm 装：

npm install -g sqlite-vec

装完以后找到生成的 .so 文件，把 openclaw.json 里的 extensionPath 改成实际路径，再重启 gateway。这个配置没对上，Memory 检索还是起不来。

常见问题

关于 node-llama-cpp 的安装提示

当 memorySearch.provider = "local" 时，node-llama-cpp 会按 modelPath 去解析模型。GGUF 文件不存在的话，它会自动下载。

如果你走的是原生构建，记得先执行 pnpm approve-builds，把 node-llama-cpp 放行，再跑 pnpm rebuild node-llama-cpp。这个步骤不做，后面容易卡在构建权限上。

安装顺序别乱

比较稳的顺序是：先装 CUDA，再装 cuDNN，然后编译 llama.cpp，最后再装原生编译的 node-llama-cpp。

sudo apt-get update
sudo apt-get install build-essential cmake git libstdc++6 libgomp1
npx node-llama-cpp source download
npx node-llama-cpp source build

如果执行 inspect gpu 时冒出 Vulkan 相关报错，但 CUDA 本身正常，通常不用太紧张。它不一定影响 GPU 加速，先看你实际跑推理时是不是走了 CUDA 路径。