Hub documentation

Agents locaux avec 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

Agents locaux avec llama.cpp

Vous pouvez exécuter un agent de codage entièrement sur votre propre matériel. Plusieurs agents open source peuvent se connecter à un serveur local llama.cpp pour vous offrir une expérience similaire à celle de Claude Code ou de Codex — mais tout s’exécute sur votre machine.

Premiers pas

1. Configurer votre matériel local

Définissez votre matériel local afin qu’il vous indique quels modèles sont compatibles avec votre configuration.

Accédez à huggingface.co/settings/hardware et configurez votre profil de matériel local. Sélectionnez ensuite llama.cpp dans vos Paramètres des applications locales, car ce sera le moteur que vous utiliserez.

2. Trouver un modèle compatible

Parcourez les modèles compatibles Llama.cpp.

3. Lancer le serveur llama.cpp

Sur la page du modèle, cliquez sur le bouton « Utiliser ce modèle » et sélectionnez llama.cpp. Les commandes exactes pour votre configuration s’afficheront. La première étape consiste à démarrer un serveur llama.cpp, par exemple

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

Cela télécharge le modèle et démarre un serveur d’API compatible OpenAI sur votre machine. Consultez le guide llama.cpp pour les instructions d’installation.

4. Connectez votre agent

Choisissez l’un des agents ci-dessous et suivez les instructions d’installation.

Pi

Pi est l’agent derrière OpenClaw et est désormais intégré directement dans Hugging Face, vous donnant accès à des milliers de modèles compatibles.

Installer Pi :

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Ajoutez ensuite votre modèle local au fichier de configuration de Pi situé dans ~/.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"
        }
      ]
    }
  }
}

Démarrer Pi dans votre répertoire de projet :

pi

Pi se connecte à votre serveur local llama.cpp et vous offre une session d'agent interactive.

Demo

Activation de la prise en charge de la vision

Pour les modèles capables de traiter des images, ajoutez "input": ["text", "image"] à l’entrée du modèle dans ~/.pi/agent/models.json :

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

Parcourez les modèles vision-langage compatibles avec Pi.

OpenClaw

OpenClaw fonctionne localement avec llama.cpp. Vous pouvez définir votre modèle via la commande intégrée :

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

Vous pouvez également exécuter openclaw onboard de manière interactive, sélectionner custom-compatibility avec openai et passer la même configuration.

Recherche en mémoire locale pour OpenClaw

Vous pouvez exécuter des modèles d’embedding locaux avec Llama.cpp pour la recherche mémoire de votre agent. Pour ce faire, assurez-vous d’avoir installé node-llama-cpp.

npm i node-llama-cpp

Voici un extrait de code pour exécuter localement EmbeddingGemma-300M quantifié pour la recherche en mémoire. OpenClaw télécharge et sert automatiquement le modèle avec la commande ci-dessous.

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"

Redémarrez la passerelle et validez.

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 fonctionne localement avec llama.cpp. Définissez une configuration par défaut comme suit :

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

### Recherche en mémoire locale pour l’agent Hermes

Hermes Agent consomme des modèles de recherche sémantique via des points de terminaison. Une fois votre modèle d’embedding préféré déployé sur le point de terminaison 8080 avec llama.cpp ou le moteur d’inférence de votre choix, ajoutez ce qui suit à ~/.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

Vérifiez que cela fonctionne, none - built-in only indique qu’aucun autre module mémoire n’est utilisé. La sortie ci-dessous montre que le service local est actif.

$ hermes memory status
# Memory status
#────────────────────────────────────────
#  Built-in:  always active
#  Provider:  (none — built-in only)

OpenCode

OpenCode fonctionne localement avec llama.cpp. Définissez 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
          }
        }
      }
    }
  }
}

Fonctionnement

La configuration comporte deux composants exécutés localement :

serveur llama.cpp — Sert le modèle sous forme d'une API compatible OpenAI sur localhost.
Votre agent — Le processus agent qui envoie des invites au serveur local, raisonne sur les tâches et exécute des actions.

┌─────────┐     API calls     ┌──────────────────┐
│  Agent  │ ───────────────▶  │  llama.cpp server │
│         │ ◀───────────────  │  (local model)    │
└─────────┘    responses      └──────────────────┘
     │
     ▼
  Your files,
  terminal, etc.

Alternative : llama-agent

llama-agent adopte une approche différente : il intègre la boucle d’agent directement dans llama.cpp sous forme d’un binaire unique, sans aucune dépendance externe. Pas de Node.js, pas de Python, il suffit de compiler et d’exécuter :

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

Les appels d’outils s’effectuent dans le processus plutôt que via HTTP, ce qui élimine toute surcharge réseau entre le modèle et l’agent. Il prend également en charge les sous-agents, les serveurs MCP et un mode serveur d’API HTTP.

Étapes suivantes

Utiliser des modèles d'IA en local — En savoir plus sur l'exécution de modèles sur votre machine
Guide llama.cpp — Installation et utilisation détaillées de llama.cpp
Agents sur le Hub — Connecter les agents à l'écosystème Hugging Face

Update on GitHub

←Créer des agents avec le SDK HF Bibliothèques d'agents→