mrliuzhiyu/Wechat-Claude-bot

위챗(WeChat)을 통한 원격 컴퓨터 제어 —— 단순한 채팅을 넘어, AI가 실제로 파일을 읽고 쓰고, 명령을 실행하며, 코드를 수정합니다

中文 · English · 日本語 · 한국어 · Русский · Español · Français · Deutsch · Português · العربية

위챗 메시지 전송 → AI가 당신의 컴퓨터 제어 → 결과가 위챗으로 전송

일반적인 챗봇과의 차이점은 무엇일까요? CowAgent/QClaw는 텍스트 대화만 가능합니다. 본 프로젝트는 Claude Code / Open Interpreter를 통해 AI가 실제로 컴퓨터를 조작하도록 합니다. 즉, 파일을 읽고 쓰고, 명령을 실행하며, 코드를 수정하고, 테스트를 실행합니다. PyQt6 데스크톱 클라이언트를 사용하며, 다양한 AI 엔진 전환을 지원하고, 극도로 심플하고 고급스러운 디자인 스타일을 갖추고 있습니다.

위챗 원격 제어— 컴퓨터 터미널을 열 필요 없이 위챗 메시지를 통해 로컬의 Claude Code를 직접 제어합니다.
위챗을 종료해도 사용 가능— 서버 측 롱 폴링 (Long Polling) 방기에 기반하여, 위챗 앱을 닫아도 메시지가 계속 대기하며, 다시 열면 즉시 답변을 받을 수 있습니다. Bot은 24시간 7일 내내 중단 없이 작동합니다.
완전한 컴퓨터 조작 능력— Claude Code는 실제로 컴퓨터를 조작할 수 있습니다: 임의의 파일 읽기/쓰기, 임의의 터미널 명령 실행, 코드 검색, 의존성 설치, Git 조작 등, 단순한 채팅 그 이상을 수행합니다.
실제 프로젝트 직접 조작— Claude Code가 로컬 프로젝트 디렉토리 내에서 실행되므로, 실제 코드 파일을 직접 수정하며 수정 즉시 반영됩니다.
다중 AI 엔진— 세 가지 어댑터 중 선택 가능: Claude Code CLI (완전한 컴퓨터 조작), Open Interpreter (다양한 모델 지원), 순수 API (Anthropic/OpenAI/DeepSeek 대화)

실시간 진행 상황 피드백— Claude Code가 파일을 읽거나, 코드를 쓰거나, 명령을 실행할 때 진행 상황을 위챗으로 실시간 푸시합니다 (예: 📖 파일 읽는 중: src/app.js)

사고 상태 표시— 처리 시작 후 3초 이내에 "🧠 생각 중..."을 푸시하고, 타이핑 (Typing) 상태를 병행하여 사용자가 Bot이 작업 중임을 알 수 있게 합니다.
파일 자동 전송— Claude Code가 읽거나 생성한 이미지/PDF/문서/동영상은 자동으로 위챗에 전송되어 수동 작업이 필요 없습니다.
이미지/파일/동영상 수신— 위챗으로 보내온 이미지, 파일, 동영상을 수신하여 자동으로 다운로드한 뒤 AI에게 전달하여 분석합니다 (PDF 요약, CSV 데이터 분석, 코드 리뷰 등).
지능형 메시지 분할— 긴 답변은 코드 블록 경계에 따라 지능적으로 자동 분할되며, 조각마다 번호가 표시됩니다.
Markdown 변환— Claude의 Markdown 출력을 위챗 친화적인 일반 텍스트 형식으로 자동 변환합니다.
음성 메시지 지원— 위챗 음성을 텍스트로 변환하는 기능을 지원하며, 오류 방지를 위해 음성 출처를 자동으로 표시합니다.
슬래시 명령 (Slash Commands)
/new 대화 초기화, /model 모델 전환, /cwd 프로젝트 디렉토리 전환, /send 파일 전송, /status 상태 확인

PyQt6 네이티브 GUI— 터미널 도구가 아닌, 극도로 심플하고 고급스러운 디자인 스타일 (Linear/Raycast/Apple에서 영감을 받음)을 제공합니다.
실시간 조작 뷰— AI가 무엇을 하고 있는지 확인 가능: 어떤 파일을 읽었는지, 어떤 명령을 실행했는지, 어떤 코드를 작성했는지 보여줍니다.
엔진 전환— GUI 설정에서 AI 엔진과 모델을 전환할 수 있으며, 재시작이 필요 없습니다.
시스템 트레이— 트레이로 최소화하여 백그라운드에서 실행하며, 더블 클릭 시 복구됩니다.

