چطور لایه‌ی پروفایل کدکس را راستی‌آزمایی کنیم؟

کدکس از نسخه‌ی 0.134.0 دیگر جدول [profiles.x] را نمی‌خواند و خطای legacy profile = "x" config is no longer supported می‌دهد. راه درست، لایه‌ی <name>.config.toml در کنار config.toml است که با codex -p name روی پیکربندی پایه سوار می‌شود. در این پست با codex debug prompt-input ثابت می‌کنیم لایه واقعا اعمال می‌شود، -c بر آن غلبه می‌کند، و نامی که فایلی پشت آن نیست بی‌صدا نادیده گرفته می‌شود.

پرچمی که راهنما نوشت و کدکس نمی‌پذیرد

در راهنمای رسمی پیکربندی نوشته شده که در کدکس 0.134.0 و پس از آن، --profile دیگر جدول [profiles.profile-name] را از config.toml نمی‌خواند و انتخابگر profile = "profile-name" در سطح فایل هم پشتیبانی نمی‌شود [1]. این یک هشدار نرم نیست؛ کدکس اجرا را متوقف می‌کند.

ما همین را روی نسخه‌ی نصب‌شده‌ی همین سرور آزمودیم. لحظه‌ی خواندن: ۱۳ اکتبر ۲۰۲۶، کدکس 0.162.1 که با codex --version گزارش می‌شود. با یک فایل پیکربندی که هم انتخابگر کهنه را دارد و هم جدول کهنه را، کدکس اصلا پیام مدل نمی‌سازد:

$ export CODEX_HOME="$PWD/.codex-lab"   # مسیر موقت؛ تنظیمات واقعی دست‌نخورده
$ mkdir -p "$CODEX_HOME"

# پیکربندی کهنه: هم انتخابگر، هم جدول تودرتو
$ cat > "$CODEX_HOME/config.toml" <<'TOML'
model = "gpt-6-astra"
sandbox_mode = "read-only"
profile = "work"

[profiles.work]
sandbox_mode = "danger-full-access"
TOML

$ codex debug prompt-input hi
Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead

نکته‌ی عملی این است که این خطا فقط وقتی رخ می‌دهد که انتخابگر کهنه در فایل باشد. اگر فقط جدول [profiles.work] را بگذارید و خط profile = ... را ننویسید، کدکس بی‌صدا از آن جدول رد می‌شود و پیکربندی پایه را عوض نمی‌کند؛ آن وقت فکر می‌کنید پروفایل‌تان فعال است، در حالی که نیست.

لایه‌ی درست کجاست و چه چیزی را واقعا عوض می‌کند

شکل تازه یک فایل جداگانه در کنار config.toml است، با نام <name>.config.toml، و انتخاب آن با --profile name یا همان -p name [1]. نام پروفایل می‌تواند حرف، رقم، خط تیره و زیرخط داشته باشد. هر چه داخل فایل بنویسید در سطح کلید اصلی نوشته می‌شود، نه داخل جدول تودرتو.

ترتیب لایه‌ها از همان راهنما روشن است: پرچم‌های خط فرمان و -c بالاترین لایه‌اند، بعد لایه‌ی پروفایل، و در پایین‌تر config.toml کاربر [1]. یعنی یک پروفایل فقط می‌تواند آنچه را عوض کند که از خط فرمان بازنویسی نشده باشد.

برای دیدن اثر واقعی، کلیدی را انتخاب کردیم که در خود متن پیام تزریق‌شده به مدل دیده می‌شود: sandbox_mode. کدکس این مقدار را در بلوک <permissions instructions> به مدل توضیح می‌دهد، پس با debug prompt-input قابل خواندن است.

$ cat > "$CODEX_HOME/config.toml" <<'TOML'
model = "gpt-6-astra"
sandbox_mode = "read-only"
TOML

# لایه‌ی پروفایل فقط همان یک کلید را عوض می‌کند
$ cat > "$CODEX_HOME/work.config.toml" <<'TOML'
sandbox_mode = "danger-full-access"
TOML

$ ls "$CODEX_HOME"
config.toml  work.config.toml

$ codex debug prompt-input hi | grep -o '`sandbox_mode` is `[a-z-]*`'
`sandbox_mode` is `read-only`

$ codex -p work debug prompt-input hi | grep -o '`sandbox_mode` is `[a-z-]*`'
`sandbox_mode` is `danger-full-access`

تفاوت این دو خط، تمام کاری است که یک لایه می‌کند: همان پروژه، همان مدل، تنها یک کلید که از فایل پروفایل آمده است. اگر خروجی شما خط اول را نشان می‌دهد، لایه اعمال نشده و باید سراغ نام فایل بروید.

وقتی -c و -p با هم قهر می‌کنند

چون -c در لایه‌ی بالاتری از پروفایل می‌نشیند، برنده است. این را هم روی همان نصب آزمودیم:

# -c در لایه‌ی بالاتر می‌نشیند و برنده است
$ codex -p work -c 'sandbox_mode="read-only"' debug prompt-input hi \
    | grep -o '`sandbox_mode` is `[a-z-]*`'
`sandbox_mode` is `read-only`

$ codex -c 'sandbox_mode="workspace-write"' debug prompt-input hi \
    | grep -o '`sandbox_mode` is `[a-z-]*`'
`sandbox_mode` is `workspace-write`

این برای اسکریپت‌های CI مهم است. اگر در خط لوله هم پروفایل بدهید و هم -c، آنچه رفتار می‌کند -c است و پروفایل بی‌اثر می‌ماند. برای همین در اسکریپت یا فقط یکی را انتخاب کنید یا مقدار نهایی را با -c صریح بنویسید تا معلوم باشد چه چیزی تعیین‌کننده است.

یک محدودیت دیگر هم هست که در راهنما پررنگ نشده: -p روی هر فرمانی کار نمی‌کند. خطای خود کدکس فهرست مجاز را می‌دهد:

# اما نه روی هر فرمانی: خطای خود کدکس فهرست مجاز را می‌دهد
$ codex -p work debug models
Error: --profile only applies to runtime commands and `codex mcp`: `codex`,
`codex exec`, `codex review`, `codex resume`, `codex queue`, `codex archive`,
`codex delete`, `codex unarchive`, `codex fork`, `codex mcp`, `codex sandbox`,
and `codex debug prompt-input`.

یعنی codex debug models با پروفایل اجرا نمی‌شود، ولی codex debug prompt-input اجرا می‌شود. برای همین همین فرمان دوم ابزار راستی‌آزمایی این پست است.

تله‌ی اصلی: نامی که فایلی پشتش نیست

اگر نام پروفایل را اشتباه تایپ کنید، کدکس خطا نمی‌دهد. پیکربندی پایه را عوض‌نشده اجرا می‌کند و شما فکر می‌کنید دارید با تنظیمات ویژه کار می‌کنید.

$ ls "$CODEX_HOME"/*.config.toml
$PWD/.codex-lab/work.config.toml

# نام اشتباه خطا نمی‌دهد؛ پیکربندی پایه عوض‌نشده اجرا می‌شود
$ codex -p ghost debug prompt-input hi | grep -o '`sandbox_mode` is `[a-z-]*`'
`sandbox_mode` is `read-only`

پسوند .config.toml بخشی از نام نیست. -p work دنبال فایلی به نام work.config.toml می‌گردد، نه profile-work.config.toml و نه work.toml. راهنمای ثالث هم قاعده‌ی نام‌گذاری و همین رفتار خاموش را توصیف می‌کند [9].

تله‌ی دوم درون خود فایل است: کلیدی که در نسخه‌ی شما وجود ندارد هم بی‌صدا رد می‌شود. اگر نام کلید را غلط بنویسید، پروفایل بارگذاری می‌شود ولی آن کلید اعمال نمی‌شود.

# کلیدی که در این نسخه وجود ندارد، بی‌صدا رد می‌شود
$ cat > "$CODEX_HOME/bad.config.toml" <<'TOML'
this_key_does_not_exist = 3
TOML

$ codex -p bad debug prompt-input hi > /dev/null ; echo "rc=$?"
rc=0

پروفایل‌هایی که واقعا به کار می‌آیند

یک پروفایل فقط نقطه‌ی شروع پیکربندی است. سه فایل کوچک که تقریبا همه‌ی تیم‌ها به آن نیاز دارند:

دو هشدار عملی. اول اینکه پروفایل در $CODEX_HOME زندگی می‌کند، نه در ریپو؛ کلون کردن پروژه پروفایل شما را فعال نمی‌کند و تیم باید آن را جداگانه نصب و بازبینی کند [9]. دوم اینکه approval_policy = "untrusted" دیگر پشتیبانی نمی‌شود و باید از پیکربندی حذف شود یا با سیاست پشتیبانی‌شده جایگزین شود [2].

برای دیدن فایل‌هایی که کدکس واقعا می‌خواند، پیکربندی پایه را از فایل‌های پروفایل جدا نگه دارید و کلید model و مجوزها را فقط یک‌جا تعریف کنید. راهنمای رسمی می‌گوید لایه‌ی پروفایل میان پیکربندی کاربر و پیکربندی پروژه می‌نشیند [1].

اگر می‌خواهید بدانید پیکربندی پروژه چه چیزی به پیام مدل اضافه می‌کند، روشی که در چطور ببینیم AGENTS.md کدکس چقدر توکن می‌برد اندازه گرفتیم هنوز همان ابزار است: debug prompt-input فایل‌های دستوری را با مسیر کامل نشان می‌دهد. و اگر می‌خواهید پرچم‌های روشن یا خاموش را ببینید، روش features list در چطور با codex features وضعیت واقعی پرچم‌ها را ببینیم هنوز درست است.

چک‌لیست پنج‌دقیقه‌ای

1. هر profile = "..." و هر جدول [profiles.x] را از config.toml حذف کنید؛ این‌ها در 0.134.0 به بعد خطا می‌دهند یا بی‌صدا رد می‌شوند [1].
2. برای هر حالت کاری یک فایل <name>.config.toml بسازید و فقط کلیدهای متفاوت با پایه را در آن بنویسید.
3. پیش از هر اجرا ls $CODEX_HOME/*.config.toml را بزنید؛ نام را با پسوند اشتباه نگذارید.
4. با codex -p name debug prompt-input لایه را راستی‌آزمایی کنید، نه با نگاه کردن به نام فایل.
5. در اسکریپت‌ها بین -p و -c یکی را انتخاب کنید، چون -c برنده است.

منابع

1. Advanced Configuration | Codex — لایه‌ی پروفایل، ترتیب لایه‌ها و کنار گذاشتن [profiles.x] از نسخه‌ی 0.134.0.
2. Configuration Reference | Codex — فهرست کلیدها و کنار گذاشتن approval_policy = "untrusted".
3. Config basics | Codex — جایگاه config.toml کاربر در سلسله‌مراتب پیکربندی.
4. Codex changelog — یادداشت‌های انتشار نسخه‌های کدکس.
5. مخزن openai/codex — پیاده‌سازی و متن خطاهایی که در این پست نقل شده.
6. انتشارهای openai/codex — نسخه‌ی 0.162.1 با تاریخ ۹ اکتبر ۲۰۲۶، همان نسخه‌ای که همه‌ی خروجی‌های این پست از آن گرفته شده.
7. AGENTS.md | Codex — دستورهای سطح پروژه که در خروجی debug prompt-input دیده می‌شوند.
8. Environment variables | Codex — متغیرهای محیطی، از جمله نقش CODEX_HOME.
9. Codex Handbook — Configuration profiles — راهنمای ثالث درباره‌ی نام‌گذاری فایل و رفتار خاموش نام اشتباه.
10. تصویر پوشش — عکس Intel Core Ultra، اثر Andrey Matveev، از Pexels.