OpenCode 가이드

현재 상태와 저장소 구분

OpenCode는 SST(Serverless Stack) 팀이 Go로 개발한 터미널 AI 코딩 에이전트입니다. 2026년 4월 기준 GitHub Stars 140,000+, 850여 명의 기여자, 최신 버전 v1.14.24 (2026-04-24)로 활발하게 개발 중입니다. 저장소가 여러 번 이전되었으므로 아래처럼 분리해서 이해하세요.

OpenCode 개요

OpenCode는 터미널 중심 워크플로우를 기반으로 코드 생성, 수정, 파일 탐색, 명령 실행을 연결하는 오픈소스 AI 코딩 에이전트입니다. 단독 TUI/CLI로 사용할 수 있고, 최근 공식 문서는 터미널, 데스크톱 앱, IDE 확장을 함께 안내합니다.

• 핵심 인터페이스: TUI/CLI 기반 상호작용
• 추가 표면: 데스크톱 앱과 IDE 확장 지원
• IDE 연동: 통합 터미널에서 실행 시 확장 자동 설치 경로 제공
• 모델 연결: 다양한 제공자 또는 OpenCode Zen 사용 가능
• 워크플로우: Plan 모드와 Build 모드를 분리해 안전하게 작업

설치와 빠른 시작

아래 명령은 공식 문서(sst/opencode) 기준 설치 방법입니다. 운영체제와 패키지 관리자 환경에 맞춰 하나만 선택하면 됩니다.

# Node 패키지 매니저 기반
npm install -g opencode-ai
# 또는
bun install -g opencode-ai
# 또는
pnpm install -g opencode-ai

# macOS Homebrew
brew install sst/tap/opencode

# Windows (Scoop)
scoop install opencode

# Windows ARM64도 지원 (v1.14.x부터)

# 또는 GitHub Releases에서 바이너리 직접 다운로드
# https://github.com/sst/opencode/releases

# 실행
opencode

빠른 시작: 권장 모델 설정

# 최고 성능: Claude Opus 4.7
export ANTHROPIC_API_KEY=sk-ant-...
opencode

# OpenAI GPT-5.5
export OPENAI_API_KEY=sk-...
opencode

# 무료: Ollama (로컬)
ollama run qwen3.6:35b-a3b
opencode  # TUI에서 Ollama 모델 선택

# GitHub Copilot OAuth (기존 구독 활용)
opencode  # 설정에서 GitHub 로그인 후 copilot 모델 선택

opencode.json 설정 파일

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-opus-4-7-20251016",
  "small_model": "anthropic/claude-haiku-4-5-20251001",
  "mode": "build"
}

IDE 연동

• VS Code, Cursor, Windsurf 통합 터미널에서 opencode 실행
• IDE CLI 명령이 PATH에 있어야 자동 연동: VS Code → code, Cursor → cursor, Windsurf → windsurf
• 현재 OpenCode는 "터미널 중심" 사용이 기본이며, IDE 확장은 이를 보조

주요 기능 (v1.14.x 기준)

병렬 세션 (탭 기반)

OpenCode TUI는 Bubble Tea 기반으로 구현되어, 하나의 프로젝트에서 여러 에이전트 세션을 동시에 탭으로 운영합니다. 서로 다른 기능 작업을 병렬로 진행하거나, 실험적 변경과 안정 작업을 분리하기에 최적입니다.

# 새 세션 탭 열기
Ctrl+N

# 탭 간 전환
Ctrl+Tab / Ctrl+Shift+Tab

# 세션 닫기
Ctrl+W

# 에이전트 중단
Esc

# 세션 컴팩션 설정 (긴 대화 압축)
# preserve_recent_tokens: 최근 토큰 유지량 설정

MCP (Model Context Protocol) 지원

OpenCode는 로컬 및 원격 MCP 서버를 모두 지원합니다. v1.14.x부터 실험적 HTTP API를 통해 외부 도구(모바일 앱, CI 등)에서 세션을 직접 제어할 수 있습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-opus-4-7-20251016",
  "mcp": {
    "servers": {
      "filesystem": {
        "type": "local",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
      },
      "github": {
        "type": "remote",
        "url": "https://mcp.github.com"
      }
    }
  }
}

