1. Gemini API 与 Vertex AI 是两套认证平面
| 路径 | 凭据 | 常见变量 |
|---|---|---|
| Gemini Developer API | Gemini API Key | GEMINI_API_KEY |
| Vertex AI | Google Cloud ADC / 服务账号 | GOOGLE_CLOUD_PROJECT、LOCATION |
| Google 登录 | OAuth 缓存 | CLI 登录状态 |
| 中转 API | 平台 API Key | 客户端支持的自定义 Base URL |
ACCESS_TOKEN_TYPE_UNSUPPORTED 常见于凭据类型与目标端点不匹配，而不是密钥字符串本身损坏。
2. 查看残留的 Vertex 与 Google 变量
env | grep -E 'GEMINI|GOOGLE|VERTEX' | sed 's/=.*$/=[REDACTED]/'若打算使用 Gemini API Key，应确认 Vertex 模式没有被旧变量开启。若打算使用 Vertex AI，则应配置项目、区域与 ADC，而不是把普通 API Key 当访问令牌。
3. 用 REST 请求单独验证 Gemini API Key
先使用官方模型列表端点验证密钥和基础网络，避免在日志中回显完整 Key。
curl "https://generativelanguage.googleapis.com/v1beta/models?key=API_KEY"REST 成功、CLI 失败说明应继续检查 CLI 的端点选择、版本与缓存；REST 也返回 401，则先处理 Key 和项目权限。
4. 清理后只启用一种认证方式
- 退出 Gemini CLI。
- 备份变量名和当前版本，不记录密钥值。
- 在新终端中只配置目标认证方式。
- 关闭 Vertex 模式或完整配置 Vertex，二选一。
- 固定一个模型执行短请求。
- 确认成功后再恢复其他变量。
5. 中转 API Key 不能发往 Google 端点
island AI Coding 平台 Key 应发送到平台的 OpenAI 兼容 Base URL https://www.codex789.com/v1。把平台 Key 发送到 Google Gemini 或 Vertex 端点会返回认证错误。应选择支持自定义 OpenAI 兼容地址的客户端。
6. 用请求记录确认最终端点
检查目标控制台是否出现请求记录，并记录状态码、模型、CLI 版本与认证类型。不要只依据 CLI 顶部的“authenticated”提示，因为它不一定证明后续生成请求使用了同一凭据路径。
7. 常见问题
API Key 有效为什么仍返回 ACCESS_TOKEN_TYPE_UNSUPPORTED？
密钥可能被发往要求 OAuth 或 ADC 的 Vertex AI 端点。有效凭据用于错误端点时仍会得到 401。
Gemini API Key 可以直接调用 Vertex AI 吗？
通常不可以。Vertex AI 使用 Google Cloud 项目和相应身份凭据，应按照 Vertex 认证方式配置。
如何确认 Gemini CLI 最终访问了哪个端点？
检查环境变量、CLI 调试日志及目标控制台请求记录，并与同一密钥的最小 REST 请求对照。
平台中转 Key 应该放到 Google API 地址吗？
不应该。平台 Key 只能发送到平台 Base URL，并由支持对应兼容协议的客户端调用。
* 本文由 island AI Coding 技术团队根据官方文档与公开问题记录原创整理。公开 issue 描述的是特定版本和环境，修复状态可能变化；操作前请记录版本并保留回滚路径。更新时间：2026-09-01。
参考：Gemini CLI API Key 401 issue · Gemini CLI Vertex 端点 401 issue · Gemini API Key 官方说明