AR ▾

الرئيسيةالدليل

إعداد وسيط Claude Code باستخدام واجهة API متوافقة مع OpenAI

يتخذ إعداد وسيط Claude Code هذا خمس خطوات: الحصول على مفتاح، كتابة تكوين LiteLLM، بدء الوسيط، ضبط متغيرين للبيئة وتشغيل اختبار. يستغرق حوالي عشر دقائق.

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

نقاط رئيسية

  1. تشغيل وسيط LiteLLM المحلي الذي يعيد التوجيه إلى https://api.claudecodeproxyapi.com/v1
  2. توجيه Claude Code إلى الوسيط باستخدام ANTHROPIC_BASE_URL وANTHROPIC_AUTH_TOKEN
  3. ربط اسم النموذج الذي يرسله Claude Code إلى النموذج الخلفي uncensored
  4. اختبار الوسيط باستخدام curl قبل بدء CLI

ما تحتاجه

  • مفتاح API من صفحة المفاتيح. أنشئ حساباً باستخدام Google أو البريد الإلكتروني وكلمة المرور، ثم احصل على رصيد التجربة بقيمة $0.50 بنقرة واحدة.
  • Python 3.9 أو أحدث، لتثبيت الوكيل الوسيط.
  • Claude Code مثبت ويعمل على جهازك.

لماذا نحتاج إلى وكيل وسيط أساساً؟ يتكلم Claude Code بتنسيق Anthropic Messages، بينما تتكلم API الخاصة بنا بتنسيق OpenAI Chat Completions مع معرف النموذج uncensored. يقوم الوكيل الوسيط بالترجمة بينهما. إذا كنت تريد الخلفية أولاً، اقرأ دليل استكشاف أخطاء الوكيل الوسيط. النموذج هو نموذج مفتوح الأوزان، وليس Claude، لذا توقع سلوكاً مختلفاً في المهام متعددة الخطوات الصعبة.

الخطوة 1: تثبيت الوكيل الوسيط

استخدم بيئة افتراضية بحيث تبقى تبعيات الوكيل منفصلة عن مشاريعك:

python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

LiteLLM هو برنامج مفتوح المصدر من طرف ثالث. تتطابق الأوامر ومفاتيح التكوين أدناه مع وثائقه العامة وقت الكتابة، ولكن تحقق من وثائقه الحالية إذا تغير أحد الأعلام.

الخطوة 2: كتابة التكوين

أنشئ config.yaml. الـ model_name هو الاسم الذي يرسله العميل. كتلة الـ litellm_params تحدد الوجهة التي سيتم توجيه الطلب إليها. بادئة الـ openai/ تخبر LiteLLM بالتحدث مع خادم متوافق مع OpenAI.

cat > config.yaml <<'EOF'
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: openai/uncensored
      api_base: https://api.claudecodeproxyapi.com/v1
      api_key: os.environ/UPSTREAM_KEY
EOF

الاسم المستعار claude-sonnet هو مثال، وليس مطلباً. قد يرسل Claude Code أسماء نماذج مختلفة متعددة، على سبيل المثال نموذج رئيسي وآخر أصغر للمهام الخلفية. أضف إدخالاً واحداً من model_list لكل اسم تراه في سجل الوكيل الوسيط، مع توجيه الجميع إلى نفس المصدر البعيد. توجيه كل الأسماء المستعارة إلى uncensored أمر جيد، لأنه يوجد نموذج واحد فقط.

يُقرأ المفتاح من متغير بيئة لذا لا يسقط أبداً في ملف قد تدرجه.

الخطوة 3: تشغيل الوكيل الوسيط

export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000

اترك هذه الطرفية مفتوحة. يجب أن ترى الخادم يستمع على المنفذ 4000. الآن تحقق من مسار المصدر البعيد من جانب الوكيل الوسيط بطلب اختبار بتنسيق Anthropic، وهو ما سيرسله Claude Code:

curl http://localhost:4000/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-local-anything" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

تعني الاستجابة JSON التي تتضمن كلمة "ready" أن الترجمة تعمل من البداية للنهاية: صيغة Anthropic في، صيغة OpenAI إلى https://api.claudecodeproxyapi.com/v1، ثم العودة. إذا قمت بتعيين مفتاح رئيسي في تكوين LiteLLM، فاستخدمه بدلاً من sk-local-anything.

الخطوة 4: توجيه Claude Code إلى الوكيل الوسيط

يقرأ Claude Code عنوان API والرمز من متغيرات البيئة. اضبطها في المحطة التي تبدأ منها واجهة سطر الأوامر:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude

استخدم عنوان الوكيل بدون لاحقة /v1 هنا، لأن واجهة سطر الأوامر تضيف مسارها الخاص. يجب أن يفي الرمز بمتطلبات الوكيل فقط، لأن المفتاح الحقيقي للمصدر هو الذي قمت بتصديره كـ UPSTREAM_KEY. إذا استخدمت ملف إعدادات واجهة سطر الأوامر للقيم البيئية بدلاً من المحطة، ضع الأسماء الثلاثة نفسها هناك. يمكن أن تتغير أسماء متغيرات البيئة لـ Claude Code بين الإصدارات، لذا تحقق منها مقابل وثائق Claude Code الحالية إذا تم تجاهل شيء.

الخطوة 5: تشغيل مهمة أولى ومراقبة السجل

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

استدعاء الأدوات مهم هنا، لأن واجهة سطر الأوامر (CLI) تقرأ الملفات وتحرر الكود من خلال الأدوات. تدعم API tools، tool_choice وtool_calls المتدفق، ويقوم الوكيل الوسيط بتحويلها. يظهر الالتزام الأضعف بمخطط أداة كخطأ في التحرير أو خطوة متكررة. عندما يحدث ذلك، قم بتقليل حجم المهمة وحاول مرة أخرى قبل أن تقرر أن الإعداد معطل.

نافذة السياق هي 100,000 رمز (token)، للموجّه والإكمال معاً. ستفشل الجلسات الطويلة التي تتجاوزها، لذا ابدأ جلسة جديدة لمهمة جديدة. التكاليف ضئيلة جداً عند $0.15 لكل مليون رمز (token) مدخل و $0.50 لكل مليون رمز (token) مخرج: طلب يحتوي على 20,000 رمز (token) مدخل و 800 مخرج يكلف $0.003 + $0.0004 = $0.0034. انظر صفحة التسعير للشحن، والتي في هذا الموقع تكون مدفوعة بالعملات المشفرة فقط (USDT على TRC20، USDC على Base).

استكشاف الأخطاء وإصلاحها

ما تراهالسببالحل
رفض الاتصالالوكيل الوسيط لا يعمل أو يختلف المنفذشغّله وطابق المنفذ في ANTHROPIC_BASE_URL
وكيل وسيط 404 أو "نموذج غير موجود"اسم النموذج الذي أرسلته واجهة سطر الأوامر (CLI) غير موجود في ملف التكوينأضف هذا الاسم إلى model_list
المصدر البعيد 401مفتاح UPSTREAM_KEY خاطئ أو فارغأعد تصدير المفتاح في قشرة الوكيل الوسيط ثم أعد التشغيل
429 مع concurrencyأكثر من 8 طلبات متزامنة (2 في التجربة)قلل عدد الوكلاء المتزامنين
429 مع rate_limitedأكثر من 300 طلب في الدقيقة (60 في التجربة)تراجع وأعد المحاولة
429 مع Retry-After: 5حمل زائد مؤقتأعد المحاولة بعد خمس ثوانٍ
تعليق البث المتدفقيحتفظ الطلب الذي يستخدم البث المتدفق بمكانه حتى ينتهيألغِه في واجهة سطر الأوامر (CLI) لتحرير المكان

لأي مشكلة غير مغطاة هنا، أدرج رأس الاستجابة X-Request-Id عند مراسلة الدعم. الوثائق تسرد كل معلمة مدعومة.

اجعله دائماً

تصبح كتابة أوامر export في كل مرة مملة. ضع بدء تشغيل البروكسي في نص برمجي صغير، ومتغيرات العميل في اسم مستعار (alias)، بحيث يكفي أمر واحد لتشغيل كل شيء:

cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh

alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'

نظراً لأن المتغيرات تُضبط فقط لذلك الأمر الواحد، فإن أمر claude العادي الخاص بك يستمر في العمل بإعداداته الافتراضية. أضف الاسم المستعار إلى ملف تعريف قشرة الطرفية الخاصة بك. احمِ السكربت باستخدام أذونات الملف مثل chmod 700، لأنه يحتوي على مفتاحك.

العودة إلى الوضع السابق

إذا كنت قد صدّرت المتغيرات في قشرة النظام الحالية، شغّل unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL وأعد تشغيل واجهة سطر الأوامر (CLI). لم يتغير شيء في جانب واجهة برمجة التطبيقات (API)، لذا لا يوجد شيء يجب التراجع عنه.

مراقبة رصيدك وإنفاقك

يحمل كل استجابة من API X-Balance-USD، الرصيد المتبقي في مفتاحك. يمكن لـ LiteLLM تمرير رؤوس المصدر البعيد في بعض الإعدادات، لكن الطريقة الأكثر أماناً لرؤية رصيدك هي الاتصال بالمصدر البعيد مباشرة من وقت لآخر:

curl -i https://api.claudecodeproxyapi.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd

جلسات الوكلاء تنمو بصمت. كل خطوة تعيد إرسال سياق العمل، لذا فإن الجلسة الطويلة تكلف أكثر لكل طلب من الجلسة القصيرة. بدء جلسة جديدة لكل مهمة يبقي المدخل صغيراً والفاتورة منخفضة. عند الأسعار المنشورة ($0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج)، يكلف الطلب الذي يحتوي على 50,000 رمز مدخل و1,000 رمز مخرج 50,000 × $0.15 / 1M = $0.0075 بالإضافة إلى $0.0005، أي ما مجموعه $0.008. عشرون طلباً من هذا النوع تصل إلى $0.16.

شحنات الرصيد تتراوح بين $20 و$500 بمبالغ صحيحة، وتُدفع بالعملات المشفرة فقط (USDT على TRC20 أو USDC على Base) في هذا الموقع. الرصيد لا ينتهي، لذا فإن الشحن الأكبر مع مكافأة +5% أو +10% أو +15% لا يضع موعداً لانتهاء صلاحية رصيدك.

أسئلة وأجوبة

ما هي متغيرات البيئة التي يحتاجها Claude Code للوكيل الوسيط؟

ANTHROPIC_BASE_URL لعنوان الوكيل وANTHROPIC_AUTH_TOKEN لرمز (token) يقبله الوكيل. يمكن أن يشير ANTHROPIC_MODEL إلى الاسم المستعار الذي قمت بتعريفه. تحقق من وثائق Claude Code الحالية لمعرفة التغييرات.

هل أضع /v1 على ANTHROPIC_BASE_URL؟

لا. استخدم عنوان الوكيل الوسيط مثل http://localhost:4000, لأن واجهة سطر الأوامر (CLI) تضيف مسارها الخاص. ينتمي /v1 فقط إلى api_base للمصدر البعيد في تكوين الوكيل الوسيط.

هل يمكنني استخدام وسيط آخر غير LiteLLM؟

نعم. يعمل أي وسيط يحول طلبات Anthropic Messages إلى OpenAI Chat Completions، مثل claude-code-router. وجّه upstream الخاص به إلى https://api.claudecodeproxyapi.com/v1 باستخدام النموذج uncensored.

هل مفتاح المصدر البعيد آمن في ملف الإعدادات؟

احتفظ به في متغير بيئة بدلاً من الملف، كما هو موضح في التكوين أعلاه. لا تقم بإدراج المفتاح في مستودع.

مفتاحك على بُعد استمارة واحدة

أنشئ حساباً، وانسخ المفتاح، ثم غيّر URL الأساسي. هذه هي الإعدادات الكاملة.