Qwen Code در ویندوز؛ نصب امن عامل کدنویسی ترمینال و Sandbox

Qwen Code یک عامل کدنویسی متن‌باز و Terminal-first است. می‌تواند Repository را بررسی کند، فایل‌ها را تغییر دهد، فرمان‌های Shell را اجرا کند، نتیجه Test را بخواند و برای انجام یک هدف چند مرحله پیش برود. این توانایی با یک Chat ساده فرق دارد: Agent فقط پیشنهاد نمی‌دهد؛ در صورت داشتن مجوز می‌تواند روی محیط واقعی شما اثر بگذارد.

در این آموزش Qwen Code را در ویندوز نصب می‌کنیم، روش اتصال Provider را می‌بینیم و سپس Trusted Folder، Sandbox، تنظیمات پروژه و Workflow نخستین Task را ایمن می‌کنیم. هدف این نیست که همه درخواست‌ها را خودکار تأیید کنیم؛ هدف ساختن حلقه‌ای است که Agent پیشنهاد و اجرا کند و توسعه‌دهنده Scope، Permission، Diff و نتیجه را کنترل کند.

Qwen Code چیست؟

Qwen Code ابزار Agentic Coding پروژه Qwen است که در ترمینال اجرا می‌شود و برای مدل‌های خانواده Qwen بهینه شده، اما در نسخه فعلی می‌تواند با Providerهای داخلی دیگر یا Provider سفارشی نیز کار کند. Agent از ابزارهایی مانند خواندن و نوشتن فایل، جست‌وجوی کد، Shell و در صورت تنظیم، LSP و MCP استفاده می‌کند.

خود Qwen Code مدل زبانی نیست. Provider، Model و Credential جداگانه انتخاب می‌شوند. کیفیت Tool Calling، Context Window، هزینه، سیاست نگه‌داری داده و تاخیر Provider روی تجربه نهایی اثر دارد. قبل از دادن کد خصوصی، شرایط داده سرویس انتخابی را بخوانید.

رابط‌های Qwen Code

برای یادگیری، Terminal Interactive داخل یک Repository آزمایشی بهترین نقطه شروع است. Headless را زمانی فعال کنید که Prompt، Permission، Timeout، Secret، Artifact و Rollback در محیط جداگانه آزموده شده باشند.

پیش‌نیازهای ویندوز

• Windows 10 یا 11 به‌روز و PowerShell قابل استفاده
• Git برای Branch، Diff و بازگشت تغییرها
• Docker Desktop یا Podman در صورت استفاده از Sandbox کانتینری
• Node.js 22 یا جدیدتر فقط برای مسیر نصب npm
• یک Provider سازگار و Credential کم‌دسترسی
• Repository آزمایشی بدون Secret و داده مشتری

Installer مستقل Runtime خصوصی خودش را دارد و معمولاً Node.js محلی نمی‌خواهد. اگر Installer مجبور شود به npm برگردد یا خودتان روش npm را انتخاب کنید، Node.js 22 و npm باید در PATH باشند. این تفاوت را پیش از عیب‌یابی خطای نصب در نظر بگیرید.

بررسی محیط

$PSVersionTable.PSVersiongit --versionnode --versionnpm --versiondocker version

لازم نیست همه فرمان‌ها موفق شوند. برای نصب مستقل، نبود Node قابل قبول است و Docker فقط وقتی Sandbox کانتینری می‌خواهید لازم می‌شود. خطا را با نیاز واقعی روش انتخابی مقایسه کنید.

روش‌های رسمی نصب Qwen Code

README رسمی فرمان کوتاه irm و iex را برای Windows نشان می‌دهد، اما اجرای مستقیم محتوای شبکه بدون مشاهده Script امکان ممیزی را کم می‌کند. روش محافظه‌کارانه این است که Script یا Release Archive را از منبع رسمی دریافت، محتوا و Hash را بررسی و سپس اجرا کنید. برای محیط سازمانی نسخه را Pin و Artifact را در مخزن داخلی تأییدشده نگه دارید.

