> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# llama.cpp 提供者

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 的原始碼簽出可能需要核准並重新建置原生相依套件：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`。