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

يمكنك تشغيل وكيل برمجي بالكامل على أجهزتك الخاصة. يمكن لعدة وكلاء مفتوحين المصدر الاتصال بخادم llama.cpp محلي لتوفير تجربة مشابهة لتجربة Claude Code أو Codex — لكن كل شيء يعمل على جهازك.

البدء

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

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

انتقل إلى huggingface.co/settings/hardware وقم بإعداد ملف عتادك المحلي. ثم اختر llama.cpp في إعدادات التطبيقات المحلية، إذ سيكون هذا هو المحرك الذي ستستخدمه.

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

تصفّح النماذج المتوافقة مع Llama.cpp.

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

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

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

تنزيل هذا النموذج وبدء خادم واجهة برمجة تطبيقات متوافقة مع OpenAI على جهازك. راجع دليل llama.cpp لتعليمات التثبيت.

4. اربط وكيلك

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

Pi

Pi هو الوكيل المسؤول عن OpenClaw، وقد تم دمجه الآن مباشرةً في Hugging Face، مما يمنحك إمكانية الوصول إلى آلاف النماذج المتوافقة.

تثبيت Pi:

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

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

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

pi

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

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

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

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

تصفّح نماذج الرؤية واللغة المتوافقة مع Pi.

OpenClaw

يعمل OpenClaw محليًا مع llama.cpp. يمكنك ضبط نموذجك عبر الأمر المدمج:

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.

npm i node-llama-cpp 

فيما يلي مثال على مقتطف شيفرة لتشغيل EmbeddingGemma-300M المُكمَّم محليًا للبحث في الذاكرة. يقوم OpenClaw بتنزيل النموذج وتقديمه تلقائيًا باستخدام الأمر أدناه.

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"

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

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 محليًا مع llama.cpp. عرّف إعدادًا افتراضيًا على النحو التالي:

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.

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 يُظهر أنه لا تُستخدم أي إضافات ذاكرة أخرى. يُظهر المخرجات أدناه أن التشغيل المحلي نشط.

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

OpenCode

يعمل OpenCode محليًا مع llama.cpp. عرّف ~/.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
          }
        }
      }
    }
  }
}

كيف يعمل

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

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

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

بديل: llama-agent

يتّبع llama-agent نهجًا مختلفًا — إذ يبني حلقة الوكيل مباشرةً داخل llama.cpp كملف تنفيذي واحد بلا أي تبعيات خارجية. لا Node.js ولا Python، فقط اجمع الملف وشغّله:

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.

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

• استخدام نماذج الذكاء الاصطناعي محليًا — تعرّف على المزيد حول تشغيل النماذج على جهازك
• دليل llama.cpp — تثبيت واستخدام llama.cpp بالتفصيل
• الوكلاء على الهاب — اربط الوكلاء بنظام Hugging Face البيئي