Gmail + Gog 配置

当需要通过 Gog CLI 为某个 agent（例如 Facet、竞赛 agent）授予 Gmail 收件箱访问权限时，请使用本技能。

适用场景

• 创建新的 agent 邮箱（例如 facet.ai.oc@gmail.com）
• 为已有 agent 配置 Gmail 读取能力
• 排查 Gog 认证失败问题
• 添加新的 OAuth 客户端或测试用户

前提条件

1. Google Cloud OAuth 客户端

• 在 Google Cloud Console 中创建一个 桌面应用 类型的 OAuth 客户端
• 启用 Gmail API
• 在 OAuth 同意屏幕中将目标 Gmail 地址添加为 测试用户
• 下载客户端 JSON 文件

2. 已安装 Gog

# 从最新发布版本安装 Gog
cd /tmp
curl -L -o gogcli_0.12.0_linux_amd64.tar.gz https://github.com/steipete/gogcli/releases/download/v0.12.0/gogcli_0.12.0_linux_amd64.tar.gz
tar -xzf gogcli_0.12.0_linux_amd64.tar.gz
install -m 0755 gog /usr/local/bin/gog

操作步骤

1. 存储 OAuth 凭据

gog auth credentials /path/to/client_secret_....json

2. 认证 Gmail 账户

export GOG_KEYRING_PASSWORD='your-keyring-password'
gog auth add agent@gmail.com --services gmail --manual

• 在浏览器中打开提示的认证 URL
• 以目标 Gmail 账户身份登录
• 批准所请求的权限
• 在 Google 重定向至 localhost 后，复制该重定向 URL
• 将其粘贴到等待输入的 Gog 提示符中

3. 验证访问权限

gog auth list
gog gmail messages search 'newer_than:7d' --account agent@gmail.com --json

4. 检查垃圾邮件文件夹

新发件人邮件常被归类至垃圾邮件：

gog gmail messages search 'in:spam newer_than:7d' --account agent@gmail.com --json

常见问题

“No auth for gmail”

• 确认已在 Google Cloud OAuth 同意屏幕中添加了测试用户
• 如有必要，可使用 --force-consent 参数重新运行认证命令

“state mismatch”

认证会话已重启。请使用最新的认证 URL 和回调地址。

“no TTY available for keyring file backend”

在运行 gog auth add 前，需先设置环境变量 GOG_KEYRING_PASSWORD。

邮件进入垃圾邮件文件夹

• 将邮件从垃圾邮件移回收件箱：gog gmail messages modify --remove SPAM --add INBOX
• 可考虑通过点击“不是垃圾邮件”来训练 Gmail 分类模型

注意事项

• OAuth 客户端 JSON 文件应存放在 ~/.openclaw/credentials/google/
• GOG_KEYRING_PASSWORD 应保存在安全的环境变量或密钥管理服务中
• 生产环境中，建议改用具备全域委派权限的服务账号（Service Account），而非 OAuth
• 务必定期检查垃圾邮件文件夹，以防遗漏关键的验证邮件或 API 相关通知

参考资料

• Gog CLI
• Google Cloud OAuth 配置指南
• OpenClaw Gmail Pub/Sub 文档