邮件（Gmail OAuth）

🟢 运行时就绪 — Gmail API 搭配 OAuth 2.0 设备流。 通过后台 gmail-inbound-daemon 工作进程轮询线程并分发接收的消息，实现流式更新。

功能概览

• OAuth 认证 — 用户授予访问权限，无需存储凭证
• 流式更新 — 消息实时更新（如聊天），通过后台工作进程实现
• Webhook — 可选的 pubsub 主题支持即时传递（需配置 Cloud Pub/Sub）
• 线程感知 — 回复保留在同一对话线程中
• 收件人覆盖 — channel 参数可将消息路由至不同的 Gmail 账户

配置步骤

1. 创建 Google Cloud 项目

1. 访问 Google Cloud 控制台
2. 创建新项目或使用现有项目
3. 启用 Gmail API：
   • 在"API 和服务"库中搜索"Gmail API"
   • 点击"启用"
4. 创建 OAuth 2.0 同意屏幕：
   • 进入"OAuth 同意屏幕"，点击"创建"
   • 选择"外部"用户类型
   • 填写应用名称、支持邮箱和开发者联系方式
   • 添加作用域 https://www.googleapis.com/auth/gmail.modify
5. 创建 OAuth 2.0 客户端 ID：
   • 进入"凭证"，点击"创建凭证"，选择"OAuth 客户端 ID"
   • 选择"桌面应用"
   • 下载 JSON（需保存客户端 ID 和密钥）

2. 为 Minara 提供凭证

快捷方式，直接告诉 Agent：

"connect Gmail to send me notifications using OAuth"

Agent 会引导你完成设备流，授予访问权限。

手动方式：

minara auth messaging add email-gmail

或直接在项目 .env 文件中配置：

GMAIL_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
[email protected]

3. （可选）启用即时 Webhook

实时接收回复而非轮询：

1. 创建 Cloud Pub/Sub 主题，用于 Gmail 通知
2. 设置指向你的 Minara 实例的推送订阅
3. 添加至 .env：

GMAIL_PUBSUB_TOPIC=projects/your-project/topics/gmail-notifications

接收消息

后台 gmail-inbound-daemon 工作进程每 30 秒轮询一次收件箱（可通过 GMAIL_POLL_INTERVAL_SEC 配置），并将接收的消息分发至工作流或 Agent 聊天。

线程处理：回复被路由回发送原始消息的工作流或聊天会话，保持对话历史。

限流

• 发送：每个用户每分钟 100 封邮件（Gmail API 限制）
• 接收：默认每 30 秒轮询一次；Pub/Sub 支持即时传递（如已配置）
• 线程读取：每条接收消息调用 1 次

故障排除

配置后显示"需要授权"

• OAuth 令牌已过期。运行 minara auth messaging test email-gmail 刷新。

无法接收回复

• 检查后台进程是否运行：minara learn cron 应显示 gmail-inbound-daemon 为活跃
• 验证 Pub/Sub 主题配置正确（如使用 Webhook）
• 检查 Agent 日志：tail -f ~/.minara/logs/agent.log | grep gmail

与 SMTP Email 的区别