ملاحظة من الكاتب: هذا دليل تطبيقي يمكنك اتباعه خطوة بخطوة حتى إتمامه. بعد قراءته وتنفيذ الخطوات، ستحصل على إعداد يتيح لك إدارة أي عدد من وكلاء البرمجة باستخدام «مفتاح واحد، وعنوان بوابة واحد»؛ وكلما أردت تغيير النموذج أو تدوير مفتاح API، لن تحتاج إلا إلى تعديل مكان واحد.
قبل البدء، تعرّف إلى ما ستفعله
- الهدف: استخدام مفتاح API واحد وعنوان واحد للخدمة العليا مع جميع وكلاء البرمجة على جهازك. سنستخدم في هذا الدليل Claude Code وCodex وPi وHermes أمثلةً؛ وصِل منها ما ثبّتّه.
- المدة: نحو 30 دقيقة، دون احتساب وقت التسجيل وتنزيل الملفات.
- المتطلبات المسبقة: رمز APIYI (أو أي مفتاح رسمي أو مفتاح لخدمة وكيل متوافقة مع OpenAI أو Anthropic)، وجهاز يمكنه تشغيل سطر الأوامر، ووكيل واحد على الأقل مثبّت.
- الصعوبة: ★★☆☆☆. يكفي أن تعرف النقر بالماوس والنسخ واللصق؛ لن تحتاج إلى كتابة أي أوامر طوال العملية.
خريطة الدليل
| الخطوة | ما ستفعله | معيار التحقق بعد الانتهاء |
|---|---|---|
| الخطوة 1 | الحصول على رمز من APIYI | نسخت الرمز وتعرف أي العنوانين ينبغي إدخاله |
| الخطوة 2 | تثبيت magpie والتعرّف إلى صفحتيه | يمكن فتح نافذتي «Agent» و«المورّدون» |
| الخطوة 3 | إضافة مفتاح API في صفحة «المورّدون» | يظهر المورّد في القائمة مع عدد النماذج |
| الخطوة 4 | تفعيل الاتصال لكل وكيل على حدة واختيار النموذج في صفحة «Agent» | يتحول المفتاح إلى الأخضر وتظهر حالة «متصل» |
| الخطوة 5 | تجربة جملة واحدة في كل وكيل للتحقق | يستجيب كل وكيل على نحو سليم |
| الخطوة 6 (اختيارية) | مقارنة الإعدادات الأصلية دون تثبيت magpie | تعرف أي ملف عدّله magpie تحديدًا |

افهم في ثلاث دقائق: ما الذي يفعله magpie بالضبط؟
إذا كان كل ما تريده هو «تنفيذ الخطوات كما هي»، فيمكنك تخطي هذا القسم. لكن تخصيص ثلاث دقائق لقراءته سيوفر عليك وقتًا كثيرًا عند استكشاف الأخطاء لاحقًا.
تختلف متطلبات الأدوات من الـ Agent للنموذج الذي تتصل به اختلافًا كبيرًا. وإذا أعددت كل أداة يدويًا، فستحتاج إلى صيانة مجموعة إعدادات مستقلة لكل أداة تثبّتها. إليك أربعة من أكثرها شيوعًا:
| أداة Agent | البروتوكول الأساسي | موضع الإعداد الشائع | صعوبة الإعداد اليدوي |
|---|---|---|---|
| Claude Code | Anthropic Messages | متغيرات البيئة أو ~/.claude/settings.json |
يجب أن تكون نقطة النهاية بتنسيق Anthropic |
| Codex | OpenAI Responses / Chat | ~/.codex/config.toml |
يتطلب إضافة قسم مخصص لمزوّد الخدمة |
| Pi (Agent للبرمجة) | يدعم عدة مزوّدين | ملف إعدادات النماذج في Pi | يجب تعريف مزوّد مخصص وقائمة نماذج بشكل منفصل |
| Hermes Agent | متوافق مع OpenAI وغيرها | مجلد إعدادات Hermes وملف .env |
يتطلب اختيار نقطة نهاية مخصصة وإدخال المفتاح |
يحل magpie (المستودع github.com/yetone/magpie، وشعاره “Every agent’s model. One place.”) هذه المشكلة: فهو يجمع إدارة «أي Agent يستخدم أي نموذج، وأي مفتاح يقرأ» في مكان واحد، ثم يعدّل ملفات الإعداد الأصلية لكل أداة.
باختصار، تتوزع المهام كالتالي:
- magpie يتولى التوزيع: يحدد النموذج الذي يستخدمه Claude Code والنموذج الذي يستخدمه Codex
- البوابة تتولى البروتوكولات: تحوّل الطلبات بتنسيقات Anthropic وOpenAI وGemini وتوجّهها إلى مزوّد النموذج الفعلي

لذلك، يُفضّل أن تدعم بوابة الاتصال بالبائع عدة بروتوكولات
التقسيم المثالي للمهام هو «magpie يتولى التوزيع، والبوابة تتولى البروتوكولات». فإذا كانت البوابة لا تدعم سوى التنسيق المتوافق مع OpenAI، فسيتعين إضافة طبقة أخرى لتحويل البروتوكول عند استخدام Claude Code. وهذا يطيل مسار الطلبات، ويزيد احتمال عدم اتساق تنسيقات استدعاء الأدوات.
تتيح APIYI استخدام رمز واحد مع ثلاثة بروتوكولات رئيسية: التوافق مع OpenAI، والتنسيق الأصلي لـ Anthropic، وتنسيق Gemini، وكلها تعمل بالمفتاح نفسه (راجع لوحة التحكم لمعرفة نطاق الدعم بالتحديد). وهكذا لا يحتاج magpie إلا إلى ربط وجهة واحدة، فتتمكن جميع أدوات Agent من الاتصال مباشرة، من دون إدارة حسابات وفواتير منفصلة لدى المزوّدين.
كيف تختار بين الطرق الثلاث؟

| الطريقة | مواضع التعديل | مواءمة البروتوكولات | تكلفة تدوير المفاتيح | الأنسب لـ |
|---|---|---|---|---|
| الإعداد اليدوي لكل أداة | 4 ملفات إعدادات + حسابات متعددة لدى المزوّدين | تتولاها بنفسك | مرتفعة، إذ يلزم التعديل في 4 مواضع أو أكثر | من يستخدم أداة أو أداتين فقط |
| نص برمجي لمتغيرات البيئة | نص برمجي واحد | يعتمد على دعم البوابة لعدة بروتوكولات | منخفضة، تعديل موضع واحد | المطورين الذين يفضلون الحلول البسيطة |
| magpie مع بوابة متعددة البروتوكولات | إدارة مركزية في موضع واحد | تتولاها البوابة | منخفضة، مع إمكانية تخصيص نموذج لكل Agent | من يستخدم ثلاث أدوات Agent أو أكثر في الوقت نفسه |
الإعداد اليدوي هو الأسهل للبدء، لكن مع زيادة عدد الأدوات تتوزع المفاتيح بين ملفات كثيرة، فترتفع كلفة تدويرها واستكشاف الأخطاء بوضوح. أما نص متغيرات البيئة، فلا يعتمد على إضافات ويكفيه بضع عشرات من الأسطر، لكنه لا يتيح تخصيص نموذج مختلف لكل Agent. ولتلبية احتياج مثل «Claude Code يستخدم Claude، وCodex يستخدم GPT، وHermes يستخدم نموذجًا أقل تكلفة»، فإن الحلول المركزية مثل magpie هي الخيار الأسهل.
الخطوة 1: احصل على مفتاح API وانسخه
1.1 أنشئ رمزًا مميزًا في لوحة تحكم APIYI
انتقل إلى لوحة تحكم APIYI (apiyi.com) وأنشئ رمزًا مميزًا، ثم انسخه.
لا تحتاج إلى تنفيذ أي أوامر في هذه الخطوة. سيُستخدم هذا المفتاح مرة واحدة فقط في العملية كلها: الصقه في لوحة «المورّد» في magpie (الخطوة 3). بعد لصقه، سيُعدّ magpie ملفات التهيئة الخاصة بكل وكيل تلقائيًا. لن تحتاج إلى استخدام export لتعيين متغيرات البيئة، أو تعديل ملفات مثل config.toml وsettings.json.
🚀 ليس لديك رمز مميز بعد؟ يمكنك التسجيل في APIYI على apiyi.com والحصول على رصيد تجريبي، ثم استخدام رمز مميز واحد لتجربة الأدوات التي تستخدمها باستمرار، قبل أن تقرر النماذج التي تريد مواصلة استخدامها.
1.2 احتفظ بهذين العنوانين في متناول يدك
عند إعداد المورّد في الخطوة 3، اختر العنوان المناسب:
| الاستخدام | العنوان |
|---|---|
| نقطة نهاية متوافقة مع OpenAI (Codex وPi وHermes وغيرها) | https://api.apiyi.com/v1 |
| نقطة نهاية Anthropic الأصلية (Claude Code) | https://api.apiyi.com |
✅ معيار إكمال هذه الخطوة: أصبح الرمز المميز في الحافظة، وتعرف أي عنوان ستُدخل في الخطوة 3.
الخطوة 2: ثبّت magpie وتعرّف أولًا على هاتين الصفحتين
يُرجى الرجوع إلى ملف README في المستودع الرسمي لمعرفة مصدر magpie وطريقة تثبيته وصيغة إعداده (github.com/yetone/magpie). يتطور المشروع بسرعة، وقد تتغير أوامر التثبيت وأسماء الحقول مع الإصدارات؛ لذا فالجزء الذي يبقى صالحًا على المدى الطويل هو لقطات الشاشة وترتيب الخطوات الموضح أدناه.
بعد التثبيت والتشغيل، ستظهر نافذة بها شريط تنقّل على اليسار. لن تحتاج في هذا الدليل إلا إلى صفحتين: Agent (لتحديد النموذج الذي يستخدمه كل وكيل) والمورّد (لتحديد موضع ربط المفتاح).
① Agent في شريط التنقّل الأيسر هو «لوحة التحكم الرئيسية» لجميع الوكلاء:

الشكل 1 · صفحة Agent: يظهر كل برنامج في سطر، ويحدد المفتاح الموجود على اليمين ما إذا كان متصلًا بـ magpie، بينما تتيح القائمة المنسدلة بجانبه اختيار النموذج
تعرّف في هذه الصفحة على ثلاثة عناصر:
| الموضع | المعنى | أين يُستخدم في هذا الدليل |
|---|---|---|
| الأيقونة والاسم في يسار كل سطر | أداة وكيل مثل Claude Desktop وCodex وPi وHermes Agent… | تفعيل كل أداة على حدة في الخطوة 4 |
| السطر الرمادي أسفل الاسم | الحالة الحالية: متصل / غير متصل / لا يمكن استخدامه إلا مع النموذج المضمّن | التحقق في الخطوة 5 |
| المفتاح والقائمة المنسدلة للنموذج على اليمين | تفعيل الاتصال واختيار النموذج الذي سيستخدمه هذا الوكيل | الخطوة 4 |
② المورّد في شريط التنقّل الأيسر هو المكان الذي تربط فيه مفتاح API بالخدمة التي تزوّدك بالنماذج (سنشرح ذلك بالتفصيل في القسم التالي).
إذا أردت أن تتعرّف على شكل ملفات إعداد magpie أولًا، فألقِ نظرة على بنية
providersوagentsفي README الرسمي. الفكرة ببساطة هي «تسمية المورّد، وإدخالbase_urlومفتاح API، ثم تحديد نموذج لكل وكيل». لكن يمكنك تنفيذ كل الإعدادات اليومية بالنقر داخل النافذة؛ إذ يتولى magpie إعداد الملفات الأصلية لكل أداة، وهذا أكثر موثوقية من تعديل YAML يدويًا.
✅ معيار إكمال هذه الخطوة: تفتح النافذة، وتظهر فيها «Agent» و«المورّد» في شريط التنقّل الأيسر.
الخطوة 3: أضف مفتاحك في «المورّدون»
3.1 انتقل إلى صفحة المورّدين
انقر على المورّدون في الشريط الجانبي الأيسر (الإطار الأحمر ① في الشكل 2)، ثم انقر على + إضافة مورّد في أعلى يسار الصفحة (الإطار الأحمر ②):

الشكل 2 · صفحة المورّدين: انتقل إلى «المورّدون» من القائمة الجانبية، ثم انقر على «+ إضافة مورّد» في أعلى اليمين. هذا هو المدخل الوحيد.
تظهر المورّدون الذين أضفتهم هنا على هيئة بطاقات. يعرض السطر الثاني من كل بطاقة عنوان المورّد وعدد النماذج المتاحة، مثل api.apiyi.com · 11 个模型. إذا أردت التأكد من أن المورّد يعمل، فتحقق أولًا من ظهور عدد في هذا السطر.
3.2 ما نوع المورّد الذي تختاره؟
بعد النقر على «+ إضافة مورّد»، ستظهر لوحة اختيار مقسمة إلى عدة مجموعات (الشكل 3):

الشكل 3 · لوحة إضافة مورّد: خمسة أنواع من المصادر، وهي الاشتراكات والمورّدون والوسيط والجهاز المحلي ونسخة magpie على جهاز آخر
تقابل المجموعات في اللوحة خمسة أنواع مختلفة من المفاتيح:
| المجموعة | ما الذي تتضمنه؟ | متى تختارها؟ |
|---|---|---|
| اشتراكات (تسجيل الدخول فقط، دون الحاجة إلى مفتاح) | الاشتراكات الرسمية في Claude وChatGPT وCursor وCopilot وGemini CLI وغيرها | إذا كنت مشتركًا في خدمة رسمية وتريد إتاحتها لوكيل آخر أيضًا |
| المورّدون (واجهات API لمزوّدي النماذج) | Anthropic وOpenAI وGoogle Gemini وDeepSeek وKimi و智谱 وMiniMax وغيرها | إذا كان لديك مفتاح API مباشرةً من أحد المورّدين |
| الوسيط (مفتاح واحد لعدة نماذج) | خدمات تجميع النماذج والوساطة مثل APIYI | إذا كنت تستخدم مفتاحًا وسيطًا واحدًا لاستدعاء عدة نماذج |
| الجهاز المحلي | خدمات محلية مثل Ollama وLM Studio وMLX | إذا كانت لديك نماذج تعمل محليًا |
| نسخة magpie على جهاز آخر | نسخة magpie مشتركة على جهاز آخر في الشبكة المحلية | إذا كنت تريد استخدام الإعدادات نفسها على عدة أجهزة |
إذا كنت تستخدم APIYI، فإن نقطة النهاية المتوافقة مع OpenAI تُعدّ وسيطًا قياسيًا؛ اختر المدخل المناسب من مجموعة الوسيط. أما إذا كان لديك مفتاح مخصص متوافق مع OpenAI أو Anthropic، فانقر مباشرةً على + مورّد مخصص في أسفل القائمة (الإطار الأحمر في الشكل 3)، ثم أدخل العنوان والمفتاح. استخدم العنوان https://api.apiyi.com/v1، أو https://api.apiyi.com للطلبات الأصلية المتوافقة مع Anthropic.
تُظهر هذه الصورة لوحة إعداد مورّد كاملة. وما تحتاج إلى ضبطه يقتصر على أربعة أسطر:

