Microsoft Teams（插件）

“进入此处者，放弃一切希望。”

更新时间：2026-01-21

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

需要安装插件

Microsoft Teams 以插件形式提供，不包含在核心安装中。

破坏性变更 (2026.1.15)： MS Teams 已从核心移出。如需使用，必须安装插件。

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

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

openclaw plugins install @openclaw/msteams

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

openclaw plugins install ./extensions/msteams

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

详情：插件

快速设置（新手）

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

最小配置：

{
  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 对话。
保持路由确定性：回复始终返回到它到达的频道。
默认安全的频道行为（除非另行配置，否则需要提及）。

配置写入

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

禁用：

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

访问控制（私信 + 群组）

私信访问

默认：channels.msteams.dmPolicy = "pairing"。未知发送者在被批准之前会被忽略。
channels.msteams.allowFrom 应使用稳定的 AAD 对象 ID。
UPN/显示名称是可变的；直接匹配默认禁用，仅在 channels.msteams.dangerouslyAllowNameMatching: true 时启用。
当凭据允许时，向导可通过 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: ["[email protected]"],
    },
  },
}

Teams + 频道白名单

通过在 channels.msteams.teams 下列出 team 和 channel 来限定群组/频道回复范围。
键应使用稳定的 team ID 和 channel conversation ID。
当 groupPolicy="allowlist" 且存在 teams 白名单时，只有列出的 team/channel 被接受（仍需提及）。
配置向导接受 Team/Channel 条目并为你存储。
启动时，OpenClaw 会将 team/channel 和用户白名单名称解析为 ID（当 Graph 权限允许时），并记录映射；未解析的 team/channel 名称保持原样但默认不参与路由，除非 channels.msteams.dangerouslyAllowNameMatching: true 已启用。

示例：

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

工作原理

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

Azure Bot 设置（前置条件）

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

步骤 1：创建 Azure Bot

前往 Create Azure Bot

填写 Basics 标签页：

字段	值
Bot handle	你的 Bot 名称，例如 `openclaw-msteams`（必须唯一）
Subscription	选择你的 Azure 订阅
Resource group	新建或使用现有
Pricing tier	开发/测试选 Free
Type of App	Single Tenant（推荐——见下方说明）
Creation type	Create new Microsoft App ID

注意： 2025-07-31 之后已弃用创建新的多租户 Bot。新 Bot 请使用 Single Tenant。

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

步骤 2：获取凭据

前往 Azure Bot 资源 → Configuration
复制 Microsoft App ID → 这是你的 appId
点击 Manage Password → 进入 App Registration
在 Certificates & secrets → New client secret → 复制 Value → 这是你的 appPassword
前往 Overview → 复制 Directory (tenant) ID → 这是你的 tenantId

步骤 3：配置 Messaging Endpoint

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

步骤 4：启用 Teams Channel

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

本地开发（隧道）

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（替代方案）

你也可以使用 Teams Developer Portal 代替手动创建 manifest ZIP：

点击 + New app
填写基本信息（名称、描述、开发者信息）
前往 App features → Bot
选择 Enter a bot ID manually 并粘贴你的 Azure Bot App ID
勾选范围：Personal、Team、Group Chat
点击 Distribute → Download app package
在 Teams 中：Apps → Manage your apps → Upload a custom app → 选择 ZIP

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

测试 Bot

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

在 Azure Portal → 你的 Azure Bot 资源 → Test in Web Chat
发送一条消息——你应该看到回复
这确认了你的 webhook 端点在 Teams 设置之前可以正常工作

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

安装 Teams 应用（旁加载或组织目录）
在 Teams 中找到 Bot 并发送私信
检查 Gateway 日志中的入站活动

设置（最小纯文本）

安装 Microsoft Teams 插件
- 从 npm：openclaw plugins install @openclaw/msteams
- 从本地 checkout：openclaw plugins install ./extensions/msteams
Bot 注册
- 创建 Azure Bot（见上文）并记录：
  - App ID
  - 客户端密钥（App password）
  - 租户 ID（单租户）
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。

配置 OpenClaw

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

Bot endpoint
- 将 Azure Bot Messaging Endpoint 设置为：
  - https://<host>:3978/api/messages（或你选择的路径/端口）。
运行 Gateway
- 当插件已安装且存在带凭据的 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 权限。它们仅在应用安装的 team/chat 内生效。

频道（team 范围）：

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": "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" }
      ]
    }
  }
}

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

使用新设置更新 manifest.json
递增 version 字段（例如 1.0.0 → 1.1.0）
重新打包 manifest 与图标（manifest.json、outline.png、color.png）
上传新 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
对于 team 频道： 在每个 team 中重新安装应用以使新权限生效
完全退出并重新启动 Teams（不仅是关闭窗口）以清除缓存的应用元数据

功能：仅 RSC vs Graph

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

可用：

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

不可用：

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

使用 Teams RSC + Microsoft Graph Application 权限

新增：

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

RSC vs Graph API

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

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

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

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

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

用户提及的额外权限： 用户 @提及对于对话中的用户开箱即用。但如果要动态搜索和提及不在当前对话中的用户，需添加 User.Read.All (Application) 权限并授予管理员同意。

已知限制

Webhook 超时

Teams 通过 HTTP webhook 投递消息。如果处理时间过长（例如 LLM 响应较慢），可能出现：

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

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

格式

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

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

配置

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

channels.msteams.enabled：启用/禁用频道。
channels.msteams.appId、channels.msteams.appPassword、channels.msteams.tenantId：Bot 凭据。
channels.msteams.webhook.port（默认 3978）
channels.msteams.webhook.path（默认 /api/messages）
channels.msteams.dmPolicy：pairing | allowlist | open | disabled（默认：pairing）
channels.msteams.allowFrom：私信白名单（推荐使用 AAD 对象 ID）。设置向导在 Graph 访问可用时会在设置过程中将名称解析为 ID。
channels.msteams.dangerouslyAllowNameMatching：紧急开关，重新启用可变 UPN/显示名称匹配和直接 team/channel 名称路由。
channels.msteams.textChunkLimit：出站文本分块大小。
channels.msteams.chunkMode：length（默认）或 newline，在长度分块前在空行（段落边界）处分割。
channels.msteams.mediaAllowHosts：入站附件主机白名单（默认为 Microsoft/Teams 域名）。
channels.msteams.mediaAuthAllowHosts：媒体重试时附加 Authorization header 的主机白名单（默认为 Graph + Bot Framework 主机）。
channels.msteams.requireMention：频道/群组中需要 @提及（默认 true）。
channels.msteams.replyStyle：thread | top-level（参见回复样式）。
channels.msteams.teams.<teamId>.replyStyle：按 team 覆盖。
channels.msteams.teams.<teamId>.requireMention：按 team 覆盖。
channels.msteams.teams.<teamId>.tools：当频道覆盖缺失时使用的默认按 team 工具策略覆盖（allow/deny/alsoAllow）。
channels.msteams.teams.<teamId>.toolsBySender：默认按 team 按发送者工具策略覆盖（支持 "*" 通配符）。
channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle：按频道覆盖。
channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention：按频道覆盖。
channels.msteams.teams.<teamId>.channels.<conversationId>.tools：按频道工具策略覆盖。
channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender：按频道按发送者工具策略覆盖。
toolsBySender 键应使用显式前缀：id:、e164:、username:、name:（旧版无前缀键仍映射为 id:）。
channels.msteams.sharePointSiteId：群组聊天/频道文件上传的 SharePoint site ID（参见在群组聊天中发送文件）。

路由与会话

会话键遵循标准 Agent 格式（参见 /concepts/session）：
- 私信共享主会话（agent:<agentId>:<mainKey>）。
- 频道/群组消息使用 conversation 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：

thread 在 Threads 样式频道中 → 回复以笨拙的嵌套形式出现
top-level 在 Posts 样式频道中 → 回复显示为独立的顶层帖子而非在线程中

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

{
  "msteams": {
    "replyStyle": "thread",
    "teams": {
      "19:[email protected]": {
        "channels": {
          "19:[email protected]": {
            "replyStyle": "top-level"
          }
        }
      }
    }
  }
}

附件和图片

当前限制：

私信： 图片和文件附件通过 Teams Bot 文件 API 正常工作。
频道/群组： 附件存储在 M365 存储（SharePoint/OneDrive）中。Webhook payload 仅包含 HTML 占位符，不含实际文件字节。需要 Graph API 权限才能下载频道附件。

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

在群组聊天中发送文件

Bot 可以在私信中使用 FileConsentCard 流程发送文件（内置）。但在群组聊天/频道中发送文件需要额外设置：

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

群组聊天为何需要 SharePoint

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

设置

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

获取 SharePoint site 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"

配置 OpenClaw：

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

分享行为

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

按用户分享更安全，因为只有聊天参与者可以访问文件。如果缺少 Chat.Read.All 权限，Bot 会回退到组织范围分享。

回退行为

场景	结果
群组聊天 + 文件 + 已配置 `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（任意）

使用消息工具或 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：

openclaw message send --channel msteams \
  --target "conversation:19:[email protected]" \
  --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:[email protected]`
群组/频道（原始）	`<conversation-id>`	`19:[email protected]`（如果包含 `@thread`）

CLI 示例：

# 按 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:[email protected]" --message "Hello"

# 向对话发送 Adaptive Card
openclaw message send --channel msteams --target "conversation:19:[email protected]" \
  --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:[email protected]",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello" }]
  }
}

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

主动消息

主动消息仅在用户已交互后才可能，因为我们在该时刻存储对话引用。
参见 /gateway/configuration 了解 dmPolicy 和白名单门控。

Team 和 Channel ID（常见陷阱）

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

Team URL：

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    Team ID（URL 解码此部分）

Channel URL：

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      Channel ID（URL 解码此部分）

配置用法：

Team ID = /team/ 后的路径段（URL 解码后，例如 19:[email protected]）
Channel ID = /channel/ 后的路径段（URL 解码后）
忽略 groupId 查询参数

私有频道

Bot 在私有频道中的支持有限：

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

私有频道不工作时的变通方案：

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

故障排查

常见问题

频道中图片不显示： 缺少 Graph 权限或管理员同意。重新安装 Teams 应用并完全退出/重新打开 Teams。
频道无回复： 默认需要提及；设置 channels.msteams.requireMention=false 或按 team/channel 配置。
版本不匹配（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”： 应用仍安装在其他 team/chat 中。先找到并卸载，或等待 5-10 分钟以完成传播。
上传时 “Something went wrong”： 改为通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools (F12) → Network 标签，检查响应体中的实际错误。
旁加载失败： 尝试 “Upload an app to your org’s app catalog” 而非 “Upload a custom app”——这通常可绕过旁加载限制。

RSC 权限不工作

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

参考

Create Azure Bot - Azure Bot 设置指南
Teams Developer Portal - 创建/管理 Teams 应用
Teams 应用 manifest schema
通过 RSC 接收频道消息
RSC 权限参考
Teams Bot 文件处理（频道/群组需要 Graph）
主动消息