故障排除

Teams 路径不支持的内容、运维人员最常遇到的故障，以及更多资料的阅读位置。

已知限制¶

Webhook 超时¶

Teams 通过 Gateway HTTP webhook 路由传递消息。有界 Express 解析器保持 1 MiB 解码后 JSON 限制，包括 gzip、deflate 和 Brotli 回调。Gateway HTTP 生命周期限制应用于主监听器；兼容性监听器保留之前的 Teams 限制：30 秒无活动、30 秒总请求、15 秒接收标头。在通道停止期间，新回调会收到可重试的 HTTP 503，直到活动响应结束，最长 30 秒，然后路由才会释放。可选的入站媒体和上下文增强共享 10 秒预算。SDK 在原始活动持久追加后返回；代理回合独立排空并主动回复。如果请求处理或持久准入错过传输窗口，Teams 可能会重试该活动，并且入口墓碑会拒绝重复的事件 ID。

如果在设置 legacyWebhook: false 后 Teams 没有响应，请检查 Azure Bot 或反向代理是否仍指向端口 3978。按照端点迁移说明使用 Gateway 端口，或完成显式旧版监听器的迁移。

Teams 云与 service URL 支持¶

此基于 SDK 的 Teams 路径已在 Microsoft Teams 公共云上经过实时验证。

入站回复使用传入的 Teams SDK 回合上下文。上下文外的主动操作——发送、编辑、删除、卡片、投票、文件同意消息和排队中的长时回复——使用已存储的对话引用 serviceUrl。公共云默认使用 Teams SDK 公共云环境，并允许在公共 Teams Connector 主机上存储引用：https://smba.trafficmanager.net/。

公共云是默认值。对于常规公共云机器人，无需设置 channels.msteams.cloud 或 channels.msteams.serviceUrl。

对于非公共 Teams 云，请在 Microsoft 发布相应主动边界时设置 cloud 和匹配的主动边界：

• channels.msteams.cloud 选择用于身份验证、JWT 验证、令牌服务和 Graph 范围的 Teams SDK 云预设。
• channels.msteams.serviceUrl 选择 Bot Connector 端点边界，用于在主动发送、编辑、删除、卡片、投票、文件同意消息和排队中的长时回复之前验证已存储的对话引用。USGov 和 DoD SDK 云需要设置它。对于 China/21Vianet，OpenClaw 使用 SDK China 预设，并且仅接受 Azure China Bot Framework 通道主机上的已存储/已配置 service URL。

Microsoft 在 Teams 主动消息文档的创建对话部分发布了全局主动 Bot Connector 端点。如果可用，请使用传入活动的 serviceUrl；否则使用 Microsoft 的下表。

GCC 示例：Microsoft 记录了单独的主动 service URL，但 Teams SDK 未公开单独的 GCC 云预设：

{
  "channels": {
    "msteams": {
      "serviceUrl": "https://smba.infra.gcc.teams.microsoft.com/teams"
    }
  }
}

GCC High 示例：

{
  "channels": {
    "msteams": {
      "cloud": "USGov",
      "serviceUrl": "https://smba.infra.gov.teams.microsoft.us/teams"
    }
  }
}

channels.msteams.serviceUrl 仅限于受支持的 Microsoft Teams Bot Connector 主机。配置 service URL 后，OpenClaw 会在主动发送、编辑、删除、卡片、投票或排队中的长时回复运行之前，检查已存储对话的 serviceUrl 是否使用相同主机。使用默认公共云配置时，如果已存储对话指向公共 Teams Connector 主机之外，OpenClaw 会采取失败关闭策略。更改 cloud/service URL 设置后，请从该对话接收一条新消息，以确保已存储的对话引用是最新的。

Microsoft 的 Teams 主动端点表中，China/21Vianet 没有单独的全局主动 smba URL。请配置 cloud: "China"，使 Teams SDK 使用 Azure China 身份验证、令牌和 JWT 端点。之后，主动发送需要来自传入 China Teams 活动的已存储对话引用，或在 Azure China Bot Framework 通道边界（*.botframework.azure.cn）上显式配置的 service URL。在 OpenClaw 通过 Azure China Graph 端点路由 Graph 请求之前，cloud: "China" 会禁用基于 Graph 的 Teams 辅助功能。

格式¶

Teams Markdown 比 Slack 或 Discord 更有限：

• 基本格式可用：粗体、斜体、code、链接。
• 文本编辑、文件说明和已确定的流式回复使用与普通消息相同的 Markdown 转换和用户提及格式。流式预览可能会显示未完成的 Markdown，直到最终回复替换它们。
• 复杂 Markdown（表格、嵌套列表）可能无法正确渲染。
• 支持 Adaptive Cards 用于审批提示、投票和语义化展示发送（参见卡片和操作）。

故障排除¶

常见问题¶

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

清单上传错误¶

• “图标文件不能为空”： 清单引用了 0 字节的图标文件。请创建有效的 PNG 图标（outline.png 为 32x32，color.png 为 192x192）。
• “webApplicationInfo.Id 已被使用”： 该应用仍安装在另一个团队/聊天中。请先找到并卸载它，或等待 5-10 分钟以完成传播。
• 上传时出现“出错了”： 请改为通过 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ Network 选项卡，并检查响应正文以获取实际错误。
• 侧载失败： 请尝试使用“将应用上传到组织的应用目录”而不是“上传自定义应用”；这通常可以绕过侧载限制。

RSC 权限不生效¶

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

参考资料¶

• 创建 Azure Bot - Azure Bot 设置指南
• Teams 开发者门户 - 创建/管理 Teams 应用
• Teams 应用清单架构
• 使用 RSC 接收频道消息
• RSC 权限参考
• Teams 机器人文件处理（频道/群组需要 Graph）
• 主动消息
• @microsoft/teams.cli - 用于机器人管理的 Teams CLI

相关¶

• 频道概览 - 所有受支持的频道
• 配对 - DM 身份验证和配对流程
• 群组 - 群聊行为和提及门控
• 频道路由 - 消息的会话路由
• 安全 - 访问模型和加固