التكامل مع Slack و Linear والـ SDK: استدعاء Codex وتوظيفه في خدماتك الخاصة

📚 التنقل في السلسلة: المقال السابق [28 · الوضع غير التفاعلي (codex exec)] شرح طريقة التشغيل المؤتمت بالكامل دون إشراف - وهي القطعة الأساسية لربط Codex بالسكربتات وخطوات CI. يتجاوز هذا المقال حدود سطر الأوامر خطوة إضافية: الأولى هي استدعاء وتوظيف Codex لإنجاز المهام من منصات التواصل والعمل اليومية للفريق مثل Slack و Linear مباشرة؛ والثانية هي استخدام حزم التطوير البرمجية (SDK) و App Server لدمج قدرات المساعد كعنصر برمجى داخل برامجك وحلولك الخاصة. المقال التالي [30 · كيفية اختيار النموذج الأنسب] سيعود لجهازك المحلي لمناقشة كيفية اختيار وضبط النموذج والجهد الأنسب لكل مهمة.

ℹ️ هذا المقال مخصص للمطورين المتقدمين. فإذا كنت تكتفي حالياً باستخدام Codex من الطرفية أو تطبيق سطح المكتب أو إضافات محررات الأكواد، فلا تحتاج لتطبيق هذه الخطوات حالياً ويمكنك تجاوز المقال بسلام. وعد إليه لاحقاً عند رغبتك في إشراك المساعد في منصات تواصل الفريق أو دمجه في تطبيقاتك البرمجية الخاصة.

نبدأ أولاً بحوار واقعي يوضح أبعاد التكامل الفني للمساعد:

يشارك زميل لقطة شاشة لرسالة خطأ في قناة Slack ويكتب: "واجهة تسجيل الدخول تعيد رمز الخطأ 500 مجدداً، من يتولى الفحص؟" ودون الحاجة لفتح جهاز الكمبيوتر الخاص بي، أكتب رداً على رسالته مباشرة: @Codex افحص الخطأ 500 المذكور أعلاه، وتتبع السبب في مستودع openai/our-backend. وخلال ثوانٍ، يضع Codex تفاعل 👀 على رسالتي ويرسل رداً يحتوي على رابط المهمة: "تم البدء، يرجى الانتظار". وأتوجه لحضور اجتماع، وعند عودتي، أجد Codex قد كتب تقريراً بأسباب المشكلة وأرفق معه كود التعديل المقترح (diff)، وبمجرد النقر على الرابط أستطيع فتح طلب السحب PR مباشرة.

أنجزت هذه المهمة بالكامل دون كتابة سطر كود واحد، دون فتح الطرفية، ودون الحاجة للتواجد أمام الكمبيوتر. ويمثل ذلك ميزة "استدعاء Codex من المنصات الخارجية" - بإنقاذه من حصار الطرفية ونقل قدراته لمنصات Slack و Linear التي يقضي فيها الفريق يومه البرمجي. ويمثل استخدام حزم SDK وخوادم App Server خطوات متقدمة: لتتجاوز استخدام Codex في منصات الآخرين، وتدمج قدراته كجزء مدمج في برامجك وتطبيقاتك الخاصة.

بقراءة هذا المقال، ستحصل على:

• التمييز الواضح بين مستويي دمج المساعد - الاستدعاء المباشر دون كود في Slack/Linear، أو دمج قدراته برمجياً باستخدام SDK / App Server
• إعداد وتفعيل استدعاء @Codex في منصة Slack، وكيفية تحديد البيئة البرمجية والمستودع وإدارة سرية البيانات للشركات
• توجيه المهام لـ Codex في منصة Linear بأسلوبين (التعيين المباشر للبطاقة أو الإشارة في التعليقات)، وأتمتة توجيه المهام باستخدام قواعد triage
• حزم التطوير البرمجية لـ Codex SDK (للغتي TypeScript و Python): كيفية التثبيت، ونماذج الأكواد المبسطة، والفرق الجوهري عن أمر codex exec
• طبيعة خادم التطبيقات App Server ومتى تلجأ لاستخدامه - مع وضع حد فاصل للبدء الآمن بحزم SDK أولاً
• نموذج برمجي بسيط مجهز للتشغيل الفوري باستخدام SDK

⚠️ جميع الأوامر والخيارات وإجراءات الدمج المذكورة أدناه تستند لـ الوثائق الرسمية لـ Codex؛ وتعتمد المسميات والخيارات المتاحة على ما يظهر في حسابك حالياً.

---

01 مستويا دمج المساعد: الاستدعاء دون كود vs الدمج البرمجي

نتناول أولاً التمييز بين مستويي التوظيف للفصل بين الاحتياجات البرمجية وتوفير الوقت.

تشبيه: توظيف فني متخصص لمساعدتك في العمل. الطريقة الأولى هي استدعاء الفني للعمل عبر منصات وتطبيقات مكتبك الحالية (مثل Slack أو Linear) وتوجيهه يدوياً بكلمات بسيطة - وتمثل Slack / Linear هذا المسار، حيث أعدت OpenAI واجهة الدمج جاهزة ولا تتطلب منك كتابة كود برمجى للبدء. الطريقة الثانية هي رغبتك في توظيف قدرات الفني ودمج خبراته لتصبح جزءاً مدمجاً داخل خط إنتاج شركتك الخاص ومنتجاتها البرمجية - ويمثل ذلك مسار الدمج البرمجي بالاستعانة بـ SDK / App Server.

