郵件（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 的區別