본문으로 건너뛰기

WeCom

최근 업데이트 2026. 10. 07.

1. 사전 조건​

  • WeCom 관리 콘솔 권한이 있어 스마트 봇을 생성할 수 있어야 합니다. OAuth가 필요한 경우 기업 자체 개발 앱도 생성해야 합니다.
  • Agentic Engine의 시스템 관리 → 채널 관리 권한이 있어야 합니다.
  • Agentic Engine 채널 관리 기능이 활성화되어 있어야 합니다.
  • 배포 서버가 WeCom 공식 롱 커넥션 주소 wss://openws.work.weixin.qq.com에 접근할 수 있어야 합니다.
  • 멤버 OAuth 연동이 필요한 경우, 플랫폼이 HTTPS로 사용자에게 공개되어 있어야 하며 사용 가능한 공인 도메인을 준비해야 합니다.

2. WeCom 스마트 봇 생성 및 자격 증명 획득​

WeCom 관리 콘솔에 로그인한 후 다음 단계에 따라 설정합니다.

  1. Security and Management -> Management Tools로 이동하여 Intelligent Bot을 찾은 후 Create Bot -> Create manually를 클릭합니다.
  2. 맨 아래로 스크롤하여 Create in API mode를 선택하고, 연결 방식은 Use persistent connection을 선택합니다.
  3. 봇 이름, 소개, 표시 범위를 입력하고 설정을 저장합니다.
  4. API 설정 영역에서 다음 자격 증명을 복사하여 안전하게 보관합니다.
WeCom 필드플랫폼 필드설명
Bot IDBot ID스마트 봇의 고유 식별자로, 롱 커넥션 인증에 사용됩니다.
SecretBot Secret스마트 봇 시크릿입니다. 안전한 곳에만 보관하고, 코드, 티켓 또는 채팅 기록에 남기지 마십시오.
팁

봇 공인 콜백 주소를 설정할 필요가 없습니다: Agentic Engine이 WebSocket 롱 커넥션을 직접 설정하고, Bot ID와 Bot Secret으로 인증을 완료합니다.

선택 사항: 멤버 OAuth 자체 개발 앱 생성​

OAuth는 봇의 메시지 송수신에 필수가 아닙니다. 사용자가 브라우저에서 WeCom 멤버 신원을 원클릭으로 연동해야 하는 경우에만 같은 기업에 자체 개발 앱을 생성하면 됩니다.

  1. WeCom 관리 콘솔에서 기업 자체 개발 앱을 생성하고, 사용할 멤버를 앱 표시 범위에 추가합니다.
  2. 기업 및 앱 자격 증명을 기록합니다.
WeCom 필드플랫폼 필드설명
Company IDCorp ID일반적으로 ww로 시작하며, 기업 정보에서 확인할 수 있습니다.
AgentIdAgent ID자체 개발 앱의 앱 ID입니다.
SecretCorp Secret자체 개발 앱의 Secret으로, 서버 측에서 멤버 신원을 가져오는 데 사용됩니다.

필수: 신뢰할 수 있는 도메인 및 URL(도메인) 주체 검증 완료​

WeCom OAuth에서 사용하는 콜백 도메인은 먼저 자체 개발 앱의 신뢰할 수 있는 도메인으로 설정해야 합니다. 신뢰할 수 있는 도메인을 저장하기 전에 WeCom은 도메인 소유권과 도메인 ICP 등록 주체를 함께 확인할 수 있으며, 두 항목 모두 통과해야 합니다.

  1. WeCom Admin Console > App Management > Self-built > 대상 앱 > Web Authorization and JS-SDK로 이동하여 Set Trusted Domain을 클릭합니다.
  2. 플랫폼의 실제 접속 도메인을 입력합니다(예: agent.example.com). 도메인만 입력하고 https://, 포트, 경로는 포함하지 않습니다. 서브도메인을 사용하는 경우 실제 서브도메인별로 따로 설정합니다.
  3. Apply for Domain Verification을 클릭하거나, 페이지 안내에 따라 WeCom이 생성한 WW_verify_*.txt 검증 파일을 다운로드합니다.
  4. 파일 이름과 내용을 변경하지 않은 채 해당 도메인의 웹사이트 루트 디렉터리에 파일을 배포합니다. 브라우저에서 직접 접근할 수 있는지 확인합니다.
域名所有权校验文件
https://agent.example.com/WW_verify_xxxxxxxxxxxx.txt
  1. 접근 결과로 검증 파일 내용이 그대로 반환되어야 하며, 로그인 페이지로 리디렉션되거나 인증에 의해 차단되거나 프런트엔드 SPA 페이지가 반환되어서는 안 됩니다.
  2. WeCom 관리 콘솔로 돌아가 Domain ownership verification file uploaded를 체크하고 저장합니다. 파일에 접근할 수 있는데도 실패하면 DNS/CDN 캐시를 확인하고 잠시 후 다시 시도합니다.
