۳ مرحلهٔ کلیدی برای فعال‌سازی Codex CLI با API کرزی‌روتر

اگر می‌خواهید از محیط محدود مرورگر خارج شوید و هوش مصنوعی را مستقیماً به فایل‌های سیستم خود متصل کنید، باید محیط توسعه خود را بازتعریف کنید. راه‌اندازی یک محیط توسعه حرفه‌ای برای AI فراتر از باز کردن یک تب در مرورگر است؛ این امر مستلزم یکپارچگی تنگاتنگ بین ترمینال شما و سیستم فایل محلی است. با پیکربندی Codex CLI و اپلیکیشن دسکتاپ متناظر آن، توسعه‌دهندگان می‌توانند از چت‌های ساده به سمت دستکاری مستقیم پروژه‌ها حرکت کنند.

این تغییر رویکرد در حالی رخ می‌دهد که صنعت به سمت جریان‌های کاری عامل‌محور (Agentic) — شبیه به داشتن یک دستیار که اجازه دارد خودش پوشه‌ها را باز کند و فایل‌ها را ویرایش کند — حرکت می‌کند. در این مدل، هوش مصنوعی برای خواندن و نوشتن فایل‌ها در محیط محلی نیاز به مجوز دارد. طبق گزارش‌های فنی، مانع اصلی برای توسعه‌دهندگان، توانایی مدل نیست، بلکه اصطکاک در تنظیم متغیرهای محیطی (Environment Variables)، پیکربندی‌های PATH و مدیریت کلیدهای API در سیستم‌عامل‌های مختلف است. هدف نهایی ایجاد یک محیط است که با یک اسکریپت، یک جایگزین دستی و عیب‌یابی‌های هدفمند قابل ردیابی باشد. همان‌طور که در تحلیل‌های قبلی ما درباره‌ی پروتکل‌های ارتباطی مدل‌ها اشاره کردیم، اگر دستور codex --version کار کند، یعنی نصب در دسترس است؛ اما اینکه آیا درخواستی پاسخ داده می‌شود یا خیر، به ترکیب مدل، آدرس ارائه‌دهنده و کلید API بستگی دارد.

زیربنای API

پیش از نصب نرم‌افزار، باید اتصال به یک ارائه‌دهنده مدل برقرار کنید. در این راهنما از Crazyrouter (کرزی‌روتر) به عنوان واسط استفاده شده است؛ ابزاری که به توسعه‌دهندگان اجازه می‌دهد قیمت مدل‌ها را مقایسه کرده و صورت‌حساب چندین مدل را در یک نقطه مدیریت کنند. به نقل از مستندات این سرویس، انتخاب ارائه‌دهنده نباید تنها بر اساس تعرفه ارزان باشد، بلکه پشتیبانی از پاسخ‌ها، در دسترس بودن و کیفیت پشتیبانی نیز باید با نیازهای کاربر سازگار باشد. اگر از دسترسی مستقیم به API رسمی استفاده می‌کنید، نیاز به این ارائه‌دهنده واسط نیست.

برای شروع، کاربر باید یک حساب کاربری بسازد، ایمیل خود را تأیید کند و به بخش "Token Management" برود تا یک کلید API ایجاد کند (این عملیات با عنوان "Create Token" لیست شده است). بسیار حیاتی است که اطمینان حاصل کنید مدل خاص gpt-5.6-sol فعال است و حساب شما اعتبار کافی دارد، زیرا اسکریپت‌های نصب این موارد را فراهم نمی‌کنند. توجه داشته باشید که رمز عبور وب‌سایت با کلید API متفاوت است. همچنین برخی از صفحات منبع ممکن است رابط کاربری چینی را نشان دهند. هنگام ایجاد توکن، شما باید تاریخ انقضا، بودجه و دسترسی به مدل‌ها را کنترل کنید.

نصب دستی CLI

برای کسانی که کنترل دقیق روی سیستم می‌خواهند، مسیر دستی توصیه می‌شود تا هر وابستگی (Dependency) به طور مجزا تأیید شود. در ویندوز، این کار مستلزم نصب نسخه LTS از Node.js از وب‌سایت رسمی است که با معماری پردازنده شما مطابقت داشته باشد. حتماً گزینه فعال‌سازی PATH را فعال نگه دارید و پس از نصب، PowerShell را ری‌استارت کنید.

این دستورات را به صورت تک‌تک اجرا کنید:

• node --version
• npm.cmd --version
• npm.cmd install -g @openai/codex
• codex.cmd --version

در صورت نیاز، Git را از سایت رسمی Git-for-Windows نصب کنید. در macOS، فرآیند از طریق یک دستور curl ساده‌تر و بهینه‌تر است: curl -fsSL https://chatgpt.com/codex/install.sh | sh. دستورالعمل‌های مربوط به PATH را دنبال کنید، ترمینال را ری‌استارت کرده و نصب را با codex --version تأیید کنید.

پیکربندی محیط

اتصال CLI به API نیازمند یک فایل config.toml در دایرکتوری .codex در پروفایل کاربر است. این فایل مدل، ارائه‌دهنده و پروتکل ارتباطی را تعریف می‌کند.

جزئیات تنظیمات

برای راه‌اندازی دستی، کاربران ویندوز باید دایرکتوری را با دستور New-Item -ItemType Directory -Path "$env:USERPROFILE\.codex" -Force بسازند و فایل پیکربندی را با notepad.exe باز کنند. کاربران مک باید از دستور mkdir -p ~/.codex استفاده کرده و فایل را با nano ~/.codex/config.toml ویرایش کنند.

پارامترهای کلیدی پیکربندی عبارتند از:

• model: مقدار آن را روی "gpt-5.6-sol" تنظیم کنید.
• model_provider: مقدار آن را روی "crazyrouter" قرار دهید.
• base_url: مقدار https://api.crazyrouter.com/v1 (دقت کنید که عبارت /responses را به انتهای آن اضافه نکنید).
• wire_api: مقدار آن را روی "responses" تنظیم کنید.

اگر فایل‌هایی از قبل وجود دارند، تنظیمات خارجی حفظ می‌شوند. دو فیلد اول باید حتماً پیش از اولین بخش که در کروشه قرار دارد، نوشته شوند. در Notepad با Ctrl+S و در nano با Control+O، سپس Return و در نهایت Control+X ذخیره کنید. مطمئن شوید نام فایل به .txt ختم نشود. توجه داشته باشید که نسخه تست شده‌ی اسکریپت از هاست cn.crazyrouter.com استفاده می‌کرد، در حالی که قالب دستی از api.crazyrouter.com استفاده می‌کند؛ از یک پیکربندی کامل و یکپارچه استفاده کنید.

مدیریت کلید API

پس از تنظیم فایل کانفیگ، کلید API باید به عنوان یک متغیر محیطی ذخیره شود. کاربران ویندوز باید از یک پرامپت امن استفاده کنند: $codexApiKey = Read-Host 'Paste your API Key, then press Enter' -AsSecureString. پس از بازگشت پرامپت، متغیر را ست کنید: [Environment]::SetEnvironmentVariable('OPENAI_API_KEY', ([System.Net.NetworkCredential]::new('', $codexApiKey)).Password, 'User'). سپس ترمینال را به طور کامل ببندید و دوباره باز کنید.

کاربران macOS عبارت export OPENAI_API_KEY='YOUR_API_KEY' را به فایل .zshrc خود با استفاده از nano اضافه کنند. عبارت جایگزین را وارد کنید اما علامت‌های نقل‌قول را حفظ کنید. سپس پیکربندی را با source ~/.zshrc بارگذاری مجدد کنید. از آنجایی که این فایل کلید را به صورت متن ساده (Plain Text) نگه می‌دارد، هرگز نباید در اسکرین‌شات‌ها یا مخازن کد (Repositories) قرار گیرد.

مسیر اسکریپت‌های خودکار

برای استقرار سریع‌تر، Crazyrouter اسکریپت‌های نصب آماده‌ای ارائه می‌دهد. در ویندوز، اجرای یک اسکریپت PowerShell با فلگ $env:CRAZYROUTER_CODEX_MODE='full' به طور خودکار وجود Git، Node.js و CLI را بررسی کرده، وابستگی‌های ناقص را تکمیل می‌کند و پیکربندی ارائه‌دهنده را می‌نویسد.

