بقلم Matt Connor
تشغيل Gemini CLI على خادم VPS بلا واجهة رسومية
شغّل Gemini CLI على VPS عبر SSH: ثبّت Node 20 أو أحدث دون sudo، وصادق بمفتاح API بلا متصفح، واستخدم tmux لمواصلة المهام بعد انقطاع الاتصال.
ما الذي تبنيه
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، يوفّر وكيلاً صغيراً متاحاً دائماً يمكنك تركه يعمل. لذلك يهم الحساب الذي يعمل به، وبيانات الاعتماد الموجودة على الخادم، أكثر من أي إعداد منفرد هنا.
المتطلبات الأساسية والتنبيهات المهمة
- خادم VPS جديد يعمل بنظام Ubuntu 24.04 عبر KVM، مع صلاحيات root أو sudo. تناسبه أي خطة KVM؛ فواجهة CLI نفسها خفيفة، وتستهلك بضع مئات من MB من الذاكرة عند عدم وجود نشاط.
- Node.js بإصدار 20 أو أحدث. هذا هو الحد الأدنى الصارم للإصدار، وحزمة التوزيعة أقدم منه؛ راجع القسم التالي. انتهى دعم Node 20 في 30 أبريل 2026، لذلك ثبّت الإصدار 24.
- اتصال HTTPS صادر (المنفذ 443) بواجهات Google البرمجية. لا تحتاج إلى منافذ واردة؛ فهذا عميل وليس خادماً، لذلك لا تفتح منفذاً في الجدار الناري من أجله.
- طريقة للمصادقة لا تتطلب متصفحاً على الخادم: إما مفتاح Gemini API مدفوع من Google AI Studio، أو تسجيل الدخول إلى Google، الذي يتطلب على خادم بلا واجهة رسومية لصق رمز مرة أخرى في الطرفية. يناسب مسار مفتاح API البرامج النصية وعمليات التشغيل غير التفاعلية.
- Docker أو Podman، فقط إذا أردت استخدام العزل
--sandbox. هذا اختياري، وسنغطيه قرب النهاية.
المشكلة التي تفاجئ الجميع الآن تتعلق بالحساب، لا بالمتصفح. أعلنت Google في 19 مايو 2026 أنه اعتباراً من 18 يونيو 2026 سيتوقف Gemini CLI عن معالجة الطلبات للمشتركين في Google AI Pro وUltra ولأي شخص يستخدمه مجاناً، وستوجّه هؤلاء المستخدمين إلى البديل Antigravity CLI (agy). ما يزال Gemini CLI يعمل مع مفاتيح Gemini API المدفوعة، ومفاتيح Gemini Enterprise Agent Platform API، وترخيص Gemini Code Assist Standard أو Enterprise الخاص بالمؤسسة. حدّد مسار المصادقة قبل البدء.
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 أو قيمة أعلى حتى يستوفي متطلبات CLI، لكن انتهى دعم Node 20 في April 30, 2026، لذلك استهدف v24.x، وهو إصدار LTS النشط حالياً. ومن المقرر أن يصبح Node 26 إصدار LTS النشط في October 28, 2026. راجع صفحة NodeSource لمعرفة سكربت الإعداد الحالي؛ يمثّل setup_24.x في عنوان URL السطر الذي يجب تغييره عند صدور إصدار LTS أحدث.
nvm، إذا كنت تفضّل إبقاء Node داخل المجلد الرئيسي لمستخدم واحد وعدم استخدام 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 يعمل بنظام Linux دون واجهة رسومية، يتحقق 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 العادي، لكنه يتطلب وجودك أمام متصفح في كل مرة. ومنذ June 18, 2026، لن يتيح لك تسجيل الدخول إلا إذا كان حساب Google الخاص بك من الحسابات التي ما زال Gemini CLI يخدمها.
هناك طريقتان مباشرتان لتجاوز ذلك.
الأولى هي استخدام مفتاح API، وهي الخيار الافتراضي المناسب للخادم. أنشئ مفتاحاً في Google AI Studio (aistudio.google.com) ضمن مشروع مفعّل عليه الفوترة، لأن Gemini CLI لم يعد يوفّر الاستخدام المجاني، ثم مرّره إلى 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 نفسه. وعلى جهاز لا يوفّر واجهة رسومية، لا تحتاج هذه الطريقة إلى نفق أو منفذ مفتوح. ومنذ June 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 لأي شيء ستتركه قيد التشغيل.
بالنسبة إلى 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 مخرجات قابلة للقراءة آلياً لإرسالها عبر pipe إلى مكان آخر. يكون استخدام الوضع دون واجهة تفاعلية مع مفتاح API مناسباً تماماً داخل جلسة tmux تشغّل مهمة دفعات طويلة، أو عند تشغيلها من إدخال cron، مع ملاحظة واحدة: لا يقرأ cron أياً من ملفات تسجيل الدخول، لذلك امنح سطر crontab الخاص به GEMINI_API_KEY (أو اجعل الأمر يقرأ ~/.gemini_env)، وإلا تفشل العملية بسبب غياب بيانات الاعتماد.
العزل والصلاحيات على خادم يشغّل أيضاً خدمات الإنتاج
الوكيل الذي يملك وصول shell هو shell. يمكن لـ Gemini CLI تشغيل الأوامر، وهو يطلب التأكيد قبل كل أمر محفوف بالمخاطر بشكل افتراضي، لكن المستخدمين يلجؤون إلى --yolo (الموافقة التلقائية على كل استدعاء لأداة)، وعندها يمكنه حذف الملفات، أو الدفع إلى git، أو الوصول إلى الخدمات الداخلية بالصلاحيات الكاملة للمستخدم الذي يعمل باسمه. على خادم يشغّل أيضاً خدمات الإنتاج، يمثل ذلك نطاق تأثير فعلياً، وليس احتمالاً نظرياً.
ثلاثة ضوابط، مرتبة حسب مقدار الفائدة التي توفرها:
- شغّله كمستخدم مخصص وغير مميّز. ليس root، وليس عضواً في
sudo. أنشئ مستخدمagentبدليله الرئيسي الخاص، وثبّت Node وCLI فيه، وبذلك تبقى التعليمات التي أسيء فهمها محصورة في ذلك الحساب. هذا هو القرار الأعلى قيمة منفرداً. - أبقِ بيانات اعتماد الإنتاج خارج الخادم. لا تضع
~/.aws/credentialsالخاص بالإنتاج، ولا تنسخ.envمن الإنتاج، ولا تستخدم كلمة مرور قاعدة بيانات تملك صلاحية الكتابة إلى أي مورد مهم. امنحه بيانات اعتماد لبيئة staging أو بيانات اعتماد للقراءة فقط. - استخدم العزل المضمّن. عند تثبيت Docker أو Podman، يشغّل
gemini --sandbox(أوGEMINI_SANDBOX=docker) استدعاءات أدوات الوكيل داخل حاوية لا تربط إلا دليل المشروع الحالي، وليس بقية نظام ملفات المضيف. لا يحل ذلك محل المستخدم غير المميّز، لكنه يوفر طبقة ثانية قوية عندما ينفذ VPS نفسه أعمالاً فعلية.
إذا كنت تشغّل Gemini CLI بجوار أدوات أخرى مستضافة ذاتياً، مثل خادم MCP يعرّض أدوات للوكيل على VPS نفسه، فاعتبر كل قدرة إضافية مساحة أخرى يمكن للوكيل الوصول إليها، وقيد الرموز المميزة التي تمنحه إياها لتقتصر على مهمة واحدة بالضبط.
الحصص والتكلفة ومسار المصادقة الذي اخترته
يحدد مسار المصادقة طريقة فوترة استخدامك، ومنذ June 18, 2026 يحدد أيضاً ما إذا كانت الخدمة ستستجيب لك أصلاً. ووفقاً لإعلان Google، توقّف Gemini CLI اعتباراً من ذلك التاريخ عن معالجة الطلبات للمشتركين في Google AI Pro وUltra ولأي شخص يستخدمه مجاناً، ويشمل ذلك المستوى المجاني للحسابات الشخصية ومفاتيح API غير المفوترة. وما زال متاحاً عبر مفاتيح Gemini API المدفوعة ومفاتيح Gemini Enterprise Agent Platform API، التي تُحاسب حسب عدد الرموز، وكذلك للمؤسسات التي تملك ترخيص Gemini Code Assist Standard أو Enterprise أو وصولاً آخر إلى Google Cloud، حيث تتم الفوترة عبر 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، وقد انتهى دعمه أيضاً. ثبّت إصدار LTS حالياً من NodeSource أو nvm. يفي Node 20 بالحد الأدنى المطلوب من CLI، لكنه انتهى دعمه نفسه منذ April 2026. تحقّق باستخدام node --version. إذا كانت لديك عدة إصدارات من Node مثبتة، فتحقّق من أن which node يشير إلى الإصدار الجديد وليس إلى /usr/bin/node.
npm error code EACCES / permission denied, mkdir '/usr/lib/node_modules/...'. حدث تثبيت عام داخل مسار مملوك لـ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://127.0.0.1:PORT لا يمكنك الوصول إليه. عثر CLI على متغير display، غالباً من ssh -X، واستخدم مسار loopback الذي تصل فيه callback إلى الخادم. نفّذ NO_BROWSER=true gemini لاستخدام مسار لصق الرمز، أو استخدم مسار API key عبر GEMINI_API_KEY. في جلسة SSH عادية، يجب أن ترى Enter the authorization code: بدلاً من ذلك. وافق على URL في متصفح laptop، ثم الصق الرمز الذي يعرضه Google.
اختفت العملية عند انقطاع SSH. شغّلت gemini مباشرة من shell الخاص بـSSH، لذلك كانت ابنة ذلك shell وانتهت مع pty عند قطع الاتصال. لا يوجد شيء يمكن استعادته. ابدأ كل جلسة باستخدام tmux new -A -s gemini، ثم شغّل CLI داخلها.
لا تزال المصادقة تفشل رغم ضبط key، أو يعود CLI إلى منتقي المصادقة، أو يعيد طلب ما API key not valid مع HTTP 400. لا توجد key في البيئة التي يراها CLI. تحقّق باستخدام printenv GEMINI_API_KEY. إذا كانت النتيجة فارغة، فلم يُحمّل ~/.gemini_env مطلقاً. تحقّق من وجود السطر في ~/.bashrc، الذي تقرؤه interactive shells، بما فيها tmux، بينما لا تقرؤه cron وغيرها من non-interactive shells. كما يؤدي وجود مسافة أو علامة اقتباس زائدة داخل قيمة key إلى API key not valid.
429 / RESOURCE_EXHAUSTED / رسالة تفيد ببلوغ حد المعدل. لقد تجاوزت quota الخاصة بمستوى المصادقة المستخدم. انتظر حتى تُعاد تهيئة النافذة، أو أبطئ agent، أو انتقل إلى API key مدفوعة. إذا علق agent في حلقة إعادة المحاولة، فأوقفه وتحقّق مما ينفذه.
FAQ
كيف أوثّق Gemini CLI على خادم بلا واجهة رسومية؟
استخدم مفتاح API مدفوعاً، وليس تسجيل الدخول عبر المتصفح. أنشئ مفتاحاً في Google AI Studio ضمن مشروع تتم فوترته، وضعه في ملف بصلاحيات mode-600 يحمّله shell الخاص بك (export GEMINI_API_KEY=...)، وسيتجاوز CLI تدفق OAuth عبر المتصفح بالكامل. إذا سجّلت الدخول باستخدام Google بدلاً من ذلك، على سبيل المثال بترخيص Code Assist Standard أو Enterprise، فسيطبع CLI على خادم بلا واجهة رسومية عنوان URL؛ افتحه على حاسوبك المحمول، ووافق، ثم الصق الرمز الذي يعرضه Google عند مطالبة Enter the authorization code:. لا يوجد منفذ يجب تثبيته ولا نفق، لكن يلزم أن تكون حاضراً أمام متصفح، ولذلك لا يصلح للبرامج النصية. لم تعد الحسابات الشخصية المجانية مدعومة من Gemini CLI منذ June 18, 2026.
لماذا يطلب التثبيت العام لـ 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 البرمجية، ولذلك يحتاج إلى المنفذ الصادر 443، لكنه لا يحتاج إلى أي منافذ واردة. كما أن تسجيل الدخول إلى Google على خادم بلا واجهة رسومية لا يحتاج إلى منفذ: إذ تلصق الرمز مرة أخرى في الطرفية بدلاً من تلقي callback على الخادم. أبقِ الاتصالات الواردة محظورة.