ClawTeam — AI 에이전트 군집 지능 (Swarm Intelligence) 프레임워크

프로젝트 개요

ClawTeam은 홍콩대학교(HKUDS 연구실)에서 개발한 AI 에이전트 군집 지능(Agent Swarm Intelligence) 프레임워크다. 하나의 명령어로 여러 AI 에이전트가 팀을 이루어 복잡한 작업을 자율적으로 분담·조율·완수하게 해준다.

“Human provides the goal. The Agent Team orchestrates everything else.”

단일 에이전트의 한계(격리된 작업 수행, 수동 조율 필요)를 극복하여, 에이전트들이 스스로 팀을 구성하고 실시간으로 협력하는 방식으로 작동한다.

Solo → Swarm: 에이전트 한 명 → 에이전트 군집
라이선스: MIT
언어: Python 3.10+
지원 에이전트: Claude Code, Codex, OpenClaw, nanobot, Kimi CLI, 커스텀 스크립트

핵심 기능 및 아키텍처

기본 작동 원리

리더 에이전트가 목표를 받아 팀을 구성하고 작업을 분배
워커 에이전트들이 각자 격리된 환경(git worktree + tmux)에서 병렬 작업
CLI 명령어 기반으로 에이전트 간 통신 (특정 SDK 없음)
리더가 실시간으로 진행 상황 모니터링 후 동적으로 전략 재조정

아키텍처 특징

항목	ClawTeam	기타 멀티에이전트 프레임워크
사용 주체	AI 에이전트 자신	오케스트레이션 코드를 짜는 사람
설정	pip install + 리더에게 프롬프트 한 번	Docker, 클라우드 API, YAML 설정
인프라	파일시스템 + tmux	Redis, 메시지 큐, 데이터베이스
에이전트 지원	모든 CLI 에이전트	프레임워크 전용
격리 방식	Git worktree (실제 브랜치, 실제 diff)	컨테이너 또는 가상환경
지능화 방식	군집이 CLI로 자기 조직화	하드코딩된 오케스트레이션 로직

주요 구성 요소

1. 에이전트 자기 조직화 (Agent Self-Organization)

리더 에이전트가 clawteam spawn으로 워커 생성
자동 주입 조율 프롬프트: 워커가 생성될 때 자동으로 다음 명령어 사용법을 알려줌

📋 Check your tasks: clawteam task list <team> --owner <your-name>
▶️ Start a task:     clawteam task update <team> <id> --status in_progress
✅ Finish a task:    clawteam task update <team> <id> --status completed
💬 Message leader:   clawteam inbox send <team> leader "status update..."
📨 Check inbox:      clawteam inbox receive <team>
😴 Report idle:      clawteam lifecycle idle <team>

2. 워크스페이스 격리 (Workspace Isolation)

각 에이전트에 독립 git worktree 할당 (clawteam/{team}/{agent} 브랜치)
병렬 작업 중 충돌 방지
체크포인트/머지/정리 명령어 제공

3. 태스크 추적 (Task Tracking with Dependencies)

공유 칸반: pending → in_progress → completed / blocked
--blocked-by 의존성 체인 → 완료 시 자동 언블록
상태별·담당자별 필터링, JSON 출력 지원

4. 에이전트 간 메시징 (Inter-Agent Messaging)

점대점 인박스(send/receive/peek)
팀 전체 브로드캐스트
파일 기반(기본) 또는 ZeroMQ P2P 전송 방식 선택 가능

5. 모니터링 및 대시보드

clawteam board show my-team      # 터미널 칸반 보드
clawteam board live my-team      # 자동 갱신 대시보드
clawteam board attach my-team    # 타일드 tmux 뷰
clawteam board serve --port 8080 # 웹 UI (실시간 업데이트)

6. 팀 템플릿 (TOML 기반)

TOML 파일로 팀 아키타입 정의 (역할, 태스크, 프롬프트)
한 명령어로 완성된 팀 즉시 실행: clawteam launch <template>
내장 템플릿: AI 헤지펀드 (7에이전트)

사용 방법 / 설치

설치