الشكل 4 · صفحة إعداد مورّد APIYI: اختر البروتوكول أولًا ثم أدخل العنوان في Base URL، وضع المفتاح في Accounts، وحدد النماذج التي تريد إتاحتها للوكيل في Models.
| السطر | ما الذي عليك إدخاله؟ |
|---|---|
| Base URL | اختر البروتوكول أولًا (متوافق مع OpenAI أو Anthropic أو Gemini)، ثم أدخل العنوان أدناه |
| Accounts | مفتاحك. يمكنك إضافة عدة مفاتيح؛ وعند نفاد رصيد المفتاح الأول، ينتقل النظام تلقائيًا إلى المفتاح التالي |
| Models | حدد النماذج التي تريد إتاحتها للوكيل. والنماذج التي تظهر في القائمة المنسدلة في الخطوة 4 هي النماذج التي تحددها هنا |
| Agents | الوكلاء الذين يُسمح لهم باستخدام هذا المورّد مصدرًا لنماذجهم |
يوضّح هذا الشكل عمليًا فكرة «رمز واحد، وبروتوكولات متعددة» التي ذكرناها سابقًا: العنوان هو
https://api.apiyi.comفي جميع الحالات. اختر Anthropic compatible لاستخدام نقطة النهاية الأصلية التي يحتاج إليها Claude Code، أو OpenAI compatible لاستخدام نقطة النهاية/v1التي يحتاج إليها Codex وPi وHermes. وينطبق الأمر نفسه على Gemini compatible. لا حاجة إلى إعداد ثلاثة مورّدين وثلاثة مفاتيح.
بعد إدخال البيانات وحفظها، ارجع إلى قائمة المورّدين وتحقق من أمرين: أن يظهر عدد النماذج في السطر الثاني من البطاقة، وأن يكون المفتاح في وضع التشغيل. إذا ظهر · N 个模型، فهذا يعني أن المفتاح والعنوان يعملان؛ فالتحقق هنا يتم تلقائيًا، ولا حاجة إلى تشغيل أوامر إضافية.
✅ التحقق من هذه الخطوة: تظهر بطاقتك في قائمة المورّدين، ويظهر فيها ما يشبه · N 个模型، وليس «غير مُعدّ».
الخطوة 4: اربط الوكلاء التي ثبّتها واحدًا تلو الآخر
ارجع إلى صفحة Agent، وكرّر الخطوات الثلاث نفسها لكل أداة ثبّتها. تعرض هذه الصفحة كل الوكلاء التي يمكن لـmagpie ربطها (وتُضاف إليها أدوات باستمرار؛ أما الأدوات غير المثبتة فتظهر بحالة «لم يُعثر على CLI»). اربط كل ما ثبّتّه. والجدول أدناه يورد أربعة أمثلة شائعة فقط:
- فعّل المفتاح الموجود على اليمين (سيتحول من الرمادي إلى اللون المضيء).
- اختر نموذجًا من القائمة الموجودة بجانب المفتاح (إذا لم تختر نموذجًا، فسيُستخدم النموذج الافتراضي؛ ويُحفظ النموذج الذي تختاره في إعدادات الأداة نفسها).
- أعِد تشغيل الأداة عند ظهور المطالبة (تحتاج معظم الأدوات، مثل Codex وClaude Code وPi وHermes، إلى إعادة تشغيل العملية كي تقرأ الإعدادات الجديدة).

