دليل إعداد النموذج المحلي باستخدام Ollama مع Claude Code

Claude Code هو وكيل البرمجة الطرفي الرسمي من Anthropic، ويتواصل افتراضيًّا مع واجهة برمجة التطبيقات السحابية الخاصة بـ Anthropic. أما Ollama فهو برنامج لتشغيل النماذج محليًّا، ويقدِّم واجهة برمجة تطبيقات HTTP متوافقة مع OpenAI. وهذان النظامان لا يتوصّلان مباشرةً ببعضهما لأن بروتوكول الاتصال بينهما غير متوافق من الجهة الأولى، وبالتالي يتطلّب ربطهما طبقة وسيطة صغيرة تقوم بترجمة واجهة رسائل Anthropic (Messages API) إلى واجهة الدردشة (chat API) التي يوفّرها Ollama. ويغطي هذا الدليل آلية عمل هذه الطبقة، وأفضل النماذج التي يستحق تشغيلها، والنقاط التي قد يفشل فيها الإعداد.

لماذا لا يتوصّل Ollama وClaude Code مباشرةً

يُرسل Claude Code طلباته بصيغة واجهة رسائل Anthropic (Messages API) (/v1/messages)، والتي تتضمّن حقولًا مخصصة من Anthropic لاستخدام الأدوات، والتحكم في التخزين المؤقت، والتعليمات النظامية (system prompts). أما Ollama فيوفّر واجهة برمجة تطبيقات /api/chat وواجهة أخرى متوافقة مع OpenAI /v1/chat/completions . ولا يدعم أيٌّ منهما لغة Anthropic الأصلية. ولربطهما، تحتاج إلى وسيط يقوم بما يلي:

• استقبال الطلبات بصيغة Anthropic عبر نقطة نهاية HTTPS.
• إعادة صياغتها على هيئة طلبات إكمال دردشة متوافقة مع OpenAI.
• إعادة توجيهها إلى Ollama، ثم ترجمة الاستجابات المتدرّجة واستدعاءات الأدوات مرةً أخرى إلى تدفق الأحداث الخاص بـ Anthropic الذي يتوقعه Claude Code.

وباعتبار عام ٢٠٢٦، هناك مشروعان يتعاملان مع هذه المهمة بكفاءة وموثوقية: claude-code-router (راوتر مصمَّم خصيصًا لـ Claude Code، ويدعم Ollama وOpenRouter وخلفيات أخرى) و LiteLLM (وسيط عام الغرض يحتوي على وضع anthropic تمرير مباشر). وكلا الخيارين عملي، لكن claude-code-router أقل تعقيدًا إذا كان Ollama هو الخلفية الوحيدة التي تستخدمها.

المتطلبات الأساسية

• تثبيت Ollama وتشغيله. راجع كيفية تثبيت منصة Ollama إذا لم تكن قد ثبّته بعد.
• تثبيت Claude Code (تثبيت npm -g @anthropic-ai/claude-code).
• نموذج واحد على الأقل قادر على البرمجة، وقد تم سحبه محليًّا.
• Node.js 18+ لتشغيل claude-code-router، أو Python 3.10+ لتشغيل LiteLLM.

تحقَّق من إمكانية الوصول إلى Ollama عبر الأمر:

curl http://localhost:11434/api/tags

اختيار نموذج محلي

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

مستوى التكميم، وطول السياق، وحجم ذاكرة التخزين المؤقت KV كلها عوامل تؤثِّر في متطلبات الذاكرة العشوائية VRAM. استخدم حاسبة الذاكرة VRAM لحساب مواصفات تهيئة محددة بدقة، واطَّلع على أفضل نماذج اللغة المحلية (LLMs) لـ Ollama لمقارنة أوسع نطاقًا.

نزِّل نسخة واحدة قبل تهيئة الوكيل (proxy):

ollama pull qwen3-coder:30b
ollama pull deepseek-coder-v2:16b

الخيار الأول: claude-code-router

أقصر طريق هو claude-code-router. ثبِّته على مستوى النظام كاملاً عبر الأمر التالي:

npm install -g @musistudio/claude-code-router

أنشئ الملف ~/.claude-code-router/config.json:

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "deepseek-coder-v2:16b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,deepseek-coder-v2:16b"
  }
}

