OpenMOSS 시작하기: 멀티 에이전트 협업으로 AI를 24시간 가동되는 기업 팀으로 만들기

난이도: 입문 | 소요 시간: 30분 | 얻는 것: OpenMOSS 4인 역할 협업 체계 이해 및 나만의 AI 회사 팀 구축

---

대상 독자

이미 OpenClaw를 사용하며 채팅, 코드 작성, 작업 수행 등 단일 에이전트의 능력을 경험해 보셨을 겁니다. 하지만 작업이 복잡해지거나 여러 단계의 협업이 필요할 때, 단일 에이전트는 특정 단계에서 멈춰버리고 사용자가 재촉할 때까지 그 상태로 머물러 있는 한계를 발견하셨을 것입니다.

OpenMOSS는 바로 이 문제를 해결하고자 합니다. 개념은 간단합니다. 에이전트 한 명에게 모든 일을 맡기지 말고, AI에게 조직 구조를 입히는 것입니다. 기획자(Planner)는 요구사항을 분해하고, 실행자(Executor)는 실무를 수행하며, 검토자(Reviewer)는 품질을 관리하고, 순찰자(Patrol)는 감시를 담당합니다. 이 네 가지 역할이 각자의 임무를 다하며 타이머 기반의 자율 운용을 통해 선순환하는 AI 회사 팀을 형성합니다.

OpenMOSS 자체는 미들웨어로서 구체적인 비즈니스 로직에는 관여하지 않고 스케줄링과 협업만 관리합니다. 어떤 스킬(Skill)을 설정해주느냐에 따라 자동으로 협업하여 작업을 완수합니다.

이 글은 다음과 같은 분들에게 적합합니다:

• 이미 OpenClaw를 사용 중이며 멀티 에이전트 협업을 경험하고 싶은 분
• 사람의 개입 없이 AI가 자동으로 지속 운용되기를 원하는 분
• 콘텐츠 생산 파이프라인, 자동화 운영, 코드 리뷰 등의 워크플로우를 구축하고 싶은 분

---

핵심 의존성 및 환경

GitHub 저장소: https://github.com/uluckyXH/OpenMOSS

---

전체 프로젝트 구조

OpenMOSS/
├── app/                          # FastAPI 백엔드
│   ├── main.py                   # 엔트리 포인트: 라우트 등록, 미들웨어, SPA 정적 서비스
│   ├── config.py                 # 설정 로드
│   ├── database.py               # 데이터베이스 초기화 (SQLAlchemy)
│   ├── models/                  # 데이터 모델 (10개 테이블)
│   ├── routers/                 # API 라우트
│   ├── services/                # 비즈니스 로직 계층
│   └── schemas/                 # Pydantic 직렬화 모델
├── webui/                        # Vue 3 프론트엔드 소스 (빌드 필요)
├── static/                       # 프론트엔드 빌드 결과물 (백엔드에서 직접 서비스)
├── prompts/                      # 에이전트 역할 프롬프트 템플릿
│   ├── templates/                # 역할 기본 템플릿
│   ├── agents/                   # 에이전트 프롬프트 예시
│   └── tool/                    # 도구 호출 프롬프트
├── skills/                        # OpenClaw 에이전트 스킬 정의
│   ├── task-cli.py              # 각 스킬 공용 API 호출 스크립트
│   ├── task-planner-skill/      # 기획자 스킬
│   ├── task-executor-skill/      # 실행자 스킬
│   ├── task-reviewer-skill/     # 검토자 스킬
│   ├── task-patrol-skill/       # 순찰자 스킬
│   └── dist/                    # 패키징된 스킬 .zip 파일
├── config.example.yaml            # 설정 파일 템플릿
├── requirements.txt              # Python 의존성
├── Dockerfile
└── docker-compose.yml

---

단계별 가이드

Step 1: 프로젝트 클론 및 의존성 설치

# 프로젝트 클론
git clone https://github.com/uluckyXH/OpenMOSS.git openmoss
cd openmoss

# Python 의존성 설치
pip install -r requirements.txt

저장소에 static/ 디렉토리가 없다면(프론트엔드 미빌드 상태), 프론트엔드를 빌드해야 합니다:

cd webui
npm install
npm run build

