Gmail OAuth 设置

使用gogCLI 实现无头环境友好的 Gmail API 访问 OAuth 流程

先决条件

• 已安装gogCLI (brew install steipete/tap/gogcli
• )
• 拥有 OAuth 凭据（桌面应用类型）的 Google Cloud 项目

项目中已启用 Gmail API

快速设置

1. 1. 创建 Google Cloud 项目与凭据前往
2. https://console.cloud.google.com
3. 创建新项目（或选择现有项目）启用 Gmail API
4. ：API 和服务 → 库 → 搜索 "Gmail API" → 启用配置 OAuth 同意屏幕
   • ：API 和服务 → OAuth 同意屏幕
   • 选择 "外部" 用户类型
   • 添加权限范围：gmail.modify（或根据需要添加其他范围）
   • 重要提示：点击"发布应用"以获取永久令牌（参见故障排除）
5. 创建凭据：API和服务 → 凭据 → 创建凭据 → OAuth客户端ID
   • 应用类型：桌面应用
   • 下载JSON文件

2. 配置gog

gog auth credentials /path/to/client_secret.json
gog auth keyring file  # Use file-based keyring for headless
export GOG_KEYRING_PASSWORD="your-password"  # Add to .bashrc

3. 运行认证流程

运行scripts/gmail-auth.sh交互式运行，或：

# Generate URL
scripts/gmail-auth.sh --url

# User opens URL, approves, copies code from localhost redirect
# Exchange code (do this quickly - codes expire in minutes!)
scripts/gmail-auth.sh --exchange CODE EMAIL

4. 验证

gog gmail search 'is:unread' --max 5 --account you@gmail.com

故障排除

"访问被阻止：[应用]尚未完成Google验证流程"

原因：应用处于"测试"模式，且Gmail账户不是测试用户。

解决方案（任选其一）：

1. 发布应用（推荐）：

   • Google Cloud Console → API 和服务 → OAuth 同意屏幕
   • 点击"发布应用"→ 确认
   • 个人使用无需 Google 审核
   • 令牌将变为永久有效

2. 添加测试用户:

   • OAuth 同意屏幕 → 测试用户 → + 添加用户
   • 添加您要授权的 Gmail 地址
   • 令牌仍会在 7 天后过期

"Google 尚未验证此应用" 警告屏幕

对于个人应用而言，这很正常。点击：

1. 高级选项（左下角）
2. 前往 [应用名称]（不安全）

由于您拥有此应用，继续操作是安全的。

令牌在 7 天后过期

原因：应用处于"测试"模式。

修复方法发布应用（见上文）。已发布的应用会获得永久的刷新令牌。

"invalid_request" 或 "invalid_grant" 错误

原因：

• 授权码已过期（它们仅持续几分钟）
• 授权码已被使用过
• 重定向URI不匹配

修复方法：生成一个新的授权URL并快速完成流程。获取授权码后立即粘贴。

"redirect_uri_mismatch" 错误

原因：令牌交换中的重定向URI与授权URL中使用的不匹配。

修复方法：此脚本使用http://localhost。请确保授权URL和交换请求都使用相同的重定向URI。

批准权限后页面卡住（移动设备）

原因：浏览器尝试连接到localhost，这在手机上不存在。

修复方法:

• 请改用桌面浏览器
• 或者，在它"卡住"时点击地址栏 - URL 中包含代码
• URL 将显示为：http://localhost/?code=4/0ABC...

多个权限复选框导致卡顿

原因：请求了过多的 OAuth 授权范围。

解决方法：使用最少的授权范围。通常仅 `gmail.modify`一个权限就足够了，并且只显示一个权限请求。

在 Google Cloud Console 中找不到项目

原因：登录了错误的 Google 账户。

解决方法：检查哪个账户拥有该项目：

• 点击个人资料图标（右上角）
• 切换账户
• 为每个账户检查项目下拉列表

新项目使用 oob 重定向时出现 "invalid_request"

原因Google 已弃用urn:ietf:wg:oauth:2.0:oob对于2022年之后创建的OAuth客户端。

修复方法：使用http://localhost重定向替代（此为脚本的默认设置）。授权后，浏览器将重定向到本地主机，并在URL中携带代码。

权限范围参考

文件

• scripts/gmail-auth.sh—— 交互式授权助手

提示

• 发布您的应用— 避开测试用户限制和7天令牌过期问题
• 快速兑换代码— 它们会在几分钟内过期
• 使用桌面浏览器— 移动浏览器处理本地主机重定向可能不稳定
• 一个权限范围就足够—gmail.modify覆盖大多数使用场景