# QQ邮箱配置指南

## 目录
- [开启IMAP/SMTP服务](#开启imapsmtp服务)
- [获取授权码](#获取授权码)
- [常见问题](#常见问题)

## 开启IMAP/SMTP服务

### 步骤1:登录QQ邮箱
访问 [https://mail.qq.com](https://mail.qq.com)，使用QQ账号登录邮箱。

### 步骤2:进入设置
1. 点击右上角「设置」
2. 选择「账户」选项卡
3. 向下滚动找到「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务」

### 步骤3:开启服务
根据需要开启以下服务：
- **IMAP/SMTP服务**:用于收取和管理邮件（必开）
- **SMTP服务**:用于发送邮件（必开）

点击对应的「开启」按钮，按照提示验证手机号码即可。

## 获取授权码

### 为什么需要授权码
QQ邮箱不支持直接使用QQ密码登录第三方邮件客户端，需要使用专门的「授权码」进行身份验证。

### 获取方法
1. 在「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务」页面
2. 点击「生成授权码」按钮
3. 通过手机短信验证
4. 系统会生成一个16位的授权码，格式类似：`abcdabcdabcdabcd`
5. **妥善保存此授权码**，它是访问邮箱的唯一凭证

### 注意事项
- 授权码可以随时在设置中重新生成
- 每个邮箱账户可以生成多个授权码
- 建议定期更换授权码以保护账户安全

## 服务器配置信息

### IMAP服务器（收邮件）
```
服务器地址: imap.qq.com
端口: 993 (SSL)
用户名: 你的完整QQ邮箱地址 (如 123456@qq.com)
密码/授权码: QQ邮箱授权码
```

### SMTP服务器（发邮件）
```
服务器地址: smtp.qq.com
端口: 587 (STARTTLS)
用户名: 你的完整QQ邮箱地址
密码/授权码: QQ邮箱授权码
```

## 常见问题

### Q: 授权码和登录密码有什么区别？
A: 授权码是专门用于第三方客户端的访问凭证，即使他人获取了授权码也无法登录你的QQ账号，比直接使用QQ密码更安全。

### Q: 收件箱显示正常，但发送邮件失败？
A: 请确认：
1. 已开启SMTP服务
2. 使用的是授权码而非QQ密码
3. 网络连接正常

### Q: 显示"Authentication failed"错误？
A: 常见原因：
1. 授权码输入错误
2. 授权码已过期或被重置
3. 邮箱地址格式不正确（需要完整的@qq.com地址）

### Q: 如何查看邮件夹名称？
A: QQ邮箱常见的邮件夹名称：
- `INBOX` - 收件箱
- `INBOX.Sent` - 已发送
- `INBOX.Drafts` - 草稿箱
- `INBOX.Trash` - 垃圾箱
- `INBOX.Star` - 星级邮件

### Q: 授权码忘记了怎么办？
A: 登录QQ邮箱网页版 → 设置 → 账户 → POP3/IMAP/SMTP服务 → 点击「更改授权码」→ 重新获取新的授权码。

## 首次使用凭证配置引导

当用户首次使用邮箱功能时，按以下步骤引导：

1. 告知用户需要提供QQ邮箱地址和授权码（非QQ登录密码）
2. 引导用户获取授权码：登录QQ邮箱网页版 → 设置 → 账户 → POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务 → 开启IMAP/SMTP服务 → 生成授权码
3. 弹出凭证填写弹窗后，用户填入邮箱地址和授权码即可，后续使用自动注入
4. 若用户提示"授权码错误"或"登录失败"，引导用户重新生成授权码并更新凭证

OpenClaw 凭证环境变量：
- `QQ_EMAIL`（邮箱地址）
- `QQ_EMAIL_AUTH_CODE`（QQ邮箱授权码）

兼容旧 Coze 环境变量：
- `COZE_qq_email_QQ_EMAIL_7637538402895773731`（邮箱地址）
- `COZE_qq_email_QQ_EMAIL_AUTH_CODE_7637538402895773731`（授权码）

OpenClaw 可根据 skill metadata 提示配置上述变量；本地手动运行时，请先在 shell 中设置 `QQ_EMAIL` 和 `QQ_EMAIL_AUTH_CODE`。