BioClaw API 연동 가이드: WhatsApp에서 생물정보학 분석을 실행하는 방법

서론

BioClaw는 NanoClaw 아키텍처와 Claude Agent SDK를 기반으로 구축된 WhatsApp AI 어시스턴트로, 생물정보학 연구자를 위해 특별히 설계되었습니다. 사용자는 WhatsApp 그룹에 메시지를 보내는 것만으로 BLAST 검색, 단백질 구조 분석, 시퀀싱 데이터 품질 관리(QC), 문헌 검색 등 복잡한 생물정보학 작업을 서버 로그인이나 명령줄 인터페이스(CLI) 없이 직접 실행할 수 있습니다.

BioClaw의 핵심 강점은 강력한 생물정보학 도구와 편리한 인스턴트 메신저를 결합하여 연구자가 휴대폰만으로 전문적인 생물학적 데이터 분석을 완료할 수 있다는 점입니다. 협력자와 실험 결과를 논의하거나 언제 어디서든 단백질 구조를 확인해야 할 때, BioClaw는 즉각적인 응답을 제공합니다.

공식 저장소: https://github.com/Runchuan-BU/BioClaw

---

방법 1: Defapi 플랫폼 사용 (권장)

왜 Defapi를 선택해야 하나요?

Defapi는 Claude 및 Gemini 모델 API를 제공하는 플랫폼으로, 가격이 공식 가격의 절반 수준입니다. 복잡한 생물정보학 작업을 완료하기 위해 대량의 API 호출이 필요한 BioClaw와 같은 도구의 경우, Defapi를 사용하면 비용을 획기적으로 낮출 수 있습니다. Defapi는 Anthropic의 API 프로토콜과 완전히 호환되므로, 기존 SDK와 코드를 수정 없이 그대로 이전할 수 있습니다.

설정 단계

1. Defapi 계정 가입: https://defapi.org 에 접속하여 계정을 등록하고 API Key를 발급받습니다.

2. BioClaw 설정 수정: 프로젝트 루트 디렉토리의 .env 파일을 편집하여 ANTHROPIC_API_KEY를 Defapi의 API Key로 교체합니다.

# 공식 API
# ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxx

# Defapi API (가격은 공식 가격의 절반)
ANTHROPIC_API_KEY=dk-xxxxxxxxxxxxxxxx

1. API 엔드포인트 설정: src/container-runner.ts 파일에 Defapi 엔드포인트 설정을 추가합니다.

// 키 화이트리스트에 추가
const allowedVars = ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY'];

// Agent Runner의 환경 변수 설정 수정
const sdkEnv: Record<string, string | undefined> = {
  ...process.env,
  ANTHROPIC_BASE_URL: 'https://api.defapi.org/v1'
};

1. 서비스 재시작:

npm run build
npm start

Defapi 지원 모델

Defapi는 다음과 같은 다양한 모델 선택지를 제공합니다.

설정 확인

다음 명령어를 실행하여 API가 정상적으로 작동하는지 확인합니다.

curl https://api.defapi.org/v1/messages \
  -H "Authorization: Bearer dk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

---

방법 2: 공식 Anthropic API 사용

설정 단계

1. API Key 발급: https://anthropic.com 에 접속하여 API Key를 신청합니다.

2. 환경 변수 설정:

# .env 파일에 추가
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxx

1. 서비스 시작:

npm install
npm start

OAuth Token 사용 (선택 사항)

Claude Code의 OAuth 인증을 사용하는 경우:

CLAUDE_CODE_OAUTH_TOKEN=sk-xxxxxxxxxxxxxxxx

---

방법 3: OpenRouter 사용

OpenRouter는 여러 AI 제공업체를 통합하여 Claude 모델 중계를 지원합니다.

설정 단계

1. OpenRouter API Key 발급: https://openrouter.ai/settings 에 접속합니다.

2. 설정 수정:

# .env 파일
ANTHROPIC_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx

1. 엔드포인트 설정 추가: container/agent-runner/src/index.ts 파일에서:

const sdkEnv: Record<string, string | undefined> = {
  ...process.env,
  ANTHROPIC_BASE_URL: 'https://openrouter.ai/api/v1'
};

---

정상 작동 여부 확인

설정을 마친 후, 다음 단계에 따라 검증을 진행하세요.

1. 서비스 시작

npm start

2. WhatsApp 그룹에서 테스트 메시지 전송

@Bioclaw 안녕하세요, 당신은 누구인가요?

3. 로그 확인

tail -f logs/bioclaw.log

설정이 올바르다면 WhatsApp에서 BioClaw의 답변을 받을 수 있습니다.

---

BioClaw의 내부 메커니즘

컨테이너 격리 아키텍처

BioClaw는 Docker 컨테이너를 사용하여 각 WhatsApp 그룹에 격리된 컴퓨팅 환경을 제공합니다. 이 설계는 몇 가지 중요한 이점을 가집니다.

첫째, 컨테이너 간의 완벽한 격리로 인해 한 그룹의 오류가 다른 그룹에 영향을 미치지 않습니다. 둘째, 각 컨테이너에는 BLAST+, BWA, SAMtools, FastQC, PyMOL 등 전체 생물정보학 도구 체인이 사전 설치되어 있어 로컬에 별도의 소프트웨어를 설치할 필요가 없습니다. 마지막으로, 컨테이너는 일정 시간 유휴 상태가 되면 자동으로 리소스를 해제하여 컴퓨팅 비용을 절감합니다.

메시지 처리 흐름

WhatsApp에서 메시지를 보내면 BioClaw는 다음과 같은 과정을 거칩니다. 먼저 Node.js 오케스트레이터가 WhatsApp을 폴링하여 새 메시지를 가져온 후, 메시지에 트리거 단어인 @Bioclaw가 포함되어 있는지 확인합니다. 트리거 검사를 통과하면 메시지는 해당 그룹의 Docker 컨테이너로 전달됩니다. 컨테이너 내부의 Claude Agent SDK가 메시지를 수신하고 AI 모델을 호출하여 응답을 생성합니다. 마지막으로 응답은 WhatsApp API를 통해 다시 그룹으로 전송됩니다.

전체 과정은 작업의 복잡도에 따라 수초에서 수십 초 정도 소요됩니다.

세션 관리

BioClaw는 다회차 대화 세션을 지원합니다. 각 그룹은 독립적인 세션 디렉토리를 가지며 세션 상태는 SQLite 데이터베이스에 저장됩니다. 이는 컨테이너가 재시작되더라도 대화 맥락이 유지되어, 에이전트가 대화의 이전 배경을 이해하고 보다 일관된 응답을 제공할 수 있음을 의미합니다.

---

주요 활용 사례

BioClaw는 특히 다음 다섯 가지 생물정보학 응용 시나리오에 적합합니다.

1. 서열 유사성 검색 및 유전자 식별

알 수 없는 서열을 발견했을 때 BLAST 검색을 통해 식별할 수 있습니다.

@Bioclaw 이 서열로 BLAST 검색을 해줘: ATGCGATCGATCGATCGATCGATCGATCG

BioClaw는 컨테이너에서 blastn 또는 blastp를 실행하여 NCBI nr 데이터베이스를 검색하고, 종 기원, E-value, 정렬 점수(alignment score)를 포함한 유사 서열 정보를 반환합니다. 이는 유전자 식별, 상동 유전자(homolog) 탐색, 진화 관계 연구에 매우 유용합니다.

2. 단백질 구조 시각화

단백질의 3차원 구조를 확인하는 것은 구조 생물학의 핵심 요구사항입니다.

@Bioclaw P53 단백질의 3D 구조를 보여주고, PyMOL로 렌더링해줘

BioClaw는 PDB 데이터베이스에서 구조 파일을 다운로드하고 PyMOL을 사용하여 고품질 렌더링 이미지를 생성하여 사용자에게 전송합니다. 특정 잔기 표시, 리간드 결합 부위 표시, 수소 결합 네트워크 표시 등 구체적인 렌더링 방식을 지정할 수도 있습니다.

3. 시퀀싱 데이터 품질 관리 (QC)

NGS 데이터를 처리할 때 첫 번째 단계는 대개 데이터 품질을 평가하는 것입니다.

@Bioclaw 워크스페이스에 있는 FastQC 보고서를 분석해줘

BioClaw는 작업 영역 내의 FASTQ 파일을 찾아 FastQC를 실행하여 품질 관리 보고서를 생성하고, 주요 지표(GC 함량, 서열 품질, 중복률 등)를 자동으로 해석하여 사용자가 후속 분석 적합성 여부를 빠르게 판단할 수 있도록 돕습니다.

4. 차등 발현 분석 및 시각화

RNA-seq 데이터의 차등 발현 분석(DEA)은 전사체 연구의 핵심입니다.

@Bioclaw counts.csv 파일로 차등 발현 분석을 하고 화산 플롯(Volcano Plot)을 그려줘

BioClaw는 counts.csv 파일을 읽고 PyDESeq2를 사용하여 차등 발현 분석을 수행하며, 유의미하게 상향 또는 하향 조절된 유전자를 시각화하는 화산 플롯을 생성합니다. 이는 질병 마커 발굴 및 유전자 조절 메커니즘 이해에 매우 가치 있는 정보를 제공합니다.

5. 과학 문헌 검색 및 요약

최신 연구 동향을 파악하는 것은 연구자의 일상적인 요구입니다.

@Bioclaw PubMed에서 CRISPR 전달 방법(delivery methods)에 관한 최신 논문을 검색해줘

BioClaw는 PubMed 데이터베이스를 검색하여 제목, 저자, 저널, 발행일 및 초록을 포함한 관련성 높은 논문 리스트를 반환합니다. 사용자는 특정 논문에 대해 더 상세한 분석을 추가로 요청할 수 있습니다.

---

설정 매개변수 참조

BioClaw는 필요에 따라 조정할 수 있는 여러 설정 매개변수를 제공합니다.

이 매개변수들은 src/config.ts 파일에서 수정할 수 있습니다.