# Gemini 接入教程：VS Code、API 与 CLI 配置

> 使用 Passion8 地址、API Key 和模型接入 Gemini：推荐 Cline VS Code 插件或 API，保留 Gemini CLI 手动配置、CC Switch 与登录迁移说明。

URL: https://docs.passion8.cc/docs/gemini
Language: zh-CN
Publisher: Passion8
Last updated: 2026-10-11

通过 Passion8 使用 Gemini，只需**本站 API Key、可用模型 ID 和对应协议的地址**。在 VS Code 使用 Cline 时，选择 `OpenAI Compatible`，Base URL 填 `https://passion8.cc/v1`；Gemini CLI 使用原生协议根地址 `https://passion8.cc`。不需要 Google 账号或 Google OAuth。

还没有本站 Key 时，先按 [快速开始](https://docs.passion8.cc/docs/quickstart) 创建令牌，再选择下面的客户端。

## 选择你的使用方式

| 场景 | 推荐入口 | 配置 |
| --- | --- | --- |
| 在 VS Code 里读代码、改文件、审阅 diff | [Cline 编辑器配置](https://docs.passion8.cc/docs/gemini/vscode) | `https://passion8.cc/v1` + 本站 Key + 模型 |
| 在自己的应用中调用模型 | [Gemini API 与 SDK](https://docs.passion8.cc/docs/gemini/api) | 按原生或兼容协议选地址 |
| 已使用 Gemini CLI，继续终端工作流 | 本页下方 CLI 配置 | `https://passion8.cc` + 本站 Key + 模型 |
| 配置后不知道怎么完成项目任务 | [编程工作流](https://docs.passion8.cc/docs/gemini/workflow) | 分析、计划、修改与验收 |

### Gemini CLI 是不是已经换掉了

Google 已将个人免费层、Google AI Pro / Ultra 的 Gemini CLI 和 Code Assist IDE 登录服务于 **2026-06-18** 迁移至 Antigravity。官方公告同时保留付费 Gemini API Key 访问，CLI 配置文档仍支持自定义 `GOOGLE_GEMINI_BASE_URL`。

本站推荐新用户从 **Cline 编辑器** 或 **API** 开始；已有 API-key CLI 工作流的用户可继续参考下面配置。这里不要求 Google OAuth 或官方订阅，也不把 Antigravity 的账户流程作为本站接入步骤。

## Gemini CLI 安装与配置




本站使用 Passion8 API Key 接入。安装 Gemini CLI 后，选择手动配置或 CC Switch 配置供应商；无需把 Google OAuth 登录作为本站接入步骤。




## 目标：在自己的仓库完成一次可审查的小改动

本教程走通安装、鉴权、配置、项目上下文、任务执行与验收。CLI 是能读写文件并运行命令的工具；开始前进入目标仓库，先检查已有修改，避免把无关改动混入结果。

## 1. 安装并确认版本

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

Node.js 支持范围以官方安装页为准。`gemini --version` 应输出版本号；命令不存在时检查 npm 全局 bin 是否在 PATH。临时试用可以改用 `npx @google/gemini-cli`。团队应记录版本后再做升级。

## 2. 准备 Passion8 Key 与模型

在 [Passion8 控制台](https://passion8.cc) 创建 API Key，并复制账号可用的 Gemini 模型 ID。CLI 使用原生 Gemini 协议，因此根地址是 **`https://passion8.cc`**，不是 `https://passion8.cc/v1`，也不需要自行追加 `/gemini` 或 `/v1beta`。

## 3. 二选一：手动配置或 CC Switch

### 方式 A：手动配置

macOS / Linux 在准备启动 CLI 的终端设置：

```bash
export GEMINI_API_KEY="替换为你的-Passion8-Key"
export GOOGLE_GEMINI_BASE_URL="https://passion8.cc"
export GEMINI_MODEL="替换为控制台可用的-Gemini-模型-ID"
gemini --model "$GEMINI_MODEL"
```

Windows PowerShell 对应写法：

```powershell
$env:GEMINI_API_KEY="替换为你的-Passion8-Key"
$env:GOOGLE_GEMINI_BASE_URL="https://passion8.cc"
$env:GEMINI_MODEL="替换为控制台可用的-Gemini-模型-ID"
gemini --model $env:GEMINI_MODEL
```

如果 CLI 仍然打开 Google 登录，先退出 CLI，将以下字段合并到 `~/.gemini/settings.json`；不要覆盖已有 MCP 或其他设置。鉴权类型应为 `gemini-api-key`：

```json
{
  "security": { "auth": { "selectedType": "gemini-api-key" } },
  "general": { "defaultApprovalMode": "default" },
  "context": { "fileName": "GEMINI.md" }
}
```

### 保存配置，下次直接启动

创建并打开用户配置文件。macOS：

```bash
mkdir -p ~/.gemini
touch ~/.gemini/.env
open -e ~/.gemini/.env
```

Windows PowerShell：

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.gemini" | Out-Null
if (-not (Test-Path "$env:USERPROFILE\.gemini\.env")) {
  New-Item -ItemType File "$env:USERPROFILE\.gemini\.env" | Out-Null
}
notepad "$env:USERPROFILE\.gemini\.env"
```

把以下三行保存到文件中，用你的本站 Key 和实际模型 ID 替换占位值；已有同名变量时修改原行，不要重复追加：

```dotenv
GEMINI_API_KEY=替换为你的-Passion8-Key
GOOGLE_GEMINI_BASE_URL=https://passion8.cc
GEMINI_MODEL=替换为控制台可用的-Gemini-模型-ID
```

保存后退出旧 CLI，重新打开终端，运行 `gemini`。这是用户目录下的配置，不要把真实 Key 放入项目 Git 仓库。已有 shell、项目 `.env` 或项目 `.gemini/settings.json` 可能覆盖用户设置，切换供应商后应检查冲突。

### 方式 B：CC Switch

1. 从 [CC Switch 官方发布页](https://github.com/farion1231/cc-switch/releases) 安装桌面应用。
2. 进入 **Gemini CLI**，添加供应商，选择**自定义配置**；不要选择 Google Official。
3. 名称填写 `Passion8`，API Key 填本站 Key，端点填 `https://passion8.cc`，模型填控制台实际 ID。
4. 检查配置预览，保存并启用该供应商。第三方供应商使用 API key 鉴权。
5. 退出旧 CLI，重新打开终端或 Gemini CLI。此方式使用 Direct / 直连配置即可，不需要为原生 Gemini 入口开启协议转换。

配置预览中的核心字段应类似：

```json
{
  "env": {
    "GEMINI_API_KEY": "replace-with-your-Passion8-key",
    "GOOGLE_GEMINI_BASE_URL": "https://passion8.cc",
    "GEMINI_MODEL": "replace-with-an-enabled-Gemini-model-ID"
  }
}
```

手动方式和 CC Switch 任选一种作为配置来源。若之前 shell 中导出了旧 Key 或旧地址，先移除旧变量再重启，避免覆盖 CC Switch 写入的配置。

## 4. 先验证接入

重新启动 `gemini` 后，先输入：

```text
只回复 OK，不读取文件，不运行命令。
```

收到回答后，在 [Passion8 控制台](https://passion8.cc) 核对这次请求的时间、模型与用量记录。回答正常且本站有对应记录，才说明本次请求走了 Passion8。若出现 Google OAuth 登录，返回第 3 步检查 `gemini-api-key` 和旧配置；若报模型错误，核对本站开放的完整 ID。

## 进阶：配置项目上下文


在仓库根目录保存下面内容，再按项目实际情况补充明确的构建和测试命令。不要把示例的包管理器假设硬塞进非 Node 项目。

```markdown
# Project instructions

- Read package.json before choosing build or test commands.
- Use the package manager specified by the lockfile.
- Keep changes limited to the requested task.
- Do not edit generated files or commit credentials.
- After a change, run the relevant existing test and report the command/result.
- If a required command is absent, report it instead of inventing a successful run.
```

在 CLI 中执行 `/memory show` 检查实际加载内容；修改文件后执行 `/memory refresh`。若看不到文件，检查当前目录、文件名与上下文配置。

## 进阶：执行项目任务

先输入：“只读检查这个仓库，告诉我启动方式、测试入口和一个适合小改动的文件。不要修改文件。”确认理解正确后，输入具体任务，例如：“为现有字符串工具补一个已定义边界条件，沿用已有测试风格；完成后运行相关测试并解释差异。”

按提示审查文件修改和命令执行。完成后在自己的终端检查：

```bash
git diff --stat
git diff
git status --short
```

验收结果应该是与任务相符的 diff 和实际测试结果，而不是只有一段完成说明。没有测试命令的项目应明确记录未验证项。

## 常见问题

| 问题 | 定位步骤 |
| --- | --- |
| 登录后仍提示未授权 | 检查选中的鉴权方式与密钥所属服务，再重新启动 |
| 模型找不到 | 从 Passion8 控制台复制完整模型 ID，核对账号分组、权限与本站入口；更新 GEMINI_MODEL 后重启 |
| 不遵守项目说明 | 用 `/memory show` 确认文件实际被加载 |
| 频繁提出不相关改动 | 把任务约束写具体，审查 diff 后缩小任务 |
| 自定义入口返回 404 | 核对是否为原生 Gemini 协议及完整根地址，不能仅更换密钥 |

## 官方来源与核对

核对日期：2026-10-11

- [Gemini CLI 迁移公告与 API Key 保留说明](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/)
- [Code Assist 当前状态](https://developers.google.com/gemini-code-assist/docs/set-up-gemini)
- [Installation](https://geminicli.com/docs/get-started/installation/)
- [Authentication](https://geminicli.com/docs/get-started/authentication/)
- [Configuration](https://geminicli.com/docs/reference/configuration/)

- [CC Switch provider configuration](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/2-providers/2.1-add.md)