DureClaw
LIVE · v0.3+

두레클로 — 조선시대 두레(협동 경작) 정신을 AI 에이전트에 담다

DureClaw

분산된 디바이스의 AI 에이전트들이 하나의 채널로 묶여 실시간 협력한다.
Claude Code를 오케스트레이터로, 각 머신의 AI 에이전트들을 워커로 연결해 멀티머신 AI 팀을 구성한다.

STEP 1 — Claude Code 플러그인
/plugin marketplace add DureClaw/dureclaw
STEP 2 — 서버 설치 (멀티머신 확장 시)
bash <(curl -fsSL https://dureclaw.baryon.ai/server)

Elixir 불필요 — Docker 또는 사전빌드 바이너리 자동 사용 · 소스 보기 ↗

Claude Code 플러그인
오케스트레이터

Claude Code가 AI 팀장 역할. MCP 도구로 태스크를 에이전트에 배분하고 결과를 수집한다.

Phoenix Channel
실시간 메시지 버스

모든 에이전트가 WebSocket 채널로 연결. 태스크 배분, 진행 상황, 결과가 실시간으로 전달된다.

멀티머신
분산 워커 팀

Mac, GPU 서버, Linux 박스, Raspberry Pi까지. Tailscale 사설망으로 어디서든 연결된다.

AI 백엔드
자동 감지 실행

claude-cli, opencode, gemini, aider, codex 등 머신에 설치된 AI를 자동 감지해 태스크를 실행한다.

01

지원 환경

🍎
macOS — Apple Silicon
M1 / M2 / M3 / M4 · arm64
서버 ✓ 워커 ✓ 사전빌드
$ bash <(curl -fsSL https://dureclaw.baryon.ai/server)
✅ darwin-arm64 바이너리 다운로드 완료
✅ Tailscale 연결됨: 100.x.x.x
→ 서버 시작 · ws://100.x.x.x:4000
완전 지원 · 권장 환경
💻
macOS — Intel
Core i5/i7/i9 · x86_64
서버 ✓ 워커 ✓ 사전빌드
$ bash <(curl -fsSL https://dureclaw.baryon.ai/server)
✅ darwin-x86_64 바이너리 다운로드 완료
→ 서버 시작 · ws://192.168.x.x:4000
완전 지원
🐧
Linux — x86_64
Ubuntu / Debian / CentOS · amd64
서버 ✓ 워커 ✓ 사전빌드 Docker
$ ROLE=builder bash <(curl -fsSL https://dureclaw.baryon.ai/agent)
✅ linux-x86_64 에이전트 설치 완료
✅ claude-cli 감지됨
→ builder@gpu-server 연결 완료
완전 지원 · GPU 서버 권장
🫐
Raspberry Pi 4 / 5
Linux arm64 · aarch64
서버 ✓ 워커 ✓ 사전빌드
$ ROLE=executor bash <(curl -fsSL https://dureclaw.baryon.ai/agent)
✅ linux-arm64 에이전트 설치 완료
✅ opencode 감지됨
→ executor@raspberrypi 연결 완료
완전 지원 · executor 역할 최적
📡
Raspberry Pi Zero W/2W
WiFi 내장 · armv6 / arm64 · 512MB RAM
워커 ✓ JS 번들
$ ROLE=executor bash <(curl -fsSL https://dureclaw.baryon.ai/agent)
✅ JS 번들 모드 (armv6)
⚠ aider 경량 모드 사용
→ executor@zero-w 연결 완료 (WiFi)
IoT 센서 · 경량 executor · WiFi로 연결
🪟
Windows 10 / 11
PowerShell · x86_64
워커 ✓ Docker
PS> $env:ROLE='builder'; $env:PHOENIX='ws://100.x.x.x:4000'
irm https://dureclaw.baryon.ai/agent.ps1 | iex
✅ opencode npm 설치 완료
→ builder@DESKTOP-WIN 연결 완료
워커 지원 · PowerShell 설치 스크립트
🐳
Docker
모든 플랫폼 · ghcr.io/dureclaw/dureclaw
서버 ✓ 컨테이너
$ docker compose up
✅ ghcr.io/dureclaw/dureclaw:latest
Elixir 불필요 · /data 볼륨 마운트
→ 서버 준비 완료 · :4000
Elixir 없이 즉시 실행
02

시스템 아키텍처

① Claude Code (오케스트레이터, 맥북)
     /plugin marketplace add DureClaw/dureclaw
   └─ MCP (oah-mcp) → Phoenix WebSocket

② Phoenix Server (메시지 버스)
     bash <(curl -fsSL https://dureclaw.baryon.ai/server)
   ws://host:4000

③ oah-agent (워커, 각 머신)
     PHOENIX=ws://host:4000 ROLE=builder bash <(curl -fsSL https://dureclaw.baryon.ai/agent)
   → WebSocket 연결 → task.assign 수신
   → AI 백엔드 실행 (claude / opencode / gemini / aider / codex)
   → task.result 반환
03

빠른 시작

1
Claude Code 플러그인
필수 · 로컬 실행 가능
여기까지만 해도 바로 사용 가능.
Claude Code가 오케스트레이터로 로컬 태스크를 실행한다.
2
Phoenix 서버 설치
멀티머신 확장 시 · Docker/바이너리
Elixir 불필요.
사전빌드 바이너리 → Docker 자동 선택.
대시보드: http://서버IP:4000/
3
워커 에이전트 설치
각 원격 머신 · /setup-team 자동 안내
또는 Claude Code에게 말하세요:
"워커 추가해줘" / "팀 설정해줘"
→ 서버 IP 자동 감지 + 복붙 명령어 출력
04

AI 팀원 추가하기

새 머신에서 아래 명령어를 실행하면 설치·설정·연결이 자동 처리된다. 서버IP는 Tailscale IP(100.x.x.x) 또는 LAN IP로 교체하거나, "워커 추가해줘"라고 Claude에게 말하면 자동으로 채워준다.

builder
코드 작성
PHOENIX=ws://서버IP:4000 ROLE=builder bash <(curl -fsSL https://dureclaw.baryon.ai/agent)
tester
테스트 실행
PHOENIX=ws://서버IP:4000 ROLE=tester bash <(curl -fsSL https://dureclaw.baryon.ai/agent)
analyst
코드 분석
PHOENIX=ws://서버IP:4000 ROLE=analyst bash <(curl -fsSL https://dureclaw.baryon.ai/agent)
executor
명령 실행
PHOENIX=ws://서버IP:4000 ROLE=executor bash <(curl -fsSL https://dureclaw.baryon.ai/agent)

Work Key 생략 시 서버에서 자동 감지 · 에이전트 이름 미지정 시 역할@머신이름으로 자동 설정 · Windows는 PowerShell 스크립트 지원

05

활용 예시 — fix-agent

3개의 에이전트가 협력해 레포지토리 버그를 자동 분석·수정·PR 생성하는 파이프라인.

시작
Claude Code가 버그 리포트 수신 → 에이전트 배분
analyzer→버그 탐지·분석
분석 완료
분석 결과 → fixer에게 전달
analyzer✓root cause 특정
fixer→코드 수정
수정 완료
수정 코드 → tester 검증 + PR 생성
fixer✓패치 완료
tester→테스트 실행 + PR 생성
PR 자동 생성 · 테스트 통과 확인 · 리뷰 요청까지 자동화
06

채널 이벤트

EVENTDIRECTIONPAYLOAD (주요 필드)설명
task.assignorch → agentto, task_id, role, instructions태스크 할당. 대상 agent가 AI 백엔드 실행.
task.progressagent → alltask_id, message, output_tail10초마다 진행 상황 브로드캐스트.
task.resultagent → alltask_id, exit_code, artifacts[]태스크 완료 보고. ARTIFACT: 라인 자동 파싱.
task.cancelorch → agenttask_id실행 중 태스크 취소. AbortController 신호.
task.blockedany → alltask_id, reason진행 불가. orchestrator가 재배정 판단.
state.updateany → serverkey: valueWork Key 상태 업데이트 (DETS 영속).
mailbox.postany → targetto, body오프라인이면 큐잉, 온라인이면 즉시 전달.
agent.helloserver → allagent, role, machine에이전트 JOIN 알림.
agent.byeserver → allagent, role에이전트 퇴장 알림.
07

REST API

METHODENDPOINT설명
GET/api/health서버 상태 · work_key 개수
GET/api/presence온라인 에이전트 목록 (name, role, machine)
GET/api/work-keysWork Key 목록
GET/api/work-keys/latest최신 Work Key (없으면 404)
POST/api/work-keys새 Work Key 발급
POST/api/task태스크 디스패치 { role, to, instructions }
GET/api/task/:id태스크 결과 폴링
POST/api/task/:id/result태스크 결과 저장 · 채널 브로드캐스트
GET/api/state/:wkWork Key 상태 조회
PATCH/api/state/:wkWork Key 상태 업데이트
GET/api/mailbox/:agent에이전트 mailbox 읽기
POST/api/mailbox/:agent에이전트 mailbox 메시지 전송