لماذا لا تعمل إعدادات Codex لديك: مشكلة مجلد .codex/

إعدادات Codex لم تكن تُطبَّق. عدّلت config.toml، وأضفت قواعد إلى AGENTS.md، وأعدت قراءة التوثيق مرتين. لم يتغير شيء. الوكيل كان يتجاهل كل شيء.

في نهاية المطاف، فككت هيكل المجلدات بالكامل. المشكلة لم تكن فيما كتبته داخل الملفات، بل في المكان الذي وُضعت فيه.

هدفان في مستودع واحد

يحاول Codex تحقيق هدفين في آنٍ واحد: التجريب السريع لميزاته التجريبية، والتوافق مع وكلاء آخرين من خلال معيار مشترك يمكن لأدوات مثل Claude Code أو OpenCode قراءته أيضاً.

هذا التقسيم ينتج عنه مجلدان مختلفان.

.codex/ هو فضاء الإعداد الخاص بـ Codex وحده، ويضم سياسات sandbox وقواعد الموافقة وضوابط وقت التشغيل. أما .agents/ فهو التنسيق المشترك، وتعيش فيه المهارات والإضافات وسجل marketplace، ويمكن لأي وكيل يتبع المعيار قراءته.

لم أكن أعرف بهذا الفصل في البداية. وضعت ملف SKILL.md داخل .codex/ فلم تُحمَّل المهارة قط. نقله إلى .agents/skills/ أصلح المشكلة فوراً. الحدود صارمة: إذا كان وكيل آخر يحتاج قراءة الملف، فمكانه في .agents/. كل ما عدا ذلك يذهب إلى .codex/.

كلا المجلدين يحظيان بحماية للقراءة فقط في وضع workspace-write، تماماً كمجلد .git/.

إعداد المشروع وإعداد المستخدم يحملان الاسم ذاته

ثمة مجلد .codex/ في جذر مشروعك، ومجلد ~/.codex/ في المجلد الرئيسي. وهما يؤديان وظيفتين مختلفتين تماماً.

.codex/ الخاص بالمشروع يحتوي على الإعدادات التي تشاركها مع فريقك: سياسات sandbox، وسير عمل الموافقة، وتعريفات الوكلاء. أما ~/.codex/ فيحتوي على الحالة الشخصية: رموز المصادقة، وسجل الأوامر، وملفات إدارة worktree.

أنشأت وكيل مراجعة في ~/.codex/agents/ وظللت أتساءل لماذا لا يملكه زملائي في الفريق. كان موجوداً على جهازي فقط. نقل الملف إلى .codex/agents/reviewer.toml في المشروع جعله يُرحَّل مع المستودع عند الاستنساخ.

يزداد الالتباس لأن Codex لا يزال في مرحلة تجريبية. ملفات worktree لتطبيق سطح المكتب، وبيانات الجلسات، وبيانات اعتماد المصادقة، كلها تتراكم في ~/.codex/ دون فصل واضح. الحدود بين “أشيائي” و”أشياء المشروع” تتشوش أكثر مما ينبغي.

أولوية الإعداد تتبع ترتيباً محدداً: الإعداد المُدار يتقدم على تجاوزات الجلسة، التي تتقدم بدورها على إعداد المستخدم. حين لا يُطبَّق شيء، تحقق من أي مستوى تُجري التعديل.

مستوى الثقة هو البوابة الحقيقية

هنا يتعثر معظم الناس، وقد أضعت وقتاً حقيقياً قبل أن أفهم السبب.

لا يُحمِّل Codex .codex/ الخاص بالمشروع من مستودعات غير موثوقة. على الإطلاق. يمكنك تعديل config.toml بقدر ما تشاء في مستودع مستنسخ حديثاً ولن يُطبَّق شيء. الملف موجود، الصياغة صحيحة، وCodex يتجاهل كل شيء بصمت.

السبب منطقي حين تراه. .agents/ يفتح مساراً لتدفق مهارات خارجية إلى بيئتك. أي مستودع يمكن أن يحمل إعداداً خبيثاً. لذا قرر Codex هذه المقايضة: توافق أوسع مع منظومة الوكلاء، مقابل تحقق أكثر صرامة من الثقة في الإعدادات المُقدَّمة من المستودع. يجب أن تُصنِّف المشروع صراحةً على أنه موثوق قبل أن يُفعَّل .codex/ الخاص به.

اضبط projects.<path>.trust_level = "trusted" في إعداد المستخدم لديك. الوصول إلى الشبكة محظور افتراضياً أيضاً، مع ثلاثة أوضاع للبحث على الويب: مخزّن مؤقتاً، أو مباشر، أو معطَّل. حتى في وضع workspace-write، يبقى كل من .git/ و.codex/ محميَّين من الكتابة.

قضيت قرابة ساعة في تعديل config.toml لمشروع كان يُتجاهَل بالكامل لأنني لم أضبط مستوى الثقة. لا رسالة خطأ، لا تحذير. صمت مطبق. هذا على الأرجح أكثر مشكلات إعداد Codex شيوعاً، ورسائل خطأ أوضح كانت ستوفر الكثير من الوقت على كثير من الناس.

التعقيد ليس عشوائياً

هيكل المجلدات فيه تشابك، لكنه ليس عشوائياً. Codex يسعى لتحقيق هدفين يشدّان في اتجاهين متعاكسين.

التكرار السريع في مرحلة التجريب يعني أن .codex/ يتراكم فيه ملفات الإعداد وتعريفات القواعد والخطافات وقطع إدارة التطبيق بوتيرة تفوق التوثيق. التوافق مع وكلاء آخرين يعني أن .agents/ يحتاج هيكلاً منفصلاً ومحمولاً للمهارات ومحتوى marketplace. ولأن .agents/ يفتح الباب أمام كود خارجي، كان لا بد من وجود طبقة التحقق من الثقة.

حين تتردد في مكان وضع ملف، اطرح سؤالاً واحداً: هل هذا خاص بـ Codex، أم ينبغي لوكلاء آخرين قراءته أيضاً؟ الإجابة الأولى تشير إلى .codex/. الثانية تشير إلى .agents/.

حين لا تعمل إعداداتك، لا تبدأ بتعديل محتوى الملف. تحقق من المجلد الذي يوجد فيه وما إذا كان المستودع موثوقاً. هناك تكمن المشكلة في أغلب الأحيان.