QQ Mail Codex 配置指南

安装并验证一个可复用的 QQ Mail 桥接器（bridge）以供 Codex 使用。优先使用配套的安装脚本和冒烟测试（smoke-test）脚本，而非临时编写的终端命令片段，以确保配置过程可重复，并规避 Windows 平台常见的编码问题。

工作流程

1. 选择安装目录。 默认路径为 ~/Documents/skills/qq-mail-mcp；除非用户已指定其他偏好路径，否则采用该默认值。

2. 安装或刷新本地 MCP 桥接器。 执行以下命令：

powershell -File "$HOME/.codex/skills/qq-mail-codex-setup/scripts/install_qq_mail_mcp.ps1"

若用户希望使用非默认目录，请传入 -InstallDir 参数。该安装脚本将完成以下操作：从 assets/qq-mail-mcp-template 复制预置模板、执行 npm install、在必要时基于 .env.example 创建 .env 文件、移除任何已存在的过期 qq_mail 条目，并通过 codex mcp add 重新注册 MCP 服务。

3. 填写凭据信息。 若 /.env 中存在缺失值，则向用户索取以下两项内容：

• QQ_MAIL_USER
• QQ_MAIL_AUTH_CODE

请使用 QQ Mail 的授权码（authorization code），而非 QQ 账户密码。

4. 运行冒烟测试。 调用封装脚本：

powershell -File "$HOME/.codex/skills/qq-mail-codex-setup/scripts/run_qq_mail_smoke_test.ps1" -Mode all

常用测试模式如下：

• -Mode check：仅验证 IMAP 登录与 SMTP 连通性
• -Mode latest：获取 INBOX 中最新一封邮件的摘要信息
• -Mode send-self-test：发送一条纯 ASCII 编码的自测邮件
• -Mailbox ：对非 INBOX 的指定邮箱文件夹执行测试
• -To 和 -Subject ：自定义自测邮件的收件人地址与主题

5. 汇总执行结果。 需报告以下信息：

• 安装目录路径
• .env 文件是新建还是复用
• qq_mail 是否已出现在 codex mcp list 输出中
• 如请求了最新邮件摘要，则输出其内容
• 发信测试是否成功

相关文件

• scripts/install_qq_mail_mcp.ps1：用于安装或刷新本地 QQ Mail MCP 桥接器
• scripts/run_qq_mail_smoke_test.ps1：执行连接性、收件箱及发信功能的冒烟测试
• assets/qq-mail-mcp-template/：本地 MCP 项目模板，将在安装过程中复制至目标目录
• references/qq-mail-troubleshooting.md：仅当配置或测试失败，或用户主动要求诊断细节时查阅

安全约束（Guardrails）

• 优先使用配套脚本，避免临时内联的 Node.js 命令片段。
• 测试邮件内容默认限制为 ASCII 字符；仅当用户明确要求发送中文内容，且你可通过 UTF-8 安全的基于文件的脚本实现时，才允许例外。
• 最终响应中不得暴露授权码（authorization code）。
• 若测试失败，请先查阅 references/qq-mail-troubleshooting.md，再决定是否采取其他措施。

示例请求

• 将我的 QQ 邮箱接入 Codex，并验证其能否读取新邮件。
• 修复 qq_mail MCP 的配置。
• 在 Codex 中配置 QQ Mail，并向我发送一封确认邮件。