كيفية استخدام Ollama مع وكيل البرمجة لديك

ما الذي تتصل به

يمكنك استخدام Ollama مع وكيل البرمجة لديك، والاتصال أبسط مما يتوقعه معظم الناس. غيّر عنوان URL الأساسي وحدد اسم نموذج واحد. لا يزال حقل مفتاح API يتطلب قيمة، لكن الخادم المحلي يتجاهلها، لذا تصلح أي سلسلة نصية.

يستمع Ollama على المنفذ 11434 ويخدم شكلين من الطلبات في الوقت نفسه. /v1/chat/completions هو الشكل المتوافق مع OpenAI، وتوضح وثائق Ollama أن المفتاح فيه مطلوب، لكنه متجاهَل. /v1/messages هو الشكل المتوافق مع Anthropic، وهو الشكل الذي يتحدث به Claude Code. يتحدث وكيلك بالفعل بأحد الشكلين، لذلك لا يتغير أي شيء آخر فيه.

يستغرق هذا الجزء خمس دقائق. أما قابلية استخدام النتيجة فتعتمد على إعدادين لا يغيّرهما أحد تقريباً: طول السياق وkeep-alive، وعلى إسناد نوع العمل الذي يجيده النموذج إليه. سيحصل كل منهما على قسم مستقل، وستجد القيود الفعلية في النهاية.

ما وكلاء البرمجة الذين يقبلون عنوان URL أساسياً محلياً

الاختبار يتكون من سؤال واحد: هل تتيح الأداة إعداد عنوان URL أساسياً؟ إذا كانت تتيحه، فيمكنها الاتصال بخادمك.

تنشر Ollama صفحات تكامل مع Claude Code وOpenCode وCodex وCline وRoo Code وZed وJetBrains IDEs وVS Code. وتوثّق Aider دعمها الخاص لـOllama في صفحة منفصلة. يغطي ذلك معظم ما يُقصد عادةً بوكيل برمجة في August 2026. لا تستخدم هذه الأدوات جميعاً البنية نفسها، وهذا الاختلاف هو سبب فشل الإعدادات.

• تحتاج معظم الوكلاء إلى نقطة نهاية متوافقة مع OpenAI. امنحها عنوان URL الأساسي http://localhost:11434/v1 وأي سلسلة غير فارغة لمفتاح API.
• لا يقبل Claude Code عنوان URL أساسياً لـOpenAI إطلاقاً. فهو يستخدم Anthropic Messages API، ولذلك يجب ضبط ANTHROPIC_BASE_URL على http://localhost:11434، حيث توفّر Ollama /v1/messages.
• يستخدم Codex واجهة OpenAI Responses API. وتوفّر Ollama /v1/responses أيضاً، بدءاً من الإصدار 0.13.3.
• لا يمكن إعادة توجيه وكيل لا يتيح إعداد عنوان URL أساسياً، لأن نقطة النهاية مضمّنة في العميل. بدلاً من ذلك، ضع طبقة ترجمة أمامه، مثل بوابة LiteLLM مستضافة ذاتياً، وأعد إتاحة نموذجك بالصيغة التي يتطلبها العميل.

يمكن لـOllama كتابة هذه الإعدادات نيابةً عنك. يبدأ ollama launch opencode تشغيل OpenCode مع إعداد مضمن للنموذج الذي تختاره، وينفّذ ollama launch claude الإجراء نفسه مع Claude Code، بينما يكتب ollama launch droid --config الإعداد دون تشغيل الأداة.

تثبيت Ollama وسحب نموذج يمكنه استدعاء الأدوات

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

يضيف برنامج التثبيت وحدة systemd ويبدأ تشغيلها، لذلك يجب أن يعرض systemctl status ollama القيمة active (running). وإذا لم يعرضها، فسيطبع journalctl -e -u ollama السبب.

