MagiClaw 입문: 플립북(Feishu) 안에 AI 연구 에이전트 팀을 배치해 협업이 자연스럽게 일어나게 하세요

15 분 안에 설정 완료｜플립북(Feishu) 네이티브 경험｜연구 Agent 편성｜EvoMaster 기반을 원클릭으로 확장

프로젝트 소개

MagiClaw 는 플립북(Feishu) 안에서 동작하는 AI 에이전트 플랫폼입니다. 핵심 아이디어는 다음과 같습니다. 사용자가 별도로 따로 열어야 하는 독립형 도구를 또 만드는 것이 아니라, 매일 사용하던 플립북(Feishu) 안에 AI 에이전트를 바로 내장하는 것입니다. 즉, 그룹 채팅이나 1:1 대화에서 요구사항을 설명하면 에이전트 팀이 바로 움직이기 시작합니다.

MagiClaw 뒤에는 EvoMaster 프레임워크가 있습니다. 이 가벼운 Agent 기반 인프라는 도구 호출, Skills(스킬), 메모리 관리, 세션 연결(세션 라우팅)을 담당합니다. 따라서 “에이전트에게 무엇을 시킬지”에 집중할 수 있고, 엔지니어링 레벨을 반복해서 다시 만들 필요가 없습니다. 전체 프로젝트는 오픈소스이며 Apache 2.0 라이선스를 따르고, 코드 규모가 작아 2차 개발이 쉽습니다.

TIP

프로젝트 주소: https://github.com/sjtu-sai-agents/MagiClaw, Apache 2.0 라이선스, Python ≥ 3.12.

목표 독자상

이 글은 다음 개발자를 대상으로 합니다.

Python 기본기가 있고 플립북(Feishu) 또는 Lark 협업 도구에 익숙하며, AI 역량을 팀의 일상 커뮤니케이션에 직접 도입하고 싶은 개발자
AI for Science 시나리오에 관심이 있어 확장 가능한 연구용 에이전트 프레임워크를 찾는 개발자
이미 EvoMaster 또는 유사한 Agent 프레임워크를 사용 중이며, 플립북(Feishu)을 프런트엔드 상호작용 계층으로 확장하고 싶은 개발자

만약 “독립적인 연구용 에이전트 올인원(풀 패키지)”을 찾고 있다면 MagiClaw은 그 답이 아닙니다. 대신 EvoMaster 생태계를 플립북(Feishu)과 연결해, 연구 워크플로가 팀 커뮤니케이션 도구 안에서 자연스럽게 흘러가게 해주는 것입니다.

핵심 의존성과 환경

의존성	최소 요구 사항	설명
Python	≥ 3.12	실행 환경
플립북(Feishu) / Lark	팀 버전	Bot 배포 및 일상 대화에 사용
LLM API	OpenAI / Anthropic 호환	`configs/magiclaw/config.yaml` 에서 설정 가능
uv	선택	고성능 패키지 관리자로 pip을 대체할 수 있음

WARNING

Python 3.12 는 필수 요구사항입니다. 예전 버전에서는 의존 패키지의 일부 C 확장 의존성을 설치할 수 없으므로, pyenv 또는 uv 로 다중 Python 버전을 관리해 다른 프로젝트와 충돌을 피하는 것을 권장합니다.

전체 프로젝트 디렉터리 구조

MagiClaw/
├── evomaster/                    # 핵심 프레임워크 라이브러리
│   ├── agent/                   # Agent 기본 클래스와 런타임
│   ├── core/                    # 핵심 도구 호출, 태스크 스케줄링
│   ├── interface/
│   │   └── feishu/             # 플립북(Feishu) 인터페이스 구현(롱 커넥션, Webhook)
│   ├── memory/                  # 영속 메모리 저장소
│   ├── skills/                  # 재사용 가능한 스킬 패키지
│   └── scheduler/               # 멀티 태스크 스케줄러
├── playground/
│   ├── magiclaw/               # 기본 플립북(Feishu) 대화 에이전트
│   ├── agent_builder/           # 메타 에이전트: 새로운 Agent 설계/생성
│   ├── coding_agent/            # 코드 작성 전용 에이전트
│   ├── report_writer_agent/     # 보고서 작성 전용 에이전트
│   └── web_search_agent/        # 웹 검색 전용 에이전트
├── configs/
│   ├── feishu/                  # 플립북(Feishu) Bot 연결 인증 정보
│   │   └── config.yaml
│   ├── magiclaw/               # LLM, 도구, MCP, 메모리 설정
│   │   └── config.yaml
│   └── agent_builder/           # 기획 + 빌드 두 에이전트 구성
├── run.py                       # CLI 빠른 시작 엔트리
├── requirements.txt
└── pyproject.toml

단계별 설치 방법

1단계: 코드 클론

git clone https://github.com/sjtu-sai-agents/MagiClaw.git
cd MagiClaw

2단계: 의존성 설치

pip install -r requirements.txt

또는 uv(더 빠름) 사용:

uv pip install -r requirements.txt

3단계: 플립북(Feishu) 애플리케이션 생성

플립북(Feishu) 오픈 플랫폼 을 열고, 팀 계정으로 로그인
엔터프라이즈 자가 구축형 애플리케이션 만들기 를 클릭하고 이름과 설명을 입력
애플리케이션에 들어간 뒤 왼쪽 메뉴에서 애플리케이션 권한 추가 를 선택하고 봇 을 체크

4단계: 애플리케이션 인증 정보 설정

환경변수 템플릿을 복사합니다.

cp .env.template .env

.env 에 플립북(Feishu) 오픈 플랫폼이 제공한 인증 정보를 입력합니다.

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

5단계: 권한 범위 가져오기

플립북(Feishu) 오픈 플랫폼에서 권한 관리 → 일괄 가져오기/내보내기 권한 으로 들어가 아래 JSON을 붙여넣습니다.

{
  "scopes": {
    "tenant": [
      "im:resource",
      "docx:document",
      "docx:document:readonly",
      "drive:drive",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "wiki:wiki:readonly"
    ],
    "user": [
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive.version",
      "drive:drive.version:readonly"
    ]
  }
}

TIP

권한은 필요에 따라 축소할 수 있습니다. 팀에서 플립북(Feishu) 문서의 읽기/쓰기가 필요 없다면 docx 와 drive 관련 권한을 제거해 안전성을 높이세요.

6단계: 이벤트 구독 설정

이벤트 및 콜백 → 이벤트 구성 에서 롱 커넥션으로 이벤트 수신 을 선택하고 아래 이벤트를 추가합니다.

설명	이벤트명
봇이 채팅방에 들어옴	`im.chat.member.bot.added_v1`
봇이 채팅방에서 나감	`im.chat.member.bot.deleted_v1`
메시지 읽음 처리됨	`im.message.message_read_v1`
메시지 회수(철회)	`im.message.recalled_v1`
메시지 수신	`im.message.receive_v1`

콜백 구성 에서도 동일하게 롱 커넥션을 선택하고 아래를 구독합니다.

설명	콜백
카드 인터랙션 콜백	`card.action.trigger`

7단계: LLM 설정

configs/magiclaw/config.yaml 을 편집해 LLM 자격 증명을 입력합니다.

llm:
  provider: openai              # 또는 anthropic / custom
  model: gpt-4o
  api_key: sk-...               # .env 에서 불러오거나 설정 파일에 직접 작성
  base_url: https://api.openai.com/v1  # 선택 사항: 커스텀 엔드포인트

8단계: 애플리케이션 게시 및 시작

플립북(Feishu) 오픈 플랫폼의 버전 관리 및 게시 에서 버전을 생성하고 게시해 Bot이 동작하도록 만듭니다.

그런 다음 봇을 시작합니다.

python -m evomaster.interface.feishu --config configs/feishu/config.yaml

시작이 성공하면 플립북(Feishu)에서 Bot에게 메시지를 보내보세요. Bot이 답장을 할 것입니다. 초기 상태에서는 다목적 대화 에이전트로 동작하며, 다중 턴 컨텍스트와 메모리 기능을 갖추고 있습니다.

듀얼 코어 Agent 아키텍처

MagiClaw의 진짜 역량은 두 개의 내장 Playground의 조합에서 나옵니다: magiclaw 는 일상 대화를 처리하고, agent_builder 는 새 전용 에이전트를 만들도록 도와줍니다.

