Microsoft Teams 设置

将 Hermes Agent 作为机器人连接到 Microsoft Teams。与 Slack 的 Socket Mode 不同，Teams 通过调用公共 HTTPS webhook 来传递消息，因此你的实例需要一个可公开访问的端点——可以是开发隧道（本地开发）或真实域名（生产环境）。

需要从 Microsoft Graph 事件获取会议摘要，而不是普通的机器人对话？请使用专用的设置页面：Teams 会议。

运行 hermes gateway setup 并选择 Microsoft Teams 以进行引导式设置。

机器人如何响应

上下文	行为
个人聊天 (DM)	机器人响应每条消息。无需 @提及。
群聊	仅当被 @提及时，机器人才会响应。
频道	仅当被 @提及时，机器人才会响应。

Teams 将 @提及作为带有 <at>BotName</at> 标签的常规消息传递，Hermes 会在处理前自动去除这些标签。

对于源码安装或本地安装，请包含 Teams 额外组件，以便 bundled adapter 可以导入 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 对象 ID（TEAMS_ALLOWED_USERS 需要）：

teams status --verbose

步骤 2：暴露 Webhook 端口

Teams 无法将消息传递到 localhost。对于本地开发，使用任何隧道工具获取公共 HTTPS URL。默认端口为 3978——如有需要，可使用 TEAMS_PORT 更改它。

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https  # replace 3978 with TEAMS_PORT if changed
devtunnel host hermes-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 "Hermes" \
  --endpoint "https://<your-tunnel-url>/api/messages"

CLI 会输出你的 CLIENT_ID、CLIENT_SECRET 和 TENANT_ID，以及步骤 6 的安装链接。请保存客户端密钥——它不会再显示。

步骤 4：配置环境变量

添加到 ~/.hermes/.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：启动网关

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d gateway

这将启动网关。默认 webhook 端口为 3978（可使用 TEAMS_PORT 覆盖）。检查其是否正在运行：

curl http://localhost:3978/health   # should return: ok
docker logs -f hermes

查找：

[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 应用（客户端）ID
`TEAMS_CLIENT_SECRET`	Azure AD 客户端密钥
`TEAMS_TENANT_ID`	Azure AD 租户 ID
`TEAMS_ALLOWED_USERS`	允许使用机器人的 AAD 对象 ID（逗号分隔）
`TEAMS_ALLOW_ALL_USERS`	设置为 `true` 以跳过允许列表并允许任何人
`TEAMS_HOME_CHANNEL`	用于 cron/主动消息传递的对话 ID
`TEAMS_HOME_CHANNEL_NAME`	主页频道的显示名称
`TEAMS_PORT`	Webhook 端口（默认：`3978`）

config.yaml

或者，通过 ~/.hermes/config.yaml 进行配置：

platforms:
  teams:
    enabled: true
    extra:
      client_id: "your-client-id"
      client_secret: "your-secret"
      tenant_id: "your-tenant-id"
      port: 3978

功能

交互式审批卡片

当代理需要运行潜在危险命令时，它会发送一个带有四个按钮的 Adaptive Card，而不是要求你输入 /approve：

Allow Once — 批准此特定命令
Allow Session — 在当前会话期间批准此模式
Always Allow — 永久批准此模式
Deny — 拒绝该命令

点击按钮会内联解析审批，并用决策结果替换卡片。

会议摘要交付（Teams 会议管道）

当启用 Teams 会议管道插件时，此适配器还处理会议摘要的外发交付——一个 Teams 集成界面，而非两个。会议转录被总结后，writer 会将摘要发布到你选择的 Teams 目标中。

管道摘要交付在 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/群聊帖子。	需要具有 `ChannelMessage.Send`（频道）或 `Chat.ReadWrite.All`（聊天）应用程序权限的 Graph 应用注册。

如果未启用 teams_pipeline 插件，这些设置将无效——它们仅在管道运行时绑定到 Graph webhook 入口时才生效。

生产部署

对于永久服务器，跳过开发隧道，并使用服务器的公共 HTTPS 端点注册你的机器人：

teams app create \
  --name "Hermes" \
  --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`	检查 `~/.hermes/.env` 中是否设置了 `ANTHROPIC_API_KEY`（或其他提供商密钥）
机器人收到消息但忽略它们	你的 AAD 对象 ID 可能不在 `TEAMS_ALLOWED_USERS` 中。运行 `teams status --verbose` 以查找它
重启时隧道 URL 发生变化	如果使用命名隧道（`devtunnel create hermes-bot`），devtunnel URL 是持久的。除非你有付费计划，否则 ngrok 和 cloudflared 每次运行都会生成新的 URL——当 URL 变化时，使用 `teams app update` 更新机器人端点
Teams 显示“此机器人无响应”	Webhook 返回了错误。检查 `docker logs hermes` 以查看回溯信息
日志中出现 `[teams] Failed to connect`	SDK 认证失败。仔细检查你的凭据，并确保租户 ID 与你在 `teams login` 中使用的账户匹配

安全性

注意

务必设置 TEAMS_ALLOWED_USERS，填入授权用户的 AAD 对象 ID。如果不设置此项，任何能够找到或安装你的机器人都可以与其交互。

将 TEAMS_CLIENT_SECRET 视为密码——通过 Azure 门户或 Teams CLI 定期轮换它。

将凭据存储在 ~/.hermes/.env 中，并设置权限为 600（chmod 600 ~/.hermes/.env）
机器人仅接受来自 TEAMS_ALLOWED_USERS 中用户的消息；未经授权的消息会被静默丢弃
你的公共端点（/api/messages）由 Teams Bot Framework 进行认证——没有有效 JWT 的请求将被拒绝

机器人如何响应​

步骤 1：安装 Teams CLI​

步骤 2：暴露 Webhook 端口​

步骤 3：创建机器人​

步骤 4：配置环境变量​

步骤 5：启动网关​

步骤 6：在 Teams 中安装应用​

配置参考​

环境变量​

config.yaml​

功能​

交互式审批卡片​

会议摘要交付（Teams 会议管道）​

生产部署​

故障排除​

安全性​

相关文档​