المصادقة

يدعم OpenClaw كلاً من OAuth ومفاتيح API لموفّري النماذج. بالنسبة إلى مضيف Gateway دائم التشغيل، يُعد مفتاح API الخيار الأكثر قابلية للتوقع؛ كما تعمل تدفقات الاشتراك/OAuth عندما تتوافق مع نموذج حسابك لدى الموفّر.

• تدفق OAuth الكامل وتخطيط التخزين: /concepts/oauth
• المصادقة المستندة إلى SecretRef (موفّرو env/file/exec): إدارة الأسرار
• أهلية بيانات الاعتماد ورموز الأسباب التي يستخدمها models status --probe: دلالات بيانات اعتماد المصادقة

الإعداد الموصى به: مفتاح API (لأي موفّر)

1. أنشئ مفتاح API في وحدة تحكم الموفّر.
2. ضعه على مضيف Gateway (الجهاز الذي يشغّل openclaw gateway):

export <PROVIDER>_API_KEY="..."openclaw models status

3. إذا كان Gateway يعمل تحت systemd/launchd، فضع المفتاح في ~/.openclaw/.env كي تتمكن الخدمة الخفية من قراءته:

cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF

4. أعد تشغيل عملية Gateway (أو الخدمة الخفية)، ثم تحقّق مجددًا:

openclaw models statusopenclaw doctor

يمكن لـopenclaw onboard أيضًا تخزين مفاتيح API لاستخدام الخدمة الخفية إذا لم ترغب في إدارة متغيرات البيئة بنفسك. راجع متغيرات البيئة للاطلاع على أسبقية تحميل البيئة كاملةً (env.shellEnv، و~/.openclaw/.env، وsystemd/launchd).

Anthropic: إعادة استخدام Claude CLI

تظل المصادقة عبر رمز إعداد Anthropic مسارًا مدعومًا. كما أن إعادة استخدام Claude CLI (الاستخدام بأسلوب claude -p) معتمدة لهذا التكامل؛ وعند توفر تسجيل دخول إلى Claude CLI على المضيف، يكون ذلك هو المسار المفضّل للاستخدام المحلي/المكتبي. أما بالنسبة إلى مضيفات Gateway طويلة الأمد، فيظل مفتاح Anthropic API الخيار الأكثر قابلية للتوقع، مع تحكم صريح في الفوترة من جانب الخادم.

إعداد المضيف لإعادة استخدام Claude CLI:

# شغّل على مضيف Gatewayclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

تتكون هذه العملية من خطوتين: تسجيل دخول Claude Code إلى Anthropic على المضيف، ثم توجيه OpenClaw لاختيار نماذج Anthropic عبر الواجهة الخلفية المحلية claude-cli وتخزين ملف تعريف مصادقة OpenClaw المطابق.

إذا لم يكن claude موجودًا في PATH، فثبّت Claude Code أو اضبط agents.defaults.cliBackends.claude-cli.command على مسار الملف التنفيذي.

إدخال الرمز المميز يدويًا

يعمل مع أي موفّر؛ ويكتب إلى مخزن مصادقة SQLite الخاص بكل وكيل ويحدّث الإعدادات:

openclaw models auth paste-token --provider openrouter

يقرأ OpenClaw ملفات تعريف المصادقة من ملف openclaw-agent.sqlite الخاص بكل وكيل. تنتمي تفاصيل نقطة النهاية (baseUrl، وapi، ومعرّفات النماذج، والرؤوس، والمُهل الزمنية) إلى models.providers.<id> في openclaw.json أو models.json، وليس إلى ملفات تعريف المصادقة.

إذا كان تثبيت أقدم لا يزال يحتوي على auth-profiles.json أو auth-state.json أو بنية مسطحة مثل { "openrouter": { "apiKey": "..." } }، فشغّل openclaw doctor --fix لاستيرادها إلى SQLite؛ يحتفظ doctor بنسخ احتياطية ذات طوابع زمنية بجانب ملفات JSON الأصلية.

