دلالات بيانات اعتماد المصادقة

تحافظ هذه الدلالات على اتساق سلوك المصادقة وقت الاختيار ووقت التشغيل. وهي مشتركة بين:

• resolveAuthProfileOrder (ترتيب ملفات التعريف)
• resolveApiKeyForProfile (حل بيانات الاعتماد وقت التشغيل)
• openclaw models status --probe
• فحوصات المصادقة في openclaw doctor ‏(doctor-auth)

رموز أسباب الفحص المستقرة

تحمل نتائج الفحص فئة status ‏(ok، وauth، وrate_limit، وbilling، وtimeout، وformat، وunknown، وno_model) بالإضافة إلى reasonCode مستقر عندما لا يصل الفحص مطلقًا إلى استدعاء نموذج:

تُبلغ فحوصات الأهلية عن ok بوصفه رمز السبب لبيانات الاعتماد القابلة للاستخدام.

بيانات اعتماد الرموز المميزة

تدعم بيانات اعتماد الرموز المميزة (type: "token") قيمة token مضمنة و/أو tokenRef.

قواعد الأهلية

1. يكون ملف تعريف الرمز المميز غير مؤهل عندما يغيب كل من token وtokenRef ‏(missing_credential).
2. الحقل expires اختياري. وعند وجوده، يجب أن يكون عددًا محدودًا من مللي ثواني حقبة Unix، أكبر من 0 ولا يتجاوز الحد الأقصى للطابع الزمني لكائن Date في JavaScript ‏(8640000000000000).
3. إذا كانت قيمة expires غير صالحة (نوع خاطئ، أو NaN، أو 0، أو سالبة، أو غير محدودة، أو تتجاوز ذلك الحد الأقصى)، يكون ملف التعريف غير مؤهل مع invalid_expires.
4. إذا كانت قيمة expires في الماضي، يكون ملف التعريف غير مؤهل مع expired.
5. لا يتجاوز tokenRef التحقق من صحة expires.

قواعد الحل

1. تتطابق دلالات أداة الحل مع دلالات الأهلية للحقل expires.
2. بالنسبة إلى ملفات التعريف المؤهلة، يمكن حل مادة الرمز المميز من القيمة المضمنة أو tokenRef.
3. تؤدي المراجع التي يتعذر حلها إلى ظهور unresolved_ref في مخرجات models status --probe.

قابلية نقل نسخ الوكلاء

يُقرأ توارث مصادقة الوكيل بأسلوب القراءة العابرة. عندما لا يكون لدى الوكيل ملف تعريف محلي، فإنه يحل ملفات التعريف من مخزن الوكيل الافتراضي/الرئيسي وقت التشغيل من دون نسخ المادة السرية إلى مخزن بيانات الاعتماد الخاص به (agents/<agentId>/agent/openclaw-agent.sqlite).

تستخدم تدفقات النسخ الصريحة، مثل openclaw agents add، سياسة قابلية النقل التالية:

• تكون ملفات تعريف api_key وtoken قابلة للنقل ما لم تكن copyToAgents: false.
• لا تكون ملفات تعريف oauth قابلة للنقل افتراضيًا، لأن رموز التحديث قد تكون أحادية الاستخدام أو حساسة للتدوير.
• يمكن لتدفقات OAuth المملوكة للمزوّد الاشتراك باستخدام copyToAgents: true فقط عندما يكون من المعروف أن نسخ مادة التحديث بين الوكلاء آمن؛ ولا ينطبق الاشتراك إلا عندما يحمل ملف التعريف مادة وصول/تحديث مضمنة.

تظل ملفات التعريف غير القابلة للنقل متاحة من خلال التوارث بأسلوب القراءة العابرة، ما لم يسجّل الوكيل المستهدف الدخول بصورة منفصلة وينشئ ملف تعريف محليًا خاصًا به.

مسارات المصادقة المعتمدة على الإعدادات فقط

تُعد إدخالات auth.profiles التي تحتوي على mode: "aws-sdk" بيانات تعريف للتوجيه، وليست بيانات اعتماد مخزنة. وتكون صالحة عندما يستخدم المزوّد المستهدف models.providers.<id>.auth: "aws-sdk"، وهو المسار الذي تكتبه عملية إعداد Amazon Bedrock المملوكة للـ Plugin. قد تظهر معرّفات ملفات التعريف هذه في auth.order وتجاوزات الجلسة حتى عند عدم وجود إدخال مطابق في مخزن بيانات الاعتماد.

