OpenCode 설치부터 Oh My OpenCode 다중 에이전트 확장까지 완벽 가이드

터미널에서 IDE급 AI 코딩을, 거기에 다중 에이전트 “AI 개발팀”까지 붙일 수 있다면… 솔직히 안 써볼 이유가 있을까요?

지난주 금요일 밤이었어요. 커피 한 잔 옆에 두고 NestJS 프로젝트 구조를 붙잡고 있었죠. 파일은 점점 늘어나고, TODO는 쌓이고… 솔직히 좀 막막했습니다. 그러다 우연히 OpenCode를 제대로 써보고, 거기에 Oh My OpenCode까지 얹어봤는데요. 뭐랄까, 진짜 “혼자 개발 → 팀 개발”로 순간이동한 느낌이었어요. 터미널 기반 AI 코딩 에이전트가 여기까지 올 줄은 몰랐죠. 오늘은 OpenCode가 정확히 뭘 하는 도구인지, 설치 방법부터 Oh My OpenCode로 다중 에이전트 팀처럼 확장하는 방법까지, 실제 워크플로우 중심으로 정리해볼게요.

목차

OpenCode란 무엇인가? OpenCode 설치 방법 총정리 LLM 연결 및 초기 설정 방법 Oh My OpenCode 개념과 에이전트 구조 Oh My OpenCode 설치 및 연동 방법 실전 워크플로우 예시: AI 개발팀처럼 일하기

OpenCode란 무엇인가?

OpenCode는 한마디로 말하면 터미널 기반 오픈소스 AI 코딩 에이전트입니다. MIT 라이선스로 공개되어 있고, GitHub에서 이미 수만 개의 스타를 받았죠. 단순한 코드 자동완성 도구가 아니라, “이 디렉터리 구조 리팩토링해줘”, “테스트 코드까지 같이 만들어줘”처럼 자연어 지시를 받아서 실제 파일을 수정하고, 구조를 바꾸고, 커밋 메시지까지 작성하는 에이전트형 워크플로우를 지원합니다.

저는 처음에 그냥 또 하나의 AI CLI겠지…라고 생각했는데요. 막상 써보니 TUI 기반 인터페이스에 LSP 연동까지 되어 있어서 코드 인텔리전스, 실시간 오류 진단, 파일 변경 감지 같은 IDE급 기능을 터미널에서 그대로 쓰는 느낌이었습니다. 게다가 OpenAI, Anthropic, Google Gemini, 심지어 로컬 LLM까지 API 키만 있으면 갈아끼울 수 있어요. 이게 진짜 매력 포인트입니다.

최근에는 OpenCode Desktop도 나와서 macOS, Windows, Linux에서 GUI 형태로도 사용할 수 있습니다. 하지만 개인적으로는 터미널 버전이 더 “에이전트스럽다”는 느낌이 강했어요.

OpenCode 설치 방법 총정리

OpenCode 설치는 생각보다 간단합니다. 공식 설치 스크립트를 쓰는 게 가장 편하고, OS별 패키지 매니저도 지원해요. 아래 표로 정리해봤습니다. 솔직히 저는 스크립트 방식이 제일 깔끔했어요.

운영체제	설치 방법	비고
공통 (macOS / Linux / Windows)	curl -fsSL https://opencode.ai/install | bash	가장 권장되는 공식 방법
macOS / Linux	brew install opencode	Homebrew 사용 시 편리
Windows	choco / scoop / mise 지원	설치 후 PATH 자동 등록

설치 후에는 opencode --version으로 정상 설치 여부를 확인하세요. 이거 안 하고 바로 쓰다가 경로 문제로 한 번 삽질했습니다… 저만 그런 거 아니죠?

LLM 연결 및 초기 설정 방법

설치가 끝났다면 이제 진짜 중요한 단계, LLM 프로바이더 연결입니다. 최소 하나의 API 키는 설정해야 OpenCode가 제대로 동작합니다. 과정은 꽤 직관적이에요.

