GenericAgent 배포 및 연동: 위챗/QQ/비즈니스용(플라이서)까지 전 플랫폼 봇 구축

프로젝트 소개

GenericAgent 는 매우 간결하고 스스로 진화하는 자율형 Agent 프레임워크입니다. 핵심은 약 3K 줄의 코드뿐이며, 9개의 원자(Atomic) 도구 + 약 100줄 규모의 Agent Loop로 어떤 LLM이든 로컬 컴퓨터에 대한 시스템 수준 제어 권한을 부여합니다.

설계 철학이 꽤 흥미롭습니다: 사전에 기술을 정해두지 않고, 진화를 통해 능력을 얻는다는 점입니다. 새로운 작업을 한 번 해결할 때마다 GenericAgent는 실행 경로를 Skill로 자동 고정합니다. 오래 사용할수록 축적되는 스킬이 더 많아져, 3K 줄 시드 코드에서 자라난 당신만의 전용 스킬 트리가 만들어집니다.

OpenClaw(약 530K 줄 코드)에 비하면 GenericAgent는 극도로 미니멀한 노선을 탑니다. 배포가 쉽고(pip install + API Key), 여러 서비스 오케스트레이션이 필요하지 않지만, 그래도 브라우저 제어, 키보드/마우스 조작, ADB로 이동형 기기 제어 같은 핵심 기능은 모두 유지합니다.

---

난이도/소요 시간/얻는 것

• 난이도: 초급 수준으로, 깊은 프로그래밍 경험이 필요하지 않습니다.
• 소요 시간: 약 30분
• 얻는 것: GenericAgent 배포 설정 + 위챗/QQ/비즈니스용(플라이서) 세 가지 IM 플랫폼 연동을 익혀, 언제 어디서나 휴대폰으로 컴퓨터 AI를 조종할 수 있게 됩니다.

---

대상 독자

• 1~5년 경력의 백엔드 또는 풀스택 개발자
• 개인용 AI 비서, 자동화 워크플로를 구축하고 싶은 사용자
• Agent 기술에 관심이 있고, "AI가 실제로 당신 대신 일을 하게 만들기"를 빠르게 경험해보고 싶은 개발자
• 다중 플랫폼 IM 연동이 필요한 경우(예: 위챗/QQ를 통해 원격으로 컴퓨터를 제어해야 하는 경우)

---

핵심 의존성과 환경

---

전체 프로젝트 구조

GenericAgent/
├── agentmain.py              # 주 진입점, 커맨드라인 모드 지원
├── launch.pyw                # 데스크톱 GUI 실행 스크립트
├── agent_loop.py             # 핵심 Agent Loop(약 100줄)
├── llmcore.py                # LLM 세션 관리
├── ga.py                     # GenericAgentHandler, 메모리와 툴 디스패치
├── frontends/                # IM 플랫폼 어댑터
│   ├── wechatapp.py         # 위챗 Bot
│   ├── qqapp.py             # QQ Bot
│   ├── fsapp.py             # 비즈니스용(플라이서) Bot
│   ├── tgapp.py             # Telegram Bot
│   ├── wecomapp.py          # 위챗(기업용) Bot
│   ├── dingtalkapp.py       # 딩톡 Bot
│   ├── tuiapp.py            # 터미널 UI
│   └── ...
├── assets/
│   ├── mykey_template.py    # API Key 설정 템플릿
│   ├── tools_schema.json    # 9개의 원자 도구 정의
│   ├── sys_prompt*.txt      # 시스템 프롬프트
│   └── tmwd_cdp_bridge/    # 브라우저 인젝션 플러그인
├── memory/                   # 메모리 저장 디렉터리
└── temp/                     # 임시 파일과 로그

---

단계별 진행

Step 1: 프로젝트 및 의존성 설치

먼저 리포지토리를 클론하고 기본 의존성을 설치합니다.

# 리포지토리 클론
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# 기본 의존성 설치
pip install requests

# GUI 의존성 설치(데스크톱 모드)
pip install streamlit pywebview

# 또는 터미널 UI 의존성 설치
pip install requests textual

Step 2: API Key 설정

설정 템플릿을 복사합니다.

cp assets/mykey_template.py mykey.py

mykey.py를 편집해 자신의 LLM 설정을 입력하세요. 아래는 Defapi 사용 예시입니다(Claude 기준).

# Defapi 중계를 통해 Claude 사용(공식 반값)
native_claude_config = {
    'name': 'claude-defapi',                    # 표시 이름
    'apikey': 'sk-ant-your-defapi-key',         # Defapi에서 제공하는 key
    'apibase': 'https://api.defapi.org',        # Defapi 엔드포인트
    'model': 'claude-sonnet-4-6',               # 또는 claude-opus-4-7
    'fake_cc_system_prompt': True,              # 중계 서비스에서 활성화 필요
    'thinking_type': 'adaptive',
    'max_tokens': 16384,
}

GenericAgent는 변수 이름을 보고 프로토콜 형식을 자동 판단합니다.

• native + claude 포함 → NativeClaudeSession(네이티브 tool 필드)
• native + oai 포함 → NativeOAISession(OpenAI 네이티브 tool 필드)
• claude만 포함( native 미포함 ) → ClaudeSession(텍스트 프로토콜 도구)

Step 3: GenericAgent 실행

먼저 커맨드라인 모드가 정상인지 테스트합니다.

python agentmain.py

대화 프롬프트 >가 보이고, 한 줄을 입력해 테스트할 수 있어야 합니다.

> 데스크톱에 hello.txt를 만들고, 내용은 Hello World로 해줘

모든 것이 정상이라면 Agent가 작업을 실행하고 결과를 피드백합니다.

데스크톱 GUI 모드로 전환합니다.

python launch.pyw

---

Step 4: 위챗 Bot 연동

위챗 Bot은 개인 위챗의 QR 스캔 로그인 지원으로, 연동이 가장 간단합니다.

추가 의존성 설치:

pip install pycryptodome qrcode requests

설정(선택): 설정하지 않아도 사용 가능하지만, 화이트리스트 설정을 권장합니다.

mykey.py에 추가:

# 위챗 화이트리스트. 위챗 ID를 입력하세요. 비워두면 모든 사용자를 허용합니다
wechat_allowed_users = []

위챗 Bot 실행:

python frontends/wechatapp.py

처음 실행 시 QR 코드 창이 뜨며, 위챗으로 스캔해 확인합니다. 로그인이 성공하면, 당신의 위챗이 GenericAgent와 대화하는 인터페이스가 됩니다.

Step 5: QQ Bot 연동

QQ Bot은 QQ 로봇 공식 API를 사용하며 공개 웹훅(webhook) 이 필요 없습니다. WebSocket의 장기 연결을 통해 메시지를 받습니다.

의존성 설치:

pip install qq-botpy

설정:

1. QQ 오픈 플랫폼 에서 로봇을 생성하고 AppID와 AppSecret을 획득합니다.
2. mykey.py에 추가:

qq_app_id = "당신의APP_ID"
qq_app_secret = "당신의APP_SECRET"
qq_allowed_users = ["사용자 openid"]  # 또는 ['*'] 로 전체 허용

QQ Bot 실행:

python frontends/qqapp.py

로봇에게 처음 메시지를 보내면, 사용자의 openid가 temp/qqapp.log에 기록됩니다.

Step 6: 비즈니스용(플라이서) Bot 연동

비즈니스용(플라이서) Bot은 텍스트, 리치 텍스트, 이미지, 파일, 오디오, 인터랙티브 카드 등 다양한 메시지 형식을 지원합니다.

의존성 설치:

pip install lark-oapi

설정:

1. 비즈니스용(플라이서) 오픈 플랫폼에서 기업용 자체 구축 앱을 생성하고 AppID와 AppSecret을 받습니다.
2. mykey.py에 추가:

fs_app_id = "cli_xxxxxxxxxxxxxxxx"
fs_app_secret = "xxxxxxxxxxxxxxxx"
fs_allowed_users = ["ou_xxxxxxxxxxxxxxxx"]  # 또는 ['*'] 로 전체 허용

비즈니스용(플라이서) Bot 실행:

python frontends/fsapp.py

Step 7: 검증 및 튜닝

모든 Bot은 다음 공통 명령을 지원합니다.

• /new - 새 대화를 시작하고 현재 문맥을 초기화
• /continue - 복구 가능한 세션 스냅샷 목록 출력
• /continue N - N번째 과거 세션 복구

여러 플랫폼을 동시에 연동해 검증:

여러 Bot을 동시에 실행하려면 터미널 창을 여러 개 열기만 하면 됩니다.

# 터미널1: 위챗
python frontends/wechatapp.py

# 터미널2: QQ
python frontends/qqapp.py

# 터미널3: 비즈니스용(플라이서)
python frontends/fsapp.py

---

자주 발생하는 문제 해결

1. API Key 설정 후 인증 오류

원인: 변수명이 잘못 적혔거나 fake_cc_system_prompt 설정이 틀렸음

해결:

• 변수명이 올바른 핵심 키워드를 포함하는지 확인(native_claude, oai_config 등)
• 중계 서비스는 반드시 fake_cc_system_prompt: True 여야 함
• apibase가 올바른지 확인(예: Defapi는 https://api.defapi.org)

2. 위챗 스캔 후 로그인 실패 메시지

원인: 위챗의 새 기기 로그인에 대한 리스크 제어(풍토/보안) 제한

해결:

• 휴대폰 쪽에서 로그인 확인을 시도(때로는 휴대폰에서 추가 검증이 필요)
• 위챗 계정에 이상 행위가 없는지 확인
• Bot 사용 빈도를 낮춰 리스크 제어를 덜 자극

3. QQ Bot이 메시지를 받지 못함

원인: 로봇이 활성화되지 않았거나 권한 설정이 잘못됨

해결:

• QQ 오픈 플랫폼에서 로봇이 활성화되어 있는지 확인
• 이벤트 구독을 올바르게 추가했는지 확인( 사적 대화 메시지(私聊消息) 이벤트 구독이 필요)
• temp/qqapp.log를 확인해 사용자의 openid가 제대로 기록되는지 확인

4. 비즈니스용(플라이서) Bot 응답이 느림

원인: LLM 추론 자체가 느리거나 네트워크 지연이 큼

해결:

• 더 빠른 모델 사용(GPT-4o-mini, MiniMax-M2 등)
• LLM API로의 네트워크 지연 확인
• max_tokens를 적절히 줄여 첫 토큰 응답 속도를 높이기

5. Bot이 대화 문맥을 기억하지 못함

원인: /new 명령을 실행했거나 세션 타임아웃

해결:

• /continue 명령으로 과거 세션을 복구
• memory/ 디렉터리에 쓰기 권한이 있는지 확인
• temp/model_responses/ 디렉터리에 세션 기록이 있는지 확인

6. 실행 중 ModuleNotFoundError 발생

원인: 의존성 패키지가 없음

해결:

# Agent가 스스로 설치하도록 하기
> 필요한 모든 Python 의존성을 설치해 주세요

# 또는 일반 의존성을 수동 설치
pip install requests pycryptodome qrcode streamlit pywebview

---

확장 읽기 / 고급 방향

브라우저 자동화 기능

Web 도구를 잠금 해제하면, GenericAgent는 로그인 상태가 유지된 실제 브라우저에서 동작하며 조작할 수 있습니다.

> web setup sop를 실행해서 web 도구를 해제해줘

그 후에는 이렇게 사용할 수 있습니다.

> 타오바오를 열고 iPhone 16을 검색한 뒤 가격순으로 정렬해줘
> B

(아래 문장은 원문 구조를 유지하기 위해 계속 이어집니다)

B

> B

브라우저 플러그인은 assets/tmwd_cdp_bridge/ 에 있으며 Chrome/Edge 등 주요 브라우저를 지원합니다.

자기 진화 메커니즘 자세히 보기

GenericAgent의 핵심 차이는 작업을 한 번 완료할 때마다 실행 경로를 Skill로 자동 고정한다는 점입니다. 다음에 비슷한 작업을 만나면, 다시 탐색할 필요 없이 바로 호출합니다.

즉:

• 오래 쓸수록 Agent는 당신의 워크플로를 더 잘 알게 됩니다.
• 스킬 트리는 완전히 당신의 것이며, 다른 사람의 "사전 스킬"과는 동일하지 않습니다.
• 3K 줄 시드 코드로도 무한한 가능성이 자라납니다.

Skill 라이브러리 생태계

커뮤니티에는 이미 백만 단위 Skill 라이브러리가 축적되어 있습니다(위챗 공식계정 글). 당신은:

• Agent에게 검색시키기: XXX를 만드는 skill을 찾아줘
• 바로 가져오기: XXX에 접속해서, 이 skill대로 해줘

고급 모드

GenericAgent의 모든 고급 기능은 문서화가 되어 있습니다(자기 문서화) — Agent에게 그대로 물어보면 됩니다.

프로그래밍 능력과 Claude Code 비교

많은 개발자들이 궁금해하는 한 가지가 있습니다: GenericAgent가 Claude Code 또는 Codex를 대체할 수 있나요?

결론은: 프로그래밍은 가능하지만 완전히 대체할 수는 없습니다.

GenericAgent의 프로그래밍 능력

GenericAgent는 code_run 도구로 임의의 코드를 실행합니다. 여기에 file_read/file_write/file_patch 등 파일 조작 기능을 결합하면, 프로그래밍 능력은 완전합니다. 코딩에 강한 모델(예: Claude, GPT-4o)을 붙이면 GenericAgent는 다음을 할 수 있습니다.

• 파일을 읽고/쓰고
• 커맨드라인을 실행하고
• 코드를 디버깅하고
• 코드 로직을 설명하고

# Claude를 백엔드로 설정
native_claude_config = {
    'apikey': 'your-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,
}

그런 다음 자연어로 바로 프로그래밍할 수 있습니다.

> 퀵 정렬 함수 하나를 작성하고, 테스트를 실행해줘
> Python으로 HTTP 서버를 구현해줘
> 이 React 컴포넌트가 어떻게 동작하는지 설명해줘

Claude Code / Codex와의 차이

핵심 차이는 이겁니다: Claude Code는 자신의 프로토콜과 툴체인으로 동작합니다(MCP 비슷한 형태). GenericAgent는 그것들을 직접 호출할 수는 없습니다. 다만 아래와 같은 간접 방법이 있습니다.

방법 1: Codeg과 병렬 사용

Codeg 프로젝트는 동시에 GenericAgent + Claude Code + Codex를 실행하고, 같은 UI에서 협업할 수 있게 해줍니다.

# GenericAgent와 Codeg을 같은 상위 디렉터리에 둠
/workspace/
  ├── GenericAgent/
  └── codeg/

# Codeg이 GenericAgent를 자동으로 감지한 뒤 병렬 사용

방법 2: API 중계를 통한 연동

GenericAgent의 NativeClaudeSession은 Claude Code 호환 프로토콜을 사용합니다. 만약 중계 서비스(예: Defapi)가 Claude Code의 패스스루(전달)를 지원한다면, GenericAgent로 Claude의 프로그래밍 능력을 사용할 수 있습니다.

# GenericAgent가 Claude의 능력으로 프로그래밍
native_claude_config = {
    'name': 'claude-defapi',
    'apikey': 'your-defapi-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,  # Claude Code 프로토콜 패스스루
}

결론

---

Reference

• GitHub: lsdefine/GenericAgent
• Technical Report: arXiv:2604.17091
• 입문 튜토리얼: Datawhale Hello GenericAgent
• 비즈니스용(플라이서) 설정 가이드: assets/SETUP_FEISHU.md