📦 安装

📦 通过 SkillHub 安装（推荐）：

skillhub install mail-agent-goose --dir ~/.openclaw/workspace/skills/

安装后需重启 Gateway：openclaw gateway restart

🎯 触发方式（说什么能唤醒这个技能）

以下任一说法都能触发：

"帮我查一下邮箱" / "看看有没有新邮件" / "查收件箱" / "收一下邮件" "发一封邮件给 xxx" / "发送邮件" / "发邮件" / "发个通知" "搜索一下 xxx 的邮件" / "找一下xxx发来的邮件" "下载邮件附件" / "把邮件里的文件下载下来" "配置邮箱" / "设置邮箱" / "我的邮箱怎么配置"

⚡ 快速开始

第一步：配置邮箱

cd ~/.openclaw/workspace/mail-agent-goose
bash setup.sh

交互式向导会引导你选择邮箱类型（Gmail/163/QQ 等），输入账号密码，自动生成 .env 文件。

或手动创建 .env：

# Gmail 示例
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your@gmail.com
IMAP_PASS=your_app_password
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@gmail.com
SMTP_PASS=your_app_password
SMTP_FROM=your@gmail.com

⚠️ Gmail：不支持普通密码，必须用 App Password（16位）。开启两步验证后到这里生成：https://myaccount.google.com/apppasswords ⚠️ 163/126/QQ：用邮箱授权码，不是登录密码

第二步：试试收发

# 查看最近 5 封邮件
node imap.js check --limit 5

# 发一封测试邮件
node smtp.js test

⚠️ 能力边界（它做不到的事）

• ❌ 不支持网页登录：必须开启邮箱的 IMAP/SMTP 功能
• ❌ 不支持发送后删除：只能发送，不能删除对方收件箱里的邮件
• ❌ 不支持定时发送：立即发送，不支持预约
• ❌ 附件无大小保证：各服务商有限制（Gmail 25MB、163 50MB），附件过大会发送失败
• ❌ 不支持批量个性化群发：可以群发，但不能像邮件营销工具那样每个收件人显示不同名字

📋 命令速查

收邮件

发邮件

管理邮件

📤 输出示例

node imap.js check --limit 3

[
  {
    "uid": 1234,
    "from": "zhangsan@example.com",
    "to": "me@example.com",
    "subject": "项目进度汇报",
    "date": "2026-07-14T09:30:00.000Z",
    "snippet": "各位好，本周进度如下：1. 前端页面已完成；2. 接口开发..."
  },
  {
    "uid": 1233,
    "from": "noreply@taobao.com",
    "to": "me@163.com",
    "subject": "【淘宝】您的订单已发货",
    "date": "2026-07-14T08:15:00.000Z",
    "snippet": "亲爱的用户，您的订单 #28475931 已发货，预计 3-5 天送达..."
  }
]

node imap.js fetch 1234

