codex doctor چیست و چطور خرابی کدکس را پیدا کنیم

کدکس از نسخه‌ی 0.131.0 یک فرمان تشخیصی به نام codex doctor دارد که ۲۱ بررسی محلی را در یک گزارش می‌ریزد. موضوع بررسی‌ها از نصب و مجوز تا ترمینال و پایگاه‌داده‌های حالت را در بر می‌گیرد. در این مقاله همین فرمان را روی کدکس 0.158.0 اجرا می‌کنیم، یک config.toml خراب می‌سازیم تا ببینیم گزارش چطور آن را شکار می‌کند، و یاد می‌گیریم خروجی JSON را با jq به یک گزارش کوتاه برای تیکت تبدیل کنیم.

doctor چه چیزی را بررسی می‌کند

این فرمان در نسخه‌ی 0.131.0 که ۱۸ مه ۲۰۲۶ منتشر شد اضافه شد؛ متن همان انتشار، آن را «تشخیص آماده برای پشتیبانی» توصیف می‌کند و شش حوزه را نام می‌برد: runtime، مجوز، ترمینال، شبکه، پیکربندی و حالت محلی. نسخه‌ی 0.135.0 بعداً بررسی‌های محیطی، گیت و ترمینال را به آن اضافه کرد. لحظه‌ی خواندن: ۲۹ سپتامبر ۲۰۲۶، روی کدکس 0.158.0 در اوبونتو 24.04.

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

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

$ codex doctor --summary --ascii --no-color
Codex Doctor v0.158.0 · linux-x86_64

Notes
   [up] updates      0.159.0 available (current 0.158.0)
   [XX] auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
   [!!] websocket    Responses WebSocket failed; HTTPS fallback may still work - Check proxy, VPN, firewall, DNS, custom CA, and WebSocket policy support.
-------------------------------------------------------------

Environment
  [ok] system       C
  [ok] disk         sufficient free disk space (23.4 GiB)
  [ok] security     endpoint protection is not inspected on this platform
  [ok] runtime      npm (package .../codex-linux-x64/vendor/x86_64-unknown-linux-musl)
  [ok] install      consistent
  [ok] search       file exists (bundled, `.../codex-path/rg`)
  [ok] git          git executable found; execution not verified
  [ok] terminal     unknown
  [ok] title        default | project hoosh-blog
  [ok] state        state paths and databases are inspectable
  [ok] threads      no rollout/state DB inventory to compare

Configuration
  [ok] config       loaded
  [XX] auth         no Codex credentials were found - Run codex login or provide an API key through a supported auth env var.
  [ok] mcp          no MCP servers configured
  [ok] sandbox      restricted fs + restricted network · approval OnRequest
  [ok] sandbox      no explicit filesystem paths to probe

Updates
  [ok] updates      update configuration is locally consistent

Connectivity
  [ok] network      no proxy env vars
  [!!] websocket    Responses WebSocket failed; HTTPS fallback may still work
  [ok] reachability active provider endpoints are reachable over HTTP

Background Server
  [--] app-server   not running (ephemeral mode)

-------------------------------------------------------------
18 ok | 1 idle | 1 warn | 1 fail failed

چهار بخش را از همین خروجی بخوانید. بخش Notes بالای گزارش، سه موردی را جلو می‌کشد که هرکدام می‌توانند توضیح یک رفتار عجیب باشند. بخش Environment می‌گوید binary از کجا آمده و آیا نصب با PATH هم‌خوان است. بخش Connectivity فرق میان WebSocket و مسیر جایگزین HTTP را جدا می‌کند، که همان چیزی است که در دیباگ شبکه معمولاً گم می‌شود. و سطر آخر شمارش نهایی است که در اسکریپت قابل استفاده است.

سطر auth در این اجرا قرمز است و این تنها خطای گزارش است. نه اعتبارنامه‌ای در ~/.codex/auth.json وجود دارد و نه متغیر محیطی پشتیبان تنظیم شده، چون روی این ماشین هرگز codex login اجرا نشده است. سه بررسی دیگر هم هشدار یا بی‌کاری‌اند و بقیه سالم‌اند.

خروجی JSON و سی فرایند

سوییچ --json همان داده‌ها را به‌صورت ماسک‌شده می‌دهد تا بتوانید بچسبانیدشان در تیکت. ریشه‌ی JSON پنج کلید دارد و هر بررسی با شناسه‌ای مثل auth.credentials کلید خودش است.

$ codex doctor --json > doctor.json
$ jq -r '.codexVersion, .overallStatus' doctor.json
0.158.0
fail

# هر بررسی‌ای که سالم نیست را جدا کن
$ jq -r '.checks | to_entries[]
    | select(.value.status != "ok")
    | "\(.value.status)\t\(.key)\t\(.value.summary)"' doctor.json
fail	auth.credentials	no Codex credentials were found
warning	network.websocket_reachability	Responses WebSocket failed; HTTPS fallback may still work

شمارش دقیق همان چیزی است که در مرجع خط فرمان کدکس به‌عنوان یک فرمان توسعه‌دهنده توصیف شده است. در این گزارش ۲۱ کلید زیر checks وجود دارد: ۱۹ تا با وضعیت ok، یک fail و یک warning. جمعشان ۲۱ است و با شمارش --summary جور در می‌آید، جز اینکه آن یکی idle را جدا حساب می‌کند.

هر بررسی یک remediation هم دارد که متن راه‌حل همان خطاست. برای خطای مجوز، همان جمله‌ای را می‌گوید که خود codex login را پیشنهاد می‌کند.

$ jq '.checks["auth.credentials"]' doctor.json
{
  "id": "auth.credentials",
  "category": "auth",
  "summary": "no Codex credentials were found",
  "details": {
    "auth file": "/root/.codex/auth.json",
    "auth storage mode": "File"
  },
  "remediation": "Run codex login or provide an API key through a supported auth env var."
}

یک پیکربندی خراب را شکار کنیم

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

# فایل پیکربندی را نگه می‌داریم تا بعداً برگردانیم
$ cp ~/.codex/config.toml /tmp/config.toml.bak

# یک خطای واقعی TOML: کروشه باز مانده و مقدار بی‌نام
$ printf 'model = "gpt-5.6-sol"\n[features\nbroken = \n' > ~/.codex/config.toml

$ codex doctor --json | jq '.checks["config.load"]'
{
  "id": "config.load",
  "category": "config",
  "status": "fail",
  "summary": "config could not be loaded",
  "details": {
    "column": "10",
    "error": "invalid configuration",
    "file": "/root/.codex/config.toml",
    "line": "3"
  },
  "remediation": "Fix the reported config error, then rerun codex doctor."
}

این همان چیزی است که یک ابزار تشخیصی باید بدهد: شماره‌ی خط ۳ و ستون ۱۰. پیام invalid configuration به‌تنهایی فقط می‌گفت فایل خراب است؛ عددهای خط و ستون می‌گویند کدام خط و کدام کاراکتر.

اثر خرابی روی خود گزارش هم محسوس است. وقتی پیکربندی بارگذاری نشود، کدکس هر بررسی‌ای که به پیکربندی نیاز دارد را کنار می‌گذارد و گزارش از ۲۱ بررسی به ۱۲ بررسی کوتاه می‌شود. یعنی auth، mcp، sandbox و updates ناپدید می‌شوند. برگرداندن فایل پشتیبان، همان ۲۱ بررسی را برمی‌گرداند و config دوباره سبز می‌شود.

# برگرداندن نسخه‌ی سالم
$ cp /tmp/config.toml.bak ~/.codex/config.toml
$ codex doctor --summary --ascii --no-color | grep -E "config|ok \|"
  [ok] config       loaded
  [ok] mcp          no MCP servers configured
  [ok] updates      update configuration is locally consistent
