最近我把 ClawEmail 的官方 CLI 文档狠狠干了一遍。
说实话，官方文档不是不能看，但真要拿来直接上手，还是有点碎。尤其是你如果第一次接触 mail-cli，很容易看着一堆命令，脑子里只剩一句话：所以我到底该先干嘛？
这篇我就不跟你绕概念了，直接把最常用的一条路给你捋顺：怎么把 mail-cli 跑起来，怎么登录，怎么创建子邮箱，怎么查信、读信、发信，最后再补上实时监听新邮件。
如果你就是想把 ClawEmail 这套 CLI 真正用起来，这篇照着做就行。
先说结论
mail-cli 不是那种“看起来很强，实际上用起来很拧巴”的工具。
它真正有用的地方在于两件事：
第一，你可以直接用命令行管理 Claw Agent 邮箱，比如创建子邮箱、启用禁用、切 profile。
第二，你可以把它接进自己的工作流里，做查信、收附件、自动收件、自动转发，甚至接到 AI 处理链路里。
但前提也很明确：你得先把认证和 profile 这层搞明白。
很多人不是不会用，是一上来就跳到 mail list、compose send，结果前面的钥匙还没插进门里。
一、先准备环境
官方文档写得很直接，环境要求只有两个：
- Node.js >= 18
- npm 或 pnpm
先在终端里检查一下自己的 Node 版本：
node -v
npm -v如果你的 Node 还在 16，或者更老，那先升级。
这一步别省。
后面很多命令你以为是登录问题，最后其实是运行环境太旧。
二、确认你已经装好 mail-cli
如果你已经装过，先看看命令能不能正常出来：
mail-cli --help能正常显示帮助信息，就说明 CLI 已经在了。
如果你本机还没装，优先按 Claw 官方给的安装方式来，不要自己乱猜包名到处装。先保证你拿到的是官方这套 mail-cli。
装完之后，我建议你再跑一次：
mail-cli debug:config这个命令很有用，它会告诉你：
- 当前配置文件路径
- 当前 profile 名称
- 当前 profile 对应的邮箱用户
- 当前 transport
你后面如果遇到“为什么我明明登录了却查不到信”，很多时候就是 profile 切错了，这个命令能第一时间帮你定位。
三、第一步不是查信，是先配 API Key
这个地方很容易绕进去。
Claw Agent 邮箱管理，比如创建子邮箱、启用禁用、删除这些，不是光登录邮箱就行，还需要先配 API Key。
命令如下：
mail-cli auth apikey set <你的_ck_live_key>如果你以后想移除，也有对应命令：
mail-cli auth apikey remove按照官方文档，这个 Key 不会明文裸奔在配置里，而是存到系统钥匙串里，再由 config.json 去引用。
这一点还不错。
至少不是那种一打开配置文件，密钥直接糊你脸上的路子。
四、登录你的 Claw 主账户
配完 API Key 后，再登录主账户。
最常用的是这条：
mail-cli auth login --user yourname@claw.163.com如果你想让它用当前配置直接登录，也可以：
mail-cli auth login登录完之后，别急着做别的，先测试认证状态：
mail-cli auth test如果认证正常，它会告诉你当前认证可用。
如果你想退出登录：
mail-cli auth logout这一步建议你养成习惯：每次怀疑自己到底有没有登录成功，先跑 auth test。
别一头扎进后面几十个命令里瞎试。
五、先看看你现在手里有哪些邮箱
主账户登录完，先列出现有邮箱：
mail-cli clawemail list如果你更喜欢 JSON 输出，方便后面脚本处理：
mail-cli clawemail list --json这一步的意义很简单。
先确认当前工作区下到底有哪些邮箱，尤其是你后面要创建子邮箱、切 profile、做自动化的时候，不先盘清楚，后面很容易乱。
六、创建一个子邮箱，跑通 Agent 邮箱管理
如果你想给不同 Agent、不同任务分邮箱，那这一步就是核心。
官方文档里创建子邮箱的命令是：
mail-cli clawemail create --prefix bot1 --type sub --display-name "My Bot"几个关键参数你要知道：
--prefix：邮箱前缀，1 到 64 个字符--type：邮箱类型，primary或sub--display-name：显示名称
正常情况下，最常用的就是 sub。
比如你想单独给日报、客服、自动回复这类流程分邮箱，就别全挤在主邮箱里。
这里有个重点，很多人会漏掉：
创建成功后，CLI 会自动往配置文件里加新的 profile。
也就是说，你后面可以直接这样切过去用：
mail-cli --profile bot1 mail list --fid INBOX另外官方还提到一个细节：创建成功后会显示授权码，而且只显示一次。
这个一定记得保存。
别等窗口关了，再回来拍大腿。
七、列出文件夹，确认 INBOX 是否正常
邮箱能不能正常工作，最简单的验证方式，不是上来发邮件，而是先看文件夹。
mail-cli folder list或者：
mail-cli folder list --json如果这一步都不正常，后面的 mail list、mail search 基本也别指望。
而且你后面很多命令都要用到 --fid，也就是文件夹 ID 或路径。
最常见的当然就是 INBOX。
八、正式开始查信
1）列出收件箱邮件
最基础命令：
mail-cli mail list --fid INBOX限制数量、按时间倒序看最近邮件：
mail-cli mail list --fid INBOX --limit 20 --desc只看未读：
mail-cli mail list --fid INBOX --unread --order date这里的重点就一个：
--fid 基本别忘。
尤其你后面如果不止一个邮箱、或者接的是 IMAP 场景，不写这个，很多问题都不好排查。
2）获取某一封指定邮件
如果你已经知道邮件 ID，可以直接取：
mail-cli mail get --ids "msg1"多封一起取：
mail-cli mail get --ids "msg1,msg2"如果是 IMAP 账户，记得补上文件夹：
mail-cli mail get --ids "msg1" --fid INBOX九、搜索邮件，比翻列表省事多了
这个命令我觉得挺实用，尤其当你的邮箱已经不是“空空如也”的时候。
按关键词搜索：
mail-cli mail search --fid INBOX --keyword "report" --limit 10按发件人筛：
mail-cli mail search --fid INBOX --from "boss@example.com" --unread按主题筛：
mail-cli mail search --fid INBOX --subject "Weekly Report"如果你想搜正文内容，用全文搜索：
mail-cli mail search --fid INBOX --keyword "invoice" --fts这里我单独提醒一句。
默认的 --keyword 主要搜的是主题、发件人、收件人这些字段；你加上 --fts，才会往正文里搜。
如果你不理解这个区别，就会很容易出现一种错觉：明明这封邮件正文里有这个词，为什么搜不出来？
因为你压根没开全文搜索。
十、读邮件正文、头信息、附件结构
这部分是我觉得官方文档写得还算清楚的一块，但很多人没串起来。
正确姿势其实是：先看正文，再看头，再看结构，需要附件时最后下附件。
1）查看正文
查看转换后的纯文本正文：
mail-cli read body --id <message-id>如果你想看原始 HTML：
mail-cli read body --id <message-id> --raw如果你想把 HTML 保存到文件：
mail-cli read body --id <message-id> --out-file body.htmlIMAP 场景补 --fid：
mail-cli read body --id <message-id> --fid INBOX2）查看邮件头
mail-cli read header --id <message-id>或者：
mail-cli read header --id <message-id> --fid INBOX这个适合你查发件人、收件人、主题、日期这些头信息。
3）查看 MIME 结构
mail-cli read structure --id <message-id>或者：
mail-cli read structure --id <message-id> --fid INBOX这一步别嫌麻烦。
因为你如果要下载附件，通常得先从这里拿到 part id。
十一、下载附件
查完结构后，就可以下附件了。
下载到当前目录：
mail-cli read attachment --id <message-id> --part <part-id>保存成指定文件名：
mail-cli read attachment --id <message-id> --part <part-id> --out-file report.pdf保存到某个目录：
mail-cli read attachment --id <message-id> --part <part-id> --out-file ./downloads/IMAP 场景同样记得带上：
mail-cli read attachment --id <message-id> --part <part-id> --fid INBOX如果你一上来就下载附件，却不知道 part-id 是什么，那不是命令有问题，是顺序错了。
先 read structure。
再下。
十二、发一封测试邮件，验证你的链路真的通了
很多教程写到这儿就收工了。
我个人不太建议。
因为“能登录”和“真的能收发”不是一回事。
最简单的测试发送：
mail-cli compose send --to "a@example.com" --subject "Hello" --body "World"带抄送、密送：
mail-cli compose send --to "a@b.com" --cc "c@d.com" --bcc "e@f.com" --subject "Test" --body "Hi"发送 HTML：
mail-cli compose send --to "a@b.com" --subject "HTML" --body "<h1>Hello</h1>" --html从文件读正文：
mail-cli compose send --to "a@b.com" --subject "Report" --body-file ./email.html --html带附件：
mail-cli compose send --to "a@b.com" --subject "Files" --body "See attached" --attach report.pdf --attach data.csv设优先级：
mail-cli compose send --to "a@b.com" --subject "Urgent" --body "!" --priority 1我建议你第一次测试时，先别玩太复杂。
就用最基础的 --to + --subject + --body，先确认能正常送达，再慢慢加附件、HTML、抄送这些东西。
十三、回复和转发也有现成命令
回复邮件：
mail-cli compose reply --id <message-id> --fid INBOX --body "收到，我稍后处理。"回复所有人：
mail-cli compose reply --id <message-id> --fid INBOX --body "收到" --all带原附件回复：
mail-cli compose reply --id <message-id> --fid INBOX --with-attachments --body "请查收"转发邮件：
mail-cli compose forward --id <message-id> --fid INBOX --to ops@example.com按附件模式转发：
mail-cli compose forward --id <message-id> --fid INBOX --to ops@example.com --mode attach这一套对于自动化工作流很实用。
比如某个子邮箱专门收监控告警、账单、日报，你拿到邮件后，筛一下，再自动回、自动转，就能省很多手工动作。
十四、最有意思的一块：实时监听新邮件
如果你只是拿 mail-cli 当一个命令行邮箱客户端，那前面已经够用了。
但如果你想把它接进 Agent 工作流，那真正关键的是这个：
mail-cli mail watch更安静一点，只保留数据流输出：
mail-cli mail watch --quiet输出原始 WebSocket 包：
mail-cli mail watch --raw切 profile 监听：
mail-cli --profile work mail watch --quiet官方文档这里给的信息挺值钱。
mail watch 默认会输出 NDJSON，也就是每来一封邮件，就往 stdout 打一行 JSON。里面已经带了常用字段，比如：
idfromtosubjectdatetexthtmlattachmentsheaderRaw
这意味着什么？
意味着你根本不用再手搓一套轮询逻辑去查新邮件了。
你可以直接把这个数据流接给 AI、脚本、自动化处理器。
比如新邮件来了，先判断是不是需要回复；需要的话，生成草稿；不需要的话，直接归档。这个路子就顺了。
十五、几个你八成会踩的坑，我提前给你拎出来
1）没配 API Key，就去跑 clawemail create
这属于典型的顺序错了。
先 auth apikey set，再去做 Agent 邮箱管理。
2）忘了 --fid
尤其是 IMAP 场景。
很多读信、查信、附件相关命令，不带 --fid，问题会特别难定位。
3）把 --keyword 当全文搜索用
默认不是。
想搜正文，要加 --fts。
4）创建子邮箱后没保存授权码
文档里说得很清楚，这个东西只显示一次。
你不保存，后面就别怪自己重走流程。
5）直接把 mail watch 跑在前台长期挂着
能挂，但不优雅。
如果你后面是接 Hermes、脚本、守护进程，最好按后台任务的方式去管理，不然一个断线、一个窗口关闭，就容易中断。
官方文档里也写了，它的重连策略是：1 秒、2 秒、4 秒、8 秒、16 秒，超过 5 次失败后退出。
所以它不是无限复活的神仙进程，这点你得心里有数。
十六、如果你只想最快跑通，照这个顺序来
我给你压成最短流程：
第一步：配置 API Key
mail-cli auth apikey set <你的_ck_live_key>第二步：登录主邮箱
mail-cli auth login --user yourname@claw.163.com
mail-cli auth test第三步：列出现有邮箱
mail-cli clawemail list第四步：创建一个子邮箱
mail-cli clawemail create --prefix bot1 --type sub --display-name "My Bot"第五步：查看文件夹和收件箱
mail-cli folder list
mail-cli --profile bot1 mail list --fid INBOX --limit 20 --desc第六步：发一封测试邮件
mail-cli --profile bot1 compose send --to user@example.com --subject "Hi" --body "Hello from bot"第七步：需要自动化时，再接 watch
mail-cli --profile bot1 mail watch --quiet这一套跑完，你对 mail-cli 的感觉就不会再停留在“文档里看过”。
而是真的能用了。
最后说我的判断
我个人看法很直接：ClawEmail 这套 mail-cli，真正适合的不是“偶尔点两下邮箱的人”，而是已经开始做 Agent、多邮箱分工、自动收发、消息流转的人。
如果你只是想偶尔看两封信，用网页端当然更省事。
但如果你已经开始折腾 Hermes、OpenClaw、子 Agent、自动日报、自动收件分类这些东西，那 mail-cli 这套命令行入口，价值就一下子出来了。
因为它不是单纯让你“在终端里收邮件”。
它是在给你一个可编排的邮箱接口。
这俩不是一回事。
所以我的建议是：
别一上来把整本文档从头背到尾。先按我上面的最短流程跑通一遍。
跑通之后，你再回头补 reply、forward、attachment、watch 这些能力，速度会快很多。
不然很容易变成：文档看了不少，命令记了不少，真正能用起来的流程，一个没落地。
这就有点亏了。