لا تكتب type: "aws-sdk" في مخزن بيانات الاعتماد؛ فبيانات الاعتماد المخزنة لا تكون إلا api_key أو token أو oauth. إذا احتوى ملف auth-profiles.json قديم على مثل هذه العلامة، فإن openclaw doctor --fix ينقلها إلى auth.profiles ويزيل العلامة من المخزن.

تصفية ترتيب المصادقة الصريح

• عند ضبط auth.order.<provider> أو تجاوز ترتيب مخزن المصادقة لمزوّد، لا يفحص models status --probe إلا معرّفات ملفات التعريف التي تظل ضمن ترتيب المصادقة المحلول لذلك المزوّد. ويتغلب التجاوز المخزن على إعداد auth.order.
• لا تُجرَّب لاحقًا وبصمت ملفات التعريف المخزنة لذلك المزوّد والمغفلة من الترتيب الصريح. تُبلغ مخرجات الفحص عنها باستخدام reasonCode: excluded_by_auth_order والتفصيل Excluded by auth.order for this provider.

حل هدف الفحص

• يمكن أن تأتي أهداف الفحص من ملفات تعريف المصادقة أو بيانات اعتماد البيئة أو models.json (قيمة source في النتيجة: profile أو env أو models.json).
• إذا كانت لدى مزوّد بيانات اعتماد لكن تعذر على OpenClaw حل نموذج مرشح قابل للفحص له، فإن models status --probe يُبلغ عن status: no_model مع reasonCode: no_model.

اكتشاف بيانات اعتماد CLI الخارجية

• لا تُكتشف بيانات الاعتماد الخاصة بوقت التشغيل فقط والمملوكة لواجهات CLI خارجية (Claude CLI لـ claude-cli، وCodex CLI لـ openai، وMiniMax CLI لـ minimax-portal) إلا عندما يكون المزوّد أو وقت التشغيل أو ملف تعريف المصادقة ضمن نطاق العملية الحالية، أو عندما يكون هناك بالفعل ملف تعريف محلي مخزن لذلك المصدر الخارجي.
• يختار مستدعو مخزن المصادقة وضعًا صريحًا لاكتشاف CLI الخارجية: none للمصادقة المحفوظة/الخاصة بالـ Plugin فقط، أو existing لتحديث ملفات تعريف CLI الخارجية المخزنة بالفعل، أو scoped لمجموعة محددة من المزوّدين/ملفات التعريف.
• تمرر مسارات القراءة فقط/الحالة allowKeychainPrompt: false؛ فهي تستخدم بيانات اعتماد CLI الخارجية المدعومة بالملفات فقط، ولا تقرأ نتائج سلسلة مفاتيح macOS أو تعيد استخدامها.

حارس سياسة SecretRef لـ OAuth

إدخال SecretRef مخصص لبيانات الاعتماد الثابتة فقط. بيانات اعتماد OAuth قابلة للتغيير وقت التشغيل (تحفظ تدفقات التحديث الرموز المميزة المدوّرة)، ولذلك ستؤدي مادة OAuth المدعومة بـ SecretRef إلى تقسيم الحالة القابلة للتغيير بين المخازن.

• إذا كانت بيانات اعتماد ملف تعريف من النوع type: "oauth"، تُرفض كائنات SecretRef لأي حقل من حقول مادة بيانات الاعتماد في ذلك الملف.
• إذا كانت قيمة auth.profiles.<id>.mode هي "oauth"، يُرفض إدخال keyRef/tokenRef المدعوم بـ SecretRef لذلك الملف.
• تُعد المخالفات حالات فشل قطعية (أخطاء مطروحة) في مسارات إعداد الأسرار عند بدء التشغيل/إعادة التحميل وحل ملفات التعريف.

رسائل متوافقة مع الإصدارات القديمة

للتوافق مع البرامج النصية، تُبقي أخطاء الفحص هذا السطر الأول دون تغيير:

Auth profile credentials are missing or expired.

تأتي التفاصيل الميسّرة للبشر ورمز السبب المستقر في الأسطر اللاحقة بالصيغة ↳ Auth reason [code]: ....

ذو صلة

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