MedgeClaw: 반값 Claude로 생명정보학(바이오인포매틱스) 분석하기

저장소: https://github.com/xjtulyc/MedgeClaw

중급 난이도, 약 30분 소요. 반값 Claude API를 사용하여 바이오 의약 AI 어시스턴트를 구축하고 매월 500+ 달러를 절약하는 방법을 알려드립니다.

대상 독자

• AI를 활용하여 데이터 분석을 보조하고자 하는 생명과학 분야 연구자
• 과학 연구 워크플로우 자동화가 필요한 생물정보학 엔지니어
• AI + 과학 연구에 관심이 있는 대학(원)생

핵심 종속성 및 환경

• Node.js 22+
• Docker + docker-compose
• Git
• Defapi API Key (반값 플랜, 아래에서 자세히 설명)

[!TIP]
8GB 이상의 VRAM을 가진 GPU가 필수적인 것은 아니지만, 보유하고 있다면 더 많은 로컬 모델 배포가 가능합니다.

전체 프로젝트 구조

MedgeClaw/
├── .env.example              # 환경 설정 템플릿
├── .env                     # 실제 설정 (example에서 복사)
├── setup.sh                 # 원클릭 설치 스크립트
├── sync.py                  # OpenClaw 설정 동기화
├── docker-compose.yml       # Docker 환경 정의
├── .medgeclaw-sync.yml      # 동기화 규칙 설정
├── docker/
│   ├── Dockerfile           # R + Python + RStudio + Jupyter
│   └── entrypoint.sh        # 컨테이너 시작 스크립트
├── skills/                  # MedgeClaw 내장 스킬
│   ├── biomed-dispatch/    # 작업 라우터
│   ├── dashboard/           # 실시간 연구 대시보드
│   ├── cjk-viz/             # CJK 폰트 감지
│   ├── svg-ui-templates/    # SVG 템플릿
│   └── feishu-rich-card/    # Feishu 리치 카드
├── scientific-skills/       # K-Dense 140개 과학 스킬 (git submodule)
├── data/                    # 데이터 디렉토리 (입력 파일 위치)
├── outputs/                 # 출력 디렉토리 (분석 결과 위치)
└── writing_outputs/         # 과학 저술 출력

---

단계별 튜토리얼

1단계: 저장소 클론

# 프로젝트 클론 (submodule 포함)
git clone --recurse-submodules https://github.com/xjtulyc/MedgeClaw.git
cd MedgeClaw

[!WARNING]
반드시 --recurse-submodules를 추가해야 합니다. 그렇지 않으면 scientific-skills 디렉토리가 비어 있게 됩니다.

2단계: 반값 Claude API 설정

가장 중요한 단계입니다. Defapi를 사용하여 비용을 대폭 절감할 것입니다!

Defapi는 OpenAI 포맷과 호환되는 모델 어그리게이터 플랫폼으로, Claude 시리즈 모델을 반값 서비스로 제공합니다. 공식 가격이 $3.75/M tokens인 Claude Sonnet 4.5를 여기서는 $1.875에 이용할 수 있습니다.

[!TIP]
매일 1000번의 유전자 분석을 수행하고, 매회 10만 tokens의 컨텍스트 + 5000 tokens의 출력을 소모한다고 가정할 때:

• 공식 API: 약 $3.75 × 1000 = $3750/월
• Defapi: 약 $1.875 × 1000 = $1875/월
• 매달 $1875 절약!

먼저 설정 템플릿을 복사합니다:

cp .env.example .env

그 다음 .env를 편집하여 Defapi API Key를 입력합니다:

# Defapi 반값 설정
ANTHROPIC_API_KEY=dk-xxxxxxxxxxxxxxxx
ANTHROPIC_BASE_URL=https://api.defapi.org
MODEL=anthropic/claude-sonnet-4.5

# 중요: Claude Code 사전 점검에 이 설정이 필요함
ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-sonnet-4.5

# 웹 인터페이스 비밀번호
RSTUDIO_PASSWORD=biomed
JUPYTER_TOKEN=biomed

[!WARNING]
Defapi API Key가 없으신가요? https://defapi.org 에 접속하여 가입하세요. 신규 사용자에게는 무료 크레딧이 제공됩니다. Defapi는 v1/chat/completions 인터페이스를 지원하며 Claude Code와 완벽히 호환됩니다.

3단계: 설치 스크립트 실행

bash setup.sh

이 스크립트는 다음 작업을 자동으로 처리합니다:

• Node.js 22+ 및 Docker 종속성 확인
• openclaw 및 claude-code 전역 설치
• ~/.claude/settings.json 생성 (Claude Code 설정)
• Docker 이미지 빌드 (R, Python, RStudio, JupyterLab 포함)
• OpenClaw workspace 설정

[!WARNING]
최초 Docker 이미지 빌드에는 네트워크 및 사양에 따라 10~20분 정도 소요됩니다.

4단계: Docker 환경 시작

docker compose up -d

시작 후 다음 주소로 접속할 수 있습니다:

• RStudio Server: http://localhost:8787 (ID rstudio, PW biomed)
• JupyterLab: http://localhost:8888 (Token biomed)

5단계: OpenClaw로 설정 동기화

python3 sync.py
openclaw gateway restart

