[opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복] 1/12화: opencode란? 벤더 락인 없는 터미널 AI 코딩 에이전트

이 글은 「opencode 12일 집중 — 터미널 네이티브 AI 코딩 에이전트 완전 정복」 1일차로, 벤더 락인 없는 오픈소스 코딩 에이전트의 핵심 개념과 구조를 살펴봅니다.

터미널을 떠나지 않고 코드를 짜는 AI 에이전트, 그런데 모델은 내가 고른다면?

시리즈를 시작하며 — 12일 후 당신의 터미널

AI 코딩 도구 춘추전국시대입니다. Cursor가 에디터를 삼켰고, Claude Code가 터미널에 자리 잡았고, GitHub Copilot은 IDE 사이드바를 꿰찼습니다. 그런데 한 가지 불편한 질문이 남습니다. “이 도구가 내일 가격을 올리거나, 내가 쓰는 모델을 빼 버리면?”

opencode는 그 질문에 대한 오픈소스 커뮤니티의 대답입니다. GitHub 스타 160K 이상을 찍으며 빠르게 성장 중인 이 프로젝트는 BYOK(Bring Your Own Key) 철학 위에 서 있습니다. 어떤 모델을, 어떤 프로바이더를 통해 쓸지는 전적으로 사용자의 선택입니다.

이 시리즈는 12일간 매일 한 편씩, opencode를 입문부터 실무 도입까지 빠르게 격파하는 단기 집중 코스입니다. 전체 흐름은 이렇습니다.

• Phase 1 — 입문 (1~3일차): opencode란 무엇이고, 어떻게 설치하고, 어떤 모델을 붙일 것인가
• Phase 2 — 핵심 사용법 (4~7일차): TUI 인터페이스, Plan/Build 모드, 내장 툴, AGENTS.md 컨텍스트 관리
• Phase 3 — 확장·고급 (8~12일차): 커스텀 커맨드, MCP 연동, 헤드리스 자동화, 멀티세션, 로컬 모델과 규제 환경 운영

금융IT 실무 관점에서 사내 도입 가능성까지 함께 짚을 예정이니, 규제 산업에 계신 분들도 끝까지 따라와 주세요.

오늘의 핵심 3가지

• opencode는 오픈소스·BYOK·멀티 서피스 AI 코딩 에이전트다. 75개 이상의 프로바이더를 지원하며, 특정 벤더에 종속되지 않는다.
• 터미널(TUI)이 1차 인터페이스지만 데스크톱·IDE로도 확장된다. Go의 Bubble Tea 프레임워크로 만든 TUI는 가볍고 빠르다.
• Claude Code·Cursor·Codex와는 “소유권”에서 결정적으로 다르다. 코드도, 모델 선택도, 인프라 배치도 사용자가 쥔다.

opencode란 무엇인가

한 줄 정의

opencode는 터미널 네이티브 AI 코딩 에이전트입니다. 터미널에서 프롬프트를 입력하면 AI가 코드를 읽고, 수정하고, 파일을 만들고, 셸 명령을 실행합니다. 여기까지는 Claude Code나 Codex와 비슷해 보일 수 있습니다. 결정적 차이는 세 단어로 요약됩니다: 오픈소스, BYOK, 멀티 서피스.

오픈소스 — 코드가 공개되어 있다는 것의 의미

opencode의 소스 코드는 GitHub에 전부 공개되어 있습니다. 160K 이상의 스타를 받으며 활발하게 개발되고 있죠. 오픈소스라는 사실은 단순히 “공짜”를 넘어 몇 가지 실질적인 이점을 줍니다.

• 감사 가능성(Auditability): 에이전트가 내 코드를 어디로 보내는지, 어떤 데이터를 수집하는지 직접 코드를 읽어 확인할 수 있습니다. 금융·의료 같은 규제 산업에서는 이 한 가지만으로도 도입 장벽이 크게 낮아집니다.
• 커스터마이징: 조직의 보안 정책에 맞춰 특정 기능을 끄거나, 내부 시스템과의 연동 로직을 직접 추가할 수 있습니다.
• 지속성: 특정 회사의 사업 결정에 프로젝트의 운명이 좌우되지 않습니다. 커뮤니티가 살아 있는 한, 도구도 살아 있습니다.

BYOK — 내 키, 내 모델, 내 선택

BYOK는 Bring Your Own Key의 약자입니다. opencode 자체는 AI 모델을 제공하지 않습니다. 대신 사용자가 자신의 API 키를 가져와서 원하는 모델을 연결합니다. 지원하는 프로바이더는 75개 이상입니다.

• Anthropic (Claude 시리즈)
• OpenAI (GPT-4o, o3 등)
• Google (Gemini)
• AWS Bedrock
• OpenRouter
• 그 외 수십 개의 프로바이더와 로컬 엔드포인트(Ollama 등)

이것이 왜 중요할까요? 프로바이더별로 가격, 성능, 정책이 다릅니다. 어떤 작업에는 Claude가 낫고, 어떤 작업에는 Gemini가 비용 대비 효율적입니다. opencode는 이 선택을 사용자에게 돌려줍니다. 한 프로바이더의 가격 인상이 곧 도구의 사용 중단을 의미하지 않습니다. 키만 바꾸면 됩니다.

멀티 서피스 — 터미널만이 아니다

opencode의 1차 인터페이스는 터미널 TUI(Text User Interface)입니다. Go 언어의 Bubble Tea 프레임워크로 만들어져 가볍고, 반응이 빠르고, SSH 세션에서도 돌아갑니다. 하지만 여기서 끝이 아닙니다. opencode는 데스크톱 앱과 IDE 확장으로도 제공됩니다. 같은 설정, 같은 AGENTS.md, 같은 워크플로우를 어느 환경에서든 이어갈 수 있다는 뜻입니다.

서버에 SSH로 붙어서 작업할 때는 TUI, 로컬에서 여유롭게 작업할 때는 데스크톱 앱, 기존 에디터 워크플로우를 유지하고 싶을 때는 IDE 확장. 상황에 맞는 서피스를 고르면 됩니다.

왜 지금 opencode인가 — AI 코딩 도구 지형도

2025~2026, AI 코딩 에이전트 시장의 폭발

지난 1년간 AI 코딩 도구 시장은 그야말로 폭발적으로 성장했습니다. 주요 플레이어를 살펴보면 상황이 명확해집니다.

Cursor는 VS Code를 포크해서 AI를 에디터 깊숙이 통합한 제품입니다. Tab 자동완성, 인라인 편집, 채팅 등 풍부한 UI를 제공하지만, 월 구독료가 발생하고, 에디터 자체를 갈아타야 합니다. VS Code 생태계를 기반으로 하면서도 본질적으로는 하나의 상용 제품에 종속되는 구조입니다.

Claude Code는 Anthropic이 만든 터미널 기반 코딩 에이전트입니다. Claude 모델의 강력한 코딩 능력을 터미널에서 바로 쓸 수 있게 해 주죠. 하지만 Anthropic의 MAX 구독 또는 API 키가 필수이고, 다른 프로바이더의 모델을 쓸 수 없습니다. 모델 선택지가 Claude로 고정됩니다.

OpenAI Codex(CLI)는 OpenAI가 내놓은 터미널 에이전트입니다. 당연히 OpenAI 모델에 묶여 있고, 아직은 초기 단계입니다. Claude Code와 마찬가지로 특정 프로바이더에 종속된 구조입니다.

이 도구들은 각각 훌륭하지만, 공통적인 한계가 있습니다. 벤더 락인(vendor lock-in)입니다.

벤더 락인이 왜 문제인가

벤더 락인은 개인 개발자에게는 불편함 정도일 수 있습니다. 하지만 조직 단위로 보면 리스크입니다.

• 비용 통제 불가: 프로바이더가 가격을 올리면 그대로 받아들이거나, 도구 자체를 바꿔야 합니다. 도구를 바꾼다는 건 워크플로우·설정·학습 비용을 모두 리셋한다는 뜻입니다.
• 모델 성능 역전: AI 모델 시장에서는 “최고의 모델”이 수시로 바뀝니다. 도구가 특정 모델에 묶여 있으면, 더 나은 모델이 나와도 갈아탈 수 없습니다.
• 정책 변경 리스크: 서비스 약관 변경, 데이터 처리 정책 변경 등이 발생했을 때 대안이 없습니다.
• 규제 대응: 금융·의료·공공 분야에서는 특정 클라우드 리전이나 프로바이더만 허용되는 경우가 있습니다. 도구가 프로바이더를 강제하면 규제 요건과 충돌할 수 있습니다.

