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 會議管道）​

生產部署​

故障排除​

安全性​

相關文檔​