Codex CLI 0.167.0: التثبيت وconfig.toml

Codex CLI 0.167.0 (2026-11-06): ثبّته، واربط QCode.cc عبر ~/.codex/config.toml وauth.json، ثم استخدم AGENTS.md والموافقات وملفات التعريف وMCP.

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

آخر تحقق: 2026-11-09 · 📄 وفق الوثائق الرسمية (أحدث إصدار مستقر من Codex CLI هو v0.167.0، صدر في 2026-11-06؛ وقد أُعيد التحقق من مفاتيح الإعداد وتغييرات الأوامر في 0.164.0 والتثبيت آخر مرة في 2026-10-26) · كما اختُبر سلوك ملف التعريف في 5.4 محليًا (✅ codex-cli 0.155.0، HOME معزول، لم تُرسل أي طلبات نموذج)

نظرة سريعة¶

📖 لماذا يختلف base_url في Codex عن ANTHROPIC_BASE_URL في Claude؟ وما الفرق بين /openai و/openai/v1؟ راجع نقاط النهاية ومسارات API.

هذا دليل كامل لـ Codex CLI موجّه إلى المطورين الصينيين، يأخذك من الصفر إلى تثبيت OpenAI Codex CLI وإعداده واستخدامه مع نماذج GPT عبر مفتاح API الخاص بك من QCode.cc. وسواء كنت تلمس أدوات البرمجة بالذكاء الاصطناعي لأول مرة أو تستخدم Claude Code بالفعل وترغب في تجربة أدوات جديدة، فهذا الدليل مناسب لك.

1. مقدمة عن Codex¶

ما هو OpenAI Codex CLI؟¶

Codex CLI هو مساعد برمجة بالذكاء الاصطناعي مفتوح المصدر يعمل من سطر الأوامر (رخصة Apache 2.0) أطلقته OpenAI، مكتوب بلغة Rust ويمكن تشغيله مباشرة في الطرفية. ويستطيع:

• قراءة وفهم مستودع الشيفرة الخاص بك
• تحرير الملفات وتوليد شيفرة جديدة
• تنفيذ الأوامر (مثل تشغيل الاختبارات وتثبيت التبعيات)
• التكرار ذاتيًا حتى اكتمال المهمة

تقوم فلسفة Codex الأساسية على الوكيل المستقل: تصف المهمة، فينجزها Codex ذاتيًا داخل بيئة معزولة، ثم تراجع النتائج في النهاية. وهذا يكمّل أسلوب Claude Code القائم على الحوار التفاعلي.

تاريخ تطوير Codex¶

مرّ اسم «Codex» بمراحل تطور متعددة ضمن تشكيلة منتجات OpenAI:

• 2021: كان Codex الأول نسخة من GPT-3 مُحسّنة للشيفرة، وشغّل GitHub Copilot
• 2024: أعادت OpenAI إحياء علامة Codex، وأطلقت وكيل برمجة بالذكاء الاصطناعي غير متزامن قائمًا على السحابة
• 2025-2026: تطوّر Codex CLI إلى أداة محلية ناضجة لسطر الأوامر، وأُعيدت كتابة Codex CLI بلغة Rust، مع دعم ميزات متقدمة مثل MCP وSkills وMulti-Agent

Codex الحالي منتج متعدد الواجهات: يشمل أداة CLI لسطر الأوامر (محور هذه المقالة)، وتطبيق سطح المكتب لنظام macOS، وإضافات IDE، ووكلاء سحابيين مدمجين في ChatGPT. أما الإصدار المستخدم عبر QCode.cc فهو إصدار CLI.

الفروقات الجوهرية بين Codex وClaude Code¶

بعبارة بسيطة: يتفوّق Codex في «المهام التي لا تتطلب تدخلًا يدويًا» (قدّم متطلبًا واضحًا ودعه ينفّذه حتى النهاية)، ويتفوّق Claude Code في «البرمجة الثنائية» (ناقش وعدّل أثناء الاستكشاف، وهو مناسب للمهام الاستكشافية). واستخدام الاثنين معًا يعطي أفضل النتائج.

لماذا تستخدم Codex عبر QCode.cc؟¶

يتطلب Codex CLI افتراضيًا مفتاح API من OpenAI أو اشتراك ChatGPT، ولا يمكن الوصول إلى OpenAI API مباشرة في البر الرئيسي الصيني.

عبر QCode.cc، يمكنك:

