Hub documentation

Agentes locais com 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 locais com llama.cpp

Você pode executar um agente de codificação inteiramente no seu próprio hardware. Vários agentes de código aberto podem se conectar a um servidor local llama.cpp para oferecer uma experiência semelhante à do Claude Code ou do Codex — mas tudo roda na sua máquina.

Começando

1. Configure seu hardware local

Configure seu hardware local para que ele possa mostrar quais modelos são compatíveis com sua configuração.

Acesse huggingface.co/settings/hardware e configure o perfil de hardware local. Em seguida, selecione llama.cpp em Local Apps settings, pois este será o mecanismo que você usará.

2. Encontre um modelo compatível

Pesquise por modelos compatíveis com Llama.cpp.

3. Inicie o servidor llama.cpp

Na página do modelo, clique no botão “Use this model” e selecione llama.cpp. Ele exibirá os comandos exatos para a sua configuração. O primeiro passo é iniciar um servidor llama.cpp, por exemplo

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

Isso baixa o modelo e inicia um servidor de API compatível com a OpenAI na sua máquina. Consulte o guia do llama.cpp para as instruções de instalação.

4. Conecte seu agente

Escolha um dos agentes abaixo e siga as instruções de configuração.

Pi

Pi é o agente por trás do OpenClaw e agora está integrado diretamente ao Hugging Face, dando a você acesso a milhares de modelos compatíveis.

Instale o Pi:

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

Em seguida, adicione seu modelo local ao arquivo de configuração do Pi em ~/.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 o Pi no diretório do seu projeto:

pi

O Pi se conecta ao seu servidor local llama.cpp e oferece uma sessão interativa de agente.

Demo

Habilitando suporte a visão

Para modelos com capacidade de visão, adicione "input": ["text", "image"] à entrada do modelo em ~/.pi/agent/models.json:

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

Navegue pelos modelos de visão-linguagem compatíveis com Pi.

OpenClaw

OpenClaw funciona localmente com llama.cpp. Você pode definir seu modelo por meio do comando a bordo:

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

Você também pode executar openclaw onboard de forma interativa, selecionar custom-compatibility com openai e passar a mesma configuração.

Busca em Memória Local para OpenClaw

Você pode executar modelos de embedding locais com Llama.cpp para a busca de memória do seu agente. Para isso, certifique-se de ter o node-llama-cpp.

npm i node-llama-cpp

Aqui está um exemplo de trecho para executar o EmbeddingGemma-300M quantizado localmente para busca de memória. O OpenClaw baixa e serve o modelo automaticamente com o comando abaixo.

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 o gateway e 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 com llama.cpp. Defina uma configuração padrão 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

### Busca em memória local para o Hermes Agent

O Hermes Agent consome modelos de busca semântica por meio de endpoints. Depois de colocar seu modelo de embedding preferido em execução no endpoint 8080 com o llama.cpp ou o motor de inferência de sua escolha, adicione o seguinte 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

Verifique se isso funciona, none - built-in only indica que nenhum outro plug-in de memória é usado. A saída abaixo mostra que o serviço local está ativo.

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

OpenCode

OpenCode funciona localmente com llama.cpp. Defina um ~/.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
          }
        }
      }
    }
  }
}

Como Funciona

A configuração possui dois componentes executados localmente:

servidor llama.cpp — Serve o modelo como uma API compatível com a OpenAI em localhost.
Seu agente — O processo do agente que envia prompts para o servidor local, raciocina sobre as tarefas e executa ações.

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

Alternativa: llama-agent

llama-agent adota uma abordagem diferente — ele integra o loop do agente diretamente ao llama.cpp como um único binário, sem dependências externas. Sem Node.js, sem Python, basta compilar e executar:

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

Como as chamadas de ferramentas ocorrem no processo, em vez de via HTTP, não há sobrecarga de rede entre o modelo e o agente. Ele também suporta subagentes, servidores MCP e um modo de servidor de API HTTP.

Próximas etapas

Use modelos de IA localmente — Saiba mais sobre a execução de modelos em seu computador
Guia do llama.cpp — Instalação e uso detalhados do llama.cpp
Agentes no Hub — Conecte agentes ao ecossistema do Hugging Face

Update on GitHub

←Criando agentes com o HF SDK Bibliotecas de Agentes→