# 빌드 결과물을 static/ 디렉토리로 복사
rm -rf ../static/*
cp -r dist/* ../static/
cd ..

---

Step 2: config.yaml 설정

처음 실행 시 OpenMOSS는 config.example.yaml로부터 config.yaml을 자동으로 생성합니다. 템플릿을 직접 복사하여 수정하는 것을 권장합니다:

cp config.example.yaml config.yaml

그 후 config.yaml을 편집하여 다음 필드들을 반드시 설정하십시오:

# 관리자 비밀번호 (처음 실행 후 자동 암호화됨)
admin:
  password: "your-secure-password-here"

# 에이전트 등록 토큰 (에이전트 등록 시 필요, 무작위 생성 권장)
agent:
  registration_token: "your-random-token-here"
  allow_registration: true

# 작업 디렉토리 (에이전트 산출물 저장 위치)
workspace:
  root: "/home/your-user/TaskWork"

# 서비스 외부 접속 주소 (에이전트가 접속 시 필요한 주소)
server:
  external_url: "http://your-server-ip:6565"

---

Step 3: 서비스 시작 및 초기화 가이드 완료

python -m uvicorn app.main:app --host 0.0.0.0 --port 6565

처음 실행하면 다음 작업이 자동으로 수행됩니다:

1. config.yaml 생성 (없는 경우)
2. SQLite 데이터베이스 초기화 (data/tasks.db)
3. 프론트엔드 자동 마운트 (static/ 디렉토리가 존재하는 경우)

브라우저에서 http://localhost:6565에 접속하면 초기화 가이드로 리다이렉트되어 다음 설정을 안내합니다:

• 관리자 비밀번호 설정
• 프로젝트 이름 설정
• 에이전트 등록 토큰 생성
• (선택 사항) 알림 채널 설정

완료 후 표시되는 서비스 주소는 다음과 같습니다:

---

Step 4: WebUI 로그인 및 관리자 대시보드 확인

초기화가 끝나면 관리자 계정으로 WebUI에 로그인합니다. 다음 페이지들을 확인할 수 있습니다:

처음에는 에이전트 목록이 비어 있습니다. 아직 에이전트를 등록하지 않았기 때문입니다. Step 5에서 등록을 시작합니다.

---

Step 5: 4가지 에이전트 생성 및 OpenClaw 등록

OpenMOSS의 네 가지 역할은 각기 다른 책임을 가집니다:

각 에이전트는 본질적으로 OpenClaw를 실행하는 인스턴스입니다. 기획자(Planner)를 예로 들어 설명하며, 나머지 세 역할도 프로세스는 동일합니다.

방법 1: WebUI를 통한 등록 (권장)

1. WebUI의 에이전트 페이지에서 「에이전트 등록」 클릭
2. 기본 정보 입력:

역할: planner
이름: OpenMOSS-Planner
등록 토큰: (config.yaml에 설정한 agent.registration_token 입력)

1. 제출하면 WebUI가 다음 정보를 반환합니다:
   • 에이전트용 API Key (보안상 한 번만 표시되므로 잘 보관하세요)
   • 에이전트용 SKILL.md 및 task-cli.py 다운로드 주소
   • 연동 가이드 (등록 명령어, 설정 방법 포함)

방법 2: API를 통한 등록

curl -X POST http://localhost:6565/api/agents/register \
  -H "X-Registration-Token: your-registration-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenMOSS-Planner",
    "role": "planner"
  }'

반환된 내용에는 API Key, 등록 명령어, 스킬 다운로드 주소가 포함됩니다:

{
  "api_key": "om_xxxxxxxxxxxxxxxxxxxx",
  "skill_cli_url": "http://localhost:6565/skills/task-cli.py",
  "skill_url": "http://localhost:6565/skills/task-planner-skill/SKILL.md",
  "register_command": "openclaw agents add ..."
}

나머지 세 에이전트도 같은 방식으로 등록하십시오:

executor → task-executor-skill
reviewer → task-reviewer-skill
patrol   → task-patrol-skill

---

Step 6: 에이전트 스킬 설정

에이전트 등록에 성공하면 두 가지 핵심 파일을 얻게 됩니다:

• task-cli.py — 모든 역할이 공통으로 사용하는 OpenMOSS API 호출 스크립트
• SKILL.md — 해당 역할의 전용 스킬 정의

이 파일들을 OpenClaw가 읽을 수 있는 디렉토리(보통 에이전트의 프롬프트와 같은 위치)에 배치합니다:

# OpenClaw 에이전트 설정 디렉토리 가정
mkdir -p ~/.openclaw/agents/openmoss-planner/skills

# 스킬 파일 다운로드
curl -o ~/.openclaw/agents/openmoss-planner/skills/task-cli.py \
  http://localhost:6565/skills/task-cli.py

curl -o ~/.openclaw/agents/openmoss-planner/skills/SKILL.md \
  http://localhost:6565/skills/task-planner-skill/SKILL.md

그 다음 OpenClaw의 에이전트 설정에서 SKILL.md의 경로를 에이전트의 프롬프트나 스킬 설정에 추가하여, 에이전트가 OpenMOSS의 어떤 API를 호출할 수 있는지 알게 합니다.

---

Step 7: cron 예약 실행 설정으로 에이전트를 자동으로 "출근"시키기

이것이 OpenMOSS와 일반 단일 에이전트의 가장 큰 차이점입니다: 에이전트는 사용자의 메시지를 기다리는 것이 아니라, 직원처럼 정해진 시간에 출근하여 업무를 시작합니다.

OpenClaw의 에이전트 설정에서 각 에이전트의 cron 작업을 설정하십시오:

planner(기획자) — 30분마다 새 작업 확인:

{
  "cron": "*/30 * * * *",
  "task": "OpenMOSS 작업 대기열을 확인하고 기획되지 않은 새 작업이 있으면 기획 프로세스 실행"
}

executor(실행자) — 15분마다 수락 대기 중인 작업 확인:

{
  "cron": "*/15 * * * *",
  "task": "OpenMOSS 하위 작업 대기열을 확인하여 작업을 수락하고 실행"
}

reviewer(검토자) — 20분마다 검토 대기 결과물 확인:

{
  "cron": "*/20 * * * *",
  "task": "OpenMOSS 검토 대기열을 확인하여 제출된 결과물 처리"
}

patrol(순찰자) — 10분마다 시스템 상태 점검:

{
  "cron": "*/10 * * * *",
  "task": "OpenMOSS 시스템 상태를 확인하고 정체된 작업을 표시하며 이상 발견 시 즉시 경고"
}

에이전트가 활성화된 후의 업무 흐름은 고정되어 있습니다:

1. OpenMOSS API를 호출하여 현재 상태 조회
2. 자신의 역할에 맞는 작업 수행
3. 결과를 OpenMOSS에 다시 기록
4. 절전 모드로 진입하여 다음 활성화 대기

이 모든 과정에 사람의 개입은 전혀 필요하지 않습니다.

---

Step 8: 첫 번째 작업 지시 및 4인 협업 선순환 검증

WebUI의 「작업 관리」 페이지에서 「작업 생성」을 클릭하고 다음과 같이 입력합니다:

작업 명칭: AI 정보 자동 번역 및 게시
목표: 중국어 인터넷의 AI/기술/디지털 정보를 수집하여 영어로 번역한 후 게시

기획자(planner)가 cron에 의해 활성화되면:

1. 작업을 접수하고 여러 모듈(수집 → 번역 → 검토 → 게시)로 분해합니다.
2. 각 모듈별 하위 작업(sub-task)을 생성합니다.
3. 각 하위 작업의 검수 기준을 정의합니다.

실행자(executor)가 활성화되면:

1. 대기열에서 첫 번째 하위 작업을 수락합니다.
2. 실무를 수행(정보 검색 및 번역)합니다.
3. 결과물을 검토 대기열에 제출합니다.

검토자(reviewer)가 활성화되면:

1. 검토 대기 중인 결과물을 가져옵니다.
2. 검수 기준에 따라 점수를 매깁니다.
3. 통과 시 하위 작업을 완료로 표시하고, 반려 시 실행자에게 재작업을 지시합니다.

순찰자(patrol)는 지속적으로 시스템을 모니터링합니다:

• 특정 하위 작업이 일정 시간 동안 진척이 없으면 자동으로 blocked 표시
• 검토 반려율이 비정상적으로 높으면 경고 알림 전송
• 실행자가 무한 루프에 빠진 것을 발견하면 관리자에게 개입 요청

WebUI의 「활동 스트림」 페이지에서 모든 에이전트의 실시간 작업 동향을 언제든지 확인할 수 있습니다.

---

Step 9: 알림 채널 설정

OpenMOSS는 주요 사건 발생 시 자동으로 알림을 보낼 수 있습니다. config.yaml에서 알림 채널을 설정하세요:

notification:
  enabled: true
  channels:
    - "Feishu_Group_ID"    # 에이전트를 그룹에 초대하고 멘션하여 chat_id 획득 필요
    - "user:ou_xxx"       # 사용자 open_id
  events:
    - task_completed       # 하위 작업 완료
    - review_rejected      # 검토 반려 (재작업)
    - all_done             # 모든 하위 작업 완료
    - patrol_alert          # 순찰 중 이상 발견

에이전트는 GET /config/notification 인터페이스를 통해 알림 설정을 읽어온 뒤, 자신의 능력(이메일, 메신저 등)을 사용하여 알림을 전송합니다.

---

자주 발생하는 문제 해결(FAQ)

1. 에이전트 등록 실패 (registration_token 불일치)

증상: 에이전트 등록 시 403 오류 또는 "invalid token" 오류 발생.

원인: 대부분 registration_token이 일치하지 않기 때문입니다. 다음 두 가지를 확인하세요:

1. OpenMOSS config.yaml 내의 agent.registration_token 값
2. 에이전트 등록 요청 헤더의 X-Registration-Token 값

공백과 대소문자를 포함하여 완전히 일치해야 합니다. config.yaml을 수정했다면 OpenMOSS 서비스를 재시작해야 합니다.

---

2. cron 작업이 에이전트를 깨우지 않음

증상: 에이전트가 자동으로 작업을 시작하지 않고 콘솔에 오류 로그도 남지 않음.

점검 순서:

1. OpenClaw 측의 cron 설정 확인 — cron 표현식이 올바른지, 작업 설명이 명확한지 확인
2. OpenClaw 인스턴스 실행 여부 확인 — 에이전트에 대응하는 OpenClaw 프로세스가 살아 있는지 확인
3. 에이전트 API Key 유효성 확인 — WebUI 에이전트 페이지에서 상태가 active인지 확인

WebUI의 「에이전트」 페이지에서 특정 에이전트의 마지막 활동 시간을 확인하여 주기적으로 활성화되고 있는지 판단할 수 있습니다.

---

3. 하위 작업이 반복적으로 반려되어 무한 루프에 빠짐

증상: 실행자(executor)가 제출한 결과물이 계속 반려되어 같은 작업이 반복됨.

원인: 보통 실행자가 검수 기준을 잘못 이해했거나 검수 기준 자체가 모호할 때 발생합니다.

해결 방법:

1. WebUI에서 반려 기록을 확인하여 검토자(reviewer)가 제시한 사유를 확인합니다.
2. 기획자(planner)가 하위 작업을 생성할 때 작성하는 검수 기준을 더 구체적이고 정량적으로 수정합니다.
3. 실행자의 능력이 부족한 경우, 더 강력한 모델로 교체합니다 (OpenClaw 에이전트의 API Key 업데이트).

---

4. 순찰자(patrol)가 응답하지 않음

증상: 시스템에 정체된 작업이 있음에도 순찰자가 표시하지 않거나 경고를 보내지 않음.

점검 사항:

1. 순찰자 에이전트의 OpenClaw 인스턴스가 실행 중인지 확인
2. 순찰자의 cron 간격이 너무 길지 않은지 확인 (*/10이 */60보다 훨씬 민감하게 반응함)
3. config.yaml에서 notification이 활성화되어 있고 채널이 올바른지 확인
4. 순찰자 에이전트에게 알림 전송 스킬(Feishu/이메일 등)이 있는지 확인

---

5. API Key 만료 또는 권한 부족

증상: 에이전트가 업무 중 갑자기 멈추고 로그에 401 또는 403 오류 발생.

원인: 에이전트의 API Key(om_으로 시작)는 OpenMOSS 내부 인증용이며 LLM의 API Key와는 별개입니다. 로그에 LLM 인증 오류가 있다면 에이전트의 LLM API Key 문제(한도 초과, 권한 취소 등)입니다.

해결 방법: OpenClaw 에이전트 설정에서 LLM API Key를 업데이트한 뒤 해당 에이전트 인스턴스를 재시작하세요.

---

6. 여러 실행자가 동시에 같은 작업을 수락함

증상: 두 명의 실행자가 같은 하위 작업을 시작하여 중복 업무 발생.

원인: OpenMOSS의 작업 대기열은 원자성(Atomicity)을 보호하므로 이론적으로는 중복 수락이 불가능합니다. 하지만 다음과 같은 경우 발생할 수 있습니다:

1. 실행자들의 cron 간격이 너무 짧아 아주 짧은 시간차로 동시에 활성화된 경우
2. 상태 업데이트 지연으로 인해 실행자가 오래된(stale) 데이터를 읽은 경우

해결 방법: 실행자의 cron 간격을 적절히 늘려(예: */5에서 */15로 변경) 상태 업데이트가 완료될 충분한 시간을 확보하세요.

---

심화 학습 / 향후 발전 방향

1. 에이전트 역할 프롬프트 커스텀

prompts/ 디렉토리에 각 역할의 프롬프트 템플릿이 있습니다. 이를 수정하여 내 비즈니스 요구에 맞는 에이전트 성격을 만들 수 있습니다:

# 기획자 프롬프트 수정
vim prompts/agents/planner-agent-prompt.md

# 실행자 프롬프트 수정
vim prompts/agents/executor-agent-prompt.md

수정된 프롬프트는 에이전트가 다음 번에 활성화될 때 자동으로 적용됩니다.

2. WordPress 스킬 연동을 통한 자동 게시

skills/wordpress-skill/은 WordPress 게시 기능을 제공합니다. 이를 실행자와 함께 사용하면 번역된 기사를 사람의 개입 없이 자동으로 WordPress 사이트에 게시할 수 있습니다.

WordPress 사이트의 URL과 API Key 설정이 필요합니다:

# WordPress 스킬 설정 안내 확인
cat skills/wordpress-skill/SKILL.md

3. 포인트 및 성과 시스템 최적화

OpenMOSS에는 에이전트 포인트 메커니즘이 내장되어 있어 검토자의 평점이 실행자의 성과 순위에 직접 영향을 미칩니다. WebUI의 「포인트 랭킹」 페이지에서 각 에이전트의 산출물 품질을 확인할 수 있습니다.

포인트 시스템을 더 엄격하거나 관대하게 만들고 싶다면 검토자의 프롬프트에서 채점 기준 설명을 수정하면 됩니다.

4. Grok Search Skill을 통한 실시간 검색 연동

skills/grok-search-runtime/은 Grok 실시간 검색 기능을 제공합니다. 실행자가 이 스킬을 가지면 인터넷 정보를 실시간으로 수집하여 번역, 정리, 게시할 수 있습니다. 이는 1M Reviews 사례의 핵심 워크플로우입니다.

5. PostgreSQL / MySQL로 마이그레이션

현재 OpenMOSS는 중소규모 팀에 적합한 SQLite를 기본으로 사용합니다. 더 높은 동시성 지원이 필요한 경우 PostgreSQL이나 MySQL로 전환할 수 있습니다:

# config.yaml
database:
  type: postgresql  # 또는 mysql
  path: ""           # 비워두고 아래 연결 문자열 사용
  connection_string: "postgresql://user:pass@localhost:5432/openmoss"

6. Docker 한 번에 배포하기

프로젝트에서 제공하는 Dockerfile과 docker-compose.yml을 사용하여 전체 환경을 한 번에 배포할 수 있습니다:

# 모든 서비스 시작
docker-compose up -d

# 로그 확인
docker-compose logs -f

OpenMOSS, 데이터베이스, 프론트엔드가 모두 패키징되어 실행되므로 빠른 검증이나 서버 이전 시 유용합니다.

7. 나만의 콘텐츠 생산 파이프라인 구축

1M Reviews의 실제 사례를 참고한 전체 파이프라인은 다음과 같습니다:

1. planner: 작업 분해 (수집 → 번역 → 검토 → 게시)
2. executor (수집): Grok Search Skill을 통한 정보 수집
3. executor (번역): 번역 API를 호출하여 내용 각색
4. reviewer: 콘텐츠 품질 및 형식 검토
5. executor (게시): WordPress Skill을 호출하여 웹사이트 게시
6. patrol: 시스템 운용 상태 모니터링 및 이상 발생 시 알림

전체 프로세스는 자율적으로 운영되며, 사용자는 처음에 목표를 설정하고 마지막에 결과물만 확인하면 됩니다.