ما تحتاجه
- مفتاح 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% لا يضع موعداً لانتهاء صلاحية رصيدك.
