OpenCode 1과 2 차이와 업그레이드하는 법 — 'OpenCode 3'의 정체까지

오픈소스 코딩 에이전트 오픈코드(OpenCode)가 내부를 처음부터 다시 쓴 버전 2를 9월에 정식 출시했어요. 저는 명령어는 그대로인데 플러그인과 일부 기능이 바뀌어서, 무작정 올리면 곤란해지는 사람이 꽤 있을 거라고 봐요. 이 글에서는 1과 2의 차이, 올려도 되는 경우와 아닌 경우, 설치 방법, 그리고 'OpenCode 3'의 정체를 2026년 10월 공식 문서 기준으로 정리해요.

OpenCode가 처음이라면 OpenCode 소개 글부터 보면 좋아요.

OpenCode 3은 나왔나요?

아니요. 2026년 10월 8일 기준으로 공식 OpenCode 3은 없어요. 공식 npm 패키지 @opencode/cli에도 3으로 시작하는 버전은 없고, 최신은 2.0.25예요.

"OpenCode v3"로 검색하면 나오는 건 대부분 다른 프로젝트예요.

Oh My OpenCode v3에서 무엇이 바뀌었는지는 Oh My OpenCode v3.0~v3.5 정리에 있어요. 결국 지금 고를 수 있는 공식 버전은 1과 2 둘뿐이에요.

OpenCode 1과 2는 무엇이 다른가요?

공식 V1 이전 가이드는 일부러 호환을 끊은 부분(breaking change)을 세 가지로 꼽아요. 플러그인 API, 서버 API, 터미널 설정 파일이에요. 체감되는 차이까지 합치면 이래요.

가장 크게 체감되는 건 실행 방식이에요. V2에서 opencode를 켜면 내 계정용 백그라운드 서버를 찾거나 새로 띄워요. 터미널, 웹 화면, 스크립트가 모두 이 서버에 붙어요. 그래서 터미널을 닫아도 세션은 서버에서 계속 돌아요.

MCP(Model Context Protocol, 외부 도구를 AI에 연결하는 표준) 쪽도 달라졌어요. 코드 모드(Code Mode)는 모델이 짧은 자바스크립트를 써서 여러 도구를 한 번에 부르는 방식이에요. 중간 결과가 대화 맥락에 쌓이지 않아서, MCP 서버를 여러 개 붙여도 부담이 덜해요.

다행히 설정 파일 위치는 같아요. opencode.json과 .opencode/ 안의 에이전트, 명령, 스킬은 V1 형식 그대로 읽어요.

지금 OpenCode 2로 업그레이드해도 될까요?

저는 기준을 하나만 두면 된다고 봐요. V1 플러그인 없이 일이 되는가예요.

V1 플러그인은 V2에서 돌아가지 않아요. 파일을 옮기거나 설정 이름을 바꾸는 것만으로는 안 되고, 새 API로 다시 써야 해요. 대표적인 예가 oh-my-openagent(옛 Oh My OpenCode)예요. 9월 26일에 나온 v5.0.0 릴리스 노트는 OpenCode v2 대응은 준비 중이라고만 적었어요. 그동안은 OpenCode 밖에서 도는 자체 실행판(OmO Native)을 권해요. 이 플러그인을 OpenCode 안에서 쓰고 있다면 지금은 V1에 남는 게 안전해요.

플러그인을 안 써도, 아래 기능에 기대고 있다면 먼저 확인하세요. 모두 V2 공식 문서에 적힌 내용이에요.

• LSP(언어 서버, 편집기처럼 코드 오류를 잡아 주는 기능): 설정은 받아도 실행하지 않아요. 대신 린트나 타입 체크 명령으로 바꾸라고 안내해요.
• CLAUDE.md: V2는 AGENTS.md만 읽어요. 클로드 코드(Claude Code)와 같이 쓰던 규칙 파일은 옮겨야 해요.
• 세션 공유: V2는 아직 세션 공유를 지원하지 않아요.
• 에이전트별 temperature: 값은 보존하지만 아직 모델 요청에 보내지 않아요. 모델 변형(variant)에 넣으라고 안내해요.

반대로 이런 경우라면 V2로 가는 편이 나아요.

• 이제 막 OpenCode를 쓰기 시작한다. 새로 추가된 기능 대부분이 V2에만 있어요.
• MCP 서버를 여러 개 붙여 쓴다. 코드 모드가 기본으로 켜져 있어요.
• 긴 작업을 걸어 두고 터미널을 닫고 싶다. 백그라운드 서버와 백그라운드 서브에이전트가 이 용도예요.

OpenCode 2는 어떻게 설치하고 확인하나요?

주의할 점부터 볼게요. 두 버전은 같은 opencode 명령을 써서 나란히 설치되지 않아요. 패키지 매니저로 V1을 깔았다면 먼저 지우라고 공식 문서가 안내해요.

예전 설치 명령 curl -fsSL https://opencode.ai/install | bash는 지금도 V1을 깔아요. 제가 스크립트를 열어 보니 GitHub의 최신 릴리스를 받는데, GitHub 릴리스에는 V1만 올라와 있어요. V2는 아래 명령 중 하나로 설치해요.

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

npm install -g @opencode/cli

brew install anomalyco/tap/opencode-v2

설치한 뒤에는 어떤 opencode가 실행되는지부터 확인하세요. V1이 PATH 앞쪽에 남아 있으면 V2 안내가 전부 틀린 것처럼 보여요.

which opencode
opencode --version

opencode v2.0.25처럼 2로 시작하면 돼요. npm 설치와 버전 확인은 제가 10월 8일에 직접 돌려 봤어요. curl과 Homebrew 명령은 공식 문서에서 그대로 옮겼어요.

API 키를 셸 환경 변수로 넘기던 분은 하나를 더 챙기세요. V2에서는 내 셸이 아니라 백그라운드 서버가 키를 읽어요. 서버가 이미 떠 있으면 셸에서 새로 넣은 값은 보이지 않아요. 그럴 땐 서버 설정에 직접 넣고 다시 시작하세요.

opencode service set env ANTHROPIC_API_KEY "$ANTHROPIC_API_KEY"
opencode service start

이 두 명령은 도움말로 형식만 확인했고, 실제 키로 돌려 보지는 않았어요.

설정 파일은 그대로 둬도 돼요. 공식 문서는 원하면 OpenCode에게 직접 V2 형식으로 옮겨 달라고 시키라고 권해요. 다만 V2 형식으로 바꾼 파일을 V1에서 다시 쓰지는 마세요. 두 버전이 같은 위치의 설정을 읽어요.

자주 묻는 질문

OpenCode 1은 계속 업데이트되나요?

지금은 그래요. 1.18 버전대가 V2와 나란히 계속 나오고 있어요. 제가 찾은 공식 문서에는 V1 지원 종료 일정이 아직 없어요.

OpenCode 2 릴리스 노트는 어디서 보나요?

GitHub 릴리스 페이지에는 V1만 보여요. V2는 GitHub 저장소에 버전 태그만 올리고 있어요. 바뀐 내용은 공식 V1 이전 가이드에 가장 잘 정리돼 있어요.

클로드 코드 스킬을 OpenCode 2에서 그대로 쓸 수 있나요?

네. V2는 .claude/skills와 ~/.claude/skills 폴더도 자동으로 찾아요. 다만 규칙 파일은 CLAUDE.md를 읽지 않으니 AGENTS.md로 옮겨야 해요.

참고 문서: OpenCode V2 문서, Migrate from V1, V2 Agents, V2 Instructions, V2 Sharing, V2 MCP servers, V2 Skills, anomalyco/opencode 저장소, oh-my-openagent v5.0.0 릴리스 노트