ClawRouter

يمنح ClawRouter ‏OpenClaw مفتاحًا واحدًا مقيّدًا بالسياسة لعدة موفّري نماذج في المنبع. لا يكتشف Plugin ‏clawrouter المضمّن إلا النماذج المسموح بها لذلك المفتاح، ويوجّه كل نموذج عبر البروتوكول المعلن له، ويعرض ميزانية المفتاح والاستخدام الإجمالي في واجهات استخدام OpenClaw.

تظل بيانات الاعتماد في المنبع وإعادة التوجيه الخاصة بكل موفّر داخل ClawRouter، لذا لن تحتاج أبدًا إلى تثبيت Plugin كل موفّر في المنبع أو مصادقته على مضيف OpenClaw. يأتي Plugin مضمّنًا مع OpenClaw (enabledByDefault: true)؛ ولا تحتاج إلا إلى بيانات اعتماد صادرة عن ClawRouter.

البدء

export CLAWROUTER_API_KEY="..."openclaw onboard --auth-choice clawrouter-api-keyopenclaw plugins enable clawrouter

openclaw models list --all --provider clawrouter

openclaw models set clawrouter/<provider>/<model>

النشر المُدار غير التفاعلي

احتفظ بمفتاح الوكيل ضمن آلية حقن الأسرار الخاصة بعبء العمل، ولا تخزّن في openclaw.json إلا SecretRef. الحقول المُدارة القياسية هي:

على سبيل المثال، يمكن لوحدة تحكم النشر امتلاك رقعة JSON5 هذه:

{  plugins: {    entries: { clawrouter: { enabled: true } },  },  models: {    providers: {      clawrouter: {        baseUrl: "https://clawrouter.internal.example",        apiKey: {          source: "env",          provider: "default",          id: "CLAWROUTER_API_KEY",        },        headers: {          "X-ClawRouter-Project-Id": "fakeco",        },      },    },  },  agents: {    defaults: {      model: { primary: "clawrouter/openai/gpt-5.5" },    },  },}

إذا كان النشر يضبط plugins.allow، فاحتفظ بإدخالاته الحالية وأضف clawrouter. تحقّق من الرقعة وطبّقها دون معالج تفاعلي:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --jsonopenclaw config patch --file ./clawrouter.patch.json5

يحل التشغيل التجريبي SecretRef، لكنه لا يطبع قيمته أبدًا. لتدوير بيانات الاعتماد، حدّث السر الخارجي الذي يوفّر CLAWROUTER_API_KEY ثم أعد تشغيل عبء عمل Gateway لكي تُحمّل بيئة العملية الجديدة. لا يتغير ملف التهيئة ولا مرجع النموذج.

بالنسبة إلى Gateway مستقل مبني من المصدر باستخدام Docker، يكون ClawRouter مشمولًا بالفعل في بيئة التشغيل الجذرية. اختر فقط Plugin القناة الذي يحتاج إلى حزم منفصل، مثل OPENCLAW_EXTENSIONS=clickclack، أو slack، أو msteams؛ راجع الصور المبنية من المصدر مع Plugins محددة. يجب أن تحزم عمليات نشر الأرشيف/الجهاز المصدر المُدمج نفسه عبر مسار التحف الخاص بها بدلًا من استهلاك صورة OCI.

الجاهزية والإثبات الفعلي

تثبت عمليات التحقق هذه حدودًا مختلفة؛ لا تستبدل إحداها بالأخرى:

# سلامة عملية ClawRouter فقط؛ لا تُختبر بيانات اعتماد ولا نموذج في المنبع.curl -fsS https://clawrouter.internal.example/v1/health # جاهزية بدء تشغيل Gateway في OpenClaw فقط؛ لا يُجرى استدعاء نموذج.curl -fsS http://127.0.0.1:18789/readyz # اكتشاف الكتالوج المقيّد ببيانات الاعتماد.openclaw models list --all --provider clawrouter --json # اختبار استدلال حقيقي بالحد الأدنى عبر موفّر ClawRouter المهيأ.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # اختبار كناري لعبء العمل باستخدام مرجع دقيق لنموذج ممنوح.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Reply exactly: CLAWROUTER_CANARY_OK" \  --json

استخدم نموذجًا يعيده الكتالوج المقيّد بدلًا من نسخ نموذج المثال دون تحقق. تعني الاستجابة الناجحة من /readyz أن Gateway يستطيع خدمة الطلبات؛ ولا تعني أن ClawRouter أو بيانات اعتماده أو أحد موفّري المنبع جاهز. يُعد اختبار النموذج واختبار الكناري للوكيل دليلي الاستدلال.

للتشخيص الفعلي، نفّذ اختبار الكناري وافحص سجلات Gateway القياسية. تصدر تشخيصات نقل النماذج الحالية، التي تقتصر على البيانات الوصفية، أسطرًا بالشكل التالي:

[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] response provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

