> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# دليل استخدام Codex لـ VS Code

> Codex 集成指南 - Ace Data Cloud

Codex هو وكيل برمجة أطلقته OpenAI. بالإضافة إلى واجهة سطر الأوامر CLI، فإنه يوفر أيضًا امتدادًا لـ VS Code يمكن من خلاله الدردشة في الشريط الجانبي للمحرر، قراءة الملفات، اقتباس السياق، توليد التعديلات ومعاينة التغييرات.

تشرح هذه المقالة كيفية تكوين واستخدام امتداد Codex في VS Code عبر وكيل متوافق مع OpenAI Responses من Ace Data Cloud. يستخدم امتداد Codex لـ VS Code وCodex CLI نفس نظام التكوين المحلي، لذا يكفي توجيه ملف `~/.codex/config.toml` إلى Ace Data Cloud لجعل Codex في VS Code يستخدم `https://api.acedata.cloud/v1`.

## عملية التسجيل

لاستخدام Codex، يمكنك أولاً الحصول على رمز API الخاص بك من [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للاحتفاظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

إذا لم تكن مسجلاً أو مسجلاً دخولًا، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لتسجيل حساب جديد أو تسجيل الدخول، وبعد ذلك ستعود تلقائيًا إلى الصفحة الحالية.

عند التسجيل لأول مرة، ستحصل على رصيد مجاني لتجربة خدمة Codex مجانًا.

## تثبيت امتداد Codex

ابحث عن `Codex` في سوق امتدادات VS Code وقم بتثبيت امتداد **Codex - OpenAI's coding agent** الذي أصدرته OpenAI. معرفه في Marketplace هو:

```text theme={null}
openai.chatgpt
```

يمكنك أيضًا تثبيته من سطر الأوامر:

```bash theme={null}
code --install-extension openai.chatgpt
```

بعد التثبيت، أعد تشغيل أو إعادة تحميل VS Code. إذا لم يظهر مدخل Codex، افتح لوحة الأوامر (macOS: `Cmd+Shift+P`، Windows/Linux: `Ctrl+Shift+P`) وابحث ونفذ:

```text theme={null}
Codex: Open Codex Sidebar
```

يظهر Codex بشكل افتراضي في الشريط الجانبي الأيمن لـ VS Code. يمكنك أيضًا سحبه إلى شريط النشاط الأيسر.

## تثبيت Codex CLI (للتحقق)

توضح الوثائق الرسمية أن امتداد Codex لـ VS Code وCodex CLI يستخدمان نفس طبقة التكوين. للتحقق من صلاحية رمز API والنموذج قبل تكوين VS Code، يُنصح بتثبيت Codex CLI أيضًا.

أحد الطرق الموصى بها هو التثبيت عبر npm، ويتطلب Node.js 18 أو أحدث:

```bash theme={null}
npm install -g @openai/codex
```

يمكن لمستخدمي macOS التثبيت عبر Homebrew:

```bash theme={null}
brew install --cask codex
```

بعد التثبيت، تحقق من توفر الأمر في الطرفية:

```bash theme={null}
codex --version
```

إذا كنت ترغب فقط في استخدام امتداد VS Code، يمكنك تخطي خطوة التحقق عبر CLI؛ سيظل يستخدم نفس ملف التكوين `~/.codex/config.toml`.

## تكوين API لـ Ace Data Cloud

يشارك امتداد Codex لـ VS Code وCodex CLI ملف التكوين. بشكل افتراضي، يطالب Codex بتسجيل الدخول إلى حساب OpenAI الرسمي أو تكوين مفتاح API الرسمي. لاستخدام Ace Data Cloud، يجب تكوين رمز API وملف `~/.codex/config.toml`.

### الخطوة الأولى: تعيين متغير البيئة

يوصى بكتابة رمز API في ملف تكوين Shell، مثل `~/.zshrc` أو `~/.bashrc` أو `~/.bash_profile`:

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

استبدل `{token}` برمز API الذي نسخته من لوحة تحكم Ace Data Cloud.

بعد التكوين، أعد فتح الطرفية أو نفذ أمر `source` المناسب لتفعيل التكوين فورًا:

```bash theme={null}
source ~/.zshrc
```

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

### الخطوة الثانية: تحرير ملف تكوين Codex

يقع ملف التكوين على مستوى المستخدم لـ Codex في `~/.codex/config.toml`. إذا لم يكن موجودًا، يمكنك إنشاؤه:

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

اكتب التكوين التالي:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

تفسير الحقول:

| الحقل                    | الوصف                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `model_provider`         | مزود النموذج الافتراضي، يشير إلى `[model_providers.acedatacloud]` أدناه                 |
| `model`                  | معرف النموذج الافتراضي المستخدم                                                         |
| `model_reasoning_effort` | قوة الاستدلال، القيم الشائعة: `low`، `medium`، `high`                                   |
| `approval_policy`        | سياسة التأكيد قبل تنفيذ الأوامر، يوصى بـ `on-request` للاستخدام اليومي                  |
| `sandbox_mode`           | صلاحيات الصندوق الرمل عند تنفيذ Codex للأوامر، يوصى بـ `workspace-write` للتطوير اليومي |
| `base_url`               | عنوان API المتوافق مع OpenAI لـ Ace Data Cloud                                          |
| `env_key`                | اسم متغير البيئة الذي يقرأ منه Codex رمز API                                            |
| `wire_api`               | نوع البروتوكول، لاستخدام OpenAI Responses API يجب أن يكون `responses`                   |

يمكنك أيضًا النقر على رمز الترس في أعلى يمين امتداد Codex، اختيار **Codex Settings > Open config.toml** لفتح هذا الملف مباشرة من VS Code.

### تكوين على مستوى المشروع

إذا أردت استخدام تكوين مختلف لمشروع معين فقط، يمكنك إنشاء `.codex/config.toml` في جذر المشروع. سيقرأ Codex هذا التكوين أولاً إذا كان المشروع موثوقًا (trusted).

مثال:

```toml theme={null}
model = "gpt-5-mini"
model_reasoning_effort = "medium"
```

يوصى بوضع رموز API الشخصية في متغيرات البيئة وعدم تضمينها في مستودع المشروع. كما يُنصح بتحديد ما إذا كان ملف `.codex/config.toml` على مستوى المشروع يجب رفعه حسب سياسة الفريق.

## مسح تسجيل الدخول المخزن لـ OpenAI

إذا كنت قد سجلت دخولك سابقًا بحساب OpenAI الرسمي في امتداد Codex، فقد يبقى تسجيل الدخول محفوظًا محليًا. قبل التبديل إلى وكيل Ace Data Cloud، يمكنك تشغيل الأمر في الطرفية:

```bash theme={null}
codex logout
```

إذا لم يكن الأمر متاحًا، يمكنك حذف ملف التخزين المؤقت محليًا:

```bash theme={null}
rm -f ~/.codex/auth.json
```

ثم أعد تشغيل أو إعادة تحميل VS Code.

## الاستخدام الأساسي

بعد الانتهاء من التكوين، افتح لوحة Codex في الجانب الأيسر أو الأيمن من VS Code وأدخل طلبك مباشرة. على سبيل المثال:

```text theme={null}
اشرح هيكل مجلدات المشروع الحالي وأشر إلى ملف الدخول الرئيسي.
```

يمكن لامتداد Codex استخدام الملفات والكود المحدد في المحرر كسياق. يمكنك أيضًا الإشارة إلى ملف باستخدام `@` في مربع الإدخال، مثل:

```text theme={null}
راجع @src/App.vue، وساعدني في تقسيم هذه الصفحة إلى مكونات أكثر وضوحًا.
```

إذا قمت بتحديد جزء من الكود، يمكنك تشغيل الأمر من لوحة الأوامر:

```text theme={null}
Codex: Add to Codex Thread
```

أو تشغيل:

```text theme={null}
Codex: Add File to Codex Thread
```

لإضافة الملف الحالي بالكامل إلى السياق.

## تبديل النموذج وقوة الاستدلال

يدعم امتداد Codex لـ VS Code تبديل النماذج من خلال محدد النموذج أسفل مربع الإدخال، ويمكنك أيضًا تعديل قوة الاستدلال. عند استخدام مزود مخصص من Ace Data Cloud، من الأفضل تعيين النموذج الافتراضي في `~/.codex/config.toml` ثم التبديل حسب الحاجة من الواجهة. التوصيات الافتراضية:

| السيناريو                              | النموذج الموصى به          | قوة الاستدلال |
| -------------------------------------- | -------------------------- | ------------- |
| قراءة الكود اليومية والتعديلات الصغيرة | `gpt-5-mini`               | `medium`      |
| مهام التطوير العادية                   | `gpt-5`                    | `high`        |
| إعادة هيكلة معقدة واستدلال عميق        | `gpt-5.5` أو `gpt-5.5-pro` | `high`        |
| مهام الاستدلال المعزز                  | `o3`                       | `high`        |

إذا لم يظهر النموذج المطلوب في الواجهة، يمكنك تعديل حقل `model` في `~/.codex/config.toml` ثم إعادة تشغيل أو إعادة تحميل VS Code. قائمة النماذج الكاملة متاحة في [وثائق خدمة OpenAI لـ Ace Data Cloud](https://platform.acedata.cloud/documents/openai).

## اختيار وضع العمل

يدعم امتداد Codex أوضاع عمل مختلفة. الأوضاع الشائعة:

| الوضع                 | السيناريو المناسب                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------- |
| `Chat`                | للمناقشة وشرح الكود والتخطيط فقط، دون تعديل الملفات مباشرة                                  |
| `Agent`               | للسماح لـ Codex بقراءة الملفات وتعديل الكود وتشغيل الأوامر الضرورية، موصى به للتطوير اليومي |
| `Agent (Full Access)` | صلاحيات أعلى مع وصول إلى الشبكة، مناسب للمواقف التي تعرف فيها المخاطر جيدًا                 |

يوصى باستخدام وضع `Agent` مع إبقاء `approval_policy = "on-request"`، بحيث يطلب Codex تأكيدًا قبل تنفيذ أوامر حساسة أو الوصول إلى مسارات خارج مساحة العمل أو الشبكة.

## التحقق من التكوين

يمكنك التحقق من عمل Codex عبر Ace Data Cloud باستخدام نفس التكوين في الطرفية:

```bash theme={null}
codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK"
```

إذا كان التكوين صحيحًا، سترى ردًا مثل:

```text theme={null}
ADC_Codex_OK
```

ثم عد إلى VS Code وافتح لوحة Codex، وأدخل سؤالًا بسيطًا:

```text theme={null}
اشرح في جملة واحدة غرض مساحة العمل الحالية.
```

يمكنك أيضًا مراجعة سجل الطلبات والتكاليف عبر [لوحة تحكم Ace Data Cloud - سجل الاستخدام](https://platform.acedata.cloud/console/usages)، ومراجعة الرصيد المتبقي عبر [لوحة تحكم Ace Data Cloud - قائمة التطبيقات](https://platform.acedata.cloud/console/applications).

## كيف يعمل

امتداد Codex لـ VS Code ليس نظام تكوين نموذج مستقل. يستخدم Codex CLI المحلي ويشارك طبقة التكوين:

1. يبدأ امتداد VS Code Codex ويقرأ ملف التكوين على مستوى المستخدم `~/.codex/config.toml`.
2. إذا كان المشروع الحالي موثوقًا ويوجد به `.codex/config.toml`، يحمّل Codex تكوين المشروع.
3. عندما يشير `model_provider` إلى `acedatacloud`، يقرأ Codex رمز API من `ACEDATACLOUD_API_KEY`.
4. تُرسل الطلبات عبر بروتوكول OpenAI Responses إلى `https://api.acedata.cloud/v1/responses`.
5. تتحقق Ace Data Cloud من الهوية، تفحص الرصيد، تعيد توجيه الطلبات، وتسجل الاستخدام.

لذلك، عادةً ما تحتاج إلى تكوين واحد فقط لكل من CLI وامتداد VS Code. بعد التحقق من CLI في الطرفية، يستخدم امتداد VS Code نفس التكوين.

## للمزيد من المعلومات

* [الوثائق الرسمية لامتداد Codex IDE](https://developers.openai.com/codex/ide)
* [مرجع إعدادات امتداد Codex IDE](https://developers.openai.com/codex/ide/settings)
* [أساسيات تكوين Codex CLI](https://developers.openai.com/codex/config-basic)
* [وثائق خدمة OpenAI لـ Ace Data Cloud](https://platform.acedata.cloud/documents/openai)