Microsoft Teams（插件）

“入此门者，当放弃一切希望。”

更新：2026-01-21。状态：支持文本与私信附件；频道/群组文件发送需配置 sharePointSiteId 与 Graph 权限（见 在群聊中发送文件）。投票通过 Adaptive Cards 发送。

需要安装插件

Microsoft Teams 以插件形式提供，不随核心安装打包。破坏性变更（2026.1.15）： MS Teams 已移出核心。若使用 Teams，必须单独安装插件。这样可保持核心安装更轻量，并让 MS Teams 依赖独立更新。通过 CLI 安装（npm 源）：

moltbot plugins install @moltbot/msteams

本地代码库（从 git 仓库运行时）：

moltbot plugins install ./extensions/msteams

在配置/入门中选择 Teams 且检测到 git 仓库时，Moltbot 会自动提示本地安装路径。详见 插件。

快速设置（入门）

1. 安装 Microsoft Teams 插件。
2. 创建 Azure Bot（App ID + 客户端密钥 + 租户 ID）。
3. 用上述凭据配置 Moltbot。
4. 通过公网 URL 或隧道暴露 /api/messages（默认端口 3978）。
5. 安装 Teams 应用包并启动网关。

最小配置：

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      appPassword: "<APP_PASSWORD>",
      tenantId: "<TENANT_ID>",
      webhook: { port: 3978, path: "/api/messages" }
    }
  }
}

说明：群聊默认被拦截（channels.msteams.groupPolicy: "allowlist"）。要允许群组回复，需设置 channels.msteams.groupAllowFrom（或使用 groupPolicy: "open" 允许任意成员，仍默认需 @ 提及）。

目标

• 通过 Teams 私信、群聊或频道与 Moltbot 对话。
• 路由确定性：回复始终回到消息来源的频道。
• 默认安全频道行为（除非另行配置，否则需要 @ 提及）。

配置写入

默认允许 Microsoft Teams 写入由 /config set|unset 触发的配置更新（需 commands.config: true）。禁用方式：

{
  channels: { msteams: { configWrites: false } }
}

访问控制（私信 + 群组）

私信访问

• 默认：channels.msteams.dmPolicy = "pairing"。未知发件人在批准前被忽略。
• channels.msteams.allowFrom 接受 AAD 对象 ID、UPN 或显示名。在凭据允许时，配置向导会通过 Microsoft Graph 将名称解析为 ID。

群组访问

• 默认：channels.msteams.groupPolicy = "allowlist"（未添加 groupAllowFrom 时会被拦截）。可用 channels.defaults.groupPolicy 在未设置时覆盖默认。
• channels.msteams.groupAllowFrom 控制哪些发件人可在群聊/频道中触发（回退到 channels.msteams.allowFrom）。
• 设 groupPolicy: "open" 允许任意成员（仍默认需 @ 提及）。
• 若要禁止所有频道，设 channels.msteams.groupPolicy: "disabled"。

示例：

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["user@org.com"]
    }
  }
}

Teams + 频道白名单

• 在 channels.msteams.teams 下列出团队与频道，限定群组/频道回复范围。
• 键可为团队 ID 或名称；频道键可为会话 ID 或名称。
• 当 groupPolicy="allowlist" 且存在 teams 白名单时，仅列出的团队/频道会被接受（需 @ 提及）。
• 配置向导接受 Team/Channel 条目并代为存储。
• 启动时，Moltbot 在 Graph 权限允许时将团队/频道及用户白名单名称解析为 ID 并记录映射；无法解析的条目保持原样。

示例：

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      teams: {
        "My Team": {
          channels: {
            "General": { requireMention: true }
          }
        }
      }
    }
  }
}

工作流程

1. 安装 Microsoft Teams 插件。
2. 创建 Azure Bot（App ID + 密钥 + 租户 ID）。
3. 构建 Teams 应用包，引用该机器人并包含下方 RSC 权限。
4. 将 Teams 应用上传/安装到团队（或个人范围用于私信）。
5. 在 ~/.clawdbot/moltbot.json（或环境变量）中配置 msteams 并启动网关。
6. 网关默认在 /api/messages 上监听 Bot Framework webhook 流量。

Azure Bot 设置（前置条件）

在配置 Moltbot 前，需先创建 Azure Bot 资源。

步骤 1：创建 Azure Bot

1. 打开 创建 Azure Bot 。
2. 填写 Basics 选项卡：

