웨이신 (WeChat)
Hermes를 WeChat (소형 검찰), Tencent의 개인 메시징 플랫폼에 연결하세요. 어댑터는 Tencent's iLink Bot API를 사용하여 개인 WeChat 계정 — 이것은 WeCom (Enterprise WeChat)과 구별됩니다. 메시지는 긴 폴링을 통해 전달됩니다, 그래서 공공 엔드 포인트 또는 webhook가 필요하지 않습니다.
이 어댑터는 personal WeChat 계정 (소비자)입니다. 엔터프라이즈/corporate WeChat이 필요한 경우 대신 WeCom adapter를 참조하세요. 주요 특징
QR 로그인은 Hermes를 iLink bot identity(예: a5ace6fd482e@im.bot)에 연결해,not는 완전히 스크립트를 사용할 수 있는 일반 개인 WeChat 계정입니다. 단점:
- iLink bot identity는 일반적으로 일반 WeChat 그룹으로 초대 할 수 없습니다 정상적인 연락처는 할 수 있습니다.
- iLink는 일반적으로 일반 WeChat 그룹 이벤트를 제공하지 않습니다 (
@-mentions of personal account used for QR login) 대부분의 봇 유형 계정에 대한 게이트웨이에. - QR 코드를 스캔하는 데 사용되는 개인 WeChat 계정
@-mentioning은 **@-mentioning과 동일 - 봇은 별도의 정체성입니다. - 아래
WEIXIN_GROUP_POLICY/WEIXIN_GROUP_ALLOWED_USERS설정은 iLink가 실제 계정 유형에 대한 그룹 이벤트를 반환 할 때만 영향을받습니다. 그렇지 않은 경우 그룹 메시지는 정책에 관계없이 Hermes에 결코 도달하지 않습니다.
연습에서 대부분의 배포는 DM을 iLink bot 작업에 의존합니다. 그룹 납품이 구성 후에 작동하지 않는 경우에, 제한은 Hermes에서 iLink 측에, 입니다. 게이트웨이는 WEIXIN_GROUP_POLICY가 disabled보다 다른 모든 것을 설정할 때마다 WARNING를 시작합니다.
주요 특징
필수품
- 개인 WeChat 계정
- 파이썬 패키지:
aiohttp및cryptography - 단자 QR 렌더링은 헤르메스가
messaging에 설치될 때 포함되어 있습니다.
필요한 의존도를 설치하세요:
사이트맵
설치
##1. 설정 마법사를 실행
WeChat 계정을 연결하는 가장 쉬운 방법은 대화형 설정으로 표시됩니다.
hermes gateway setup
Weixin를 선택하면 프롬프트합니다. 마법사는:
- iLink Bot API에서 QR 코드를 요청
- 터미널에 있는 QR 부호를 표시하세요 (또는 URL을 제공합니다)
- WeChat 모바일 앱으로 QR 코드를 스캔할 수 있습니다.
- 휴대폰에 로그인 확인
- 계정 자격 증명을
~/.hermes/weixin/accounts/로 자동적으로 저장하세요
확인되면 다음과 같은 메시지를 볼 수 있습니다.
사이트맵
마법사는 account_id, token 및 base_url를 저장하므로 수동으로 구성할 필요가 없습니다.
##2. 환경 변수 구성
초기 QR 로그인 후 최소 계정 ID를 ~/.hermes/.env로 설정하세요.
사이트맵
##3. 게이트웨이 시작
hermes gateway
어댑터는 저장된 자격 증명을 복원하고 iLink API에 연결하고 메시지를 위해 긴 오염을 시작합니다.
특징
- **Long-poll 수송 ** - 대중적인 엔드포인트, webhook, 또는 WebSocket 필요 없음
- **QR 코드 로그인 ** -
hermes gateway setup를 통해 스캔 연결 설정 - **DM 메시징 ** - 구성 가능한 액세스 정책; 그룹 메시징은 iLink에 실제로 그룹 이벤트를 제공 (iLink bot 계정의 경우를 제외하고 - 위의 경고 참조)
- Media support - 이미지, 비디오, 파일 및 음성 메시지
- **AES-128-ECB 암호화 CDN ** - 모든 미디어 전송을위한 자동 암호화 / 암호 -컨텍스트 Token persistence — 재시작 전의 Disk-backed Answer 연속성 -Markdown formatting - 헤더, 테이블 및 코드 블록을 포함한 Markdown을 보존하므로 Markdown을 지원하는 WeChat 클라이언트는 기본적으로 렌더링 할 수 있습니다. -Smart message chunking — 메시지는 한계의 밑에 있을 때 단 하나 거품으로 체재합니다; 논리 경계에서 분할된 대형 페이로드만 -Typing Indicators - 에이전트 프로세스 동안 WeChat 클라이언트의 "typing..."상태를 보여줍니다.
- SSRF Protection - 아웃바운드 미디어 URL은 다운로드하기 전에 유효합니다. -Message deduplication — 5분 슬라이딩 윈도우는 이중 처리
- backoff와 자동 리트리 - transient API 오류에서 복구
구성 옵션
platforms.weixin.extra의 config.yaml에서 이러한 설정:
| 키 | 기본 | 설명 |
|---|---|---|
account_id | iLink Bot 계정 ID (필수) | |
token | 이링크 봇 토큰 (필수, QR 로그인에서 자동 입력) | |
base_url | https://ilinkai.weixin.qq.com | iLink API 기본 URL |
cdn_base_url | https://novac2c.cdn.weixin.qq.com/c2c | 미디어 전송의 CDN 기본 URL |
dm_policy | open | DM 액세스: open, allowlist, disabled, pairing |
group_policy | disabled | 그룹 액세스: open, allowlist, disabled |
allow_from | `` | DM(dm policy=allowlist)에서 사용 가능한 사용자 ID |
group_allow_from | `` | 그룹 ID 허용(그룹 policy=allowlist) |
split_multiline_messages | false | true가 있을 때 멀티라인을 여러 채팅 메시지로 재생합니다. false의 경우, 길이 제한을 초과하지 않는 한 하나의 메시지로 멀티 라인 replies를 유지합니다. |
액세스 정책
DM 정책
봇에 직접 메시지를 보낼 수있는 제어:
| 가치 | 행동 |
|---|---|
open | 누구나 DM 봇(기본) |
allowlist | allow_from의 사용자 ID만 DM |
disabled | 모든 DM은 무시 |
pairing | 페어링 모드(초기 설정) |
WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2
그룹 정책
bot이 when iLink가 연결된 ID의 그룹 이벤트를 제공합니다. QR-login iLink bot identities (e.g. ...@im.bot)의 경우, 그룹 이벤트는 일반적으로 전혀 전달되지 않습니다. 따라서이 정책에는 영향을 미치지 않을 수 있습니다. - 페이지 상단의 iLink bot 제한 경고를 참조하세요.
| 가치 | 행동 |
|---|---|
open | 봇은 모든 그룹에 대응합니다(이벤트가 전달되는 경우) |
allowlist | 봇은 group_allow_from에 나열된 그룹 ID에 대해서만 대응합니다. |
disabled | 모든 그룹 메시지가 무시됩니다(과태) |
사이트맵
기본 그룹 정책은 Weixin의 disabled입니다 (open에 기본적으로있는 WeCom와 동일). 이것은 의도적 - 개인 WeChat 계정은 많은 그룹에있을 수 있으며, iLink bot identities는 일반적으로 일반 WeChat 그룹 메시지를받을 수 없습니다. 게이트웨이는 WARNING를 WEIXIN_GROUP_POLICY를 disabled보다 다른 모든 것에 설정하면 시작시 WARNING를 기록합니다.
주요 특징
미디어 지원
인바운드 (receiving)
어댑터는 사용자의 미디어 첨부 파일을 수신, WeChat CDN에서 다운로드, 그들을 해독, 에이전트 처리에 로컬로 캐시:
| 유형 | 취급 방법 |
|---|---|
| Images | 다운로드, AES 암호화, JPEG로 캐시. |
| Video | 다운로드, AES 암호화, MP4로 캐시. |
| Files | 다운로드, AES 암호화, 캐시. 원본 파일명은 보존됩니다. |
| 인포메이션 text transcription을 사용할 수 있다면 텍스트로 추출됩니다. 그렇지 않으면 오디오 (SILK 형식)가 다운로드 및 캐시되었습니다. · |
Quoted 메시지: 인용 된 (replied-to) 메시지에서 미디어도 추출되므로 사용자가 회신하는 것에 대해 동의해야합니다.
# # AES-128-ECB CDN 암호화
WeChat 미디어 파일은 암호화 된 CDN을 통해 전송됩니다. 접합기는 이 투명하게 취급합니다:
- 상행: 암호화 된 미디어는
encrypted_query_paramURL을 사용하여 CDN에서 다운로드 한 다음 메시지 페이로드에서 제공 된 파일 키를 사용하여 AES-128-ECB로 해독됩니다. - 상행: 파일은 랜덤 AES-128-ECB 키로 로컬로 암호화되며, CDN에 업로드된 암호화된 참조는 아웃바운드 메시지에 포함되어 있습니다.
- AES 키는 16 바이트 (128 비트)입니다. Keys는 raw base64 또는 hex-encoded로 도착할 수 있습니다. 어댑터는 모두 형식을 처리합니다.
cryptographyPython 패키지가 필요합니다.
구성이 필요하지 않습니다 - 암호화 및 해독은 자동으로 발생합니다.
# 아웃바운드 (끝)
| 방법 | 그것이 보내는 것 |
|---|---|
send | Markdown 형식의 문자 메시지 |
send_image / send_image_file | 기본 이미지 메시지(CDN 업로드) |
send_document | 파일 첨부 파일(CDN 업로드) |
send_video | 비디오 메시지(CDN 업로드) |
모든 아웃 바운드 미디어는 암호화 된 CDN 업로드 흐름을 통해 간다:
- 임의 AES-128 키 생성
- AES-128-ECB + PKCS#7 패딩 파일 암호화
- iLink API (
getuploadurl)에서 업로드 URL을 요청하세요. - CDN에 ciphertext를 업로드
- 암호화된 매체 참고를 가진 메시지를 보내십시오
컨텍스트 토큰 지속
iLink Bot API는 context_token가 주어진 동료를 위한 각 아웃바운드 메시지로 다시 정정해야 합니다. 어댑터는 디스크 백업 컨텍스트 토큰 저장소를 유지합니다.
- 토큰은 account+peer에서
~/.hermes/weixin/accounts/<account_id>.context-tokens.json에 저장됩니다 - 초기에, 이전에 저장된 토큰은 복원됩니다.
- 모든 inbound 메시지는 그 sender에 대한 저장된 토큰을 업데이트합니다.
- 아웃바운드 메시지는 최신 컨텍스트 토큰을 자동으로 포함합니다.
이것은 게이트웨이 재시작 후에도 응답 continuity를 지킵니다.
Markdown 포맷
iLink Bot API를 통해 연결된 WeChat 클라이언트는 Markdown을 직접 렌더링 할 수 있으므로 어댑터는 다시 작성 대신 Markdown을 보존합니다.
-Headers Markdown headings로 유지 (#, ##,...)
- **Tables ** Markdown 테이블로 숙박
- 코드 울타리 울타리 코드 블록으로 유지
- Excessive blank line는 울타리 코드 블록 외부의 이중 신라인으로 붕괴됩니다.
메시지 Chunking
메시지는 플랫폼 제한 내에서 적합한 단일 채팅 메시지로 전달됩니다. 만 대형 페이로드는 배달을 위해 나뉩니다.
- 최대 메시지 길이: 4000 문자
- 여러 단락이나 라인 브레이크를 포함 할 때도 제한의 메시지
- 논리 경계 (paragraphs, 공백 선, 부호 담)에 분할되는 대형 메시지
- 코드 울타리는 가능한 한 무관하게 유지됩니다 ( 울타리 자체가 한계를 초과하지 않는 한 중 차단)
- 대형 개별 블록은 기본 어댑터의 truncation 논리로 돌아갑니다.
- 0.3 s inter-chunk 지연은 다중 펑크가 전송될 때 WeChat rate-limit drops를 방지합니다.
타이핑 표시
the adapter shows typing status in the WeChat 클라이언트:
- 메시지가 도착하면 어댑터는
typing_ticket를 통해getconfigAPI를 fetches - 타이핑 티켓은 사용자 당 10 분 동안 캐시됩니다.
send_typing는 typing-start 신호를 보냅니다;stop_typing는 typing 정지 신호를 보냅니다- 게이트웨이는 자동으로 표시 표시를 트리거하고 에이전트가 메시지를 처리하는 동안
Long-Poll 연결
어댑터는 HTTP long-polling (WebSocket)을 사용하여 메시지를 수신합니다.
어떻게 작동합니까?
- 연결: 자격 증명을 검증하고 poll 루프를 시작합니다.
- Poll: 35초 간격으로
getupdates. 서버는 메시지가 도착하거나 타임아웃이 만료될 때까지 요청을 보유합니다. - 배치: 인바운드 메시지는
asyncio.create_task를 통해 동시 파견됩니다. - 동기화 버퍼: 영구 동기화 커서 (
get_updates_buf)는 디스크에 저장되므로 어댑터가 다시 시작 후 올바른 위치에서 다시 시작합니다.
# # # Retry Behavior의
API 오류에서 어댑터는 간단한 리트리 전략을 사용합니다.
| 조건 | 행동 | 행동 |
|-----------|------|
| 일시적인 오류(1st–2nd) | 2초 후 재시동 |
| 반복 오류 (3+) | 30초 동안 다시, 카운터 재설정 |
| 세션이 만료됨(errcode=-14) | 10분간 일시 중지 |
| 시간표 | 즉시 재포장(일반적인 긴팔 행동) |
# 신청
인바운드 메시지는 5 분 창으로 메시지 ID를 사용하여 deduplicated. 이것은 네트워크 hiccups 또는 overlapping poll 응답 도중 두 배 가공을 방지합니다.
토큰 잠금
하나의 Weixin 게이트웨이 인스턴스만 한 번에 주어진 토큰을 사용할 수 있습니다. 어댑터는 시작시 범위의 잠금을 획득하고 종료시 해제됩니다. 다른 게이트웨이가 이미 동일한 토큰을 사용하고 있다면, 시작은 비공식 오류 메시지가 실패합니다.
모든 환경 변수
| 변수 | 필수 | 기본 | 설명 |
|---|---|---|---|
WEIXIN_ACCOUNT_ID | ✅ | – | 아이링크 봇 계정 ID( QR 로그인) |
WEIXIN_TOKEN | ✅ | – | 아이링크 봇 토큰( QR 로그인에서 자동 입력) |
WEIXIN_BASE_URL | https://ilinkai.weixin.qq.com | ||
WEIXIN_CDN_BASE_URL | https://novac2c.cdn.weixin.qq.com/c2c | ||
WEIXIN_DM_POLICY | open | ||
WEIXIN_GROUP_POLICY | disabled | 그룹 액세스 정책: open, allowlist, disabled | |
WEIXIN_ALLOWED_USERS | - | (empty) | DM 수표용 사용자 ID |
WEIXIN_GROUP_ALLOWED_USERS | - | (empty) | 그룹 채팅 ID**(회원 사용자 ID) 변수 이름은 레거시입니다 - 그것은 그룹 ID를 기대, 사용자 ID. |
WEIXIN_HOME_CHANNEL | |||
WEIXIN_HOME_CHANNEL_NAME | Home | ||
WEIXIN_ALLOW_ALL_USERS | - |
문제 해결
| 문제 | 해결 |
|---|---|
Weixin startup failed: aiohttp and cryptography are required | 설치: pip install aiohttp cryptography |
Weixin startup failed: WEIXIN_TOKEN is required | QR 로그인을 완료하려면 hermes gateway setup를 실행하거나 WEIXIN_TOKEN를 수동으로 설정하세요 |
Weixin startup failed: WEIXIN_ACCOUNT_ID is required | WEIXIN_ACCOUNT_ID를 .env로 설정하거나 hermes gateway setup를 실행 |
Another local Hermes gateway is already using this Weixin token | 토큰 당 다른 게이트웨이 인스턴스를 먼저 중지하고 있음 |
세션 만료(errcode=-14) | 로그인 세션이 만료되었습니다. 다시 실행 hermes gateway setup 새로운 QR 코드를 스캔 |
| 설정 중에 QR코드가 만료되었습니다 | QR 자동 재시동 3회 만료를 유지하면 네트워크 연결 확인 |
| 봇은 DM에 대응하지 않습니다. | WEIXIN_DM_POLICY를 확인하시고, allowlist로 설정하면, 송신자는 WEIXIN_ALLOWED_USERS에 있어야 합니다 |
| 봇은 그룹 메시지를 무시합니다 | 그룹 정책은 disabled에 기본입니다. WEIXIN_GROUP_POLICY=open 또는 allowlist를 설정하지만 QR-login iLink bot identities (...@im.bot)는 일반적으로 일반 WeChat 그룹 메시지를받을 수 없습니다. 게이트웨이가 그룹 메시지에 대한 원시 인바운드 이벤트를 표시하지 않는 경우, 제한은 Hermes가 아닌 iLink 측에 있습니다. |
| 미디어 다운로드/업로드 실패 | cryptography가 설치되어 있습니다. novac2c.cdn.weixin.qq.com에 네트워크 액세스 확인 |
Blocked unsafe URL (SSRF protection) | 인바운드 미디어 URL은 개인/내부 주소입니다. 공공 URL은 허용됩니다 |
| 음성 메시지가 텍스트로 표시됩니다 | WeChat이 transcription을 제공하는 경우, 어댑터는 텍스트를 사용합니다. 이것은 예상된 행동 |
| 메시지가 복제되었습니다 | 메시지 ID에 의한 어댑터 복제 중복을 볼 경우, 여러 게이트웨이 인스턴스가 실행되는 경우 확인 |
iLink POST... HTTP 4xx/5xx | iLink 서비스에서 API 오류. 토큰 유효성 및 네트워크 연결 확인 |
| 터미널 QR 코드가 렌더링되지 않습니다 | 메시징 추가 재설치: pip install hermes-agent[messaging]. 대신 QR 위에 인쇄 된 URL을 엽니 다 |