hermes教程-Microsoft Teams 设置

Microsoft Teams 设置

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

如果你需要的是来自 Microsoft Graph 事件的会议摘要，而不是普通的机器人对话，请使用专门的设置页面：Teams Meetings。

运行 hermes gateway setup 并选择 Microsoft Teams 以获得引导式操作指南。

机器人如何响应

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

对于源码或本地安装，请包含 Teams 额外依赖，以便捆绑的适配器能够导入 Microsoft Teams SDK：

uv sync --extra teams
## 或者，对于可编辑安装：
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  # 如果更改了 TEAMS_PORT，请替换 3978
devtunnel host hermes-bot
## ngrok
ngrok http 3978  # 如果更改了 TEAMS_PORT，请替换 3978
## cloudflared
cloudflared tunnel --url http://localhost:3978  # 如果更改了 TEAMS_PORT，请替换 3978

从输出中复制 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：

## 必需
TEAMS_CLIENT_ID=<your-client-id>
TEAMS_CLIENT_SECRET=<your-client-secret>
TEAMS_TENANT_ID=<your-tenant-id>
## 限制访问特定用户（推荐）
## 使用 `teams status --verbose` 中的 AAD 对象 ID
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   # 应返回：ok
docker logs -f hermes

查找：

步骤 6：在 Teams 中安装应用

teams app get <teamsAppId> --install-link

在浏览器中打开打印的链接——它会直接在 Teams 客户端中打开。安装后，向你的机器人发送一条直接消息——它已准备就绪。

配置参考

环境变量

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

功能

交互式审批卡片

当代理需要执行潜在危险命令时，它会发送一张自适应卡片，包含四个按钮，而不是要求你输入 /approve：

• 允许一次 — 批准此特定命令
• 允许会话 — 在本次会话的剩余时间内批准此模式
• 始终允许 — 永久批准此模式
• 拒绝 — 拒绝命令

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

会议摘要投递（Teams 会议管道）

当启用了 Teams 会议管道插件 时，此适配器还负责会议摘要的出站投递——一个 Teams 集成界面，而非两个。会议记录被总结后，写入器会将摘要发布到你选择的 Teams 目标中。

管道摘要投递在 teams 平台条目下与机器人配置一起配置：

platforms:
  teams:
    enabled: true
    extra:
## 现有机器人配置 (client_id, client_secret, tenant_id, port) ...
## 会议摘要投递（仅在启用 teams_pipeline 插件时使用）
      delivery_mode: "graph"       # 或 "incoming_webhook"
## 对于 delivery_mode: graph — 选择以下之一：
      chat_id: "19:meeting_..."    # 发布到 Teams 聊天
## team_id: "..."             # 或发布到频道
## channel_id: "..."
## access_token: "..."        # 可选；回退到 MSGRAPH_* 应用凭据
## 对于 delivery_mode: incoming_webhook:
## incoming_webhook_url: "https://outlook.office.com/webhook/..."

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

生产部署

对于永久服务器，跳过 devtunnel，将机器人注册到服务器的公共 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 会拒绝自签名证书。

故障排除

安全

警告

始终设置 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 的请求将被拒绝

相关文档

• Teams Meetings
• 操作 Teams 会议管道