弃用说明： 2025-07-31 后不再支持新建多租户机器人。新机器人请使用 Single Tenant。

3. 点击 Review + create → Create（等待约 1–2 分钟）。

步骤 2：获取凭据

1. 进入 Azure Bot 资源 → Configuration。
2. 复制 Microsoft App ID → 即 appId。
3. 点击 Manage Password → 进入应用注册。
4. 在 Certificates & secrets → New client secret → 复制 Value → 即 appPassword。
5. 进入 Overview → 复制 Directory (tenant) ID → 即 tenantId。

步骤 3：配置 Messaging 端点

1. 在 Azure Bot → Configuration。
2. 将 Messaging endpoint 设为你的 webhook URL：
   • 生产：https://your-domain.com/api/messages
   • 本地开发：使用隧道（见下方 本地开发（隧道））。

步骤 4：启用 Teams 频道

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

本地开发（隧道）

Teams 无法访问 localhost。本地开发请使用隧道。方式 A：ngrok

ngrok http 3978
# 复制 https URL，如 https://abc123.ngrok.io
# 将 messaging endpoint 设为：https://abc123.ngrok.io/api/messages

方式 B：Tailscale Funnel

tailscale funnel 3978
# 使用你的 Tailscale funnel URL 作为 messaging endpoint

Teams Developer Portal（替代方式）

不必手动做 manifest ZIP，可使用 Teams Developer Portal ：

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

通常比手改 JSON manifest 更简单。

测试机器人

方式 A：Azure Web Chat（先验证 webhook）

1. 在 Azure 门户 → 你的 Azure Bot 资源 → Test in Web Chat。
2. 发送一条消息，应收到回复。
3. 可确认 webhook 端点在 Teams 配置前已可用。

方式 B：Teams（安装应用后）

1. 安装 Teams 应用（侧载或组织目录）。
2. 在 Teams 中找到机器人并发送私信。
3. 查看网关日志中的入站活动。

设置（最小、仅文本）

1. 安装 Microsoft Teams 插件
   • 从 npm：moltbot plugins install @moltbot/msteams
   • 从本地代码库：moltbot plugins install ./extensions/msteams
2. 机器人注册
   • 创建 Azure Bot（见上）并记录：App ID、客户端密钥（App password）、租户 ID（单租户）。
3. Teams 应用 manifest
   • 包含 bot 条目，botId = <App ID>。
   • Scopes：personal、team、groupChat。
   • supportsFiles: true（个人范围文件处理必需）。
   • 添加下方 RSC 权限。
   • 创建图标：outline.png（32x32）、color.png（192x192）。
   • 将三个文件一起打包为 ZIP：manifest.json、outline.png、color.png。
4. 配置 Moltbot

{
  "msteams": {
    "enabled": true,
    "appId": "<APP_ID>",
    "appPassword": "<APP_PASSWORD>",
    "tenantId": "<TENANT_ID>",
    "webhook": { "port": 3978, "path": "/api/messages" }
  }
}

也可使用环境变量替代配置项：MSTEAMS_APP_ID、MSTEAMS_APP_PASSWORD、MSTEAMS_TENANT_ID。

5. 机器人端点
   • 将 Azure Bot Messaging Endpoint 设为：https://<host>:3978/api/messages（或你选择的路径/端口）。
6. 运行网关
   • 安装插件且存在带凭据的 msteams 配置时，Teams 频道会自动启动。

历史上下文

• channels.msteams.historyLimit 控制最近多少条频道/群组消息被纳入提示。
• 回退到 messages.groupChat.historyLimit。设 0 可禁用（默认 50）。
• 私信历史可用 channels.msteams.dmHistoryLimit（用户轮次）限制。每用户覆盖：channels.msteams.dms["<user_id>"].historyLimit。

当前 Teams RSC 权限（Manifest）

以下为 Teams 应用 manifest 中已有的 resourceSpecific 权限，仅适用于应用已安装的团队/会话内。

频道（团队范围）：

• ChannelMessage.Read.Group (Application) — 无需 @ 提及即可接收所有频道消息
• ChannelMessage.Send.Group (Application)
• Member.Read.Group (Application)
• Owner.Read.Group (Application)
• ChannelSettings.Read.Group (Application)
• TeamMember.Read.Group (Application)
• TeamSettings.Read.Group (Application)

群聊：

• ChatMessage.Read.Chat (Application) — 无需 @ 提及即可接收所有群聊消息

Teams Manifest 示例（脱敏）

最小有效示例，含必需字段。请替换 ID 与 URL。

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",
  "manifestVersion": "1.23",
  "version": "1.0.0",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": { "short": "Moltbot" },
  "developer": {
    "name": "Your Org",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com/privacy",
    "termsOfUseUrl": "https://example.com/terms"
  },
  "description": { "short": "Moltbot in Teams", "full": "Moltbot in Teams" },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#5B6DEF",
  "bots": [
    {
      "botId": "11111111-1111-1111-1111-111111111111",
      "scopes": ["personal", "team", "groupChat"],
      "isNotificationOnly": false,
      "supportsCalling": false,
      "supportsVideo": false,
      "supportsFiles": true
    }
  ],
  "webApplicationInfo": {
    "id": "11111111-1111-1111-1111-111111111111"
  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        { "name": "ChannelMessage.Read.Group", "type": "Application" },
        { "name": "ChannelMessage.Send.Group", "type": "Application" },
        { "name": "Member.Read.Group", "type": "Application" },
        { "name": "Owner.Read.Group", "type": "Application" },
        { "name": "ChannelSettings.Read.Group", "type": "Application" },
        { "name": "TeamMember.Read.Group", "type": "Application" },
        { "name": "TeamSettings.Read.Group", "type": "Application" },
        { "name": "ChatMessage.Read.Chat", "type": "Application" }
      ]
    }
  }
}

Manifest 注意（必填字段）

• bots[].botId 必须与 Azure Bot App ID 一致。
• webApplicationInfo.id 必须与 Azure Bot App ID 一致。
• bots[].scopes 须包含计划使用的范围（personal、team、groupChat）。
• bots[].supportsFiles: true 为个人范围文件处理所必需。
• 若要接收频道流量，authorization.permissions.resourceSpecific 须包含频道读/发权限。

更新已安装应用

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

1. 用新设置更新 manifest.json。
2. 递增 version 字段（如 1.0.0 → 1.1.0）。
3. 重新打包 manifest 与图标（manifest.json、outline.png、color.png）。
4. 上传新 zip：
   • 方式 A（Teams 管理后台）： Teams Admin Center → Teams apps → Manage apps → 找到应用 → Upload new version
   • 方式 B（侧载）： 在 Teams → Apps → Manage your apps → Upload a custom app
5. 团队频道： 在每个团队中重新安装应用以使新权限生效。
6. 完全退出并重新打开 Teams（不只是关窗口）以清除缓存的应用元数据。

能力：仅 RSC 与 Graph

仅 Teams RSC（已安装应用，无 Graph API 权限）

支持：读取频道消息文本内容；发送频道消息文本内容；接收私信文件附件。

不支持：频道/群组的图片或文件内容（payload 仅含 HTML 占位）；从 SharePoint/OneDrive 下载附件；读取消息历史（仅限实时 webhook 事件）。

Teams RSC + Microsoft Graph 应用权限

额外支持：下载托管内容（粘贴到消息中的图片）；从 SharePoint/OneDrive 下载文件附件；通过 Graph 读取频道/会话消息历史。

RSC 与 Graph API

结论： RSC 用于实时监听；Graph API 用于历史访问。离线时补看错过的消息需要 Graph API 的 ChannelMessage.Read.All（需管理员同意）。

启用 Graph 的媒体与历史（频道必需）

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

1. 在 Entra ID（Azure AD）应用注册中，添加 Microsoft Graph 应用程序权限：
   • ChannelMessage.Read.All（频道附件 + 历史）
   • Chat.Read.All 或 ChatMessage.Read.All（群聊）
2. 为租户授予管理员同意。
3. 提高 Teams 应用 manifest 版本，重新上传并在 Teams 中重新安装应用。
4. 完全退出并重新打开 Teams 以清除缓存的应用元数据。

已知限制

Webhook 超时

Teams 通过 HTTP webhook 投递消息。若处理过久（例如 LLM 响应慢），可能出现：网关超时、Teams 重试消息（导致重复）、回复丢失。Moltbot 通过快速返回并主动发送回复来缓解，但极慢的响应仍可能出问题。

格式

Teams 的 Markdown 比 Slack 或 Discord 更受限：基础格式可用（粗体、斜体、代码、链接）；复杂 Markdown（表格、嵌套列表）可能无法正确渲染。投票与任意卡片发送支持 Adaptive Cards（见下）。

配置

主要设置（共享频道模式见 配置）：

• channels.msteams.enabled：启用/禁用频道。
• channels.msteams.appId、channels.msteams.appPassword、channels.msteams.tenantId：机器人凭据。
• channels.msteams.webhook.port（默认 3978）、channels.msteams.webhook.path（默认 /api/messages）。
• channels.msteams.dmPolicy：pairing | allowlist | open | disabled（默认 pairing）。
• channels.msteams.allowFrom：私信白名单（AAD 对象 ID、UPN 或显示名）。在 Graph 可用时向导会在设置阶段将名称解析为 ID。
• channels.msteams.textChunkLimit：出站文本分块大小。
• channels.msteams.chunkMode：length（默认）或 newline，在按长度分块前按空行（段落边界）拆分。
• channels.msteams.mediaAllowHosts：入站附件主机白名单（默认 Microsoft/Teams 域名）。
• channels.msteams.requireMention：频道/群组是否需 @ 提及（默认 true）。
• channels.msteams.replyStyle：thread | top-level（见 回复风格）。
• channels.msteams.teams.<teamId>.replyStyle、requireMention、tools、toolsBySender：按团队覆盖。
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle、requireMention、tools、toolsBySender：按频道覆盖。
• channels.msteams.sharePointSiteId：群聊/频道文件上传用 SharePoint 站点 ID（见 在群聊中发送文件）。

路由与会话

• 会话键遵循标准 agent 格式（见 会话）：私信共享主会话（agent:<agentId>:<mainKey>）；频道/群组消息使用会话 id：agent:<agentId>:msteams:channel:<conversationId>、agent:<agentId>:msteams:group:<conversationId>。

回复风格：线程与帖子

Teams 近期在同一数据模型上提供两种频道 UI 风格：

问题： Teams API 不暴露频道使用的 UI 风格。若 replyStyle 与频道不匹配：在 Threads 风格频道用 thread → 回复会别扭地嵌套；在 Posts 风格频道用 top-level → 回复会变成独立主帖而非线程内。解决： 根据频道实际设置，按频道配置 replyStyle：

{
  "msteams": {
    "replyStyle": "thread",
    "teams": {
      "19:abc...@thread.tacv2": {
        "channels": {
          "19:xyz...@thread.tacv2": {
            "replyStyle": "top-level"
          }
        }
      }
    }
  }
}

附件与图片

当前限制： 私信： 图片与文件附件通过 Teams 机器人文件 API 可用。频道/群组： 附件存放在 M365 存储（SharePoint/OneDrive），webhook payload 仅含 HTML 占位，不含实际文件字节。下载频道附件需要 Graph API 权限。无 Graph 权限时，带图片的频道消息会以纯文本接收（机器人无法访问图片内容）。默认 Moltbot 仅从 Microsoft/Teams 主机名下载媒体；可用 channels.msteams.mediaAllowHosts 覆盖（["*"] 表示允许任意主机）。

在群聊中发送文件

私信中机器人可通过 FileConsentCard 流程（内置）发送文件。在群聊/频道中发送文件需额外配置：

为何群聊需要 SharePoint

机器人没有个人 OneDrive 驱动器（/me/drive Graph API 对应用身份无效）。要在群聊/频道发文件，机器人需上传到 SharePoint 站点并创建分享链接。

配置步骤

1. 在 Entra ID（Azure AD）→ 应用注册中添加 Graph API 权限：Sites.ReadWrite.All (Application) — 上传文件到 SharePoint；Chat.Read.All (Application) — 可选，启用按用户分享链接。
2. 为租户授予管理员同意。
3. 获取 SharePoint 站点 ID：

# 通过 Graph Explorer 或带有效 token 的 curl：
curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"

# 例如站点为 "contoso.sharepoint.com/sites/BotFiles"
curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"

# 响应中含 "id": "contoso.sharepoint.com,guid1,guid2"

4. 配置 Moltbot：

{
  channels: {
    msteams: {
      sharePointSiteId: "contoso.sharepoint.com,guid1,guid2"
    }
  }
}

分享行为

按用户分享更安全。若缺少 Chat.Read.All，机器人会回退到组织内分享。

回退行为

文件存放位置

上传的文件存放在所配置 SharePoint 站点的默认文档库下的 /MoltbotShared/ 文件夹。

投票（Adaptive Cards）

Moltbot 通过 Adaptive Cards 发送 Teams 投票（无原生 Teams 投票 API）。CLI：moltbot message poll --channel msteams --target conversation:<id> ...。投票由网关记录在 ~/.clawdbot/msteams-polls.json。网关需保持在线以记录投票。投票暂不自动发布结果摘要（如需可查看该存储文件）。

Adaptive Cards（任意）

通过 message 工具或 CLI 向 Teams 用户或会话发送任意 Adaptive Card JSON。card 参数接受 Adaptive Card JSON 对象；提供 card 时消息文本可选。Agent 工具：

{
  "action": "send",
  "channel": "msteams",
  "target": "user:<id>",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{"type": "TextBlock", "text": "Hello!"}]
  }
}

CLI：

moltbot message send --channel msteams \
  --target "conversation:19:abc...@thread.tacv2" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'

卡片 schema 与示例见 Adaptive Cards 文档 。目标格式详见下方 目标格式。

目标格式

MSTeams 目标使用前缀区分用户与会话：

CLI 示例：

# 按用户 ID 发送
moltbot message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"

# 按显示名发送（会触发 Graph API 查询）
moltbot message send --channel msteams --target "user:John Smith" --message "Hello"

# 发送到群聊或频道
moltbot message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"

# 向会话发送 Adaptive Card
moltbot message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'

Agent 工具示例：

{
  "action": "send",
  "channel": "msteams",
  "target": "user:John Smith",
  "message": "Hello!"
}

{
  "action": "send",
  "channel": "msteams",
  "target": "conversation:19:abc...@thread.tacv2",
  "card": {"type": "AdaptiveCard", "version": "1.5", "body": [{"type": "TextBlock", "text": "Hello"}]}
}

注意：不带 user: 前缀时，名称会按群组/团队解析。按显示名指定用户时请始终使用 user: 前缀。

主动消息

• 仅当用户已有过交互后才可发送主动消息，因为此时我们才存储会话引用。
• dmPolicy 与白名单门控见 配置。

团队与频道 ID（常见坑）

Teams URL 中的 groupId 查询参数不是配置用的团队 ID。请从 URL 路径中提取 ID。团队 URL： 路径中 /team/ 后的段（需 URL 解码，如 19:Bk4j...@thread.tacv2）为 Team ID。频道 URL： 路径中 /channel/ 后的段（URL 解码）为 Channel ID。配置时： Team ID = /team/ 后的路径段（URL 解码）；Channel ID = /channel/ 后的路径段（URL 解码）；忽略 groupId 查询参数。

私密频道

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

若私密频道不可用： 使用标准频道与机器人交互；使用私信（用户始终可直接联系机器人）；需要历史时使用 Graph API（需 ChannelMessage.Read.All）。

故障排查

常见问题

• 频道中图片不显示： 缺少 Graph 权限或管理员同意。重新安装 Teams 应用并完全退出/重开 Teams。
• 频道无回复： 默认需 @ 提及；设 channels.msteams.requireMention=false 或按团队/频道配置。
• 版本不一致（Teams 仍显示旧 manifest）： 移除并重新添加应用，并完全退出 Teams 以刷新。
• Webhook 返回 401 Unauthorized： 无 Azure JWT 时手动测试会出现，表示端点可达但鉴权失败。请用 Azure Web Chat 正确测试。

Manifest 上传错误

• “Icon file cannot be empty”： manifest 引用的图标文件为 0 字节。请提供有效 PNG 图标（outline.png 32x32，color.png 192x192）。
• “webApplicationInfo.Id already in use”： 应用仍安装在其它团队/会话中。先找到并卸载，或等待 5–10 分钟传播。
• 上传时 “Something went wrong”： 改从 https://admin.teams.microsoft.com  上传，打开浏览器 DevTools (F12) → Network，查看响应体中的具体错误。
• 侧载失败： 尝试“将应用上传到组织的应用目录”而非“上传自定义应用”，常可绕过侧载限制。

RSC 权限不生效

1. 确认 webApplicationInfo.id 与机器人 App ID 完全一致。
2. 重新上传应用并在团队/会话中重新安装。
3. 检查组织管理员是否禁用了 RSC 权限。
4. 确认使用正确 scope：团队用 ChannelMessage.Read.Group，群聊用 ChatMessage.Read.Chat。

参考

• 创建 Azure Bot  — Azure Bot 设置指南
• Teams Developer Portal  — 创建/管理 Teams 应用
• Teams 应用 manifest 架构 
• 使用 RSC 接收频道消息 
• RSC 权限参考 
• Teams 机器人文件处理 （频道/群组需 Graph）
• 主动消息