IMAP/SMTP 邮件工具

通过 IMAP 协议读取、搜索和管理邮件；通过 SMTP 协议发送邮件。支持 Gmail、Outlook、163.com、vip.163.com、126.com、vip.126.com、188.com、vip.188.com，以及任意标准 IMAP/SMTP 服务器。

配置

运行配置脚本以设置您的邮箱账户：

bash setup.sh

配置分为两个文件：

• config.env（技能目录中）—— 服务器主机地址、端口、TLS 设置、允许访问的目录
• ~/.openclaw/.env —— 凭据信息（用户名、密码、发件人地址）

旧版回退方式：~/.config/imap-smtp-email/.env（单个合并配置文件）。

配置文件格式

# 默认账户（无前缀）
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=your@email.com
IMAP_PASS=your_password
IMAP_TLS=true
IMAP_REJECT_UNAUTHORIZED=true
IMAP_MAILBOX=INBOX

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your@email.com
SMTP_PASS=your_password
SMTP_FROM=your@email.com
SMTP_REJECT_UNAUTHORIZED=true

# 文件访问白名单（安全限制）
ALLOWED_READ_DIRS=~/Downloads,~/Documents
ALLOWED_WRITE_DIRS=~/Downloads

多账户支持

您可在同一配置文件中配置多个邮箱账户。每个额外账户需为其所有变量添加一个名称前缀（全大写）。

添加账户

运行配置脚本并选择“Add a new account”（添加新账户）：

bash setup.sh

或手动在 config.env 中添加带前缀的配置项，并在 ~/.openclaw/.env 中添加对应密钥：

# 工作账户（WORK_ 前缀）
WORK_IMAP_HOST=imap.company.com
WORK_IMAP_PORT=993
WORK_IMAP_USER=me@company.com
WORK_IMAP_PASS=password
WORK_IMAP_TLS=true
WORK_IMAP_REJECT_UNAUTHORIZED=true
WORK_IMAP_MAILBOX=INBOX
WORK_SMTP_HOST=smtp.company.com
WORK_SMTP_PORT=587
WORK_SMTP_SECURE=false
WORK_SMTP_USER=me@company.com
WORK_SMTP_PASS=password
WORK_SMTP_FROM=me@company.com
WORK_SMTP_REJECT_UNAUTHORIZED=true

使用指定账户

在命令前添加 --account 参数：

node scripts/imap.js --account work check
node scripts/smtp.js --account work send --to foo@bar.com --subject Hi --body Hello

若未指定 --account，则默认使用（无前缀）主账户。

账户名称规则

• 仅允许字母与数字（例如：work、163、personal2）
• 不区分大小写：work 和 WORK 指向同一账户
• .env 中的前缀始终为大写（例如：WORK_IMAP_HOST）
• ALLOWED_READ_DIRS 和 ALLOWED_WRITE_DIRS 对所有账户共享（始终无前缀）

常见邮件服务器配置

Gmail 注意事项：

• Gmail 不接受您的常规账户密码
• 您必须生成一个 App Password：https://myaccount.google.com/apppasswords
• 将生成的 16 位 App Password 用作 IMAP_PASS / SMTP_PASS
• 要求 Google 账户已启用两步验证

163.com 注意事项：

• 请使用 授权码（而非账户密码）
• 请先在网页端设置中启用 IMAP/SMTP 支持

IMAP 命令（接收邮件）

check

检查新邮件或未读邮件。

node scripts/imap.js [--account ] check [--limit 10] [--mailbox INBOX] [--recent 2h]

选项：

• --limit ：最大返回数量（默认值：10）
• --mailbox ：要检查的邮箱（默认：INBOX）
• --recent ：仅显示最近 X 时间内的邮件（例如：30m、2h、7d）

fetch

根据 UID 获取完整邮件内容。

node scripts/imap.js [--account ] fetch  [--mailbox INBOX]

download

