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

本地检出（当从 git 仓库运行时）：

openclaw plugins install ./extensions/msteams

如果在 configure/onboarding 期间选择 Teams 并检测到 git 检出，OpenClaw 将自动提供本地安装路径。

详情：插件

快速设置（入门）

  1. 安装 Microsoft Teams 插件。
  2. 创建 Azure Bot（应用 ID + 客户端密码 + 租户 ID）。
  3. 使用这些凭据配置 OpenClaw。
  4. 通过公共 URL 或隧道暴露 /api/messages（默认端口 3978）。
  5. 安装 Teams 应用包并启动网关。

最小配置：

{
  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 下列出团队和频道来限制群组/频道回复范围。
  • 键可以是团队 ID 或名称；频道键可以是会话 ID 或名称。
  • 当 groupPolicy="allowlist" 且存在团队允许列表时，仅接受列出的团队/频道（提及门控）。
  • 配置向导接受 Team/Channel 条目并为你存储它们。
  • 启动时，OpenClaw 解析团队/频道和用户允许列表名称为 ID（当 Graph 权限允许时）并记录映射；未解析的条目保持原样。

示例：

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

工作原理

  1. 安装 Microsoft Teams 插件。
  2. 创建 Azure Bot（应用 ID + 密码 + 租户 ID）。
  3. 构建引用机器人的 Teams 应用包并包含下方 RSC 权限。
  4. 在团队中安装 Teams 应用（或私聊的个人范围）。
  5. 在 ~/.openclaw/openclaw.json（或环境变量）中配置 msteams 并启动网关。
  6. 网关默认在 /api/messages 上监听 Bot Framework webhook 流量。

Azure Bot 设置（前置条件）

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

步骤 1：创建 Azure Bot

  1. 转到 Create Azure Bot

  2. 填写 Basics 选项卡：

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

弃用通知： 2025-07-31 后弃用创建新的多租户机器人。新机器人请使用 Single Tenant。

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

步骤 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

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

  1. 在 Azure Bot → Configuration
  2. 将消息传递端点设置为你 的 webhook URL：
    • 生产环境：https://your-domain.com/api/messages
    • 本地开发：使用隧道（见下方本地开发）

步骤 4：启用 Teams 频道

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

本地开发（隧道）

Teams 无法访问 localhost。本地开发使用隧道：

选项 A：ngrok

ngrok http 3978
# 复制 https URL，例如 https://abc123.ngrok.io
# 设置消息传递端点为：https://abc123.ngrok.io/api/messages

选项 B：Tailscale Funnel

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 应用 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 Portal → 你的 Azure Bot 资源 → Test in Web Chat
  2. 发送消息 - 你应该看到回复
  3. 这确认了你的 webhook 端点在 Teams 设置之前工作

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

  1. 安装 Teams 应用（sideload 或组织目录）
  2. 在 Teams 中找到机器人并发送私聊
  3. 检查网关日志中的传入活动

设置（最小文本仅）

  1. 安装 Microsoft Teams 插件

    • 从 npm：openclaw plugins install @openclaw/msteams
    • 从本地检出：openclaw plugins install ./extensions/msteams

  2. 机器人注册

    • 创建 Azure Bot（见上方）并记下：
      • 应用 ID
      • 客户端密码（应用密码）
      • 租户 ID（单租户）

  3. Teams 应用清单

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

  4. 配置 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

  5. 机器人端点

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

  6. 运行网关

    • 当插件安装且 msteams 配置存在凭据时，Teams 频道自动启动。

历史上下文

  • channels.msteams.historyLimit 控制最近多少条频道/群组消息被包装到提示中。
  • 回退到 messages.groupChat.historyLimit。设置为 0 禁用（默认 50）。
  • 私聊历史可以通过 channels.msteams.dmHistoryLimit 限制（用户轮次）。每个用户覆盖：channels.msteams.dms["<user_id>"].historyLimit。

当前 Teams RSC 权限（清单）

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

对于频道（团队范围）：

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

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

  1. 用新设置更新你的 manifest.json
  2. 递增 version 字段（例如 1.0.0 → 1.1.0）
  3. 重新压缩带图标的清单（manifest.json、outline.png、color.png）
  4. 上传新压缩包：
    • 选项 A（Teams 管理中心）： Teams 管理中心 → Teams 应用 → 管理应用 → 找到你的应用 → 上传新版本
    • 选项 B（Sideload）： 在 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）否（仅轮询）
历史消息否是（可以查询历史）
设置复杂仅应用清单需要管理员同意 + 令牌流程
离线工作否（必须运行）是（随时查询）

结论： RSC 用于实时监听；Graph API 用于历史访问。对于离线时遗漏的消息，你需要 Graph API 和 ChannelMessage.Read.All（需要管理员同意）。

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

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

  1. 在 Entra ID（Azure AD）应用注册中，添加 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 响应慢），你可能会看到：

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

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

格式

Teams markdown 比 Slack 或 Discord 更有限：

  • 基本格式化有效：粗体、斜体、代码、链接
  • 复杂 markdown（表格、嵌套列表）可能无法正确呈现
  • 支持 polls 和任意卡片发送的 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：私聊允许列表（推荐 AAD 对象 ID）。向导在 Graph 访问可用时在设置期间将名称解析为 ID
  • channels.msteams.dangerouslyAllowNameMatching：紧急开关以重新启用可变的 UPN/显示名称匹配
  • channels.msteams.textChunkLimit：出站文本块大小
  • channels.msteams.chunkMode：length（默认）或 newline 在长度分块之前按空行（段落边界）分割
  • channels.msteams.mediaAllowHosts：入站附件主机允许列表（默认 Microsoft/Teams 域）
  • channels.msteams.mediaAuthAllowHosts：媒体重试附加授权头的主机允许列表（默认 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（参见在群组聊天中发送文件）

路由和会话

  • 会话键遵循标准智能体格式（参见/concepts/session）：
    • 私聊共享主会话（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：

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

附件和图片

当前限制：

  • 私聊： 图片和文件附件通过 Teams 机器人文件 API 工作。
  • 频道/群组： 附件存储在 M365 存储（SharePoint/OneDrive）。Webhook 有效载荷仅包含 HTML 存根，而不是实际的文件字节。需要 Graph API 权限才能下载频道附件。

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

在群组聊天中发送文件

机器人可以使用内置的 FileConsentCard 流程在私聊中发送文件。但是，在群组聊天/频道中发送文件需要额外设置：

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

为什么群组聊天需要 SharePoint

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

设置

  1. 在 Entra ID（Azure AD）→ 应用注册中添加 Graph API 权限：

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

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

  3. 获取你的 SharePoint 站点 ID：

    # 通过 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"

  4. 配置 OpenClaw：

    {
  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 将任意 Adaptive Card JSON 发送到 Teams 用户或会话。

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

智能体工具：

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

目标格式

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

智能体工具示例：

{
  "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: 前缀，名称默认解析为群组/团队。按显示名称定位人员时始终使用 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:[email protected]）
  • 频道 ID = /channel/ 后的路径段（URL 解码）
  • 忽略 groupId 查询参数

私有频道

机器人在私有频道中支持有限：

功能标准频道私有频道
机器人安装是有限
实时消息（webhook）是可能不工作
RSC 权限是可能表现不同
@提及是如果机器人可访问
Graph API 历史是是（带权限）

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

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

故障排除

常见问题

  • 频道中的图片不显示： 缺少 Graph 权限或管理员同意。重新安装 Teams 应用并完全退出/重新打开 Teams。
  • 频道中没有回复： 默认需要提及；设置 channels.msteams.requireMention=false 或为每个团队/频道配置。
  • 版本不匹配（Teams 仍显示旧清单）： 移除并重新添加应用并完全退出 Teams 以刷新。
  • Webhook 401 未授权： 手动测试时预期会出现（没有 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 分钟让传播完成。
  • 上传出了问题: 改用 https://admin.teams.microsoft.com 上传，打开浏览器 DevTools（F12）→ 网络选项卡，并检查响应体以获取实际错误。
  • Sideload 失败： 尝试”上传应用到组织的应用目录”而不是”上传自定义应用” - 这通常可以绕过 sideload 限制。

RSC 权限不工作

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

参考资料