pip install clawteam
 
# 소스에서 설치
git clone https://github.com/HKUDS/ClawTeam.git
cd ClawTeam
pip install -e .
 
# ZeroMQ P2P 전송 옵션 포함
pip install -e ".[p2p]"

요구사항: Python 3.10+, tmux, CLI 코딩 에이전트 (claude, codex 등)

에이전트가 주도하는 방식 (추천)

"Build a web app. Use clawteam to split the work across multiple agents."

Claude Code에 이렇게 입력하면, 에이전트가 알아서 팀 생성 → 워커 스폰 → 태스크 분배 → 조율.

수동 방식

# 1. 팀 생성
clawteam team spawn-team my-team -d "Build auth module" -n leader
 
# 2. 워커 에이전트 스폰 (각자 git worktree, tmux 창, 아이덴티티 자동 부여)
clawteam spawn --team my-team --agent-name alice --task "Implement OAuth2"
clawteam spawn --team my-team --agent-name bob --task "Write unit tests"
 
# 3. 모니터링
clawteam board attach my-team

지원 에이전트

에이전트	스폰 명령어	상태
Claude Code	`clawteam spawn tmux claude --team ...`	✅ 완전 지원
Codex	`clawteam spawn tmux codex --team ...`	✅ 완전 지원
OpenClaw	`clawteam spawn tmux openclaw --team ...`	✅ 완전 지원
nanobot	`clawteam spawn tmux nanobot --team ...`	✅ 완전 지원
Kimi CLI	`clawteam spawn tmux kimi --team ...`	✅ 완전 지원
Cursor	`clawteam spawn subprocess cursor --team ...`	🔮 실험적

주요 사용 사례

1. 자율 ML 연구 (8 에이전트 × 8 H100 GPU)

Andrej Karpathy의 autoresearch 프로젝트 기반. 하나의 프롬프트로:

8개 전문 연구 에이전트를 8개 H100 GPU에 분산 배치
2,430+ 실험 자율 수행
val_bpb 지표 1.044 → 0.977 (6.4% 개선)
인간 개입 없이 약 30 GPU-시간 소요

2. 풀스택 소프트웨어 엔지니어링

“풀스택 Todo 앱 빌드” 명령 → 5개 전문 에이전트 자동 스폰:

architect → backend1, backend2, frontend, tester
의존성 체인 자동 관리 (architect 완료 → backend 언블록 → tester 언블록)
에이전트 간 OpenAPI 스펙, API 엔드포인트 정보 자동 공유

3. AI 헤지펀드 (7 에이전트 팀)

clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"

Portfolio Manager (리더) + 5개 분석가 (버핏/성장/기술/펀더멘털/센티먼트) + Risk Manager
각 에이전트가 독립 분석 → 리스크 관리자가 종합 → 포트폴리오 매니저가 최종 결정

특이점 / 인상적인 점

프레임워크 없는 프레임워크: 에이전트들이 단순한 CLI 명령어만으로 스스로 조율. Redis, 메시지 큐 등 무거운 인프라 불필요.
에이전트가 에이전트를 스폰: 리더 에이전트가 스스로 팀을 구성하고 필요시 동적으로 재편. “AI가 AI 팀장 역할을 한다”는 개념이 실제로 구현됨.
자동 주입 조율 프롬프트: 워커 에이전트 생성 시 협업 방법을 자동으로 알려주는 프롬프트가 주입됨 → 어떤 CLI 에이전트도 즉시 팀원이 될 수 있음.
Git worktree 기반 격리: 에이전트마다 독립 브랜치를 자동 생성하여 병렬 작업 중 충돌 없이 진행 가능.
한국어 공식 문서 제공: HKUDS가 공식적으로 한국어 README를 지원 (README_KR.md).
실증된 결과: 단순 개념 증명이 아니라 실제 ML 연구(2430+ 실험, 6.4% val_bpb 개선)에 적용한 실험 결과를 공개함.
Claude Code 스킬 내장: pip install clawteam만으로 Claude Code와 연동되는 스킬이 자동 활성화됨.

Context Vault

탐색기