OpenCode는 여러 모델 공급자와 워크플로를 붙일 수 있는 오픈소스 터미널 AI 코딩 에이전트입니다. 여기에 oh-my-opencode를 얹으면 역할 분리, 자동 도구 연결, 코드베이스 탐색 루틴까지 한 번에 챙길 수 있어서 “무료에 가까운 실전 작업 환경”을 만들기 좋습니다.
평소에 터미널에서 코드 작업을 많이 하는데, 올해 초에 OpenCode + oh-my-opencode 조합으로 글을 한번 썼어요. 그 글이 170회 넘게 조회되면서 꽤 효자 노릇을 했는데요.
근데 3개월 사이에 양쪽 다 많이 바뀌었어요.
- OpenCode — 최근 changelog 기준으로 데스크톱 UX, Copilot 계열 모델 지원, 세션 공유/관리 경험이 계속 보강되는 중
- oh-my-opencode — 설치 흐름, 에이전트 오케스트레이션, 설정 문서가 빠르게 다듬어지는 중
- Claude Code — 팀/플러그인/스킬 문서가 계속 정리되면서 팀 작업 기준점 역할을 하는 중
특히 팀 단위 작업을 어떻게 굴릴지라는 질문에서는 OpenCode 진영과 Claude Code 진영을 같이 보는 게 훨씬 도움이 됩니다.
그래서 이번 글은 설치 가이드를 리프레시하면서, OpenCode 진영이 지금 어디까지 왔는지와 팀 작업 관점에서 뭘 기대할 수 있는지를 한 번에 정리합니다.
누구를 위한 글인가?
– OpenCode를 이미 쓰고 있는데 최신 업데이트를 놓친 분
– Claude Code가 비싸서 오픈소스 대안을 찾고 있는 분
– Claude Code류 팀 작업 흐름이 궁금한데 OpenCode 쪽에서 어디까지 따라갈 수 있는지 궁금한 분
– 터미널 기반 AI 코딩 에이전트를 처음 써보려는 분
🆕 2026년 3월 기준 — 뭐가 달라졌나?
OpenCode 쪽에서 지금 눈여겨볼 변화
| 변경 사항 | 설명 |
|---|---|
| 데스크톱 UX 보강 | 공식 changelog 기준으로 앱 쪽 스크롤, 루프, 세션 표시 같은 UX가 계속 보강되고 있음 |
| 세션 공유/분기 | share 문서 기준으로 세션 URL 공유와 공개 범위 제어가 가능 |
| Copilot 계열 지원 확장 | changelog 기준으로 Copilot GPT 계열 지원이 계속 붙고 있어 기존 구독 재활용 가치가 큼 |
| 워크플로 자동화 | GitHub나 외부 스크립트와 붙여서 팀 작업 흐름으로 확장하기 쉬움 |
oh-my-opencode 쪽에서 지금 강한 포인트
| 변경 사항 | 설명 |
|---|---|
| 설치 진입장벽 낮음 | README 기준으로 bunx나 npx 한 줄부터 시작 가능 |
| 오케스트레이션 지향 | 단순 보조도구보다 “에이전트 하네스” 성격이 강함 |
| 설정 자유도 높음 | 프로젝트/유저 단위 설정 파일과 JSONC 지원으로 튜닝 폭이 넓음 |
| 내장 스킬/도구 확장성 | MCP, git, 브라우저 자동화 등 작업단 확장이 쉬움 |
비교 기준으로 볼 Claude Code 쪽 강점
| 기능 | 설명 |
|---|---|
| 플러그인/스킬 문서 정리 | 팀 공통 워크플로를 설명하고 배포하기 좋음 |
| 팀 정책/권한 설명 | 누가 어떤 수준까지 실행할지 정하기 쉬움 |
| 도구 생태계 | 팀 사용 규칙과 확장 포인트가 문서화돼 있음 |
1. OpenCode 설치 (2026.03 최신)
macOS (Homebrew)
brew install opencode
npm
npm install -g opencode
curl (직접 설치)
curl -fsSL <https://opencode.dev/install.sh> | sh
Windows (Scoop)
scoop install opencode
업그레이드 (기존 사용자)
opencode upgrade
설치 확인:
opencode --version
# 설치 후 버전이 정상적으로 찍히면 OK
💡 Tip: 릴리즈 주기가 빠른 편이라(3월에만 2번), 가끔
opencode upgrade한번 해주면 좋아요.
단, 안정성이 걱정되면 자동 업데이트를 Off 해놓는 것도 방법.
2. oh-my-opencode 설치
oh-my-opencode는 OpenCode 위에 얹는 “배터리 포함” 오케스트레이션 플러그인이에요.
Bun (권장)
bunx oh-my-opencode install
npm
npx oh-my-opencode install
설치하면 OpenCode에 자동으로 연결됩니다.
oh-my-opencode란?
OpenCode 전용 플러그인으로, Claude Code의 서브에이전트·MCP·LSP 기능을 오픈소스 환경에서 구현한 오케스트레이션 레이어입니다. 멀티모델(Claude, GPT, Gemini, Kimi 등)을 동시에 활용하면서 역할별 에이전트를 자동으로 배분합니다.
3. API 키 설정 — ⚠️ Anthropic OAuth 밴 주의
🚨 여전히 유효한 경고
Anthropic이 서드파티 OAuth 접근을 차단하는 정책은 2026년 3월 현재도 유지되고 있어요.
Claude 계정(구독)을 OAuth로 연결하면 계정 정지 위험이 있습니다.
대신 이렇게 설정하세요:
권장 1: Gemini API (무료 티어 있음)
export GEMINI_API_KEY="your-api-key"
권장 2: OpenAI API
export OPENAI_API_KEY="your-api-key"
권장 3: Claude API 키 (OAuth 아님!)
export ANTHROPIC_API_KEY="your-api-key"
⚠️
ANTHROPIC_API_KEY(API 콘솔에서 발급)는 OK.
❌ Claude 구독 계정 OAuth 로그인은 밴 위험.
이 차이를 꼭 구분하세요.
권장 4: GitHub Copilot 연동 (NEW!)
기존 Copilot 구독이 있다면 OpenCode와 연동 가능:
opencode --provider copilot
Copilot 사용량 한도 내에서 OpenCode의 고급 도구(LSP, MCP, 에이전트)를 그대로 쓸 수 있어요. 추가 API 비용 없이요.
설정 파일
위치: ~/.config/opencode/opencode.json
{
"provider": "gemini",
"model": "gemini-2.5-flash"
}
4. oh-my-opencode 내장 에이전트 — 2026 업데이트
oh-my-opencode의 핵심은 역할별 에이전트 자동 배분이에요.
| 에이전트 | 역할 | 추천 모델 | 용도 |
|---|---|---|---|
| Librarian | 관련 파일 찾기 | Flash 모델 | 코드베이스 탐색 |
| Scratchpad | 메모 & 계획 | Flash 모델 | Plan Mode |
| Think | 깊은 사고 | o1/o3/Gemini-thinking | 복잡한 로직 설계 |
| Guru | 코드 리뷰 | Opus/Pro 모델 | 품질 검증 |
| Research | 웹 검색 리서치 | Pro 모델 | 최신 라이브러리 정보 |
| Explore | 탐색적 분석 | Sonnet 모델 | 리팩토링 방향 탐색 |
| Oracle | 최종 결정 | Opus/Pro 모델 | 아키텍처 판단 |
내장 MCP (자동 활성화)
| MCP | 기능 |
|---|---|
| context7 | 라이브러리 공식 문서 자동 참조 |
| websearch_exa | Exa AI 기반 웹 검색 |
| grep_app | GitHub 코드 검색 |
내장 훅
| 훅 | 기능 |
|---|---|
todo-continuation-enforcer |
TODO 목록 자동 관리 |
context-window-monitor |
컨텍스트 윈도우 모니터링 |
session-recovery |
세션 자동 복구 |
comment-checker |
코드 주석 체크 |
preemptive-compaction |
토큰 초과 전 자동 압축 |
5. Claude Code 2.0 팀모드 vs OpenCode — 핵심 비교
여기가 이번 업데이트 글의 핵심이에요.
Claude Code 2.0이 “Agent Teams” 모드를 내놓으면서, 팀 단위 코딩 워크플로우의 기준이 확 올라갔어요. 그래서 OpenCode + oh-my-opencode로 비슷하게 쓸 수 있는지, 뭐가 다른지 정리해봤어요.
기능 비교표
| 항목 | Claude Code 2.0 (Agent Teams) | OpenCode + oh-my-opencode |
|---|---|---|
| 가격 | Max 플랜 $100/월 또는 API | 무료 (API 비용만) |
| 모델 | Claude만 | 75개+ (Claude, GPT, Gemini, Kimi 등) |
| 팀 모드 | ✅ Agent Teams (Team Lead + Teammates) | ⚠️ 멀티세션 병렬 실행 (수동 조율) |
| 에이전트 간 메시징 | ✅ Inbox 시스템 | ❌ 없음 (세션 간 공유 불가) |
| 공유 태스크 리스트 | ✅ pending/in-progress/completed | ❌ 없음 |
| 멀티에이전트 코드 리뷰 | ✅ 역할별 리뷰 분담 | ⚠️ Guru 에이전트 단일 리뷰 |
| Split Panes | ✅ tmux/iTerm2 통합 | ⚠️ 수동 tmux 세팅 필요 |
| 서브에이전트 | ✅ | ✅ (oh-my-opencode) |
| MCP 지원 | ✅ | ✅ (context7, Exa, grep) |
| LSP 통합 | ⚠️ 제한적 | ✅ 풍부 (커스텀 LSP 추가 가능) |
| Plan Mode | ✅ | ✅ Scratchpad 에이전트 |
| Debug Mode | ✅ | ✅ (API 요청/FS 작업/LSP 로그) |
| 오픈소스 | ❌ | ✅ |
| GitHub Actions 연동 | ❌ | ✅ (/opencode 또는 /oc 멘션) |
| 세션 공유 링크 | ❌ | ✅ (팀원에게 세션 링크 공유) |
| 데스크톱 앱 | ❌ (터미널만) | ✅ (macOS/Windows/Linux) |
| 프로바이더 락인 | Anthropic만 | 없음 (75개+ 프로바이더) |
내 판단 — 어떤 상황에서 어떤 걸 쓸까
| 상황 | 추천 | 이유 |
|---|---|---|
| 혼자 코딩, 비용 절감 중요 | OpenCode + oh-my-opencode | 무료, 모델 자유, LSP 강점 |
| 2~3명 팀, 병렬 작업 필요 | Claude Code 2.0 Agent Teams | 팀 모드 네이티브, 조율 자동화 |
| Claude 모델만 쓸 예정 | Claude Code 2.0 | 자체 생태계 최적화 |
| 다양한 모델 실험·비교 | OpenCode | 75개+ 프로바이더 |
| GitHub Actions CI/CD 연동 | OpenCode | /opencode 멘션으로 자동 실행 |
| 세션 공유·협업 | OpenCode | sharable links |
| 데스크톱 GUI 원함 | OpenCode | 데스크톱 앱 있음 |
| 최고 품질 에이전트 조율 | Claude Code 2.0 | Agent Teams 완성도 높음 |
솔직히 Claude Code 2.0의 Agent Teams는 조율 자동화가 진짜 잘 되어 있어요. Team Lead가 작업을 쪼개서 Teammates에게 할당하고, 결과를 종합하는 과정이 매끄러워요.
반면 OpenCode는 멀티세션을 병렬로 돌릴 수 있지만, 세션 간 통신이나 공유 태스크 리스트가 없어서 사람이 직접 조율해야 해요. 이 부분은 아직 갭이 있어요.
그런데 비용, 모델 자유도, GitHub 연동, 세션 공유 쪽은 OpenCode가 확실히 앞서요.
결국 “팀 모드 자동 조율이 얼마나 중요한가”가 선택의 핵심 기준이에요.
6. 실습 — OpenCode + oh-my-opencode 기본 워크플로우
기본 실행
cd my-project
opencode
모델 선택
opencode --model gemini-2.5-flash
opencode --model gpt-4o
opencode --model claude-sonnet-4
Plan Mode 실습 (Scratchpad 에이전트 활용)
프로젝트에서 OpenCode를 실행한 뒤:
> 이 프로젝트에 인증 시스템을 추가하고 싶어.
> 먼저 계획을 세워줘. (Plan Mode)
Scratchpad 에이전트가 아키텍처 계획을 작성하고, Librarian이 관련 파일을 찾고, Think 에이전트가 로직을 설계하는 과정이 자동으로 돌아가요.
Debug Mode 실습
> 이 API 엔드포인트가 500 에러를 반환해. 디버깅해줘.
Debug Mode에서는 API 요청/응답, 파일 시스템 작업, LSP 통신 로그를 실시간으로 확인할 수 있어요.
GitHub Actions 연동 (팀 워크플로우)
GitHub 이슈나 PR 댓글에 /opencode 또는 /oc를 멘션하면:
/opencode 이 이슈의 원인을 분석하고 수정 PR을 올려줘
GitHub Actions 러너에서 OpenCode가 자동으로 실행됩니다. 이슈 분석 → 브랜치 생성 → 코드 수정 → PR 제출까지 자동화할 수 있어요.
세션 공유 (팀 협업)
opencode share
팀원에게 세션 링크를 보내면, 대화 히스토리와 코드 변경 내역을 그대로 볼 수 있어요. 페어 프로그래밍이나 코드 리뷰 때 유용합니다.
7. 설정 커스터마이징
설정 파일 위치
~/.config/opencode/opencode.json # OpenCode 기본
~/.config/opencode/oh-my-opencode.json # oh-my-opencode
훅 비활성화
{
"disabled_hooks": ["comment-checker", "agent-usage-reminder"]
}
MCP 비활성화
{
"disabled_mcps": ["context7", "websearch_exa", "grep_app"]
}
LSP 서버 추가 (커스텀)
{
"lsp": {
"typescript-language-server": {
"command": ["typescript-language-server", "--stdio"],
"extensions": [".ts", ".tsx"],
"priority": 10
},
"pyright": {
"command": ["pyright-langserver", "--stdio"],
"extensions": [".py"],
"priority": 10
}
}
}
실험적 기능
{
"experimental": {
"preemptive_compaction_threshold": 0.85,
"truncate_all_tool_outputs": true,
"auto_resume": true
}
}
8. 주의사항 정리
| # | 주의사항 | 대응 방법 |
|---|---|---|
| 1 | 🚨 Anthropic OAuth 밴 위험 | Claude API 키 사용. OAuth 연결 금지 |
| 2 | 💰 API 비용 발생 | Gemini 무료 티어 또는 Copilot 연동 활용 |
| 3 | 🔧 초기 설정 필요 | Claude Code보다 세팅에 시간이 좀 더 걸림 |
| 4 | ⚡ 업데이트 빈번 | 안정성 우선이면 자동 업데이트 Off |
| 5 | 🤝 팀 모드 갭 | Agent Teams 같은 자동 조율은 아직 없음 |
FAQ
Q1. OpenCode와 Claude Code 중에 뭘 써야 하나요?
A: 혼자 코딩하면서 비용 절감이 중요하다면 OpenCode, 팀 단위 병렬 작업과 자동 조율이 필요하다면 Claude Code 2.0 Agent Teams가 낫습니다. 다양한 모델을 실험하고 싶다면 OpenCode가 75개+ 프로바이더를 지원해서 더 유리합니다.
Q2. oh-my-opencode 없이 OpenCode만 써도 되나요?
A: 네. OpenCode 자체만으로도 기본적인 AI 코딩 에이전트로 동작합니다. 다만 서브에이전트(Librarian, Guru 등), 자동 MCP 설정, preemptive compaction 같은 고급 기능은 oh-my-opencode가 있어야 됩니다.
Q3. Claude API 키는 괜찮은데 OAuth는 왜 안 되나요?
A: Anthropic이 서드파티 앱에서 Claude 구독 계정(OAuth)으로 접근하는 것을 ToS 위반으로 판단하고 있습니다. API 콘솔에서 발급받은 API 키(ANTHROPIC_API_KEY)는 정상 사용 가능합니다.
Q4. GitHub Copilot + OpenCode 조합은 어떤가요?
A: 기존 Copilot 구독이 있다면 추가 API 비용 없이 OpenCode의 고급 도구(LSP, MCP, 에이전트 시스템)를 쓸 수 있어서 가성비가 좋습니다. 다만 Copilot 사용량 한도 내에서 동작합니다.
Q5. 팀 단위 에이전트 워크플로는 왜 비용이 빨리 늘어나나요?
A: Agent Teams는 단일 세션 대비 토큰 소모가 상당히 많습니다. Team Lead + Teammates가 각각 별도 컨텍스트를 유지하기 때문에, 복잡한 작업에서는 단일 세션의 3~5배까지 비용이 올라갈 수 있습니다.
Q6. OpenCode 데스크톱 앱과 터미널 TUI 차이가 있나요?
A: 핵심 기능은 동일합니다. 데스크톱 앱은 모델 선택 저장, 사이드바 세션 관리, 추론 요약 접기/펼치기 같은 GUI 편의 기능이 추가되어 있습니다. 터미널 파워유저라면 TUI, GUI를 선호하면 데스크톱 앱을 쓰면 됩니다.
Q7. OpenCode에서 Claude Code 쪽 팀 워크플로 비슷하게 갈 수 있나요?
A: 직접적인 Agent Teams 기능은 아직 없습니다. 다만 멀티세션 병렬 실행 + 세션 공유 링크 + GitHub Actions /opencode 멘션을 조합하면 팀 워크플로우를 구성할 수 있습니다. 세션 간 자동 메시징이나 공유 태스크 리스트는 지원하지 않으므로, 수동 조율이 필요합니다.
결론 — 2026년 3월 시점의 판단
3개월 전에 이 글을 처음 쓸 때만 해도 OpenCode + oh-my-opencode는 “무료 Claude Code 대안” 정도였어요.
근데 지금은 상황이 좀 달라졌어요.
- OpenCode 쪽: 데스크톱 앱, GitHub Copilot 연동, GitHub Actions 통합까지 나오면서 팀 워크플로우 도구로 진화 중
- Claude Code 쪽: Agent Teams 모드로 멀티에이전트 자동 조율의 기준을 확 올림
둘 다 각자의 방향으로 빠르게 달리고 있어요.
내가 선택하는 기준은 이래요:
| 기준 | 내 선택 |
|---|---|
| 혼자 코딩 + 비용 민감 | OpenCode + oh-my-opencode |
| 팀 프로젝트 + 자동 조율 필요 | Claude Code 계열 |
| 다양한 모델 실험 | OpenCode |
| 이미 Copilot 구독 있음 | OpenCode + Copilot 연동 |
한 줄로 줄이면:
“혼자 쓰면 OpenCode, 팀 조율이 중요하면 Claude Code 계열, 둘 다 섞으면 운영 폭이 가장 넓다”
다음에 읽을 글
- 30일 써본 Cursor·Windsurf·Claude Code: 역할 나누기와 월 비용
- ClawTeam 운영비 공개 2026 — git worktree·tmux·LLM 팀을 실제로 굴리면 어디서 비용 터지나
- A2A 프로토콜 튜토리얼 2026 — AI 에이전트끼리 붙이면 어디서 막히고 어떻게 넘기나
🔗 참고 링크
- OpenCode 공식
- OpenCode GitHub
- OpenCode Changelog
- oh-my-opencode GitHub
- oh-my-opencode npm
- Claude Code Skills 문서
- Claude Code Plugins 문서
- Gemini API (무료 티어)
⚠️ 면책 조항: 이 글은 2026년 3월 19일 기준 정보입니다. OpenCode와 oh-my-opencode는 업데이트가 빠르므로 최신 버전은 공식 사이트를 확인하세요. Anthropic OAuth 정책은 변경될 수 있습니다.