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 را تفکیک می‌کند، اما هرگز مقدار آن را چاپ نمی‌کند. برای چرخش اعتبارنامه، 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 "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 متصل شود. مقادیری که در بودجهٔ ۱۲۸ نویسه‌ای شناسهٔ درخواست قرار می‌گیرند یکسان‌اند. مقادیر طولانی‌تر پسوند :model:<n> و یک هش قطعی را حفظ می‌کنند تا فراخوانی‌های متمایز همچنان محدود و قابل اتصال باقی بمانند. فرادادهٔ ایستای استقرار مانند X-ClawRouter-Project-Id را می‌توان در نگاشت headers ارائه‌دهنده تنظیم کرد. سرآیندهای انتساب عامل و نشست، محدودیت جداگانهٔ ۲۵۶ نویسه‌ای خود را حفظ می‌کنند. شناسه‌های درخواست خودکاری که شامل نویسه‌های خارج از مجموعهٔ شناسه‌های 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 نیاز ندارد: تازه‌سازی بعدی فهرست (با حافظهٔ نهان ۶۰ ثانیه‌ای برای هر دامنهٔ اعتبارنامه) آن را کشف می‌کند. مدلی که به پروتکل سیمی جدیدی نیاز دارد، ابتدا به پشتیبانی Plugin نیاز خواهد داشت.

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

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 پایه) ذخیرهٔ موقت می‌شود.
• کلید پراکسی فقط هنگام ارسال درخواست پیوست می‌شود و در فرادادهٔ مدل ذخیره نمی‌شود.
• مقادیر انتساب خودکار و هم‌بستگی درخواست پیش از ارسال از فاصله‌های اضافی پاک می‌شوند و در صورت داشتن نویسه‌های کنترلی رد می‌شوند. مقادیر انتساب حداکثر ۲۵۶ نویسه و شناسه‌های درخواست حداکثر ۱۲۸ نویسه هستند.
• اطلاعات تشخیصی انتقال مدل فقط شامل فراداده است و هرگز کلید پراکسی یا محتوای مدل را دربر نمی‌گیرد.
• شناسه‌های مدل بومی Anthropic و Gemini فقط هنگام ارسال به شناسه‌های بالادستی آن‌ها بازنویسی می‌شوند.
• ردیف‌های پشتیبانی‌نشده یا فاقد مجوز کاتالوگ به‌صورت بسته رد می‌شوند و قابل انتخاب نیستند.

مرتبط