Google AI 编程工具实战避坑指南

本文将详细介绍使用 Google 全新 AI 编程工具 Antigravity 和 Gemini CLI 时遇到的各种问题及解决方案，帮助开发者快速上手这两款被誉为"下一代 AI 编程助手"的产品。

一、前置知识

在阅读本文之前，建议你具备以下基础：

• 基本的代理/VPN 使用经验
• 熟悉 VS Code 或类似 IDE 的使用
• 了解 AI 编程辅助工具的基本概念
• 基本的终端命令行操作能力

二、Antigravity 与 Gemini CLI 简介

2.1 Antigravity 是什么

Google Antigravity 是谷歌在 2025 年 11 月与 Gemini 3.0 一同发布的全新 AI 原生集成开发环境（IDE）。它不是传统代码编辑器的简单插件，而是将 AI 代理、代码编辑器和浏览器深度融合，打造了从需求规划、代码编写、自动化测试到部署验证的"全流程闭环"。

核心特性：

• Agent-First 理念：AI 代理可以跨编辑器、终端和浏览器进行规划、执行和验证编码任务
• 多模型支持：深度整合 Gemini 3，同时兼容 Claude、GPT 等第三方大模型
• 全流程自动化：从编码到测试再到部署验证的完整工作流

2.2 Gemini CLI 是什么

Gemini CLI 是 Google 推出的终端版 AI 助手，通过命令行界面即可直接调用 Gemini 的强大能力。与网页版 Gemini 主要区别在于使用场景和交互方式：

三、必须开启 VPN TUN 模式

问题现象

许多用户在安装 Antigravity 后，点击登录按钮后浏览器弹开，但一直转圈无法完成验证；或者登录成功后软件界面卡死、功能不加载。

根本原因

Antigravity 作为一个独立的桌面应用，它的验证请求可能没有被传统系统代理（System Proxy）捕获。多数代理软件的默认配置只代理浏览器流量，而 Antigravity 的本地验证流量走了不同的网络路径。

解决方案：开启 TUN 模式

TUN 模式（虚拟网卡模式）是一种比传统系统代理更底层的网络转发方式，它会创建一个虚拟网卡，将所有流量（包括应用程序的直接网络请求）都纳入代理范围。

操作步骤：

1. 打开你的代理软件（Clash、V2Ray、Mirage 等）
2. 找到「TUN 模式」或「虚拟网卡模式」设置
3. 开启该模式
4. 重启 Antigravity 应用

注意事项：

• TUN 模式下，进入 Antigravity 后建议先选择「Open Folder」（随便选个文件夹进入系统），然后在顶部把模式切换为「Playground」开始使用
• 建议使用美区节点，实测稳定性最高

替代方案：Proxifier 强制代理

如果你因某些原因不想开启全局 TUN 模式，可以使用 Proxifier 强制指定 Antigravity 走代理：

# 配置代理服务器
Proxy Server: 127.0.0.1:7890  # 具体端口请查看你的代理软件设置

# 配置代理规则
Target Hosts: *  # 通配符匹配所有目标

更好的替代方案：Antigravity-Proxy 插件

如果你觉得 TUN 模式流量消耗太大（全局代理所有流量），这里有一个更优雅的解决方案：Antigravity-Proxy。

为什么是更好的方案

工作原理

Antigravity-Proxy 是一个基于 MinHook 的 Windows DLL 代理注入工具。它通过劫持 version.dll，将 Antigravity 相关进程（Antigravity.exe 和 language_server_windows）的网络流量透明地重定向到本地 SOCKS5/HTTP 代理，而不影响其他应用程序。

安装配置步骤

1. 下载 Antigravity-Proxy

   GitHub 仓库：https://github.com/yuaotian/antigravity-proxy

2. 准备文件

   下载后解压，得到以下文件：

   • version.dll - 代理注入 DLL
   • config.json - 配置文件

