ClawHub

node-llama-cpp 安装指南

Other

提供在美的内网环境下安装和排查 node-llama-cpp 以支持 OpenClaw memorySearch 的详细步骤和替代远程 embedding 配置。

Install

openclaw skills install node-llama-cpp-install-guide

node-llama-cpp 安装指南（Windows 内网环境）

概述

在美的集团内网环境下，为 OpenClaw memorySearch 安装 node-llama-cpp 的完整记录。包含 7 个常见问题的排查和替代方案（远程 embedding）。

环境要求

项目值
OSWindows 10+ (x64)
Node>= 22.16.0（必须，低于此版本会导致 DLL 加载失败）
npm>= 10.9.0
OpenClaw2026.3.13+
网络GitHub HTTPS 可用，SSH 可能被内网封锁

核心问题清单

问题 1：GitHub SSH 被封锁

ssh: connect to host github.com port 22: Connection timed out

修复：

git config --global url."https://".insteadOf git://
git config --global url."https://github.com/".insteadOf ssh://git@github.com/

问题 2：npm 依赖冲突

npm error ERESOLVE could not resolve
npm error peerOptional oxlint-tsgolint@">=0.22.1" from oxlint@1.68.0

修复：使用 --force 或 --legacy-peer-deps

问题 3：Node 版本不匹配

npm warn EBADENGINE Unsupported engine {
  required: { node: '>=22.16.0' },
  current: { node: 'v22.14.0' }
}

影响：Node 22.14.0 与预编译二进制 ABI 不兼容，导致 ERR_DLOPEN_FAILED。

修复：升级 Node 到 22.16+ 或更高。

问题 4：预编译二进制 DLL 加载失败

Error: A dynamic link library (DLL) initialization routine failed.
code: 'ERR_DLOPEN_FAILED'

根因：Node 版本不匹配。

问题 5：postinstall 下载失败

request to https://github.com/xpack-dev-tools/cmake-xpack/releases/... failed
reason: connect ETIMEDOUT

根因：内网封锁 GitHub Releases 下载。

问题 6：源码编译失败

SpawnError: Command npm exec --yes -- xpm@^0.16.3 install @xpack-dev-tools/cmake@latest exited with code 3

根因：cmake 无法下载。

问题 7：预编译二进制本地缺失

workspace 中 node-llama-cpp 的 bins 目录只有 .moved.txt 占位符，真实二进制被清理。

安装步骤（如果网络畅通）

cd "C:\Program Files\mx\resources\openclaw"
npm install node-llama-cpp --ignore-scripts --force
cd node_modules/node-llama-cpp
node ./dist/cli/cli.js postinstall

关键参数：

  • --ignore-scripts：绕过 git 依赖问题
  • --force：绕过 peer 依赖冲突

替代方案：远程 embedding（推荐用于内网环境）

在 openclaw.json 中配置：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "sources": ["memory"],
        "provider": "openai",
        "remote": {
          "baseUrl": "https://apiprod.midea.com/llm/f-devops-python-litellm/v1",
          "apiKey": ""
        },
        "fallback": "none"
      }
    }
  }
}

验证：

openclaw.cmd memory status

预期输出：

Provider: openai (requested: openai)
Model: text-embedding-3-small
Vector: ready
FTS: ready

三层防护配置（防止配置丢失）

第 1 层：PRD preset

C:\Program Files\mx\resources\openclaw\config\prd-openclaw.json

加入 memorySearch 和 plugins 配置。

第 2 层：openclaw.cmd 环境变量

D:\Users\yindb2\AppData\Local\openclaw\mx\current\openclaw.cmd

添加：

set "OPENCLAW_CONFIG_MODE=local"
set "OPENCLAW_CONFIG_SERVER_TOKEN="

第 3 层：dist JS 白名单

C:\Program Files\mx\resources\openclaw\dist\reply-*.js

移除 agents.defaults 白名单。

教训

  1. 内网环境不要选本地嵌入方案：GitHub 封锁 + 网络限制导致安装不可行
  2. Node 版本必须匹配：22.14 vs 22.16 的差异足以导致 native addon 加载失败
  3. 远程 embedding 是最佳选择：配置即生效，不需要额外依赖
  4. PRD preset 必须同步更新：否则 gateway 重启后配置被覆盖

参考