나는 1300년 전의 제국 제도를 사용하여 AI Multi-Agent 협업 아키텍처를 재설계했습니다. 그 결과, 고대인이 현대 AI 프레임워크보다 권력 분립과 견제에 대해 더 잘 이해하고 있다는 것을 발견했습니다.

12개의 AI Agent(11개의 비즈니스 역할 + 1개의 호환 역할)가 삼성육부(三省六部)를 구성합니다: 태자(太子)의 분류, 중서성(中书省)의 계획, 문하성(门下省)의 심사 및 봉박(封驳), 상서성(尚书省)의 발령, 그리고 육부(六部)와 이부(吏部)의 병렬 실행. CrewAI보다 한 단계 높은 제도적 심사(Institutional Audit)를 제공하며, AutoGen보다 실시간 칸반(Kanban)을 하나 더 갖추고 있습니다.

🎬 데모 보기 · 🚀 30초 체험 · 🏛️ 아키텍처 · 📋 칸반 기능 · 📚 아키텍처 문서 · English · 日本語 · 기여하기

🎥 삼성육부 AI Multi-Agent 협업 전체 프로세스 데모

🐳

OpenClaw가 없나요? 다음 한 줄을 실행하세요:
docker run -p 7891:7891 cft0808/edict

그러면 전체 칸반 데모(시뮬레이션 데이터 사전 설정됨)를 체험할 수 있습니다.

대부분의 Multi-Agent 프레임워크의 방식은 다음과 같습니다:

"자, 너희 AI들끼리 알아서 대화하고, 대화가 끝나면 결과를 나에게 가져와."

그러면 당신은 어떤 처리를 거쳤는지 알 수 없는 결과물 뭉치를 받게 되며, 이는 재현 불가능하고, 감사(Audit)할 수 없으며, 개입할 수도 없습니다.

삼성육부의 사고방식은 완전히 다릅니다 —— 우리는 중국에 1400년 동안 존재했던 제도적 아키텍처를 사용했습니다:

당신 (황제) → 태자 (분류) → 중서성 (계획) → 문하성 (심의) → 상서성 (발령) → 육부 (실행) → 회주 (보고)

이것은 화려한 은유가 아니라, 진정한 권력 분립과 견제입니다:

기능	CrewAI	MetaGPT	AutoGen	삼성육부
심사 메커니즘	❌ 없음	✅ 문하성 전담 심사 · 봉박 가능
실시간 칸반	❌	❌	❌	✅ 군기처(军机处) Kanban + 타임라인
작업 개입	❌	❌	❌	✅ 중단 / 취소 / 복구
흐름 감사	❌	✅ 완전한 상소문(奏折) 아카이브
Agent 상태 모니터링	❌	❌	❌	✅ 하트비트(Heartbeat) + 활성도 감지
모델 핫스위칭	❌	❌	❌	✅ 칸반 내 원클릭 LLM 전환
스킬 관리	❌	❌	❌	✅ Skills 조회 / 추가
뉴스 애그리게이션 푸시	❌	❌	❌	✅ 천하 요보 + Feishu 푸시
배포 난이도	중	고	중	저 · 원클릭 설치 / Docker

핵심 차이점: 제도적 심사 + 완전한 관측 가능성 + 실시간 개입 가능성

🔍 왜 「문하성 심사」가 핵심 무기인가요? (클릭하여 확장)

CrewAI와 AutoGen의 Agent 협업 모드는 "완료 후 제출" 방식입니다. 즉, 산출물의 품질을 검사하는 사람이 없습니다. 마치 회사에 QA 부서가 없어서 엔지니어가 코드를 작성하자마자 바로 배포하는 것과 같습니다.

삼성육부의 문하성은 바로 이 일을 전문적으로 수행합니다:

• 📋 계획 품질 검토 —— 중서성의 계획이 완벽한가? 하위 작업 분할이 합리적인가?
• 🚫 부적격 산출물 봉박(Reject) —— 단순한 경고(Warning)가 아니라, 즉시 반려하여 재작업을 지시합니다.
• 🔄 강제 재작업 루프 —— 계획이 기준에 도달할 때까지 반복됩니다.

이것은 선택적인 플러그인이 아닙니다 —— 아키텍처의 일부입니다. 모든 어명(旨意)은 예외 없이 문하성을 거쳐야 합니다.

이것이 바로 삼성육부가 복잡한 작업을 처리하면서도 신뢰할 수 있는 결과를 내는 이유입니다. 실행 계층으로 전달되기 전에 강제적인 품질 관문이 있기 때문입니다. 1300년 전 당 태종은 이미 깨달았습니다 —— 제약받지 않는 권력은 반드시 오류를 범한다는 것을.

• 태자의 메시지 분류 —— 잡담은 자동 응답하고, 어명(旨意)인 경우에만 작업을 생성
• 삼성(중서·문하·상서)은 계획, 심의, 발령을 담당
• 칠부(호·예·병·형·공·이 + 조참관)는 전문적인 실행을 담당
• 엄격한 권한 매트릭스 —— 누가 누구에게 메시지를 보낼 수 있는지 명확히 규정
• 상태 전환 검증 —— kanban_update.py가 합법적인 경로 전환을 강제하며, 불법적인 상태 점프는 거부됨
• 각 Agent의 독립성 —— 독립된 Workspace · 독립된 Skills · 독립된 모델 사용
• 어명 데이터 클리닝 —— 제목/비고에서 파일 경로, 메타데이터, 무효한 접두사를 자동 제거

docker run -p 7891:7891 cft0808/sansheng-demo

http://localhost:7891 을 열면 군기처 칸반을 체험할 수 있습니다.

⚠️ exec format error 발생 시

？ (클릭하여 확장)

exec format error

？ (클릭하여 확장)

만약 x86/amd64 머신(예: Ubuntu, WSL2)에서 다음을 본다면:

exec /usr/local/bin/python3: exec format error

이는 이미지 아키텍처가 일치하지 않기 때문입니다. --platform 파라미터를 사용하세요:

docker run --platform linux/amd64 -p 7891:7891 cft0808/sansheng-demo

또는 docker-compose를 사용하세요 (platform: linux/amd64가 내장되어 있습니다):

docker compose up

• OpenClaw 설치 완료
• Python 3.10+
• macOS / Linux

git clone https://github.com/cft0808/edict.git
cd edict
chmod +x install.sh && ./install.sh

설치 스크립트 자동 수행 항목:

• ✅ 전체 Agent Workspace 생성 (태자/이부/조참 포함, 기존 main 브랜치와 호환)
• ✅ 각 성/부의 SOUL.md 작성 (페르소나 + 워크플로우 규칙 + 데이터 정제 규격)
• ✅ Agent 및 권한 매트릭스를 openclaw.json에 등록
• ✅ 심볼릭 링크를 통한 데이터 통합 (각 Workspace의 data/scripts → 프로젝트 디렉토리로 연결하여 데이터 일관성 보장)
• ✅ Agent 간 통신 가시성 설정 (sessions.visibility all을 통해 메시지 도달 불가능 문제 해결)
• ✅ 모든 Agent에 API Key 동기화 (이미 설정된 Agent로부터 자동 복사)
• ✅ React 프론트엔드 빌드 (Node.js 18+ 필요, 미설치 시 건너뜀)
• ✅ 데이터 디렉토리 초기화 + 최초 데이터 동기화 (관리관 통계 포함)
• ✅ Gateway 재시작하여 설정 적용

⚠️ 최초 설치 시: 먼저 API Key를 설정해야 합니다: openclaw agents add taizi 명령을 실행한 후, 다시 ./install.sh를 실행하여 모든 Agent에 동기화하세요.

# 방식 1: 원클릭 실행 (권장)
chmod +x start.sh && ./start.sh
# 방식 2: 개별 실행
...

🖥️ 운영 환경 배포 (systemd)

# systemd 서비스 설치
sudo cp edict.service /etc/systemd/system/
sudo systemctl daemon-reload
...

💡 대시보드는 즉시 사용 가능합니다: server.py 내에 dashboard/dashboard.html이 내장되어 있으며, Docker 이미지에는 사전 빌드된 React 프론트엔드가 포함되어 있습니다.

