Antigravity CLI 中转站配置教程

# Antigravity CLI 中转站配置教程

> 适用：`agy`（Google Antigravity CLI，Gemini 系列的官方终端智能体）  
> 中转站地址：`https://api.zaimod.com`  
> 主线：**建令牌 → 写一行 `settings.json` → 设两个环境变量 → `agy` 启动**，约 8 分钟

---

## 一、先弄清这是哪条线

如果你按老教程装的是 `gemini` 命令，那是**上一代产品**。Google 已经把 Gemini CLI 的后续开发整体迁到 Antigravity CLI，二进制名从 `gemini` 换成 `agy`，语言从 Node.js 换成 Go —— 这**不是改名，是换产品**。

| 项目      | Gemini CLI（旧）          | Antigravity CLI（新）           |
| ------- | ---------------------- | ---------------------------- |
| 命令      | `gemini`               | `agy`                        |
| 运行时     | Node.js（npm 安装）        | Go 原生二进制，**不需要 Node.js**     |
| 配置目录    | `~/.gemini/`           | `~/.gemini/antigravity-cli/` |
| 主配置     | `~/.gemini/.env` 或环境变量 | `settings.json` + 环境变量       |
| MCP 配置  | 内联在 `settings.json`    | 独立 `mcp_config.json`         |
| 工作区技能目录 | `.gemini/skills/`      | `.agents/skills/`            |

**停服边界要分清楚**，别被"Gemini CLI 已死"的说法带偏：

- 2026 年 6 月 18 日起，**个人 / 免费 / Google AI Pro、Ultra 订阅**这几条消费级通道停止为 Gemini CLI 提供请求服务；
- **企业版（Code Assist Standard / Enterprise）和走 API Key 计费**的用法不受这个时间点限制 —— 本教程属于后者，这也是"旧版兼容"分页还能继续用的原因；
- 官方公告：`https://developers.googleblog.com/en/an-important-update-transitioning-gemini-cli-to-antigravity-cli/`

> 一句话：**新装就装 `agy`**；只有在维护旧配置、或所在环境只能用 `gemini` 时，才翻到《Gemini CLI（旧版）配置教程》那一篇。

---

## 二、一分钟速查表

| 项目     | 填什么                                                                                                       |
| ------ | --------------------------------------------------------------------------------------------------------- |
| 配置文件   | `~/.gemini/antigravity-cli/settings.json`（Windows：`C:\Users\<用户名>\.gemini\antigravity-cli\settings.json`） |
| 配置文件内容 | **只有一行**：`{"modelProvider": "gemini"}`                                                                    |
| 凭证     | 环境变量 `GEMINI_API_KEY` = 你的令牌                                                                              |
| 接口地址   | 环境变量 `GOOGLE_GEMINI_BASE_URL` = `https://api.zaimod.com`（**纯域名，不带 `/v1beta`**）                             |
| 令牌分组   | **Gemini-GCP**                                                                                            |
| 验证     | `agy --version` → `agy` → 顶部出现 `Gemini API key`                                                           |

**两个反直觉的点先说在前面：**

1. **`settings.json` 里不写 Key、也不写地址**。Antigravity CLI 只从**环境变量**读这两样东西，写进 JSON 不会生效，还会让你误以为配好了。
2. **分组名和客户端是交叉的**：Antigravity CLI 用「**Gemini-GCP**」，旧版 Gemini CLI 用「**Gemini-反重力**」。名字反着来，配反了就是 401 / 模型列表空。见第九章第 4 条。

---

## 三、第一步：建令牌（Gemini-GCP）

**1. 控制台 → 令牌管理 → 创建令牌**

**2. 名称**随意，建议 `agy` 或 `gcp`（能认出是给这条线用的就行）。

**3. 令牌分组可选「Gemini」或者「智能自动」**

**4.「模型限制列表」留空**

界面上的原话是「请选择该令牌支持的模型，留空支持所有模型」。留着空 = 不限制；一旦填了，而列表里没有 CLI 实际请求的那个模型，就会直接 403。Antigravity CLI 会自己挑模型、还可能切到低配版本跑子任务，你很难列全，所以留空最稳。

**5. 提交 → 回到令牌列表 → 「密钥」列 → 复制密钥**

复制菜单里有两个容易混的项：

- **复制密钥** ← 要的是这个，得到一串纯密钥；
- **复制连接信息** ← 得到的是带 `Base URL`、`Bearer` 前缀的一整段，粘进环境变量会直接 401。

---

## 四、第二步：写 `settings.json`（只写一行）

Antigravity CLI 的配置目录是 `~/.gemini/antigravity-cli`。文件内容**只有**这一个字段：

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

### 4.1 Windows

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.gemini\antigravity-cli" | Out-Null
notepad "$env:USERPROFILE\.gemini\antigravity-cli\settings.json"
```

记事本里粘贴上面那段 JSON 保存。**注意别存成 `settings.json.txt`**（保存对话框里把「保存类型」改成「所有文件」）。

### 4.2 macOS

```bash
mkdir -p ~/.gemini/antigravity-cli
touch ~/.gemini/antigravity-cli/settings.json
open -e ~/.gemini/antigravity-cli/settings.json
```

### 4.3 Linux

```bash
mkdir -p ~/.gemini/antigravity-cli
nano ~/.gemini/antigravity-cli/settings.json
```

粘贴后按 `Ctrl + O` → 回车 → `Ctrl + X`。

### 4.4 `modelProvider` 到底是什么

原文这一段解释得很到位，值得原样保留并展开：

- 它是 **CLI 的后端标识**，不是中转站的令牌分组名。你令牌选的是 Gemini-GCP，这里**也必须写 `gemini`**；
- 改成 `gcp`、`openai`、`antigravity` 都不行 —— 官方 CLI 只在值为 `gemini` 时启用 **`GEMINI_API_KEY` 直连模式**，其它值会走默认登录后端，也就是把你扔回浏览器里做 Google 账号 OAuth；
- **删掉这个字段** = 恢复默认登录后端（同样会要求 OAuth）。

所以这个字段唯一的作用就是：**告诉 agy"我要用 API Key 直连，别拉我去登录"**。

### 4.5 校验 JSON

```powershell
# Windows
Get-Content "$env:USERPROFILE\.gemini\antigravity-cli\settings.json" -Raw | ConvertFrom-Json
```

```bash
# macOS / Linux
python3 -m json.tool ~/.gemini/antigravity-cli/settings.json
```

能原样打印 = 合法。JSON 坏了 agy 不一定报错，可能直接当没配过、退回默认登录 —— 所以这一步值得做。

---

## 五、第三步：设两个环境变量

这是整篇最关键的一步，**两个变量缺一不可**：一个证明你是谁，一个告诉它去哪。

### 5.1 Windows（PowerShell）

```powershell
[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "你的API_KEY", "User")
[Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "https://api.zaimod.com", "User")
```

把 `你的API_KEY` 换成第三步复制的密钥，两行分别执行。

**必须知道的三个细节：**

1. `"User"` 表示写入**当前用户的永久环境变量**，重启电脑也在；写成 `"Process"` 只对当前进程有效。
2. **设置完不会影响已经开着的终端**。必须关掉 PowerShell 重开，`agy` 才读得到。
3. 想验证是否写进去了，**新开**一个 PowerShell：

```powershell
[Environment]::GetEnvironmentVariable("GEMINI_API_KEY","User")
[Environment]::GetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL","User")
```

能打印出值就算成功。若返回空，说明上一行执行时报错了（常见于引号用了中文引号）。

### 5.2 macOS

```bash
echo 'export GEMINI_API_KEY="你的API_KEY"' >> ~/.zshrc
echo 'export GOOGLE_GEMINI_BASE_URL="https://api.zaimod.com"' >> ~/.zshrc
source ~/.zshrc
```

macOS 现在默认 zsh，写 `~/.zshrc`；确认一下自己用的是哪个：

```bash
echo $SHELL
```

输出 `/bin/bash` 就把 `~/.zshrc` 换成 `~/.bash_profile`。

> 原文这里只说"将替换后的一行加入 `~/.zshrc` 并保存"，没给命令。实际手敲 `export ...` 只对**当前这个终端窗口**有效，关掉就没了 —— 一定要落到 rc 文件里。

### 5.3 Linux

```bash
echo 'export GEMINI_API_KEY="你的API_KEY"' >> ~/.bashrc
echo 'export GOOGLE_GEMINI_BASE_URL="https://api.zaimod.com"' >> ~/.bashrc
source ~/.bashrc
```

用 zsh / fish 的，换成 `~/.zshrc` / `~/.config/fish/config.fish`（fish 的写法是 `set -gx GEMINI_API_KEY "..."`）。

### 5.4 地址为什么只能是纯域名

`GOOGLE_GEMINI_BASE_URL` 填的是**根域名**，CLI 自己往后拼 `/v1beta/models/{模型}:generateContent`。

写成 `https://api.zaimod.com/v1beta` → 实际请求变 `/v1beta/v1beta/models/...` → 404。  
末尾也别加 `/`，同理。

这条和 n8n、扣子那类"必须写到 `/v1`"的客户端**正好相反**，是换域名时最容易踩的坑。

---

## 六、第四步：启动与验证

**关掉并重新打开终端**（让新环境变量生效），然后：

```bash
agy
```

![](/uploads/editor/20261101/img_6ae627a0bce5b4.54460430.png)

### 6.1 看这三处

| 位置   | 应该看到                         | 看到别的东西说明什么                                                                             |
| ---- | ---------------------------- | -------------------------------------------------------------------------------------- |
| 顶部横幅 | `Antigravity CLI <版本号>`      | 版本号异常旧 → 装了两份，用 `which -a agy` 查                                                       |
| 认证行  | **`Gemini API key`**         | 出现 `Google account` / 让你浏览器 OAuth → 没读到 `GEMINI_API_KEY`，或 `modelProvider` 不是 `gemini` |
| 当前模型 | 例如 `Gemini 3.8 Flash (High)` | 显示的还是官方默认模型 → `GOOGLE_GEMINI_BASE_URL` 没生效                                             |

