OAuth

يدعم OpenClaw بروتوكول OAuth («مصادقة الاشتراك») للموفّرين الذين يتيحونه، ولا سيما OpenAI Codex (ChatGPT OAuth) وإعادة استخدام Anthropic Claude CLI. وبالنسبة إلى Anthropic، يكون التقسيم العملي كما يلي:

• مفتاح Anthropic API: فوترة Anthropic API المعتادة.
• Anthropic Claude CLI / مصادقة الاشتراك داخل OpenClaw: أخبرنا موظفو Anthropic بأن هذا الاستخدام مسموح به مجددًا، لذا يتعامل OpenClaw مع إعادة استخدام Claude CLI واستخدام claude -p بوصفهما معتمدين لهذا التكامل ما لم تنشر Anthropic سياسة جديدة. ولا تزال المصادقة بمفتاح API هي المسار الموصى به والأكثر أمانًا لاستخدام Anthropic في بيئات الإنتاج.

يخزّن OpenClaw كلًا من المصادقة بمفتاح OpenAI API ومصادقة ChatGPT/Codex OAuth ضمن معرّف الموفّر الأساسي openai. أما معرّفات ملفات التعريف القديمة openai-codex:* وإدخالات auth.order.openai-codex فهي حالة قديمة يصلحها openclaw doctor --fix؛ استخدم معرّفات ملفات التعريف openai:* وauth.order.openai للإعدادات الجديدة.

تتناول هذه الصفحة:

• كيفية عمل تبادل الرموز عبر OAuth ‏(PKCE)
• موضع تخزين الرموز (وسبب ذلك)
• كيفية التعامل مع حسابات متعددة (ملفات التعريف + التجاوزات الخاصة بكل جلسة)

تعمل Plugins الخاصة بالموفّرين، التي تتضمن تدفق OAuth أو مفتاح API خاصًا بها، عبر نقطة الدخول نفسها:

openclaw models auth login --provider <id>

مستودع الرموز (سبب وجوده)

عادةً ما يُصدر موفّرو OAuth رمز تحديث جديدًا عند كل تسجيل دخول أو تحديث. ويبطل بعض الموفّرين رمز التحديث السابق عند إصدار رمز جديد للمستخدم أو التطبيق نفسه. والعرض العملي لذلك: تسجّل الدخول عبر OpenClaw وكذلك عبر Claude Code / Codex CLI، ثم يُسجّل خروج أحدهما لاحقًا بصورة عشوائية.

للحد من ذلك، يتعامل OpenClaw مع مخزن ملفات تعريف المصادقة بوصفه مستودعًا للرموز:

• يقرأ وقت التشغيل بيانات الاعتماد من موضع واحد لكل وكيل
• يمكن أن تتعايش ملفات تعريف متعددة ويجري توجيهها بصورة حتمية
• تعتمد إعادة استخدام CLI خارجي على الموفّر: بمجرد امتلاك OpenClaw ملف تعريف OAuth محليًا لموفّر، يصبح رمز التحديث المحلي هو المصدر الأساسي. وإذا رُفض رمز التحديث المحلي، يُبلغ OpenClaw عن ملف التعريف لإعادة المصادقة بدلًا من الرجوع إلى بيانات رموز CLI الخارجية. ويكون تمهيد Codex CLI أضيق نطاقًا: فلا يمكنه سوى تهيئة ملف تعريف فارغ على نمط openai:default قبل أن يمتلك OpenClaw مصادقة OAuth لذلك الموفّر؛ وبعد ذلك تظل عمليات التحديث التي يملكها OpenClaw هي المصدر الأساسي
• تحصر مسارات الحالة وبدء التشغيل اكتشاف CLI الخارجي في مجموعة الموفّرين المضبوطة مسبقًا، كي لا يُفحص مخزن تسجيل دخول CLI غير ذي صلة في إعداد يضم موفّرًا واحدًا

التخزين (موضع الرموز)

توجد الأسرار لكل وكيل، ويُستخدم الاسم المنطقي auth-profiles.json مفتاحًا لها (المخزن الأساسي هو قاعدة بيانات SQLite الخاصة بالوكيل؛ ويُحتفظ باسم JSON للتوافق وعرض الأدوات):

• ملفات تعريف المصادقة (OAuth + مفاتيح API + مراجع اختيارية على مستوى القيم): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• ملف التوافق القديم: ~/.openclaw/agents/<agentId>/agent/auth.json (تُزال إدخالات api_key الثابتة عند اكتشافها)

ملف قديم مخصص للاستيراد فقط (لا يزال مدعومًا، لكنه ليس المخزن الرئيسي):

• ~/.openclaw/credentials/oauth.json (يُستورد إلى مخزن ملفات تعريف المصادقة عند أول استخدام)

تراعي جميع المسارات المذكورة أعلاه أيضًا $OPENCLAW_STATE_DIR (تجاوز دليل الحالة). المرجع الكامل: /gateway/configuration-reference#auth-storage

للاطلاع على مراجع الأسرار الثابتة وسلوك تفعيل لقطة وقت التشغيل، راجع إدارة الأسرار.

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

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

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

تبادل OAuth (كيفية عمل تسجيل الدخول)

