تم تصميم OpenClaw لتكون محايدة تجاه مزودي الخدمة، وهي ميزتها الخفية القوية. فهي تدعم الأسماء المعتادة مثل OpenAI وAnthropic، لكنها تسمح لك أيضاً بربط أي واجهة برمجة تطبيقات (API) متوافقة مع OpenAI كمزود مخصص (مستندات OpenClaw، 2026). هذا الخيار التصميمي الفردي هو ما يتيح لك الاحتفاظ بالوكيل (agent) الذي تفضله مع تشغيله على نماذج مفتوحة الأوزان أرخص بكثير، وهي النماذج التي تكلف جزءاً بسيطاً من أسعار النماذج الرائدة لكل "توكن" (token).
العقبة تكمن في أن الإعداد يحتوي على خطوة واحدة يغفل عنها الجميع تقريباً، والقيام بها بشكل خاطئ يؤدي إلى رسالة خطأ ترسل المستخدمين في مسار خاطئ. هذا الدليل يشرح عملية إعداد API مخصص لـ OpenClaw بالطريقة الصحيحة: كيف تعمل تحت الغطاء، التكوين الدقيق الذي يجب نسخه، فخ القائمة المسموح بها، وكيفية التحقق من الاتصال. خصص حوالي خمس دقائق من وقتك.
لماذا قد تحتاج إلى إعداد API مخصص لـ OpenClaw على الإطلاق؟
السبب الصادق هو التكلفة. تقوم الأدوات الوكيلة (Agentic tools) مثل OpenClaw بإعادة إرسال السياق المتراكم في كل خطوة استنتاج، لذا فهي تستهلك "توكنز" أكثر بـ 10 إلى 100 مرة من نافذة المحادثة لنفس المهمة (LeanOps، 2026). هذا المضاعف هو السبب في تضخم فواتير الوكيل بسرعة، حيث يصل المستخدمون المكثفون للنماذج الرائدة إلى حوالي 13 دولاراً لكل مطور يومياً (CloudZero، 2026). إعداد API مخصص لـ OpenClaw يهاجم تلك الفاتورة في مكان وجودها الفعلي: السعر لكل "توكن". وجّه الوكيل إلى نموذج مفتوح الأوزان بدلاً من نموذج رائد وستنخفض تكلفة الوحدة بشكل حاد، غالباً بنسبة 70% أو أكثر في العمل الروتيني، بينما تظل فجوة الجودة في البرمجة اليومية صغيرة. أنت تحتفظ بسير عمل OpenClaw الذي تعرفه بالفعل وتغير فقط ما يجيب على الطلبات. هناك سبب ثانٍ يهم الفرق خارج المناطق التي يخدمها مزود معين مباشرة. يمنحك المزود المخصص طريقة مستقرة ومتوافقة لتشغيل الوكيل دون الاعتماد على فواتير شركة واحدة، أو جدول طرح التحديثات، أو التوفر الإقليمي.
كيف يعمل إعداد API مخصص لـ OpenClaw: الخطوتان اللتان يغفل عنهما الناس
قبل نسخ التكوين، افهم النموذج الذي تستخدمه OpenClaw، لأنه يفسر الخطأ الذي يواجهه الجميع. يتم تحديد المزود المخصص في مكانين، وكلاهما مطلوب.
أولاً، تصف المزود نفسه في قسم models.providers: عنوان URL الأساسي (base URL)، مفتاح API، بروتوكول النقل (openai-completions لأي نقطة نهاية متوافقة مع OpenAI)، وقائمة النماذج التي يقدمها. ثانياً، وهذا هو الجزء الذي يغفل عنه الناس، يجب عليك إدراج النموذج في القائمة المسموح بها في agents.defaults.models، باستخدام المعرف المؤهل بالكامل provider-name/model-name (مستندات OpenClaw، 2026). تعريف المزود لا يجعل نماذجه قابلة للاستخدام تلقائياً. سترفض OpenClaw أي شيء ليس موجوداً في القائمة المسموح بها.
هذا التصميم مقصود. القائمة المسموح بها هي ما يسمح لك بتحديد كتالوج كبير من المزودين والنماذج ولكن تعرض فقط تلك التي تريد حقاً أن يصل إليها الوكيل. بمجرد استيعاب أن المزودين والقائمة المسموح بها هما طبقتان منفصلتان، يصبح باقي إعداد API مخصص لـ OpenClaw عملية ميكانيكية.
إعداد API مخصص لـ OpenClaw، خطوة بخطوة
يستخدم المثال أدناه Atlas Cloud كمزود، لأنه يعرض نقطة نهاية واحدة متوافقة مع OpenAI تدعم النماذج الرئيسية مفتوحة الأوزان خلف مفتاح واحد. هذا يجعل التكوين قصيراً ويسمح لك بتبديل النماذج لاحقاً دون تسجيل أي شيء جديد. تنطبق نفس الخطوات على أي مزود متوافق؛ فقط عنوان URL الأساسي والمفتاح يتغيران.
الخطوة 1: الحصول على نقطة النهاية ومفتاح API الخاص بك
بحلول نهاية هذه الخطوة سيكون لديك سلسلتان: عنوان URL أساسي ومفتاح.
- أنشئ حساباً مع مزود الخدمة الخاص بك وافتح قسم مفاتيح API.
- أنشئ مفتاحاً مخصصاً للاستخدام البرمجي. في Atlas Cloud، تختار Coding Plan كنوع للمفتاح، مما يربطه بحصة البرمجة القائمة على الرصيد بدلاً من الدفع حسب الاستخدام العام.
- لاحظ عنوان URL الأساسي. بالنسبة للعملاء المتوافقين مع OpenAI مثل OpenClaw، تستخدم Atlas Cloud الرابط https://api.atlascloud.ai/v1 (لاحقة /v1 مهمة هنا).
الخطوة 2: تشغيل معالج الإعداد (Wizard)، أسرع إعداد لـ API مخصص في OpenClaw
بحلول نهاية هذه الخطوة، سيكون الاتصال مباشراً بالطريقة السهلة. في الجهاز (terminal)، قم بتشغيل المعالج الموجه:
Bash1openclaw onboard
ثم اتبع التعليمات: اختر Yes، اختر QuickStart، وحدد Custom Provider. سيطلب المعالج عنوان API الأساسي (https://api.atlascloud.ai/v1)، ومفتاح API الذي نسخته، ومعرف النموذج. تأكد من اختيار بروتوكول OpenAI-compatible عند المطالبة. عندما تظهر رسالة Verification successful، فهذا يعني أن نقطة النهاية تعمل. انتهِ بإعطاء نقطة النهاية معرفاً واسماً ودوداً. الميزة الخفية للمعالج: هو يكتب تعريف المزود وإدخال القائمة المسموح بها للنماذج نيابة عنك، ثم يعيد تشغيل البوابة، لذا تتخطى وضع الفشل الأكثر شيوعاً تماماً.
الخطوة 3: أو تحرير ملف التكوين مباشرة
بحلول نهاية هذه الخطوة ستفهم ما كتبه المعالج فعلياً، وهو أمر مهم عندما تريد إضافة المزيد من النماذج لاحقاً. يقع التكوين في ~/.openclaw/openclaw.json (مستندات OpenClaw، 2026). حدد المزود:
JSON1{ 2 "models": { 3 "mode": "merge", 4 "providers": { 5 "atlascloud": { 6 "baseUrl": "https://api.atlascloud.ai/v1", 7 "apiKey": "your-atlas-api-key", 8 "api": "openai-completions", 9 "models": [ 10 { "id": "zai-org/glm-5.1", "name": "glm-5.1", "contextWindow": 200000 } 11 ] 12 } 13 } 14 } 15}
الخيار "mode": "merge" يحافظ على المزودين الحاليين لديك دون استبدالهم. بالنسبة للمزودين المخصصين، الحقول مثل reasoning وcost وmaxTokens اختيارية وتعود إلى القيم الافتراضية المعقولة، لذا لا تحتاج إلى ملء كل شيء للبدء.
الخطوة 4: إدراج النموذج في القائمة المسموح بها
بحلول نهاية هذه الخطوة ستسمح OpenClaw لك بالفعل باستخدام النموذج. هذه هي الخطوة التي يتجاهلها الناس. أضف المعرف المؤهل بالكامل إلى القائمة المسموح بها:
JSON1{ 2 "agents": { 3 "defaults": { 4 "models": { 5 "atlascloud/zai-org/glm-5.1": { "alias": "glm" } 6 } 7 } 8 } 9}
المفتاح هو اسم مزودك متبوعاً بمعرف النموذج تماماً كما حددته. الـ alias هو مجرد اختصار يمكنك كتابته بدلاً من المسار الكامل. بدون هذه الكتلة، يوجد المزود ولكن يتم رفض كل طلب.
الخطوة 5: التحقق من إعداد API المخصص لـ OpenClaw
بحلول نهاية هذه الخطوة ستعرف أنها تعمل. ابدأ OpenClaw، حدد النموذج الخاص بك (أو اختصاره)، وأعطه مهمة بسيطة مثل شرح ملف. الاستجابة العادية تعني أن الطلبات تتدفق إلى نقطة النهاية الخاصة بك. إذا رأيت "model not allowed"، أعد زيارة الخطوة 4؛ فمن المؤكد تقريباً أن مفتاح القائمة المسموح بها لا يتطابق تماماً مع أسماء المزود والنموذج. إذا حصلت على خطأ في المصادقة، فالمفتاح خاطئ أو يحتوي على مسافة زائدة. إذا لم يتمكن من الاتصال، أعد التحقق من عنوان URL الأساسي ولاحقة /v1.
اختيار نموذج لإعداد API المخصص لـ OpenClaw
اختيار النموذج هو حيث يتم تحديد التوفير. النمط الذكي هو استخدام نموذج مفتوح قوي ورخيص للعمل اليومي والاحتفاظ بنموذج أغلى ثمناً للحالات التي تتطلب استنتاجاً صعباً. القدرة حقيقية: على معيار SWE-Bench Pro، تسجل النماذج المفتوحة الرائدة في مستويات الـ 70 العالية مقابل حوالي 91 لأفضل النماذج الرائدة (Codersera، 2026)، وهي فجوة ذات مغزى في أصعب المشكلات ولكنها صغيرة في مهام الميزات الروتينية وإعادة الهيكلة. على بوابة تعتمد على الرصيد، يحمل كل نموذج مضاعفاً يربط استخدام "التوكن" بالأرصدة، مما يجعل مقارنة التكلفة النسبية سهلة:
| معرف النموذج | السياق | مضاعف الإدخال | مضاعف الإخراج | التوفير التقريبي مقابل الرسمي |
|---|---|---|---|---|
| deepseek-ai/deepseek-v4-flash | 1M | 0.23 | 0.46 | ~50% |
| deepseek-ai/deepseek-v3.2 | 160K | 0.42 | 0.62 | ~55% |
| minimaxai/minimax-m2.5 | 200K | 0.65 | 2.18 | ~45% |
| moonshotai/kimi-k2.6 | 262K | 1.72 | 7.26 | ~45% |
| zai-org/glm-5.1 | 200K | 2.54 | 7.99 | ~45% |
المصدر: قواعد رصيد خطة ترميز Atlas Cloud. تكلفة الرصيد = توكنز الإدخال × مضاعف الإدخال + توكنز الإخراج × مضاعف الإخراج. خيار افتراضي معقول: شغّل GLM-5.1 أو Kimi K2.6 للبرمجة التفاعلية، وانتقل إلى DeepSeek V4 Flash للوظائف ذات الحجم الكبير أو المهام الخلفية، ولا تستخدم نموذجاً رائداً إلا في المهام العرضية التي لا يستطيع النموذج المفتوح حلها. نظراً لأن كل شيء يقع خلف مزود واحد، فإن التبديل هو تغيير بسطر واحد للاختصار الذي تستدعيه.
نقطة نهاية واحدة لـ OpenClaw وClaude Code وCodex
نقطة النهاية التي تشغل إعداد OpenClaw الخاص بك ليست محدودة بـ OpenClaw. معظم المطورين يشغلون أكثر من وكيل، وتوجيه كل واحد منهم إلى مزود مختلف يعني التوفيق بين مفاتيح منفصلة، ولوحات تحكم منفصلة، وفواتير منفصلة. التوحيد على نقطة نهاية واحدة متوافقة مع OpenAI يقلص ذلك إلى مجموعة رصيد واحدة ومكان واحد لتغيير النماذج.
نظراً لأن Atlas Cloud تعرض نفس عنوان URL الأساسي عبر الأدوات، فإن تكوين OpenClaw أعلاه له مكافئات مباشرة في أماكن أخرى. تقرأ Claude Code خلفيتها من ~/.claude/settings.json باستخدام ANTHROPIC_BASE_URL المعين على https://api.atlascloud.ai (ملاحظة: لا توجد لاحقة /v1 لـ Claude Code تحديداً). تستخدم Codex ملف ~/.codex/config.toml مع base_url موجه إلى https://api.atlascloud.ai/v1. العملاء بأسلوب Cursor وOpenCode وCopilot يستخدمون نفس نقطة نهاية /v1. مفتاح واحد، ميزانية واحدة، كل أداة.
هذا التوحيد يصلح أيضاً التحكم في الإنفاق. الخطة التي تجدد بدل رصيد يومي ثابت عند منتصف الليل تضع سقفاً هيكلياً لحلقة الوكيل الجامحة، بينما تمتص باقات الدفع حسب الاستخدام الارتفاعات العرضية. تبدأ خطط Atlas Cloud بـ 10 دولارات شهرياً، وتحمل باقات الدفع حسب الاستخدام خصماً بنسبة 41%، وتتم تسوية الترقيات في منتصف الدورة تناسبياً، لذا يمكن أن يكلف تغيير المستوى الفرق فقط بدلاً من خطة جديدة.
أخطاء إعداد API مخصص لـ OpenClaw الشائعة
تتعقب معظم الإعدادات الفاشلة قائمة قصيرة من الأخطاء، وتقريباً كلها تقع في التكوين بدلاً من أي شيء أعمق. نسيان القائمة المسموح بها. الخطأ الأكثر شيوعاً على الإطلاق. تعريف المزود هو نصف المهمة فقط. إذا رأيت "model not allowed"، فالنموذج مفقود من agents.defaults.models أو المفتاح لا يتطابق (haimaker، 2026). عدم تطابق مفتاح القائمة المسموح بها. يجب أن يكون مفتاح القائمة المسموح بها provider-name/model-name باستخدام السلاسل الدقيقة التي حددتها. أي خطأ مطبعي في أي من النصفين ينتج عنه نفس الرفض مثل حذفه تماماً. مسار عنوان URL الأساسي خاطئ. تتوقع الأدوات المتوافقة مع OpenAI مثل OpenClaw مسار /v1. تركه أو إضافته حيث لا تريده أداة معينة يسبب أخطاء في الاتصال. الكتابة فوق التكوين بدلاً من دمجه. إذا قمت بتحرير التكوين يدوياً بدون "mode": "merge"، يمكنك مسح المزودين الآخرين. احتفظ بوضع الدمج إلا إذا كنت تقصد استبدال كل شيء.
الأسئلة الشائعة: إعداد API مخصص لـ OpenClaw
هل إعداد API مخصص لـ OpenClaw صعب؟
لا. أسرع مسار هو معالج openclaw onboard، الذي يكتب تعريف المزود والقائمة المسموح بها للنماذج نيابة عنك ويستغرق حوالي خمس دقائق. المسار اليدوي هو تعديلان صغيران لملف JSON. العقبة المفاهيمية الوحيدة هي تذكر أن تعريف المزود وإدراج النموذج في القائمة المسموح بها هما خطوتان منفصلتان.
ما هو خطأ إعداد API مخصص لـ OpenClaw الأكثر شيوعاً؟
رفض "model not allowed"، وهو يعني تقريباً دائماً أن النموذج مفقود من القائمة المسموح بها في agents.defaults.models، أو أن مفتاح provider-name/model-name به خطأ مطبعي. الفشل في الإدراج في القائمة المسموح بها هو السبب الأول لهذا الخطأ (haimaker، 2026)، وهذا هو بالضبط سبب تعامل معالج الإعداد معه تلقائياً.
ما هو النموذج الذي يجب أن أختاره لإعداد API المخصص لـ OpenClaw؟
للبرمجة التفاعلية، يعد النموذج المفتوح العام القوي مثل GLM-5.1 أو Kimi K2.6 خياراً افتراضياً جيداً. للعمل ذي الحجم الكبير أو المهام الخلفية، يعتبر النموذج الأرخص مثل DeepSeek V4 Flash منطقياً. احتفظ بنموذج رائد احتياطياً فقط للمهام التي لا يستطيع النموذج المفتوح حلها حقاً.
كم يمكن للمزود المخصص توفيره لي فعلياً؟
يعتمد ذلك على النموذج، لكن الفرق كبير. يعمل DeepSeek V4 Flash بحوالي 0.14 دولار لكل مليون "توكن" إدخال مقابل عدة دولارات للنماذج الرائدة (Codersera، 2026)، لذا فإن توجيه العمل الروتيني إلى نموذج مفتوح يقلل عادةً فاتورة كل "توكن" بنسبة 70% أو أكثر دون تغيير طريقة عملك.
هل يمكنني العودة إلى مزودي الأصلي لاحقاً؟
نعم. المزودون المخصصون إضافيون عندما تحتفظ بـ "mode": "merge"، لذا يظل المزودون الأصليون محددين. التبديل هو مجرد مسألة اختيار نموذج أو اختصار مختلف في OpenClaw، ويمكنك إزالة كتلة المزود في أي وقت.
الخاتمة
يعد إعداد API مخصص لـ OpenClaw أحد أكثر تغييرات الخمس دقائق تأثيراً التي يمكن للمطور القيام بها في عام 2026. يظل الوكيل كما هو، لكن الواجهة الخلفية والفاتورة لا تفعلان ذلك. حدد المزود، أدرج النموذج في القائمة المسموح بها، وجهه إلى خيار مفتوح الأوزان، وستحتفظ بسير عمل OpenClaw الذي تعرفه مع دفع جزء بسيط من أسعار النماذج الرائدة. إذا كنت تريده تحت مفتاح واحد وميزانية واحدة تغطي أيضاً Claude Code وCodex، يمكنك تشغيله من خلال وحدة تحكم خطة البرمجة Atlas Cloud وتبديل النماذج وقتما تتغير المهمة.
