# وكلاء محليون باستخدام llama.cpp

يمكنك تشغيل وكيل برمجي بالكامل على أجهزتك الخاصة. يمكن لعدة وكلاء مفتوحين المصدر الاتصال بخادم [llama.cpp](https://github.com/ggerganov/llama.cpp) محلي لتوفير تجربة مشابهة لتجربة Claude Code أو Codex — لكن كل شيء يعمل على جهازك.

## البدء

### 1. اضبط عتادك المحلي

اضبط عتادك المحلي ليُظهر لك أي النماذج متوافقة مع إعدادك.

انتقل إلى [huggingface.co/settings/hardware](https://huggingface.co/settings/hardware) وقم بإعداد ملف العتاد المحلي الخاص بك. ثم اختر `llama.cpp` في [إعدادات التطبيقات المحلية](https://huggingface.co/settings/local-apps)، إذ سيكون هذا هو المحرك الذي ستستخدمه.

### 2. ابحث عن نموذج متوافق

تصفّح [النماذج المتوافقة مع Llama.cpp](https://huggingface.co/models?apps=llama.cpp&sort=trending).

### 3. تشغيل خادم llama.cpp

في صفحة النموذج، انقر على زر **"استخدام هذا النموذج"** واختر `llama.cpp`. سيُظهر لك الأوامر الدقيقة الخاصة بإعدادك. الخطوة الأولى هي تشغيل خادم llama.cpp، على سبيل المثال

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

تنزيل هذا النموذج وبدء خادم واجهة برمجة تطبيقات متوافقة مع OpenAI على جهازك. راجع [دليل llama.cpp](./gguf-llamacpp) لتعليمات التثبيت.

### 4. اربط وكيلك

اختر أحد الوكلاء أدناه واتبع تعليمات الإعداد.

## Pi

[Pi](https://pi.dev) هو الوكيل المسؤول عن [OpenClaw](https://github.com/openclaw)، وقد تم دمجه الآن مباشرةً في Hugging Face، مما يمنحك إمكانية الوصول إلى آلاف النماذج المتوافقة.

تثبيت Pi:

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

ثم أضف نموذجك المحلي إلى ملف إعدادات Pi الموجود في `~/.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"
        }
      ]
    }
  }
}
```

ابدأ Pi في مجلد مشروعك:

```bash
pi
```

يتصل Pi بخادم llama.cpp المحلي لديك ويمنحك جلسة وكيل تفاعلية.

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

### تفعيل دعم الرؤية

بالنسبة إلى النماذج القادرة على الرؤية، أضف `"input": ["text", "image"]` إلى إدخال النموذج في `~/.pi/agent/models.json`:

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

تصفّح [نماذج الرؤية واللغة المتوافقة مع Pi](https://huggingface.co/models?pipeline_tag=image-text-to-text&apps=pi).

## OpenClaw

يعمل [OpenClaw](https://github.com/openclaw) محليًا مع llama.cpp. يمكنك ضبط نموذجك عبر الأمر المدمج:

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

يمكنك أيضًا تشغيل `openclaw onboard` بشكل تفاعلي، واختيار `custom-compatibility` مع `openai`، وتمرير نفس الإعدادات.

### البحث في الذاكرة المحلية لـ OpenClaw

يمكنك تشغيل نماذج تضمين محلية باستخدام Llama.cpp لبحث ذاكرة وكيلك. للقيام بذلك، تأكد من توفر node-llama-cpp.

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

فيما يلي مثال على مقتطف شيفرة لتشغيل [EmbeddingGemma-300M المُكمَّم](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF?show_file_info=embeddinggemma-300M-Q8_0.gguf) محليًا للبحث في الذاكرة. يقوم OpenClaw بتنزيل النموذج وتقديمه تلقائيًا باستخدام الأمر أدناه.

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

أعد تشغيل البوابة وتحقق من ذلك.

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

يعمل [Hermes Agent](https://hermes-agent.nousresearch.com/) محليًا مع llama.cpp. عرّف إعدادًا افتراضيًا على النحو التالي:

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

يستهلك وكيل Hermes نماذج البحث الدلالي من خلال نقاط النهاية. بمجرد تشغيل نموذج التضمين المفضل لديك على نقطة النهاية 8080 باستخدام llama.cpp أو محرك الاستدلال الذي تختاره، أضف ما يلي إلى `~/.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
```

تحقق من أن هذا يعمل، `none - built-in only` يُظهر أنه لا تُستخدم أي إضافات ذاكرة أخرى. يُظهر المخرجات أدناه أن التشغيل المحلي نشط.

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

## OpenCode

يعمل [OpenCode](https://opencode.ai) محليًا مع llama.cpp. عرّف `~/.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
          }
        }
      }
    }
  }
}
```

## كيف يعمل

يتضمن الإعداد مكونين يعملان محليًا:

1. **خادم llama.cpp** — يقدّم النموذج كواجهة برمجية متوافقة مع OpenAI على `localhost`.
2. **وكيلك** — عملية الوكيل التي ترسل الأوامر إلى الخادم المحلي، وتُفكّر في المهام، وتنفّذ الإجراءات.

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

## بديل: llama-agent

يتّبع [llama-agent](https://github.com/gary149/llama-agent) نهجًا مختلفًا — إذ يبني حلقة الوكيل مباشرةً داخل [llama.cpp](https://github.com/ggerganov/llama.cpp) كملف تنفيذي واحد بلا أي تبعيات خارجية. لا Node.js ولا Python، فقط اجمع الملف وشغّله:

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

بما أن استدعاءات الأدوات تحدث داخل العملية بدلاً من المرور عبر HTTP، فلا يوجد أي عبء شبكي بين النموذج والوكيل. كما يدعم الوكلاء الفرعيين، وخوادم MCP، ووضع خادم واجهة برمجة التطبيقات HTTP.

## الخطوات التالية

- [استخدام نماذج الذكاء الاصطناعي محليًا](./local-apps) — تعرّف على المزيد حول تشغيل النماذج على جهازك
- [دليل llama.cpp](./gguf-llamacpp) — تثبيت واستخدام llama.cpp بالتفصيل
- [الوكلاء على الهاب](./agents-overview) — اربط الوكلاء بنظام Hugging Face البيئي