مدل‌های CLI

ارجاع‌های مدل یک ارائه‌دهنده و مدل را انتخاب می‌کنند. آن‌ها معمولا زمان‌اجرای سطح‌پایین عامل را انتخاب نمی‌کنند. ارجاع‌های عامل OpenAI استثنای اصلی هستند: openai/gpt-5.5 به‌طور پیش‌فرض روی ارائه‌دهنده رسمی OpenAI از طریق زمان‌اجرای سرور برنامه Codex اجرا می‌شود. ارجاع‌های اشتراکی Copilot (github-copilot/*) علاوه بر این می‌توانند به Plugin زمان‌اجرای عامل خارجی GitHub Copilot وارد شوند — آن مسیر صریح باقی می‌ماند (بدون جایگزین auto). بازنویسی‌های صریح زمان‌اجرا به سیاست ارائه‌دهنده/مدل تعلق دارند، نه به کل عامل یا نشست. در حالت زمان‌اجرای Codex، ارجاع openai/gpt-* به معنای صورتحساب‌گیری کلید API نیست؛ احراز هویت می‌تواند از یک حساب Codex یا پروفایل OAuth openai بیاید. زمان‌اجراهای عامل و زمان‌اجرای عامل GitHub Copilot را ببینید.

انتخاب مدل چگونه کار می‌کند

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

منبع انتخاب و رفتار جایگزین

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

• پیش‌فرض‌های پیکربندی‌شده (agents.defaults.model.primary و مدل‌های اصلی ویژه عامل) نقطه شروع عادی هستند و از agents.defaults.model.fallbacks استفاده می‌کنند.
• انتخاب‌های جایگزین خودکار وضعیت بازیابی موقت هستند. آن‌ها با modelOverrideSource: "auto" ذخیره می‌شوند تا نوبت‌های بعدی بتوانند بدون آزمودن هر باره یک مدل اصلی شناخته‌شده معیوب، همچنان از زنجیره جایگزین استفاده کنند؛ OpenClaw به‌صورت دوره‌ای مدل اصلی اولیه را دوباره می‌آزماید، پس از بازیابی انتخاب خودکار را پاک می‌کند، و گذارهای جایگزینی/بازیابی را یک بار به‌ازای هر تغییر وضعیت اعلام می‌کند.
• انتخاب‌های نشست کاربر دقیق هستند. /model، انتخابگر مدل، session_status(model=...)، و sessions.patch مقدار modelOverrideSource: "user" را ذخیره می‌کنند؛ اگر آن ارائه‌دهنده/مدل انتخاب‌شده در دسترس نباشد، OpenClaw به‌جای عبور به مدل پیکربندی‌شده دیگر، به‌صورت قابل‌مشاهده شکست می‌خورد.
• تغییر agents.defaults.model.primary انتخاب‌های نشست موجود را بازنویسی نمی‌کند. اگر وضعیت می‌گوید This session is pinned to X; config primary Y will apply to new/unpinned sessions.، انتخاب نشست فعلی را با /model default پاک کنید تا دوباره مدل اصلی پیکربندی‌شده را به ارث ببرد.
• Cron --model / محموله model یک مدل اصلی برای هر کار است. همچنان از جایگزین‌های پیکربندی‌شده استفاده می‌کند مگر این‌که کار، محموله صریح fallbacks را فراهم کند (برای اجرای سخت‌گیرانه cron از fallbacks: [] استفاده کنید).
• انتخابگرهای مدل پیش‌فرض CLI و فهرست مجاز با فهرست کردن models.providers.*.models صریح به‌جای بارگذاری کاتالوگ داخلی کامل، به models.mode: "replace" احترام می‌گذارند.
• انتخابگر مدل Control UI از Gateway نمای مدل پیکربندی‌شده‌اش را می‌خواهد: در صورت وجود، agents.defaults.models، شامل ورودی‌های سراسری ارائه‌دهنده provider/*، وگرنه models.providers.*.models صریح به‌علاوه ارائه‌دهندگانی با احراز هویت قابل‌استفاده. کاتالوگ داخلی کامل برای نماهای مرور صریح مانند models.list با view: "all" یا openclaw models list --all رزرو شده است.

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

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

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

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

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 (فهرست مجاز + نام‌های مستعار + پارامترهای ارائه‌دهنده + ورودی‌های ارائه‌دهنده پویای provider/*)
• models.providers (ارائه‌دهندگان سفارشی نوشته‌شده در models.json)

ویرایش‌های ایمن فهرست مجاز

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

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

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

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

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

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

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

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

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

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

نمونه پیکربندی فهرست مجاز:

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

می‌توانید مدل‌ها را برای نشست فعلی بدون راه‌اندازی مجدد تغییر دهید:

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

رفتار/پیکربندی کامل فرمان: فرمان‌های اسلش.

فرمان‌های CLI

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

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

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

models status

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

مثال (Claude CLI):

claude auth loginopenclaw models status

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

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

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

1. پشتیبانی از تصویر
2. تأخیر ابزار
3. اندازهٔ زمینه
4. تعداد پارامترها

ورودی:

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

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

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

ارائه‌دهنده‌های سفارشی در models.providers در models.json زیر پوشهٔ عامل نوشته می‌شوند (پیش‌فرض ~/.openclaw/agents/<agentId>/agent/models.json). کاتالوگ‌های provider-plugin به‌صورت shardهای کاتالوگ تولیدشده و متعلق به Plugin زیر وضعیت Plugin عامل ذخیره می‌شوند و به‌طور خودکار بارگذاری می‌شوند. این فایل به‌طور پیش‌فرض ادغام می‌شود مگر اینکه models.mode روی replace تنظیم شده باشد.

مرتبط

• زمان‌های اجرای عامل — OpenClaw، Codex، و دیگر زمان‌های اجرای حلقهٔ عامل
• مرجع پیکربندی — کلیدهای پیکربندی مدل
• تولید تصویر — پیکربندی مدل تصویر
• جابه‌جایی خودکار مدل — زنجیره‌های جایگزین
• ارائه‌دهنده‌های مدل — مسیریابی ارائه‌دهنده و احراز هویت
• تولید موسیقی — پیکربندی مدل موسیقی
• تولید ویدئو — پیکربندی مدل ویدئو