# 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](https://github.com/ggerganov/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](https://huggingface.co/settings/hardware) e configure o perfil de hardware local. Em seguida, selecione `llama.cpp` em [Local Apps settings](https://huggingface.co/settings/local-apps), pois este será o mecanismo que você usará.

### 2. Encontre um modelo compatível

Pesquise por [modelos compatíveis com Llama.cpp](https://huggingface.co/models?apps=llama.cpp&sort=trending).

### 3. Inicie o servidor llama.cpp

Na página do modelo, clique no botão **"Usar este modelo"** e selecione `llama.cpp`. Ele exibirá os comandos exatos para a sua configuração. O primeiro passo é iniciar um servidor llama.cpp, por exemplo

```bash
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](./gguf-llamacpp) 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](https://pi.dev) é o agente por trás do [OpenClaw](https://github.com/openclaw) e agora está integrado diretamente ao Hugging Face, dando a você acesso a milhares de modelos compatíveis.

Instale o Pi:

```bash
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`:

```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:

```bash
pi
```

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

![Demo](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/pi-llama-cpp-demo.gif)

### Habilitando suporte a visão

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

```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](https://huggingface.co/models?pipeline_tag=image-text-to-text&apps=pi).

## OpenClaw

[OpenClaw](https://github.com/openclaw) funciona localmente com llama.cpp. Você pode definir seu modelo por meio do comando a bordo:

```bash
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.

```bash
npm i node-llama-cpp 
```

Aqui está um exemplo de trecho para executar o [EmbeddingGemma-300M quantizado](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF?show_file_info=embeddinggemma-300M-Q8_0.gguf) localmente para busca de memória. O OpenClaw baixa e serve o modelo automaticamente com o comando abaixo.

```bash
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.

```bash
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](https://hermes-agent.nousresearch.com/) funciona localmente com llama.cpp. Defina uma configuração padrão como:

```yaml
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`.

```bash
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.

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

## OpenCode

[OpenCode](https://opencode.ai) funciona localmente com llama.cpp. Defina um `~/.config/opencode/opencode.json`:

```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:

1. **servidor llama.cpp** — Serve o modelo como uma API compatível com a OpenAI em `localhost`.
2. **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](https://github.com/gary149/llama-agent) adota uma abordagem diferente — ele integra o loop do agente diretamente ao [llama.cpp](https://github.com/ggerganov/llama.cpp) como um único binário, sem dependências externas. Sem Node.js, sem Python, basta compilar e executar:

```bash
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](./local-apps) — Saiba mais sobre a execução de modelos em seu computador
- [Guia do llama.cpp](./gguf-llamacpp) — Instalação e uso detalhados do llama.cpp
- [Agentes no Hub](./agents-overview) — Conecte agentes ao ecossistema do Hugging Face