Microsoft Teams（插件）

"进入此门者，须弃一切希望。"

更新时间：2026-01-21

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

需要安装插件

Microsoft Teams 作为插件发布，不包含在核心安装中。

破坏性变更（2026.1.15）： MS Teams 已从核心中移出。如果你使用它，必须安装插件。

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

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

bash

openclaw plugins install @openclaw/msteams

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

bash

openclaw plugins install ./extensions/msteams

如果你在配置/引导设置过程中选择 Teams，且检测到 git 检出，OpenClaw 将自动提供本地安装路径。

详情：插件

快速设置（新手）

安装 Microsoft Teams 插件。
创建一个 Azure Bot（App ID + 客户端密钥 + 租户 ID）。
使用这些凭证配置 OpenClaw。
通过公共 URL 或隧道暴露 /api/messages（默认端口 3978）。
安装 Teams 应用包并启动网关（Gateway）。

最小配置：

json5

{
  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 私聊、群聊或频道与 OpenClaw 对话。
保持确定性路由：回复总是返回到到达的通道（Channel）。
默认使用安全通道行为（除非另行配置，否则需要提及）。

配置写入

默认情况下，Microsoft Teams 允许通过 /config set|unset 触发的配置更新写入（需要 commands.config: true）。

禁用方式：

json5

{
  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"。

示例：

json5

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

团队 + 频道允许列表

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

示例：

json5

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

工作原理

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

Azure Bot 设置（前提条件）

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

步骤 1：创建 Azure Bot

前往创建 Azure Bot

填写基本信息选项卡：

字段	值
Bot 句柄	你的机器人名称，例如 `openclaw-msteams`（必须唯一）
订阅	选择你的 Azure 订阅
资源组	新建或使用现有资源组
定价层	Free（用于开发/测试）
应用类型	单租户（推荐 - 见下方说明）
创建类型	创建新的 Microsoft App ID

弃用通知： 在 2025-07-31 之后，创建新的多租户机器人已弃用。新机器人请使用单租户。

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

步骤 2：获取凭证

前往你的 Azure Bot 资源 → 配置
复制 Microsoft App ID → 这是你的 appId
点击 管理密码 → 前往应用注册
在证书和密钥 → 新建客户端密钥 → 复制值 → 这是你的 appPassword
前往概述 → 复制目录（租户）ID → 这是你的 tenantId

步骤 3：配置消息端点

在 Azure Bot → 配置
将消息端点设置为你的 Webhook URL：
- 生产环境：https://your-domain.com/api/messages
- 本地开发：使用隧道（参见下方本地开发）

步骤 4：启用 Teams 通道

在 Azure Bot → 通道
点击 Microsoft Teams → 配置 → 保存
接受服务条款

本地开发（隧道）

Teams 无法访问 localhost。使用隧道进行本地开发：

方案 A：ngrok

bash

ngrok http 3978
# 复制 https URL，例如 https://abc123.ngrok.io
# 将消息端点设置为：https://abc123.ngrok.io/api/messages

方案 B：Tailscale Funnel

bash

tailscale funnel 3978
# 使用你的 Tailscale Funnel URL 作为消息端点

Teams 开发者门户（替代方案）

你可以使用 Teams 开发者门户代替手动创建清单 ZIP：

点击 + 新建应用
填写基本信息（名称、描述、开发者信息）
前往应用功能 → 机器人
选择手动输入机器人 ID 并粘贴你的 Azure Bot App ID
勾选范围：个人、团队、群聊
点击分发 → 下载应用包
在 Teams 中：应用 → 管理你的应用 → 上传自定义应用 → 选择 ZIP

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

测试机器人

方案 A：Azure Web Chat（先验证 Webhook）

在 Azure Portal → 你的 Azure Bot 资源 → 在 Web Chat 中测试
发送一条消息 - 你应该能看到回复
这确认你的 Webhook 端点在 Teams 设置之前就能正常工作

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

安装 Teams 应用（旁加载或组织目录）
在 Teams 中找到机器人并发送私聊
检查网关（Gateway）日志中的传入活动

设置（最小纯文本）

安装 Microsoft Teams 插件
- 从 npm：openclaw plugins install @openclaw/msteams
- 从本地检出：openclaw plugins install ./extensions/msteams
机器人注册
- 创建 Azure Bot（参见上方）并记录：
  - App ID
  - 客户端密钥（App password）
  - 租户 ID（单租户）
Teams 应用清单
- 包含一个 bot 条目，其中 botId = <App ID>。
- 范围：personal、team、groupChat。
- supportsFiles: true（个人范围文件处理所需）。
- 添加 RSC 权限（见下方）。
- 创建图标：outline.png（32x32）和 color.png（192x192）。
- 将三个文件打包为 ZIP：manifest.json、outline.png、color.png。

配置 OpenClaw

json

{
  "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

机器人端点
- 将 Azure Bot 消息端点设置为：
  - https://<host>:3978/api/messages（或你选择的路径/端口）。
运行网关（Gateway）
- 当插件已安装且 msteams 配置中存在凭证时，Teams 通道（Channel）会自动启动。

历史上下文

channels.msteams.historyLimit 控制有多少最近的频道/群组消息被包含在提示中。
回退到 messages.groupChat.historyLimit。设置 0 表示禁用（默认 50）。
私聊历史可通过 channels.msteams.dmHistoryLimit（用户轮次）限制。按用户覆盖：channels.msteams.dms["<user_id>"].historyLimit。

当前 Teams RSC 权限（清单）

以下是 Teams 应用清单中现有的 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 清单示例（已脱敏）

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

json

{
  "$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": "OpenClaw" },
  "developer": {
    "name": "Your Org",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com/privacy",
    "termsOfUseUrl": "https://example.com/terms"
  },
  "description": { "short": "OpenClaw in Teams", "full": "OpenClaw 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" }
      ]
    }
  }
}

清单注意事项（必需字段）

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 权限）：

使用新设置更新你的 manifest.json
递增 version 字段（例如 1.0.0 → 1.1.0）
重新打包清单和图标（manifest.json、outline.png、color.png）
上传新的 ZIP：
- 方案 A（Teams 管理中心）： Teams 管理中心 → Teams 应用 → 管理应用 → 找到你的应用 → 上传新版本
- 方案 B（旁加载）： 在 Teams → 应用 → 管理你的应用 → 上传自定义应用
对于团队频道： 在每个团队中重新安装应用以使新权限生效
完全退出并重新启动 Teams（不只是关闭窗口）以清除缓存的应用元数据

功能：仅 RSC vs Graph

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

可用功能：

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

不可用功能：

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

使用 Teams RSC + Microsoft Graph 应用程序权限

额外功能：

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

RSC vs Graph API

功能	RSC 权限	Graph API
实时消息	是（通过 Webhook）	否（仅轮询）
历史消息	否	是（可查询历史）
设置复杂度	仅应用清单	需要管理员同意 + Token 流程
离线工作	否（必须运行中）	是（随时查询）

总结： RSC 用于实时监听；Graph API 用于历史访问。要补齐离线期间遗漏的消息，需要具有 ChannelMessage.Read.All 的 Graph API（需要管理员同意）。

启用 Graph 的媒体 + 历史（频道所需）

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

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

用户提及的额外权限： 对于会话中的用户，用户 @提及可以直接使用。但是，如果你想动态搜索并提及不在当前会话中的用户，需要添加 User.Read.All（Application）权限并授予管理员同意。

已知限制

Webhook 超时

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

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

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

格式

Teams 的 Markdown 支持比 Slack 或 Discord 更有限：

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

配置

关键设置（参见 /gateway/configuration 了解共享通道模式）：

channels.msteams.enabled：启用/禁用通道（Channel）。
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.mediaAuthAllowHosts：媒体重试时附加 Authorization 头的主机白名单（默认为 Graph + Bot Framework 主机）。
channels.msteams.requireMention：频道/群组中需要 @提及（默认 true）。
channels.msteams.replyStyle：thread | top-level（参见回复样式：线程 vs 帖子）。
channels.msteams.teams.<teamId>.replyStyle：按团队覆盖。
channels.msteams.teams.<teamId>.requireMention：按团队覆盖。
channels.msteams.teams.<teamId>.tools：按团队默认工具策略覆盖（allow/deny/alsoAllow），当频道覆盖缺失时使用。
channels.msteams.teams.<teamId>.toolsBySender：按团队按发送者的工具策略覆盖（支持 "*" 通配符）。
channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle：按频道覆盖。
channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention：按频道覆盖。
channels.msteams.teams.<teamId>.channels.<conversationId>.tools：按频道工具策略覆盖（allow/deny/alsoAllow）。
channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender：按频道按发送者的工具策略覆盖（支持 "*" 通配符）。
channels.msteams.sharePointSiteId：群聊/频道中文件上传的 SharePoint 站点 ID（参见在群聊中发送文件）。

路由与会话

会话（Session）键遵循标准智能体（Agent）格式（参见 /concepts/session）：
- 私聊共享主会话（agent:<agentId>:<mainKey>）。
- 频道/群组消息使用会话 ID：
  - agent:<agentId>:msteams:channel:<conversationId>
  - agent:<agentId>:msteams:group:<conversationId>

回复样式：线程 vs 帖子

Teams 最近在同一底层数据模型上引入了两种频道 UI 样式：

样式	描述	推荐 `replyStyle`
Posts（经典）	消息以卡片形式显示，回复在下方以线程形式展示	`thread`（默认）
Threads（类 Slack）	消息线性流动，更像 Slack	`top-level`

问题： Teams API 不会暴露频道使用的 UI 样式。如果使用了错误的 replyStyle：

在 Threads 样式频道中使用 thread → 回复显示为尴尬的嵌套
在 Posts 样式频道中使用 top-level → 回复显示为独立的顶级帖子而非线程内回复

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

json

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

附件与图片

当前限制：

私聊： 图片和文件附件通过 Teams 机器人文件 API 工作。
频道/群组： 附件存储在 M365 存储中（SharePoint/OneDrive）。Webhook 有效载荷仅包含 HTML 存根，而非实际文件字节。需要 Graph API 权限才能下载频道附件。

没有 Graph 权限时，包含图片的频道消息将仅作为纯文本接收（机器人无法访问图片内容）。默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。使用 channels.msteams.mediaAllowHosts 覆盖（使用 ["*"] 允许任何主机）。 Authorization 头仅附加到 channels.msteams.mediaAuthAllowHosts 中的主机（默认为 Graph + Bot Framework 主机）。请保持此列表严格（避免多租户后缀）。

在群聊中发送文件

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

场景	文件发送方式	所需设置
私聊	FileConsentCard → 用户接受 → 机器人上传	开箱即用
群聊/频道	上传到 SharePoint → 分享链接	需要 `sharePointSiteId` + Graph 权限
图片（任何场景）	Base64 编码内联	开箱即用

为什么群聊需要 SharePoint

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

设置

在 Entra ID（Azure AD）→ 应用注册中添加 Graph API 权限：
- Sites.ReadWrite.All（Application）- 上传文件到 SharePoint
- Chat.Read.All（Application）- 可选，启用按用户共享链接
为租户授予管理员同意。

获取你的 SharePoint 站点 ID：

bash

# 通过 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"

配置 OpenClaw：

json5

{
  channels: {
    msteams: {
      // ... 其他配置 ...
      sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
    },
  },
}

共享行为

权限	共享行为
仅 `Sites.ReadWrite.All`	组织级共享链接（组织内任何人可访问）
`Sites.ReadWrite.All` + `Chat.Read.All`	按用户共享链接（仅聊天成员可访问）

按用户共享更安全，因为只有聊天参与者可以访问文件。如果缺少 Chat.Read.All 权限，机器人将回退到组织级共享。

回退行为

场景	结果
群聊 + 文件 + 已配置 `sharePointSiteId`	上传到 SharePoint，发送共享链接
群聊 + 文件 + 未配置 `sharePointSiteId`	尝试 OneDrive 上传（可能失败），仅发送文本
个人聊天 + 文件	FileConsentCard 流程（无需 SharePoint）
任何场景 + 图片	Base64 编码内联（无需 SharePoint）

文件存储位置

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

投票（Adaptive Cards）

OpenClaw 通过 Adaptive Cards 发送 Teams 投票（没有原生 Teams 投票 API）。

CLI：openclaw message poll --channel msteams --target conversation:<id> ...
投票由网关（Gateway）记录在 ~/.openclaw/msteams-polls.json 中。
网关（Gateway）必须保持在线才能记录投票。
投票目前不会自动发布结果摘要（如有需要请检查存储文件）。

Adaptive Cards（任意）

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

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

智能体（Agent）工具：

json

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

CLI：

bash

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

参见 Adaptive Cards 文档了解卡片 Schema 和示例。目标格式详情请参见下方目标格式。

目标格式

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

目标类型	格式	示例
用户（按 ID）	`user:<aad-object-id>`	`user:40a1a0ed-4ff2-4164-a219-55518990c197`
用户（按名称）	`user:<display-name>`	`user:John Smith`（需要 Graph API）
群组/频道	`conversation:<conversation-id>`	`conversation:19:abc123...@thread.tacv2`
群组/频道（原始）	`<conversation-id>`	`19:abc123...@thread.tacv2`（包含 `@thread` 时）

CLI 示例：

bash

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

# 按显示名称发送给用户（触发 Graph API 查找）
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"

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

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

智能体（Agent）工具示例：

json

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

json

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

注意：没有 user: 前缀时，名称默认解析为群组/团队。通过显示名称定位用户时，请始终使用 user: 前缀。

主动消息

主动消息仅在用户已交互后才可用，因为我们在那时存储了会话引用。
参见 /gateway/configuration 了解 dmPolicy 和允许列表门控。

团队和频道 ID（常见陷阱）

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

团队 URL：

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    团队 ID（对此进行 URL 解码）

频道 URL：

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      频道 ID（对此进行 URL 解码）

用于配置：

团队 ID = /team/ 后的路径段（URL 解码后，例如 19:Bk4j...@thread.tacv2）
频道 ID = /channel/ 后的路径段（URL 解码后）
忽略 groupId 查询参数

私有频道

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

功能	标准频道	私有频道
机器人安装	是	有限
实时消息（Webhook）	是	可能无法工作
RSC 权限	是	行为可能不同
@提及	是	如果机器人可访问
Graph API 历史	是	是（需要权限）

私有频道不工作时的替代方案：

使用标准频道进行机器人交互
使用私聊 - 用户总是可以直接给机器人发消息
使用 Graph API 进行历史访问（需要 ChannelMessage.Read.All）

故障排查

常见问题

频道中图片不显示： Graph 权限或管理员同意缺失。重新安装 Teams 应用并完全退出/重新打开 Teams。
频道中无回复： 默认需要提及；设置 channels.msteams.requireMention=false 或按团队/频道配置。
版本不匹配（Teams 仍显示旧清单）： 移除 + 重新添加应用并完全退出 Teams 以刷新。
Webhook 返回 401 Unauthorized： 在没有 Azure JWT 的情况下手动测试时是预期行为 - 表示端点可达但认证失败。使用 Azure Web Chat 进行正确测试。

清单上传错误

"Icon file cannot be empty"： 清单引用了 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 权限不工作

验证 webApplicationInfo.id 与你的机器人 App ID 完全匹配
重新上传应用并在团队/聊天中重新安装
检查你的组织管理员是否阻止了 RSC 权限
确认你使用了正确的范围：团队使用 ChannelMessage.Read.Group，群聊使用 ChatMessage.Read.Chat

Microsoft Teams（插件） ​

需要安装插件 ​

快速设置（新手） ​

目标 ​

配置写入 ​

访问控制（私聊 + 群组） ​

工作原理 ​

Azure Bot 设置（前提条件） ​

步骤 1：创建 Azure Bot ​

步骤 2：获取凭证 ​

步骤 3：配置消息端点 ​

步骤 4：启用 Teams 通道 ​

本地开发（隧道） ​

Teams 开发者门户（替代方案） ​

测试机器人 ​

设置（最小纯文本） ​

历史上下文 ​

当前 Teams RSC 权限（清单） ​

Teams 清单示例（已脱敏） ​

清单注意事项（必需字段） ​

更新现有应用 ​

功能：仅 RSC vs Graph ​

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

使用 Teams RSC + Microsoft Graph 应用程序权限 ​

RSC vs Graph API ​

启用 Graph 的媒体 + 历史（频道所需） ​

已知限制 ​

Webhook 超时 ​

格式 ​

配置 ​

路由与会话 ​

回复样式：线程 vs 帖子 ​

附件与图片 ​

在群聊中发送文件 ​

为什么群聊需要 SharePoint ​

设置 ​

共享行为 ​

回退行为 ​

文件存储位置 ​

投票（Adaptive Cards） ​

Adaptive Cards（任意） ​

目标格式 ​

主动消息 ​

团队和频道 ID（常见陷阱） ​

私有频道 ​

故障排查 ​

常见问题 ​

清单上传错误 ​

RSC 权限不工作 ​

参考资料 ​

Microsoft Teams（插件）

需要安装插件

快速设置（新手）

目标

配置写入

访问控制（私聊 + 群组）

工作原理

Azure Bot 设置（前提条件）

步骤 1：创建 Azure Bot

步骤 2：获取凭证

步骤 3：配置消息端点

步骤 4：启用 Teams 通道

本地开发（隧道）

Teams 开发者门户（替代方案）

测试机器人

设置（最小纯文本）

历史上下文

当前 Teams RSC 权限（清单）

Teams 清单示例（已脱敏）

清单注意事项（必需字段）

更新现有应用

功能：仅 RSC vs Graph

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

使用 Teams RSC + Microsoft Graph 应用程序权限

RSC vs Graph API

启用 Graph 的媒体 + 历史（频道所需）

已知限制

Webhook 超时

格式

配置

路由与会话

回复样式：线程 vs 帖子

附件与图片

在群聊中发送文件

为什么群聊需要 SharePoint

设置

共享行为

回退行为

文件存储位置

投票（Adaptive Cards）

Adaptive Cards（任意）

目标格式

主动消息

团队和频道 ID（常见陷阱）

私有频道

故障排查

常见问题

清单上传错误

RSC 权限不工作

参考资料