llama.cpp 提供者

llama-cpp 是官方的外部供應商外掛，用於程序內本機 GGUF 文字推論與嵌入。它會註冊文字供應商 llama-cpp、 嵌入供應商 local，並擁有 node-llama-cpp 原生執行階段。

使用本機推論或本機記憶嵌入前，請先安裝此外掛：

openclaw plugins install @openclaw/llama-cpp-provider

主要的 openclaw npm 套件不包含 node-llama-cpp。將 原生相依套件保留在此外掛中，可避免一般 OpenClaw npm 更新 刪除手動安裝於 OpenClaw 套件目錄中的執行階段。

​

本機文字推論

在互動式初始設定期間選擇 本機模型 (llama.cpp)。OpenClaw 會在 下載預設模型前詢問：

hf:bartowski/Qwen_Qwen3-4B-Instruct-2507-GGUF/Qwen_Qwen3-4B-Instruct-2507-Q4_K_M.gguf

Qwen3 4B Instruct 2507 Q4_K_M 檔案約為 2.5 GB。請為 模型權重大致預留 3 GB RAM，另加上下文與 OpenClaw 執行階段的額外用量。預設 上下文會自動調整大小，上限為 8,192 個權杖，因此在 8 GB 的機器上仍可實際使用。 僅在機器有足夠記憶體時設定更大的上下文。

初始設定的探索檢查為唯讀。只有當預設或已設定的 GGUF 檔案已存在於模型快取時， 它才會自動提供 llama.cpp 選項；探索期間絕不會下載。Ollama 與 LM Studio 仍是獨立的本機服務選項，並各自保有探索流程。手動選擇 llama.cpp 才會提示下載預設模型。

供應商會使用 GGUF 模型內嵌的聊天範本與原生 node-llama-cpp 函式呼叫。文字會逐權杖串流。工具呼叫會回傳至 OpenClaw 執行，而非在 node-llama-cpp 內執行。

​

使用其他 GGUF 模型

將模型新增至 models.providers.llama-cpp。在 params.modelPath 中填入本機路徑或完整的 hf: 檔案 URI：

{
  models: {
    mode: "merge",
    providers: {
      "llama-cpp": {
        baseUrl: "local://llama-cpp",
        api: "openai-completions",
        params: {
          modelCacheDir: "~/.node-llama-cpp/models",
        },
        models: [
          {
            id: "my-local-model",
            name: "My local GGUF",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 8192,
            maxTokens: 2048,
            params: {
              modelPath: "~/Models/my-model.Q4_K_M.gguf",
              contextSize: 8192,
            },
            compat: { supportsTools: true },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "llama-cpp/my-local-model" },
    },
  },
}

推論絕不會隱式下載缺少的模型。若使用自訂 hf: URI， 請先將 GGUF 下載至 modelCacheDir。探索會使用 node-llama-cpp 本身的唯讀快取解析器，包括儲存庫、分支及分割檔案命名。

​

記憶嵌入設定

將 memory.search.provider 設為 local：

{
  memory: {
    search: {
      provider: "local",
      local: {
        modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",
      },
    },
  },
}

local.modelPath 的預設值為上方顯示的 hf: URI（embeddinggemma-300m-qat-Q8_0.gguf）。 若要使用其他模型，請將其指向不同的 hf: URI 或本機 .gguf 檔案。 local.modelCacheDir 會覆寫已下載模型的快取位置 （預設值：~/.node-llama-cpp/models），而 local.contextSize 接受 整數或 "auto"。

當 local.contextSize 為數值時，供應商也會將該需求 提供給 node-llama-cpp 的自動 GPU 層配置。這可讓 node-llama-cpp 同時容納 模型與嵌入上下文，並保留其記憶體安全檢查。 使用 "auto" 時，node-llama-cpp 會維持其一般自動配置。

​

原生執行階段

使用 Node 24 可獲得最順暢的原生安裝流程。使用 pnpm 的原始碼簽出可能需要核准並重新建置原生相依套件：

pnpm approve-builds
pnpm rebuild node-llama-cpp

​

記憶執行階段診斷

供應商載入後執行 openclaw memory status --deep，即可檢查 所選後端與建置版本、裝置名稱、GPU 卸載層數、要求的 上下文大小，以及最近觀察到的 VRAM 或統一記憶體快照。VRAM 值包含觀察時間戳記，因為被動狀態讀取不會 重新載入模型或輪詢裝置。

若執行中的閘道已使用本機供應商，相同的最新已知資訊 也可能出現在 openclaw doctor 中。一般的狀態或診斷命令 不會僅為收集診斷資訊而載入模型。

​

疑難排解

如果 node-llama-cpp 遺失或載入失敗，OpenClaw 會回報失敗， 並顯示：

1. 安裝外掛：openclaw plugins install @openclaw/llama-cpp-provider。
2. 使用 Node 24 進行原生安裝／更新。
3. 若使用 pnpm 原始碼簽出：先執行 pnpm approve-builds，再執行 pnpm rebuild node-llama-cpp。

若要進行不依賴程序內原生相依套件的本機推論，請改用 Ollama 或 LM Studio 供應商。若要更輕鬆地使用本機嵌入，請改將 memory.search.provider 設為遠端嵌入供應商，例如 lmstudio、 ollama、openai 或 voyage。