学了个寂寞

Appearance

Microsoft Teams（插件） ​

"放弃吧，所有进入这里的人。"

更新时间：2026-01-21

支持状态：文本 + 私信附件均受支持；频道/群组文件发送需要 sharePointSiteId + Graph 权限（见在群聊中发送文件）。投票通过 Adaptive Cards 发送。消息操作提供显式的 upload-file 用于文件优先发送。

安装插件 ​

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

重大变更（2026.1.15）： Microsoft Teams 已从核心迁出。如果你使用它，必须安装插件。

这样设计可以保持核心安装包轻量，并让 Microsoft Teams 依赖独立更新。

通过 CLI 安装（npm 仓库）：

bash
openclaw plugins install @openclaw/msteams

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

bash
openclaw plugins install ./extensions/msteams

在设置时选择 Teams 且检测到 git 代码仓库时，OpenClaw 会自动提示使用本地安装路径。

详见：插件说明

快速配置（初学者） ​

  1. 安装 Microsoft Teams 插件。
  2. 创建 Azure Bot（App ID + 客户端密钥 + 租户 ID）。
  3. 用这些凭证配置 OpenClaw。
  4. 通过公网 URL 或隧道暴露 /api/messages（默认端口 3978）。
  5. 安装 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 对话。
  • 保持路由确定性：回复始终返回到消息来源的渠道。
  • 默认安全的频道行为（必须 @提及，除非另行配置）。

配置写入 ​

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

禁用方式：

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

示例：

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

Teams + 频道白名单

  • 在 channels.msteams.teams 下列出团队和频道，以限制群组/频道回复的范围。
  • 键应使用稳定的团队 ID 和频道会话 ID。
  • 当 groupPolicy="allowlist" 且存在 Teams 白名单时，只接受列表中的团队/频道（需 @提及）。
  • 配置向导接受 Team/Channel 条目并为你存储。
  • 启动时，OpenClaw 在 Graph 权限允许的情况下将团队/频道和用户白名单名称解析为 ID 并记录映射；未解析的团队/频道名称会原样保留，但除非 channels.msteams.dangerouslyAllowNameMatching: true，否则默认会被路由忽略。

示例：

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

工作原理 ​

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

Azure Bot 配置（前提条件） ​

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

第一步：创建 Azure Bot ​

  1. 访问 创建 Azure Bot

  2. 填写 Basics 标签页：

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

废弃通知： 2025-07-31 之后，新多租户 Bot 的创建已废弃。新 Bot 请使用 Single Tenant。

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

第二步：获取凭证 ​

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

第三步：配置消息端点 ​

  1. 在 Azure Bot → Configuration 中
  2. 将 Messaging endpoint 设置为你的 Webhook URL：

第四步：启用 Teams 频道 ​

  1. 在 Azure Bot → Channels 中
  2. 点击 Microsoft Teams → Configure → Save
  3. 接受服务条款

本地开发（隧道） ​

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：

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

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

测试机器人 ​

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

  1. 在 Azure 门户 → 你的 Azure Bot 资源 → Test in Web Chat
  2. 发送消息——你应该能看到响应
  3. 这确认你的 Webhook 端点在 Teams 配置前已正常工作

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

  1. 安装 Teams 应用（侧载或组织目录）
  2. 在 Teams 中找到机器人并发送私信
  3. 查看 Gateway 日志中的入站活动

配置（纯文本最小版） ​

  1. 安装 Microsoft Teams 插件

    • 从 npm：openclaw plugins install @openclaw/msteams
    • 从本地仓库：openclaw plugins install ./extensions/msteams

  2. 注册 Bot

    • 创建 Azure Bot（见上方）并记录：
      • App ID
      • 客户端密钥（App 密码）
      • 租户 ID（单租户）

  3. Teams 应用清单

    • 包含 botId = <App ID> 的 bot 条目。
    • 范围：personal、team、groupChat。
    • supportsFiles: true（个人范围文件处理必需）。
    • 添加 RSC 权限（见下方）。
    • 创建图标：outline.png（32x32）和 color.png（192x192）。
    • 将三个文件打包成 ZIP：manifest.json、outline.png、color.png。

  4. 配置 OpenClaw

    json5
    {
  channels: {
    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

  5. Bot 端点

    • 将 Azure Bot 消息端点设置为：
      • https://<host>:3978/api/messages（或你选择的路径/端口）。

  6. 运行 Gateway

    • 安装插件且 msteams 配置存在凭证时，Teams 渠道会自动启动。

历史上下文 ​

  • channels.msteams.historyLimit 控制包含在提示中的最近频道/群组消息数量。
  • 回退到 messages.groupChat.historyLimit，设置 0 禁用（默认 50）。
  • 私信历史可用 channels.msteams.dmHistoryLimit 限制（用户轮次）。每用户覆盖：channels.msteams.dms["<user_id>"].historyLimit。

当前 Teams RSC 权限（清单） ​

这些是 Teams 应用清单中现有的 resourceSpecific 权限，仅在安装了应用的团队/聊天中生效。

频道（团队范围）：

  • ChannelMessage.Read.Group（应用）- 无需 @提及即可接收所有频道消息
  • ChannelMessage.Send.Group（应用）
  • Member.Read.Group（应用）
  • Owner.Read.Group（应用）
  • ChannelSettings.Read.Group（应用）
  • TeamMember.Read.Group（应用）
  • TeamSettings.Read.Group（应用）

群聊：

  • ChatMessage.Read.Chat（应用）- 无需 @提及即可接收所有群聊消息

Teams 清单示例（已脱敏） ​

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

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

  1. 更新 manifest.json 中的新设置
  2. 增加 version 字段（例如 1.0.0 → 1.1.0）
  3. 重新打包 清单和图标（manifest.json、outline.png、color.png）
  4. 上传新 ZIP：
    • 选项 A（Teams 管理中心）： Teams 管理中心 → Teams 应用 → 管理应用 → 找到你的应用 → 上传新版本
    • 选项 B（侧载）： 在 Teams 中 → 应用 → 管理你的应用 → 上传自定义应用
  5. 对于团队频道： 在每个团队中重新安装应用，使新权限生效
  6. 完全退出并重新启动 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 权限并授权管理员同意。

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

用户 @提及的额外权限： 会话中已有用户的 @提及无需额外权限。但如果需要动态搜索并提及不在当前会话中的用户，添加 User.Read.All（应用）权限并授予管理员同意。

已知限制 ​

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/显示名称匹配和直接团队/频道名称路由。
  • 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（见回复样式）。
  • 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：每频道每发送者工具策略（支持 "*" 通配符）。
  • toolsBySender 键应使用明确的前缀：id:、e164:、username:、name:（旧版无前缀键仍映射到 id:）。
  • channels.msteams.sharePointSiteId：群聊/频道文件上传的 SharePoint 站点 ID（见在群聊中发送文件）。

路由与会话 ​

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

回复样式：线程 vs 帖子 ​

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

样式描述建议的 replyStyle
帖子（经典）消息以卡片形式显示，回复嵌套在下方thread（默认）
线程（类Slack）消息线性流动，更像 Slacktop-level

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

  • 在线程样式频道中使用 thread → 回复显示为尴尬的嵌套
  • 在帖子样式频道中使用 top-level → 回复作为独立的顶层帖子出现，而非在线程中

解决方案： 根据频道的实际设置，为每个频道配置 replyStyle：

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

附件与图片 ​

当前限制：

  • 私信： 图片和文件附件通过 Teams Bot 文件 API 正常工作。
  • 频道/群组： 附件存储在 M365（SharePoint/OneDrive）中。Webhook 载荷只包含 HTML 存根，不含实际文件字节。下载频道附件需要 Graph API 权限。
  • 对于显式的文件优先发送，使用 action=upload-file 加 media / filePath / path；可选的 message 作为附带文本/注释，filename 覆盖上传名称。

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

在群聊中发送文件 ​

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

场景文件发送方式需要的配置
私信FileConsentCard → 用户接受 → Bot 上传开箱即用
群聊/频道上传到 SharePoint → 共享链接需要 sharePointSiteId + Graph 权限
图片（任意场景）Base64 内联开箱即用

为何群聊需要 SharePoint ​

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

配置步骤 ​

  1. 在 Entra ID（Azure AD）→ App Registration 中添加 Graph API 权限：

    • Sites.ReadWrite.All（应用）- 上传文件到 SharePoint
    • Chat.Read.All（应用）- 可选，启用每用户共享链接

  2. 为租户授予管理员同意。

  3. 获取你的 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"

  4. 配置 OpenClaw：

    json5
    {
  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（任意卡片） ​

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

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

智能体工具：

json5
{
  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 示例详见 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"}]}'

智能体工具示例：

json5
{
  action: "send",
  channel: "msteams",
  target: "user:John Smith",
  message: "Hello!",
}
json5
{
  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 查询参数

私有频道 ​

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

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

私有频道不工作时的解决方案：

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

故障排查 ​

常见问题 ​

  • 频道中图片不显示： 缺少 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 与你的 Bot App ID 完全一致
  2. 重新上传应用并在团队/聊天中重新安装
  3. 检查你的组织管理员是否阻止了 RSC 权限
  4. 确认使用了正确的范围：团队用 ChannelMessage.Read.Group，群聊用 ChatMessage.Read.Chat

参考链接 ​

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策