تشغيل Gemini CLI على خادم VPS بلا واجهة رسومية

ما الذي تبنيه

Gemini CLI يعمل باستمرار على خادم تملكه، ويمكن الوصول إليه عبر SSH، وينفّذ مهام وكيل طويلة تواصل العمل بعد إغلاق الحاسوب المحمول. يتطلب التثبيت 3 أوامر. أما العمل الفعلي فيتعلق بكل ما يفترض وجود حاسوب مكتبي: إذ تريد أداة Google CLI فتح متصفح لتسجيل الدخول، بينما لا يحتوي خادمك على متصفح. لذلك يركّز معظم هذا الدليل على المسار الذي لا يتطلب واجهة رسومية، وعلى تثبيت إصدار حديث من Node لا توفره التوزيعة، وعلى تثبيت npm عاماً لا يحتاج إلى root، وعلى المصادقة دون متصفح باستخدام مفتاح API تحفظه بعيداً عن سجل أوامر shell، وعلى tmux كي لا تؤدي جلسة SSH المنقطعة إلى إيقاف المهمة قيد التشغيل.

Gemini CLI هو برنامج Node مفتوح المصدر (Apache-2.0) (@google/gemini-cli) يتصل بنماذج Gemini من Google، ويمكنه قراءة الملفات وكتابتها، وتشغيل أوامر shell، وتشغيل الأدوات في دليل العمل. وعلى VPS، يوفّر وكيلاً صغيراً متاحاً دائماً يمكنك تركه يعمل. لذلك يهم الحساب الذي يعمل به، وبيانات الاعتماد الموجودة على الخادم، أكثر من أي إعداد منفرد هنا.

المتطلبات الأساسية والمشكلات العملية المهمة

• خادم KVM VPS جديد يعمل بنظام Ubuntu 24.04، مع صلاحيات root أو sudo. تناسبه أي خطة KVM؛ فواجهة CLI نفسها خفيفة وتستهلك بضع مئات من MB من الذاكرة عند عدم وجود حمل.
• Node.js بإصدار 20 أو أحدث. هذا هو الحد الأدنى الإلزامي الوحيد للإصدار، بينما إصدار حزمة التوزيعة أقل منه؛ راجع القسم التالي.
• اتصال HTTPS صادر (على المنفذ 443) إلى واجهات Google البرمجية. لا تحتاج إلى أي منافذ واردة؛ فهذا عميل وليس خادماً، لذلك لا تفتح له منفذاً في الجدار الناري.
• طريقة للمصادقة لا تحتاج إلى متصفح على الخادم: إما مفتاح Gemini API من Google AI Studio، أو نفق SSH إلى متصفح على جهازك. يناسب مسار مفتاح API البرامج النصية وعمليات التشغيل غير التفاعلية.
• Docker أو Podman، إذا أردت عزل --sandbox فقط. هذا اختياري، وسنتناوله قرب النهاية.

المشكلة العملية التي تواجه الجميع هي أن تدفق تسجيل الدخول الأول gemini مصمم لأجهزة سطح المكتب. يحاول فتح متصفح، وعلى خادم بلا واجهة رسومية يفشل أحياناً أو يعرض رابطاً لا يعمل. حدّد طريقة المصادقة قبل أن تبدأ.

Node: حزمة التوزيعة قديمة جداً

توفّر Ubuntu 24.04 الإصدار Node 18.19.1 في مستودعاتها، مع npm 9.2.0. يحدّد Gemini CLI في package.json الإصدار 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 على بيئة تشغيل غير مدعومة. وقد يتصرف بشكل غير صحيح أو يتعطل عند وصوله إلى واجهة برمجة تطبيقات في Node 20 أو إصدار أحدث، ويتوقع وجودها. كما وصل Node 18 إلى نهاية دورة حياته في April 2025، لذلك لن يحل المشكلة بأي حال. ثبّت إصدار LTS حديثاً قبل تثبيت CLI. المساران المناسبان هما 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 أو قيمة أعلى، وv24.x هو إصدار LTS النشط حالياً. راجع صفحة NodeSource لمعرفة أحدث script للإعداد. تشير 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 والحزم العامة الخاصة به تحت ~/.nvm، لذلك لا تحدث مشكلة صلاحيات التثبيت العام المذكورة في القسم التالي. إذا اخترت nvm، فيمكنك تجاوز خطوة npm-prefix.

