---
read_when:
    - شما یک کلید مدیریت‌شده برای چندین ارائه‌دهندهٔ مدل می‌خواهید
    - در OpenClaw به کشف مدل‌های ClawRouter یا گزارش سهمیه نیاز دارید
summary: مدل‌های محدودشده به اعتبارنامه را از طریق ClawRouter مسیریابی کنید و سهمیه‌های مدیریت‌شده را نمایش دهید
title: ClawRouter
x-i18n:
    generated_at: "2026-07-12T10:37:15Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: b9a83253b5de3022bb3d3113427e5183f4ac537161ed75723fec0dafc33ebb00
    source_path: providers/clawrouter.md
    workflow: 16
---

ClawRouter برای چندین ارائه‌دهندهٔ بالادستی مدل، یک کلید با دامنهٔ سیاستی در اختیار OpenClaw قرار می‌دهد. Plugin همراه `clawrouter` فقط مدل‌هایی را کشف می‌کند که برای آن کلید مجازند، هر مدل را از طریق پروتکل اعلام‌شدهٔ آن مسیریابی می‌کند و بودجه و مصرف تجمیعی کلید را در بخش‌های مصرف OpenClaw گزارش می‌دهد.

اعتبارنامه‌های بالادستی و ارسال اختصاصی هر ارائه‌دهنده در ClawRouter باقی می‌مانند، بنابراین هرگز لازم نیست Plugin هر ارائه‌دهندهٔ بالادستی را روی میزبان OpenClaw نصب یا احراز هویت کنید. این Plugin همراه OpenClaw عرضه می‌شود (`enabledByDefault: true`)؛ فقط به یک اعتبارنامهٔ صادرشدهٔ ClawRouter نیاز دارید.

| ویژگی         | مقدار                                           |
| ------------- | ----------------------------------------------- |
| ارائه‌دهنده   | `clawrouter`                                    |
| Plugin        | همراه (در OpenClaw گنجانده شده است)             |
| احراز هویت    | `CLAWROUTER_API_KEY`                            |
| نشانی پیش‌فرض | `https://clawrouter.openclaw.ai`                |
| فهرست مدل‌ها  | محدود به اعتبارنامه از طریق `/v1/catalog`       |
| سهمیه‌ها      | بودجه و مصرف ماهانه از طریق `/v1/usage`         |

## شروع به کار

<Steps>
  <Step title="دریافت اعتبارنامهٔ محدود">
    از مدیر ClawRouter خود اعتبارنامه‌ای درخواست کنید که سیاست آن شامل
    ارائه‌دهندگان، مدل‌ها و بودجهٔ ماهانه‌ای باشد که باید استفاده کنید. اعتبارنامه‌ها
    هنگام صدور فقط یک بار نمایش داده می‌شوند.
  </Step>
  <Step title="پیکربندی OpenClaw">
    ```bash
    export CLAWROUTER_API_KEY="..."
    openclaw onboard --auth-choice clawrouter-api-key
    openclaw plugins enable clawrouter
    ```

    `clawrouter` همراه محصول است و به‌طور پیش‌فرض فعال است. اگر پیکربندی شما
    `plugins.allow` را تنظیم می‌کند، پیش از فعال‌سازی، `clawrouter` را به آن فهرست
    اضافه کنید. برای یک استقرار سفارشی، `models.providers.clawrouter.baseUrl` را
    روی مبدأ ClawRouter تنظیم کنید؛ مقدار پیش‌فرض `https://clawrouter.openclaw.ai`
    است.

  </Step>
  <Step title="فهرست‌کردن مدل‌های اعطاشده">
    ```bash
    openclaw models list --all --provider clawrouter
    ```

    ارجاع‌های مدل بازگردانده‌شده را دقیقاً همان‌طور که نمایش داده شده‌اند استفاده کنید.
    آن‌ها فضای نام بالادستی را حفظ می‌کنند، مانند
    `clawrouter/openai/gpt-5.5`،
    `clawrouter/anthropic/claude-sonnet-4-6` یا
    `clawrouter/google/gemini-3.5-flash`. اگر `agents.defaults.models` در
    پیکربندی شما یک فهرست مجاز است، هر ارجاع انتخاب‌شدهٔ ClawRouter را به آن
    اضافه کنید.

  </Step>
  <Step title="انتخاب مدل">
    ```bash
    openclaw models set clawrouter/<provider>/<model>
    ```

    همچنین می‌توانید یک مدل بازگردانده‌شده را برای یک اجرای منفرد با
    `openclaw agent --model clawrouter/<provider>/<model> --message "..."`
    انتخاب کنید.

  </Step>
</Steps>