magiclaw: 플립북(Feishu) 세션 편성기

magiclaw는 기본으로 활성화되는 플립북(Feishu) 대화 에이전트이며, 핵심 역량은 편성(오케스트레이션)과 위임 입니다.

복잡한 요청을 보내면 magiclaw는 혼자서 모든 것을 처리하려 하지 않습니다. 먼저 이 작업에 필요한 전용 역량이 무엇인지 식별한 다음, 도구 호출을 통해 다른 등록된 Playground에게 일을 위임합니다.

플립북(Feishu)에서 이렇게 요청합니다: 「RAG 아키텍처가 금융 분야에서의 최신 진전에 대해 조사해주고, 보고서를 작성해줘」

→ magiclaw가 요청을 받음
→ 필요 항목 판단: 문헌 조사(web_search_agent) + 보고서 작성(report_writer_agent)
→ 두 에이전트를 각각 호출
→ 결과를 종합해 플립북(Feishu) 메시지로 반환

이 위임 메커니즘 덕분에 magiclaw는 간결함을 유지합니다. “무엇이든 다” 할 필요가 없고, 언제 누구를 호출해야 하는지만 알면 됩니다. 모든 전용 Agent의 역량은 Skills와 도구 인터페이스를 통해 확장됩니다.

agent_builder: 메타 에이전트

agent_builder는 MagiClaw에서 가장 흥미로운 부분입니다. 이것도 자체가 하나의 Agent이지만, 역할은 새로운 Agent를 설계하고 생성하는 것 입니다.

원하는 작업 유형을 알려주면 agent_builder는 다음을 수행합니다.

요구사항을 분석하고 Agent에 필요한 핵심 역량을 추출
Agent의 스킬 파일을 생성(YAML frontmatter + Markdown 설명)
playground/ 디렉터리에 기록하고 MagiClaw에 등록
새 Agent는 즉시 사용 가능해지고, magiclaw가 이를 위임 대상으로 삼을 수 있습니다.

플립북(Feishu)에서 이렇게 요청합니다: 「코드 리뷰를 전담하는 Agent가 필요해」

→ agent_builder가 요구사항을 분석
→ `code_reviewer_agent.py` + 해당 구성 파일을 생성
→ 시스템에 등록
→ 응답: 「code_reviewer를 생성했어요. 이제 magiclaw가 코드 리뷰 작업을 여기에 위임할 수 있습니다」

이 부트스트래핑(자기 확장) 능력 덕분에 팀은 자신의 연구 방향에 맞춰 Agent 라이브러리를 계속 확장할 수 있고, 모든 시나리오를 처음부터 한 번에 정의할 필요가 없습니다.

도구 구성과 Skills / 메모리 메커니즘

도구 레이어 구성

configs/magiclaw/config.yaml 에서 여러 종류의 도구를 구성할 수 있습니다.

tools:
  mcp:
    # MCP 프로토콜 도구(파일 시스템, Git, 데이터베이스 등)
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

  web_search:
    enabled: true
    provider: duckduckgo         # 선택: bing / google / serpapi

  feishu:
    read_document: true           # 플립북(Feishu) 문서 읽기
    send_file: true               # 파일 전송

도구 설정은 Agent가 “무엇을 할 수 있는지”를 결정하고, Skills는 Agent가 “얼마나 잘 해내는지”를 결정합니다.

Skills 스킬 시스템

Skills는 구조화된 프롬프트를 캡슐화한 것으로, Agent가 특정 작업에서 더 좋은 성능을 내도록 돕습니다. EvoMaster의 Skills 디렉터리는 evomaster/skills/ 이며, 각 Skill은 Markdown 파일입니다.

---
name: research-paper-summary
trigger: literature survey, paper review, paper analysis
agent: research
---

# Research Paper Summary Skill

사용자가 논문을 요약하거나 분석해달라고 요청하면 다음 단계를 수행합니다.

1. 논문 제목, 저자, 발표 venue 추출
2. 핵심 기여(contribution) 추출
3. 방법론의 핵심 포인트 추출
4. 한계점(limitations) 추출
5. 구조화된 요약을 출력(300단어 이내)

사용자가 ArXiv 링크를 제공했다면, 먼저 페이지 내용을 가져온 뒤 분석합니다.

Skills는 필요 시 로드됩니다. Agent는 특정 유형의 작업을 처리할 때 해당 Skills를 자동으로 매칭하며, 사용자가 수동으로 트리거할 필요가 없습니다.

영속 메모리

MagiClaw의 메모리는 evomaster/memory/ 모듈이 관리하며, 다양한 저장 백엔드를 지원합니다.

memory:
  backend: sqlite               # 선택: sqlite / redis / file
  session_ttl: 86400            # 세션 메모리 보존 시간(초)
  long_term:
    enabled: true
    store: file                 # 디스크에 영속화
    path: ./memory_store/

대화가 끝날 때마다 Agent는 핵심 컨텍스트를 자동으로 메모리에 기록합니다. 다음 세션이 시작되면 Agent가 이전 메모리를 읽어 세션 간 일관성을 유지합니다.

전체 워크플로 데모

시나리오: 팀을 위한 「논문 빠른 읽기」 Agent 구축

목표: 플립북(Feishu)에서 Bot에게 ArXiv 링크 하나를 던지면, 자동으로 구조화된 논문 요약을 반환합니다.

Step 1: agent_builder로 Agent 생성

플립북(Feishu)에서 MagiClaw에게 메시지를 보냅니다.

논문 빠른 읽기 Agent를 만들어줘. 이름은 paper_reader 로 해줘

agent_builder가 playground/paper_reader/ 디렉터리를 생성하며 다음을 포함합니다.

playground/paper_reader/
├── __init__.py
├── agent.py                   # Agent 메인 로직
└── config.yaml                 # Agent 레벨 설정

Step 2: magiclaw에 등록

새 Agent 생성 후 configs/magiclaw/config.yaml 을 편집해 playgrounds 아래에 등록합니다.

playgrounds:
  - name: paper_reader
    path: playground/paper_reader
    enabled: true

봇을 재시작하면 magiclaw가 paper_reader를 인식하고 위임할 수 있습니다.

Step 3: 테스트

플립북(Feishu)에서 다음을 입력합니다.

@Bot paper_reader https://arxiv.org/abs/2401.01234

paper_reader가 자동으로 실행합니다.

1. ArXiv 페이지를 가져옴
2. 제목, 저자, 초록을 추출
3. 구조화된 요약을 생성(기여 + 방법 + 한계)
4. 플립북(Feishu) 메시지로 반환

자주 묻는 질문 및 문제 해결

Q1: 봇을 시작했는데 플립북(Feishu)에서 응답이 없음

원인: 이벤트 구독 또는 롱 커넥션 구성이 올바르지 않습니다.

확인 절차:

# 1. 봇이 게시되어 있는지 확인(플립북(Feishu) 오픈 플랫폼 → 버전 관리 및 게시)
# 게시하지 않은 봇은 운영 환경에서 메시지 수신/송신이 불가능합니다

# 2. 롱 커넥션이 올바르게 구성되어 있는지 확인
# 플립북(Feishu) 오픈 플랫폼 → 이벤트 및 콜백 → 이벤트 구성 → "롱 커넥션" 선택

# 3. 시작 로그에 에러가 있는지 확인
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

Q2: Bot은 메시지를 받지만 "지원되지 않는 작업" 이라고 응답함

원인: 권한 범위가 부족하거나, 해당 범위에 앱이 게시되지 않았습니다.

확인 절차:

플립북(Feishu) 오픈 플랫폼 → 권한 관리 에서 아래 최소 권한 세트가 모두 열려 있는지 확인합니다.

"im:message",
"im:message:send_as_bot",
"im:chat:readonly"

Bot이 그룹 채팅에 참여해야 한다면 im:message.group_at_msg:readonly 도 필요합니다.

Q3: agent_builder로 Agent를 만든 뒤 magiclaw가 인식하지 못함

원인: 새 Agent가 configs/magiclaw/config.yaml 에 등록되지 않았습니다.

해결 방법:

configs/magiclaw/config.yaml 의 playgrounds 목록에 새 Agent가 추가되어 있고 enabled: true 로 설정되어 있는지 확인하세요. 설정을 수정한 뒤에는 봇을 재시작해야 합니다.

Q4: 메모리가 세션 간 유지되지 않아 매번 Agent가 마치 기억을 잃은 것처럼 행동함

원인: 메모리 저장 백엔드가 올바르게 구성되지 않았거나, 저장 경로에 쓰기 권한이 없습니다.

확인 절차:

# 1. config.yaml의 memory 설정을 확인
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. memory_store 디렉터리가 존재하고 쓰기 가능해야 함
mkdir -p memory_store
chmod 755 memory_store

# 3. 봇을 재시작한 뒤 메시지를 보내 메모리 쓰기를 트리거

Q5: Web Search 도구가 빈 결과를 반환하거나 타임아웃 발생

원인: 네트워크에서 검색 서비스에 접근할 수 없거나, Search API 자격 증명이 구성되지 않았습니다.

해결 방법:

DuckDuckGo를 사용한다면(무료, API Key 불필요) Python 환경에서 외부 네트워크 접근이 가능한지 확인합니다.

# 네트워크 테스트
python -c "import requests; print(requests.get('https://api.duckduckgo.com/?q=test&format=json').status_code)"

200이 반환되는데도 Bot에서 계속 타임아웃이 난다면, configs/magiclaw/config.yaml 의 tools.web_search.provider 구성이 올바른지 확인하세요.

Q6: MCP 도구를 시작할 수 없고 "command not found" 가 표시됨

원인: MCP Server의 npx 또는 Node.js 경로가 시스템 PATH에 추가되지 않았습니다.

해결 방법:

# npx가 사용 가능한지 확인
npx --version

# npx를 찾지 못한다면 경로를 수동으로 지정
# configs/magiclaw/config.yaml을 편집합니다.
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

확장 읽기 및 고급 방향

1. SciMaster 생태계 연동

MagiClaw는 EvoMaster 생태계의 플립북(Feishu) 입구이며, 전체 SciMaster 시리즈(ML-Master, X-Master, Browse-Master 등)는 상위(upstream) EvoMaster 저장소에 있습니다. 연구 방향에 다중 모달 재료 과학 분석이나 다중 실험 협업이 필요하다면, EvoMaster에서 이러한 전용 Agent를 동기화하고 MagiClaw의 편성(오케스트레이션) 레이어에 연동할 수 있습니다.

2. 커스텀 MCP 도구

MagiClaw의 MCP 도구 인터페이스는 어떤 MCP Server든 연동할 수 있도록 지원합니다. Python으로 MCP Server를 작성해 내부 API, 연구 데이터베이스 조회 도구 또는 HPC 클러스터 제출 스크립트를 감싸고, 이를 MagiClaw에 등록하면 Agent가 플립북(Feishu) 안에서 곧바로 호출할 수 있습니다.

3. 다중 Bot 협업 아키텍처

팀에 서로 다른 기능의 Bot이 여러 개 있다면(예: 하나는 캘린더 관리, 하나는 코드 관리, 하나는 문헌 관리), 플립북(Feishu) 그룹 채팅을 통해 협업하게 만들 수 있습니다. 하나의 그룹에 여러 Bot을 통합하고, 각각이 자신에게 맡은 역할을 담당하도록 하며, @ 로 전환해 사용할 수 있습니다.

4. 팀 전용 모델 배포

EvoMaster는 custom Provider를 지원해, 사내에 배포된 LLM(Llama, Mistral, Qwen 등)을 연동할 수 있습니다. 연구 데이터가 외부로 반출될 수 없다면 로컬 또는 사설 클라우드에 모델을 배포하고, MagiClaw의 플립북(Feishu) 인터페이스로 조작하면 데이터는 전혀 외부 네트워크로 나가지 않습니다.

5. Agent 행동(행위) 튜닝

각 Playground의 Agent 동작은 주로 config.yaml 의 prompt 와 skills 에 의해 제어됩니다. 특정 상황에서 Agent의 성능이 좋지 않다면, 해당 Skill 파일을 수정해 Agent의 사고 단계와 출력 형식을 조정할 수 있습니다. 코드 수정은 필요 없습니다.