OpenClaw

OpenClaw Microsoft Teams 채널

엔터프라이즈
보통

Azure Bot 리소스를 통해 Bot Framework를 사용하여 OpenClaw를 Microsoft Teams에 연결합니다. 이 플러그인 기반 통합을 통해 AI 어시스턴트가 Teams에서 작동할 수 있으며, 개인 DM, 그룹 채팅 및 채널 대화를 처리합니다. OpenClaw는 /api/messages에서 Bot Framework의 webhook 이벤트를 수신하고 Teams 메시징 API를 통해 응답하며, 스레드 답변, Adaptive Cards, 리액션, SharePoint를 통한 파일 공유, 팀/채널별 구성 재정의를 지원합니다.

기본 정보
난이도보통
카테고리엔터프라이즈
지원 기능 수5 / 6

Microsoft Teams 지원 기능

텍스트 메시지

지원

미디어 및 파일

지원

리액션

지원

스레드

지원

음성 메시지

미지원

그룹 채팅

지원

Microsoft Teams 사전 요구사항

  • Azure Bot 리소스를 생성할 수 있는 권한이 있는 Azure 계정
  • App ID, App Password(클라이언트 시크릿) 및 Tenant ID가 등록된 Azure Bot(단일 테넌트 권장)
  • 봇 구성, 범위 및 아이콘(outline.png 32×32, color.png 192×192)이 포함된 Teams App Manifest(manifest.json)
  • 공개 HTTPS URL 또는 터널을 통해 접근 가능한 OpenClaw Gateway 실행 중(기본 webhook 포트 3978)
  • Teams 플러그인 설치: openclaw plugins install @openclaw/msteams

Microsoft Teams 빠른 설정

1

Azure Bot 리소스 생성

Azure Portal → 리소스 만들기 → 'Azure Bot' 검색으로 이동합니다. Single Tenant 유형으로 생성합니다. App Registration에서 클라이언트 시크릿을 생성합니다. App ID, 클라이언트 시크릿, Tenant ID를 복사합니다. OpenClaw 구성에 세 가지 모두 필요합니다.

2

Teams 플러그인 설치 및 구성

'openclaw plugins install @openclaw/msteams'를 실행하여 플러그인을 설치합니다. openclaw.json에 appId, appPassword, tenantId를 포함한 Teams 채널 구성을 추가합니다. 환경 변수 MSTEAMS_APP_ID, MSTEAMS_APP_PASSWORD, MSTEAMS_TENANT_ID를 사용할 수도 있습니다.

3

메시징 엔드포인트 설정 및 Teams 채널 활성화

Azure Portal에서 Bot 리소스 → 구성으로 이동합니다. 메시징 엔드포인트를 'https://<your-domain>/api/messages'로 설정합니다. 그런 다음 채널 → Microsoft Teams 추가 → 구성으로 이동합니다. 로컬 개발의 경우 터널(ngrok 또는 Tailscale Funnel)을 사용하여 포트 3978을 노출합니다.

4

Teams 앱 생성 및 설치

봇의 App ID를 botId로, 범위(personal, team, groupChat) 및 RSC 권한이 포함된 manifest.json을 생성합니다. outline.png와 color.png와 함께 zip으로 압축합니다. Teams Developer Portal 또는 Teams Admin Center를 통해 업로드합니다. 테스트용으로는 앱 패키지를 사이드로드합니다.

5

봇 테스트

Teams에서 봇을 찾아 다이렉트 메시지를 보냅니다. 기본 페어링 정책을 사용하는 경우, 터미널에서 'openclaw pairing approve msteams <code>'로 발신자를 승인합니다. 봇이 AI 생성 응답으로 답변해야 합니다.

Microsoft Teams 구성 예시

config.json
{
  "channels": {
    "msteams": {
      "enabled": true,
      "appId": "YOUR_APP_ID",
      "appPassword": "YOUR_APP_PASSWORD",
      "tenantId": "YOUR_TENANT_ID",
      "webhook": {
        "port": 3978,
        "path": "/api/messages"
      }
    }
  }
}

Microsoft Teams 상세 문서

아키텍처 개요

OpenClaw는 Azure Bot Framework를 통해 Microsoft Teams와 통합됩니다. 이는 webhook 기반 아키텍처로, Teams가 메시지를 Gateway의 /api/messages 엔드포인트로 라우팅하고 OpenClaw가 Bot Framework REST API를 통해 응답합니다. 흐름: 사용자가 Teams에서 메시지 전송 → Bot Framework Service → Gateway로 webhook POST(포트 3978) → OpenClaw가 AI로 처리 → Bot Framework API를 통해 응답 → Teams가 응답 전달. Teams 플러그인은 'openclaw plugins install @openclaw/msteams'를 통해 별도로 설치됩니다. 이 모듈식 접근 방식은 핵심 Gateway를 가볍게 유지하면서 Teams 전용 기능(Adaptive Cards, SharePoint 파일 업로드, RSC 권한)을 독립적으로 관리할 수 있게 합니다. 인증은 Azure AD를 사용합니다: Bot Framework는 수신 webhook 요청에서 JWT 토큰을 검증하고, OpenClaw는 App ID와 App Password를 사용하여 발신 API 호출을 인증합니다. 보안을 위해 단일 테넌트 구성이 권장되며, 봇을 조직의 Azure AD 디렉터리로 제한합니다.
Gateway는 공개 HTTPS URL을 통해 접근 가능해야 합니다. 로컬 개발의 경우 ngrok 또는 Tailscale Funnel을 사용하여 포트 3978로 터널링하세요.
조직 보안을 위해 다중 테넌트보다 단일 테넌트 봇이 권장됩니다. Azure AD 디렉터리의 토큰만 수락합니다.

Azure Bot 설정 및 앱 등록

Teams 봇을 설정하려면 Azure Portal에서 리소스를 생성해야 합니다: 1. Azure Bot 리소스 생성 — 마켓플레이스에서 'Azure Bot'을 검색합니다. 봇 유형으로 Single Tenant를 선택합니다. 이렇게 하면 Bot 리소스와 App Registration이 모두 생성됩니다. 2. 클라이언트 시크릿 생성 — App Registrations → 봇 앱 → 인증서 및 비밀에서 새 클라이언트 시크릿을 생성합니다. 값을 즉시 복사하세요(한 번만 표시됩니다). 3. 자격 증명 기록 — 개요 페이지의 App (client) ID, 클라이언트 시크릿 값, Directory (tenant) ID. 이 세 가지 값이 봇의 인증 자격 증명입니다. 4. 메시징 엔드포인트 설정 — Bot 리소스 → 구성에서 엔드포인트를 'https://<your-domain>/api/messages'로 설정합니다. 여기로 Teams가 webhook 이벤트를 전송합니다. 5. Teams 채널 활성화 — 채널 → 채널 추가 → Microsoft Teams로 이동합니다. 구성하고 저장합니다. 구성 파일 값 대신 환경 변수를 사용할 수 있습니다: MSTEAMS_APP_ID, MSTEAMS_APP_PASSWORD, MSTEAMS_TENANT_ID.
openclaw.json
{
  "channels": {
    "msteams": {
      "appId": "<APP_ID>",
      "appPassword": "<APP_PASSWORD>",
      "tenantId": "<TENANT_ID>"
    }
  }
}
App Password를 안전하게 보관하세요. 버전 관리에 절대 커밋하지 마세요. 프로덕션 배포에는 환경 변수(MSTEAMS_APP_PASSWORD)를 사용하세요. Azure Portal에서 클라이언트 시크릿을 주기적으로 교체하세요.

Teams App Manifest 및 RSC 권한

Teams App Manifest(manifest.json)는 봇의 ID, 범위 및 권한을 정의합니다. 두 개의 아이콘과 함께 .zip 파일로 패키징하여 설치합니다. Manifest 필수 항목: • botId — Azure Bot의 App ID • Scopes — personal(DM), team(채널), groupChat(그룹 대화) • supportsFiles: true — 개인 채팅에서 파일 동의 카드 활성화 • Resource-Specific Consent(RSC) 권한 — @멘션 없이 메시지를 수신할 수 있도록 허용 채널(team 범위)용 RSC 권한: • ChannelMessage.Read.Group — @멘션 없이 채널 메시지 수신 • ChannelMessage.Send.Group — 채널에 메시지 전송 • TeamMember.Read.Group, TeamSettings.Read.Group — 팀 메타데이터 읽기 그룹 채팅용 RSC 권한: • ChatMessage.Read.Chat — @멘션 없이 그룹 채팅 메시지 수신 필요한 아이콘: • outline.png — 32×32 픽셀, 투명 배경 • color.png — 192×192 픽셀, 풀 컬러 앱 아이콘 manifest.json과 두 아이콘을 함께 zip으로 압축한 후 Teams Developer Portal, Teams Admin Center를 통해 업로드하거나 테스트용으로 사이드로드합니다.
설치된 앱을 업데이트할 때(예: RSC 권한 추가), manifest.json의 version 필드를 증가시키고 다시 zip으로 압축하여 재업로드한 후 각 팀에 재설치합니다.
앱을 설치하거나 업데이트한 후, 새 권한이 적용되도록 Teams 클라이언트를 완전히 종료한 후 다시 실행하세요.

DM 정책

DM(다이렉트 메시지) 정책은 개인 채팅에서 봇과 상호작용할 수 있는 사용자를 제어합니다. OpenClaw는 네 가지 정책을 지원합니다: • pairing(기본값) — 봇에게 메시지를 보내는 새 사용자는 랜덤 페어링 코드를 받습니다. 터미널에서 'openclaw pairing approve msteams <code>'로 승인합니다. 승인 후 자유롭게 채팅할 수 있습니다. • allowlist — allowFrom에 나열된 사용자만 봇에게 메시지를 보낼 수 있습니다. AAD 객체 ID, UPN(user@org.com) 또는 표시 이름을 지원합니다. • open — 테넌트 내 모든 Teams 사용자가 봇에게 메시지를 보낼 수 있습니다. 안전 확인으로 allowFrom에 '*'를 추가해야 합니다. • disabled — DM 기능이 완전히 비활성화됩니다. Teams는 AAD(Azure AD) 객체 ID, UPN 또는 표시 이름으로 사용자를 식별합니다. 사용자가 메시지를 보낼 때 Gateway 로그에서 찾거나 Azure Portal의 Azure Active Directory → 사용자에서 조회할 수 있습니다.
openclaw.json
{
  "channels": {
    "msteams": {
      "dmPolicy": "allowlist",
      "allowFrom": [
        "user@org.com",
        "40a1a0ed-4ff2-4164-a219-55518990c197"
      ]
    }
  }
}
UPN 형식(user@org.com)이 허용 목록에 가장 편리합니다. 사용자가 이메일 주소를 변경할 수 있는 경우 AAD 객체 ID가 더 안정적입니다.
'openclaw pairing list msteams'를 사용하여 대기 중인 모든 페어링 요청과 코드를 확인하세요.

그룹 채팅 및 채널 관리

OpenClaw는 Teams 채널(팀 내)과 그룹 채팅을 모두 지원하며, 각각 구성 가능한 접근 제어를 제공합니다: • disabled(그룹 기본값) — 모든 그룹/채널 메시지 무시 • allowlist — 승인된 발신자(groupAllowFrom을 통해)만 봇을 트리거할 수 있음 • open — 모든 그룹 멤버 또는 채널 참가자의 메시지에 응답 기본적으로 봇은 채널 및 그룹 채팅에서 @멘션을 필요로 합니다(requireMention: true). requireMention을 false로 설정하면 모든 메시지에 응답하거나, RSC 권한을 구성하여 멘션 없이 메시지를 수신할 수 있습니다. Teams 채널과 그룹 채팅은 별도의 대화 컨텍스트를 유지합니다. 각 대화에는 고유한 세션과 기록이 있으며, DM 및 다른 대화와 격리됩니다. 팀별 및 채널별 재정의를 통해 세밀한 제어가 가능합니다. 각 팀 또는 팀 내 개별 채널에 대해 다른 replyStyle, requireMention, 도구 구성을 설정할 수 있습니다.
openclaw.json
{
  "channels": {
    "msteams": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["user@org.com"],
      "teams": {
        "My Team": {
          "channels": {
            "General": {
              "requireMention": true
            }
          }
        }
      }
    }
  }
}
팀 및 채널 표시 이름 또는 대화 ID(19:...@thread.tacv2)를 teams 구성의 키로 사용합니다.
채널별 재정의는 상위 팀 구성에서 상속되며, 팀 구성은 전역 msteams 구성에서 상속됩니다.