💡 자세한 튜토리얼은 Getting Started 가이드를 참조하세요.

┌───────────────────────────────────┐
│ 👑 황제 (당신) │
│ Feishu · Telegram · Signal │
...

부서	Agent ID	직무	전문 분야
👑 태자	taizi	메시지 분류, 요구사항 정리	잡담 식별, 어명 추출, 제목 요약
📜 중서성	zhongshu	어명 수령, 계획, 세부 분해	요구사항 이해, 작업 분해, 방안 설계
🔍 문하성	menxia	심의, 검토, 봉박 (거부)	품질 검토, 리스크 식별, 표준 통제
📮 상서성	shangshu	배정, 조율, 취합	작업 스케줄링, 진행 추적, 결과 통합
💰 호부	hubu	데이터, 자원, 산출	데이터 처리, 보고서 생성, 비용 분석
📝 예부	libu	문서, 규격, 보고	기술 문서, API 문서, 규격 제정
⚔️ 병부	bingbu	코드, 알고리즘, 점검	기능 개발, 버그 수정, 코드 리뷰
⚖️ 형부	xingbu	보안, 컴플라이언스, 감사	보안 스캔, 컴플라이언스 체크, 레드라인 관리
🔧 공부	gongbu	CI/CD, 배포, 도구	Docker 설정, 파이프라인, 자동화
📋 이부	libu_hr	인사, Agent 관리	Agent 등록, 권한 유지보수, 교육
🌅 조참관	zaochao	매일 아침 조회, 뉴스 애그리게이션	정기 브리핑, 데이터 취합

원하는 대로 보낼 수 있는 것이 아닙 —— 진정한 권력 분립과 견제

From ↓ \ To →	태자	중서	문하	상서	호	예	병	형	공	리
태자		—	✅
중서성	✅	—	✅	✅
문하성	✅	—	✅
상서성	✅	✅	—	✅	✅	✅	✅	✅	✅
육부+리부	✅

황제 → 태자 분배 → 중서 계획 → 문하 심의 → 발송 완료 → 실행 중 → 검토 대기 → ✅ 완료
↑ │ │
└──── 봉박 ─┘ 차단 Blocked

⚡

상태 전환 보호: kanban_update.py

• 내장된 _VALID_TRANSITIONS:

  • 상태 머신 검증을 통해, 비정상적인 이동(예: Doing → Taizi)은 거부되고 로그가 기록되어 프로세스가 우회되는 것을 방지합니다. 🔄

• 비동기 이벤트 기반: 서비스 간 통신은 Redis Streams EventBus를 통해 느슨하게 결합(decouple)되며, Outbox Relay를 사용하여 이벤트의 신뢰성 있는 전송을 보장합니다. 모든 상태 변경은 감사 로그(audit.py)에 자동으로 기록되어 완전한 추적이 가능합니다.

edict/
├── agents/ # 12개 Agent의 페르소나 템플릿
│ ├── taizi/SOUL.md # 태자 · 메시지 분류 (지시(旨意) 제목 규격 포함)
...

Feishu / Telegram / Signal을 통해 중서성에 메시지를 보내기:

사용자 등록 시스템을 설계해 주세요. 요구사항은 다음과 같습니다:
1. RESTful API (FastAPI)
2. PostgreSQL 데이터베이스
...

그리고 앉아서 구경하세요:

• 📜 중서성이 지시를 받고, 하위 작업 분배 계획을 수립합니다.
• 🔍 문하성이 심의하고, 통과/봉박(封駁)으로 재계획을 요청하며 되돌립니다.
• 📮 상서성이 승인하여 병부 + 공부 + 예부에 할당합니다.
• ⚔️ 각 부서가 병렬로 실행하며, 진행 상황은 실시간으로 확인 가능합니다.
• 📮 상서성이 결과를 취합하여 보고(回奏)합니다.

전 과정은 군기처 칸반에서 실시간 모니터링할 수 있으며, 언제든지 중단, 취소, 복구가 가능합니다.

칸반 → 📜 지시고 → 템플릿 선택 → 매개변수 입력 → 하지(下旨)

