Gemini CLI 配置全攻略：接入 APINebula 实战教程

前言：为什么要用 Gemini CLI 配合第三方平台接入

Gemini CLI 是 Google 官方推出的命令行工具，让开发者能够直接在终端与 Gemini 模型进行交互，无需切换到浏览器或编写额外的脚本代码。对于习惯命令行工作流的开发者而言，这种方式效率极高，也更容易集成到自动化脚本和开发流程中。

从行业背景来看，Gemini CLI 是 Google 在 2025 年推出的开源命令行工具，基于 Gemini 2.5 Pro 模型构建，与 GitHub Copilot CLI、Anthropic 的 Claude Code 等工具属于同一赛道——命令行原生的 AI 助手。这类工具的核心优势在于可以直接读取本地文件系统、理解项目上下文，并且能通过管道（pipe）与其他命令行工具串联，融入 Unix 哲学下的工具链。Google 为 Gemini CLI 提供了每日 1000 次免费请求的额度（绑定个人 Google 账号），底层支持高达 100 万 token 的超长上下文窗口，这使其在处理大型代码库时具有显著优势。

然而，直接使用官方接口在国内环境下往往会遇到网络访问和账号门槛等问题。通过 APINebula 这样的第三方 API 聚合平台接入，可以用统一的令牌和服务器地址来调用 Gemini 模型，绕开常见的访问障碍，同时便于集中管理配额与费用。

这类第三方 API 聚合平台的技术本质是充当反向代理（Reverse Proxy）和 API 网关（API Gateway）。它们在海外部署中转服务器，将用户的请求转发到 Google、OpenAI、Anthropic 等原始 API 端点，再将响应返回给用户。这种架构解决了两个核心问题：一是网络可达性，平台在全球多个节点部署了中转服务，国内用户无需自行配置代理即可访问；二是账号与支付门槛，用户无需持有海外信用卡或通过 Google Cloud 的身份验证，只需在聚合平台注册并充值即可调用多家厂商的模型。从技术实现上看，这些平台通常兼容 OpenAI API 格式（即所谓的「OpenAI 兼容接口」），因此大多数支持自定义 API 端点的工具都可以无缝接入。

本文作为 APINebula 官方接入指南的第四期，专门讲解 Gemini CLI 的配置流程，涵盖 Windows 与 Mac 两大平台的完整步骤。整个过程可以概括为「安装 + 配置」两步走，掌握后即可在几分钟内完成接入。

Gemini CLI 安装：Windows 与 Mac 双平台指南

无论哪个平台，Gemini CLI 的安装都遵循「执行安装命令 + 验证版本号」的固定套路。

Windows 平台安装 Gemini CLI

在 Windows 上，打开终端后执行官方提供的安装命令，工具会自动拉取并安装最新版本的 Gemini CLI。安装完成后，再在终端执行版本查询命令，如果终端正常输出了版本号，就说明 Gemini CLI 已经安装成功。

这一验证环节非常重要——版本号能正常打印，意味着命令行工具已经被正确注册到系统的环境变量中，后续的调用才不会报「命令未找到」的错误。

Mac 平台安装 Gemini CLI

Mac 用户首先需要按下 Command + 空格 打开聚焦搜索（Spotlight），输入「终端」或「Terminal」并回车进入终端窗口。后续所有命令都在这个窗口中输入执行。

在终端里执行安装命令，工具会自动下载最新版本的 Gemini CLI。如果过程中遇到权限不足的情况，则需要输入带提权的命令，并按照提示输入系统密码完成安装。安装结束后，同样通过版本查询命令来验证——终端正常输出版本号即代表安装成功。

配置 .env 文件接入 APINebula

安装完成后，真正的接入核心在于配置。Gemini CLI 的主要配置信息保存在一个名为 .env 的文件中。

.env 文件是一种广泛使用的环境变量配置方式，最早由 Ruby 社区的 dotenv 库推广，后被 Node.js、Python 等生态广泛采纳。其格式为简单的 KEY=VALUE 键值对，每行一条。Gemini CLI 在启动时会读取配置目录下的 .env 文件，将其中的键值对加载为环境变量，从而覆盖默认的 API 端点、认证令牌和模型选择。这种设计的好处是将敏感信息（如 API Key）与代码分离，避免令牌泄露到版本控制系统中——这也是为什么 .gitignore 模板中几乎都会包含 .env 的原因。

进入 Gemini CLI 配置目录

在终端里执行进入配置目录的命令，该命令会自动创建（或进入）Gemini 的配置目录，并生成对应的 .env 文件，同时用记事本（或默认文本编辑器）打开它。Mac 与 Windows 的逻辑一致，只是命令实现略有差异。

.env 文件是 Gemini CLI 的主配置文件，所有关键的接入参数都写在这里。

填写三行关键配置参数

打开 .env 文件后，删除其中原有的所有内容，然后完整粘贴以下三行配置并保存：

• 第一行——服务器地址：这是 APINebula 提供的接入地址。如果后续官方更新了新的地址，可以在官网控制台的「数据看板」中查看，届时直接替换这一行即可。
• 第二行——API Key（令牌）：将此处替换为你在 APINebula 平台申请到的令牌。这是身份认证的核心凭据，务必妥善保管。
• 第三行——模型名称：填写当前分组下实际可用的 Gemini 模型名称。这里需要特别注意，模型名称必须与你创建 API Key 时所选择的分组相对应，不一定和演示画面里的名称完全一致，要以自己账号实际可用的分组为准。

分组与模型匹配的常见误区

这里是最容易出错的一个环节。很多用户直接照抄教程画面里的模型名称，结果调用时报错。原因在于：不同的 API Key 属于不同分组，每个分组能访问的模型集合并不相同。正确的做法是登录 APINebula 控制台，查看自己令牌所在分组下的可用模型列表，选取对应名称填入第三行。

从技术角度理解，APINebula 的「分组」机制本质上是一组路由规则，它定义了哪些模型名称可以被该分组下的 API Key 调用，以及每个模型请求实际被转发到哪个上游供应商。例如，一个名为「Gemini 高级组」的分组可能包含 gemini-2.5-pro、gemini-2.5-flash 等模型，而另一个「基础组」可能只包含 gemini-2.0-flash-lite。当你在 .env 文件中填写的模型名称不在当前 API Key 对应分组的可用列表中时，平台会返回 404 或 403 错误。这种设计借鉴了微服务架构中 API 网关的路由与鉴权模式，既实现了细粒度的访问控制，也方便平台按不同模型的成本差异进行差异化定价。

验证 Gemini CLI 配置是否成功

更换令牌并保存 .env 文件后，需要重新打开终端（让新的环境变量生效），然后执行 gemini 命令进入交互界面。需要注意的是，大多数 shell（如 bash、zsh、PowerShell）只在启动时读取一次环境配置，因此修改 .env 文件后必须重启终端才能使新配置生效。

进入交互界面后，随便输入一句话进行测试，如果 Gemini CLI 能够正常返回内容，就说明整个配置流程已经成功打通。

如果返回内容异常或报错，通常可以从以下三个方向排查：

1. 服务器地址：是否填写正确，有没有更新到最新地址；
2. API Key：令牌是否有效，账户是否还有可用额度；
3. 模型名称：是否与令牌所在的分组匹配。

这三点逐一排查完，绝大多数 Gemini CLI 配置问题都能得到解决。

总结：两步走完成 Gemini CLI 接入

回顾整个流程，Gemini CLI 接入 APINebula 的核心可以浓缩为两步：

1. 安装：执行安装命令 + 验证版本号；
2. 配置：编辑 .env 文件，填入服务器地址、API Key、模型名称三行参数，重启终端验证。

这套流程在 Windows 和 Mac 上高度一致，差异主要体现在终端的打开方式和安装命令的实现细节上。对于开发者来说，命令行接入方式不仅上手快，还便于后续集成到自动化脚本中，是提升 AI 工具使用效率的实用方案。

实际上，将 Gemini CLI 集成到自动化流程中可以解锁许多高级用法。例如，在 CI/CD 流水线中调用 Gemini CLI 对 Pull Request 进行代码审查，自动生成审查意见并写入评论；在 Shell 脚本中用管道将日志文件传入 Gemini CLI 进行异常分析；或者在 Makefile 中添加一个 target，让 AI 自动为新增代码生成单元测试。这种用法的关键在于 Gemini CLI 支持非交互模式（non-interactive mode），可以通过标准输入/输出与其他程序通信，完全符合 Unix 管道哲学。相比调用 REST API 编写 Python 脚本，命令行方式的启动成本更低、集成更灵活，特别适合 DevOps 工程师和全栈开发者的日常工作流。

掌握这一套配置逻辑后，无论平台如何更新地址或模型，你都能快速完成迁移和调整。