opencode의 BYOK 구조는 이 문제를 구조적으로 해결합니다. 도구와 모델이 분리되어 있으므로, 모델을 바꿔도 도구는 그대로입니다. 설정 파일에서 프로바이더와 모델명만 변경하면 됩니다.

한눈에 비교 — opencode vs Claude Code vs Cursor vs Codex

말로 설명하는 것보다 표 한 장이 빠릅니다. AI 코딩 에이전트 선택 시 실질적으로 따져야 할 항목들을 정리했습니다.

항목	opencode	Claude Code	Cursor	Codex (OpenAI CLI)
라이선스	오픈소스	프로프라이어터리	프로프라이어터리	오픈소스
모델 선택	75+ 프로바이더 자유 선택	Claude 전용	복수 모델 (제한적)	OpenAI 전용
과금 구조	BYOK (API 키 직접 관리)	MAX 구독 또는 API 키	월 구독 ($20~$40)	API 키 (사용량 기반)
1차 인터페이스	터미널 TUI	터미널 CLI	에디터 (VS Code 포크)	터미널 CLI
추가 서피스	데스크톱 앱, IDE 확장	IDE 확장 (제한적)	에디터 단일	CLI 단일
TUI 프레임워크	Go Bubble Tea	Node.js Ink	Electron	Node.js
컨텍스트 관리	AGENTS.md	CLAUDE.md	.cursorrules	AGENTS.md
비대화형 실행	opencode run, serve (HTTP)	claude -p (파이프)	없음	codex -q
MCP 지원	지원	지원	지원	지원
자체 호스팅	가능	불가	불가	가능
벤더 락인	없음	Anthropic	Cursor Inc.	OpenAI
에어갭 환경	Ollama 등 로컬 모델 가능	불가	불가	제한적

비교표에서 읽어야 할 것

표를 보면 opencode가 모든 면에서 우월하다는 뜻이 아닙니다. 각 도구는 자신의 생태계 안에서 최적화되어 있습니다. Claude Code를 쓰면 Claude 모델의 능력을 100% 활용하는 데 최적화된 경험을 얻습니다. Cursor는 에디터 통합이 뛰어나서 코드 작성 흐름이 끊기지 않습니다.

opencode의 진짜 강점은 “선택의 유연성”입니다. 오늘은 Claude를 쓰다가 내일은 GPT-4o로, 다음 달에는 비용 절감을 위해 Gemini Flash로 바꿀 수 있습니다. 도구를 바꾸지 않고요. 이것은 특히 다음 상황에서 빛납니다.

• 여러 프로바이더의 모델을 비교 평가해야 하는 팀
• 프로바이더 변경 가능성을 열어 두어야 하는 조직
• 에어갭(망분리) 환경에서 로컬 모델만 써야 하는 규제 산업
• 단일 도구에 대한 의존도를 줄이고 싶은 개인 개발자

opencode의 핵심 구조 들여다보기

TUI — Bubble Tea 위의 코딩 에이전트

opencode의 터미널 인터페이스는 Go 언어의 Bubble Tea 프레임워크 위에 만들어졌습니다. Bubble Tea는 The Elm Architecture에서 영감을 받은 TUI 프레임워크로, 상태 관리가 깔끔하고 렌더링이 빠릅니다.

실용적으로 이것이 의미하는 바는 이렇습니다.

• 빠른 시작: Go로 컴파일된 단일 바이너리이므로 의존성 설치 없이 바로 실행됩니다. Node.js 런타임이 필요한 Claude Code와 대조됩니다.
• 낮은 리소스 사용: Electron이나 Node.js 기반 도구에 비해 메모리 사용량이 현저히 적습니다.
• SSH 호환: 원격 서버에 SSH로 접속해서 바로 사용할 수 있습니다. 별도의 포트 포워딩이나 X11 포워딩이 필요 없습니다.
• 마우스 지원: 터미널 앱이지만 마우스 클릭과 스크롤도 지원합니다.

Plan 모드와 Build 모드 — Tab 하나로 전환

opencode에는 두 가지 핵심 동작 모드가 있습니다.

• Plan 모드: AI가 코드를 읽고 분석하지만, 실제로 파일을 수정하거나 명령을 실행하지 않습니다. 읽기 전용 탐색 모드입니다. 낯선 코드베이스를 파악할 때, 변경 계획을 세울 때 사용합니다.
• Build 모드: AI가 실제로 파일을 만들고, 수정하고, 셸 명령을 실행합니다. 구현 모드입니다.

