OpenCode는 터미널 UI에서 모델과 대화하며 파일 수정, 명령 실행, 코드 탐색을 수행하는 오픈소스 코딩 에이전트입니다. LSP와 프로젝트 지침 파일을 활용할 수 있고 여러 모델 공급자를 선택할 수 있지만, 연결 방식과 지원 기능은 버전별로 확인해야 합니다. 실제 도입에서는 시작 속도보다 저장소 쓰기, 셸 실행 권한, 외부 모델로 전송되는 코드, 테스트와 diff 검증을 먼저 따져야 합니다.
OpenCode는 어떤 개발자에게 맞을까: 터미널 에이전트의 설치와 권한
OpenCode는 일반 코드 챗봇과 무엇이 다른가?
OpenCode는 터미널 환경(CLI)에서 동작하는 AI 코딩 에이전트입니다. 단순히 챗봇과 대화하는 것이 아니라, AI가 실제 개발자처럼 파일을 수정하고, 명령어를 실행하고, 프로젝트 전체를 분석합니다.
Go 기반 TUI와 모델 추상화가 주요 특징입니다. 다만 Go로 작성됐다는 사실만으로 전체 작업이 빠르다고 단정할 수는 없습니다. 응답 지연은 연결한 모델, 전송한 context, 실행한 빌드와 테스트 시간에 크게 좌우됩니다.
선택 이유는 무엇인가?
- 모델 선택: 설정이 지원하는 범위에서 공급자와 로컬 모델을 바꿀 수 있습니다.
- LSP 통합: 단순 텍스트 예측이 아니라, IDE처럼 코드의 문법과 참조를 이해합니다.
- 컨텍스트 관리:
AGENTS.md파일로 프로젝트의 규칙과 구조를 작업마다 전달할 수 있습니다.
어떤 기능이 실제 코드 변경을 돕는가?
원문 저장소와 문서에 소개된 기능은 다음과 같습니다.
2.1. 모델 호환성
OpenCode는 여러 모델 공급자를 공통 작업 흐름에 연결합니다. 아래 목록과 모델 이름은 글 작성 시점의 예시이므로 현재 지원 여부를 설치 전에 확인해야 합니다.
- 클라우드 모델: OpenAI (GPT-4o), Anthropic (Claude 3.5 Sonnet), Google (Gemini Pro), Groq (초고속 추론)
- 로컬 모델: Ollama를 통한 Llama 3, Mistral 등의 로컬 LLM 구동 지원 (보안이 중요한 기업 환경에 적합)
- GitHub Copilot: 기존 Copilot 구독 계정을 연동하여 사용 가능
2.2. TUI와 세션
Bubble Tea 기반 UI는 마우스, 스크롤, 문법 하이라이팅과 세션 기능을 제공하는 것으로 소개됩니다.
- Vim 스타일 편집: 내장 에디터를 통해 AI의 제안을 즉석에서 수정하거나 메시지를 작성할 수 있습니다.
- 세션 관리:
Ctrl+N으로 새로운 작업을 시작하고,Ctrl+S로 현재 작업을 저장하며, 언제든 이전 세션을 불러올 수 있습니다.
2.3. 컨텍스트 관리
- Auto Compact: 대화가 길어져 토큰 한도에 도달하면, OpenCode가 자동으로 대화 내용을 요약하여 컨텍스트를 유지하면서 토큰 비용을 절약합니다.
- AGENTS.md: 프로젝트 루트의 지침을 읽어 아키텍처, 코딩 규칙, 사용 라이브러리를 작업 조건으로 활용합니다. 오래된 지침이나 비밀 정보를 넣지 않도록 검토해야 합니다.
2.4. 도구 통합
에이전트는 허용된 범위에서 실제 작업 공간의 도구를 실행할 수 있습니다.
- 명령어 실행: 빌드, 테스트, 배포 명령을 AI가 직접 수행하고 결과를 분석합니다.
- 파일 조작: 코드를 작성하고 수정하며,
rg(ripgrep) 등을 사용해 코드베이스를 검색합니다. - LSP 지원: 언어 서버에서 정의와 참조 정보를 얻습니다. LSP가 코드 생성 오류를 자동으로 제거하는 것은 아닙니다.
내부 구조는 모델과 터미널 UI를 어떻게 분리하나?
개발자로서 OpenCode의 내부가 어떻게 돌아가는지 이해하면 더 잘 활용할 수 있습니다.
클라이언트-서버 구조 (Client-Server)
OpenCode는 Core Logic과 Interface를 분리한 구조로 소개됩니다. 원격 제어 가능성을 현재 제공되는 안전한 원격 운영 기능으로 해석해서는 안 되며, 실제 binding, 인증, 네트워크 설정을 확인해야 합니다.
Go + Bubble Tea
OpenCode는 Go로 컴파일된 바이너리 형태입니다. 실제 메모리에는 TUI뿐 아니라 언어 서버, 모델 context, 실행한 개발 도구가 포함되므로 대상 프로젝트에서 측정해야 합니다.
LLM 추상화 계층
internal/llm 패키지는 다양한 공급자(OpenAI, Claude 등)를 표준화된 인터페이스로 묶습니다. 새로운 모델이 나와도 OpenCode 코어 로직을 수정할 필요 없이 어댑터만 추가하면 되는 구조입니다.
설치 전에 어떤 명령과 버전을 확인해야 하나?
아래 명령은 원문 시점의 설치 스냅샷입니다. 현재 저장소와 문서에서 패키지 이름, 요구 버전, 설치 스크립트 내용을 먼저 대조해야 합니다.
4.1. 설치 (Installation)
Mac & Linux (Homebrew 권장) 가장 관리가 쉬운 방법입니다. 전용 탭(Tap)을 추가하여 설치합니다.
1
brew install opencode-ai/tap/opencode
자동 설치 스크립트 (Mac/Linux) 빠르게 설치하고 싶다면 curl 스크립트를 사용하세요.
1
curl -fsSL https://opencode.ai/install | bash
Go 개발자라면 (go install) Go 1.22 이상이 설치되어 있다면 직접 빌드하여 설치할 수 있습니다.
1
go install github.com/opencode-ai/opencode@latest
Windows Windows 사용자는 Scoop을 사용하거나 릴리스 페이지에서 바이너리를 다운로드할 수 있습니다.
1
scoop install opencode
4.2. 설정 (Configuration)
설치 후 가장 먼저 해야 할 일은 인증 및 모델 설정입니다.
- 초기화 및 로그인: 터미널에서 다음 명령어를 입력하여 대화형 설정 마법사를 시작합니다.
1
opencode auth login
이 과정에서 GitHub 계정으로 로그인하거나,
OpenCode Zen(OpenCode 팀이 큐레이팅한 모델 서비스)을 사용할 수 있습니다. - 개별 API 키 설정 (고급 사용자): 만약 본인의 OpenAI 키나 Anthropic 키를 직접 사용하고 싶다면, 환경 변수나 설정 파일(
~/.config/opencode/config.json)을 수정하면 됩니다.1 2
export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-proj-..."
- 프로젝트 초기화: 작업하려는 프로젝트 폴더로 이동하여 초기화를 진행합니다.
1 2
cd /path/to/my-project opencode /init이 명령은 프로젝트 구조를 바탕으로
AGENTS.md를 만들 수 있습니다. 생성 내용을 검토하고 비밀, 로컬 경로를 제거한 뒤 공유 여부를 결정해야 합니다.
첫 코드 변경은 어떤 순서로 검증해야 하나?
설치 뒤에는 별도 브랜치와 작은 읽기 작업부터 시작합니다. 파일 쓰기와 셸 권한은 테스트, diff, 복구 흐름을 확인한 뒤에 넓히는 편이 안전합니다.
기본 실행
1
opencode
터미널이 TUI 모드로 전환되며 대화창이 나타납니다. 자연어로 명령을 내리면 됩니다.
- “이 프로젝트의
main.go에서 에러 핸들링 부분을 리팩토링해줘.” - “현재 디렉토리의 모든 테스트를 실행하고 실패한 이유를 분석해.”
주요 단축키 및 명령어
- Tab: 에이전트 모드 전환 (코딩 에이전트 <-> 일반 챗봇 등)
- Ctrl+N: 새 세션 시작 (컨텍스트 초기화)
- Ctrl+S: 세션 저장
- @general: 복잡한 검색이나 다단계 추론이 필요할 때 호출하는 서브 에이전트
논-인터랙티브 모드 (파이프라인 활용)
OpenCode는 파이프라인으로도 사용할 수 있습니다. CI/CD 스크립트나 자동화 작업에 유용합니다.
1
2
# 커밋 메시지 자동 생성
git diff | opencode "이 변경사항에 대한 커밋 메시지를 작성해줘"
GitHub 통합 활용
GitHub 이슈나 PR 연동은 별도 설정과 계정 권한이 필요합니다. 읽기, 쓰기, 병합 권한을 분리하고 외부 변경은 사람이 검토하도록 구성해야 합니다.
어떤 작업부터 맡기는 것이 적절할까?
시나리오 A: 레거시 코드 분석 및 문서화 새로운 회사에 입사했는데 문서가 하나도 없는 상황을 가정해 봅시다.
opencode /init으로 전체 구조 파악.- “@general
auth관련 로직이 어디에 있는지 찾아서 흐름도를 설명해줘”라고 명령. - OpenCode가
grep과 LSP를 이용해 호출 관계를 파악하고 요약해 줍니다.
시나리오 B: 반복적인 테스트 수정 기능을 변경하여 수십 개의 테스트가 깨졌습니다.
- “
go test ./...를 실행하고 실패한 테스트를 하나씩 고쳐줘.” - OpenCode는 테스트를 실행하고, 에러 로그를 읽은 뒤, 소스 코드를 수정하고 다시 테스트를 돌리는 과정을 반복(Agent Loop)하여 모든 테스트를 통과시킵니다.
다른 터미널 도구와 비교할 기준은 무엇인가?
| 특징 | OpenCode | GitHub Copilot CLI | Aider |
|---|---|---|---|
| 기반 언어 | Go | Node.js | Python |
| 모델 지원 | 설정, 버전별 확인 | 서비스 범위 확인 | 설정, 버전별 확인 |
| LSP 지원 | 제공 범위 확인 | 제공 범위 확인 | 제공 범위 확인 |
| UX/UI | TUI (Bubble Tea) | CLI 텍스트 위주 | CLI 텍스트 위주 |
| 설치 편의성 | 바이너리 하나 | npm 필요 | Python/pip 필요 |
장점:
- 터미널 안에서 모델, 도구, 프로젝트 지침을 연결할 수 있다.
AGENTS.md로 팀 규칙을 명시할 수 있다.- LSP 정보를 코드 탐색에 활용할 수 있다.
단점:
- 아직 초기 단계라 버그가 있을 수 있다.
- IDE(VS Code 등) 플러그인 형태가 아니므로, 터미널 사용이 익숙지 않은 개발자에겐 진입 장벽이 있다.
결론: OpenCode를 선택해도 되는 조건은 무엇인가?
OpenCode는 터미널 중심 작업, 모델 선택, LSP 탐색과 프로젝트 지침을 한 흐름으로 묶고 싶은 개발자에게 후보가 될 수 있습니다. 반대로 IDE 통합이 우선이거나 저장소와 외부 모델 사이의 데이터 전송을 허용할 수 없다면 다른 구성이 더 적합할 수 있습니다.
채택 전에는 대표 수정에서 계획의 정확성, 불필요한 diff, 테스트 성공과 실패 복구, 토큰, API 비용, 민감한 파일 제외를 기록해야 합니다. 에이전트의 완료 문장보다 실제 diff와 테스트 로그를 우선하고, 배포, 커밋, 외부 메시지는 별도의 승인 단계로 남겨야 합니다.
함께 읽으면 이해가 이어지는 글
- Destructive Command Guard: AI 코딩 에이전트의 터미널 명령어 실행을 통제하는 안전 계층 설계 — AI 에이전트(Claude Code, Cursor 등)가 실행하는 파괴적인 셸 명령어를 서브 밀리초 단위로 사전 차단하고, 텍스트 피드백을 통해 AI가 스스로 안전한 명령어로 우회할 수 있도록 돕는 오픈소스 가드레일…
- herdr: 쏟아지는 AI 코딩 에이전트를 통제하는 터미널 멀티플렉서 — 기존 터미널 멀티플렉서의 한계를 넘어, AI 에이전트의 작업 상태(대기, 작업 중, 완료)를 실시간으로 자동 추적하고 제어하는 herdr의 구조와 활용법을 알아봅니다.
- prime-agent: 지속형 파이썬 커널과 재귀적 서브에이전트로 구축하는 자가개선 AI 코딩 하네스 — prime-agent는 영속적인 IPython 커널을 단일 도구 인터페이스로 활용하여 AI 에이전트가 코드와 상태를 파이썬 변수로 유지할 수 있게 만든 오픈소스 코딩 하네스입니다. 재귀적 언어 모델(RLM) 구조를 통해 서브에이전트를…
표지 1 —
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.