---
read_when:
    - العمل على حل ملفات تعريف المصادقة أو توجيه بيانات الاعتماد
    - تصحيح أخطاء مصادقة النموذج أو ترتيب ملفات التعريف
summary: الدلالات القياسية لأهلية بيانات الاعتماد وآلية حسمها لملفات تعريف المصادقة
title: دلالات بيانات اعتماد المصادقة
x-i18n:
    generated_at: "2026-07-12T05:31:58Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6b0516b1bb23f400d5ac5fd39a628736034440216ac22823eef061b38564dff0
    source_path: auth-credential-semantics.md
    workflow: 16
---

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

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

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

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

| `reasonCode`             | المعنى                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `excluded_by_auth_order` | أُغفل ملف التعريف من ترتيب المصادقة الصريح لمزوّده.                                        |
| `missing_credential`     | لم تُضبط بيانات اعتماد مضمنة أو SecretRef.                                                 |
| `expired`                | قيمة `expires` للرمز المميز تقع في الماضي.                                                 |
| `invalid_expires`        | قيمة `expires` ليست طابعًا زمنيًا صالحًا وموجبًا بنظام Unix بالمللي ثانية.                  |
| `unresolved_ref`         | تعذر حل SecretRef المضبوط.                                                                 |
| `ineligible_profile`     | ملف التعريف غير متوافق مع إعدادات المزوّد (بما في ذلك إدخال مفتاح مشوّه).                   |
| `no_model`               | بيانات الاعتماد موجودة، لكن لم يُحل أي نموذج مرشح قابل للفحص.                               |

تُبلغ فحوصات الأهلية عن `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]: ...`.

## ذو صلة

- [إدارة الأسرار](/ar/gateway/secrets)
- [تخزين المصادقة](/ar/concepts/oauth)