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

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

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

يستمع Ollama على المنفذ 11434، ويقدّم ثلاث واجهات API في الوقت نفسه. /api هي API الأصلية لـOllama. أما /v1 فهي الطبقة المتوافقة مع OpenAI، وتغطي بدورها عدة صيغ: /v1/chat/completions و/v1/responses و/v1/completions و/v1/models و/v1/embeddings. توضّح وثائق Ollama أن المفتاح مطلوب هناك، لكنه يُتجاهل. الواجهة الثالثة متوافقة مع Anthropic: يستخدم العميل http://localhost:11434 عنوان URL الأساسي، ثم يضيف /v1/messages، وهو المسار الذي يتحدث إليه Claude Code. تستخدم معظم الوكلاء /v1/chat/completions، بينما يستخدم Codex /v1/responses، ويستخدم Claude Code /v1/messages. يتحدث وكيلك بالفعل بإحدى هذه الواجهات، لذلك لا يتغير فيه شيء آخر.

يستغرق إعداد هذا الجزء خمس دقائق. أما قابلية استخدام النتيجة فتعتمد على إعدادين لا يغيرهما أحد تقريباً: طول السياق و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 السبب.

يجب أن يدعم النموذج استدعاء الأدوات، لأن الوكيل يعمل بهذه الطريقة. فهو يقرأ ملفاً، ويكتب patch، ويشغّل الاختبار، ثم يقرأ الفشل ويحاول مرة أخرى. النموذج الذي لا يستطيع إصدار استدعاء أداة سيصف التعديل نصياً بدلاً من تنفيذه، وقد يدخل الوكيل في حلقة أو يتوقف. ابحث عن التصنيف tools في صفحة النموذج على ollama.com قبل سحبه. يحمل qwen3-coder:30b هذا التصنيف، واعتباراً من October 2026 يكون هذا الوسم تنزيلًا بحجم 19 GB مع نافذة سياق بسعة 256K. إذا كان خادمك يعتمد على CPU فقط أو يملك قدراً قليلاً من RAM، توضّح حسابات الذاكرة الخاصة بوسم Qwen 27B على VPS ما الذي يتسع له فعلياً نطاق من 8 إلى 64 GB قبل أن تبدأ التنزيل. بعد سحب النموذج، ستُخزَّن تلك الجيجابايتات على root disk للخادم، وهو الجزء الأقل مساحة احتياطية في 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 كبير.

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

تذكر وثائق Ollama أن المهام مثل agents وأدوات البرمجة يجب ضبطها على 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

اضبط القيمة على الخادم بدلاً من agent لسببين. لا يحتوي مخطط OpenAI chat completions على حقل لطول السياق، لذلك لا يستطيع العميل المتوافق مع OpenAI طلبه. كما أن الإعداد يخص الخادم، ولذلك يرثه كل agent توجّهه إلى هذا الخادم. ولجهة المخرجات حد أقصى مستقل. وبخلاف طول السياق، ينتقل هذا الحد عبر 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، ينخفض معدل الرموز بدرجة تجعل حلقة agent غير قابلة للاستخدام. وتساعدك طريقة قياس الرموز في الثانية على LLM محلي في العثور على الحد الفعلي لخادمك. ويتناول مقدار RAM وCPU الذي يحتاجه VPS لتشغيل coding agent كيفية تحديد مواصفات الجهاز قبل شرائه.

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

يفرّغ 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 للنموذج مع سياقه. إذا كان PROCESSOR يعرض 100% CPU على جهاز يحتوي على GPU، فاستبعد السبب الآخر أولاً: قد لا يكون Ollama قد عثر على GPU أصلاً. تشير وثائق Ollama إلى أنه على Linux قد يفشل أحياناً في اكتشاف NVIDIA GPU بعد دورة suspend/resume، ويعود إلى CPU، وأن إعادة تحميل برنامج التشغيل باستخدام sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm تتجاوز هذه المشكلة. إذا عُثر على GPU واستمر التقسيم، فخفّض طول السياق، أو انتقل إلى نموذج أصغر أو 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، وينخفض معدل الرموز انخفاضاً حاداً.