무료 LLM API로 OpenCode 사용하기
OpenCode는 터미널과 데스크톱용 오픈 소스 코딩 에이전트입니다. 모든 OpenAI 호환 제공업체를 받아들입니다. 이 가이드는 OpenCode를 FreeLLMAPI를 통한 무료 모델에 연결합니다. 명령 하나로 설정을 쓰고 키를 저장합니다.
코드, 모델 이름, 실시간 카탈로그 레이블은 영어로 표시합니다.
1단계: FreeLLMAPI 설치
FreeLLMAPI는 오픈 소스 게이트웨이입니다. 사용자 컴퓨터에서 Docker로 실행되며, 45개 제공업체의 무료 요금제를 하나의 키 뒤에 묶습니다.
macOS 또는 Linux에 설치
curl -fsSL https://freellmapi.co/install.sh | bashhttp://localhost:3001을 여세요. Keys 페이지에서 무료 제공업체 키를 두 개 이상 추가하세요. Google AI Studio와 Groq는 각각 몇 분 안에 무료 키를 제공합니다. 같은 페이지에서 통합 키를 복사하세요.
2단계: 명령 하나로 OpenCode 연결하기
명령 한 줄
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key> --dry-run
npx freellmapi setup-opencode --url http://localhost:3001 --api-key <unified-key>
opencode이 명령은 세 가지 작업을 합니다.
freellmapi제공업체를~/.config/opencode/opencode.json에 추가합니다. 이 제공업체는 실시간 카탈로그의 모델을 컨텍스트 한도와 함께 나열합니다.- 기본 모델을
freellmapi/auto로 설정합니다. - 키를 OpenCode 자격 증명 파일
~/.local/share/opencode/auth.json에 저장합니다. CLI와 데스크톱 앱 모두에서 환경 변수가 필요하지 않습니다.
명령은 쓰기 전에 백업을 만듭니다. 새 제공업체를 기존 설정에 병합하므로 다른 제공업체는 유지됩니다. XDG_CONFIG_HOME 또는 XDG_DATA_HOME이 설정되어 있으면, 명령은 그 폴더를 사용합니다.
긴 작업을 시작하기 전에, 게이트웨이가 지금 요청을 처리할 수 있는지 확인하세요. 이 호출은 지금 사용 가능한 키가 있는 모델만 나열합니다.
준비된 모델 확인
curl "http://localhost:3001/v1/models?execution_status=ready" \
-H "Authorization: Bearer <unified-key>"상태가 exhausted인 모델은 키가 있지만, 모든 키가 지금 한도에 도달한 상태입니다. 이 상태는 쿨다운이 끝나면 해제됩니다. 클라이언트의 요청이 게이트웨이에 도달하는지 확인하려면 npx freellmapi doctor를 실행하세요. 대시보드 요청 로그에는 OpenCode의 각 호출이 표시됩니다. X-Routed-Via 응답 헤더는 각 요청에 답변한 제공업체와 모델을 보여 줍니다. 요청이 장애 대응으로 넘어갔다면, X-Fallback-Trail 헤더가 실패한 각 단계와 이유를 보여 줍니다.
수동 설정: opencode.json 제공업체 블록
수동으로 설정하려면 이 블록을 ~/.config/opencode/opencode.json에 추가하거나, 프로젝트의 opencode.json에 추가하세요. OpenCode는 @ai-sdk/openai-compatible을 /v1/chat/completions 엔드포인트에 사용합니다.
opencode.json
{
"$schema": "https://opencode.ai/config.json",
"model": "freellmapi/auto",
"provider": {
"freellmapi": {
"npm": "@ai-sdk/openai-compatible",
"name": "FreeLLMAPI",
"options": {
"baseURL": "http://localhost:3001/v1"
},
"models": {
"auto": {
"name": "Auto",
"limit": { "context": 128000, "output": 8192 }
}
}
}
}
}그런 다음 키를 추가하세요. OpenCode를 시작하고, /connect를 실행한 다음, freellmapi 제공업체를 선택하고 통합 키를 붙여 넣으세요. /connect의 제공업체 ID는 설정의 ID와 일치해야 합니다. /models를 실행하여 모델을 선택하세요.
limit.context는 모델의 최대 입력 토큰 수입니다.limit.output은 모델이 생성할 수 있는 최대 토큰 수입니다.- 최상위
model은provider/model형식을 씁니다. 이 값이 없으면 OpenCode는 이전에 사용하던 모델을 유지합니다. - 사용하려는 모든 모델 ID는
models맵에 있어야 합니다.GET /v1/models에서 ID를 더 추가하세요.
providers 키를 쓰는 V2 설정 형식을 설명합니다. 문서에 따르면 위의 V1 형식도 여전히 지원됩니다. FreeLLMAPI 설정 명령은 V1 형식을 씁니다.OpenCode에 맞는 모델 고르기
OpenCode는 에이전트입니다. 도구 호출을 통해 파일을 읽고, 편집하고, 명령을 실행합니다. 각 요청에는 시스템 프롬프트, 도구 정의, 파일 내용이 들어 있습니다. 도구 호출을 지원하고 컨텍스트 창이 큰 모델을 사용하세요.
| 모델 | 무료 제공 | 컨텍스트 | 무료 한도 (가장 좋은 조건) | 도구 | 비전 |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 요청/분 1 req/min per model | 예 | 아니요 |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 요청/분 40 RPM | 예 | 예 |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | 예 | 예 |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | 예 | 아니요 |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | 예 | 예 |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 요청/분 20 요청/일 250,000 토큰/분 ~3M | 예 | 예 |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | 예 | 예 |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 요청/분 50 요청/일 50 req/day account-wide (1,000 after a $10 purchase) | 예 | 예 |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 요청/분 50 요청/일 Shared rate limit | 예 | 아니요 |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 요청/분 250 요청/일 70,000 토큰/분 ~6M | 예 | 예 |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 요청/분 20 요청/일 250,000 토큰/분 ~3M | 예 | 예 |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | 예 | 예 |
일치하는 무료 모델 109개 중 12개를 표시합니다. 모든 모델 보기.
FreeLLMAPI 카탈로그의 실시간 데이터입니다 (버전 2026.11.19, 2026-11-19 확인). 무료 한도는 자주 바뀝니다. 카탈로그는 매일 확인합니다.
freellmapi/auto를 쓰면 라우터가 요청마다 모델을 선택합니다. auto:smart와 auto:fast를 models 맵에 추가하면 지능 또는 속도 기준으로 요청을 조정할 수 있습니다. 대시보드에서 이름 있는 프로필(예: auto:coding)을 만든 후에는 그 프로필도 추가할 수 있습니다.
요청 한도와 긴 세션
에이전트 작업 하나는 수십 개의 요청을 보낼 수 있습니다. 무료 요금제 하나만으로는 긴 작업이 빨리 멈춥니다. FreeLLMAPI는 각 키의 요청 수와 토큰 수를 셉니다. 제공업체가 429 오류를 보내면, 라우터는 요청을 체인의 다음 모델로 보내고 세션은 계속됩니다.
- 제공업체 4개 이상의 키를 추가하세요. 제공업체가 많을수록 하루 요청 수가 늘어납니다.
FREELLMAPI_CONTEXT_HANDOFF=on_model_switch를 FreeLLMAPI.env에서 설정하여 컨텍스트 전달을 켜세요. 모델이 바뀌면 다음 모델은 작업을 이어받는다는 짧은 메모를 받습니다.- 고정 세션은 대화를 30분 동안 한 모델에 유지합니다. 이렇게 하면 에이전트의 동작이 일관됩니다.
- 작업마다 새 세션을 시작하세요. 컨텍스트가 작을수록 요청당 토큰을 적게 씁니다.
문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 키가 올바른데도 "Invalid API key" | 설정의 빈 apiKey가 /connect의 키를 덮어씀 | apiKey를 options에서 삭제하거나, setup-opencode를 다시 실행하세요 |
| OpenCode가 새 제공업체를 사용하지 않음 | 최상위 model이 설정되지 않음 | "model": "freellmapi/auto"로 설정하세요 |
| 모델을 찾을 수 없음 | 모델 ID가 제공업체의 models 맵에 없음 | 맵에 ID를 추가하거나, setup-opencode를 다시 실행하세요 |
{env:VAR} 키가 비어 있음 | OpenCode는 설정되지 않은 변수를 빈 문자열로 바꿈 | 같은 셸에서 변수를 내보내거나, /connect로 키를 저장하세요 |
| 도구 호출이 실패함 | 모델의 도구 호출 지원이 약함 | 위 표에서 모델을 고르세요 |
| "N번 시도 후 모든 모델이 요청 한도에 걸림" | 모든 키가 한도에 도달함 | 더 많은 제공업체의 키를 추가하거나 쿨다운이 끝날 때까지 기다리세요 |
자주 묻는 질문
OpenCode를 무료로 쓸 수 있나요?
예. OpenCode는 오픈 소스입니다. OpenAI 호환 제공업체로 FreeLLMAPI에 연결하세요. 게이트웨이는 각 요청을 무료 제공업체 요금제로 보내므로, 추론 비용은 $0입니다.
OpenCode에 사용자 지정 OpenAI 호환 제공업체를 어떻게 추가하나요?
opencode.json에 npm을 @ai-sdk/openai-compatible로 설정한 제공업체, options.baseURL, models 맵을 추가하세요. 그런 다음 /connect를 실행하여 키를 저장하고, /models를 실행하여 모델을 선택하세요.
OpenCode에 가장 좋은 무료 모델은 무엇인가요?
도구 호출을 지원하고 컨텍스트가 최소 128K인 모델을 쓰세요. 이 페이지의 표는 오늘 두 조건을 모두 충족하는 가장 성능 좋은 무료 모델을 보여 줍니다. freellmapi/auto를 쓰면 라우터가 모델을 선택합니다.
OpenCode는 API 키를 어디에 저장하나요?
/connect로 추가한 키는 ~/.local/share/opencode/auth.json에 저장됩니다. FreeLLMAPI 설정 명령도 키를 그곳에 쓰므로, CLI와 데스크톱 앱이 모두 키를 찾습니다.
관련 가이드
- 무료 LLM API로 Aider 사용하기
- 무료 모델로 Codex CLI 사용하기
- Claude Code를 무료로 사용하는 방법
- 최고의 무료 코딩 모델 API
- 무료 OpenAI 호환 API Base URL
출처
- OpenCode docs: providers (V1 config) (20 November 2026 확인)
- OpenCode docs: config (20 November 2026 확인)
- OpenCode docs: migrate from V1 (20 November 2026 확인)
- FreeLLMAPI CLI generators (20 November 2026 확인)
- FreeLLMAPI docs: context handoff (20 November 2026 확인)