
آموزش کامل OpenCode: راهنمای جامع ایجنت کدنویسی متنباز
OpenCode را از نصب و اتصال مدل تا AGENTS.md، ایجنتهای plan و build، مجوزها، Skill، MCP، پلاگین، IDE، دسکتاپ، سرور و GitHub یاد بگیرید.
ادامه مطلبتیم ژرف ایآی

OpenAI Codex عامل کدنویسی است که میتواند مخزن را بررسی کند، فایل را ویرایش کند، فرمان اجرا کند، تغییر را بیازماید، تفاوتها را بازبینی و یک کار مهندسی چندمرحلهای را دنبال کند. واژه مهم «عامل» است: Codex به جای تحویل یک قطعه کد، در محیطی که شما مجاز کردهاید کار میکند و برای درستی تغییر مدرک جمع میکند.
این راهنما در ۱۵ مرداد ۱۴۰۵ / ۶ اوت ۲۰۲۶ با راهنمای جاری OpenAI و یک نصب محلی Codex CLI دوباره اعتبارسنجی شده است. Codex سریع تغییر میکند؛ نام محیط، مدل، دسترسی، فرمان و شیوه نصب ممکن است عوض شود. برای وضع روز، مستندات رسمی Codex، راهنمای جاری محصول و تاریخ تغییرات رسمی را ببینید. دسترسپذیری همچنان به طرح، سیاست فضای کاری، سکو، منطقه، روش ورود و بلوغ قابلیت وابسته است.

Codex در چند محیط با مزیتهای متفاوت ارائه میشود:
codex exec و اسکریپت لازم دارید.صفحه جاری Codex CLI کار روی مخزن محلی، مجوز قابل تنظیم و استفاده تعاملی یا اسکریپتی را توضیح میدهد. راهنمای آغاز OpenAI نیز تجربه رومیزی و گزینههای CLI، IDE، وب و ابر را معرفی میکند. مقاله قدیمی ممکن است محصول رومیزی را فقط «اپ Codex» بنامد؛ نام رسمی جاری سکوی خود را ملاک بگیرید.
کوچکترین محیط متناسب با کار را انتخاب کنید. توضیح یک فایل شاید در IDE بهتر باشد؛ مهاجرت مخزن همراه آزمون در کاری مستقل؛ و تحلیل تکرارشونده در CI با حالت غیرتعاملی. توان مدل تنها بخشی از سامانه است؛ محیط، زمینه، مجوز و راستیآزمایی نتیجه را تعیین میکنند.
تا ۶ اوت ۲۰۲۶، صفحه رسمی برای macOS و Linux نصبکننده مستقل را پیشنهاد میکند:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
وارد پروژه شوید:
cd /path/to/your/repository
codex
در نخستین اجرا یکی از روشهای ورود موجود را انتخاب کنید. شیوه احراز هویت و دسترسی به قابلیتها ممکن است متفاوت باشد؛ مستندات رسمی احراز هویت را ببینید. کلید API بهتنهایی دسترسی فضای کاری ChatGPT، کار ابری یا اتصالدهنده را نمیدهد.
بررسیهای محلی:
codex --version
codex --help
codex doctor
نسخه محلی بررسیشده برای این مقاله حالت تعاملی و فرمانهایی مانند exec، review، مدیریت MCP و افزونه، ورود، بهروزرسانی، سندباکس، ادامه یا شاخهزدن نشست و مرور کار ابری داشت. بعضی فرمانها در راهنما آزمایشیاند؛ بدون بررسی نسخه و سند، کار حیاتی را به آنها وابسته نکنید.
در حالت تعاملی، نمونههای رسمی شامل /status برای تنظیمات، /permissions برای مجوز، /model برای مدل و میزان استدلال، /review برای بازبینی و /init برای ساخت راهنمای مخزن است. این مثالها تاریخدارند؛ اگر نسخه شما متفاوت است راهنمای همان نصب را ببینید.
«برنامه را درست کن» مشخصات نیست. درخواست خوب، نتیجه، مدرک، مرز و تعریف پایان را بیان میکند:
خطای ارسال دوباره invoice را رفع کن.
با test موجود بازتولید کن یا test متمرکز failing اضافه کن.
مسیر request را از API تا persistence trace کن.
کوچکترین fix بدون تغییر رفتار دیگر را بساز.
schema دیتابیس و formatting نامرتبط را تغییر نده.
ابتدا test متمرکز و سپس suite مرتبط را اجرا کن.
diff نهایی را برای regression review و ریسک باقیمانده را گزارش کن.
این موارد را وارد کنید:
برای کار ناآشنا پس از بررسی، برنامهای کوتاه بخواهید. برای اصلاح کوچک و روشن، اجازه اقدام مستقیم بدهید. برنامهریزی هنگام وجود معماریهای رقیب یا تصمیم برگشتناپذیر ارزش دارد؛ وقتی گام امن بعدی معلوم است فقط هزینه میافزاید.
Codex زمانی بهترین نتیجه را میدهد که چرخه را ببندد: خواندن، ویرایش، اجرا، بازرسی و اصلاح. عاملهای مهندسی نرمافزار الگوی عمومی و محدودیت آن را توضیح میدهد.
درخواست برای یک کار است؛ AGENTS.md قراردادهای تکرارشونده مانند معماری، فرمان، فایل تولیدی، انتظار آزمون، اولویت بازبینی و خطر محلی را بیان میکند.
راهنمای رسمی AGENTS.md دستور لایهای را مستند میکند. فایل ریشه را کوتاه نگه دارید و راهنمای ویژه هر زیرشاخه را نزدیک همان کد قرار دهید.
## Repository map
- `apps/web`: رابط Next.js
- `services/api`: API و business rule
- `packages/schema`: generated؛ دستی edit نکن
## Verification
- برای تغییر API تست مرتبط را اجرا کن.
- پیش از handoff lint را اجرا کن.
- UI را در desktop و mobile verify کن.
## Safety
- migration production اجرا نکن.
- `.env` و credential را تغییر یا commit نکن.
- تغییر نامرتبط worktree را حفظ کن.
دستور باید برای مهندس دیگری نیز قابل اجرا باشد. «مواظب باش» ضعیف است؛ «مهاجرت تولید را اجرا نکن، SQL بساز و برای تأیید توقف کن» عملی است. جزئیات موقت مسئله در درخواست بماند، نه راهنمای دائمی.
Codex میتواند فایل بخواند، فضای کار را ویرایش کند، فرمان اجرا کند و در صورت فعالبودن به شبکه یا ابزار بیرونی برسد. تنظیم امن به کار بستگی دارد.
نسخه جاری CLI حالتهای فقطخواندنی، نوشتن در فضای کار و دسترسی کامل و همچنین سیاست تأیید دارد. مستندات رسمی امنیت Codex مرجع روز مدل مجوز است.
اصول:
از --dangerously-bypass-approvals-and-sandbox فقط وقتی استفاده کنید که فرایند عمداً در سندباکس بیرونی قوی اجرا میشود. نام پرچم هشدار دقیقی است.
تنظیمات میتواند در فایل Codex و گزینه فرمان باشد. config.toml قدیمی را کورکورانه کپی نکنید؛ کلید و مقدار تغییر میکند. مرجع زنده پیکربندی را برای نسخه خود ببینید و در صورت پشتیبانی، اعتبارسنجی سختگیرانه را فعال کنید.

این سطحها مسئلههای متفاوتی حل میکنند:
کوچکترین سطح را برگزینید. اگر مخزن فقط npm test میخواهد، AGENTS.md کافی است. بازبینی امنیتی تکراری با مرجع و اسکریپت به مهارت نیاز دارد. پرسوجوی سامانه مسائل خصوصی باید با ابزار مجاز انجام شود، نه چسباندن دستی. منع مکانیکی فرمان ممنوع با قلاب یا سیاست مدیریتی از متن قویتر است.
برای MCP:
codex mcp --help
codex mcp list
فقط سرور مورد اعتماد بیفزایید. فایل اجرایی یا نشانی، اعتبارنامه، ابزار، مقصد داده و فرایند بهروزرسانی را بازبینی کنید. سند مخرب میتواند دستور تزریق کند؛ اجازه ابزار نباید به اطاعت از متن سند وابسته باشد.
نمایه رسمی OpenAI صفحههای جدا برای MCP، مهارت، افزونه و قلاب دارد. چون این سطحها در حال تغییرند، ساختار و فرمان دقیق را همانجا بررسی کنید.

نسخه رومیزی برای فایل محلی، بازبینی دیداری، کار طولانی یا توان بیرون ترمینال مفید است. فقط پوشه لازم را باز کنید. برای اجرای مستقل از فضای کاری جدا استفاده کنید تا کارهای موازی تغییر هم را بازنویسی نکنند.
IDE هنگامی قویتر است که انتخاب و فایل باز زمینه مفیدی میدهند؛ اما رفتار و آزمون را همچنان صریح بگویید. برجستهکردن کد، مشخصات کامل نیست.
ابر به دسترسی مخزن، وابستگی، راز و فرمان آمادهسازی نیاز دارد. راز را محدود و دورهای تعویض کنید. ابر نمیتواند خدمت یا دستگاه فقطمحلی را بدون دسترسی مناسب بیازماید. پیش از ادغام، تفاوت و مدرک آزمون را ببینید.
کار موازی وقتی وظایف جدا هستند مفید و وقتی فایل مشترک، رابط نامعلوم یا وضعیت تغییرپذیر مشترک دارند زیانبار است. مرز مالکیت و قرارداد اتصال را نخست تعیین کنید.

تصویر رسمی OpenAI؛ کنترل دقیق به محیط، سکو، workspace و rollout بستگی دارد.
Codex میتواند planning را از implementation جدا کند. در CLI از mode control نسخه نصبشده—راهنمای رسمی /plan و تغییر mode را مستند کرده—استفاده کنید تا عامل پیش از edit، فایل، dependency و ترتیب قابلverification را پیدا کند.
plan mode برای تغییر چند package، contract، migration یا reproduction نامطمئن ارزش بیشتری دارد. از plan بخواهید رفتار فعلی و evidence، file و ownership، compatibility داده/API، verification متمرکز و گسترده، rollout/rollback و سؤال باز پیش از mutation را پوشش دهد.
برای کار بسیار طولانی execution plan را در artifact task یا مخزن نگه دارید و با تغییر evidence بهروز کنید. plan سند هماهنگی زنده است، نه permission اجرای خودکار همه stepها.
Codex فعلی delegation صریح به subagent و هماهنگی موازی را پشتیبانی میکند. در CLI، /agent در نسخههای پشتیبانیشده عامل فعال را نشان میدهد یا امکان جابهجایی میدهد. تعریف پایدار عامل سفارشی میتواند در .codex/agents/*.toml با نقشهایی مانند explorer، reviewer یا specialist worker قرار گیرد.
subagent را برای evidence مستقل بهکار ببرید: mapping package جدا، پژوهش گزینه مستقل، reproduction defect یا review امنیت و تست. یک integration owner نگه دارید. write موازی باید worktree جدا یا file ownership کاملاً مجزا داشته باشد؛ در غیر این صورت فرضهای یکدیگر را خراب میکنند.
child agent مرز امنیتی نیست و خروجی delegateشده trusted نمیشود. source، diff، command و test واقعی را review کنید. multi-agent هزینه token و coordination را چندبرابر میکند؛ برای تغییر وابسته یک agent محدود پیشفرض بهتر است. راهنمای subagent syntax جاری را نشان میدهد.
Projectها context و chat مرتبط را گروهبندی میکنند. برای outcome مستقل chat جدا بسازید و definition of done روشن بدهید. thread طولانی تصمیم مفید نگه میدارد اما فرض stale هم جمع میکند؛ هنگام resume مخزن و درخواست جاری را دوباره بخوانید.
در app رومیزی، Git worktree به chatهای مستقل checkout جدا از یک project میدهد. این امنترین پیشفرض برای implementation موازی و scheduled work است. راهنمای رسمی worktree handoff و cleanup را توضیح میدهد.
worktree فقط file را جدا میکند. database، cloud، cache، queue، account و deployment همچنان میتوانند مشترک باشند؛ resource جدا بدهید یا operation بیرونی را read-only نگه دارید.
Codex فعلی فراتر از terminal است:
هرکدام permission و trust boundary متفاوت دارد. متن وب و screenshot ورودی غیرقابلاعتماد هستند. session لاگینشده میتواند داده خصوصی و side effect بیرونی داشته باشد. خواندن صفحه مجوز ارسال پیام، submit form، تغییر permission، publish، purchase یا upload نیست.
Browser Developer mode را فقط برای debug نیازمند دسترسی عمیقتر فعال کنید. responsive UI، RTL/LTR، console، network و production URL نهایی را verify کنید؛ build موفق پذیرش بصری نیست.
منابع رسمی: Browser، Computer Use، image generation، visualization و Sites.
memory جریان شخصی مفید را میان کارها نگه میدارد اما جای AGENTS.md نیست: memory user-scoped و driftپذیر است؛ instruction مخزن policy تیمی versioned و reviewable است. secret، پیام خصوصی، credential، OTP، رکورد محافظتشده یا داده شخصی اتفاقی را نگه ندارید و memory stale را حذف کنید.
scheduled task یک prompt آزموده را روی project محلی یا cloud تکرار میکند. ابتدا method را در skill یا workflow صریح تعریف و دستی اجرا، سپس schedule کنید. task امن scope محدود، سقف cost/time، رفتار no-data، duplicate detection، worktree جدا برای Git change و approval انسانی پیش از publish، message، merge، deploy یا تغییر external system دارد.
برای local file app باید هنگام schedule در دسترس باشد. در folder بدون Git ممکن است task مستقیم روی project کار کند؛ project versioned یا کپی یکبارمصرف بهتر است. راهنمای memory و scheduled task را ببینید.
برای integration بهجای scrape متن terminal از interface پشتیبانیشده استفاده کنید:
codex exec برای script و CI؛این interfaceها output عامل را deterministic نمیکنند. version، model، prompt، revision، sandbox/permission، tool event، exit، test و diff نهایی را ثبت کنید. security scan evidence محدود است، نه audit certification؛ finding مهم و fix را مستقل verify کنید.
از developer workflows، Codex SDK، App Server و Codex Security CLI شروع کنید.
Codex میتواند تغییر محلی و گردش کارهای پشتیبانیشده درخواست ادغام GitHub را بازبینی کند. راهنمای رسمی بازبینی کد مسیر جاری را شرح میدهد.
codex review
بخواهید درستی، امنیت، از دسترفتن داده، همزمانی، سازگاری و آزمون مفقود را پیش از سبک ببیند:
## Review priorities
- ابتدا authorization bypass و tenant-data leak.
- migration را برای rollback و mixed-version check کن.
- generated file را output بدان، نه source edit.
- فقط finding عملی با file و line evidence گزارش کن.
بازبینی هوش مصنوعی اختیار ادغام نیست. آزمون، تحلیل ایستا، بررسی نوع، ابزار امنیت و بازبینی انسانی متناسب را اجرا کنید. «یافتهای نیست» اثبات ایمنی نیست.
codex exec غیرتعاملی و مناسب اسکریپت یا CI است. با تحلیل فقطخواندنی آغاز کنید:

codex exec "diff جاری را برای ریسک correctness بررسی کن؛ فایل را تغییر نده."
برای خودکارسازی:
کد خروج صفر تنها دروازه نباشد. پرونده را بررسی کنید: آزمون، فایل مورد انتظار، مسیر ممنوع، راز و سازگاری با درخواست.
راهنمای مخزن، وضعیت، کد مرتبط، آزمون و تاریخ را بخواند و تغییر کاربر را حفظ کند.
آزمون شکستخورده، امضای لاگ، تصویر یا سناریوی قطعی پیدا کنید. مسئله حدسی را اصلاح نکنید.
فایل مجاز، اقدام ممنوع، سازگاری و نقطه تأیید را روشن کنید.
کوچکترین تغییر منسجم؛ ویژگی بزرگ با ایستگاههای قابل بازبینی.
نخست آزمون متمرکز و سپس بررسی گسترده متناسب. رابط با مدرک مرورگر، عملکرد با خط پایه و مهاجرت با مسیر رفت و برگشت.
git diff، بازبینی Codex و بازبینی انسان؛ پرونده تولیدی، قفل وابستگی و تنظیمات باید عمدی باشند.
نتیجه، فایل، فرمان، مدرک، محدودیت و گام بعد را بگویید. ادغام یا انتشار را بدون راستیآزمایی اعلام نکنید.
این چرخه ردپای لازم برای مشاهدهپذیری عامل را نیز میسازد.
پیش از ادغام:
Codex را با نتیجه پذیرفتهشده بسنجید، نه خط کد تولیدی. زمان تا بازبینی، قبولی نخستین آزمون، یافته بازبینی، بازگردانی، نقص فراری، افزایش مجوز و سهم کار دارای مدرک سنجههای بهتریاند.
زمینه ناکافی: فایل آشکار اصلاح و قرارداد پاییندست فراموش میشود. معماری بدهید و ردیابی فراخواننده بخواهید.
دامنه بیش از حد: اصلاح کوچک به بازآرایی تبدیل میشود. هدف خارج دامنه و بازبینی زودهنگام تفاوت را مشخص کنید.
پایان کاذب: عامل پس از آزمون باریک موفقیت اعلام میکند. بررسی لازم را صریح کنید.
آسیب فضای کاری ناتمیز: تغییر موجود بازنویسی یا وارد ثبت میشود. وضعیت و حفظ تغییر نامرتبط را بخواهید.
گسترش مجوز: فرمان مسدود به دسترسی کامل منجر میشود. فقط اقدام محدود را تأیید کنید.
راهنمای محصول کهنه: فرمان یا مدل کپیشده دیگر وجود ندارد. راهنما را تاریخدار و به سند رسمی وصل کنید.
سوگیری خودکارسازی: توضیح صیقلی بازبین را آرام میکند. آزمون، مدرک و بازرسی مستقل لازم است.
خیر. تا ۳۰ ژوئیه ۲۰۲۶، سند رسمی Codex را در تجربه رومیزی و وب ChatGPT، CLI، افزونه IDE و ابر توضیح میدهد؛ دسترسی متفاوت است.
بله، در محیط و حدود مجوز دادهشده. سندباکس و تأیید متناسب بگذارید.
بله، سازوکار رسمی راهنمای مخزن و دستور لایهای است.
بله، سند رسمی گردش کار محلی و GitHub پشتیبانیشده را دارد. CI و بازبینی انسان همچنان لازماند.
بله، codex exec غیرتعاملی است. محیط دورریختنی، اعتبارنامه محدود و دروازه قابل سنجش ماشین لازم است.
بهطور پیشفرض نه. کمترین دسترسی و افزایش محدود را به کار ببرید.
دسترسی و پیشنهاد تغییر میکند. انتخابگر و سند جاری را ببینید و روی کار واقعی مخزن خود ارزیابی کنید. Qwen3.8، GLM-5.2 و DeepSeek-V4 در harness چندارائهدهنده بررسی شدهاند؛ این راهنما ادعا نمیکند مدل ثالث را میتوان داخل Codex انتخاب کرد.
تسلط، حفظ فرمانهای خط مورب نیست. باید پیرامون عامل قرارداد مهندسی قابل اعتماد بسازید: راهنمای پایدار مخزن، مجوز محدود، کار بازتولیدپذیر، ابزار مناسب، راستیآزمایی اجرایی، بازبینی و تحویل صادق. وقتی چرخهای درست شد، بخش تکراری را در AGENTS.md، تنظیمات، مهارت یا CI ثبت کنید و جزئیات ناپایدار محصول را تاریخدار و متصل به سند رسمی نگه دارید.
منابع بررسیشده و جاری تا ۱۵ مرداد ۱۴۰۵ / ۶ اوت ۲۰۲۶:

OpenCode را از نصب و اتصال مدل تا AGENTS.md، ایجنتهای plan و build، مجوزها، Skill، MCP، پلاگین، IDE، دسکتاپ، سرور و GitHub یاد بگیرید.
ادامه مطلب
با این آموزش جامع Claude Code را یاد بگیرید. نصب، پیکربندی، سرورهای MCP، هوکها، یکپارچهسازی با IDE و ویژگیهای پیشرفته. راهنمای کامل ابزار CLI هوش مصنوعی Anthropic برای توسعهدهندگان.
ادامه مطلب
راهنمای عملیاتی برای تصمیمگیری درباره تلاش دوباره، اجرای موازی، تغییر مسیر یا تطبیق نتیجه در گردشکار هوش مصنوعی؛ بدون تبدیل ابهام زمانپایان به اقدام تجاری تکراری.
ادامه مطلببا تیم ما تماس بگیرید و درباره نحوه کمک به کسبوکار خود صحبت کنید.