sync.py는 다음 작업을 수행합니다:

• MedgeClaw의 스킬들을 OpenClaw workspace로 복사
• OpenClaw 설정 파일 업데이트
• 프로젝트 문서를 AI 에이전트 컨텍스트에 주입

6단계: 설치 확인

# 빠른 API 연결 확인 (30초 이내에 "hello"가 반환되어야 함)
claude --dangerously-skip-permissions -p 'run: echo hello'

성공적으로 hello가 출력된다면 설정이 올바르게 완료된 것입니다.

[!WARNING]
30초 이상 멈춰 있다면 ANTHROPIC_SMALL_FAST_MODEL 설정이 올바르지 않은 것입니다. 즉, 사용 중인 프록시가 해당 모델을 지원하지 않는 경우입니다. Defapi는 전체 Claude 모델 리스트를 지원하므로 문제없이 작동합니다.

---

자주 묻는 질문(FAQ) 및 문제 해결

Q1: Docker 빌드 실패

증상: docker compose build가 멈추거나 에러 발생

해결:

# Docker 캐시를 정리하고 다시 시도
docker system prune -a
docker compose build --no-cache

Q2: Claude Code 사전 점검(Pre-flight check) 멈춤

증상: 어떤 명령을 실행해도 멈춰 있으며 "Pre-flight check is taking longer than expected" 메시지 표시

해결: 서드파티 프록시가 기본 Haiku 모델을 지원하지 않을 수 있습니다. ANTHROPIC_SMALL_FAST_MODEL을 반드시 설정해야 합니다:

# .env에 추가 또는 프록시가 지원하는 모델로 수정
ANTHROPIC_SMALL_FAST_MODEL=anthropic/claude-sonnet-4.5

Defapi는 전체 Claude 모델 리스트와 호환되므로 이 설정을 완벽하게 지원합니다.

Q3: scientific-skills 디렉토리가 비어 있음

증상: skills/ 디렉토리는 존재하지만 내용이 없음

해결:

git submodule update --init --recursive

Q4: 포트 충돌

증상: 8787 또는 8888 포트가 이미 사용 중이라는 메시지

해결:

# 사용 중인 프로세스 확인
lsof -i :8787
lsof -i :8888

# 또는 docker-compose.yml의 포트 매핑 수정

Q5: OpenClaw가 MedgeClaw 스킬을 찾지 못함

증상: 에이전트가 biomed-dispatch 등의 스킬을 인식하지 못함

해결:

# 다시 동기화
python3 sync.py
openclaw gateway restart

Q6: R/Python 패키지 설치 실패

증상: 분석 스크립트 실행 시 "package not found" 에러 발생

해결:

# Python 패키지
docker exec medgeclaw pip install <package-name>

# R 패키지
docker exec medgeclaw Rscript -e 'install.packages("<package-name>", repos="https://cran.r-project.org")'

---

추가 읽을거리 / 심화 방향

1. K-Dense 과학 스킬

MedgeClaw는 다음을 포함한 140개의 과학 스킬을 통합하고 있습니다:

• 오믹스 분석: DESeq2, edgeR, Scanpy, Seurat
• 신약 개발: ChEMBL, DeepChem, DiffDock
• 문헌 검색: PubMed, bioRxiv, Semantic Scholar
• 경로 분석: gseapy, clusterProfiler

자세한 사용법은 scientific-skills/scientific-skills/ 디렉토리 내의 SKILL.md를 참조하세요.

2. 커스텀 스킬 개발

MedgeClaw에 새로운 스킬을 추가하고 싶으신가요? AgentSkills 규격에 따라 디렉토리를 생성하세요:

skills/
└── your-custom-skill/
    └── SKILL.md   # 스킬 정의 파일

SKILL.md 템플릿:

# Your Custom Skill

## When to use
이 스킬을 어떤 상황에서 호출해야 하는지 설명

## How it works
스킬의 구체적인 구현 로직

## Examples
몇 가지 사용 예시

3. 모델별 비교

실제 테스트 기준 모델별 비교:

모델	속도	품질	가격	적합한 시나리오
claude-sonnet-4.5 (Defapi)	중간	높음	중간	일상 분석 (추천)
claude-opus-4.5 (Defapi)	느림	최고	높음	복잡한 추론 작업
claude-haiku-4.5 (Defapi)	빠름	중간	낮음	단순 작업
qwen2.5:14b (로컬)	로컬	중간	무료	완전 오프라인 환경

[!TIP]
비용을 더 절약하고 싶다면, Defapi는 가격이 더 저렴하고 단순 작업에 적합한 Claude Haiku 4.5도 지원합니다.

4. Feishu 연동

MedgeClaw를 Feishu(Lark) 그룹 채팅에서 사용하고 싶으신가요? FEISHU_DEFAULT_CHAT_ID 환경 변수를 설정한 후, feishu-rich-card 스킬을 사용하여 이미지와 텍스트가 포함된 카드 형태의 보고서를 전송할 수 있습니다.

5. 연구 대시보드

매 분석 작업마다 실시간 대시보드가 자동으로 생성됩니다. data/<task_name>/dashboard/dashboard.html에 접속하면 진행 상황, 코드, 출력 미리보기를 확인할 수 있습니다.