نصب و اجرای Codex روی ویندوز با WSL (۲۰۲۶)

OpenAI Codex CLI یک دستیار کدنویسی هوش مصنوعی مبتنی بر ترمینال است که می‌تواند کد پایه شما را بخواند، کد بنویسد، دستورات را اجرا کند و فایل‌ها را مدیریت کند -- همه از خط فرمان. نکته: این ابزار برای macOS و Linux طراحی شده است. اگر از ویندوز استفاده می‌کنید، باید آن را از طریق WSL (زیرسیستم ویندوز برای لینوکس) اجرا کنید.

این راهنما کل فرآیند راه‌اندازی را از نصب WSL تا اجرای Codex روی ماشین ویندوزی شما پوشش می‌دهد.

OpenAI Codex CLI چیست؟

Codex CLI ابزار خط فرمان متن‌باز OpenAI برای توسعه نرم‌افزار با کمک هوش مصنوعی است. آن را به‌عنوان یک عامل کدنویسی native ترمینال در نظر بگیرید که می‌تواند:

کل ساختار پروژه شما را بخواند و درک کند
کد را در چندین فایل بنویسد، ویرایش و بازنویسی کند
دستورات shell را اجرا کند و خروجی را تفسیر کند
با خواندن لاگ‌ها و stack trace‌ها خطاها را دیباگ کند
با هر زبان برنامه‌نویسی کار کند

به‌صورت محلی اجرا می‌شود اما از API OpenAI (یا endpoint‌های سازگار) برای backend مدل زبانی استفاده می‌کند.

پیش‌نیازها

نیاز	جزئیات
Windows 10 (build 19041+) یا Windows 11	WSL2 نیاز به نسخه جدید ویندوز دارد
دسترسی ادمین	برای نصب WSL لازم است
کلید API OpenAI	از platform.openai.com دریافت کنید
۸+ گیگابایت رم	WSL2 یک kernel لینوکس واقعی در کنار ویندوز اجرا می‌کند
اینترنت پایدار	برای فراخوانی‌های API به OpenAI لازم است

مرحله ۱: نصب WSL2

اگر WSL2 از قبل نصب ندارید، PowerShell را به‌عنوان Administrator باز کرده و اجرا کنید:

wsl --install

این دستور WSL2 را با Ubuntu به‌عنوان توزیع پیش‌فرض نصب می‌کند. وقتی درخواست شد کامپیوتر را restart کنید.

بعد از reboot، ترمینال Ubuntu به‌طور خودکار باز می‌شود. نام کاربری و رمز عبور لینوکس خود را تنظیم کنید.

تأیید اجرای WSL2

# در PowerShell
wsl --list --verbose

باید چیزی مثل این ببینید:

  NAME      STATE           VERSION
* Ubuntu    Running         2

اگر ستون VERSION عدد ۱ را نشان می‌دهد، به WSL2 ارتقا دهید:

wsl --set-version Ubuntu 2

مرحله ۲: راه‌اندازی محیط لینوکس

ترمینال WSL خود را باز کنید (در منوی Start «Ubuntu» را جستجو کنید) و پکیج‌ها را به‌روز کنید:

sudo apt update && sudo apt upgrade -y

نصب Node.js

Codex CLI به Node.js 18+ نیاز دارد. از طریق nvm (Node Version Manager) نصب کنید:

# نصب nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# بارگذاری مجدد پیکربندی shell
source ~/.bashrc

# نصب Node.js LTS
nvm install --lts

# تأیید
node --version  # باید v22.x یا بالاتر نشان دهد
npm --version

نصب Git (اگر موجود نیست)

sudo apt install -y git

مرحله ۳: نصب Codex CLI

Codex را به‌صورت global از طریق npm نصب کنید:

npm install -g @openai/codex

نصب را تأیید کنید:

codex --version

مرحله ۴: پیکربندی کلید API

Codex برای کارکرد به یک کلید API OpenAI نیاز دارد. آن را به‌عنوان متغیر محیطی تنظیم کنید:

# برای ماندگاری به پیکربندی shell اضافه کنید
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

یا یک فایل .env در پوشه پروژه خود بسازید:

echo 'OPENAI_API_KEY=sk-your-api-key-here' > .env

استفاده از provider متفاوت LLM

Codex از هر API سازگار با OpenAI پشتیبانی می‌کند. برای استفاده از provider متفاوت، base URL را تنظیم کنید:

# مثال: استفاده از یک instance محلی Ollama
export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"

# مثال: استفاده از xAI Grok
export OPENAI_API_KEY="your-xai-key"
export OPENAI_BASE_URL="https://api.x.ai/v1"

مرحله ۵: دسترسی به فایل‌های ویندوز

WSL می‌تواند از طریق /mnt/c/ به سیستم فایل ویندوز شما دسترسی داشته باشد. پروژه‌های ویندوزی شما در این مسیر موجودند:

# رفتن به یک پوشه پروژه ویندوز
cd /mnt/c/Users/YourUsername/Projects/my-app

# لیست فایل‌ها
ls -la

برای عملکرد بهتر، repository‌ها را مستقیم در سیستم فایل WSL کلون کنید:

# پوشه native WSL (I/O بسیار سریع‌تر)
cd ~
mkdir projects
cd projects
git clone https://github.com/your-repo/my-app.git

مهم: عملیات فایل روی /mnt/c/ به‌طور قابل توجهی کندتر از سیستم فایل native WSL (~/) است. برای بهترین عملکرد Codex، در پوشه خانگی WSL کار کنید.

مرحله ۶: اجرای Codex

