Microsoft Teams（插件）

"Enter here, abandon all hope."

更新日期：2026-01-21

状态：支持文本 + DM 附件；频道/群组文件发送需要 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（应用 ID + 客户端密钥 + 租户 ID）。
使用这些凭证配置 OpenClaw。
公开 /api/messages（默认端口 3978）通过公共 URL 或隧道。
安装 Teams 应用包并启动网关。

最小配置：

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

配置写入

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

禁用：

json5

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

访问控制（DM + 群组）

DM 访问

默认：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"]
    }
  }
}

Teams + 频道允许列表

通过在 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（应用 ID + 密钥 + 租户 ID）。
构建引用机器人的 Teams 应用包并包含下面的 RSC 权限。
将 Teams 应用安装到团队（或个人范围的 DM）。
在 ~/.openclaw/openclaw.json 中配置 msteams（或环境变量）并启动网关。
网关默认在 /api/messages 上侦听 Bot Framework webhook 流量。

Azure Bot 设置（先决条件）

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

步骤 1：创建 Azure Bot

转到 Create Azure Bot

填写 Basics 选项卡：

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

弃用通知： 2025-07-31 之后新的多租户机器人创建已被弃用。新机器人使用 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：配置消息传递端点

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

步骤 4：启用 Teams 频道

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

本地开发（隧道）

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：

点击 + 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 清单更容易。

测试机器人

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

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

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

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

设置（最小文本支持）

安装 Microsoft Teams 插件
- 从 npm：openclaw plugins install @openclaw/msteams
- 从本地检出：openclaw plugins install ./extensions/msteams
机器人注册
- 创建 Azure Bot（见上文）并记下：
  - 应用 ID
  - 客户端密钥（应用密码）
  - 租户 ID（单租户）
Teams 应用清单
- 包含引用机器人的 bot 条目，botId = <App ID>。
- 范围：personal、team、groupChat。
- supportsFiles: true（个人范围文件处理需要）。
- 添加 RSC 权限（下方）。
- 创建图标：outline.png (32x32) 和 color.png (192x192)。
- 将三个文件打包在一起：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（或你选择的路径/端口）。
运行网关
- 当插件安装且具有凭证的 msteams 配置存在时，Teams 通道自动启动。

历史上下文

channels.msteams.historyLimit 控制作为上下文包裹到提示中的最近频道/群组消息数量。
回退到 messages.groupChat.historyLimit。设置为 0 禁用（默认 50）。
DM 历史可以通过 channels.msteams.dmHistoryLimit 限制（用户轮）。每用户覆盖：channels.msteams.dms["<user_id>"].historyLimit。

当前 Teams RSC 权限（清单）

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

对于频道（团队范围）：

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 应用 ID。
webApplicationInfo.id 必须匹配 Azure Bot 应用 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 Admin Center）： Teams Admin Center → Teams apps → Manage apps → 找到你的应用 → Upload new version
- 选项 B（侧载）： 在 Teams 中 → Apps → Manage your apps → Upload a custom app
对于团队频道： 重新安装 Teams 中的应用以使新权限生效
完全退出并重启 Teams（不仅仅是关闭窗口）以清除缓存的应用元数据

功能：RSC 仅 vs Graph

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

工作：

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

不工作：

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

使用 Teams RSC + Microsoft Graph Application 权限

增加：

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

RSC vs Graph API

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

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

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

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

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

已知限制

Webhook 超时

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

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

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

格式化

Teams markdown 比 Slack 或 Discord 更有限：

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

配置

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

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：DM 允许列表（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：每团队覆盖。
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（见在群组聊天中发送文件）。

路由与会话

会话密钥遵循标准智能体格式（见 /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：

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

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

json

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

附件和图片

当前限制：

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

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

在群组聊天中发送文件

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

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

为什么群组聊天需要 SharePoint

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

设置

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

获取你的 SharePoint 站点 ID：

bash

# 通过 Graph Explorer 或 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 将 Teams 投票发送为 Adaptive Cards（没有原生的 Teams 投票 API）。

CLI：openclaw message poll --channel msteams --target conversation:<id> ...
投票由网关记录在 ~/.openclaw/msteams-polls.json 中。
网关必须保持在线以记录投票。
投票尚未自动发布结果摘要（需要检查存储文件）。

Adaptive Cards（任意）

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

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

智能体工具：

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 文档。有关目标格式详情，见下方目标格式。

目标格式

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

智能体工具示例：

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:。

主动消息

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

团队和频道 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 历史	是	是（需要权限）

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

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

故障排除

常见问题

图片在频道中不显示： Graph 权限或管理员同意缺失。重新安装 Teams 应用并完全退出重新打开 Teams。
频道中没有回复： 默认需要提及；设置 channels.msteams.requireMention=false 或按团队/频道配置。
版本不匹配（Teams 仍然显示旧清单）： 移除 + 重新添加应用并完全退出 Teams 刷新。
401 Unauthorized 来自 webhook： 测试手动时预期没有 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" on upload: 尝试通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 选项卡，并检查响应体中的实际错误。
侧载失败： 尝试"上传应用到组织的应用目录"而不是"上传自定义应用" - 这通常绕过侧载限制。

RSC 权限不工作

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

Microsoft Teams（插件） ​

需要插件 ​

快速设置（入门） ​

设计目标 ​

配置写入 ​

访问控制（DM + 群组） ​

工作原理 ​

Azure Bot 设置（先决条件） ​

步骤 1：创建 Azure Bot ​

步骤 2：获取凭证 ​

步骤 3：配置消息传递端点 ​

步骤 4：启用 Teams 频道 ​

本地开发（隧道） ​

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

测试机器人 ​

设置（最小文本支持） ​

历史上下文 ​

当前 Teams RSC 权限（清单） ​

示例 Teams 清单（已编辑） ​

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

更新现有应用 ​

功能：RSC 仅 vs Graph ​

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

使用 Teams RSC + Microsoft Graph Application 权限 ​

RSC vs Graph API ​

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

已知限制 ​

Webhook 超时 ​

格式化 ​

配置 ​

路由与会话 ​

回复样式：线程 vs 帖子 ​

附件和图片 ​

在群组聊天中发送文件 ​

为什么群组聊天需要 SharePoint ​

设置 ​

共享行为 ​

回退行为 ​

文件存储位置 ​

投票（Adaptive Cards） ​

Adaptive Cards（任意） ​

目标格式 ​

主动消息 ​

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

私人频道 ​

故障排除 ​

常见问题 ​

清单上传错误 ​

RSC 权限不工作 ​

参考 ​

Microsoft Teams（插件）

需要插件

快速设置（入门）

设计目标

配置写入

访问控制（DM + 群组）

工作原理

Azure Bot 设置（先决条件）

步骤 1：创建 Azure Bot

步骤 2：获取凭证

步骤 3：配置消息传递端点

步骤 4：启用 Teams 频道

本地开发（隧道）

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

测试机器人

设置（最小文本支持）

历史上下文

当前 Teams RSC 权限（清单）

示例 Teams 清单（已编辑）

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

更新现有应用

功能：RSC 仅 vs Graph

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

使用 Teams RSC + Microsoft Graph Application 权限

RSC vs Graph API

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

已知限制

Webhook 超时

格式化

配置

路由与会话

回复样式：线程 vs 帖子

附件和图片

在群组聊天中发送文件

为什么群组聊天需要 SharePoint

设置

共享行为

回退行为

文件存储位置

投票（Adaptive Cards）

Adaptive Cards（任意）

目标格式

主动消息

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

私人频道

故障排除

常见问题

清单上传错误

RSC 权限不工作

参考