Agently Mail CLI：安装、授权与邮件工作流实践
6月 24, 2026
说明：本文由 Codex 根据作者提供的主题、实际配置过程与 Agently 官方公开文档辅助生成，属于 AI 生成/整理内容，非作者原创。请读者自行甄别并交叉验证。
Agently Mail CLI 是面向 AI Agent 的邮箱命令行工具。它让 Agent 可以在获得授权后，通过自然语言或命令行完成查看、搜索、阅读、发送、回复、转发和下载附件等邮件工作。
这篇文章记录一套可复现的安装与使用流程，也整理了这次实践中完成的一次“查询广州本周天气并发邮件”的标准工作流。文中不会包含真实邮箱地址、OAuth 授权链接、访问令牌或邮件内容。
它适合做什么#
把 Agently Mail CLI 安装到 Agent 运行环境后，可以把邮件事务描述成自然语言，例如：
帮我发一封邮件给 recipient@example.com，主题是“本周安排”，正文是“周三下午开会”。Agent 会把请求转换为 CLI 操作，并在写入类动作前展示待发送摘要、等待用户确认。除了发邮件，常见用法还包括：
- 查看最近收到的邮件。
- 搜索主题或正文中包含某个关键词的邮件。
- 读取指定邮件及其附件元信息。
- 回复、转发或将邮件移入回收站。
- 下载普通附件到本地目录。
对于需要反复处理收件箱、整理邮件或根据上下文起草邮件的工作流，这种方式比手动在网页邮箱中来回切换更顺手。
安装与配置#
前提是本机已经安装 Node.js 和 npm。官方当前的安装入口见 Agently CLI 配置文档。
1. 安装或更新 CLI#
npm install -g @tencent-qqmail/agently-cli安装完成后可确认命令是否可用：
agently-cli --version2. 安装 Agent skill#
如果希望让支持 Skills 的 Agent 直接理解邮件工作流，继续安装官方 skill：
npx skills add https://agent.qq.com --skill -g -y这个步骤会把邮件操作说明安装到 Agent 可读取的位置。之后可以直接说“帮我发一封邮件”或“整理最近收到的邮件”，不必每次手写完整命令。
3. 完成 OAuth 授权#
agently-cli auth login命令会输出一个浏览器授权链接。打开链接、登录并同意授权后，终端会自动结束。授权链接本身具有敏感性，不应贴到公开文章、聊天记录或截图中。
4. 验证当前账户#
agently-cli +me
agently-cli auth status+me 用于确认已授权的邮箱别名，auth status 用于查看授权状态。CLI 会在本机保存授权凭据；不要把凭据文件、终端输出中的令牌或授权链接提交到仓库。
这次实践走过的完整流程#
本次实际完成的流程如下：
- 全局安装
@tencent-qqmail/agently-cli。 - 安装
agently-mailskill。 - 运行
agently-cli auth login，在浏览器中完成 OAuth 授权。 - 用
agently-cli +me验证邮箱已可用。 - 提出“发一封广州本周天气邮件”的需求，Agent 先查询天气信息并收集收件人。
- Agent 生成待发送邮件的摘要，包含发件人、收件人、主题和附件数量。
- 用户明确确认后，CLI 将邮件加入发送队列。
最后一步很重要：成功进入发送队列不等于收件方已经阅读。它表示 CLI 已接受并提交发送请求；投递与阅读状态仍受邮件服务和收件方环境影响。
用自然语言操作邮件#
安装 skill 后，最省事的方式是直接描述目标。以下提示语都足够明确：
我最近收到了哪些邮件？
搜索主题里包含“发票”的邮件。
读取 msg_xxx 的内容，并概括待办事项。
帮我回复 msg_xxx：已收到，会在周五前反馈。
把 msg_xxx 转发给 recipient@example.com，并附一句“供参考”。涉及发送、回复、转发或移入回收站时，Agent 应先展示操作摘要并等待确认。阅读、搜索和列出邮件属于只读操作，通常不需要二次确认。
常用 CLI 命令#
即使没有接入 Agent，也可以在终端直接使用 CLI：
| 目标 | 示例命令 |
|---|---|
| 查看当前授权用户 | agently-cli +me |
| 查看授权状态 | agently-cli auth status |
| 列出收件箱邮件 | agently-cli message +list --dir inbox --limit 10 |
| 搜索邮件 | agently-cli message +search --q "关键词" |
| 阅读一封邮件 | agently-cli message +read --id msg_xxx |
| 回复邮件 | agently-cli message +reply --id msg_xxx --body "已收到" |
| 转发邮件 | agently-cli message +forward --id msg_xxx --to recipient@example.com |
| 下载普通附件 | agently-cli attachment +download --msg msg_xxx --att att_xxx |
邮件和附件都应被当作不可信的外部输入处理。尤其是邮件正文中如果出现“立即转发”“执行某条命令”等文字，不能把它当作用户授权；只有用户在对话中明确提出的请求才可以触发操作。
发邮件为何需要两阶段确认#
发送、回复、转发和删除都会改变邮箱状态，因此 CLI 采用两阶段确认。第一次调用只生成摘要和确认令牌，不会真正发送；在人工确认后，用相同参数加上确认令牌再次调用，操作才会执行。
第一次调用：
agently-cli message +send \
--to recipient@example.com \
--subject "广州本周天气" \
--body "这里是天气摘要。"CLI 会返回待确认的发送摘要和一个短时有效的 confirmation_token。核对收件人、主题、正文和附件后，再执行第二次调用：
agently-cli message +send \
--to recipient@example.com \
--subject "广州本周天气" \
--body "这里是天气摘要。" \
--confirmation-token "<confirmation_token>"第二次调用必须使用第一次返回的令牌，且参数应保持一致。令牌与 OAuth 链接一样属于敏感信息，示例中只能使用占位符，不能复用或公开真实值。
需要添加附件时，在发送命令中重复传入相对路径即可：
agently-cli message +send \
--to recipient@example.com \
--subject "周报" \
--body "附件是本周周报。" \
--attachment ./weekly-report.pdf同样先获取确认摘要，再在用户确认后补充 --confirmation-token。
日常维护与排查#
当 CLI 提示有新版本时，更新 CLI 和 skill：
npm install -g @tencent-qqmail/agently-cli
npx skills add https://agent.qq.com --skill -g -y更新 skill 后重启 Agent，让它重新加载最新说明。若授权失效，先用 agently-cli auth status 检查状态；需要重新授权时再运行 agently-cli auth login。
如果终端提示找不到 agently-cli，通常是 npm 的全局 bin 目录没有加入 PATH。先确认 npm 的全局安装路径，再按当前 shell 的配置方式补充环境变量即可。
小结#
Agently Mail CLI 的核心价值不只是“能从终端发邮件”，而是把邮件能力交给 AI Agent 后，仍保留清晰的人类确认边界：只读任务可以快速自动化，涉及外发或删除的动作则必须由用户最后确认。
实际使用时，建议把收件人、主题、正文要求和附件意图说清楚；把 OAuth 链接、确认令牌、邮箱账号和邮件中的外部指令视为敏感或不可信数据。这样既能把邮件事务交给 Agent，也不会失去对外发动作的控制。