设置
安装插件,注册机器人和 Teams 应用,将 Teams 指向一个可访问的端点,并验证结果。
捆绑插件¶
Microsoft Teams 在当前 OpenClaw 版本中作为捆绑插件提供;在常规打包构建中无需单独安装。
在较旧的构建或排除了捆绑 Teams 的自定义安装中,直接安装 npm 包:
使用裸包以跟随当前官方发布标签。仅在需要可复现安装时固定到确切版本。
本地检出(从 git 仓库运行):
详情:插件
快速设置¶
@microsoft/teams.cli 通过一条命令处理机器人注册、清单创建和凭据生成。
1. 安装并登录
npm install -g @microsoft/teams.cli@preview
teams login
teams status # verify you're logged in and see your tenant info
Note
Teams CLI 以 @preview dist-tag 发布(见上文安装命令)。命令和标志可能在不同版本之间变化。
2. 启动隧道(Teams 无法访问 localhost)
如有需要,安装并认证 devtunnel CLI(入门指南)。
# One-time setup (persistent URL across sessions):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 18789 --protocol auto
# Each dev session:
devtunnel host my-openclaw-bot
# Your endpoint: https://<tunnel-id>.devtunnels.ms/api/messages
Note
需要 --allow-anonymous,因为 Teams 无法对 devtunnels 进行身份验证。每个传入的机器人请求仍会由 Teams SDK 验证。
替代方案:ngrok http 18789 或 tailscale funnel 18789(URL 可能每次会话都会变化)。如果不同,请使用你配置的 Gateway 端口。配置反向代理时,仅暴露所需的 webhook 路径。
新安装仅使用 Gateway 端口。Doctor 会通过在现有安装中设置一次性 channels.msteams.legacyWebhook 固定项来保留端口 3978。
在迁移回调并通过 Gateway 端口验证投递后,移除该固定项以关闭旧端口。
3. 创建应用
这会创建一个 Entra ID(Azure AD)应用,生成客户端密钥,构建并上传 Teams 应用清单(包含图标),并注册一个由 Teams 管理的机器人(无需 Azure 订阅)。输出包括 CLIENT_ID、CLIENT_SECRET、TENANT_ID 和一个 Teams App ID;它还会提供直接在 Teams 中安装该应用的选项。
4. 配置 OpenClaw,使用输出中的凭据:
{
channels: {
msteams: {
enabled: true,
appId: "<CLIENT_ID>",
appPassword: "<CLIENT_SECRET>",
tenantId: "<TENANT_ID>",
webhook: { path: "/api/messages" },
},
},
}
或直接使用环境变量:MSTEAMS_APP_ID、MSTEAMS_APP_PASSWORD、MSTEAMS_TENANT_ID。
5. 在 Teams 中安装应用
teams app create 会提示你安装应用;选择“在 Teams 中安装”。之后要获取安装链接:
6. 验证一切正常
对机器人注册、AAD 应用配置、清单有效性和 SSO 设置运行诊断。
对于生产环境,请考虑使用联合身份验证(证书或托管标识)而不是客户端密钥。
Note
默认情况下,群聊会被阻止(channels.msteams.groupPolicy: "allowlist")。若要允许群聊回复,请设置 channels.msteams.groupAllowFrom,或使用 groupPolicy: "open" 允许任意成员(需提及)。
目标¶
- 通过 Teams 私信、群聊或频道与 OpenClaw 对话。
- 保持路由确定性:回复始终返回其到达的频道。
- 默认采用安全的频道行为(除非另行配置,否则需要提及)。
手动设置(不使用 Teams CLI)
### 工作原理 {#how-it-works} 1. 确保 Microsoft Teams 插件可用(当前版本中已捆绑)。 2. 创建一个 **Azure Bot**(App ID + 密钥 + 租户 ID)。 3. 构建一个引用该机器人的 **Teams 应用包**,包括 [RSC 权限](manifest-and-permissions.md#current-teams-rsc-permissions-manifest)。 4. 将 Teams 应用上传/安装到团队中(或用于私信的个人范围)。 5. 在 `~/.openclaw/openclaw.json`(或环境变量)中配置 `msteams`,并启动网关。 6. Gateway 在 `gateway.port`(默认 `18789`)的 `/api/messages` 上提供 Bot Framework webhook 流量,并使用 Teams SDK JWT 身份验证。 ### 步骤 1:创建 Azure Bot {#step-1-create-azure-bot} 1. 前往 [创建 Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) 2. 填写 **基本信息** 选项卡: | 字段 | 值 | | ------------------ | -------------------------------------------------------- | | **机器人句柄** | 你的机器人名称,例如 `openclaw-msteams`(必须唯一) | | **订阅** | 选择你的 Azure 订阅 | | **资源组** | 新建或使用现有资源组 | | **定价层** | 开发/测试使用 **免费** | | **应用类型** | **单租户**(推荐;见下文说明) | | **创建类型** | **创建新的 Microsoft App ID** | !!! warning 自 2025-07-31 之后,创建新的多租户机器人已弃用。新机器人请使用 **单租户**。 3. 点击 **审查 + 创建**,然后点击 **创建**(约 1-2 分钟)。 ### 步骤 2:获取凭据 {#step-2-get-credentials} 1. Azure Bot 资源 → **配置** → 复制 **Microsoft App ID**(你的 `appId`)。 2. **管理密码** → App Registration → **证书和密钥** → **新客户端密钥** → 复制 **值**(你的 `appPassword`)。 3. **概览** → 复制 **目录(租户)ID**(你的 `tenantId`)。 ### 步骤 3:配置消息端点 {#step-3-configure-messaging-endpoint} 1. Azure Bot → **配置**。 2. 设置 **消息端点**: - 生产环境:`https://your-domain.com/api/messages` - 本地开发:使用隧道(参见 [本地开发](#local-development-tunneling)) ### 步骤 4:启用 Teams 渠道 {#step-4-enable-teams-channel} 1. Azure Bot → **渠道**。 2. 点击 **Microsoft Teams** → 配置 → 保存。 3. 接受服务条款。 ### 步骤 5:构建 Teams 应用清单 {#step-5-build-teams-app-manifest} - 包含一个 `bot` 条目,其中 `botId =本地开发(隧道)¶
Teams 无法访问 localhost。请使用持久开发隧道,以便 URL 在多次会话之间保持稳定:
# One-time setup:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 18789 --protocol auto
# Each dev session:
devtunnel host my-openclaw-bot
替代方案:ngrok http 18789 或 tailscale funnel 18789(URL 可能每次会话都会变化)。如果配置的网关端口不同,请使用该端口。配置反向代理时,仅暴露所需的 webhook 路径。
如果隧道 URL 发生变化,请更新端点:
测试机器人¶
运行诊断:
一次性检查机器人注册、AAD 应用、清单和 SSO 配置。
发送测试消息:
- 安装 Teams 应用(安装链接来自
teams app get <id> --install-link)。 - 在 Teams 中找到该机器人并发送私信。
- 检查网关日志中的传入活动。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw