آموزش کامل OpenAI Codex: راهنمای جامع ایجنت کدنویسی هوش مصنوعی

OpenAI Codex فقط یک ابزار ترمینالی ساده نیست. Codex یک سیستم کامل ایجنت کدنویسی است که می‌تواند در ترمینال، داخل IDE، در اپ دسکتاپ Codex، در محیط ابری، در Pull Requestهای گیت‌هاب و حتی در CI یا ابزارهای داخلی شما کار کند.

این راهنما بر اساس مستندات رسمی OpenAI Codex در تاریخ ۲۱ ژوئن ۲۰۲۶ نوشته شده است. نام مدل‌ها، قیمت‌گذاری، دستورات نصب و قابلیت‌ها ممکن است تغییر کنند؛ بنابراین برای تصمیم‌های عملیاتی، لینک‌های رسمی انتهای مقاله را هم بررسی کنید.

---

OpenAI Codex چیست؟

OpenAI Codex ایجنت کدنویسی OpenAI برای توسعه نرم‌افزار است. Codex می‌تواند کدبیس را بخواند، سیستم‌های ناشناخته را توضیح دهد، فایل‌ها را ویرایش کند، دستور اجرا کند، خطاها را دیباگ کند، تغییرات را ریویو کند و کارهای تکراری مهندسی را خودکار کند.

تفاوت اصلی Codex با یک چت‌بات معمولی در این است که Codex هدف را می‌گیرد، کانتکست جمع می‌کند، برنامه می‌ریزد یا برنامه شما را اجرا می‌کند، فایل تغییر می‌دهد، تست اجرا می‌کند، خروجی را می‌خواند و تا رسیدن به نتیجه یا برخورد با مانع ادامه می‌دهد.

Codex چه کارهایی انجام می‌دهد؟

• نوشتن کد: پیاده‌سازی فیچر، اسکریپت، تست، migration، تغییر UI و مستندات.
• درک کدبیس: توضیح معماری، مسیرهای اصلی، جریان داده و بخش‌های پرریسک.
• دیباگ: بررسی لاگ، بازتولید خطا، پیدا کردن ریشه مشکل و اعمال کوچک‌ترین اصلاح قابل دفاع.
• بازبینی کد: پیدا کردن باگ‌های جدی، edge caseهای جاافتاده، ریسک امنیتی و تست‌های ناقص.
• اتوماسیون توسعه: اجرای چک‌های تکراری، آماده‌سازی release note، تریاژ issue و رفع خطای CI.
• اتصال به ابزارها: استفاده از MCP، پلاگین‌ها، مرورگر، computer use، گیت‌هاب، Linear، Slack، Figma، Sentry و مستندات داخلی در صورت پیکربندی.

---

سطوح مختلف Codex: کدام را انتخاب کنیم؟

Codex چند سطح یا surface دارد. ایده اصلی در همه یکی است، اما هر سطح برای نوع خاصی از کار مناسب‌تر است.

پیشنهاد عملی

اگر کامل‌ترین تجربه محلی را می‌خواهید، از اپ Codex شروع کنید. اگر ترمینال‌محور هستید، CLI بهترین انتخاب است. اگر فایل‌های باز و selection ادیتور مهم است، افزونه IDE مناسب‌تر است. برای کارهای پس‌زمینه یا branch-based از Cloud استفاده کنید. برای کارهای بدون UI از codex exec، GitHub Action یا SDK کمک بگیرید.

---

بخش ۱: نصب و راه‌اندازی اولیه

حساب کاربری و دسترسی

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

روش ورود اهمیت دارد:

• ورود با ChatGPT از پلن، دسترسی workspace، کنترل‌های enterprise و Codex Cloud استفاده می‌کند.
• ورود با API key از billing پلتفرم OpenAI استفاده می‌کند و برای CLI، IDE و اتوماسیون مناسب است.
• Codex Cloud به ورود با ChatGPT نیاز دارد.

نصب اپ Codex

اپ Codex برای macOS و Windows در دسترس است. آن را از quickstart رسمی Codex دانلود کنید، باز کنید، با ChatGPT یا API key وارد شوید، یک پوشه پروژه انتخاب کنید و اولین thread محلی خود را شروع کنید.

اپ Codex برای این کارها مناسب است:

• اجرای چند thread در چند پروژه
• ساخت و مدیریت Git worktree
• ترمینال داخلی
• diff، stage، commit، push و ساخت PR
• اتوماسیون‌ها
• مرورگر داخلی برای preview
• computer use برای اپ‌های دسکتاپ
• preview برای PDF، spreadsheet، document و presentation

نصب افزونه IDE

افزونه Codex را برای Visual Studio Code، Cursor، Windsurf یا ادیتورهای سازگار با VS Code نصب کنید. بعد از نصب، پنل Codex در sidebar ظاهر می‌شود و می‌توانید وارد حساب شوید.

افزونه به صورت پیش‌فرض در حالت Agent شروع می‌شود؛ یعنی Codex می‌تواند فایل بخواند، دستور اجرا کند و داخل دایرکتوری پروژه تغییر ایجاد کند. وقتی فقط توضیح یا برنامه می‌خواهید، حالت محدودتر را انتخاب کنید.

نصب Codex CLI

در macOS یا Linux، نصب‌کننده رسمی:

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

در Windows PowerShell:

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

برای نصب unattended:

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

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

روش‌های دیگر:

npm install -g @openai/codex
brew install --cask codex

بررسی نصب:

codex --version
codex --help

ورود به حساب

codex login

سپس ورود با ChatGPT یا API key را انتخاب کنید. CLI و افزونه IDE credential cache مشترک دارند؛ اگر از یکی خارج شوید ممکن است در دیگری هم نیاز به ورود دوباره داشته باشید.

برای ماشین‌های headless:

codex login --device-auth

برای اتوماسیون‌های مطمئن، credential را فقط در همان فرمانی قرار دهید که نیاز دارد؛ نه در کل محیط job.

---

بخش ۲: اولین جلسه Codex

وارد یک repo شوید:

cd path/to/your-project
codex

یک prompt خواندنی و کم‌ریسک:

Explain this codebase. Focus on the main entry points, data flow, test commands, and the riskiest modules.

یک prompt اجرایی و محدود:

Fix the failing login validation test. Keep the change minimal, run the relevant test, and show me the diff before summarizing.

قالب prompt قوی

Goal:
Implement [specific behavior].

Context:
Relevant files are [files/folders]. The current error is [error/log].

Constraints:
Keep the change minimal. Follow existing patterns. Do not add dependencies.

Done when:
The relevant tests pass and the diff only touches the intended files.

چه زمانی اول plan بخواهیم؟

برای کارهای مبهم، چندفایلی، پرریسک یا سخت‌تست، قبل از ویرایش plan بخواهید:

Before editing, inspect the code and write a short implementation plan. Include the files you expect to change and the checks you will run.

در CLI، دستور /plan حالت برنامه‌ریزی را فعال می‌کند.

---

بخش ۳: دستورهای ضروری CLI

فلگ‌های کاربردی

پیشنهاد معمول برای توسعه محلی:

codex --sandbox workspace-write --ask-for-approval on-request

برای مشاوره و ریویو:

codex --sandbox read-only --ask-for-approval on-request

از --dangerously-bypass-approvals-and-sandbox فقط وقتی استفاده کنید که Codex داخل یک sandbox خارجی و disposable اجرا می‌شود.

---

بخش ۴: دستورهای Slash

Slash commandها به شما اجازه می‌دهند جلسه فعال CLI را بدون restart کنترل کنید.

دستور /status را زیاد استفاده کنید؛ سریع‌ترین راه برای فهمیدن وضعیت واقعی session است.

---

بخش ۵: مدل‌ها و Reasoning

راهنمای رسمی Codex در ۲۱ ژوئن ۲۰۲۶ پیشنهاد می‌کند برای بیشتر کارها از gpt-5.5 شروع کنید. این مدل برای کدنویسی پیچیده، computer use، کارهای دانشی، research و taskهای چندمرحله‌ای مناسب‌ترین گزینه عمومی است.

برای کارهای سبک‌تر و سریع‌تر، gpt-5.4-mini گزینه خوبی است. برخی کاربران Pro ممکن است مدل research-preview به نام gpt-5.3-codex-spark را هم برای iteration سریع ببینند.

تنظیم مدل پیش‌فرض:

model = "gpt-5.5"

اجرای موقت با مدل مشخص:

codex --model gpt-5.5
codex exec --model gpt-5.5 "review the diff for concurrency bugs"

برای taskهای کوچک reasoning پایین یا متوسط کافی است. برای دیباگ پیچیده، refactor چندفایلی، migration، security review و معماری از reasoning بالاتر استفاده کنید.

