توسط Matt Connor 2026-10-10

اجرای Gemini CLI روی سرور مجازی بدون رابط گرافیکی

Q: چرا نصب سراسری npm نیاز به sudo دارد و چگونه از آن اجتناب کنم؟

زیرا پیشوند سراسری پیشفرض npm مسیر /usr/lib/node_modules است که کاربر شما اجازه نوشتن در آن را ندارد، بنابراین دستور ساده npm install -g با خطای EACCES مواجه میشود. راه حل اشتباه استفاده از sudo npm -g است که فایلهایی با مالکیت root باقی میگذارد و باعث خرابی نصبهای بعدی میشود. راه حل درست این است که پیشوند را به دایرکتوری home خود (npm config set prefix ~/.npm-global) تغییر دهید و مسیر bin آن را به PATH اضافه کنید، یا از nvm استفاده کنید که بستههای سراسری را بهطور خودکار در home شما نصب میکند.

Q: آیا اجرای Gemini CLI روی سرور production امن است؟

فقط با احتیاط، زیرا یک عامل (agent) با دسترسی shell میتواند هر کاری که کاربرِ اجراکننده آن اجازه دارد را انجام دهد. آن را بهعنوان یک کاربر اختصاصی بدون امتیاز (unprivileged) و بدون دسترسی sudo اجرا کنید، اعتبارنامههای production را روی آن ماشین قرار ندهید، از تأیید خودکار --yolo اجتناب کنید و از --sandbox (Docker یا Podman) برای ایزوله کردن فراخوانی ابزارها از host استفاده کنید. حسابی که CLI تحت آن اجرا میشود، از هر flag تکی که تنظیم میکنید اهمیت بیشتری دارد.

Q: آیا نیاز است پورتهای فایروال را برای Gemini CLI باز کنم؟

خیر. این یک کلاینت است که فراخوانیهای HTTPS خروجی به APIهای Google انجام میدهد، بنابراین به پورت خروجی 443 نیاز دارد اما هیچ پورت ورودی لازم ندارد. ورود به سیستم Google روی سرور headless نیز به هیچ پورتی نیاز ندارد: شما بهجای دریافت callback روی سرور، یک کد را در ترمینال وارد میکنید. دسترسیهای ورودی را مسدود نگه دارید.

راهنمای کامل اجرای Gemini CLI روی VPS با استفاده از Node.js و tmux. یاد بگیرید چگونه بدون نیاز به مرورگر احراز هویت کنید و با نصب بدون sudo، وظایف طولانی را مدیریت کنید.

آنچه در حال ساخت آن هستید

یک CLI برای Gemini که همیشه روی سرور شخصی شما در دسترس است، از طریق SSH قابل دسترسی بوده و وظایف طولانی‌مدت عامل (agent) را اجرا می‌کند که پس از بستن لپ‌تاپ همچنان به کار خود ادامه می‌دهند. نصب این ابزار تنها با 3 دستور انجام می‌شود. آنچه نیاز به تلاش دارد، مواردی است که پیش‌فرض‌های محیط دسکتاپ را در نظر می‌گیرند: CLI گوگل برای ورود به سیستم نیاز به باز کردن مرورگر دارد، در حالی که سرور شما فاقد رابط گرافیکی است. بنابراین، بخش عمده این راهنما شامل مسیر headless، نصب نسخه به‌روز Node که در مخازن توزیع شما موجود نیست، نصب سراسری npm بدون نیاز به دسترسی root، احراز هویت بدون مرورگر با استفاده از یک API key که در تاریخچه shell ذخیره نمی‌شود، و استفاده از tmux برای جلوگیری از توقف وظایف در صورت قطع اتصال SSH است.

Gemini CLI یک برنامه Node متن‌باز (تحت مجوز Apache-2.0) است (@google/gemini-cli) که با مدل‌های Gemini گوگل ارتباط برقرار می‌کند و توانایی خواندن و نوشتن فایل‌ها، اجرای دستورات shell و مدیریت ابزارها در دایرکتوری کاری را دارد. روی یک VPS، این ابزار یک عامل کوچک و همیشه در دسترس است که می‌توانید آن را در حال اجرا رها کنید؛ به همین دلیل، حسابی که با آن اجرا می‌شود و اعتبارنامه‌هایی که روی سرور قرار دارند، از هر تنظیم دیگری در این راهنما اهمیت بیشتری دارند.

پیش‌نیازها و نکات مهم

یک سرور مجازی (VPS) تازه با سیستم‌عامل Ubuntu 24.04 و دسترسی root یا sudo. هر پلن KVM مناسب است؛ خود CLI سبک است و در حالت استراحت تنها چند صد مگابایت از RAM را اشغال می‌کند.
نسخه Node.js 20 یا جدیدتر. این حداقل نسخه مورد نیاز است و بسته موجود در مخازن توزیع قدیمی‌تر از این مقدار است؛ بخش بعدی را ببینید. پشتیبانی از Node 20 در تاریخ 30 آوریل 2026 به پایان رسیده است، بنابراین نسخه 24 را نصب کنید.
دسترسی خروجی HTTPS (پورت 443) به APIهای Google. نیازی به باز کردن پورت‌های ورودی نیست؛ این یک کلاینت است، نه یک سرور، بنابراین نیازی به ایجاد حفره در فایروال ندارید.
روشی برای احراز هویت که به مرورگر روی سرور نیاز نداشته باشد: یا یک Gemini API key خریداری‌شده از Google AI Studio، یا ورود به حساب Google که در سیستم‌های بدون رابط گرافیکی (headless)، از شما می‌خواهد یک کد را در ترمینال وارد کنید. روش استفاده از API key برای اسکریپت‌ها و اجراهای خودکار مناسب‌تر است.
Docker یا Podman، تنها در صورتی که به ایزوله‌سازی --sandbox نیاز دارید. این مورد اختیاری است و در انتهای راهنما پوشش داده شده است.

نکته‌ای که اکنون بسیاری را دچار مشکل می‌کند، نوع حساب کاربری است، نه مرورگر. گوگل در تاریخ 19 مه 2026 اعلام کرد که از 18 ژوئن 2026، Gemini CLI دیگر به مشترکین Google AI Pro و Ultra و همچنین کاربران نسخه رایگان سرویس‌دهی نخواهد کرد و این کاربران را به جایگزین آن، یعنی Antigravity CLI (agy)، ارجاع می‌دهد. Gemini CLI همچنان با Gemini API keyهای پولی، کلیدهای Gemini Enterprise Agent Platform و لایسنس‌های Gemini Code Assist Standard یا Enterprise سازمان‌ها کار می‌کند. پیش از شروع، مسیر احراز هویت خود را مشخص کنید.

نکته: بسته توزیع‌شده بسیار قدیمی است

توزیع Ubuntu 24.04 نسخه Node 18.19.1 را در مخازن خود ارائه می‌دهد که با npm 9.2.0 همراه است. فایل package.json در Gemini CLI نسخه engines: { node: ">=20" } را اعلام می‌کند و npm به‌صورت پیش‌فرض از ناسازگاری جلوگیری نمی‌کند؛ بنابراین نصب انجام می‌شود اما هشداری نمایش داده می‌شود که شکاف موجود را مشخص می‌کند:

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: '@google/gemini-cli@0.50.0',
npm WARN EBADENGINE   required: { node: '>=20' },
npm WARN EBADENGINE   current: { node: 'v18.19.1', npm: '9.2.0' }
npm WARN EBADENGINE }

اگر از این هشدار عبور کنید، CLI روی یک runtime پشتیبانی‌نشده اجرا می‌شود که در آن یا دچار اختلال می‌شود و یا به محض رسیدن به یک API مربوط به Node 20+ که انتظار وجود آن را دارد، کرش می‌کند. پشتیبانی از Node 18 نیز در آوریل 2025 به پایان رسیده است، بنابراین در هر صورت این یک مسیر بن‌بست است. پیش از نصب CLI، یک نسخه LTS فعلی را نصب کنید. دو روش تمیز برای این کار وجود دارد: NodeSource (یک مخزن apt امضاشده در سطح سیستم) یا nvm (یک مدیریت نسخه برای هر کاربر). یکی را انتخاب کنید.

NodeSource، اگر می‌خواهید Node برای تمام کاربران سیستم در دسترس باشد:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version

دستور node --version باید خروجی v20.x یا بالاتر را چاپ کند تا نیاز CLI برآورده شود، اما پشتیبانی از Node 20 در تاریخ 30 آوریل 2026 به پایان رسیده است، بنابراین هدف خود را روی v24.x که نسخه LTS فعال فعلی است قرار دهید. Node 26 قرار است در تاریخ 28 اکتبر 2026 به عنوان LTS فعال جایگزین شود. برای مشاهده اسکریپت راه‌اندازی فعلی، صفحه NodeSource را بررسی کنید؛ مقدار setup_24.x در URL همان بخشی است که هنگام انتشار نسخه LTS جدیدتر باید تغییر کند.

nvm، اگر ترجیح می‌دهید Node را در دایرکتوری home یک کاربر نگه دارید و هرگز با sudo به آن دست نزنید:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version

نسخه v0.40.1 در آن URL در زمان نگارش این متن معتبر بوده است؛ برای اطلاع از آخرین نسخه، فایل README مربوط به nvm را بررسی کنید و پیش از اجرا، نسخه را جایگزین کنید. nvm برای این کار یک مزیت واقعی دارد: Node و بسته‌های سراسری (global) آن را در مسیر ~/.nvm نصب می‌کند، بنابراین مشکل مجوز در نصب‌های سراسری که در بخش بعدی به آن اشاره می‌شود، هرگز رخ نخواهد داد. اگر از روش nvm استفاده می‌کنید، می‌توانید مرحله npm-prefix را نادیده بگیرید.

نصب CLI بدون `sudo npm -g`

دستور وسوسه‌انگیز sudo npm install -g @google/gemini-cli است. این کار را انجام ندهید. استفاده از یک پیشوند (prefix) سراسری که مالک آن root است، در هر نصب بعدی باعث خطای دسترسی می‌شود و فایل‌هایی با مالکیت root در کش npm باقی می‌گذارد که ماه‌ها بعد برای شما مشکل‌ساز خواهند شد. اجرای یک npm install -g ساده (بدون sudo) روی یک Node سیستمی، منجر به خطای دیگری می‌شود:

npm error code EACCES
npm error syscall mkdir
npm error path /usr/lib/node_modules/@google
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/lib/node_modules/@google'

این خروجی نشان می‌دهد که npm در تلاش است در /usr/lib بنویسد، که کاربر شما به آن دسترسی ندارد. راه‌حل، استفاده از sudo نیست؛ بلکه باید پیشوند سراسری npm را به دایرکتوری home خود هدایت کنید تا نصب‌های سراسری در جایی قرار بگیرند که مالکیت آن با شماست:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli
gemini --version

استفاده از ~/.bashrc و نه ~/.profile، عامدانه است: tmux که دو بخش بعد، CLI را درون آن اجرا خواهید کرد، یک non-login shell را شروع می‌کند که ~/.bashrc را می‌خواند و از ~/.profile صرف‌نظر می‌کند. بنابراین، یک خط PATH در فایل اشتباه باعث می‌شود gemini دقیقاً در جایی که به آن نیاز دارید، دیده نشود. چاپ شماره نسخه توسط gemini --version، تمام چیزی است که برای تست نیاز دارید. اگر به‌جای آن gemini: command not found دریافت کردید، یعنی export مربوط به PATH اعمال نشده است؛ در این صورت به بخش حالت‌های شکست مراجعه کنید. اگر از nvm استفاده می‌کنید، از خطوط مربوط به پیشوند صرف‌نظر کنید؛ چرا که nvm به‌طور خودکار بسته‌های سراسری را در دایرکتوری home شما نصب می‌کند.

اگر در گذشته sudo npm را اجرا کرده‌اید و اکنون با Your cache folder contains root-owned files مواجه می‌شوید، آن را یک‌بار با دستور sudo chown -R $(id -u):$(id -g) ~/.npm تعمیر کنید.

مشکل احراز هویت در سیستم‌های بدون نمایشگر (Headless) و نحوه عبور از آن

ابزار gemini را برای نخستین بار به‌صورت تعاملی اجرا کنید تا پیشنهاد ورود به سیستم با حساب Google را به شما ارائه دهد. در محیط دسکتاپ، این کار یک تب مرورگر باز می‌کند. در یک VPS لینوکسی بدون نمایشگر (headless)، رابط خط فرمان (CLI) ابتدا وجود نمایشگر را بررسی می‌کند و زمانی که هیچ‌یک از متغیرهای DISPLAY، WAYLAND_DISPLAY یا MIR_SOCKET تنظیم نشده باشند، اصلاً برای باز کردن مرورگر تلاش نمی‌کند. در عوض، یک لینک ورود چاپ کرده و منتظر می‌ماند تا کد را کپی و در آنجا وارد کنید:

Please visit the following URL to authorize the application:

https://accounts.google.com/o/oauth2/v2/auth?...

Enter the authorization code:

این جریان از طریق SSH معمولی کار می‌کند، اما هر بار به حضور شما در مقابل یک مرورگر نیاز دارد و از تاریخ 18 ژوئن 2026، تنها در صورتی شما را وارد می‌کند که حساب Google شما جزو مواردی باشد که Gemini CLI همچنان پشتیبانی می‌کند.

دو راهکار منطقی برای عبور از این وضعیت وجود دارد.

راهکار اول استفاده از API key است که گزینه پیش‌فرض مناسب برای سرور محسوب می‌شود. یک کلید در Google AI Studio (aistudio.google.com) در پروژه‌ای که صورت‌حساب (billing) آن فعال است ایجاد کنید، زیرا Gemini CLI دیگر سرویس رایگان ارائه نمی‌دهد. سپس آن را به‌عنوان یک متغیر محیطی به CLI معرفی کنید؛ ابزار مقدار GEMINI_API_KEY را می‌خواند و به‌طور کامل از جریان مرورگر صرف‌نظر می‌کند. اکنون نوبت به بخش «دور نگه داشتن از تاریخچه و فایل‌های قابل خواندن برای همه» می‌رسد. دستور export GEMINI_API_KEY=AIza... را در خط فرمان تایپ نکنید، زیرا به‌صورت متن ساده در ~/.bash_history ذخیره می‌شود و آن را در فایلی که دیگران اجازه خواندنش را دارند قرار ندهید. آن را در فایلی با مجوز 600 بنویسید که shell در هنگام شروع آن را فراخوانی (source) می‌کند:

umask 077
printf 'export GEMINI_API_KEY=%s\n' 'AIzaSyYOUR_KEY_HERE' > ~/.gemini_env
chmod 600 ~/.gemini_env
echo '[ -f ~/.gemini_env ] && . ~/.gemini_env' >> ~/.bashrc
source ~/.bashrc

مجوز chmod 600 به این معناست که فقط کاربر شما می‌تواند فایل را بخواند. با دستور printenv GEMINI_API_KEY تأیید کنید که کلید به محیط منتقل شده است؛ اگر خروجی خالی باشد، CLI به‌جای استفاده از کلید، به سراغ انتخابگر احراز هویت خود می‌رود. همچنین اگر این ساختار را ترجیح می‌دهید، ابزار فایل .env را در مسیر ~/.gemini/ می‌خواند؛ قانون مشابه است، پس از chmod 600 ~/.gemini/.env استفاده کنید.

راهکار دوم، ورود مستقیم با حساب Google است که در یک سیستم بدون نمایشگر، نیازی به تونل یا باز کردن پورت ندارد. از تاریخ 18 ژوئن 2026، این روش عمدتاً برای مجوزهای Gemini Code Assist Standard یا Enterprise سازمان‌ها کاربرد دارد (متغیر GOOGLE_CLOUD_PROJECT را نیز تنظیم کنید)؛ حساب‌های شخصی رایگان و اشتراک‌های Google AI Pro یا Ultra دیگر پشتیبانی نمی‌شوند. CLI را از طریق یک نشست SSH معمولی شروع کرده و گزینه Sign in with Google را انتخاب کنید:

gemini

URL چاپ شده را در مرورگر لپ‌تاپ خود کپی کرده و تأیید کنید. Google شما را به https://codeassist.google.com/authcode هدایت می‌کند که یک کد احراز هویت را نمایش می‌دهد؛ آن را در خط فرمان Enter the authorization code: در VPS وارد کنید تا ورود تکمیل شود. هیچ فرآیندی روی سرور منتظر callback نمی‌ماند، بنابراین نیازی به باز کردن پورت یا تنظیم ssh -L نیست. متغیر OAUTH_CALLBACK_PORT فقط برای جریان loopback اهمیت دارد که CLI هنگام یافتن نمایشگر از آن استفاده می‌کند. اگر با X11 forwarding (ssh -X) متصل شده‌اید، DISPLAY تنظیم می‌شود و CLI به‌جای آن از جریان loopback با تغییر مسیر به http://127.0.0.1:PORT/oauth2callback روی سرور استفاده می‌کند؛ برای اجبار به استفاده از جریان ورود کد، دستور NO_BROWSER=true gemini را اجرا کنید. این روش کار می‌کند، اما نیاز دارد که شما پشت مرورگر باشید، بنابراین برای اسکریپت‌ها مناسب نیست. برای هر چیزی که قرار است به‌صورت خودکار اجرا شود، از API key استفاده کنید.

برای استفاده از Vertex AI یا یک پروژه Google Cloud به‌جای AI Studio، متغیر GOOGLE_API_KEY را به همراه GOOGLE_GENAI_USE_VERTEXAI=true، یا برای مجوز Code Assist متغیر GOOGLE_CLOUD_PROJECT را تنظیم کنید؛ همان انضباط در متغیرهای محیطی و همان فایل با مجوز 600 را رعایت کنید.

اجرای آن در tmux برای جلوگیری از توقف در صورت قطع اتصال SSH

یک فرایند gemini که مستقیماً از شل SSH خود اجرا می‌کنید، فرزند همان شل محسوب می‌شود. قطع اتصال، بستن لپ‌تاپ، ناپایداری Wi-Fi یا اتمام زمان انتظار (idle timeout) باعث می‌شود sshd شبه‌ترمینال (pseudo-terminal) را از بین ببرد، شل سیگنال SIGHUP دریافت کند و در نهایت فرایند در CLI متوقف شود. در این حالت، وظیفه‌ای که ده دقیقه از ویرایش فایل‌های آن گذشته است از بین می‌رود و پس از اتصال مجدد، فرایندی برای بازیابی وجود نخواهد داشت.

ابزار tmux با در اختیار گرفتن مالکیت شل به جای sshd، این مشکل را حل می‌کند. این همان الگویی است که در اجرای یک AI coding agent روی یک VPS از راه دور داخل tmux استفاده می‌شود و در اینجا نیز دقیقاً به همان شکل عمل می‌کند:

sudo apt install -y tmux
tmux new -A -s gemini
# inside the session:
gemini
# detach with Ctrl-b then d, the task keeps running
# reconnect later from any machine:
tmux attach -t gemini

دستور tmux new -A -s gemini به نشست (session) با نام gemini متصل می‌شود؛ اگر این نشست وجود داشته باشد به آن وصل می‌شود و در غیر این صورت آن را ایجاد می‌کند. بنابراین، این تنها دستوری است که باید بلافاصله پس از هر بار ورود به سیستم اجرا کنید. شلِ داخل آن متعلق به سرورِ جداشدهٔ (detached) tmux است، نه نشست SSH شما؛ بنابراین قطع اتصال باعث توقف کار CLI نمی‌شود. پس از اتصال مجدد، با attach کردن دوباره به همان وضعیت قبلی و تاریخچهٔ اسکرول دسترسی خواهید داشت. اگر چندین نشست agent را روی یک سرور اجرا می‌کنید (هر کدام در یک نشست tmux مجزا)، آن‌ها در اینجا راهی برای ارتباط با یکدیگر ندارند؛ برخلاف Claude Code که در آن یک نشست می‌تواند متن را به نشست دیگری روی همان VPS منتقل کند، بنابراین هر job مربوط به Gemini را مستقل نگه دارید یا آن‌ها را از طریق فایل‌های روی دیسک هماهنگ کنید.

برای اجراهای غیرتعاملی و اسکریپت‌شده، Gemini CLI دارای حالت headless است: gemini -p "summarise the failing tests in this repo" پاسخ را چاپ کرده و خارج می‌شود، و --output-format json خروجی قابل‌فهم برای ماشین ارائه می‌دهد تا بتوانید آن را به جای دیگری pipe کنید. حالت headless همراه با یک API key دقیقاً همان چیزی است که برای اجرای یک batch job طولانی داخل نشست tmux یا فراخوانی از طریق cron به آن نیاز دارید. تنها یک نکته را در نظر داشته باشید: یک cron job هیچ‌کدام از فایل‌های ورود (login files) شما را بارگذاری نمی‌کند؛ بنابراین در خط crontab، متغیر GEMINI_API_KEY را به صورت دستی تعریف کنید (یا دستور را طوری تنظیم کنید که ~/.gemini_env را source کند)، در غیر این صورت اجرا به دلیل نبود اعتبارنامه (credentials) با شکست مواجه می‌شود.

سندباکس و مجوزها در سروری که سرویس‌های عملیاتی (Production) را اجرا می‌کند

عاملی که دسترسی shell دارد، در واقع یک shell است. Gemini CLI می‌تواند دستورات را اجرا کند و به‌صورت پیش‌فرض پیش از هر دستور پرخطر از شما تأیید می‌گیرد، اما کاربران اغلب از --yolo (تأیید خودکار تمام فراخوانی‌های ابزار) استفاده می‌کنند. در این حالت، عامل می‌تواند فایل‌ها را حذف کند، به git کد push کند یا با تمام اختیارات کاربری که با آن اجرا شده، به سرویس‌های داخلی دسترسی پیدا کند. در سروری که سرویس‌های عملیاتی را میزبانی می‌کند، این یک ریسک واقعی است، نه یک احتمال فرضی.

سه کنترل امنیتی، به ترتیب اولویت و اثربخشی:

اجرا با یک کاربر اختصاصی و بدون امتیاز (unprivileged). نه root و نه عضوی از گروه sudo. یک کاربر agent با home directory اختصاصی بسازید، Node و CLI را در آن نصب کنید. با این کار، اگر دستور اشتباهی اجرا شود، اثر آن به همان حساب محدود می‌ماند. این مهم‌ترین تصمیم امنیتی است.
اعتبارنامه‌های عملیاتی (Production) را روی سرور نگه ندارید. هیچ ~/.aws/credentials عملیاتی، هیچ .env کپی‌شده از محیط production و هیچ رمز عبور دیتابیسی که دسترسی نوشتن به داده‌های حساس دارد را در آنجا قرار ندهید. به جای آن از اعتبارنامه‌های محیط staging یا دسترسی فقط‌خواندنی (read-only) استفاده کنید.
از سندباکس داخلی استفاده کنید. اگر Docker یا Podman نصب باشد، gemini --sandbox (یا GEMINI_SANDBOX=docker) فراخوانی‌های ابزار توسط عامل را درون کانتینری اجرا می‌کند که فقط دایرکتوری پروژه فعلی را mount می‌کند، نه کل فایل‌سیستم میزبان را. این جایگزین کاربر بدون امتیاز نیست، اما وقتی همان VPS کارهای واقعی انجام می‌دهد، یک لایه امنیتی دوم و قدرتمند محسوب می‌شود.

اگر Gemini CLI را در کنار سایر ابزارهای self-hosted اجرا می‌کنید، مثلاً یک سرور MCP که ابزارها را روی همان VPS در اختیار عامل قرار می‌دهد، هر قابلیت جدیدی که اضافه می‌کنید را به عنوان سطح دسترسی جدید برای عامل در نظر بگیرید و توکن‌هایی که به آن می‌دهید را دقیقاً محدود به یک وظیفه خاص کنید.

سهمیه، هزینه و انتخاب مسیر احراز هویت

مسیر احراز هویت تعیین‌کننده نحوه محاسبه هزینه‌ها است و از تاریخ 18 ژوئن 2026، مشخص می‌کند که آیا اصلاً به شما سرویس‌دهی می‌شود یا خیر. طبق اطلاعیه Google، از آن تاریخ، Gemini CLI دیگر به مشترکین Google AI Pro و Ultra و همچنین تمامی کاربران نسخه رایگان (شامل حساب‌های شخصی و API keyهای بدون صورت‌حساب) سرویس‌دهی نمی‌کند. این ابزار همچنان از طریق API keyهای پولی Gemini و Gemini Enterprise Agent Platform که هزینه را بر اساس توکن محاسبه می‌کنند، و همچنین برای سازمان‌هایی که دارای لایسنس Gemini Code Assist Standard یا Enterprise یا سایر دسترسی‌های Google Cloud هستند و صورت‌حساب آن‌ها از طریق Google Cloud صادر می‌شود، در دسترس است. هر سطح دسترسی همچنان محدودیت‌های دقیقه و روزانه دارد؛ در صورت عبور از این محدودیت‌ها، درخواست‌ها تا زمان بازنشانی بازه زمانی، با خطای rate-limit مواجه می‌شوند.

دو نکته کاربردی: یک عامل (agent) خودکار در یک حلقه تکرار می‌تواند سهمیه شما را به‌سرعت مصرف کند، بنابراین پیش از آنکه اجرای آن را به یک cron job بسپارید، در دفعات اول عملکرد آن را زیر نظر بگیرید. اگر دلیل شما برای استفاده از مدل سمت سرور، حفظ حریم خصوصی یا استنتاج نامحدود (unmetered) به‌جای استفاده از مدل‌های میزبانی‌شده توسط Google است، موضوع متفاوت خواهد بود؛ میزبانی شخصی یک مدل زبانی بزرگ (LLM) متن‌باز با استفاده از Ollama روی یک VPS وزن‌ها و پرامپت‌ها را روی سرور شخصی شما نگه می‌دارد، اما هزینه آن استفاده از مدلی بسیار کوچک‌تر از Gemini است.

به‌روز نگه‌داشتن

ابزار Gemini CLI به‌طور مرتب عرضه (release) می‌شود. از آنجا که آن را در یک prefix متعلق به کاربر نصب کرده‌اید، برای به‌روزرسانی هرگز نیازی به sudo نیست:

npm install -g @google/gemini-cli@latest
gemini --version

کانال‌های عرضه مختلفی وجود دارد: @latest نسخه پایدار، @preview نسخه پیش‌نمایش هفتگی و @nightly نسخه آزمایشی (bleeding edge) است. برای هر سرویسی که به آن وابستگی دارید، نسخه را روی @latest قفل کنید. در nvm، بسته‌های سراسری (global) تحت نسخه فعال Node قرار می‌گیرند؛ بنابراین پس از استفاده از nvm use برای تغییر نسخه Node، ممکن است نیاز باشد CLI را دوباره نصب کنید. به‌جای دنبال کردن تک‌تک وصله‌ها (patch)، یادداشت‌های انتشار (release notes) را مطالعه کنید.

حالت‌های شکست، همراه با رشته‌های دقیق

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }، و سپس کرش کردن CLI در زمان اجرا. نسخه Node بسیار قدیمی است؛ توزیع سیستم از 18.19.1 استفاده می‌کند که آن هم از چرخه پشتیبانی خارج شده است. یک نسخه LTS فعلی را از NodeSource یا nvm نصب کنید (Node 20 حداقل نیاز CLI را برآورده می‌کند، اما خود آن نیز از آوریل 2026 از چرخه پشتیبانی خارج شده است)، با node --version آن را تأیید کنید، و اگر چندین نسخه Node نصب دارید، بررسی کنید که which node به نسخه جدید اشاره کند و نه /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. نصب سراسری (global) در مسیری که مالک آن root است. از sudo استفاده نکنید؛ npm config set prefix ~/.npm-global را تنظیم کنید، ~/.npm-global/bin را در PATH قرار دهید و آن را به عنوان کاربر عادی خود دوباره نصب کنید. اگر یک sudo npm قبلی، فایل‌های کش با مالکیت root (Your cache folder contains root-owned files) باقی گذاشته است، sudo chown -R $(id -u):$(id -g) ~/.npm را اجرا کنید.

Failed to open browser، یا یک redirect_uri که به http://127.0.0.1:PORT اشاره دارد و در دسترس نیست. CLI یک متغیر display پیدا کرده است (اغلب از ssh -X) و جریان loopback را انتخاب کرده که callback آن به سرور ختم می‌شود. برای دریافت جریان paste-a-code، دستور NO_BROWSER=true gemini را اجرا کنید یا از مسیر API-key (GEMINI_API_KEY) استفاده کنید. در یک نشست SSH معمولی، باید به جای آن Enter the authorization code: را ببینید؛ URL را در مرورگر لپ‌تاپ خود تأیید کنید و کدی که Google نمایش می‌دهد را paste کنید.

فرآیند با قطع شدن SSH ناپدید شد. شما gemini را مستقیماً از shell مربوط به SSH اجرا کردید، بنابراین آن فرآیند فرزند آن shell بود و با قطع شدن pty از بین رفت. چیزی برای بازیابی وجود ندارد. هر نشست را با tmux new -A -s gemini شروع کنید و CLI را درون آن اجرا کنید.

احراز هویت با وجود تنظیم کلید همچنان شکست می‌خورد، CLI به انتخابگر auth بازمی‌گردد، یا یک درخواست با API key not valid و HTTP 400 مواجه می‌شود. کلید در محیطی که CLI می‌بیند وجود ندارد. با printenv GEMINI_API_KEY تأیید کنید؛ اگر خالی است، ~/.gemini_env شما هرگز source نشده است. بررسی کنید که این خط در ~/.bashrc وجود داشته باشد، فایلی که shellهای تعاملی (از جمله tmux) آن را می‌خوانند اما cron و سایر shellهای غیرتعاملی آن را نمی‌خوانند. یک فضای خالی یا کوتیشن اضافه در مقدار کلید نیز منجر به API key not valid می‌شود.

429 / RESOURCE_EXHAUSTED / یک پیام محدودیت نرخ (rate-limit). شما سهمیه مربوط به سطح (tier) احراز هویت خود را تمام کرده‌اید. منتظر بمانید تا بازه زمانی بازنشانی شود، سرعت agent را کاهش دهید یا به یک API key پولی مهاجرت کنید. یک agent که در حلقه تلاش مجدد (retry loop) گیر کرده است، مدام این خطا را دریافت می‌کند؛ آن را متوقف کرده و بررسی کنید چه کاری انجام می‌دهد.

FAQ

چگونه Gemini CLI را روی یک سرور headless احراز هویت کنم؟

از یک API key پولی استفاده کنید، نه ورود از طریق مرورگر. یک کلید در Google AI Studio روی پروژه‌ای که دارای صورت‌حساب است ایجاد کنید، آن را در فایلی با دسترسی 600 قرار دهید که shell شما آن را source می‌کند (export GEMINI_API_KEY=...)؛ با این کار، CLI به‌طور کامل از فرآیند OAuth مرورگر عبور می‌کند. اگر به‌جای آن با حساب Google وارد شوید، برای مثال در لایسنس‌های Code Assist Standard یا Enterprise، CLI روی سرور headless یک URL چاپ می‌کند؛ آن را در لپ‌تاپ خود باز کنید، تأیید کنید و کدی که Google نمایش می‌دهد را در پرامپت Enter the authorization code: وارد کنید. هیچ پورتی برای باز کردن یا تونلی برای ایجاد وجود ندارد، اما چون نیاز به حضور شما در مرورگر دارد، برای اسکریپت‌ها مناسب نیست. حساب‌های شخصی رایگان از تاریخ 18 ژوئن 2026 توسط Gemini CLI پشتیبانی نمی‌شوند.

چرا نصب سراسری npm نیاز به sudo دارد و چگونه از آن اجتناب کنم؟

زیرا پیشوند سراسری پیش‌فرض npm مسیر /usr/lib/node_modules است که کاربر شما اجازه نوشتن در آن را ندارد، بنابراین دستور ساده npm install -g با خطای EACCES مواجه می‌شود. راه حل اشتباه استفاده از sudo npm -g است که فایل‌هایی با مالکیت root باقی می‌گذارد و باعث خرابی نصب‌های بعدی می‌شود. راه حل درست این است که پیشوند را به دایرکتوری home خود (npm config set prefix ~/.npm-global) تغییر دهید و مسیر bin آن را به PATH اضافه کنید، یا از nvm استفاده کنید که بسته‌های سراسری را به‌طور خودکار در home شما نصب می‌کند.

چگونه Gemini CLI را پس از قطع اتصال فعال نگه دارم؟

آن را داخل tmux اجرا کنید. فرآیندی که از shell مربوط به SSH شروع شده باشد، با قطع اتصال از بین می‌رود زیرا فرزند آن shell محسوب می‌شود؛ tmux آن shell را تحت یک سرور جداگانه اجرا می‌کند که پس از قطع اتصال زنده می‌ماند. از tmux new -A -s gemini استفاده کنید، gemini را داخل آن اجرا کنید، با Ctrl-b d جدا شوید و بعداً با tmux attach -t gemini دوباره متصل شوید.

آیا اجرای Gemini CLI روی سرور production امن است؟

فقط با احتیاط، زیرا یک عامل (agent) با دسترسی shell می‌تواند هر کاری که کاربرِ اجراکننده آن اجازه دارد را انجام دهد. آن را به‌عنوان یک کاربر اختصاصی بدون امتیاز (unprivileged) و بدون دسترسی sudo اجرا کنید، اعتبارنامه‌های production را روی آن ماشین قرار ندهید، از تأیید خودکار --yolo اجتناب کنید و از --sandbox (Docker یا Podman) برای ایزوله کردن فراخوانی ابزارها از host استفاده کنید. حسابی که CLI تحت آن اجرا می‌شود، از هر flag تکی که تنظیم می‌کنید اهمیت بیشتری دارد.

آیا نیاز است پورت‌های فایروال را برای Gemini CLI باز کنم؟

خیر. این یک کلاینت است که فراخوانی‌های HTTPS خروجی به APIهای Google انجام می‌دهد، بنابراین به پورت خروجی 443 نیاز دارد اما هیچ پورت ورودی لازم ندارد. ورود به سیستم Google روی سرور headless نیز به هیچ پورتی نیاز ندارد: شما به‌جای دریافت callback روی سرور، یک کد را در ترمینال وارد می‌کنید. دسترسی‌های ورودی را مسدود نگه دارید.

#gemini-cli#node#tmux#headless#ai #vps