QwenPaw 딥다이브
— 내 메신저 안에 사는 '셀프호스팅 AI 비서'

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

QwenPaw = "내가 쓰는 모든 메신저 안에 들어와 있는, 도구를 쓸 줄 아는 개인 AI 비서." ChatGPT는 정해진 웹사이트에서만 만나지만, QwenPaw는 텔레그램·디스코드·위챗 등 내가 평소 쓰는 채팅앱 안에서 직접 말을 걸 수 있고, 부탁하면 답변만 하는 게 아니라 파일을 찾아 읽고·코드를 돌리고·웹을 뒤지고·매일 아침 뉴스를 요약해 보내주는 일까지 "행동"한다. 그리고 그 비서는 내 컴퓨터(또는 내 서버)에서 돌아간다.

중요한 사실 하나 — 이름이 비슷해 헷갈리지만 QwenPaw는 흔히 알려진 다른 챗봇 호스팅 프로젝트(AstrBot 등)와 코드 계보가 다르다. 원래 이름은 CoPaw였고 2026년 4월 QwenPaw로 리브랜딩됐으며, 알리바바 통이 연구 계열인 agentscope-ai 조직 소유다. 핵심 엔진도 같은 조직의 agentscope / agentscope-runtime 프레임워크다.

2왜 주목받는가

TrendShift 일간 2위까지 올라온 이유 — 트렌딩의 배경.

2025~2026년은 "에이전트가 실제 업무를 대신하는" 흐름이 폭발한 시기다. 코딩 에이전트(Claude Code·Codex)에 이어, 이번엔 "내 개인 비서 에이전트를 통째로 셀프호스팅"하는 쪽이 주목받는다. QwenPaw가 상위로 올라온 이유를 다섯으로 정리한다.

① "내 메신저 = 비서 창구" — 17개 채널 동시 연결

텔레그램·디스코드·위챗·QQ·딩톡·라크(Feishu)·Matrix·Mattermost·기업위챗·iMessage·MQTT, 심지어 SIP(전화)까지. 한 비서를 띄워 두면 어느 메신저에서 말을 걸든 같은 에이전트가 같은 기억으로 응답한다. "챗봇을 어디에 붙일까"라는 통합 문제를 한 번에 해결한 것이 가장 큰 매력이다.

② 알리바바 agentscope 생태계의 플래그십

QwenPaw는 단독 프로젝트가 아니라, 알리바바의 오픈소스 에이전트 프레임워크 agentscope 위에 세워진 대표 응용 사례다. Qwen(통이천문) 모델을 무료 티어로 바로 쓸 수 있고, DashScope·ModelScope 연동이 1급 시민이다. 프레임워크 제작사가 직접 만든 레퍼런스 앱이라 "agentscope를 제대로 쓰는 법"의 교본 역할을 한다.

③ Skills + MCP + ACP — 에이전트 표준 3종 세트를 한 몸에

요즘 에이전트 생태계의 세 표준을 모두 엮었다. Skills(Anthropic의 Agent Skill 포맷 그대로, SKILL.md 폴더), MCP(외부 도구를 꽂는 표준), ACP(Zed·OpenCode 같은 에디터가 이 에이전트에 붙는 프로토콜)를 동시에 지원한다. 셋을 한 시스템에서 실제로 통합한 보기 드문 레퍼런스다.

④ 프라이버시 우선 + 다층 보안 가드레일

데이터를 로컬 파일과 OS 키링에 두는 데다, 에이전트가 위험한 짓을 못 하게 막는 안전장치가 코드로 들어 있다. rm -rf 같은 파괴적 셸 명령을 정규식 규칙으로 차단하고(Tool Guard), 설치하는 스킬의 코드를 정적 스캔하며(Skill Scanner), 채널별 사용자 화이트리스트로 접근을 통제한다.

⑤ 데스크탑 앱 + 멀티 에이전트 + 능동 메모리

같은 React 웹 콘솔을 Tauri로 묶어 데스크탑 앱으로도 배포하고, 데스크탑 펫 플러그인까지 있다. 역할이 다른 여러 에이전트를 띄워 서로 협업·위임시키고, 대화를 거듭하며 메모리(Markdown)가 스스로 진화하는 기능도 갖췄다.

3기술 스택 전체 지도

pyproject.toml · 소스 트리(526개 .py + React 콘솔)에서 직접 확인한 실제 구성.

QwenPaw는 ⓐ 백엔드(에이전트·서버 두뇌) ⓑ 프론트엔드(웹 콘솔/데스크탑) ⓒ 저장·보안 세 층으로 나뉜다. 한 가지 큰 특징은 전통적 데이터베이스가 없다는 점 — 상태를 전부 로컬 파일과 OS 키링에 둔다.

ⓐ 백엔드 — 에이전트 & 서버 (두뇌)

ⓑ LLM 공급자 & 채널 SDK

ⓒ 프론트엔드 (웹 콘솔 = 데스크탑 앱)

ⓓ 저장 & 보안 (DB가 아니라 파일!)

4아키텍처 심화 분석

텔레그램에 보낸 한 줄이 답이 되어 돌아오기까지 — 메시지의 여정.

QwenPaw의 진짜 묘미는 "표준 프레임워크는 위임하고, 자기만의 레이어를 위에 얹는" 이중 구조다. 에이전트의 추론 루프(ReAct)는 agentscope에 맡기고, 그 위에 채널 입출력·메시지 큐·접근제어·보안 가드를 직접 구현했다. 메시지 한 통의 흐름을 그림으로 보면 이렇다.

핵심 설계 패턴 ① — 프레임워크 위임 + Mixin 합성

에이전트 클래스 정의 한 줄이 전체 설계 철학을 압축한다:

class QwenPawAgent(CodingModeMixin, ToolGuardMixin, ReActAgent):
    # 추론 루프 자체는 agentscope의 ReActAgent에 위임하고,
    # '코딩 모드'와 '도구 안전 가드' 같은 횡단 관심사는 Mixin으로 끼워 넣는다.

자체 ReAct를 새로 짜지 않고 ReActAgent를 상속하되, 기능을 Mixin(혼합 클래스)으로 분리해 합성했다. "도구 가드"나 "코딩 모드"를 켜고 끄기 쉽고, 본체 코드가 깔끔해진다 — 다중 상속의 모범적 사용.

핵심 설계 패턴 ② — 데코레이터 체인으로 모델 감싸기

LLM 모델 객체를 그대로 쓰지 않고, 같은 인터페이스를 유지한 채 기능을 겹겹이 입힌다.

model = RetryChatModel(            # ③ 재시도 · 레이트리밋 · 백오프
            TokenRecordingModelWrapper(   # ② 토큰 사용량 기록
                provider.get_chat_model_instance(model_name)  # ① 원본 모델
            )
        )

양파처럼 감싼 데코레이터 패턴이다. 토큰 측정·재시도 로직이 에이전트 본체에 섞이지 않고 투명하게 추가된다. 멀티벤더 LLM 앱을 만들 때 그대로 베껴 쓸 만한 구조다.

핵심 설계 패턴 ③ — 레지스트리 + base_url 프리셋

수십 개 LLM 공급자를 일일이 클래스로 만들지 않는다. OpenAI 호환·Anthropic 호환·Gemini 3개 베이스로 환원하고, DeepSeek·Kimi·Zhipu·DashScope(Qwen) 등은 base_url과 메타데이터만 바꿔 등록한다. 채널도 마찬가지로 딕셔너리 레지스트리 + 지연 import(lazy) 방식이다.

핵심 설계 패턴 ④ — 큐 + 디바운스 + 컨텍스트 전파

채팅의 현실 문제를 구조로 푼다. 사용자가 메시지를 3줄 연달아 보내면? UnifiedQueueManager가 세션별 큐에서 디바운스(잠깐 모았다 합치기)·배치 병합으로 처리한다. 그리고 비동기 호출 사슬 전체에 누가·어느 채널·어느 세션인지를 ContextVar로 흘려보내, 미들웨어→러너→모델→토큰기록까지 일관된 컨텍스트를 유지한다.

5디렉토리 구조 해부

레포를 클론하면 보이는 폴더들 — 어디에 뭐가 있나.

한눈에 정리하면: src/qwenpaw/agents/가 두뇌(에이전트·도구·스킬), src/qwenpaw/app/가 신경망(채널·서버·라우팅), src/qwenpaw/providers/가 입(LLM 연결), console/가 얼굴(웹·데스크탑 UI)이다. 구조를 빨리 잡으려면 agents/react_agent.py(에이전트가 어떻게 도구를 쓰나)와 app/channels/base.py(채널이 어떻게 추상화됐나) 두 파일이 지름길이다.

6학습 포인트 (기술별)

이 레포에서 무엇을, 어떻게 배울 수 있나.

① 표준 프레임워크 위에 프로덕션 시스템 얹기 (가장 값진 부분)

"agentscope가 주는 ReAct/Toolkit/Formatter를 어떻게 상속·확장하고, 그 위에 채널 I/O·큐·접근제어를 직접 구현하는가"의 분리선이 명확하다. 프레임워크를 쓰되 끌려다니지 않는 법을 배우는 실전 교본이다.

실습 아이디어: react_agent.py에서 어떤 부분이 agentscope 상속이고 어떤 부분이 QwenPaw 자체 코드인지 형광펜으로 나눠 본다.

② 멀티벤더 LLM 추상화

베이스클래스 환원 + base_url 프리셋 + 데코레이터(재시도·레이트리밋·토큰측정) 체인. 수십 개 LLM을 한 인터페이스로 다루는 멀티벤더 LLM 앱의 모범 설계를 providers/에서 통째로 볼 수 있다.

실습 아이디어: providers/에서 OpenAI 호환 프리셋이 어떻게 정의되는지 찾아, base_url만 바꾼 "가짜 공급자"를 하나 추가해 본다.

③ 비동기 메시지 파이프라인

asyncio Queue, 디바운스, 배치 병합, ContextVar 컨텍스트 전파, graceful shutdown. "여러 채팅방에서 동시에 메시지가 쏟아질 때 어떻게 안 꼬이게 처리하나"의 구체적 답을 app/channels/에서 배운다.

실습 아이디어: UnifiedQueueManager의 디바운스 시간을 바꿔, 메시지를 빠르게 연달아 보낼 때 동작이 어떻게 달라지는지 관찰한다.

④ Skills + MCP + ACP 통합

요즘 에이전트 생태계 표준(Skills·MCP·ACP)을 한 시스템에 엮은 드문 레퍼런스. SKILL.md 포맷, MCP 클라이언트 핫리로드, ACP 서버/클라이언트 양방향을 실제 코드로 확인할 수 있다.

실습 아이디어: 빌트인 스킬 하나(agents/skills/cron-en/SKILL.md)를 열어, frontmatter와 본문이 에이전트에게 어떻게 "도구 사용법"을 알려주는지 읽어 본다.

⑤ 에이전트 보안 가드레일

"에이전트가 rm -rf를 치면 어떻게 막나?"의 실제 구현. 정규식 규칙 엔진(Tool Guard) + 스킬 정적 스캐너 + 승인 워크플로의 다층 방어를 security/에서 본다. 자율 에이전트를 만들 사람이라면 반드시 봐야 할 부분.

실습 아이디어: security/tool_guard/의 위험 명령 YAML 규칙을 읽고, 차단되는 명령과 통과되는 명령의 경계를 정리한다.

⑥ 웹앱을 Tauri로 데스크탑 패키징

같은 React 코드를 웹 콘솔과 데스크탑 앱으로 동시 배포하는 방법(Rust Tauri 2 + NSIS). "내 웹 도구를 어떻게 설치형 앱으로 만드나"의 가벼운 입문이 console/src-tauri/에 있다.

7하드웨어 / 시스템 요구사항

내 컴퓨터에서 돌리려면 뭐가 필요한가.

QwenPaw 자체는 "LLM API를 호출하는 가벼운 에이전트 서버"다. 클라우드 LLM(Qwen·DeepSeek·OpenAI 등)을 쓰면 무거운 GPU가 필요 없다 — 진짜 계산은 LLM 쪽이 한다. 내 머신은 채널 중계·도구 실행·웹 콘솔만 돌리면 된다. 단, 로컬 모델·브라우저 자동화·코딩 모드를 켜면 그만큼 자원이 더 든다.

8직접 해볼 수 있는 실습 과제

난이도별 5개 — 손으로 익히는 게 최고다.

9관련 기술 심화 학습 로드맵

이 레포를 발판으로 4주 코스를 짠다면.

10핵심 키워드 사전

레포 문서·코드에 자주 나오는 용어 빠른 정리.

11참고 링크

더 깊이 파고들 곳.