Provedor llama.cpp

llama-cpp é o plugin de provedor externo oficial para embeddings GGUF locais. Ele registra o ID de provedor de embeddings local e é responsável pela dependência de runtime node-llama-cpp usada por memorySearch.provider: "local".

Instale-o antes de usar embeddings de memória locais:

openclaw plugins install @openclaw/llama-cpp-provider

O pacote npm principal openclaw não inclui node-llama-cpp. Manter a dependência nativa neste plugin evita que atualizações normais do OpenClaw via npm excluam um runtime instalado manualmente no diretório do pacote OpenClaw.

Configuração

Defina memorySearch.provider como local:

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

O padrão de local.modelPath é o URI hf: mostrado acima (embeddinggemma-300m-qat-Q8_0.gguf). Aponte-o para outro URI hf: ou para um arquivo .gguf local a fim de usar outro modelo. local.modelCacheDir substitui o local em que os modelos baixados são armazenados em cache (padrão: ~/.node-llama-cpp/models), e local.contextSize aceita um número inteiro ou "auto".

Quando local.contextSize é numérico, o provedor também fornece esse requisito ao posicionamento automático de camadas na GPU do node-llama-cpp. Isso permite que o node-llama-cpp ajuste o modelo e o contexto dos embeddings em conjunto, mantendo suas verificações de segurança de memória. Com "auto", o node-llama-cpp mantém seu posicionamento automático normal.

Runtime nativo

Use o Node 24 para obter um processo de instalação nativa mais simples. Cópias de trabalho do código-fonte que usam pnpm podem precisar aprovar e recompilar a dependência nativa:

pnpm approve-buildspnpm rebuild node-llama-cpp

Diagnóstico do runtime

Execute openclaw memory status --deep depois que o provedor for carregado para inspecionar o backend e a compilação selecionados, os nomes dos dispositivos, as camadas transferidas para a GPU, o tamanho de contexto solicitado e o último instantâneo observado da VRAM ou da memória unificada. Os valores de VRAM incluem um carimbo de data e hora da observação porque as leituras passivas de status não recarregam o modelo nem consultam o dispositivo.

Os mesmos dados conhecidos mais recentes podem aparecer em openclaw doctor quando o Gateway em execução já tiver usado o provedor local. Um comando normal de status ou de diagnóstico não carrega um modelo apenas para coletar diagnósticos.

Solução de problemas

Se node-llama-cpp estiver ausente ou não puder ser carregado, o OpenClaw relatará a falha com estas orientações:

1. Instale o plugin: openclaw plugins install @openclaw/llama-cpp-provider.
2. Use o Node 24 para instalações/atualizações nativas.
3. Em uma cópia de trabalho do código-fonte que usa pnpm: pnpm approve-builds e, em seguida, pnpm rebuild node-llama-cpp.

Para usar embeddings locais com menos atrito e sem a etapa de compilação nativa, defina memorySearch.provider como um provedor remoto de embeddings, como lmstudio, ollama, openai ou voyage.