1. 프로젝트 루트 디렉터리로 이동
2. opencode init 실행
3. 사용할 모델 프로바이더 선택 (OpenAI, Anthropic, Google 등)
4. API 키 입력 후 설정 파일 자동 생성

일반적으로 OPENAI_API_KEY 같은 환경변수와 .opencode/config.json 파일이 생성됩니다.

설정이 끝났다면 이제 opencode만 입력해도 TUI 세션이 시작됩니다. 여기서부터 진짜 “AI 코딩 에이전트”의 세계가 열립니다.

Oh My OpenCode 개념과 에이전트 구조

Oh My OpenCode는 OpenCode 위에서 동작하는 확장 플러그인입니다. 쉽게 말해, 단일 AI 코딩 에이전트를 다중 에이전트 “AI 개발팀” 구조로 확장해주는 도구예요. 메인 오케스트레이터가 작업을 여러 서브 에이전트에게 나눠주고, 병렬 실행하고, 실패하면 전략을 바꿔 재시도하는 구조입니다.

기본 OpenCode가 “읽고 분석하고 수정하는” 에이전트라면, Oh My OpenCode는 그 위에서 설계자, 리뷰어, 리서처, 실행 담당을 각각 분리해 실제 팀처럼 역할을 나눕니다. 복잡한 리팩토링이나 대규모 구조 개편, 문서 생성, 테스트 병렬 실행 같은 장기 태스크에서 진짜 빛을 발해요.

특히 Sisyphus, Oracle, Librarian 같은 에이전트가 각자 역할을 맡아 움직이는 구조는, 혼자 개발하는데도 팀과 일하는 느낌을 줍니다. 이건 써봐야 압니다… 진짜로요.

Oh My OpenCode 설치 및 연동 방법

전제 조건은 간단합니다. OpenCode CLI가 이미 설치되어 있고, 최소 한 개 이상의 LLM 프로바이더가 설정되어 있어야 합니다. 그리고 Node.js/npm 환경이 필요합니다.

설치 방식	명령 예시	특징
GitHub 직접 클론	git clone ... + npm install	공식 퀵스타트 방식
bunx 단일 명령	bunx oh-my-opencode install	간편 설치
에이전트에게 위임	opencode "ultrawork 모드로 설치"	자동 설정 병합

설치 스크립트는 OpenCode 설정 파일과 플러그인 구성을 자동으로 병합해줍니다. 그래서 수동으로 설정 파일을 건드릴 일이 거의 없어요. 이게 생각보다 큰 장점입니다. 설정 꼬이면 진짜 멘붕 오거든요…

실전 워크플로우 예시: AI 개발팀처럼 일하기

이제 진짜 재미있는 부분입니다. OpenCode + Oh My OpenCode 조합으로 어떻게 일하느냐. 저는 보통 이런 식으로 지시합니다.

• “현재 코드베이스 분석하고 TODO 리스트 작성해줘.”
• “Oracle이 아키텍처 리뷰하고 개선안 설계해.”
• “Sisyphus가 작업 분할하고 병렬 실행해.”
• “테스트 실패하면 전략 바꿔서 재시도.”

이 과정에서 백그라운드 에이전트들이 테스트, 빌드, 문서 생성까지 동시에 처리합니다. 저는 예전에 하루 걸리던 리팩토링을 반나절 안에 끝낸 적도 있어요. 물론 100% 완벽하진 않지만, 초안과 구조를 잡아주는 속도는 압도적입니다.

요약하자면, OpenCode는 “AI 코딩 어시스턴트”, Oh My OpenCode는 “AI 개발팀 매니저”입니다. 혼자 일하지만, 혼자가 아닌 느낌. 이게 가장 큰 차이예요.

OpenCode & Oh My OpenCode 자주 묻는 질문

OpenCode는 완전히 무료인가요?

OpenCode 자체는 MIT 라이선스 기반의 오픈소스라 무료로 사용할 수 있습니다. 다만 연결하는 LLM 프로바이더(OpenAI, Anthropic, Google 등)는 API 사용량에 따라 비용이 발생합니다. 즉, 도구는 무료지만 모델 사용 비용은 별도라고 이해하면 됩니다.

로컬 LLM도 연결할 수 있나요?

가능합니다. OpenCode는 다양한 모델 프로바이더를 유연하게 연결할 수 있도록 설계되어 있어, 로컬 LLM 서버와도 연동할 수 있습니다. 다만 성능과 응답 속도는 사용하는 모델과 하드웨어 사양에 크게 좌우됩니다.

OpenCode Desktop과 CLI 버전의 차이는 무엇인가요?

CLI 버전은 터미널 중심의 에이전트형 워크플로우에 최적화되어 있고, Desktop은 GUI 환경에서 보다 직관적인 사용을 지원합니다. 기능적으로는 유사하지만, 개발 스타일에 따라 선호도가 갈립니다. 터미널 기반 자동화에 익숙하다면 CLI가 더 강력하게 느껴질 수 있습니다.

Oh My OpenCode는 반드시 설치해야 하나요?

필수는 아닙니다. 소규모 프로젝트나 단순 리팩토링 정도라면 기본 OpenCode만으로도 충분합니다. 하지만 복잡한 아키텍처 변경이나 대규모 코드베이스 관리, 장시간 병렬 작업이 필요하다면 Oh My OpenCode의 다중 에이전트 구조가 큰 도움이 됩니다.

실무 프로젝트에 바로 적용해도 괜찮을까요?

가능은 하지만, 반드시 코드 리뷰와 테스트 과정을 병행해야 합니다. AI 에이전트가 구조를 빠르게 잡아주긴 하지만, 비즈니스 로직의 세부 맥락까지 완벽히 이해하는 것은 아닙니다. 특히 보안, 인증, 결제 관련 코드는 사람이 최종 검증하는 것이 안전합니다.

어떤 개발 스택에서 가장 효과적인가요?

Python(FastAPI), NestJS, Spring, React, Node 기반 프로젝트 등 구조가 명확한 프레임워크에서 특히 강점을 보입니다. LSP 기반 분석이 가능하고 파일 구조가 일정할수록 에이전트의 이해도가 높아집니다. 다만 언어 자체보다는 프로젝트의 복잡도와 코드 품질이 더 중요한 변수입니다.

정리해보면, OpenCode는 터미널에서 동작하는 강력한 오픈소스 AI 코딩 에이전트이고, Oh My OpenCode는 그 위에 “AI 개발팀”을 얹어주는 확장 레이어라고 볼 수 있습니다. 혼자 코드 짜다가 구조 꼬이고, 리팩토링 미루고, 테스트 귀찮아서 뒤로 밀어본 적… 다들 한 번쯤 있잖아요. 저도 그랬구요. 그런데 에이전트에게 역할을 나눠주고, 병렬로 일하게 하고, 실패하면 전략을 바꿔 재시도하게 만드는 경험은 생각보다 꽤 혁신적이었습니다.

물론 모든 걸 100% 맡길 수는 없습니다. 중요한 비즈니스 로직이나 보안 관련 코드는 반드시 사람이 최종 검토해야 하죠. 하지만 초안 작성, 구조 설계, TODO 분해, 테스트 코드 생성 같은 영역에서는 생산성이 확실히 올라갑니다. 특히 OpenCode 설치부터 LLM 연결, Oh My OpenCode 다중 에이전트 구성까지 한 번 세팅해두면, 이후 개발 속도가 체감될 정도로 빨라집니다.

혹시 지금 사용하는 스택이 있다면(예: Python/FastAPI, NestJS, Spring, K8s 등), 그 조합에 맞는 OpenCode 프롬프트 패턴이나 Oh My OpenCode 워크플로우를 더 구체적으로 구성해보는 것도 좋겠습니다. 댓글로 남겨주시면, 실제 실무에 바로 쓸 수 있는 형태로 정리해볼게요.