# Google Antigravity CLI 接入

> **最后核实**：2026-09-18 · 📄 依据官方文档（Antigravity CLI 1.2.x（自更新清单 1.2.6，2026-09 查阅））

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | 走 QCode 这条腿：Gemini ✅（原生协议，`GOOGLE_GEMINI_BASE_URL`）· 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 与 Gemini Code Assist 的 IDE 扩展「will stop serving requests」，对象是
> **Google AI Pro、Ultra，以及用个人账号免费使用的那批人**；**企业付费密钥不受影响**——
> 同一篇公告说仍可通过付费的 Gemini / Gemini Enterprise Agent Platform API key 继续使用。
> 当天上线的是 **Antigravity CLI 与 Antigravity 2.0**，而 Antigravity 这款 IDE 早在
> **2025-11-18** 就已发布。之前按 [Gemini CLI 集成](/docs/ide/gemini) 配过的，可以改用本页的方式。

[Google Antigravity](https://antigravity.google/) 是 Google 面向个人登录档接替 Gemini CLI 的新一代工具链，
包含桌面 IDE、命令行 **Antigravity CLI（`agy`，Go 编写）** 与 SDK 三部分。
本页只讲 CLI：把 **QCode.cc 配成它的模型上游**。

## 🔴 先看清楚：只能走 Gemini 协议

Antigravity CLI 的自定义端点是 **Gemini 兼容**的，通过环境变量 `GOOGLE_GEMINI_BASE_URL` 指定。
官方 troubleshooting 表逐字写着 `modelProvider` 的「**gemini 是唯一可接受的取值**」，
所以这条路径**接不上 OpenAI 兼容端点**；经 QCode 时也只能调 Gemini 系模型。

| 项 | 值 |
|---|---|
| 配置文件 | `~/.gemini/antigravity-cli/settings.json` |
| 关键字段 | `"modelProvider": "gemini"` |
| 密钥 | 环境变量 `GEMINI_API_KEY`（填你的 QCode `cr_` 密钥） |
| 端点覆盖 | 环境变量 `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 / 自定义 provider 入口**，无法把它的内置 agent
模型换成第三方端点。社区有基于本地代理拦截的第三方方案，但那属于逆向手段、不受官方支持，
本页不做推荐。

**能接 QCode 的是 CLI（`agy`），不是 IDE。**

## 前置条件

- 拥有 QCode.cc API Key（`cr_` 开头），在 [控制台](https://qcode.cc/dashboard) 获取
- 了解 QCode 的 [接入点与 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
# 安装到 ~/.local/bin/agy
```

</div>

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

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

</div>

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

PowerShell：

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
# 安装到 C:\Users\<用户名>\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`；macOS / Linux 的 `install.sh` 自己只认 `-d, --dir <路径>` 与 `-h, --help`，遇到未知参数会直接退出。别在 macOS / Linux 上照抄这两个旗标。

## 第 2 步：改用 API Key 登录（跳过 Google 账号）

默认情况下 `agy` 会去读系统钥匙串或拉起浏览器做 Google 账号登录。要改成用 API Key，
编辑（不存在则新建）`~/.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_你的QCode密钥"
export GOOGLE_GEMINI_BASE_URL="https://api.qcode.cc/gemini"
```

写进 `~/.zshrc` / `~/.bashrc` 可持久化。Windows PowerShell：

```powershell
$env:GEMINI_API_KEY = "cr_你的QCode密钥"
$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 客户端，官方既没有成文说明拼接规则，也**没有**说明末尾多一个 `/` 会不会被规整
（Gemini CLI 那条腿的 SDK 是会剥掉一个尾斜杠的），所以我们只按官方示例的形态写，不去猜边界行为。
这一点和 OpenCode 的 `google` provider 相反（那个要带 `/v1beta`），
两种写法的区别见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

**国内用户**把域名换成 `https://asia.qcode.cc/gemini`（亚洲节点，HK/JP 就近）即可，Key 不变；
`us` / `eu` 同理。

> 用 `GEMINI_API_KEY` 登录时，`/logout` 不起作用 —— 因为没有存储的会话可清除。

## 第 4 步：验证连通

先绕开工具直接打 QCode 的 Gemini 端点：

```bash
# 看当前可调的 Gemini 模型
curl -s https://api.qcode.cc/gemini/v1beta/models \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# 发一条最小请求（模型名换成上面列出的）
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}}'
```

- 返回带 `candidates` 的 JSON → 端点与密钥都正常
- 返回 **401** → 路径对，密钥缺失或写错

**可用模型以实时查询为准**，不要照抄任何文档里的固定清单。上面第一条 `curl` 返回的 id，就是
QCode 这条腿上能调的模型；完整清单与单价见 [qcode.cc/models](https://qcode.cc/models)。

不过要留个心：`agy` 的 `/model` 面板和 `agy --model=...` 用的是**产品展示名**（形如 `Gemini 3.5 Flash`），
官方没有说明在自定义端点下如何把 API 返回的 id 对到面板项，也没说这个列表是否来自你所配的端点。
如果面板里找不到你要的型号，官方没有给出进一步的写法——这条我们**未实测**，只能按现状描述。

确认端点可用后再回到 `agy` 里跑一次对话。

## 看图（视觉输入）与生成图像的区别

`agy` 这类工具能**读图**——把界面截图、报错截图、架构图喂给具备视觉能力的模型，
让它据此写代码或排错。这和**生成图像**是两回事：

- **看图（视觉输入）**：在提示里引用图片文件路径，或粘贴 / 拖拽图片。
  Gemini 系模型具备视觉能力。典型用途：照着设计稿还原 UI、根据报错截图定位 bug、读架构图。
- **生成图像**：要用专门的图像模型 `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 系；换客户端或换模型 |
| 模型名报错 | 用了未在售或拼错的 id | 用第 4 步的 `curl` 列出实际可调集合 |
| 国内连接慢 / 超时 | 用了 `api` 主域 | 改用 `https://asia.qcode.cc/gemini` |
| `/logout` 没反应 | 用的是 API Key 登录 | 属预期行为，没有会话可清除 |

## 进一步

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族真源表
- [Gemini CLI 集成](/docs/ide/gemini) — 迁移前的旧工具（企业密钥仍可用）
- [子代理](/docs/advanced/subagents) — 编排多个后台 agent
- [自动化与 CI/CD](/docs/advanced/headless) — 无头模式与脚本化

> 还没有 QCode 密钥？同一把 `cr_` 密钥覆盖 Claude、GPT、Gemini 与图像模型（协议不同，
> 见上文真源表）。查看 [价格方案](https://qcode.cc/pricing) 开始使用。