# راهنمای یکپارچه‌سازی Gemini CLI

> **⚠️ در حال حاضر در دسترس نیست**: QCode همه مدل‌های Gemini را به‌طور موقت از دسترس خارج کرده است، بنابراین مراحل زیر برای فراخوانی Gemini از طریق QCode فعلاً قابل استفاده نیستند و فقط برای مرجع نگه داشته شده‌اند؛ لطفاً به‌جای آن از Claude، GPT یا مدل‌های چینی استفاده کنید.

> **آخرین بررسی**: 2026-09-18 · 📄 طبق مستندات رسمی (Gemini CLI v0.60.0 (2026-09-15؛ سرویس‌دهی به سطح‌های Pro/مصرف‌کننده از 2026-06-18 متوقف شد، کلیدهای پرداختی سازمانی ادامه دارند))

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Gemini (فعلاً توسط QCode ارائه نمی‌شود؛ فقط برای مرجع) · Claude ❌ · GPT ❌ · مدل‌های چینی ❌ |
| پروتکل و Base URL | Gemini: `https://api.qcode.cc/gemini` (خود CLI مسیر `/v1beta/...` را اضافه می‌کند — آن را به‌صورت دستی اضافه نکنید) |
| محل پیکربندی | `~/.gemini/settings.json` یا متغیر محیطی `GOOGLE_GEMINI_BASE_URL` + `GEMINI_API_KEY` |
| مستندات رسمی | [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) |

> **⚠️ تغییر مهم: مسیر ورود مصرف‌کننده با Google Antigravity CLI جایگزین شد**. پست رسمی 2026-05-19 به‌صورت نقل‌قول مستقیم بیان می‌کند که از **2026-06-18**، Gemini CLI و افزونه‌های IDE مربوط به Gemini Code Assist «سرویس‌دهی به درخواست‌ها را متوقف خواهند کرد» — برای **Google AI Pro و Ultra**، و برای افرادی که از آن به‌صورت رایگان با حساب کاربری شخصی استفاده می‌کنند. آنچه در آن روز در دسترس قرار گرفت **Antigravity CLI و Antigravity 2.0** بود (خود IDE Antigravity زودتر، در 2025-11-18، عرضه شده بود). سازمانی وضعیت متفاوتی دارد: سازمان‌هایی که مجوز Gemini Code Assist Standard یا Enterprise دارند دسترسی خود را حفظ می‌کنند، و همان پست می‌گوید «Gemini CLI از طریق کلیدهای API پرداختی Gemini و Gemini Enterprise Agent Platform در دسترس باقی خواهد ماند». **بنابراین این صفحه همچنان برای کلیدهای پرداختی سازمانی معتبر است**؛ کاربران Pro / Ultra / رایگان باید به [Google Antigravity CLI](/docs/ide/antigravity) مهاجرت کنند.
>
> مخزن بدون نگهداری نیست: در روز این بررسی (2026-09-18) هنوز یک بیلد شبانه منتشر می‌کرد، و آخرین انتشار پایدار v0.60.0 (2026-09-15) است. عبارت دقیق «**سرویس‌دهی به ورودهای مصرف‌کننده را متوقف کرد**» است، نه «نگهداری آن متوقف شد».


QCode.cc از Claude Code و OpenAI Codex پشتیبانی می‌کند که می‌توانند از همان کلید استفاده کنند. مراحل راه‌اندازی Gemini CLI در ادامه فقط برای مرجع نگه داشته شده‌اند، اما QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد.
## Gemini CLI چیست

[Gemini CLI](https://geminicli.com/) دستیار برنامه‌نویسی هوش مصنوعی خط فرمان Google است، مشابه Claude Code، که در توسعه کد، اشکال‌زدایی و عملیات فایل در ترمینال به شما کمک می‌کند.

## مدل‌های موجود

QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد. پرس‌وجوی زیر نشان می‌دهد که پس از ارائه دوباره آن‌ها، چگونه آن‌ها را فهرست کنید (فقط برای مرجع):

**پرس‌وجوی زنده را مرجع بدانید** — فهرست ثابتی را از هیچ سند، از جمله همین سند، کپی نکنید:

```bash
curl -s https://api.qcode.cc/gemini/v1beta/models \
  -H "x-goog-api-key: cr_your_qcode_key"
```

شناسه‌هایی که برگردند، مدل‌های Gemini قابل فراخوانی هستند؛ یکی را در `GEMINI_MODEL` قرار دهید.
کاتالوگ کامل و قیمت‌های زنده در [qcode.cc/models](https://qcode.cc/models) قرار دارند.

> **یادداشت نسخه**: از 2026-06-18، Gemini CLI دیگر به حساب‌های شخصی Pro / Ultra / رایگان سرویس‌دهی نمی‌کند — به [Google Antigravity CLI](https://antigravity.google/) مهاجرت کنید (Antigravity CLI و Antigravity 2.0 در 2026-05-19 در دسترس شدند)؛ کلیدهای پرداختی سازمانی تحت تأثیر نیستند و می‌توانند همچنان از Gemini CLI استفاده کنند.

## نمای کلی پیکربندی

Gemini CLI به متغیرهای محیطی زیر نیاز دارد:

- `GOOGLE_GEMINI_BASE_URL` - نقطه پایانی سرویس

- `GEMINI_API_KEY` - کلید API (همانند Claude Code)

- `GEMINI_MODEL` - انتخاب مدل
فایل تنظیمات، مسیر رسمی پشتیبانی‌شده دیگر است: `~/.gemini/settings.json` در سطح کاربر، `.gemini/settings.json` در سطح پروژه (پروژه بر کاربر اولویت دارد). مدل `model.name` است، نوع احراز هویت `security.auth.selectedType` است؛ مقادیر رشته‌ای در آن فایل‌ها می‌توانند با `$VAR`، `${VAR}` یا `${VAR:-default}` به متغیرهای محیطی ارجاع دهند. مستندات بیان می‌کند که `GOOGLE_GEMINI_BASE_URL` برای احراز هویت gemini-api-key اعمال می‌شود، بنابراین هر دو متغیر را مطابق زیر تنظیم کنید.


<div data-os="macos" markdown="1">

## پیکربندی macOS

### گام 1: نصب Node.js

Gemini CLI برای اجرا به Node.js نیاز دارد.

#### روش 1: استفاده از Homebrew (توصیه‌شده)

اگر Homebrew را نصب کرده‌اید، از آن برای نصب Node.js استفاده کنید:

```bash
# Update Homebrew
brew update

# Install Node.js
brew install node
```

#### روش 2: دانلود رسمی

1. به [https://nodejs.org/](https://nodejs.org/) مراجعه کنید

2. نسخه LTS را برای macOS دانلود کنید

3. فایل `.pkg` دانلودشده را باز کنید

4. دستورالعمل‌های نصب‌کننده را برای تکمیل نصب دنبال کنید

#### یادداشت‌های macOS

- ممکن است در صورت بروز مشکلات مجوز، نیاز به استفاده از `sudo` داشته باشید

- اجرای اول ممکن است به تأیید در تنظیمات سیستم نیاز داشته باشد

- استفاده از Terminal یا iTerm2 توصیه می‌شود

#### تأیید نصب Node.js

پس از نصب، Terminal را باز کنید و اجرا کنید:

```bash
node --version
npm --version
```

اگر شماره‌های نسخه نمایش داده شوند، نصب موفق بوده است!

### گام 2: نصب Gemini CLI

Gemini CLI را به‌صورت سراسری با npm نصب کنید:

```bash
npm install -g @google/gemini-cli
```

پس از نصب، تأیید کنید:

```bash
gemini --version
```

### گام 3: پیکربندی متغیرهای محیطی Gemini CLI

متغیرهای محیطی زیر را برای اتصال به سرویس پراکسی تنظیم کنید:

#### راه‌اندازی موقت (نشست جاری)

دستورهای زیر را در Terminal اجرا کنید:

```bash
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

> `cr_xxxxxxxxxx` را با [کلید API QCode.cc](https://qcode.cc/dashboard) خود جایگزین کنید. از همان کلید API که برای Claude Code استفاده می‌کنید استفاده کنید.

#### راه‌اندازی دائمی (پیکربندی شل)

موارد زیر را به فایل پیکربندی شل خود (`~/.zshrc`) اضافه کنید:

```bash
# Gemini CLI Configuration
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

سپس اجرا کنید:

```bash
source ~/.zshrc
```

### تأیید متغیرهای محیطی Gemini CLI

در Terminal تأیید کنید:

```bash
echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL
```

</div>

<div data-os="linux" markdown="1">
## پیکربندی Linux / WSL2

### مرحله 1: نصب Node.js

Gemini CLI برای اجرا به Node.js نیاز دارد.

#### روش 1: استفاده از nvm (توصیه‌شده)

nvm مدیریت چندین نسخه Node.js را آسان می‌کند:

```bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# Install latest LTS version
nvm install --lts
```

#### روش 2: استفاده از مدیر بسته

```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora
sudo dnf install nodejs

# Arch Linux
sudo pacman -S nodejs npm
```

#### نکات Linux / WSL2

- کاربران WSL2 باید در زیرسیستم Linux نصب کنند، نه Windows

- استفاده از nvm به جلوگیری از مشکلات مجوز کمک می‌کند

- اطمینان حاصل کنید که فایل پیکربندی شل، nvm را به‌درستی بارگذاری می‌کند

#### بررسی نصب Node.js

پس از نصب، ترمینال را باز کنید و اجرا کنید:

```bash
node --version
npm --version
```

اگر شماره نسخه‌ها نمایش داده شد، نصب موفقیت‌آمیز بوده است!

### مرحله 2: نصب Gemini CLI

Gemini CLI را به‌صورت سراسری با npm نصب کنید:

```bash
npm install -g @google/gemini-cli
```

پس از نصب، بررسی کنید:

```bash
gemini --version
```

### مرحله 3: پیکربندی متغیرهای محیطی Gemini CLI

متغیرهای محیطی زیر را برای اتصال به سرویس پروکسی تنظیم کنید:

#### راه‌اندازی موقت (نشست فعلی)

دستورهای زیر را در ترمینال اجرا کنید:

```bash
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

> `cr_xxxxxxxxxx` را با [کلید API QCode.cc](https://qcode.cc/dashboard) خود جایگزین کنید. از همان کلید API که Claude Code استفاده می‌کند استفاده کنید.

#### راه‌اندازی دائمی (پیکربندی شل)

موارد زیر را به فایل پیکربندی شل خود (`~/.bashrc`) اضافه کنید:

```bash
# Gemini CLI Configuration
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
export GEMINI_API_KEY="cr_xxxxxxxxxx"
export GEMINI_MODEL="gemini-2.5-pro"
```

سپس اجرا کنید:

```bash
source ~/.bashrc
```

اگر از Zsh استفاده می‌کنید، آن را به `~/.zshrc` اضافه کنید و `source ~/.zshrc` را اجرا کنید.

### بررسی متغیرهای محیطی Gemini CLI

در ترمینال بررسی کنید:

```bash
echo $GOOGLE_GEMINI_BASE_URL
echo $GEMINI_API_KEY
echo $GEMINI_MODEL
```

</div>

<div data-os="windows" markdown="1">

## پیکربندی Windows

### مرحله 1: نصب Node.js

Gemini CLI برای اجرا به Node.js نیاز دارد.

#### روش 1: دانلود رسمی (توصیه‌شده)

1. مرورگر خود را باز کنید و به [https://nodejs.org/](https://nodejs.org/) بروید

2. روی نسخه «LTS» برای دانلود کلیک کنید (برای پایداری توصیه می‌شود)

3. روی فایل `.msi` دانلودشده دوبار کلیک کنید

4. از ویزارد نصب پیروی کنید و تنظیمات پیش‌فرض را حفظ کنید

#### روش 2: استفاده از مدیر بسته

اگر Chocolatey یا Scoop را نصب کرده‌اید، از خط فرمان استفاده کنید:

```powershell
# Using Chocolatey
choco install nodejs

# Or using Scoop
scoop install nodejs
```

#### نکات Windows

- استفاده از PowerShell به‌جای CMD توصیه می‌شود

- اگر با مشکلات مجوز مواجه شدید، با دسترسی Administrator اجرا کنید

- برخی نرم‌افزارهای آنتی‌ویروس ممکن است آن را علامت‌گذاری کنند؛ در صورت نیاز آن را به فهرست سفید اضافه کنید

#### بررسی نصب Node.js

پس از نصب، PowerShell یا CMD را باز کنید و اجرا کنید:

```powershell
node --version
npm --version
```

اگر شماره نسخه‌ها نمایش داده شد، نصب موفقیت‌آمیز بوده است!

### مرحله 2: نصب Gemini CLI

Gemini CLI را به‌صورت سراسری با npm نصب کنید:

```powershell
npm install -g @google/gemini-cli
```

پس از نصب، بررسی کنید:

```powershell
gemini --version
```

### مرحله 3: پیکربندی متغیرهای محیطی Gemini CLI

متغیرهای محیطی زیر را برای اتصال به سرویس پروکسی تنظیم کنید:

#### راه‌اندازی موقت PowerShell (نشست فعلی)

دستورهای زیر را در PowerShell اجرا کنید:

```powershell
$env:GOOGLE_GEMINI_BASE_URL = "https://api.qcode.cc/gemini"
$env:GEMINI_API_KEY = "cr_xxxxxxxxxx"
$env:GEMINI_MODEL = "gemini-2.5-pro"
```

> `cr_xxxxxxxxxx` را با [کلید API QCode.cc](https://qcode.cc/dashboard) خود جایگزین کنید. از همان کلید API که Claude Code استفاده می‌کند استفاده کنید.

#### راه‌اندازی دائمی PowerShell (سطح کاربر)

دستورهای زیر را در PowerShell اجرا کنید:

```powershell
# Set user-level environment variables (permanent)
[System.Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "https://api.qcode.cc/gemini", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("GEMINI_MODEL", "gemini-2.5-pro", [System.EnvironmentVariableTarget]::User)
```

> برای اعمال تغییرات باید PowerShell را دوباره باز کنید.

### بررسی متغیرهای محیطی Gemini CLI

در PowerShell بررسی کنید:

```powershell
echo $env:GOOGLE_GEMINI_BASE_URL
echo $env:GEMINI_API_KEY
echo $env:GEMINI_MODEL
```

</div>
## عیب‌یابی

### نسخه Node.js بیش از حد قدیمی است

**مشکل**: Gemini CLI ناسازگاری نسخه Node.js را گزارش می‌کند

**راه‌حل**:

1. نسخه Node.js را بررسی کنید: `node --version`

2. الزام رسمی، Node.js **20.0.0 یا بالاتر** است (`engines.node >=20.0.0`)؛ ماندن روی 18 بلافاصله پس از نصب شکست می‌خورد

3. با nvm ارتقا دهید: `nvm install --lts && nvm use --lts`

### اعمال نشدن متغیرهای محیطی

**مشکل**: پس از تنظیم متغیرهای محیطی نمی‌توانید متصل شوید

**راه‌حل**:

1. مطمئن شوید ترمینال را دوباره باز کرده‌اید یا دستور `source` را اجرا کرده‌اید

2. بررسی کنید نام متغیرها صحیح باشند (به بزرگی و کوچکی حروف حساس است)

3. اطمینان حاصل کنید قالب کلید API درست است (با `cr_` شروع می‌شود)

### مشکلات اتصال شبکه

**مشکل**: نمی‌توانید به سرویس QCode.cc متصل شوید

**راه‌حل**:

1. اتصال شبکه را بررسی کنید

2. اطمینان حاصل کنید `GOOGLE_GEMINI_BASE_URL` درست تنظیم شده است

3. نقاط دسترسی دیگر را امتحان کنید:
   - آسیا: `https://asia.qcode.cc/gemini`

## مستندات مرتبط

- [Antigravity CLI](/docs/ide/antigravity) - جانشین رسمی Gemini CLI
- [پیکربندی محیط](/docs/getting-started/environment) - راه‌اندازی Claude Code

- [یکپارچه‌سازی Codex](/docs/ide/codex) - پیکربندی OpenAI Codex CLI

- [شروع سریع](/docs/getting-started/quick-start) - شروع کار با Claude Code