FAQ

پرسش‌های متداول: مدل‌ها و احراز هویت

Edit source

پرسش‌وپاسخ دربارهٔ مدل و پروفایل احراز هویت. برای راه‌اندازی، نشست‌ها، Gateway، کانال‌ها و عیب‌یابی، FAQ اصلی را ببینید.

مدل‌ها: پیش‌فرض‌ها، انتخاب، نام‌های مستعار، جابه‌جایی

«مدل پیش‌فرض» چیست؟

مدل پیش‌فرض OpenClaw همان چیزی است که به‌عنوان مقدار زیر تنظیم می‌کنید:

Code
agents.defaults.model.primary

مدل‌ها به‌شکل provider/model ارجاع داده می‌شوند (مثال: openai/gpt-5.5 یا anthropic/claude-sonnet-4-6). اگر provider را حذف کنید، OpenClaw ابتدا یک نام مستعار را امتحان می‌کند، سپس یک تطابق provider پیکربندی‌شدهٔ یکتا برای همان شناسهٔ دقیق مدل را، و فقط پس از آن به‌عنوان مسیر سازگاری منسوخ‌شده، به provider پیش‌فرض پیکربندی‌شده برمی‌گردد. اگر آن provider دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش یک پیش‌فرض کهنه از provider حذف‌شده، به نخستین provider/model پیکربندی‌شده برمی‌گردد. بااین‌حال همچنان باید provider/model را صریحاً تنظیم کنید.

چه مدلی را پیشنهاد می‌کنید؟

پیش‌فرض پیشنهادی: از قوی‌ترین مدل نسل جدید موجود در مجموعهٔ providerهای خود استفاده کنید. برای عامل‌های دارای ابزار یا ورودی نامطمئن: قدرت مدل را بر هزینه اولویت دهید. برای گفت‌وگوی معمولی/کم‌ریسک: از مدل‌های جایگزین ارزان‌تر استفاده کنید و بر اساس نقش عامل مسیردهی کنید.

MiniMax مستندات خودش را دارد: MiniMax و مدل‌های محلی.

قاعدهٔ سرانگشتی: برای کارهای پرریسک از بهترین مدلی که از پس هزینه‌اش برمی‌آیید استفاده کنید، و برای گفت‌وگوی معمولی یا خلاصه‌سازی از مدلی ارزان‌تر. می‌توانید مدل‌ها را برای هر عامل مسیردهی کنید و از زیرعامل‌ها برای موازی‌سازی کارهای طولانی استفاده کنید (هر زیرعامل توکن مصرف می‌کند). مدل‌ها و زیرعامل‌ها را ببینید.

هشدار جدی: مدل‌های ضعیف‌تر/بیش‌ازحد کوانتیزه‌شده در برابر تزریق پرامپت و رفتار ناامن آسیب‌پذیرترند. امنیت را ببینید.

زمینهٔ بیشتر: مدل‌ها.

چگونه بدون پاک کردن پیکربندی، مدل‌ها را عوض کنم؟

از دستورهای مدل استفاده کنید یا فقط فیلدهای model را ویرایش کنید. از جایگزینی کامل پیکربندی پرهیز کنید.

گزینه‌های امن:

  • /model در چت (سریع، برای هر نشست)
  • openclaw models set ... (فقط پیکربندی مدل را به‌روزرسانی می‌کند)
  • openclaw configure --section model (تعاملی)
  • ویرایش agents.defaults.model در ~/.openclaw/openclaw.json

از config.apply با یک شیء جزئی پرهیز کنید، مگر اینکه قصد داشته باشید کل پیکربندی را جایگزین کنید. برای ویرایش‌های RPC، ابتدا با config.schema.lookup بررسی کنید و ترجیحاً از config.patch استفاده کنید. payload جست‌وجو مسیر نرمال‌شده، مستندات/محدودیت‌های سطحی schema، و خلاصه‌های فرزند بلافاصله را برای به‌روزرسانی‌های جزئی در اختیارتان می‌گذارد. اگر پیکربندی را بازنویسی کردید، از نسخهٔ پشتیبان بازیابی کنید یا برای تعمیر دوباره openclaw doctor را اجرا کنید.

مستندات: مدل‌ها، پیکربندی، Config، Doctor.

آیا می‌توانم از مدل‌های خودمیزبان (llama.cpp، vLLM، Ollama) استفاده کنم؟

بله. Ollama ساده‌ترین مسیر برای مدل‌های محلی است.

سریع‌ترین راه‌اندازی:

  1. Ollama را از https://ollama.com/download نصب کنید
  2. یک مدل محلی مانند ollama pull gemma4 را pull کنید
  3. اگر مدل‌های ابری هم می‌خواهید، ollama signin را اجرا کنید
  4. openclaw onboard را اجرا کنید و Ollama را انتخاب کنید
  5. Local یا Cloud + Local را انتخاب کنید

نکته‌ها:

  • Cloud + Local مدل‌های ابری را به‌همراه مدل‌های محلی Ollama شما می‌دهد
  • مدل‌های ابری مانند kimi-k2.5:cloud به pull محلی نیاز ندارند
  • برای جابه‌جایی دستی، از openclaw models list و openclaw models set ollama/<model> استفاده کنید

نکتهٔ امنیتی: مدل‌های کوچک‌تر یا به‌شدت کوانتیزه‌شده در برابر تزریق پرامپت آسیب‌پذیرترند. ما برای هر رباتی که می‌تواند از ابزارها استفاده کند، مدل‌های بزرگ را قویاً توصیه می‌کنیم. اگر همچنان مدل‌های کوچک می‌خواهید، sandboxing و allowlistهای سخت‌گیرانهٔ ابزار را فعال کنید.

مستندات: Ollama، مدل‌های محلی، providerهای مدل، امنیت، Sandboxing.

OpenClaw، Flawd و Krill برای مدل‌ها از چه چیزی استفاده می‌کنند؟
  • این استقرارها می‌توانند متفاوت باشند و ممکن است در طول زمان تغییر کنند؛ هیچ توصیهٔ provider ثابتی وجود ندارد.
  • تنظیم runtime فعلی را روی هر gateway با openclaw models status بررسی کنید.
  • برای عامل‌های حساس به امنیت/دارای ابزار، از قوی‌ترین مدل نسل جدید موجود استفاده کنید.
چگونه مدل‌ها را در لحظه عوض کنم (بدون راه‌اندازی دوباره)؟

از دستور /model به‌عنوان یک پیام مستقل استفاده کنید:

Code
/model sonnet/model opus/model gpt/model gpt-mini/model gemini/model gemini-flash/model gemini-flash-lite

این‌ها نام‌های مستعار داخلی هستند. نام‌های مستعار سفارشی را می‌توان از طریق agents.defaults.models اضافه کرد.

می‌توانید مدل‌های موجود را با /model، /model list یا /model status فهرست کنید.

/model/model list) یک انتخاب‌گر فشردهٔ شماره‌دار نشان می‌دهد. با شماره انتخاب کنید:

Code
/model 3

همچنین می‌توانید یک پروفایل احراز هویت خاص را برای provider اجبار کنید (برای هر نشست):

Code
/model opus@anthropic:default/model opus@anthropic:work

نکته: /model status نشان می‌دهد کدام عامل فعال است، کدام فایل auth-profiles.json استفاده می‌شود، و کدام پروفایل احراز هویت بعداً امتحان خواهد شد. همچنین endpoint پیکربندی‌شدهٔ provider (baseUrl) و حالت API (api) را در صورت موجود بودن نشان می‌دهد.

چگونه پروفایلی را که با @profile سنجاق کرده‌ام بردارم؟

/model را بدون پسوند @profile دوباره اجرا کنید:

Code
/model anthropic/claude-opus-4-6

اگر می‌خواهید به پیش‌فرض برگردید، آن را از /model انتخاب کنید (یا /model <default provider/model> را بفرستید). از /model status استفاده کنید تا تأیید کنید کدام پروفایل احراز هویت فعال است.

