email-pro-optimized

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

Security Scan

The skill mostly matches its stated email-management purpose but contains inconsistent declarations and several risky components (embedded credentials, git auto-push/sync scripts, undeclared config/env usage) that warrant caution before installing or running.

Purpose & Capability

Name/description (high-performance email tool) match the code that implements IMAP/SMTP and OAuth flows, but the skill reads/writes user credential files under ~/.openclaw and the package metadata does not declare those config paths. README and scripts contain specific account emails and an Outlook client_id/client_secret pair (hard-coded), which is unexpected for a general-purpose skill and inconsistent with the registry 'no config paths / no primary credential' claims.

Instruction Scope

SKILL.md instructs running the included scripts for listing, authorizing, checking and sending mail (expected), but the repository also includes maintenance, auto-push, and sync scripts that run git commands, copy files to a workspace path, and update/publish metadata. Those maintenance/sync scripts operate outside the narrow email functionality (touch other directories, run git push) and are not documented as required steps in SKILL.md — this is scope creep and increases the chance of unintended data disclosure.

Install Mechanism

There is no external install or download step and the skill is instruction-only / local files. No remote archive downloads or nonstandard installers were found. Installing means writing the provided files locally, which is low-risk compared to networked installers.

Credentials

SKILL.md declares only python3 and requests 'requests' package, but the code reads/writes ~/.openclaw/credentials/*, and oauth_handler will read GMAIL_CLIENT_ID / GMAIL_CLIENT_SECRET environment variables if present — those env var uses are not declared in the skill metadata. More importantly, there are hard-coded Outlook OAuth client_id and client_secret values in README and authorize-outlook.sh, which is unexpected and could expose credentials or indicate leaked secrets.

Persistence & Privilege

The skill is not marked 'always', but several included scripts (auto-push.py, sync-updates.py, maintain.py) modify files under ~/.openclaw, copy files to a workspace directory, and run git push. Those capabilities allow the skill's code/config to be propagated or pushed to remote repositories and could cause credential/config leakage if used. The presence of these auto-sync/push scripts increases the persistence and blast radius if run.

Scan Findings in Context

[hardcoded-credentials:authorize-outlook.sh] unexpected: authorize-outlook.sh and README include a concrete-looking Azure client_id and client_secret; embedding provider secrets in distributed skill files is unexpected for a generic email client and risks leaking credentials.

[git-automation:auto-push-sync-updates] unexpected: scripts/auto-push.py and scripts/sync-updates.py run shell git commands, stage/commit/push changes and copy files to another workspace path; automated push/sync behavior is not needed for normal email read/send operations and could exfiltrate files or credentials if remotes are configured.

[undeclared-env-vars:gmail-credentials] expected: oauth_handler._get_oauth_credentials will read GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET from environment as an optional source; that is plausible for OAuth flows but these environment variables are not declared in requires.env.

[local-http-server:oauth-callback] expected: oauth_handler creates a local HTTPServer to receive OAuth callbacks on localhost:8080 — this is expected for a local OAuth authorization flow.

What to consider before installing

This skill implements the claimed email features, but there are red flags you should address before installing or running it: - Do NOT run authorize-outlook.sh or the hard-coded authorization commands until you confirm whether the embedded client_id/client_secret are intentionally included; they look like real secrets and may be leaked credentials. Replace them with your own OAuth credentials. - Inspect and avoid running maintenance/sync scripts (scripts/auto-push.py, scripts/sync-updates.py, scripts/maintain.py) unless you understand their behavior. They will run git commands, copy files to other locations, and attempt to push to remotes — this can leak code or secrets (including any oauth_tokens.json) to remote repositories. - The skill reads/writes credentials under ~/.openclaw/credentials (email-accounts.json, oauth_tokens.json) even though the registry said no config paths; review and secure that directory (600 perms) and keep sensitive tokens out of tracked git repositories. - The oauth handler will read GMAIL_CLIENT_ID/GMAIL_CLIENT_SECRET from env vars if present; consider using environment variables or a local oauth_config.json you control, and delete any embedded secrets in the repository. - Prefer testing in an isolated environment (VM/container) and remove or sanitize hard-coded credentials and any remote git remotes before allowing automated scripts to run. If you want to proceed, manually run only the specific email scripts you need (email-pro.py, authorize.py) and avoid the auto-push/sync tooling unless you have audited them fully.

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 邮箱支持
• ✅ 高性能批量获取
• ✅ 并发处理