Agent WeChat
사람과 AI 에이전트를 위한 오픈 소스 WeChat 클라이언트입니다.
대안적인 WeChat 데스크톱 클라이언트를 사용하거나, 터미널에서 작업하거나, AI 에이전트를 연결할 수 있습니다. 동일한 API를 통해 대화를 읽고, 미디어를 교환하며, 자신만의 도구를 구축하세요. Agent WeChat은 WeChat과 직접 통신하며, 백그라운드 서비스(daemon)가 공식 앱이 실행될 필요는 없습니다.
시작하기 · 문서화 · OpenClaw · 다운로드
사용 예시 보기
93초 데모 시청하기 · 비디오 다운로드
Nick Bot과의 한 대화: 휴대폰에서 질문하고, 음성으로 답장하며, 데스크톱 클라이언트에서 이미지 요청을 하고, 터미널에서 결과를 저장하는 과정입니다. 녹화된 영상은 이 데모에 사용된 빌드를 보여주며, 현재 설정 및 플랫폼 상태는 아래 링크되어 있습니다.
데스크톱 인터페이스
Agent WeChat desktop showing an image reply from Nick Bot; other conversations are blurred
WeChat 음성 통화
시작하기
데스크톱 앱
- GitHub Releases에서 사용하려는 플랫폼의 설치 프로그램을 다운로드합니다.
- 로컬 허브를 실행하려면 **이 장치 사용(Use this device)**을 선택하거나, **다른 허브에 연결(Connect to another hub)**합니다.
- WeChat 프로필을 추가하고 휴대폰에서 로그인 지침을 따릅니다.
이 앱에는 채팅 인터페이스, 네이티브 허브, 그리고 wx CLI가 포함되어 있습니다. 설치 프로그램, 시스템 요구 사항, 연결 키 및 네트워킹에 대한 자세한 내용은 [데스크톱 가이드]를 참조하세요. 데스크톱 패키징과 설치된 앱 승인 여부는 플랫폼마다 다르므로, 사용하려는 빌드의 플랫폼 상태와 릴리스 노트를 확인하십시오.
터미널 및 API
npm을 사용하여 네이티브 CLI를 설치한 다음, 백그라운드 서비스(daemon)를 시작합니다:
pm install -g @agent-wechat/cli
wx --json version
wx serve
패키지의 설치 스크립트가 네이티브 실행 파일을 다운로드하고 검증할 수 있도록 허용해야 합니다. 설치 대안에는 pnpm, 독립형 바이너리(standalone binaries), 그리고 Docker가 포함됩니다. 음성/비디오 준비를 위해 데몬 호스트에 FFmpeg과 FFprobe를 설치해야 합니다. (데스크톱 앱이 이들을 번들링합니다.)
기존에 지원되는 WeChat for Linux 프로필이 있는 경우, 공식 앱을 닫고 파일을 백업한 다음 두 번째 터미널에서 실행합니다:
wx auth login --official
wx accounts list
wx chats list
...
데몬이 해당 프로필을 사용하는 동안에는 공식 앱을 닫아 두어야 합니다. 대신 별도의 프로필을 생성하려면 계정 연결을 참조하세요. 새 프로필은 이전 전체 채팅 기록을 받지 못합니다. 여러 계정이 있는 경우, --account ID_OR_ALIAS를 사용하여 하나를 선택하십시오.
연결이 완료되면 대화를 검사하고 첨부 파일을 저장할 수 있습니다:
wx contacts find Alice
wx messages list CHAT_ID --limit 20
wx messages media CHAT_ID MESSAGE_ID --output ./saved-image.jpg
자세한 내용은 CLI 예제, API 문서, 그리고 호스팅 옵션을 참조하세요.
WeChat 기능
| 영역 (Area) | 할 수 있는 것 (What you can do) |
|---|
| 대화 (Conversations) | DM 및 그룹 사용; 로컬에 저장된 기록 탐색 및 검색; 읽지 않은 메시지 수 확인 및 채팅 표시 읽음 처리. |
발신된 인용 답장(quoted replies) 및 링크 카드 전송은 구현되었으나 아직 실시간 수신자 검증을 기다리고 있습니다. 미디어 가용성은 수신 소스, 지원되는 형식, 크기 제한에 따라 달라집니다. 검색은 저장된 기록을 다루며, 모든 원격 기록을 포함하지는 않습니다. 메시지 유형 (message types), 미디어 (media), 그룹 (groups) 및 구현 및 검증 체크리스트 (implementation and validation checklist)를 참조하십시오.
기존 공식 프로필 사용하기 (Use your existing official profile)
Agent WeChat은 기존의 공식 WeChat for Linux 프로필 내에서 지원되는 쓰기 작업을 읽고 계속할 수 있습니다 (in place). 이 기능은 계정 신원을 유지하며 저장된 대화, 연락처, 그룹 및 미디어를 사용합니다.
| 프로필 데이터 (Profile data) | 읽기 (Read) | 쓰기 (Write) |
|---|
| 메시지 (Messages) | 저장된 기록 및 지원되는 풍부한 콘텐츠 (rich content) | 새로 수신되고 승인된 발신 메시지; 지원되는 리콜 업데이트 (recall updates) |
오프라인 프로필 명령어는 데몬(daemon)이나 네트워크 연결 없이 지원되는 저장된 기록, 연락처, 그룹 및 미디어를 검사할 수 있으며, 소스 보존 스냅샷(source-preserving snapshots)과 필요한 키를 사용합니다. 여기서의 연락처 쓰기(Contact writes)는 동기화된 메타데이터(synchronized metadata)를 의미하며, 임의의 친구 생성, 삭제 또는 편집을 의미하지 않습니다.
기존 프로필 호환성(Existing-profile compatibility)은 인식된 Linux 레이아웃을 대상으로 합니다. 알 수 없는 파일은 보존되며, 지원되지 않는 데이터베이스 레이아웃은 거부됩니다. 일반적인 공식 검색 인덱스 유지 관리(search-index maintenance), 임의의 프로필 마이그레이션(arbitrary profile migration), 그리고 공식 앱으로의 원활한 전환(seamless switching)은 확립되지 않았습니다. 복사/가져오기/내보내기 워크플로우는 여전히 실험적입니다. 네이티브 프로필 가이드 (native profile guide)를 참조하십시오.
OpenClaw
@agent-wechat/agent-wechat 플러그인을 사용하여 에이전트를 WeChat에 연결하십시오.
openclaw plugins install @agent-wechat/agent-wechat
이후 [OpenClaw 설정]을 따라 계정을 선택하고, 범위가 지정된 토큰(scoped token)을 생성하며, 에이전트가 답변할 대상을 구성하세요. DM과 그룹은 설정 전까지 비활성화됩니다. 답장은 연결된 계정을 사용합니다.
| 기능 | 지원 여부 |
|---|
| DM 및 그룹 | 수신 가능한 메시지를 받고 동일한 WeChat 스레드에서 답장합니다. |
| ... | |
| 기본 기록/미디어 도구는 현재 채팅 내에 머무릅니다. 아카이브 권한(Archive grants)은 다른 채널을 포함하여 계정 전체의 읽기를 허용하므로, 해당 접근이 필요한 에이전트에게만 부여하세요. 미디어 이해 및 생성은 구성된 모델과 도구에 따라 달라집니다. [agent tools], [access policies], 그리고 [hosting modes]를 참조하세요. | |
작동 방식 (How it works)
flowchart LR
Desktop[데스크톱 클라이언트] --> API[HTTP API 및 이벤트]
CLI[wx CLI] --> API
...
Rust 데몬(daemon)은 계정, 동기화 및 미디어를 처리합니다. 클라이언트는 인증된 API와 이벤트 스트림을 공유합니다. 지원되는 메시지/연락처/그룹 상태는 WeChat 프로필에 존재하며, 데몬은 자격 증명(credentials), 보류 작업(pending work), 복구 기록을 별도로 유지합니다. 각 프로필에는 하나의 작성자만 소유권을 가집니다.
데스크톱 앱, CLI 및 OpenClaw가 사용하는 것과 동일한 API는 사용자 자신의 스크립트, 통합 및 클라이언트에서 사용할 수 있습니다. 구성 요소 경계와 저장 모델은 [아키텍처 가이드]를 읽어보세요.
이전 설치본을 업그레이드하시나요? [마이그레이션 가이드]를 따라 프로필과 백업 데이터를 유지하세요.
탐색 및 기여 (Explore and contribute)
WeChat에 연결하지 않고 합성 계정 및 미디어를 사용하여 클라이언트를 사용해 보세요:
pnpm install --frozen-lockfile
pnpm client:dev
전제 조건 및 시나리오 제어는 클라이언트 프리뷰 가이드와
시뮬레이터 가이드를 참조하십시오. 변경 사항을 빌드하고 테스트하려면
AGENTS.md와 빌드 가이드부터 시작하십시오.
데모 에셋 및 갤러리 소스에는 완성된 비디오, 스크린샷, 합성 시각적 장치(synthetic visual fixtures), 그리고 이미지 생성 스크립트가 포함되어 있습니다. 비디오 편집 소스는 모션 타이틀, 타이밍 및 원본 악기(instrumental)를 보존하며, 개인적인 원본 녹음 파일은 Git 외부에 보관됩니다.
라이선스
Agent WeChat의 원본 프로젝트 코드는 MIT License에 따라 라이선스가 부여됩니다. 타사 컴포넌트는 기존의 라이선스와 고지 사항을 유지합니다. 자세한 내용은 번들된 고지, 컴포넌트별 고지, 그리고 Inter 폰트 라이선스를 참조하십시오.
