OpenClaw Himalaya 技能配置实战：Himalaya config.toml 的 IMAP/SMTP 账户、认证与多后端全解

本文基于 OpenClaw 仓库内置的 Himalaya 技能参考文档 configuration.md，系统讲解如何用 ~/.config/himalaya/config.toml 完成 Himalaya CLI 的邮件账户配置：从最小 IMAP + SMTP 设置、三种口令管理方案，到 Gmail / iCloud 等具体服务商、文件夹别名、多账户切换、Notmuch 本地后端与 OAuth2 认证。读完后可在 OpenClaw Agent 或终端中直接复制运行这些配置，让 Himalaya 胜任邮件的读取、搜索、撰写、回复与归档。

一、Himalaya 在 OpenClaw 中的位置：一个依赖二进制门槛的邮件技能

Himalaya 是一个命令行 IMAP/SMTP 邮件客户端，OpenClaw 以"技能"（Skill）的形式把它封装起来，让 Agent 学会通过 shell 操作邮箱：列文件夹、读邮件、搜索、撰写、回复、转发、复制、移动、删除。技能定义见 SKILL.md，其 YAML frontmatter 中声明了运行门槛：

"requires": { "bins": ["himalaya"] }

也就是说，只有系统里安装了 himalaya 可执行文件，该技能才会在加载时被放行。按 Skills 加载机制 的说明，技能在加载时会根据环境、配置和二进制是否存在进行过滤（gating），这正是 requires.bins 发挥作用的地方。安装方式 SKILL.md 中给出的官方路径是 Homebrew：

brew install himalaya
himalaya --version        # 验证安装
himalaya account configure # 交互式配置账户

技能的参考文档分两份，配置篇与撰写篇相互引用：

• references/configuration.md：账户配置、认证、后端设置（本文主体）；
• references/message-composition.md：MML（MIME Meta Language）邮件撰写语法。

本文聚焦前者，并补充仓库内的技能加载背景与常用命令，便于配置完成后立即上手验证。

二、配置文件位置与整体结构

Himalaya 的全局配置文件固定位于：

~/.config/himalaya/config.toml

整个文件以 TOML 的 [accounts.<名称>] 表组织，一个表对应一个账户。每个账户包含三类核心配置：

1. 账户标识：email、display-name、default；
2. 收信后端：backend.*（IMAP、Notmuch 等）；
3. 发信后端：message.send.backend.*（SMTP）。

认证信息统一挂在后端下的 auth 键中，这也是本文第三节的重点。

三、最小可用的 IMAP + SMTP 配置

参考文档给出的最小配置覆盖了"收 + 发"两端，可直接复制改参使用：

[accounts.default]
email = "[e-mail]"
display-name = "Your Name"
default = true

# IMAP backend for reading emails
backend.type = "imap"
backend.host = "imap.example.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "[e-mail]"
backend.auth.type = "password"
backend.auth.raw = "your-password"

# SMTP backend for sending emails
message.send.backend.type = "smtp"
message.send.backend.host = "smtp.example.com"
message.send.backend.port = 587
message.send.backend.encryption.type = "start-tls"
message.send.backend.login = "[e-mail]"
message.send.backend.auth.type = "password"
message.send.backend.auth.raw = "your-password"

关键参数说明：

参数	作用	说明
backend.type	收信后端类型	imap 或 notmuch（本地邮件库，见第七节）
backend.port / encryption.type	IMAP 加密通道	993 端口配 tls（直接 TLS）
message.send.backend.port / encryption.type	SMTP 加密通道	587 端口惯配 start-tls（STARTTLS 升级）
backend.login	登录名	通常等于邮箱地址，部分服务商要求本地部分
default = true	默认账户	不带 --account 时使用该账户

注意收信与发信是两条独立的后端链：收信走 backend.*（IMAP），发信走 message.send.backend.*（SMTP），二者的 host、port、认证都可以不同。

四、口令的三种管理方式（安全要点）

SKILL.md 在 Setup 一节特别强调："Prefer password managers/keyrings for credentials; do not paste secrets into chat/logs."（优先使用密码管理器或系统钥匙串存放凭证，不要把密钥粘进聊天或日志）。参考文档据此给出了三档方案，安全等级依次递增：

1. 明文口令（仅限测试，不推荐）

backend.auth.raw = "your-password"

raw 直接写在配置文件中，任何能读到该文件的人都可见，参考文档明确标注 "testing only, not recommended"，只适合一次性调试。

2. 命令取口令（推荐）

backend.auth.cmd = "pass show email/imap"
# backend.auth.cmd = "security find-generic-password -a [e-mail] -s imap -w"

auth.cmd 指向一条在运行环境可执行的命令，Himalaya 启动时执行它并取其标准输出作为口令。示例覆盖了两类主流密码管理器：

• Linux 的 pass（git-crypt/GPG 加密的密码管理工具）；
• macOS 的 security find-generic-password（直接查询系统钥匙串，-w 只输出密码值）。

这种方式让配置文件里不落任何明文密钥，且与 SKILL.md 的安全建议一致。

3. 系统钥匙串（keyring feature）

backend.auth.keyring = "imap-example"

配置后执行 himalaya account configure <account>，由 Himalaya 交互式地把口令存入系统 keyring（需要构建时启用 keyring 特性）。auth.keyring 的值是钥匙串中条目的标识名。

三者对应的配置键互斥：同一个后端下按 auth.type = "password" 搭配 raw / cmd / keyring 之一，不要混用。

五、Gmail 配置（App Password 场景）

[accounts.gmail]
email = "[e-mail]"
display-name = "Your Name"
default = true

backend.type = "imap"
backend.host = "imap.gmail.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "[e-mail]"
backend.auth.type = "password"
backend.auth.cmd = "pass show google/app-password"

message.send.backend.type = "smtp"
message.send.backend.host = "smtp.gmail.com"
message.send.backend.port = 587
message.send.backend.encryption.type = "start-tls"
message.send.backend.login = "[e-mail]"
message.send.backend.auth.type = "password"
message.send.backend.auth.cmd = "pass show google/app-password"

参数要点：

• IMAP 固定为 imap.gmail.com:993（TLS），SMTP 固定为 smtp.gmail.com:587（STARTTLS）；
• 参考文档给出的注意事项：Gmail 在开启两步验证（2FA）时必须使用 App Password（应用专用密码），普通账户密码会被拒绝；
• 收发两端的 auth.cmd 可以指向同一条命令，把应用密码存入密码管理器即可复用。

六、iCloud 配置（应用专用密码）

[accounts.icloud]
email = "[e-mail]"
display-name = "Your Name"

backend.type = "imap"
backend.host = "imap.mail.me.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "[e-mail]"
backend.auth.type = "password"
backend.auth.cmd = "pass show icloud/app-password"

message.send.backend.type = "smtp"
message.send.backend.host = "smtp.mail.me.com"
message.send.backend.port = 587
message.send.backend.encryption.type = "start-tls"
message.send.backend.login = "[e-mail]"
message.send.backend.auth.type = "password"
message.send.backend.auth.cmd = "pass show icloud/app-password"

与 Gmail 的差异：

• 服务器域名为 mail.me.com（IMAP 加 imap. 前缀，SMTP 加 smtp. 前缀）；
• 该示例未设 default = true，适合与默认账户共存，用 --account icloud 显式选用；
• 参考文档提示：需在 Apple 官方 Apple ID 站点生成应用专用密码（app-specific password）填入密码管理器。

七、文件夹别名（Folder Aliases）

不同邮件服务商对系统文件夹的命名并不统一（Sent / Sent Messages / Drafts / Junk 等），Himalaya 允许把统一别名映射到真实文件夹：

[accounts.default.folder.alias]
inbox = "INBOX"
sent = "Sent"
drafts = "Drafts"
trash = "Trash"

配置后，CLI 与 Agent 用 inbox、sent、drafts、trash 这类稳定名称操作文件夹，不必关心底层实际名称，跨服务商迁移时也更稳。

八、多账户与 --account 切换

在同一个 config.toml 中并列声明多个 [accounts.*] 表即可：

[accounts.personal]
email = "[e-mail]"
default = true
# ... backend config ...

[accounts.work]
email = "[e-mail]"
# ... backend config ...

其中只有一个账户应设 default = true。需要操作非默认账户时，在任意命令前加 --account：

himalaya --account work envelope list

SKILL.md 的 Safety 一节把这一点列为安全准则之一："Use --account when multiple accounts exist."——在 OpenClaw Agent 场景下尤其重要，避免把个人与工作邮箱的发信动作混淆。

九、Notmuch 后端（本地邮件）

Himalaya 除 IMAP 外还支持 Notmuch 本地邮件库后端，直接索引磁盘上的邮件，无需网络：

[accounts.local]
email = "[e-mail]"

backend.type = "notmuch"
backend.db-path = "~/.mail/.notmuch"

只需 backend.type = "notmuch" 与 backend.db-path 指向 Notmuch 数据库目录。该账户没有配置 message.send.backend，因此是纯本地收信/搜索场景，适合归档检索或离线工作流。

十、OAuth2 认证

对支持 OAuth2 的服务商（如企业 IdP、部分自建邮件网关），参考文档给出了完整的 token 链配置。Himalaya 本身不内置浏览器授权流程，而是把 client-secret、access-token、refresh-token 全部交给外部命令提供：

backend.auth.type = "oauth2"
backend.auth.client-id = "your-client-id"
backend.auth.client-secret.cmd = "pass show oauth/client-secret"
backend.auth.access-token.cmd = "pass show oauth/access-token"
backend.auth.refresh-token.cmd = "pass show oauth/refresh-token"
backend.auth.auth-url = "https://provider.com/oauth/authorize"
backend.auth.token-url = "https://provider.com/oauth/token"

配置要点：

• client-id 明文存放即可（非机密）；client-secret、access-token、refresh-token 一律走 *.cmd，与第四节的口令管理器模式一致，https://provider.com/... 为占位地址，需替换为服务商真实的授权端点与令牌端点；
• token 过期后的刷新由外部脚本负责（执行 token-url 换发新 token 后更新密码管理器条目），Himalaya 每次运行时从命令重新取回最新值。

十一、其他常用账户选项

签名

[accounts.default]
signature = "Best regards,\nYour Name"
signature-delim = "-- \n"

signature 是每封发出的邮件自动附加的签名内容（TOML 转义换行），signature-delim 是签名分隔行，默认形式即标准 RFC 2822 风格的 -- \n。

附件下载目录

[accounts.default]
downloads-dir = "~/Downloads/himalaya"

控制 himalaya 保存附件的落盘目录，便于 Agent 后续用文件工具处理。

撰写编辑器

交互式撰写（himalaya message write）使用 $EDITOR 环境变量的值打开编辑器：

export EDITOR="vim"

撰写流程详见姊妹篇 MML 撰写参考：编辑器打开的是一个模板，保存退出即发送、直接退出即取消；MML 标签（<#multipart>、<#part>）会在发送时编译为正式 MIME，支持附件、内嵌图片与 text/html 双版本。

十二、配置完成后：用 OpenClaw 技能验证

配置就绪后，SKILL.md 按"读/写/整理"三类给出了可直接复用的命令集，可作为 config.toml 的冒烟测试清单：

# 读/搜索
himalaya folder list
himalaya envelope list
himalaya message read <id>
himalaya envelope list from [e-mail] subject invoice

# 写
himalaya message write
himalaya template write
himalaya template send < /tmp/message.txt
himalaya message reply <id>
himalaya message forward <id>

# 整理
himalaya message copy <id> <folder>
himalaya message move <id> <folder>
himalaya message delete <id>
himalaya flag add <id> --flag seen
himalaya flag remove <id> --flag seen

SKILL.md 的 Safety 一节还要求：批量发送/删除/移动前先确认；多账户时显式带 --account；在汇总中引用消息时要使用精确的 message ID。这些正是 OpenClaw Agent 调用 Himalaya 时的行为约束。

与 OpenClaw 自带 IMAP 插件的分工

仓库中另有一个内置插件 extensions/imap（openclaw.plugin.json 中描述为 "Watch IMAP mailboxes and dispatch authenticated incoming email to isolated agent sessions"，且 enabledByDefault: false）。从源码结构看，两者定位互补：

• extensions/imap 插件：监听 IMAP 收件箱，把经过认证的来信分发给隔离的 Agent 会话，解决"收信触发"；
• Himalaya 技能：以 CLI 形式提供完整的收发能力（发信、回复、转发、归档），且 Himalaya 的配置独立存放在 ~/.config/himalaya/config.toml，与插件的 accounts.* 插件配置互不干扰。

需要说明的是，本文所有 Himalaya 参数均以仓库内参考文档 configuration.md 为准；Himalaya 的具体版本行为（如 keyring 特性是否启用、Notmuch 后端支持范围）以所用 himalaya 二进制版本为准，配置前先 himalaya --version 确认。

十三、配置自检清单

• [ ] ~/.config/himalaya/config.toml 中恰好一个账户设了 default = true；
• [ ] 收信（backend.*）与发信（message.send.backend.*）两端 host/port/加密方式均正确：IMAP 993+tls、SMTP 587+start-tls 是最常见的组合；
• [ ] 生产环境不用 auth.raw 明文口令，改为 auth.cmd（密码管理器/钥匙串命令）或 auth.keyring；
• [ ] Gmail / iCloud 已改用 App Password / 应用专用密码；
• [ ] 多账户时所有 Agent 命令显式携带 --account；
• [ ] himalaya folder list、himalaya envelope list 能正常返回，作为配置生效的最终验证。