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

# Gemini CLI

> 将 Gemini CLI 连接到 AihubMax

## 概述

[Gemini CLI](https://github.com/google-gemini/gemini-cli) 是 Google 推出的开源命令行 AI 工具，可让你在终端中直接与 Gemini 模型交互，进行代码理解、生成和编辑等操作。

通过将 Gemini CLI 连接到 AihubMax，你可以使用 AihubMax 提供的 Gemini 系列模型。

<Warning>
  Gemini CLI 不支持通过配置文件自定义 Base URL。配置需要修改安装包内的源文件。更新包后需要重新修改。
</Warning>

## 前置条件

<CardGroup cols={2}>
  <Card title="AihubMax API Key" icon="key">
    一个有效的 AihubMax API Key，并确保有权限访问 Gemini 模型。[前往 AihubMax →](https://api.aihubmax.com/console)
  </Card>

  <Card title="Node.js 20+" icon="node-js">
    安装 Gemini CLI 需要 Node.js v20 或更高版本以及 npm。[下载 Node.js →](https://nodejs.org/zh-cn/download/)
  </Card>
</CardGroup>

## 安装与配置

<Steps>
  <Step title="第一步：安装 Gemini CLI">
    ```bash theme={null}
    npm install -g @google/gemini-cli
    ```
  </Step>

  <Step title="第二步：设置 API Key">
    在配置环境变量前，先前往 [AihubMax 控制台](https://api.aihubmax.com/console) 创建专用密钥：

    1. 打开「API 密钥」页面并点击「创建密钥」。
    2. 将密钥名称标记为「Gemini CLI」或其他易识别的名字。
    3. **分组务必选择「Gemini\_CLI」**，该分组启用了 Gemini 协议所需的额外转码与速率额度。

    <Warning>
      如果没有选择「Gemini\_CLI」分组，Gemini CLI 可能无法正常调用 AihubMax 的 Gemini 模型，或出现 403/429 报错。
    </Warning>

    生成密钥后，将其写入环境变量 `GEMINI_API_KEY`。下面两种方式二选一：使用 **CC-Switch** 自动注入，或手动在 Shell 配置文件中导出环境变量。

    <Tabs>
      <Tab title="CC-Switch（推荐）">
        1. 从 [GitHub Releases](https://github.com/farion1231/cc-switch/releases) 下载与你系统匹配的安装包并安装。
        2. 在 CC-Switch 中新增一个「Gemini CLI」配置，Base URL 保持默认的 `https://api.aihubmax.com`，认证方式选择「自定义 Header」。
        3. 回到 AihubMax 密钥列表，点击目标密钥右侧的 **「导入到 CCS」**，并选择刚才的配置。

        ![通过 AihubMax 一键导入 Gemini CLI 配置](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260329003930220.png)

        通过 CC-Switch 启动终端后，工具会在当前 Shell 中自动注入 `GEMINI_API_KEY`，无需手动导出。
      </Tab>

      <Tab title="macOS / Linux">
        ```bash theme={null}
        export GEMINI_API_KEY="sk-your-foxapi-api-key"
        ```

        然后重新加载配置：

        ```bash theme={null}
        source ~/.zshrc  # 或 source ~/.bashrc
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        [Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "sk-your-foxapi-api-key", "User")
        ```

        设置后请重新启动 PowerShell。
      </Tab>
    </Tabs>
  </Step>

  <Step title="第三步：修改 Base URL">
    <Tip>
      CC-Switch 仅负责注入 `GEMINI_API_KEY`，并不会替你修改 CLI 安装目录内的 Base URL 配置，因此无论上一阶段选择哪种方式，以下修改都必须执行一次。
    </Tip>

    Gemini CLI 不支持通过配置文件自定义 Base URL，需要直接修改安装包内的两个源文件。

    首先，找到 npm 全局安装目录：

    ```bash theme={null}
    npm root -g
    ```

    如果你已经克隆了这份文档仓库，也可以直接运行仓库内的辅助脚本自动完成替换：

    ```bash theme={null}
    bash 101.api_docs/mintlify/ai-tools/patch-gemini-cli-base-url.sh
    ```

    该脚本会自动定位全局安装目录、修改 `index.mjs` 和 `index.cjs`，并为原文件生成 `.foxapi.bak` 备份。

    然后修改以下两个文件：

    **文件 1：** `{install_dir}/@google/gemini-cli/node_modules/@google/genai/dist/node/index.mjs`（约第 11222 行）

    **文件 2：** `{install_dir}/@google/gemini-cli/node_modules/@google/genai/dist/node/index.cjs`（约第 11244 行）

    在两个文件中，找到并替换：

    ```js theme={null}
    // 修改前：
    initHttpOptions.baseUrl = `https://generativelanguage.googleapis.com/`;

    // 修改后：
    initHttpOptions.baseUrl = `https://api.aihubmax.com/`;
    ```

    <Tip>
      在 macOS/Linux 上，你可以使用 `sed` 命令快速替换：

      ```bash theme={null}
      INSTALL_DIR=$(npm root -g)
      sed -i.bak 's|https://generativelanguage.googleapis.com/|https://api.aihubmax.com/|g' \
        "$INSTALL_DIR/@google/gemini-cli/node_modules/@google/genai/dist/node/index.mjs" \
        "$INSTALL_DIR/@google/gemini-cli/node_modules/@google/genai/dist/node/index.cjs"
      ```
    </Tip>

    <Warning>
      更新 Gemini CLI（`npm update -g @google/gemini-cli`）后，源文件会被覆盖，需要重新执行此修改。
    </Warning>
  </Step>

  <Step title="第四步：开始使用">
    在你的项目目录中启动 Gemini CLI：

    ```bash theme={null}
    cd /path/to/your/project
    gemini
    ```

    或运行单次命令：

    ```bash theme={null}
    gemini "解释一下这个项目的架构"
    ```

    在交互模式中，输入 `/model` 可以切换模型。
  </Step>
</Steps>

## 验证连接

运行以下命令验证配置是否正确：

```bash theme={null}
gemini "你好，请确认你正在正常工作。"
```

如果配置正确，Gemini 将通过 AihubMax 返回回复。

## 可用模型

| 模型                       | 说明                    |
| ------------------------ | --------------------- |
| `gemini-2.5-pro`         | 最强大的 Gemini 模型，适合复杂任务 |
| `gemini-2.5-flash`       | 快速高效，适合日常编程辅助         |
| `gemini-3-pro-preview`   | 下一代 Gemini Pro 预览版    |
| `gemini-3-flash-preview` | 下一代 Gemini Flash 预览版  |

## 常见问题

<AccordionGroup>
  <Accordion title="错误：认证失败">
    * 确认 `GEMINI_API_KEY` 环境变量已正确设置，且值为你的 AihubMax API Key（以 `sk-` 开头）。
    * 确认 Key 未过期且账户余额充足。
    * 确认该 Key 有权限访问 Gemini 模型。
  </Accordion>

  <Accordion title="错误：连接失败或超时">
    * 确认 Base URL 修改已在**两个文件**（`index.mjs` 和 `index.cjs`）中正确应用。
    * 检查网络连接，确保能访问 `api.aihubmax.com`。
    * 如果所在地区有网络限制，尝试使用 VPN。
  </Accordion>

  <Accordion title="更新后修改丢失">
    * 运行 `npm update -g @google/gemini-cli` 后，源文件会被覆盖。
    * 需要重新按照第三步的方法修改 Base URL。
  </Accordion>

  <Accordion title="模型未找到">
    * 确认模型名称正确且在 AihubMax 上可用。
    * 在交互模式中使用 `/model` 命令切换不同模型。
  </Accordion>
</AccordionGroup>