配置

The channels.msteams 设置、用于替代认证密钥的环境变量，以及历史上下文规则。

环境变量¶

这些与认证相关的配置键可以通过环境变量设置，而不是通过 openclaw.json（其他配置键，例如 groupPolicy 或 historyLimit，仅限配置）：

历史上下文¶

• channels.msteams.historyLimit 控制将多少条最近的频道/群组消息包装进 Prompt。回退到 messages.groupChat.historyLimit，然后默认为 50。设置 0 以禁用。
• Graph 线程上下文会添加父消息以及最多最旧的 50 条回复，同时包含最近的频道历史。它排除触发消息，并将历史与发送者的命令文本分开，因此历史中引用的命令不会执行。获取的长消息会在 Prompt 的每条消息限制内保留开头和结尾。
• 线程和引用附件上下文遵循 channels.msteams.contextVisibility，回退到 channels.defaults.contextVisibility，然后为 all。使用 allowlist 通过发送者允许列表（allowFrom / groupAllowFrom）同时过滤两者，或使用 allowlist_quote 过滤线程历史，同时允许引用上下文。
• 可以使用 channels.msteams.dmHistoryLimit（用户轮次）限制私信历史。按用户覆盖：channels.msteams.dms["<user_id>"].historyLimit。

配置¶

关键设置（参见 /gateway/configuration 了解共享频道模式）：

• channels.msteams.enabled：启用/禁用该频道。
• channels.msteams.appId、channels.msteams.appPassword、channels.msteams.tenantId：机器人凭据。
• channels.msteams.cloud：Teams SDK 云环境（Public、USGov、USGovDoD 或 China；默认 Public）。为 USGov/DoD SDK 云设置 serviceUrl；China 使用 SDK 预设和已存储的 Azure China Bot Framework 会话引用，在 Azure China Graph 路由发布之前，禁用基于 Graph 的辅助功能。
• channels.msteams.serviceUrl：SDK 主动操作的 Bot Connector 服务 URL 边界。公共云使用 SDK 默认值；为 GCC（https://smba.infra.gcc.teams.microsoft.com/teams）、GCC High 或 DoD 设置。当已存储的会话引用来自由 21Vianet 运营的 Teams 时，China 接受 Azure China Bot Framework 频道主机。
• channels.msteams.webhook.path：Gateway HTTP 路由（省略或为空时使用 /api/messages），在 gateway.port（默认 18789）上提供。
• channels.msteams.legacyWebhook：兼容性监听器。省略时保留端口 3978 并使用先前的通配符绑定；{ port, host? } 选择端点；false 关闭旧监听器。
• channels.msteams.dmPolicy：pairing | allowlist | open | disabled（默认 pairing）。
• channels.msteams.allowFrom：私信允许列表（建议使用 AAD 对象 ID）。稳定的 AAD 对象 ID 还可授权审批操作。在设置期间，如果可用 Graph 访问，向导会将名称解析为 ID。
• channels.msteams.defaultTo：默认出站目标；稳定的 AAD 对象 ID 也可授权审批操作。
• channels.msteams.dangerouslyAllowNameMatching：紧急开关，用于重新启用可变的 UPN/显示名称匹配以及直接的团队/频道名称路由。
• channels.msteams.textChunkLimit：出站文本块大小（以字符计）（默认 4000，并且无论配置值多高，硬性上限均为 4000）。
• channels.msteams.streaming.chunkMode：length（默认）或 newline，在按长度分块之前按空行（段落边界）拆分。
• channels.msteams.mediaAllowHosts：入站附件主机允许列表（默认为 Microsoft/Teams 域名：Graph、SharePoint/OneDrive、Teams CDN、Bot Framework、Azure Media Services）。
• channels.msteams.mediaAuthAllowHosts：在媒体重试时附加 Authorization 头的允许列表（默认为 Graph + Bot Framework 主机）。
• channels.msteams.graphMediaFallback：当频道/群组 HTML 省略文件标记时，选择加入 Graph 消息查找（默认 false；参见 频道/群组文件恢复）。
• channels.msteams.mediaMaxMb：按频道媒体大小限制覆盖（以 MB 计）。未设置时回退到 agents.defaults.mediaMaxMb。
• channels.msteams.requireMention：在频道/群组中要求 @提及（默认 true）。
• channels.msteams.requireMentionInBotThreads：覆盖以本机器人跟踪消息为根的频道线程中的提及门控。省略时保留当前行为；参见 机器人创建的线程。
• channels.msteams.replyStyle：thread | top-level（参见 回复样式）。
• channels.msteams.teams.<teamId>.replyStyle：按团队覆盖。
• channels.msteams.teams.<teamId>.requireMention：按团队覆盖。
• channels.msteams.teams.<teamId>.requireMentionInBotThreads：按团队机器人线程覆盖。
• 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>.requireMentionInBotThreads：按频道机器人线程覆盖。
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools：按频道工具策略覆盖（allow/deny/alsoAllow）。
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender：按频道按发送者工具策略覆盖（支持 "*" 通配符）。
• toolsBySender 键使用显式前缀：channel:、id:、e164:、username:、name:。运行 openclaw doctor --fix 将已弃用的无前缀键迁移到 id: 条目。
• channels.msteams.authType：认证类型 - "secret"（默认）或 "federated"。
• channels.msteams.certificatePath：PEM 证书文件路径（federated + 证书认证）。
• channels.msteams.certificateThumbprint：证书指纹；可接受，认证不要求。
• channels.msteams.useManagedIdentity：启用托管标识认证（federated 模式）。
• channels.msteams.managedIdentityClientId：用户分配托管标识的客户端 ID。
• channels.msteams.sharePointSiteId：群组聊天/频道中文件上传的 SharePoint 站点 ID（参见 在群组聊天中发送文件）。
• channels.msteams.welcomeCard、channels.msteams.groupWelcomeCard、channels.msteams.promptStarters：首次私信/群组联系时显示的欢迎 Adaptive Card，以及其建议的 Prompt 按钮。
• channels.msteams.responsePrefix：添加到出站回复前面的文本。
• channels.msteams.feedbackEnabled（默认 true）、channels.msteams.feedbackReflection（默认 true）、channels.msteams.feedbackReflectionCooldownMs：回复上的点赞/点踩反馈，以及负面反馈反思跟进。
• channels.msteams.sso、channels.msteams.delegatedAuth：用于 SSO 支持流程的 Bot Framework OAuth 连接和委托 Graph 范围；sso.enabled: true 需要 sso.connectionName。

