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

# Gemini CLI

> 通过 GravitexAI 使用 Gemini CLI 进行 AI 辅助编程，支持代码生成、代码审查、智能问答等

## 一、产品简介

**Gemini CLI** 是 Google 官方推出的命令行 AI 编程工具，允许你在终端中直接与 Gemini 系列模型交互。通过 **GravitexAI** 中转后，你可以：

<CardGroup cols={2}>
  <Card title="终端直接调用" icon="terminal">
    在终端中快速调用 Gemini 3.5 / 3.1 / 2.5 等模型
  </Card>

  <Card title="AI 辅助编程" icon="code">
    代码生成、代码审查、单元测试自动化
  </Card>

  <Card title="智能问答" icon="message-question">
    技术问题解答、架构设计、错误排查
  </Card>

  <Card title="文档生成" icon="file-lines">
    README、API 文档、JSDoc 注释自动生成
  </Card>
</CardGroup>

<Info>
  通过 **GravitexAI** 中转后，你可以享受国内优化网络、统一的 API Key 管理，以及与 Claude、GPT 等模型的一站式聚合接入。
</Info>

## 二、前置要求

* **Node.js** ≥ 18.0.0
* **npm** 或 **yarn** 包管理器
* 在 [GravitexAI 控制台](https://maas.gravitex.ai/#/keys) 获取的 API Key（格式如 `sk-xxxxxxxxxx`）

## 三、快速开始

### 第一步：安装 Gemini CLI

<CodeGroup>
  ```bash npm theme={null}
  node --version  # 需要 >= 18

  npm install -g @google/gemini-cli

  gemini --version
  ```

  ```bash yarn theme={null}
  node --version  # 需要 >= 18

  yarn global add @google/gemini-cli

  gemini --version
  ```
</CodeGroup>

### 第二步：获取 GravitexAI API Key

<Steps>
  <Step title="登录 GravitexAI 控制台">
    访问 [maas.gravitex.ai](https://maas.gravitex.ai) 注册或登录账号。
  </Step>

  <Step title="创建 API Key">
    进入「[密钥管理](https://maas.gravitex.ai/#/keys)」页面，点击「创建新令牌」。
  </Step>

  <Step title="复制密钥">
    复制生成的 API Key（格式：`sk-xxxxxxxxxx`），妥善保存。
  </Step>
</Steps>

### 第三步：配置环境变量

<Warning>
  **重要**：`GOOGLE_GEMINI_BASE_URL` 必须设置为 `https://api.gravitex.ai`，**不要**带上 `/v1`、`/gemini` 等多余路径，否则会导致连接失败。
</Warning>

<Tabs>
  <Tab title="Zsh (macOS / Linux)">
    ```bash theme={null}
    # 编辑 .zshrc 文件
    nano ~/.zshrc

    # 添加以下环境变量
    export GOOGLE_GEMINI_BASE_URL="https://api.gravitex.ai"
    export GEMINI_API_KEY="sk-your-gravitex-key"  # 替换为你的 GravitexAI 密钥

    # 保存后重新加载配置
    source ~/.zshrc
    ```
  </Tab>

  <Tab title="Bash (Linux)">
    ```bash theme={null}
    # 编辑 .bashrc 文件
    nano ~/.bashrc

    # 添加以下环境变量
    export GOOGLE_GEMINI_BASE_URL="https://api.gravitex.ai"
    export GEMINI_API_KEY="sk-your-gravitex-key"

    # 保存后重新加载配置
    source ~/.bashrc
    ```
  </Tab>

  <Tab title="PowerShell (Windows)">
    ```powershell theme={null}
    # 临时设置
    $env:GOOGLE_GEMINI_BASE_URL="https://api.gravitex.ai"
    $env:GEMINI_API_KEY="sk-your-gravitex-key"

    # 永久保存（推荐）
    [System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_BASE_URL', 'https://api.gravitex.ai', 'User')
    [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'sk-your-gravitex-key', 'User')
    ```
  </Tab>

  <Tab title="CMD (Windows)">
    ```cmd theme={null}
    :: 临时设置
    set GOOGLE_GEMINI_BASE_URL=https://api.gravitex.ai
    set GEMINI_API_KEY=sk-your-gravitex-key

    :: 永久保存（需管理员权限）
    setx GOOGLE_GEMINI_BASE_URL "https://api.gravitex.ai"
    setx GEMINI_API_KEY "sk-your-gravitex-key"
    ```
  </Tab>
</Tabs>

### 第四步：初始化与测试

<Steps>
  <Step title="启动 Gemini CLI">
    ```bash theme={null}
    gemini
    ```
  </Step>

  <Step title="首次认证">
    在交互界面输入：

    ```
    /auth
    ```

    选择 **Gemini API Key (AI Studio)**。
  </Step>

  <Step title="测试连接">
    ```bash theme={null}
    # 简单测试
    gemini "Hello, 测试连接是否正常"

    # 编程任务测试
    gemini "解释一下 React Hooks 的使用方法"
    gemini "编写一个 Python 函数计算斐波那契数列"
    ```
  </Step>
</Steps>

## 四、推荐模型（经 GravitexAI 使用）

GravitexAI 已对接最新的 Gemini 全系列模型，可在 CLI 中直接调用：

### Gemini 3.x 系列（推荐）

| 模型 ID                              | 适用场景          | 特点          |
| ---------------------------------- | ------------- | ----------- |
| **gemini-3.5-flash** ⭐             | 高吞吐对话、低延迟工具调用 | 最新快速版本，速度最优 |
| **gemini-3.1-pro-preview**         | 复杂推理、高质量代码生成  | 新一代核心智能模型   |
| **gemini-3.1-flash-lite-preview**  | 高并发批量任务       | 高性价比快速版本    |
| **gemini-3.1-flash-image-preview** | 图像理解 / 文生图    | 多模态增强版本     |
| **gemini-3-pro-image-preview**     | 高质量文生图        | 图像能力强化版本    |
| **gemini-3-flash-preview**         | 多轮对话、工具调用     | 平衡速度与质量     |

<Info>
  **推荐配置**：

  * 复杂编程任务、架构设计：**gemini-3.1-pro-preview**
  * 日常代码生成、问答：**gemini-3.5-flash**
  * 批量处理、快速迭代：**gemini-3.1-flash-lite-preview**
</Info>

完整模型列表请参见 [GravitexAI 模型广场](https://maas.gravitex.ai/#/models)。

## 五、核心功能

### 1. 代码生成

<Tabs>
  <Tab title="函数生成">
    ```bash theme={null}
    gemini "用 Python 写一个快速排序算法，包含详细注释"
    ```

    **输出示例**：

    ```python theme={null}
    def quick_sort(arr):
        """
        快速排序算法
        时间复杂度：平均 O(n log n)，最坏 O(n²)
        空间复杂度：O(log n)
        """
        if len(arr) <= 1:
            return arr

        pivot = arr[len(arr) // 2]
        left = [x for x in arr if x < pivot]
        middle = [x for x in arr if x == pivot]
        right = [x for x in arr if x > pivot]

        return quick_sort(left) + middle + quick_sort(right)
    ```
  </Tab>

  <Tab title="项目脚手架">
    ```bash theme={null}
    gemini "创建一个 Express.js REST API 项目结构，包含用户认证和数据库配置"
    ```
  </Tab>

  <Tab title="单元测试">
    ```bash theme={null}
    gemini "为以下函数编写 Jest 单元测试：
    function fibonacci(n) {
      if (n <= 1) return n;
      return fibonacci(n - 1) + fibonacci(n - 2);
    }"
    ```
  </Tab>
</Tabs>

### 2. 代码审查

```bash theme={null}
# 性能审查
gemini "审查以下代码的性能问题和潜在 bug：
[粘贴你的代码]"

# 安全审计
gemini "检查这段代码的安全漏洞，特别关注 SQL 注入和 XSS 攻击"

# 最佳实践建议
gemini "这段 React 组件有什么可以优化的地方？是否遵循最佳实践？"
```

### 3. 技术问答

```bash theme={null}
# 概念解释
gemini "解释一下 JavaScript 的闭包概念，并给出实际应用场景"

# 错误排查
gemini "为什么我的 Promise 没有被正确 resolve？"

# 架构设计
gemini "微服务架构和单体架构的优缺点对比"
```

### 4. 文档生成

```bash theme={null}
# 生成 README
gemini "为我的 Node.js 库生成专业的 README.md，包括安装、使用示例、API 文档"

# 生成 API 文档
gemini "为这个 REST API 端点生成 OpenAPI 3.0 规范文档"

# 添加代码注释
gemini "为以下代码添加详细的 JSDoc 注释"
```

## 六、交互式命令

在 Gemini CLI 交互模式下，可使用以下指令：

| 命令       | 说明      | 示例                              |
| -------- | ------- | ------------------------------- |
| `/auth`  | 重新认证    | `/auth`                         |
| `/model` | 切换模型    | `/model gemini-3.1-pro-preview` |
| `/clear` | 清除对话历史  | `/clear`                        |
| `/help`  | 显示帮助信息  | `/help`                         |
| `/exit`  | 退出 CLI  | `/exit` 或 `Ctrl+C`              |
| `/save`  | 保存对话到文件 | `/save conversation.txt`        |

<Tip>
  **模型切换**：使用 `/model` 命令可在不同模型之间快速切换。也可在启动时通过 `--model` 参数指定：

  ```bash theme={null}
  gemini --model gemini-3.1-pro-preview "你的问题"
  gemini --model gemini-3.5-flash "快速测试"
  ```
</Tip>

## 七、高级用法

### 1. GitHub Actions 集成（自动化代码审查）

```yaml theme={null}
name: Gemini Code Review
on:
  pull_request:
    branches: [ main ]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli

      - name: Run Code Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          GOOGLE_GEMINI_BASE_URL: https://api.gravitex.ai
        run: |
          gemini "审查这个 Pull Request 的代码质量、安全性和性能：
          $(git diff origin/main...HEAD)"
```

### 2. 批处理脚本

```bash theme={null}
#!/bin/bash

# 批量代码审查
for file in src/**/*.js; do
  echo "Reviewing $file..."
  gemini "审查文件 $file 的代码质量" < "$file"
done

# 生成项目文档
gemini "为整个项目生成技术文档大纲" < README.md
```

## 八、常见问题

<AccordionGroup>
  <Accordion title="连接失败或认证错误？">
    **检查清单**：

    1. **环境变量是否正确**：

       ```bash theme={null}
       echo $GOOGLE_GEMINI_BASE_URL
       echo $GEMINI_API_KEY
       ```

       确保输出为：

       * `GOOGLE_GEMINI_BASE_URL`: `https://api.gravitex.ai`（**不要**带 `/v1` 或其他路径）
       * `GEMINI_API_KEY`: 以 `sk-` 开头的完整密钥

    2. **重新加载环境变量**：
       ```bash theme={null}
       source ~/.zshrc  # 或 source ~/.bashrc
       ```

    3. **重启终端**：完全关闭并重新打开终端窗口。

    4. **验证 API Key**：登录 [GravitexAI 控制台](https://maas.gravitex.ai/#/keys) 确认 Key 是否有效且余额充足。
  </Accordion>

  <Accordion title="如何切换不同的 Gemini 模型？">
    **方式一：交互模式下使用 `/model` 命令**

    ```
    /model gemini-3.1-pro-preview
    /model gemini-3.5-flash
    ```

    **方式二：命令行直接指定**

    ```bash theme={null}
    gemini --model gemini-3.1-pro-preview "你的问题"
    gemini --model gemini-3.5-flash "快速测试"
    ```
  </Accordion>

  <Accordion title="如何保存对话历史？">
    **方法一**：使用 `/save` 命令

    ```
    /save conversation-2025-01-01.txt
    ```

    **方法二**：重定向输出

    ```bash theme={null}
    gemini "你的问题" > output.txt
    gemini "你的问题" | tee output.txt   # 同时显示和保存
    ```
  </Accordion>

  <Accordion title="Node.js 版本不满足要求怎么办？">
    **推荐使用 nvm 管理 Node.js 版本**：

    ```bash theme={null}
    # 安装 nvm
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

    # 安装 Node.js 18+
    nvm install 18
    nvm use 18
    nvm alias default 18

    node --version
    ```
  </Accordion>

  <Accordion title="为什么响应速度慢？">
    **可能原因和解决方案**：

    1. **网络问题**：GravitexAI 提供国内优化节点，正常情况下响应较快。可在 [GravitexAI 控制台](https://maas.gravitex.ai) 查看实时状态。
    2. **模型选择**：使用 `gemini-3.5-flash` 或 `gemini-3.1-flash-lite-preview` 可获得更快响应。
    3. **Token 限制**：减少单次请求的复杂度和上下文长度。

    **测试连接速度**：

    ```bash theme={null}
    time gemini --model gemini-3.5-flash "Hello"
    ```
  </Accordion>

  <Accordion title="如何在 Windows 上使用？">
    **推荐使用 PowerShell**：

    1. 从 [Node.js 官网](https://nodejs.org/) 下载并安装 Node.js
    2. 以**管理员**身份打开 PowerShell
    3. 设置环境变量：
       ```powershell theme={null}
       [System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_BASE_URL', 'https://api.gravitex.ai', 'User')
       [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'sk-your-key', 'User')
       ```
    4. **重启** PowerShell
    5. 运行 `npm install -g @google/gemini-cli` 安装

    或使用 **WSL**（Windows Subsystem for Linux）获得更接近原生的体验。
  </Accordion>
</AccordionGroup>

## 九、最佳实践

### 提示词优化

<CardGroup cols={2}>
  <Card title="明确具体" icon="bullseye">
    ❌ "优化这段代码"

    ✅ "优化这段代码的性能，重点关注循环效率和内存使用"
  </Card>

  <Card title="提供上下文" icon="book">
    ❌ "这个函数有什么问题？"

    ✅ "这是一个处理用户登录的函数，当前遇到异步错误，帮我找出问题"
  </Card>

  <Card title="分步骤请求" icon="list-ol">
    ❌ "帮我完成整个项目"

    ✅ "第一步：设计数据库模型；第二步：创建 API 路由；第三步：..."
  </Card>

  <Card title="要求示例" icon="code">
    ❌ "解释闭包"

    ✅ "解释 JavaScript 闭包，并给出 3 个实际应用场景和代码示例"
  </Card>
</CardGroup>

### 推荐工作流

<Steps>
  <Step title="问题定义">
    清晰描述要解决的问题或实现的功能。
  </Step>

  <Step title="获取方案">
    使用 Gemini CLI 生成初步解决方案或代码。
  </Step>

  <Step title="审查优化">
    要求 AI 审查自己生成的代码，找出潜在问题。
  </Step>

  <Step title="迭代改进">
    根据反馈逐步优化，直到满足需求。
  </Step>

  <Step title="文档补充">
    生成必要的注释和文档。
  </Step>
</Steps>

## 十、参考链接

* Gemini CLI 官方文档：[https://ai.google.dev/gemini-api/docs/cli](https://ai.google.dev/gemini-api/docs/cli)
* GravitexAI 控制台：[https://maas.gravitex.ai](https://maas.gravitex.ai)
* 模型广场：[https://maas.gravitex.ai/#/models](https://maas.gravitex.ai/#/models)
* 快速开始：[/cn/quickstart](/cn/quickstart)

<Tip>
  **快速上手**：按本文「快速开始」章节操作，5 分钟内即可完成配置并开始使用 Gemini CLI。
</Tip>