​

Microsoft Teams (plugin)

“Abandon all hope, ye who enter here.”

​

Plugin required

openclaw plugins install @openclaw/msteams

openclaw plugins install ./extensions/msteams

​

Quick setup (beginner)

1. Microsoft Teams plugin을 설치합니다.
2. Azure Bot를 생성합니다. App ID, client secret, tenant ID가 필요합니다.
3. 해당 credential로 OpenClaw를 구성합니다.
4. 공개 URL 또는 tunnel을 통해 /api/messages(기본 port 3978)를 노출합니다.
5. Teams app package를 설치하고 gateway를 시작합니다.

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

​

Goals

• Teams DM, group chat, channel에서 OpenClaw와 대화할 수 있게 합니다.
• routing은 항상 deterministic하게 유지되어, reply가 들어온 채널로 다시 돌아갑니다.
• 별도 설정이 없으면 안전한 channel behavior를 기본값으로 사용합니다. 즉, mentions가 필요합니다.

​

Config writes

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

​

Access control (DMs + groups)

• 기본값: channels.msteams.dmPolicy = "pairing". 승인 전까지 unknown sender는 무시됩니다.
• channels.msteams.allowFrom에는 안정적인 AAD object ID 사용을 권장합니다.
• UPN이나 display name은 바뀔 수 있으므로 direct matching은 기본 비활성화이며, channels.msteams.dangerouslyAllowNameMatching: true일 때만 켤 수 있습니다.
• credential이 허용되면 wizard가 Microsoft Graph를 통해 이름을 ID로 resolve할 수 있습니다.

• 기본값: channels.msteams.groupPolicy = "allowlist" 입니다. groupAllowFrom을 추가하기 전에는 차단됩니다. unset일 때 기본값을 바꾸려면 channels.defaults.groupPolicy를 사용하세요.
• channels.msteams.groupAllowFrom은 group chat/channel에서 어떤 sender가 bot을 트리거할 수 있는지 제어합니다. unset이면 channels.msteams.allowFrom으로 fallback합니다.
• groupPolicy: "open"이면 모든 member를 허용합니다. 그래도 기본적으로 mention gating은 유지됩니다.
• 아무 channel도 허용하지 않으려면 channels.msteams.groupPolicy: "disabled"를 사용합니다.

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["user@org.com"],
    },
  },
}

• channels.msteams.teams 아래에 team과 channel을 나열해 group/channel reply 범위를 제한할 수 있습니다.
• key는 team ID 또는 이름, channel key는 conversation ID 또는 이름이 될 수 있습니다.
• groupPolicy="allowlist"이고 teams allowlist가 있으면, 나열된 team/channel만 mention-gated로 허용됩니다.
• configure wizard는 Team/Channel 항목을 받아 자동 저장할 수 있습니다.
• startup 시 OpenClaw는 team/channel 이름과 user allowlist 이름을 ID로 resolve하고 그 매핑을 로그에 남깁니다. resolve되지 않은 항목은 입력한 값을 유지합니다.

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

​

How it works

1. Microsoft Teams plugin을 설치합니다.
2. Azure Bot를 만들고 App ID, secret, tenant ID를 확인합니다.
3. bot을 참조하고 아래 RSC permission을 포함하는 Teams app package를 만듭니다.
4. Teams app을 팀에 업로드하거나 personal scope에 설치합니다.
5. ~/.openclaw/openclaw.json 또는 env vars에 msteams를 구성하고 gateway를 시작합니다.
6. gateway는 기본적으로 /api/messages에서 Bot Framework webhook traffic을 수신합니다.

​

Azure Bot Setup (Prerequisites)

​

Step 1: Create Azure Bot

1. Create Azure Bot으로 이동합니다.
2. Basics 탭을 채웁니다.

   Field	Value
   Bot handle	봇 이름. 예: openclaw-msteams (고유해야 함)
   Subscription	사용할 Azure subscription 선택
   Resource group	새로 만들거나 기존 항목 사용
   Pricing tier	개발/테스트에는 Free
   Type of App	Single Tenant 권장
   Creation type	Create new Microsoft App ID

Deprecation notice: 새 multi-tenant bot 생성은 2025-07-31 이후 deprecated되었습니다. 새 bot은 Single Tenant를 사용하세요.

3. Review + create → Create를 클릭하고 1~2분 정도 기다립니다.

​

Step 2: Get Credentials

1. Azure Bot resource에서 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로 설정합니다.
   • Production: https://your-domain.com/api/messages
   • Local dev: 아래 Local Development 참고

