OpenCode, oh-my-opencode 설치 및 사용 가이드

🧩 OpenCode(opencode) 설치 및 사용 가이드 (macOS / Windows)

macOS 및 Windows 환경에서 OpenCode(opencode)를 설치하고
Gemini / Claude 기반으로 정상 사용하기까지의 전체 과정 정리

---

1️⃣ Node.js 설치 (공통)

📌 목적

• opencode는 Node.js 기반 CLI 도구
• Node.js 필수

✅ 설치

• 공식 사이트
  👉 https://nodejs.org/ko/download
• LTS 버전 권장

✅ 설치 확인

 

node -v npm -v

버전 출력 시 정상 설치 완료

---

2️⃣ OpenCode(opencode) 설치

🔹 OS별 차이

OS설치 방식

macOS	Homebrew
Windows	npm (global)

---

✅ macOS 설치 (Homebrew)

 

brew install opencode

 

opencode --version

---

✅ Windows 설치 (npm)

 

npm install -g opencode

⚠️ 권한 오류 발생 시
PowerShell을 관리자 권한으로 실행

 

opencode --version

---

⚠️ (Windows) PowerShell 스크립트 실행 권한 오류 해결

ReactJS 프로젝트 build, npm / npx / opencode 실행 시
스크립트 권한 제한으로 에러가 발생하는 경우

---

🔍 원인

Windows PowerShell 기본 정책이
스크립트 실행 제한(Restricted) 상태이기 때문

---

✅ 해결 절차 (요약)

1️⃣ PowerShell 관리자 권한 실행

• Windows 검색 → PowerShell
• 우클릭 → 관리자 권한으로 실행

2️⃣ 현재 실행 정책 확인

 

Get-ExecutionPolicy

 

Restricted

→ 스크립트 실행 차단 상태

---

3️⃣ 실행 정책 변경 (추천)

 

Set-ExecutionPolicy RemoteSigned

보안 + 실사용 균형이 가장 좋음 (권장)

⚠️ 전체 허용이 필요한 경우:

 

Set-ExecutionPolicy Unrestricted

---

4️⃣ 변경 확인

 

Get-ExecutionPolicy

---

📌 실행 정책 요약

정책설명

Restricted	기본값, 스크립트 실행 불가
Unrestricted	모든 스크립트 실행 가능 (보안 위험)
RemoteSigned	로컬 스크립트 실행 가능 (추천)

 

Get-Help Set-ExecutionPolicy

---

3️⃣ 작업 폴더 생성 및 이동

📁 예시

macOS

 

~/Desktop/workspace/Football News

 

cd "~/Desktop/workspace/Football News"

또는 Finder → 폴더 우클릭 → 폴더에서 새로운 터미널 열기

---

Windows

 

C:\workspace\Football News

 

cd "C:\workspace\Football News"

또는 탐색기 주소창에 cmd 입력

---

4️⃣ opencode 초기화 (중요)

❌ 잘못된 명령

 

opencode init

→ init을 폴더로 인식하여 에러 발생

---

✅ 올바른 명령

 

opencode init .

• 현재 폴더를 프로젝트 루트로 설정
• 에러 없이 종료되면 성공

---

5️⃣ Gemini / Claude API Key 생성

🔑 Gemini

• https://aistudio.google.com/
• API Key 생성

 

AIzaSy********************************

🔑 Claude

• https://platform.claude.com/dashboard

⚠️ 실제 키는 GitHub / Notion / 캡처에 절대 공유 금지

---

6️⃣ opencode 최초 실행 & 설정 (TUI)

 

opencode

최초 실행 시 대화형 설정 UI 등장

🔹 추천 선택

질문선택

Claude Pro/Max 구독 여부	Yes
OpenCode Zen Access	No
Z.ai Coding Plan	No
Gemini Integration	Yes

---

7️⃣ 권한 요청 화면

macOS

 

Permission required Access ~/.config/opencode/oh-my-opencode.json

→ Allow once 선택

Windows

• SmartScreen 경고 시
  추가 정보 → 실행

---

8️⃣ OpenCode 메인 UI 진입 성공 🎉

확인 포인트

• 환영 메시지
• Essential Tutorial 표시
• 하단 상태바 예시:

 

Build · gemini-3-flash-preview

👉 Gemini 모델 정상 연결

---

9️⃣ OpenCode 기본 사용법

 

축구 뉴스 수집 자동화 구조를 설계해줘

🔹 ultrawork 모드

 

ultrawork Football News 프로젝트 전체 아키텍처 설계해줘

🔹 Prometheus 모드

• Tab 키 → 작업 계획 모드

---

🔟 oh-my-opencode 플러그인 설치 (강력 추천)

📌 개요

• OpenCode 사용성 확장 플러그인
• https://github.com/code-yeongyu/oh-my-opencode

✅ 설치

1. GitHub README의 설치 명령어 복사
2. opencode 실행 중 터미널에 붙여넣기
3. 실행

---

✅ macOS / Windows 차이 요약

항목macOSWindows

Node 설치	pkg	exe
opencode 설치	brew	npm -g
터미널	Terminal	PowerShell / CMD
권한 이슈	macOS 권한 팝업	ExecutionPolicy