OpenCode 무료 활용법: Muse Spark 설치부터 실전까지

💸 1. 왜 유료 결제 없이 코딩 에이전트를 쓸 수 있을까?

매달 20달러씩 나가는 구독료 때문에 AI 코딩 도구를 망설였다면, OpenCode + OpenCode Zen 무료 모델 조합이 현실적인 대안입니다.

OpenCode는 터미널에서 동작하는 오픈소스 AI 코딩 에이전트입니다. VS Code 플러그인처럼 에디터에 종속되지 않고, 터미널, 데스크톱 앱, IDE 확장으로 동일하게 쓸 수 있습니다.

핵심은 OpenCode Zen이라는 검증된 모델 게이트웨이입니다. OpenCode 팀이 코딩 에이전트로 잘 동작하는 모델과 서빙 방식을 직접 벤치마크해서 제공하는 목록인데, 여기에 완전 무료(Free) 티어가 포함되어 있습니다.

💡 이번 글의 주인공
Muse Spark 1.3 Contributor Free (모델 ID: muse-spark-1.3-contributor-free)는 2026년 10월 기준 OpenCode Zen에서 입력, 출력 모두 무료로 제공되는 Meta 계열 모델입니다. 한시적 무료 제공이며, 할인된 가격 대신 프롬프트와 응답이 향후 Meta 모델 학습에 활용될 수 있다는 점을 공식 문서에 명시하고 있습니다.

이 글은 필자가 실제로 운영 중인 정적 블로그(seodaeya.github.io)에서 결제 정보 없이 무료 모델만으로 글을 기획하고 초안을 생성한 경험을 바탕으로, 설치부터 실전 프롬프트까지 재현 가능하게 정리한 것입니다.

---

🧩 2. 무료 모델 전체 지도: Muse Spark만 있는 게 아니다

Zen 가격표에서 Free로 표기된 모델은 2026년 10월 3일 기준 아래 12종입니다. Muse Spark가 막히거나 느릴 때 바로 갈아탈 수 있도록 미리 알아두면 좋습니다.

📌 프라이버시 체크포인트

1. Space Bunny Free, LongCat 2.5 Preview Free는 제로 리텐션(학습 미사용)을 명시합니다.
   
2. Muse Spark 1.3 Contributor Free는 프롬프트가 학습에 사용될 수 있는 Contributor 조건입니다. 회사 코드, 고객정보, 키(key)는 넣지 마세요.
   
3. NVIDIA trial 계열 2종은 트라이얼 용도, 개인·기밀 데이터 제출 금지입니다.

---

⚙️ 3. 설치: 5분 완성 (macOS, Windows, Linux)

사전 준비물은 모던 터미널 하나뿐입니다. WezTerm, Alacritty, Ghostty, Kitty 중 편한 것을 쓰면 됩니다.

3-1. macOS / Linux 추천 설치 3종

가장 쉬운 방법은 공식 설치 스크립트입니다.

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

Homebrew 사용자라면 탭(tap) 방식이 최신 릴리스 반영이 가장 빠릅니다.

brew install anomalyco/tap/opencode

Node.js 생태계에 익숙하다면 npm 전역 설치도 됩니다.

npm install -g opencode-ai

Arch Linux는 저장소 버전을 그대로 쓰면 됩니다.

sudo pacman -S opencode

3-2. Windows는 WSL이 정답

공식 문서는 Windows에서 WSL(Windows Subsystem for Linux) 사용을 권장합니다. 성능과 기능 호환성이 네이티브보다 안정적입니다.

choco install opencode

scoop install opencode

npm install -g opencode-ai

설치 후 버전 확인은 아래 한 줄이면 됩니다.

opencode --version

3-3. 대화형 TUI와 단발 실행(One-shot) CLI의 차이

OpenCode는 단순히 터미널을 켜서 대화하는 TUI 방식뿐만 아니라, 스크립트나 파이프라인에서 단발로 지시를 수행하는 CLI 비대화형 모드(opencode run)를 기본 지원합니다.

# TUI를 켜지 않고 특정 지시만 즉시 수행
opencode run "README.md에 최신 변경 내역과 설치 가이드 요약을 추가해줘"

# 파이프(|)를 통한 git 변경 사항 전달 및 자동 커밋 메시지 생성
git diff | opencode run "이 변경 사항을 분석해서 Conventional Commits 형식의 메시지로 작성해줘"

▲ 터미널에서 opencode 실행 시 나타나는 인터랙티브 TUI 및 Zen 무료 모델 연동 파이프라인

---

🔑 4. 초기 설정: 결제 없이 무료 모델에 연결하기

OpenCode는 API 키 방식으로 어떤 LLM 제공자든 붙일 수 있습니다. 초보자에게는 Zen 연결이 가장 단순합니다.

4-1. Zen 연결 3단계

1. 프로젝트 폴더로 이동 후 실행합니다.

cd \~/Projects/seodaeya.github.io
opencode

2. TUI에서 아래 명령을 입력하고 opencode 제공자를 선택합니다.

/connect

3. 브라우저에서 열린 인증 페이지(opencode.ai/auth)에 로그인하고 API 키를 복사한 뒤, 터미널 입력창에 붙여넣고 엔터를 누릅니다.

이 시점에 결제 정보를 요구하는 화면이 나올 수 있지만, 무료 모델만 쓸 예정이라면 크레딧 충전 없이 다음 단계로 넘어가도 됩니다. 자동 충전(auto-reload)은 기본적으로 잔액 5달러 이하에서 20달러가 충전되는 구조이므로, 무료로만 쓰려면 반드시 꺼두는 것이 안전합니다.

4-2. 무료 모델 선택 확인

TUI에서 모델 목록을 열어 무료 모델이 보이는지 확인합니다.

/models

목록에서 아래 ID가 보이면 성공입니다.

opencode/muse-spark-1.3-contributor-free

전체 모델 메타데이터가 필요하면 아래 엔드포인트에서도 JSON으로 조회됩니다.

https://opencode.ai/zen/v1/models

Muse Spark 1.3 유료판과 무료판의 엔드포인트는 동일 계열입니다.

💡 설정 파일로 고정하는 법: 전역(Global) vs 프로젝트(Local)
매번 /models에서 수동으로 고르기 번거롭다면 설정 파일로 기본 모델과 보안 권한을 고정할 수 있습니다. OpenCode는 계층형 설정(Layered Configuration)을 지원하므로 사용 목적에 맞게 위치를 선택하면 됩니다:

• 전역 설정 (\~/.config/opencode/opencode.json): 내 PC의 모든 프로젝트에서 별도 설정 없이 무료 모델을 기본으로 사용
• 프로젝트 설정 (./opencode.json): 특정 저장소에서만 해당 모델과 규칙을 덮어쓰기

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/muse-spark-1.3-contributor-free",
  "permission": {
    "bash": "ask",
    "edit": "allow"
  }
}

• $schema: VS Code, Cursor 등 모던 에디터에서 설정 키값 자동 완성(IntelliSense) 및 유효성 검사 제공
• model: 무료 티어인 opencode/muse-spark-1.3-contributor-free로 고정
• permission.bash: "ask": 무료 모델 사용 시 가장 중요한 안전장치입니다. 무료 모델이 잘못된 터미널 명령어(예: 파일 영구 삭제, 엉뚱한 의존성 설치 등)를 독단적으로 실행하지 못하도록 쉘 실행 전 반드시 사용자 확인을 요구합니다.
• permission.edit: "allow": 파일 수정 및 코딩 작업은 승인 대기 없이 즉시 반영하여 작업 흐름을 유지합니다.

---

📁 5. 프로젝트 초기화: AGENTS.md가 무료 활용의 핵심이다

연결이 끝났다면, 작업할 저장소에서 초기화 명령을 실행합니다.

/init

OpenCode가 프로젝트 구조와 코딩 패턴을 분석해서 AGENTS.md 파일을 루트에 생성합니다. 이 파일은 Git에 커밋해서 팀과 공유하는 것이 권장됩니다.

AGENTS.md는 Cursor의 .cursorrules나 Claude Code의 CLAUDE.md와 동일한 역할을 하며, OpenCode가 모든 대화 턴마다 자동으로 시스템 컨텍스트에 주입합니다.

💰 무료 티어 토큰 절약의 핵심 공식
프롬프트마다 "한국어로 답해줘", "strong 태그 써줘" 같은 규칙을 반복해서 입력하면 매 턴마다 수백 토큰이 낭비됩니다. 규칙을 AGENTS.md에 30줄 이내로 간결하고 명확하게 고정해 두면, 중복 지시를 완전히 생략할 수 있어 무료 모델의 제한된 컨텍스트 윈도우와 일일 할당량을 극대화할 수 있습니다.

필자의 블로그 저장소에는 아래 5대 규칙이 AGENTS.md에 고정되어 있습니다. 무료 모델은 유료 플래그십보다 지시 추종력이 약할 수 있으므로, 규칙을 짧고 명시적으로 적는 것이 오히려 유리합니다.

1. 한국어 마크다운 볼딩은 별표 2개 대신 strong 태그 사용
2. 본문 물결표는 반드시 ~로 이스케이프 (예: 15~20개, 수일~4주)
3. 빌드 타임 자동 변환 스크립트 유지
4. LaTeX 수식 금지, 유니코드 기호(×, ÷, ➔) 사용
5. SEO 제목은 최대 44자, 권장 32~42자

초기화 직후 /init이 만든 파일을 한 번 눈으로 검수하고, 모호한 문장은 직접 다듬어 주세요. 이 10분의 손질이 이후 수십 번의 무료 호출 품질을 좌우합니다.

---

🚀 6. 실전 활용법 5가지: 블로그 글쓰기로 배우는 패턴

무료 모델을 마구잡이로 질문하는 용도로 쓰면 금방 한계에 부딪힙니다. 아래 5가지 패턴으로 쓰면 체감 품질이 달라집니다.

6-1. 질문하기: 코드베이스 해설사로 쓰기

처음 보는 저장소에서는 파일 기호(@)로 문맥을 좁혀서 묻습니다.

@packages/functions/src/api/index.ts 파일에서 인증 흐름이 어떻게 처리돼?
관련 함수와 호출 순서를 5줄로 요약해줘.

이미지를 터미널에 드래그 앤 드롭해서 함께 넘기면, 스크린샷 기반 질문도 됩니다.

6-2. 플랜 모드로 큰 작업 쪼개기

Tab 키를 누르면 플랜 모드와 빌드 모드가 전환됩니다. 플랜 모드에서는 변경 없이 구현 방법만 제안합니다.

방문자가 노트를 삭제하면 DB에서 삭제 플래그만 세우고,
최근 삭제 노트 화면에서 복구/영구 삭제를 고르게 하고 싶어.
먼저 플랜만 짜줘.

플랜이 나오면 피드백을 주고, 확신이 설 때 다시 Tab을 눌러 빌드 모드로 바꿉니다.

좋아, 그 플랜대로 변경해줘.

6-3. 작은 변경은 바로 지시하기

명확한 작업은 플랜 없이 한 번에 지시하는 것이 토큰을 아낍니다.

/settings 라우트에 인증을 추가해줘.
@packages/functions/src/notes.ts의 방식을 참고해서
@packages/functions/src/settings.ts에 같은 로직으로 구현해줘.

마음에 안 들면 되돌리기는 아래 명령으로 해결됩니다.

/undo

/redo

6-4. TUI 내부 쉘 명령어 즉시 실행 (!)

TUI를 종료하거나 별도의 터미널 분할 창으로 이동할 필요 없이, 입력창 맨 앞에 느낌표(!)를 붙이면 쉘 명령어를 즉시 실행하고 결과를 바로 확인할 수 있습니다.

!git status
!npm run build
!git diff

6-5. 리더 키(Leader Key, Ctrl+X)와 필수 단축키

OpenCode는 일반 텍스트 입력과의 충돌을 방지하기 위해 Ctrl+X 리더 키 체계를 채택하고 있습니다. Ctrl+X를 먼저 누른 뒤 아래 키를 순차적으로 누르면 핵심 기능이 즉시 발동합니다:

• Ctrl+X ➔ c (/compact): 무료 티어 사용 시 필수 단축키입니다. 긴 대화로 토큰이 누적되었을 때 이전 대화의 노이즈를 지능적으로 요약 압축하여 컨텍스트 윈도우 한도 초과를 방지합니다.
• Ctrl+X ➔ e (/editor): 기본 터미널 입력창이 좁을 때, 환경변수에 지정된 외부 텍스트 에디터($EDITOR)를 열어 장문의 프롬프트를 편하게 작성합니다.
• Tab: Plan(기획 전용) 모드와 Build(실제 코드 수정) 모드 상호 전환

6-6. 블로그 글쓰기: 무료 모델로 초안 뽑는 루틴

필자가 이 블로그에서 쓰는 방식입니다. 유료 결제 없이도 아래 흐름이면 1차 초안이 나옵니다.

1. 개요 먼저 강제: 제목 37자 내외, H2 5~6개 목차부터 받기
2. 표와 코드 강제: 비교표 2개, 코드블록 3개 이상 포함 조건 걸기
3. 규칙 주입: strong 태그, 물결 이스케이프, LaTeX 금지, 44자 제한을 프롬프트에 매번 명시
4. 인간 검수: 가격, 버전, 명령어는 공식 문서 대조 후 발행

주제: OpenCode 무료 설치와 Muse Spark 설정법
조건:
- 제목 37자 내외, H2 5개
- 비교표 2개, bash 코드블록 3개
- 볼딩은 strong 태그만, 물결은 \~로 이스케이프
- LaTeX 금지, × ÷ ➔ 유니코드 사용
먼저 목차만 짜줘.

6-7. 대화 공유로 협업하기

팀원과 결과를 공유할 때는 대화 링크를 만듭니다.

/share

기본적으로 비공개이며, 명령 실행 시에만 링크가 생성되고 클립보드에 복사됩니다.

---

🛡️ 7. 무료로 오래 쓰는 5가지 절약 팁

무료라고 무제한이 아닙니다. 한시 제공 중단에 대비한 완충 전략이 필요합니다.

1. 월간 한도와 자동충전 점검: Zen 워크스페이스에서 월간 사용 한도를 0~5달러로 낮추고, 자동충전(auto-reload)은 꺼둡니다. 잔액 5달러 이하에서 20달러 자동충전이 되는 기본값을 그대로 두면 의도치 않은 결제가 생깁니다.
2. 무거운 작업은 플랜 모드에서 다듬기: 플랜을 확정하기 전에는 파일 수정을 허용하지 마세요. 오출력 후 재시도가 토큰을 가장 많이 먹습니다.
3. 주기적인 /compact 컨텍스트 압축: 세션이 길어지면 이전 턴의 디버깅 로그와 파일 내용이 고스란히 컨텍스트 비용으로 누적됩니다. 작업 주제가 바뀔 때마다 /compact를 실행하세요.
4. 모델 로테이션 준비: Muse Spark 무료판이 혼잡하면 Space Bunny Free, MiMo-V2.6-Flash Free, Ling 3.1 Flash Free로 즉시 전환할 수 있게 /models 단축 선택에 익숙해집니다.
5. 민감정보 분리: Contributor Free 조건상 프롬프트가 학습에 활용될 수 있으므로, 실제 서비스 API 키, 고객 DB 개인정보, 사내 비공개 알고리즘은 입력하지 마세요. 사내 코드는 로컬 LLM(mlx-serve, Ollama)이나 BYOK 유료 키로 철저히 분리해야 합니다.

필요 커넥션 수 = RPS × 처리 시간

위 공식처럼, 무료 사용도 호출 빈도 × 작업 크기가 핵심입니다. 한 번에 거대한 작업을 던지는 대신, 목차 ➔ 본문 ➔ 검수처럼 3단계로 나누면 실패 시 재시도 비용이 1/3로 줄어듭니다.

---

⚠️ 8. 시작 전 체크리스트와 흔한 오류

설치가 꼬였을 때는 공식 문제해결(troubleshooting) 문서와 GitHub 이슈를 먼저 확인하는 것이 빠릅니다.

---

🎯 9. 총평: 무료가 주는 가장 큰 선물은 습관이다

유료 모델이 매달 결과가 보장되는 헬스장이라면, 무료 모델은 집 앞 공원입니다. 기구는 단순하지만, 매일 나가서 쓰는 사람이 결국 체력을 얻습니다.

필자 기준으로 Muse Spark 1.3 Contributor Free는 설치 가이드, 트러블슈팅 초안, 블로그 목차와 표 만들기에서 유료 대비 손색이 없었습니다. 대신 아래 3가지는 인간이 맡아야 했습니다.

• 팩트 체크: 버전 번호, 가격, 명령어는 공식 문서 대조
• 톤 조정: 블로그 특유의 말투와 경험담 삽입
• 최종 책임: 발행 버튼은 항상 인간이 누르기

결제 없이 시작하고 싶다면, 오늘 프로젝트 폴더 하나에서 opencode 한 줄로 시작해 보세요. 5분 설치와 10분 AGENTS.md 손질이, 다음 달 카드 명세서에서 20달러를 지워줄 것입니다.

---

🔗 연관 아티클 & 공식 링크 바로가기

• OpenCode 공식 문서: OpenCode Intro - 설치부터 초기화까지 (공식 ↗)
• OpenCode Zen 모델·가격표: Zen - Muse Spark 무료 티어 확인 (공식 ↗)
• 관련 글: Gemini CLI 설치 가이드: macOS 및 Windows 환경별 설정법 (↗)
• 관련 글: Mac에서 가장 빠른 로컬 AI 서버, mlx-serve 완전 정복 (↗)