يرسل Plugin ترويسات X-ClawRouter-Client وX-ClawRouter-Agent-Id وX-ClawRouter-Session-Id محدودة الطول عند توفر تلك المعرّفات. كما يربط callId التشخيصي لاستدعاء النموذج (<run-id>:model:<n>) مع X-Request-ID، بحيث يمكن ربط حدث استدعاء نموذج في OpenClaw بسجل تدقيق ClawRouter الذي يقتصر على البيانات الوصفية. تكون القيم الواقعة ضمن ميزانية معرّف الطلب البالغة 128 محرفًا متطابقة. وتحتفظ القيم الأطول باللاحقة :model:<n> وبصمة حتمية، بحيث تظل الاستدعاءات المختلفة محدودة الطول وقابلة للربط. يمكن ضبط البيانات الوصفية الثابتة للنشر، مثل X-ClawRouter-Project-Id، في خريطة headers الخاصة بالموفّر. تحتفظ ترويسات إسناد الوكيل والجلسة بحدها المنفصل البالغ 256 محرفًا. تستخدم معرّفات الطلب التلقائية التي تحتوي على محارف خارج مجموعة معرّفات ASCII الخاصة بـ ClawRouter الصيغة الحتمية محدودة الطول نفسها. تتغلب الترويسات المهيأة صراحةً، بما فيها أي صيغة حالة أحرف من X-Request-ID، على القيم التلقائية. يسجّل تشخيص النقل البيانات الوصفية للتوجيه والاستجابة؛ ولا يسجّل بيانات الاعتماد أو معرّفات الطلب أو المطالبات أو الإكمالات. يوفّر حدث التدقيق الخاص بـ ClawRouter موفّر المنبع المحدد وحالة الاحتفاظ بالمحتوى.

اكتشاف النماذج

يعيد GET /v1/catalog البنية { providers: [...] }، حيث يسرد كل إدخال موفّر مصفوفة models[] الخاصة به (مع معرّف المنبع والإمكانات والأسعار) ومسارات الطلبات المدعومة لديه. لا يوفّر OpenClaw قائمة ثانية ثابتة من نماذج ClawRouter. يُعلن نموذج الكتالوج كنموذج OpenClaw عندما:

• تمنح سياسة بيانات الاعتماد موفّره؛
• يعلن نموذج الكتالوج عن إمكانية LLM مدعومة (llm.responses، أو llm.chat، أو llm.messages، أو llm.stream مع مسار بث مطابق)؛ و
• يوفّر الموفّر مسارًا مطابقًا لإحدى وسائل النقل أدناه.

لا تتطلب إضافة نموذج إلى موفّر ClawRouter مدعوم إصدارًا جديدًا من OpenClaw: سيكتشفه تحديث الكتالوج التالي (المخزّن مؤقتًا لمدة 60 ثانية لكل نطاق بيانات اعتماد). أما النموذج الذي يحتاج إلى بروتوكول سلكي جديد فيتطلب دعم Plugin أولًا.

البروتوكول وPlugins الموفّرين

يمتلك ClawRouter بيانات اعتماد المنبع؛ ويخبر كتالوجه OpenClaw بوسيلة النقل التي يجب استخدامها، لذا لن تحتاج أبدًا إلى تثبيت Plugin المصادقة لكل شركة في المنبع.

يطبّق Plugin أيضًا سياسات إعادة التشغيل ومخطط الأدوات المطابقة لتلك العائلات (توافق مخطط أدوات OpenAI/DeepSeek/Gemini؛ وسياسات إعادة التشغيل الأصلية في Anthropic وGoogle Gemini). لا يُعلن عمدًا موفّر كتالوج لا يقدّم إلا تنسيق طلب غير مدعوم كنموذج نصي في OpenClaw. طبّع هؤلاء الموفّرين وفق أحد العقود المدعومة في ClawRouter بدلًا من إرسال حمولة غير متوافقة.

الحصص والاستخدام

تغذّي استجابة /v1/usage من ClawRouter واجهات استخدام الموفّر المعتادة في OpenClaw: إجماليات الطلبات والرموز والإنفاق، بالإضافة إلى نافذة ميزانية شهرية عندما يكون للمفتاح حد. تظل المفاتيح غير المقاسة تعرض الاستخدام الإجمالي دون نافذة نسبة مئوية.

يستخدم البحث عن الحصة المفتاح المقيّد نفسه المستخدم لاكتشاف النماذج. لا يؤدي فشل البحث عن الحصة إلى حظر تنفيذ النموذج.

تحقق من اللقطة الفعلية باستخدام:

openclaw status --usageopenclaw models status

تتوفر لقطة الموفّر نفسها للأمر /status في الدردشة وواجهة استخدام OpenClaw. تكون الميزانية على مستوى السياسة، لذا قد تغير الطلبات التي ينفذها عميل آخر يستخدم سياسة ClawRouter نفسها النسبة المتبقية.

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

سلوك الأمان

• يقتصر اكتشاف الكتالوج على مفتاح الوكيل المُهيّأ، ويُخزَّن مؤقتًا لكل نطاق من نطاقات بيانات الاعتماد (دليل الوكيل، ودليل مساحة العمل، ومعرّف ملف تعريف المصادقة، وعنوان URL الأساسي).
• لا يُرفق مفتاح الوكيل إلا عند إرسال الطلب؛ ولا يُخزَّن في البيانات الوصفية للنموذج.
• تُزال المسافات الزائدة من قيم الإسناد التلقائي وربط الطلبات، وتُرفض محارف التحكم فيها قبل الإرسال. ويقتصر طول قيم الإسناد على 256 محرفًا، ومعرّفات الطلبات على 128 محرفًا.
• لا تحتوي تشخيصات نقل النموذج إلا على البيانات الوصفية، ولا تتضمن مطلقًا مفتاح الوكيل أو محتوى النموذج.
• لا تُعاد كتابة معرّفات نماذج Anthropic وGemini الأصلية إلى معرّفاتها لدى المصدر إلا عند الإرسال.
• تُرفض صفوف الكتالوج غير المدعومة أو غير الممنوحة تلقائيًا، ولا يمكن تحديدها.

ذو صلة