دليل البدء السريع لـ Cloud Native Codex CLI

مرحباً بك في Cloud Native Codex CLI! هذا مساعد برمجة قوي بالذكاء الاصطناعي يعتمد على خدمة اشتراك تهيئة Codex الرسمية.

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

المتطلب	التفاصيل
نظام التشغيل	macOS 12+، Ubuntu 20.04+/Debian 10+ أو Windows 11 عبر WSL2
Git (اختياري، مُوصى به)	2.23+ مع مساعد PR مدمج
الذاكرة	الحد الأدنى 4 جيجابايت (8 جيجابايت مُوصى به)

1. تثبيت Codex CLI

اختر إحدى الطرق:

npm (عام)

npm i -g @openai/codex
# أو في الحالات التي يتطلّب فيها اسم الحزمة الأصلي:
# npm i -g @openai/codex@native
codex --version

Homebrew (macOS)

brew update
brew install codex
codex --version

إذا تعذّر تشغيل codex أو كانت نسخة Node قديمة، حدِّث Node (عادةً ما يتطلّب Node 22+) أو استخدم تثبيت Homebrew.

---

2. تحضير مفتاح API لـ GPTMeta Pro وإعداد Codex

تسجيل حساب GPTMeta Pro API

الخطوة 1: زيارة صفحة التسجيل

1. زيارة https://coultra.blueshirtmap.com
2. النقر على زر التسجيل لإنشاء حساب جديد
3. ملء معلومات التسجيل المطلوبة

الخطوة 2: إنشاء مفتاح API

1. بعد تسجيل الدخول بنجاح، انتقل إلى صفحة إدارة مفاتيح API
2. إنشاء مجموعة مفاتيح API جديدة

3. اختر "القناة المستقرة عالية السرعة" كاسم للمجموعة 4. توليد ونسخ مفتاح API الخاص بك

إعداد Codex

عند التشغيل، يقرأ Codex الملف config.toml من ~/.codex/. إذا لم يكن موجوداً، فأنشئه:

mkdir -p ~/.codex
nano ~/.codex/config.toml

أضِف التالي إلى config.toml (عدِّل حسب الحاجة):

# الإعدادات الافتراضية العليا
model = "gpt-4o"            # اكتب نموذجاً متاحاً فعلياً في GPTMeta Pro API
model_provider = "coultra"  # ضبط المزوّد الافتراضي

[model_providers.coultra]
name = "GPTMeta Pro API (OpenAI-compatible)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "مفتاح_GPTMeta_Pro_API_الخاص_بك"    # أدخل مفتاح API مباشرة
wire_api = "chat"           # استخدام بروتوكول OpenAI Chat Completions

# اختياري: تعريف ملف تعريفي لسهولة التبديل عبر سطر الأوامر
[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"      # طلب التأكيد عند الحاجة
sandbox_mode = "workspace-write"    # السماح بالكتابة ضمن مشروع العمل، ولا يزال دون اتصال

شرح الحقول الأساسية:

• model / model_provider: النموذج والمزوّد الافتراضيان.
• [model_providers.<id>].base_url: جذر خدمتك /v1; يتواصل Codex عبر بروتوكول Chat Completions (عادةً POST {base_url}/chat/completions).
• env_key: يحدد من أي متغيّر بيئي يجلب Codex بيانات الاعتماد.
• wire_api: نوع البروتوكول؛ لاستخدام Chat Completions استعمل "chat".
• profiles.* ومعه --profile: تجميع مجموعة إعدادات للتبديل السريع أثناء التشغيل.

---

3. التشغيل والتحقّق

تأكّد من وجود COULTRA_API_KEY في جلسة الطرفية الحالية (انظر الخطوة 2)، ثم:

# تشغيل باستخدام ملف تعريفي
codex --profile coultra "اشرح بنية المستودع الحالي باللغة العربية"

# أو تشغيل بالإعدادات الافتراضية (المزوّد مضبوط مسبقاً على coultra)
codex "ولِّد سكربت Python يجلب بيانات من API ويحفظها كـ CSV"

أثناء التشغيل، يعمل Codex داخل صندوق محلي لـ "قراءة الكود، وتعديل الملفات، وتنفيذ الأوامر". عند الحاجة إلى صلاحيات، سيطلب وفق approval_policy; يسمح workspace-write بالكتابة داخل مجلد المشروع فقط، مع البقاء دون اتصال.

---

4. مرجع سريع للصندوق/سياسة الموافقات

• سياسة الموافقات:

  • استخدم --ask-for-approval أو اضبط approval_policy للتحكّم بدرجة التفاعل.
  • --full-auto علَمٌ مريح (تدخّل أقل، مع البقاء داخل الصندوق).

• مستويات الصندوق:

  • read-only: قراءة فقط (دون كتابة، ودون اتصال)
  • workspace-write: الكتابة ضمن مجلد المشروع، مع البقاء دون اتصال
  • danger-full-access: غير مستحسن، يُماثل إلغاء الصندوق
  • في سطر الأوامر: --sandbox MODE، وفي الإعدادات: sandbox_mode="MODE".

هل تحتاج اتصالاً مؤقتاً؟ الإصدار الحالي يركّز على أمان "عدم الاتصال افتراضياً". استخدم وضع "الخطر" أو خيارات فتح الشبكة لاحقاً بحذر.

---

5. الأسئلة الشائعة (FAQ)

① 401/403: مفتاح API غير صالح أو الرصيد غير كافٍ

• أنشئ مفتاحاً جديداً من لوحة GPTMeta Pro API؛ وتحقّق من تفعيل COULTRA_API_KEY في الجلسة الحالية (echo $COULTRA_API_KEY).
• في CI، استعمل Secrets لحقن المتغيّرات البيئية وتجنّب تضمينها صراحة.

② 404 / "Resource not found": خطأ في base_url

• تتطلّب معظم التطبيقات المتوافقة أن يشير base_url إلى …/v1؛ بعض المنصّات (مثل Azure) تحتاج مقاطع مسار إضافية. المسارات الناقصة تؤدي إلى 404.

③ لم يعمل --profile أو لم تُحمَّل بعض المفاتيح

• حدِّث إلى نسخة أحدث؛ إصدارات قديمة كانت تعاني من مشكلات مع بعض مفاتيح الملف التعريفي.

④ بعد تثبيت NPM، codex غير متاح أو النسخة غير صحيحة

• حدِّث Node (موصى به 22+) أو استخدم Homebrew؛ الإصدارات الحديثة غيّرت حزمه وسلوكه في npm.

⑤ تعذّر الاتصال بمزوّد محلي/خارجي أو منفذ غير صحيح

• تحقّق من base_url; عالجت الإصدارات المبكرة أخطاء في base_url/المنفذ عن طريق التحديث.

---

6. إعداد حدٍّ أدنى قابل للاستخدام (MVP) لإعادة الاستخدام مباشرةً

# ~/.codex/config.toml
model = "gpt-4o"
model_provider = "coultra"

[model_providers.coultra]
name = "GPTMeta Pro API (OpenAI-compatible)"
base_url = "https://coultra.blueshirtmap.com/v1"
env_key = "مفتاح_GPTMeta_Pro_API_الخاص_بك"    # أدخل مفتاح API مباشرة
wire_api = "chat"

[profiles.coultra]
model_provider = "coultra"
model = "gpt-4o"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

أمر البدء:

export COULTRA_API_KEY="مفتاحك"
codex --profile coultra "أضِف أمراً فرعياً لـ CLI إلى هذا المستودع"

---

7. نصائح استخدام متقدّمة

مرجع سطر الأوامر

الأمر	الغرض	مثال
codex	واجهة تفاعلية	codex
codex "..."	واجهة تفاعلية مع نص أولي	codex "fix lint errors"
codex exec "..."	"وضع الأتمتة" غير التفاعلي	codex exec "explain utils.ts"

الوضع غير التفاعلي/CI

تشغيل Codex بدون واجهة في خطوط الأنابيب. مثال على خطوة GitHub Action:

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex exec --full-auto "update CHANGELOG for next release"

بروتوكول سياق النموذج (MCP)

يمكن تكوين Codex CLI لاستخدام خوادم MCP من خلال تعريف قسم mcp_servers في ~/.codex/config.toml. وهو مصمم ليعكس كيفية تعريف أدوات مثل Claude و Cursor لـ mcpServers في ملفات التكوين JSON الخاصة بها، على الرغم من أن تنسيق Codex مختلف قليلاً حيث أنه يستخدم TOML بدلاً من JSON، على سبيل المثال:

# IMPORTANT: the top-level key is `mcp_servers` rather than `mcpServers`.
[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }