تتبع المشاكل الشائعة وإصلاحها: فشل التثبيت، مشاكل تسجيل الدخول，رفض تعديل الملفات，فك شفرة كل مشكلة
📚 التنقل في السلسلة: ركزت المقالة السابقة 〔36 أفضل الممارسات〕 على «كيفية الاستخدام الصحيح والناجح»، لتتحول العادات الجيدة إلى جزء من ذاكرتك العضلية. وتأتي هذه المقالة على النقيض — لمعالجة المشاكل والصعوبات التي قد تواجهها: فشل التثبيت، ومشاكل تسجيل الدخول، ورفض الأداة تعديل ملفاتك، وتراجع مستوى الاستجابة... ونقوم بفك شفرة كل مشكلة وتوضيح حلها. وتلخص المقالة التالية 〔38 قاموس المصطلحات〕 مصطلحات سلسلة Codex بالكامل لتكون مرجعًا سريعًا لك.
«يا أخي، لقد قمت بتشغيل npm install، وعند كتابة codex تظهر رسالة command not found، ماذا أفعل؟»
«عملية تسجيل الدخول تدور دون نهاية، ولا يفتح المتصفح، هل أحتاج للاستعانة بأدوات تخطي الحجب؟»
«يمكنه قراءة كودي، ولكن بمجرد مطالبته بتعديل ملف يظهر خطأ يفيد بأن الـ sandbox يمنع الكتابة — لم أقم بتهيئة هذا الشيء مطلقًا؟»
كانت هذه هي الأسئلة الثلاثة الأكثر تكرارًا في مجتمعات المطورين خلال العامين الماضيين، ويقع فيها المستخدمون بشكل يومي تقريبًا. وبصراحة، فإن 90% من مشاكل Codex ليست أخطاء برمجية في الأداة، بل هي عدم استيعاب لطبيعة عمل وسلوك الأداة الافتراضي — كعدم إتمام تسجيل الدخول، أو تفعيل القيود الأمنية، أو تضخم حجم السياق. وتتجنب هذه المقالة استعراض النظريات، وتركز على معالجة المشاكل بالترتيب الأكثر احتمالاً لظهورها، ونوضح لكل منها تفاصيل «الأعراض ← السبب ← الحل»، لتتمكن من حل المشكلة بمفردك.
بعد قراءة هذه المقالة، ستحصل على:
- دليل فحص سريع لعشر مشاكل هي الأكثر شيوعًا بصيغة «الأعراض ← السبب ← الحل»، مرتبة حسب تكرار وقوعها
- حلول محددة لمشاكل التثبيت، وفشل الدخول، وتوقف الاتصالات التي تواجه المبتدئين في البداية
- توضيح للحدود الأمنية خلف مشكلة «رفض تعديل الملفات»، وأمر السطر الواحد لحلها
- معايير واضحة لتحديد ما إذا كنت بحاجة لضغط السياق عبر
/compactأو بدء جلسة جديدة عبر/newعند تضخم السياق - قائمة تشخيص عامة «افحص هذه الثلاثة أولاً» لتتمكن من معالجة أي مشاكل جديدة تظهر بشكل مستقل
⚠️ تعتمد الأوامر ومفاتيح التكوين والسلوك الافتراضي على مستندات Codex الرسمية؛ وتتغير أسماء النماذج وأرقام الإصدارات مع التحديثات، لذا اعتمد على ما يظهره أمر
codex --versionولوحة الموديلات الفعلية لديك. وتمت صياغة حلول الصلاحيات بناءً على مستندات التوثيق و الصلاحيات الرسمية، ونشير إلى أن ميزة ملفات تعريف الصلاحيات (permission profiles) مصنفة كنسخة تجريبية (Beta) وقد تخضع للتغيير.
01 مبدأ التشخيص: افحص هذه الثلاثة أولاً، وتجنب التكهنات
الخلاصة أولاً: عند مواجهة أي مشكلة مع Codex، تجنب التسرع في إعادة التثبيت أو حذفه والتبديل لأداة أخرى، وتحقق أولاً من ثلاثة أمور بالترتيب — الإصدار، تسجيل الدخول، والصلاحيات. حيث تتركز أغلب المشاكل في هذه النقاط الثلاث.
تشبيه: التشخيص الطبي. عند دخولك لغرفة الطوارئ، لن يوجهك الطبيب لإجراء أشعة مقطعية مباشرة، بل سيقوم بفحص النبض وضغط الدم والحرارة وسؤالك عن موضع الألم — لاستبعاد المشاكل الكبرى أولاً بناءً على المؤشرات الأساسية. والأمر نفسه عند فحص Codex، تحقق من ثلاثة مؤشرات أساسية أولاً ثم انتقل للتفاصيل:
# 1. التحقق من نجاح التثبيت وصحة الإصدار
codex --version
# 2. التحقق من حالة تسجيل الدخول وبيانات الاعتماد
codex login status
# 3. التحقق من صلاحيات الجلسة الحالية (اكتبه داخل الواجهة التفاعلية)
/statusيوضح لك الأمر الأول «هل تم التثبيت بنجاح وهل الإصدار قديم»؛ ويوضح الثاني «هل فقدت بيانات الاعتماد وتتطلب إعادة الدخول»؛ ويوضح الثالث «ما هي مستويات الـ sandbox والموافقة المحددة وهل تسمح بتعديل الملفات».
وقد اعتمدت عادة: مطالبة أي شخص يسألني عن خطأ في Codex بتمرير نتائج تشغيل هذه الأوامر الثلاثة أولاً. وفي أغلب الحالات، يكتشف السائل سبب المشكلة بنفسه أثناء نسخ النتائج — إما لأن الإصدار قديم للغاية ولم يتم تحديثه منذ أشهر، أو لأن حالة login status توضح عدم إتمام الدخول.
💡 الخلاصة في جملة واحدة: يعتمد التشخيص الصحيح على فحص المؤشرات الثلاثة الأساسية (الإصدار، الدخول، الصلاحيات) أولاً، وتجنب التكهنات العشوائية.
02 فشل التثبيت، والأمر غير موجود
تواجه هذه المشكلة المبتدئين في البداية، وتتسبب في إحباط الكثيرين.
الأعراض: بعد تشغيل npm install بنجاح وكتابة codex في الطرفية، تظهر رسالة command not found: codex؛ أو تعطل التنزيل في المنتصف مع ظهور أخطاء باللون الأحمر.
السبب: لا يرجع هذا لخلل في Codex عادة، بل لوجود مشاكل في بيئة جهازك. وتتركز الحالات في ثلاث: عدم إدراج مجلد npm bin العالمي في متغيرات البيئة PATH، أو استخدام إصدار قديم لبيئة Node، أو غياب صلاحيات الكتابة في مجلد التثبيت العالمي لـ npm.
الحلول، جرب الخطوات التالية بالترتيب:
- تأكد من إصدار Node أولاً. اكتب
node --versionفي الطرفية، واستخدام إصدار قديم (مثل إصدارات رئيسية قديمة) يمنع تثبيت الأدوات الحديثة. قم بترقية Node أولاً عند الحاجة. - تشير رسالة
command not foundعادة لغياب مسار npm bin العالمي من متغير البيئةPATH. اكتبnpm config get prefixلمعرفة مسار مجلد التثبيت العالمي، وتأكد من إدراج المجلد الفرعيbinالخاص به داخل متغير البيئةPATHلجهازك. - ظهور أخطاء صلاحيات
EACCESأثناء التثبيت يشير لمحاولة الكتابة في مجلدات النظام دون امتلاك الصلاحية. وتجنب تشغيل التثبيت كمسؤول عبرsudo npm install -g— فهذا سينقل مشاكل الصلاحيات لكل العمليات القادمة. والحل الصحيح هو توجيه مجلد التثبيت العالمي لـ npm لمسار يمتلك مستخدمك الحالي صلاحيات الكتابة فيه، أو الاعتماد على مدير إصدارات Node (مثل nvm) لإدارة البيئة. - لتفادي مشاكل npm بالكامل، استخدم خيارات التثبيت الأخرى. يوفر Codex طرق تثبيت رسمية بديلة تناسب نظام تشغيلك في مستندات التثبيت. وعند إعداد جهاز Mac جديد واجهت مشاكل صلاحيات متكررة مع npm، وقمت بالتبديل لطريقة التثبيت الرسمية البديلة وأنجزت العمل في ثلاث دقائق.
فروق نظام التشغيل: تواجه مستخدمي Windows مشاكل تثبيت مختلفة (غياب WSL، مشاكل المسارات وغيرها)، ونفصل هذه الجوانب في 〔33 نقاط استخدام Windows الأساسية〕 وتجنب البحث عنها هنا.
💡 الخلاصة في جملة واحدة: تشير رسالة
command not foundلغياب مسار npm bin العالمي من متغيرPATHلجهازك، وتجنب تشغيل التثبيت كمسؤول عبر sudo لمعالجة أخطاء الصلاحيات.
03 فشل تسجيل الدخول، وانتهاء صلاحية الاعتماد
بعد إتمام التثبيت، تواجه المشكلة الثانية المتعلقة بتسجيل الدخول.
الأعراض: بعد تشغيل codex login لا تفتح صفحة المتصفح، أو تفتح الصفحة وتكتمل العملية في المتصفح ولكن تظل الطرفية تدور دون استجابة؛ أو تظهر تنبيهات «المستخدم غير موثق» أو «انتهت الجلسة» وتطالبك بإعادة تسجيل الدخول أثناء العمل.
السبب: يعتمد تسجيل الدخول الافتراضي لـ Codex على «آلية الرجوع للمتصفح (browser callback)» — حيث يقوم بتشغيل خادم محلي مؤقت في المسار localhost:1455 بانتظار إرسال المتصفح لرمز الاعتماد. وتفشل العملية في ثلاث حالات: غياب المتصفح في البيئات البعيدة أو الخوادم، أو حجب المنفذ المحلي لآلية الرجوع بواسطة جدار الحماية، أو تلف ملفات التخزين المؤقت للاعتمادات.
الحلول:
- إذا كنت تستخدم جهازك المحلي وتوقفت العملية عند الرجوع من المتصفح، تأكد من إتمام تسجيل الدخول في المتصفح بالكامل أولاً، ومن عدم استخدام منفذ
localhost:1455بواسطة تطبيقات أخرى أو حجبه بجدار الحماية. - عند العمل في خوادم بعيدة، أو بيئات Docker، أو اتصالات SSH التي لا تحتوي على متصفحات، استخدم ميزة «تسجيل الدخول عبر رمز الجهاز (device code)» (نسخة تجريبية Beta):
codex login --device-authسيعطيك الأمر رابطًا ورمز تحقق مؤقتًا، ويمكنك فتح الرابط وتمرير الرمز من أي جهاز آخر يحتوي على متصفح والضغط على تأكيد، ليتم تفعيل الاعتماد وجلسة العمل في الطرفية البعيدة مباشرة. وهي الطريقة الأسهل لتسجيل الدخول في البيئات البعيدة.
- إذا تعذر استخدام رمز الجهاز أيضًا، استخدم الحل البديل: قم بتسجيل الدخول بنجاح على جهازك المحلي أولاً، ثم انقل ملف الاعتماد المؤقت
~/.codex/auth.jsonإلى نفس المسار على الجهاز البعيد. تحذير: يحتوي هذا الملف على مفتاح الوصول الخاص بحسابك ويمثل كلمة مرورك، وتجنب إضافته لـ git أو مشاركته في مجتمعات المطورين أو تذاكر الدعم. - عند «فقدان جلسة تسجيل الدخول المتكرر»: يقوم Codex بتحديث مفتاح الوصول لحساب ChatGPT تلقائيًا قبل انتهاء الصلاحية، ولا ينبغي فقدان الدخول بشكل متكرر. وفي حال حدوث ذلك، تحقق من الحالة أولاً عبر
codex login status، وقم بتشغيلcodex logoutثمcodex loginللبدء من جديد. ويتم حفظ سجلات عمليات تسجيل الدخول في ملفcodex-login.logلمساعدتك في التشخيص.
| بيئة العمل | طريقة تسجيل الدخول الموصى بها |
|---|---|
| جهاز محلي يحتوي على متصفح | تشغيل codex login مباشرة وإتمام الخطوات في المتصفح |
| خادم بعيد / Docker /SSH دون واجهة رسومية | استخدام خيار رمز الجهاز codex login --device-auth |
| تعذر استخدام رمز الجهاز | تسجيل الدخول محليًا ونقل ملف الاعتماد ~/.codex/auth.json |
| شبكات الشركات التي تستخدم وكيل TLS / CA خاص | تحديد مسار ملف شهادة PEM عبر متغير البيئة CODEX_CA_CERTIFICATE قبل الدخول |
عند تهيئة Codex على خادم CI بعيد لا يحتوي على واجهة رسومية، قمت بتشغيل أمر codex login وظللت أنتظر فتح المتصفح لعدة دقائق قبل أن أدرك غياب الواجهة. وقمت بالتبديل لأمر codex login --device-auth واستخدمت هاتفي لمسح الرمز وتأكيده، وأنجزت العمل في عشرين ثانية. اعتمد على خيار رمز الجهاز دائمًا للبيئات البعيدة وتجنب انتظار المتصفح.
💡 الخلاصة في جملة واحدة: تجنب انتظار فتح المتصفح في البيئات البعيدة، واستخدم خيار رمز الجهاز
codex login --device-authكخيار أساسي.
04 تعطل الشبكة，وهل تحتاج لأدوات تخطي الحجب
الأعراض: تدور الأداة لفترة طويلة دون استجابة عند تسجيل الدخول أو إرسال الطلبات أو تشغيل المهام، وتنتهي بظهور أخطاء انتهاء الوقت أو فشل الاتصال.
السبب: يتم تشغيل نماذج Codex على خوادم OpenAI، ولا يمكن الاتصال بها مباشرة من بعض البيئات المحلية. وتتسبب شبكات الشركات التي تستخدم وكلاء TLS أو شهادات CA خاصة في قطع الاتصال أيضًا.
الحلول:
- تتطلب الأداة استخدام خدمات تخطي الحجب (VPN) للعمل في بعض البيئات. ولا يمكن تجاوز هذا الشرط — حيث يحتاج Codex للاتصال بخدمات OpenAI، وغياب الاتصال يعطل عمل الأداة بالكامل. تأكد من تشغيل خدمة VPN على مستوى النظام بالكامل أو شمول النطاقات المعنية بالاتصال، فتشغيل إضافات المتصفح فقط دون توجيه حركة الطرفية للشبكة الافتراضية سيبقي المشكلة قائمة.
- تأكد من توجيه حركة الطرفية عبر خدمة VPN. يظن البعض أن عمل المتصفح بنجاح يعني سلامة الاتصال، بينما تظل الطرفية معزولة ولا يمكن لـ Codex الاتصال بالخوادم. قم بإعداد متغيرات البيئة
HTTP_PROXY/HTTPS_PROXYللطرفية، أو اعتمد على أدوات توجيه الاتصال للنظام بالكامل. - عند استخدام شبكة شركة تعتمد على وكيل TLS أو شهادات CA خاصة، يفشل الاتصال بسبب تعذر التحقق من الشهادات. ويوفر Codex إمكانية تمرير مسار ملف شهادات PEM الخاص بشركتك عبر متغير بيئة مخصص:
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex loginوعند غياب متغير CODEX_CA_CERTIFICATE يتراجع للبحث في متغير SSL_CERT_FILE. وتعمل شهادات CA المخصصة مع عمليات تسجيل الدخول وطلبات HTTPS والاتصالات المشفرة عبر WebSocket بنجاح.
وعند العمل داخل شبكة شركة، كان المتصفح قادرًا على تشغيل ChatGPT بينما يفشل Codex في الاتصال، واكتشفت بعد التشخيص قيام وكيل TLS للشركة بتبديل الشهادات. وقمت بإعداد متغير البيئة CODEX_CA_CERTIFICATE وتوجيهه لملف الشهادة الموفر من قسم تقنية المعلومات، وعمل الاتصال مباشرة. وتذكر دائمًا: «قدرة المتصفح على الاتصال بالإنترنت لا تعني بالضرورة قدرة Codex على ذلك».
💡 الخلاصة في جملة واحدة: تتطلب بيئات المطورين توجيه حركة الطرفية لشبكة افتراضية (VPN) للاتصال بالخادم، واستخدم متغير
CODEX_CA_CERTIFICATEلتمرير شهادات CA المخصصة للشركات.
05 عدم تفعيل النموذج المطلوب، أو غيابه من القائمة
الأعراض: عدم ظهور نموذج معين يتحدث عنه المطورون الآخرون في لوحة /model؛ أو ظهور أخطاء «النموذج غير موجود / غير مدعوم» عند تحديد نموذج معين في ملف التكوين أو عند بدء التشغيل.
السبب: ترتبط النماذج المتاحة للحساب بـ طريقة تسجيل الدخول (اشتراك ChatGPT vs استخدام API key) وباقة الحساب؛ وتصنف بعض النماذج كنسخ تجريبية خاصة بباقات معينة؛ وتم إلغاء بعض الموديلات القديمة رسميًا.
الحلول:
- اعتمد على ما يظهر لك في لوحة
/modelالمحلية فعليًا، وتجنب حفظ الأسماء. يمثل النموذج الرائد الافتراضي حاليًاgpt-5.5بينما يمثل النموذج الخفيف المخصص للمهام البسيطة والوكلاء الفرعيينgpt-5.4-mini، ويتوفر هذان النموذجان لأغلب الحسابات. - من الطبيعي عدم ظهور نموذج
gpt-5.3-codex-sparkفي قائمتك — فهو نسخة تجريبية للبحث تقتصر إتاحتها حاليًا على مشتركي باقة ChatGPT Pro، ولا يشير غيابه لخلل في تثبيت الأداة. - عند ظهور أخطاء عدم توفر النموذج رغم كتابته في الإعدادات، راجع ملف
~/.codex/config.tomlأو علامة--modelوتأكد من عدم استخدام أسماء الموديلات الملغاة مثلgpt-5.2أوgpt-5.3-codex. قم بتغييرها للموديلات الحديثة المدعومة. - للتحقق من النموذج الفعال للجلسة الحالية، اكتب أمر
/statusداخل الجلسة التفاعلية لمراجعة التفاصيل وتجنب التخمين.
تخضع أسماء النماذج وحدود إتاحتها للتغيير المستمر مع التحديثات والباقات، ويركز هذا القسم على توضيح أسلوب الفحص والتحقق؛ وتعتمد النماذج المتاحة لك على ما تعرضه لوحة
/modelفعليًا.
💡 الخلاصة في جملة واحدة: ترتبط النماذج المتاحة بنوع الحساب وطريقة تسجيل الدخول، واعتمد على ما تعرضه لوحة
/modelفعليًا لتحديد المتاح.
06 الصلاحيات مقيدة، والـ sandbox يمنع تعديل الملفات
يمثل هذا السبب الأساسي لمشاكل «القدرة على القراءة مع العجز عن تعديل الملفات»، وهو ما يسبب حيرة للمبتدئين.
الأعراض: يستطيع Codex قراءة الكود وكتابة التحليلات والمقترحات بنجاح، ولكن بمجرد مطالبته بتعديل ملف أو تشغيل أمر كتابة يظهر خطأ يفيد بأن الـ sandbox يمنع التعديل، أو تظهر نوافذ تأكيد تطلب موافقتك مع كل خطوة تعديل.
السبب: هذا سلوك أمني افتراضي طبيعي لحمايتك وليس خللاً في الأداة. يمنع Codex افتراضيًا التعديل العشوائي للملفات على جهازك — حيث يشغل الأوامر داخل sandbox مقيد الصلاحيات لحماية الملفات؛ ويطلب موافقتك الصريحة قبل التعديل أو الاتصال بالشبكة أو الخروج لمجلدات خارج مساحة العمل. وشعورك بالتقييد هو دليل على فاعلية الحماية الأمنية الافتراضية.
تشبيه: استئجار شقة. يمنحك المالك (الإعداد الافتراضي لـ Codex) صلاحيات «معاينة الشقة» فقط في البداية، ويمنع هدم الجدران أو تغيير الأثاث؛ وإذا كنت تريد إجراء تعديلات وديكورات، فيجب الاتفاق أولاً وتحديد «التعديلات المسموحة» بوضوح. ولا يهدف هذا للتضييق عليك، بل لمنع التعديلات العشوائية دون تفويض صريح منك.
الحلول، باتباع طريقتين:
للسماح بالتعديل لمرة واحدة مؤقتة، استخدم علامات سطر الأوامر. حدد مستوى الـ sandbox عبر
--sandbox(أو اختصارًا-s)، وحدد سياسة الموافقة عبر--ask-for-approval(أو اختصارًا-a). وللسماح بالتعديل بحرية داخل مجلد المشروع وطلب الموافقة عند الخروج منه، استخدم المزيج الذهبي اليومي:bashcodex --sandbox workspace-write --ask-for-approval on-requestتحدثنا بالتفصيل عن خيارات الصلاحيات ودمجها في 〔15 الصلاحيات والـ sandbox والموافقة〕 وتجنب تكرارها هنا.
لتعيين الإعدادات كخيارات افتراضية دائمة، اكتبها في ملف
~/.codex/config.toml. وتقدم ملفات تعريف الصلاحيات الحديثة (permission profiles - تجريبية Beta) ثلاثة مستويات مدمجة:
| ملف تعريف الصلاحيات | القدرات المسموحة | الحالات المناسبة |
|---|---|---|
:read-only | السماح بالقراءة فقط، ومنع كتابة أي أوامر أو تعديلات | معاينة وقراءة الكود وإعداد التقارير دون تعديل الملفات |
:workspace | السماح بالكتابة داخل مجلد مساحة العمل والمجلدات المؤقتة للنظام | التطوير اليومي العادي وتعديل ملفات المشروع الحالي |
:danger-full-access | إلغاء قيود الـ sandbox المحلية بالكامل | تجنب تشغيله على جهازك الشخصي، واقتصر على البيئات المعزولة |
قم بتعيين ملف تعريف الصلاحيات المطلوب في خيار default_permissions. وانتبه لملاحظة هامة تؤكدها الجهة الرسمية: لا يمكن دمج ملفات تعريف الصلاحيات الجديدة مع إعدادات sandbox_mode القديمة — ففي حال كتابة خيار sandbox_mode في أي ملف تكوين أو تمرير علامة --sandbox في سطر الأوامر، سيتم تجاهل ملفات تعريف الصلاحيات الجديدة وتفعيل النظام القديم. اختر أحد النظامين وتجنب كتابتهما معًا.
قمت سابقًا بتعيين الصلاحيات الكاملة كإعداد افتراضي عام بحثًا عن البساطة، وطلبت منه في مجلد مؤقت لا يحتوي على git «حذف الملفات غير المستخدمة»، وكاد أن يبدأ في مسح ملفات مجلد المستخدم الرئيسي الخاص بي — لذا يقتصر استخدام خيارات الصلاحيات الكاملة على الحاويات والبيئات المعزولة فقط، وتعيينها كخيار افتراضي لجهازك الشخصي هو مخاطرة غير مدروسة.
💡 الخلاصة في جملة واحدة: مشكلة «رفض تعديل الملفات» هي حماية أمنية افتراضية، واستخدم علامات
-s/-aمؤقتًا أو اكتب الإعدادات في ملفconfig.tomlبشكل دائم، وتجنب خلط إعدادات الصلاحيات القديمة والجديدة.
07 MCP 连不上
07 فشل اتصال خادم MCP
الأعراض: قمت بتهيئة خادم MCP (Model Context Protocol)، ولكن لا تظهر الأدوات الخاصة به داخل Codex، أو يظهر خطأ يفيد بفشل الاتصال عند بدء التشغيل.
السبب: خادم MCP هو عملية مستقلة منفصلة، ويقوم Codex بالاتصال به بناءً على طريقة التشغيل المحددة. ويرجع فشل الاتصال لعدة أسباب: خطأ في كتابة أمر التشغيل، غياب الاعتمادات أو حزم التشغيل اللازمة، غياب متغيرات البيئة المطلوبة (مثل مفاتيح API المخصصة للخادم)، أو قيام جدار الحماية بمنع الاتصال بالمنفذ.
الحلول:
- شغل خادم MCP بشكل منفصل خارج Codex أولاً. قم بتشغيل الخادم مباشرة في الطرفية بالاعتماد على أوامر التشغيل المحددة في مستنداته، وراقب الأخطاء التي تظهر. وتتركز أغلب المشاكل في هذه الخطوة — كعدم صحة مسار التشغيل، أو غياب الحزم المطلوبة، أو غياب متغيرات البيئة.
- راجع تفاصيل إعداد خادم MCP في ملف
config.toml، وتأكد من مطابقة مسار وأوامر التشغيل والوسائط (args) ومتغيرات البيئة للقيم المطلوبة بدقة وتجنب التخمين. - تتطلب بعض خوادم MCP الاتصال بالإنترنت، فتأكد من سماح الـ sandbox بالوصول للشبكة. حيث يتم إغلاق الشبكة افتراضيًا للـ sandbox ويمنع الاتصال بالخارج.
- عند استمرار فشل الاتصال، راجع سجلات Codex لمعرفة ما إذا كانت المشكلة هي «تعذر بدء تشغيل العملية» أم «بدء تشغيل العملية مع فشل المصافحة (handshake)». ويشبه تشخيص اتصال خادم MCP تشخيص أي خدمة خارجية: تأكد من تشغيل العملية أولاً ثم تتبع الاتصال.
تحدثنا عن فكرة بروتوكول MCP كمنفذ توصيل خارجي في 〔20 استخدام MCP للربط مع الأدوات الخارجية〕، ونركز هنا على حل المشكلات. واستغرق إعداد أول خادم MCP لي نصف ساعة من المحاولات لأكتشف في النهاية غياب متغير بيئة هام — وتشغيل الخدمة بشكل مستقل خارج Codex أولاً يوفر عليك الكثير من الوقت والجهد في التشخيص.
💡 الخلاصة في جملة واحدة: عند فشل اتصال خادم MCP، تشغيله بشكل مستقل خارج Codex أولاً يظهر سبب المشكلة بوضوح في أغلب الأوقات.
08 تضخم السياق، وتراجع ذكاء النموذج
الأعراض: بعد استمرار الحوار في الجلسة لفترة طويلة، يبدأ Codex في «فقدان الذاكرة» — كنسيان القواعد المحددة مسبقًا، أو تكرار ارتكاب الأخطاء التي قمت بتوجيهه لتجنبها، أو تقديم ردود غير منطقية.
السبب: لكل جلسة حد أقصى لحجم نافذة السياق (context window) يمثل سعة «الذاكرة المؤقتة» للنموذج. ومع استمرار الحوار وتضخم المحتوى، يتم استبعاد المعلومات القديمة تدريجيًا لصالح الجديدة، مما يتسبب في «نسيان» القواعد وتراجع جودة الإجابات.
تشبيه: سبورة الكتابة. مساحة السبورة محدودة، وعند امتلائها بالكامل سنضطر لمسح الأجزاء القديمة لكتابة محتوى جديد. ولا يعني هذا تراجع ذكاء النموذج، بل هو استبعاد للذاكرة القديمة بالتدريج.
الحلول، بضرورة التمييز بين «الحاجة للضغط» أو «الحاجة للتجديد»:
- إذا كنت بحاجة لمواصلة العمل على نفس المهمة وتراجع أداء النموذج، اكتب أمر
/compactداخل الجلسة. سيقوم بتلخيص الحوار السابق في نسخة موجزة لتوفير مساحة من الـ tokens، مع الاحتفاظ بالقواعد والتعليمات الأساسية. وهو الحل المناسب لمواصلة العمل مع مهام طويلة السجلات. - إذا كنت تريد الانتقال لمهمة جديدة وتجنب تداخل التعليمات مع السابقة، اكتب أمر
/newلبدء جلسة جديدة نظيفة داخل نفس واجهة CLI، أو اكتب أمر/clearلمسح الشاشة وبدء جلسة جديدة بالكامل. ويكمن الفرق في: أن أمر/newيحتفظ بمحتوى الشاشة القديم للأعلى للرجوع إليه؛ بينما يقوم أمر/clearبمسح محتوى الشاشة وبدء الجلسة الجديدة مباشرة. - اعتمد على فحص حجم السياق المتبقي عبر أمر
/statusباستمرار، وتجنب انتظار تراجع ذكاء النموذج. وعادتي الحالية هي فحص الحالة عبر/statusمع المهام الطويلة بشكل مستمر، وتشغيل/compactيدويًا فور اقتراب امتلاء السياق لحماية جودة العمل.
| طبيعة الحالة | الإجراء المناسب |
|---|---|
| مواصلة العمل الحالي مع تضخم الجلسة وتراجع التركيز | تشغيل أمر /compact لتلخيص الجلسة وتوفير مساحة للسياق |
| الانتقال لمهمة جديدة وتفادي تداخل التعليمات | تشغيل أمر /new لبدء جلسة جديدة نظيفة |
| مسح الشاشة وبدء جلسة جديدة بالكامل | تشغيل أمر /clear لمسح المحتوى والبدء من جديد |
| فحص المساحة المتبقية للسياق | تشغيل أمر /status لمراجعة التفاصيل |
💡 الخلاصة في جملة واحدة: تراجع ذكاء النموذج يعني امتلاء نافذة السياق، واستخدم أمر
/compactلمواصلة العمل الحالي، وأمر/newعند الانتقال لمهمة جديدة.
09 تجاوز التكلفة / الحد الأقصى للاستخدام
الأعراض: ظهور تنبيهات تفيد بنفاد رصيد الاستخدام أو التقييد المؤقت في باقة الاشتراك؛ أو زيادة قيمة الفاتورة عن المتوقع عند استخدام API key.
السبب: يختلف نظام الاحتساب تمامًا بين الخيارين — حيث يعتمد اشتراك ChatGPT على حدود استخدام للباقة يتم تجديدها دوريًا؛ بينما يعتمد نظام API key على احتساب الاستهلاك الفعلي للمخرجات والمدخلات، وتؤدي زيادة تشغيل النماذج القوية ورفع قوة الاستدلال لزيادة التكلفة بسرعة.
الحلول:
- عند نفاد رصيد باقة الاشتراك، تتبقى أمامك خيارات الانتظار لتجديد الرصيد أو ترقية الباقة. وتتمثل الطريقة الأساسية لتوفير الرصيد في تجنب تشغيل النماذج القوية للمهام البسيطة — اعتمد على المزيج
gpt-5.4-miniوقوة استدلال منخفضة للمهام الروتينية، واحتفظ بالنموذج الرائد وقوة الاستدلال العالية للمهام الصعبة فقط. ووضحنا هذه القواعد بالتفصيل في 〔30 كيفية اختيار النموذج〕. - عند زيادة فاتورة API key عن المتوقع، تأكد من عدم الإفراط في اختيار موديلات قوية أو رفع قوة الاستدلال (
model_reasoning_effort) للحد الأقصى دائمًا. فاستخدام نموذج رائد مع مستوىxhighلإصلاح خطأ إملائي بسيط هو استهلاك مفرط للموارد والمال. وقم بضبط قوة الاستدلال حسب صعوبة المهمة (minimal/low/medium/high/xhigh) لخفض التكلفة مباشرة. ويمكنك تعيين الخيار المتوسط افتراضيًا في ملف~/.codex/config.tomlعبرmodel_reasoning_effort = "medium"، وتعديله مؤقتًا عند الحاجة عبر-c model_reasoning_effort=medium. - تفويض المهام المتكررة والبسيطة للوكلاء الفرعيين مع النماذج الخفيفة. تظهر ميزة السرعة والتكلفة لـ mini بوضوح مع المهام البسيطة المتكررة (مثل تعديل الأسماء أو تنظيف الاستيرادات).
قمت سابقًا بقفل إعدادات قوة الاستدلال على وضع xhigh تفاديًا لتعقيد الضبط، وتسبب ذلك في زيادة فاتورة استهلاك API بشكل ملحوظ لمهام بسيطة كان يمكن إنجازها في ثوانٍ. وضبط النماذج وقوة الاستدلال بشكل صحيح هو الطريقة الأكثر فاعلية لخفض التكلفة.
💡 الخلاصة في جملة واحدة: رشد استخدام باقة الاشتراك، وقم بخفض مستويات النماذج وقوة الاستدلال لنظام API لتفادي زيادة الفواتير، وتجنب استخدام الإعدادات القصوى للمهام البسيطة.
10 المشاكل الخاصة بنظام Windows، وكيفية التراجع عند ارتكابه لخطأ
تتعلق المجموعة الأخيرة بمشاكل نظام التشغيل Windows، وكيفية التراجع عند حدوث أخطاء تعديل الكود.
المشاكل الخاصة بنظام Windows
الأعراض: ظهور أخطاء في قراءة المسارات، أو اختلاف سلوك الـ sandbox عن الشروحات العامة، أو تعطل بعض الميزات عند التشغيل الأصلي على Windows.
السبب: يختلف تطبيق الـ sandbox ونظام الملفات والشبكة في نظام Windows الأصلي مقارنة بأنظمة macOS / Linux.
الحلول: للحصول على تجربة عمل متطابقة تمامًا مع بيئات Linux على نظام Windows، تنصح التوجيهات الرسمية باستخدام بيئة WSL (Windows Subsystem for Linux). وقمنا بتفصيل مشاكل التثبيت والمسارات وتهيئة WSL الخاصة بنظام Windows في 〔33 نقاط استخدام Windows الأساسية〕، وعند مواجهة أي مشكلة تتعلق بطبيعة عمل نظام Windows فراجع تلك المقالة مباشرة وتجنب التعديل العشوائي.
كيفية التراجع عند ارتكاب خطأ في تعديل الكود
الأعراض: قام Codex بإجراء تعديلات واسعة على الكود وتسبب ذلك في تعطل عمل الميزة أو تحريف المنطق، وتريد التراجع للنسخة السابقة.
السبب: يقوم Codex بتعديل الملفات الحقيقية في مجلد العمل مباشرة، ولا يقوم بإنشاء نسخ احتياطية للملفات تلقائيًا.
الحلول، مرتبة حسب الأمان والاعتمادية:
- الاعتماد على Git كخيار أساسي. وهذا هو السبب خلف تأكيدنا المستمر على ضرورة إجراء
git commitلحالة الكود النظيفة قبل مطالبة Codex ببدء العمل. وعند حدوث مشكلة، استخدم أمرgit diffلمراجعة ما تم تعديله، وتشغيلgit restore(أوgit checkout) للتراجع عن التعديلات والعودة لآخر commit نظيف مباشرة. ويمثل Git أداة التراجع الأكثر أمانًا واعتمادية للمطور. - مع المجلدات المؤقتة التي لا تخضع لإدارة Git، لا تتوفر وسيلة سهلة أو تلقائية للتراجع — وهو السبب خلف تصنيف قاعدة «الالتزام بـ Git قبل بدء العمل» كأحد أهم القواعد في [المقالة 36].
- تقييد الصلاحيات مسبقًا. إذا كنت متخوفًا من تعديل ملفات معينة، استخدم وضع القراءة فقط
:read-onlyأولاً لمطالبته بتقديم مقترح التعديل، وقم بتفعيل وضع الكتابة بعد مراجعتك وموافقتك للتصرف بوعي بدلاً من معالجة المشاكل لاحقًا.
تجرعت مرارة التعديل بدون commit مسبق عند مطالبة Codex بإجراء إعادة هيكلة كود واسعة، وقام بتعديل ثلاثة ملفات جانبية لم أطلب لمسها وتسبب في تعطل العمل، واضطررت للتراجع اليدوي سطرًا بسطر واستغرق ذلك نصف ساعة من وقتي. ومنذ ذلك الحين، أصبحت قاعدة «الـ commit النظيف قبل تفعيل Codex» خطوة أساسية لا أهملها أبدًا.
💡 الخلاصة في جملة واحدة: راجع مشاكل Windows في 〔المقالة 33〕؛ والوسيلة الاعتمادية الوحيدة للتراجع عن أخطاء التعديل هي تشغيل
git commitقبل مطالبته بالعمل.
ملخص
قمنا في هذه المقالة بمراجعة عشر فئات من المشاكل والصعوبات الشائعة مع Codex وحلولها، ونلخصها في النقاط التالية:
- فحص المؤشرات الثلاثة أولاً: تشغيل
codex --version، وcodex login status، و أمر/statusداخل الجلسة، حيث تتركز أغلب المشاكل في الإصدار أو الدخول أو الصلاحيات. - المشاكل الأساسية الثلاث: ترجع رسالة
command not foundلعدم تضمين مسار npm bin فيPATH؛ واستخدم خيار رمز الجهازcodex login --device-authللبيئات البعيدة؛ وتطلب الشبكات المحلية استخدام خدمات VPN وتوجيه حركة الطرفية مع إمكانية تمرير شهادات CA للشركات عبرCODEX_CA_CERTIFICATE. - مشكلة «رفض تعديل الملفات» هي ميزة أمنية: استخدم علامات
-s/-aمؤقتًا لتسهيل العمل أو اكتب الإعدادات في ملفconfig.tomlللضبط الدائم، وتجنب خلط الخيارات القديمة والجديدة. - تراجع ذكاء النموذج يشير لامتلاء السياق: استخدم أمر
/compactللتلخيص ومواصلة العمل، وأمر/newلبدء جلسة جديدة نظيفة. - التحكم في التكلفة: خفض مستويات النماذج وقوة الاستدلال للمهام البسيطة؛ واستخدم أمر
git restoreللتراجع عن التعديلات غير المرغوبة بشرط إتمام commit مسبق للعمل.
تستطيع الآن تشخيص أي خطأ يواجهك مع Codex بشكل مستقل باتباع خطوات «الأعراض ← السبب ← الحل»، واستخدام منهجية فحص المؤشرات الأساسية لحل أي مشكلات جديدة تواجهك.
المقالة التالية 〔38 قاموس المصطلحات〕 تمثل مسك الختام لسلسلة Codex بالكامل — حيث سنقوم بجمع وترتيب جميع المصطلحات البرمجية والتقنية التي وردت في السلسلة (الـ sandbox، الموافقة، قوة الاستدلال، بروتوكول MCP، الوكلاء الفرعيون، و codex exec...) في قاموس مصطلحات مرتب لتسهيل البحث والرجوع إليه. وقبل المغادرة، فكر في هذا السؤال البسيط: من بين الحلول الموضحة في هذه المقالة، كم حلًا يرتبط مباشرة بالالتزام بقاعدتين أساسيتين — «التراجع والتأكيد قبل العمل» و«تحديد الصلاحيات»؟ هل تستطيع تحديدها؟ سنلتقي في المقالة القادمة.