gemini-auth

用途

gemini-auth 用于为 Gemini CLI 配置和管理身份验证，覆盖 OAuth、API 密钥和 Vertex AI 三种方式，适合需要在个人、工作或企业环境中切换 Gemini 访问方式的用户。

主要能力

1. Google OAuth（免费层）

无需管理 API 密钥
60 请求/分钟
1,000 请求/天
可访问 Gemini 2.5 Pro
1M token 上下文窗口

初始设置：运行 gemini，会打开浏览器进行 Google 账号登录。

2. API 密钥

支持程序化访问
无需浏览器
可脚本化工作流

从 https://aistudio.google.com/ 获取 API 密钥后，可通过三种方式配置：

环境变量：

export GEMINI_API_KEY="your-api-key-here"

用户配置文件：

mkdir -p ~/.gemini
echo 'GEMINI_API_KEY="your-api-key-here"' > ~/.gemini/.env
chmod 600 ~/.gemini/.env

项目配置：

mkdir -p ./.gemini
echo 'GEMINI_API_KEY="your-api-key-here"' > ./.gemini/.env
echo '.gemini/' >> .gitignore

验证：

gemini --yolo -p "Test authentication and report status"

3. Vertex AI（企业）

企业级安全
更高的速率限制
高级功能
支持服务账号

设置 Google Cloud CLI：

curl https://sdk.cloud.google.com | bash
exec -l $SHELL
gcloud init

配置项目：

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

服务账号设置：

gcloud iam service-accounts create gemini-cli \
  --display-name="Gemini CLI Service Account"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:gemini-cli@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud iam service-accounts keys create ~/gemini-sa-key.json \
  --iam-account=gemini-cli@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com

export GOOGLE_APPLICATION_CREDENTIALS="~/gemini-sa-key.json"

测试连接：

gemini --yolo -p "Test Vertex AI authentication and report project details"

使用方式

认证优先级

Gemini CLI 按以下顺序检查认证：

命令行标志
环境变量
项目 .gemini/.env
用户 ~/.gemini/.env
OAuth 令牌
交互式提示

配置文件

~/.gemini/config.json 示例：

{
  "auth": {
    "method": "oauth",
    "autoRefresh": true,
    "timeout": 30000
  },
  "apiKey": {
    "source": "env",
    "envVar": "GEMINI_API_KEY",
    "filePath": "~/.gemini/.env"
  },
  "vertex": {
    "project": "auto",
    "location": "us-central1",
    "credentials": "auto"
  }
}

多账户管理

提供 switch_gemini_account 脚本，可在 personal、work、enterprise 三种账户间切换，并通过 gemini --yolo -p 自动验证认证状态与配额。还提供 test_all_accounts 批量测试脚本。

安全密钥存储

支持使用 pass（密码存储）或 macOS keychain 安全保存 API 密钥：

pass insert gemini/api-key
export GEMINI_API_KEY="$(pass show gemini/api-key)"

速率限制管理

提供 gemini_with_retry 脚本，支持最多 3 次重试、指数退避（60 秒起），以及 track_gemini_usage 记录每日请求数并在接近 1000 上限时告警。

故障排查

启用调试：export GEMINI_DEBUG=true
检查认证源：gemini auth debug
分别测试：gemini auth test oauth / apikey / vertex
OAuth 令牌过期：删除 ~/.gemini/auth/tokens 后执行 gemini auth refresh
API 密钥未找到：检查环境变量与 .env 文件，并用 curl 验证密钥
Vertex AI 权限：使用 gcloud 检查服务账号与 IAM 角色

安全最佳实践

将 .env、.gemini/、*.key、*.json 加入 .gitignore
按环境使用不同密钥
定期轮换密钥（提供 rotate_api_key 脚本）
审计日志：提供 audit_gemini 函数记录时间、用户、认证方式与命令

集成示例

GitHub Actions：安装 @google/gemini-cli，通过 secrets 传入 GEMINI_API_KEY，运行分析命令
Docker：基于 node:20-alpine 安装 Gemini CLI，通过构建参数或运行时挂载传入凭据

适用场景

个人开发者使用免费 OAuth 快速接入 Gemini CLI
需要脚本化、无浏览器环境的自动化工作流
企业环境使用 Vertex AI 服务账号与更高配额
多账户切换、密钥安全存储、速率限制处理与审计
CI/CD 与 Docker 环境中的 Gemini CLI 集成

限制

资料未提供具体的价格、收费信息、平台兼容性细节或性能效果数据。部分命令与脚本依赖外部工具（如 pass、gcloud、keychain），需用户自行准备。