Hermes Agent 配置 QQ 邮箱 教程 (Himalaya CLI)

Hermes Agent 配置 QQ 邮箱 教程 (Himalaya CLI)

✨ 本教程详细记录如何配置 QQ 邮箱的 IMAP/SMTP 服务，并使用 Himalaya CLI 命令行工具管理邮件。

📋 前置条件

• QQ 邮箱账号（如：646269678@qq.com）
• 已获取 QQ 邮箱的 授权码（不是 QQ 密码）
• Linux/macOS 终端环境（或 WSL）
• 已安装 Himalaya CLI 邮件客户端

🔐 第一步：获取 QQ 邮箱授权码

1. 登录 QQ 邮箱网页版：https://mail.qq.com
2. 点击顶部 设置 → 账户
3. 找到 POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务 部分
4. 开启 IMAP/SMTP服务（如果未开启）
5. 点击 生成授权码，按照提示发送短信验证
6. 复制生成的 16位授权码

⚠️ 重要提示：

• 授权码是第三方客户端登录的专用密码
• 不要泄露给他人
• 更改 QQ 密码会导致授权码失效，需要重新生成

📡 第二步：QQ 邮箱服务器信息

根据 QQ 邮箱官方文档（SMTP/IMAP服务）：

IMAP 接收邮件服务器

• 服务器地址 ：imap.qq.com
• 端口 ：993
• 加密：SSL/TLS
• 协议：IMAP

SMTP 发送邮件服务器

• 服务器地址 ：smtp.qq.com
• 端口 ：465（推荐）或 587
• 加密：SSL/TLS
• 协议：SMTP

账户信息

• 邮箱地址 ：你的完整 QQ 邮箱（如：646269678@qq.com）
• 用户名：同上（完整邮箱地址）
• 密码 ：授权码（不是 QQ 密码）

📦 第三步：安装 Himalaya CLI

通过 Cargo 安装（推荐）

cargo install himalaya

通过包管理器安装

# Ubuntu/Debian
sudo apt install himalaya

# macOS (Homebrew)
brew install himalaya

# Arch Linux
sudo pacman -S himalaya

验证安装

himalaya --version
# 输出示例：himalaya v1.2.0 +maildir +smtp +wizard +sendmail +pgp-commands +imap

⚙️ 第四步：配置 Himalaya

Himalaya 的配置文件位于 ~/.config/himalaya/config.toml。

创建配置文件

mkdir -p ~/.config/himalaya

编辑配置文件

nano ~/.config/himalaya/config.toml

配置文件内容

将以下内容复制到配置文件中，替换 646269678@qq.com 为你的邮箱，和你的授权码：

[accounts.qq]
email = "646269678@qq.com"
display-name = "你的显示名称"
default = true

[accounts.qq.backend]
type = "imap"
host = "imap.qq.com"
port = 993
encryption = { type = "tls" }
login = "646269678@qq.com"
auth = { type = "password", raw = "你的授权吗" }

[accounts.qq.message.send.backend]
type = "smtp"
host = "smtp.qq.com"
port = 465
encryption = { type = "tls" }
login = "646269678@qq.com"
auth = { type = "password", raw = "你的授权吗" }

配置说明

• accounts.qq：账户名称，可自定义（如改为 qqmail）
• email：你的 QQ 邮箱地址
• display-name：发送邮件时显示的姓名
• default = true：设为默认账户
• backend：IMAP 接收服务器配置
• message.send.backend：SMTP 发送服务器配置

✅ 第五步：测试配置

1. 检查账户配置

himalaya account list

输出应显示你的账户：

| NAME | BACKENDS | DEFAULT |
|------|----------|---------|
| qq   |          | yes     |

2. 诊断账户

himalaya account doctor qq

输出应为：Checking TOML configuration integrity for account qq... OK

3. 列出邮件（测试 IMAP 连接）

himalaya envelope list

如果连接成功，会显示最近的邮件列表：

| ID   | FLAGS | SUBJECT                          | FROM         | DATE                   |
|------|-------|----------------------------------|--------------|------------------------|
| 1676 |       | 更安全、更高效、更强大...        | QQ邮箱团队   | 2026-04-23 07:29+08:00 |
| 1671 |       | D-Claw 验证码                    | lslcool.hi   | 2026-04-21 19:13+08:00 |
...（更多邮件）

4. 发送测试邮件（可选）

himalaya message write

按照提示填写：