• استدعاء Claude وGPT والنماذج الصينية الشائعة بمفتاح واحد: يستخدم Codex نماذج GPT، ويستخدم Claude Code نموذج Claude، وكلاهما يشترك في مفتاح API نفسه من QCode
• استخدام عدة نقاط نهاية: api.qcode.cc هي نقطة الدخول العالمية، وus.qcode.cc يخدم أمريكا الشمالية وأوروبا، وasia.qcode.cc يخدم آسيا، وينبغي لمستخدمي البر الرئيسي الصيني تفضيل asia.qcode.cc؛ ولا حاجة إلى وكيل ذاتي البناء
• الدفع حسب token، مع أسعار لكل نموذج على qcode.cc/models
• يشترك Claude Code وCodex في حصة الخطة، لذا تكفي خطة واحدة لكلا الأداتين

2. تثبيت Codex CLI¶

متطلبات النظام¶

قبل التثبيت، يرجى التأكد من أن بيئتك تستوفي الشروط التالية:

• نظام التشغيل: macOS 12+، Ubuntu 20.04+، Windows 10+ (يُوصى بـ WSL2)
• Node.js: v22 LTS أو أحدث (مطلوب للتثبيت عبر npm)
• Git: 2.x أو أحدث (يحتاج Codex إلى Git للتعرف على مستودع الشيفرة)
• مساحة القرص: نحو 200MB (بما في ذلك تبعيات npm)

الطريقة 1: التثبيت عبر npm (موصى به)¶

هذه طريقة التثبيت الأكثر شيوعًا، وتنطبق على جميع أنظمة التشغيل:

npm install -g @openai/codex

نصيحة: إذا واجهت مشكلات في الأذونات، يمكن لمستخدمي macOS/Linux إضافة sudo، أو استخدام nvm لإدارة Node.js لتجنب مشكلات الأذونات.

المستخدمون الصينيون: إذا كان تنزيل npm بطيئًا، يمكنك استخدام مرآة Taobao: bash npm install -g @openai/codex --registry=https://registry.npmmirror.com

الطريقة 2: التثبيت عبر Homebrew (macOS)¶

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

brew install --cask codex

تتمثل ميزة Homebrew في الإدارة التلقائية للتبعيات والتحديثات.

الطريقة 3: تنزيل الملف الثنائي مباشرةً (متقدم)¶

نزّل الملفات الثنائية المُجمّعة مسبقًا لمنصتك من صفحة GitHub Releases وضعها في دليل PATH. لا تعتمد هذه الطريقة على Node.js. حتى 2026-11-09، أحدث إصدار مستقر هو v0.167.0 (نُشر في 2026-11-06)؛ وقد تحقق فحص 2026-10-15 من v0.162.1 (نُشر في 2026-10-09). تُسمّى الأصول حسب المنصة: على سبيل المثال codex-x86_64-unknown-linux-musl.tar.gz لـ Linux x64، وcodex-aarch64-apple-darwin.tar.gz لـ macOS بنظام Apple silicon، وcodex-x86_64-pc-windows-msvc.exe لـ Windows x64.

# Example: download and install the Linux x64 build
curl -fsSLO https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

الطريقة 4: سكربت التثبيت الرسمي (macOS / Linux)¶

توفّر وثائق OpenAI Codex الرسمية (حتى 2026-10-26) أيضًا مثبّتًا مستقلًا:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

أكّد التثبيت باستخدام codex --version.

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

codex --version

إذا ظهر لك رقم إصدار، فقد نجح التثبيت. لا تعتبر أي رقم في هذه الصفحة «أحدث إصدار حالي» — استخدم GitHub Releases وnpm @openai/codex، وتحقق من الجهاز باستخدام codex --version.

إعداد الإكمال التلقائي للصدفة (اختياري)¶

يدعم Codex الإكمال التلقائي للصدفة؛ اضغط Tab عند إدخال الأوامر للحصول على اقتراحات:

# Zsh users
echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash users
echo 'eval "$(codex completion bash)"' >> ~/.bashrc
source ~/.bashrc

إذا أظهر Zsh الرسالة command not found: compdef، فأضف autoload -Uz compinit && compinit قبل eval.

3. إعداد QCode.cc¶

يتطلب Codex CLI إعداد ملفين للاتصال بخدمة QCode.cc:

• ~/.codex/config.toml — نقطة نهاية الخادم وإعداد النموذج
• ~/.codex/auth.json — مصادقة مفتاح API

الخطوة 1: إنشاء دليل الإعداد¶

mkdir $HOME\.codex

mkdir -p ~/.codex

mkdir -p ~/.codex

الخطوة 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

تفاصيل حقول config.toml:

الخطوة 3: إنشاء auth.json¶

اكتب المحتوى التالي في ~/.codex/auth.json:

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

استبدل cr_xxxxxxxxxx بـمفتاح API الخاص بك في QCode.cc. يبدأ المفتاح بـ cr_.

ملاحظات auth.json:

• يوفّر هذا الملف مفتاح API إلى Codex (مع requires_openai_auth = true، يقرأ Codex OPENAI_API_KEY منه)
• أذونات الملف الموصى بها هي 600 (قراءة/كتابة للمالك فقط): chmod 600 ~/.codex/auth.json

الخطوة 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 setting (current session)
$env:QCODE_API_KEY = "cr_xxxxxxxxxx"

# Permanent setting (write to user environment variable)
[System.Environment]::SetEnvironmentVariable("QCODE_API_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)

# Temporary setting
export QCODE_API_KEY="cr_xxxxxxxxxx"

# Permanent setting
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# Temporary setting
export QCODE_API_KEY="cr_xxxxxxxxxx"

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

# Permanent setting (Zsh)
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

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

تتوفر نماذج Codex/GPT التالية عبر QCode.cc:

لا يوفّر QCode حاليًا gpt-6-luna / gpt-5.6-luna. يُرجى استخدام نموذج GPT آخر (gpt-6.1-sol / gpt-6.1-terra / gpt-6-sol / gpt-5.6-terra).

يستخدم Claude Code وCodex مفتاح API نفسه الخاص بـ QCode، ولا يتطلب تبديل النماذج أي إعداد إضافي. تحتسب QCode رسومًا لكل token؛ وتوجد أسعار كل نموذج على qcode.cc/models.

4. دليل الاستخدام الأساسي¶

4.1 تشغيل Codex¶

افتح الطرفية، وانتقل إلى دليل مشروعك، ثم شغّل:

cd /path/to/your/project
codex

سيشغّل Codex واجهة تفاعلية في الطرفية (TUI)، حيث يمكنك إدخال تعليمات باللغة الطبيعية. تتكون الواجهة من:

• شريط الحالة العلوي: يعرض النموذج الحالي، ووضع الموافقة، وحالة بيئة العزل
• المنطقة الرئيسية: ردود الذكاء الاصطناعي وسجلات العمليات
• مربع الإدخال السفلي: حيث تدخل التعليمات

يمكنك أيضًا إعطاء المهام مباشرةً على سطر الأوامر (الوضع غير التفاعلي)، وهو مناسب للاستدعاء من النصوص البرمجية:

# Interactive launch
codex

# Non-interactive mode: execute single task then exit
codex "Read this project's structure and give me an overview"

# Task with image
codex -i screenshot.png "Fix the UI issue shown in the screenshot"

# Specify model
codex -m gpt-6-sol "Refactor the error handling in the authentication module"

4.2 المهمة الأولى: دع Codex يكتب دالة¶

لنبدأ بمثال بسيط. شغّل Codex في دليل مشروعك وأدخل:

Write a Python function that accepts a list of strings and returns the longest one. If there are multiple strings with the same length, return the first one. Save to utils.py.

سينفّذ Codex الخطوات التالية:

1. التخطيط: تحليل متطلباتك وصياغة خطة تنفيذ
2. توليد الشيفرة: إنشاء utils.py وكتابة الدالة
3. طلب التأكيد: في الإعداد المسبق للقراءة فقط، أو عندما يحتاج تغيير إلى موافقة (مثل الكتابة خارج مساحة العمل)، يعرض Codex تعديل الملف المعلّق وينتظر تأكيدك؛ وفي الإعداد المسبق الافتراضي، تُنفَّذ التعديلات داخل مساحة العمل تلقائيًا

عندما يلزم التأكيد، سترى prompt مثل هذا:

Codex wants to create file: utils.py
─────────────────────────────────────

+ def find_longest(strings: list[str]) -> str:
+     """Return the longest string in the list, or the first one if there are multiple."""
+     if not strings:
+         raise ValueError("List cannot be empty")
+     return max(strings, key=len)

Accept? [y/n]

أدخل y للتأكيد، وسيكتب Codex الشيفرة إلى الملف.

بعد ذلك، يمكنك متابعة إعطاء مزيد من التعليمات، وسيحافظ Codex على السياق ضمن الجلسة نفسها:

Write a unit test for this function using pytest

سيقرأ Codex تلقائيًا ملف utils.py الذي أنشأته للتو، ثم يولّد ملف الاختبار المقابل.

4.3 فهم وضع تنفيذ بيئة العزل في Codex¶

هذه إحدى أهم ميزات الأمان في Codex. ينفّذ Codex الأوامر داخل بيئة عزل، بثلاثة مستويات أمان:

يُعدّ وضع workspace-write الافتراضي الخيار الأفضل للتطوير اليومي: يستطيع Codex قراءة الملفات وكتابتها وتشغيل الأوامر بحرية داخل دليل المشروع، لكنه لا يستطيع الوصول إلى الملفات أو الشبكة خارج المشروع.

إذا كانت مهمتك تتطلب الوصول إلى الشبكة (مثل npm install)، يمكنك تمكين الوصول إلى الشبكة مؤقتًا:

codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies and run tests"

4.4 مراجعة تغييرات Codex وقبولها¶

تتبع تعديلات ملفات Codex سياسة الموافقة. وفقًا للوثائق الرسمية (حتى 2026-10-26)، فإن الإعداد الافتراضي في مستودع Git هو الإعداد المسبق «الكتابة في مساحة العمل + الموافقات عند الطلب»:

• تعديلات الملفات والأوامر داخل مساحة العمل: تُنفَّذ تلقائيًا
• الكتابة خارج مساحة العمل، والوصول إلى الشبكة وما شابه ذلك من إجراءات: تُعرض عليك وتنتظر التأكيد
• المجلدات التي ليست مستودعات Git: للقراءة فقط افتراضيًا، لذا يسأل Codex قبل تغيير أي شيء

عندما يقترح Codex تعديلات، يمكنك:

• القبول (y): تطبيق التعديل
• الرفض (n): تخطي هذا التعديل
• عرض التفاصيل: مراجعة الفروقات بعناية قبل اتخاذ القرار

نصيحة: استخدم أمر الشرطة المائلة /diff لعرض جميع التعديلات المطبّقة في الجلسة الحالية في أي وقت.

4.5 نصائح التفاعل الشائعة¶

الإشارة إلى ملف: أدخل @ متبوعًا باسم الملف، وسيقرأ Codex محتوى ذلك الملف تلقائيًا:

Review @src/app.py and optimize error handling

تنفيذ أوامر Shell: ابدأ بـ ! لتشغيل الأوامر مباشرة، وسيُمرَّر الإخراج إلى Codex:

!cat error.log
Analyze the error log above and find the root cause

إضافة تعليمات: عندما يكون Codex قيد التشغيل، اضغط Enter لإدراج تعليمات جديدة، واضغط Tab لوضع الجولة التالية من التعليمات في قائمة الانتظار.

الرجوع للتحرير: عندما يكون مربع الإدخال فارغًا، اضغط Esc مرتين للعودة إلى الرسالة السابقة وتعديلها/إعادة إرسالها. تابع الضغط على Esc للرجوع إلى رسائل أقدم، ثم اضغط Enter لتفريع سطر حوار جديد من تلك النقطة.

الإدخال عبر الأنبوب: يمكنك تمرير إخراج أوامر أخرى عبر الأنبوب إلى Codex للتحليل:

# Analyze recent git changes
git diff HEAD~3 | codex "Review these changes and identify potential issues"

# Analyze error logs
cat /var/log/app/error.log | codex "Analyze the root causes of these errors"

# Review PR
gh pr diff 42 | codex "Review this PR's code quality and security"

اختصارات لوحة المفاتيح:

أوامر الشرطة المائلة:

4.6 تغييرات أوامر Codex CLI 0.164.0 (2026-10-23)¶

صدر Codex CLI 0.164.0 في 2026-10-23. تسرد ملاحظات الإصدار هذه التغييرات المتعلقة بالأوامر والإعدادات (منقولة حرفيًا):

• حفظ prompts وأوامر الشرطة المائلة القابلة لإعادة الاستخدام في عشر فتحات مرقّمة /presets، مع قائمة لوحة مفاتيح للوصول السريع.
• تعيين النموذج وجهد الاستدلال والسرعة وملفات تعريف الأذونات مباشرةً باستخدام وسائط /model و/permissions المضمّنة.
• مصادقة اتصالات MCP الخاصة بالمؤسسات باستخدام منح حساب Codex المؤهلة أو تسجيل دخول مخصص، بما في ذلك عملاء OAuth الذين يتطلبون أسرارًا.
• إخفاء بيانات الاعتماد أثناء أوامر Bash البعيدة المدعومة وجلسات لقطة Zsh، بما في ذلك بيانات الاعتماد من المزوّدين المخصصين.

تظل المفاتيح المستخدمة في الإعداد أعلاه في مرجع الإعدادات الرسمي الذي جرى التحقق منه في 2026-10-26: model_provider، و[model_providers.<id>]، وbase_url، وwire_api، وrequires_openai_auth. أوامر التثبيت دون تغيير في README الرسمي الذي جرى التحقق منه في اليوم نفسه: npm install -g @openai/codex، أو brew install --cask codex، أو curl -fsSL https://chatgpt.com/codex/install.sh | sh.

5. الإعدادات المتقدمة¶

5.1 ملفات التعليمات المخصصة (AGENTS.md)¶

يدعم Codex ملفات AGENTS.md لتزويد الذكاء الاصطناعي بسياق المشروع ومواصفات العمل، وتعمل بصورة مشابهة لملف CLAUDE.md الخاص بـ Claude Code.

تعليمات على مستوى المشروع: أنشئ AGENTS.md في الدليل الجذر للمشروع:

# AGENTS.md

## Project Description
This is a FastAPI backend project using PostgreSQL database.

## Code Standards

- All functions must have type annotations
- New API endpoints require corresponding tests
- Run `make lint` to check code style before committing

## Test Commands

- Unit tests: `pytest tests/unit/`
- Integration tests: `pytest tests/integration/`
- Code check: `make lint`

التعليمات العامة: أنشئ قواعد افتراضية عامة في ~/.codex/AGENTS.md، ترثها جميع المشاريع:

# Global Instructions

- Always communicate in English
- Code comments use English
- Prefer functional programming style
- Generated code must include error handling

تجاوز الدليل الفرعي: يؤدي إنشاء AGENTS.override.md في دليل محدد إلى تجاوز قواعد الدليل الأب:

# services/payments/AGENTS.override.md

- All changes in this directory must be written to audit log
- Amount calculations use Decimal type, no floating point numbers

يبحث Codex عن ملفات التعليمات بالترتيب التالي: AGENTS.override.md > AGENTS.md > ملف الاحتياط المُهيأ. الحد الأقصى للحجم الإجمالي المجمّع افتراضيًا هو 32KB، ويمكن تعديله عبر project_doc_max_bytes.

5.2 ضبط الموافقات وبيئة العزل¶

تأتي ضوابط الأمان في Codex على طبقتين: يحدد وضع بيئة العزل ما يستطيع Codex فعله تقنيًا (أين يمكنه الكتابة، وما إذا كان يستطيع الوصول إلى الشبكة)، وتحدد سياسة الموافقات متى يجب عليه أن يسألك أولًا. حتى 2026-10-26، وفقًا لوثائق OpenAI الرسمية، يتحكم فيهما خياران من سطر الأوامر:

تركيبات شائعة (الوثائق الرسمية):

🔴 إن الصيغ --full-auto و--suggest و--auto-edit و--approval-mode التي قد تراها في دروس أقدم ليست ضمن قائمة الخيارات الرسمية الحالية. عندما تحتاج إلى الكتابة الذاتية الكاملة للملفات، استخدم --sandbox workspace-write؛ وللتشغيل غير التفاعلي استخدم codex exec --sandbox workspace-write.

⚠️ تتغير خيارات Codex بسرعة. ثق بالمخرجات الفعلية للأمر codex --help بدلًا من قائمة خيارات منسوخة من أي وثيقة، بما في ذلك هذه الصفحة.

عيّن الإعدادات الافتراضية في config.toml:

# Recommended for personal development
approval_policy = "on-request"
sandbox_mode = "workspace-write"

يقبل approval_policy القيم on-request أو never أو جدول granular يفصل الـ prompt حسب الفئة. تنص الوثائق الرسمية على أن approval_policy = "untrusted" لم يعد مدعومًا؛ وإذا كان إعداد قديم لا يزال يحتوي على ذلك السطر فقد يمنع العميل من البدء، لذا احذفه.

التبديل أثناء الجلسة: استخدم الأمر /permissions للتبديل بين الإعداد المسبق الافتراضي ووضع القراءة فقط دون إعادة التشغيل.

الإعداد الموصى به حسب السيناريو¶

5.3 تهيئة خوادم MCP¶

يدعم Codex بروتوكول سياق النموذج (MCP)، الذي يمكنه ربط أدوات خارجية لتوسيع الإمكانات.

إضافة خادم MCP عبر سطر الأوامر:

codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json

التهيئة عبر config.toml:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token" }

بعد التهيئة، أعد تشغيل Codex واستخدم الأمر /mcp لعرض الخوادم المتصلة. ستظهر أدوات MCP تلقائيًا في قائمة الأدوات المتاحة في Codex إلى جانب الأدوات المدمجة.

اجعل Codex نفسه خادم MCP: يمكن أيضًا تشغيل Codex بالعكس كخادم MCP، تستدعيه وكلاء ذكاء اصطناعي آخرون. هذا مفيد جدًا عند بناء أنظمة متعددة الوكلاء.

5.4 تهيئة ملف التعريف (إدارة البيئات المتعددة)¶

إذا كانت مشاريع مختلفة تحتاج إلى إعدادات مختلفة (العمل مقابل الشخصي، مثلًا)، فاستخدم ملفات التعريف. بدءًا من Codex 0.134.0 لم تعد جداول [profiles.<name>] القديمة داخل config.toml صالحة — أصبح لكل ملف تعريف ملفه الخاص: ~/.codex/<name>.config.toml. الكتل الثلاث أدناه هي الصيغة الجديدة الكاملة:

# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "qcode"
model = "gpt-6-sol"

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

# ~/.codex/work.config.toml
model = "gpt-6-sol"
model_reasoning_effort = "high"

# ~/.codex/personal.config.toml
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

ابدأ بملف تعريف:

codex --profile work "Refactor authentication module"
codex --profile personal "Write a small script"

✅ إن السلوكيات الثلاثة أدناه مُختبرة على جهازنا (codex-cli 0.155.0، linux-x86_64، HOME معزول، دون إرسال أي طلب إلى النموذج) وهي المزالق التي يقع فيها الناس:

• الإبقاء على الجدول القديم وتمرير --profile هو خطأ صارم، وليس تجاهلًا صامتًا:

text Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.

• كما أن محدد profile = "work" على المستوى الأعلى لم يعد مدعومًا هو الآخر:

text Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead

• بدون --profile، لا تُحلّ الجداول المتبقية [profiles.*] ببساطة — لا يزال codex doctor يبلّغ عن config.toml parse ok ويستخدم القيم على المستوى الأعلى. «عدم وجود خطأ» لا يعني «أنه أصبح ساريًا»، لذا احذف الجداول القديمة عند الترحيل.

كذلك، لا ينطبق --profile إلا على الأوامر الفرعية وقت التشغيل (codex، exec، review، resume، queue، archive، delete، unarchive، fork، mcp، sandbox، debug prompt-input)؛ أما على doctor فيفشل بالرسالة --profile only applies to runtime commands .... ملف التعريف طبقة أعلى من إعداد المستخدم وأدنى من إعداد المشروع وسطر الأوامر — انظر 5.6.

5.5 الوضع غير التفاعلي (النصوص البرمجية والأتمتة)¶

لا يقتصر استخدام Codex على الوضع التفاعلي فحسب، بل يمكن تشغيله أيضًا بصورة غير تفاعلية في النصوص البرمجية وخطوط CI/CD: استخدم codex exec لتشغيل مهمة ثم الخروج (وفقًا للوثائق الرسمية، يعمل بصورة غير تفاعلية ويبث النتائج إلى stdout أو JSONL).

# Basic usage: execute task then exit
codex exec "Add installation instructions to README.md"

# Allow workspace writes: fully autonomous execution
codex exec --sandbox workspace-write "Run test suite, fix all failing tests"

# Output a JSONL event stream (for auditing or post-processing)
codex exec --json "Refactor error handling module"

استخدام Codex في CI/CD:

# GitHub Actions example

- name: Auto-fix lint errors
  run: |
    # Environment-variable variant: use env_key in config.toml, no requires_openai_auth
    mkdir -p ~/.codex
    cat > ~/.codex/config.toml <<'EOF'
    model_provider = "qcode"
    model = "gpt-6.1-sol"

    [model_providers.qcode]
    name = "qcode"
    base_url = "https://api.qcode.cc/openai"
    wire_api = "responses"
    env_key = "QCODE_API_KEY"
    EOF
    npx @openai/codex exec --sandbox workspace-write "Run eslint --fix to fix all lint errors, then commit the fixes"
  env:
    QCODE_API_KEY: ${{ secrets.QCODE_API_KEY }}

Codex SDK: إذا كنت تحتاج إلى استدعاء Codex في برامجك الخاصة، فيمكنك استخدام SDK الرسمي للاستدعاء البرمجي، وتضمين Codex في أدوات التطوير أو سير العمل الخاصة بك.

5.6 أولوية الإعدادات¶

عندما تتعارض مصادر إعدادات متعددة، يحلّها Codex بترتيب الأولوية التالي (من الأعلى إلى الأدنى):

1. وسائط سطر الأوامر (--model، -c، إلخ)
2. إعداد المشروع (.codex/config.toml، من جذر المشروع إلى الدليل الحالي، والأقرب له الأولوية؛ ولا يُحمّل إلا بعد الوثوق بالمجلد، وتُتجاهل مفاتيح مثل model_provider وmodel_providers وprofile وprofiles في طبقة المشروع)
3. ملف التعريف (~/.codex/<name>.config.toml، يُحدد بواسطة --profile <name>)
4. إعداد المستخدم (~/.codex/config.toml)
5. إعداد النظام (/etc/codex/config.toml، أنظمة Unix)
6. الإعدادات الافتراضية المدمجة

يساعدك فهم هذه الأولوية على التحكم الدقيق في السلوك على مستويات مختلفة. على سبيل المثال، عيّن إعدادات افتراضية عامة في ~/.codex/config.toml، وتجاوز إعدادات محددة في .codex/config.toml الخاص بالمشروع، ثم استخدم وسائط سطر الأوامر لإجراء تعديلات لمرة واحدة.

6. مقارنة Claude Code وCodex¶

باختصار: Claude Code برمجة ثنائية تفاعلية؛ وCodex تنفيذ ذاتي للمهام. يناسب Claude Code تصحيح الأخطاء الاستكشافي وإعادة الهيكلة المعقدة وفهم البنية؛ ويناسب Codex أعمال الميزات المحددة جيدًا والترحيلات الكبيرة وأتمتة CI/CD. ملفا التعليمات الخاصان بهما هما CLAUDE.md وAGENTS.md، وكلاهما يدعم MCP بالكامل، وكلاهما يتشارك حصة خطة QCode.cc نفسها — والتبديل بينهما لا يكلّف شيئًا.

المقارنة الكاملة جنبًا إلى جنب عبر 13 بُعدًا (نموذج التنفيذ، ونافذة السياق، والعزل الصندوقي، وتعدد الوكلاء، والمصدر المفتوح وغير ذلك) → Codex مقابل Claude Code.

7. أمثلة عملية¶

يوضّح ما يلي استخدام Codex عبر عدة سيناريوهات واقعية. يتضمن كل مثال أوامر محددة وتأثيرات متوقعة.

المثال 1: فهم مشروع جديد¶

عندما تتولى قاعدة شيفرة غير مألوفة:

cd /path/to/new/project
codex

في الواجهة التفاعلية:

What does this project do? Please analyze the directory structure, main modules, tech stack,
and give a concise architecture diagram (using ASCII art).

سيفحص Codex ملفات المشروع، ويحلل ملفات التبعيات مثل package.json وrequirements.txt وgo.mod، ويقرأ ملفات الإدخال الرئيسية، ثم يقدّم نظرة عامة شاملة على المشروع.

المثال 2: مراجعة الشيفرة¶

codex "Review all changes from the most recent git commit in the src/ directory. Focus on:
1. Potential bugs (null pointers, boundary conditions)
2. Security risks (SQL injection, XSS, hardcoded keys)
3. Performance issues (N+1 queries, unnecessary loops)
Provide specific code locations and fix suggestions."

المثال 3: إعادة الهيكلة بالجملة¶

codex --sandbox workspace-write "Replace all Python file print() calls with the logging module.
Specific requirements:
1. Import logging at the top of each file
2. Create logger = logging.getLogger(__name__)
3. Replace print() with logger.info()
4. Keep original formatted strings
5. After replacement, run pytest to ensure nothing is broken"

سيعالج Codex الملفات واحدًا تلو الآخر، مع الحفاظ على اتساق الشيفرة، ثم يشغّل الاختبارات للتحقق في النهاية.

المثال 4: كتابة مجموعة اختبارات كاملة¶

codex "Write complete unit tests for src/services/user_service.py. Requirements:
1. Use pytest + pytest-mock
2. Cover all public methods
3. Include both happy path and exception path tests
4. Mock external dependencies (database, HTTP requests)
5. Save test file to tests/unit/test_user_service.py
6. Run tests to confirm all pass"

المثال 5: إصلاح الاختبارات ذاتيًا¶

حالة استخدام كلاسيكية ذاتية بالكامل — دع Codex يصلح الاختبارات الفاشلة بنفسه:

codex --sandbox workspace-write "Run all tests. If any fail:
1. Analyze the failure reasons
2. Fix the code (not the tests)
3. Re-run tests
4. Repeat above steps until all tests pass
Finally, provide a fix summary."

المثال 6: تنفيذ واجهة المستخدم من نموذج تصميم¶

codex -i design.png "Implement this page using React + Tailwind CSS based on this design mockup.
Requirements:
1. Responsive layout (mobile support)
2. Pixel-perfect recreation of the design mockup
3. Reasonable component splitting
4. Add basic interaction states (hover, focus)"

المثال 7: ترحيل قاعدة البيانات¶

codex "I need to add an avatar_url field (varchar 500, nullable) to the users table.
Please:
1. Create Alembic migration script
2. Update SQLAlchemy model
3. Update related Pydantic schema
4. Update CRUD operation functions
5. Add corresponding API endpoints (GET/PUT)
6. Run migration and confirm success"

المثال 8: إنشاء سجل التغييرات تلقائيًا في CI/CD¶

codex --sandbox workspace-write "Analyze all git commits from the last release tag to now,
categorize them according to conventional commits specification,
and generate CHANGELOG.md update content.
Include: new features, bug fixes, breaking changes, other improvements."

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

تعذّر العثور على ملف التكوين¶

المشكلة: يعرض Codex رسالة تفيد بعدم العثور على ملف التكوين أو تعذّر تحميل التكوين

الحل:

1. تحقق من وجود دليل التكوين: ls ~/.codex/
2. تأكد من وجود كلا الملفين config.toml وauth.json
3. تحقق من صحة صياغة TOML في config.toml (الأخطاء الشائعة: علامات اقتباس ناقصة، أخطاء كتابية)
4. شغّل codex doctor لإنشاء تقرير تشخيصي يغطي التثبيت والتكوين والمصادقة

فشل مصادقة مفتاح API¶

المشكلة: تظهر رسالة 401 Unauthorized أو أن مفتاح API غير صالح

الحل:

1. تأكد من صحة صيغة مفتاح API (يبدأ بـ cr_)
2. تحقق من أن المفتاح في auth.json كامل (دون مسافات أو فواصل أسطر إضافية)
3. إذا كنت تستخدم صيغة متغيرات البيئة، فتأكد من أن المزوّد يضبط env_key = "QCODE_API_KEY"، ولا يضبط requires_openai_auth = true، وأن المتغير مُصدَّر
4. سجّل الدخول إلى لوحة تحكم QCode.cc لتأكيد حالة المفتاح والحصة المتبقية

مشكلات اتصال الشبكة¶

المشكلة: تعذّر الاتصال بخدمة QCode.cc، أو انتهت المهلة، أو رُفض الاتصال

الحل:

1. تحقق من أن الشبكة تعمل: curl -I https://api.qcode.cc
2. تحقق من صحة إعداد base_url (يجب أن يكون https://api.qcode.cc/openai)

3. جرّب نقطة نهاية أخرى:

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

5. إذا كنت تستخدم وكيلاً/VPN خاصاً بالشركة، فتأكد من أن إعدادات الوكيل لا تحظر طلبات HTTPS

إرشادات اختيار النموذج¶

المشكلة: غير متأكد من النموذج الذي تريد اختياره

النصيحة:

بعد تعيين النموذج الافتراضي في config.toml، يمكنك أيضاً التبديل مؤقتاً:

codex -m gpt-6-sol "Analyze this complex concurrency bug"

قيود بيئة العزل التي تسبب فشل الأوامر¶

المشكلة: الأوامر التي يحاول Codex تنفيذها ترفضها بيئة العزل

الحل:

1. إذا كان الأمر عملية شبكة (مثل npm install)، فمكّن الشبكة مؤقتاً: bash codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies"
2. إذا كنت تحتاج إلى كتابة ملفات خارج دليل المشروع، فوسّع نطاق الكتابة مؤقتاً: bash codex --sandbox danger-full-access "Save output to /tmp/result.txt"
3. استخدم /permissions أثناء الجلسة لعرض الأذونات الحالية وتعديلها

توضيح التكلفة¶

المشكلة: كيف تُحتسب تكاليف Codex وClaude Code؟

التوضيح:

• يتشارك Codex وClaude Code حصة خطة QCode.cc
• يمكن استخدام الخطة نفسها من كلا الأداتين في وقت واحد
• تُحتسب التكاليف بناءً على استهلاك token الفعلي، وليس حسب الأداة
• عندما يكرّر Codex العمل ذاتياً لعدة جولات، قد يكون استهلاك token لمهمة واحدة أعلى، لكنه يوفّر وقت تفاعل المطوّر
• تفرض QCode فاتورة لكل token؛ أسعار كل نموذج على qcode.cc/models، ويمكنك التحقق من الاستخدام في لوحة تحكم QCode.cc

هل يمكن أن يتعايش AGENTS.md وCLAUDE.md؟¶

نعم. إذا كان مشروعك يستخدمه كل من Codex وClaude Code:

• يقرأ Codex فقط AGENTS.md، ويتجاهل CLAUDE.md
• يقرأ Claude Code فقط CLAUDE.md، ويتجاهل AGENTS.md
• لا يؤثر أحدهما في الآخر، ويمكنك الاحتفاظ بملفات تعليمات منفصلة لأدوات مختلفة
• يوصى بالحفاظ على اتساق المواصفات الأساسية في الملفين (مثل أوامر الاختبار ونمط الشيفرة وما إلى ذلك)

10. الوثائق ذات الصلة¶

• إعداد متغيرات البيئة — إعدادات متغيرات البيئة لـ Claude Code
• البدء السريع — دليل البدء السريع لـ Claude Code
• تكامل Aider — إعداد مساعد برمجة آخر مفتوح المصدر بالذكاء الاصطناعي
• نصائح CLI — استخدام متقدم لسطر الأوامر مع Claude Code
• نصائح سير العمل — اقتراحات لسير العمل لتحسين كفاءة البرمجة بالذكاء الاصطناعي

المؤسسات ←