اگر دو provider یک شناسهٔ مدل یکسان ارائه کنند، /model از کدام استفاده می‌کند؟

/model provider/model همان مسیر دقیق provider را برای نشست انتخاب می‌کند.

برای مثال، qianfan/deepseek-v4-flash و deepseek/deepseek-v4-flash ارجاع‌های مدل متفاوتی هستند، هرچند هر دو شامل deepseek-v4-flash هستند. OpenClaw نباید فقط به‌خاطر تطابق شناسهٔ مدل بدون provider، بی‌صدا از یک provider به دیگری جابه‌جا شود.

ارجاع /model انتخاب‌شده توسط کاربر برای سیاست fallback نیز سخت‌گیرانه است. اگر آن provider/model انتخاب‌شده در دسترس نباشد، پاسخ به‌صورت قابل‌مشاهده شکست می‌خورد، به‌جای اینکه از agents.defaults.model.fallbacks پاسخ دهد. زنجیره‌های fallback پیکربندی‌شده همچنان برای پیش‌فرض‌های پیکربندی‌شده، primaryهای کار Cron، و وضعیت fallback انتخاب‌شدهٔ خودکار اعمال می‌شوند.

اگر اجرایی که از یک override غیرنشستی شروع شده اجازهٔ استفاده از fallback را داشته باشد، OpenClaw ابتدا provider/model درخواست‌شده را امتحان می‌کند، سپس fallbackهای پیکربندی‌شده را، و فقط پس از آن primary پیکربندی‌شده را. این کار مانع می‌شود شناسه‌های مدل تکراری بدون provider مستقیماً به provider پیش‌فرض برگردند.

مدل‌ها و failover مدل را ببینید.

آیا می‌توانم از GPT 5.5 برای کارهای روزانه و Codex 5.5 برای کدنویسی استفاده کنم؟

بله. انتخاب مدل و انتخاب runtime را جداگانه در نظر بگیرید:

  • عامل کدنویسی بومی Codex: agents.defaults.model.primary را روی openai/gpt-5.5 تنظیم کنید. وقتی احراز هویت اشتراک ChatGPT/Codex را می‌خواهید، با openclaw models auth login --provider openai-codex وارد شوید.
  • کارهای مستقیم OpenAI API خارج از حلقهٔ عامل: OPENAI_API_KEY را برای تصاویر، embeddingها، گفتار، realtime و دیگر سطح‌های غیرعاملی OpenAI API پیکربندی کنید.
  • احراز هویت کلید API عامل OpenAI: از /model openai/gpt-5.5 با یک پروفایل API-key مرتب‌شدهٔ openai-codex استفاده کنید.
  • زیرعامل‌ها: کارهای کدنویسی را به یک عامل متمرکز بر Codex با مدل openai/gpt-5.5 خودش مسیردهی کنید.

مدل‌ها و دستورهای اسلش را ببینید.

چگونه حالت سریع را برای GPT 5.5 پیکربندی کنم؟

از یک toggle نشستی یا یک پیش‌فرض پیکربندی استفاده کنید:

  • برای هر نشست: وقتی نشست از openai/gpt-5.5 استفاده می‌کند، /fast on را بفرستید.
  • پیش‌فرض برای هر مدل: agents.defaults.models["openai/gpt-5.5"].params.fastMode را روی true تنظیم کنید.

مثال:

json5
{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: true,          },        },      },    },  },}

برای OpenAI، حالت سریع در درخواست‌های بومی Responses پشتیبانی‌شده به service_tier = "priority" نگاشت می‌شود. overrideهای نشستی /fast بر پیش‌فرض‌های پیکربندی غلبه می‌کنند.

تفکر و حالت سریع و حالت سریع OpenAI را ببینید.

چرا "Model ... is not allowed" را می‌بینم و سپس پاسخی دریافت نمی‌کنم؟

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

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

