配置
channels.msteams 设置、代替认证密钥的环境变量,以及历史上下文规则。
环境变量¶
这些与认证相关的配置键可以通过环境变量设置,而不必放在 openclaw.json 中(其他配置键,如 groupPolicy 或 historyLimit,仅可通过配置文件设置):
| 环境变量 | 配置键 | 备注 |
|---|---|---|
MSTEAMS_APP_ID |
appId |
|
MSTEAMS_APP_PASSWORD |
appPassword |
|
MSTEAMS_TENANT_ID |
tenantId |
|
MSTEAMS_AUTH_TYPE |
authType |
"secret" 或 "federated" |
MSTEAMS_CERTIFICATE_PATH |
certificatePath |
联合认证 + 证书 |
MSTEAMS_CERTIFICATE_THUMBPRINT |
certificateThumbprint |
已接受,认证非必需 |
MSTEAMS_USE_MANAGED_IDENTITY |
useManagedIdentity |
联合认证 + 托管标识 |
MSTEAMS_MANAGED_IDENTITY_CLIENT_ID |
managedIdentityClientId |
仅适用于用户分配的托管标识 |
历史上下文¶
channels.msteams.historyLimit控制最近多少条频道/群组消息被包装进提示词。回退到messages.groupChat.historyLimit,然后默认为 50。设为0可禁用。- Graph 线程上下文会在最近的频道历史记录之外,添加父消息以及最早的最多 50 条回复。它排除触发消息,并将历史记录与发送者的命令文本分开保存,因此历史记录中被引用的命令不会执行。对于获取到的较长消息,会在提示词的每条消息限制范围内保留其开头和结尾。
- 线程和引用附件的上下文遵循
channels.msteams.contextVisibility,回退到channels.defaults.contextVisibility,再回退到all。使用allowlist可通过发送者允许列表(allowFrom/groupAllowFrom)过滤两者;或使用allowlist_quote过滤线程历史,同时允许引用上下文。 - DM 历史可通过
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:显式兼容性监听器。{ port, host? }选择一个端点,当省略host时保留之前的通配符绑定。省略或设为false时不打开单独的监听器。channels.msteams.dmPolicy:pairing | allowlist | open | disabled(默认pairing)。channels.msteams.allowFrom:DM 允许列表(建议使用 AAD 对象 ID)。稳定的 AAD 对象 ID 也可授权审批操作。设置期间,在 Graph 访问可用时,向导会将名称解析为 ID。channels.msteams.defaultTo:默认出站目标;稳定的 AAD 对象 ID 也可用于授权审批操作。channels.msteams.dangerouslyAllowNameMatching:破窗(break-glass)开关,用于重新启用可变的 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 证书文件路径(联合认证 + 证书认证)。channels.msteams.certificateThumbprint:证书指纹;已接受,认证非必需。channels.msteams.useManagedIdentity:启用托管标识认证(联合模式)。channels.msteams.managedIdentityClientId:用户分配的托管标识的客户端 ID。channels.msteams.sharePointSiteId:用于群聊/频道中文件上传的 SharePoint 站点 ID(参见 在群聊中发送文件)。channels.msteams.welcomeCard、channels.msteams.groupWelcomeCard、channels.msteams.promptStarters:首次 DM/群组联系时显示的欢迎自适应卡片(Adaptive Card),以及其建议的提示按钮。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。
Doctor 会为已启用 Teams 渠道的现有安装一次性固定 legacyWebhook: { port: 3978 },前提是它依赖隐式端口。需要存在先前运行的证据;全新安装不会打开单独的监听器。显式配置的 webhook.port 会通过 Doctor 的正常配置备份和写入流程迁移到 legacyWebhook.port。固定的兼容性监听器会转发到相同的 Gateway 路由和 JWT 验证。
已弃用的 TypeScript webhook.port 输入项在下一个 Plugin SDK 主要版本之前保持源码兼容。运行时配置使用 legacyWebhook;运行 openclaw doctor --fix 以迁移旧键。
在确认通过 Gateway 端口完成一次投递后,移除 channels.msteams.legacyWebhook 固定项以及任何旧的防火墙或 Compose 端口映射。保留 meta.migrations.webhookListeners,Doctor 会将其与固定项一起保存,以便后续运行不会重新创建它。有关包含的配置源和只读配置源,请参阅 Webhook 迁移。
显式 false 也会禁用监听器。Doctor 和启动过程会打印 Gateway 路由以及需要移除的设置。
对于仅通过环境变量提供 Teams 凭据的现有安装,Doctor 会保留端点,而不会在源配置中启用 Teams。如果这些凭据仅对 Gateway 服务可见,Doctor 会将该决定推迟到 Gateway 启动时。请继续使用 gateway run --ambient-channels 来激活它。单独的监听器设置不再启用 Teams;如需永久选择加入,请使用 enabled: true。Doctor 会为先前隐含激活的已编写监听器设置添加该标志,包括显式的 legacyWebhook: false。它不会为已记录迁移完成的生成固定项添加该标志。
自定义路径还会接受旧的 /api/messages 别名,并在该路由可用时保留其现有弃用警告。如果另一个插件拥有该别名,启动过程会记录冲突并继续提供已配置的路径。请将 Azure Bot 更新为已配置的路径。
Gateway 为检查保留 /health、/healthz、/ready、/readyz、/startup 和 /startupz,包括带查询字符串的 URL。如果你以前的 Teams 回调使用其中某个路径,请将 webhook.path 设置为 /api/messages,并更新 Azure Bot 或代理上游以匹配。Doctor 会报告此冲突。兼容性监听器会保持旧端点可用;当未配置显式旧版监听器时,启动过程会拒绝不可用的 Gateway 路由。在移除该监听器的固定项之前,请验证替换项。
/api/channels 下的路径在主监听器上需要 Gateway 身份验证,包括编码形式。Teams 回调使用 Azure JWT 进行身份验证,因此请改用 /api/messages。Doctor 和启动过程会报告相同的回调更改操作;兼容性监听器会继续提供旧路径,直到该切换完成。
Express 参数、通配符和大括号模式在旧版端口上继续可用。Gateway 路由注册使用字面路径。在禁用用于某个模式的旧版监听器之前,请将现有 webhook.path 更改为 /api/messages,并更新 Azure Bot 或你的代理。Doctor 和启动过程会识别这些模式;如果没有显式旧版监听器,启动过程会报告所需更改,而不是静默丢弃回调。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw