Multica 입문: 오픈소스 Claude Managed Agents, AI 직원 관리 시스템(작업 보드, 자율적으로 작업 수주, 기술을 축적 가능)

입문용 | 약 20분 | Multica의 핵심 개념(보드/에이전트/스킬/런타임)을 익히고, 자체 호스팅 배포(Docker), 로컬 데몬 설정, 그리고 에이전트를 생성하고 작업을 할당하는 전체 과정을 습득합니다

---

프로젝트 소개

먼저 이런 질문부터 해볼게요. 지금 여러분의 팀에는 AI 프로그래밍 어시스턴트가 몇 개나 돌고 있나요? Claude Code, Codex, 그리고 커스터마이징한 일부 에이전트들. 그런데 이들은 각자 독립적으로 일하고, 작업 귀속이 없으며, 진행 상황도 추적되지 않고, 기억이 쌓이지 않습니다. 한 작업을 끝내면 바로 잊어버리죠. 다음에 같은 문제가 다시 생겨도 처음부터 다시 시작해야 합니다.

Multica가 하는 일은 AI 프로그래밍 어시스턴트를 위한 작업 보드(Task Board) 를 만들어주는 것입니다. 여기서 Issue를 생성하고, 동료에게 작업을 배정하듯이 AI 직원에게 할당할 수 있어요. 그러면 AI 직원이 작업을 자동으로 수락하고, 코드를 실행하고, 진행 상황을 보고하며, 코멘트하고, 심지어 새로운 Issue를 직접 생성하기도 합니다. 더 재미있는 점은, 성공적으로 해결한 방법을 「스킬(Skills)」로 축적해 팀의 모든 AI 직원이 재사용할 수 있다는 것입니다.

즉, Multica는 AI 프로그래밍 어시스턴트의 「조직이 없고, 기억이 없고, 협업이 불가능한」 문제 를 해결합니다.

---

대상 독자

• Claude Code / Codex 같은 AI 프로그래밍 어시스턴트를 쓰고 있지만 개발자 관리가 지저분해져 고민인 분
• 인간-기계 혼합 팀을 구성하려는 제품/엔지니어링 팀
• AI Agent의 자율화에 관심이 있는 테크 리드

핵심 의존성 및 환경

• Docker + Docker Compose(자체 호스팅 배포)
• 최소 1개 AI 프로그래밍 CLI(Claude Code / Codex / OpenClaw / OpenCode)
• Go 1.26+(소스 개발용) / Node.js 20+ + pnpm(프론트엔드 개발용)

전체 프로젝트 구조 트리

multica/
├── server/              # Go 백엔드(Chi 라우팅 + WebSocket 실시간 푸시)
├── apps/web/           # Next.js 16 프론트엔드(작업 보드 화면)
├── packages/           # 공유 패키지
│   ├── core/          # 핵심 로직(Zustand 상태, TanStack Query)
│   ├── ui/            # 원자 UI 컴포넌트(shadcn + Base UI)
│   └── views/         # 공유 페이지와 컴포넌트
└── docker-compose.selfhost.yml  # 자체 호스팅 배포 설정

~/.multica/             # 사용자 수준 CLI 설정
├── daemon.log         # 데몬 실행 로그
└── config             # 인증 토큰 및 서버 설정

---

단계별 진행

1단계: Docker Compose로 원클릭 배포

자체 호스팅을 선택했다면, 배포는 아래 세 줄 명령만으로 끝납니다:

git clone https://github.com/multica-ai/multica.git
cd multica
cp .env.example .env

.env를 편집하고, 최소한 JWT_SECRET을 설정합니다:

JWT_SECRET=$(openssl rand -hex 32)
# 생성된 랜덤 문자열을 .env의 JWT_SECRET 필드에 그대로 입력

모든 서비스를 시작합니다:

docker compose -f docker-compose.selfhost.yml up -d

그러면 세 개의 컨테이너가 자동으로 실행됩니다: PostgreSQL( pgvector 확장 포함 ), Go 백엔드(자동으로 DB 마이그레이션 실행), Next.js 프론트엔드. http://localhost:3000을 열면 작업 보드를 확인할 수 있습니다.

2단계: 계정 등록 + Workspace 생성

http://localhost:3000를 열고 이메일로 로그인하세요( Magic Link는 이메일로 발송됩니다).

로그인 후 기본 Workspace로 이동합니다. Workspace는 Multica의 격리 단위입니다. 각 Workspace마다 고유한 Agent, Issue, 멤버가 있습니다. 팀에 여러 프로젝트가 있다면, 여러 Workspace를 만들어 격리 관리할 수 있습니다.

3단계: multica CLI 설치 + Daemon 시작

Daemon은 로컬 런타임으로, 여러분의 머신을 AI 작업을 실행할 수 있는 「Runtime」으로 바꿔줍니다. 설치 방법은 아래 중 하나를 선택하면 됩니다:

# 방법 1: Homebrew( macOS / Linux )
brew tap multica-ai/tap
brew install multica

# 방법 2: 소스에서 컴파일
git clone https://github.com/multica-ai/multica.git
cd multica
make build
cp server/bin/multica /usr/local/bin/multica

설치가 끝나면, 자체 호스팅 서버에 연결합니다(클라우드 Multica라면 이 단계를 건너뜁니다):

# 자체 호스팅은 먼저 서버 주소를 지정해야 합니다
export MULTICA_APP_URL=http://localhost:3000
export MULTICA_SERVER_URL=ws://localhost:8080/ws

# 설정 영속화
multica config set app_url http://localhost:3000
multica config set server_url ws://localhost:8080/ws

로그인하고 Daemon을 시작합니다:

multica login    # 브라우저를 열어 인증을 완료합니다
multica daemon start   # 백그라운드 실행 후 작업을 대기합니다

Daemon은 여러분의 머신에 설치된 AI 프로그래밍 CLI(claude, codex, openclaw, opencode)를 자동으로 감지하고, 이를 사용 가능한 Runtime으로 등록합니다.

4단계: Settings → Agents에서 첫 번째 AI Agent 만들기

프론트엔드로 돌아가서 Settings → Agents → New Agent 로 이동합니다:

1. Runtime 선택(여러분의 머신에서 감지된 CLI)
2. Provider 선택(Claude Code / Codex / OpenClaw / OpenCode)
3. Agent 이름 지정 — 이것이 작업 보드에서 해당 Agent의 「정체성」이 됩니다

생성이 완료되면, 이 Agent는 작업 보드의 멤버 목록에 로봇 아이콘과 함께 나타납니다.

5단계: Runtime이 온라인인지 확인

Settings → Runtimes 로 들어가면, 여러분의 머신이 「Active」 상태로 표시되어야 합니다. 그렇지 않다면:

# Daemon 상태 확인
multica daemon status

# 실시간 로그 확인
multica daemon logs -f

Runtime이 오프라인인 경우는 보통 Daemon이 실행되지 않았거나, AI CLI가 PATH에 없기 때문입니다. Claude Code 또는 Codex를 설치한 뒤 다시 multica daemon start를 실행하세요.

6단계: Issue 생성 후 Agent에 할당

작업 보드로 돌아가서 New Issue 를 클릭하고 제목과 설명을 작성한 다음, 방금 만든 Agent에 Assign 합니다.

또는 CLI로 생성:

multica issue create \
  --title "Add dark mode to settings page" \
  --description "Use CSS variables for theming, support system preference detection" \
  --priority high \
  --assignee "Lambda"   # 여기에 여러분의 Agent 이름을 입력

할당 후에는 Issue의 상태가 todo에서 자동으로 in_progress로 바뀝니다. Daemon이 자신에게 할당된 작업을 감지해 즉시 수락하고 실행을 시작하기 때문입니다.

7단계: Agent의 자율 실행을 관찰하기

Agent는 자동으로 다음을 수행합니다:

1. 작업 수락 — 자신에게 할당된 Issue를 확인하면 실행 상태로 전환
2. 진행 보고 — WebSocket으로 상태를 작업 보드에 실시간 푸시하므로, 무엇을 하고 있는지 확인할 수 있습니다
3. 코멘트 및 피드백 — Issue 아래에 코멘트를 남겨 진행 상황이나 막힌 지점을 설명
4. 하위 Issue 생성 — 작업이 너무 크다고 판단되면 자율적으로 하위 작업으로 쪼갭니다
5. 완료 또는 보고 — 작업이 끝나면 done으로 표시, 해결할 수 없는 문제가 생기면 blocked로 표시하고 이유를 설명

이후에는 다른 일을 계속해도 됩니다. 다시 돌아오면 PR이 이미 만들어져 있을 수도 있어요.

8단계: 실행 로그 확인

CLI로 Agent의 상세 실행 과정을 확인합니다:

# 특정 Issue의 모든 실행 기록 나열
multica issue runs <issue-id>

# 특정 실행의 메시지 로그 보기(Agent의 사고 흐름, 도구 호출, 출력)
multica issue run-messages <task-id>

# 실시간 추적( tail -f 효과 )
multica issue run-messages <task-id> --since 0

이 단계는 디버깅과 Agent 동작을 이해하는 데 매우 중요합니다. 결과뿐 아니라, 전체 추론과 실행 과정까지 볼 수 있기 때문입니다.

9단계: 스킬(Skills) 축적

이 파트가 Multica에서 가장 흥미로운 부분입니다. Agent가 문제를 성공적으로 해결하면, 그 해결책을「스킬」로 축적해 팀의 모든 Agent가 호출할 수 있습니다.

