openclaw models

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

مرتبط:

• ارائه‌دهندگان + مدل‌ها: مدل‌ها
• مفاهیم انتخاب مدل + فرمان اسلش /models: مفهوم مدل‌ها
• راه‌اندازی احراز هویت ارائه‌دهنده: شروع به کار

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

openclaw models statusopenclaw models listopenclaw models set <model-or-alias>openclaw models scan

openclaw models status پیش‌فرض/جایگزین‌های حل‌شده را همراه با نمای کلی احراز هویت نشان می‌دهد. وقتی نماهای لحظه‌ای استفاده از ارائه‌دهنده در دسترس باشند، بخش وضعیت OAuth/API-key شامل پنجره‌های استفاده ارائه‌دهنده و نماهای لحظه‌ای سهمیه است. ارائه‌دهندگان فعلی پنجره استفاده: Anthropic، GitHub Copilot، Gemini CLI، OpenAI، MiniMax، Xiaomi و z.ai. احراز هویت استفاده، در صورت وجود، از هوک‌های اختصاصی ارائه‌دهنده می‌آید؛ در غیر این صورت OpenClaw به اعتبارنامه‌های OAuth/API-key مطابق از پروفایل‌های احراز هویت، env یا پیکربندی بازمی‌گردد. در خروجی --json، auth.providers نمای کلی ارائه‌دهنده آگاه از env/config/store است، در حالی که auth.oauth فقط سلامت پروفایل auth-store است. برای اجرای پروب‌های زنده احراز هویت روی هر پروفایل ارائه‌دهنده پیکربندی‌شده، --probe را اضافه کنید. پروب‌ها درخواست‌های واقعی هستند (ممکن است توکن مصرف کنند و محدودیت نرخ را فعال کنند). برای بررسی وضعیت مدل/احراز هویت یک عامل پیکربندی‌شده، از --agent <id> استفاده کنید. وقتی حذف شود، فرمان اگر OPENCLAW_AGENT_DIR تنظیم شده باشد از آن استفاده می‌کند، وگرنه از عامل پیش‌فرض پیکربندی‌شده استفاده می‌کند. ردیف‌های پروب می‌توانند از پروفایل‌های احراز هویت، اعتبارنامه‌های env یا models.json بیایند. برای عیب‌یابی OAuth مربوط به OpenAI ChatGPT/Codex، openclaw models status، openclaw models auth list --provider openai و openclaw config get agents.defaults.model --json سریع‌ترین راه برای تایید این هستند که آیا یک عامل پروفایل OAuth قابل‌استفاده openai برای openai/* از طریق runtime بومی Codex دارد یا نه. راه‌اندازی ارائه‌دهنده OpenAI را ببینید.

نکات:

• models set <model-or-alias> مقدار provider/model یا یک alias را می‌پذیرد.
• models list فقط خواندنی است: پیکربندی، پروفایل‌های احراز هویت، وضعیت catalog موجود و ردیف‌های catalog متعلق به ارائه‌دهنده را می‌خواند، اما models.json را بازنویسی نمی‌کند.
• ستون Auth در سطح ارائه‌دهنده و فقط خواندنی است. این مقدار از فراداده پروفایل احراز هویت محلی، نشانگرهای env، کلیدهای ارائه‌دهنده پیکربندی‌شده، نشانگرهای ارائه‌دهنده محلی، نشانگرهای env/profile مربوط به AWS Bedrock و فراداده synthetic-auth مربوط به Plugin محاسبه می‌شود؛ runtime ارائه‌دهنده را بارگذاری نمی‌کند، secretهای keychain را نمی‌خواند، APIهای ارائه‌دهنده را فراخوانی نمی‌کند، یا آمادگی اجرای دقیق برای هر مدل را اثبات نمی‌کند.
• models list --all --provider <id> می‌تواند ردیف‌های catalog ایستای متعلق به ارائه‌دهنده را از manifestهای Plugin یا فراداده catalog ارائه‌دهنده bundled شامل کند، حتی وقتی هنوز با آن ارائه‌دهنده احراز هویت نکرده‌اید. آن ردیف‌ها تا زمانی که احراز هویت مطابق پیکربندی نشود همچنان به‌صورت در دسترس نبودن نمایش داده می‌شوند.
• models list هنگام کند بودن کشف catalog ارائه‌دهنده، control plane را پاسخ‌گو نگه می‌دارد. نماهای پیش‌فرض و پیکربندی‌شده پس از یک انتظار کوتاه به ردیف‌های مدل پیکربندی‌شده یا synthetic بازمی‌گردند و اجازه می‌دهند کشف در پس‌زمینه تمام شود. وقتی به catalog دقیق و کامل کشف‌شده نیاز دارید و مایلید منتظر کشف ارائه‌دهنده بمانید، از --all استفاده کنید.
• models list --all گسترده، ردیف‌های catalog manifest را روی ردیف‌های registry ادغام می‌کند بدون اینکه هوک‌های مکمل runtime ارائه‌دهنده را بارگذاری کند. مسیرهای سریع manifest فیلترشده بر اساس ارائه‌دهنده فقط از ارائه‌دهندگانی استفاده می‌کنند که با static علامت‌گذاری شده‌اند؛ ارائه‌دهندگانی که با refreshable علامت‌گذاری شده‌اند، registry/cache-backed می‌مانند و ردیف‌های manifest را به‌عنوان مکمل اضافه می‌کنند، در حالی که ارائه‌دهندگان علامت‌گذاری‌شده با runtime روی کشف registry/runtime می‌مانند.
• models list فراداده مدل بومی و سقف‌های runtime را جدا نگه می‌دارد. در خروجی جدول، وقتی سقف runtime موثر با پنجره context بومی فرق داشته باشد، Ctx مقدار contextTokens/contextWindow را نشان می‌دهد؛ ردیف‌های JSON وقتی ارائه‌دهنده آن سقف را افشا کند، contextTokens را شامل می‌شوند.
• models list --provider <id> بر اساس شناسه ارائه‌دهنده فیلتر می‌کند، مانند moonshot یا openai. این فرمان برچسب‌های نمایشی pickerهای تعاملی ارائه‌دهنده، مانند Moonshot AI، را نمی‌پذیرد.
• ارجاع‌های مدل با جدا کردن روی اولین / تجزیه می‌شوند. اگر شناسه مدل شامل / است (به سبک OpenRouter)، پیشوند ارائه‌دهنده را وارد کنید (مثال: openrouter/moonshotai/kimi-k2).
• اگر ارائه‌دهنده را حذف کنید، OpenClaw ابتدا ورودی را به‌عنوان alias حل می‌کند، سپس به‌عنوان تطابق یکتای ارائه‌دهنده پیکربندی‌شده برای همان شناسه دقیق مدل، و فقط بعد از آن با یک هشدار deprecation به ارائه‌دهنده پیش‌فرض پیکربندی‌شده بازمی‌گردد. اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش یک پیش‌فرض کهنه مربوط به ارائه‌دهنده حذف‌شده، به اولین ارائه‌دهنده/مدل پیکربندی‌شده بازمی‌گردد.
• models status ممکن است در خروجی احراز هویت برای placeholderهای غیرمحرمانه (برای مثال OPENAI_API_KEY، secretref-managed، minimax-oauth، oauth:chutes، ollama-local) مقدار marker(<value>) را نشان دهد، به‌جای اینکه آن‌ها را مانند secretها mask کند.

پویش مدل‌ها

models scan catalog عمومی :free مربوط به OpenRouter را می‌خواند و candidateها را برای استفاده به‌عنوان fallback رتبه‌بندی می‌کند. خود catalog عمومی است، بنابراین پویش‌های فقط فراداده به کلید OpenRouter نیاز ندارند.

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

گزینه‌ها:

• --no-probe (فقط فراداده؛ بدون lookup پیکربندی/secretها)
• --min-params <b>
• --max-age-days <days>
• --provider <name>
• --max-candidates <n>
• --timeout <ms> (درخواست catalog و timeout برای هر probe)
• --concurrency <n>
• --yes
• --no-input
• --set-default
• --set-image
• --json

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

وضعیت مدل‌ها

گزینه‌ها:

• --json
• --plain
• --check (exit 1=منقضی‌شده/مفقود، 2=در حال انقضا)
• --probe (پروب زنده پروفایل‌های احراز هویت پیکربندی‌شده)
• --probe-provider <name> (پروب یک ارائه‌دهنده)
• --probe-profile <id> (شناسه‌های پروفایل تکراری یا جداشده با کاما)
• --probe-timeout <ms>
• --probe-concurrency <n>
• --probe-max-tokens <n>
• --agent <id> (شناسه عامل پیکربندی‌شده؛ OPENCLAW_AGENT_DIR را override می‌کند)

--json stdout را برای payload JSON رزرو نگه می‌دارد. diagnostics مربوط به پروفایل احراز هویت، ارائه‌دهنده و startup به stderr هدایت می‌شوند تا اسکریپت‌ها بتوانند stdout را مستقیم به ابزارهایی مانند jq pipe کنند.

bucketهای وضعیت پروب:

• ok
• auth
• rate_limit
• billing
• timeout
• format
• unknown
• no_model

موارد detail/reason-code پروب که باید انتظار داشت:

• excluded_by_auth_order: یک پروفایل ذخیره‌شده وجود دارد، اما auth.order.<provider> صریح آن را حذف کرده است، بنابراین پروب به‌جای امتحان کردن آن، exclusion را گزارش می‌کند.
• missing_credential، invalid_expires، expired، unresolved_ref: پروفایل حاضر است اما eligible/resolvable نیست.
• no_model: احراز هویت ارائه‌دهنده وجود دارد، اما OpenClaw نتوانست یک candidate مدل قابل probe برای آن ارائه‌دهنده حل کند.

Aliasها + fallbackها

openclaw models aliases listopenclaw models fallbacks list

پروفایل‌های احراز هویت

openclaw models auth addopenclaw models auth list [--provider <id>] [--json]openclaw models auth login --provider <id>openclaw models auth login --provider openai --profile-id openai:workopenclaw models auth paste-api-key --provider <id>openclaw models auth setup-token --provider <id>openclaw models auth paste-token

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

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

models auth login جریان احراز هویت Plugin ارائه‌دهنده (OAuth/API key) را اجرا می‌کند. از openclaw plugins list استفاده کنید تا ببینید کدام ارائه‌دهندگان نصب شده‌اند. برای نوشتن نتایج احراز هویت در store یک عامل پیکربندی‌شده مشخص، از openclaw models auth --agent <id> <subcommand> استفاده کنید. flag والد --agent توسط add، list، login، paste-api-key، setup-token، paste-token و login-github-copilot رعایت می‌شود.

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

مثال‌ها:

openclaw models auth login --provider openai --set-defaultopenclaw models auth login --provider openai --method api-keyopenclaw models auth paste-api-key --provider openaiopenclaw models auth list --provider openai

نکات:

• login برای ارائه‌دهندگانی که در هنگام login از پروفایل‌های نام‌گذاری‌شده پشتیبانی می‌کنند، --profile-id <id> را می‌پذیرد. از این برای جدا نگه داشتن چند login برای یک ارائه‌دهنده استفاده کنید.
• paste-api-key کلیدهای API تولیدشده در جای دیگر را می‌پذیرد، مقدار کلید را prompt می‌کند، و آن را در شناسه پروفایل پیش‌فرض <provider>:manual می‌نویسد، مگر اینکه --profile-id را پاس دهید. در automation، کلید را روی stdin pipe کنید، برای مثال printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai.
• setup-token و paste-token به‌عنوان فرمان‌های generic token برای ارائه‌دهندگانی باقی می‌مانند که روش‌های احراز هویت token را افشا می‌کنند.
• setup-token به یک TTY تعاملی نیاز دارد و روش token-auth ارائه‌دهنده را اجرا می‌کند (وقتی آن ارائه‌دهنده روش setup-token را افشا کند، به‌صورت پیش‌فرض همان روش).
• paste-token یک رشته token تولیدشده در جای دیگر یا از automation را می‌پذیرد.
• paste-token به --provider نیاز دارد، به‌صورت پیش‌فرض مقدار token را prompt می‌کند، و آن را در شناسه پروفایل پیش‌فرض <provider>:manual می‌نویسد، مگر اینکه --profile-id را پاس دهید.
• در automation، به‌جای پاس دادن token به‌عنوان آرگومان، آن را روی stdin pipe کنید تا اعتبارنامه‌های ارائه‌دهنده در shell history یا process list ظاهر نشوند.
• paste-token --expires-in <duration> انقضای مطلق token را از یک مدت نسبی مانند 365d یا 12h ذخیره می‌کند.
• برای openai، کلیدهای API OpenAI و ماده token مربوط به ChatGPT/OAuth شکل‌های احراز هویت متفاوتی هستند. از paste-api-key برای کلیدهای API OpenAI با sk-... و از paste-token فقط برای ماده احراز هویت token استفاده کنید.
• نکته Anthropic: کارکنان Anthropic به ما گفته‌اند استفاده به سبک OpenClaw از Claude CLI دوباره مجاز است، بنابراین OpenClaw استفاده مجدد از Claude CLI و استفاده از claude -p را برای این integration مجاز تلقی می‌کند، مگر اینکه Anthropic سیاست جدیدی منتشر کند.
• setup-token / paste-token مربوط به Anthropic همچنان به‌عنوان یک مسیر token پشتیبانی‌شده OpenClaw در دسترس هستند، اما OpenClaw اکنون استفاده مجدد از Claude CLI و claude -p را، وقتی در دسترس باشد، ترجیح می‌دهد.

مرتبط

• مرجع CLI
• انتخاب مدل
• Failover مدل