model_reasoning_effort = "high"

---

بخش ۶: پیکربندی Codex

Codex تنظیمات را از چند لایه می‌خواند.

اولویت تنظیمات

از بالاترین اولویت:

1. فلگ‌های CLI و overrideهای --config
2. فایل‌های trusted project مثل .codex/config.toml
3. profileها مثل ~/.codex/profile-name.config.toml
4. تنظیمات کاربر در ~/.codex/config.toml
5. تنظیمات سیستم مثل /etc/codex/config.toml
6. پیش‌فرض‌های داخلی

تنظیمات project-local فقط در پروژه‌های trusted بارگذاری می‌شوند.

نمونه config.toml

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "medium"
personality = "pragmatic"

[sandbox_workspace_write]
network_access = false

[shell_environment_policy]
include_only = ["PATH", "HOME", "LANG"]

[features]
hooks = true
multi_agent = true
shell_snapshot = true

Profileها

codex --profile review
codex exec --profile ci "summarize risk in this pull request"

چند profile مفید:

• review: read-only، reasoning بالا، بدون ویرایش
• frontend: workspace-write همراه با ابزار مرورگر
• ci: اجرای غیرتعاملی، مدل ثابت، خروجی JSON
• research: جستجوی زنده فعال

---

بخش ۷: سندباکس، Approval و امنیت

امنیت در Codex دو لایه دارد:

• Sandbox mode: مشخص می‌کند Codex از نظر فنی به چه چیزهایی دسترسی دارد.
• Approval policy: مشخص می‌کند چه زمانی باید قبل از عمل کردن اجازه بگیرد.

Sandbox Modeها

در حالت محلی، دسترسی network برای commandها به صورت پیش‌فرض خاموش است مگر اینکه فعال شود:

[sandbox_workspace_write]
network_access = true

فقط وقتی واقعاً لازم است network را فعال کنید.

Approval Policyها

برای توسعه محلی، ترکیب workspace-write و on-request معمولاً بهترین نقطه شروع است.

مسیرهای محافظت‌شده

در sandbox پیش‌فرض، مسیرهایی مثل .git، .codex و .agents حتی داخل writable root هم read-only هستند تا Git و state ایجنت آسیب نبیند.

Auto Review برای Approval

اگر auto-review در workspace شما فعال باشد، درخواست‌های حساس approval می‌توانند قبل از اجرا توسط یک policy reviewer بررسی شوند. این مکانیزم برای جلوگیری از credential probing، عملیات destructive و ضعیف کردن امنیت مفید است.

---

بخش ۸: Web Search و دسترسی شبکه

دو مفهوم را قاطی نکنید:

• ابزار web search: ابزاری برای مدل جهت جستجوی وب.
• دسترسی شبکه commandها: اینکه دستورهای shell اجراشده توسط Codex به network دسترسی داشته باشند یا نه.

حالت‌های web search:

web_search = "cached"
# web_search = "live"
# web_search = "disabled"

برای یک اجرای خاص:

codex --search "check the latest release notes and update this migration guide"

محتوای وب را untrusted فرض کنید. Prompt injection می‌تواند در issue، HTML، README، مستندات و لاگ‌ها وجود داشته باشد.

---

بخش ۹: راهنمای پایدار با AGENTS.md

AGENTS.md فایل راهنمای دائمی است که Codex قبل از شروع کار می‌خواند. از آن برای conventionهای repo، دستورهای build/test، انتظارات ریویو و راهنمایی‌های دایرکتوری‌محور استفاده کنید.

Codex کجا را می‌خواند؟

• ~/.codex/AGENTS.md
• ~/.codex/AGENTS.override.md
• AGENTS.md در ریشه repo
• AGENTS.md یا AGENTS.override.md در زیرمسیرهای نزدیک‌تر
• fallback filenameها در صورت پیکربندی

فایل‌های نزدیک‌تر به دایرکتوری کار بعدتر وارد prompt می‌شوند و می‌توانند راهنمایی‌های بالاتر را override کنند.

نمونه AGENTS.md

# AGENTS.md

## Repository expectations

- Use `npm run lint` before opening a pull request.
- Use `npm test -- --runInBand` for targeted test verification.
- Keep changes small and aligned with existing component patterns.
- Do not add production dependencies without asking first.

## Review guidelines

- Flag auth, billing, and data-loss regressions as high priority.
- Treat missing tests on shared logic as P1.
- Mention exact file paths and line numbers in review findings.

این فایل را کوتاه و عملی نگه دارید. اگر توضیح طولانی لازم است، آن را در docs جدا بگذارید و از AGENTS.md به آن لینک دهید.

---

بخش ۱۰: Skills، Plugins، MCP، Hooks و Automations

قدرت واقعی Codex وقتی مشخص می‌شود که آن را با workflow تیم خود تنظیم کنید.

Skills

Skill یک workflow قابل استفاده مجدد است. هر skill معمولاً یک SKILL.md دارد و می‌تواند references، scripts، examples و assets هم داشته باشد.

کاربردهای خوب:

• release workflow
• آماده‌سازی PR
• batch ترجمه
• پیاده‌سازی design
• گزارش data analysis
• security review
• migration playbook
• workflowهای پشتیبانی مشتری

نمونه ساده:

---
name: release-check
description: Prepare and verify a release branch. Use when the user asks to ship, release, or publish changes.
---

1. Inspect the diff and identify the release scope.
2. Run the project's documented checks.
3. Confirm generated assets are current.
4. Draft release notes with changed files and verification results.

می‌توانید skill را با $skill-name صدا بزنید یا اجازه دهید Codex با توجه به description آن را خودش انتخاب کند.

Plugins

Plugin بسته قابل نصب است و می‌تواند skill، MCP config، hook، asset و app integration داشته باشد. وقتی می‌خواهید workflow را بین چند توسعه‌دهنده یا تیم توزیع کنید، plugin مناسب‌تر است.

MCP Servers

MCP راه استاندارد اتصال Codex به ابزارها و context خارجی است.

MCP می‌تواند ارائه کند:

• tools
• resources
• prompts
• server instructions

افزودن MCP محلی:

codex mcp add context7 -- npx -y @upstash/context7-mcp

نمونه config:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

در CLI از /mcp برای دیدن سرورهای فعال استفاده کنید.

Hooks

Hookها اسکریپت‌هایی هستند که اطراف lifecycle Codex اجرا می‌شوند. برای validation، policy، logging، prompt scanning و guardrail مناسب‌اند.

نمونه TOML:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

Hookها را قبل از trust کردن بررسی کنید، چون hook command می‌تواند اسکریپت محلی اجرا کند.

Automations

Automationها taskهای تکرارشونده Codex را در پس‌زمینه اجرا می‌کنند.

کاربردها:

• بررسی status PR
• polling برای deployment طولانی
• گزارش هفتگی dependency
• تریاژ خطاهای تست
• summary روزانه changelog
• چک‌های امنیتی تکرارشونده

از thread automation وقتی استفاده کنید که context همین conversation باید حفظ شود. برای کارهای مستقل، automation پروژه‌ای یا standalone مناسب‌تر است.

---

بخش ۱۱: گردش کار در اپ Codex

اپ Codex کامل‌ترین سطح محلی است.

حالت‌های Local، Worktree و Cloud

وقتی چند کار مستقل دارید یا نمی‌خواهید checkout اصلی تغییر کند، از worktree استفاده کنید.

ابزارهای Git

اپ Codex diff نشان می‌دهد، stage/revert انجام می‌دهد، commit می‌سازد، push می‌کند و می‌تواند PR باز کند. برای عملیات پیشرفته‌تر از ترمینال داخلی استفاده کنید.

ترمینال داخلی

هر thread یک ترمینال scoped به project یا worktree دارد. Codex می‌تواند خروجی ترمینال را بخواند؛ مثلاً لاگ dev server یا خطای build را بدون copy/paste بررسی کند.

مرورگر داخلی

مرورگر داخلی برای local dev server، preview فایل و صفحات عمومی بدون sign-in مناسب است. می‌توانید روی UI کامنت بگذارید و از Codex بخواهید همان نقطه را اصلاح کند.

Computer Use

Computer use به Codex اجازه می‌دهد اپ دسکتاپ را ببیند، کلیک کند و تایپ کند. برای تست GUI، simulator، تنظیمات اپ و bugهای فقط‌دیداری مفید است. چون می‌تواند state خارج از repo را تغییر دهد، scope را محدود نگه دارید.

---

بخش ۱۲: افزونه IDE

افزونه IDE وقتی مفید است که context ادیتور مهم باشد.

اشاره به فایل‌ها

Use @CheckoutForm.tsx and @pricing.ts as context. Add a coupon validation state and update the tests.

Selection

کد را انتخاب کنید و از Codex بخواهید آن را توضیح دهد، refactor کند، تست بنویسد یا ریویو کند. برای تغییرات محدود، این روش دقیق‌تر است.

Agent، Chat و Full Access

• Agent: خواندن، ویرایش و اجرای command داخل project.
• Chat: پاسخ و plan بدون عمل مستقیم.
• Agent Full Access: دسترسی گسترده همراه با network؛ با احتیاط استفاده شود.

اجرای Cloud از IDE

برای taskهای بزرگ‌تر، یک cloud environment انتخاب کنید و کار را در Codex Cloud اجرا کنید. بعد از بررسی خروجی، می‌توانید ادامه را محلی انجام دهید.

---

بخش ۱۳: Codex Cloud

Codex Cloud taskها را در کانتینرهای مدیریت‌شده OpenAI اجرا می‌کند.

فرایند کلی:

1. Codex کانتینر می‌سازد و repo را روی branch یا commit انتخاب‌شده checkout می‌کند.
2. setup script اجرا می‌شود و می‌تواند برای نصب dependency به اینترنت وصل شود.
3. agent phase شروع می‌شود. دسترسی اینترنت agent به صورت پیش‌فرض خاموش است مگر اینکه فعال شود.
4. Codex فایل‌ها را ویرایش می‌کند، command اجرا می‌کند و نتیجه را validate می‌کند.
5. شما summary و diff را بررسی می‌کنید، follow-up می‌دهید یا PR می‌سازید.

پیکربندی Environment

موارد مهم:

• دسترسی repo
• setup script
• maintenance script
• نسخه runtimeها
• environment variableها
• secrets
• policy دسترسی اینترنت

Secretها فقط برای setup script در دسترس هستند و قبل از agent phase حذف می‌شوند.

چه زمانی Cloud بهتر است؟

Cloud مناسب است وقتی:

• می‌خواهید کار از checkout محلی جدا باشد
• task باید در پس‌زمینه اجرا شود
• خروجی باید به branch و PR تبدیل شود
• ماشین محلی dependency لازم را ندارد
• teammate باید نتیجه را در گیت‌هاب بررسی کند

Local مناسب‌تر است وقتی task به state خصوصی local، browser session، simulator، اپ دسکتاپ یا hardware وابسته است.

---

بخش ۱۴: بازبینی کد با Codex

Codex چند روش review دارد.

ریویوی محلی

داخل CLI:

/review

گزینه‌های رایج:

• review تغییرات uncommitted
• review نسبت به base branch
• review یک commit مشخص
• review با دستورالعمل سفارشی

ریویوی Pull Request در GitHub

بعد از راه‌اندازی Codex Cloud و code review برای repo، در PR بنویسید:

@codex review

برای تمرکز بیشتر:

@codex review for security regressions and missing edge-case tests

برای fix کردن یک finding:

@codex fix the P1 issue

Review Guidelines در AGENTS.md

## Review guidelines

- Prioritize bugs, data loss, auth mistakes, and security regressions.
- Treat missing tests on shared logic as P1.
- Do not comment on style unless it changes behavior or maintainability.

Codex نزدیک‌ترین AGENTS.md مرتبط با فایل تغییرکرده را اعمال می‌کند.

---

بخش ۱۵: Noninteractive Mode و CI

از codex exec وقتی استفاده کنید که Codex باید از script یا pipeline اجرا شود.

استفاده پایه

codex exec "summarize the repository structure and list the top 5 risky areas"

اجازه ویرایش:

codex exec --sandbox workspace-write "fix the failing unit test"

ریویوی read-only:

codex exec --sandbox read-only "review this repository for migration risk"

خروجی JSONL

codex exec --json "summarize the repo structure" | jq

خروجی JSONL می‌تواند شامل eventهای thread، command execution، تغییر فایل، MCP tool call، web search، plan update و پیام نهایی باشد.

خروجی ساختاریافته

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

Prompt به همراه stdin

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix"

این الگو برای لاگ، خروجی CI، traceهای HTTP، changelog و bug report مناسب است.

GitHub Action

برای اجرای Codex در GitHub Actions از openai/codex-action@v1 استفاده کنید. این روش بهتر از نصب دستی CLI و قرار دادن API key در shell step است.

قواعد امنیتی:

• محدود کردن افرادی که workflow را trigger می‌کنند
• permission کمینه برای repo
• قرار ندادن OPENAI_API_KEY در stepهای untrusted
• اجرای Codex نزدیک انتهای job
• ذخیره patch به عنوان artifact و باز کردن PR در job جداگانه با permission مناسب

---

بخش ۱۶: SDK

وقتی می‌خواهید Codex داخل ابزار داخلی شما اجرا شود، از SDK استفاده کنید.

TypeScript

npm install @openai/codex-sdk

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result);

Python

pip install openai-codex

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.4",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

SDK برای dashboardهای داخلی، review bot، ابزار release، migration assistant و workflowهایی مناسب است که باید thread را در چند run ادامه دهند.

---

بخش ۱۷: ورودی تصویری و تولید تصویر

Codex می‌تواند تصویر را به عنوان context بخواند.

codex --image screenshot.png "Explain the UI bug and suggest a fix"

چند تصویر:

codex --image before.png,after.png "Compare these states and identify regressions"

کاربردها:

• screenshot UI
• حالت خراب مرورگر
• design mockup
• دیاگرام معماری
• error dialog
• screenshot شبیه‌ساز موبایل

Codex در برخی سطح‌ها می‌تواند تصویر هم تولید یا ویرایش کند؛ برای assetهای UI، banner، placeholder، sprite sheet و reference illustration مفید است.

---

بخش ۱۸: Import از Claude Code

Codex مسیر import برای برخی تنظیمات Claude Code، فایل‌های پروژه و chatهای اخیر دارد.

در CLI:

/import

وقتی از قبل موارد زیر را دارید، import مفید است:

• فایل‌های instruction مربوط به Claude Code
• config سرورهای MCP
• skillها یا subagentها
• chatهای اخیر که می‌خواهید وارد Codex شوند

بعد از import، فایل‌های تولیدشده را بررسی کنید. مهاجرت بین ابزارها فرصت خوبی برای حذف راهنمایی‌های قدیمی و ساده‌سازی config است.

---

بخش ۱۹: workflowهای عملی

۱. شناخت repo جدید

Read the repository and explain the architecture. Include the main entry points, important commands, data flow, risky areas, and the first three tasks a new developer should do.

سپس:

Create an AGENTS.md draft from what you learned. Keep it short and include only commands and conventions Codex should follow every time.

۲. رفع bug با ریسک کم

Reproduce this bug from the failing test output below. Find the smallest fix, explain the root cause, update or add one focused test, and run only the relevant checks.

۳. ریویو قبل از PR

Review my uncommitted changes against origin/main. Prioritize P0/P1 defects, missed edge cases, data-loss risk, and missing tests. Do not comment on style unless it affects behavior.

۴. ساخت فیچر

Implement [feature]. First inspect existing patterns and write a short plan. Then make the change, update tests, run the relevant checks, and summarize the diff.

۵. QA فرانت‌اند

Start the dev server, use the in-app browser to inspect the changed page, verify desktop and mobile states, fix visible layout issues, and include screenshots or a clear visual summary.

۶. گزارش هفتگی خودکار

Create a weekly automation that checks this repo for merged PRs, failing checks, open release blockers, and dependency updates. Report only actionable findings.

۷. تریاژ خطای CI

gh run view 123456 --log \
  | codex exec "summarize the CI failure, identify the most likely root cause, and propose the smallest fix"

---

بخش ۲۰: بهترین روش‌ها

کانتکست درست بدهید

فایل‌ها، دستورها، خطاها و محدودیت‌های مهم را نام ببرید. اگر rule تجاری پنهان وجود دارد، صریح بگویید.

Definition of Done را مشخص کنید

مثلاً:

• تست مرتبط پاس شود
• lint یا build پاس شود
• screenshot درست باشد
• PR آماده باشد
• مستندات به‌روز شود
• فایل نامرتبط تغییر نکند

از Git checkpoint استفاده کنید

git status
git diff
git add path/to/file
git commit -m "Implement focused change"

task را کوچک نگه دارید

Codex می‌تواند کار بزرگ انجام دهد، اما کیفیت review وقتی بهتر است که task محدود باشد. تغییرات نامرتبط را در thread، worktree یا PR جدا نگه دارید.

اعتماد کنید، اما verify کنید

همیشه بررسی کنید:

• diff
• دستورهای تولیدشده
• نتیجه تست
• تغییر dependency
• migration
• کد حساس امنیتی
• فایل‌های خروجی و screenshotها

تکرار را به config تبدیل کنید

اگر یک دستورالعمل را چند بار تکرار کردید، آن را به یکی از این‌ها منتقل کنید:

• AGENTS.md
• skill
• hook
• MCP
• automation

---

کارت مرجع سریع

دستورهای روزانه

codex
codex --sandbox read-only
codex --sandbox workspace-write --ask-for-approval on-request
codex resume --last
codex doctor
codex exec "summarize this repo"
codex review
codex mcp --help
codex completion zsh

Slash commandهای روزانه

/status
/permissions
/model
/plan
/review
/diff
/mcp
/skills
/hooks
/compact
/exit

فایل‌های مهم

---

سوالات متداول

آیا OpenAI Codex رایگان است؟

طبق quickstart رسمی، همه پلن‌های ChatGPT شامل Codex هستند. همچنین می‌توانید با OpenAI API key و اعتبار API از Codex استفاده کنید. البته دسترسی قابلیت‌ها بین ورود با ChatGPT، ورود با API key و Codex Cloud می‌تواند متفاوت باشد.

چطور Codex CLI را نصب کنیم؟

در macOS یا Linux:

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

روش‌های دیگر:

npm install -g @openai/codex
brew install --cask codex

آیا Codex CLI همان اپ Codex است؟

مفهوم ایجنت و بخش زیادی از تنظیمات مشترک است، اما surfaceها فرق دارند. CLI ترمینال‌محور است؛ اپ Codex پروژه‌ها، threadها، worktree، اتوماسیون، ابزار Git، مرورگر داخلی، computer use و preview بهتر artifactها را اضافه می‌کند.

آیا Codex می‌تواند Pull Request گیت‌هاب را review کند؟

بله. بعد از راه‌اندازی Codex Cloud و code review برای repo، می‌توانید در PR بنویسید @codex review یا review خودکار را فعال کنید.

آیا Codex از MCP پشتیبانی می‌کند؟

بله. Codex در CLI و افزونه IDE از MCP serverها پشتیبانی می‌کند و اپ Codex هم همان تنظیمات MCP را استفاده می‌کند. MCP راه استاندارد اتصال Codex به ابزارهایی مثل مستندات، Figma، GitHub، browser automation، Sentry و سیستم‌های داخلی است.

آیا Codex در CI قابل اجراست؟

بله. برای اجرای noninteractive از codex exec استفاده کنید یا در GitHub Actions از openai/codex-action@v1 کمک بگیرید. credential را فقط به step مربوط به Codex بدهید و API key را در build stepهای untrusted قرار ندهید.

چطور از Codex امن استفاده کنیم؟

برای برنامه‌ریزی و review با read-only شروع کنید. برای توسعه عادی از workspace-write همراه با on-request استفاده کنید. Full access را فقط در محیط‌های ایزوله به کار ببرید. قبل از انتشار، diff، commandها، dependencyها، migrationها و نتیجه تست را بررسی کنید.

---

منابع رسمی

• Codex overview
• Codex quickstart
• Codex CLI
• Codex CLI command options
• Codex app features
• Codex IDE extension
• Codex cloud environments
• Agent approvals and security
• Config basics
• AGENTS.md guide
• Agent skills
• Model Context Protocol
• Hooks
• Automations
• Noninteractive mode
• Codex GitHub Action
• Codex SDK

---

نتیجه‌گیری

Codex را باید مثل یک همکار نرم‌افزاری قابل پیکربندی دید. CLI سرعت ترمینال را می‌دهد، افزونه IDE کانتکست ادیتور را اضافه می‌کند، اپ دسکتاپ هماهنگی، worktree و ابزارهای محلی را فراهم می‌کند، Cloud اجرای ایزوله پس‌زمینه را ممکن می‌کند و سطح‌های اتوماسیون Codex را وارد workflowهای تکرارشونده مهندسی می‌کنند.

ساده شروع کنید: Codex را نصب کنید، وارد حساب شوید، در حالت read-only از آن بخواهید repo را توضیح دهد، سپس برای یک bug کوچک به workspace-write بروید. وقتی این چرخه قابل اعتماد شد، AGENTS.md بسازید، sandbox و approval را تنظیم کنید، MCP وصل کنید، workflowهای تکراری را به skill تبدیل کنید و بخش‌های پایدار فرایند توسعه را automation کنید.