通过 Azure Bot 注册和 Teams CLI，在 5-10 分钟内将 OpenClaw 接入 Microsoft Teams。支持文本、私信附件、群聊/频道消息（需 @提及）以及 Adaptive Cards。群聊默认被阻止，频道图片需要 Graph 权限。快速配置命令：teams app create 完成 Bot 注册、清单创建和凭证生成。群聊/频道文件发送需 sharePointSiteId 和 Graph 权限。

OpenClaw 接入 Microsoft Teams 渠道配置指南

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

捆绑插件

Microsoft Teams 作为捆绑插件随当前 OpenClaw 发布版提供，正常打包的构建无需单独安装。

若使用旧版本或自定义构建（不包含 Teams），可手动安装 npm 包：

bash

openclaw plugins install @openclaw/msteams

使用裸包以跟随当前官方发布标签。仅在需要可复现安装时，才锁定精确版本。

从本地代码仓库运行时：

bash

openclaw plugins install ./path/to/local/msteams-plugin

详情：插件

快速安装

@microsoft/teams.cli 可用一条命令处理 Bot 注册、清单创建和凭证生成。

1. 安装并登录

bash

npm install -g @microsoft/teams.cli@preview
teams login
teams status   # 验证已登录，查看租户信息

INFO

Teams CLI 目前处于预览阶段，命令和参数可能随版本变化。

2. 启动隧道（Teams 无法访问 localhost）

安装并验证 devtunnel CLI（入门指南见 Azure Dev Tunnels）。

bash

# 一次性设置（跨会话保持固定 URL）：
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# 每次开发会话：
devtunnel host my-openclaw-bot
# 你的端点：https://<tunnel-id>.devtunnels.ms/api/messages

INFO

--allow-anonymous 是必须的，因为 Teams 无法认证 devtunnels。每个入站 Bot 请求仍由 Teams SDK 自动校验。

替代方案：ngrok http 3978 或 tailscale funnel 3978（但每次会话可能变更 URL）。

3. 创建应用

bash

teams app create \
  --name "OpenClaw" \
  --endpoint "https://<your-tunnel-url>/api/messages"

该命令会：

创建 Entra ID（Azure AD）应用
生成客户端密钥
构建并上传 Teams 应用清单（含图标）
注册 Bot（默认由 Teams 管理，无需 Azure 订阅）

输出将显示 CLIENT_ID、CLIENT_SECRET、TENANT_ID 和 Teams App ID——记下这些值以用于下一步。它还会提供直接在 Teams 中安装应用的选项。

4. 配置 OpenClaw

使用输出中的凭据配置：

json5

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<CLIENT_ID>",
      appPassword: "<CLIENT_SECRET>",
      tenantId: "<TENANT_ID>",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

或直接使用环境变量：MSTEAMS_APP_ID、MSTEAMS_APP_PASSWORD、MSTEAMS_TENANT_ID。

5. 在 Teams 中安装应用

teams app create 会提示安装应用——选择 "Install in Teams"。若跳过，稍后可获取安装链接：

bash

teams app get <teamsAppId> --install-link

6. 验证一切正常

bash

teams app doctor <teamsAppId>

该命令会运行诊断，检查 Bot 注册、AAD 应用配置、清单有效性和 SSO 设置。

生产环境建议使用联合身份认证（证书或托管身份）替代客户端密钥。

INFO

群聊默认被阻止（channels.msteams.groupPolicy: "allowlist"）。要允许群聊回复，设置 channels.msteams.groupAllowFrom，或使用 groupPolicy: "open" 允许任何成员（需 @提及）。

目标

通过 Teams 私信、群聊或频道与 OpenClaw 对话。
保持路由确定性：回复始终回到来源渠道。
默认采用安全频道行为（除非另行配置，否则需要 @提及）。

配置写入

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

禁用：

json5

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

访问控制（私信 + 群组）

私信访问

默认：channels.msteams.dmPolicy = "pairing"。未知发送者被忽略，直到批准。
channels.msteams.allowFrom 应使用稳定的 AAD 对象 ID 或静态发送者访问组，如 accessGroup:core-team。
不要依赖 UPN/显示名称进行允许列表匹配——它们可能变化。OpenClaw 默认禁用直接名称匹配；需显式启用 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: ["00000000-0000-0000-0000-000000000000", "accessGroup:core-team"],
    },
  },
}

Teams + 频道允许列表

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

示例：

json5

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

手动配置（不使用 Teams CLI）

若无法使用 Teams CLI，可通过 Azure Portal 手动设置 Bot。

工作原理

确保 Microsoft Teams 插件可用（当前版本已捆绑）。
创建 Azure Bot（App ID + 密钥 + 租户 ID）。
构建引用该 Bot 并包含以下 RSC 权限的 Teams 应用包。
将 Teams 应用上传/安装到团队（或个人范围用于私信）。
在 ~/.openclaw/openclaw.json（或环境变量）中配置 msteams 并启动网关。
网关默认监听 /api/messages 上的 Bot Framework Webhook 流量。

步骤 1：创建 Azure Bot

前往创建 Azure Bot

填写 Basics 标签页：

字段	值
Bot handle	Bot 名称，例如 `openclaw-msteams`（必须唯一）
Subscription	选择 Azure 订阅
Resource group	新建或使用现有
Pricing tier	开发/测试选 Free
Type of App	Single Tenant（推荐）
Creation type	Create new Microsoft App ID

WARNING

2025-07-31 后已弃用多租户 Bot。新 Bot 请使用 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
接受服务条款

步骤 5：构建 Teams 应用清单

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

步骤 6：配置 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。

步骤 7：运行网关

当插件可用且 msteams 配置存在凭据时，Teams 渠道会自动启动。 :::

联合身份认证（证书 + 托管身份）

2026.4.11 新增

生产环境支持联合身份认证，作为客户端密钥的更安全替代方案。提供两种方式：

选项 A：基于证书的认证

使用在 Entra ID 应用注册中注册的 PEM 证书。

配置：

生成或获取证书（PEM 格式，包含私钥）。
在 Entra ID → App Registration → Certificates & secrets → Certificates → 上传公钥证书。

配置：

json5

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      certificatePath: "/path/to/cert.pem",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

环境变量：

MSTEAMS_AUTH_TYPE=federated
MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem

选项 B：Azure 托管身份

使用 Azure 托管身份实现无密码认证，适用于 Azure AKS、App Service、Azure VM 等环境。

工作原理：

Bot Pod/VM 拥有托管身份（系统分配或用户分配）。
联合身份凭证将托管身份链接到 Entra ID 应用注册。
运行时，OpenClaw 使用 @azure/identity 从 Azure IMDS 端点（169.254.169.254）获取令牌。
令牌传递给 Teams SDK 用于 Bot 认证。

前置条件：

已启用托管身份的 Azure 基础设施（AKS 工作负载身份、App Service、VM）
在 Entra ID 应用注册上创建的联合身份凭证
Pod/VM 对 IMDS（169.254.169.254:80）的网络访问

配置（系统分配托管身份）：

json5

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      useManagedIdentity: true,
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

配置（用户分配托管身份）：

json5

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      useManagedIdentity: true,
      managedIdentityClientId: "<MI_CLIENT_ID>",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

环境变量：

MSTEAMS_AUTH_TYPE=federated
MSTEAMS_USE_MANAGED_IDENTITY=true
MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>（仅用户分配）

AKS 工作负载身份配置

在 AKS 集群上启用工作负载身份。

在 Entra ID 应用注册上创建联合身份凭证：

bash

az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{
  "name": "my-bot-workload-identity",
  "issuer": "<AKS_OIDC_ISSUER_URL>",
  "subject": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>",
  "audiences": ["api://AzureADTokenExchange"]
}'

为 Kubernetes 服务账户添加注解：

yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-bot-sa
  annotations:
    azure.workload.identity/client-id: "<APP_CLIENT_ID>"

为 Pod 添加标签以注入工作负载身份：

yaml

metadata:
  labels:
    azure.workload.identity/use: "true"

确保对 IMDS 的网络访问：若使用 NetworkPolicy，添加出站规则允许流量到 169.254.169.254/32 的 80 端口。

认证方式对比

方式	配置	优势	劣势
客户端密钥	`appPassword`	配置简单	密钥轮换要求，安全性较低
证书	`authType: "federated"` + `certificatePath`	网络不共享密钥	证书管理开销
托管身份	`authType: "federated"` + `useManagedIdentity`	无密码化，无需管理密钥	需要 Azure 基础设施

默认行为： 未设置 authType 时，OpenClaw 默认使用客户端密钥认证。现有配置无需修改。