يجب أن يدعم النموذج استدعاء الأدوات، لأن استدعاء الأدوات هو الطريقة التي يعمل بها الوكيل. يقرأ ملفاً، ويكتب تصحيحاً، ويشغّل الاختبار، ثم يقرأ الفشل ويحاول مرة أخرى. النموذج الذي لا يستطيع إصدار استدعاء أداة سيصف التعديل نصياً بدلاً من تنفيذه، وقد يدخل الوكيل في حلقة أو يتوقف. ابحث عن التصنيف tools في صفحة النموذج على ollama.com قبل سحبه. يحمل qwen3-coder:30b هذا التصنيف، واعتباراً من August 2026 يبلغ حجم هذا التنزيل 19 GB وتبلغ نافذة السياق 256K.

تحقق الآن من الأسماء التي يوفّرها الخادم فعلياً:

curl http://localhost:11434/v1/models

السلاسل النصية في هذه الاستجابة هي ما يجب أن يتضمنه إعداد الوكيل، حرفياً. يؤدي التحقق منها أولاً إلى حل معظم أخطاء عدم العثور على النموذج. إذا لم يكن Ollama مثبتاً بعد، فراجع الشرح الأطول في استضافة LLM ذاتياً باستخدام Ollama على VPS.

وجّه OpenCode إلى Ollama

حرّر ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

المفتاح ضمن models هو اسم النموذج الذي يُرسل إلى Ollama، لذلك يجب أن يطابق ollama ls تماماً. الحقل name هو مجرد التسمية الظاهرة في منتقي النماذج. ابدأ opencode، وانتقل إلى موفّر Ollama، وراقب journalctl -e -u ollama للتأكد من وصول الطلب إلى خادمك بدلاً من وصوله إلى مكان آخر. يوضّح تشغيل OpenCode على VPS إعداد الوكيل نفسه.

وجّه Claude Code إلى Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

تم تعيين ANTHROPIC_API_KEY إلى سلسلة فارغة عن قصد. إذا تُرك مفتاح حقيقي في البيئة، فستُرسل طلباتك إلى API المستضاف بدلاً من ذلك، وستتحمل تكلفة مالية من دون تنفيذ محلي. يتولى ollama launch claude ضبط كل ذلك نيابةً عنك.

تعرّف إلى ما لا توفّره طبقة التوافق. فهي لا تنفّذ tool_choice أو تخزين المطالبات مؤقتاً، ولا توفّر نقطة نهاية لعدّ الرموز، لذلك فإن أعداد الرموز التي تراها تقريبية ومأخوذة من أداة تقسيم الرموز الخاصة بالنموذج. يحمّل Claude Code أيضاً مطالبة نظام كبيرة ومجموعة أدوات كبيرة، ولذلك يحتاج إلى سياق أكبر مما يحتاج إليه عميل محادثة. يتناول ما إذا كان يمكنك استضافة Claude ذاتياً السؤال الأوسع حول ما ينتقل وما لا ينتقل.

وجّه Aider إلى Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

توصي وثائق Aider باستخدام البادئة ollama_chat/ بدلاً من ollama/. كما تتيح لك تثبيت نافذة السياق لكل نموذج في .aider.model.settings.yml، وهذا مفيد عندما يحتاج أحد النماذج إلى نافذة مختلفة عن الإعداد الافتراضي للخادم:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

لماذا ينتج الإعداد العامل مخرجات غير منطقية

هذا هو القسم المهم. يختار Ollama طول السياق الافتراضي من VRAM، أي ذاكرة الفيديو في GPU، التي يستطيع رؤيتها. وهذه القيم الافتراضية منشورة:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

تستخدم معظم خطط VPS، وكل خادم يعمل بالـCPU فقط، الصف الأول: 4,096 من الرموز. ولا يحصل على 262,144 من الرموز في الصف الأخير إلا GPU كبير.

يمرّر الوكيل 4096 رمزاً قبل أن ينفّذ أي عمل. ويكون prompt النظام وتعريفات الأدوات وقائمة المستودع وأول ملف يفتحه أكبر من ذلك بالفعل. ما يحدث بعد ذلك هو جوهر المشكلة: لا يظهر أي خطأ. توضّح وثائق Aider أن Ollama يتجاهل بصمت السياق الذي يتجاوز حجم النافذة. فتخرج أقدم الرموز من السياق، ويجيب النموذج بثقة عن ملف لم يعد يراه، أو ينسى تعليمة أعطيته إياها قبل خطوتين. تقف هذه الآلية وراء معظم التقارير التي تصف النموذج المحلي بأنه غبي جداً لكتابة التعليمات البرمجية.

تذكر وثائق Ollama أن المهام مثل الوكلاء وأدوات البرمجة يجب أن تُضبط على 64000 رمز على الأقل. اضبط ذلك على الخادم:

sudo systemctl edit ollama.service

أضف هذه الأسطر إلى ملف override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

ثم أعد التحميل وأعد التشغيل:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps هو الاختبار. فهو يطبع عمود CONTEXT، وهذا الرقم هو ما استلمه النموذج فعلياً. ستختلف قيمتا ID وSIZE لديك:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

اضبط القيمة على الخادم بدلاً من ضبطها في الوكيل، لسببين. لا يحتوي مخطط OpenAI chat completions على حقل لطول السياق، لذلك لا يستطيع العميل المتوافق مع OpenAI طلب قيمة له. كما أن الإعداد يخص الخادم، ولذلك يرثه كل وكيل توجّهه إلى الخادم. إذا احتاج أحد النماذج إلى نافذة مختلفة، فضمّنها في نسخة منه باستخدام Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

السياق ليس مجانياً. تستهلك النافذة الأطول ذاكرة أكبر، لذلك راقب عمود PROCESSOR. المطلوب هو 100% GPU. عندما ينتقل جزء من النموذج إلى CPU، ينخفض معدل الرموز بما يكفي لجعل حلقة الوكيل غير قابلة للاستخدام. وتساعدك قياس الرموز في الثانية على LLM محلي على معرفة الحد الفعلي لخادمك. ويتناول مقدار RAM وCPU الذي يحتاج إليه VPS لوكيل برمجي كيفية تحديد حجم الجهاز قبل شرائه.

إبقاء النموذج محمّلاً بين الطلبات

تُفرغ Ollama النموذج تلقائياً بعد 5 دقائق من آخر طلب. هذا مناسب لمربع الدردشة وغير مناسب لعمل الوكلاء. تتوقف لقراءة فرق التغييرات، وينتهي المؤقت، ثم يعيد الطلب التالي تحميل عشرات الغيغابايت من الأوزان من القرص قبل ظهور الرمز الأول. ويبدو ذلك كأن النظام قد تجمّد.

يقبل OLLAMA_KEEP_ALIVE سلسلة مدة مثل 10m أو 24h، أو رقماً عادياً يمثل عدد الثواني، أو -1 لإبقاء النموذج محمّلاً دون حد زمني، أو 0 لإفراغه فوراً. اضبطه بجانب طول السياق:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

لا يتوفر حقل الطلب keep_alive إلا في نقطتي النهاية الأصليتين /api/generate و/api/chat في Ollama، وليس في نقاط النهاية المتوافقة. لذلك لا يستطيع الوكيل ضبطه لكل طلب. متغير البيئة هو الأداة الوحيدة المتاحة لك. عندما تحتاج إلى استعادة الذاكرة، يفرغ ollama stop qwen3-coder:30b النموذج دون إيقاف الخادم.

تشغيل Ollama على خادم منفصل

يرتبط Ollama بعنوان localhost. للوصول إليه من جهاز آخر، عيّن OLLAMA_HOST=0.0.0.0:11434 في ملف override نفسه الخاص بـsystemd، ثم أعد تشغيل الخدمة.

