Codex CLI
وكيل OpenAI للبرمجة الطرفية

أربع طرق للتثبيت (الوثائق الرسمية اعتبارًا من 2026-10-20)

اعتبارًا من 2026-10-20، تسرد وثائق Codex CLI الرسمية من OpenAI أربع طرق للتثبيت: المثبّت المستقل على macOS وLinux، والمثبّت المستقل على Windows الذي يُشغّل من نافذة PowerShell جديدة، وnpm أو Homebrew. للتحديث، نفّذ أمر التثبيت نفسه مرة أخرى؛ مع Homebrew، استخدم brew upgrade --cask codex.

بعد التثبيت، افتح دليل مشروع ونفّذ codex. عند التشغيل الأول، اختر «تسجيل الدخول باستخدام ChatGPT» أو أي طريقة تسجيل دخول أخرى متاحة، ثم صف المهمة في جملة واحدة. توصي OpenAI بإنشاء نقاط تحقق Git قبل المهمة وبعدها حتى تتمكن من التراجع عن التغييرات.

• macOS / Linux: شغّل الأمر curl -fsSL https://chatgpt.com/codex/install.sh | sh
• Windows (PowerShell): شغّل الأمر powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
• npm: شغّل الأمر npm install -g @openai/codex
• Homebrew: شغّل الأمر brew install --cask codex
• WSL: تقول الوثائق الرسمية إن WSL1 كان مدعومًا حتى Codex 0.114؛ وابتداءً من 0.115 انتقلت بيئة Linux المعزولة إلى bubblewrap، لذا استخدم WSL2.

طريقتا تسجيل الدخول وحدود الاستخدام الرسمية

تصف وثائق المصادقة لدى OpenAI طريقتين لتسجيل الدخول إلى Codex CLI: «تسجيل الدخول باستخدام ChatGPT» للوصول عبر الاشتراك، أو مفتاح API للوصول حسب الاستخدام. يمكنك تمرير مفتاح إلى codex login --with-api-key عبر الأنبوب، ويعرض codex login status الطريقة النشطة. تُخزّن تفاصيل تسجيل الدخول مؤقتًا في ~/.codex/auth.json أو في مخزن بيانات الاعتماد في نظام التشغيل، وتتشارك CLI وإضافة IDE في تسجيل الدخول المخزّن مؤقتًا نفسه.

مع تسجيل الدخول عبر ChatGPT، تُطبَّق حدود خطتك: تقدّر صفحة الأسعار لدى OpenAI (اعتبارًا من 2026-10-20) عدد الرسائل المحلية لكل فترة من خمس ساعات لـ Plus وStandard Business، وتذكر أن خطط Pro لا تخضع حاليًا لحد خمس ساعات، وتشير إلى أن الحدود الأسبوعية قد تُطبَّق أيضًا؛ اكتب /status داخل جلسة لعرض حدودك المتبقية. مع مفتاح API من OpenAI، يستخدم Codex سعر OpenAI الرسمي (أسعار API القياسية) بدلًا من رصيد خطة ChatGPT المضمّن.

ربط Codex CLI بمفتاح API من QCode

يستخدم دليل QCode لـ Codex بروتوكول Responses من OpenAI: في ملف ~/.codex/config.toml على مستوى المستخدم، أضف مزوّد نموذج مخصصًا (بأي اسم تختاره)، واجعل model_provider يشير إليه، واملأ الحقول أدناه. بعد إنشاء حساب على QCode، أنشئ مفتاح API يبدأ بـ cr_ في لوحة التحكم وستكون جاهزًا.

هذا الإعداد يخدم نماذج GPT فقط: تذكر النظرة العامة في وثائق QCode أن نقطة النهاية Responses التي يستخدمها Codex لا تخدم Claude أو النماذج الصينية. لنماذج Claude مثل claude-sonnet-5-5 أو claude-opus-5-5، أعدّ Claude Code باستخدام المفتاح نفسه. تُحتسب الفاتورة لكل token؛ وتُدرج أسعار كل نموذج على /models.

• base_url: https://api.qcode.cc/openai (تذكر وثائق QCode أنه يجب أن يكون هذا بالضبط)؛ عنوان النسخ الاحتياطي الآسيوي هو https://asia.qcode.cc/openai.
• wire_api: responses، مع ضبط requires_openai_auth على true. تذكر وثائق OpenAI أن إصدارات Codex الحالية لا تدعم wire_api = chat ولا نقطة نهاية تقتصر على Chat Completions.
• اختر واحدًا: بالنسبة لمتغير بيئة، احذف requires_openai_auth واضبط env_key = "QCODE_API_KEY" (الاسم متروك لك)، ثم صدّر ذلك المتغير؛ وبالنسبة إلى ملف، أبقِ requires_openai_auth = true وضع المفتاح في ~/.codex/auth.json (الصلاحية 600). تذكر الوثائق أن Codex يتجاهل env_key عندما requires_openai_auth = true.
• model: نموذج GPT مذكور في وثائق QCode، مثل gpt-6-sol أو gpt-6.1-sol أو gpt-6-astra أو gpt-5.6-terra أو gpt-5.6-sol؛ ويمكن ضبط model_reasoning_effort على low أو medium أو high.
• هل تفضّل عدم تعديل الملفات يدويًا؟ تقدّم وثائق QCode سكربت إعداد من سطر واحد: curl -fsSL https://qcode.cc/install/codex.sh | bash (على Windows، irm https://qcode.cc/install/codex.ps1 | iex). يثبّت CLI، ويكتب إعداد ~/.codex، ويتحقق من الاتصال.

الأخطاء الشائعة وإصلاحاتها

ابدأ بـ codex doctor: تذكر الوثائق الرسمية أنه يولّد تقرير تشخيص محلي يغطي التثبيت والإعداد والمصادقة وبيئة التشغيل وGit وسلامة الطرفية. داخل جلسة، يؤكد /status النموذج النشط وسياسة الموافقة والسياق المتبقي، ويطبع /debug-config كيفية تطبيق كل طبقة إعداد.

• 401 أو مفتاح API غير صالح: تأكد من أن المفتاح يبدأ بـ cr_ وأنه لا يحتوي على مسافات أو فواصل أسطر زائدة؛ وإذا كنت تستخدم متغير بيئة، فيجب أن يطابق اسمه env_key في config.toml تمامًا؛ ثم تحقق من حالة المفتاح في لوحة التحكم في QCode.
• مهلات الاتصال أو أخطاء الشبكة: تأكد من أن base_url هو https://api.qcode.cc/openai، واختبر باستخدام curl -I https://api.qcode.cc، وجرّب https://asia.qcode.cc/openai إذا لم يستجب العنوان الرئيسي.
• تغييرات الإعداد لا تأثير لها: تذكر وثائق OpenAI أن ملفات .codex/config.toml على مستوى المشروع تتجاهل مفاتيح مثل model_provider وmodel_providers، لذلك يجب أن يكون المزوّد في ملف ~/.codex/config.toml على مستوى المستخدم.
• أخطاء ملفات التعريف: منذ Codex 0.134.0، لم يعد --profile يقرأ جداول [profiles.name] من config.toml ولم يعد محدد ملف التعريف الأعلى مدعومًا؛ انقل تلك الإعدادات إلى ملف منفصل ~/.codex/name.config.toml.
• النموذج غير متاح: تذكر وثائق OpenAI أن GPT-5.3-Codex-Spark أُوقف في 2026-09-14، وأن gpt-5.4 أُوقف من Codex مع تسجيل الدخول عبر ChatGPT في 2026-08-31 (إيقاف GPT-5.5 مشمول في بطاقات النماذج أعلاه)، لذا استبدل أسماء النماذج القديمة في النصوص البرمجية والإعداد.
• خطأ EACCES أثناء تثبيت npm عالميًا: تقترح وثائق QCode نقل الدليل العام لـ npm إلى دليل المستخدم لديك؛ ويُعد المثبّت المستقل الرسمي أعلاه خيارًا آخر.