شرح خطوة بخطوة لطريقة ربط Claude Code مع Gemini وتجاوز شاشة الدخول الأولى

كل مطور جرّب ربط Claude Code مع Gemini مرة واحدة على الأقل يعرف تماماً ما الذي ينتظره: شاشة OAuth تظهر ولا تختفي، أو رسالة خطأ تقول إن النموذج غير متوافق، أو ببساطة صمت تام من الطرفية. ليس المشكلة في الأداة ولا في النموذج، بل في الفجوة البروتوكولية بين عالمين لا يتحدثان نفس اللغة.

شرح خطوة بخطوة لطريقة ربط Claude Code مع Gemini وتجاوز شاشة الدخول الأولى.

هذا الدليل مكتوب لمطور يريد إجابات دقيقة لا نظريات. ستجد هنا الخطوات البرمجية الكاملة لبناء جسر عمل حقيقي بين بيئة Claude Code وواجهة Google AI Studio المجانية، مع حلول جراحية للمشاكل التي يتجاهلها معظم الأدلة الأخرى.

فهم التحدي التقني لدمج بيئة Claude Code مع نماذج Gemini

قبل أي سطر كود، ثمة حقيقة تقنية يجب استيعابها: Claude Code لا يتكلم مع Gemini مباشرة. هذه ليست ثغرة بل تصميم متعمد. الأداة مبنية بالكامل على توقع استجابات بتنسيق Anthropic Messages API، وكل ما يخرج من هذا التنسيق يُعتبر خطأً.

ولأن Gemini 2.5 Flash free يتحدث لغته الخاصة تماماً عبر نقطة نهاية مختلفة، فإن أي محاولة للتوصيل المباشر ستنتهي بفشل صامت أو رسالة خطأ غامضة. الحل ليس تعديل أي من الطرفين، بل إضافة مترجم وسيط بينهما.

الاختلاف الهيكلي بين بروتوكول طلبات Anthropic وواجهات Google API

Claude Code يرسل كل طلباته إلى مسار /v1/messages بحقول خاصة بـ Anthropic مثل system بشكله المنفصل وanthropic-beta وanthropic-version كترويسات إلزامية. Gemini من ناحيته يتوقع طلبات على مسار /v1beta/models/model:generateContent بهيكل JSON مختلف تماماً لا يعترف بحقول Anthropic.

النتيجة العملية واضحة كما وثّقها مطورون على Medium: Claude Code يرسل طلباً بصيغة Anthropic، Gemini يستقبل شيئاً لا يفهمه ويعيد خطأ، وClaude Code يفسّر ذلك الخطأ على أنه نموذج غير موجود. لا أحد مخطئ هنا، ببساطة هما لا يتحدثان نفس اللغة.

جدول المقارنة الشامل بين واجهة سطر أوامر Claude Code وأداة Gemini CLI

المعيار	Claude Code CLI	Gemini CLI
بروتوكول الطلبات	Anthropic Messages API	Google Gemini Native API
مسار النقطة الطرفية	/v1/messages	/v1beta/models/:model:generateContent
نظام المصادقة	ANTHROPIC_API_KEY / OAuth	GEMINI_API_KEY / Google Cloud ADC
التوافق المباشر	لا يدعم Gemini API مباشرة	لا يدعم Anthropic API مباشرة
الحل للتكامل	ANTHROPIC_BASE_URL يشير إلى LiteLLM	GOOGLE_GEMINI_BASE_URL يشير إلى LiteLLM
اكتشاف النماذج	CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1	GOOGLE_GEMINI_BASE_URL تلقائي
الطبقة المجانية	يتطلب رصيد Anthropic	Google AI Studio مجاناً

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

الدليل البرمجي لتهيئة وإعداد المترجم الوسيط LiteLLM

1. احصل على مفتاح API Google AI Studio المجاني من aistudio.google.com ضمن قسم API Keys
2. تأكد من وجود Python 3.9 أو أعلى مثبتاً على جهازك
3. ثبّت حزمة LiteLLM مع الإضافات الضرورية للعمل كخادم وكيل
4. أنشئ ملف تكوين YAML يُعرّف نماذج Gemini ويربطها بمفتاح API
5. شغّل الخادم الوسيط محلياً على المنفذ 4000
6. وجّه Claude Code إلى الخادم عبر متغيرات البيئة
7. اختبر الاتصال بإرسال طلب تجريبي والتحقق من الاستجابة

