بدء سريع مع Codex CLI (2026): الإعداد في 5 دقائق

ثبّت Codex CLI ووصّله بـ QCode.cc في نحو 5 دقائق: سكربت بنقرة واحدة أو إعداد يدوي عبر config.toml + auth.json، ثم أول مهمة. المفتاح نفسه المستخدم في Claude Code.

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

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

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

إذا لم يكن لديك حساب QCode.cc بعد، فاختر أولًا خطة واحصل على مفتاحك (يعمل المفتاح بالطريقة نفسها أيًّا كان الخيار الذي تختاره).

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

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

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

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

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

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

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)¶

brew install --cask codex

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

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

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

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

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

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

mkdir -p ~/.codex

2.2 كتابة config.toml¶

أنشئ ~/.codex/config.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

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

2.3 إنشاء auth.json¶

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

{
  "OPENAI_API_KEY": "cr_your_key_here"
}

استبدل cr_your_key_here بمفتاح API من لوحة تحكم QCode.cc الخاصة بك.

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

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

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"

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

# 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 بالفعل، فستجد المفتاح في المكان نفسه على لوحة التحكم.

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

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

codex "print hello world"

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

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

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

إذا واجهت مشكلات، فانتقل إلى قسم الأسئلة الشائعة.

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

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

cd /path/to/your/project

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

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

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

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: تعديلات دفعية¶

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

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

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

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

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

codex "Refactor the auth module"

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

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

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

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

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

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.

مرجع الأوامر¶

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

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

لا توفّر QCode حاليًا gpt-6-luna / gpt-5.6-luna. يُرجى استخدام نموذج GPT آخر. تحتسب QCode الفوترة لكل token؛ وأسعار كل نموذج على 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:

# 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.

استخدام Codex مع Claude Code¶

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

# 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: مقارنة متعمقة.

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

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

• دليل إعداد AGENTS.md -- تخصيص سلوك مشروع Codex
• Codex vs Claude Code: مقارنة متعمقة -- فهم الفروق وكيفية الجمع بين الأداتين
• إعداد تكامل Codex -- مرجع الإعداد الكامل (بما في ذلك خطوات مفصّلة لـ Windows وأنظمة تشغيل متعددة)
• نصائح وحيل CLI -- نصائح للإنتاجية في البرمجة بالذكاء الاصطناعي

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

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

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

الحل:

# 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
4. تحقّق من صياغة TOML ومن اسم المزوّد في config.toml

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

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

1. تأكد من ضبط base_url على https://api.qcode.cc/openai
2. اختبر اتصال الشبكة: curl -I https://api.qcode.cc

3. إذا كانت نقطة النهاية الحالية غير متاحة، فجرّب نقطة أخرى:

4. نقطة نهاية آسيا: https://asia.qcode.cc/openai

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

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

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

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

المؤسسات ←