نصب Codex CLI در ویندوز؛ راهنمای شروع امن و فرمان‌های کاربردی

اگر ترجیح می‌دهید عامل کدنویسی هوشمند را از همان جایی به کار بگیرید که Build، Test و Git را اجرا می‌کنید، Codex CLI یک مسیر مستقیم در اختیار شما می‌گذارد. این ابزار داخل ترمینال اجرا می‌شود، ساختار Repository را می‌خواند، درباره مسئله توضیح می‌دهد و در صورت اجازه شما می‌تواند فایل‌ها را ویرایش یا فرمان اجرا کند.

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

Codex CLI چیست و چه کاری انجام می‌دهد؟

Codex CLI عامل کدنویسی OpenAI برای محیط خط فرمان است. برخلاف یک چت عمومی، در متن پروژه محلی کار می‌کند و می‌تواند فایل‌های مرتبط را پیدا کند، ارتباط بخش‌های مختلف کد را توضیح دهد، Patch بسازد و آزمایش‌های پروژه را اجرا کند. نتیجه خوب زمانی به دست می‌آید که مسئله، محدوده تغییر و معیار پذیرش را روشن بیان کنید.

سه کاربرد روزمره آن عبارت‌اند از عیب‌یابی یک خطای مشخص، ایجاد تغییر محدود همراه با تست و بازبینی تغییرات پیش از Commit. برای پرسش‌هایی که فقط به توضیح نیاز دارند، Sandbox خواندنی انتخاب مناسبی است. وقتی ویرایش لازم است، دسترسی نوشتن را به همان Workspace محدود کنید.

پیش‌نیازهای نصب در ویندوز

پیش از نصب، ویندوز ۶۴ بیتی، یک ترمینال به‌روز و دسترسی عادی به اینترنت را آماده کنید. Git اجباری نیست، اما برای دیدن Diff و حفظ تاریخچه تغییرات توصیه می‌شود. اگر روش npm را انتخاب می‌کنید، نسخه پشتیبانی‌شده Node.js و npm نیز باید روی سیستم موجود باشد.

• PowerShell یا Windows Terminal را باز کنید.
• با git --version از در دسترس بودن Git مطمئن شوید.
• در روش npm، فرمان‌های node --version و npm --version را بررسی کنید.
• برای پروژه واقعی، ابتدا از پاک بودن وضعیت Git یا ثبت تغییرات فعلی مطمئن شوید.

اجرای ترمینال با دسترسی Administrator برای استفاده روزمره توصیه نمی‌شود. اگر نصب‌کننده برای مرحله‌ای مشخص به مجوز بالاتر نیاز داشت، فقط همان مرحله را با آگاهی اجرا کنید و نشست اصلی Codex را با حساب عادی ادامه دهید.

روش اول: نصب با اسکریپت رسمی PowerShell

README رسمی Codex برای ویندوز یک نصب‌کننده PowerShell ارائه می‌کند. چون الگوی دانلود و اجرای مستقیم اسکریپت، کد اینترنتی را بلافاصله اجرا می‌کند، در محیط سازمانی بهتر است ابتدا نشانی و محتوای اسکریپت را طبق سیاست تیم بررسی کنید. سپس فرمان رسمی را اجرا کنید:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"codex --versioncodex doctor

فرمان دوم نسخه نصب‌شده را نشان می‌دهد و codex doctor برای بررسی نصب، تنظیمات، احراز هویت، Git و محیط اجرا طراحی شده است. اگر ترمینال فرمان را پیدا نکرد، پیش از نصب دوباره یک پنجره تازه باز کنید تا PATH بازخوانی شود.

روش دوم: نصب Codex CLI با npm

اگر Node.js را از قبل برای توسعه وب دارید، نصب سراسری بسته رسمی مسیر آشنایی است. بسته را نصب کنید و سپس نسخه را بررسی کنید:

npm install -g @openai/codexcodex --versioncodex

وجود چند نصب هم‌زمان می‌تواند باعث شود PATH نسخه دیگری را اجرا کند. با Get-Command codex -All مسیر همه نسخه‌های قابل مشاهده را ببینید. سپس فقط یک روش نصب را نگه دارید و بعد از Update دوباره نسخه فعال را کنترل کنید.

نصب Native یا استفاده در WSL؟

نسخه Native برای شروع سریع در پروژه‌هایی که مسیر و ابزارهایشان ویندوزی است مناسب است. WSL وقتی ارزش بیشتری دارد که Build و وابستگی‌های اصلی پروژه در لینوکس اجرا می‌شوند. پوشه را میان دو محیط جابه‌جا نکنید؛ Codex، Git و ابزار Build باید همگی همان فایل‌ها را از یک محیط ببینند.

ورود با حساب ChatGPT و اولین اجرا

پس از اجرای codex گزینه ورود با ChatGPT را انتخاب کنید و جریان احراز هویت مرورگر را کامل کنید. طبق راهنمای رسمی، Codex در طرح‌های ChatGPT ارائه می‌شود و محدودیت استفاده به نوع طرح بستگی دارد. کلید یا توکن ورود را در فایل پروژه، اسکرین‌شات یا Prompt قرار ندهید.

1. در PowerShell به ریشه Repository بروید.
2. با git status وضعیت اولیه را ثبت کنید.
3. codex را اجرا و ورود را کامل کنید.
4. برای شروع فقط درخواست تحلیل بدهید: «ساختار پروژه را توضیح بده و هنوز هیچ فایلی را تغییر نده».
5. پس از شناخت مسیرها، یک تغییر کوچک با معیار پذیرش روشن درخواست کنید.

اجرای Codex از ریشه صحیح مهم است، زیرا Workspace مرز اصلی مشاهده و ویرایش فایل‌هاست. آن را از پوشه‌ای مانند ریشه درایو یا پوشه اسناد شخصی اجرا نکنید. یک Repository مشخص، محدوده‌ای قابل فهم و قابل بازبینی ایجاد می‌کند.

چگونه یک درخواست خوب بنویسیم؟

درخواست خوب چهار جزء دارد: هدف، محدوده، محدودیت و روش تأیید. به جای «پروژه را درست کن»، بنویسید «خطای اعتبارسنجی فرم ثبت‌نام را در پوشه مشخص بررسی کن؛ قرارداد API را تغییر نده؛ تست مرتبط را اضافه کن؛ سپس فقط فایل‌های تغییرکرده و نتیجه تست را گزارش بده».

نمونه سناریوی کم‌ریسک

برای نخستین کار واقعی، مسئله‌ای انتخاب کنید که نتیجه آن با تست یا Build قابل سنجش باشد. ابتدا از Codex بخواهید برنامه تغییر را بنویسد. بعد از تأیید برنامه، اجازه ویرایش محدود بدهید و در پایان git diff --check و تست هدفمند را اجرا کنید.

• فایل‌های مجاز برای تغییر را نام ببرید.
• بخش‌های ممنوع مانند Migration یا تنظیمات Production را صریح کنید.
• فرمان اعتبارسنجی را مشخص کنید.
• از عامل بخواهید فرض‌ها و موارد حل‌نشده را گزارش کند.

Sandbox و Approval را امن تنظیم کنید

Codex برای فرمان‌های تولیدشده سیاست Sandbox و Approval دارد. حالت‌های Sandbox شامل read-only، workspace-write و danger-full-access هستند. برای بررسی اولیه از read-only و برای تغییر کنترل‌شده از workspace-write استفاده کنید. دسترسی کامل فقط در محیط ایزوله و برای نیاز روشن قابل توجیه است.

در فایل تنظیمات می‌توانید توقف برای تأیید فرمان و سطح Sandbox را تعیین کنید. نمونه زیر یک نقطه شروع متعادل است:

approval_policy = "on-request"sandbox_mode = "workspace-write" [windows]sandbox = "elevated"

مقدار on-request به عامل اجازه می‌دهد هنگام نیاز به عملیات خارج از مرز فعلی درخواست تأیید کند. در ویندوز، مستندات رسمی حالت Sandbox بومی elevated را پیشنهاد می‌کنند و unelevated را برای زمانی می‌دانند که دسترسی مدیریتی یا راه‌اندازی elevated در دسترس نیست.

چه چیزهایی را نباید بی‌درنگ تأیید کرد؟

فرمان حذف بازگشتی، تغییر فایل‌های Secret، نصب ناشناخته، دسترسی به مسیر خارج Workspace، اجرای Script دانلودشده و تغییر تنظیمات Production نیازمند توقف و بررسی‌اند. نام فرمان را کافی ندانید؛ آرگومان‌ها، مسیر هدف و اثری را که بعد از اجرا باقی می‌ماند بخوانید.

فرمان‌های کاربردی Codex CLI

فرمان پایه codex رابط تعاملی را باز می‌کند. codex exec برای اجرای غیرتعاملی طراحی شده و می‌تواند خروجی ساختاریافته بدهد. codex review تغییرات را بازبینی می‌کند و codex resume نشست قبلی را ادامه می‌دهد. برای دیدن گزینه‌های همان نسخه از codex --help استفاده کنید، زیرا قابلیت‌ها همراه نسخه‌ها تکامل پیدا می‌کنند.

نمونه زیر یک اجرای خواندنی و محدود برای تحلیل پروژه است:

codex exec --sandbox read-only --cd . "مسیر اجرای اعتبارسنجی این پروژه را پیدا کن و هیچ فایلی را تغییر نده"codex reviewcodex resume --last

گزینه --cd ریشه Workspace را تعیین می‌کند و --sandbox read-only برای تحلیل بدون ویرایش مناسب است. در Automation از گزینه خطرناک عبور از Sandbox و Approval استفاده نکنید، مگر اینکه Runner واقعاً ایزوله، ورودی‌ها کنترل‌شده و اثرات قابل بازیابی باشند.

رفع خطاهای رایج نصب و اجرا

فرمان codex پیدا نمی‌شود

ترمینال را ببندید و دوباره باز کنید، سپس Get-Command codex -All را اجرا کنید. در نصب npm، مسیر global bin باید در PATH باشد. نصب‌های موازی را شناسایی کنید و به جای افزودن چند مسیر، روش نصب اصلی را مشخص نگه دارید.

ورود در مرورگر کامل نمی‌شود

زمان سیستم، Proxy و امکان باز شدن localhost را بررسی کنید. از کپی کردن فایل احراز هویت میان سیستم‌ها خودداری کنید. ابتدا codex doctor و سپس راهنمای رسمی ورود را بررسی کنید؛ اگر حساب سازمانی است، سیاست Workspace ممکن است روی روش ورود اثر بگذارد.

فرمان Build در Codex با ترمینال شما فرق دارد

احتمالاً PATH، Working Directory یا محیط Native و WSL متفاوت است. همان فرمان را در همان پوشه و همان Shell اجرا کنید. نسخه Runtimeها را به درخواست اضافه کنید و از Codex بخواهید قبل از نصب وابستگی جدید، علت تفاوت را گزارش کند.

چک‌لیست قبل از سپردن پروژه واقعی

1. Repository و شاخه درست را باز کرده‌اید.
2. تغییرات قبلی Commit شده یا دست‌کم با git status ثبت شده‌اند.
3. فایل‌های Secret و خروجی Build در Ignore قرار دارند.
4. Sandbox متناسب با کار انتخاب شده است.
5. مسیرهای خارج Workspace مجوز پیش‌فرض ندارند.
6. معیار پذیرش و فرمان تست مشخص است.
7. هر Diff را پیش از Commit می‌خوانید.
8. نتیجه تست عامل را با اجرای مستقل کنترل می‌کنید.

اگر پیش‌تر با عامل‌های ترمینالی دیگر کار کرده‌اید، راهنمای GitHub Copilot CLI و مقاله نصب و تنظیم مجوزهای OpenCode کمک می‌کنند تفاوت رویکردها را با معیارهای عملی مقایسه کنید.

جمع‌بندی

نصب Codex CLI در ویندوز چند دقیقه بیشتر زمان نمی‌برد، اما استفاده قابل اعتماد آن به مرزبندی درست وابسته است: ابزار را از Repository مشخص اجرا کنید، نخست تحلیل خواندنی بگیرید، برای ویرایش از workspace-write استفاده کنید، فرمان‌ها و Diff را بخوانید و نتیجه را با Build و Test مستقل بسنجید. عامل کدنویسی جایگزین کنترل نسخه و بازبینی نیست؛ ارزش آن زمانی بیشتر می‌شود که این کنترل‌ها از قبل در جریان کار شما حضور داشته باشند.

برای یادگیری پروژه‌محور ابزارهای برنامه‌نویسی و هوش مصنوعی، سرفصل‌های آموزشی خانه برنامه نویسان البرز را بررسی کنید و تمرین را با یک Repository آزمایشی آغاز کنید.

منابع رسمی

• مخزن رسمی Codex و روش‌های نصب
• مرجع رسمی فرمان‌های Codex CLI
• تنظیمات پایه Codex
• Sandbox ویندوز در Codex
• استفاده از Codex با طرح ChatGPT