• To: 你的邮箱地址
• Subject: 测试邮件
• Body: 这是一封测试邮件

按 Ctrl+D 完成编辑，输入 send 发送。

🚀 第六步：常用 Himalaya 命令

邮件管理

# 列出最新邮件（默认显示10封）
himalaya envelope list

# 列出更多邮件（如20封）
himalaya envelope list --max 20

# 阅读特定邮件
himalaya message read <邮件ID>

# 查看邮件线程
himalaya envelope thread <邮件ID>

# 搜索邮件
himalaya envelope list --query "GitHub"

# 标记为已读
himalaya flag add <邮件ID> seen

# 删除邮件
himalaya message delete <邮件ID>

文件夹管理

# 列出所有文件夹
himalaya folder list

# 切换到特定文件夹
himalaya envelope list --folder "INBOX"

# 查看垃圾邮件
himalaya envelope list --folder "Junk"

发送邮件

# 交互式编写邮件
himalaya message write

# 回复邮件
himalaya message reply <邮件ID>

# 转发邮件
himalaya message forward <邮件ID>

账户管理

# 列出所有账户
himalaya account list

# 诊断账户问题
himalaya account doctor <账户名>

# 交互式配置账户（需要TTY）
himalaya account configure <账户名>

🔧 第七步：故障排除

常见错误及解决方案

1. "cannot list envelopes: feature not available"

问题 ：配置文件格式错误或缺少必要字段。
解决 ：检查配置文件格式，确保 encryption = { type = "tls" } 而不是 encryption = "tls"。

2. "authentication failed"

问题 ：授权码错误或已失效。
解决：

• 重新生成 QQ 邮箱授权码
• 更新配置文件中的 auth.raw 字段
• 确保使用的是 授权码 而不是 QQ 密码

3. "connection timeout" 或 "network error"

问题 ：网络问题或服务器地址错误。
解决：

• 检查网络连接
• 确认服务器地址正确：
  • IMAP: imap.qq.com:993
  • SMTP: smtp.qq.com:465
• 尝试关闭防火墙或 VPN 测试

4. "certificate verify failed"

问题 ：SSL 证书验证失败。
解决：

# 测试 SSL 连接
openssl s_client -connect imap.qq.com:993 -crlf

如果证书有效，可能是系统时间不正确。

5. Himalaya 命令不存在

问题 ：Himalaya 未正确安装。
解决：

# 重新安装
cargo install himalaya --force

# 或添加到 PATH
export PATH="$HOME/.cargo/bin:$PATH"

调试模式

启用调试日志查看详细错误信息：

himalaya envelope list --debug
himalaya envelope list --trace

📝 第八步：其他邮件客户端配置

如果你需要使用其他邮件客户端，配置信息相同：

Thunderbird

1. 新建账户 → 输入姓名、邮箱、密码（授权码）
2. 手动配置：
   • 接收：IMAP，imap.qq.com，端口 993，SSL/TLS
   • 发送：SMTP，smtp.qq.com，端口 465，SSL/TLS

mutt (Linux 终端)

编辑 ~/.muttrc：

set imap_user = "646269678@qq.com"
set imap_pass = "你的授权码"
set smtp_url = "smtps://646269678@qq.com@smtp.qq.com:465/"
set smtp_pass = "你的授权码"
set from = "646269678@qq.com"
set realname = "你的姓名"

Apple Mail / Outlook

使用相同的服务器信息，密码处填写 授权码。

💾 配置文件备份

建议备份你的配置文件：

# 备份
cp ~/.config/himalaya/config.toml ~/himalaya-config-backup.toml

# 恢复
cp ~/himalaya-config-backup.toml ~/.config/himalaya/config.toml

📚 参考链接

1. QQ 邮箱 SMTP/IMAP 服务官方文档
2. Himalaya CLI GitHub 仓库
3. Himalaya 官方文档

🎯 总结

通过本教程，你已经成功：

• ✅ 获取了 QQ 邮箱授权码
• ✅ 了解了 QQ 邮箱服务器信息
• ✅ 安装并配置了 Himalaya CLI
• ✅ 测试了邮件收发功能
• ✅ 掌握了常用邮件管理命令

现在你可以通过命令行高效管理 QQ 邮箱了！遇到问题请参考故障排除部分，或重新查看本教程。

---

最后更新：2026年4月23日
文档维护：Hermes Agent
祝你使用愉快！ ✨