截图里这三行同时出现，就是配置到位的完整凭证。

### 6.2 发一句话

```console
你好
```

正常返回内容 = 通了。但**最硬的证据仍然是控制台**：「使用日志」里要出现这次请求记录。

- 有回复 + 日志有记录 → 完全打通
- 有回复 + 日志空 → 还在走官方，回头查环境变量是否被别处覆盖
- 无回复 + 日志空 → 见第八章

### 6.3 换模型

会话里直接敲斜杠命令：

```console
/model
```

模型名称以**控制台模型广场**为准，不用写进 `settings.json` —— 这条原文说对了：Antigravity CLI 会根据令牌分组读取可用模型，写死在配置里反而会和分组打架。

---

## 七、从 Gemini CLI 迁过来（老用户必看）

原来的 `gemini` 配置不会自动变成 `agy` 的配置，但有官方迁移命令。原文完全没提这段，属于本教程补充。

**1. 首次启动会自动问你要不要迁移**

在还有旧配置的机器上第一次跑 `agy`，会弹出交互清单，让你选择要转换的扩展和全局配置，并把会话令牌存进系统钥匙串。

**2. 手动导入扩展 → 插件**

```bash
agy plugin import gemini
```

它会扫描旧的本地目录，把 Gemini 扩展转成 Antigravity 的原生插件（`commands` 会转成 skills，`mcpServers` 会迁到 `mcp_config.json`）。

**3. 三处路径变了，要手动搬**

| 资产     | Gemini CLI          | Antigravity CLI                                                |
| ------ | ------------------- | -------------------------------------------------------------- |
| 全局技能   | `~/.gemini/skills/` | `~/.gemini/antigravity-cli/skills/`                            |
| 工作区技能  | `.gemini/skills/`   | `.agents/skills/` ← **要手动 mv**                                 |
| MCP 配置 | 内联在 `settings.json` | `~/.gemini/config/mcp_config.json` 或 `.agents/mcp_config.json` |

```bash
# 工作区技能搬家（在项目根目录执行）
mkdir -p .agents && git mv .gemini/skills .agents/skills
```

**4. MCP 的远程服务器字段名改了**

旧写法 `url` / `httpUrl` 要改成 **`serverUrl`**。漏改的表现很坑：**不报错**，MCP 工具就是不出现，模型照样侃侃而谈。

```json
{
  "mcpServers": {
    "remote-indexer": {
      "serverUrl": "https://mcp.example.com/sse",
      "env": { "AUTH_TOKEN": "xxx" }
    }
  }
}
```

**5. 迁移完跑一次体检**

```bash
agy doctor
```

上下文文件（`GEMINI.md`、`AGENTS.md`）两边通用，不用改。

---

## 八、常见问题

| 现象                                            | 原因                                                 | 处理                                                        |
| --------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `agy : 无法将"agy"项识别为...` / `command not found` | 安装目录不在 PATH（脚本一般装到 `~/.local/bin`），或装完没重开终端        | 重开终端；仍不行把 `~/.local/bin` 加进 PATH 后 `source`               |
| 安装脚本卡住、超时、`curl: (7) Failed to connect`       | `antigravity.google` 在部分网络下直连不通                    | 本机开代理后重跑安装命令，**确认终端本身走了代理**（很多命令行工具不继承系统代理）               |
| 启动后被拉去浏览器做 Google 登录                          | `GEMINI_API_KEY` 没读到，或 `modelProvider` 不是 `gemini` | 新开终端 `echo $GEMINI_API_KEY` 确认；检查 `settings.json` 只有那一个字段 |
| `401` / 无效令牌                                  | 密钥粘错（多了 `Bearer `）、令牌被删、额度耗尽                       | 回控制台「复制密钥」重取                                              |
| `403`                                         | 令牌的「模型限制列表」里没有当前模型                                 | 编辑令牌，把该列表清空                                               |
| `404`                                         | `GOOGLE_GEMINI_BASE_URL` 带了 `/v1beta` 或末尾 `/`      | 改成纯域名 `https://api.zaimod.com`                             |
| 能对话但工具不生效、Agent 不动手                           | 分组不支持对应能力，或迁移后 MCP 字段没改成 `serverUrl`               | 换 Gemini-GCP 分组；检查 `mcp_config.json`                      |
| Windows 设完环境变量没反应                             | 没重开终端，或写到了 `"Process"` 作用域                         | 重开 PowerShell；确认第三个参数是 `"User"`                           |
| `settings.json` 改了没效果                         | 文件存成了 `.txt`、或有 BOM / 中文引号                         | 用 4.5 的命令校验；重存为 UTF-8 无 BOM                               |
| 回复很慢或中断                                       | 网络抖动 / 长连接被掐                                       | 重开 `agy`；必要时挂代理                                           |
| 模型名和文档里的不一样                                   | 分组不同、控制台模型池在变                                      | 以模型广场为准，`/model` 里选实际存在的那个                                |

---

上一篇：Gemini CLI配置{else}上一篇：没有了下一篇：Grok Build 配置{else}下一篇：没有了