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 را تفکیک می‌کند، اما هرگز مقدار آن را چاپ نمی‌کند. برای چرخش اعتبارنامه، Secret خارجی تأمین‌کنندهٔ CLAWROUTER_API_KEY را به‌روزرسانی کنید و بار کاری Gateway را دوباره راه‌اندازی کنید تا محیط فرایند جدید بارگذاری شود. فایل پیکربندی و ارجاع مدل تغییر نمی‌کنند.

برای یک Gateway مستقل Docker که از منبع ساخته شده است، ClawRouter از قبل در زمان اجرای ریشه گنجانده شده است. فقط Plugin کانالی را انتخاب کنید که به بسته‌بندی جداگانه نیاز دارد، مانند OPENCLAW_EXTENSIONS=clickclack، slack یا msteams؛ به تصاویر ساخته‌شده از منبع با Pluginهای انتخاب‌شده مراجعه کنید. استقرارهای بایگانی/دستگاهی باید همان منبع ثبت‌شده را از طریق پایپ‌لاین مصنوع خود بسته‌بندی کنند، نه اینکه تصویر 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 نیاز دارد.

Pluginهای پروتکل و ارائه‌دهنده

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 فقط هنگام ارسال به شناسه‌های بالادستی آن‌ها بازنویسی می‌شوند.
• ردیف‌های پشتیبانی‌نشده یا فاقد مجوز کاتالوگ به‌صورت بسته رد می‌شوند و قابل انتخاب نیستند.

مرتبط