وتتوزع الأدوات والمسارات كالتالي:

فئة الدمج	الأدوات المستخدمة	متطلبات العمل	بيئة التشغيل الفنية
الاستدعاء دون كود	تكامل Slack وتكامل Linear	تثبيت التطبيق وتوثيق الحسابات والاستدعاء بـ @Codex	بيئة Codex السحابية (Cloud)
الدمج البرمجي	حزم Codex SDK (TypeScript / Python)	كتابة كود لتشغيل وإدارة جلسات Codex برمجياً	في تطبيقك، خطوات CI، أو خوادمك الخاصة
الدمج البرمجي العميق	خادم التطبيقات App Server	ربط بروتوكول JSON-RPC لخدمة عمليات الدمج العميقة	إضافات محررات الكود والتطبيقات الرسومية الخاصة

ونشدد على ركيزة فنية هامة: تعتمد مهام Slack و Linear في الخلفية على تشغيل "المهام السحابية" (Codex cloud الموضحة في المقال 10). ويعني ذلك أن كتابة @Codex في تعليقات Slack يتبعها قيام المساعد بإنشاء حاوية Docker سحابية على خوادم OpenAI وسحب مستودع GitHub الخاص بك لإجراء التعديلات وتوليد كود المقارنة. وبذلك تشترك هذه الأدوات في نفس متطلبات العمل السحابي الموضحة في المقال 10 (ربط مستودع GitHub، تهيئة البيئات البرمجية، وتوفير اشتراك مدفوع).

متى نلجأ لاستخدام هذه الأدوات؟

• عند الرغبة في إرسال فكرة أو رصد خطأ برمجى لـ Codex بسرعة ودون حاجة لفتح جهاز الكمبيوتر أو تشغيل الطرفية ← يفضل استخدام تكامل Slack/Linear.
• عند الرغبة في كتابة سكربتات خاصة لإجراء مهام فحص وتنسيق مكررة في خطوات CI ← يفضل استخدام حزم SDK.
• عند الرغبة في بناء تطبيق رسومي مخصص أو إضافة لمحرر كود غير مدعوم وتتطلب التفاعل مع تفاصيل التفكير والموافقات والخطوات خطوة بخطوة ← يفضل استخدام App Server.

💡 ملخص في جملة واحدة: ينقسم ربط المساعد لمستويين - تكامل Slack/Linear للاستدعاء دون كود (يعتمد على تشغيل المهام السحابية)، وحزم SDK / App Server لدمج قدرات المساعد برمجياً داخل تطبيقاتك الخاصة؛ وحدد احتياجك قبل البدء.

---

02 الاستدعاء والعمل داخل منصة Slack

نبدأ بأداة الاستدعاء الأسرع والأكثر استخداماً - تكامل Slack. فبمجرد الإشارة لـ @Codex في قنوات أو سلاسل محادثات (threads) منصة Slack مع كتابة طلبك، يقوم المساعد بتنفيذ المهمة سحابياً ويعيد النتائج في نفس سلسلة المحادثة.

تشبيه: الإشارة لزميل متخصص في قناة العمل المشتركة. بدلاً من الذهاب لمكتب الزميل أو فتح حوار خاص، تقوم بكتابة سطر الطلب والإشارة إليه في قناة الفريق ليتلقى التنبيه ويقوم بالمعالجة ويرسل لك الحل في نفس الموضع. ويمثل Codex هذا الزميل الرقمي في Slack: تكتب الطلب بالإشارة إليه، ليتولى المعالجة السحابية ويرسل النتائج في نفس القناة. وتتميز الميزة بقراءتها للرسائل السابقة في thread مما يغنيك عن إعادة كتابة تفاصيل المشكلة.

خطوات التهيئة والربط:

تتطلب تهيئة التوصيل إتمام الخطوات الثلاث التالية وفقاً للوثائق:

1. تأمين متطلبات العمل السحابي. وهي الخطوة الأساسية - حيث يشترط توفر اشتراك مدفوع معتمد (مثل Plus أو Pro أو Business أو Enterprise أو Edu)، وتوصيل حساب GitHub بالبرنامج، وتهيئة بيئة برمجية سحابية واحدة على الأقل (environment). وهي نفس الإعدادات الموضحة في المقال 10.
2. تثبيت تطبيق Slack لـ Codex. توجه لـ قائمة الموصلات (connectors) في إعدادات Codex وقم بتثبيت وتوثيق التطبيق. وقد يتطلب تثبيته موافقة مسؤول إدارة منصة Slack للشركة.
3. إدراج @Codex في قنوات العمل. وستظهر لك رسائل تنبيه من Slack تطلب إضافة المساعد للقناة عند محاولة الإشارة إليه للمرة الأولى.

أسلوب الاستخدام:

1. أشر للمساعد وكتابة طلبك في القناة أو الـ thread: @Codex <طلبك>.
2. (اختياري) يمكنك تحديد المستودع والبيئة البرمجية المستهدفة صراحة في الطلب لتلافي الأخطاء، مثل: @Codex fix the above in openai/codex.
3. سيعرض المساعد التفاعل 👀 على تعليقك، ويرسل رسالة تضم رابط المهمة السحابية الفعالة؛ وعند الاكتمال يعرض كود التعديل (diff) وملخص الحلول في تعليق تالٍ.

آلية تحديد المستودع والبيئة السحابية تلقائياً:

عند إغفال تحديد المستودع في الطلب، يتبع المساعد الخطوات التالية للتوجيه تلقائياً:

• يقوم Codex بمراجعة البيئات البرمجية المتاحة في حسابك واختيار البيئة الأكثر توافقاً دلالياً مع تفاصيل الطلب؛ وفي حال غموض الطلب يعتمد المساعد البيئة البرمجية المستخدمة في آخر مهمة برمجية لك.
• ويتم تشغيل المهمة على الفرع الرئيسي للمستودع الأول المكتوب في خريطة المستودعات (repo map) لتلك البيئة. ويمكنك تعديل خريطة المستودعات من صفحة البيئات البرمجية للبرنامج.
• وإذا عجز المساعد عن العثور على بيئة متوافقة، سيرسل تعليقاً يوضح متطلبات التهيئة والربط البرمجي للمتابعة.

وللحفاظ على وقت المعالجة وتجنب أخطاء التوجيه، يوصى بكتابة اسم المستودع صراحة في الطلب دائماً (مثل ...in openai/our-backend) وخاصة للمطورين الذين يديرون مشاريع متعددة في نفس الوقت.

خصوصية البيانات للشركات (Enterprise settings):

يوفر البرنامج لمديري الشركات حظراً أمنياً لحماية الخصوصية: يقوم المساعد افتراضياً بعرض ملخص النتائج البرمجية وتفاصيل الحل في تعليقات Slack. وعند الرغبة في منع كتابة الأكواد في قنوات التواصل:

يمكن لمسؤول الحساب في صفحة إدارة بيئة العمل المشتركة للشركة إلغاء خيار السماح لـ Codex بكتابة الإجابات التلقائية عند اكتمال المهام (Allow Codex Slack app to post answers on task completion). وبذلك يقتصر رد المساعد على إرسال رابط المهمة السحابية الحامية فقط، ويُمنع عرض كود التعديل في القناة.

يوضح المخطط التالي دورة معالجة الطلبات القادمة من Slack:

يوضح المخطط خط سير العمل: إرسال الطلب مع الإشارة لـ @Codex من Slack ← إرسال رابط المهمة وبدء المعالجة ← بناء الحاوية السحابية وسحب الكود من GitHub ← معالجة التعديلات وإرسال النتائج لقناة Slack ← وإمكانية النقر على الرابط لمراجعة وتدقيق العمل في المتصفح.

تدريب عملي سريع:

المتطلبات: عضوية في قناة Slack وتوفر صلاحية تثبيت التطبيقات، وتوفر إعدادات العمل السحابي لـ Codex (الربط مع GitHub وتهيئة البيئات البرمجية).

الخطوة الأولى: تثبيت التطبيق. توجه لصفحة connectors وقم بتثبيت تطبيق Slack وربطه بحسابك.

المتوقع: ظهور تطبيق Codex في قائمة تطبيقات منصة Slack الخاصة بالفريق.

الخطوة الثانية: إشراك المساعد في القناة. توجه لقناة تجريبية في Slack، واكتب تعليقاً يضم الإشارة لـ @Codex ووافق على إشراكه في القناة عند ظهور تنبيه Slack.

الخطوة الثالثة: إرسال طلب تجريبي مبسط (مع كتابة اسم المستودع بدقة):

@Codex في مستودع openai/test-repo، قم بإضافة جملة "Hello from Slack" في السطر الأول لملف README، وتجنب أي تعديل آخر.

استبدل openai/test-repo بالمسار الصحيح لمستودعك التجريبي الذي تملك صلاحيات التعديل والكتابة فيه.

المتوقع: ظهور التفاعل 👀 على رسالتك من المساعد، تليها رسالة رابط المهمة؛ وخلال دقائق يعرض Codex تعليقاً يضم ملخص التعديل البرمجي ورابط الكود المقارن (diff) لفتح PR.

💡 ملخص في جملة واحدة: يتلقى تكامل Slack المهام بالإشارة لـ @Codex في القنوات، لتشغيل مهمة معالجة سحابية تتطلب توفر خيارات التوصيل الأساسية (الاشتراك، GitHub، والبيئة البرمجية)؛ وينصح بكتابة اسم المستودع صراحة في الطلب دائماً لتلافي أخطاء التوجيه.

---

03 استدعاء وتوجيه المهام داخل منصة Linear

إلى جانب قنوات المحادثة، يمكنك إدراج المساعد للعمل كعضو فعال داخل منصة إدارة المشاريع وتذاكر العمل Linear - لتتمكن من إسناد المهام البرمجية لـ Codex مباشرة ومن واجهة إدارة المشروع.

تشبيه: سحب بطاقة المهمة وتعيينها للمطور. عند استخدام لوحة مهام الفريق، تقوم بسحب تذكرة عمل معينة وتعيينها لزميلك المطور ليبدأ العمل عليها وتحديث حالتها. وبتكامل Codex، تظهر بطاقته كأحد المطورين المتاحين للتعيين - حيث يتلقى التذكرة، ويقوم بسحب الكود البرمجي وإجراء التعديلات سحابياً، ويكتب تقريراً بالخطوات في تعليقات التذكرة عند الانتهاء.

وتتوفر الميزة للحسابات التي تملك اشتراكاً سحابياً معتمداً. ويتطلب تفعيلها لحسابات الشركات موافقة المسؤول وتمكين خيار Codex for Linear في قائمة الموصلات.

