Proveedor de llama.cpp

llama-cpp es el plugin de proveedor externo oficial para embeddings GGUF locales. Registra el identificador de proveedor de embeddings local y es responsable de la dependencia de entorno de ejecución node-llama-cpp que utiliza memorySearch.provider: "local".

Instálelo antes de usar embeddings de memoria locales:

openclaw plugins install @openclaw/llama-cpp-provider

El paquete npm principal openclaw no incluye node-llama-cpp. Mantener la dependencia nativa en este plugin evita que las actualizaciones normales de OpenClaw mediante npm eliminen un entorno de ejecución instalado manualmente dentro del directorio del paquete de OpenClaw.

Configuración

Establezca memorySearch.provider en local:

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

El valor predeterminado de local.modelPath es el URI hf: mostrado anteriormente (embeddinggemma-300m-qat-Q8_0.gguf). Asígnelo a otro URI hf: o a un archivo .gguf local para usar otro modelo. local.modelCacheDir sustituye la ubicación donde se almacenan en caché los modelos descargados (valor predeterminado: ~/.node-llama-cpp/models), y local.contextSize acepta un entero o "auto".

Cuando local.contextSize es numérico, el proveedor también proporciona ese requisito a la asignación automática de capas de GPU de node-llama-cpp. Esto permite que node-llama-cpp aloje conjuntamente el modelo y el contexto de embeddings mientras conserva sus comprobaciones de seguridad de memoria. Con "auto", node-llama-cpp mantiene su asignación automática habitual.

Entorno de ejecución nativo

Use Node 24 para que la instalación nativa sea lo más fluida posible. Las copias del código fuente que usan pnpm podrían necesitar aprobar y recompilar la dependencia nativa:

pnpm approve-buildspnpm rebuild node-llama-cpp

Diagnósticos del entorno de ejecución

Ejecute openclaw memory status --deep después de que se haya cargado el proveedor para consultar el backend y la compilación seleccionados, los nombres de los dispositivos, las capas transferidas a la GPU, el tamaño de contexto solicitado y la última instantánea observada de la VRAM o la memoria unificada. Los valores de VRAM incluyen una marca de tiempo de observación porque las consultas pasivas de estado no vuelven a cargar el modelo ni sondean el dispositivo.

Los mismos datos conocidos más recientes pueden aparecer en openclaw doctor cuando el Gateway en ejecución ya ha utilizado el proveedor local. Un comando normal de estado o de diagnóstico no carga un modelo únicamente para recopilar diagnósticos.

Solución de problemas

Si falta node-llama-cpp o no se puede cargar, OpenClaw informa del error junto con estas instrucciones:

1. Instale el plugin: openclaw plugins install @openclaw/llama-cpp-provider.
2. Use Node 24 para las instalaciones y actualizaciones nativas.
3. Desde una copia del código fuente basada en pnpm: pnpm approve-builds y, a continuación, pnpm rebuild node-llama-cpp.

Para usar embeddings locales con menos complicaciones y sin el paso de compilación nativa, establezca memorySearch.provider en un proveedor de embeddings remoto como lmstudio, ollama, openai o voyage.