Hub documentation

Agentes locales con llama.cpp

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Agentes locales con llama.cpp

Puedes ejecutar un agente de programación 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.

Primeros pasos

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

Busca modelos compatibles con Llama.cpp.

3. Iniciar el servidor de llama.cpp

En la página del modelo, haz clic en el botón “Usar este modelo” y selecciona llama.cpp. Te mostrará los comandos exactos para tu configuración. El primer paso es iniciar un servidor de llama.cpp, por ejemplo

llama-server -hf ggml-org/gemma-4-26b-a4b-it-GGUF:Q4_K_M

Esto descarga el modelo y inicia un servidor de API compatible con OpenAI en tu máquina. Consulta la guía de llama.cpp para obtener instrucciones de instalación.

4. 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

Luego, añade tu modelo local al archivo de configuración de Pi en ~/.pi/agent/models.json:

{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "ggml-org-gemma-4-26b-4b-gguf"
        }
      ]
    }
  }
}

Inicie Pi en el directorio de su proyecto:

pi

Pi se conecta a tu servidor local de llama.cpp y te ofrece una sesión de agente interactiva.

Demo

Habilitar el soporte de visión

Para los modelos con capacidad de visión, añade "input": ["text", "image"] a la entrada del modelo en ~/.pi/agent/models.json:

"models": [
  {
    "id": "unsloth/Qwen3.6-35B-A3B-GGUF:Q4_K_XL",
    "input": ["text", "image"]
  }
]

Explora modelos de visión-lenguaje compatibles con Pi.

OpenClaw

OpenClaw funciona localmente con llama.cpp. Puedes configurar tu modelo mediante el comando integrado:

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "http://127.0.0.1:8080/v1" \
  --custom-model-id "ggml-org-gemma-4-26b-a4b-gguf" \
  --custom-api-key "llama.cpp" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --accept-risk

También puede ejecutar openclaw onboard de forma interactiva, seleccionar custom-compatibility con openai y pasar la misma configuración.

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. Define una configuración predeterminada como:

model:
  provider: custom
  default: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M
  base_url: http://127.0.0.1:8080/v1
  api_key: llama.cpp

custom_providers:
  - name: Local (127.0.0.1:8080)
    base_url: http://127.0.0.1:8080/v1
    api_key: llama.cpp
    model: ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M

### 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
          }
        }
      }
    }
  }
}

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 — El proceso del agente que 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.

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

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

Update on GitHub

←Creación de agentes con el SDK de HF Bibliotecas de agentes→