الأسئلة الشائعة: النماذج والمصادقة

يُضبط باستخدام:

agents.defaults.model.primary

النماذج هي مراجع بصيغة provider/model (مثال: openai/gpt-5.5، anthropic/claude-sonnet-4-6). عيّن دائمًا provider/model صراحةً. إذا حذفت المزوّد، يحاول OpenClaw أولًا مطابقة اسم مستعار، ثم مطابقة مزوّد مُهيأ وفريد لمعرّف النموذج، ثم يعود إلى المزوّد الافتراضي المُهيأ (مسار توافق مهمل). إذا لم يعد ذلك المزوّد يتضمن النموذج الافتراضي المُهيأ، يعود OpenClaw إلى أول مزوّد/نموذج مُهيأ بدلًا من استخدام إعداد افتراضي قديم.

استخدم أقوى نموذج من أحدث جيل توفره مجموعة مزوّديك، خصوصًا للوكلاء الذين يستخدمون الأدوات أو يتعاملون مع مدخلات غير موثوقة؛ فالنماذج الأضعف أو المفرطة في التكميم أكثر عرضة لحقن الموجّهات والسلوك غير الآمن (راجع الأمان). وجّه النماذج الأقل تكلفة إلى المحادثات الروتينية أو منخفضة المخاطر وفقًا لدور الوكيل.

وجّه النماذج لكل وكيل واستخدم الوكلاء الفرعيين لتنفيذ المهام الطويلة بالتوازي (يستهلك كل وكيل فرعي رموزه الخاصة). راجع النماذج، والوكلاء الفرعيين، وMiniMax، والنماذج المحلية.

غيّر حقول النموذج فقط، وتجنب استبدال الإعدادات بالكامل.

• /model في المحادثة (لكل جلسة، راجع أوامر الشرطة المائلة)
• openclaw models set ... (يحدّث إعدادات النموذج فقط)
• openclaw configure --section model (تفاعلي)
• عدّل agents.defaults.model مباشرةً في ~/.openclaw/openclaw.json

بالنسبة إلى تعديلات RPC، افحص أولًا باستخدام config.schema.lookup (المسار الموحّد، ووثائق المخطط السطحية، وملخصات العناصر الفرعية)، ثم فضّل config.patch على config.apply مع كائن جزئي. إذا كنت قد استبدلت الإعدادات بالفعل، فاستعدها من النسخة الاحتياطية أو شغّل openclaw doctor لإصلاحها.

الوثائق: النماذج، والتهيئة، والإعدادات، وDoctor.

نعم، Ollama هو المسار الأسهل. إعداد سريع:

1. ثبّت Ollama من https://ollama.com/download
2. نزّل نموذجًا محليًا، مثل ollama pull gemma4
3. لاستخدام النماذج السحابية أيضًا، شغّل ollama signin
4. شغّل openclaw onboard، واختر Ollama، ثم Local أو Cloud + Local

يمنحك Cloud + Local النماذج السحابية إلى جانب نماذج Ollama المحلية؛ ولا تحتاج النماذج السحابية مثل kimi-k2.5:cloud إلى تنزيل محلي. للتبديل يدويًا: openclaw models list، ثم openclaw models set ollama/<model>.

النماذج الأصغر أو شديدة التكميم أكثر عرضة لحقن الموجّهات. استخدم نماذج كبيرة لأي روبوت لديه صلاحية الوصول إلى الأدوات؛ وإذا استخدمت نماذج صغيرة رغم ذلك، ففعّل العزل وقوائم السماح الصارمة للأدوات.

الوثائق: Ollama، والنماذج المحلية، ومزوّدو النماذج، والأمان، والعزل.

أرسل /model <name> كرسالة مستقلة. راجع أوامر الشرطة المائلة للاطلاع على قائمة الأوامر الكاملة، بما فيها أداة الاختيار المرقمة (/model، و/model list، و/model 3)، والأمر /model default لمسح تجاوز الجلسة، والأمر /model status لعرض تفاصيل نقطة النهاية/وضع API.

