# راه‌اندازی Google Antigravity CLI

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

> **آخرین بازبینی**: 2026-09-18 · 📄 بر اساس مستندات رسمی (Antigravity CLI 1.2.x (مانیفست به‌روزرسان خودکار 1.2.6، بررسی‌شده در 2026-09))

## نگاه اجمالی

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

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

[Google Antigravity](https://antigravity.google/) جانشین Gemini CLI از سوی Google برای ورودهای
کاربران عادی است. این ابزار
در قالب سه بخش عرضه می‌شود: یک IDE دسکتاپ، **Antigravity CLI (`agy`، نوشته‌شده به Go)**، و یک SDK.
این صفحه فقط CLI را پوشش می‌دهد: اتصال آن به **QCode.cc**.
## 🔴 ابتدا این را بخوانید: فقط پروتکل Gemini

نقطه پایانی سفارشی Antigravity CLI **سازگار با Gemini** است و از طریق متغیر محیطی
`GOOGLE_GEMINI_BASE_URL` تنظیم می‌شود. جدول عیب‌یابی رسمی عیناً می‌گوید که
`gemini` «تنها مقدار پذیرفته‌شده» برای `modelProvider` است — بنابراین این مسیر **نمی‌تواند
نقطه پایانی سازگار با OpenAI را بپذیرد** و از طریق QCode فقط می‌تواند مدل‌های خانواده Gemini را ارائه دهد.

| مورد | مقدار |
|---|---|
| فایل پیکربندی | `~/.gemini/antigravity-cli/settings.json` |
| فیلد کلید | `"modelProvider": "gemini"` |
| اعتبارنامه | متغیر محیطی `GEMINI_API_KEY` (کلید `cr_` QCode شما) |
| بازنویسی نقطه پایانی | متغیر محیطی `GOOGLE_GEMINI_BASE_URL` |
| متغیرهایی که نادیده می‌گیرد | مستندات رسمی می‌گوید: agy **فایل‌های `.env` را بارگذاری نمی‌کند** و `GOOGLE_API_KEY` تأثیری ندارد — اعتبارنامه فقط از `GEMINI_API_KEY` در محیط خوانده می‌شود. Gemini CLI فایل `.env` را بارگذاری می‌کند، بنابراین رفتار این دو متضاد است؛ کاربران CI یک بار به این موضوع برمی‌خورند و هرگز فراموش نمی‌کنند |
| مدل‌های قابل استفاده | از طریق QCode: فقط خانواده Gemini |

> برای Claude یا GPT، از کلاینت دیگری استفاده کنید — [Claude Code](/docs/getting-started/installation)،
> [Codex CLI](/docs/ide/codex)، [Cline](/docs/ide/cline)، [Zed](/docs/ide/zed).
> اینکه کدام پروتکل کدام مدل‌ها را ارائه می‌دهد در
> [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) مستند شده است.

## 🔴 Antigravity IDE (اپلیکیشن دسکتاپ 2.0) قابل اتصال نیست

Antigravity **IDE دسکتاپ در حال حاضر هیچ قلاب رسمی BYOK یا قلاب ارائه‌دهنده سفارشی ندارد**، بنابراین مدل عامل داخلی آن را نمی‌توان با یک نقطه پایانی شخص ثالث جایگزین کرد. پروژه‌های جامعه این را با یک پراکسی رهگیری محلی دور می‌زنند، اما آن مسیری مهندسی‌معکوس‌شده و بدون پشتیبانی رسمی است و این صفحه آن را توصیه نمی‌کند.

**مؤلفه‌ای که به QCode متصل می‌شود CLI (`agy`) است، نه IDE.**

## پیش‌نیازها

- یک کلید API QCode.cc (با `cr_` شروع می‌شود)، از [کنسول](https://qcode.cc/dashboard)
- آشنایی با [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths)

## گام 1: نصب Antigravity CLI

به [مستندات نصب رسمی](https://antigravity.google/docs/cli/install) مراجعه کنید:

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

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
# installs to ~/.local/bin/agy
```

</div>

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

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
# installs to ~/.local/bin/agy
```

</div>

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

PowerShell:

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
# installs to C:\Users\<username>\AppData\Local\agy\bin
```

CMD:

```bat
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```

</div>

صفحه نصب رسمی از `--skip-aliases` و `--skip-path` نام می‌برد، اما این رفتار **Windows** است: `install.ps1` / `install.cmd` آرگومان‌ها را به `agy install` منتقل می‌کنند، در حالی که `install.sh` روی macOS / Linux فقط `-d, --dir <path>` و `-h, --help` را می‌پذیرد و با هر چیز دیگری خارج می‌شود. این دو گزینه را روی macOS / Linux کپی نکنید.
## گام 2: تغییر به احراز هویت با کلید API (رد کردن ورود با Google)

به‌طور پیش‌فرض `agy` کلیدخانه سیستم‌عامل شما را می‌خواند یا برای ورود با حساب کاربری Google مرورگری باز می‌کند. برای استفاده از کلید API به‌جای آن، فایل `~/.gemini/antigravity-cli/settings.json` را ویرایش کنید (یا بسازید):

```json
{
  "modelProvider": "gemini"
}
```

با این تنظیم، `agy` **صفحه ورود را رد می‌کند** و مستقیماً رابط اصلی را باز می‌کند و در عوض متغیر محیطی `GEMINI_API_KEY` را می‌خواند.

> 🔴 اگر `"modelProvider": "gemini"` تنظیم شده باشد اما `GEMINI_API_KEY` وجود نداشته باشد، **CLI شروع نمی‌شود**. هر دو با هم لازم‌اند.

## گام 3: کلید و نقطه پایانی را روی QCode تنظیم کنید

```bash
export GEMINI_API_KEY="cr_your_qcode_key"
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
```

برای ماندگار شدن، آن‌ها را به `~/.zshrc` / `~/.bashrc` اضافه کنید. در Windows PowerShell:

```powershell
$env:GEMINI_API_KEY = "cr_your_qcode_key"
$env:GOOGLE_GEMINI_BASE_URL = "https://api.qcode.cc/gemini"
```

**مقدار `GOOGLE_GEMINI_BASE_URL` را در `/gemini` متوقف کنید** و `/v1beta` را قرار ندهید: مثال رسمی یک نشانی بدون مسیر است (`export GOOGLE_GEMINI_BASE_URL="https://your-endpoint.example.com"`)، و کلاینت خودش بخش نسخه و مسیر درخواست را اضافه می‌کند. agy یک کلاینت Go با کد بسته است — Google نه قاعده اتصال را مستند کرده است و نه اینکه آیا `/` انتهایی نرمال‌سازی می‌شود (SDK پشت Gemini CLI آن را حذف می‌کند)، بنابراین از شکل مستندشده پیروی می‌کنیم و درباره موارد حاشیه‌ای حدس نمی‌زنیم. این خلاف ارائه‌دهنده `google` در OpenCode است (که واقعاً به `/v1beta` نیاز دارد)؛ تفاوت در [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) توضیح داده شده است.

**از سرزمین اصلی چین**، میزبان را با `https://asia.qcode.cc/gemini` عوض کنید (گره آسیا، نزدیک‌ترین از میان کره / تایوان / هنگ‌کنگ)؛ کلید تغییری نمی‌کند. `us` هم به همین شکل کار می‌کند.

> هنگام احراز هویت با `GEMINI_API_KEY`، `/logout` هیچ کاری نمی‌کند — نشست ذخیره‌شده‌ای برای پاک کردن وجود ندارد.

## گام 4: بررسی اتصال

نقطه پایانی Gemini در QCode را مستقیم و با دور زدن ابزار تست کنید:

```bash
# List the Gemini models you can currently call
curl -s https://api.qcode.cc/gemini/v1beta/models \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# Send a minimal request (use a model id from the list above)
curl -s "https://api.qcode.cc/gemini/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"contents":[{"parts":[{"text":"ping"}]}],"generationConfig":{"maxOutputTokens":16}}'
```

- JSON حاوی `candidates` → هم نقطه پایانی و هم کلید درست هستند
- **401** → مسیر درست است؛ کلید وجود ندارد یا اشتباه است

**پرس‌وجوی زنده را برای اینکه کدام مدل‌ها وجود دارند مرجع بدانید** — فهرست ثابتی را از هیچ مستند، از جمله همین مستند، کپی نکنید. شناسه‌هایی که اولین `curl` برمی‌گرداند همان‌هایی هستند که این نقطه پایانی QCode می‌تواند ارائه دهد؛ کاتالوگ کامل و قیمت‌ها در [qcode.cc/models](https://qcode.cc/models) است.

یک نکته: پنل `/model` در `agy` و `agy --model=...` از **نام‌های نمایشی محصول** استفاده می‌کنند (به شکل `Gemini 3.5 Flash`). Google مستند نکرده است که وقتی یک نقطه پایانی سفارشی تنظیم می‌شود، یک شناسه از API چگونه به یک ورودی پنل نگاشت می‌شود، و نه اینکه آیا آن فهرست اصلاً از نقطه پایانی شما می‌آید. اگر مدل شما در پنل وجود ندارد، راهنمای رسمی بیشتری وجود ندارد — ما این را **تست نکرده‌ایم**، بنابراین آن را همان‌طور که هست توصیف می‌کنیم.

پس از اینکه نقطه پایانی تأیید شد، یک گفتگو در `agy` اجرا کنید.
## ورودی بینایی در برابر تولید تصویر

ابزارهایی مانند `agy` می‌توانند **تصاویر را بخوانند** — یک اسکرین‌شات رابط کاربری، اسکرین‌شات خطا یا نمودار معماری را به آن‌ها بدهید و بگذارید مدل بر اساس آن کد بنویسد یا اشکال‌زدایی کند. این با **تولید** تصویر متفاوت است:

- **ورودی بینایی**: در prompt خود به مسیر یک فایل تصویر ارجاع دهید، یا تصویری را جای‌گذاری کنید یا بکشید و رها کنید. مدل‌های Gemini بینایی دارند. کاربردهای معمول: بازسازی یک رابط کاربری از روی یک طرح، یافتن یک باگ از روی اسکرین‌شات خطا، خواندن یک نمودار معماری.
- **تولید تصویر**: به مدل اختصاصی `gpt-image-2` روی نقطه پایانی تصویر QCode نیاز دارد — [تولید تصویر gpt-image-2](/docs/usage/image-2) را ببینید.

## عیب‌یابی

| نشانه | علت احتمالی | راه‌حل |
|---------|--------------|-----|
| CLI شروع نمی‌شود | `modelProvider: "gemini"` تنظیم شده است اما `GEMINI_API_KEY` وجود ندارد | متغیر محیطی را اضافه کنید، یا فیلد را حذف کنید تا به ورود با حساب کاربری بازگردید |
| 401 | کلید تزریق نشده یا نادرست است | `GEMINI_API_KEY` را بررسی کنید — پیشوند `cr_`، بدون فاصله اضافی |
| 404 | `GOOGLE_GEMINI_BASE_URL` یک `/v1beta` اضافی دارد، یا پیشوند مسیر نادرست است | در `/gemini` متوقف شوید، مانند مثال رسمی؛ رفتار اسلش انتهایی مستند نشده است |
| `model_not_available_on_endpoint` | مدلی از Claude / GPT درخواست شده است | این نقطه پایانی فقط Gemini را ارائه می‌دهد؛ کلاینت یا مدل را تغییر دهید |
| خطای نام مدل | شناسه بازنشسته‌شده یا با املای نادرست | از `curl` مرحله 4 برای فهرست کردن مواردی که واقعاً قابل فراخوانی هستند استفاده کنید |
| کندی / اتمام زمان از چین | استفاده از دامنه ریشه `api` | به `https://asia.qcode.cc/gemini` تغییر دهید |
| `/logout` هیچ کاری نمی‌کند | شما با یک کلید API احراز هویت کرده‌اید | انتظار می‌رود — نشستی برای پاک کردن وجود ندارد |

## بعدی

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — جدول پروتکل × خانواده مدل
- [یکپارچه‌سازی Gemini CLI](/docs/ide/gemini) — نسخه پیشین (کلیدهای سازمانی هنوز کار می‌کنند)
- [زیرعامل‌ها](/docs/advanced/subagents) — هماهنگ‌سازی عامل‌های پس‌زمینه
- [خودکارسازی و CI/CD](/docs/advanced/headless) — حالت بدون رابط گرافیکی و اسکریپت‌نویسی

> هنوز کلید QCode ندارید؟ یک کلید `cr_` مدل‌های Claude، GPT، چینی و تصویری را پوشش می‌دهد (روی پروتکل‌های مختلف
> — جدول بالا را ببینید). برای شروع [قیمت‌گذاری](https://qcode.cc/pricing) را ببینید.