OpenCode: 오픈소스 AI 코딩 에이전트와 Desktop v2

AI 코딩 도구가 개발자의 일상에 깊숙이 자리 잡은 지금, 많은 분들이 Claude Code, GitHub Copilot, Cursor 같은 도구들을 사용하고 계실 겁니다. 그런데 이런 도구들은 대부분 유료이고 소스 코드도 공개되어 있지 않죠.

그래서 오늘은 코드가 투명하게 공개되어 있고 다양한 모델 공급자(provider)를 지원하는 오픈소스 AI 코딩 에이전트, OpenCode를 소개해 드리겠습니다. 기본 사용법과 권한 설정뿐 아니라 2026년 7월 공개된 Desktop v2의 변화까지 함께 살펴볼게요.

opencode

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는 물론 로컬 모델까지 연결할 수 있습니다
  • Claude Pro/Max 연동: Anthropic 계정으로 로그인해서 기존 구독을 활용할 수 있습니다

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년 7월 25일 기준 최신 안정 릴리스는 v1.18.5입니다. 이름을 구분하면 다음과 같아요.

이름뜻현재 상태
OpenCode v1.18.xCLI, TUI, Desktop을 함께 배포하는 릴리스 버전안정 릴리스
Desktop v2Desktop 앱의 새 레이아웃과 작업 흐름v1.18.0부터 전환 배포
Desktop 앱OpenCode를 그래픽 화면에서 사용하는 공식 앱아직 베타

따라서 “OpenCode 2.0 출시”는 새 Desktop 환경이 널리 배포되기 시작했다는 뜻에 가깝습니다. opencode --version이 1.18.5를 출력해도 정상이에요.

대화창에서 작업 공간으로

이전 Desktop은 프로젝트를 고르고 대화 세션을 여는 구조가 중심이었습니다. 에이전트와 대화하다가 터미널 명령이 필요하면 별도 창으로 이동하고, 수정된 파일을 자세히 보려면 다시 편집기를 열어야 했죠.

Desktop v2는 이 흐름을 하나의 작업 공간(workspace) 안으로 끌어옵니다.

Desktop v2의 작업 공간
┌─────────────────────────────────────────────────────────┐
│ [세션 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 bucket add extras
scoop install extras/opencode

Desktop 앱은 공식 다운로드 페이지에서 받을 수 있습니다. macOS에서는 Homebrew Cask로도 설치할 수 있어요.

brew install --cask 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 Zen을 추천드립니다. OpenCode 팀이 코딩 에이전트에 최적화된 모델들을 직접 테스트하고 벤치마킹해서 제공하는 유료 서비스입니다. OpenCode는 여러 LLM 공급자를 지원하는데, 모델마다 코딩 성능이 천차만별이거든요. Zen을 사용하면 어떤 모델이 좋은지 고민하거나 여러 공급자의 API 키를 각각 발급받을 필요 없이 바로 시작할 수 있습니다.

CLI에서 먼저 인증하려면 다음 명령을 실행합니다.

opencode auth login
opencode auth list

TUI에서는 /connect 명령을 입력해 공급자 선택 화면을 열 수도 있습니다.

/connect

Popular 섹션에서는 다음과 같은 공급자를 선택할 수 있습니다.

  • OpenCode Zen (Recommended): OpenCode 팀이 추천하는 큐레이션 모델
  • Anthropic: Claude Max 구독 또는 API 키 사용
  • GitHub Copilot: 기존 Copilot 구독 활용
  • OpenAI: GPT 모델 사용
  • Google: Gemini 모델 사용
  • OpenRouter: 다양한 모델을 하나의 API로

Zen을 선택하면 웹 브라우저에서 로그인하고 API 키를 발급받을 수 있습니다. 이미 Claude Max나 다른 AI 서비스를 구독하고 계신다면, 해당 공급자를 선택해서 기존 구독을 활용할 수도 있습니다.

프로젝트 초기화

이제 작업할 프로젝트 디렉터리로 이동해서 OpenCode를 시작해 봅시다.

cd /path/to/your/project
opencode

프로젝트에서 처음 OpenCode를 사용한다면 /init 명령어로 초기화하는 것을 권장합니다.

/init

이 명령어를 실행하면 OpenCode가 프로젝트 구조를 분석하고 AGENTS.md 파일을 생성합니다. 이 파일은 OpenCode가 프로젝트의 구조와 코딩 패턴을 이해하는 데 도움을 줍니다. Claude Code의 CLAUDE.md와 비슷한 역할을 하는데요. 자세한 내용은 별도 포스팅을 참고해 주세요.

💡 AGENTS.md 파일은 Git에 커밋해서 팀원들과 공유하는 것이 좋습니다!

기본 사용법

OpenCode의 기본적인 사용법을 알아봅시다.

프롬프트를 작성할 때 @ 키를 누르면 파일 이름 일부만 입력해도 프로젝트 내 파일을 찾을 수 있습니다. 이렇게 찾은 파일을 프롬프트에 포함시키면 OpenCode가 해당 파일의 내용을 참고해서 답변해 줍니다.

@packages/functions/src/api/index.ts 에서 인증이 어떻게 처리되는지 설명해줘

OpenCode에는 Plan 모드와 Build 모드가 있는데요. Tab 키로 두 모드를 전환할 수 있습니다. Plan 모드에서는 변경 사항을 직접 적용하지 않고 구현 계획만 제안하고, Build 모드에서는 실제로 코드를 수정합니다. 복잡한 기능을 추가할 때는 먼저 Plan 모드에서 계획을 검토한 후 Build 모드로 전환해서 구현하는 것을 권장합니다.

원하지 않는 변경이 적용되었다면 /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이 시도하면 “Accept”, “Accept Always”, “Deny” 세 가지 옵션이 표시됩니다. “Accept Always”를 선택하면 현재 세션 동안 같은 종류의 명령어가 자동으로 허용됩니다.

전역 설정은 ~/.config/opencode/config.json 또는 ~/.config/opencode/config.jsonc에 저장할 수 있습니다.

세션 공유

세션을 링크로 공유할 수 있다는 점도 눈에 띕니다.

/share

이 명령어를 실행하면 현재 대화의 공유 링크가 클립보드에 복사됩니다. 팀원에게 문제 상황을 설명하거나, 버그를 디버깅할 때 유용하게 활용할 수 있습니다.

예시 대화 보기를 통해 실제 공유된 세션이 어떻게 보이는지 확인해 보세요.

사용자화

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.0CCBY

개발자를 위한 뉴스레터

달레가 정리한 AI 개발 트렌드와 직접 만든 콘텐츠를 전해드립니다.

관련 포스트

AI를 위한 프로젝트 안내서: AGENTS.md와 CLAUDE.md

요즘 Cursor나 Claude Code, Codex와 같은 AI 도구로 소프트웨어 개발을 많이 하시죠? 그런데 AI 코딩 에이전트에게 작업을 시키다 보면 프로젝트에 대한 전반적인 지식이 부족하여 엉뚱하게 작업을 진행할 때가 있습니다. 예를 들어, 테스트 파일을 엉뚱한 위치에 생성하거나, 프로젝트의 코딩 컨벤션을 무시하거나, 마음대로 이미 쓰고 있는 라이브러리랑 비슷한 기능을 하는 다른 라이브러리를 설치해버리는 식이죠. 이럴 때는 AI 에이전트에게 좀 더 구체적으로 작업 방향을 알려줄 수 있지만, 새로운 대화 세션을 시작할 때마다

코딩 에이전트는 어떻게 작동하는가

요즘 개발자 커뮤니티에서 코딩 에이전트 이야기가 정말 많이 나옵니다. Claude Code, Cursor, Windsurf, Copilot 등등 하루가 멀다 하고 새로운 도구가 등장하고 있죠. 그런데 이 도구들이 내부적으로 어떻게 돌아가는지 아는 사람은 의외로 많지 않습니다. 코딩 에이전트는 단순히 코드를 생성하는 것을 넘어서 파일을 읽고 명령어를 실행하고 테스트까지 돌리는 꽤 복잡한 시스템인데요. 그 중심에는 **도구 사용(Tool Use)**이라는 메커니즘이 있습니다. 이 글에서는 코딩 에이전트가 어떻게 작동하는지 그 원리를 하

Goose 사용법: Block이 만든 오픈소스 AI 코딩 에이전트

AI 코딩 에이전트 시장이 점점 뜨거워지고 있죠. Claude Code나 OpenCode 같은 도구가 이미 많은 개발자의 워크플로우에 자리 잡았는데요, 오늘은 조금 다른 접근 방식을 취하는 도구를 하나 소개해드리겠습니다. 바로 Block(구 Square)이 만든 오픈소스 AI 코딩 에이전트, Goose입니다. Goose는 2025년 1월에 처음 공개된 이후 빠르게 성장해서, 지금은 GitHub 스타 27,000개 이상, 기여자 400명 이상의 대규모 오픈소스 프로젝트가 되었습니다. 2025년 12월에는 Linux Foundation

Playwright CLI: AI 코딩 에이전트를 위한 Microsoft의 새로운 브라우저 자동화 도구

AI 코딩 에이전트에게 브라우저를 맡기는 흐름이 더 빨라지고 있습니다. 이전에 Playwright MCP로 AI 에이전트가 MCP 서버를 통해 브라우저를 다루는 방법을 살펴봤고, Vercel Labs의 agent-browser 같은 CLI 기반 접근도 소개했었는데요. 이번에는 Playwright를 만든 Microsoft가 직접 내놓은 새 도구를 들고 왔습니다. Playwright CLI는 그 이름 그대로 Playwright의 핵심 기능을 명령줄 인터페이스로 노출한 도구입니다. 흥미로운 점은 이게 단순한 playwright 패키지의

ccusage: 클로드 코드 토큰 사용량과 비용을 한눈에

클로드 코드를 쓰다 보면 어느 순간 궁금해지는 게 있어요. 이번 달에 토큰을 얼마나 썼지? 비용은 얼마쯤 나왔을까? 세션 중에 /cost로 현재 비용을 확인할 수는 있는데, 지난주 월요일에 얼마를 썼는지나 프로젝트별 비용 분포는 알기 어렵죠. ccusage는 이 질문들에 답해주는 CLI 도구예요. 클로드 코드가 로컬에 남기는 세션 로그 파일을 분석해서 일별, 월별, 세션별 토큰 사용량과 비용을 테이블 형태로 보여줘요. 설치할 필요도 없이 npx 한 줄이면 바로 실행할 수 있어서 진입 장벽이 거의 없어요. 바로 실행해보기 ccusag

AI를 위한 CLI 설계: 에이전트가 쓰기 좋은 커맨드라인 도구 만들기

요즘 개발하다 보면 CLI 도구를 직접 타이핑하기보다 AI 에이전트한테 시키는 일이 부쩍 늘었습니다. 클로드 코드나 Cursor 같은 코딩 에이전트가 터미널에서 git, npm, docker, grep 같은 명령어를 알아서 실행해주니까요. 근데 가만 생각해보면 우리가 쓰는 CLI 도구 대부분은 사람이 직접 타이핑하는 걸 전제로 만들어졌어요. --help 플래그로 사용법을 찾아보고, 탭 완성으로 옵션을 탐색하고, 에러 메시지를 읽고 다시 시도하는 거죠. AI 에이전트는 이렇게 도구를 쓰지 않습니다. 문서를 읽어 이해한 뒤 명령어를 한