# بدء سريع مع Codex

> ⚡ **موصى به: الإعداد بنقرة واحدة** — أمر `curl -fsSL https://qcode.cc/install/codex.sh | bash` (في Windows: `irm https://qcode.cc/install/codex.ps1 | iex`) يثبّت CLI، ويكتب ملف إعداد `~/.codex`، ويتحقق من الاتصال. راجع [سكربت الإعداد بنقرة واحدة](/docs/getting-started/one-click-install). تابع القراءة للإعداد اليدوي.

إذا كنت تستخدم Claude Code بالفعل، فسيصبح Codex CLI جاهزًا للعمل لديك خلال **5 دقائق** باتباع هذا الدليل. تتشاركان حصة خطة QCode.cc وتستخدمان مفتاح API نفسه، لذا يمكنك التبديل بينهما بحرية بعد إعدادهما.

إذا لم يكن لديك حساب QCode.cc بعد، فاختر أولًا [خطة واحصل على مفتاحك](/docs/getting-started/choose-a-plan) (يعمل المفتاح بالطريقة نفسها أيًّا كان الخيار الذي تختاره).

---

## المتطلبات المسبقة

قبل البدء، تأكد من أن بيئتك تستوفي هذه المتطلبات:

| المتطلب | الإصدار | كيفية التحقق |
|-------------|---------|-------------|
| Node.js | v22 أو أحدث | `node --version` |
| npm | v10 أو أحدث | `npm --version` |
| Git | أي إصدار | `git --version` |
| نظام التشغيل | macOS / Linux / Windows (WSL) | - |
| مفتاح QCode.cc | مفتاح API يبدأ بـ `cr_` | [لوحة التحكم](https://qcode.cc/dashboard) |

> **ملاحظة**: تعمل بيئة العزل على مستوى النواة في Codex بأفضل شكل على Linux. كما أن macOS وWindows WSL مدعومان بالكامل أيضًا، غير أن بعض ميزات بيئة العزل قد تكون محدودة.

---

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

اختر إحدى طرق التثبيت التالية:

### الخيار A: التثبيت العام عبر npm (موصى به)

```bash
npm install -g @openai/codex

# Users in China can speed this up with the Taobao mirror
npm install -g @openai/codex --registry=https://registry.npmmirror.com
```

### الخيار B: Homebrew (macOS)

```bash
brew install --cask codex
```

### الخيار C: البناء من المصدر

```bash
git clone https://github.com/openai/codex.git
cd codex
cargo build --release
cp target/release/codex ~/.local/bin/
```

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

```bash
codex --version
# should print a version (trust `codex --version` on this machine, not a stale number from the web)
```

---
## الخطوة 2: إعداد QCode.cc

### 2.1 إنشاء دليل الإعدادات

```bash
mkdir -p ~/.codex
```

### 2.2 كتابة config.toml

أنشئ `~/.codex/config.toml`:

```toml
model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
```

مرجع الإعدادات:

| الحقل | الوصف |
|-------|-------------|
| `model_provider` | استخدم المزوّد المخصص `qcode` (الاسم متروك لك، ما دام يطابق `[model_providers.<name>]`) |
| `model` | النموذج الافتراضي، ويُوصى بـ `gpt-6.1-sol`؛ راجع «النماذج المتاحة» أدناه |
| `model_reasoning_effort` | عمق الاستدلال، مثل `low` / `medium` / `high`؛ تعتمد المستويات المتاحة على النموذج |
| `base_url` | نقطة نهاية QCode.cc العالمية (`api.qcode.cc`؛ يمكن للبر الرئيسي الصيني استخدام `asia.qcode.cc`، وأمريكا الشمالية / أوروبا `us.qcode.cc`) |
| `wire_api` | بروتوكول API، اضبطه على `responses` |
| `requires_openai_auth` | استخدم مصادقة بنمط OpenAI؛ يُقرأ المفتاح من `OPENAI_API_KEY` في `~/.codex/auth.json`. عند الضبط على `true`، يتجاهل Codex قيمة `env_key` (الوثائق الرسمية) |

### 2.3 إنشاء auth.json

أنشئ `~/.codex/auth.json`:

```json
{
  "OPENAI_API_KEY": "cr_your_key_here"
}
```

> استبدل `cr_your_key_here` بمفتاح API من [لوحة تحكم QCode.cc](https://qcode.cc/dashboard) الخاصة بك.

### 2.4 ضبط متغيرات البيئة

لتمرير المفتاح عبر متغير بيئة بدلًا من ذلك، استبدل `requires_openai_auth = true` في `[model_providers.qcode]` بـ `env_key = "QCODE_API_KEY"` ثم صدّر ذلك المتغير. **استخدم أحد الخيارين فقط**: تنص الوثائق الرسمية على أن Codex يتجاهل `env_key` عندما يكون `requires_openai_auth = true`. الإعداد الكامل للبديل الخاص بمتغير البيئة:

```toml
model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
env_key = "QCODE_API_KEY"
```

ثم اضبط متغير البيئة:

```bash
# Temporary (current terminal session only)
export QCODE_API_KEY="cr_your_key_here"

# Permanent (Bash users)
echo 'export QCODE_API_KEY="cr_your_key_here"' >> ~/.bashrc
source ~/.bashrc

# Permanent (Zsh users)
echo 'export QCODE_API_KEY="cr_your_key_here"' >> ~/.zshrc
source ~/.zshrc
```

> **نصيحة**: هذا هو المفتاح نفسه الذي تستخدمه مع Claude Code. إذا كنت تستخدم Claude Code بالفعل، فستجد المفتاح في المكان نفسه على [لوحة التحكم](https://qcode.cc/dashboard).

---
## الخطوة 3: التحقق من الإعداد

نفّذ مهمة بسيطة لاختبار الاتصال:

```bash
codex "print hello world"
```

إذا بدأ Codex بشكل طبيعي وأعاد استجابة، فإن الإعداد ناجح.

### قائمة التحقق

- يبدأ Codex دون أخطاء
- تُوجَّه طلبات API عبر QCode.cc (دون انتهاء مهل الشبكة)
- تعمل استجابات النموذج بشكل صحيح (يفهم تعليماتك)

إذا واجهت مشكلات، فانتقل إلى قسم [الأسئلة الشائعة](#faq).

---

## الخطوة 4: أول مهمة حقيقية لك

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

```bash
cd /path/to/your/project
```

### المثال 1: تحليل بنية المشروع

```bash
codex "Analyze this project's directory structure and tech stack, and give a brief overview"
```

### المثال 2: توليد الشيفرة

```bash
codex "Create a utils/date-formatter.ts file with these features:
  1. Format a date as YYYY-MM-DD
  2. Calculate the number of days between two dates
  3. Determine whether a date is a business day
  4. Add complete JSDoc comments and unit tests for each function"
```

### المثال 3: تعديلات دفعية

```bash
codex "Convert all .js files under src/ to .ts files and add type annotations"
```

سيكمل Codex المهمة تلقائيًا في بيئة معزولة، ثم يعرض ملخصًا للتغييرات لتراجعها.

---

## الأذونات والبيئة المعزولة

يستخدم Codex خيارين للتحكم في ما يمكنه فعله (`--sandbox`) ومتى يسألك (`--ask-for-approval`). التفاصيل أدناه مأخوذة من وثائق OpenAI الرسمية (حتى 2026-10-15).

### الافتراضي: مساحة العمل قابلة للكتابة، والموافقات عند الطلب

```bash
codex "Refactor the auth module"
```

- في مستودع Git، هذا هو الإعداد المسبق الذي تحصل عليه دون خيارات: يقرأ Codex الملفات ويعدّلها وينفّذ الأوامر داخل مساحة العمل، ويسأل أولًا قبل الكتابة خارجها أو استخدام الشبكة
- الأنسب لـ: التطوير اليومي (الافتراضي الموصى به)

### للقراءة فقط: انظر دون تغيير

```bash
codex --sandbox read-only --ask-for-approval on-request "Analyze the auth module and suggest a refactor"
```

- البيئة المعزولة للقراءة فقط -- **لا تعدّل أي ملفات**
- الأنسب لـ: تعلّم الشيفرة، وتقييم الأساليب

### التشغيل غير التفاعلي والأتمتة

```bash
codex exec --sandbox workspace-write "Run tests and fix all failures"
```

- يعمل `codex exec` بصورة غير تفاعلية ويطبع النتائج إلى الإخراج القياسي (أو JSONL مع `--json`)
- تقتصر البيئة المعزولة على مساحة العمل ولن تؤثر في النظام خارجها
- الأنسب لـ: تكامل CI/CD، والمهام الدفعية

> يمكنك أيضًا تعيين الإعدادات الافتراضية في `config.toml`: `approval_policy = "on-request"` و`sandbox_mode = "workspace-write"`. صيغ `--suggest` و`--auto-edit` و`approval_mode` من الدروس القديمة ليست في قائمة الخيارات الرسمية الحالية؛ عند الشك، اعتمد على `codex --help`.

---
## مرجع الأوامر

| الأمر | الوصف |
|---------|-------------|
| `codex "your instruction"` | بدء Codex مع تعليمات أولى |
| `codex exec "instruction"` | التشغيل دون تفاعل ثم الخروج |
| `codex --model gpt-6.1-sol` | تحديد النموذج |
| `codex --sandbox workspace-write "instruction"` | مساحة العمل قابلة للكتابة |
| `codex --sandbox read-only "instruction"` | للقراءة فقط، دون تغيير الملفات |
| `codex --version` | عرض الإصدار |
| `codex --help` | عرض المساعدة |

### النماذج المتاحة

النماذج التالية متاحة عبر QCode.cc:

| النموذج | الوصف | يُنصح به لـ |
|-------|-------------|-----------------|
| `gpt-6.1-sol` | تحديث GPT-6 Sol (2026-09-29)، نافذة سياق 1.05M، إدخال مُخزَّن مؤقتًا بسعر أقل | المهام العامة / المعقدة (موصى به ★؛ توصي وثائق OpenAI Codex الرسمية بـ GPT-6.1 Sol للبرمجة المعقدة) |
| `gpt-6.1-terra` | من الفئة المتوسطة من GPT-6.1، سعر الوحدة نحو نصف سعر `gpt-6.1-sol` (انظر /models) | البرمجة اليومية / المهام المجمّعة |
| `gpt-6-sol` | الطراز الرائد GPT-6، نافذة سياق 1.05M | المهام العامة / المعقدة |
| `gpt-6-astra` | الفئة الأقوى، بسعر مرتفع | أعلى قدرة |
| `gpt-5.6-terra` | الطراز الرائد GPT-5.6 | البرمجة / المهام المعقدة |
| `gpt-5.6-sol` | عائلة الطراز الرائد GPT-5.6 | قدرة من الفئة العليا |

> لا توفّر QCode حاليًا gpt-6-luna / gpt-5.6-luna. يُرجى استخدام نموذج GPT آخر. تحتسب QCode الفوترة لكل token؛ وأسعار كل نموذج على [qcode.cc/models](https://qcode.cc/models).

> **لا يظهر gpt-6.1-sol في قائمة `/model`؟** مع الإعدادات أعلاه، تعرض قائمة `/model` في Codex قائمة النماذج المدمجة في العميل، لذا يعتمد الأمر على إصدار Codex لديك: يظهر gpt-6.1-sol في القائمة بدءًا من Codex 0.160.0. رقِّ إلى أحدث إصدار (`npm install -g @openai/codex@latest`، أو `brew upgrade --cask codex` مع Homebrew). ويعمل أيضًا دون ترقية: ضبط `model = "gpt-6.1-sol"` في `config.toml` (أو `codex --model gpt-6.1-sol`) لا يعتمد على القائمة. وعلى العكس، قد يظهر gpt-6-luna في القائمة، لكن QCode لا توفّره حاليًا، ويُعيد اختياره خطأً.

---

## إعدادات المشروع: AGENTS.md

أنشئ ملف `AGENTS.md` في جذر مشروعك لتحديد كيفية تصرّف Codex في ذلك المشروع -- على غرار `CLAUDE.md` في Claude Code:

```markdown
# AGENTS.md

- Use TypeScript strict mode
- Code style follows ESLint + Prettier
- Test framework: Vitest
- Run `npm run lint && npm test` before committing
- Component files use PascalCase naming
```

> للإعدادات التفصيلية، انظر [دليل إعدادات AGENTS.md](/docs/usage/agents-md).

---
## استخدام Codex مع Claude Code

بما أن الأداتين تشتركان في الحصة نفسها على QCode.cc، فإن أفضل ممارسة هي استخدامهما معًا:

```bash
# Terminal 1: Use Claude Code to analyze the problem
$ claude
> Where's the performance bottleneck? Help me analyze the approach.

# Terminal 2: Use Codex for batch execution
$ codex "Optimize all database queries under src/api/ according to this plan:
  1. Add query caching
  2. Fix N+1 queries
  3. Add index suggestion comments"
```

> لمزيد من الأنماط المشتركة، راجع [Codex vs Claude Code: مقارنة متعمقة](/docs/getting-started/codex-vs-claude-code).

---

## الخطوات التالية

اكتمل الإعداد -- أنت الآن جاهز لبدء استخدام Codex. القراءات الموصى بها:

- [دليل إعداد AGENTS.md](/docs/usage/agents-md) -- تخصيص سلوك مشروع Codex
- [Codex vs Claude Code: مقارنة متعمقة](/docs/getting-started/codex-vs-claude-code) -- فهم الفروق وكيفية الجمع بين الأداتين
- [إعداد تكامل Codex](/docs/ide/codex) -- مرجع الإعداد الكامل (بما في ذلك خطوات مفصّلة لـ Windows وأنظمة تشغيل متعددة)
- [نصائح وحيل CLI](/docs/usage/cli-tips) -- نصائح للإنتاجية في البرمجة بالذكاء الاصطناعي

---

## الأسئلة الشائعة

### س: يفشل التثبيت مع `npm ERR! EACCES`

**السبب**: صلاحيات غير كافية على مجلد التثبيت العام الخاص بـ npm.

**الحل**:

```bash
# Option A: Use sudo (not recommended long-term)
sudo npm install -g @openai/codex

# Option B: Configure npm to use a user directory (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex
```

### س: ظهور `API key not found` أو فشل المصادقة

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

1. تأكد من أن المفتاح في `~/.codex/auth.json` يبدأ بـ `cr_`
2. إذا كنت تستخدم صيغة متغير البيئة، فتأكد من أن المزوّد لديه `env_key = "QCODE_API_KEY"` (ولا يوجد `requires_openai_auth = true`) وأن المتغير مُصدَّر: `echo $QCODE_API_KEY`
3. تأكد من أن المفتاح لم تنته صلاحيته: تحقّق من [لوحة التحكم QCode.cc](https://qcode.cc/dashboard)
4. تحقّق من صياغة TOML ومن اسم المزوّد في `config.toml`

### س: انتهاء مهلة الاتصال أو خطأ في الشبكة

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

1. تأكد من ضبط `base_url` على `https://api.qcode.cc/openai`
2. اختبر اتصال الشبكة: `curl -I https://api.qcode.cc`
3. إذا كانت نقطة النهاية الحالية غير متاحة، فجرّب نقطة أخرى:
   - نقطة نهاية آسيا: `https://asia.qcode.cc/openai`

### س: هل مفتاح Codex هو نفسه مفتاح Claude Code؟

**نعم**. كلاهما يستخدم مفتاح API نفسه الخاص بـ QCode.cc مع حصة مشتركة. لا تحتاج إلى مفتاح منفصل.

### س: هل يعمل على Windows؟

**نعم**، لكننا نوصي باستخدام WSL (Windows Subsystem for Linux). كما أن الدعم الأصلي لـ Windows آخذ في التحسّن. راجع [إعداد تكامل Codex](/docs/ide/codex) للحصول على خطوات مفصّلة لإعداد Windows.