Oh My OpenAgent 사용법 — 설치부터 멀티 에이전트 활용까지
AI 코딩 도구를 쓰다 보면 하나의 모델에게 코드 탐색, 문서 조사, 설계, 구현, 검증을 모두 맡기는 데 한계가 있다는 사실을 금방 체감합니다. Oh My OpenAgent(줄여서 OMO)는 이런 작업을 여러 전문 에이전트와 모델에 나누어 처리하도록 돕는 오픈소스 에이전트 오케스트레이션 하네스입니다. OpenCode에서는 강력한 플러그인 형태의 Ultimate 에디션으로, OpenAI Codex CLI에서는 가벼운 Light 에디션으로 사용할 수 있습니다. 이 글에서는 2026년 8월 공식 문서를 기준으로 설치 방법, 기본 사용 흐름, 유용한 명령과 주의점을 차례로 정리합니다.
Oh My OpenAgent는 무엇인가
OMO의 핵심은 단일 AI를 만능 도우미처럼 사용하는 대신, 역할이 다른 에이전트들을 개발팀처럼 조율하는 것입니다. 메인 오케스트레이터가 전체 작업을 관리하고, 코드베이스 탐색이나 외부 문서 조사, 복잡한 기술 판단처럼 독립적으로 처리할 수 있는 일은 전문 에이전트에 맡깁니다. 공식 기능 문서에는 11개의 전문 에이전트가 소개되어 있으며, 에이전트마다 전문 분야와 모델 선택 체인, 도구 권한이 다릅니다.
특정 모델 공급자 하나에 종속되지 않는 것도 특징입니다. 설치할 때 보유한 Claude, ChatGPT, Gemini, GitHub Copilot 또는 OpenCode Go 등의 구독 여부를 반영해 에이전트별 모델 구성을 만들 수 있습니다. 다만 모든 모델을 무조건 같은 모델로 덮어쓰면 에이전트의 역할과 모델 특성이 어긋날 수 있으므로, 처음에는 설치 프로그램이 생성한 기본값을 쓰는 편이 안전합니다.
설치 전 선택: OpenCode인가 Codex CLI인가
설치 명령을 실행하기 전에 어느 실행 환경에서 사용할지 정해야 합니다. OpenCode용 Ultimate는 플러그인, 에이전트·모델 설정, 공급자 인증까지 포함한 전체 기능 구성이며, Codex CLI용 Light는 Codex 플러그인 마켓플레이스와 에이전트 구성을 설치하는 경량판입니다. 두 환경을 모두 쓰는 구성도 지원합니다.
- OpenCode Ultimate: 터미널 기반 OpenCode에서 OMO의 전체 오케스트레이션 기능을 사용하려는 경우
- Codex CLI Light: 기존 Codex CLI 환경에 OMO식 에이전트 구성과 도구를 추가하려는 경우
- Both: 두 환경을 오가며 동일한 작업 방식을 사용하려는 경우
프로젝트 이름은 과거 Oh My OpenCode에서 Oh My OpenAgent로 변경되었습니다. 이전 패키지명인 oh-my-opencode도 전환 기간 동안 호환되지만, 새 설치와 OpenCode의 플러그인 등록에는 oh-my-openagent를 사용하는 것이 권장됩니다.
설치와 상태 확인
OpenCode용 권장 설치 방법은 Bun의 일회성 실행 명령을 사용하는 것입니다. 설치 화면에서 사용하는 구독과 공급자를 선택하면 알맞은 설정을 생성합니다.
bunx oh-my-openagent installCodex CLI만 사용한다면 다음 명령으로 Light 에디션을 설치할 수 있습니다.
npx lazycodex-ai install두 플랫폼을 한 번에 구성하려면 다음과 같이 플랫폼 옵션을 지정합니다.
bunx oh-my-openagent install --platform=both공식 문서는 npm install -g나 bun add -g 같은 전역 설치를 권장하지 않습니다. 플러그인이 OpenCode 또는 Codex가 읽는 정확한 위치에 설치되어야 하고 준비 과정에서 Bun이 필요하기 때문입니다. OpenCode를 사용한다면 버전이 1.4.0 이상인지 확인한 뒤 진단 명령을 실행합니다.
opencode --version
bunx oh-my-openagent doctordoctor는 시스템, 설정, 도구, 모델 상태를 점검합니다. 더 자세한 결과는 --verbose, 자동화에서 읽을 JSON 결과는 --json 옵션으로 확인할 수 있습니다. 예전 플러그인 이름이 설정에 남아 있다면 경고도 표시합니다.
기본 사용 흐름
설치가 끝난 뒤 OpenCode 사용자는 프로젝트 디렉터리에서 opencode를 실행하고 평소처럼 자연어로 작업을 요청하면 됩니다. 좋은 요청은 목표, 작업 범위, 제약 조건, 완료 기준을 함께 담습니다. 예를 들어 “이 저장소의 인증 흐름을 조사하고 보안상 문제를 찾은 뒤, 기존 API 호환성을 유지하면서 수정하고 관련 테스트를 통과시켜 줘”처럼 요청할 수 있습니다. 이런 복합 작업에서는 메인 에이전트가 탐색과 조사 작업을 백그라운드 에이전트에 나누고 결과를 모아 구현을 진행합니다.
처음 접한 대형 저장소라면 /init-deep가 유용합니다. 이 명령은 프로젝트의 디렉터리 구조를 분석해 계층형 AGENTS.md 지식 기반을 만듭니다. 이후 에이전트가 작업할 때 루트의 공통 지침과 하위 디렉터리별 맥락을 함께 읽을 수 있어, 반복적인 설명을 줄이는 데 도움이 됩니다.
/init-deep --max-depth=3리팩터링 작업은 /refactor, 계획이 준비된 작업 세션은 /start-work로 시작할 수 있습니다. 장시간 자율 작업을 반복 수행하는 Ralph Loop와 Ultrawork 계열 명령도 제공되지만, 범위가 불명확한 상태에서 켜기보다는 테스트와 종료 조건을 먼저 명확히 적는 편이 좋습니다. 반복 작업을 중단해야 할 때는 /stop-continuation을 사용하고, 새 세션으로 넘길 때는 /handoff로 상세한 맥락 요약을 만들 수 있습니다.
터미널 자동화와 설정
대화형 화면을 열지 않고 작업을 실행해야 한다면 run 명령을 사용할 수 있습니다. 이 명령은 할 일이 모두 완료 또는 취소되고 백그라운드 자식 세션이 유휴 상태가 될 때까지 기다린 뒤 종료합니다.
bunx oh-my-openagent run "테스트 실패 원인을 찾아 수정하고 결과를 요약해 줘" --directory /path/to/project --json필요할 때만 --agent나 --model로 실행 에이전트와 모델을 지정할 수 있습니다. 별도 지정이 없으면 명령행 옵션, 환경 변수, 플러그인 설정, 기본 Sisyphus 순서로 에이전트를 결정합니다. 현재 통합 설정 파일은 ~/.omo/omo.jsonc이며, 프로젝트별 설정은 .omo/omo.jsonc에 둘 수 있습니다. JSONC 형식이므로 주석과 후행 쉼표를 지원합니다.
처음부터 세부 모델 매핑을 과도하게 바꾸기보다 기본 구성으로 실제 작업을 몇 번 수행한 뒤 비용이나 품질 문제가 확인된 에이전트만 조정하는 것이 좋습니다. 사용할 수 있는 모델은 opencode models로 확인하고, 모델 기능 캐시가 오래되었다면 bunx oh-my-openagent refresh-model-capabilities로 갱신할 수 있습니다.
알아둘 점과 실전 팁
- 권한을 확인합니다. 자율 에이전트는 파일 변경과 명령 실행 범위가 넓습니다. 중요한 저장소에서는 Git 브랜치와 깨끗한 작업 트리를 준비하고, 비밀키가 출력되거나 커밋되지 않도록 합니다.
- 완료 기준을 구체화합니다. “고쳐 줘”보다 통과해야 할 테스트, 유지할 API, 수정 금지 영역을 함께 적으면 결과가 안정적입니다.
- 진단부터 합니다. 에이전트나 모델이 보이지 않으면 무작정 재설치하기 전에
doctor --verbose와 OpenCode 설정의 플러그인 항목을 확인합니다. - 비용을 관찰합니다. 여러 에이전트가 병렬로 모델을 호출할 수 있으므로, 유료 구독 한도와 API 과금 정책을 확인해야 합니다.
- 텔레메트리를 선택합니다. 공식 문서에 따르면 익명 사용 이벤트가 기본 활성화됩니다. 원하지 않으면
OMO_DISABLE_POSTHOG=1또는OMO_SEND_ANONYMOUS_TELEMETRY=0환경 변수로 끌 수 있습니다.
마무리
Oh My OpenAgent는 단순히 프롬프트를 꾸며 주는 확장 기능이라기보다, 복잡한 개발 작업을 여러 역할과 모델에 분배하는 실행 계층에 가깝습니다. 입문자는 OpenCode용 bunx oh-my-openagent install 또는 Codex용 npx lazycodex-ai install로 시작하고, 설치 직후 doctor로 상태를 확인하면 됩니다. 이후에는 작은 저장소에서 /init-deep와 일반 작업 요청을 시험해 보고, 자동화가 필요한 시점에 run과 모델별 설정을 확장하는 순서가 부담이 적습니다.
참고 자료
'AI Agent' 카테고리의 다른 글
| Multi-Agent-CAD 공개 — 4개 에이전트가 3D 설계를 나누는 방법 (1) | 2026.08.10 |
|---|---|
| GJC 가재코드 소개 — 허예찬이 복잡성을 덜어내며 만든 코딩 에이전트 (0) | 2026.08.10 |
| Prime Agent와 ARC-AGI-3 — 모델보다 하네스가 중요한 이유 (0) | 2026.08.09 |
| ORCA 소개 — 코딩 에이전트를 병렬 운영하는 오픈소스 ADE (0) | 2026.08.09 |
| tmux 설치와 사용법 — 세션·창·패널 실전 가이드 (0) | 2026.08.09 |