خطوات التهيئة والربط:

1. تهيئة متطلبات العمل السحابي: توصيل حساب GitHub بالبرنامج، وإعداد البيئات البرمجية السحابية للمستودع المستهدف.
2. تثبيت موصل Linear: توجه لصفحة connectors وقم بتنشيط اتصال Linear.
3. توثيق حساب Linear: افتح تعليقات إحدى تذاكر العمل في Linear، واكتب تعليقاً يضم الإشارة لـ @Codex للمرة الأولى واتبع خطوات توثيق الحساب المعروضة.

أساليب إسناد المهام:

توفر المنصة الأسلوبين التاليين للعمل:

الأسلوب الأول: التعيين المباشر للتذكرة (Assignee). تعيين تذكرة العمل لـ Codex كمسؤول عن التنفيذ من خيارات التذكرة مباشرة، ليبدأ المساعد في قراءة المتطلبات والبدء في كتابة الأكواد في السحاب.

الأسلوب الثاني: الإشارة في التعليقات. كتابة إشارة لـ @Codex في تعليقات التذكرة لتوجيهه لإجراء عملية محددة أو طرح استفسار فني؛ ويقوم المساعد بالرد في نفس سلسلة التعليقات للتحاور ومتابعة التعديلات.

وكما هو الحال في Slack، يعتمد Codex على التحليل الدلالي لبيانات التذكرة لاختيار البيئة والمستودع الأنسب للمهمة؛ ولضمان دقة العمل يوصى بكتابة اسم المستودع في تفاصيل التذكرة أو في تعليق الاستدعاء صراحة (مثل @Codex fix this in openai/codex).

ويمكنك متابعة تفاصيل وخطوات المعالجة من سجل نشاط التذكرة Activity أو بالنقر على رابط المهمة السحابية المرفق؛ وعند الانتهاء يرسل Codex تعليقاً ملخصاً يضم رابط كود التعديل المقارن (diff) لفتح PR بضغطة زر.

الأتمتة وتوجيه التذاكر تلقائياً (Triage rules):

تتميز منصة Linear بإمكانية أتمتة توجيه التذاكر الجديدة لـ Codex دون حاجة لتعيينها يدوياً:

1. افتح صفحة الإعدادات Settings في Linear.
2. اختر فريق العمل المستهدف تحت قسم Your teams.
3. قم بتمكين خط سير العمل الافتراضي وتفعيل خيار Triage للمهام الجديدة.
4. أنشأ قاعدة توجيه جديدة Triage rules، واضبط خيار التعيين التلقائي كـ Delegate → Codex مع كتابة الشروط المطلوبة للتذاكر (مثل التذاكر التي تملك وسم bug أو refactor).

لتتحول التذاكر المتوافقة للمساعد تلقائياً بمجرد إنشائها. وننبه لنقطة فنية هامة: يعتمد Codex عند تشغيل التذاكر المؤتمتة على حجز حصص الاستهلاك من حساب المطور الذي قام بإنشاء التذكرة، لذا احرص على إعلام أعضاء الفريق بشروط الأتمتة المعتمدة لتنظيم حصص الاستهلاك السحابية.

مسار إضافي: موصل Linear MCP للمطورين

أشرنا لتكامل Linear السحابي لإسناد المهام. وإذا كنت تريد تمكين نسخة Codex المحلية (الطرفية، أو تطبيق سطح المكتب، أو إضافات IDE) من قراءة بيانات وتذاكر Linear مباشرة (مثل الطلب منه "اقرأ تفاصيل التذكرة ENG-123 يدوياً لتهيئة الكود")، فالطريق هو استخدام خادم Linear MCP (المشروح في المقال 20).

ويمكنك إضافة الخادم لـ Codex بكتابة الأمر التالي في الطرفية:

codex mcp add linear --url https://mcp.linear.app/mcp

ليقوم بمطالبة ترخيص حسابك بالخدمة. أو كتابته يدوياً في ملف التكوين الرئيسي ~/.codex/config.toml:

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

ثم تشغيل أمر codex mcp login linear لتنشيط الاتصال. ويعمل هذا التهيئة لنسخة الطرفية وإضافات محررات الكود معاً.

وتذكر دائماً الفصل بين المسارين: كتابة @Codex في تعليقات موقع Linear يمثل مهمة معالجة سحابية؛ وتهيئة Linear MCP يمثل ربط مصادر بيانات للنسخة المحلية للمساعد. فالأول يعني "ذهاب المساعد للعمل في منصة Linear"، والثاني يعني "استيراد المساعد لبيانات Linear لبيئة جهازك".

💡 ملخص في جملة واحدة: يدعم تكامل Linear إسناد المهام بتعيين التذكرة لـ Codex كمسؤول أو الإشارة إليه في التعليقات، مع إمكانية أتمتة التوجيه التلقائي عبر خيارات Triage rules؛ ويتوفر موصل Linear MCP لتمكين النسخة المحلية للمساعد من قراءة بيانات وتذاكر الخدمة.

---

04 حزم التطوير البرمجية (Codex SDK) لدمج المساعد برمجياً

بعد شرح أدوات الاستدعاء الجاهزة دون كود، ننتقل لمسار التطوير البرمجي لدمج المساعد - حزم Codex SDK (وهي عبارة عن مكتبات برمجية تتيح لك كتابة الأكواد للتحكم في عمليات وجلسات Codex برمجياً).

