> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gogogotoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini CLI 配置

> 安装并配置 Gemini CLI 以使用 gogogotoken API

Gemini CLI 是 Google 官方提供的命令行 AI 助手。根据官方文档，Gemini CLI 支持通过 **Google 登录**、**Gemini API Key** 或 **Vertex AI** 完成认证；如果要接入 gogogotoken，推荐使用 **Gemini API Key + 自定义 Base URL**。

<Info>
  官方文档：[https://geminicli.com/docs/get-started/](https://geminicli.com/docs/get-started/)
</Info>

<Warning>
  Gemini CLI 的 Base URL 只填写根域名 `https://gogogotoken.ai`。不要手动追加 `/v1beta/models/...`，CLI 会按 Gemini API 格式自动拼接请求路径。
</Warning>

## 安装 Gemini CLI

官方推荐通过 `npm` 安装。安装前请先确认本机已安装 Node.js。

```bash theme={null}
node --version
npm --version
```

如果没有版本号输出，请先参考 [环境配置](/tools/environment-setup) 安装 Node.js。

<Tabs>
  <Tab title="全局安装">
    ```bash theme={null}
    npm install -g @google/gemini-cli
    ```

    安装完成后运行：

    ```bash theme={null}
    gemini
    ```
  </Tab>

  <Tab title="直接运行">
    如果不想全局安装，也可以使用 `npx` 直接启动：

    ```bash theme={null}
    npx @google/gemini-cli
    ```
  </Tab>
</Tabs>

## 认证方式选择

Gemini CLI 首次启动时会询问 `How would you like to authenticate for this project?`。官方文档中的常见方式如下：

| 方式                    | 适用场景                               | 是否需要 Google Cloud Project |
| --------------------- | ---------------------------------- | ------------------------- |
| `Sign in with Google` | 使用个人 Google 账号或订阅                  | 通常不需要，组织账号可能需要            |
| `Use Gemini API key`  | 使用 Gemini API Key 或第三方 Gemini 兼容网关 | 不需要                       |
| `Vertex AI`           | 使用 Google Cloud Vertex AI          | 需要                        |

<Tip>
  接入 gogogotoken 时，请选择 `Use Gemini API key`，并设置 `GOOGLE_GEMINI_BASE_URL`、`GEMINI_API_KEY` 与 `GEMINI_MODEL`。
</Tip>

## 配置 API

<Steps>
  <Step title="创建 API Key">
    进入控制台的 [令牌管理](/billing/api-key-management)，创建一个用于 Gemini CLI 的令牌。

    建议为 Gemini CLI 单独创建令牌，方便后续统计用量和排查问题。
  </Step>

  <Step title="找到 Gemini 的配置文件夹">
    安装并运行过 Gemini CLI 后，配置文件夹会自动生成。打开终端程序，根据不同系统，运行下面的命令，打开 Gemini 的配置文件夹。

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        open "$HOME/.gemini"
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        explorer "$env:USERPROFILE\.gemini"
        ```
      </Tab>

      <Tab title="Windows CMD">
        ```batch theme={null}
        start "" "%USERPROFILE%\.gemini"
        ```
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        xdg-open "$HOME/.gemini"
        ```
      </Tab>

      <Tab title="WSL2">
        ```bash theme={null}
        explorer.exe "$(wslpath -w "$HOME/.gemini")"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="手动创建 .env 文件">
    在刚打开的 `.gemini` 文件夹中，手动创建一个名为 `.env` 的文件，并写入如下内容：

    ```text theme={null}
    GOOGLE_GEMINI_BASE_URL="https://gogogotoken.ai"
    GEMINI_API_KEY="YOUR_API_KEY"
    GEMINI_MODEL="gemini-2.5-flash"
    ```

    将 `YOUR_API_KEY` 替换为你在令牌管理中创建的 API Key。

    <Note>
      文件名必须是 `.env`，不要保存成 `.env.txt`。Windows 如果看不到扩展名，建议先在文件管理器中开启“文件扩展名”显示。
    </Note>
  </Step>

  <Step title="命令行临时配置">
    如果你只想在当前终端临时测试，也可以直接设置环境变量。

    <Tabs>
      <Tab title="macOS / Linux / WSL2">
        ```bash theme={null}
        export GOOGLE_GEMINI_BASE_URL="https://gogogotoken.ai"
        export GEMINI_API_KEY="YOUR_API_KEY"
        export GEMINI_MODEL="gemini-2.5-flash"
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        $env:GOOGLE_GEMINI_BASE_URL="https://gogogotoken.ai"
        $env:GEMINI_API_KEY="YOUR_API_KEY"
        $env:GEMINI_MODEL="gemini-2.5-flash"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="启动并选择认证方式">
    运行 Gemini CLI：

    ```bash theme={null}
    gemini
    ```

    首次启动时选择 `Use Gemini API key`。如果之前已经登录过其他账号，可以在 Gemini CLI 中输入 `/auth` 重新选择认证方式。
  </Step>

  <Step title="验证连通性">
    在 Gemini CLI 中发送一个简单请求：

    ```text theme={null}
    Explain this project in three bullet points.
    ```

    如果能正常返回内容，说明 Gemini CLI 已通过 gogogotoken 发起请求。
  </Step>
</Steps>

## 持久化环境变量

Gemini CLI 会自动读取 `.gemini/.env`。如果你把 `.env` 放在用户目录的 `.gemini` 文件夹中，它会作为用户级配置生效；如果放在某个项目的 `.gemini` 文件夹中，则只对该项目生效。

<Warning>
  API Key 属于敏感凭据。请不要把包含密钥的 `.env` 文件提交到 Git。
</Warning>

## 使用 CC Switch 导入 Gemini CLI 配置

如果你已经安装 [CC Switch](/tools/cc-switch)，也可以通过图形界面把 gogogotoken 的 Gemini CLI 配置写入本地环境，减少手动编辑 `.env` 的出错概率。

<Steps>
  <Step title="在令牌管理中选择对应令牌并打开 CC Switch">
    安装好 `CC Switch` 之后，进入控制台的 [令牌管理](/billing/api-key-management)，找到你准备给 `Gemini CLI` 使用的令牌。

    然后点击该令牌右侧的 `聊天` 下拉菜单，选择 `CC Switch`，系统会唤起本地的配置导入流程。

    <Frame>
      <img src="https://mintcdn.com/gogogotoken/SVoSxOqdlEcGU5Ly/images/codex/codex-cc-switch-enabled.png?fit=max&auto=format&n=SVoSxOqdlEcGU5Ly&q=85&s=256e7be2a25d0ecd92cbe24ac7efb3e3" alt="令牌管理中选择 CC Switch" width="3004" height="1410" data-path="images/codex/codex-cc-switch-enabled.png" />
    </Frame>
  </Step>

  <Step title="选择导入目标为 Gemini CLI">
    在弹出的导入窗口中，把应用目标切换为 `Gemini CLI`。

    确认下面三项配置无误后，点击 `打开 CC Switch`：

    * `GOOGLE_GEMINI_BASE_URL`: `https://gogogotoken.ai`
    * `GEMINI_API_KEY`: 当前令牌
    * `GEMINI_MODEL`: `gemini-2.5-flash`

    <Frame>
      <img src="https://mintcdn.com/gogogotoken/SVoSxOqdlEcGU5Ly/images/gemini-cli/user-attachment-6.png?fit=max&auto=format&n=SVoSxOqdlEcGU5Ly&q=85&s=73182daf7cb1ece66449c77747cdcdd8" alt="选择 Gemini CLI 和模型" width="1108" height="816" data-path="images/gemini-cli/user-attachment-6.png" />
    </Frame>
  </Step>

  <Step title="在 CC Switch 中确认 Gemini CLI 已启用">
    导入完成后，切换到 `CC Switch` 顶部的 `Gemini CLI` 图标页签。

    如果配置成功，你会看到刚导入的供应商出现在列表中，并显示为 `使用中`。这说明 `Gemini CLI` 已经切换到当前配置。

    <Frame>
      <img src="https://mintcdn.com/gogogotoken/SVoSxOqdlEcGU5Ly/images/gemini-cli/user-attachment-7.png?fit=max&auto=format&n=SVoSxOqdlEcGU5Ly&q=85&s=be904dafb8625d9040514dc931848585" alt="确认 Gemini CLI Provider 已启用" width="2000" height="1300" data-path="images/gemini-cli/user-attachment-7.png" />
    </Frame>
  </Step>

  <Step title="在 Gemini CLI 中验证配置">
    重启 Gemini CLI，然后发送一次简单请求：

    ```bash theme={null}
    gemini -p "Say hello in one sentence."
    ```

    如果能正常返回内容，说明 Gemini CLI 已通过 CC Switch 写入的配置访问 gogogotoken。

    <Frame>
      <img src="https://mintcdn.com/gogogotoken/SVoSxOqdlEcGU5Ly/images/gemini-cli/user-attachment-8.png?fit=max&auto=format&n=SVoSxOqdlEcGU5Ly&q=85&s=9fbdda78826f77e9abb9f1d63920c429" alt="Gemini CLI 当前模型验证" width="1140" height="976" data-path="images/gemini-cli/user-attachment-8.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  无论你是手动修改 `.env`，还是通过 `CC Switch` 切换供应商，只要改动了 Base URL、API Key 或模型，都建议重启 Gemini CLI 后再测试。
</Warning>

## 故障排查

| 现象               | 可能原因                           | 处理方式                                                        |
| ---------------- | ------------------------------ | ----------------------------------------------------------- |
| 启动后仍要求 Google 登录 | 未选择 `Use Gemini API key`       | 输入 `/auth` 重新选择认证方式                                         |
| `401/403`        | Key 无效，或令牌分组不包含目标模型            | 检查 API Key 与模型权限                                            |
| `404`            | Base URL 写入了多余路径               | 确认只设置 `https://gogogotoken.ai`                              |
| 模型不符合预期          | 未设置 `GEMINI_MODEL`，或当前会话仍使用旧配置 | 设置控制台可用的 `GEMINI_MODEL`（如 `gemini-2.5-flash`）后重启 Gemini CLI |
| `429`            | 触发限速或额度不足                      | 在控制台检查套餐、余额和限流策略                                            |
| 无法读取 `.env`      | 文件位置不符合 Gemini CLI 查找规则        | 使用 `~/.gemini/.env` 或当前项目的 `.gemini/.env`                   |

<Tip>
  如果你修改了 API Key、Base URL、模型或认证方式，建议退出并重新启动 Gemini CLI，再进行测试。
</Tip>