跳转至

故障排除

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 云和服务 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 通道主机上的已存储/已配置服务 URL。

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

Teams 环境 OpenClaw 配置 主动 serviceUrl
公共 无需 cloud/serviceUrl 配置 https://smba.trafficmanager.net/teams
GCC 设置 serviceUrl;不存在单独的 Teams SDK 云预设 https://smba.infra.gcc.teams.microsoft.com/teams
GCC High cloud: "USGov" + serviceUrl https://smba.infra.gov.teams.microsoft.us/teams
DoD cloud: "USGovDoD" + serviceUrl https://smba.infra.dod.teams.microsoft.us/teams
China/21Vianet cloud: "China" 使用传入活动的 serviceUrl

GCC 示例:Microsoft 记录了单独的主动服务 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 主机。配置了服务 URL 后,OpenClaw 会在主动发送、编辑、删除、卡片、投票或排队的长时回复运行之前,检查已存储会话的 serviceUrl 是否使用相同主机。在默认公共云配置下,如果已存储会话指向公共 Teams Connector 主机之外,OpenClaw 会失败关闭。更改 cloud/服务 URL 设置后,请从该会话接收一条新消息,以确保已存储的会话引用是最新的。

China/21Vianet 在 Microsoft 的 Teams 主动端点表中没有单独的全局主动 smba URL。请配置 cloud: "China",以便 Teams SDK 使用 Azure China 身份验证、令牌和 JWT 端点。随后,主动发送需要来自传入 China Teams 活动的已存储会话引用,或者在 Azure China Bot Framework 通道边界(*.botframework.azure.cn)上显式配置的服务 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 进行正确测试。

清单上传错误

  • "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 选项卡,并检查响应正文以获取实际错误。
  • 侧载失败: 请尝试使用“Upload an app to your org's app catalog”而不是“Upload a custom app”;这通常可以绕过侧载限制。

RSC 权限不生效

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

参考资料

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw