WeCom (위챗)
Hermes를 WeCom ( Ten信), Tencent의 엔터프라이즈 메시징 플랫폼에 연결하세요. 어댑터는 실시간 양방향 통신을위한 WeCom의 AI Bot WebSocket Gateway를 사용합니다. - 공공 엔드포인트 또는 webhook이 필요하지 않습니다.
필수품
- A WeCom 조직 계정
- WeCom 관리자 콘솔에서 만든 AI Bot
- 봇 ID와 비밀의 자격 증명 페이지
- 파이썬 패키지:
aiohttp및httpx
설치
단계 1: AI Bot 만들기
권장: 스캔-to-Create (하나의 명령)
사이트맵
** WeCom**를 선택하고 WeCom 모바일 앱으로 QR 코드를 스캔합니다. Hermes는 정확한 권한으로 봇 응용 프로그램을 자동으로 만들고 자격 증명을 저장합니다.
설정 마법사는:
- 터미널에 있는 QR 부호를 표시하세요
- WeCom 모바일 앱으로 스캔할 수 있습니다.
- Bot ID와 비밀을 자동 검색
- 액세스 제어 구성을 통해 안내
대안: 수동 체제
scan-to-create가 사용할 수없는 경우, 마법사는 수동 입력으로 돌아갑니다:
- [WeCom 관리자 콘솔]에 로그인 (https://work.weixin.qq.com/wework_admin/frame)
- ** 신청**→** 신청**→AI Bot
- 봇 이름과 설명 구성
- Bot ID및Secret를 credentials 페이지에서 복사하세요.
hermes gateway setup를 실행하고, ** WeCom**를 선택하고, 프롬프트 할 때 자격 증명을 입력하세요.
Bot 비밀 개인 유지. 봇을 무시할 수 있습니다. 주요 특징
단계 2: 헤르메스를 구성
선택권 A: 상호 작용하는 체제 (추천하는)
hermes gateway setup
** WeCom**를 선택하고 프롬프트를 따르십시오. 마법사를 통해 안내합니다:
- Bot credentials ( QR 검사 또는 수동 입력을 통해)
- 액세스 제어 설정 (도표, 페어링 모드, 또는 액세스 열기)
- 알림의 홈 채널
선택권 B: 수동 윤곽
다음을 ~/.hermes/.env에 추가하세요:
사이트맵
단계 3: 게이트웨이를 시작
사이트맵
특징
- **WebSocket 수송 ** - 영구 연결, 필요 없음
- **DM 및 그룹 메시징 ** - 설정 가능한 액세스 정책 -Per-group sender Allowlists - 각 그룹에서 상호작용할 수 있는 정밀한 편두통 제어
- Media support - 이미지, 파일, 음성, 비디오 업로드 및 다운로드
- **AES 암호화 미디어 ** - 인바운드 첨부 파일에 대한 자동 해독
- Quote 컨텍스트 - 응답 스레드 유지 -Markdown 렌더링 - 풍부한 텍스트 응답
- Reply-mode Streaming - inbound 메시지 컨텍스트에 대한 응답을 상관
- 자동 연결 - 연결 방울에 폭발성 백 오프
구성 옵션
config.yaml에서 이러한 설정 platforms.wecom.extra:
| 키 | 기본 | 설명 |
|---|---|---|
bot_id | ||
secret | ||
websocket_url | wss://openws.work.weixin.qq.com | 웹소켓 게이트웨이 URL |
dm_policy | open | DM 액세스: open, allowlist, disabled, pairing |
group_policy | open | 그룹 액세스: open, allowlist, disabled |
allow_from | `` | DM(dm policy=allowlist)에서 사용 가능한 사용자 ID |
group_allow_from | `` | 그룹 ID 허용(그룹 policy=allowlist) |
groups | {} | Per-group 구성(아래 참조) |
액세스 정책
DM 정책
봇에 직접 메시지를 보낼 수있는 제어:
| 가치 | 행동 |
|---|---|
open | 누구나 DM 봇(기본) |
allowlist | allow_from의 사용자 ID는 DM |
disabled | 모든 DM은 무시 |
pairing | 페어링 모드(초기 설정) |
WECOM_DM_POLICY=allowlist
그룹 정책
봇이 응답하는 컨트롤:
| 가치 | 행동 |
|---|---|
open | 봇은 모든 그룹에 대응합니다(기본) |
allowlist | 봇은 group_allow_from에 나열된 그룹 ID에서만 대응합니다 |
disabled | 모든 그룹 메시지가 무시됩니다 |
WECOM_GROUP_POLICY=allowlist
# Per-Group Sender 허용 목록
편두통 통제를 위해, 당신은 특정한 그룹 내의 봇과 상호 작용할 수 있는 제한할 수 있습니다. 이것은 config.yaml에서 형성됩니다:
사이트맵
일부:
group_policy및group_allow_from컨트롤은 그룹이 허용 여부를 결정합니다.- 그룹이 최고 수준의 체크를 통과하면
groups.<group_id>.allow_from목록 (현재)은 그 그룹 내에서 보내는 제한이 봇과 상호 작용할 수 있습니다. - 와일드 카드
"*"그룹 항목은 명시적으로 나열되지 않은 그룹에 대한 기본 역할을합니다. - 허용표 항목은 모든 사용자를 허용하기 위해
*와일드카드를 지원하며, 항목은 현명합니다. - 항목은 선택적으로
wecom:user:또는wecom:group:접두사 형식을 사용할 수 있습니다 - 접두사는 자동으로 벗겨집니다.
allow_from가 그룹에 구성되지 않은 경우, 해당 그룹의 모든 사용자는 허용됩니다 (그룹 자체가 최상위 정책 검사를 통과).
미디어 지원
인바운드 (receiving)
어댑터는 사용자가 미디어 첨부 파일을 수신하고 에이전트 처리에 대해 로컬로 캐시합니다.
| 유형 | 취급 방법 |
|---|---|
| Images | 현지에서 다운로드 및 캐시 URL 기반 및 base64 인코딩 이미지 모두 지원. · |
| Files | 다운로드 및 캐시. 파일명은 원본 메시지에서 보존됩니다. |
| Voice | 음성 메시지 텍스트 transcription을 사용할 수 있습니다. |
| Mixed message | WeCom Mix-type 메시지(텍스트 + 이미지)는 파싱 및 모든 구성품이 추출되어 있습니다. · |
Quoted 메시지: 인용 된 (replied-to) 메시지에서 미디어도 추출되므로 사용자가 회신하는 것에 대해 동의해야합니다.
AES 암호화 미디어 해독
WeCom는 AES-256-CBC와 일부 인바운드 미디어 첨부 파일을 암호화합니다. 어댑터는 자동으로 핸들:
- 인바운드 미디어 항목에는
aeskey필드가 포함되어있을 때 어댑터는 암호화 된 바이트를 다운로드하고 PKCS#7 패딩을 사용하여 AES-256-CBC를 사용하여 해독합니다. - AES 키는
aeskey필드의 base64-decoded 값입니다 ( 정확히 32 바이트). - IV는 키의 첫 번째 16 바이트에서 파생됩니다.
cryptographyPython 패키지 (pip install cryptography)가 필요합니다.
구성이 필요하지 않습니다 - 암호 해독은 암호화 된 미디어가 수신되면 투명하게 발생합니다.
# 아웃바운드 (끝)
| 방법 | 보낼 곳 | 크기 제한 |
|---|---|---|
send | 마크다운 텍스트 메시지 | 4000 char |
send_image / send_image_file | 기본 이미지 메시지 | 10 MB |
send_document | 파일 첨부 | 20 MB |
send_voice | 음성 메시지(기본 음성 전용) | |
send_video | 비디오 메시지 | 10 MB |
Chunked 업로드: 파일이 3단계 프로토콜을 통해 512 KB의 펑크에 업로드됩니다 (init → chunks → finish). 어댑터가 자동으로 처리됩니다.
자동 다운 그레이드: 미디어가 기본 유형의 크기 제한을 초과하지만 절대 20 MB 파일 제한 아래는 대신 일반적인 파일 첨부 파일로 자동 전송됩니다:
- 이미지 > 10 MB → 파일로 전송
- 비디오 > 10 MB → 파일로 전송
- 음성 > 2 MB → 파일로 전송
- Non-AMR 오디오 → 파일로 전송 (기본 음성을 위한 AMR만 지원)
절대 제한을 초과하는 파일은 채팅에 전송된 정보 메시지로 거부됩니다.
대답-모드 스트림 응답
봇이 WeCom 콜백을 통해 메시지를 수신하면 어댑터는 인바운드 요청 ID를 기억합니다. 응답이 전송되는 동안 요청 컨텍스트는 여전히 활성, 어댑터는 WeCom의 응답 모드 (aibot_respond_msg)를 사용하여 인바운드 메시지에 직접 응답을 수정합니다. 이 WeCom 클라이언트의 더 자연스러운 대화 경험을 제공합니다.
인바운드 요청 컨텍스트가 만료되거나 사용되지 않은 경우 어댑터는 aibot_send_msg를 통해 전송하는 유동 메시지로 돌아갑니다.
응답 모드 또한 미디어에 대 한 작동: 업로드 된 미디어 시작 메시지에 회신으로 보낼 수 있습니다.
연결 및 연결
어댑터는 wss://openws.work.weixin.qq.com의 WeCom의 게이트웨이에 지속적인 WebSocket 연결을 유지합니다.
# 연결 수명주기
- 연결: WebSocket 연결을 열고 bot id와 비밀을 가진
aibot_subscribe인증 프레임을 보냅니다. - **Heartbeat: ** 애플리케이션 레벨 핑 프레임을 30초마다 전송하여 연결이 살아있을 수 있습니다. 3.Listen: 지속적으로 인바운드 프레임을 읽고 메시지 콜백을 파견합니다.
재연결 Behavior
연결 손실에, 접합기는 reconnect에 exponential backoff를 이용합니다:
| 지연 | |---|-------| | 제1회 리트리 | 2초 | | 제2회 리트리 | 5초 | | 제3회 리트리 | 10초 | | 제4회 리트리 | 30초 | | 5초 | 60초 |
각 성공적인 재연결 후, 백오프 카운터가 0으로 재설정됩니다. 모든 보류 요청 선물은 차단에 실패하므로 콜러는 무한하게 걸지 않습니다.
# 신청
인바운드 메시지는 5 분 창과 1000 항목의 최대 캐시로 메시지 ID를 사용하여 deduplicated입니다. 이것은 reconnection 또는 네트워크 hiccups 도중 메시지의 두 배 가공을 방지합니다.
모든 환경 변수
| 변수 | 필수 | 기본 | 설명 |
|---|---|---|---|
WECOM_BOT_ID | ✅ | – | WeCom AI 봇 ID |
WECOM_SECRET | ✅ | - | WeCom AI Bot 비밀 |
WECOM_ALLOWED_USERS | (empty) | 게이트웨이 레벨 수표용 사용자 ID | |
WECOM_HOME_CHANNEL | |||
WECOM_WEBSOCKET_URL | wss://openws.work.weixin.qq.com | ||
WECOM_DM_POLICY | open | ||
WECOM_GROUP_POLICY | open |
문제 해결
| 문제 | 해결 |
|---|---|
WECOM_BOT_ID and WECOM_SECRET are required | 설정 마법사를 모두 설정할 수 있습니다 |
WeCom startup failed: aiohttp not installed | 설치 aiohttp: pip install aiohttp |
WeCom startup failed: httpx not installed | 설치 httpx: pip install httpx |
invalid secret (errcode=40013) | 봇의 자격 증명에 비밀을 검증 |
Timed out waiting for subscribe acknowledgement | openws.work.weixin.qq.com의 네트워크 연결 확인 |
| 봇은 그룹에 반응하지 않습니다 | group_policy 설정 확인 및 그룹 ID는 group_allow_from |
| 봇은 그룹에서 특정 사용자를 무시합니다 | allow_from 목록에 groups 구성 섹션에서 확인 |
| 미디어 해독 실패 | 설치 cryptography: pip install cryptography |
cryptography is required for WeCom media decryption | 인바운드 미디어는 AES 암호화입니다. 설치: pip install cryptography |
| 파일로 전송되는 음성 메시지 | WeCom는 기본 음성을 위한 AMR 형식만 지원합니다. 다른 형식은 파일로 자동화됩니다. |
File too large 에러 | WeCom에는 모든 파일 업로드에 절대 제한이 있습니다. 파일을 압축하거나 분할합니다. |
| 이미지는 파일로 전송됩니다 | 이미지 > 10 MB는 기본 이미지 제한을 초과하고 파일 첨부에 자동 다운 그레이드입니다. · |
Timeout sending message to WeCom | 웹소켓이 분리될 수 있습니다. 재연결 메시지에 대한 로그를 확인합니다. |
WeCom websocket closed during authentication | 네트워크 문제 또는 잘못된 증명. bot id와 비밀을 확인합니다. |