Hub documentation
Agentes locales con llama.cpp
Agentes locales con llama.cpp
Puedes ejecutar un agente de codificación de forma local, por completo en tu propio hardware. Varios agentes de código abierto pueden conectarse a un servidor local de llama.cpp para ofrecerte una experiencia similar a la de Claude Code o Codex, pero todo se ejecuta en tu máquina.
Cómo funciona
La configuración tiene dos componentes que se ejecutan localmente:
- servidor de llama.cpp — Sirve el modelo como una API compatible con OpenAI en
localhost. - Su agente — Envía indicaciones al servidor local, razona sobre las tareas y ejecuta acciones.
┌─────────┐ API calls ┌───────────────────┐
│ Agent │ ───────────────▶ │ llama.cpp server │
│ │ ◀─────────────── │ (local model) │
└─────────┘ responses └───────────────────┘
│
▼
Your files,
terminal, etc.Configurar el servidor de llama.cpp
1. Configura tu hardware local
Configura tu hardware local para que te muestre qué modelos son compatibles con tu configuración.
Ve a huggingface.co/settings/hardware y configura tu perfil de hardware local. Luego, selecciona llama.cpp en tus Local Apps settings, ya que este será el motor que utilizarás.
2. Buscar un modelo compatible
Busque modelos GGUF compatibles con Llama. Una vez seleccionado, descargue el modelo en su hardware.
Si necesitas inspiración, la aplicación Llama sugerirá algunos modelos adaptados a tu dispositivo de hardware (ver Paso 3).
3. Instale la aplicación Llama
Puedes instalar fácilmente llama.cpp en tu máquina:
- Mac y Windows: instala la app de Llama, una aplicación de escritorio minimalista que se ubica en la bandeja del sistema
Una vez que la aplicación esté instalada, sigue los pasos para empezar a usar tu modelo favorito, recomendado para tu sistema.

- Linux (or if you only want the command line): comando de instalación en una línea:
curl -LsSf https://llama.app/install.sh | sh
Verifique la instalación:
llama --version
4. Inicie el router
Si instalaste la aplicación de escritorio, llama serve ya está en ejecución. Puedes verificarlo consultando la lista de modelos en localhost:9931.
En caso contrario, inicia llama serve. Al pasar un modelo, se inicia el modo de un solo modelo en lugar del modo de router. Consulta la guía del servidor de llama.cpp para la configuración del router.
Tienes dos opciones:
- Carga automática: por defecto, los modelos se cargan bajo demanda.
- Carga manual: añade
--no-models-autoloady luego usa/llamapara cargar los modelos antes de seleccionarlos.
Para la carga automática, simplemente inicie:
llama serve
En la mayoría de los casos no necesitas banderas adicionales, ya que los valores predeterminados deberían ser razonables. Para un uso avanzado, aquí tienes una muestra de posibles banderas que podrían interesarte:
-ngl alldescarga todas las capas a la GPU. Omítelo para usar la descarga automática a la GPU.-c 32768establece el tamaño del contexto en tokens. Use-c 0para la ventana de contexto completa del modelo, lo cual puede requerir considerablemente más memoria. El contexto se comparte entre los slots de servidor en paralelo.--models-dir ~/modelsdetecta archivos GGUF locales desde un directorio local personalizado.
Aunque el comando anterior debería ser todo lo que necesitas, aquí tienes algunas banderas comunes para usar con llama serve:
| Flag | Qué hace |
|---|---|
-ngl all | descarga todas las capas a la GPU |
-c 32768 | establece el tamaño del contexto en tokens |
--models-dir ~/models | descubre archivos GGUF locales desde un directorio local personalizado |
5. Conecta tu agente
Elija uno de los agentes de la lista siguiente y siga las instrucciones de configuración.
Pi
Pi es el agente detrás de OpenClaw y ahora está integrado directamente en Hugging Face, lo que te da acceso a miles de modelos compatibles.
Instalar Pi:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Inicie Pi en el directorio de su proyecto:
pi
Configura llama.cpp:
/login llama.cpp
Ejecuta /llama para cargar un modelo y luego /model para seleccionar el modelo cargado para la sesión actual.
OpenClaw
OpenClaw funciona localmente con llama.cpp. Puedes configurar tu modelo mediante el comando integrado:
openclaw plugins install @openclaw/llama-cpp-provider openclaw onboard
Búsqueda de memoria local para OpenClaw
Puedes ejecutar modelos de embedding locales con Llama.cpp para la búsqueda de memoria de tu agente. Para ello, asegúrate de tener node-llama-cpp.
npm i node-llama-cpp
A continuación se muestra un ejemplo de código para ejecutar EmbeddingGemma-300M cuantizado localmente para la búsqueda de memoria. OpenClaw descarga y sirve el modelo automáticamente con el comando siguiente.
openclaw config set agents.defaults.memorySearch.provider local
openclaw config set agents.defaults.memorySearch.local.modelPath "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf"Reinicie la puerta de enlace y valide.
openclaw gateway restart
openclaw memory status
# Memory Search (main)
# Provider: local (requested: local)
# Model: hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.ggufHermes Agent
Hermes Agent funciona localmente con llama.cpp. En ~/.hermes/config.yaml añade lo siguiente.
custom_providers:
- name: llama cpp (127.0.0.1:8080)
base_url: http://127.0.0.1:8080/v1Búsqueda en memoria local para Hermes Agent
Hermes Agent consume modelos de búsqueda semántica a través de puntos finales. Una vez que tengas tu modelo de incrustación preferido en ejecución en el punto final 8080 con llama.cpp o el motor de inferencia de tu elección, añade lo siguiente a ~/.hermes/config.yaml.
auxiliary:
session_search:
base_url: "http://127.0.0.1:8080/v1"
api_key: "no-key-required"
model: "local-llama" # your model alias
timeout: 90
max_concurrency: 1Comprueba si esto funciona, none - built-in only indica que no se utilizan otros complementos de memoria. La siguiente salida muestra que la ejecución local está activa.
$ hermes memory status
# Memory status
#────────────────────────────────────────
# Built-in: always active
# Provider: (none — built-in only)OpenCode
OpenCode funciona localmente con llama.cpp. Define un ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"llama.cpp": {
"npm": "@ai-sdk/openai-compatible",
"name": "llama-server (local)",
"options": {
"baseURL": "http://127.0.0.1:8080/v1"
},
"models": {
"gemma-4-26b-4b-it": {
"name": "Gemma 4 (local)",
"limit": {
"context": 128000,
"output": 8192
}
}
}
}
}
}Alternativa: llama-agent
llama-agent adopta un enfoque diferente: integra el bucle del agente directamente en llama.cpp como un único binario sin dependencias externas. Sin Node.js, sin Python, solo compilar y ejecutar:
git clone https://github.com/gary149/llama-agent.git
cd llama-agent
# Build
cmake -B build
cmake --build build --target llama-agent
# Run (downloads the model automatically)
./build/bin/llama-agent -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_MDado que las llamadas a herramientas se producen en el proceso y no a través de HTTP, no hay sobrecarga de red entre el modelo y el agente. También admite subagentes, servidores MCP y un modo de servidor de API HTTP.
Próximos pasos
- Usar modelos de IA localmente — Obtén más información sobre la ejecución de modelos en tu equipo
- Guía de llama.cpp — Instalación y uso detallados de llama.cpp
- Agentes en el Hub — Conecta agentes al ecosistema de Hugging Face