​

Step 4: Enable Teams Channel

1. Azure Bot → Channels
2. Microsoft Teams → Configure → Save
3. Terms of Service를 수락합니다.

​

Local Development (Tunneling)

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

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

​

Teams Developer Portal (Alternative)

1. + New app 클릭
2. 기본 정보 입력 (name, description, developer info)
3. App features → Bot
4. Enter a bot ID manually를 선택하고 Azure Bot App ID를 붙여넣기
5. scope 체크: 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 resource에서 Test in Web Chat로 이동합니다.
2. 메시지를 보내고 응답을 확인합니다.
3. Teams 설정 전에 webhook endpoint가 정상인지 확인할 수 있습니다.

1. Teams app을 설치합니다. (sideload 또는 org catalog)
2. Teams에서 bot을 찾아 DM을 보냅니다.
3. gateway log에서 inbound activity를 확인합니다.

​

Setup (minimal text-only)

1. Install the Microsoft Teams plugin
   • npm에서 설치: openclaw plugins install @openclaw/msteams
   • local checkout에서 설치: openclaw plugins install ./extensions/msteams
2. Bot registration
   • 위 설명대로 Azure Bot를 만들고 다음 정보를 확보합니다.
     • App ID
     • Client secret (App password)
     • Tenant ID (single-tenant)
3. Teams app manifest
   • bot entry에 botId = <App ID>를 넣습니다.
   • scope: personal, team, groupChat
   • supportsFiles: true (personal scope file handling에 필요)
   • 아래 RSC permission 추가
   • icon 생성: outline.png (32x32), color.png (192x192)
   • manifest.json, outline.png, color.png 세 파일을 함께 ZIP으로 묶습니다.
4. Configure OpenClaw
   복사

   AI에게 묻기

   {
     "msteams": {
       "enabled": true,
       "appId": "<APP_ID>",
       "appPassword": "<APP_PASSWORD>",
       "tenantId": "<TENANT_ID>",
       "webhook": { "port": 3978, "path": "/api/messages" }
     }
   }
   
   config key 대신 env vars도 사용할 수 있습니다.
   • MSTEAMS_APP_ID
   • MSTEAMS_APP_PASSWORD
   • MSTEAMS_TENANT_ID
5. Bot endpoint
   • Azure Bot Messaging Endpoint를 다음처럼 설정합니다.
     • https://<host>:3978/api/messages
     • 또는 사용 중인 path/port
6. Run the gateway
   • plugin이 설치되어 있고 credential이 포함된 msteams config가 있으면 Teams channel은 자동으로 시작됩니다.

​

History context

• channels.msteams.historyLimit은 최근 channel/group message 몇 개를 prompt에 감쌀지 제어합니다.
• messages.groupChat.historyLimit로 fallback합니다. 0이면 비활성화됩니다. 기본값은 50입니다.
• DM history는 channels.msteams.dmHistoryLimit로 제한할 수 있습니다. 사용자별 override는 channels.msteams.dms["<user_id>"].historyLimit를 사용합니다.

​

Current Teams RSC Permissions (Manifest)

• ChannelMessage.Read.Group (Application) - @mention 없이도 모든 channel message 수신
• 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 없이도 모든 group chat message 수신

​

Example Teams Manifest (redacted)

{
  "$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 caveats (must-have fields)

• bots[].botId는 Azure Bot App ID와 반드시 일치해야 합니다.
• webApplicationInfo.id도 Azure Bot App ID와 반드시 일치해야 합니다.
• bots[].scopes에는 사용할 surface (personal, team, groupChat)가 포함되어야 합니다.
• bots[].supportsFiles: true는 personal scope file handling에 필요합니다.
• channel traffic을 원하면 authorization.permissions.resourceSpecific에 channel read/send 권한이 있어야 합니다.

​

Updating an existing app

1. manifest.json을 새 설정으로 갱신합니다.
2. version 필드를 증가시킵니다. 예: 1.0.0 → 1.1.0
3. manifest.json, outline.png, color.png를 다시 ZIP으로 묶습니다.
4. 새 ZIP을 업로드합니다.
   • Option A (Teams Admin Center): Teams Admin Center → Teams apps → Manage apps → 앱 선택 → Upload new version
   • Option B (Sideload): Teams → Apps → Manage your apps → Upload a custom app
5. team channel의 경우 새 permission이 반영되도록 각 team에 app을 다시 설치합니다.
6. Teams app metadata cache를 비우기 위해 Teams를 완전히 종료한 뒤 다시 실행합니다.

​

Capabilities: RSC only vs Graph

​

With Teams RSC only (app installed, no Graph API permissions)

• channel message text 내용 읽기
• channel message text 전송
• personal (DM) file attachment 수신

• channel/group의 image 또는 file contents (payload에는 HTML stub만 포함)
• SharePoint/OneDrive에 저장된 attachment 다운로드
• live webhook event를 넘는 과거 message history 조회

​

With Teams RSC + Microsoft Graph Application permissions

• hosted contents 다운로드 (메시지에 붙여넣은 image 등)
• SharePoint/OneDrive의 file attachment 다운로드
• Graph를 통한 channel/chat message history 조회

​

RSC vs Graph API

​

Graph-enabled media + history (required for channels)

1. Entra ID (Azure AD) App Registration에서 Microsoft Graph Application permissions를 추가합니다.
   • ChannelMessage.Read.All (channel attachment + history)
   • Chat.Read.All 또는 ChatMessage.Read.All (group chats)
2. tenant에 대해 Grant admin consent를 수행합니다.
3. Teams app manifest version을 올리고, 다시 업로드하고, Teams에서 app을 재설치합니다.
4. cached app metadata를 지우기 위해 Teams를 완전히 종료 후 재실행합니다.

​

Known Limitations

​

Webhook timeouts

• Gateway timeout
• Teams의 message retry로 인한 duplicate
• dropped reply

​

Formatting

• 기본 formatting은 동작: bold, italic, code, links
• 복잡한 markdown(table, nested list 등)은 올바르게 렌더링되지 않을 수 있음
• poll과 arbitrary card send에는 Adaptive Cards를 사용합니다.

​

Configuration

• channels.msteams.enabled: 채널 활성화/비활성화
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: bot credentials
• channels.msteams.webhook.port (default 3978)
• channels.msteams.webhook.path (default /api/messages)
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (default: pairing)
• channels.msteams.allowFrom: DM allowlist (AAD object ID 권장). Graph access가 가능하면 wizard가 setup 중 이름을 ID로 resolve합니다.
• channels.msteams.dangerouslyAllowNameMatching: mutable UPN/display-name matching을 다시 켜는 break-glass toggle
• channels.msteams.textChunkLimit: outbound text chunk 크기
• channels.msteams.chunkMode: length (default) 또는 newline. 빈 줄 단위로 먼저 나눈 뒤 길이 기준 chunking으로 fallback
• channels.msteams.mediaAllowHosts: inbound attachment host allowlist (default는 Microsoft/Teams domain)
• channels.msteams.mediaAuthAllowHosts: media retry 시 Authorization header를 붙일 host allowlist (기본은 Graph + Bot Framework host)
• channels.msteams.requireMention: channel/group에서 @mention 필요 여부 (default true)
• channels.msteams.replyStyle: thread | top-level (아래 Reply Style 참고)
• channels.msteams.teams.<teamId>.replyStyle: team별 override
• channels.msteams.teams.<teamId>.requireMention: team별 override
• channels.msteams.teams.<teamId>.tools: channel override가 없을 때 적용되는 team-level tool policy override (allow/deny/alsoAllow)
• channels.msteams.teams.<teamId>.toolsBySender: team-level per-sender tool policy override ("*" wildcard 지원)
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: channel별 override
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: channel별 override
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: channel별 tool policy override (allow/deny/alsoAllow)
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: channel별 per-sender tool policy override ("*" wildcard 지원)
• toolsBySender key는 명시적 prefix 사용 권장: id:, e164:, username:, name: (legacy unprefixed key는 id:로만 매핑)
• channels.msteams.sharePointSiteId: group chat/channel에서 file upload에 사용할 SharePoint site ID (아래 Sending files in group chats 참고)

​

Routing & Sessions

• session key는 표준 agent 형식을 따릅니다. 자세한 내용은 /concepts/session을 참고하세요.
  • direct message는 main session을 공유합니다 (agent:<agentId>:<mainKey>)
  • channel/group message는 conversation id를 사용합니다.
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Reply Style: Threads vs Posts

• Threads-style channel에서 thread를 쓰면 reply가 어색하게 중첩되어 보임
• Posts-style channel에서 top-level을 쓰면 reply가 thread 안이 아니라 새로운 top-level post처럼 보임

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

​

Attachments & Images

• DMs: Teams bot file API를 통해 image와 file attachment가 동작합니다.
• Channels/groups: attachment는 M365 storage(SharePoint/OneDrive)에 저장됩니다. webhook payload에는 실제 file bytes가 아니라 HTML stub만 포함됩니다. channel attachment를 다운로드하려면 Graph API permissions가 필요합니다.

​

Sending files in group chats

​

Why group chats need SharePoint

​

Setup

1. Entra ID (Azure AD) → App Registration에서 Graph API permissions를 추가합니다.
   • Sites.ReadWrite.All (Application) - SharePoint file upload
   • Chat.Read.All (Application) - 선택 사항, user별 sharing link 가능
2. tenant에 대해 Grant admin consent를 수행합니다.
3. SharePoint site ID를 가져옵니다.
   복사

   AI에게 묻기

   # 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: "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에 설정합니다.
   복사

   AI에게 묻기

   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Sharing behavior

​

Fallback behavior

​

Files stored location

​

Polls (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> ...
• 투표 결과는 gateway가 ~/.openclaw/msteams-polls.json에 기록합니다.
• 투표 기록을 남기려면 gateway가 계속 online 상태여야 합니다.
• 아직 결과 요약을 자동 게시하지는 않습니다. 필요하면 store file을 직접 확인하세요.

​

Adaptive Cards (arbitrary)

{
  "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:abc...@thread.tacv2" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'

​

Target formats

# 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 an Adaptive Card to a conversation
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --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:abc...@thread.tacv2",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello" }]
  }
}

​

Proactive messaging

• proactive message는 user가 먼저 한 번 상호작용한 뒤에만 가능합니다. 그때 conversation reference를 저장하기 때문입니다.
• dmPolicy와 allowlist gating은 /gateway/configuration을 참고하세요.

​

Team and Channel IDs (Common Gotcha)

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/ 뒤 path segment (URL-decoded, 예: 19:Bk4j...@thread.tacv2)
• Channel ID = /channel/ 뒤 path segment (URL-decoded)
• groupId query parameter는 무시

​

Private Channels

1. bot interaction은 standard channel을 사용
2. DM 사용 - 사용자는 언제든 bot에게 직접 메시지 가능
3. Graph API로 historical access 사용 (ChannelMessage.Read.All 필요)

​

Troubleshooting

​

Common issues

• 채널에서 이미지가 보이지 않음: Graph permission 또는 admin consent가 빠진 경우가 많습니다. Teams app을 재설치하고 Teams를 완전히 종료 후 다시 실행하세요.
• 채널에서 응답이 없음: 기본값으로 mention이 필요합니다. channels.msteams.requireMention=false 또는 team/channel별 override를 설정하세요.
• Version mismatch (Teams에 옛 manifest가 계속 보임): app을 제거 후 다시 추가하고 Teams를 완전히 종료해 cache를 비우세요.
• Webhook의 401 Unauthorized: Azure JWT 없이 수동 테스트하면 정상적으로 보이는 현상입니다. endpoint는 도달 가능하지만 auth가 실패한 상태입니다. 검증은 Azure Web Chat으로 하세요.

​

Manifest upload errors

• “Icon file cannot be empty”: manifest가 참조하는 icon file이 0 byte입니다. 유효한 PNG icon을 생성하세요. (outline.png 32x32, color.png 192x192)
• “webApplicationInfo.Id already in use”: app이 다른 team/chat에 아직 설치되어 있습니다. 먼저 제거하거나 5~10분 정도 propagation을 기다리세요.
• “Something went wrong” on upload: https://admin.teams.microsoft.com에서 업로드하고, 브라우저 DevTools(F12) → Network 탭에서 실제 오류 응답 본문을 확인하세요.
• Sideload failing: “Upload a custom app” 대신 “Upload an app to your org’s app catalog”를 시도하세요. sideload 제한을 우회하는 경우가 많습니다.

​

RSC permissions not working

1. webApplicationInfo.id가 bot의 App ID와 정확히 일치하는지 확인
2. app을 다시 업로드하고 team/chat에 재설치
3. 조직 admin이 RSC permission을 차단하지 않았는지 확인
4. scope가 맞는지 확인: team에는 ChannelMessage.Read.Group, group chat에는 ChatMessage.Read.Chat

​

References

• Create Azure Bot - Azure Bot setup guide
• Teams Developer Portal - Teams app 생성/관리
• Teams app manifest schema
• Receive channel messages with RSC
• RSC permissions reference
• Teams bot file handling (channel/group에는 Graph 필요)
• Proactive messaging