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

⚠️ 업데이트 (2026-10-17): 이 글에서 소개한 Muse Spark 1.3 Contributor Free 무료 모델은 현재 사용할 수 없습니다(실측 시 Model unavailable 반환, 무료 엔드포인트 종료·유료 모델만 잔존). 설치·설정 방법 자체는 그대로 유효하지만, 무료로 이어가려면 모델을 교체해야 합니다. 현재 무료 모델 9종과 유료 전환 비용은 OpenCode Muse Spark 1.3 무료 종료: 과금 함정과 대안에서 정리했습니다.

💸 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 모델 학습에 활용될 수 있다는 점을 공식 문서에 명시하고 있습니다.

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

---

🧩 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 완전 정복 (↗)