경고

URL 주체 검증: 신뢰할 수 있는 도메인의 ICP 등록 주체는 현재 WeCom의 인증/검증 주체와 일치하거나, WeCom이 인정하는 연관 관계가 있어야 합니다. "URL 주체 검증 실패" 또는 "도메인 주체 불일치"라는 안내가 표시되면 앱 코드로는 우회할 수 없습니다. 주체가 일치하는 등록된 도메인으로 변경하거나, 먼저 ICP 등록과 주체 연관을 완료한 후 설정해야 합니다.

구성 항목예시요구 사항
신뢰할 수 있는 도메인agent.example.comWeCom 관리 콘솔에는 호스트 이름만 입력
검증 파일 URLhttps://agent.example.com/WW_verify_xxxxxxxxxxxx.txt도메인 루트 디렉터리에 배포하고 파일 내용을 그대로 반환
OAuth 콜백 URLhttps://agent.example.com/agent/api/wecom-oauth/callback예시는 /agent 하위 경로를 사용하는 배포
출처 화이트리스트ALLOWED_ORIGINS=https://agent.example.com프로토콜과 호스트 이름을 입력하며, 경로는 포함하지 않음
팁

두 URL을 혼동하지 마십시오: 검증 파일은 반드시 도메인 루트 디렉터리에 있어야 하고, OAuth 콜백은 여전히 /agent/api/wecom-oauth/callback을 사용합니다. 두 경로는 다르지만 호스트 이름은 신뢰할 수 있는 도메인과 일치해야 합니다.

  1. 신뢰할 수 있는 도메인, 소유권, 주체 검증을 완료한 후 다음 OAuth 콜백 주소에 브라우저에서 정상적으로 접근할 수 있는지 확인합니다.
未配置子路径时
https://<your-domain>/agent/api/wecom-oauth/callback

운영 환경에서는 인증 출처 화이트리스트를 설정하는 것을 권장합니다. 여러 출처는 영문 쉼표로 구분합니다.

ALLOWED_ORIGINS=https://<your-domain>

3. 플랫폼에서 WeCom 채널 추가​

관리자가 Agentic Engine에 로그인하여 시스템 관리 → 채널 관리로 이동합니다:

  1. 새 채널을 클릭하고 채널 타입으로 WeCom을 선택합니다.
  2. 다음 구성 항목을 입력합니다:
구성 항목필수 여부설명
채널 이름필수표시 이름(예: "WeCom 봇")
Bot ID필수WeCom 스마트 봇의 Bot ID입니다.
Bot Secret필수WeCom 스마트 봇의 Secret입니다.
멤버 OAuth 바인딩 활성화선택활성화하면 브라우저 인증 연동을 우선 사용하며, 비활성화해도 연동 코드는 계속 사용할 수 있습니다.
Corp ID조건부 필수OAuth를 활성화하면 반드시 입력해야 합니다.
Agent ID조건부 필수OAuth를 활성화하면 반드시 입력해야 합니다.
Corp Secret조건부 필수OAuth를 활성화하면 반드시 입력해야 합니다.
기본 모델선택선택하지 않으면 시스템 전역 기본 모델을 사용합니다.
시스템 프롬프트선택이 채널의 Agent 대화에만 적용됩니다.
  1. 저장을 클릭한 다음 채널의 활성화 스위치를 켭니다.
  2. 채널 상태가 온라인으로 바뀌는지 확인합니다. 여전히 오프라인 또는 오류이면 이 문서의 문제 해결 섹션에 따라 확인합니다.
팁

채널 타입마다 인스턴스는 하나만 생성할 수 있습니다. Secret은 암호화되어 저장되며 다시 표시되지 않습니다. 채널을 편집할 때 Secret을 비워 두면 원래 값이 유지됩니다. OAuth를 끄면 OAuth 자격 증명 전체가 삭제됩니다.

4. 사용자 WeCom 계정 연동​

방법 1: OAuth 권한 부여 연동​

  1. 사용자가 Agentic Engine에 로그인하여 왼쪽 하단의 사용자 아바타를 클릭합니다.
  2. 계정 메뉴에서 WeCom을 찾아 연동을 클릭합니다.
  3. 시스템이 WeCom 멤버 인증 페이지를 열면, 사용자는 같은 기업의 내부 멤버 계정으로 인증을 완료합니다.
  4. 인증에 성공하면 창이 자동으로 닫히고, 메뉴의 WeCom 상태가 연동됨으로 바뀝니다.

방법 2: 일회용 연동 코드​

OAuth가 활성화되지 않았거나 플랫폼에 HTTP로 접속하는 경우, 시스템은 자동으로 연동 코드를 사용합니다.

  1. 왼쪽 하단의 사용자 아바타를 클릭하고, WeCom 행에서 연동을 클릭합니다.
  2. 시스템이 생성한 6자리 연동 코드를 복사합니다. 연동 코드는 10분간 유효하며 한 번만 사용할 수 있습니다.
  3. WeCom에서 스마트 봇에게 다음 명령 중 하나를 보냅니다.
绑定 ABC234
+bind ABC234

봇이 "WeCom 계정 연동 성공"이라고 답하면 플랫폼 메뉴가 자동으로 연동됨으로 업데이트됩니다. 같은 WeCom 멤버로 다른 Agentic Engine 사용자의 활성 연동을 덮어쓸 수 없습니다.

연결 해제​

  1. 왼쪽 하단의 사용자 아바타를 클릭하고, WeCom 행에서 연결 해제를 클릭합니다.
  2. 연결 해제를 확인하면 상태가 연동되지 않음으로 바뀝니다. Agentic Engine 계정을 변경하려면 먼저 기존 계정의 연결을 해제해야 합니다.

5. 자주 묻는 질문​

채널 상태가 오프라인 또는 오류인 경우​

  • Bot ID와 Bot Secret을 같은 스마트 봇에서 가져왔는지, 복사할 때 불필요한 공백이 들어가지 않았는지 확인합니다.
  • WeCom 관리 콘솔에서 봇이 비활성화되지 않았고, API 모드와 롱 커넥션이 선택되어 있는지 확인합니다.
  • 서버가 wss://openws.work.weixin.qq.com에 접근할 수 있는지 확인합니다.
  • Secret을 다시 생성하면 기존 값은 무효화됩니다. 채널을 편집하여 새 Secret을 입력하고 다시 활성화하십시오.

OAuth가 활성화되지 않았거나 설정이 불완전하다는 안내가 표시되는 경우​

  • WeCom 채널이 활성화되어 있고 멤버 OAuth 바인딩 활성화 스위치가 켜져 있는지 확인합니다.
  • Corp ID, Agent ID, Corp Secret이 모두 입력되어 있고, 같은 기업의 자체 개발 앱에서 가져온 값인지 확인합니다.
  • 자체 개발 앱의 표시 범위에 현재 멤버가 포함되어 있는지 확인합니다.

OAuth 콜백 실패​

  • 콜백 도메인, 프로토콜, 포트, 경로가 플랫폼의 실제 접속 주소와 완전히 일치하는지 확인합니다.
  • NEXT_PUBLIC_BASE_PATH를 사용하는 경우 콜백 주소에 해당 하위 경로가 포함되어야 합니다.
  • ALLOWED_ORIGINS를 설정한 경우 현재 접속 출처가 화이트리스트에 있는지 확인합니다.
  • OAuth 연동에는 반드시 기업 내부 멤버를 사용해야 하며, 외부 연락처는 연동을 지원하지 않습니다.

연동 코드가 유효하지 않거나 만료된 경우​

  • 연동 코드를 다시 생성하고 10분 이내에 사용합니다.
  • 명령 형식이 绑定 ABC234 또는 +bind ABC234인지 확인합니다.
  • 연동 코드는 한 번만 사용할 수 있으며, 이미 사용한 연동 코드는 다시 제출할 수 없습니다.

봇이 텍스트에는 답변하지만 첨부 파일을 읽지 못하는 경우​

  • channel.wecom.fileUploads.enabled가 꺼져 있지 않은지 확인합니다.
  • 지원되는 파일 형식인지, 단일 파일 크기와 메시지당 첨부 파일 수가 설정된 제한을 초과하지 않는지 확인합니다.
  • 샌드박스 첨부 파일 스토리지와 파일 API를 정상적으로 사용할 수 있는지 확인합니다.

템플릿 카드를 클릭해도 응답이 없는 경우​

  • 채널 롱 커넥션이 온라인 상태인지 확인합니다.
  • 카드에 해당하는 인터랙션이 만료되지 않았고 아직 응답되지 않았으며, 현재 클릭한 사용자가 연동된 사용자인지 확인합니다.
  • 서버가 WeCom이 요구하는 시간 내에 카드를 처리하고 업데이트할 수 있는지 확인합니다.

관련 페이지와 다음 단계

이 문서가 도움이 되었나요?
이 페이지의 내용