Gemini CLI 配置 API 密钥教程：免费使用 Gemini 3 模型

为什么需要配置 API 密钥

Gemini CLI 中的 Gemini 3 模型目前只对两类用户开放：AI Ultra 付费会员（英国地区约每月 120 英镑），以及通过 API 密钥认证的用户（也支持 Vertex API 密钥）。虽然 Google 未来可能向所有标准账户开放 Gemini 3，但免费使用大概率会附带额度限制。

API 密钥（API Key）是一种常见的身份认证和授权机制，广泛应用于云服务和开发者平台中。它本质上是一串由服务提供商生成的唯一字符串，用于标识调用者身份并追踪其 API 使用量。与 OAuth 等基于令牌的认证方式不同，API 密钥通常直接嵌入请求头或 URL 参数中，使用起来更为简便，但安全性要求也更高——一旦泄露，任何持有该密钥的人都可以冒充你发起请求。Google 的 API 密钥体系与其 Cloud 项目紧密绑定，每个密钥都关联到特定项目，从而实现精细化的用量监控和计费管理。

配置 API 密钥的核心优势在于：你可以完全掌控自己的使用量，不受免费额度的约束。此外，未来的新模型或其他服务（如图像生成）同样可能需要 API 密钥认证，尽早掌握这一配置方法很有必要。

关于 Vertex API 密钥的补充说明：Vertex AI 是 Google Cloud 的企业级机器学习平台，提供更完善的安全控制、VPC 网络隔离、IAM 权限管理和合规审计功能。通过 Vertex AI 访问 Gemini 模型时，认证方式通常基于服务账户（Service Account）和 OAuth 2.0，而非简单的 API 密钥。对于个人开发者和学习用途，AI Studio 的 API 密钥已经足够；但对于企业生产环境，Vertex AI 提供了更高级别的安全保障和更灵活的部署选项，包括数据驻留（Data Residency）控制和私有端点（Private Endpoint）支持。

如果你目前只需要使用 Gemini 2.5 模型，可以暂时跳过这一步。但对于想要体验 Gemini 3 的用户，下面是完整的 Gemini CLI API 密钥配置流程。

在 Google AI Studio 创建 API 密钥

登录 Google AI Studio

首先访问 aistudio.google.com，使用你的 Google 账户登录。Google AI Studio 是 Google 面向开发者推出的一站式 AI 开发平台，定位介于消费级产品（如 Gemini 聊天应用）和企业级平台（如 Vertex AI）之间。它提供了可视化的模型交互界面、Prompt 工程工具、以及 API 密钥管理功能。除了像 ChatGPT 那样与 Gemini 模型对话，AI Studio 还支持 Vibe Coding 构建应用——这是一项允许用户通过自然语言描述来快速生成应用原型的特色功能，大幅降低了编程门槛。更关键的是，你可以在这里生成 API 密钥，用于 Gemini CLI 的认证。相比直接使用 Google Cloud Console，AI Studio 的界面更加友好，特别适合个人开发者和小型团队快速上手 Gemini 系列模型。

Google AI Studio 界面

创建项目并关联密钥

在生成 API 密钥之前，需要先创建一个项目，让密钥关联到具体项目以便计费管理。操作步骤如下：

点击左侧导航栏中的 Get API Key 链接，进入 API 密钥管理页面
点击 Projects 链接
点击右上角的 Create New Project 按钮
为项目命名（例如 "Gemini CLI Course"），然后点击 Create

项目创建完成后，你会看到它默认被分配了免费层级（Free Tier）。免费层级的功能与之前在 Gemini CLI 中使用的体验类似——可以使用 Gemini 2.5，但存在使用限制。

设置计费账户并领取 300 美元免费额度

要通过 API 密钥使用 Gemini 3 模型，必须为项目设置付费计划。点击项目旁边的 Setup Billing 链接，系统会跳转到 Google Cloud 控制台，在这里关联一个计费账户。

Google Cloud Platform（GCP）采用按需付费（Pay-as-you-go）的计费模式，所有资源消耗都通过计费账户（Billing Account）进行结算。计费账户需要绑定信用卡或其他支付方式，但绑定不等于立即扣费。

好消息是： 首次创建 Google Cloud 计费账户时，通常会获得 300 美元的免费额度，有效期约为三个月。这笔额度是 Google 获客策略的重要组成部分，覆盖 GCP 上几乎所有服务，包括 Compute Engine、Cloud Storage 以及 AI/ML 相关的 API 调用。试用期结束后，系统不会自动开始收费，而是需要用户手动升级为付费账户，因此在此期间你无需支付任何实际费用。

计费设置页面

关联计费账户后，刷新 AI Studio 页面，你应该能看到项目已升级为 Tier 1（付费计划）。实际费用取决于你通过 API 密钥调用 Gemini CLI 的频率和用量。建议在 Cloud Console 中设置预算警报（Budget Alerts），当消费达到预设阈值时自动发送通知，有效防止意外超支。

Gemini 3 API 定价说明

Gemini 3 采用按量计费模式，输入和输出分别收费：

输入（Input）：你发送的提示词和上下文内容
输出（Output）：模型返回的回复，包括其内部的思考和推理过程

费用按每 100 万 tokens 计算。在大语言模型（LLM）领域，Token 是文本处理的基本单位，但一个 Token 并不等同于一个单词或字符。对于英文文本，一个 Token 大约对应 4 个字符或 0.75 个单词；对于中文文本，一个汉字通常被编码为 1-2 个 Token。输出 Token 的单价通常高于输入 Token，因为生成文本比处理文本需要更多的计算资源。

值得注意的是，Gemini 3 的深度推理过程（Chain-of-Thought）也会产生输出 Token——模型在给出最终答案之前的思考步骤同样计入输出量。这意味着模型的深度推理能力虽然提升了回答质量，但也会相应增加 Token 消耗。以日常 CLI 开发为例，一次中等复杂度的代码分析请求可能消耗数千到数万个 Token，距离 100 万 Token 的计费单位仍有很大距离，普通用户不必过于担心费用问题。

生成 Gemini API 密钥

回到 API Keys 页面，点击 Create 按钮：

为密钥命名（例如 "Gemini CLI"）
关联到刚才创建的项目
点击创建按钮，等待几秒钟
创建完成后，点击复制图标保存你的 API 密钥

API 密钥创建页面

⚠️ 安全提醒：API 密钥务必妥善保管，不要分享给任何人，也不要提交到公开的代码仓库中。一旦泄露，他人可以用你的密钥产生费用。建议将密钥存储在环境变量或专用的密钥管理工具（如 .env 文件配合 .gitignore）中，而非硬编码在源代码里。

在 Gemini CLI 中配置 API 密钥认证

切换到 API 密钥认证方式

回到 Gemini CLI 的聊天会话中，按照以下步骤完成认证切换：

运行 /auth 命令
选择第二个选项：Use a Gemini API key
粘贴你刚才复制的 API 密钥，按回车确认

完成后，Gemini CLI 将通过你的 API 密钥发送请求和接收响应，不再依赖 Google 账户认证。这意味着所有的 API 调用都将通过你的密钥关联的项目进行计费，你可以在 Google Cloud Console 中实时查看用量和费用明细。

启用 Gemini 3 预览功能

默认情况下，Gemini 3 模型在 CLI 中并未启用。运行 /model 命令可以验证这一点——你会发现选项中没有 Gemini 3，并且顶部会提示需要在设置中启用预览功能。

启用步骤如下：

运行 /settings 命令
切换到 Workspace 级别（这样仅在当前项目中启用预览功能）
将 Preview Features 选项设置为 true

启用预览功能设置

将设置限定在 Workspace 级别而非全局级别是一个好的实践——这样你可以针对不同项目使用不同的模型配置，避免在不需要 Gemini 3 的项目中意外产生额外费用。

再次运行 /model 命令，你会看到 Gemini 3 已经出现在可选模型列表中。

选择合适的模型模式

启用 Gemini 3 后，你有两种使用模式可选：

