tracks
AI 비즈니스 기초
12
OpenCode는 특정 작업을 수행하도록 설계되었습니다. 이는 AI 모델을 저장소, 터미널, 개발 도구에 연결하는 오픈 소스 에이전트입니다. 버그 수정을 요청하면 관련 파일을 찾고, 계획을 세우고, 코드를 수정하고, 테스트를 실행하며, 오류에 대응할 수 있습니다. 자동완성만으로는 이를 자체적으로 수행할 수 없습니다.
이처럼 역할이 넓어지면서 주목을 받았습니다. 작성 시점 기준, 활성 OpenCode 저장소는 약 189,000개의 GitHub 스타를 보유하고 있었습니다. 별 수를 코드 품질의 증거로 보진 않지만, 프로젝트에 쏠린 관심의 정도는 보여줍니다.
현실은 그렇게 깔끔하지만은 않습니다. OpenCode는 여러 모델 중 선택할 수 있게 하고, 그 선택을 사용자가 관리하도록 합니다. 2026년 1월의 한 제공자 정책 변경은 옵션이 얼마나 빠르게 변할 수 있는지 보여줬습니다. 이 점을 OpenCode의 작동 방식과 함께 살펴보겠습니다.
이어서 진행하기 전에 이름에 관한 간단한 참고 사항이 있습니다. OpenCode를 검색하면 보관(archived)된 Go 기반 opencode-ai/opencode 저장소가 보일 수 있습니다. 그 프로젝트는 2025년 9월 이후 유지보수가 중단되었습니다. 본 글은 github.com/anomalyco/opencode의 활성 프로젝트에 집중하며, 이는 Serverless Stack (SST) 프레임워크를 만든 팀이 제작했습니다.
OpenCode란?
OpenCode는 MIT 라이선스로 공개된 오픈 소스 AI 코딩 에이전트입니다. 특정 모델 제공자에 묶이지 않는 모델 불가지론적(model-agnostic) 도구입니다. 사용자는 소스 코드를 읽고 수정할 수 있으며, 자체 호스팅도 가능합니다. 소프트웨어 자체는 무료입니다. 모델 과금은 별도이며, 이는 아래 기능 섹션에서 다룹니다.
OpenCode는 대규모 언어 모델(LLM)이 아닙니다. 선택한 모델이 프롬프트를 읽고 응답을 생성합니다. OpenCode는 그 모델을 둘러싼 파일 도구, 쉘 접근, 세션 기록, 권한 규칙, 인터페이스를 제공합니다. 이 구분이 유용한 이유는 모델을 바꿔도 나머지 도구를 바꿀 필요가 없기 때문입니다.
해당 도구는 과거 SST였던 Anomaly가 제작했으며, 주로 TypeScript와 Bun으로 동작합니다.
보관된 저장소와 현재 OpenCode 저장소 비교. 이미지: 필자 제공.
OpenCode는 특정 모델 계열에 묶여 있지 않습니다. Models.dev 레지스트리를 통해 Anthropic, OpenAI, Google, DeepSeek, Groq, 그리고 Ollama를 통한 로컬 모델 등 75개가 넘는 제공자와 연결됩니다. 기존 구독 계정을 연결하는 방법도 있으며, 이는 기능 섹션에서 다룹니다.
파일 변경 사항을 보여주는 OpenCode 터미널 세션. 이미지: 필자 제공.
OpenCode는 터미널에서 시작했지만, 현재는 터미널 인터페이스(TUI), macOS/Windows/Linux용 베타 데스크톱 앱, VS Code 같은 에디터 확장으로 제공됩니다. 작성 시점의 최신 안정 버전은 v1.18.8입니다.
OpenCode가 만들어진 이유
앞서 언급했듯, OpenCode는 여러 제공자의 모델을 지원합니다. 이는 모델 품질과 가격이 변하고, 특정 제공자에 묶인 도구는 사용자 선택지를 줄이기 때문에 그렇게 설계되었습니다.
문서에 따르면 OpenCode는 어떤 제공자에도 결합되어 있지 않습니다. 앞서 언급한 Models.dev 레지스트리가 OpenCode가 사용하는 모델 정보와 가격을 제공합니다.
이 선택은 과금 이상의 차이를 만듭니다. 모델마다 컨텍스트 한도, 도구 호출 형식, 입력 유형이 다릅니다. OpenCode는 이러한 차이를 하나의 인터페이스로 흡수합니다. 개발자는 같은 프로젝트에서 세션을 다른 코딩 도구로 옮기지 않고도 선택한 모델을 바꿀 수 있습니다.
팀은 또한 사용자가 검토할 수 있는 터미널 중심 도구를 선호합니다. 프로젝트 지침은 AGENTS.md라는 평범한 파일에 존재합니다. 이 파일을 OpenCode가 어떻게 만들고 사용하는지는 뒤에서 설명하겠습니다.
공식 프로젝트는 세 가지 설계 선택을 밝힙니다. 첫째는 앞서 다룬 제공자 지원입니다. 둘째는 주요 제어를 터미널에 두는 것입니다. 셋째는 클라이언트와 서버의 분리입니다. 이 분리는 다음 섹션에서 설명합니다.
2026년 1월, Anthropic은 비공식 경로를 통한 소비자용 Claude 구독의 서드파티 도구 사용을 차단했습니다. 이후 OpenCode는 다른 구독 옵션을 추가하고 자체 게이트웨이를 사용했습니다. 사용자는 다른 제공자를 통해 계속 연결할 수 있었습니다.
이 사건은 OpenCode에서 제공자 선택이 왜 큰 관심을 받는지 설명합니다. 사용자가 그 선택으로 무엇을 하는지 보려면, 다음으로 세션을 살펴보겠습니다.
OpenCode의 작동 방식
OpenCode는 클라이언트와 로컬 서버로 동작합니다. TUI, 데스크톱 앱, IDE 확장, SDK는 모두 HTTP로 그 서버와 통신합니다. 같은 서버는 opencode attach <url>로 원격 접속을, opencode serve로 헤드리스 사용을 지원합니다.
세션 내부에서 에이전트는 관련 파일을 읽고, 필요하면 계획을 세우며, 코드를 수정하고, 필요한 경우 명령을 실행합니다. 이후 LSP(Language Server Protocol) 통합이 컴파일러 및 린터 진단을 모델로 다시 전달하여, 타입 및 문법 오류에 대응할 수 있게 합니다.
예를 들어, 작업은 파일을 찾기 위해 glob 또는 grep으로 시작할 수 있습니다. 에이전트는 read로 파일을 살펴보고 edit으로 선택한 줄을 변경할 수 있습니다. 그런 다음 bash로 테스트나 빌드 명령을 실행할 수 있습니다. 출력 결과는 다음 모델 요청의 일부가 됩니다.
Build와 Plan의 구분은 권한 스위치로 이해하는 것이 가장 쉽습니다. Build는 기본 모드로 읽기, 쓰기, 명령 실행이 가능합니다. Plan은 파일을 수정하거나 bash 명령을 실행하기 전에 확인을 요청합니다. Tab을 누르면 두 모드 간 전환이 됩니다.
권한 검사는 도구 호출 시 적용됩니다. 프로젝트는 특정 도구를 허용, 차단, 또는 매번 사용자에게 확인하도록 설정할 수 있습니다. 규칙은 명령 패턴에 따라 달리할 수도 있습니다. 예를 들어 팀은 일상적인 테스트는 허용하되, 다른 쉘 명령은 확인을 요구하도록 할 수 있습니다.
세션은 OpenCode의 데이터 디렉터리 아래 로컬 디스크에 저장됩니다. OpenCode는 긴 대화를 자동으로 압축합니다. /undo와 /redo 명령은 Git 기반 파일 스냅샷 사이를 오갑니다.
OpenCode의 주요 기능
OpenCode는 주요 기능을 모델 접근, 프로젝트 컨텍스트, 작업 실행, 로컬 사용으로 묶어 설명합니다. 아래 섹션은 각 그룹이 코딩 세션에서 무엇을 바꾸는지 설명합니다.
멀티 모델 지원
앞서 언급했듯 OpenCode는 Models.dev를 통해 제공자 목록을 가져옵니다. 실제로는 호스티드 서비스, 클라우드 플랫폼, 또는 OpenAI 호환 엔드포인트를 연결할 수 있습니다. GitHub Copilot과 ChatGPT Plus/Pro 로그인을 사용하면 별도 API 키를 관리하는 대신 대안이 됩니다.
제공자를 고른다고 해서 모든 모델이 똑같이 동작하는 것은 아닙니다. 도구 사용, 컨텍스트 한도, 응답 시간, 가격은 선택한 모델과 제공자에 따라 달라집니다. 호스티드 모델 호출은 필요한 코드 컨텍스트를 해당 제공자의 자체 데이터 규정에 따라 전송하기도 합니다.
OpenCode는 모델에 접근하는 두 가지 선택적 방법도 제공합니다. OpenCode Zen은 선별된 모델 목록을 제공하는 종량 과금형 게이트웨이입니다. OpenCode Go는 선택된 오픈 웨이트 모델에 대해 첫 달 $5, 이후 월 $10의 구독입니다. 사용자는 자체 API 키를 계속 사용할 수 있습니다. 가격은 변동될 수 있습니다.
약간 성가신 부분도 있습니다. 도구가 무료여도 제공자 요금이 발생할 수 있습니다.
저장소 컨텍스트로 작업하기
/init 를 실행하면 OpenCode가 프로젝트 구조와 규칙을 요약한 AGENTS.md 를 생성합니다. 팀은 이 파일을 커밋하여 세션이 공통 지침으로 시작되도록 할 수 있습니다.
이 파일에는 테스트 명령, 폴더 이름, 네이밍 규칙, 프로젝트 관련 메모를 포함할 수 있습니다. 전역 AGENTS.md에는 여러 프로젝트에서 사용하는 지침을 넣고, 프로젝트 파일에는 특정 저장소의 규칙을 담습니다.
앞서 설명한 LSP 검사는 수정 후에 실행됩니다. 저장소 컨텍스트에는 파일 참조도 포함됩니다. @ 기호를 사용해 선택한 파일을 프롬프트에 끌어올 수 있습니다.
코딩 작업 실행
앞서 설명한 Build와 Plan 에이전트 외에도, OpenCode에는 다단계 검색, 코드베이스 스캔, 외부 문서 작업을 위한 하위 에이전트가 포함되어 있습니다. 사용자 정의 에이전트는 자체 모델, 프롬프트, 도구 권한을 가질 수 있습니다.
각 하위 에이전트는 별도의 자식 세션에서 동작하므로, 그 메시지가 동일한 방식으로 메인 세션을 채우지 않습니다. 사용자 정의 에이전트는 읽기 전용으로 제한하거나, 더 저렴한 모델을 할당하거나, 특정 유형의 작업에 대한 지침을 줄 수 있습니다.
Model Context Protocol (MCP) 서버는 외부 서비스를 추가합니다. 이는 opencode.json에 정의되며, 앞서 다룬 권한 검사 규칙은 이들이 추가하는 도구에도 동일하게 적용됩니다.
계획에서 코드 변경으로 전환하기. 영상: 필자 제공.
로컬 우선 개발(그리고 그 한계)
"로컬 우선(local-first)"이라는 표현에는 단서가 필요합니다. 아무 데이터도 머신 밖으로 나가지 않는다는 약속으로 읽어서는 안 됩니다. 제공자 섹션에서 언급했듯 OpenCode는 Ollama와 연결할 수 있습니다. 이 설정은 코드와 프롬프트를 로컬 인프라에 유지합니다. 호스티드 모델, /share, 그리고 OpenCode Zen은 데이터를 로컬 머신 밖으로 전송합니다.
로컬 사용은 여전히 모델에 좌우됩니다. 작은 모델은 잘못된 도구 호출을 반환하거나 파일 간 연결을 놓칠 수 있습니다. 로컬 서버는 선택한 모델을 위한 충분한 메모리와 각 요청에 함께 전송되는 파일을 담을 충분한 컨텍스트 공간이 필요합니다.
권한 시스템은 워크플로 보호 장치이지 보안 샌드박스가 아닙니다. 네트워크로 접근 가능한 서버 모드는 OPENCODE_SERVER_PASSWORD 를 사용하고 localhost에 바인딩해야 합니다. 이전의 인증되지 않은 노출 문제는 패치되었지만, 서버 모드는 인증 없이 공개적으로 노출해선 안 됩니다.
OpenCode 아키텍처
앞서 언급했듯 OpenCode는 클라이언트와 로컬 서버를 분리합니다. 이 분리는 구성과 저장 상태에 영향을 줍니다. API는 서버를 사용하는 또 다른 방법을 제공합니다.
TUI만 사용할 계획이라면 API 세부 사항은 건너뛰어도 됩니다. 마지막 문단의 구성 설명이 실제로 사용하게 될 부분입니다.
TypeScript와 Bun 서버는 모델 제공자와 통신하고 도구를 실행합니다. 또한 상태를 관리합니다. OpenAPI 3.1 사양으로 공식 @opencode-ai/sdk가 생성됩니다. 스크립트와 커스텀 클라이언트는 이 문서화된 API를 사용할 수 있습니다.
API에는 세션, 메시지, 파일, 제공자, 도구, 에이전트, 구성 항목이 포함됩니다. 이는 OpenCode 자체 클라이언트가 사용하는 것과 동일한 서버입니다. 스크립트는 TUI를 제어하려고 하지 않고도 세션을 생성하거나 메시지를 보낼 수 있습니다.
하나의 서버에 연결되는 OpenCode 클라이언트들. 이미지: 필자 제공.
앞서 나열한 인터페이스는 클라이언트로 동작합니다. TUI, 데스크톱 앱, IDE 확장, opencode web이 이에 해당합니다. 이들은 모두 동일한 서버 프로세스와 통신합니다. 별도의 장치도 해당 프로세스를 통해 기존 세션에 붙을 수 있습니다.
opencode serve 를 실행하면 일반 TUI 없이 서버가 시작됩니다. opencode web을 실행하면 브라우저 클라이언트가 추가됩니다. 두 명령 모두 서버가 다른 장치에서 접근 가능하다면 인증이 필요합니다.
구성은 프로젝트 수준의 opencode.json 또는 opencode.jsonc에 저장되며, 전역 기본값은 ~/.config/opencode/opencode.json입니다. 여기서 모델, 권한, MCP 서버, 사용자 정의 에이전트를 제어합니다. 워크플로 섹션에서 다뤘듯, 세션 기록과 도구 로그는 사용자가 공유하지 않는 한 로컬 파일에 남습니다.
일반적인 OpenCode 워크플로
OpenCode의 동일한 구성 요소는 여러 일반적인 소프트웨어 작업에 사용될 수 있습니다. 아래 예시는 각 작업에서 여전히 사람의 검토가 왜 중요한지 보여줍니다.
새 기능 개발
앞서 설명한 Plan-to-Build 프로세스를 사용하면, 개발자가 기능을 요청하고 어떤 수정도 이루어지기 전에 제안된 단계를 검토할 수 있습니다. Tab을 누르면 작업이 Build 모드로 전환되어 코드 변경과 테스트를 진행합니다.
계획은 파일 변경 이전에 수정할 수 있습니다. 이 검토를 통해 범위를 조정하고, 변경되면 안 되는 파일을 명시하거나, 테스트 요구 사항을 추가하길 권합니다.
기존 코드 리팩터링
동일한 Plan-to-Build 프로세스가 리팩터링에도 유효합니다. Plan 모드는 Build 모드가 수정을 적용하기 전에 의존성과 호출 지점을 파악할 수 있습니다. 결과가 잘못된 경우, /undo로 이전 스냅샷을 복원합니다. 테스트를 통과해도 모든 공개 인터페이스가 그대로인지 보장하지 않으므로, 사용자는 diff를 반드시 검토해야 합니다.
애플리케이션 디버깅
디버깅에서는 OpenCode가 스택 트레이스를 언어 서버의 타입 정보와 결합할 수 있습니다. 변경 사항을 제안하고, 오류를 일으킨 단계를 재현하며, 결과를 확인할 수 있습니다. 재현 단계가 명확하지 않다면, 코드가 빌드되거나 기존 테스트가 통과하는지만 확인하는 데 그칠 수 있습니다.
테스트 작성
앞서 설명했듯 Build 모드는 파일을 수정하고 명령을 실행할 수 있습니다. 테스트 작성의 경우, 테스트를 생성하고, 결과를 읽고, 다시 수정할 수 있다는 의미입니다. 전체 테스트 스위트는 더 많은 피드백을 제공하지만 시간이 더 걸립니다.
테스트 품질은 여전히 사람의 검토가 필요합니다. 생성된 테스트는 구현을 반복할 뿐, 사용자가 의존하는 동작을 검증하지 않을 수 있습니다.
대규모 코드베이스 이해
저장소 섹션에서 /init가 프로젝트 노트를 생성하는 방법을 설명했습니다. 그 다음에는 "여기서 인증은 어떻게 동작하나요?" 같은 질문으로 탐색을 유도할 수 있습니다. @general 하위 에이전트는 저장소의 여러 부분을 검색할 수 있습니다.
저장소 전체 설명을 요청하기보다 구체적인 질문이 보통 더 명확한 결과를 산출합니다. @로 파일을 참조하면 검색 범위를 더 좁힐 수 있습니다.
OpenCode와 다른 AI 코딩 에이전트 비교
이들 도구는 라이선스, 모델 지원, 인터페이스, 과금 방식이 다릅니다. 특정 도구를 기본 선택으로 두기보다 이 지점에서 비교합니다.
OpenCode vs. Claude Code
자세한 내용은 OpenCode 대 Claude Code 비교 글을 참고하세요. Claude Code는 독점 소프트웨어로 Anthropic의 모델과 계정 체계를 사용합니다. OpenCode는 MIT 라이선스를 사용하며 사용자가 제공자를 선택합니다. 소스 코드와 구성을 열람할 수 있다는 점도 다릅니다. 역사 섹션에서 언급했듯 소비자용 Claude 구독은 OpenCode를 통해 더 이상 동작하지 않으므로, Claude 사용에는 Anthropic의 미터형 API 키가 필요합니다.
두 도구 모두 파일을 읽고, 변경하고, 명령을 실행하며, MCP 서버를 사용할 수 있습니다. 주요 차이는 모델 접근입니다. Claude Code는 앞서 설명한 Anthropic 구성에 머무는 반면, OpenCode는 다른 제공자나 로컬 엔드포인트에 연결할 수 있습니다.
OpenCode vs. Cursor
Cursor는 VS Code 기반 IDE로 CLI와 클라우드 에이전트도 제공합니다. 기본 워크플로는 제안, 파일 변경, 에이전트 작업을 에디터 내부에 유지합니다. OpenCode는 앞서 나열한 터미널, 데스크톱, 에디터 인터페이스를 사용합니다. Cursor는 유료 구독 플랜을 사용하고, OpenCode 소프트웨어는 무료이지만 사용자는 토큰에 대해 모델 제공자에게 비용을 지불할 수 있습니다. 주요 차이는 작업 인터페이스, 모델 선택, 과금 방식입니다.
Cursor에는 개발자가 타이핑하는 동안 인라인 자동완성도 포함됩니다. OpenCode는 에이전트에 부여한 작업 중심으로 설계되어 있으며 해당 형태의 자동완성을 대체하지 않습니다. 일부 개발자는 작업 유형에 따라 두 도구를 병행해 사용할 수 있습니다.
OpenCode vs. Cline
Cline의 코어 프로젝트는 VS Code와 CLI 인터페이스를 가진 오픈 소스 BYOK 에이전트입니다. JetBrains 클라이언트도 있지만, 작성 시점에는 오픈 소스가 아닙니다. Cline과 OpenCode는 모두 MCP를 지원하고 승인 규칙을 설정할 수 있습니다. Cline은 에디터 사이드바에 컨트롤을 배치하고, OpenCode는 에디터와 독립적으로 실행될 수 있는 터미널 세션을 사용합니다. 선택은 주로 변경 사항을 검토하고 승인하는 위치의 선호에 달려 있습니다.
Cline은 Apache 2.0 라이선스를, OpenCode는 앞서 언급한 MIT 라이선스를 사용합니다. 두 도구 모두 소스 검토와 변경이 가능하지만, 인터페이스와 프로젝트 파일은 다릅니다.
Aider와 Codex CLI도 터미널 기반 코딩 에이전트입니다. OpenCode는 동일한 프로젝트에서 터미널, 데스크톱, IDE 사용을 모두 포괄하고 여러 제공자의 모델을 지원합니다.
OpenCode 설치 및 시작하기
공식 설치 스크립트는 대부분의 Unix 계열 시스템에서 동작합니다. 커맨드라인 도구를 설치하는 한 가지 방법을 제공합니다.
이 명령은 OpenCode 바이너리를 다운로드하여 사용자 환경에 추가합니다. 업데이트를 시스템의 다른 구성과 함께 관리하려면 패키지 관리자가 더 적합할 수 있습니다.
curl -fsSL https://opencode.ai/install | bash패키지 관리자 옵션으로는 npm i -g opencode-ai@latest, brew install anomalyco/tap/opencode(macOS, Linux), scoop install opencode 또는 choco install opencode (Windows)가 있습니다. 데스크톱 앱은 macOS, Windows, Linux용으로 제공됩니다. Windows에서는 일부 파일 시스템 및 셸 기능이 WSL에서 더 잘 동작하므로 OpenCode 문서는 WSL 사용을 권장합니다.
설치에는 모델 접근이 포함되지 않습니다. 첫 세션에서는 멀티 모델 섹션에서 다룬 접근 방법 중 하나가 여전히 필요합니다.
프로젝트 지침을 만들기 전 OpenCode 설치하기. 영상: 필자 제공.
OpenCode는 정말 무료인가요?
OpenCode에서 Claude 모델을 사용할 수 있나요?
OpenCode는 인터넷 연결 없이도 작동하나요?
보관된 opencode-ai/opencode 저장소가 같은 프로젝트인가요?
OpenCode는 내 소스 코드 프라이버시를 어떻게 처리하나요?
주제