Microsoft Teams 设置
将 KOPI AI AGENT 作为机器人接入 Microsoft Teams。与 Slack 的 Socket Mode 不同,Teams 通过调用公开的 HTTPS webhook 来传递消息,因此你的实例需要一个可公开访问的端点——开发环境下使用 dev tunnel(本地开发),生产环境下使用真实域名。
需要从 Microsoft Graph 事件获取会议摘要,而不是普通的机器人对话?请使用专门的设置页面:Teams Meetings。
运行
kopi gateway setup并选择 Microsoft Teams,即可获得交互式引导。
机器人的响应方式
| 场景 | 行为 |
|---|---|
| 私人聊天(DM) | 机器人回复每条消息,无需 @提及。 |
| 群聊 | 机器人仅在被 @提及时回复。 |
| 频道 | 机器人仅在被 @提及时回复。 |
Teams 会将 @提及作为带有 <at>BotName</at> 标签的普通消息发送,Kopi Agent 会在处理前自动去除这些标签。
对于源码安装或本地安装,请包含 Teams extra,以便内置适配器能够导入 Microsoft Teams SDK:
uv sync --extra teams
# or, for editable installs:
uv pip install -e ".[teams]"
第 1 步:安装 Teams CLI
@microsoft/teams.cli 会自动完成机器人注册——无需进入 Azure 门户。
npm install -g @microsoft/teams.cli@preview
teams login
验证你的登录状态并查找你自己的 AAD object ID(TEAMS_ALLOWED_USERS 所需):
teams status --verbose
第 2 步:暴露 Webhook 端口
Teams 无法将消息发送到 localhost。本地开发时,使用任意隧道工具获取公开的 HTTPS URL。默认端口是 3978——如有需要,可通过 TEAMS_PORT 修改。
# devtunnel (Microsoft)
devtunnel create kopi-bot --allow-anonymous
devtunnel port create kopi-bot -p 3978 --protocol https # replace 3978 with TEAMS_PORT if changed
devtunnel host kopi-bot
# ngrok
ngrok http 3978 # replace 3978 with TEAMS_PORT if changed
# cloudflared
cloudflared tunnel --url http://localhost:3978 # replace 3978 with TEAMS_PORT if changed
从输出中复制 https:// URL——下一步会用到。开发期间请保持隧道运行。
生产环境中,请改为将机器人的端点指向服务器的公开域名(参见生产部署)。
第 3 步:创建机器人
teams app create \
--name "Kopi Agent" \
--endpoint "https://<your-tunnel-url>/api/messages"
CLI 会输出你的 CLIENT_ID、CLIENT_SECRET 和 TENANT_ID,以及第 6 步所需的安装链接。请保存好 client secret——它不会再次显示。
第 4 步:配置环境变量
添加到 ~/.kopi/.env:
# Required
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>
# Restrict access to specific users (recommended)
# Use AAD object IDs from `teams status --verbose`
TEAMS_ALLOWED_USERS=<your-aad-object-id>
第 5 步:启动 Gateway
KOPI_UID=$(id -u) KOPI_GID=$(id -g) docker compose up -d gateway
这会启动 gateway。默认 webhook 端口是 3978(可用 TEAMS_PORT 覆盖)。检查它是否正在运行:
curl http://localhost:3978/health # should return: ok
docker logs -f kopi-agent
查看以下输出:
[teams] Webhook server listening on 0.0.0.0:3978/api/messages
第 6 步:在 Teams 中安装应用
teams app get <teamsAppId> --install-link
在浏览器中打开输出的链接——它会直接在 Teams 客户端中打开。安装后,向你的机器人发送一条私信——一切就绪。
配置参考
环境变量
| 变量 | 描述 |
|---|---|
TEAMS_CLIENT_ID | Azure AD 应用(client)ID |
TEAMS_CLIENT_SECRET | Azure AD client secret |
TEAMS_TENANT_ID | Azure AD tenant ID |
TEAMS_ALLOWED_USERS | 允许使用机器人的 AAD object ID,以逗号分隔 |
TEAMS_ALLOW_ALL_USERS | 设置 true 可跳过允许列表,允许所有人使用 |
TEAMS_HOME_CHANNEL | 用于 cron/主动消息投递的 Conversation ID |
TEAMS_HOME_CHANNEL_NAME | 主频道的显示名称 |
TEAMS_PORT | Webhook 端口(默认:3978) |
config.yaml
也可以通过 ~/.kopi/config.yaml 进行配置:
platforms:
teams:
enabled: true
extra:
client_id: "your-client-id"
client_secret: "your-secret"
tenant_id: "your-tenant-id"
port: 3978
功能
交互式审批卡片
当 agent 需要运行可能有危险的命令时,它会发送一张带有四个按钮的 Adaptive Card,而不是让你手动输入 /approve:
- Allow Once — 批准这条特定命令
- Allow Session — 在本次会话的剩余时间内批准该模式
- Always Allow — 永久批准该模式
- Deny — 拒绝该命令
点击按钮即可就地完成审批,并将卡片替换为决策结果。
会议摘要投递(Teams Meeting Pipeline)
启用 Teams 会议 pipeline plugin 时,此适配器还会处理会议摘要的对外投递——只有一套 Teams 集成界面,而非两套。会议转录被摘要完成后,writer 会将摘要发布到你选择的 Teams 目标。
Pipeline 摘要投递在机器人配置旁的 teams 平台条目下配置:
platforms:
teams:
enabled: true
extra:
# existing bot config (client_id, client_secret, tenant_id, port) ...
# Meeting summary delivery (only used when the teams_pipeline plugin is enabled)
delivery_mode: "graph" # or "incoming_webhook"
# For delivery_mode: graph — pick ONE of:
chat_id: "19:meeting_..." # post into a Teams chat
# team_id: "..." # OR post into a channel
# channel_id: "..."
# access_token: "..." # optional; falls back to MSGRAPH_* app credentials
# For delivery_mode: incoming_webhook:
# incoming_webhook_url: "https://outlook.office.com/webhook/..."
| 模式 | 适用场景 | 权衡 |
|---|---|---|
incoming_webhook | 简单的"把摘要发布到这个频道",使用 Teams 生成的静态 URL。 | 无回复线程、无回应表情,以 webhook 配置的身份显示。 |
graph | 通过 Microsoft Graph 以机器人身份在频道中发布带线程的帖子,或发布到 1:1/群聊。 | 需要 Graph 应用注册,并授予 ChannelMessage.Send(频道)或 Chat.ReadWrite.All(聊天)application 权限。 |
如果 teams_pipeline plugin 未启用,这些设置将不会生效——它们只在 pipeline 运行时绑定到 Graph webhook 入口时才会生效。
生产部署
对于长期运行的服务器,请跳过 devtunnel,并将你的服务器公开 HTTPS 端点注册到机器人:
teams app create \
--name "Kopi Agent" \
--endpoint "https://your-domain.com/api/messages"
如果你已经创建了机器人,只需更新端点:
teams app update --id <teamsAppId> --endpoint "https://your-domain.com/api/messages"
确保你配置的端口(TEAMS_PORT,默认 3978)可从互联网访问,且 TLS 证书有效——Teams 会拒绝自签名证书。
故障排查
| 问题 | 解决方案 |
|---|---|
health 端点正常工作,但机器人不响应 | 检查隧道是否仍在运行,以及机器人的消息终结点是否与隧道 URL 一致 |
日志中出现 KeyError: 'teams' | 重启容器 —— 该问题已在当前版本中修复 |
| 机器人返回认证错误 | 确认 TEAMS_CLIENT_ID、TEAMS_CLIENT_SECRET 和 TEAMS_TENANT_ID 均已正确设置 |
No inference provider configured | 检查 ~/.kopi/.env 中是否已设置 ANTHROPIC_API_KEY(或其他 provider 密钥) |
| 机器人收到消息但不予处理 | 你的 AAD object ID 可能不在 TEAMS_ALLOWED_USERS 中。运行 teams status --verbose 查找该 ID |
| 隧道 URL 在重启后发生变化 | 如果使用命名隧道(devtunnel create kopi-bot),devtunnel 的 URL 是持久的。ngrok 和 cloudflared 每次运行都会生成新的 URL(除非你使用付费套餐)—— URL 变化时请用 teams app update 更新机器人的终结点 |
| Teams 显示“This bot is not responding” | webhook 返回了错误。检查 docker logs hermes 中的回溯信息 |
日志中出现 [teams] Failed to connect | SDK 认证失败。请仔细核对你的凭据,并确认租户 ID 与你在 teams login 中使用的账号一致 |
安全
务必设置 TEAMS_ALLOWED_USERS,填入已授权用户的 AAD object ID。若不设置,任何能找到或安装你机器人的人都能与之交互。
请像对待密码一样对待 TEAMS_CLIENT_SECRET —— 定期通过 Azure 门户或 Teams CLI 轮换它。
- 将凭据存储在
~/.kopi/.env中,权限设置为600(chmod 600 ~/.kopi/.env) - 机器人只接受
TEAMS_ALLOWED_USERS中用户发来的消息;未授权的消息会被静默丢弃 - 你的公开端点(
/api/messages)由 Teams Bot Framework 进行认证——没有有效 JWT 的请求会被拒绝