شروع سریع Codex CLI (2026): راه‌اندازی در 5 دقیقه

Codex CLI را نصب کنید و در حدود 5 دقیقه آن را به QCode.cc متصل کنید: اسکریپت یک‌کلیکی یا پیکربندی دستی config.toml + auth.json، سپس نخستین کار. همان کلید Claude Code.

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

⚡ پیشنهادی: راه‌اندازی یک‌کلیکی — curl -fsSL https://qcode.cc/install/codex.sh | bash (ویندوز: irm https://qcode.cc/install/codex.ps1 | iex) CLI را نصب می‌کند، پیکربندی ~/.codex را می‌نویسد و اتصال را بررسی می‌کند. اسکریپت راه‌اندازی یک‌کلیکی را ببینید. برای راه‌اندازی دستی به خواندن ادامه دهید.

اگر از قبل از Claude Code استفاده می‌کنید، این راهنما شما را در 5 دقیقه با Codex CLI راه‌اندازی می‌کند. هر دو ابزار سهمیه پلن QCode.cc را مشترکاً مصرف می‌کنند و از یک کلید API یکسان استفاده می‌کنند؛ بنابراین پس از پیکربندی می‌توانید آزادانه بین آن‌ها جابه‌جا شوید.

اگر هنوز حساب کاربری QCode.cc ندارید، ابتدا یک پلن انتخاب کنید و کلید خود را بگیرید (کلید در هر گزینه‌ای که انتخاب کنید یکسان کار می‌کند).

پیش‌نیازها¶

پیش از شروع، مطمئن شوید محیط شما این الزامات را برآورده می‌کند:

توجه: سندباکس سطح هسته Codex بهترین عملکرد را روی Linux دارد. macOS و Windows WSL نیز کاملاً پشتیبانی می‌شوند، هرچند برخی قابلیت‌های سندباکس ممکن است محدود باشند.

گام 1: نصب Codex CLI¶

یکی از روش‌های نصب زیر را انتخاب کنید:

گزینه A: نصب سراسری با npm (پیشنهادی)¶

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)¶

brew install --cask codex

گزینه C: ساخت از سورس¶

git clone https://github.com/openai/codex.git
cd codex
cargo build --release
cp target/release/codex ~/.local/bin/

نصب را بررسی کنید:

codex --version
# should print a version (trust `codex --version` on this machine, not a stale number from the web)

گام 2: پیکربندی QCode.cc¶

2.1 ایجاد پوشه پیکربندی¶

mkdir -p ~/.codex

2.2 نوشتن config.toml¶

فایل ~/.codex/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

مرجع پیکربندی:

2.3 ایجاد auth.json¶

فایل ~/.codex/auth.json را ایجاد کنید:

{
  "OPENAI_API_KEY": "cr_your_key_here"
}

cr_your_key_here را با کلید API خود از داشبورد QCode.cc جایگزین کنید.

2.4 تنظیم متغیرهای محیطی¶

برای اینکه به‌جای آن کلید را از طریق یک متغیر محیطی منتقل کنید، requires_openai_auth = true را در [model_providers.qcode] با env_key = "QCODE_API_KEY" جایگزین کنید و آن متغیر را export کنید. از یکی از این دو روش استفاده کنید: مستندات رسمی بیان می‌کند که Codex وقتی requires_openai_auth = true است، env_key را نادیده می‌گیرد. پیکربندی کامل برای حالت استفاده از متغیر محیطی:

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"

سپس متغیر محیطی را تنظیم کنید:

# 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 استفاده می‌کنید، کلید را در همان محل در داشبورد پیدا می‌کنید.

گام 3: بررسی تنظیمات¶

برای آزمودن اتصال، یک وظیفه ساده اجرا کنید:

codex "print hello world"

اگر Codex به‌طور عادی اجرا شود و پاسخی برگرداند، پیکربندی موفق است.

فهرست بررسی¶

• Codex بدون خطا اجرا می‌شود
• درخواست‌های API از طریق QCode.cc مسیریابی می‌شوند (بدون خطاهای مهلت زمانی شبکه)
• پاسخ‌های مدل به‌درستی کار می‌کنند (دستورهای شما را می‌فهمد)

اگر با مشکلی روبه‌رو شدید، به بخش پرسش‌های متداول بروید.

گام 4: نخستین وظیفه واقعی شما¶

بیایید یک سناریوی عملی را امتحان کنیم تا ببینید Codex چه می‌تواند انجام دهد. به پوشه یک پروژه بروید:

cd /path/to/your/project

مثال 1: تحلیل ساختار پروژه¶

codex "Analyze this project's directory structure and tech stack, and give a brief overview"

مثال 2: تولید کد¶

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: تغییرات دسته‌ای¶

codex "Convert all .js files under src/ to .ts files and add type annotations"

Codex وظیفه را به‌صورت خودکار در یک محیط ایزوله تکمیل می‌کند و سپس خلاصه تغییرات را برای بررسی شما ارائه می‌دهد.

مجوزها و محیط ایزوله¶

Codex از دو گزینه برای کنترل کارهایی که می‌تواند انجام دهد (--sandbox) و زمان پرسش از شما (--ask-for-approval) استفاده می‌کند. جزئیات زیر از مستندات رسمی OpenAI گرفته شده است (به تاریخ 2026-10-15).

پیش‌فرض: فضای کاری قابل نوشتن، تأییدها در صورت درخواست¶

codex "Refactor the auth module"

• در یک مخزن Git، این همان پیش‌تنظیمی است که بدون هیچ گزینه‌ای دریافت می‌کنید: Codex فایل‌ها را می‌خواند، فایل‌ها را ویرایش می‌کند و فرمان‌ها را درون فضای کاری اجرا می‌کند، و پیش از نوشتن در بیرون آن یا استفاده از شبکه، ابتدا می‌پرسد
• مناسب برای: توسعه روزمره (پیش‌فرض توصیه‌شده)

فقط‌خواندنی: نگاه کنید اما تغییر ندهید¶

codex --sandbox read-only --ask-for-approval on-request "Analyze the auth module and suggest a refactor"

• محیط ایزوله فقط‌خواندنی -- هیچ فایلی را تغییر نمی‌دهد
• مناسب برای: یادگیری کد، ارزیابی رویکردها

غیرتعاملی و خودکارسازی¶

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 اعتماد کنید.

مرجع دستورها¶

مدل‌های موجود¶

مدل‌های زیر از طریق QCode.cc در دسترس هستند:

QCode در حال حاضر gpt-6-luna / gpt-5.6-luna را ارائه نمی‌دهد. لطفاً از مدل GPT دیگری استفاده کنید. QCode هزینه را به‌ازای هر توکن محاسبه می‌کند؛ نرخ هر مدل در 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:

# 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 مراجعه کنید.

استفاده از Codex همراه با Claude Code¶

از آنجا که هر دو ابزار از سهمیه QCode.cc استفاده می‌کنند، بهترین روش استفاده هم‌زمان از آن‌هاست:

# 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: مقایسه‌ای عمیق را ببینید.

گام‌های بعدی¶

پیکربندی کامل شد -- آماده‌اید استفاده از Codex را شروع کنید. مطالعه پیشنهادی:

• راهنمای پیکربندی AGENTS.md -- رفتار پروژه را در Codex سفارشی کنید
• Codex در برابر Claude Code: مقایسه‌ای عمیق -- تفاوت‌ها و روش ترکیب این دو را بشناسید
• پیکربندی یکپارچه‌سازی Codex -- مرجع کامل پیکربندی (شامل مراحل تفصیلی Windows و چند سیستم‌عامل)
• نکات و ترفندهای CLI -- نکته‌های افزایش بهره‌وری برای کدنویسی با هوش مصنوعی

پرسش‌های متداول¶

پرسش: نصب با npm ERR! EACCES شکست می‌خورد¶

علت: نداشتن دسترسی کافی به پوشه نصب سراسری npm.

راه‌حل:

# 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 بررسی کنید
4. نحو TOML و نام ارائه‌دهنده را در config.toml بررسی کنید

پرسش: اتمام زمان اتصال یا خطای شبکه¶

مراحل عیب‌یابی:

1. تأیید کنید که base_url روی https://api.qcode.cc/openai تنظیم شده است
2. اتصال شبکه را آزمایش کنید: curl -I https://api.qcode.cc

3. اگر نقطه پایانی فعلی در دسترس نیست، نقطه پایانی دیگری را امتحان کنید:

4. نقطه پایانی آسیا: https://asia.qcode.cc/openai

پرسش: آیا کلید Codex همان کلید Claude Code است؟¶

بله. هر دو از همان کلید API در QCode.cc با سهمیه مشترک استفاده می‌کنند. به کلید جداگانه نیازی ندارید.

پرسش: آیا روی Windows کار می‌کند؟¶

بله، اما استفاده از WSL (Windows Subsystem for Linux) را توصیه می‌کنیم. پشتیبانی بومی از Windows نیز در حال بهبود است. برای مراحل تفصیلی راه‌اندازی در Windows، پیکربندی یکپارچه‌سازی Codex را ببینید.

سازمانی ←