آموزش Gemini CLI در ویندوز؛ نصب، Folder Trust و اجرای امن Agent
Gemini CLI را در ویندوز نصب و برای یک پروژه واقعی آماده کنید؛ از ورود با حساب Google تا Folder Trust، Checkpoint، Sandbox، Permission و اتصال محدود MCP.
Gemini CLI یک Agent متن‌باز و Terminal-first است که مدل‌های Gemini را مستقیماً کنار فایل‌ها، Git و فرمان‌های پروژه می‌آورد. این ابزار می‌تواند کد را توضیح دهد، فایل بسازد، تست اجرا کند و با ابزارهای بیرونی ارتباط بگیرد؛ همین توانایی‌ها باعث می‌شوند نصب ساده پایان کار نباشد.
در این راهنما Gemini CLI را روی ویندوز نصب می‌کنیم، اما اولین جلسه را فقط برای تحلیل یک Repository آزمایشی باز می‌کنیم. سپس Folder Trust، Checkpoint، Sandbox و مجوز ابزارها را طوری تنظیم می‌کنیم که هر تغییر قابل مشاهده و بازگشت باشد.
Gemini CLI چیست؟
Gemini CLI پروژه متن‌باز Google با مجوز Apache 2.0 است. رابط اصلی آن ترمینال است و ابزارهای داخلی برای خواندن و نوشتن فایل، اجرای Shell، دریافت محتوای وب و اتصال MCP دارد. در نتیجه با یک Chat ساده فرق دارد: پاسخ می‌تواند به اقدام روی محیط محلی تبدیل شود.
| قابلیت | کاربرد | کنترل پیشنهادی |
|---|---|---|
| تحلیل فایل | شناخت ساختار و وابستگی‌ها | شروع فقط‌خواندنی |
| ویرایش کد | رفع خطا و ساخت Feature | Branch و Diff |
| Shell | Build و Test | تأیید فرمان |
| Web Fetch | خواندن مستندات | دامنه معتبر |
| MCP | اتصال سرویس‌ها | Scope حداقلی |
اگر هنوز تفاوت Agent با Chatbot برایتان روشن نیست، راهنمای AI Agent را بخوانید. برای مقایسه یک عامل ترمینالی دیگر نیز آموزش GitHub Copilot CLI مفید است.
پیش‌نیازهای نصب روی ویندوز
- نسخه پشتیبانی‌شده Node.js و npm را از منبع رسمی نصب کنید.
- PowerShell یا Windows Terminal را با حساب عادی اجرا کنید، نه Administrator.
- یک Repository آزمایشی جدا از پروژه Production آماده کنید.
- Git را نصب و پیش از شروع یک Commit سالم ایجاد کنید.
- برای ورود تعاملی، مرورگر باید با ترمینال همان دستگاه ارتباط داشته باشد.
Gemini CLI را از Package رسمی @google/gemini-cli بگیرید. نام مشابه در Registry یا Installer متفرقه می‌تواند جعلی باشد. پیش از نصب، Publisher و لینک Repository را کنترل کنید.
نصب Gemini CLI با npm
برای امتحان بدون نصب دائمی، فرمان npx @google/gemini-cli را اجرا کنید. برای استفاده روزمره، نصب Global با npm install -g @google/gemini-cli انجام می‌شود. سپس gemini --version را برای تأیید نسخه و gemini را برای شروع بزنید.
اگر فرمان gemini شناخته نشد
یک Terminal تازه باز کنید و مسیر Global npm را بررسی کنید. نصب را با دسترسی Administrator تکرار نکنید مگر مستندات سیستم شما آن را الزام کرده باشد. چند نسخه Node یا مدیر نسخه می‌تواند Package را در Path متفاوت نصب کند.
چطور نسخه را به‌روز کنیم؟
برای نسخه پایدار جدید می‌توانید Package رسمی را با پسوند @latest دوباره نصب کنید. پیش از Update، Changelog را بخوانید و روی پروژه آزمایشی Folder Trust، Permission و Extensionهای خود را دوباره کنترل کنید.
ورود با حساب Google یا API Key
برای استفاده محلی، مستندات رسمی ورود با حساب Google را به بیشتر کاربران پیشنهاد می‌کند. پس از اجرای gemini گزینه Sign in with Google را انتخاب کنید و جریان مرورگر را کامل کنید. حساب‌های سازمانی ممکن است به Google Cloud Project نیاز داشته باشند.
| روش | مناسب برای | نکته امنیتی |
|---|---|---|
| Sign in with Google | کاربر محلی و تعاملی | حساب درست و دستگاه شخصی |
| Gemini API Key | اسکریپت یا حساب جدا | فقط Environment امن |
| Vertex AI | سازمان و Google Cloud | Role حداقلی و Project مشخص |
API Key را در Prompt، فایل GEMINI.md، Repository، Screenshot یا Log قرار ندهید. فایل .env نیز فقط وقتی امن است که از Git حذف شده و دسترسی سیستم‌عامل محدود باشد.
Folder Trust را فعال کنید
Folder Trust مشخص می‌کند کدام Workspace اجازه بارگذاری تنظیمات پروژه، MCP Server، Hook، Skill و Environment محلی را دارد. در پوشه Untrusted، Gemini CLI بسیاری از این قابلیت‌ها را غیرفعال می‌کند و برای Toolها تأیید می‌خواهد.
در تنظیمات کاربر، گزینه security.folderTrust.enabled را فعال نگه دارید. وقتی Dialog اعتماد ظاهر شد، محتویات کشف‌شده را بخوانید. برای Repository دانلودشده یا ناشناس، گزینه Don’t trust انتخاب بهتری است.
- هرگز پوشه عمومی بزرگی مثل Downloads یا ریشه درایو را Trust نکنید.
- Trust parent folder فقط برای مجموعه پروژه‌های تحت کنترل خودتان مناسب است.
- فایل‌های
.gemini/settings.jsonو Commandهای سفارشی را قبل از Trust بررسی کنید. - با فرمان
/permissionsتصمیم پوشه جاری را دوباره ارزیابی کنید. - در CI از دورزدن Trust بدون کنترل Repository استفاده نکنید.
Checkpoint را پیش از ویرایش فعال کنید
Checkpointing پیش از تغییر فایل توسط ابزارهای AI یک Snapshot می‌سازد. این قابلیت به‌صورت پیش‌فرض خاموش است و باید از تنظیمات فعال شود. گزینه مربوط در شاخه general.checkpointing.enabled قرار دارد.
پس از فعال‌سازی، فرمان /restore فهرست Checkpointهای پروژه را نشان می‌دهد. Checkpoint جای Git و Backup Database نیست؛ برای مقایسه سریع تغییر Agent مفید است، اما Commit و Branch همچنان منبع اصلی تاریخچه کد هستند.
Sandbox در ویندوز چه کاری انجام می‌دهد؟
Sandbox عملیات پرریسک مثل Shell و ویرایش فایل را از بخش‌های دیگر میزبان جدا می‌کند. می‌توانید آن را با --sandbox یا -s فعال کنید. روش Container به Docker یا Podman نیاز دارد و Workspace را داخل محیط ایزوله Mount می‌کند.
Sandbox بومی ویندوز ممکن است Integrity Level بعضی فایل‌های ساخته‌شده یا تغییرکرده را پایدار تغییر دهد؛ بنابراین ابتدا آن را روی پوشه آزمایشی بسنجید. Sandbox مجوز نامحدود نیست و Prompt Injection، Secret لو‌رفته یا اتصال MCP پرقدرت را به‌تنهایی حل نمی‌کند.
| لایه | ریسک تحت کنترل | محدودیت |
|---|---|---|
| Folder Trust | تنظیمات مخرب Workspace | برای پوشه Trusted کافی نیست |
| Permission | اجرای Tool ناخواسته | تأیید عجولانه بی‌اثر می‌کند |
| Sandbox | آسیب به میزبان | به پیکربندی درست وابسته است |
| Checkpoint | بازگشت فایل | Backup داده نیست |
| Git | Review و تاریخچه | Secret Commitشده را امن نمی‌کند |
اولین جلسه را فقط‌خواندنی شروع کنید
از Gemini بخواهید ساختار پروژه، Entry Point، مسیر Test و ریسک‌های تغییر را توضیح دهد و صریحاً بگویید هیچ فایل یا فرمانی اجرا نشود. سپس خروجی را با README و کد واقعی مقایسه کنید.
این Repository را فقط تحلیل کن. هیچ فایل، Package، تنظیم، Git state یا Database را تغییر نده و هیچ فرمانی اجرا نکن. ابتدا فایل‌های مرتبط، معماری، روش اجرای Test و سه ریسک اصلی را با ارجاع به مسیر فایل توضیح بده. در پایان یک برنامه کوچک با معیار پذیرش پیشنهاد کن.
پس از تأیید تحلیل، یک Branch جدا بسازید و فقط یک Task محدود بدهید. پیش از پذیرش تغییر، git diff، Test، خروجی Build و فایل‌های جدید را بررسی کنید.
MCP را از روز اول Trusted نکنید
MCP می‌تواند Gemini CLI را به GitHub، Database یا API متصل کند. هر Server ابزارهای تازه‌ای وارد Session می‌کند. ابتدا با gemini mcp list وضعیت اتصال را ببینید و از /mcp برای مشاهده Toolهای عرضه‌شده استفاده کنید.
گزینه Trust برای MCP می‌تواند Dialog تأیید Tool را دور بزند؛ تا زمانی که Server، کد، Transport و Scope آن را بررسی نکرده‌اید از آن استفاده نکنید. Secret را در آرگومان قابل مشاهده Shell ننویسید و Toolهای غیرضروری را با Include/Exclude محدود کنید. برای اصول طراحی اتصال، راهنمای MCP Server امن را ببینید.
چک‌لیست انتشار تغییر Agent
- Workspace فقط شامل فایل‌های پروژه و بدون Secret باشد.
- Branch و Commit مبنا پیش از شروع ثبت شده باشد.
- هر Tool Call و فرمان پیش از اجرا خوانده شود.
- Diff فقط Scope توافق‌شده را پوشش دهد.
- Test خودکار و سناریوی دستی مرتبط اجرا شود.
- Dependency جدید از نظر منبع، مجوز و نسخه بررسی شود.
- Migration، Deploy و Push فقط با تصمیم انسانی انجام شود.
- پس از پایان، Session و دسترسی‌های موقت بسته شوند.
اشتباه‌های رایج
- اجرای CLI در پوشه Home: دامنه فایل‌های قابل مشاهده بیش از نیاز می‌شود.
- Trust کردن پوشه والد: Repository ناشناس بعدی هم ناخواسته معتبر می‌شود.
- فعال‌کردن YOLO بدون Sandbox: فرصت بازبینی Toolها از بین می‌رود.
- اتکا به Checkpoint برای Database: Snapshot فایل لزوماً داده بیرونی را برنمی‌گرداند.
- قرار دادن API Key در settings پروژه: Secret ممکن است Commit یا Share شود.
- اعتماد فوری به MCP Server: ابزار بیرونی بدون بررسی به داده دسترسی می‌گیرد.
جمع‌بندی
Gemini CLI نصب ساده‌ای دارد، اما استفاده حرفه‌ای آن از انتخاب یک Workspace کوچک و قابل اعتماد شروع می‌شود. Folder Trust از بارگذاری تنظیمات ناشناس جلوگیری می‌کند، Checkpoint بازگشت سریع می‌دهد و Sandbox دامنه اثر فرمان‌ها را محدود می‌کند.
هیچ‌کدام جای Review انسانی، Git و Backup را نمی‌گیرند. ابتدا تحلیل فقط‌خواندنی، سپس تغییر کوچک روی Branch و در پایان Test و Diff؛ این ترتیب سرعت Agent را بدون واگذاری کنترل به کار می‌گیرد.
امروز Gemini CLI را فقط روی یک Repository آزمایشی اجرا کنید، Folder Trust و Checkpoint را بررسی کنید و پیش از هر ویرایش از Agent بخواهید برنامه و معیار پذیرش را ارائه دهد.