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 سياسة جديدة. بالنسبة إلى Anthropic في بيئات الإنتاج، تظل المصادقة بمفتاح API المسار الموصى به والأكثر أمانًا.

يخزّن 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. أنشئ الرمز المميز بتشغيل claude setup-token على أي جهاز يحتوي على Claude Code، ثم ابدأ مسار رمز إعداد 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 ولا يقبل سوى مضيفي الاسترجاع المحلي؛ ويمكن تجاوزه باستخدام 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
• مرجع التهيئة - مفاتيح إعداد المصادقة