اگر CLI از قبل نصب شده است، در خط اول عبارت 'full' را با 'switch' جایگزین کنید. خط دوم یک اسکریپت عمومی را از گیت‌هاب (https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/main/install-crazyrouter-codex.ps1) فراخوانی و اجرا می‌کند. مسیر نصب کامل ممکن است باعث باز شدن دیالوگ‌های نصب‌کننده و مجوزها شود و از گزینه‌هایی برای پذیرش توافق‌نامه‌های نرم‌افزاری استفاده کند. کلید API را در پرامپت وارد کنید (نامرئی بودن ورودی در این مرحله طبیعی است) و مدل را تنها در صورتی تأیید کنید که توکن شما اجازه دسترسی به آن را می‌دهد.

کاربران مک می‌توانند همین نتیجه را با یک اسکریپت bash به دست آورند: ابتدا touch ~/.zshrc و سپس curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-codex-cli/main/install-crazyrouter-codex.sh | bash -s -- --full. اگر CLI از قبل وجود دارد، از --switch استفاده کنید. اگر Git نصب نیست، پیش از اجرای مجدد اسکریپت، دستور xcode-select --install را اجرا کنید. در نهایت، source ~/.zshrc و codex --version را اجرا نمایید.

تأیید اتصال

تأیید در دو مرحله انجام می‌شود. ابتدا یک بررسی ساده در شل تأیید می‌کند که آیا OPENAI_API_KEY حضور دارد یا خیر:

• ویندوز: if ([string]::IsNullOrWhiteSpace($env:OPENAI_API_KEY)) { 'KEY_MISSING' } else { 'KEY_FOUND' }
• مک: if [ -n "${OPENAI_API_KEY:-}" ]; then echo KEY_FOUND; else echo KEY_MISSING; fi

ظهور KEY_FOUND فقط حضور کلید را تأیید می‌کند، نه اعتبار آن را. مرحله دوم، یک تست عملکردی است که با ایجاد یک دایرکتوری تست (مثلاً codex-first-test) با استفاده از New-Item (ویندوز) یا mkdir -p (مک) انجام می‌شود. دستور codex را اجرا کرده و این پرسش را بپرسید: "Erkläre in drei Sätzen den Zweck einer README-Datei. Lies und ändere keine Dateien."

یکپارچه‌سازی اپلیکیشن دسکتاپ

اپلیکیشن دسکتاپ ChatGPT (که شامل رابط Codex است) به طور جداگانه از طریق استور رسمی یا نصب‌کننده نصب می‌شود. در ویندوز، اپلیکیشن باید پس از ذخیره کلید API در محیط سیستم، ری‌استارت شود.

در macOS، در بخش "About This Mac" بررسی کنید تا بین نسخه‌های Apple Silicon یا Intel انتخاب کنید. اگر از فایل .dmg استفاده می‌کنید، برنامه را به پوشه "Applications" بکشید؛ برای فایل .pkg، مراحل دستیار نصب را دنبال کنید. یک نکته بسیار ظریف وجود دارد: اپلیکیشن‌هایی که از طریق Dock اجرا می‌شوند، به طور خودکار فایل .zshrc را نمی‌خوانند. برای رفع این مشکل، Codex را با Command+Q ببندید و دستور source ~/.zshrc و سپس launchctl setenv OPENAI_API_KEY "$OPENAI_API_KEY" را اجرا کنید. سپس اپلیکیشن را ری‌استارت کنید. از Command+Shift+G در دیالوگ پوشه برای ورود به ~/Projects/codex-first-test استفاده کرده و درخواست را تکرار کنید. این انتقال نشست‌محور (Session-based) است و باید بعد از هر بار ری‌بوت تکرار شود.

مدیریت دسترسی‌ها و خطاها