تثبيت حزم الاعتماديات وتجهيز بيئة Python

ابدأ بتثبيت LiteLLM مع خادم الوكيل. إذا كنت في بيئة مشاركة أو CI/CD، احرص على تجنب الإصدارات 1.82.7 و1.82.8 التي وثّقت Anthropic فيها ثغرة أمنية خطيرة.

BASH

# تثبيت LiteLLM مع خادم الوكيل (تجنب 1.82.7 و 1.82.8)
pip install "litellm[proxy]>=1.83.0"

# التحقق من الإصدار المثبت
litellm --version

# تثبيت أداة httpx للاختبار
pip install httpx

صياغة ملف التكوين المتقدم لربط نماذج جيميناي المتعددة

ملف config.yaml هو قلب الإعداد بأكمله. هنا تُعرّف النماذج وتربطها بمفاتيح API وتحدد قواعد التوجيه. يمكنك تضمين أكثر من نموذج في نفس الملف للتبديل الديناميكي لاحقاً.

config.yaml

model_list:
  # Gemini 2.5 Flash - النموذج الرئيسي المجاني
  - model_name: gemini-2.5-flash
    litellm_params:
      model: gemini/gemini-2.5-flash
      api_key: os.environ/GEMINI_API_KEY

  # Gemini 2.5 Pro - للمهام المعقدة
  - model_name: gemini-2.5-pro
    litellm_params:
      model: gemini/gemini-2.5-pro
      api_key: os.environ/GEMINI_API_KEY

  # Gemini 2.0 Flash - بديل خفيف وسريع
  - model_name: gemini-2.0-flash
    litellm_params:
      model: gemini/gemini-2.0-flash
      api_key: os.environ/GEMINI_API_KEY

litellm_settings:
  # تعطيل الترويسات التجريبية لتجنب أخطاء 400
  drop_params: true

general_settings:
  master_key: "sk-local-dev-key-change-this"

تفعيل وتشغيل بوابة العبور المحلية والتحقق من الاستجابة

الآن نُشغّل الخادم الوسيط ونتحقق من أنه يستقبل طلبات بتنسيق Anthropic ويترجمها بنجاح إلى Gemini. احتفظ بهذه النافذة مفتوحة طوال جلسة العمل.

BASH

# تصدير مفتاح Gemini API
export GEMINI_API_KEY="AIza..."

# تشغيل خادم LiteLLM
litellm --config config.yaml --port 4000

# في نافذة ثانية - اختبار سريع للتحقق من الاتصال
curl -X POST http://localhost:4000/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-local-dev-key-change-this" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "gemini-2.5-flash",
    "max_tokens": 50,
    "messages": [{"role": "user", "content": "قل مرحبا"}]
  }'

# يجب أن تحصل على استجابة JSON بتنسيق Anthropic

إذا ظهرت الاستجابة بتنسيق Anthropic الصحيح مع حقل content وusage، فالجسر يعمل. والآن ننتقل إلى الجزء الأكثر إرباكاً للمطورين: تجاوز شاشة الدخول الأولى.

الحل الجراحي لتجاوز شاشة الدخول الأولى وحلقة OAuth اللانهائية

لماذا تظهر شاشة OAuth حتى مع وجود متغيرات البيئة؟

Claude Code يتحقق من حالة الإعداد الأولي من ملف ~/.claude.json قبل أن يقرأ متغيرات البيئة. إذا كان الحقل hasCompletedOnboarding غائباً أو مضبوطاً على false، ستُعرض شاشة الترحيب والمصادقة بصرف النظر عن أي إعداد آخر. هذا السلوك موثق في الإصدار الحالي v2.x وما فوقه، وهو متعمد من Anthropic لضمان اكتمال إعداد المستخدم الجديد.

تعديل ملف التكوين المحلي لتخطي مرحلة الترحيب الأولى يدوياً

الحل الأبسط والأنظف هو تعديل ملف ~/.claude.json مباشرة. هذا ملف تكوين مستخدم عادي، وتعديله لا يؤثر على الكود الأساسي للأداة ولا على اتصالها الآمن بالخوادم.

~/.claude.json

{
  "hasCompletedOnboarding": true,
  "lastOnboardingVersion": "2.1.29",
  "projects": {
    "/home/user/my-project": {
      "hasTrustDialogAccepted": true
    }
  }
}

تجاوز قيود جدار الحماية وبيئات WSL2 عبر مفاتيح API المباشرة

في بيئات WSL2 أو الخوادم الحكومية أو الشبكات المؤسسية ذات القيود الصارمة، تفشل OAuth لأسباب متعددة تتعلق بإعادة التوجيه. المسار الأنظف هو استخدام ANTHROPIC_AUTH_TOKEN trick بالاعتماد الكامل على المفتاح المباشر.

• لا تضع ANTHROPIC_API_KEY وANTHROPIC_AUTH_TOKEN معاً في نفس البيئة، سيظهر تحذير تعارض المصادقة.
• في WSL2، تأكد أن عنوان ANTHROPIC_BASE_URL يستخدم http://localhost:4000 وليس عنوان IP الخارجي.
• إذا كان الخادم الوسيط يعمل على الـ Windows Host وليس داخل WSL2، استخدم $(cat /etc/resolv.conf | grep nameserver | awk '{print $2}') للحصول على عنوان IP الصحيح.
• لتعطيل الترويسات التجريبية التي تسبب أحياناً خطأ 400 في بيئات الوكيل، أضف CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 إلى متغيرات البيئة.
• في بيئات Docker، ضع الإعدادات في ملف .env منفصل وأضفه عبر --env-file بدلاً من تضمينه في الـ Dockerfile.

استخدام ميزة سكربت استرجاع المفاتيح الديناميكي لبيئات المؤسسات

للبيئات التي تتطلب تدوير المفاتيح تلقائياً أو تكاملاً مع نظام إدارة الأسرار، يوفر Claude Code ميزة apiKeyHelper الرسمية التي تستدعي سكربت shell لاسترجاع المفتاح بشكل ديناميكي عند الحاجة.

~/.claude/api-key-helper.sh + settings.json

# الخطوة 1: إنشاء سكربت استرجاع المفتاح
mkdir -p ~/.claude
cat > ~/.claude/api-key-helper.sh << 'EOF'
#!/bin/bash
# يمكن استبدال هذا باستدعاء vault أو AWS Secrets Manager
echo "sk-local-dev-key-change-this"
EOF
chmod +x ~/.claude/api-key-helper.sh

# الخطوة 2: تسجيل السكربت في إعدادات Claude Code
cat > ~/.claude/settings.json << 'EOF'
{
  "apiKeyHelper": "/home/YOUR_USERNAME/.claude/api-key-helper.sh"
}
EOF

# الخطوة 3: تصدير عنوان الخادم الوسيط
export ANTHROPIC_BASE_URL="http://localhost:4000"

# الخطوة 4: تشغيل Claude Code
# سيستدعي التطبيق السكربت تلقائياً ويتجاوز شاشة تسجيل الدخول
claude

مصفوفة الإعداد المتكامل لمتغيرات بيئة التشغيل لـ Claude Code

متغير البيئة	القيمة المثالية	الوظيفة	الأولوية
ANTHROPIC_BASE_URL	http://localhost:4000	يوجّه كل الطلبات نحو خادم LiteLLM	إلزامي
ANTHROPIC_AUTH_TOKEN	sk-local-dev-key	مفتاح التحقق مع الخادم الوسيط	إلزامي
GEMINI_API_KEY	AIza... (من Google AI Studio)	مفتاح Gemini الذي يستخدمه LiteLLM	إلزامي
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY	1	يُفعّل قراءة النماذج من /v1/models	مُوصى به
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	1	يمنع أخطاء 400 من الترويسات التجريبية	اختياري
ANTHROPIC_MODEL	gemini-2.5-flash	النموذج الافتراضي لكل الجلسات	اختياري
LITELLM_MASTER_KEY	قيمة آمنة وعشوائية	مفتاح إدارة خادم LiteLLM	إلزامي في الخادم

تفعيل الاكتشاف التلقائي للنماذج والتبديل الديناميكي داخل الجلسة

من أقوى ميزات هذا الإعداد القدرة على التبديل بين نماذج Gemini المختلفة داخل نفس الجلسة دون إعادة التشغيل. هذا يتطلب تفعيل الاكتشاف التلقائي أولاً.

BASH - الإعداد الكامل للجلسة

# --- إضافة هذا الكتلة إلى ~/.bashrc أو ~/.zshrc ---

# الخادم الوسيط
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-dev-key-change-this"

# مفتاح Gemini للخادم
export GEMINI_API_KEY="AIza..."

# تفعيل اكتشاف النماذج (يتطلب Claude Code v2.1.129+)
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

# تعطيل الترويسات التجريبية لتجنب أخطاء 400
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# --- داخل جلسة Claude Code ---
# التبديل إلى نموذج أثقل للمهام المعقدة
# /model gemini-2.5-pro

# التبديل إلى نموذج سريع للمهام البسيطة
# /model gemini-2.0-flash

معالجة تضارب أولويات المصادقة وتجنب تحذيرات التعارض المشترك

تحذير Mixed API and authentication credential usage يظهر عندما تجمع بين طريقتي مصادقة في نفس الوقت. الأولويات محددة بدقة في كود Claude Code:

• لا تضع ANTHROPIC_API_KEY في ملف .bashrc إذا كنت تستخدم ANTHROPIC_AUTH_TOKEN للوكيل المحلي، اختر أحدهما فقط
• ANTHROPIC_AUTH_TOKEN له أولوية أعلى من ANTHROPIC_API_KEY، لكن وجودهما معاً يُنتج التحذير
• apiKeyHelper في settings.json له الأولوية الأدنى بين الثلاثة، ولن يعمل إذا كان أي من المتغيرين الآخرين موجوداً
• لإزالة بيانات OAuth القديمة التي قد تتعارض مع إعداد الوكيل: cat ~/.claude.json | jq 'del(.oauthAccount)' > /tmp/c.json && mv /tmp/c.json ~/.claude.json
• في Windows عبر PowerShell، استخدم [Environment]::SetEnvironmentVariable بدلاً من export لضمان ثبات المتغيرات بين الجلسات

تقييم الأداء والميزات التشغيلية والعيوب لبيئة العمل المشتركة

✅ المزايا

• الوصول المجاني إلى نماذج Gemini 2.5 Flash free عبر Google AI Studio بدون تكلفة
• التبديل الديناميكي بين النماذج داخل نفس الجلسة عبر أمر /model
• تتبع التكلفة والاستخدام مركزياً عبر لوحة LiteLLM
• دعم Google Cloud Vertex AI credits لبيئات المؤسسات
• الاستمرار في العمل حتى لو انقطع مزود واحد عبر نظام الاحتياط
• تشغيل النماذج بالكامل داخل البنية التحتية المحلية لمن يهتم بالخصوصية

⚠️ القيود والعيوب

• بعض ميزات Claude Code المتقدمة مثل prompt caching تتطاير عند التوجيه عبر وكيل
• الخادم الوسيط يُضيف تأخيراً مقداره 20-60ms على كل طلب
• نماذج Gemini تختلف في أسلوب التفكير عن Claude، ما قد يؤثر على جودة الكود المُنتج
• إصداران من LiteLLM (1.82.7 و1.82.8) فيهما ثغرة أمنية موثقة يجب تجنبهما
• الطبقة المجانية من مفتاح API مجاني لها حدود معدل استخدام قد تُقيّد الجلسات المكثفة
• تحديثات Claude Code المتكررة قد تكسر التوافق مع بعض إعدادات الوكيل مؤقتاً

الأسئلة الشائعة حول تشغيل واستكشاف أخطاء الربط الفنية وإصلاحها

هل يمكن استخدام Claude Code مع Gemini بدون تثبيت LiteLLM؟