下载某封邮件的所有附件，或指定某个附件。

node scripts/imap.js [--account ] download  [--mailbox INBOX] [--dir ] [--file ]

选项：

• --mailbox ：邮箱名（默认：INBOX）
• --dir ：输出目录（默认：当前目录）
• --file ：仅下载指定名称的附件（默认：下载全部附件）

search

使用过滤条件搜索邮件。

node scripts/imap.js [--account ] search [options]

选项：
  --unseen           仅匹配未读邮件
  --seen             仅匹配已读邮件
  --from      发件人地址包含指定字符串
  --subject    主题包含指定文本
  --recent     最近 X 时间内收到的邮件（例如：30m、2h、7d）
  --since      指定日期之后的邮件（格式：YYYY-MM-DD）
  --before     指定日期之前的邮件（格式：YYYY-MM-DD）
  --limit         最大返回数量（默认：20）
  --mailbox    要搜索的邮箱（默认：INBOX）

mark-read / mark-unread

将邮件标记为已读或未读。

node scripts/imap.js [--account ] mark-read  [uid2 uid3...]
node scripts/imap.js [--account ] mark-unread  [uid2 uid3...]

list-mailboxes

列出所有可用邮箱/文件夹。

node scripts/imap.js [--account ] list-mailboxes

list-accounts

列出所有已配置的邮箱账户。

node scripts/imap.js list-accounts
node scripts/smtp.js list-accounts

显示账户名、邮箱地址、服务器地址及配置状态。

SMTP 命令（发送邮件）

send

通过 SMTP 发送邮件。

node scripts/smtp.js [--account ] send --to  --subject  [options]

必需参数：

• --to ：收件人（多个收件人用英文逗号分隔）
• --subject ：邮件主题，或使用 --subject-file

可选参数：

• --body ：纯文本正文内容
• --html：将正文作为 HTML 发送
• --body-file ：从文件读取正文内容
• --html-file ：从文件读取 HTML 内容
• --cc ：抄送收件人
• --bcc ：密送收件人
• --attach ：附件路径（多个附件用英文逗号分隔）
• --from ：覆盖默认发件人地址

示例：

# 简单文本邮件
node scripts/smtp.js send --to recipient@example.com --subject "Hello" --body "World"

# HTML 邮件
node scripts/smtp.js send --to recipient@example.com --subject "Newsletter" --html --body "
Welcome
"

# 带附件的邮件
node scripts/smtp.js send --to recipient@example.com --subject "Report" --body "Please find attached" --attach report.pdf

# 多收件人
node scripts/smtp.js send --to "a@example.com,b@example.com" --cc "c@example.com" --subject "Update" --body "Team update"

test

通过向自己发送测试邮件来验证 SMTP 连接。

node scripts/smtp.js [--account ] test

依赖项

npm install

安全说明

• 凭据存储于 ~/.openclaw/.env，权限设为 600（仅属主可读写）；连接配置位于技能目录下的 config.env
• Gmail：常规密码将被拒绝 —— 请前往 https://myaccount.google.com/apppasswords 生成 App Password
• 163.com：请使用授权码（授权码），而非账户密码

故障排查

连接超时：

• 确认服务器正在运行且网络可达
• 检查主机地址与端口配置是否正确

认证失败：

• 确认用户名（通常为完整邮箱地址）正确
• 确认密码正确
• 163.com：请使用授权码，而非账户密码
• Gmail：常规密码不可用 —— 请前往 https://myaccount.google.com/apppasswords 生成 App Password
• Yahoo Mail：常规密码不可用 —— 请前往 https://login.yahoo.com/account/security 生成 App Password

TLS/SSL 错误：

• 确保 IMAP_TLS/SMTP_SECURE 设置与服务器要求一致
• 对于自签名证书：设置 IMAP_REJECT_UNAUTHORIZED=false 或 SMTP_REJECT_UNAUTHORIZED=false