email-pro-optimized

高性能邮件工具 - 支持 QQ、Gmail、Outlook。IMAP读、SMTP写、OAuth 2.0、并发处理。速度比 imap-smtp-email 快 4-5 倍。

Security Scan

The skill mostly matches its stated purpose (email IMAP/SMTP + OAuth), but it includes embedded OAuth credentials and git push automation that are disproportionate and risky.

Purpose & Capability

Most files (providers, oauth_handler, email-pro) are coherent with a high-performance multi-provider email tool. However the repo includes an automatic git push script and hard-coded Outlook client ID/secret/tenant in scripts and README — these are not required to provide email access and are unexpected for a user-facing email client package.

Instruction Scope

SKILL.md instructs running authorization scripts (e.g., bash scripts/authorize-outlook.sh) which call authorize.py with a client_secret passed on the command line. That exposes secrets via process arguments and the repo's provided authorize-outlook.sh contains a hard-coded client_secret/tenant/client_id, which the instructions explicitly recommend executing.

Install Mechanism

No install spec; SKILL.md lists python3 and requests which aligns with the Python scripts included. Absence of an install step reduces risk of arbitrary remote code download.

Credentials

The skill declares no required environment variables, yet the code reads GMAIL_CLIENT_ID/GMAIL_CLIENT_SECRET and supports storing credentials in ~/.openclaw/credentials/*. More importantly, the repository contains hard-coded Outlook client_id/client_secret/tenant values in authorize-outlook.sh and README — embedded sensitive credentials are disproportionate and dangerous.

Persistence & Privilege

The skill is not always-enabled and allows user invocation (normal). It does include scripts (auto-push.py, maintain.py) that can modify and push the skill repository to remote origins; these scripts are not automatically executed by the platform but provide capability to push local changes (possible exfiltration vector) if run.

Scan Findings in Context

[hardcoded-client-secret] unexpected: scripts/authorize-outlook.sh and README.md include a Client ID, Client Secret, and Tenant ID; embedding secrets in distributed code is unexpected and risky for a mail client.

[shell-exec-git-push] unexpected: scripts/auto-push.py runs shell git commands and will push the skill directory to the configured remote. This can leak repository contents or credentials if executed.

[cli-arg-secret-exposure] unexpected: authorize-outlook.sh passes the client_secret on the command line to authorize.py, exposing the secret in process listings and command histories.

[reads-credentials-path] expected: Code reads and writes tokens and account configs in ~/.openclaw/credentials which is expected for an email client managing OAuth tokens and account info.

What to consider before installing

This skill appears to implement a capable multi-provider email client, but it ships with embedded Outlook OAuth credentials and a script that will push the skill directory to a remote Git repo. Those embedded secrets should be treated as sensitive — do NOT run authorize-outlook.sh or any auto-push/maintain scripts without auditing and removing secrets. Recommended steps before installing or running: 1) Inspect and remove any hard-coded client_id/client_secret/tenant values from scripts and README; treat them as compromised if you used them anywhere. 2) Run authorization manually using your own OAuth client credentials (do not reuse the repo's values), and avoid passing secrets on the command line; use interactive input or secure config files with 600 permissions. 3) Do not run scripts/auto-push.py unless you understand and control the remote repo (it will git add/commit/push and could leak data). 4) If you already ran the included credentials, rotate those app secrets in Azure/Google immediately. 5) Prefer running this code in an isolated environment and examine ~/.openclaw/credentials to ensure only expected tokens are stored. If you want, I can point to exact files/lines to remove or show safer ways to perform OAuth authorization and token storage.

Email Pro Optimized - 高性能邮件工具

快速、高效的邮件管理工具，支持多账号、多提供商、批量处理、并发获取。

支持的邮箱类型

邮箱	认证方式	状态
QQ 邮箱	IMAP/SMTP + 授权码	✅ 完全支持
Gmail	OAuth 2.0	✅ 完全支持
Outlook/Live	OAuth 2.0	✅ 完全支持

性能对比

指标	imap-smtp-email	Email Pro Optimized
10封邮件	1.5-2s	0.3-0.5s
100封邮件	15-20s	2-3s
1000封邮件	150-200s	15-20s
并发处理	❌	✅
连接复用	❌	✅
多提供商	❌	✅

快速开始

1. 列出账户

python3 scripts/email-pro.py list-accounts

2. 检查邮件（QQ 邮箱）

# 检查最近 10 封
python3 scripts/email-pro.py --account qq_3421 check --limit 10

# 仅检查未读
python3 scripts/email-pro.py --account qq_3421 check --unread

# 使用其他账户
python3 scripts/email-pro.py --account qq_136 check --limit 5

3. 授权 Gmail 邮箱

# 自动授权 Gmail
python3 scripts/authorize.py gmail --name gmail_qiao

# 或使用默认配置
python3 scripts/authorize.py gmail

4. 授权 Outlook 邮箱

# 自动授权（已配置 Azure 信息）
bash scripts/authorize-outlook.sh

# 或手动授权
python3 scripts/authorize.py outlook \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET" \
  --tenant-id "YOUR_TENANT_ID" \
  --name "outlook_live"

5. 检查邮件（Gmail/Outlook）

# Gmail
python3 scripts/email-pro.py --account gmail_qiao check --limit 10

# Outlook
python3 scripts/email-pro.py --account outlook_live check --limit 10

6. 发送邮件

# QQ 邮箱
python3 scripts/email-pro.py --account qq_136 send \
  --to "[e-mail]" \
  --subject "Hello" \
  --body "Test email"

# Gmail
python3 scripts/email-pro.py --account gmail_qiao send \
  --to "[e-mail]" \
  --subject "Hello" \
  --body "Test email"

# Outlook
python3 scripts/email-pro.py --account outlook_live send \
  --to "[e-mail]" \
  --subject "Hello" \
  --body "Test email"

OAuth 自动刷新

Gmail 和 Outlook 的 OAuth token 会自动刷新，无需手动干预。

工作原理

• 自动检测过期 - 每次使用前自动检查 token 是否过期
• 提前刷新 - 提前 5 分钟刷新，避免过期
• 透明处理 - 调用方无需关心刷新逻辑
• 持久化 - 新 token 自动保存到凭证文件

在代码中使用

from scripts.oauth_handler import get_valid_token

# 获取有效的 token（自动刷新）
token = get_valid_token('gmail')
headers = {'Authorization': f'Bearer {token}'}

# 使用 headers 调用 Gmail API
response = requests.get('https://www.googleapis.com/gmail/v1/users/me/profile', headers=headers)

高级用法

搜索邮件

python3 scripts/email-pro.py search "旅行" --limit 20

获取完整邮件

python3 scripts/email-pro.py fetch 71197

批量并发获取

# 获取最近 100 封邮件的完整内容（5 个线程并发）
python3 scripts/email-pro.py check --limit 100 | \
  jq -r '.[].uid' | \
  xargs -I {} python3 scripts/email-pro.py fetch {}

配置

配置文件位置

~/.openclaw/credentials/email-accounts.json

QQ 邮箱配置

{
  "qq_3421": {
    "email": "[e-mail]",
    "auth_code": "xxxx",
    "smtp_server": "smtp.qq.com",
    "smtp_port": 587,
    "imap_server": "imap.qq.com",
    "imap_port": 993,
    "provider": "imap",
    "status": "✅ 正常",
    "note": "接收邮箱"
  }
}

Outlook 配置

{
  "outlook_live": {
    "email": "[e-mail]",
    "provider": "outlook",
    "account_name": "outlook_live",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "tenant_id": "YOUR_TENANT_ID",
    "status": "✅ 已授权",
    "note": "Outlook 邮箱"
  }
}

Gmail 配置

{
  "gmail_account": {
    "email": "[e-mail]",
    "provider": "gmail",
    "account_name": "gmail_account",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "status": "✅ 已授权",
    "note": "Gmail 邮箱"
  }
}

命令参考

check - 检查邮件

python3 scripts/email-pro.py check [OPTIONS]

Options:
  --account NAME     账户名称 (默认: qq_3421)
  --limit N          限制数量 (默认: 10)
  --unread           仅未读邮件
  --mailbox NAME     邮箱名称 (默认: INBOX)

fetch - 获取完整邮件

python3 scripts/email-pro.py fetch UID [OPTIONS]

Options:
  --account NAME     账户名称 (默认: qq_3421)
  --mailbox NAME     邮箱名称 (默认: INBOX)

search - 搜索邮件

python3 scripts/email-pro.py search QUERY [OPTIONS]

Options:
  --account NAME     账户名称 (默认: qq_3421)
  --limit N          限制数量 (默认: 20)
  --mailbox NAME     邮箱名称 (默认: INBOX)

send - 发送邮件

python3 scripts/email-pro.py send [OPTIONS]

Options:
  --account NAME     账户名称 (默认: qq_3421)
  --to EMAIL         收件人 (必需)
  --subject TEXT     主题 (必需)
  --body TEXT        正文 (必需)
  --html             HTML 格式
  --attach FILE...   附件

list-accounts - 列出账户

python3 scripts/email-pro.py list-accounts

OAuth 授权

Outlook 授权流程

1. 获取 Azure 应用信息

   • 登录 Azure Portal
   • 创建应用注册或使用现有应用
   • 复制 Client ID、Client Secret、Tenant ID

2. 运行授权脚本

   bash scripts/authorize-outlook.sh
   

   或

   python3 scripts/authorize.py outlook \
     --client-id "YOUR_CLIENT_ID" \
     --client-secret "YOUR_CLIENT_SECRET" \
     --tenant-id "YOUR_TENANT_ID"
   

3. 浏览器授权

   • 脚本会打开浏览器
   • 登录你的 Outlook 账户
   • 授予权限
   • 令牌自动保存到 ~/.openclaw/credentials/oauth_tokens.json

Gmail 授权流程

1. 获取 Google OAuth 凭证

   • 访问 Google Cloud Console
   • 创建 OAuth 2.0 凭证
   • 复制 Client ID 和 Client Secret

2. 运行授权脚本

   python3 scripts/authorize.py gmail \
     --client-id "YOUR_CLIENT_ID" \
     --client-secret "YOUR_CLIENT_SECRET" \
     --name "gmail_account"
   

3. 浏览器授权

   • 脚本会打开浏览器
   • 登录你的 Gmail 账户
   • 授予权限
   • 令牌自动保存

优化点

1. 批量 fetch - 一次获取多封邮件，快 4.5 倍
2. 连接复用 - 保持连接活跃，省 385ms
3. 错误处理 - 跳过损坏邮件，更稳定
4. 并发处理 - 支持多线程并发获取
5. 多提供商 - 统一接口支持 QQ、Gmail、Outlook
6. OAuth 2.0 - 安全的令牌认证，自动刷新

性能基准

✅ 检查 10 封邮件: 0.5s
✅ 检查 100 封邮件: 3s
✅ 检查 1000 封邮件: 20s
✅ 发送邮件: 0.6s
✅ 并发获取 20 封: 1.5s

故障排除

连接超时

• 检查网络连接
• 验证 IMAP/SMTP 服务器地址和端口
• 对于 Outlook，确保已授权

认证失败

• QQ 邮箱：确认授权码正确（不是密码）
• Outlook：重新运行授权脚本
• Gmail：检查 OAuth 令牌是否过期

邮件解析失败

• 某些邮件格式可能不支持
• 脚本会自动跳过损坏的邮件

依赖

• Python 3.6+
• requests（用于 OAuth 和 API 调用）
• 标准库: imaplib, smtplib, email, ssl, json, argparse

安装依赖：

pip3 install requests

文件结构

email-pro-optimized/
├── scripts/
│   ├── email-pro.py          # 主程序
│   ├── providers.py          # 邮件提供商实现
│   ├── oauth_handler.py      # OAuth 处理
│   ├── authorize.py          # 授权工具
│   ├── authorize-outlook.sh  # Outlook 快速授权
│   └── analyze.py            # 邮件分析工具
├── SKILL.md                  # 本文档
└── README.md                 # 项目说明

常见用例

旅行监控

# 定期检查旅行相关邮件
python3 scripts/email-pro.py search "机票|酒店|旅行" --limit 50

# 发送监控报告
python3 scripts/email-pro.py --account qq_136 send \
  --to "[e-mail]" \
  --subject "旅行监控报告" \
  --body "今日发现 5 条相关邮件"

邮件备份

# 导出所有邮件为 JSON
python3 scripts/email-pro.py check --limit 1000 > backup.json

自动分类

# 使用 analyze.py 分析邮件
python3 scripts/analyze.py

更新日志

v2.0.0 (2026-03-20)

• ✅ 新增 Gmail 支持（OAuth 2.0）
• ✅ 新增 Outlook 支持（OAuth 2.0）
• ✅ 模块化提供商架构
• ✅ 自动令牌刷新
• ✅ 统一命令接口

v1.0.0 (2026-03-19)

• ✅ QQ 邮箱支持
• ✅ 高性能批量获取
• ✅ 并发处理