## استقرار مدیریت‌شدهٔ غیرتعاملی

کلید پراکسی را در سازوکار تزریق اطلاعات محرمانهٔ بار کاری نگه دارید و در
`openclaw.json` فقط یک SecretRef ذخیره کنید. فیلدهای متعارف مدیریت‌شده عبارت‌اند از:

| هدف                | فیلد پیکربندی یا محیطی                                                    |
| ------------------ | ------------------------------------------------------------------------- |
| مبدأ مسیریاب       | `models.providers.clawrouter.baseUrl`                                     |
| اعتبارنامه         | `models.providers.clawrouter.apiKey` -> SecretRef محیطی                   |
| مقدار محرمانه      | `CLAWROUTER_API_KEY` در محیط فرایند Gateway                               |
| مدل پیش‌فرض        | `agents.defaults.model.primary` -> `clawrouter/<provider>/<model>`        |
| برچسب بار کاری     | `models.providers.clawrouter.headers.X-ClawRouter-Project-Id` (اختیاری)  |

برای نمونه، یک کنترل‌کنندهٔ استقرار می‌تواند مالک این وصلهٔ JSON5 باشد:

```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` را اضافه کنید. بدون جادوگر تعاملی اعتبارسنجی و اعمال کنید:

```bash
openclaw config patch --file ./clawrouter.patch.json5 --dry-run --json
openclaw config patch --file ./clawrouter.patch.json5
```

اجرای آزمایشی SecretRef را تفکیک می‌کند، اما هرگز مقدار آن را چاپ نمی‌کند. برای
چرخش اعتبارنامه، Secret خارجی تأمین‌کنندهٔ `CLAWROUTER_API_KEY` را به‌روزرسانی
کنید و بار کاری Gateway را مجدداً راه‌اندازی کنید تا محیط فرایند جدید بارگذاری شود.
فایل پیکربندی و ارجاع مدل تغییر نمی‌کنند.

برای یک Gateway مستقل Docker که از منبع ساخته شده است، ClawRouter از قبل در
محیط اجرای ریشه گنجانده شده است. فقط Plugin کانالی را انتخاب کنید که به بسته‌بندی
جداگانه نیاز دارد، مانند `OPENCLAW_EXTENSIONS=clickclack`، `slack` یا `msteams`؛
به [تصاویر ساخته‌شده از منبع با Pluginهای منتخب](/fa/install/docker#source-built-images-with-selected-plugins)
مراجعه کنید. استقرارهای آرشیوی/دستگاهی باید همان منبع ادغام‌شده را از طریق خط
لولهٔ مصنوعات خود بسته‌بندی کنند، نه اینکه تصویر OCI را مصرف کنند.

## آمادگی و اثبات زنده

این بررسی‌ها مرزهای متفاوتی را اثبات می‌کنند؛ یکی را جایگزین دیگری نکنید:

```bash
# فقط سلامت فرایند 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 را بررسی کنید.
ابزارهای تشخیصی موجودِ انتقال مدل که فقط فراداده ثبت می‌کنند، خط‌هایی با شکل زیر
تولید می‌کنند:

```text
[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 احراز هویت همهٔ
شرکت‌های بالادستی را نصب کنید.

| قابلیت / مسیر فهرست                                      | انتقال OpenClaw       |
| -------------------------------------------------------- | --------------------- |
| `llm.responses` (ارائه‌دهندهٔ سازگار با OpenAI)          | `openai-responses`    |
| `llm.chat` (ارائه‌دهندهٔ سازگار با OpenAI)               | `openai-completions`  |
| `llm.messages` + مسیر `anthropic.messages`               | `anthropic-messages`  |
| `llm.stream` + مسیر پخش جریانی `google.generate_content` | `google-generative-ai` |

این Plugin سیاست‌های بازپخش و طرح‌وارهٔ ابزار منطبق را نیز برای این خانواده‌ها
اعمال می‌کند (سازگاری طرح‌وارهٔ ابزار OpenAI/DeepSeek/Gemini؛ سیاست‌های بازپخش
بومی Anthropic و Google Gemini). ارائه‌دهنده‌ای در فهرست که فقط قالب درخواست
پشتیبانی‌نشده‌ای ارائه می‌کند، عمداً به‌عنوان مدل متنی OpenClaw معرفی نمی‌شود.
به‌جای ارسال بار دادهٔ ناسازگار، آن ارائه‌دهندگان را در ClawRouter به یکی از
قراردادهای پشتیبانی‌شده نرمال‌سازی کنید.

## سهمیه‌ها و مصرف

پاسخ `/v1/usage` در ClawRouter بخش‌های عادی مصرف ارائه‌دهنده در OpenClaw را
تغذیه می‌کند: مجموع درخواست‌ها، توکن‌ها و هزینه، به‌علاوهٔ یک بازهٔ بودجهٔ ماهانه
هنگامی که کلید دارای محدودیت باشد. کلیدهای بدون اندازه‌گیری همچنان مصرف تجمیعی
را بدون بازهٔ درصدی نمایش می‌دهند.

جست‌وجوی سهمیه از همان کلید محدودشدهٔ کشف مدل استفاده می‌کند. شکست در جست‌وجوی
سهمیه، اجرای مدل را مسدود نمی‌کند.

نمای زنده را با این فرمان‌ها بررسی کنید:

```bash
openclaw status --usage
openclaw models status
```

همان نمای ارائه‌دهنده برای `/status` در گفت‌وگو و رابط مصرف OpenClaw نیز در
دسترس است. بودجه در سطح سیاست است، بنابراین درخواست‌های یک کارخواه دیگر که از
همان سیاست ClawRouter استفاده می‌کند می‌تواند درصد باقی‌مانده را تغییر دهد.

## عیب‌یابی

| نشانه                                    | بررسی                                                                                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| هیچ مدل ClawRouter وجود ندارد            | تأیید کنید Plugin فعال است و `plugins.allow` آن را مجاز می‌کند، سپس بررسی کنید اعتبارنامه فعال است و دست‌کم یک ارائه‌دهندهٔ آماده را مجاز می‌کند.       |
| یک مدل پیکربندی‌شدهٔ ClawRouter وجود ندارد | قابلیت و پشتیبانی مسیر آن را در `/v1/catalog` بررسی کنید. قراردادهای انتقال پشتیبانی‌نشده عمداً فیلتر می‌شوند.                                           |
| `Unknown model: clawrouter/...`          | وقتی نگاشت پیکربندی `agents.defaults.models` به‌عنوان فهرست مجاز استفاده می‌شود، ارجاع دقیق فهرست را به آن اضافه کنید.                                   |
| `401` یا `403` از فهرست یا مصرف          | اعتبارنامهٔ ClawRouter را دوباره صادر کنید یا دامنهٔ آن را تغییر دهید؛ OpenClaw به کلیدهای ارائه‌دهندهٔ بالادستی بازنمی‌گردد.                            |
| فراخوانی مدل پس از کشف شکست می‌خورد      | اتصال ارائه‌دهنده و سلامت بالادستی را در ClawRouter بررسی کنید، سپس پس از بازیابی وضعیت آمادگی آن دوباره تلاش کنید.                                      |
| مصرف دارای مجموع است اما درصد ندارد      | سیاست بدون اندازه‌گیری است؛ برای نمایش یک بازهٔ درصدی، در ClawRouter بودجهٔ ماهانه اضافه کنید.                                                          |

## رفتار امنیتی

- کشف کاتالوگ به کلید پراکسی پیکربندی‌شده محدود است و برای هر دامنهٔ اعتبارنامه (دایرکتوری عامل، دایرکتوری فضای کاری، شناسهٔ پروفایل احراز هویت و URL پایه) ذخیرهٔ موقت می‌شود.
- کلید پراکسی فقط هنگام ارسال درخواست پیوست می‌شود و در فرادادهٔ مدل ذخیره نمی‌شود.
- مقادیر انتساب خودکار و هم‌بستگی درخواست پیش از ارسال از فاصله‌های اضافی پاک می‌شوند و در صورت داشتن نویسه‌های کنترلی رد می‌شوند. مقادیر انتساب حداکثر ۲۵۶ نویسه و شناسه‌های درخواست حداکثر ۱۲۸ نویسه هستند.
- اطلاعات تشخیصی انتقال مدل فقط شامل فراداده است و هرگز کلید پراکسی یا محتوای مدل را دربر نمی‌گیرد.
- شناسه‌های مدل بومی Anthropic و Gemini فقط هنگام ارسال به شناسه‌های بالادستی آن‌ها بازنویسی می‌شوند.
- ردیف‌های پشتیبانی‌نشده یا فاقد مجوز کاتالوگ به‌صورت بسته رد می‌شوند و قابل انتخاب نیستند.

## مرتبط

<CardGroup cols={2}>
  <Card title="ارائه‌دهندگان مدل" href="/fa/concepts/model-providers" icon="layers">
    پیکربندی ارائه‌دهنده و انتخاب مدل.
  </Card>
  <Card title="رهگیری مصرف" href="/fa/concepts/usage-tracking" icon="chart-line">
    نماهای مصرف و وضعیت OpenClaw.
  </Card>
</CardGroup>