介绍
# Gmail OAuth Setup
使用 `gog` CLI 访问 Gmail API 的无头友好 OAuth 流程。
## 前置条件
- 已安装 `gog` CLI (`brew install steipete/tap/gogcli`) - 拥有包含 OAuth 凭据的 Google Cloud 项目（桌面应用类型） - 项目中已启用 Gmail API
## 快速设置
### 1. 创建 Google Cloud 项目和凭据
1. 访问 https://console.cloud.google.com 2. 创建一个新项目（或选择现有项目） 3. **启用 Gmail API**：API 和服务 → 库 → 搜索 "Gmail API" → 启用 4. **配置 OAuth 同意屏幕**：API 和服务 → OAuth 同意屏幕 - 用户类型选择 "External"（外部） - 填写应用名称、用户支持电子邮件 - 添加范围：`gmail.modify`（或其他所需范围） - **重要提示**：点击 "PUBLISH APP" 以获取永久令牌（参见故障排除） 5. **创建凭据**：API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID - 应用类型：**Desktop app**（桌面应用） - 下载 JSON 文件
### 2. 配置 gog
```bash 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`，或者：
```bash # 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. 验证
```bash gog gmail search 'is:unread' --max 5 --account [email protected] ```
## 故障排除
### "Access blocked: [app] has not completed the Google verification process"（访问被阻止：[应用] 未完成 Google 验证流程）
**原因**：应用处于 "Testing"（测试）模式，且 Gmail 账号不是测试用户。
**解决方案**（任选其一）： 1. **发布应用**（推荐）： - Google Cloud Console → API 和服务 → OAuth 同意屏幕 - 点击 **"PUBLISH APP"** → 确认 - 个人使用无需 Google 审核 - 令牌将变为永久有效
2. **添加测试用户**： - OAuth 同意屏幕 → 测试用户 → + 添加用户 - 添加您正在授权的 Gmail 地址 - 令牌仍会在 7 天后过期
### "Google hasn't verified this app"（Google 尚未验证此应用）警告界面
**这对于个人应用来说是正常现象。** 点击： 1. **Advanced**（左下角） 2. **Go to [app name] (unsafe)**（前往 [应用名称]（不安全））
由于您拥有该应用，可以放心继续。
### 令牌在 7 天后过期
**原因**：应用处于 "Testing"（测试）模式。
**修复方法**：发布应用（见上文）。已发布的应用将获得永久刷新令牌。
### "invalid_request" 或 "invalid_grant" 错误
**原因**： - 授权码已过期（它们仅持续几分钟） - 代码已被使用 - 重定向 URI 不匹配
**修复方法**：生成新的授权 URL 并快速完成流程。获取代码后立即粘贴。
### "redirect_uri_mismatch" 错误
**原因**：令牌交换中的重定向 URI 与授权 URL 中使用的不匹配。
**修复方法**：此脚本使用 `http://localhost`。请确保授权 URL 和交换过程使用相同的重定向 URI。
### 批准权限后页面挂起（移动端）
**原因**：浏览器尝试连接 localhost，而手机上不存在 localhost。
**修复方法**： - 改用桌面浏览器 - 或者在页面 "挂起" 时点击地址栏 - URL 中包含代码 - URL 将类似于：`http://localhost/?code=4/0ABC...`
### 多个权限复选框导致挂起
**原因**：请求的 OAuth 范围过多。
**修复方法**：使用最小范围。仅 `gmail.modify` 通常就足够了，且仅显示一个权限。
### 在 Google Cloud Console 中找不到项目
**原因**：登录了错误的 Google 账号。
**修复方法**：检查哪个账号拥有项目： - 点击个人资料图标（右上角） - 切换账号 - 检查每个账号的项目下拉菜单
### 使用 oob 重定向时出现 "invalid_request"（新项目）
**原因**：Google 已弃用 2022 年后创建的 OAuth 客户端的 `urn:ietf:wg:oauth:2.0:oob`。
**修复方法**：改用 `http://localhost` 重定向（此脚本的默认设置）。批准后，浏览器会重定向到 localhost 并在 URL 中附带代码。
## 范围参考
| 范围 | 访问权限 | |-------|--------| | `gmail.modify` | 读取、发送、删除、管理标签（推荐） | | `gmail.readonly` | 仅读取 | | `gmail.send` | 仅发送 | | `gmail.compose` | 创建草稿、发送 |
## 文件
- `scripts/gmail-auth.sh` — 交互式授权助手
## 提示
- **发布您的应用** — 避免测试用户限制和 7 天令牌过期 - **快速交换代码** — 它们会在几分钟后过期 - **使用桌面浏览器** — 移动浏览器处理 localhost 重定向可能不稳定 - **一个范围就够了** — `gmail.modify` 涵盖了大多数用例