⚡ 02. 셋팅

opencode-02-셋팅-diagram.svg

OpenCode란?

OpenCode는 AI가 코드를 직접 작성하고 수정해주는 오픈 소스 코딩 에이전트입니다.

⭐ GitHub 스타 68,500+
👥 월 사용자 650,000명+
💻 터미널, 데스크톱 앱, IDE 확장으로 사용 가능
🔒 코드와 데이터를 외부로 저장하지 않음

시작하기 전 준비사항

✅ 필수 요구사항

항목	확인 방법	설치 가이드
Node.js 18+	`node --version`	Node.js 설치 가이드 참고
npm	`npm --version`	Node.js와 함께 자동 설치됨
PowerShell	기본 제공	Windows 기본 탑재

💡 Node.js가 없다면? 여기를 클릭하여 PowerShell로 쉽게 설치하세요!

1단계: OpenCode 설치

방법 A: npm으로 설치 (추천)

1-1. PowerShell을 관리자 권한으로 실행

Windows 키 누르기
PowerShell 입력
우클릭 → 관리자 권한으로 실행

1-2. OpenCode 설치 명령어 입력

npm install -g opencode-ai@latest

예상 화면:

added 245 packages in 15s

1-3. 설치 확인

opencode --version

예상 결과:

opencode version 1.x.x

💡 에러 발생 시: Node.js 설치 가이드를 먼저 확인하세요.

방법 B: 데스크톱 앱 설치 (GUI 선호자)

CLI가 불편하다면 데스크톱 앱을 설치할 수 있습니다.

1-1. opencode.ai/download 접속

1-2. Windows용 설치 파일 다운로드

1-3. 다운로드한 .exe 파일 실행 및 설치

1-4. 설치 후 바탕화면 아이콘 클릭

💡 주의: 데스크톱 앱도 내부적으로 Node.js가 필요합니다. 설치 프로그램이 자동으로 처리합니다.

2단계: 처음 실행

2-1. 터미널에서 OpenCode 실행

opencode

예상 화면:

┌─────────────────────────────────────────┐
│  Welcome to OpenCode                    │
│  AI-powered coding agent                │
└─────────────────────────────────────────┘

No API provider configured.
Would you like to connect one now? (Y/n)

2-2. Y 입력 후 Enter (API 프로바이더 연결 시작)

3단계: API 프로바이더 연결 (필수)

OpenCode가 AI 모델을 사용하려면 API 프로바이더가 필요합니다.

💰 무료로 시작하고 싶다면? 옵션 2: Antigravity (Google OAuth)를 선택하세요!

옵션 1: OpenCode Zen

장점:

✅ OpenCode 팀이 검증한 모델
✅ 설정 간단
✅ 코딩 에이전트에 최적화
⚠️ 유료 (크레딧 필요)

3-1. 프로바이더 선택 화면에서 opencode 선택

? Select a provider:
  > opencode (OpenCode Zen)
    google (Antigravity OAuth - 무료!)
    others (Z.AI, Claude 등)
    anthropic (Claude)
    openai (GPT)

3-2. 브라우저가 자동으로 열림 → opencode.ai/auth

3-3. GitHub 또는 Google 계정으로 로그인

3-4. API 키 복사 (자동으로 클립보드에 복사됨)

Your API Key:
oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3-5. 터미널로 돌아와서 API 키 붙여넣기 후 Enter

예상 결과:

✓ API key saved successfully
✓ Connected to OpenCode Zen

옵션 2: Antigravity (Google OAuth) - 무료! ⭐

장점:

✅ 완전 무료 (Google 계정만 있으면 됨)
✅ Claude Opus 4.5, Sonnet 4.5, Gemini 3 Pro 사용 가능
✅ 여러 Google 계정 자동 로테이션 지원
✅ API 키 불필요
🎯 초보자에게 가장 추천!

설치 방법:

3-1. opencode-antigravity-auth 플러그인 설치

npm install -g opencode-google-antigravity-auth

3-2. OpenCode 실행 후 인증

opencode auth login

3-3. 프로바이더 선택 화면에서 Google 선택

? Select a provider:
  > Google (Antigravity OAuth)
    opencode (OpenCode Zen)
    anthropic (Claude)

3-4. OAuth with Google (Antigravity) 선택

3-5. 브라우저가 자동으로 열리면 Google 계정으로 로그인

3-6. 권한 승인 (Antigravity 접근 허용)

예상 결과:

✓ Successfully authenticated with Google
✓ Connected to Antigravity
✓ Available models: Claude Opus 4.5, Sonnet 4.5, Gemini 3 Pro

3-7. (선택사항) 추가 Google 계정 등록

? Add another Google account for load balancing? (Y/n)

여러 계정을 등록하면 한 계정이 rate limit에 걸렸을 때 자동으로 다른 계정으로 전환됩니다.

💡 팁: Gmail 계정이 여러 개 있다면 모두 등록해서 사용량 한도를 늘릴 수 있습니다!

관련 자료:

옵션 3: Z.AI Coding Plan (코딩 특화)

장점:

✅ 저렴한 가격 (월 $3$ 6 코딩 플랜)
✅ 빠른 응답 속도
✅ 코딩 특화 모델 GLM-4.7
✅ OpenAI 호환 API
💰 가성비 최고의 옵션

설치 방법:

3-1. Z.AI Coding Plan 가입

회원가입 후 Coding Plan 구독 ($3/월 시작)
Dashboard → API Keys → Create Key
API 키 복사

3-2. OpenCode 인증

opencode auth login

3-3. 프로바이더 선택 화면에서 Z.AI 선택

? Select a provider:
  > Z.AI Coding Plan
    Google (Antigravity OAuth - 무료!)
    opencode (OpenCode Zen)

3-4. Coding Plan 구독자라면 Z.AI Coding Plan 선택

3-5. API 키 붙여넣기

? Enter your Z.AI API key:
zai-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

예상 결과:

✓ API key saved successfully
✓ Connected to Z.AI Coding Plan
✓ Available models: GLM-4.7, GLM-4.5-Air

3-6. 모델 선택

## OpenCode 실행 후
> /model
 
## GLM-4.7 선택 (코딩 특화)

설정 확인:

API 엔드포인트: https://api.z.ai/api/coding/paas/v4

관련 자료:

옵션 4: 기타 프로바이더

OpenCode는 다음 프로바이더들도 지원합니다:

프로바이더	가격	특징	추천 대상
OpenAI (GPT)	유료	GPT-4, GPT-4 Turbo	범용 작업
Anthropic (Claude)	유료	Claude Opus, Sonnet	복잡한 코딩
Gemini	무료 크레딧	Google Gemini Pro	Google 생태계 사용자
Ollama	무료 (로컬)	로컬 실행	오프라인 환경

💡 초보자 팁: 로컬 모델(Ollama, LM Studio)은 설정이 복잡하므로 나중에 시도하세요.

3-A단계: 멀티 프로바이더 설정 (고급)

여러 프로바이더를 동시에 설정하여 상황에 따라 전환할 수 있습니다.

추천 조합: Antigravity(메인) + Z.AI(서브)

장점:

✅ Antigravity로 무료 Claude Opus 4.5 사용
✅ Rate limit 걸리면 Z.AI GLM-4.7로 전환
✅ 코딩 특화 작업은 GLM-4.7로 빠르게 처리
✅ 비용 효율적인 운영

설정 방법:

1단계: Antigravity 설정 (메인)

위의 “옵션 2: Antigravity” 가이드를 따라 Google OAuth 인증 완료

2단계: Z.AI Coding Plan 설정 (서브)

## Z.AI 인증
opencode auth login

Z.AI Coding Plan 선택 → API 키 입력

3단계: opencode.json 파일 편집

## Windows
notepad %USERPROFILE%\.opencode\opencode.json
 
## 또는 VS Code로
code %USERPROFILE%\.opencode\opencode.json

4단계: 설정 파일에 두 프로바이더 추가

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "antigravity": {
      "type": "google-oauth",
      "primary": true,
      "models": ["claude-opus-4-5", "claude-sonnet-4-5", "gemini-3-pro"]
    },
    "zai-coding": {
      "type": "openai-compatible",
      "options": {
        "baseURL": "https://api.z.ai/api/coding/paas/v4"
      },
      "models": [
        {
          "id": "glm-4.7",
          "displayName": "GLM-4.7 (Coding Optimized)"
        },
        {
          "id": "glm-4.5-air",
          "displayName": "GLM-4.5-Air (Fast)"
        }
      ]
    }
  },
  "defaultProvider": "antigravity",
  "fallbackProvider": "zai-coding"
}

5단계: 프로바이더 전환 방법

OpenCode 실행 중 프로바이더 전환:

## 메인 프로바이더로 전환 (Antigravity)
> /provider antigravity

## 서브 프로바이더로 전환 (Z.AI GLM-4.7)
> /provider zai-coding-coding

## 현재 프로바이더 확인
> /provider

6단계: 작업별 프로바이더 선택 팁

작업 유형	추천 프로바이더	이유
복잡한 리팩토링	Antigravity (Claude Opus 4.5)	뛰어난 코드 이해력
빠른 코드 생성	Z.AI (GLM-4.7)	빠른 응답 속도
디버깅	Antigravity	긴 컨텍스트 지원
간단한 수정	Z.AI (GLM-4.5-Air)	빠르고 경제적
문서 작성	Antigravity	자연스러운 문장 생성

자동 전환 설정:

{
  "autoSwitchProvider": true,
  "switchRules": [
    {
      "condition": "rate_limit",
      "action": "fallback"
    },
    {
      "condition": "error",
      "retry": 2,
      "then": "fallback"
    }
  ]
}

4단계: 프로젝트에서 OpenCode 시작

4-1. 작업할 프로젝트 폴더로 이동

cd C:\Users\YourName\Projects\my-project

4-2. OpenCode 실행

opencode

예상 화면:

┌─────────────────────────────────────────┐
│  OpenCode - AI Coding Agent             │
│  Project: my-project                    │
│  Model: Claude Sonnet 3.5               │
└─────────────────────────────────────────┘

Type /help for commands
>

4-3. 프로젝트 초기화 (선택사항이지만 권장)

/init

예상 결과:

✓ Created AGENTS.md
✓ Project initialized

💡 AGENTS.md란? 프로젝트에 대한 AI의 컨텍스트를 저장하는 파일입니다. Git에 커밋하면 팀원들도 동일한 컨텍스트를 공유할 수 있습니다.

5단계: 첫 작업 해보기

예제 1: 간단한 질문

> 이 프로젝트의 구조를 설명해줘

OpenCode가 할 일:

프로젝트 파일 탐색
주요 폴더 및 파일 분석
구조 설명 제공

예제 2: 코드 수정 요청

> src/index.js 파일을 읽고, console.log를 모두 제거해줘

OpenCode가 할 일:

src/index.js 파일 읽기
console.log 찾기
수정 내용 미리보기 제공
승인 후 파일 수정

예제 3: 새 기능 추가

> 사용자 인증 기능을 추가해줘.
> 이메일/비밀번호 로그인을 지원하고, JWT 토큰을 사용해야 해.

OpenCode가 할 일:

필요한 패키지 설치 제안
인증 로직 코드 작성
라우트 및 미들웨어 생성
테스트 코드 제안

6단계: Build vs Plan 모드 이해하기

OpenCode는 2가지 모드로 작동합니다.

모드	단축키	설명	언제 사용?
Build	기본	파일 수정, 명령 실행 가능	실제 코드 작성할 때
Plan	`Tab`	읽기 전용, 분석만	코드 리뷰, 구조 파악할 때

Build 모드 (기본)

> [Build Mode]
> 이 파일을 수정해줘

✅ 파일 읽기/쓰기 가능
✅ 터미널 명령 실행
✅ 패키지 설치

Plan 모드

> [Tab 키 누름]
> [Plan Mode]
> 이 코드를 어떻게 개선할 수 있을까?

✅ 파일 읽기만 가능
⚠️ 수정 요청 시 거부됨
✅ 분석 및 제안만 제공

전환:

Tab 키를 누르면 Build ↔ Plan 모드 전환

7단계: 유용한 명령어 익히기

파일 참조하기

> @src/index.js 파일의 main 함수를 설명해줘

@ 기호로 파일을 참조하면 파일 경로 자동완성이 나타납니다.

변경사항 되돌리기

> /undo

마지막 변경사항을 취소합니다.

변경사항 다시 적용

> /redo

취소한 작업을 다시 적용합니다.

대화 공유

> /share

현재 대화의 공유 링크를 생성합니다 (클립보드에 자동 복사).

도움말 보기

> /help

사용 가능한 모든 명령어 목록을 확인합니다.

8단계: 실전 워크플로우

시나리오: 새 기능 추가하기

1단계: Plan 모드로 계획 수립

[Tab 키 → Plan 모드 진입]

> 사용자 프로필 페이지를 추가하려고 해.
> 어떤 파일들을 수정해야 하고, 어떤 구조가 좋을지 제안해줘.

2단계: 피드백 및 조정

> 라우팅은 React Router를 사용하고,
> 프로필 정보는 Zustand로 상태 관리해줘.

3단계: Build 모드로 전환 및 구현

[Tab 키 → Build 모드 진입]

> 위 계획대로 구현해줘.

4단계: 확인 및 테스트

> npm run dev를 실행해서 에러가 있는지 확인해줘.

5단계: 문제 해결

> 에러를 수정해줘.

자주 발생하는 문제 해결

문제 1: “command not found: opencode”

원인: OpenCode가 PATH에 없거나 설치되지 않음

해결 1: OpenCode 재설치

npm install -g opencode-ai@latest

해결 2: PATH 환경 변수 확인

## npm 글로벌 경로 확인
npm config get prefix
 
## 해당 경로가 PATH에 있는지 확인
echo $env:PATH

Windows PATH 설정:

Windows 검색 → “환경 변수” 입력
“시스템 환경 변수 편집” 클릭
환경 변수 버튼 → Path 변수 선택 → 편집
C:\Users\YourName\AppData\Roaming\npm 추가
모든 창 닫고 새 PowerShell 열기

해결 3: Node.js가 없는 경우

→ Node.js 설치 가이드를 참고하여 설치하세요.

문제 2: API 키 연결 오류

원인: API 키가 잘못되었거나 만료됨

해결:

## 프로바이더 재연결
opencode
> /connect

다시 프로바이더 선택 및 API 키 입력

문제 3: 파일 수정이 안 됨

원인: Plan 모드에 있음

해결:

Tab 키를 눌러 Build 모드로 전환

확인: 프롬프트에 [Build Mode] 또는 [Plan Mode] 표시 확인

문제 4: 프로젝트 인식 안 됨

원인: 잘못된 디렉토리에서 실행

해결:

## 현재 위치 확인
pwd
 
## 올바른 프로젝트 폴더로 이동
cd C:\path\to\your\project
 
## 다시 실행
opencode

문제 5: 느린 응답 속도

원인: 큰 프로젝트 또는 느린 모델

해결:

.opencodeignore 파일 생성 (불필요한 폴더 제외)
더 빠른 모델로 변경 (예: Claude Haiku)

## .opencodeignore 예시
node_modules/
dist/
build/
.git/
*.log

문제 6: Antigravity 인증 실패

원인: Google OAuth 인증 문제

해결:

## 1. 플러그인이 설치되었는지 확인
npm list -g opencode-google-antigravity-auth
 
## 2. 최신 버전으로 업데이트
npm update -g opencode-google-antigravity-auth
 
## 3. 다시 인증 시도
opencode auth login

Google 계정 권한 문제:

브라우저에서 myaccount.google.com/permissions 접속
Antigravity 관련 권한 확인 및 재승인

문제 7: Rate Limit 오류

원인: Antigravity 사용량 한도 초과

해결:

여러 Google 계정 등록 (자동 로테이션)
사용량 확인 대시보드 설치

## Antigravity 사용량 대시보드
npm install -g antigravity-dashboard-tui
antigravity-dashboard

잠시 기다렸다가 다시 시도 (한도는 시간당 리셋됨)

다음 단계

더 배우기

1. 고급 기능 - 커스터마이징, 테마, 키바인드
1. 실전 예제 - 실제 프로젝트 작업 예시
공식 문서

Antigravity 관련 리소스

Antigravity Auth 플러그인 - 공식 GitHub
설정 가이드 - 상세 설정 방법
Medium 튜토리얼 - 단계별 가이드
사용법 가이드 - 실전 예제

Z.AI Coding Plan 관련 리소스

Z.AI Coding Plan 공식 페이지 - 가격 및 플랜
Z.AI OpenCode 문서 - 공식 설정 가이드
Mastra Z.AI 가이드 - 모델 정보

커뮤니티

Discord - 질문하고 팁 공유
GitHub - 이슈 제보 및 기여

요약 체크리스트

완료하셨나요?

모두 완료했다면 OpenCode 사용 준비가 끝났습니다! 🎉

💰 무료 사용자를 위한 추가 체크리스트

opencode-google-antigravity-auth 플러그인 설치
Google 계정으로 OAuth 인증 완료
(선택) 추가 Google 계정 등록 (로테이션용)
(선택) Antigravity 사용량 대시보드 설치

🔄 멀티 프로바이더 사용자 체크리스트

Antigravity (메인) 설정 완료
Z.AI Coding Plan (서브) 설정 완료
opencode.json 파일에 두 프로바이더 설정 추가
/provider 명령으로 전환 테스트 (antigravity ↔ zai-coding)
작업별 프로바이더 선택 전략 숙지

팁 모음

💡 자주 사용하는 패턴

파일 수정 전 확인:

> @src/config.js 파일을 먼저 보여줘

다중 파일 작업:

> @src/utils/auth.js와 @src/routes/user.js를 수정해서
> JWT 인증을 추가해줘

설명과 함께 작업:

> 각 단계마다 무엇을 하는지 설명하면서
> 데이터베이스 마이그레이션 스크립트를 작성해줘

안전한 작업:

> 수정하기 전에 백업을 만들고,
> 변경 사항을 미리 보여줘

점진적 개발:

> 먼저 기본 구조만 만들고,
> 내가 확인한 후에 세부 기능을 추가해줘

멀티 프로바이더 활용:

> /provider antigravity
> (복잡한 리팩토링 작업 수행)

> /provider zai-coding
> (빠른 코드 생성 작업 수행)

Rate Limit 대처:

# Antigravity가 rate limit 걸리면
> /provider zai-coding
> 위 작업을 이어서 진행해줘

일하는 ai

탐색기

⚡ 02. 셋팅

OpenCode란?

시작하기 전 준비사항

1단계: OpenCode 설치

방법 A: npm으로 설치 (추천)

방법 B: 데스크톱 앱 설치 (GUI 선호자)

2단계: 처음 실행

3단계: API 프로바이더 연결 (필수)

옵션 1: OpenCode Zen

옵션 2: Antigravity (Google OAuth) - 무료! ⭐

옵션 3: Z.AI Coding Plan (코딩 특화)

옵션 4: 기타 프로바이더

3-A단계: 멀티 프로바이더 설정 (고급)

추천 조합: Antigravity(메인) + Z.AI(서브)

4단계: 프로젝트에서 OpenCode 시작

5단계: 첫 작업 해보기

예제 1: 간단한 질문

예제 2: 코드 수정 요청

예제 3: 새 기능 추가

6단계: Build vs Plan 모드 이해하기

Build 모드 (기본)

Plan 모드

7단계: 유용한 명령어 익히기

파일 참조하기

변경사항 되돌리기

변경사항 다시 적용

대화 공유

도움말 보기

8단계: 실전 워크플로우

시나리오: 새 기능 추가하기

자주 발생하는 문제 해결

문제 1: “command not found: opencode”

문제 2: API 키 연결 오류

문제 3: 파일 수정이 안 됨

문제 4: 프로젝트 인식 안 됨

문제 5: 느린 응답 속도

문제 6: Antigravity 인증 실패

문제 7: Rate Limit 오류

다음 단계

더 배우기

Antigravity 관련 리소스

Z.AI Coding Plan 관련 리소스

커뮤니티

요약 체크리스트

💰 무료 사용자를 위한 추가 체크리스트

🔄 멀티 프로바이더 사용자 체크리스트

팁 모음

그래프 뷰

목차

백링크