لماذا نلجأ لاستخدام حزم SDK بدلاً من أوامر الطرفية؟ لأن كتابة أوامر codex exec والاعتماد على تحليل نصوص المخرجات تعجز عن تلبية المتطلبات المتقدمة - مثل فتح جلسة محادثة مستمرة، توجيه أسئلة متتالية، والحصول على نتائج مهيكلة ومباشرة برمجياً. وتوفر حزم SDK الخيارات والواجهات البرمجية اللازمة لإنجاز ذلك. وتنص الوثائق الرسمية على:

تتيح مكتبة TypeScript البرمجية واجهات متكاملة للتحكم في Codex من تطبيقاتك الخاصة، وتوفر مرونة أعلى مقارنة بالوضع غير التفاعلي.

أهم مجالات استخدام حزم SDK:

• دمج المساعد في خطوات التكامل والنشر المستمر (CI/CD) للفريق.
• بناء وكلاء مساعدين (agents) يعتمدون على تشغيل Codex لإجراء مهام برمجية معقدة.
• بناء أدوات وميزات برمجية داخلية للشركة وتوظيف Codex لإدارتها.
• دمج قدرات وميزات Codex التوليدية داخل منتجاتك وحلولك البرمجية الخاصة.

تشبيه: الانتقال من استخدام جهاز التحكم عن بعد لكتابة كود برمجي مباشر للتحكم في المحرك. يماثل أمر codex exec جهاز التحكم البسيط - ترسل إشارة محددة مسبقاً وتنتظر تنفيذها؛ بينما تمنحك حزم SDK القدرة على كتابة أكواد تفصيلية للتحكم في المحرك: كفتح قنوات اتصال مستمرة، الاستماع للأحداث خطوة بخطوة، والتحكم في حدود وصلاحيات بيئة المعزل برمجياً.

واجهات لغتي TypeScript و Python:

يوفر البرنامج مكتبتين رسميتين للعمل، ونوضح الفروق البرمجية والبيئات المتوافقة لكل منهما لتفادي الأخطاء:

وجه المقارنة	مكتبة TypeScript	مكتبة Python
أمر التثبيت	npm install @openai/codex-sdk	pip install openai-codex
إصدار البيئة المطلوبة	بيئة Node.js الإصدار 18 فما فوق	بيئة Python الإصدار 3.10 فما فوق
طبيعة التشغيل	تعمل في الخادم البرمجي (server-side)	تتصل بخادم التطبيقات المحلي (app-server)
آلية الاتصال في الخلفية	اتصال مباشر بالخدمات	تعتمد على واجهة JSON-RPC للاتصال بخادم التطبيقات
مرحلة الاستقرار	مستقرة للاستخدام العام	مرحلة تجريبية (beta) وتخضع للتحديثات

نلخص أهم الملاحظات الفنية للمكتبات:

• يقتصر تشغيل مكتبة TypeScript على الخوادم (Node.js) ويحظر استخدامها للتشغيل المباشر من متصفحات الويب لحماية مفاتيح الترخيص.
• تتوفر مكتبة Python حالياً بنسخة تجريبية beta، ويقوم أمر التثبيت المعتاد pip install openai-codex بجلب النسخة التجريبية المعتمدة الأخيرة؛ ولجلب الميزات المتقدمة قيد التطوير استخدم معامل التثبيت المسبق pip install --pre openai-codex. وتقوم الحزمة البرمجية بإعداد وتثبيت نسخة CLI مرافقة تلقائياً، ويمكنك تمرير مسار ملف CLI مخصص يدوياً باستخدام الكلاس CodexConfig(codex_bin=...) عند الحاجة.

وتلاحظ عدم تماثل أسماء الحزم البرمجية للغتين (اسم مكتبة Node هو @openai/codex-sdk واسم مكتبة Python هو openai-codex)، لذا احرص على استخدام الاسم الصحيح عند التثبيت.

نموذج كود لـ TypeScript:

بدء جلسة ← إرسال طلب ← وعرض النتيجة:

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result);

ولمتابعة العمل وإرسال طلبات تالية في نفس الجلسة، استمر في استدعاء دالة run()؛ ويمكنك استعادة جلسة سابقة باستخدام معرف الجلسة كالتالي:

// استكمال العمل في نفس الجلسة
const result = await thread.run("Implement the plan");
console.log(result);

// استعادة جلسة سابقة بمعرفها
const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");
console.log(result2);

نموذج كود لـ Python:

استخدام المعالج with لإدارة دورة حياة الجلسة تلقائياً:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.4",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

ولتشغيل العمليات غير المتزامنة (async)، استخدم الكلاس AsyncCodex كالتالي:

import asyncio
from openai_codex import AsyncCodex

async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.4")
        result = await thread.run("Implement the plan")
        print(result.final_response)

asyncio.run(main())

التحكم في صلاحيات المعزل برمجياً:

كما هو الحال في أوامر CLI، تتيح لك الحزم تحديد صلاحيات بيئة المعزل لكل جلسة (Thread) باستخدام الكلاس Sandbox المدمج، مع إمكانية تعديل الصلاحيات لكل طلب مستقل داخل الجلسة:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    # تعديل الصلاحيات للقراءة فقط للطلب الحالي
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

الخيارات المتاحة لخصائص Sandbox في المكتبة:

الخيار	الصلاحيات المتاحة
Sandbox.read_only	قراءة الملفات فقط، ويمنع التعديل
Sandbox.workspace_write	قراءة الملفات وتعديلها داخل مجلد المشروع الحالي فقط
Sandbox.full_access	صلاحيات كاملة ودون قيود على نظام الملفات

وعند إغفال تحديد الصلاحيات عند البدء، يعتمد خادم التطبيقات خيارات الأمان الافتراضية المحددة في إعدادات جهازك. وتذكر أن تحديد الصلاحيات لطلب معين ينسحب على بقية الطلبات التالية في نفس الجلسة ما لم تقم بتعديلها مجدداً.

الفرق الجوهري بين حزم SDK وأمر codex exec:

نلخص الفروق الأساسية لتسهيل اختيار الأداة المناسبة:

وجه المقارنة	أمر codex exec (المقال 28)	حزم Codex SDK
طبيعة الأداة	أمر سطر أوامر يكتب في الطرفية	مكتبة برمجية تستدعيها في كود التطبيق
صيغة الاستخدام	تشغيل أمر وقراءة مخرجات stdout	استدعاء الحزم و كتابة كود برمجى
استمرارية الجلسة	تتطلب كتابة أمر resume لاستعادة الجلسات	كلاس Thread يدعم استدعاء دالة run() لعدة مرات متتالية
قراءة النتائج	تتطلب فحص النصوص أو قراءة سجلات JSONL	جلب خصائص كائن النتيجة المباشر (مثل final_response)
التحكم في المعزل	خيارات ومعاملات تكتب في سطر الأمر	خصائص كلاس Sandbox برمجياً ولكل طلب مستقل
الاستخدام الأنسب	المهام المنفردة والسكربتات البسيطة	بناء الوكلاء المساعدين والدمج العميق في التطبيقات

المعيار بسيط: للمهمات الفردية والسكربتات البسيطة التي تنجز بأمر واحد، اكتفِ بأمر codex exec؛ ولتسيير مهام متتالية والتحكم برمجياً في الجلسات وبناء وكلاء مستقلين، استخدم حزم SDK.

💡 ملخص في جملة واحدة: تتيح حزم Codex SDK التحكم في جلسات Codex برمجياً (مكتبة Node لـ Node.js 18+ ومكتبة Python لـ Python 3.10+)؛ وتتميز بمرونة إدارتها للمحادثات المتتالية وتفاصيل بيئة المعزل مقارنة بأمر codex exec.

---

05 خادم التطبيقات (App Server) للدمج البرمجي العميق

نتناول هنا المكون الأكثر عمقاً وتخصصاً - خادم التطبيقات (App Server). ونوضح دوره بوضوح أمنياً وتطبيقياً: يمثل خادم التطبيقات البوابة البرمجية الأساسية التي يعتمد عليها Codex لتشغيل وإدارة واجهات التفاعل الرسومية الكبيرة (مثل إضافات محررات الكود المعتمدة)، ويستخدم لبناء واجهات تفاعل مخصصة وتطبيقات رسومية متكاملة للذكاء الاصطناعي.

ما هي الخدمات التي يوفرها؟ تشير الوثائق لتقديمه خدمات: إدارة تراخيص الحساب، حفظ تاريخ الجلسات، إدارة طلبات الموافقات، وبث أحداث الوكيل لحظياً (streaming events) - وهي الخدمات الحيوية لبناء أي واجهة رسومية متكاملة.

تشبيه: المحرك والمحولات الكهربائية المرافقة له لخط الإنتاج. تمثل حزم SDK المحرك الذي يتم تشغيله لإدارة مخرجات بسيطة؛ ويمثل خادم التطبيقات (App Server) المحولات الكهربائية وخطوط التوصيل التي تعرض تفاصيل استهلاك الطاقة وتسمح بتركيب مفاتيح تحكم خارجية وحواف أمان مخصصة. ويقوم خادم التطبيقات بتوفير هذه التفاصيل البرمجية عبر واجهة بروتوكول JSON-RPC لتسهيل بناء واجهتك الخاصة.

ويعتمد خادم التطبيقات على بروتوكول JSON-RPC 2.0 لتبادل الرسائل بالاتجاهين عبر القنوات القياسية (stdio). ويتم بدء تشغيل الخادم بكتابة الأمر التالي في الطرفية:

codex app-server

ويتم معالجة دورة عمل الجلسات وتدفق الرسائل بالاستعانة بالمفاهيم التالية:

• Thread (الجلسة): وتضم سجل المحادثة والتفاعلات للوكيل.
• Turn (الجولة): وتضم طلب المطور وسجل المعالجة المرافق له، وتبث أحداث العمل لحظياً.
• Item (العنصر): ويمثل وحدة تبادل البيانات (تعليقات، تعديل ملفات، أو استدعاء أدوات).

ويقوم المطور ببناء قنوات الاتصال لاستقبال التنبيهات لحظياً وإظهار النوافذ الرسومية للموافقات والتعديلات.

وتضع الوثائق الرسمية قاعدة صارمة ومحددة لاختيار الأداة المناسبة تمنع تشتت المطورين:

يحظر تشغيل خادم التطبيقات (App Server) لخدمة مهام التشغيل الآلي أو خطوات CI، ويجب الاعتماد على حزم Codex SDK في هذه البيئات.

المعيار والحد الفاصل للاستخدام:

طبيعة التطبيق المطلوب	خيار التوصيل الأنسب
خطوات CI/CD، السكربتات، ومهام الخلفية المجدولة	حزم Codex SDK
بناء وكيل برمجي لإنجاز مهام الخلفية	حزم Codex SDK
بناء إضافة لمحرر كود، تطبيق رسومي مخصص، أو واجهة تفاعل متكاملة (تتطلب تفاصيل تاريخ الجلسات والموافقات وبث الأحداث)	خادم التطبيقات App Server

الخلاصة للمطورين: اقتصر على استخدام حزم SDK وتجنب استخدام خادم التطبيقات (App Server) في مهامك البرمجية العادية. فخادم التطبيقات مصمم بالأساس لبناء المنتجات الرسومية المتكاملة، وتوظيفه للمهام العادية يرفع من الصعوبة والتعقيد البرمجي دون فائدة حقيقية.

💡 ملخص في جملة واحدة: يمثل خادم التطبيقات (App Server) البوابة البرمجية الأساسية لـ Codex لبناء الواجهات الرسومية وإضافات محررات الكود عبر بروتوكول JSON-RPC؛ وتحظر الوثائق استخدامه لمهام CI والسكربتات وتوصي بالاعتماد على حزم SDK.

---

06 تدريب عملي: كتابة وتشغيل كود مبسط باستخدام SDK

نطبق معاً تدريباً عملياً متكاملاً لإنشاء وتفعيل كود TypeScript مبسط يستدعي حزم SDK لقراءة وتلخيص ملف نصي محلي والتحقق من سلامة المخرجات.

المتطلبات: تثبيت بيئة Node.js الإصدار 18 فما فوق، وتوفر ترخيص Codex (إتمام خطوات تسجيل الدخول عبر CLI مسبقاً).

الخطوة الأولى: إنشاء مجلد التدريب وتهيئة المشروع

mkdir codex-sdk-demo
cd codex-sdk-demo
npm init -y

الخطوة الثانية: تثبيت حزمة SDK الرسمية

npm install @openai/codex-sdk

المتوقع: اكتمال تثبيت الحزمة بنجاح وظهورها في ملف package.json والمجلد @openai/codex-sdk.

الخطوة الثالثة: إنشاء ملف نصي للقراءة

أنشأ ملفاً باسم hello.txt واكتب بداخله السطر التالي:

This project is a tiny demo for the Codex SDK.

الخطوة الرابعة: كتابة كود الاستدعاء

أنشأ ملفاً باسم run.mjs (نستخدم الامتداد .mjs لتمكين كتابة دالة await مباشرة في أعلى الملف) واكتب بداخله الكود التالي:

import { Codex } from "@openai/codex-sdk";

// إنشاء كائن الاتصال
const codex = new Codex();
// بدء جلسة عمل جديدة
const thread = codex.startThread();
// إرسال طلب القراءة والتلخيص
const result = await thread.run(
  "Read hello.txt in the current directory and summarize it in one sentence."
);

// طباعة النتيجة
console.log(result);

يتطابق الكود مع الهيكل البرمجي الموضح في القسم 04: إعداد الكائن ← بدء الجلسة ← تشغيل الطلب ← وعرض النتيجة.

الخطوة الخامسة: تشغيل الكود البرمجي ومراجعة النتائج

node run.mjs

المتوقع: يبدأ السكربت في الاتصال بالخدمة وتشغيل المهمة في الخلفية، وخلال ثوانٍ يطبع النتيجة النهائية والتي تضم تلخيصاً نصياً دقيقاً لمحتويات ملف hello.txt، مما يثبت نجاح دورة التوصيل البرمجي بنجاح.

وفي حال ظهور أخطاء متعلقة بالترخيص، فتأكد من إتمام تسجيل الدخول محلياً بكتابة codex login أولاً؛ وراجع سلامة اتصالات الشبكة على جهازك.

بإتمام هذه الخطوات الخمس، تكون قد تحققت عملياً من مسار دمج المساعد برمجياً باستخدام حزم SDK وتوجيه الطلبات وقراءة النتائج.

💡 ملخص في جملة واحدة: خطوات التدريب هي: تهيئة المشروع وتثبيت حزمة Node البرمجية @openai/codex-sdk ← إنشاء ملف hello.txt ← كتابة كود استدعاء الجلسة ودالة run ← وتشغيل الملف بأمر node ومراجعة مخرجات التلخيص؛ لإتقان العمل البرمجي مع المساعد.

---

07 جدول المقارنة وتحديد الأداة الأنسب لمشروعك

نلخص الخيارات والمنصات المختلفة الموضحة في هذا المقال لمساعدتك في تحديد الخيار الأنسب لمتطلبات عملك:

متطلبات مهمتك البرمجية	الأداة والمنصة الأنسب	الأسباب الفنية
"الإشارة للمساعد في محادثات Slack للفحص السريع"	تكامل Slack	لا تتطلب كوداً برمجياً، وتسمح بطلب المهام مباشرة من الهاتف أو القنوات المشتركة
"توجيه وأتمتة مهام تذاكر العمل في Linear للفريق"	تكامل Linear	تدعم خيارات التعيين اليدوي للتذاكر وأتمتة التوجيه عبر triage rules
"تمكين نسخة Codex المحلية من الاستعلام عن تذاكر Linear"	موصل Linear MCP	لربط مصادر البيانات محلياً وتسهيل قراءة التذاكر من إضافات محررات الكود
"كتابة سكربتات بسيطة لمهام الفحص وخطوات CI"	أمر codex exec (المقال 28)	الخيار الأسرع والأنظف، ولا تتطلب كتابة أكواد برمجية معقدة
"بناء وكيل برمجي متطور أو دمج المساعد في تطبيقك الخاص"	حزم Codex SDK	تمنحك القدرة على إدارة الجلسات وتتابع الطلبات والتحكم بالمعزل برمجياً
"بناء إضافة جديدة لمحرر كود أو تطبيق رسومي متكامل"	خادم التطبيقات App Server	يوفر واجهة JSON-RPC لبث الأحداث لحظياً وإدارة تاريخ الجلسات والموافقات

