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 的超长上下文窗口，这使其在处理大型代码库时具有显著优势。值得一提的是，100 万 token 的上下文窗口意味着 Gemini CLI 可以一次性「读懂」约 70 万字的文本内容，这大致相当于 10-15 本技术书籍的体量，或者一个包含数百个文件的中大型代码仓库。相比之下，GPT-4 Turbo 的上下文窗口为 12.8 万 token，Claude 3.5 Sonnet 为 20 万 token。这种量级的差异意味着 Gemini CLI 在分析整个微服务架构的代码库、审查跨模块的依赖关系时，可以将所有相关文件一次性加载进上下文，而不需要像其他工具那样分批处理或依赖 RAG（检索增强生成）等外部机制来弥补上下文长度的不足。

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

这类第三方 API 聚合平台的技术本质是充当反向代理（Reverse Proxy）和 API 网关（API Gateway）。反向代理是一种服务器架构模式，与我们日常所说的「正向代理」（如 VPN、SOCKS 代理）方向相反——正向代理是客户端主动配置的出口中转，而反向代理部署在服务端一侧，客户端甚至无需感知中转的存在。在这个场景中，聚合平台在海外部署中转服务器，将用户的请求转发到 Google、OpenAI、Anthropic 等原始 API 端点，再将响应返回给用户。API 网关则是在反向代理基础上增加了认证鉴权、流量控制、请求路由和日志审计等能力，是微服务架构中的标准基础设施组件，常见的开源实现包括 Kong、APISIX 和 Envoy 等。这种架构解决了两个核心问题：一是网络可达性，平台在全球多个节点部署了中转服务，国内用户无需自行配置代理即可访问；二是账号与支付门槛，用户无需持有海外信用卡或通过 Google Cloud 的身份验证，只需在聚合平台注册并充值即可调用多家厂商的模型。从技术实现上看，这些平台通常兼容 OpenAI API 格式（即所谓的「OpenAI 兼容接口」）。这一格式之所以成为事实标准，是因为 OpenAI 最早定义了 /v1/chat/completions 这套 RESTful API 规范，后来几乎所有 AI 工具和框架（如 LangChain、LlamaIndex、各类 IDE 插件）都优先支持了这一格式，因此其他模型提供商和聚合平台纷纷选择兼容此格式以降低开发者的迁移成本。这意味着大多数支持自定义 API 端点的工具都可以无缝接入。

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

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

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

Windows 平台安装 Gemini CLI

在 Windows 上，打开终端后执行官方提供的安装命令，工具会自动拉取并安装最新版本的 Gemini CLI。Gemini CLI 基于 Node.js 构建，因此安装过程实际上是通过 npm（Node Package Manager）从注册表拉取包文件。如果你的系统尚未安装 Node.js，需要先前往 nodejs.org 下载 LTS（长期支持）版本并安装——建议选择 18.x 或更高版本，因为 Gemini CLI 依赖较新的 Node.js 运行时特性。安装完成后，再在终端执行版本查询命令，如果终端正常输出了版本号，就说明 Gemini CLI 已经安装成功。

这一验证环节非常重要——版本号能正常打印，意味着命令行工具已经被正确注册到系统的环境变量（即 PATH 变量）中，后续的调用才不会报「命令未找到」的错误。PATH 是操作系统用来查找可执行文件的目录列表，当你在终端输入一个命令时，系统会按照 PATH 中列出的目录逐一查找对应的可执行文件。npm 全局安装的包通常会被放置在 PATH 已包含的目录中，但在某些 Windows 配置下（特别是使用 nvm 等 Node 版本管理工具时），可能需要手动确认 PATH 设置是否正确。

Mac 平台安装 Gemini CLI

Mac 用户首先需要按下 Command + 空格 打开聚焦搜索（Spotlight），输入「终端」或「Terminal」并回车进入终端窗口。后续所有命令都在这个窗口中输入执行。macOS 自带的终端默认使用 zsh（Z Shell）作为 shell 环境——这是从 macOS Catalina（10.15）开始的变化，之前的默认 shell 是 bash。两者在基本使用上差异不大，但配置文件不同：zsh 使用 ~/.zshrc，bash 使用 ~/.bashrc 或 ~/.bash_profile，这在后续排查环境变量问题时可能会用到。

在终端里执行安装命令，工具会自动下载最新版本的 Gemini CLI。如果过程中遇到权限不足的情况（通常表现为 EACCES 错误），则需要输入带提权的命令（即在命令前加 sudo），并按照提示输入系统密码完成安装。sudo 是 Unix/Linux 系统中的超级用户权限提升命令，它允许普通用户以管理员身份执行单条命令，而不需要切换到 root 账户。安装结束后，同样通过版本查询命令来验证——终端正常输出版本号即代表安装成功。

配置 .env 文件接入 APINebula

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

.env 文件是一种广泛使用的环境变量配置方式，最早由 Ruby 社区的 dotenv 库在 2012 年左右推广，后被 Node.js（dotenv 包，npm 周下载量超过 3000 万次）、Python（python-dotenv）、PHP（vlucas/phpdotenv）等生态广泛采纳，已成为现代软件开发中管理配置的事实标准之一。其格式为简单的 KEY=VALUE 键值对，每行一条，以 # 开头的行为注释。Gemini CLI 在启动时会读取配置目录下的 .env 文件，将其中的键值对加载为环境变量，从而覆盖默认的 API 端点、认证令牌和模型选择。这种设计的好处是将敏感信息（如 API Key）与代码分离，避免令牌泄露到版本控制系统中——这也是为什么 .gitignore 模板中几乎都会包含 .env 的原因。这一实践源自「十二要素应用」（The Twelve-Factor App）方法论中的第三条原则：「在环境中存储配置」，即应用的配置应通过环境变量注入，而非硬编码在源代码中。

进入 Gemini CLI 配置目录

在终端里执行进入配置目录的命令，该命令会自动创建（或进入）Gemini 的配置目录，并生成对应的 .env 文件，同时用记事本（或默认文本编辑器）打开它。Mac 与 Windows 的逻辑一致，只是命令实现略有差异。在 Windows 上，配置目录通常位于 %APPDATA%\gemini 路径下（即 C:\Users\用户名\AppData\Roaming\gemini）；在 macOS/Linux 上，则遵循 XDG Base Directory 规范，通常位于 ~/.config/gemini 目录。了解这些路径在排查问题时很有帮助——如果你不确定 .env 文件是否被正确读取，可以直接到这些目录下确认文件是否存在及内容是否正确。

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

填写三行关键配置参数

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

• 第一行——服务器地址（GEMINI_API_BASE 或类似键名）：这是 APINebula 提供的接入地址，本质上是 API 网关的入口 URL。它替代了 Google 官方的 https://generativelanguage.googleapis.com 端点，让所有请求通过 APINebula 的中转服务器转发。如果后续官方更新了新的地址（例如因为域名变更或节点迁移），可以在官网控制台的「数据看板」中查看，届时直接替换这一行即可。
• 第二行——API Key（令牌）：将此处替换为你在 APINebula 平台申请到的令牌。这是身份认证的核心凭据，务必妥善保管。API Key 的安全性至关重要：不要将其提交到 GitHub 等公开仓库，不要在聊天工具中明文传输，也不要截图分享。如果怀疑令牌泄露，应立即在 APINebula 控制台重新生成新的 Key 并废弃旧的。
• 第三行——模型名称（GEMINI_MODEL 或类似键名）：填写当前分组下实际可用的 Gemini 模型名称。常见的 Gemini 模型包括 gemini-2.5-pro（最强推理能力）、gemini-2.5-flash（速度与质量的平衡）、gemini-2.0-flash-lite（轻量快速）等。这里需要特别注意，模型名称必须与你创建 API Key 时所选择的分组相对应，不一定和演示画面里的名称完全一致，要以自己账号实际可用的分组为准。

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

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

从技术角度理解，APINebula 的「分组」机制本质上是一组路由规则，它定义了哪些模型名称可以被该分组下的 API Key 调用，以及每个模型请求实际被转发到哪个上游供应商。这种设计在 API 网关领域被称为「路由表」（Routing Table），类似于网络路由器根据目的地 IP 选择转发端口的逻辑。例如，一个名为「Gemini 高级组」的分组可能包含 gemini-2.5-pro、gemini-2.5-flash 等模型，并且这些请求被路由到 Google 的美西节点；而另一个「基础组」可能只包含 gemini-2.0-flash-lite，请求被路由到成本更低的节点。当你在 .env 文件中填写的模型名称不在当前 API Key 对应分组的可用列表中时，平台会返回 404（资源不存在）或 403（权限不足）错误。这种设计借鉴了微服务架构中 API 网关的路由与鉴权模式，既实现了细粒度的访问控制（RBAC，基于角色的访问控制），也方便平台按不同模型的成本差异进行差异化定价——毕竟 gemini-2.5-pro 的推理成本远高于 gemini-2.0-flash-lite，分组机制确保了不同付费层级的用户只能访问对应成本的模型。