本地开发（隧道）

Teams 无法访问 localhost。使用持久化的开发隧道，确保 URL 跨会话保持一致：

bash

# 一次性设置：
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# 每次开发会话：
devtunnel host my-openclaw-bot

替代方案：ngrok http 3978 或 tailscale funnel 3978（URL 可能每次会话变化）。

若隧道 URL 变更，更新端点：

bash

teams app update <teamsAppId> --endpoint "https://<new-url>/api/messages"

测试 Bot

运行诊断：

bash

teams app doctor <teamsAppId>

一次检查 Bot 注册、AAD 应用、清单和 SSO 配置。

发送测试消息：

安装 Teams 应用（使用 teams app get <id> --install-link 的安装链接）
在 Teams 中找到 Bot 并发送私信
检查网关日志中的入站活动

环境变量

所有配置键可通过环境变量设置：

MSTEAMS_APP_ID
MSTEAMS_APP_PASSWORD
MSTEAMS_TENANT_ID
MSTEAMS_AUTH_TYPE（可选："secret" 或 "federated"）
MSTEAMS_CERTIFICATE_PATH（联合 + 证书）
MSTEAMS_CERTIFICATE_THUMBPRINT（可选，认证不需要）
MSTEAMS_USE_MANAGED_IDENTITY（联合 + 托管身份）
MSTEAMS_MANAGED_IDENTITY_CLIENT_ID（仅用户分配 MI）

成员信息操作

OpenClaw 暴露了一个基于 Graph 的 member-info 操作，智能体和自动化可解析频道成员详情（显示名称、邮件地址、角色）。

要求：

Member.Read.Group RSC 权限（已在推荐清单中）
跨团队查询：User.Read.All Graph 应用权限 + 管理员同意

该操作由 channels.msteams.actions.memberInfo 控制（默认：当 Graph 凭据可用时启用）。

历史上下文

channels.msteams.historyLimit 控制包含在提示中的最近频道/群组消息数量。
回退到 messages.groupChat.historyLimit，设置 0 禁用（默认 50）。
获取的线程历史按发送者允许列表（allowFrom / groupAllowFrom）过滤，因此线程上下文填充只包含允许发送者的消息。
引用的附件上下文（由 Teams 回复 HTML 派生的 ReplyTo*）当前原样传递。简而言之，允许列表控制谁可以触发智能体；目前只过滤特定补充上下文路径。
私信历史可用 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 CLI 添加 RSC 权限：

bash

teams app rsc add <teamsAppId> ChannelMessage.Read.Group --type Application

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

bash

# 下载、编辑并重新上传清单
teams app manifest download <teamsAppId> manifest.json
# 本地编辑 manifest.json...
teams app manifest upload manifest.json <teamsAppId>
# 若内容变更，版本会自动递增

更新后，在每个团队中重新安装应用以使新权限生效。完全退出并重新启动 Teams（不仅关闭窗口）以清除缓存的应用元数据。

手动更新清单（不使用 CLI）

使用新设置更新 manifest.json
增加 version 字段（例如 1.0.0 → 1.1.0）
重新打包 清单和图标（manifest.json、outline.png、color.png）
上传新 ZIP：
- Teams 管理中心： Teams 应用 → 管理应用 → 找到应用 → 上传新版本
- 侧载： 在 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 权限并授权管理员同意。

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

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