9가지 사전 설정 템플릿:
주간 보고서 생성 · 코드 검토 · API 설계 · 경쟁사 분석 · 데이터 보고서 · 블로그 게시물 · 배포 계획 · 이메일 문안 · 회의록 요약

agents/<id>/SOUL.md를 편집하면 Agent의 페르소나, 책임, 출력 규격을 수정할 수 있습니다.

Skills 추가하는 세 가지 방법:

칸반 → 🔧 스킬 설정 → ➕ 원격 Skill 추가
→ Agent + Skill 이름 + GitHub URL 입력
→ 확인 → ✅ 완료

# GitHub에서 mmx_cli skill을 문하성에 추가
python3 scripts/skill_manager.py add-remote \
--agent menxia \
...

# 원격 skill 추가
curl -X POST http://localhost:7891/api/add-remote-skill \
-H

| 특징 | 설명 |
|---|---| 
| React 18 프론트엔드 | TypeScript + Vite + Zustand 상태 관리 (State Management), 13개의 기능 컴포넌트 |
| 순수 stdlib 백엔드 | `server.py`는 `http.server`를 기반으로 하며, 의존성(Dependency) 없이 API와 정적 파일 서비스를 동시에 제공 |
| EventBus 이벤트 버스 | Redis Streams 발행/구독 (Pub/Sub), 서비스 간 디커플링 (Decoupling) 통신 |
| Outbox Relay | 트랜잭션 Outbox 패턴을 통해 이벤트의 신뢰할 수 있는 전달 (At-least-once semantics) 보장 |
| 상태 머신 감사 (State Machine Audit) | 엄격한 생명주기 상태 전환 + 완전한 감사 로그 (`audit.py`) |
| 병렬 스케줄링 엔진 | Dispatch Worker는 병렬 실행, 지수 백오프 재시도 (Exponential Backoff Retry), 리소스 락 (Resource Lock) 지원 |
| DAG 오케스트레이터 | Orchestrator는 DAG 기반의 작업 분해 및 의존성 분석 수행 |
| Agent 사고 시각화 | Agent의 thinking 과정, 도구 호출 (Tool Call), 결과 반환을 실시간으로 전시 |
| 원클릭 설치 / 원클릭 실행 | `install.sh` 자동 설정, `start.sh` 명령 하나로 모든 서비스 실행 |
| systemd 프로덕션 배포 | `edict.service`는 systemd 데몬을 지원하여 부팅 시 자동 실행 |
| 15초 동기화 | 데이터 자동 새로고침, 대시보드 카운트다운 표시 |
| Dashboard 인증 | `auth.py`가 대시보드 로그인 인증 제공 |
| 데일리 의식 | 처음 실행 시 상조(朝) 개막 애니메이션 재생 |
| 원격 Skills 생태계 | GitHub/URL로부터 능력을 원클릭으로 가져오며, 버전 관리 + CLI + API + UI 지원 |

---

- **📖 작업 분배 흐름 전체 아키텍처 — 필독 문서**
  - 삼성육부(三省六部)가 복잡한 작업을 처리하는 비즈니스 설계와 기술적 구현을 상세히 설명
  - 포함 내용: 9대 작업 상태 머신 / 권한 매트릭스 / 4단계 스케줄링 (재시도 → 업그레이드 → 롤백) / Session JSONL 데이터 융합
  - 완전한 사용 사례, API 엔드포인트 설명, CLI 도구 문서 포함
  - CrewAI/AutoGen과 비교: 왜 제도화(Institutionalization)가 자유로운 협업보다 중요한가
  - 장애 시나리오 및 복구 메커니즘
  - **이 문서를 읽으면 삼성육부가 왜 강력한지 이해할 수 있습니다** (9,500자 이상, 30분 소요)

- **🎓 원격 Skills 리소스 관리 가이드 — Skills 생태계**
  - 인터넷에서 skills를 연결하고 추가, GitHub/Gitee/임의의 HTTPS URL 지원
  - 기본 Skills 소스 및 커스텀 Hub 지원
  - CLI 도구 + 대시보드 UI + Restful API
  - Skills 파일 규격 및 보안 방어
  - 버전 관리 및 원클릭 업데이트 지원

- **⚡ Remote Skills 빠른 시작 — 5분 만에 익히기**
  - 빠른 체험, CLI 명령어, 대시보드 조작 예시
  - 자신만의 Skills 라이브러리 생성
  - API 전체 참조 + FAQ

- **🚀 빠른 시작 가이드 — 초보자 입문**
- **🤝 기여 가이드 — 기여에 참여하고 싶다면? 여기서 시작하세요**

---

**❌ 작업 총 타임아웃 / 하급자가 완료했으나 태자(太子)에게 전달되지 않음**

**증상**: 육부(六部) 또는 상서성(尚書省)에서 작업을 완료했으나, 태자가 보고를 받지 못해 최종적으로 타임아웃 발생.

**점검 단계**:

**1. Agent 등록 상태 확인**:

`curl -s http://127.0.0.1:7891/api/agents-status | python3 -m json.tool`

`taizi` agent의 `statusLabel`이 `alive`인지 확인하십시오.

**2. Gateway 로그 확인**:

ls /tmp/openclaw/ | tail -5 # 최신 로그 찾기
grep -i "error|fail|unknown" /tmp/openclaw/openclaw-*.log | tail -20

- **주요 원인**:
  - Agent ID 불일치 (v1.2에서 `main` → `taizi`로 수정됨)
  - LLM provider 타임아웃 (자동 재시도 기능 추가됨)
  - 좀비 Agent 프로세스 (`ps aux | grep openclaw`로 확인)

**3. 강제 재시도**:

수동으로 점검 스캔 트리거 (자동 재시도가 멈춘 작업을 위해)

curl -X POST http://127.0.0.1:7891/api/scheduler-scan
-H 'Content-Type: application/json' -d '{"thresholdSec":60}'

**❌ Docker: exec format error**

**증상**: `exec /usr/local/bin/python3: exec format error`

**원인**: 이미지 아키텍처 (arm64)와 호스트 아키텍처 (amd64)가 일치하지 않음. 

**해결**: 

방법 1: 플랫폼 지정

docker run --platform linux/amd64 -p 7891:7891 cft0808/sansheng-demo

방법 2: docker-compose 사용 (platform 내장됨)

...

**❌ Skill 다운로드 실패**

**증상**: `python3 scripts/skill_manager.py import-official-hub` 에러 발생.

**점검**: 

네트워크 연결성 테스트

curl -I https://raw.githubusercontent.com/MiniMax-AI/cli/main/skill/SKILL.md

타임아웃 발생 시, 프록시 사용

...

**주요 원인**:

- 중국 본토에서 GitHub raw 리소스에 접속할 때 프록시 필요
- 네트워크 타임아웃 (30초로 증가 + 3회 자동 재시도 적용됨)
- 기본 skill 소스에 접속할 수 없거나, 커스텀 Skills Hub 설정 오류

전체 로드맵 및 참여 방법: ROADMAP.md

- 12부제 Agent 아키텍처 (태자 + 삼성 + 칠부 + 조침관) + 권한 매트릭스 (Permission Matrix)
- 군기처 실시간 대시보드 (10개 기능 패널 + 실시간 활동 패널)
- 작업 중단 / 취소 / 복구
- 상소(奏折) 시스템 (자동 아카이빙 + 5단계 타임라인)
- 성지(聖旨) 템플릿 라이브러리 (9개 프리셋 + 파라미터 양식)
- 조참(上朝) 의식 애니메이션
- 천하 요보(天下要闻) + Feishu 푸시 + 구독 관리
- 모델 핫 스위칭 (Hot Switching) + 스킬 관리 + 스킬 추가
- 관리자 개요 + Token 소모 통계
- 소규모 작업 / 세션 모니터링
- 태자 메시지 분류 (잡담 자동 응답 / 지시 사항 작업 생성)
- 지시 데이터 클리닝 (경로/메타데이터/접두사 자동 제거)
- 중복 작업 방지 + 완료된 작업 보호
- 엔드 투 엔드 (End-to-End) 테스트 커버리지 (17개 Assertion)
- React 18 프론트엔드 리팩토링 (TypeScript + Vite + Zustand · 13개 컴포넌트)
- Agent 사고 과정 시각화 (실시간 thinking / 도구 호출 / 결과 반환)
- 프론트엔드-백엔드 통합 배포 (server.py가 API + 정적 파일 서비스 동시 제공)

