edict

⚔️ 三省六部 · Edict

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

12개의 AI Agent(11개 업무 역할 + 1개 호환 역할)가 삼성육부를 구성합니다: 태자 분류, 중서성 기획, 문하성 심의·봉박, 상서성 파견, 육부+이부 병렬 실행.
CrewAI보다 한 겹 더 많은 제도적 심의, AutoGen보다 하나 더 많은 실시간 대시보드.

🎬 Demo 보기 ·
🚀 30초 체험 ·
🏛️ 아키텍처 ·
📋 대시보드 기능 ·
📚 아키텍처 문서 ·
English ·
日本語 ·
기여하기

🎬 Demo

🎥 삼성육부 AI 멀티 Agent 협업 전체 프로세스 시연

📸 GIF 미리보기 (더 빠른 로딩)

Feishu로 칙명 하달 → 태자 분류 → 중서성 기획 → 문하성 심의 → 육부 병렬 실행 → 주절 보고 (30초)

🐳 OpenClaw가 없으신가요? docker run -p 7891:7891 cft0808/edict 한 줄이면 전체 대시보드 Demo를 체험할 수 있습니다(모의 데이터 사전 탑재).

🤔 왜 삼성육부인가?
대부분의 Multi-Agent 프레임워크의 방식은:

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

그러면 어떤 처리를 거쳤는지 알 수 없는 결과물을 받게 되고, 재현도, 감사도, 개입도 불가능합니다.

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

당신 (황제) → 태자 (분류) → 중서성 (기획) → 문하성 (심의) → 상서성 (파견) → 육부 (실행) → 회주

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

CrewAI
MetaGPT
AutoGen
삼성육부

심의 메커니즘
❌ 없음
⚠️ 선택
⚠️ Human-in-loop
✅ 문하성 전담 심의 · 봉박 가능

실시간 대시보드
❌
❌
❌
✅ 군기처 Kanban + 타임라인

작업 개입
❌
❌
❌
✅ 중단 / 취소 / 복구

흐름 감사
⚠️
⚠️
❌
✅ 완전한 주절 아카이브

Agent 상태 모니터링
❌
❌
❌
✅ 하트비트 + 활성도 감지

모델 핫스왑
❌
❌
❌
✅ 대시보드 내 원클릭 LLM 전환

스킬 관리
❌
❌
❌
✅ Skills 조회 / 추가

뉴스 집계 푸시
❌
❌
❌
✅ 천하요문 + Feishu 푸시

배포 난이도
중
고
중
저 · 원클릭 설치 / Docker

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

🔍 왜 「문하성 심의」가 킬러 기능인가? (클릭하여 펼치기)

CrewAI와 AutoGen의 Agent 협업 모델은 "끝나면 바로 제출" — 산출물 품질을 검사하는 사람이 없습니다. QA 부서가 없는 회사에서 엔지니어가 코드를 작성하자마자 바로 배포하는 것과 같습니다.

삼성육부의 문하성은 바로 이 일을 전담합니다:

📋 방안 품질 심사 — 중서성의 기획이 완전한가? 하위 작업 분해가 합리적인가?
🚫 불합격 산출물 봉박 — warning이 아니라, 바로 반려 후 재작업
🔄 강제 재작업 루프 — 방안이 기준을 충족할 때까지 통과 불가

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

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

✨ 기능 개요
🏛️ 십이부제 Agent 아키텍처

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

📋 군기처 대시보드 (10개 기능 패널)

📋 칙명 대시보드 · Kanban

상태 열별 전체 작업 표시
성부 필터 + 전문 검색
하트비트 배지 (🟢활성 🟡정체 🔴경고)
작업 상세 + 전체 흐름 체인
중단 / 취소 / 복구 조작

🔭 성부 스케줄 · Monitor

상태별 작업 수 시각화
부서 분포 가로 막대 차트
Agent 상태 실시간 카드

📜 주절각 · Memorials

완료된 칙명 자동 아카이브를 주절로
5단계 타임라인: 성지→중서→문하→육부→회주
원클릭 Markdown 복사
상태별 필터

📜 지고 · Template Library

9개 사전 설정 성지 템플릿
분류 필터 · 파라미터 폼 · 예상 시간 및 비용
칙명 미리보기 → 원클릭 하달

👥 관원 총람 · Officials

Token 소비 랭킹
활성도 · 완료 수 · 세션 통계

📰 천하요문 · News

매일 자동 수집되는 기술/금융 뉴스
분류 구독 관리 + Feishu 푸시

