ClawTeam이란 무엇인가 2026 — git worktree와 tmux로 만드는 AI 에이전트 팀 운영법

Posted on by

AI 에이전트를 혼자 쓰는 시대는 이미 지났습니다.

Claude Code 한 창, Codex 한 창 켜놓고 번갈아 가며 지시하는 방식은 2025년 초까지만 해도 “AI를 잘 쓰는 사람”의 모습이었습니다. 지금은 다릅니다. 같은 저장소에서 에이전트 다섯 개가 동시에 다른 기능을 짜고, 리더 에이전트가 그 결과를 모아 판단을 내리는 구조가 실제 개발자들의 워크플로우로 들어오고 있습니다.

ClawTeam은 그 흐름의 한가운데 있는 오픈소스입니다.

복잡한 큐 시스템도, Redis 설치도, 별도 서버도 필요 없습니다. git worktree와 tmux, 그리고 파일시스템 하나로 AI 에이전트를 팀 단위로 운영하는 구조를 만듭니다. 홍콩대 데이터인텔리전스 랩(HKUDS)이 공개한 이 저장소는 2026년 3월 18일 기준으로 꾸준히 업데이트 중이며, 이미 Claude Code, Codex, OpenClaw, Cursor 네 가지 에이전트를 공식 지원합니다.

이 글은 ClawTeam이 어떻게 작동하는지, git worktree를 왜 에이전트 격리에 쓰는지, tmux로 병렬 관리하는 실제 패턴이 무엇인지를 정리합니다. 기존 멀티에이전트 프레임워크(Cowork, OpenClaw)와 어떻게 다른지도 함께 비교합니다.

ClawTeam을 한 줄로 요약하면: leader 에이전트가 worker 에이전트를 spawning하고, 각 worker가 격리된 git worktree에서 독립 실행된 뒤, tmux window를 통해 진행 상황을 조율하는 경량 멀티에이전트 오케스트레이션 도구입니다.

지금 결론

Claude Code 한 창으로 충분한 상황이 있습니다. 근데 아닌 상황도 있습니다. ClawTeam은 후자를 위한 도구입니다.

ClawTeam이 맞는 상황:
– 작업이 독립적인 하위 태스크로 쪼개지고, 병렬로 돌릴 수 있을 때
– Redis나 Kafka 없이 가볍게 멀티에이전트를 시험해보고 싶을 때
– Claude Code, Codex, Cursor 중 하나 이상을 이미 쓰고 있을 때
– 에이전트 간 충돌(같은 파일을 동시에 수정하는 상황)이 실제로 문제가 됐을 때

ClawTeam이 맞지 않는 상황:
– 에이전트 간 실시간 상태 공유가 필수인 작업
– 장기 실행 중 장애 자동 복구가 중요한 프로덕션 환경
– 클라우드 기반 에이전트 실행이 필요한 경우

ClawTeam이란 무엇인가

ClawTeam은 HKUDS(홍콩대 데이터인텔리전스 랩)가 만든 Agent Swarm Intelligence 프레임워크입니다. 한 명의 leader 에이전트가 여러 worker 에이전트를 spawn하고, 각 worker가 역할을 나눠 협업하는 구조입니다.

핵심 철학: 무거운 인프라 없이

기존 멀티에이전트 프레임워크들은 대개 다음 중 하나를 요구했습니다.

  • 메시지 큐: RabbitMQ, Kafka
  • 상태 저장소: Redis, PostgreSQL
  • 별도 오케스트레이터: 에이전트를 관리하는 별도 프로세스

ClawTeam은 이것들을 전부 빼고 파일시스템과 tmux로 대체했습니다.

에이전트 간 통신 = 파일 (inbox, task, board 디렉터리)
에이전트 격리   = git worktree (각 worker가 독립된 워킹디렉터리 보유)
에이전트 가시성 = tmux window (각 worker가 별도 창에서 실행)

단순한 것처럼 보이지만, 이 단순함이 실제 실무 환경에서 강점이 됩니다. 설치가 빠르고, 디버깅이 직관적이고, 기존 개발 환경에 그대로 붙습니다.

지원 에이전트

ClawTeam은 현재 다음 네 가지 CLI 에이전트를 공식 지원합니다.

에이전트 특징
Claude Code Anthropic. 가장 널리 쓰임
Codex OpenAI. 코드 생성 특화
OpenClaw 오픈소스 범용 에이전트
Cursor 에디터 기반. Cursor Background Agent 경유

git worktree로 에이전트를 격리하는 이유

멀티에이전트에서 가장 먼저 부딪히는 현실적인 문제가 있습니다. 에이전트 둘이 같은 파일을 동시에 수정하면 어떻게 될까요.

정답은 충돌입니다. 더 나쁜 경우는 충돌도 없이 한 에이전트의 변경이 다른 에이전트의 변경을 덮어쓰는 것입니다. 이 문제를 근본적으로 해결하는 방법이 git worktree입니다.

git worktree란

git worktree는 하나의 git 저장소에서 여러 개의 워킹디렉터리를 동시에 체크아웃하는 기능입니다. .git 데이터(오브젝트 데이터베이스, refs, config)는 공유하지만, 실제 파일이 존재하는 디렉터리는 분리됩니다.

# 기본 사용 예시
git worktree add ../feature-auth feature/auth
git worktree add ../feature-api feature/api

# 결과 구조
my-project/          # 메인 워킹트리 (main 브랜치)
my-project-auth/     # 분리된 워킹트리 (feature/auth)
my-project-api/      # 분리된 워킹트리 (feature/api)

세 디렉터리 모두 같은 git 저장소를 공유하지만, 각 디렉터리는 독립된 파일 공간입니다. 에이전트 A가 my-project-auth/에서 작업하는 동안 에이전트 B는 my-project-api/에서 완전히 다른 파일을 만질 수 있습니다.

Anthropic의 Claude Code 창시자 Boris Cherny는 worktree를 “자신의 1순위 생산성 팁”이라고 공개적으로 언급했고, 3~5개의 worktree를 동시에 돌리는 방식으로 작업한다고 밝혔습니다.

ClawTeam이 worktree를 쓰는 방식

ClawTeam에서 leader가 clawteam spawn을 실행하면 자동으로 일어나는 일이 세 가지 있습니다.

  1. 해당 worker 전용 git worktree 생성
  2. 해당 worktree용 tmux window 생성
  3. worker 에이전트가 그 worktree 안에서 실행됨

직접 git worktree add를 치거나 tmux 창을 수동으로 열 필요가 없습니다. leader가 명령 하나로 이 과정을 자동화합니다.

worktree 격리의 실제 한계

격리가 완전하지 않은 영역도 있습니다. 알고 쓰는 것이 중요합니다.

공유되는 것들:
– 로컬 데이터베이스 상태 (SQLite, PostgreSQL 로컬 인스턴스)
– 포트 (두 에이전트가 같은 포트에서 서버를 띄우려 하면 충돌)
– 캐시 디렉터리 (node_modules, .cache 등)
– 디스크 공간 (2GB 코드베이스에서 5개 worktree 운영 시 약 10GB 추가 사용)

격리되는 것들:
– 코드 파일
– 브랜치와 커밋 이력
– 환경 변수 설정 (worktree별로 다르게 설정 가능)

tmux로 병렬 관리하는 3가지 패턴

tmux는 단순한 터미널 분할 도구가 아닙니다. ClawTeam 맥락에서는 에이전트 팀의 실시간 관제 패널이자 격리된 실행 환경입니다.

패턴 1: window-per-worker (가장 기본)

각 에이전트가 별도 tmux window에서 실행됩니다. 세션 하나 안에 window가 에이전트 수만큼 생깁니다.

tmux session: clawteam-project
  window 0: leader        (전체 조율, 진행 상황 모니터)
  window 1: worker-auth   (인증 모듈 작업)
  window 2: worker-api    (API 엔드포인트 작업)
  window 3: worker-test   (테스트 작성)

Ctrl+b 2로 worker-api 창으로 즉시 이동해 진행 상황 확인이 가능합니다. 에이전트가 멈췄거나 오류가 났을 때 직접 개입할 수 있는 가시성이 확보됩니다.

패턴 2: pane-split (소규모 팀용)

window를 분할해서 여러 에이전트 출력을 동시에 보는 방식입니다. 에이전트 수가 3개 이하일 때 유용합니다.

+------------------+------------------+
|                  |                  |
|  leader          |  worker-1        |
|  (조율 로그)      |  (기능 A 진행중) |
|                  |                  |
+------------------+------------------+
|                                     |
|  worker-2 (기능 B 진행중)            |
|                                     |
+-------------------------------------+

dmux(formkit이 만든 에이전트 멀티플렉서)가 이 패턴을 자동화합니다. n 키 하나로 새 pane을 열고 프롬프트를 입력하면 worktree와 branch, 에이전트 실행까지 자동 처리됩니다.

패턴 3: session-per-project (대규모, 프로젝트 분리)

여러 프로젝트를 동시에 진행할 때 프로젝트마다 tmux session을 분리합니다.

tmux session: project-alpha
  window 0: leader
  window 1~5: workers

tmux session: project-beta
  window 0: leader
  window 1~3: workers

tmux ls로 세션 목록 확인, tmux attach -t project-alpha로 전환합니다. 프로젝트 간 컨텍스트 스위칭이 깔끔합니다.

tmux + worktree 조합 도구 비교

ClawTeam 외에도 이 조합을 쓰는 도구들이 있습니다. 목적이 다르므로 상황에 맞게 선택합니다.

도구 특징 적합한 상황
ClawTeam leader-worker swarm, 자동 spawn 작업 분배와 팀 조율이 필요할 때
workmux tmux + worktree 수동 관리 단순 병렬 실행, 직접 제어 선호
dmux pane 단위 자동화, Claude Code 특화 빠른 병렬 실험, 소규모
muxtree bash 스크립트 1개, 초경량 최소 의존성 환경

swarm 구조 비교: Cowork vs OpenClaw vs ClawTeam

멀티에이전트 접근 방식은 구조적으로 크게 세 가지 계열로 나뉩니다. 볼트에서 앞서 정리한 내용과 함께 비교합니다.

Cowork (DAG/P2P 구조)

Cowork는 에이전트 간 관계를 방향성 비순환 그래프(DAG)로 표현합니다. 에이전트 A의 출력이 에이전트 B의 입력이 되는 파이프라인 방식입니다.

강점:
– 작업 의존성이 명확한 파이프라인에 적합
– 에이전트 간 P2P 통신 (중앙 집중 없음)
– 복잡한 워크플로우 모델링 가능

약점:
– 그래프 설계 비용이 있음
– 실시간 동적 팀 구성이 어려움
– CLI 에이전트 지원이 ClawTeam보다 제한적

OpenClaw (Gateway/중앙집중 구조)

OpenClaw는 중앙 Gateway를 통해 모든 에이전트 요청을 라우팅합니다. 에이전트 팩(ClawTeam.com과는 다른 서비스)이나 플러그인 방식으로 기능을 확장합니다.

강점:
– 단일 진입점으로 모니터링·로깅 일원화
– 설정 기반으로 팀 구성 (코드 없이도 가능)
– 상업적 생태계 (Packs, 통합)

약점:
– Gateway가 병목 또는 단일 장애점
– 자체 호스팅보다는 SaaS 의존성 높음
– git worktree 수준의 네이티브 격리는 없음

ClawTeam (Swarm/분산 구조)

강점:
– 인프라 의존성 없음 (파일시스템 + tmux)
– leader가 동적으로 worker를 spawn
– git worktree로 코드 충돌 근본 방지
– CLI 에이전트 4종 공식 지원

약점:
– 장애 복구 자동화 없음 (worker가 죽으면 수동 개입 필요)
– 대규모 팀(10개+)에서 tmux 관리 복잡도 증가
– 실시간 상태 공유 제한적 (파일 기반이라 지연 있음)

구조 비교 한눈에 보기

기준 Cowork OpenClaw ClawTeam
통신 방식 DAG/P2P 중앙 Gateway 파일시스템
에이전트 격리 프로세스 프로세스 git worktree
설치 복잡도 중간 낮음 낮음
인프라 필요 최소 Gateway 필요 없음
동적 팀 구성 제한적 중간 강점
장애 복구 중간 Gateway 의존 수동
오픈소스 일부 일부 완전

실제로 써보면 달라지는 것들

ClawTeam README에 나오는 헤지펀드 예시는 구조를 이해하는 데 도움이 됩니다. 5명의 Analyst 에이전트(버핏 스타일, 성장주, 기술적 분석, 펀더멘탈, 센티먼트)가 동시에 분석을 돌리고, Risk Manager 에이전트가 신호를 취합한 뒤, Portfolio Manager(leader)가 최종 판단을 내리는 구조입니다.

실무에서 비슷하게 쓸 수 있는 패턴을 몇 가지 정리합니다.

풀스택 기능 개발

leader: 기능 명세 분석, 태스크 분배, 최종 통합
worker-backend: API 엔드포인트 구현
worker-frontend: UI 컴포넌트 구현
worker-test: 테스트 케이스 작성

각 worker가 독립된 worktree에서 작업하고, leader가 주기적으로 진행 상황을 파일(board)로 수집합니다. 완료 후 leader가 PR 생성까지 담당합니다.

다각도 코드 리뷰

leader: 리뷰 범위 설정, 최종 판단
worker-security: 보안 취약점 검토
worker-performance: 성능 이슈 검토
worker-style: 코드 스타일·가독성 검토

각 관점에서 독립적으로 리뷰가 이루어지므로, 단일 에이전트 리뷰보다 사각지대가 줄어듭니다.

리서치 + 정리 분리

leader: 주제 정의, 최종 합성
worker-1: 소스 A 리서치
worker-2: 소스 B 리서치
worker-3: 선행 연구 검토
writer: 수집된 팩트 기반 초안 작성

컨텍스트를 나눠 수집하고 마지막에 합치는 방식은 단일 에이전트가 처리하는 것보다 컨텍스트 창 한계를 효과적으로 우회합니다.

언제 ClawTeam이 맞고, 언제 아닌가

ClawTeam을 써야 할 때 체크리스트

아래 항목 중 3개 이상 해당되면 ClawTeam이 유효한 선택입니다.

  • [ ] 하나의 복잡한 작업을 독립적인 하위 태스크로 나눌 수 있다
  • [ ] 에이전트들이 다른 파일/디렉터리를 주로 다룬다
  • [ ] Redis, Kafka 같은 메시지 인프라 없이 실험하고 싶다
  • [ ] Claude Code, Codex, OpenClaw, Cursor 중 하나를 이미 쓴다
  • [ ] tmux를 이미 쓰거나 배울 의향이 있다
  • [ ] 에이전트 충돌(같은 파일 동시 수정)을 경험한 적 있다
  • [ ] 단계적으로 결과를 검토하고 싶다 (배치 실행보다 점진적 진행)

ClawTeam을 피해야 할 때

에이전트 간 실시간 상태 공유가 핵심인 작업: 파일 기반 통신은 지연이 있습니다. 에이전트 A의 결과를 에이전트 B가 밀리초 단위로 받아야 한다면 맞지 않습니다.

프로덕션 환경 자동 복구: worker가 예외로 종료됐을 때 ClawTeam은 자동으로 재시작하지 않습니다. 사람이 tmux 창을 보고 개입해야 합니다. 무인 실행이 필요한 환경이라면 별도 하네스 코드가 필요합니다.

10개 이상의 에이전트 팀: tmux window가 10개를 넘어가면 탐색 비용이 늘어납니다. 이 스케일에서는 별도 오케스트레이터가 더 적합합니다.

클라우드 실행: ClawTeam은 로컬 환경 중심입니다. 에이전트를 클라우드 서버에 분산 배포하는 구조는 현재 기본 지원 범위 밖입니다.

실수 TOP 5

ClawTeam을 처음 도입할 때 흔히 겪는 실수들입니다.

1. worktree를 너무 많이 만들어서 디스크가 터진다

2GB 코드베이스에 worktree 5개를 만들면 약 10GB가 추가로 사용됩니다. 시작 전에 df -h로 여유 공간을 확인하세요. 완료된 worktree는 git worktree remove로 즉시 정리합니다.

2. 데이터베이스 공유로 race condition 발생

SQLite나 로컬 PostgreSQL을 공유하면 두 worker가 동시에 같은 레코드를 수정하는 상황이 생깁니다. 각 worker가 독립된 DB 파일(SQLite)을 쓰거나, DB 의존성 없는 순수 파일 작업으로 범위를 제한하는 것이 안전합니다.

3. leader 에이전트에게 너무 많은 컨텍스트를 몰아준다

leader는 전체 조율에 집중해야 합니다. 개별 파일을 직접 수정하거나 긴 코드를 분석하게 하면 컨텍스트 창이 빠르게 소모됩니다. leader는 inbox/board 파일 읽기와 지시 내리기에만 집중시키세요.

4. 포트 충돌을 무시하고 서버를 여러 개 띄운다

worker-backend와 worker-frontend가 모두 3000번 포트를 쓰려 하면 충돌합니다. 각 worker의 환경변수에 다른 포트를 명시하거나, worktree별 .env 파일에 PORT=3001, PORT=3002처럼 구분해두세요.

5. tmux를 쓸 줄 모른 채 시작한다

Ctrl+b c (새 window), Ctrl+b n (다음 window), Ctrl+b d (세션 분리). 이 세 가지만 먼저 익히면 ClawTeam 운영에 필요한 tmux 조작의 80%는 커버됩니다.

FAQ

Q. ClawTeam을 써보려면 git worktree를 먼저 배워야 하나요?

ClawTeam이 자동으로 worktree를 생성하므로 명령어를 외울 필요는 없습니다. 단, worktree가 뭔지 개념을 알고 있으면 오류가 났을 때 디버깅이 훨씬 쉬워집니다. git worktree list로 현재 등록된 worktree를 확인하고, git worktree remove로 정리하는 두 가지 정도는 알아두면 충분합니다.

Q. Claude Code 없이 Codex만으로도 ClawTeam을 쓸 수 있나요?

가능합니다. ClawTeam은 에이전트 종류를 spawn 시점에 지정합니다. Codex만 쓰는 것도, Claude Code와 Codex를 섞어 쓰는 것도 지원됩니다. 비용이나 작업 성격에 따라 worker마다 다른 에이전트를 붙이는 실험도 가능합니다.

Q. 우리 회사 코드베이스에 바로 붙여도 되나요?

작은 격리된 브랜치에서 먼저 실험하는 것을 권장합니다. ClawTeam은 leader의 판단에 따라 코드를 수정합니다. 프로덕션 브랜치가 아닌 feature 브랜치에서 실험하고, 결과를 PR로 올려 사람이 검토하는 흐름이 안전합니다.

Q. workmux, dmux, muxtree와 ClawTeam의 차이가 뭔가요?

workmux, dmux, muxtree는 “worktree + tmux 설정 자동화 도구”입니다. 사람이 각 창에서 에이전트에게 직접 지시합니다. ClawTeam은 leader 에이전트가 worker 에이전트에게 지시합니다. 사람이 관여하는 레벨이 다릅니다. ClawTeam은 자동화 수준이 한 단계 높고, 그만큼 제어권을 에이전트에게 더 넘깁니다.

Q. HKUDS ClawTeam과 clawteam.com(에이전트 팩)은 같은 건가요?

다릅니다. HKUDS/ClawTeam은 홍콩대 연구팀이 만든 오픈소스 swarm 프레임워크입니다. clawteam.com은 OpenClaw용 에이전트 팩을 판매하는 상업 서비스입니다. 이름이 같아서 혼동하기 쉽지만 전혀 다른 프로젝트입니다. 이 글은 HKUDS/ClawTeam(GitHub 오픈소스)을 기준으로 합니다.

Q. 에이전트가 실행 중에 죽으면 ClawTeam이 자동으로 재시작해 주나요?

현재 기본 기능으로는 자동 재시작이 없습니다. tmux 창에서 직접 확인하고 재실행해야 합니다. 무인 장기 실행이 필요하다면 별도의 하네스 스크립트(health check + 자동 재시작)를 직접 구성해야 합니다.

참고 자료

관련 글