Outlook Entra — SKILL.md

通过 OAuth 2.0（设备代码流）接入 Microsoft Outlook，并调用 Microsoft Graph API。
只读权限 — 仅使用 Mail.Read、Calendars.Read 和 Contacts.Read 权限。

前置条件

• 已在 Entra（Azure AD）中注册应用，并配置以下权限：
  • Mail.Read、Calendars.Read、Contacts.Read
  • 启用 OAuth 2.0 设备代码流（device code flow）
• Python 3.8+，并安装 requests、html2text、cryptography
• Python 3.8+，且在 skill 目录下已创建 .venv 虚拟环境（命令示例：uv venv .venv && uv pip install html2text requests cryptography）
• 已配置 .env 文件（参见 .env.example）

安装

# 创建虚拟环境（必需）
cd ~/.openclaw/workspace/skills/outlook-entra
uv venv .venv
uv pip install html2text requests cryptography

# 复制并编辑配置文件
cp .env.example .env
# ⚠️ 在 .env 中填写 client_id、client_secret 和 tenant_id

认证流程（Device Code Flow）

设备代码流（RFC 8628）仅需用户一次性手动介入。

步骤 1 — 运行认证脚本

.venv/bin/python scripts/outlook_auth.py

该脚本将执行以下操作：

1. 向 Microsoft 请求设备代码（device code）
2. 输出用户代码及验证 URL

步骤 2 — 手动完成认证

访问 https://login.microsoft.com/device，输入上一步显示的代码。
有效时限：最多 15 分钟。

步骤 3 — 等待确认结果

脚本将持续轮询 Microsoft 的 token endpoint，直至成功获取访问令牌（access token）。
认证成功后，令牌将被本地持久化保存。

令牌工作机制

• access_token 有效期约为 1 小时
• refresh_token 可用于在无需用户介入的前提下，自动换取新的 access_token
• 刷新操作由 cron 定时任务每小时自动触发（详见「Cron」章节）
• 若 refresh_token 也已过期（例如因数月未使用），则需重新执行完整认证流程

常用命令

# 查看当前令牌状态
.venv/bin/python scripts/outlook_auth.py --status

# 手动刷新令牌
.venv/bin/python scripts/outlook_refresh.py

# 撤销并删除本地令牌
.venv/bin/python scripts/outlook_auth.py --revoke

只读命令列表

# 查看连接状态
.venv/bin/python scripts/outlook_auth.py --status

# 获取收件箱最新邮件（前 10 封）
.venv/bin/python scripts/outlook_graph.py messages --folder Inbox --top 10

# 查看某封邮件详情（默认输出 Markdown 格式正文）
.venv/bin/python scripts/outlook_graph.py message 

# 以原始 HTML 格式输出邮件正文（适用于内容提取或粘贴）
.venv/bin/python scripts/outlook_graph.py message  --raw

# 列出所有邮箱文件夹
.venv/bin/python scripts/outlook_graph.py folders

# 列出某封邮件的所有附件
.venv/bin/python scripts/outlook_graph.py attachments 

# 下载指定附件
.venv/bin/python scripts/outlook_graph.py download  --attach-id  --output /path/to/file

# 获取日历事件（前 10 条）
.venv/bin/python scripts/outlook_graph.py events --top 10

# 获取联系人（前 20 个）
.venv/bin/python scripts/outlook_graph.py contacts --top 20

# 邮件关键词搜索
.venv/bin/python scripts/outlook_graph.py search "keyword"

# 获取当前用户个人资料
.venv/bin/python scripts/outlook_graph.py profile

环境变量（.env）

skill 目录结构

outlook-entra/
├── SKILL.md
├── README.md
├── .env.example
├── .gitignore
├── .venv/                   # Python 虚拟环境（通过 uv venv 创建）
├── scripts/
│   ├── outlook_auth.py      # 实现 OAuth 设备代码流、状态查询与令牌撤销
│   ├── outlook_graph.py     # 调用 Microsoft Graph API（只读操作）
│   ├── outlook_refresh.py   # 自动刷新令牌（供 cron 调用）
│   └── outlook_token.py     # 共享模块（封装令牌读取与刷新逻辑）
└── tests/
    └── test_outlook.py      # 单元测试

注意事项

• 设备代码流（RFC 8628）：用户需访问 https://microsoft.com/devicelogin 并输入一次性代码，全程仅需操作一次。
• 刷新令牌（refresh tokens）：当 access_token 过期时，系统将自动使用 refresh_token 获取新令牌。
• 若设置了 TOKEN_FILE_KEY，所有令牌将以 AES-GCM 方式加密后写入磁盘。
• Microsoft Graph API 返回 401 错误时，将自动触发令牌刷新流程。

Cron — 自动令牌刷新

outlook_refresh.py 脚本会检查当前令牌是否即将过期，并在必要时自动刷新。

Crontab 配置 — 每小时 HH:55 执行一次：

55 * * * * /home/fred-ghilini/.openclaw/workspace/skills/outlook-entra/.venv/bin/python /home/fred-ghilini/.openclaw/workspace/skills/outlook-entra/scripts/outlook_refresh.py >> /home/fred-ghilini/.openclaw/outlook_refresh.log 2>&1

安装命令：

SKILL_DIR="/home/fred-ghilini/.openclaw/workspace/skills/outlook-entra"
( crontab -l 2>/dev/null | grep -v outlook_refresh; echo "55 * * * * ${SKILL_DIR}/.venv/bin/python ${SKILL_DIR}/scripts/outlook_refresh.py >> ~/.openclaw/outlook_refresh.log 2>&1" ) | crontab -

验证是否安装成功：

crontab -l | grep outlook_refresh

参考资料

• OAuth 2.0 Device Code Flow — Microsoft
• Microsoft Graph — Mail API
• Microsoft Graph — Calendar API