Concepts and configuration

CLI مدل‌ها

Edit source

Model failover

چرخش پروفایل احراز هویت، دوره‌های سردشدن، و نحوهٔ تعامل آن با جایگزین‌ها.

Model providers

مرور سریع ارائه‌دهنده‌ها و نمونه‌ها.

Agent runtimes

PI، Codex، و دیگر runtimeهای حلقهٔ عامل.

Configuration reference

کلیدهای پیکربندی مدل.

ارجاع‌های مدل یک ارائه‌دهنده و مدل را انتخاب می‌کنند. آن‌ها معمولاً runtime سطح‌پایین عامل را انتخاب نمی‌کنند. ارجاع‌های عامل OpenAI استثنای اصلی هستند: openai/gpt-5.5 به‌طور پیش‌فرض روی ارائه‌دهندهٔ رسمی OpenAI از طریق runtime سرور برنامهٔ Codex اجرا می‌شود. بازنویسی‌های صریح runtime باید در سیاست ارائه‌دهنده/مدل قرار بگیرند، نه روی کل عامل یا نشست. در حالت runtime مربوط به Codex، ارجاع openai/gpt-* به معنی پرداخت با کلید API نیست؛ احراز هویت می‌تواند از یک حساب Codex یا پروفایل احراز هویت openai-codex بیاید. runtimeهای عامل را ببینید.

نحوهٔ کار انتخاب مدل

OpenClaw مدل‌ها را به این ترتیب انتخاب می‌کند:

Primary model

agents.defaults.model.primary (یا agents.defaults.model).

Fallbacks

agents.defaults.model.fallbacks (به‌ترتیب).

Provider auth failover

پیش از رفتن به مدل بعدی، failover احراز هویت داخل یک ارائه‌دهنده انجام می‌شود.

Related model surfaces