응답 스타일 및 스레딩

Teams는 채널에 대해 두 가지 UI 레이아웃을 제공하며, OpenClaw의 응답 동작은 이에 맞춰야 합니다: • Posts(클래식 레이아웃) — 루트 메시지 아래에 스레드 답변을 사용합니다. replyStyle을 'thread'(기본값)로 설정합니다. 봇의 응답이 원본 메시지 카드에 대한 답변으로 표시됩니다. • Threads(Slack 스타일 레이아웃) — 선형 메시지 흐름을 사용합니다. replyStyle을 'top-level'로 설정합니다. 봇이 스레딩 대신 새로운 최상위 메시지를 보냅니다. Teams API는 채널이 어떤 레이아웃을 사용하는지 노출하지 않으므로 replyStyle을 직접 구성해야 합니다. 설정이 일치하지 않아도 오류는 발생하지 않지만 대화 흐름이 최적이 아닐 수 있습니다. 응답 스타일은 전역, 팀별 또는 채널별로 구성할 수 있습니다. 이를 통해 동일한 Teams 조직 내 다른 채널의 다른 레이아웃에 맞출 수 있습니다.
openclaw.json
{
  "channels": {
    "msteams": {
      "replyStyle": "thread",
      "teams": {
        "19:abc...@thread.tacv2": {
          "channels": {
            "19:xyz...@thread.tacv2": {
              "replyStyle": "top-level"
            }
          }
        }
      }
    }
  }
}

파일 처리 및 SharePoint

OpenClaw는 Teams에서 채팅 유형에 따라 다른 동작으로 파일 공유를 지원합니다: 개인 채팅: • 내장 FileConsentCard 흐름 — 추가 설정이 필요 없습니다. 봇이 파일 동의 카드를 보내고, 사용자가 승인하면 파일이 업로드됩니다. 그룹 채팅 및 채널: • Microsoft Graph 권한 필요: Sites.ReadWrite.All • 선택 사항: 사용자별 공유 링크를 위한 Chat.Read.All(채팅 멤버에게만 접근을 제한) • sharePointSiteId를 구성하여 파일 업로드용 SharePoint 사이트를 지정 • 파일은 SharePoint 문서 라이브러리의 /OpenClawShared/ 폴더에 저장됩니다 Chat.Read.All 없이는 공유 파일 링크가 조직 전체에 적용됩니다. 이 권한이 있으면 공유가 현재 채팅 멤버로 제한됩니다. 수신 첨부 파일은 Gateway에서 자동으로 다운로드되어 처리됩니다. mediaAllowHosts 및 mediaAuthAllowHosts 구성은 첨부 파일 다운로드 시 신뢰할 수 있는 도메인을 제어합니다.
openclaw.json
{
  "channels": {
    "msteams": {
      "sharePointSiteId": "YOUR_SHAREPOINT_SITE_ID",
      "mediaAllowHosts": ["*.microsoft.com", "*.sharepoint.com"],
      "mediaAuthAllowHosts": ["graph.microsoft.com"]
    }
  }
}
Graph API 권한(Sites.ReadWrite.All, Chat.Read.All)은 Azure AD 테넌트에서 관리자 동의가 필요합니다. IT 관리자와 협력하여 이러한 권한을 부여하세요.

Adaptive Cards 및 설문

