آموزش Qwen Code: راهنمای کامل ایجنت کدنویسی متن‌باز

Qwen Code ایجنت کدنویسی متن‌باز Qwen برای ترمینال است. این ابزار مخزن را می‌خواند و ویرایش می‌کند، ابزار shell و language server و وب را به‌کار می‌گیرد، تغییر را plan می‌کند، ساب‌ایجنت و agent team پایدار می‌سازد، کار را در Git worktree ایزوله می‌کند، Skill یاد می‌گیرد، context پروژه را به خاطر می‌سپارد و از طریق MCP، IDE، دسکتاپ، daemon، SDK، GitHub و پیام‌رسان کار می‌کند.

این آموزش در ۱۵ مرداد ۱۴۰۵ (۶ اوت ۲۰۲۶) با مستندات رسمی Qwen Code، مخزن رسمی و به‌روزرسانی ۳۰ ژوئیه تطبیق داده شد. این release نسخه‌های پایدار 0.21.0 و 0.21.1 را پوشش می‌دهد. Qwen Code تقریباً هر هفته تغییر می‌کند؛ با /about رفتار نسخه نصب‌شده را بررسی کنید.

اسکرین‌شات رسمی مخزن Qwen Code؛ مدل داخل تصویر نمونه است و default همیشگی نیست.

Qwen Code فقط کلاینت یک مدل نیست

Qwen Code یک agent harness است. مدل‌های Qwen تناسب مهمی دارند، اما کلاینت از پروتکل‌های Qwen، OpenAI-compatible، Anthropic-compatible و Gemini-compatible، ارائه‌دهنده‌های ثالث و server محلی مثل Ollama یا vLLM پشتیبانی می‌کند. انتخاب مدل با انتخاب پوسته ایجنت یکی نیست.

Qwen Code مناسب است اگر این موارد را می‌خواهید:

• ایجنت ترمینالی متن‌باز با release سریع؛
• مدل Qwen به‌صورت first-class همراه آزادی ارائه‌دهنده؛
• QWEN.md، auto-memory، Skill، hook، MCP و LSP؛
• ساب‌ایجنت، agent team، کار پس‌زمینه و worktree isolation؛
• TUI، CLI headless، IDE، دسکتاپ، Web Shell، daemon، SDK یا channel پیام‌رسان؛
• فرمان‌های داخلی review، goal، loop، plan، arena و workflow.

همین گستردگی سطح اعتماد را زیاد می‌کند. کلاینت متن‌باز محلی ممکن است کد را به مدل hosted، MCP بیرونی، Web Shell یا پیام‌رسان بفرستد. هر اتصال را مستقل بازبینی کنید.

نصب Qwen Code

مرور رسمی نصب‌کننده standalone را پیشنهاد می‌کند.

macOS یا Linux:

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh | bash

Windows PowerShell:

irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 | iex

Homebrew و npm نیز مستند شده‌اند:

brew install qwen-code
npm install -g @qwen-code/qwen-code@latest

مسیر npm اکنون Node.js 22 یا جدیدتر می‌خواهد. اگر qwen روی PATH نیست shell را دوباره باز و نسخه واقعی را بررسی کنید:

qwen --version
qwen --help

برای نصب آفلاین یا کنترل‌شده، installer رسمی archive و SHA256SUMS را می‌پذیرد. در تیم و CI نسخه آزموده‌شده را pin کنید تا تغییر هفتگی بدون review وارد production نشود.

احراز هویت و انتخاب ارائه‌دهنده دقیق

داخل پروژه اجرا و منوی provider را باز کنید:

cd /path/to/project
qwen

/auth

راهنمای فعلی احراز هویت این مسیرها را دارد:

• Alibaba ModelStudio: پلن Coding، پلن Token یا API key استاندارد؛
• ارائه‌دهنده ثالث: مسیر داخلی برای DeepSeek، Z.AI، MiniMax، OpenRouter و مواردی که زنده نشان داده می‌شوند؛
• custom provider: server محلی، proxy یا endpoint سازگار دیگر.

free tier قدیمی Qwen OAuth در ۱۵ آوریل ۲۰۲۶ متوقف شد. آموزش‌هایی که هنوز روزانه ۱۰۰۰ فراخوانی OAuth رایگان وعده می‌دهند قدیمی‌اند. API key را در متغیر محیطی یا credential store مستندشده نگه دارید، نه QWEN.md، settings.json، اسکرین‌شات، shell history یا Git.

با /model دقیقاً مدل‌های plan انتخابی را ببینید. یک نام مدل ممکن است در region یا router مختلف قیمت، context، modality و سیاست نگه‌داری متفاوت داشته باشد.

Qwen3.8 و شناسه دقیق preview

عبارت «Qwen 3.8» به مدل واقعی فعلی اشاره دارد. به‌روزرسانی ۲۳ ژوئیه Qwen Code مدل qwen3.8-max-preview را به فهرست ModelStudio Token Plan افزود. release ۳۰ ژوئیه نیز سازگاری modality تصویر Qwen3.8 را در کلاینت اصلاح کرد.

شناسه واقعی را به کار ببرید:

/model qwen3.8-max-preview

یا پس از پیکربندی:

qwen --model qwen3.8-max-preview

این مدل preview و endpoint استدلال‌محور است، نه نام عمومی همه deploymentهای Qwen. مطالعه موردی رسمی صریحاً می‌گوید منظورش از “qwen3.8-max” همان preview است. به‌جای حدس‌زدن qwen3.8 یا qwen3.8-plus، model picker زنده را ببینید.

برای کار code-first مدل‌های Qwen3-Coder موجود در plan را نیز مقایسه کنید. برای تصویر و ویدئو modality واقعی نسخه را ببینید و از نام Max نتیجه‌گیری نکنید. context بسیار بزرگ دلیل خوبی برای فرستادن کل مخزن در هر درخواست نیست؛ retrieval و خروجی ابزار محدود معمولاً سیگنال بهتر و هزینه کمتر دارد.

شروع امن در مخزن

پیش از اجرا:

git status --short --branch
qwen

Workspace Trust را فقط برای پوشه موردنظر تأیید کنید. ابتدا بررسی بدون mutation بخواهید:

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

سپس قرارداد اجرا را دقیق کنید:

یک تست رگرسیون fail بساز، باگ token منقضی را بازتولید کن، کوچک‌ترین اصلاح را
پیشنهاد بده، منتظر تأیید بمان، پیاده‌سازی کن، تست هدفمند و type check را اجرا و
diff نهایی را مرور کن. commit، push، publish یا deploy نکن.

برای context مشخص از @path/to/file و برای کار مبهم یا پراثر از /plan استفاده کنید. Plan mode فعلی برای خروج نیازمند تأیید صریح است و فرمان تغییر‌دهنده state را مسدود می‌کند.

نوشتن QWEN.md کوتاه و مفید

QWEN.md briefing پایدار پروژه است. راهنمای memory فایل global در ~/.qwen/QWEN.md، فایل تیم در ریشه پروژه و override محلی برای جزئیات commitنشده را توضیح می‌دهد. /init مخزن را تحلیل و starter می‌سازد یا برای فایل موجود پیشنهاد می‌دهد.

## Repository map

- `apps/web`: رابط Next.js مشتری
- `services/api`: مجوز و persistence
- `generated`: خروجی تولیدی؛ دستی تغییر نده

## Verification

- پس از هر تغییر رفتاری نزدیک‌ترین تست هدفمند را اجرا کن.
- پیش از تحویل `npm run typecheck` را اجرا کن.
- UI تغییرکرده را در عرض desktop و mobile بررسی کن.

## Safety

- تغییر نامرتبط working tree را حفظ کن.
- فایل `.env` را نخوان و ویرایش نکن.
- بدون مجوز صریح commit، push، merge، publish یا deploy نکن.

فایل را کوتاه و خاص نگه دارید. حقیقتی را که مدل با خواندن کد به‌سادگی پیدا می‌کند تکرار نکنید. به سند contributor موجود ارجاع دهید و خروجی /init را پیش از commit بازبینی کنید.

Plan، approval، auto mode و sandbox

Qwen Code برنامه‌ریزی، سیاست تأیید و ایزولیشن را جدا می‌کند:

• plan mode هنگام حل نیازمندی mutation را محدود می‌کند؛
• approval mode ابزار نیازمند تأیید انسان را تعیین می‌کند؛
• auto mode با classifier prompt عملیات کم‌ریسک را کم می‌کند؛
• sandbox دسترسی فرمان در مرز سیستم‌عامل را محدود می‌کند؛
• worktree isolation فایل و branch را برای کار موازی جدا می‌کند.

در مخزن ناآشنا با تأیید دستی و sandbox شروع کنید. راهنمای approval حالت‌های فعلی و کنترل صفحه‌کلید را توضیح می‌دهد. classifier خودکار ممکن است درباره فرمان ترکیبی، redirect، credential یا ابزار با نام گمراه‌کننده اشتباه کند. حتی با sandbox، credential تولید را بیرون process نگه دارید.

ساب‌ایجنت، Agent Team و worktree

Qwen Code ساب‌ایجنت محدود، agent پس‌زمینه، fork و Agent Team آزمایشی پایدار دارد. نسخه جدید nested subagent، سقف concurrency بر اساس مدل، fork_turns انتخابی، بازیابی background agent میان sessionها و ادامه گفتگو با agent تمام‌شده بدون ساخت دوباره state را اضافه کرده است.

اسکرین‌شات رسمی Qwen Code؛ child agent دیده می‌شود و نمی‌تواند تأیید لازم را پنهانی دور بزند.

parallelism را برای task مستقل به کار ببرید: نقشه مخزن، بررسی تست، پژوهش سند یا review فقط‌خواندنی. برای هر agent مالک، مرز فایل، قالب خروجی و شرط پایان تعریف کنید. برای پیاده‌سازی موازی worktree isolation بگذارید تا فایل‌ها overwrite نشوند. leader باید تغییرها را مرحله‌ای ادغام و gate کامل را اجرا کند.

Agent Team پیام و task list مشترک دارد. feature آزمایشی را فقط پس از خواندن تنظیمات نسخه نصب‌شده فعال و concurrency را بر اساس مدل/provider محدود کنید. ایجنت بیشتر اغلب جست‌وجوی تکراری و هزینه بیشتر می‌سازد، نه سرعت واقعی.

Skill، /learn، memory، hook، MCP و LSP

لایه توسعه Qwen Code گسترده است:

• Skill روند قابل تکرار را در پوشه SKILL.md بسته‌بندی می‌کند؛
• /learn متن، سند، وب، پوشه و اکنون ویدئو را با provenance به Skill تبدیل می‌کند؛
• auto-memory context منتخب را میان sessionها نگه می‌دارد؛
• team memory قابل اشتراک و همگام‌سازی اختیاری است؛
• hook بررسی قطعی lifecycle را اجرا می‌کند؛
• MCP سرویس و داده بیرونی می‌آورد؛
• LSP diagnostic و symbol intelligence می‌دهد.

نسخه 0.21 پوشه Skill سفارشی دارد تا کتابخانه بازبینی‌شده میان agentهای سازگار مشترک باشد. Skill تولیدشده به منبع متکی است اما الزاماً execution-verified نیست؛ SKILL.md، script، download و عمل بیرونی را پیش از فعال‌سازی ببینید. در کار حساس auto-memory را خاموش و محتوای /memory را بازبینی کنید.

MCP را تک‌تک با credential کم‌اختیار و allowlist ابزار اضافه کنید. محتوای وب، issue، سند یا پیام بیرونی را untrusted بدانید. برای بررسی همیشگی مثل formatter، secret scan یا تست هدفمند از hook استفاده کنید، نه برای deploy خودکار.

انتخاب سطح مناسب

پروژه رسمی این سطح‌ها را دارد:

• qwen برای TUI تعاملی؛
• qwen -p "..." برای script و CI؛
• integrationهای VS Code، Zed و JetBrains؛
• Qwen Code Desktop برای macOS، Windows و Linux؛
• qwen serve برای daemon آزمایشی HTTP+SSE/ACP؛
• SDKهای TypeScript، Python و Java؛
• channelهای Telegram، DingTalk، WeChat، Feishu، GitHub و پلتفرم مستند دیگر؛
• Web Shell برای session، Git، channel و مدیریت فایل در مرورگر.

هر سطح مرز اختیار را تغییر می‌دهد. GitHub یا پیام‌رسان محتوای کاربر نامطمئن، token طولانی‌عمر، نگاشت هویت و خطر loop می‌آورد. triggerکننده را محدود، حساب اختصاصی کم‌اختیار و protected branch را الزامی کنید. qwen serve را بدون auth و transport مناسب در شبکه نامطمئن منتشر نکنید.

Headless، خروجی ساختاریافته و schedule

یک فراخوانی فقط‌خواندنی:

qwen -p "فایل‌های تغییرکرده را خلاصه و تست جاافتاده را مشخص کن"

Qwen Code خروجی محدود به JSON Schema، dual output، session management و /loop زمان‌بندی‌شده دارد. /goal نیز با judge model و تشخیص هدف غیرممکن کار می‌کند. این قابلیت‌ها برای eval و نگه‌داری مفیدند، اما مجوز تغییر state بیرونی ایجاد نمی‌کنند.

برای CI:

1. checkout موقت و sandbox به کار ببرید؛
2. token را تا حد ممکن فقط‌خواندنی کنید؛
3. نسخه Qwen Code و model ID را pin کنید؛
4. turn، ابزار، زمان و هزینه را محدود کنید؛
5. JSON، exit status، diff و artifact تست را اعتبارسنجی کنید؛
6. برای PR، merge، release یا deploy تأیید انسان بخواهید.

با /stats درخواست، tool call، file change، تخمین هزینه، TTFT و throughput را ببینید. مدل را با کار پذیرفته‌شده مقایسه کنید، نه فقط token در ثانیه.

گردش‌کار کامل Qwen Code

1. Open narrowly: فقط مخزن یا package معتبر را باز کنید؛
2. Read instructions: QWEN.md، override، Skill، hook و MCP را ببینید؛
3. Reproduce: تست fail، log یا رفتار قابل مشاهده ثبت کنید؛
4. Plan: scope، تست پذیرش و عمل ممنوع را روشن کنید؛
5. Isolate: پیش از ویرایش branch یا worktree بسازید؛
6. Implement: هنگام drift با real-time steering مسیر را اصلاح کنید؛
7. Verify: تست هدفمند، gate گسترده و QA runtime/browser را اجرا کنید؛
8. Review: /diff یا Git و سپس بازبین مستقل فقط‌خواندنی؛
9. Handoff: فرمان، مدرک، ریسک، هزینه و عمل بیرونی انجام‌نشده را گزارش کنید.

پیش از commit از /review، برای پرسش جانبی بدون برهم‌زدن context از /btw، برای summary فقط‌خواندنی session قبلی از @ و برای سنجش از /stats استفاده کنید. هیچ‌کدام جای source control نیست.

رفع اشکال

آموزش احراز هویت مطابقت ندارد: OAuth رایگان متوقف شده است. Qwen Code را به‌روز و از /auth با ModelStudio، third-party یا custom provider فعلی استفاده کنید.

qwen3.8 پیدا نمی‌شود: /model را اجرا و اگر Token Plan و region شما دارد، شناسه دقیق qwen3.8-max-preview را بزنید. alias نسازید.

QWEN.md نادیده گرفته می‌شود: working directory، نام و case فایل، hierarchy، override محلی و /memory را بررسی و دستور متناقض را کوتاه کنید.

مدل loop یا تکرار می‌کند: اجرا را قطع، diff را ذخیره، session تازه با context کمتر بسازید، کلاینت را به‌روز و fallback آزموده‌شده را امتحان کنید. stream runaway را بدون سقف رها نکنید.

agentهای موازی conflict دارند: متوقف کنید، worktree و branchها را ببینید، هر بار یک diff ادغام و کل gate را دوباره اجرا کنید.

MCP یا daemon گیر می‌کند: server مشکوک را خاموش، transport/auth/timeout را بررسی، در صورت پشتیبانی force reconnect و اتصال‌ها را یکی‌یکی فعال کنید.

پرسش‌های رایج

آیا Qwen Code رایگان است؟

کلاینت متن‌باز است. فراخوانی مدل hosted، پلن ModelStudio، router، sandbox ابری و سرویس بیرونی قیمت خود را دارد. free tier قدیمی Qwen OAuth دیگر وجود ندارد.

آیا فقط با مدل Qwen کار می‌کند؟

خیر. چند پروتکل سازگار، provider ثالث و endpoint محلی دارد. کیفیت tool use مدل‌ها فرق دارد؛ هر گزینه را با تست پذیرش یکسان مخزن بسنجید.

آیا Qwen3.8 open weights است؟

شناسه‌ای که اکنون Qwen Code مستند می‌کند qwen3.8-max-preview از ModelStudio Token Plan است. از نام خانواده نتیجه نگیرید که weights منتشر شده؛ صفحه رسمی مدل و license همان artifact را ببینید.

Qwen Code یا OpenCode؟

OpenCode پوسته متن‌باز و چندارائه‌دهنده دیگری با ترمینال، دسکتاپ، IDE، server، SDK و GitHub است. Qwen Code در agent team، memory، channel، Web Shell، Skill و اتصال مدل Qwen سرعت توسعه بالایی دارد. هر دو را با یک task بسنجید.

برای انتخاب مدل‌به‌مدل، راهنمای Qwen3.8، GLM-5.2 و DeepSeek-V4 را ببینید.

یادداشت منابع

بازبینی‌شده در ۱۵ مرداد ۱۴۰۵ / ۶ اوت ۲۰۲۶:

• مرور Qwen Code
• مخزن رسمی Qwen Code
• احراز هویت
• ارائه‌دهنده مدل
• memory و QWEN.md
• approval mode
• Skill
• به‌روزرسانی ۲۳ ژوئیه و Qwen3.8 preview
• به‌روزرسانی ۳۰ ژوئیه و قابلیت‌های 0.21