آن خطا به‌جای پاسخ عادی برگردانده می‌شود. راه‌حل: مدل دقیق را به agents.defaults.models اضافه کنید، برای کاتالوگ‌های provider پویا یک wildcard provider مانند "provider/*": {} اضافه کنید، allowlist را بردارید، یا مدلی را از /model list انتخاب کنید. اگر دستور شامل --runtime codex هم بود، ابتدا allowlist را به‌روزرسانی کنید و سپس همان دستور /model provider/model --runtime codex را دوباره امتحان کنید.

چرا "Unknown model: minimax/MiniMax-M2.7" را می‌بینم؟

یعنی provider پیکربندی نشده است (هیچ پیکربندی provider یا پروفایل احراز هویت MiniMax پیدا نشده)، بنابراین مدل قابل resolve نیست.

چک‌لیست رفع مشکل:

  1. به نسخهٔ فعلی OpenClaw ارتقا دهید (یا از source main اجرا کنید)، سپس gateway را راه‌اندازی دوباره کنید.

  2. مطمئن شوید MiniMax پیکربندی شده است (wizard یا JSON)، یا احراز هویت MiniMax در env/auth profiles وجود دارد تا provider منطبق بتواند تزریق شود (MINIMAX_API_KEY برای minimax، MINIMAX_OAUTH_TOKEN یا OAuth ذخیره‌شدهٔ MiniMax برای minimax-portal).

  3. از شناسهٔ دقیق مدل (حساس به حروف بزرگ و کوچک) برای مسیر احراز هویت خود استفاده کنید: minimax/MiniMax-M2.7 یا minimax/MiniMax-M2.7-highspeed برای راه‌اندازی API-key، یا minimax-portal/MiniMax-M2.7 / minimax-portal/MiniMax-M2.7-highspeed برای راه‌اندازی OAuth.

  4. اجرا کنید:

    bash
    openclaw models list

    و از فهرست انتخاب کنید (یا /model list در چت).

MiniMax و مدل‌ها را ببینید.

آیا می‌توانم MiniMax را به‌عنوان پیش‌فرض و OpenAI را برای کارهای پیچیده استفاده کنم؟

بله. از MiniMax به‌عنوان پیش‌فرض استفاده کنید و در صورت نیاز مدل‌ها را برای هر نشست عوض کنید. Fallbackها برای خطاها هستند، نه «کارهای سخت»، پس از /model یا یک عامل جداگانه استفاده کنید.

گزینهٔ A: جابه‌جایی برای هر نشست

json5
{  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M2.7" },      models: {        "minimax/MiniMax-M2.7": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

سپس:

Code
/model gpt

گزینهٔ B: عامل‌های جداگانه

  • پیش‌فرض عامل A: MiniMax
  • پیش‌فرض عامل B: OpenAI
  • بر اساس عامل مسیردهی کنید یا برای جابه‌جایی از /agent استفاده کنید

مستندات: مدل‌ها، مسیردهی چندعاملی، MiniMax، OpenAI.

آیا opus / sonnet / gpt میان‌برهای داخلی هستند؟

بله. OpenClaw چند کوتاه‌نویسی پیش‌فرض ارائه می‌کند (فقط وقتی اعمال می‌شوند که مدل در agents.defaults.models وجود داشته باشد):

  • opusanthropic/claude-opus-4-7
  • sonnetanthropic/claude-sonnet-4-6
  • gptopenai/gpt-5.4
  • gpt-miniopenai/gpt-5.4-mini
  • gpt-nanoopenai/gpt-5.4-nano
  • geminigoogle/gemini-3.1-pro-preview
  • gemini-flashgoogle/gemini-3-flash-preview
  • gemini-flash-litegoogle/gemini-3.1-flash-lite-preview

اگر alias خودتان را با همان نام تنظیم کنید، مقدار شما اولویت دارد.

چگونه میان‌برهای مدل (aliasها) را تعریف/بازنویسی کنم؟

aliasها از agents.defaults.models.<modelId>.alias می‌آیند. نمونه:

json5
{  agents: {    defaults: {      model: { primary: "anthropic/claude-opus-4-6" },      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },        "anthropic/claude-haiku-4-5": { alias: "haiku" },      },    },  },}

سپس /model sonnet (یا /<alias> وقتی پشتیبانی شود) به همان شناسه مدل resolve می‌شود.

چگونه مدل‌هایی از providerهای دیگر مانند OpenRouter یا Z.AI اضافه کنم؟

OpenRouter (پرداخت به‌ازای توکن؛ مدل‌های متعدد):

json5
{  agents: {    defaults: {      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },    },  },  env: { OPENROUTER_API_KEY: "sk-or-..." },}

Z.AI (مدل‌های GLM):

json5
{  agents: {    defaults: {      model: { primary: "zai/glm-5" },      models: { "zai/glm-5": {} },    },  },  env: { ZAI_API_KEY: "..." },}

اگر به یک provider/model اشاره کنید اما کلید provider لازم وجود نداشته باشد، در زمان اجرا خطای احراز هویت می‌گیرید (مثلاً No API key found for provider "zai").

پس از افزودن یک agent جدید، کلید API برای provider پیدا نشد

این معمولاً یعنی agent جدید مخزن auth خالی دارد. auth برای هر agent جداست و در این مسیر ذخیره می‌شود:

Code
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

گزینه‌های رفع مشکل:

  • openclaw agents add <id> را اجرا کنید و auth را در طول wizard پیکربندی کنید.
  • یا فقط profileهای ایستای قابل‌حمل api_key / token را از مخزن auth agent اصلی به مخزن auth agent جدید کپی کنید.
  • برای profileهای OAuth، وقتی agent جدید به حساب خودش نیاز دارد از همان agent جدید وارد شوید؛ در غیر این صورت OpenClaw می‌تواند بدون clone کردن refresh tokenها، از agent پیش‌فرض/اصلی بخواند.

agentDir را بین agentها دوباره استفاده نکنید؛ این کار باعث تداخل auth/session می‌شود.

failover مدل و "همه مدل‌ها ناموفق بودند"

failover چگونه کار می‌کند؟

failover در دو مرحله انجام می‌شود:

  1. چرخش profile احراز هویت در همان provider.
  2. fallback مدل به مدل بعدی در agents.defaults.model.fallbacks.

cooldownها روی profileهای ناموفق اعمال می‌شوند (backoff نمایی)، بنابراین OpenClaw حتی وقتی یک provider با محدودیت نرخ روبه‌روست یا موقتاً دچار خطاست، می‌تواند به پاسخ‌گویی ادامه دهد.

bucket محدودیت نرخ فقط پاسخ‌های ساده 429 را شامل نمی‌شود. OpenClaw همچنین پیام‌هایی مانند Too many concurrent requests، ThrottlingException، concurrency limit reached، workers_ai ... quota limit exceeded، resource exhausted و محدودیت‌های دوره‌ای پنجره مصرف (weekly/monthly limit reached) را محدودیت نرخ شایسته failover تلقی می‌کند.

برخی پاسخ‌هایی که شبیه billing هستند 402 نیستند، و برخی پاسخ‌های HTTP 402 نیز در همان bucket گذرا می‌مانند. اگر provider روی 401 یا 403 متن billing صریح برگرداند، OpenClaw همچنان می‌تواند آن را در مسیر billing نگه دارد، اما matcherهای متن مخصوص provider در محدوده همان provideri می‌مانند که مالک آن‌هاست (برای مثال OpenRouter Key limit exceeded). اگر پیام 402 در عوض شبیه یک پنجره مصرف قابل تلاش مجدد یا محدودیت هزینه سازمان/فضای کاری باشد (daily limit reached, resets tomorrow، organization spending limit exceeded)، OpenClaw آن را rate_limit تلقی می‌کند، نه یک غیرفعال‌سازی billing طولانی.

خطاهای سرریز context متفاوت‌اند: امضاهایی مانند request_too_large، input exceeds the maximum number of tokens، input token count exceeds the maximum number of input tokens، input is too long for the model، یا ollama error: context length exceeded به‌جای پیش بردن fallback مدل، در مسیر Compaction/تلاش مجدد می‌مانند.