به پوشه پروژه بروید و Codex را شروع کنید:

cd ~/projects/my-app

# شروع Codex در حالت interactive
codex

# یا مستقیماً یک وظیفه بدهید
codex "Add error handling to all the API route handlers in this project"

حالت‌های استقلال Codex

Codex سه سطح استقلال دارد که کنترل می‌کنند چقدر می‌تواند بدون پرسیدن کار کند:

حالت	Flag	چه کاری می‌تواند انجام دهد
Suggest	`--suggest`	خواندن فایل‌ها، پیشنهاد تغییرات (پیش‌فرض)
Auto-edit	`--auto-edit`	خواندن فایل‌ها، اعمال تغییرات کد
Full auto	`--full-auto`	خواندن فایل‌ها، ویرایش کد، اجرای دستورات

# اجازه دادن به Codex برای ایجاد تغییرات کد به‌طور خودکار
codex --auto-edit "Refactor this Express app to use TypeScript"

# اجازه دادن به Codex برای اجرای دستورات هم (با احتیاط استفاده کنید)
codex --full-auto "Set up ESLint and Prettier for this project, install dependencies, and fix all linting errors"

مثال‌های عملی

رفع باگ از یک پیام خطا:

codex "I'm getting 'TypeError: Cannot read property of undefined' on line 42 of src/utils/parser.ts. Fix it."

اضافه کردن تست برای کد موجود:

codex "Write unit tests for all functions in src/services/auth.ts using Jest"

بازنویسی یک کامپوننت:

codex "Convert the UserProfile class component in src/components/UserProfile.jsx to a functional component with hooks"

رفع مشکلات رایج

«codex: command not found»

مطمئن شوید پوشه npm global bin در PATH شما است:

# بررسی محل نصب پکیج‌های global توسط npm
npm config get prefix

# اگر لازم است به PATH اضافه کنید
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc

دسترسی کند به فایل‌ها

اگر Codex هنگام کار با فایل‌ها روی /mnt/c/ کند است، پروژه را به سیستم فایل WSL منتقل کنید:

cp -r /mnt/c/Users/YourUsername/Projects/my-app ~/projects/my-app
cd ~/projects/my-app

مصرف حافظه WSL

WSL2 می‌تواند حافظه زیادی مصرف کند. یک فایل .wslconfig در پوشه خانگی ویندوز بسازید تا آن را محدود کنید:

# C:\Users\YourUsername\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB

بعد از تغییر پیکربندی WSL را restart کنید:

# در PowerShell
wsl --shutdown

مشکلات شبکه (شکست فراخوانی‌های API)

اگر Codex نمی‌تواند به OpenAI API برسد، تنظیمات DNS در WSL را بررسی کنید:

# بررسی کارکرد DNS resolution
nslookup api.openai.com

# اگر شکست خورد، DNS را رفع کنید
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo bash -c 'echo "[network]\ngenerateResolvConf = false" > /etc/wsl.conf'

برنامه‌های GUI و clipboard

برای کپی خروجی Codex به clipboard ویندوز:

# pipe کردن خروجی به clipboard ویندوز
codex "explain this function" | clip.exe

# یا نصب xclip برای clipboard دو طرفه
sudo apt install -y xclip

یکپارچگی با VS Code

برای بهترین تجربه، از VS Code با افزونه WSL استفاده کنید:

افزونه «WSL» را در VS Code نصب کنید
پروژه WSL خود را با code . از ترمینال WSL باز کنید
ترمینال یکپارچه VS Code به‌طور خودکار از WSL استفاده می‌کند
Codex را مستقیم در ترمینال VS Code اجرا کنید

# از پوشه پروژه WSL شما
code .

# سپس در ترمینال VS Code (که اکنون WSL است)
codex "Add a README with setup instructions for this project"

Codex در مقابل سایر ابزارهای کدنویسی هوش مصنوعی

ویژگی	Codex CLI	Claude Code	Cursor	GitHub Copilot
رابط	ترمینال	ترمینال	IDE	IDE
ویرایش فایل	بله	بله	بله	فقط پیشنهاد
اجرای دستور	بله	بله	محدود	خیر
پشتیبانی WSL	از طریق WSL	از طریق WSL	Native	Native
متن‌باز	بله	خیر	خیر	خیر
انعطاف مدل	هر سازگار با OpenAI	فقط Claude	چندگانه	مبتنی بر GPT
حالت آفلاین	خیر (نیاز به API)	خیر	خیر	خیر
قیمت	فقط هزینه API	اشتراک Claude	$20+/ماه	$10+/ماه

جمع‌بندی

اجرای Codex روی ویندوز از طریق WSL همان تجربه کاربران macOS و Linux را می‌دهد. راه‌اندازی حدود ۱۵ دقیقه طول می‌کشد و یکپارچگی WSL2 به اندازه کافی بالغ است که تفاوت را به زحمت متوجه شوید. برای بهترین عملکرد، فایل‌های پروژه را در سیستم فایل WSL نگه دارید به جای دسترسی به drive‌های ویندوز.

اگر پروژه‌های شما شامل رسانه‌های تولیدشده با هوش مصنوعی کنار کد هستند، Hypereal AI را برای یک API یکپارچه که تولید تصویر، ویدیو، آواتار ناطق و بیشتر را مدیریت می‌کند بررسی کنید. برای توسعه‌دهندگان ایرانی، Hypereal بدون نگرانی از تحریم‌ها قابل دسترسی است.

Hypereal AI را رایگان امتحان کنید -- ۳۵ کردیت، بدون نیاز به کارت اعتباری.