ابدأ تشغيل Claude Code عبر الراوتر (router):

ccr code

يُفعِّل الراوتر نقطة نهاية محلية متوافقة مع Anthropic، ويضبط متغيرات البيئة تلقائيًّا لـ Claude Code، ويوجِّه حركة المرور إلى Ollama. وقد تغيَّرت أسماء حقول التهيئة الدقيقة بين الإصدارات الفرعية — لذا راجع ملف README الخاص بالمشروع إذا رُفِض أحد المفاتيح.

الخيار الثاني: وسيط LiteLLM

إذا كنت تشغل بالفعل LiteLLM لخدمات أخرى، فاستخدمه مجددًا. وأنشئ الملف config.yaml:

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: ollama_chat/qwen3-coder:30b
      api_base: http://localhost:11434
  - model_name: claude-haiku-4
    litellm_params:
      model: ollama_chat/deepseek-coder-v2:16b
      api_base: http://localhost:11434

شغِّله بالأمر التالي:

litellm --config config.yaml --port 4000

ثم وجِّه Claude Code إلى الوكيل (انظر القسم التالي). ويقوم LiteLLM بترجمة طلبات واجهة برمجة التطبيقات من تنسيق Anthropic إلى تنسيق Ollama تلقائيًّا على المسار /anthropic .

توجيه Claude Code إلى الوسيط

يقرأ برنامج Claude Code متغيرَيْ بيئة لتحويل حركة مرور واجهة برمجة التطبيقات الخاصة به. عيِّن هذين المتغيرين في واجهة سطر الأوامر (shell) قبل تشغيل البرنامج عبر الأمر التالي: claude.

macOS وLinux

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-anything"
claude

أضف هذه الأوامر إلى الملف ~/.zshrc أو ~/.bashrc لجعلها دائمة. أما قيمة المفتاح فهي غير مستخدمة من قِبل الوكيل المحلي، لكن برنامج Claude Code يرفض التشغيل دون تعيينها.

ويندوز (PowerShell)

$env:ANTHROPIC_BASE_URL="http://localhost:4000"
$env:ANTHROPIC_API_KEY="sk-anything"
claude

