​

Microsoft Teams (plugin)

“Hãy từ bỏ mọi hy vọng, hỡi những ai bước vào đây.”

​

Plugin bắt buộc

openclaw plugins install @openclaw/msteams

openclaw plugins install ./extensions/msteams

​

Thiết lập nhanh (cho người mới)

1. Cài plugin Microsoft Teams.
2. Tạo Azure Bot (App ID + client secret + tenant ID).
3. Cấu hình OpenClaw với các thông tin xác thực đó.
4. Mở /api/messages (mặc định cổng 3978) qua URL công khai hoặc tunnel.
5. Cài gói ứng dụng Teams và khởi động gateway.

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

​

Mục tiêu

• Giao tiếp với OpenClaw qua DM Teams, chat nhóm hoặc kênh.
• Giữ định tuyến xác định: phản hồi luôn quay lại đúng kênh đã nhận.
• Mặc định hành vi an toàn cho kênh (yêu cầu mention trừ khi cấu hình khác).

​

Ghi cấu hình

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

​

Kiểm soát truy cập (DMs + nhóm)

• Mặc định: channels.msteams.dmPolicy = "pairing". Unknown senders are ignored until approved.
• channels.msteams.allowFrom accepts AAD object IDs, UPNs, or display names. The wizard resolves names to IDs via Microsoft Graph when credentials allow.

• Default: channels.msteams.groupPolicy = "allowlist" (blocked unless you add groupAllowFrom). Use channels.defaults.groupPolicy to override the default when unset.
• channels.msteams.groupAllowFrom kiểm soát người gửi nào có thể kích hoạt trong chat nhóm/kênh (dự phòng về channels.msteams.allowFrom).
• Đặt groupPolicy: "open" để cho phép mọi thành viên (vẫn yêu cầu mention theo mặc định).
• Để không cho phép kênh nào, đặt channels.msteams.groupPolicy: "disabled".

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

• Giới hạn phản hồi nhóm/kênh bằng cách liệt kê teams và channels dưới channels.msteams.teams.
• Khóa có thể là team ID hoặc tên; khóa kênh có thể là conversation ID hoặc tên.
• Khi groupPolicy="allowlist" và có danh sách teams, chỉ các team/kênh được liệt kê mới được chấp nhận (yêu cầu mention).
• Trình cấu hình chấp nhận các mục Team/Channel và lưu giúp bạn.
• Khi khởi động, OpenClaw phân giải tên team/kênh và danh sách cho phép người dùng sang ID (khi Graph cho phép) và ghi log ánh xạ; các mục không phân giải được sẽ giữ nguyên như đã nhập.

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

​

Cách hoạt động

1. Cài plugin Microsoft Teams.
2. Tạo Azure Bot (App ID + secret + tenant ID).
3. Xây dựng gói ứng dụng Teams tham chiếu bot và bao gồm các quyền RSC bên dưới.
4. Tải lên/cài ứng dụng Teams vào một team (hoặc phạm vi cá nhân cho DM).
5. Cấu hình msteams trong ~/.openclaw/openclaw.json (hoặc biến môi trường) và khởi động gateway.
6. Gateway lắng nghe webhook Bot Framework trên /api/messages theo mặc định.

​

Thiết lập Azure Bot (Điều kiện tiên quyết)

​

Bước 1: Tạo Azure Bot

1. Vào Create Azure Bot
2. Điền tab Basics:

   Trường	Giá trị
   Tên bot	Tên bot của bạn, ví dụ openclaw-msteams (phải duy nhất)
   Gói đăng ký	Chọn subscription Azure
   Nhóm tài nguyên	Tạo mới hoặc dùng sẵn
   Bậc giá	Free cho dev/test
   Loại ứng dụng	Single Tenant (khuyến nghị - xem lưu ý bên dưới)
   Loại tạo	Create new Microsoft App ID

Thông báo ngừng hỗ trợ: Việc tạo bot đa tenant mới đã bị ngừng sau 2025-07-31. Use Single Tenant for new bots.

3. Nhấn Review + create → Create (chờ ~1-2 phút)

​

Bước 2: Lấy thông tin xác thực

1. Vào tài nguyên Azure Bot → Configuration
2. Sao chép Microsoft App ID → đây là appId của bạn
3. Nhấn Manage Password → vào App Registration
4. Trong Certificates & secrets → New client secret → sao chép Value → đây là appPassword
5. Vào Overview → sao chép Directory (tenant) ID → đây là tenantId

​

Bước 3: Cấu hình Messaging Endpoint

1. Trong Azure Bot → Configuration
2. Đặt Messaging endpoint thành URL webhook của bạn:
   • Production: https://your-domain.com/api/messages
   • Dev cục bộ: dùng tunnel (xem Phát triển cục bộ bên dưới)

​

Bước 4: Bật kênh Teams

1. Trong Azure Bot → Channels
2. Nhấn Microsoft Teams → Configure → Save
3. Chấp nhận Điều khoản dịch vụ

​

Phát triển cục bộ (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 (Thay thế)

1. Nhấn + New app
2. Điền thông tin cơ bản (tên, mô tả, thông tin nhà phát triển)
3. Vào App features → Bot
4. Chọn Enter a bot ID manually và dán Azure Bot App ID
5. Chọn phạm vi: Personal, Team, Group Chat
6. Nhấn Distribute → Download app package
7. Trong Teams: Apps → Manage your apps → Upload a custom app → chọn ZIP

​

Kiểm thử bot

1. Azure Portal → tài nguyên Azure Bot → Test in Web Chat
2. Gửi tin nhắn – bạn sẽ thấy phản hồi
3. Xác nhận endpoint webhook hoạt động trước khi cấu hình Teams

1. Cài ứng dụng Teams (sideload hoặc org catalog)
2. Tìm bot trong Teams và gửi DM
3. Kiểm tra log gateway để xem hoạt động đến

​

Thiết lập (tối thiểu, chỉ văn bản)

1. Cài plugin Microsoft Teams
   • Từ npm: openclaw plugins install @openclaw/msteams
   • Từ checkout cục bộ: openclaw plugins install ./extensions/msteams
2. Đăng ký bot
   • Tạo Azure Bot (xem trên) và ghi lại:
     • App ID
     • Client secret (App password)
     • Tenant ID (single-tenant)
3. Manifest ứng dụng Teams
   • Bao gồm mục bot với botId = <App ID>.
   • Phạm vi: personal, team, groupChat.
   • supportsFiles: true (bắt buộc cho xử lý tệp phạm vi cá nhân).
   • Thêm quyền RSC (bên dưới).
   • Tạo icon: outline.png (32x32) và color.png (192x192).
   • Nén cả ba tệp: manifest.json, outline.png, color.png.
4. Cấu hình OpenClaw
   {
     "msteams": {
       "enabled": true,
       "appId": "<APP_ID>",
       "appPassword": "<APP_PASSWORD>",
       "tenantId": "<TENANT_ID>",
       "webhook": { "port": 3978, "path": "/api/messages" }
     }
   }
   
   Bạn cũng có thể dùng biến môi trường thay cho khóa cấu hình:
   • MSTEAMS_APP_ID
   • MSTEAMS_APP_PASSWORD
   • MSTEAMS_TENANT_ID
5. Endpoint bot
   • Đặt Azure Bot Messaging Endpoint thành:
     • https://<host>:3978/api/messages (hoặc đường dẫn/cổng bạn chọn).
6. Chạy gateway
   • Kênh Teams tự khởi động khi plugin được cài và tồn tại cấu hình msteams với thông tin xác thực.

​

Ngữ cảnh lịch sử

• channels.msteams.historyLimit kiểm soát số lượng tin nhắn kênh/nhóm gần đây được gói vào prompt.
• Falls back to messages.groupChat.historyLimit. Set 0 to disable (default 50).
• DM history can be limited with channels.msteams.dmHistoryLimit (user turns). Ghi đè theo từng người dùng: channels.msteams.dms["<user_id>"].historyLimit.

​

Quyền RSC Teams hiện tại (Manifest)

• ChannelMessage.Read.Group (Application) - nhận mọi tin nhắn kênh không cần @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) - nhận mọi tin nhắn chat nhóm không cần @mention

​

Ví dụ Manifest Teams (đã lược bỏ)

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

​

Lưu ý manifest (các trường bắt buộc)

• bots[].botId phải khớp Azure Bot App ID.
• webApplicationInfo.id phải khớp Azure Bot App ID.
• bots[].scopes phải bao gồm các bề mặt bạn định dùng (personal, team, groupChat).
• bots[].supportsFiles: true là bắt buộc để xử lý tệp ở phạm vi cá nhân.
• authorization.permissions.resourceSpecific phải bao gồm đọc/gửi kênh nếu bạn muốn lưu lượng kênh.

​

Cập nhật ứng dụng hiện có

1. Cập nhật manifest.json với thiết lập mới
2. Tăng trường version (ví dụ 1.0.0 → 1.1.0)
3. Nén lại manifest với icon (manifest.json, outline.png, color.png)
4. Tải lên zip mới:
   • Tùy chọn A (Teams Admin Center): Teams Admin Center → Teams apps → Manage apps → tìm app → Upload new version
   • Tùy chọn B (Sideload): Trong Teams → Apps → Manage your apps → Upload a custom app
5. Với kênh team: Cài lại app trong từng team để quyền mới có hiệu lực
6. Thoát hoàn toàn và mở lại Teams (không chỉ đóng cửa sổ) để xóa cache metadata app

​

Khả năng: chỉ RSC vs Graph

​

Với chỉ Teams RSC (app đã cài, không có quyền Graph API)

• Đọc nội dung văn bản tin nhắn kênh.
• Gửi nội dung văn bản tin nhắn kênh.
• Nhận tệp đính kèm cá nhân (DM).

• Hình ảnh hoặc nội dung tệp trong kênh/nhóm (payload chỉ có stub HTML).
• Tải xuống tệp đính kèm lưu trong SharePoint/OneDrive.
• Đọc lịch sử tin nhắn (ngoài sự kiện webhook trực tiếp).

​

Với Teams RSC + quyền Microsoft Graph Application

• Tải nội dung được lưu trữ (ảnh dán trong tin nhắn).
• Tải tệp đính kèm lưu trong SharePoint/OneDrive.
• Đọc lịch sử tin nhắn kênh/chat qua Graph.

​

RSC vs Graph API

​

Media + lịch sử dùng Graph (bắt buộc cho kênh)

1. Trong Entra ID (Azure AD) App Registration, thêm quyền Microsoft Graph Application:
   • ChannelMessage.Read.All (tệp đính kèm kênh + lịch sử)
   • Chat.Read.All hoặc ChatMessage.Read.All (chat nhóm)
2. Cấp admin consent cho tenant.
3. Tăng manifest version của app Teams, tải lại và cài lại app trong Teams.
4. Thoát hoàn toàn và mở lại Teams để xóa cache metadata app.

​

Hết thời gian webhook

​

Hết thời gian webhook

• Gateway timeout
• Teams gửi lại tin nhắn (gây trùng lặp)
• Mất phản hồi

​

Định dạng

• Định dạng cơ bản hoạt động: đậm, nghiêng, code, liên kết
• Markdown phức tạp (bảng, danh sách lồng nhau) có thể không hiển thị đúng
• Adaptive Cards được hỗ trợ cho thăm dò ý kiến và gửi thẻ tùy ý (xem bên dưới)

​

Cấu hình

• channels.msteams.enabled: bật/tắt kênh.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: thông tin xác thực bot.
• channels.msteams.webhook.port (mặc định 3978)
• channels.msteams.webhook.path (mặc định /api/messages)
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (mặc định: pairing)
• 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.textChunkLimit: kích thước chia đoạn văn bản gửi ra.
• channels.msteams.chunkMode: length (mặc định) hoặc newline để chia theo dòng trống (ranh giới đoạn) trước khi chia theo độ dài.
• channels.msteams.mediaAllowHosts: danh sách cho phép host tệp đính kèm vào (mặc định là domain Microsoft/Teams).
• channels.msteams.mediaAuthAllowHosts: danh sách cho phép đính kèm header Authorization khi retry media (mặc định Graph + Bot Framework).
• channels.msteams.requireMention: yêu cầu @mention trong kênh/nhóm (mặc định true).
• channels.msteams.replyStyle: thread | top-level (xem Kiểu trả lời).
• channels.msteams.teams.<teamId>.replyStyle: per-team override.
• channels.msteams.teams.<teamId>.requireMention: per-team override.
• channels.msteams.teams.<teamId>.tools: default per-team tool policy overrides (allow/deny/alsoAllow) used when a channel override is missing.
• channels.msteams.teams.<teamId>.toolsBySender: default per-team per-sender tool policy overrides ("*" wildcard supported).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: per-channel override.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: per-channel override.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: per-channel tool policy overrides (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: per-channel per-sender tool policy overrides ("*" wildcard supported).
• channels.msteams.sharePointSiteId: SharePoint site ID để tải tệp lên trong chat nhóm/kênh (xem Gửi tệp trong chat nhóm).

​

Định tuyến & Phiên

• Khóa phiên theo định dạng tác tử chuẩn (xem /concepts/session):
  • Tin nhắn trực tiếp dùng chung phiên chính (agent:<agentId>:<mainKey>).
  • Tin nhắn kênh/nhóm dùng conversation id:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Kiểu trả lời: Threads vs Posts

• thread trong kênh kiểu Threads → trả lời bị lồng khó chịu
• top-level trong kênh kiểu Posts → trả lời thành bài đăng cấp cao riêng lẻ

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

​

Tệp đính kèm & Hình ảnh

• DMs: Hình ảnh và tệp đính kèm hoạt động qua API tệp bot Teams.
• Channels/groups: Attachments live in M365 storage (SharePoint/OneDrive). The webhook payload only includes an HTML stub, not the actual file bytes. Graph API permissions are required to download channel attachments.

​

Gửi tệp trong chat nhóm

​

Vì sao chat nhóm cần SharePoint

​

Thiết lập

1. Thêm quyền Graph API trong Entra ID (Azure AD) → App Registration:
   • Sites.ReadWrite.All (Application) - tải tệp lên SharePoint
   • Chat.Read.All (Application) - tùy chọn, bật liên kết chia sẻ theo người dùng
2. Cấp admin consent cho tenant.
3. Lấy 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. Cấu hình OpenClaw:
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Hành vi chia sẻ

​

Hành vi dự phòng

​

Vị trí lưu tệp

​

Thăm dò ý kiến (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> ...
• Phiếu bầu được gateway ghi trong ~/.openclaw/msteams-polls.json.
• Gateway phải luôn online để ghi nhận phiếu.
• Thăm dò chưa tự động đăng tổng kết kết quả (xem tệp lưu trữ nếu cần).

​

Adaptive Cards (tùy ý)

{
  "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!"}]}'

​

Định dạng đích

# 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" }]
  }
}

​

Nhắn tin chủ động

• Nhắn tin chủ động chỉ có thể thực hiện sau khi người dùng đã tương tác, vì lúc đó chúng tôi lưu conversation reference.
• Xem /gateway/configuration cho dmPolicy và điều kiện danh sách cho phép.

​

Team và Channel ID (Lỗi thường gặp)

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 = đoạn đường dẫn sau /team/ (URL-decoded, ví dụ 19:[email protected])
• Channel ID = đoạn đường dẫn sau /channel/ (URL-decoded)
• Bỏ qua tham số truy vấn groupId

​

Kênh riêng tư

1. Dùng kênh chuẩn cho tương tác bot
2. Dùng DM – người dùng luôn có thể nhắn trực tiếp cho bot
3. Dùng Graph API cho truy cập lịch sử (yêu cầu ChannelMessage.Read.All)

​

Sự cố thường gặp

​

Sự cố thường gặp

• Images not showing in channels: Graph permissions or admin consent missing. Reinstall the Teams app and fully quit/reopen Teams.
• Không có phản hồi trong kênh: Mặc định yêu cầu mention; đặt channels.msteams.requireMention=false hoặc cấu hình theo team/kênh.
• Lệch phiên bản (Teams vẫn hiển thị manifest cũ): Gỡ + thêm lại app và thoát/mở lại Teams để làm mới.
• 401 Unauthorized from webhook: Expected when testing manually without Azure JWT - means endpoint is reachable but auth failed. Use Azure Web Chat to test properly.

​

Lỗi tải manifest

• “Icon file cannot be empty”: The manifest references icon files that are 0 bytes. Create valid PNG icons (32x32 for outline.png, 192x192 for color.png).
• “webApplicationInfo.Id already in use”: The app is still installed in another team/chat. Find and uninstall it first, or wait 5-10 minutes for propagation.
• “Something went wrong” khi tải: Thử tải qua https://admin.teams.microsoft.com, mở DevTools (F12) → tab Network, kiểm tra response body để biết lỗi thực.
• Sideload thất bại: Thử “Upload an app to your org’s app catalog” thay vì “Upload a custom app” – thường vượt qua hạn chế sideload.

​

Quyền RSC không hoạt động

1. Xác minh webApplicationInfo.id khớp chính xác App ID của bot
2. Tải lại app và cài lại trong team/chat
3. Kiểm tra admin org có chặn quyền RSC không
4. Xác nhận dùng đúng phạm vi: ChannelMessage.Read.Group cho teams, ChatMessage.Read.Chat cho chat nhóm

​

Tham khảo

• Create Azure Bot - Hướng dẫn thiết lập Azure Bot
• Teams Developer Portal - tạo/quản lý ứng dụng Teams
• Teams app manifest schema
• Receive channel messages with RSC
• RSC permissions reference
• Teams bot file handling (kênh/nhóm cần Graph)
• Proactive messaging