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>

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

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

على سبيل المثال، يمكن لوحدة تحكم النشر امتلاك رقعة 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 "أجب تمامًا: CLAWROUTER_CANARY_OK" \  --json

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

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

[model-fetch] بدء provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] استجابة 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/Perplexity؛ وسياسات إعادة التشغيل الأصلية في Anthropic وGoogle Gemini). تحصل نماذج Perplexity على إعادة كتابة صارمة للمخطط: تُزال patternProperties وadditionalProperties، ويعلن كل مخطط كائن عن properties، لأن Perplexity يرفض مخططات الأدوات التي لا تتضمنها. لا يُعلن عمدًا عن موفّر كتالوج لا يتيح سوى تنسيق طلب غير مدعوم بوصفه نموذجًا نصيًا في OpenClaw. طبّع هؤلاء الموفّرين إلى أحد العقود المدعومة في ClawRouter بدلًا من إرسال حمولة غير متوافقة.

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

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

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

تحقّق من اللقطة المباشرة باستخدام:

openclaw status --usageopenclaw models status

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

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

سلوك الأمان

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

ذو صلة