Microsoft Teams 设置

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

需要 Microsoft Graph 事件的会议摘要而非普通的机器人对话？请使用专门的设置页面：Teams 会议。

机器人如何响应

上下文	行为
个人聊天（私聊）	机器人回复每条消息。无需 @提及。
群聊	机器人仅在 @提及时回复。
频道	机器人仅在 @提及时回复。

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

第一步：安装 Teams CLI

@microsoft/teams.cli 自动化机器人注册——无需 Azure 门户。

npm install -g @microsoft/teams.cli@preview
teams login

要验证您的登录并找到您自己的 AAD 对象 ID（TEAMS_ALLOWED_USERS 所需）：

teams status --verbose

第二步：暴露 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——您将在下一步中使用它。开发期间保持隧道运行。

对于生产环境，将机器人的端点指向您服务器的公共域名（请参见生产部署）。

第三步：创建机器人

teams app create \
  --name "Hermes" \
  --endpoint "https://<your-tunnel-url>/api/messages"

CLI 会输出您的 CLIENT_ID、CLIENT_SECRET 和 TENANT_ID，以及第 6 步的安装链接。保存 client secret——它不会再次显示。

第四步：配置环境变量

添加到 ~/.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>

第五步：启动网关

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

查找：

[teams] Webhook server listening on 0.0.0.0:3978/api/messages

第六步：在 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`	用于定时任务/主动消息投递的对话 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：

允许一次 — 批准此特定命令
允许会话 — 批准此模式在会话余下时间内生效
始终允许 — 永久批准此模式
拒绝 — 拒绝该命令

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

会议摘要投递（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/..."

模式	何时使用	权衡
`incoming_webhook`	通过静态 Teams 生成的 URL 简单”将摘要发布到此频道”。	无回复线程，无反应，显示为 webhook 配置的身份。
`graph`	通过 Microsoft Graph 在机器人身份下发布线程式频道帖子或 1:1/群聊帖子。	需要具有 `ChannelMessage.Send`（频道）或 `Chat.ReadWrite.All`（聊天）应用程序权限的 Graph 应用注册。

如果未启用 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 拒绝自签名证书。

故障排查

问题	解决方法
`health` 端点工作但机器人不响应	检查您的隧道是否仍在运行，以及机器人的消息端点是否与隧道 URL 匹配
日志中出现 `KeyError: 'teams'`	重启容器——这在当前版本中已修复
机器人响应认证错误	确认 `TEAMS_CLIENT_ID`、`TEAMS_CLIENT_SECRET` 和 `TEAMS_TENANT_ID` 均正确设置
`未配置推理提供者`	检查 `~/.hermes/.env` 中是否设置了 `ANTHROPIC_API_KEY`（或其他提供者密钥）
机器人收到消息但忽略它们	您的 AAD 对象 ID 可能不在 `TEAMS_ALLOWED_USERS` 中。运行 `teams status --verbose` 查找它
隧道 URL 在重启后变化	devtunnel 如果使用命名隧道则 URL 是持久的（`devtunnel create hermes-bot`）。ngrok 和 cloudflared 每次运行生成新 URL，除非您有付费计划——更改后用 `teams app update` 更新机器人端点
Teams 显示”此 bot 未响应”	Webhook 返回了错误。检查 `docker logs hermes` 中的回溯信息
日志中出现 `[teams] Failed to connect`	SDK 认证失败。仔细检查您的凭证，并确认租户 ID 与 `teams login` 中使用的账户匹配

安全

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

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

Microsoft Teams