لجعلها دائمة عبر الجلسات، استخدم الأمر [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://localhost:4000", "User"). وإذا كان برنامج Claude Code مثبتًا عبر WSL، فقم بتكوين المتغيرات داخل واجهة سطر أوامر WSL بدلًا من ذلك — إذ يمكن الوصول إلى Ollama الذي يعمل على نظام Windows من WSL عبر العنوان http://host.docker.internal:11434 أو عبر عنوان IP الخاص بمضيف Windows.

نظام Windows (بدون WSL)

يستهدف برنامج Claude Code رسميًّا أنظمة macOS وLinux وWSL. أما دعم نظام Windows الأصلي فقد كان محفوفًا بالمشاكل تاريخيًّا؛ لذا يُفضَّل تشغيله ضمن بيئة WSL2 ما لم تكن قد تأكَّدت من أن الإصدار الحالي يعمل بسلاسة على إعدادك.

تكوين السياق ومدة الانتظار

يفترض برنامج Claude Code سياقًا بطول 200 ألف رمز (token)، وسرعة عالية للوصول إلى أول رمز. ولن تتمكن النماذج المحلية من تحقيق أيٍّ من هذين الشرطين. وهناك نقطتان رئيسيتان للضبط تؤثران في الأداء:

• طول سياق Ollama. عيِّنه صراحةً لكل نموذج باستخدام ملف Modelfile (مثلPARAMETER num_ctx 32768) أو عبر متغير البيئة OLLAMA_CONTEXT_LENGTH على خادم Ollama. أما الطول الافتراضي للسياق فهو صغير جدًّا وسيؤدي إلى اقتطاع المحادثات الطويلة بصمت.
• ذاكرة التخزين المؤقت KV المُستهلكة من VRAM. فاستخدام سياق بطول 32 ألف رمز على نموذج بحجم 30 مليار معلَّمة يستهلك عدة غيغابايتات فقط من ذاكرة التخزين المؤقت KV. ويمكنك التحقق من إجمالي استهلاك الذاكرة باستخدام الأمر ollama ps.

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

القيود المعروفة

• وظائف الأدوات (Tool use) هشَّة. تعتمد أدوات تعديل الملفات وتنفيذ أوامر bash والبحث في برنامج Claude Code على إخراج JSON دقيق جدًّا لاستدعاء الأدوات. وتُخفق النماذج المحلية في هذا الشرط غالبًا، مما يؤدي إلى إنشاء استدعاءات معطوبة أو تخيُّل محتويات الملفات. ويعتبر نموذجا qwen3-coder وdeepseek-coder-v2 من أكثر النماذج موثوقية في هذا الصدد، لكن لا أحدهما يعادل أداء Claude Sonnet.
• التخزين المؤقت للتعليمات البرمجية (Prompt caching) لا يؤثر إطلاقًا. شركة Anthropic cache_control يتم تجاهل الحقول ذات الصلة من قِبل الوكيل. وبالتالي تُرسَل التعليمات البرمجية النظامية الطويلة مجددًا في كل دورة.
• السرعة. حتى على وحدة معالجة رسوميات GPU بسعة 24 غيغابايت، فإن نموذجًا بحجم 30 مليار معلَّمة مع سياق بطول 32 ألف رمز يولِّد ما بين 15 و40 رمزًا في الثانية. وبما أن الحلقة الوكيلية (agentic loop) في برنامج Claude Code تقوم بعدة استدعاءات في كل مهمة، فقد تصل المدة الزمنية الفعلية (wall-clock time) إلى 5–10 أضعاف المدة التي تستغرقها واجهة برمجة التطبيقات السحابية.
• الوكلاء الفرعية (Sub-agents) وخوادم MCP. تظل الميزات المتقدمة في برنامج Claude Code (مثل الوكلاء الخلفية وخوادم MCP) تعمل عمومًا لأنها تمر عبر نفس الوكيل، لكن أي ميزة تعتمد على سلوك خادم خاص بشركة Anthropic قد تفشل بصمت.

متى تستخدم هذا الإعداد بدلًا من واجهة برمجة التطبيقات السحابية

إن استخدام برنامج Claude Code محليًّا منطقيٌّ عندما: لا يجوز أن يغادر الكود شبكتك، أو كنت تستخدم واجهة برمجة التطبيقات ضمن ميزانية محدودة وتنفذ عمليات إعادة هيكلة ضخمة، أو كنت تجري تجارب على الاستضافة الذاتية. أما استخدامه اليومي في البرمجة الوكيلية (agentic coding) حيث يكون الهدف الأساسي هو القدرة الاستنتاجية من فئة Claude Sonnet، فهو أقل منطقية.

ولاتخاذ قرار رقمي، احسب الأرقام من كلا الجانبين. فـ حاسبة تكلفة واجهة برمجة التطبيقات (API) يقدِّر النفقات الشهرية على واجهة برمجة تطبيقات Anthropic، بينما حاسبة نقطة التعادل بين الاستضافة المحلية وواجهة برمجة التطبيقات (API) يقارن هذه النفقات مقابل استهلاك تكلفة وحدة معالجة الرسوميات GPU على المدى الطويل. وفي معظم الحالات، يتفوَّق الخيار السحابي على المطور الفردي، أما بالنسبة للفرق التي تستخدم واجهة برمجة التطبيقات بكثافة، فقد تُحقِّق العائد على الاستثمار من صندوق محلي مشترك خلال سنة واحدة. وإذا كنت تخطط لمواصفات هذا الصندوق، فإن أفضل وحدات معالجة الرسوميات لتشغيل نماذج اللغة الكبيرة محليًّا يغطي الإرشادات الحالية لأحدث فئة.

بدائل Ollama لهذا التدفق العملي

إذا كانت أداء منصة Ollama يُشكل عامل تقييد، فإن برامج التشغيل الأخرى التي تدعم واجهات برمجة التطبيقات (APIs) المتوافقة مع OpenAI تعمل بنفس الطريقة تمامًا خلف نفس الوكيل (proxy): LM Studioومنها vLLM وخادم llama.cpp. انظر إلى LM Studio لخيار يركّز على واجهة المستخدم الرسومية (GUI)، أو إلى الدليل الكامل لـ Ollama لنظرة أعمق في منصة Ollama نفسها.

الأسئلة الشائعة

هل يمكن لـ Claude Code استخدام Ollama دون الحاجة إلى وكيل (proxy)؟

لا. فبرنامج Claude Code يتواصل باستخدام واجهة رسائل Anthropic البرمجية (Messages API)، ولا تُنفِّذ منصة Ollama هذه الواجهة. ولذلك فأنت بحاجة إلى طبقة ترجمة مثل claude-code-router أو LiteLLM. وسيؤدي تعيين ANTHROPIC_BASE_URL مباشرةً إلى http://localhost:11434 إلى فشل الطلب الأول فور إرساله.

أي نموذج محلي يقترب أكثر ما يمكن من أداء نموذج Claude Sonnet في مهام البرمجة؟

وبالنسبة للأحجام التي يستطيع معظم المستخدمين تشغيلها فعليًّا، فإن النموذجين qwen3-coder (30B MoE) وdeepseek-coder-v2 (16B lite) هما الخياران الأفضل حاليًّا. ولا يتفوق أيٌّ منهما على Sonnet في المهام المتعددة الملفات التي تتطلب وكالة (agentic tasks)، لكن كليهما قابلان للاستخدام في التعديلات داخل ملف واحد، واستكمال الشيفرة، ومراجعة الكود. قارن درجات الذكاء على لوحة تصنيف النماذج اللغوية الكبيرة (LLM).

هل يعمل التخزين المؤقت للموجهات (prompt caching) مع Ollama عند استخدامه خلف Claude Code؟

لا. فالتخزين المؤقت للموجهات الخاص بـ Anthropic هو ميزة خدمية تُطبَّق على جانب الخادم ضمن واجهة رسائلهم البرمجية (API). أما الوكلاء (proxies) فتقوم بإزالة حقول cache_control أو تتجاهلها، وبالتالي يعاد معالجة موجه النظام الكامل وتاريخ المحادثة بالكامل في كل طلب. وهذا أحد الأسباب التي تجعل الإعدادات المحلية تبدو أبطأ في كل دورة (turn) مقارنةً بالواجهة السحابية، حتى وإن كانت سرعة معالجة الرموز (token throughput) متماثلة تقريبًا.

كم كمية ذاكرة VRAM أحتاجها للحصول على تجربة جيدة؟

إن وحدة معالجة رسومية واحدة سعة 24 غيغابايت (مثل RTX 3090/4090/5090) تكفي لتشغيل نموذج برمجي حجمه 30 مليار معلمة (30B coder model) عند تكمية Q4 وبسياق يصل إلى نحو 32 ألف رمز (32K context). أما بالنسبة للنماذج من فئة 70 مليار معلمة أو السياقات الأطول، فيجب التخطيط لاستخدام 48 غيغابايت (مثل RTX 6000 Ada أو زوج من بطاقات RTX 3090) أو أكثر. استخدم حاسبة الذاكرة VRAM للحصول على أرقام دقيقة لكل نموذج ومستوى تكمية.

هل يمكنني دمج النماذج المحلية والنموذج السحابي في جلسة واحدة من Claude Code؟

نعم، وذلك عبر استخدام مُوجِّه (router). إذ يسمح لك برنامج claude-code-router بتعيين نماذج مختلفة لأدوار مختلفة — مثلاً: استخدام النموذج السحابي Sonnet للوكيل الرئيسي، ونموذج محلي لأداء المهام الخلفية أو استكمال الشيفرة. ويمكن أن يؤدي هذا إلى خفض تكاليف واجهة برمجة التطبيقات (API) بشكل كبير، مع الحفاظ على جودة عالية في المسار الحرج (critical path).

هل توجد طريقة رسمية مدعومة من شركة Anthropic لتشغيل Claude Code محليًّا؟

لا. فشركة Anthropic توزّع برنامج Claude Code كعميل (client) لواجهتها البرمجية السحابية فقط، ولا تُوزّع أوزان نموذج Claude أصلًا. وبالتالي فإن جميع الإعدادات المحلية تعتمد على وكلاء (proxies) مجتمعية تشير إلى نماذج تابعة لأطراف ثالثة. وإذا قامت Anthropic بتغيير واجهة رسائلها البرمجية (Messages API)، فقد تحتاج هذه الوكلاء إلى تحديثات قبل أن يعود برنامج Claude Code للعمل معها مرة أخرى.