Oh My OpenCode 완벽 가이드: 작동원리·설치·핵심 기능·JSON 튜닝까지

오 마이 오픈코드 설치부터 실전 튜닝까지: AI 팀을 내 로컬에 고용하는 법

지난 글에서 OpenCode를 “강력한 엔진”으로 이해하셨다면, Oh My OpenCode(OMO)는 그 엔진 위에 얹는 자율주행 레이어에 가깝습니다. 단순히 기능을 몇 개 더하는 방식이 아니라, 개발 흐름을 “내가 직접 다 처리하는 방식”에서 “일을 지시하고 운영하는 방식”으로 바꿔 놓습니다. 그래서 OMO는 플러그인이라기보다, 내 작업 환경에 ‘팀’을 들이는 경험에 더 가깝습니다.

이 글은 설치는 해봤지만 “그래서 이걸로 뭘 해야 하지?”에서 멈춘 개발자분들을 위해, 작동 방식과 설치, 핵심 기능, 그리고 커스터마이징까지 한 번에 이어지는 실전 가이드로 구성했습니다.

1) 엔진만으로는 부족하다: 도구가 아니라 운영의 문제

AI 코딩이 막히는 순간은 대개 비슷합니다. 컨텍스트가 흔들리고, 길고 큰 작업은 중간에 끊기고, 문서 조사·테스트·리팩토링이 순차로 밀리면서 사람이 병목이 됩니다. 이 문제는 “더 똑똑한 모델 하나”로만 해결되지 않고, 작업을 운영하는 방식 자체를 바꿔야 풀리는 경우가 많습니다.

OMO는 바로 그 지점을 건드립니다. 역할을 나누고, 할 일을 쪼개고, 병렬로 처리하는 구조를 기본값으로 제공해 “사람이 붙어서 이어 붙이는 시간”을 줄이는 데 초점을 둡니다.

핵심을 정리하면 아래와 같습니다.

• 컨텍스트 유실로 인한 재설명 비용이 누적됩니다.
• 큰 작업은 “중간 멈춤”이 반복되며 흐름이 끊깁니다.
• 리서치·검증·테스트가 순차로 밀리면서 속도가 느려집니다.

Oh My Opencode 깃허브 바로가기

2) 작동 원리: 1인 개발자가 아니라 ‘팀’으로 일한다

OMO의 핵심은 “메인 에이전트가 PM처럼 일하고, 전문 에이전트들이 역할을 나눠 협업한다”는 오케스트레이션 구조입니다. 단일 에이전트에게 모든 걸 몰아주는 대신, 분석·탐색·문서·추론 같은 작업을 분리해 동시에 굴릴 수 있도록 설계돼 있습니다. 이 구조를 이해하면 OMO를 ‘기능 모음’이 아니라 ‘작업 방식’으로 받아들이게 됩니다.

Sisyphus(시시포스): PM/오케스트레이터

OMO의 기본 에이전트인 Planner-Sisyphus는 복잡한 작업을 단계로 쪼개고(Plan), 실행(Build)까지 이어가도록 구성됩니다. 즉, “어디까지 했지?”를 사람이 정리하기 전에, 에이전트가 스스로 계획을 만들고 다음 액션을 이어가도록 유도하는 역할입니다. 시시포스라는 이름처럼, 일이 끝날 때까지 멈추지 않는 완주 지향이 중심 철학입니다.

물론 모든 상황에서 무조건 자동화가 정답은 아닙니다. 다만 “사람이 결정을 기다리느라 멈추는 시간”을 줄여야 하는 구간에서는 이 구조가 특히 효과적입니다.

Specialists(전문가들): 역할별 멀티태스킹

OMO의 ‘팀 플레이’는 대표적으로 아래 역할들로 체감됩니다. 내가 리뷰를 하거나 방향을 잡는 동안, 다른 에이전트가 문서를 찾고 영향 범위를 훑고 테스트 전략을 세우는 식으로 병렬성이 만들어집니다. 즉, 속도의 핵심은 더 빠른 타이핑이 아니라 병렬로 움직이는 작업 분해에 있습니다.

