huacnlee/omamail · 上手攻略
- 仓库：huacnlee/omamail
- 链接：https://github.com/huacnlee/omamail
- 分类：Linux Desktop · 邮件客户端
- 作者：Tom
- 更新：2026-08-25
是什么
Omamail 是一个运行在 Omarchy 桌面环境（基于 Quickshell 的 Hyprland 面板插件）里的原生邮件客户端。它以插件形式集成进 Omarchy 桌面进程，不是浏览器 tab，而是一个真正的 Hyprland 窗口，自动适配桌面主题，在面板显示未读计数。
支持 Gmail（官方 API）、HEY（通过 37signals 官方 HEY CLI）、以及任何 IMAP/SMTP 邮箱（Fastmail、iCloud、Outlook、Yahoo、Zoho、GMX、Proton Mail Bridge 等）。
解决什么问题
在 Linux Hyprland 桌面下，现有的邮件方案通常是： - 浏览器打开 Gmail（消耗资源、无法本地通知） - Thunderbird/Evolution 等传统邮件客户端（外观不融入 Hyprland 主题） - 其他 WebMail 客户端
Omamail 的核心差异是：设计驱动而非功能堆叠，深度融入 Omarchy 外观和窗口模型，在 Hyprland 平铺窗口管理体系里像原生应用一样工作，自动跟随主题，资源占用极低。
快速安装
安装 Omamail 插件
omarchy plugin add https://github.com/huacnlee/omamail.git --enable
打开邮件窗口
点击任务栏的信封图标，或在 ~/.config/hypr/bindings.lua 添加快捷键：
o.bind("SUPER + SHIFT + G", "Omamail", "omarchy shell shell toggle omamail '{}'")
目标对象是
shell而不是插件 ID：窗口由 shell 召唤，而 shell 才是真正加载插件的入口。
系统依赖
- Omarchy 4（必需）
socat、secret-tool、openssl、xdg-open、curl（Omarchy 已自带大部分）
添加邮箱账户
Gmail
- 在 Google Cloud Console 创建 OAuth 客户端
- 插件会引导完成 Google 登录
- 获取 Gmail API 访问权限（支持标签、对话、Gmail 搜索语法、报告垃圾邮件）
HEY
- 安装 basecamp/hey-cli
- 首次使用时授权 HEY CLI（插件通过 CLI 与 HEY 通信）
IMAP/SMTP（通用）
添加任意 IMAP 邮箱，只需提供地址和 App Password（不是在网页登录）。
⚠️ IMAP 不支持日历附件解析：邀请函的日历部分无法读取（HEY 同理，因为 HEY CLI 只返回文本）。
多账户支持
支持同时连接多个账户，每个账户独立 inbox、独立缓存、独立未读计数。
核心用法
键盘操作
| 按键 | 功能 |
|---|---|
j / k |
上/下移动列表 |
e |
归档（⚠️ HEY 无归档功能） |
s |
星标（⚠️ HEY 无星标功能） |
r |
回复 |
c |
写信 |
Alt+1~0 |
切换邮箱（底部面板提示序号） |
Alt+A |
切换账户 |
/ |
搜索 |
? |
帮助 |
如果当前邮箱没有某个功能，插件会直接提示「该邮箱无此操作」而非假装可用——这是设计层面的诚实。
会议邀请处理
邮件中的日历邀请会被自动解析，显示为会议卡片： - 会议时间（换算为本地时区） - 时长 - 地点/视频链接（Google Meet 链接一键加入） - 是否重复 - 其他参与者的回复状态
回复会作为普通邮件发出，任何日历服务器都能识别（仅限 Gmail 和 IMAP，HEY 不支持）。
一键退订
- 支持 one-click unsubscribe 的新闻通讯直接退订
- 只提供邮件地址的 newsletters 会自动打开写信窗口（不访问发件人域名）
- 只提供网页退订页面的会提示后再打开浏览器
⚠️ 在用户主动请求前，插件不会访问任何发件人域名。
隐私保护
- 图片默认不加载（防止发件人知道你打开了邮件）
- Gmail refresh token 和所有 IMAP 密码存储在 GNOME Keyring（从不写入配置文件或命令行）
- HEY 账户凭据完全不在本插件中：HEY CLI 自行管理 token
典型适用场景
- Omarchy 用户：已在使用 Omarchy 桌面，希望邮件深度集成而非开浏览器
- 多邮箱用户：同时使用 Gmail + HEY + IMAP 邮箱，需要统一界面管理
- 键盘重度用户：
j/k/e/r/c全键盘操作，不碰鼠标 - 隐私敏感用户：图片默认阻断，凭据存 Keyring 不落地
- 资源受限环境：不需要开浏览器，一个 Hyprland 窗口处理所有邮件
坑与注意
⚠️ 依赖 Omarchy 4：不是通用 Linux 邮件客户端，必须在 Omarchy 桌面环境下运行。
⚠️ HEY 限制：HEY CLI 只返回邮件文本，不含日历附件，所以会议邀请功能在 HEY 账户上不可用。
⚠️ Proton Mail：需要通过 Proton Bridge（IMAP）接入，不支持 Proton 官方 API。
⚠️ Proton VPN 等特殊邮箱：部分加密邮箱可能不完全兼容 IMAP。
⚠️ 非 Chrome/Electron：Omamail 是 Quickshell 插件，与传统邮件客户端架构完全不同，调试和排错需要了解 Omarchy 机制。
⚠️ 安装门槛：需要已有 Omarchy 4 环境，对新用户有一定上手门槛。
与同类对比
| Omamail | Thunderbird | Geary | Browser Gmail | |
|---|---|---|---|---|
| 运行方式 | Omarchy 插件/原生窗口 | 独立应用 | 独立应用 | 浏览器 tab |
| 外观融合 | ✅ 跟随 Omarchy 主题 | ❌ | ❌ | ❌ |
| HEY 支持 | ✅（官方 CLI） | ❌ | ❌ | ❌ |
| Gmail API | ✅ | IMAP | IMAP | ✅ |
| 多账户 | ✅ | ✅ | ✅ | ❌（需多标签页） |
| 键盘操作 | ✅ vi风格 j/k | 一般 | 一般 | 一般 |
| 资源占用 | 极低 | 中 | 中 | 高 |
| 日历邀请解析 | ✅ | 部分 | 部分 | ✅ |
| 隐私（图片阻断） | ✅ | ❌ | ❌ | ❌ |
| 平台 | Omarchy/Hyprland | 全平台 | Linux | 全平台 |
一句话推荐结论
Omamail 是专为 Omarchy/Hyprland 桌面打造的低噪邮件客户端，深度集成桌面主题 + Keyring 安全存储 + Gmail/HEY/IMAP 全覆盖 + 键盘优先设计，适合已入坑 Omarchy 并追求「邮件像桌面原生应用」体验的用户；非 Omarchy 用户可直接跳过。