Fournisseur llama.cpp

llama-cpp est le plugin de fournisseur externe officiel pour les embeddings GGUF locaux. Il enregistre l’identifiant de fournisseur d’embeddings local et gère la dépendance d’exécution node-llama-cpp utilisée par memorySearch.provider: "local".

Installez-le avant d’utiliser les embeddings de mémoire locaux :

openclaw plugins install @openclaw/llama-cpp-provider

Le paquet npm principal openclaw n’inclut pas node-llama-cpp. Le maintien de la dépendance native dans ce plugin empêche les mises à jour npm ordinaires d’OpenClaw de supprimer un environnement d’exécution installé manuellement dans le répertoire du paquet OpenClaw.

Configuration

Définissez memorySearch.provider sur local :

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

La valeur par défaut de local.modelPath est l’URI hf: indiquée ci-dessus (embeddinggemma-300m-qat-Q8_0.gguf). Faites-la pointer vers une autre URI hf: ou vers un fichier .gguf local pour utiliser un autre modèle. local.modelCacheDir remplace l’emplacement de mise en cache des modèles téléchargés (valeur par défaut : ~/.node-llama-cpp/models), et local.contextSize accepte un entier ou "auto".

Lorsque local.contextSize est numérique, le fournisseur transmet également cette exigence au placement automatique des couches sur le GPU de node-llama-cpp. Cela permet à node-llama-cpp d’adapter simultanément le modèle et le contexte d’embedding tout en conservant ses contrôles de sécurité de la mémoire. Avec "auto", node-llama-cpp conserve son placement automatique habituel.

Environnement d’exécution natif

Utilisez Node 24 pour bénéficier du processus d’installation native le plus fluide. Les copies de travail des sources utilisant pnpm peuvent nécessiter l’approbation et la recompilation de la dépendance native :

pnpm approve-buildspnpm rebuild node-llama-cpp

Diagnostics d’exécution

Exécutez openclaw memory status --deep après le chargement du fournisseur pour examiner le moteur et la version sélectionnés, les noms des appareils, les couches déchargées sur le GPU, la taille de contexte demandée ainsi que le dernier instantané observé de la VRAM ou de la mémoire unifiée. Les valeurs de VRAM comprennent un horodatage d’observation, car les lectures d’état passives ne rechargent pas le modèle et n’interrogent pas l’appareil.

Les mêmes informations connues les plus récentes peuvent apparaître dans openclaw doctor lorsque le Gateway en cours d’exécution a déjà utilisé le fournisseur local. Une commande d’état ou de diagnostic ordinaire ne charge pas de modèle uniquement pour recueillir des diagnostics.

Résolution des problèmes

Si node-llama-cpp est absent ou ne parvient pas à se charger, OpenClaw signale l’échec avec les instructions suivantes :

1. Installez le plugin : openclaw plugins install @openclaw/llama-cpp-provider.
2. Utilisez Node 24 pour les installations et mises à jour natives.
3. Depuis une copie de travail des sources utilisant pnpm : pnpm approve-builds, puis pnpm rebuild node-llama-cpp.

Pour utiliser plus facilement des embeddings locaux sans l’étape de compilation native, définissez plutôt memorySearch.provider sur un fournisseur d’embeddings distant tel que lmstudio, ollama, openai ou voyage.