# llama.cpp ile Yerel Ajanlar

Kodlama ajanını tamamen kendi donanımınızda çalıştırabilirsiniz. Birkaç açık kaynaklı ajan, size Claude Code veya Codex'e benzer bir deneyim sunmak için yerel bir [llama.cpp](https://github.com/ggerganov/llama.cpp) sunucusuna bağlanabilir — ancak her şey makinenizde çalışır.

## Başlangıç

### 1. Yerel Donanımınızı Ayarlayın

Yerel donanımınızı yapılandırın; böylece kurulumunuzla uyumlu modelleri görebilirsiniz.

[huggingface.co/settings/hardware](https://huggingface.co/settings/hardware) adresine gidin ve yerel donanım profilinizi yapılandırın. Ardından, kullanacağınız motor bu olacağı için [Yerel Uygulamalar ayarlarınızda](https://huggingface.co/settings/local-apps) `llama.cpp` seçeneğini seçin.

### 2. Uygun Bir Model Bulun

[Llama.cpp ile uyumlu modelleri](https://huggingface.co/models?apps=llama.cpp&sort=trending) görüntüleyin.

### 3. llama.cpp Sunucusunu Başlatın

Model sayfasında **"Bu modeli kullan"** düğmesine tıklayın ve `llama.cpp` seçeneğini işaretleyin. Kurulumunuza uygun tam komutlar gösterilir. İlk adım, bir llama.cpp sunucusu başlatmaktır, örneğin

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

Bu, modeli indirir ve makinenizde OpenAI ile uyumlu bir API sunucusu başlatır. Kurulum talimatları için [llama.cpp kılavuzuna](./gguf-llamacpp) bakın.

### 4. Ajanınızı Bağlayın

Aşağıdaki ajanlardan birini seçin ve kurulum talimatlarını izleyin.

## Pi

[Pi](https://pi.dev), [OpenClaw](https://github.com/openclaw)'ın arkasındaki ajan ve artık Hugging Face'e doğrudan entegre edilmiş durumda; bu sayede binlerce uyumlu modele erişim imkânı sunuyor.

Pi'yi yükleyin:

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

Ardından yerel modelinizi `~/.pi/agent/models.json` konumundaki Pi yapılandırma dosyasına ekleyin:

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

Proje dizininizde Pi'yi başlatın:

```bash
pi
```

Pi, yerel llama.cpp sunucunuza bağlanır ve size etkileşimli bir ajan oturumu sağlar.

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

### Görüntü desteğini etkinleştirme

Görüntü yeteneğine sahip modeller için `~/.pi/agent/models.json` dosyasındaki model girdisine `"input": ["text", "image"]` ekleyin:

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

Pi ile uyumlu [görsel-dil modellerini](https://huggingface.co/models?pipeline_tag=image-text-to-text&apps=pi) görüntüleyin.

## OpenClaw

[OpenClaw](https://github.com/openclaw), llama.cpp ile yerel olarak çalışır. Modelinizi yerleşik komutla ayarlayabilirsiniz:

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

Ayrıca `openclaw onboard` komutunu etkileşimli olarak çalıştırıp `custom-compatibility` seçeneğini `openai` ile seçerek aynı yapılandırmayı iletebilirsiniz.

### OpenClaw için Yerel Bellek Araması

Ajanınızın bellek araması için yerel gömme modellerini Llama.cpp ile çalıştırabilirsiniz. Bunu yapmak için node-llama-cpp'ın kurulu olduğundan emin olun.

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

Yerel bellek araması için [quantized EmbeddingGemma-300M](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF?show_file_info=embeddinggemma-300M-Q8_0.gguf) çalıştırmak için örnek bir kod parçası aşağıdadır. OpenClaw, aşağıdaki komutla modeli otomatik olarak indirir ve sunar.

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

Gateway'yi yeniden başlatın ve doğrulayın.

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

[Hermes Agent](https://hermes-agent.nousresearch.com/), llama.cpp ile yerel olarak çalışır. Varsayılan yapılandırmayı şu şekilde tanımlayın:

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

### Hermes Ajanı için Yerel Bellek Araması

Hermes Agent, anlamsal arama modellerini uç noktalar üzerinden kullanır. Tercih ettiğiniz gömme modelini 8080 numaralı uç noktada llama.cpp veya tercih ettiğiniz çıkarım motoruyla çalıştırdıktan sonra, aşağıdakileri `~/.hermes/config.yaml` dosyasına ekleyin.

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

Bunun çalıştığını kontrol edin, `none - built-in only` başka bir bellek eklentisinin kullanılmadığını gösterir. Aşağıdaki çıktı, yerel sunumun aktif olduğunu gösterir.

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

## OpenCode

[OpenCode](https://opencode.ai), llama.cpp ile yerel olarak çalışır. `~/.config/opencode/opencode.json` tanımlayın:

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

## Nasıl Çalışır

Kurulum, yerel olarak çalışan iki bileşenden oluşur:

1. **llama.cpp sunucusu** — Modeli `localhost` üzerinde OpenAI ile uyumlu bir API olarak sunar.
2. **Ajanınız** — Yerel sunucuya istemler gönderen, görevler hakkında akıl yürüten ve eylemleri yürüten ajan süreci.

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

## Alternatif: llama-agent

[llama-agent](https://github.com/gary149/llama-agent) farklı bir yaklaşım benimser — ajan döngüsünü [llama.cpp](https://github.com/ggerganov/llama.cpp) içine, harici bağımlılığı sıfır olan tek bir ikili dosya olarak doğrudan yerleştirir. Node.js yok, Python yok, derleyip çalıştırmanız yeterli:

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

Araç çağrıları HTTP üzerinden değil, süreç içi gerçekleştiği için model ile ajan arasında ağ gecikmesi yoktur. Ayrıca alt ajanları, MCP sunucularını ve bir HTTP API sunucu modunu destekler.

## Sonraki Adımlar

- [Yapay Zeka Modellerini Yerel Olarak Kullanın](./local-apps) — Modelleri kendi makinenizde çalıştırma hakkında daha fazla bilgi edinin
- [llama.cpp Kılavuzu](./gguf-llamacpp) — Detaylı llama.cpp kurulumu ve kullanımı
- [Hub'daki Ajanlar](./agents-overview) — Ajanları Hugging Face ekosistemine bağlayın