تفاصيل ملف التكوين config.toml: إدارة وضبط خيارات المساعد من ملف واحد
📚 التنقل في السلسلة: المقال السابق [17 · التحكم في الكمبيوتر واستخدام المتصفح (Computer Use)] جعل لـ Codex يداً - تمكنه من رؤية الشاشة، والنقر على سطح المكتب، وفتح المتصفح. هذا المقال يعود بنا من الواجهة الرسومية إلى ملف نصي بسيط ولكنه بالغ الأهمية -
config.toml. ربما صادفت هذا الملف في المقالات السابقة (عند الحديث عن الصلاحيات، تفعيل الذاكرة، أو ضبط النماذج)، وسنشرحه هنا بالتفصيل: أين يقع الملف، كيف يبدو هيكله، ما هي وظيفة كل حقل ومفتاح تحكم، وكيف يتم حسم التعارض بين الملفات المتعددة. المقال التالي [19 · نظام الذاكرة (Memories و Chronicle)] سيتناول نظام الذاكرة لتمكين المساعد من التعرف على سياق عملك عبر الجلسات.
يقول الكثيرون أن ملفات الإعداد والتكوين هي من الأمور التي "تكتب مرة واحدة عند التثبيت وتترك دون لمس طالما أن البرنامج يعمل" - ولكن لنكن صادقين، فهذه القاعدة مع Codex تؤدي لنتائج عكسية تماماً.
عند بدء استخدامي لـ Codex في مارس 2026، لم أقم بلمس ملف config.toml نهائياً، وكنت أضطر عند كل تشغيل لكتابة أمر /model لتغيير النموذج، وكتابة /permissions لتعديل صلاحيات المعزل، وإدخال --search يدوياً لتمكين البحث على الويب، مما يترتب عليه تكرار نفس الخطوات سبع أو ثماني مرات يومياً. وخلال أسبوع واحد، اكتشفت أنني قمت بكتابة توليفة "التبديل للنموذج الأقوى مع فتح صلاحيات الكتابة" يدوياً أكثر من ثلاثين مرة. وحينها أدركت خطئي: لقد قمت بتحويل مهمة يمكن كتابتها مرة واحدة لتعمل تلقائياً، إلى مهمة روتينية مكررة أهدرت الكثير من الوقت.
وجاء الحل ببساطة في فتح وتحديث ملف config.toml. حيث كتبت فيه إعدادات الصلاحيات والنموذج المعتمد، ليعمل Codex بأسلوبي المفضل تلقائياً وبمجرد تشغيله، مما وفر جهود كتابة الأوامر يدوياً.
بقراءة هذا المقال، ستحصل على:
- التمييز الواضح بين ملف
config.tomlوملفAGENTS.md(أوCLAUDE.md) - وفهم تخصص كل منهما - مكان حفظ ملف التكوين على جهازك الشخصي، والفرق الجوهري بين إعدادات المستخدم العامة (User-level) وإعدادات المشروع الخاصة (Project-level)
- فهم الستة مستويات الفنية للأولويات لحسم تعارض الإعدادات، ومعرفة حدود الصلاحيات المفروضة على خيارات المشروع الحساسة (مثل حظر تعديل حقل مزود الخدمة من مجلد المشروع)
- الدليل الشامل لأهم ثمانية مفاتيح تحكم في ملف التكوين (مثل
modelوsandbox_modeوapproval_policyوweb_searchوغيرها) مع قيمها الافتراضية - كيفية إجراء تعديل مؤقت للإعدادات لجلسة تشغيل واحدة باستخدام خيار
-c، أو التبديل بين مجموعات إعدادات كاملة باستخدام خيار--profile
01 الفارق الجوهري بين config.toml و AGENTS.md
قبل الخوض في تفاصيل السطور، يجب فهم تخصص كل ملف لتلافي الخلط بين الاستخدامات:
- ملف
config.toml: يختص بتعريف كيفية عمل المساعد فاوضح فيه: ما هو النموذج الافتراضي؟ ما هي حدود بيئة المعزل والصلاحيات؟ هل يسمح بالبحث على الويب؟ ويخدم هذا الملف البنية التحتية والخيارات التشغيلية للبرنامج. - ملف
AGENTS.md(أوCLAUDE.md): يختص بتعريف ما الذي يجب على المساعد تذكره وتنفيذه فندون فيه: قواعد صياغة الكود المفضلة، أسلوب تسمية المتغيرات، مسارات المجلدات الحساسة، وقواعد التنسيق. ويخدم هذا الملف سياق المشروع وهويته البرمجية الخاصة.
تشبيه: إعدادات تشغيل الآلة الكاتبة مقابل دليل كتابة المحتوى. يمثل ملف config.toml ضبط خيارات الآلة - كحجم الورق، نوع الخط، لون الحبر، وحدود الأمان لحركة الحروف (تحديد الإعدادات الفنية للعمل). ويمثل ملف AGENTS.md الدليل الإرشادي للكتابة - ككتابة العناوين بنمط معين، تجنب استخدام كلمات عامية، والالتزام بأسلوب صياغة محدد (توجيه المحتوى والنتائج). الأول يضبط حركة وكفاءة الآلة، والثاني يوجه جودة المخرجات البرمجية - وتجنب خلط الخيارات بينهما.
💡 ملخص في جملة واحدة: يختص ملف
config.tomlبـ خيارات التشغيل الفنية وعلاقة Codex بالنظام (النموذج والصلاحيات والمعزل)، بينما يختص ملفAGENTS.mdبـ إرشادات صياغة الكود وسياق المشروع (القواعد والذاكرة والتنسيق).
02 مواقع ملف التكوين: مستويان للحفظ
تعتمد قراءة Codex للإعدادات على مستويين من الملفات يتم حفظهما في مسارات محددة كالتالي:
المستوى الأول: إعدادات المستخدم العامة (User-level config)
يتم حفظ الملف في مجلد المستخدم الرئيسي للنظام ويطبق على جميع عمليات تشغيل Codex للمستخدم وعلى كافة المشاريع المفتوحة.
مسارات الحفظ الافتراضية بحسب نظام التشغيل:
- لأنظمة macOS و Linux:
~/.codex/config.toml - لأنظمة Windows (في مجلد المستخدم):
C:\Users\<اسم_المستخدم>\.codex\config.toml
ويخدم هذا الملف إعداداتك المفضلة الدائمة - كتعريف حساب OpenAI، تحديد النموذج المعتمد الأقوى، وتنشيط الميزات التجريبية العامة.
المستوى الثاني: إعدادات المشروع الخاصة (Project-level config)
يتم حفظ الملف في المجلد الرئيسي (الجذر) لمستودع Git الخاص بالمشروع في المسار:
<مجلد_مشروعك>/.codex/config.tomlويخدم هذا الملف إعدادات المشروع البرمجية الخاصة المشتركة مع فريق التطوير - كتحديد خوادم MCP المستخدمة للمشروع، أو إلزام المساعد باستخدام نموذج متوافق مع معايير الشركة البرمجية.
وننبه لقاعدة أمان صارمة ومهمة تتعلق بتحميل ملفات المشروع:
يقوم Codex بتجاهل تحميل ملف تكوين المشروع
.codex/config.tomlتلقائياً ما لم يكن المجلد مهيأ كمستودع Git موثوق ومحمي، لمنع الأكواد الخبيثة الخارجية من تعديل إعدادات أمان جهازك.
03 تسلسل الأولويات وحسم تعارض الخيارات
عند كتابة نفس الخيار في عدة ملفات، يعتمد Codex على تسلسل أولويات محدد بستة مستويات لحسم التعارض والوصول للقيمة الفعلية:
graph TD
A["1. خيارات سطر الأوامر المؤقتة (Command Line Flag)"] --> B["2. خيار التعديل المؤقت للجلسة (-c / --config)"]
B --> C["3. ملف تكوين المشروع المعتمد (Project config.toml)"]
C --> D["4. ملف بروفايل الإعدادات المختار (--profile)"]
D --> E["5. ملف تكوين المستخدم العام (User config.toml)"]
E --> F["6. الإعدادات الافتراضية المدمجة للبرنامج (Built-in Default)"]ونوضح القاعدة الذهبية للتسلسل: القيمة الأكثر تحديداً ومحلية تتغلب على القيمة العامة.
ولحماية أمن جهازك، تفرض المنصة حظر الحدود الأمنية للمشروع؛ حيث يمنع المساعد تحميل خيارات التعديل الحساسة من ملف المشروع الخاص وتقتصر قراءتها على ملف المستخدم العام فقط. وتضم القائمة الحساسة:
model_provider(تعديل حساب ومزود نموذج الذكاء الاصطناعي).notify(إعدادات التنبيهات الخارجية).otel(إعدادات تتبع ونقل السجلات الفنية للشبكة).profile(إعداد بروفايل الحساب البرمجي).
فلو حاول مشروع خارجي قمت بسحبه تعديل حقل model_provider ليوجه استدعاءاتك لخوادم مشبوهة، فسيتم إهمال التعديل تلقائياً والالتزام بالخيار المسجل في ملف المستخدم العام لجهازك.
04 الدليل التفصيلي لأهم خيارات التكوين
نعرض هنا نموذجاً لملف تكوين متكامل يضم أهم الخيارات المعتمدة وقيمها الافتراضية لتسهيل كتابته:
# نموذج ملف config.toml متكامل
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cache-only"
[features]
memories = true
chronicle = true
[mcp_servers.sqlite]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sqlite", "--db", "./dev.db"]ونشرح الخيارات بالتفصيل وفقاً للوثائق الرسمية:
1. خيار تحديد النموذج model
- الوظيفة: تحديد اسم النموذج الافتراضي المستخدم للمحادثات والمهام.
- الخيارات الشائعة: أسماء النماذج المعتمدة في حسابك.
- ملاحظة: عند إغفاله، يعتمد المساعد النموذج التلقائي المعتمد من النظام.
2. خيار سياسة الموافقات approval_policy
- الوظيفة: تحديد متى يتوقف المساعد لطلب إذن المطور قبل تشغيل الأدوات.
- الخيارات المتاحة:
untrusted: التوقف لطلب الموافقة لكل عملية تشغيل أداة برمجية.on-request(الافتراضي): التوقف للموافقة عند محاولة تعديل ملفات خارج مجلد المشروع أو تفعيل أدوات ذات خطورة.never: التشغيل التلقائي الكامل دون طلب موافقة (يقتصر استخدامه على البيئات المعزولة).
3. خيار بيئة المعزل sandbox_mode
- الوظيفة: تحديد حدود صلاحيات الوصول وتعديل الملفات للنظام.
- الخيارات المتاحة:
read-only: قراءة الأكواد والتحليل فقط دون إمكانية التعديل.workspace-write(الافتراضي في Git): السماح بتعديل الملفات داخل مجلد المشروع الحالي.danger-full-access: صلاحيات كاملة ودون قيود على النظام (يحذر استخدامه على開發机).
4. خيار البحث على الويب web_search
- الوظيفة: ضبط صلاحيات استخدام محركات البحث لجلب البيانات.
- الخيارات المتاحة:
cache-only(الافتراضي): البحث في البيانات المخزنة محلياً وتجنب الاتصال المباشر.enabled: السماح بالبحث المباشر على الويب لجلب البيانات الحديثة.disabled: حظر البحث تماماً لمنع مشاركة الكلمات الدلالية خارج جهازك.
5. قسم الميزات التجريبية [features]
- الوظيفة: تنشيط وإلغاء الميزات الحديثة المضافة للبرنامج.
- أهم المفاتيح:
memories = true: تنشيط الذاكرة طويلة المدى لحفظ تفضيلات المطور.chronicle = true: تنشيط سجل التعديلات التفصيلي لتبسيط معالجة الأكواد.
05 التعديل المؤقت والتبديل باستخدام البروفايلات
توفر المنصة طريقتين لتعديل الإعدادات وتخصيصها دون الحاجة لتحديث الملفات باستمرار:
أولاً: خيار التعديل المؤقت للجلسة الحالية (-c / --config)
عند الرغبة في تشغيل مهمة واحدة بإعدادات مختلفة (مثل تشغيل نموذج قوي للبحث لمرة واحدة)، استخدم خيار -c متبوعاً بالقيمة المطلوبة:
codex -c model=gpt-5.5 -c web_search=enabledلتسري الإعدادات على الجلسة الحالية فقط وتزول بمجرد الإغلاق دون تعديل ملفاتك الأصلية.
ثانياً: خيار التبديل بين مجموعات إعدادات كاملة (--profile)
عند الانتقال بين مشاريع متعددة تتطلب خيارات أمان متباينة (مثل مشاريع الشركة الحساسة ومشاريع المصادر المفتوحة)، يمكنك كتابة مجموعات إعدادات مستقلة (Profiles) في ملف المستخدم العام كالتالي:
# إعدادات المستخدم العام ~/.codex/config.toml
# البروفايل الافتراضي العام
model = "gpt-5-mini"
sandbox_mode = "workspace-write"
# بروفايل المشاريع المفتوحة المعزولة
[profiles.open-source]
model = "gpt-5.5"
sandbox_mode = "danger-full-access"
approval_policy = "never"
# بروفايل مشاريع الشركة الحساسة
[profiles.work-strict]
model = "gpt-5-mini"
sandbox_mode = "read-only"
approval_policy = "untrusted"ويمكنك التبديل لتطبيق بروفايل معين بكتابة المعامل --profile عند تشغيل المساعد:
codex --profile work-strictليقوم Codex بتهيئة الجلسة بالكامل بناءً على خيارات الأمان المحددة لهذا البروفايل لتلافي مخاطر العبث بالملفات بالخطأ.
06 تدريب عملي: كتابة واختبار خيار التعديل المؤقت
نطبق معاً تدريباً عملياً متكاملاً للتحقق من أولويات قراءة الإعدادات باستخدام أمر التعديل المؤقت وتفادي تعديل الملفات الأصلية.
الخطوة الأولى: التحقق من النموذج الافتراضي الحالي
افتح الطرفية واكتب الأمر البرمجي التالي لقراءة معلومات التشغيل الحالية:
codex --statusالمتوقع: ظهور تفاصيل إصدار البرنامج والنموذج الافتراضي المعتمد حالياً لجلساتك (مثلاً gpt-5-mini بناءً على إعدادات جهازك).
الخطوة الثانية: تشغيل المساعد بالنموذج المختار مؤقتاً
سنقوم بتشغيل Codex وكتابة طلب تلخيص مع إجباره على استخدام نموذج قوي محدد مؤقتاً عبر خيار -c:
codex -c model=gpt-5.5 "用一句话说明当前系统时间"المتوقع: بدء تشغيل المساعد واستدعاء النموذج المختار gpt-5.5 مباشرة لمعالجة الطلب وعرض الإجابة ثم الإغلاق دون إظهار تنبيهات تعارض.
الخطوة الثالثة: التحقق من ثبات النموذج الافتراضي
لمعرفة هل أثر التعديل المؤقت على خيارات جهازك الأصلية، أعد كتابة أمر التحقق:
codex --statusالمتوقع: عودة النموذج الافتراضي لقيمته الأصلية السابقة (مثلاً gpt-5-mini). مما يثبت نجاح الفحص الذاتي وتأكيد أن خيار -c يقتصر تأثيره على جلسة العمل الحالية فقط.
وبذلك تكتسب المرونة الكافية لتسيير المهام المختلفة بأمان وسرعة.
💡 ملخص في جملة واحدة: خطوات التدريب هي: فحص حالة المساعد الأساسية ← تشغيل مهمة بنموذج مخصص عبر خيار
-c← وإعادة فحص الحالة للتأكد من ثبات الخيارات الأصلية وعدم تأثرها بالتعديل المؤقت.
07 ملخص
شرحنا في هذا المقال خيارات ملف التكوين config.toml - وكيفية التمييز بينه وبين ملفات الإرشادات، وتحديد أولويات القراءة، وحفظ الملفات في المستويين، والتبديل بين مجموعات الإعدادات.
دعنا نلخص النقاط الأساسية معاً بشكل سريع:
| الجانب | المفهوم الأساسي | نقاط هامة |
|---|---|---|
| ملف التكوين | ضبط كيفية عمل المساعد فنية | يحدد النموذج والصلاحيات والمعزل، ويحفظ بصيغة TOML |
| مستويات الحفظ | مستويان: للمستخدم عام، وللمشروع خاص | مستندات المستخدم تحفظ في مجلد الهوم، ومستندات المشروع تحفظ في مجلد Git |
| الأولويات | سطر الأوامر يتغلب على الملفات | الترتيب: سطر الأوامر ← خيار -c ← ملف المشروع ← البروفايل ← ملف المستخدم |
| حدود المشروع | منع تعديل الخيارات الحساسة للمشروع | يتجاهل المساعد حقول مثل model_provider من ملف المشروع لحمايتك |
| خيارات التشغيل | أهم ثمانية مفاتيح تشغيل للبرنامج | خيارات model و sandbox_mode و approval_policy و web_search والذاكرة |
| التبديل المؤقت | خيار -c وبروفايلات --profile | يتيح خيار -c التعديل للجلسة الحالية، ويسمح --profile بالتبديل بين مجموعات كاملة |
يجب أن تكون الآن قادراً على: التمييز بين تخصص ملف التكوين وملف القواعد؛ وحفظ وكتابة الخيارات في مستوياتها الصحيحة؛ وحسم تعارض الخيارات ومعرفة تسلسل الأولويات؛ وضبط إعدادات الأمان والمعزل والموافقات والذاكرة؛ والتبديل المرن بين البروفايلات لتأمين سير العمل. هذا الضبط لملف التكوين يتيح لك تهيئة المساعد ليلائم أسلوب عملك وتفضيلاتك تلقائياً وبمجرد تشغيل جهازك.
وتذكر دائماً التوجيهات الفنية - واحفظ قواعد "حفظ خيارات الأمان الحساسة في ملف المستخدم العام، وكتابة الصلاحيات الأضيق التي تفي بالعمل، واستخدام التعديل المؤقت للمهمات المنفردة، والتحقق الدوري من حالة المساعد" لتأمين وتسريع العمل.
المقال التالي [19 · نظام الذاكرة (Memories و Chronicle)] - ساعدنا ملف التكوين وخياراته على ضبط أسلوب عمل Codex فنية. وننتقل في المقال القادم لميزة هامة قمنا بتنشيطها في قسم الميزات التجريبية وهي ميزة الذاكرة: وكيفية تمكين المساعد من التعرف على سياق عملك، تذكر التوجيهات السابقة، وبناء سجل المعرفة (Chronicle) ليعمل كشريك برمجى يفهم تفاصيل مشروعك وجلسات عملك عبر الفترات الزمنية المختلفة لتسهيل وتسريع التطوير.