스킬(Skill)은 본질적으로 재사용 가능한 경험입니다. 배포 절차, 코드 리뷰 규칙, 데이터 마이그레이션 단계 같은 것들이죠. 팀의 한 Agent가 이를 학습하면, 다른 Agent가 비슷한 상황을 만나도 바로 활용할 수 있어 다시 처음부터 탐색할 필요가 없습니다.

스킬 관리는 Settings → Skills 페이지에서 확인하고 관리할 수 있습니다.

---

자주 발생하는 문제 해결

1. Daemon이 서버에 연결되지 않음

# 자체 호스팅에서는 먼저 서버 주소를 설정해야 합니다
multica config show  # 현재 설정 확인

# 클라우드에 연결 중인데 자체 호스팅에 연결하고 싶다면
multica config set server_url ws://localhost:8080/ws
multica daemon stop
multica daemon start

2. Runtime이 오프라인으로 표시됨

# AI CLI가 설치되어 있고 PATH에 있는지 확인
which claude
which codex

# Daemon 재시작
multica daemon stop
multica daemon start

# 상태 확인
multica daemon status

3. Issue를 할당했는데 Agent가 반응하지 않음

가능한 원인 3가지:

# 원인 1: Daemon이 실행되지 않음
multica daemon status

# 원인 2: Workspace가 watch되지 않음
multica workspace list  # watch 상태 확인
multica workspace watch <workspace-id>

# 원인 3: Agent가 해당 Workspace를 watch하지 않음
# Settings → Workspaces에서 Workspace가 체크되어 있는지 확인

4. Docker 컨테이너 헬스 체크 실패

# 모든 컨테이너 상태 확인
docker compose -f docker-compose.selfhost.yml ps

# 백엔드 로그 확인
docker compose -f docker-compose.selfhost.yml logs backend

# 흔한 원인: PostgreSQL이 준비되기 전에 백엔드가 시작됨
# 10초 기다린 뒤 재시도
docker compose -f docker-compose.selfhost.yml restart backend

5. 로그인 실패( Magic Link를 받지 못함 )

# .env에 RESEND_API_KEY가 설정되어 있는지 확인
grep RESEND .env

# 없다면 https://resend.com 에서 API Key를 발급받으세요
# 그리고 .env에 추가
RESEND_API_KEY=re_xxxxx
[email protected]

# 백엔드 재시작
docker compose -f docker-compose.selfhost.yml restart backend

6. Agent 실행 시간 초과

Agent의 기본 실행 타임아웃은 2시간입니다. 작업이 너무 크다면:

# 타임아웃 연장(단위: 시간)
export MULTICA_AGENT_TIMEOUT=8h
multica daemon stop
multica daemon start

또는 Issue에서 큰 작업을 여러 개의 작은 Issue로 쪼개서, Agent에게 단계적으로 할당해 완료하세요.

---

확장 읽기 / 고급 방향

Multica Cloud: 직접 배포하고 싶지 않다면 multica.ai에 등록해서 바로 사용하세요. 제로 구성으로 쓸 수 있습니다. 클라우드는 모든 기능을 지원하며, 멀티 Workspace, 멀티 Agent, 스킬 관리도 포함합니다.

다중 Runtime 혼합: 한 대의 머신에서 여러 Daemon 설정 파일을 실행할 수 있습니다(multica --profile staging daemon start). 또는 로컬 Runtime과 클라우드 Runtime을 함께 섞어 쓰는 것도 가능하며, 여러 환경에서 개발할 때 적합합니다.

4대 Runtime 비교: Claude Code(Anthropic), Codex(OpenAI), OpenClaw(로컬 Agent), OpenCode는 각각 특징이 있습니다. Claude Code는 코드 이해와 수정에 가장 강하고, Codex는 범용 작업에 더 유연하며, OpenClaw은 로컬 툴체인이 필요한 시나리오에 적합합니다. 작업 유형에 맞는 Runtime을 선택하세요.

스킬의 심층 활용: 스킬이 진짜 재사용되도록 하려면, 단순한 아카이브로 전락하지 않게 해야 합니다. 코드 리뷰와 비슷한 스킬 심사 메커니즘을 만들고, 효과적인 스킬을 정기적으로 정리하며, 오래된 스킬은 폐기해 팀의 AI 역량이 지속적으로 진화하도록 할 수 있습니다.

아키텍처 분석: Multica의 백엔드는 Go(Chi 라우터 + WebSocket)이고, 프론트엔드는 Next.js 16(App Router + Zustand + TanStack Query)입니다. 데이터베이스는 PostgreSQL 17 + pgvector(벡터 저장소)를 사용합니다. WebSocket 실시간 푸시는 시스템의 핵심입니다. Agent의 매 단계 실행이 작업 보드로 푸시되므로 새로고침 없이 진행 상황을 확인할 수 있습니다.