llama.cpp プロバイダー

llama-cpp は、プロセス内のローカル GGUF テキスト推論および埋め込み用の公式外部プロバイダー Plugin です。テキストプロバイダー llama-cpp と埋め込みプロバイダー local を登録し、node-llama-cpp ネイティブランタイムを所有します。

ローカル推論またはローカルメモリ埋め込みを使用する前にインストールしてください。

openclaw plugins install @openclaw/llama-cpp-provider

メインの openclaw npm パッケージには node-llama-cpp は含まれていません。ネイティブ依存関係をこの Plugin に保持することで、通常の 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 GB のマシンでも実用的に動作するよう、上限 8,192 トークンで自動的にサイズ設定されます。マシンに十分なメモリがある場合にのみ、より大きなコンテキストを設定してください。

オンボーディングの検出チェックは読み取り専用です。デフォルトまたは設定済みの GGUF ファイルがモデルキャッシュにすでに存在する場合にのみ、llama.cpp を自動的に提示します。検出中にダウンロードすることはありません。Ollama と LM Studio は引き続き個別のローカルサービスの選択肢であり、それぞれ独自の検出フローを維持します。llama.cpp を手動で選択すると、デフォルトモデルのダウンロードを確認するフローに進みます。

このプロバイダーは、GGUF モデルに埋め込まれたチャットテンプレートと、node-llama-cpp のネイティブ関数呼び出しを使用します。テキストはトークン単位でストリーミングされます。ツール呼び出しは node-llama-cpp 内で実行されるのではなく、実行のために OpenClaw に返されます。

別の GGUF モデルを使用する

models.providers.llama-cpp にモデルを追加します。ローカルパスまたは完全な hf: ファイル URI を params.modelPath に指定します。

{  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-buildspnpm rebuild node-llama-cpp

メモリランタイムの診断

プロバイダーが読み込まれた後に openclaw memory status --deep を実行すると、選択されたバックエンドとビルド、デバイス名、GPU にオフロードされたレイヤー、要求されたコンテキストサイズ、および最後に観測された VRAM またはユニファイドメモリのスナップショットを確認できます。パッシブなステータス読み取りではモデルの再読み込みやデバイスのポーリングを行わないため、VRAM の値には観測時刻のタイムスタンプが含まれます。

実行中の Gateway がローカルプロバイダーをすでに使用している場合、同じ最終確認済みの情報が openclaw doctor に表示されることがあります。通常のステータスまたは doctor コマンドでは、診断情報を収集するためだけにモデルを読み込むことはありません。

トラブルシューティング

node-llama-cpp が見つからないか読み込みに失敗した場合、OpenClaw は次の内容とともに失敗を報告します。

1. Plugin をインストールします: 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 などのリモート埋め込みプロバイダーに設定します。