وتذكر القواعد الفنية الهامة:

• تجنب كتابة كود معقد باستخدام SDK لمهام بسيطة تنجز بأمر codex exec واحد.
• يحظر تشغيل خادم التطبيقات (App Server) لمهام CI والسكربتات العامة.
• لا تمنع خيارات التوصيل السحابي إعداد ميزات فحص محلية، ويمكنك الجمع بينهما بمرونة (Slack للطلب السريع، و SDK لخطوات CI، وم MCP للقراءة المحلية).

💡 ملخص في جملة واحدة: يقتصر دمج المساعد دون كود على Slack/Linear للتسهيل، ويستخدم أمر exec للسكربتات البسيطة، وحزم SDK للتحكم البرمجي في الجلسات، ويحجز خادم App Server لبناء الواجهات الرسومية وإضافات محررات الكود.

---

08 ملخص

شرحنا في هذا المقال تكامل Codex مع Slack و Linear، واستخدام حزم التطوير البرمجية (SDK) وخيار خادم التطبيقات (App Server) - وكيفية إعداد وربط منصات تواصل الفريق للفحص، وكتابة الأكواد للتحكم برمجياً بجلسات المساعد، وتقييد الصلاحيات الأمنية.

دعنا نلخص النقاط الأساسية معاً بشكل سريع:

الجانب	تكامل Slack / Linear	حزم Codex SDK	خادم التطبيقات App Server
طبيعة الأداة	واجهات جاهزة دون كود للإشارة للمساعد	مكتبات برمجية للتحكم بالعمليات كودياً	خادم خلفية يعتمد على بروتوكول JSON-RPC
طريقة التشغيل	كتابة @Codex في تعليقات القناة أو التذكرة	استدعاء دالة run() وإنشاء كلاس Thread	تبادل الرسائل عبر القنوات القياسية stdio
بيئة المعالجة	مهام معالجة سحابية (Codex cloud)	خوادمك الخاصة أو خطوات CI المحلية	إضافات محررات الكود والتطبيقات الرسومية
تحديد المستودع	يفضل كتابته صراحة في الطلب لتلافي الأخطاء	يحدد مسار المشروع في كود التهيئة	يدار من واجهة إعدادات خادم التطبيق
خيارات الأمان	تظل خاضعة لقيود بيئة المعزل السحابية	تحديد الصلاحيات برمجياً باستخدام كلاس Sandbox	إعداد وبث أحداث الموافقات الرسومية للمطور

يجب أن تكون الآن قادراً على: التمييز بين مستويات دمج المساعد واختيار الأداة الأنسب لمشروعك؛ وإعداد وتفويض Codex للعمل من قنوات Slack وتذاكر Linear؛ وأتمتة توجيه المهام؛ وتثبيت وتوظيف حزم SDK للغتي TypeScript و Python وكتابة كود مبسط لإدارة المحادثات المتتالية؛ وتحديد صلاحيات المعزل برمجياً؛ ومعرفة دور خادم التطبيقات App Server. هذه القدرة على استدعاء ودمج المساعد في مختلف المنصات والبرمجيات تتيح لك توظيف الذكاء الاصطناعي كعنصر فاعل يسهل الوصول إليه وتوجيهه لخدمة متطلبات عملك وعمل فريقك البرمجي.

وتذكر دائماً التوجيهات الأمنية والعملية - واحفظ قواعد "كتابة اسم المستودع صراحة في طلبات Slack/Linear، وحفظ مفاتيح الترخيص أمنياً، والبدء الآمن بحزم SDK وتجنب App Server إلا للواجهات الرسومية، والتحقق اليدوي الصارم قبل دمج الأكواد" لتأمين وتسريع دورتك البرمجية.

---

المقال التالي [30 · كيفية اختيار النموذج الأنسب] - ساعدنا تكامل الخدمات وحزم SDK على تشغيل واستدعاء المساعد من قنوات التواصل وتطبيقاتك البرمجية بنجاح. ولكن عند توجيه المهام (سواء من Slack أو SDK أو الطرفية)، يظل هناك سؤال أساسي معلق: أي النماذج البرمجية المتاحة نختار لتنفيذ هذه المهمة؟ سنتحدث في المقال القادم بالتفصيل عن خيارات النماذج: والفروق الفنية بين النماذج القوية ذات الاستدلال العالي للحلول الصعبة، والنماذج السريعة والاقتصادية للمهام البسيطة، وكيفية ضبط جهود التفكير للتوفيق بين السرعة والسرعة والجودة الفنية.

---

قراءات مقترحة

• استخدام MCP للاتصال بالأدوات الخارجية: تركيب 'منفذ خارجي' لـ Codex
• التكامل مع Git و GitHub: توظيف Codex كمراجع وكاتب للـ PRs
• دليل ملف التكوين config.toml: إدارة وضبط خيارات المساعد من ملف واحد