نفّذ ذلك على شبكة خاصة فقط. توضّح وثائق Ollama أن واجهة API المحلية لا تتطلب مصادقة، لذلك فإن فتح المنفذ 11434 على الإنترنت يتيح لأي شخص استخدام موارد جهازك وقراءة كل ما يرسله وكيلك. هناك خياران آمنان. أبقِ الارتباط على localhost، وحوّل المنفذ عبر SSH من حاسوبك المحمول:

ssh -N -L 11434:localhost:11434 you@your-vps

سيواصل وكيلك الإشارة إلى http://localhost:11434/v1 ولن يلاحظ أي اختلاف. الخيار الآخر هو استخدام VPN، مع ربط Ollama بعنوان VPN بدلاً من 0.0.0.0. إذا كان عدة أشخاص أو عدة وكلاء سيشاركون جهازاً واحداً، فإن مجدول Ollama غير مصمم لهذا الحمل، وتوضح المقارنة بين Ollama وvLLM النقطة التي يبدأ عندها فرق معدل المعالجة بالتسبب في مشكلات.

حيث يتفوق نموذج البرمجة المحلي، وحيث لا يتفوق

لا يحلّ وكيل يديره نموذج تستضيفه محلّ واجهة API متقدمة في كل مهمة. لكنه يتفوق بوضوح في أربعة أنواع من العمل.

• التعديلات الميكانيكية واسعة النطاق، عندما يكون كل تغيير صغيراً ويمكنك التحقق منه. إعادة التسمية عبر مستودع، وإضافة تلميحات الأنواع، وكتابة docstrings، وترجمة التعليقات. يمكن للنموذج أن يعمل لساعات من دون أن تتغير الفاتورة.
• العمل الذي يجب ألا يغادر أجهزتك. مثل شيفرة عميل مشمولة باتفاقية سرية، أو مستودع داخلي لا يُسمح لك بإرساله إلى طرف ثالث.
• الأجهزة غير المتصلة بالإنترنت أو المعزولة عن الشبكة، حيث لا توجد واجهة API مستضافة يمكن استدعاؤها أصلاً.
• التكلفة المتوقعة. بعد دفع تكلفة الخادم، لا يضيف الوكيل الذي يستهلك tokens داخل حلقة أي تكلفة إضافية، وهذا عكس واجهة API التي تحاسب حسب الاستخدام. تتضمن متى تتعادل تكلفة GPU VPS مع تكلفة tokens في واجهة API الحسابات.

يتراجع أداؤه في المهام الطويلة متعددة الخطوات. تتطلب مهمة «اكتشف سبب فشل هذا الاختبار، وأصلح السبب، وحدّث المستدعين» إجراء العديد من استدعاءات الأدوات الصحيحة بالتتابع، مع إبقاء السجل الكامل ضمن السياق. سينتج نموذج ضمن نطاق 8B إلى 14B على خادم متواضع استدعاء أداة مشوهاً، أو سيفقد الخطة بعد بضع جولات، وستقضي وقتاً في توجيهه يفوق الوقت الذي كانت ستستغرقه المهمة. هذه ليست مشكلة prompt يمكن حلها بصياغة أفضل. إنها مشكلة سعة.

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

أنماط الفشل والنصوص التي ستظهر لك

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. الخادم لا يعمل، أو أن agent يشير إلى مضيف مختلف. شغّل systemctl status ollama، ثم journalctl -e -u ollama.

يُبلغ agent بأن النموذج غير موجود. لا يطابق الاسم في ملف الإعداد اسماً يوفّره الخادم. قارنه مع curl http://localhost:11434/v1/models، وانسخ النص منه. تُعد العلامة جزءاً من الاسم، لذلك يفشل الإعداد الذي يحدد علامة لم تسحبها من قبل، حتى إذا كان نموذج مشابه مثبتاً.

يجيب agent بنص نثري ولا يحرر أي ملف. إما أن النموذج لا يدعم الأدوات، أو أن الطلب وتعريفات أدواته يملآن نافذة السياق مسبقاً. تحقّق من تسمية tools في صفحة النموذج، ثم تحقّق من العمود CONTEXT في ollama ps.

صمت طويل قبل ظهور الرمز الأول، ثم سرعة طبيعية. انتهت مدة keep-alive، وتُقرأ الأوزان من القرص مجدداً. اضبط OLLAMA_KEEP_ALIVE.

يناقض النموذج ملفاً قرأه للتو. هذا اقتطاع للسياق. يعرض ollama ps عادةً قيمة CONTEXT أصغر مما تتوقع أنك ضبطته، لأن متغير البيئة أُرسل إلى shell لديك بدلاً من وحدة systemd.

يعمل كل شيء ببطء، وPROCESSOR ليس 100% GPU. لا يتسع VRAM للنموذج مع سياقه. خفّض طول السياق، أو انتقل إلى نموذج أصغر أو quantisation أصغر.

FAQ

هل يمكنني توجيه Claude Code إلى Ollama؟

نعم، ولكن ليس باستخدام URL متوافق مع OpenAI. يتحدث Claude Code مع Anthropic Messages API، ويعرض Ollama هذا الشكل على /v1/messages في المنفذ نفسه 11434. صدّر ANTHROPIC_BASE_URL=http://localhost:11434 وANTHROPIC_AUTH_TOKEN=ollama واضبط ANTHROPIC_API_KEY على قيمة فارغة، ثم شغّله باستخدام claude --model qwen3-coder:30b. يكتب ollama launch claude الإعدادات نفسها نيابةً عنك. لا تطبّق طبقة التوافق tool_choice أو التخزين المؤقت للمطالبات، ولا توفّر نقطة نهاية لعدّ الرموز، لذلك تُعدّ أعداد الرموز المبلّغ عنها تقريبية.

لماذا يجيب النموذج المحلي عن شيفرة لا يستطيع رؤيتها؟

لأن الطلب لم يعد يتسع ضمن نافذة السياق، وقد أُسقط أقدم جزء منه من دون ظهور خطأ. يحدد Ollama سياقه الافتراضي استناداً إلى VRAM التي يعثر عليها. وعندما تقل عن 24 GiB، يكون هذا الإعداد الافتراضي 4,096 رمزاً، وهو أقل من أن يستوعب موجه النظام وتعريفات الأدوات الخاصة بالوكيل وحدها. اضبط OLLAMA_CONTEXT_LENGTH=64000 في وحدة systemd، وأعد تشغيل Ollama، وتأكد من أن العمود CONTEXT في ollama ps يعرض القيمة الجديدة.

ما النموذج الذي ينبغي أن أشغّله لوكيل برمجي على VPS؟

اختر أكبر نموذج يحمل التصنيف tools ويمكنه البقاء في الذاكرة مع نافذة سياق بحجم 64k، وفضّل نموذجاً محسّناً للشيفرة. يُعد qwen3-coder:30b الخيار الشائع على خادم GPU الذي يملك VRAM كافية. عندما يقل عدد المعاملات تقريباً عن 14B، يستطيع النموذج مع ذلك الإجابة جيداً عن أسئلة الشيفرة، لكنه قد يفشل في التعديلات متعددة الخطوات، لأن عمل الوكيل يتأثر بشدة بأخطاء التنسيق الصغيرة في استدعاءات الأدوات. اختبره باستخدام مهمة حقيقية واحدة من مستودعك، لا باستخدام موجه تجريبي.

هل أحتاج إلى GPU لتشغيل وكيل برمجي باستخدام نموذجي الخاص؟

عملياً، نعم. يعمل الاستدلال باستخدام CPU فقط، ويكون مناسباً للأسئلة الفردية، لكن الوكيل يرسل طلبات كثيرة لكل مهمة، ويعيد كل طلب قراءة سجل طويل، لذلك يحوّل معدل الرموز البطيء مهمة تستغرق دقيقتين إلى مهمة تستغرق ساعة. افحص العمود PROCESSOR في ollama ps: أي قيمة غير 100% GPU تعني أن جزءاً من النموذج يعمل على CPU، وينخفض معدل الرموز بشدة.