模式	行为说明
Auto	系统根据任务复杂度自动选择模型：简单任务用 Flash 模型，复杂任务用 Gemini 3（在日限额内），超出限额回退到 2.5 Pro
Pro	跳过 Flash 模型，所有任务直接使用 Gemini 3

Gemini 系列模型采用分层架构设计：Flash 模型（如 Gemini 2.0 Flash）专注于低延迟和高吞吐量，适合简单的文本补全、格式转换等轻量任务；Pro 模型（如 Gemini 2.5 Pro）在推理能力和上下文理解上更强；而 Gemini 3 代表了当前最高水平的推理能力。Auto 模式背后的路由机制类似于 OpenAI 的 GPT-4o 自动选择策略——系统会根据输入的复杂度、上下文长度、任务类型等信号，动态决定将请求分发给哪个模型。这种设计既能保证复杂任务获得最佳推理质量，又能避免简单任务浪费高端模型的计算资源。

建议选择 Auto 模式，这样可以在性能和成本之间取得较好的平衡。

验证 Gemini 3 是否配置成功

配置完成后，可以用一个简单的提示来测试：

Can you examine the code base and explain this project to me?

如果一切正常，你会注意到两个明显变化：

响应时间略有增加——因为 Gemini 3 会进行更深入的推理和思考（即 Chain-of-Thought 推理），模型在输出最终答案之前会先生成一系列中间推理步骤，这些步骤虽然增加了延迟，但显著提升了回答的准确性和深度
响应顶部会显示 "Gemini 3 Pro Preview" 标识，确认你正在使用新模型

从实际体验来看，Gemini 3 在代码分析和项目理解方面的表现比 2.5 有明显提升，回复的深度和准确性都更胜一筹。

常见问题

Q：配置 API 密钥后还能切换回 Google 账户认证吗？

可以。运行 /auth 命令，选择 Google 账户登录即可切换回去。两种认证方式可以随时切换。切换回 Google 账户认证后，API 调用将不再通过你的计费项目计费，而是使用 Google 账户关联的免费额度。

Q：300 美元免费额度用完后怎么办？

免费额度用完后，Google Cloud 会按实际用量从你绑定的支付方式中扣费。你可以在 Google Cloud 控制台中设置预算提醒，避免意外超支。具体操作路径为：Cloud Console → Billing → Budgets & Alerts → Create Budget，你可以设置多个阈值（如 50%、80%、100%），系统会在消费达到对应比例时发送邮件通知。

Q：API 密钥泄露了怎么办？

立即回到 Google AI Studio 的 API Keys 页面，删除泄露的密钥并重新生成一个新的。同时检查 Google Cloud 控制台中是否有异常用量。如果发现未授权的消费，可以联系 Google Cloud 支持团队申请费用审查。为防止类似事件再次发生，建议使用 Git 的 pre-commit hook 或工具（如 git-secrets、truffleHog）自动扫描代码提交中是否包含密钥信息。

总结

完成以上 Gemini CLI API 密钥配置后，你已经：

✅ 在 Google AI Studio 中创建了项目并关联了计费账户
✅ 生成了专用的 Gemini API 密钥
✅ 在 Gemini CLI 中完成了 API 密钥认证
✅ 启用了预览功能并开始使用 Gemini 3 模型

整个过程并不复杂，但带来的能力提升非常明显。API 密钥不仅解锁了 Gemini 3，还为后续使用图像生成等高级功能打下了基础。对于认真使用 Gemini CLI 进行开发的用户来说，这是一项值得投入的配置。

核心要点

Gemini 3 模型目前仅对 AI Ultra 会员和 API 密钥用户开放，配置 API 密钥可以突破免费额度限制
需要在 Google AI Studio 中创建项目、关联计费账户后才能生成 API 密钥，首次注册可获得 300 美元免费额度
在 CLI 中通过 /auth 命令切换为 API 密钥认证，并通过 /settings 启用 Preview Features 才能使用 Gemini 3
模型选择建议使用 Auto 模式，系统会根据任务复杂度自动在 Flash、Gemini 3 和 2.5 Pro 之间切换
Gemini 3 按输入输出分别计费（每百万 tokens），日常 CLI 使用的费用通常可控