openclaw models

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

مرتبط:

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

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

openclaw models statusopenclaw models listopenclaw 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 فقط سلامت نمایه در ذخیره‌گاه احراز هویت را نشان می‌دهد.

گزینه‌ها:

ردیف‌های کاوش می‌توانند از نمایه‌های احراز هویت، اعتبارنامه‌های محیط یا 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 را ببینید.

فهرست

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).

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

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 به کاوش زنده نیاز دارند؛ نتایج اسکن صرفاً فراداده‌ای اطلاعاتی هستند و روی پیکربندی اعمال نمی‌شوند.

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

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> را به یک کلید استاندارد ارائه‌دهنده/مدل تفکیک می‌کند؛ بنابراین اختصاص نام مستعار به یک نام مستعار، به‌جای ایجاد زنجیره، آن را دوباره هدف‌گذاری می‌کند.

جایگزین‌ها

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 را با همان ساختار زیرفرمان مدیریت می‌کند.

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

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 login-github-copilotopenclaw 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 را اجرا کنید.

مثال‌ها:

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

نکته‌ها:

• 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
• انتخاب مدل
• جایگزینی مدل هنگام خرابی