ثبّت CLI من دون sudo npm -g

قد يبدو الأمر sudo npm install -g @google/gemini-cli مناسباً. لا تستخدمه. يؤدي ضبط global prefix مملوك لـ root إلى ظهور أخطاء صلاحيات في كل عملية تثبيت لاحقة، كما يترك ملفات مملوكة لـ root في npm cache، وقد تسبب مشكلات بعد أشهر. إذا شغّلت 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، بل توجيه global prefix في npm إلى مجلدك الشخصي، حتى تصل عمليات التثبيت العامة إلى مكان تملكه:

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 داخله بعد قسمين من الآن، shell غير تفاعلي لتسجيل الدخول، ويقرأ ~/.bashrc ويتجاوز ~/.profile. لذلك، إذا وضعت سطر PATH في الملف الخطأ، فسيبقى gemini غير مرئي تحديداً في المكان الذي تحتاج إليه. يكفي أن يطبع gemini --version رقم إصدار لاختبار الإعداد. إذا ظهر لك بدلاً من ذلك gemini: command not found، فهذا يعني أن تصدير PATH لم يُطبَّق؛ راجع أوضاع الفشل. مع nvm، تجاوز أسطر prefix بالكامل، لأنه يثبّت الحزم العامة في مجلدك الشخصي أصلاً.

إذا شغّلت sudo npm في وقت سابق، وظهر لك الآن Your cache folder contains root-owned files، فأصلح المشكلة مرة واحدة باستخدام sudo chown -R $(id -u):$(id -g) ~/.npm.

مشكلة المصادقة في الوضع غير التفاعلي وكيفية تجاوزها

شغّل gemini بشكل تفاعلي في المرة الأولى، وسيعرض عليك تسجيل الدخول باستخدام حساب Google. على جهاز سطح المكتب، يفتح ذلك علامة تبويب في المتصفح. أما على VPS غير المزود بواجهة رسومية، فلا يوجد متصفح، لذلك إما أن يطبع المسار عنوان URL محلياً يتوقع منك فتحه، أو يفشل مباشرة برسالة مثل:

Failed to open browser. Please visit the following URL to authorize:
https://accounts.google.com/o/oauth2/v2/auth?...&redirect_uri=http://localhost:PORT

تكمن المشكلة في redirect_uri=http://localhost:PORT. حتى إذا فتحت عنوان URL على حاسوبك المحمول ووافقت، يعيد Google التوجيه إلى http://localhost:PORT، أي إلى localhost على الخادم، وهو منفذ لا يمكن لأي شيء على حاسوبك المحمول الوصول إليه. ولن تكتمل عملية تسجيل الدخول.

هناك طريقتان مباشرتان لتجاوز ذلك.

الطريقة الأولى هي استخدام مفتاح API، وهي الخيار الافتراضي الصحيح للخادم. أنشئ مفتاحاً في Google AI Studio (aistudio.google.com)، ومرّره إلى CLI كمتغير بيئة؛ إذ يقرأ GEMINI_API_KEY ويتجاوز تدفق المتصفح بالكامل. والآن ننتقل إلى جزء "إبقاؤه خارج سجل الأوامر والملفات القابلة للقراءة من الجميع". لا تكتب export GEMINI_API_KEY=AIza... عند المطالبة، لأنه سيُحفظ في ~/.bash_history بنص واضح، ولا تضعه في ملف يمكن للآخرين قراءته. اكتب المفتاح في ملف بصلاحيات mode-600 يحمّله shell عند البدء:

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 الشخصي، مع طبقته المجانية، وذلك عبر تمرير استدعاء OAuth العكسي إلى حاسوبك المحمول. المشكلة أن خادم loopback لدى CLI يرتبط بمنفذ عشوائي في كل تشغيل، لذلك لا يوجد منفذ ثابت لإعادة التوجيه ما لم تثبّته أولاً باستخدام متغير البيئة OAUTH_CALLBACK_PORT، ثم تعيد توجيه المنفذ نفسه تماماً:

# from your laptop, forward the callback port into the SSH session:
ssh -L 8085:localhost:8085 user@your-server
# then, on the server, pin the callback to the same port and start the CLI:
export OAUTH_CALLBACK_PORT=8085
gemini

لا يستطيع CLI فتح متصفح، لذلك يطبع عنوان URL للمصادقة؛ افتحه في متصفح حاسوبك المحمول ووافق، وعندما يعيد Google التوجيه إلى http://localhost:8085/...، ينقل SSH هذا الطلب عبر النفق إلى خادم loopback على VPS، وتكتمل عملية تسجيل الدخول. إذا تركت المنفذ غير مثبت، فسيُستخدم منفذ عشوائي جديد في كل تشغيل، ولن يتمكن أي ssh -L أعددته مسبقاً من التقاطه. تعمل هذه الطريقة، لكنها تتطلب وجودك أمام متصفح، لذلك لا تصلح للبرامج النصية. استخدم مفتاح API لأي شيء تتركه قيد التشغيل.

بالنسبة إلى Vertex AI أو مشروع Google Cloud بدلاً من AI Studio، اضبط GOOGLE_API_KEY مع GOOGLE_GENAI_USE_VERTEXAI=true، أو GOOGLE_CLOUD_PROJECT للحصول على ترخيص Code Assist، مع تطبيق الانضباط نفسه على متغيرات البيئة والملف ذي الصلاحيات mode-600.

شغّله داخل tmux حتى لا تنهي جلسة SSH المنقطعة تشغيله

تكون عملية gemini التي تشغّلها مباشرةً من صدفة SSH تابعةً لتلك الصدفة. إذا فُقد الاتصال، أو أُغلق الحاسوب المحمول، أو انقطع Wi-Fi، أو انتهت مهلة الخمول، فإن sshd ينهي الطرفية الوهمية، وتتلقى الصدفة الإشارة SIGHUP، ثم تنهي بدورها اتصال CLI. تتوقف المهمة التي كانت قد أمضت عشر دقائق في تحرير الملفات، ولا تعود هناك عملية يمكن استعادتها عند إعادة الاتصال.

يحل tmux هذه المشكلة بتملّك الصدفة بدلاً من أن تكون sshd مالكتها. هذا هو النمط نفسه المستخدم في تشغيل وكيل ترميز بالذكاء الاصطناعي على 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 بجلسة تحمل الاسم gemini إذا كانت موجودة، وتنشئها إذا لم تكن موجودة، لذلك فهي الأمر الوحيد الذي تحتاج إلى تشغيله مباشرةً بعد كل تسجيل دخول. تنتمي الصدفة الموجودة داخل الجلسة إلى خادم tmux المنفصل، لا إلى جلسة SSH، ولذلك يترك انقطاع الاتصال CLI قيد التشغيل. أعد الاتصال، ثم اتصل بالجلسة، وستعود إلى سجل التمرير نفسه. إذا شغّلت عدة جلسات للوكلاء على خادم واحد، فأنشئ جلسة tmux لكل جلسة. لا يمكن لهذه الجلسات التواصل مع بعضها هنا، بخلاف Claude Code، حيث يمكن لـجلسة واحدة تمرير نص إلى جلسة أخرى على VPS نفسه، لذلك أبقِ كل مهمة Gemini مستقلة أو نسّق بينها عبر الملفات الموجودة على القرص.

لعمليات التشغيل غير التفاعلية والمبرمجة، يتضمن Gemini CLI وضعاً بلا واجهة تفاعلية: يطبع gemini -p "summarise the failing tests in this repo" إجابةً ثم يخرج، ويوفّر --output-format json مخرجات قابلة للمعالجة آلياً لتمريرها إلى مكان آخر. يكون الوضع بلا واجهة تفاعلية مع مفتاح API مناسباً تماماً داخل جلسة tmux تشغّل مهمة دفعية طويلة، أو عند تشغيله من إدخال cron، مع ملاحظة واحدة: لا يحمّل cron أياً من ملفات تسجيل الدخول، لذلك امنح سطر crontab قيمة GEMINI_API_KEY الخاصة به، أو اجعل الأمر يحمّل ~/.gemini_env، وإلا فسيعود CLI إلى تدفق المصادقة عبر المتصفح ويفشل.

العزل وصلاحيات الوصول على خادم يشغّل الإنتاج أيضاً

الوكيل الذي يملك وصولاً إلى shell يملك وصولاً إلى shell. يمكن لـ Gemini CLI تشغيل الأوامر، وهو يطلب افتراضياً التأكيد قبل كل أمر ينطوي على مخاطر، لكن المستخدمين قد يلجؤون إلى --yolo (الموافقة التلقائية على كل استدعاء لأداة). عندها يمكنه حذف الملفات، أو الدفع إلى git، أو الوصول إلى الخدمات الداخلية بالصلاحيات الكاملة للمستخدم الذي يعمل به. على خادم يشغّل الإنتاج أيضاً، يمثل ذلك نطاق تأثير فعلياً، وليس احتمالاً افتراضياً.

ثلاثة إجراءات للتحكم، مرتبة حسب مقدار الفائدة التي توفرها:

• شغّله باستخدام مستخدم مخصص لا يملك صلاحيات مرتفعة. لا تستخدم root، ولا مستخدماً عضواً في sudo. أنشئ مستخدم agent مع home خاص به، وثبّت Node وCLI فيه، وبذلك يظل أي تفسير خاطئ للتعليمات محصوراً في ذلك الحساب. هذا هو القرار الأعلى قيمة على الإطلاق.
• أبقِ بيانات اعتماد الإنتاج خارج الخادم. لا تضع ~/.aws/credentials الخاص بالإنتاج، ولا تنسخ .env من الإنتاج، ولا تستخدم كلمة مرور قاعدة بيانات تملك صلاحية الكتابة إلى أي مورد مهم. امنحه بيانات اعتماد لبيئة staging أو بيانات اعتماد للقراءة فقط.
• استخدم العزل المضمّن. عند تثبيت Docker أو Podman، يشغّل gemini --sandbox (أو GEMINI_SANDBOX=docker) استدعاءات أدوات الوكيل داخل حاوية معزولة عن نظام ملفات المضيف وشبكته. لا يحل ذلك محل المستخدم غير ذي الصلاحيات المرتفعة، لكنه يوفر طبقة ثانية قوية عندما يؤدي VPS نفسه أعمالاً فعلية.

إذا كنت تشغّل Gemini CLI إلى جانب أدوات أخرى مستضافة ذاتياً، مثل خادم MCP يعرّض الأدوات للوكيل على VPS نفسه، فاعتبر كل قدرة إضافية سطحاً يمكن للوكيل الوصول إليه، وقيّد الرموز المميزة التي تمنحه إياها لتقتصر على مهمة واحدة تحديداً.

الحصة والتكلفة ومسار المصادقة الذي اخترته

يحدد مسار المصادقة طريقة احتساب التكلفة عليك. يستخدم حساب Google الشخصي، عبر مسار OAuth، الطبقة المجانية من Gemini Code Assist، مع حدود فعلية لكل دقيقة ولكل يوم. إذا تجاوزت هذه الحدود، تعيد الطلبات خطأ تجاوز معدل الطلبات إلى أن تُعاد تهيئة النافذة الزمنية. قد يكون مفتاح API من AI Studio ضمن الطبقة المجانية أو خاضعاً للفوترة، وذلك حسب المشروع. يرفع المفتاح الخاضع للفوترة الحدود، وتُحتسب التكلفة لكل رمز. تُحتسب تكلفة المصادقة عبر Vertex وCloud project من خلال Google Cloud.

هناك ملاحظتان عمليتان. يمكن لوكيل يعمل دون تدخل وفي حلقة أن يستهلك الحصة بسرعة، لذلك راقبه في المرات الأولى قبل أن تثق به ضمن مهمة cron. وإذا كان سبب استخدامك لنموذج على الخادم هو الخصوصية أو الاستدلال غير الخاضع للقياس، وليس نماذج Google المستضافة، فهذه أداة مختلفة؛ إن استضافة LLM مفتوح المصدر ذاتياً باستخدام Ollama على VPS، فستبقى الأوزان والمطالبات على خادمك، لكنك ستشغّل نموذجاً أصغر بكثير من Gemini.

تحديثه باستمرار

يصدر Gemini CLI إصدارات جديدة كثيراً. وبما أنك ثبّتَّه في prefix يملكه المستخدم، فلن تحتاج التحديثات إلى sudo:

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

تتوفر قنوات إصدار متعددة: @latest هي القناة المستقرة، و@preview هي المعاينة الأسبوعية، و@nightly هي الأحدث والأقل استقراراً. ثبّت الإصدار على @latest لكل ما تعتمد عليه. في nvm، تُخزَّن الحزم العامة ضمن إصدار Node النشط. لذلك، بعد استخدام nvm use للتبديل بين إصدارات Node، قد تحتاج إلى إعادة تثبيت CLI. اقرأ ملاحظات الإصدار بدلاً من تثبيت كل تصحيح فور صدوره.

أنماط الفشل، مع السلاسل النصية الدقيقة

npm WARN EBADENGINE Unsupported engine ... required: { node: '>=20' }، ثم تعطل CLI أثناء التشغيل. إصدار Node قديم، وهو إصدار 18.19.1 في التوزيعة، وقد انتهى دعمه أيضاً. ثبّت Node 20+ من NodeSource أو nvm، وتحقق باستخدام node --version. وإذا كانت لديك عدة إصدارات من Node، فتحقق من أن which node يشير إلى الإصدار الجديد وليس إلى /usr/bin/node.

npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. حدث تثبيت عام داخل prefix مملوك لـroot. لا تستخدم sudo لهذا الأمر. اضبط npm config set prefix ~/.npm-global، وأضف ~/.npm-global/bin إلى PATH، ثم أعد التثبيت كمستخدمك العادي. إذا ترك sudo npm السابق ملفات cache مملوكة لـroot (Your cache folder contains root-owned files)، فنفّذ sudo chown -R $(id -u):$(id -g) ~/.npm.

Failed to open browser، أو تسجيل دخول يتوقف، أو redirect_uri=http://localhost:PORT لا يمكنك الوصول إليه. يتطلب مسار OAuth متصفحاً غير متوفر على الخادم، كما أن callback المحلي يشير إلى الخادم لا إلى حاسوبك المحمول. استخدم مسار مفتاح API (GEMINI_API_KEY)، أو ثبّت OAUTH_CALLBACK_PORT، ومرّره عبر SSH باستخدام ssh -L، ثم افتح URL محلياً.

اختفت العملية عند انقطاع SSH. شغّلت gemini مباشرة من shell الخاص بـSSH، لذلك كانت عملية فرعية لذلك shell وتوقفت مع pty عند قطع الاتصال. لا يوجد شيء يمكن استعادته. ابدأ كل جلسة باستخدام tmux new -A -s gemini وشغّل CLI داخلها.

ما زالت المصادقة تفشل رغم ضبط المفتاح، أو يعود CLI إلى منتقي المصادقة، أو يعيد طلب ما API key not valid مع HTTP 400. المفتاح غير موجود في البيئة التي يراها CLI. تحقّق باستخدام printenv GEMINI_API_KEY. إذا كانت النتيجة فارغة، فهذا يعني أن ~/.gemini_env لم يُحمَّل. تحقق من وجود السطر في ~/.bashrc، الذي تقرؤه shell التفاعلية، بما فيها tmux، لكن cron وغيرها من shells غير التفاعلية لا تقرؤه. كما أن وجود مسافة أو علامة اقتباس زائدة داخل قيمة المفتاح ينتج API key not valid.

429 / RESOURCE_EXHAUSTED / رسالة تفيد بتجاوز حد المعدل. لقد تجاوزت الحصة الخاصة بالمستوى الذي تستخدمه مصادقتك. انتظر حتى تُعاد تهيئة النافذة، أو خفّض سرعة الوكيل، أو انتقل إلى مفتاح API مدفوع. إذا علق وكيل في حلقة إعادة المحاولة، فأوقفه وتحقق مما يفعله.

FAQ

كيف أصادق Gemini CLI على خادم بلا واجهة رسومية؟

استخدم مفتاح API، وليس تسجيل الدخول عبر المتصفح. أنشئ مفتاحاً في Google AI Studio، وضعه في ملف بصلاحيات 600 يقرأه shell عند بدء التشغيل (export GEMINI_API_KEY=...)، وسيتجاوز CLI تدفق OAuth عبر المتصفح بالكامل. إذا كنت تريد تحديداً الطبقة المجانية للحساب الشخصي، ثبّت منفذ loopback باستخدام OAUTH_CALLBACK_PORT=8085، وأعد توجيهه إلى حاسوبك المحمول باستخدام ssh -L 8085:localhost:8085 user@server، ثم افتح الرابط المطبوع محلياً. لكن هذا يتطلب وجودك أمام متصفح، لذلك لا يناسب البرامج النصية.

لماذا يطلب التثبيت العام لـnpm استخدام sudo، وكيف أتجنب ذلك؟

لأن البادئة العامة الافتراضية لـnpm هي /usr/lib/node_modules، ولا يستطيع مستخدمك الكتابة إليها، لذلك يفشل npm install -g العادي مع EACCES. الحل الخاطئ هو sudo npm -g، لأنه يترك ملفات مملوكةً لـroot وتؤدي إلى فشل عمليات التثبيت اللاحقة. الحل الصحيح هو توجيه البادئة إلى مجلدك المنزلي (npm config set prefix ~/.npm-global)، وإضافة مساره bin إلى PATH، أو استخدام nvm، الذي يثبّت الحزم العامة داخل مجلدك المنزلي تلقائياً.

كيف أُبقي Gemini CLI قيد التشغيل بعد قطع الاتصال؟

شغّله داخل tmux. تموت العملية التي تبدأها من shell الخاص بـSSH عند انقطاع الاتصال، لأنها ابنة ذلك shell؛ بينما يشغّل tmux الـshell داخل خادم منفصل يستمر بعد انقطاع الاتصال. استخدم tmux new -A -s gemini، وشغّل gemini داخله، وافصل الجلسة باستخدام Ctrl-b d، ثم أعد الاتصال بها لاحقاً باستخدام tmux attach -t gemini.

هل من الآمن تشغيل Gemini CLI على خادم إنتاج؟

يمكن ذلك بحذر فقط، لأن الوكيل الذي يملك صلاحية shell يستطيع تنفيذ أي إجراء يستطيع المستخدم الذي يشغّله تنفيذَه. شغّله كمستخدم مخصص غير مميّز ولا يملك sudo، وأبقِ بيانات اعتماد الإنتاج خارج الجهاز، وتجنب الموافقة التلقائية عبر --yolo، واستخدم --sandbox (Docker أو Podman) لعزل استدعاءات الأدوات عن المضيف. حساب المستخدم الذي يعمل به أهم من أي خيار منفرد تضبطه.

هل أحتاج إلى فتح أي منافذ في جدار الحماية لاستخدام Gemini CLI؟

لا. فهو عميل يجري اتصالات HTTPS صادرة إلى واجهات Google API، لذلك يحتاج إلى المنفذ الصادر 443، ولا يحتاج إلى منافذ واردة. إذا استخدمت نفق OAuth، فإن منفذ الاستدعاء الراجع المثبّت، مثل 8085، يعمل على localhost ويُوصل إليه عبر إعادة توجيه SSH، وليس عبر منفذ وارد مفتوح. أبقِ الاتصالات الواردة محجوبة.