خطای 401 Unauthorized در Codex: علت‌ها و راه‌حل‌ها
تا 2026-10-07، وقتی CLI یا افزونه IDE مربوط به Codex خطای 401 Unauthorized برمیگرداند، مستندات رسمی به سه نقطه بررسی میرسد: روش ورود فعال شما (codex login status)، محلی که اعتبارنامه‌ها در آن کش میشوند (~/.codex/auth.json یا مخزن اعتبارنامه سیستم‌عامل)، و در مورد ارائهدهنده سفارشی، نحوه ترکیب model_provider، env_key و requires_openai_auth در config.toml. راه‌حل‌ها عبارت‌اند از اجرای دوباره codex login، تغییر به کلید API با printenv OPENAI_API_KEY | codex login --with-api-key، یا قرار دادن کلید در جایی که ارائهدهنده واقعاً آن را میخواند. این صفحه از واژه‌های مستندات و تاریخچه تغییرات رسمی OpenAI Codex پیروی میکند و راهاندازی QCode را نشان میدهد.
به‌روزرسانی شده 2026-11-14
یک کلید برای Claude، GPT و مدل‌های پیشروی چینی، با صورت‌حساب به‌ازای توکن، آماده به کار در چند دقیقه.
- صورت‌حساب به‌ازای توکن — نرخ‌های زنده در /models
- پرداخت با کارت (Visa / Mastercard)، Apple Pay، Google Pay یا رمزارز
- بهصورت خودخدمت: شارژ حساب و فعال‌سازی فوری
چهار نکته که ابتدا باید روشن شود
روش‌های ورود رسمی
ورود با ChatGPT از اشتراک شما استفاده میکند؛ ورود با کلید API بر پایه مصرف است، و مستندات می‌گوید ورود با کلید API از قیمت‌گذاری استاندارد API استفاده میکند، نه از اعتبارهای پلن ChatGPT. CLI، افزونه IDE و اپلیکیشن دسکتاپ از هر دو پشتیبانی میکنند.
اعتبارنامههای کششده
جزئیات ورود در ~/.codex/auth.json یا مخزن اعتبارنامه سیستم‌عامل کش می‌شود و بین CLI و افزونه IDE مشترک است؛ از هر کدام خارج شوید، دفعه بعد که دیگری را اجرا کنید باید دوباره وارد شوید.
منبع کلید در ارائهدهنده سفارشی
env_key نام متغیر محیطی‌ای را مشخص میکند که Codex کلید را از آن میخواند؛ طبق مستندات، وقتی requires_openai_auth = true باشد، Codex مقدار env_key را نادیده میگیرد و از احراز هویت OpenAI استفاده میکند.
مستندات QCode آنها را چگونه تفسیر میکند
در مستندات QCode، خطای 401 به معنای مشکل در کلید است و 404 به معنای پیشوند مسیر اشتباه؛ base_url مربوط به Codex با یک بخش کم یا زیاد، 404 برمیگرداند.
خطای 401 به چه معناست و ابتدا چه چیزی را بررسی کنید
تا 2026-10-07، خطای 401 Unauthorized از Codex به این معناست که سرور اعتبارنامههای روی درخواست را نپذیرفته، یا درخواست هیچ اعتبارنامهای نداشته است. مستندات رسمی دو روش ورود را فهرست میکند: ورود با ChatGPT (دسترسی مبتنی بر اشتراک) و ورود با کلید API (دسترسی مبتنی بر مصرف)؛ اپلیکیشن دسکتاپ، Codex CLI و افزونه IDE از هر دو پشتیبانی میکنند، در حالی که Codex cloud به ChatGPT نیاز دارد. وقتی نشست معتبری در دسترس نباشد، codex login با جریان مرورگر آن مسیر پیشفرض است و codex login status روش فعال را نشان میدهد. در مورد ارائهدهنده سفارشی، config.toml هم مهم است: مقدار پیشفرض model_provider برابر openai است؛ ارائه‌دهنده‌ای با requires_openai_auth = true از احراز هویت OpenAI استفاده میکند و env_key را نادیده میگیرد؛ ارائه‌دهنده‌ای که فقط env_key دارد، کلید را از همان متغیر میخواند؛ و اگر هیچ‌کدام تنظیم نشده باشد، مستندات می‌گوید Codex فرض میکند ارائهدهنده به احراز هویت نیازی ندارد.
تغییرات اخیر و گزارش‌های کاربران
گزارش تغییرات رسمی چند ورودی مرتبط با ورود دارد (خط زمانی زیر را ببینید)؛ در 2026-10-01 با نسخه 0.160.0، مستندات درباره این روشن شد که اعتبارنامههای ارائهدهنده چگونه از بک‌اند ذخیره‌سازی پیکربندی‌شده استفاده میکنند و env_key چگونه متغیر محیطی کلید API را مشخص میکند. جدا از این، یک گزارش مشکل با عنوان «unexpected status 401 Unauthorized issue» در GitHub openai/codex در 2026-09-25 باز شد که در آن کاربران گزارش میدهند حتی در حالت ورود ChatGPT پیام «Incorrect API key provided» را میبینند (گزارش‌های کاربران؛ OpenAI علتی را مستند نکرده است). این صفحه چنین مواردی را فقط نشانه‌ای از برخورد افراد زیادی با این خطا می‌داند؛ مراحل از مستندات رسمی پیروی میکنند.
سه ورودی مرتبط با ورود در گزارش تغییرات رسمی
Codex CLI 0.156.0: ورود می‌تواند از طریق پروکسی‌های سیستم بازیابی شود، و همان ورودی اعتبارنامههای MCP را وقتی کشف OAuth خطای 503 برمیگرداند تازهسازی میکند.
Codex CLI 0.159.0: ورود محلی ChatGPT مرورگر را بهطور قابل‌اعتماد باز میکند، و فرایند آشناسازی اولیه میان‌بری برای کپی لینک ورود اضافه میکند.
Codex CLI 0.160.0: مستندات روشن میکنند که اعتبارنامههای ارائهدهنده چگونه از بک‌اند ذخیره‌سازی پیکربندی‌شده استفاده میکنند و env_key چگونه متغیر محیطی کلید API را مشخص میکند.
تأییدشده در برابر تأییدنشده
تأییدشده (عیناً در مستندات رسمی)
همه موارد زیر را می‌توان واژه‌به‌واژه در مستندات رسمی بررسی کرد: دو روش ورود و اینکه هر یک کجا کار میکند؛ اینکه codex login، printenv OPENAI_API_KEY | codex login --with-api-key، codex login --device-auth، codex login status و codex logout چه کاری انجام میدهند؛ جزئیات ورود که در ~/.codex/auth.json یا مخزن اعتبارنامه سیستم‌عامل کش می‌شود (پیکربندی نمونه رسمی، file را که به auth.json اشاره دارد، به‌عنوان پیشفرض cli_auth_credentials_store علامت‌گذاری میکند) و توسط CLI و افزونه IDE به اشتراک گذاشته می‌شود، که آنها نیز همان لایه‌های پیکربندی را به اشتراک میگذارند؛ نشستهای ChatGPT که توکنها را پیش از انقضا بهطور خودکار تازهسازی میکنند؛ پیشفرض بودن model_provider روی openai؛ نادیده گرفته شدن env_key وقتی requires_openai_auth = true؛ نادیده گرفته شدن model_provider، model_providers و openai_base_url، همراه با یک هشدار هنگام راهاندازی، در .codex/config.toml محلی پروژه؛ اینکه --profile از نسخه 0.134.0 به بعد دیگر جدول‌های [profiles.name] را از config.toml نمیخواند؛ اینکه responses تنها wire_api پشتیبانی‌شده است؛ و اینکه [model_providers.openai] مجاز نیست و در عوض از openai_base_url استفاده می‌شود.
تأییدنشده یا مستندنشده
دو مورد را این صفحه نتوانست تأیید کند، پس برنامه‌ریزی خود را بر پایه آنها قرار ندهید: ① چرا برخی کاربران حتی با ورود ChatGPT خطای 401 میبینند، چون issue در GitHub فقط حدس‌های کاربران را دارد و مستندات چیزی در این باره نمی‌گویند؛ ② این صفحه هیچ جدول رسمی از تمام رشته‌های خطای 401 Codex پیدا نکرد، بنابراین جز جایی که یک رشته به مستندات نسبت داده شود، رشته‌های خطای نقل‌شده در اینجا از گزارش‌های کاربران می‌آیند.
دو جفت تنظیم که افراد آنها را با هم اشتباه می‌گیرند
ورود ChatGPT در برابر کلید API
ورود ChatGPT از اشتراک شما و یک جریان مرورگری (codex login) استفاده میکند؛ روی ماشین راهدور یا بدون رابط گرافیکی از codex login --device-auth استفاده کنید. ورود با کلید API با نرخ‌های استاندارد API صورت‌حساب می‌شود: در CLI، printenv OPENAI_API_KEY | codex login --with-api-key؛ در افزونه IDE، در صفحهای که هنوز وارد حساب نشده‌اید گزینه Use API Key را انتخاب کنید. مستندات، کلیدهای API را پیشفرض توصیه‌شده برای خودکارسازی می‌نامند، و CODEX_API_KEY کلیدی را در اختیار فرایند غیرتعاملی Codex قرار میدهد. برای تغییر، ابتدا codex logout را اجرا کنید تا اعتبارنامههای فعلی پاک شوند.
env_key در برابر requires_openai_auth
این‌ها دو گزینه احراز هویت برای یک ارائهدهنده سفارشی هستند. env_key = "NAME" باعث می‌شود Codex کلید را از همان متغیر محیطی بخواند؛ نام را شما انتخاب میکنید و باید با متغیری که واقعاً export میکنید مطابقت داشته باشد. requires_openai_auth = true باعث می‌شود ارائهدهنده از احراز هویت OpenAI (ChatGPT یا کلید API) استفاده کند، و مستندات میگویند Codex در این حالت env_key را نادیده میگیرد. اگر هیچ‌کدام تنظیم نشوند، Codex فرض میکند احراز هویت لازم نیست. همچنین experimental_bearer_token برای یک توکن مستقیم وجود دارد که مستندات آن را به نفع env_key توصیه‌نشده علامت‌گذاری میکند.
به همین ترتیب پیش بروید
① برای دیدن اینکه روی ChatGPT هستید یا روی کلید API، codex login status را اجرا کنید (زمانی که وارد شده باشید با 0 خارج می‌شود). ② برای سرویس خود OpenAI: codex logout را اجرا کنید، سپس codex login (ورود ChatGPT در مرورگر)، printenv OPENAI_API_KEY | codex login --with-api-key (تغییر به کلید API) یا codex login --device-auth (ماشین‌های راهدور یا headless)؛ افزونه IDE همان کش ورود CLI را به اشتراک می‌گذارد، بنابراین اصلاح را دریافت میکند. ③ برای ارائهدهنده سفارشی: model_provider و جدول [model_providers.name] را در ~/.codex/config.toml قرار دهید، چون آن کلیدها در .codex/config.toml محلی پروژه نادیده گرفته میشوند؛ با --profile، تنظیمات را در ~/.codex/name.config.toml قرار دهید. ④ برای QCode، مستندات این config.toml را ارائه میدهد: model_provider = "qcode"، model = "gpt-6.1-sol"، model_reasoning_effort = "high"، به‌همراه جدول [model_providers.qcode] با name = "qcode"، base_url = "https://api.qcode.cc/openai"، wire_api = "responses"، requires_openai_auth = true (نام ارائهدهنده به خود شما بستگی دارد؛ مثال مستندات از qcode استفاده میکند). در ~/.codex/auth.json بنویسید {"OPENAI_API_KEY": "cr_xxxxxxxxxx"} با کلید cr_ خودتان، و مجوزهای فایل را روی 600 تنظیم کنید. برای انتقال کلید از طریق متغیر محیطی به‌جای آن، requires_openai_auth = true را در جدول با env_key = "QCODE_API_KEY" جایگزین کنید (نام متغیر هم به خود شما بستگی دارد) و QCODE_API_KEY را export کنید. از یکی استفاده کنید، نه هر دو: مستندات رسمی میگویند وقتی requires_openai_auth = true است، Codex مقدار env_key را نادیده میگیرد؛ بنابراین اگر هر دو تنظیم شوند، متغیر محیطی اثری ندارد. ⑤ خودآزمایی: درخواستی به https://api.qcode.cc/openai/v1/models با Authorization: Bearer و کلید خود بفرستید؛ اگر یک لیست JSON برگردد، یعنی آدرس و کلید هر دو درست هستند.
در QCode
در QCode، Codex فقط با مدل‌های GPT کار میکند؛ Claude و خانواده‌های DeepSeek، GLM، Kimi و Qwen از طریق پروتکل OpenAI Responses که Codex از آن استفاده میکند ارائه نمی‌شوند. در config.toml، base_url را روی https://api.qcode.cc/openai با wire_api = "responses" تنظیم کنید؛ کلید، کلید QCode شماست که با cr_ شروع می‌شود، از داشبورد میآید و مطابق مستندات در OPENAI_API_KEY در ~/.codex/auth.json نوشته می‌شود. مستندات همچنین یک حالت با متغیر محیطی را فهرست میکنند: requires_openai_auth = true را با env_key = "QCODE_API_KEY" جایگزین کنید و آن متغیر را export کنید. از یکی استفاده کنید، نه هر دو: مستندات رسمی میگویند وقتی requires_openai_auth = true است، Codex مقدار env_key را نادیده میگیرد؛ بنابراین اگر هر دو تنظیم شوند، متغیر محیطی اثری ندارد. مدل پیشفرض مستندات gpt-6.1-sol است؛ می‌توانید به gpt-6-sol یا gpt-5.6-terra تغییر دهید. در صورت دریافت 401، مواردی را که مستندات فهرست میکند بررسی کنید: کلید با cr_ شروع می‌شود، کلید موجود در auth.json کامل است و فاصله یا شکست خط اضافی ندارد، و وضعیت کلید و سهمیه باقی‌مانده در داشبورد درست به نظر می‌رسند؛ کلید اشتباه Invalid API key را برمیگرداند. base_url با یک بخش اضافه یا یک بخش کم، 404 برمیگرداند، نه 401. محاسبه هزینه به‌ازای هر توکن است؛ برای قیمت هر مدل /models را ببینید.
پرسش‌های متداول
Codex خطای 401 Unauthorized میدهد: ابتدا چه چیزی را باید بررسی کنم؟
ابتدا codex login status را اجرا کنید. طبق مستندات رسمی، حالت احراز هویت فعال را چاپ میکند و زمانی که وارد شده باشید با 0 خارج می‌شود. وقتی دانستید روی ChatGPT هستید یا از کلید API استفاده میکنید، بررسی کنید Codex با OpenAI ارتباط برقرار میکند یا با یک ارائهدهنده سفارشی: برای OpenAI، دوباره وارد شوید یا کلیدها را تغییر دهید؛ برای ارائهدهنده سفارشی، بررسی کنید ارائه‌دهنده‌ای که model_provider مشخص میکند از کدام احراز هویت استفاده میکند (env_key یا requires_openai_auth) و اینکه کلید همان جایی است که آن ارائهدهنده از آن میخواند.
چگونه بین ورود با ChatGPT و کلید API جابهجا شوید؟
برای پاک کردن اعتبارنامههای فعلی codex logout را اجرا کنید، سپس از راه دیگر وارد شوید. طبق مستندات: برای ChatGPT، codex login را اجرا کنید و کار را در مرورگر تمام کنید؛ برای کلید API، آن را با printenv OPENAI_API_KEY | codex login --with-api-key وارد کنید؛ در افزونه IDE، در صفحهای که از حساب خارج شدهاید، Sign in with ChatGPT یا Use API Key را انتخاب کنید. CLI و افزونه همان ورود کششده را به اشتراک میگذارند. اگر مدیر forced_login_method را تنظیم کرده باشد، وقتی اعتبارنامههای شما مطابقت نداشته باشند، Codex شما را از حساب خارج میکند و از برنامه بیرون میآید.
مدتی کار میکرد و حالا 401 برمیگرداند. آیا توکن منقضی شده است؟
اگر از ورود ChatGPT استفاده میکنید، ابتدا آن را یک نشست کهنه در نظر بگیرید: codex logout را اجرا کنید، سپس codex login را اجرا کنید. مستندات میگویند نشستهای ChatGPT توکنها را در حین استفاده و پیش از انقضا بهطور خودکار تازهسازی میکنند، بنابراین نشستهای فعال معمولاً نیازی به ورود دوباره از مرورگر ندارند. در GitHub، کاربران گزارش میدهند که پس از کهنه شدن ورود، پیام «Provided authentication token is expired. Please try signing in again.» یا «Your access token could not be refreshed because your refresh token was revoked. Please log out and sign in again.» را میبینند (هر دو گزارش کاربر). در یک ماشین راهدور یا بدون رابط گرافیکی، با codex login --device-auth وارد شوید.
ارائهدهنده سفارشی من env_key را تنظیم میکند و کلید را export کردهام. چرا هنوز 401 دریافت میکنم؟
ابتدا بررسی کنید که همان ارائهدهنده requires_openai_auth = true داشته باشد: مستندات میگویند Codex در این حالت env_key را نادیده میگیرد و از احراز هویت OpenAI (ChatGPT یا کلید API) استفاده میکند. اگر اینطور نیست، مطمئن شوید مقدار env_key دقیقاً با نام متغیری که export کردهاید مطابقت دارد؛ مستندات میگویند Codex متغیری را میخواند که در آن پیکربندی نام برده شده است، بنابراین خود نام ثابت نیست. در GitHub، کاربران گزارش میدهند که وقتی هیچ اعتبارنامهای پیکربندی نشده است، پیام «401 Unauthorized: Missing bearer or basic authentication in header» را میبینند (گزارش کاربر).
config.toml را ویرایش کردم، اما به نظر میرسد Codex هنوز از OpenAI استفاده میکند؟
بررسی کنید که تنظیمات ارائهدهنده همان جایی باشد که Codex آنها را میخواند. مستندات سه تله را توضیح میدهد: model_provider، model_providers و openai_base_url در .codex/config.toml محلی پروژه نادیده گرفته میشوند و هنگام راهاندازی هشدار میدهند؛ از Codex 0.134.0، --profile دیگر [profiles.name] را از config.toml نمیخواند، بنابراین از ~/.codex/name.config.toml استفاده کنید؛ و شناسههای داخلی openai، ollama و lmstudio را نمیتوان برای ارائهدهنده سفارشی دوباره به کار برد، بنابراین برای تغییر فقط آدرس OpenAI از openai_base_url استفاده کنید. اگر model_provider تنظیم نشده باشد، بهصورت پیشفرض openai است.
چگونه خطای 401 را با QCode عیب‌یابی کنم؟
از مستندات QCode پیروی کنید: تأیید کنید که کلید با cr_ شروع می‌شود، کلید موجود در ~/.codex/auth.json کامل است و فاصله یا خط‌شکن اضافه ندارد، و وضعیت کلید و سهمیه باقی‌مانده در داشبورد درست به نظر می‌رسند؛ مستندات همچنین اشتراک منقضی‌شده را از دلایل 401 می‌داند. اگر از نسخه متغیر محیطی مستندات استفاده میکنید، تأیید کنید که ارائهدهنده env_key = "QCODE_API_KEY" دارد، requires_openai_auth = true ندارد، و متغیر export شده است: مستندات رسمی میگویند وقتی requires_openai_auth = true باشد، Codex env_key را نادیده میگیرد. متغیرهای محیطی باقی‌مانده می‌توانند تنظیمات فعلی شما را بازنویسی کنند، بنابراین env | grep -i openai را اجرا کنید و متغیرهایی را که دیگر استفاده نمی‌کنید پاک کنید. سپس با Authorization: Bearer و کلید خود در برابر https://api.qcode.cc/openai/v1/models خودآزمایی کنید: اگر یک فهرست JSON دریافت کردید، آدرس و کلید درست هستند. مستندات 401 را مشکل کلید و 404 را پیشوند مسیر نادرست می‌خوانند؛ base_url مربوط به Codex باید https://api.qcode.cc/openai باشد.
منابع
از سمت OpenAI: صفحه‌های مستندات رسمی Codex با عنوان‌های Authentication، Config basics، Advanced Configuration، Configuration Reference، Environment variables، command line options و IDE extension settings (همین مستندات روی developers.openai.com/codex و learn.chatgpt.com ارائه میشوند)، به‌همراه تغییرات Codex و یادداشت‌های انتشار GitHub openai/codex برای 0.156.0، 0.159.0 و 0.160.0، همه در تاریخ 2026-10-07 دریافت شده‌اند. از سمت QCode: صفحه‌های مستندات QCode برای آموزش Codex (به‌روزرسانی 2026-09-30)، نقاط پایانی و قالب‌های API، کدهای خطا، عیب‌یابی و راهاندازی Cursor، که همان روز دریافت شده‌اند. پیشینه: issue 48237 در GitHub openai/codex و چند issue دیگر مرتبط با 401 که فقط به‌عنوان گزارش کاربران نقل شده‌اند.
یک کلید cr_ برای Codex و Claude Code
Codex از طریق https://api.qcode.cc/openai به gpt-6-sol، gpt-6.1-sol و سایر مدل‌های GPT دسترسی پیدا میکند و هزینه بر اساس توکن محاسبه می‌شود؛ برای قیمت هر مدل /models را ببینید.
مطالب مرتبط
اعتبار API پلن ChatGPT Pro تمام شده است: حالا چه باید کرد (2026-11)
پلن‌های Pro و Business تا $500 در ماه اعتبار API دریافت میکنند، بدون انتقال به ماه بعد، در صفر شدن اعتبار HTTP 429 دریافت می‌شود؛ اعتبار پرداختی را بهصورت رسمی اضافه کنید یا با کلید QCode ادامه دهید.
توضیح مسدود شدن حساب‌های Codex و ChatGPT Pro
چرا حساب‌های Codex و ChatGPT Pro تعلیق میشوند و چه باید کرد.
Codex «Selected model is at capacity»: نه سهمیه، نه 429
چگونه خطای ظرفیت را از سایر خطاها تشخیص دهیم و چه باید کرد.
راهنمای پرداخت با رمزارز
نه رمزارز، 56 شبکه، کارمزد پلتفرم صفر برای اعتبار API کدنویسی با هوش مصنوعی.
مراحل و نقل‌قول‌های این صفحه در تاریخ 2026-10-07 با مستندات و تغییرات Codex از OpenAI و مستندات QCode بررسی شده‌اند؛ در صورت اختلاف، صفحه‌های رسمی ملاک هستند و ممکن است تغییرات بدون اطلاع رخ دهد. رشته‌های خطا و توضیحات برگرفته از issueهای GitHub گزارش کاربران هستند، نه یافته‌های رسمی. دسترس‌پذیری مدل‌ها همان چیزی است که /models نشان میدهد.