验证 Gemini CLI 配置是否成功

更换令牌并保存 .env 文件后，需要重新打开终端（让新的环境变量生效），然后执行 gemini 命令进入交互界面。需要注意的是，大多数 shell（如 bash、zsh、PowerShell）只在启动时读取一次环境配置，因此修改 .env 文件后必须重启终端才能使新配置生效。这是因为 shell 进程在启动时会执行一系列初始化脚本（如 .bashrc、.zshrc、$PROFILE），并将环境变量加载到进程的内存空间中。之后进程运行期间，环境变量表不会自动刷新。Gemini CLI 作为 shell 的子进程，继承的是父进程（即当前终端会话）启动时的环境变量快照。因此，即使你修改了 .env 文件，已经运行的终端会话中的 Gemini CLI 仍然会使用旧的配置值。唯一的例外是某些工具（如 direnv）可以在切换目录时自动重新加载 .env 文件，但 Gemini CLI 默认不依赖此机制，所以最可靠的方式就是关闭当前终端窗口并重新打开一个。

进入交互界面后，随便输入一句话进行测试，如果 Gemini CLI 能够正常返回内容，就说明整个配置流程已经成功打通。建议首次测试时使用简单的问题（如「你好，请介绍一下自己」），这样可以快速确认连接是否正常，而不会因为复杂提示词导致的超时或内容过滤等问题干扰判断。

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

1. 服务器地址：是否填写正确，有没有更新到最新地址。常见错误包括地址末尾多了斜杠 /、协议头 https:// 被遗漏、或者复制时混入了不可见的空格字符；
2. API Key：令牌是否有效，账户是否还有可用额度。可以通过 APINebula 控制台的「数据看板」查看令牌状态和剩余配额；
3. 模型名称：是否与令牌所在的分组匹配。如果不确定，回到控制台的分组管理页面逐一确认。

这三点逐一排查完，绝大多数 Gemini CLI 配置问题都能得到解决。如果仍然无法正常使用，可以尝试在终端中设置 DEBUG=true 环境变量运行 Gemini CLI，查看详细的请求日志，确认请求是否成功发送到了正确的端点。

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

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

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

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

实际上，将 Gemini CLI 集成到自动化流程中可以解锁许多高级用法。例如，在 CI/CD 流水线（如 GitHub Actions、GitLab CI、Jenkins）中调用 Gemini CLI 对 Pull Request 进行代码审查，自动生成审查意见并通过 API 写入 PR 评论区；在 Shell 脚本中用管道将日志文件传入 Gemini CLI 进行异常分析，比如 cat error.log | gemini "分析这些错误日志，找出根因"；或者在 Makefile 中添加一个 test-gen target，让 AI 自动为新增代码生成单元测试框架。更进一步，还可以结合 watch 命令实现文件变更的实时监控与 AI 分析，或者使用 cron 定时任务让 Gemini CLI 每天自动总结服务器运行状态。这种用法的关键在于 Gemini CLI 支持非交互模式（non-interactive mode），可以通过标准输入（stdin）接收内容、通过标准输出（stdout）返回结果，并以合适的退出码（exit code）表示执行状态，完全符合 Unix 管道哲学中「做好一件事，并能与其他工具组合」的设计原则。相比调用 REST API 编写 Python 脚本（需要处理 HTTP 请求库、JSON 解析、错误重试等样板代码），命令行方式的启动成本更低、集成更灵活，特别适合 DevOps 工程师和全栈开发者的日常工作流。

掌握这一套配置逻辑后，无论平台如何更新地址或模型，你都能快速完成迁移和调整。配置的本质始终是三个要素：请求发往哪里（服务器地址）、以谁的身份发送（API Key）、调用哪个模型（模型名称），理解了这个框架，面对任何 AI CLI 工具的接入配置都能触类旁通。