• Librarian: 문서/코드 탐색과 맥락 회수
• Explore: 대규모 코드베이스에서 패턴·의존성·구조 탐색
• Oracle: 코드 설명, 질문 응답, 트러블슈팅

3) 설치 가이드: 실패 없는 3단계 셋업

설치는 복잡해 보이지만, 실제로는 “OpenCode 설치 → OMO 설치 → 인증 및 초기화” 세 단계로 정리됩니다. 아래는 그대로 따라 하실 수 있도록 명령어 중심으로 구성했습니다. 특히 /init을 건너뛰면 OMO가 프로젝트를 이해하는 기반이 약해지므로, 마지막 단계까지 한 번에 마무리하시는 게 좋습니다.

Step 0. 준비물

터미널 환경과 사용할 LLM 프로바이더(API 키 또는 연결 플로우)가 필요합니다. OpenCode는 터미널 기반 UX를 전제로 하므로, 개발 환경에서 터미널 사용이 익숙하시면 진행이 편합니다. 모델은 Claude/OpenAI/Gemini 중 무엇을 쓰든 상관없지만, 최소 한 가지는 연결돼 있어야 합니다.

Step 1. OpenCode 설치

공식 설치 스크립트는 아래 한 줄입니다.

curl -fsSL <https://opencode.ai/install> | bash

Step 2. Oh My OpenCode 설치

OMO는 bunx 기반 설치가 권장됩니다.

bunx oh-my-opencode install

Step 3. 실행 + 인증 연결 + 초기화

프로젝트 폴더로 이동해 OpenCode를 실행합니다.

cd your-project
opencode

그다음 TUI 안에서 /connect로 인증을 연결하고, /init으로 AGENTS.md를 생성합니다. AGENTS.md는 “이 프로젝트가 어떤 구조인지”를 OMO가 이해하는 기본 문서에 가까워서, 품질 차이를 만드는 구간입니다.

인증 과정에서 브라우저 리다이렉트가 꼬이는 경우가 있는데, 그럴 때는 안내되는 인증 페이지를 직접 열어 키를 복사·붙여넣는 방식이 가장 안정적인 편입니다.

4) 핵심 기능 Deep Dive: 이것만 알면 고수

OMO의 기능은 많지만, 초반에 체감이 크게 오는 건 몇 가지로 압축됩니다. ulw로 작업을 끝까지 밀어붙이는 경험을 만들고, 필요한 순간에 전문가를 호출하며, LSP/MCP 같은 보조 장치를 켜서 “토큰과 시간”을 아끼는 흐름이 기본 골자입니다. 이 세 가지가 잡히면, OMO는 ‘설치해둔 툴’이 아니라 ‘매일 쓰는 작업 루틴’으로 넘어갑니다.

① Ultrawork(ulw): “해줘”가 아니라 “끝내놔”

Ultrawork(또는 ulw)는 “중간 멈춤”을 줄이는 데 초점이 있습니다. 할 일 목록을 만들고, 실행하고, 에러가 나면 수정하고, 다시 진행하는 흐름을 스스로 이어가도록 유도합니다. 그래서 단순 요청이 아니라 “완료를 기준으로” 지시하는 느낌이 강합니다. 정리하면, ulw는 ‘진행’이 아니라 ‘완료’를 목표로 모드를 바꾸는 스위치입니다.

예시는 아래처럼 잡으시면 됩니다.

ulw: Vue 2 프로젝트를 Vue 3로 마이그레이션 해줘.
- 우선 영향 범위 분석
- 단계별 마이그레이션 플랜 작성
- 빌드/테스트 통과까지 반복해서 끝내줘

② 전문가 호출(@ 멘션): 필요한 사람만, 필요한 순간에

OMO는 @ 멘션을 통해 역할 에이전트를 불러 쓰는 흐름이 자연스럽습니다. 단일 에이전트에게 “다 해줘”라고 던지기보다, 작업을 분해한 뒤 가장 적합한 역할에게 맡기는 방식이 안정적입니다. 작업 품질은 ‘모델 선택’만큼이나 ‘역할 분해’에서 결정됩니다.