3. 配置代理端口

   编辑 config.json，修改代理服务器配置：

   {
     "proxy": {
       "host": "127.0.0.1",
       "type": "socks5",
       "port": 6328  // 改成你的 SOCKS 端口
     }
   }
   

   常用代理软件端口参考：

   代理软件	SOCKS5 端口	HTTP 端口
   Clash / Clash Verge	7891	7890
   Clash for Windows	7891	7890
   V2RayN	10808	10809

4. 复制到 Antigravity 目录

   将 version.dll 和 config.json 复制到 Antigravity 安装目录（与 Antigravity.exe 同级）：

   D:\Antigravity\Antigravity\
   ├── Antigravity.exe
   ├── version.dll        # 复制到这里
   └── config.json        # 复制到这里
   

5. 验证配置

   启动 Antigravity 后，会在同目录生成 proxy.log 日志文件，可以查看代理是否成功注入。

使用流程（推荐）

1. 启动 Clash Verge（开启系统代理/规则模式，不需要 TUN！）
2. 启动 Antigravity
3. 正常登录和使用

关键点：Clash Verge 只需开启系统代理（规则模式），不需要开启 TUN 模式！

Antigravity-Proxy 会强制 Antigravity 的流量走本地 SOCKS5 代理，而其他应用正常走系统代理规则，互不影响。

常见问题

• 代理软件必须保持开启：因为依赖本地端口，关闭代理软件会导致 Antigravity 断网
• 日志查看：如遇问题，查看 proxy.log 排查
• 端口测试：可以用以下命令测试端口是否可用：

  Test-NetConnection -ComputerName 127.0.0.1 -Port 6328
  

四、Antigravity Manager 与 Tools 的使用

为什么需要它

Antigravity 官方对账号所在地有限制，很多用户会遇到以下错误提示：

"Your current account is not eligible for Antigravity, because it is not currently available in your location."

即使账号没有问题，登录成功后也可能一直卡在设置页面无法进入主界面。

Antigravity Manager 介绍

Antigravity Manager 是一个基于 Tauri v2 + React (Rust) 构建的专业 Antigravity 账号管理与切换工具，核心功能包括：

• 账号管理：一键添加、删除、切换 Google 账号
• 配额监控：实时显示各账号的模型使用配额
• 协议转换：支持将 Google Session 转化为标准 API 接口
• 多账号轮询：当一个账号达到频率限制时自动切换

使用步骤

1. 下载 Antigravity Manager

   访问 GitHub 仓库：https://github.com/lbjlaq/Antigravity-Manager

2. 安装并启动

   解压后运行程序，使用你的 Google Pro 账号登录

3. 配置反代服务

   在「API 反代」栏目启动服务

4. 打开 Antigravity

   确保 VPN 开启 TUN 模式，现在可以直接使用而无需再经历繁琐的登录流程

Antigravity Tools 的预热账号功能

你提到的 Antigravity Tools（就是 Antigravity Manager 的新名称）确实具备「预热账号」功能。这个功能的目的是：

• 提前激活配额：通过定时唤醒 AI 模型来触发配额重置周期
• 减少冷启动时间：保持账号处于活跃状态，避免首次使用时等待过久
• 降低风控风险：模拟正常用户使用行为，减少账号被判定为异常的风险

五、VS Code 设置与插件迁移

问题背景

通过 Antigravity Manager 跳过官方安装流程后，Antigravity 是一个没有任何配置的全新环境。如果你希望迁移现有的 VS Code 设置和插件，需要手动操作。

迁移步骤

1. 在 Antigravity 中打开命令面板：

   • Windows/Linux：Ctrl + Shift + P
   • Mac：Cmd + Shift + P

2. 输入并搜索以下命令之一：

   • Import VS Code settings - 导入 VS Code 设置
   • Import VS Code extensions - 导入 VS Code 插件

3. Antigravity 会自动扫描你电脑上标准路径下的 VS Code 数据并进行迁移

插件市场配置

Antigravity 默认使用 Open VSX 作为插件市场，如果你需要使用 VS Code 官方插件市场，需要手动配置：

