# شروع سریع Codex > ⚡ **پیشنهادی: راه‌اندازی یک‌کلیکی** — `curl -fsSL https://qcode.cc/install/codex.sh | bash` (ویندوز: `irm https://qcode.cc/install/codex.ps1 | iex`) CLI را نصب می‌کند، پیکربندی `~/.codex` را می‌نویسد و اتصال را بررسی می‌کند. [اسکریپت راه‌اندازی یک‌کلیکی](/docs/getting-started/one-click-install) را ببینید. برای راه‌اندازی دستی به خواندن ادامه دهید. اگر از قبل از Claude Code استفاده می‌کنید، این راهنما شما را در **5 دقیقه** با Codex CLI راه‌اندازی می‌کند. هر دو ابزار سهمیه پلن QCode.cc را مشترکاً مصرف می‌کنند و از یک کلید API یکسان استفاده می‌کنند؛ بنابراین پس از پیکربندی می‌توانید آزادانه بین آن‌ها جابه‌جا شوید. اگر هنوز حساب کاربری QCode.cc ندارید، ابتدا [یک پلن انتخاب کنید و کلید خود را بگیرید](/docs/getting-started/choose-a-plan) (کلید در هر گزینه‌ای که انتخاب کنید یکسان کار می‌کند). --- ## پیش‌نیازها پیش از شروع، مطمئن شوید محیط شما این الزامات را برآورده می‌کند: | نیازمندی | نسخه | نحوه بررسی | |-------------|---------|-------------| | Node.js | v22 یا جدیدتر | `node --version` | | npm | v10 یا جدیدتر | `npm --version` | | Git | هر نسخه‌ای | `git --version` | | سیستم‌عامل | macOS / Linux / Windows (WSL) | - | | کلید QCode.cc | کلید API که با `cr_` شروع می‌شود | [داشبورد](https://qcode.cc/dashboard) | > **توجه**: سندباکس سطح هسته Codex بهترین عملکرد را روی Linux دارد. macOS و Windows WSL نیز کاملاً پشتیبانی می‌شوند، هرچند برخی قابلیت‌های سندباکس ممکن است محدود باشند. --- ## گام 1: نصب Codex CLI یکی از روش‌های نصب زیر را انتخاب کنید: ### گزینه A: نصب سراسری با npm (پیشنهادی) ```bash npm install -g @openai/codex # Users in China can speed this up with the Taobao mirror npm install -g @openai/codex --registry=https://registry.npmmirror.com ``` ### گزینه B: Homebrew (macOS) ```bash brew install --cask codex ``` ### گزینه C: ساخت از سورس ```bash git clone https://github.com/openai/codex.git cd codex cargo build --release cp target/release/codex ~/.local/bin/ ``` نصب را بررسی کنید: ```bash codex --version # should print a version (trust `codex --version` on this machine, not a stale number from the web) ``` --- ## گام 2: پیکربندی QCode.cc ### 2.1 ایجاد پوشه پیکربندی ```bash mkdir -p ~/.codex ``` ### 2.2 نوشتن config.toml فایل `~/.codex/config.toml` را ایجاد کنید: ```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 ``` مرجع پیکربندی: | فیلد | توضیح | |-------|-------------| | `model_provider` | از ارائه‌دهنده سفارشی `qcode` استفاده کنید (نام به خود شما بستگی دارد، تا زمانی که با `[model_providers.]` مطابقت داشته باشد) | | `model` | مدل پیش‌فرض، `gpt-6.1-sol` توصیه می‌شود؛ «مدل‌های موجود» را در ادامه ببینید | | `model_reasoning_effort` | عمق استدلال، مانند `low` / `medium` / `high`؛ سطوح موجود به مدل بستگی دارد | | `base_url` | نقطه پایانی جهانی QCode.cc (`api.qcode.cc`؛ سرزمین اصلی چین می‌تواند از `asia.qcode.cc` استفاده کند، آمریکای شمالی / اروپا از `us.qcode.cc`) | | `wire_api` | پروتکل API؛ روی `responses` تنظیم کنید | | `requires_openai_auth` | از احراز هویت به سبک OpenAI استفاده کنید؛ کلید از `OPENAI_API_KEY` در `~/.codex/auth.json` خوانده می‌شود. وقتی روی `true` تنظیم شود، Codex مقدار `env_key` را نادیده می‌گیرد (مستندات رسمی) | ### 2.3 ایجاد auth.json فایل `~/.codex/auth.json` را ایجاد کنید: ```json { "OPENAI_API_KEY": "cr_your_key_here" } ``` > `cr_your_key_here` را با کلید API خود از [داشبورد QCode.cc](https://qcode.cc/dashboard) جایگزین کنید. ### 2.4 تنظیم متغیرهای محیطی برای اینکه به‌جای آن کلید را از طریق یک متغیر محیطی منتقل کنید، `requires_openai_auth = true` را در `[model_providers.qcode]` با `env_key = "QCODE_API_KEY"` جایگزین کنید و آن متغیر را export کنید. **از یکی از این دو روش استفاده کنید**: مستندات رسمی بیان می‌کند که Codex وقتی `requires_openai_auth = true` است، `env_key` را نادیده می‌گیرد. پیکربندی کامل برای حالت استفاده از متغیر محیطی: ```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" env_key = "QCODE_API_KEY" ``` سپس متغیر محیطی را تنظیم کنید: ```bash # Temporary (current terminal session only) export QCODE_API_KEY="cr_your_key_here" # Permanent (Bash users) echo 'export QCODE_API_KEY="cr_your_key_here"' >> ~/.bashrc source ~/.bashrc # Permanent (Zsh users) echo 'export QCODE_API_KEY="cr_your_key_here"' >> ~/.zshrc source ~/.zshrc ``` > **نکته**: این همان کلیدی است که برای Claude Code استفاده می‌کنید. اگر از قبل از Claude Code استفاده می‌کنید، کلید را در همان محل در [داشبورد](https://qcode.cc/dashboard) پیدا می‌کنید. --- ## گام 3: بررسی تنظیمات برای آزمودن اتصال، یک وظیفه ساده اجرا کنید: ```bash codex "print hello world" ``` اگر Codex به‌طور عادی اجرا شود و پاسخی برگرداند، پیکربندی موفق است. ### فهرست بررسی - Codex بدون خطا اجرا می‌شود - درخواست‌های API از طریق QCode.cc مسیریابی می‌شوند (بدون خطاهای مهلت زمانی شبکه) - پاسخ‌های مدل به‌درستی کار می‌کنند (دستورهای شما را می‌فهمد) اگر با مشکلی روبه‌رو شدید، به بخش [پرسش‌های متداول](#faq) بروید. --- ## گام 4: نخستین وظیفه واقعی شما بیایید یک سناریوی عملی را امتحان کنیم تا ببینید Codex چه می‌تواند انجام دهد. به پوشه یک پروژه بروید: ```bash cd /path/to/your/project ``` ### مثال 1: تحلیل ساختار پروژه ```bash codex "Analyze this project's directory structure and tech stack, and give a brief overview" ``` ### مثال 2: تولید کد ```bash codex "Create a utils/date-formatter.ts file with these features: 1. Format a date as YYYY-MM-DD 2. Calculate the number of days between two dates 3. Determine whether a date is a business day 4. Add complete JSDoc comments and unit tests for each function" ``` ### مثال 3: تغییرات دسته‌ای ```bash codex "Convert all .js files under src/ to .ts files and add type annotations" ``` Codex وظیفه را به‌صورت خودکار در یک محیط ایزوله تکمیل می‌کند و سپس خلاصه تغییرات را برای بررسی شما ارائه می‌دهد. --- ## مجوزها و محیط ایزوله Codex از دو گزینه برای کنترل کارهایی که می‌تواند انجام دهد (`--sandbox`) و زمان پرسش از شما (`--ask-for-approval`) استفاده می‌کند. جزئیات زیر از مستندات رسمی OpenAI گرفته شده است (به تاریخ 2026-10-15). ### پیش‌فرض: فضای کاری قابل نوشتن، تأییدها در صورت درخواست ```bash codex "Refactor the auth module" ``` - در یک مخزن Git، این همان پیش‌تنظیمی است که بدون هیچ گزینه‌ای دریافت می‌کنید: Codex فایل‌ها را می‌خواند، فایل‌ها را ویرایش می‌کند و فرمان‌ها را درون فضای کاری اجرا می‌کند، و پیش از نوشتن در بیرون آن یا استفاده از شبکه، ابتدا می‌پرسد - مناسب برای: توسعه روزمره (پیش‌فرض توصیه‌شده) ### فقط‌خواندنی: نگاه کنید اما تغییر ندهید ```bash codex --sandbox read-only --ask-for-approval on-request "Analyze the auth module and suggest a refactor" ``` - محیط ایزوله فقط‌خواندنی -- **هیچ فایلی را تغییر نمی‌دهد** - مناسب برای: یادگیری کد، ارزیابی رویکردها ### غیرتعاملی و خودکارسازی ```bash codex exec --sandbox workspace-write "Run tests and fix all failures" ``` - `codex exec` به‌صورت غیرتعاملی اجرا می‌شود و نتایج را در خروجی استاندارد چاپ می‌کند (یا با `--json` به‌صورت JSONL) - محیط ایزوله به فضای کاری محدود است و بر سیستم بیرون از آن اثری نمی‌گذارد - مناسب برای: یکپارچه‌سازی CI/CD، وظایف دسته‌ای > می‌توانید پیش‌فرض‌ها را در `config.toml` نیز تنظیم کنید: `approval_policy = "on-request"` و `sandbox_mode = "workspace-write"`. شکل‌های `--suggest`، `--auto-edit` و `approval_mode` از آموزش‌های قدیمی‌تر در فهرست گزینه‌های رسمی فعلی وجود ندارند؛ در صورت تردید، به `codex --help` اعتماد کنید. --- ## مرجع دستورها | دستور | توضیح | |---------|-------------| | `codex "your instruction"` | شروع Codex با یک دستورالعمل اولیه | | `codex exec "instruction"` | اجرا به‌صورت غیرتعاملی، سپس خروج | | `codex --model gpt-6.1-sol` | تعیین مدل | | `codex --sandbox workspace-write "instruction"` | فضای کاری قابل نوشتن | | `codex --sandbox read-only "instruction"` | فقط‌خواندنی، بدون تغییر فایل | | `codex --version` | نمایش نسخه | | `codex --help` | نمایش راهنما | ### مدل‌های موجود مدل‌های زیر از طریق QCode.cc در دسترس هستند: | مدل | توضیح | پیشنهادی برای | |-------|-------------|-----------------| | `gpt-6.1-sol` | به‌روزرسانی GPT-6 Sol (2026-09-29)، پنجره زمینه 1.05M، ورودی کش‌شده ارزان‌تر | کارهای عمومی / پیچیده (پیشنهادی ★؛ مستندات رسمی OpenAI Codex برای کدنویسی پیچیده GPT-6.1 Sol را توصیه می‌کند) | | `gpt-6.1-terra` | GPT-6.1 میان‌رده، قیمت واحد حدوداً نصف `gpt-6.1-sol` (به /models مراجعه کنید) | کدنویسی روزمره / کارهای دسته‌ای | | `gpt-6-sol` | پرچمدار GPT-6، پنجره زمینه 1.05M | کارهای عمومی / پیچیده | | `gpt-6-astra` | قوی‌ترین رده، قیمت ممتاز | بالاترین توانمندی | | `gpt-5.6-terra` | پرچمدار GPT-5.6 | کدنویسی / کارهای پیچیده | | `gpt-5.6-sol` | خانواده پرچمدار GPT-5.6 | توانمندی رده بالا | > QCode در حال حاضر gpt-6-luna / gpt-5.6-luna را ارائه نمی‌دهد. لطفاً از مدل GPT دیگری استفاده کنید. QCode هزینه را به‌ازای هر توکن محاسبه می‌کند؛ نرخ هر مدل در [qcode.cc/models](https://qcode.cc/models) است. > **gpt-6.1-sol در منوی `/model` نیست؟** با پیکربندی بالا، منوی `/model` در Codex فهرست مدل‌های تعبیه‌شده در کلاینت را نشان می‌دهد، بنابراین به نسخه Codex شما بستگی دارد: gpt-6.1-sol از Codex 0.160.0 به بعد در منو ظاهر می‌شود. به آخرین انتشار به‌روزرسانی کنید (`npm install -g @openai/codex@latest`، یا با Homebrew از `brew upgrade --cask codex` استفاده کنید). بدون به‌روزرسانی هم کار می‌کند: `model = "gpt-6.1-sol"` در `config.toml` (یا `codex --model gpt-6.1-sol`) به منو وابسته نیست. در مقابل، ممکن است gpt-6-luna در منو ظاهر شود، اما QCode در حال حاضر آن را ارائه نمی‌دهد و انتخاب آن خطا برمی‌گرداند. --- ## پیکربندی پروژه: AGENTS.md برای تعیین نحوه رفتار Codex در آن پروژه، یک فایل `AGENTS.md` در ریشه پروژه خود ایجاد کنید — مشابه `CLAUDE.md` در Claude Code: ```markdown # AGENTS.md - Use TypeScript strict mode - Code style follows ESLint + Prettier - Test framework: Vitest - Run `npm run lint && npm test` before committing - Component files use PascalCase naming ``` > برای پیکربندی دقیق، به [راهنمای پیکربندی AGENTS.md](/docs/usage/agents-md) مراجعه کنید. --- ## استفاده از Codex همراه با Claude Code از آنجا که هر دو ابزار از سهمیه QCode.cc استفاده می‌کنند، بهترین روش استفاده هم‌زمان از آن‌هاست: ```bash # Terminal 1: Use Claude Code to analyze the problem $ claude > Where's the performance bottleneck? Help me analyze the approach. # Terminal 2: Use Codex for batch execution $ codex "Optimize all database queries under src/api/ according to this plan: 1. Add query caching 2. Fix N+1 queries 3. Add index suggestion comments" ``` > برای الگوهای ترکیبی بیشتر، [Codex در برابر Claude Code: مقایسه‌ای عمیق](/docs/getting-started/codex-vs-claude-code) را ببینید. --- ## گام‌های بعدی پیکربندی کامل شد -- آماده‌اید استفاده از Codex را شروع کنید. مطالعه پیشنهادی: - [راهنمای پیکربندی AGENTS.md](/docs/usage/agents-md) -- رفتار پروژه را در Codex سفارشی کنید - [Codex در برابر Claude Code: مقایسه‌ای عمیق](/docs/getting-started/codex-vs-claude-code) -- تفاوت‌ها و روش ترکیب این دو را بشناسید - [پیکربندی یکپارچه‌سازی Codex](/docs/ide/codex) -- مرجع کامل پیکربندی (شامل مراحل تفصیلی Windows و چند سیستم‌عامل) - [نکات و ترفندهای CLI](/docs/usage/cli-tips) -- نکته‌های افزایش بهره‌وری برای کدنویسی با هوش مصنوعی --- ## پرسش‌های متداول ### پرسش: نصب با `npm ERR! EACCES` شکست می‌خورد **علت**: نداشتن دسترسی کافی به پوشه نصب سراسری npm. **راه‌حل**: ```bash # Option A: Use sudo (not recommended long-term) sudo npm install -g @openai/codex # Option B: Configure npm to use a user directory (recommended) mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm install -g @openai/codex ``` ### پرسش: پیام `API key not found` یا خطای احراز هویت دریافت می‌کنید **مراحل عیب‌یابی**: 1. تأیید کنید که کلید در `~/.codex/auth.json` با `cr_` شروع می‌شود 2. اگر از نسخه متغیر محیطی استفاده می‌کنید، تأیید کنید که ارائه‌دهنده دارای `env_key = "QCODE_API_KEY"` است (و `requires_openai_auth = true` ندارد) و اینکه متغیر export شده است: `echo $QCODE_API_KEY` 3. تأیید کنید که کلید منقضی نشده است: آن را در [داشبورد QCode.cc](https://qcode.cc/dashboard) بررسی کنید 4. نحو TOML و نام ارائه‌دهنده را در `config.toml` بررسی کنید ### پرسش: اتمام زمان اتصال یا خطای شبکه **مراحل عیب‌یابی**: 1. تأیید کنید که `base_url` روی `https://api.qcode.cc/openai` تنظیم شده است 2. اتصال شبکه را آزمایش کنید: `curl -I https://api.qcode.cc` 3. اگر نقطه پایانی فعلی در دسترس نیست، نقطه پایانی دیگری را امتحان کنید: - نقطه پایانی آسیا: `https://asia.qcode.cc/openai` ### پرسش: آیا کلید Codex همان کلید Claude Code است؟ **بله**. هر دو از همان کلید API در QCode.cc با سهمیه مشترک استفاده می‌کنند. به کلید جداگانه نیازی ندارید. ### پرسش: آیا روی Windows کار می‌کند؟ **بله**، اما استفاده از WSL (Windows Subsystem for Linux) را توصیه می‌کنیم. پشتیبانی بومی از Windows نیز در حال بهبود است. برای مراحل تفصیلی راه‌اندازی در Windows، [پیکربندی یکپارچه‌سازی Codex](/docs/ide/codex) را ببینید.