18 ok | 1 idle | 3 notes | 1 warn | 1 fail failed

خواندن هر بخش به زبان ساده

گزارش ۲۱ بررسی دارد و لازم نیست همه را بخوانید. جدول زیر همان بررسی‌هایی را می‌گیرد که در عمل بیشتر به درد می‌خورند و می‌گوید هرکدام چه چیزی را ثابت می‌کنند.

بخش install ارزش عملی خاصی دارد. اگر binary از یک مسیر اجرا شود که با ریشه‌ی بسته‌ی npm شما فرق دارد، این بررسی هشدار می‌دهد و دستور درست را پیشنهاد می‌کند. در اجرای ما نصب از npm و سازگار بود، پس --summary حتی مسیرهای نصب را چاپ نکرد؛ برای دیدن آن‌ها --all لازم است.

بخش state هم برای کسانی مهم است که نشست‌هایشان جمع شده. در اجرای ما هیچ پایگاه‌داده‌ای برای مقایسه نبود و بررسی در حالت idle ماند؛ روی ماشینی که ساعت‌ها کدکس اجرا شده، همین بررسی تعداد فایل‌های rollout و حجمشان را می‌دهد، که همان عددی است که اگر بزرگ شود کانتکست و فضای دیسک را می‌بلعد.

کِی doctor کافی نیست

doctor فقط وضعیت محلی را می‌بیند. سه چیز را نمی‌تواند تشخیص دهد و نباید از گزارش سبز انتظار داشته باشید که پاسخ دهد.

اول، خطاهای سمت سرور. اگر درخواست‌ها با خطای ۴۰۱ برمی‌گردند در حالی که بررسی auth سبز است، مشکل از حساب یا کلید شماست، نه از نصب محلی. دوم، پاسخ‌های بد از خود مدل. کیفیت خروجی و پایداری مدل در هیچ گزارش محلی‌ای نیست. سوم، نشست‌های بلند و پرهزینه؛ doctor می‌گوید پایگاه‌داده سالم است، نه اینکه کانتکست شما جا دارد.

یک مرز دیگر هم هست: در این اجرا بررسی websocket هشدار داد و متن خطا Missing bearer or basic authentication in header بود، چون هیچ مجوزی وجود نداشت. یعنی آن هشدار پیامد خطای مجوز بود، نه مشکلی جداگانه در شبکه. اول مجوز را درست کنید، بعد درباره‌ی WebSocket قضاوت کنید. همین ترتیب در فهرست تغییرات کدکس هم دیده می‌شود، جایی که بررسی‌های محیطی و خود فرمان در دو مرحله‌ی جدا اضافه شدند.

اگر تا اینجا نرسیده‌اید که کدکس را چطور راه بیندازید، پست اجرای codex exec در خط لوله مسیر راه‌اندازی آن را در CI نشان می‌دهد و پست اتصال سرور MCP با client secret پیکربندی config.toml را برای سرورهای واقعی باز می‌کند. اگر نسخه‌ی شما فرمان doctor را نشناخت، انتشار 0.157.0 را ببینید و با فرمان نصب همین نسخه به‌روزرسانی کنید.

منابع

1. مرجع خط فرمان کدکس: فرمان‌های توسعه‌دهنده و codex doctor
2. انتشار کدکس 0.131.0، ۱۸ مه ۲۰۲۶: اضافه شدن codex doctor
3. کامیت افزودن codex doctor در مخزن کدکس
4. انتشار کدکس 0.135.0: غنی‌سازی بررسی‌های محیطی و ترمینال
5. کامیت افزودن بررسی‌های محیطی به doctor
6. سورس doctor در کدکس: چرا فقط‌خواندنی است
7. فهرست تغییرات کدکس و ChatGPT
8. انتشار کدکس 0.157.0