OpenCode | 설치와 TUI 사용

OpenCode, Go, Zen의 세 층

초보가 가장 먼저 섞는 지점은 이름이 세 곳에 겹친다는 것이다. OpenCode는 에이전트 본체다. Go는 그 안의 선택 공급자 구독이다. Zen은 종량제 게이트웨이다. 세 이름이 같은 도메인에 있어서, Go를 결제해야 OpenCode가 켜진다고 읽기 쉽다. 공식 Go 문서는 다른 제공자와 똑같이 동작하며 완전히 선택 사항이라고 못 박는다.

본체만 깔면 TUI 창은 뜬다. 질문에 모델이 붙으려면 공급자 키가 하나 이상 있어야 한다. 이미 Anthropic이나 OpenAI 키가 있으면 그것을 먼저 쓴다. 여러 오픈 모델을 월정액으로 묶고 싶을 때 Go를 추가한다. Go 한도를 넘긴 뒤에도 같은 콘솔에서 쓰거나, Go 목록에 없는 모델을 쓰려면 Zen 잔액이다.

인수 없이 opencode를 치면 TUI가 기본으로 열린다. 입력칸에 한국어로 적어도 된다. 폴더 안의 코드를 설명하라고 묻거나, 기능을 추가하라고 맡기거나, @파일경로로 범위를 좁힌다. 한 파일을 설명하라는 짧은 질문은 토큰이 적다. 레포 전체를 한 번에 고쳐 달라는 문장은 Plan 모드에서 먼저 쪼개는 경우가 많다.

같은 바이너리로 비대화형 한 번도 된다. opencode run 뒤에 문장을 붙이면 TUI 없이 한 번 돌고 끝난다. 스크립트나 CI가 이 경로다. serve는 헤드리스 HTTP 백엔드이고, web은 브라우저 UI다. attach는 이미 떠 있는 백엔드에 터미널을 붙인다. 데스크톱 앱도 같은 바이너리를 쓴다. 설치 확인은 여전히 opencode --version이다.

Cursor를 지우는 대체가 아니다. 공식 IDE 문서는 VS Code와 Cursor, Windsurf, VSCodium처럼 터미널을 지원하는 포크에서 확장을 붙인다고 적는다. 에디터 채팅이 레포를 고치는 일과, 통합 터미널의 TUI가 같은 폴더를 고치는 일은 창이 다르다. 로그인도 키가 다르다. Cursor 계정으로 OpenCode TUI가 켜지지는 않는다.

공식 소개가 예로 드는 터미널은 WezTerm, Alacritty, Ghostty, Kitty다. Windows 기본 콘솔만으로도 설치는 된다. Git Bash가 있으면 셸 도구가 덜 깨지고, 경로를 OPENCODE_GIT_BASH_PATH로 넘기는 환경 변수가 CLI 문서에 있다.

설치와 PATH 확인

macOS와 Linux에서 공식 소개가 가장 짧다고 적은 방법은 설치 스크립트다. bash가 있는 환경에서 한 줄을 파이프로 넘긴다.

curl -fsSL https://opencode.ai/install | bash

Windows에서 Git Bash가 없으면 이 줄은 bash를 찾지 못해 실패한다. 공식 Windows 절의 주 목록은 Chocolatey, Scoop, npm이다. Chocolatey는 관리자 PowerShell에서 choco가 잡혀 있어야 하고, Scoop은 사용자 권한으로 scoop이 PATH에 있어야 한다. 패키지 매니저가 없는 상태에서 그 명령을 치면 OpenCode가 없는 것이 아니라 매니저가 없는 것이다.

2026년 7월 27일 실측은 npm 전역이었다. 그 경로를 쓰려면 Node.js가 먼저 있어야 한다. Node가 없으면 npm 자체가 명령으로 잡히지 않는다. LTS 설치는 nodejs.org다. 설치 직후 새 PowerShell을 열어야 PATH가 갱신되는 경우가 있다.

Node가 준비된 뒤 Windows에서 7월 실측이 쓴 줄은 아래와 같다.

npm install -g opencode-ai

