CLI مدل‌ها

ارجاع‌های مدل یک ارائه‌دهنده و مدل را انتخاب می‌کنند. آن‌ها معمولاً زمان‌اجرای سطح پایین عامل را انتخاب نمی‌کنند. برای مثال، openai/gpt-5.5 بسته به agents.defaults.agentRuntime.id می‌تواند از مسیر عادی ارائه‌دهنده OpenAI یا از طریق زمان‌اجرای app-server در Codex اجرا شود. در حالت زمان‌اجرای Codex، ارجاع openai/gpt-* به‌معنای صورتحساب API key نیست؛ احراز هویت می‌تواند از یک حساب Codex یا پروفایل احراز هویت openai-codex بیاید. زمان‌اجراهای عامل را ببینید.

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

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

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

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

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

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

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

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

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

openclaw onboard

این می‌تواند مدل + احراز هویت را برای ارائه‌دهندگان رایج، از جمله اشتراک OpenAI Code (Codex) (OAuth) و Anthropic (API key یا 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 (فهرست مجاز + aliasها + پارامترهای ارائه‌دهنده)
• 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 harness را انتخاب می‌کند و احراز هویت Codex را جداگانه به‌کار می‌برد.

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

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

{
  agent: {
    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 status

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

# فرمان‌های CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

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

# models list

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

--allboolean

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

--localboolean

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

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

--plainboolean

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

--jsonboolean

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

# models status

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

مثال (Claude CLI):

claude auth login
openclaw models status

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

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

--no-probeboolean

آزمون‌های زنده را رد کن (فقط فراداده).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

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

--set-imageboolean

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

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

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

ورودی:

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

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

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

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

# مرتبط

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