متن عمومی خطای سرور عمداً محدودتر از «هر چیزی که unknown/error در آن باشد» است. OpenClaw شکل‌های گذرای محدود به provider مانند An unknown error occurred خام از Anthropic، Provider returned error خام از OpenRouter، خطاهای stop-reason مانند Unhandled stop reason: error، payloadهای JSON api_error با متن گذرای سرور (internal server error، unknown error, 520، upstream error، backend error) و خطاهای provider-busy مانند ModelNotReadyException را وقتی context provider مطابقت داشته باشد، سیگنال‌های timeout/overloaded شایسته failover تلقی می‌کند. متن عمومی fallback داخلی مانند LLM request failed with an unknown error. محافظه‌کارانه می‌ماند و به‌تنهایی fallback مدل را فعال نمی‌کند.

معنای "No credentials found for profile anthropic:default" چیست؟

یعنی سیستم تلاش کرده از شناسه profile احراز هویت anthropic:default استفاده کند، اما نتوانسته credentialهای آن را در مخزن auth مورد انتظار پیدا کند.

چک‌لیست رفع مشکل:

  • تأیید کنید profileهای auth کجا قرار دارند (مسیرهای جدید در برابر legacy)
    • فعلی: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • legacy: ~/.openclaw/agent/* (با openclaw doctor migrate می‌شود)
  • تأیید کنید env var شما توسط Gateway بارگذاری شده است
    • اگر ANTHROPIC_API_KEY را در shell خود تنظیم کرده‌اید اما Gateway را از طریق systemd/launchd اجرا می‌کنید، ممکن است آن را به ارث نبرد. آن را در ~/.openclaw/.env قرار دهید یا env.shellEnv را فعال کنید.
  • مطمئن شوید agent درست را ویرایش می‌کنید
    • راه‌اندازی‌های چند-agent یعنی ممکن است چند فایل auth-profiles.json وجود داشته باشد.
  • وضعیت مدل/auth را sanity-check کنید
    • از openclaw models status برای دیدن مدل‌های پیکربندی‌شده و اینکه providerها authenticated هستند یا نه استفاده کنید.

چک‌لیست رفع مشکل برای "No credentials found for profile anthropic"

این یعنی اجرا به یک profile احراز هویت Anthropic pin شده، اما Gateway نمی‌تواند آن را در مخزن auth خود پیدا کند.

  • از Claude CLI استفاده کنید

    • روی میزبان gateway، openclaw models auth login --provider anthropic --method cli --set-default را اجرا کنید.
  • اگر می‌خواهید به‌جای آن از کلید API استفاده کنید

    • ANTHROPIC_API_KEY را در ~/.openclaw/.env روی میزبان gateway قرار دهید.

    • هر ترتیب pin شده‌ای را که profile گم‌شده را اجبار می‌کند پاک کنید:

      bash
      openclaw models auth order clear --provider anthropic
  • تأیید کنید commandها را روی میزبان gateway اجرا می‌کنید

    • در حالت remote، profileهای auth روی ماشین gateway قرار دارند، نه laptop شما.
چرا Google Gemini را هم امتحان کرد و شکست خورد؟

اگر config مدل شما Google Gemini را به‌عنوان fallback شامل شود (یا به shorthand مربوط به Gemini تغییر داده باشید)، OpenClaw آن را هنگام fallback مدل امتحان می‌کند. اگر credentialهای Google را پیکربندی نکرده باشید، No API key found for provider "google" را می‌بینید.

رفع مشکل: یا auth Google را فراهم کنید، یا مدل‌های Google را در agents.defaults.model.fallbacks / aliasها حذف/اجتناب کنید تا fallback به آنجا route نشود.

درخواست LLM رد شد: thinking signature required (Google Antigravity)

علت: history نشست شامل thinking blockهای بدون signature است (اغلب از یک stream لغوشده/جزئی). Google Antigravity برای thinking blockها به signature نیاز دارد.

رفع مشکل: OpenClaw اکنون thinking blockهای بدون امضا را برای Google Antigravity Claude حذف می‌کند. اگر هنوز ظاهر می‌شود، یک نشست جدید شروع کنید یا برای آن agent، /thinking off را تنظیم کنید.

profileهای auth: چه هستند و چگونه آن‌ها را مدیریت کنید

مرتبط: /concepts/oauth (flowهای OAuth، ذخیره‌سازی token، الگوهای چندحسابی)

profile auth چیست؟

profile auth یک رکورد credential نام‌گذاری‌شده (OAuth یا کلید API) است که به یک provider وابسته است. profileها در این مسیر قرار دارند:

Code
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

برای بررسی profileهای ذخیره‌شده بدون dump کردن secrets، openclaw models auth list را اجرا کنید (اختیاری: --provider <id> یا --json). برای جزئیات به Models CLI مراجعه کنید.

شناسه‌های profile معمول چه هستند؟

OpenClaw از شناسه‌های دارای پیشوند provider مانند این‌ها استفاده می‌کند:

  • anthropic:default (وقتی هویت ایمیلی وجود ندارد رایج است)
  • anthropic:<email> برای هویت‌های OAuth
  • شناسه‌های سفارشی که انتخاب می‌کنید (مثلاً anthropic:work)
آیا می‌توانم کنترل کنم کدام profile auth اول امتحان شود؟

بله. config از metadata اختیاری برای profileها و یک ترتیب برای هر provider (auth.order.<provider>) پشتیبانی می‌کند. این کار secrets را ذخیره نمی‌کند؛ شناسه‌ها را به provider/mode نگاشت می‌کند و ترتیب چرخش را تنظیم می‌کند.

OpenClaw ممکن است یک profile را اگر در cooldown کوتاه (محدودیت نرخ/timeout/خطاهای auth) یا وضعیت disabled طولانی‌تر (billing/اعتبار ناکافی) باشد، موقتاً skip کند. برای بررسی این موضوع، openclaw models status --json را اجرا کنید و auth.unusableProfiles را بررسی کنید. تنظیم: auth.cooldowns.billingBackoffHours*.

cooldownهای محدودیت نرخ می‌توانند وابسته به مدل باشند. profileای که برای یک مدل در cooldown است همچنان می‌تواند برای مدل هم‌خانواده روی همان provider قابل استفاده باشد، در حالی که پنجره‌های billing/disabled همچنان کل profile را مسدود می‌کنند.

همچنین می‌توانید از طریق CLI یک override ترتیب برای هر agent تنظیم کنید (که در auth-state.json همان agent ذخیره می‌شود):

bash
# Defaults to the configured default agent (omit --agent)openclaw models auth order get --provider anthropic # Lock rotation to a single profile (only try this one)openclaw models auth order set --provider anthropic anthropic:default # Or set an explicit order (fallback within provider)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Clear override (fall back to config auth.order / round-robin)openclaw models auth order clear --provider anthropic

برای هدف‌گیری یک agent مشخص:

bash
openclaw models auth order set --provider anthropic --agent main anthropic:default

برای تأیید اینکه واقعاً چه چیزی امتحان خواهد شد، استفاده کنید از:

bash
openclaw models status --probe

اگر یک profile ذخیره‌شده از ترتیب صریح حذف شده باشد، probe به‌جای اینکه آن را بی‌صدا امتحان کند، برای آن profile، excluded_by_auth_order را گزارش می‌دهد.

OAuth در برابر کلید API - تفاوت چیست؟

OpenClaw از هر دو پشتیبانی می‌کند:

  • OAuth اغلب از دسترسی اشتراکی استفاده می‌کند (در موارد قابل اعمال).
  • کلیدهای API از billing پرداخت به‌ازای توکن استفاده می‌کنند.

wizard به‌صورت صریح از Anthropic Claude CLI، OpenAI Codex OAuth و کلیدهای API پشتیبانی می‌کند.

مرتبط

Was this useful?