CLI مدل‌ها

یک ارجاع مدل (provider/model) ارائه‌دهنده و مدل را انتخاب می‌کند، نه محیط اجرای سطح‌پایین عامل را. وقتی سیاست محیط اجرا تنظیم نشده یا auto باشد، سیاست مسیریابی تحت مالکیت ارائه‌دهنده OpenAI ممکن است Codex را فقط برای یک مسیر دقیق و رسمی HTTPS مربوط به Platform Responses یا ChatGPT Responses، بدون بازنویسی تألیفی درخواست، انتخاب کند؛ صرفاً پیشوند openai/* هرگز Codex را انتخاب نمی‌کند. سازگارکننده‌های Completions، نقطه‌های پایانی سفارشی و رفتار تألیفی درخواست در OpenClaw باقی می‌مانند. نقطه‌های پایانی رسمی HTTP متن ساده رد می‌شوند. به محیط اجرای ضمنی عامل OpenAI مراجعه کنید.

ارجاع‌های اشتراکی Copilot (github-copilot/*) را می‌توان برای استفاده از Plugin خارجی محیط اجرای عامل GitHub Copilot فعال کرد، اما این مسیر همیشه صریح است (و هرگز با auto انتخاب نمی‌شود). بازنویسی‌های محیط اجرا باید در سیاست ارائه‌دهنده/مدل قرار گیرند، نه در کل عامل یا نشست. انتخاب محیط اجرا روش صورت‌حساب را تعیین نمی‌کند: اعتبارنامه‌های کلید API در OpenAI و اشتراک ChatGPT/Codex از هم متمایز می‌مانند. به محیط‌های اجرای عامل و محیط اجرای عامل GitHub Copilot مراجعه کنید.

ترتیب انتخاب

سطوح مرتبط پیکربندی مدل:

• agents.defaults.models نام‌های مستعار و تنظیمات هر مدل را ذخیره می‌کند. افزودن یک ورودی، بازنویسی‌های مدل را محدود نمی‌کند.
• agents.defaults.modelPolicy.allow فهرست مجاز اختیاری برای بازنویسی‌ها است. از ارجاع‌های دقیق یا نویسه‌های عام انتهای پیشوند مانند provider/* و provider/namespace/* استفاده کنید؛ برای مجاز کردن هر مدلی، آن را حذف کنید یا روی [] تنظیم کنید. agents.entries.*.modelPolicy.allow مختص هر عامل، سیاست پیش‌فرض را برای همان عامل جایگزین می‌کند.
• agents.defaults.utilityModel یک مدل اختیاری کم‌هزینه‌تر برای کارهای داخلی کوتاه مانند عنوان‌های تولیدشده نشست داشبورد، عنوان‌های رشته/موضوع کانال‌های پشتیبانی‌شده و روایت پیشرفت است. agents.entries.*.utilityModel مختص هر عامل آن را بازنویسی می‌کند. وقتی تنظیم نشده باشد، OpenClaw در صورت وجود از مدل کوچک پیش‌فرض اعلام‌شده ارائه‌دهنده اصلی استفاده می‌کند (OpenAI ← gpt-5.6-luna، Anthropic ← claude-haiku-4-5)؛ در غیر این صورت از مدل اصلی عامل استفاده می‌کند. برای غیرفعال کردن مسیریابی کمکی، آن را روی رشته خالی تنظیم کنید. اگر یک مدل کمکی متمایز شکست بخورد، تولید عنوان‌ها یک بار دیگر با مدل اصلی تلاش می‌شود. برای عنوان‌های داشبورد، استخراج خودکار مدل کمکی و جایگزین عادی از ارائه‌دهنده و پروفایل احراز هویت مؤثر نشست پیروی می‌کنند؛ یک مدل کمکی صریح، ارائه‌دهنده/احراز هویت پیکربندی‌شده خود را حفظ می‌کند. مدل کمکی خالی فقط مسیر جایگزین مدل کوچک را نادیده می‌گیرد، نه تولید عنوان داشبورد را. کارهای کمکی فراخوانی‌های جداگانه مدل هستند و ممکن است محتوای محدودشده کار را برای ارائه‌دهنده مدل انتخاب‌شده ارسال کنند.
• agents.defaults.imageModel فقط زمانی استفاده می‌شود که مدل اصلی نتواند تصویر بپذیرد.
• agents.defaults.pdfModel توسط ابزار pdf استفاده می‌شود. اگر تنظیم نشده باشد، ابزار ابتدا به imageModel و سپس به مدل حل‌شده نشست/پیش‌فرض برمی‌گردد.
• agents.defaults.mediaModels.{image,music,video} زیربنای ابزارهای مشترک تولید رسانه است. اگر تنظیم نشده باشد، هر ابزار یک پیش‌فرض ارائه‌دهنده دارای پشتوانه احراز هویت را استنتاج می‌کند: ابتدا ارائه‌دهنده پیش‌فرض کنونی، سپس ارائه‌دهندگان ثبت‌شده باقی‌مانده برای آن قابلیت به‌ترتیب شناسه ارائه‌دهنده. جایگزینی میان‌ارائه‌دهنده‌ای رفتار پیش‌فرض ثابت است.
• agents.entries.*.model مختص هر عامل (به‌همراه اتصال‌ها)، agents.defaults.model را بازنویسی می‌کند — به مسیریابی چندعاملی مراجعه کنید.

مرجع کامل کلیدها، مقادیر پیش‌فرض و نمونه‌های JSON5: مرجع پیکربندی.

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

provider/model یکسان، بسته به منشأ آن رفتار متفاوتی دارد:

سایر قواعد انتخاب:

• تغییر agents.defaults.model.primary پین‌های نشست موجود را بازنویسی نمی‌کند. اگر وضعیت This session is pinned to X; config primary Y will apply to new/unpinned sessions. را گزارش می‌کند، برای پاک کردن پین، /model default را اجرا کنید.
• انتخاب‌گرهای مدل پیش‌فرض و فهرست مجاز در CLI با فهرست کردن فقط models.providers.*.models به‌جای کل کاتالوگ داخلی، به models.mode: "replace" احترام می‌گذارند.
• انتخاب‌گر مدل در رابط کنترل، نمای مدل پیکربندی‌شده را از Gateway درخواست می‌کند. یک modelPolicy.allow صریح آن را پالایش می‌کند، از جمله ورودی‌های دارای نویسه عام انتهای پیشوند؛ در غیر این صورت مدل‌های پیکربندی‌شده و ارائه‌دهندگان دارای احراز هویت قابل‌استفاده را نشان می‌دهد. کل کاتالوگ داخلی فقط برای نماهای مرور صریح رزرو شده است (models.list با view: "all" یا openclaw models list --all).
• رابط‌های موجودی ارائه‌دهندگان از models.list به‌همراه view: "provider-config" استفاده می‌کنند تا ردیف‌های models.providers.*.models تألیف‌شده در منبع را بدون اعمال فهرست‌های مجاز انتخاب‌گر نشان دهند.

جزئیات کامل سازوکار: جایگزینی مدل هنگام خرابی.

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

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

راه‌اندازی اولیه

openclaw onboard

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

اگر هیچ مدل اصلی پیکربندی نشده باشد، راه‌اندازی جدید با کلید API در OpenAI، openai/gpt-5.6 را انتخاب می‌کند؛ شناسه ساده API مستقیم به رده Sol حل می‌شود. راه‌اندازی جدید OAuth برای ChatGPT/Codex، ارجاع دقیق کاتالوگ openai/gpt-5.6-sol را انتخاب می‌کند. احراز هویت مجدد، مدل اصلی صریح موجود را حفظ می‌کند، از جمله openai/gpt-5.5. اگر GPT-5.6 برای حساب در دسترس نیست، openai/gpt-5.5 را صریحاً انتخاب کنید؛ OpenClaw آن را بی‌سروصدا تنزل نمی‌دهد.

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

اگر agents.defaults.modelPolicy.allow خالی نباشد، به فهرست مجاز برای /model، بازنویسی‌های نشست و --model تبدیل می‌شود. انتخاب مدلی خارج از آن فهرست مجاز، پیش از تولید هر پاسخ عادی بازمی‌گردد. agents.entries.*.modelPolicy.allow مختص هر عامل، سیاست پیش‌فرض را برای همان عامل جایگزین می‌کند.

بازنویسی مدل "provider/model" توسط agents.defaults.modelPolicy.allow مجاز نیست."provider/model"، ‏"provider/*" یا پیشوند محدودتر "provider/namespace/*" را به agents.defaults.modelPolicy.allow اضافه کنید، یا برای مجاز کردن هر مدل، فهرست را حذف/خالی کنید.

برای رفع آن، مدل یا نویسه عام ارائه‌دهنده را به کلید نام‌برده modelPolicy.allow اضافه کنید، آن فهرست را حذف/خالی کنید، یا مدلی را از /model list انتخاب کنید. اگر فرمان ردشده شامل بازنویسی محیط اجرا مانند /model openai/gpt-5.5 --runtime codex بود، ابتدا فهرست مجاز را اصلاح کنید، سپس همان فرمان را دوباره امتحان کنید.

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

برای محدود کردن ارائه‌دهندگان بدون فهرست کردن تک‌تک مدل‌ها، از ورودی‌های نویسه عام انتهای پیشوند استفاده کنید. provider/* در سطح ارائه‌دهنده با همه مدل‌های زیرمجموعه آن ارائه‌دهنده مطابقت دارد؛ پیشوند محدودتری مانند clawrouter/anthropic/* فقط با همان فضای نام مطابقت دارد:

{  agents: {    defaults: {      modelPolicy: {        allow: ["openai/*", "vllm/*"],      },    },  },}

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

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

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

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

/model در گفت‌وگو

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

• /model و /model list یک انتخاب‌گر شماره‌دار فشرده (خانواده مدل + ارائه‌دهندگان موجود) را نمایش می‌دهند؛ /model <#> از آن انتخاب می‌کند. در Discord، این کار فهرست‌های کشویی ارائه‌دهنده/مدل را با یک مرحله Submit باز می‌کند؛ در Telegram، انتخاب‌های انتخاب‌گر محدود به نشست هستند و هرگز مقدار پیش‌فرض پایدار عامل را در openclaw.json بازنویسی نمی‌کنند. /models add منسوخ شده است و به‌جای ثبت مدل‌ها از طریق چت، یک پیام برمی‌گرداند.
• /model انتخاب جدید نشست را بلافاصله ذخیره می‌کند. اگر عامل بیکار باشد، اجرای بعدی فوراً از آن استفاده می‌کند؛ اگر اجرایی از قبل فعال باشد، تغییر برای نقطه بعدی تلاش مجددِ پاک در صف قرار می‌گیرد (یا نقطه‌ای بعدتر، اگر فعالیت ابزار یا خروجی پاسخ از قبل آغاز شده باشد).
• /model default انتخاب نشست را پاک می‌کند تا دوباره مقدار اصلی پیکربندی‌شده را به ارث ببرد.
• ارجاع /model انتخاب‌شده توسط کاربر برای آن نشست سخت‌گیرانه است: اگر دسترس‌ناپذیر شود، پاسخ به‌طور آشکار شکست می‌خورد، به‌جای آنکه بی‌صدا از طریق agents.defaults.model.fallbacks به گزینه‌های جایگزین برگردد. مقادیر پیش‌فرض پیکربندی‌شده و مقادیر اصلی کارهای cron همچنان از زنجیره‌های جایگزین استفاده می‌کنند.
• /model status نمای تفصیلی است: نامزدهای احراز هویت برای هر ارائه‌دهنده، و (در صورت پیکربندی) نقطه پایانی ارائه‌دهنده baseUrl به‌همراه حالت api.
• ارجاع‌های مدل با تقسیم روی نخستین / تجزیه می‌شوند؛ provider/model را وارد کنید. اگر شناسه مدل خود حاوی / است (به سبک OpenRouter)، پیشوند ارائه‌دهنده را نیز درج کنید، برای مثال /model openrouter/moonshotai/kimi-k2. اگر ارائه‌دهنده را حذف کنید، OpenClaw به‌ترتیب این موارد را امتحان می‌کند: (1) تطبیق نام مستعار، (2) تطبیق یکتای ارائه‌دهنده پیکربندی‌شده برای همان شناسه دقیق مدل بدون پیشوند، (3) ارائه‌دهنده پیش‌فرض پیکربندی‌شده (بازگشت منسوخ‌شده) — و اگر آن ارائه‌دهنده دیگر مدل پیش‌فرض پیکربندی‌شده را عرضه نکند، به‌جای آن نخستین ارائه‌دهنده/مدل پیکربندی‌شده را انتخاب می‌کند تا مقدار پیش‌فرض کهنه مربوط به ارائه‌دهنده حذف‌شده نمایش داده نشود.
• ارجاع‌های مدل به حروف کوچک نرمال‌سازی می‌شوند؛ در غیر این صورت، شناسه‌های ارائه‌دهنده دقیق هستند، بنابراین از شناسه اعلام‌شده توسط Plugin استفاده کنید.

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

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models بدون زیرفرمان، میان‌بری برای models status است که انقضای OAuth را نیز برای پروفایل‌های مخزن احراز هویت نمایش می‌دهد (به‌طور پیش‌فرض در فاصله 24h هشدار می‌دهد). پرچم‌های کامل، ساختارهای JSON و زیرفرمان‌های پروفایل احراز هویت: مرجع CLI مدل‌ها.

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

ارائه‌دهندگان سفارشی پیکربندی‌شده زیر models.providers در models.json واقع در دایرکتوری عامل نوشته می‌شوند (پیش‌فرض ~/.openclaw/agents/<agentId>/agent/models.json). فهرست‌های Plugin ارائه‌دهنده جداگانه و به‌شکل بخش‌های تولیدشده فهرست که تحت مالکیت Plugin هستند ذخیره می‌شوند و به‌طور خودکار بارگذاری می‌شوند. این فایل به‌طور پیش‌فرض با پیکربندی ادغام می‌شود؛ برای استفاده صرفاً از ارائه‌دهندگان پیکربندی‌شده خود، models.mode: "replace" را تنظیم کنید.

ماندگاری نشانگرها بر مرجعیت منبع استوار است: هر زمان OpenClaw فایل models.json را بازتولید می‌کند — از جمله در مسیرهای هدایت‌شده با فرمان مانند openclaw agent — نشانگرها را از تصویر لحظه‌ای پیکربندی منبع فعال (پیش از حل‌وفصل) می‌نویسد، نه از مقادیر حل‌شده اسرار در زمان اجرا.

مرتبط

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