설치 직후 PowerShell에서 opencode를 쳤을 때 'opencode'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.가 나오면 바이너리가 없는 것이 아니라 PATH가 빠진 경우가 많다. npm 전역 접두는 보통 %AppData%\Roaming\npm이다. 그 폴더가 사용자 PATH에 없으면 셸이 opencode.cmd를 찾지 못한다.

PATH가 잡혔는지는 두 명령으로 본다. opencode --version이 숫자를 찍고, where.exe opencode가 C:\Users\<이름>\AppData\Roaming\npm\opencode.cmd를 가리키면 된 것이다. 7월 실측 버전은 1.18.7이었다. 지금 숫자는 그 명령이 찍는 값이 맞다. npm config get prefix가 찍는 경로가 PATH에 들어 있는지도 같이 본다.

opencode --version
where.exe opencode
npm config get prefix

Homebrew는 brew install opencode가 아니다. 공식 문서는 tap anomalyco/tap/opencode를 적는다. brew 기본 formula는 업데이트가 느리다고 문서가 밝힌다. Mise는 mise use -g github:anomalyco/opencode다. Docker는 docker run -it --rm ghcr.io/anomalyco/opencode로 컨테이너 한 번 실행이다. Arch는 pacman -S opencode와 AUR opencode-bin이 있다. 릴리스 페이지에서 바이너리를 받아도 된다.

Windows에서 Bun으로 까는 일은 문서가 준비 중이라고 적는다. Git Bash가 있는 Windows에서 curl 스크립트를 쓰거나, 셸 도구가 깨질 때는 CLI 문서의 OPENCODE_GIT_BASH_PATH에 bash 실행 파일 경로를 넣는다.

위키에 나온 open 단축은 npm 전역 폴더에 만든 로컬 래퍼다. 공식 명령이 아니고, macOS 파일 열기 open과 이름이 겹친다. 실행 파일 이름은 opencode다.

업그레이드는 opencode upgrade다. 특정 버전을 고정할 때는 opencode upgrade v0.1.48처럼 태그를 붙인다. CI나 팀에서 버전을 맞춰 둘 때 쓴다. --method로 curl, npm, pnpm, bun, brew를 고른다. 제거는 opencode uninstall이다. 키와 설정은 남기고 바이너리만 지울 때 --keep-config를, 세션 기록까지 남길 때 --keep-data를 붙인다.

공급자 연결과 모델 ID

바이너리만 있으면 TUI는 뜨지만, 공급자와 모델이 비어 있으면 질문은 멈춘다. TUI /connect와 셸 opencode auth login은 같은 키를 저장한다. 실행 위치만 다르다. 슬래시는 TUI가 떠 있는 동안의 명령이다. PowerShell에 /connect를 그대로 치면 로그인이 되지 않는다. Windows에서 슬래시는 경로 구분자로도 읽히므로, 셸에 슬래시 명령을 치면 더 헷갈린다.

공식 순서는 콘솔에 로그인해 API 키를 복사한 뒤, TUI에서 /connect로 공급자를 고르고 키를 붙이는 것이다. Go를 쓰려면 opencode.ai/go에서 구독이 되어 있어야 한다. Zen을 쓰려면 결제 정보를 넣고 키를 받는다. 다른 공급자는 Models.dev 목록 기준으로 opencode auth login이 키를 받는다.

2026년 7월 27일 위키 화면은 사이드 API 키 메뉴가 Zen과 Go를 가리지 않는 공통 칸이었다. Go 전용 키 페이지가 따로 있는 것은 아니었다. 같은 문자열을 넣은 뒤 TUI에서 공급자 이름만 고른다.

키를 넣은 뒤에도 기본 모델 ID가 비어 있으면 세션이 어느 모델을 쓸지 모른다. 설정 파일의 model 필드가 그 기본값이다. Go는 접두 opencode-go/다. 공식 예는 Kimi K3를 opencode-go/kimi-k3로 적는다. Zen은 접두 opencode/다. 예는 opencode/gpt-5.5다. Go 구독이 없는 상태에서 opencode-go/ 접두를 고르면 그 묶음은 응답하지 않는다. 다른 공급자로 붙은 모델만 동작한다.

Windows 위키는 설정 파일을 C:/Users/<이름>/.config/opencode/opencode.json에 두었다. 환경 변수 OPENCODE_CONFIG는 파일 경로를, OPENCODE_CONFIG_DIR는 디렉터리를 덮어쓴다. 예는 OPENCODE_CONFIG_DIR=D:/myconfig다. 인증 파일 기본 위치는 CLI 문서 기준 ~/.local/share/opencode/auth.json이다. 시작 시 이 파일과 프로젝트 .env의 키를 같이 읽는다.

Go 기본 모델을 설정 파일에 넣는 예는 아래와 같다.

{
  "model": "opencode-go/kimi-k3"
}

Zen 쪽 접두를 쓰는 예는 아래와 같다.

{
  "model": "opencode/gpt-5.5"
}

프로젝트 폴더로 이동한 뒤 인수 없이 실행하면 TUI가 뜬다.

opencode

--model 또는 -m에 provider/model 형식을 넘기면 그 세션만 모델을 바꾼다. --continue 또는 -c는 마지막 세션을 이어 간다. --session은 세션 ID를 고른다.

셸에서 키가 저장됐는지는 opencode auth list로 본다. 목록이 비어 있으면 아직 공급자가 없는 것이다. 연결된 모델 목록은 opencode models다. 공급자 ID를 붙이면 그 묶음만 본다. Go만 보려면 opencode models opencode-go다. --refresh는 models.dev 캐시를 갱신한다. 로그아웃은 opencode auth logout이다.

opencode auth login
opencode auth list
opencode models
opencode models opencode-go

TUI 작업 흐름

공급자가 붙으면 작업할 저장소 루트에서 /init을 실행한다. OpenCode가 프로젝트를 읽고 루트에 AGENTS.md를 만든다. 구조와 코딩 패턴을 이후 세션에 남기는 메모다. README를 대신하지는 않는다. 이 파일이 없으면 매 세션마다 같은 맥락을 다시 설명해야 하고, 그만큼 토큰이 나간다.

파일에 적는 내용은 짧아도 된다. 건드리지 말 디렉터리, 테스트 실행 명령, 팀 코딩 규칙, 사용 중인 프레임워크 버전이 예다. 다음 질문이 그 메모를 본다.

# 프로젝트 규칙

## 건드리지 말 것
- /legacy 디렉터리
- package-lock.json 직접 수정

## 테스트 실행
npm test

## 코딩 규칙
- TypeScript strict 모드
- 함수형 컴포넌트만 사용
- 커밋 메시지는 한국어

Tab 키는 Plan과 Build를 전환한다. 화면 오른쪽 아래에 모드가 표시된다. Plan은 파일 변경을 끄고 구현 방법만 제안한다. 변경 파일이 세 개 이상이거나 요구가 아직 확정되지 않았을 때 Plan을 먼저 쓴다. 긴 기능, 화면이 여러 장인 작업도 같다. 공식 소개 예는 노트 삭제를 소프트 딜리트로 바꾸고 복구 화면을 만드는 문장이다. Plan에서 단계가 나온 뒤에 스크린샷을 터미널로 끌어다 참고 화면으로 붙이면, 에이전트가 그 이미지를 보고 설계를 고친다. 합의가 난 뒤에 Tab으로 Build로 돌아간다.

한 파일의 짧은 수정은 Build에서 바로 말한다. 공식 예는 /notes 라우트의 인증 로직을 /settings에 그대로 옮기라는 문장이다. Build가 파일을 고친 뒤 결과가 아니면 /undo다. 방금 적용한 변경을 되돌리고 원래 메시지를 다시 보여 준다. 프롬프트를 고쳐서 재요청하거나 /redo로 같은 변경을 다시 적용한다. 대화를 팀에 넘기려면 /share가 링크를 만든다.

경로를 @packages/functions/src/notes.ts처럼 집어 주면 컨텍스트가 좁아진다. 레포 전체를 넘기면 토큰이 늘고 응답이 느려진다. @는 그 파일만 읽으라는 표시다. 코드베이스 설명만 필요할 때도 같은 문법을 쓴다.

TUI에서 /models를 치면 연결된 공급자의 모델 목록이 나온다. 셸의 opencode models와 같은 목록을 다른 창에서 보는 것이다.

스크립트나 CI는 opencode run이다. TUI를 띄우지 않고 문장 한 번을 실행한다. --attach로 이미 떠 있는 opencode serve에 붙이면 MCP 서버를 매번 콜드 부트하지 않는다. --file 또는 -f로 파일을 메시지에 첨부한다. --format json은 원시 이벤트다.

opencode run "테스트 파일을 추가하고 커버리지를 80% 이상으로 올려라"
opencode run --attach "로그인 라우트의 에러 처리를 추가해라"

세션 목록은 opencode session list다. 토큰과 비용 통계는 opencode stats다. export와 import는 세션 JSON과 공유 URL을 오간다.

MCP 서버는 OpenCode가 외부 도구에 붙는 통로다. 처음 TUI가 대답하는 단계에서는 없어도 된다. 쓸 때는 opencode mcp add로 넣고 mcp list로 상태를 본다. OAuth가 있는 서버는 mcp auth다. GitHub 저장소에 에이전트 워크플로를 심는 안내는 opencode github install이다. 로컬 TUI 사용과 별개의 자동화 층이다.

VS Code와 Cursor 확장

공식 IDE 문서는 통합 터미널에서 opencode를 실행하라고 한다. 확장이 자동으로 깔린다. 마켓플레이스에서 OpenCode를 찾아 Install을 눌러도 된다.

자동 설치가 실패하는 조건은 세 가지다. 통합 터미널이 아닌 외부 PowerShell이나 Windows Terminal에서만 실행했을 때다. code 또는 cursor 셸 명령이 PATH에 없을 때다. 조직 정책으로 확장 설치 권한이 막혀 있을 때다. 첫 경우는 에디터 안의 터미널에서 다시 실행한다. 둘째는 명령 팔레트의 “Shell Command: Install ‘code’ command in PATH” 또는 Cursor의 같은 항목이다. 셋째는 마켓플레이스 수동 설치나 관리자 허용이 필요하다.

Windows와 Linux에서 에디터 파일을 연 뒤 37~42번 줄을 선택하고 Alt+Ctrl+K를 누르면 TUI에 @File#L37-42가 삽입된다. Cursor Agent 채팅창에서 파일을 참조하는 일과 비슷해 보이지만, 실제로는 분할 터미널의 TUI 입력칸에 경로가 붙는 것이다. 채팅 사이드바를 대체하지 않는다.

Ctrl+Esc는 분할 터미널에서 OpenCode를 열거나, 이미 떠 있는 세션으로 포커스한다. Ctrl+Shift+Esc는 기존 세션이 있어도 새 터미널 세션을 연다. UI의 OpenCode 버튼도 같은 목적이다. 문서는 현재 선택 영역과 탭을 자동으로 공유한다고 적는다.

macOS 단축키는 조합이 다르다. TUI의 /editor나 /export가 시스템 기본 앱이 아니라 VS Code를 열게 하려면 EDITOR='code --wait'를 환경에 둔다.

모델 키와 구독은 확장과 무관하다. 여전히 TUI /connect 또는 셸 opencode auth login, 그리고 콘솔 쪽이다.

셸 명령과 TUI 슬래시

공식 소개 페이지는 /connect를 적고, CLI 페이지는 auth login을 적는다. 한 창에 두 문서를 겹치면 슬래시가 PowerShell 명령처럼 보인다. Windows에서 버전은 나오는데 모델이 비어 있는 상태가 그 결과인 경우가 많다. 슬래시는 TUI가 해석하는 명령이고, 셸은 opencode로 시작하는 서브커맨드만 받는다.

전역 플래그는 --help, --version, --print-logs, --log-level이다. 자주 쓰는 환경 변수는 OPENCODE_CONFIG, OPENCODE_CONFIG_DIR, OPENCODE_GIT_BASH_PATH, OPENCODE_DISABLE_AUTOUPDATE다. 자동 업데이트가 CI에서 버전을 바꾸지 않게 막을 때 마지막 변수를 켠다. serve와 web에 비밀번호를 걸려면 OPENCODE_SERVER_PASSWORD다.

TUI 안에서만 동작하는 슬래시를 셸에 치면 실패한다. /connect, /models, /init, /undo가 그 예다.

Go 구독과 달러 한도

Go는 OpenCode가 선별한 오픈 코딩 모델 묶음이다. 한도는 요청 횟수가 아니라 달러다. 5시간 안에 12달러어치 요청을 쓰면 그 구간 한도에 닿는다. 5시간 동안만 켜 둔다는 뜻이 아니다. 세 겹은 5시간 12달러, 주 30달러, 월 60달러다. 문서는 월 10달러를 내고 약 6배 사용량을 주는 것이 목표라고 적는다.

같은 5시간 12달러에서 Kimi K3는 약 110회, MiMo-V2.5는 약 30,100회가 나온다고 공식 표가 적는다. 모델마다 토큰 단가가 달라서다. 단가가 낮은 모델은 같은 달러로 요청이 많다. 표의 횟수는 관찰된 토큰 패턴으로 환산한 추정이다. 실제 횟수는 프롬프트 길이와 응답 토큰에 따라 달라진다. 주간·월간 열도 같은 추정이다. Kimi K3는 주 250, 월 490이다. GLM-5.3-Flash는 5시간 1,580, 주 3,950, 월 7,900이다. MiMo-V2.5는 주 75,200, 월 150,400이다.

조사일 목록에는 Grok 4.6, GLM-5.3-Flash와 GLM-5.3, GPT 5.6 Luna, Kimi K3, MiniMax M3, Qwen3.8, DeepSeek V4, Hy3 등이 있다. 목록은 테스트에 따라 바뀐다. 산 카탈로그는 https://opencode.ai/zen/go/v1/models다. TUI /models가 그 스냅샷을 보여 준다.

공식 관찰 패턴 기반 추정이다. 개인 워크로드와 숫자가 다를 수 있다.

GLM-5.3-Flash의 Go 표 Usage 열이 15달러인 이유는 6배 목표(월 60달러)보다 사용량 배율이 낮다는 뜻이다. 공식 문서는 일부 모델의 사용량이 더 적은 이유를 신작·할인 모델이라고 설명한다. 한국어 랜딩의 한시 2× 확대와 표의 15달러는 같은 모델의 다른 표현이다. 조사일 Go 표 Input은 0.15달러, Output은 0.50달러다.

한도에 닿으면 요청이 막힌다. Zen 잔액이 있으면 콘솔의 Use balance를 켠다. 켜면 Go 한도 이후 종량 잔액으로 넘어간다. 사용량은 콘솔 게이지로 본다.

Zen은 종량제 게이트웨이다. 잔액이 5달러 아래로 내려가면 기본 20달러를 자동충전하고, 금액과 자동충전 자체는 끌 수 있다. 설정 접두는 opencode/다. 조사일 Zen 무료 칸에는 Big Pickle, MiMo-V2.5 Free, Ling 3.0 Flash Fin, Nemotron 무료 엔드포인트, Muse Spark Contributor Free가 있다. 한정 기간이고 학습·보안 로그 예외가 붙는다.

2026년 7월 27일 Stripe 화면에는 월 10달러에 첫 달 50% 할인이 붙어 당일 5달러가 찍혔다. 8월 31일 공식 문서와 한국어 랜딩은 월 10달러만 적는다. 청구액은 결제 직전 화면이 정본이다.

개인정보 표는 대부분 학습 미사용, 보존 0일이다. Grok 4.6과 GPT 5.6 Luna는 30일 보존이다. Muse Spark 1.2 Contributor는 학습에 쓰이며 일부 지역만이다. Contributor 모델을 고르면 대화가 학습에 쓰일 수 있다. DeepSeek ZDR 문구는 조사일 문서가 2026년 8월 31일까지라고 적는다. 그 이후 갱신은 공개되지 않았다.

