oh-my-claudecode 배포 및 팁: 32개의 전문 에이전트가 대신 일해주는 효율 두 배의 업무 환경

난이도: 중급 | 소요 시간: 30분 | 학습 목표: 멀티 에이전트 오케스트레이션, 제로 구성 배포, 팀 파이프라인 구축 마스터

대상 독자: 이미 Claude Code를 사용 중이거나 사용 계획이 있는 개발자, 에이전트 협업 효율을 한 단계 더 높이고 싶은 팀.

핵심 종속성: Node.js ≥18, tmux(교차 플랫폼 선택 사항), Claude Code CLI

---

1. 프로젝트 소개

Claude Code 자체로도 강력하지만, 단일 에이전트는 복잡한 멀티 모듈 프로젝트를 처리할 때 한계가 있습니다. 여러 대화창을 반복해서 전환하거나 코드 리뷰, 아키텍처 설계, 테스트 검증을 수동으로 조율해야 하는 번거로움이 따릅니다.

oh-my-claudecode(이하 OMC)는 바로 이 문제를 해결하기 위해 탄생했습니다. Claude Code의 멀티 에이전트 오케스트레이션 레이어로서 핵심 이념은 다음과 같습니다:

Claude Code를 배우지 마세요. 그냥 OMC를 사용하세요.

간단히 말해, 원하는 바를 자연어로 설명하기만 하면 됩니다. OMC가 32개의 전문 에이전트를 자동으로 스케줄링하고, 적절한 모델(Haiku / Sonnet / Opus)을 선택하며, 검증이 완료될 때까지 작업을 병렬로 처리합니다. 전체 과정은 설정이 필요 없으며(Zero-config), 어떤 명령어도 외울 필요가 없습니다.

프로젝트 주소: https://github.com/Yeachan-Heo/oh-my-claudecode

---

2. 주요 기능 개요

2.1 제로 구성(Zero-config) 및 즉시 사용 가능

YAML이나 JSON 설정을 작성할 필요 없이 설치 후 일상 언어로 말하면 바로 실행됩니다. 스마트한 기본값이 90% 이상의 시나리오를 커버합니다.

2.2 32개의 전문 에이전트

각 에이전트는 명확한 책임 범위를 가지며, OMC는 작업 유형에 따라 가장 적합한 에이전트로 자동 라우팅합니다:

전체 목록은 AGENTS.md에 정의되어 있습니다.

2.3 스마트 모델 라우팅

OMC는 작업의 복잡도에 따라 자동으로 모델을 선택합니다:

• Haiku: 간단한 검색, 포맷팅, 가벼운 문구 수정
• Sonnet: 표준 구현, 디버깅, 테스트(일상적인 주력 모델)
• Opus: 아키텍처 설계, 보안 검토, 복잡한 리팩토링

이러한 방식의 장점은 비용 최적화이며, 커뮤니티 피드백에 따르면 평균 30-50%의 토큰 소비를 절감할 수 있습니다.

2.4 자동 병렬화

독립적인 작업은 수동으로 나눌 필요 없이 자동으로 서로 다른 에이전트에게 할당되어 병렬로 실행됩니다.

2.5 지속적 실행 (verify/fix 루프)

Ralph 모드에서는 에이전트가 작업을 마친 후 자동으로 검증 루프에 진입합니다. 검증에 실패하면 실제로 통과할 때까지 스스로 수정하고 다시 실행합니다.

2.6 스킬 자가 학습 (Learner 시스템)

실행 과정에서 겪은 디버깅 경험은 자동으로 재사용 가능한 Skill 파일로 추출되어 .omc/skills/ 아래에 저장됩니다. 다음에 유사한 문제를 만나면 수동으로 기억해낼 필요 없이 컨텍스트에 자동으로 주입됩니다.

2.7 OpenClaw 통합

Claude Code 세션 이벤트를 OpenClaw Gateway로 전달하여 Telegram / Discord 등의 채널을 통한 자동 알림 및 원격 트리거를 지원합니다.

---

3. 전체 프로젝트 구조

oh-my-claudecode/
├── agents/              # 32개 전문 에이전트 정의 파일
├── bridge/              # OpenClaw / 서드파티 브릿지
├── docs/                # 아키텍처 문서, 마이그레이션 가이드, 성능 모니터링
├── examples/            # 워크플로우 예시
├── hooks/               # Claude Code 훅 주입
├── missions/            # 미션 정의
├── research/            # 연구 모듈
├── scripts/             # 도구 스크립트 (OpenClaw Gateway Demo 등)
├── skills/              # OMC 내장 Skill 파일
├── src/                 # 핵심 소스 코드
├── tests/               # 테스트 슈트
├── CLAUDE.md            # 에이전트 런타임 주요 설정 (OMC가 Claude Code에 주입)
├── AGENTS.md            # 에이전트 목록 및 설명
└── package.json

일반 사용자 입장에서 주로 다루게 되는 항목은 다음과 같습니다:

• skills/ — 사용자 정의 Skill 파일
• .omc/ — 런타임에 생성된 세션, 상태, 계획 파일

---

4. 설치 및 설정

4.1 사전 요구 사항

필수 설치:

• Claude Code CLI — Max/Pro 구독 또는 Anthropic API Key 필요
• Node.js ≥18 — OMC는 TypeScript/npm 프로젝트입니다.

선택 사항(강력 권장):

• tmux — omc team 및 속도 제한 자동 복구 기능은 tmux에 의존합니다.

플랫폼별 tmux 설치:

# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# Arch
sudo pacman -S tmux

# Windows 기본 (권장)
winget install psmux

# Windows WSL2
sudo apt install tmux

4.2 OMC 설치 (두 가지 방식)

방식 1: Marketplace 설치 (권장)

# 플러그인 소스 추가
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

# 플러그인 설치
/plugin install oh-my-claudecode

방식 2: npm 전역 설치

npm i -g oh-my-claude-sisyphus@latest

설치가 완료되면 OMC가 자동으로 활성화되며, 모든 / 명령어와 매직 키워드를 사용할 수 있습니다.

4.3 초기 설정

# 아무 디렉토리에서나 실행
/setup
/omc-setup

최초 실행 시 다음 설정을 안내합니다:

• Claude Code 설정 디렉토리 확인
• OpenClaw Gateway (선택 사항)
• tmux 세션 감지

문제가 발생하면 진단 도구를 실행하세요:

/omc-doctor

4.4 Team Mode 활성화 (권장)

Team Mode는 OMC v4.1.7 이후의 기본 오케스트레이션 방식입니다. Claude Code 설정에서 실험적 기능을 활성화해야 합니다:

# ~/.claude/settings.json 편집

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

---

5. 실행 모드 심층 분석

OMC는 다양한 작업 시나리오에 적합한 여러 실행 모드를 제공합니다. 차이점을 이해하는 것이 효율적인 사용의 핵심입니다.

5.1 Team Mode (권장) ⭐

적용 시나리오: 아키텍처, 코딩, 리뷰, 테스트의 협업이 필요한 복잡한 멀티 모듈 작업.

Team Mode는 엄격한 파이프라인을 따라 실행됩니다:

team-plan → team-prd → team-exec → team-verify → team-fix (루프)

작업은 계획부터 시작하여 제품 설계, 코드 실행, 검증을 거치며, fix 단계에서 문제가 발견되면 실행 단계로 돌아가 다시 시작합니다. 전체 과정은 사용자의 개입 없이 OMC가 자동으로 조정합니다.

기본 사용법:

/team 3:executor "모든 TypeScript 컴파일 오류 수정"

숫자 3은 3개의 executor 에이전트를 사용하여 병렬 처리함을 의미합니다.

CLI 버전 tmux Workers (v4.4.0+):

omc team 2:codex "auth 모듈 보안 검토"
omc team 2:gemini "UI 컴포넌트 접근성 재설계"
omc team 1:claude "결제 프로세스 구현"
omc team status auth-review
omc team shutdown auth-review

이들은 실제 독립적인 tmux 프로세스로 실행되며, 완료 후 리소스를 점유하지 않고 자동으로 종료됩니다.

5.2 Autopilot

적용 시나리오: 명확한 요구사항이 있고 사람의 개입 없이 엔드 투 엔드로 기능을 완성해야 할 때.

autopilot: build a REST API for managing tasks

Autopilot 모드에서는 단일 Lead 에이전트가 설계부터 구현까지 전 과정을 책임지며, 파이프라인에 의존하지 않습니다.

5.3 Ralph (지속성 모드)

적용 시나리오: 작업이 반드시 완전히 완료되어야 하며, "부분 완료 후 종료"가 허용되지 않을 때.

Ralph 모드는 Ultrawork의 병렬 능력에 verify/fix 루프를 추가한 형태입니다:

executor → verify → fix → verify (통과할 때까지)

ralph: auth 모듈 리팩토링, 모든 테스트 통과 필수

Claude Code가 실제 검증 없이 "완료된 것처럼 보일 때" 종료되는 현상을 자주 겪는다면 Ralph가 해결책입니다.

5.4 Ultrawork (최대 병렬)

적용 시나리오: 최단 시간에 처리해야 하는 대량의 수정 또는 리팩토링.

ulw 모든 ESLint 오류 수정
ulw 모든 컴포넌트 이름을 PascalCase로 변경

이전 작업의 완료를 기다리지 않고 모든 수정을 병렬로 실행하므로 "기지 오류 목록"의 일괄 처리에 적합합니다.

5.5 /ccg 3중 모델 어드바이저

적용 시나리오: Codex와 Gemini의 시각을 동시에 얻고 Claude가 이를 종합해야 할 때.

/ccg 이 PR을 검토해줘 — 아키텍처(Codex) 및 UI 컴포넌트(Gemini)

/ask codex와 /ask gemini를 호출하고, Claude가 최종적으로 종합된 출력을 담당합니다. 백엔드와 프런트엔드 교차 리뷰 또는 멀티 모델 검증이 필요한 시나리오에 적합합니다.

5.6 모드별 비교표

---

6. 실전 활용 사례

6.1 시나리오 1: REST API 구축 (Team Mode)

Team Mode를 사용하여 작업 관리 REST API를 구축한다고 가정해 봅시다:

/team 2:executor "Express + TypeScript를 사용하여 CRUD 인터페이스 4개를 포함한 작업 관리 REST API 구현"

OMC는 자동으로 작업을 분해합니다:

1. architect가 API 구조와 데이터 모델 설계
2. executor들이 각 인터페이스를 병렬로 구현
3. test-engineer가 통합 테스트 작성
4. code-reviewer가 코드 검토
5. verifier가 테스트를 실행하여 검증

사용자는 최종 결과만 기다리면 됩니다.

6.2 시나리오 2: 모든 오류 자동 수정 (Ultrawork)

ulw 모든 TypeScript 타입 오류와 ESLint 경고 수정

CI/CD 파이프라인이나 레거시 프로젝트를 인수했을 때 빠른 정리에 적합합니다.

6.3 시나리오 3: 요구사항이 불명확할 때 (Deep Interview)

무엇을 해야 할지 스스로도 확신이 서지 않는다면:

/deep-interview "개인 블로그 시스템을 만들고 싶어"

Deep Interview는 산파법 질문을 통해 요구사항을 명확히 해줍니다: 대상 독자, 선호 기술 스택, CMS 필요 여부, SEO 요구사항 등. 명확히 한 뒤 작업을 시작하여 중도 폐기를 방지합니다.

6.4 시나리오 4: 멀티 모델 교차 검토 (/ccg)

/ccg 이 PR의 백엔드 아키텍처는 Codex가, UI 컴포넌트는 Gemini가 검토해줘

6.5 시나리오 5: 속도 제한 자동 복구

Claude API의 속도 제한(Rate Limit)이 발생했을 때:

omc wait          # 현재 상태 및 복구 가이드 확인
omc wait --start  # 자동 복구 데몬 시작
omc wait --stop   # 데몬 정지

---

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

Q1: /team 명령어가 작동하지 않고 "Team Mode 미활성화" 오류가 뜹니다.

원인: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 환경 변수가 설정되지 않았습니다.

해결:

# ~/.claude/settings.json 파일을 열어 다음을 추가하세요:
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Claude Code 세션을 재시작하면 적용됩니다.

---

Q2: omc team 실행 시 tmux 관련 오류가 발생합니다.

원인: Windows 사용자가 tmux를 설치하지 않았거나, tmux가 PATH에 등록되어 있지 않습니다.

해결:

# Windows 기본
winget install psmux

# macOS
brew install tmux

# 설치 확인
tmux -V

이미 설치되어 있는데도 오류가 난다면, psmux의 bin 디렉토리가 시스템 PATH에 포함되어 있는지 확인하세요.

---

Q3: Marketplace 설치 후 OMC 명령어가 작동하지 않습니다.

원인: 플러그인 캐시가 갱신되지 않았거나 설치 경로가 잘못되었습니다.

해결:

# marketplace 클론 업데이트
/plugin marketplace update omc

# 재초기화
/setup

# 진단 도구 실행
/omc-doctor

---

Q4: Claude Code에서 속도 제한이 떴는데 자동 복구가 안 됩니다.

원인: omc wait --start가 실행되지 않았거나, tmux 세션 내부에서 실행 중이 아닙니다.

해결:

# 반드시 tmux 세션 내에서 실행하세요
tmux new -s omc-watch
omc wait --start

데몬이 시작되면 tmux 백그라운드에서 실행되며, 속도 제한이 해제되면 자동으로 Claude Code 세션을 재개합니다.

---

Q5: OMC 업데이트 후 동작이 이상합니다.

원인: 구버전 플러그인 캐시와 신버전 코드 간의 호환성 문제입니다.

해결:

# Marketplace 설치의 경우:
/plugin marketplace update omc
/setup

# npm 설치의 경우:
npm i -g oh-my-claude-sisyphus@latest
/omc-doctor

---

Q6: Skill 파일이 자동으로 주입되지 않습니다.

원인: Skill 트리거 키워드가 일치하지 않거나 파일 경로가 잘못되었습니다.

해결:

Skill 파일은 우선순위에 따라 두 곳에 위치할 수 있습니다:

# 프로젝트 수준 (높은 우선순위): .omc/skills/
# 사용자 수준 (낮은 우선순위): ~/.omc/skills/

Skill 파일의 frontmatter 내 triggers 배열에 현재 대화의 키워드가 포함되어 있는지 확인하세요:

---
name: Fix Proxy Crash
description: aiohttp proxy crashes on ClientDisconnectedError
triggers: ["proxy", "aiohttp", "disconnected"]  # 키워드 매칭
source: extracted
---

---

8. 추가 읽을거리 / 심화 학습

8.1 사용자 정의 Skill 작성

OMC는 실제 디버깅 경험에서 재사용 가능한 Skill을 추출할 수 있습니다:

/learner

추출 후 .omc/skills/ 아래에 YAML 파일이 생성됩니다. 다음에 유사한 문제를 만나면 수동 리콜 없이 자동 주입됩니다.

8.2 OpenClaw 통합

OMC는 원격 트리거 및 알림을 위해 Claude Code 세션 이벤트를 OpenClaw Gateway로 전달할 수 있습니다:

# 자동 구성 가이드 실행
/oh-my-claudecode:configure-notifications
# → "OpenClaw Gateway" 선택

~/.claude/omc_config.openclaw.json 수동 설정:

{
  "enabled": true,
  "gateways": {
    "my-gateway": {
      "url": "https://your-gateway.example.com/wake",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" },
      "method": "POST",
      "timeout": 10000
    }
  },
  "hooks": {
    "session-start": { "gateway": "my-gateway", "instruction": "Session started for {{projectName}}", "enabled": true },
    "stop":          { "gateway": "my-gateway", "instruction": "Session stopping for {{projectName}}", "enabled": true }
  }
}

지원되는 훅 이벤트: session-start, stop, keyword-detector, ask-user-question, pre-tool-use, post-tool-use.

8.3 알림 시스템 (Telegram / Discord / Slack)

omc config-stop-callback telegram --enable --token <bot_token> --chat <chat_id> --tag-list "@alice,bob"
omc config-stop-callback discord --enable --webhook <url> --tag-list "@here,123456789012345678"

세션 종료 시 요약본이 그룹에 자동 전송되며, 증분 태그 업데이트를 지원합니다.

8.4 OpenClaw + OMC 협업 워크플로우

OpenClaw의 자동화와 OMC의 멀티 에이전트 오케스트레이션을 결합하면 다음과 같은 구현이 가능합니다:

• OpenClaw가 Discord/Telegram 메시지를 감시하여 Claude Code 세션 트리거
• OMC가 Claude Code 내부에서 32개 에이전트를 조율하여 복잡한 작업 수행
• OpenClaw Gateway가 결과를 다시 채팅 채널로 푸시

이를 통해 일상적인 채팅 도구로 명령을 내리는 24시간 온라인 멀티 에이전트 도우미를 가질 수 있습니다.

이 협업 아키텍처 구축 방법은 scripts/openclaw-gateway-demo.mjs를 참고하세요.

8.5 성능 모니터링 및 디버깅

OMC는 실행 중 .omc/ 아래에 다양한 파일을 생성합니다:

.omc/sessions/*.json        # 세션 요약
.omc/state/agent-replay-*.jsonl  # 실행 리플레이 로그
.omc/plans/                 # 작업 계획
.omc/research/              # 연구 결과물

HUD를 실행하여 실시간 오케스트레이션 상태를 확인하세요:

/oh-my-claudecode:hud setup
omc hud

---

참고 링크

• 프로젝트 홈페이지: https://github.com/Yeachan-Heo/oh-my-claudecode
• npm 패키지: https://www.npmjs.com/package/oh-my-claude-sisyphus
• 전체 문서: https://yeachan-heo.github.io/oh-my-claudecode-website
• CLI 참조: https://yeachan-heo.github.io/oh-my-claudecode-website/docs.html#cli-reference
• Discord 커뮤니티: https://discord.gg/PUwSMR9XNk