افرض ملف تعريف مصادقة محددًا لكل جلسة باستخدام @profile:

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

لإلغاء تثبيت ملف تعريف ضُبط باستخدام @profile، أعد تشغيل /model من دون اللاحقة (مثل /model anthropic/claude-opus-4-6)، أو اختر الإعداد الافتراضي من /model. استخدم /model status للتأكد من ملف تعريف المصادقة النشط.

يحدد /model provider/model مسار ذلك المزوّد بالضبط. على سبيل المثال، يُعد qianfan/deepseek-v4-flash وdeepseek/deepseek-v4-flash مرجعين مختلفين رغم تطابق معرّف النموذج؛ ولا يبدّل OpenClaw المزوّدين بصمت عند مطابقة معرّف مجرد.

يكون مرجع /model الذي اختاره المستخدم صارمًا عند الرجوع الاحتياطي: إذا أصبح ذلك المزوّد/النموذج غير متاح، يفشل الرد بشكل ظاهر بدلًا من الرجوع إلى agents.defaults.model.fallbacks. تظل سلاسل الرجوع الاحتياطي المُهيأة مطبقة على الإعدادات الافتراضية المُهيأة، والنماذج الأساسية لمهام Cron، وحالة الرجوع الاحتياطي المحددة تلقائيًا. عندما يُسمح لتشغيل لا يستخدم تجاوزًا خاصًا بالجلسة بالرجوع الاحتياطي، يحاول OpenClaw أولًا المزوّد/النموذج المطلوب، ثم البدائل المُهيأة، ثم النموذج الأساسي المُهيأ؛ ولذلك لا تقفز معرّفات النماذج المجردة المتكررة مباشرةً إلى المزوّد الافتراضي.

راجع النماذج وتجاوز فشل النموذج.

نعم، اختيار النموذج واختيار بيئة التشغيل أمران منفصلان:

• وكيل البرمجة الأصلي Codex: عيّن agents.defaults.model.primary إلى openai/gpt-5.5. سجّل الدخول باستخدام openclaw models auth login --provider openai لمصادقة اشتراك ChatGPT/Codex.
• مهام OpenAI API المباشرة خارج حلقة الوكيل: هيّئ OPENAI_API_KEY للصور والتضمينات والكلام والوقت الفعلي وغيرها من واجهات OpenAI API غير الخاصة بالوكيل.
• مصادقة وكيل OpenAI باستخدام مفتاح API: استخدم /model openai/gpt-5.5 مع ملف تعريف مفتاح API مرتب تابع لـopenai.
• الوكلاء الفرعيون: وجّه مهام البرمجة إلى وكيل يركز على Codex وله نموذج openai/gpt-5.5 خاص به.

راجع النماذج وأوامر الشرطة المائلة.

• لكل جلسة: أرسل /fast on أثناء استخدام openai/gpt-5.5.
• كإعداد افتراضي لكل نموذج: عيّن agents.defaults.models["openai/gpt-5.5"].params.fastMode إلى true.
• حد الإيقاف التلقائي: يشغّل /fast auto أو params.fastMode: "auto" استدعاءات النموذج الجديدة بسرعة حتى بلوغ حد الإيقاف، ثم يشغّل استدعاءات إعادة المحاولة أو الرجوع الاحتياطي أو نتائج الأدوات أو المتابعة اللاحقة من دون الوضع السريع. القيمة الافتراضية لحد الإيقاف هي 60 ثانية؛ ويمكن تجاوزها باستخدام params.fastAutoOnSeconds في النموذج.

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: "auto",            fastAutoOnSeconds: 30,          },        },      },    },  },}

يتطابق الوضع السريع مع service_tier = "priority" في طلبات OpenAI Responses الأصلية؛ وتُحفظ قيم service_tier الحالية، ولا يعيد الوضع السريع كتابة reasoning أو text.verbosity. تتقدم تجاوزات /fast الخاصة بالجلسة على إعدادات التهيئة الافتراضية.

