WeClaw: 위챗을 Claude, Codex 등 AI 에이전트와 연결하는 프로젝트

읽을거리&정보공유
, , , , ,
1

WeClaw: 위챗을 Claude, Codex 등 AI 에이전트와 연결하는 브릿지
WeClaw: 위챗을 Claude, Codex 등 AI 에이전트와 연결하는 브릿지1536×1024 272 KB

WeClaw 소개

WeClaw는 위챗(WeChat)을 Claude, Codex, Gemini, Kimi 같은 AI 에이전트와 연결해 주는 브릿지입니다. 메신저 앱에서 보낸 메시지를 로컬에 설치된 AI 코딩 에이전트로 전달하고, 그 응답을 다시 위챗으로 돌려보내는 역할을 합니다. 평소 데스크톱에서 쓰던 코딩 에이전트를, 컴퓨터 앞에 있지 않더라도 위챗 대화창을 통해 그대로 호출할 수 있게 해 주는 도구입니다.

WeClaw의 접근 방식은 여러 에이전트를 하나의 대화 채널로 묶는 것입니다. 위챗으로 들어온 메시지는 WeClaw를 거쳐 기본 에이전트나 명령어로 지정한 특정 에이전트에게 전달되고, 에이전트의 응답은 위챗에 맞는 형태로 변환되어 되돌아옵니다. WeClaw는 Go로 작성되었으며, 한 줄 설치 명령으로 설치한 뒤 weclaw start 를 실행하면 QR 코드 로그인부터 에이전트 자동 감지까지 이어집니다.

WeClaw는 텐센트의 @tencent-weixin/openclaw-weixin 에서 영감을 받은 프로젝트입니다. 본 게시물에서는 WeClaw의 동작 방식과 에이전트 연결 모드, 설치 및 채팅 명령, 그리고 미디어 처리 같은 추가 기능을 정리합니다.

WeClaw의 동작 방식

WeClaw는 위챗과 AI 에이전트 사이에서 메시지를 중계합니다. 사용자가 위챗으로 보낸 메시지는 클로봇(ClawBot)과 릴레이 서버(Relay Server)를 거쳐 WeClaw로 전달되고, WeClaw는 이를 Codex, Claude Code, OpenClaw 등 연결된 에이전트로 라우팅한 뒤 응답을 위챗으로 되돌려 보냅니다.

WeClaw의 메시지 전달 구조
WeClaw의 메시지 전달 구조2032×1160 111 KB

에이전트를 연결하는 방식은 세 가지 모드로 나뉩니다. ACP 모드는 장시간 실행되는 서브프로세스로 표준 입출력을 통해 JSON-RPC로 통신하며, 프로세스와 세션을 재사용하기 때문에 가장 빠릅니다(Claude, Codex, Kimi, Gemini, Cursor, OpenCode, OpenClaw). CLI 모드는 메시지마다 새 프로세스를 실행하고 --resume 로 세션 이어가기를 지원합니다(예: claude -p, codex exec). HTTP 모드는 OpenAI 호환 chat completions API로 연결합니다. 두 방식을 모두 쓸 수 있으면 자동 감지가 CLI보다 ACP를 우선합니다.

WeClaw 설치와 채팅 명령

한 줄 설치 명령으로 설치한 뒤 weclaw start 를 실행하면 됩니다. 첫 실행 시 QR 코드가 표시되고, 위챗으로 스캔해 로그인하면 설치된 AI 에이전트를 자동으로 감지해 ~/.weclaw/config.json 에 설정을 저장한 뒤 위챗 메시지 수신과 응답을 시작합니다.

# 한 줄 설치
curl -sSL https://raw.githubusercontent.com/fastclaw-ai/weclaw/main/install.sh | sh

# 시작 (첫 실행 시 QR 코드 로그인)
weclaw start

Go나 Docker로 설치할 수도 있습니다.

# Go로 설치
go install github.com/fastclaw-ai/weclaw@latest

# Docker로 실행
docker run -it -v ~/.weclaw:/root/.weclaw ghcr.io/fastclaw-ai/weclaw start

위챗 대화창에서는 메시지 앞에 명령을 붙여 에이전트를 제어합니다. 그냥 메시지를 보내면 기본 에이전트로 전달되고, /codex write a function 처럼 특정 에이전트를 지정하거나 /cc /cx /gm 같은 별칭(alias)으로 호출할 수 있습니다. /claude 로 기본 에이전트를 바꾸면 그 설정이 저장되어 재시작 후에도 유지되고, /cwd /path/to/project 로 작업 디렉토리를 바꾸거나 /new 로 새 대화를 시작할 수 있습니다.

에이전트별 세부 설정은 ~/.weclaw/config.json 에서 지정합니다. 각 에이전트의 연결 모드(type)와 실행 명령, 환경 변수, 모델 등을 정의하며, 별칭도 여기서 추가할 수 있습니다.

{
  "default_agent": "claude",
  "agents": {
    "claude": {
      "type": "acp",
      "command": "/usr/local/bin/claude-agent-acp",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-xxx" },
      "model": "sonnet"
    },
    "openclaw": {
      "type": "http",
      "endpoint": "https://api.example.com/v1/chat/completions",
      "api_key": "sk-xxx",
      "model": "openclaw:main"
    }
  }
}

일부 CLI 에이전트는 위챗 환경에서 동작하지 않는 대화형 권한 승인을 요구하는데, WeClaw는 에이전트 설정의 args 에 --dangerously-skip-permissions(Claude CLI)나 --skip-git-repo-check(Codex CLI) 같은 플래그를 넣어 이를 우회할 수 있게 합니다. 다만 이 플래그들은 안전 검사를 끄는 것이므로, 저장소 문서도 위험을 이해한 경우에만 사용하라고 경고하고 있습니다.

WeClaw의 추가 기능

WeClaw는 이미지, 영상, 파일, 음성 메시지를 위챗과 주고받을 수 있습니다. 위챗에서 음성 메시지를 보내면 위챗의 음성-텍스트 변환을 이용해 자동으로 텍스트로 바꿔 에이전트에 전달하고, 에이전트가 마크다운 이미지 문법으로 이미지를 담아 응답하면 해당 이미지를 내려받아 위챗 CDN에 업로드한 뒤 이미지 메시지로 보냅니다. 에이전트 응답의 마크다운은 위챗 표시에 맞게 코드 펜스를 제거하고 링크는 표시 텍스트만 남기는 식으로 평문으로 변환됩니다.

또한 사용자가 먼저 메시지를 보내지 않아도 위챗 사용자에게 메시지를 보내는 능동 발신(proactive messaging)을 지원합니다. weclaw send CLI 명령이나, weclaw start 가 실행 중일 때 127.0.0.1:18011 에서 동작하는 HTTP API로 텍스트와 미디어를 보낼 수 있습니다.

WeClaw의 라이선스

WeClaw의 저장소에는 MIT 라이선스 파일이 포함되어 있습니다. 다만 저자는 README에서 이 프로젝트가 개인 학습용이며 상업적 용도로는 사용하지 말라고 명시하고 있으므로, 사용 전 이 안내를 함께 확인하는 것이 좋습니다.

:house: WeClaw 홈페이지

:github: WeClaw 프로젝트 GitHub 저장소



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. :smiley:

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck: