​

Microsoft Teams（外掛）

「凡進入此地者，請放棄一切希望。」

​

33. 需要外掛

openclaw plugins install @openclaw/msteams

openclaw plugins install ./extensions/msteams

​

快速設定（新手）

1. 安裝 Microsoft Teams 外掛。
2. 建立 Azure Bot（App ID + client secret + tenant ID）。
3. 以這些憑證設定 OpenClaw。
4. 透過公開 URL 或通道公開 /api/messages（預設連接埠 3978）。
5. 35. 安裝 Teams 應用程式套件並啟動閘道。

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      appPassword: "<APP_PASSWORD>",
      tenantId: "<TENANT_ID>",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

​

目標

• 透過 Teams 私訊、群組聊天或頻道與 OpenClaw 對話。
• 保持路由的確定性：回覆一律回到訊息來源的頻道。
• 預設採安全的頻道行為（除非另行設定，否則需要提及）。

​

設定寫入

{
  channels: { msteams: { configWrites: false } },
}

​

存取控制（私訊 + 群組）

• 預設：channels.msteams.dmPolicy = "pairing"。未知寄件者在核准前會被忽略。 37. 未知的傳送者在核准前會被忽略。
• channels.msteams.allowFrom: allowlist for DMs (AAD object IDs, UPNs, or display names). The wizard resolves names to IDs during setup when Graph access is available.

• 預設：channels.msteams.groupPolicy = "allowlist"（除非加入 groupAllowFrom，否則封鎖）。若未設定，可用 channels.defaults.groupPolicy 覆寫預設。 40. 在未設定時，使用 channels.defaults.groupPolicy 來覆寫預設值。
• channels.msteams.groupAllowFrom 控制哪些寄件者可在群組聊天／頻道中觸發（回退至 channels.msteams.allowFrom）。
• 設定 groupPolicy: "open" 以允許任何成員（預設仍需提及）。
• 若要 不允許任何頻道，請設定 channels.msteams.groupPolicy: "disabled"。

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
    },
  },
}

• 於 channels.msteams.teams 下列出 Teams 與頻道以限制群組／頻道回覆範圍。
• 鍵值可為 team ID 或名稱；頻道鍵值可為會話 ID 或名稱。
• 當設定 groupPolicy="allowlist" 且存在 teams 允許清單時，僅接受列出的 teams／頻道（需提及）。
• 設定精靈可接受 Team/Channel 項目並替你儲存。
• 啟動時，OpenClaw 會在 Graph 權限允許下，將 team／頻道與使用者允許清單名稱解析為 ID 並記錄對應；無法解析者將保留原樣。

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      teams: {
        "My Team": {
          channels: {
            General: { requireMention: true },
          },
        },
      },
    },
  },
}

​

How it works

1. 安裝 Microsoft Teams 外掛。
2. 建立 Azure Bot（App ID + secret + tenant ID）。
3. 建立 Teams 應用程式套件，參考該機器人並包含下方的 RSC 權限。
4. 將 Teams 應用程式上傳／安裝至 team（或個人範圍以使用私訊）。
5. 在 ~/.openclaw/openclaw.json（或環境變數）中設定 msteams 並啟動 Gateway 閘道器。
6. Gateway 閘道器 預設在 /api/messages 監聽 Bot Framework webhook 流量。

​

Azure Bot 設定（先決條件）

​

步驟 1：建立 Azure Bot

1. 前往 Create Azure Bot
2. 填寫 Basics 分頁：

   欄位	值
   Bot handle	你的機器人名稱，例如 openclaw-msteams（必須唯一）
   Subscription	選擇你的 Azure 訂閱
   Resource group	新建或使用既有
   Pricing tier	開發／測試用選 Free
   Type of App	Single Tenant（建議，見下方說明）
   Creation type	Create new Microsoft App ID

Deprecation notice: Creation of new multi-tenant bots was deprecated after 2025-07-31. Use Single Tenant for new bots.

3. 點擊 Review + create → Create（等待約 1–2 分鐘）

​

步驟 2：取得憑證

1. 前往你的 Azure Bot 資源 → Configuration
2. 複製 Microsoft App ID → 即為你的 appId
3. 點擊 Manage Password → 前往 App Registration
4. 於 Certificates & secrets → New client secret → 複製 Value → 即為你的 appPassword
5. 前往 Overview → 複製 Directory (tenant) ID → 即為你的 tenantId

​

Step 3: Configure Messaging Endpoint

1. 在 Azure Bot → Configuration
2. 將 Messaging endpoint 設為你的 webhook URL：
   • 正式環境：https://your-domain.com/api/messages
   • 本機開發：使用通道（請見下方〈本機開發（通道）〉）

​

步驟 4：啟用 Teams 頻道

1. 在 Azure Bot → Channels
2. 點擊 Microsoft Teams → Configure → Save
3. 接受服務條款

​

Local Development (Tunneling)

ngrok http 3978
# Copy the https URL, e.g., https://abc123.ngrok.io
# Set messaging endpoint to: https://abc123.ngrok.io/api/messages

tailscale funnel 3978
# Use your Tailscale funnel URL as the messaging endpoint

​

Teams Developer Portal（替代方案）

1. 點擊 + New app
2. 填寫基本資訊（名稱、描述、開發者資訊）
3. 前往 App features → Bot
4. 選擇 Enter a bot ID manually 並貼上你的 Azure Bot App ID
5. 勾選範圍：Personal、Team、Group Chat
6. 點擊 Distribute → Download app package
7. 在 Teams：Apps → Manage your apps → Upload a custom app → 選擇 ZIP

​

Testing the Bot

1. Azure Portal → 你的 Azure Bot 資源 → Test in Web Chat
2. 傳送訊息——應可看到回應
3. 確認 Teams 設定前，先驗證 webhook 端點可用

1. 安裝 Teams 應用程式（側載或組織目錄）
2. Find the bot in Teams and send a DM
3. Check gateway logs for incoming activity

​

設定（最小文字版）

1. 安裝 Microsoft Teams 外掛
   • 來自 npm：openclaw plugins install @openclaw/msteams
   • 來自本機檢出：openclaw plugins install ./extensions/msteams
2. 機器人註冊
   • 建立 Azure Bot（見上文）並記下：
     • App ID
     • Client secret（App 密碼）
     • Tenant ID（單一租戶）
3. Teams 應用程式 manifest
   • 包含 bot 項目，值為 botId = <App ID>。
   • 範圍：personal、team、groupChat。
   • supportsFiles: true（個人範圍檔案處理必需）。
   • 加入 RSC 權限（如下）。
   • 建立圖示：outline.png（32×32）與 color.png（192×192）。
   • 將三個檔案一起壓縮：manifest.json、outline.png、color.png。
4. 設定 OpenClaw
   {
     "msteams": {
       "enabled": true,
       "appId": "<APP_ID>",
       "appPassword": "<APP_PASSWORD>",
       "tenantId": "<TENANT_ID>",
       "webhook": { "port": 3978, "path": "/api/messages" }
     }
   }
   
   也可改用環境變數而非設定鍵：
   • MSTEAMS_APP_ID
   • MSTEAMS_APP_PASSWORD
   • MSTEAMS_TENANT_ID
5. Bot endpoint
   • 將 Azure Bot Messaging Endpoint 設為：
     • https://<host>:3978/api/messages（或自訂路徑／連接埠）。
6. 執行 Gateway 閘道器
   • 安裝外掛且存在含憑證的 msteams 設定時，Teams 頻道會自動啟動。

​

歷史脈絡

• channels.msteams.historyLimit 控制要包入提示中的最近頻道／群組訊息數量。
• 回退至 messages.groupChat.historyLimit。設定 0 可停用（預設 50）。 Set 0 to disable (default 50). Set 0 to disable (default 50).
• 私訊（DM）歷史可用 channels.msteams.dmHistoryLimit（使用者回合）限制；每位使用者可用 channels.telegram.dms["<user_id>"].historyLimit 覆寫。 私訊（DM）歷史可用 channels.msteams.dmHistoryLimit（使用者回合）限制；每位使用者可用 channels.telegram.dms["<user_id>"].historyLimit 覆寫。 私訊歷史可用 channels.msteams.dmHistoryLimit（使用者輪次）限制。每位使用者可用 channels.msteams.dms["<user_id>"].historyLimit 覆寫。

​

目前 Teams RSC 權限（Manifest）

• ChannelMessage.Read.Group（Application）— 不需 @mention 即可接收所有頻道訊息
• ChannelMessage.Send.Group（Application）
• Member.Read.Group（Application）
• Owner.Read.Group（Application）
• ChannelSettings.Read.Group（Application）
• TeamMember.Read.Group（Application）
• TeamSettings.Read.Group（Application）

• ChatMessage.Read.Chat（Application）— 不需 @mention 即可接收所有群組聊天訊息

​

範例 Teams Manifest（已隱去）

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",
  "manifestVersion": "1.23",
  "version": "1.0.0",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": { "short": "OpenClaw" },
  "developer": {
    "name": "Your Org",
    "websiteUrl": "https://example.com",
    "privacyUrl": "https://example.com/privacy",
    "termsOfUseUrl": "https://example.com/terms"
  },
  "description": { "short": "OpenClaw in Teams", "full": "OpenClaw in Teams" },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#5B6DEF",
  "bots": [
    {
      "botId": "11111111-1111-1111-1111-111111111111",
      "scopes": ["personal", "team", "groupChat"],
      "isNotificationOnly": false,
      "supportsCalling": false,
      "supportsVideo": false,
      "supportsFiles": true
    }
  ],
  "webApplicationInfo": {
    "id": "11111111-1111-1111-1111-111111111111"
  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        { "name": "ChannelMessage.Read.Group", "type": "Application" },
        { "name": "ChannelMessage.Send.Group", "type": "Application" },
        { "name": "Member.Read.Group", "type": "Application" },
        { "name": "Owner.Read.Group", "type": "Application" },
        { "name": "ChannelSettings.Read.Group", "type": "Application" },
        { "name": "TeamMember.Read.Group", "type": "Application" },
        { "name": "TeamSettings.Read.Group", "type": "Application" },
        { "name": "ChatMessage.Read.Chat", "type": "Application" }
      ]
    }
  }
}

​

Manifest 注意事項（必備欄位）

• bots[].botId 必須 與 Azure Bot App ID 相符。
• webApplicationInfo.id 必須 與 Azure Bot App ID 相符。
• bots[].scopes 必須包含你計畫使用的介面（personal、team、groupChat）。
• bots[].supportsFiles: true 為個人範圍檔案處理所需。
• authorization.permissions.resourceSpecific 若要使用頻道流量，必須包含讀取／傳送。

​

更新既有應用程式

1. 更新你的 manifest.json 設定
2. 遞增 version 欄位（例如 1.0.0 → 1.1.0）
3. 重新壓縮 manifest 與圖示（manifest.json、outline.png、color.png）
4. 上傳新的 ZIP：
   • 選項 A（Teams Admin Center）： Teams Admin Center → Teams apps → Manage apps → 找到你的應用程式 → Upload new version
   • 選項 B（側載）： Teams → Apps → Manage your apps → Upload a custom app
5. 頻道（team）： 在每個 team 重新安裝應用程式，權限才會生效
6. 完全結束並重新啟動 Teams（不只是關閉視窗）以清除快取的應用程式中繼資料

​

能力：僅 RSC vs Graph

​

僅 Teams RSC（已安裝應用程式，無 Graph API 權限）

• Read channel message text content.
• Send channel message text content.
• 接收 個人（私訊） 檔案附件。

• 頻道／群組 圖片或檔案內容（負載僅包含 HTML stub）。
• 下載儲存在 SharePoint／OneDrive 的附件。
• Reading message history (beyond the live webhook event).

​

Teams RSC + Microsoft Graph Application 權限

• Downloading hosted contents (images pasted into messages).
• 下載儲存在 SharePoint／OneDrive 的檔案附件。
• 透過 Graph 讀取頻道／聊天訊息歷史。

​

RSC vs Graph API

​

啟用 Graph 的媒體 + 歷史（頻道必需）

1. 在 Entra ID（Azure AD）App Registration 中新增 Microsoft Graph Application 權限：
   • ChannelMessage.Read.All（頻道附件 + 歷史）
   • Chat.Read.All 或 ChatMessage.Read.All（群組聊天）
2. 授與租戶的管理員同意。
3. 提升 Teams 應用程式 manifest 版本、重新上傳，並 在 Teams 中重新安裝應用程式。
4. 完全結束並重新啟動 Teams 以清除快取的應用程式中繼資料。

​

已知限制

​

Webhook 逾時

• Gateway timeouts
• Teams 重試訊息（造成重複）
• 回覆遺失

​

格式

• 基本格式可用：粗體、斜體、code、連結
• 複雜 Markdown（表格、巢狀清單）可能無法正確顯示
• 投票與任意卡片可使用 Adaptive Cards（見下文）

​

設定

• channels.msteams.enabled：啟用／停用頻道。
• channels.msteams.appId、channels.msteams.appPassword、channels.msteams.tenantId：機器人憑證。
• channels.msteams.webhook.port（預設 3978）
• channels.msteams.webhook.path（預設 /api/messages）
• channels.msteams.dmPolicy：pairing | allowlist | open | disabled（預設：pairing）
• channels.msteams.allowFrom 接受 AAD 物件 ID、UPN 或顯示名稱。 39. 在認證允許的情況下，精靈會透過 Microsoft Graph 將名稱解析為 ID。
• channels.msteams.textChunkLimit：輸出文字分塊大小。
• channels.msteams.chunkMode：length（預設）或 newline，在長度分塊前以空行（段落邊界）切分。
• channels.msteams.mediaAllowHosts：入站附件主機允許清單（預設為 Microsoft／Teams 網域）。
• channels.msteams.mediaAuthAllowHosts：媒體重試時附加 Authorization 標頭的主機允許清單（預設為 Graph + Bot Framework 主機）。
• channels.msteams.requireMention：頻道／群組是否需要 @mention（預設 true）。
• channels.msteams.replyStyle：thread | top-level（見〈回覆樣式〉）。
• channels.msteams.teams.<teamId>.replyStyle：每 team 覆寫。
• channels.msteams.teams.<teamId>.requireMention：每 team 覆寫。
• channels.msteams.teams.<teamId>.tools：每 team 的預設工具政策覆寫（allow/deny/alsoAllow），在缺少頻道覆寫時使用。
• channels.msteams.teams.<teamId>.toolsBySender：每 team、每寄件者的工具政策覆寫（支援 "*" 萬用字元）。
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle：每頻道覆寫。
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention：每頻道覆寫。
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools：每頻道工具政策覆寫（allow/deny/alsoAllow）。
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender：每頻道、每寄件者的工具政策覆寫（支援 "*" 萬用字元）。
• channels.msteams.sharePointSiteId：群組聊天／頻道檔案上傳用的 SharePoint site ID（見〈在群組聊天中傳送檔案〉）。

​

Routing & Sessions

• 工作階段鍵遵循標準代理程式格式（見 /concepts/session）：
  • 私訊共用主要工作階段（agent:<agentId>:<mainKey>）。
  • 頻道／群組訊息使用會話 ID：
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

回覆樣式：Threads vs Posts

• 在 Threads 樣式頻道使用 thread → 回覆會不自然地巢狀
• 在 Posts 樣式頻道使用 top-level → 回覆會成為獨立的頂層貼文，而非串內

{
  "msteams": {
    "replyStyle": "thread",
    "teams": {
      "19:[email protected]": {
        "channels": {
          "19:[email protected]": {
            "replyStyle": "top-level"
          }
        }
      }
    }
  }
}

​

附件與圖片

• 私訊： 圖片與檔案附件可透過 Teams 機器人檔案 API 使用。
• 頻道／群組： 附件存放於 M365 儲存體（SharePoint／OneDrive）。Webhook 負載僅含 HTML stub，沒有實際位元組。需要 Graph API 權限 才能下載頻道附件。 The webhook payload only includes an HTML stub, not the actual file bytes. The webhook payload only includes an HTML stub, not the actual file bytes. Graph API permissions are required to download channel attachments.

​

在群組聊天中傳送檔案

​

為何群組聊天需要 SharePoint

​

設定

1. 在 Entra ID（Azure AD）→ App Registration 新增 Graph API 權限：
   • Sites.ReadWrite.All（Application）— 上傳檔案至 SharePoint
   • Chat.Read.All（Application）— 選用，啟用逐使用者分享連結
2. 授與租戶的管理員同意。
3. 取得 SharePoint site ID：
   # Via Graph Explorer or curl with a valid token:
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
   
   # Example: for a site at "contoso.sharepoint.com/sites/BotFiles"
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
   
   # Response includes: "id": "contoso.sharepoint.com,guid1,guid2"
   
4. 設定 OpenClaw：
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

分享行為

​

回退行為

​

檔案儲存位置

​

投票（Adaptive Cards）

• CLI：openclaw message poll --channel msteams --target conversation:<id> ...
• 投票結果由 Gateway 閘道器 記錄於 ~/.openclaw/msteams-polls.json。
• Gateway 閘道器 必須保持上線才能記錄投票。
• 投票目前尚未自動張貼結果摘要（如有需要請檢查儲存檔案）。

​

Adaptive Cards（任意）

{
  "action": "send",
  "channel": "msteams",
  "target": "user:<id>",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello!" }]
  }
}

openclaw message send --channel msteams \
  --target "conversation:19:[email protected]" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'

​

目標格式

# Send to a user by ID
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"

# Send to a user by display name (triggers Graph API lookup)
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"

# Send to a group chat or channel
openclaw message send --channel msteams --target "conversation:19:[email protected]" --message "Hello"

# Send an Adaptive Card to a conversation
openclaw message send --channel msteams --target "conversation:19:[email protected]" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'

{
  "action": "send",
  "channel": "msteams",
  "target": "user:John Smith",
  "message": "Hello!"
}

{
  "action": "send",
  "channel": "msteams",
  "target": "conversation:19:[email protected]",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello" }]
  }
}

​

6. 主動式訊息

• 只有在使用者互動之後才能進行主動式訊息，因為我們會在該時點儲存對話參考。
• 請見 /gateway/configuration 以了解 dmPolicy 與允許清單門檻。

​

Team 與 Channel ID（常見陷阱）

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    Team ID (URL-decode this)

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      Channel ID (URL-decode this)

• Team ID = /team/ 之後的路徑片段（URL 解碼，例如 19:[email protected]）
• Channel ID = /channel/ 之後的路徑片段（URL 解碼）
• 忽略 groupId 查詢參數

​

私人頻道

1. 使用標準頻道與機器人互動
2. 13. 使用私訊（DM）—使用者隨時都可以直接傳訊給機器人
3. 使用 Graph API 讀取歷史（需要 ChannelMessage.Read.All）

​

常見問題

​

常見問題

• 頻道中看不到圖片： 缺少 Graph 權限或管理員同意。重新安裝 Teams 應用程式並完全結束／重啟 Teams。 15. 重新安裝 Teams 應用程式，並完全關閉後再重新開啟 Teams。
• 頻道沒有回應： 預設需要提及；設定 channels.msteams.requireMention=false 或逐 team／頻道設定。
• 版本不一致（Teams 仍顯示舊 manifest）： 移除並重新加入應用程式，並完全結束 Teams 以刷新。
• Webhook 回傳 401 Unauthorized： 在未使用 Azure JWT 手動測試時屬正常，表示端點可達但驗證失敗。請使用 Azure Web Chat 正確測試。 16. 使用 Azure Web Chat 進行正確的測試。

​

Manifest 上傳錯誤

• 「Icon file cannot be empty」： manifest 參照的圖示為 0 位元組。請建立有效的 PNG 圖示（outline.png 需 32×32，color.png 需 192×192）。 17. 建立有效的 PNG 圖示（outline.png 為 32x32，color.png 為 192x192）。
• 「webApplicationInfo.Id already in use」： 應用程式仍安裝於其他 team／聊天。請先解除安裝，或等待 5–10 分鐘傳播完成。 18. 請先找到並解除安裝，或等待 5–10 分鐘讓變更傳播完成。
• 上傳時顯示「Something went wrong」： 改用 https://admin.teams.microsoft.com 上傳，開啟瀏覽器 DevTools（F12）→ Network 分頁，查看回應本文以取得實際錯誤。
• 側載失敗： 嘗試「Upload an app to your org’s app catalog」而非「Upload a custom app」，通常可繞過側載限制。

​

RSC 權限無法運作

1. 確認 webApplicationInfo.id 與機器人的 App ID 完全相符
2. 重新上傳應用程式並在 team／聊天中重新安裝
3. 檢查組織管理員是否封鎖 RSC 權限
4. 確認使用正確範圍：teams 使用 ChannelMessage.Read.Group，群組聊天使用 ChatMessage.Read.Chat

​

參考資料

• Create Azure Bot — Azure Bot 設定指南
• Teams Developer Portal — 建立／管理 Teams 應用程式
• Teams app manifest schema
• Receive channel messages with RSC
• RSC permissions reference
• Teams bot file handling（頻道／群組需要 Graph）
• Proactive messaging