OpenClaw Microsoft Teams 연결 튜토리얼

서문

Microsoft Teams는 기업 협업의 주류 플랫폼 중 하나로, 다양한 조직과 기업에서 널리 사용되고 있습니다. OpenClaw를 Teams에 연결하면 기업 내부에 안전하고 제어 가능한 AI 어시스턴트를 제공할 수 있습니다. 이 글에서는 Azure AD 앱 등록부터 Teams 앱 배포까지의 전체 프로세스를 상세히 설명합니다.

사전 조건

OpenClaw가 설치되어 정상적으로 실행 중
Microsoft 365 조직 계정 보유 (개인 계정은 기능 제한)
Azure 구독 보유 (무료 티어 가능)
Teams 관리자 권한 보유 (또는 관리자에게 앱 승인을 요청할 수 있음)
OpenClaw 서비스가 공인 HTTPS 주소로 접근 가능

아키텍처 개요

Teams Bot의 메시지 흐름은 다음과 같습니다:

사용자가 Teams에서 메시지 전송
         ↓
Microsoft Bot Framework Service
         ↓
HTTPS Webhook을 통해 OpenClaw로 전송
         ↓
OpenClaw가 메시지를 처리하고 AI 모델 호출
         ↓
Bot Framework API를 통해 응답 전송
         ↓
사용자가 Teams에서 응답 수신

1단계: Azure AD 앱 등록

1.1 앱 등록 생성

Azure Portal에 로그인합니다
Azure Active Directory → 앱 등록을 검색하여 진입합니다
새 등록을 클릭합니다
다음 정보를 입력합니다:

필드	값
이름	OpenClaw Teams Bot
지원되는 계정 유형	모든 조직 디렉터리의 계정 (다중 테넌트)
리디렉션 URI	비워 둠

등록을 클릭합니다

1.2 핵심 정보 기록

등록 완료 후 개요 페이지에서 다음 정보를 기록합니다:

애플리케이션(클라이언트) ID: 12345678-abcd-efgh-ijkl-123456789012
디렉터리(테넌트) ID: 87654321-dcba-hgfe-lkji-210987654321

1.3 클라이언트 비밀 생성

좌측 메뉴에서 인증서 및 비밀을 클릭합니다
새 클라이언트 비밀을 클릭합니다
설명을 입력합니다 (예: "OpenClaw Bot Secret")
만료 기간을 선택합니다 (24개월 권장)
추가를 클릭합니다
비밀 값을 즉시 복사합니다 (페이지를 떠나면 다시 확인할 수 없습니다)

클라이언트 비밀: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
주의: 이 비밀을 즉시 저장해 주십시오. 페이지 새로고침 후에는 다시 확인할 수 없습니다!

2단계: Bot 리소스 생성

2.1 Azure Bot 생성

Azure Portal에서 Azure Bot을 검색합니다
만들기를 클릭합니다
다음 정보를 입력합니다:

필드	값
Bot 핸들	openclaw-teams-bot
구독	Azure 구독 선택
리소스 그룹	새로 만들기 또는 기존 리소스 그룹 선택
가격 책정 계층	F0 (무료)
Microsoft 앱 ID 유형	다중 테넌트
만들기 유형	기존 앱 등록 사용
앱 ID	이전 단계에서 획득한 애플리케이션(클라이언트) ID

검토 + 만들기 → 만들기를 클릭합니다

2.2 메시지 엔드포인트 설정

Bot 리소스 생성 완료 후:

Bot 리소스 페이지로 이동합니다
좌측 메뉴에서 구성을 클릭합니다
메시지 엔드포인트에 입력합니다:

https://your-domain.com/webhook/teams/messages

적용을 클릭합니다

2.3 Teams 채널 활성화

Bot 리소스의 좌측 메뉴에서 채널을 클릭합니다
사용 가능한 채널 목록에서 Microsoft Teams를 클릭합니다
서비스 약관에 동의합니다
적용을 클릭합니다

Teams 채널 활성화 후 상태가 실행 중으로 표시되어야 합니다.

3단계: OpenClaw 설정

3.1 설정 파일 방식

~/.config/openclaw/openclaw.json5를 편집합니다:

{
  channels: {
    teams: {
      enabled: true,
      // Azure AD 애플리케이션(클라이언트) ID
      appId: "12345678-abcd-efgh-ijkl-123456789012",
      // Azure AD 클라이언트 비밀
      appPassword: "your-client-secret-value",
      // 테넌트 ID (다중 테넌트 모드에서는 비워 둘 수 있음)
      tenantId: "",

      // Webhook 경로
      webhookPath: "/webhook/teams/messages",

      // 메시지 처리 설정
      message: {
        // 팀 채널에서 @Bot 멘션이 필요한지 여부
        mentionRequired: true,
        // 1:1 채팅에서 자동 응답
        personalChatEnabled: true,
        // 그룹 채팅에서 활성화 여부
        groupChatEnabled: true
      },

      // 응답 설정
      reply: {
        // Adaptive Card 형식 사용 여부 (더 보기 좋음)
        useAdaptiveCard: true,
        // "입력 중" 표시기 표시
        showTyping: true,
        // 긴 메시지 분할 임계값
        maxLength: 28000
      }
    }
  }
}

