Hub documentation

Agentes locales con llama.cpp

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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:

  1. servidor de llama.cpp — Sirve el modelo como una API compatible con OpenAI en localhost.
  2. 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. llama app
  • 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-autoload y luego usa /llama para 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 all descarga todas las capas a la GPU. Omítelo para usar la descarga automática a la GPU.
  • -c 32768 establece el tamaño del contexto en tokens. Use -c 0 para 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 ~/models detecta 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:

FlagQué hace
-ngl alldescarga todas las capas a la GPU
-c 32768establece el tamaño del contexto en tokens
--models-dir ~/modelsdescubre 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.gguf

Hermes 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/v1

Bú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: 1

Comprueba 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_M

Dado 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

Update on GitHub