Microsoft Teams (플러그인)

"여기에 들어오는 모든 이여, 희망을 버리라."

업데이트: 2026-01-21

상태: 텍스트 + DM 첨부파일이 지원됩니다. 채널/그룹 파일 전송은 sharePointSiteId + Graph 권한이 필요합니다(그룹 채팅에서 파일 전송 참조). 투표는 Adaptive Card를 통해 전송됩니다.

플러그인 필요

Microsoft Teams는 플러그인으로 제공되며 코어 설치에 번들되지 않습니다.

중대한 변경사항 (2026.1.15): MS Teams가 코어에서 분리되었습니다. 사용하는 경우 플러그인을 설치해야 합니다.

설명: 코어 설치를 가볍게 유지하고 MS Teams 의존성을 독립적으로 업데이트할 수 있습니다.

CLI를 통해 설치 (npm 레지스트리):

openclaw plugins install @openclaw/msteams

로컬 체크아웃 (git 저장소에서 실행 시):

openclaw plugins install ./extensions/msteams

구성/온보딩 중에 Teams를 선택하고 git 체크아웃이 감지되면, OpenClaw가 자동으로 로컬 설치 경로를 제공합니다.

자세한 내용: Plugins

빠른 설정 (초보자용)

Microsoft Teams 플러그인을 설치합니다.
Azure Bot을 생성합니다(App ID + client secret + tenant ID).
해당 자격 증명으로 OpenClaw를 구성합니다.
/api/messages를 공개 URL 또는 터널을 통해 노출합니다(기본 포트 3978).
Teams 앱 패키지를 설치하고 Gateway를 시작합니다.

최소 설정:

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

참고: 그룹 채팅은 기본적으로 차단됩니다(channels.msteams.groupPolicy: "allowlist"). 그룹 응답을 허용하려면 channels.msteams.groupAllowFrom을 설정하세요(또는 groupPolicy: "open"을 사용하여 모든 멤버 허용, 멘션 게이팅).

목표

Teams DM, 그룹 채팅 또는 채널을 통해 OpenClaw와 대화합니다.
라우팅을 결정론적으로 유지합니다: 응답은 항상 도착한 채널로 돌아갑니다.
기본적으로 안전한 채널 동작(다르게 구성하지 않는 한 멘션 필요).

설정 쓰기

기본적으로 Microsoft Teams는 /config set|unset으로 트리거된 설정 업데이트 쓰기가 허용됩니다(commands.config: true 필요).

비활성화:

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

접근 제어 (DM + 그룹)

DM 접근

기본값: channels.msteams.dmPolicy = "pairing". 알 수 없는 발신자는 승인될 때까지 무시됩니다.
channels.msteams.allowFrom은 AAD 객체 ID, UPN 또는 표시 이름을 허용합니다. 마법사는 자격 증명이 허용하는 경우 Microsoft Graph를 통해 이름을 ID로 해석합니다.

그룹 접근

기본값: channels.msteams.groupPolicy = "allowlist" (groupAllowFrom을 추가하지 않는 한 차단됨). 설정되지 않은 경우 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 아래에 팀과 채널을 나열하여 그룹/채널 응답 범위를 지정합니다.
키는 팀 ID 또는 이름일 수 있으며, 채널 키는 대화 ID 또는 이름일 수 있습니다.
groupPolicy="allowlist"이고 팀 허용목록이 있는 경우, 나열된 팀/채널만 수락됩니다(멘션 게이팅).
구성 마법사는 Team/Channel 항목을 허용하고 저장합니다.
시작 시, OpenClaw는 팀/채널 및 사용자 허용목록 이름을 ID로 해석하고(Graph 권한이 허용하는 경우) 매핑을 로깅합니다. 해석되지 않은 항목은 입력한 그대로 유지됩니다.

예시:

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

작동 방식

Microsoft Teams 플러그인을 설치합니다.
Azure Bot을 생성합니다(App ID + secret + tenant ID).
아래의 RSC 권한을 포함하는 봇을 참조하는 Teams 앱 패키지를 빌드합니다.
Teams 앱을 팀에 업로드/설치합니다(또는 DM을 위한 개인 범위).
~/.openclaw/openclaw.json(또는 환경 변수)에서 msteams를 구성하고 Gateway를 시작합니다.
Gateway는 기본적으로 /api/messages에서 Bot Framework webhook 트래픽을 수신합니다.

