---
read_when:
    - می‌خواهید مدل‌های پیش‌فرض را تغییر دهید یا وضعیت احراز هویت ارائه‌دهنده را مشاهده کنید
    - می‌خواهید مدل‌ها/ارائه‌دهندگان موجود را بررسی و پروفایل‌های احراز هویت را اشکال‌زدایی کنید
summary: مرجع CLI برای `openclaw models` (وضعیت/فهرست/تنظیم/پویش، نام‌های مستعار، گزینه‌های جایگزین، احراز هویت)
title: مدل‌ها
x-i18n:
    generated_at: "2026-07-16T15:50:28Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 330598225664ff961ab41bf6358226ad64eb43e941be7f422cfde0fe9d93cea8
    source_path: cli/models.md
    workflow: 16
---

# `openclaw models`

کشف، اسکن و پیکربندی مدل (مدل پیش‌فرض، جایگزین‌ها، نمایه‌های احراز هویت).

مرتبط:

- ارائه‌دهندگان + مدل‌ها: [مدل‌ها](/fa/providers/models)
- مفاهیم انتخاب مدل + فرمان اسلش `/models`: [مفهوم مدل‌ها](/fa/concepts/models)
- راه‌اندازی احراز هویت ارائه‌دهنده: [شروع به کار](/fa/start/getting-started)

## فرمان‌های رایج

```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models set-image <model-or-alias>
openclaw models scan
```

زیرفرمان‌های `status` و `auth` برای هدف‌گیری یک عامل پیکربندی‌شده، `--agent <id>` را می‌پذیرند؛ `list`، `scan`، `aliases` و `fallbacks`/`image-fallbacks` همیشه از عامل پیش‌فرض پیکربندی‌شده استفاده می‌کنند و `set`/`set-image` صراحتاً `--agent` را رد می‌کنند. در صورت حذف، فرمان‌های آگاه از `--agent`، اگر `OPENCLAW_AGENT_DIR` تنظیم شده باشد از آن و در غیر این صورت از عامل پیش‌فرض پیکربندی‌شده استفاده می‌کنند.

### وضعیت

`openclaw models status` پیش‌فرض/جایگزین‌های نهایی را به‌همراه نمایی کلی از احراز هویت نشان می‌دهد. هنگامی که تصویرهای لحظه‌ای مصرف ارائه‌دهنده در دسترس باشند، بخش وضعیت OAuth/کلید API شامل بازه‌های مصرف ارائه‌دهنده و تصویرهای لحظه‌ای سهمیه است. ارائه‌دهندگان فعلی بازه مصرف: Anthropic، GitHub Copilot، Gemini CLI، OpenAI، MiniMax، Xiaomi و z.ai. احراز هویت مصرف، در صورت وجود، از هوک‌های اختصاصی ارائه‌دهنده دریافت می‌شود؛ در غیر این صورت OpenClaw به اعتبارنامه‌های منطبق OAuth/کلید API از نمایه‌های احراز هویت، محیط یا پیکربندی متوسل می‌شود.

در خروجی `--json`، `auth.providers` نمای کلی ارائه‌دهنده با آگاهی از محیط/پیکربندی/ذخیره‌گاه است، درحالی‌که `auth.oauth` فقط سلامت نمایه در ذخیره‌گاه احراز هویت را نشان می‌دهد.

گزینه‌ها:

| پرچم                      | اثر                                                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `--json`                  | خروجی JSON؛ عیب‌یابی‌های نمایه احراز هویت، ارائه‌دهنده و راه‌اندازی به stderr می‌روند تا stdout برای انتقال به `jq` قابل استفاده بماند. |
| `--plain`                 | خروجی متن ساده.                                                                                            |
| `--check`                 | اگر احراز هویت در آستانه انقضا/منقضی باشد، با وضعیت غیرصفر خارج می‌شود: `1` = منقضی/مفقود، `2` = در آستانه انقضا.                             |
| `--probe`                 | کاوش زنده نمایه‌های احراز هویت پیکربندی‌شده. درخواست‌های واقعی؛ ممکن است توکن مصرف کند و محدودیت نرخ را فعال کند.            |
| `--probe-provider <name>` | فقط یک ارائه‌دهنده را کاوش می‌کند.                                                                                      |
| `--probe-profile <id>`    | شناسه‌های مشخص نمایه احراز هویت را کاوش می‌کند (تکراری یا جداشده با ویرگول).                                                  |
| `--probe-timeout <ms>`    | مهلت زمانی هر کاوش.                                                                                            |
| `--probe-concurrency <n>` | کاوش‌های هم‌زمان.                                                                                            |
| `--probe-max-tokens <n>`  | حداکثر توکن کاوش (در حد امکان).                                                                               |
| `--agent <id>`            | شناسه عامل پیکربندی‌شده؛ `OPENCLAW_AGENT_DIR` را لغو می‌کند.                                                          |

ردیف‌های کاوش می‌توانند از نمایه‌های احراز هویت، اعتبارنامه‌های محیط یا `models.json` بیایند. دسته‌های وضعیت کاوش: `ok`، `auth`، `rate_limit`، `billing`، `timeout`، `format`، `unknown`، `no_model`.

کدهای جزئیات/دلیل مورد انتظار هنگامی که یک کاوش هرگز به فراخوانی مدل نمی‌رسد:

- `excluded_by_auth_order`: یک نمایه ذخیره‌شده وجود دارد، اما `auth.order.<provider>` صریح آن را حذف کرده است؛ بنابراین کاوش به‌جای امتحان‌کردن آن، حذف را گزارش می‌کند.
- `missing_credential`، `invalid_expires`، `expired`، `unresolved_ref`: نمایه موجود است، اما واجد شرایط یا قابل تفکیک نیست.
- `ineligible_profile`: نمایه به دلیل دیگری با پیکربندی ارائه‌دهنده ناسازگار است.
- `no_model`: احراز هویت ارائه‌دهنده موجود است، اما OpenClaw نتوانست یک مدل نامزد قابل کاوش برای آن ارائه‌دهنده تفکیک کند.

برای عیب‌یابی OAuth مربوط به OpenAI ChatGPT/Codex، سریع‌ترین راه برای تأیید اینکه آیا یک عامل از طریق زمان اجرای بومی Codex دارای نمایه OAuth قابل استفاده `openai` برای `openai/*` است، `openclaw models status`، `openclaw models auth list --provider openai` و `openclaw config get agents.defaults.model --json` هستند. [راه‌اندازی ارائه‌دهنده OpenAI](/fa/providers/openai#check-and-recover-codex-oauth-routing) را ببینید.

### فهرست

`openclaw models list` فقط خواندنی است: پیکربندی، نمایه‌های احراز هویت، وضعیت کاتالوگ موجود و ردیف‌های کاتالوگ متعلق به ارائه‌دهنده را می‌خواند، اما هرگز `models.json` را بازنویسی نمی‌کند.

گزینه‌ها: `--all` (کاتالوگ کامل)، `--local` (فیلتر به مدل‌های محلی)، `--provider <id>`، `--json`، `--plain`.

نکات:

- ستون `Auth` فقط خواندنی است. برای مسیرهای مدل متعلق به ارائه‌دهنده، مانند OpenAI، مسیر API/نشانی پایه هر ردیف را با نمایه‌های واجد شرایط در `auth.order` مؤثر، اعتبارنامه‌های محیط/پیکربندی و SecretRefهای تفکیک‌شده در دامنه فرمان تطبیق می‌دهد. هنگامی که سیاست مسیر یک ردیف مشخص OpenAI در دسترس نباشد، آن ردیف به‌جای قرض‌گرفتن احراز هویت سطح ارائه‌دهنده ناشناخته باقی می‌ماند؛ بررسی‌های قدیمی صرفاً ارائه‌دهنده‌ای و سایر ارائه‌دهندگان، رفتار سطح ارائه‌دهنده را حفظ می‌کنند. فراداده احراز هویت مصنوعی Plugin فقط نشانه‌ای از قابلیت زمان اجرا است، نه مدرکی برای احراز هویت بومی حساب؛ بنابراین مسیرهای وابسته به حساب بدون شواهد مثبت رجیستری ناشناخته باقی می‌مانند. این فرمان زمان اجرای ارائه‌دهنده را بارگیری نمی‌کند، اسرار زنجیره‌کلید را نمی‌خواند، APIهای ارائه‌دهنده را فراخوانی نمی‌کند و آمادگی دقیق اجرا را اثبات نمی‌کند.
- `models list --all --provider <id>` می‌تواند ردیف‌های کاتالوگ ایستای متعلق به ارائه‌دهنده را از مانیفست‌های Plugin یا فراداده کاتالوگ ارائه‌دهنده همراه داشته باشد، حتی اگر هنوز نزد آن ارائه‌دهنده احراز هویت نکرده باشید. تا زمانی که احراز هویت منطبق پیکربندی نشود، آن ردیف‌ها همچنان به‌صورت در دسترس نیستند نمایش داده می‌شوند.
- `models list` هنگامی که کشف کاتالوگ ارائه‌دهنده کند است، صفحه کنترل را پاسخ‌گو نگه می‌دارد. نماهای پیش‌فرض و پیکربندی‌شده پس از انتظاری کوتاه به ردیف‌های مدل پیکربندی‌شده یا مصنوعی متوسل می‌شوند و اجازه می‌دهند کشف در پس‌زمینه تمام شود. هنگامی که به کاتالوگ کامل و دقیق کشف‌شده نیاز دارید و مایلید برای کشف ارائه‌دهنده منتظر بمانید، از `--all` استفاده کنید.
- `models list --all` گسترده، بدون بارگیری هوک‌های تکمیلی زمان اجرای ارائه‌دهنده، ردیف‌های کاتالوگ مانیفست را روی ردیف‌های رجیستری ادغام می‌کند. مسیرهای سریع مانیفست فیلترشده بر اساس ارائه‌دهنده فقط از ارائه‌دهندگانی استفاده می‌کنند که با `static` علامت‌گذاری شده‌اند؛ ارائه‌دهندگان علامت‌گذاری‌شده با `refreshable` متکی به رجیستری/حافظه نهان می‌مانند و ردیف‌های مانیفست را به‌عنوان مکمل اضافه می‌کنند، درحالی‌که ارائه‌دهندگان علامت‌گذاری‌شده با `runtime` بر کشف رجیستری/زمان اجرا باقی می‌مانند.
- `models list` فراداده بومی مدل و سقف‌های زمان اجرا را متمایز نگه می‌دارد. در خروجی جدول، هنگامی که یک سقف مؤثر زمان اجرا با پنجره زمینه بومی تفاوت دارد، `Ctx` مقدار `contextTokens/contextWindow` را نشان می‌دهد؛ اگر ارائه‌دهنده آن سقف را ارائه کند، ردیف‌های JSON شامل `contextTokens` هستند.
- برای مسیرهای متعلق به ارائه‌دهنده، `models list` یک ردیف منطقی ارائه‌دهنده/مدل را روی مسیر انتخاب‌شده نگاشت می‌کند. `Input` و `Ctx` فقط از یک ردیف کاتالوگ مسیر فیزیکی دقیق می‌آیند و لغوهای منطقی صریح پیکربندی‌شده در آخر اعمال می‌شوند؛ انتخاب مسیر تفکیک‌نشده به‌جای قرض‌گرفتن فراداده مسیر هم‌خانواده، فیلدهای قابلیت را ناشناخته نشان می‌دهد.
- `models list --provider <id>` بر اساس شناسه ارائه‌دهنده، مانند `moonshot` یا `openai`، فیلتر می‌کند. برچسب‌های نمایشی انتخاب‌گرهای تعاملی ارائه‌دهنده، مانند `Moonshot AI`، را نمی‌پذیرد.
- ارجاع‌های مدل با تقسیم بر اساس **اولین** `/` تجزیه می‌شوند. اگر شناسه مدل شامل `/` باشد (به سبک OpenRouter)، پیشوند ارائه‌دهنده را درج کنید (مثال: `openrouter/moonshotai/kimi-k2`).
- اگر ارائه‌دهنده را حذف کنید، OpenClaw ابتدا ورودی را به‌عنوان نام مستعار، سپس به‌عنوان تطبیق منحصربه‌فرد ارائه‌دهنده پیکربندی‌شده برای همان شناسه دقیق مدل تفکیک می‌کند و تنها پس از آن با هشدار منسوخ‌شدن به ارائه‌دهنده پیش‌فرض پیکربندی‌شده متوسل می‌شود. اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش یک پیش‌فرض منسوخ مربوط به ارائه‌دهنده حذف‌شده، به اولین ارائه‌دهنده/مدل پیکربندی‌شده متوسل می‌شود.
- `models status` ممکن است در خروجی احراز هویت، به‌جای پوشاندن جای‌نگهدارهای غیرمحرمانه به‌عنوان اسرار، `marker(<value>)` را برای آن‌ها نشان دهد (برای مثال `OPENAI_API_KEY`، `secretref-managed`، `minimax-oauth`، `oauth:chutes`، `ollama-local`).

### تنظیم مدل پیش‌فرض / تصویر

```bash
openclaw models set <model-or-alias>
openclaw models set-image <model-or-alias>
```

`set` در `agents.defaults.model.primary` می‌نویسد؛ `set-image` در `agents.defaults.imageModel.primary` می‌نویسد. هر دو `provider/model` یا یک نام مستعار پیکربندی‌شده را می‌پذیرند. همچنین، هنگامی که مدل تازه انتخاب‌شده به نصب Plugin زمان اجرای Codex/Copilot نیاز دارد، `set` آن را ترمیم می‌کند؛ `set-image` چنین نمی‌کند. هیچ‌یک از فرمان‌ها `--agent` را نمی‌پذیرند؛ آن‌ها همیشه در پیش‌فرض‌های عامل می‌نویسند.

### اسکن

`models scan` کاتالوگ عمومی `:free` متعلق به OpenRouter را می‌خواند و نامزدها را برای استفاده به‌عنوان جایگزین رتبه‌بندی می‌کند. خود کاتالوگ عمومی است، بنابراین اسکن‌های صرفاً فراداده‌ای به کلید OpenRouter نیاز ندارند.

OpenClaw به‌طور پیش‌فرض تلاش می‌کند پشتیبانی از ابزار و تصویر را با فراخوانی‌های زنده مدل کاوش کند. اگر هیچ کلید OpenRouter پیکربندی نشده باشد، فرمان به خروجی صرفاً فراداده‌ای متوسل می‌شود و توضیح می‌دهد که مدل‌های `:free` همچنان برای کاوش و استنتاج به `OPENROUTER_API_KEY` نیاز دارند.

گزینه‌ها:

- `--no-probe` (فقط فراداده؛ بدون جست‌وجوی پیکربندی/اسرار)
- `--min-params <b>`
- `--max-age-days <days>`
- `--provider <name>`
- `--max-candidates <n>`
- `--timeout <ms>` (مهلت زمانی درخواست کاتالوگ و هر کاوش)
- `--concurrency <n>`
- `--yes`
- `--no-input`
- `--set-default`
- `--set-image`
- `--json`

`--set-default` و `--set-image` به کاوش زنده نیاز دارند؛ نتایج اسکن صرفاً فراداده‌ای اطلاعاتی هستند و روی پیکربندی اعمال نمی‌شوند.

## نام‌های مستعار

```bash
openclaw models aliases list [--json] [--plain]
openclaw models aliases add <alias> <model-or-alias>
openclaw models aliases remove <alias>
```

نام‌های مستعار برای هر ورودی مدل به‌صورت `agents.defaults.models.<key>.alias` ذخیره می‌شوند. `add` ابتدا `<model-or-alias>` را به یک کلید استاندارد ارائه‌دهنده/مدل تفکیک می‌کند؛ بنابراین اختصاص نام مستعار به یک نام مستعار، به‌جای ایجاد زنجیره، آن را دوباره هدف‌گذاری می‌کند.

## جایگزین‌ها

```bash
openclaw models fallbacks list [--json] [--plain]
openclaw models fallbacks add <model-or-alias>
openclaw models fallbacks remove <model-or-alias>
openclaw models fallbacks clear
```

`agents.defaults.model.fallbacks` را مدیریت می‌کند. `openclaw models image-fallbacks list|add|remove|clear` فهرست موازی `agents.defaults.imageModel.fallbacks` را با همان ساختار زیرفرمان مدیریت می‌کند.

## نمایه‌های احراز هویت

```bash
openclaw models auth add
openclaw models auth list [--provider <id>] [--json]
openclaw models auth login --provider <id>
openclaw models auth login --provider openai --profile-id openai:work
openclaw models auth login-github-copilot
openclaw models auth paste-api-key --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token --provider <id>
openclaw models auth order get --provider <id>
openclaw models auth order set --provider <id> <profileIds...>
openclaw models auth order clear --provider <id>
```

`models auth add` راهنمای تعاملی احراز هویت است. بسته به ارائه‌دهنده‌ای که انتخاب می‌کنید، می‌تواند جریان احراز هویت ارائه‌دهنده (OAuth/کلید API) را اجرا کند یا شما را برای چسباندن دستی توکن راهنمایی کند.

`models auth list` پروفایل‌های احراز هویت ذخیره‌شده برای عامل انتخاب‌شده را بدون چاپ توکن، کلید API یا اطلاعات محرمانه OAuth فهرست می‌کند. از `--provider <id>` برای محدودکردن نتایج به یک ارائه‌دهنده، مانند `openai`، و از `--json` برای اسکریپت‌نویسی استفاده کنید.

`models auth login` جریان احراز هویت Plugin ارائه‌دهنده (OAuth/کلید API) را اجرا می‌کند. برای مشاهده ارائه‌دهندگان نصب‌شده از `openclaw plugins list` استفاده کنید. `login` گزینهٔ `--profile-id <id>` را برای ارائه‌دهندگانی می‌پذیرد که هنگام ورود از پروفایل‌های نام‌گذاری‌شده پشتیبانی می‌کنند (از این گزینه برای جدا نگه‌داشتن چند ورود به یک ارائه‌دهنده استفاده کنید)، گزینهٔ `--method <id>` را برای انتخاب یک روش احراز هویت مشخص، گزینهٔ `--device-code` را به‌عنوان میان‌بری برای `--method device-code`، گزینهٔ `--set-default` را برای اعمال مدل پیش‌فرض توصیه‌شدهٔ ارائه‌دهنده، و گزینهٔ `--force` را برای حذف اولیهٔ پروفایل‌های موجود آن ارائه‌دهنده می‌پذیرد (وقتی یک پروفایل OAuth ذخیره‌شده در حافظهٔ نهان گیر کرده است یا می‌خواهید حساب را تغییر دهید، از این گزینه استفاده کنید).

`models auth login-github-copilot` میان‌بری برای `models auth login --provider github-copilot --method device` (جریان دستگاه GitHub) است؛ این دستور `--yes` را برای بازنویسی یک پروفایل موجود بدون نمایش درخواست تأیید می‌پذیرد.

برای نوشتن نتایج احراز هویت در مخزن یک عامل پیکربندی‌شدهٔ مشخص، از `openclaw models auth --agent <id> <subcommand>` استفاده کنید. پرچم والد `--agent` توسط `add`، `list`، `login`، `paste-api-key`، `setup-token`، `paste-token`، `login-github-copilot` و `order get`/`set`/`clear` رعایت می‌شود.

برای مدل‌های OpenAI، `--provider openai` به‌طور پیش‌فرض از ورود با حساب ChatGPT/Codex استفاده می‌کند. فقط زمانی از `--method api-key` استفاده کنید که می‌خواهید یک پروفایل کلید API متعلق به OpenAI اضافه کنید؛ معمولاً به‌عنوان پشتیبان برای محدودیت‌های اشتراک Codex. برای انتقال وضعیت قدیمی و منسوخ احراز هویت/پروفایل با پیشوند OpenAI Codex به `openai`، دستور `openclaw doctor --fix` را اجرا کنید.

مثال‌ها:

```bash
openclaw models auth login --provider openai --set-default
openclaw models auth login --provider openai --method api-key
openclaw models auth paste-api-key --provider openai
openclaw models auth list --provider openai
```

نکته‌ها:

- `paste-api-key` کلیدهای API تولیدشده در جای دیگر را می‌پذیرد، مقدار کلید را درخواست می‌کند و آن را در شناسهٔ پروفایل پیش‌فرض `<provider>:manual` می‌نویسد، مگر اینکه `--profile-id` را ارسال کنید. در خودکارسازی، کلید را از طریق ورودی استاندارد ارسال کنید؛ برای مثال `printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai`.
- `setup-token` و `paste-token` برای ارائه‌دهندگانی که روش‌های احراز هویت با توکن ارائه می‌کنند، همچنان دستورهای عمومی توکن هستند.
- `setup-token` به یک TTY تعاملی نیاز دارد و روش احراز هویت با توکن ارائه‌دهنده را اجرا می‌کند (اگر آن ارائه‌دهنده روش `setup-token` را ارائه کند، به‌طور پیش‌فرض از همان استفاده می‌شود).
- `paste-token` به `--provider` نیاز دارد، به‌طور پیش‌فرض مقدار توکن را درخواست می‌کند و آن را در شناسهٔ پروفایل پیش‌فرض `<provider>:manual` می‌نویسد، مگر اینکه `--profile-id` را ارسال کنید. در خودکارسازی، به‌جای ارسال توکن به‌عنوان آرگومان، آن را از طریق ورودی استاندارد ارسال کنید تا اطلاعات اعتبارنامهٔ ارائه‌دهنده در تاریخچهٔ پوسته یا فهرست فرایندها ظاهر نشود.
- `paste-token --expires-in <duration>` زمان انقضای مطلق توکن را بر اساس یک مدت نسبی مانند `365d` یا `12h` ذخیره می‌کند.
- برای `openai`، کلیدهای API متعلق به OpenAI و اطلاعات توکن ChatGPT/OAuth ساختارهای احراز هویت متفاوتی دارند. برای کلیدهای API متعلق به `sk-...` OpenAI از `paste-api-key` و فقط برای اطلاعات احراز هویت با توکن از `paste-token` استفاده کنید.
- Anthropic:‏ `setup-token`/`paste-token` مسیرهای احراز هویت پشتیبانی‌شدهٔ OpenClaw برای `anthropic` هستند، اما OpenClaw ترجیح می‌دهد در صورت دردسترس‌بودن Claude CLI ‏(`claude -p`) روی میزبان، از آن دوباره استفاده کند.
- `auth order get/set/clear` جایگزینی ترتیب پروفایل‌های احراز هویت مختص هر عامل را برای یک ارائه‌دهنده مدیریت می‌کند که در `auth-state.json` ذخیره می‌شود (جدا از کلید پیکربندی `auth.order.<provider>`). ‏`set` یک یا چند شناسهٔ پروفایل را به‌ترتیب اولویت می‌پذیرد؛ `clear` به ترتیب پیکربندی/نوبت‌گردشی بازمی‌گردد.

## مرتبط

- [مرجع CLI](/fa/cli)
- [انتخاب مدل](/fa/concepts/model-providers)
- [جایگزینی مدل هنگام خرابی](/fa/concepts/model-failover)