تركيب Codex ليس صعبًا، ولكن ما يعيق العمل حقًا هو عملية الاتصال: أين أضع مفتاح API، كيف أكتب ملف config.toml، ما الفروق بين Windows و macOS، لماذا لا يقرأ VS Code المتغيرات في الطرفية، هل يجب تثبيت النموذج بشكل ثابت...

إذا كنت تريد فقط تشغيل Codex بسرعة، يمكنك تقليل الإعدادات إلى ثلاثة قيم:

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

بعد الانتهاء، يمكن لمشاريع CLI و Desktop و VS Code مشاركة ملف ~/.codex/config.toml، ويتم اختيار النموذج مباشرة عند التشغيل، دون الحاجة لتعديل الإعدادات باستمرار عند تغيير النموذج.

وفيما يلي خطوات إعداد من الصفر.

التحضيرات

قبل البدء، يرجى التأكد من:

  • التسجيل وتسجيل الدخول إلى Ace Data Cloud
  • إنشاء أو وجود تطبيق متاح
  • تثبيت Node.js و npm على جهازك
  • القدرة على استخدام الطرفية أو PowerShell
  • الاستعداد لاستخدام أحد أدوات Codex: CLI، Desktop، أو إضافة VS Code

الخطوة الأولى: الحصول على مفتاح API من Ace Data Cloud

افتح قائمة تطبيقات Ace Data Cloud، وادخل إلى التطبيق المتاح ونسخ مفتاح API.

ملاحظات مهمة:

  • مفتاح API هو بيانات حساسة، لا تضعه في مستودعات عامة
  • لا تضع المفتاح الحقيقي في لقطات الشاشة التعليمية
  • يُنصح بإنشاء وإدارة المفاتيح حسب البيئة أو الاستخدام
  • عند الشك في التسريب، قم بتغييره أو إلغائه فورًا

نستخدم هنا متغير البيئة ACEDATACLOUD_API_KEY لتجنب كتابة المفتاح بشكل صريح في ملف الإعدادات الخاص بـ Codex.

الخطوة الثانية: تثبيت Codex CLI

قم بتثبيت Codex عبر npm بشكل عالمي:

npm install -g @openai/codex

ثم تحقق من التثبيت:

codex --version

إذا ظهرت رسالة أن الأمر غير موجود، تأكد من أن مجلد تنفيذ npm العالمي مضاف إلى متغير PATH، ثم أعد فتح الطرفية.

إذا كنت تستخدم VS Code بشكل رئيسي، يمكنك أيضًا تثبيت إضافة Codex من OpenAI:

code --install-extension openai.chatgpt

ملف الإعدادات مشترك بين CLI و VS Code، لذا يُنصح بتكوين Provider ومتغيرات البيئة أولاً، ثم فتح المحرر للتحقق.

الخطوة الثالثة: إعداد متغير بيئة API Key

macOS / Linux: للجلسة الحالية

export ACEDATACLOUD_API_KEY="مفتاح API الخاص بك"

هذا الأمر ينفذ فقط للجلسة الحالية وعملياتها الفرعية. عند إغلاق الطرفية، يختفي المتغير.

macOS / Linux: بشكل دائم

إذا كنت تستخدم Zsh:

echo 'export ACEDATACLOUD_API_KEY="مفتاح API الخاص بك"' >> ~/.zshrc
source ~/.zshrc

إذا كنت تستخدم Bash:

echo 'export ACEDATACLOUD_API_KEY="مفتاح API الخاص بك"' >> ~/.bashrc
source ~/.bashrc

لا تنسَ عدم نسخ إعدادات shell التي تحتوي على المفتاح الحقيقي على أجهزة مشتركة، ويجب إدارة المفاتيح بشكل آمن مع الحد الأدنى من الصلاحيات.

Windows PowerShell

setx ACEDATACLOUD_API_KEY "مفتاح API الخاص بك"

بعد تنفيذ الأمر، أغلق وأعد فتح PowerShell. ملاحظة: setx لا يحدث المتغير في الجلسة الحالية تلقائيًا، لذا قد لا يقرأها الطرفية أو VS Code إلا بعد إعادة التشغيل.

لإعداد المتغير مؤقتًا للجلسة الحالية فقط:

$env:ACEDATACLOUD_API_KEY="مفتاح API الخاص بك"

الخطوة الرابعة: إنشاء أو تحرير ملف config.toml

ملف الإعدادات المشترك بين CLI و Desktop و VS Code هو:

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

إذا لم يكن المجلد موجودًا، أنشئه أولاً.

على macOS / Linux:

mkdir -p ~/.codex

ثم أضف المحتوى التالي:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

أما على Windows، فالمحتوى مشابه لكن مع تغيير أمر التوثيق ليعمل عبر PowerShell:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

يجب أن تتطابق الأسماء التالية تمامًا:

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

ويجب أن يتضمن الـ Base URL /v1.

الخطوة الخامسة: تشغيل Codex واختيار النموذج

بعد حفظ الإعدادات، أعد تشغيل الطرفية ثم نفذ:

codex

داخل واجهة Codex، نفذ الأمر:

/model

وتحقق من أن المزود هو acedatacloud، ثم اختر النموذج من القائمة.

لا يلزم تثبيت النموذج بشكل ثابت في الإعدادات. فصل اختيار المزود عن اختيار النموذج يقلل من الحاجة لتعديل ملف TOML عند التبديل. النموذج الفعلي والتوافر يتغيران باستمرار، ويجب الاعتماد على /model وواجهة المنصة في الوقت الحقيقي.

الخطوة السادسة: التحقق باستخدام طلب بسيط

لا تطلب من Codex إعادة هيكلة المستودع بالكامل مباشرة. أرسل طلبًا بسيطًا وسريعًا لتقييم النتيجة، مثل:

请概括当前项目的目录结构，不要修改任何文件。

ثم تحقق من وصول الطلب عبر تاريخ استخدام Ace Data Cloud، وتأكد من الحالة والاستهلاك.

إذا نجح الطلب البسيط، يمكنك بعد ذلك التحقق من قراءة الملفات، وتوليد المقترحات، وتعديل الكود، وتشغيل الاختبارات تدريجيًا.

إعدادات VS Code

ملحق VS Code يقرأ نفس ملف ~/.codex/config.toml، لكن مدى رؤيته لمفتاح API يعتمد على بيئة تشغيل الملحق.

بعد التكوين، أغلق VS Code تمامًا وأعد فتحه. على macOS / Linux، إذا لم يقرأ المتغيرات من الواجهة الرسومية، يمكنك تشغيل:

code .

من طرفية تحتوي على متغيرات البيئة التي أعددتها.

البيئات التي تتطلب إعداد المتغيرات بشكل خاص:

  • Remote SSH: على الجهاز البعيد
  • WSL: داخل بيئة WSL
  • Dev Container: داخل حاوية
  • Codespaces أو بيئات عن بُعد مماثلة

إعداد المتغيرات في الطرفية المحلية لا يضمن تلقائيًا أن يراها الملحق عند التشغيل عن بُعد.

إعدادات Desktop

تطبيق Desktop يشارك ملف الإعدادات مع CLI، لكنه قد لا يلتقط المتغيرات التي تم إعدادها مؤقتًا في الطرفية.

إذا لم يقرأ المفتاح:

  1. اجعله دائمًا أو على مستوى النظام
  2. أغلق تطبيق Desktop تمامًا
  3. أعد تشغيله
  4. تحقق من إعداد المزود والنموذج

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

1. خطأ 401 أو Unauthorized أو مفتاح غير صحيح

تحقق من التالي:

  1. هل نسخت المفتاح بشكل كامل؟
  2. هل اسم متغير البيئة هو ACEDATACLOUD_API_KEY؟
  3. هل أعدت تشغيل العملية بعد إعداد المتغير؟
  4. هل أمر auth.command مناسب لنظام التشغيل الخاص بك؟
  5. هل المفتاح لا يزال صالحًا؟ لا تقم بإخراج المفتاح الكامل إلى السجل أو الدردشة. يمكنك استخدام طريقة التحقق فقط من "وجوده" للتحقق من المتغير.

macOS / Linux:

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "المفتاح مضبوط"; else echo "المفتاح مفقود"; fi

PowerShell:

if ($env:ACEDATACLOUD_API_KEY) { "المفتاح مضبوط" } else { "المفتاح مفقود" }

2. لم يتحول المزود إلى acedatacloud

تأكد من مسار ملف التكوين وطبقات TOML. الأخطاء الشائعة تشمل:

  • كتابة اسم الملف كـ config.toml.txt
  • تحرير ملف في دليل مستخدم آخر
  • عدم تطابق اسم الجدول
  • أخطاء في علامات الاقتباس أو تنسيق المصفوفة
  • عدم إعادة تشغيل العميل بعد الحفظ

3. فشل طلب عنوان URL الأساسي

تأكد من أن العنوان هو:

https://api.acedata.cloud/v1

لا تتجاهل https:// أو النهاية /v1، ولا تستخدم عنوان صفحة وحدة التحكم بشكل خاطئ.

4. يمكن استخدام CLI، ولا يمكن استخدام VS Code

غالبًا، ليست مشكلة في تكوين المزود، بل أن عملية VS Code لم تقرأ متغيرات البيئة. قم بتشغيل code . من طرفية تحتوي على المتغيرات المعدة، أو قم بإعادة تشغيل VS Code بعد تكوين متغيرات النظام على مستوى النظام.

5. لا يمكن قراءة المفتاح في WSL أو SSH أو الحاويات

يجب إعداد متغيرات البيئة في البيئة التي يعمل فيها Codex أو الإضافة. setx على Windows لا يكتب تلقائيًا إلى WSL؛ والمتغيرات المحلية لن تنتقل تلقائيًا إلى مضيف SSH البعيد أو الحاوية.

6. لا يمكن العثور على النموذج المطلوب

لا تخمن معرف النموذج القديم يدويًا. استخدم /model لعرض الخيارات الحية، وتحقق من أذونات التطبيق، الرصيد، والمزود الحالي.

7. تصل الطلبات ولكن لا يمكن إكمال المهام المعقدة

ابدأ بتضييق نطاق المهمة: اجعل Codex يقرأ فقط التحليل، ويعرض الخطط، ثم اسمح بالتعديلات والاختبارات تدريجيًا. نجاح الاتصال بالنموذج لا يعني أن جميع مهام المستودعات يجب أن تكتمل مرة واحدة؛ التغييرات المعقدة لا تزال تتطلب معايير قبول واضحة، واختبارات، ومراجعة يدوية.

قائمة فحص التحقق من التكوين الموصى بها

قبل تقديم المهمة الرسمية الأولى، تحقق من كل بند:

  • حصلت على مفتاح API صالح من قائمة التطبيقات
  • تم حفظ المفتاح في ACEDATACLOUD_API_KEY
  • لم تكتب المفتاح في مستودع Git
  • model_provider هو acedatacloud
  • عنوان URL الأساسي هو https://api.acedata.cloud/v1
  • auth.command يتوافق مع نظام التشغيل
  • أعدت تشغيل Codex أو VS Code بالكامل
  • /model يعرض المزود والنموذج
  • طلب الاختبار الأدنى ناجح
  • يمكن رؤية سجل الاستخدام في سجل التاريخ

مزود واحد، يقلل من التكرار في التكوين

الهدف من هذا الأسلوب في الاتصال ليس كتابة ملف TOML أكثر، بل بناء حدود ثابتة:

  • إدارة مفتاح API بواسطة متغيرات البيئة
  • إدارة اتصال المزود بواسطة config.toml
  • اختيار النموذج داخل Codex حسب المهمة
  • عرض سجلات الاستدعاء والاستهلاك في وحدة تحكم Ace Data Cloud
  • مشاركة تكوين واحد بين CLI، سطح المكتب، وVS Code

عندما يتم فصل المصادقة، المزود، واختيار النموذج بوضوح، ستتمكن من تحديد العديد من المشاكل المتعلقة بـ "لماذا لا يمكن استخدام Codex" بسرعة، دون الحاجة إلى تسجيل الدخول مرارًا، أو إعادة التثبيت، أو نسخ تكوينات متعددة.

افتح مركز تكوين Codex للاطلاع على الأدلة الرسمية لمختلف العملاء، أو توجه إلى قائمة التطبيقات للحصول على مفتاح API.

المراجع