agents.defaults.models فهرست مجاز/کاتالوگ مدل‌هایی است که OpenClaw می‌تواند استفاده کند (به‌همراه aliasها). برای محدودکردن ارائه‌دهنده‌های قابل مشاهده و در عین حال پویا نگه‌داشتن کشف ارائه‌دهنده، از ورودی‌های provider/* استفاده کنید.
agents.defaults.imageModel فقط زمانی استفاده می‌شود که مدل اصلی نتواند تصویر بپذیرد.
agents.defaults.pdfModel توسط ابزار pdf استفاده می‌شود. اگر حذف شود، ابزار ابتدا به agents.defaults.imageModel و سپس به مدل پیش‌فرض/نشست resolveشده fallback می‌کند.
agents.defaults.imageGenerationModel توسط قابلیت مشترک تولید تصویر استفاده می‌شود. اگر حذف شود، image_generate همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده با پشتوانهٔ احراز هویت را استنتاج کند. ابتدا ارائه‌دهندهٔ پیش‌فرض فعلی را امتحان می‌کند، سپس ارائه‌دهنده‌های ثبت‌شدهٔ باقی‌ماندهٔ تولید تصویر را به‌ترتیب شناسهٔ ارائه‌دهنده امتحان می‌کند. اگر یک ارائه‌دهنده/مدل مشخص تنظیم می‌کنید، احراز هویت/کلید API همان ارائه‌دهنده را هم پیکربندی کنید.
agents.defaults.musicGenerationModel توسط قابلیت مشترک تولید موسیقی استفاده می‌شود. اگر حذف شود، music_generate همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده با پشتوانهٔ احراز هویت را استنتاج کند. ابتدا ارائه‌دهندهٔ پیش‌فرض فعلی را امتحان می‌کند، سپس ارائه‌دهنده‌های ثبت‌شدهٔ باقی‌ماندهٔ تولید موسیقی را به‌ترتیب شناسهٔ ارائه‌دهنده امتحان می‌کند. اگر یک ارائه‌دهنده/مدل مشخص تنظیم می‌کنید، احراز هویت/کلید API همان ارائه‌دهنده را هم پیکربندی کنید.
agents.defaults.videoGenerationModel توسط قابلیت مشترک تولید ویدئو استفاده می‌شود. اگر حذف شود، video_generate همچنان می‌تواند یک پیش‌فرض ارائه‌دهنده با پشتوانهٔ احراز هویت را استنتاج کند. ابتدا ارائه‌دهندهٔ پیش‌فرض فعلی را امتحان می‌کند، سپس ارائه‌دهنده‌های ثبت‌شدهٔ باقی‌ماندهٔ تولید ویدئو را به‌ترتیب شناسهٔ ارائه‌دهنده امتحان می‌کند. اگر یک ارائه‌دهنده/مدل مشخص تنظیم می‌کنید، احراز هویت/کلید API همان ارائه‌دهنده را هم پیکربندی کنید.
پیش‌فرض‌های هر عامل می‌توانند agents.defaults.model را از طریق agents.list[].model به‌همراه bindingها بازنویسی کنند (مسیریابی چندعاملی را ببینید).

منبع انتخاب و رفتار fallback

همان provider/model بسته به این‌که از کجا آمده باشد می‌تواند معنی‌های متفاوتی داشته باشد:

پیش‌فرض‌های پیکربندی‌شده (agents.defaults.model.primary و primaryهای مخصوص عامل) نقطهٔ شروع عادی هستند و از agents.defaults.model.fallbacks استفاده می‌کنند.
انتخاب‌های fallback خودکار، وضعیت بازیابی موقت هستند. آن‌ها با modelOverrideSource: "auto" ذخیره می‌شوند تا نوبت‌های بعدی بتوانند بدون آزمودن یک primary خرابِ شناخته‌شده، همچنان از زنجیرهٔ fallback استفاده کنند.
انتخاب‌های نشست کاربر دقیق هستند. /model، انتخاب‌گر مدل، session_status(model=...)، و sessions.patch مقدار modelOverrideSource: "user" را ذخیره می‌کنند؛ اگر آن ارائه‌دهنده/مدل انتخاب‌شده در دسترس نباشد، OpenClaw به‌جای افتادن روی مدل پیکربندی‌شدهٔ دیگر، خطا را آشکارا نشان می‌دهد.
Cron --model / payload model یک primary در سطح هر job است. همچنان از fallbackهای پیکربندی‌شده استفاده می‌کند، مگر اینکه job مقدار payload صریح fallbacks ارائه کند (برای اجرای سخت‌گیرانهٔ cron از fallbacks: [] استفاده کنید).
مدل پیش‌فرض CLI و انتخاب‌گرهای allowlist به models.mode: "replace" احترام می‌گذارند و به‌جای بارگذاری کل کاتالوگ داخلی، models.providers.*.models صریح را فهرست می‌کنند.
انتخاب‌گر مدل در رابط Control از Gateway نمای مدل پیکربندی‌شده‌اش را می‌خواهد: در صورت وجود، agents.defaults.models، شامل ورودی‌های سراسری ارائه‌دهنده مانند provider/*؛ در غیر این صورت models.providers.*.models صریح به‌همراه ارائه‌دهنده‌هایی که احراز هویت قابل استفاده دارند. کل کاتالوگ داخلی فقط برای نماهای مرور صریح مانند models.list با view: "all" یا openclaw models list --all رزرو شده است.

سیاست سریع مدل

primary خود را روی قوی‌ترین مدل نسل جدیدی که در دسترس شماست تنظیم کنید.
برای کارهای حساس به هزینه/تأخیر و گفت‌وگوهای کم‌ریسک‌تر از fallbackها استفاده کنید.
برای عامل‌های دارای ابزار یا ورودی‌های نامطمئن، از رده‌های مدل قدیمی‌تر/ضعیف‌تر پرهیز کنید.

راه‌اندازی اولیه (توصیه‌شده)

اگر نمی‌خواهید پیکربندی را دستی ویرایش کنید، راه‌اندازی اولیه را اجرا کنید:

bash

openclaw onboard

این فرمان می‌تواند مدل + احراز هویت را برای ارائه‌دهنده‌های رایج تنظیم کند، از جمله اشتراک OpenAI Code (Codex) (OAuth) و Anthropic (کلید API یا Claude CLI).

کلیدهای پیکربندی (مرور کلی)

agents.defaults.model.primary و agents.defaults.model.fallbacks
agents.defaults.imageModel.primary و agents.defaults.imageModel.fallbacks
agents.defaults.pdfModel.primary و agents.defaults.pdfModel.fallbacks
agents.defaults.imageGenerationModel.primary و agents.defaults.imageGenerationModel.fallbacks
agents.defaults.videoGenerationModel.primary و agents.defaults.videoGenerationModel.fallbacks
agents.defaults.models (allowlist + aliasها + پارامترهای ارائه‌دهنده + ورودی‌های پویأ ارائه‌دهندهٔ provider/*)
models.providers (ارائه‌دهنده‌های سفارشی نوشته‌شده در models.json)

ویرایش‌های امن allowlist

هنگام به‌روزرسانی دستی agents.defaults.models از نوشتن‌های افزایشی استفاده کنید:

bash

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

Clobber protection rules

openclaw config set از mapهای مدل/ارائه‌دهنده در برابر clobber شدن تصادفی محافظت می‌کند. انتساب یک شیء ساده به agents.defaults.models، models.providers، یا models.providers.<id>.models زمانی رد می‌شود که باعث حذف ورودی‌های موجود شود. برای تغییرات افزایشی از --merge استفاده کنید؛ فقط وقتی از --replace استفاده کنید که مقدار ارائه‌شده باید به مقدار کامل مقصد تبدیل شود.

راه‌اندازی تعاملی ارائه‌دهنده و openclaw configure --section model نیز انتخاب‌های محدود به ارائه‌دهنده را در allowlist موجود merge می‌کنند، بنابراین افزودن Codex، Ollama، یا ارائه‌دهندهٔ دیگر باعث حذف ورودی‌های مدل نامرتبط نمی‌شود. Configure هنگام اعمال دوبارهٔ احراز هویت ارائه‌دهنده، مقدار موجود agents.defaults.model.primary را حفظ می‌کند. فرمان‌های صریح تنظیم پیش‌فرض مانند openclaw models auth login --provider <id> --set-default و openclaw models set <model> همچنان agents.defaults.model.primary را جایگزین می‌کنند.

«مدل مجاز نیست» (و چرا پاسخ‌ها متوقف می‌شوند)

اگر agents.defaults.models تنظیم شده باشد، به allowlist برای /model و بازنویسی‌های نشست تبدیل می‌شود. وقتی کاربر مدلی را انتخاب کند که در آن allowlist نیست، OpenClaw این را برمی‌گرداند:

Code

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

وقتی فرمان ردشده شامل بازنویسی runtime مانند /model openai/gpt-5.5 --runtime codex بود، ابتدا allowlist را اصلاح کنید، سپس همان فرمان /model ... --runtime ... را دوباره امتحان کنید. برای اجرای بومی Codex، مدل انتخاب‌شده همچنان openai/gpt-5.5 است؛ runtime codex harness را انتخاب می‌کند و احراز هویت Codex را جداگانه به‌کار می‌گیرد.

برای مدل‌های محلی/GGUF، ارجاع کامل دارای پیشوند ارائه‌دهنده را در allowlist ذخیره کنید، برای مثال ollama/gemma4:26b، lmstudio/Gemma4-26b-a4-it-gguf، یا همان provider/model دقیقی که openclaw models list --provider <provider> نشان می‌دهد. نام فایل‌های محلی بدون پیشوند یا نام‌های نمایشی وقتی allowlist فعال است کافی نیستند.

اگر می‌خواهید ارائه‌دهنده‌ها را بدون فهرست‌کردن دستی هر مدل محدود کنید، ورودی‌های provider/* را به agents.defaults.models اضافه کنید:

json5

{  agents: {    defaults: {      models: {        "openai-codex/*": {},        "vllm/*": {},      },    },  },}

با این سیاست، /model، /models، و انتخاب‌گرهای مدل کاتالوگ کشف‌شده را فقط برای همان ارائه‌دهنده‌ها نشان می‌دهند. مدل‌های جدید از ارائه‌دهنده‌های انتخاب‌شده می‌توانند بدون ویرایش allowlist ظاهر شوند. وقتی به یک مدل مشخص از ارائه‌دهنده‌ای دیگر نیاز دارید، ورودی‌های دقیق provider/model می‌توانند با ورودی‌های provider/* ترکیب شوند.

نمونهٔ پیکربندی allowlist:

json5

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

تعویض مدل‌ها در گفت‌وگو (`/model`)

می‌توانید بدون راه‌اندازی دوباره، مدل‌ها را برای نشست فعلی تعویض کنید:

Code

/model/model list/model 3/model openai/gpt-5.4/model status

Picker behavior

/model (و /model list) یک انتخاب‌گر فشرده و شماره‌دار است (خانوادهٔ مدل + ارائه‌دهنده‌های موجود).
در Discord، /model و /models یک انتخاب‌گر تعاملی با dropdownهای ارائه‌دهنده و مدل به‌همراه مرحلهٔ Submit باز می‌کنند.
در Telegram، انتخاب‌های انتخاب‌گر /models محدود به نشست هستند؛ آن‌ها پیش‌فرض پایدار عامل را در openclaw.json تغییر نمی‌دهند.
/models add منسوخ شده و اکنون به‌جای ثبت مدل‌ها از داخل گفت‌وگو، پیام منسوخ‌شدن برمی‌گرداند.
/model <#> از همان انتخاب‌گر انتخاب می‌کند.

Persistence and live switching

/model انتخاب جدید نشست را فوراً پایدار می‌کند.
اگر عامل بیکار باشد، اجرای بعدی بلافاصله از مدل جدید استفاده می‌کند.
اگر اجرایی از قبل فعال باشد، OpenClaw یک تعویض زنده را در حالت pending علامت‌گذاری می‌کند و فقط در یک نقطهٔ retry تمیز با مدل جدید restart می‌کند.
اگر فعالیت ابزار یا خروجی پاسخ از قبل شروع شده باشد، تعویض pending می‌تواند تا یک فرصت retry بعدی یا نوبت بعدی کاربر در صف بماند.
ارجاع /model انتخاب‌شده توسط کاربر برای آن نشست سخت‌گیرانه است: اگر ارائه‌دهنده/مدل انتخاب‌شده در دسترس نباشد، پاسخ به‌جای جواب‌دادن بی‌صدا از agents.defaults.model.fallbacks، آشکارا شکست می‌خورد. این با پیش‌فرض‌های پیکربندی‌شده و primaryهای job مربوط به cron فرق دارد که همچنان می‌توانند از زنجیره‌های fallback استفاده کنند.
/model status نمای جزئیات است (نامزدهای احراز هویت و، در صورت پیکربندی، baseUrl مربوط به endpoint ارائه‌دهنده + حالت api).

Ref parsing

ارجاع‌های مدل با جدا کردن روی نخستین / تجزیه می‌شوند. هنگام وارد کردن /model <ref> از provider/model استفاده کنید.
اگر خود شناسهٔ مدل شامل / باشد (به سبک OpenRouter)، باید پیشوند ارائه‌دهنده را وارد کنید (مثال: /model openrouter/moonshotai/kimi-k2).
اگر ارائه‌دهنده را حذف کنید، OpenClaw ورودی را به این ترتیب resolve می‌کند:
1. تطابق alias
2. تطابق یکتای ارائه‌دهندهٔ پیکربندی‌شده برای همان شناسهٔ مدل بدون پیشوند
3. بازگشت منسوخ به ارائه‌دهندهٔ پیش‌فرض پیکربندی‌شده — اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw در عوض برای جلوگیری از نمایش پیش‌فرض کهنهٔ ارائه‌دهندهٔ حذف‌شده، به نخستین ارائه‌دهنده/مدل پیکربندی‌شده بازمی‌گردد.

رفتار/پیکربندی کامل دستور: دستورات Slash.

دستورات CLI

bash

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models (بدون زیردستور) میان‌بری برای models status است.

`models list`

به‌طور پیش‌فرض مدل‌های پیکربندی‌شده/در دسترس از نظر احراز هویت را نشان می‌دهد. flagهای مفید:

--allboolean

کاتالوگ کامل. ردیف‌های کاتالوگ ایستای متعلق به ارائه‌دهندهٔ همراه را پیش از پیکربندی احراز هویت شامل می‌شود، بنابراین نماهای صرفاً اکتشافی می‌توانند مدل‌هایی را نشان دهند که تا زمانی که اعتبارنامه‌های مطابق ارائه‌دهنده را اضافه نکنید در دسترس نیستند.

--localboolean

فقط ارائه‌دهنده‌های محلی.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> فیلتر بر اساس شناسهٔ ارائه‌دهنده، برای مثال moonshot. برچسب‌های نمایشی از انتخابگرهای تعاملی پذیرفته نمی‌شوند.

--plainboolean

یک مدل در هر خط.

--jsonboolean

خروجی قابل خواندن برای ماشین.

`models status`

مدل اصلی resolveشده، fallbackها، مدل تصویر و نمای کلی احراز هویت ارائه‌دهنده‌های پیکربندی‌شده را نشان می‌دهد. همچنین وضعیت انقضای OAuth را برای پروفایل‌های یافت‌شده در مخزن احراز هویت نمایش می‌دهد (به‌طور پیش‌فرض در بازهٔ ۲۴ ساعت هشدار می‌دهد). --plain فقط مدل اصلی resolveشده را چاپ می‌کند.

Auth and probe behavior

وضعیت OAuth همیشه نشان داده می‌شود (و در خروجی --json نیز گنجانده می‌شود). اگر ارائه‌دهندهٔ پیکربندی‌شده‌ای اعتبارنامه نداشته باشد، models status بخشی با عنوان احراز هویت گمشده چاپ می‌کند.
JSON شامل auth.oauth (پنجرهٔ هشدار + پروفایل‌ها) و auth.providers (احراز هویت مؤثر برای هر ارائه‌دهنده، شامل اعتبارنامه‌های مبتنی بر env) است. auth.oauth فقط سلامت پروفایل مخزن احراز هویت است؛ ارائه‌دهنده‌های فقط-env در آن ظاهر نمی‌شوند.
برای خودکارسازی از --check استفاده کنید (هنگام نبودن/منقضی بودن خروج با 1، هنگام نزدیک بودن انقضا خروج با 2).
برای بررسی‌های زندهٔ احراز هویت از --probe استفاده کنید؛ ردیف‌های probe می‌توانند از پروفایل‌های احراز هویت، اعتبارنامه‌های env یا models.json بیایند.
اگر auth.order.<provider> صریح یک پروفایل ذخیره‌شده را حذف کند، probe به‌جای تلاش برای آن، excluded_by_auth_order را گزارش می‌کند. اگر احراز هویت وجود داشته باشد اما هیچ مدل قابل probe برای آن ارائه‌دهنده resolve نشود، probe مقدار status: no_model را گزارش می‌کند.

مثال (Claude CLI):

bash

claude auth loginopenclaw models status

اسکن (مدل‌های رایگان OpenRouter)

openclaw models scan کاتالوگ مدل رایگان OpenRouter را بررسی می‌کند و می‌تواند به‌صورت اختیاری مدل‌ها را برای پشتیبانی از ابزار و تصویر probe کند.

--no-probeboolean

از probeهای زنده صرف‌نظر کن (فقط metadata).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

agents.defaults.model.primary را روی نخستین انتخاب تنظیم کن.

--set-imageboolean

agents.defaults.imageModel.primary را روی نخستین انتخاب تصویر تنظیم کن.

نتایج اسکن بر اساس موارد زیر رتبه‌بندی می‌شوند:

پشتیبانی تصویر
تأخیر ابزار
اندازهٔ زمینه
تعداد پارامترها

ورودی:

فهرست /models در OpenRouter (فیلتر :free)
probeهای زنده به کلید API OpenRouter از پروفایل‌های احراز هویت یا OPENROUTER_API_KEY نیاز دارند (نگاه کنید به متغیرهای محیطی)
فیلترهای اختیاری: --max-age-days، --min-params، --provider، --max-candidates
کنترل‌های درخواست/probe: --timeout، --concurrency

وقتی probeهای زنده در یک TTY اجرا می‌شوند، می‌توانید fallbackها را به‌صورت تعاملی انتخاب کنید. در حالت غیرتعاملی، برای پذیرش پیش‌فرض‌ها --yes را پاس دهید. نتایج فقط-metadata اطلاع‌رسانی هستند؛ --set-default و --set-image به probeهای زنده نیاز دارند تا OpenClaw یک مدل OpenRouter بدون کلید و غیرقابل استفاده را پیکربندی نکند.

رجیستری مدل‌ها (`models.json`)

ارائه‌دهنده‌های سفارشی در models.providers در فایل models.json زیر دایرکتوری عامل نوشته می‌شوند (پیش‌فرض ~/.openclaw/agents/<agentId>/agent/models.json). این فایل به‌طور پیش‌فرض merge می‌شود مگر اینکه models.mode روی replace تنظیم شده باشد.

Merge mode precedence

تقدم حالت merge برای شناسه‌های ارائه‌دهندهٔ مطابق:

baseUrl غیرخالی که از قبل در models.json عامل وجود دارد برنده است.
apiKey غیرخالی در models.json عامل فقط زمانی برنده است که آن ارائه‌دهنده در زمینهٔ پیکربندی/پروفایل احراز هویت فعلی تحت مدیریت SecretRef نباشد.
مقادیر apiKey ارائه‌دهندهٔ تحت مدیریت SecretRef به‌جای ماندگار کردن رازهای resolveشده، از markerهای منبع (ENV_VAR_NAME برای ارجاع‌های env، secretref-managed برای ارجاع‌های file/exec) تازه‌سازی می‌شوند.
مقادیر header ارائه‌دهندهٔ تحت مدیریت SecretRef از markerهای منبع (secretref-env:ENV_VAR_NAME برای ارجاع‌های env، secretref-managed برای ارجاع‌های file/exec) تازه‌سازی می‌شوند.
apiKey/baseUrl خالی یا گمشدهٔ عامل به models.providers پیکربندی fallback می‌کند.
فیلدهای دیگر ارائه‌دهنده از پیکربندی و داده‌های کاتالوگ نرمال‌شده تازه‌سازی می‌شوند.

مرتبط

runtimeهای عامل — PI، Codex و runtimeهای دیگر حلقهٔ عامل
مرجع پیکربندی — کلیدهای پیکربندی مدل
تولید تصویر — پیکربندی مدل تصویر
failover مدل — زنجیره‌های fallback
ارائه‌دهنده‌های مدل — مسیریابی ارائه‌دهنده و احراز هویت
تولید موسیقی — پیکربندی مدل موسیقی
تولید ویدئو — پیکربندی مدل ویدئو

Was this useful?

نحوهٔ کار انتخاب مدل

Primary model

Fallbacks

Provider auth failover

منبع انتخاب و رفتار fallback

سیاست سریع مدل

راه‌اندازی اولیه (توصیه‌شده)

کلیدهای پیکربندی (مرور کلی)

ویرایش‌های امن allowlist

«مدل مجاز نیست» (و چرا پاسخ‌ها متوقف می‌شوند)

تعویض مدل‌ها در گفت‌وگو (/model)

دستورات CLI

models list

models status

اسکن (مدل‌های رایگان OpenRouter)

رجیستری مدل‌ها (models.json)

مرتبط

تعویض مدل‌ها در گفت‌وگو (`/model`)

`models list`

`models status`

رجیستری مدل‌ها (`models.json`)