• @librarian: “최신 문서/권장 구현 패턴 찾아주세요.”
• @explore: “이 변경의 영향 범위를 빠르게 훑어주세요.”
• @oracle: “왜 이렇게 설계됐는지 설명하고 리팩토링 방향을 제안해 주세요.”

③ LSP & MCP: 보이지 않지만 생산성을 끌어올리는 장치

LSP(Language Server Protocol)는 코드의 의미를 이해하는 언어 서버 기반 분석에 가깝습니다. 필요할 때 필요한 오류만 뽑아내고, 전역 검사를 매번 반복하지 않도록 도와주는 식으로 비용을 줄이는 데 도움이 됩니다. MCP(Context Protocol)는 외부 지식 연결 통로로, 공식 문서나 검색을 에이전트가 더 잘 활용하도록 연결해 줍니다. 결국 LSP/MCP는 “더 많이 생성”이 아니라 “덜 낭비하고 더 정확히 접근”하도록 만드는 장치입니다.

5. [킬러] 나만의 OMO 만들기: JSON 커스터마이징(모델/비용 최적화)

OMO를 깊게 쓰는 순간부터는 설정 파일이 핵심이 됩니다. 위치는 두 가지로 정리됩니다. 프로젝트별 설정이 우선 적용되므로, 팀 단위로 운영하신다면 프로젝트 전용 파일부터 잡는 편이 깔끔합니다. 여기서부터 OMO는 ‘내 작업 스타일에 맞춘 도구’로 변합니다.

• 프로젝트 전용(우선): .opencode/oh-my-opencode.json
• 사용자 전역: ~/.config/opencode/oh-my-opencode.json

5-1. Brain vs Hands: 모델을 역할로 쪼개서 비용을 줄이기

실전에서는 “계획/아키텍처”는 강한 모델이, “탐색/문서/요약/반복 작업”은 빠르고 저렴한 모델이 유리한 경우가 많습니다. OMO는 에이전트별로 모델을 분리할 수 있어, 이런 역할 분리를 그대로 비용 구조로 연결할 수 있습니다. 즉, ‘똑똑한 모델을 덜 쓰는 방법’이 아니라 ‘똑똑한 모델을 써야 할 구간을 좁히는 방법’에 가깝습니다.

아래는 예시 형태입니다.

{
"agents": {
"planner-sisyphus": { "model": "anthropic/claude-sonnet-4-5" },

"librarian": { "model": "google/gemini-3-flash" },
"explore": { "model": "google/gemini-3-flash" },

"oracle": { "model": "openai/gpt-4.1" }
}
}

모델 ID는 환경과 프로바이더에 따라 달라질 수 있으니, 먼저 “내 환경에서 유효한 모델 목록”을 확인하고 적용하시는 게 안전합니다.

5-2. 다이어트 팁: 불필요한 Hook/MCP 끄기

작업 방식에 따라 훅이나 MCP가 오히려 소음이 될 때도 있습니다. 이럴 때는 필요 없는 항목을 꺼서 흐름을 단순하게 만들 수 있습니다. 세팅을 잘하면 OMO는 더 복잡해지는 게 아니라, 오히려 더 조용하고 집중하기 쉬운 도구가 됩니다.

{
"disabled_hooks": ["comment-checker", "agent-usage-reminder"],
"disabled_mcps": ["context7"]
}

5-3. LSP 세팅: 토큰/로그 폭주 줄이기

예를 들어 TS/JS에서 typescript-language-server를 우선으로 두는 식으로 구성할 수 있습니다. 프로젝트 규모가 커질수록 “전체를 매번 돌리는 방식”은 비용과 시간이 커지기 쉬워서, LSP로 필요한 범위를 좁히는 접근이 도움이 됩니다.

{
"lsp": {
"typescript-language-server": {
"command": ["typescript-language-server", "--stdio"],
"extensions": [".ts", ".tsx", ".js", ".jsx"],
"priority": 10
}
}
}

6. 트러블슈팅: 설치/초기화에서 가장 자주 막히는 지점

설치 자체보다, “버전/인증/모델 인식”에서 시간이 새는 경우가 많습니다. 특히 팀에서 여러 사람이 동시에 세팅할 때는, 여기서 편차가 생기기 쉽습니다. 아래 세 가지는 초반에 한 번만 점검해 두면 대부분의 삽질을 줄일 수 있습니다.

• OpenCode 버전 이슈가 있으면 config 동작이 꼬일 수 있으니, 가급적 최신 버전으로 맞추는 편이 안전합니다.
• /connect 인증 리다이렉트가 꼬이면, 안내되는 인증 페이지를 직접 열어 키를 복사·붙여넣는 방식이 안정적입니다.
• 모델 이름이 인식되지 않으면, 현재 환경에서 유효한 모델 ID 목록을 먼저 확인한 뒤 적용하세요.

7. 마무리: 도구에서 습관으로

OMO를 설치했다는 건 “플러그인을 깔았다”는 말로는 설명이 부족합니다. 실제로는 AI를 붙인 코딩이 아니라, AI와 함께 일하는 방식—즉 운영 프로세스를 들였다는 쪽에 가깝습니다. 결국 성능은 ‘무슨 모델을 쓰느냐’보다 ‘어떤 방식으로 일을 굴리느냐’에서 갈립니다.

처음에는 가볍게 시작하시는 게 좋습니다. 한 번에 큰 전환을 하기보다, 작은 작업 하나를 끝까지 밀어보고, 그 다음에 비용 최적화와 운영 규칙을 붙이는 흐름이 안정적입니다.

오늘 바로 해볼 Action Plan은 아래 3가지만 잡아도 충분합니다.

• 설치 후 프로젝트에서 opencode 실행 → /connect → /init까지 마무리하기
• ulw를 한 번 써서 “완료까지 가는 경험” 만들기
• .opencode/oh-my-opencode.json에서 에이전트별 모델 분리로 비용/속도 최적화하기

8. “AI 팀을 고용했는데, 이제 뭘 바꿔야 하죠?”

리트머스는 AI·바이브코딩 기반 실전 외주개발을 ‘도구 추천’이 아니라 운영 방식까지 포함한 실행형 설계로 풀어내는 팀입니다. 빠르게 만드는 것만이 아니라, 요구사항을 제품 단위로 정리하고(기획), 리스크를 줄이는 기준을 먼저 세운 뒤(프로세스), 개발·QA까지 한 흐름으로 밀어붙이는 방식으로 속도와 정확도를 동시에 맞춥니다. 지금 바로 리트머스에 문의해 보세요. 우리 프로젝트가 바이브코딩 외주에 적합한지 검토해드립니다.

그런데 여기서 한 가지가 더 남습니다. OMO 같은 도구를 붙이면 생산성이 확 올라가지만, 실제로 많은 팀이 다음 단계에서 막히는 지점이 있습니다. “어디까지 AI에게 맡기고, 어디서부터 사람 리뷰 게이트를 걸어야 안전한가?”, “레거시·대규모 작업을 ulw로 돌릴 때 실패 확률을 낮추는 운영 규칙은 무엇인가?” 같은 질문입니다.

함께 읽으면 좋은 글

에이전트 코딩을 '운영'하는 법: Cursor 공식 가이드 정리

위 글은 ‘에이전트를 잘 쓰는 팀’이 공통으로 지키는 작업 단위, 검증 루프, 컨텍스트 관리 방법을 더 구체적으로 정리해 둔 글입니다. 이번 글에서 다룬 OMO의 작동 방식과 튜닝을 실제 팀 프로세스에 연결할 때, 무엇을 표준으로 삼고 어떤 룰을 먼저 정해야 하는지 판단 기준을 잡는 데 도움이 됩니다. 읽고 나면 “도구 설치”에서 끝나지 않고, 우리 팀에 맞는 운영 패턴으로 정착시키는 다음 단계가 훨씬 선명해지실 거예요.

원하시면 리트머스가 현재 레포/스택/팀 규모를 기준으로 oh-my-opencode.json 가성비 세팅과 ulw 운영 룰(작업 범위, 리뷰 게이트, 훅 다이어트, 트러블슈팅 체크리스트)까지 묶어 “바로 적용 가능한 형태”로 정리해 드리겠습니다. 무료 견적 상담을 요청하시면 바로 안내드리겠습니다!