커스텀 에이전트

마크다운 파일로 커스텀 에이전트를 정의하고, @mention으로 TUI 내에서 호출합니다. 역할별 전문 에이전트를 만들어 팀 전체가 공유할 수 있습니다.

---
name: reviewer
description: 코드 리뷰 전문 에이전트
model: anthropic/claude-opus-4-7-20251016
---

당신은 시니어 코드 리뷰어입니다.
- 버그, 보안 취약점, 성능 문제를 우선 지적하세요
- 한국어로 리뷰를 작성하세요
- 개선 코드 예시를 반드시 포함하세요

# 커스텀 에이전트 호출
@reviewer src/auth.py를 리뷰해줘

# 슬래시 커맨드 (마크다운 파일로 정의)
/test-gen    # .opencode/commands/test-gen.md
/refactor    # .opencode/commands/refactor.md

GitHub Actions 통합

PR 코멘트에 /opencode 또는 /oc를 입력하면 CI에서 OpenCode가 자동으로 실행됩니다. 코드 리뷰, 자동 수정, PR 설명 생성 등을 CI 파이프라인에 통합할 수 있습니다.

name: OpenCode CI
on:
  issue_comment:
    types: [created]

jobs:
  opencode:
    if: startsWith(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sst/opencode-action@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

LSP 통합

OpenCode는 Language Server Protocol을 통해 진단 정보(타입 오류, 린트 경고)를 에이전트 컨텍스트에 포함합니다. v1.14.21부터 C# (Roslyn), Kotlin LSP pull diagnostics를 추가로 지원합니다.

모델 선택 가이드 (2026-04)

OpenCode Zen 심화 가이드

OpenCode Zen은 OpenCode 팀이 코딩 에이전트 용도로 테스트/검증한 모델 조합을 제공하는 게이트웨이입니다. 단순 모델 목록이 아니라, 모델-제공자 조합 품질을 맞춰 제공하는 운영 레이어로 이해하면 됩니다.

Zen을 쓰는 이유

• 검증된 조합: 코딩 에이전트에 적합한 모델/제공자 조합을 선별
• 운영 단순화: 여러 제공자 품질 편차를 직접 관리하지 않아도 됨
• 워크스페이스 통제: 팀 단위 모델 접근 제어와 정책 적용 가능
• BYOK 혼합: 필요 시 OpenAI/Anthropic 키를 직접 붙여 병행 사용 가능

연결 절차 (TUI 기준)

1. OpenCode Zen 인증 페이지에서 로그인
2. 결제 수단과 API 키 발급 확인
3. TUI에서 /connect 실행 후 OpenCode Zen 선택
4. 발급받은 API 키 입력
5. /models로 사용 가능한 추천 모델 목록 확인

# OpenCode 실행
opencode

# TUI 내부 명령 예시
/connect
/models

모델 ID와 엔드포인트 이해

OpenCode 설정에서 Zen 모델을 지정할 때는 보통 opencode/<model-id> 형태를 사용합니다. 예: opencode/<team-default-model>

// opencode.json 예시
{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/<team-default-model>"
}

요금/한도 운영 포인트

Zen은 사용량 기반 과금(pay-as-you-go) 모델을 제공하며, 모델별 토큰 단가가 다릅니다. 실무에서는 "단가표"보다 "한도/자동 충전/모니터링" 운영 규칙을 먼저 정해두는 편이 안전합니다.

• 자동 충전: 잔액 임계치 이하 시 자동 충전 동작 가능
• 월 한도: 팀/개인 지출 상한선을 설정해 비용 폭주 방지
• 모델 정책: 고비용 모델은 제한하고 표준 모델 중심으로 기본값 지정
• BYOK 분리: 특정 요청은 Zen 과금이 아닌 제공자 직접 과금

팀 운영(권한/모델 통제/BYOK)

팀 환경에서 Zen을 쓰는 핵심은 "권한 분리"와 "모델 접근 제어"입니다. 관리자 권한을 최소 인원으로 제한하고, 기본 모델 풀을 미리 정해 비용과 품질을 같이 관리하세요.

• Admin: 멤버/모델/과금/API 키 운영
• Member: 허용된 모델 범위 내 사용
• 모델 접근 제어: 고비용 또는 정책 위반 가능 모델 비활성화
• BYOK: OpenAI/Anthropic 개인 또는 조직 키를 붙여 과금 경로 분리

개인정보/데이터 정책 체크리스트

• 모델 호스팅 지역(예: 미국)과 조직 정책 충돌 여부 사전 확인
• 제로 보존 정책 적용 범위와 예외 모델 확인
• 무료/실험 모델 사용 시 데이터 활용 고지 문구 재확인
• 민감 코드 저장소는 별도 규칙(허용 확장자/디렉터리 제한) 운영

Zen 실무 플레이북

아래 내용은 팀에서 OpenCode Zen을 실제 운영할 때 자주 쓰는 기준안입니다. 모델 선택, 정책 통제, 비용 추정 순서로 설계하면 시행착오를 크게 줄일 수 있습니다.

모델군별 추천 시나리오

팀 정책 템플릿 (운영 초안)

아래는 팀 위키나 온보딩 문서에 바로 붙일 수 있는 정책 템플릿 예시입니다. 숫자 값은 팀 예산과 배포 빈도에 맞게 조정하세요.

# OpenCode Zen 팀 운영 정책 (예시)
# 1) 기본 모델
- 기본 모델: opencode/<중간-등급-코딩-모델>
- 고성능 모델: 승인된 작업에서만 사용

# 2) 월 한도
- 개인 월 한도: 팀 정책에 맞는 값으로 설정
- 팀 월 한도: 예산 승인 범위에 맞게 설정
- 80% 도달 시 운영 채널 자동 알림

# 3) 권한
- Admin: 모델 허용/차단, 한도, 과금 설정
- Member: 허용된 모델만 사용

# 4) 데이터 처리
- 민감 저장소는 승인된 모델만 사용
- 무료/실험 모델 사용 전 데이터 정책 재확인

# 5) 운영 규칙
- 대규모 변경: Plan 모드로 계획 검토 후 Build 전환
- 실패 시 재시도 순서: 기본 모델 → 고성능 모델
- API 키는 환경 변수 또는 비밀 저장소만 사용

설정 템플릿 (opencode.json 예시)

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/<기본-모델-id>",
  "small_model": "opencode/<저비용-모델-id>",
  "mode": "build"
}

비용 시뮬레이션 예시

실제 단가는 수시로 바뀌므로, 아래는 산식 중심 예시입니다. 핵심은 팀별 요청량을 기준으로 월 예산 범위를 빠르게 추정하는 것입니다.

# 월비용(대략) = (일평균 입력토큰/1,000,000 × 입력단가 + 일평균 출력토큰/1,000,000 × 출력단가) × 근무일수

문제 해결 빠른 점검표

도구 비교

공식 레퍼런스

• OpenCode 공식 문서
• IDE 연동 문서
• Providers 문서
• MCP 서버 문서
• 커스텀 에이전트 문서
• OpenCode Zen 문서
• 활성 저장소 (sst/opencode)
• 릴리즈 노트

핵심 정리

• 현재 활성 저장소는 sst/opencode이며, v1.14.24 (2026-04-24), GitHub Stars 140K+의 가장 빠르게 성장하는 터미널 AI 코딩 에이전트입니다.
• 병렬 세션(탭)으로 여러 에이전트를 동시에 운영할 수 있는 것이 Claude Code, Aider 대비 핵심 차별점입니다.
• MCP 서버 통합과 커스텀 에이전트(마크다운)로 팀 특화 워크플로우를 구축할 수 있습니다.
• GitHub Actions 통합(/opencode, /oc)으로 PR 기반 AI 자동화 파이프라인을 CI에 통합합니다.
• 모델은 75개 이상 지원하며, 최고 성능은 Claude Opus 4.7 (SWE-bench 87.6%) 또는 GPT-5.5 (88.7%)입니다.
• 게이트웨이는 Zen(사용량 기반) · Black($20–200/월 정액) · 직접 BYOK 세 가지를 목적에 맞게 선택하세요.
• 실무에서는 설치 자체보다 모델 정책, 비용 통제, 팀 권한 설계가 안정성에 더 큰 영향을 줍니다.