迁移现有 webhook 端点¶

Teams webhook 现在共享 Gateway HTTP 监听器。Teams SDK 仍会验证 Azure JWT 签名；调用方无需提供 Gateway Token。请保留 Azure Bot 中的公共 HTTPS 消息端点，并将其反向代理上游更改为 Gateway 端口 18789（或你的 gateway.port），同时保留 /api/messages 或你配置的 webhook.path。如果你直接暴露端口，请将 Azure Bot 的消息端点更新为能够到达此 Gateway 路由的公共 HTTPS URL。

在未写入监听器设置的情况下，现有安装仍会在端口 3978 上继续接收回调。显式配置的 webhook.port 会通过 Doctor 的常规配置备份和写入流程迁移到 legacyWebhook.port。隐式和显式兼容监听器都会转发到同一个 Gateway 路由和 JWT 验证；OpenClaw 不会静默移除任一监听器。

已弃用的 TypeScript webhook.port 输入项在下一个 Plugin SDK 主要版本之前保持源码兼容。运行时配置使用 legacyWebhook；运行 openclaw doctor --fix 以迁移旧键。

在确认通过 Gateway 端口完成一次投递后，设置 channels.msteams.legacyWebhook: false，并移除任何旧的防火墙或 Compose 端口映射。删除该设置会恢复默认兼容监听器，因此请使用 false 来关闭它。没有计划中的截止日期；退役此兼容行为需要单独的变更。Doctor 和启动过程会打印 Gateway 路由以及禁用旧监听器的确切设置。

自定义路径在该路由可用时，也会接受旧的 /api/messages 别名，并带有其现有的弃用警告。如果另一个插件拥有该别名，启动过程会记录冲突并继续提供已配置的路径。请将 Azure Bot 更新为已配置的路径。

Gateway 为探针保留 /health、/healthz、/ready、/readyz、/startup 和 /startupz，包括带查询字符串的 URL。如果你以前的 Teams 回调使用了这些路径之一，请将 webhook.path 设置为 /api/messages，并更新 Azure Bot 或代理上游以匹配。Doctor 会报告此冲突。兼容监听器会保持旧端点可用；只有当 legacyWebhook 为 false 时，启动过程才会拒绝不可用的 Gateway 路由。在禁用该监听器之前，请先验证替代方案。

/api/channels 下的路径在主监听器上需要 Gateway 身份验证，包括编码后的拼写。Teams 回调使用 Azure JWT 进行身份验证，因此请改用 /api/messages。Doctor 和启动过程会报告相同的回调变更操作；兼容监听器会继续提供旧路径，直到该切换完成。

Express 参数、通配符和大括号模式在旧端口上继续可用。Gateway 路由注册使用字面路径。在禁用某个模式的旧监听器之前，请将现有 webhook.path 更改为 /api/messages，并更新 Azure Bot 或你的代理。Doctor 和启动过程会识别这些模式；当 legacyWebhook: false 时，启动过程会报告所需变更，而不是静默丢弃回调。