<!-- Source: https://hermesbible.com/docs/user-guide/messaging/teams -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/teams

Microsoft Teams 設定

將 Hermes Agent 連接為 Microsoft Teams 的機器人。與 Slack 的 Socket Mode 不同，Teams 透過呼叫公開的 HTTPS Webhook 來傳遞訊息，因此你的實例需要一個公開可達的端點 — 可以是開發用的 Tunnel（本地開發）或正式網域（正式環境）。

需要從 Microsoft Graph 事件取得會議摘要，而非一般的機器人對話嗎？請使用專屬的設定頁面：Teams Meetings。

執行 hermes gateway setup 並選擇 Microsoft Teams 以進行引導設定。

機器人回應方式

Teams 會將 @mention 以 <at>BotName</at> 標籤的普通訊息形式傳遞，Hermes 會在處理前自動將其移除。

---

對於原始碼安裝或本地安裝，需要包含 Teams extra 以便內建的 Adapter 能夠匯入 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 Object ID（用於 TEAMS_ALLOWED_USERS）：

teams status --verbose

---

步驟 2：公開 Webhook 連接埠

Teams 無法將訊息傳遞到 localhost。進行本地開發時，請使用任何 Tunnel 工具取得公開的 HTTPS URL。預設連接埠為 3978 — 如需變更可使用 TEAMS_PORT。

# devtunnel (Microsoft)
devtunnel create hermes-bot --allow-anonymous
devtunnel port create hermes-bot -p 3978 --protocol https  # 若已變更，請將 3978 替換為 TEAMS_PORT
devtunnel host hermes-bot

# ngrok
ngrok http 3978  # 若已變更，請將 3978 替換為 TEAMS_PORT

# cloudflared
cloudflared tunnel --url http://localhost:3978  # 若已變更，請將 3978 替換為 TEAMS_PORT

從輸出中複製 https:// URL — 你將在下一步使用它。開發期間請保持 Tunnel 運作。

在正式環境中，請將機器人的端點指向伺服器的公開網域（參見正式環境部署）。

---

步驟 3：建立機器人

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

CLI 會輸出你的 CLIENT_ID、CLIENT_SECRET 和 TENANT_ID，以及用於步驟 6 的安裝連結。請妥善保存 Client Secret — 它不會再次顯示。

---

步驟 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 Object ID
TEAMS_ALLOWED_USERS=<your-aad-object-id>

---

步驟 5：啟動 Gateway

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

這會啟動 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

---

步驟 6：在 Teams 中安裝 App

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

---

功能

互動式審批卡片

當 Agent 需要執行 potentially dangerous 命令時，它會傳送一張包含四個按鈕的 Adaptive Card，而非要求你輸入 /approve：

• Allow Once — 允許此次特定命令
• Allow Session — 在本次對話剩餘時間內允許此模式
• Always Allow — 永久允許此模式
• Deny — 拒絕該命令

點擊按鈕即可直接完成審批，卡片會被替換為決策結果。

會議摘要傳遞 (Teams Meeting Pipeline)

當啟用 Teams meeting pipeline 外掛 時，此 Adapter 也負責會議摘要的外送傳遞 — 同一個 Teams 整合介面，而非兩個。會議逐字稿完成摘要後，撰寫者會將摘要發佈到你指定的 Teams 目標。

Pipeline 摘要傳遞設定位於 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_* App 憑證
      # delivery_mode: incoming_webhook：
      # incoming_webhook_url: "https://outlook.office.com/webhook/..."

如果 未 啟用 teams_pipeline 外掛，這些設定不會生效 — 僅在 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 會拒絕自簽憑證。

---

疑難排解

---

安全性

WARNING

務必設定 TEAMS_ALLOWED_USERS，使用已授權使用者的 AAD Object 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 Meeting Pipeline

---

---

WeCom 回呼（自建 App）