Claude Code أداة برمجة تعمل من سطر الأوامر، طورتها Anthropic، وتتصل افتراضيًا بواجهة Anthropic الرسمية. كثيرًا ما توجّه الفرق المحلية هذه الأداة إلى بوابة داخلية أو بوابة طرف ثالث، لمعالجة استقرار الوصول وتوحيد الفوترة وإدارة الحصص. جوهر ما يسمى «الربط بواجهة API مخصصة» هو تغيير ثلاثة أمور فقط: وجهة الطلب (Base URL)، وطريقة المصادقة (المفتاح)، والطراز المستدعى (اسم الطراز).
تسير هذه المقالة وفق ترتيب التثبيت، ومتغيرات البيئة، وملف الإعدادات، واختيار الطراز، والتحقق من الاتصال، والنشر داخل الفريق، والأمان، لتقديم مسار ربط قابل لإعادة الاستخدام. الأوامر موجّهة أساسًا إلى macOS وLinux، مع الإشارة إلى Windows بشكل منفصل.
ملاحظة: Claude وAnthropic علامتان تجاريتان مملوكتان لمالكيهما، وهذه المقالة مخصصة للشرح التقني للربط فقط، ولا تفيد بأي تبعية أو ارتباط بالمزودين المعنيين. تتحدث إصدارات Claude Code بوتيرة سريعة، وقد تتغير متغيرات البيئة وعناصر الإعداد وأسماء القوائم بين الإصدارات؛ لذا يُرجى الاعتماد على
claude --helpوالوثائق الرسمية وتعليمات الربط داخل الموقع.
أولًا: ثلاثة أمور يجب تأكيدها قبل الربط
يستخدم Claude Code بروتوكول Anthropic Messages، وليس بروتوكول Chat Completions الخاص بـ OpenAI. لذلك يجب أن توفر واجهة API المخصصة نقطتين على الأقل: مدخلًا متوافقًا مع Anthropic على المسار /v1/messages، وأسماء طرازات مطابقة لما تقدمه البوابة فعليًا. البوابة التي توفر مدخلًا متوافقًا مع OpenAI فقط لا يمكن إدخالها مباشرة في Claude Code، إلا إذا كانت توفر أيضًا مسارًا متوافقًا مع Anthropic.
جهّز ثلاثة عناصر قبل البدء:
- Base URL: العنوان الجذري للبوابة، مثل
https://ai.zhongshangqihang.com. يعتمد وجود/v1على تنفيذ البوابة، وتُراجع تعليمات الربط داخل الموقع. - مفتاح API: يُنشأ في لوحة التحكم، مع ضبط سقف الحصة ومدة الصلاحية، ولا يُستخدم مفتاح دائم بلا حد للاختبار.
- اسم الطراز: يُنسخ من لوحة التحكم أو صفحة الأسعار، ولا يُكتب يدويًا من الذاكرة؛ لأن خطأً في حالة الأحرف أو في أحد الواصلات قد يؤدي إلى خطأ «الطراز غير موجود».
إذا لم يكن لديك حساب بعد، فابدأ من صفحة التسجيل وأنشئ مفتاح اختبار بحصة منخفضة.
ثانيًا: تثبيت Claude Code
يُوزع Claude Code عادةً عبر npm، مع توفر طرق تثبيت أخرى. هذا هو المسار الأكثر شيوعًا:
- تأكد من تثبيت Node.js. يُنصح بإصدار LTS ما زال مدعومًا، وتُراجع الوثائق الرسمية للحد الأدنى للإصدار.
- نفّذ
npm install -g @anthropic-ai/claude-codeللتثبيت العام. - نفّذ
claude --versionللتأكد من توفر الأمر وسجّل رقم الإصدار. - انتقل إلى مجلد مشروع اختباري، وشغّل
claude، وأكمل الإعداد الأولي مثل السمة والثقة بالمجلد. - إذا كان للفريق سياسة لإدارة الإصدارات، فثبّت إصدارًا محددًا ووثّقه في دليل البدء، واختبر الترقية في مشروع تجريبي أولًا.
node --version
npm install -g @anthropic-ai/claude-code
claude --version
cd /path/to/your-project
claude
عند استخدام واجهة API مخصصة، لا يلزم عادةً تسجيل الدخول إلى حساب Anthropic، لكن تجاوز تسجيل الدخول يعتمد على الإصدار وطريقة الإعداد. إذا طُلب منك تسجيل الدخول بعد البدء، فتحقق أولًا من أن متغيرات البيئة سارية في الصدفة نفسها التي شغّلت منها Claude Code.
ثالثًا: متغيرات البيئة BASE_URL وAUTH_TOKEN
يقرأ Claude Code متغيري مصادقة شائعين:
ANTHROPIC_BASE_URL: العنوان الجذري للطلبات.ANTHROPIC_AUTH_TOKEN: يُرسل بصيغةAuthorization: Bearer، وهو الشائع في الربط عبر البوابات.ANTHROPIC_API_KEY: يُرسل بصيغةx-api-key، ويقترب من أسلوب المصادقة الأصلي في Anthropic.
يكفي ضبط أحد الخيارين. إذا كانت البوابة تصادق بنمط Bearer فاستخدم ANTHROPIC_AUTH_TOKEN؛ وإذا كانت تصادق بالنمط الأصلي فاستخدم ANTHROPIC_API_KEY. عند ضبط الاثنين معًا قد تختلف الأولوية بين الإصدارات، ما ينتج عنه خطأ 401 رغم صحة القيم؛ لذا يُفضل الإبقاء على واحد فقط.
export ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com"
export ANTHROPIC_AUTH_TOKEN="sk-مفتاحك"
claude
تؤدي إضافة الإعداد إلى ~/.zshrc أو ~/.bashrc إلى تفعيله باستمرار، ويُنفذ source ~/.zshrc بعد التعديل. في Windows PowerShell استخدم $env:ANTHROPIC_BASE_URL="..."، وهو ساري في النافذة الحالية فقط؛ وللحفظ الدائم استخدم واجهة متغيرات بيئة النظام أو setx، ثم أعد فتح الطرفية.
لا تكتب أوامر export في سكربت المشروع ثم ترفعها إلى المستودع. بعد دخول المفتاح إلى تاريخ Git، فإن حذف الملف لا يعني حذف السجل.
رابعًا: settings.json لتثبيت الإعداد في ملف
تصلح متغيرات البيئة للتبديل المؤقت، أما الاستخدام الطويل الأمد فيُفضل تثبيته في ملف settings الخاص بـ Claude Code. توجد عادةً ثلاثة مستويات:
- مستوى المستخدم:
~/.claude/settings.json، ويؤثر في جميع مشاريع الجهاز. - مستوى المشروع:
.claude/settings.json، ويمكن رفعه إلى المستودع، ويناسب الإعدادات غير الحساسة المشتركة بين الفريق. - مستوى المشروع المحلي:
.claude/settings.local.json، ولا يُرفع، ويناسب التجاوزات الشخصية.
مثال:
{
"env": {
"ANTHROPIC_BASE_URL": "https://ai.zhongshangqihang.com",
"ANTHROPIC_AUTH_TOKEN": "sk-مفتاحك"
},
"model": "claude-sonnet-4-5"
}
تنبيه: المفتاح داخل settings.json يكون نصًا صريحًا. قد يكون ذلك مقبولًا على جهاز شخصي، لكنه غير مناسب على أجهزة مشتركة أو في CI أو مستودعات الكود. ضع في ملف مستوى المشروع Base URL واسم الطراز فقط، واترك المفتاح لمتغيرات البيئة أو أداة إدارة الأسرار. تسير أولوية الإعداد عمومًا من إعداد المؤسسة إلى معاملات سطر الأوامر إلى المشروع المحلي إلى المشروع إلى المستخدم، وتراجع الوثائق الخاصة بالإصدار الحالي للتفاصيل الدقيقة.
خامسًا: اختيار الطراز حسب المهمة
تُقسم طرازات Claude عادةً إلى ثلاث فئات، وتناسب كلًا منها مهام مختلفة:
| الفئة | الاستخدامات النموذجية | المفاضلة |
|---|---|---|
| Opus | إعادة الهيكلة المعقدة، والتحليل عبر الملفات، ووكلاء المسارات الطويلة | قدرة أعلى، وتكلفة أعلى عادةً، وسرعة قد تكون أقل |
| Sonnet | البرمجة اليومية، وإصلاح الأخطاء، ومراجعة الكود | توازن بين القدرة والتكلفة، ويصلح كخيار افتراضي |
| Haiku | الإكمال البسيط، والتنسيق، والمهام الدفعية الصغيرة | سرعة عالية وتكلفة منخفضة، لكنه يتراجع في المهام المعقدة |
داخل Claude Code يمكن تحديد الطراز الرئيسي عبر ANTHROPIC_MODEL، كما يمكن تجاوز تعيين كل فئة عبر ANTHROPIC_DEFAULT_SONNET_MODEL وANTHROPIC_DEFAULT_OPUS_MODEL وANTHROPIC_DEFAULT_HAIKU_MODEL. قد تختلف المتغيرات المدعومة بين الإصدارات، فراجع claude --help أو الوثائق الرسمية قبل الضبط.
يجب أن يتطابق اسم الطراز مع دليل الطرازات في البوابة. قد تستخدم البوابة تسميات خاصة للطرازات المصدر، ولا يضمن الاسم المذكور في الوثائق الرسمية العثور على الطراز. توجد الطرازات المتاحة وطريقة الفوترة في صفحة الأسعار، وهي قابلة للتعديل مع تحديثات الطرازات وسياسات المزود الأعلى.
سادسًا: التحقق من الاتصال عبر curl قبل Claude Code
اختبر البوابة أولًا بمعزل عن Claude Code باستخدام curl:
curl "$ANTHROPIC_BASE_URL/v1/messages" \
-H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-5",
"max_tokens": 64,
"messages": [{"role": "user", "content": "أجب بكلمة OK فقط"}]
}'
إذا كانت البوابة تصادق بنمط Bearer، فاستبدل x-api-key بـ Authorization: Bearer $ANTHROPIC_AUTH_TOKEN. عندما يعود الطلب بالرمز 200 والمحتوى سليم، فهذا يعني أن مجموعة واحدة على الأقل من Base URL والمفتاح والطراز تعمل.
عد بعد ذلك إلى Claude Code واتبع الترتيب:
- نفّذ
claude --versionللتأكد من قابلية تنفيذ العميل. - شغّل
claude doctorداخل مجلد المشروع، إن كان الإصدار الحالي يوفر هذا الأمر، لفحص التثبيت والإعداد. - شغّل
claudeواستخدم/statusلمراجعة الطراز الحالي ومعلومات الحساب. - أدخل مهمة منخفضة المخاطر، مثل «اشرح بنية هذا المجلد دون تعديل الملفات».
- راقب الاستجابة، وتحقق من ظهور أخطاء 401 أو 404 أو «الطراز غير موجود».
جدول المقارنة بين الأعراض الشائعة:
| العَرَض | يُفحص أولًا | المعالجة |
|---|---|---|
| 401 | المفتاح، واسم المتغير، وترويسة الطلب | أعد نسخ المفتاح؛ واحتفظ بمتغير مصادقة واحد فقط |
| 404 | زيادة أو نقصان /v1 في Base URL |
عدّل إلى العنوان الجذري أو المدخل المتوافق وفق وثائق البوابة |
| model not found | عدم تطابق اسم الطراز مع دليل البوابة | انسخه من لوحة التحكم أو صفحة الأسعار |
| انتهاء مهلة الطلب | الشبكة، وDNS، والوكيل | جرّب شبكة أخرى؛ وتأكد من أن الوكيل لا يعيد كتابة الترويسات |
| 429 | حدود التزامن أو الحصة | خفّض التزامن؛ وافحص حد المفتاح |
سابعًا: النشر داخل الفريق: مفتاح لكل شخص ومدخل موحد
لا يُنصح بمشاركة مفتاح واحد بين أعضاء الفريق. الممارسة الأكثر أمانًا هي:
- مفتاح لكل شخص، يتضمن اسمه أو الغرض منه، ويُعطّل فور مغادرته.
- حصص لكل مشروع أو بيئة، مع فصل الإنتاج عن الاختبار.
- بوابة موحدة لمراجعة الاستخدام وتوزيع الطرازات والاستدعاءات غير الطبيعية مركزيًا.
- إعداد مؤسسي يوزع Base URL والطرازات المسموح بها، لتقليل أخطاء الإعداد اليدوي.
- توثيق خطوات الربط في دليل بدء يتضمن أوامر التحقق والأخطاء الشائعة.
- مراجعة الاستخدام أسبوعيًا أو شهريًا ومعالجة المفاتيح غير الطبيعية فورًا.
إذا كانت الشركة تتبع إجراءات شراء وامتثال، فتحقق أولًا من مسار البيانات: تُرسل مقاطع الكود إلى البوابة وإلى خدمة الطراز الأعلى. وتحدد شروط الخدمة ما إذا كانت تُحفظ، ومدة الحفظ، وما إذا كانت تُستخدم في التدريب؛ فلا تفترض شيئًا من تلقاء نفسك.
ثامنًا: حدود الأمان للمفاتيح والكود والبيانات
في الختام، بعض الحدود التي لا يجوز تجاوزها:
- لا يدخل المفتاح إلى Git أو الصور أو كود الواجهة الأمامية أو لقطات الشاشة أو سجلات المحادثة.
- أضف
.gitignoreإلى المشروع، على أن يغطي على الأقل.envو.env.*و.claude/settings.local.json. - عند الاشتباه بتسريب، ألغِ المفتاح القديم أولًا ثم افحص الاستخدام، ولا تكتف بتغيير كلمة المرور.
- ضع تاريخ انتهاء للمفتاح، واستبدله عند تغيّر الموظفين.
- على الأجهزة المشتركة استخدم أداة إدارة أسرار أو
apiKeyHelper، ولا تكتب النص الصريح في settings.json. - ثبّت Claude Code من مصادر موثوقة فقط، واقرأ ملاحظات التغيير قبل الترقية.
الأسئلة الشائعة
هل يلزم تسجيل الدخول إلى حساب Anthropic لاستخدام Claude Code؟
ليس بالضرورة. بعد ضبط Base URL ومتغير مصادقة صالحين، يمكن للعميل الاتصال بواجهة API المخصصة مباشرة؛ لكن إرشادات البدء الأول مثل السمة والثقة بالمجلد قد تظهر. يعتمد تجاوز تسجيل الدخول على الإصدار وطريقة الإعداد؛ وعند مواجهة مشكلة، تحقق أولًا من سريان متغيرات البيئة في صدفة التشغيل.
ما الفرق بين ANTHROPIC_API_KEY وANTHROPIC_AUTH_TOKEN؟
يُرسل الأول عادةً في ترويسة x-api-key، بينما يُرسل الثاني في Authorization: Bearer. يعتمد الاختيار على طريقة مصادقة البوابة، ويُنصح بضبط واحد فقط لتجنب تعارض الترويسات.
هل يُكتب Base URL كعنوان جذري أم مع /v1؟
يكتب Claude Code عادةً العنوان الجذري، ويتولى العميل تركيب /v1/messages؛ لكن بعض البوابات تطلب إدخال المدخل المتوافق مباشرة. طريقة التحديد بسيطة: اختبر العنوان الجذري مع /v1/messages عبر curl؛ فإن نجح فاستخدم الجذري، وإلا فعدّل وفق وثائق البوابة.
لماذا يعمل curl بينما يفشل Claude Code؟
من الأسباب الشائعة عدم انتقال متغيرات الصدفة إلى الواجهة الرسومية أو الطرفية المدمجة في بيئة التطوير، أو ضبط متغيري مصادقة معًا وتعارضهما. نفّذ echo $ANTHROPIC_BASE_URL في الطرفية نفسها التي تشغّل منها Claude Code للتأكد.
هل يمكن للفريق مشاركة مفتاح واحد؟
تقنيًا نعم، لكنه غير مستحسن. لا يتيح المفتاح المشترك تمييز استهلاك الأعضاء، ويصعب معه تحديد المسؤول عند التسريب. مفتاح لكل شخص مع حصص وتواريخ انتهاء يخفض كلفة الإدارة.
الخطوة التالية
إذا لم يكن لديك حساب بوابة جاهز، فابدأ من صفحة التسجيل وأنشئ مفتاح اختبار بحصة منخفضة، ثم تحقق على مرحلتين: curl أولًا، ثم Claude Code. تجد الطرازات والفوترة في صفحة الأسعار، والأسعار قابلة للتعديل وتُراجع وفق المعلومات اللحظية في الصفحة.
قراءات ذات صلة:
