چطور غلط تایپی در پیکربندی کدکس را پیدا کنیم؟

پرچم --strict-config تنها راهی است که کدکس کلید اشتباه در config.toml را به شما نشان می‌دهد. بدون آن، approval_polic بی‌صدا نادیده گرفته می‌شود و کدکس با تنظیمات پیش‌فرض بالا می‌آید. در کدکس 0.162.1 چهار فرمان این پرچم را رد کردند و doctor آن را می‌پذیرد اما اعمال نمی‌کند، پس جای درستش در exec و review است، نه هر فرمانی.

چرا کلید اشتباه بی‌صدا از بین می‌رود

کدکس پرونده‌ی ~/.codex/config.toml را می‌خواند و فیلدهای ناشناخته را عمدا دور می‌ریزد. دلیلش سازگاری رو به عقب است: یک فایل پیکربندی که با کدکس 0.157 نوشته شده باید روی 0.162 هم کار کند، حتی اگر نسخه‌ی جدید کلیدی را حذف کرده باشد.

همین تصمیم یک هزینه دارد که در هر نسخه تکرار می‌شود. اگر approval_policy را با یک غلط تایپی بنویسید، هیچ پیامی نمی‌بینید. نه خطایی، نه هشداری. کدکس بارگذاری می‌شود و کار می‌کند، فقط با مقدار پیش‌فرض.

نتیجه‌ی عملی این است که شما فکر می‌کنید مجوز خودکار را خاموش کرده‌اید و کدکس به‌جای پرسیدن، فرمان را اجرا می‌کند. پرچم --strict-config دقیقا همین سوراخ را می‌بندد: هر فیلدی که این نسخه از کدکس نمی‌شناسد، به خطا تبدیل می‌شود.

یک غلط تایپی، خروجی واقعی

برای اینکه آزمون تمیز باشد، کل تنظیمات را در یک مسیر جدا می‌سازیم تا CODEX_HOME واقعی دست‌نخورده بماند. این کار را در یک ترمینال تازه انجام دهید و متغیر را برای همین پوسته نگه دارید.

$ export CODEX_HOME="$PWD/.codex-lab"   # مسیر موقت؛ تنظیمات واقعی دست‌نخورده
$ mkdir -p "$CODEX_HOME"
$ printf 'model = "gpt-5.1-codex"
approval_polic = "on-request"
' > "$CODEX_HOME/config.toml"
$ cat "$CODEX_HOME/config.toml"
model = "gpt-5.1-codex"
approval_polic = "on-request"

# بدون پرچم، کلید ناشناخته بی‌صدا رد می‌شود
$ codex --version
codex-cli 0.162.1

# با پرچم، همان فایل خطا می‌دهد و نام کلید را می‌گوید
$ codex --strict-config < /dev/null
Error loading config.toml:
$PWD/.codex-lab/config.toml:2:1: unknown configuration field `approval_polic`
  |
2 | approval_polic = "on-request"
  | ^^^^^^^^^^^^^^

خروجی دو چیز را با هم می‌گوید که در پیام معمولی کدکس وجود ندارد. ستون و خط یعنی 2:1، و خط تیره‌ی زیر کلید یعنی دقیقا کدام متن را باید اصلاح کنید.

نکته‌ی مهم این است که خطا پیش از هر کار شبکه‌ای می‌آید. یعنی برای پیدا کردن این غلط تایپی نیازی به ورود به حساب کدکس یا کلید API ندارید. آزمون بالا روی یک ماشین بدون ورود اجرا شده است.

سه دسته خطا که نباید با هم اشتباه شوند

پرچم --strict-config فقط یک نوع اشتباه را می‌گیرد: کلیدی که اصلا وجود ندارد. اشتباه روی کلیدی که وجود دارد اما مقدارش غلط است، بدون این پرچم هم خطا می‌دهد.

تفاوت را با یک trust_level اشتباه ببینید. مقدار درست دو حالت دارد و مقدار نوشته‌شده هیچ‌کدام نیست.

# کلید درست، مقدار غلط: پیام یکسان با و بدون پرچم
$ printf 'model = "gpt-5.1-codex"
[projects."/tmp/x"]
trust_level = "safe"
' > "$CODEX_HOME/config.toml"
$ codex exec --skip-git-repo-check hi
Error loading config.toml:
$PWD/.codex-lab/config.toml:3:15: unknown variant `safe`, expected `trusted` or `untrusted`
  |
3 | trust_level = "safe"
  |               ^^^^^^

# کلید ناشناخته در جدول features: بدون پرچم بی‌صدا رد می‌شود
$ printf 'model = "gpt-5.1-codex"
[features]
not_a_real_feature = true
' > "$CODEX_HOME/config.toml"
$ codex exec --skip-git-repo-check hi
Reading additional input from stdin...
OpenAI Codex v0.162.1
--------
model: gpt-5.1-codex
approval: on-request
sandbox: read-only

به خط approval: on-request در خروجی آخر نگاه کنید. این دقیقا همان چیزی است که آدم فکر می‌کند تنظیم کرده، اما مقدار پیش‌فرض است، نه چیزی که خودش نوشته. جدول features یک نقشه‌ی بولی تخت است که هر کلید دلخواهی را می‌پذیرد، پس در حالت عادی هیچ نشانه‌ای باقی نمی‌ماند.

کدام فرمان پرچم را می‌پذیرد

مستندات رسمی می‌گویند پرچم برای فرمان‌های زمان اجرا پشتیبانی می‌شود: codex، exec، review، resume، fork، app-server و exec-server.

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

$ codex --strict-config features list
Error: `--strict-config` is not supported for `codex features`
$ codex --strict-config debug models
Error: `--strict-config` is not supported for `codex debug`
$ codex --strict-config mcp list
Error: `--strict-config` is not supported for `codex mcp`

# doctor پرچم را می‌پذیرد اما اعمال نمی‌کند: دو اجرا، یک جمله
$ codex --strict-config doctor --summary --no-color | grep config
   ⚠ config       config loaded
$ codex doctor --summary --no-color | grep config
   ⚠ config       config loaded

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

این پرچم را کجا بگذاریم

بهترین جای این پرچم، خط لوله‌ی بازبینی است. آنجا هزینه‌ی اجرا بالاست و یک غلط تایپی بی‌صدا یعنی یک دور کامل بازبینی با تنظیمات اشتباه.

# دروازه‌ی پیکربندی: صفر درخواست به شبکه، فقط خواندن فایل
$ codex exec --strict-config --skip-git-repo-check true >/dev/null 2>&1
$ echo "exit=$?"
exit=0

# سپس بازبینی واقعی؛ کلید ناشناخته اینجا نام برده می‌شود
$ codex review --strict-config --uncommitted
Error loading config.toml:
~/.codex/config.toml:2:1: unknown configuration field `approval_policies`
  |
2 | approval_policies = "never"
  | ^^^^^^^^^^^^^^^^^

کد 0 یعنی پیکربندی سالم است و اجازه می‌دهد دور واقعی شروع شود. اگر غلط تایپی داشته باشد، کد 1 برمی‌گردد و همان پیام خطا را روی خروجی استاندارد می‌بینید. یک نکته‌ی عملی در همین آزمون‌ها دیده شد: با خطای پیکربندی، کدکس اصلا به سرور مدل وصل نمی‌شود، پس این دروازه بدون کلید API هم کار می‌کند.

جمع‌بندی

سه چیز را در این نسخه اندازه گرفتم و هر سه قابل بازتولید است. نخست اینکه کلید ناشناخته در config.toml بدون پرچم هیچ خطایی نمی‌دهد و با پرچم نام کلید را همراه با شماره‌ی خط می‌گوید. دوم اینکه خطای مقدار روی کلید موجود، بدون پرچم هم داده می‌شود، پس این پرچم اشتباه مقدار را نمی‌گیرد. سوم اینکه چهار فرمان پرچم را رد کردند و doctor آن را می‌پذیرد اما نادیده می‌گیرد.

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

منابع

1. مرجع فرمان‌های کدکس: تعریف پرچم --strict-config و فهرست فرمان‌های پشتیبان
2. مرجع خط فرمان کدکس: جدول پرچم‌ها و فرمان‌های پشتیبان
3. پیشنهاد افزودن حالت سخت‌گیرانه‌ی پیکربندی، شماره‌ی ۲۰۵۵۹
4. پیاده‌سازی اعتبارسنجی حالت سخت‌گیرانه در کدکس
5. آزمون‌های بارگذار پیکربندی کدکس برای کلید ناشناخته
6. مرجع کامل پیکربندی کدکس و فهرست کلیدهای معتبر
7. پایه‌های پیکربندی کدکس و ترتیب اولویت مقادیر
8. مستندات سندباکس و مجوز کدکس
9. مخزن رسمی کدکس در گیت‌هاب
10. پست پیشین: تشخیص خرابی کدکس با doctor
11. پست پیشین: کاتالوگ مدل‌های کدکس