تُنفّذ تدفقات تسجيل الدخول التفاعلية في OpenClaw داخل openclaw/plugin-sdk/llm.ts وتُوصَل بالمعالجات الإرشادية والأوامر.

رمز إعداد Anthropic

شكل التدفق:

1. ابدأ مسار رمز إعداد Anthropic أو لصق الرمز من OpenClaw
2. يخزّن OpenClaw بيانات اعتماد Anthropic الناتجة في ملف تعريف مصادقة
3. يظل اختيار النموذج على anthropic/...
4. تظل ملفات تعريف مصادقة Anthropic الموجودة متاحة للتراجع والتحكم في الترتيب

OpenAI Codex (ChatGPT OAuth)

تُدعم مصادقة OpenAI Codex OAuth صراحةً للاستخدام خارج Codex CLI، بما في ذلك تدفقات عمل OpenClaw.

يستخدم أمر تسجيل الدخول معرّف موفّر OpenAI الأساسي:

openclaw models auth login --provider openai

استخدم --profile-id openai:<name> لحسابات ChatGPT/Codex OAuth متعددة ضمن وكيل واحد. لا تستخدم openai-codex:<name> لملفات التعريف الجديدة. ينقل Doctor تلك البادئة القديمة إلى معرّف ملف تعريف openai:* خالٍ من التعارضات؛ شغّل openclaw models auth list --provider openai بعد الإصلاح وقبل نسخ معرّفات ملفات التعريف إلى auth.order أو /model ...@<profileId>.

شكل التدفق (PKCE):

1. أنشئ أداة تحقق/اختبار PKCE وقيمة state عشوائية
2. افتح https://auth.openai.com/oauth/authorize?... (النطاق openid profile email offline_access)
3. حاول التقاط رد النداء على http://localhost:1455/auth/callback (يكون مضيف رد النداء افتراضيًا localhost ولا يقبل إلا مضيفات local loopback؛ ويمكن تجاوزه باستخدام OPENCLAW_OAUTH_CALLBACK_HOST)
4. إذا أمكنك لصق رمز قبل وصول رد النداء (أو كنت تعمل عن بُعد/دون واجهة وتعذّر ربط رد النداء)، فألصق عنوان URL لإعادة التوجيه/الرمز بدلًا من ذلك؛ يتسابق اللصق اليدوي مع رد نداء المتصفح، ويُعتمد أيهما يكتمل أولًا
5. بادل الرمز عبر https://auth.openai.com/oauth/token
6. استخرج accountId من رمز الوصول وخزّن { access, refresh, expires, accountId }

مسار المعالج الإرشادي هو openclaw onboard ← خيار المصادقة openai.

التحديث + انتهاء الصلاحية

تخزّن ملفات التعريف طابعًا زمنيًا باسم expires. وفي وقت التشغيل:

• إذا كانت expires في المستقبل، فاستخدم رمز الوصول المخزّن
• إذا انتهت صلاحيته، فحدّثه (تحت قفل ملف) واستبدل بيانات الاعتماد المخزّنة
• إذا قرأ وكيل ثانوي ملف تعريف OAuth موروثًا من الوكيل الرئيسي، فتُكتب نتيجة التحديث إلى مخزن الوكيل الرئيسي بدلًا من نسخ رمز التحديث إلى مخزن الوكيل الثانوي
• تُعاد قراءة بيانات اعتماد CLI المُدارة خارجيًا (Claude CLI وتمهيد Codex CLI محدود النطاق؛ راجع مستودع الرموز) بدلًا من استهلاك رمز تحديث منسوخ. وإذا فشل تحديث مُدار، يُبلغ OpenClaw عن ملف التعريف المتأثر لإعادة المصادقة بدلًا من إرجاع بيانات رموز CLI الخارجية.

تتم عملية التحديث تلقائيًا؛ ولا تحتاج عمومًا إلى إدارة الرموز يدويًا.

حسابات متعددة (ملفات التعريف) + التوجيه

نَمطان:

1) المفضّل: وكلاء منفصلون

إذا أردت ألّا يتفاعل حسابا «شخصي» و«عمل» مطلقًا، فاستخدم وكلاء معزولين (جلسات + بيانات اعتماد + مساحة عمل منفصلة):

openclaw agents add workopenclaw agents add personal

ثم اضبط المصادقة لكل وكيل (عبر المعالج الإرشادي) ووجّه المحادثات إلى الوكيل المناسب.

2) متقدم: ملفات تعريف متعددة في وكيل واحد

يدعم مخزن ملفات تعريف المصادقة عدة معرّفات لملفات التعريف للموفّر نفسه. اختر أيها يُستخدم:

• عموميًا عبر ترتيب الإعداد (auth.order)
• لكل جلسة عبر /model ...@<profileId>

مثال (تجاوز الجلسة):

• /model Opus@anthropic:work

اعرض معرّفات ملفات التعريف الموجودة باستخدام:

openclaw models auth list --provider <id>

وثائق ذات صلة:

• التبديل الاحتياطي للنماذج (قواعد التدوير + فترة التهدئة)
• أوامر الشرطة المائلة (واجهة الأوامر)

ذو صلة

• المصادقة - نظرة عامة على مصادقة موفّر النموذج
• الأسرار - تخزين بيانات الاعتماد وSecretRef
• مرجع الإعدادات - مفاتيح إعداد المصادقة