WeiClaw: 위챗과 AI Agent 간의 전 모달리티(Full-modality) 양방향 통신 오픈소스 프로젝트

빠른 시작 · 전 모달리티 (Full-modality) · 멀티미디어 프로토콜 · 다중 Agent · 능동적 전송 · 커스텀 Agent

중국어 | English

⭐ 이 프로젝트가 도움이 되었다면 Star를 눌러주세요!

전 세계 최초로 위챗(WeChat)과 모든 AI Agent 간의 전 모달리티(Full-modality) 양방향 통신을 지원하는 오픈소스 프로젝트입니다 —— 텍스트, 이미지, 음성, 비디오, 파일을 모두 송수신할 수 있습니다.

• 🔌 의존성 없는 접속 — npx 사용
  한 줄의 명령어로 clone이나 별도의 설정 없이 바로 사용 가능합니다. - 🧠
  Agent 무관 — 모든 OpenAI 호환 API (Codex / Gemini / Claude / OpenCode / 자체 구축)를 지원합니다. - 📡
  전 모달리티 (Full-modality) — 텍스트, 이미지, 음성, 비디오, 파일을 양방향으로 완벽하게 지원합니다. - 🤖
  다중 Agent (Multi-Agent) — 여러 Agent를 동시에 연결하고 @를 통해 라우팅을 전환할 수 있습니다. - ⌨️
  타이핑 인디케이터 — Agent가 생각 중일 때 "상대방이 입력 중"임을 표시합니다. - 📤
  능동적 전송 API — Agent가 여러 개의 메시지를 푸시할 수 있어, 실제 사람이 타이핑하는 듯한 리듬을 시뮬레이션합니다.

모달리티 (Modality)	위챗 → Agent	Agent → 위챗
📝 텍스트	✅	✅
...
Agent	접속 방식	설치
---	---	---
⌬ OpenCode	--opencode	npm i -g opencode-ai
🤖 OpenAI Codex	--codex	npm i -g @openai/codex
💎 Google Gemini	--gemini	npm i -g @google/gemini-cli
🧬 Claude Code	--claude	npm i -g @anthropic-ai/claude-code
🐾 OpenClaw	--openclaw	npm i -g openclaw
🔗 모든 OpenAI 호환 API	URL 직접 전달	—
📡 ACP 프로토콜 Agent	--agent name=acp://...	—

각 CLI Agent를 처음 사용할 때는 인증을 완료해야 합니다:

Claude: claude를 실행하여 Anthropic 계정에 로그인하세요.
Gemini: gemini를 한 번 실행하면 브라우저에 Google OAuth 권한 요청 팝업이 뜹니다. 완료되면 토큰이 로컬에 캐시되어 이후 --gemini 모드로 정상 사용이 가능합니다.
Codex: codex를 한 번 실행하여 OpenAI OAuth 인증을 완료하세요.
OpenCode: opencode를 한 번 실행하여 AI provider 인증을 완료하세요 (opencode providers login).

# 원하는 Agent를 선택하세요:
npx weiclaw --codex # OpenAI Codex
npx weiclaw --gemini # Google Gemini
...

처음 사용 시: 터미널에 QR 코드가 나타나면 → 위챗으로 스캔하여 → 완료합니다. 이후에는 자동으로 로그인이 재사용됩니다.

# 1. Node.js >= 22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22
...

위챗 사용자 ←→ 텐센트 (Tencent) ilinkai API ←→ weiclaw ←→ 당신의 Agent (HTTP)

텐센트 ilinkai 인터페이스를 직접 호출하여 위챗 메시지를 송수신하므로, 중간 계층이나 리버스 엔지니어링(Reverse Engineering), 웹 버전(Web version)이 필요 없습니다. Agent는 단지 OpenAI 호환 HTTP 인터페이스만 노출하면 됩니다.

어떤 언어로든 POST /v1/chat/completions를 노출하면 됩니다:

@app.post("/v1/chat/completions")
def chat(request):
    message = request.json["messages"][-1]["content"]
    ...

그 다음: npx weiclaw http://your-agent:8000/v1를 실행하세요.
Agent의 응답에 특정 형식이 포함되어 있으면 멀티미디어를 자동으로 전송합니다.

유형	Agent 응답 형식	설명
이미지		URL, 로컬 경로, data URI 지원
음성	[audio:경로 또는 URL]	MP3/WAV/OGG, ffmpeg + pilk 필요
비디오	[video:경로 또는 URL]	ffmpeg 필요
파일	[file:경로 또는 URL]	모든 파일 유형

이미지 수신 (WeChat → Agent)은 OpenAI Vision API를 따릅니다:

{
"messages": [{
"role": "user",
...

예시: image-test.mjs · voice-test.mjs · video-test-local.mjs · file-test.mjs

Agent 템플릿: claude-code · opencode · openai

동시에 여러 Agent를 연결할 때는 @ 접두사 라우팅(Prefix Routing)을 사용합니다. OpenAI 형식과 ACP 프로토콜을 지원합니다:

npx weiclaw \
--agent codex=http://localhost:3001/v1 \
--agent gemini=http://localhost:3002/v1 \
...

WeChat 메시지	효과
你好	기본 Agent에게 전송
@codex 写个排序	Codex로 라우팅
@gemini 审查代码	Gemini로 라우팅
@list	모든 Agent 확인
@切换 gemini	기본 Agent 전환

Bridge가 시작될 때 localhost:9099에 HTTP API를 노출하며, Agent는 여러 개의 메시지를 능동적으로 푸시할 수 있습니다 (실제 사람이 타이핑하는 듯한 리듬을 시뮬레이션):

curl -X POST http://localhost:9099/api/send \
-H "Content-Type: application/json" \
-d '{"to": "user_id", "content": "嗯……"}'

to — WeChat 사용자 ID (bridge가 agent를 호출할 때 user 필드를 통해 전달됨)
content — Agent 응답과 동일한 형식 지원 (순수 텍스트, ![image](...), [audio:path] 등)
--port PORT를 사용하여 포트 사용자 정의 가능

용도: Agent가 하나의 메시지에 대해 여러 단계로 나누어 응답할 수 있도록 전송 간격을 제어할 수 있습니다:

import requests, time
def send(to, text):
    requests.post("http://localhost:9099/api/send", json={"to": to, "content": text})
...

로그인 자격 증명은 ~/.weiclaw/credentials.json에 저장되며, 삭제하면 다시 로그인할 수 있습니다.

이 프로젝트가 도움이 되었다면 ⭐ Star를 눌러주세요. 저희에게 가장 큰 힘이 됩니다!