2026년 4월 14일 위키는 모델 7종과 Black 플랜을 적었다. 8월 31일 공식 Go·Zen 문서와 한국어 랜딩에는 Black이 없다. 4월 목록을 현재 카탈로그로 읽으면 틀린다. 구독 전 결제 화면의 플랜 이름이 정본이다.

Ox Alpha와 GLM-5.3-Flash

2026년 8월 20일 OpenCode와 OpenRouter에 Ox Alpha라는 익명 무료 모델이 올랐다. Zen ID는 x-preview-f-free, OpenRouter는 stealth/ox-alpha였다. 8월 22일 위키는 당시 시점으로 「지금은 무료」라고 적었다.

8월 26일 Z.ai는 출시 전 테스트명이 ox-alpha였고 제품명은 GLM-5.3-Flash라고 밝혔다. 총 파라미터 320B, 활성 18B, 네이티브 멀티모달, MIT 가중치라고 공개했다. 그 무료 스텔스 ID는 더 이상 지원되지 않는다. GitHub 이슈 제목은 Model x-preview-f-free is not supported다.

지금 Go에서 쓰는 ID는 opencode-go/glm-5.3-flash다. 8월 22일 위키의 무료 안내를 그대로 따라가면 피커에서 실패한다. x-preview-f-free와 stealth/ox-alpha는 현재 쓸 수 있는 모델이 아니다.

Z.ai 코딩 플랜의 3× 쿼터와 OpenRouter 직결 단가는 Go의 달러 한도와 분모가 다르다. 한 숫자로 합치면 틀린다.

마무리

앞에서 다룬 OpenCode 설치와 사용의 핵심만 짧게 정리한다.

• OpenCode는 오픈소스 터미널 코딩 에이전트다. Cursor 채팅창이 아니다. Go와 Zen은 선택 공급자다.
• Windows 실측 설치는 npm 전역 opencode-ai다. Node.js가 필요하고, 확인은 opencode --version과 where.exe opencode다.
• 설치 다음이 공급자 키다. TUI /connect 또는 셸 opencode auth login이다. 모델 ID 접두는 Go opencode-go/, Zen opencode/다.
• 프로젝트 루트에서 /init이 AGENTS.md를 만들고, Tab이 Plan과 Build를 전환한다. 결과가 아니면 /undo다.
• VS Code와 Cursor는 통합 터미널에서 opencode를 치면 확장이 깔린다. 단축키는 분할 터미널 TUI용이다.
• Go는 월 10달러 선택 구독이다. 한도는 달러다. 5시간 12달러, 주 30달러, 월 60달러다.
• x-preview-f-free는 종료됐다. 후속은 opencode-go/glm-5.3-flash다.

「먼저 깔고 키를 넣은 뒤, 슬래시는 TUI 안에서만 친다.」 에디터 입문은 Node와 Cursor가 먼저다. OpenCode는 그 폴더를 터미널 에이전트로 여는 층이다.

출처와 링크

조사 기준일 2026년 8월 31일. 설치, /init, Plan, CLI, IDE는 그날 공식 한국어 문서다. Windows npm 경로와 Stripe 첫 달 5달러는 2026년 7월 27일 위키 실측이다.

소개와 설치는 OpenCode 문서다. Go 구독과 한도는 Go 문서와 한국어 랜딩이다. 종량제는 Zen, 셸 명령은 CLI, 확장은 IDE다. 영어 Go 문서도 같은 한도를 적는다. https://opencode.ai/docs/go/

Windows 키 연결과 opencode-go/kimi-k3 실측은 OpenCode Go CLI 설정이다. Ox Alpha 종료와 정체는 opencode#45279와 Z.ai GLM-5.3-Flash다. 8월 22일 당시 안내는 Ox Alpha 위키에 남아 있다.

제휴 경유 구독 안내는 min-inter Go 링크다. 공식 결제는 opencode.ai/go다.