# OpenCode 무료 활용

OpenCode와 무료 모델을 활용한 비용 없는 에이전틱 코딩 실습 환경을 구성합니다.

원본 URL: https://abc.noco.kr/practice/opencode-free

[OpenCode](/glossary#opencode)는 무료 모델을 목록에 함께 담고 있어서, 요금제 없이도 에이전틱 코딩을 처음부터 끝까지 해 볼 수 있다. 모델을 고르는 기준, 무료로 써도 되는 범위, 수업과 연결하는 방법을 정리한다.

기준일: 2026-09-30. 무료 모델의 목록과 조건은 자주 바뀌므로 아래 값은 예시로 읽는다.

## 무료 모델의 범위

OpenCode 안에는 [OpenCode Zen](/glossary#opencode-zen)에서 제공하는 무료 모델이 들어 있다. 직접 써 보면 별도 가입 없이 바로 대화하고 파일을 고치는 데까지 쓸 수 있다. 런타임의 기능(파일 읽기·편집, 셸 실행, 룰·스킬 읽기)은 모델과 별개이므로, 무료 모델로도 [룰](/glossary#rules)과 [스킬](/glossary#skills)이 있는 저장소를 그대로 다룰 수 있다.

이 목록에는 [Space Bunny](/glossary#space-bunny)처럼 원래 모델 이름을 숨긴 채 제공되는 [스텔스 모델](/glossary#stealth-model)도 포함된다. 스텔스 모델은 유료 풀과 독립된 별도 한도로 제공되므로 토큰과 비용을 아끼는 데 유용하다. 구체적인 활용 전략과 주의점은 [무료 스텔스 모델 활용](/practice/token-saving#stealth-model)을 참고한다.

-  비용이 들지 않으니 시행착오를 부담 없이 반복할 수 있다.
-  명령·프롬프트·룰 작성 연습처럼 결과가 틀려도 잃을 것이 없는 일에 알맞다.
-  상위 모델보다 결과가 흔들릴 수 있다. 중요한 결과는 다른 모델이 다시 검토한다.

```bash
opencode models                  # 지금 쓸 수 있는 모델 목록. 무료 모델은 이름이 -free로 끝난다
opencode run -m opencode/space-bunny-free "README.md를 읽고 세 줄로 요약해줘"
```

`-m`에는 `제공자/모델` 형식을 쓴다. 대화형 화면(TUI)에서는 `/models`로 목록을 열어 고르고, 자주 쓰는 모델은 설정 파일에 기본값으로 둔다.

```json
{ "model": "opencode/space-bunny-free" }
```

::: details 보충: 설치와 연결
기준일: 2026-09-30. macOS·Linux에서는 `brew install opencode`로 설치할 수 있다. 설치 방법은 [OpenCode 공식 문서](https://opencode.ai/docs/)에 정리돼 있다.

유료 제공자나 Zen 계정을 연결할 때는 TUI에서 `/connect`를 실행하고 안내에 따라 API 키를 붙여 넣는다. 키는 저장소나 수업 자료에 옮기지 않는다. 설정 파일의 위치와 `model` 키는 [모델 설정 문서](https://opencode.ai/docs/models/)를 따른다.
:::

## 사용량 기반 모델 선택

무료 모델은 종류가 많고 금방 바뀐다. 무엇부터 써 볼지는 [OpenRouter](/glossary#openrouter)의 사용량을 보고 정한다. OpenRouter [순위 페이지](https://openrouter.ai/rankings)는 실제로 처리된 토큰 양을 기준으로 많이 쓰이는 모델을 보여 준다. 코딩 같은 용도별 순위도 함께 볼 수 있다.

```mermaid
flowchart LR
  A[OpenRouter 사용량 순위에서 후보 확인] --> B["opencode models로 실제 사용 가능 여부 확인"]
  B --> C[작은 과제로 시험]
  C --> D{쓸 만한가}
  D -- 예 --> E[기본 모델로 지정]
  D -- 아니오 --> A
```

1. 순위에서 요즘 많이 쓰이는 모델을 후보로 뽑는다.
2. `opencode models`에서 그 모델(또는 같은 계열의 무료 모델)이 실제로 나오는지 본다.
3. 파일 하나를 요약하거나 함수 하나를 고치는 작은 과제로 시험한다.
4. 결과가 안정적이면 기본 모델로 지정하고, 아니면 다음 후보로 넘어간다.

참고: 사용량이 많다는 것은 널리 쓰인다는 뜻이지 내 작업에 잘 맞는다는 보증이 아니다. 후보를 좁히는 데만 쓰고, 최종 선택은 직접 시험한 결과로 한다.

## 무료 모델로 해 볼 연습

처음에는 결과가 틀려도 되는 작은 일부터 시킨다. 아래 프롬프트는 연습용 저장소에서 그대로 붙여 넣어 볼 수 있다.

```text
이 저장소의 구조를 파일 단위로 훑어보고, 처음 온 사람에게 필요한 순서로 세 줄 요약해줘.
```

```text
README.md의 설치 절차를 그대로 따라 했을 때 막힐 만한 곳을 찾아서 목록으로 알려줘. 파일은 고치지 마.
```

```text
AGENTS.md를 10줄 이내로 새로 써줘. 빌드 명령, 금지사항만 넣고 나머지는 스킬로 빼도 된다고 표시해줘.
```

- 첫 번째는 읽기만 하는 일이라 가장 안전하다. 모델이 파일을 잘 찾는지 감을 잡는다.
- 두 번째는 "고치지 마"처럼 하지 않을 일을 적는 연습이다. 범위를 좁힐수록 무료 모델도 덜 흔들린다.
- 세 번째는 [룰](/glossary#rules)을 직접 써 보는 연습이다. 결과가 마음에 들지 않으면 같은 세션에서 고쳐 달라고 이어 간다.

## 유료 모델로 넘어가는 시점

무료 모델이 잘 못 하는 일을 억지로 시키지 않는다. 다음 신호가 반복되면 다른 모델이나 요금제를 생각한다.

| 신호 | 대응 |
|---|---|
| 같은 지시를 세 번 고쳐도 결과가 어긋난다 | 지시를 더 잘게 나눈다. 그래도 안 되면 다른 모델에 같은 과제를 시켜 비교한다 |
| 파일이 커질수록 앞부분과 다른 내용이 나온다 | [모듈을 작게 나눠](/practice/token-saving) 한 번에 읽는 양을 줄인다 |
| 개인·기업 정보를 다뤄야 한다 | 무료 모델을 쓰지 않고, 데이터 처리 조건을 확인한 유료 모델이나 계정을 쓴다 |
| 결과를 검토할 사람이 없다 | 다른 모델을 Reviewer로 두는 구성을 고려한다. [herdr 오케스트레이션](/practice/herdr) 참고 |

## 개인·기업 정보 금지

무료 모델은 학습 용도로만 쓴다. 무료 기간에는 입력한 내용이 모델 개선에 쓰이거나 기록될 수 있기 때문이다. 조건은 모델마다 다르다.

| 넣어도 되는 것 | 넣으면 안 되는 것 |
|---|---|
| 연습용으로 만든 예제 저장소 | 회사 코드·내부 문서 |
| 공개된 문서와 오픈소스 코드 | 고객·수강생 개인정보 |
| 가짜 데이터, 샘플 CSV | API 키, 토큰, `.env` |

::: details 보충: 무료 모델의 데이터 조건
기준일: 2026-09-30. [OpenCode Zen 문서의 개인정보 항목](https://opencode.ai/docs/zen/)에는 모델별 조건이 나온다. 일부 무료 모델은 무료 기간 동안 수집한 데이터를 모델 개선에 쓸 수 있다고 밝힌다. NVIDIA 무료 엔드포인트를 쓰는 모델은 체험 용도이므로 개인·기밀 데이터를 넣지 말라고 안내한다. 이 밖에도 모델마다 조건이 다르니, 쓸 모델의 항목을 그때그때 확인한다.

OpenCode는 기본 권한 설정에서 `.env` 파일 읽기를 막는다. 다만 이것이 모든 민감 정보를 지켜 준다는 뜻은 아니다. 권한 규칙의 세부는 [OpenCode 권한 문서](https://opencode.ai/docs/permissions)와 [세팅: 권한과 화면 요소](/harness-basics/settings)에서 다룬다.
:::

## 수업에 연결하기

무료 모델은 수강생이 부담 없이 시작하는 경로로 쓴다. 각자 가입해 개인 키와 한도를 직접 관리하는 원칙은 [API 제공자](/concepts/api-provider)와 같다.

```mermaid
flowchart LR
  P["사전 연습<br/>무료 모델로 설치·명령·룰 연습"] --> C["수업<br/>각자의 계정과 한도로 실습"]
  C --> A["사후 활용<br/>무료 모델로 계속 반복"]
```

- 사전 연습: 수업 전에 OpenCode를 설치하고 무료 모델로 프롬프트와 룰 작성을 미리 해 본다. 수업 시간을 설치와 환경 문제에 쓰지 않아도 된다.
- 사후 활용: 수업이 끝난 뒤에도 비용 없이 계속 써 볼 수 있다.
- 수업에서 요금제를 제공한다면, 그 요금제도 사전 연습이나 사후 활용 쪽으로 잡는다. 수업에 쓸 요금제와 무료 모델의 역할을 겹치지 않게 나누는 셈이다. 요금제 조합은 [요금제](/concepts/pricing)를 참고한다.

## 이 저장소에서 쓰는 방식

이 자료집을 만드는 저장소에서는 무료 모델 하나를 Worker로 두고 원고와 테마 작업을 맡긴다. 무료 모델이라 결과를 그대로 받지 않고, 반드시 다른 모델이 검토한다. 월 한도가 있는 유료 풀([OpenCode Go](/glossary#opencode-go))의 모델은 잔량을 보고 번갈아 배정한다. 역할을 나누는 방법은 [herdr 오케스트레이션](/practice/herdr)에서 다룬다.

무료 Worker에게 보내는 지시는 짧고 범위가 분명해야 한다.

```text
docs/plan.md의 '작업 카드'에서 K2를 맡아라.
- 고칠 파일: docs/cases/ 아래 지정된 두 파일만
- 참고: plan.md의 해당 카드와 writing 스킬
- 완료 조건: pnpm docs:build 통과, 해당 파일만 커밋
- 끝나면 커밋 해시와 바꾼 소제목만 보고
```

 무료 모델에는 지시를 짧게 쓰고, 완료 조건에 빌드 통과 같은 확인 가능한 기준을 넣는다. 결과는 검토 모델이 파일을 직접 열어 확인한다.