Gemini CLI API Key 获取与配置：macOS、Windows 和无头模式
简答：Gemini CLI 不一定需要 API Key：本地交互使用可直接登录 Google 账号；无浏览器、脚本或 CI/CD 场景更适合使用 AI Studio 的 Gemini API Key。获取后设置 GEMINI_API_KEY，启动 gemini 并选择 Use Gemini API key；若仍要求登录，优先检查变量名、旧认证变量和项目配置。
定义：Gemini CLI API Key 是供 Gemini CLI 调用 Gemini API 的环境变量凭据，通常通过 GEMINI_API_KEY 传入，适合无头运行、脚本和不使用交互式 Google 登录的场景。
先看结论：你是否真的需要 Gemini API Key
如果你是在自己的电脑上交互式使用 Gemini CLI，官方当前推荐先运行 gemini，再选择使用 Google 账号登录；这种方式通常不需要手动创建 API Key。若服务器没有浏览器、要运行无头模式、脚本或 CI/CD，则可以使用 Google AI Studio 创建的 Gemini API Key，并通过 GEMINI_API_KEY 提供给 CLI。认证方式会影响配额、计费、服务条款和隐私设置，选择前应查看 Gemini CLI 官方认证说明。
| 方式 | 适合场景 | 主要配置 | 是否通常需要 Google Cloud 项目 |
|---|---|---|---|
| Google 账号登录 | 本地交互式使用 | 运行 gemini 后选择 Sign in with Google | 个人账号通常不需要；组织账号等情况可能需要 |
| Gemini API Key | 无头模式、脚本、服务器 | GEMINI_API_KEY | 使用 AI Studio 创建的 key 时通常不需要单独设置项目变量 |
| Vertex AI | Google Cloud 项目、组织权限和企业环境 | GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION 或对应凭据 | 需要 |
如果你只是想在本地打开 CLI 试用，先用 Google 账号登录通常更省步骤；如果你的终端无法打开浏览器，直接配置 API Key 更合适。
如何获取 Gemini API Key 并配置到 Gemini CLI
第 1 步：在 Google AI Studio 创建或查看 key
- 打开 Google AI for Developers 的 Gemini API Key 文档，进入 Google AI Studio 的 API Keys 页面。
- 如果是新用户，AI Studio 可能会创建默认 Google Cloud 项目和 API Key；如果你已有项目，需要先将项目导入 AI Studio，再在对应项目下创建 key。
- 复制新建的 key，并把它当作密码处理，不要提交到 Git 仓库、前端代码或公开日志。
Google 的 API Key 文档说明，Gemini API 正从 Standard key 迁移到 Authorization key；文档还写明，2026 年 9 月之后 Standard key 将被拒绝，新的 AI Studio key 默认使用 Authorization key。由于这是会随平台规则变化的内容，创建或迁移时应以 当前 API Key 文档显示的状态为准。
第 2 步：macOS 或 Linux 设置变量
只在当前终端会话使用，可以执行：
export GEMINI_API_KEY='YOUR_GEMINI_API_KEY'然后启动 CLI：
gemini出现认证方式选择时，选择 Use Gemini API key。Gemini CLI 官方认证页明确使用的变量名是 GEMINI_API_KEY，不要把 Vertex AI 专用的 GOOGLE_API_KEY 误当成 Gemini API Key 的通用替代变量。
第 3 步：Windows PowerShell 设置变量
当前 PowerShell 会话可执行：
$env:GEMINI_API_KEY = 'YOUR_GEMINI_API_KEY'
gemini如果要永久保存，可使用 Windows 的环境变量设置界面创建用户变量 GEMINI_API_KEY，保存后重新打开终端。Google AI 文档和 Gemini CLI 文档都建议通过环境变量管理 key；保存到用户环境变量后，其他从该账户启动的进程可能读取它，因此不要在共享电脑上随意持久化。
第 4 步：使用项目级或用户级 .env 文件
Gemini CLI 当前文档说明，它会从当前目录向上查找 .gemini/.env，也会查找用户目录下的 ~/.gemini/.env；只使用找到的第一个文件，不会把多个文件自动合并。示例：
mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GEMINI_API_KEY='YOUR_GEMINI_API_KEY'
EOFWindows PowerShell 示例：
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini"
@"
GEMINI_API_KEY='YOUR_GEMINI_API_KEY'
"@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8配置文件的优点是不用每次手动 export，缺点是本地文件一旦被同步、备份或提交到仓库，key 可能泄露。请把 .gemini/.env 加入项目的忽略规则，并检查 shell 历史记录、日志和屏幕共享内容。
GEMINI_API_KEY、GOOGLE_API_KEY 和 Vertex AI 变量怎么区分
| 变量 | 主要用途 | 不要混用的情况 |
|---|---|---|
GEMINI_API_KEY | Gemini API Key 认证，Gemini CLI 的 Use Gemini API key 选项 | 不要用它代替 Vertex AI 项目配置 |
GOOGLE_API_KEY | Gemini CLI 文档中主要用于 Vertex AI express mode 的 Google Cloud API key | 不是看到“Google API”就可以与 AI Studio key 任意互换 |
GOOGLE_CLOUD_PROJECT 与 GOOGLE_CLOUD_LOCATION | Vertex AI 或部分组织账号、Code Assist 场景的项目和位置配置 | 配置了这些变量后，个人账号可能触发组织订阅或项目检查 |
GOOGLE_APPLICATION_CREDENTIALS | Vertex AI 使用服务账号 JSON 凭据时指定文件路径 | 不要把服务账号 JSON 文件提交到代码仓库 |
Gemini CLI 官方认证代码和文档将 Gemini API、Vertex AI、ADC 等方式分开处理。若你选择的是 Use Gemini API key，先只检查 GEMINI_API_KEY；若选择 Vertex AI，再按官方文档配置项目、位置或凭据。变量已设置但认证界面仍反复出现时，可以暂时清理冲突变量后重启 CLI：
unset GOOGLE_API_KEY GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_PROJECT_ID GOOGLE_APPLICATION_CREDENTIALSPowerShell 可执行：
Remove-Item Env:GOOGLE_API_KEY, Env:GOOGLE_CLOUD_PROJECT, Env:GOOGLE_CLOUD_PROJECT_ID, Env:GOOGLE_APPLICATION_CREDENTIALS -ErrorAction Ignore注意：上述清理命令只影响当前终端会话；如果变量写在 shell 配置文件或 .gemini/.env 中，还要检查对应文件。Gemini CLI 官方故障排查文档特别提到，个人账号环境中残留 Google Cloud 项目变量，可能导致组织订阅检查。
无头模式、服务器和 CI/CD 怎么配置
无头模式不能依赖首次运行时打开浏览器完成登录。Gemini CLI 官方文档说明，如果没有现成的缓存凭据，需要通过环境变量配置 Gemini API Key 或 Vertex AI。对于使用 Gemini API Key 的脚本，建议在 CI/CD 平台的 Secret、变量保险库或 Secret Manager 中保存，不要把 key 写进 YAML、Shell 脚本或命令行参数。
export GEMINI_API_KEY="$CI_GEMINI_API_KEY"
gemini如果是在本地测试无头配置，可以先检查变量是否非空，但不要直接打印完整 key：
if [ -z "$GEMINI_API_KEY" ]; then
echo 'GEMINI_API_KEY is not set' >&2
exit 1
fi
echo 'GEMINI_API_KEY is set'如果使用 Vertex AI，则要改用项目和位置变量、ADC、服务账号或 Google Cloud API Key 中的一种方式，并清理可能冲突的 GEMINI_API_KEY 或 GOOGLE_API_KEY。详细变量要求可查看 Gemini CLI 认证文档。
Gemini CLI API Key 不生效：按这张表排查
| 现象 | 优先检查 | 处理步骤 |
|---|---|---|
| CLI 提示没有 GEMINI_API_KEY | 变量名、当前终端会话、.env 文件位置 | 执行非泄露式检查；确认变量名完全是 GEMINI_API_KEY，再重启 gemini。 |
| 已设置 key 但仍要求 Google 登录 | 启动后选择的认证方式和旧缓存 | 重新启动 CLI，在认证选择中明确选择 Use Gemini API key；不要误选 Sign in with Google。 |
| 使用个人账号却出现组织订阅或项目检查 | GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_PROJECT_ID 是否残留 | 按官方排查文档暂时取消这些变量，再重新启动 CLI。 |
| API Key 无效或请求被拒绝 | key 是否复制完整、是否被撤销、类型和限制是否符合当前规则 | 回到 AI Studio 查看 key 状态；必要时创建新的 Authorization key，并更新环境变量。 |
| 提示没有权限创建 key | 项目 IAM 权限、Generative Language API 是否启用 | 使用有权限的项目管理员协助，或在允许的情况下导入正确项目；以 Google API Key 文档列出的权限要求为准。 |
| 请求达到配额或计费异常 | 项目、key 类型、配额和计费设置 | 在 AI Studio 或 Google Cloud 项目中核对关联关系、限制和用量；不要仅凭 CLI 的认证成功判断配额状态。 |
如果仍无法定位，先把问题缩小到认证层：确认 GEMINI_API_KEY 在当前进程可见、没有把 Vertex AI 变量和 Gemini API 变量混用、没有把旧 key 写在更高优先级的 .env 文件中。Gemini CLI 官方还提供了 认证与登录故障排查文档，可继续核对具体错误信息。
安全检查：创建后别忘了做这 5 件事
- 不要把 API Key 写进 Git、公开 issue、聊天记录、截图或前端打包文件。
- 项目中使用
.gitignore排除.gemini/.env、本地密钥文件和服务账号 JSON。 - 生产环境优先使用 CI/CD Secret 或 Secret Manager，不要把完整 key 打到日志。
- 为 key 设置适当的 API 限制，并定期查看关联项目的用量和账单提醒。
- 怀疑泄露时，先在 AI Studio 或 Google Cloud 中撤销、删除或替换 key，再更新本地和部署环境。
Google 的 API Key 文档明确提醒，泄露的 key 可能被他人消耗项目配额、产生意外费用或访问受保护资源。安全设置完成后，再测试 CLI，比直接把 key 粘贴进脚本更容易控制风险。本文是独立的接入整理页面，不是 Gemini CLI 或 Google 官方页面；认证、密钥类型和限制应以对应官方文档为准。
常见问题
Gemini CLI 必须使用 API Key 吗？
不必须。本地交互式使用可以运行 gemini 并选择 Sign in with Google；没有浏览器、需要无头运行或接入 CI/CD 时，再使用 AI Studio 的 Gemini API Key。
Gemini CLI 应该设置 GEMINI_API_KEY 还是 GOOGLE_API_KEY？
选择 Use Gemini API key 时设置 GEMINI_API_KEY。GOOGLE_API_KEY 主要出现在 Vertex AI express mode 等 Google Cloud 认证场景，不能因为变量名称相似就直接互换。
为什么 GEMINI_API_KEY 已设置，Gemini CLI 还让我登录？
先确认启动后的认证选项是否选择了 Use Gemini API key，再检查变量是否存在于当前终端或 CLI 能读取的 .gemini/.env 文件中；同时排查是否误用了 Vertex AI 变量或更高优先级的配置文件。
Google AI Studio 创建 API Key 时没有权限怎么办？
先确认当前项目和账号。Google 文档列出的相关权限包括查看项目、创建 API Key、启用服务以及绑定服务账号等；如果没有项目管理员权限，应让管理员授权或选择有权限的项目。
API Key 泄露后应该怎么处理？
立即在 AI Studio 或 Google Cloud 中撤销、删除或替换泄露的 key，再更新本地、服务器和 CI/CD Secret，并检查项目用量和账单提醒。不要只从代码中删除而不撤销旧 key。