已知限制

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：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：每频道工具策略
channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender：每频道每发送者工具策略
toolsBySender 键应使用明确前缀：channel:、id:、e164:、username:、name:（旧版无前缀键仍映射到 id:）
channels.msteams.actions.memberInfo：启用/禁用基于 Graph 的成员信息操作（默认：Graph 凭据可用时启用）
channels.msteams.authType：认证类型 - "secret"（默认）或 "federated"
channels.msteams.certificatePath：PEM 证书文件路径（联合 + 证书认证）
channels.msteams.certificateThumbprint：证书指纹（可选，认证不需要）
channels.msteams.useManagedIdentity：启用托管身份认证（联合模式）
channels.msteams.managedIdentityClientId：用户分配托管身份的客户端 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）	消息线性流动，更像 Slack	`top-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",
            },
          },
        },
      },
    },
  },
}

解析优先级

Bot 回复频道消息时，replyStyle 从最具体的覆盖向下解析。第一个非 undefined 值生效：

每频道 — channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
每团队 — channels.msteams.teams.<teamId>.replyStyle
全局 — channels.msteams.replyStyle
隐式默认 — 从 requireMention 衍生：
- requireMention: true → thread
- requireMention: false → top-level

若全局设置 requireMention: false 但未显式设置 replyStyle，帖子样式频道中的 @提及将显示为顶层帖子。在全局、团队或频道级别锁定 replyStyle: "thread" 以避免意外。

线程上下文保留

当 replyStyle: "thread" 生效且 Bot 在频道线程中被 @提及，OpenClaw 会将原始线程根重新附加到出站会话引用（19:…@thread.tacv2;messageid=<root>），使回复落在同一线程内。这适用于实时（轮次内）发送和 Bot Framework 轮次上下文过期后的主动发送。

线程根取自存储的会话引用上的 threadId。早于 threadId 的老引用回退到 activityId，因此现有部署无需重新播种即可继续工作。

当 replyStyle: "top-level" 生效时，频道线程的入站会以新的顶层帖子回应——不附加线程后缀。这是线程样式频道的正确行为；若看到期望线程回复却出现顶层帖子，说明 replyStyle 对该频道设置不正确。

附件与图片

当前限制：

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

无 Graph 权限时，包含图片的频道消息以纯文本接收（Bot 无法访问图片内容）。默认情况下，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 站点并创建共享链接。

设置

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

获取 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"

配置 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> ...
投票由网关记录在 ~/.openclaw/msteams-polls.json 中。
网关必须保持在线才能记录投票。
投票目前不会自动发布结果摘要（查看存储文件即可）。

表示卡片

使用 message 工具、CLI 或常规回复投递，发送语义表示负载到 Teams 用户或会话。OpenClaw 从通用表示合约将其渲染为 Teams Adaptive Cards。

presentation 参数接受语义块。提供 presentation 时，消息文本可选。按钮渲染为 Adaptive Card 提交或 URL 操作。选择菜单在 Teams 渲染器中尚不原生，因此 OpenClaw 在投递前降级为可读文本。

智能体工具：

json5

{
  action: "send",
  channel: "msteams",
  target: "user:<id>",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello!" }],
  },
}

CLI：

bash

openclaw message send --channel msteams \
  --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello!"}]}'

目标格式

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"

# 向会话发送表示卡片
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}'

智能体工具示例：

json5

{
  action: "send",
  channel: "msteams",
  target: "user:John Smith",
  message: "Hello!",
}

json5

{
  action: "send",
  channel: "msteams",
  target: "conversation:19:abc...@thread.tacv2",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello" }],
  },
}

INFO

无 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=...
                                    └────────────────────────────┘
                                    Team 会话 ID（URL 解码后使用）

频道 URL：

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      频道 ID（URL 解码后使用）

配置说明：

团队键 = /team/ 后的路径段（URL 解码后，如 19:Bk4j...@thread.tacv2；旧租户可能显示 @thread.skype，同样有效）
频道键 = /channel/ 后的路径段（URL 解码后）
忽略 groupId 查询参数。它是 Microsoft Entra 组 ID，而非 Bot Framework 会话 ID。

私有频道

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

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

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

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

故障排查

常见问题

频道中图片不显示： 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 标签，查看响应体中的实际错误。
侧载失败： 尝试"将应用上传到你的组织应用目录"而非"上传自定义应用"——通常可绕过侧载限制。

RSC 权限不工作

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

常见问题

配置了 groupAllowFrom，但频道还是不响应，是哪里出错了？

检查以下几点：① groupPolicy 是否设为 allowlist 或 open；② groupAllowFrom 中填写的是稳定的 AAD 对象 ID，不是 UPN 或显示名称；③ Teams 应用是否已在目标团队中安装；④ 是否已 @提及机器人（requireMention 默认为 true）。

Bot 在 Teams 频道里收到了消息，但图片内容看不到，怎么解决？

频道附件存储在 SharePoint/OneDrive，Webhook 载荷只有 HTML 存根。需要在 Entra ID 的 App Registration 中添加 Graph API 应用权限（ChannelMessage.Read.All），授予管理员同意，然后重新上传应用清单并在每个团队重新安装，最后完全退出并重启 Teams 清除缓存。

更新了 Teams 应用清单，新的 RSC 权限还是没生效，怎么处理？

必须同时做三件事：① 增加清单 version 字段（如 1.0.0 → 1.1.0）；② 重新打包并上传 ZIP；③ 在每个使用该应用的团队中重新安装应用。仅上传新版本不会自动刷新已安装团队的权限。更新后还需要完全退出并重新启动 Teams 客户端。

参考链接

创建 Azure Bot - Azure Bot 配置指南
Teams 开发者门户 - 创建/管理 Teams 应用
Teams 应用清单 Schema
使用 RSC 接收频道消息
RSC 权限参考
Teams Bot 文件处理（频道/群组需要 Graph）
主动消息
@microsoft/teams.cli - Teams 命令行管理 Bot

OpenClaw 接入 Microsoft Teams 渠道配置指南 ​

捆绑插件 ​

快速安装 ​

目标 ​

配置写入 ​

访问控制（私信 + 群组） ​

工作原理 ​

步骤 1：创建 Azure Bot ​

步骤 2：获取凭据 ​

步骤 3：配置消息端点 ​

步骤 4：启用 Teams 频道 ​

步骤 5：构建 Teams 应用清单 ​

步骤 6：配置 OpenClaw ​

步骤 7：运行网关 ​

联合身份认证（证书 + 托管身份） ​

选项 A：基于证书的认证 ​

选项 B：Azure 托管身份 ​

AKS 工作负载身份配置 ​

认证方式对比 ​

本地开发（隧道） ​

测试 Bot ​

环境变量 ​

成员信息操作 ​

历史上下文 ​

当前 Teams RSC 权限（清单） ​

Teams 清单示例（已脱敏） ​

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

更新已安装的应用 ​

能力：仅 RSC vs Graph ​

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

使用 Teams RSC + Microsoft Graph 应用权限 ​

RSC vs Graph API 对比 ​

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

已知限制 ​

Webhook 超时 ​

格式限制 ​

配置 ​

路由与会话 ​

回复样式：线程 vs 帖子 ​

解析优先级 ​

线程上下文保留 ​

附件与图片 ​

在群聊中发送文件 ​

为何群聊需要 SharePoint ​

设置 ​

共享行为 ​

回退行为 ​

文件存储位置 ​

投票（Adaptive Cards） ​

表示卡片 ​

目标格式 ​

主动消息 ​

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

私有频道 ​

故障排查 ​

常见问题 ​

清单上传错误 ​

RSC 权限不工作 ​

常见问题 ​

配置了 groupAllowFrom，但频道还是不响应，是哪里出错了？ ​

Bot 在 Teams 频道里收到了消息，但图片内容看不到，怎么解决？ ​

更新了 Teams 应用清单，新的 RSC 权限还是没生效，怎么处理？ ​

参考链接 ​

相关文档 ​

OpenClaw 接入 Microsoft Teams 渠道配置指南

捆绑插件

快速安装

目标

配置写入

访问控制（私信 + 群组）

工作原理

步骤 1：创建 Azure Bot

步骤 2：获取凭据

步骤 3：配置消息端点

步骤 4：启用 Teams 频道

步骤 5：构建 Teams 应用清单

步骤 6：配置 OpenClaw

步骤 7：运行网关

联合身份认证（证书 + 托管身份）

选项 A：基于证书的认证

选项 B：Azure 托管身份

AKS 工作负载身份配置

认证方式对比

本地开发（隧道）

测试 Bot

环境变量

成员信息操作

历史上下文

当前 Teams RSC 权限（清单）

Teams 清单示例（已脱敏）

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

更新已安装的应用

能力：仅 RSC vs Graph

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

使用 Teams RSC + Microsoft Graph 应用权限

RSC vs Graph API 对比

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

已知限制

Webhook 超时

格式限制

配置

路由与会话

回复样式：线程 vs 帖子

解析优先级

线程上下文保留

附件与图片

在群聊中发送文件

为何群聊需要 SharePoint

设置

共享行为

回退行为

文件存储位置

投票（Adaptive Cards）

表示卡片

目标格式

主动消息

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

私有频道

故障排查

常见问题

清单上传错误

RSC 权限不工作

常见问题

配置了 groupAllowFrom，但频道还是不响应，是哪里出错了？

Bot 在 Teams 频道里收到了消息，但图片内容看不到，怎么解决？

更新了 Teams 应用清单，新的 RSC 权限还是没生效，怎么处理？

参考链接

相关文档