{
  "uid": 1234,
  "from": "zhangsan@example.com",
  "to": "me@example.com",
  "subject": "项目进度汇报",
  "date": "2026-07-14T09:30:00.000Z",
  "text": "各位好，本周进度如下：n1. 前端页面已完成n2. 接口开发完成 80%n请查收。",
  "html": "
各位好，本周进度如下：
前端页面已完成
接口开发完成80%
",
  "attachments": [
    {
      "filename": "进度报告.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ]
}

node smtp.js send --to a@b.com --subject "测试" --body "你好"

{
  "success": true,
  "messageId": "",
  "response": "250 OK",
  "to": "a@b.com"
}

node smtp.js test

{
  "success": true,
  "message": "SMTP connection successful",
  "messageId": ""
}

🛠 完整命令参考

IMAP 命令

# 检查新邮件（默认 10 封，最新在前）
node imap.js check [--limit 10] [--mailbox INBOX] [--recent 2h] [--unseen]

# 根据 UID 获取邮件完整内容
node imap.js fetch  [--mailbox INBOX]

# 下载附件（全部或指定文件）
node imap.js download  [--mailbox INBOX] [--dir ] [--file ]

# 搜索邮件
node imap.js search [options]
  --unseen           仅未读
  --seen             仅已读
  --from      发件人包含
  --subject    主题包含
  --recent     最近（如 2h、7d）
  --since      某日期之后（YYYY-MM-DD）
  --before     某日期之前（YYYY-MM-DD）
  --limit         最大结果数（默认 20）

# 标记已读/未读
node imap.js mark-read  [uid2 uid3...]
node imap.js mark-unread  [uid2 uid3...]

# 列出所有邮箱文件夹
node imap.js list-mailboxes

SMTP 命令

# 发送邮件
node smtp.js send --to  --subject  [options]

  必填：
    --to               收件人（多个逗号分隔）
    --subject           主题

  可选：
    --body              纯文本正文
    --html                    正文是 HTML（配合 --body 使用）
    --body-file         从文件读取正文
    --html-file         从 HTML 文件读取内容
    --cc               抄送
    --bcc              密送
    --attach            附件（多个逗号分隔）
    --from             覆盖默认发件人

# 测试连接（给自己发一封测试邮件）
node smtp.js test

常用邮件服务器

❓ 常见问题（FAQ）

连接与认证类

Q1: 报"连接超时"（ETIMEDOUT/ECONNREFUSED）

可能原因：IMAP/SMTP 服务器地址错误、端口错误、网络不通、服务器维护

排查步骤：

1. 确认 .env 中的 IMAP_HOST / SMTP_HOST 地址正确（参考上方服务器表格）
2. 测试网络连通性：telnet imap.qq.com 993 或 curl -v telnet://imap.gmail.com:993
3. 确认邮箱服务商的 IMAP/SMTP 功能已在网页端开启
4. 163/QQ 等国内邮箱有时需要等待 5-10 分钟才能激活服务
5. 若公司/校园网限制外网 IMAP 端口，换用手机热点尝试

Q2: 报"认证失败"（Authentication failed/INVALID_CREDENTIALS）

可能原因：密码类型错误、授权码过期、账号拼写错误

Gmail 必做：

1. Gmail 不支持普通密码，必须用 App Password（16位）
2. 去 https://myaccount.google.com/apppasswords 生成（需先开启两步验证）
3. 如果没有"生成App Password"选项 → 先去 https://myaccount.google.com/security 开启两步验证
4. 用生成的 App Password 替换 .env 中的 IMAP_PASS 和 SMTP_PASS

163/126/QQ 必做：

1. 登录网页邮箱 → 设置 → POP3/SMTP/IMAP → 开启 IMAP/SMTP
2. 使用授权码而非登录密码（不是 QQ 登录密码！）
3. 授权码可在邮箱设置页面重新生成
4. 确认 IMAP_USER 填写的是完整邮箱地址（如 123456@qq.com，不是纯数字 QQ 号）

Q3: 163 邮箱报"IMAP ID failed"警告

这是正常现象（服务器不支持 IMAP ID 扩展），不影响使用，脚本会自动跳过继续执行。

Q4: Gmail 报"请用 App Password"但我明明用了 App Password

1. 确认 App Password 填写正确（16位，无空格）
2. App Password 生成后只能看一次，如丢失需重新生成
3. 确认 IMAP_USER 是 Gmail 地址格式（如 xxx@gmail.com）
4. 如最近更改了 Google 账号密码，需重新生成 App Password

邮件收发类

Q5: 查邮件成功但返回空列表

1. 确认 IMAP/SMTP 已开启：登录邮箱网页 → 设置 → 查看是否已启用 IMAP
2. 检查是否在正确的文件夹（默认是 INBOX），其他文件夹用 --mailbox 文件夹名
3. Gmail：Settings → See all settings → Forwarding and POP/IMAP → IMAP Access → Enable

Q6: 附件下载失败（ALLOWED_WRITE_DIRS）

1. 在 .env 中添加允许写入的目录：ALLOWED_WRITE_DIRS=~/Downloads
2. 多个目录用逗号分隔：ALLOWED_WRITE_DIRS=~/Downloads,~/Documents
3. 指定下载目录：node imap.js download 1234 --dir ~/Downloads
4. 确认目录存在且有写入权限

Q7: 发邮件报"附件太大"

各服务商单封邮件附件限制：

• Gmail：25MB
• 163/126：50MB
• QQ 邮箱：50MB

解决方案：压缩大文件（PDF/图片用压缩工具），或改用网盘分享链接

Q8: 发送成功但收件人没收到

1. 检查收件人地址是否正确
2. 查看发件箱确认发送记录
3. 检查垃圾邮件文件夹
4. Gmail 可能因 SPF/DKIM 未配置被对方服务器拒收
5. 163/QQ 可能拦截非发件人本人账号的邮件，发送地址需与 SMTP_USER 一致

配置与工具类

Q9: 163/QQ 邮件收不到或发不出去

1. 确认已在邮箱网页端开启 IMAP/SMTP 服务
2. 用授权码（非登录密码）填入 IMAP_PASS 和 SMTP_PASS
3. 163 邮箱发送需确保发件人与登录账号一致
4. 首次开启服务后需等待 5-30 分钟生效

Q10: 命令行参数写错了没提示

感谢反馈！当前版本的参数校验已在优化中。传错参数时会直接透传给底层 CLI，请参考上方「命令速查」表格确保参数正确。

Q11: 网络波动后命令直接失败，能否自动重试？

未来版本将加入自动重试机制。当前请手动重试命令，或检查网络环境后再次执行。

🔗 关联技能

本技能可与以下技能联动使用：

🎨 html-mail-goose（邮件模板生成）

用 html-mail-goose 生成 HTML 邮件模板后，直接用 mail-agent 发送：

# 1. 生成模板
python html-mail-goose/generate_email_template.py --input welcome.json --output welcome.html

# 2. 发送 HTML 邮件
node mail-agent-goose/smtp.js send --to user@example.com 
  --subject "欢迎加入 MyCompany" 
  --html-file ./welcome.html

html-mail-goose 安装：

skillhub install html-mail-goose --dir ~/.openclaw/workspace/skills/

🌐 goosehost（静态网站托管）

把文件部署到 GooseHost，在邮件里附上预览链接：

# 1. 部署
goosehost deploy ./report.html --slug 月度报告

# 2. 发邮件附链接
node mail-agent-goose/smtp.js send 
  --to user@example.com 
  --subject "你的月度报告" 
  --body "报告已生成：https://page.goose.cc.cd/s/月度报告"

goosehost 安装：

skillhub install goosehost --dir ~/.openclaw/workspace/skills/
openclaw gateway restart