مسارات المصادقة الخارجية مثل auth: "aws-sdk" في Bedrock ليست بيانات اعتماد. بالنسبة إلى مسار Bedrock مسمّى، اضبط auth.profiles.<id>.mode: "aws-sdk" في openclaw.json — ولا تكتب type: "aws-sdk" في مخزن ملفات تعريف المصادقة. ينقل openclaw doctor --fix علامات AWS SDK القديمة من مخزن بيانات الاعتماد إلى البيانات الوصفية للإعدادات.

بيانات اعتماد مدعومة بـSecretRef

• يمكن لبيانات اعتماد api_key استخدام keyRef: { source, provider, id }
• يمكن لبيانات اعتماد token استخدام tokenRef: { source, provider, id }
• ترفض ملفات التعريف بوضع OAuth بيانات اعتماد SecretRef: إذا كانت قيمة auth.profiles.<id>.mode هي "oauth"، فسيُرفض keyRef/tokenRef المدعوم بـSecretRef لذلك الملف.

التحقق من حالة مصادقة النموذج

openclaw models statusopenclaw doctor

فحص مناسب للأتمتة، يُرجع رمز الخروج 1 عند انتهاء الصلاحية/الفقدان، و2 عند اقتراب انتهاء الصلاحية:

openclaw models status --check

مسابر المصادقة الحية (أضف --probe-provider أو --probe-profile أو --probe-timeout أو --probe-concurrency أو --probe-max-tokens لتضييق النطاق):

openclaw models status --probe

ملاحظات:

• يمكن أن تأتي صفوف المسبر من ملفات تعريف المصادقة أو بيانات اعتماد البيئة أو models.json.
• إذا أغفل auth.order.<provider> ملف تعريف مخزنًا، فسيُبلغ المسبر عن excluded_by_auth_order لذلك الملف بدلًا من تجربته.
• إذا كانت المصادقة موجودة لكن OpenClaw لا يستطيع تحديد نموذج قابل للمسح لذلك الموفّر، فسيُبلغ المسبر عن status: no_model.
• يمكن أن تكون فترات التهدئة الناتجة عن حدود المعدل خاصة بالنموذج: إذ يمكن لملف تعريف في فترة تهدئة لنموذج واحد أن يواصل خدمة نموذج شقيق لدى الموفّر نفسه.

نصوص تشغيلية اختيارية (systemd/Termux): نصوص مراقبة المصادقة.

تدوير مفاتيح API ‏(Gateway)

يعيد بعض الموفّرين محاولة الطلب باستخدام مفتاح بديل مُعدّ عندما تصطدم المكالمة بحد معدل لدى الموفّر.

ترتيب أولوية المفاتيح لكل موفّر:

1. OPENCLAW_LIVE_<PROVIDER>_KEY (تجاوز واحد يثبّت مفتاحًا واحدًا)
2. <PROVIDER>_API_KEYS (قائمة مفصولة بفواصل أو مسافات أو فواصل منقوطة)
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_* (أي متغير بيئة بهذه البادئة)

يرجع موفّرا Google (google وgoogle-vertex) أيضًا إلى GOOGLE_API_KEY كخيار احتياطي. تُزال التكرارات من القائمة المجمّعة قبل الاستخدام.

ينتقل OpenClaw إلى المفتاح التالي فقط عندما تطابق رسالة الخطأ إحدى العبارات التالية: rate_limit أو rate limit أو 429 أو quota exceeded/quota_exceeded أو resource exhausted/resource_exhausted أو too many requests. لا تُعاد محاولة الأخطاء الأخرى باستخدام مفاتيح بديلة. إذا فشلت جميع المفاتيح، يُعاد الخطأ النهائي من المحاولة الأخيرة.

لا تؤدي إزالة المصادقة المحفوظة إلى إلغاء المفتاح لدى الموفّر — دوّره أو ألغِه من لوحة معلومات الموفّر عندما تحتاج إلى إبطاله من جانب الموفّر.

إزالة مصادقة الموفّر أثناء تشغيل Gateway

عند إزالة مصادقة موفّر عبر مستوى تحكم Gateway، يحذف OpenClaw ملفات تعريف المصادقة المحفوظة لذلك الموفّر ويوقف عمليات الدردشة/الوكيل النشطة التي يطابق موفّر نموذجها المحدد الموفّر المُزال. تُصدر العمليات الموقوفة أحداث الإلغاء/دورة الحياة المعتادة مع stopReason: "auth-revoked"، كي تتمكن العملاء المتصلة من إظهار أن العملية توقفت بسبب إزالة بيانات الاعتماد.

التحكم في بيانات الاعتماد المستخدمة

معرّفات OpenAI وopenai-codex القديمة

تستخدم ملفات تعريف مفاتيح OpenAI API وملفات تعريف OAuth الخاصة بـChatGPT/Codex معرّف الموفّر القياسي openai. استخدم معرّفات ملفات التعريف openai:* وauth.order.openai في الإعدادات الجديدة.

إذا رأيت openai-codex في إعدادات أقدم أو معرّفات ملفات تعريف المصادقة أو auth.order.openai-codex، فتعامل معه على أنه مُدخل ترحيل قديم — ولا تنشئ ملفات تعريف openai-codex جديدة. شغّل:

openclaw doctor --fixopenclaw models auth list --provider openai

يعيد doctor كتابة معرّفات ملفات التعريف القديمة openai-codex:* وإدخالات auth.order.openai-codex إلى مسار openai القياسي. للاطلاع على توجيه النماذج/وقت التشغيل الخاص بـOpenAI، راجع OpenAI.

أثناء تسجيل الدخول (CLI)

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

يفصل --profile-id بين عمليات تسجيل دخول OAuth المتعددة للموفّر نفسه داخل وكيل واحد.

يحذف --force ملفات تعريف المصادقة المحفوظة لذلك الموفّر في دليل الوكيل المحدد، ثم يعيد تشغيل تدفق المصادقة نفسه. استخدمه عندما يكون ملف تعريف محفوظ عالقًا أو منتهي الصلاحية أو مرتبطًا بالحساب الخطأ. وهو لا يلغي بيانات الاعتماد لدى الموفّر.

openclaw models auth login --provider anthropic --force

لكل جلسة (أمر دردشة)

• يثبّت /model <alias-or-id>@<profileId> بيانات اعتماد موفّر محددة للجلسة الحالية (أمثلة لمعرّفات ملفات التعريف: anthropic:default وanthropic:work).
• يعرض /model (أو /model list) أداة اختيار مدمجة؛ ويعرض /model status العرض الكامل (المرشحين + ملف تعريف المصادقة التالي، إضافة إلى تفاصيل نقطة نهاية الموفّر عند إعدادها).

إذا غيّرت ترتيب المصادقة أو تثبيت ملف التعريف لدردشة قيد التشغيل بالفعل، فأرسل /new أو /reset لبدء جلسة جديدة — تحتفظ الجلسات الحالية بتحديد النموذج/ملف التعريف الحالي حتى إعادة الضبط.

لكل وكيل (تجاوز CLI)

تُخزّن تجاوزات ترتيب المصادقة في حالة مصادقة SQLite الخاصة بذلك الوكيل:

openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

استخدم --agent <id> لاستهداف وكيل محدد؛ واحذفه لاستخدام الوكيل الافتراضي المُعدّ. يعرض openclaw models status --probe ملفات التعريف المخزنة المُغفلة على أنها excluded_by_auth_order بدلًا من تخطيها بصمت.

استكشاف الأخطاء وإصلاحها

"لم يتم العثور على بيانات اعتماد"

أعدّ مفتاح Anthropic API على مضيف Gateway، أو أعدّ مسار رمز إعداد Anthropic، ثم تحقّق مجددًا:

openclaw models status

الرمز المميز يوشك أن تنتهي صلاحيته/منتهي الصلاحية

شغّل openclaw models status لمعرفة ملف التعريف الذي توشك صلاحيته على الانتهاء. إذا كان ملف تعريف رمز Anthropic مفقودًا أو منتهي الصلاحية، فحدّثه عبر رمز الإعداد أو انتقل إلى مفتاح Anthropic API.

ذو صلة

• إدارة الأسرار
• الوصول عن بُعد
• تخزين المصادقة