كيف تستخدم 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 بشكل منفصل. يغطي ذلك معظم ما يُقصد عادةً بوكيل برمجة في أغسطس 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. إذا كان خادمك يعمل باستخدام CPU فقط أو يفتقر إلى RAM، توضّح حسابات الذاكرة لوسم Qwen 27B على VPS ما يمكن تشغيله فعلياً ضمن 8 إلى 64 GB قبل بدء التنزيل. بعد سحب النموذج، ستُخزَّن تلك الجيجابايتات على القرص الجذري للخادم، وهو الجزء من VPS الذي يملك أقل مساحة احتياطية، لذلك من المفيد قراءة مكان احتفاظ Ollama بملفات النماذج وكيفية نقلها إلى مكان آخر قبل امتلاء القرص.

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

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 يتجاهل بصمت السياق الذي يتجاوز النافذة. تسقط أقدم الرموز، لذلك يجيب النموذج بثقة عن ملف لم يعد يراه، أو ينسى تعليمة أعطيته إياها قبل خطوتين. تقف هذه الآلية وراء معظم التقارير التي تفيد بأن النموذج المحلي غبي أكثر من اللازم لكتابة التعليمات البرمجية. واختيار القيمة نفسها قرار مستقل، ويستحق ما يكلّفه num_ctx من ذاكرة KV cache عند كل حجم القراءة قبل اعتماد قيمة معينة.

تقول وثائق 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 طلب قيمة له. كما أن الإعداد يخص كل خادم، ولذلك يرثه كل وكيل توجّهه إلى الخادم. ولجهة الإخراج حد أقصى مستقل، وعلى خلاف طول السياق ينتقل هذا الحد عبر compatibility endpoint، لذلك فإن num_predict وحقل max_tokens الذي يقابله هما الخياران المناسبان عندما تتوقف الإجابة في منتصف patch. إذا احتاج نموذج واحد إلى نافذة مختلفة، فضمّنها في نسخة باستخدام 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 دقائق من آخر طلب. هذا مناسب لمربع محادثة، لكنه غير مناسب لعمل الوكلاء. قد تتوقف لقراءة diff، وينتهي المؤقت، ثم يعيد الطلب التالي تحميل عشرات الجيجابايت من الأوزان من القرص قبل ظهور أول token. ويبدو ذلك كأنه توقف.

يأخذ 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 على خادم منفصل

يرتبط Ollama بعنوان localhost. للوصول إليه من جهاز آخر، عيّن OLLAMA_HOST=0.0.0.0:11434 في تجاوز 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 النقطة التي يبدأ عندها فرق معدل المعالجة بالتأثير سلباً.

متى يتفوّق نموذج برمجي محلي، ومتى لا يتفوّق

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

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

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

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

أنماط الفشل، والعبارات التي ستراها

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

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

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

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

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

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

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 كافية. إذا كان هذا الوسم أكبر من قدرة خادمك، فستكون أرقام RAM وسرعات التشغيل باستخدام CPU فقط لنموذج Nemotron 3.5 Lightning مقارنة مفيدة قبل بدء التنزيل. تحت نحو 14B من المعاملات، يمكن للنموذج أن يجيب جيداً عن الأسئلة المتعلقة بالشيفرة، لكنه قد يفشل في التعديلات متعددة الخطوات، لأن عمل الوكيل يتأثر بشدة بالأخطاء الصغيرة في تنسيق استدعاءات الأدوات. اختبره باستخدام مهمة حقيقية من مستودعك، لا باستخدام مطالبة نموذجية.

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

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