الوضع غير التفاعلي (codex exec): تشغيل المساعد في السكربتات وخطوات CI
📚 التنقل في السلسلة: المقال السابق [27 · التشغيل الآلي والتكامل المستمر (CI/CD)] قدم نظرة شاملة على "أتمتة العمل مع Codex" - المهام البرمجية الأنسب للأتمتة وكيفية إعدادها في خطوات CI. يركز هذا المقال على الأمر البرمجي الأساسي المحرك لهذه العمليات:
codex exec، والذي يمثل "الوضع غير التفاعلي" الذي يتلقى الطلب وينفذ المهمة ثم يغلق فوراً ودون فتح واجهة المحادثة الرسومية. المقال التالي [29 · التكامل مع Slack و Linear والـ SDK] سيتحدث عن كيفية ربط هذه القدرات البرمجية بمنصات التواصل ونظم تذاكر الدعم والعمل.
أصدقائي، نتحدث اليوم عن أمر برمجى ستلجأ لاستخدامه عاجلاً أم آجلاً في عملك - وهو codex exec.
أشرنا إليه باختصار في المقال 08 الخاص بـ "سطر الأوامر CLI" وشبهناه بـ "طلب الوجبات الخارجية": حيث ترسل الطلب (رسالة prompt)، لتعمل عمليات المعالجة في الخلفية وتصلك النتيجة النهائية في الطرفية مباشرة ودون حاجة لتواجدك. ولكن ذلك المقال قدم فكرة عامة فقط. ويكشف هذا المقال تفاصيل ومسارات عمل هذا الأمر وكيفية دمج مخرجاته وتمريرها في الأنابيب البرمجية للتشغيل الآلي.
لماذا نهتم بالوضع غير التفاعلي؟ لأن وضع المحادثة التفاعلي المعتاد (الذي تدخل إليه بكتابة أمر codex) يملك عائقاً أساسياً: وهو اعتماده على وجود مطور بشري أمام الشاشة - ليقرأ المحادثة، ويوافق على تشغيل الأدوات، ويراجع الأكواد. ولكن عند الرغبة في "فحص ومراجعة كود التعديلات اليومية للمستودع تلقائياً كل صباح"، "محاولة إصلاح الكود تلقائياً بمجرد فشل اختبارات CI"، أو "تمرير مخرجات أخطاء البناء للمساعد ليقدم تقريراً بأسباب المشكلة" - فلا يتوفر مطور بشري أمام الشاشة للموافقة. والتوقف لطلب إذن المطور يعطل العمل البرمجي بالكامل. تم تصميم أمر codex exec خصيصاً ليعمل في غياب المطور البشري.
وبمعنى بسيط، يمثل إتقانك لأمر codex exec الحد الفاصل بين "استخدام Codex كأداة مساعدة" و"دمجه كعنصر برمجى فعال داخل دورة عملك المؤتمتة".
بقراءة هذا المقال، ستحصل على:
- التمييز الواضح بين أمر
codex execووضع المحادثة التفاعلي المعتاد، والمهام الأنسب لتشغيله في غياب الإشراف البشري - فهم الميزة الفنية الأهم للأمر: توجيه السجلات والبيانات لقناة
stderrوحصر النتائج النهائية في قناةstdoutلتسهيل ربط الأنابيب البرمجية - كيفية استخدام خيار
--json(لإخراج السجلات كأحداث مهيكلة مقروءة للآلة) وخياري-o/--output-last-message(لحفظ الملاحظة النهائية في ملف) بالتوازي داخل خطوات CI - فهم حدود صلاحيات الأمان لبيئة المعزل في الوضع غير التفاعلي (والتي تعمل بالقراءة فقط افتراضياً ويجب إعطاؤها صلاحيات الكتابة صراحة)
- طريقتان لتمرير مدخلات الأنابيب القياسية stdin (تمرير البيانات كملفات مرجعية مع كتابة الطلب، أو استخدام
codex exec -لجعل stdin هو الطلب بالكامل) - نموذج بسيط قابل للتنفيذ والنسخ لتجربة الأتمتة: تشغيل المهمة ← استقبال المخرجات ← وكتابة سكربت لتكرار المعالجة
⚠️ جميع الأوامر والخيارات المذكورة أدناه تستند لـ الوثائق الرسمية لـ Codex؛ وتعتمد مسميات النماذج والإصدارات على ما يتوفر لديك محلياً حالياً.
01 الفروق الجوهرية والمهام الأنسب للوضع غير التفاعلي
نبدأ بالخلاصة: صمم أمر codex exec ليعمل في غياب الإشراف البشري - في السكربتات، المهام المجدولة، وخطوات التكامل المستمر (CI)، حيث يحظر التوقف لطلب الأذونات ويجب تشغيل المهمة حتى النهاية وإعادة المخرجات بصيغة تقبلها البرامج التالية.
تذكر أن كل الممارسات السابقة كانت تتم في وضع المحادثة التفاعلي - حيث تدخل بكتابة codex لواجهة TUI (واجهة الطرفية الرسومية)، وترسل الطلب، وتتابع كتابة الأكواد، وتوافق على تشغيل الأدوات. ويفي هذا الأسلوب بمعظم المهام اليومية بشرط تواجدك.
ولكن تتوفر ثلاث فئات من المهام تفضل إنجازها في غيابك:
الفئة الأولى: المهام الروتينية المتكررة والمملة. مثل "إعداد ملخص التغييرات البرمجية لآخر 10 تعديلات تمت في المستودع". وهي مهمة بسيطة ولكنها مكررة - ولا تود فتح Codex يدوياً كل صباح ونسخ التعديلات وتلقي الملخص ونقله.
الفئة الثانية: البيئات التي تفتقر للواجهات الرسومية. مثل خوادم البناء في CI، خوادم الاستضافة البعيدة، وحاويات Docker، حيث يُمنع تشغيل واجهة TUI الرسومية لعدم توفر متصفح أو نافذة تفاعلية.
الفئة الثالثة: الرغبة في إرسال مخرجات المساعد لبرنامج آخر. مثل توجيه Codex لتلخيص سجل أخطاء البناء في جدول Markdown، وإرسال الجدول مباشرة لملف نصي أو تمريره لأمر gh pr comment لنشره كتعليق في PR. ويتطلب ذلك أن يعيد المساعد المخرجات النصية نظيفة وخالية من السجلات الفنية لتتمكن البرامج التالية من قراءتها.
تشبيه: ماكينة البيع الذاتي مقابل موظف البيع خلف الطاولة. يمثل وضع المحادثة التفاعلي الموظف خلف الطاولة - تتحدث معه، ويقوم بالتحضير، ويمكنه سؤالك "هل تريد إضافة نكهة معينة؟"، ويسلمك المنتج عند الانتهاء. ويمثل أمر codex exec ماكينة البيع الذاتي - تضغط على الزر (ترسل الأمر البرمجي)، لتعمل الماكينة في الخلفية وتخرج لك المنتج في فتحة الاستلام (قناة stdout)، دون وجود موظف، ودون توجيه أسئلة، ودون حاجة لوجود مشرف. وتكمن فائدتها في إتمام المعاملات تلقائياً: ليلاً، في خطوط البناء، أو لخدمة مئات العمليات بالتوازي.
أهم حالات استخدام codex exec في المشاريع:
- "فشل بناء المشروع في CI، وبدء المساعد تلقائياً في فحص الأكواد وإصلاح العطل وفتح PR بالتعديل" - تشغيل مؤتمت بالكامل في الخلفية.
- "تجميع التعديلات الأخيرة وتوليد وثائق التغيير (release notes) وحفظها في ملف" - مهمة مكررة تنفذ بسكربت بسيط.
- "تمرير سجل أخطاء البناء البرمجي للمساعد عبر الأنابيب ليقوم بتحليله وتلخيص المشكلة واقتراح الحلول" - اختصاراً لخطوات النسخ واللصق اليدوية.
💡 ملخص في جملة واحدة: صمم أمر
codex execليعمل في غياب الإشراف البشري (كعمل الماكينات التلقائي) - في المهام المكررة، البيئات الخالية من الواجهات، وعند الرغبة في تمرير مخرجات المساعد لبرامج أخرى؛ لتجنب التوقف لطلب الموافقات.
02 الاستخدام الأساسي لأمر codex exec
تتميز كتابة أمر codex exec بالبساطة - حيث تكتب الأمر متبوعاً بنص الطلب (prompt) بين علامتي تنصيص، وتضغط زر الإدخال:
codex exec "总结这个仓库的结构，列出最该警惕的 5 个地方"سيقوم Codex بقراءة مجلد المشروع الحالي، وتجهيز خطة العمل، وعرض خطوات المعالجة في الطرفية، ثم يعرض النتائج النهائية ويغلق الجلسة فوراً - ودون التوقف لطلب مدخلات أو فتح نافذة المحادثة. وهذا هو جوهر العمل غير التفاعلي: التنفيذ السريع والمغادرة دون حوار.
تشبيه: إرسال بريد إلكتروني يضم قائمة مهام للمساعد، وانتظار الرد المكتمل. يمثل وضع المحادثة التفاعلي مكالمة الهاتف - حوار مستمر وتعديل للطلبات أثناء الحديث. ويمثل أمر codex exec إرسال رسالة بريد - تكتب فيها كل المتطلبات بوضوح (نص الطلب)، ليتسلمها المساعد وينفذ العمل بالكامل ويرسل لك النتيجة النهائية في رسالة رد. ولا يمكنك مراجعته أثناء العمل لتعديل الشروط، لذا احرص على صياغة الطلب بوضوح من المرة الأولى.
أهم الخيارات والطلبات التي يمكنك استخدامها:
# استخدام الاسم المختصر codex e لسرعة الكتابة (يطابق codex exec تماماً)
codex e "解释这个项目是干什么的"# اختيار نموذج معين لتنفيذ الطلب الحالي (استخدم المسميات المتاحة في حسابك)
codex exec -m gpt-5.5 "审查当前改动，列出潜在 bug"# تشغيل المهمة دون حفظ سجلاتها في تاريخ المحادثات (وضع ephemeral)
codex exec --ephemeral "快速过一遍这个仓库，给点下一步建议"وننبه لـ فارق هام جداً عن وضع المحادثة التفاعلي المعتاد: عند تشغيل المساعد تفاعلياً ومحاولته تعديل ملف، يتوقف لطلب إذنك صراحة؛ بينما في وضع codex exec (المصمم للعمل الآلي) يمتنع المساعد عن إظهار نوافذ طلب الموافقة أثناء التشغيل. وتعتمد قدرته على تعديل الملفات بالكامل على صلاحيات بيئة المعزل التي حددتها عند بدء التشغيل (كما سنوضح في القسم 04)، وتذكر أنه لن يتوقف ليسألك.
⚠️ شرط Git الإجباري لـ Codex: يشترط البرنامج تشغيل الأوامر داخل مجلد مهيأ كمستودع Git (ويمكنك تخطي هذا الشرط بكتابة
--skip-git-repo-check)، لحماية ملفاتك من أي تعديلات عشوائية قد يجريها المساعد وصعوبة التراجع عنها في غياب Git. وإذا حاولت تشغيل الأمر في مجلد عادي فسيتم إيقافه تلقائياً. واستخدم خيار تخطي الفحص فقط في البيئات المعزولة والآمنة وفقاً للوثائق.
💡 ملخص في جملة واحدة: يمثل أمر
codex exec(أو الاختصارcodex e) أسلوب تشغيل مباشر يتلقى الطلب وينفذه ثم يغلق الجلسة دون التوقف لطلب موافقات أثناء العمل؛ ويشترط التشغيل داخل مستودع Git (أو استخدام خيار تخطي الفحص عند الضرورة).
03 توجيه السجلات لـ stderr وحصر النتائج في stdout
نتناول هنا الميزة التقنية الأهم لأمر codex exec والتي تتيح دمج مخرجاته وتمريرها في الأنابيب البرمجية بسلام.
المشكلة: ينتج عن تشغيل Codex سجلات فنية طويلة - تفكير المساعد، الأدوات المستدعاة، والملفات المقروءة. وإذا قمت بمحاولة حفظ مخرجات المساعد في ملف نصي، فستمتلئ ملفاتك بهذه السجلات الفنية المزعجة ويصعب استخلاص النتيجة النهائية (مثل تقرير المراجعة) منها.
يقدم Codex الحل بـ فصل قنوات المخرجات لخطين منفصلين:
توجيه السجلات والبيانات الفنية لقناة stderr (الأخطاء القياسية)، وحصر المخرجات والنتائج النهائية في قناة stdout (المخرجات القياسية). ويمثل هذان الخطان قنوات المخرجات المعتمدة في أنظمة Unix، ورغم عرضهما معاً في واجهة الطرفية للمطور، إلا أن أدوات الحفظ > والأنابيب | تقتصر افتراضياً على قراءة قناة stdout فقط. وبذلك يتم عزل وتصفية النتائج تلقائياً.
تشبيه: عزل مخلفات البناء عن المنتج النهائي في موقع العمل. يترافق بناء المنزل مع ضجيج ومخلفات وأتربة (تمثل قناة stderr الصاخبة والمؤقتة)؛ ولكن المنتج النهائي الذي يتسلمه العميل هو فيلا نظيفة ومرتبة (تمثل قناة stdout النظيفة). ويتم إخراج مخلفات البناء من الباب الجانبي للموقع، وتسليم الفيلا من البوابة الرئيسية - لتضمن خلو عملية التسليم من أي مخلفات. وتماثل قنوات Codex هذا الفصل.
يوضح المثال التالي سهولة استخدام الميزة لحفظ تقرير التعديلات:
codex exec "给最近 10 个提交生成发布说明" | tee release-notes.mdالمتوقع: ستشاهد خطوات وسجلات عمل المساعد تعرض في الطرفية (عبر stderr)، وعند الانتهاء يتم كتابة تقرير التغييرات وعرضه؛ وبفتح ملف release-notes.md ستجد تقرير التغييرات نظيفاً وخالياً من أي سجلات فنية جانبية لكون أداة tee قد استقبلت مخرجات stdout فقط.
وتسهل هذه القنوات إتمام العمليات التالية:
| العملية المطلوبة | صيغة الأمر البرمجي | آلية العمل |
|---|---|---|
| حفظ النتائج النهائية فقط في ملف | codex exec "..." > out.md | جلب مخرجات stdout وحفظها، وعرض سجلات stderr في الطرفية |
| حفظ النتائج وعرضها في الطرفية معاً | codex exec "..." | tee out.md | تقوم أداة tee بنسخ مخرجات stdout للملف وعرضها |
| تمرير النتائج مباشرة للحافظة (copy) | codex exec "..." | pbcopy | نسخ النتائج النظيفة للحافظة للاستخدام المباشر |
| حفظ السجلات والنتائج في ملفات منفصلة | codex exec "..." > out.md 2> log.txt | توجيه مخرجات stdout للملف out، وسجلات stderr للملف log |
واجهت مشكلة سابقاً عندما حاولت دمج القنوات بكتابة العلامة 2>&1 في السكربت، فامتلأت ملفات المخرجات بسطور التفكير الفنية للبرنامج وتعطلت قراءتها برمجياً. وتذكر دائماً إبقاء القنوات منفصلة وتجنب دمجها لتلقي نتائج نظيفة ومباشرة.
💡 ملخص في جملة واحدة: يوجه أمر
codex execسجلات العمل لقناة stderr والنتائج النهائية لقناة stdout لتسهيل تصفية وحفظ النتائج عبر أدوات الحفظ والأنابيب تلقائياً؛ وتجنب دمج القنوات لتلافي تعبئة الملفات بالسجلات الفنية.
04 أمان وصلاحيات المعزل في الوضع غير التفاعلي
تحدثنا عن مخرجات الأمر، ونوضح هنا ضوابط الأمان والصلاحيات لـ codex exec عند العمل في الخلفية وغياب المطور البشري.
تفرض المنصة قاعدة أمان صارمة في الوضع غير التفاعلي: يعمل أمر codex exec افتراضياً في وضع القراءة فقط لبيئة المعزل (read-only) - ليتولى المساعد قراءة الملفات وتحليلها وتقديم المقترحات، ويُمنع نهائياً من تعديل أي ملف في المشروع أو تشغيل عمليات خارجية ذات أثر جانبي ما لم تقم بتغيير الصلاحيات صراحة.
ويرجع هذا الحظر لمنع المساعد من إجراء تغييرات غير محسوبة على كود المشروع في غياب المراجع البشري. وتنصح الإرشادات بـ منح المساعد الصلاحيات الأضيق التي تضمن نجاح عمله فقط.
تشبيه: تصريح دخول الفني لإجراء الصيانة في غيابك. تمنح الفني تصريحاً بالدخول للمكتب لقراءة العدادات وتدوين الملاحظات فقط (وضع القراءة فقط read-only)؛ وإذا تطلب الأمر إصلاح عطل معين فتمنحه تصريحاً بالدخول وتعديل الأجهزة داخل مجلد العمل المحدد (وضع كتابة مجلد العمل workspace-write)؛ وتجنب تماماً منحه تصريحاً عاماً ومفتوحاً للعبث بجميع غرف ومحتويات الشركة دون رقابة (وضع الصلاحيات الكاملة danger-full-access). فتقييد الصلاحيات هو أساس الأمان للأتمتة.
لتعديل الصلاحيات، استخدم معامل --sandbox (أو الاختصار -s):
| وضع المعزل | الصلاحيات المتاحة | الاستخدام الأنسب |
|---|---|---|
read-only (الافتراضي لـ exec) | قراءة الكود والتحليل فقط، ويُمنع تعديل الملفات أو تشغيل عمليات خارجية | لمراجعة الكود، كتابة التقارير، وتلخيص الملاحظات |
workspace-write | السماح بالقراءة وتعديل الملفات داخل مجلد المشروع الحالي فقط | لتمكين المساعد من إصلاح الأكواد وتعديل الملفات البرمجية |
danger-full-access | صلاحيات كاملة ودون قيود على نظام التشغيل | في بيئات البناء المعزولة فقط (CI runners أو حاويات Docker) |
صيغ كتابة الأوامر بحسب الصلاحيات:
# الوضع الافتراضي: مراجعة الكود واستخراج الملاحظات أمنياً ودون تعديل للملفات
codex exec "审查当前改动，列出潜在 bug"# تمكين صلاحيات التعديل للمجلد الحالي: للسماح للمساعد بإصلاح الأكواد وكتابة الملفات
codex exec --sandbox workspace-write "修好失败的测试用例"# وضع الصلاحيات الكاملة: يحظر تشغيله على جهازك الشخصي ويقتصر على بيئات البناء المعزولة
codex exec --sandbox danger-full-access "<المهمة_المعزولة>"وننبه لثلاث نقاط تقنية هامة:
- تجنب استخدام المعامل
--full-autoالمعتمد في الإصدارات القديمة، حيث يعتبر حالياً خياراً ملغى وتنبيهات الاستبدال تطلب استخدام--sandbox workspace-writeلتوحيد خيارات الأمان. - حظر تشغيل وضع
danger-full-accessعلى أجهزة المطورين الشخصية لتفادي مخاطر العبث بالملفات والنظام خارج نطاق المشروع. - تتوفر خيارات لتشغيل الأتمتة بشكل نظيف (ephemeral execution): يتيح خيار
--ignore-user-configتجاوز قراءة ملف التكوين العام للمستخدمconfig.tomlلتلافي تداخل الإعدادات الشخصية للمطور؛ ويساعد خيار--ignore-rulesفي تخطي فحص ملفات القواعد.rulesالمحلية لضمان ثبات تشغيل السكربتات في البيئات المختلفة.
واجهت مشكلة سابقاً في خطوات البناء لنسيان كتابة صلاحية الكتابة، حيث كان المساعد يقرأ الكود ويعجز عن تعديل الملفات البرمجية، وزال الإشكال فور إضافة معامل --sandbox workspace-write للأمر. وتذكر دائماً كتابة الصلاحيات صراحة عند الرغبة في التعديل.
💡 ملخص in جملة واحدة: يعمل أمر
codex execافتراضياً في وضع القراءة فقط لبيئة المعزل لحمايتك؛ ويشترط كتابة--sandbox workspace-writeللسماح بتعديل ملفات المشروع؛ وتجنب تشغيل الصلاحيات الكاملة إلا في بيئات البناء المعزولة.
05 استخدام خيار --json وخياري المخرجات
تتطلب كتابة السكربتات البرمجية لتتبع نتائج Codex الحصول على مخرجات مهيكلة وسهلة القراءة برمجياً بدلاً من النصوص المرسلة للمطورين.
ويوفر Codex خيارين للحصول على المخرجات المهيكلة وتخزينها:
أولاً: خيار --json لجلب أحداث التشغيل مهيكلة
يؤدي إضافة خيار --json (أو --experimental-json في بعض التحديثات) لتحويل مخرجات قناة stdout من نصوص عادية إلى سطور JSON مستقلة (JSON Lines / JSONL) - حيث يكتب المساعد سطراً جديداً بصيغة JSON عند وقوع أي حدث أو تغير في حالة المعالجة.
تشبيه: الانتقال من مشاهدة مسرحية لقراءة سجل الأحداث للمخرج. يمثل النص العادي مشاهدة العرض والاطلاع على النتيجة العامة؛ ويمثل خيار --json الحصول على ورقة المخرج التي تدون تفاصيل العمل خطوة بخطوة: كبدء تشغيل الجلسة، بدء تشغيل الأداة، انتهاء الأداة، والرموز المستهلكة؛ مما يتيح للسكربتات قراءتها وفحصها وتوجيه العمليات بناءً عليها.
codex exec --json "总结这个仓库的结构" | jqوتحتوي السطور البرمجية الناتجة على أحداث مثل بدء الجلسة thread.started وخطوات العمل turn.started / turn.completed وأحداث الأدوات item.completed وسجلات الأخطاء error. وإليك نموذجاً للسطور البرمجية الناتجة:
{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"仓库包含 docs、sdk、examples 三个目录。"}}
{"type":"turn.completed","usage":{"input_tokens":24763,"output_tokens":122}}ويمكن للسكربتات قراءة هذه الحقول البرمجية لفحص نجاح المعالجة أو رصد الرموز المستهلكة وتوجيه الخطوات التالية.
ثانياً: خياري حفظ المخرجات -o و --output-last-message
عند الرغبة في حفظ الرسالة والنتيجة النهائية للمساعد في ملف مستقل لتوجيهها للخطوات التالية، يوفر البرنامج خيار -o <file_path> (أو الصيغة الكاملة --output-last-message):
codex exec "提炼项目元信息" -o ./summary.mdونشير لـ ميزة هامة: يقوم خيار -o بكتابة الرسالة النهائية في الملف المحدد، دون حجب طباعتها في قناة stdout، مما يتيح لك الاستمرار في توجيه المخرجات القياسية للأنابيب البرمجية الأخرى بمرونة.
المقارنة واختيار الخيار الأنسب:
| المطلوب إنجازه | الخيار البرمجي الأنسب | مخرجات stdout المتوقعة |
|---|---|---|
| فحص تفاصيل العمليات، تتبع تقدم الأدوات، أو جلب الرموز المستهلكة | --json | سطور برمجية متتالية بصيغة JSON (JSONL) |
| حفظ الملاحظة النهائية في ملف نصي مباشرة | -o <path> | كتابة الملف مع بقاء النص العادي مطبوعاً في الطرفية |
| تشغيل عمليات CI متكاملة تتطلب الفحص والقراءة معاً | استخدام --json و -o معاً | سطور JSON في الطرفية، وكتابة الملاحظة النصية في الملف المختار |
وتمثل كتابة الخيارين --json و -o معاً في نفس الأمر الصيغة المفضلة لخطوات CI/CD - لتلقي سجلات الفحص برمجياً وكتابة التقرير النهائي للمطورين في نفس الوقت.
ويمكنك استدعاء معامل --output-schema وتمرير ملف JSON Schema محدد لإجبار المساعد على صياغة النتائج النهائية وفق حقول برمجية ثابتة ومحددة (مثل حقول "اسم_المشروع" و "قائمة_الملفات") لتسهيل معالجتها برمجياً.
💡 ملخص في جملة واحدة: يحول خيار
--jsonالمخرجات لـ سطور JSON متتالية (JSONL) لتسهيل قراءتها برمجياً وتتبع العمليات، ويقوم خيار-oبكتابة الرسالة النهائية في ملف مستقل مع بقاء طباعتها في الطرفية؛ وينصح بدمجهما معاً لخطوات CI/CD.
06 تمرير مدخلات الأنابيب القياسية stdin لـ codex exec
شرحنا كيفية توجيه مخرجات Codex. ونبين هنا كيفية تمرير البيانات للمساعد كمدخلات عبر الأنابيب القياسية (stdin)، وهي ميزة هامة لتسيير العمليات التلقائية.
الفائدة: الرغبة في تمكين المساعد من معالجة بيانات ديناميكية تنتج عن تشغيل أدوات أخرى - مثل تمرير سجل أخطاء البناء أو مخرجات الفحص أمنياً - وتجنب خطوات النسخ واللصق اليدوية.
وينقسم تمرير البيانات لـ أسلوبين فنيين بحسب موضع كتابة إرشادات العمل:
الأسلوب الأول: كتابة إرشادات العمل يدوياً، وتمرير البيانات كملفات مرجعية (prompt + stdin). تكتب نص الطلب البرمجي في سطر الأمر، ويقوم المساعد بمعاملة البيانات القادمة من الأنبوب القياسي كملفات مرجعية سياقية للمهمة.
الأسلوب الثاني: تمرير الطلب والبيانات معاً عبر الأنبوب القياسي (codex exec -). حيث يضم الأنبوب إرشادات العمل والبيانات معاً، وتوجه المساعد لقراءتها مباشرة دون معاملات إضافية.
تشبيه: أسلوب تسليم المعاملات والملفات للسكرتير. الأسلوب الأول يماثل تسليمه الملفات يدوياً وتوجيهه شفهياً بقولك "قم بتلخيص هذه الأوراق وتحديد المشاكل" - فالتوجيه صادر منك، والأوراق تمثل المرجع (الطلب + stdin). الأسلوب الثاني يماثل تسليمه مغلفاً يحتوي على ورقة التعليمات والأوراق معاً وقولك "نفذ ما بداخل المغلف" - فالتعليمات والأوراق بداخل المغلف معاً (codex exec -). ويحدد استخدام كل منهما طريقة بناء الأكواد وتكاملها.
الأسلوب الأول: كتابة الطلب وتمرير البيانات كمرجع (prompt + stdin)
يستخدم عند رغبتك في كتابة الإرشادات يدوياً وتمرير مخرجات أداة أخرى كبيانات مرجعية. وتتبع الأداة السلوك التالي:
عند استقبال بيانات عبر stdin مع كتابة نص الطلب في الأمر، يتعامل Codex مع نص الطلب كإرشادات عمل رئيسية ومع البيانات القادمة كملفات مرجعية سياقية للمهمة.
مثال لتمرير سجل أخطاء اختبارات البناء للمساعد لقراءتها واقتراح الحلول:
npm test 2>&1 \
| codex exec "总结失败的测试，提出最小改动的修复方案" \
| tee test-summary.mdالمتوقع: يتم تمرير سجلات اختبارات البناء (بما في ذلك الأخطاء عبر 2>&1) كمرجع لـ Codex، ويقوم المساعد بقراءتها وتطبيق إرشاد التلخيص وكتابة الحل وحفظ النتائج في ملف test-summary.md تلقائياً.
أو لتمرير السطور الأخيرة من سجل أخطاء الخادم للمراجعة:
tail -n 200 app.log \
| codex exec "找出最可能的根因，引用最关键的几条报错，给出接下来三步排查建议" \
> log-triage.mdالأسلوب الثاني: جعل stdin هو الطلب بالكامل (codex exec -)
يستخدم عند رغبتك في بناء نص الطلب والإرشادات برمجياً وديناميكياً من السكربت أو قراءتها من ملفات جاهزة. ويكفي كتابة علامة الشرطة - في نهاية الأمر لتوجيه Codex لقراءة الطلب بالكامل من الأنبوب القياسي:
# قراءة إرشادات الطلب بالكامل من ملف نصي وتمريرها للمساعد
cat prompt.txt | codex exec -# بناء نص الطلب والإرشادات برمجياً وتمريرها للمساعد
printf "用 3 条要点总结这段错误日志：\n\n%s\n" "$(tail -n 200 app.log)" \
| codex exec -ويساهم هذا الأسلوب في فصل كتابة الإرشادات والطلبات عن كود السكربت الرئيسي - حيث تحفظ إرشادات العمل في ملفات مستقلة (مثل prompt.txt) ويقوم السكربت بقراءتها وتمريرها للمساعد مباشرة، مما يسهل تعديل الشروط مستقبلاً دون مساس بالأكواد البرمجية للسكربت.
💡 ملخص في جملة واحدة: يحدد موضع الإرشادات طريقة التمرير - إرشادات مكتوبة وبيانات قادمة من الأنبوب تستخدم صيغة الطلب والأنبوب (prompt + stdin)؛ وإرشادات وبيانات مدمجة في الأنبوب تستخدم صيغة الشرطة (
codex exec -) لقراءة الطلب بالكامل من stdin.
07 استعادة ومتابعة الجلسة السابقة: أمر codex exec resume
لا يقتصر الوضع غير التفاعلي على المهام المنفردة، بل يتيح لك ربط العمليات وتسيير مهام متتالية - كفحص الأخطاء أولاً، ومطالبة المساعد بإصلاح المشاكل المكتشفة بناءً على سياق الفحص المكتمل. ويتم ربط الجلسات بالاستعانة بأمر resume.
تشبيه: سباق التتابع وتسليم العصا. ينهي المتسابق الأول فترته (جلسة codex exec الأولى) ويسلم العصا للمتسابق الثاني (أمر codex exec resume) ليتابع الجري من نفس الموضع - دون حاجة للبدء من خط البداية مجدداً لحفظ سياق وتفاصيل الجلسة. وغياب الاستعادة يتطلب إعادة تمرير تفاصيل الفحص الأول للمساعد مما يستهلك الرموز ويزيد أوقات المعالجة.
لكتابة عمليات متتالية في السكربت:
# الخطوة الأولى: فحص التعديلات والبحث عن المشاكل الأمنية
codex exec "审查这处改动有没有竞态条件"
# الخطوة الثانية: استعادة الجلسة والطلب منه كتابة الإصلاحات بناءً على الفحص
codex exec resume --last "把你发现의 竞态条件修掉"تحدد علامة --last استعادة آخر جلسة تفكير نشطة في مجلد العمل الحالي. ولتحديد جلسة معينة بدقة، اكتب معرف الجلسة الخاص بها (Session ID) كالتالي:
codex exec resume <SESSION_ID> "继续上次的任务"ونشير لتفصيلين هامين: يدعم أمر resume خيار --all للبحث عن الجلسات في بقية المجلدات؛ وكتابة نص الطلب بعد أمر resume تعتبر اختيارية لمتابعة الجلسة أو إرسال توجيهات جديدة. وتذكر أن الجلسات التي تفعل فيها خيار عدم حفظ السجلات --ephemeral لا يمكن استعادتها لعدم تسجيل تفاصيلها على القرص.
💡 ملخص في جملة واحدة: يتيح أمر
codex exec resume --lastاستعادة ومتابعة آخر جلسة عمل نشطة في المجلد لاستكمال المهام المتتالية وحفظ الرموز؛ ويحظر استخدام الاستعادة للجلسات التي تفعل فيها خيار--ephemeral.
08 تدريب عملي: كتابة سكربت لتسيير فحص وتلخيص مخرجاته
نطبق معاً تدريباً عملياً متكاملاً: تهيئة مستودع Git ← تشغيل أمر codex exec لحفظ المخرجات وتأكيد فصل القنوات ← قراءة مخرجات JSON ← واستخدام السكربت لتسيير فحص دوري للملفات.
يشترط تثبيت CLI وتوفير مستودع Git (يمكنك تهيئة مجلد فارغ بكتابة
git initوتثبيت ملف عشوائي فيه).
الخطوة الأولى: تشغيل فحص القراءة الأساسي (دون تعديل للملفات)
codex exec "用一句话说清这个项目是干什么的"المتوقع: ظهور خطوات وسجلات المعالجة (عبر stderr) تليها النتيجة النهائية (عبر stdout) ثم إغلاق الجلسة والعودة للطرفية العادية. مما يثبت نجاح الوضع غير التفاعلي.
الخطوة الثانية: حفظ النتيجة والتحقق من فصل القنوات
codex exec "用一句话说清这个项目是干什么的" > result.txtالمتوقع: ظهور سجلات المعالجة في الطرفية، وبفتح ملف result.txt ستجد النتيجة النصية النهائية فقط ودون أي سجلات فنية للبرنامج. مما يثبت أن علامة الحفظ > استقبلت مخرجات stdout فقط وقامت بتصفية stderr.
الخطوة الثالثة: تشغيل الخيار البرمجي لجلب أحداث JSON
codex exec --json "列出这个项目里的文件类型"المتوقع: تحول مخرجات الطرفية لسطور برمجية متتالية بصيغة JSON تبدأ بـ {"type":"thread.started",...} وتوضح تفاصيل العمل وحجم الرموز المستهلكة.
الخطوة الرابعة: حفظ الرسالة وتمرير المخرجات معاً
codex exec "用一句话总结这个项目" -o last.mdالمتوقع: طباعة النتيجة في الطرفية وكتابتها في نفس الوقت في ملف last.md للتأكد من عمل خيار -o دون حجب القنوات القياسية.
الخطوة الخامسة: كتابة سكربت حلقة تكرارية للفحص الدوري
سنقوم بكتابة سكربت يقوم بالدوران على ملفات markdown وتمرير كل منها للمساعد لإعداد ملخص فني وحفظ النتائج (نستخدم خيار --ignore-user-config لضمان نظافة وثبات الفحص):
for f in *.md; do
echo "=== $f ==="
codex exec --ignore-user-config "用一句话说明 $f 写的是什么"
doneالمتوقع: يقوم السكربت بالدوران وتمرير كل ملف على حدة لـ codex exec وطباعة الملخص الناتج في الطرفية. وهي النواة الأساسية لكتابة سكربتات فحص وتعديل الملفات الكبيرة في الخلفية.
بإتمام هذه الخطوات الخمس، تكون قد تحققت عملياً من دورة عمل الوضع غير التفاعلي: التشغيل الأساسي ← التحقق من القنوات ← جلب JSON ← حفظ الملفات ← وكتابة السكربت التكراري.
💡 ملخص في جملة واحدة: خطوات التدريب العملي هي: تشغيل codex exec ← حفظ المخرجات بالرمز > للتحقق من الفصل ← جلب أحداث JSON ← استخدام خيار -o لحفظ الملف ← وكتابة سكربت الحلقة التكرارية لملفات markdown؛ لإتقان تشغيل المساعد كعنصر برمجى.
09 ملخص
شرحنا في هذا المقال الوضع غير التفاعلي لأمر codex exec - وكيفية عزل قنوات المخرجات، وإعداد صلاحيات بيئة المعزل، وجلب أحداث JSON، وتمرير مدخلات stdin، واستعادة الجلسات.
دعنا نلخص النقاط الأساسية معاً بشكل سريع:
| الجانب | المفهوم الأساسي | نقاط هامة |
|---|---|---|
| وظيفة الأمر | تشغيل Codex في غياب الإشراف البشري | للأتمتة والسكربتات وخطوات CI، وينفذ المهمة ويغلق الجلسة فوراً دون طلب موافقات |
| فصل القنوات | عزل السجلات الفنية عن النتائج | السجلات والخطوات توجه لـ stderr؛ والنتائج النهائية توجه لـ stdout لتسهيل الحفظ |
| صلاحيات المعزل | تعمل بالقراءة فقط افتراضياً لحمايتك | يشترط تفعيل خيار --sandbox workspace-write صراحة عند الرغبة في تمكينه من تعديل الكود |
| أحداث JSON | خيار جلب البيانات برمجياً | يحول خيار --json المخرجات لـ سطور JSON متتالية (JSONL) لتتبع تقدم الأدوات والرموز |
| حفظ الملفات | خيار الحفظ الفردي للرسالة | يتيح خيار -o حفظ الرسالة النهائية في ملف نصي دون حجب طباعتها في الطرفية |
| مدخلات stdin | تمرير البيانات للمساعد كمرجع | استخدام صيغة الطلب والأنبوب (prompt + stdin) للمراجع؛ وصيغة الشرطة (codex exec -) لقراءة الطلب من الأنبوب |
| استعادة الجلسة | ربط العمليات المتتالية | يتيح أمر codex exec resume --last استكمال المهام من موضع انتهاء الجلسة الأخيرة |
يجب أن تكون الآن قادراً على: توضيح دور أمر codex exec والمهام الأنسب لتشغيله؛ واستخدام قنوات المخرجات لحفظ النتائج وتصفية السجلات الفنية؛ وضبط صلاحيات بيئة المعزل لتعديل أو قراءة الملفات؛ وجلب أحداث JSON وحفظ النتائج في ملفات نصية؛ وتمرير البيانات المرجعية أو الطلبات عبر الأنابيب القياسية؛ واستعادة الجلسات السابقة؛ وكتابة سكربتات أتمتة بسيطة. هذه القدرة على توظيف خيارات أمر codex exec تتيح لك دمج الذكاء الاصطناعي كعنصر برمجى مرن يسهل التحكم بمدخلاته ومخرجاته لتطوير حلول عملك الخاصة.
وتذكر دائماً التنبيهات الفنية - واحفظ قواعد "قراءة النتائج من stdout والسجلات من stderr، وتمكين sandbox: workspace-write للتعديل، واستخدام علامة الشرطة لقراءة الطلب من stdin، وتأكيد ثقة الخطافات يدوياً" لتأمين وتسريع العمل.
المقال التالي [29 · التكامل مع Slack و Linear والـ SDK] - ساعدنا أمر codex exec والسكربتات على تشغيل المساعد وتمرير بياناته برمجياً بنجاح. ولكن كيف نقوم بنقل هذه القدرات البرمجية لتتكامل مع أدوات التواصل اليومي لفريق العمل (مثل تلقي طلبات الفحص من Slack أو تحويل تذاكر الدعم لمهام برمجية في Linear)؟ سنتحدث في المقال القادم بالتفصيل عن تكامل الأدوات والـ SDK: وكيفية ربط Codex بمنصات التواصل ونظم تذاكر العمل والوصول لقدرات المساعد عبر حزم التطوير البرمجية (SDK) لإدراج الذكاء الاصطناعي في بيئة عمل الفريق بالكامل.