اگر ساعت‌هاست برای رفع خطای ۴۰۱ در محیط ترمینال می‌جنگید، احتمالاً در تلهٔ یک کد وضعیت کلی افتاده‌اید. باید بدانید که در Codex CLI، کد «۴۰۱ Unauthorized» تنها یک چتر بزرگ است که ۹ حالت شکست متفاوت را زیر خود پنهان می‌کند. این کد وضعیت در بسیاری از موارد، کم‌فایده‌ترین بخش خروجی است؛ زیرا تشخیص واقعی در بدنهٔ پیام (Message Body) نهفته است.
بسیاری از توسعه‌دهندگان تصور می‌کنند این خطا همیشه به معنای اشتباه بودن رمز است، اما حقیقت این است که درک این تفاوت‌های ظریف حیاتی است، زیرا راهکار رفع مشکل نبودِ توکن (Bearer Token)، با راهکار حذف یک کاراکتر «خط جدید» (Newline) در انتهای کلید، کاملاً متفاوت است. تمام موارد بررسی‌شده در این گزارش، بر روی نسخه ۰.۱۴۶.۰ این ابزار در تاریخ جولای ۲۰۲۶ بازتولید شده‌اند.
برای شروع یک عیب‌یابی اصولی، کاربران باید یک توالی سخت‌گیرانه و سه مرحله‌ای را طی کنند. اول، بررسی کنید آیا اصلاً درخواستی به شبکه ارسال شده است یا خیر. اگر خروجی حاوی عبارت «Missing environment variable» است، یعنی CLI هرگز تلاشی برای تماس با سرور نکرده است. این وضعیت نشان‌دهنده یک خطای پیکربندی محلی است، جایی که ابزار به دنبال متغیری می‌گردد که در جلسه (Session) فعلی شل، یا تعریف نشده است یا خالی است. دوم، متن دقیق بعد از برچسب «۴۰۱ Unauthorized» را بخوانید؛ سه پیام متمایز با این کد وضعیت مرتبط هستند که هر کدام به یک علت ریشه‌ای متفاوت اشاره دارند. سوم، یک تست مجزا با دستور curl انجام دهید. با ارسال یک درخواست مستقیم POST به اندپوینت API همراه با کلید، می‌توانید تعیین کنید که آیا مشکل در تنظیمات Codex است یا اینکه خودِ کلید API ابطال شده یا نامعتبر است.
یک هشدار حیاتی در این مرحله وجود دارد: برای اعتبارسنجی کلید در سرویس‌های تجمیعی (Aggregators)، هرگز از اندپوینت /v1/models استفاده نکنید. طبق گزارش‌های فنی، بسیاری از ارائه‌دهندگان فهرست مدل‌ها را عمومی نگه می‌دارند؛ این یعنی حتی اگر کلید API شما کاملاً نامعتبر باشد، باز هم درخواست به /v1/models ممکن است پاسخ ۲ همان «موفقیت» (200 OK) را برگرداند و شما را دچار احساس امنیت کاذب کند.
یکی از رایج‌ترین شکست‌های «خاموش»، خطای «Missing bearer or basic authentication in header» است. این اتفاق زمانی رخ می‌دهد که درخواست به سرور می‌رسد، اما هدرِ Authorization کاملاً غایب است. یک تصور اشتباه رایج این است که صرفاً Export کردن متغیر محیطی OPENAI_API_KEY این مشکل را حل می‌کند. با این حال، در ارائه‌دهنده پیش‌فرض، Codex CLI بسته به پلاگین مورد استفاده، ممکن است به یک نگاشت پیکربندی خاص یا نام متغیر متفاوتی نیاز داشته باشد. اگر هدر غایب باشد، یعنی CLI در تزریق کلید به شیء درخواست پیش از ارسال، شکست خورده است. این نوع رفتارهای پیش‌بینی‌نشده یادآور چالش‌های استقرار در AWS Bedrock AgentCore است که در آن شکست‌های خاموش می‌توانند عیب‌یابی را سخت کنند.
همان‌طور که در تحلیل‌های پیشین ما درباره‌ی امنیت مدل‌های بازمتن اشاره کردیم، مدیریت دقیق متغیرهای محیطی اولین سد دفاعی در برابر خطاهای زمان اجراست. در اینجا نیز با پیام «Incorrect API key provided» مواجه می‌شویم. برخلاف خطای نبودِ هدر، این پیام تایید می‌کند که کلیدی ارسال شده است، اما سرور آن را رد کرده است. این وضعیت معمولاً ناشی از موارد زیر است: استفاده از کلید مربوط به یک پروژه اشتباه، استفاده از کلید آزمایشی (Trial) منقضی شده، یا کلیدی که به دلیل مشکلات مربوط به صورت‌حساب و پرداخت (Billing) غیرفعال شده است. راه حل در اینجا تغییر تنظیمات CLI نیست، بلکه تولید یک کلید جدید از داشبورد ارائه‌دهنده است.
اما فریبنده‌ترین خطا، پیام «You didn't provide an API key» است که با خطای «Missing bearer» تفاوت دارد. این مشکل معمولاً زمانی رخ می‌دهد که هدر در حین انتقال حذف شده یا ساختار آن تخریب (Malformed) شده باشد. رایج‌ترین علت، وجود یک کاراکتر «خط جدید» (Trailing Newline) در انتهای رشته‌ی کلید API است. برای مثال، اگر کلید خود را با دستور echo $KEY > key.txt و بدون پرچم -n ذخیره کرده باشید، یا اگر هنگام کپی کردن از یک ویرایشگر متن، یک خط جدید را همراه آن برداشته باشید، CLI آن فضای خالی را در هدر قرار می‌دهد. سرور سپس هدر را تخریب‌شده می‌بیند و به‌طور کامل آن را نادیده می‌گیرد. برای رفع این مشکل، مطمئن شوید که متغیر محیطی با یک رشته تمیز، بدون کوتیشن‌های اطراف یا فضاهای خالی در انتها تنظیم شده است.
علاوه بر خطاهای ۴۰۱ صریح، «شباهت‌های گمراه‌کننده»ای وجود دارند که کاربران اغلب آن‌ها را با شکست احراز هویت اشتباه می‌گیرند. خطای «Missing environment variable» که پیش‌تر ذکر شد، یک خطای زمان اجرای محلی است، نه پاسخی از سرور. اگر با این خطا مواجه شدید، فایل‌های .bashrc، .zshrc یا .env خود را بررسی کنید. اطمینان حاصل کنید که نام متغیر دقیقاً با آنچه Codex CLI انتظار دارد مطابقت دارد (به عنوان مثال، تفاوت بین CODEX_API_KEY و OPENAI_API_KEY).
یک مورد رایج دیگر، خطای ۴۰۴ Not Found است که از تنظیم اشتباه base_url ناشی می‌شود. اگر base_url به‌جای https://api.provider.com/v1 به صورت https://api.provider.com تنظیم شده باشد، درخواست به یک اندپوینت غیرموجود می‌رسد. برخی سرورها در این حالت، اگر دایرکتوری ریشه نیاز به احراز هویت داشته باشد، پاسخ ۴۰۱ می‌دهند و اگر نیاز نداشته باشد، پاسخ ۴۰۴ می‌دهند. در هر دو حالت، کاربر وقت خود را صرف تغییر کلیدها می‌کند، در حالی که مشکل واقعی تنها نبودِ پسوند /v1 در فایل پیکربندی است. این یک مثال کلاسیک از خطای مسیریابی (Routing) است که در لباس خطای احراز هویت ظاهر شده است و مشابه رویکرد جامع برای رفع خطای گمراه‌کننده model_not_found است که در آن ترکیب صحیح آدرس و کلید کلید حل مسئله است.
علاوه بر این، کاربران سرویس‌های تجمیعی (API Aggregators) اغلب با مشکلاتی در «نگاشت مدل» (Model Mapping) مواجه می‌شوند. اگر CLI را طوری تنظیم کنید که مدلی را درخواست کند که کلید API شما به آن دسترسی ندارد (مثلاً درخواست gpt-5.5 با یک کلید سطح Tier-1)، برخی ارائه‌دهندگان به‌جای خطای ۴۰۳ Forbidden، کد ۴۰۱ را برمی‌گردانند. اگرچه این یک تخلف از استانداردهای HTTP است، اما در عمل زیاد رخ می‌دهد. اگر کلید شما برای مدل‌های پایه کار می‌کند اما برای مدل‌های پیشرفته شکست می‌خورد، سهمیه (Quota) و تنظیمات دسترسی ارائه‌دهنده خود را چک کنید.
میانگیرهای شبکه (Network Intermediaries) نیز می‌توانند باعث ایجاد نویز در احراز هویت شوند. پروکسی‌های سازمانی یا VPNهایی که بازرسی SSL (SSL Inspection) انجام می‌دهند، ممکن است هدرهای Authorization را حذف کنند یا هدرهای خودشان را تزریق نمایند و باعث شوند سرور مقصد پاسخ ۴۰۱ دهد. اگر به این موضوع شک دارید، سعی کنید CLI را از یک شبکه متفاوت اجرا کنید یا از ابزارهایی مانند Charles Proxy یا Wireshark برای بازرسی بسته‌های ارسالی استفاده کنید. اگر هدر «Authorization» در فاصله بین CLI و سرور ناپدید می‌شود، مشکل از زیرساخت شبکه شماست، نه اعتبارنامه‌ها.
در نهایت، تأثیر Escaping در شل را در نظر بگیرید. اگر کلید API شما حاوی نویسه‌های خاصی (مانند # یا !) باشد و شما متغیر را در شلی تعریف کنید که از تک‌کوتیشن (') استفاده نمی‌کند، شل ممکن است سعی کند آن کلید را به‌عنوان یک متغیر تفسیر (Interpolate) کند. این منجر به ارسال یک رشته کوتاه شده یا تغییر یافته به سرور می‌شود. همیشه هنگام Export کردن کلیدهای API در ترمینال، آن‌ها را در تک‌کوتیشن قرار دهید تا رشته دقیقاً به صورت لیتِرال حفظ شود.
به طور خلاصه، مسیر حل مشکلات احراز هویت در Codex CLI یک فرآیند حذف است. ابتدا تایید کنید که CLI واقعاً درخواستی ارسال می‌کند. سپس، بین نبودِ هدر، رد شدن کلید و تخریب هدر توسط فضاهای خالی تمایز قائل شوید. پس از رد شدن موارد مربوط به ۴۰۱، خطاهای پیکربندی مانند base_url اشتباه یا مسائل مربوط به تفسیر شل را بررسی کنید. با تمرکز بر بدنه پاسخ به‌جای کد وضعیت، می‌توانید زمان عیب‌یابی را از ساعت‌ها به دقایق کاهش دهید. نکته کلیدی این است که پیام خطای دقیق سرور، تنها نقشه قابل اعتماد برای رسیدن به راه حل است. چه یک کاراکتر خط جدید باشد، چه نبود /v1 و چه یک کلید ابطال شده، پاسخ همیشه در متن پاسخ سرور است.
گام بعدی شما
- تمام متغیرهای محیطی مربوط به کلیدها را با تک‌کوتیشن (
') مجدداً تعریف کنید تا از تفسیر شل جلوگیری شود. - اگر از فایل برای ذخیره کلید استفاده می‌کنید، با دستور
cat -e key.txtوجود کاراکترهای پنهان در انتهای خط را بررسی کنید. - در صورت تکرار خطای ۴۰۱، یک بار درخواست را مستقیم با
curlارسال کنید تا متوجه شوید مشکل در لایه CLI است یا لایه API.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو