Codex CLI 0.167.0: نصب و config.toml

Codex CLI 0.167.0 (2026-11-06): آن را نصب کنید، QCode.cc را از طریق ~/.codex/config.toml و auth.json متصل کنید، سپس از AGENTS.md، تأییدها، پروفایل‌ها و MCP استفاده کنید.

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

آخرین بررسی: 2026-11-09 · 📄 بر اساس مستندات رسمی (آخرین نسخه پایدار Codex CLI v0.167.0، منتشرشده در 2026-11-06؛ کلیدهای پیکربندی، تغییرات فرمان در 0.164.0 و نصب آخرین بار در 2026-10-26 دوباره بررسی شدند) · رفتار پروفایل در 5.4 نیز به‌صورت محلی آزمایش شد (✅ codex-cli 0.155.0، HOME مجزا، هیچ درخواستی به مدل ارسال نشد)

در یک نگاه¶

📖 چرا base_url در Codex با ANTHROPIC_BASE_URL در Claude تفاوت دارد؟ تفاوت /openai و /openai/v1 چیست؟ نقاط پایانی و مسیرهای API را ببینید.

این یک آموزش کامل Codex CLI برای توسعه‌دهندگان چینی است که شما را از صفر تا نصب، پیکربندی و استفاده از OpenAI Codex CLI با مدل‌های GPT از طریق کلید API QCode.cc خود همراهی می‌کند. اگر برای نخستین بار با ابزارهای برنامه‌نویسی با هوش مصنوعی آشنا می‌شوید یا از قبل از Claude Code استفاده می‌کنید و می‌خواهید ابزارهای جدید را امتحان کنید، این آموزش برای شما مناسب است.

1. معرفی Codex¶

OpenAI Codex CLI چیست؟¶

Codex CLI یک دستیار برنامه‌نویسی با هوش مصنوعی و متن‌باز برای خط فرمان (مجوز Apache 2.0) است که OpenAI آن را عرضه کرده، با Rust نوشته شده و می‌تواند مستقیماً در ترمینال اجرا شود. این ابزار می‌تواند:

• مخزن کد شما را بخواند و درک کند
• فایل‌ها را ویرایش کند و کد جدید تولید کند
• فرمان‌ها را اجرا کند (مانند اجرای تست‌ها، نصب وابستگی‌ها)
• به‌صورت خودمختار تکرار کند تا وظیفه کامل شود

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

تاریخچه توسعه Codex¶

نام «Codex» در سبد محصولات OpenAI چندین تحول را پشت سر گذاشته است:

• 2021: نخستین Codex نسخه‌ای از GPT-3 بود که روی کد ریزتنظیم شده بود و نیروی محرکه GitHub Copilot بود
• 2024: OpenAI برند Codex را دوباره فعال کرد و یک عامل کدنویسی با هوش مصنوعیِ ناهمگام و ابری عرضه کرد
• 2025-2026: Codex CLI به یک ابزار محلی بالغ خط فرمان تبدیل شد، با Rust بازنویسی شد و از ویژگی‌های پیشرفته‌ای مانند MCP، Skills و Multi-Agent پشتیبانی کرد

Codex کنونی محصولی با چند رابط کاربری است: ابزار خط فرمان CLI (تمرکز این مقاله)، اپلیکیشن دسکتاپ macOS، افزونه‌های IDE و عامل‌های ابری یکپارچه‌شده با ChatGPT. نسخه‌ای که از طریق QCode.cc استفاده می‌شود، نسخه CLI است.

تفاوت‌های اصلی Codex و Claude Code¶

به‌زبان ساده: Codex در «وظایف بدون نیاز به دخالت» مهارت دارد (یک نیازمندی روشن بدهید و بگذارید کار را تا انتها پیش ببرد)، Claude Code در «برنامه‌نویسی زوجی» مهارت دارد (هنگام کاوش، بحث و ویرایش کنید، مناسب وظایف اکتشافی). استفاده هم‌زمان از هر دو بهترین نتیجه را می‌دهد.

چرا از Codex از طریق QCode.cc استفاده کنیم؟¶

Codex CLI به‌طور پیش‌فرض به یک کلید API OpenAI یا اشتراک ChatGPT نیاز دارد و در سرزمین اصلی چین، API OpenAI به‌طور مستقیم قابل دسترسی نیست.

از طریق QCode.cc می‌توانید:

• Claude، GPT و مدل‌های چینی رایج را با یک کلید فراخوانی کنید: Codex از مدل‌های GPT استفاده می‌کند، Claude Code از Claude استفاده می‌کند و هر دو از همان کلید API QCode استفاده می‌کنند
• از چندین نقطه پایانی استفاده کنید: api.qcode.cc نقطه ورود جهانی است، us.qcode.cc به آمریکای شمالی و اروپا سرویس می‌دهد، asia.qcode.cc به آسیا سرویس می‌دهد و کاربران در سرزمین اصلی چین باید asia.qcode.cc را ترجیح دهند؛ نیازی به پروکسی خودساخته نیست
• به‌ازای هر توکن پرداخت کنید، با نرخ‌های هر مدل در qcode.cc/models
• Claude Code و Codex سهمیه پلن را به اشتراک می‌گذارند، بنابراین یک پلن برای هر دو ابزار کار می‌کند

2. نصب Codex CLI¶

پیش‌نیازهای سیستم¶

پیش از نصب، لطفاً بررسی کنید که محیط شما شرایط زیر را دارد:

• سیستم‌عامل: macOS 12+، Ubuntu 20.04+، Windows 10+ (WSL2 توصیه می‌شود)
• Node.js: v22 LTS یا بالاتر (برای نصب npm لازم است)
• Git: 2.x یا بالاتر (Codex برای شناسایی مخزن کد به Git نیاز دارد)
• فضای دیسک: حدود 200MB (شامل وابستگی‌های npm)

روش 1: نصب با npm (توصیه‌شده)¶

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

npm install -g @openai/codex

نکته: اگر با مشکل مجوز مواجه شدید، کاربران macOS/Linux می‌توانند sudo را اضافه کنند یا برای مدیریت Node.js از nvm استفاده کنند تا از مشکل مجوز جلوگیری شود.

کاربران چینی: اگر دانلود npm کند است، می‌توانید از میرور Taobao استفاده کنید: bash npm install -g @openai/codex --registry=https://registry.npmmirror.com

روش 2: نصب با Homebrew (macOS)¶

کاربران macOS می‌توانند از طریق Homebrew نیز نصب کنند:

brew install --cask codex

مزیت Homebrew مدیریت خودکار وابستگی‌ها و به‌روزرسانی‌هاست.

روش 3: دانلود مستقیم باینری (پیشرفته)¶

باینری‌های از پیش کامپایل‌شده برای پلتفرم خود را از صفحه GitHub Releases دانلود کنید و در پوشه PATH قرار دهید. این روش به Node.js وابسته نیست. تا تاریخ 2026-11-09، آخرین نسخه پایدار v0.167.0 است (منتشرشده در 2026-11-06)؛ در بررسی 2026-10-15، نسخه v0.162.1 (منتشرشده در 2026-10-09) بررسی شد. فایل‌های ارائه‌شده بر اساس پلتفرم نام‌گذاری می‌شوند: برای مثال codex-x86_64-unknown-linux-musl.tar.gz برای Linux x64، codex-aarch64-apple-darwin.tar.gz برای macOS با پردازنده Apple silicon، و codex-x86_64-pc-windows-msvc.exe برای Windows x64.

# Example: download and install the Linux x64 build
curl -fsSLO https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

روش 4: اسکریپت نصب رسمی (macOS / Linux)¶

مستندات رسمی OpenAI Codex (تا تاریخ 2026-10-26) نیز یک نصب‌کننده مستقل ارائه می‌دهد:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

نصب را با codex --version تأیید کنید.

بررسی نصب¶

codex --version

اگر شماره نسخه را مشاهده کردید، نصب موفق بوده است. عددی را که در این صفحه می‌بینید «آخرین نسخه فعلی» در نظر نگیرید — از GitHub Releases و npm @openai/codex استفاده کنید و با codex --version ماشین را بررسی کنید.

پیکربندی تکمیل خودکار پوسته (اختیاری)¶

Codex از تکمیل خودکار پوسته پشتیبانی می‌کند؛ هنگام وارد کردن دستورها برای دریافت پیشنهادها Tab را فشار دهید:

# Zsh users
echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash users
echo 'eval "$(codex completion bash)"' >> ~/.bashrc
source ~/.bashrc

اگر Zsh پیام command not found: compdef را نمایش داد، autoload -Uz compinit && compinit را پیش از eval اضافه کنید.

3. پیکربندی QCode.cc¶

Codex CLI برای اتصال به سرویس QCode.cc نیاز به پیکربندی دو فایل دارد:

• ~/.codex/config.toml — نقطه پایانی سرور و پیکربندی مدل
• ~/.codex/auth.json — احراز هویت با کلید API

گام 1: ایجاد پوشه پیکربندی¶

mkdir $HOME\.codex

mkdir -p ~/.codex

mkdir -p ~/.codex

گام 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

جزئیات فیلدهای config.toml:

گام 3: ایجاد auth.json¶

محتوای زیر را در ~/.codex/auth.json بنویسید:

{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}

cr_xxxxxxxxxx را با کلید API QCode.cc خود جایگزین کنید. کلید با cr_ شروع می‌شود.

نکات auth.json:

• این فایل کلید API را در اختیار Codex قرار می‌دهد (با requires_openai_auth = true، Codex مقدار OPENAI_API_KEY را از آن می‌خواند)
• دسترسی‌های فایل به‌صورت 600 توصیه می‌شود (فقط مالک بتواند بخواند/بنویسد): chmod 600 ~/.codex/auth.json

گام 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 setting (current session)
$env:QCODE_API_KEY = "cr_xxxxxxxxxx"

# Permanent setting (write to user environment variable)
[System.Environment]::SetEnvironmentVariable("QCODE_API_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)

# Temporary setting
export QCODE_API_KEY="cr_xxxxxxxxxx"

# Permanent setting
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# Temporary setting
export QCODE_API_KEY="cr_xxxxxxxxxx"

# Permanent setting (Bash)
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# Permanent setting (Zsh)
echo 'export QCODE_API_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

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

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

QCode در حال حاضر gpt-6-luna / gpt-5.6-luna را ارائه نمی‌دهد. لطفاً از مدل GPT دیگری استفاده کنید (gpt-6.1-sol / gpt-6.1-terra / gpt-6-sol / gpt-5.6-terra).

Claude Code و Codex از همان کلید API QCode استفاده می‌کنند و تغییر مدل‌ها به تنظیمات اضافی نیاز ندارد. QCode بر اساس توکن صورت‌حساب می‌کند؛ نرخ‌های هر مدل در qcode.cc/models است.

4. آموزش استفاده پایه¶

4.1 اجرای Codex¶

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

cd /path/to/your/project
codex

Codex یک رابط تعاملی ترمینال (TUI) اجرا می‌کند که در آن می‌توانید دستورهای زبان طبیعی را وارد کنید. این رابط شامل موارد زیر است:

• نوار وضعیت بالا: مدل جاری، حالت تأیید و وضعیت محیط ایزوله را نشان می‌دهد
• ناحیه اصلی: پاسخ‌های هوش مصنوعی و گزارش‌های عملیات
• کادر ورودی پایین: جایی که دستورها را وارد می‌کنید

همچنین می‌توانید وظایف را مستقیماً در خط فرمان (حالت غیرتعاملی) بدهید که برای فراخوانی از اسکریپت مناسب است:

# Interactive launch
codex

# Non-interactive mode: execute single task then exit
codex "Read this project's structure and give me an overview"

# Task with image
codex -i screenshot.png "Fix the UI issue shown in the screenshot"

# Specify model
codex -m gpt-6-sol "Refactor the error handling in the authentication module"

4.2 اولین وظیفه: از Codex بخواهید یک تابع بنویسد¶

بیایید با یک مثال ساده شروع کنیم. Codex را در پوشه پروژه خود اجرا کنید و وارد کنید:

Write a Python function that accepts a list of strings and returns the longest one. If there are multiple strings with the same length, return the first one. Save to utils.py.

Codex مراحل زیر را اجرا می‌کند:

1. برنامه‌ریزی: نیازمندی‌های شما را تحلیل می‌کند و برنامه پیاده‌سازی را تدوین می‌کند
2. تولید کد: utils.py را ایجاد می‌کند و تابع را می‌نویسد
3. درخواست تأیید: در پیش‌تنظیم فقط‌خواندنی، یا وقتی تغییری نیاز به تأیید دارد (مثلاً نوشتن خارج از فضای کاری)، Codex تغییر فایل در انتظار را نشان می‌دهد و منتظر تأیید شما می‌ماند؛ در پیش‌تنظیم پیش‌فرض، ویرایش‌های داخل فضای کاری به‌طور خودکار اجرا می‌شوند

وقتی تأیید لازم باشد، یک prompt مانند این را می‌بینید:

Codex wants to create file: utils.py
─────────────────────────────────────

+ def find_longest(strings: list[str]) -> str:
+     """Return the longest string in the list, or the first one if there are multiple."""
+     if not strings:
+         raise ValueError("List cannot be empty")
+     return max(strings, key=len)

Accept? [y/n]

y را وارد کنید تا تأیید شود، و Codex کد را در فایل می‌نویسد.

سپس می‌توانید دستورهای بیشتری بدهید و Codex زمینه را در همان نشست حفظ می‌کند:

Write a unit test for this function using pytest

Codex به‌طور خودکار utils.py را که همین حالا ایجاد کرده‌اید می‌خواند، سپس فایل تست مربوطه را تولید می‌کند.

4.3 درک حالت اجرای محیط ایزوله Codex¶

این یکی از مهم‌ترین ویژگی‌های امنیتی Codex است. Codex دستورها را در یک محیط ایزوله اجرا می‌کند، با سه سطح امنیتی:

حالت پیش‌فرض workspace-write بهترین انتخاب برای توسعه روزمره است: Codex می‌تواند آزادانه فایل‌ها را بخواند/بنویسد و دستورها را در پوشه پروژه اجرا کند، اما نمی‌تواند به فایل‌ها یا شبکه خارج از پروژه دسترسی داشته باشد.

اگر وظیفه شما نیاز به دسترسی به شبکه دارد (مانند npm install)، می‌توانید دسترسی به شبکه را موقتاً فعال کنید:

codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies and run tests"

4.4 بازبینی و پذیرش تغییرات Codex¶

تغییرات فایل Codex از یک سیاست تأیید پیروی می‌کند. بر اساس مستندات رسمی (تا تاریخ 2026-10-26)، پیش‌فرض در یک مخزن Git، پیش‌تنظیم «نوشتن در فضای کاری + تأییدهای بر اساس درخواست» است:

• ویرایش فایل‌ها و دستورهای داخل فضای کاری: به‌طور خودکار اجرا می‌شوند
• نوشتن خارج از فضای کاری، دسترسی به شبکه و اقدامات مشابه: به شما نمایش داده می‌شود و منتظر تأیید می‌ماند
• پوشه‌هایی که مخزن Git نیستند: به‌طور پیش‌فرض فقط‌خواندنی هستند، بنابراین Codex پیش از هر تغییری می‌پرسد

وقتی Codex تغییراتی را پیشنهاد می‌دهد، می‌توانید:

• پذیرش (y): تغییر را اعمال کنید
• رد (n): از این تغییر صرف‌نظر کنید
• مشاهده جزئیات: پیش از تصمیم‌گیری، diff را به‌دقت بررسی کنید

نکته: از دستور اسلش /diff استفاده کنید تا در هر زمان همه تغییرات اعمال‌شده در نشست جاری را مشاهده کنید.

4.5 نکات رایج تعامل¶

ارجاع به فایل: @ را وارد کنید و سپس نام فایل را بنویسید؛ Codex به‌طور خودکار محتوای آن فایل را می‌خواند:

Review @src/app.py and optimize error handling

اجرای دستورهای Shell: با ! شروع کنید تا دستورها مستقیماً اجرا شوند؛ خروجی به Codex منتقل می‌شود:

!cat error.log
Analyze the error log above and find the root cause

افزودن دستور: وقتی Codex در حال اجراست، Enter را فشار دهید تا دستور جدید درج شود، و Tab را فشار دهید تا دور بعدی دستورها در صف قرار گیرد.

ویرایش با عقب‌گرد: وقتی کادر ورودی خالی است، دو بار Esc را فشار دهید تا به پیام قبلی برگردید و آن را تغییر دهید/دوباره ارسال کنید. برای عقب‌گرد به پیام‌های قبلی‌تر، فشار دادن Esc را ادامه دهید، سپس Enter را فشار دهید تا از آن نقطه یک خط مکالمه جدید منشعب شود.

ورودی لوله‌ای: می‌توانید خروجی دستورهای دیگر را برای تحلیل به Codex لوله‌کشی کنید:

# Analyze recent git changes
git diff HEAD~3 | codex "Review these changes and identify potential issues"

# Analyze error logs
cat /var/log/app/error.log | codex "Analyze the root causes of these errors"

# Review PR
gh pr diff 42 | codex "Review this PR's code quality and security"

میان‌برهای صفحه‌کلید:

دستورهای اسلش:

4.6 تغییرات دستور Codex CLI 0.164.0 (2026-10-23)¶

Codex CLI 0.164.0 در 2026-10-23 منتشر شد. یادداشت‌های انتشار آن این تغییرات مربوط به دستور و پیکربندی را فهرست می‌کنند (نقل‌شده عیناً):

• ذخیره promptهای قابل استفاده مجدد و دستورهای اسلش در ده جایگاه شماره‌دار /presets، همراه با منوی صفحه‌کلید برای دسترسی سریع.
• تنظیم مستقیم مدل، میزان استدلال، سرعت و پروفایل‌های مجوز با آرگومان‌های درون‌خطی /model و /permissions.
• احراز هویت اتصال‌های MCP سازمانی با استفاده از مجوزهای حساب Codex واجد شرایط یا ورود اختصاصی، شامل کلاینت‌های OAuth نیازمند secret.
• پنهان‌سازی اعتبارنامه‌ها در طول دستورهای Bash راه‌دور پشتیبانی‌شده و نشست‌های snapshot در Zsh، شامل اعتبارنامه‌های ارائه‌دهندگان سفارشی.

کلیدهای استفاده‌شده در پیکربندی بالا در مرجع پیکربندی رسمی بررسی‌شده در 2026-10-26 باقی می‌مانند: model_provider، [model_providers.<id>]، base_url، wire_api و requires_openai_auth. دستورهای نصب در README رسمی بررسی‌شده در همان روز بدون تغییر هستند: npm install -g @openai/codex، brew install --cask codex، یا curl -fsSL https://chatgpt.com/codex/install.sh | sh.

5. پیکربندی پیشرفته¶

5.1 فایل‌های دستورالعمل سفارشی (AGENTS.md)¶

Codex از فایل‌های AGENTS.md پشتیبانی می‌کند تا زمینه پروژه و مشخصات کار را در اختیار هوش مصنوعی قرار دهد؛ عملکرد آن مشابه CLAUDE.md در Claude Code است.

دستورالعمل‌های سطح پروژه: فایل AGENTS.md را در پوشه ریشه پروژه ایجاد کنید:

# AGENTS.md

## Project Description
This is a FastAPI backend project using PostgreSQL database.

## Code Standards

- All functions must have type annotations
- New API endpoints require corresponding tests
- Run `make lint` to check code style before committing

## Test Commands

- Unit tests: `pytest tests/unit/`
- Integration tests: `pytest tests/integration/`
- Code check: `make lint`

دستورالعمل‌های سراسری: قواعد پیش‌فرض سراسری را در ~/.codex/AGENTS.md ایجاد کنید؛ همه پروژه‌ها آن را به ارث می‌برند:

# Global Instructions

- Always communicate in English
- Code comments use English
- Prefer functional programming style
- Generated code must include error handling

بازنویسی زیرپوشه: ایجاد AGENTS.override.md در یک پوشه مشخص می‌تواند قواعد والد را بازنویسی کند:

# services/payments/AGENTS.override.md

- All changes in this directory must be written to audit log
- Amount calculations use Decimal type, no floating point numbers

Codex فایل‌های دستورالعمل را به ترتیب زیر جست‌وجو می‌کند: AGENTS.override.md > AGENTS.md > فایل جایگزین پیکربندی‌شده. محدودیت اندازه مجموع پیش‌فرض 32KB است و با project_doc_max_bytes قابل تنظیم است.

5.2 تنظیم تأییدها و محیط ایزوله¶

کنترل‌های امنیتی Codex دو لایه دارند: حالت محیط ایزوله تعیین می‌کند Codex از نظر فنی چه کارهایی می‌تواند انجام دهد (کجا می‌تواند بنویسد، آیا می‌تواند به شبکه دسترسی داشته باشد)، و سیاست تأیید تعیین می‌کند چه زمانی باید ابتدا از شما بپرسد. بر اساس مستندات رسمی OpenAI، تا تاریخ 2026-10-26، دو گزینه خط فرمان آن‌ها را کنترل می‌کنند:

ترکیب‌های رایج (مستندات رسمی):

🔴 فرم‌های --full-auto، --suggest، --auto-edit و --approval-mode که ممکن است در آموزش‌های قدیمی‌تر ببینید، در فهرست گزینه‌های رسمی فعلی نیستند. وقتی به نوشتن کاملاً خودمختار فایل نیاز دارید، از --sandbox workspace-write استفاده کنید؛ برای اجراهای غیرتعاملی از codex exec --sandbox workspace-write استفاده کنید.

⚠️ گزینه‌های Codex سریع تغییر می‌کنند. به خروجی واقعی codex --help اعتماد کنید، نه به فهرست گزینه‌هایی که از هر سندی، از جمله همین صفحه، کپی شده است.

تعیین پیش‌فرض‌ها در config.toml:

# Recommended for personal development
approval_policy = "on-request"
sandbox_mode = "workspace-write"

approval_policy مقدار on-request، never یا یک جدول granular را می‌پذیرد که promptها را بر اساس دسته تقسیم می‌کند. مستندات رسمی می‌گویند approval_policy = "untrusted" دیگر پشتیبانی نمی‌شود؛ اگر پیکربندی قدیمی هنوز آن خط را دارد، می‌تواند مانع شروع کلاینت شود، پس آن را حذف کنید.

تغییر در طول نشست: از دستور /permissions برای جابه‌جایی بین پیش‌فرض و حالت فقط‌خواندنی بدون راه‌اندازی مجدد استفاده کنید.

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

5.3 پیکربندی سرورهای MCP¶

Codex از پروتکل زمینه مدل (MCP) پشتیبانی می‌کند که می‌تواند ابزارهای خارجی را متصل کرده و قابلیت‌ها را گسترش دهد.

افزودن سرور MCP از طریق خط فرمان:

codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json

پیکربندی از طریق config.toml:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token" }

پس از پیکربندی، Codex را راه‌اندازی مجدد کنید و از دستور /mcp برای مشاهده سرورهای متصل استفاده کنید. ابزارهای MCP به‌طور خودکار در کنار ابزارهای داخلی در فهرست ابزارهای در دسترس Codex ظاهر می‌شوند.

تبدیل خود Codex به سرور MCP: Codex همچنین می‌تواند به‌صورت معکوس به‌عنوان سرور MCP اجرا شود و توسط سایر عامل‌های هوش مصنوعی فراخوانی شود. این موضوع هنگام ساخت سیستم‌های چندعاملی بسیار مفید است.

5.4 پیکربندی پروفایل (مدیریت چندمحیطی)¶

اگر پروژه‌های مختلف به تنظیمات متفاوتی نیاز دارند (مثلاً کاری در برابر شخصی)، از پروفایل‌ها استفاده کنید. از Codex 0.134.0 به بعد، جدول‌های قدیمی [profiles.<name>] داخل config.toml دیگر معتبر نیستند — اکنون هر پروفایل فایل مخصوص خود را دارد: ~/.codex/<name>.config.toml. سه بلوک زیر شکل کامل جدید هستند:

# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "qcode"
model = "gpt-6-sol"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true

# ~/.codex/work.config.toml
model = "gpt-6-sol"
model_reasoning_effort = "high"

# ~/.codex/personal.config.toml
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"

شروع با یک پروفایل:

codex --profile work "Refactor authentication module"
codex --profile personal "Write a small script"

✅ سه رفتار زیر روی دستگاه خودمان آزمایش شده‌اند (codex-cli 0.155.0، linux-x86_64، HOME ایزوله، بدون ارسال درخواست مدل) و همان دام‌هایی هستند که افراد به آن‌ها برمی‌خورند:

• نگه داشتن جدول قدیمی و ارسال --profile یک خطای سخت است، نه نادیده‌گرفتن بی‌صدا:

text Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.

• انتخاب‌گر سطح بالای profile = "work" هم بازنشسته شده است:

text Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead

• بدون --profile، جدول‌های باقی‌مانده [profiles.*] اصلاً بررسی نمی‌شوند — codex doctor همچنان config.toml parse ok را گزارش می‌کند و از مقادیر سطح بالا استفاده می‌کند. «بدون خطا» به معنای «اعمال شد» نیست، پس هنگام مهاجرت جدول‌های قدیمی را حذف کنید.

همچنین، --profile فقط برای زیردستورهای زمان اجرا اعمال می‌شود (codex، exec، review، resume، queue، archive، delete، unarchive، fork، mcp، sandbox، debug prompt-input)؛ روی doctor با پیام --profile only applies to runtime commands ... شکست می‌خورد. فایل پروفایل لایه‌ای بالاتر از پیکربندی کاربری شما و پایین‌تر از پیکربندی پروژه و خط فرمان است — به بخش 5.6 مراجعه کنید.

5.5 حالت غیرتعاملی (اسکریپت‌ها و خودکارسازی)¶

Codex نه‌تنها می‌تواند به‌صورت تعاملی استفاده شود، بلکه می‌تواند در اسکریپت‌ها و خطوط لوله CI/CD نیز به‌صورت غیرتعاملی اجرا شود: از codex exec برای اجرای یک وظیفه و خروج استفاده کنید (بر اساس مستندات رسمی، به‌صورت غیرتعاملی اجرا می‌شود و نتایج را به stdout یا JSONL جریان می‌دهد).

# Basic usage: execute task then exit
codex exec "Add installation instructions to README.md"

# Allow workspace writes: fully autonomous execution
codex exec --sandbox workspace-write "Run test suite, fix all failing tests"

# Output a JSONL event stream (for auditing or post-processing)
codex exec --json "Refactor error handling module"

استفاده از Codex در CI/CD:

# GitHub Actions example

- name: Auto-fix lint errors
  run: |
    # Environment-variable variant: use env_key in config.toml, no requires_openai_auth
    mkdir -p ~/.codex
    cat > ~/.codex/config.toml <<'EOF'
    model_provider = "qcode"
    model = "gpt-6.1-sol"

    [model_providers.qcode]
    name = "qcode"
    base_url = "https://api.qcode.cc/openai"
    wire_api = "responses"
    env_key = "QCODE_API_KEY"
    EOF
    npx @openai/codex exec --sandbox workspace-write "Run eslint --fix to fix all lint errors, then commit the fixes"
  env:
    QCODE_API_KEY: ${{ secrets.QCODE_API_KEY }}

SDK Codex: اگر نیاز دارید Codex را در برنامه‌های خودتان فراخوانی کنید، می‌توانید از SDK رسمی برای فراخوانی برنامه‌نویسی استفاده کنید و Codex را در ابزارها یا جریان‌های کاری توسعه خود جاسازی کنید.

5.6 اولویت پیکربندی¶

وقتی چند منبع پیکربندی با هم تعارض دارند، Codex آن‌ها را به ترتیب اولویت زیر (از بالاترین به پایین‌ترین) حل می‌کند:

1. آرگومان‌های خط فرمان (--model، -c و غیره)
2. پیکربندی پروژه (.codex/config.toml، از ریشه پروژه تا پوشه جاری، نزدیک‌ترین اولویت دارد؛ فقط زمانی بارگذاری می‌شود که پوشه مورد اعتماد باشد، و کلیدهایی مانند model_provider، model_providers، profile و profiles در لایه پروژه نادیده گرفته می‌شوند)
3. فایل پروفایل (~/.codex/<name>.config.toml، انتخاب‌شده با --profile <name>)
4. پیکربندی کاربر (~/.codex/config.toml)
5. پیکربندی سیستم (/etc/codex/config.toml، سیستم‌های Unix)
6. پیش‌فرض‌های داخلی

درک این اولویت به شما کمک می‌کند رفتار را در سطوح مختلف به‌طور دقیق کنترل کنید. برای مثال، پیش‌فرض‌های کلی را در ~/.codex/config.toml تعیین کنید، تنظیمات مشخص را در .codex/config.toml پروژه بازنویسی کنید، سپس برای تنظیمات یک‌باره از آرگومان‌های خط فرمان استفاده کنید.

6. مقایسه Claude Code و Codex¶

در یک خط: Claude Code برنامه‌نویسی جفتی تعاملی است؛ Codex اجرای خودمختار وظیفه است. Claude Code برای اشکال‌زدایی اکتشافی، بازآرایی‌های پیچیده و درک یک معماری مناسب است؛ Codex برای کار روی ویژگی‌های به‌خوبی مشخص‌شده، مهاجرت‌های انبوه و خودکارسازی CI/CD مناسب است. فایل‌های دستورالعمل آن‌ها CLAUDE.md و AGENTS.md هستند، هر دو به‌طور کامل از MCP پشتیبانی می‌کنند و هر دو از همان سهمیه پلن QCode.cc به‌طور مشترک استفاده می‌کنند — جابه‌جایی بین آن‌ها هیچ هزینه‌ای ندارد.

مقایسه کامل رو‌در‌رو در 13 بُعد (مدل اجرا، پنجره زمینه، سندباکس‌سازی، چندعاملی، متن‌باز و موارد دیگر) → Codex در برابر Claude Code.

7. مثال‌های عملی¶

در ادامه، استفاده از Codex را در چند سناریوی واقعی نشان می‌دهیم. هر مثال شامل دستورهای مشخص و اثرهای مورد انتظار است.

مثال 1: درک یک پروژه جدید¶

وقتی پایگاه کد ناآشنایی را تحویل می‌گیرید:

cd /path/to/new/project
codex

در رابط تعاملی:

What does this project do? Please analyze the directory structure, main modules, tech stack,
and give a concise architecture diagram (using ASCII art).

Codex فایل‌های پروژه را پیمایش می‌کند، فایل‌های وابستگی مانند package.json، requirements.txt و go.mod را تحلیل می‌کند، فایل‌های ورودی کلیدی را می‌خواند و سپس نمای کلی جامعی از پروژه ارائه می‌دهد.

مثال 2: بازبینی کد¶

codex "Review all changes from the most recent git commit in the src/ directory. Focus on:
1. Potential bugs (null pointers, boundary conditions)
2. Security risks (SQL injection, XSS, hardcoded keys)
3. Performance issues (N+1 queries, unnecessary loops)
Provide specific code locations and fix suggestions."

مثال 3: بازآرایی دسته‌ای¶

codex --sandbox workspace-write "Replace all Python file print() calls with the logging module.
Specific requirements:
1. Import logging at the top of each file
2. Create logger = logging.getLogger(__name__)
3. Replace print() with logger.info()
4. Keep original formatted strings
5. After replacement, run pytest to ensure nothing is broken"

Codex فایل‌ها را یکی‌یکی پردازش می‌کند، سازگاری کد را حفظ می‌کند و در پایان برای راستی‌آزمایی تست‌ها را اجرا می‌کند.

مثال 4: نوشتن مجموعه تست کامل¶

codex "Write complete unit tests for src/services/user_service.py. Requirements:
1. Use pytest + pytest-mock
2. Cover all public methods
3. Include both happy path and exception path tests
4. Mock external dependencies (database, HTTP requests)
5. Save test file to tests/unit/test_user_service.py
6. Run tests to confirm all pass"

مثال 5: برطرف‌سازی خودمختار تست¶

یک مورد استفاده کلاسیک و کاملاً خودمختار — اجازه دهید Codex تست‌های ناموفق را خودش برطرف کند:

codex --sandbox workspace-write "Run all tests. If any fail:
1. Analyze the failure reasons
2. Fix the code (not the tests)
3. Re-run tests
4. Repeat above steps until all tests pass
Finally, provide a fix summary."

مثال 6: پیاده‌سازی رابط کاربری از روی ماکاپ طراحی¶

codex -i design.png "Implement this page using React + Tailwind CSS based on this design mockup.
Requirements:
1. Responsive layout (mobile support)
2. Pixel-perfect recreation of the design mockup
3. Reasonable component splitting
4. Add basic interaction states (hover, focus)"

مثال 7: مهاجرت پایگاه داده¶

codex "I need to add an avatar_url field (varchar 500, nullable) to the users table.
Please:
1. Create Alembic migration script
2. Update SQLAlchemy model
3. Update related Pydantic schema
4. Update CRUD operation functions
5. Add corresponding API endpoints (GET/PUT)
6. Run migration and confirm success"

مثال 8: تولید خودکار گزارش تغییرات در CI/CD¶

codex --sandbox workspace-write "Analyze all git commits from the last release tag to now,
categorize them according to conventional commits specification,
and generate CHANGELOG.md update content.
Include: new features, bug fixes, breaking changes, other improvements."

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

فایل پیکربندی یافت نشد¶

مشکل: Codex پیام می‌دهد که فایل پیکربندی یافت نشد یا نمی‌تواند پیکربندی را بارگذاری کند

راه‌حل:

1. بررسی کنید که دایرکتوری پیکربندی وجود دارد: ls ~/.codex/
2. تأیید کنید که هر دو فایل config.toml و auth.json وجود دارند
3. بررسی کنید که نحو TOML در config.toml درست است (خطاهای رایج: نبود گیومه، غلط تایپی)
4. دستور codex doctor را اجرا کنید تا گزارش تشخیصی شامل نصب، پیکربندی و احراز هویت تولید شود

احراز هویت کلید API ناموفق بود¶

مشکل: پیام 401 Unauthorized یا نامعتبر بودن کلید API

راه‌حل:

1. تأیید کنید که قالب کلید API درست است (با cr_ شروع می‌شود)
2. بررسی کنید که کلید در auth.json کامل است (بدون فاصله یا شکست خط اضافی)
3. اگر از گونه متغیر محیطی استفاده می‌کنید، تأیید کنید که ارائه‌دهنده دارای env_key = "QCODE_API_KEY" است، requires_openai_auth = true ندارد و متغیر export شده است
4. وارد کنسول QCode.cc شوید تا وضعیت کلید و سهمیه باقی‌مانده را تأیید کنید

مشکلات اتصال شبکه¶

مشکل: اتصال به سرویس QCode.cc برقرار نمی‌شود، پایان مهلت اتصال (timeout) یا رد شدن اتصال (connection refused)

راه‌حل:

1. بررسی کنید که شبکه سالم است: curl -I https://api.qcode.cc
2. صحت پیکربندی base_url را بررسی کنید (باید https://api.qcode.cc/openai باشد)

3. نقطه پایانی دیگری را امتحان کنید:

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

5. اگر از پروکسی/VPN شرکتی استفاده می‌کنید، تأیید کنید که تنظیمات پروکسی درخواست‌های HTTPS را مسدود نمی‌کند

توصیه انتخاب مدل¶

مشکل: مطمئن نیستید کدام مدل را انتخاب کنید

توصیه:

پس از تعیین مدل پیش‌فرض در config.toml، می‌توانید به‌صورت موقت هم مدل را عوض کنید:

codex -m gpt-6-sol "Analyze this complex concurrency bug"

محدودیت‌های سندباکس موجب شکست دستورها می‌شود¶

مشکل: دستورهایی که Codex می‌کوشد اجرا کند توسط سندباکس رد می‌شوند

راه‌حل:

1. اگر عملیات شبکه‌ای است (مانند npm install)، دسترسی شبکه را موقتاً فعال کنید: bash codex -c 'sandbox_workspace_write.network_access=true' "Install dependencies"
2. اگر لازم است فایل‌هایی بیرون از دایرکتوری پروژه بنویسید، دامنه نوشتن را موقتاً گسترش دهید: bash codex --sandbox danger-full-access "Save output to /tmp/result.txt"
3. در طول نشست از /permissions استفاده کنید تا مجوزهای فعلی را ببینید و تنظیم کنید

توضیح هزینه¶

مشکل: هزینه‌های Codex و Claude Code چگونه محاسبه می‌شود؟

توضیح:

• Codex و Claude Code سهمیه پلن QCode.cc را مشترکاً استفاده می‌کنند
• یک پلن می‌تواند هم‌زمان توسط هر دو ابزار استفاده شود
• هزینه‌ها بر اساس مصرف واقعی توکن محاسبه می‌شود، نه بر اساس ابزار
• وقتی Codex به‌صورت خودمختار برای چندین دور تکرار می‌کند، مصرف توکن برای یک وظیفه ممکن است بیشتر باشد، اما در زمان تعامل توسعه‌دهنده صرفه‌جویی می‌شود
• QCode بر اساس توکن صورت‌حساب می‌کند؛ نرخ هر مدل در qcode.cc/models آمده است و می‌توانید مصرف را در کنسول QCode.cc بررسی کنید

آیا AGENTS.md و CLAUDE.md می‌توانند هم‌زمان وجود داشته باشند؟¶

بله. اگر پروژه شما هم توسط Codex و هم Claude Code استفاده می‌شود:

• Codex فقط AGENTS.md را می‌خواند و CLAUDE.md را نادیده می‌گیرد
• Claude Code فقط CLAUDE.md را می‌خواند و AGENTS.md را نادیده می‌گیرد
• آن‌ها با یکدیگر تداخلی ندارند و می‌توانید فایل‌های دستورالعمل جداگانه‌ای برای ابزارهای مختلف نگه دارید
• توصیه می‌شود مشخصات اصلی را در هر دو فایل یکسان نگه دارید (مانند دستورهای آزمون، سبک کد و غیره)

10. مستندات مرتبط¶

• پیکربندی متغیرهای محیطی — تنظیمات متغیرهای محیطی برای Claude Code
• شروع سریع — راهنمای شروع سریع Claude Code
• یکپارچه‌سازی Aider — پیکربندی دستیار برنامه‌نویسی هوش مصنوعی متن‌باز دیگر
• نکات CLI — استفاده پیشرفته از خط فرمان برای Claude Code
• نکات گردش کار — پیشنهادهای گردش کار برای بهبود بهره‌وری کدنویسی با هوش مصنوعی

سازمانی ←