OpenCode 가이드

현재 상태와 저장소 구분

OpenCode 관련 정보는 과거 저장소와 현재 활성 저장소가 혼재되어 있어 혼동이 자주 생깁니다. 아래처럼 두 계열을 분리해서 이해하면 오해를 줄일 수 있습니다.

OpenCode 개요

OpenCode는 터미널 중심 워크플로우를 기반으로 코드 생성, 수정, 파일 탐색, 명령 실행을 연결하는 오픈소스 AI 코딩 에이전트입니다. 단독 TUI/CLI로 사용할 수 있고, VS Code/Cursor/Windsurf 같은 편집기에서는 확장 연동으로 함께 사용할 수 있습니다.

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

설치와 빠른 시작

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

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

# macOS Homebrew (탭)
brew install anomalyco/tap/opencode

# 실행
opencode

IDE 연동 핵심

• VS Code, Cursor, Windsurf 통합 터미널에서 opencode 실행
• 확장 연동이 자동으로 진행되지 않으면 IDE CLI 명령 존재 여부 점검
• 예: VS Code는 code, Cursor는 cursor, Windsurf는 windsurf

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/gpt-5.2-codex

// opencode.json 예시
{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/gpt-5.2-codex"
}

요금/한도 운영 포인트

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

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

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

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

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

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

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

Zen 실무 플레이북

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

모델군별 추천 시나리오

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

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

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

# 2) 월 한도
- 개인 월 한도: 40 USD
- 팀 월 한도: 500 USD
- 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 문서
• OpenCode Zen 문서
• 활성 저장소 (anomalyco/opencode)
• 과거 아카이브 저장소 (opencode-ai/opencode)

핵심 정리

• 현재 기준 OpenCode 정보는 "활성 저장소"와 "과거 아카이브 저장소"를 분리해서 봐야 정확합니다.
• OpenCode Zen은 모델 게이트웨이이며, 단순 모델 카탈로그가 아니라 운영 정책 계층까지 포함합니다.
• 실무에서는 설치 자체보다 모델 정책, 비용 통제, 팀 권한 설계가 안정성에 더 큰 영향을 줍니다.