Microsoft Teams

​

內建外掛

openclaw plugins install @openclaw/msteams

openclaw plugins install ./path/to/local/msteams-plugin

​

快速設定

npm install -g @microsoft/teams.cli@preview
teams login
teams status   # verify you're logged in and see your tenant info

# One-time setup (persistent URL across sessions):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot
# Your endpoint: https://<tunnel-id>.devtunnels.ms/api/messages

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

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

teams app get <teamsAppId> --install-link

teams app doctor <teamsAppId>

​

目標

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

​

設定寫入

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

​

存取控制（DM + 群組）

• 預設：channels.msteams.dmPolicy = "pairing"。未知寄件者在核准前會被忽略。
• channels.msteams.allowFrom 應使用穩定的 AAD 物件 ID，或靜態寄件者存取群組，例如 accessGroup:core-team。
• 不要依賴 UPN/顯示名稱比對來建立允許清單；它們可能會變更。OpenClaw 預設停用直接名稱比對；可使用 channels.msteams.dangerouslyAllowNameMatching: true 選擇啟用。
• 當憑證允許時，精靈可以透過 Microsoft Graph 將名稱解析為 ID。

• 預設：channels.msteams.groupPolicy = "allowlist"（除非加入 groupAllowFrom，否則封鎖）。當 channels.msteams.groupPolicy 未設定時，channels.defaults.groupPolicy 可以覆寫共用預設值。
• channels.msteams.groupAllowFrom 控制哪些寄件者或靜態寄件者存取群組可以在群組聊天/頻道中觸發（會回退到 channels.msteams.allowFrom）。
• 設定 groupPolicy: "open" 可允許任何成員（預設仍需提及）。
• 若要封鎖所有頻道，請設定 channels.msteams.groupPolicy: "disabled"。

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["00000000-0000-0000-0000-000000000000", "accessGroup:core-team"],
    },
  },
}

• 在 channels.msteams.teams 下列出團隊與頻道，以限定群組/頻道回覆範圍。
• 使用 Teams 連結中的穩定 Teams 對話 ID 作為鍵，而不是可變的顯示名稱（請參閱團隊與頻道 ID）。
• 當 groupPolicy="allowlist" 且存在 teams 允許清單時，只接受列出的團隊/頻道（需提及）。
• 設定精靈接受 Team/Channel 項目，並會替你儲存。
• 啟動時，OpenClaw 會將團隊/頻道與使用者允許清單名稱解析為 ID（當 Graph 權限允許時），並記錄對應關係。未解析的名稱會保留為輸入值，但除非設定 channels.msteams.dangerouslyAllowNameMatching: true，否則路由時會忽略。

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

​

同盟驗證（憑證加受控識別）

​

選項 A：憑證式驗證

1. 產生或取得憑證（含私密金鑰的 PEM 格式）。
2. Entra ID → App Registration → Certificates & secrets → Certificates → 上傳公開憑證。

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      certificatePath: "/path/to/cert.pem",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem

​

選項 B：Azure 受控識別

1. bot pod/VM 具有受控識別（系統指派或使用者指派）。
2. 同盟識別憑證會將受控識別連結到 Entra ID 應用程式註冊。
3. 執行時，OpenClaw 使用 @azure/identity 從 Azure IMDS 端點取得 token。
4. token 會傳遞給 Teams SDK，用於 bot 驗證。

• 已啟用受控識別的 Azure 基礎設施（AKS workload identity、App Service、VM）。
• 已在 Entra ID 應用程式註冊上建立同盟識別憑證。
• pod/VM 可網路存取 IMDS（169.254.169.254:80）。

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

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id>（僅限使用者指派）

​

AKS Workload Identity 設定

1. 在 AKS 叢集上啟用工作負載身分識別。
2. 在 Entra ID 應用程式註冊上建立同盟身分識別認證：
   az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{
     "name": "my-bot-workload-identity",
     "issuer": "<AKS_OIDC_ISSUER_URL>",
     "subject": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>",
     "audiences": ["api://AzureADTokenExchange"]
   }'
   
3. 使用應用程式用戶端 ID 註解 Kubernetes 服務帳戶：
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-bot-sa
     annotations:
       azure.workload.identity/client-id: "<APP_CLIENT_ID>"
   
4. 標記 Pod 以注入工作負載身分識別：
   metadata:
     labels:
       azure.workload.identity/use: "true"
   
5. 允許網路存取 IMDS (169.254.169.254)：如果使用 NetworkPolicy，請為連接埠 80 上的 169.254.169.254/32 新增輸出規則。

​

驗證類型比較

​

本機開發（通道轉發）

# One-time setup:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot

teams app update <teamsAppId> --endpoint "https://<new-url>/api/messages"

​

測試機器人

teams app doctor <teamsAppId>

1. 安裝 Teams 應用程式（安裝連結來自 teams app get <id> --install-link）。
2. 在 Teams 中找到機器人並傳送 DM。
3. 檢查閘道記錄中是否有傳入活動。

​

環境變數

​

成員資訊動作

• Member.Read.Group RSC 權限（已包含在建議的資訊清單中）。
• 跨團隊查詢：需要 User.Read.All Graph 應用程式權限並取得管理員同意。

​

歷史內容脈絡

• channels.msteams.historyLimit 控制要將多少最近的頻道/群組訊息包入提示。會回退到 messages.groupChat.historyLimit，再預設為 50。設定 0 可停用。
• 擷取到的討論串歷史會依寄件者允許清單 (allowFrom / groupAllowFrom) 篩選，因此討論串脈絡植入只包含來自允許寄件者的訊息。
• 引用附件脈絡（從回覆本身附件中的 Skype Reply-schema HTML 解析）會不經篩選直接傳遞；目前只有討論串歷史植入會套用寄件者允許清單篩選器。
• DM 歷史可用 channels.msteams.dmHistoryLimit（使用者回合）限制。每位使用者覆寫：channels.msteams.dms["<user_id>"].historyLimit。

​

目前的 Teams RSC 權限（資訊清單）

• ChannelMessage.Read.Group（應用程式）- 接收所有未 @mention 的頻道訊息
• ChannelMessage.Send.Group（應用程式）
• Member.Read.Group（應用程式）
• Owner.Read.Group（應用程式）
• ChannelSettings.Read.Group（應用程式）
• TeamMember.Read.Group（應用程式）
• TeamSettings.Read.Group（應用程式）

• ChatMessage.Read.Chat（應用程式）- 接收所有未 @mention 的群組聊天訊息

teams app rsc add <teamsAppId> ChannelMessage.Read.Group --type Application

​

Teams 資訊清單範例（已遮蔽）

{
  $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" },
      ],
    },
  },
}

​

資訊清單注意事項（必備欄位）

• bots[].botId 必須符合 Azure Bot 應用程式 ID。
• webApplicationInfo.id 必須符合 Azure Bot 應用程式 ID。
• bots[].scopes 必須包含你計畫使用的介面（personal、team、groupChat）。
• bots[].supportsFiles: true 是在個人範圍中處理檔案所必需。
• authorization.permissions.resourceSpecific 必須包含頻道流量所需的頻道讀取/傳送權限。

​

更新現有應用程式

# Download, edit, and re-upload the manifest
teams app manifest download <teamsAppId> manifest.json
# Edit manifest.json locally...
teams app manifest upload manifest.json <teamsAppId>
# Version is auto-bumped if content changed

​

功能：僅 RSC 與 Graph

​

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

• 讀取頻道訊息文字內容。
• 傳送頻道訊息文字內容。
• 接收**個人（DM）**檔案附件。

• 頻道/群組影像或檔案內容（承載資料只包含 HTML stub）。
• 下載儲存在 SharePoint/OneDrive 的附件。
• 讀取即時網路鉤子事件以外的訊息歷史。

​

使用 Teams RSC + Microsoft Graph 應用程式權限

• 下載託管內容（貼到訊息中的影像）。
• 下載儲存在 SharePoint/OneDrive 的檔案附件。
• 透過 Graph 讀取頻道/聊天訊息歷史。

​

RSC 與 Graph API

​

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

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

​

已知限制

​

網路鉤子逾時

• Teams 重試訊息（造成重複）。
• 回覆被捨棄。

​

Teams 雲端與服務 URL 支援

• channels.msteams.cloud 會選取 Teams SDK 雲端預設集，用於驗證、JWT 驗證、權杖服務與 Graph 範圍。
• channels.msteams.serviceUrl 會選取 Bot Connector 端點邊界，用於在主動傳送、編輯、刪除、卡片、投票、檔案同意訊息，以及已排入佇列的長時間執行回覆之前驗證已儲存的對話參照。USGov 與 DoD SDK 雲端需要它。對於 China/21Vianet，OpenClaw 會使用 SDK China 預設集，且只接受 Azure China Bot Framework channel 主機上的已儲存/已設定服務 URL。

{
  "channels": {
    "msteams": {
      "serviceUrl": "https://smba.infra.gcc.teams.microsoft.com/teams"
    }
  }
}

{
  "channels": {
    "msteams": {
      "cloud": "USGov",
      "serviceUrl": "https://smba.infra.gov.teams.microsoft.us/teams"
    }
  }
}

​

格式設定

• 基本格式可運作：粗體、斜體、code、連結。
• 複雜 markdown（表格、巢狀清單）可能無法正確呈現。
• Adaptive Cards 支援投票和語意呈現傳送（見下方）。

​

設定

• channels.msteams.enabled：啟用/停用 channel。
• channels.msteams.appId、channels.msteams.appPassword、channels.msteams.tenantId：bot 憑證。
• channels.msteams.cloud：Teams SDK 雲端環境（Public、USGov、USGovDoD 或 China；預設 Public）。USGov/DoD SDK 雲端請搭配 serviceUrl 設定；China 使用 SDK 預設集和已儲存的 Azure China Bot Framework 對話參照，且 Graph 支援的輔助功能會停用，直到 Azure China Graph 路由發布為止。
• channels.msteams.serviceUrl：SDK 主動操作的 Bot Connector 服務 URL 邊界。公用雲端使用 SDK 預設值；請為 GCC（https://smba.infra.gcc.teams.microsoft.com/teams）、GCC High 或 DoD 設定。當已儲存的對話參照來自 21Vianet 營運的 Teams 時，China 會接受 Azure China Bot Framework channel 主機。
• channels.msteams.webhook.port（預設 3978）。
• channels.msteams.webhook.path（預設 /api/messages）。
• channels.msteams.dmPolicy：pairing | allowlist | open | disabled（預設 pairing）。
• channels.msteams.allowFrom：DM 允許清單（建議使用 AAD 物件 ID）。Graph 存取可用時，精靈會在設定期間將名稱解析為 ID。
• channels.msteams.dangerouslyAllowNameMatching：緊急切換，用於重新啟用可變的 UPN/顯示名稱比對，以及直接團隊/channel 名稱路由。
• channels.msteams.textChunkLimit：傳出文字區塊大小（字元數，預設 4000，且無論設定值更高與否，硬性上限皆為 4000）。
• channels.msteams.chunkMode：length（預設）或 newline，用於在依長度分塊前，先依空白行（段落邊界）分割。
• channels.msteams.mediaAllowHosts：傳入附件主機允許清單（預設為 Microsoft/Teams 網域：Graph、SharePoint/OneDrive、Teams CDN、Bot Framework、Azure Media Services）。
• channels.msteams.mediaAuthAllowHosts：媒體重試時可附加 Authorization 標頭的允許清單（預設為 Graph + Bot Framework 主機）。
• channels.msteams.mediaMaxMb：每個 channel 的媒體大小限制覆寫值，單位 MB。未設定時退回 agents.defaults.mediaMaxMb。
• channels.msteams.requireMention：在 channel/群組中需要 @mention（預設 true）。
• channels.msteams.replyStyle：thread | top-level（請見 回覆樣式）。
• channels.msteams.teams.<teamId>.replyStyle：每個團隊的覆寫值。
• channels.msteams.teams.<teamId>.requireMention：每個團隊的覆寫值。
• channels.msteams.teams.<teamId>.tools：每個團隊預設的工具政策覆寫值（allow/deny/alsoAllow），在缺少 channel 覆寫值時使用。
• channels.msteams.teams.<teamId>.toolsBySender：每個團隊、每位傳送者的預設工具政策覆寫值（支援 "*" 萬用字元）。
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle：每個 channel 的覆寫值。
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention：每個 channel 的覆寫值。
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools：每個 channel 的工具政策覆寫值（allow/deny/alsoAllow）。
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender：每個 channel、每位傳送者的工具政策覆寫值（支援 "*" 萬用字元）。
• toolsBySender 鍵應使用明確前綴：channel:、id:、e164:、username:、name:（舊版未加前綴的鍵仍只會對應到 id:）。
• channels.msteams.authType：驗證類型 - "secret"（預設）或 "federated"。
• channels.msteams.certificatePath：PEM 憑證檔案路徑（聯合 + 憑證驗證）。
• channels.msteams.certificateThumbprint：憑證指紋；會接受，但驗證不需要。
• channels.msteams.useManagedIdentity：啟用受控身分驗證（聯合模式）。
• channels.msteams.managedIdentityClientId：使用者指派受控身分的用戶端 ID。
• channels.msteams.sharePointSiteId：在群組聊天/channel 中上傳檔案的 SharePoint 網站 ID（請見 在群組聊天中傳送檔案）。
• channels.msteams.welcomeCard、channels.msteams.groupWelcomeCard、channels.msteams.promptStarters：首次 DM/群組聯絡時顯示的歡迎 Adaptive Card，以及其建議提示按鈕。
• channels.msteams.responsePrefix：加到傳出回覆前的文字。
• channels.msteams.feedbackEnabled（預設 true）、channels.msteams.feedbackReflection（預設 true）、channels.msteams.feedbackReflectionCooldownMs：回覆上的讚/倒讚意見回饋，以及負面意見回饋反思追蹤。
• channels.msteams.sso、channels.msteams.delegatedAuth：用於 SSO 支援流程的 Bot Framework OAuth 連線與委派 Graph 範圍；sso.enabled: true 需要 sso.connectionName。

​

路由與工作階段

• 工作階段鍵遵循標準代理格式（請見 /concepts/session）：
  • 直接訊息共用主要工作階段（agent:<agentId>:<mainKey>）。
  • Channel/群組訊息使用對話 ID：
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

回覆樣式：執行緒與貼文

• 在執行緒樣式 channel 中使用 thread → 回覆會尷尬地呈現為巢狀。
• 在貼文樣式 channel 中使用 top-level → 回覆會顯示為獨立的頂層貼文，而不是在執行緒中。

{
  channels: {
    msteams: {
      replyStyle: "thread",
      teams: {
        "19:abc...@thread.tacv2": {
          channels: {
            "19:xyz...@thread.tacv2": {
              replyStyle: "top-level",
            },
          },
        },
      },
    },
  },
}

​

解析優先順序

1. 每個 channel - channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. 每個團隊 - channels.msteams.teams.<teamId>.replyStyle
3. 全域 - channels.msteams.replyStyle
4. 隱含預設值 - 從 requireMention 推導：
   • requireMention: true → thread
   • requireMention: false → top-level

​

執行緒脈絡保留

​

附件與圖片

• DM： 圖片和檔案附件可透過 Teams 機器人檔案 API 運作。
• 頻道/群組： 附件存放在 M365 儲存空間（SharePoint/OneDrive）。網路鉤子承載內容只包含 HTML stub，不包含實際檔案位元組。需要 Graph API 權限 才能下載頻道附件。
• 對於明確以檔案優先的傳送，請使用 action=upload-file 搭配 media / filePath / path；選用的 message 會成為隨附文字/註解，而 filename（或 title）會覆寫上傳名稱。

​

在群組聊天中傳送檔案

​

為什麼群組聊天需要 SharePoint

​

設定

1. 在 Entra ID (Azure AD) → App Registration 中新增 Graph API 權限：
   • Sites.ReadWrite.All（Application）- 將檔案上傳到 SharePoint。
   • Chat.Read.All（Application）- 選用，啟用每位使用者的分享連結。
2. 為租用戶授與管理員同意。
3. 取得你的 SharePoint 網站 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）

• 命令列介面：openclaw message poll --channel msteams --target conversation:<id> --poll-question "..." --poll-option "..." --poll-option "..."。
• 票數由閘道記錄在 state/openclaw.sqlite 下的 OpenClaw 外掛狀態 SQLite。
• 既有的 msteams-polls.json 檔案會由 openclaw doctor --fix 匯入，而不是由執行中的外掛匯入。
• 閘道必須保持在線才能記錄票數。
• 投票不會自動發布結果摘要，目前也還沒有投票結果命令列介面。

​

呈現卡片

{
  action: "send",
  channel: "msteams",
  target: "user:<id>",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello!" }],
  },
}

openclaw message send --channel msteams \
  --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hello","blocks":[{"type":"text","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:abc...@thread.tacv2" --message "Hello"

# Send a presentation card to a conversation
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}'

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

{
  action: "send",
  channel: "msteams",
  target: "conversation:19:abc...@thread.tacv2",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello" }],
  },
}

​

主動訊息

• 只有在使用者互動之後，才可能傳送主動訊息，因為 OpenClaw 會在該時間點儲存對話參照。
• 如需 dmPolicy 和允許清單閘控，請參閱 /gateway/configuration。

​

團隊與頻道 ID（常見陷阱）

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

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

• 團隊鍵 = /team/ 後方的路徑區段（URL 解碼後，例如 19:Bk4j...@thread.tacv2；較舊的租用戶可能顯示 @thread.skype，這也有效）。
• 頻道鍵 = /channel/ 後方的路徑區段（URL 解碼後）。
• 對於 OpenClaw 路由，請忽略 groupId 查詢參數。它是 Microsoft Entra 群組 ID，不是傳入 Teams 活動中使用的 Bot Framework 對話 ID。

​

私人頻道

1. 使用標準頻道進行機器人互動。
2. 使用私訊；使用者永遠可以直接傳訊息給機器人。
3. 使用 Graph API 進行歷史存取（需要 ChannelMessage.Read.All）。

​

疑難排解

​

常見問題

• 圖片未顯示在頻道中： 缺少 Graph 權限或管理員同意。重新安裝 Teams 應用程式，並完全結束/重新開啟 Teams。
• 頻道中沒有回應： 預設需要提及；設定 channels.msteams.requireMention=false，或依團隊/頻道設定。
• 版本不符（Teams 仍顯示舊資訊清單）： 移除 + 重新加入應用程式，並完全結束 Teams 以重新整理。
• 網路鉤子傳回 401 Unauthorized： 手動測試時若沒有 Azure JWT，這是預期情況；表示端點可連線，但驗證失敗。請使用 Azure Web Chat 正確測試。

​

資訊清單上傳錯誤

• 「Icon file cannot be empty」： 資訊清單參照了 0 位元組的圖示檔案。建立有效的 PNG 圖示（outline.png 為 32x32，color.png 為 192x192）。
• 「webApplicationInfo.Id already in use」： 應用程式仍安裝在其他團隊/聊天中。請先找到並解除安裝，或等待 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. 重新上傳應用程式，並在團隊/聊天中重新安裝。
3. 檢查你的組織管理員是否封鎖了 RSC 權限。
4. 確認你使用的是正確範圍：團隊使用 ChannelMessage.Read.Group，群組聊天使用 ChatMessage.Read.Chat。

​

參考資料

• 建立 Azure Bot - Azure Bot 設定指南
• Teams 開發者入口網站 - 建立/管理 Teams 應用程式
• Teams 應用程式資訊清單結構描述
• 使用 RSC 接收頻道訊息
• RSC 權限參考
• Teams 機器人檔案處理（頻道/群組需要 Graph）
• 主動傳訊
• @microsoft/teams.cli - 用於機器人管理的 Teams 命令列介面

​

相關

• 頻道總覽 - 所有支援的頻道
• 配對 - 私訊驗證與配對流程
• 群組 - 群組聊天行為與提及門檻
• 頻道路由 - 訊息的工作階段路由
• 安全性 - 存取模型與強化