1. 打开 Antigravity Settings
2. 找到「Editor」设置项
3. 修改以下两个地址为官方源：

   Marketplace Item URL: https://marketplace.visualstudio.com/items
   Marketplace Gallery URL: https://marketplace.visualstudio.com/_apis/public/gallery
   

4. 重启 Antigravity 生效

六、Agent Terminated 错误与 Cockpit 插件

问题描述

在使用 Antigravity 过程中，你可能会遇到以下错误：

"Agent terminated due to error. You can prompt the model to try again or start a new conversation if the error persists."

这个错误通常由以下原因导致：

• 资源耗尽：内存或文件描述符耗尽
• 未捕获异常：关键代码路径缺少异常处理
• 外部依赖故障：API 调用超时或失败
• 账号状态异常：账号配额耗尽或被风控

Antigravity Cockpit 插件介绍

针对上述问题，社区开发者提供了 Antigravity Cockpit 插件来解决。

核心功能：

1. 一键切号：无需手动登录 logout，快速切换账号
2. 多种导入方式：支持 OAuth 授权、Refresh Token、插件同步
3. 唤醒任务：定时激活 AI 模型，触发配额重置周期
4. 设备指纹：生成、管理、绑定设备指纹，降低风控风险
5. 多开实例：支持同时运行多个独立账号实例

安装与配置

1. 下载 Cockpit 插件

   GitHub 地址：https://github.com/jlcodes99/cockpit-tools

2. 安装步骤

   • 点击 Antigravity 下方一排绿色的指示灯
   • 在弹出框中选择「自动唤醒」
   • 点击「立即测试」

3. 配置说明

   • WebSocket 服务默认仅本地访问（127.0.0.1）
   • 默认端口：19528（可在设置中修改）
   • 数据存储在：~/.antigravity_cockpit

预热账号与自动唤醒的关系

你问的这个问题很好。Antigravity Tools 的「预热账号」功能和 Cockpit 的「自动唤醒」功能确实有相似之处，但侧重点不同：

两者可以配合使用，效果更佳。

七、 Gemini CLI 常见问题与解决方案

7.1 安装前置条件

在安装 Gemini CLI 之前，请确保满足以下环境要求：

• Node.js 18+（推荐使用 nvm 进行版本管理）
• 科学上网环境（建议开启全局代理模式）
• 终端代理配置

7.2 终端代理设置

Gemini CLI 需要通过终端运行，因此必须配置终端代理：

# Windows PowerShell（临时设置）
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"

# Windows CMD（临时设置）
set HTTPS_PROXY=http://127.0.0.1:7890
set HTTP_PROXY=http://127.0.0.1:7890

# macOS / Linux（临时设置）
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

注意： 代理设置为临时，每次启动终端都需重新设置。如需永久生效，请添加到系统环境变量或Shell配置文件中。

7.3 GOOGLE_CLOUD_PROJECT 环境变量问题

问题描述

如果你使用企业/工作区 Google 账号，可能会遇到以下错误：

"Failed to login. Workspace accounts and licensed Code Assist users must configure GOOGLE_CLOUD_PROJECT"

或

"This account requires setting the GOOGLE_CLOUD_PROJECT env var"

解决方案

1. 访问 Google Cloud 控制台：https://console.cloud.google.com/

2. 创建或选择项目：

   • 如果你从未创建过项目，系统会自动生成名为 "My First Project" 的默认项目
   • 在控制台左上角点击项目名称，在弹出的项目列表中查看项目 ID（例如：my-awesome-project-382913）

3. 启用 Gemini API：

   • 访问 API 库：https://console.cloud.google.com/apis/library
   • 搜索 "Gemini for Google Cloud" 并启用

4. 设置环境变量：

   # Windows PowerShell
   $env:GOOGLE_CLOUD_PROJECT="你的项目ID"
   
   # Windows CMD
   set GOOGLE_CLOUD_PROJECT=你的项目ID
   
   # macOS / Linux
   export GOOGLE_CLOUD_PROJECT=你的项目ID
   

5. 验证配置：

   # 验证环境变量是否设置成功
   $env:GOOGLE_CLOUD_PROJECT
   