نصب با npm در ویندوز

اگر Node.js 22 یا جدیدتر دارید، مسیر npm شفاف و قابل تکرار است. ابتدا Registry فعال و اطلاعات Package را ببینید، سپس نسخه مشخص یا latest را آگاهانه نصب کنید. در محیط Production یا Classroom بهتر است نسخه دقیق را Pin و زمان ارتقا را کنترل کنید.

node --versionnpm config get registrynpm view @qwen-code/qwen-code versionnpm install --global @qwen-code/qwen-code@latestqwen --versionqwen --help

اگر qwen پس از نصب شناخته نشد، Terminal تازه باز و مسیر Global npm را بررسی کنید. پوشه‌های سیستمی را با Permission عمومی Writable نکنید و PowerShell را فقط برای دورزدن تنظیم PATH با Run as Administrator اجرا نکنید. علت را در npm prefix و PATH کاربر پیدا کنید.

به‌روزرسانی و ثبت نسخه

به‌روزرسانی npm با همان فرمان و latest انجام می‌شود، اما اجرای کور آخرین نسخه در CI قابلیت بازتولید را کم می‌کند. نسخه‌ای را که آزموده‌اید در مستندات پروژه ثبت و Release Note را قبل از ارتقا بخوانید. برای Rollback، نسخه قبلی را صریح نصب کنید؛ حذف کل تنظیمات کاربر معمولاً لازم نیست.

نصب از Release Archive با بررسی SHA-256

Releaseهای رسمی می‌توانند Archive ویندوز و فایل SHA256SUMS ارائه کنند. هر دو را از همان Release دریافت کنید، Hash Archive را با مقدار منتشرشده مقایسه و سپس Installer را اجرا کنید. نام فایل و نسخه در مثال زیر Placeholder است و باید با Release واقعی جایگزین شود.

$archive = '.\qwen-code-win-x64.zip'$actual = (Get-FileHash -Algorithm SHA256 -LiteralPath $archive).Hash$actualGet-Content -LiteralPath '.\SHA256SUMS'# فقط پس از تطبیق کامل Hash، نصب را ادامه دهید.

مقایسه Size یا نام فایل کافی نیست. Hash را با حروف بزرگ یا کوچک می‌توان مقایسه کرد، اما رشته Hex باید کامل و دقیق یکسان باشد. اگر Release فایل Hash ندارد، Publisher و کانال دانلود را دوباره بررسی کنید و در محیط حساس Artifact را بدون تأیید وارد نکنید.

نخستین اجرا و اتصال Provider با /auth

از ریشه Repository آزمایشی qwen را اجرا کنید. در نخستین اجرا منوی Provider نمایش داده می‌شود. بعداً نیز فرمان /auth امکان تغییر روش احراز هویت را می‌دهد. گزینه‌ها می‌توانند Alibaba ModelStudio، Providerهای ثالث داخلی و Custom Provider باشند.

Set-Location 'C:\Projects\qwen-demo'git status --short --branchqwen# داخل رابط تعاملی:/auth

API Key را در Prompt، Command History، فایل Repository یا اسکرین‌شات نگذارید. آن را فقط از جریان Authentication رسمی وارد کنید. برای هر تیم یا محیط، Credential جدا با Scope و Budget محدود بسازید. اگر Provider از Regionهای متفاوت استفاده می‌کند، Base URL و محل داده را با مستندات رسمی همان حساب تطبیق دهید.

تنظیمات Qwen Code کجا ذخیره می‌شوند؟

تنظیمات کاربر در مسیر .qwen/settings.json داخل Home و تنظیمات پروژه در .qwen/settings.json ریشه Repository ذخیره می‌شوند. تنظیم Global روی همه پروژه‌ها اثر دارد؛ تنظیم Project می‌تواند همراه کد Commit شود و باید در Review دیده شود. Secret را داخل هیچ‌کدام ثبت نکنید.

نام Propertyها ممکن است تغییر کند؛ قبل از ویرایش فایل، Settings Reference نسخه نصب‌شده را ببینید. Config ناشناخته را از Blog یا Repository شخص ثالث کپی نکنید، زیرا می‌تواند MCP Server، Hook یا Tool جدید فعال کند.

Trusted Folders را فعال کنید

قابلیت Folder Trust جلوی بارگذاری خودکار تنظیمات پروژه ناشناس را می‌گیرد، اما طبق مستندات فعلی پیش‌فرض آن غیرفعال است و باید در تنظیمات User فعال شود. پس از فعال‌سازی، نخستین بار که Qwen Code را در یک Directory اجرا می‌کنید درباره اعتماد سؤال می‌کند.

{  "security": {    "folderTrust": {      "enabled": true    }  }}

این فایل باید User-level باشد تا Repository ناشناس نتواند خودش را مورد اعتماد اعلام کند. در حالت Untrusted، تنظیمات Workspace و فایل env پروژه نادیده گرفته می‌شوند، Auto-Accept غیرفعال است و برخی قابلیت‌های Extension و Memory محدود می‌شوند. به Parent Folder بزرگ مانند کل Projects اعتماد نکنید مگر همه زیرپوشه‌ها تحت کنترل شما باشند.

Sandbox در ویندوز با Docker یا Podman

Sandbox اجرای فرمان و ویرایش فایل را از Host جدا می‌کند. برای Windows و Linux، مستندات Docker یا Podman را پیشنهاد می‌کنند. Container Workspace و پوشه تنظیمات .qwen را Mount می‌کند تا Authentication و Settings حفظ شوند؛ بنابراین Sandbox همچنان می‌تواند فایل‌های Mountشده و Credentialهای قابل دسترسی را ببیند.

برای شروع، Docker Desktop را روشن و نسخه آن را بررسی کنید. سپس Qwen Code را با Flag رسمی Sandbox از ریشه پروژه آزمایشی اجرا کنید. از Mount کردن Drive کامل، Home، پوشه SSH یا Credential Store خودداری کنید.

docker versionSet-Location 'C:\Projects\qwen-demo'git status --short --branchqwen --sandbox

Sandbox لایه دفاعی است، نه تضمین. شبکه خروجی، Image مورد استفاده، Volumeها و Docker Socket را بررسی کنید. اگر Agent بتواند Credential Cloud را از Mount یا Environment بخواند، Container مانع استفاده از آن نمی‌شود. Image را از Registry رسمی بگیرید و نسخه آن را برای Workflow حساس ثبت کنید.

Sandbox چه چیزی را حل می‌کند و چه چیزی را نه؟

نخستین Task امن

پیش از Agent یک Branch جدا بسازید و Test پایه را اجرا کنید. Task باید کوچک، قابل آزمون و دارای ممنوعیت روشن باشد. درخواست «پروژه را بهتر کن» به Agent اجازه می‌دهد Scope را خودش حدس بزند؛ درخواست دقیق امکان Review دارد.

• هدف را به یک Bug یا Test محدود کنید.
• فایل‌ها و Directoryهای مجاز را مشخص کنید.
• فرمان Test رسمی پروژه را بنویسید.
• نصب Dependency، Migration، Push و Deploy را ممنوع کنید.
• از Agent بخواهید پیش از ویرایش Plan کوتاه ارائه دهد.
• در پایان Diff، Test و موارد انجام‌نشده را گزارش کند.

نمونه Prompt کنترل‌شده

Explain the validation flow before making changes.Add one regression test for an empty display name.Change only the test project and UserValidator.Do not install packages, change schema, push, or deploy.Run the focused test and show the final diff.

