Docs

WeChat Bot

QR 코드를 스캔해 iLink를 통해 WeChat 계정을 Multica 에이전트에 연결합니다.

Multica는 Tencent의 OpenClaw Weixin 플러그인이 구현한 프로토콜을 사용해 WeChat iLink Bot 서비스에 연결합니다. WeCom과는 별도 채널입니다. OpenClaw를 설치하거나 데스크톱 WeChat 자동화 도구를 실행할 필요가 없습니다.

연결하기

  1. 내가 소유한 에이전트를 엽니다. 워크스페이스 소유자나 관리자는 워크스페이스의 모든 에이전트에 연결할 수 있습니다. 메시지 채널에서 메시지 채널 추가 를 선택한 뒤 WeChat 을 선택합니다. QR 코드가 바로 표시됩니다.
  2. 본인의 WeChat 계정 으로 QR 코드를 스캔하고 휴대폰에서 승인합니다. WeChat이 인증 코드를 요구하면 휴대폰에 표시된 숫자를 대화 상자에 입력합니다. 연결되면 대화 상자가 닫히고 에이전트의 메시지 채널에 WeChat이 표시됩니다.
  3. WeChat에서 Bot에 새 DM을 보냅니다. 에이전트가 작업을 실행하려면 온라인 런타임이 필요합니다.

스캔한 계정은 이 대화 상자를 연 Multica 사용자에게 연결됩니다. 메시지는 그 사용자의 워크스페이스 권한으로 실행됩니다. QR 코드를 공유하거나 다른 사람에게 스캔을 부탁하지 마세요. 다른 WeChat 계정이나 그룹의 메시지는 받지 않습니다.

로그인 유효 시간은 최대 5분이며, WeChat이 코드를 더 일찍 만료시킬 수도 있습니다. 만료되면 새 QR 코드를 생성하세요. 대화 상자를 닫으면 승인 대기 중인 로그인이 취소됩니다. 다른 에이전트나 워크스페이스에 연결된 Bot은 먼저 기존 연결을 해제해야 합니다. 계정 이용 자격은 WeChat이 결정하며, 연결을 거절하거나 추가 인증을 요구할 수 있습니다.

에이전트 설정의 WeChat QR 로그인

이 이미지의 QR 코드는 테스트용이며 실제 인증 코드가 아닙니다.

메시지와 명령

  • 텍스트 메시지는 같은 Multica 채팅을 이어갑니다. 최종 답변은 일반 텍스트로 WeChat에 전달되며, 긴 답변은 Unicode 문자가 손상되지 않도록 나눠 보냅니다. 스트리밍 메시지 편집은 지원하지 않습니다.
  • 에이전트가 실행되는 동안 가능하면 WeChat의 입력 중 표시를 갱신합니다. 완료, 실패 또는 취소 후에는 중단합니다. 갱신에 실패하면 다음 5초 주기에 다시 시도합니다. 표시 권한이 없거나 요청이 실패해도 메시지와 답변은 중단되지 않습니다.
  • /new [메시지] 는 새 Multica 채팅을 시작합니다. /clear [메시지] 는 현재 채팅에서 에이전트가 볼 수 있는 컨텍스트를 초기화합니다. /issue <제목> 은 연결된 에이전트에게 할당되는 태스크를 만듭니다.
  • 오브젝트 스토리지가 설정되어 있으면 받은 이미지, 파일, 동영상, 전사되지 않은 음성 메시지를 Multica 채팅에 첨부합니다. WeChat이 제공한 음성 전사는 텍스트로 사용합니다. Multica는 별도 음성 인식 서비스를 추가하거나 SILK 오디오를 변환하지 않습니다.
  • 에이전트의 최종 답변에 첨부된 파일은 WeChat으로 전달됩니다. 지원되는 이미지와 MP4 동영상은 네이티브 미디어 메시지로, 오디오를 포함한 다른 형식은 파일 메시지로 보냅니다. 이 어댑터의 전송 한도는 파일당 20 MiB 입니다. 파일 전송에 실패하면 안내를 보내며, 파일은 Multica에 남습니다.
  • 그룹 채팅, 연락처 접근, 선제 알림, 전달된 메시지 펼치기, 인용 메시지 기록 가져오기는 지원하지 않습니다.

답변에는 WeChat이 해당 대화에 발급한 컨텍스트 인증 정보가 필요합니다. 컨텍스트 만료로 답변이 거절되면 새 메시지를 보내세요. Multica는 유효 시간을 고정값으로 가정하지 않습니다. API 성공 응답은 제공자가 요청을 수락했다는 뜻이며, 전달이나 읽음을 보장하지 않습니다. 전송 결과 응답이 유실되면 결과 불명으로 기록하고 자동 재전송하지 않습니다.

부하가 높으면 WeChat 답변 알림이 생략될 수 있습니다. 답변은 Multica 채팅에서 확인할 수 있습니다.

연결 해제

에이전트의 메시지 채널에서 WeChat 관리 → 연결 해제 를 선택합니다. 새 메시지는 에이전트에 전달되지 않고, 저장된 답변 컨텍스트도 삭제됩니다. Multica 채팅 기록은 유지됩니다. iLink가 명시적으로 인증 만료 응답을 반환해도 연결을 비활성화하고 만료 안내를 표시합니다. 새 QR 코드를 스캔해 다시 연결하세요. 같은 에이전트의 기존 연결을 재인증하면 채팅과 수신 커서를 유지합니다. 같은 워크스페이스의 다른 에이전트에 이미 연결된 Bot이면 해당 에이전트를 관리할 수 있으면 대화 상자에 에이전트 이름을 표시하므로 먼저 그곳에서 연결을 해제하세요. 다른 워크스페이스의 에이전트 정보는 표시하지 않습니다.

워크스페이스 메시지 설정의 연결된 WeChat 계정

셀프 호스팅

영구 보관할 암호화 키를 생성합니다.

openssl rand -base64 32

API 서버의 MULTICA_WEIXIN_SECRET_KEY 로 설정하고 서버를 재시작합니다. 모든 레플리카에서 같은 키를 사용하고, 배포 시크릿 및 백업과 함께 보관하세요. 키를 바꾸면 기존 인증 정보를 복호화할 수 없어 Bot을 다시 연결해야 합니다. 키가 없으면 연결 기능이 비활성화됩니다. Docker Compose는 이 변수를 전달합니다.

API 서버는 ilinkai.weixin.qq.com, WeChat이 반환하는 *.weixin.qq.com 지역 호스트, novac2c.cdn.weixin.qq.com 에 HTTPS로 접근할 수 있어야 합니다. 공개 webhook이나 인바운드 터널은 필요 없습니다. 브라우저에는 QR 표시 내용과 상태만 전달하며, Bot 인증 정보와 답변 컨텍스트는 서버에 암호화하여 저장합니다.

일반 데이터베이스 마이그레이션을 적용하세요. 공통 채널 관리자가 레플리카 전체에서 연결 하나당 롱 폴링 하나를 유지하고, 공통 수신 엔진이 배치를 수락한 뒤 업데이트 커서를 저장합니다. 최종 답변은 데이터베이스 전달 임대로 중복 전송을 방지합니다. 전송 대기 이벤트는 메모리에 있어 서버 재시작 시 답변이 중단될 수 있으며, 결과가 불명확한 전송은 재시도하지 않습니다. 답변과 첨부파일은 Multica에 남습니다.

프로토콜 참조는 Tencent @tencent-weixin/openclaw-weixin 2.4.10, 소스 커밋 874637a 및 해당 프로토콜 문서입니다. 이 어댑터는 Go 네이티브 구현이며 실행 시 해당 패키지에 의존하지 않습니다. 제공자 동작과 계정 이용 자격은 Multica 릴리스와 별개로 바뀔 수 있습니다.

이 페이지에서