7.4 中文文档显示乱码问题

问题描述

在使用 Gemini CLI 时，你可能会遇到以下问题：

• 现象：当 Gemini CLI 执行 PowerShell 命令并输出中文时，显示为乱码
• 示例：本应显示「目录」，却显示为「鐩綍」

根本原因

这是典型的终端字符编码问题：

• Windows PowerShell 默认使用 GBK 编码（代码页 936）
• Gemini CLI 输出的内容使用 UTF-8 编码
• 两者编码不匹配导致中文无法正确解析

解决方案：修改 PowerShell 编码为 UTF-8

第一步：打开 PowerShell 配置文件

# 在 PowerShell 中执行
if (!(Test-Path $PROFILE)) { New-Item -Path $PROFILE -Type File -Force }
notepad $PROFILE

这会打开一个记事本窗口（配置文件）。

第二步：添加编码设置

在打开的记事本中粘贴以下三行代码：

[Console]::InputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

按 Ctrl + S 保存，然后关闭记事本。

第三步：重启 PowerShell 验证

1. 完全关闭当前 PowerShell 窗口
2. 重新打开 PowerShell
3. 测试乱码是否解决

解决方案二：修改 Windows 系统区域设置（推荐）

如果你希望全局解决中文乱码问题，可以修改系统区域设置：

1. 打开「设置」→「时间和语言」→「语言和区域」
2. 点击「管理语言设置」
3. 在「管理」选项卡中，点击「更改系统区域设置」
4. 勾选「Beta：使用 Unicode UTF-8 提供全球语言支持」
5. 重启电脑

注意： 此设置会影响所有应用程序的编码行为，请谨慎使用。

八、完整工作流程总结

graph TD
    A[选择工具] -->|Antigravity| B[网络配置]
    A -->|Gemini CLI| C[终端配置]

    B --> D{选择代理方案}
    D -->|方案一| E[开启 TUN 模式]
    D -->|方案二| F[使用 Antigravity-Proxy]

    E --> G{登录是否成功?}
    F --> G

    G -->|失败| H[下载 Antigravity Manager]
    H --> I[使用 Manager 登录账号]
    I --> J[启动 API 反代服务]
    J --> K[打开 Antigravity]
    K --> L[配置 VS Code 迁移]
    L --> M[可选：安装 Cockpit 插件]

    C --> N[安装 Node.js 18+]
    N --> O[设置终端代理]
    O --> P{是否企业账号?}
    P -->|是| Q[配置 GOOGLE_CLOUD_PROJECT]
    P -->|否| R{是否出现乱码?}
    Q --> S[启动 Gemini CLI]
    R -->|是| T[修改 PowerShell 编码为 UTF-8]
    T --> S
    R -->|否| S

    M --> U[开始使用]
    S --> U

    style E fill:#9ff,color:#000
    style H fill:#f9f,color:#000
    style T fill:#ff9,color:#000
    style U fill:#9f9,color:#000

九、总结要点

1. 网络配置是关键：解决登录问题的核心是让 Antigravity 流量走代理
2. 推荐 Antigravity-Proxy：可关闭 TUN 模式，仅代理 Antigravity 相关进程，节省 VPN 流量
3. 善用第三方工具：Antigravity Manager/Tools 可以绕过复杂的官方登录流程
4. 插件迁移需手动：通过命令面板的 Import 命令可以迁移 VS Code 数据
5. Agent 错误可解：Cockpit 插件的自动唤醒功能可以有效减少 "Agent terminated" 错误
6. 预热功能有区别：Tools 的预热和 Cockpit 的自动唤醒侧重点不同，可配合使用
7. Gemini CLI 终端编码：如遇中文乱码，修改 PowerShell 配置文件添加 UTF-8 编码设置
8. 企业账号需配置：工作区账号需要设置 GOOGLE_CLOUD_PROJECT 环境变量

提示：代理和账号管理工具存在一定风险，请谨慎使用，建议仅用于学习研究目的。