⚙️ 모델 설정 · Models

각 Agent별 독립 LLM 전환
적용 후 Gateway 자동 재시작 (~5초 반영)

🛠️ 스킬 설정 · Skills

각 성부에 설치된 Skills 일람
상세 조회 + 신규 스킬 추가

💬 소작업 · Sessions

OC-* 세션 실시간 모니터링
유입 채널 · 하트비트 · 메시지 미리보기

🎬 조회 의식 · Ceremony

매일 첫 접속 시 오프닝 애니메이션 재생
오늘의 통계 · 3.5초 후 자동 사라짐

🏛️ 조당 의정 · Court Discussion

여러 관원이 안건을 두고 부서 관점 토론 전개
LLM 기반 다역할 토론 (각 부가 직책에 따라 전문 의견 발표)
다회차 진행 · 결론 요약 · 토론 기록 보존 지원

🖼️ 스크린샷
칙명 대시보드

📸 더 많은 스크린샷 펼치기
성부 스케줄

작업 흐름 상세

모델 설정

스킬 설정

관원 총람

세션 기록

주절 아카이브

성지 템플릿

천하요문

조회 의식

🚀 30초 빠른 체험
Docker 원클릭 시작
docker run -p 7891:7891 cft0808/sansheng-demo
http://localhost:7891 을 열면 군기처 대시보드를 체험할 수 있습니다.

⚠️ 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 , 메시지 도달 불가 문제 해결)
✅ API Key를 모든 Agent에 동기화 (설정된 Agent에서 자동 복사)
✅ React 프론트엔드 빌드 (Node.js 18+ 필요, 미설치 시 건너뜀)
✅ 데이터 디렉토리 초기화 + 최초 데이터 동기화 (관원 통계 포함)
✅ Gateway 재시작으로 설정 반영

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

시작
# 방식 1: 원클릭 시작 (권장)
chmod +x start.sh && ./start.sh

# 방식 2: 개별 시작
bash scripts/run_loop.sh & # 데이터 갱신 루프
python3 dashboard/server.py # 대시보드 서버

# 브라우저 열기
open http://127.0.0.1:7891

🖥️ 프로덕션 환경 배포 (systemd)
# systemd 서비스 설치
sudo cp edict.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable edict
sudo systemctl start edict

# 또는 관리 스크립트 사용
bash edict.sh start # 시작
bash edict.sh status # 상태 확인
bash edict.sh restart # 재시작
bash edict.sh stop # 중지

💡 대시보드 즉시 사용 가능 : server.py에 dashboard/dashboard.html 내장, Docker 이미지에 사전 빌드된 React 프론트엔드 포함

💡 상세 튜토리얼은 Getting Started 가이드를 참고하세요

🏛️ 아키텍처
┌───────────────────────────────────┐
│ 👑 황제 (당신) │
│ Feishu · Telegram · Signal │
└─────────────────┬─────────────────┘
│ 하달
┌─────────────────▼─────────────────┐
│ � 태자 (taizi) │
│ 분류: 잡담은 직접 응답 / 칙명은 작업 생성 │
└─────────────────┬─────────────────┘
│ 전지
┌─────────────────▼─────────────────┐
│ 📜 중서성 (zhongshu) │
│ 접지 → 기획 → 하위 작업 분해 │
└─────────────────┬─────────────────┘
│ 심의 제출
┌─────────────────▼─────────────────┐
│ 🔍 문하성 (menxia) │
│ 방안 심의 → 준주 / 봉박 🚫 │
└─────────────────┬─────────────────┘
│ 준주 ✅
┌─────────────────▼─────────────────┐
│ 📮 상서성 (shangshu) │
│ 작업 파견 → 육부 조율 → 결과 종합 회주 │
└───┬──────┬──────┬──────┬──────┬───┘
│ │ │ │ │
┌─────▼┐ ┌───▼───┐ ┌▼─────┐ ┌───▼─┐ ┌▼─────┐
│💰 호부│ │📝 예부│ │⚔️ 병부│ │⚖️ 형부│ │🔧 공부│
│ 데이터 │ │ 문서 │ │ 엔지니어링 │ │ 컴플라이언스 │ │ 인프라 │
└──────┘ └──────┘ └──────┘ └─────┘ └──────┘
┌──────┐
│📋 이부│
│ 인사 │
└──────┘

각 성부 직책

부서
Agent ID
직책
전문 분야

� 태자
taizi
메시지 분류, 요구 정리
잡담 식별, 칙명 정제, 제목 요약

📜 중서성
zhongshu
접지, 기획, 분해
요구 이해, 작업 분해, 방안 설계

🔍 문하성
menxia
심의, 검증, 봉박
품질 심사, 리스크 식별, 기준 관리

📮 상서성
shangshu
파견, 조율, 종합
작업 스케줄링, 진행 추적, 결과 통합

💰 호부
hubu
데이터, 리소스, 회계
데이터 처리, 보고서 생성, 비용 분석

📝 예부
libu
문서, 규범, 보고서
기술 문서, API 문서, 규범 제정

⚔️ 병부
bingbu
코드, 알고리즘, 점검
기능 개발, Bug 수정, 코드 리뷰

⚖️ 형부
xingbu
보안, 컴플라이언스, 감사
보안 스캔, 컴플라이언스 점검, 레드라인 관리

🔧 공부
gongbu
CI/CD, 배포, 도구
Docker 설정, 파이프라인, 자동화

📋 이부
libu_hr
인사, Agent 관리
Agent 등록, 권한 유지, 교육

🌅 조조회관
zaochao
매일 조회, 뉴스 집계
정기 방송, 데이터 종합

권한 매트릭스

마음대로 보낼 수 없다 — 진정한 분권과 견제

From ↓ \ To →
태자
중서
문하
상서
호
예
병
형
공
이

태자
—
✅

중서성
✅
—
✅
✅

문하성

✅
—
✅

상서성

✅
✅
—
✅
✅
✅
✅
✅
✅

육부+이부

✅

작업 상태 전이
황제 → 태자 분류 → 중서 기획 → 문하 심의 → 파견됨 → 실행 중 → 심사 대기 → ✅ 완료
↑ │ │
└──── 봉박 ─┘ 차단 Blocked

⚡ 상태 전이 보호 : kanban_update.py에 _VALID_TRANSITIONS 상태 머신 검증 내장,
불법 점프(예: Doing→Taizi)는 거부되고 로그에 기록되어 프로세스 우회 불가.

🔄 비동기 이벤트 기반 : 서비스 간 Redis Streams EventBus로 통신을 분리, Outbox Relay가 이벤트의 신뢰성 있는 전달 보장.
모든 상태 변경은 감사 로그( audit.py )에 자동 기록되어 완전한 추적 지원.

📁 프로젝트 구조
edict/
├── agents/ # 12개 Agent 인격 템플릿
│ ├── taizi/SOUL.md # 태자 · 메시지 분류 (칙명 제목 규범 포함)
│ ├── zhongshu/SOUL.md # 중서성 · 기획 중추
│ ├── menxia/SOUL.md # 문하성 · 심의 검증
│ ├── shangshu/SOUL.md # 상서성 · 스케줄링 두뇌
│ ├── hubu/SOUL.md # 호부 · 데이터 리소스
│ ├── libu/SOUL.md # 예부 · 문서 규범
│ ├── bingbu/SOUL.md # 병부 · 엔지니어링 구현
│ ├── xingbu/SOUL.md # 형부 · 컴플라이언스 감사
│ ├── gongbu/SOUL.md # 공부 · 인프라
│ ├── libu_hr/ # 이부 · 인사 관리
│ └── zaochao/SOUL.md # 조조회관 · 정보 허브
├── dashboard/
│ ├── dashboard.html # 군기처 대시보드 (단일 파일 · 제로 의존성 · ~2500줄)
│ ├── dist/ # React 프론트엔드 빌드 산출물 (Docker 이미지 내 포함, 로컬 선택)
│ ├── auth.py # Dashboard 로그인 인증
│ ├── court_discuss.py # 조당 의정 (다관원 LLM 토론 엔진)
│ └── server.py # API 서버 (Python 표준 라이브러리 · 제로 의존성 · ~2300줄)
├── edict/backend/ # 비동기 백엔드 서비스 (SQLAlchemy + Redis)
│ ├── app/models/
│ │ ├── task.py # 작업 모델 + 상태 머신
│ │ ├── audit.py # 감사 로그 모델
│ │ └── outbox.py # Outbox 메시지 모델
│ ├── app/services/
│ │ ├── event_bus.py # Redis Streams EventBus
│ │ └── task_service.py # 작업 서비스 계층
│ └── app/workers/
│ ├── dispatch_worker.py # 병렬 스케줄링 + 재시도 + 리소스 락
│ ├── orchestrator_worker.py # DAG 오케스트레이터
│ └── outbox_relay.py # 트랜잭션 Outbox Relay
├── agents/
│ ├── <agent_id>/SOUL.md # 각 성부 Agent 인격 템플릿
│ ├── GLOBAL.md # 전역 Agent 설정
│ └── groups/ # Agent 그룹 (sansheng / liubu)
├── scripts/
│ ├── run_loop.sh # 데이터 갱신 루프 (15초마다)
│ ├── kanban_update.py # 대시보드 CLI (칙명 데이터 정제 + 제목 검증 + 상태 머신)
│ ├── skill_manager.py # Skill 관리 도구 (원격/로컬 Skills 추가, 업데이트, 제거)
│ ├── agentrec_advisor.py # Agent 모델 추천 (공과부 + 비용 최적화)
│ ├── linucb_router.py # LinUCB 지능형 라우팅
│ ├── refresh_watcher.py # 데이터 변경 감시
│ ├── sync_from_openclaw_runtime.py
│ ├── sync_agent_config.py
│ ├── sync_officials_stats.py
│ ├── fetch_morning_news.py
│ ├── refresh_live_data.py
│ ├── apply_model_changes.py
│ └── file_lock.py # 파일 락 (다중 Agent 동시 쓰기 방지)
├── tests/
│ ├── test_e2e_kanban.py # 엔드투엔드 테스트 (17개 어서션)
│ └── test_state_machine_consistency.py # 상태 머신 일관성 테스트
├── data/ # 런타임 데이터 (gitignored)
├── docs/
│ ├── task-dispatch-architecture.md # 📚 상세 아키텍처 문서: 작업 분배, 흐름, 스케줄링의 완전한 설계 (비즈니스+기술)
│ ├── getting-started.md # 빠른 시작 가이드
│ ├── wechat-article.md # 위챗 아티클
│ └── screenshots/ # 기능 스크린샷 (11장)
├── install.sh # 원클릭 설치 스크립트
├── start.sh # 원클릭 시작 (Dashboard + 데이터 갱신)
├── edict.service # systemd 서비스 설정 (프로덕션 배포)
├── edict.sh # 서비스 관리 스크립트 (start/stop/restart/status)
├── CONTRIBUTING.md # 기여 가이드
└── LICENSE # MIT License

🎯 사용 방법
AI에게 칙명 하달
Feishu / Telegram / Signal을 통해 중서성에 메시지 전송:

사용자 등록 시스템을 설계해줘, 요구사항:
1. RESTful API (FastAPI)
2. PostgreSQL 데이터베이스
3. JWT 인증
4. 완전한 테스트 케이스
5. 배포 문서

그런 다음 편하게 앉아서 구경하세요:

📜 중서성 접지, 하위 작업 분배 방안 기획
🔍 문하성 심의, 통과 / 봉박 반려 후 재기획
📮 상서성 준주, 병부 + 공부 + 예부에 파견
⚔️ 각 부 병렬 실행, 진행 상황 실시간 확인
📮 상서성 결과 종합, 당신에게 회주

전 과정을 군기처 대시보드 에서 실시간 모니터링 가능하며, 언제든 중단, 취소, 복구 할 수 있습니다.

성지 템플릿 사용

대시보드 → 📜 지고 → 템플릿 선택 → 파라미터 입력 → 하달

9개 사전 설정 템플릿: 주간 보고서 생성 · 코드 리뷰 · API 설계 · 경쟁사 분석 · 데이터 보고서 · 블로그 글 · 배포 방안 · 이메일 문안 · 스탠드업 요약

커스텀 Agent
agents/<id>/SOUL.md 를 편집하면 Agent의 인격, 직책, 출력 규범을 수정할 수 있습니다.

Skills 증보 (인터넷에서 연결)
Skills를 추가하는 세 가지 방법:

1️⃣ 대시보드 UI (가장 간단)
대시보드 → 🔧 스킬 설정 → ➕ 원격 Skill 추가
→ Agent + Skill 이름 + GitHub URL 입력
→ 확인 → ✅ 완료

2️⃣ CLI 명령 (가장 유연)
# GitHub에서 mmx_cli skill을 문하성에 추가
python3 scripts/skill_manager.py add-remote \
--agent menxia \
--name mmx_cli \
--source https://raw.githubusercontent.com/MiniMax-AI/cli/main/skill/SKILL.md \
--description " MiniMax 멀티모달 CLI 스킬 "

# 기본 skills를 지정 agents에 원클릭 임포트
python3 scripts/skill_manager.py import-official-hub \
--agents menxia,shangshu

# 추가된 모든 원격 skills 나열
python3 scripts/skill_manager.py list-remote

# 특정 skill을 최신 버전으로 업데이트
python3 scripts/skill_manager.py update-remote \
--agent menxia \
--name mmx_cli
3️⃣ API 요청 (자동화 통합)
# 원격 skill 추가
curl -X POST http://localhost:7891/api/add-remote-skill \
-H " Content-Type: application/json " \
-d ' {
"agentId": "menxia",
"skillName": "mmx_cli",
"sourceUrl": "https://raw.githubusercontent.com/MiniMax-AI/cli/main/skill/SKILL.md",
"description": "MiniMax 멀티모달 CLI 스킬"
} '

# 모든 원격 skills 조회
curl http://localhost:7891/api/remote-skills-list
기본 임포트 가능 Skill:

지원 Skills:

mmx_cli — MiniMax 멀티모달 CLI 스킬 (텍스트, 이미지, 비디오, 음성, 음악, 검색)

자체 Skills Hub가 있다면 OPENCLAW_SKILLS_HUB_BASE 또는 ~/.openclaw/skills-hub-url 로 커스텀 소스를 설정할 수 있습니다.

자세한 내용은 🎓 원격 Skills 리소스 관리 가이드 참고

🔧 기술 하이라이트

특징
설명

React 18 프론트엔드
TypeScript + Vite + Zustand 상태 관리, 13개 기능 컴포넌트

순수 stdlib 백엔드
server.py는 http.server 기반, 제로 의존성, API + 정적 파일 서비스 동시 제공

EventBus 이벤트 버스
Redis Streams 발행/구독, 서비스 간 분리 통신

Outbox Relay
트랜잭션 Outbox 패턴, 이벤트 신뢰성 있는 전달 보장 (최소 1회 시맨틱)

상태 머신 감사
엄격한 라이프사이클 상태 전이 + 완전한 감사 로그 ( audit.py )

병렬 스케줄링 엔진
Dispatch Worker가 병렬 실행, 지수 백오프 재시도, 리소스 락 지원

DAG 오케스트레이터
Orchestrator가 DAG 기반 작업 분해 및 의존성 해석

Agent 사고 시각화
Agent의 thinking 과정, 도구 호출, 반환 결과 실시간 표시

원클릭 설치 / 원클릭 시작
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 대비: 왜 제도화 > 자유 협업인가
장애 시나리오와 복구 메커니즘
이 문서를 읽으면 삼성육부가 왜 이렇게 강력한지 이해하게 됩니다 (9500+ 자, 30분 완전 이해)

🎓 원격 Skills 리소스 관리 가이드 — Skills 생태계

인터넷에서 skills 연결 및 증보, GitHub/Gitee/임의 HTTPS URL 지원
기본 Skills 소스 및 커스텀 Hub 지원
CLI 도구 + 대시보드 UI + Restful API
Skills 파일 규범 및 보안 보호
버전 관리 및 원클릭 업데이트 지원

⚡ Remote Skills 빠른 시작 — 5분 입문

빠른 체험, CLI 명령, 대시보드 조작 예시
자체 Skills 라이브러리 생성
API 완전 참조 + 자주 묻는 질문

🚀 빠른 시작 가이드 — 초보자 입문

🤝 기여 가이드 — 기여하고 싶으신가요? 여기서 시작하세요

🔧 자주 묻는 문제 해결

❌ 작업이 계속 타임아웃 / 하위 부서는 완료했지만 태자에게 전달 불가
증상 : 육부 또는 상서성이 작업을 완료했지만 태자가 보고를 받지 못해 결국 타임아웃.

점검 단계 :

Agent 등록 상태 확인 :

curl -s http://127.0.0.1:7891/api/agents-status | python3 -m json.tool
taizi agent의 statusLabel이 alive 인지 확인.

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 실행하여 확인)

강제 재시도 :

# 수동 점검 스캔 트리거 (멈춘 작업 자동 재시도)
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 내장)
docker compose up

❌ Skill 다운로드 실패
증상 : python3 scripts/skill_manager.py import-official-hub 오류 발생.

점검 :

# 네트워크 연결 테스트
curl -I https://raw.githubusercontent.com/MiniMax-AI/cli/main/skill/SKILL.md

# 타임아웃 시 프록시 사용
export https_proxy=http://your-proxy:port
python3 scripts/skill_manager.py import-offic…