Microsoft Teams는 Adaptive Cards를 지원합니다. 이는 일반 텍스트를 넘어선 풍부한 대화형 카드 기반 레이아웃입니다. OpenClaw는 향상된 봇 상호작용을 위해 이를 활용합니다: 설문: • 'openclaw message poll --channel msteams --target conversation:<id>'를 통해 설문 생성 • Adaptive Card 액션을 통해 투표가 수집되며 ~/.openclaw/msteams-polls.json에 로컬로 저장됩니다 • 투표를 수집하려면 Gateway가 온라인 상태를 유지해야 합니다 사용자 정의 Adaptive Cards: • CLI를 통해 임의의 Adaptive Cards 전송: openclaw message send --channel msteams --target "conversation:<id>" --card '{...}' • 카드는 Adaptive Card 스키마 버전 1.5를 지원합니다 • 텍스트 블록, 이미지, 액션 버튼, 입력 필드 등을 포함할 수 있습니다 서식 참고: • 일반 메시지에서는 기본 마크다운(굵게, 기울임, 코드, 링크)이 지원됩니다 • 복잡한 표와 깊이 중첩된 목록은 올바르게 렌더링되지 않을 수 있습니다 • 풍부한 레이아웃의 경우 마크다운 서식 대신 Adaptive Cards를 사용하세요
Adaptive Cards Designer(adaptivecards.io/designer)를 사용하여 전송 전에 사용자 정의 카드 레이아웃을 빌드하고 미리 볼 수 있습니다.
Adaptive Cards 액션은 OpenClaw가 사용자 입력으로 처리하는 postback 이벤트를 트리거할 수 있습니다.

Teams ID 추출

Teams URL에는 여러 ID가 포함되어 있지만, 구성에 필요한 ID가 모두 같은 것은 아닙니다. 올바른 ID를 추출하는 방법은 다음과 같습니다: Team ID — URL 경로에서 찾을 수 있습니다(groupId 쿼리 파라미터가 아님): https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/... → '19%3ABk4j...%40thread.tacv2'를 URL 디코딩하여 팀 ID를 얻습니다 Channel ID — 역시 URL 경로에 있습니다: https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/... → URL 디코딩하여 채널 대화 ID를 얻습니다 CLI 명령의 사용자 대상: • AAD ID로: user:40a1a0ed-4ff2-4164-a219-55518990c197 • 표시 이름으로: user:John Smith • 대화: conversation:19:abc...@thread.tacv2 • 원시(@thread 포함 시): 19:abc...@thread.tacv2
Teams URL의 'groupId' 쿼리 파라미터를 사용하지 마세요. 이것은 Microsoft 365 Group ID이며 Teams 대화 ID가 아닙니다. 항상 URL 경로에서 ID를 추출하고 URL 디코딩하세요.

Microsoft Teams 구성 참조

enabled
Type: booleanDefault: true

Microsoft Teams 채널 활성화 또는 비활성화

appId
Type: stringDefault: ""

Azure Bot App ID(Microsoft App ID). 환경 변수 MSTEAMS_APP_ID도 사용 가능

appPassword
Type: stringDefault: ""

Azure Bot 클라이언트 시크릿. 환경 변수 MSTEAMS_APP_PASSWORD도 사용 가능

tenantId
Type: stringDefault: ""

단일 테넌트 인증을 위한 Azure AD Tenant ID. 환경 변수 MSTEAMS_TENANT_ID도 사용 가능

webhook.port
Type: numberDefault: 3978

Bot Framework 이벤트를 수신하는 webhook 리스너 포트

webhook.path
Type: stringDefault: "/api/messages"

수신 Bot Framework 메시지를 위한 webhook 엔드포인트 경로

dmPolicy
Type: stringDefault: "pairing"

봇에 DM을 보낼 수 있는 사용자를 제어합니다. 옵션: pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

봇에 DM을 보낼 수 있는 AAD 객체 ID, UPN 또는 표시 이름(dmPolicy가 allowlist일 때)

groupPolicy
Type: stringDefault: "allowlist"

그룹/채널 접근 제어. 옵션: allowlist, open, disabled

groupAllowFrom
Type: string[]Default: []

그룹 채팅에서 허용되는 발신자. 설정되지 않으면 allowFrom으로 대체

teams
Type: objectDefault: {}

팀별 및 채널별 구성 재정의(replyStyle, requireMention, tools)

requireMention
Type: booleanDefault: true

채널 및 그룹 채팅에서 @멘션 필요. RSC 권한과 함께 false로 설정하면 모든 메시지에 응답

replyStyle
Type: stringDefault: "thread"

응답 레이아웃 스타일. 옵션: thread(클래식 Posts), top-level(Slack 스타일 Threads)

configWrites
Type: booleanDefault: true

런타임에 /config set|unset 명령으로 채널 설정 수정 허용

textChunkLimit
Type: numberDefault: —

청킹 전 발신 메시지당 최대 문자 수

chunkMode
Type: stringDefault: "length"

텍스트 청킹 전략. 옵션: length(하드 분할), newline(단락 인식)

sharePointSiteId
Type: stringDefault: ""

그룹 채팅/채널 파일 업로드를 위한 SharePoint 사이트 ID

mediaAllowHosts
Type: string[]Default: MS/Teams domains

미디어 첨부 파일 다운로드가 허용된 호스트

mediaAuthAllowHosts
Type: string[]Default: Graph + Bot Framework

미디어 다운로드 시 Authorization 헤더를 수신하는 호스트

dmHistoryLimit
Type: numberDefault: 50

대화당 AI 컨텍스트에 포함되는 최근 DM 메시지 수

historyLimit
Type: numberDefault: 50

AI 컨텍스트에 포함되는 최대 채널/그룹 메시지 수

Microsoft Teams 자주 묻는 질문

Microsoft Teams 문제 해결

채널 메시지에서 이미지 및 첨부 파일이 누락됩니다

Graph API 권한이 부여되지 않았거나 관리자 동의가 누락되었습니다. 봇이 실제 파일 대신 콘텐츠 스텁을 수신합니다.

앱 등록에 관리자 동의가 있는 ChannelMessage.Read.All 및 Chat.Read.All Graph 권한이 있는지 확인합니다. 권한을 업데이트한 후 Teams 앱을 재설치합니다. 캐시된 권한을 새로 고치려면 Teams 클라이언트를 완전히 종료한 후 다시 엽니다.
봇이 채널에서 응답하지 않습니다(DM에서만 작동)

봇은 기본적으로 채널 및 그룹 채팅에서 @멘션을 필요로 하거나 RSC 권한이 구성되지 않았습니다.

채널 메시지에서 봇을 @멘션하거나, 구성에서 requireMention: false로 설정하고 앱 매니페스트에 RSC 권한 ChannelMessage.Read.Group을 추가합니다. 매니페스트를 업데이트한 후 각 팀에 앱을 재설치합니다.
변경 후 Teams App 매니페스트가 업데이트되지 않습니다

Teams가 앱 메타데이터를 적극적으로 캐시합니다. 이전 매니페스트가 여전히 사용 중입니다.

manifest.json의 version 필드를 증가시키고(예: 1.0.0 → 1.1.0), 패키지를 다시 zip으로 압축하고, Teams에서 이전 앱을 제거하고, 업데이트된 패키지를 재설치한 후 Teams 클라이언트를 강제 종료하고 다시 시작합니다.
webhook 엔드포인트에서 401 Unauthorized 오류 발생

OpenClaw 구성의 appId, appPassword 또는 tenantId가 Azure Bot 등록과 일치하지 않거나, 적절한 Azure JWT 토큰 없이 수동으로 테스트하고 있습니다.

세 가지 자격 증명이 Azure Portal 값과 정확히 일치하는지 확인합니다. Teams 관련 문제를 해결하기 전에 Azure의 내장 Web Chat(Bot 리소스 → 웹 채팅에서 테스트)을 사용하여 봇이 작동하는지 확인합니다. tenantId가 봇이 등록된 디렉터리와 일치하는지 확인합니다.
봇이 비공개 채널에서 작동하지 않습니다

Microsoft Teams는 과거에 비공개 채널에서 봇 지원이 제한적이었습니다. 2026년 초부터 Microsoft는 비공개 채널에 대한 전체 앱 지원을 배포하고 있지만 아직 모든 테넌트에서 사용할 수 없을 수 있습니다.

테넌트가 비공개 채널 앱 지원 업데이트를 받았는지 확인하세요. 아직 사용할 수 없는 경우 표준(공개) 채널, 그룹 채팅 또는 DM을 사용하세요. 앱은 각 비공개 채널에 개별적으로 추가해야 합니다. 팀 수준에서 설치해도 비공개 채널에 자동으로 적용되지 않습니다.
전체 문서 보기모든 채널로 돌아가기

관련 채널

Feishu / Lark

Medium

OpenClaw WebSocket을 통한 Feishu/Lark 통합

설정 가이드

Slack

Medium

OpenClaw Bolt SDK를 통한 워크스페이스 앱 통합

설정 가이드

Google Chat

Medium

OpenClaw HTTP 엔드포인트를 통한 Google Chat API 앱

설정 가이드