Microsoft Teams（插件） ​

“Enter here, abandon all hope.”

更新日期：2026-01-21

状态：支持文本 + DM 附件；频道/群组文件发送需要 + Graph 权限（见在群组聊天中发送文件）。投票通过 Adaptive Cards 发送。

Microsoft Teams 作为插件提供，不与核心安装捆绑。

重大更改（2026.1.15）： MS Teams 从核心移出。如果你使用它，必须安装插件。

解释：保持核心安装更轻量，并让 MS Teams 依赖项独立更新。

通过 CLI 安装（npm 注册表）：

本地检出（从 git 仓库运行时）：

如果在配置/入职期间选择 Teams 并检测到 git 检出，OpenClaw 会自动提供本地安装路径。

详情：插件

1. 安装 Microsoft Teams 插件。
2. 创建一个 Azure Bot（应用 ID + 客户端密钥 + 租户 ID）。
3. 使用这些凭证配置 OpenClaw。
4. 公开 （默认端口 3978）通过公共 URL 或隧道。
5. 安装 Teams 应用包并启动网关。

最小配置：

注意：默认情况下群组聊天被阻止（）。要允许群组回复，设置 （或使用 允许任何成员，仍受提及门控）。

• 通过 Teams DM、群组聊天或频道与 OpenClaw 对话。
• 保持路由确定性：回复始终返回到它们到达的通道。
• 默认安全频道行为（需要提及，除非另行配置）。

默认情况下，Microsoft Teams 允许通过 触发的配置更新（需要 ）。

禁用：

DM 访问

• 默认：。未知发送者在批准前被忽略。
• 接受 AAD 对象 ID、UPN 或显示名称。向导在凭证允许时通过 Microsoft Graph 将名称解析为 ID。

群组访问

• 默认：（除非你添加 ，否则被阻止）。在未设置时使用 覆盖默认值。
• 控制哪些发送者可以在群组聊天/频道中触发（回退到 ）。
• 设置 以允许任何成员（仍然默认受提及门控）。
• 要允许无频道，设置 。

示例：

Teams + 频道允许列表

• 通过在 下列出团队和频道来限定群组/频道回复范围。
• 键可以是团队 ID 或名称；频道键可以是会话 ID 或名称。
• 当 且存在团队允许列表时，只接受列出的团队/频道（受提及门控）。
• 向导接受 条目并为你存储它们。
• 启动时，OpenClaw 将团队/频道和用户允许列表名称解析为 ID（当 Graph 权限允许时）并记录映射；未解析的条目保持原样。

示例：

1. 安装 Microsoft Teams 插件。
2. 创建一个 Azure Bot（应用 ID + 密钥 + 租户 ID）。
3. 构建引用机器人的 Teams 应用包并包含下面的 RSC 权限。
4. 将 Teams 应用安装到团队（或个人范围的 DM）。
5. 在 中配置 （或环境变量）并启动网关。
6. 网关默认在 上侦听 Bot Framework webhook 流量。

在配置 OpenClaw 之前，你需要创建 Azure Bot 资源。

1. 转到 Create Azure Bot
2. 填写 Basics 选项卡：
   字段 值 Bot handle 你的机器人名称，例如 （必须唯一） Subscription 选择你的 Azure 订阅 Resource group 创建新的或使用现有的 Pricing tier 免费 用于开发/测试 Type of App Single Tenant（推荐 – 见下方说明） Creation type Create new Microsoft App ID

弃用通知： 2025-07-31 之后新的多租户机器人创建已被弃用。新机器人使用 Single Tenant。

3. 点击 Review + create → Create（等待 ~1-2 分钟）

1. 转到你的 Azure Bot 资源 → Configuration
2. 复制 Microsoft App ID → 这是你的
3. 点击 Manage Password → 转到 App Registration
4. 在 Certificates & secrets → New client secret → 复制 Value → 这是你的
5. 转到 Overview → 复制 Directory (tenant) ID → 这是你的

1. 在 Azure Bot → Configuration
2. 将 Messaging endpoint 设置为你的 webhook URL：
   • 生产环境：
   • 本地开发：使用隧道（见下方本地开发）

1. 在 Azure Bot → Channels
2. 点击 Microsoft Teams → Configure → Save
3. 接受服务条款

Teams 无法到达 。为本地开发使用隧道：

选项 A：ngrok

选项 B：Tailscale Funnel

你可以使用 Teams 开发者门户 而不是手动创建清单 ZIP：

1. 点击 + New app
2. 填写基本信息（名称、描述、开发者信息）
3. 转到 App features → Bot
4. 选择 Enter a bot ID manually 并粘贴你的 Azure Bot App ID
5. 检查范围：Personal、Team、Group Chat
6. 点击 Distribute → Download app package
7. 在 Teams 中：Apps → Manage your apps → Upload a custom app → 选择 ZIP

这通常比手动编辑 JSON 清单更容易。

选项 A：Azure Web Chat（首先验证 webhook）

1. 在 Azure Portal → 你的 Azure Bot 资源 → Test in Web Chat
2. 发送消息 – 你应该看到回复
3. 这确认你的 webhook 端点在 Teams 设置之前工作

选项 B：Teams（应用安装后）

1. 安装 Teams 应用（侧载或组织目录）
2. 在 Teams 中找到机器人并发送 DM
3. 检查网关日志是否有传入活动

1. 安装 Microsoft Teams 插件
   • 从 npm：
   • 从本地检出：
2. 机器人注册
   • 创建 Azure Bot（见上文）并记下：
     • 应用 ID
     • 客户端密钥（应用密码）
     • 租户 ID（单租户）
3. Teams 应用清单
   • 包含引用机器人的 条目，。
   • 范围：、、。
   • （个人范围文件处理需要）。
   • 添加 RSC 权限（下方）。
   • 创建图标： (32×32) 和 (192×192)。
   • 将三个文件打包在一起：、、。
4. 配置 OpenClaw

   你也可以使用环境变量代替配置键：
5. 机器人端点
   • 将 Azure Bot 消息端点设置为：
     • （或你选择的路径/端口）。
6. 运行网关
   • 当插件安装且具有凭证的 配置存在时，Teams 通道自动启动。

• 控制作为上下文包裹到提示中的最近频道/群组消息数量。
• 回退到 。设置为 禁用（默认 50）。
• DM 历史可以通过 限制（用户轮）。每用户覆盖：。

这些是我们 Teams 应用清单中现有的资源特定权限。它们仅在应用安装的团队/聊天中适用。

对于频道（团队范围）：

• （Application）- 无需 @提及即可接收所有频道消息
• （Application）
• （Application）
• （Application）
• （Application）
• （Application）
• （Application）

对于群组聊天：

• （Application）- 无需 @提及即可接收所有群组聊天消息

最小、有效的示例，包含必填字段。替换 ID 和 URL。

• 必须匹配 Azure Bot 应用 ID。
• 必须匹配 Azure Bot 应用 ID。
• 必须包含你计划使用的界面（、、）。
• 对于个人范围的文件处理是必需的。
• 必须包含频道读取/发送（如果你想要频道流量）。

要更新已安装的 Teams 应用（例如添加 RSC 权限）：

1. 使用新设置更新你的
2. 增加 字段（例如 → ）
3. 重新打包清单和图标（、、）
4. 上传新 zip：
   • 选项 A（Teams Admin Center）： Teams Admin Center → Teams apps → Manage apps → 找到你的应用 → Upload new version
   • 选项 B（侧载）： 在 Teams 中 → Apps → Manage your apps → Upload a custom app
5. 对于团队频道： 重新安装 Teams 中的应用以使新权限生效
6. 完全退出并重启 Teams（不仅仅是关闭窗口）以清除缓存的应用元数据

工作：

• 读取频道消息 文本 内容。
• 发送频道消息 文本 内容。
• 接收 个人（DM） 文件附件。

不工作：

• 频道/群组 图片或文件内容（负载仅包含 HTML 存根）。
• 下载存储在 SharePoint/OneDrive 中的附件。
• 读取消息历史（超出实时 webhook 事件）。

增加：

• 下载托管内容（粘贴到消息中的图片）。
• 下载存储在 SharePoint/OneDrive 中的文件附件。
• 通过 Graph 读取频道/聊天消息历史。

底线： RSC 用于实时监听；Graph API 用于历史访问。对于离线时错过消息，要获取需要 的 Graph API 权限。

如果你需要频道中的图片/文件或想要获取消息历史，必须启用 Microsoft Graph 权限并授予管理员同意。

1. 在 Entra ID (Azure AD) App Registration 中，添加 Microsoft Graph Application 权限：
   • （频道附件 + 历史）
   • 或 （群组聊天）
2. 授予租户管理员同意。
3. 增加 Teams 应用 清单版本，重新上传，并在 Teams 中重新安装应用。
4. 完全退出并重启 Teams 以清除缓存的应用元数据。

Teams 通过 HTTP webhook 传递消息。如果处理时间太长（例如缓慢的 LLM 响应），你可能会看到：

• 网关超时
• Teams 重试消息（导致重复）
• 丢弃回复

OpenClaw 通过快速返回并主动发送回复来处理这个问题，但非常缓慢的响应可能仍然导致问题。

Teams markdown 比 Slack 或 Discord 更有限：

• 基本格式化有效：粗体、斜体、、链接
• 复杂 markdown（表格、嵌套列表）可能无法正确渲染
• Adaptive Cards 支持投票和任意卡片发送（见下方）

关键设置（有关共享通道模式见 ）：

• ：启用/禁用通道。
• 、、：机器人凭证。
• （默认 ）
• （默认 ）
• : （默认：pairing）
• ：DM 允许列表（AAD 对象 ID、UPN 或显示名称）。向导在 Graph 访问可用时在设置期间将名称解析为 ID。
• ：出站文本分块大小。
• : （默认）或 在长度分块之前按空行（段落边界）拆分。
• ：入站附件主机允许列表（默认为 Microsoft/Teams 域名）。
• ：在频道/群组中需要 @提及（默认 true）。
• : （见回复样式）。
• ：每团队覆盖。
• ：每团队覆盖。
• ：默认每团队工具策略覆盖（//），当频道覆盖缺失时使用。
• ：默认每团队每发送者工具策略覆盖（支持 通配符）。
• ：每频道覆盖。
• ：每频道覆盖。
• ：每频道工具策略覆盖（//）。
• ：每频道每发送者工具策略覆盖（支持 通配符）。
• ：群组聊天/频道中文件上传的 SharePoint 站点 ID（见在群组聊天中发送文件）。

• 会话密钥遵循标准智能体格式（见 /concepts/session）：
  • 直接消息共享主会话（）。
  • 频道/群组消息使用会话 ID：

Teams 最近在相同的基础数据模型上引入了两种频道 UI 样式：

问题： Teams API 不公开频道使用哪种 UI 样式。如果你使用错误的 ：

• 在 Threads 样式的频道中 → 回复尴尬地嵌套
• 在 Posts 样式的频道中 → 回复显示为单独的顶层帖子而不是线程内

解决方案： 根据频道设置方式配置每频道的 ：

当前限制：

• DM： 图片和文件附件通过 Teams 机器人文件 API 工作。
• 频道/群组： 附件位于 M365 存储（SharePoint/OneDrive）。Webhook 负载仅包含 HTML 存根，不包含实际文件字节。需要 Graph API 权限才能下载频道附件。

如果没有 Graph 权限，频道中带有图片的消息将作为纯文本接收（图片内容对机器人不可访问）。 默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。使用 覆盖（使用 允许任何主机）。

机器人可以使用 FileConsentCard 流程在 DM 中发送文件（内置）。然而，在群组聊天/频道中发送文件需要额外设置：

机器人没有个人 OneDrive 驱动器（ Graph API 端点不适用于应用身份）。要在群组聊天/频道中发送文件，机器人上传到 SharePoint 站点并创建共享链接。

1. 在 Entra ID (Azure AD) App Registration 中添加 Graph API 权限：
   • （Application）- 上传文件到 SharePoint
   • （Application）- 可选，启用每用户共享链接
2. 授予租户管理员同意。
3. 获取你的 SharePoint 站点 ID：
4. 配置 OpenClaw：

每用户共享更安全，因为只有聊天参与者可以访问文件。如果 权限缺失，机器人回退到组织范围共享。

上传的文件存储在配置的 SharePoint 站点默认文档库的 文件夹中。

OpenClaw 将 Teams 投票发送为 Adaptive Cards（没有原生的 Teams 投票 API）。

• CLI：
• 投票由网关记录在 中。
• 网关必须保持在线以记录投票。
• 投票尚未自动发布结果摘要（需要检查存储文件）。

使用 工具或 CLI 向 Teams 用户或对话发送任意 Adaptive Card JSON。

参数接受 Adaptive Card JSON 对象。当提供 时，消息文本是可选的。

智能体工具：

CLI：

有关卡片架构和示例，见 Adaptive Cards 文档。有关目标格式详情，见下方目标格式。

MSTeams 目标使用前缀区分用户和对话：

CLI 示例：

智能体工具示例：

注意：没有 前缀，名称默认解析为群组/团队寻址。按显示名称定位人员时始终使用 。

• 主动消息只有在用户交互后才可能，因为我们此时存储对话引用。
• 有关 和允许列表门控，见 。

Teams URL 中的 查询参数不是用于配置的团队 ID。从 URL 路径中提取 ID：

团队 URL：

频道 URL：

用于配置：

• 团队 ID = 后的路径段（URL 解码，例如 ）
• 频道 ID = 后的路径段（URL 解码）
• 忽略 查询参数

机器人在私人频道中支持有限：

如果私人频道不工作的解决方法：

1. 对机器人交互使用标准频道
2. 使用 DM – 用户可以直接向机器人发送消息
3. 使用 Graph API 进行历史访问（需要 ）

• 图片在频道中不显示： Graph 权限或管理员同意缺失。重新安装 Teams 应用并完全退出重新打开 Teams。
• 频道中没有回复： 默认需要提及；设置 或按团队/频道配置。
• 版本不匹配（Teams 仍然显示旧清单）： 移除 + 重新添加应用并完全退出 Teams 刷新。
• 401 Unauthorized 来自 webhook： 测试手动时预期没有 Azure JWT – 意味着端点可达但认证失败。使用 Azure Web Chat 正确测试。

• “Icon file cannot be empty”: 清单引用的图标文件是 0 字节。创建有效的 PNG 图标（ 为 32×32， 为 192×192）。
• “webApplicationInfo.Id already in use”: 应用仍安装在另一个团队/聊天中。首先找到并卸载它，或等待 5-10 分钟传播。
• “Something went wrong” on upload: 尝试通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 选项卡，并检查响应体中的实际错误。
• 侧载失败： 尝试”上传应用到组织的应用目录”而不是”上传自定义应用” – 这通常绕过侧载限制。

1. 验证 完全匹配你的机器人的应用 ID
2. 重新上传应用并在团队/聊天中重新安装
3. 检查你的组织管理员是否阻止了 RSC 权限
4. 确认你使用正确的范围： 用于团队， 用于群组聊天

• Create Azure Bot – Azure Bot 设置指南
• Teams Developer Portal – 创建/管理 Teams 应用
• Teams app manifest schema
• Receive channel messages with RSC
• RSC permissions reference
• Teams bot file handling（频道/群组需要 Graph）
• Proactive messaging