أداة Gemini CLI مفتوحة المصدر من Google—وهي وكيل ذكاء اصطناعي يعتمد على الطرفية يجلب Gemini إلى بيئة الـ shell—تطورت بسرعة منذ الإطلاق وتدعم الآن تهيئة غنية، وملفات سياق المشروع (GEMINI.md / .gemini)، وأوامر سلاش مخصصة، والتحكم في أدلة مساحة العمل. المشروع يتطور بنشاط على GitHub (المستودع الرسمي)، وقد دخل مرحلة المعاينة العامة بحصص سخية، ويجري دمجه في أدوات مطورين أخرى (تكاملات المحرر وCI/Actions). لكن مع توسع الفرق، أو عند العمل عبر محركات أقراص أو بيئات مقيّدة (حاويات، حواسيب محمولة مُدارة من الشركة، Cloud Shell، أنظمة Windows)، ستصطدم سريعاً بسؤال عملي: أين يخزن Gemini ملفاته، وكيف يمكنك تغيير الأدلة التي يقرأ ويكتب فيها Gemini؟
ما هو Gemini CLI؟
Gemini CLI هو وكيل ذكاء اصطناعي مفتوح المصدر من Google يعمل عبر سطر الأوامر، ويجلب قوة نماذج Gemini مباشرة إلى طرفيتك. يوفر قدرات وكيل تفاعلي لمساعدة في الشيفرة، وفحص الملفات والمشاريع، وتنفيذ أوامر الـ shell (مع ضوابط أمان)، ودمج أدوات مثل Google Search، وModel Context Protocol (MCP)، وأدوات توليد الوسائط المرفقة مع Gemini. صُمّم الـ CLI ليكون خفيف الوزن، قابلاً للبرمجة النصية، وقابلاً للتوسعة؛ وهو متاح من المستودع الرسمي ومُعبّأ لسهولة التثبيت.
لماذا يهم الدليل
يحفظ Gemini CLI التهيئة (على سبيل المثال، settings.json)، ومطالبات النظام أو السياق (GEMINI.md)، وبيانات الاعتماد المخزّنة مؤقتاً، ومعرّفات القياس عن بُعد، وحالات أخرى دائمة داخل دليل .gemini. موقع هذا الدليل يحدد:
- أي إعدادات يقوم الـ CLI بتحميلها (عالمية مقابل خاصة بالمشروع)،
- ما هي ملفات “الذاكرة” التي سيقرأها الوكيل،
- أين تُخزَّن بيانات الاعتماد مؤقتاً (يؤثر على سلوك تسجيل الدخول)،
- قابلية إعادة الإنتاج عبر الأجهزة أو CI عندما تريد توفير مستودع تهيئة مخصص.
فهم الدليل (وتغييره عند الضرورة) يساعد في سير عمل متعدد المشاريع، وCI، وعمليات نشر بالحاويات، والفرق ذات مخازن تهيئة مركزية.
أين يخزن Gemini CLI الإعدادات افتراضياً؟
افتراضياً يستخدم الـ CLI دليلاً باسم .gemini. في معظم عمليات تثبيت المستخدمين، يُحلّ هذا إلى ~/.gemini (مجلد .gemini في دليل المنزل). يدعم الـ CLI أيضاً ملفات .gemini على مستوى المشروع (مثل .gemini/settings.json في جذر المشروع) والتي تتجاوز إعدادات المستخدم أثناء العمل من ذلك مجلد المشروع. تُقرأ إعدادات النظام من مواقع خاصة بنظام التشغيل (على سبيل المثال /etc/ على Linux أو %PROGRAMDATA% على Windows) عند الاقتضاء. مسارات نموذجية:
- Linux / macOS:
~/.gemini/(مثل/home/alice/.geminiأو/Users/alice/.gemini). - Windows:
%USERPROFILE%\.gemini(مثلC:\Users\Alice\.gemini).
داخل.geminiستجد غالباًsettings.json، وGEMINI.md، وcommands/، وذاكرات محلية مؤقتة. يقرأ الـ CLI أيضاً مجلدات.gemini/الخاصة بكل مشروع (جذر المشروع) للحصول على إعدادات على مستوى المشروع.
كيف يمكنني تغيير أو إعادة توجيه دليل تهيئة Gemini CLI؟
هناك عدة طرق عملية — من الأبسط (العمل في المجلد المرغوب) إلى الأكثر متانة (متغيرات البيئة أو عمليات إعادة توجيه نظام الملفات). اختر أسلوباً بناءً على ما إذا كنت تتحكم في بيئة التشغيل (جهاز تطوير محلي مقابل CI)، وعلى نظام التشغيل الذي تستخدمه، وعلى ما إذا كنت تفضّل تغييراً مؤقتاً أو دائماً.
1) استخدام دليل .gemini على مستوى المشروع (موصى به لإعدادات كل مشروع)
إذا كنت تريد إعدادات لكل مشروع، أنشئ دليلاً فرعياً باسم .gemini في جذر مشروعك وضع settings.json وGEMINI.md وملفات المشروع الأخرى هناك. يفضل Gemini CLI إعدادات المشروع عندما تشغله من دليل ذلك المشروع:
your-project/├─ .gemini/│ ├─ settings.json│ └─ GEMINI.md└─ src/
ابدأ gemini بينما موقع الـ shell لديك هو your-project/ وسيقوم الـ CLI بالتقاط ملفات .gemini من تلك الشجرة (يبحث صعوداً للعثور على سياق المشروع). هذا هو الأسلوب الأكثر أماناً وصراحة لإعدادات كل مشروع.
2) استخدام متغيرات البيئة الموثّقة (عند الدعم)
يشير كود ومراجع Gemini CLI إلى عدة متغيرات بيئة تُستخدم لتغيير السلوك. بعضها مخصص لإعدادات النظام أو تجاوزات ملفات خاصة:
GEMINI_API_KEYوGEMINI_MODELوغيرها تُستخدم عادةً للمصادقة واختيار النموذج.- هناك إشارات في الكود والوثائق إلى متغيرات مثل
GEMINI_CLI_SYSTEM_SETTINGS_PATH(يُستخدم لتجاوز مسار إعدادات النظام) وثوابت مثلGEMINI_CONFIG_DIR(اسم.geminiالافتراضي المستخدم في الكود). تقترح بعض طلبات المجتمع وطلبات الدمج إضافة أو احترام متغير بيئةGEMINI_CONFIG_DIRللسماح للمستخدمين بنقل دليل التهيئة بالكامل.
مثال (bash / macOS / Linux):
# Temporary for this shell sessionexport GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"# Or override system settings path if your install supports it:export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"# Then rungemini
PowerShell (Windows):
$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'gemini
تنبيه مهم: وفقاً لأحدث مناقشات المجتمع والقضايا، تم طلب
GEMINI_CONFIG_DIRوالإشارة إليه في الكود في بعض الأماكن — لكن أُبلغ عن أخطاء خاصة بالمنصات وسلوك غير متسق (لا سيما على Windows). وهذا يعني أن إعادة التوجيه عبر متغيرات البيئة قد لا تكون موثوقة بشكل موحّد على كل منصة أو إصدار. تحقق من ملاحظات الإصدار وقضايا المستودع لإصدار الـ Gemini CLI المثبت لديك إذا كنت تعتمد على ذلك.
3) إضافة أدلة إلى مساحة عمل Gemini داخل الجلسة
إذا كنت تريد أن يكون Gemini على علم بأدلة إضافية (حتى يتمكن من قراءة الملفات كسياق)، فهناك مجموعة أوامر تفاعلية باسم /directory. على سبيل المثال:
/directory add path/to/another/project/directory list
هذا لا ينقل دليل التهيئة، لكنه يسمح للوكيل بإدراج ملفات من أدلة أخرى في سياق مساحة العمل. هذا مفيد عندما تريد أن يشير الوكيل إلى مستودعات أخرى دون تغيير تهيئتك العالمية.
4) إنشاء رابط رمزي أو ربط لنظام الملفات (حل عملي)
إذا رفض الـ CLI قبول تجاوزات البيئة أو كنت تحتاج إلى حل موثوق عبر العمليات، استخدم إعادة توجيه لنظام الملفات:
على Unix/macOS:
# move the original config foldermv ~/.gemini ~/gemini_backup# create a symlink to your desired locationln -s /path/to/central/gemini-config ~/.gemini
على Windows (موجه PowerShell بامتيازات إدارية):
# Move the original directoryMove-Item -Path $env:USERPROFILE\.gemini -Destination C:\GeminiConfigBackup# Create a junction (administrator)New-Item -ItemType Junction -Path $env:USERPROFILE\.gemini -Target C:\CentralGeminiConfig
هذا الأسلوب يُجبر الـ CLI على القراءة من موقعك المرغوب دون الحاجة إلى دعم أصيل في الـ CLI. ملاحظة: الروابط الرمزية/الوصلات تتطلب صلاحيات نظام ملفات مناسبة وقد تتصرف بشكل مختلف في بيئات الحاويات أو Windows. استخدمها بحذر. (انظر “ملاحظات محددة لـ Windows” أدناه.)
5) تغيير دليل المنزل الفعّال للعملية (خدعة للحاويات/CI)
عند التشغيل في CI أو الحاويات أو البيئات المؤقتة، يمكنك تغيير $HOME (في Unix) أو %USERPROFILE% (في Windows) لعملية gemini بحيث يُحلّ ~/.gemini إلى مسار تتحكم به:
# Run gemini with a custom HOME (bash)HOME=/ci/workspace/you gemini --some-command# Or in a container DockerfileENV HOME=/app/userRUN mkdir -p /app/user/.geminiCOPY config /app/user/.gemini
هذا مفيد لقابلية إعادة الإنتاج في CI، لكن انتبه: تغيير HOME قد يؤثر على أدوات أخرى وتدفقات المصادقة (مثل مخازن Google OAuth المؤقتة)، لذا حدد هذه التقنية ضمن حاويات معزولة أو أغلفة على مستوى العملية.
كيف يمكنني تثبيت واستخدام Gemini CLI عبر CometAPI؟
الإجابة المختصرة: لديك مساران عمليان — (أ) استدعاء نماذج Gemini مباشرة عبر CometAPI (موصى به وهو الأبسط)، أو (ب) جعل Gemini CLI الرسمي يتحدث إلى CometAPI إمّا باستخدام إصدار من Gemini-CLI يدعم عنوان URL أساسي مخصص (تضيف بعض الإصدارات/طلبات الدمج ذلك)، أو بتشغيل وكيل محلي صغير يترجم طلبات Gemini-CLI إلى استدعاءات بأسلوب CometAPI/OpenAI.
ما هو CometAPI؟
CometAPI هو بوابة/تجميع واجهات برمجة تطبيقات تعرض مئات النماذج من جهات خارجية (بما فيها عائلة Gemini من Google) خلف واجهة HTTP بأسلوب OpenAI. تقوم بالتسجيل، وتحصل على مفتاح حامل، ثم تستدعي نقاط النهاية مثل https://api.cometapi.com/v1/chat/completions . يستخدم CometAPI رموز الحامل القياسية في ترويسة Authorization.
لماذا تستخدم CometAPI؟ يقدم تسعيراً أقل من الواجهة الرسمية لتسهيل الدمج. دليل تثبيت واستخدام Gemini CLI:
كيف يمكنني استدعاء نماذج Gemini مباشرة عبر CometAPI؟ (موصى به)
إذا كان هدفك ببساطة استخدام نماذج Gemini ولا تحتاج ميزات Gemini CLI بشكل صارم، فإن الاستدعاء المباشر لـ CometAPI مباشر وموثوق.
export COMET_KEY="sk-xxxx"curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \ -H "Authorization: Bearer $COMET_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-2.5-pro", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the 3 key benefits of unit tests."} ], "max_tokens": 300 }' | jq .
تتيح لك هذه الاستدعاءات المباشرة دمج CometAPI في السكربتات أو التطبيقات أو CI دون الاعتماد على Gemini CLI.
هل يمكنني جعل Gemini CLI يستخدم CometAPI؟
تضيف بعض إصدارات/طلبات دمج Gemini CLI متغيرات بيئة لتجاوز عنوان URL الأساسي لواجهة Gemini. إذا كان الإصدار المثبت لديك يدعم ضبط عنوان URL أساسي مخصص لواجهة Gemini + استخدام مفتاح CometAPI، يمكنك توجيهه إلى CometAPI وضبط مفتاح CometAPI كـ GEMINI_API_KEY (يتوقع الـ CLI متغيراً باسم GEMINI_API_KEY لمصادقة مفتاح واجهة Gemini).
مثال:
# example env — *check your gemini-cli docs for exact var names*export GEMINI_API_KEY="sk-xxxxx" # CometAPI keyexport GOOGLE_GEMINI_BASE_URL="https://api.cometapi.com/v1" # if supportedgemini # run the CLI; it will use the configured base URL
استكشاف الأخطاء وإصلاحها: مشكلات شائعة وحلول
المشكلة: لا يستطيع Gemini رؤية ملفات في مستودع آخر
- جرّب
gemini --include-directories /path/to/repoعند البدء. أو داخل الجلسة:/directory add /path/to/repo. - إذا كان المستودع على تركيب شبكي، تحقق من الأذون وأن مستخدم عملية الـ CLI يستطيع قراءة الملفات.
- إذا استخدمت رابطاً رمزياً لنقل
.gemini، تحقق من أن الـ CLI يتبع الرابط لـGEMINI.mdوsettings.json(بعض الإصدارات لا تتبع بعض الروابط الرمزية لأسباب أمنية).
المشكلة: يفشل gemini في إنشاء ~/.gemini على Windows (EPERM)
هذا يعني عادة أن عمليتك لا تمتلك إذناً للكتابة إلى %USERPROFILE%. حلول:
- شغّل الطرفية كمسؤول أو عدّل أذون المجلدات.
- اضبط موقع تهيئة مخصص عبر رابط رمزي أو، عند الدعم، عبر متغير بيئة (ترقب دعم
GEMINI_CONFIG_DIRمستقبلاً).
المشكلة: لا يغيّر cd دليل العمل داخل وضع الـ shell
هذه مشكلة معترف بها على بعض المنصات. الموصى به: انتقل إلى تنفيذ أوامر الـ shell من خارج عملية Gemini CLI أو أضف أدلة عبر /directory add.
المشكلة: أسماء نماذج CometAPI لا تطابق ما تتوقعه
استدعِ نقطة النهاية /v1/models وتفحّص JSON. غالباً ما تحتوي معرفات النماذج على سلاسل متغيرات دقيقة (مثل gemini-2.5-flash-preview-04-17). استخدم السلسلة الدقيقة في طلبك.
الخلاصة
تصميم Gemini CLI الافتراضي يفضّل سلوكاً معقولاً وسهل الاكتشاف: ~/.gemini عالمي لإعدادات المستخدم الافتراضية و.gemini خاص بالمشروع لتجاوزات كل مستودع. يدفع المجتمع نحو مزيد من القابلية للتكوين الأصلية (متغيرات بيئة صريحة أو أعلام) لجعل الأداة أكثر وداً لبيئات متعددة المستخدمين، بالحاويات، وبالمؤسسات.
كيفية تغيير دليل Gemini CLI:
نظرة عامة: يخزن Gemini CLI التهيئة والملفات السياقية على مستوى المستخدم في دليل .gemini (عادةً ~/.gemini). يمكنك التأثير على الدليل الذي يستخدمه الـ CLI عبر (1) الاعتماد على .gemini على مستوى المشروع في دليل العمل الحالي، (2) استخدام متغيرات البيئة أو خيارات الـ CLI عند الدعم، (3) إضافة أدلة مساحة العمل داخل جلسة تفاعلية، أو (4) استخدام تقنيات نظام الملفات (روابط رمزية، وصلات bind، أو تغيير متغيرات المنزل/الملف الشخصي) عندما تكون الخيارات الأصلية مفقودة.
للبدء، استكشف قدرات نماذج Gemini (مثل Gemini 3 Pro) في Playground وراجع دليل الواجهة للحصول على تعليمات مفصلة. قبل الوصول، تأكد من أنك قمت بتسجيل الدخول إلى CometAPI وحصلت على مفتاح الـ API. يقدم CometAPI سعراً أقل بكثير من السعر الرسمي لمساعدتك على الدمج.
هل أنت جاهز؟→ تجربة مجانية لنماذج Gemini !
