llama.cpp-provider

llama-cpp is de officiële externe providerplugin voor lokale GGUF-tekstinferentie en embeddings binnen hetzelfde proces. Deze registreert tekstprovider llama-cpp, embeddingprovider local en beheert de native runtime node-llama-cpp.

Installeer deze voordat je lokale inferentie of lokale geheugenembeddings gebruikt:

openclaw plugins install @openclaw/llama-cpp-provider

Het npm-hoofdpakket openclaw bevat node-llama-cpp niet. Door de native afhankelijkheid in deze plugin te houden, wordt voorkomen dat normale npm-updates van OpenClaw een handmatig geïnstalleerde runtime in de pakketmap van OpenClaw verwijderen.

Lokale tekstinferentie

Kies Lokaal model (llama.cpp) tijdens de interactieve onboarding. OpenClaw vraagt om bevestiging voordat het standaardmodel wordt gedownload:

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

Het bestand Qwen3 4B Instruct 2507 Q4_K_M is ongeveer 2,5 GB groot. Reken op circa 3 GB RAM voor de modelgewichten, plus de context en overhead van de OpenClaw-runtime. De standaardcontext wordt automatisch ingesteld met een limiet van 8.192 tokens, zodat deze praktisch bruikbaar blijft op machines met 8 GB. Configureer alleen een grotere context als de machine voldoende geheugen heeft.

De detectiecontrole tijdens de onboarding is alleen-lezen. llama.cpp wordt alleen automatisch aangeboden wanneer het standaard of geconfigureerde GGUF-bestand al in de modelcache staat; tijdens de detectie wordt nooit iets gedownload. Ollama en LM Studio blijven afzonderlijke opties voor lokale services en behouden hun eigen detectieflows. llama.cpp handmatig kiezen is de manier om de vraag voor het downloaden van het standaardmodel te krijgen.

De provider gebruikt de ingebouwde chatsjabloon van het GGUF-model en native functieaanroepen van node-llama-cpp. Tekst wordt token voor token gestreamd. Toolaanroepen worden voor uitvoering teruggestuurd naar OpenClaw in plaats van binnen node-llama-cpp te worden uitgevoerd.

Een ander GGUF-model gebruiken

Voeg een model toe aan models.providers.llama-cpp. Plaats een lokaal pad of een volledige hf:-bestands-URI in 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" },    },  },}

Bij inferentie wordt een ontbrekend model nooit impliciet gedownload. Download voor een aangepaste hf:-URI eerst het GGUF-bestand naar modelCacheDir. Detectie gebruikt de eigen alleen-lezen cache-resolver van node-llama-cpp, inclusief naamgeving voor repository's, branches en gesplitste bestanden.

Configuratie van geheugenembeddings

Stel memory.search.provider in op local:

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

local.modelPath gebruikt standaard de hierboven getoonde hf:-URI (embeddinggemma-300m-qat-Q8_0.gguf). Verwijs naar een andere hf:-URI of een lokaal .gguf-bestand om een ander model te gebruiken. local.modelCacheDir overschrijft waar gedownloade modellen in de cache worden opgeslagen (standaard: ~/.node-llama-cpp/models) en local.contextSize accepteert een geheel getal of "auto".

Wanneer local.contextSize numeriek is, geeft de provider die vereiste ook door aan de automatische plaatsing van GPU-lagen door node-llama-cpp. Hierdoor kan node-llama-cpp het model en de embeddingcontext samen inpassen, terwijl de controles voor geheugenveiligheid behouden blijven. Met "auto" behoudt node-llama-cpp de normale automatische plaatsing.

Native runtime

Gebruik Node 24 voor het soepelste native installatieproces. Broncodecheck-outs die pnpm gebruiken, moeten mogelijk de native afhankelijkheid goedkeuren en opnieuw bouwen:

pnpm approve-buildspnpm rebuild node-llama-cpp

Diagnostiek voor de geheugenruntime

Voer openclaw memory status --deep uit nadat de provider is geladen om de geselecteerde backend en build, apparaatnamen, naar de GPU overgehevelde lagen, aangevraagde contextgrootte en de laatst waargenomen momentopname van VRAM of gedeeld geheugen te inspecteren. De VRAM- waarden bevatten een tijdstempel van de waarneming, omdat passieve statusuitlezingen het model niet opnieuw laden en het apparaat niet pollen.

Dezelfde laatst bekende gegevens kunnen in openclaw doctor verschijnen wanneer de actieve Gateway de lokale provider al heeft gebruikt. Een normale status- of doctor-opdracht laadt geen model alleen om diagnostische gegevens te verzamelen.

Probleemoplossing

Als node-llama-cpp ontbreekt of niet kan worden geladen, meldt OpenClaw de fout met:

1. Installeer de plugin: openclaw plugins install @openclaw/llama-cpp-provider.
2. Gebruik Node 24 voor native installaties/updates.
3. Vanuit een pnpm-broncodecheck-out: pnpm approve-builds, daarna pnpm rebuild node-llama-cpp.

Gebruik voor lokale inferentie zonder een native afhankelijkheid binnen hetzelfde proces in plaats daarvan de provider Ollama of LM Studio. Voor lokale embeddings met minder configuratie stel je memory.search.provider in op een externe embeddingprovider zoals lmstudio, ollama, openai of voyage.