---
read_when:
    - برای چندین ارائه‌دهنده مدل، یک کلید مدیریت‌شده می‌خواهید
    - به کشف مدل یا گزارش سهمیهٔ ClawRouter در OpenClaw نیاز دارید
summary: مدل‌های محدودشده به اعتبارنامه را از طریق ClawRouter مسیریابی کنید و سهمیه‌های مدیریت‌شده را نمایش دهید
title: ClawRouter
x-i18n:
    generated_at: "2026-07-27T16:58:06Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 929a93e8d1d003e21f792d0fdab9542553ffab374f59d4d0505819b0f719591f
    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.modelPolicy.allow`
    پیکربندی شده است، هر ارجاع انتخاب‌شدهٔ ClawRouter را به آن اضافه کنید.

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

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

  </Step>
</Steps>

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

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

| هدف       | فیلد پیکربندی یا محیط                                              |
| ------------- | ------------------------------------------------------------------------ |
| مبدأ مسیریاب | `models.providers.clawrouter.baseUrl`                                    |
| اعتبارنامه    | `models.providers.clawrouter.apiKey` -> env 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 "دقیقاً پاسخ دهید: CLAWROUTER_CANARY_OK" \
  --json
```

به‌جای کپی‌کردن کورکورانهٔ مدل نمونه، از مدلی استفاده کنید که کاتالوگ دارای دامنه بازگردانده است.
پاسخ موفق `/readyz` یعنی Gateway می‌تواند
درخواست‌ها را سرویس دهد؛ این به‌معنای آماده‌بودن ClawRouter، اعتبارنامهٔ آن یا یک
ارائه‌دهندهٔ بالادستی نیست. کاوش مدل و نمونهٔ کنترل عامل، اثبات‌های استنتاج هستند.

برای عیب‌یابی زنده، نمونهٔ کنترل را اجرا و گزارش‌های استاندارد Gateway را بررسی کنید.
تشخیص‌های موجود و صرفاً مبتنی بر فرادادهٔ انتقال مدل، خط‌هایی با این شکل تولید می‌کنند:

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

| قابلیت / مسیر کاتالوگ                               | انتقال 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/Perplexity؛ سیاست‌های بازپخش بومی
Anthropic و Google Gemini). مدل‌های Perplexity بازنویسی سخت‌گیرانهٔ
طرح‌واره دریافت می‌کنند: `patternProperties` و `additionalProperties` حذف می‌شوند و
هر طرح‌وارهٔ شیء `properties` را اعلام می‌کند، زیرا Perplexity طرح‌واره‌های ابزار
فاقد آن‌ها را رد می‌کند. ارائه‌دهندهٔ کاتالوگی که فقط یک
قالب درخواست پشتیبانی‌نشده ارائه می‌کند، عمداً به‌عنوان مدل متنی OpenClaw
معرفی نمی‌شود. به‌جای ارسال محمولهٔ ناسازگار، آن ارائه‌دهندگان را در
ClawRouter با یکی از قراردادهای پشتیبانی‌شده نرمال‌سازی کنید.

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

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

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

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

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

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

## عیب‌یابی

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

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

- کشف کاتالوگ به کلید پروکسی پیکربندی‌شده محدود است و برای هر محدوده اعتبارنامه (دایرکتوری عامل، دایرکتوری فضای کاری، شناسه پروفایل احراز هویت و نشانی URL پایه) در حافظه نهان ذخیره می‌شود.
- کلید پروکسی فقط هنگام ارسال درخواست پیوست می‌شود؛ این کلید در فراداده مدل ذخیره نمی‌شود.
- مقادیر انتساب خودکار و هم‌بستگی درخواست پیش از ارسال کوتاه‌سازی می‌شوند و در صورت وجود نویسه‌های کنترلی رد می‌شوند. مقادیر انتساب به 256 نویسه و شناسه‌های درخواست به 128 نویسه محدود هستند.
- اطلاعات تشخیصی انتقال مدل فقط شامل فراداده است و هرگز کلید پروکسی یا محتوای مدل را در بر نمی‌گیرد.
- شناسه‌های مدل بومی 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>