نظرياً نعم، عبر بناء خادم وكيل مخصص يُنفّذ نقطة نهاية /v1/messages بنفسك. لكن عملياً، LiteLLM هو الحل الأنضج والموثق رسمياً مع Claude Code. توجد بدائل مفتوحة المصدر مثل claude-code-proxy على GitHub تُسهّل الإعداد أكثر للمطورين الذين يريدون إعداداً أخف.

لماذا تظهر رسالة خطأ 400 مع ترويسة anthropic-beta؟

Claude Code يُضيف تلقائياً ترويسات تجريبية في كل طلب مثل prompt-caching-scope-2026-01-05. معظم خوادم الوكيل والنماذج الخارجية لا تدعم هذه الترويسات وترفضها بخطأ 400. الحل: ضع CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 في متغيرات البيئة لإيقاف هذا السلوك.

هل الطبقة المجانية من Google AI Studio كافية للاستخدام اليومي في البرمجة؟

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

ما الفرق بين ANTHROPIC_API_KEY و ANTHROPIC_AUTH_TOKEN؟

ANTHROPIC_API_KEY مخصص للاتصال المباشر بـ Anthropic API. ANTHROPIC_AUTH_TOKEN مخصص للمصادقة مع الخوادم الوسيطة مثل LiteLLM. عند استخدام وكيل محلي، استخدم ANTHROPIC_AUTH_TOKEN فقط، لأن وجود الاثنين معاً يُنتج تحذير تعارض.

كيف أتأكد أن Claude Code يتصل فعلاً بـ Gemini وليس بـ Anthropic؟

راقب سجلات LiteLLM في الطرفية. عند كل طلب من Claude Code ستجد سطراً يُظهر gemini/gemini-2.5-flash مع رمز الاستجابة. يمكنك أيضاً تشغيل Claude Code في وضع verbose بإضافة ANTHROPIC_LOG=debug لرؤية كل طلب خام يُرسله.

هل يعمل هذا الإعداد مع بيئة التطوير المتكاملة VS Code أو JetBrains؟

نعم. إضافات Claude Code لـ VS Code وJetBrains تقرأ نفس متغيرات البيئة ونفس ملف settings.json. الإعداد الموثق في هذا المقال يعمل مع جميع بيئات Claude Code بما فيها بيئة تطوير Gemini CLI.

ماذا أفعل إذا توقف الخادم الوسيط في منتصف الجلسة؟

Claude Code سيُظهر خطأ اتصال ولكن لن يفقد سياق المحادثة. فقط أعد تشغيل LiteLLM بنفس ملف config.yaml، ثم اضغط Enter في طرفية Claude Code لإعادة المحاولة. يُنصح بتشغيل LiteLLM داخل tmux أو كخدمة systemd لتجنب هذا السيناريو.

الخلاصة: ربط الأدوات لا يكتمل بدون طبقة حماية تُحصّن ما بنيته. من الناحية الأمنية، تجنب تماماً حفظ GEMINI_API_KEY داخل ملف .bashrc بنص واضح، بدلاً من ذلك استخدم مدير أسرار مثل متغيرات البيئة للذكاء الاصطناعي المشفرة عبر pass أو direnv أو HashiCorp Vault. الإصداران الخطيران من LiteLLM (1.82.7 و1.82.8) يجب تجنبهما تماماً حتى لو كانا مثبتين حالياً في بيئتك.

من ناحية التحكم بالميزانية، استخدم لوحة LiteLLM الإدارية لضبط حدود الإنفاق اليومي لكل مفتاح افتراضي. يمكنك إنشاء مفاتيح مختلفة لكل مشروع مع حدود منفصلة، ما يمنع مشروعاً واحداً من استهلاك كامل حصة Google Cloud Vertex AI credits المتاحة. للمشاريع الشخصية، ابقَ في الطبقة المجانية من Google AI Studio وراقب الاستخدام أسبوعياً من لوحة Google Cloud Console.

أخيراً، استخدم ملف .env بدلاً من تصدير المتغيرات مباشرة في الـ shell، وتأكد أن هذا الملف مُدرج في .gitignore قبل أي عملية push. هذا الإعداد الكامل يمنحك حرية أتمتة الكود عبر جيميناي بتكلفة صفرية فعلياً، مع الاحتفاظ بكامل السيطرة على البيئة وأمانها.