3.2 환경 변수 방식

export TEAMS_APP_ID="12345678-abcd-efgh-ijkl-123456789012"
export TEAMS_APP_PASSWORD="your-client-secret-value"

3.3 재시작 및 확인

openclaw restart

# Teams 채널 로그 확인
openclaw logs -f --component channel:teams

성공 로그:

[INFO] [channel:teams] Teams Bot 서비스가 시작되었습니다
[INFO] [channel:teams] App ID: 12345678-abcd-****-****-************
[INFO] [channel:teams] Webhook 경로: /webhook/teams/messages
[INFO] [channel:teams] 메시지 수신 대기 중...

4단계: Teams 앱 패키지 생성

Teams 클라이언트에서 Bot을 찾아 사용하려면 Teams 앱 패키지를 만들어야 합니다.

4.1 앱 매니페스트 생성

manifest.json 파일을 생성합니다:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "version": "1.0.0",
  "id": "12345678-abcd-efgh-ijkl-123456789012",
  "developer": {
    "name": "Your Organization",
    "websiteUrl": "https://your-domain.com",
    "privacyUrl": "https://your-domain.com/privacy",
    "termsOfUseUrl": "https://your-domain.com/terms"
  },
  "name": {
    "short": "OpenClaw AI",
    "full": "OpenClaw AI Assistant for Teams"
  },
  "description": {
    "short": "AI 지능형 어시스턴트",
    "full": "OpenClaw 기반의 AI 지능형 어시스턴트로, 다양한 대규모 언어 모델을 지원하며 팀에 즉각적인 지능형 질의응답 서비스를 제공합니다."
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#5B5FC7",
  "bots": [
    {
      "botId": "12345678-abcd-efgh-ijkl-123456789012",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": false,
      "isNotificationOnly": false,
      "commandLists": [
        {
          "scopes": ["personal", "team", "groupChat"],
          "commands": [
            {
              "title": "ask",
              "description": "AI에게 질문하기"
            },
            {
              "title": "model",
              "description": "AI 모델 전환"
            },
            {
              "title": "reset",
              "description": "대화 컨텍스트 초기화"
            },
            {
              "title": "help",
              "description": "도움말 정보 표시"
            }
          ]
        }
      ]
    }
  ],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": ["your-domain.com"]
}

4.2 아이콘 준비

두 개의 아이콘 파일을 준비합니다:

파일명	크기	설명
`color.png`	192x192 픽셀	컬러 아이콘, 앱 목록에 사용
`outline.png`	32x32 픽셀	아웃라인 아이콘, 투명 배경 흰색 전경

4.3 앱 패키징

manifest.json, color.png, outline.png을 ZIP 파일로 패키징합니다:

zip teams-app.zip manifest.json color.png outline.png

4.4 Teams에 업로드

개발자 업로드 (개인 사용):

Teams 클라이언트를 엽니다
좌측 앱 → 앱 관리를 클릭합니다
앱 업로드 → 사용자 정의 앱 업로드를 클릭합니다
teams-app.zip 파일을 선택합니다

조직 레벨 배포 (관리자 작업):

Teams 관리 센터에 로그인합니다
Teams 앱 → 앱 관리로 이동합니다
새 앱 업로드를 클릭합니다
teams-app.zip 파일을 선택합니다
검토 후 조직 앱 스토어에 게시합니다

사용 방법

1:1 채팅

Teams에서 OpenClaw AI 앱을 찾습니다
채팅 시작을 클릭합니다
질문을 직접 입력하면 AI 응답을 받을 수 있습니다

팀 채널에서 사용

대상 팀 채널에서 @OpenClaw AI를 입력합니다
질문을 입력합니다

@OpenClaw AI 프로젝트 주간 보고서 템플릿을 작성해 주세요

그룹 채팅에서 사용

OpenClaw AI를 그룹 채팅에 추가합니다
@Bot 후 질문을 입력합니다

Adaptive Card 형식

Adaptive Card를 활성화하면 Bot의 응답이 더 아름답고 구조화되어 표시됩니다:

{
  channels: {
    teams: {
      reply: {
        useAdaptiveCard: true,
        adaptiveCard: {
          // 코드 블록 고정 폭 글꼴 사용
          codeStyle: true,
          // 모델 정보 표시
          showModelInfo: true,
          // 처리 소요 시간 표시
          showLatency: true,
          // "계속 질문" 버튼 추가
          actionButtons: true
        }
      }
    }
  }
}

Adaptive Card는 응답을 스타일이 적용된 카드로 서식화하며, 다음을 포함합니다:

헤더 영역에 Bot 이름과 모델 표시
본문 영역에서 Markdown 렌더링 지원
코드 블록에 구문 강조 및 복사 버튼
하단에 토큰 소비량 및 처리 시간 표시

기업 배포 주의사항

규정 준수 및 데이터 보안

고려사항	권장사항
데이터 상주	AI 모델 API의 데이터 처리 지역이 규정 준수 요건에 부합하는지 확인
데이터 보존	대화 기록의 보존 및 정리 정책 설정
감사 로그	감사 요건을 충족하기 위한 상세 로그 기록 활성화
접근 제어	Bot을 사용할 수 있는 사용자 및 팀 제한

사용자 권한 제어

{
  channels: {
    teams: {
      security: {
        // 허용된 사용자 이메일 목록
        allowedUsers: [
          "*@your-company.com"  // 회사 도메인의 모든 사용자 허용
        ],
        // 관리자 사용자
        adminUsers: [
          "[email protected]"
        ],
        // 허용된 팀 ID
        allowedTeams: [],
        // 사용자별 일일 메시지 제한
        dailyLimit: 100
      }
    }
  }
}

고가용성 배포

기업급 배포의 경우 다음을 권장합니다:

{
  channels: {
    teams: {
      // 요청 타임아웃 설정 (밀리초)
      timeout: 60000,
      // 재시도 설정
      retry: {
        maxAttempts: 3,
        backoffMs: 1000
      },
      // 동시성 제한
      concurrency: {
        maxConcurrent: 50,
        queueSize: 200
      }
    }
  }
}

Webhook과 Connector 비교

Bot Framework 방식 외에도 Teams는 Incoming Webhook 또는 Connector를 통한 통합을 지원합니다:

방식	양방향 통신	설정 복잡도	기능 풍부도
Bot Framework	지원	높음	가장 풍부
Incoming Webhook	전송만	낮음	기본
Connector	전송만	중간	중간

Bot Framework는 사용자 메시지를 수신하고 응답할 수 있는 유일한 방식이므로 OpenClaw의 권장 방안입니다. Webhook과 Connector는 단방향 알림 시나리오에만 적합합니다.

문제 해결

Bot이 응답하지 않음

# OpenClaw 로그 확인
openclaw logs --level error --component channel:teams

# 일반적인 원인:
# 1. 메시지 엔드포인트 URL에 접근 불가
# 2. App ID 또는 Password가 올바르지 않음
# 3. Bot에 Teams 채널이 활성화되지 않음

403 Forbidden 오류

# 일반적으로 App Password가 만료되었거나 올바르지 않음
# Azure AD → 앱 등록 → 인증서 및 비밀에서 비밀번호를 다시 생성
# OpenClaw 설정을 업데이트한 후 재시작
openclaw config set channels.teams.appPassword "new-password"
openclaw restart

Teams에 앱 업로드 불가

다음 사항을 확인합니다:

Teams 관리 센터에서 사용자 정의 앱 업로드가 허용되어 있는지
manifest.json의 id가 Azure AD 앱 ID와 일치하는지
아이콘 파일의 크기와 형식이 올바른지
ZIP 패키지 구조가 올바른지 (파일이 루트 디렉터리에 있고 하위 폴더에 있지 않은지)

응답 타임아웃

Teams Bot Framework는 15초 이내 응답을 요구합니다. AI 모델 응답이 느린 경우:

{
  channels: {
    teams: {
      reply: {
        // "입력 중" 표시기를 활성화하여 사용자에게 피드백 제공
        showTyping: true,
        // 먼저 "처리 중" 메시지를 전송
        thinkingMessage: "생각 중입니다...",
        // 완료 후 원래 메시지를 업데이트 (새 메시지 전송 대신)
        updateMessage: true
      }
    }
  }
}

요약

OpenClaw를 Microsoft Teams에 연결하는 데는 다소 많은 단계가 필요하지만, 기업에 안전하고 제어 가능한 AI 어시스턴트를 제공할 수 있습니다. 핵심 프로세스:

Azure AD에서 앱을 등록하고 자격 증명 획득
Azure Bot 리소스를 생성하고 Teams 채널 활성화
OpenClaw에서 App ID와 Password 설정
Teams 앱 패키징 및 배포
보안 정책 및 접근 제어 설정

기업 시나리오에서는 데이터 보안, 규정 준수 요건 및 접근 제어에 반드시 주의를 기울여야 합니다. 먼저 테스트 팀에서 검증한 후 정상 작동이 확인되면 전체 조직으로 확대하는 것을 권장합니다.