Azure Bot 설정 (사전 요구사항)

OpenClaw를 구성하기 전에 Azure Bot 리소스를 생성해야 합니다.

1단계: Azure Bot 생성

Azure Bot 생성으로 이동

Basics 탭 작성:

필드	값
Bot handle	봇 이름, 예: openclaw-msteams (고유해야 함)
Subscription	Azure 구독 선택
Resource group	새로 만들거나 기존 사용
Pricing tier	개발/테스트용 Free
Type of App	Single Tenant (권장 - 아래 참고 참조)
Creation type	Create new Microsoft App ID

폐기 공지: 새 다중 테넌트 봇 생성은 2025-07-31 이후 폐기되었습니다. 새 봇에는 Single Tenant를 사용하세요.

Review + create → Create 클릭 (~1-2분 대기)

2단계: 자격 증명 가져오기

Azure Bot 리소스 → Configuration으로 이동
Microsoft App ID 복사 → 이것이 appId입니다
Manage Password 클릭 → App Registration으로 이동
Certificates & secrets → New client secret → Value 복사 → 이것이 appPassword입니다
Overview로 이동 → Directory (tenant) ID 복사 → 이것이 tenantId입니다

3단계: 메시징 엔드포인트 구성

Azure Bot → Configuration에서
Messaging endpoint를 webhook URL로 설정:
- 프로덕션: https://your-domain.com/api/messages
- 로컬 개발: 터널 사용 (아래 로컬 개발 참조)

4단계: Teams 채널 활성화

Azure Bot → Channels에서
Microsoft Teams 클릭 → Configure → Save
서비스 약관 승인

로컬 개발 (터널링)

Teams는 localhost에 접근할 수 없습니다. 로컬 개발을 위해 터널을 사용하세요:

옵션 A: ngrok

ngrok http 3978
# https URL 복사, 예: https://abc123.ngrok.io
# 메시징 엔드포인트를 다음으로 설정: https://abc123.ngrok.io/api/messages

옵션 B: Tailscale Funnel

tailscale funnel 3978
# Tailscale funnel URL을 메시징 엔드포인트로 사용

Teams 개발자 포털 (대안)

manifest ZIP을 수동으로 생성하는 대신 Teams 개발자 포털을 사용할 수 있습니다:

+ New app 클릭
기본 정보 작성 (이름, 설명, 개발자 정보)
App features → Bot으로 이동
Enter a bot ID manually 선택 후 Azure Bot App ID 붙여넣기
범위 체크: Personal, Team, Group Chat
Distribute → Download app package 클릭
Teams에서: Apps → Manage your apps → Upload a custom app → ZIP 선택

JSON manifest를 수동으로 편집하는 것보다 종종 더 쉽습니다.

봇 테스트

옵션 A: Azure Web Chat (webhook 먼저 검증)

Azure Portal → Azure Bot 리소스 → Test in Web Chat
메시지 전송 - 응답을 받아야 합니다
Teams 설정 전에 webhook 엔드포인트가 작동하는지 확인합니다

옵션 B: Teams (앱 설치 후)

Teams 앱 설치 (사이드로드 또는 조직 카탈로그)
Teams에서 봇을 찾아 DM 전송
들어오는 활동에 대한 Gateway 로그 확인

설정 (최소 텍스트 전용)

Microsoft Teams 플러그인 설치
- npm에서: openclaw plugins install @openclaw/msteams
- 로컬 체크아웃에서: openclaw plugins install ./extensions/msteams
봇 등록
- Azure Bot을 생성하고(위 참조) 다음을 기록합니다:
  - App ID
  - Client secret (App password)
  - Tenant ID (단일 테넌트)
Teams 앱 manifest
- botId = <App ID>인 bot 항목을 포함합니다.
- 범위: personal, team, groupChat.
- supportsFiles: true (개인 범위 파일 처리에 필요).
- RSC 권한 추가 (아래 참조).
- 아이콘 생성: outline.png (32x32) 및 color.png (192x192).
- 세 파일을 함께 압축: manifest.json, outline.png, color.png.

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

봇 엔드포인트
- Azure Bot Messaging Endpoint를 다음으로 설정:
  - https://<host>:3978/api/messages (또는 선택한 경로/포트).
Gateway 실행
- 플러그인이 설치되고 자격 증명이 있는 msteams 설정이 있으면 Teams 채널이 자동으로 시작됩니다.

히스토리 컨텍스트

channels.msteams.historyLimit은 프롬프트에 래핑되는 최근 채널/그룹 메시지 수를 제어합니다.
messages.groupChat.historyLimit로 폴백합니다. 비활성화하려면 0으로 설정합니다(기본값 50).
DM 히스토리는 channels.msteams.dmHistoryLimit(사용자 턴)로 제한할 수 있습니다. 사용자별 재정의: channels.msteams.dms["<user_id>"].historyLimit.

현재 Teams RSC 권한 (Manifest)

이들은 Teams 앱 manifest에 있는 기존 resourceSpecific 권한입니다. 앱이 설치된 팀/채팅 내에서만 적용됩니다.

채널용 (팀 범위):

ChannelMessage.Read.Group (Application) - @멘션 없이 모든 채널 메시지 수신
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) - @멘션 없이 모든 그룹 채팅 메시지 수신

Teams Manifest 예시 (편집됨)

필수 필드가 포함된 최소, 유효한 예시입니다. ID와 URL을 교체하세요.

{
  "$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는 채널 트래픽을 원하는 경우 채널 read/send를 포함해야 합니다.

기존 앱 업데이트

이미 설치된 Teams 앱을 업데이트하려면(예: RSC 권한 추가):

새 설정으로 manifest.json 업데이트
version 필드 증가 (예: 1.0.0 → 1.1.0)
아이콘과 함께 manifest 재압축 (manifest.json, outline.png, color.png)
새 zip 업로드:
- 옵션 A (Teams 관리 센터): Teams 관리 센터 → Teams 앱 → 앱 관리 → 앱 찾기 → 새 버전 업로드
- 옵션 B (사이드로드): Teams → Apps → Manage your apps → Upload a custom app
팀 채널의 경우: 새 권한이 적용되도록 각 팀에서 앱을 재설치
Teams 완전히 종료 후 재시작 (창만 닫는 것이 아님)하여 캐시된 앱 메타데이터 지우기

기능: RSC만 vs Graph

Teams RSC만 사용 시 (앱 설치됨, Graph API 권한 없음)

작동:

채널 메시지 텍스트 콘텐츠 읽기.
채널 메시지 텍스트 콘텐츠 전송.
개인 (DM) 파일 첨부파일 수신.

작동하지 않음:

채널/그룹 이미지 또는 파일 콘텐츠 (페이로드에는 HTML stub만 포함).
SharePoint/OneDrive에 저장된 첨부파일 다운로드.
메시지 히스토리 읽기 (실시간 webhook 이벤트 이상).

Teams RSC + Microsoft Graph Application 권한 사용 시

추가:

호스팅된 콘텐츠 다운로드 (메시지에 붙여넣은 이미지).
SharePoint/OneDrive에 저장된 파일 첨부파일 다운로드.
Graph를 통한 채널/채팅 메시지 히스토리 읽기.

RSC vs Graph API

기능	RSC 권한	Graph API
실시간 메시지	Yes (webhook을 통해)	No (폴링만)
과거 메시지	No	Yes (히스토리 쿼리 가능)
설정 복잡도	앱 manifest만	관리자 동의 + 토큰 플로우 필요
오프라인 작동	No (실행 중이어야 함)	Yes (언제든지 쿼리 가능)

결론: RSC는 실시간 수신용이고, Graph API는 과거 접근용입니다. 오프라인 중 누락된 메시지를 따라잡으려면 ChannelMessage.Read.All이 있는 Graph API가 필요합니다(관리자 동의 필요).

Graph 활성화 미디어 + 히스토리 (채널에 필요)

채널에서 이미지/파일이 필요하거나 메시지 히스토리를 가져오려면, Microsoft Graph 권한을 활성화하고 관리자 동의를 부여해야 합니다.

Entra ID (Azure AD) App Registration에서 Microsoft Graph Application 권한 추가:
- ChannelMessage.Read.All (채널 첨부파일 + 히스토리)
- Chat.Read.All 또는 ChatMessage.Read.All (그룹 채팅)
테넌트에 대한 관리자 동의 부여.
Teams 앱 manifest 버전 증가, 재업로드, Teams에서 앱 재설치.
Teams 완전히 종료 후 재시작하여 캐시된 앱 메타데이터 지우기.

알려진 제한사항

Webhook 타임아웃

Teams는 HTTP webhook을 통해 메시지를 전달합니다. 처리 시간이 너무 오래 걸리면(예: 느린 LLM 응답) 다음이 발생할 수 있습니다:

Gateway 타임아웃
Teams가 메시지 재시도 (중복 발생)
응답 누락

OpenClaw는 빠르게 반환하고 적극적으로 응답을 보내는 방식으로 이를 처리하지만, 매우 느린 응답은 여전히 문제를 일으킬 수 있습니다.

포맷

Teams markdown은 Slack이나 Discord보다 제한적입니다:

기본 포맷 작동: bold, italic, code, 링크
복잡한 markdown (테이블, 중첩 목록)은 올바르게 렌더링되지 않을 수 있음
Adaptive Card는 투표 및 임의의 카드 전송에 지원됨 (아래 참조)

설정

주요 설정 (공유 채널 패턴은 /gateway/configuration 참조):

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: DM 허용목록 (AAD 객체 ID, UPN 또는 표시 이름). 마법사는 Graph 접근이 가능한 경우 설정 중에 이름을 ID로 해석합니다.
channels.msteams.textChunkLimit: 아웃바운드 텍스트 청크 크기.
channels.msteams.chunkMode: length (기본값) 또는 newline으로 길이 청킹 전에 빈 줄(단락 경계)로 분할.
channels.msteams.mediaAllowHosts: 인바운드 첨부파일 호스트 허용목록 (기본값은 Microsoft/Teams 도메인).
channels.msteams.requireMention: 채널/그룹에서 @멘션 필요 (기본값 true).
channels.msteams.replyStyle: thread | top-level (Reply Style 참조).
channels.msteams.teams.<teamId>.replyStyle: 팀별 재정의.
channels.msteams.teams.<teamId>.requireMention: 팀별 재정의.
channels.msteams.teams.<teamId>.tools: 채널 재정의가 누락된 경우 사용되는 기본 팀별 도구 정책 재정의 (allow/deny/alsoAllow).
channels.msteams.teams.<teamId>.toolsBySender: 기본 팀별 발신자별 도구 정책 재정의 ("*" 와일드카드 지원).
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 사이트 ID (그룹 채팅에서 파일 전송 참조).

라우팅 & 세션

세션 키는 표준 에이전트 형식을 따릅니다(/concepts/session 참조):
- 다이렉트 메시지는 메인 세션을 공유합니다(agent:<agentId>:<mainKey>).
- 채널/그룹 메시지는 대화 id를 사용합니다:
  - agent:<agentId>:msteams:channel:<conversationId>
  - agent:<agentId>:msteams:group:<conversationId>

답장 스타일: 스레드 vs 포스트

Teams는 최근 동일한 기본 데이터 모델에서 두 가지 채널 UI 스타일을 도입했습니다:

스타일	설명	권장 replyStyle
Posts (클래식)	메시지가 카드로 표시되고 그 아래에 스레드 답장이 있음	thread (기본값)
Threads (Slack 유사)	메시지가 선형으로 흐름, Slack과 유사	top-level

문제: Teams API는 채널이 어떤 UI 스타일을 사용하는지 노출하지 않습니다. 잘못된 replyStyle을 사용하면:

Threads 스타일 채널에서 thread → 답장이 어색하게 중첩됨
Posts 스타일 채널에서 top-level → 답장이 스레드 대신 별도의 최상위 포스트로 표시됨

해결책: 채널 설정 방식에 따라 채널별로 replyStyle을 구성합니다:

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

첨부파일 & 이미지

현재 제한사항:

DM: 이미지 및 파일 첨부파일이 Teams 봇 파일 API를 통해 작동합니다.
채널/그룹: 첨부파일은 M365 스토리지(SharePoint/OneDrive)에 있습니다. webhook 페이로드에는 HTML stub만 포함되고 실제 파일 바이트는 포함되지 않습니다. 채널 첨부파일을 다운로드하려면 Graph API 권한이 필요합니다.

Graph 권한 없이는, 이미지가 있는 채널 메시지가 텍스트만으로 수신됩니다(이미지 콘텐츠는 봇이 접근할 수 없음). 기본적으로 OpenClaw는 Microsoft/Teams 호스트명에서만 미디어를 다운로드합니다. channels.msteams.mediaAllowHosts로 재정의합니다(모든 호스트를 허용하려면 ["*"] 사용).

그룹 채팅에서 파일 전송

봇은 FileConsentCard 플로우(내장)를 사용하여 DM에서 파일을 전송할 수 있습니다. 그러나 그룹 채팅/채널에서 파일 전송은 추가 설정이 필요합니다:

컨텍스트	파일 전송 방법	필요한 설정
DM	FileConsentCard → 사용자 수락 → 봇 업로드	기본적으로 작동
그룹 채팅/채널	SharePoint에 업로드 → 공유 링크	sharePointSiteId + Graph 권한 필요
이미지 (모든 컨텍스트)	Base64 인코딩 인라인	기본적으로 작동

그룹 채팅에 SharePoint가 필요한 이유

봇은 개인 OneDrive 드라이브가 없습니다(/me/drive Graph API 엔드포인트는 애플리케이션 ID에서 작동하지 않음). 그룹 채팅/채널에서 파일을 전송하려면, 봇이 SharePoint 사이트에 업로드하고 공유 링크를 생성합니다.

설정

Entra ID (Azure AD) → App Registration에서 Graph API 권한 추가:
- Sites.ReadWrite.All (Application) - SharePoint에 파일 업로드
- Chat.Read.All (Application) - 선택사항, 사용자별 공유 링크 활성화
테넌트에 대한 관리자 동의 부여.

SharePoint 사이트 ID 가져오기:

# Graph Explorer 또는 유효한 토큰이 있는 curl을 통해:
curl -H "Authorization: Bearer $TOKEN" \
  "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"

# 예: "contoso.sharepoint.com/sites/BotFiles"의 사이트에 대해
curl -H "Authorization: Bearer $TOKEN" \
  "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"

# 응답에는 다음이 포함됩니다: "id": "contoso.sharepoint.com,guid1,guid2"

OpenClaw 구성:

{
  channels: {
    msteams: {
      // ... 기타 설정 ...
      sharePointSiteId: "contoso.sharepoint.com,guid1,guid2"
    }
  }
}

공유 동작

권한	공유 동작
Sites.ReadWrite.All만	조직 전체 공유 링크 (조직 내 누구나 접근 가능)
Sites.ReadWrite.All + Chat.Read.All	사용자별 공유 링크 (채팅 멤버만 접근 가능)

사용자별 공유가 더 안전합니다(채팅 참가자만 파일에 접근 가능). Chat.Read.All 권한이 없으면, 봇은 조직 전체 공유로 폴백합니다.

폴백 동작

시나리오	결과
그룹 채팅 + 파일 + sharePointSiteId 구성됨	SharePoint에 업로드, 공유 링크 전송
그룹 채팅 + 파일 + sharePointSiteId 없음	OneDrive 업로드 시도 (실패 가능), 텍스트만 전송
개인 채팅 + 파일	FileConsentCard 플로우 (SharePoint 없이 작동)
모든 컨텍스트 + 이미지	Base64 인코딩 인라인 (SharePoint 없이 작동)

파일 저장 위치

업로드된 파일은 구성된 SharePoint 사이트의 기본 문서 라이브러리에 있는 /OpenClawShared/ 폴더에 저장됩니다.

투표 (Adaptive Cards)

OpenClaw는 Teams 투표를 Adaptive Card로 전송합니다(네이티브 Teams 투표 API가 없음).

CLI: openclaw message poll --channel msteams --target conversation:<id> ...
투표는 Gateway에 의해 ~/.openclaw/msteams-polls.json에 기록됩니다.
Gateway는 투표를 기록하려면 온라인 상태여야 합니다.
투표는 아직 결과 요약을 자동 게시하지 않습니다(필요한 경우 저장소 파일 검사).

Adaptive Cards (임의)

message 도구 또는 CLI를 사용하여 Teams 사용자 또는 대화에 모든 Adaptive Card JSON을 전송합니다.

card 매개변수는 Adaptive Card JSON 객체를 허용합니다. card가 제공되면 메시지 텍스트는 선택사항입니다.

에이전트 도구:

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

CLI:

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

카드 스키마 및 예시는 Adaptive Cards 문서를 참조하세요. 타겟 형식 세부정보는 아래 타겟 형식을 참조하세요.

타겟 형식

MSTeams 타겟은 사용자와 대화를 구별하기 위해 접두사를 사용합니다:

타겟 유형	형식	예시
사용자 (ID로)	user:<aad-object-id>	user:40a1a0ed-4ff2-4164-a219-55518990c197
사용자 (이름으로)	user:<display-name>	user:John Smith (Graph API 필요)
그룹/채널	conversation:<conversation-id>	conversation:19:[email protected]
그룹/채널 (raw)	<conversation-id>	19:[email protected] (@thread 포함 시)

CLI 예시:

# ID로 사용자에게 전송
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"

# 표시 이름으로 사용자에게 전송 (Graph API 조회 트리거)
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"

# 그룹 채팅 또는 채널에 전송
openclaw message send --channel msteams --target "conversation:19:[email protected]" --message "Hello"

# 대화에 Adaptive Card 전송
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"}]}
}

참고: user: 접두사 없이는 이름이 기본적으로 그룹/팀 해석으로 처리됩니다. 표시 이름으로 사람을 타겟팅할 때는 항상 user:를 사용하세요.

프로액티브 메시징

프로액티브 메시지는 사용자가 상호작용한 후에만 가능합니다. 그 시점에 대화 참조를 저장하기 때문입니다.
dmPolicy 및 허용목록 게이팅은 /gateway/configuration을 참조하세요.

팀 및 채널 ID (일반적인 함정)

Teams URL의 groupId 쿼리 매개변수는 구성에 사용되는 팀 ID가 아닙니다. 대신 URL 경로에서 ID를 추출합니다:

팀 URL:

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    팀 ID (URL 디코드 필요)

채널 URL:

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      채널 ID (URL 디코드 필요)

설정용:

팀 ID = /team/ 다음의 경로 세그먼트 (URL 디코딩됨, 예: 19:[email protected])
채널 ID = /channel/ 다음의 경로 세그먼트 (URL 디코딩됨)
groupId 쿼리 매개변수는 무시

비공개 채널

봇은 비공개 채널에서 제한적으로 지원됩니다:

기능	표준 채널	비공개 채널
봇 설치	Yes	제한적
실시간 메시지 (webhook)	Yes	작동하지 않을 수 있음
RSC 권한	Yes	다르게 동작할 수 있음
@멘션	Yes	봇이 접근 가능한 경우
Graph API 히스토리	Yes	Yes (권한 필요)

비공개 채널이 작동하지 않는 경우 해결 방법:

봇 상호작용에 표준 채널 사용
DM 사용 - 사용자는 항상 봇에게 직접 메시지를 보낼 수 있습니다
과거 접근을 위해 Graph API 사용 (ChannelMessage.Read.All 필요)

문제 해결

일반적인 문제

채널에서 이미지가 표시되지 않음: Graph 권한 또는 관리자 동의 누락. Teams 앱을 재설치하고 Teams를 완전히 종료/다시 열기.
채널에서 응답 없음: 기본적으로 멘션이 필요합니다. channels.msteams.requireMention=false로 설정하거나 팀/채널별로 구성하세요.
버전 불일치 (Teams가 여전히 이전 manifest 표시): 앱을 제거 + 다시 추가하고 Teams를 완전히 종료하여 새로 고침.
webhook에서 401 Unauthorized: Azure JWT 없이 수동으로 테스트할 때 예상됨 - 엔드포인트가 접근 가능하지만 인증 실패를 의미합니다. Azure Web Chat을 사용하여 제대로 테스트하세요.

Manifest 업로드 오류

"Icon file cannot be empty": manifest가 0바이트인 아이콘 파일을 참조합니다. 유효한 PNG 아이콘 생성 (outline.png는 32x32, color.png는 192x192).
"webApplicationInfo.Id already in use": 앱이 여전히 다른 팀/채팅에 설치되어 있습니다. 먼저 찾아서 제거하거나 전파를 위해 5-10분 대기.
업로드 시 "Something went wrong": https://admin.teams.microsoft.com을 통해 업로드하고, 브라우저 개발자 도구 (F12) → Network 탭을 열고, 실제 오류에 대한 응답 본문 확인.
사이드로드 실패: "Upload a custom app" 대신 "Upload an app to your org's app catalog"을 시도 - 이것이 종종 사이드로드 제한을 우회합니다.

RSC 권한 작동하지 않음

webApplicationInfo.id가 봇의 App ID와 정확히 일치하는지 확인
앱을 재업로드하고 팀/채팅에서 재설치
조직 관리자가 RSC 권한을 차단했는지 확인
올바른 범위 사용 확인: 팀에는 ChannelMessage.Read.Group, 그룹 채팅에는 ChatMessage.Read.Chat