두 모드 사이의 전환은 Tab 키 한 번입니다. “먼저 Plan으로 구조를 파악하고, 확신이 서면 Build로 전환해서 실행”이라는 자연스러운 워크플로우가 만들어집니다. 5일차에서 이 워크플로우를 실전 시나리오로 다룰 예정입니다.

AGENTS.md — 프로젝트 컨텍스트의 핵심

opencode는 프로젝트의 컨텍스트를 AGENTS.md 파일로 관리합니다. 이 파일은 프로젝트 루트에 놓이며, AI에게 프로젝트의 구조, 규칙, 주의사항 등을 알려주는 역할을 합니다. Claude Code의 CLAUDE.md, Cursor의 .cursorrules와 같은 개념이지만, opencode는 /init 명령 한 번으로 프로젝트를 스캔해서 초안을 자동 생성해 줍니다.

AGENTS.md의 진정한 가치는 팀 공유에 있습니다. 이 파일을 Git에 커밋해 두면, 팀원 누구나 같은 컨텍스트로 AI를 사용할 수 있습니다. 7일차에서 모범 템플릿과 팀 공유 전략을 상세히 다루겠습니다.

내장 도구 — 읽고, 쓰고, 검색하고, 실행하고

opencode에 내장된 도구들은 코딩 에이전트가 실제로 “일”을 할 수 있게 해 주는 손과 발입니다.

• 파일 조작: read, write, edit, patch — 파일을 읽고, 만들고, 부분 수정합니다.
• 셸 실행: ! 접두사로 터미널 명령을 직접 실행합니다.
• 검색: grep, glob으로 코드베이스를 빠르게 탐색합니다.
• LSP 연동: 정의로 이동, 참조 찾기 등 Language Server Protocol 기반 탐색을 지원합니다.

이 도구들은 6일차에서 하나씩 실습할 예정입니다.

비대화형 실행과 자동화

opencode는 대화형 TUI만 있는 것이 아닙니다. 자동화를 위한 비대화형 모드도 갖추고 있습니다.

• opencode run: 프롬프트를 인자로 넘기고 결과만 받습니다.
• -q 플래그: 조용한 모드. 불필요한 출력을 제거합니다.
• -f json: 출력을 JSON 형식으로 받아 파이프라인에 연결합니다.
• opencode serve: 헤드리스 HTTP 서버로 띄워 OpenAPI 스펙의 API를 노출합니다.
• @opencode-ai/sdk: JavaScript/TypeScript SDK로 프로그래매틱하게 제어합니다.

CI/CD 파이프라인, 코드 리뷰 자동화, 이슈 대응 봇 등 다양한 자동화 시나리오에 활용할 수 있습니다. GitHub Actions에서는 이슈 코멘트에 /opencode를 적으면 에이전트가 실행되는 통합도 제공합니다. 10일차와 11일차에서 이 주제를 깊이 다룹니다.

opencode를 선택해야 하는 사람, 그리고 아닌 사람

opencode가 딱 맞는 경우

• 터미널 중심 워크플로우를 가진 개발자: vim/neovim, tmux, 터미널 멀티플렉서를 주력으로 쓰는 분이라면 opencode는 자연스럽게 기존 환경에 녹아듭니다.
• 멀티 프로바이더 전략을 취하는 팀: 작업 유형이나 비용에 따라 모델을 바꿔 쓰고 싶은 팀에게 BYOK 구조는 필수입니다.
• 자체 호스팅이 필요한 환경: 보안 정책상 외부 SaaS를 쓸 수 없거나, 데이터가 외부로 나가면 안 되는 환경에서 opencode + 로컬 모델 조합은 현실적인 선택지입니다.
• CI/CD·자동화 통합이 목표인 DevOps 엔지니어: opencode serve의 OpenAPI 인터페이스와 SDK는 자동화 파이프라인 구축을 수월하게 합니다.
• 오픈소스 투명성을 중시하는 조직: 코드 감사가 가능하므로 규제 요건 충족이 상대적으로 용이합니다.

다른 선택이 나을 수 있는 경우

• 특정 모델에 이미 올인한 개인: Claude MAX 구독을 쓰고 있고 다른 모델을 쓸 계획이 없다면, Claude Code가 더 매끄러운 경험을 줄 수 있습니다.
• GUI 에디터를 절대 떠나기 싫은 분: Cursor나 Windsurf처럼 에디터 자체에 AI가 녹아든 환경을 선호한다면, 터미널 TUI는 적응이 필요합니다.
• 제로 설정을 원하는 입문자: BYOK 구조는 API 키 발급, 모델 선택, 설정 파일 작성 등 초기 셋업 단계가 있습니다. “설치하면 바로 되는” 경험을 원한다면 진입 장벽을 느낄 수 있습니다.

물론 이 시리즈를 따라오시면, 그 진입 장벽을 최대한 낮춰 드리는 것이 목표입니다.

실습 — opencode 첫 실행 맛보기

오늘은 개관이 주제이므로 설치와 설정의 상세한 내용은 내일 2일차에서 다룹니다. 하지만 “일단 돌려 보고 싶다”는 분을 위해 가장 빠른 설치 경로를 하나 남깁니다.

# macOS / Linux — curl 원라이너 설치
curl -fsSL https://opencode.ai/install | bash

# 설치 확인
opencode --version

# 프로젝트 디렉토리에서 첫 실행
cd ~/my-project
opencode

# TUI가 뜨면:
#   Tab  → Plan ↔ Build 전환
#   @    → 파일 퍼지 검색
#   /init → AGENTS.md 자동 생성
#   ctrl+x → leader 키 (단축키 허브)

Windows에서는 WSL 환경을 가정합니다. WSL2 + Ubuntu가 설치되어 있다면 위 명령을 그대로 사용할 수 있습니다. 네이티브 Windows(Scoop, Chocolatey)도 지원하며, 2일차에서 5가지 설치 방법을 비교합니다.

첫 실행 후 API 키가 없으면 opencode auth login으로 인증 흐름을 시작합니다. 이 부분 역시 2일차에서 안내합니다.

Gotcha 미니 코너 — 첫날의 함정

“opencode를 실행했는데 모델이 응답하지 않아요.”

opencode는 BYOK입니다. 설치만 하면 끝이 아니라, API 키 설정까지 마쳐야 모델이 동작합니다. 첫 실행 시 TUI 화면은 뜨지만, 프롬프트를 보내면 에러가 나거나 응답이 없을 수 있습니다. 이유는 단순합니다 — 아직 어떤 프로바이더에도 연결되지 않은 상태이기 때문입니다.

해결은 간단합니다. opencode auth login을 실행하거나, 환경 변수로 API 키를 설정하세요. 3일차에서 프로바이더별 키 설정과 모델 선택을 상세히 다루니, 오늘은 “설치 = 즉시 사용”이 아니라는 점만 기억해 두세요.

12일 로드맵 한눈에 보기

매일 어떤 주제를 다루는지 미리 확인하고, 관심 있는 회차를 북마크해 두세요.

일차	단계	주제
1	입문	opencode란 무엇인가 — 오늘 이 글
2	입문	설치 5가지 + 첫 인증 흐름
3	입문	BYOK 모델 선택과 비용 시뮬레이션
4	핵심	TUI 단축키 마스터 + 테마 커스터마이징
5	핵심	Plan → Build 워크플로우 실전
6	핵심	내장 도구 완전 정복 (read/write/grep/LSP)
7	핵심	AGENTS.md 모범 템플릿과 팀 공유
8	확장	커스텀 커맨드와 슬래시 명령
9	확장	MCP 연동 — 사내 시스템과 AI 연결
10	확장	opencode serve + SDK로 자동화
11	확장	멀티세션·서브에이전트·GitHub Actions
12	확장	로컬 모델·에어갭·규제 환경 운영

마무리 — 내일 예고

오늘은 opencode가 무엇이고, AI 코딩 에이전트 시장에서 어떤 위치에 있으며, 왜 지금 주목할 만한지를 훑었습니다. 비교표 하나로 Claude Code·Cursor·Codex와의 차이가 선명해졌길 바랍니다.

내일 2일차에서는 opencode를 실제로 설치합니다. curl·npm·Homebrew·Scoop·Arch 다섯 가지 설치 경로를 비교하고, opencode auth login부터 /init으로 AGENTS.md를 생성하는 것까지 — 복사·붙여넣기만으로 첫 세션을 시작하는 데 필요한 전부를 다룹니다.

---