Proveedor de llama.cpp

llama-cpp es el Plugin de proveedor externo oficial para la inferencia de texto y las incrustaciones GGUF locales en proceso. Registra el proveedor de texto llama-cpp, el proveedor de incrustaciones local y es responsable del entorno de ejecución nativo node-llama-cpp.

Instálelo antes de usar la inferencia local o las incrustaciones 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 npm de OpenClaw eliminen un entorno de ejecución instalado manualmente dentro del directorio del paquete OpenClaw.

Inferencia de texto local

Elija Modelo local (llama.cpp) durante la incorporación interactiva. OpenClaw solicita confirmación antes de descargar el modelo predeterminado:

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

El archivo Qwen3 4B Instruct 2507 Q4_K_M ocupa aproximadamente 2.5 GB. Reserve unos 3 GB de RAM para los pesos del modelo, además del contexto y la sobrecarga del entorno de ejecución de OpenClaw. El contexto predeterminado se dimensiona automáticamente con un límite de 8,192 tokens para que siga siendo práctico en equipos con 8 GB. Configure un contexto mayor solo cuando el equipo disponga de suficiente memoria.

La comprobación de detección de la incorporación es de solo lectura. Ofrece llama.cpp automáticamente solo cuando el archivo GGUF predeterminado o configurado ya se encuentra en la caché de modelos; nunca realiza descargas durante la detección. Ollama y LM Studio siguen siendo opciones independientes de servicios locales y conservan sus propios flujos de detección. Elegir llama.cpp manualmente es la vía que solicita descargar el modelo predeterminado.

El proveedor utiliza la plantilla de chat integrada del modelo GGUF y la invocación de funciones nativa de node-llama-cpp. El texto se transmite token por token. Las llamadas a herramientas regresan a OpenClaw para su ejecución, en lugar de ejecutarse dentro de node-llama-cpp.

Usar otro modelo GGUF

Añada un modelo a models.providers.llama-cpp. Introduzca una ruta local o un URI de archivo hf: completo en 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" },    },  },}

La inferencia nunca descarga implícitamente un modelo que falte. Para un URI hf: personalizado, descargue primero el GGUF en modelCacheDir. La detección utiliza el resolutor de caché de solo lectura propio de node-llama-cpp, incluidos el repositorio, la rama y la nomenclatura de archivos divididos.

Configuración de incrustaciones de memoria

Establezca memory.search.provider en local:

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

local.modelPath usa de forma predeterminada el URI hf: mostrado anteriormente (embeddinggemma-300m-qat-Q8_0.gguf). Asígnelo a un URI hf: diferente o a un archivo .gguf local para usar otro modelo. local.modelCacheDir reemplaza 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 comunica ese requisito a la asignación automática de capas de GPU de node-llama-cpp. Esto permite que node-llama-cpp ajuste conjuntamente el modelo y el contexto de incrustación mientras conserva sus comprobaciones de seguridad de memoria. Con "auto", node-llama-cpp mantiene su asignación automática normal.

Entorno de ejecución nativo

Use Node 24 para que la instalación nativa sea lo más sencilla posible. Los repositorios de código fuente que utilizan pnpm pueden requerir aprobar y recompilar la dependencia nativa:

pnpm approve-buildspnpm rebuild node-llama-cpp

Diagnóstico del entorno de ejecución de memoria

Ejecute openclaw memory status --deep después de que se haya cargado el proveedor para inspeccionar 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 lecturas pasivas de estado no vuelven a cargar el modelo ni consultan 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 datos de diagnóstico.

Solución de problemas

Si node-llama-cpp no está presente o no se puede cargar, OpenClaw informa del fallo con:

1. Instale el Plugin: openclaw plugins install @openclaw/llama-cpp-provider.
2. Use Node 24 para las instalaciones y actualizaciones nativas.
3. Desde un repositorio de código fuente de pnpm: pnpm approve-builds y, a continuación, pnpm rebuild node-llama-cpp.

Para realizar inferencia local sin una dependencia nativa en proceso, use en su lugar el proveedor Ollama o LM Studio. Para obtener incrustaciones locales con menos complicaciones, establezca memory.search.provider en un proveedor remoto de incrustaciones, como lmstudio, ollama, openai o voyage.