پس از برقراری اتصال، توانایی AI در تغییر فایل‌ها توسط تنظیمات مجوز کنترل می‌شود. حالت "Ask for approval" اجازه می‌دهد AI در پوشه پروژه کار کند، اما برای هر دسترسی خارج از آن محدوده، از کاربر اجازه بگیرد.

برای تست قابلیت نوشتن، از Codex بخواهید فایلی به نام learning-checklist.md در پوشه تست ذخیره کند که شامل سه تسک Markdown خالی برای نصب، پاسخ API و تغییرات فایل باشد. فایل را در Explorer یا Finder تأیید کنید. توجه داشته باشید که یک سیاست Read-only (فقط خواندنی) ممکن است این عملیات را مسدود کند؛ در یک تست قبلی، چنین سیاستی باعث مسدود شدن عملیات شد.

راهکارهای عیب‌یابی رایج شامل موارد زیر است:

• عدم شناسایی CLI: بررسی نصب و PATH. در مک، دستور export PATH="$PATH:$(npm config get prefix)/bin" را امتحان کنید.
• مسدود شدن codex.ps1 در PowerShell: به جای آن از codex.cmd استفاده کنید.
• خطای KEY_MISSING: فرآیند را ری‌استارت کرده یا .zshrc را مجدداً بارگذاری کنید.
• خطای HTTP 401: اعتبار کلید API، تاریخ انقضا و ارائه‌دهنده را بررسی کنید.
• خطای HTTP 403: متن خطا، انتشار مدل و قوانین حساب کاربری را مقایسه کنید.
• کارکرد CLI اما عدم کارکرد دسکتاپ: کاربر، مسیر کانفیگ و محیط پردازش را مقایسه کنید.
• Write Denied: پوشه پروژه و مجوزهای فعال را بررسی کنید.

طبق تأییدات فنی انجام شده در ۱۴ اکتبر ۲۰۲۶، این محیط با Node.js 24.21.0، npm 11.19.0، Git 2.53.0 و Codex CLI 0.162.1 پایدار بود. این‌ها مقادیر مقایسه‌ای هستند، نه حداقل نسخه‌های مورد نیاز.

تحلیل تحریریه

این پیکربندی نشان‌دهنده یک روند رو به رشد در تجربه توسعه‌دهندگان است: حرکت به سمت ابزارهای CLI "مستقل از API" (API-agnostic). با استفاده از ارائه‌دهنده‌ای مانند Crazyrouter، توسعه‌دهندگان از بسته شدن در چرخه پرداخت یک فروشنده واحد جلوگیری می‌کنند و می‌توانند مدل‌ها را بر اساس هزینه یا عملکرد، بدون بازنویسی پیکربندی محلی خود، تعویض کنند.

برای کاربر نهایی، مهم‌ترین نکته، تفاوت بین اشتراک ChatGPT و استفاده از API است. این دو مسیر پرداخت جداگانه‌ای دارند. توانایی اجرای یک ابزار CLI که با فایل‌های محلی تعامل دارد، نشان‌دهنده تغییر جایگاه AI از یک "چت‌بات" به یک "عامل محلی" (Local Agent) است که اصطکاک کپی و پیست کردن کد بین IDE و مرورگر را به شدت کاهش می‌دهد.

برای اطمینان از پایداری محیط خود، به طور منظم تاریخ انقضای توکن‌های API را بررسی کرده و بودجه خود را در داشبورد ارائه‌دهنده مانیتور کنید تا از خطاهای ۴۰۳ در میانه پروژه جلوگیری شود. برای دریافت گزارش‌های خطای مفید، سیستم‌عامل، نسخه CLI، آخرین نقطه موفقیت‌آمیز و متن پاک‌سازی شده خطا را ارائه دهید.

گام بعدی شما

• بررسی تاریخ انقضای توکن‌های API در داشبورد کرزی‌روتر برای جلوگیری از توقف ناگهانی پروژه.
• تست قابلیت نوشتن فایل در یک محیط ایزوله (Sandbox) پیش از دادن دسترسی به پوشه‌های اصلی کد.
• مقایسه هزینه استنتاج مدل gpt-5.6-sol با مدل‌های جایگزین در Crazyrouter برای بهینه‌سازی بودجه.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.