OpenCode: 오픈소스 AI 코딩 에이전트와 Desktop v2
AI 코딩 도구가 개발자의 일상에 깊숙이 자리 잡은 지금, 많은 분들이 Claude Code, GitHub Copilot, Cursor 같은 도구들을 사용하고 계실 겁니다. 그런데 이런 도구들은 대부분 유료이고 소스 코드도 공개되어 있지 않죠.
그래서 오늘은 코드가 투명하게 공개되어 있고 다양한 모델 공급자(provider)를 지원하는 오픈소스 AI 코딩 에이전트, OpenCode를 소개해 드리겠습니다. 기본 사용법과 권한 설정뿐 아니라 2026년 7월 공개된 Desktop v2의 변화까지 함께 살펴볼게요.

OpenCode란?
OpenCode는 명령줄 인터페이스(command-line interface, 이하 CLI), 터미널 사용자 인터페이스(terminal user interface, 이하 TUI), 통합 개발 환경(integrated development environment, 이하 IDE), 데스크톱 앱(desktop app, 이하 Desktop 앱)에서 사용할 수 있는 오픈소스 AI 코딩 에이전트입니다. Claude Code와 비슷한 개념이지만 도구의 소스 코드가 공개되어 있다는 점이 가장 큰 차이입니다. OpenCode 자체는 무료로 설치할 수 있어도 연결하는 대형 언어 모델(large language model, 이하 LLM)에 따라 API나 구독 비용은 따로 들 수 있어요.
OpenCode의 핵심 특징을 살펴볼까요?
- 언어 서버 프로토콜(Language Server Protocol, LSP) 지원: LLM을 위한 언어 서버를 자동으로 불러옵니다
- 멀티 세션: 같은 프로젝트에서 여러 에이전트를 병렬로 실행할 수 있습니다
- 세션 공유: 대화 내용을 링크로 공유해서 팀원과 협업하거나 디버깅할 수 있습니다
- 여러 모델 공급자: Claude, GPT, Gemini는 물론 로컬 모델까지 연결할 수 있습니다
- 에디터 연동: ACP로 Zed, JetBrains, Neovim 같은 에디터에 에이전트로 붙일 수 있습니다
OpenCode 2.0은 무엇인가요?
“OpenCode 2.0이 나왔다”는 이야기를 듣고 업데이트한 뒤 버전을 확인하면 조금 당황할 수 있습니다.
opencode --version
결과에는 2.0.0이 아니라 1.18.x가 표시되기 때문인데요. 설치가 잘못된 것은 아닙니다. 이번에 2.0이라고 불리는 대상은 OpenCode 전체의 안정 버전이 아니라 OpenCode Desktop의 새 인터페이스인 Desktop v2입니다.
공식 변경 기록에 따르면 2026년 7월 14일 공개된 v1.18.0에서 Desktop v2 마이그레이션(migration)이 완료됐습니다. 새 레이아웃으로 올리는 처리와 첫 실행 온보딩(onboarding)이 이 버전에 포함됐고, 전환 기간에는 설정에서 이전 화면으로 돌아갈 수도 있습니다.
글을 업데이트하는 2026년 9월 26일 기준 최신 안정 릴리스는 v1.18.32입니다. 이름을 구분하면 다음과 같아요.
| 이름 | 뜻 | 현재 상태 |
|---|---|---|
OpenCode v1.18.x | CLI, TUI, Desktop을 함께 배포하는 릴리스 버전 | 안정 릴리스 |
| Desktop v2 | Desktop 앱의 새 레이아웃과 작업 흐름 | v1.18.0부터 전환 배포 |
| Desktop 앱 | OpenCode를 그래픽 화면에서 사용하는 공식 앱 | 아직 베타 |
따라서 “OpenCode 2.0 출시”는 새 Desktop 환경이 널리 배포되기 시작했다는 뜻에 가깝습니다. opencode --version이 1.18.32를 출력해도 정상이에요.
대화창에서 작업 공간으로
이전 Desktop은 프로젝트를 고르고 대화 세션을 여는 구조가 중심이었습니다. 에이전트와 대화하다가 터미널 명령이 필요하면 별도 창으로 이동하고, 수정된 파일을 자세히 보려면 다시 편집기를 열어야 했죠.
Desktop v2는 이 흐름을 하나의 작업 공간(workspace) 안으로 끌어옵니다.
┌─────────────────────────────────────────────────────────┐
│ [세션 A] [세션 B] [세션 C] + │
├──────────────────────────────┬──────────────────────────┤
│ │ 파일 / 변경점 / 리뷰 │
│ 에이전트 대화 │ │
│ │ src/app.ts │
│ │ src/app.test.ts │
├──────────────────────────────┴──────────────────────────┤
│ 통합 터미널 │
└─────────────────────────────────────────────────────────┘
먼저 여러 세션을 브라우저 페이지처럼 탭으로 열어둘 수 있습니다. 한 탭에서 로그인 오류를 조사하게 하고 다른 탭에서는 의존성 업데이트를 맡기는 식이죠. 탭을 옮겨도 프롬프트 초안과 상태가 유지되고, 읽지 않은 질문이 남은 탭에는 표시가 붙습니다.
같은 창 아래에는 통합 터미널(integrated terminal)이 들어왔습니다. 에이전트가 코드를 수정한 뒤 테스트나 Git 명령을 곧바로 실행할 수 있어요. 탭을 바꿔도 터미널이 마운트된 상태를 유지하므로 오래 걸리는 테스트를 실행해 둔 채 다른 세션을 확인했다가 돌아올 수도 있습니다.
bun test
bun run typecheck
git diff --stat
오른쪽의 리뷰 패널(review panel)은 변경점(diff)과 파일 탐색을 한곳에 모았습니다. 변경된 파일을 차례로 비교할 수 있고, 파일 브라우저 탭에서 프로젝트의 디렉터리 트리를 훑어보다가 일반 파일도 탭으로 열어 주변 코드를 확인할 수 있습니다. 열린 파일은 편집기가 아니라 구문 강조가 된 뷰어라서 직접 고칠 수는 없어요. 대신 줄 범위를 골라 코멘트를 달면 그 내용이 프롬프트 컨텍스트로 에이전트에게 전달되니, 코드 리뷰하듯 짚어 가며 수정을 맡기면 됩니다. 에이전트의 최종 답변만 믿고 끝내는 대신, 예상하지 못한 파일이 바뀌지 않았는지 살핀 뒤 같은 창에서 테스트까지 다시 실행하는 흐름이 자연스러워졌어요.
프롬프트 입력창인 컴포저(composer)도 다시 작성됐습니다. 파일 첨부, 명령, 컨텍스트(context), 셸 모드를 한 메뉴에서 고를 수 있고 메뉴를 열었다 닫아도 쓰던 초안이 남습니다. 프롬프트마다 모델을 바꿀 수 있어 간단한 탐색은 빠른 모델에, 복잡한 설계는 추론 성능이 높은 모델에 맡길 수도 있습니다.
각 기능만 보면 화려하지 않을 수 있습니다. 하지만 요청하고, 명령을 실행하고, 수정된 코드를 검토하는 과정이 한 화면 안에서 이어진다는 점이 Desktop v2의 가장 큰 변화입니다.
CLI와 Desktop 설치
OpenCode를 설치하는 방법은 여러 가지가 있습니다. 가장 간단한 방법은 설치 스크립트를 사용하는 것입니다.
curl -fsSL https://opencode.ai/install | bash
Bun을 선호한다면 전역 패키지로 설치할 수 있습니다.
bun add --global opencode-ai@latest
macOS나 Linux에서 Homebrew를 쓴다면 업데이트가 빠른 공식 탭을 사용하는 방법이 권장됩니다.
brew install anomalyco/tap/opencode
Windows 사용자라면 Chocolatey나 Scoop을 활용할 수 있습니다.
# Chocolatey
choco install opencode
# Scoop
scoop install opencode
Desktop 앱은 공식 다운로드 페이지에서 받을 수 있습니다. macOS에서는 Homebrew Cask로, Windows에서는 Scoop으로도 설치할 수 있어요.
# macOS
brew install --cask opencode-desktop
# Windows
scoop bucket add extras
scoop install extras/opencode-desktop
기존 사용자는 OpenCode 자체 명령으로 최신 버전까지 올릴 수 있습니다.
opencode upgrade
opencode --version
설치 방법을 자동으로 찾지 못하면 --method로 기존 설치 방식을 알려주세요.
opencode upgrade --method bun
Desktop은 뒤에서 로컬 OpenCode 서버를 사이드카(sidecar) 프로세스로 실행합니다. 화면만 최신이어도 내부 서버가 오래됐거나 플러그인이 맞지 않으면 세션과 터미널에서 문제가 날 수 있어요. 이상한 동작이 보이면 Desktop 앱과 CLI를 모두 최신 상태로 맞춘 뒤 다시 확인하는 편이 좋습니다.
Desktop v2는 큰 개편인 만큼 v1.18.0 이후에도 홈 화면, 탭 복원, 리뷰 패널, 프롬프트 입력, 서버 연결에 관한 수정이 빠르게 이어졌습니다. 전환 기간에는 설정의 레이아웃 전환 옵션으로 이전 화면을 잠시 쓸 수 있었지만, 이 옵션은 한시적이라 최신 버전에서는 보이지 않을 수 있습니다. Desktop 앱은 아직 베타이므로 중요한 작업은 작은 저장소에서 먼저 시험해 보는 편이 안전합니다.
LLM 공급자 선택
설치가 완료되면 LLM 공급자를 설정해야 합니다. OpenCode를 처음 사용하신다면 OpenCode 팀이 운영하는 OpenCode Zen이나 OpenCode Go로 시작하는 게 가장 간단합니다. OpenCode는 여러 LLM 공급자를 지원하는데, 모델마다 코딩 성능이 천차만별이거든요. 두 서비스 모두 OpenCode 팀이 코딩 에이전트용으로 직접 테스트한 모델만 모아 두었기 때문에, 어떤 모델이 좋은지 고민하거나 공급자별 API 키를 각각 발급받지 않아도 됩니다.
둘은 요금 방식이 다릅니다. Zen은 크레딧을 충전해 두고 요청마다 차감하는 종량제 서비스이고, Big Pickle처럼 기간 한정으로 무료로 풀린 모델도 함께 제공합니다. 무료 모델이라도 Zen에 가입해서 API 키를 받아야 쓸 수 있어요. Go는 월 구독제로, 오픈 모델 위주의 모델 묶음을 모델별 월간 한도 안에서 고정 요금으로 쓸 수 있습니다. 한도를 넘으면 Zen 잔액으로 이어서 쓰도록 설정할 수도 있고요.
CLI에서 먼저 인증하려면 다음 명령을 실행합니다.
opencode providers login
opencode providers list
예전에 쓰던 opencode auth login도 providers의 별칭으로 남아 있어서 그대로 동작합니다.
TUI에서는 /connect 명령을 입력해 공급자 선택 화면을 열 수도 있습니다.
/connect
Popular 섹션에서는 다음과 같은 공급자를 선택할 수 있습니다.
- OpenCode Zen (Recommended): OpenCode 팀이 추천하는 큐레이션 모델
- Anthropic: Claude 모델을 API 키로 사용
- GitHub Copilot: 기존 Copilot 구독 활용
- OpenAI: GPT 모델 사용
- Google: Gemini 모델 사용
- OpenRouter: 다양한 모델을 하나의 API로
Zen을 선택하면 웹 브라우저에서 로그인하고 API 키를 발급받을 수 있습니다.
Claude Pro나 Max 구독을 연결하는 방법은 주의가 필요합니다. 예전 OpenCode에는 Claude 구독 계정으로 로그인하는 플러그인이 기본으로 들어 있었지만, Anthropic이 서드파티 도구에서 구독을 쓰는 것을 명시적으로 금지하면서 1.3.0부터 빠졌습니다. 그래서 OpenCode에서 Claude를 쓰려면 Anthropic API 키를 연결해야 하고, 사용량만큼 API 비용이 따로 나갑니다. Claude 구독을 그대로 쓰고 싶다면 Claude Code를 직접 쓰거나, goose처럼 ACP로 Claude Code를 불러다 쓰는 도구를 고르는 편이 맞아요.
Desktop 앱의 설정에서 Models 화면을 열면 Anthropic을 비롯한 여러 공급자의 모델이 쭉 나오고 일부는 켜져 있을 수도 있습니다.
이 목록은 Models.dev 카탈로그에서 가져온 것이고, 토글은 모델 선택기에 보일지 여부만 정합니다.
켜져 있다고 연결된 게 아니니, 실제로 쓰려면 Providers 화면이나 /connect에서 해당 공급자를 먼저 인증하세요.
프로젝트 초기화
이제 작업할 프로젝트 디렉터리로 이동해서 OpenCode를 시작해 봅시다.
cd /path/to/your/project
opencode
프로젝트에서 처음 OpenCode를 사용한다면 /init 명령어로 초기화하는 것을 권장합니다.
/init
이 명령어를 실행하면 OpenCode가 프로젝트 구조를 분석하고 AGENTS.md 파일을 생성합니다.
이 파일은 OpenCode가 프로젝트의 구조와 코딩 패턴을 이해하는 데 도움을 줍니다.
Claude Code의 CLAUDE.md와 비슷한 역할을 하는데요. 자세한 내용은 AGENTS.md와 CLAUDE.md 작성법을 참고해 주세요.
💡
AGENTS.md파일은 Git에 커밋해서 팀원들과 공유하는 것이 좋습니다!
기본 사용법
OpenCode의 기본적인 사용법을 알아봅시다.
프롬프트를 작성할 때 @ 키를 누르면 파일 이름 일부만 입력해도 프로젝트 내 파일을 찾을 수 있습니다.
이렇게 찾은 파일을 프롬프트에 포함시키면 OpenCode가 해당 파일의 내용을 참고해서 답변해 줍니다.
@packages/functions/src/api/index.ts 에서 인증이 어떻게 처리되는지 설명해줘
OpenCode에는 Build와 Plan이라는 두 가지 기본 에이전트가 있는데요. Tab 키로 둘을 전환할 수 있습니다.
Build는 모든 도구를 쓰는 기본 에이전트라 실제로 코드를 수정합니다.
Plan은 파일 수정과 셸 명령이 모두 ask로 묶여 있어서, 허락하지 않는 한 아무것도 바꾸지 않고 분석과 구현 계획에 집중해요.
복잡한 기능을 추가할 때는 먼저 Plan에서 계획을 검토한 후 Build로 전환해서 구현하는 것을 권장합니다.
이 밖에 기본 에이전트가 필요할 때 불러 쓰는 서브에이전트(subagent)도 있습니다.
코드베이스를 빠르게 훑는 Explore와 범용 작업을 맡는 General이 기본으로 들어 있고, @general 이 함수가 어디서 쓰이는지 찾아줘처럼 @로 직접 부를 수도 있어요.
원하지 않는 변경이 적용되었다면 /undo 명령어로 되돌릴 수 있습니다.
/undo
여러 번 실행해서 여러 변경 사항을 되돌릴 수도 있고, /redo로 다시 적용할 수도 있습니다.
참고로 /undo와 /redo는 내부적으로 Git을 사용하기 때문에 프로젝트가 Git 저장소여야 합니다.
유용한 기능
OpenCode에는 작업을 편하게 만드는 기능이 여럿 있습니다.
!로 시작하면 셸 명령어를 바로 실행할 수 있습니다.
명령어의 출력 결과가 대화에 추가되기 때문에, LLM이 이를 참고해서 답변할 수 있습니다.
!ls -la
/models 명령어로 사용 가능한 모델 목록을 확인하고 전환할 수 있습니다.
작업 특성에 따라 더 빠른 모델이나 더 똑똑한 모델을 선택할 수 있죠.
/models
/sessions 명령어로 이전 세션 목록을 확인하고 이어서 작업할 수 있습니다.
어제 진행하던 작업을 오늘 다시 시작하고 싶을 때 유용합니다.
/sessions
대화가 길어지면 /compact 명령어로 세션을 요약할 수 있습니다.
컨텍스트 윈도우를 절약하면서도 중요한 맥락은 유지할 수 있습니다.
/compact
/export 명령어는 현재 대화를 마크다운 파일로 내보내줍니다.
나중에 참고하거나 문서화할 때 유용합니다.
권한 설정
OpenCode가 파일을 수정하거나 명령어를 실행할 때 매번 승인을 받을지, 자동으로 실행할지 설정할 수 있습니다.
프로젝트 루트에 opencode.json 또는 opencode.jsonc 파일을 만들어서 permission 옵션을 설정하면 됩니다.
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "ask",
"bash": {
"git push": "ask",
"git status": "allow",
"bun run build": "allow",
"terraform *": "deny"
}
}
}
권한 값은 세 가지가 있습니다:
allow: 승인 없이 자동 실행ask: 매번 사용자에게 승인 요청deny: 실행 금지
"ask"로 설정된 작업을 LLM이 시도하면 한 번만 허용(once), 계속 허용(always), 거부(reject) 중에서 고르게 됩니다.
계속 허용을 선택하면 현재 세션 동안 같은 패턴의 요청이 자동으로 허용됩니다.
설정하지 않은 권한은 대부분 allow가 기본값입니다.
다만 프로젝트 밖의 경로에 접근하는 external_directory와 같은 도구를 반복해서 호출하는 doom_loop는 기본으로 ask이고, 파일 읽기는 .env 파일만 빼고 허용돼요.
권한 키도 edit와 bash 말고 read, webfetch, websearch, task, skill 등으로 세분돼 있으니 필요한 것만 골라 조이면 됩니다.
전역 설정은 ~/.config/opencode/opencode.json에 저장합니다.
일괄 작업처럼 매번 승인하기 번거로울 때는 --auto 플래그로 실행하면 명시적으로 deny한 것 말고는 모두 자동 승인됩니다.
그만큼 위험하니 믿을 수 있는 저장소에서만 쓰세요.
세션 공유
세션을 링크로 공유할 수 있다는 점도 눈에 띕니다.
/share
이 명령어를 실행하면 현재 대화의 공유 링크가 클립보드에 복사됩니다. 팀원에게 문제 상황을 설명하거나, 버그를 디버깅할 때 유용하게 활용할 수 있습니다.
실제로 공유된 세션이 어떻게 보이는지는 예시 대화에서 확인해 보세요.
에디터에서 ACP로 쓰기
터미널이나 Desktop 앱 말고 평소 쓰는 에디터 안에서 OpenCode를 쓰고 싶다면 ACP를 활용하면 됩니다.
ACP(Agent Client Protocol)는 에디터와 코딩 에이전트가 JSON-RPC 메시지로 대화하는 표준 프로토콜인데요.
opencode acp 명령을 실행하면 OpenCode가 ACP 에이전트 서버로 동작합니다.
예를 들어 Zed에서는 settings.json에 다음과 같이 등록하면 에이전트 패널에서 OpenCode를 고를 수 있어요.
{
"agent_servers": {
"OpenCode": {
"type": "custom",
"command": "opencode",
"args": ["acp"]
}
}
}
JetBrains IDE는 acp.json에 OpenCode 실행 파일의 절대 경로와 ["acp"] 인자를 적고, Neovim에서는 avante.nvim이나 CodeCompanion.nvim 같은 플러그인으로 연결합니다.
ACP로 연결해도 내장 도구, MCP 서버, AGENTS.md, 권한 설정은 그대로 적용됩니다.
다만 /undo와 /redo 같은 일부 슬래시 명령은 아직 ACP에서 지원하지 않아요.
사용자화
OpenCode는 여러 사용자화 옵션을 제공합니다.
- 테마 설정: 원하는 색상 테마를 선택할 수 있습니다
- 키 바인딩 변경: 자주 사용하는 단축키를 직접 바꿀 수 있습니다
- 코드 포매터 설정: Prettier, ESLint 등과 연동할 수 있습니다
- 사용자 지정 명령: 자주 사용하는 작업을 명령으로 만들 수 있습니다
자세한 설정 방법은 공식 문서를 참고하세요.
마치며
OpenCode는 소스가 공개된 AI 코딩 에이전트입니다. 여러 모델 공급자를 고를 수 있고 TUI, IDE, Desktop 앱 중 익숙한 화면을 선택할 수 있다는 점이 매력적이에요.
Desktop v2에서는 탭, 통합 터미널, 리뷰 패널이 한 작업 공간에 모이면서 대화 도구에서 개발 작업 공간으로 한 걸음 더 가까워졌습니다. 업데이트한 뒤 2.0.0이 보이지 않더라도 최신 v1.18.x에서 새 레이아웃이 열린다면 제대로 설치된 거예요.
먼저 작은 작업 하나를 맡겨 보고, 대화에서 검토와 테스트까지 이어지는 흐름이 내 작업 방식에 맞는지 확인해 보는 건 어떨까요? 더 자세한 정보는 GitHub 저장소에서 확인하실 수 있습니다.
This work is licensed under CC BY 4.0