आपका Codex Config काम क्यों नहीं कर रहा: .codex/ Folder की समस्या

मेरा Codex config apply नहीं हो रहा था। मैंने config.toml edit किया, AGENTS.md में rules add किए, docs दो बार पढ़े। कुछ नहीं बदला। Agent सब कुछ ignore करता रहा।

आखिरकार मैंने पूरे folder structure को खोलकर देखा। Problem यह नहीं थी कि मैंने files में क्या लिखा। Problem यह थी कि files किस जगह रखी थीं।

एक ही repo में दो काम

Codex एक साथ दो चीजें solve करने की कोशिश कर रहा है। एक है अपने beta features के साथ rapid experimentation। दूसरा है cross-agent compatibility, यानी एक shared standard जिसे Claude Code या OpenCode जैसे tools भी read कर सकें।

इस division से दो folders बनते हैं।

.codex/ Codex का अपना config space है। Sandbox policies, approval rules, और runtime guardrails यहां जाते हैं। .agents/ shared format है। Skills, plugins, और marketplace registry इस तरफ रहती है, जिसे कोई भी agent पढ़ सकता है जो इस standard को follow करता है।

मुझे शुरू में इस split के बारे में पता नहीं था। मैंने एक SKILL.md file .codex/ में डाल दी और skill कभी load नहीं हुई। उसे .agents/skills/ में move करते ही तुरंत काम करने लगी। यह boundary strict है: अगर कोई दूसरा agent उसे read करे, तो वो .agents/ में होनी चाहिए। बाकी सब .codex/ में।

दोनों folders को workspace-write mode में .git/ की तरह read-only protection मिलती है।

Project config और user config का एक ही नाम

आपके project root में एक .codex/ होता है और आपकी home directory में एक ~/.codex/। दोनों बिल्कुल अलग काम करते हैं।

Project .codex/ में वो settings होती हैं जो आप team के साथ share करते हैं: sandbox policies, approval workflows, agent definitions। ~/.codex/ में personal state होती है: auth tokens, command history, worktree management files।

मैंने ~/.codex/agents/ में एक reviewer agent बनाया और समझ नहीं पाया कि teammates को वो क्यों नहीं मिल रहा। वो सिर्फ मेरी machine पर था। उस file को project के .codex/agents/reviewer.toml में move करने पर वो repo के साथ clone में जाने लगा।

यह confusion और बढ़ जाती है क्योंकि Codex अभी भी beta में है। Desktop app worktree files, session data, और auth credentials सब ~/.codex/ में बिना किसी clear separation के इकट्ठा हो जाते हैं। “मेरी चीज़” और “project की चीज़” के बीच की line उतनी साफ नहीं है जितनी होनी चाहिए।

Config priority एक specific order follow करती है: managed config सबसे पहले आता है, फिर session overrides, फिर user config। जब कुछ apply नहीं हो रहा हो, तो check करें कि आप किस level को edit कर रहे हैं।

Trust level असली रुकावट है

यहीं पर ज़्यादातर लोग फंस जाते हैं, और मैंने भी काफी वक्त बर्बाद किया इसे समझने से पहले।

Codex किसी untrusted repo से project .codex/ को load नहीं करता। बिल्कुल नहीं। आप किसी freshly cloned repo में config.toml को जितना चाहें edit करें, कुछ apply नहीं होगा। File वहां है, syntax सही है, और Codex चुपचाप सब कुछ ignore करता रहता है।

इसकी वजह समझ में आती है जब आप देखते हैं। .agents/ एक रास्ता खोलता है जिससे external skills आपके environment में आ सकती हैं। कोई भी repo एक malicious config ship कर सकता है। इसलिए Codex ने यह trade-off किया: agent ecosystem के साथ wider compatibility, लेकिन repo-provided settings के लिए stricter trust verification। Config activate होने से पहले project को explicitly trusted mark करना पड़ता है।

अपने user config में projects.<path>.trust_level = "trusted" set करें। Network access भी default रूप से blocked रहती है, web search के तीन modes हैं: cached, live, या disabled। Workspace-write mode में भी .git/ और .codex/ write-protected रहते हैं।

मैंने करीब एक घंटा एक project config.toml edit करने में बिताया जिसे completely ignore किया जा रहा था, क्योंकि मैंने trust level set नहीं किया था। कोई error message नहीं, कोई warning नहीं। बस चुप्पी। यह शायद Codex setup की सबसे common frustration है, और यहां बेहतर error messaging बहुत सारे लोगों का बहुत सारा समय बचा सकती थी।

यह complexity अचानक नहीं आई

Folder structure उलझा हुआ है, लेकिन बेवजह नहीं। Codex दो ऐसे goals के पीछे है जो एक-दूसरे के विपरीत खिंचते हैं।

Fast beta iteration का मतलब है कि .codex/ में config files, rule definitions, hooks, और app management artifacts उस रफ्तार से जमा होते हैं जो documentation से आगे निकल जाती है। Cross-agent compatibility का मतलब है कि .agents/ को skills और marketplace content के लिए एक अलग, portable structure चाहिए। और क्योंकि .agents/ external code का दरवाज़ा खोलता है, इसलिए trust verification layer का होना ज़रूरी था।

जब आप सोच रहे हों कि file कहां जाए, तो एक सवाल पूछें: क्या यह Codex-specific है, या दूसरे agents को भी इसे read करना चाहिए? पहला जवाब .codex/ की तरफ इशारा करता है। दूसरा .agents/ की तरफ।

जब आपका config काम नहीं कर रहा हो, तो file contents edit करने से शुरू मत करें। Check करें कि वो किस folder में है और repo trusted है या नहीं। Problem लगभग हमेशा वहीं होती है।