- 어비(御批) 모드 (수동 승인 + 원클릭 승인/봉박)
- 공과보 (Agent 성과 점수 + 모델 추천 + 비용 최적화)
- EventBus 이벤트 버스 (Redis Streams를 이용한 디커플링 통신)
- Outbox Relay (트랜잭션 이벤트 전달)
- 상태 머신 (State Machine) 감사 (엄격한 생명주기 + 감사 로그)
- 병렬 스케줄링 엔진 (지수 백오프 재시도 + 리소스 락)
- DAG 오케스트레이터 (작업 분해 + 의존성 분석)
- Dashboard 인증 (로그인 인증)
- 원클릭 실행 / systemd 프로덕션 배포
- 급전포 (Agent 간 실시간 메시지 흐름 시각화)
- 국사관 (지식 베이스 검색 + 인용 출처 추적)

- Docker Compose + Demo 이미지
- Notion / Linear 어댑터
- 연례 대고 (Agent 연간 성과 보고서)
- 모바일 최적화 + PWA
- ClawHub 등록

모든 형태의 기여를 환영합니다! 자세한 내용은 CONTRIBUTING.md를 참조하세요.

특별히 환영하는 분야:

- 🎨 **UI 강화**: 다크/라이트 테마, 반응형, 애니메이션 최적화
- 🤖 **신규 Agent**: 특정 시나리오에 적합한 전문 Agent 역할
- 📦 **Skills 생태계**: 각 부서 전용 스킬 팩
- 🔗 **통합 확장**: Notion · Jira · Linear · GitHub Issues
- 🌐 **국제화**: 일본어 · 한국어 · 스페인어
- 📱 **모바일**: 반응형 최적화, PWA

`examples/`

디렉토리에 실제 엔드 투 엔드 사용 사례가 수록되어 있습니다:

| 사례 | 지시(旨意) | 관련 부서 |
|---|---|---|
| 경쟁사 분석 | "CrewAI vs AutoGen vs LangGraph 분석" | 중서→문하→호부+병부+예부 |
| ... |
각 사례는 다음을 포함합니다: 전체 지시 → 중서성 계획 → 문하성 검토 의견 → 각 부서 실행 결과 → 최종 상소.

이 프로젝트가 즐거움을 주었다면, Star를 눌러주세요 ⚔️

옛날에는 디보(邸报)로 천하의 정령을 전했다면, 지금은 공식 계정으로 AI 아키텍처를 이야기합니다.

당신은 다음과 같은 것을 보게 될 것입니다:

- 🏛️
**아키텍처 해체 (Architecture Breakdown)** —— 삼성육부(三省六部)는 도대체 어떻게 권력을 분립하고 견제하는가? 12개의 에이전트(Agent)는 각각 어떤 직무를 수행하는가? - 🔥
**트러블슈팅 복기 (Pitfall Review)** —— 에이전트(Agent)끼리 싸우면 어떻게 해야 할까? 토큰(Token)이 다 타버렸을 때 아끼는 방법은? 문하성(门下省)은 왜 자꾸 봉박(封驳, 상소 거부)을 하는가? - 🛠️
**이슈(Issue) 수정 기록** —— 모든 버그(Bug)는 하나의 상소문이다, 짐이 어떻게 비홍(批红, 결재)을 내리는지 보라 - 💡
**토큰(Token) 절약술** —— 문하성(门下省)의 심사 효과를 1/10의 토큰(Token)으로 구현하는 비밀 - 🎭
**에이전트(Agent) 페르소나 이스터 에그** —— 육부(六部)의 SOUL.md는 어떻게 작성되었는가? 

"짐이 AI에게 조참(上朝)을 명했더니, AI가 짐보다 더 치열하게 일한다."
—— 팔로우하시면 이해하게 될 것입니다.

**⚔️ 고대의 지혜로 신기술을 제어하고, 지혜로 AI를 다스리다**

Governing AI with the wisdom of ancient empires