Office 365 连接器（多账户增强版）

概述

此技能提供稳定可靠、可用于生产环境的连接，以接入Office 365 / Outlook服务，包括电子邮件、日历和联系人。现在支持多账户（v2.0.0版），您可以通过一次技能安装管理多个 Microsoft 365 身份（工作、个人、咨询等）。

它通过提供 OAuth 身份验证、自动令牌刷新、按账户隔离以及全面的 Azure 应用注册设置指南，解决了从自动化工具连接 Office 365 的常见难题。

非常适合：

• 跨组织管理多个工作身份
• 分离个人与工作电子邮件/日历
• 访问共享邮箱和委托日历
• 跨多个客户工作的顾问和自由职业者

v2.0.0 版新增功能：支持多账户！请参阅MULTI-ACCOUNT.md获取完整使用指南。

归属：由Matthew Gordon(matt@workandthrive.ai) 增强- 请参阅CREDITS.md

获取完整归属信息。

v2.0.0 版本新特性

• 由 Matthew Gordon 实现的主要增强功能：✨多账户管理
• - 通过一个技能处理多个 Microsoft 365 身份🔐按账户令牌隔离
• - 为每个账户提供独立、安全的令牌存储🔄轻松切换账户- 在所有操作中使用--account=名称
• 标志⚙️默认账户选择
• 📦传统导入工具- 无缝迁移现有的单账户设置
• 🎯账户管理命令行界面- 简单的添加/删除/列表/默认命令
• ✅完全向后兼容- 现有的单账户设置无需更改即可工作

查看CHANGELOG.md获取完整版本历史。

功能

电子邮件操作

• 读取邮件（收件箱、已发送邮件、文件夹）
• 发送邮件（支持附件、HTML格式）
• 按发件人、主题、日期范围搜索邮件
• 管理文件夹和移动邮件
• 标记为已读/未读，标记邮件
• 删除邮件

日历操作

• 读取日历事件
• 创建/更新/删除事件
• 检查可用性
• 管理会议邀请
• 支持周期性事件
• 时区处理

联系人操作

• 读取联系人和联系人文件夹
• 创建/更新/删除联系人
• 按姓名、电子邮件、公司搜索联系人
• 管理联系人群组
• 同步联系人信息

快速入门 - 多账户

添加您的首个账户

cd skills/office365-connector

# Add account
node accounts.js add work <tenant-id> <client-id> <client-secret> you@work.com "Work account"

# Authenticate
node auth.js login --account=work

添加更多账户

# Add personal account
node accounts.js add personal <tenant> <client> <secret> you@outlook.com "Personal"

# Add consulting account
node accounts.js add consulting <tenant> <client> <secret> you@client.com "Consulting"

# Set default
node accounts.js default work

# List all accounts
node accounts.js list

使用您的账户

# Check work calendar
node calendar.js today --account=work

# Read personal emails
node email.js recent 10 --account=personal

# Send from consulting account
node send-email.js send client@example.com "Subject" "Body" --account=consulting

从单账户设置迁移

已经在使用 v1.0.0 版本？没问题！

# Import your existing setup
node accounts.js import-legacy

# Continue using without changes (environment variables still work)
# OR add additional accounts
node accounts.js add secondary <tenant> <client> <secret>

先决条件

在使用此技能之前，您必须完成 Azure 应用注册设置以获取：

1. 租户 ID- 您的 Azure AD 租户标识符
2. 客户端 ID- 您的应用程序（客户端）ID
3. 客户端密码- 您的应用程序密码值

设置时间：每个账户约 10-15 分钟

请参阅设置指南获取完整的分步说明。

权限验证

此技能需要以下委托权限（需要用户同意）：

电子邮件权限

• Mail.Read- 读取用户电子邮件
• Mail.ReadWrite- 对用户电子邮件的读写权限
• Mail.Send- 以用户身份发送电子邮件

日历权限

• Calendars.Read- 读取用户日历
• Calendars.ReadWrite- 对用户日历的读写访问权限

联系人权限

• Contacts.Read- 读取用户联系人
• Contacts.ReadWrite- 对用户联系人的读写访问权限

个人资料权限（认证所需）

• User.Read- 登录并读取用户个人资料
• offline_access- 保持对数据的访问权限（刷新令牌）

重要提示：在继续设置之前，请确认您理解并批准这些权限。每个权限都授予对您 Microsoft 365 数据的特定访问权限。

请参阅权限参考以获取关于每个权限所允许操作的详细信息。

配置

多账户配置（v2.0.0+）

账户信息存储在~/.openclaw/auth/office365-accounts.json令牌位于~/.openclaw/auth/office365/目录下。

使用accounts.js命令行工具进行管理：

node accounts.js list                # List all accounts
node accounts.js add <name> ...      # Add account
node accounts.js remove <name>       # Remove account
node accounts.js default <name>      # Set default

传统单账户（向后兼容）

环境变量仍适用于单账户场景：

export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"

或在OpenClaw配置中：

{
  "env": {
    "vars": {
      "AZURE_TENANT_ID": "your-tenant-id",
      "AZURE_CLIENT_ID": "your-client-id",
      "AZURE_CLIENT_SECRET": "your-client-secret"
    }
  }
}

认证流程

本技能采用OAuth 2.0设备代码流实现稳健认证：

1. 向微软请求设备代码
2. 显示用户代码与验证网址
3. 用户访问网址并输入代码
4. 轮询令牌获取状态
5. 存储访问令牌与刷新令牌（按账户）
6. 令牌过期时自动刷新

令牌存储：令牌安全存储于~/.openclaw/auth/office365/<账户名称>.json使用模式0600（仅所有者可读写）。

使用示例

多账户邮件操作

# Read from default account
node email.js recent 10

# Read from specific account
node email.js recent 10 --account=work

# Search in consulting account
node email.js search "proposal" --account=consulting

# Send from appropriate identity
node send-email.js send client@example.com "Update" "..." --account=consulting

多账户日历操作

# Check work calendar
node calendar.js today --account=work

# Check personal calendar
node calendar.js week --account=personal

账户管理

# List all configured accounts
node accounts.js list

# Check authentication status
node auth.js status --account=work

# Re-authenticate if needed
node auth.js login --account=work

实际用例

多重工作身份

跨多个组织工作时的理想选择：

# Morning: Check all calendars
node calendar.js today --account=work
node calendar.js today --account=consulting
node calendar.js today --account=startup

# Process emails by identity
node email.js recent --account=work
node email.js recent --account=consulting

# Send from appropriate account
node send-email.js send client@bigcorp.com "Proposal" "..." --account=work

个人与职业分离

# Work hours: Work account
node calendar.js today --account=work
node email.js recent --account=work

# After hours: Personal account
node email.js recent --account=personal

错误处理

该技能包含针对以下情况的稳健错误处理：

• 令牌过期- 采用指数退避策略的自动刷新
• 速率限制- 包含适当延迟的重试逻辑
• 网络错误- 连接超时处理
• 权限错误- 关于缺失权限范围的清晰提示信息
• API错误- 来自Microsoft Graph的详细错误信息
• 未找到账户- 提供有用建议的错误信息

速率限制

Microsoft Graph API 设有速率限制：

• 应用级限制: 每小时 130,000 次请求
• 用户级限制: 根据工作负载动态调整
• 节流机制: 429 状态码触发自动重试

本技能通过指数退避机制自动处理节流。

安全考量

1. 令牌安全: 令牌存储采用受限文件权限（0600）
2. 账户隔离机制: 每个账户使用独立的令牌存储
3. 权限范围限制: 仅请求最小必要权限
4. 刷新令牌: 自动轮换机制，旧令牌即时失效
5. 客户端密钥: 永不记录或暴露；以 0600 模式存储
6. 多租户：此设置为单租户（仅限您的组织）

故障排除

多账户问题

"未指定账户且未设置默认账户"

# Set a default account
node accounts.js default work

# Or always specify --account=
node calendar.js today --account=work

"账户未找到"

# List available accounts
node accounts.js list

# Add the missing account
node accounts.js add <name> <tenant> <client> <secret>

身份验证已过期

# Check status
node auth.js status --account=work

# Re-authenticate
node auth.js login --account=work

常见问题

"AADSTS700016：在目录中未找到应用程序"

• 验证租户ID是否与您的Azure AD租户匹配
• 确保应用注册未被删除

"AADSTS65001：用户未同意授权"

• 完成设备代码流身份验证
• 若组织要求，请检查管理员同意

"AADSTS700082：刷新令牌已过期"

• 使用设备代码流重新进行身份验证
• 检查令牌存储文件的权限

"403 禁止访问"

• 验证API权限是否已在Azure中授予
• 检查是否需要管理员同意

参见安装指南和MULTI-ACCOUNT.md获取详细的故障排除信息。

限制

• 附件大小：每个附件最大 4MB（API 限制）
• 邮件收件人：每封邮件最多 500 个收件人
• 日历事件：最多可创建未来 1,095 天的事件
• 批量操作：每批次最多 20 个请求

命令参考

账户管理

node accounts.js list                           # List all accounts
node accounts.js add <name> <tenant> <client> <secret> [email] [desc]
node accounts.js remove <name>                  # Remove account
node accounts.js default <name>                 # Set default
node accounts.js import-legacy                  # Import v1.0.0 setup

认证

node auth.js login [--account=name]            # Authenticate
node auth.js status [--account=name]           # Check status
node auth.js token [--account=name]            # Get access token

邮件

node email.js recent [count] [--account=name]
node email.js search "query" [--account=name]
node email.js from email@domain [--account=name]
node email.js read <id> [--account=name]

日历

node calendar.js today [--account=name]
node calendar.js week [--account=name]

发送与管理

node send-email.js send <to> <subject> <body> [--account=name]
node send-email.js reply <message-id> <body> [--account=name]
node cancel-event.js <event-id> [comment] [--account=name]

资源

文档文件

• MULTI-ACCOUNT.md- 完整的多账户使用指南
• CHANGELOG.md- 版本历史与更新
• CREDITS.md- 归属与致谢
• references/setup-guide.md- Azure应用注册分步指南
• references/permissions.md- 安全与权限参考

Microsoft资源

• Microsoft Graph API文档：https://learn.microsoft.com/en-us/graph/api/overview
• 委托权限与应用权限：https://learn.microsoft.com/en-us/graph/auth/auth-concepts
• 速率限制：https://learn.microsoft.com/en-us/graph/throttling

致谢

原始技能：来自ClawHub社区的office365-connector v1.0.0

多账户增强版 (v2.0.0)：Matthew Gordon (matt@workandthrive.ai)

感谢马修·戈登（Matthew Gordon）贡献了多账户增强功能，这使得这项技能对于顾问、自由职业者以及任何需要管理多个工作身份的人来说都大大提升了实用性！

参见CREDITS.md以获取完整的贡献者名单。

许可证

保持与原技能许可证的兼容性。详情请参见CREDITS.md文件。