الشكل 5 · افتح قائمة النماذج المنسدلة: الخيار الأول «الافتراضي» يجعل الوكيل يستخدم نموذجه المدمج من دون المرور عبر magpie. أما الخيارات التي تليه، فيظهر بجانب كل منها «عبر magpie». اختر أحدها، وسيستخدم الوكيل النموذج المقابل لدى المورّد.
| الوكيل | ما الذي يحدث بعد تفعيل المفتاح؟ | هل يلزم إعادة التشغيل؟ |
|---|---|---|
| Claude Code | يغيّر magpie قيمتي base_url وtoken اللتين يقرأهما، ويوجّههما إلى البوابة الخاصة به |
نعم، نفّذ exit ثم شغّل claude مجددًا |
| Codex | يضيف magpie قسمًا خاصًا بالمورّد إلى ~/.codex/config.toml |
نعم، أعد تشغيل codex في الطرفية |
| Pi | يضيف magpie مورّدًا مخصصًا إلى إعدادات النماذج في Pi | نعم، أعد تشغيل Pi |
| Hermes Agent | يكتب magpie نقطة نهاية مخصصة في مجلد إعدادات Hermes | نعم، أعد تشغيل Hermes |
إليك بعض الحالات الشائعة التي تدل على أن الإعداد يسير في الاتجاه الصحيح:
- تم الربط: حُفظت الإعدادات، وستسري مفعولها بعد إعادة تشغيل الأداة.
- غير مرتبط · يستخدم إعدادات XXX الخاصة به: لم يُفعّل المفتاح أو لم يُختر نموذج بعد.
- لا يمكنه استخدام سوى نماذج XXX الخاصة به، ولا يمكن لـmagpie ربطه: هذه الأداة (مثل Cursor) لا تسمح باستخدام سوى نماذجها الخاصة. هذا قيد في تصميمها، وليس خطأ في الإعدادات.
- لم يُعثر على CLI: الأداة غير مثبتة أو غير موجودة في
PATH. ثبّتها أو أضفها إلىPATHثم حاول مجددًا.
💡 إذا أردت استخدام نماذج مختلفة مع وكلاء مختلفين (مثل Claude مع Claude Code، وGPT مع Codex، ونموذج أقل تكلفة مع Hermes)، فاختر النموذج المناسب لكل واحد في هذه الخطوة. وهذه إحدى أهم مزايا magpie مقارنةً بـ«البرامج النصية لمتغيرات البيئة».
✅ التحقق من هذه الخطوة: فعّل المفاتيح لكل الأدوات المثبتة، وتأكد من أن سطر الحالة لم يعد يعرض «غير مرتبط».
الخطوة 5: اختبر كل Agent بمهمة واحدة
لا يعني اكتمال الإعداد أن العمل انتهى؛ المهم أن تتأكد من نجاحه عمليًا. أرسل أبسط مهمة إلى كل أداة:
| Agent | إجراء التحقق | النتيجة المتوقعة |
|---|---|---|
| Claude Code | شغّل claude، ثم اكتب: «ألقِ نظرة على المجلد الحالي واذكر أسماء ثلاثة ملفات» |
تظهر نتيجة عادية، من دون أخطاء 401 أو 404 |
| Codex | شغّل codex، ثم اسأل: «ما لغة البرمجة المستخدمة في هذا المستودع؟» |
تظهر نتيجة عادية، من دون أخطاء متعلقة بمزوّد الخدمة |
| Pi | شغّل Pi، وأرسل إليه أي طلب يشرح فيه مقطعًا برمجيًا | تظهر نتيجة عادية |
| Hermes Agent | شغّله، ثم اطرح عليه سؤالًا من جملة واحدة | تظهر نتيجة عادية |
للتأكد من أن الطلبات تمر فعلًا عبر البوابة، أسهل طريقة هي مراجعة سجل الاستخدام أو الطلبات لهذا الرمز في لوحة تحكم APIYI. إذا ظهر سجل استدعاء جديد، فهذا يعني أن طلبات جميع الوكلاء تصل إلى المفتاح نفسه.
✅ معيار إتمام هذه الخطوة: يستجيب كل Agent بنجاح، وتظهر سجلات الاستدعاءات المقابلة في لوحة التحكم.
ملحق: كيف تختار النموذج؟ (الخيار الافتراضي عند عدم التأكد)
| Agent | النماذج الموصى بها | نقطة نهاية البروتوكول |
|---|---|---|
| Claude Code | نماذج Claude (فهو الأقدر على التعامل مع تنسيق استدعاء الأدوات الخاص بنماذج شركته) | واجهة Anthropic الأصلية |
| Codex CLI | نماذج GPT / Codex | OpenAI Responses |
| Pi | بدّل النماذج حسب المهمة: استخدم نموذجًا قويًا لكتابة الشفرة، ونموذجًا أقل تكلفة لتحرير المستندات | متوافق مع OpenAI |
| Hermes | نماذج اقتصادية أو ذات نافذة سياق طويلة | متوافق مع OpenAI |
💡 يُنصح بتجربة المهمة نفسها باستخدام وكلاء ونماذج مختلفة. فمع وجود رمز موحّد، لا يتطلب التبديل سوى تغيير اسم النموذج، وتصبح مقارنة التكلفة سهلة.
الخطوة 6 (اختيارية): ما الإعدادات التي يكتبها magpie نيابةً عنك؟
هذا القسم لا يؤثر في تشغيل الأدوات، وليس خطوة إلزامية. في الاستخدام اليومي، لن تحتاج إلى تعديل هذه الملفات: بمجرد تفعيل المفتاح في الخطوة 4، يكون magpie قد أعدّ كل ما يلي. أضفنا هذا القسم لسببين فقط: لتعرف أي طبقة تفحص عند حدوث مشكلة، ولتتمكن من نسخ الإعدادات مباشرةً إذا قررت يومًا الاستغناء عن magpie.
Claude Code: ANTHROPIC_BASE_URL وANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.apiyi.com" # نقطة نهاية Anthropic الأصلية
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# اختياري: تحديد النموذج الافتراضي (راجع قائمة النماذج في لوحة التحكم)
# export ANTHROPIC_MODEL="<اسم نموذج Claude>"
claude
يمكنك أيضًا إضافة الإعدادات إلى الحقل env في الملف ~/.claude/settings.json، لتصبح مستقلة عن جلسة الطرفية.
Codex: قسم المزوّد في ~/.codex/config.toml
# ~/.codex/config.toml
model = "<اسم نموذج من سلسلة GPT>"
model_provider = "apiyi"
[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1" # نقطة نهاية متوافقة مع OpenAI
env_key = "APIYI_API_KEY"
wire_api = "responses" # إذا كان النموذج المختار لا يدعم Responses، فغيّر القيمة إلى "chat"
يُعدّ wire_api أكثر الإعدادات عرضةً للخطأ: تستخدم الإصدارات الحديثة من Codex بروتوكول Responses افتراضيًا. فإذا كانت البوابة تتيح لهذا النموذج بروتوكول Chat Completions فقط، فعليك تغييره إلى chat.
Pi وHermes: تعريف مزوّد مخصص متوافق مع OpenAI
الفكرة واحدة: اجعل base_url هو https://api.apiyi.com/v1، واجعل مفتاح API يشير إلى APIYI_API_KEY. تختلف بنية الإعدادات من إصدار إلى آخر، لذا راجع الوثائق الرسمية لكل أداة:
عرض الإعدادات المرجعية لـ Pi / Hermes وسكربت التبديل بنقرة واحدة
// Pi: عرّف المزوّد في إعدادات النماذج المخصصة (راجع وثائق Pi الرسمية لمعرفة البنية)
{
"providers": {
"apiyi": {
"baseUrl": "https://api.apiyi.com/v1",
"api": "openai-completions",
"apiKey": "APIYI_API_KEY",
"models": [{ "id": "<اسم النموذج>" }]
}
}
}
# Hermes: شغّل hermes model واختر نقطة نهاية مخصصة متوافقة مع OpenAI،
# ثم أدخل المعلومات التالية عند الطلب (أو أضفها إلى ملف .env / config في مجلد إعدادات Hermes)
# Base URL : https://api.apiyi.com/v1
# API Key : $APIYI_API_KEY
# Model : <اسم النموذج>
#!/usr/bin/env bash
# agents-env.sh —— بديل لا يعتمد على magpie: مفتاح واحد لتشغيل جميع الوكلاء
# طريقة الاستخدام: source agents-env.sh
: "${APIYI_API_KEY:?يرجى تنفيذ export APIYI_API_KEY أولًا}"
# Claude Code (بروتوكول Anthropic)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# متغيرات عامة للأدوات المتوافقة مع OpenAI، مثل Codex وPi وHermes
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"
# التحقق من الاتصال
curl -s "$OPENAI_BASE_URL/models" \
-H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ تم توجيه جميع الوكلاء إلى البوابة نفسها"
إذا كنت تفضّل استخدام سطر الأوامر، فانسخ أسطر `export` من السكربت إلى `~/.zshrc`. وللتحقق من صلاحية المفتاح فقط، يكفي تنفيذ أمر واحد:
curl -s "https://api.apiyi.com/v1/models" \
-H "Authorization: Bearer sk-你的令牌" | head -c 300
إذا ظهرت قائمة بالنماذج، تتضمن عناصر كثيرة مثل `”id”:”…”`، فهذا يعني أن المفتاح والعنوان يعملان كما ينبغي.
عند حدوث مشكلة، ابدأ من هنا: أربعة أخطاء شائعة
| رسالة الخطأ | السبب الشائع | الحل |
|---|---|---|
| Claude Code: خطأ 401 / فشل المصادقة | أُضيف المفتاح إلى ANTHROPIC_API_KEY، أو أُضيف /v1 إلى base_url بالخطأ |
استخدم ANTHROPIC_AUTH_TOKEN، واجعل base_url اسم النطاق فقط |
| Codex: خطأ 404 / المسار غير موجود | لا يتوافق wire_api مع البروتوكول الذي يدعمه النموذج |
جرّب التبديل بين responses وchat |
| النموذج غير موجود | اسم النموذج مكتوب خطأ، أو أن المفتاح لا يتيح استخدامه | افتح قائمة النماذج ضمن «المزوّدون» وتحقق من وجود النموذج؛ ويمكن لمستخدمي سطر الأوامر التحقق باستخدام curl /models |
| Pi / Hermes لا يستجيبان | لم يُعرّف مزوّد مخصص، أو لم يُفعّل متغير المفتاح | نفّذ echo $APIYI_API_KEY، ثم أعد فتح الطرفية |
احرص دائمًا على استكشاف الأخطاء من الأسفل إلى الأعلى: تحقق أولًا من عمل البوابة والمفتاح (هل تظهر البطاقة الخاصة بالمزوّد عبارة · N 个模型؟)، ثم راجع الإعدادات الأصلية للأداة المعنية، وأخيرًا افحص طبقة الربط في magpie. بهذه الخطوات الثلاث يمكنك تحديد ما إذا كانت المشكلة من الخدمة upstream، أو من الأداة نفسها، أو من طبقة الإعدادات الموحدة.
الأسئلة الشائعة
س1: ما هو magpie؟
magpie مشروع مفتوح المصدر أطلقه yetone، ومستودعه على `github.com/yetone/magpie`، وشعاره: «نموذج كل وكيل، في مكان واحد». يجمع إعدادات النماذج التي تستخدمها وكلاء الذكاء الاصطناعي المختلفة في مكان واحد، ما يقلل تكرار الإعداد بين أدوات مثل Claude Code وCodex. ويحظى حاليًا بنحو 16 ألف نجمة على GitHub.
س2: ما العلاقة بين magpie وبوابة API؟
لكل منهما دور مختلف. يتولى magpie تحديد «أي نموذج يستخدمه كل وكيل، وأي مفتاح يقرأ»، بينما تتولى بوابة API «تمرير الطلبات إلى مزوّدي النماذج وفق البروتوكول المناسب». لا يحل magpie محل البوابة، ويعمل بأفضل شكل عند استخدامه مع بوابة تدعم بروتوكولات متعددة.
س3: بعد اتباع الدليل، هل ستستخدم جميع الوكلاء مفتاحًا واحدًا فعلًا؟
نعم. ستُوجَّه طلبات كل وكيل إلى عنوان البوابة نفسه، وستقرأ الوكلاء القيمة من متغير البيئة `APIYI_API_KEY` فقط. عند تدوير المفتاح، يكفي تغييره في هذا الموضع لتطبيقه على الجميع، كما ستظهر الفاتورة في البوابة وحدها.
س4: هل أحتاج إلى إعادة التشغيل بعد تغيير الإعدادات؟
نعم. يجب إغلاق أدوات سطر الأوامر مثل Claude Code وCodex وPi وHermes ثم إعادة فتحها. أما الأدوات ذات الواجهة الرسومية مثل Claude Desktop وZed، فيجب إغلاقها تمامًا ثم تشغيلها من جديد؛ فإغلاق النافذة وحده لا يكفي. سيعرض سطر الحالة في صفحة الوكلاء الإجراء المطلوب بالتحديد.
س5: لماذا تظهر لبعض الوكلاء رسالة «لا يمكن استخدام سوى النماذج المضمّنة»؟
تقيّد بعض الأدوات، مثل Cursor، استخدام النماذج باشتراكها الخاص ولا تقرأ إعدادات مزوّدي النماذج الخارجيين. هذا قيد في تصميمها، وليس خطأً في الإعدادات. في هذه الحالة، تجاوز تلك الأداة وأكمِل ربط الأدوات الأخرى كالمعتاد.
س6: هل يؤثر استخدام بوابة API مع Claude Code في استدعاء الأدوات؟
لا، ما دامت البوابة توفر التنسيق الأصلي لـ Anthropic Messages. أما المسار الأكثر عرضة للمشكلات فهو استخدام «تنسيق متوافق مع OpenAI مع طبقة تحويل إضافية»، إذ قد تضيع تفاصيل تنسيق استدعاء الأدوات. ولهذا يُنصح باختيار بوابة تدعم بروتوكولات متعددة.
س7: ما قيود هذا الحل؟
هناك ثلاثة قيود: قد تتغير حقول إعدادات magpie مع الإصدارات، لذا قد تحتاج إلى التحقق منها مجددًا بعد التحديث؛ ولا يمكن ربط بعض الأدوات، مثل Cursor؛ وإذا كانت البوابة لا تدعم التنسيق الأصلي لـ Anthropic، فسيصبح مسار Claude Code أطول وأكثر عرضة للأخطاء.
مرجع سريع في خمس دقائق
- توزيع المهام: يدير magpie تعيين النماذج، وتتولى البوابة تمرير الطلبات وفق البروتوكول؛ لكل منهما مهمة واحدة.
- مفتاح واحد: اختر مزوّدًا يدعم بروتوكولات متعددة، ليستخدم جميع الوكلاء مفتاحًا واحدًا وفاتورة واحدة.
- ترتيب البدء: أنشئ مفتاحًا في لوحة التحكم ← ألصقه في «مزوّد الخدمة» ← فعّل الوكيل ← اختبر الوكلاء واحدًا تلو الآخر. تتم الخطوات كلها بالنقر في النوافذ، من دون أوامر.
- ترتيب استكشاف الأخطاء وإصلاحها: ابدأ بالبوابة، ثم إعدادات الوكيل الأصلية، ثم طبقة تعيين magpie؛ أي من الأسفل إلى الأعلى.
- ملاحظة حول Claude Code: استخدم
ANTHROPIC_AUTH_TOKEN، ولا تضف/v1إلى base_url. - ملاحظة حول Codex: يجب أن يتوافق
wire_apiمع البروتوكول الذي يدعمه النموذج. - خطة بديلة: يمكن لبرنامج نصي لمتغيرات البيئة، وهو
agents-env.sh، أن يتيح لجميع الوكلاء استخدام مفتاح واحد أيضًا.
إذا كنت تستخدم أكثر من ثلاثة وكلاء، فسيستحق الأمر تخصيص نصف ساعة لإعداد هذا الحل؛ فبعد ذلك، لن تحتاج عند تغيير النموذج أو تدوير المفتاح إلا إلى تعديل موضع واحد. نوصي بالحصول على رصيد تجريبي من APIYI عبر apiyi.com، ثم اختبار الأدوات التي تستخدمها باستمرار أولًا، وتخصيص النماذج لكل وكيل بحسب المهمة بعد ذلك.
قراءات ذات صلة
- 📘 هل يدعم Workbuddy الاستدعاء بتنسيق Claude الأصلي؟ 3 أسباب و6 فئات من أخطاء content: استكشاف الأخطاء وإصلاحها عمليًا: إذا أردت معرفة الفرق بين تنسيق Anthropic الأصلي والتنسيق المتوافق مع OpenAI، فاقرأ هذا المقال. ستجد فيه أيضًا أسباب ضرورة استخدام Claude Code لنقطة النهاية الأصلية، كما ورد في الخطوة الثانية من هذا المقال.
- 📊 مقارنة claude-sonnet-5-5 وclaude-opus-5-5: هل Opus أسرع ولم يعد Sonnet سوى خيار أرخص؟ 6 مجموعات بيانات توضّح أفضل توليفة لوكلاء المؤسسات ذوي السياق الطويل: اطّلع على هذا المقال قبل اختيار نموذج لكل وكيل في الخطوة الرابعة، لتحديد الوكلاء الذين سيستخدمون Opus ومن سيستخدمون نموذجًا أقل تكلفة.
- ⚠️ ما الحد الأقصى للتزامن في Gemini-4-argon AI Studio؟ 5 أسباب لتكرار أخطاء 429 و6 خطوات لحلها: إذا تجاوزت عدة وكلاء حد معدل الطلبات عند استخدام المفتاح نفسه، فاتبع خطوات استكشاف الأخطاء الست الواردة هنا.
- 🧭 خطأ OpenAI: model not found؟ أُزيل GPT-5.5 من ChatGPT في 14 أكتوبر، إليك 5 خطوات للتحقق والبدائل: إذا ظهر خطأ «النموذج غير موجود» أثناء التحقق في الخطوة الخامسة، فتأكد أولًا من أن اسم النموذج لا يزال صالحًا.
📚 المراجع
- GitHub – magpie: المستودع الرسمي للمشروع
- الرابط:
github.com/yetone/magpie - ملاحظة: يُرجى الرجوع إلى ملف README لمعرفة طريقة التثبيت وصيغة الإعدادات وتحديثات الإصدارات.
- الوثائق الرسمية لـ Claude Code: متغيرات البيئة وإعدادات settings
- الرابط:
docs.anthropic.com/en/docs/claude-code - ملاحظة: توضيحات رسمية بشأن المتغيرات مثل
ANTHROPIC_BASE_URL. - مستودع OpenAI Codex CLI: إعدادات config.toml وmodel_providers
- الرابط:
github.com/openai/codex - ملاحظة: شرح إعدادات المزوّد المخصص والمعامل
wire_api. - مركز وثائق APIYI: نقاط النهاية متعددة البروتوكولات وقائمة النماذج
- الرابط:
docs.apiyi.com - ملاحظة: إرشادات الربط بنقاط نهاية بروتوكولات OpenAI وAnthropic وغيرها.
الكاتب: فريق APIYI التقني
للنقاش التقني: نرحب بمشاركة تجاربكم في إعداد magpie ضمن التعليقات. وللاطلاع على مزيد من معلومات الربط، تفضلوا بزيارة مركز وثائق APIYI على docs.apiyi.com.