اگر Agent برای Rule کسب‌وکار اطلاعات ندارد، از آن بخواهید سؤال بپرسد. حدس مدل درباره Validation، مالیات، مجوز یا دسترسی کاربر نباید بدون تأیید Domain Expert وارد کد شود.

قبل از تأیید Shell چه چیزهایی را ببینیم؟

نام فرمان، Argumentها، Working Directory، Redirect، Pipeline و مقصد فایل را کامل بخوانید. فرمان Test محلی با فرمانی که Migration را روی Connection String محیط اجرا می‌کند یکسان نیست. وجود کلمه test در نام Script اثبات بی‌خطر بودن آن نیست.

Git، Diff و بازگشت تغییرها

Qwen Code می‌تواند تغییر بسازد، اما Git باید تاریخچه رسمی شما بماند. پیش از شروع، Worktree تمیز و Branch جدا داشته باشید. بعد از Agent، ابتدا git diff و سپس Test، Lint و Build را خودتان اجرا کنید. خروجی موفقی که Agent گزارش می‌دهد جای اجرای مستقل نیست.

git status --short --branchgit diff --statgit diff --checkgit diffdotnet testgit status --short

فرمان Test را با Stack پروژه عوض کنید. برای بازگشت، ابتدا Diff را ذخیره و منبع تغییر را بفهمید. از reset --hard یا حذف بازگشتی روی مسیر مبهم استفاده نکنید؛ این فرمان‌ها می‌توانند تغییرهای خود کاربر را نیز نابود کنند.

IDE Companion برای VS Code

Qwen Code می‌تواند Editor سازگار را تشخیص دهد و اتصال Companion را پیشنهاد کند. فرمان /ide install افزونه را نصب و /ide enable اتصال را فعال می‌کند. داخل VS Code نیز Commandهایی برای شروع Session، Accept Diff و بستن Diff Editor وجود دارد.

Publisher افزونه را در Marketplace بررسی کنید. Accept Diff به معنی درست‌بودن تغییر نیست؛ فقط تغییر نمایش‌داده‌شده را می‌پذیرد. پیش از قبول، فایل‌های اضافه، تغییر Lockfile، Migration، Configuration و Test حذف‌شده را بررسی کنید.

LSP چه کمکی می‌کند؟

پشتیبانی Language Server Protocol امکان Diagnostic، یافتن Reference و Code Action دقیق‌تر را می‌دهد، اما Language Server مربوط به زبان باید نصب باشد. برای TypeScript از typescript-language-server، برای Python از pylsp و برای زبان‌های دیگر از Server رسمی همان اکوسیستم استفاده می‌شود.

نصب Global ابزار توسعه روی سیستم مشترک باید مدیریت شود. نسخه Language Server را ثبت و Binary را از Package Manager معتبر بگیرید. LSP خطای Type و Syntax را بهتر پیدا می‌کند، اما Rule امنیتی و منطق کسب‌وکار را تضمین نمی‌کند.

مدیریت MCP و ابزارهای خارجی

MCP Server دامنه ابزارهای Agent را گسترش می‌دهد و ممکن است به GitHub، Database، Browser یا سرویس سازمانی دسترسی بدهد. هر Server جدید را مانند یک Integration دارای Credential ارزیابی کنید: Publisher، Command اجرا، Scope، Network، Secret و Log را بررسی کنید.

• MCP ناشناس را از Config عمومی اینترنت کپی نکنید.
• Credential جدا و کم‌اختیار بسازید.
• Serverهای پروژه را در Code Review قرار دهید.
• ابزارهای بلااستفاده را غیرفعال کنید.
• خروجی وب و Repository را داده غیرقابل اعتماد بدانید.
• برای عملیات مالی، حذف داده و Production تأیید بیرونی نگه دارید.

Workflow روزانه پیشنهادی

1. نسخه Qwen Code و Provider را ثبت کنید.
2. Repository را به‌روز و Worktree را تمیز کنید.
3. Branch جدا و Baseline Test بسازید.
4. Folder Trust را برای مسیر دقیق تصمیم بگیرید.
5. در پروژه ناشناس از حالت Untrusted شروع کنید.
6. در ویندوز Sandbox Docker یا Podman را فعال کنید.
7. Task کوچک با Scope و ممنوعیت روشن بدهید.
8. Shell و تغییرهای حساس را دستی تأیید کنید.
9. Diff، Test، Lint و Build را مستقل اجرا کنید.
10. Commit کوچک و Pull Request با Review انسانی بسازید.

خطاهای رایج Qwen Code در ویندوز

Qwen Code چه زمانی انتخاب مناسبی نیست؟

اگر پروژه Secretهای جدا‌نشدنی، داده بسیار حساس یا دسترسی مستقیم Production دارد، نخست باید محیط توسعه و کنترل دسترسی را اصلاح کنید. اگر تیم Git، Test و Review ندارد، Agent مشکل فرایند را حل نمی‌کند و سرعت تولید تغییر بررسی‌نشده را بیشتر می‌کند.

برای تکمیل یک خط ساده، Autocomplete سبک‌تر است. برای کار سازمانی، قبل از انتخاب نهایی Qwen Code را با Policy داده، مدل‌های مجاز، Proxy، Audit، SSO و نیازهای Compliance تیم بسنجید. متن‌باز بودن Client به‌تنهایی درباره محل پردازش Prompt توسط Provider تضمین نمی‌دهد.

مقایسه با مسیرهای مشابه

اگر Agent مبتنی بر Editor می‌خواهید، راهنمای Kilo Code در VS Code و آموزش Cline را ببینید. برای Workflow Terminal با Git، آموزش Aider AI مکمل این مقاله است. راهنمای انتخاب و اجرای محلی مدل‌های Qwen نیز تفاوت خود مدل با ابزار Agent را روشن می‌کند.

چک‌لیست پیش از استفاده روی کد واقعی

• Qwen Code از Release، Installer یا npm رسمی نصب شده است.
• نسخه ابزار و روش نصب ثبت شده است.
• Folder Trust در User Settings فعال است.
• Repository ناشناس پیش از Trust بررسی شده است.
• Sandbox روی Windows با Docker یا Podman فعال است.
• فقط Workspace لازم Mount شده و Secret داخل آن نیست.
• API Key در Prompt، History یا Git ذخیره نشده است.
• Branch جدا، Baseline Test و مسیر بازگشت دارید.
• Shell، MCP، Push و Deploy خودکار نیستند.
• Diff و Test مستقل پیش از Commit بررسی می‌شوند.

جمع‌بندی

Qwen Code یک Agent متن‌باز قدرتمند برای ترمینال است که می‌تواند شناخت Repository، ویرایش، اجرای فرمان و بررسی نتیجه را در یک Session ترکیب کند. نصب موفق فقط به ظاهرشدن فرمان qwen محدود نیست؛ باید منبع Artifact، نسخه، Provider، Credential، Folder Trust و Sandbox نیز مشخص باشند.

در ویندوز از npm با Node.js 22 یا Installer و Archive رسمی استفاده کنید، دانلود را قابل ممیزی نگه دارید، /auth را برای اتصال امن Provider اجرا و Folder Trust را فعال کنید. سپس با Sandbox، Branch جدا، Prompt محدود، تأیید Shell و Review مستقل Diff جلو بروید.

یک Repository آزمایشی بدون Secret بساز، Qwen Code را با نسخه ثبت‌شده نصب کن و نخستین Task را فقط به توضیح معماری و افزودن یک Test کوچک محدود کن.

منابع رسمی

• مخزن رسمی Qwen Code
• Qwen Code Overview
• Settings Reference
• Trusted Folders
• Sandbox
• IDE Integration
• LSP Support
• Installation Guide و Release Archive