다중 사용자 세션 격리— 각 위챗 사용자마다 독립적인 세션(Session)을 가지며, 대화 컨텍스트(Context)가 연속적으로 유지되어 서로 간섭하지 않습니다.
동시성 제어— 최대 3개의 작업을 동시에 처리하며, 초과 시 "잠시만 기다려 주세요"라고 안내합니다.
세션 영구 유지— 세션 만료 시간이 설정되지 않아 컨텍스트가 지속적으로 유지됩니다 (VS Code에서 Claude Code를 사용하는 경험과 동일).
세션 지속화 (Persistence)— sessionId가 디스크에 저장되어 재시작 후에도 컨텍스트 손실 없이 자동으로 복구됩니다.
자동 재연결— 토큰(Token) 만료 시 자동으로 다시 QR 코드를 스캔하여 로그인하며, 토큰을 지속화하여 반복적인 스캔을 방지합니다.
타임아웃 보호— 5분 동안 응답이 없으면 강제로 종료하고 이미 도출된 일부 결과를 반환합니다.
우아한 종료 (Graceful Exit)— 창을 닫으면 트레이로 최소화되며, 종료 시 모든 자식 프로세스를 자동으로 정리합니다.
로컬 실행— 코드와 데이터는 어떠한 제3자 서버도 거치지 않으며, 자격 증명 파일 권한은 소유자(Owner)만 읽고 쓸 수 있습니다.

위챗 공식 OpenClaw는 다양한 모델 백엔드 연결을 지원하고 ClawBot 프로토콜을 통해 위챗에 연결할 수 있는 기능이 풍부한 AI 에이전트 프레임워크입니다. 이는 커스텀 AI 능력이 필요한 시나리오에 적합한 완전한 플랫폼 레벨의 솔루션입니다.

하지만 만약 당신의 목표가 위챗을 통해 로컬의 Claude Code를 원격 제어하는 것이라면, OpenClaw는 최적의 해답이 아닙니다. 다음은 두 방식의 핵심 차이점입니다:

비교 차원	OpenClaw	본 프로젝트 (WeChat Claude Code Bot)
포지셔닝 (Positioning)	범용 AI 에이전트 (Agent) 프레임워크, 다양한 모델 및 플러그인 지원	한 가지에 집중: 위챗(WeChat)과 로컬 AI 엔진 연결
설치	프레임워크 자체 + API Key + 모델 설정 + 플러그인 시스템 + 의존성 체인	3단계: `git clone` → `pip install` → `python main.py`
의존성 (Dependency)	프레임워크가 방대하고 의존성이 많아 설치 시 오류 발생 가능성 높음	5개의 핵심 의존성 (PyQt6 / requests / cryptography / qrcode / python-dotenv)
유지보수	프레임워크 업데이트가 빈번하여 지속적인 업그레이드 필요, 버전 호환성 문제 발생 가능성 높음	코드가 간결하고 투명하며, 핵심 로직은 약 3,600행 내외

이것이 가장 결정적인 차이점입니다:

구분	OpenClaw	본 프로젝트
과금 방식	매 대화마다 Claude API를 호출하며, 토큰 (Token) 단위로 과금	로컬의 Claude Code CLI를 사용하며, 기존 구독 한도 내에서 사용
비용 특징	긴 대화, 코드 분석, 다회차 상호작용 시 토큰 소모가 커서 비용 통제가 어려움	추가적인 토큰 비용 없음, 이미 Claude Code 구독 중이라면 추가 비용 제로
API Key	반드시 설정 필요	Claude Code 엔진 사용 시 불필요 (다른 엔진 선택 시 가능)

본 프로젝트가 직접 API를 호출하는 대신 Claude Code CLI를 연결하는 방식을 선택한 이유는, Claude Code 자체가 API 호출로는 대체할 수 없는 능력을 제공하기 때문입니다:

완전한 컴퓨터 제어 — 임의의 파일 읽기/쓰기, 임의의 터미널 명령 실행, 전체 코드베이스 검색 등 단순한 텍스트 대화를 넘어섬
프로젝트 수준의 컨텍스트 (Context) — 프로젝트 디렉토리 전체가 Claude Code의 컨텍스트가 되어, 전체 코드베이스 구조를 이해함
10개 이상의 내장 도구 (Built-in Tools) — Read, Write, Edit, Bash, Glob, Grep, WebSearch 등 완성된 도구 체인 제공
진정한 코드 조작 — 실제 파일을 직접 수정하고, Git 작업을 수행하며, 의존성을 설치하는 등 변경 사항이 즉시 적용됨
실시간 진행 상황 피드백 — 모든 작업 단계(파일 읽기, 명령 실행, 코드 편집 등)가 실시간으로 위챗에 전송됨
연속적인 세션 (Session) — 독립적인 세션 관리를 통해 여러 차례의 대화 동안 컨텍스트가 유지됨

이러한 능력들은 API 호출과 자체적인 도구 체인 구현을 통해 구현할 수도 있지만, Claude Code CLI는 이미 잘 다듬어진 성숙한 제품이므로 굳이 바퀴를 다시 발명할 필요가 없습니다.

OpenClaw = 기능이 풍부한 AI 프레임워크로, 커스텀 AI 능력이 필요한 범용 시나리오에 적합하지만, 무겁고 비싸며 설치가 까다로움

본 프로젝트 = 경량 Python 데스크톱 클라이언트, 추가 비용 제로, 한 가지에 집중: 위챗을 통해 AI를 원격 제어할 수 있게 함

범용 AI 위챗 봇을 구축하고 싶으며, 다양한 모델 연결 및 커스텀 플러그인이 필요한 경우 → OpenClaw
위챗을 통해 원격으로 컴퓨터를 제어하고, 코드를 수정하며, 명령을 실행하고 싶은 경우 → 본 프로젝트
이미 Claude Code 구독 중이며, 추가 비용 없이 위챗 원격 제어 기능을 얻고 싶은 경우 → 본 프로젝트

본 프로젝트는 위챗 공식 iLink Bot (ClawBot) 프로토콜을 기반으로 하며, 위챗 QR 코드 스캔을 통해 연결을 수립합니다:

클라이언트를 실행하면 GUI에 QR 코드가 표시되며, 위챗으로 스캔하면 연결됩니다. 연결된 후에는 위챗 앱을 종료하더라도 봇은 계속 실행되며 메시지를 처리합니다. 나중에 위챗을 다시 열면 답변을 확인할 수 있습니다.

┌──────────┐ ┌──────────────────┐ ┌───────────────┐
│ 위챗 사용자 │ ──메시지──▶│ iLink Bot API │ ──폴링 (Polling)──▶│ 로컬 봇 │
│ (모바일) │ ◀─답변── │ (weixin.qq.com) │ ◀─전송── │ (PyQt6 클라이언트) │
...

봇은 위챗 iLink Bot API (Long Polling)를 통해 사용자 메시지를 수신합니다.
수신된 메시지를 현재 선택된 AI 엔진(기본값: Claude Code CLI, stream-json 모드)으로 전달합니다.
AI의 도구 호출(파일 읽기, 코드 쓰기, 명령 실행 등)을 실시간으로 분석하여 진행 상황을 위챗으로 푸시합니다.
AI 작업이 완료되면 최종 결과를 포맷팅하여 위챗으로 다시 보내며, 생성된 파일은 자동으로 전송됩니다.

요구 사항

Python >= 3.11
Claude Code CLI 설치 완료 (npm install -g @anthropic-ai/claude-code) — Claude Code 엔진 사용 시 필요
위챗 계정

# 1. 프로젝트 클론
git clone https://github.com/mrliuzhiyu/Wechat-Claude-bot.git
cd Wechat-Claude-bot
...

실행 후 GUI에서 환경 검사(Claude CLI, 네트워크 연결 등 확인)를 진행합니다.
검사가 통과되면 QR 코드가 표시됩니다.
위챗(WeChat) 실행 → QR 코드 스캔 → 연결 확인
조작 뷰(Operation View)에 진입하면 바로 사용할 수 있습니다.
위챗에서 봇(Bot)에게 직접 메시지를 보내면 됩니다.

최초 로그인 후 토큰(Token)은 자동으로 저장되어, 다음 실행 시에는 (토큰이 만료되지 않는 한) 다시 QR 코드를 스캔할 필요가 없습니다.

.env 파일 또는 환경 변수를 통해 설정 가능합니다:

변수	설명	기본값
`CLAUDE_CWD`	Claude Code의 기본 작업 디렉토리 (Working Directory)	현재 작업 디렉토리

각 사용자는 /cwd 명령어를 통해 독립적으로 작업 디렉토리를 전환할 수 있으며, 이는 다른 사용자에게 영향을 주지 않습니다. 기본 모델은 Sonnet입니다.

클라이언트 설정 페이지에서는 다음을 수행할 수 있습니다:

AI 엔진 전환 (Claude Code / Open Interpreter / Direct API)
모델 선택 (Sonnet / Opus / Haiku)
API Key 설정 (Open Interpreter 및 Direct API 엔진 사용 시 필요)
작업 디렉토리 수정
사용자 세션 삭제

위챗에서 자연어로 요구 사항을 직접 설명하면, Claude Code가 자동으로 실행합니다:

나: 프로젝트 구조 좀 봐줘
Bot: 🤖 확인했습니다, 처리 중...
Bot: 🔍 파일 검색 중: **/*
...

Claude Code가 작업을 수행할 때 실시간 진행 상황 피드백을 받을 수 있습니다:

📖 파일 읽는 중: src/app.js
✏️ 파일 편집 중: src/utils.js
⚡ 명령 실행 중: npm test
...

Claude Code의 응답이 4,000자를 초과할 경우, 메시지는 지능적으로 분할됩니다:

코드 블록(Code Block) 경계에서 우선적으로 분할
그다음 빈 줄(Empty Line)에서 분할
각 조각에는 (계속 2/3)와 같이 번호가 표시됩니다.

동료가 운영 환경에 긴급 버그가 있다고 피드백을 주었지만, 당신은 지하철에 있습니다.

나: src/api/auth.js의 login 함수 좀 봐줘
Bot: [코드 내용 표시]
나: 42행의 토큰 검증 로직에 문제가 있어. 만료 시간은 >=가 아니라 >를 사용해야 해
...

주말에 외출 중인데, 갑자기 영감이 떠올라 기능을 빠르게 추가하고 싶습니다.

나: src/components 아래에 다크/라이트 모드 전환을 지원하는 ThemeToggle 컴포넌트를 만들어줘
Bot: 📝 파일 생성 중: components/ThemeToggle.jsx
Bot: ✏️ 파일 편집 중: App.jsx
...

새 프로젝트를 인계받아 코드 구조를 빠르게 파악하고 싶을 때입니다.

나: 이 프로젝트의 전체 아키텍처는 어떻게 돼?
Bot: [프로젝트 구조, 주요 모듈, 기술 스택 분석...]
나: 데이터베이스 연결 로직은 어디에 있어?
...

외부에서 서비스 상태를 확인해야 할 때입니다.

나: docker 컨테이너 실행 상태 좀 보여줘
Bot: ⚡ 명령 실행 중: docker ps
Bot: [컨테이너 목록 표시...]
...

명령어	설명
`/help`	도움말 정보 표시
`/new`	대화 초기화 및 새 세션 시작
`/model`	모델 전환 (sonnet / opus / haiku), 기본값 Sonnet
`/cwd <경로>`	작업 디렉토리/프로젝트 전환 (사용자별 독립적)
`/send <경로>`	로컬 파일을 위챗으로 전송 (이미지, 파일, 비디오 지원, 최대 50MB)
`/send <경로>	설명`
`/status`	봇 상태 확인 (버전, 모델, 디렉토리, 실행 시간)

슬래시(/) 명령어 외의 모든 메시지는 AI 엔진으로 전송됩니다. Claude Code가 읽거나 생성한 미디어 파일은 자동으로 위챗으로 전송됩니다.

Wechat-Claude-bot/
├── main.py # PyQt6 애플리케이션 엔트리 포인트
├── core/ # 핵심 로직
...

Claude Code CLI가 설치되어 있는지 확인하세요:

npm install -g @anthropic-ai/claude-code

그리고 claude --version이 정상적으로 출력되는지 확인하십시오. Claude Code 엔진을 사용하지 않는 경우, 설정에서 Open Interpreter 또는 Direct API로 전환할 수 있습니다.

GUI 창이 정상적으로 시작되는지 확인하세요. 시작 로그에도 관련 정보가 출력됩니다. 네트워크가 ilinkai.weixin.qq.com에 접속 가능한지 확인하십시오.

봇은 토큰 만료를 자동으로 감지하여 QR 코드를 다시 표시하므로, 수동 작업이 필요 없습니다.

가능합니다. 각 위챗 사용자는 독립적인 세션을 가지며, 최대 3개의 요청을 동시에 처리할 수 있습니다. 초과 시에는 자동으로 대기열에 추가됩니다.

기본적으로 단일 요청의 타임아웃은 5분입니다. 작업이 너무 복잡하다면, 먼저 Claude가 프로젝트 구조를 파악하게 한 뒤 구체적인 작업을 수행하도록 단계를 나누어 요청할 수 있습니다.

완벽하게 지원합니다. 송수신 양방향 모두 가능합니다:

수신: 사용자가 WeChat에서 이미지/파일/비디오 전송 → 로컬 PC로 자동 다운로드 → AI 지능형 분석 (PDF 요약, CSV 데이터 분석, 코드 리뷰 등)
자동 발송: AI가 읽거나 생성한 이미지/PDF/문서/비디오는 WeChat으로 자동 전송되며, 수동 작업이 필요하지 않습니다.
수동 발송: /send <파일 경로> 사용

임의의 파일 전송 가능 (최대 50MB 제한), /send 경로 | 설명 지원

설명 포함 가능
음성: WeChat 음성 메시지의 텍스트 변환(STT)을 지원하며, 오류 허용 범위를 높이기 위해 출처를 자동으로 표기합니다.

세션은 만료되지 않습니다. 각 사용자의 대화 컨텍스트는 Claude Code의 세션 (session) 메커니즘을 통해 지속적으로 유지되며, 이는 VS Code에서 Claude Code를 사용하는 것과 동일한 효과를 제공합니다. 재시작 후에도 세션은 유실되지 않습니다 (sessionId가 디스크에 영구 저장됨). /new를 전송하여

수동으로 초기화할 수 있습니다.

가능합니다. /cwd D:\projects\my-app을 전송하세요.

작업 디렉토리 (working directory)를 전환합니다. 각 사용자의 작업 디렉토리는 독립적이며, 전환 후에는 새로운 프로젝트 컨텍스트를 가져오기 위해 대화가 자동으로 초기화됩니다.

엔진	능력	적합한 시나리오
Claude Code CLI	완전한 컴퓨터 제어 (파일 읽기/쓰기, 명령 실행, 코드 검색)	원격 개발, 코드 수정, 운영 관리 (Ops)
Open Interpreter	다중 모델 지원 (GPT-4/Claude/Gemini/Ollama), 코드 실행 가능	다른 모델 또는 로컬 모델을 사용하고 싶은 경우
Direct API	순수 대화 (Anthropic/OpenAI/DeepSeek), 컴퓨터 제어 불가	단순 채팅 및 질의응답이 필요한 경우

Bot은 사용자의 로컬 PC에서 실행되므로, 코드가 제3자 서버를 거치지 않습니다.
Claude Code는 완전한 권한 모드로 실행되어 파일을 읽고 쓸 수 있으며 명령을 실행할 수 있습니다.
로그인 자격 증명은 로컬에 저장됩니다.
.state/

디렉토리이며, 파일 권한은 소유자(owner)만 읽고 쓸 수 있도록 설정되어 있습니다. .env

파일은 .gitignore에 포함되어 있어 Git에 커밋되지 않습니다.

주의: Claude Code는 완전한 권한을 가지고 있으므로, 신뢰할 수 있는 사람만이 Bot에게 메시지를 보낼 수 있도록 주의하십시오.

본 프로젝트는 GPL-3.0 라이선스를 채택합니다.

자유로운 사용, 수정 및 배포
파생 저작물은 반드시 동일한 라이선스로 오픈 소스화해야 함
자세한 내용은 LICENSE 파일을 참조하십시오.

mrliuzhiyu/Wechat-Claude-bot

요약

핵심 포인트

댓글