راجع التفكير والوضع السريع وقسم الوضع السريع ضمن الإعدادات المتقدمة في صفحة مزوّد OpenAI.

إذا ضُبط agents.defaults.models، فإنه يصبح قائمة السماح الخاصة بـ/model وتجاوزات الجلسة. يؤدي اختيار نموذج خارج تلك القائمة إلى إرجاع ما يلي بدلًا من رد عادي:

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/*": {} للفهارس الديناميكية، أو أزل قائمة السماح، أو اختر نموذجًا من /model list. إذا تضمن الأمر أيضًا --runtime codex، فحدّث قائمة السماح أولًا، ثم أعد محاولة الأمر نفسه /model provider/model --runtime codex.

إذا كنت تستخدم إصدارًا أقدم من OpenClaw، فقم بالترقية أولًا (أو شغّل من فرع المصدر main) وأعد تشغيل Gateway؛ فقد لا يكون MiniMax-M3 موجودًا بعد في فهرس الإصدار المثبّت لديك. بخلاف ذلك، يكون مزوّد MiniMax غير مُهيأ (لم يُعثر على إدخال للمزوّد أو ملف تعريف مصادقة)، ولذلك يتعذر حل النموذج. راجع قسم استكشاف الأخطاء وإصلاحها في صفحة مزوّد MiniMax للاطلاع على قائمة التحقق الكاملة للإصلاح، وجدول معرّفات المزوّد/النموذج، ومثال كتلة الإعدادات.

نعم. استخدم MiniMax كنموذج افتراضي وبدّل النماذج لكل جلسة؛ فالبدائل مخصصة للأخطاء، لا «للمهام الصعبة»، لذلك استخدم /model أو وكيلًا منفصلًا.

الخيار أ: التبديل لكل جلسة

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

ثم استخدم /model gpt.

الخيار ب: وكلاء منفصلون — يستخدم الوكيل أ MiniMax افتراضيًا، ويستخدم الوكيل ب OpenAI افتراضيًا؛ وجّه حسب الوكيل أو استخدم /agent للتبديل.

الوثائق: النماذج، وتوجيه الوكلاء المتعددين، وMiniMax، وOpenAI.

نعم، هذه اختصارات مضمّنة، ولا تُطبّق إلا عندما يكون النموذج المستهدف موجودًا في agents.defaults.models:

يتجاوز اسمك المستعار الذي يحمل الاسم نفسه الاسم المضمّن.

توجد الأسماء المستعارة في agents.defaults.models.<modelId>.alias:

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

بعد ذلك يُحل /model sonnet (أو /<alias> عند دعمه) إلى معرّف ذلك النموذج.

OpenRouter (الدفع لكل رمز؛ نماذج عديدة):

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

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

يؤدي غياب مفتاح المزوّد لمزوّد/نموذج مُشار إليه إلى ظهور خطأ مصادقة وقت التشغيل (مثل No API key found for provider "zai").

لم يُعثر على مفتاح API للمزوّد بعد إضافة وكيل جديد

يكون مخزن المصادقة للوكيل الجديد فارغًا؛ فالمصادقة خاصة بكل وكيل، وتُخزّن في:

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

الإصلاح: شغّل openclaw agents add <id> واضبط المصادقة في المعالج، أو انسخ فقط ملفات تعريف api_key/token الثابتة القابلة للنقل من مخزن الوكيل الرئيسي. بالنسبة إلى OAuth، سجّل الدخول من الوكيل الجديد عندما يحتاج إلى حسابه الخاص. راجع توجيه الوكلاء المتعددين للاطلاع على القواعد الكاملة لإعادة استخدام agentDir ومشاركة بيانات الاعتماد — لا تُعِد أبدًا استخدام agentDir بين الوكلاء.

مرحلتان:

1. تدوير ملفات تعريف المصادقة ضمن المزوّد نفسه.
2. الرجوع إلى نموذج بديل بالانتقال إلى النموذج التالي في agents.defaults.model.fallbacks.

تُطبَّق فترات تهدئة على ملفات التعريف التي تفشل (تراجع أُسّي)، لذا يواصل OpenClaw الاستجابة عندما يفرض المزوّد حدًا على المعدل أو يتعطل مؤقتًا.

تشمل فئة تحديد المعدل أكثر من مجرد 429: تُعدّ Too many concurrent requests وThrottlingException وconcurrency limit reached وworkers_ai ... quota limit exceeded وقيود نافذة الاستخدام الدورية (weekly/monthly limit reached) جميعها قيودًا على المعدل تستدعي تجاوز الفشل.

لا تكون استجابات الفوترة دائمًا 402، كما تبقى بعض استجابات 402 في فئة الأخطاء العابرة/تحديد المعدل بدلًا من مسار الفوترة. وقد يظل نص الفوترة الصريح في 401/403 موجّهًا إلى الفوترة؛ وتظل مطابقات النص الخاصة بكل مزوّد (مثل Key limit exceeded في OpenRouter) محصورة في المزوّد الخاص بها. وتُعامَل استجابة 402 التي تبدو كحد قابل لإعادة المحاولة لنافذة الاستخدام أو حد إنفاق للمؤسسة/مساحة العمل (daily limit reached, resets tomorrow وorganization spending limit exceeded) على أنها rate_limit، لا تعطيلًا طويلًا بسبب الفوترة.

تُستبعد أخطاء تجاوز السياق تمامًا من مسار الرجوع إلى البديل — فالتواقيع مثل 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 تنتقل إلى Compaction/إعادة المحاولة بدلًا من الانتقال إلى النموذج البديل التالي.

نطاق نص أخطاء الخادم العام أضيق من «أي شيء يحتوي على unknown/error بداخله». ومن أشكال الأخطاء العابرة المقيّدة بالمزوّد التي تُعد إشارات لتجاوز الفشل: رسالة Anthropic المجرّدة An unknown error occurred، ورسالة OpenRouter المجرّدة Provider returned error، وأخطاء سبب التوقف مثل Unhandled stop reason: error، وحمولات JSON من نوع api_error التي تحتوي على نص خادم عابر (internal server error وunknown error, 520 وupstream error وbackend error)، وأخطاء انشغال المزوّد مثل ModelNotReadyException عندما يتطابق سياق المزوّد. ويظل نص الرجوع الداخلي العام مثل LLM request failed with an unknown error. محافظًا ولا يؤدي إلى الرجوع إلى بديل بمفرده.

لا يحتوي معرّف ملف تعريف المصادقة anthropic:default على بيانات اعتماد في مخزن المصادقة المتوقع.

قائمة تحقق للإصلاح:

• تأكد من مكان ملفات التعريف — الحالي: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json؛ القديم: ~/.openclaw/agent/* (يرحّله openclaw doctor).
• تأكد من أن Gateway يحمّل متغير البيئة لديك. لن يصل ANTHROPIC_API_KEY المضبوط فقط في صدفتك إلى تشغيل Gateway عبر systemd/launchd — ضعه في ~/.openclaw/.env أو فعّل env.shellEnv.
• تأكد من أنك تعدّل الوكيل الصحيح — تحتوي إعدادات الوكلاء المتعددين على عدة ملفات auth-profiles.json.
• شغّل openclaw models status لرؤية النماذج المضبوطة وحالة مصادقة المزوّد.

بالنسبة إلى "No credentials found for profile anthropic" (من دون لاحقة بريد إلكتروني):

التشغيل مثبّت على ملف تعريف Anthropic لا يستطيع Gateway العثور عليه.

• استخدم Claude CLI: شغّل openclaw models auth login --provider anthropic --method cli --set-default على مضيف Gateway.

• يُفضّل استخدام مفتاح API بدلًا من ذلك: ضع ANTHROPIC_API_KEY في ~/.openclaw/.env على مضيف Gateway، ثم امسح أي ترتيب مثبّت يفرض استخدام ملف التعريف المفقود:

  openclaw models auth order clear --provider anthropic

• الوضع البعيد: توجد ملفات تعريف المصادقة على جهاز Gateway، لا على حاسوبك المحمول — تأكد من أنك تشغّل الأوامر هناك.

إذا كان ضبط النموذج لديك يتضمن Google Gemini كخيار بديل (أو إذا انتقلت إلى اختصار Gemini)، فسيحاول OpenClaw استخدامه أثناء الرجوع إلى البديل. يؤدي عدم ضبط بيانات اعتماد Google إلى No API key found for provider "google". الإصلاح: أضف مصادقة Google، أو أزل نماذج Google من agents.defaults.model.fallbacks/الأسماء المستعارة.

رُفض طلب LLM: توقيع التفكير مطلوب (Google Antigravity)

السبب: يحتوي سجل الجلسة على كتل تفكير بلا تواقيع (غالبًا من دفق أُجهض أو اكتمل جزئيًا)؛ يتطلب Google Antigravity تواقيع على كتل التفكير. يزيل OpenClaw كتل التفكير غير الموقعة لـ Google Antigravity Claude؛ وإذا استمرت المشكلة، فابدأ جلسة جديدة أو اضبط /thinking off لذلك الوكيل.

سجل بيانات اعتماد مُسمّى (OAuth أو مفتاح API) مرتبط بمزوّد، ومخزّن في:

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

افحص ملفات التعريف المحفوظة دون كشف الأسرار: openclaw models auth list (اختياريًا مع --provider <id> أو --json). راجع CLI للنماذج.

مسبوقة باسم المزوّد: anthropic:default (شائع عند عدم وجود هوية بريد إلكتروني)، وanthropic:<email> لهويات OAuth، أو معرّف مخصص تختاره (مثل anthropic:work).

نعم. يحدد ضبط auth.order.<provider> ترتيب التدوير لكل مزوّد (بيانات وصفية فقط — لا تُخزّن أسرار).

قد يتخطى OpenClaw ملف تعريف في فترة تهدئة قصيرة (بسبب قيود المعدل، أو انتهاء المهلة، أو فشل المصادقة) أو في حالة تعطيل أطول (بسبب الفوترة/عدم كفاية الرصيد). افحص ذلك باستخدام openclaw models status --json وتحقق من auth.unusableProfiles. اضبطه باستخدام auth.cooldowns.billingBackoffHours*. يمكن أن تكون فترات تهدئة تحديد المعدل مقيّدة بالنموذج — إذ يمكن لملف تعريف في فترة تهدئة لنموذج واحد أن يظل يخدم نموذجًا شقيقًا لدى المزوّد نفسه؛ بينما تحظر نوافذ الفوترة/التعطيل ملف التعريف بأكمله.

عيّن تجاوزًا للترتيب لكل وكيل (يُخزّن في auth-state.json لذلك الوكيل):

# Defaults to the configured default agent (omit --agent)openclaw models auth order get --provider anthropic # Lock rotation to a single profileopenclaw 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 # Target a specific agentopenclaw models auth order set --provider anthropic --agent main anthropic:default

تحقق مما سيُجرَّب فعليًا: openclaw models status --probe. ويُبلّغ عن ملف تعريف مخزّن محذوف من ترتيب صريح بالحالة excluded_by_auth_order بدلًا من تجربته بصمت.

• غالبًا ما يستخدم OAuth / تسجيل الدخول عبر CLI وصول الاشتراك عندما يدعمه المزوّد. بالنسبة إلى Anthropic، تستخدم الواجهة الخلفية لـ Claude CLI في OpenClaw الأمر claude -p من Claude Code، والذي تتعامل معه Anthropic حاليًا على أنه استخدام Agent SDK/برمجي يُحتسب ضمن حدود استخدام الاشتراك — راجع Anthropic للاطلاع على حالة إيقاف الفوترة مؤقتًا الحالية وروابط المصادر.
• تستخدم مفاتيح API فوترة بحسب عدد الرموز.

يدعم المعالج Anthropic Claude CLI، وOpenAI Codex OAuth، ومفاتيح API.