الإضافات (Plugins): تثبيت حزمة قدرات متكاملة بضغطة زر
📚 التنقل في السلسلة: المقال السابق [22 · مهارات الوكيل (Skills)] علمك كيفية كتابة "دليل استخدام متخصص" لـ Codex - لتجميع خطوات وسير عمل مكرر وصياغته في مهارات للوكيل (Skills). ولكن مع كثرة المهارات وإعدادات MCP وربط التطبيقات، ستجد نفسك تقوم بـ "إعداد كل قطعة على حدة" وتواجه صعوبة في النقل. يعلمك هذا المقال كيفية حزم هذه المكونات في إضافات (Plugins): لتثبيتها وإيقافها ومشاركتها كحزمة متكاملة بضغطة زر. المقال التالي [24 · القواعد والخطافات (Hooks)] سيتحدث عن كيفية إعداد نقاط تحقق وتفعيل تلقائي لـ Codex.
أصدقائي، نتحدث اليوم عن ميزة قد تبدو إضافية تجميلية ولكنها في الحقيقة متطلب أساسي ومهم جداً للعمل - وهي الإضافات (Plugins).
يقول البعض أن الإضافة هي مجرد طريقة لتجميع الملفات وتسهيل تركيبها، وهي ميزة ثانوية يفضل تأجيلها حتى إتقان المكونات الفردية أولاً. ولكن الحقيقة هي عكس ذلك تماماً. واجهت هذه المشكلة بنفسي: في أبريل من عام 2025 قمت بتهيئة مجموعة من المهارات (skills) لـ Codex في أحد المشاريع للقيام بـ "سحب تعديلات قاعدة البيانات، وتوليد وثائق الجداول"، وربطت معها خادم MCP للاتصال بالأدوات الداخلية للشركة، واستغرق الإعداد مني حوالي ساعتين. وبعد أسبوعين، أردت استخدام نفس الأدوات في مستودع مشروع آخر - فبدأت بنقل الملفات يدوياً واحداً تلو الآخر من المشروع القديم، ولكنني نسيت نقل تكوين متغير بيئة معين في ملف .mcp.json، ففشل المساعد في الاتصال بالخادم، وقضيت نصف ساعة إضافية لحل المشكلة. تلك هي معاناة تنظيم المكونات الفردية يدويًا.
تقدم الإضافات الحل الرسمي لهذه المعاناة في Codex: وهي حزم المهارات (skills) وربط التطبيقات وخوادم MCP في حزمة واحدة متكاملة يسهل مشاركتها وتثبيتها بضغطة زر. فالحزمة التي قضيت وقتاً في بنائها للمشروع A، يمكنك تثبيتها في المشروع B أو على أجهزة زملائك في العمل بضغطة زر واحدة ودون خوف من نسيان أي تكوين.
بقراءة هذا المقال، ستحصل على:
- المكونات الثلاثة التي تحزمها الإضافة، والفرق بينها وبين "المهارات الفردية" في جدول مقارنة مخصص
- كيفية تصفح وتثبيت الإضافات من "سوق الإضافات (Plugin Directory)" عبر واجهة التطبيق الرسومية أو سطر الأوامر CLI
- خطوات إضافة سوق إضافات جديد، تثبيت إضافة منه، واستدعائها باستخدام
@من سطر الأوامر بالتفصيل - بنية مجلد الإضافة وكيفية تنظيم ملفاتها يدوياً (ملف التكوين
.codex-plugin/plugin.jsonومجلدات المكونات) - شروط أمان "تأكيد الثقة" التي يفرضها النظام قبل تشغيل إضافات الطرف الثالث أو السماح للخطافات (hooks) بالعمل تلقائياً
⚠️ جميع الأوامر والمسارات والخيارات المذكورة أدناه تستند لـ المستندات الرسمية لـ Codex؛ أما أسماء النماذج والاشتراكات والميزات قيد التطوير فتتغير مع التحديثات وتعتمد على ما يظهر لديك محلياً.
01 ما هي مكونات الإضافة (Plugin)
نبدأ بالخلاصة: الإضافة هي مجلد متكامل يحتوي على ملفات التكوين والمهارات وخوادم MCP المرتبطة ببعضها، ويمكن تثبيتها وإيقافها ومشاركتها كحزمة برمجية واحدة.
لماذا نحتاج للإضافات؟ لأن إدارة المكونات الفردية يترتب عليها ثلاثة عوائق رئيسية: صعوبة النقل بين المشاريع، غياب أسلوب موحد للمشاركة مع الفريق، وصعوبة تحديث الإعدادات وتعميمها. فإذا أردت نقل مهارة وخادم MCP قمت بتهيئتها لمشروع آخر، فستضطر لنسخ الملفات يدوياً؛ ومشاركتها مع زملائك تتطلب شرحاً طويلاً لمسارات الحفظ والتعديلات المطلوبة في ملفاتهم. الإضافة تحل المشكلة بـ "وضع كل القطع في صندوق واحد"، لتقوم بنقل الصندوق بالكامل أو إعطائه لزملائك مباشرة.
تشبيه: "مجموعات الأثاث المتكاملة" من إيكيا. عندما تعجبك غرفة مكتب معينة معروضة في المعرض - تضم مكتباً وكرسياً ومصباحاً وعلب تنظيم - فإذا قمت بشرائها بشكل فردي، فستضطر للبحث عن أرقام القطع والتحقق من توافق أحجامها وتركيب كل منها على حدة. ولكن إيكيا توفر خيار شرائها كـ "مجموعة مكتب متكاملة" بطلب واحد، لتقوم بتركيبها معاً مباشرة والحصول على نفس التنسيق المطلوب. الإضافة تتبع نفس الفكرة: حزم مجموعة من المهارات والأدوات والروابط في حزمة واحدة وتثبيتها معاً، وتجنب عناء البحث عن كل قطعة وتركيبها يدوياً.
تحدد الوثائق المكونات الثلاثة التي تحزمها الإضافة كالتالي:
| المكون | وظيفته | طريقة استخدامه بعد التثبيت |
|---|---|---|
| Skills (المهارات) | إرشادات مكررة لتنفيذ مهام محددة يقرأها Codex عند الاستدعاء | يستدعيها Codex تلقائياً بناءً على تحليل الطلب، أو يدوياً برمز @ |
| Apps (تكامل التطبيقات) | قنوات الاتصال بالخدمات الخارجية مثل GitHub و Slack و Google Drive لقراءة وتحديث البيانات | تتطلب موافقة وترخيص حسابك في ChatGPT عند التثبيت أو الاستخدام الأول |
| MCP servers | خوادم لربط الأدوات وقواعد البيانات الخارجية بالبرنامج | قد تتطلب إعدادات إضافية وتفعيل الترخيص لبدء تشغيلها |
لاحظ أن الإضافة تجمع المكونات الثلاثة الأساسية - المهارات، ربط التطبيقات، وخوادم MCP. وتتوافق هذه المكونات مع ما شرحناه في المقالات السابقة: مهارات الوكيل في المقال 22، وخوادم MCP في المقال 20، ويمثل ربط التطبيقات (Apps) طريقة اتصال Codex بالخدمات السحابية. وتقوم الإضافة بربط هذه المكونات معاً.
ما هو الفرق بينها وبين كتابة مهارة فردية؟ تنصح الوثائق بالمعيار التالي: عند العمل على مستودع واحد ولسير عمل شخصي محدد، فاكتفِ بكتابة مهارة فردية محلية؛ وعند الرغبة في مشاركة الأدوات مع الفريق، أو حزم تكوينات التطبيقات وخوادم MCP معاً، أو إصدار نسخ برمجية محددة، فقم ببنائها كإضافة.
| وجه المقارنة | المهارة الفردية (للاستخدام الشخصي) | الإضافة (Plugin) |
|---|---|---|
| الاستخدام الأنسب | مستودع واحد، سير عمل شخصي، وتجربة سريعة | مشاركة مع الفريق، حزم تطبيقات و MCP، وإصدار نسخ برمجية |
| المكونات المحزومة | تقتصر على مهارة واحدة عادة | تجميع المهارات والتطبيقات وخوادم MCP والخطافات (hooks) معاً |
| أسلوب المشاركة | نسخ ونقل الملفات يدوياً للآخرين | مشاركتها عبر سوق الإضافات أو مجلد العمل بضغطة زر واحدة |
| إدارة النسخ البرمجية | لا تدعم | تحتوي على حقل version لإصدار نسخ برمجية وتحديثها |
المعيار بسيط: للمهام الفردية البسيطة واليومية اكتفِ بالمهارات الفردية؛ ولتجميع التكوينات ومشاركتها مع الفريق وإصدار نسخ برمجية تفضل الإضافات. وتجنب بناء إضافة لمهارة بسيطة تستخدمها بمفردك لتقليل الخطوات الفنية.
💡 ملخص في جملة واحدة: تجمع إضافة Codex المهارات والتطبيقات وخوادم MCP في حزمة واحدة يسهل تثبيتها وإيقافها؛ واعتمد على المهارات الفردية للاستخدام الشخصي، والمسار لربط وتجميع التكوينات ومشاركتها مع الفريق وإصدار نسخ برمجية هو الإضافات.
02 فوائد بناء وحزم الإضافات
شرحنا ماهية الإضافات. ونوضح هنا الفوائد العملية من ورائها لتتجنب المشاكل الفنية لإدارة التكوينات يدوياً.
تتلخص أهم الفوائد في النقاط الثلاث التالية:
أولاً، سهولة النقل بين المشاريع. بالعودة لمشكلة نقل مهارات وخادم قاعدة البيانات يدوياً ونسيان متغيرات البيئة. فبمجرد حزمها في إضافة، يمكنك تثبيتها في أي مشروع جديد بضغطة زر واحدة وتضمن بقاء التكوينات ومتغيرات البيئة سليمة دون نقصان.
ثانياً، سهولة المشاركة مع الفريق. عند الرغبة في نقل الإعدادات يدوياً لزملائك، ستضطر لشرح مسارات الحفظ وكيفية تعديل ملفات التكوين، ويقع الكثيرون في أخطاء إملائية. أما مع الإضافات: فيكفي نشر الإضافة في سوق إضافات الشركة الخاص، أو مشاركتها داخل بيئة العمل المشتركة في تطبيق Codex، ليقوم بقية الزملاء بتثبيتها بضغطة زر واحدة والحصول على إعدادات مطابقة تماماً.
ثالثاً، الإدارة الموحدة وإصدار النسخ. تحتوي الإضافة على حقل الإصدار version مما يسهل تحديث الإرشادات وتعميمها؛ كما تتيح إعدادات Codex تعطيل الإضافة أو تفعيلها أو تعديل صلاحيات خوادم MCP التابعة لها من ملف التكوين الرئيسي دون حاجة لتعديل كود الإضافة نفسه. بينما يصعب تعميم تعديلات المكونات الفردية الموزعة يدوياً.
تشبيه: تثبيت "ملف تعريف الإعدادات" في الهاتف المحمول. عند تسلمك لهاتف العمل من الشركة، لن يطلب منك مسؤول الدعم ضبط شبكة Wi-Fi، والبريد الإلكتروني، وصلاحيات VPN، والشهادات الأمنية يدوياً خطوة بخطوة - بل يرسل لك "ملف تعريف التكوين"، وبمجرد النقر عليه يتم ضبط كل الإعدادات دفعة واحدة، وعند الرغبة في إزالتها يكفي حذف ملف التعريف لتزول كل التكوينات بسلام. الإضافة تمثل هذا الملف لإعدادات وتكوينات Codex - تثبيت متكامل، إدارة موحدة، وحذف نظيف.
يوضح الجدول التالي الفروق العملية:
| العملية | ❌ المكونات الفردية يدوياً | ✅ الإضافة الموحدة |
|---|---|---|
| النقل لمشروع جديد | نقل يدوياً لكل ملف وكتابة الإعدادات ومخاطر النسيان | تثبيت من سوق الإضافات مباشرة وتطبيق كل التكوينات |
| مشاركتها مع الزملاء | شرح مسارات الحفظ وكتابة السطور والموافقات | نشرها في بيئة العمل وتثبيتها بضغطة زر من الزملاء |
| التحديث والتطوير | تعديل يدوي وتحديث يدوي لكل زميل للملفات | تعديل رقم النسخة ونشر التحديث ليحصل الجميع عليه تلقائياً |
تظهر أهمية الإضافات بوضوح عند العمل في فريق أو مع زيادة عدد المشاريع والتكوينات الحساسة التي تضم خوادم MCP وتكامل التطبيقات، حيث تساهم في توفير أوقات الدعم الفني وتوحيد بيئة عمل المطورين.
💡 ملخص في جملة واحدة: تكمن قيمة الإضافة في تسهيل النقل، تبسيط المشاركة مع الفريق، وتمكين الإدارة الموحدة وتحديث النسخ للمكونات المتعددة لتفادي أخطاء الإعداد اليدوي المتفرقة.
03 سوق الإضافات (Plugin Directory): متجر التطبيقات المدمج
بعد فهم طبيعة الإضافات، نأتي لمصدر الحصول عليها. يوفر Codex واجهة مدمجة تسمى "سوق الإضافات (Plugin Directory)" لتصفح وتثبيت الإضافات المجهزة.
وينقسم السوق لثلاثة أقسام رئيسية نوضحها كالتالي:
تشبيه: أقسام متجر التطبيقات في الهاتف. يحتوي المتجر على قسم للتطبيقات الموصى بها (المعتمدة والآمنة للجميع)، وقسم للتطبيقات المشتركة مع العائلة (تطبيقات الشركة المشتركة للزملاء)، وقسم لتطبيقاتك الخاصة (التطبيقات التي قمت بتطويرها بنفسك). وتطابق أقسام Codex هذه الفكرة كالتالي:
| القسم | المحتويات |
|---|---|
| Curated by OpenAI (精选 الإضافات المعتمدة) | إضافات تم فحصها واعتمادها من OpenAI وتتوفر لجميع المستخدمين، وتتميز بالأمان العالي |
| Shared with you (المشتركة معك) | إضافات قام أعضاء بيئة العمل المشتركة (Workspace) في ChatGPT بمشاركتها معك |
| Created by you (التي قمت بإنشائها) | إضافات قمت بتطويرها بنفسك أو إضافتها لبيئتك الخاصة |
ويمكنك التصفح والتثبيت بطريقتين، عبر واجهة التطبيق الرسومية أو واجهة سطر الأوامر CLI:
عبر واجهة التطبيق الرسومية: توجه لتبويب Plugins في قائمة خيارات Codex، وابحث عن الإضافة المطلوبة وانقر على Add to Codex لتثبيتها مباشرة.
عبر واجهة سطر الأوامر CLI: شغل الجلسة واكتب الأمر المائل التالي (تنبيه: الكلمة بصيغة الجمع plugins بنقطة في البداية):
codex
/pluginsستظهر واجهة تصفح الإضافات مقسمة بحسب الأسواق (marketplaces)، ويمكنك التنقل بينها والاطلاع على تفاصيل كل إضافة وتثبيتها أو إزالتها؛ والضغط على زر Space يفعل أو يوقف تشغيل الإضافة المثبتة مؤقتاً دون حذفها.
كيف تستدعي ميزات الإضافة بعد التثبيت؟ توفر الإرشادات أسلوبين للعمل:
- كتابة طلبك مباشرة باللغة الطبيعية. مثل قولك "اقرأ رسائل Gmail غير المقروءة اليوم" أو "جلب مستند إرشادات النشر الأخير من Google Drive" - ليتولى Codex مراجعة الإضافات المثبتة واختيار الأداة المناسبة لتنفيذ طلبك.
- الاستدعاء الصريح باستخدام رمز
@. عند رغبتك في تحديد إضافة معينة أو مهارة تابعة لها بدقة، اكتب رمز@متبوعاً بالاسم المناسب للتشغيل المباشر دون ترك الخيار للمساعد.
ويتطابق أسلوب الاستدعاء باستخدام @ مع ما شرحناه في المقال 22 لل مهارات، حيث يتم التعامل مع المهارات المحزومة في الإضافة بنفس الأسلوب.
💡 ملخص في جملة واحدة: يمثل سوق الإضافات متجر تطبيقات مدمج يضم ثلاثة أقسام (معتمدة، مشتركة، وخاصة)؛ ويتم التصفح يدوياً من خيارات التطبيق أو بأمر
/pluginsفي واجهة CLI، ويتم استدعاء الميزات باللغة الطبيعية أو بالإشارة للاسم صراحة برمز@.
04 أمان وصلاحيات الإضافات المثبتة
تفعيل وتثبيت الإضافة لا يعني منحها الصلاحيات المطلوبة تلقائياً - ونوضح هنا التفاصيل الأمنية الهامة التي يقع فيها المبتدئون.
تنص القواعد الأمنية بوضوح على: أن تثبيت الإضافة يتيح استخدام مهاراتها وسير عملها داخل Codex، ولكنه لا يتجاوز إعدادات الموافقة وبيئة المعزل المحددة للمحادثة. أي أن الإضافة تظل خاضعة لقيود الأمان والصلاحيات التي حددتها في المقالين 15 و 16 لحماية جهازك.
إليك متطلبات الترخيص للمكونات الثلاثة عند التثبيت:
| المكون | عند التثبيت والاستخدام |
|---|---|
| Skills (المهارات) | تعمل مباشرة بمجرد تثبيت الإضافة دون حاجة لخطوات إضافية |
| Apps (التطبيقات) | تتطلب إدخال الترخيص أو تسجيل الدخول لحساب الخدمة في ChatGPT عند التثبيت أو الاستخدام الأول |
| MCP servers | قد تتطلب إعدادات إضافية وتفعيل الترخيص (Bearer token أو تسجيل دخول) للبدء |
تلاحظ أن المهارات تعمل تلقائياً، بينما يتطلب ربط التطبيقات وخوادم MCP خطوات ترخيص إضافية. ويجب إتمام هذه التراخيص لتتمكن الإضافة من تنفيذ المهام.
وتذكر قاعدة هامة لحماية البيانات والخصوصية: عند إرسال بيانات بالاستعانة بأداة أو تطبيق تتبع للإضافة، تخضع هذه البيانات لسياسات الخصوصية وشروط الاستخدام الخاصة بالجهة المطورة للتطبيق. فمشاركة البيانات مع تطبيقات (GitHub و Slack و Drive) تعني خضوعها لسياساتها الأمنية، لذا اقتصر على ربط الخدمات التي تثق بخصوصيتها.
تشبيه: تثبيت تطبيق الهاتف للتحكم في قفل المنزل الذكي. تقوم بتنزيل التطبيق وتثبيته أولاً (تثبيت الإضافة بنجاح)، ولكنه لن يتحكم بالقفل إلا بعد الدخول للتطبيق والربط مع القفل المادي وترخيصه (ترخيص التطبيقات عند الاستخدام الأول)؛ وتفعيل ميزات التخزين السحابي يتطلب إدخال حسابك وترخيصه أيضاً (تراخيص خوادم MCP). التثبيت هو خطوة أولى، وتوثيق تراخيص الأدوات الخارجية هي خطوات منفصلة تالية - وهو نفس الأسلوب المتبع لإضافات Codex.
وعند الرغبة في إزالة أو إيقاف إضافة مثبتة، تتوفر الطريقتان التاليتان:
- إلغاء التثبيت بالكامل: افتح الإضافة في واجهة التصفح واختر Uninstall plugin. وتذكر: أن إلغاء تثبيت الإضافة يزيل ملفاتها من Codex، ولكنه لا يلغي تراخيص التطبيقات المسجلة في حساب ChatGPT، ويجب تسجيل الدخول لحساب ChatGPT وإزالتها يدوياً إن أردت.
- إيقاف التشغيل مؤقتاً: للحفاظ على ملفات الإضافة وإيقافها مؤقتاً، توجه لملف التكوين العام
~/.codex/config.tomlواكتب حقل التشغيل كـenabled = falseتحت الإضافة المعنية، ثم أعد تشغيل Codex:
[plugins."gmail@openai-curated"]
enabled = falseتكتب اسم الإضافة بالصيغة اسم_الإضافة@اسم_السوق (مثل gmail@openai-curated). ويؤدي الضغط على زر Space في واجهة CLI لتغيير هذه القيمة تلقائياً في ملف التكوين.
💡 ملخص في جملة واحدة: يقتصر تثبيت الإضافة على جلب ملفاتها وتظل خاضعة لقيود بيئة المعزل والموافقات العامة للجلسة، ويتطلب ربط التطبيقات وخوادم MCP خطوات ترخيص منفصلة؛ وإلغاء التثبيت يزيل ملفات المساعد ويتطلب إزالة تراخيص الحساب من ChatGPT يدوياً.
05 خطوات عملية: إضافة سوق، تثبيت إضافة، واستخدامها
نطبق معاً تدريباً عملياً متكاملاً: إضافة سوق إضافات جديد من GitHub ← تثبيت إضافة منه ← واستدعاؤها باستخدام @ من واجهة CLI.
يتم إدارة أسواق الإضافات عبر مجموعة أوامر codex plugin marketplace في الطرفية - وتذكر أنها أوامر طرفية عادية تشغل قبل بدء محادثة Codex وليست أوامر مائلة داخل الجلسة.
الخطوة الأولى: إضافة سوق إضافات جديد
لإضافة مستودع سوق إضافات من GitHub، اكتب الأمر التالي واستبدل owner/repo بالمسار الصحيح للمستودع:
codex plugin marketplace add owner/repoويدعم الأمر خيارات معاملات مختلفة بحسب الحاجة:
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-rootحيث يقبل الأمر كتابة مسار GitHub المختصر، أو عناوين Git الكاملة (HTTP/HTTPS أو SSH)، أو مجلد سوق محلي على جهازك. ويستخدم خيار --ref لتحديد نسخة فرع معين، ويسمح --sparse بسحب المجلدات الفرعية المحددة فقط للمستودع.
المتوقع: سيقوم Codex بتسجيل المستودع كسوق معتمد وتحديث قائمة الأسواق المتاحة. ولا تشمل هذه الخطوة تثبيت أي إضافة، بل تقتصر على عرض المتاح.
الخطوة الثانية: مراجعة الأسواق المسجلة
codex plugin marketplace listالمتوقع: ظهور قائمة بالأسواق المتاحة ومسارات فحصها (وتضم الأسواق المدمجة والأسواق التي قمت بإضافتها يدوياً)، مما يثبت نجاح إضافة السوق البرمجي.
ونعرض الأوامر الإضافية لإدارة الأسواق للرجوع إليها عند الحاجة:
codex plugin marketplace upgrade # تحديث وتنشيط كل الأسواق
codex plugin marketplace upgrade marketplace-name # تحديث سوق معين
codex plugin marketplace remove marketplace-name # إزالة سوق معينالخطوة الثالثة: فتح واجهة الإضافات وتثبيت الإضافة
ادخل لجلسة Codex وافتح واجهة التصفح:
codex
/pluginsالمتوقع: ظهور واجهة تصفح الإضافات، قم بالتبديل لتبويب السوق الجديد الذي قمت بإضافته، واختر الإضافة المطلوبة وانقر على Install plugin للتثبيت.
الخطوة الرابعة: استدعاء ميزات الإضافة
تشترط الإرشادات فتح محادثة جديدة (new thread) بعد تثبيت الإضافات لتتمكن الجلسة من استحضار وقراءة الإضافات الجديدة. واكتب طلبك باللغة الطبيعية أو أشر صراحة للإضافة أو مهارة تابعة لها باستخدام رمز @:
@<plugin_name_or_skill>المتوقع: سيقوم Codex بتفعيل المهارة أو الأداة التابعة للإضافة وتطبيق خطواتها. وفي حال تطلب المكون تسجيل الدخول أو إدخال تراخيص فستظهر التنبيهات اللازمة للمتابعة.
بإتمام هذه الخطوات، تكون قد تحققت عملياً من دورة عمل الإضافات: إضافة سوق جديد ← تثبيت إضافة منه يدوياً ← فتح محادثة جديدة واستدعاء الميزات بترميز @.
💡 ملخص في جملة واحدة: تضاف الأسواق بأمر
codex plugin marketplace addفي الطرفية، وتثبت الإضافات بأمر/pluginsداخل الجلسة، ويشترط فتح محادثة جديدة لاستدعاء ميزات الإضافة باللغة الطبيعية أو برمز@.
06 بنية مجلد الإضافة وكتابة الإعدادات يدوياً
قد ترغب مستقبلاً في حزم مهاراتك وخوادم MCP وتكوينات التطبيقات التي قمت بإنشائها في إضافة برمجية واحدة لمشاركتها. ونوضح هنا بنية المجلد وقواعد تنظيم الملفات لتتمكن من بنائها بشكل صحيح.
يوفر Codex مهارة مدمجة تسمى @plugin-creator لمساعدتك في إنشاء بنية المجلد وملف التكوين الأساسي تلقائياً - حيث تنشئ لك ملف plugin.json وتساعد في تهيئة مجلد سوق محلي لتجربة الإضافة وتطويرها. ويقترح الاعتماد عليها لتوفير الوقت وتجنب الأخطاء البرمجية.
وتتكون الإضافة يدوياً من جزأين أساسيين: ملف التكوين الرئيسي (بمثابة بطاقة الهوية) ومجلدات المكونات الفرعية.
يسمى ملف التكوين بـ plugin.json ويحفظ داخل مجلد فرعي يسمى .codex-plugin/ في جذر مجلد الإضافة، ويكتب بداخله:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}يمثل حقل الاسم name معرف الهوية الأساسي للإضافة ويشترط كتابته بتنسيق kebab-case (حروف صغيرة تفصل بينها شرطة مثل my-first-plugin) لتجنب أخطاء التسمية. وتحدد بقية الحقول مسارات المكونات المحزومة (المهارات، خوادم MCP، التطبيقات، والخطافات) كمسارات نسبية تبدأ بـ ./ وتعتمد على مجلد جذر الإضافة.
وتحفظ مجلدات المكونات الفرعية داخل مجلد جذر الإضافة وتحدد مساراتها في ملف التكوين. وتوضح القائمة التالية المسارات المعتمدة لتنظيم الملفات:
| المكون المطلوب | مسار الحفظ | حقل التكوين المقابل |
|---|---|---|
| مهارات الوكيل (Skills) | skills/<skill_name>/SKILL.md | skills |
| خطافات دورة التشغيل (Hooks) | hooks/hooks.json | hooks (تلقائي عند مطابقة المسار) |
| إعدادات خوادم MCP | .mcp.json (في جذر المجلد) | mcpServers |
| إعدادات تكامل التطبيقات (Apps) | .app.json (في جذر المجلد) | apps |
| الصور والوسائط للمتجر | ./assets/ | يحدد في قسم interface |
وتكون بنية مجلد الإضافة كالتالي:
my-first-plugin/
├── .codex-plugin/
│ └── plugin.json ← ملف التكوين الرئيسي (يحفظ بمفرده هنا)
├── skills/
│ └── hello/
│ └── SKILL.md
├── .mcp.json ← إعدادات خوادم MCP (في الجذر)
├── .app.json ← إعدادات تكامل التطبيقات (في الجذر)
└── hooks/
└── hooks.json⚠️ تنبيه هام جداً لتجنب الأخطاء: يحفظ ملف
plugin.jsonبمفرده داخل مجلد.codex-plugin/الفرعي. ويحظر وضع بقية مجلدات المكونات (skills و hooks وملفات التكوين الأخرى) داخل مجلد.codex-plugin/الفرعي، ويجب حفظها في جذر مجلد الإضافة مباشرة لتكون平級 مع مجلد.codex-plugin/. ومخالفة ذلك تمنع Codex من التعرف على المهارات والملفات المرفقة.
ونوضح قيمتين للتسهيل:
- يمكن الاستغناء عن تحديد حقل hooks عند مطابقة المسار الافتراضي. إذا حفظت ملف الخطافات في المسار
./hooks/hooks.jsonفسيقوم Codex بقراءته وتفعيله تلقائياً دون حاجة لكتابة حقلhooksفي ملف التكوين. - تتوفر خيارات إضافية للملف عند النشر. حيث تضاف حقول مثل
authorوhomepageوlicenseو قسمinterface(لتحديد الاسم والوصف المعروض وأيقونة الإضافة وألوان الواجهة وطلبات التشغيل السريع في المتجر). وتكفي الحقول الأساسية البسيطة للاستخدام والتجربة المحلية.
وتلاحظ تطابق هذه البنية مع تنظيم المهارات الفردية وملفات التكوين السابقة، نظراً لأن الإضافة صممت بالأساس لتجميع هذه المكونات في مكان واحد يسهل مشاركته.
💡 ملخص في جملة واحدة: تتكون الإضافة من ملف التكوين
.codex-plugin/plugin.jsonومجلدات المكونات المجاورة له؛ وتأكد من إبقاء مجلدات المكونات (skills و hooks و.mcp.json) في جذر مجلد الإضافة وعدم وضعها داخل مجلد.codex-plugin/؛ واستعن بمهارة@plugin-creatorللمساعدة في الإنشاء.
07 أمان الإضافات: حظر تشغيل الخطافات (Hooks) تلقائياً
نختتم بجانب أمني غاية في الأهمية، ويجب عدم التفريط فيه. فالسهولة في التثبيت تطلب حذراً مضاعفاً وتأكداً من مصادر الإضافات.
تنطبق قواعد التقييم الأمني الموضحة في المقال 16 على الإضافات أيضاً. نظراً لأن الإضافة قد تحتوي على تكامل تطبيقات (للتحكم بحساباتك الخارجية)، أو خوادم MCP (لتشغيل عمليات محلية)، أو خطافات دورة التشغيل hooks (لتشغيل سكربتات تلقائياً عند وقوع أحداث معينة في النظام). وتعمل هذه المكونات داخل بيئة الصلاحيات المتاحة للمساعد.
ولحمايتك، يفرض Codex قاعدة أمان صارمة وصريحة: لا يتم تمكين أو تشغيل خطافات (hooks) الإضافة تلقائياً بمجرد تثبيتها. وتنص الوثائق على ما يلي:
لا يعني تثبيت أو تشغيل الإضافة تمكين الخطافات (hooks) التابعة لها تلقائياً. وتعتبر الخطافات المرفقة مع الإضافات خطافات غير مدارة (non-managed hooks)، ويقوم Codex بتجاوزها وتجاهلها تلقائياً حتى يقوم المستخدم بمراجعتها وتأكيد الثقة فيها يدوياً.
الفكرة واضحة: حتى لو قمت بتثبيت إضافة تحتوي على خطافات خبيثة بالخطأ، فلن يتم تشغيل هذه الخطافات تلقائياً - بل سيتوقف Codex ويعرض نافذة لمراجعة الخطاف وسكربتات التشغيل التابعة له وتأكيد الثقة فيها أولاً. ويمثل هذا الفحص الإجباري صمام الأمان الأساسي للإضافات. وسنشرح تفاصيل عمل الخطافات وخطوات الفحص في المقال 24 · القواعد والخطافات (Hooks).
تشبيه: تركيب لوحة تحكم ذكية جديدة في المنزل، وطلب ربطها بكهرباء المطبخ. بمجرد تثبيت اللوحة وتوصيلها (تثبيت الإضافة بنجاح وتفعيل مهاراتها)، لن تقوم بتوصيل الكهرباء لأجهزة الطبخ الحساسة تلقائياً - بل تتطلب اللوحة الدخول لإعدادات الأمان وتأكيد صلاحيات الربط يدوياً (تأكيد ثقة الخطافات يدوياً). وتظل الصلاحيات الحساسة معلقة بانتظار موافقتك.
ونلخص إجراءات الفحص قبل تثبيت أي إضافة خارجية في النقاط الثلاث التالية:
| خطوة الفحص | كيفية التطبيق |
|---|---|
| التحقق من المطور | التزم بالإضافات المعتمدة من OpenAI؛ وتحقق من هوية مطور الإضافة المشتركة؛ وتجنب تثبيت إضافات من مستودعات مجهولة |
| مراجعة المكونات | تفقد محتويات وتفاصيل الإضافة قبل التثبيت للتأكد من المكونات المرفقة (تطبيقات، خوادم MCP، أو خطافات) وصلاحياتها |
| فحص الخطافات (Hooks) | عند مطالبة Codex بالموافقة على الخطاف، اقرأ السكربت والتعليمات البرمجية وتأكد من سلامتها وتجنب الموافقة العشوائية |
وهناك جوانب أمان مدمجة للمساعدة: تقتصر الإضافات المشتركة داخل بيئة العمل (Workspace) على نطاق الشركة والمنظمة المعتمد، ويُمنع أي حساب خارج المنظمة من الوصول إليها؛ ويشترط تأكيد موافقتك قبل تشغيل الخطافات؛ وتظل الإضافة خاضعة لقيود الموافقات العامة للجلسة. ولكن تظل مراجعتك الشخصية هي خط الدفاع الأهم.
وتشير الوثائق الحالية إلى أن إمكانية نشر الإضافات في سوق الإضافات العام وإدارة النشر تتوفر قريباً. ويقتصر نشر وتوزيع الإضافات حالياً على "أسواق المستودعات الخاصة" و"المشاركة داخل بيئة العمل المشتركة للشركة"، مما يسهل التحكم في مصادر الإضافات ويقلل المخاطر الأمنية.
💡 ملخص في جملة واحدة: تملك الإضافة صلاحيات قوية للوصول للأدوات والملفات، ويضع Codex حاجز أمان صارماً: يحظر تشغيل خطافات الإضافات تلقائياً ويتطلب مراجعتها والموافقة عليها يدوياً أولاً؛ والتزم بفحص مصادر الإضافات ومحتوياتها وسكربتات خطافاتها قبل التشغيل.
08 ملخص
شرحنا في هذا المقال نظام الإضافات (Plugins) في Codex بالتفصيل - وكيفية حزم المهارات والتطبيقات وخوادم MCP في حزمة واحدة وتثبيتها وإدارتها ومشاركتها أمنياً.
دعنا نلخص النقاط الأساسية معاً بشكل سريع:
| الجانب | الشرح والنقاط الهامة |
|---|---|
| مفهوم الإضافة | حزمة برمجية متكاملة تضم المهارات (skills) وتكامل التطبيقات (apps) وخوادم MCP، وتسهل النقل والمشاركة والتحديث |
| سوق الإضافات | متجر مدمج مقسم لثلاثة أقسام (معتمدة، مشتركة، وخاصة) يسهل تصفحه وتثبيت الأدوات منه |
| التصفح والتثبيت | عبر تبويب Plugins في التطبيق أو بأمر /plugins في CLI؛ واستخدام أوامر codex plugin marketplace add لإضافة أسواق جديدة |
| استدعاء الميزات | باللغة الطبيعية أو بالإشارة للاسم صراحة برمز @؛ ويشترط فتح محادثة جديدة بعد تثبيت الإضافات للعمل بها |
| إيقاف التشغيل | تعديل حقل التشغيل لـ enabled = false في ملف config.toml يدوياً وإعادة تشغيل البرنامج |
| بنية المجلد يدوياً | ملف التكوين .codex-plugin/plugin.json في مجلده الخاص، وحفظ مجلدات المكونات في جذر مجلد الإضافة مباشرة |
| أمان الإضافات | تظل خاضعة لقيود بيئة المعزل والموافقات العامة؛ ويحظر تشغيل الخطافات hooks تلقائياً ويتطلب موافقتك اليدوية الصريحة |
توضح الرسمة التالية بنية ومسار عمل الإضافات بالتفصيل:
تساعدك الرسمة في فهم دورتي العمل: دورة تثبيت واستدعاء الإضافات في الجزء العلوي، ومكونات حزمة الإضافة وشروط وتراخيص تشغيل كل مكون في الجزء السفلي لتأمين إعداداتها.
يجب أن تكون الآن قادراً على: التمييز بين كتابة مهارة فردية محلية وحزم المكونات في إضافة برمجية؛ وتصفح سوق الإضافات وتثبيت الأدوات وتوثيق التراخيص؛ وإضافة أسواق جديدة عبر سطر الأوامر؛ والتعرف على بنية مجلد الإضافة وموقع حفظ ملف التكوين الرئيسي؛ ومراجعة الخطافات وتأمين تشغيلها. هذه القدرة على حزم وتوزيع الأدوات تتيح لك توحيد وتسهيل بيئة عمل فريق المطورين بالاستعانة بإضافات مجهزة مسبقاً.
وتذكر دائماً التنبيهات الفنية - واحفظ قواعد "فتح محادثة جديدة بعد تثبيت الإضافة، وحظر وضع بقية المكونات داخل مجلد .codex-plugin/ الفرعي وحفظها في الجذر، وحظر تشغيل الخطافات تلقائياً" لتسهيل وتأمين وسرعة العمل.
المقال التالي [24 · القواعد والخطافات (Hooks)] - تحدثنا في هذا المقال والمقالات السابقة عن الخطافات (Hooks) المرفقة بالبرنامج والإضافات ودورها في إجراء الفحص التلقائي، وحظر تشغيلها تلقائياً لدواعي الأمان. سنتناول في المقال القادم تفاصيل الخطافات والقواعد البرمجية: وكيفية إعداد نقاط تحقق وتفعيل تلقائي لـ Codex عند حدوث أحداث معينة (مثل قراءة ملف، تشغيل أمر، أو بدء محادثة) لفرض المعايير البرمجية والأمنية تلقائياً ودون حاجة لتذكرها يدوياً.